darthrootbeer · Oct 2, 2026 · Oct 2, 2026
diff --git a/pipelines/docs-pipeline/ARCHITECTURE.md b/pipelines/docs-pipeline/ARCHITECTURE.md
@@ -221,7 +221,7 @@ Using only the "Stage details" section, build a table with three columns: my ste
 A good answer has one row per step of mine, writes stage names exactly as the document does, and says "none" instead of forcing a match.
 ```
 
-**How this prompt was checked.** On 2026-10-01 I ran it against Claude Sonnet and Claude Haiku in the same way as the prompts at the end of this document. The first version let Sonnet match steps to stages that do not do the same job. The prompt now says to write "none" and not to stretch a stage to fit, and Sonnet passed on the rerun. Haiku still stretched one step (rewriting by hand) onto the style passes, so treat this prompt as verified on Sonnet only.
+**How this prompt was checked.** On 2026-10-01 this prompt was run under my direction against Claude Sonnet and Claude Haiku in the same way as the prompts at the end of this document, and a Claude model (Sonnet 5.5) graded the answers; I have not re-read every answer. The first version let Sonnet match steps to stages that do not do the same job. The prompt now says to write "none" and not to stretch a stage to fit, and Sonnet passed on the rerun. Haiku still stretched one step (rewriting by hand) onto the style passes, so treat this prompt as verified on Sonnet only.
 
 ---
 
@@ -305,7 +305,7 @@ For each check give the action to take, the result I should see, and what a fail
 A good answer has exactly these four checks, does not invent commands or file names, and points out where the document is silent.
 ```
 
-**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". The answers for these prompts were not saved.
+**How these prompts were checked.** On 2026-10-01 every prompt in this document was run under my direction through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. This document and any other file the prompt names were attached, each bracketed input was replaced with a made-up sample, and a Claude model (Sonnet 5.5) graded each answer against that prompt's "good answer" list, which was written before the run. I have not re-read every answer. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". The answers for these prompts were not saved.
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |

diff --git a/pipelines/docs-pipeline/README.md b/pipelines/docs-pipeline/README.md
@@ -4,7 +4,7 @@
 
 **Why it is the best thing in this repo.** I used a version of it every working day on real documentation, and no other piece here has had that much real use. What makes it work is that the order and the gates are fixed. Style passes run before reviews, so the reviewers never read prose that still needs cleaning. Each stage commits its output, so every change can be traced to the stage that made it. And the human decision comes last, where it counts. The reason to read it is the structure, which you can copy to other kinds of work, more than any single skill.
 
-**How it was built, and what it does not claim.** Claude Code wrote these skills under my direction. I set the requirements, ran them on real documentation, read what came out, and corrected what was wrong. I did not type them by hand. This is prompts, ordering, and checks. There is no model training, no machine-learning pipeline, no retrieval system, and no claim to production ML experience. The copy here is a generic export of the version I used: you fill in the placeholders and the knowledge files before it fits your docs, and the publish and verify stages assume a git-based docs repo. I can vouch for how it behaved on my own docs, not on yours.
+**How it was built, and what it does not claim.** Claude Code wrote these skills under my direction. I set the requirements, ran them on real documentation, read what came out, and corrected what was wrong. I did not type them by hand. This is prompts, ordering, and checks. There is no model training, no machine-learning pipeline, no retrieval system, and no claim to production ML experience. The copy here is a generic export of the version I used: you fill in the placeholders and the knowledge files before it fits your docs, and the publish and verify stages assume a git-based docs repo. Stages 2, 4b and 6 assume a git repo that syncs to ReadMe (readme.com): flat slugs, ReadMe frontmatter, blockquote callouts. Other platforms need those three skills adapted. I can vouch for how it behaved on my own docs, not on yours.
 
 Each skill is a markdown file that Claude Code loads when you run the matching `/skill-name` command.
 
@@ -44,7 +44,7 @@ The pipeline loads three knowledge sources at runtime. They ship as working star
 |------|--------------|
 | `_knowledge/glossary.yaml` | Your domain terminology, canonical forms, and common mistakes |
 | `_knowledge/product-kb/` | Your product model: integration types, API endpoints, domain objects, webhooks, error codes |
-| `_knowledge/style-guides/general/style-guide_general.md` | Your voice, tone, and formatting rules |
+| `_knowledge/style-guides/general/style-guide_general.md` | Your voice, tone, and formatting rules. It also holds an optional house rule that every doc ends with a "Prompt for your AI model" block; delete that section if your docs do not carry reader prompts |
 
 Each file has fill-in instructions at the top. Stage 0 copies the whole `_knowledge/` folder into every new workspace, so fill these in before you create one.
 
@@ -60,7 +60,7 @@ workspace → audit → split → overview → structure → voice → human →
 Run the full pipeline with:
 
 ```
-/docs-pipeline TICKET-1319 setup-and-credentials
+/docs-pipeline TICKET-1234 setup-and-credentials
 ```
 
 Or invoke individual skills directly for targeted work:
@@ -136,7 +136,7 @@ Write me a trial plan that uses only the stages that do not need a docs platform
 A good answer uses the real command names from the README, leaves out the publish and verify stages, describes each stage's output only as the README does, and does not predict what the stage will find in my document.
 ```
 
-**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all three after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
+**How these prompts were checked.** On 2026-10-01 every prompt in this document was run under my direction through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. This document was attached, each bracketed input was replaced with a made-up sample, and a Claude model (Sonnet 5.5) graded each answer against that prompt's "good answer" list, which was written before the run. I have not re-read every answer. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all three after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |

diff --git a/pipelines/docs-pipeline/SETUP.md b/pipelines/docs-pipeline/SETUP.md
@@ -2,7 +2,7 @@
 
 This is a set of Claude Code skills that takes existing documentation through a structured improvement pipeline: audit → split → style passes → reviews → publish. Each skill is a markdown instruction file. Claude Code reads the file and executes the steps when you invoke the corresponding `/skill-name` command.
 
-This guide is for an AI agent setting up the pipeline for a new documentation project. Read it top to bottom before running anything.
+This guide is for you, or an AI agent working for you, setting up the pipeline for a new documentation project. Read it top to bottom before running anything.
 
 ---
 
@@ -16,6 +16,7 @@ Before running any skill:
 - **Node.js** with `markdownlint-cli` available (`npm install -g markdownlint-cli`) — required by `docs-publish`
 - A docs repository with markdown files to improve
 - A published docs site (or a staging environment) that the repo syncs to
+- A docs platform that matches the skills' assumption. Stages 2, 4b and 6 assume a git repo that syncs to ReadMe (readme.com): flat slugs, ReadMe frontmatter, blockquote callouts. Other platforms need those three skills adapted.
 
 ---
 
@@ -89,6 +90,8 @@ If the count is lower, the loop wrote to a different folder than the one Claude
 
 ## 4. Smoke test
 
+The starter `_knowledge/product-kb/index.md` ships with an `extracted:` date. Once that date is more than 90 days old, Stage 4c reports a staleness warning on the starter data. Update the date to today when you replace the starter KB (section 5).
+
 First, an offline check that needs no model. From the root of your clone, run `python3 pipelines/docs-pipeline/tests/check_pipeline.py`. It confirms that every knowledge file the skills name exists and that the folder holds no private paths. It should print `check_pipeline: clean`.
 
 Then the real test. This runs the pipeline on a short sample doc that ships in this folder (`sample/acme-orders-cancellations.md`, a made-up doc about a made-up product). It stops before anything is published and needs no placeholders. Run these in Claude Code:
@@ -203,7 +206,7 @@ Following section 5.1 of the guide and the structure in the placeholder file, dr
 A good answer uses the field names from the placeholder file exactly, has no more than 10 entries, and marks everything it could not know as "needs review".
 ```
 
-**How this prompt was checked.** On 2026-10-01 I ran it against Claude Sonnet and Claude Haiku, attaching this guide and `_knowledge/glossary.yaml`, with a made-up paragraph of product text. Sonnet passed. The first version made Haiku invent capitalization rules from how words happened to be capitalized in my sample. The prompt now forbids that, and both models passed on the rerun.
+**How this prompt was checked.** On 2026-10-01 this prompt was run under my direction against Claude Sonnet and Claude Haiku, with this guide and `_knowledge/glossary.yaml` attached and a made-up paragraph of product text. A Claude model (Sonnet 5.5) graded each answer against the prompt's "good answer" line; I have not re-read every answer. Sonnet passed. The first version made Haiku invent capitalization rules from how words happened to be capitalized in my sample. The prompt now forbids that, and both models passed on the rerun.
 
 ---
 
@@ -342,7 +345,7 @@ Rewrite the smoke test in section 4 for my doc. Change only what has to change f
 A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them.
 ```
 
-**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all four prompts after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
+**How these prompts were checked.** On 2026-10-01 every prompt in this document was run under my direction through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. This document and any other file the prompt names were attached, each bracketed input was replaced with a made-up sample, and a Claude model (Sonnet 5.5) graded each answer against that prompt's "good answer" list, which was written before the run. I have not re-read every answer. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all four prompts after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |

diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md b/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md
@@ -269,9 +269,11 @@ Not this:
 
 ## END EVERY DOC WITH A PROMPT FOR THE READER'S AI MODEL
 
+*Optional house rule. This section is a suggestion, not a requirement. Delete it, and the matching check in `docs-style-check-structure`, if your docs do not carry reader prompts.*
+
 Readers now work with an AI model beside the doc. Give them a prompt that is ready to paste, so the doc teaches, checks, and adapts itself on request.
 
-- End every doc with a prompt block.
+- If you adopt this rule, end every doc with a prompt block.
 - End every H2 section with a prompt block when the section is self-contained and longer than about 40 lines of prose (code blocks and tables do not count).
 - Use the exact block shape below. Do not rename the heading.
 - Each prompt is self-contained. It says which files the reader attaches, what the model must do, and what a good answer contains.
@@ -373,7 +375,7 @@ Write the closing prompt block for my doc in the exact shape the guide gives, wi
 A good answer uses the exact heading and intro sentence from the guide, has three labeled prompts, gives every prompt a checkable good-answer clause, explains how to run, judge, and record each test, and leaves the test result blank.
 ```
 
-**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
+**How these prompts were checked.** On 2026-10-01 every prompt in this document was run under my direction through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. This document and any other file the prompt names were attached, each bracketed input was replaced with a made-up sample, and a Claude model (Sonnet 5.5) graded each answer against that prompt's "good answer" list, which was written before the run. I have not re-read every answer. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified".
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |

diff --git a/pipelines/docs-pipeline/docs-style-check-structure.md b/pipelines/docs-pipeline/docs-style-check-structure.md
@@ -193,7 +193,7 @@ For each doc, run the checks defined below for its type. Record every finding as
 
 #### 4f. All doc types: prompt block for the reader's AI model
 
-Run this check on every doc, whatever its type. The rule lives in the general style guide under "End every doc with a prompt for the reader's AI model". Read that section first.
+This is an optional house rule, so treat every finding here as a suggestion. If the style guide has no "End every doc with a prompt for the reader's AI model" section, or the user says the docs do not carry reader prompts, skip this check and say so in the report. Otherwise run it on every doc, whatever its type. The rule lives in the general style guide under "End every doc with a prompt for the reader's AI model". Read that section first.
 
 Skip a doc if it is exempt: a skill file, a file under `_archive/`, `_templates/`, `_attachments/` or `_process/`, or an index or README under about 25 lines that only routes the reader elsewhere.
 

diff --git a/pipelines/docs-pipeline/tests/smoke-test-run.md b/pipelines/docs-pipeline/tests/smoke-test-run.md
@@ -8,7 +8,7 @@ This is the real output of following the Install and Smoke test sections of [SET
 
 Commit under test: `e035975`.
 
-```text
+~~~text
 $ git clone -b fix/docs-pipeline-runnable https://github.com/darthrootbeer/context-engineering-toolkit.git repo
 commit e035975 docs(docs-pipeline): add saved prompt runs, offline check and readability skill readme
 
@@ -45,7 +45,7 @@ Done.
     - docs/output/_process/style-audit/
     - docs/output/_process/visual-audit/diagrams/
     - docs/output/docs/
-```
+~~~
 
 I skipped three optional steps because their settings are still placeholders:
 - **Shared config link:** `SHARED_CONFIG_DIR` is unset, so there is no `_shared` link.