microsoft
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/src/content/docs/enterprise/security.md‎
Lines changed: 10 additions & 1 deletion b/‎docs/src/content/docs/enterprise/security.md‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎docs/src/content/docs/getting-started/first-package.md‎
Lines changed: 1 addition & 0 deletions b/‎docs/src/content/docs/getting-started/first-package.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/src/content/docs/guides/pack-distribute.md‎
Lines changed: 29 additions & 48 deletions b/‎docs/src/content/docs/guides/pack-distribute.md‎
Lines changed: 29 additions & 48 deletions
diff --git a/‎docs/src/content/docs/guides/plugins.md‎
Lines changed: 2 additions & 18 deletions b/‎docs/src/content/docs/guides/plugins.md‎
Lines changed: 2 additions & 18 deletions
@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `apm install` now accepts the YAML list form under `target:` (e.g. `target: [copilot, claude]`); previously crashed with a garbled `Unknown target` error. (#1197)
 - `apm install --update` now falls back from a stale `ADO_APM_PAT` to an `az login` AAD bearer in the preflight auth probe, matching the behavior of `apm install` and every other ADO call site. Previously the preflight raised `AuthenticationError` on 401/403 even when `az login` would have succeeded. The bearer env also pops any pre-existing `GIT_TOKEN` so the JWT flows only via `GIT_CONFIG_VALUE_0`, and the per-host stale-PAT warning dedup is lock-guarded so parallel installs against the same ADO host emit one warning instead of one-per-thread. (#1212)
 - `Unknown target` error suggestions no longer advertise the `agent-skills` meta-target, which `apm targets` intentionally omits from its table. The canonical set still accepts `agent-skills` via `--target` and `apm.yml`, but the recovery path printed on errors now matches what the discovery command actually lists. (#1215)
+- `apm pack` no longer hardcodes `pack.target` into bundles; bundles are target-agnostic and `apm install <bundle>` resolves the consumer target from project context and wires bundle `.mcp.json` servers per target via `MCPIntegrator`. (#1217)
 
 ## [0.12.4] - 2026-05-07
 
 
@@ -190,11 +190,20 @@ APM deploys files only to controlled subdirectories within the project root.
 All deploy paths are validated before any file operation:
 
 1. **No `..` segments.** Any path containing `..` is rejected outright.
-2. **Allowed prefixes only.** Paths must start with an allowed prefix (`.github/`, `.claude/`, `.cursor/`, or `.opencode/`).
+2. **Allowed prefixes only.** Paths must start with an allowed target-integrator prefix (`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.gemini/`, `.windsurf/`, `.agents/`). In addition, the local-bundle install path stages instructions for compile-only targets under `apm_modules/<slug>/.apm/instructions/` with its own containment check (the resolved path must remain within `apm_modules/`) and `<slug>` validation rejecting traversal sequences and characters outside `[A-Za-z0-9._-]`.
 3. **Resolution containment.** The fully resolved path must remain within the project root directory.
 
 A path must pass all three checks. Failure on any check prevents the file from being written.
 
+### Local bundle install trust model
+
+`apm install <bundle>` accepts a directory or `.tar.gz` produced by `apm pack`. Bundles are imperative (no policy / dependency-resolver / network) and target-agnostic; the consumer's project drives where files land. Trust boundaries:
+
+1. **`bundle_files` keys are untrusted.** They come from the bundle's own `apm.lock.yaml` and are validated for traversal sequences before any filesystem path is constructed; resolved destinations must remain within the deploy root. Unsafe entries are skipped with a warning.
+2. **`plugin.json` is bundle metadata, never deployed.** It is recognized case-insensitively and skipped in both the manifest-driven deploy loop and the lockfile-less fallback walk so case-folding filesystems (HFS+, NTFS) cannot smuggle a renamed file past the skip.
+3. **`.mcp.json` is bundle metadata, never deployed verbatim.** It is recognized case-insensitively and skipped from the deploy loop. After files deploy, `apm install` parses the bundle's `.mcp.json` (Anthropic plugin schema, `mcpServers` map) and routes each entry through `MCPIntegrator.install` as a self-defined dependency, so the consumer's resolved target(s) get the servers in their own native MCP config (Claude `.mcp.json`, Copilot `~/.copilot/mcp-config.json`, VS Code `.vscode/mcp.json`, Cursor `.cursor/mcp.json`, etc.). `MCPIntegrator` enforces the same validation and runtime gating used by `apm.yml`-declared servers; per-server parse errors are isolated and do not block the rest of the install.
+4. **Slug validation.** The bundle's `id` (used as `<slug>` for staged instructions and the install label) is rejected if it contains traversal sequences or characters outside `[A-Za-z0-9._-]`.
+
 ### Symlink handling
 
 Symlinks are never followed during file discovery or artifact operations:
 
@@ -272,6 +272,7 @@ Output (plugin format is the default):
 ```
 build/team-skills-1.0.0/
 +-- plugin.json        # synthesized, schema-conformant per https://json.schemastore.org/claude-code-plugin.json
++-- apm.lock.yaml      # enriched copy with bundle_files manifest (used by `apm install <bundle>` for integrity)
 +-- agents/
 |   +-- team-reviewer.agent.md
 +-- skills/
 
@@ -36,15 +36,9 @@ The left side (install, pack) runs where APM is available. The right side (downl
 Creates a self-contained bundle from installed dependencies. Reads the `deployed_files` manifest in `apm.lock.yaml` as the source of truth -- it does not scan the disk.
 
 ```bash
-# Default: Claude Code plugin directory, target auto-detected
+# Default: target-agnostic plugin bundle that installs into any consumer
 apm pack
 
-# Filter by target
-apm pack --target copilot         # only .github/ files
-apm pack --target claude          # only .claude/ files
-apm pack --target all             # all targets
-apm pack -t claude,copilot        # multiple targets (comma-separated)
-
 # Legacy APM bundle layout (consumed by microsoft/apm-action restore)
 apm pack --format apm
 
@@ -63,61 +57,42 @@ apm pack --dry-run
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--format` | `plugin` | Bundle format. `plugin` emits a Claude Code plugin directory with `plugin.json`. `apm` emits the legacy APM bundle layout. |
-| `-t, --target` | auto-detect | File filter: `copilot`, `claude`, `cursor`, `opencode`, `all`. `vscode` is a deprecated alias for `copilot`. |
+| `-t, --target` | (deprecated) | Deprecated. Emits a warning; the value is recorded in `pack.target` as diagnostic metadata only and is ignored by `apm install` target resolution. Bundles are target-agnostic; the consumer's project decides where files land at install time. |
 | `--archive` | off | Produce `.tar.gz` instead of directory |
 | `-o, --output` | `./build` | Output directory |
 | `--dry-run` | off | List files without writing |
 | `--force` | off | On collision (plugin format), last writer wins |
 
-### Target filtering
-
-The target flag controls which deployed files are included based on path prefix:
-
-| Target | Includes |
-|--------|----------|
-| `copilot` | Paths starting with `.github/` |
-| `vscode` | Deprecated alias for `copilot` |
-| `claude` | Paths starting with `.claude/` |
-| `cursor` | Paths starting with `.cursor/` |
-| `opencode` | Paths starting with `.opencode/` |
-| `all` | `.github/`, `.claude/`, `.cursor/`, and `.opencode/` |
-
-When no target is specified, APM auto-detects from the `target` field in `apm.yml`, falling back to `all`.
-
-### Cross-target path mapping
+### Plugin layout normalization
 
-Skills and agents are semantically identical across targets -- `.github/skills/X` and `.claude/skills/X` contain the same content. When the lockfile records files under a different target prefix than the one you are packing for, APM automatically remaps `skills/` and `agents/` paths:
+`apm pack` (default `--format plugin`) emits an Anthropic plugin directory regardless of which targets installed the source files. Skills and agents are semantically identical across targets, so APM normalizes paths into the plugin convention:
 
 ```
-apm pack --target claude
-# .github/skills/my-plugin/SKILL.md  ->  .claude/skills/my-plugin/SKILL.md
-# .github/agents/helper.md           ->  .claude/agents/helper.md
+.github/skills/my-plugin/SKILL.md  ->  skills/my-plugin/SKILL.md
+.claude/agents/helper.md           ->  agents/helper.md
 ```
 
-Only `skills/` and `agents/` are remapped. Commands, instructions, and hooks are target-specific and are never mapped.
-
-The enriched lockfile inside the bundle uses the remapped paths, so the bundle is self-consistent. When mapping occurs, the `pack:` section includes a `mapped_from` field listing the original prefixes.
+Commands, instructions, and hooks are also rehomed under the plugin's top-level convention dirs. The bundle is self-consistent and target-agnostic; the consumer's project drives where files land at install time.
 
 ### Targeting mental model
 
-**Choose your target when you pack. Unpack delivers exactly what was packed.**
+**Bundles are target-agnostic. The consumer's project decides where the files land.**
+
+A bundle ships in Anthropic plugin layout (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`) as a transport convention -- not a target binding. When a consumer runs `apm install <bundle>`, APM resolves the consumer's target from their project context (same precedence as registry installs: `--target` flag, then `apm.yml`, then directory detection) and routes the bundle's primitives through the integrators for that target.
 
-A bundle is a deployable snapshot, not a retargetable source artifact. Target selection happens at pack time because that is when the full context is available -- which file types are remappable (skills, agents) and which are target-specific (commands, instructions, hooks).
+Concretely: the same `team-skills.tgz` installed into a Copilot project lands under `.github/`; installed into a Claude project, lands under `.claude/`; installed into an OpenCode project, lands under `.opencode/` with instructions staged for `apm compile`.
 
-`apm unpack` does not remap paths. If the bundle was packed for Claude, the files land under `.claude/`. If you need a different target, re-pack from source with the desired `--target` flag, or use `--target all` to include all platforms.
+`--target` on `apm pack` is **deprecated**. The field is informational and never overrides consumer-side target resolution; an advisory warning may still print at install time if the bundle's recorded `pack.target` differs from the resolved install target.
 
-When unpacking, APM reads the bundle's `pack:` metadata and shows the target it was packed for. If the bundle target does not match the project's detected target, a warning is displayed:
+Compile-only targets (OpenCode, Codex, Gemini) receive instructions under `apm_modules/<slug>/.apm/instructions/` so [`apm compile`](../../guides/compilation/) merges them into `AGENTS.md` / `GEMINI.md` on the next compile.
 
 ```
-$ apm unpack team-skills.tar.gz
-[*] Unpacking team-skills.tar.gz -> .
-[i] Bundle target: claude (1 dep(s), 3 file(s))
-[!] Bundle target 'claude' differs from project target 'copilot'
-[+] Unpacked 3 file(s) (verified)
+$ apm install team-skills.tgz
+[>] Installing local bundle from team-skills.tgz
+[*] Installed 3 file(s) from local bundle
+[!] Bundle staged 1 instruction(s) for compile (target: opencode). Run 'apm compile' to merge them into AGENTS.md / GEMINI.md / equivalent.
 ```
 
-This is informational -- the files still extract. The warning helps users understand why their tool may not see the unpacked files and suggests the correct workflow.
-
 ## Plugin format vs APM format
 
 `apm pack` produces one of two output shapes. The default is the plugin format.
@@ -126,7 +101,7 @@ This is informational -- the files still extract. The warning helps users unders
 |---|---|---|
 | Output layout | Claude Code plugin directory with `plugin.json` at the root and convention dirs (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`) | Mirrors `apm install` deploy paths (`.github/`, `.claude/`, `.cursor/`, `.opencode/`) plus an enriched `apm.lock.yaml` |
 | `plugin.json` | Synthesized (or updated from existing) and validates against the [official Claude Code plugin manifest schema](https://json.schemastore.org/claude-code-plugin.json) | Not emitted |
-| `apm.lock.yaml` inside output | Not emitted (no APM-specific files) | Enriched copy with a `pack:` metadata section |
+| `apm.lock.yaml` inside output | Enriched copy with a `pack:` metadata section (when the project has a lockfile) | Enriched copy with a `pack:` metadata section |
 | Drop-in for | Any Claude Code plugin consumer (Copilot CLI, Claude Code, Cursor, ...) | `microsoft/apm-action`'s restore mode and bundle-aware tooling |
 | `devDependencies` | Excluded | Included (full install layout) |
 
@@ -279,15 +254,17 @@ build/my-project-1.0.0/
 
 The bundle is self-describing: its `apm.lock.yaml` lists every file it contains and the dependency graph that produced them.
 
-## Lockfile enrichment (APM format only)
+## Lockfile enrichment
 
-When `--format apm` is used, the bundle includes a copy of `apm.lock.yaml` enriched with a `pack:` section. The project's own `apm.lock.yaml` is never modified.
+Both formats embed an enriched `apm.lock.yaml` in the bundle when the project has a lockfile. The project's own `apm.lock.yaml` is never modified; the embedded copy carries an additional `pack:` section so consumers verify integrity at install time without re-running the upstream pack.
 
 ```yaml
 pack:
   format: apm
-  target: copilot
   packed_at: '2025-07-14T09:30:00+00:00'
+  bundle_files:
+    .github/prompts/design-review.prompt.md: a1b2c3...
+    .github/agents/architect.md: d4e5f6...
 lockfile_version: '1'
 generated_at: '2025-07-14T09:28:00+00:00'
 apm_version: '0.5.0'
@@ -304,10 +281,14 @@ dependencies:
       - .github/agents/architect.md
 ```
 
-The `pack:` section records the bundle `format`, the effective `target` filter, and a `packed_at` UTC timestamp. Plugin-format output has no `apm.lock.yaml` -- consumers verify by re-running the upstream pack instead.
+The `pack:` section records the bundle `format`, the per-file `bundle_files` SHA-256 manifest, and a `packed_at` UTC timestamp.
 
 ## `apm unpack`
 
+:::note
+For APM consumers, prefer `apm install <bundle>` over `apm unpack`. `apm install` deploys both formats target-agnostically, persists provenance to the project lockfile (`local_deployed_files`), and works with directory or `.tar.gz` inputs. `apm unpack` is retained for the legacy APM-format restore-without-APM workflow consumed by `microsoft/apm-action@v1`.
+:::
+
 Extracts an APM bundle (produced with `--format apm`) into a project directory. Accepts both `.tar.gz` archives and unpacked bundle directories. Plugin-format output is consumed directly by Claude Code and other plugin hosts and does not need `apm unpack`.
 
 ```bash
@@ -462,4 +443,4 @@ During unpack, verification found files listed in the bundle's lockfile that are
 If `apm pack` produces zero files, check:
 
 1. Your dependencies have `deployed_files` entries in `apm.lock.yaml`. This can happen if `apm install` completed but no integration files were deployed (e.g., the package has no prompts or agents for the active target).
-2. The `--target` filter matches where files were deployed. For example, if files are under `.github/` but you pack with `--target claude`, APM will remap `skills/` and `agents/` automatically. If no remappable files exist, the bundle will be empty. Try `--target all` or check `apm.lock.yaml` to see which prefixes your files use.
+2. The bundle is built from the `deployed_files` in `apm.lock.yaml` directly. Cross-target remapping for the convention dirs (`skills/`, `agents/`, `commands/`, `instructions/`, `hooks/`) runs automatically. If `apm.lock.yaml` shows zero deployed files, run `apm install` first; if files exist there but the bundle is empty, file an issue.
@@ -8,23 +8,7 @@ APM treats plugins and packages as the same artifact. Every APM package is plugi
 
 ## Plugin authoring
 
-The only authoring decision is whether you also keep an `apm.yml`:
-
-- **With `apm.yml` (recommended).** You get dependency management, lockfile pinning, [security scanning](../../enterprise/security/), [`devDependencies`](../../reference/manifest-schema/#5-devdependencies), and multi-runtime deploy during development. `apm pack` still emits a plugin-compatible bundle for non-APM consumers. This is what `apm init --plugin` produces.
-- **From an existing `plugin.json`.** APM consumes it natively - `apm install owner/repo` works against any plugin repo without migration. Metadata is synthesized from `plugin.json`. Add an `apm.yml` later if you want APM tooling during development.
-
-For why `apm.yml` adds value on top of `plugin.json`, see [Anatomy -- Why not just ship a `plugin.json`?](../../introduction/anatomy-of-an-apm-package/#why-not-just-ship-a-pluginjson).
-
-### Authoring workflow
-
-```bash
-apm init my-plugin --plugin    # apm.yml + plugin.json
-apm install --dev owner/helpers # dev-only dependency (excluded from pack)
-apm install owner/core-rules   # production dependency
-apm pack                       # plugin-compatible bundle by default
-```
-
-The packed directory contains no APM-specific files. See [Pack & Distribute -- Plugin format](../../guides/pack-distribute/#plugin-format-vs-apm-format) for the output mapping and [Without APM: what you give up](../../guides/pack-distribute/#without-apm-what-you-give-up) for the consumer-side trade-off.
+For the authoring flow (`apm init --plugin`, dev/prod dependency split, `apm pack` output mapping, hybrid mode with `apm.yml` + `plugin.json`), see [Pack & Distribute](../../guides/pack-distribute/) and the [first package walkthrough](../../getting-started/first-package/#6-ship-as-a-plugin-optional). For why APM still adds value when you already have a `plugin.json`, see [Anatomy -- Why not just ship a `plugin.json`?](../../introduction/anatomy-of-an-apm-package/#why-not-just-ship-a-pluginjson).
 
 ## Overview
 
@@ -353,7 +337,7 @@ This:
 
 ## Exporting APM packages as plugins
 
-Use the [authoring workflow](#authoring-workflow) to develop plugins with APM's full tooling and export them as standalone plugin directories. See [Pack & Distribute -- Plugin format](../../guides/pack-distribute/#plugin-format-vs-apm-format) for the output mapping and structure.
+Use the [authoring workflow](#plugin-authoring) to develop plugins with APM's full tooling and export them as standalone plugin directories. See [Pack & Distribute -- Plugin format](../../guides/pack-distribute/#plugin-format-vs-apm-format) for the output mapping and structure.
 
 ## Finding Plugins