@caddis/cli 0.4.0 → 0.4.2

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.83",
+  "version": "1.3.87",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/check_doc_coverage.py

@@ -728,7 +728,7 @@ def remove_rows_with_targets(text: str, targets: list[str]) -> str:
 def _atomic_write(path: Path, text: str) -> bool:
     """Write ``text`` via a same-dir, per-process temp file + atomic replace. Returns True on success.
 
-    A crash mid-write can't leave a truncated DOC-MAP (mirrors dream_memory.save_facts). The temp name
+    A crash mid-write can't leave a truncated DOC-MAP. The temp name
     is PID-tagged so two concurrent runs don't fight over one temp. Returns **False (never raises)** if
     the target is locked — on Windows an open editor / AV can hold it — so a maintenance run degrades to
     a clear message instead of a stack trace.

package/bundles/antigravity-plugin/scripts/setup_project_ai.py

@@ -896,6 +896,7 @@ agent-log.jsonl
 .last-usage-review
 relay.md
 relay/
+session-state.md
 PROJECT-FACTS.md
 memory.jsonl
 """
@@ -1131,12 +1132,13 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
     """Create the harness-owned .caddis/ artifact tree + a default .gitignore + a config example.
 
     Committed subdirs: plans, handoffs, agent-docs, prd, kb, prompts, comms. Transient state
-    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, PROJECT-FACTS.md, memory.jsonl)
-    is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
+    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, session-state.md,
+    PROJECT-FACTS.md, memory.jsonl) is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
     Phase A3) — kb/ and prompts/ round out plans/prd/agent-docs/reviews so nothing has to
     scatter to the repo root or .github/. Also drops a documented `config.toml.example`
-    (guard/doc_coverage). Idempotent; never clobbers an existing .gitignore or
-    config example.
+    (guard/doc_coverage). Idempotent. An existing .caddis/.gitignore is never clobbered or
+    reordered, but MISSING entries are appended — otherwise a repo set up before an entry
+    existed would never receive it. The config example is left alone entirely.
 
     Writes into the repo's `.caddis/`.
     """
@@ -1198,7 +1200,34 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
         notes.append(f"scaffold: wrote {label}/kb/environment-map.md")
     gi = root / ".gitignore"
     if gi.exists():
-        notes.append(f"scaffold: {label}/.gitignore present — kept")
+        # APPEND what is missing rather than keeping the file frozen. The old behaviour was
+        # "present -> kept", so a repo scaffolded before an entry was added NEVER received it.
+        # That is not hypothetical: `session-state.md` is rewritten by the Stop hook on every
+        # turn and contains the operator's verbatim words, and an already-scaffolded repo was
+        # sitting one hook-fire away from committing it.
+        #
+        # Only ever adds; a line the user wrote themselves is never touched or reordered.
+        try:
+            existing = gi.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        have = {ln.strip() for ln in existing.splitlines()}
+        missing = [
+            ln for ln in ARTIFACT_GITIGNORE.splitlines()
+            if ln.strip() and not ln.startswith("#") and ln.strip() not in have
+        ]
+        if not missing:
+            notes.append(f"scaffold: {label}/.gitignore present — up to date")
+        else:
+            if not dry:
+                block = "" if existing.endswith("\n") or not existing else "\n"
+                block += "\n# added by caddis — newer transient artifacts\n"
+                block += "\n".join(missing) + "\n"
+                gi.write_text(existing + block, encoding="utf-8")
+            notes.append(
+                f"scaffold: {label}/.gitignore — added {len(missing)} missing entry(ies): "
+                + ", ".join(missing)
+            )
     else:
         if not dry:
             root.mkdir(parents=True, exist_ok=True)

package/bundles/antigravity-plugin/skills/_registry.md

@@ -39,6 +39,7 @@
 | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
+| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
 | Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
 
@@ -48,6 +49,7 @@
 |-------|------|-------------|
 | Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
 | Explainer Doc | `explainer-doc/` | Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case. |
+| Tech Explainer | `tech-explainer/` | >- |
 | Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
 | Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
 

package/bundles/antigravity-plugin/skills/safe-cleanup/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```

package/bundles/antigravity-plugin/skills/tech-explainer/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: tech-explainer
+context: fork
+description: >-
+  Write a plain-language technical explainer for a smart reader who did NOT do the investigation — a
+  manager, an infra colleague, a stakeholder, the person whose recommendation you are answering.
+  Layered Mermaid diagrams that rank causes by SIZE OF EFFECT, a controlled-vocabulary table,
+  Simplified Technical English, published withdrawn results, and questions back to the reader. Use
+  this skill whenever the user says "explain this to X", "explainer", "write this up for someone
+  non-technical", "plain English", "simplified technical english", "STE", "explain our findings",
+  "write up the benchmark results", "answer my manager's recommendations", "why is it slow — document
+  it", "make a doc with diagrams explaining the stack", or is about to summarise an investigation, a
+  benchmark, a postmortem, an architecture, or a disagreement for a reader who will not read the raw
+  data. NOT for handing off work to be BUILT by a vendor or another team (use explainer-doc for that —
+  it produces an actionable spec); NOT for READMEs or API docs (use technical-writing). This one
+  produces UNDERSTANDING: the reader must finish able to argue with you on the merits.
+---
+
+# tech-explainer — make a stranger understand, and able to push back
+
+The reader is intelligent but was not in the room. They did not watch the tests, they will not read
+the raw report, and they have their own opinion about what you should do. If you hand them the
+findings compressed, every conclusion looks like an assertion, and the conversation becomes
+credentials against credentials.
+
+**The job is not to summarise. The job is to transfer enough of the reasoning that the reader can
+disagree with you correctly.** A reader who finishes and says "I still think it's the wrapper, and
+here's why your 3x number is wrong" is a success. A reader who nods and remembers nothing is a
+failure, even if they agreed.
+
+## What this skill gives you
+
+| File                        | Use it for                                                                  |
+| --------------------------- | --------------------------------------------------------------------------- |
+| `assets/skeleton.md`        | **Start here.** The fill-in document. Copy it, then delete what has nothing to say. |
+| `references/diagrams.md`    | Copy-paste Mermaid for all six patterns, plus the syntax that bites.        |
+| `references/language.md`    | Full STE rules, the rewrite table, and the mechanical rewrite pass.         |
+
+## When this is NOT the right skill
+
+- The reader must **build** something from the document → `explainer-doc`. That skill produces an
+  actionable spec (DDL, queries, acceptance criteria). This one produces understanding.
+- The reader already lived through the investigation → `technical-writing` or a plain summary. The
+  vocabulary table and STE discipline are overhead they don't need.
+- It's a README, API reference, or runbook → `technical-writing`.
+
+The tell for *this* skill: **the reader will form or change an opinion**, and you need that opinion
+to be based on the numbers rather than on trust.
+
+## The central move — rank the layers by size of effect
+
+This is the single technique that makes the document work, and it is what most explainers get wrong.
+
+An architecture diagram shows **what exists**. It is the natural thing to draw and it is nearly
+useless here, because the reader's real question is not "what is the shape of this system" — it is
+**"what should we change?"** So draw the same stack, but label every layer with **the magnitude of
+its effect on the outcome**:
+
+```
+LAYER 1 — The model — LARGEST EFFECT — about 3x
+LAYER 2 — The engine — MEDIUM EFFECT — tens of percent
+LAYER 3 — The program — SMALL EFFECT — under 5%
+LAYER 4 — The operating system — NO EFFECT
+```
+
+Now the reader who came in convinced that swapping the program would fix everything can see, without
+being contradicted, that they were aiming at the 5% layer. **The disagreement becomes arithmetic.**
+That is worth more than any paragraph of argument, because arithmetic is something they can check
+and you cannot fake.
+
+Rules for this diagram:
+
+- **Order the layers by effect size, largest first** — not by where they sit in the stack, and not by
+  the order you investigated them.
+- **Every layer carries a number or an honest "no effect"**, plus the one-line reason. A layer with no
+  measurement is a layer you are guessing about; say "not measured" rather than inventing a rank.
+- **Include the layer the reader is about to optimise, even if it ranks last.** Leaving it out looks
+  evasive. Ranking it last with a measured number is the whole argument.
+- **Say how to read it.** One line under the diagram: *"If we change the program, we gain a few
+  percent. If we change the model, we gain about 3 times. Layer 1 is where the work must go."*
+
+If your subject has no natural layers, the same move still applies: rank the candidate causes by
+their measured contribution, and call them causes rather than layers. The stack is a convenience; the
+ranking is the point. It transfers to any "why is it slow / expensive / wrong" question — the causes
+of an ETL's runtime, the sources of a cloud bill, the contributors to a defect rate.
+
+**An attribution number must carry its method.** "The N+1 query is 85% of the p99" is the sentence
+the whole document rests on, and share-of-total figures are where this kind of analysis rots: they
+get produced by one tool, quoted onward, and nobody remembers whether it was mean or p99, warm or
+cold, one endpoint or all of them. Say how the share was obtained, in the same breath — *"85% of p99,
+from 12,000 spans over 24 hours, attributed by span duration"*. If you cannot say how, rank it
+qualitatively and mark it unmeasured rather than putting a false number on the diagram.
+
+## Simplified Technical English — the language discipline
+
+STE is not dumbing down. It is removing every sentence that can be read two ways, so a reader who is
+expert in a *different* field never has to guess. Announce it in the header so the terseness reads as
+courtesy rather than curtness:
+
+> **Written in Simplified Technical English.** Short sentences. One idea per sentence.
+
+Six rules cover most of it. Full rules and before/after rewrites: `references/language.md`.
+
+1. **One idea per sentence.** Aim under 20 words. Split on "and", "but", "which", ";".
+2. **One word, one meaning.** Fix the term in the vocabulary table (§2), then never use a synonym for
+   it. "Engine" stays "engine" — never "backend", "runtime", or "inference layer".
+3. **Active voice, and name the actor.** "We withdrew the result", not "the result was withdrawn".
+4. **No idiom, no metaphor, no hedging.** Not "the low-hanging fruit", not "it seems likely that".
+   If you are unsure, say the size of your uncertainty: "we measured this once, on a test prompt".
+5. **Every number carries its unit and its basis.** "2,373 output tokens per summary, measured from
+   `gpt-4o`" — not "about 2.4k tokens".
+6. **Never open a paragraph with a pronoun standing in for the previous paragraph.** The reader
+   skims and lands mid-document; name the subject again. ("This is the most important diagram in
+   this document" is fine — "this" points at the thing directly below it, not at prose above.)
+
+## The shape — sections in this order
+
+The order is load-bearing: the reader must be able to stop at any section and have gained something
+complete. Not every document needs all fifteen. The **bold** slots are the ones that make it *this*
+kind of document; drop the others when they have nothing to say.
+
+| §   | Slot                              | What it does                                                                                                                    |
+| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| —   | **Header**                        | Title, `**Audience:**` by name, and the STE announcement. Naming the reader changes how the whole document reads.                |
+| 1   | **Why this document exists**      | Numbered list of the questions this answers. Then route the reader's own question: *"Section 5 answers the LM Studio question."* |
+| 2   | **Words used in this document**   | Controlled vocabulary table. One meaning only. This is what lets the rest be short.                                             |
+| 3   | What we are building              | One left-to-right flowchart of the real pipeline, plus the physical facts (hardware, OS, versions).                              |
+| 4   | **The goal, in numbers**          | Target / measured / gap, in a table, with the three key rows in bold. If there is no gap, say what "good" is.                    |
+| 5   | The layer stack                   | What sits on what, and which layers are cheap to change. Answer the reader's specific question here if they asked one.           |
+| 6   | Why the work took so long         | The results you **withdrew**, and what caught each one. See below — this section buys more credibility than any other.           |
+| 7   | Where the time (or cost) goes     | A proportion chart with the sample count. Redirects effort before anyone argues about it.                                        |
+| 8   | **What limits the result**        | The ranked-layer diagram. The most important diagram in the document. Say so, and say how to read it.                            |
+| 9   | The recommendations we checked    | One row per claim: recommendation / verdict / evidence. Then a **"Where the advice is right"** subsection.                       |
+| 10  | What the constraint costs         | The forced choice (a platform, a vendor, a deadline) — what it costs, and what it genuinely gives back.                          |
+| 11  | **What we do next**               | Ordered steps as a flowchart. Name which step matters most. Then list the measurement gaps still open.                           |
+| 12  | Questions for \<reader\>          | Real questions only. This converts a verdict into a conversation.                                                                |
+| 13  | **Summary in five lines**         | Five numbered sentences. Someone will read only this. Make it survivable alone.                                                  |
+| —   | **Related documents**             | Table: document → what it holds. This is what lets §1–13 stay short without hiding anything.                                     |
+
+Rename the slots to fit the domain — a security review, a cost analysis, and a latency investigation
+will all name §3–§10 differently. Keep the order and the intent.
+
+### When a slot does not fit
+
+Most explainers hit two or three of these. Substituting is right; padding the slot with invented
+content is not, and forcing a section you have nothing for is how the document starts sounding
+false.
+
+| Situation                                            | What to do                                                                                                                                                                                            |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **§4 — no target exists**                            | Retitle it "The result, in numbers" and make the missing target the finding: *"We have no agreed p99 target. That is the first thing to fix."* A gap you cannot size is still worth naming.            |
+| **§5 duplicates §8** (few causes, one stack)         | Collapse. Make §5 a table with a column §8 lacks — usually **cost to change** or **who owns it** — and let §8 carry the only stack diagram. Two near-identical diagrams teach the reader nothing twice. |
+| **§6 — nothing was withdrawn**                       | Do not invent a retraction. Substitute the assumptions the argument rests on, plus what would falsify each. Same function: it shows the reader where to attack.                                        |
+| **§9 — no formal list of recommendations**           | The reader still has a belief. Turn it into a claims-checked table: *the claim as they would state it* / verdict / evidence. "It's just copying data" is a claim; check it like one.                    |
+| **No independent external number to anchor against** | Say so once and move on. A stated absence costs nothing; a fabricated comparison costs the document.                                                                                                   |
+| **The reader has no name** ("my manager")            | Use their role in the audience line — *"Audience: the engineering manager"* — and leave a visible placeholder. Never invent a name.                                                                     |
+| **The prompt is the only source**                    | Say so in §1 and label every number by origin: measured / calculated / assumed. See process step 2.                                                                                                    |
+
+### When to stop
+
+Section count follows the evidence, not the template. Four numbers and one conclusion is a six-section
+document; a three-week investigation with retractions is a fifteen-section document. If a section
+would exist only because the table lists it, cut it — a short explainer that a manager finishes beats
+a complete one they abandon at §7.
+
+The load-bearing minimum is: the audience line, §2, §8, §13, and the related-documents table.
+
+## The moves that carry the document
+
+**Lead every section with the bolded short answer.** The reader is looking for the answer to one
+question. Give it in the first line, in bold, then spend the section earning it:
+
+> **Short answer: we do not have LM Studio installed. But we already run the engine that is inside
+> LM Studio.**
+
+**Publish what you withdrew.** List the results you reported and later retracted, each with the cause
+and how it was caught. This feels like confessing and it is actually the strongest section in the
+document: it explains why the work took three weeks, it proves the surviving numbers were checked the
+same way, and it inoculates you against the next person who finds an error. End with the lesson in
+one line — *"a benchmark that gives a believable number is not therefore correct."*
+
+**Steelman the person you are answering.** Before refuting a recommendation, write the subsection
+where they are right, and mean it. *"The review is correct that the GPU is not fully used. We confirmed
+this with arithmetic."* Then: *"The instinct behind the advice is right. The cause is different from
+the cause given."* Nobody accepts a correction from someone who did not first understand them.
+
+**Route each wrong assumption to its real cause, and it is usually not the reader.** When someone
+recommends a fix you have already applied, the honest framing is almost never "they were wrong" — it
+is that nobody told them. Write it that way: *"The database has been on NVMe since March. That is not
+recorded anywhere the infra team can see, which is our gap to close, not a wrong call."* This is the
+same instinct as the steelman, applied to facts rather than judgement, and it does real work in a
+document that answers someone senior: it separates **the recommendation was reasonable given what
+they knew** from **the recommendation is what we should do**, which is the only distinction that
+lets a senior reader change position without losing anything. Look for it every time a verdict comes
+out "already done" or "does not apply here".
+
+**Show the arithmetic in a bare code block.** When a conclusion rests on a calculation, print it so
+the reader can redo it in their head:
+
+```
+GPU memory speed                 3,900 GB per second
+Data read per token              2.65 GB
+Theoretical maximum              1,470 tokens per second
+Measured                         114 to 316 tokens per second   (8% to 21%)
+```
+
+A number the reader can re-derive is a number they own. A number they must accept is one they will
+challenge later, at a worse time.
+
+**Anchor against an independent external result, when one exists.** "Are we misconfigured?" is
+answerable only by comparison. Find someone else's published number on comparable kit, put it in a
+two-row table beside yours, and state the conclusion plainly. This turns a defensive claim into a
+measurement. If no comparable number exists, say that in one line and move on — never assemble a
+lookalike from a different workload to fill the slot.
+
+**Admit the gaps you did not close.** Name what you never measured directly and what you would need
+to do it. Two or three lines. A document with no admitted gaps reads as marketing.
+
+**Diagrams for shape, tables for detail, prose only for judgement.** If a table says it better, delete
+the diagram. The count is not the test — the test is that each diagram answers a question no other
+one answers. The source explainer carries eight across thirteen sections and none is redundant; a
+six-section explainer with four near-identical stack diagrams is over-drawn.
+
+## Diagram vocabulary
+
+Keep to a small, repeated set of Mermaid shapes — the document reads as one voice because the same
+four patterns recur. Copy-paste versions with the syntax details (bold inside nodes, dotted
+"hypothetical" arrows, line breaks, pie charts): `references/diagrams.md`.
+
+| Pattern                            | Use for                                        |
+| ---------------------------------- | ---------------------------------------------- |
+| `flowchart LR`                     | The pipeline. Input → work → output.           |
+| `flowchart TB` with `subgraph`s    | The layer stack — §5, and the ranked §8.       |
+| `flowchart LR` with a decision node | A loop or a check procedure.                    |
+| `pie showData`                     | Where the time/cost goes. Give the run or N.   |
+
+Check every diagram before shipping: paste it into `mermaid.live`, or read it against the syntax
+table at the end of `references/diagrams.md`. A broken Mermaid block renders as raw source and costs
+more credibility than the diagram was worth.
+
+## Process
+
+1. **Name the reader and their question.** Ask if it is not obvious. "Explain the benchmark" is not
+   enough — you need *who* and *what they currently believe*, because §8's ranking exists to meet a
+   specific wrong (or right) belief. If they already have full context, stop and use a plain summary.
+2. **Read the source material yourself.** The raw report, the measurement logs, the plan, the thread
+   you are answering. Do not write an explainer from a summary — the explainer is the place where
+   soft numbers get caught, and you cannot catch them at second hand. **If no source exists and the
+   request itself is all you have**, that is workable but must be visible: say in §1 that the numbers
+   come from the requester, and tag every figure in the document `(measured)`, `(calculated)` — with
+   the arithmetic shown — or `(assumed)`. The tags cost a few words and they are what stop your
+   inference being quoted back later as someone's measurement.
+3. **Build §8 first.** List every candidate cause, attach its measured effect size, and sort. If you
+   cannot rank them, you do not yet understand the system well enough to explain it — go measure, or
+   say explicitly which layers are unranked and why.
+4. **Write §2, the vocabulary, second.** Every term you fix here makes the following sections shorter.
+5. **Copy `assets/skeleton.md` and fill it top to bottom**, deleting the slots that have nothing to
+   say (see "When a slot does not fit"). Keep evidence beside each claim rather than in an appendix.
+6. **Rewrite in STE last, as its own pass.** Split long sentences, hunt synonyms for defined terms,
+   convert passive to active, attach units to bare numbers. It is a mechanical pass; do it
+   mechanically. `references/language.md` has the rewrite table.
+7. **Run the exit gate.**
+
+## The exit gate
+
+Ask all four before shipping. Each one has caught a real defect in this document type.
+
+- **"Can the reader disagree with me on the merits?"** If every conclusion rests on "we measured it"
+  with no visible number or method, they can only agree or distrust. Neither is useful.
+- **"Does §8 rank the layer the reader cares about?"** If their favoured fix is missing from the
+  ranked diagram, the document dodges instead of answering.
+- **"Would the five-line summary survive alone?"** Someone will forward only that. Read it cold.
+- **"What did I state without a basis?"** Every number needs a unit, a sample size or a measurement
+  date, and a way to reproduce it. Bare numbers are where explainers rot first — they get quoted
+  onward, and six weeks later nobody knows what they measured.
+- **"Which section is here only because the template listed it?"** Cut it. Padding reads as padding,
+  and it spends the attention you need for §8.
+
+If the repository has a document-frontmatter convention, apply it (`type: analysis` fits this
+document kind). Then add the document to the doc index if one exists.