# Workshop runs and session budget

Opening and closing a workshop run under `work/`, and inspecting the per-session call budget.

<!-- wikitool:toc -->
## Contents

- [`work new`](#work-new)
- [`work close`](#work-close)
- [`budget status`](#budget-status)
- [`budget reset`](#budget-reset)
<!-- /wikitool:toc -->

<!-- wikitool:reference-commands -->
## `work new`

Scaffold `work/<runkey>/` for one workshop run.

**Synopsis**

- `wikitool work new (--input <raw path> | --key <run key>) [--again] [--dry-run]`

**Options**

```text
  --input <str>  Path to the raw source tree or file this run covers, e.g.
                 raw/documents/handbook
  --key <str>    Explicit run key for a run with no raw input (a migration, a
                 sweep across kb/). Mutually exclusive with --input; may not
                 start with 'ingest-'.
  --again        This is a deliberate re-ingest of a tree already processed
                 before: append today's date to the run key instead of refusing
                 the collision.
  --dry-run      Show what would be created, write nothing
  -h, --help     Show this message and exit.
```

**Examples**

```bash
tools/wikitool work new --input raw/2026/09/handbuch
tools/wikitool work new --key migrate-7.0.0
tools/wikitool work new --input raw/2026/09/handbuch --again
```

**Behaviour**

- Creates `work/<runkey>/` with the required `README.md` and `plan.md`.
- `--input` derives the run key from the path below `raw/` (an ingest); `--key` names it outright for a run with no raw input - a migration or a sweep across `kb/` - and may not start with `ingest-`, which stays reserved for derived keys. Exactly one of the two.
- Refuses a collision instead of suffixing it.
- `--again` opens a dated second pass (`<runkey>-<date>`) over a tree that has itself changed.
- `--dry-run` reports the run key and files without writing.

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: Yes - one directory with two files
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - Neither or both of `--input`/`--key` given, or a `--key` that is empty or starts with `ingest-`
- `1` - `--input` is outside `raw/`, does not exist, or is `raw/` itself (an empty run key)
- `1` - The workshop already exists

**See also**

- `work/CONTRACT.md` - run keys, required files, how a run closes
- `wikitool work close` - deletes the run when it is done
- `instructions/ingest-large-tree.md` - the ingest that opens a run

## `work close`

Delete a finished workshop.

**Synopsis**

- `wikitool work close --run-key <name> [--yes] [--dry-run]`

**Options**

```text
  --run-key <str>  The workshop directory name  [required]
  -y, --yes        Confirm deletion. Required: closing discards the only copy of
                   the run's working notes, so the durable conclusions must
                   already be in kb/.
  --dry-run        Show what would be deleted, delete nothing
  -h, --help       Show this message and exit.
```

**Examples**

```bash
tools/wikitool work close --run-key ingest-2026-09-handbuch --dry-run
tools/wikitool work close --run-key ingest-2026-09-handbuch --yes
```

**Behaviour**

- Deletes `work/<run-key>/` recursively.
- Without `--yes` it lists what would be lost and refuses: nothing in a workshop is recoverable from the rest of the repo, so the durable conclusions must already be in `kb/`.
- `--dry-run` lists the files without deleting.
- Not idempotent: once deleted, the run key is unknown.

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: No - a recursive delete
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - Unknown run key
- `1` - `--yes` was not passed - the output lists what would be lost

**See also**

- `work/CONTRACT.md` - how a run closes
- `wikitool work new` - opens a run

## `budget status`

Show the current session's `wikitool` call count and recent command history.

**Synopsis**

- `wikitool budget status`

**Options**

```text
  -h, --help  Show this message and exit.
```

**Examples**

```bash
tools/wikitool budget status
```

**Behaviour**

- Shows the current session's `wikitool` call count and its recent command history.
- Never counted against the budget; never fails; safe to retry freely.

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only
- Counts toward the session call budget: no
- Can reach the network: no

**Exit codes**

- `0` - success

**See also**

- `instructions/session-setup.md` - scoping the budget to a task
- `instructions/gates.md` - what to do when the Iteration Budget Gate refuses

## `budget reset`

Clear the current session's (or every session's) iteration budget state.

**Synopsis**

- `wikitool budget reset --yes [--all]`

**Options**

```text
  --all       Clear every session's budget, not just the current one.
  -y, --yes   Confirm clearing the budget. Only pass this after a human has
              approved continuing the session - never set it automatically to
              work around the gate.
  -h, --help  Show this message and exit.
```

**Examples**

```bash
tools/wikitool budget reset --yes    # only after the user approved it
```

**Behaviour**

- Clears the current session's iteration budget state; `--all` deletes every session's.
- Requires `--yes`: clearing the counter is itself a way around the Iteration Budget Gate, so it needs the same explicit human approval.
- Counted against the budget like any other call.

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: Read/rewrite of one JSON file (or its deletion, with `--all`)
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - `--yes` not passed

**See also**

- `wikitool budget status` - the current count
- `instructions/gates.md` - why `budget reset` is not the escape hatch
<!-- /wikitool:reference-commands -->