diff --git a/.agents/skills/bmad-agent-tech-writer/SKILL.md b/.agents/skills/bmad-agent-tech-writer/SKILL.md
new file mode 100644
index 000000000..ff6430d93
--- /dev/null
+++ b/.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.
diff --git a/.agents/skills/bmad-agent-tech-writer/customize.toml b/.agents/skills/bmad-agent-tech-writer/customize.toml
new file mode 100644
index 000000000..4cda474b5
--- /dev/null
+++ b/.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"
diff --git a/.agents/skills/bmad-agent-tech-writer/explain-concept.md b/.agents/skills/bmad-agent-tech-writer/explain-concept.md
new file mode 100644
index 000000000..9daea41da
--- /dev/null
+++ b/.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.
diff --git a/.agents/skills/bmad-agent-tech-writer/mermaid-gen.md b/.agents/skills/bmad-agent-tech-writer/mermaid-gen.md
new file mode 100644
index 000000000..8d1ff5fe1
--- /dev/null
+++ b/.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.
diff --git a/.agents/skills/bmad-agent-tech-writer/validate-doc.md b/.agents/skills/bmad-agent-tech-writer/validate-doc.md
new file mode 100644
index 000000000..2e93c241f
--- /dev/null
+++ b/.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.
diff --git a/.agents/skills/bmad-agent-tech-writer/write-document.md b/.agents/skills/bmad-agent-tech-writer/write-document.md
new file mode 100644
index 000000000..a524d2937
--- /dev/null
+++ b/.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.
diff --git a/.agents/skills/bmad-code-review/steps/step-01-gather-context.md b/.agents/skills/bmad-code-review/steps/step-01-gather-context.md
index d5ab4a46d..0169a1099 100644
--- a/.agents/skills/bmad-code-review/steps/step-01-gather-context.md
+++ b/.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
diff --git a/.agents/skills/bmad-code-review/steps/step-02-review.md b/.agents/skills/bmad-code-review/steps/step-02-review.md
index 13c844e0a..691dbf142 100644
--- a/.agents/skills/bmad-code-review/steps/step-02-review.md
+++ b/.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
diff --git a/.agents/skills/bmad-document-project/SKILL.md b/.agents/skills/bmad-document-project/SKILL.md
new file mode 100644
index 000000000..112732031
--- /dev/null
+++ b/.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`
diff --git a/.agents/skills/bmad-document-project/checklist.md b/.agents/skills/bmad-document-project/checklist.md
new file mode 100644
index 000000000..7b67d1e56
--- /dev/null
+++ b/.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
diff --git a/.agents/skills/bmad-document-project/customize.toml b/.agents/skills/bmad-document-project/customize.toml
new file mode 100644
index 000000000..dc6670c00
--- /dev/null
+++ b/.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 = ""
diff --git a/.agents/skills/bmad-document-project/documentation-requirements.csv b/.agents/skills/bmad-document-project/documentation-requirements.csv
new file mode 100644
index 000000000..9f773ab00
--- /dev/null
+++ b/.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
diff --git a/.agents/skills/bmad-document-project/instructions.md b/.agents/skills/bmad-document-project/instructions.md
new file mode 100644
index 000000000..4a57b8843
--- /dev/null
+++ b/.agents/skills/bmad-document-project/instructions.md
@@ -0,0 +1,128 @@
+# Document Project Workflow Router
+
+Communicate all responses in {communication_language}
+
+
+
+This router determines workflow mode and delegates to specialized sub-workflows
+
+
+Check for existing state file at: {project_knowledge}/project-scan-report.json
+
+
+ Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification
+ Extract cached project_type_id(s) from state file if present
+ Calculate age of state file (current time - last_updated)
+
+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]:
+
+
+
+ Set resume_mode = true
+ Set workflow_mode = {{mode}}
+ Load findings summaries from state file
+ Load cached project_type_id(s) from state file
+
+ CONDITIONAL CSV LOADING FOR RESUME:
+ For each cached project_type_id, load ONLY the corresponding row from: ./documentation-requirements.csv
+ Skip loading project-types.csv and architecture_registry.csv (not needed on resume)
+ Store loaded doc requirements for use in remaining steps
+
+ Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"
+
+
+ Read fully and follow: ./workflows/deep-dive-workflow.md with resume context
+
+
+
+ Read fully and follow: ./workflows/full-scan-workflow.md with resume context
+
+
+
+
+
+ Create archive directory: {project_knowledge}/.archive/
+ Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json
+ Set resume_mode = false
+ Continue to Step 0.5
+
+
+
+ Display: "Exiting workflow without changes."
+ Exit workflow
+
+
+
+ Display: "Found old state file (>24 hours). Starting fresh scan."
+ Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json
+ Set resume_mode = false
+ Continue to Step 0.5
+
+
+
+
+
+Check if {project_knowledge}/index.md exists
+
+
+ Read existing index.md to extract metadata (date, project structure, parts count)
+ Store as {{existing_doc_date}}, {{existing_structure}}
+
+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]:
+
+
+
+ Set workflow_mode = "full_rescan"
+ Display: "Starting full project rescan..."
+ Read fully and follow: ./workflows/full-scan-workflow.md
+ After sub-workflow completes, continue to Step 4
+
+
+
+ Set workflow_mode = "deep_dive"
+ Set scan_level = "exhaustive"
+ Display: "Starting deep-dive documentation mode..."
+ Read fully and follow: ./workflows/deep-dive-workflow.md
+ After sub-workflow completes, continue to Step 4
+
+
+
+ Display message: "Keeping existing documentation. Exiting workflow."
+ Exit workflow
+
+
+
+
+ Set workflow_mode = "initial_scan"
+ Display: "No existing documentation found. Starting initial project scan..."
+ Read fully and follow: ./workflows/full-scan-workflow.md
+ After sub-workflow completes, continue to Step 4
+
+
+
+
+
diff --git a/.agents/skills/bmad-document-project/templates/deep-dive-template.md b/.agents/skills/bmad-document-project/templates/deep-dive-template.md
new file mode 100644
index 000000000..c1285cdc0
--- /dev/null
+++ b/.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_
diff --git a/.agents/skills/bmad-document-project/templates/index-template.md b/.agents/skills/bmad-document-project/templates/index-template.md
new file mode 100644
index 000000000..0340a35af
--- /dev/null
+++ b/.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_
diff --git a/.agents/skills/bmad-document-project/templates/project-overview-template.md b/.agents/skills/bmad-document-project/templates/project-overview-template.md
new file mode 100644
index 000000000..3bbb0d24e
--- /dev/null
+++ b/.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_
diff --git a/.agents/skills/bmad-document-project/templates/project-scan-report-schema.json b/.agents/skills/bmad-document-project/templates/project-scan-report-schema.json
new file mode 100644
index 000000000..69e059833
--- /dev/null
+++ b/.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" }
+ }
+ }
+ }
+ }
+}
diff --git a/.agents/skills/bmad-document-project/templates/source-tree-template.md b/.agents/skills/bmad-document-project/templates/source-tree-template.md
new file mode 100644
index 000000000..203062175
--- /dev/null
+++ b/.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_
diff --git a/.agents/skills/bmad-document-project/workflows/deep-dive-instructions.md b/.agents/skills/bmad-document-project/workflows/deep-dive-instructions.md
new file mode 100644
index 000000000..3ec51b66e
--- /dev/null
+++ b/.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)
+
+
+
+This workflow performs exhaustive deep-dive documentation of specific areas
+Handles: deep_dive mode only
+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}`
+
+
+Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.
+Load existing project structure from index.md and project-parts.json (if exists)
+Load source tree analysis to understand available areas
+
+
+ Analyze existing documentation to suggest deep-dive options
+
+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):
+
+
+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
+
+
+Store as {{deep_dive_target}}
+
+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]
+
+
+Return to Step 13a (select different area)
+
+
+
+ Set scan_mode = "exhaustive"
+ Initialize file_inventory = []
+
+ 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
+
+
+
+ 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
+
+
+
+
+
+ DISPLAY: "Memtrace not available — using traditional file-reading for symbol discovery."
+ Continue with existing exhaustive file-reading approach below.
+
+
+
+
+
+ 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.
+
+
+ Get complete recursive file list from {{target_path}}
+ Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map
+ 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
+
+
+
+
+ Read complete file at {{target_path}}
+ Extract all information as above
+ Read all files it imports (follow import chain 1 level deep)
+ Find all files that import this file (dependents via grep)
+ Store all in file_inventory
+
+
+
+ Identify all route/controller files in API group
+ Read all route handlers completely
+ Read associated middleware, controllers, services
+ Read data models and schemas used
+ Extract complete request/response schemas
+ Document authentication and authorization requirements
+ Store all in file_inventory
+
+
+
+ Search codebase for all files related to feature name
+ Include: UI components, API endpoints, models, services, tests
+ Read each file completely
+ Store all in file_inventory
+
+
+
+ Get all component files in group
+ Read each component completely
+ Extract: Props interfaces, hooks used, child components, state management
+ Store all in file_inventory
+
+
+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
+
+
+comprehensive_file_inventory
+
+
+
+Check Memtrace availability (from Step 13b): if `memtrace_available == true`, use graph-based relationship analysis
+
+
+ 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
+
+
+
+ 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
+
+
+
+
+ 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
+
+
+
+Continue with data flow tracing and integration point identification using the combined graph+file data...
+
+dependency_graph
+data_flow_analysis
+integration_points
+
+
+
+ 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
+
+
+Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply
+
+
+Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere
+
+
+related_code_references
+reuse_opportunities
+
+
+
+ Create documentation filename: deep-dive-{{sanitized_target_name}}.md
+ 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}}
+
+
+Load complete deep-dive template from: ../templates/deep-dive-template.md
+Fill template with all collected data from steps 13b-13d
+Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md
+Validate deep-dive document completeness
+
+deep_dive_documentation
+
+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
+
+
+
+
+ Read existing index.md
+
+Check if "Deep-Dive Documentation" section exists
+
+
+ Add new section after "Generated Documentation":
+
+## Deep-Dive Documentation
+
+Detailed exhaustive analysis of specific areas:
+
+
+
+
+
+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}}
+
+
+ Update index metadata:
+ Last Updated: {{date}}
+ Deep-Dives: {{deep_dive_count}}
+
+
+ Save updated index.md
+
+ updated_index
+
+
+
+ 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
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+Would you like to:
+
+1. **Deep-dive another area** - Analyze another feature/module/folder
+2. **Finish** - Complete workflow
+
+Your choice [1/2]:
+
+
+
+ Clear current deep_dive_target
+ Go to Step 13a (select new area)
+
+
+
+ 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!
+
+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.
+Exit workflow
+
+
+
+
+
diff --git a/.agents/skills/bmad-document-project/workflows/deep-dive-workflow.md b/.agents/skills/bmad-document-project/workflows/deep-dive-workflow.md
new file mode 100644
index 000000000..c55f036a7
--- /dev/null
+++ b/.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`
diff --git a/.agents/skills/bmad-document-project/workflows/full-scan-instructions.md b/.agents/skills/bmad-document-project/workflows/full-scan-instructions.md
new file mode 100644
index 000000000..dfe556368
--- /dev/null
+++ b/.agents/skills/bmad-document-project/workflows/full-scan-instructions.md
@@ -0,0 +1,1245 @@
+# Full Project Scan 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
+- `get_directory_tree` (mode=compact/verbose, max_depth=4-6) — project directory structure from File-kind graph nodes
+- `list_communities` (min_size=3) — Louvain community clusters as logical module boundaries
+- `find_symbol` (kind=Function|Method|Class|Interface, limit=200) — discover exported symbols with kind, file_path, complexity_score
+- `find_api_endpoints` (limit=200) — all HTTP endpoints with method, path template, handler function
+- `get_api_topology` (include_external=false, min_confidence=0.7) — cross-service HTTP call map
+- `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_source_window` — read bounded source for request/response type extraction from handlers
+
+> **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
+- Graph data is PRIMARY source when available; existing heuristic file-reading is preserved as fallback
+
+**Graceful degradation:**
+- Memtrace unavailable → set `memtrace_available = false`, skip all graph queries, use existing heuristic file-reading
+- Partial query success → apply available data, note partial status in diagnostics
+- NEVER block the documentation workflow on Memtrace availability
+- Graph data provides STRUCTURAL accuracy; file-reading provides IMPLEMENTATION detail (comments, TODOs, side effects)
+
+
+
+This workflow performs complete project documentation (Steps 1-12)
+Handles: initial_scan and full_rescan modes
+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}`
+
+
+DATA LOADING STRATEGY - Understanding the Documentation Requirements System:
+
+Display explanation to user:
+
+**How Project Type Detection Works:**
+
+This workflow uses a single comprehensive CSV file to intelligently document your project:
+
+**documentation-requirements.csv** (../documentation-requirements.csv)
+
+- Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
+- 24-column schema combining project type detection AND documentation requirements
+- **Detection columns**: project_type_id, key_file_patterns (used to identify project type from codebase)
+- **Requirement columns**: requires_api_scan, requires_data_models, requires_ui_components, etc.
+- **Pattern columns**: critical_directories, test_file_patterns, config_patterns, etc.
+- Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
+- Example: For project_type_id="web", key_file_patterns includes "package.json;tsconfig.json;\*.config.js" and requires_api_scan=true
+
+**When Documentation Requirements are Loaded:**
+
+- **Fresh Start (initial_scan)**: Load all 12 rows → detect type using key_file_patterns → use that row's requirements
+- **Resume**: Load ONLY the doc requirements row(s) for cached project_type_id(s)
+- **Full Rescan**: Same as fresh start (may re-detect project type)
+- **Deep Dive**: Load ONLY doc requirements for the part being deep-dived
+
+
+Now loading documentation requirements data for fresh start...
+
+Load documentation-requirements.csv from: ../documentation-requirements.csv
+Store all 12 rows indexed by project_type_id for project detection and requirements lookup
+Display: "Loaded documentation requirements for 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)"
+
+Display: "✓ Documentation requirements loaded successfully. Ready to begin project analysis."
+
+
+
+Check if {project_knowledge}/index.md exists
+
+
+ Read existing index.md to extract metadata (date, project structure, parts count)
+ Store as {{existing_doc_date}}, {{existing_structure}}
+
+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]:
+
+
+
+ Set workflow_mode = "full_rescan"
+ Continue to scan level selection below
+
+
+
+ Set workflow_mode = "deep_dive"
+ Set scan_level = "exhaustive"
+ Initialize state file with mode=deep_dive, scan_level=exhaustive
+ Jump to Step 13
+
+
+
+ Display message: "Keeping existing documentation. Exiting workflow."
+ Exit workflow
+
+
+
+
+ Set workflow_mode = "initial_scan"
+ Continue to scan level selection below
+
+
+Select Scan Level
+
+
+ Choose your scan depth level:
+
+**1. Quick Scan** (2-5 minutes) [DEFAULT]
+
+- Pattern-based analysis without reading source files
+- Scans: Config files, package manifests, directory structure
+- Best for: Quick project overview, initial understanding
+- File reading: Minimal (configs, README, package.json, etc.)
+
+**2. Deep Scan** (10-30 minutes)
+
+- Reads files in critical directories based on project type
+- Scans: All critical paths from documentation requirements
+- Best for: Comprehensive documentation for brownfield PRD
+- File reading: Selective (key files in critical directories)
+
+**3. Exhaustive Scan** (30-120 minutes)
+
+- Reads ALL source files in project
+- Scans: Every source file (excludes node_modules, dist, build)
+- Best for: Complete analysis, migration planning, detailed audit
+- File reading: Complete (all source files)
+
+Your choice [1/2/3] (default: 1):
+
+
+
+ Set scan_level = "quick"
+ Display: "Using Quick Scan (pattern-based, no source file reading)"
+
+
+
+ Set scan_level = "deep"
+ Display: "Using Deep Scan (reading critical files per project type)"
+
+
+
+ Set scan_level = "exhaustive"
+ Display: "Using Exhaustive Scan (reading all source files)"
+
+
+Initialize state file: {project_knowledge}/project-scan-report.json
+Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable.
+Write initial state:
+{
+"workflow_version": "1.2.0",
+"timestamps": {"started": "{{current_timestamp}}", "last_updated": "{{current_timestamp}}"},
+"mode": "{{workflow_mode}}",
+"scan_level": "{{scan_level}}",
+"project_root": "{{project_root_path}}",
+"project_knowledge": "{{project_knowledge}}",
+"completed_steps": [],
+"current_step": "step_1",
+"findings": {},
+"outputs_generated": ["project-scan-report.json"],
+"resume_instructions": "Starting from step 1"
+}
+
+Continue with standard workflow from Step 1
+
+
+
+
+Ask user: "What is the root directory of the project to document?" (default: current working directory)
+Store as {{project_root_path}}
+
+Scan {{project_root_path}} for key indicators:
+
+- Directory structure (presence of client/, server/, api/, src/, app/, etc.)
+- Key files (package.json, go.mod, requirements.txt, etc.)
+- Technology markers matching detection_keywords from project-types.csv
+
+
+Detect if project is:
+
+- **Monolith**: Single cohesive codebase
+- **Monorepo**: Multiple parts in one repository
+- **Multi-part**: Separate client/server or similar architecture
+
+
+
+ List detected parts with their paths
+ I detected multiple parts in this project:
+ {{detected_parts_list}}
+
+Is this correct? Should I document each part separately? [y/n]
+
+
+Set repository_type = "monorepo" or "multi-part"
+For each detected part: - Identify root path - Run project type detection using key_file_patterns from documentation-requirements.csv - Store as part in project_parts array
+
+
+Ask user to specify correct parts and their paths
+
+
+
+ Set repository_type = "monolith"
+ Create single part in project_parts array with root_path = {{project_root_path}}
+ Run project type detection using key_file_patterns from documentation-requirements.csv
+
+
+For each part, match detected technologies and file patterns against key_file_patterns column in documentation-requirements.csv
+Assign project_type_id to each part
+Load corresponding documentation_requirements row for each part
+
+I've classified this project:
+{{project_classification_summary}}
+
+Does this look correct? [y/n/edit]
+
+
+project_structure
+project_parts_metadata
+
+IMMEDIATELY update state file with step completion:
+
+- Add to completed_steps: {"step": "step_1", "status": "completed", "timestamp": "{{now}}", "summary": "Classified as {{repository_type}} with {{parts_count}} parts"}
+- Update current_step = "step_2"
+- Update findings.project_classification with high-level summary only
+- **CACHE project_type_id(s)**: Add project_types array: [{"part_id": "{{part_id}}", "project_type_id": "{{project_type_id}}", "display_name": "{{display_name}}"}]
+- This cached data prevents reloading all CSV files on resume - we can load just the needed documentation_requirements row(s)
+- Update last_updated timestamp
+- Write state file
+
+
+PURGE detailed scan results from memory, keep only summary: "{{repository_type}}, {{parts_count}} parts, {{primary_tech}}"
+
+
+
+For each part, scan for existing documentation using patterns:
+- README.md, README.rst, README.txt
+- CONTRIBUTING.md, CONTRIBUTING.rst
+- ARCHITECTURE.md, ARCHITECTURE.txt, docs/architecture/
+- DEPLOYMENT.md, DEPLOY.md, docs/deployment/
+- API.md, docs/api/
+- Any files in docs/, documentation/, .github/ folders
+
+
+Create inventory of existing_docs with:
+
+- File path
+- File type (readme, architecture, api, etc.)
+- Which part it belongs to (if multi-part)
+
+
+I found these existing documentation files:
+{{existing_docs_list}}
+
+Are there any other important documents or key areas I should focus on while analyzing this project? [Provide paths or guidance, or type 'none']
+
+
+Store user guidance as {{user_context}}
+
+existing_documentation_inventory
+user_provided_context
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_2", "status": "completed", "timestamp": "{{now}}", "summary": "Found {{existing_docs_count}} existing docs"}
+- Update current_step = "step_3"
+- Update last_updated timestamp
+
+
+PURGE detailed doc contents from memory, keep only: "{{existing_docs_count}} docs found"
+
+
+
+Check Memtrace availability for structural technology discovery:
+ - Use `list_indexed_repositories` to confirm the project repo is indexed
+ - If indexed: set `memtrace_available = true` and proceed with graph-based discovery
+ - If NOT indexed: set `memtrace_available = false` and skip to traditional file-pattern scanning
+
+
+
+ DISPLAY: "Memtrace graph detected — enriching technology analysis with structural data..."
+
+ Graph-Based Technology Stack Discovery:
+
+ **A) Directory Structure via Graph:**
+ - Use `get_directory_tree` (repo_id={{repo_id}}, mode=compact, max_depth=4) to get the complete project tree
+ - The tree is built from Memtrace's File-kind nodes — it automatically respects .gitignore
+ - Cross-reference detected directories against `critical_directories` from documentation_requirements
+ - This provides structural validation of the project layout BEFORE any file reading
+
+ **B) Logical Module Boundaries:**
+ - Use `list_communities` (repo_id={{repo_id}}, min_size=3) to discover Louvain community clusters
+ - Communities represent tightly-coupled symbol groups — these are the natural subsystem boundaries
+ - Map communities to directory paths using the community symbols' file_path fields
+ - Store as `{{memtrace_communities}}` for later use in Steps 5 and 8
+
+ **C) Technology Surface Indicators:**
+ - Use `find_symbol` (repo_id={{repo_id}}, kind="Function", limit=30) to sample exported functions
+ - Use `find_symbol` (repo_id={{repo_id}}, kind="Class", limit=20) to sample exported classes
+ - Analyze symbol patterns for technology indicators:
+ - Express/Connect middleware signatures → Node.js API framework
+ - React component patterns (capitalized, returns JSX) → Frontend framework
+ - Axum handler fn signatures → Rust web framework
+ - FastAPI/Flask route decorators → Python web framework
+ - Process ALL queries SEQUENTIALLY — NEVER parallelize
+
+ **D) Endpoint Discovery (preview):**
+ - Use `find_api_endpoints` (repo_id={{repo_id}}, limit=10) to sample the API surface
+ - The endpoint paths and HTTP methods indicate the API framework in use
+ - Store endpoint sample for cross-validation in Step 4
+
+
+
+ Merge Graph Data with Traditional Analysis:
+ - Graph data provides structural validation of file-pattern-based detection
+ - Community boundaries confirm or correct the multi-part structure detected in Step 1
+ - Symbol patterns provide secondary technology indicators alongside package manifest parsing
+ - Store `{{memtrace_tech_insights}}` as structured enrichment data
+
+
+
+
+ DISPLAY: "Memtrace not available — using traditional file-pattern technology detection."
+ Continue with existing key_file_patterns scanning below.
+
+
+
+For each part in project_parts:
+ - Load key_file_patterns from documentation_requirements
+ - Scan part root for these patterns
+ - Parse technology manifest files (package.json, go.mod, requirements.txt, etc.)
+ - Extract: framework, language, version, database, dependencies
+ - Build technology_table with columns: Category, Technology, Version, Justification
+
+
+Determine architecture pattern based on detected tech stack:
+
+- Use project_type_id as primary indicator (e.g., "web" → layered/component-based, "backend" → service/API-centric)
+- Consider framework patterns (e.g., React → component hierarchy, Express → middleware pipeline)
+- Note architectural style in technology table
+- Store as {{architecture_pattern}} for each part
+
+
+technology_stack
+architecture_patterns
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_3", "status": "completed", "timestamp": "{{now}}", "summary": "Tech stack: {{primary_framework}}"}
+- Update current_step = "step_4"
+- Update findings.technology_stack with summary per part
+- Update last_updated timestamp
+
+
+PURGE detailed tech analysis from memory, keep only: "{{framework}} on {{language}}"
+
+
+
+
+BATCHING STRATEGY FOR DEEP/EXHAUSTIVE SCANS
+
+
+ This step requires file reading. Apply batching strategy:
+
+Identify subfolders to process based on: - scan_level == "deep": Use critical_directories from documentation_requirements - scan_level == "exhaustive": Get ALL subfolders recursively (excluding node_modules, .git, dist, build, coverage)
+
+
+For each subfolder to scan: 1. Read all files in subfolder (consider file size - use judgment for files >5000 LOC) 2. Extract required information based on conditional flags below 3. IMMEDIATELY write findings to appropriate output file 4. Validate written document (section-level validation) 5. Update state file with batch completion 6. PURGE detailed findings from context, keep only 1-2 sentence summary 7. Move to next subfolder
+
+
+Track batches in state file:
+findings.batches_completed: [
+{"path": "{{subfolder_path}}", "files_scanned": {{count}}, "summary": "{{brief_summary}}"}
+]
+
+
+
+
+ Use pattern matching only - do NOT read source files
+ Use glob/grep to identify file locations and patterns
+ Extract information from filenames, directory structure, and config files only
+
+
+For each part, check documentation_requirements boolean flags and execute corresponding scans:
+
+
+ Check Memtrace availability (from Step 3): if `memtrace_available == true`, use graph-based API discovery as the PRIMARY method
+
+
+ Graph-Based API Discovery (PRIMARY):
+
+ **A) Discover All HTTP Endpoints:**
+ - Call `find_api_endpoints` (repo_id={{repo_id}}, limit=200) to get every HTTP endpoint
+ - Each result includes: handler function name, HTTP method (GET/POST/PUT/DELETE/etc.), path template, file_path, line number
+ - Group endpoints by: file_path (which file defines them), community (from Step 3 data), path prefix (e.g., /api/users, /api/products)
+ - Process STRICTLY SEQUENTIALLY — do NOT parallelize endpoint queries
+
+ **B) Cross-Service Topology:**
+ - Call `get_api_topology` (repo_id={{repo_id}}, include_external=false, min_confidence=0.7) for cross-service HTTP calls
+ - This reveals which other services call this repo's endpoints AND which services this repo calls
+ - Filter to edges where THIS repo is EITHER the source OR target
+ - Store as `{{memtrace_api_topology}}` for Step 7 (integration architecture) and Step 8 (architecture docs)
+
+ **C) Build API Contracts from Graph Data:**
+ For each endpoint group:
+ - HTTP method + path template → API contract entry
+ - handler function name → link to implementation location
+ - community membership → which subsystem owns this endpoint
+ - cross-service callers (from topology) → external consumers of this endpoint
+
+ **D) Fallback to file scanning for request/response schemas:**
+ - The graph provides endpoint location and routing — but request/response TYPE information requires source reading
+ - Use `get_source_window` on each handler function to extract type annotations/schemas
+ - Process SEQUENTIALLY — one handler at a time
+
+
+
+ IMMEDIATELY write graph-sourced API contracts to: {project_knowledge}/api-contracts-{part_id}.md
+ Validate document completeness — ensure each endpoint has: method, path, handler, community, cross-service callers
+
+
+
+ Memtrace not available — falling back to heuristic file scanning for API discovery:
+ Scan for API routes and endpoints using integration_scan_patterns
+ Look for: controllers/, routes/, api/, handlers/, endpoints/
+
+
+ Use glob to find route files, extract patterns from filenames and folder structure
+
+
+
+ Read files in batches (one subfolder at a time)
+ Extract: HTTP methods, paths, request/response types from actual code
+
+
+
+Build API contracts catalog
+IMMEDIATELY write to: {project_knowledge}/api-contracts-{part_id}.md
+Validate document has all required sections
+Update state file with output generated
+PURGE detailed API data, keep only: "{{api_count}} endpoints documented"
+api_contracts\*{part_id}
+
+
+
+ Scan for data models using schema_migration_patterns
+ Look for: models/, schemas/, entities/, migrations/, prisma/, ORM configs
+
+
+ Identify schema files via glob, parse migration file names for table discovery
+
+
+
+ Read model files in batches (one subfolder at a time)
+ Extract: table names, fields, relationships, constraints from actual code
+
+
+Build database schema documentation
+IMMEDIATELY write to: {project_knowledge}/data-models-{part_id}.md
+Validate document completeness
+Update state file with output generated
+PURGE detailed schema data, keep only: "{{table_count}} tables documented"
+data_models\*{part_id}
+
+
+
+ Analyze state management patterns
+ Look for: Redux, Context API, MobX, Vuex, Pinia, Provider patterns
+ Identify: stores, reducers, actions, state structure
+ state_management_patterns_{part_id}
+
+
+
+ Inventory UI component library
+ Scan: components/, ui/, widgets/, views/ folders
+ Categorize: Layout, Form, Display, Navigation, etc.
+ Identify: Design system, component patterns, reusable elements
+ ui_component_inventory_{part_id}
+
+
+
+ Look for hardware schematics using hardware_interface_patterns
+ This appears to be an embedded/hardware project. Do you have:
+ - Pinout diagrams
+ - Hardware schematics
+ - PCB layouts
+ - Hardware documentation
+
+If yes, please provide paths or links. [Provide paths or type 'none']
+
+Store hardware docs references
+hardware*documentation*{part_id}
+
+
+
+ Scan and catalog assets using asset_patterns
+ Categorize by: Images, Audio, 3D Models, Sprites, Textures, etc.
+ Calculate: Total size, file counts, formats used
+ asset_inventory_{part_id}
+
+
+Scan for additional patterns based on doc requirements:
+
+- config_patterns → Configuration management
+- auth_security_patterns → Authentication/authorization approach
+- entry_point_patterns → Application entry points and bootstrap
+- shared_code_patterns → Shared libraries and utilities
+- async_event_patterns → Event-driven architecture
+- ci_cd_patterns → CI/CD pipeline details
+- localization_patterns → i18n/l10n support
+
+
+Apply scan_level strategy to each pattern scan (quick=glob only, deep/exhaustive=read files)
+
+comprehensive*analysis*{part_id}
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_4", "status": "completed", "timestamp": "{{now}}", "summary": "Conditional analysis complete, {{files_generated}} files written"}
+- Update current_step = "step_5"
+- Update last_updated timestamp
+- List all outputs_generated
+
+
+PURGE all detailed scan results from context. Keep only summaries:
+
+- "APIs: {{api_count}} endpoints"
+- "Data: {{table_count}} tables"
+- "Components: {{component_count}} components"
+
+
+
+
+Check Memtrace availability: if `memtrace_available == true`, use graph-based tree generation
+
+
+ Graph-Based Source Tree (PRIMARY):
+
+ **A) Generate Tree from Graph:**
+ - Call `get_directory_tree` (repo_id={{repo_id}}, mode=verbose, max_depth=6)
+ - The tree is built from Memtrace's File-kind graph nodes
+ - It automatically respects .gitignore and .memtraceignore
+ - This returns a compact, bounded tree — no manual file-system traversal needed
+
+ **B) Annotate with Community Boundaries:**
+ - Cross-reference tree directories against `{{memtrace_communities}}` from Step 3
+ - For each directory that contains symbols from a community, annotate: `# Community: "community_label" (size: N symbols)`
+ - This shows the logical subsystem boundaries overlaid on the physical directory structure
+
+ **C) Annotate with Critical Directories:**
+ - For each directory matching critical_directories from documentation_requirements:
+ - Mark as: `[CRITICAL]` with the requirement's purpose annotation
+ - Example: `src/controllers/ [CRITICAL] API route handlers — 12 endpoints`
+ - Use `find_api_endpoints` data from Step 4 to provide endpoint counts per directory
+
+ **D) Entry Point Markers:**
+ - Use the entry_point_patterns from documentation_requirements
+ - Cross-reference with `find_symbol` (kind=Function) results from Step 3 to identify entry point symbols
+ - Annotate entry point files with `[ENTRY]` marker
+
+
+ IMMEDIATELY write source-tree-analysis.md to disk with graph-sourced annotations
+ Validate document structure
+
+
+
+ Memtrace not available — falling back to manual directory tree generation:
+ For each part, generate complete directory tree using critical_directories from doc requirements
+ Annotate the tree with purpose, entry points, key files, integration points
+ IMMEDIATELY write source-tree-analysis.md to disk
+
+
+source_tree_analysis
+critical_folders_summary
+
+Update state file:
+- Add to completed_steps: {"step": "step_5", "status": "completed", "timestamp": "{{now}}", "summary": "Source tree documented"}
+- Update current_step = "step_6"
+- Add output: "source-tree-analysis.md"
+
+PURGE detailed tree from context, keep only: "Source tree with {{folder_count}} critical folders"
+
+
+
+Scan for development setup using key_file_patterns and existing docs:
+- Prerequisites (Node version, Python version, etc.)
+- Installation steps (npm install, etc.)
+- Environment setup (.env files, config)
+- Build commands (npm run build, make, etc.)
+- Run commands (npm start, go run, etc.)
+- Test commands using test_file_patterns
+
+
+Look for deployment configuration using ci_cd_patterns:
+
+- Dockerfile, docker-compose.yml
+- Kubernetes configs (k8s/, helm/)
+- CI/CD pipelines (.github/workflows/, .gitlab-ci.yml)
+- Deployment scripts
+- Infrastructure as Code (terraform/, pulumi/)
+
+
+
+ Extract contribution guidelines:
+ - Code style rules
+ - PR process
+ - Commit conventions
+ - Testing requirements
+
+
+
+development_instructions
+deployment_configuration
+contribution_guidelines
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_6", "status": "completed", "timestamp": "{{now}}", "summary": "Dev/deployment guides written"}
+- Update current_step = "step_7"
+- Add generated outputs to list
+
+ PURGE detailed instructions, keep only: "Dev setup and deployment documented"
+
+
+
+Analyze how parts communicate:
+- Scan integration_scan_patterns across parts
+- Identify: REST calls, GraphQL queries, gRPC, message queues, shared databases
+- Document: API contracts between parts, data flow, authentication flow
+
+
+Create integration_points array with:
+
+- from: source part
+- to: target part
+- type: REST API, GraphQL, gRPC, Event Bus, etc.
+- details: Endpoints, protocols, data formats
+
+
+IMMEDIATELY write integration-architecture.md to disk
+Validate document completeness
+
+integration_architecture
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_7", "status": "completed", "timestamp": "{{now}}", "summary": "Integration architecture documented"}
+- Update current_step = "step_8"
+
+ PURGE integration details, keep only: "{{integration_count}} integration points"
+
+
+
+For each part in project_parts:
+ - Use matched architecture template from Step 3 as base structure
+ - Fill in all sections with discovered information:
+ * Executive Summary
+ * Technology Stack (from Step 3)
+ * Architecture Pattern (from registry match)
+ * Data Architecture (from Step 4 data models scan)
+ * API Design (from Step 4 API scan if applicable)
+ * Component Overview (from Step 4 component scan if applicable)
+ * Source Tree (from Step 5)
+ * Development Workflow (from Step 6)
+ * Deployment Architecture (from Step 6)
+ * Testing Strategy (from test patterns)
+
+
+
+ - Generate: architecture.md (no part suffix)
+
+
+
+ - Generate: architecture-{part_id}.md for each part
+
+
+For each architecture file generated:
+
+- IMMEDIATELY write architecture file to disk
+- Validate against architecture template schema
+- Update state file with output
+- PURGE detailed architecture from context, keep only: "Architecture for {{part_id}} written"
+
+
+architecture_document
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_8", "status": "completed", "timestamp": "{{now}}", "summary": "Architecture docs written for {{parts_count}} parts"}
+- Update current_step = "step_9"
+
+
+
+
+Generate project-overview.md with:
+- Project name and purpose (from README or user input)
+- Executive summary
+- Tech stack summary table
+- Architecture type classification
+- Repository structure (monolith/monorepo/multi-part)
+- Links to detailed docs
+
+
+Generate source-tree-analysis.md with:
+
+- Full annotated directory tree from Step 5
+- Critical folders explained
+- Entry points documented
+- Multi-part structure (if applicable)
+
+
+IMMEDIATELY write project-overview.md to disk
+Validate document sections
+
+Generate source-tree-analysis.md (if not already written in Step 5)
+IMMEDIATELY write to disk and validate
+
+Generate component-inventory.md (or per-part versions) with:
+
+- All discovered components from Step 4
+- Categorized by type
+- Reusable vs specific components
+- Design system elements (if found)
+
+ IMMEDIATELY write each component inventory to disk and validate
+
+Generate development-guide.md (or per-part versions) with:
+
+- Prerequisites and dependencies
+- Environment setup instructions
+- Local development commands
+- Build process
+- Testing approach and commands
+- Common development tasks
+
+ IMMEDIATELY write each development guide to disk and validate
+
+
+ Generate deployment-guide.md with:
+ - Infrastructure requirements
+ - Deployment process
+ - Environment configuration
+ - CI/CD pipeline details
+
+ IMMEDIATELY write to disk and validate
+
+
+
+ Generate contribution-guide.md with:
+ - Code style and conventions
+ - PR process
+ - Testing requirements
+ - Documentation standards
+
+ IMMEDIATELY write to disk and validate
+
+
+
+ Generate api-contracts.md (or per-part) with:
+ - All API endpoints
+ - Request/response schemas
+ - Authentication requirements
+ - Example requests
+
+ IMMEDIATELY write to disk and validate
+
+
+
+ Generate data-models.md (or per-part) with:
+ - Database schema
+ - Table relationships
+ - Data models and entities
+ - Migration strategy
+
+ IMMEDIATELY write to disk and validate
+
+
+
+ Generate integration-architecture.md with:
+ - How parts communicate
+ - Integration points diagram/description
+ - Data flow between parts
+ - Shared dependencies
+
+ IMMEDIATELY write to disk and validate
+
+Generate project-parts.json metadata file:
+`json
+ {
+ "repository_type": "monorepo",
+ "parts": [ ... ],
+ "integration_points": [ ... ]
+ }
+ `
+
+IMMEDIATELY write to disk
+
+
+supporting_documentation
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_9", "status": "completed", "timestamp": "{{now}}", "summary": "All supporting docs written"}
+- Update current_step = "step_10"
+- List all newly generated outputs
+
+
+PURGE all document contents from context, keep only list of files generated
+
+
+
+
+INCOMPLETE DOCUMENTATION MARKER CONVENTION:
+When a document SHOULD be generated but wasn't (due to quick scan, missing data, conditional requirements not met):
+
+- Use EXACTLY this marker: _(To be generated)_
+- Place it at the end of the markdown link line
+- Example: - [API Contracts - Server](./api-contracts-server.md) _(To be generated)_
+- This allows Step 11 to detect and offer to complete these items
+- ALWAYS use this exact format for consistency and automated detection
+
+
+Create index.md with intelligent navigation based on project structure
+
+
+ Generate simple index with:
+ - Project name and type
+ - Quick reference (tech stack, architecture type)
+ - Links to all generated docs
+ - Links to discovered existing docs
+ - Getting started section
+
+
+
+
+ Generate comprehensive index with:
+ - Project overview and structure summary
+ - Part-based navigation section
+ - Quick reference by part
+ - Cross-part integration links
+ - Links to all generated and existing docs
+ - Getting started per part
+
+
+
+Include in index.md:
+
+## Project Documentation Index
+
+### Project Overview
+
+- **Type:** {{repository_type}} {{#if multi-part}}with {{parts.length}} parts{{/if}}
+- **Primary Language:** {{primary_language}}
+- **Architecture:** {{architecture_type}}
+
+### Quick Reference
+
+{{#if single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+ {{else}}
+ {{#each parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Tech Stack:** {{tech_stack}}
+- **Root:** {{root_path}}
+ {{/each}}
+ {{/if}}
+
+### Generated Documentation
+
+- [Project Overview](./project-overview.md)
+- [Architecture](./architecture{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless architecture_file_exists}} (To be generated) {{/unless}}
+- [Source Tree Analysis](./source-tree-analysis.md)
+- [Component Inventory](./component-inventory{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless component_inventory_exists}} (To be generated) {{/unless}}
+- [Development Guide](./development-guide{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless dev_guide_exists}} (To be generated) {{/unless}}
+ {{#if deployment_found}}- [Deployment Guide](./deployment-guide.md){{#unless deployment_guide_exists}} (To be generated) {{/unless}}{{/if}}
+ {{#if contribution_found}}- [Contribution Guide](./contribution-guide.md){{/if}}
+ {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{#unless api_contracts_exists}} (To be generated) {{/unless}}{{/if}}
+ {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{#unless data_models_exists}} (To be generated) {{/unless}}{{/if}}
+ {{#if multi-part}}- [Integration Architecture](./integration-architecture.md){{#unless integration_arch_exists}} (To be generated) {{/unless}}{{/if}}
+
+### Existing Documentation
+
+{{#each existing_docs}}
+
+- [{{title}}]({{relative_path}}) - {{description}}
+ {{/each}}
+
+### Getting Started
+
+{{getting_started_instructions}}
+
+
+Before writing index.md, check which expected files actually exist:
+
+- For each document that should have been generated, check if file exists on disk
+- Set existence flags: architecture_file_exists, component_inventory_exists, dev_guide_exists, etc.
+- These flags determine whether to add the _(To be generated)_ marker
+- Track which files are missing in {{missing_docs_list}} for reporting
+
+
+IMMEDIATELY write index.md to disk with appropriate _(To be generated)_ markers for missing files
+Validate index has all required sections and links are valid
+
+index
+
+Update state file:
+
+- Add to completed_steps: {"step": "step_10", "status": "completed", "timestamp": "{{now}}", "summary": "Master index generated"}
+- Update current_step = "step_11"
+- Add output: "index.md"
+
+
+PURGE index content from context
+
+
+
+Show summary of all generated files:
+Generated in {{project_knowledge}}/:
+{{file_list_with_sizes}}
+
+
+Run validation checklist from ../checklist.md
+
+INCOMPLETE DOCUMENTATION DETECTION:
+
+1. PRIMARY SCAN: Look for exact marker: _(To be generated)_
+2. FALLBACK SCAN: Look for fuzzy patterns (in case agent was lazy):
+ - _(TBD)_
+ - _(TODO)_
+ - _(Coming soon)_
+ - _(Not yet generated)_
+ - _(Pending)_
+3. Extract document metadata from each match for user selection
+
+
+Read {project_knowledge}/index.md
+
+Scan for incomplete documentation markers:
+Step 1: Search for exact pattern "_(To be generated)_" (case-sensitive)
+Step 2: For each match found, extract the entire line
+Step 3: Parse line to extract:
+
+- Document title (text within [brackets] or **bold**)
+- File path (from markdown link or inferable from title)
+- Document type (infer from filename: architecture, api-contracts, data-models, component-inventory, development-guide, deployment-guide, integration-architecture)
+- Part ID if applicable (extract from filename like "architecture-server.md" → part_id: "server")
+ Step 4: Add to {{incomplete_docs_strict}} array
+
+
+Fallback fuzzy scan for alternate markers:
+Search for patterns: _(TBD)_, _(TODO)_, _(Coming soon)_, _(Not yet generated)_, _(Pending)_
+For each fuzzy match:
+
+- Extract same metadata as strict scan
+- Add to {{incomplete_docs_fuzzy}} array with fuzzy_match flag
+
+
+Combine results:
+Set {{incomplete_docs_list}} = {{incomplete_docs_strict}} + {{incomplete_docs_fuzzy}}
+For each item store structure:
+{
+"title": "Architecture – Server",
+"file\*path": "./architecture-server.md",
+"doc_type": "architecture",
+"part_id": "server",
+"line_text": "- [Architecture – Server](./architecture-server.md) (To be generated)",
+"fuzzy_match": false
+}
+
+
+Documentation generation complete!
+
+Summary:
+
+- Project Type: {{project_type_summary}}
+- Parts Documented: {{parts_count}}
+- Files Generated: {{files_count}}
+- Total Lines: {{total_lines}}
+
+{{#if incomplete_docs_list.length > 0}}
+⚠️ **Incomplete Documentation Detected:**
+
+I found {{incomplete_docs_list.length}} item(s) marked as incomplete:
+
+{{#each incomplete_docs_list}}
+{{@index + 1}}. **{{title}}** ({{doc_type}}{{#if part_id}} for {{part_id}}{{/if}}){{#if fuzzy_match}} ⚠️ [non-standard marker]{{/if}}
+{{/each}}
+
+{{/if}}
+
+Would you like to:
+
+{{#if incomplete_docs_list.length > 0}}
+
+1. **Generate incomplete documentation** - Complete any of the {{incomplete_docs_list.length}} items above
+2. Review any specific section [type section name]
+3. Add more detail to any area [type area name]
+4. Generate additional custom documentation [describe what]
+5. Finalize and complete [type 'done']
+ {{else}}
+6. Review any specific section [type section name]
+7. Add more detail to any area [type area name]
+8. Generate additional documentation [describe what]
+9. Finalize and complete [type 'done']
+ {{/if}}
+
+Your choice:
+
+
+
+ Which incomplete items would you like to generate?
+
+{{#each incomplete_docs_list}}
+{{@index + 1}}. {{title}} ({{doc_type}}{{#if part_id}} - {{part_id}}{{/if}})
+{{/each}}
+{{incomplete_docs_list.length + 1}}. All of them
+
+Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all':
+
+
+Parse user selection:
+
+- If "all", set {{selected_items}} = all items in {{incomplete_docs_list}}
+- If comma-separated numbers, extract selected items by index
+- Store result in {{selected_items}} array
+
+
+ Display: "Generating {{selected_items.length}} document(s)..."
+
+ For each item in {{selected_items}}:
+
+1. **Identify the part and requirements:**
+ - Extract part_id from item (if exists)
+ - Look up part data in project_parts array from state file
+ - Load documentation_requirements for that part's project_type_id
+
+2. **Route to appropriate generation substep based on doc_type:**
+
+ **If doc_type == "architecture":**
+ - Display: "Generating architecture documentation for {{part_id}}..."
+ - Load architecture_match for this part from state file (Step 3 cache)
+ - Re-run Step 8 architecture generation logic ONLY for this specific part
+ - Use matched template and fill with cached data from state file
+ - Write architecture-{{part_id}}.md to disk
+ - Validate completeness
+
+ **If doc_type == "api-contracts":**
+ - Display: "Generating API contracts for {{part_id}}..."
+ - Load part data and documentation_requirements
+ - Re-run Step 4 API scan substep targeting ONLY this part
+ - Use scan_level from state file (quick/deep/exhaustive)
+ - Generate api-contracts-{{part_id}}.md
+ - Validate document structure
+
+ **If doc_type == "data-models":**
+ - Display: "Generating data models documentation for {{part_id}}..."
+ - Re-run Step 4 data models scan substep targeting ONLY this part
+ - Use schema_migration_patterns from documentation_requirements
+ - Generate data-models-{{part_id}}.md
+ - Validate completeness
+
+ **If doc_type == "component-inventory":**
+ - Display: "Generating component inventory for {{part_id}}..."
+ - Re-run Step 9 component inventory generation for this specific part
+ - Scan components/, ui/, widgets/ folders
+ - Generate component-inventory-{{part_id}}.md
+ - Validate structure
+
+ **If doc_type == "development-guide":**
+ - Display: "Generating development guide for {{part_id}}..."
+ - Re-run Step 9 development guide generation for this specific part
+ - Use key_file_patterns and test_file_patterns from documentation_requirements
+ - Generate development-guide-{{part_id}}.md
+ - Validate completeness
+
+ **If doc_type == "deployment-guide":**
+ - Display: "Generating deployment guide..."
+ - Re-run Step 6 deployment configuration scan
+ - Re-run Step 9 deployment guide generation
+ - Generate deployment-guide.md
+ - Validate structure
+
+ **If doc_type == "integration-architecture":**
+ - Display: "Generating integration architecture..."
+ - Re-run Step 7 integration analysis for all parts
+ - Generate integration-architecture.md
+ - Validate completeness
+
+3. **Post-generation actions:**
+ - Confirm file was written successfully
+ - Update state file with newly generated output
+ - Add to {{newly_generated_docs}} tracking list
+ - Display: "✓ Generated: {{file_path}}"
+
+4. **Handle errors:**
+ - If generation fails, log error and continue with next item
+ - Track failed items in {{failed_generations}} list
+
+
+After all selected items are processed:
+
+**Update index.md to remove markers:**
+
+1. Read current index.md content
+2. For each item in {{newly_generated_docs}}:
+ - Find the line containing the file link and marker
+ - Remove the _(To be generated)_ or fuzzy marker text
+ - Leave the markdown link intact
+3. Write updated index.md back to disk
+4. Update state file to record index.md modification
+
+
+Display generation summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ **Documentation Generation Complete!**
+
+**Successfully Generated:**
+{{#each newly_generated_docs}}
+
+- {{title}} → {{file_path}}
+ {{/each}}
+
+{{#if failed_generations.length > 0}}
+**Failed to Generate:**
+{{#each failed_generations}}
+
+- {{title}} ({{error_message}})
+ {{/each}}
+ {{/if}}
+
+**Updated:** index.md (removed incomplete markers)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+Update state file with all generation activities
+
+Return to Step 11 menu (loop back to check for any remaining incomplete items)
+
+
+Make requested modifications and regenerate affected files
+Proceed to Step 12 completion
+
+
+ Update state file:
+- Add to completed_steps: {"step": "step_11_iteration", "status": "completed", "timestamp": "{{now}}", "summary": "Review iteration complete"}
+- Keep current_step = "step_11" (for loop back)
+- Update last_updated timestamp
+
+ Loop back to beginning of Step 11 (re-scan for remaining incomplete docs)
+
+
+
+ Update state file:
+- Add to completed_steps: {"step": "step_11", "status": "completed", "timestamp": "{{now}}", "summary": "Validation and review complete"}
+- Update current_step = "step_12"
+
+ Proceed to Step 12
+
+
+
+
+Create final summary report
+Compile verification recap variables:
+ - Set {{verification_summary}} to the concrete tests, validations, or scripts you executed (or "none run").
+ - Set {{open_risks}} to any remaining risks or TODO follow-ups (or "none").
+ - Set {{next_checks}} to recommended actions before merging/deploying (or "none").
+
+
+Display completion message:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Project Documentation Complete! ✓
+
+**Location:** {{project_knowledge}}/
+
+**Master Index:** {{project_knowledge}}/index.md
+👆 This is your primary entry point for AI-assisted development
+
+**Generated Documentation:**
+{{generated_files_list}}
+
+**Next Steps:**
+
+1. Review the index.md to familiarize yourself with the documentation structure
+2. When creating a brownfield PRD, point the PRD workflow to: {{project_knowledge}}/index.md
+3. For UI-only features: Reference {{project_knowledge}}/architecture-{{ui_part_id}}.md
+4. For API-only features: Reference {{project_knowledge}}/architecture-{{api_part_id}}.md
+5. For full-stack features: Reference both part architectures + integration-architecture.md
+
+**Verification Recap:**
+
+- Tests/extractions executed: {{verification_summary}}
+- Outstanding risks or follow-ups: {{open_risks}}
+- Recommended next checks before PR: {{next_checks}}
+
+**Brownfield PRD Command:**
+When ready to plan new features, run the PRD workflow and provide this index as input.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+FINALIZE state file:
+
+- Add to completed_steps: {"step": "step_12", "status": "completed", "timestamp": "{{now}}", "summary": "Workflow complete"}
+- Update timestamps.completed = "{{now}}"
+- Update current_step = "completed"
+- Write final state file
+
+
+Display: "State file saved: {{project_knowledge}}/project-scan-report.json"
+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.
+
+
diff --git a/.agents/skills/bmad-document-project/workflows/full-scan-workflow.md b/.agents/skills/bmad-document-project/workflows/full-scan-workflow.md
new file mode 100644
index 000000000..5aaf4a580
--- /dev/null
+++ b/.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`
diff --git a/.agents/skills/bmad-quick-dev/step-03-implement.md b/.agents/skills/bmad-quick-dev/step-03-implement.md
index 9e70b7fb9..5ae7b310d 100644
--- a/.agents/skills/bmad-quick-dev/step-03-implement.md
+++ b/.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
diff --git a/.agents/skills/bmad-quick-dev/step-oneshot.md b/.agents/skills/bmad-quick-dev/step-oneshot.md
index a1885c263..026e76644 100644
--- a/.agents/skills/bmad-quick-dev/step-oneshot.md
+++ b/.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
diff --git a/.agents/skills/gds-code-review/steps/step-01-gather-context.md b/.agents/skills/gds-code-review/steps/step-01-gather-context.md
index 8381e3b83..a74ad440b 100644
--- a/.agents/skills/gds-code-review/steps/step-01-gather-context.md
+++ b/.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
diff --git a/.agents/skills/gds-code-review/steps/step-02-review.md b/.agents/skills/gds-code-review/steps/step-02-review.md
index 350503a6d..4926c811d 100644
--- a/.agents/skills/gds-code-review/steps/step-02-review.md
+++ b/.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