tools: one data record per command - -h, index and CONTRACT.md render from cli_contract (#121)

Files changed:
- AGENTS.md
- CHANGES.md
- VERSION
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-close/SKILL.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/cite_cmd.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/eval_cmd.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/index_build.py
- tools/chemenu/commands/instructions_cmd.py
- tools/chemenu/commands/links_cmd.py
- tools/chemenu/commands/lint.py
- tools/chemenu/commands/log_append.py
- tools/chemenu/commands/migrate_cmd.py
- tools/chemenu/commands/new_page.py
- tools/chemenu/commands/page_ops.py
- tools/chemenu/commands/provenance_cmd.py
- tools/chemenu/commands/raw_cmd.py
- tools/chemenu/commands/review_cmd.py
- tools/chemenu/commands/run_budget.py
- tools/chemenu/commands/search.py
- tools/chemenu/commands/task_cmd.py
- tools/chemenu/commands/touch.py
- tools/chemenu/commands/types_cmd.py
- tools/chemenu/commands/upload_cmd.py
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/commands/work_cmd.py
- tools/chemenu/commands/xref.py
- tools/chemenu/tests/test_cli_contract.py
- tools/chemenu/tests/test_docs_verify.py
- tools/chemenu/tests/test_run_budget.py

tools/chemenu/commands/raw_cmd.py

@@ -71,7 +71,7 @@ from typing import Optional
 
 import typer
 
-from chemenu import config
+from chemenu import cli_contract, config
 from chemenu.commands._util import fail, rel_path, success
 from chemenu.frontmatter_io import write_page
 from chemenu.kb_scan import load_kb_pages
@@ -309,6 +309,90 @@ def _replace(
     success("Review them in this same run: the replacement and their update belong in one commit.")
 
 
+@cli_contract.record(cli_contract.CommandRecord(
+    path="raw accept",
+    summary="Promote one or more files from `incoming/` into `raw/`.",
+    synopsis=(
+        cli_contract.Variant(
+            usage='raw accept <file> [<file> ...] --fidelity <v> --authority <v> '
+            '[--page "<Title>"] [--dry-run]',
+            notes="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",
+        ),
+        cli_contract.Variant(
+            usage='raw accept <file> --replaces <raw-path> [--fidelity <v>] [--authority <v>] '
+            "[--dry-run]",
+            notes="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",
+        ),
+    ),
+    properties=cli_contract.Properties(
+        effect=cli_contract.Effect.WRITE,
+        idempotent=cli_contract.Idempotent.NO,
+        atomic="`raw accept`: No - one filesystem move per file, then (with `--page`) one page "
+        "write. `raw accept --replaces`: No - one `unlink()` + one `rename()`, plus (if "
+        "`--fidelity`/`--authority` was given) one page write",
+        budget=cli_contract.Budget.COUNTED,
+    ),
+    notes="See `raw/CONTRACT.md` \"Getting a file in: incoming/\".",
+    failures=(
+        cli_contract.Failure(
+            label="raw accept",
+            exit_1="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",
+            retry="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",
+        ),
+        cli_contract.Failure(
+            label="raw accept --replaces",
+            exit_1="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",
+            retry="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",
+        ),
+    ),
+))
 @app.command("accept")
 def raw_accept_command(
     files: list[Path] = typer.Argument(