@vpxa/aikit 0.1.65 → 0.1.67

package/scaffold/general/skills/docs/SKILL.md

@@ -1,509 +1,509 @@
----
-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_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_structure({ path: "." })` | File tree, package layout, layer organization → `docs/architecture/overview.md` |
-| Architecture diagrams | `analyze_diagram({ path: "." })` | Mermaid diagrams of component relationships → `docs/architecture/` |
-| Dependency map | `analyze_dependencies({ path: "." })` | Import graph, cross-package edges → `docs/architecture/overview.md` dependencies section |
-| Component analysis | `analyze_symbols({ path: "src/component" })` | Exports, classes, interfaces → `docs/architecture/components/{name}.md` |
-| Entry points / API surface | `analyze_entry_points({ path: "." })` | CLI bins, route handlers, main exports → `docs/reference/api.md` |
-| Code patterns | `analyze_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 by Diátaxis Quadrant
-
-After determining the documentation action, classify the target document's quadrant:
-
-| 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/` |
-
-Use the [Diátaxis Compass](references/diataxis-compass.md) for edge cases and ambiguous content.
-
-## Templates
-
-### Component Doc Template (`docs/architecture/components/{name}.md`)
-
-```markdown
-# {Component Name}
-
-## Purpose
-One-paragraph description of what this component does and why it exists.
-
-## Architecture
-- **Location**: `src/{path}/`
-- **Entry point**: `{file}`
-- **Key dependencies**: {list}
-
-## Public API
-Brief description of the component's public interface.
-
-## Design Decisions
-- Link to relevant ADRs: [ADR-NNN](../../decisions/NNN-{title}.md)
-
-## Data Flow
-How data enters, transforms through, and exits this component.
-```
-
-### Guide Template (`docs/guides/{topic}.md`)
-
-```markdown
-# How to {Task}
-
-## Prerequisites
-What you need before starting.
-
-## Steps
-1. Step one
-2. Step two
-3. Step three
-
-## Verification
-How to confirm it worked.
-
-## Troubleshooting
-Common issues and solutions.
-```
-
-### Reference Template (`docs/reference/{topic}.md`)
-
-```markdown
-# {Topic} Reference
-
-## 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`
-- 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
-
-## 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_dependencies`, `analyze_structure` |
-| `structure.md` | Directory layout, entry points, key files, packages | `analyze_structure`, `analyze_entry_points` |
-| `design.md` | Layers, patterns, data flow, component boundaries | `analyze_structure`, `analyze_patterns`, `analyze_diagram` |
-| `conventions.md` | Naming, formatting, error handling, import conventions | `analyze_patterns`, `search("conventions")` |
-| `integrations.md` | External APIs, databases, auth, monitoring, CI/CD | `analyze_dependencies`, `search("API\|database\|auth")` |
-| `testing.md` | Test frameworks, file organization, mocking, coverage | `analyze_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_structure({ path: "." })                    → project layout, packages, layers
-  analyze_patterns({ path: "." })                     → conventions, design patterns
-  analyze_entry_points({ path: "." })                 → API surface, CLI entry points
-
-Step 2: Map Dependencies
-  analyze_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_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_structure` → folder organization, `analyze_patterns` → framework detection, `analyze_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_structure`
-- **Output**: `docs/architecture/overview.md` main body
-
-#### 3. Architecture Visualization
-- High-level subsystem diagram
-- Component interaction diagrams
-- Data flow diagrams
-- **Tools**: `analyze_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_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_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_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_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_entry_points` + `analyze_patterns`
-- **Output**: `docs/guides/contributing.md` or `docs/architecture/overview.md` extension section
-
-## Rules for the `_docs-sync` Epilogue Step
-
-When this skill is loaded during the `_docs-sync` epilogue:
-
-### 0. Gather Flow Artifacts
-
-Read all available artifacts from the completed flow before assessing code changes:
-
-```
-flow_status()                                      # Get artifactsPath, topic, phase
-find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all flow artifacts
-digest({ sources: [                                # Compress artifacts for context
-  { path: "<found-artifact-1>" },
-  { path: "<found-artifact-2>" },
-  ...
-]})
-```
-
-Map each discovered artifact to documentation actions using [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md).
-
-Read every artifact `find()` returns — different flows produce different files. Focus on artifacts that contain decisions, requirements, and verification results; skip artifacts that only repeat completed work.
-
-If `flow_status()` returns no active flow or no artifacts directory exists, skip this step (source-only mode).
-
-### 1. Assess Changes (tool-driven)
-
-```
-git_context({})                                    # What changed in this flow
-blast_radius({ changed_files: ["changed-files"] }) # Impact analysis
-```
-
-Use the output to classify changes against the Change-to-Doc Mapping decision tree.
-
-### 1b. Classify Target Quadrant
-
-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
-
-Run the [quality checklist](references/diataxis-quality.md) against any doc created or substantially modified.
-
-### 2. Apply the Mapping
-
-Follow the Change-to-Doc Mapping decision tree above to determine required documentation actions.
-
-### 3. Bootstrap `docs/` If Needed (tool-driven)
-
-If `docs/` doesn't exist, run the full Architecture Blueprint workflow:
-
-```
-# Generate content with tools
-produce_knowledge({ path: "." })           # → docs/README.md foundation
-analyze_structure({ path: "." })           # → docs/architecture/overview.md structure section
-analyze_diagram({ path: "." })             # → docs/architecture/ Mermaid diagrams
-analyze_dependencies({ path: "." })        # → docs/architecture/overview.md dependency section
-analyze_entry_points({ path: "." })        # → docs/reference/api.md foundation
-analyze_patterns({ path: "." })            # → docs/architecture/overview.md patterns section
-
-# Create the docs/ tree
-docs/
-├── README.md              ← From produce_knowledge output + project context
-├── architecture/
-│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
-│   └── components/        ← From analyze_symbols per major component
-├── decisions/
-│   └── index.md           ← ADR log (delegate to adr-skill)
-├── guides/
-│   └── testing.md         ← From analyze_patterns test info
-└── reference/
-    └── api.md             ← From analyze_entry_points
-```
-
-### 4. Update Existing Docs (tool-assisted)
-
-- Use `compact({ path: "docs/existing.md", query: "section to update" })` to read the current section
-- Use `blast_radius` output to identify which sections need updating
-- **Don't rewrite** — update relevant sections, preserve existing content
-- **Don't duplicate** — reference code comments/READMEs instead of copying
-
-### 5. Delegate When Appropriate
-
-- Architecture decisions → `adr-skill` → `docs/decisions/`
-- Architecture diagrams → `c4-architecture` skill → `docs/architecture/`
-- Blueprint refresh → Run Blueprint Workflow above
-
-### 6. Update the Index
-
-If docs were added/removed, update `docs/README.md` index.
-
-### 7. Skip If Nothing Changed
-
-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.
-
-## 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.
-
-### Clarity and Precision
-- **Concrete over abstract** — Use specific terms, not vague language ("the retry handler" not "the relevant component")
-- **No needless words** — Cut filler; every sentence earns its place
-- **Active voice when the agent matters** — "The scheduler retries failed jobs" not "Failed jobs are retried"
-- **Affirmative form** — State what something does, not what it does not do (unless a warning)
-- **Claims match evidence** — Do not overstate or understate; back factual claims with file paths or tool output
-
-### Structure
-- **Parallel structure** — Express coordinate ideas in similar form (consistent table columns, consistent list grammar)
-- **Stress position** — Place the important information at the end of the sentence
-- **Sentence variety** — Break sentences over 30 words; vary length to maintain rhythm
-- **Bullets only for genuine lists** — Do not convert flowing prose into bullet points; two items or a sentence do not need bullets
-
-### AI-Tell Avoidance
-- **No dying metaphors** — Avoid "cutting-edge", "leverages", "streamlines", "robust", "seamless"
-- **No transition-word openers** — Do not start paragraphs with "Additionally", "Furthermore", "Moreover"
-- **No em-dash overuse** — Use commas, semicolons, or separate sentences instead
-- **No summary closers** — Do not end every paragraph by restating what it just said
-- **Consistent terminology** — Pick one term and use it throughout; do not alternate synonyms for variety
-
-## Anti-Patterns
-
-### Documentation Maintenance
-- ❌ Documenting implementation details that are obvious from code
-- ❌ Creating docs for every small change (use the mapping tree)
-- ❌ Duplicating information already in code comments or README files
-- ❌ Writing docs that will be immediately outdated (e.g., exact version numbers)
-- ❌ Creating empty placeholder docs "for later"
-- ❌ Rewriting existing docs from scratch instead of updating sections
-
-### Quadrant Mixing (Diátaxis)
-- ❌ **Tutorial with Explanation** — conceptual paragraphs between steps → extract "why" to Explanation doc, link from tutorial
-- ❌ **How-To that Teaches** — "Let's learn..." framing in a task guide → assume competence, link prerequisites
-- ❌ **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
-
-### Project Knowledge
-- See [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) for environment gotchas and anti-pattern table
-
----
-
+---
+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_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_structure({ path: "." })` | File tree, package layout, layer organization → `docs/architecture/overview.md` |
+| Architecture diagrams | `analyze_diagram({ path: "." })` | Mermaid diagrams of component relationships → `docs/architecture/` |
+| Dependency map | `analyze_dependencies({ path: "." })` | Import graph, cross-package edges → `docs/architecture/overview.md` dependencies section |
+| Component analysis | `analyze_symbols({ path: "src/component" })` | Exports, classes, interfaces → `docs/architecture/components/{name}.md` |
+| Entry points / API surface | `analyze_entry_points({ path: "." })` | CLI bins, route handlers, main exports → `docs/reference/api.md` |
+| Code patterns | `analyze_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 by Diátaxis Quadrant
+
+After determining the documentation action, classify the target document's quadrant:
+
+| 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/` |
+
+Use the [Diátaxis Compass](references/diataxis-compass.md) for edge cases and ambiguous content.
+
+## Templates
+
+### Component Doc Template (`docs/architecture/components/{name}.md`)
+
+```markdown
+# {Component Name}
+
+## Purpose
+One-paragraph description of what this component does and why it exists.
+
+## Architecture
+- **Location**: `src/{path}/`
+- **Entry point**: `{file}`
+- **Key dependencies**: {list}
+
+## Public API
+Brief description of the component's public interface.
+
+## Design Decisions
+- Link to relevant ADRs: [ADR-NNN](../../decisions/NNN-{title}.md)
+
+## Data Flow
+How data enters, transforms through, and exits this component.
+```
+
+### Guide Template (`docs/guides/{topic}.md`)
+
+```markdown
+# How to {Task}
+
+## Prerequisites
+What you need before starting.
+
+## Steps
+1. Step one
+2. Step two
+3. Step three
+
+## Verification
+How to confirm it worked.
+
+## Troubleshooting
+Common issues and solutions.
+```
+
+### Reference Template (`docs/reference/{topic}.md`)
+
+```markdown
+# {Topic} Reference
+
+## 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`
+- 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
+
+## 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_dependencies`, `analyze_structure` |
+| `structure.md` | Directory layout, entry points, key files, packages | `analyze_structure`, `analyze_entry_points` |
+| `design.md` | Layers, patterns, data flow, component boundaries | `analyze_structure`, `analyze_patterns`, `analyze_diagram` |
+| `conventions.md` | Naming, formatting, error handling, import conventions | `analyze_patterns`, `search("conventions")` |
+| `integrations.md` | External APIs, databases, auth, monitoring, CI/CD | `analyze_dependencies`, `search("API\|database\|auth")` |
+| `testing.md` | Test frameworks, file organization, mocking, coverage | `analyze_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_structure({ path: "." })                    → project layout, packages, layers
+  analyze_patterns({ path: "." })                     → conventions, design patterns
+  analyze_entry_points({ path: "." })                 → API surface, CLI entry points
+
+Step 2: Map Dependencies
+  analyze_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_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_structure` → folder organization, `analyze_patterns` → framework detection, `analyze_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_structure`
+- **Output**: `docs/architecture/overview.md` main body
+
+#### 3. Architecture Visualization
+- High-level subsystem diagram
+- Component interaction diagrams
+- Data flow diagrams
+- **Tools**: `analyze_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_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_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_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_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_entry_points` + `analyze_patterns`
+- **Output**: `docs/guides/contributing.md` or `docs/architecture/overview.md` extension section
+
+## Rules for the `_docs-sync` Epilogue Step
+
+When this skill is loaded during the `_docs-sync` epilogue:
+
+### 0. Gather Flow Artifacts
+
+Read all available artifacts from the completed flow before assessing code changes:
+
+```
+flow_status()                                      # Get artifactsPath, topic, phase
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all flow artifacts
+digest({ sources: [                                # Compress artifacts for context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Map each discovered artifact to documentation actions using [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md).
+
+Read every artifact `find()` returns — different flows produce different files. Focus on artifacts that contain decisions, requirements, and verification results; skip artifacts that only repeat completed work.
+
+If `flow_status()` returns no active flow or no artifacts directory exists, skip this step (source-only mode).
+
+### 1. Assess Changes (tool-driven)
+
+```
+git_context({})                                    # What changed in this flow
+blast_radius({ changed_files: ["changed-files"] }) # Impact analysis
+```
+
+Use the output to classify changes against the Change-to-Doc Mapping decision tree.
+
+### 1b. Classify Target Quadrant
+
+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
+
+Run the [quality checklist](references/diataxis-quality.md) against any doc created or substantially modified.
+
+### 2. Apply the Mapping
+
+Follow the Change-to-Doc Mapping decision tree above to determine required documentation actions.
+
+### 3. Bootstrap `docs/` If Needed (tool-driven)
+
+If `docs/` doesn't exist, run the full Architecture Blueprint workflow:
+
+```
+# Generate content with tools
+produce_knowledge({ path: "." })           # → docs/README.md foundation
+analyze_structure({ path: "." })           # → docs/architecture/overview.md structure section
+analyze_diagram({ path: "." })             # → docs/architecture/ Mermaid diagrams
+analyze_dependencies({ path: "." })        # → docs/architecture/overview.md dependency section
+analyze_entry_points({ path: "." })        # → docs/reference/api.md foundation
+analyze_patterns({ path: "." })            # → docs/architecture/overview.md patterns section
+
+# Create the docs/ tree
+docs/
+├── README.md              ← From produce_knowledge output + project context
+├── architecture/
+│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
+│   └── components/        ← From analyze_symbols per major component
+├── decisions/
+│   └── index.md           ← ADR log (delegate to adr-skill)
+├── guides/
+│   └── testing.md         ← From analyze_patterns test info
+└── reference/
+    └── api.md             ← From analyze_entry_points
+```
+
+### 4. Update Existing Docs (tool-assisted)
+
+- Use `compact({ path: "docs/existing.md", query: "section to update" })` to read the current section
+- Use `blast_radius` output to identify which sections need updating
+- **Don't rewrite** — update relevant sections, preserve existing content
+- **Don't duplicate** — reference code comments/READMEs instead of copying
+
+### 5. Delegate When Appropriate
+
+- Architecture decisions → `adr-skill` → `docs/decisions/`
+- Architecture diagrams → `c4-architecture` skill → `docs/architecture/`
+- Blueprint refresh → Run Blueprint Workflow above
+
+### 6. Update the Index
+
+If docs were added/removed, update `docs/README.md` index.
+
+### 7. Skip If Nothing Changed
+
+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.
+
+## 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.
+
+### Clarity and Precision
+- **Concrete over abstract** — Use specific terms, not vague language ("the retry handler" not "the relevant component")
+- **No needless words** — Cut filler; every sentence earns its place
+- **Active voice when the agent matters** — "The scheduler retries failed jobs" not "Failed jobs are retried"
+- **Affirmative form** — State what something does, not what it does not do (unless a warning)
+- **Claims match evidence** — Do not overstate or understate; back factual claims with file paths or tool output
+
+### Structure
+- **Parallel structure** — Express coordinate ideas in similar form (consistent table columns, consistent list grammar)
+- **Stress position** — Place the important information at the end of the sentence
+- **Sentence variety** — Break sentences over 30 words; vary length to maintain rhythm
+- **Bullets only for genuine lists** — Do not convert flowing prose into bullet points; two items or a sentence do not need bullets
+
+### AI-Tell Avoidance
+- **No dying metaphors** — Avoid "cutting-edge", "leverages", "streamlines", "robust", "seamless"
+- **No transition-word openers** — Do not start paragraphs with "Additionally", "Furthermore", "Moreover"
+- **No em-dash overuse** — Use commas, semicolons, or separate sentences instead
+- **No summary closers** — Do not end every paragraph by restating what it just said
+- **Consistent terminology** — Pick one term and use it throughout; do not alternate synonyms for variety
+
+## Anti-Patterns
+
+### Documentation Maintenance
+- ❌ Documenting implementation details that are obvious from code
+- ❌ Creating docs for every small change (use the mapping tree)
+- ❌ Duplicating information already in code comments or README files
+- ❌ Writing docs that will be immediately outdated (e.g., exact version numbers)
+- ❌ Creating empty placeholder docs "for later"
+- ❌ Rewriting existing docs from scratch instead of updating sections
+
+### Quadrant Mixing (Diátaxis)
+- ❌ **Tutorial with Explanation** — conceptual paragraphs between steps → extract "why" to Explanation doc, link from tutorial
+- ❌ **How-To that Teaches** — "Let's learn..." framing in a task guide → assume competence, link prerequisites
+- ❌ **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
+
+### Project Knowledge
+- See [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) for environment gotchas and anti-pattern table
+
+---
+
 *Diátaxis content in this skill and its reference files is adapted from the [Diátaxis framework](https://diataxis.fr/) by Daniele Procida, used under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).*