feat(story-6.4): implement hallucination-free documentation with Memtrace graph queries

.agents/skills/bmad-agent-tech-writer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: bmad-agent-tech-writer
+description: Technical documentation specialist and knowledge curator. Use when the user asks to talk to Paige or requests the tech writer.
+---
+
+# Paige — Technical Writer
+
+## Overview
+
+You are Paige, the Technical Writer. You transform complex concepts into accessible, structured documentation — writing for the reader's task, favoring diagrams when they carry more signal than prose, and adapting depth to audience. Master of CommonMark, DITA, OpenAPI, and Mermaid.
+
+## Conventions
+
+- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Adopt Persona
+
+Adopt the Paige / Technical Writer identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
+
+Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 6: Greet the User
+
+Greet `{user_name}` warmly by name as Paige, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
+
+Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Paige, let's document this codebase"), skip the menu and dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+
+Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
+
+From here, Paige stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.

.agents/skills/bmad-agent-tech-writer/customize.toml

@@ -0,0 +1,82 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Paige, the Technical Writer, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "Paige"
+title = "Technical Writer"
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "📚"
+
+# Steps to run before the standard activation (persona, config, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before presenting the menu.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the agent keeps in mind for the whole session (org rules,
+# domain constants, user preferences). Distinct from the runtime memory
+# sidecar — these are static context loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+  "Memtrace structural documentation capabilities are available for brownfield project documentation. When documenting a project via the bmad-document-project workflow, use Memtrace MCP tools as the primary discovery mechanism: get_directory_tree for directory structure, list_communities for module boundaries, find_api_endpoints and get_api_topology for API surface mapping, find_symbol for exported symbol discovery, get_symbol_context for caller/callee/type relationships, analyze_relationships and find_dependency_path for dependency graphs, find_central_symbols and find_bridge_symbols for architectural insight. All graph queries MUST use sequential for...of with await — NEVER Promise.all. Check index freshness via list_indexed_repositories before trusting graph output. Memtrace data is advisory — fall back to heuristic file-reading when Memtrace is unavailable. NEVER block the documentation workflow on Memtrace availability. Prefer summarized output to stay under 2000 token limit.",
+]
+
+role = "Capture and curate project knowledge so humans and future LLM agents stay in sync during the BMad Method analysis phase."
+identity = "Writes with Julia Evans's accessibility and Edward Tufte's visual precision."
+communication_style = "Patient educator — explains like teaching a friend. Every analogy earns its place."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "Write for the reader's task, not the writer's checklist.",
+  "A diagram beats a thousand-word paragraph.",
+  "Audience-aware: simplify or detail as the reader needs.",
+]
+
+# Capabilities menu. Overrides merge by `code`: matching codes replace the item
+# in place, new codes append. Each item has exactly one of `skill` (invokes a
+# registered skill by name) or `prompt` (executes the prompt text directly).
+
+[[agent.menu]]
+code = "DP"
+description = "Generate comprehensive project documentation (brownfield analysis, architecture scanning)"
+skill = "bmad-document-project"
+
+[[agent.menu]]
+code = "WD"
+description = "Author a document following documentation best practices through guided conversation"
+prompt = "Read and follow the instructions in {skill-root}/write-document.md"
+
+[[agent.menu]]
+code = "MG"
+description = "Create a Mermaid-compliant diagram based on your description"
+prompt = "Read and follow the instructions in {skill-root}/mermaid-gen.md"
+
+[[agent.menu]]
+code = "VD"
+description = "Validate documentation against standards and best practices"
+prompt = "Read and follow the instructions in {skill-root}/validate-doc.md"
+
+[[agent.menu]]
+code = "EC"
+description = "Create clear technical explanations with examples and diagrams"
+prompt = "Read and follow the instructions in {skill-root}/explain-concept.md"

.agents/skills/bmad-agent-tech-writer/explain-concept.md

@@ -0,0 +1,20 @@
+---
+name: explain-concept
+description: Create clear technical explanations with examples
+menu-code: EC
+---
+
+# Explain Concept
+
+Create a clear technical explanation with examples and diagrams for a complex concept.
+
+## Process
+
+1. **Understand the concept** — Clarify what needs to be explained and the target audience
+2. **Structure** — Break it down into digestible sections using a task-oriented approach
+3. **Illustrate** — Include code examples and Mermaid diagrams where helpful
+4. **Deliver** — Present the explanation in clear, accessible language appropriate for the audience
+
+## Output
+
+A structured explanation with examples and diagrams that makes the complex simple.

.agents/skills/bmad-agent-tech-writer/mermaid-gen.md

@@ -0,0 +1,20 @@
+---
+name: mermaid-gen
+description: Create Mermaid-compliant diagrams
+menu-code: MG
+---
+
+# Mermaid Generate
+
+Create a Mermaid diagram based on user description through multi-turn conversation until the complete details are understood.
+
+## Process
+
+1. **Understand the ask** — Clarify what needs to be visualized
+2. **Suggest diagram type** — If not specified, suggest diagram types based on the ask (flowchart, sequence, class, state, ER, etc.)
+3. **Generate** — Create the diagram strictly following Mermaid syntax and CommonMark fenced code block standards
+4. **Iterate** — Refine based on user feedback
+
+## Output
+
+A Mermaid diagram in a fenced code block, ready to render.

.agents/skills/bmad-agent-tech-writer/validate-doc.md

@@ -0,0 +1,19 @@
+---
+name: validate-doc
+description: Validate documentation against standards and best practices
+menu-code: VD
+---
+
+# Validate Documentation
+
+Review the specified document against documentation best practices along with anything additional the user asked you to focus on.
+
+## Process
+
+1. **Load the document** — Read the specified document fully
+2. **Analyze** — Review against documentation standards, clarity, structure, audience-appropriateness, and any user-specified focus areas
+3. **Report** — Return specific, actionable improvement suggestions organized by priority
+
+## Output
+
+A prioritized list of specific, actionable improvement suggestions.

.agents/skills/bmad-agent-tech-writer/write-document.md

@@ -0,0 +1,20 @@
+---
+name: write-document
+description: Author a document following documentation best practices
+menu-code: WD
+---
+
+# Write Document
+
+Engage in multi-turn conversation until you fully understand the ask. Use a subprocess if available for any web search, research, or document review required to extract and return only relevant info to the parent context.
+
+## Process
+
+1. **Discover intent** — Ask clarifying questions until the document scope, audience, and purpose are clear
+2. **Research** — If the user provides references or the topic requires it, use subagents to review documents and extract relevant information
+3. **Draft** — Author the document following documentation best practices: clear structure, task-oriented approach, diagrams where helpful
+4. **Review** — Use a subprocess to review and revise for quality of content and standards compliance
+
+## Output
+
+A complete, well-structured document ready for use.

.agents/skills/bmad-code-review/steps/step-01-gather-context.md

@@ -40,6 +40,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` flag is mandatory
 - `--summarize` flag required for blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code audit, continue with heuristic review
+- Stale index (`[FRESHNESS]` in STDERR) → skip graph queries, proceed with existing review logic
+- Partial failure → note diagnostic, apply available data, do not halt the review
+- NEVER block the code review workflow on Memtrace availability
+
 ---
 
 ## RULES

.agents/skills/bmad-code-review/steps/step-02-review.md

@@ -35,6 +35,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` flag is mandatory
 - `--summarize` flag required for blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code audit, continue with heuristic review
+- Stale index (`[FRESHNESS]` in STDERR) → skip graph queries, proceed with existing review logic
+- Partial failure → note diagnostic, apply available data, do not halt the review
+- NEVER block the code review workflow on Memtrace availability
+
 ---
 
 ## RULES

.agents/skills/bmad-document-project/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: bmad-document-project
+description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
+---
+
+# Document Project Workflow
+
+**Goal:** Document brownfield projects for AI context.
+
+**Your Role:** Project documentation specialist.
+
+## Conventions
+
+- Bare paths (e.g. `instructions.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+Greet `{user_name}` (if you have not already), speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## Execution
+
+Read fully and follow: `./instructions.md`

.agents/skills/bmad-document-project/checklist.md

@@ -0,0 +1,245 @@
+# Document Project Workflow - Validation Checklist
+
+## Scan Level and Resumability
+
+- [ ] Scan level selection offered (quick/deep/exhaustive) for initial_scan and full_rescan modes
+- [ ] Deep-dive mode automatically uses exhaustive scan (no choice given)
+- [ ] Quick scan does NOT read source files (only patterns, configs, manifests)
+- [ ] Deep scan reads files in critical directories per project type
+- [ ] Exhaustive scan reads ALL source files (excluding node_modules, dist, build)
+- [ ] State file (project-scan-report.json) created at workflow start
+- [ ] State file updated after each step completion
+- [ ] State file contains all required fields per schema
+- [ ] Resumability prompt shown if state file exists and is <24 hours old
+- [ ] Old state files (>24 hours) automatically archived
+- [ ] Resume functionality loads previous state correctly
+- [ ] Workflow can jump to correct step when resuming
+
+## Write-as-you-go Architecture
+
+- [ ] Each document written to disk IMMEDIATELY after generation
+- [ ] Document validation performed right after writing (section-level)
+- [ ] State file updated after each document is written
+- [ ] Detailed findings purged from context after writing (only summaries kept)
+- [ ] Context contains only high-level summaries (1-2 sentences per section)
+- [ ] No accumulation of full project analysis in memory
+
+## Batching Strategy (Deep/Exhaustive Scans)
+
+- [ ] Batching applied for deep and exhaustive scan levels
+- [ ] Batches organized by SUBFOLDER (not arbitrary file count)
+- [ ] Large files (>5000 LOC) handled with appropriate judgment
+- [ ] Each batch: read files, extract info, write output, validate, purge context
+- [ ] Batch completion tracked in state file (batches_completed array)
+- [ ] Batch summaries kept in context (1-2 sentences max)
+
+## Project Detection and Classification
+
+- [ ] Project type correctly identified and matches actual technology stack
+- [ ] Multi-part vs single-part structure accurately detected
+- [ ] All project parts identified if multi-part (no missing client/server/etc.)
+- [ ] Documentation requirements loaded for each part type
+- [ ] Architecture registry match is appropriate for detected stack
+
+## Technology Stack Analysis
+
+- [ ] All major technologies identified (framework, language, database, etc.)
+- [ ] Versions captured where available
+- [ ] Technology decision table is complete and accurate
+- [ ] Dependencies and libraries documented
+- [ ] Build tools and package managers identified
+
+## Codebase Scanning Completeness
+
+- [ ] All critical directories scanned based on project type
+- [ ] API endpoints documented (if requires_api_scan = true)
+- [ ] Data models captured (if requires_data_models = true)
+- [ ] State management patterns identified (if requires_state_management = true)
+- [ ] UI components inventoried (if requires_ui_components = true)
+- [ ] Configuration files located and documented
+- [ ] Authentication/security patterns identified
+- [ ] Entry points correctly identified
+- [ ] Integration points mapped (for multi-part projects)
+- [ ] Test files and patterns documented
+
+## Source Tree Analysis
+
+- [ ] Complete directory tree generated with no major omissions
+- [ ] Critical folders highlighted and described
+- [ ] Entry points clearly marked
+- [ ] Integration paths noted (for multi-part)
+- [ ] Asset locations identified (if applicable)
+- [ ] File organization patterns explained
+
+## Architecture Documentation Quality
+
+- [ ] Architecture document uses appropriate template from registry
+- [ ] All template sections filled with relevant information (no placeholders)
+- [ ] Technology stack section is comprehensive
+- [ ] Architecture pattern clearly explained
+- [ ] Data architecture documented (if applicable)
+- [ ] API design documented (if applicable)
+- [ ] Component structure explained (if applicable)
+- [ ] Source tree included and annotated
+- [ ] Testing strategy documented
+- [ ] Deployment architecture captured (if config found)
+
+## Development and Operations Documentation
+
+- [ ] Prerequisites clearly listed
+- [ ] Installation steps documented
+- [ ] Environment setup instructions provided
+- [ ] Local run commands specified
+- [ ] Build process documented
+- [ ] Test commands and approach explained
+- [ ] Deployment process documented (if applicable)
+- [ ] CI/CD pipeline details captured (if found)
+- [ ] Contribution guidelines extracted (if found)
+
+## Multi-Part Project Specific (if applicable)
+
+- [ ] Each part documented separately
+- [ ] Part-specific architecture files created (architecture-{part_id}.md)
+- [ ] Part-specific component inventories created (if applicable)
+- [ ] Part-specific development guides created
+- [ ] Integration architecture document created
+- [ ] Integration points clearly defined with type and details
+- [ ] Data flow between parts explained
+- [ ] project-parts.json metadata file created
+
+## Index and Navigation
+
+- [ ] index.md created as master entry point
+- [ ] Project structure clearly summarized in index
+- [ ] Quick reference section complete and accurate
+- [ ] All generated docs linked from index
+- [ ] All existing docs linked from index (if found)
+- [ ] Getting started section provides clear next steps
+- [ ] AI-assisted development guidance included
+- [ ] Navigation structure matches project complexity (simple for single-part, detailed for multi-part)
+
+## File Completeness
+
+- [ ] index.md generated
+- [ ] project-overview.md generated
+- [ ] source-tree-analysis.md generated
+- [ ] architecture.md (or per-part) generated
+- [ ] component-inventory.md (or per-part) generated if UI components exist
+- [ ] development-guide.md (or per-part) generated
+- [ ] api-contracts.md (or per-part) generated if APIs documented
+- [ ] data-models.md (or per-part) generated if data models found
+- [ ] deployment-guide.md generated if deployment config found
+- [ ] contribution-guide.md generated if guidelines found
+- [ ] integration-architecture.md generated if multi-part
+- [ ] project-parts.json generated if multi-part
+
+## Content Quality
+
+- [ ] Technical information is accurate and specific
+- [ ] No generic placeholders or "TODO" items remain
+- [ ] Examples and code snippets are relevant to actual project
+- [ ] File paths and directory references are correct
+- [ ] Technology names and versions are accurate
+- [ ] Terminology is consistent across all documents
+- [ ] Descriptions are clear and actionable
+
+## Brownfield PRD Readiness
+
+- [ ] Documentation provides enough context for AI to understand existing system
+- [ ] Integration points are clear for planning new features
+- [ ] Reusable components are identified for leveraging in new work
+- [ ] Data models are documented for schema extension planning
+- [ ] API contracts are documented for endpoint expansion
+- [ ] Code conventions and patterns are captured for consistency
+- [ ] Architecture constraints are clear for informed decision-making
+
+## Output Validation
+
+- [ ] All files saved to correct output folder
+- [ ] File naming follows convention (no part suffix for single-part, with suffix for multi-part)
+- [ ] No broken internal links between documents
+- [ ] Markdown formatting is correct and renders properly
+- [ ] JSON files are valid (project-parts.json if applicable)
+
+## Final Validation
+
+- [ ] User confirmed project classification is accurate
+- [ ] User provided any additional context needed
+- [ ] All requested areas of focus addressed
+- [ ] Documentation is immediately usable for brownfield PRD workflow
+- [ ] No critical information gaps identified
+
+## Issues Found
+
+### Critical Issues (must fix before completion)
+
+-
+
+### Minor Issues (can be addressed later)
+
+-
+
+### Missing Information (to note for user)
+
+-
+
+## Deep-Dive Mode Validation (if deep-dive was performed)
+
+- [ ] Deep-dive target area correctly identified and scoped
+- [ ] All files in target area read completely (no skipped files)
+- [ ] File inventory includes all exports with complete signatures
+- [ ] Dependencies mapped for all files
+- [ ] Dependents identified (who imports each file)
+- [ ] Code snippets included for key implementation details
+- [ ] Patterns and design approaches documented
+- [ ] State management strategy explained
+- [ ] Side effects documented (API calls, DB queries, etc.)
+- [ ] Error handling approaches captured
+- [ ] Testing files and coverage documented
+- [ ] TODOs and comments extracted
+- [ ] Dependency graph created showing relationships
+- [ ] Data flow traced through the scanned area
+- [ ] Integration points with rest of codebase identified
+- [ ] Related code and similar patterns found outside scanned area
+- [ ] Reuse opportunities documented
+- [ ] Implementation guidance provided
+- [ ] Modification instructions clear
+- [ ] Index.md updated with deep-dive link
+- [ ] Deep-dive documentation is immediately useful for implementation
+
+---
+
+## State File Quality
+
+- [ ] State file is valid JSON (no syntax errors)
+- [ ] State file is optimized (no pretty-printing, minimal whitespace)
+- [ ] State file contains all completed steps with timestamps
+- [ ] State file outputs_generated list is accurate and complete
+- [ ] State file resume_instructions are clear and actionable
+- [ ] State file findings contain only high-level summaries (not detailed data)
+- [ ] State file can be successfully loaded for resumption
+
+## Completion Criteria
+
+All items in the following sections must be checked:
+
+- ✓ Scan Level and Resumability
+- ✓ Write-as-you-go Architecture
+- ✓ Batching Strategy (if deep/exhaustive scan)
+- ✓ Project Detection and Classification
+- ✓ Technology Stack Analysis
+- ✓ Architecture Documentation Quality
+- ✓ Index and Navigation
+- ✓ File Completeness
+- ✓ Brownfield PRD Readiness
+- ✓ State File Quality
+- ✓ Deep-Dive Mode Validation (if applicable)
+
+The workflow is complete when:
+
+1. All critical checklist items are satisfied
+2. No critical issues remain
+3. User has reviewed and approved the documentation
+4. Generated docs are ready for use in brownfield PRD workflow
+5. Deep-dive docs (if any) are comprehensive and implementation-ready
+6. State file is valid and can enable resumption if interrupted

.agents/skills/bmad-document-project/customize.toml

@@ -0,0 +1,42 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-document-project. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All briefs must include a regulatory-risk section."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+  "Memtrace structural documentation capabilities are available during brownfield project documentation. Use Memtrace MCP tools as the primary discovery mechanism: get_directory_tree (mode=compact/verbose, max_depth=6) for directory structure, list_communities (min_size=3) for logical module boundaries, find_api_endpoints (limit=200) for API surface mapping, get_api_topology (include_external=false, min_confidence=0.7) for cross-service call topology, find_symbol (kind=Function/Method/Class/Interface, limit=200) for exported symbol discovery, get_symbol_context for caller/callee/type/community/process data per symbol, analyze_relationships (query_type=find_callers/find_callees/imports/exporters) for dependency graphs, find_dependency_path for execution path tracing, find_central_symbols (limit=20) and find_bridge_symbols (limit=15) for architectural significance. Use list_indexed_repositories to check index freshness before EVERY query. All graph queries MUST use sequential for...of with await — NEVER Promise.all. Memtrace graph data is the PRIMARY discovery source when available; fall back to heuristic file-reading when Memtrace is unavailable. NEVER block the documentation workflow on Memtrace availability. Prefer summarized output to stay under 2000 token limit. Cap symbol batches at 200. Graph data enriches — does not replace — the existing file-reading logic.",
+]
+
+# Scalar: executed when the workflow reaches its terminal stage, after
+# the main output has been delivered. Override wins. Leave empty for
+# no custom post-completion behavior.
+
+on_complete = ""

.agents/skills/bmad-document-project/documentation-requirements.csv

@@ -0,0 +1,12 @@
+project_type_id,requires_api_scan,requires_data_models,requires_state_management,requires_ui_components,requires_deployment_config,key_file_patterns,critical_directories,integration_scan_patterns,test_file_patterns,config_patterns,auth_security_patterns,schema_migration_patterns,entry_point_patterns,shared_code_patterns,monorepo_workspace_patterns,async_event_patterns,ci_cd_patterns,asset_patterns,hardware_interface_patterns,protocol_schema_patterns,localization_patterns,requires_hardware_docs,requires_asset_inventory
+web,true,true,true,true,true,package.json;tsconfig.json;*.config.js;*.config.ts;vite.config.*;webpack.config.*;next.config.*;nuxt.config.*,src/;app/;pages/;components/;api/;lib/;styles/;public/;static/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.spec.ts;*.test.tsx;*.spec.tsx;**/__tests__/**;**/*.test.*;**/*.spec.*,.env*;config/*;*.config.*;.config/;settings/,*auth*.ts;*session*.ts;middleware/auth*;*.guard.ts;*authenticat*;*permission*;guards/,migrations/**;prisma/**;*.prisma;alembic/**;knex/**;*migration*.sql;*migration*.ts,main.ts;index.ts;app.ts;server.ts;_app.tsx;_app.ts;layout.tsx,shared/**;common/**;utils/**;lib/**;helpers/**;@*/**;packages/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json;workspace.json;rush.json,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;jobs/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;bitbucket-pipelines.yml,.drone.yml,public/**;static/**;assets/**;images/**;media/**,N/A,*.proto;*.graphql;graphql/**;schema.graphql;*.avro;openapi.*;swagger.*,i18n/**;locales/**;lang/**;translations/**;messages/**;*.po;*.pot,false,false
+mobile,true,true,true,true,true,package.json;pubspec.yaml;Podfile;build.gradle;app.json;capacitor.config.*;ionic.config.json,src/;app/;screens/;components/;services/;models/;assets/;ios/;android/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.test.tsx;*_test.dart;*.test.dart;**/__tests__/**,.env*;config/*;app.json;capacitor.config.*;google-services.json;GoogleService-Info.plist,*auth*.ts;*session*.ts;*authenticat*;*permission*;*biometric*;secure-store*,migrations/**;realm/**;*.realm;watermelondb/**;sqlite/**,main.ts;index.ts;App.tsx;App.ts;main.dart,shared/**;common/**;utils/**;lib/**;components/shared/**;@*/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json,*event*.ts;*notification*.ts;*push*.ts;background-fetch*,fastlane/**;.github/workflows/**;.gitlab-ci.yml;bitbucket-pipelines.yml;appcenter-*,assets/**;Resources/**;res/**;*.xcassets;drawable*/;mipmap*/;images/**,N/A,*.proto;graphql/**;*.graphql,i18n/**;locales/**;translations/**;*.strings;*.xml,false,true
+backend,true,true,false,false,true,package.json;requirements.txt;go.mod;Gemfile;pom.xml;build.gradle;Cargo.toml;*.csproj,src/;api/;services/;models/;routes/;controllers/;middleware/;handlers/;repositories/;domain/,*client.ts;*repository.ts;*service.ts;*connector*.ts;*adapter*.ts,*.test.ts;*.spec.ts;*_test.go;test_*.py;*Test.java;*_test.rs,.env*;config/*;*.config.*;application*.yml;application*.yaml;appsettings*.json;settings.py,*auth*.ts;*session*.ts;*authenticat*;*authorization*;middleware/auth*;guards/;*jwt*;*oauth*,migrations/**;alembic/**;flyway/**;liquibase/**;prisma/**;*.prisma;*migration*.sql;*migration*.ts;db/migrate,main.ts;index.ts;server.ts;app.ts;main.go;main.py;Program.cs;__init__.py,shared/**;common/**;utils/**;lib/**;core/**;@*/**;pkg/**,pnpm-workspace.yaml;lerna.json;nx.json;go.work,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;*handler*.ts;jobs/**;workers/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;.drone.yml,N/A,N/A,*.proto;*.graphql;graphql/**;*.avro;*.thrift;openapi.*;swagger.*;schema/**,N/A,false,false
+cli,false,false,false,false,false,package.json;go.mod;Cargo.toml;setup.py;pyproject.toml;*.gemspec,src/;cmd/;cli/;bin/;lib/;commands/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*_spec.rb,.env*;config/*;*.config.*;.*.rc;.*rc,N/A,N/A,main.ts;index.ts;cli.ts;main.go;main.py;__main__.py;bin/*,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;goreleaser.yml,N/A,N/A,N/A,N/A,false,false
+library,false,false,false,false,false,package.json;setup.py;Cargo.toml;go.mod;*.gemspec;*.csproj;pom.xml,src/;lib/;dist/;pkg/;build/;target/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*Test.java;*_test.rs,.*.rc;tsconfig.json;rollup.config.*;vite.config.*;webpack.config.*,N/A,N/A,index.ts;index.js;lib.rs;main.go;__init__.py,src/**;lib/**;core/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+desktop,false,false,true,true,true,package.json;Cargo.toml;*.csproj;CMakeLists.txt;tauri.conf.json;electron-builder.yml;wails.json,src/;app/;components/;main/;renderer/;resources/;assets/;build/,*service.ts;ipc*.ts;*bridge*.ts;*native*.ts;invoke*,*.test.ts;*.spec.ts;*_test.rs;*.spec.tsx,.env*;config/*;*.config.*;app.config.*;forge.config.*;builder.config.*,*auth*.ts;*session*.ts;keychain*;secure-storage*,N/A,main.ts;index.ts;main.js;src-tauri/main.rs;electron.ts,shared/**;common/**;utils/**;lib/**;components/shared/**,N/A,*event*.ts;*ipc*.ts;*message*.ts,.github/workflows/**;.gitlab-ci.yml;.circleci/**,resources/**;assets/**;icons/**;static/**;build/resources,N/A,N/A,i18n/**;locales/**;translations/**;lang/**,false,true
+game,false,false,true,false,false,*.unity;*.godot;*.uproject;package.json;project.godot,Assets/;Scenes/;Scripts/;Prefabs/;Resources/;Content/;Source/;src/;scenes/;scripts/,N/A,*Test.cs;*_test.gd;*Test.cpp;*.test.ts,.env*;config/*;*.ini;settings/;GameSettings/,N/A,N/A,main.gd;Main.cs;GameManager.cs;main.cpp;index.ts,shared/**;common/**;utils/**;Core/**;Framework/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,Assets/**;Scenes/**;Prefabs/**;Materials/**;Textures/**;Audio/**;Models/**;*.fbx;*.blend;*.shader;*.hlsl;*.glsl;Shaders/**;VFX/**,N/A,N/A,Localization/**;Languages/**;i18n/**,false,true
+data,false,true,false,false,true,requirements.txt;pyproject.toml;dbt_project.yml;airflow.cfg;setup.py;Pipfile,dags/;pipelines/;models/;transformations/;notebooks/;sql/;etl/;jobs/,N/A,test_*.py;*_test.py;tests/**,.env*;config/*;profiles.yml;dbt_project.yml;airflow.cfg,N/A,migrations/**;dbt/models/**;*.sql;schemas/**,main.py;__init__.py;pipeline.py;dag.py,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,*event*.py;*consumer*.py;*producer*.py;*worker*.py;jobs/**;tasks/**,.github/workflows/**;.gitlab-ci.yml;airflow/dags/**,N/A,N/A,*.proto;*.avro;schemas/**;*.parquet,N/A,false,false
+extension,true,false,true,true,false,manifest.json;package.json;wxt.config.ts,src/;popup/;content/;background/;assets/;components/,*message.ts;*runtime.ts;*storage.ts;*tabs.ts,*.test.ts;*.spec.ts;*.test.tsx,.env*;wxt.config.*;webpack.config.*;vite.config.*,*auth*.ts;*session*.ts;*permission*,N/A,index.ts;popup.ts;background.ts;content.ts,shared/**;common/**;utils/**;lib/**,N/A,*message*.ts;*event*.ts;chrome.runtime*;browser.runtime*,.github/workflows/**,assets/**;icons/**;images/**;static/**,N/A,N/A,_locales/**;locales/**;i18n/**,false,false
+infra,false,false,false,false,true,*.tf;*.tfvars;pulumi.yaml;cdk.json;*.yml;*.yaml;Dockerfile;docker-compose*.yml,terraform/;modules/;k8s/;charts/;playbooks/;roles/;policies/;stacks/,N/A,*_test.go;test_*.py;*_test.tf;*_spec.rb,.env*;*.tfvars;config/*;vars/;group_vars/;host_vars/,N/A,N/A,main.tf;index.ts;__main__.py;playbook.yml,modules/**;shared/**;common/**;lib/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+embedded,false,false,false,false,false,platformio.ini;CMakeLists.txt;*.ino;Makefile;*.ioc;mbed-os.lib,src/;lib/;include/;firmware/;drivers/;hal/;bsp/;components/,N/A,test_*.c;*_test.cpp;*_test.c;tests/**,.env*;config/*;sdkconfig;*.json;settings/,N/A,N/A,main.c;main.cpp;main.ino;app_main.c,lib/**;shared/**;common/**;drivers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,N/A,*.h;*.hpp;drivers/**;hal/**;bsp/**;pinout.*;peripheral*;gpio*;*.fzz;schematics/**,*.proto;mqtt*;coap*;modbus*,N/A,true,false

.agents/skills/bmad-document-project/instructions.md

@@ -0,0 +1,128 @@
+# Document Project Workflow Router
+
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
+
+<step n="1" goal="Check for ability to resume and determine workflow mode">
+<action>Check for existing state file at: {project_knowledge}/project-scan-report.json</action>
+
+<check if="project-scan-report.json exists">
+  <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
+  <action>Extract cached project_type_id(s) from state file if present</action>
+  <action>Calculate age of state file (current time - last_updated)</action>
+
+<ask>I found an in-progress workflow state from {{last_updated}}.
+
+    **Current Progress:**
+
+    - Mode: {{mode}}
+    - Scan Level: {{scan_level}}
+    - Completed Steps: {{completed_steps_count}}/{{total_steps}}
+    - Last Step: {{current_step}}
+    - Project Type(s): {{cached_project_types}}
+
+    Would you like to:
+
+    1. **Resume from where we left off** - Continue from step {{current_step}}
+    2. **Start fresh** - Archive old state and begin new scan
+    3. **Cancel** - Exit without changes
+
+    Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set resume_mode = true</action>
+    <action>Set workflow_mode = {{mode}}</action>
+    <action>Load findings summaries from state file</action>
+    <action>Load cached project_type_id(s) from state file</action>
+
+    <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
+    <action>For each cached project_type_id, load ONLY the corresponding row from: ./documentation-requirements.csv</action>
+    <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
+    <action>Store loaded doc requirements for use in remaining steps</action>
+
+    <action>Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
+
+    <check if="workflow_mode == deep_dive">
+      <action>Read fully and follow: ./workflows/deep-dive-workflow.md with resume context</action>
+    </check>
+
+    <check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
+      <action>Read fully and follow: ./workflows/full-scan-workflow.md with resume context</action>
+    </check>
+
+  </check>
+
+  <check if="user selects 2">
+    <action>Create archive directory: {project_knowledge}/.archive/</action>
+    <action>Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display: "Exiting workflow without changes."</action>
+    <action>Exit workflow</action>
+  </check>
+
+  <check if="state file age >= 24 hours">
+    <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
+    <action>Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+</step>
+
+<step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">
+<action>Check if {project_knowledge}/index.md exists</action>
+
+<check if="index.md exists">
+  <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
+  <action>Store as {{existing_doc_date}}, {{existing_structure}}</action>
+
+<ask>I found existing documentation generated on {{existing_doc_date}}.
+
+What would you like to do?
+
+1. **Re-scan entire project** - Update all documentation with latest changes
+2. **Deep-dive into specific area** - Generate detailed documentation for a particular feature/module/folder
+3. **Cancel** - Keep existing documentation as-is
+
+Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set workflow_mode = "full_rescan"</action>
+    <action>Display: "Starting full project rescan..."</action>
+    <action>Read fully and follow: ./workflows/full-scan-workflow.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 2">
+    <action>Set workflow_mode = "deep_dive"</action>
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Display: "Starting deep-dive documentation mode..."</action>
+    <action>Read fully and follow: ./workflows/deep-dive-workflow.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="index.md does not exist">
+  <action>Set workflow_mode = "initial_scan"</action>
+  <action>Display: "No existing documentation found. Starting initial project scan..."</action>
+  <action>Read fully and follow: ./workflows/full-scan-workflow.md</action>
+  <action>After sub-workflow completes, continue to Step 4</action>
+</check>
+
+</step>
+
+</workflow>

.agents/skills/bmad-document-project/templates/deep-dive-template.md

@@ -0,0 +1,345 @@
+# {{target_name}} - Deep Dive Documentation
+
+**Generated:** {{date}}
+**Scope:** {{target_path}}
+**Files Analyzed:** {{file_count}}
+**Lines of Code:** {{total_loc}}
+**Workflow Mode:** Exhaustive Deep-Dive
+
+## Overview
+
+{{target_description}}
+
+**Purpose:** {{target_purpose}}
+**Key Responsibilities:** {{responsibilities}}
+**Integration Points:** {{integration_summary}}
+
+## Complete File Inventory
+
+{{#each files_in_inventory}}
+
+### {{file_path}}
+
+**Purpose:** {{purpose}}
+**Lines of Code:** {{loc}}
+**File Type:** {{file_type}}
+
+**What Future Contributors Must Know:** {{contributor_note}}
+
+**Exports:**
+{{#each exports}}
+
+- `{{signature}}` - {{description}}
+  {{/each}}
+
+**Dependencies:**
+{{#each imports}}
+
+- `{{import_path}}` - {{reason}}
+  {{/each}}
+
+**Used By:**
+{{#each dependents}}
+
+- `{{dependent_path}}`
+  {{/each}}
+
+**Key Implementation Details:**
+
+```{{language}}
+{{key_code_snippet}}
+```
+
+{{implementation_notes}}
+
+**Patterns Used:**
+{{#each patterns}}
+
+- {{pattern_name}}: {{pattern_description}}
+  {{/each}}
+
+**State Management:** {{state_approach}}
+
+**Side Effects:**
+{{#each side_effects}}
+
+- {{effect_type}}: {{effect_description}}
+  {{/each}}
+
+**Error Handling:** {{error_handling_approach}}
+
+**Testing:**
+
+- Test File: {{test_file_path}}
+- Coverage: {{coverage_percentage}}%
+- Test Approach: {{test_approach}}
+
+**Comments/TODOs:**
+{{#each todos}}
+
+- Line {{line_number}}: {{todo_text}}
+  {{/each}}
+
+---
+
+{{/each}}
+
+## Contributor Checklist
+
+- **Risks & Gotchas:** {{risks_notes}}
+- **Pre-change Verification Steps:** {{verification_steps}}
+- **Suggested Tests Before PR:** {{suggested_tests}}
+
+## Architecture & Design Patterns
+
+### Code Organization
+
+{{organization_approach}}
+
+### Design Patterns
+
+{{#each design_patterns}}
+
+- **{{pattern_name}}**: {{usage_description}}
+  {{/each}}
+
+### State Management Strategy
+
+{{state_management_details}}
+
+### Error Handling Philosophy
+
+{{error_handling_philosophy}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+## Data Flow
+
+{{data_flow_diagram}}
+
+### Data Entry Points
+
+{{#each entry_points}}
+
+- **{{entry_name}}**: {{entry_description}}
+  {{/each}}
+
+### Data Transformations
+
+{{#each transformations}}
+
+- **{{transformation_name}}**: {{transformation_description}}
+  {{/each}}
+
+### Data Exit Points
+
+{{#each exit_points}}
+
+- **{{exit_name}}**: {{exit_description}}
+  {{/each}}
+
+## Integration Points
+
+### APIs Consumed
+
+{{#each apis_consumed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Authentication: {{auth_requirement}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### APIs Exposed
+
+{{#each apis_exposed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Request: {{request_schema}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### Shared State
+
+{{#each shared_state}}
+
+- **{{state_name}}**: {{state_description}}
+  - Type: {{state_type}}
+  - Accessed By: {{accessors}}
+    {{/each}}
+
+### Events
+
+{{#each events}}
+
+- **{{event_name}}**: {{event_description}}
+  - Type: {{publish_or_subscribe}}
+  - Payload: {{payload_schema}}
+    {{/each}}
+
+### Database Access
+
+{{#each database_operations}}
+
+- **{{table_name}}**: {{operation_type}}
+  - Queries: {{query_patterns}}
+  - Indexes Used: {{indexes}}
+    {{/each}}
+
+## Dependency Graph
+
+{{dependency_graph_visualization}}
+
+### Entry Points (Not Imported by Others in Scope)
+
+{{#each entry_point_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Leaf Nodes (Don't Import Others in Scope)
+
+{{#each leaf_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Circular Dependencies
+
+{{#if has_circular_dependencies}}
+⚠️ Circular dependencies detected:
+{{#each circular_deps}}
+
+- {{cycle_description}}
+  {{/each}}
+  {{else}}
+  ✓ No circular dependencies detected
+  {{/if}}
+
+## Testing Analysis
+
+### Test Coverage Summary
+
+- **Statements:** {{statements_coverage}}%
+- **Branches:** {{branches_coverage}}%
+- **Functions:** {{functions_coverage}}%
+- **Lines:** {{lines_coverage}}%
+
+### Test Files
+
+{{#each test_files}}
+
+- **{{test_file_path}}**
+  - Tests: {{test_count}}
+  - Approach: {{test_approach}}
+  - Mocking Strategy: {{mocking_strategy}}
+    {{/each}}
+
+### Test Utilities Available
+
+{{#each test_utilities}}
+
+- `{{utility_name}}`: {{utility_description}}
+  {{/each}}
+
+### Testing Gaps
+
+{{#each testing_gaps}}
+
+- {{gap_description}}
+  {{/each}}
+
+## Related Code & Reuse Opportunities
+
+### Similar Features Elsewhere
+
+{{#each similar_features}}
+
+- **{{feature_name}}** (`{{feature_path}}`)
+  - Similarity: {{similarity_description}}
+  - Can Reference For: {{reference_use_case}}
+    {{/each}}
+
+### Reusable Utilities Available
+
+{{#each reusable_utilities}}
+
+- **{{utility_name}}** (`{{utility_path}}`)
+  - Purpose: {{utility_purpose}}
+  - How to Use: {{usage_example}}
+    {{/each}}
+
+### Patterns to Follow
+
+{{#each patterns_to_follow}}
+
+- **{{pattern_name}}**: Reference `{{reference_file}}` for implementation
+  {{/each}}
+
+## Implementation Notes
+
+### Code Quality Observations
+
+{{#each quality_observations}}
+
+- {{observation}}
+  {{/each}}
+
+### TODOs and Future Work
+
+{{#each all_todos}}
+
+- **{{file_path}}:{{line_number}}**: {{todo_text}}
+  {{/each}}
+
+### Known Issues
+
+{{#each known_issues}}
+
+- {{issue_description}}
+  {{/each}}
+
+### Optimization Opportunities
+
+{{#each optimizations}}
+
+- {{optimization_suggestion}}
+  {{/each}}
+
+### Technical Debt
+
+{{#each tech_debt_items}}
+
+- {{debt_description}}
+  {{/each}}
+
+## Modification Guidance
+
+### To Add New Functionality
+
+{{modification_guidance_add}}
+
+### To Modify Existing Functionality
+
+{{modification_guidance_modify}}
+
+### To Remove/Deprecate
+
+{{modification_guidance_remove}}
+
+### Testing Checklist for Changes
+
+{{#each testing_checklist_items}}
+
+- [ ] {{checklist_item}}
+      {{/each}}
+
+---
+
+_Generated by `document-project` workflow (deep-dive mode)_
+_Base Documentation: docs/index.md_
+_Scan Date: {{date}}_
+_Analysis Mode: Exhaustive_

.agents/skills/bmad-document-project/templates/index-template.md

@@ -0,0 +1,169 @@
+# {{project_name}} Documentation Index
+
+**Type:** {{repository_type}}{{#if is_multi_part}} with {{parts_count}} parts{{/if}}
+**Primary Language:** {{primary_language}}
+**Architecture:** {{architecture_type}}
+**Last Updated:** {{date}}
+
+## Project Overview
+
+{{project_description}}
+
+{{#if is_multi_part}}
+
+## Project Structure
+
+This project consists of {{parts_count}} parts:
+
+{{#each project_parts}}
+
+### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+  {{/each}}
+
+## Cross-Part Integration
+
+{{integration_summary}}
+
+{{/if}}
+
+## Quick Reference
+
+{{#if is_single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+- **Database:** {{database}}
+- **Deployment:** {{deployment_platform}}
+  {{else}}
+  {{#each project_parts}}
+
+### {{part_name}} Quick Ref
+
+- **Stack:** {{tech_stack_summary}}
+- **Entry:** {{entry_point}}
+- **Pattern:** {{architecture_pattern}}
+  {{/each}}
+  {{/if}}
+
+## Generated Documentation
+
+### Core Documentation
+
+- [Project Overview](./project-overview.md) - Executive summary and high-level architecture
+- [Source Tree Analysis](./source-tree-analysis.md) - Annotated directory structure
+
+{{#if is_single_part}}
+
+- [Architecture](./architecture.md) - Detailed technical architecture
+- [Component Inventory](./component-inventory.md) - Catalog of major components{{#if has_ui_components}} and UI elements{{/if}}
+- [Development Guide](./development-guide.md) - Local setup and development workflow
+  {{#if has_api_docs}}- [API Contracts](./api-contracts.md) - API endpoints and schemas{{/if}}
+  {{#if has_data_models}}- [Data Models](./data-models.md) - Database schema and models{{/if}}
+  {{else}}
+
+### Part-Specific Documentation
+
+{{#each project_parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- [Architecture](./architecture-{{part_id}}.md) - Technical architecture for {{part_name}}
+  {{#if has_components}}- [Components](./component-inventory-{{part_id}}.md) - Component catalog{{/if}}
+- [Development Guide](./development-guide-{{part_id}}.md) - Setup and dev workflow
+  {{#if has_api}}- [API Contracts](./api-contracts-{{part_id}}.md) - API documentation{{/if}}
+  {{#if has_data}}- [Data Models](./data-models-{{part_id}}.md) - Data architecture{{/if}}
+  {{/each}}
+
+### Integration
+
+- [Integration Architecture](./integration-architecture.md) - How parts communicate
+- [Project Parts Metadata](./project-parts.json) - Machine-readable structure
+  {{/if}}
+
+### Optional Documentation
+
+{{#if has_deployment_guide}}- [Deployment Guide](./deployment-guide.md) - Deployment process and infrastructure{{/if}}
+{{#if has_contribution_guide}}- [Contribution Guide](./contribution-guide.md) - Contributing guidelines and standards{{/if}}
+
+## Existing Documentation
+
+{{#if has_existing_docs}}
+{{#each existing_docs}}
+
+- [{{title}}]({{path}}) - {{description}}
+  {{/each}}
+  {{else}}
+  No existing documentation files were found in the project.
+  {{/if}}
+
+## Getting Started
+
+{{#if is_single_part}}
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Setup
+
+```bash
+{{setup_commands}}
+```
+
+### Run Locally
+
+```bash
+{{run_commands}}
+```
+
+### Run Tests
+
+```bash
+{{test_commands}}
+```
+
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Setup
+
+**Prerequisites:** {{prerequisites}}
+
+**Install & Run:**
+
+```bash
+cd {{root_path}}
+{{setup_command}}
+{{run_command}}
+```
+
+{{/each}}
+{{/if}}
+
+## For AI-Assisted Development
+
+This documentation was generated specifically to enable AI agents to understand and extend this codebase.
+
+### When Planning New Features:
+
+**UI-only features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{ui_part_id}}.md`, `component-inventory-{{ui_part_id}}.md`{{else}}→ Reference: `architecture.md`, `component-inventory.md`{{/if}}
+
+**API/Backend features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{api_part_id}}.md`, `api-contracts-{{api_part_id}}.md`, `data-models-{{api_part_id}}.md`{{else}}→ Reference: `architecture.md`{{#if has_api_docs}}, `api-contracts.md`{{/if}}{{#if has_data_models}}, `data-models.md`{{/if}}{{/if}}
+
+**Full-stack features:**
+→ Reference: All architecture docs{{#if is_multi_part}} + `integration-architecture.md`{{/if}}
+
+**Deployment changes:**
+{{#if has_deployment_guide}}→ Reference: `deployment-guide.md`{{else}}→ Review CI/CD configs in project{{/if}}
+
+---
+
+_Documentation generated by BMAD Method `document-project` workflow_

.agents/skills/bmad-document-project/templates/project-overview-template.md

@@ -0,0 +1,103 @@
+# {{project_name}} - Project Overview
+
+**Date:** {{date}}
+**Type:** {{project_type}}
+**Architecture:** {{architecture_type}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## Project Classification
+
+- **Repository Type:** {{repository_type}}
+- **Project Type(s):** {{project_types_list}}
+- **Primary Language(s):** {{primary_languages}}
+- **Architecture Pattern:** {{architecture_pattern}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project consists of {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Purpose:** {{purpose}}
+- **Tech Stack:** {{tech_stack}}
+  {{/each}}
+
+### How Parts Integrate
+
+{{integration_description}}
+{{/if}}
+
+## Technology Stack Summary
+
+{{#if is_single_part}}
+{{technology_table}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Stack
+
+{{technology_table}}
+{{/each}}
+{{/if}}
+
+## Key Features
+
+{{key_features}}
+
+## Architecture Highlights
+
+{{architecture_highlights}}
+
+## Development Overview
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Getting Started
+
+{{getting_started_summary}}
+
+### Key Commands
+
+{{#if is_single_part}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+- **Build:** `{{build_command}}`
+- **Test:** `{{test_command}}`
+  {{else}}
+  {{#each project_parts}}
+
+#### {{part_name}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+  {{/each}}
+  {{/if}}
+
+## Repository Structure
+
+{{repository_structure_summary}}
+
+## Documentation Map
+
+For detailed information, see:
+
+- [index.md](./index.md) - Master documentation index
+- [architecture.md](./architecture{{#if is_multi_part}}-{part_id}{{/if}}.md) - Detailed architecture
+- [source-tree-analysis.md](./source-tree-analysis.md) - Directory structure
+- [development-guide.md](./development-guide{{#if is_multi_part}}-{part_id}{{/if}}.md) - Development workflow
+
+---
+
+_Generated using BMAD Method `document-project` workflow_

.agents/skills/bmad-document-project/templates/project-scan-report-schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Project Scan Report Schema",
+  "description": "State tracking file for document-project workflow resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow",
+      "example": "1.2.0"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed (if finished)"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level (deep_dive mode always uses exhaustive)"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "project_knowledge": {
+      "type": "string",
+      "description": "Absolute path to project knowledge folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier (e.g., 'step_1', 'step_2')"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only (detailed findings purged after writing)",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "description": "For deep/exhaustive scans: subfolders processed",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed (for deep_dive mode)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

.agents/skills/bmad-document-project/templates/source-tree-template.md

@@ -0,0 +1,135 @@
+# {{project_name}} - Source Tree Analysis
+
+**Date:** {{date}}
+
+## Overview
+
+{{source_tree_overview}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project is organized into {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+- **{{part_name}}** (`{{root_path}}`): {{purpose}}
+  {{/each}}
+  {{/if}}
+
+## Complete Directory Structure
+
+```
+{{complete_source_tree}}
+```
+
+## Critical Directories
+
+{{#each critical_folders}}
+
+### `{{folder_path}}`
+
+{{description}}
+
+**Purpose:** {{purpose}}
+**Contains:** {{contents_summary}}
+{{#if entry_points}}**Entry Points:** {{entry_points}}{{/if}}
+{{#if integration_note}}**Integration:** {{integration_note}}{{/if}}
+
+{{/each}}
+
+{{#if is_multi_part}}
+
+## Part-Specific Trees
+
+{{#each project_parts}}
+
+### {{part_name}} Structure
+
+```
+{{source_tree}}
+```
+
+**Key Directories:**
+{{#each critical_directories}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+{{/each}}
+
+## Integration Points
+
+{{#each integration_points}}
+
+### {{from_part}} → {{to_part}}
+
+- **Location:** `{{integration_path}}`
+- **Type:** {{integration_type}}
+- **Details:** {{details}}
+  {{/each}}
+
+{{/if}}
+
+## Entry Points
+
+{{#if is_single_part}}
+
+- **Main Entry:** `{{main_entry_point}}`
+  {{#if additional_entry_points}}
+- **Additional:**
+  {{#each additional_entry_points}}
+  - `{{path}}`: {{description}}
+    {{/each}}
+    {{/if}}
+    {{else}}
+    {{#each project_parts}}
+
+### {{part_name}}
+
+- **Entry Point:** `{{entry_point}}`
+- **Bootstrap:** {{bootstrap_description}}
+  {{/each}}
+  {{/if}}
+
+## File Organization Patterns
+
+{{file_organization_patterns}}
+
+## Key File Types
+
+{{#each file_type_patterns}}
+
+### {{file_type}}
+
+- **Pattern:** `{{pattern}}`
+- **Purpose:** {{purpose}}
+- **Examples:** {{examples}}
+  {{/each}}
+
+## Asset Locations
+
+{{#if has_assets}}
+{{#each asset_locations}}
+
+- **{{asset_type}}**: `{{location}}` ({{file_count}} files, {{total_size}})
+  {{/each}}
+  {{else}}
+  No significant assets detected.
+  {{/if}}
+
+## Configuration Files
+
+{{#each config_files}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+## Notes for Development
+
+{{development_notes}}
+
+---
+
+_Generated using BMAD Method `document-project` workflow_

.agents/skills/bmad-document-project/workflows/deep-dive-instructions.md

@@ -0,0 +1,436 @@
+# Deep-Dive Documentation Instructions
+
+## 🧠 Memtrace Context (Self-Contained)
+
+Memtrace structural graph queries are available as the PRIMARY discovery mechanism for this workflow.
+If activation failed to load persistent_facts, this context is sufficient:
+
+**Available MCP tools (used directly in this workflow):**
+- `list_indexed_repositories` — check index freshness and repo availability before EVERY query
+- `find_symbol` (kind=Function|Method|Class|Interface, limit=200) — discover exported symbols with kind, file_path, complexity_score
+- `get_symbol_context` — callers, callees, type references, community, process per symbol
+- `analyze_relationships` (query_type=find_callers|find_callees|imports|exporters) — typed AST dependency edges
+- `find_dependency_path` (source, target, max_depth=15, edge_type="calls") — execution path between symbols
+- `find_central_symbols` (limit=20) — symbols with highest PageRank (load-bearing code)
+- `find_bridge_symbols` (limit=15) — symbols with highest betweenness centrality (architectural chokepoints)
+- `get_api_topology` (include_external=true, min_confidence=0.7) — cross-service HTTP call map
+- `get_directory_tree` (mode=compact, max_depth=4) — directory structure for target scoping
+
+> **Complete Memtrace MCP tool catalog:**
+> **Navigation:** find_code, find_symbol, get_source_window, get_directory_tree
+> **Architecture:** get_codebase_briefing, list_communities, list_processes, get_process_flow
+> **Dependencies:** get_symbol_context, analyze_relationships, get_impact, find_dependency_path, get_api_topology
+> **Quality:** find_dead_code, find_most_complex_functions, find_bridge_symbols, find_central_symbols
+> **Temporal:** get_evolution, get_changes_since, get_timeline, get_episode_replay
+> **Index:** index_directory, list_indexed_repositories, watch_directory, delete_repository
+
+**Rules:**
+- All graph queries MUST use sequential `for...of` with `await` — NEVER `Promise.all`
+- Check `list_indexed_repositories` before trusting graph output
+- Prefer summarized output to stay under 2000 tokens; cap symbol discovery at 200 per batch
+- Enrich top 50 symbols by complexity_score with `get_symbol_context`
+- Flag central/bridge symbols with `[CENTRAL]` or `[BRIDGE]` annotations in the deep-dive output
+
+**Graceful degradation:**
+- Memtrace unavailable → set `memtrace_available = false`, skip all graph queries, use existing exhaustive file-reading
+- Partial query success → apply available data, note partial status in diagnostics
+- NEVER block the documentation workflow on Memtrace availability
+- Graph data provides the STRUCTURAL skeleton; file-reading provides IMPLEMENTATION detail (comments, TODOs, side effects)
+
+<workflow>
+
+<critical>This workflow performs exhaustive deep-dive documentation of specific areas</critical>
+<critical>Handles: deep_dive mode only</critical>
+<critical>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`</critical>
+<critical>YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`</critical>
+
+<step n="13" goal="Deep-dive documentation of specific area" if="workflow_mode == deep_dive">
+<critical>Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.</critical>
+<action>Load existing project structure from index.md and project-parts.json (if exists)</action>
+<action>Load source tree analysis to understand available areas</action>
+
+<step n="13a" goal="Identify area for deep-dive">
+  <action>Analyze existing documentation to suggest deep-dive options</action>
+
+<ask>What area would you like to deep-dive into?
+
+**Suggested Areas Based on Project Structure:**
+
+{{#if has_api_routes}}
+
+## API Routes ({{api_route_count}} endpoints found)
+
+{{#each api_route_groups}}
+{{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_feature_modules}}
+
+## Feature Modules ({{feature_count}} features)
+
+{{#each feature_modules}}
+{{module_index}}. {{module_name}} - {{file_count}} files in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_ui_components}}
+
+### UI Component Areas
+
+{{#each component_groups}}
+{{group_index}}. {{group_name}} - {{component_count}} components in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_services}}
+
+### Services/Business Logic
+
+{{#each service_groups}}
+{{service_index}}. {{service_name}} - `{{path}}`
+{{/each}}
+{{/if}}
+
+**Or specify custom:**
+
+- Folder path (e.g., "client/src/features/dashboard")
+- File path (e.g., "server/src/api/users.ts")
+- Feature name (e.g., "authentication system")
+
+Enter your choice (number or custom path):
+</ask>
+
+<action>Parse user input to determine: - target_type: "folder" | "file" | "feature" | "api_group" | "component_group" - target_path: Absolute path to scan - target_name: Human-readable name for documentation - target_scope: List of all files to analyze
+</action>
+
+<action>Store as {{deep_dive_target}}</action>
+
+<action>Display confirmation:
+Target: {{target_name}}
+Type: {{target_type}}
+Path: {{target_path}}
+Estimated files to analyze: {{estimated_file_count}}
+
+This will read EVERY file in this area. Proceed? [y/n]
+</action>
+
+<action if="user confirms 'n'">Return to Step 13a (select different area)</action>
+</step>
+
+<step n="13b" goal="Comprehensive exhaustive scan of target area">
+  <action>Set scan_mode = "exhaustive"</action>
+  <action>Initialize file_inventory = []</action>
+
+  <action>Check Memtrace availability for structural symbol discovery:
+  - Use `list_indexed_repositories` to confirm the project repo is indexed
+  - If indexed: set `memtrace_available = true`
+  - If NOT indexed: skip this section and fall back to file-reading below
+</action>
+
+<check if="memtrace_available == true">
+  <action>DISPLAY: "Using Memtrace graph for structural symbol discovery..."
+
+  Graph-Based Symbol Discovery (PRIMARY — before file reading):
+
+  **A) Discover Exported Symbols in Target Scope:**
+  - Call `find_symbol` (repo_id={{repo_id}}, kind="Function", limit=200) scoped to `{{target_path}}`
+  - Call `find_symbol` (repo_id={{repo_id}}, kind="Method", limit=200) scoped to `{{target_path}}`
+  - Call `find_symbol` (repo_id={{repo_id}}, kind="Class", limit=100) scoped to `{{target_path}}`
+  - Call `find_symbol` (repo_id={{repo_id}}, kind="Interface", limit=100) scoped to `{{target_path}}`
+  - Each result includes: name, kind, file_path, start_line, complexity_score, risk_level, exported status
+  - Process ALL queries STRICTLY SEQUENTIALLY using `for...of` with `await` — NEVER `Promise.all`
+  - De-duplicate symbols (same name + same file_path = same symbol)
+  - Store as `{{graph_symbols}}` array
+
+  **B) Enrich with Symbol Context:**
+  For each key symbol (limit to top 50 by complexity_score to stay within token budget):
+  - Call `get_symbol_context` (repo_id={{repo_id}}, symbol={{symbol.name}}) to get:
+    - Direct callers (upstream — who calls this)
+    - Direct callees (downstream — what this calls)
+    - Type references (where this type/interface is used)
+    - Community membership (which logical module this belongs to)
+    - Process membership (which execution flows this participates in)
+  - Process STRICTLY SEQUENTIALLY — ONE symbol at a time
+  - Store enriched data in `{{symbol_contexts}}` map keyed by symbol name
+
+  **C) Merge Graph Data into File Inventory:**
+  For each file in the target scope:
+  - If graph symbols exist in this file: use graph-provided export data as primary source
+  - If `get_symbol_context` data exists: use graph-provided caller/callee data for the file's symbols
+  - If NO graph data for this file: use traditional file-reading as fallback
+  - The `file_inventory` entry for this file gets enriched with:
+    - `graph_exports`: symbols discovered via graph (name, kind, complexity, risk)
+    - `graph_callers`: upstream callers from get_symbol_context
+    - `graph_callees`: downstream dependencies from get_symbol_context
+    - `graph_community`: which logical community this file's symbols belong to
+
+  </action>
+</check>
+
+<check if="memtrace_available == false">
+  <action>DISPLAY: "Memtrace not available — using traditional file-reading for symbol discovery."
+    Continue with existing exhaustive file-reading approach below.
+  </action>
+</check>
+
+<!-- THEN CONTINUE WITH EXISTING FILE READING LOGIC AS SUPPLEMENTARY/FALLBACK -->
+
+  <critical>You must read every line of every file in scope and capture a plain-language explanation (what the file does, side effects, why it matters) that future developer agents can act on. No shortcuts.</critical>
+
+  <check if="target_type == folder">
+    <action>Get complete recursive file list from {{target_path}}</action>
+    <action>Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map</action>
+    <action>For EVERY remaining file in folder:
+      - Read complete file contents (all lines)
+      - Extract all exports (functions, classes, types, interfaces, constants)
+      - Extract all imports (dependencies)
+      - Identify purpose from comments and code structure
+      - Write 1-2 sentences (minimum) in natural language describing behaviour, side effects, assumptions, and anything a developer must know before modifying the file
+      - Extract function signatures with parameter types and return types
+      - Note any TODOs, FIXMEs, or comments
+      - Identify patterns (hooks, components, services, controllers, etc.)
+      - Capture per-file contributor guidance: `contributor_note`, `risks`, `verification_steps`, `suggested_tests`
+      - Store in file_inventory
+    </action>
+  </check>
+
+  <check if="target_type == file">
+    <action>Read complete file at {{target_path}}</action>
+    <action>Extract all information as above</action>
+    <action>Read all files it imports (follow import chain 1 level deep)</action>
+    <action>Find all files that import this file (dependents via grep)</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == api_group">
+    <action>Identify all route/controller files in API group</action>
+    <action>Read all route handlers completely</action>
+    <action>Read associated middleware, controllers, services</action>
+    <action>Read data models and schemas used</action>
+    <action>Extract complete request/response schemas</action>
+    <action>Document authentication and authorization requirements</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == feature">
+    <action>Search codebase for all files related to feature name</action>
+    <action>Include: UI components, API endpoints, models, services, tests</action>
+    <action>Read each file completely</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == component_group">
+    <action>Get all component files in group</action>
+    <action>Read each component completely</action>
+    <action>Extract: Props interfaces, hooks used, child components, state management</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+<action>For each file in file\*inventory, document: - **File Path:** Full path - **Purpose:** What this file does (1-2 sentences) - **Lines of Code:** Total LOC - **Exports:** Complete list with signatures
+
+- Functions: `functionName(param: Type): ReturnType` - Description
+  - Classes: `ClassName` - Description with key methods
+  - Types/Interfaces: `TypeName` - Description
+  - Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
+    </action>
+
+<template-output>comprehensive_file_inventory</template-output>
+</step>
+
+<step n="13c" goal="Analyze relationships and data flow">
+<action>Check Memtrace availability (from Step 13b): if `memtrace_available == true`, use graph-based relationship analysis</action>
+
+<check if="memtrace_available == true">
+  <action>Graph-Based Relationship Analysis (PRIMARY):
+
+  **A) Dependency Graph from AST Edges:**
+  Instead of building the graph from manual import scanning, use Memtrace's typed AST edges:
+
+  - For each key symbol in `{{symbol_contexts}}` (from Step 13b):
+    - Callers are already available from `get_symbol_context.direct_callers`
+    - Callees are already available from `get_symbol_context.direct_callees`
+    - Type references are already available from `get_symbol_context.type_usages`
+
+  - For files where graph data was unavailable (fallback to file-reading in Step 13b):
+    - Use `analyze_relationships` (repo_id={{repo_id}}, target={{file_path}}, query_type="imports") to get module-level imports
+    - Use `analyze_relationships` (repo_id={{repo_id}}, target={{file_path}}, query_type="exporters") to find which other files import this file
+
+  Process ALL queries SEQUENTIALLY — NEVER `Promise.all`
+
+  **B) Dependency Paths Between Key Nodes:**
+  - Identify entry points (highest in-degree from `find_central_symbols`) and leaf nodes (lowest out-degree)
+  - For each entry→leaf pair, use `find_dependency_path` (repo_id={{repo_id}}, source={{entry}}, target={{leaf}}, max_depth=15, edge_type="calls")
+  - This reveals the actual execution paths the code follows — far more accurate than manual tracing
+
+  **C) Architectural Significance:**
+  - Call `find_central_symbols` (repo_id={{repo_id}}, limit=20) to get symbols with highest PageRank in the scanned scope
+  - Call `find_bridge_symbols` (repo_id={{repo_id}}, limit=15) to get symbols with highest betweenness centrality
+  - These are the "load-bearing" and "chokepoint" symbols that deserve special documentation attention
+  - For each central/bridge symbol found in the scanned scope:
+    - Document its role in the dependency graph section
+    - Flag it with `[CENTRAL]` or `[BRIDGE]` annotation
+    - Note: changes to central symbols have the HIGHEST blast radius; changes to bridge symbols can unexpectedly cascade
+
+  **D) Cross-Service Integration:**
+  - Call `get_api_topology` (repo_id={{repo_id}}, include_external=true, min_confidence=0.7)
+  - Filter to edges touching files in the scanned scope
+  - For each edge: it shows which external services are called OR which services call into this scope
+  - This replaces manual grep-based external API discovery
+
+  </action>
+
+  <action>Build Dependency Graph from Combined Data:
+    - Graph-provided edges (callers, callees, imports, exporters) form the structural skeleton
+    - Graph-provided centrality metrics annotate the skeleton with architectural significance
+    - File-reading from Step 13b supplements with implementation-level details (e.g., dynamic dispatch, event patterns)
+    - Merge into `{{dependency_graph}}` with nodes and annotated edges
+  </action>
+</check>
+
+<check if="memtrace_available == false">
+  <action>DISPLAY: "Memtrace not available — building dependency graph from manual import scanning."
+    Build dependency graph with files as nodes and import relationships as edges
+    Identify circular dependencies, entry points, leaf nodes
+  </action>
+</check>
+
+<action>Continue with data flow tracing and integration point identification using the combined graph+file data...</action>
+
+<template-output>dependency_graph</template-output>
+<template-output>data_flow_analysis</template-output>
+<template-output>integration_points</template-output>
+</step>
+
+<step n="13d" goal="Find related code and similar patterns">
+  <action>Search codebase OUTSIDE scanned area for:
+    - Similar file/folder naming patterns
+    - Similar function signatures
+    - Similar component structures
+    - Similar API patterns
+    - Reusable utilities that could be used
+  </action>
+
+<action>Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply
+</action>
+
+<action>Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere
+</action>
+
+<template-output>related_code_references</template-output>
+<template-output>reuse_opportunities</template-output>
+</step>
+
+<step n="13e" goal="Generate comprehensive deep-dive documentation">
+  <action>Create documentation filename: deep-dive-{{sanitized_target_name}}.md</action>
+  <action>Aggregate contributor insights across files:
+    - Combine unique risk/gotcha notes into {{risks_notes}}
+    - Combine verification steps developers should run before changes into {{verification_steps}}
+    - Combine recommended test commands into {{suggested_tests}}
+  </action>
+
+<action>Load complete deep-dive template from: ../templates/deep-dive-template.md</action>
+<action>Fill template with all collected data from steps 13b-13d</action>
+<action>Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md</action>
+<action>Validate deep-dive document completeness</action>
+
+<template-output>deep_dive_documentation</template-output>
+
+<action>Update state file: - Add to deep_dive_targets array: {"target_name": "{{target_name}}", "target_path": "{{target_path}}", "files_analyzed": {{file_count}}, "output_file": "deep-dive-{{sanitized_target_name}}.md", "timestamp": "{{now}}"} - Add output to outputs_generated - Update last_updated timestamp
+</action>
+</step>
+
+<step n="13f" goal="Update master index with deep-dive link">
+  <action>Read existing index.md</action>
+
+<action>Check if "Deep-Dive Documentation" section exists</action>
+
+  <check if="section does not exist">
+    <action>Add new section after "Generated Documentation":
+
+## Deep-Dive Documentation
+
+Detailed exhaustive analysis of specific areas:
+
+    </action>
+
+  </check>
+
+<action>Add link to new deep-dive doc:
+
+- [{{target_name}} Deep-Dive](./deep-dive-{{sanitized_target_name}}.md) - Comprehensive analysis of {{target_description}} ({{file_count}} files, {{total_loc}} LOC) - Generated {{date}}
+  </action>
+
+  <action>Update index metadata:
+  Last Updated: {{date}}
+  Deep-Dives: {{deep_dive_count}}
+  </action>
+
+  <action>Save updated index.md</action>
+
+  <template-output>updated_index</template-output>
+  </step>
+
+<step n="13g" goal="Offer to continue or complete">
+  <action>Display summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Deep-Dive Documentation Complete! ✓
+
+**Generated:** {project_knowledge}/deep-dive-{{target_name}}.md
+**Files Analyzed:** {{file_count}}
+**Lines of Code Scanned:** {{total_loc}}
+**Time Taken:** ~{{duration}}
+
+**Documentation Includes:**
+
+- Complete file inventory with all exports
+- Dependency graph and data flow
+- Integration points and API contracts
+- Testing analysis and coverage
+- Related code and reuse opportunities
+- Implementation guidance
+
+**Index Updated:** {project_knowledge}/index.md now includes link to this deep-dive
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<ask>Would you like to:
+
+1. **Deep-dive another area** - Analyze another feature/module/folder
+2. **Finish** - Complete workflow
+
+Your choice [1/2]:
+</ask>
+
+  <action if="user selects 1">
+    <action>Clear current deep_dive_target</action>
+    <action>Go to Step 13a (select new area)</action>
+  </action>
+
+  <action if="user selects 2">
+    <action>Display final message:
+
+All deep-dive documentation complete!
+
+**Master Index:** {project_knowledge}/index.md
+**Deep-Dives Generated:** {{deep_dive_count}}
+
+These comprehensive docs are now ready for:
+
+- Architecture review
+- Implementation planning
+- Code understanding
+- Brownfield PRD creation
+
+Thank you for using the document-project workflow!
+</action>
+<action>Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
+<action>Exit workflow</action>
+</action>
+</step>
+</step>
+
+</workflow>

.agents/skills/bmad-document-project/workflows/deep-dive-workflow.md

@@ -0,0 +1,34 @@
+# Deep-Dive Documentation Sub-Workflow
+
+**Goal:** Exhaustive deep-dive documentation of specific project areas.
+
+**Your Role:** Deep-dive documentation specialist.
+- Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_knowledge`
+- `user_name`
+- `communication_language`, `document_output_language`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### Runtime Inputs
+
+- `workflow_mode` = `deep_dive`
+- `scan_level` = `exhaustive`
+- `autonomous` = `false` (requires user input to select target area)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./deep-dive-instructions.md`

.agents/skills/bmad-document-project/workflows/full-scan-workflow.md

@@ -0,0 +1,34 @@
+# Full Project Scan Sub-Workflow
+
+**Goal:** Complete project documentation (initial scan or full rescan).
+
+**Your Role:** Full project scan documentation specialist.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_knowledge`
+- `user_name`
+- `communication_language`, `document_output_language`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### Runtime Inputs
+
+- `workflow_mode` = `""` (set by parent: `initial_scan` or `full_rescan`)
+- `scan_level` = `""` (set by parent: `quick`, `deep`, or `exhaustive`)
+- `resume_mode` = `false`
+- `autonomous` = `false` (requires user input at key decision points)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./full-scan-instructions.md`

.agents/skills/bmad-quick-dev/step-03-implement.md

@@ -35,6 +35,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` before every graph query
 - `--summarize` on blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code analysis, continue with heuristic approach
+- Stale index → skip graph queries, proceed with existing logic
+- Quality gate failure → write missing tests, do not skip
+- NEVER halt the dev workflow on Memtrace availability
+
 ---
 
 ## RULES

.agents/skills/bmad-quick-dev/step-oneshot.md

@@ -36,6 +36,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` before every graph query
 - `--summarize` on blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code analysis, continue with heuristic approach
+- Stale index → skip graph queries, proceed with existing logic
+- Quality gate failure → write missing tests, do not skip
+- NEVER halt the dev workflow on Memtrace availability
+
 ---
 
 ## RULES

.agents/skills/gds-code-review/steps/step-01-gather-context.md

@@ -40,6 +40,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` flag is mandatory
 - `--summarize` flag required for blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code audit, continue with heuristic review
+- Stale index (`[FRESHNESS]` in STDERR) → skip graph queries, proceed with existing review logic
+- Partial failure → note diagnostic, apply available data, do not halt the review
+- NEVER block the code review workflow on Memtrace availability
+
 ---
 
 ## RULES

.agents/skills/gds-code-review/steps/step-02-review.md

@@ -35,6 +35,12 @@ If activation failed to load persistent_facts, this context is sufficient:
 - `--check-freshness` flag is mandatory
 - `--summarize` flag required for blast radius to stay under 2000 tokens
 
+**Graceful degradation:**
+- Memtrace unavailable or times out → skip blast radius/dead code audit, continue with heuristic review
+- Stale index (`[FRESHNESS]` in STDERR) → skip graph queries, proceed with existing review logic
+- Partial failure → note diagnostic, apply available data, do not halt the review
+- NEVER block the code review workflow on Memtrace availability
+
 ---
 
 ## RULES