darthrootbeer · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026
diff --git a/.gitleaksignore b/.gitleaksignore
@@ -0,0 +1,3 @@
+# Placeholder token in a sample curl command (Authorization: Bearer YOUR_API_KEY), docs-pipeline sample doc.
+# It is a fake value in a made-up example, not a credential. The line sits in an earlier commit of PR 30, which cannot be rewritten.
+445b46ad65f98f2e34928eaf9340d5417edcde79:pipelines/docs-pipeline/sample/acme-orders-cancellations.md:curl-auth-header:22
diff --git a/pipelines/docs-pipeline/ARCHITECTURE.md b/pipelines/docs-pipeline/ARCHITECTURE.md
@@ -14,7 +14,7 @@ Think of it like a car wash with stations: soap, rinse, wax, dry. You don't skip
 
 Each stage is a **skill** — a markdown file full of instructions that Claude Code reads and follows. When you type `/docs-diataxis-audit`, Claude loads that skill file and executes the steps inside it. The skill tells Claude what to look at, what to produce, and what to check before moving on.
 
-Skills are just text files. They live in `~/.claude/skills/`. You can read them, edit them, and version them like any other file.
+Skills are just text files. They live in `~/.claude/skills/<name>/SKILL.md` once installed (section 3 of [SETUP.md](./SETUP.md) has the exact install loop). You can read them, edit them, and version them like any other file.
 
 ---
 
@@ -24,15 +24,15 @@ Three knowledge files live in `_knowledge/` and are loaded by accuracy-sensitive
 
 - `_knowledge/glossary.yaml` — domain terminology loaded by `docs-grammar-spelling` to check canonical forms and catch common mistakes
 - `_knowledge/product-kb/` — product model files loaded by `docs-sme-review` to fact-check domain accuracy claims
-- `_knowledge/style-guides/style-guide.md` — voice and tone rules loaded by `docs-style-check-voice`
+- `_knowledge/style-guides/` — style guides loaded by the style passes. `docs-style-check-voice` reads `general/style-guide_general.md`; the structure and human passes read the `diataxis/` and `write-like-a-human/` folders
 
-Placeholder files with instructions are in `_knowledge/`. The pipeline will run without them, but Stage 3b (voice), Stage 3e (grammar), and Stage 4c (SME review) will produce generic or incomplete results.
+Starter files with instructions are in `_knowledge/`, so the pipeline runs from a fresh clone. The product knowledge base describes a made-up product (the "Acme Orders API") and must be replaced with your own: until then Stage 4c (SME review) checks drafts against the wrong product. Stage 0 copies `_knowledge/` into each workspace, because the skills read it relative to the workspace folder.
 
 ---
 
 ## The workspace
 
-Before anything runs, the pipeline creates a **workspace** — a folder in `~/projects/` named like `workspace_doc-1319_setup-and-credentials`. This is where everything lives:
+Before anything runs, the pipeline creates a **workspace** — a folder in `~/projects/` (the `WORKSPACE_ROOT` constant) named like `workspace_doc-1319_setup-and-credentials`. This is where everything lives:
 
 ```
 workspace_doc-1319_setup-and-credentials/
@@ -43,7 +43,8 @@ workspace_doc-1319_setup-and-credentials/
       _process/     ← audit reports, style notes, review outputs, changes log
   CLAUDE.md         ← instructions for Claude working in this project
   README.md
-  _shared/          ← symlink to shared tools and style guides
+  _knowledge/       ← copy of the glossary, style guides and product knowledge base
+  _shared/          ← optional link to your own shared tools (only if SHARED_CONFIG_DIR is set)
 ```
 
 The workspace is a git repo. Every stage commits its output. So you can always see exactly what changed at each step.
@@ -111,7 +112,7 @@ flowchart TD
 
 ### Stage 0 — Workspace Setup (`/docs-workspace-setup`)
 
-Creates the project directory (`workspace_doc-{num}_{slug}`), runs `git init`, adds shared resource symlinks, writes `CLAUDE.md` and `README.md`, and copies the source doc(s) into `docs/input/`. Optionally creates a project note in your tracking tool.
+Creates the project directory (`workspace_doc-{num}_{slug}`), runs `git init`, copies in `_knowledge/`, writes `CLAUDE.md`, `README.md` and `.gitignore`, and copies the source doc(s) into `docs/input/`. Optionally links a shared config folder and creates a project note in your notes folder.
 
 **Outputs:** Project directory, initial git commit, source docs in place.
 
@@ -132,8 +133,8 @@ Most docs mix types. The audit surfaces those mixtures and recommends whether to
 
 **Outputs:**
 - `{guide}_audit-report.md` — full analysis with section-level breakdown
-- `{guide}_mapping.json` — machine-readable section map (schema: `_shared/schemas/diataxis-audit-mapping/`)
-- SVG visualizations of the content distribution
+- `{guide}_mapping.json` — machine-readable section map (structure is described in the audit skill; an optional schema in your shared config folder is used if present)
+- SVG visualizations of the content distribution (optional, only if the diagram tool in your shared config folder is installed)
 
 ---
 
@@ -155,7 +156,7 @@ Five sequential passes. Each one loads what it needs fresh. Each pass edits docs
 Checks Diataxis structural rules for each doc's type: required sections, heading format, opening sentence, conclusion. Rules differ per type — a how-to has different required sections than a reference.
 
 **3b — Voice (`/docs-style-check-voice`)**
-Reads the style guide from `_knowledge/style-guides/style-guide.md`. Populate this with your team's conventions before running. Applies voice and tone, list formatting, callout usage, table structure, terminology, and addressing conventions (`you`, not `the user`).
+Reads the style guide from `_knowledge/style-guides/general/style-guide_general.md`. Adapt it to your team's conventions before running. Applies voice and tone, list formatting, callout usage, table structure, terminology, and addressing conventions (`you`, not `the user`).
 
 **3c — Human (`/docs-style-check-human`)**
 Removes AI writing patterns: em dashes, banned filler phrases (`it's worth noting`, `notably`), uniform sentence length, bold-label lists, corporate padding.
@@ -304,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".
+**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.
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |

diff --git a/pipelines/docs-pipeline/README.md b/pipelines/docs-pipeline/README.md
@@ -13,7 +13,7 @@ Each skill is a markdown file that Claude Code loads when you run the matching `
 | File | Slash command | Stage | What it does |
 |------|--------------|-------|--------------|
 | `docs-pipeline.md` | `/docs-pipeline` | Orchestrator | Runs the full pipeline end-to-end, stage by stage |
-| `docs-workspace-setup.md` | `/docs-workspace-setup` | 0 | Creates the workspace directory, symlinks, and project note |
+| `docs-workspace-setup.md` | `/docs-workspace-setup` | 0 | Creates the workspace directory, copies in the knowledge files, and writes the starter files |
 | `docs-diataxis-audit.md` | `/docs-diataxis-audit` | 1 | Classifies doc content by Diataxis type, produces audit report + JSON mapping |
 | `docs-diataxis-split.md` | `/docs-diataxis-split` | 2 | Extracts content into typed output files (how-to, explanation, reference, tutorial) |
 | `docs-diataxis-create-overview.md` | `/docs-diataxis-create-overview` | 2b | Creates the overview/index entry-point doc after a split |
@@ -30,22 +30,28 @@ Each skill is a markdown file that Claude Code loads when you run the matching `
 | `docs-publish.md` | `/docs-publish` | 6 | Copies output to docs repo, adds frontmatter, creates branch + PR |
 | `docs-work-verify.md` | `/docs-work-verify` | Post | Verifies the PR merged and changes are live |
 
+## Quick start
+
+1. Install the skills with the loop in section 3 of [SETUP.md](./SETUP.md).
+2. Run the smoke test in section 4 of [SETUP.md](./SETUP.md). It uses the sample doc in [`sample/`](./sample/acme-orders-cancellations.md) and needs no configuration.
+3. Replace the made-up product knowledge in `_knowledge/` with your own (next section), then fill in the placeholders under Configuration.
+
 ## Knowledge sources
 
-The pipeline loads three knowledge sources at runtime. Populate these before running:
+The pipeline loads three knowledge sources at runtime. They ship as working starters, so it runs from a fresh clone. The product knowledge base describes a made-up product (the "Acme Orders API"), so replace it with your own before you trust Stage 4c on real docs:
 
 | Path | What it needs |
 |------|--------------|
 | `_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/style-guide.md` | Your voice, tone, and formatting rules |
+| `_knowledge/style-guides/general/style-guide_general.md` | Your voice, tone, and formatting rules |
 
-Placeholder files with structure and instructions are already in `_knowledge/`. Fill them in before running `docs-grammar-spelling`, `docs-sme-review`, or `docs-style-check-voice`.
+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.
 
 ## Pipeline order
 
 ```
-workspace → audit → split → structure → voice → human → readability
+workspace → audit → split → overview → structure → voice → human → readability
          → grammar → visuals → links → SME → changes → decisions → publish → verify
 ```
 
@@ -81,6 +87,8 @@ Before using this pipeline on your docs, replace these placeholders throughout t
 | `{YOUR_DOCS_REPO_PATH}` | Local filesystem path to your docs repo clone |
 | `{YOUR_DEFAULT_OG_IMAGE_URL}` | Default Open Graph image URL for published docs |
 
+Two placeholders are optional. `{SHARED_CONFIG_DIR}` (a folder of your own shared tools) and `{NOTES_DIR}` (a notes folder for a project note) can stay as they are: any step that needs them is skipped. `{YOUR_PIPELINE_DIR}` is filled in by the install loop in SETUP.md, so you do not set it by hand.
+
 ---
 
 ### Prompt for your AI model
@@ -94,10 +102,10 @@ I have attached the README for "docs-pipeline", a set of Claude Code skills that
 
 1. In plain language, say what problem it solves and what it does not do.
 2. List the stages in order, one line each, and explain why the style passes come before the reviews.
-3. Say where a person has to decide something and where the AI works alone.
+3. Say exactly what the person does between every two stages, and what the AI does alone inside a stage.
 4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong.
 
-A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead, and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README.
+A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead (so it never says the person does not touch a stage), and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README.
 ```
 
 **Review against your own setup**
@@ -128,11 +136,10 @@ 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 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 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".
 
 | Prompt | Sonnet | Haiku |
 | --- | --- | --- |
-| Understand and teach | Pass | Pass |
-| Review against your own setup | Pass | Pass. It credited the README with a phrase the README does not contain. |
-| Adapt and test | Pass | Pass after a fix. The first version asked what I "should expect to see", and Haiku answered with confident predictions about a document it had never seen. The prompt now asks only for what the README says each stage produces. |
-
+| Understand and teach | Pass | Pass. It said the pipeline "works through seven stages", a count the README does not state. |
+| Review against your own setup | Pass | Pass. It did not list the three optional placeholders, which the README describes in prose and not in the table. |
+| Adapt and test | Pass | Pass |