@vpxa/aikit 0.1.307 → 0.1.308

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

@@ -158,8 +158,8 @@ Detailed workflow for acquiring and documenting project knowledge into \`docs/ar
 \`\`\`
 onboard({ path: "." })                           # Full codebase scan
 produce_knowledge({ scope: "." })                 # Comprehensive analysis
-analyze({ aspect: "structure", path: "." })      # Project layout, packages, layers
-analyze({ aspect: "dependencies", path: "." })   # All dependencies + import graph
+analyze({ items: [{aspect: "structure", path: "."}] })      # Project layout, packages, layers
+analyze({ items: [{aspect: "dependencies", path: "."}] })   # All dependencies + import graph
 \`\`\`
 
 Then read \`README\`, \`PRD\`, \`TRD\`, \`ROADMAP\`, \`SPEC\`, \`DESIGN\` files if they exist.
@@ -171,13 +171,13 @@ Use Phase 1 tool outputs to answer questions for each of the seven documents. Ru
 
 | 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 |
+| stack.md | \`analyze({ items: [{aspect: "dependencies", ...}] })\` → manifests, frameworks; \`analyze({ items: [{aspect: "structure", ...}] })\` → runtime signals |
+| structure.md | \`analyze({ items: [{aspect: "structure", ...}] })\` → file tree, packages; \`analyze({ items: [{aspect: "entry_points", ...}] })\` → entry points, key files |
+| design.md | \`analyze({ items: [{aspect: "structure", ...}] })\` → layers; \`analyze({ items: [{aspect: "patterns", ...}] })\` → design patterns; \`analyze({ items: [{aspect: "diagram", ...}] })\` → component diagrams |
+| conventions.md | \`analyze({ items: [{aspect: "patterns", ...}] })\` → naming, formatting; \`search("conventions")\` → detected conventions |
+| integrations.md | \`analyze({ items: [{aspect: "dependencies", ...}] })\` → external deps; \`search("API\\|database\\|auth\\|webhook")\` → integration points |
+| testing.md | \`analyze({ items: [{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 |
 
 ### Phase 3: Populate Documents
 
@@ -201,7 +201,7 @@ Rules:
 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
+2. If any required section is missing or unsupported → fix and re-validate
 3. Repeat until all seven docs pass
 
 Validation pass criteria:
@@ -271,9 +271,9 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 \`\`\`
 {root}/
-├── {dir}/    ← {purpose}
-Γöé   ΓööΓöÇΓöÇ ...
-└── {dir}/    ← {purpose}
+├── {dir}/    ← {purpose}
+Γöé   └── ...
+└── {dir}/    ← {purpose}
 \`\`\`
 
 ## Entry Points
@@ -296,8 +296,8 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze({ aspect: "structure", ... })\` output ΓÇö directory tree
-- \`analyze({ aspect: "entry_points", ... })\` output ΓÇö entry points
+- \`analyze({ items: [{aspect: "structure", ...}] })\` output ΓÇö directory tree
+- \`analyze({ items: [{aspect: "entry_points", ...}] })\` output ΓÇö entry points
 \`\`\`
 
 ## design.md
@@ -318,7 +318,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 ## Data Flow
 
 \`\`\`
-{source} → {transform} → {destination}
+{source} → {transform} → {destination}
 \`\`\`
 
 {Brief description of primary data paths.}
@@ -337,9 +337,9 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze({ aspect: "structure", ... })\` output ΓÇö layers
-- \`analyze({ aspect: "patterns", ... })\` output ΓÇö design patterns
-- \`analyze({ aspect: "diagram", ... })\` output ΓÇö component diagrams
+- \`analyze({ items: [{aspect: "structure", ...}] })\` output ΓÇö layers
+- \`analyze({ items: [{aspect: "patterns", ...}] })\` output ΓÇö design patterns
+- \`analyze({ items: [{aspect: "diagram", ...}] })\` output ΓÇö component diagrams
 \`\`\`
 
 ## conventions.md
@@ -377,7 +377,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze({ aspect: "patterns", ... })\` output ΓÇö detected conventions
+- \`analyze({ items: [{aspect: "patterns", ...}] })\` output ΓÇö detected conventions
 - Linter/formatter config files ΓÇö enforced rules
 \`\`\`
 
@@ -416,7 +416,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze({ aspect: "dependencies", ... })\` output ΓÇö external packages
+- \`analyze({ items: [{aspect: "dependencies", ...}] })\` output ΓÇö external packages
 - \`.env.example\` ΓÇö required environment variables
 - CI config files ΓÇö pipeline definitions
 \`\`\`
@@ -458,7 +458,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze({ aspect: "patterns", ... })\` output ΓÇö test patterns
+- \`analyze({ items: [{aspect: "patterns", ...}] })\` output ΓÇö test patterns
 - \`test_run({})\` output ΓÇö test health
 - Test config files ΓÇö framework configuration
 \`\`\`
@@ -531,13 +531,13 @@ Common pitfalls when documenting project knowledge. Reference this during Phase
 
 ## Anti-Pattern Table
 
-| ❌ Don't | ✅ Do instead |
+| ✗ 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", ... })\` |
+| Assume README describes current architecture | Cross-reference with actual file structure via \`analyze({ items: [{aspect: "structure", ...}] })\` |
 | Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in \`concerns.md\` |
 
 ## Acquisition Workflow
@@ -560,19 +560,19 @@ All of the following must be true before finishing:
 
 | 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")\` |
+| \`stack.md\` | Language, runtime, frameworks, dependencies, dev tooling | \`analyze({ items: [{aspect: "dependencies", ...}] })\`, \`analyze({ items: [{aspect: "structure", ...}] })\` |
+| \`structure.md\` | Directory layout, entry points, key files, packages | \`analyze({ items: [{aspect: "structure", ...}] })\`, \`analyze({ items: [{aspect: "entry_points", ...}] })\` |
+| \`design.md\` | Layers, patterns, data flow, component boundaries | \`analyze({ items: [{aspect: "structure", ...}] })\`, \`analyze({ items: [{aspect: "patterns", ...}] })\`, \`analyze({ items: [{aspect: "diagram", ...}] })\` |
+| \`conventions.md\` | Naming, formatting, error handling, import conventions | \`analyze({ items: [{aspect: "patterns", ...}] })\`, \`search("conventions")\` |
+| \`integrations.md\` | External APIs, databases, auth, monitoring, CI/CD | \`analyze({ items: [{aspect: "dependencies", ...}] })\`, \`search("API\\|database\\|auth")\` |
+| \`testing.md\` | Test frameworks, file organization, mocking, coverage | \`analyze({ items: [{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-reference.md](references/project-knowledge-reference.md) for the standard template of each document.
 
 ### Workflow & References
 
-Follow the four-phase workflow: **Scan → Investigate → Populate → Validate**.
+Follow the four-phase workflow: **Scan → Investigate → Populate → Validate**.
 
 - [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
@@ -596,8 +596,8 @@ One-paragraph description of what this component does and why it exists.
 Brief description of the component's public interface.
 
 ## Integration Contracts
-- **Incoming**: {caller/component} → {contract or payload}
-- **Outgoing**: {dependency/component} ← {contract or payload}
+- **Incoming**: {caller/component} → {contract or payload}
+- **Outgoing**: {dependency/component} ← {contract or payload}
 
 ## Design Decisions
 - Link to relevant ADRs: [ADR-NNN](../../decisions/NNN-{title}.md)
@@ -618,7 +618,7 @@ sequenceDiagram
 \`\`\`
 
 ## Error Paths & Failure Modes
-- {failure mode} → {observable symptom} → {recovery or fallback}
+- {failure mode} → {observable symptom} → {recovery or fallback}
 \`\`\`
 
 ### Tutorial Template (\`docs/guides/tutorials/{topic}.md\`)
@@ -740,8 +740,8 @@ Use this template for any generated section that includes factual claims:
 
 | Claim | Evidence | Class |
 |-------|----------|-------|
-| API supports pagination | \`src/routes/users.ts:42\` — \`limit\` and \`offset\` params | ✅ Verified |
-| Rate limiting at 100 req/min | \`src/middleware/rate-limit.ts:15\` — \`rateLimit({ max: 100 })\` | ✅ Verified |
+| API supports pagination | \`src/routes/users.ts:42\` ΓÇö \`limit\` and \`offset\` params | ✓ Verified |
+| Rate limiting at 100 req/min | \`src/middleware/rate-limit.ts:15\` ΓÇö \`rateLimit({ max: 100 })\` | ✓ Verified |
 | Supports multi-tenant isolation | Inferred from \`orgId\` discriminator in queries | 🔍 Inferred |
 | Designed for horizontal scaling | No direct code evidence | ⚠️ Assumed |
 \`\`\`
@@ -782,7 +782,7 @@ Generate dependency-ordered codebase walkthroughs that teach the system through
 
 ### Algorithm
 
-1. \`analyze({ aspect: "entry_points", path: "." })\` ΓÇö find likely tour starting points
+1. \`analyze({ items: [{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
@@ -811,7 +811,7 @@ Each prose step in a markdown tour should name the focus, explain what the reade
 ### Tour Generation Workflow
 
 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
+2. For each step, use \`compact({ items: [{path, query: "purpose and public API"}] })\` to extract key info
 3. Write the tour as \`docs/tours/{topic}.md\`
 4. Generate \`docs/tours/index.md\` linking all tours with descriptions
 
@@ -833,14 +833,14 @@ Guided walkthroughs ordered for understanding.
 
 \`\`\`
 docs/
-ΓööΓöÇΓöÇ tours/
-  Γö£ΓöÇΓöÇ index.md             # Tour listing with descriptions
-  Γö£ΓöÇΓöÇ architecture.md      # System structure tour
-  Γö£ΓöÇΓöÇ data-flow.md         # Data pipeline tour
-  Γö£ΓöÇΓöÇ feature-{name}.md    # Feature-specific tours
-  ΓööΓöÇΓöÇ interactive/
-    Γö£ΓöÇΓöÇ {name}.json        # Tour data injected into viewer
-    ΓööΓöÇΓöÇ {name}.html        # Interactive viewer output
+└── tours/
+  ├── index.md             # Tour listing with descriptions
+  ├── architecture.md      # System structure tour
+  ├── data-flow.md         # Data pipeline tour
+  ├── feature-{name}.md    # Feature-specific tours
+  └── interactive/
+    ├── {name}.json        # Tour data injected into viewer
+    └── {name}.html        # Interactive viewer output
 \`\`\`
 
 ## Interactive JSON Tour (Recommended)
@@ -954,9 +954,9 @@ After generating tour JSON, validate EVERY step's line numbers against the actua
 **Validation snippet:**
 \`\`\`
 For each step:
-  compact({ path: step.file, query: step.title })  → find actual location
-  read_file(step.file, step.line, step.line + 10)   → verify code matches description
-  If mismatch → search({ query: step.explanation }) → find correct file:line
+  compact({ items: [{path: step.file, query: step.title}] })  → find actual location
+  read_file(step.file, step.line, step.line + 10)   → verify code matches description
+  If mismatch → search({ query: step.explanation }) → find correct file:line
 \`\`\`
 
 Tour JSON with stale line numbers is a **quality gate failure**. Fix before saving.
@@ -1118,7 +1118,7 @@ present({
 
 ## Business Domain Documentation
 
-Document the business domain as a three-level hierarchy: **Domain → Flow → Step**. This captures what the system does in business terms, separate from its technical architecture.
+Document the business domain as a three-level hierarchy: **Domain → Flow → Step**. This captures what the system does in business terms, separate from its technical architecture.
 
 ### Hierarchy
 
@@ -1128,9 +1128,9 @@ Document the business domain as a three-level hierarchy: **Domain ΓåÆ Flow Γ
 
 ### Domain Discovery Workflow
 
-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
+1. \`analyze({ items: [{aspect: "structure", path: "."}] })\` ΓÇö identify top-level domain boundaries
+2. \`analyze({ items: [{aspect: "entry_points", path: "."}] })\` ΓÇö detect flow entry types
+3. \`trace({ items: [{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
 
 ### Domain Template (\`docs/architecture/domains/{domain-name}.md\`)
@@ -1168,19 +1168,19 @@ Document the business domain as a three-level hierarchy: **Domain ΓåÆ Flow Γ
 
 | This Domain | Direction | Other Domain | Mechanism |
 |-------------|-----------|--------------|-----------|
-| {current} | → calls | {other} | {API/event/import} |
-| {other} | → notifies | {current} | {event/callback} |
+| {current} | → calls | {other} | {API/event/import} |
+| {other} | → notifies | {current} | {event/callback} |
 \`\`\`
 
 ### Directory Convention
 
 \`\`\`
 docs/
-ΓööΓöÇΓöÇ architecture/
-  ΓööΓöÇΓöÇ domains/
-    Γö£ΓöÇΓöÇ authentication.md
-    Γö£ΓöÇΓöÇ billing.md
-    ΓööΓöÇΓöÇ inventory.md
+└── architecture/
+  └── domains/
+    ├── authentication.md
+    ├── billing.md
+    └── inventory.md
 \`\`\``},{file:`references/tour.schema.json`,content:`{
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "AIKIT Interactive Code Tour",
@@ -1323,10 +1323,10 @@ Structured LLM prompt templates for generating high-quality documentation. Each
 **Phase 1** is deterministic (no LLM needed):
 \`\`\`
 # Deterministic Tour Ranking (run BEFORE LLM)
-1. graph({ action: "find_nodes" }) → get all module nodes
+1. graph({ action: "find_nodes" }) → get all module nodes
 2. Compute for each node:
-   - in_degree (how many import it) → "importance"
-   - out_degree (how many it imports) → "complexity"
+   - in_degree (how many import it) → "importance"
+   - out_degree (how many it imports) → "complexity"
    - centrality = in_degree / (in_degree + out_degree)
 3. Rank by: entry_points FIRST, then by centrality DESC
 4. Group by layer (from layer detection)
@@ -1469,7 +1469,7 @@ You are a domain and architecture analyst. Given files belonging to a business d
     "Rule 2 description"
   ],
   "flows": [
-    { "name": "Flow name", "steps": ["Step 1 → file:fn", "Step 2 → file:fn"], "trigger": "What initiates this" }
+    { "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": [
@@ -1506,9 +1506,9 @@ const priorState = JSON.parse(readFile("docs/.docs-state.json"))
 1. Compute SHA-256 hash of current content
 2. Extract function/class signatures (name + params + return type)
 3. Compare against priorState:
-   - Hash identical → NONE (skip entirely)
-   - Hash different but signatures identical → COSMETIC (update timestamps only)
-   - Signatures changed → STRUCTURAL (full regeneration needed)
+   - Hash identical → NONE (skip entirely)
+   - Hash different but signatures identical → COSMETIC (update timestamps only)
+   - Signatures changed → STRUCTURAL (full regeneration needed)
 4. Output: changeManifest = { none: [...], cosmetic: [...], structural: [...], new: [...] }
 \`\`\`
 
@@ -1539,8 +1539,8 @@ Later phases consume this IR instead of re-reading raw files.
 ### Phase 2 ΓÇö Analyze (deterministic + LLM)
 \`\`\`
 # Identify documentation gaps
-analyze({ aspect: "structure" })                  # All modules
-analyze({ aspect: "entry_points" })              # Tour starting points
+analyze({ items: [{aspect: "structure"}] })                  # All modules
+analyze({ items: [{aspect: "entry_points"}] })              # Tour starting points
 graph({ action: "find_nodes" })                  # Full module graph
 # For each undocumented module: apply File Documentation Prompt
 # For each domain cluster: apply Domain Documentation Prompt
@@ -1550,12 +1550,12 @@ graph({ action: "find_nodes" })                  # Full module graph
 
 **Phase 2a ΓÇö Deterministic (no LLM tokens):**
 \`\`\`
-analyze({ aspect: "structure" })           # File tree, exports, imports
-analyze({ aspect: "symbols" })             # All exported symbols
-analyze({ aspect: "entry_points" })        # Entry points
+analyze({ items: [{aspect: "structure"}] })           # File tree, exports, imports
+analyze({ items: [{aspect: "symbols"}] })             # All exported symbols
+analyze({ items: [{aspect: "entry_points"}] })        # Entry points
 graph({ action: "find_nodes" })            # Module graph
 # For each module:
-file_summary({ path })                     # Structure without reading full file
+file_summary({ items: [{path}] })                     # Structure without reading full file
 # Output: structured JSON with all deterministic facts
 \`\`\`
 
@@ -1574,12 +1574,12 @@ Do NOT re-analyze file structure ΓÇö it is already correct in the input."
 For large codebases, run specialized analyzers in parallel:
 \`\`\`
 # Parallel analyzers (each can be a separate subagent dispatch):
-1. Structure Analyzer → file tree, layers, boundaries
-2. Dependency Analyzer → import graph, cross-package edges
-3. Flow Analyzer → request paths, data transformations
-4. Test Analyzer → test descriptions, coverage signals
-5. Config Analyzer → env vars, feature flags, build config
-6. Existing-Docs Analyzer → scan docs/, README, comments, JSDoc
+1. Structure Analyzer → file tree, layers, boundaries
+2. Dependency Analyzer → import graph, cross-package edges
+3. Flow Analyzer → request paths, data transformations
+4. Test Analyzer → test descriptions, coverage signals
+5. Config Analyzer → env vars, feature flags, build config
+6. Existing-Docs Analyzer → scan docs/, README, comments, JSDoc
 
 # Layer detection consumes ALL analyzer outputs
 \`\`\`
@@ -1591,16 +1591,16 @@ search({ query: "describe\\(|it\\(|test\\(" })
 # OR
 find({ pattern: "(describe|it|test)\\s*\\(" })
 
-# Group by feature area (file path → domain)
+# Group by feature area (file path → domain)
 # Only harvest from:
-✅ BDD: describe("User Authentication", () => { it("should login with valid credentials") })
-✅ E2E: test("checkout flow completes successfully")
-✅ Business: it("calculates tax correctly for international orders")
+✓ BDD: describe("User Authentication", () => { it("should login with valid credentials") })
+✓ E2E: test("checkout flow completes successfully")
+✓ Business: it("calculates tax correctly for international orders")
 
 # Skip:
-❌ Snapshots: it("renders correctly")
-❌ Performance: it("completes within 100ms")
-❌ Internal: it("calls private helper")
+✗ Snapshots: it("renders correctly")
+✗ Performance: it("completes within 100ms")
+✗ Internal: it("calls private helper")
 
 # Output: test-requirement map
 {
@@ -1631,7 +1631,7 @@ graph({ action: "find_nodes" })
 
 # Step 3: Name clusters by:
 # - Directory name (e.g., "authentication" from src/auth/)
-# - Shared export prefix (e.g., "User*" → "User Management")
+# - Shared export prefix (e.g., "User*" → "User Management")
 # - Domain keyword extraction from file names
 
 # Step 4: Validate clusters
@@ -1653,10 +1653,10 @@ graph({ action: "find_nodes" })
 \`\`\`
 
 **Anti-pattern prevention:**
-- ❌ NEVER generate one doc per file → generates useless entries like "dateFormatter utility docs"
-- ✅ ALWAYS cluster files into features → generates meaningful domain documentation
-- ❌ NEVER map file paths directly to PRD sections
-- ✅ ALWAYS map feature clusters to PRD capabilities
+- ✗ NEVER generate one doc per file → generates useless entries like "dateFormatter utility docs"
+- ✓ ALWAYS cluster files into features → generates meaningful domain documentation
+- ✗ NEVER map file paths directly to PRD sections
+- ✓ ALWAYS map feature clusters to PRD capabilities
 
 ### Phase 4 ΓÇö Generate Tours (3-phase)
 \`\`\`
@@ -1691,7 +1691,7 @@ graph({ action: "find_nodes" })
 
 #### Multi-Layer PRD Extraction Detail
 
-**L1 — Direct Harvest (HIGH confidence, ✅ Verified):**
+**L1 ΓÇö Direct Harvest (HIGH confidence, ✓ Verified):**
 \`\`\`
 # Auto-detect and harvest structured specs:
 find({ glob: "**/*.{yaml,yml,json}" })     # OpenAPI/Swagger specs
@@ -1699,27 +1699,27 @@ find({ glob: "**/*.feature" })              # Gherkin/BDD scenarios
 find({ glob: "**/*.graphql" })              # GraphQL schemas
 find({ glob: "**/migrations/**" })          # Database migration files
 
-# Each found spec → direct extraction:
-# OpenAPI → API endpoints, request/response schemas, auth requirements
-# Gherkin → user stories with acceptance criteria
-# GraphQL → data model, query capabilities
-# Migrations → data model evolution
+# Each found spec → direct extraction:
+# OpenAPI → API endpoints, request/response schemas, auth requirements
+# Gherkin → user stories with acceptance criteria
+# GraphQL → data model, query capabilities
+# Migrations → data model evolution
 \`\`\`
 
 **L2 — Pattern Inference (MEDIUM confidence, 🔍 Inferred):**
 \`\`\`
 # Extract from code patterns:
-# API routes → user story inference
+# API routes → user story inference
 find({ pattern: "router\\.(get|post|put|delete|patch)" })
-# → "As a [role], I can [HTTP method] [resource] to [inferred purpose]"
+# → "As a [role], I can [HTTP method] [resource] to [inferred purpose]"
 
-# TypeScript interfaces → data model
-symbol({ name: "interface" })
-# → Data entities with field types and relationships
+# TypeScript interfaces → data model
+symbol({ items: [{name: "interface"}] })
+# → Data entities with field types and relationships
 
-# JSDoc/docstrings → functional requirements
+# JSDoc/docstrings → functional requirements
 find({ pattern: "@description|@summary|@purpose" })
-# → Requirements text from developer documentation
+# → Requirements text from developer documentation
 \`\`\`
 
 **L3 — Reverse Generation (LOW confidence, ⚠️ Assumed):**
@@ -1729,13 +1729,13 @@ find({ pattern: "@description|@summary|@purpose" })
 "What user-facing requirement does this code fulfill?
 Respond with a user story format. Mark confidence as LOW."
 
-# Git history → feature timeline
+# Git history → feature timeline
 git_context({ commit_count: 50 })
-# Group commits by feature area → evolution narrative
+# Group commits by feature area → evolution narrative
 
-# Code comments → developer intent
+# Code comments → developer intent
 find({ pattern: "// TODO|// FIXME|// HACK|// NOTE" })
-# → Technical debt items and design intent
+# → Technical debt items and design intent
 \`\`\`
 
 #### NFR Extraction Detail
@@ -1766,7 +1766,7 @@ find({ pattern: "audit|auditLog|audit.?trail" })
 find({ pattern: "retention|ttl|expiry|purge" })
 find({ pattern: "consent|gdpr|GDPR|pii|PII|redact" })
 
-# Each match → NFR row:
+# Each match → NFR row:
 { category: "Security", pattern: "rateLimit", file: "src/middleware/rate-limit.ts", evidence: "Rate limiter at 100 req/min per IP", nfr: "API must enforce rate limiting at 100 requests per minute per client IP" }
 \`\`\`
 
@@ -1803,8 +1803,8 @@ find({ pattern: "orgId|tenantId|teamId|workspaceId" })
   - Use the c4-architecture skill to produce interactive HTML with ELK auto-layout
   - Save to docs/architecture/interactive/{view-name}.html
 3. Add navigation links:
-  - From docs/architecture/overview.md → link to interactive viewers
-  - From tour steps that reference architecture → link to relevant C4 view
+  - From docs/architecture/overview.md → link to interactive viewers
+  - From tour steps that reference architecture → link to relevant C4 view
 4. Generate documentation hub:
   - Use the present tool's docs-browser block type to create a navigable index
   - Include all markdown docs with status indicators and links to interactive companions
@@ -1827,7 +1827,7 @@ find({ pattern: "orgId|tenantId|teamId|workspaceId" })
   - Each sentence with a specific assertion = one claim
 
 2. For each claim, find its code anchor:
-  - ✅ Verified: claim references specific file:line, function, or test
+  - ✓ Verified: claim references specific file:line, function, or test
   - 🔍 Inferred: claim derived from pattern or docstring
   - ⚠️ Assumed: no direct code anchor found
 
@@ -1842,9 +1842,9 @@ find({ pattern: "orgId|tenantId|teamId|workspaceId" })
   Target: ≥80% for PRDs, ≥70% for architecture docs, ≥90% for API reference
 
 5. Gap report:
-  - Claims with no anchor → "⚠️ Needs human review"
-  - Code with no corresponding doc → "📝 Undocumented"
-  - Sections >50% assumed → add review banner
+  - Claims with no anchor → "ΓÜá∩╕Å Needs human review"
+  - Code with no corresponding doc → "≡ƒô¥ Undocumented"
+  - Sections >50% assumed → add review banner
 \`\`\`
 
 #### Evidence Verification
@@ -1863,25 +1863,25 @@ find({ pattern: "orgId|tenantId|teamId|workspaceId" })
 ### 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
+├── 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
@@ -1891,10 +1891,10 @@ When generating documentation for a specific framework, inject framework-specifi
 ### 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"
+- 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
@@ -1934,8 +1934,8 @@ When generating documentation for a specific framework, inject framework-specifi
 | 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
+- 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
@@ -1966,7 +1966,7 @@ What problem does this solve? Who has this problem? What's the impact of not sol
 
 ### 4. Capabilities
 
-Each capability has a unique ID for tracing requirements → code → tests → docs.
+Each capability has a unique ID for tracing requirements → code → tests → docs.
 
 | capability_id | Name | Description | Status |
 |---------------|------|-------------|--------|
@@ -2020,10 +2020,10 @@ Extracted automatically from code patterns. Each NFR includes code evidence.
 
 | Category | Requirement | Evidence | Confidence |
 |----------|-------------|----------|------------|
-| Performance | [requirement statement] | [file:line pattern found] | ✅/🔍/⚠️ |
-| Security | [requirement statement] | [file:line pattern found] | ✅/🔍/⚠️ |
-| Reliability | [requirement statement] | [file:line pattern found] | ✅/🔍/⚠️ |
-| Compliance | [requirement statement] | [file:line pattern found] | ✅/🔍/⚠️ |
+| Performance | [requirement statement] | [file:line pattern found] | ✓/≡ƒöì/ΓÜá∩╕Å |
+| Security | [requirement statement] | [file:line pattern found] | ✓/≡ƒöì/ΓÜá∩╕Å |
+| Reliability | [requirement statement] | [file:line pattern found] | ✓/≡ƒöì/ΓÜá∩╕Å |
+| Compliance | [requirement statement] | [file:line pattern found] | ✓/≡ƒöì/ΓÜá∩╕Å |
 
 **Extraction patterns (run these searches):**
 - Performance: \`setTimeout\`, \`debounce\`, \`cache\`, \`TTL\`, \`pagination\`, \`pool\`, \`maxConnections\`
@@ -2067,11 +2067,11 @@ Each PRD section carries a confidence rating based on its extraction source:
 
 | Evidence Class | Symbol | Source | Trust Level |
 |----------------|--------|--------|-------------|
-| Verified | ✅ | OpenAPI specs, test assertions, type signatures | High — directly from code |
+| Verified | ✓ | OpenAPI specs, test assertions, type signatures | High ΓÇö directly from code |
 | Inferred | 🔍 | Route patterns, docstrings, naming conventions | Medium — pattern-based |
 | Assumed | ⚠️ | LLM interpretation of implementation code | Low — needs human review |
 
-**Completeness target:** ≥80% of capability claims should be ✅ Verified or 🔍 Inferred.
+**Completeness target:** ΓëÑ80% of capability claims should be ✓ Verified or ≡ƒöì Inferred.
 Sections with >50% ⚠️ Assumed claims must include a review banner.
 
 ---
@@ -2109,8 +2109,8 @@ The PRD index tracks all PRDs and their capabilities for automated cross-referen
 |---------|--------|
 | 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 |
+| 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
 
@@ -2122,21 +2122,21 @@ When bootstrapping \`docs/\` for the first time or refreshing architecture docum
 
 \`\`\`
 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
+  analyze({ items: [{aspect: "structure", path: "."}] })        → project layout, packages, layers
+  analyze({ items: [{aspect: "patterns", path: "."}] })         → conventions, design patterns
+  analyze({ items: [{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
+  analyze({ items: [{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
+  analyze({ items: [{aspect: "diagram", path: "."}] })          → Mermaid architecture diagrams
+  Delegate to c4-architecture skill                    → C4 context/container/component views
 
 Step 4: Synthesize
-  produce_knowledge({ scope: "." })                   → comprehensive analysis
+  produce_knowledge({ scope: "." })                   → comprehensive analysis
   Combine outputs into docs/ structure
 \`\`\`
 
@@ -2146,21 +2146,21 @@ The architecture blueprint should cover these areas (adapted from the Architectu
 
 #### 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
+- **Tools**: \`analyze({ items: [{aspect: "structure", ...}] })\` → folder organization, \`analyze({ items: [{aspect: "patterns", ...}] })\` → framework detection, \`analyze({ items: [{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", ... })\`
+- **Tools**: \`produce_knowledge\` + \`analyze({ items: [{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
+- **Tools**: \`analyze({ items: [{aspect: "diagram", ...}] })\` + \`c4-architecture\` skill
 - **Output**: \`docs/architecture/overview.md\` diagrams + \`docs/architecture/diagrams/\`
 
 #### 4. Core Architectural Components
@@ -2169,7 +2169,7 @@ For each major component:
 - Internal structure
 - Key abstractions
 - Interaction patterns
-- **Tools**: \`analyze({ aspect: "symbols", path: "component/" })\` + \`compact({ path, query: "exports" })\`
+- **Tools**: \`analyze({ items: [{aspect: "symbols", path: "component/"}] })\` + \`compact({ items: [{path, query: "exports"}] })\`
 - **Output**: \`docs/architecture/components/{name}.md\`
 
 #### 5. Layers & Dependencies
@@ -2177,7 +2177,7 @@ For each major component:
 - Dependency rules between layers
 - Abstraction mechanisms for separation
 - Circular dependencies or violations
-- **Tools**: \`analyze({ aspect: "dependencies", ... })\` + \`graph({ action: 'neighbors' })\`
+- **Tools**: \`analyze({ items: [{aspect: "dependencies", ...}] })\` + \`graph({ action: 'neighbors' })\`
 - **Output**: \`docs/architecture/overview.md\` layers section
 
 #### 6. Cross-Cutting Concerns
@@ -2186,21 +2186,21 @@ Document implementation patterns for:
 - Logging & observability
 - Validation patterns
 - Configuration management
-- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "error handling" })\`
+- **Tools**: \`analyze({ items: [{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" })\`
+- **Tools**: \`analyze({ items: [{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", ... })\`
+- **Tools**: \`analyze({ items: [{aspect: "entry_points", ...}] })\` + \`analyze({ items: [{aspect: "patterns", ...}] })\`
 - **Output**: \`docs/guides/contributing.md\` or \`docs/architecture/overview.md\` extension section
 
 ## Skill Integration
@@ -2337,10 +2337,10 @@ For source-only work, start from analysis output:
 
 \`\`\`
 produce_knowledge({ scope: "." })
-analyze({ aspect: "structure", path: "." })
-analyze({ aspect: "dependencies", path: "." })
-analyze({ aspect: "entry_points", path: "." })
-analyze({ aspect: "patterns", path: "." })
+analyze({ items: [{aspect: "structure", path: "."}] })
+analyze({ items: [{aspect: "dependencies", path: "."}] })
+analyze({ items: [{aspect: "entry_points", path: "."}] })
+analyze({ items: [{aspect: "patterns", path: "."}] })
 \`\`\`
 
 ### 2. Classify the Doc Before Writing
@@ -2400,10 +2400,10 @@ If nothing durable changed, say so explicitly: "No documentation updates needed.
 | Need | Start with |
 |---|---|
 | Project overview | \`produce_knowledge({ scope: "." })\` |
-| Structure or layers | \`analyze({ aspect: "structure", path: "." })\` |
-| Dependency or boundary map | \`analyze({ aspect: "dependencies", path: "." })\` or \`graph(...)\` |
-| Public surface | \`analyze({ aspect: "entry_points", path: "." })\` and \`analyze({ aspect: "symbols", path: ... })\` |
-| Conventions and test patterns | \`analyze({ aspect: "patterns", path: "." })\` |
+| Structure or layers | \`analyze({ items: [{aspect: "structure", path: "."}] })\` |
+| Dependency or boundary map | \`analyze({ items: [{aspect: "dependencies", path: "."}] })\` or \`graph(...)\` |
+| Public surface | \`analyze({ items: [{aspect: "entry_points", path: "."}] })\` and \`analyze({ items: [{aspect: "symbols", path: ...}] })\` |
+| Conventions and test patterns | \`analyze({ items: [{aspect: "patterns", path: "."}] })\` |
 | Update scope | \`git_context({})\` + \`blast_radius({ changed_files: [...] })\` |
 
 Never start by free-writing a big markdown page from memory.