feat: docs reference generates a human command reference under docs/reference/ from the command records, one page per group plus exit codes and gates; toc never lands inside another generated region (#188)
Files changed: - CHANGES.md - README.md - VERSION - docs/reference/README.md - docs/reference/commands/README.md - docs/reference/commands/catalog-and-log.md - docs/reference/commands/content-migrations.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/guideline-export.md - docs/reference/commands/instance-health.md - docs/reference/commands/links-and-citations.md - docs/reference/commands/pages.md - docs/reference/commands/provenance.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/commands/workshop-runs-and-session-budget.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/test_reference_doc.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
01c888d3cd
commit
53383e7e9b
29 files changed
+5079
-29
No files matched your search
@@ -0,0 +1,216 @@
|
||||
# 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 -->
|
||||
Reference in new issue
Block a user