tools: command records, Raw material and uploads group - one line per cause, examples, prohibitions (#142)

Files changed:
- CHANGES.md
- VERSION
- tools/CONTRACT.md
- tools/chemenu/commands/raw_cmd.py
- tools/chemenu/commands/upload_cmd.py

tools/CONTRACT.md

@@ -1357,8 +1357,8 @@ Promote one or more files from `incoming/` into `raw/`.
 
 **SYNOPSIS**
 
-- `wikitool raw accept <file> [<file> ...] --fidelity <v> --authority <v> [--page "<Title>"] [--dry-run]` - Promote one or more files from `incoming/` into `raw/<YYYY>/<MM>/`, computed from the accept date rather than chosen by hand (`raw/CONTRACT.md` "Getting a file in"): a subdirectory under `incoming/` is tolerated and ignored, not inspected - `raw/` no longer addresses by type. One file promoted alone lands with no directory of its own; several files in one call nest under `raw/<YYYY>/<MM>/<stem>/`, named after the first file's stem. `--fidelity`/`--authority` are required here (see `types describe source`; `unknown` is refused, backfill-only) - the one moment both are knowable. `--page "<Title>"` additionally extends that existing source page's `raw_files:` in the same call and writes both capture fields onto it (refused if it already carries a different value - a capture field is fixed once); if that raises the page past one file, its already-promoted file is folded into a bundle at *its own* parent directory, not today's shard, so a bundle never mixes an old and a new capture date, after checking it has no other owner (`provenance.duplicate_raw_file_owners`). The set of names occupied anywhere under `raw/` - file stems and bundle directory names alike, old type directories and date shards together - must stay unique: a promote whose target name already belongs to something this call does not itself own is refused, naming both `--replaces` and renaming-in-`incoming/` without recommending either
-- `wikitool raw accept <file> --replaces <raw-path> [--fidelity <v>] [--authority <v>] [--dry-run]` - The one sanctioned way past that uniqueness rule, and the one sanctioned way to correct an already-set capture field: overwrites `<raw-path>` in place with the single incoming file (same filename required; there is no type directory left to match), leaving every page's `raw_files:` untouched and writing no `kb/` page - the previous edition survives only in `git log --follow <raw-path>`. `--fidelity`/`--authority` are optional here, and passing one overwrites the owning page's already-set value - the one path fill-once does not block, because a corrected capture is a new edition of the source, not an edit of the page describing it. Refuses if the target has more than one owning source page; if it has none, replaces anyway and says so. Cannot be combined with `--page` or with more than one incoming file - a replacement is one file for one file. Prints the source page (if any) and its citing pages, so their update lands in the same commit as the replacement
+- `wikitool raw accept <file> [<file> ...] --fidelity <v> --authority <v> [--page "<Title>"] [--dry-run]` - Promote one or more files from `incoming/` into today's `raw/<YYYY>/<MM>/` shard
+- `wikitool raw accept <file> --replaces <raw-path> [--fidelity <v>] [--authority <v>] [--dry-run]` - Overwrite one existing raw file in place with a new edition
 
 **PROPERTIES**
 
@@ -1368,20 +1368,58 @@ Promote one or more files from `incoming/` into `raw/`.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool raw accept incoming/docker-cheatsheet.md --fidelity verbatim --authority reporting`
+- `tools/wikitool raw accept incoming/part-2.md --fidelity verbatim --authority reporting --page "Source - Docker Cheatsheet"`
+- `tools/wikitool raw accept incoming/cluster.md --replaces raw/documents/cluster.md`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it, two files in one call share a filename, a target path already exists, `--fidelity`/`--authority` is missing (unless `--replaces`) or names `unknown` or a value outside the schema's enum, the target name is already occupied anywhere under `raw/` by something the call does not own, `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value
-- 1    raw accept --replaces: More than one incoming file, `--page` also given, the incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, the target does not lie under `raw/` or does not exist, `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page
+- 1    raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it; two files in one call share a filename; or a target path already exists
+- 1    raw accept: `--fidelity`/`--authority` is missing, or names `unknown` or a value outside the schema's enum
+- 1    raw accept: The target name is already occupied anywhere under `raw/` by something the call does not own
+- 1    raw accept: `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value
+- 1    raw accept --replaces: More than one incoming file, or `--page` also given
+- 1    raw accept --replaces: The incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, or the target does not lie under `raw/` or does not exist
+- 1    raw accept --replaces: `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page
 
 **ON FAILURE**
 
-- raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it, two files in one call share a filename, a target path already exists, `--fidelity`/`--authority` is missing (unless `--replaces`) or names `unknown` or a value outside the schema's enum, the target name is already occupied anywhere under `raw/` by something the call does not own, `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value -> Fix the named argument and retry once. Safe to retry as-is once the cause is fixed: a file already at its computed destination is what "already exists" reports, not a partial prior run to resume. A stem-occupied refusal is not fixed by retrying at all - it names `--replaces` and renaming in `incoming/` as the two routes and neither is the tool's to pick. Never choose the destination by hand instead - that is the decision this command exists to take away
-- raw accept --replaces: More than one incoming file, `--page` also given, the incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, the target does not lie under `raw/` or does not exist, `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page -> Fix the named argument and retry once. Every check runs before the filesystem is touched, so a refusal leaves both files exactly as they were
+- raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it; two files in one call share a filename; or a target path already exists -> Fix the named argument and retry once
+- raw accept: `--fidelity`/`--authority` is missing, or names `unknown` or a value outside the schema's enum -> Pass both with a valid value, then retry once
+- raw accept: The target name is already occupied anywhere under `raw/` by something the call does not own -> Not fixed by retrying: the refusal names `--replaces` (same source, new edition) and renaming in `incoming/` (a separate source) as the two routes, and neither is the tool's to pick. Show the message to the user and wait
+- raw accept: `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value -> Fix the named argument and retry once; a different capture value on an existing page is a new edition - `--replaces`
+- raw accept --replaces: More than one incoming file, or `--page` also given -> A replacement is one file for one file - fix the call and retry once
+- raw accept --replaces: The incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, or the target does not lie under `raw/` or does not exist -> Fix the named argument and retry once - every check runs before the filesystem is touched, so both files are exactly as they were
+- raw accept --replaces: `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page -> Fix the named argument and retry once; nothing was touched
+
+**NEVER**
+
+- Never choose the destination under `raw/` by hand, and never move a file into `raw/` yourself.
+- Never pick between `--replaces` and renaming on your own initiative after a name-occupied refusal - the user tells the two intents apart.
 
 **NOTES**
 
-See `raw/CONTRACT.md` "Getting a file in: incoming/".
+- Promotes files from `incoming/` into `raw/<YYYY>/<MM>/`, computed from the accept date rather than chosen by hand. A subdirectory under `incoming/` is tolerated and ignored, not inspected - `raw/` does not address by type.
+- One file promoted alone lands with no directory of its own; several files in one call nest under `raw/<YYYY>/<MM>/<stem>/`, named after the first file's stem.
+- `--fidelity`/`--authority` are required on a plain accept (`types describe source` lists the values); `unknown` is refused - it is backfill-only.
+- `--page "<Title>"` additionally extends that existing source page's `raw_files:` in the same call and writes both capture fields onto it - refused if it already carries a different value, since a capture field is fixed once.
+- If `--page` raises the page past one file, its already-promoted file is folded into a bundle at *its own* parent directory, not today's shard, so a bundle never mixes an old and a new capture date - after checking that file has no other owner.
+- Every name occupied anywhere under `raw/` - file stems and bundle directory names alike, old type directories and date shards together - stays unique: a promote whose target name already belongs to something this call does not itself own is refused, naming `--replaces` and renaming in `incoming/` as the two routes, without recommending either.
+- `--replaces <raw-path>` overwrites that file in place with the single incoming file (same filename required), leaves every page's `raw_files:` untouched and writes no `kb/` page; the previous edition survives only in `git log --follow <raw-path>`.
+- With `--replaces`, `--fidelity`/`--authority` are optional, and passing one overwrites the owning page's already-set value - the one path the fixed-once rule does not block.
+- `--replaces` refuses a target with more than one owning source page; with none, it replaces anyway and says so. It cannot be combined with `--page` or with more than one incoming file.
+- `--replaces` prints the source page (if any) and its citing pages, so their update lands in the same commit as the replacement.
+- A file already at its computed destination is what "already exists" reports, not a partial prior run to resume - safe to retry as-is once a cause is fixed.
+- `--dry-run` reports the moves without making them.
+
+**SEE ALSO**
+
+- `raw/CONTRACT.md` "Getting a file in: incoming/" - the rules and why
+- `wikitool types describe source` - the capture field values
+- `wikitool new source` - the source page for a promoted file
 
 #### `upload list`
 
@@ -1399,13 +1437,26 @@ List every MCP submission currently waiting in the quarantine (`mcp-upload/`).
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool upload list`
+- `tools/wikitool upload list --json`
+
 **EXIT STATUS**
 
 - 0    success
 
 **NOTES**
 
-Oldest id first - id, filename, size, submitter. Only ever non-empty when `.wikitool-upload.json` opts a checkout into the MCP server's `submit` tool (see the MCP read server design note). Never fails - a submission directory with a corrupt manifest is silently skipped. Safe to retry freely.
+- Lists every submission waiting in `mcp-upload/`, oldest id first: id, filename, size, submitter.
+- Only ever non-empty when `.wikitool-upload.json` opts the checkout into the MCP server's `submit` tool.
+- A submission directory with a corrupt manifest is silently skipped.
+- Never fails; read-only and safe to retry freely.
+
+**SEE ALSO**
+
+- `wikitool upload show` - one submission's manifest
+- `INSTALL-MCP.md` § "Schritt 7: Optional - den `submit`-Pfad freischalten"
 
 #### `upload show`
 
@@ -1423,6 +1474,10 @@ Print one submission's manifest in full.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool upload show <id>`
+
 **EXIT STATUS**
 
 - 0    success
@@ -1434,7 +1489,14 @@ Print one submission's manifest in full.
 
 **NOTES**
 
-Filename, size, sha256, submitter, submitter source (the header name, not a claim the header was honest), submission time. What a reviewer reads before `accept`
+- Prints one submission's manifest in full: filename, size, sha256, submitter, submitter source (the header name, not a claim the header was honest), submission time.
+- What a reviewer reads before `upload accept`.
+- Read-only.
+
+**SEE ALSO**
+
+- `wikitool upload accept` - promotes it after review
+- `wikitool upload reject` - declines it
 
 #### `upload accept`
 
@@ -1453,19 +1515,40 @@ Filename, size, sha256, submitter, submitter source (the header name, not a clai
 - network: no
 - gates: upload-review
 
+**EXAMPLES**
+
+- `tools/wikitool upload accept <id>`
+- `tools/wikitool upload accept <id> --confirm <token>    # re-run after exit 42, once the user approved the manifest`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    Unknown or malformed submission id, the submission's file is missing from `mcp-upload/<id>/`, or `incoming/<filename>` already exists. **Exit 42, not 1**, when `--confirm` is absent or does not match the manifest's current token - the Upload Review Gate, not a validation error
-- 42   needs clearance - upload-review (see AGENTS.md § Gates)
+- 1    Unknown or malformed submission id, or the submission's file is missing from `mcp-upload/<id>/`
+- 1    `incoming/<filename>` already exists
+- 42   Upload Review Gate: `--confirm` is absent or does not match the manifest's current token
 
 **ON FAILURE**
 
-- Unknown or malformed submission id, the submission's file is missing from `mcp-upload/<id>/`, or `incoming/<filename>` already exists. **Exit 42, not 1**, when `--confirm` is absent or does not match the manifest's current token - the Upload Review Gate, not a validation error -> For exit 42: show the user the full manifest and the exact `--confirm <token>` re-run line printed, and stop - the same rule as every other exit-42 gate (AGENTS.md invariant 6). For the three exit-1 cases: fix the named argument and retry once; an occupied `incoming/<filename>` is not fixed by retrying unchanged - rename or clear it first
+- Unknown or malformed submission id, or the submission's file is missing from `mcp-upload/<id>/` -> Fix the named argument and retry once
+- `incoming/<filename>` already exists -> Not fixed by retrying unchanged - rename or clear it first
+- Upload Review Gate: `--confirm` is absent or does not match the manifest's current token -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
+
+**NEVER**
+
+- Never pass a `--confirm` token the user has not seen and approved.
 
 **NOTES**
 
-Promote a submission's file from `mcp-upload/<id>/` into `incoming/`, delete the quarantine directory, and append an `accepted` event to `mcp-upload/ledger.jsonl`. Without a matching `--confirm`, exits **42** and prints the manifest in full plus the exact re-run line - the same shape as the Mass-Update Gate's clearance, one submission at a time. The token digests id/filename/size/sha256/submitter, so an edited or superseded manifest invalidates it. Refuses (without the gate - these are ordinary validation errors) when `incoming/<filename>` already exists
+- Promotes a submission's file from `mcp-upload/<id>/` into `incoming/`, deletes the quarantine directory, and appends an `accepted` event to `mcp-upload/ledger.jsonl`.
+- Upload Review Gate: without a matching `--confirm`, exits 42 and prints the manifest in full plus the exact re-run line - one submission at a time. The gate check runs before anything is moved.
+- The token digests id, filename, size, sha256 and submitter, so an edited or superseded manifest invalidates it.
+- An occupied `incoming/<filename>` is an ordinary validation error, not the gate.
+
+**SEE ALSO**
+
+- `wikitool upload show` - the manifest to review
+- `wikitool raw accept` - the next step for the file in `incoming/`
+- `instructions/gates.md` - the gate procedure
 
 #### `upload reject`
 
@@ -1483,6 +1566,10 @@ Delete a submission's material, keeping only its ledger trail.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool upload reject <id> --reason "duplicate of raw/articles/llm-wiki.md"`
+
 **EXIT STATUS**
 
 - 0    success
@@ -1490,11 +1577,18 @@ Delete a submission's material, keeping only its ledger trail.
 
 **ON FAILURE**
 
-- Unknown or malformed submission id, or an empty `--reason` -> Fix the argument and retry once. Not idempotent against a second call with the same id: the first call already deleted the submission, so a retry reports "unknown id" - that is confirmation, not a failure
+- Unknown or malformed submission id, or an empty `--reason` -> Fix the argument and retry once. After a first successful call, "unknown id" is confirmation, not a failure
 
 **NOTES**
 
-An append-only `rejected` event naming the reason and the sha256 of what was declined. No gate - rejecting needs no clearance, only accepting does
+- Appends an append-only `rejected` event naming the reason and the sha256 of what was declined, then deletes the submission's material.
+- The ledger write happens first, so an interruption still leaves the reason on record.
+- No gate - rejecting needs no clearance, only accepting does.
+- Not idempotent: a second call with the same id reports "unknown id", which confirms the first call worked.
+
+**SEE ALSO**
+
+- `wikitool upload show` - the manifest to review
 
 ### Git