feat!: docs/ sorted into tutorials, how-to, reference, explanation plus unshipped docs/dev/; explanation pages and developer guide moved, human docs English (#187)

The seven explanation pages move to docs/explanation/ without a stub, DEVELOPMENT.md becomes docs/dev/development.md (translated to English), dist export leaves docs/dev/ out, docs verify rejects a file outside the five areas, and AGENTS.md states that the stack's human documentation is English. Required migration 9.0.0-docs-diataxis rewrites the old path in an instance's own kb/CONVENTIONS.md. Files changed: - .wikitool-kb.json - AGENTS.md - CHANGES.md - CLAUDE.md - DEVELOPMENT.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/knowledge-and-commitment.md - docs/explanation/language-boundaries.md - docs/explanation/model-and-effort-selection.md - docs/explanation/ownership-and-templates.md - docs/explanation/pipeline-rationale.md - docs/explanation/version-model.md - docs/explanation/why-gates-are-code.md - docs/how-to/README.md - docs/knowledge-and-commitment.md - docs/language-boundaries.md - docs/model-and-effort-selection.md - docs/ownership-and-templates.md - docs/pipeline-rationale.md - docs/reference/README.md - docs/tutorials/README.md - docs/version-model.md - docs/why-gates-are-code.md - instructions/CONTRACT.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-mode.md - instructions/gtd-weekly-review/SKILL.md - instructions/ingest-queue.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/migrations/9.0.0-docs-diataxis.md - instructions/upgrade-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/tasks/protocol.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_toc.py - types/type-guidance.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-06 20:45:09 +02:00
1 parent 0e15972ee7
commit d66a3f65f4
@@ -39,7 +39,7 @@ development material under `instructions/dev/` and `commonplace/`, and no
   | 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 |
   | `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/`, `commonplace/`, `DEVELOPMENT.md` and `.gitea/` are present | Never shipped |
+   | `instructions/dev/`, `docs/dev/`, `commonplace/` and `.gitea/` are present | Never shipped |

 5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
   it is how a change to the shipped surface is looked at before it is released:
@@ -68,6 +68,6 @@ development material under `instructions/dev/` and `commonplace/`, and no

 ## Scope

-Not for operating an instance, and not for the release workflow itself (`DEVELOPMENT.md` for
+Not for operating an instance, and not for the release workflow itself (`docs/dev/development.md` for
 humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
 prunes `instructions/dev/` wholesale.
@@ -36,21 +36,21 @@ 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) |
   | 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`, `DEVELOPMENT.md` names it - AGENTS.md § File naming says which document is for which reader |
-   | The reasoning behind a gate, boundary, or design decision | The `docs/` 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/` and no issue tracker, so a distributed instance gets the mechanism without the why |
+   | 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 |
+   | 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>/` |
   | 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 |
-   | [dev-setup.md](dev-setup.md) | [DEVELOPMENT.md](../../DEVELOPMENT.md), read against it the same way - nothing checks this pair at all |
+   | [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 |

 3. **A heading you changed means a table of contents to regenerate - by the tool, never by
   hand.** Every reference file over 100 lines carries one (`AGENTS.md`, the stage contracts,
   `kb/CONVENTIONS.md`, each `COLLECTION.md`, the flat `instructions/**.md` form, the
-   type-specs, the `docs/` pages - each with the `<name>.template` it ships as, where one
-   exists, and a `SKILL.md` the one exception). Adding, renaming,
-   reordering or deleting a `##`/`###` heading in one of them makes its region stale, and
+   type-specs, the `docs/` pages in all five areas - each with the `<name>.template` it ships
+   as, where one exists, and a `SKILL.md` the one exception). Adding, renaming, reordering or
+   deleting a `##`/`###` heading in one of them makes its region stale, and
   `docs verify` fails on stale exactly as it fails on missing:

   ```bash
@@ -73,7 +73,7 @@ touched; a row that does not apply needs no action.

 - **The change touched no document in the table?** Nothing to do - not every stack change moves
  a claim. A pure bugfix with an unchanged interface is the common case.
- **Unsure whether a `docs/` page's reasoning moved?** Read it. A `docs/` page carries no
+- **Unsure whether a `docs/explanation/` page's reasoning moved?** Read it. A `docs/` page carries no
  normative sentence and nothing verifies it by construction (AGENTS.md § File naming), so an
  unsure guess defaults to reading the page rather than skipping the question -
  [`stack-close`](stack-close/SKILL.md) step 3 asks it again in the closing phase as a
@@ -23,7 +23,7 @@ phases this one ends; read it first when this session started cold.
 The phases around the checked middle of a work package have no mechanical guard at all -
 `pytest`, `docs verify`, `instructions verify` and CI cover the code and tests in between, and
 nothing covers a changelog entry's accuracy, a `docs/` page's staleness, or an issue body's final
-state (see `docs/model-and-effort-selection.md`). Asking the same session to notice it has
+state (see `docs/explanation/model-and-effort-selection.md`). Asking the same session to notice it has
 crossed into that unchecked stretch - as a prose break inside one long skill - failed twice in a
 row on this stack (Gitea #42, then #30): both times the session knew the rule and skipped past
 it anyway, because nothing in the moment forced the question. The first split (Gitea #47) moved
@@ -71,7 +71,7 @@ always will.
   naming) - the same is true of `tools/CONTRACT.md`'s generated command records and any touched
   `<stage>/CONTRACT.md`, whose prose `docs verify` checks only for presence and record
   membership, never for what a field or a section actually says
-   (`instructions/dev/doc-pull-through.md`); of `README.md`/`INSTALL.md`/`DEVELOPMENT.md`
+   (`instructions/dev/doc-pull-through.md`); of `README.md`/`INSTALL.md`/`docs/`
   prose; and of a new instruction's own wording, which `instructions verify` checks structurally
   but never for what it claims. If the change this package shipped moved the reasoning or the
   behaviour one of these documents describes, update it now; if none did, say so rather than
@@ -118,4 +118,4 @@ next phase's slash command in a session started on the right model - and the tra
 what carries the work across it.

 Which model suits which phase, and the reasoning, is
-`docs/model-and-effort-selection.md`.
+`docs/explanation/model-and-effort-selection.md`.