chemenu/docs/reference/commands/workshop-runs-and-session-budget.md

Workshop runs and session budget

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

Contents

• work new
• work close
• budget status
• budget reset

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