fix: differentiate VS Code and Copilot CLI as separate targets in user-scope registry

Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>
Agent-Logs-Url: https://github.com/microsoft/apm/sessions/b36f06ca-13e4-472b-a4ec-95e22f01f52e

Author: Copilot

docs/src/content/docs/guides/scoped-installation.md

@@ -40,7 +40,8 @@ Not all AI tools read primitives from user-level directories. APM warns during `
 | Target | User-level directory | Status | Primitives at user scope | Reference |
 |--------|---------------------|--------|--------------------------|-----------|
 | Claude Code | `~/.claude/` | Supported | commands, agents, skills, hooks | [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings) |
-| Copilot | `~/.github/` | Not supported | None (VS Code reads `.github/` from workspace only; user config is via VS Code settings) | [VS Code custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) |
+| Copilot (CLI) | `~/.copilot/` | Supported | agents | [Custom agents for CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli) |
+| VS Code | User settings.json | Partial | MCP servers only (via VS Code user settings) | [VS Code settings](https://code.visualstudio.com/docs/configure/settings) |
 | Cursor | `~/.cursor/` | Not supported | None (user rules are managed via Cursor Settings UI) | [Cursor rules docs](https://cursor.com/docs/rules) |
 | OpenCode | `~/.opencode/` | Unverified | None confirmed | No official docs available |
 
@@ -58,5 +59,6 @@ apm uninstall -g microsoft/apm-sample-package
 |----------|-------|
 | Team-shared instructions and prompts | Project (`apm install`) |
 | Personal Claude Code commands and agents | User (`apm install -g`) |
+| Personal Copilot CLI agents | User (`apm install -g`) |
 | CI/CD reproducible setup | Project |
-| Cross-project coding standards (Claude Code) | User |
+| Cross-project coding standards (Claude Code, Copilot CLI) | User |

src/apm_cli/core/scope.py

@@ -12,9 +12,12 @@
 - **Claude Code** (fully supported): reads ``~/.claude/`` for global
   commands, agents, skills, and ``CLAUDE.md``.
   Ref: https://docs.anthropic.com/en/docs/claude-code/settings
-- **Copilot** (not supported): VS Code reads ``.github/`` only from the
-  workspace root; user-level configuration lives in VS Code settings.
-  Ref: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
+- **Copilot CLI** (supported): reads ``~/.copilot/agents/`` for
+  user-level custom agents.
+  Ref: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
+- **VS Code** (partial): supports user-level MCP servers via
+  VS Code user ``settings.json``; ``.github/`` is workspace-only.
+  Ref: https://code.visualstudio.com/docs/configure/settings
 - **Cursor** (not supported): user-level rules are managed via the
   Cursor Settings UI, not the filesystem.
   Ref: https://cursor.com/docs/rules
@@ -123,10 +126,14 @@ def ensure_user_dirs() -> Path:
 #   from it and merges them with project-level ``.claude/``.
 #   Ref: https://docs.anthropic.com/en/docs/claude-code/settings
 #
-# * Copilot -- VS Code reads ``.github/`` only from the current
-#   workspace root.  User-level instructions are configured via
-#   VS Code settings (``settings.json``), not a home-directory file.
-#   Ref: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
+# * Copilot CLI -- ``~/.copilot/agents/`` is the documented user-level
+#   directory for custom agents.  Agents placed here are available
+#   across all repositories.
+#   Ref: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
+#
+# * VS Code -- supports user-level MCP server configuration through
+#   VS Code user settings.json.  ``.github/`` is workspace-scoped only.
+#   Ref: https://code.visualstudio.com/docs/configure/settings
 #
 # * Cursor -- user-level rules are configured via the Cursor Settings
 #   UI (Settings > Rules for AI).  The ``.cursor/rules/`` directory is
@@ -145,12 +152,19 @@ def ensure_user_dirs() -> Path:
         "description": "User-level Claude commands, agents, and settings",
         "reference": "https://docs.anthropic.com/en/docs/claude-code/settings",
     },
-    "copilot": {
-        "supported": False,
-        "user_root": "~/.github",
-        "primitives": [],
-        "description": "Not supported -- VS Code reads .github/ from workspace only",
-        "reference": "https://code.visualstudio.com/docs/copilot/customization/custom-instructions",
+    "copilot_cli": {
+        "supported": True,
+        "user_root": "~/.copilot",
+        "primitives": ["agents"],
+        "description": "User-level custom agents for Copilot CLI",
+        "reference": "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli",
+    },
+    "vscode": {
+        "supported": True,
+        "user_root": "~/settings.json",
+        "primitives": ["mcp_servers"],
+        "description": "MCP servers only (via VS Code user settings.json)",
+        "reference": "https://code.visualstudio.com/docs/configure/settings",
     },
     "cursor": {
         "supported": False,
@@ -187,6 +201,6 @@ def warn_unsupported_user_scope() -> str:
         return ""
     names = ", ".join(unsupported)
     return (
-        f"[!] User-scope primitives are only read by Claude Code. "
+        f"[!] Some targets do not support user-scope primitives. "
         f"Targets without native user-level support: {names}"
     )

tests/integration/test_global_scope_e2e.py

@@ -161,8 +161,8 @@ def test_warns_about_unsupported_targets(self, apm_command, fake_home):
         """Install --global should warn about targets that lack user-scope support."""
         result = _run_apm(apm_command, ["install", "--global"], fake_home, fake_home)
         combined = result.stdout + result.stderr
-        assert "copilot" in combined.lower(), (
-            f"Missing copilot warning in output: {combined}"
+        assert "cursor" in combined.lower(), (
+            f"Missing cursor warning in output: {combined}"
         )
 
     def test_uninstall_global_shows_scope_info(self, apm_command, fake_home):

tests/unit/core/test_scope.py

@@ -158,7 +158,7 @@ class TestUserScopeTargets:
     """Validate the target support registry."""
 
     def test_all_known_targets_present(self):
-        expected = {"copilot", "claude", "cursor", "opencode"}
+        expected = {"copilot_cli", "vscode", "claude", "cursor", "opencode"}
         assert set(USER_SCOPE_TARGETS.keys()) == expected
 
     def test_each_target_has_required_keys(self):
@@ -178,8 +178,17 @@ def test_user_roots_start_with_tilde(self):
     def test_claude_is_supported(self):
         assert USER_SCOPE_TARGETS["claude"]["supported"] is True
 
-    def test_copilot_is_not_supported(self):
-        assert USER_SCOPE_TARGETS["copilot"]["supported"] is False
+    def test_copilot_cli_is_supported(self):
+        assert USER_SCOPE_TARGETS["copilot_cli"]["supported"] is True
+
+    def test_copilot_cli_supports_agents(self):
+        assert "agents" in USER_SCOPE_TARGETS["copilot_cli"]["primitives"]
+
+    def test_vscode_is_supported(self):
+        assert USER_SCOPE_TARGETS["vscode"]["supported"] is True
+
+    def test_vscode_supports_mcp_servers(self):
+        assert "mcp_servers" in USER_SCOPE_TARGETS["vscode"]["primitives"]
 
     def test_cursor_is_not_supported(self):
         assert USER_SCOPE_TARGETS["cursor"]["supported"] is False
@@ -208,14 +217,14 @@ class TestScopeWarnings:
 
     def test_get_unsupported_targets(self):
         unsupported = get_unsupported_targets()
-        assert "copilot" in unsupported
         assert "cursor" in unsupported
         assert "opencode" in unsupported
         assert "claude" not in unsupported
+        assert "copilot_cli" not in unsupported
+        assert "vscode" not in unsupported
 
     def test_warn_message_includes_unsupported_names(self):
         msg = warn_unsupported_user_scope()
         assert msg  # non-empty
-        assert "copilot" in msg
         assert "cursor" in msg
-        assert "Claude Code" in msg
+        assert "opencode" in msg

tests/unit/test_install_command.py

@@ -638,7 +638,7 @@ def test_global_flag_shows_scope_info(self):
                 assert result.exit_code == 1
                 assert "user scope" in result.output.lower() or "~/.apm/" in result.output
                 # Should warn about unsupported targets
-                assert "copilot" in result.output.lower()
+                assert "cursor" in result.output.lower()
             finally:
                 os.chdir(self.original_dir)
 
@@ -656,7 +656,7 @@ def test_global_short_flag_g(self):
                 assert (fake_home / ".apm" / "apm_modules").is_dir()
                 assert "user scope" in result.output.lower() or "~/.apm/" in result.output
                 # Should warn about unsupported targets
-                assert "copilot" in result.output.lower()
+                assert "cursor" in result.output.lower()
             finally:
                 os.chdir(self.original_dir)