feat: docs/ carries the operator's how-to guides, a configuration reference and the architecture and telemetry explanations carved out of README.md, INSTALL.md, INSTALL-MCP.md and EVALS.md; the last two retired (#190)

Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - 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/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-07 05:13:56 +02:00
1 parent cff7df4ffa
commit f9056c04f7
@@ -36,7 +36,7 @@ development material under `instructions/dev/` and `commonplace/`, and no

   | Here | In an instance |
   |---|---|
-   | No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument (`EVALS.md` § "Whether it runs at all") | Telemetry is off until the operator turns it on |
+   | No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument ([telemetry-and-evaluation.md](../../docs/explanation/telemetry-and-evaluation.md#whether-it-runs-at-all)) | Telemetry is off until the operator turns it on |
   | `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
   | `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
   | `instructions/dev/`, `docs/dev/`, `commonplace/` and `.gitea/` are present | Never shipped |
@@ -11,8 +11,8 @@ what a table cell, a contract section, or a README paragraph actually *says*. A
 can change, a gate's threshold can move, a contract's wording can go false, and every one of
 those checks stays green (Gitea #90; Gitea #91 narrows what the command-table check matches, but
 adds no reading of cell content). Content quality of every document below is therefore session
-work, the same duty AGENTS.md's Changelog section states for `README.md`/`EVALS.md`/
-`tools/README.md` - this instruction exists because that duty used to stop at those three files
+work, the same duty AGENTS.md's Changelog section states for `README.md`, `tools/README.md` and
+the pages under `docs/` - this instruction exists because that duty used to stop at the human docs
 while the contracts rotted next to a green check (ten stale error-contract rows accumulated this
 way; see Gitea #89 for one).

@@ -36,12 +36,12 @@ touched; a row that does not apply needs no action.
   | A `wikitool` command's behaviour, flags, or interface | Its `cli_contract.CommandRecord` (name, synopsis, properties, exit status, retry policy - `tools/chemenu/cli_contract.py`), then `wikitool docs contract --apply` to regenerate its copy in [tools/CONTRACT.md](../../tools/CONTRACT.md) and `wikitool docs reference --apply` for the human reference under `docs/reference/` (a new group in `cli_contract.GROUPS` first needs its page there, with a title, a one-sentence head and the marker pair) |
   | A stage's authoring rules (`raw/`, `kb/`, `types/`, `reports/`, `work/`, `tools/`, `instructions/`) | The touched `<stage>/CONTRACT.md` |
   | A rule, gate, or invariant `AGENTS.md` itself states | The relevant `AGENTS.md` section (Invariants, Gates, File naming, Routing, ...) |
-   | A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `EVALS.md`, `tools/README.md`, `INSTALL.md`, `INSTALL-MCP.md` or the pages under `docs/tutorials/`, `docs/how-to/` and `docs/reference/` names it - AGENTS.md § File naming says which document is for which reader. A new page goes into the area its kind of documentation belongs to; that area's `README.md` says which |
+   | A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `tools/README.md`, `INSTALL.md` or the pages under `docs/tutorials/`, `docs/how-to/` and `docs/reference/` names it - AGENTS.md § File naming says which document is for which reader. A new page goes into the area its kind of documentation belongs to; that area's `README.md` says which |
   | The reasoning behind a gate, boundary, or design decision | The `docs/explanation/` page that carries it, if one exists (AGENTS.md § File naming lists all six reached from AGENTS.md itself, plus a seventh reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/explanation/` and no issue tracker, so a distributed instance gets the mechanism without the why |
   | A task-tracker adapter (`tools/chemenu/tasks/`), its recorded fixtures, or the live suite | [instructions/dev/tracker-testing.md](tracker-testing.md), and `MANIFEST.json` beside the fixtures when they were re-recorded |
   | A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/`; for a shipped skill (not under `instructions/dev/`) whose name or `description` changed, or one added or removed, `wikitool docs reference --apply` for the skill catalogue `docs/reference/skills.md` |
-   | A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`) | [INSTALL.md](../../INSTALL.md) § Konfiguration, where an operator looks the shape up; the [setup-instance.md](../setup-instance.md) decision point that offers it during setup; and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
-   | An installation instruction - [preflight.md](../preflight.md), [setup-instance.md](../setup-instance.md), [bootstrap.md](../bootstrap.md), [upgrade-instance.md](../upgrade-instance.md) - or `tools/prerequisites.txt` | [INSTALL.md](../../INSTALL.md), the human guide to the same procedure. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. `docs verify` checks only the two enumerable overlaps - the prerequisites lists, which `wikitool docs prerequisites --apply` regenerates from the manifest, and the setup questions: a question the agent asks the user carries `<!-- setup-question: <key> -->` where it is asked in `setup-instance.md`, and `INSTALL.md` § "Was der Agent dich fragt" names it with the same marker. Every other sentence is this session's to compare. `INSTALL.md` does not retell the steps, so a change to their order or wording alone moves nothing there |
+   | A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`) | [docs/reference/configuration.md](../../docs/reference/configuration.md), where an operator looks the shape up - written by hand, since nothing generates it; the [setup-instance.md](../setup-instance.md) decision point that offers it during setup; and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
+   | An installation instruction - [preflight.md](../preflight.md), [setup-instance.md](../setup-instance.md), [bootstrap.md](../bootstrap.md), [upgrade-instance.md](../upgrade-instance.md) - or `tools/prerequisites.txt` | [INSTALL.md](../../INSTALL.md), the human guide to the same procedure - for `upgrade-instance.md`, [docs/how-to/update-an-instance.md](../../docs/how-to/update-an-instance.md) instead. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. `docs verify` checks only the two enumerable overlaps - the prerequisites lists, which `wikitool docs prerequisites --apply` regenerates from the manifest, and the setup questions: a question the agent asks the user carries `<!-- setup-question: <key> -->` where it is asked in `setup-instance.md`, and `INSTALL.md` § "Was der Agent dich fragt" names it with the same marker. Every other sentence is this session's to compare. `INSTALL.md` does not retell the steps, so a change to their order or wording alone moves nothing there |
   | [dev-setup.md](dev-setup.md), the release workflow (`version bump`/`version release`/`publish`/CI), or another developer-facing process | [docs/dev/development.md](../../docs/dev/development.md), read against it the same way - nothing checks this pair at all. A page under `docs/dev/` is never shipped, so it may link into `instructions/dev/` and cite issue numbers |
   | A new page type the stack requires, or a new collection | Its type-spec and `COLLECTION.md` (both as the `.template` an instance adopts), the collection table in [kb/CONTRACT.md](../../kb/CONTRACT.md), and **both adoption paths**: [setup-instance.md](../setup-instance.md) for a fresh instance and [upgrade-instance.md](../upgrade-instance.md) for an existing one, where an unadopted template is what `docs verify` refuses. A new or changed `root: kb` type-spec or its schema - description, `layout:`, subtype enum, required fields - also needs `wikitool docs reference --apply` for `docs/reference/page-types.md` |

@@ -65,7 +65,7 @@ session, or a fresh one after `/clear` - assume the second, and work from the bo
   `instructions/dev/version-parts.md` § The candidate model. A `--major` bump needs `--breaking` and either a
   migration document or `--no-migration`; `instructions/dev/version-parts.md` has all of it.

-   Prose-only changes (`README.md`, `INSTALL.md`, `EVALS.md`) and the workflows under `.gitea/`
+   Prose-only changes (`README.md`, `INSTALL.md`, the pages under `docs/`) and the workflows under `.gitea/`
   do not need a bump - CI's version gate is scoped to what changes behaviour.

 5. **Pull through every document that makes a claim about the surface you touched.**
@@ -159,8 +159,8 @@ Whenever you add or change a test under `tools/chemenu/tests/`.

   Read it by module, not by total. A thin Typer wrapper sitting low is evidence that the logic
   was cut out from under it and tested there; the list worth acting on is the modules whose
-   *logic* is uncovered. EVALS.md § "How much of the stack the suite reaches" names both, and
-   the measured baseline. There is no threshold to satisfy - the suite is not graded on the
+   *logic* is uncovered. [docs/dev/development.md](../../docs/dev/development.md) § "How much of the stack the
+   suite reaches" names both, and the measured baseline. There is no threshold to satisfy - the suite is not graded on the
   number.

 ## Decision points
@@ -247,7 +247,7 @@ the three-line test below is usually enough.

 ## Decision points

- **The change ships no code - only `README.md`, `INSTALL.md`, `EVALS.md`, or `.gitea/`?** No
+- **The change ships no code - only `README.md`, `INSTALL.md`, pages under `docs/`, or `.gitea/`?** No
  bump at all; CI's version gate is scoped to what changes behaviour.
 - **A break you can see coming but are not making yet?** File it as an issue and let it
  accumulate. Boundary crossings are cheaper in batches, and step 4's "defer" alternative is
@@ -271,7 +271,7 @@ one it needs before that.

 8. <!-- setup-question: telemetry --> **Decision point - telemetry.** Every instance installed from
   a release carries a `.wikitool-release.json` and starts with telemetry **off**; nobody asked for
-   it, and nobody reads `EVALS.md` before the first file is written anyway. This step only asks
+   it, and nobody reads up on telemetry before the first file is written anyway. This step only asks
   whether the operator wants to reverse that.

   Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
@@ -289,7 +289,7 @@ one it needs before that.
   `tools/wikitool doctor` reports the result in step 12 (`telemetry`): on/off, why
   (installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
   never a `FAIL`, since both directions are a valid state. More on this:
-   [EVALS.md](../EVALS.md) § "Whether it runs at all".
+   [telemetry-and-evaluation.md](../docs/explanation/telemetry-and-evaluation.md#whether-it-runs-at-all).

 9. <!-- setup-question: task-tracker --> **Decision point - task tracker.** The instance ships the
   `project` type and the collection its type-spec's `base_dir:` names (`kb/gtd/` here), so
@@ -304,7 +304,7 @@ one it needs before that.
   `.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
   the three thresholds the review reads as configuration rather than schema. The shape, the
   shipped providers, and what Super Productivity in particular needs are in
-   [INSTALL.md](../INSTALL.md) § Konfiguration; do not restate them here. If no, do nothing - no
+   [configuration.md](../docs/reference/configuration.md#task-tracker); do not restate them here. If no, do nothing - no
   file is created, and adding one later needs nothing from this procedure.

   `doctor` reports the result in step 12 (`tasks`): absent is `OK`, a malformed file is the one
@@ -95,8 +95,8 @@ a further checkout of this one ([bootstrap.md](bootstrap.md)).
   beside it before unpacking, and refuses one that does not match. A tarball must unpack to
   exactly one top-level directory. The checksum comes from the same host as the archive, so it catches a
   damaged transfer, not a compromised host - who is trusted to publish releases is the
-   operator's decision, made before this file starts ([INSTALL.md](../INSTALL.md) § "Version und
-   Updates").
+   operator's decision, made before this file starts
+   ([update-an-instance.md](../docs/how-to/update-an-instance.md)).

 5. **Dry-run the swap and read all four counts:**

@@ -293,4 +293,4 @@ own - see the second paragraph. Anything about
 [migrate-corpus.md](migrate-corpus.md) § "Writing the migration document".

 What a human decides before any of this starts - which release, whether to take it at all, where
-the tarball comes from - is [INSTALL.md](../INSTALL.md) § "Version und Updates".
+the tarball comes from - is [update-an-instance.md](../docs/how-to/update-an-instance.md).