feat(install): clarify orchestrator custom install path

- remove misleading custom override for orchestrator agent generation
- document fork custom-source procedure with bmm + copilot
- add copilot install test coverage for bmad-orchestrator agents-only path

_bmad/custom/config.toml

@@ -2,11 +2,9 @@
 # Committed to the repo — applies to every developer on the project.
 # Tables deep-merge over base config; keyed entries merge by key.
 
-# Orchestrator agent — enable in custom installs
+# NOTE: Do not declare bmad-orchestrator here to "enable" Copilot agent generation.
-[agents.bmad-orchestrator]
+# Copilot Custom Agents files are generated from installed skill sources
-name = "Orchestrator"
+# (skill-manifest + skill customize.toml [agent]), not from _bmad/custom overrides.
-title = "BMAD Orchestrator"
+# Keep orchestrator source-of-truth in:
-icon = "🧭"
+#   - src/bmm-skills/module.yaml
-team = "software-development"
+#   - src/bmm-skills/4-implementation/bmad-orchestrator/customize.toml
-module = "bmm"
-description = "Routes natural-language intent to the right BMAD skill or named agent, verifies lightweight prerequisites, and suggests the next step without forcing the user to memorize commands."

docs/how-to/install-custom-modules.md

@@ -105,6 +105,24 @@ Multiple sources can be comma-separated:
 --custom-source /path/one,https://github.com/org/repo,/path/two
 ```
 
+### Fork BMAD with bmad-orchestrator in BMM
+
+If your fork ships `bmad-orchestrator` inside `src/bmm-skills`, install from your fork as a custom source and include `bmm` in module selection.
+
+```bash
+npx bmad-method install \
+  --directory . \
+  --modules bmm \
+  --custom-source https://github.com/your-org/your-bmad-fork \
+  --tools github-copilot \
+  --yes
+```
+
+Notes:
+
+- `bmad-orchestrator` must exist as a native BMM skill source with a valid `[agent]` block in `customize.toml`.
+- Copilot Custom Agents generation depends on the installer version consuming your fork. If your installer build predates the current agent-discovery behavior, the skill may install correctly while the Copilot agent pointer is not generated yet.
+
 ## How Module Discovery Works
 
 The installer uses two modes to find installable modules in a source:

test/test-installation-components.js

@@ -596,6 +596,7 @@ async function runTests() {
         '"bmad-master","bmad-master","Workflow with no customize.toml — should NOT appear in Copilot agents picker","core","_bmad/core/bmad-master/SKILL.md"',
         '"bmad-agent-fixture","bmad-agent-fixture","Persona agent — customize.toml has [agent], SHOULD appear","core","_bmad/core/bmad-agent-fixture/SKILL.md"',
         '"bmad-tea","bmad-tea","Non-conventional id but [agent] in customize.toml — SHOULD appear","core","_bmad/core/bmad-tea/SKILL.md"',
+        '"bmad-orchestrator","bmad-orchestrator","BMM orchestrator persona with [agent] in customize.toml — SHOULD appear","bmm","_bmad/bmm/4-implementation/bmad-orchestrator/SKILL.md"',
         '"bmad-agent-builder","bmad-agent-builder","Skill-builder workflow — id contains -agent- but customize.toml has [workflow] — should NOT appear","core","_bmad/core/bmad-agent-builder/SKILL.md"',
         '"bmad-help","bmad-help","Meta-help skill — no customize.toml; SHOULD NOT appear in agents picker (toml-driven filter)","core","_bmad/core/bmad-help/SKILL.md"',
         '',
@@ -627,6 +628,15 @@ async function runTests() {
       path.join(installedBmadDir17, 'core', 'bmad-tea', 'customize.toml'),
       ['[agent]', 'name = "Murat"', 'title = "Test Architect"', ''].join('\n'),
     );
+    await fs.ensureDir(path.join(installedBmadDir17, 'bmm', '4-implementation', 'bmad-orchestrator'));
+    await fs.writeFile(
+      path.join(installedBmadDir17, 'bmm', '4-implementation', 'bmad-orchestrator', 'SKILL.md'),
+      ['---', 'name: bmad-orchestrator', 'description: fixture for bmad-orchestrator', '---', '', 'Body of bmad-orchestrator.'].join('\n'),
+    );
+    await fs.writeFile(
+      path.join(installedBmadDir17, 'bmm', '4-implementation', 'bmad-orchestrator', 'customize.toml'),
+      ['[agent]', 'name = "Orchestrator"', 'title = "BMAD Orchestrator"', ''].join('\n'),
+    );
     // [workflow] customize.toml for the meta-skill — its id contains `-agent-`
     // but it is NOT a persona (mirrors bmad-agent-builder in production).
     await fs.writeFile(
@@ -677,6 +687,7 @@ async function runTests() {
     const agentsDir17 = path.join(tempProjectDir17, '.github', 'agents');
     const agentFileForPersona17 = path.join(agentsDir17, 'bmad-agent-fixture.agent.md');
     const agentFileForTea17 = path.join(agentsDir17, 'bmad-tea.agent.md');
+    const agentFileForOrchestrator17 = path.join(agentsDir17, 'bmad-orchestrator.agent.md');
     const agentFileForWorkflow17 = path.join(agentsDir17, 'bmad-master.agent.md');
     const agentFileForMetaSkill17 = path.join(agentsDir17, 'bmad-agent-builder.agent.md');
     const agentFileForBmadHelp17 = path.join(agentsDir17, 'bmad-help.agent.md');
@@ -686,6 +697,10 @@ async function runTests() {
       'Persona agent ([agent] in customize.toml) gets a .agent.md file in .github/agents/',
     );
     assert(await fs.pathExists(agentFileForTea17), 'Non-conventional id with [agent] in customize.toml is included (no allowlist needed)');
+    assert(
+      await fs.pathExists(agentFileForOrchestrator17),
+      'BMM orchestrator with [agent] customize.toml is included in Copilot agents picker',
+    );
     assert(!(await fs.pathExists(agentFileForWorkflow17)), 'Workflow skill (no customize.toml) is FILTERED OUT of .github/agents/');
     assert(
       !(await fs.pathExists(agentFileForBmadHelp17)),