documentation updates

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to this project
 
-Thank you for considering contributing to this project! This document outlines the process for contributing and some guidelines to follow.
+Thank you for contributing to this project! This document outlines the process for contributing and some guidelines to follow.
 
 🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
 
@@ -8,10 +8,7 @@ Thank you for considering contributing to this project! This document outlines t
 
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
-💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions:
+💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions or search past discussions or ideas.
-
-- **#general-dev** - Technical discussions, feature ideas, and development questions
-- **#bugs-issues** - Bug reports and issue discussions
 
 ## Code of Conduct
 
@@ -191,10 +188,6 @@ Fixes #[issue number] (if applicable)
 
 [2-3 bullets listing HOW you implemented it]
 
--
--
--
-
 ## Testing
 
 [1-2 sentences on how you tested this]

README.md

@@ -112,98 +112,6 @@ npm run install:bmad # build and install all to a destination folder
 
 BMAD™'s natural language framework works in ANY domain. Expansion packs provide specialized AI agents for creative writing, business strategy, health & wellness, education, and more. Also expansion packs can expand the core BMAD-METHOD™ with specific functionality that is not generic for all cases. [See the Expansion Packs Guide](docs/expansion-packs.md) and learn to create your own!
 
-## Codebase Flattener Tool
-
-The BMAD-METHOD™ includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption. This tool aggregates your entire codebase into a single XML file, making it easy to share your project context with AI assistants for analysis, debugging, or development assistance.
-
-### Features
-
-- **AI-Optimized Output**: Generates clean XML format specifically designed for AI model consumption
-- **Smart Filtering**: Automatically respects `.gitignore` patterns to exclude unnecessary files, plus optional project-level `.bmad-flattenignore` for additional exclusions
-- **Binary File Detection**: Intelligently identifies and excludes binary files, focusing on source code
-- **Progress Tracking**: Real-time progress indicators and comprehensive completion statistics
-- **Flexible Output**: Customizable output file location and naming
-
-### Usage
-
-```bash
-# Basic usage - creates flattened-codebase.xml in current directory
-npx bmad-method flatten
-
-# Specify custom input directory
-npx bmad-method flatten --input /path/to/source/directory
-npx bmad-method flatten -i /path/to/source/directory
-
-# Specify custom output file
-npx bmad-method flatten --output my-project.xml
-npx bmad-method flatten -o /path/to/output/codebase.xml
-
-# Combine input and output options
-npx bmad-method flatten --input /path/to/source --output /path/to/output/codebase.xml
-```
-
-### Example Output
-
-The tool will display progress and provide a comprehensive summary:
-
-```text
-📊 Completion Summary:
-✅ Successfully processed 156 files into flattened-codebase.xml
-📁 Output file: /path/to/your/project/flattened-codebase.xml
-📏 Total source size: 2.3 MB
-📄 Generated XML size: 2.1 MB
-📝 Total lines of code: 15,847
-🔢 Estimated tokens: 542,891
-📊 File breakdown: 142 text, 14 binary, 0 errors
-```
-
-The generated XML file contains your project's text-based source files in a structured format that AI models can easily parse and understand, making it perfect for code reviews, architecture discussions, or getting AI assistance with your BMAD-METHOD™ projects.
-
-#### Advanced Usage & Options
-
-- CLI options
-  - `-i, --input <path>`: Directory to flatten. Default: current working directory or auto-detected project root when run interactively.
-  - `-o, --output <path>`: Output file path. Default: `flattened-codebase.xml` in the chosen directory.
-- Interactive mode
-  - If you do not pass `--input` and `--output` and the terminal is interactive (TTY), the tool will attempt to detect your project root (by looking for markers like `.git`, `package.json`, etc.) and prompt you to confirm or override the paths.
-  - In non-interactive contexts (e.g., CI), it will prefer the detected root silently; otherwise it falls back to the current directory and default filename.
-- File discovery and ignoring
-  - Uses `git ls-files` when inside a git repository for speed and correctness; otherwise falls back to a glob-based scan.
-  - Applies your `.gitignore` plus a curated set of default ignore patterns (e.g., `node_modules`, build outputs, caches, logs, IDE folders, lockfiles, large media/binaries, `.env*`, and previously generated XML outputs).
-  - Supports an optional `.bmad-flattenignore` file at the project root for additional ignore patterns (gitignore-style). If present, its rules are applied after `.gitignore` and the defaults.
-
-##### `.bmad-flattenignore` example
-
-Create a `.bmad-flattenignore` file in the root of your project to exclude files that must remain in git but should not be included in the flattened XML:
-
-```text
-seeds/**
-scripts/private/**
-**/*.snap
-```
-
-- Binary handling
-  - Binary files are detected and excluded from the XML content. They are counted in the final summary but not embedded in the output.
-- XML format and safety
-  - UTF-8 encoded file with root element `<files>`.
-  - Each text file is emitted as a `<file path="relative/path">` element whose content is wrapped in `<![CDATA[ ... ]]>`.
-  - The tool safely handles occurrences of `]]>` inside content by splitting the CDATA to preserve correctness.
-  - File contents are preserved as-is and indented for readability inside the XML.
-- Performance
-  - Concurrency is selected automatically based on your CPU and workload size. No configuration required.
-  - Running inside a git repo improves discovery performance.
-
-#### Minimal XML example
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<files>
-  <file path="src/index.js"><![CDATA[
-    // your source content
-  ]]></file>
-</files>
-```
-
 ## Documentation & Resources
 
 ### Essential Guides

docs/GUIDING-PRINCIPLES.md

@@ -1,6 +1,6 @@
 # BMad Method Guiding Principles
 
-The BMad Method is a natural language framework for AI-assisted software development. These principles ensure contributions maintain the method's effectiveness.
+The BMad Core and Method is a natural language framework for AI-assisted workflow with human in the loop processing along with software development. These principles ensure contributions maintain the method's effectiveness.
 
 ## Core Principles
 
@@ -8,7 +8,7 @@ The BMad Method is a natural language framework for AI-assisted software develop
 
 - **Minimize dev agent dependencies**: Development agents that work in IDEs must have minimal context overhead
 - **Save context for code**: Every line counts - dev agents should focus on coding, not documentation
-- **Web agents can be larger**: Planning agents (PRD Writer, Architect) used in web UI can have more complex tasks and dependencies
+- **Planning agents can be larger**: Planning agents (PM, Architect) used in web UI can have more complex tasks and dependencies
 - **Small files, loaded on demand**: Multiple small, focused files are better than large files with many branches
 
 ### 2. Natural Language First
@@ -85,7 +85,7 @@ Templates follow the [BMad Document Template](../common/utils/bmad-doc-template.
 
 ## Remember
 
-- The power is in natural language orchestration, not code
+- The power is in natural language orchestration and human agent collaboration, not code
 - Dev agents code, planning agents plan
 - Keep dev agents lean for maximum coding efficiency
 - Expansion packs handle specialized domains

docs/flattener.md

@@ -0,0 +1,91 @@
+# Codebase Flattener Tool
+
+The BMAD-METHOD™ includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption when uploading to web AI tools. This tool aggregates your entire codebase into a single XML file, making it easy to share your project context with AI assistants for analysis, debugging, or development assistance.
+
+## Features
+
+- **AI-Optimized Output**: Generates clean XML format specifically designed for AI model consumption
+- **Smart Filtering**: Automatically respects `.gitignore` patterns to exclude unnecessary files, plus optional project-level `.bmad-flattenignore` for additional exclusions if planning to flatten an existing repository for external update and analysis
+- **Binary File Detection**: Intelligently identifies and excludes binary files, focusing on source code
+- **Progress Tracking**: Real-time progress indicators and comprehensive completion statistics
+- **Flexible Output**: Customizable output file location and naming
+
+## Usage
+
+```bash
+# Basic usage - creates flattened-codebase.xml in current directory
+npx bmad-method flatten
+
+# Specify custom input directory
+npx bmad-method flatten --input /path/to/source/directory
+npx bmad-method flatten -i /path/to/source/directory
+
+# Specify custom output file
+npx bmad-method flatten --output my-project.xml
+npx bmad-method flatten -o /path/to/output/codebase.xml
+
+# Combine input and output options
+npx bmad-method flatten --input /path/to/source --output /path/to/output/codebase.xml
+```
+
+## Example Output
+
+The tool will display progress and provide a comprehensive summary:
+
+```text
+📊 Completion Summary:
+✅ Successfully processed 156 files into flattened-codebase.xml
+📁 Output file: /path/to/your/project/flattened-codebase.xml
+📏 Total source size: 2.3 MB
+📄 Generated XML size: 2.1 MB
+📝 Total lines of code: 15,847
+🔢 Estimated tokens: 542,891
+📊 File breakdown: 142 text, 14 binary, 0 errors
+```
+
+The generated XML file contains your project's text-based source files in a structured format that AI models can easily parse and understand, making it perfect for code reviews, architecture discussions, or getting AI assistance with your BMAD-METHOD™ projects.
+
+## Advanced Usage & Options
+
+- CLI options
+  - `-i, --input <path>`: Directory to flatten. Default: current working directory or auto-detected project root when run interactively.
+  - `-o, --output <path>`: Output file path. Default: `flattened-codebase.xml` in the chosen directory.
+- Interactive mode
+  - If you do not pass `--input` and `--output` and the terminal is interactive (TTY), the tool will attempt to detect your project root (by looking for markers like `.git`, `package.json`, etc.) and prompt you to confirm or override the paths.
+  - In non-interactive contexts (e.g., CI), it will prefer the detected root silently; otherwise it falls back to the current directory and default filename.
+- File discovery and ignoring
+  - Uses `git ls-files` when inside a git repository for speed and correctness; otherwise falls back to a glob-based scan.
+  - Applies your `.gitignore` plus a curated set of default ignore patterns (e.g., `node_modules`, build outputs, caches, logs, IDE folders, lockfiles, large media/binaries, `.env*`, and previously generated XML outputs).
+  - Supports an optional `.bmad-flattenignore` file at the project root for additional ignore patterns (gitignore-style). If present, its rules are applied after `.gitignore` and the defaults.
+
+## `.bmad-flattenignore` example
+
+Create a `.bmad-flattenignore` file in the root of your project to exclude files that must remain in git but should not be included in the flattened XML:
+
+```text
+seeds/**
+scripts/private/**
+**/*.snap
+```
+
+- Binary handling
+  - Binary files are detected and excluded from the XML content. They are counted in the final summary but not embedded in the output.
+- XML format and safety
+  - UTF-8 encoded file with root element `<files>`.
+  - Each text file is emitted as a `<file path="relative/path">` element whose content is wrapped in `<![CDATA[ ... ]]>`.
+  - The tool safely handles occurrences of `]]>` inside content by splitting the CDATA to preserve correctness.
+  - File contents are preserved as-is and indented for readability inside the XML.
+- Performance
+  - Concurrency is selected automatically based on your CPU and workload size. No configuration required.
+  - Running inside a git repo improves discovery performance.
+
+## Minimal XML example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<files>
+  <file path="src/index.js"><![CDATA[
+    // your source content
+  ]]></file>
+</files>
+```

docs/versions.md

@@ -6,7 +6,7 @@
 - [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2)
 - [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1)
 
-## Current Version: V4 - Alpha
+## Current Version: V4
 
 Guiding Principles of V4:
 

docs/working-in-the-brownfield.md

@@ -1,17 +1,14 @@
 # Working in the Brownfield: A Complete Guide
 
-> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
+## Critical Tip
->
+
-> Gemini Web's 1M+ token context window or Gemini CLI (when it's working) can analyze your ENTIRE codebase, or critical sections of it, all at once (obviously within reason):
+Regardless of what you plan for your existing project you want to start agentic coding with, producing contextual artifacts for agents is of the highest importance.
->
+
-> - Upload via GitHub URL or use gemini cli in the project folder
+If using Claude Code - it is recommended to use the document-project task with the architect to systematically produce important key artifacts for your codebase.
-> - If working in the web: use `npx bmad-method flatten` to flatten your project into a single file, then upload that file to your web agent. To exclude additional files that must remain in git but shouldn't be sent to the AI, add a `.bmad-flattenignore` file at the project root (gitignore-style), e.g.:
+
->
+Optionally you can product context information and understanding for your repo utilizing web agents like Gemini. If its already in github, you can provide the project URL in gemini and use the agents to help analyze or document the project with the team fullstack or the architect specific gem.
-> ```text
+
-> seeds/**
+If your project is too large, you can also flatten your codebase - which can make it easier to upload or use with some tools. You can read more about the optional tool in the [Flattener Guide](./flattener.md)
-> scripts/private/**
-> **/*.snap
-> ```
 
 ## What is Brownfield Development?
 
@@ -32,9 +29,15 @@ If you have just completed an MVP with BMad, and you want to continue with post-
 
 ## The Complete Brownfield Workflow
 
+Starting in the Web Option (potentially save some cost but a potentially more frustrating experience):
+
 1. **Follow the [<ins>User Guide - Installation</ins>](user-guide.md#installation) steps to setup your agent in the web.**
 2. **Generate a 'flattened' single file of your entire codebase** run: `npx bmad-method flatten`
 
+Starting in an IDE with large context and good models (Its important to use quality models for this process for the best results)
+
+1. In Claude Code or a similar IDE, select the architect agent and then use the \*document-project task. You will want to ensure you are validating and directing the agent to produce the best possible documents for LLMs to understand your code base, and not include any misleading or unnecessary info.
+
 ### Choose Your Approach
 
 #### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "4.42.1",
+  "version": "4.43.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

test.md

@@ -1 +0,0 @@
-# Test

tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.42.1",
+  "version": "4.43.0",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "keywords": [
     "bmad",