lots of docs updates

.bmad-core/agents/architect.md

@@ -2,27 +2,24 @@
 
 CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 activation-instructions:
-    - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
+  - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
-    - Only read the files/tasks listed here when user selects them for execution to minimize context usage
+  - Only read the files/tasks listed here when user selects them for execution to minimize context usage
-    - The customization field ALWAYS takes precedence over any conflicting instructions
+  - The customization field ALWAYS takes precedence over any conflicting instructions
-    - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
+  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
-
 agent:
   name: Winston
   id: architect
   title: Architect
   icon: 🏗️
-  whenToUse: "Use for system design, architecture documents, technology selection, API design, and infrastructure planning"
+  whenToUse: Use for system design, architecture documents, technology selection, API design, and infrastructure planning
-  customization:
+  customization: null
-
 persona:
   role: Holistic System Architect & Full-Stack Technical Leader
   style: Comprehensive, pragmatic, user-centric, technically deep yet accessible
   identity: Master of holistic application design who bridges frontend, backend, infrastructure, and everything in between
   focus: Complete systems architecture, cross-stack optimization, pragmatic technology selection
-
   core_principles:
     - Holistic System Thinking - View every component as part of a larger system
     - User Experience Drives Architecture - Start with user journeys and work backward
@@ -34,24 +31,22 @@ persona:
     - Data-Centric Design - Let data requirements drive architecture
     - Cost-Conscious Engineering - Balance technical ideals with financial reality
     - Living Architecture - Design for change and adaptation
-
 startup:
   - Greet the user with your name and role, and inform of the *help command.
   - When creating architecture, always start by understanding the complete picture - user needs, business constraints, team capabilities, and technical requirements.
-
 commands:
-  - "*help" - Show: numbered list of the following commands to allow selection
+  - '*help" - Show: numbered list of the following commands to allow selection'
-  - "*chat-mode" - (Default) Architect consultation with advanced-elicitation for complex system design
+  - '*chat-mode" - (Default) Architect consultation with advanced-elicitation for complex system design'
-  - "*create-doc {template}" - Create doc (no template = show available templates)
+  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - "*execute-checklist {checklist}" - Run architectural validation checklist
+  - '*execute-checklist {checklist}" - Run architectural validation checklist'
-  - "*research {topic}" - Generate deep research prompt for architectural decisions
+  - '*research {topic}" - Generate deep research prompt for architectural decisions'
-  - "*exit" - Say goodbye as the Architect, and then abandon inhabiting this persona
+  - '*exit" - Say goodbye as the Architect, and then abandon inhabiting this persona'
-
 dependencies:
   tasks:
     - create-doc
-    - execute-checklist
     - create-deep-research-prompt
+    - document-project
+    - execute-checklist
   templates:
     - architecture-tmpl
     - front-end-architecture-tmpl

.bmad-core/agents/bmad-master.md

@@ -55,6 +55,7 @@ dependencies:
     - correct-course
     - create-deep-research-prompt
     - create-doc
+    - document-project
     - create-expansion-pack
     - create-agent
     - create-next-story

.bmad-core/bmad-core-config.yml

@@ -0,0 +1,60 @@
+agent_file_references:
+  core_docs:
+    - docs/index.md
+    - docs/prd.md
+    - docs/architecture.md
+    - docs/architecture/index.md
+    - 'docs/architecture/coding-standards.md # Required by DEV at startup'
+    - 'docs/architecture/tech-stack.md # Technology stack reference'
+    - 'docs/architecture/unified-project-structure.md # Project structure guide'
+    - 'docs/architecture/testing-strategy.md # Testing requirements'
+  story_files:
+    - 'docs/stories/ # Stories directory (pattern: {epicNum}.{storyNum}.story.md)'
+  epic_locations:
+    primary: docs/
+    secondary: docs/prd/
+  architecture_shards:
+    backend:
+      - 'docs/architecture/backend-architecture.md # Backend service patterns'
+      - 'docs/architecture/rest-api-spec.md # API endpoint specifications'
+      - 'docs/architecture/data-models.md # Data structures and validation'
+      - 'docs/architecture/database-schema.md # Database design'
+      - 'docs/architecture/external-apis.md # Third-party integrations'
+    frontend:
+      - 'docs/architecture/frontend-architecture.md # Frontend patterns'
+      - docs/architecture/components.md
+      - 'docs/architecture/core-workflows.md # User interaction flows'
+      - 'docs/architecture/ui-ux-spec.md # UI/UX specifications'
+    shared:
+      - 'docs/architecture/tech-stack.md # Technology constraints'
+      - 'docs/architecture/unified-project-structure.md # Code organization'
+      - 'docs/architecture/coding-standards.md # Project conventions'
+      - 'docs/architecture/testing-strategy.md # Testing requirements'
+  additional_docs:
+    - 'docs/tech-stack.md # Technology stack (if separate)'
+    - 'docs/data-models.md # Data models (if separate)'
+    - 'docs/api-reference.md # API reference (if separate)'
+    - 'docs/frontend-architecture.md # Frontend arch (if separate)'
+bmad_core_dependencies:
+  tasks:
+    - .bmad-core/tasks/create-next-story.md
+    - .bmad-core/tasks/execute-checklist.md
+    - .bmad-core/tasks/correct-course.md
+    - .bmad-core/tasks/shard-doc.md
+    - .bmad-core/tasks/index-docs.md
+  templates:
+    - .bmad-core/templates/story-tmpl.md
+  checklists:
+    - .bmad-core/checklists/story-draft-checklist.md
+    - .bmad-core/checklists/story-dod-checklist.md
+  utils:
+    - .bmad-core/utils/template-format.md
+file_patterns:
+  story_files: '{epicNum}.{storyNum}.story.md'
+  epic_files: epic-{n}-{description}.md
+story_statuses:
+  - Draft
+  - Approved
+  - In Progress
+  - Review
+  - Done

.bmad-core/tasks/document-project.md

@@ -0,0 +1,389 @@
+# Document an Existing Project
+
+## Purpose
+
+Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
+
+## Task Instructions
+
+### 1. Initial Project Analysis
+
+[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
+
+1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
+2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
+3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
+4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
+5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
+
+Ask the user these elicitation questions to better understand their needs:
+
+- What is the primary purpose of this project?
+- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
+- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
+- Are there any existing documentation standards or formats you prefer?
+- What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
+  ]]
+
+### 2. Core Documentation Generation
+
+[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
+
+**Core Documents (always generate):**
+
+1. **docs/index.md** - Master documentation index
+2. **docs/architecture/index.md** - Architecture documentation index
+3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
+4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
+5. **docs/architecture/unified-project-structure.md** - Project structure and organization
+6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
+
+**Backend Documents (generate for backend/full-stack projects):**
+
+7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
+8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
+9. **docs/architecture/data-models.md** - Data structures and validation rules
+10. **docs/architecture/database-schema.md** - Database design and relationships
+11. **docs/architecture/external-apis.md** - Third-party integrations
+
+**Frontend Documents (generate for frontend/full-stack projects):**
+
+12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
+13. **docs/architecture/components.md** - UI component specifications
+14. **docs/architecture/core-workflows.md** - User interaction flows
+15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
+
+**Additional Documents (generate if applicable):**
+
+16. **docs/prd.md** - Product requirements document (if not exists)
+17. **docs/architecture/deployment-guide.md** - Deployment and operations info
+18. **docs/architecture/security-considerations.md** - Security patterns and requirements
+19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
+
+**Optional Enhancement Documents:**
+
+20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
+21. **docs/architecture/changelog-conventions.md** - Change management practices
+22. **docs/architecture/code-review-checklist.md** - Review standards and practices
+
+Present each document section by section, using the advanced elicitation task after each major section.]]
+
+### 3. Document Structure Template
+
+[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
+
+```markdown
+# {{Document Title}}
+
+## Overview
+
+{{Brief description of what this document covers and why it's important for AI agents}}
+
+## Quick Reference
+
+{{Key points, commands, or patterns that agents need most frequently}}
+
+## Detailed Information
+
+{{Comprehensive information organized into logical sections}}
+
+## Examples
+
+{{Concrete examples showing proper usage or implementation}}
+
+## Common Patterns
+
+{{Recurring patterns agents should recognize and follow}}
+
+## Things to Avoid
+
+{{Anti-patterns, deprecated approaches, or common mistakes}}
+
+## Related Resources
+
+{{Links to other relevant documentation or external resources}}
+```
+
+Each document should be:
+
+- **Concrete and actionable** - Focus on what agents need to do, not just concepts
+- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
+- **Example-rich** - Include specific code examples and real file references
+- **Context-aware** - Reference actual project files, folders, and conventions
+- **Assumption-free** - Don't assume agents know project history or implicit knowledge
+  ]]
+
+### 4. Content Guidelines for Each Document Type
+
+#### Core Architecture Documents
+
+##### docs/architecture/index.md
+
+[[LLM: Create a comprehensive index of all architecture documentation:
+
+- List all architecture documents with brief descriptions
+- Group documents by category (backend, frontend, shared)
+- Include quick links to key sections
+- Provide reading order recommendations for different use cases]]
+
+##### docs/architecture/unified-project-structure.md
+
+[[LLM: Document the complete project structure:
+
+- Root-level directory structure with explanations
+- Where each type of code belongs (backend, frontend, tests, etc.)
+- File naming conventions and patterns
+- Module/package organization
+- Generated vs. source file locations
+- Build output locations]]
+
+##### docs/architecture/coding-standards.md
+
+[[LLM: Capture project-wide coding conventions:
+
+- Language-specific style guidelines
+- Naming conventions (variables, functions, classes, files)
+- Code organization within files
+- Import/export patterns
+- Comment and documentation standards
+- Linting and formatting tool configurations
+- Git commit message conventions]]
+
+##### docs/architecture/tech-stack.md
+
+[[LLM: Document all technologies and versions:
+
+- Primary languages and versions
+- Frameworks and major libraries with versions
+- Development tools and their versions
+- Database systems and versions
+- External services and APIs used
+- Browser/runtime requirements]]
+
+##### docs/architecture/testing-strategy.md
+
+[[LLM: Define testing approaches and requirements:
+
+- Test file locations and naming conventions
+- Unit testing patterns and frameworks
+- Integration testing approaches
+- E2E testing setup (if applicable)
+- Test coverage requirements
+- Mocking strategies
+- Test data management]]
+
+#### Backend Architecture Documents
+
+##### docs/architecture/backend-architecture.md
+
+[[LLM: Document backend service structure:
+
+- Service layer organization
+- Controller/route patterns
+- Middleware architecture
+- Authentication/authorization patterns
+- Request/response flow
+- Background job processing
+- Service communication patterns]]
+
+##### docs/architecture/rest-api-spec.md
+
+[[LLM: Specify all API endpoints:
+
+- Base URL and versioning strategy
+- Authentication methods
+- Common headers and parameters
+- Each endpoint with:
+  - HTTP method and path
+  - Request parameters/body
+  - Response format and status codes
+  - Error responses
+- Rate limiting and quotas]]
+
+##### docs/architecture/data-models.md
+
+[[LLM: Define data structures and validation:
+
+- Core business entities
+- Data validation rules
+- Relationships between entities
+- Computed fields and derivations
+- Data transformation patterns
+- Serialization formats]]
+
+##### docs/architecture/database-schema.md
+
+[[LLM: Document database design:
+
+- Database type and version
+- Table/collection structures
+- Indexes and constraints
+- Relationships and foreign keys
+- Migration patterns
+- Seed data requirements
+- Backup and recovery procedures]]
+
+##### docs/architecture/external-apis.md
+
+[[LLM: Document third-party integrations:
+
+- List of external services used
+- Authentication methods for each
+- API endpoints and usage patterns
+- Rate limits and quotas
+- Error handling strategies
+- Webhook configurations
+- Data synchronization patterns]]
+
+#### Frontend Architecture Documents
+
+##### docs/architecture/frontend-architecture.md
+
+[[LLM: Document frontend application structure:
+
+- Component hierarchy and organization
+- State management patterns
+- Routing architecture
+- Data fetching patterns
+- Authentication flow
+- Error boundary strategies
+- Performance optimization patterns]]
+
+##### docs/architecture/components.md
+
+[[LLM: Specify UI components:
+
+- Component library/design system used
+- Custom component specifications
+- Props and state for each component
+- Component composition patterns
+- Styling approaches
+- Accessibility requirements
+- Component testing patterns]]
+
+##### docs/architecture/core-workflows.md
+
+[[LLM: Document user interaction flows:
+
+- Major user journeys
+- Screen flow diagrams
+- Form handling patterns
+- Navigation patterns
+- Data flow through workflows
+- Error states and recovery
+- Loading and transition states]]
+
+##### docs/architecture/ui-ux-spec.md
+
+[[LLM: Define UI/UX guidelines:
+
+- Design system specifications
+- Color palette and typography
+- Spacing and layout grids
+- Responsive breakpoints
+- Animation and transition guidelines
+- Accessibility standards
+- Browser compatibility requirements]]
+
+### 5. Adaptive Content Strategy
+
+[[LLM: Adapt your documentation approach based on project characteristics:
+
+**For Web Applications:**
+
+- Focus on component patterns, routing, state management
+- Include build processes, asset handling, and deployment
+- Cover API integration patterns and data fetching
+
+**For Backend Services:**
+
+- Emphasize service architecture, data models, and API design
+- Include database interaction patterns and migration strategies
+- Cover authentication, authorization, and security patterns
+
+**For CLI Tools:**
+
+- Focus on command structure, argument parsing, and output formatting
+- Include plugin/extension patterns if applicable
+- Cover configuration file handling and user interaction patterns
+
+**For Libraries/Frameworks:**
+
+- Emphasize public API design and usage patterns
+- Include extension points and customization approaches
+- Cover versioning, compatibility, and migration strategies
+
+**For Mobile Applications:**
+
+- Focus on platform-specific patterns and navigation
+- Include state management and data persistence approaches
+- Cover platform integration and native feature usage
+
+**For Data Science/ML Projects:**
+
+- Emphasize data pipeline patterns and model organization
+- Include experiment tracking and reproducibility approaches
+- Cover data validation and model deployment patterns
+  ]]
+
+### 6. Quality Assurance
+
+[[LLM: Before completing each document:
+
+1. **Accuracy Check**: Verify all file paths, commands, and code examples work
+2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
+3. **Clarity Assessment**: Check that explanations are clear and actionable
+4. **Consistency Verification**: Ensure terminology and patterns align across all documents
+5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
+
+Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
+
+### 7. Final Integration
+
+[[LLM: After all documents are completed:
+
+1. Ensure all documents are created in the proper BMAD-expected locations:
+
+   - Core docs in `docs/` (index.md, prd.md)
+   - Architecture shards in `docs/architecture/` subdirectory
+   - Create the `docs/architecture/` directory if it doesn't exist
+
+2. Create/update the master index documents:
+
+   - Update `docs/index.md` to reference all documentation
+   - Create `docs/architecture/index.md` listing all architecture shards
+
+3. Verify document cross-references:
+
+   - Ensure all documents link to related documentation
+   - Check that file paths match the actual project structure
+   - Validate that examples reference real files in the project
+
+4. Provide maintenance guidance:
+
+   - Document update triggers (when to update each doc)
+   - Create a simple checklist for keeping docs current
+   - Suggest automated validation approaches
+
+5. Summary report including:
+   - List of all documents created with their paths
+   - Any gaps or areas needing human review
+   - Recommendations for project-specific additions
+   - Next steps for maintaining documentation accuracy
+
+Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
+
+## Success Criteria
+
+- Documentation enables AI agents to understand project context without additional explanation
+- All major architectural patterns and coding conventions are captured
+- Examples reference actual project files and demonstrate real usage
+- Documentation is structured consistently and easy to navigate
+- Content is actionable and focuses on what agents need to do, not just understand
+
+## Notes
+
+- This task is designed to work with any project type, language, or framework
+- The documentation should reflect the project as it actually is, not as it should be
+- Focus on patterns that agents can recognize and replicate consistently
+- Include both positive examples (what to do) and negative examples (what to avoid)

README.md

@@ -256,6 +256,11 @@ npm install
 
 ## Documentation & Guides
 
+### Architecture & Technical
+
+- 🏗️ [Core Architecture](docs/core-architecture.md) - Complete technical architecture and system design
+- 📖 [User Guide](docs/user-guide.md) - Comprehensive guide to using BMAD-METHOD effectively
+
 ### Workflow Guides
 
 - 📚 [Universal BMAD Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs
@@ -277,7 +282,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Version History
 
-- **Current**: [v4.0.0](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs
+- **Current**: [v4](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs
 - **Previous Versions**:
   - [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3) - Introduced the unified BMAD Agent and Gemini optimization
   - [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2) - Added web agents and template separation

docs/core-architecture.md

@@ -0,0 +1,213 @@
+# BMAD Method: Core Architecture
+
+This document serves as the definitive source of truth for the BMAD-Method's architecture. It is designed to be understood by both human developers and the AI agents that operate within the framework.
+
+## 1. Overview
+
+The BMAD-Method is an AI-Powered Agile Development Framework designed to transform software development by providing specialized AI agents for every role in a complete Agile team. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex software development tasks in a predictable, high-quality manner.
+
+The system facilitates a full development lifecycle:
+
+1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
+2. **Architecture & Design**: Defining system architecture and UI/UX specifications.
+3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
+
+## 2. System Architecture Diagram
+
+The entire BMAD-Method ecosystem is designed around the `.bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
+
+```mermaid
+graph TD
+    subgraph BMAD Method Project
+        subgraph Core Framework
+            A["bmad-core"]
+            A --> B["agents"]
+            A --> C["agent-teams"]
+            A --> D["workflows"]
+            A --> E["templates"]
+            A --> F["tasks"]
+            A --> G["checklists"]
+            A --> H["data (KB)"]
+        end
+
+        subgraph Tooling
+            I["tools/builders/web-builder.js"]
+        end
+
+        subgraph Outputs
+            J[".bmad-core/web-bundles"]
+        end
+
+        B -- defines dependencies for --> E
+        B -- defines dependencies for --> F
+        B -- defines dependencies for --> G
+        B -- defines dependencies for --> H
+
+        C -- bundles --> B
+        I -- reads from --> A
+        I -- creates --> J
+    end
+
+    subgraph Target Environments
+        K["IDE (Cursor, VS Code, etc.)"]
+        L["Web UI (Gemini, ChatGPT)"]
+    end
+
+    B --> K
+    J --> L
+
+    style A fill:#1a73e8,color:#fff
+    style I fill:#f9ab00,color:#fff
+    style J fill:#34a853,color:#fff
+```text
+
+## 3. Core Components
+
+The `.bmad-core` directory contains all the definitions and resources that give the agents their capabilities.
+
+### 3.1. Agents (`.bmad-core/agents/`)
+
+- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
+- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
+- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation.
+- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
+- **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
+
+### 3.2. Agent Teams (`.bmad-core/agent-teams/`)
+
+- **Purpose**: Team files (e.g., `team-all.yml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
+- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
+
+### 3.3. Workflows (`.bmad-core/workflows/`)
+
+- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
+- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
+
+### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
+
+- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies.
+  - **`templates/`**: Contains markdown templates for common documents like PRDs, architecture specifications, and user stories.
+  - **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story".
+  - **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or Architect.
+  - **`data/`**: Contains the core knowledge base (`bmad-kb.md`), technical preferences (`technical-preferences.md`), and other key data files.
+
+#### 3.4.1. Template Processing System
+
+A key architectural principle of BMAD is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
+
+The BMAD framework employs a sophisticated template processing system orchestrated by three key components:
+
+- **`template-format.md`** (`.bmad-core/utils/`): Defines the foundational markup language used throughout all BMAD templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
+
+- **`create-doc.md`** (`.bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
+
+- **`advanced-elicitation.md`** (`.bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
+
+The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
+
+#### 3.4.2. Technical Preferences System
+
+BMAD includes a personalization layer through the `technical-preferences.md` file in `.bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
+
+**Purpose and Benefits:**
+- **Consistency**: Ensures all agents reference the same technical preferences
+- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
+- **Personalization**: Agents provide recommendations aligned with user preferences
+- **Learning**: Captures lessons learned and preferences that evolve over time
+
+**Content Structure:**
+The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
+
+**Integration Points:**
+- Templates can reference technical preferences during document generation
+- Agents suggest preferred technologies when appropriate for project requirements
+- When preferences don't fit project needs, agents explain alternatives
+- Web bundles can include preferences content for consistent behavior across platforms
+
+**Evolution Over Time:**
+Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time.
+
+## 4. The Build & Delivery Process
+
+The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter.
+
+### 4.1. Web Builder (`tools/builders/web-builder.js`)
+
+- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `.bmad-core/web-bundles/`.
+- **Process**:
+  1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
+  2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
+  3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
+  4. **Outputs Bundle**: The final `.txt` file is saved in the `web-bundles` directory, ready to be uploaded to a web UI.
+
+### 4.2. Environment-Specific Usage
+
+- **For IDEs**: Users interact with the agents directly via their markdown files in `.bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
+- **For Web UIs**: Users upload a pre-built bundle from `.bmad-core/web-bundles/`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
+
+## 5. BMAD Workflows
+
+### 5.1. The Planning Workflow
+
+Before development begins, BMAD follows a structured planning workflow that establishes the foundation for successful project execution:
+
+```mermaid
+graph TD
+    A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"}
+    B -->|Yes| C["Analyst: Market Research & Analysis"]
+    B -->|No| D["Create Project Brief"]
+    C --> D["Analyst: Create Project Brief"]
+    D --> E["PM: Create PRD from Brief"]
+    E --> F["Architect: Create Architecture from PRD"]
+    F --> G["PO: Run Master Checklist"]
+    G --> H{"Documents Aligned?"}
+    H -->|Yes| I["Planning Complete"]
+    H -->|No| J["PO: Update Epics & Stories"]
+    J --> K["Update PRD/Architecture as needed"]
+    K --> G
+    I --> L["📁 Switch to IDE"]
+    L --> M["PO: Shard Documents"]
+    M --> N["Ready for SM/Dev Cycle"]
+    
+    style I fill:#34a853,color:#fff
+    style G fill:#f9ab00,color:#fff
+    style L fill:#1a73e8,color:#fff
+    style N fill:#34a853,color:#fff
+```
+
+**Key Planning Phases:**
+
+1. **Optional Analysis**: Analyst conducts market research and competitive analysis
+2. **Project Brief**: Foundation document created by Analyst or user
+3. **PRD Creation**: PM transforms brief into comprehensive product requirements
+4. **Architecture Design**: Architect creates technical foundation based on PRD
+5. **Validation & Alignment**: PO ensures all documents are consistent and complete
+6. **Refinement**: Updates to epics, stories, and documents as needed
+7. **Environment Transition**: Critical switch from web UI to IDE for development workflow
+8. **Document Preparation**: PO shards large documents for development consumption
+
+**Workflow Orchestration**: The `bmad-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases.
+
+### 5.2. The Core Development Cycle
+
+Once the initial planning and architecture phases are complete, the project moves into a cyclical development workflow, as detailed in the `bmad-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process.
+
+```mermaid
+graph TD
+    A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
+    B --> C["PO: Shard Arch"]
+    C --> D["Development Phase"]
+    D --> E["Scrum Master: Drafts next story from sharded epic"]
+    E --> F{"User Approval"}
+    F -->|Approved| G["Dev: Implement Story"]
+    F -->|Needs Changes| E
+    G --> H["Dev: Complete story Tasks"]
+    H --> I{"User Verification"}
+    I -->|Verified Complete| J["Mark Story as Done"]
+    I -->|Needs Fixes| G
+    J --> E
+
+    style J fill:#34a853,color:#fff
+```
+
+This cycle continues, with the Scrum Master and Developer agents working in tandem, until all stories in the epic are completed.