From 51cb7ca36c97fbf2c60c9caf31decfd4b3473e2c Mon Sep 17 00:00:00 2001
From: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com>
Date: Sat, 23 May 2026 08:00:28 +0200
Subject: [PATCH] docs: update copilot detection signals and MCP per-dep
 registry

- targets-matrix.md, targets.md: document the expanded Copilot harness
  auto-detection signals added in #1440. The copilot target is now
  activated by .github/instructions/, .github/agents/, .github/prompts/,
  or .github/hooks/ directories in addition to the monolithic
  .github/copilot-instructions.md file.

- install-mcp-servers.md: document that the registry: URL field on
  individual MCP dependency entries is now honored during install (#1443).
  Previously stored but ignored (emitting a 'not yet applied' warning).
  Added example showing the per-dep custom registry form and the
  equivalent --registry CLI flag.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/consumer/install-mcp-servers.md      | 19 +++++++++++++++++--
 .../src/content/docs/reference/cli/targets.md |  6 +++++-
 .../content/docs/reference/targets-matrix.md  |  4 ++--
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/docs/src/content/docs/consumer/install-mcp-servers.md b/docs/src/content/docs/consumer/install-mcp-servers.md
index 6839109d2..19b7a9c47 100644
--- a/docs/src/content/docs/consumer/install-mcp-servers.md
+++ b/docs/src/content/docs/consumer/install-mcp-servers.md
@@ -29,14 +29,18 @@ dependencies:
     # 1. Registry reference (bare string)
     - io.github.github/github-mcp-server
 
-    # 2. Self-defined stdio (local process)
+    # 2. Registry reference with a per-dep custom registry URL
+    - name: my-internal-server
+      registry: https://registry.internal.example.com
+
+    # 3. Self-defined stdio (local process)
     - name: filesystem
       registry: false
       transport: stdio
       command: npx
       args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
 
-    # 3. Self-defined remote (HTTP / SSE)
+    # 4. Self-defined remote (HTTP / SSE)
     - name: linear
       registry: false
       transport: http
@@ -45,6 +49,17 @@ dependencies:
         Authorization: "Bearer ${LINEAR_TOKEN}"
 ```
 
+When `registry:` is a string URL (form 2 above), APM routes that entry through
+the specified registry instead of the global default (`https://api.mcp.github.com`).
+Each dependency can point to a different registry; APM groups them and installs
+each group via its own registry client. The `registry:` URL is persisted to
+`apm.yml` and honored on every subsequent `apm install`. You can also set the
+custom URL from the CLI with `--registry URL` when first adding the entry:
+
+```bash
+apm install --mcp my-internal-server --registry https://registry.internal.example.com
+```
+
 The full grammar (overlays, `${input:...}` variables, `tools:`
 allowlists, `package:` selection) is in
 [Package Anatomy](../../concepts/package-anatomy/).
diff --git a/docs/src/content/docs/reference/cli/targets.md b/docs/src/content/docs/reference/cli/targets.md
index 5ce1bc0d0..c4ef30c10 100644
--- a/docs/src/content/docs/reference/cli/targets.md
+++ b/docs/src/content/docs/reference/cli/targets.md
@@ -92,7 +92,7 @@ match per target is enough to activate it.
 | Target | Signal(s) APM looks for | Deploy directory |
 |--------|-------------------------|------------------|
 | `claude` | `.claude/` directory, or `CLAUDE.md` file | `.claude/` |
-| `copilot` | `.github/copilot-instructions.md` file | `.github/` |
+| `copilot` | `.github/copilot-instructions.md` file (monolithic), or `.github/instructions/`, `.github/agents/`, `.github/prompts/`, `.github/hooks/` directories (file-based layout) | `.github/` |
 | `cursor` | `.cursor/` directory, or `.cursorrules` file (legacy) | `.cursor/` |
 | `codex` | `.codex/` directory | `.codex/` |
 | `gemini` | `.gemini/` directory, or `GEMINI.md` file | `.gemini/` |
@@ -104,6 +104,10 @@ Notes:
 
 - Detection is filesystem-only. APM does not inspect file contents to
   decide whether a marker is "real".
+- Copilot is detected by either the monolithic `.github/copilot-instructions.md`
+  file OR by the presence of any file-based layout directory
+  (`.github/instructions/`, `.github/agents/`, `.github/prompts/`,
+  `.github/hooks/`). Any one of these is sufficient.
 - A `CLAUDE.md` written as documentation will still activate the
   `claude` target. Pin `targets:` in `apm.yml` to override.
 - If no signals are found and `apm.yml` declares no `targets:`,
diff --git a/docs/src/content/docs/reference/targets-matrix.md b/docs/src/content/docs/reference/targets-matrix.md
index 69ad5e33e..49e68e5e4 100644
--- a/docs/src/content/docs/reference/targets-matrix.md
+++ b/docs/src/content/docs/reference/targets-matrix.md
@@ -54,7 +54,7 @@ list before `compile` or `install`.
 | Target   | Signals (any one activates the target)        |
 |----------|-----------------------------------------------|
 | claude   | `.claude/` directory, or `CLAUDE.md` file     |
-| copilot  | `.github/copilot-instructions.md` file        |
+| copilot  | `.github/copilot-instructions.md` file, or `.github/instructions/`, `.github/agents/`, `.github/prompts/`, `.github/hooks/` directories |
 | cursor   | `.cursor/` directory, or `.cursorrules` file  |
 | codex    | `.codex/` directory                           |
 | gemini   | `.gemini/` directory, or `GEMINI.md` file     |
@@ -70,7 +70,7 @@ a project's `apm.yml` `targets:` field so contributors running plain
 
 GitHub Copilot (CLI and IDE).
 
-- **Detection.** `.github/copilot-instructions.md`.
+- **Detection.** `.github/copilot-instructions.md` (monolithic), or any of `.github/instructions/`, `.github/agents/`, `.github/prompts/`, `.github/hooks/` directories (file-based layout).
 - **Deploy directory.** `.github/` at project scope; `~/.copilot/` at user scope.
 - **Supported primitives.** instructions, prompts, agents, skills, hooks, mcp.
 - **File conventions.**