Table of Contents

Workshop runs and session budget

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/reference/commands/workshop-runs-and-session-budget.md at v10.1.0 – edit the repository, not this wiki.

Workshop runs and session budget

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

`work new`

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

Synopsis

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

Options

  --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

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

  --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

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

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

Examples

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

  --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

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