docs: clarify module requirements (no package.json needed)

- Modules only require module.yaml to function
- module-help.csv is optional but highly suggested for BMad help system
- package.json is only needed for npm publishing, not module functionality
- Add note about future auto-generation of module-help.csv from metadata
- Update all module structure examples to clarify optional vs required files

Author: Brian Madison

docs/explanation/module-building-architecture.md

@@ -58,18 +58,23 @@ The brief is exploratory and creative. You're discovering what your module shoul
 your-module/
 ├── src/
 │   ├── module.yaml              # Module metadata and config
-│   ├── module-help.csv          # Feature registry (auto-generated)
+│   ├── module-help.csv          # Feature registry (optional but powerful)
 │   ├── agents/                  # Agent directory
 │   │   └── your-agent.agent.yaml  # Agent SPEC files (stubs)
 │   ├── workflows/               # Workflow directory
 │   │   └── your-workflow/        # Workflow SPEC files (stubs)
 │   │       └── workflow.md
 │   └── _module-installer/       # Custom install prompts (if needed)
-├── package.json                  # NPM package config
 ├── README.md                     # Documentation template
 └── TODO.md                       # Implementation checklist
 ```
 
+For npm publishing, add:
+```
+├── package.json                  # NPM package config (publishing only)
+└── .npmignore                    # Excludes dev files from npm package
+```
+
 **What these SPEC files contain:**
 - **Agent specs** — Persona definitions (name, role, voice) as references for workflows
 - **Workflow specs** — Outline of steps, goals, structure (not finished workflows)
@@ -157,11 +162,16 @@ wedding-planner/
 │   │   │   └── workflow.md                    # SPEC
 │   │   └── day-of-schedule/
 │   │       └── workflow.md                    # SPEC
-├── package.json
 ├── README.md
 └── TODO.md
 ```
 
+For npm publishing, add:
+```
+├── package.json
+└── .npmignore
+```
+
 **What the SPEC files contain:**
 
 `budget-specialist.agent.yaml` (spec):
@@ -239,7 +249,7 @@ After Phase 3, your module is complete and functional:
 wedding-planner/
 ├── src/
 │   ├── module.yaml                          # ✅ Complete
-│   ├── module-help.csv                      # ✅ Complete
+│   ├── module-help.csv                      # ✅ Complete (optional but powerful)
 │   ├── agents/
 │   │   ├── budget-specialist.agent.yaml     # ✅ Built by Bond
 │   │   ├── vendor-coordinator.agent.yaml    # ✅ Built by Bond
@@ -248,11 +258,16 @@ wedding-planner/
 │   │   ├── budget-workshop/                 # ✅ Built by Wendy
 │   │   ├── vendor-vetting/                  # ✅ Built by Wendy
 │   │   └── day-of-schedule/                 # ✅ Built by Wendy
-├── package.json                             # ✅ Complete
 ├── README.md                                # ✅ Complete
 └── TODO.md                                  # ✅ All items checked
 ```
 
+For npm publishing, add:
+```
+├── package.json                             # For npm distribution
+└── .npmignore
+```
+
 ## Why This Architecture Works
 
 | Benefit | Explanation |

docs/how-to/validate-agents-and-workflows.md

@@ -174,10 +174,10 @@ Use Morgan's validation workflow:
 | Category | Checks |
 |----------|--------|
 | **module.yaml** | Metadata, install questions, config valid |
+| **module-help.csv** | Proper CSV format and required columns (if present) |
 | **Structure** | Agents, workflows, tools folders present |
 | **Agents** | All agent files valid |
 | **Workflows** | All workflow files valid |
-| **Package** | package.json configured correctly |
 
 ## Common Validation Issues
 

docs/reference/builder-commands.md

@@ -193,10 +193,10 @@ Validates a module.
 
 **Checks:**
 - `module.yaml` validity
+- `module-help.csv` format (if present)
 - Folder structure
 - Agent file compliance
 - Workflow file compliance
-- `package.json` configuration
 
 ## Command Quick Reference
 

docs/tutorials/create-your-first-module.md

@@ -13,7 +13,7 @@ This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad in
 - What a BMad module is and what it contains
 - How to create a module brief with Morgan (module-builder)
 - How to build a complete module from your brief
-- How to configure module.yaml and package.json
+- How to configure module.yaml and module-help.csv
 - How to publish your module to npm
 
 :::note[Prerequisites]
@@ -39,11 +39,16 @@ Every BMad module follows a standard structure:
 your-module/
 ├── src/
 │   ├── module.yaml          # Module metadata and install config
+│   ├── module-help.csv      # Feature registry for BMad help system
 │   ├── agents/              # Agent definitions (.agent.yaml)
 │   ├── workflows/           # Workflow files
 │   └── tools/               # Small reusable tools
-├── package.json             # NPM package info
 ├── README.md                # Module documentation
+```
+
+For npm publishing, add:
+```
+├── package.json             # NPM package info (for publishing only)
 └── .npmignore               # Excludes dev files from npm package
 ```
 
@@ -52,10 +57,11 @@ your-module/
 | Component | Purpose | Required |
 |-----------|---------|----------|
 | **module.yaml** | Metadata, install questions, config | ✅ Yes |
-| **package.json** | NPM publishing, version info | ✅ Yes |
+| **module-help.csv** | Feature registry for BMad help system | ⭐ Highly suggested |
 | **Agents** | AI assistants with specific roles | ⚪ Optional |
 | **Workflows** | Step-by-step processes | ⚪ Optional |
 | **Tools** | Reusable prompt files | ⚪ Optional |
+| **package.json** | NPM publishing, version info | 📦 For publishing only |
 
 ## Why Build Modules?
 
@@ -177,9 +183,26 @@ config:
   # Add your config keys here
 ```
 
-### package.json
+### module-help.csv (Optional but Powerful)
+
+The `module-help.csv` file registers your module's agents and workflows with BMad's intelligent help system. This enables contextual recommendations and smart workflow chaining.
 
-Configure `package.json` for npm publishing:
+:::tip[Why module-help.csv Matters]
+The BMad help system uses this file to suggest the right workflows at the right time. Without it, your module's features remain hidden. With it, they become part of the intelligent BMad ecosystem.
+:::
+
+```csv
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
+your-module,discovery,"Your Workflow Name",your-workflow,10,workflows/your-workflow/workflow.md,your-workflow,false,workflow-builder,,"Brief description of what this workflow does",_your-module-output/,
+```
+
+:::note[Future Changes]
+In a future release, `module-help.csv` will be auto-generated from workflow and agent metadata. For now, it's the manual way to tap into the power of the BMad help system.
+:::
+
+### package.json (For npm Publishing Only)
+
+If you plan to publish your module to npm, create `package.json`:
 
 ```json
 {
@@ -196,6 +219,10 @@ Configure `package.json` for npm publishing:
 Use scoped naming (`@username/module-name` or `@bmad-code-org/` for official modules).
 :::
 
+:::note[Local Modules Don't Need package.json]
+If you're only using your module locally or sharing it directly (folder, git repo), you can skip `package.json` entirely. It's only required for npm publishing.
+:::
+
 ## Step 4: Implement Your Agents and Workflows
 
 Morgan created spec files during the build step. Now implement your agents and workflows:
@@ -218,9 +245,10 @@ Before publishing, validate your module:
 
 Morgan checks:
 - `module.yaml` is complete and valid
+- `module-help.csv` is properly formatted (if present)
 - Agent files follow BMad standards
 - Workflows have proper structure
-- Package.json is configured correctly
+- Folder structure is correct
 
 Fix any issues Morgan identifies, then re-validate.