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

tools/chemenu/tests/test_dist_cmd.py

@@ -38,7 +38,6 @@ def repo(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
         "<!-- dist:strip-start -->\n```\n└── commonplace/\n```\n<!-- dist:strip-end -->\n",
         encoding="utf-8",
     )
-    (root / "EVALS.md").write_text("# EVALS\n", encoding="utf-8")
     (root / "CLAUDE.md").write_text("# CLAUDE\n\n@AGENTS.md\n", encoding="utf-8")
     (root / ".gitignore").write_text("*.pyc\n", encoding="utf-8")
     (root / ".gitattributes").write_text("* text=auto eol=lf\n", encoding="utf-8")
@@ -191,6 +190,18 @@ def test_plan_never_includes_docs_dev(repo):
     assert "docs/explanation/why-gates-are-code.md" in plan
 
 
+def test_plan_ships_no_retired_root_docs(repo):
+    """`EVALS.md` and `INSTALL-MCP.md` became pages under docs/. A stray copy
+    left at the root of a source tree is not shipped, so an upgraded instance
+    loses them as retired files instead of carrying a stale second copy."""
+    (repo / "EVALS.md").write_text("# EVALS\n", encoding="utf-8")
+    (repo / "INSTALL-MCP.md").write_text("# MCP\n", encoding="utf-8")
+    plan = dist_cmd.build_plan()
+    assert "EVALS.md" not in plan
+    assert "INSTALL-MCP.md" not in plan
+    assert "README.md" in plan
+
+
 def test_plan_never_includes_instructions_dev(repo):
     """instructions/dev/ - flat dev-only instructions and the nested skill
     that switches a session into tool-development mode - is pruned

tools/chemenu/tests/test_git_publish.py

@@ -532,6 +532,7 @@ def test_paths_land_in_the_group_a_reviewer_expects():
     assert group_of("tools/chemenu/cli.py")[0] == "Tooling"
     assert group_of(".claude/settings.json")[0] == "Harness config"
     assert group_of("README.md")[0] == "Human docs"
+    assert group_of("docs/how-to/ingest-a-source.md")[0] == "Human docs"
     assert group_of("work/run/plan.md")[0] == "Workshop"
     assert group_of("something-else.txt")[0] == "Other"
 

tools/chemenu/tests/test_instructions_shell.py

@@ -99,7 +99,17 @@ def test_every_exception_is_still_in_use():
     assert ALLOWED <= used, ALLOWED - used
 
 
-SHIPPED_DOCS = ("AGENTS.md", "README.md", "INSTALL.md", "EVALS.md")
+SHIPPED_ROOT_DOCS = ("AGENTS.md", "README.md", "INSTALL.md")
+
+
+def shipped_docs() -> list[Path]:
+    """The root documents an operator reads, plus every page `dist export` ships under `docs/` -
+    the how-to guides among them name the preflight call an operator types."""
+    docs = REPO / "docs"
+    pages = sorted(
+        path for path in docs.rglob("*.md") if path.relative_to(docs).parts[0] != "dev"
+    )
+    return [REPO / name for name in SHIPPED_ROOT_DOCS] + pages
 
 # A line that starts the PowerShell preflight - bare (`.\tools\preflight.ps1`, `& preflight.ps1`)
 # or through pwsh - as opposed to one that merely names the file (a comment, a download).
@@ -109,7 +119,7 @@ BYPASS = "pwsh -NoProfile -ExecutionPolicy Bypass -File "
 
 @pytest.mark.parametrize(
     "path",
-    [REPO / name for name in SHIPPED_DOCS] + shipped_instructions(),
+    shipped_docs() + shipped_instructions(),
     ids=lambda p: str(p.relative_to(REPO)),
 )
 def test_every_powershell_preflight_call_carries_the_bypass(path):

tools/chemenu/tests/test_pipeline_l0.py

@@ -5,7 +5,8 @@ asks whether the commands compose - whether a wiki assembled the documented way
 comes out structurally clean, and whether the catalog is a fixed point rather
 than something that keeps changing every time it is rebuilt.
 
-That is the hard-oracle floor the eval ladder in EVALS.md rests on: before a
+That is the hard-oracle floor the eval ladder in
+docs/explanation/telemetry-and-evaluation.md rests on: before a
 score can say anything about how an agent worked, running the tools correctly has
 to be known to produce a clean tree.