minor doc updates

Author: Brian Madison

docs/explanation/what-are-agents.md docs/explanation/what-are-bmad-agents.mddocs/explanation/what-are-agents.md renamed to docs/explanation/what-are-bmad-agents.md

@@ -2,7 +2,9 @@
 title: "Agents"
 ---
 
-Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
+BMad Agents are AI Persona files that your agent can adopt to better help you accomplish tasks, communicate with or enjoy. Each agent has a unique personality, specialized capabilities, and an interactive help menu.
+
+Additionally some agents can optionally have their own file system based memory, making them capable of remembering vast amounts of information that is relevant. This can open up many interesting use cases for you to explore.
 
 ## Agent Types
 
@@ -29,19 +31,18 @@ Simple agents are complete in a single file. They excel at well-defined tasks an
 Expert agents have a **sidecar** - a companion folder containing additional instructions, workflows, and memory files. They remember context across sessions and handle complex, multi-step tasks.
 
 **Best for:**
-- Domain specialists (security architect, game designer, product manager)
-- Tasks requiring persistent memory
-- Complex workflows with multiple stages
-- Projects that grow over time
+- Domain specialists (design, legal, therapy, companion)
+- Agents with built in commands defined in separate files that only they will utilize - these are gemerally more complex than the simple one or two line prompts for simple agent custom menu items
+  - Note: These commands will be launched by loading the agent - another option is to create a simple agent and skills separately.
 
-**Example:** A game architect that remembers your design decisions, maintains consistency across sprints, and coordinates with other specialists.
+**Example:** An accounting expert that has specialized workflows to guide you through tax preparation, but also remembers work you have done together before, and remembers details about you.
 
 ## Key Differences
 
 | Feature          | Simple         | Expert                     |
 | ---------------- | -------------- | -------------------------- |
 | **Files**        | Single file    | Agent + sidecar folder     |
-| **Memory**       | Session only   | Persistent across sessions |
+| **Memory**       | Usually no     | Persistent across sessions |
 | **Capabilities** | Focused scope  | Multi-domain, extensible   |
 | **Setup**        | Zero config    | Sidecar initialization     |
 | **Best Use**     | Specific tasks | Ongoing projects           |
@@ -60,10 +61,10 @@ All agents share these building blocks:
 - Skills, tools, and knowledge the agent can apply
 - Mapped to specific menu commands
 
-### Menu
+### Menu Items
 - Interactive command list
 - Triggers, descriptions, and handlers
-- Auto-includes help and exit options
+- Auto-includes help, chat, bmad-help and exit options
 
 ### Critical Actions (optional)
 - Instructions that execute before the agent starts
@@ -75,23 +76,6 @@ All agents share these building blocks:
 Choose **Simple** for focused, one-off tasks with no memory needs. Choose **Expert** when you need persistent context and complex workflows.
 :::
 
-**Choose Simple when:**
-- You need a task done quickly and reliably
-- The scope is well-defined and won't change much
-- You don't need the agent to remember things between sessions
-
-**Choose Expert when:**
-- You're building something complex over time
-- The agent needs to maintain context (project history, decisions)
-- You want the agent to coordinate workflows or other agents
-- Domain expertise requires specialized knowledge bases
-
 ## Creating Custom Agents
 
-BMad provides the **BMad Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](https://github.com/bmad-code-org/bmad-builder/blob/main/docs/tutorials/create-custom-agent.md) for step-by-step instructions.
-
-
-
-## Customizing Existing Agents
-
-You can modify any agent's behavior without editing core files. See [BMad Customization](/docs/how-to/customization/index.md) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained.
+See the [Agent Creation Guide](https://github.com/bmad-code-org/bmad-builder/blob/main/docs/tutorials/create-custom-agent.md) for step-by-step instructions on how to create your own agents and use them in the BMad Ecosystem.

docs/explanation/what-are-modules.md

@@ -2,84 +2,37 @@
 title: "Modules"
 ---
 
-Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
+Modules are bundles of agents, workflows, and configuration that solve specific problems or address particular domains. Think of them like plugins or extensions—packaged capabilities you can install to extend what's possible.
 
-## What is a Module?
+## What Is a Module?
 
 A module is a self-contained package that includes:
 
-- **Agents** - Specialized AI assistants
-- **Workflows** - Step-by-step processes
-- **Configuration** - Module-specific settings
-- **Documentation** - Usage guides and reference
+- **Agents** — Specialized AI assistants with specific roles
+- **Workflows** — Step-by-step processes for accomplishing tasks
+- **Configuration** — Module settings and variables
+- **Documentation** — Usage guides and reference
 
-## Official BMad Method and Builder Modules
+When you install a module, all its agents and workflows become available as commands.
+
+## Official Modules
 
 :::note[Core is Always Installed]
-The Core module is automatically included with every BMad installation. It provides the foundation that other modules build upon.
+The Core module comes with every BMad installation and provides the foundation other modules build upon.
 :::
 
-### Core Module
-Always installed, provides shared functionality:
-- Global configuration
-- Core workflows (Party Mode, Advanced Elicitation, Brainstorming)
-- Common tasks (document indexing, sharding, review)
-
-### BMad Method (BMM)
-Software and game development:
-- Project planning workflows
-- Implementation agents (Dev, PM, QA, Scrum Master)
-- Testing and architecture guidance
-
-### BMad Builder (BMB)
-Create custom solutions:
-- Agent creation workflows
-- Workflow authoring tools
-- Module scaffolding
-
-## Additional Official BMad Modules
-
-These are officially maintained modules by BMad but have their own repo's and docs.
-These give a good idea also of what can be done with the BMad builder and creating your own custom modules.
-
-### Creative Intelligence Suite (CIS)
-Innovation and creativity:
-- Creative thinking techniques
-- Innovation strategy workflows
-- Storytelling and ideation
-- [Available Here](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
-
-### BMad Game Dev (BMGD)
-Game development specialization:
-- Game design workflows
-- Narrative development
-- Performance testing frameworks
-- [Available Here](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
-
-## Module Structure
-
-Installed modules follow this structure:
-
-```
-_bmad/
-├── core/           # Always present
-├── bmm/            # BMad Method (if installed)
-├── bmb/            # BMad Builder (if installed)
-├── cis/            # Creative Intelligence (if installed)
-└── bmgd/           # Game Dev (if installed)
-```
+| Module | Purpose |
+|--------|---------|
+| **Core** | Global configuration, common workflows (Brainstorming, Party Mode), shared tasks |
+| **BMM** (Method) | Software and game development—planning, implementation agents, architecture |
+| **BMB** (Builder) | Creating custom agents, workflows, and modules |
+| **CIS** (Creative Intelligence) | Innovation, creativity techniques, storytelling, ideation |
+| **BMGD** (Game Dev) | Game design workflows, narrative development, performance testing |
 
 ## Custom Modules
 
-You can create your own modules containing:
-- Custom agents for your domain
-- Organizational workflows
-- Team-specific configurations
-
-Custom modules are installed the same way as official modules.
+You can create your own modules for your domain—team-specific workflows, organizational agents, custom configurations. They install the same way as official modules.
 
 ## Installing Modules
 
-During BMad installation, you choose which modules to install. You can also add or remove modules later by re-running the installer.
-
-See [Installation Guide](/docs/how-to/installation/index.md) for details.
+Choose which modules to install during setup, or add/remove modules later by re-running the installer. See [Installation Guide](/docs/how-to/install-custom-modules.md) for details.