diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index aa358f685..98efcc247 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -286,7 +286,7 @@
       "name": "gem-team",
       "source": "gem-team",
       "description": "Self-Learning Multi-agent orchestration harness for spec-driven development and automated verification.",
-      "version": "1.16.0"
+      "version": "1.20.0"
     },
     {
       "name": "go-mcp-development",
diff --git a/agents/gem-browser-tester.agent.md b/agents/gem-browser-tester.agent.md
index d49869bdd..ddca369c2 100644
--- a/agents/gem-browser-tester.agent.md
+++ b/agents/gem-browser-tester.agent.md
@@ -4,6 +4,8 @@ name: gem-browser-tester
 argument-hint: "Enter task_id, plan_id, plan_path, and test validation_matrix or flow definitions."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the BROWSER TESTER
diff --git a/agents/gem-code-simplifier.agent.md b/agents/gem-code-simplifier.agent.md
index 77977629e..caff6bf2e 100644
--- a/agents/gem-code-simplifier.agent.md
+++ b/agents/gem-code-simplifier.agent.md
@@ -4,6 +4,8 @@ name: gem-code-simplifier
 argument-hint: "Enter task_id, scope (single_file|multiple_files|project_wide), targets (file paths/patterns), and focus (dead_code|complexity|duplication|naming|all)."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the CODE SIMPLIFIER
diff --git a/agents/gem-critic.agent.md b/agents/gem-critic.agent.md
index 713ef88ff..267a61880 100644
--- a/agents/gem-critic.agent.md
+++ b/agents/gem-critic.agent.md
@@ -4,6 +4,8 @@ name: gem-critic
 argument-hint: "Enter plan_id, plan_path, scope (plan|code|architecture), and target to critique."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the CRITIC
diff --git a/agents/gem-debugger.agent.md b/agents/gem-debugger.agent.md
index 755e90b90..114069dfb 100644
--- a/agents/gem-debugger.agent.md
+++ b/agents/gem-debugger.agent.md
@@ -4,6 +4,8 @@ name: gem-debugger
 argument-hint: "Enter task_id, plan_id, plan_path, and error_context (error message, stack trace, failing test) to diagnose."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the DEBUGGER
diff --git a/agents/gem-designer-mobile.agent.md b/agents/gem-designer-mobile.agent.md
index 7e923de37..4782db527 100644
--- a/agents/gem-designer-mobile.agent.md
+++ b/agents/gem-designer-mobile.agent.md
@@ -4,6 +4,8 @@ name: gem-designer-mobile
 argument-hint: "Enter task_id, plan_id (optional), plan_path (optional), mode (create|validate), scope (component|screen|navigation|design_system), target, context (framework, library), and constraints (platform, responsive, accessible, dark_mode)."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the DESIGNER-MOBILE
@@ -336,7 +338,7 @@ Return JSON per `Output Format`
 ### Execution
 
 - Priority order: Tools > Tasks > Scripts > CLI
-- For user input/permissions: use `vscode_askQuestions` tool.
+- For user input/permissions: use `vscode_askQuestions` or similar tool.
 - Batch independent calls, prioritize I/O-bound
 - Retry: 3x
 - Output: specs + JSON, no summaries unless failed
diff --git a/agents/gem-designer.agent.md b/agents/gem-designer.agent.md
index fb8351bca..e24539eaf 100644
--- a/agents/gem-designer.agent.md
+++ b/agents/gem-designer.agent.md
@@ -4,6 +4,8 @@ name: gem-designer
 argument-hint: "Enter task_id, plan_id (optional), plan_path (optional), mode (create|validate), scope (component|page|layout|design_system), target, context (framework, library), and constraints (responsive, accessible, dark_mode)."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the DESIGNER
@@ -277,7 +279,7 @@ Return JSON per `Output Format`
 ### Execution
 
 - Priority order: Tools > Tasks > Scripts > CLI
-- For user input/permissions: use `vscode_askQuestions` tool.
+- For user input/permissions: use `vscode_askQuestions` or similar tool.
 - Batch independent calls, prioritize I/O-bound
 - Retry: 3x
 - Output: specs + JSON, no summaries unless failed
diff --git a/agents/gem-devops.agent.md b/agents/gem-devops.agent.md
index a7d578da2..5ba54183f 100644
--- a/agents/gem-devops.agent.md
+++ b/agents/gem-devops.agent.md
@@ -4,6 +4,8 @@ name: gem-devops
 argument-hint: "Enter task_id, plan_id, plan_path, task_definition, environment (dev|staging|prod), requires_approval flag, and devops_security_sensitive flag."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the DEVOPS
@@ -212,7 +214,7 @@ Return JSON per `Output Format`
 ### Execution
 
 - Priority order: Tools > Tasks > Scripts > CLI
-- For user input/permissions: use `vscode_askQuestions` tool.
+- For user input/permissions: use `vscode_askQuestions` or similar tool.
 - Batch independent calls, prioritize I/O-bound
 - Retry: 3x
 - Output: JSON only, no summaries unless failed
diff --git a/agents/gem-documentation-writer.agent.md b/agents/gem-documentation-writer.agent.md
index 80278e71f..47ebf1bf5 100644
--- a/agents/gem-documentation-writer.agent.md
+++ b/agents/gem-documentation-writer.agent.md
@@ -4,6 +4,8 @@ name: gem-documentation-writer
 argument-hint: "Enter task_id, plan_id, plan_path, task_definition with task_type (documentation|walkthrough|update), audience, coverage_matrix."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the DOCUMENTATION WRITER
diff --git a/agents/gem-implementer-mobile.agent.md b/agents/gem-implementer-mobile.agent.md
index 288d7e94e..199512c5c 100644
--- a/agents/gem-implementer-mobile.agent.md
+++ b/agents/gem-implementer-mobile.agent.md
@@ -4,6 +4,8 @@ name: gem-implementer-mobile
 argument-hint: "Enter task_id, plan_id, plan_path, and mobile task_definition to implement for iOS/Android."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the IMPLEMENTER-MOBILE
diff --git a/agents/gem-implementer.agent.md b/agents/gem-implementer.agent.md
index d68cd15df..4a1b49788 100644
--- a/agents/gem-implementer.agent.md
+++ b/agents/gem-implementer.agent.md
@@ -4,6 +4,8 @@ name: gem-implementer
 argument-hint: "Enter task_id, plan_id, plan_path, and task_definition with tech_stack to implement."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the IMPLEMENTER
diff --git a/agents/gem-mobile-tester.agent.md b/agents/gem-mobile-tester.agent.md
index 8d5a796b7..40cca92f9 100644
--- a/agents/gem-mobile-tester.agent.md
+++ b/agents/gem-mobile-tester.agent.md
@@ -4,6 +4,8 @@ name: gem-mobile-tester
 argument-hint: "Enter task_id, plan_id, plan_path, and mobile test definition to run E2E tests on iOS/Android."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the MOBILE TESTER
diff --git a/agents/gem-orchestrator.agent.md b/agents/gem-orchestrator.agent.md
index d160bdff5..c337ba809 100644
--- a/agents/gem-orchestrator.agent.md
+++ b/agents/gem-orchestrator.agent.md
@@ -4,6 +4,7 @@ name: gem-orchestrator
 argument-hint: "Describe your objective or task. Include plan_id if resuming."
 disable-model-invocation: true
 user-invocable: true
+mode: primary
 ---
 
 # You are the ORCHESTRATOR
@@ -71,14 +72,14 @@ Route based on `user_intent` from researcher:
 
 #### 5.1 Validation
 
-- Validation not needed for low complexity plans with no clarifications/gray_areas. For all others:
+- Validation not needed for low complexity plans. For:
   - Medium complexity: delegate to `gem-reviewer` for plan review.
-  - High complexity: delegate to both `gem-reviewer` for plan review and `gem-critic` with scope=plan and target=plan.yaml for plan review in parallel.
+  - High complexity: delegate to both `gem-reviewer` for plan review and `gem-critic` with scope=plan and target=plan.yaml for plan review and critic in parallel.
 - IF failed/blocking: Loop to `gem-planner` with feedback (max 3 iterations)
 
 #### 5.2 Present
 
-- Present plan via `vscode_askQuestions` if complexity is medium/ high
+- Present plan via `vscode_askQuestions` or similar tool if complexity is medium/ high
 - IF user requests changes or feedback → replan, otherwise continue to execution
 
 ### 6. Phase 6: Execution Loop
@@ -235,7 +236,7 @@ Blocked tasks: task_id, why blocked, how long waiting
 
 ### Execution
 
-- Use `vscode_askQuestions` for user input
+- Use `vscode_askQuestions` or similar tool for user input
 - Read orchestration metadata: plan.yaml, PRD.yaml, AGENTS.md, agent outputs, Memory
 - Delegate ALL validation, research, analysis to subagents
 - Batch independent delegations (up to 4 parallel)
@@ -289,14 +290,14 @@ Run I/O and other operations in parallel and minimize repeated reads.
 ### Directives
 
 - Execute autonomously — complete ALL waves/ tasks without pausing for user confirmation between waves.
-- For approvals (plan, deployment): use `vscode_askQuestions` with context
+- For approvals (plan, deployment): use `vscode_askQuestions` or similar tool with context
 - Handle needs_approval: present → IF approved, re-delegate; IF denied, mark blocked
 - Delegation First: NEVER execute ANY task yourself. Always delegate to subagents
 - Even simplest/meta tasks handled by subagents
 - Handle failure: IF failed → debugger diagnose → retry 3x → escalate
 - Route user feedback → Planning Phase
 - Team Lead Personality: Brutally brief. Exciting, motivating, sarcastic. Announce progress at key moments as brief STATUS UPDATES (never as questions)
-- Update `manage_todo_list` and task/ wave status in `plan` after every task/wave/subagent
+- Update `manage_todo_list` or similar tools and task/ wave status in `plan` after every task/wave/subagent
 - AGENTS.md Maintenance: delegate to `gem-documentation-writer`
 - PRD Updates: delegate to `gem-documentation-writer`
 
diff --git a/agents/gem-planner.agent.md b/agents/gem-planner.agent.md
index 86dfadc10..78a0a1476 100644
--- a/agents/gem-planner.agent.md
+++ b/agents/gem-planner.agent.md
@@ -4,6 +4,8 @@ name: gem-planner
 argument-hint: "Enter plan_id, objective, and task_clarifications."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the PLANNER
diff --git a/agents/gem-researcher.agent.md b/agents/gem-researcher.agent.md
index a8e176e20..38f903928 100644
--- a/agents/gem-researcher.agent.md
+++ b/agents/gem-researcher.agent.md
@@ -4,6 +4,8 @@ name: gem-researcher
 argument-hint: "Enter plan_id, objective, focus_area (optional), and task_clarifications array."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the RESEARCHER
@@ -45,7 +47,7 @@ Understand intent, resolve ambiguity, confirm scope. Workflow:
 1. Check existing plan → Ask "Continue, modify, or fresh?"
 2. Set `user_intent`: continue_plan | modify_plan | new_task
 3. Detect gray areas in user request → IF found → Generate 2-4 options each
-4. Present via `vscode_askQuestions`, classify:
+4. Present via `vscode_askQuestions` or similar tool, classify:
    - Architectural → `architectural_decisions`
    - Task-specific → `task_clarifications`
 5. Assess complexity → Output intent, clarifications, decisions, gray_areas
@@ -315,7 +317,7 @@ gaps: # REQUIRED
 ### Execution
 
 - Priority order: Tools > Tasks > Scripts > CLI
-- For user input/permissions: use `vscode_askQuestions` tool.
+- For user input/permissions: use `vscode_askQuestions` or similar tool.
 - Batch independent calls, prioritize I/O-bound (searches, reads)
 - Use semantic_search, grep_search, read_file
 - Retry: 3x
diff --git a/agents/gem-reviewer.agent.md b/agents/gem-reviewer.agent.md
index d9e1f69c1..08c8d9228 100644
--- a/agents/gem-reviewer.agent.md
+++ b/agents/gem-reviewer.agent.md
@@ -4,6 +4,8 @@ name: gem-reviewer
 argument-hint: "Enter task_id, plan_id, plan_path, review_scope (plan|task|wave), and review criteria for compliance and security audit."
 disable-model-invocation: false
 user-invocable: false
+mode: subagent
+hidden: true
 ---
 
 # You are the REVIEWER
diff --git a/plugins/gem-team/.github/plugin/plugin.json b/plugins/gem-team/.github/plugin/plugin.json
index fbf189385..5e5f34c30 100644
--- a/plugins/gem-team/.github/plugin/plugin.json
+++ b/plugins/gem-team/.github/plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "gem-team",
-  "version": "1.16.0",
+  "version": "1.20.0",
   "description": "Self-Learning Multi-agent orchestration harness for spec-driven development and automated verification.",
   "author": {
     "name": "mubaidr",
diff --git a/plugins/gem-team/README.md b/plugins/gem-team/README.md
index e7b020d23..d1b84dffe 100644
--- a/plugins/gem-team/README.md
+++ b/plugins/gem-team/README.md
@@ -6,6 +6,15 @@ Self-Learning Multi-agent orchestration harness for spec-driven development and
 
 ## Quick Start
 
+```bash
+# Install via APM (recommended)
+apm install mubaidr/gem-team
+
+# Or register as a marketplace
+apm marketplace add mubaidr/gem-team
+apm install gem-team@gem-team
+```
+
 See [all supported installation options](#installation) below.
 
 ---
@@ -108,20 +117,183 @@ User Goal → Orchestrator → [Simple: Research/Plan] or [Complex: Discuss →
 
 ## Installation
 
-| Method                               | Command / Link                                                                                                                                                                                                                                                                                                                                | Docs                                                                                              |
-| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
-| **Code**                             | **[Install Now](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%253A%252F%252Fraw.githubusercontent.com%252Fgithub%252Fawesome-copilot%252Fmain%252F.agents)**                                                                                                                                   | [Copilot Docs](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-chat) |
-| **Code Insiders**                    | **[Install Now](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%253A%252F%252Fraw.githubusercontent.com%252Fgithub%252Fawesome-copilot%252Fmain%252F.agents)**                                                                                                                          | [Copilot Docs](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-chat) |
-| **APM <br/> (All AI coding agents)** | `apm install mubaidr/gem-team`                                                                                                                                                                                                                                                                                                                | [APM Docs](https://microsoft.github.io/apm/)                                                      |
-| **Copilot CLI (Marketplace)**        | `copilot plugin install gem-team@awesome-copilot`                                                                                                                                                                                                                                                                                             | [CLI Docs](https://github.com/github/copilot-cli)                                                 |
-| **Copilot CLI (Direct)**             | `copilot plugin install gem-team@mubaidr`                                                                                                                                                                                                                                                                                                     | [CLI Docs](https://github.com/github/copilot-cli)                                                 |
-| **Windsurf**                         | `codeium agent install mubaidr/gem-team`                                                                                                                                                                                                                                                                                                      | [Windsurf Docs](https://docs.codeium.com/windsurf)                                                |
-| **Claude Code**                      | `claude plugin install mubaidr/gem-team`                                                                                                                                                                                                                                                                                                      | [Claude Docs](https://docs.anthropic.com/en/docs/claude-code)                                     |
-| **OpenCode**                         | `opencode plugin install mubaidr/gem-team`                                                                                                                                                                                                                                                                                                    | [OpenCode Docs](https://opencode.ai/docs/)                                                        |
-| **Manual <br/> (Copy agent files)**  | VS Code: `~/.vscode/agents/` <br/> VS Code Insiders: `~/.vscode- insiders/agents/` <br/> GitHub Copilot: `~/.github/copilot/agents/` <br/> GitHub Copilot (project): `.github/plugin/agents/` <br/> Windsurf: `~/.windsurf/agents/` <br/> Claude: `~/.claude/agents/` <br/> Cursor: `~/.cursor/agents/` <br/> OpenCode: `~/.opencode/agents/` | —                                                                                                 |
+### Install APM First
+
+If you don't have APM installed, install it first:
+
+```bash
+# macOS/Linux
+curl -fsSL https://microsoft.github.io/apm/install.sh | sh
+
+# Windows (PowerShell)
+irm https://microsoft.github.io/apm/install.ps1 | iex
+
+# Or via npm
+npm install -g @microsoft/apm
+```
+
+**Why APM?** Universal package manager for AI coding tools. One command installs to all your tools (Copilot CLI, Claude Code, Cursor, OpenCode). Handles version locking, updates, and dependencies automatically.
+
+[APM Documentation](https://microsoft.github.io/apm/) | [GitHub](https://github.com/microsoft/apm)
+
+---
+
+Choose the method that works best for your workflow:
+
+### Method 1: Direct Install via APM (Recommended)
+
+Fastest way to get started. APM automatically detects your tool and installs to the correct location.
+
+```bash
+apm install mubaidr/gem-team
+```
+
+**Works with:** GitHub Copilot CLI, Claude Code, Cursor, OpenCode
+
+[APM Documentation](https://microsoft.github.io/apm/getting-started/quick-start/)
+
+---
+
+### Method 2: Via Marketplace
+
+Add gem-team as a marketplace, then install from it. Useful for browsing available agents and managing updates.
+
+#### GitHub Copilot CLI
+
+```bash
+# Add marketplace
+copilot plugin marketplace add mubaidr/gem-team
+
+# Browse available plugins
+copilot plugin marketplace browse gem-team
+
+# Install
+copilot plugin install gem-team@gem-team
+```
+
+#### Claude Code
+
+```bash
+# Add marketplace
+/plugin marketplace add mubaidr/gem-team
+
+# Browse in UI
+/plugin
+
+# Install
+/plugin install gem-team@gem-team
+```
+
+#### Cursor IDE
+
+```bash
+# Add marketplace via APM
+apm marketplace add mubaidr/gem-team
+
+# Install
+apm install gem-team@gem-team
+```
 
 ---
 
+### Method 3: From awesome-copilot Marketplace
+
+Install from the official awesome-copilot marketplace (GitHub Copilot CLI only).
+
+```bash
+# awesome-copilot is pre-registered by default
+copilot plugin install gem-team@awesome-copilot
+```
+
+**Note:** This method is only available if gem-team is listed in the awesome-copilot marketplace.
+
+---
+
+### Method 4: Local/Manual Installation
+
+For development, testing, or offline use.
+
+#### Clone Repository
+
+```bash
+git clone https://github.com/mubaidr/gem-team.git
+cd gem-team
+```
+
+#### Claude Code
+
+```bash
+# Load as local plugin
+claude --plugin-dir .
+
+# Or add as local marketplace
+/plugin marketplace add ./
+
+# Reload after changes
+/reload-plugins
+```
+
+#### Cursor IDE
+
+```bash
+# Option 1: Via chat command
+# In Cursor: /add-plugin /absolute/path/to/gem-team
+
+# Option 2: Copy agents to project
+# One-line install: Copy agents and rename to .mdc
+mkdir -p .cursor/rules && cp .apm/agents/*.agent.md .cursor/rules/ && cd .cursor/rules && for f in *.agent.md; do mv "$f" "${f%.agent.md}.mdc"; done && cd ../..
+```
+
+#### GitHub Copilot CLI
+
+```bash
+# Add as local marketplace
+copilot plugin marketplace add /absolute/path/to/gem-team
+
+# Install
+copilot plugin install gem-team@gem-team
+```
+
+#### Manual Copy (Any Tool)
+
+```bash
+# Copy agents to your tool's directory
+# GitHub Copilot: ~/.copilot/
+# Claude Code: ~/.claude/plugins/
+# Cursor: .cursor/rules/
+# OpenCode: .opencode/plugins/
+
+cp -r .apm/agents <destination>
+```
+
+---
+
+### VS Code Extension (GitHub Copilot)
+
+Search for "gem-team" in the VS Code Extensions marketplace.
+
+1. Open VS Code
+2. Go to Extensions (Ctrl+Shift+X)
+3. Search "gem-team"
+4. Click Install
+
+---
+
+### Verification
+
+After installation, verify agents are available:
+
+```bash
+# GitHub Copilot CLI
+copilot plugin list
+
+# Claude Code
+/plugin list
+
+# APM (any tool)
+apm list
+```
+
 ## The Agent Team
 
 ### Core Workflow