@vpxa/aikit 0.1.147 → 0.1.148

package/scaffold/dist/definitions/skills/docs.mjs

@@ -1,657 +1,229 @@
-function e({blockDocs:e}={}){return[{file:`references/diataxis-anti-patterns.md`,content:`# Diátaxis Anti-Patterns
+function e({_blockDocs:e}={}){return[{file:`references/diataxis-reference.md`,content:`# Diátaxis Reference
 
-Five common documentation anti-patterns that violate Diátaxis quadrant boundaries. Each pattern includes detection signals, a violation/compliant example pair, and remediation.
+    Use this reference to classify documentation before writing, choose the right document shape, review quality, and detect quadrant drift early.
 
-## Anti-Pattern 1: Tutorial with Explanation
+    ## Two-Question Compass
 
-**Detection signals:** "This is because...", conceptual paragraphs between steps, "Let's understand why..." mid-tutorial.
+    The Diátaxis compass classifies documentation with two questions:
 
-**Failure mode:** Learner loses momentum; cognitive load increases; tutorial becomes reference-like.
+    | Axis | Question | Poles | What it decides |
+    |------|----------|-------|-----------------|
+    | Intent | Is the reader trying to do something or understand something? | Action vs Cognition | Whether the document guides work or develops understanding |
+    | Context | Is the reader learning or working? | Study vs Work | Whether the document supports acquisition or application |
 
-**Violation example:**
+    Interpret the axes this way:
 
-> Step 4: Exchange the authorization code for a token.
->
-> The authorization code grant exists because the client and server need a temporary credential that can be verified before issuing a bearer token. In OAuth 2.0, this protects the user agent from exposing long-lived credentials and supports redirect-based trust establishment. The protocol also separates authentication from authorization, which matters when multiple identity providers are involved.
->
-> Now paste the token into the next command.
+    - **Action** means practical doing, following steps, executing work, or completing a task.
+    - **Cognition** means understanding, context, concepts, relationships, or meaning.
+    - **Study** means the reader is building skill or knowledge.
+    - **Work** means the reader is applying existing skill to a real task.
 
-**Compliant example:**
+    Use the compass when a draft feels mixed, when a request could fit more than one document type, or when you need a quick check before creating a new page.
 
-> Step 4: Exchange the authorization code for a token.
->
-> Note: For why this works, see [Explanation: Authentication Flow].
+    ## Four Quadrants
 
-**Fix:** Extract all "why" content to a separate explanation document. Leave only the action and the minimum guidance needed to complete the learning exercise.
+    The two axes produce four document forms:
 
-## Anti-Pattern 2: How-To That Teaches
+    | Quadrant | Reader need | Outcome | Typical signals | Avoid |
+    |----------|-------------|---------|-----------------|-------|
+    | Tutorial | Action + Study | Learner completes a guided lesson | staged steps, visible checkpoints, one skill at a time | reference tables, deep rationale, broad coverage |
+    | How-To | Action + Work | Capable user completes a specific task | imperative steps, prerequisites, verification | long teaching sections, conceptual detours |
+    | Reference | Cognition + Work | Reader looks up facts quickly | exhaustive tables, schemas, parameters, contracts | opinion, narrative, workflow instruction |
+    | Explanation | Cognition + Study | Reader understands why something is shaped this way | trade-offs, concepts, relationships, architecture reasoning | procedural steps, command sequences |
 
-**Detection signals:** "Let's learn...", "First, understand that...", explanations of basic concepts, beginner-level framing.
+    Common blur zones:
 
-**Failure mode:** Experienced users waste time reading fundamentals they already know.
+    | Content | Looks Like | Actually Is | Disambiguation |
+    |---------|-----------|-------------|----------------|
+    | Getting Started | Tutorial or How-To | Tutorial if there is a learning journey; How-To if it only gets the system running | Look for staged learning versus immediate task completion |
+    | Architecture Overview | Explanation or Reference | Explanation if it interprets design; Reference if it inventories components or schemas | Ask whether the page argues or catalogs |
+    | Troubleshooting | How-To or Reference | How-To if it says what to do; Reference if it lists symptoms or codes | Ask whether the reader is acting or checking |
+    | Best Practices | Explanation or How-To | Explanation if it discusses trade-offs; How-To if it gives concrete steps | Ask whether the page persuades or instructs |
+    | Changelog | Reference or Explanation | Usually Reference; Explanation only when it includes rationale and interpretation | Ask whether the entry records changes or explains them |
 
-**Violation example:**
+    If a draft mixes signals from multiple rows, re-run the [Two-Question Compass](#two-question-compass), then reshape it with the matching section under [Templates](#templates).
 
-> # How to Deploy
->
-> Before we deploy, let's learn what Docker is. Docker is a containerization platform that packages software with its dependencies so it can run consistently across environments. Containers differ from virtual machines because they share the host kernel...
+    ## Templates
 
-**Compliant example:**
+    Pick one template and keep the whole page in that mode.
 
-> # How to Deploy
->
-> Prerequisites: Docker installed. If you need setup help, see [Tutorial: Getting Started with Docker].
->
-> 1. Build the image.
-> 2. Push it to the registry.
-> 3. Roll out the new version.
+    | Quadrant | Recommended structure | Notes |
+    |----------|-----------------------|-------|
+    | Tutorial | Goal, prerequisites, staged steps, visible checkpoints, recap | Teach one skill well. Keep momentum. |
+    | How-To | Goal, prerequisites, steps, verification, troubleshooting | Assume competence. Omit background unless strictly needed to act. |
+    | Reference | Overview, schema or API surface, options, constraints, examples for lookup | Keep tone factual, terse, and consistent. |
+    | Explanation | Problem, context, concepts, trade-offs, related decisions, links to evidence | Take a position. Connect ideas instead of listing procedures. |
 
-**Fix:** Assume competence. Split foundational teaching into a tutorial for learners and keep the how-to focused on completing a task for someone who already knows the basics.
+    Quadrant-specific rules:
 
-## Anti-Pattern 3: Reference with Narrative
+    - **Tutorial**: show visible results at each stage, avoid digressions, and link outward for depth.
+    - **How-To**: focus on one task, use imperative language, and keep supporting context brief.
+    - **Reference**: optimize for lookup speed, stable structure, and completeness.
+    - **Explanation**: explain why, connect causes and consequences, and link to code, ADRs, or tool output.
 
-**Detection signals:** First-person voice ("I recommend..."), opinions, step-by-step instructions in a reference table, anecdotes.
+    Run the finished draft against the [Quality Checklist](#quality-checklist) before shipping it.
 
-**Failure mode:** Reference becomes unreliable for quick lookup; opinions pollute facts.
+    ## Quality Checklist
 
-**Violation example:**
+    Run this checklist against every document created or updated during \`_docs-sync\`:
 
-> | Parameter | Type | Description |
-> |-----------|------|-------------|
-> | \`retry\` | \`number\` | I usually set this to \`5\` because it feels safer in production, and in my experience lower values make operators nervous. |
+    ### Quadrant Purity
+    - [ ] Document serves exactly one Diátaxis quadrant
+    - [ ] No mixed-mode content such as tutorial narration plus reference tables plus explanation prose
+    - [ ] Language patterns match the selected quadrant (see [Four Quadrants](#four-quadrants))
+    - [ ] If content from another quadrant is needed, it is linked, not embedded
 
-**Compliant example:**
+    ### Structure & Completeness
+    - [ ] All required sections for the chosen form are present (see [Templates](#templates))
+    - [ ] No empty placeholder sections
+    - [ ] Cross-references to related docs in other quadrants exist where useful
+    - [ ] Any \`type:\` frontmatter or metadata matches the actual quadrant
 
-> | Parameter | Type | Default | Constraints |
-> |-----------|------|---------|-------------|
-> | \`retry\` | \`number\` | \`3\` | Integer, \`0-10\` |
->
-> For recommended usage patterns, see [How-To: Retry Configuration Best Practices].
+    ### Evidence & Accuracy
+    - [ ] Claims are traceable to source files, config, or AI Kit tool output
+    - [ ] Unknowns are marked \`[TODO]\`, not guessed
+    - [ ] Team-intent items are marked \`[ASK USER]\`
+    - [ ] No stale facts such as removed features, deprecated APIs, or obsolete version details
 
-**Fix:** Strip opinions into explanation content and move procedures into a how-to. Keep the reference page factual, terse, and optimized for lookup.
+    ### Audience Fit
+    - [ ] Tutorial assumes a learner and teaches one skill at a time
+    - [ ] How-To assumes competence and stays task-focused
+    - [ ] Reference stays factual, comprehensive, and structurally consistent
+    - [ ] Explanation provides context, perspective, and connected reasoning
 
-## Anti-Pattern 4: Explanation with Procedures
+    Iterate in small loops:
 
-**Detection signals:** Numbered steps, imperative commands, "Step 1:", code blocks with instructions to run.
+    1. Pick one document, section, or paragraph.
+    2. Classify it with the [Two-Question Compass](#two-question-compass).
+    3. Check it against this checklist.
+    4. Make one improvement.
+    5. Repeat.
 
-**Failure mode:** Reader expecting understanding gets confused by action items; the document serves neither purpose well.
+    Optional audit scoring:
 
-**Violation example:**
+    | Score | Quality | Action |
+    |-------|---------|--------|
+    | 100% | Excellent | No action needed |
+    | 75-99% | Good | Fix during the next related change |
+    | 50-74% | Needs work | Schedule improvement |
+    | <50% | Poor | Rewrite or split immediately |
 
-> # Why We Use Microservices
->
-> Our architecture separates services by deployment boundary and ownership model.
->
-> Step 1: Create a new service directory under \`services/\`.
-> Step 2: Copy the standard Dockerfile.
-> Step 3: Register the service in the gateway config.
+    Organic growth rules:
 
-**Compliant example:**
+    - Let structure emerge from real content needs; do not create empty four-folder layouts.
+    - A project with no tutorials does not need a \`tutorials/\` directory.
+    - Add document types as the codebase and team actually need them.
+    - A correct, narrow document is better than an ambitious mixed document.
 
-> # Why We Use Microservices
->
-> This architecture reduces coupling between release cycles, lets teams own isolated domains, and supports scaling services unevenly.
->
-> For the practical workflow, see [How-To: Create a New Service].
+    ## Anti-Patterns
 
-**Fix:** Move procedures to a how-to or tutorial. Keep explanation documents discursive, interpretive, and focused on reasoning rather than execution.
+    These patterns signal quadrant mixing or misplaced content.
 
-## Anti-Pattern 5: Mixed-Mode Document
+    | Anti-pattern | Detection signals | Failure mode | Fix |
+    |--------------|-------------------|--------------|-----|
+    | Tutorial with Explanation | conceptual paragraphs between steps, "why" digressions mid-lesson | learner loses momentum and the lesson becomes reference-like | move reasoning to Explanation and leave only the learning path |
+    | How-To That Teaches | beginner framing, concept lessons, long fundamentals | experienced users must read material they do not need | assume competence and link to Tutorial for prerequisites |
+    | Reference with Narrative | opinion, anecdotes, first-person recommendations, workflow prose | lookup becomes slow and facts become unreliable | keep facts in Reference, move interpretation to Explanation |
+    | Explanation with Procedures | numbered commands, imperative instructions, run-this-now blocks | the page stops explaining and starts acting like a guide | move procedures to How-To or Tutorial |
+    | Mixed-Mode Document | one page tries to teach, instruct, explain, and catalog at once | the page serves no audience well and becomes hard to maintain | split the page by quadrant and cross-link the results |
 
-**Detection signals:** Multiple quadrant signals in one document; tutorial narration plus reference tables plus explanation prose; a page with more than two distinct purposes.
+    Common mistakes worth catching in review:
 
-**Failure mode:** The document serves no single purpose well, becomes impossible to maintain, and grows without bound.
+    - Writing a tutorial that tries to be comprehensive instead of teach one skill.
+    - Embedding opinion in reference material.
+    - Creating empty four-quadrant structures before the content exists.
+    - Writing how-to guides that explain everything instead of helping the reader finish the task.
+    - Writing explanation without perspective, trade-offs, or evidence.
+    - Trying to classify navigation pages such as indexes or README landing pages; navigation pages can remain unclassified.
 
-**Violation example:**
+    This reference adapts concepts from the Diátaxis framework at diataxis.fr. Diátaxis framework content is licensed under CC-BY-SA 4.0; retain attribution and share-alike terms for further adaptations.`},{file:`references/project-knowledge-reference.md`,content:`# Project Knowledge Reference
 
-> # Authentication Guide
->
-> OAuth lets users delegate access without sharing passwords. Here is a beginner-friendly walkthrough of the handshake. Below is the full endpoint matrix and token schema. Next, compare session cookies with JWTs and evaluate the security trade-offs. Finally, follow these steps to configure SSO in production.
+## Workflow
 
-**Compliant example:**
+### Project Knowledge — Workflow
 
-Split the material into four documents:
-
-1. Tutorial: Getting Started with Authentication
-2. Reference: Authentication API
-3. Explanation: Authentication Architecture Decisions
-4. How-To: Configure SSO
-
-**Fix:** Split the page into separate documents, one per quadrant. Cross-link them so readers can move between learning, doing, understanding, and lookup without mode-switching inside a single page.
-
-## Blur Zones
-
-Common cases where the boundary between two quadrants is genuinely ambiguous:
-
-| Content | Looks Like | Actually Is | Disambiguation |
-|---------|-----------|-------------|----------------|
-| Getting Started | Tutorial or How-to | Ask whether there is a learning journey. If yes, it is a Tutorial. If it is just "get it running", it is a How-to. | Look for staged learning versus immediate task completion. |
-| Architecture Overview | Explanation or Reference | If it explains why the system is shaped this way, it is Explanation. If it lists components, schemas, or interfaces, it is Reference. | Ask whether the page interprets or inventories. |
-| Troubleshooting | How-to or Reference | If it says "do X when Y happens", it is a How-to. If it is a lookup table of error codes or symptoms, it is Reference. | Ask whether the reader is acting or checking. |
-| Best Practices | Explanation or How-to | If it explains reasoning and trade-offs, it is Explanation. If it gives actionable steps to follow, it is a How-to. | Ask whether the content persuades or instructs. |
-| Changelog | Reference or Explanation | It is almost always Reference because it is a factual record. It only becomes Explanation when it includes design rationale and interpretation. | Ask whether the entry records changes or argues for them. |
-
-## Common Mistakes
-
-| Mistake | Why It's Wrong | Fix |
-|---------|----------------|-----|
-| Writing a tutorial that tries to be comprehensive | Tutorials should teach one thing well, not cover everything. | Narrow the scope and link to reference for completeness. |
-| Embedding opinions in reference docs | Reference must be factual and trustworthy. | Move opinions to explanation docs. |
-| Creating empty four-section structures | Diátaxis is a quality framework, not a template to fill. | Let structure emerge from actual content needs. |
-| Making how-to guides that explain everything | How-to assumes competence; explanations break flow. | Link to tutorials for prerequisites and explanations for context. |
-| Writing explanation that lacks opinion or perspective | Good explanation connects concepts and provides insight. | Take a position and explain trade-offs and reasoning. |
-| Trying to classify every page | Some pages, such as README or index pages, are navigation rather than content. | Navigation pages do not need quadrant classification. |
-
-## Attribution
-
-This reference adapts concepts from the Diátaxis framework at diataxis.fr and from keithpatton/diataxis-agent-skill. Diátaxis framework content is licensed under CC-BY-SA 4.0; retain attribution and share-alike terms for further adaptations.`},{file:`references/diataxis-compass.md`,content:`# The Diataxis Compass
-
-The Diataxis Compass is a simple classification aid for documentation. It reduces classification to two axes so an author can decide what kind of document they are writing before structure and tone drift across quadrants.
-
-Use it when a draft feels mixed, when a request could fit more than one documentation type, or when you need a quick check before creating a new document.
-
-## The Two Axes
-
-The compass uses two independent axes:
-
-| Axis | Question | Poles | What it tells you |
-|------|----------|-------|-------------------|
-| Horizontal | Is the reader trying to do something or understand something? | Action vs Cognition | Whether the content should guide behavior or develop understanding |
-| Vertical | Is the reader learning or working? | Study vs Work | Whether the content serves acquisition or application |
-
-Interpret the axes this way:
-
-- **Action** means practical doing, following steps, executing work, or completing a task.
-- **Cognition** means understanding, context, concepts, relationships, or meaning.
-- **Study** means the reader is acquiring skill or knowledge.
-- **Work** means the reader is applying skill or knowledge to a real task.
-
-## ASCII Quadrant Diagram
-
-\`\`\`text
-                     ACTION                              COGNITION
-          +--------------------------------+--------------------------------+
- STUDY    | Tutorial                       | Explanation                    |
-          | Learn by doing                 | Learn by understanding         |
-          +--------------------------------+--------------------------------+
- WORK     | How-to Guide                   | Reference                      |
-          | Accomplish a specific task     | Consult facts while working    |
-          +--------------------------------+--------------------------------+
-\`\`\`
-
-## Two-Question Decision Tree
-
-Ask these questions in order:
-
-1. Is the reader trying to **DO** something or **UNDERSTAND** something?
-2. Is the reader **LEARNING** or **WORKING**?
-
-Answer matrix:
-
-| Q1 | Q2 | Result |
-|----|----|--------|
-| Action | Study | Tutorial |
-| Action | Work | How-to guide |
-| Cognition | Work | Reference |
-| Cognition | Study | Explanation |
-
-Short version:
-
-- Action + Study = **Tutorial**
-- Action + Work = **How-to guide**
-- Cognition + Work = **Reference**
-- Cognition + Study = **Explanation**
-
-## Content Type Signals
-
-Trigger phrases are not absolute rules, but they are strong signals.
-
-| Quadrant | Typical trigger phrases or patterns | What they usually indicate |
-|----------|-------------------------------------|----------------------------|
-| Tutorial | \`build your first\`, \`getting started\`, \`learn\`, \`introduction to\`, \`beginner\`, \`walkthrough\` | A guided learning path with a defined outcome |
-| How-to guide | \`how to\`, \`configure\`, \`deploy\`, \`set up\`, \`integrate\`, \`migrate\`, \`troubleshoot\` | A task-focused guide for a user trying to solve a real problem |
-| Reference | \`API\`, \`parameters\`, \`options\`, \`schema\`, \`configuration\`, \`specification\`, \`returns\` | Structured factual material consulted during work |
-| Explanation | \`why\`, \`how it works\`, \`overview\`, \`trade-offs\`, \`background\`, \`concepts\`, \`design\` | Material meant to increase understanding and context |
-
-Signals become more reliable when they align across title, headings, verbs, and document structure.
-
-## Confidence Calibration
-
-Use confidence to decide whether to classify, split, or rewrite.
-
-| Confidence | Interpretation | Recommended action |
-|------------|----------------|--------------------|
-| High | All signals match one quadrant | Classify directly and write fully in that mode |
-| Medium | Signals match one quadrant but the topic could span two | Classify to the dominant quadrant and cross-link the adjacent need |
-| Low | Mixed signals across quadrants | Split the document rather than forcing one label |
-
-Practical rule:
-
-- **High** means title, tone, structure, and user need all point the same way.
-- **Medium** means one quadrant clearly dominates, but a neighboring quadrant is tempting.
-- **Low** means the document is trying to teach, guide, explain, and describe at once.
-
-## Edge Cases
-
-Some common document labels are ambiguous on their face. Classify by function, not by title alone.
-
-| Content label | Recommended classification | Reasoning |
-|---------------|----------------------------|-----------|
-| README | Reference | Usually a project summary and entry point, not a discursive explanation |
-| FAQ | Split per question | Each answer may belong to a different quadrant |
-| Getting Started | Tutorial or How-to guide | Tutorial if aimed at learning; How-to if aimed at competent users getting started in work |
-| Troubleshooting | How-to guide | It is task-oriented problem solving |
-| Changelog | Reference | It is a factual record |
-| Architecture overview | Explanation | It exists to help the reader understand system design |
-| Migration guide | How-to guide | It helps the reader complete a concrete transition task |
-
-## Ambiguity Protocol
-
-When classification is uncertain:
-
-1. Default to the quadrant that serves the reader's immediate need.
-2. If it is still unclear, split the document by quadrant.
-3. If splitting is not worth the cost, classify it by the dominant quadrant and explicitly note the secondary one.
-
-Useful signs that a split is warranted:
-
-- the introduction promises learning, but the body is a task checklist
-- the document alternates between step-by-step actions and API facts
-- the writer keeps adding “why” digressions to operational instructions
-- headings naturally group into two different quadrant modes
-
-## Attribution
-
-This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the Compass and related quadrant descriptions.
-
-Source material is licensed under **CC-BY-SA 4.0**.
-
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).`},{file:`references/diataxis-quadrants.md`,content:`# Diataxis Quadrants
-
-This reference describes the four documentation quadrants in Diataxis: Tutorial, How-to guide, Reference, and Explanation. Use it when a document has already been classified, or when you need boundary tests to decide whether content belongs in one quadrant or has drifted into another.
-
-## Tutorial
-
-### Definition
-
-A tutorial is a guided learning experience. It helps a reader acquire competence by doing something meaningful in a controlled path toward a defined outcome.
-
-### Tutorial Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Learning-oriented | A reference to consult |
-| Practical and guided | A set of independent steps |
-| Structured as a path | Complete coverage of a topic |
-| Built around a defined outcome | A free-form discussion |
-
-### Defining Characteristics
-
-- It is designed for a reader who is still learning.
-- It follows a deliberate path from start to finish.
-- It creates a successful encounter with the product or skill.
-- It limits choices so the learner can focus.
-- It optimizes for confidence, momentum, and visible progress.
-
-### Language Patterns
-
-Tutorial language is guided, concrete, and supportive. It commonly uses second person and first-person plural.
-
-- \`In this tutorial, you will ...\`
-- \`You'll see ...\`
-- \`Next, we ...\`
-- \`Notice that ...\`
-- \`The output should look something like ...\`
-
-The tone should reduce uncertainty, set expectations, and keep the learner on a single path.
-
-### Boundary Tests
-
-- If the steps can be done in any order, it is probably **not** a tutorial.
-- If there is no learning outcome, it is probably a **How-to guide**.
-- If the content starts listing all options and variants, it is drifting toward **Reference**.
-- If the content spends time on rationale and design history, it is drifting toward **Explanation**.
-
-## How-to Guide
-
-### Definition
-
-A how-to guide is a task-oriented document for someone trying to solve a specific problem or complete a real piece of work. It assumes the reader already has enough competence to act on concise guidance.
-
-### How-to Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Task-oriented | A lesson |
-| Practical | An explanation of concepts |
-| Focused on a specific problem | A comprehensive reference |
-| Written for application in real work | A broad introduction |
-
-### Defining Characteristics
-
-- It starts from a concrete goal or problem.
-- It is written for readers who are already doing work.
-- It emphasizes action, judgement, and usable sequence.
-- It avoids digressions into fundamentals unless strictly necessary.
-- It may branch for real-world conditions and alternatives.
-
-### Language Patterns
-
-How-to language is direct and imperative. It should sound executable.
-
-- \`Configure X.\`
-- \`Deploy to Y.\`
-- \`Set up the service account.\`
-- \`If you need Z, do ...\`
-- \`To migrate safely, first ...\`
-
-Good how-to writing is short, concrete, and free of conceptual detours.
-
-### Boundary Tests
-
-- If it teaches fundamentals before the task, it is drifting toward **Tutorial**.
-- If it mostly describes available options rather than choosing a path, it is drifting toward **Reference**.
-- If it answers \`why\` more than \`what to do\`, it is drifting toward **Explanation**.
-- If success depends on following a pedagogical sequence rather than solving a task, it belongs in **Tutorial**.
-
-## Reference
-
-### Definition
-
-Reference is factual documentation consulted during work. It describes the machinery, interface, structure, or behavior of the system as clearly and consistently as possible.
-
-### Reference Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Information-oriented | A guide |
-| Austere and factual | Opinionated |
-| Comprehensive within scope | Narrative |
-| Structured consistently | Selective in the style of a lesson |
-
-### Defining Characteristics
-
-- It is optimized for lookup, not for linear reading.
-- It presents facts, interfaces, constraints, and structure.
-- It uses a consistent pattern so readers can find answers quickly.
-- It aims for completeness inside a defined scope.
-- It avoids persuasion, instruction-heavy flow, and discursive context.
-
-### Language Patterns
-
-Reference language is descriptive, factual, and usually third person.
-
-- \`Returns {type}.\`
-- \`Accepts the following parameters ...\`
-- \`Option values are ...\`
-- \`The schema contains ...\`
-- \`Configuration keys include ...\`
-
-Warnings and constraints are fine, but they should remain factual rather than tutorial or argumentative.
-
-### Boundary Tests
-
-- If the content explains why a design exists, it belongs in **Explanation**.
-- If the content shows how to accomplish a task with the feature, it belongs in **How-to guide**.
-- If the content walks a newcomer through a first success path, it belongs in **Tutorial**.
-- If the content becomes selective and outcome-driven rather than complete and structured, it is no longer pure reference.
-
-## Explanation
-
-### Definition
-
-Explanation is understanding-oriented documentation. It connects concepts, provides rationale and background, and helps the reader build a mental model of the system or topic.
-
-### Explanation Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Understanding-oriented | Step-by-step instructions |
-| Discursive and connective | A lookup table |
-| Rich in context | A tutorial |
-| Concerned with reasons and implications | A terse list of facts |
-
-### Defining Characteristics
-
-- It provides context, rationale, and conceptual framing.
-- It connects details into a broader mental model.
-- It can discuss trade-offs, history, alternatives, and design intent.
-- It supports reflection more than immediate action.
-- It is bounded by topic rather than by task or API surface.
-
-### Language Patterns
-
-Explanation language is descriptive, interpretive, and often comparative.
-
-- \`The reason for ...\`
-- \`This approach was chosen because ...\`
-- \`Consider the trade-off ...\`
-- \`Historically, the system evolved this way because ...\`
-- \`An X in this system is analogous to ...\`
-
-It is acceptable here to surface perspective, evaluation, and multiple interpretations.
-
-### Boundary Tests
-
-- If the document has numbered operational steps, it likely belongs in **How-to guide** or **Tutorial**.
-- If it lists facts without context, it likely belongs in **Reference**.
-- If it promises a concrete outcome the reader will build, it likely belongs in **Tutorial**.
-- If it exists mainly to solve an immediate operational problem, it belongs in **How-to guide**.
-
-## Cross-Linking Rules
-
-Quadrants should cooperate rather than compete. Each document should point to adjacent documentation types when a different reader need appears.
-
-| From | Cross-link pattern |
-|------|--------------------|
-| Tutorial | \`For the full API, see [Reference].\` |
-| How-to guide | \`To understand why, see [Explanation].\` |
-| Reference | \`For a guide on using this, see [How-to].\` |
-| Explanation | \`To get started, see [Tutorial].\` |
-
-Use cross-links when content would otherwise drift into the wrong quadrant. Link instead of absorbing the adjacent material.
-
-## Attribution
-
-This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the quadrant descriptions and distinction pages.
-
-Source material is licensed under **CC-BY-SA 4.0**.
-
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).`},{file:`references/diataxis-quality.md`,content:`# Diataxis Quality & Iteration
-
-How to assess and improve documentation quality using the Diátaxis framework.
-
-## Quality Checklist
-
-Run this checklist against every document created or updated during \`_docs-sync\`:
-
-### Quadrant Purity
-- [ ] Document serves exactly ONE Diátaxis quadrant
-- [ ] No mixed-mode content (tutorial narration + reference tables + explanation prose)
-- [ ] Language patterns match the quadrant (see diataxis-quadrants.md)
-- [ ] If content from another quadrant is needed, it's linked — not embedded
-
-### Structure & Completeness
-- [ ] All required template sections are present (see diataxis-templates.md)
-- [ ] No empty placeholder sections
-- [ ] Cross-references to related docs in other quadrants exist
-- [ ] \`type:\` frontmatter tag matches the actual content quadrant
-
-### Evidence & Accuracy
-- [ ] Claims are traceable to source files, config, or AI Kit tool output
-- [ ] Unknowns are marked \`[TODO]\`, not guessed
-- [ ] Team-intent items are marked \`[ASK USER]\`
-- [ ] No stale information (version numbers, deprecated APIs, removed features)
-
-### Audience Fit
-- [ ] Tutorial: assumes beginner, teaches one skill, shows visible results at each step
-- [ ] How-To: assumes competence, addresses specific task, no unnecessary explanation
-- [ ] Reference: factual, comprehensive, consistent structure, austere
-- [ ] Explanation: provides context, takes a position, connects concepts
-
-## Iterative Improvement Process
-
-Documentation improves incrementally. Don't try to perfect everything at once.
+Detailed workflow for acquiring and documenting project knowledge into \`docs/architecture/\`.
 
-### The Loop
+## Four-Phase Workflow
 
 \`\`\`
-1. Pick one document (or section, or paragraph)
-2. Classify it → which Diátaxis quadrant?
-3. Check → does it serve that quadrant well? (use checklist above)
-4. Make one improvement
-5. Repeat
+- [ ] Phase 1: Scan with AI Kit tools, read intent documents
+- [ ] Phase 2: Investigate each documentation area
+- [ ] Phase 3: Populate all seven docs in docs/architecture/
+- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items
 \`\`\`
 
-### When to Iterate
-
-| Trigger | Action |
-|---------|--------|
-| New doc created during \`_docs-sync\` | Run full checklist before committing |
-| Existing doc updated | Check only the modified sections |
-| Docs audit requested | Run checklist on all docs; prioritize by staleness |
-| Content feels wrong but works | Classify first — often the issue is quadrant mixing |
-
-### Organic Growth (from diataxis.fr)
-
-- Let documentation structure emerge from content needs — don't create empty four-section structures
-- A project with no tutorials doesn't need a \`tutorials/\` directory
-- Add documentation types as the project actually needs them
-- Perfect is the enemy of good — a correct how-to guide is better than no documentation
-
-### Scoring (optional, for audits)
-
-Per document, count how many checklist items pass out of the total applicable items.
-
-| Score | Quality | Action |
-|-------|---------|--------|
-| 100% | Excellent | No action needed |
-| 75-99% | Good | Fix during next relevant change |
-| 50-74% | Needs work | Schedule improvement |
-| <50% | Poor | Rewrite or split immediately |
-
----
-
-*Quality framework follows the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/diataxis-templates.md`,content:`# Diataxis Templates
-
-Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
-
-## Tutorial Template
-
-**Location**: \`docs/guides/tutorials/{topic}.md\`
-**Quadrant**: Tutorial (learning-oriented, practical)
-
-\`\`\`markdown
----
-type: tutorial
----
-
-# Tutorial: {Title — Start with a Verb Phrase}
-
-> **What you'll build/learn**: One sentence describing the concrete outcome.
-
-## Prerequisites
-
-- {Prerequisite 1} — [install guide](link)
-- {Prerequisite 2}
-
-## Steps
-
-### 1. {First Visible Result}
-
-{Concrete action with immediate, visible output.}
+### Phase 1: Scan and Read Intent
 
-\`\`\`bash
-{command or code}
 \`\`\`
-
-> **You'll see**: {expected output — always show what success looks like}
-
-### 2. {Build on Step 1}
-
-{Next concrete action that builds on the previous result.}
-
-> **You'll see**: {expected output}
-
-### 3. {Complete the Goal}
-
-{Final action that achieves the tutorial's stated outcome.}
-
-> **You'll see**: {final result matching the "What you'll build" promise}
-
-## What You Learned
-
-{One-paragraph summary of skills acquired. No new concepts here.}
-
-## Next Steps
-
-- [How to {related task}](../guides/{topic}.md) — apply what you learned
-- [{Topic} Reference](../../reference/{topic}.md) — full API details
-- [About {concept}](../../architecture/{topic}.md) — understand the design
+onboard({ path: "." })                           # Full codebase scan
+produce_knowledge({ path: "." })                  # Comprehensive analysis
+analyze({ aspect: "structure", path: "." })      # Project layout, packages, layers
+analyze({ aspect: "dependencies", path: "." })   # All dependencies + import graph
 \`\`\`
 
-### Tutorial Rules
-
-1. **Always show results** — every step must have a "You'll see" block
-2. **Linear path only** — no branching, no optional steps, no alternatives
-3. **No explanations** — if the reader asks "why?", link to an Explanation doc
-4. **Concrete outcome** — the tutorial must produce something visible (output, file, running service)
-5. **Minimum viable scope** — teach ONE thing; link to other tutorials for more
-
-## Explanation Template
-
-**Location**: \`docs/architecture/{topic}.md\` or \`docs/decisions/NNN-{title}.md\`
-**Quadrant**: Explanation (understanding-oriented, theoretical)
-
-\`\`\`markdown
----
-type: explanation
----
+Then read \`README\`, \`PRD\`, \`TRD\`, \`ROADMAP\`, \`SPEC\`, \`DESIGN\` files if they exist.
+Summarise the stated project intent before reading any source code.
 
-# About {Topic}
+### Phase 2: Investigate
 
-## Context
+Use Phase 1 tool outputs to answer questions for each of the seven documents. Run additional targeted tools:
 
-{Why this topic matters. What problem or question it addresses. Set the stage.}
+| Document | Investigation Tools |
+|----------|-------------------|
+| stack.md | \`analyze({ aspect: "dependencies", ... })\` → manifests, frameworks; \`analyze({ aspect: "structure", ... })\` → runtime signals |
+| structure.md | \`analyze({ aspect: "structure", ... })\` → file tree, packages; \`analyze({ aspect: "entry_points", ... })\` → entry points, key files |
+| design.md | \`analyze({ aspect: "structure", ... })\` → layers; \`analyze({ aspect: "patterns", ... })\` → design patterns; \`analyze({ aspect: "diagram", ... })\` → component diagrams |
+| conventions.md | \`analyze({ aspect: "patterns", ... })\` → naming, formatting; \`search("conventions")\` → detected conventions |
+| integrations.md | \`analyze({ aspect: "dependencies", ... })\` → external deps; \`search("API\\|database\\|auth\\|webhook")\` → integration points |
+| testing.md | \`analyze({ aspect: "patterns", ... })\` → test patterns; \`search("test framework")\` → test setup; \`test_run({})\` → test health |
+| concerns.md | \`audit({ path: "." })\` → health issues; \`dead_symbols({})\` → dead code; \`git_context({})\` → high-churn files |
 
-## Background
+### Phase 3: Populate Documents
 
-{Historical context, prior art, or constraints that shaped the current approach.}
+Create each document in \`docs/architecture/\` in this order:
 
-## How It Works
+1. **stack.md** — Language, runtime version, frameworks, production dependencies, dev tooling
+2. **structure.md** — Directory layout, entry points, key files, package organization
+3. **design.md** — Layers, architectural patterns, data flow, component boundaries
+4. **conventions.md** — Naming conventions, formatting rules, error handling patterns, import conventions
+5. **integrations.md** — External APIs, databases, auth providers, monitoring, CI/CD
+6. **testing.md** — Test frameworks, file organization, mocking strategy, coverage approach
+7. **concerns.md** — Tech debt, known bugs, security risks, performance bottlenecks, high-churn files
 
-{Discursive description — connections between components, data flow, design reasoning.}
-{NO step-by-step procedures — link to How-To guides for that.}
+Rules:
+- Use \`[TODO]\` for anything that cannot be determined from code
+- Use \`[ASK USER]\` where the right answer requires team intent
+- Include an "Evidence" section in each doc with file paths and tool receipts
 
-## Design Decisions
+### Phase 4: Validate, Repair, Verify
 
-{Why this approach was chosen over alternatives.}
-{Link to ADRs where they exist: [ADR-NNN](../decisions/NNN-{title}.md)}
+Run this mandatory validation loop before finalizing:
 
-## Trade-Offs
+1. For each non-trivial claim, confirm at least one evidence reference exists
+2. If any required section is missing or unsupported → fix and re-validate
+3. Repeat until all seven docs pass
 
-| Gained | Sacrificed |
-|--------|-----------|
-| {benefit} | {cost} |
+Validation pass criteria:
+- No unsupported claims
+- No empty required sections
+- Unknowns use \`[TODO]\` rather than assumptions
+- Team-intent gaps are explicitly marked \`[ASK USER]\`
 
-## Related
+Then present a summary, list every \`[ASK USER]\` item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.
 
-- [How to {task}](../guides/{topic}.md) — practical application
-- [{API} Reference](../reference/{topic}.md) — technical details
-- [Tutorial: {topic}](../guides/tutorials/{topic}.md) — hands-on introduction
-\`\`\`
+## Focus Area Mode
 
-### Explanation Rules
+If the user specifies a focus area (e.g., "architecture only" or "testing and concerns"):
 
-1. **Take a position** — good explanation has perspective and opinion
-2. **Connect concepts** — show relationships, not isolated facts
-3. **No procedures** — if you write "Step 1:", move it to a How-To doc
-4. **Bounded scope** — explain ONE concept/decision/pattern per document
-5. **Link to evidence** — reference ADRs, code, or analysis tool output
+1. Always run Phase 1 in full
+2. Fully complete focus-area documents first
+3. For non-focus documents, keep required sections present and mark unknowns as \`[TODO]\`
+4. Still run the Phase 4 validation loop on all seven documents
 
----
+## Templates
 
-*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/flow-artifacts-guide.md`,content:'# Flow Artifacts Guide\n\n## What Are Flow Artifacts\n\nFlows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.\n\nUse artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.\n\n## How to Discover Artifacts\n\n```text\nflow({ action: \'status\' })                        # Get artifactsPath\nfind({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files\ndigest({ sources: [                                # Compress into working context\n  { path: "<found-artifact-1>" },\n  { path: "<found-artifact-2>" },\n  ...\n]})\n```\n\nRead every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.\n\n## Artifact Catalog\n\n| Artifact | Flow | Contains |\n|---|---|---|\n| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |\n| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |\n| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |\n| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |\n| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |\n| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |\n| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |\n\n## Artifact-to-Documentation Mapping\n\n| Artifact | Contains | Documentation Target | Action |\n|---|---|---|---|\n| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |\n| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |\n| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |\n| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |\n| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |\n| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |\n| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |\n| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |\n| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |\n\n## Reading Strategy\n\nRead every artifact `find()` returns. Triage by content type:\n\n| Content Signal | Documentation Value | Action |\n|---|---|---|\n| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |\n| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |\n| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |\n| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |\n\nSkip artifacts that only repeat completed work with no insights beyond the code diff.\n\n> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.\n\n## What Not to Document\n\n| Avoid | Do Instead |\n|---|---|\n| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |\n| Documenting every task or progress update | Keep only durable insights that help future readers |\n| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |'},{file:`references/project-knowledge-gotchas.md`,content:'# Project Knowledge — Gotchas\n\nCommon pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).\n\n## Environment Gotchas\n\n**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.\n\n**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.\n\n**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don\'t map directly to the filesystem. Map aliases to real paths before documenting structure.\n\n**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.\n\n**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.\n\n**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.\n\n**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.\n\n**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.\n\n## Anti-Pattern Table\n\n| ❌ Don\'t | ✅ Do instead |\n|---------|--------------|\n| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |\n| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what\'s actually there |\n| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |\n| Document `dist/` or `build/` naming patterns as conventions | Source files only |\n| Assume README describes current architecture | Cross-reference with actual file structure via `analyze({ aspect: "structure", ... })` |\n| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |'},{file:`references/project-knowledge-templates.md`,content:`# Project Knowledge Templates
+### Project Knowledge Templates
 
 Templates for the seven project knowledge documents in \`docs/architecture/\`. Use these to ensure consistent structure across projects.
 
@@ -931,253 +503,81 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 - \`audit()\` output — health issues
 - \`dead_symbols({})\` output — dead code
 - \`git_context({})\` output — high-churn files
-\`\`\``},{file:`references/project-knowledge-workflow.md`,content:`# Project Knowledge — Workflow
+\`\`\`
 
-Detailed workflow for acquiring and documenting project knowledge into \`docs/architecture/\`.
+## Gotchas & Anti-Patterns
 
-## Four-Phase Workflow
+### Project Knowledge — Gotchas
 
-\`\`\`
-- [ ] Phase 1: Scan with AI Kit tools, read intent documents
-- [ ] Phase 2: Investigate each documentation area
-- [ ] Phase 3: Populate all seven docs in docs/architecture/
-- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items
-\`\`\`
+Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
 
-### Phase 1: Scan and Read Intent
+## Environment Gotchas
 
-\`\`\`
-onboard({ path: "." })                           # Full codebase scan
-produce_knowledge({ path: "." })                  # Comprehensive analysis
-analyze({ aspect: "structure", path: "." })      # Project layout, packages, layers
-analyze({ aspect: "dependencies", path: "." })   # All dependencies + import graph
-\`\`\`
+**Monorepos:** Root \`package.json\` may have no source — check for \`workspaces\`, \`packages/\`, or \`apps/\` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
 
-Then read \`README\`, \`PRD\`, \`TRD\`, \`ROADMAP\`, \`SPEC\`, \`DESIGN\` files if they exist.
-Summarise the stated project intent before reading any source code.
+**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
 
-### Phase 2: Investigate
+**TypeScript path aliases:** \`tsconfig.json\` \`paths\` config means imports like \`@/foo\` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
 
-Use Phase 1 tool outputs to answer questions for each of the seven documents. Run additional targeted tools:
+**Generated/compiled output:** Never document patterns from \`dist/\`, \`build/\`, \`generated/\`, \`.next/\`, \`out/\`, or \`__pycache__/\`. These are artefacts — document source conventions only.
 
-| Document | Investigation Tools |
-|----------|-------------------|
-| stack.md | \`analyze({ aspect: "dependencies", ... })\` → manifests, frameworks; \`analyze({ aspect: "structure", ... })\` → runtime signals |
-| structure.md | \`analyze({ aspect: "structure", ... })\` → file tree, packages; \`analyze({ aspect: "entry_points", ... })\` → entry points, key files |
-| design.md | \`analyze({ aspect: "structure", ... })\` → layers; \`analyze({ aspect: "patterns", ... })\` → design patterns; \`analyze({ aspect: "diagram", ... })\` → component diagrams |
-| conventions.md | \`analyze({ aspect: "patterns", ... })\` → naming, formatting; \`search("conventions")\` → detected conventions |
-| integrations.md | \`analyze({ aspect: "dependencies", ... })\` → external deps; \`search("API\\|database\\|auth\\|webhook")\` → integration points |
-| testing.md | \`analyze({ aspect: "patterns", ... })\` → test patterns; \`search("test framework")\` → test setup; \`test_run({})\` → test health |
-| concerns.md | \`audit({ path: "." })\` → health issues; \`dead_symbols({})\` → dead code; \`git_context({})\` → high-churn files |
+**\`.env.example\` reveals required config:** Secrets are never committed. Read \`.env.example\`, \`.env.template\`, or \`.env.sample\` to discover required environment variables.
 
-### Phase 3: Populate Documents
+**\`devDependencies\` ≠ production stack:** Only \`dependencies\` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in \`stack.md\`.
 
-Create each document in \`docs/architecture/\` in this order:
+**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in \`concerns.md\`.
 
-1. **stack.md** — Language, runtime version, frameworks, production dependencies, dev tooling
-2. **structure.md** — Directory layout, entry points, key files, package organization
-3. **design.md** — Layers, architectural patterns, data flow, component boundaries
-4. **conventions.md** — Naming conventions, formatting rules, error handling patterns, import conventions
-5. **integrations.md** — External APIs, databases, auth providers, monitoring, CI/CD
-6. **testing.md** — Test frameworks, file organization, mocking strategy, coverage approach
-7. **concerns.md** — Tech debt, known bugs, security risks, performance bottlenecks, high-churn files
-
-Rules:
-- Use \`[TODO]\` for anything that cannot be determined from code
-- Use \`[ASK USER]\` where the right answer requires team intent
-- Include an "Evidence" section in each doc with file paths and tool receipts
-
-### Phase 4: Validate, Repair, Verify
-
-Run this mandatory validation loop before finalizing:
-
-1. For each non-trivial claim, confirm at least one evidence reference exists
-2. If any required section is missing or unsupported → fix and re-validate
-3. Repeat until all seven docs pass
-
-Validation pass criteria:
-- No unsupported claims
-- No empty required sections
-- Unknowns use \`[TODO]\` rather than assumptions
-- Team-intent gaps are explicitly marked \`[ASK USER]\`
-
-Then present a summary, list every \`[ASK USER]\` item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.
-
-## Focus Area Mode
-
-If the user specifies a focus area (e.g., "architecture only" or "testing and concerns"):
-
-1. Always run Phase 1 in full
-2. Fully complete focus-area documents first
-3. For non-focus documents, keep required sections present and mark unknowns as \`[TODO]\`
-4. Still run the Phase 4 validation loop on all seven documents`},{file:`SKILL.md`,content:`---
-name: docs
-description: "Living documentation management — Diátaxis framework, docs/ convention, create/update rules, staleness detection, integration with adr-skill and c4-architecture."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: on-demand
-  inputs: [code-changes, flow-artifacts, architecture]
-  outputs: [documentation]
-  relatedSkills: [adr-skill, c4-architecture]
-  internal: true
----
-
-# Docs — Living Documentation Skill
-
-Manage the \`docs/\` folder as a single source of truth for project documentation. This skill runs during the mandatory \`_docs-sync\` epilogue step of every flow, ensuring documentation stays in sync with code changes.
-
-## Principles
-
-1. **Living, not legacy** — Documentation is updated as code changes, never as a separate "docs sprint"
-2. **One source of truth** — Never duplicate what's in code comments, READMEs, or inline JSDoc
-3. **Diátaxis framework** — Organize docs into four categories using the two-question compass:
-  - **Q1**: Is the reader trying to **do** something (action) or **understand** something (cognition)?
-  - **Q2**: Is the reader **learning** (study) or **working** (work)?
-  - Action+Study → Tutorial · Action+Work → How-to · Cognition+Work → Reference · Cognition+Study → Explanation
-  - See [references/diataxis-compass.md](references/diataxis-compass.md) for the full classification system
-4. **Minimal but complete** — Create docs only when they add value beyond what code communicates
-5. **Delegate to specialists** — Architecture diagrams → \`c4-architecture\` skill. Decision records → \`adr-skill\`
-
-## Documentation Modes
-
-This skill operates in two modes, often combined:
-
-### Source-Only Mode
-Generate documentation from code analysis alone. Used when:
-- Bootstrapping \`docs/\` for the first time (\`produce_knowledge\`, \`analyze_*\` tools)
-- Running outside a flow context (manual documentation refresh)
-- Flow produced no artifacts (auto-skipped design step)
-
-### Flow-Aware Mode (Primary)
-Generate documentation from code changes **plus** flow artifacts. This is the primary mode during \`_docs-sync\` because every completed flow produces structured artifacts containing design decisions, requirements, and verification results.
-
-Flow artifacts are the most valuable documentation input — they capture the *why* behind changes (decisions, constraints, trade-offs, risks) while code only shows the *what*.
-
-**Artifact reading sequence:**
-\`\`\`
-flow({ action: 'status' })                        # Get artifactsPath
-find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all artifacts
-digest({ sources: [                                # Compress into working context
-  { path: "<found-artifact-1>" },
-  { path: "<found-artifact-2>" },
-  ...
-]})
-\`\`\`
-
-See [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md) for the artifact catalog and artifact-to-documentation mapping.
-
-## AI Kit Tools for Documentation
-
-Use these existing AI Kit tools to generate documentation content — never write docs from scratch when a tool can provide the foundation:
-
-| Documentation Task | AI Kit Tool | What It Provides |
-|---|---|---|
-| Project overview | \`produce_knowledge({ path: "." })\` | Comprehensive analysis: structure, patterns, dependencies → \`docs/README.md\` |
-| Architecture overview | \`analyze({ aspect: "structure", path: "." })\` | File tree, package layout, layer organization → \`docs/architecture/overview.md\` |
-| Architecture diagrams | \`analyze({ aspect: "diagram", path: "." })\` | Mermaid diagrams of component relationships → \`docs/architecture/\` |
-| Dependency map | \`analyze({ aspect: "dependencies", path: "." })\` | Import graph, cross-package edges → \`docs/architecture/overview.md\` dependencies section |
-| Component analysis | \`analyze({ aspect: "symbols", path: "src/component" })\` | Exports, classes, interfaces → \`docs/architecture/components/{name}.md\` |
-| Entry points / API surface | \`analyze({ aspect: "entry_points", path: "." })\` | CLI bins, route handlers, main exports → \`docs/reference/api.md\` |
-| Code patterns | \`analyze({ aspect: "patterns", path: "." })\` | Design patterns, conventions → \`docs/architecture/overview.md\` patterns section |
-| Impact analysis | \`blast_radius({ changed_files: [...] })\` | What's affected by changes → targeted doc updates |
-| Change detection | \`git_context({})\` | Recent changes, diff summary → determine which docs need updating |
-| Module graph | \`graph({ action: 'neighbors', node_id })\` | Who-imports-whom, cross-package dependencies → architecture diagrams |
-| Full audit | \`audit({ path: "." })\` | Structure + deps + patterns + health + dead symbols → comprehensive docs refresh |
+**High-churn files = fragile areas:** Files appearing most in recent \`git_context({})\` output have the highest modification rate and likely hidden complexity. Always note them in \`concerns.md\`.
 
-### Tool-First Workflow
-
-When creating documentation, always start with tool output, then enhance with human context:
-
-\`\`\`
-1. Run the relevant analysis tool(s)
-2. Use the output as the doc's foundation
-3. Add: purpose/motivation (why, not just what)
-4. Add: decision context (link to ADRs)
-5. Add: cross-references to related docs
-6. Remove: implementation details visible in code
-\`\`\`
+## Anti-Pattern Table
 
-### Present Tool Block Reference
+| ❌ Don't | ✅ Do instead |
+|---------|--------------|
+| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
+| "This is a Next.js project" (without checking \`package.json\`) | Check \`dependencies\` first. State what's actually there |
+| Guess the database from a variable name like \`dbUrl\` | Check manifest for \`pg\`, \`mysql2\`, \`mongoose\`, \`prisma\`, etc. |
+| Document \`dist/\` or \`build/\` naming patterns as conventions | Source files only |
+| Assume README describes current architecture | Cross-reference with actual file structure via \`analyze({ aspect: "structure", ... })\` |
+| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in \`concerns.md\` |
 
-${e?.bySkill?.docs||``}
+## Acquisition Workflow
 
-## \`docs/\` Convention
+Produces seven populated documents in \`docs/architecture/\` covering everything needed to work effectively on the project — stack, structure, design, conventions, integrations, testing, and concerns.
 
-\`\`\`
-docs/
-├── README.md                      ← Project overview + docs index (always exists)
-├── architecture/
-│   ├── overview.md                ← C4 context + container diagrams (c4-architecture skill)
-│   ├── stack.md                   ← Language, runtime, frameworks, all dependencies
-│   ├── structure.md               ← Directory layout, entry points, key files
-│   ├── design.md                  ← Layers, patterns, data flow
-│   ├── conventions.md             ← Naming, formatting, error handling, imports
-│   ├── integrations.md            ← External APIs, databases, auth, monitoring
-│   ├── testing.md                 ← Frameworks, file organization, mocking strategy
-│   ├── concerns.md                ← Tech debt, bugs, security risks, perf bottlenecks
-│   └── components/
-│       └── {component-name}.md    ← Per-component technical docs
-├── decisions/                     ← Architecture Decision Records (adr-skill)
-│   ├── index.md                   ← ADR log / table of contents
-│   └── NNN-{title}.md             ← Individual ADRs
-├── guides/
-│   ├── tutorials/                 ← Learning-oriented lessons (Diátaxis: Tutorial)
-│   │   └── {topic}.md
-│   └── {topic}.md                 ← How-to guides for common tasks (Diátaxis: How-To)
-└── reference/
-    ├── api.md                     ← API reference (endpoints, schemas, auth)
-    └── configuration.md           ← Configuration options and environment variables
-\`\`\`
+**Only document what is verifiable from files or tool output — never infer or assume.**
 
-### Directory Purposes
+### Output Contract
 
-| Directory | Diátaxis Quadrant | What Goes Here | When to Create/Update |
-|-----------|-------------------|----------------|----------------------|
-| \`architecture/\` | Explanation + Reference | C4 diagrams, project knowledge (stack, structure, design, conventions, integrations, testing, concerns), component docs | Initial onboarding, new component, structural change, architecture decision |
-| \`decisions/\` | Explanation | ADRs — why decisions were made | Non-trivial technical decision (see adr-skill triggers) |
-| \`guides/\` | How-To | Step-by-step instructions for tasks | New workflow, complex setup, common operations |
-| \`guides/tutorials/\` | Tutorial | Learning-oriented guided lessons with concrete outcomes | New technology/feature adoption, onboarding new developers |
-| \`reference/\` | Reference | API docs, config options, data schemas | API change, new config option, schema modification |
+All of the following must be true before finishing:
 
-## Change-to-Doc Mapping
+1. All seven files exist in \`docs/architecture/\`: \`stack.md\`, \`structure.md\`, \`design.md\`, \`conventions.md\`, \`integrations.md\`, \`testing.md\`, \`concerns.md\`
+2. Every claim is traceable to source files, config, or AI Kit tool output
+3. Unknowns are marked \`[TODO]\`; intent-dependent decisions are marked \`[ASK USER]\`
+4. Every document includes a short "Evidence" section with file paths or tool receipts
+5. Final response includes numbered \`[ASK USER]\` questions and intent-vs-reality divergences
 
-Use this decision tree to determine what documentation action to take after a flow completes:
+### Documents
 
-\`\`\`
-What changed?
-├── New component/module/package
-│   ├── Creates public API? → Create docs/architecture/components/{name}.md + update reference/api.md
-│   └── Internal only? → Update docs/architecture/overview.md (component list)
-├── API change (new endpoint, changed contract, new config)
-│   └── Update docs/reference/api.md or docs/reference/configuration.md
-├── Architecture/infrastructure decision
-│   └── Delegate to adr-skill → creates/updates docs/decisions/NNN-{title}.md
-├── Structural/architecture change
-│   └── Delegate to c4-architecture skill → updates docs/architecture/overview.md
-├── New developer workflow (build, deploy, test pattern)
-│   └── Create or update docs/guides/{topic}.md
-├── Bug fix
-│   ├── Reveals missing docs? → Create the missing doc
-│   └── Straightforward fix? → No docs update needed
-└── Dependency update / refactor / cleanup
-    └── No docs update needed (unless public API changed)
-\`\`\`
+| Document | Covers | Primary Tools |
+|----------|--------|---------------|
+| \`stack.md\` | Language, runtime, frameworks, dependencies, dev tooling | \`analyze({ aspect: "dependencies", ... })\`, \`analyze({ aspect: "structure", ... })\` |
+| \`structure.md\` | Directory layout, entry points, key files, packages | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "entry_points", ... })\` |
+| \`design.md\` | Layers, patterns, data flow, component boundaries | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "patterns", ... })\`, \`analyze({ aspect: "diagram", ... })\` |
+| \`conventions.md\` | Naming, formatting, error handling, import conventions | \`analyze({ aspect: "patterns", ... })\`, \`search("conventions")\` |
+| \`integrations.md\` | External APIs, databases, auth, monitoring, CI/CD | \`analyze({ aspect: "dependencies", ... })\`, \`search("API\\|database\\|auth")\` |
+| \`testing.md\` | Test frameworks, file organization, mocking, coverage | \`analyze({ aspect: "patterns", ... })\`, \`test_run({})\`, \`search("test")\` |
+| \`concerns.md\` | Tech debt, bugs, security risks, perf, high-churn files | \`audit()\`, \`dead_symbols()\`, \`git_context()\` |
 
-### Classify by Diátaxis Quadrant
+Use [references/project-knowledge-reference.md](references/project-knowledge-reference.md) for the standard template of each document.
 
-After determining the documentation action, classify the target document's quadrant:
+### Workflow & References
 
-| Action → Cognition? | Study → Work? | Quadrant | Target Directory |
-|---------------------|---------------|----------|------------------|
-| Action (doing) | Study (learning) | **Tutorial** | \`guides/tutorials/\` |
-| Action (doing) | Work (applying) | **How-To** | \`guides/\` |
-| Cognition (understanding) | Work (using) | **Reference** | \`reference/\` |
-| Cognition (understanding) | Study (grasping) | **Explanation** | \`architecture/\`, \`decisions/\` |
+Follow the four-phase workflow: **Scan → Investigate → Populate → Validate**.
 
-Use the [Diátaxis Compass](references/diataxis-compass.md) for edge cases and ambiguous content.
+- [references/project-knowledge-reference.md](references/project-knowledge-reference.md) — Full 4-phase workflow, investigation tools per document, population rules, focus area mode
+- [references/project-knowledge-reference.md](references/project-knowledge-reference.md) — Environment gotchas and anti-pattern table`},{file:`references/doc-templates.md`,content:`# Document Templates Reference
 
-## Templates
+Use depth-specific templates. Do not hand the model a generic instruction like "document this" without the correct structure for the target document type.
 
 ### Component Doc Template (\`docs/architecture/components/{name}.md\`)
 
@@ -1195,11 +595,59 @@ One-paragraph description of what this component does and why it exists.
 ## Public API
 Brief description of the component's public interface.
 
+## Integration Contracts
+- **Incoming**: {caller/component} → {contract or payload}
+- **Outgoing**: {dependency/component} ← {contract or payload}
+
 ## Design Decisions
 - Link to relevant ADRs: [ADR-NNN](../../decisions/NNN-{title}.md)
 
 ## Data Flow
 How data enters, transforms through, and exits this component.
+
+## Sequence Diagram
+\`\`\`mermaid
+sequenceDiagram
+  participant Caller
+  participant Component
+  participant Dependency
+  Caller->>Component: {request or event}
+  Component->>Dependency: {integration contract}
+  Dependency-->>Component: {response}
+  Component-->>Caller: {result}
+\`\`\`
+
+## Error Paths & Failure Modes
+- {failure mode} → {observable symptom} → {recovery or fallback}
+\`\`\`
+
+### Tutorial Template (\`docs/guides/tutorials/{topic}.md\`)
+
+\`\`\`markdown
+# Tutorial: {Outcome}
+
+## Prerequisite Check
+- Verify {tool, account, or repo state}
+- Expected output: {what confirms the reader can start}
+
+## Step 1: {First milestone}
+Explain the goal of this step.
+
+\`\`\`{language}
+{code example}
+\`\`\`
+
+Expected output:
+\`\`\`text
+{visible result}
+\`\`\`
+
+## Step 2: {Next milestone}
+Repeat the pattern: explain, show code, show expected output.
+
+## Common Mistakes
+- {mistake} — {how to fix it}
+- {mistake} — {how to fix it}
 \`\`\`
 
 ### Guide Template (\`docs/guides/{topic}.md\`)
@@ -1208,18 +656,27 @@ How data enters, transforms through, and exits this component.
 # How to {Task}
 
 ## Prerequisites
-What you need before starting.
+- Required access, tools, and starting state.
+
+## Step 1: {Action}
+Describe the action.
+
+### Verify
+- Expected: {what success looks like}
+- Actual if broken: {what usually differs}
 
-## Steps
-1. Step one
-2. Step two
-3. Step three
+## Step 2: {Action}
+Describe the next action.
+
+### Verify
+- Expected: {what success looks like}
+- Actual if broken: {what usually differs}
 
 ## Verification
-How to confirm it worked.
+How to confirm the whole task worked end to end.
 
 ## Troubleshooting
-Common issues and solutions.
+Common issues, likely causes, and fixes.
 \`\`\`
 
 ### Decision Index Template (\`docs/decisions/index.md\`)
@@ -1246,163 +703,31 @@ The **Source** column links to the flow artifact (typically \`design.md\` or \`d
 ## Overview
 Brief description of what this reference covers.
 
-## {Section}
-
-| Item | Type | Default | Description |
-|------|------|---------|-------------|
-| ... | ... | ... | ... |
-\`\`\`
-
-> **Tutorial and Explanation templates**: For the remaining two Diátaxis quadrants, see [references/diataxis-templates.md](references/diataxis-templates.md).
-
-## Integration with Other Skills
-
-### \`adr-skill\` Integration
-- All ADRs live in \`docs/decisions/\`
-- When the docs-sync step detects an architecture decision was made during the flow, delegate to \`adr-skill\`
-- After \`adr-skill\` creates/updates an ADR, update \`docs/decisions/index.md\`
-- Include the Source column linking to the flow artifact where the decision was designed.
-- Cross-reference ADRs from component docs where relevant
-
-### \`c4-architecture\` Integration
-- Architecture diagrams live in \`docs/architecture/\`
-- When the docs-sync step detects structural changes (new packages, changed boundaries), delegate to \`c4-architecture\`
-- Use Mermaid format for docs files (not HTML) — markdown renders in GitHub
-- Reference diagrams from component docs
-
-### Mermaid Syntax Rules
-
-When generating Mermaid diagrams in documentation:
-
-- **Quote node labels containing special characters** — Names with \`@\`, \`/\`, or other special characters must be wrapped in double quotes inside square brackets: \`subgraph Commons["@scope/package-name"]\`, \`NodeId["@org/lib"]\`
-- **Quote subgraph titles with special characters** — \`subgraph Title["@scope/name"]\` not \`subgraph @scope/name\`
-- Node IDs (aliases) must not contain special characters — use plain alphanumeric IDs and put the display name in \`["..."]\`
-
-## Project Knowledge Acquisition
-
-Produces seven populated documents in \`docs/architecture/\` covering everything needed to work effectively on the project — stack, structure, design, conventions, integrations, testing, and concerns.
-
-**Only document what is verifiable from files or tool output — never infer or assume.**
-
-### Output Contract
-
-All of the following must be true before finishing:
-
-1. All seven files exist in \`docs/architecture/\`: \`stack.md\`, \`structure.md\`, \`design.md\`, \`conventions.md\`, \`integrations.md\`, \`testing.md\`, \`concerns.md\`
-2. Every claim is traceable to source files, config, or AI Kit tool output
-3. Unknowns are marked \`[TODO]\`; intent-dependent decisions are marked \`[ASK USER]\`
-4. Every document includes a short "Evidence" section with file paths or tool receipts
-5. Final response includes numbered \`[ASK USER]\` questions and intent-vs-reality divergences
-
-### Documents
-
-| Document | Covers | Primary Tools |
-|----------|--------|---------------|
-| \`stack.md\` | Language, runtime, frameworks, dependencies, dev tooling | \`analyze({ aspect: "dependencies", ... })\`, \`analyze({ aspect: "structure", ... })\` |
-| \`structure.md\` | Directory layout, entry points, key files, packages | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "entry_points", ... })\` |
-| \`design.md\` | Layers, patterns, data flow, component boundaries | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "patterns", ... })\`, \`analyze({ aspect: "diagram", ... })\` |
-| \`conventions.md\` | Naming, formatting, error handling, import conventions | \`analyze({ aspect: "patterns", ... })\`, \`search("conventions")\` |
-| \`integrations.md\` | External APIs, databases, auth, monitoring, CI/CD | \`analyze({ aspect: "dependencies", ... })\`, \`search("API\\|database\\|auth")\` |
-| \`testing.md\` | Test frameworks, file organization, mocking, coverage | \`analyze({ aspect: "patterns", ... })\`, \`test_run({})\`, \`search("test")\` |
-| \`concerns.md\` | Tech debt, bugs, security risks, perf, high-churn files | \`audit()\`, \`dead_symbols()\`, \`git_context()\` |
-
-Use [references/project-knowledge-templates.md](references/project-knowledge-templates.md) for the standard template of each document.
-
-### Workflow & References
-
-Follow the four-phase workflow: **Scan → Investigate → Populate → Validate**.
-
-- [references/project-knowledge-workflow.md](references/project-knowledge-workflow.md) — Full 4-phase workflow, investigation tools per document, population rules, focus area mode
-- [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) — Environment gotchas and anti-pattern table
-
-## Architecture Blueprint Generation
-
-When bootstrapping \`docs/\` for the first time or refreshing architecture documentation, generate a comprehensive architecture blueprint. This replaces manual documentation with tool-driven analysis.
-
-### Blueprint Workflow
-
-\`\`\`
-Step 1: Detect & Analyze
-  analyze({ aspect: "structure", path: "." })        → project layout, packages, layers
-  analyze({ aspect: "patterns", path: "." })         → conventions, design patterns
-  analyze({ aspect: "entry_points", path: "." })     → API surface, CLI entry points
-
-Step 2: Map Dependencies
-  analyze({ aspect: "dependencies", path: "." })     → import graph, cross-package edges
-  graph({ action: 'find_nodes', name_pattern: '*' })   → module graph nodes
-  graph({ action: 'neighbors', node_id: '...' })       → dependency directions
-
-Step 3: Visualize
-  analyze({ aspect: "diagram", path: "." })          → Mermaid architecture diagrams
-  Delegate to c4-architecture skill                    → C4 context/container/component views
-
-Step 4: Synthesize
-  produce_knowledge({ path: "." })                    → comprehensive analysis
-  Combine outputs into docs/ structure
-\`\`\`
-
-### Blueprint Sections
-
-The architecture blueprint should cover these areas (adapted from the Architecture Blueprint Generator pattern):
-
-#### 1. Architecture Detection & Analysis
-- **Auto-detect**: Project type, framework, architectural pattern (Clean Architecture, Microservices, Layered, etc.)
-- **Tools**: \`analyze({ aspect: "structure", ... })\` → folder organization, \`analyze({ aspect: "patterns", ... })\` → framework detection, \`analyze({ aspect: "dependencies", ... })\` → dependency flow
-- **Output**: \`docs/architecture/overview.md\` header section
-
-#### 2. Architectural Overview
-- Guiding principles from code structure
-- Architectural boundaries and enforcement mechanisms
-- Hybrid patterns or adaptations
-- **Tools**: \`produce_knowledge\` + \`analyze({ aspect: "structure", ... })\`
-- **Output**: \`docs/architecture/overview.md\` main body
-
-#### 3. Architecture Visualization
-- High-level subsystem diagram
-- Component interaction diagrams
-- Data flow diagrams
-- **Tools**: \`analyze({ aspect: "diagram", ... })\` + \`c4-architecture\` skill
-- **Output**: \`docs/architecture/overview.md\` diagrams + \`docs/architecture/diagrams/\`
-
-#### 4. Core Architectural Components
-For each major component:
-- Purpose and responsibility
-- Internal structure
-- Key abstractions
-- Interaction patterns
-- **Tools**: \`analyze({ aspect: "symbols", path: "component/" })\` + \`compact({ path, query: "exports" })\`
-- **Output**: \`docs/architecture/components/{name}.md\`
-
-#### 5. Layers & Dependencies
-- Layer structure as implemented
-- Dependency rules between layers
-- Abstraction mechanisms for separation
-- Circular dependencies or violations
-- **Tools**: \`analyze({ aspect: "dependencies", ... })\` + \`graph({ action: 'neighbors' })\`
-- **Output**: \`docs/architecture/overview.md\` layers section
-
-#### 6. Cross-Cutting Concerns
-Document implementation patterns for:
-- Error handling & resilience
-- Logging & observability
-- Validation patterns
-- Configuration management
-- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "error handling" })\`
-- **Output**: \`docs/architecture/overview.md\` cross-cutting section
-
-#### 7. Testing Architecture
-- Test framework and strategy
-- Test boundary patterns (unit, integration, e2e)
-- Test file conventions
-- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "test" })\`
-- **Output**: \`docs/guides/testing.md\`
+## Public API
 
-#### 8. Extension & Evolution
-- How to add features while preserving architecture
-- Component creation patterns
-- Integration patterns for external systems
-- **Tools**: \`analyze({ aspect: "entry_points", ... })\` + \`analyze({ aspect: "patterns", ... })\`
-- **Output**: \`docs/guides/contributing.md\` or \`docs/architecture/overview.md\` extension section
+### {Function or Endpoint}
+- **Signature**: \`{full signature with parameter and return types}\`
+- **Parameters**:
+  - \`{name}\` (\`{type}\`) — {purpose}
+- **Returns**: \`{type}\` — {meaning}
+
+#### Usage Example
+\`\`\`{language}
+{example}
+\`\`\`
+
+#### Error Codes
+
+- | Code | Condition | Resolution |
+- |------|-----------|------------|
+- | ... | ... | ... |
+
+#### Edge Cases
+- {edge case}
+- {edge case}
+\`\`\`
+
+> **Explanation templates**: For the remaining conceptual quadrant, see [references/diataxis-reference.md](references/diataxis-reference.md).`},{file:`references/flow-artifacts-guide.md`,content:'# Flow Artifacts Guide\n\n## What Are Flow Artifacts\n\nFlows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.\n\nUse artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.\n\n## How to Discover Artifacts\n\n```text\nflow({ action: \'status\' })                        # Get artifactsPath\nfind({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files\ndigest({ sources: [                                # Compress into working context\n  { path: "<found-artifact-1>" },\n  { path: "<found-artifact-2>" },\n  ...\n]})\n```\n\nRead every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.\n\n## Artifact Catalog\n\n| Artifact | Flow | Contains |\n|---|---|---|\n| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |\n| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |\n| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |\n| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |\n| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |\n| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |\n| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |\n\n## Artifact-to-Documentation Mapping\n\n| Artifact | Contains | Documentation Target | Action |\n|---|---|---|---|\n| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |\n| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |\n| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |\n| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |\n| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |\n| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |\n| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |\n| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |\n| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |\n\n## Reading Strategy\n\nRead every artifact `find()` returns. Triage by content type:\n\n| Content Signal | Documentation Value | Action |\n|---|---|---|\n| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |\n| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |\n| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |\n| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |\n\nSkip artifacts that only repeat completed work with no insights beyond the code diff.\n\n> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.\n\n## What Not to Document\n\n| Avoid | Do Instead |\n|---|---|\n| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |\n| Documenting every task or progress update | Keep only durable insights that help future readers |\n| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |'},{file:`references/tour-generation.md`,content:`# Tour Generation Reference
 
 ## Guided Tour Generation
 
@@ -1410,36 +735,37 @@ Generate dependency-ordered codebase walkthroughs that teach the system through
 
 ### Algorithm
 
-1. \`analyze({ aspect: "entry_points", path: "." })\` — find tour start points (0 in-degree modules)
-2. \`graph({ action: "find_nodes", name_pattern: "src" })\` — get all module nodes
-3. \`graph({ action: "neighbors", node_id: "<entry>", direction: "outgoing" })\` — build dependency graph
+1. \`analyze({ aspect: "entry_points", path: "." })\` — find likely tour starting points
+2. \`graph({ action: "find_nodes", name_pattern: "src" })\` — get relevant module nodes
+3. \`graph({ action: "neighbors", node_id: "<entry>", direction: "outgoing" })\` — build the local dependency view
 4. Topological sort on import edges — determine reading order
-5. Group by depth/layer — create logical tour steps
-6. Batch ≤ 3 related files per step — keep each step focused
-7. Append concept/cross-cutting nodes as final steps
+5. Group by depth or layer — create logical steps
+6. Batch up to three closely related files per step — keep each step focused
+7. End with cross-cutting concepts or follow-up links when needed
 
 ### Tour Step Format
 
-Each step in a tour:
+Each prose step in a markdown tour should name the focus, explain what the reader will understand, and link to the relevant files.
 
 \`\`\`markdown
-## Step {order}: {title}
+## {Step Title}
 
-{description — what the reader will understand after this step}
+{What the reader should understand after this step}
 
 **Files:**
 - \`{file1}\` — {role}
 - \`{file2}\` — {role}
 
-**Key concepts:** {comma-separated concepts introduced here}
-**Depends on:** Steps {list of prerequisite step numbers}
+**Notes:**
+- {important concept or callout}
+- {follow-up detail or caution}
 \`\`\`
 
 ### Tour Generation Workflow
 
-1. Run the algorithm above to produce ordered step list
+1. Run the algorithm above to produce an ordered step list
 2. For each step, use \`compact({ path, query: "purpose and public API" })\` to extract key info
-3. Write tour as \`docs/tours/{topic}.md\`
+3. Write the tour as \`docs/tours/{topic}.md\`
 4. Generate \`docs/tours/index.md\` linking all tours with descriptions
 
 ### Tour Index Template (\`docs/tours/index.md\`)
@@ -1447,7 +773,7 @@ Each step in a tour:
 \`\`\`markdown
 # Codebase Tours
 
-Guided walkthroughs ordered by dependency — read them in sequence to understand the system.
+Guided walkthroughs ordered for understanding.
 
 | Tour | Description | Steps | Audience |
 |------|-------------|-------|----------|
@@ -1461,9 +787,9 @@ Guided walkthroughs ordered by dependency — read them in sequence to understan
 \`\`\`
 docs/
 └── tours/
-  ├── index.md              # Tour listing with descriptions
-  ├── architecture.md       # System structure tour
-  ├── data-flow.md          # Data pipeline tour
+  ├── index.md             # Tour listing with descriptions
+  ├── architecture.md      # System structure tour
+  ├── data-flow.md         # Data pipeline tour
   └── feature-{name}.md    # Feature-specific tours
 \`\`\`
 
@@ -1473,14 +799,14 @@ Document the business domain as a three-level hierarchy: **Domain → Flow → S
 
 ### Hierarchy
 
-- **Domain**: A bounded business context (e.g., "Authentication", "Billing", "Inventory")
-- **Flow**: A business process within a domain (e.g., "User Login", "Invoice Generation")
-- **Step**: An atomic action within a flow (e.g., "Validate Credentials", "Generate PDF")
+- **Domain**: A bounded business context such as Authentication, Billing, or Inventory
+- **Flow**: A business process within a domain such as User Login or Invoice Generation
+- **Step**: An atomic action within a flow such as Validate Credentials or Generate PDF
 
 ### Domain Discovery Workflow
 
-1. \`analyze({ aspect: "structure", path: "." })\` — identify top-level domain boundaries (directories, modules)
-2. \`analyze({ aspect: "entry_points", path: "." })\` — detect flow entry types (HTTP, CLI, event, cron, manual)
+1. \`analyze({ aspect: "structure", path: "." })\` — identify top-level domain boundaries
+2. \`analyze({ aspect: "entry_points", path: "." })\` — detect flow entry types
 3. \`trace({ start: "<entry-point>", direction: "forward" })\` — map each flow's step sequence
 4. \`graph({ action: "neighbors", node_id: "<domain-module>", direction: "both" })\` — find cross-domain interactions
 
@@ -1502,7 +828,7 @@ Document the business domain as a three-level hierarchy: **Domain → Flow → S
 - **{Entity}**: {description + key attributes}
 
 ## Business Rules
-- {rule 1 — e.g., "Passwords must be hashed before storage"}
+- {rule 1}
 - {rule 2}
 
 ## Flows
@@ -1515,9 +841,6 @@ Document the business domain as a three-level hierarchy: **Domain → Flow → S
 2. {Step 2} — \`{file:function}\` — {what happens}
 3. {Step 3} — \`{file:function}\` — {what happens}
 
-### {Flow Name 2}
-...
-
 ## Cross-Domain Interactions
 
 | This Domain | Direction | Other Domain | Mechanism |
@@ -1539,55 +862,84 @@ docs/
 
 ## Interactive Tour Visualization (Data-Driven Viewer)
 
-AI Kit ships a pre-built \`tour-viewer.html\` that handles ALL rendering, graph layout, step navigation, and animation. The LLM's only job is to produce valid JSON data matching the schema below. **NEVER generate HTML for tours** — inject JSON into the shipped viewer.
+AI Kit ships a pre-built \`tour-viewer.html\` that handles rendering, step navigation, code context, and interaction. The LLM's job is to produce valid JSON data and inject it into the shipped viewer. **Never generate tour HTML from scratch.**
+
+Tour data must conform to [references/tour.schema.json](references/tour.schema.json).
 
 ### Usage
 
-1. Generate JSON matching the schema below
+1. Generate JSON that conforms to [references/tour.schema.json](references/tour.schema.json)
 2. Copy the shipped viewer from \`assets/tour-viewer.html\`
 3. Inject the JSON into the \`<script type="application/json" id="tour-data">\` block
 4. Save to \`docs/tours/interactive/{name}.html\`
 
-### JSON Schema
+### JSON Example
 
 \`\`\`json
 {
-  "title": "Tour Title",
-  "description": "What this tour covers",
-  "estimatedTime": "12 min",
+  "title": "Authentication Tour",
+  "description": "Walk through the login path from entry point to token issuance.",
+  "version": "1.0.0",
+  "metadata": {
+    "author": "AI Kit",
+    "created": "2026-05-14T00:00:00Z",
+    "tags": ["authentication", "onboarding", "prerequisites:config"],
+    "difficulty": "intermediate"
+  },
   "steps": [
     {
-      "stepNumber": 1,
-      "id": "unique-step-id",
-      "title": "Step Display Name",
-      "file": "src/path/to/file.ts",
-      "explanation": "What happens here and why it matters...",
-      "learnsConcept": "Key concept learned at this step",
-      "duration": "2 min"
-    }
-  ],
-  "dependencies": [
-    {
-      "source": "step-id-from",
-      "target": "step-id-to"
+      "id": "entry-point",
+      "title": "Request Entry",
+      "description": "This handler receives the login request, validates the outer shape, and forwards work to the auth service.",
+      "file": "src/http/routes/login.ts",
+      "line": 1,
+      "endLine": 28,
+      "language": "ts",
+      "codeSnippet": "export async function loginRoute(req, res) { /* ... */ }",
+      "highlights": [
+        {
+          "line": 8,
+          "label": "Request validation starts here",
+          "style": "info"
+        }
+      ],
+      "notes": [
+        "Introduces the request boundary.",
+        "The main concept here is input validation before auth logic."
+      ]
     }
   ]
 }
 \`\`\`
 
+### Tour Data Guidelines
+
+1. **title**: Use a reader-facing tour name.
+2. **description**: State the tour goal and scope in one or two sentences.
+3. **version**: Set the schema version you are targeting.
+4. **metadata**: Use optional metadata for authoring info, tags, timestamps, and difficulty.
+5. **steps**: Order is defined by array position. Do not add a separate ordinal field.
+6. **id**: Optional but recommended for stable references and analytics; use descriptive kebab-case when present.
+7. **description** on each step: Explain what matters in this step and why it belongs in the tour.
+8. **file**, **line**, and **endLine**: Point to the exact source span when possible.
+9. **codeSnippet** and **language**: Provide a fallback snippet when the viewer cannot load the file directly.
+10. **highlights**: Use line annotations for the few lines the reader should notice first.
+11. **notes**: Capture concepts, tips, cautions, or prerequisite reminders that do not belong in the main description.
+
+Mapping from the old contract to the current schema:
+
+- Put learned concepts, tips, and follow-up reminders in \`notes\`.
+- Put cross-cutting labels or prerequisite tags in \`metadata.tags\`.
+- Do not emit legacy timing, sequencing, concept, or graph-edge fields from the previous contract.
+
 ### Viewer Capabilities (automatic)
 
-- **Graph visualization**: Steps as nodes, dependencies as directed edges
-- **Auto-layout**: BFS-based tree layout from dependency graph
-- **Step highlighting**: Active step glows blue, completed steps turn green
-- **Animated edges**: Current path pulses with animation
-- **Bottom panel**: Shows file path, explanation, learned concept
-- **Navigation**: Previous/Next buttons + dot progress indicator
-- **Clickable nodes**: Click any step node to jump to it
-- **Collapsible panel**: Toggle bottom panel to see more graph
-- **Dark theme**: Consistent slate/navy color scheme
-- **Responsive**: Full viewport with graph taking center stage
-- **AI Kit badge**: Fixed bottom-right attribution badge (auto-included)
+- Step navigation with previous and next controls
+- File context display using \`file\`, \`line\`, and \`endLine\`
+- Syntax-highlighted fallback snippets using \`codeSnippet\` and \`language\`
+- Line annotations from \`highlights\`
+- Supplemental callouts from \`notes\`
+- Responsive layout with shipped AI Kit branding
 
 ### File-Type Icons (automatic)
 
@@ -1607,46 +959,148 @@ The viewer auto-detects file extensions and renders colored SVG icons:
 | .yaml, .yml | #cb171e (red) | "YML" text |
 | other | #6b7a90 (gray) | Generic file |
 
-Icons appear automatically in step nodes. No configuration needed — the viewer matches by file path extension.
-
-### Tour Data Guidelines
-
-1. **id**: Use kebab-case, descriptive (e.g., entry-point, auth-middleware, db-schema)
-2. **stepNumber**: Sequential 1-based numbering matching intended reading order
-3. **file**: Relative path from workspace root
-4. **explanation**: 1-3 sentences — what this file/module does and why it's important in the tour
-5. **learnsConcept**: Single concept name (2-4 words) the reader gains
-6. **dependencies**: Graph edges — which steps must be understood before this one
-7. **duration**: Estimated time for reader to absorb this step
+Icons appear automatically in step nodes. No configuration is needed.
 
 ### Tour Generation Strategy
 
-1. Identify entry points (entry_points analysis or scope_map)
-2. Trace critical paths through the codebase
-3. Order by dependency graph — a step should only reference concepts from prior steps
-4. Aim for 5-12 steps per tour (more → split into multiple tours)
-5. Each step teaches exactly ONE concept
+1. Identify entry points with \`entry_points\` analysis or \`scope_map\`.
+2. Trace the critical reading path through the codebase.
+3. Order steps so each step only depends on ideas already introduced by earlier steps.
+4. Aim for 5-12 steps per tour; split longer tours by concern.
+5. Let each step teach one main idea, with supporting detail in \`notes\`.
 
 ### Interactive C4 Architecture Visualization
 
 For architecture documentation, generate interactive C4 diagrams using the shipped **c4-viewer.html** from the \`c4-architecture\` skill.
 
 **Integration with docs skill:**
-- Architecture docs in \`docs/architecture/\` MUST have interactive HTML companions in \`docs/architecture/interactive/\`
-- Use the \`c4-architecture\` skill to generate C4 viewer HTML — it handles JSON schema, ReactFlow rendering, and ELK auto-layout
-- The \`c4-architecture\` skill provides: zoom/pan, node search, detail panels, drag-to-rearrange, and professional styling
+- Architecture docs in \`docs/architecture/\` should have interactive HTML companions in \`docs/architecture/interactive/\`
+- Use the \`c4-architecture\` skill to generate C4 viewer HTML; it handles JSON schema, ReactFlow rendering, and ELK auto-layout
+- The \`c4-architecture\` skill provides zoom and pan, node search, detail panels, drag-to-rearrange, and consistent styling
 
 **Workflow:**
-1. During Phase 5 (Domain Docs), identify system-level architecture views
-2. For EACH architecture view (system context, container, component):
+1. During domain or architecture documentation work, identify system-level views.
+2. For each architecture view such as system context, container, or component:
   - Generate C4 JSON data: \`{nodes: [{id, label, type, description, technology}], edges: [{from, to, label}]}\`
   - Use the \`c4-architecture\` skill to render interactive HTML
   - Save to \`docs/architecture/interactive/{view-name}.html\`
-3. Cross-reference: link from markdown docs to interactive viewers
+3. Link from the markdown docs to the interactive viewers.
+
+**Critical:** Never generate architecture HTML from scratch. Always use the shipped \`c4-viewer.html\` via the \`c4-architecture\` skill.`},{file:`references/tour.schema.json`,content:`{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AIKIT Interactive Code Tour",
+  "description": "Schema for AI Kit interactive code tour data. The agent generates JSON matching this schema, which is injected into tour-viewer.html.",
+  "version": "1.0.0",
+  "type": "object",
+  "required": ["title", "steps"],
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Tour title displayed in the viewer header"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief tour description shown below the title"
+    },
+    "version": {
+      "type": "string",
+      "description": "Schema version for forward compatibility",
+      "default": "1.0.0"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "author": { "type": "string" },
+        "created": { "type": "string", "format": "date-time" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "difficulty": { "type": "string", "enum": ["beginner", "intermediate", "advanced"] }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["title", "description"],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Step title shown in navigation"
+          },
+          "description": {
+            "type": "string",
+            "description": "Markdown content explaining this step"
+          },
+          "file": {
+            "type": "string",
+            "description": "Relative file path this step references"
+          },
+          "line": {
+            "type": "integer",
+            "description": "Starting line number in the file"
+          },
+          "endLine": {
+            "type": "integer",
+            "description": "Ending line number (for range highlights)"
+          },
+          "codeSnippet": {
+            "type": "string",
+            "description": "Code snippet to display if file is not available"
+          },
+          "language": {
+            "type": "string",
+            "description": "Language for syntax highlighting of codeSnippet"
+          },
+          "highlights": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "line": { "type": "integer" },
+                "label": { "type": "string" },
+                "style": { "type": "string", "enum": ["info", "warning", "error", "success"] }
+              },
+              "required": ["line"]
+            },
+            "description": "Line-level highlights within the code"
+          },
+          "notes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Additional callouts or tips for this step"
+          }
+        }
+      }
+    }
+  }
+}`},{file:`references/generation-pipeline.md`,content:`# Generation Pipeline Reference
 
-**CRITICAL:** NEVER generate architecture HTML from scratch. ALWAYS use the shipped c4-viewer.html via the \`c4-architecture\` skill. Hand-crafted HTML will be inconsistent and unprofessional.
 ## Documentation Generation Prompts
 
+    Use document-type-specific output requirements. Do not ask the model to "write clearly", "document the feature", or "create comprehensive documentation" without attaching the right depth requirements.
+
+    ### Document-Type Output Requirements
+
+    #### Tutorial Output Requirements
+    - Include step-by-step code examples with expected output
+    - Show common mistakes and how to fix them
+    - Add prerequisite checks at the start
+
+    #### Reference Output Requirements
+    - Include complete function signatures with all parameters and return types
+    - Add usage examples for each public API
+    - Document error codes and edge cases
+
+    #### Architecture Output Requirements
+    - Include sequence diagrams for key interactions (Mermaid format)
+    - Document error paths and failure modes
+    - Show integration contracts between components
+
+    #### How-To / Guide Output Requirements
+    - Include troubleshooting section for common issues
+    - Add verification steps after each major action
+    - Show expected vs actual output for validation
+
 Structured LLM prompt templates for generating high-quality documentation. Each produces strict JSON for consistent, parseable output.
 
 ### Tour Generation Prompt (2-Phase)
@@ -1680,28 +1134,40 @@ You are a developer onboarding guide. Given a ranked list of codebase modules wi
 
 **Instructions:**
 - Create 8-15 tour steps (adjust to codebase size)
+- Make step 1 a prerequisite check before deep navigation
 - Start with entry points and high-level orchestration
 - Progress to increasingly detailed/specialized modules
 - Each step should teach ONE concept
 - Group related files into single steps (max 3 files per step)
 - End with cross-cutting concerns and extension points
-- Include estimated reading time per step
+- Include code snippets with expected output inside step descriptions when a step teaches executable behavior
+- Use notes to call out common mistakes and how to fix them
 
-**Respond ONLY with a JSON object:**
+**Respond ONLY with a JSON object matching** \`references/tour.schema.json\`**:**
 {
   "title": "Tour title",
   "description": "One sentence overview",
-  "estimatedTime": "30 min",
+  "version": "1.0.0",
+  "metadata": {
+    "difficulty": "intermediate",
+    "tags": ["onboarding", "tour"]
+  },
   "steps": [
     {
-      "stepNumber": 1,
-      "title": "Step title — concept learned",
-      "files": ["src/index.ts"],
-      "explanation": "2-3 sentences explaining what this teaches",
-      "learnsConcept": "Single concept name",
-      "prerequisites": [],
-      "linesOfInterest": { "src/index.ts": [12, 45] },
-      "duration": "2 min"
+      "title": "Start here — entry point",
+      "description": "Markdown explanation with a prerequisite check, code example, and expected output.",
+      "file": "src/index.ts",
+      "line": 12,
+      "endLine": 45,
+      "codeSnippet": "const app = createApp();",
+      "language": "ts",
+      "highlights": [
+        { "line": 12, "label": "Entry point", "style": "info" }
+      ],
+      "notes": [
+        "Common mistake: bootstrapping the wrong entry file. Fix: start from the configured entry point.",
+        "Expected output: the server or app shell initializes without runtime errors."
+      ]
     }
   ]
 }
@@ -1710,7 +1176,7 @@ You are a developer onboarding guide. Given a ranked list of codebase modules wi
 ### File Documentation Prompt
 
 \`\`\`
-You are a technical writer. Document this source file for developer reference.
+You are a technical writer producing developer reference documentation for this source file.
 
 **File:** {{FILE_PATH}}
 **Content:**
@@ -1719,18 +1185,36 @@ You are a technical writer. Document this source file for developer reference.
 **Module's role in architecture:** {{MODULE_ROLE}}
 **Layer:** {{LAYER}}
 
+**Reference output requirements:**
+- Include complete function signatures with all parameters and return types
+- Add usage examples for each public API
+- Document error codes and edge cases
+
 **Respond ONLY with a JSON object:**
 {
   "title": "Module name — one-line purpose",
   "overview": "2-3 sentence description of what this module does and why it exists",
   "publicAPI": [
-    { "name": "functionName", "signature": "typed signature", "description": "what it does", "example": "brief usage" }
+    {
+      "name": "functionName",
+      "signature": "export function functionName(input: Input): Output",
+      "parameters": [
+        { "name": "input", "type": "Input", "required": true, "description": "what this parameter controls" }
+      ],
+      "returns": { "type": "Output", "description": "what comes back" },
+      "description": "what it does",
+      "example": "brief usage"
+    }
   ],
   "dependencies": [
     { "module": "import path", "purpose": "why this dependency" }
   ],
   "patterns": ["Pattern names used (e.g., Factory, Observer, Middleware)"],
   "gotchas": ["Non-obvious behaviors or edge cases"],
+  "errorCodes": [
+    { "code": "ERR_EXAMPLE", "when": "when this failure happens", "resolution": "how to recover or debug" }
+  ],
+  "edgeCases": ["Edge case 1", "Edge case 2"],
   "relatedModules": ["paths to related files for cross-reference"]
 }
 \`\`\`
@@ -1738,7 +1222,7 @@ You are a technical writer. Document this source file for developer reference.
 ### Domain Documentation Prompt
 
 \`\`\`
-You are a domain-driven design analyst. Given files belonging to a business domain, document the domain model.
+You are a domain and architecture analyst. Given files belonging to a business domain, document the domain model and the architecture that supports it.
 
 **Domain:** {{DOMAIN_NAME}}
 **Files in this domain:**
@@ -1750,6 +1234,11 @@ You are a domain-driven design analyst. Given files belonging to a business doma
 **Cross-domain relationships:**
 {{CROSS_DOMAIN_EDGES}}
 
+**Architecture output requirements:**
+- Include sequence diagrams for key interactions (Mermaid format)
+- Document error paths and failure modes
+- Show integration contracts between components
+
 **Respond ONLY with a JSON object:**
 {
   "domain": "Domain name",
@@ -1767,6 +1256,13 @@ You are a domain-driven design analyst. Given files belonging to a business doma
   "flows": [
     { "name": "Flow name", "steps": ["Step 1 → file:fn", "Step 2 → file:fn"], "trigger": "What initiates this" }
   ],
+  "sequenceDiagramMermaid": "sequenceDiagram\\n  participant Client\\n  participant Domain\\n  participant Dependency\\n  Client->>Domain: Trigger flow\\n  Domain->>Dependency: Call contract\\n  Dependency-->>Domain: Response",
+  "integrationContracts": [
+    { "from": "Caller", "to": "Dependency", "contract": "payload/schema/api", "notes": "why this boundary exists" }
+  ],
+  "failureModes": [
+    { "mode": "Dependency timeout", "effect": "Flow stalls", "recovery": "retry or fallback" }
+  ],
   "crossDomainInteractions": [
     { "direction": "outgoing|incoming", "otherDomain": "Name", "mechanism": "API/event/import", "purpose": "Why" }
   ]
@@ -1775,7 +1271,7 @@ You are a domain-driven design analyst. Given files belonging to a business doma
 
 ## Documentation Generation Pipeline
 
-Orchestrate comprehensive documentation generation using a phased approach.
+Orchestrate phased documentation generation with document-type-specific outputs and validation.
 
 ### Phase 1 — Inventory (deterministic)
 \`\`\`
@@ -1864,89 +1360,377 @@ graph({ action: "find_nodes" })                  # Full module graph
 5. Verify all interactive HTML files open correctly and contain valid JSON data
 \`\`\`
 
-### Output Structure
-\`\`\`
-docs/
-├── tours/
-│   ├── getting-started.md          # Primary tour (Mermaid diagrams)
-│   ├── advanced-internals.md       # Deep-dive tour
-│   └── interactive/
-│       ├── getting-started.html    # Shipped tour-viewer.html + JSON data
-│       └── advanced-internals.html
-├── architecture/
-│   ├── c4-context.md
-│   ├── c4-containers.md
-│   ├── interactive/
-│   │   ├── overview.html           # React Flow architecture
-│   │   └── per-service.html
-│   └── domains/
-│       ├── authentication.md
-│       └── billing.md
-├── reference/
-│   └── modules/                    # Per-module API docs
-└── guides/
-    └── contributing.md
-\`\`\`
+### Output Structure
+\`\`\`
+docs/
+├── tours/
+│   ├── getting-started.md          # Primary tour (Mermaid diagrams)
+│   ├── advanced-internals.md       # Deep-dive tour
+│   └── interactive/
+│       ├── getting-started.html    # Shipped tour-viewer.html + JSON data
+│       └── advanced-internals.html
+├── architecture/
+│   ├── c4-context.md
+│   ├── c4-containers.md
+│   ├── interactive/
+│   │   ├── overview.html           # React Flow architecture
+│   │   └── per-service.html
+│   └── domains/
+│       ├── authentication.md
+│       └── billing.md
+├── reference/
+│   └── modules/                    # Per-module API docs
+└── guides/
+    └── contributing.md
+\`\`\`
+
+## Framework Context Injection
+
+When generating documentation for a specific framework, inject framework-specific conventions into LLM prompts to improve generation quality:
+
+### Detection
+\`\`\`
+# Auto-detect framework from project files:
+- package.json → "next", "react", "express", "nestjs", "@angular/core"
+- requirements.txt → "django", "flask", "fastapi"
+- go.mod → "gin", "fiber", "echo"
+- Cargo.toml → "actix-web", "axum", "rocket"
+\`\`\`
+
+### Addendum Format
+\`\`\`markdown
+## {{FRAMEWORK}} Documentation Addendum
+(Injected into documentation prompts when {{FRAMEWORK}} is detected)
+
+### Canonical Documentation Structure
+
+| Path Pattern | Doc Type | Template |
+|---|---|---|
+| {{src_pattern}} | {{doc_type}} | {{which template to use}} |
+
+### Tour Conventions
+
+- Tour starts at: {{entry_point_pattern}}
+- Key learning progression: {{progression}}
+- Framework-specific concepts to teach: {{concepts}}
+
+### Domain Conventions
+
+- Where domains live: {{domain_path_pattern}}
+- How domains are bounded: {{boundary_mechanism}}
+\`\`\`
+
+### Example: Next.js Addendum
+\`\`\`
+## Next.js Documentation Addendum
+
+### Canonical Documentation Structure
+| Path Pattern | Doc Type | Template |
+|---|---|---|
+| app/layout.tsx | Architecture | Root layout, providers, theme |
+| app/**/page.tsx | Feature docs | Page-level feature documentation |
+| app/api/** | API Reference | Endpoint documentation |
+| lib/** | Reference | Utility/service documentation |
+| components/** | Component docs | Props, usage examples, variants |
+
+### Tour Conventions
+- Tour starts at: app/layout.tsx (root) → app/page.tsx (home)
+- Key progression: Layout → Pages → API Routes → Lib → Components
+- Framework concepts: App Router, Server Components, Server Actions, Middleware
+
+### Domain Conventions
+- Domains live in: app/(domain)/ or features/(domain)/
+- Bounded by: Route groups or feature folders
+\`\`\``},{file:`references/prd-template.md`,content:`# Living PRD Template
+
+A Product Requirements Document (PRD) that evolves with the codebase. Each capability has a unique \`capability_id\` for cross-referencing.
+
+## PRD Structure
+
+### 1. Overview
+- **Product Name**: [name]
+- **Version**: [semantic version]
+- **Last Updated**: [ISO date]
+- **Status**: draft | review | approved | deprecated
+
+### 2. Problem Statement
+What problem does this solve? Who has this problem? What's the impact of not solving it?
+
+### 3. Goals & Non-Goals
+
+| Goal | Measurable Target | Priority |
+|------|-------------------|----------|
+| [goal] | [metric] | P0/P1/P2 |
+
+**Non-Goals:** Explicitly list what this does NOT aim to solve.
+
+### 4. Capabilities
+
+Each capability has a unique ID for tracing requirements → code → tests → docs.
+
+| capability_id | Name | Description | Status |
+|---------------|------|-------------|--------|
+| CAP-001 | [name] | [description] | proposed/approved/implemented/verified |
+
+#### Capability Detail Template
+
+\`\`\`yaml
+capability_id: CAP-XXX
+name: [Descriptive Name]
+description: [What it does]
+acceptance_criteria:
+  - [Testable criterion 1]
+  - [Testable criterion 2]
+dependencies: [CAP-YYY, CAP-ZZZ]
+priority: P0 | P1 | P2
+status: proposed | approved | implemented | verified
+traceability:
+  tests: [test file paths]
+  docs: [doc file paths]
+  code: [implementation file paths]
+\`\`\`
+
+### 5. User Stories
+
+\`\`\`
+As a [role], I want [capability] so that [benefit].
+Acceptance: [testable criteria]
+Links: CAP-XXX
+\`\`\`
+
+### 6. Technical Constraints
+- Performance requirements
+- Security requirements
+- Compatibility requirements
+- Infrastructure constraints
+
+### 7. Architecture Decisions
+Link to ADRs: \`docs/decisions/ADR-NNN-*.md\`
+
+### 8. Milestones & Phases
+
+| Phase | Capabilities | Target | Status |
+|-------|-------------|--------|--------|
+| MVP | CAP-001, CAP-002 | [date] | planned/active/complete |
+
+### 9. Risk Register
+
+| Risk | Impact | Likelihood | Mitigation | Owner |
+|------|--------|------------|------------|-------|
+| [risk] | H/M/L | H/M/L | [strategy] | [who] |
+
+### 10. Appendix
+- Glossary of terms
+- Related documents
+- Change log
+
+---
+
+## PRD Index Schema (prd.index.json)
+
+The PRD index tracks all PRDs and their capabilities for automated cross-referencing:
+
+\`\`\`json
+{
+  "prds": [
+    {
+      "id": "PRD-001",
+      "title": "Feature Name",
+      "path": "docs/prds/PRD-001-feature-name.md",
+      "status": "approved",
+      "capabilities": ["CAP-001", "CAP-002"],
+      "lastUpdated": "2024-01-15"
+    }
+  ],
+  "capabilities": {
+    "CAP-001": {
+      "prd": "PRD-001",
+      "status": "implemented",
+      "tests": ["tests/cap-001.test.ts"],
+      "code": ["src/features/cap-001/"]
+    }
+  }
+}
+\`\`\`
+
+## When to Create/Update PRDs
+
+| Trigger | Action |
+|---------|--------|
+| New feature request | Create new PRD with capability_ids |
+| Flow design step | Reference PRD, add capabilities |
+| Implementation complete | Update capability status → implemented |
+| Tests passing | Update capability status → verified |
+| Architecture decision | Link ADR to affected capabilities |
+`},{file:`references/architecture-blueprint.md`,content:`# Architecture Blueprint Reference
+
+## Architecture Blueprint Generation
+
+When bootstrapping \`docs/\` for the first time or refreshing architecture documentation, generate a comprehensive architecture blueprint. This replaces manual documentation with tool-driven analysis.
+
+### Blueprint Workflow
+
+\`\`\`
+Step 1: Detect & Analyze
+  analyze({ aspect: "structure", path: "." })        → project layout, packages, layers
+  analyze({ aspect: "patterns", path: "." })         → conventions, design patterns
+  analyze({ aspect: "entry_points", path: "." })     → API surface, CLI entry points
+
+Step 2: Map Dependencies
+  analyze({ aspect: "dependencies", path: "." })     → import graph, cross-package edges
+  graph({ action: 'find_nodes', name_pattern: '*' })   → module graph nodes
+  graph({ action: 'neighbors', node_id: '...' })       → dependency directions
+
+Step 3: Visualize
+  analyze({ aspect: "diagram", path: "." })          → Mermaid architecture diagrams
+  Delegate to c4-architecture skill                    → C4 context/container/component views
+
+Step 4: Synthesize
+  produce_knowledge({ path: "." })                    → comprehensive analysis
+  Combine outputs into docs/ structure
+\`\`\`
+
+### Blueprint Sections
+
+The architecture blueprint should cover these areas (adapted from the Architecture Blueprint Generator pattern):
+
+#### 1. Architecture Detection & Analysis
+- **Auto-detect**: Project type, framework, architectural pattern (Clean Architecture, Microservices, Layered, etc.)
+- **Tools**: \`analyze({ aspect: "structure", ... })\` → folder organization, \`analyze({ aspect: "patterns", ... })\` → framework detection, \`analyze({ aspect: "dependencies", ... })\` → dependency flow
+- **Output**: \`docs/architecture/overview.md\` header section
+
+#### 2. Architectural Overview
+- Guiding principles from code structure
+- Architectural boundaries and enforcement mechanisms
+- Hybrid patterns or adaptations
+- **Tools**: \`produce_knowledge\` + \`analyze({ aspect: "structure", ... })\`
+- **Output**: \`docs/architecture/overview.md\` main body
+
+#### 3. Architecture Visualization
+- High-level subsystem diagram
+- Component interaction diagrams
+- Data flow diagrams
+- **Tools**: \`analyze({ aspect: "diagram", ... })\` + \`c4-architecture\` skill
+- **Output**: \`docs/architecture/overview.md\` diagrams + \`docs/architecture/diagrams/\`
+
+#### 4. Core Architectural Components
+For each major component:
+- Purpose and responsibility
+- Internal structure
+- Key abstractions
+- Interaction patterns
+- **Tools**: \`analyze({ aspect: "symbols", path: "component/" })\` + \`compact({ path, query: "exports" })\`
+- **Output**: \`docs/architecture/components/{name}.md\`
+
+#### 5. Layers & Dependencies
+- Layer structure as implemented
+- Dependency rules between layers
+- Abstraction mechanisms for separation
+- Circular dependencies or violations
+- **Tools**: \`analyze({ aspect: "dependencies", ... })\` + \`graph({ action: 'neighbors' })\`
+- **Output**: \`docs/architecture/overview.md\` layers section
+
+#### 6. Cross-Cutting Concerns
+Document implementation patterns for:
+- Error handling & resilience
+- Logging & observability
+- Validation patterns
+- Configuration management
+- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "error handling" })\`
+- **Output**: \`docs/architecture/overview.md\` cross-cutting section
+
+#### 7. Testing Architecture
+- Test framework and strategy
+- Test boundary patterns (unit, integration, e2e)
+- Test file conventions
+- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "test" })\`
+- **Output**: \`docs/guides/testing.md\`
+
+#### 8. Extension & Evolution
+- How to add features while preserving architecture
+- Component creation patterns
+- Integration patterns for external systems
+- **Tools**: \`analyze({ aspect: "entry_points", ... })\` + \`analyze({ aspect: "patterns", ... })\`
+- **Output**: \`docs/guides/contributing.md\` or \`docs/architecture/overview.md\` extension section
+
+## Skill Integration
 
-## Framework Context Injection
+### \`adr-skill\` Integration
+- All ADRs live in \`docs/decisions/\`
+- When the docs-sync step detects an architecture decision was made during the flow, delegate to \`adr-skill\`
+- After \`adr-skill\` creates/updates an ADR, update \`docs/decisions/index.md\`
+- Include the Source column linking to the flow artifact where the decision was designed.
+- Cross-reference ADRs from component docs where relevant
 
-When generating documentation for a specific framework, inject framework-specific conventions into LLM prompts to improve generation quality:
+### \`c4-architecture\` Integration
+- Architecture diagrams live in \`docs/architecture/\`
+- When the docs-sync step detects structural changes (new packages, changed boundaries), delegate to \`c4-architecture\`
+- Use Mermaid format for docs files (not HTML) — markdown renders in GitHub
+- Reference diagrams from component docs
 
-### Detection
-\`\`\`
-# Auto-detect framework from project files:
-- package.json → "next", "react", "express", "nestjs", "@angular/core"
-- requirements.txt → "django", "flask", "fastapi"
-- go.mod → "gin", "fiber", "echo"
-- Cargo.toml → "actix-web", "axum", "rocket"
-\`\`\`
+### Mermaid Syntax Rules
 
-### Addendum Format
-\`\`\`markdown
-## {{FRAMEWORK}} Documentation Addendum
-(Injected into documentation prompts when {{FRAMEWORK}} is detected)
+When generating Mermaid diagrams in documentation:
 
-### Canonical Documentation Structure
+- **Quote node labels containing special characters** — Names with \`@\`, \`/\`, or other special characters must be wrapped in double quotes inside square brackets: \`subgraph Commons["@scope/package-name"]\`, \`NodeId["@org/lib"]\`
+- **Quote subgraph titles with special characters** — \`subgraph Title["@scope/name"]\` not \`subgraph @scope/name\`
+- Node IDs (aliases) must not contain special characters — use plain alphanumeric IDs and put the display name in \`["..."]\``},{file:`SKILL.md`,content:`---
+name: docs
+description: "Living documentation management — Diátaxis framework, docs/ convention, create/update rules, staleness detection, integration with adr-skill and c4-architecture."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [code-changes, flow-artifacts, architecture]
+  outputs: [documentation]
+  relatedSkills: [adr-skill, c4-architecture]
+  internal: true
+---
 
-| Path Pattern | Doc Type | Template |
-|---|---|---|
-| {{src_pattern}} | {{doc_type}} | {{which template to use}} |
+# Docs — Living Documentation Skill
 
-### Tour Conventions
+Manage the \`docs/\` folder as a single source of truth for project documentation. This skill runs during the mandatory \`_docs-sync\` epilogue step of every flow, ensuring documentation stays in sync with code changes.
 
-- Tour starts at: {{entry_point_pattern}}
-- Key learning progression: {{progression}}
-- Framework-specific concepts to teach: {{concepts}}
+## Principles
 
-### Domain Conventions
+1. **Living, not legacy** — Documentation is updated as code changes, never as a separate "docs sprint"
+2. **One source of truth** — Never duplicate what's in code comments, READMEs, or inline JSDoc
+3. **Diátaxis framework** — Organize docs into four categories using the two-question compass:
+  - **Q1**: Is the reader trying to **do** something (action) or **understand** something (cognition)?
+  - **Q2**: Is the reader **learning** (study) or **working** (work)?
+  - Action+Study → Tutorial · Action+Work → How-to · Cognition+Work → Reference · Cognition+Study → Explanation
+  - See [references/diataxis-reference.md](references/diataxis-reference.md) for the full classification system
+4. **Minimal but complete** — Create docs only when they add value beyond what code communicates
+5. **Delegate to specialists** — Architecture diagrams → \`c4-architecture\` skill. Decision records → \`adr-skill\`
 
-- Where domains live: {{domain_path_pattern}}
-- How domains are bounded: {{boundary_mechanism}}
-\`\`\`
+## Documentation Modes
 
-### Example: Next.js Addendum
-\`\`\`
-## Next.js Documentation Addendum
+This skill operates in two modes, often combined:
 
-### Canonical Documentation Structure
-| Path Pattern | Doc Type | Template |
-|---|---|---|
-| app/layout.tsx | Architecture | Root layout, providers, theme |
-| app/**/page.tsx | Feature docs | Page-level feature documentation |
-| app/api/** | API Reference | Endpoint documentation |
-| lib/** | Reference | Utility/service documentation |
-| components/** | Component docs | Props, usage examples, variants |
+### Source-Only Mode
+Generate documentation from code analysis alone. Used when:
+- Bootstrapping \`docs/\` for the first time (\`produce_knowledge\`, \`analyze_*\` tools)
+- Running outside a flow context (manual documentation refresh)
+- Flow produced no artifacts (auto-skipped design step)
 
-### Tour Conventions
-- Tour starts at: app/layout.tsx (root) → app/page.tsx (home)
-- Key progression: Layout → Pages → API Routes → Lib → Components
-- Framework concepts: App Router, Server Components, Server Actions, Middleware
+### Flow-Aware Mode (Primary)
+Generate documentation from code changes **plus** flow artifacts. This is the primary mode during \`_docs-sync\` because every completed flow produces structured artifacts containing design decisions, requirements, and verification results.
 
-### Domain Conventions
-- Domains live in: app/(domain)/ or features/(domain)/
-- Bounded by: Route groups or feature folders
+Flow artifacts are the most valuable documentation input — they capture the *why* behind changes (decisions, constraints, trade-offs, risks) while code only shows the *what*.
+
+**Artifact reading sequence:**
+\`\`\`
+flow({ action: 'status' })                        # Get artifactsPath
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all artifacts
+digest({ sources: [                                # Compress into working context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
 \`\`\`
 
+See [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md) for the artifact catalog and artifact-to-documentation mapping.
+
 ## Rules for the \`_docs-sync\` Epilogue Step
 
 When this skill is loaded during the \`_docs-sync\` epilogue:
@@ -1987,9 +1771,9 @@ For each doc action identified in Step 1, determine the Diátaxis quadrant:
 1. Ask: **Action or Cognition?** Is the reader doing something or understanding something?
 2. Ask: **Study or Work?** Is the reader learning or applying?
 3. Match the answer pair to a quadrant → pick the target directory
-4. If ambiguous → consult [references/diataxis-compass.md](references/diataxis-compass.md) for edge cases
+4. If ambiguous → consult [references/diataxis-reference.md](references/diataxis-reference.md) for edge cases
 
-Run the [quality checklist](references/diataxis-quality.md) against any doc created or substantially modified.
+Run the [quality checklist](references/diataxis-reference.md) against any doc created or substantially modified.
 
 ### 2. Apply the Mapping
 
@@ -2043,6 +1827,183 @@ If docs were added/removed, update \`docs/README.md\` index.
 
 If the flow's changes don't warrant doc updates (e.g., pure bug fix with no revelations), report "No documentation updates needed" and move on.
 
+## AI Kit Tools for Documentation
+
+Use these existing AI Kit tools to generate documentation content — never write docs from scratch when a tool can provide the foundation:
+
+| Documentation Task | AI Kit Tool | What It Provides |
+|---|---|---|
+| Project overview | \`produce_knowledge({ path: "." })\` | Comprehensive analysis: structure, patterns, dependencies → \`docs/README.md\` |
+| Architecture overview | \`analyze({ aspect: "structure", path: "." })\` | File tree, package layout, layer organization → \`docs/architecture/overview.md\` |
+| Architecture diagrams | \`analyze({ aspect: "diagram", path: "." })\` | Mermaid diagrams of component relationships → \`docs/architecture/\` |
+| Dependency map | \`analyze({ aspect: "dependencies", path: "." })\` | Import graph, cross-package edges → \`docs/architecture/overview.md\` dependencies section |
+| Component analysis | \`analyze({ aspect: "symbols", path: "src/component" })\` | Exports, classes, interfaces → \`docs/architecture/components/{name}.md\` |
+| Entry points / API surface | \`analyze({ aspect: "entry_points", path: "." })\` | CLI bins, route handlers, main exports → \`docs/reference/api.md\` |
+| Code patterns | \`analyze({ aspect: "patterns", path: "." })\` | Design patterns, conventions → \`docs/architecture/overview.md\` patterns section |
+| Impact analysis | \`blast_radius({ changed_files: [...] })\` | What's affected by changes → targeted doc updates |
+| Change detection | \`git_context({})\` | Recent changes, diff summary → determine which docs need updating |
+| Module graph | \`graph({ action: 'neighbors', node_id })\` | Who-imports-whom, cross-package dependencies → architecture diagrams |
+| Full audit | \`audit({ path: "." })\` | Structure + deps + patterns + health + dead symbols → comprehensive docs refresh |
+
+### Tool-First Workflow
+
+When creating documentation, always start with tool output, then enhance with human context:
+
+\`\`\`
+1. Run the relevant analysis tool(s)
+2. Use the output as the doc's foundation
+3. Add: purpose/motivation (why, not just what)
+4. Add: decision context (link to ADRs)
+5. Add: cross-references to related docs
+6. Remove: implementation details visible in code
+\`\`\`
+
+## \`docs/\` Convention
+
+\`\`\`
+docs/
+├── README.md                      ← Project overview + docs index (always exists)
+├── architecture/
+│   ├── overview.md                ← C4 context + container diagrams (c4-architecture skill)
+│   ├── stack.md                   ← Language, runtime, frameworks, all dependencies
+│   ├── structure.md               ← Directory layout, entry points, key files
+│   ├── design.md                  ← Layers, patterns, data flow
+│   ├── conventions.md             ← Naming, formatting, error handling, imports
+│   ├── integrations.md            ← External APIs, databases, auth, monitoring
+│   ├── testing.md                 ← Frameworks, file organization, mocking strategy
+│   ├── concerns.md                ← Tech debt, bugs, security risks, perf bottlenecks
+│   └── components/
+│       └── {component-name}.md    ← Per-component technical docs
+├── decisions/                     ← Architecture Decision Records (adr-skill)
+│   ├── index.md                   ← ADR log / table of contents
+│   └── NNN-{title}.md             ← Individual ADRs
+├── guides/
+│   ├── tutorials/                 ← Learning-oriented lessons (Diátaxis: Tutorial)
+│   │   └── {topic}.md
+│   └── {topic}.md                 ← How-to guides for common tasks (Diátaxis: How-To)
+└── reference/
+    ├── api.md                     ← API reference (endpoints, schemas, auth)
+    └── configuration.md           ← Configuration options and environment variables
+\`\`\`
+
+### Directory Purposes
+
+| Directory | Diátaxis Quadrant | What Goes Here | When to Create/Update |
+|-----------|-------------------|----------------|----------------------|
+| \`architecture/\` | Explanation + Reference | C4 diagrams, project knowledge (stack, structure, design, conventions, integrations, testing, concerns), component docs | Initial onboarding, new component, structural change, architecture decision |
+| \`decisions/\` | Explanation | ADRs — why decisions were made | Non-trivial technical decision (see adr-skill triggers) |
+| \`guides/\` | How-To | Step-by-step instructions for tasks | New workflow, complex setup, common operations |
+| \`guides/tutorials/\` | Tutorial | Learning-oriented guided lessons with concrete outcomes | New technology/feature adoption, onboarding new developers |
+| \`reference/\` | Reference | API docs, config options, data schemas | API change, new config option, schema modification |
+
+## Change-to-Doc Mapping
+
+Use this decision tree to determine what documentation action to take after a flow completes:
+
+\`\`\`
+What changed?
+├── New component/module/package
+│   ├── Creates public API? → Create docs/architecture/components/{name}.md + update reference/api.md
+│   └── Internal only? → Update docs/architecture/overview.md (component list)
+├── API change (new endpoint, changed contract, new config)
+│   └── Update docs/reference/api.md or docs/reference/configuration.md
+├── Architecture/infrastructure decision
+│   └── Delegate to adr-skill → creates/updates docs/decisions/NNN-{title}.md
+├── Structural/architecture change
+│   └── Delegate to c4-architecture skill → updates docs/architecture/overview.md
+├── New developer workflow (build, deploy, test pattern)
+│   └── Create or update docs/guides/{topic}.md
+├── Bug fix
+│   ├── Reveals missing docs? → Create the missing doc
+│   └── Straightforward fix? → No docs update needed
+└── Dependency update / refactor / cleanup
+    └── No docs update needed (unless public API changed)
+\`\`\`
+
+### Classify Document Type
+
+Route each document to the right framework based on its audience and purpose:
+
+| Document Type | Primary Framework | Classification Method | Target Structure |
+|---|---|---|---|
+| End-user docs (tutorials, guides, references, explanations) | Diátaxis | Two-question compass: Action/Cognition × Study/Work | \`guides/\`, \`reference/\`, \`architecture/\` |
+| Architecture docs (C4 diagrams, component views, deployment) | arc42-lite | Context → Container → Component → Deployment views | \`architecture/\` |
+| API documentation (endpoints, schemas, contracts) | Contract-first | OpenAPI-inspired: paths, schemas, auth, errors | \`reference/api.md\` |
+| Operations docs (runbooks, playbooks, incident response) | Runbook format | Trigger → Diagnose → Fix → Verify → Prevent | \`guides/operations/\` |
+
+**Decision flow:**
+1. Is it API documentation? → Contract-first (OpenAPI-inspired structure)
+2. Is it architecture/infrastructure? → arc42-lite views
+3. Is it operational/on-call? → Runbook format
+4. Everything else → Diátaxis two-question compass
+
+For Diátaxis edge cases, consult [references/diataxis-reference.md](references/diataxis-reference.md).
+
+## Templates
+
+Document templates for each type are in [references/doc-templates.md](references/doc-templates.md).
+
+Key templates: Component Doc, Tutorial, Guide, Decision Index, Reference. Each includes depth-appropriate prompts (sequence diagrams, edge cases, error paths).
+
+## Skill Integration
+
+Integration patterns with \`adr-skill\`, \`c4-architecture\`, and Mermaid syntax rules are in [references/architecture-blueprint.md](references/architecture-blueprint.md).
+
+## Project Knowledge
+
+Project knowledge acquisition workflow, templates, and gotchas are in [references/project-knowledge-reference.md](references/project-knowledge-reference.md).
+
+## Architecture Documentation
+
+Architecture blueprint generation instructions are in [references/architecture-blueprint.md](references/architecture-blueprint.md).
+
+Pairs with the \`c4-architecture\` skill for interactive diagram generation.
+
+## Living PRD Generation
+
+Product Requirements Documents (PRDs) serve as the single source of truth for what a feature does and why. They use \`capability_id\` keys (e.g., \`CAP-001\`) for end-to-end traceability: requirements -> code -> tests -> docs.
+
+### When to Create/Update PRDs
+
+| Trigger | Action |
+|---------|--------|
+| New feature or epic | Create PRD from [references/prd-template.md](references/prd-template.md) |
+| Flow design step | Reference existing PRD, add new capabilities |
+| Implementation complete | Update capability status -> \`implemented\` |
+| Tests passing | Update capability status -> \`verified\` |
+| Architecture decision (ADR) | Link ADR to affected capabilities |
+
+### PRD Generation Workflow
+
+1. **Create** - Use the 10-section template from \`references/prd-template.md\`
+2. **Assign capability_ids** - Each discrete capability gets a unique \`CAP-XXX\` ID
+3. **Cross-reference** - Link capabilities to code files, test files, and doc files in the traceability section
+4. **Maintain index** - Update \`docs/prds/prd.index.json\` (schema in the reference) for automated cross-referencing
+5. **Evolve** - PRDs are living documents. Update status fields as implementation progresses through proposed -> approved -> implemented -> verified
+
+### Output Location
+
+PRDs go in \`docs/prds/PRD-NNN-descriptive-name.md\`. The index lives at \`docs/prds/prd.index.json\`.
+
+## Tour Generation & Interactive Visualization
+
+Tour generation, domain-specific docs, and interactive visualization instructions are in [references/tour-generation.md](references/tour-generation.md).
+
+Key points:
+- Tour JSON schema: see [references/tour.schema.json](references/tour.schema.json)
+- Interactive viewer: copy shipped \`assets/tour-viewer.html\`, inject tour JSON data
+- Domain docs: framework-specific, API, and library documentation patterns
+
+## Generation Pipeline
+
+Full generation prompts, multi-phase pipeline, and framework context instructions are in [references/generation-pipeline.md](references/generation-pipeline.md).
+
+Quick reference:
+1. **Analyze** — scan existing docs, identify gaps
+2. **Plan** — determine doc type, framework, structure
+3. **Generate** — use depth-appropriate prompts (NOT generic "write clearly")
+4. **Validate** — check Diátaxis compliance, completeness, accuracy
+
 ## Writing Style
 
 Follow these rules when generating documentation content. Adapted from *The Elements of Agent Style* (CC BY 4.0, Yue Zhao) and classic writing authorities.
@@ -2102,10 +2063,10 @@ All links in generated docs must be correct relative to the file that contains t
 - ❌ **Reference with Narrative** — opinions in API tables ("I recommend...") → strip opinions to Explanation doc
 - ❌ **Explanation with Procedures** — numbered steps in a conceptual doc → move procedures to How-To
 - ❌ **Mixed-Mode Document** — one doc serving multiple quadrants → split into separate documents per quadrant
-- See [references/diataxis-anti-patterns.md](references/diataxis-anti-patterns.md) for detection signals, counterexamples, and blur zones
+- See [references/diataxis-reference.md](references/diataxis-reference.md) for detection signals, counterexamples, and blur zones
 
 ### Project Knowledge
-- See [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) for environment gotchas and anti-pattern table
+- See [references/project-knowledge-reference.md](references/project-knowledge-reference.md) for environment gotchas and anti-pattern table
 
 ---