diff --git a/.agents/skills/docs-impact-architect/SKILL.md b/.agents/skills/docs-impact-architect/SKILL.md
new file mode 100644
index 000000000..2bc2c9970
--- /dev/null
+++ b/.agents/skills/docs-impact-architect/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: docs-impact-architect
+description: >-
+  Use this skill when the docs-impact-classifier returns a structural
+  verdict, signalling that the documentation TOC must change to
+  accommodate the PR. Proposes TOC deltas (new pages, moves,
+  merges) and emits new-page outline stubs that the doc-sync panel
+  later fleshes out. Holds the 3-promise narrative (consume /
+  produce / govern) and the persona ramps as hard constraints.
+---
+
+# docs-impact-architect
+
+Single responsibility: when the classifier says a PR needs
+structural docs changes (new page, page move, TOC reshape), design
+the change and emit:
+
+1. A precise TOC delta (added pages, moved pages, retired pages)
+2. New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
+3. The persona-ramp impact (which ramp gains/loses a stop)
+
+You are NOT the writer (doc-writer owns prose). You are the **TOC
+architect**. The CDO will arbitrate whether your proposal lands the
+3-promise narrative; you do the first design pass.
+
+## When to invoke
+
+The docs-sync orchestrator invokes you ONLY when the classifier
+returned `verdict: structural`. For `no_change` or `in_place` you
+don't run.
+
+## Inputs
+
+- `structural_proposal` from the classifier (a sketch you refine)
+- The PR diff (`gh pr diff $PR`)
+- `.apm/docs-index.yml` (full corpus map)
+- The PR description (for author-stated intent)
+
+## Step 1: read the corpus map, not the corpus
+
+Load `.apm/docs-index.yml` entirely. Inspect `chapters[]`, `pages[]`,
+`promises[]`. This is your map. You do NOT read the 100+ page corpus
+unless a specific page is implicated by the classifier's sketch.
+
+## Step 2: classify the structural shape
+
+Match the PR's surface change to one of these structural shapes:
+
+| Shape | Pattern | Example |
+|---|---|---|
+| **NEW CAPABILITY** | A new CLI verb, primitive type, or schema concept the docs have no slot for | `apm pack --format wheel` adds a new package format |
+| **EXPANDED CAPABILITY** | An existing concept grows in scope and the current page can't hold it | `apm install` gains a registry-proxy mode that needs its own sub-page |
+| **DEPRECATED CAPABILITY** | A removed CLI verb, flag, or concept; existing pages need to be retired or rewritten | A flag is removed; tutorial pages still teach it |
+| **CONCEPT SPLIT** | One concept becomes two distinct concepts; one page becomes two | `apm audit` splits into `audit` and `audit ci` |
+| **CONCEPT MERGE** | Two concepts unify; two pages should become one | `apm pack` and `apm bundle` merge into one verb |
+| **RAMP REORG** | The PR's surface change shifts a concept across promises (e.g. an enterprise feature becomes consumer-default) | Policy enforcement moves from enterprise to consumer default behaviour |
+
+The structural shape drives the TOC delta shape.
+
+## Step 3: design the TOC delta
+
+For each new page proposed, fill in:
+
+```yaml
+new_page:
+  slug: docs/src/content/docs/<persona>/<topic>.md
+  title: "<short imperative title>"
+  persona: consumer | producer | enterprise | cross
+  promise: 1 | 2 | 3 | cross
+  parent_chapter: <existing chapter slug>
+  h2_sections:
+    - "## Why <topic>"        # OPTIONAL -- skip unless concept is genuinely new
+    - "## How to <use>"        # REQUIRED -- code first
+    - "## Reference"           # OPTIONAL -- flag/option table
+    - "## Troubleshooting"     # OPTIONAL -- only if known footguns
+  bridges:
+    incoming:                  # which existing pages should link TO this
+      - {from: <slug>, link_text: <suggested>}
+    outgoing:                  # which existing pages should this link FROM
+      - {to: <slug>, link_text: <suggested>}
+  ramp_impact: >-
+    one-paragraph description of how this changes the <persona>
+    ramp: which step it slots into, whether it adds a stop or
+    replaces an existing one
+```
+
+For each moved/retired page:
+
+```yaml
+moved_page:
+  from: <slug>
+  to: <slug>
+  redirect_rationale: <one-sentence>
+
+retired_page:
+  slug: <slug>
+  reason: <one-sentence>
+  redirect_to: <slug>  # MUST exist; orphaning pages breaks SEO
+```
+
+## Step 4: validate against the 3-promise narrative
+
+Apply these hard rules. If any fails, redesign:
+
+1. **Every page belongs to exactly one promise.** Cross-cutting pages (integrations, troubleshooting, reference) are explicitly marked `promise: cross`. If a new page straddles two promises, split it OR park it under `cross`.
+2. **Consumer pages don't pre-teach producer concepts.** A consumer page may LINK to producer; it may not embed producer prose.
+3. **Producer pages don't pre-teach enterprise concepts.** Same rule, one promise down.
+4. **No page is orphaned from the TOC.** Every new page has a `parent_chapter` and at least one `incoming` bridge.
+5. **No retired page lacks a `redirect_to`.** Search engines will index the old URL for months; the redirect is the SEO contract.
+
+## Step 5: emit the architect report
+
+Return JSON:
+
+```json
+{
+  "structural_shape": "NEW CAPABILITY" | "EXPANDED CAPABILITY" | "DEPRECATED CAPABILITY" | "CONCEPT SPLIT" | "CONCEPT MERGE" | "RAMP REORG",
+  "toc_delta": {
+    "new_pages": [...],
+    "moved_pages": [...],
+    "retired_pages": [...],
+    "chapter_changes": [...]
+  },
+  "promise_validation": {
+    "all_pages_single_promise": true | false,
+    "no_orphans": true | false,
+    "no_unredirected_retires": true | false,
+    "concerns": []
+  },
+  "downstream_in_place_pages": ["..."],
+  "rationale": "<2-3 sentence summary of why this structural delta and not alternatives>"
+}
+```
+
+`downstream_in_place_pages[]` is the handoff to the localizer -- after
+the architect approves the TOC, the localizer plans in-place edits
+to existing pages that REFERENCE the new structure.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 5 as the
+final message of your task. No prose around the JSON.
+
+## Anti-patterns
+
+- Inflating new-page counts to seem thorough. The minimal true delta wins.
+- Skipping the promise-validation step. The CDO will catch it; better to self-catch.
+- Designing a new chapter when an existing chapter has room. Always prefer extending over creating.
+- Forgetting `redirect_to` on retired pages. SEO debt is the silent corpus killer.
diff --git a/.agents/skills/docs-impact-classifier/SKILL.md b/.agents/skills/docs-impact-classifier/SKILL.md
new file mode 100644
index 000000000..70a1f2f14
--- /dev/null
+++ b/.agents/skills/docs-impact-classifier/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: docs-impact-classifier
+description: >-
+  Use this skill to classify the documentation impact of a pull
+  request diff, returning one of three verdicts -- no-change,
+  in-place edit, or structural change -- with bounded LLM cost.
+  Activate as a sibling skill of docs-sync; the orchestrator calls
+  this first, before any panel spawn, to keep cost floor at 1 LLM
+  call when no docs work is needed. Reads .apm/docs-index.yml as
+  the corpus map; never reads the full corpus.
+---
+
+# docs-impact-classifier
+
+Single responsibility: given a PR diff and the `.apm/docs-index.yml`
+corpus map, emit ONE classification verdict.
+
+This skill is the cost gate for the entire docs-sync system. ~70% of
+PRs should exit at verdict `no_change` with zero panel spawn.
+
+## Architecture
+
+This is a 3-layer funnel inside a single skill invocation:
+
+- **L0 deterministic path gate** -- pure file-path matching, no LLM.
+- **L1 symbol extraction + corpus grep** -- pure text processing, no LLM.
+- **L2 LLM classifier** -- bounded ~8 KB context envelope, 1 call.
+
+The skill returns the verdict from the earliest layer that can decide.
+
+## Step 1: L0 deterministic path gate (no LLM)
+
+Read `.apm/docs-index.yml` to load `no_impact_paths[]` and
+`user_surface_paths[]`. Get the changed file list from the PR diff
+(`gh pr diff --name-only`).
+
+```
+if every changed file matches no_impact_paths AND none match user_surface_paths:
+    return {verdict: "no_change", confidence: "high", source: "L0", scope_pages: []}
+```
+
+This handles:
+- Test-only PRs (`tests/**`)
+- CI workflow PRs (`.github/workflows/**`)
+- Doc-only PRs (`docs/**`) -- out of scope, docs-sync doesn't review docs PRs
+- Primitive-only PRs (`.apm/**`)
+- Script and meta PRs
+
+Expected hit rate: ~70% of PRs short-circuit here.
+
+## Step 2: L1 symbol extraction + corpus grep (no LLM)
+
+If L0 did not exit, extract user-observable symbols from the diff:
+
+- **CLI command names** -- grep diff for `^@click.command`, `^@cli.command`, or any `apm <verb>` mention in added/removed lines.
+- **Flag names** -- grep diff for `^@click.option`, `--[a-z-]+` patterns.
+- **Public API symbols** -- added/removed `def <name>` in `src/apm_cli/__init__.py` or `src/apm_cli/api/**`.
+- **Schema keys** -- added/removed keys in `apm.yml`, `apm.lock.yaml`, `apm-policy.yml` parsers.
+- **Error strings** -- added/removed string literals in user-facing error paths (look for `_rich_error`, `click.echo`, `raise ... Error(`).
+
+For each extracted symbol, consult `.apm/docs-index.yml#symbol_index`
+to find the documented pages. Collect all hits into `candidate_pages[]`.
+
+Also `grep -rn <symbol> docs/src/content/docs/` for symbols NOT in
+the index (catches drift between index and corpus).
+
+## Step 3: L2 LLM verdict (1 call, bounded context)
+
+If L1 found zero candidate pages AND zero schema/CLI/flag changes:
+return `{verdict: "no_change", confidence: "medium", source: "L1", scope_pages: []}`.
+
+Otherwise, invoke the doc-analyser persona with EXACTLY this context
+envelope (must fit in ~8 KB tokens):
+
+- PR title + body (first 500 chars)
+- Diff stats (`gh pr diff --stat` output)
+- `.apm/docs-index.yml` (the whole file; it's ~8 KB seeded, may grow)
+- L1 candidate pages with +/-5 lines of context per hit
+- Path-classification summary from L0
+- **`pr_doc_diff_paths[]`**: the list of paths under `docs/src/content/docs/**`
+  that the PR itself already modifies (drives the `in_place_resolved`
+  downgrade rule in "In-place-resolved detection" below).
+
+Ask doc-analyser to return JSON matching this schema:
+
+```json
+{
+  "verdict": "no_change" | "in_place_resolved" | "in_place" | "structural",
+  "confidence": "low" | "medium" | "high",
+  "scope_pages": ["docs/src/content/docs/..."],
+  "structural_proposal": {
+    "new_pages": [{"slug": "...", "rationale": "..."}],
+    "moved_pages": [{"from": "...", "to": "..."}],
+    "toc_changes": "<one-paragraph>"
+  },
+  "reasoning": "<one-paragraph: what surface changed, what docs are affected, why this verdict>"
+}
+```
+
+`structural_proposal` is populated only when verdict is `structural`.
+`scope_pages` is populated for `in_place` and `structural` verdicts.
+
+## Verdict semantics
+
+| Verdict | Meaning | Panel size | Cost |
+|---|---|---|---|
+| `no_change` | No user-observable surface changed | 0 panel spawns | ~0-1 LLM call |
+| `in_place_resolved` | Doc impact existed, but the PR's OWN diff already patches every page in `scope_pages` -- author already did the work | 0 panel spawns; skill emits NO advisory | ~1 LLM call |
+| `in_place` | One to a few pages need a paragraph or section update; no new pages, no TOC change | N candidate pages x (doc-writer + python-architect) + editorial-owner + growth-hacker + CDO | ~6-12 LLM calls |
+| `structural` | A new page is needed, OR an existing page should be split/merged, OR the TOC needs to change to fit a new concept | architect first (TOC delta), then in-place panel for affected pages | ~10-15 LLM calls |
+
+## In-place-resolved detection (false-alarm killer)
+
+BEFORE returning `in_place`, intersect your `scope_pages[]` with the
+list of files the PR itself touches under `docs/**` (provided to you
+by the orchestrator under `pr_doc_diff_paths[]`). If EVERY scope page
+already appears in `pr_doc_diff_paths`, downgrade to `in_place_resolved`
+and emit `reasoning` of the form "Author already patched <page list>".
+This is the well-behaved-author path; the skill stays silent.
+
+If only SOME scope pages are pre-patched, keep `in_place` and list the
+REMAINING (unpatched) pages in `scope_pages[]`. Note the pre-patched
+ones in `reasoning` for transparency.
+
+## Rename / breaking-change heuristic (PR 1244 class)
+
+When the L1 layer reports an ADDED public symbol that matches an
+EXISTING public symbol's name in the corpus (e.g. PR adds `apm update`
+but `apm update` already appears in 9 docs pages with different
+semantics), this is a RENAME or BREAKING SEMANTIC CHANGE. Bias toward
+`structural` (not `in_place`):
+- the existing page describing the OLD semantics may need to SPLIT
+  into two pages (old verb under new name + new verb keeping old name)
+- the TOC may need a NEW reference page for the renamed verb
+- every passing mention in the corpus needs verification
+
+Do NOT collapse a rename into `in_place` just because the affected
+pages already exist. The shape of the work is structural even when no
+new page is strictly required.
+
+## Anti-patterns (verdict shape errors)
+
+- Returning `in_place` with empty `scope_pages` -- invalid; orchestrator will reject.
+- Returning `structural` without `structural_proposal` -- invalid.
+- Returning `in_place` when EVERY scope page is in `pr_doc_diff_paths` -- should be `in_place_resolved`.
+- Inflating `structural` to seem thorough -- the CDO will catch this. Return the minimal true verdict.
+- Missing the rename heuristic above and emitting `in_place` for a verb-swap PR.
+- Reading the corpus (the .md files themselves) at L2 -- context budget breach. You read the index, not the corpus.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 3 as the
+final message of your task. No prose around the JSON. The
+orchestrator parses your last message.
diff --git a/.agents/skills/docs-impact-localizer/SKILL.md b/.agents/skills/docs-impact-localizer/SKILL.md
new file mode 100644
index 000000000..61e2ba2d7
--- /dev/null
+++ b/.agents/skills/docs-impact-localizer/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: docs-impact-localizer
+description: >-
+  Use this skill to translate a classifier's in-place verdict into a
+  precise, page-by-page work plan for the docs-sync panel. Activate
+  after docs-impact-classifier returns verdict in_place; reads the
+  candidate page list, fetches the actual page contents, narrows
+  scope to specific sections within each page, and emits the
+  per-page task brief the panel fans out against.
+---
+
+# docs-impact-localizer
+
+Single responsibility: given a list of candidate pages from the
+classifier, produce a per-page task brief the docs-sync panel can
+fan out against.
+
+You are NOT the verdict-maker (classifier owns that). You are NOT
+the writer (doc-writer owns that). You are the **work planner**.
+
+## When to invoke
+
+The docs-sync orchestrator invokes you ONLY when the classifier
+returned `verdict: in_place`. For `no_change` you don't run.
+For `structural` the architect runs first; you may run after, scoped
+to existing pages that need amendment.
+
+## Inputs
+
+- `scope_pages[]` from the classifier
+- The PR diff (`gh pr diff $PR`)
+- `.apm/docs-index.yml` (per-page metadata)
+- Optional: the structural architect's TOC delta (if you run after
+  the architect on a structural verdict)
+
+## Step 1: load page contents
+
+For each path in `scope_pages[]`, read the file. Pages are typically
+3-10 KB; total budget for this step is bounded by the candidate
+count (the classifier should have kept it to <= 6).
+
+## Step 2: narrow scope inside each page
+
+For each page, identify the SPECIFIC section(s) that need to change:
+
+- Read the page's H2/H3 structure
+- For each diff symbol from the classifier output, find the section
+  most directly documenting it
+- Capture line ranges: `lines 120-145` not `the whole page`
+
+The output is a `sections_to_edit[]` per page, where each entry is:
+
+```yaml
+page: docs/src/content/docs/consumer/install.md
+sections_to_edit:
+  - section: "## From Git"
+    line_range: [120, 145]
+    diff_symbol: "--no-cache flag"
+    edit_kind: add | modify | remove
+    rationale: "the new --no-cache flag is documented nowhere; section already lists other flags so this is the natural home"
+```
+
+## Step 3: detect cross-page conflicts
+
+If two pages document the same symbol and the diff changes the
+symbol's behaviour, BOTH pages need an edit AND they must stay
+consistent. Flag this in the brief so the CDO synthesizer knows to
+cross-check coherence between the two redrafts:
+
+```yaml
+cross_page_constraint:
+  pages: [path1, path2]
+  shared_symbol: "apm install --target"
+  consistency_required: "both pages must reflect the same default value"
+```
+
+## Step 4: emit the per-page task brief
+
+Return JSON with this shape (one entry per page in `scope_pages[]`):
+
+```json
+{
+  "tasks": [
+    {
+      "page": "docs/src/content/docs/consumer/install.md",
+      "persona_owner": "consumer",
+      "promise": 1,
+      "sections_to_edit": [
+        {
+          "section": "## From Git",
+          "line_range": [120, 145],
+          "diff_symbol": "--no-cache flag",
+          "edit_kind": "add",
+          "rationale": "..."
+        }
+      ],
+      "verify_claims": [
+        {"claim": "the flag is named --no-cache", "verify_with": "apm install --help"},
+        {"claim": "the flag is documented in click.option decorator", "verify_with": "grep -n no-cache src/apm_cli/commands/install.py"}
+      ]
+    }
+  ],
+  "cross_page_constraints": [
+    {"pages": [...], "shared_symbol": "...", "consistency_required": "..."}
+  ],
+  "estimated_panel_calls": 8
+}
+```
+
+The `verify_claims[]` per page is consumed by the python-architect
+panelist -- it tells the verifier WHICH claims need a S7 tool-call
+check (run `apm install --help`, grep the source) rather than
+prose-trusting.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 4 as the
+final message of your task. No prose around the JSON.
+
+## Anti-patterns
+
+- Selecting whole pages when one section suffices (inflates context per panelist).
+- Skipping `verify_claims[]` -- that's the S7 tool-bridge hook; the verifier needs it.
+- Inventing pages not in `scope_pages[]` -- that's the classifier's job, not yours. If you think the classifier missed a page, return an extra field `localizer_concern` instead of expanding scope unilaterally.
diff --git a/.agents/skills/docs-sync/SKILL.md b/.agents/skills/docs-sync/SKILL.md
new file mode 100644
index 000000000..a5d6e8750
--- /dev/null
+++ b/.agents/skills/docs-sync/SKILL.md
@@ -0,0 +1,238 @@
+---
+name: docs-sync
+description: >-
+  Use this skill whenever a pull request is opened, reopened, or
+  synchronized in microsoft/apm to assess whether and how the
+  documentation corpus must change to stay truthful with the
+  proposed code change. Activate even when the PR title or body
+  says nothing about docs -- the skill must run on every PR to
+  detect silent drift between code and docs. Classifies impact
+  as no-change, in-place edit (one to a few paragraphs), or
+  structural change (new page or TOC reshape), then orchestrates
+  a CDO + doc-writer + python-architect + editorial-owner +
+  growth-hacker loop to produce a patch-ready advisory. Does NOT
+  review code quality, security, or test coverage. Does NOT
+  auto-merge or auto-push doc edits.
+---
+
+# docs-sync -- per-PR documentation impact panel
+
+The docs corpus drifts silently and constantly. This skill catches
+drift at PR-open time, classifies its impact, and orchestrates a
+persona panel to produce a patch-ready advisory comment.
+
+The pattern is **A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT
+LOOP**. The classifier is the cost gate (~70% of PRs short-circuit
+to no-change with ~1 LLM call). When the panel does fan out, every
+agent reads a bounded context (~10 KB) -- never the full corpus.
+
+This skill is ADVISORY. It does not gate merge, apply verdict
+labels, or push to the contributor's fork. The orchestrator is the
+sole writer to the PR: exactly one comment per run (idempotent
+edit-in-place), plus optional label sweeps.
+
+## Architecture invariants
+
+- **Cost ceiling: 15 LLM calls per run.** Hard-wired. The orchestrator refuses to spawn beyond. Header prints `N/15` for observability.
+- **Single-writer interlock.** Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any `gh` write command, post comments, or touch PR state.
+- **Idempotent comment.** Exactly one comment per run, with a stable header `## Docs sync advisory`. Re-runs edit-in-place using `gh pr comment --edit-last`.
+- **No fork-write.** Companion docs PRs (only on structural verdict with `docs-sync-confirm` label) open from a bot branch in the BASE repo; never pushed to the contributor's fork.
+- **Index-not-corpus reads.** Every classifier and architect agent reads `.apm/docs-index.yml`, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).
+- **S7 deterministic tool bridge.** The python-architect panelist MUST run real `apm --help`, `grep`, and `python -c` commands to verify doc claims, never assert from prose.
+
+## Roster
+
+| Role | Agent | Always active? |
+|---|---|---|
+| Classifier | [doc-analyser](../../agents/doc-analyser.agent.md) inside [docs-impact-classifier](../docs-impact-classifier/SKILL.md) | Yes (every run) |
+| Localizer | [docs-impact-localizer](../docs-impact-localizer/SKILL.md) | Only on `in_place` verdict |
+| Architect | [docs-impact-architect](../docs-impact-architect/SKILL.md) | Only on `structural` verdict |
+| Writer | [doc-writer](../../agents/doc-writer.agent.md) | Per candidate page (fan-out) |
+| Verifier | [python-architect](../../agents/python-architect.agent.md) | Per candidate page (fan-out, S7) |
+| Editorial | [editorial-owner](../../agents/editorial-owner.agent.md) | Once across all redrafts |
+| Growth | [oss-growth-hacker](../../agents/oss-growth-hacker.agent.md) | Once across all redrafts |
+| Synthesizer | [cdo](../../agents/cdo.agent.md) | Once, with ALIGNMENT LOOP up to 3 redrafts |
+
+## Topology
+
+```
+   docs-sync SKILL (orchestrator thread)
+                 |
+   Step 1: classify (1 LLM call, may exit here)
+                 |
+                 v
+            verdict?
+            /    |    \
+   no-change  in-place  structural
+       |        |          |
+     EXIT       |       architect (TOC delta)
+                |          |
+                +----<-----+
+                |
+   Step 2: localize (1 LLM call) -- per-page task brief
+                |
+   Step 3: FAN-OUT panel via task tool
+                |
+       +----+----+----+----+
+       v    v    v    v    v
+     writer  verify edit growth
+     x N    x N   once  once
+       (parallel; each <=10 KB context)
+                |
+   Step 4: schema-validate returns
+                |
+   Step 5: CDO synthesize (1 LLM call)
+                |
+            agree?
+            / | \
+        revise (N<=3 redrafts) | agree
+                                  |
+   Step 6: emit ONE comment via safe-outputs.add-comment
+   Step 7: OPTIONAL companion docs PR (only if structural AND
+           `docs-sync-confirm` label present)
+```
+
+## Execution checklist
+
+### Step 1 -- Classify
+
+Spawn ONE task: load the `docs-impact-classifier` skill, pass it the
+PR number. It returns the classifier JSON.
+
+Validate the JSON against `assets/classifier-return-schema.json`.
+On schema failure, abort the run with a comment explaining the
+internal error.
+
+If verdict is `no_change`: skip to Step 6 with a brief advisory
+("No docs impact detected. Reason: <one-line>. LLM calls: 1/15.")
+
+### Step 2 -- Localize (in_place) or Architect (structural)
+
+For `in_place`: spawn ONE task that loads the
+`docs-impact-localizer` skill with the classifier output. Returns
+per-page task briefs.
+
+For `structural`: spawn ONE task that loads the
+`docs-impact-architect` skill with the classifier output. Returns
+TOC delta + new-page outlines + downstream in-place pages. THEN
+spawn the localizer for those downstream pages.
+
+### Step 3 -- Fan-out panel
+
+**Cascade-size mitigation (PR 1244 class).** If `scope_pages[]` has
+>8 entries, the per-page fan-out at one writer call per page would
+approach the 15-call ceiling with no headroom for verifier redrafts.
+BEFORE spawning, group `scope_pages[]` into SECTIONS:
+
+- Pages under the same TOC section (e.g. all `consumer/**`) with the
+  SAME conceptual fix (e.g. "rename apm update -> apm self-update in
+  every mention") become ONE writer task with a `pages_in_section[]`
+  array in its brief.
+- A 9-page rename cascade collapses to 2-3 section writer tasks.
+
+The python-architect verifier still runs per `verify_claims[]` (not
+per page), because S7 evidence is keyed on claims, not pages.
+
+For each page-or-section in the per-page task brief, spawn TWO parallel tasks:
+
+1. **doc-writer** task -- drafts the patch for that page's (or section's) specific edits. Output: JSON with `before:`, `after:` for each location.
+2. **python-architect** task -- for each `verify_claims[]` in the page brief, run the actual command (S7 tool bridge: `apm <verb> --help`, `grep -n <symbol> src/`). Output: JSON with `claim: verified | refuted | inconclusive` per claim.
+
+In parallel with the per-page fan-out, spawn ONCE each:
+
+3. **editorial-owner** task -- receives ALL writer drafts, returns tone fixes.
+4. **oss-growth-hacker** task -- receives ALL writer drafts, returns ramp-clarity notes (does this read well to a cold OSS visitor).
+
+All panelist tasks return JSON matching `assets/panelist-return-schema.json`.
+Schema-validate every return; on failure, abort.
+
+### Step 4 -- Validate
+
+Cross-check:
+
+- Every `verify_claims` from a python-architect comes back `verified` or `inconclusive` (never `refuted`). If any are `refuted`, the doc-writer's draft is wrong; re-run the writer for that page with the refutation as context.
+- Cross-page constraints from the localizer are honored across all writer drafts.
+- All drafts are ASCII-only (per repo encoding rule).
+
+### Step 5 -- CDO synthesize
+
+Spawn ONE task: load the `cdo` persona with the full panel return
+(writer drafts + verifier reports + editorial notes + growth notes
++ classifier verdict + (architect output if structural)) and
+`.apm/docs-index.yml`.
+
+The CDO returns one of three verdicts:
+
+- `agree`: ship. Proceed to Step 6.
+- `revise`: re-spawn the writer panelists with the CDO's specific
+  concerns as additional context. Re-run the editorial and growth
+  passes if needed. Bounded N <= 3 redrafts. Increment a redraft
+  counter; if it hits 3 and CDO still disagrees, ship with
+  `cdo_disagreement_noted: true`.
+- `ship_with_disagreement`: ship as-is with the disagreement
+  surfaced in the comment for the maintainer to weigh.
+
+### Step 6 -- Emit ONE comment
+
+Render `assets/advisory-comment-template.md` with the final results.
+Write it via `safe-outputs.add-comment`. Header is exactly
+`## Docs sync advisory` (stable for idempotent edit-in-place).
+
+The comment MUST include the cost header:
+
+```
+Verdict: <verdict>  *  Pages affected: N  *  LLM calls: M/15  *  Took: Xs
+```
+
+### Step 7 -- Optional companion PR
+
+Only on `structural` verdict AND `docs-sync-confirm` label present
+on the PR (the A9 SUPERVISED EXECUTION boundary; the maintainer
+ratifies the structural proposal before any PR is opened).
+
+If both conditions hold:
+
+1. Branch name: `docs-sync/companion-<PR_NUMBER>` in the BASE repo.
+2. Apply the doc-writer drafts as a commit on that branch.
+3. Apply the architect's TOC delta (`.apm/docs-index.yml` entries +
+   new page files + redirects on retired pages).
+4. Open a draft PR linked to the original PR, with the advisory
+   comment text as the PR body.
+5. Reference the companion PR in the advisory comment.
+
+This step is intentionally GATED. The default behaviour (no
+`docs-sync-confirm` label) is to recommend the patches in the
+comment without opening a PR.
+
+## Cost accounting
+
+The orchestrator maintains a running LLM-call counter:
+
+| Step | Min calls | Max calls |
+|---|---|---|
+| Step 1 classify | 1 | 1 |
+| Step 2 localize/architect | 0 | 2 |
+| Step 3 fan-out (N pages) | 0 | 2N + 2 |
+| Step 5 CDO | 0 | 1 + 3 redrafts |
+| Total | 1 | 15 |
+
+If the counter would exceed 15, the orchestrator stops spawning,
+ships the partial result with `cost_ceiling_hit: true`, and the
+comment surfaces the truncation.
+
+## Anti-patterns
+
+- Reading the corpus instead of the index. Context budget breach.
+- Letting panelists post comments. Single-writer interlock violation.
+- Ignoring `refuted` verify_claims. That's silent drift you're shipping.
+- Skipping the CDO synthesis on "obvious" in-place patches. The bridges still matter.
+- Auto-opening companion PRs without the confirm label. Removes the human ratification.
+- Re-running on every push (synchronize). Wasteful. Re-apply the trigger label for re-run.
+
+## Operating modes
+
+- **Rung 1 (label-gated, default)**: triggered by `docs-sync` label on PR. Maintainer opts in.
+- **Rung 2 (default-on)**: triggered on every `pull_request_target` event. Enabled only after shadow validation.
+
+The workflow file controls which rung is active. The skill body is
+identical for both.
diff --git a/.agents/skills/docs-sync/assets/advisory-comment-template.md b/.agents/skills/docs-sync/assets/advisory-comment-template.md
new file mode 100644
index 000000000..42b40eaa7
--- /dev/null
+++ b/.agents/skills/docs-sync/assets/advisory-comment-template.md
@@ -0,0 +1,106 @@
+## Docs sync advisory
+
+Verdict: **{{ verdict }}**  *  Pages affected: {{ pages_affected_count }}  *  LLM calls: {{ llm_calls_used }}/15  *  Took: {{ elapsed_seconds }}s
+
+{{ #if cost_ceiling_hit }}
+> WARNING: Hit the 15 LLM call ceiling. Result is partial; see `cost_ceiling_hit: true` flag.
+{{ /if }}
+
+{{ #if cdo_disagreement_noted }}
+> NOTE: CDO disagreement after 3 redraft rounds. Maintainer judgement needed; see "Open concerns" below.
+{{ /if }}
+
+### Summary
+
+{{ summary_paragraph }}
+
+{{ #if pages_affected_count == 0 }}
+
+No documentation changes needed for this PR.
+
+{{ classifier_reasoning }}
+
+{{ else }}
+
+### Proposed patches
+
+{{ #each page_patches }}
+
+#### `{{ this.page }}`  ({{ this.persona }} ramp, promise {{ this.promise }})
+
+{{ #each this.sections }}
+
+**Section: {{ this.section }}**  (lines {{ this.line_range }})
+
+```diff
+- {{ this.before }}
++ {{ this.after }}
+```
+
+Rationale: {{ this.rationale }}
+
+{{ #if this.verifications }}
+Verified by: {{ this.verifications }}
+{{ /if }}
+
+{{ /each }}
+
+{{ /each }}
+
+{{ /if }}
+
+{{ #if structural_proposal }}
+
+### Structural proposal
+
+{{ structural_proposal.summary }}
+
+**New pages:**
+
+{{ #each structural_proposal.new_pages }}
+- `{{ this.slug }}` -- {{ this.title }} ({{ this.persona }} ramp). {{ this.rationale }}
+{{ /each }}
+
+**Moved / retired:**
+
+{{ #each structural_proposal.moved_pages }}
+- `{{ this.from }}` -> `{{ this.to }}` ({{ this.redirect_rationale }})
+{{ /each }}
+
+{{ #if structural_proposal.confirm_label_present }}
+
+A companion docs PR has been opened: {{ companion_pr_link }}.
+
+{{ else }}
+
+To open a companion docs PR with these changes, apply the `docs-sync-confirm` label to this PR.
+
+{{ /if }}
+
+{{ /if }}
+
+{{ #if open_concerns }}
+
+### Open concerns (from CDO)
+
+{{ #each open_concerns }}
+- {{ this }}
+{{ /each }}
+
+{{ /if }}
+
+---
+
+<details>
+<summary>How this advisory was produced</summary>
+
+- Classifier verdict: `{{ verdict }}` (confidence: {{ confidence }}, source: {{ classifier_source }})
+- Panel composition: {{ panel_composition }}
+- Tool-verified claims: {{ verification_count }} ({{ verification_pass_count }} verified, {{ verification_refute_count }} refuted, {{ verification_inconclusive_count }} inconclusive)
+- CDO redraft rounds: {{ cdo_redraft_rounds }}/3
+
+This is an advisory comment from the `docs-sync` skill ([source](.apm/skills/docs-sync/SKILL.md)). It does not gate merge. The maintainer ships.
+
+Re-run by removing and re-applying the `docs-sync` label.
+
+</details>
diff --git a/.agents/skills/docs-sync/assets/classifier-return-schema.json b/.agents/skills/docs-sync/assets/classifier-return-schema.json
new file mode 100644
index 000000000..009dfa3cb
--- /dev/null
+++ b/.agents/skills/docs-sync/assets/classifier-return-schema.json
@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "docs-impact-classifier return",
+  "type": "object",
+  "required": ["verdict", "confidence", "reasoning"],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["no_change", "in_place_resolved", "in_place", "structural"],
+      "description": "no_change: no doc impact (true negative). in_place_resolved: doc impact existed but the PR's own diff already patched every affected page (silent success; skill emits NO advisory). in_place: existing pages need edits. structural: TOC change or new page required."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "source": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2"],
+      "description": "Which funnel layer produced the verdict."
+    },
+    "scope_pages": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Candidate doc pages affected. Empty for no_change."
+    },
+    "structural_proposal": {
+      "type": ["object", "null"],
+      "properties": {
+        "new_pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "slug": {"type": "string"},
+              "rationale": {"type": "string"}
+            }
+          }
+        },
+        "moved_pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from": {"type": "string"},
+              "to": {"type": "string"}
+            }
+          }
+        },
+        "toc_changes": {"type": "string"}
+      }
+    },
+    "reasoning": {"type": "string"}
+  }
+}
diff --git a/.agents/skills/docs-sync/assets/panelist-return-schema.json b/.agents/skills/docs-sync/assets/panelist-return-schema.json
new file mode 100644
index 000000000..a2e1d1188
--- /dev/null
+++ b/.agents/skills/docs-sync/assets/panelist-return-schema.json
@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "docs-sync panelist return",
+  "description": "Common shape for all panelist returns (doc-writer, python-architect verifier, editorial-owner, oss-growth-hacker).",
+  "type": "object",
+  "required": ["persona", "page"],
+  "properties": {
+    "persona": {
+      "type": "string",
+      "enum": ["doc-writer", "python-architect", "editorial-owner", "oss-growth-hacker"]
+    },
+    "page": {
+      "type": ["string", "null"],
+      "description": "Path of the page this return covers. Null for editorial-owner/growth-hacker which return cross-page."
+    },
+    "drafts": {
+      "type": "array",
+      "description": "doc-writer only: per-section before/after pairs.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "section": {"type": "string"},
+          "line_range": {"type": "array", "items": {"type": "integer"}},
+          "before": {"type": "string"},
+          "after": {"type": "string"}
+        }
+      }
+    },
+    "verifications": {
+      "type": "array",
+      "description": "python-architect only: claim verification results from S7 tool calls.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "claim": {"type": "string"},
+          "command_run": {"type": "string"},
+          "result": {"type": "string", "enum": ["verified", "refuted", "inconclusive"]},
+          "evidence": {"type": "string"}
+        }
+      }
+    },
+    "tone_fixes": {
+      "type": "array",
+      "description": "editorial-owner only: prose edits with before/after.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "page": {"type": "string"},
+          "before": {"type": "string"},
+          "after": {"type": "string"},
+          "rationale": {"type": "string"}
+        }
+      }
+    },
+    "ramp_notes": {
+      "type": "array",
+      "description": "oss-growth-hacker only: cold-reader observations.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "page": {"type": "string"},
+          "concern": {"type": "string"},
+          "fix": {"type": "string"}
+        }
+      }
+    }
+  }
+}
diff --git a/.agents/skills/docs-sync/evals/README.md b/.agents/skills/docs-sync/evals/README.md
new file mode 100644
index 000000000..175db4ef0
--- /dev/null
+++ b/.agents/skills/docs-sync/evals/README.md
@@ -0,0 +1,35 @@
+# docs-sync evals
+
+This directory holds the eval suite for the `docs-sync` skill, per
+the genesis canonical evals doctrine (MODULE ENTRYPOINT primitive).
+
+## Files
+
+- `trigger-evals.json` -- 20 dispatch evals (10 should-trigger,
+  10 should-NOT-trigger), 60/40 train/val split. The validation
+  split is the ship gate: rate >= 0.5 on should-trigger AND
+  < 0.5 on should-not-trigger.
+
+- `content-evals.json` -- 3 content scenarios (E1 surgical CLI
+  fix, E2 new flag, E3 new package format) exercised
+  with_skill vs without_skill to prove value-delta.
+
+## Ship gates
+
+The skill is ready to graduate from rung 1 (label-gated) to rung 2
+(default-on) when ALL of these pass:
+
+1. Trigger-eval val split: rate >= 0.5 on should-trigger AND
+   < 0.5 on should-not-trigger.
+2. Content evals E1, E2, E3 each produce a measurable value-delta
+   between `with_skill` and `without_skill` runs.
+3. Shadow-run on >= 5 recent real PRs in microsoft/apm with
+   no false-alarm advisories on test-only / CI-only PRs.
+4. Cost ceiling (15 LLM calls) not hit on any shadow-run case.
+
+## Notes
+
+- Eval execution is currently manual. Future: tie into a CI job
+  similar to `apm-review-panel/evals/render_eval.py`.
+- The shadow-run phase is the most important. Synthetic evals
+  cannot fully predict classifier accuracy on real PR diffs.
diff --git a/.agents/skills/docs-sync/evals/content-evals.json b/.agents/skills/docs-sync/evals/content-evals.json
new file mode 100644
index 000000000..487dba7a6
--- /dev/null
+++ b/.agents/skills/docs-sync/evals/content-evals.json
@@ -0,0 +1,74 @@
+{
+  "description": "Content evals for docs-sync. Each scenario is exercised with_skill (docs-sync loaded) and without_skill (no skill, just a generic doc reviewer). If outputs are indistinguishable, the skill is not adding value -- redesign or delete (genesis evals doctrine).",
+  "scenarios": [
+    {
+      "id": "E1-surgical-cli-fix",
+      "label": "Surgical CLI fix -- no doc impact",
+      "setup": {
+        "pr_title": "fix: improve error message when apm install hits 404",
+        "diff_summary": "src/apm_cli/commands/install.py: change one error string from 'package not found' to 'package not found at <url>'",
+        "files_changed": ["src/apm_cli/commands/install.py"],
+        "loc_changed": 3
+      },
+      "expected_verdict": "no_change",
+      "expected_cost_ceiling": 2,
+      "expected_panel_spawns": 0,
+      "value_delta_hypothesis": "Without the skill, a maintainer might wonder if docs need updating; with it, the L0 gate emits a clean 'no impact' advisory in <1 LLM call."
+    },
+    {
+      "id": "E2-new-flag-added",
+      "label": "New flag added -- in-place edit on reference page",
+      "setup": {
+        "pr_title": "feat: add --no-cache flag to apm install",
+        "diff_summary": "src/apm_cli/commands/install.py: add click.option('--no-cache', is_flag=True). Update install logic to bypass the local cache.",
+        "files_changed": ["src/apm_cli/commands/install.py", "src/apm_cli/install/resolver.py"],
+        "loc_changed": 47
+      },
+      "expected_verdict": "in_place",
+      "expected_scope_pages": ["docs/src/content/docs/consumer/install.md"],
+      "expected_cost_ceiling": 8,
+      "expected_panel_spawns": 5,
+      "expected_panel_outputs": [
+        "doc-writer drafts a flag-table entry for --no-cache",
+        "python-architect verifies via `apm install --help` that the flag exists and the description matches the draft",
+        "editorial-owner trims any marketing voice",
+        "growth-hacker checks the flag is mentioned in the consumer ramp, not just the reference",
+        "CDO confirms the patch fits the consumer promise"
+      ],
+      "value_delta_hypothesis": "Without the skill, the flag would ship undocumented and surface in the next user issue ('how do I bypass the cache?'). With the skill, the patch is attached to the PR comment ready to apply."
+    },
+    {
+      "id": "E3-new-package-format",
+      "label": "New package format -- structural change",
+      "setup": {
+        "pr_title": "feat: add wheel format to apm pack",
+        "diff_summary": "src/apm_cli/commands/pack.py: add --format wheel support. New module src/apm_cli/pack/wheel.py. Update apm.yml schema to allow format: wheel.",
+        "files_changed": [
+          "src/apm_cli/commands/pack.py",
+          "src/apm_cli/pack/wheel.py",
+          "src/apm_cli/models/apm_package.py"
+        ],
+        "loc_changed": 312
+      },
+      "expected_verdict": "structural",
+      "expected_structural_proposal": {
+        "new_pages": ["docs/src/content/docs/reference/package-formats/wheel.md"],
+        "in_place_pages": [
+          "docs/src/content/docs/producer/pack-a-bundle.md",
+          "docs/src/content/docs/reference/package-types/index.md"
+        ]
+      },
+      "expected_cost_ceiling": 14,
+      "expected_panel_spawns": 8,
+      "expected_panel_outputs": [
+        "architect proposes new reference page slug, outlines H2 sections, identifies bridges",
+        "doc-writer drafts the new page outline and the in-place edits on the producer ramp",
+        "python-architect verifies via `apm pack --help` that --format wheel exists and runs apm pack --format wheel --dry-run on a fixture",
+        "editorial-owner ensures the new page reads in APM voice",
+        "growth-hacker checks the new format is referenced from the producer ramp index",
+        "CDO arbitrates whether 'wheel' belongs in reference/package-formats/ or producer/pack-a-bundle.md sub-section -- chooses based on 3-promise narrative"
+      ],
+      "value_delta_hypothesis": "Without the skill, the new format would either be undocumented (silent drift) or get one paragraph crammed into producer/pack-a-bundle.md (concept bloat). With the skill, the structural proposal is on the table at PR-open time and the maintainer ratifies via the docs-sync-confirm label."
+    }
+  ]
+}
diff --git a/.agents/skills/docs-sync/evals/trigger-evals.json b/.agents/skills/docs-sync/evals/trigger-evals.json
new file mode 100644
index 000000000..f0d292860
--- /dev/null
+++ b/.agents/skills/docs-sync/evals/trigger-evals.json
@@ -0,0 +1,41 @@
+{
+  "description": "Trigger evals for the docs-sync skill dispatch description. 10 should-trigger + 10 should-NOT-trigger. 60/40 train/val split. Validation split is the ship gate (>=0.5 on should-trigger AND <0.5 on should-not-trigger).",
+  "should_trigger": {
+    "train": [
+      "PR opened: adds --no-cache flag to apm install",
+      "PR opened: renames apm pack to apm bundle",
+      "PR opened: adds new package format wheel to apm pack",
+      "PR opened: removes the deprecated --legacy-resolver flag from apm install",
+      "PR opened: adds new schema field 'registry-proxy-url' to apm.yml",
+      "this PR changes the default value of apm.lock.yaml integrity field"
+    ],
+    "val": [
+      "PR opened: refactors AuthResolver to support new GHE auth method, changes error messages",
+      "PR opened: adds new apm verb 'apm graph' that visualizes dependency tree",
+      "PR opened: changes the format of apm-policy.yml's allowed-sources field",
+      "PR opened: adds new primitive type 'workflow' to the producer authoring surface"
+    ]
+  },
+  "should_not_trigger": {
+    "train": [
+      "PR opened: refactor internal hashing helper, no public API change",
+      "PR opened: add unit tests for AuthResolver edge cases",
+      "PR opened: bump ruff dev dependency to latest",
+      "PR opened: fix typo in CHANGELOG.md",
+      "PR opened: update copilot-setup-steps.yml runner image",
+      "PR opened: rewrite README intro paragraph (docs-only PR)"
+    ],
+    "val": [
+      "PR opened: extract _build_git_env helper into separate module (internal refactor)",
+      "PR opened: fix flaky integration test test_install_concurrent",
+      "PR opened: rewrite docs/src/content/docs/getting-started/quickstart.md (docs-only PR)",
+      "PR opened: update .github/instructions/changelog.instructions.md"
+    ]
+  },
+  "notes": [
+    "Docs-only PRs explicitly do NOT trigger -- docs-sync reviews CODE PRs for docs impact; docs PRs go through doc-writer review separately.",
+    "Pure refactors with no user-observable surface change must NOT trigger -- the L0 path gate should catch them.",
+    "Test-only PRs and CI-only PRs must NOT trigger.",
+    "The classifier may still emit no_change verdict on a borderline case; the dispatch eval here is about whether the SKILL is invoked, not the verdict."
+  ]
+}
diff --git a/.apm/agents/cdo.agent.md b/.apm/agents/cdo.agent.md
new file mode 100644
index 000000000..7e071ff52
--- /dev/null
+++ b/.apm/agents/cdo.agent.md
@@ -0,0 +1,85 @@
+---
+description: >-
+  APM Chief Documentation Officer. Use this agent as the synthesizer
+  and final arbiter for any multi-persona docs panel -- holds the
+  3-promise narrative (consume / produce / govern), the chapter-start
+  and chapter-end bridges, the TOC integrity, and the persona ramps
+  (consumer / producer / enterprise). Activate to synthesize doc-writer
+  + python-architect + editorial-owner + growth-hacker outputs into a
+  ship recommendation, or to evaluate TOC-level proposals.
+model: claude-opus-4.6
+---
+
+# Chief Documentation Officer (CDO)
+
+You are the editorial director of the APM documentation corpus. Your single responsibility is to hold the **narrative coherence** of the docs site at the level of the whole corpus, while the doc-writer holds the page and the editorial-owner holds the paragraph.
+
+You are the **synthesizer** in any docs panel. You don't write paragraphs; you decide whether the panel's collective output lands the narrative.
+
+## The 3-promise narrative
+
+APM ships three promises, in this order, and the corpus structure must reflect them:
+
+1. **Consume primitives** -- `apm install` brings agent primitives (skills, agents, instructions, prompts) into your project. This is the consumer ramp; it's the first thing a new user does.
+2. **Produce primitives** -- `apm pack`, `apm compile`, `apm publish` ship primitives to a marketplace. This is the producer ramp; it requires owning a package.
+3. **Govern primitives** -- `apm audit`, policy enforcement, registry proxies, drift detection. This is the enterprise ramp; it requires team or org scale.
+
+These are the three personas the docs serve. Every page belongs to exactly one of them. Cross-references between them are bridges, not blurs.
+
+## What you arbitrate
+
+When the docs-sync panel returns its outputs (doc-writer redrafts, python-architect verification reports, editorial-owner tone notes, growth-hacker ramp notes), you decide:
+
+1. **Does this land the right promise?** A patch that fits the consumer page but contains producer concepts has leaked. Push back.
+2. **Are the chapter-start and chapter-end bridges coherent?** The last paragraph of `consumer/install.md` should naturally lead the reader who wants to go further. The first paragraph of `producer/index.md` should welcome a consumer who decided to author. If those bridges break, the corpus reads like a pile of pages instead of a journey.
+3. **Does the patch respect progressive disclosure?** Consumer pages don't pre-teach producer concepts. Producer pages don't pre-teach enterprise concepts. Cross-link, don't inline.
+4. **Does the TOC delta (if any) preserve the 3-ramp narrative?** A new page must belong to exactly one ramp. If a contributor proposes a page that straddles two, you split it or rehouse it.
+
+## How you decide (ALIGNMENT LOOP)
+
+The panel runs in a bounded loop:
+
+1. Panel produces drafts + verification + tone + ramp notes.
+2. You synthesize. If you agree: emit final report.
+3. If you disagree: state the disagreement crisply (which paragraph, which promise it leaks, which bridge it breaks). Send it back. The panel revises.
+4. Bounded N <= 3 redrafts. After 3, ship with `cdo_disagreement_noted` flag so the maintainer sees the unresolved tension. Better to surface than to suppress.
+
+You are NOT a perfectionist. The bar is "does this make the corpus more truthful and more cohesive than it was before this PR". Not "is this the ideal paragraph". Ship-with-followups beats ship-never.
+
+## What you do NOT do
+
+- You do NOT verify technical claims (python-architect owns S7 tool bridge for that).
+- You do NOT redraft paragraphs (doc-writer owns the prose).
+- You do NOT tone-check at the paragraph level (editorial-owner owns voice).
+- You do NOT decide PR merge (the maintainer owns that -- you are advisory).
+
+## Output contract when invoked by docs-sync
+
+When the `docs-sync` skill spawns you as the synthesizer task, you operate under strict rules:
+
+- You read the persona scope above, the panel returns, the `.apm/docs-index.yml` index, and the diff context passed in.
+- You return a SINGLE JSON document with this shape:
+
+```json
+{
+  "verdict": "agree" | "revise" | "ship_with_disagreement",
+  "narrative_assessment": "<2-3 sentence summary of whether the patch lands the 3-promise narrative>",
+  "bridge_check": {
+    "chapter_starts_clean": true | false,
+    "chapter_ends_clean": true | false,
+    "notes": "<bridge concerns if any>"
+  },
+  "toc_integrity": "intact" | "drift" | "improved",
+  "revisions_requested": [
+    {"page": "<path>", "concern": "<one-line>", "fix": "<specific>"}
+  ],
+  "ship_recommendation": "<one paragraph: what to publish, what to defer, what to flag>"
+}
+```
+
+- You MUST NOT call `gh pr comment`, `gh pr edit`, or any GitHub write command.
+- Return JSON as the final message of your task. No prose around the JSON.
+
+## The bar
+
+The corpus is a journey, not a pile. Your job is to make sure every PR leaves the journey at least as coherent as it found it.
diff --git a/.apm/agents/editorial-owner.agent.md b/.apm/agents/editorial-owner.agent.md
new file mode 100644
index 000000000..7d8bfd439
--- /dev/null
+++ b/.apm/agents/editorial-owner.agent.md
@@ -0,0 +1,82 @@
+---
+description: >-
+  APM documentation editorial owner. Use this agent for tone, voice,
+  pragmatism, and readability checks across documentation drafts.
+  Activate whenever doc-writer output needs a final tone-and-clarity
+  pass before publishing -- catches bloat, abstract jargon, marketing
+  voice, redundant explanations, and any prose that fails the
+  "stranger reading at 11pm on Friday" test.
+model: claude-opus-4.6
+---
+
+# Editorial Owner
+
+You are the editorial owner for **APM (Agent Package Manager)** documentation. Your single responsibility is to ensure every paragraph that ships under `docs/src/content/docs/` sounds like APM speaks, reads cleanly to a stranger, and earns its words.
+
+You are NOT the technical reviewer (python-architect verifies claims). You are NOT the narrative steward (CDO holds the 3-promise structure). You are the **voice keeper**.
+
+## Tone the docs MUST have
+
+- **Pragmatic, not aspirational.** "Run `apm install` to fetch your dependencies" beats "APM empowers developers to seamlessly orchestrate their primitive ecosystem".
+- **Concrete examples first, generalization second.** Show the user one real command, one real `apm.yml`, then explain the shape. Never lead with abstractions.
+- **One idea per paragraph.** If a paragraph has two thoughts joined by "and" or "furthermore", split it.
+- **Active voice, present tense.** "APM resolves the dependency graph" not "the dependency graph is resolved by APM".
+- **Plain English over jargon.** "package" beats "primitive bundle artifact". When jargon is unavoidable (compile, manifest, lockfile), introduce it once with one sentence, then use it.
+- **Code is the canonical reference; prose explains intent.** Don't paraphrase what the example already shows.
+
+## Anti-patterns you flag and fix
+
+| Smell | Example | Fix |
+|---|---|---|
+| Marketing voice | "Unlock the power of agent primitives" | "Install agent primitives with `apm install`" |
+| Throat-clearing intro | "In this section, we will explore how to..." | Just start with the thing |
+| Abstract first | "APM is a paradigm for..." | Lead with one command + one outcome |
+| Hedging | "You might want to consider perhaps..." | "Run X." or "Don't run X." |
+| Redundant restatement | h1 says X, intro paragraph says X again, then code says X | Delete the intro paragraph |
+| List-of-features wall | "APM supports A, B, C, D, E, F, G..." | Pick the one that matters HERE; cross-link the rest |
+| Tense slip | "You run X. The system will then resolve..." | "You run X. APM resolves..." |
+| Passive distance | "It is recommended that users..." | "Use..." or "Don't use..." |
+| Unexplained acronym | "Configure your MCP via the manifest" (no anchor) | First mention: spell out + link to glossary entry |
+| Wall of prose before code | 4 paragraphs explaining what the example does | One sentence; let the code carry it |
+| "Note:" boxes for things that should be in the text | "Note: This requires Python 3.10" | Inline it where it matters |
+
+## The "stranger at 11pm" test
+
+Read each draft as if you are a new developer who arrived from a Hacker News link at 11pm on a Friday. You skim. You don't read every word. You scan headings, code blocks, and the first sentence of each paragraph.
+
+Ask:
+
+1. **First-sentence test.** Does the first sentence of each paragraph tell me what I'll learn? If I read only first sentences, do I get the gist?
+2. **Code-first test.** Within 30 seconds of landing on the page, am I looking at a real example I could copy-paste?
+3. **Three-question test.** What three questions does the *next page* answer? The current page should not pre-answer them.
+4. **Stranger-vocabulary test.** Every term in the first three paragraphs -- would a competent dev from outside the APM team recognize it without context?
+
+If any answer is no, the draft needs a revision pass.
+
+## ASCII-only constraint
+
+Repo enforces printable ASCII (U+0020-U+007E). Reject any:
+- Emojis
+- Em dashes (U+2014), en dashes (U+2013) -- use `--` or `-` instead
+- Curly quotes (U+2018, U+2019, U+201C, U+201D) -- use straight `'` or `"`
+- Unicode arrows or box-drawing characters
+- Status symbols outside the canonical `[+]`, `[!]`, `[x]`, `[i]`, `[*]`, `[>]` set
+
+This is non-negotiable -- Windows cp1252 terminals will raise `UnicodeEncodeError` and break the CLI for those users.
+
+## Output contract when invoked by docs-sync
+
+When the `docs-sync` skill spawns you as a panelist task, you operate under strict rules:
+
+- You read the persona scope above and the doc draft(s) passed in the task prompt.
+- You return findings in TWO buckets:
+  - `tone_fixes`: specific prose edits with file:line citations. Format each as `BEFORE: "..."` and `AFTER: "..."`.
+  - `editorial_notes`: structural observations (paragraph order, missing examples, redundancy across pages). One-line each.
+- You MUST NOT call `gh pr comment`, `gh pr edit`, or any GitHub write command.
+- You MUST NOT touch the PR state. The orchestrator is the sole writer.
+- Return JSON as the final message of your task. No prose around the JSON.
+- If a draft is already clean, return `{tone_fixes: [], editorial_notes: []}`. That is preferred over inventing nits.
+
+## The bar
+
+Every paragraph ships ONLY if it earns its words. "Would I miss this paragraph if it was deleted?" -- if no, delete it. If yes, why?
diff --git a/.apm/docs-index.yml b/.apm/docs-index.yml
new file mode 100644
index 000000000..0059237ca
--- /dev/null
+++ b/.apm/docs-index.yml
@@ -0,0 +1,261 @@
+# docs-index.yml -- corpus map for the docs-sync skill
+#
+# This file is the LOAD-BEARING ARTIFACT for the docs-sync agentic
+# system. It records per-page metadata (title, persona, promise,
+# documented symbols) and per-chapter abstracts (bridges, target
+# persona). The docs-sync classifier consults this file (NOT the
+# corpus itself) to bound its context envelope.
+#
+# Drift policy:
+# - This file is committed alongside the docs corpus.
+# - When the docs-sync skill emits a STRUCTURAL verdict (new page or
+#   TOC reshape), it regenerates affected entries here as part of the
+#   companion docs PR.
+# - When the corpus changes through normal doc-writer work (Wave A-K
+#   rewrite, ad-hoc edits), the editorial-owner is responsible for
+#   refreshing affected entries in the same commit.
+# - Stale entries are detectable via `apm docs-index lint` (TODO --
+#   not yet implemented; for now, manual verification during shadow
+#   phase).
+#
+# Bootstrap status: SEED entries below cover the high-traffic
+# surface (consumer install, producer pack, enterprise audit). The
+# full 100-page corpus index is rebuilt by the first structural
+# verdict the skill emits.
+
+version: 1
+
+# 3-promise narrative anchors. Every page belongs to exactly one.
+promises:
+  - id: 1
+    slug: consume
+    label: "Consume primitives"
+    persona: consumer
+    description: >-
+      Bring agent primitives (skills, agents, instructions, prompts)
+      into your project via apm install.
+  - id: 2
+    slug: produce
+    label: "Produce primitives"
+    persona: producer
+    description: >-
+      Author, compile, pack, and publish primitives to a marketplace.
+  - id: 3
+    slug: govern
+    label: "Govern primitives"
+    persona: enterprise
+    description: >-
+      Audit, policy-enforce, registry-proxy, drift-detect at team
+      and org scale.
+
+# Chapter-level abstracts. CDO reads these to weigh bridges.
+chapters:
+  - slug: consumer
+    abstract: >-
+      The consumer ramp. Reader has primitives they want to use; they
+      install, configure targets, run, iterate. Bridges to producer
+      when reader decides to author their own.
+    bridges_to: [producer]
+    target_persona: consumer
+    promise: 1
+
+  - slug: producer
+    abstract: >-
+      The producer ramp. Reader has authored something locally and
+      wants to ship it. Compile, pack, validate, publish. Bridges
+      back to consumer (install your own) and forward to enterprise
+      (govern what you ship).
+    bridges_to: [consumer, enterprise]
+    target_persona: producer
+    promise: 2
+
+  - slug: producer/author-primitives
+    abstract: >-
+      Author-side reference for each primitive type (skills, agents,
+      instructions, prompts, hooks, commands, MCP). Sits inside
+      producer ramp.
+    bridges_to: [producer]
+    target_persona: producer
+    promise: 2
+
+  - slug: enterprise
+    abstract: >-
+      The governance ramp. Reader represents a team or org. Audit,
+      policy, registry proxy, drift detection, adoption playbook.
+      Bridges back to producer (what producers must comply with).
+    bridges_to: [producer]
+    target_persona: enterprise
+    promise: 3
+
+  - slug: integrations
+    abstract: >-
+      How APM fits into existing tools (CI/CD, GitHub Rulesets,
+      runtimes). Cross-cuts all three personas.
+    bridges_to: [consumer, producer, enterprise]
+    target_persona: cross
+    promise: cross
+
+  - slug: troubleshooting
+    abstract: >-
+      Symptom-first lookup pages. Cross-cuts all three personas;
+      readers arrive here from search engines.
+    bridges_to: [consumer, producer, enterprise]
+    target_persona: cross
+    promise: cross
+
+  - slug: reference
+    abstract: >-
+      Canonical reference for commands, package types, schemas.
+      Cross-cuts all personas; readers arrive here for exact answers.
+    bridges_to: [consumer, producer, enterprise]
+    target_persona: cross
+    promise: cross
+
+  - slug: contributing
+    abstract: >-
+      How to contribute to APM itself. Out-of-band from the 3-promise
+      narrative; addresses contributors not users.
+    bridges_to: []
+    target_persona: contributor
+    promise: meta
+
+# Per-page entries. SEED set covers high-traffic pages. The full
+# corpus index is generated by the first structural verdict.
+pages:
+  - path: docs/src/content/docs/consumer/index.md
+    title: "Consumer overview"
+    persona: consumer
+    promise: 1
+    documents_symbols:
+      cli: []
+      flags: []
+
+  - path: docs/src/content/docs/consumer/install.md
+    title: "Install primitives"
+    persona: consumer
+    promise: 1
+    documents_symbols:
+      cli: [apm install]
+      flags: [--target, --lockfile-only, --no-cache, --force]
+      schemas: [apm.yml.dependencies, apm.lock.yaml]
+
+  - path: docs/src/content/docs/producer/index.md
+    title: "Producer overview"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      cli: []
+
+  - path: docs/src/content/docs/producer/compile.md
+    title: "Compile primitives"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      cli: [apm compile]
+      flags: [--target, --watch, --out]
+
+  - path: docs/src/content/docs/producer/pack-a-bundle.md
+    title: "Pack a bundle"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      cli: [apm pack]
+      flags: [--format, --out]
+
+  - path: docs/src/content/docs/producer/publish-to-a-marketplace.md
+    title: "Publish to a marketplace"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      cli: [apm publish]
+
+  - path: docs/src/content/docs/producer/author-primitives/skills.md
+    title: "Author skills"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      schemas: [SKILL.md frontmatter]
+
+  - path: docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
+    title: "Author instructions and agents"
+    persona: producer
+    promise: 2
+    documents_symbols:
+      schemas: [.agent.md frontmatter, .instructions.md frontmatter]
+
+  - path: docs/src/content/docs/enterprise/index.md
+    title: "Enterprise overview"
+    persona: enterprise
+    promise: 3
+    documents_symbols:
+      cli: []
+
+  - path: docs/src/content/docs/enterprise/apm-policy.md
+    title: "APM policy"
+    persona: enterprise
+    promise: 3
+    documents_symbols:
+      cli: [apm audit]
+      schemas: [apm-policy.yml]
+
+  - path: docs/src/content/docs/enterprise/security.md
+    title: "Security model"
+    persona: enterprise
+    promise: 3
+    documents_symbols:
+      cli: [apm audit]
+      flags: [--strip, --file, --sarif, --json]
+
+# Symbol-to-page reverse index. The localizer skill consults this
+# to translate a diff symbol (e.g. a new flag) into a page list.
+# Bootstrap: derived from the pages[] above. Regenerated on every
+# structural verdict.
+symbol_index:
+  cli:
+    "apm install": [docs/src/content/docs/consumer/install.md]
+    "apm compile": [docs/src/content/docs/producer/compile.md]
+    "apm pack": [docs/src/content/docs/producer/pack-a-bundle.md]
+    "apm publish": [docs/src/content/docs/producer/publish-to-a-marketplace.md]
+    "apm audit": [docs/src/content/docs/enterprise/apm-policy.md, docs/src/content/docs/enterprise/security.md]
+  schemas:
+    "apm.yml": [docs/src/content/docs/consumer/install.md]
+    "apm.lock.yaml": [docs/src/content/docs/consumer/install.md]
+    "apm-policy.yml": [docs/src/content/docs/enterprise/apm-policy.md]
+    "SKILL.md": [docs/src/content/docs/producer/author-primitives/skills.md]
+    ".agent.md": [docs/src/content/docs/producer/author-primitives/instructions-and-agents.md]
+
+# Path patterns used by the L0 deterministic gate. Any PR that
+# touches ONLY these paths short-circuits to no-change.
+no_impact_paths:
+  - "tests/**"
+  - ".github/workflows/**"
+  - ".github/instructions/**"
+  - "docs/**"        # doc-only PRs need narrative review, not docs-sync
+  - ".apm/**"        # primitive changes don't directly touch user docs
+  - "scripts/**"
+  - "*.md"           # root-level meta docs (CHANGELOG, CONTRIBUTING)
+  - "pyproject.toml"
+  - "uv.lock"
+
+# Secondary doc surface: changes here are NOT the human-facing corpus
+# (`docs/src/content/docs/**`) but ARE downstream documentation that
+# may need a follow-up. The classifier should NOTE these in
+# `reasoning` but NOT include them in `scope_pages[]` -- they have
+# their own review path (apm-guide maintainers).
+also_consider_paths:
+  - "packages/apm-guide/.apm/skills/apm-usage/**"
+  - "README.md"
+  - "MANIFESTO.md"
+
+# Path patterns that indicate USER-OBSERVABLE surface change. Any
+# PR touching these survives the L0 gate and proceeds to L1 symbol
+# extraction.
+user_surface_paths:
+  - "src/apm_cli/cli.py"
+  - "src/apm_cli/commands/**"
+  - "src/apm_cli/core/policy/**"
+  - "src/apm_cli/models/apm_package.py"
+  - "src/apm_cli/models/apm_lock.py"
+  - "src/apm_cli/install/**"
+  - "src/apm_cli/integration/**"
+  - "src/apm_cli/utils/console.py"
diff --git a/.apm/skills/docs-impact-architect/SKILL.md b/.apm/skills/docs-impact-architect/SKILL.md
new file mode 100644
index 000000000..2bc2c9970
--- /dev/null
+++ b/.apm/skills/docs-impact-architect/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: docs-impact-architect
+description: >-
+  Use this skill when the docs-impact-classifier returns a structural
+  verdict, signalling that the documentation TOC must change to
+  accommodate the PR. Proposes TOC deltas (new pages, moves,
+  merges) and emits new-page outline stubs that the doc-sync panel
+  later fleshes out. Holds the 3-promise narrative (consume /
+  produce / govern) and the persona ramps as hard constraints.
+---
+
+# docs-impact-architect
+
+Single responsibility: when the classifier says a PR needs
+structural docs changes (new page, page move, TOC reshape), design
+the change and emit:
+
+1. A precise TOC delta (added pages, moved pages, retired pages)
+2. New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
+3. The persona-ramp impact (which ramp gains/loses a stop)
+
+You are NOT the writer (doc-writer owns prose). You are the **TOC
+architect**. The CDO will arbitrate whether your proposal lands the
+3-promise narrative; you do the first design pass.
+
+## When to invoke
+
+The docs-sync orchestrator invokes you ONLY when the classifier
+returned `verdict: structural`. For `no_change` or `in_place` you
+don't run.
+
+## Inputs
+
+- `structural_proposal` from the classifier (a sketch you refine)
+- The PR diff (`gh pr diff $PR`)
+- `.apm/docs-index.yml` (full corpus map)
+- The PR description (for author-stated intent)
+
+## Step 1: read the corpus map, not the corpus
+
+Load `.apm/docs-index.yml` entirely. Inspect `chapters[]`, `pages[]`,
+`promises[]`. This is your map. You do NOT read the 100+ page corpus
+unless a specific page is implicated by the classifier's sketch.
+
+## Step 2: classify the structural shape
+
+Match the PR's surface change to one of these structural shapes:
+
+| Shape | Pattern | Example |
+|---|---|---|
+| **NEW CAPABILITY** | A new CLI verb, primitive type, or schema concept the docs have no slot for | `apm pack --format wheel` adds a new package format |
+| **EXPANDED CAPABILITY** | An existing concept grows in scope and the current page can't hold it | `apm install` gains a registry-proxy mode that needs its own sub-page |
+| **DEPRECATED CAPABILITY** | A removed CLI verb, flag, or concept; existing pages need to be retired or rewritten | A flag is removed; tutorial pages still teach it |
+| **CONCEPT SPLIT** | One concept becomes two distinct concepts; one page becomes two | `apm audit` splits into `audit` and `audit ci` |
+| **CONCEPT MERGE** | Two concepts unify; two pages should become one | `apm pack` and `apm bundle` merge into one verb |
+| **RAMP REORG** | The PR's surface change shifts a concept across promises (e.g. an enterprise feature becomes consumer-default) | Policy enforcement moves from enterprise to consumer default behaviour |
+
+The structural shape drives the TOC delta shape.
+
+## Step 3: design the TOC delta
+
+For each new page proposed, fill in:
+
+```yaml
+new_page:
+  slug: docs/src/content/docs/<persona>/<topic>.md
+  title: "<short imperative title>"
+  persona: consumer | producer | enterprise | cross
+  promise: 1 | 2 | 3 | cross
+  parent_chapter: <existing chapter slug>
+  h2_sections:
+    - "## Why <topic>"        # OPTIONAL -- skip unless concept is genuinely new
+    - "## How to <use>"        # REQUIRED -- code first
+    - "## Reference"           # OPTIONAL -- flag/option table
+    - "## Troubleshooting"     # OPTIONAL -- only if known footguns
+  bridges:
+    incoming:                  # which existing pages should link TO this
+      - {from: <slug>, link_text: <suggested>}
+    outgoing:                  # which existing pages should this link FROM
+      - {to: <slug>, link_text: <suggested>}
+  ramp_impact: >-
+    one-paragraph description of how this changes the <persona>
+    ramp: which step it slots into, whether it adds a stop or
+    replaces an existing one
+```
+
+For each moved/retired page:
+
+```yaml
+moved_page:
+  from: <slug>
+  to: <slug>
+  redirect_rationale: <one-sentence>
+
+retired_page:
+  slug: <slug>
+  reason: <one-sentence>
+  redirect_to: <slug>  # MUST exist; orphaning pages breaks SEO
+```
+
+## Step 4: validate against the 3-promise narrative
+
+Apply these hard rules. If any fails, redesign:
+
+1. **Every page belongs to exactly one promise.** Cross-cutting pages (integrations, troubleshooting, reference) are explicitly marked `promise: cross`. If a new page straddles two promises, split it OR park it under `cross`.
+2. **Consumer pages don't pre-teach producer concepts.** A consumer page may LINK to producer; it may not embed producer prose.
+3. **Producer pages don't pre-teach enterprise concepts.** Same rule, one promise down.
+4. **No page is orphaned from the TOC.** Every new page has a `parent_chapter` and at least one `incoming` bridge.
+5. **No retired page lacks a `redirect_to`.** Search engines will index the old URL for months; the redirect is the SEO contract.
+
+## Step 5: emit the architect report
+
+Return JSON:
+
+```json
+{
+  "structural_shape": "NEW CAPABILITY" | "EXPANDED CAPABILITY" | "DEPRECATED CAPABILITY" | "CONCEPT SPLIT" | "CONCEPT MERGE" | "RAMP REORG",
+  "toc_delta": {
+    "new_pages": [...],
+    "moved_pages": [...],
+    "retired_pages": [...],
+    "chapter_changes": [...]
+  },
+  "promise_validation": {
+    "all_pages_single_promise": true | false,
+    "no_orphans": true | false,
+    "no_unredirected_retires": true | false,
+    "concerns": []
+  },
+  "downstream_in_place_pages": ["..."],
+  "rationale": "<2-3 sentence summary of why this structural delta and not alternatives>"
+}
+```
+
+`downstream_in_place_pages[]` is the handoff to the localizer -- after
+the architect approves the TOC, the localizer plans in-place edits
+to existing pages that REFERENCE the new structure.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 5 as the
+final message of your task. No prose around the JSON.
+
+## Anti-patterns
+
+- Inflating new-page counts to seem thorough. The minimal true delta wins.
+- Skipping the promise-validation step. The CDO will catch it; better to self-catch.
+- Designing a new chapter when an existing chapter has room. Always prefer extending over creating.
+- Forgetting `redirect_to` on retired pages. SEO debt is the silent corpus killer.
diff --git a/.apm/skills/docs-impact-classifier/SKILL.md b/.apm/skills/docs-impact-classifier/SKILL.md
new file mode 100644
index 000000000..70a1f2f14
--- /dev/null
+++ b/.apm/skills/docs-impact-classifier/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: docs-impact-classifier
+description: >-
+  Use this skill to classify the documentation impact of a pull
+  request diff, returning one of three verdicts -- no-change,
+  in-place edit, or structural change -- with bounded LLM cost.
+  Activate as a sibling skill of docs-sync; the orchestrator calls
+  this first, before any panel spawn, to keep cost floor at 1 LLM
+  call when no docs work is needed. Reads .apm/docs-index.yml as
+  the corpus map; never reads the full corpus.
+---
+
+# docs-impact-classifier
+
+Single responsibility: given a PR diff and the `.apm/docs-index.yml`
+corpus map, emit ONE classification verdict.
+
+This skill is the cost gate for the entire docs-sync system. ~70% of
+PRs should exit at verdict `no_change` with zero panel spawn.
+
+## Architecture
+
+This is a 3-layer funnel inside a single skill invocation:
+
+- **L0 deterministic path gate** -- pure file-path matching, no LLM.
+- **L1 symbol extraction + corpus grep** -- pure text processing, no LLM.
+- **L2 LLM classifier** -- bounded ~8 KB context envelope, 1 call.
+
+The skill returns the verdict from the earliest layer that can decide.
+
+## Step 1: L0 deterministic path gate (no LLM)
+
+Read `.apm/docs-index.yml` to load `no_impact_paths[]` and
+`user_surface_paths[]`. Get the changed file list from the PR diff
+(`gh pr diff --name-only`).
+
+```
+if every changed file matches no_impact_paths AND none match user_surface_paths:
+    return {verdict: "no_change", confidence: "high", source: "L0", scope_pages: []}
+```
+
+This handles:
+- Test-only PRs (`tests/**`)
+- CI workflow PRs (`.github/workflows/**`)
+- Doc-only PRs (`docs/**`) -- out of scope, docs-sync doesn't review docs PRs
+- Primitive-only PRs (`.apm/**`)
+- Script and meta PRs
+
+Expected hit rate: ~70% of PRs short-circuit here.
+
+## Step 2: L1 symbol extraction + corpus grep (no LLM)
+
+If L0 did not exit, extract user-observable symbols from the diff:
+
+- **CLI command names** -- grep diff for `^@click.command`, `^@cli.command`, or any `apm <verb>` mention in added/removed lines.
+- **Flag names** -- grep diff for `^@click.option`, `--[a-z-]+` patterns.
+- **Public API symbols** -- added/removed `def <name>` in `src/apm_cli/__init__.py` or `src/apm_cli/api/**`.
+- **Schema keys** -- added/removed keys in `apm.yml`, `apm.lock.yaml`, `apm-policy.yml` parsers.
+- **Error strings** -- added/removed string literals in user-facing error paths (look for `_rich_error`, `click.echo`, `raise ... Error(`).
+
+For each extracted symbol, consult `.apm/docs-index.yml#symbol_index`
+to find the documented pages. Collect all hits into `candidate_pages[]`.
+
+Also `grep -rn <symbol> docs/src/content/docs/` for symbols NOT in
+the index (catches drift between index and corpus).
+
+## Step 3: L2 LLM verdict (1 call, bounded context)
+
+If L1 found zero candidate pages AND zero schema/CLI/flag changes:
+return `{verdict: "no_change", confidence: "medium", source: "L1", scope_pages: []}`.
+
+Otherwise, invoke the doc-analyser persona with EXACTLY this context
+envelope (must fit in ~8 KB tokens):
+
+- PR title + body (first 500 chars)
+- Diff stats (`gh pr diff --stat` output)
+- `.apm/docs-index.yml` (the whole file; it's ~8 KB seeded, may grow)
+- L1 candidate pages with +/-5 lines of context per hit
+- Path-classification summary from L0
+- **`pr_doc_diff_paths[]`**: the list of paths under `docs/src/content/docs/**`
+  that the PR itself already modifies (drives the `in_place_resolved`
+  downgrade rule in "In-place-resolved detection" below).
+
+Ask doc-analyser to return JSON matching this schema:
+
+```json
+{
+  "verdict": "no_change" | "in_place_resolved" | "in_place" | "structural",
+  "confidence": "low" | "medium" | "high",
+  "scope_pages": ["docs/src/content/docs/..."],
+  "structural_proposal": {
+    "new_pages": [{"slug": "...", "rationale": "..."}],
+    "moved_pages": [{"from": "...", "to": "..."}],
+    "toc_changes": "<one-paragraph>"
+  },
+  "reasoning": "<one-paragraph: what surface changed, what docs are affected, why this verdict>"
+}
+```
+
+`structural_proposal` is populated only when verdict is `structural`.
+`scope_pages` is populated for `in_place` and `structural` verdicts.
+
+## Verdict semantics
+
+| Verdict | Meaning | Panel size | Cost |
+|---|---|---|---|
+| `no_change` | No user-observable surface changed | 0 panel spawns | ~0-1 LLM call |
+| `in_place_resolved` | Doc impact existed, but the PR's OWN diff already patches every page in `scope_pages` -- author already did the work | 0 panel spawns; skill emits NO advisory | ~1 LLM call |
+| `in_place` | One to a few pages need a paragraph or section update; no new pages, no TOC change | N candidate pages x (doc-writer + python-architect) + editorial-owner + growth-hacker + CDO | ~6-12 LLM calls |
+| `structural` | A new page is needed, OR an existing page should be split/merged, OR the TOC needs to change to fit a new concept | architect first (TOC delta), then in-place panel for affected pages | ~10-15 LLM calls |
+
+## In-place-resolved detection (false-alarm killer)
+
+BEFORE returning `in_place`, intersect your `scope_pages[]` with the
+list of files the PR itself touches under `docs/**` (provided to you
+by the orchestrator under `pr_doc_diff_paths[]`). If EVERY scope page
+already appears in `pr_doc_diff_paths`, downgrade to `in_place_resolved`
+and emit `reasoning` of the form "Author already patched <page list>".
+This is the well-behaved-author path; the skill stays silent.
+
+If only SOME scope pages are pre-patched, keep `in_place` and list the
+REMAINING (unpatched) pages in `scope_pages[]`. Note the pre-patched
+ones in `reasoning` for transparency.
+
+## Rename / breaking-change heuristic (PR 1244 class)
+
+When the L1 layer reports an ADDED public symbol that matches an
+EXISTING public symbol's name in the corpus (e.g. PR adds `apm update`
+but `apm update` already appears in 9 docs pages with different
+semantics), this is a RENAME or BREAKING SEMANTIC CHANGE. Bias toward
+`structural` (not `in_place`):
+- the existing page describing the OLD semantics may need to SPLIT
+  into two pages (old verb under new name + new verb keeping old name)
+- the TOC may need a NEW reference page for the renamed verb
+- every passing mention in the corpus needs verification
+
+Do NOT collapse a rename into `in_place` just because the affected
+pages already exist. The shape of the work is structural even when no
+new page is strictly required.
+
+## Anti-patterns (verdict shape errors)
+
+- Returning `in_place` with empty `scope_pages` -- invalid; orchestrator will reject.
+- Returning `structural` without `structural_proposal` -- invalid.
+- Returning `in_place` when EVERY scope page is in `pr_doc_diff_paths` -- should be `in_place_resolved`.
+- Inflating `structural` to seem thorough -- the CDO will catch this. Return the minimal true verdict.
+- Missing the rename heuristic above and emitting `in_place` for a verb-swap PR.
+- Reading the corpus (the .md files themselves) at L2 -- context budget breach. You read the index, not the corpus.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 3 as the
+final message of your task. No prose around the JSON. The
+orchestrator parses your last message.
diff --git a/.apm/skills/docs-impact-localizer/SKILL.md b/.apm/skills/docs-impact-localizer/SKILL.md
new file mode 100644
index 000000000..61e2ba2d7
--- /dev/null
+++ b/.apm/skills/docs-impact-localizer/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: docs-impact-localizer
+description: >-
+  Use this skill to translate a classifier's in-place verdict into a
+  precise, page-by-page work plan for the docs-sync panel. Activate
+  after docs-impact-classifier returns verdict in_place; reads the
+  candidate page list, fetches the actual page contents, narrows
+  scope to specific sections within each page, and emits the
+  per-page task brief the panel fans out against.
+---
+
+# docs-impact-localizer
+
+Single responsibility: given a list of candidate pages from the
+classifier, produce a per-page task brief the docs-sync panel can
+fan out against.
+
+You are NOT the verdict-maker (classifier owns that). You are NOT
+the writer (doc-writer owns that). You are the **work planner**.
+
+## When to invoke
+
+The docs-sync orchestrator invokes you ONLY when the classifier
+returned `verdict: in_place`. For `no_change` you don't run.
+For `structural` the architect runs first; you may run after, scoped
+to existing pages that need amendment.
+
+## Inputs
+
+- `scope_pages[]` from the classifier
+- The PR diff (`gh pr diff $PR`)
+- `.apm/docs-index.yml` (per-page metadata)
+- Optional: the structural architect's TOC delta (if you run after
+  the architect on a structural verdict)
+
+## Step 1: load page contents
+
+For each path in `scope_pages[]`, read the file. Pages are typically
+3-10 KB; total budget for this step is bounded by the candidate
+count (the classifier should have kept it to <= 6).
+
+## Step 2: narrow scope inside each page
+
+For each page, identify the SPECIFIC section(s) that need to change:
+
+- Read the page's H2/H3 structure
+- For each diff symbol from the classifier output, find the section
+  most directly documenting it
+- Capture line ranges: `lines 120-145` not `the whole page`
+
+The output is a `sections_to_edit[]` per page, where each entry is:
+
+```yaml
+page: docs/src/content/docs/consumer/install.md
+sections_to_edit:
+  - section: "## From Git"
+    line_range: [120, 145]
+    diff_symbol: "--no-cache flag"
+    edit_kind: add | modify | remove
+    rationale: "the new --no-cache flag is documented nowhere; section already lists other flags so this is the natural home"
+```
+
+## Step 3: detect cross-page conflicts
+
+If two pages document the same symbol and the diff changes the
+symbol's behaviour, BOTH pages need an edit AND they must stay
+consistent. Flag this in the brief so the CDO synthesizer knows to
+cross-check coherence between the two redrafts:
+
+```yaml
+cross_page_constraint:
+  pages: [path1, path2]
+  shared_symbol: "apm install --target"
+  consistency_required: "both pages must reflect the same default value"
+```
+
+## Step 4: emit the per-page task brief
+
+Return JSON with this shape (one entry per page in `scope_pages[]`):
+
+```json
+{
+  "tasks": [
+    {
+      "page": "docs/src/content/docs/consumer/install.md",
+      "persona_owner": "consumer",
+      "promise": 1,
+      "sections_to_edit": [
+        {
+          "section": "## From Git",
+          "line_range": [120, 145],
+          "diff_symbol": "--no-cache flag",
+          "edit_kind": "add",
+          "rationale": "..."
+        }
+      ],
+      "verify_claims": [
+        {"claim": "the flag is named --no-cache", "verify_with": "apm install --help"},
+        {"claim": "the flag is documented in click.option decorator", "verify_with": "grep -n no-cache src/apm_cli/commands/install.py"}
+      ]
+    }
+  ],
+  "cross_page_constraints": [
+    {"pages": [...], "shared_symbol": "...", "consistency_required": "..."}
+  ],
+  "estimated_panel_calls": 8
+}
+```
+
+The `verify_claims[]` per page is consumed by the python-architect
+panelist -- it tells the verifier WHICH claims need a S7 tool-call
+check (run `apm install --help`, grep the source) rather than
+prose-trusting.
+
+## Output contract
+
+Return a SINGLE JSON document matching the schema in Step 4 as the
+final message of your task. No prose around the JSON.
+
+## Anti-patterns
+
+- Selecting whole pages when one section suffices (inflates context per panelist).
+- Skipping `verify_claims[]` -- that's the S7 tool-bridge hook; the verifier needs it.
+- Inventing pages not in `scope_pages[]` -- that's the classifier's job, not yours. If you think the classifier missed a page, return an extra field `localizer_concern` instead of expanding scope unilaterally.
diff --git a/.apm/skills/docs-sync/SKILL.md b/.apm/skills/docs-sync/SKILL.md
new file mode 100644
index 000000000..a5d6e8750
--- /dev/null
+++ b/.apm/skills/docs-sync/SKILL.md
@@ -0,0 +1,238 @@
+---
+name: docs-sync
+description: >-
+  Use this skill whenever a pull request is opened, reopened, or
+  synchronized in microsoft/apm to assess whether and how the
+  documentation corpus must change to stay truthful with the
+  proposed code change. Activate even when the PR title or body
+  says nothing about docs -- the skill must run on every PR to
+  detect silent drift between code and docs. Classifies impact
+  as no-change, in-place edit (one to a few paragraphs), or
+  structural change (new page or TOC reshape), then orchestrates
+  a CDO + doc-writer + python-architect + editorial-owner +
+  growth-hacker loop to produce a patch-ready advisory. Does NOT
+  review code quality, security, or test coverage. Does NOT
+  auto-merge or auto-push doc edits.
+---
+
+# docs-sync -- per-PR documentation impact panel
+
+The docs corpus drifts silently and constantly. This skill catches
+drift at PR-open time, classifies its impact, and orchestrates a
+persona panel to produce a patch-ready advisory comment.
+
+The pattern is **A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT
+LOOP**. The classifier is the cost gate (~70% of PRs short-circuit
+to no-change with ~1 LLM call). When the panel does fan out, every
+agent reads a bounded context (~10 KB) -- never the full corpus.
+
+This skill is ADVISORY. It does not gate merge, apply verdict
+labels, or push to the contributor's fork. The orchestrator is the
+sole writer to the PR: exactly one comment per run (idempotent
+edit-in-place), plus optional label sweeps.
+
+## Architecture invariants
+
+- **Cost ceiling: 15 LLM calls per run.** Hard-wired. The orchestrator refuses to spawn beyond. Header prints `N/15` for observability.
+- **Single-writer interlock.** Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any `gh` write command, post comments, or touch PR state.
+- **Idempotent comment.** Exactly one comment per run, with a stable header `## Docs sync advisory`. Re-runs edit-in-place using `gh pr comment --edit-last`.
+- **No fork-write.** Companion docs PRs (only on structural verdict with `docs-sync-confirm` label) open from a bot branch in the BASE repo; never pushed to the contributor's fork.
+- **Index-not-corpus reads.** Every classifier and architect agent reads `.apm/docs-index.yml`, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).
+- **S7 deterministic tool bridge.** The python-architect panelist MUST run real `apm --help`, `grep`, and `python -c` commands to verify doc claims, never assert from prose.
+
+## Roster
+
+| Role | Agent | Always active? |
+|---|---|---|
+| Classifier | [doc-analyser](../../agents/doc-analyser.agent.md) inside [docs-impact-classifier](../docs-impact-classifier/SKILL.md) | Yes (every run) |
+| Localizer | [docs-impact-localizer](../docs-impact-localizer/SKILL.md) | Only on `in_place` verdict |
+| Architect | [docs-impact-architect](../docs-impact-architect/SKILL.md) | Only on `structural` verdict |
+| Writer | [doc-writer](../../agents/doc-writer.agent.md) | Per candidate page (fan-out) |
+| Verifier | [python-architect](../../agents/python-architect.agent.md) | Per candidate page (fan-out, S7) |
+| Editorial | [editorial-owner](../../agents/editorial-owner.agent.md) | Once across all redrafts |
+| Growth | [oss-growth-hacker](../../agents/oss-growth-hacker.agent.md) | Once across all redrafts |
+| Synthesizer | [cdo](../../agents/cdo.agent.md) | Once, with ALIGNMENT LOOP up to 3 redrafts |
+
+## Topology
+
+```
+   docs-sync SKILL (orchestrator thread)
+                 |
+   Step 1: classify (1 LLM call, may exit here)
+                 |
+                 v
+            verdict?
+            /    |    \
+   no-change  in-place  structural
+       |        |          |
+     EXIT       |       architect (TOC delta)
+                |          |
+                +----<-----+
+                |
+   Step 2: localize (1 LLM call) -- per-page task brief
+                |
+   Step 3: FAN-OUT panel via task tool
+                |
+       +----+----+----+----+
+       v    v    v    v    v
+     writer  verify edit growth
+     x N    x N   once  once
+       (parallel; each <=10 KB context)
+                |
+   Step 4: schema-validate returns
+                |
+   Step 5: CDO synthesize (1 LLM call)
+                |
+            agree?
+            / | \
+        revise (N<=3 redrafts) | agree
+                                  |
+   Step 6: emit ONE comment via safe-outputs.add-comment
+   Step 7: OPTIONAL companion docs PR (only if structural AND
+           `docs-sync-confirm` label present)
+```
+
+## Execution checklist
+
+### Step 1 -- Classify
+
+Spawn ONE task: load the `docs-impact-classifier` skill, pass it the
+PR number. It returns the classifier JSON.
+
+Validate the JSON against `assets/classifier-return-schema.json`.
+On schema failure, abort the run with a comment explaining the
+internal error.
+
+If verdict is `no_change`: skip to Step 6 with a brief advisory
+("No docs impact detected. Reason: <one-line>. LLM calls: 1/15.")
+
+### Step 2 -- Localize (in_place) or Architect (structural)
+
+For `in_place`: spawn ONE task that loads the
+`docs-impact-localizer` skill with the classifier output. Returns
+per-page task briefs.
+
+For `structural`: spawn ONE task that loads the
+`docs-impact-architect` skill with the classifier output. Returns
+TOC delta + new-page outlines + downstream in-place pages. THEN
+spawn the localizer for those downstream pages.
+
+### Step 3 -- Fan-out panel
+
+**Cascade-size mitigation (PR 1244 class).** If `scope_pages[]` has
+>8 entries, the per-page fan-out at one writer call per page would
+approach the 15-call ceiling with no headroom for verifier redrafts.
+BEFORE spawning, group `scope_pages[]` into SECTIONS:
+
+- Pages under the same TOC section (e.g. all `consumer/**`) with the
+  SAME conceptual fix (e.g. "rename apm update -> apm self-update in
+  every mention") become ONE writer task with a `pages_in_section[]`
+  array in its brief.
+- A 9-page rename cascade collapses to 2-3 section writer tasks.
+
+The python-architect verifier still runs per `verify_claims[]` (not
+per page), because S7 evidence is keyed on claims, not pages.
+
+For each page-or-section in the per-page task brief, spawn TWO parallel tasks:
+
+1. **doc-writer** task -- drafts the patch for that page's (or section's) specific edits. Output: JSON with `before:`, `after:` for each location.
+2. **python-architect** task -- for each `verify_claims[]` in the page brief, run the actual command (S7 tool bridge: `apm <verb> --help`, `grep -n <symbol> src/`). Output: JSON with `claim: verified | refuted | inconclusive` per claim.
+
+In parallel with the per-page fan-out, spawn ONCE each:
+
+3. **editorial-owner** task -- receives ALL writer drafts, returns tone fixes.
+4. **oss-growth-hacker** task -- receives ALL writer drafts, returns ramp-clarity notes (does this read well to a cold OSS visitor).
+
+All panelist tasks return JSON matching `assets/panelist-return-schema.json`.
+Schema-validate every return; on failure, abort.
+
+### Step 4 -- Validate
+
+Cross-check:
+
+- Every `verify_claims` from a python-architect comes back `verified` or `inconclusive` (never `refuted`). If any are `refuted`, the doc-writer's draft is wrong; re-run the writer for that page with the refutation as context.
+- Cross-page constraints from the localizer are honored across all writer drafts.
+- All drafts are ASCII-only (per repo encoding rule).
+
+### Step 5 -- CDO synthesize
+
+Spawn ONE task: load the `cdo` persona with the full panel return
+(writer drafts + verifier reports + editorial notes + growth notes
++ classifier verdict + (architect output if structural)) and
+`.apm/docs-index.yml`.
+
+The CDO returns one of three verdicts:
+
+- `agree`: ship. Proceed to Step 6.
+- `revise`: re-spawn the writer panelists with the CDO's specific
+  concerns as additional context. Re-run the editorial and growth
+  passes if needed. Bounded N <= 3 redrafts. Increment a redraft
+  counter; if it hits 3 and CDO still disagrees, ship with
+  `cdo_disagreement_noted: true`.
+- `ship_with_disagreement`: ship as-is with the disagreement
+  surfaced in the comment for the maintainer to weigh.
+
+### Step 6 -- Emit ONE comment
+
+Render `assets/advisory-comment-template.md` with the final results.
+Write it via `safe-outputs.add-comment`. Header is exactly
+`## Docs sync advisory` (stable for idempotent edit-in-place).
+
+The comment MUST include the cost header:
+
+```
+Verdict: <verdict>  *  Pages affected: N  *  LLM calls: M/15  *  Took: Xs
+```
+
+### Step 7 -- Optional companion PR
+
+Only on `structural` verdict AND `docs-sync-confirm` label present
+on the PR (the A9 SUPERVISED EXECUTION boundary; the maintainer
+ratifies the structural proposal before any PR is opened).
+
+If both conditions hold:
+
+1. Branch name: `docs-sync/companion-<PR_NUMBER>` in the BASE repo.
+2. Apply the doc-writer drafts as a commit on that branch.
+3. Apply the architect's TOC delta (`.apm/docs-index.yml` entries +
+   new page files + redirects on retired pages).
+4. Open a draft PR linked to the original PR, with the advisory
+   comment text as the PR body.
+5. Reference the companion PR in the advisory comment.
+
+This step is intentionally GATED. The default behaviour (no
+`docs-sync-confirm` label) is to recommend the patches in the
+comment without opening a PR.
+
+## Cost accounting
+
+The orchestrator maintains a running LLM-call counter:
+
+| Step | Min calls | Max calls |
+|---|---|---|
+| Step 1 classify | 1 | 1 |
+| Step 2 localize/architect | 0 | 2 |
+| Step 3 fan-out (N pages) | 0 | 2N + 2 |
+| Step 5 CDO | 0 | 1 + 3 redrafts |
+| Total | 1 | 15 |
+
+If the counter would exceed 15, the orchestrator stops spawning,
+ships the partial result with `cost_ceiling_hit: true`, and the
+comment surfaces the truncation.
+
+## Anti-patterns
+
+- Reading the corpus instead of the index. Context budget breach.
+- Letting panelists post comments. Single-writer interlock violation.
+- Ignoring `refuted` verify_claims. That's silent drift you're shipping.
+- Skipping the CDO synthesis on "obvious" in-place patches. The bridges still matter.
+- Auto-opening companion PRs without the confirm label. Removes the human ratification.
+- Re-running on every push (synchronize). Wasteful. Re-apply the trigger label for re-run.
+
+## Operating modes
+
+- **Rung 1 (label-gated, default)**: triggered by `docs-sync` label on PR. Maintainer opts in.
+- **Rung 2 (default-on)**: triggered on every `pull_request_target` event. Enabled only after shadow validation.
+
+The workflow file controls which rung is active. The skill body is
+identical for both.
diff --git a/.apm/skills/docs-sync/assets/advisory-comment-template.md b/.apm/skills/docs-sync/assets/advisory-comment-template.md
new file mode 100644
index 000000000..42b40eaa7
--- /dev/null
+++ b/.apm/skills/docs-sync/assets/advisory-comment-template.md
@@ -0,0 +1,106 @@
+## Docs sync advisory
+
+Verdict: **{{ verdict }}**  *  Pages affected: {{ pages_affected_count }}  *  LLM calls: {{ llm_calls_used }}/15  *  Took: {{ elapsed_seconds }}s
+
+{{ #if cost_ceiling_hit }}
+> WARNING: Hit the 15 LLM call ceiling. Result is partial; see `cost_ceiling_hit: true` flag.
+{{ /if }}
+
+{{ #if cdo_disagreement_noted }}
+> NOTE: CDO disagreement after 3 redraft rounds. Maintainer judgement needed; see "Open concerns" below.
+{{ /if }}
+
+### Summary
+
+{{ summary_paragraph }}
+
+{{ #if pages_affected_count == 0 }}
+
+No documentation changes needed for this PR.
+
+{{ classifier_reasoning }}
+
+{{ else }}
+
+### Proposed patches
+
+{{ #each page_patches }}
+
+#### `{{ this.page }}`  ({{ this.persona }} ramp, promise {{ this.promise }})
+
+{{ #each this.sections }}
+
+**Section: {{ this.section }}**  (lines {{ this.line_range }})
+
+```diff
+- {{ this.before }}
++ {{ this.after }}
+```
+
+Rationale: {{ this.rationale }}
+
+{{ #if this.verifications }}
+Verified by: {{ this.verifications }}
+{{ /if }}
+
+{{ /each }}
+
+{{ /each }}
+
+{{ /if }}
+
+{{ #if structural_proposal }}
+
+### Structural proposal
+
+{{ structural_proposal.summary }}
+
+**New pages:**
+
+{{ #each structural_proposal.new_pages }}
+- `{{ this.slug }}` -- {{ this.title }} ({{ this.persona }} ramp). {{ this.rationale }}
+{{ /each }}
+
+**Moved / retired:**
+
+{{ #each structural_proposal.moved_pages }}
+- `{{ this.from }}` -> `{{ this.to }}` ({{ this.redirect_rationale }})
+{{ /each }}
+
+{{ #if structural_proposal.confirm_label_present }}
+
+A companion docs PR has been opened: {{ companion_pr_link }}.
+
+{{ else }}
+
+To open a companion docs PR with these changes, apply the `docs-sync-confirm` label to this PR.
+
+{{ /if }}
+
+{{ /if }}
+
+{{ #if open_concerns }}
+
+### Open concerns (from CDO)
+
+{{ #each open_concerns }}
+- {{ this }}
+{{ /each }}
+
+{{ /if }}
+
+---
+
+<details>
+<summary>How this advisory was produced</summary>
+
+- Classifier verdict: `{{ verdict }}` (confidence: {{ confidence }}, source: {{ classifier_source }})
+- Panel composition: {{ panel_composition }}
+- Tool-verified claims: {{ verification_count }} ({{ verification_pass_count }} verified, {{ verification_refute_count }} refuted, {{ verification_inconclusive_count }} inconclusive)
+- CDO redraft rounds: {{ cdo_redraft_rounds }}/3
+
+This is an advisory comment from the `docs-sync` skill ([source](.apm/skills/docs-sync/SKILL.md)). It does not gate merge. The maintainer ships.
+
+Re-run by removing and re-applying the `docs-sync` label.
+
+</details>
diff --git a/.apm/skills/docs-sync/assets/classifier-return-schema.json b/.apm/skills/docs-sync/assets/classifier-return-schema.json
new file mode 100644
index 000000000..009dfa3cb
--- /dev/null
+++ b/.apm/skills/docs-sync/assets/classifier-return-schema.json
@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "docs-impact-classifier return",
+  "type": "object",
+  "required": ["verdict", "confidence", "reasoning"],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["no_change", "in_place_resolved", "in_place", "structural"],
+      "description": "no_change: no doc impact (true negative). in_place_resolved: doc impact existed but the PR's own diff already patched every affected page (silent success; skill emits NO advisory). in_place: existing pages need edits. structural: TOC change or new page required."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "source": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2"],
+      "description": "Which funnel layer produced the verdict."
+    },
+    "scope_pages": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Candidate doc pages affected. Empty for no_change."
+    },
+    "structural_proposal": {
+      "type": ["object", "null"],
+      "properties": {
+        "new_pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "slug": {"type": "string"},
+              "rationale": {"type": "string"}
+            }
+          }
+        },
+        "moved_pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from": {"type": "string"},
+              "to": {"type": "string"}
+            }
+          }
+        },
+        "toc_changes": {"type": "string"}
+      }
+    },
+    "reasoning": {"type": "string"}
+  }
+}
diff --git a/.apm/skills/docs-sync/assets/panelist-return-schema.json b/.apm/skills/docs-sync/assets/panelist-return-schema.json
new file mode 100644
index 000000000..a2e1d1188
--- /dev/null
+++ b/.apm/skills/docs-sync/assets/panelist-return-schema.json
@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "docs-sync panelist return",
+  "description": "Common shape for all panelist returns (doc-writer, python-architect verifier, editorial-owner, oss-growth-hacker).",
+  "type": "object",
+  "required": ["persona", "page"],
+  "properties": {
+    "persona": {
+      "type": "string",
+      "enum": ["doc-writer", "python-architect", "editorial-owner", "oss-growth-hacker"]
+    },
+    "page": {
+      "type": ["string", "null"],
+      "description": "Path of the page this return covers. Null for editorial-owner/growth-hacker which return cross-page."
+    },
+    "drafts": {
+      "type": "array",
+      "description": "doc-writer only: per-section before/after pairs.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "section": {"type": "string"},
+          "line_range": {"type": "array", "items": {"type": "integer"}},
+          "before": {"type": "string"},
+          "after": {"type": "string"}
+        }
+      }
+    },
+    "verifications": {
+      "type": "array",
+      "description": "python-architect only: claim verification results from S7 tool calls.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "claim": {"type": "string"},
+          "command_run": {"type": "string"},
+          "result": {"type": "string", "enum": ["verified", "refuted", "inconclusive"]},
+          "evidence": {"type": "string"}
+        }
+      }
+    },
+    "tone_fixes": {
+      "type": "array",
+      "description": "editorial-owner only: prose edits with before/after.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "page": {"type": "string"},
+          "before": {"type": "string"},
+          "after": {"type": "string"},
+          "rationale": {"type": "string"}
+        }
+      }
+    },
+    "ramp_notes": {
+      "type": "array",
+      "description": "oss-growth-hacker only: cold-reader observations.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "page": {"type": "string"},
+          "concern": {"type": "string"},
+          "fix": {"type": "string"}
+        }
+      }
+    }
+  }
+}
diff --git a/.apm/skills/docs-sync/evals/README.md b/.apm/skills/docs-sync/evals/README.md
new file mode 100644
index 000000000..175db4ef0
--- /dev/null
+++ b/.apm/skills/docs-sync/evals/README.md
@@ -0,0 +1,35 @@
+# docs-sync evals
+
+This directory holds the eval suite for the `docs-sync` skill, per
+the genesis canonical evals doctrine (MODULE ENTRYPOINT primitive).
+
+## Files
+
+- `trigger-evals.json` -- 20 dispatch evals (10 should-trigger,
+  10 should-NOT-trigger), 60/40 train/val split. The validation
+  split is the ship gate: rate >= 0.5 on should-trigger AND
+  < 0.5 on should-not-trigger.
+
+- `content-evals.json` -- 3 content scenarios (E1 surgical CLI
+  fix, E2 new flag, E3 new package format) exercised
+  with_skill vs without_skill to prove value-delta.
+
+## Ship gates
+
+The skill is ready to graduate from rung 1 (label-gated) to rung 2
+(default-on) when ALL of these pass:
+
+1. Trigger-eval val split: rate >= 0.5 on should-trigger AND
+   < 0.5 on should-not-trigger.
+2. Content evals E1, E2, E3 each produce a measurable value-delta
+   between `with_skill` and `without_skill` runs.
+3. Shadow-run on >= 5 recent real PRs in microsoft/apm with
+   no false-alarm advisories on test-only / CI-only PRs.
+4. Cost ceiling (15 LLM calls) not hit on any shadow-run case.
+
+## Notes
+
+- Eval execution is currently manual. Future: tie into a CI job
+  similar to `apm-review-panel/evals/render_eval.py`.
+- The shadow-run phase is the most important. Synthetic evals
+  cannot fully predict classifier accuracy on real PR diffs.
diff --git a/.apm/skills/docs-sync/evals/content-evals.json b/.apm/skills/docs-sync/evals/content-evals.json
new file mode 100644
index 000000000..487dba7a6
--- /dev/null
+++ b/.apm/skills/docs-sync/evals/content-evals.json
@@ -0,0 +1,74 @@
+{
+  "description": "Content evals for docs-sync. Each scenario is exercised with_skill (docs-sync loaded) and without_skill (no skill, just a generic doc reviewer). If outputs are indistinguishable, the skill is not adding value -- redesign or delete (genesis evals doctrine).",
+  "scenarios": [
+    {
+      "id": "E1-surgical-cli-fix",
+      "label": "Surgical CLI fix -- no doc impact",
+      "setup": {
+        "pr_title": "fix: improve error message when apm install hits 404",
+        "diff_summary": "src/apm_cli/commands/install.py: change one error string from 'package not found' to 'package not found at <url>'",
+        "files_changed": ["src/apm_cli/commands/install.py"],
+        "loc_changed": 3
+      },
+      "expected_verdict": "no_change",
+      "expected_cost_ceiling": 2,
+      "expected_panel_spawns": 0,
+      "value_delta_hypothesis": "Without the skill, a maintainer might wonder if docs need updating; with it, the L0 gate emits a clean 'no impact' advisory in <1 LLM call."
+    },
+    {
+      "id": "E2-new-flag-added",
+      "label": "New flag added -- in-place edit on reference page",
+      "setup": {
+        "pr_title": "feat: add --no-cache flag to apm install",
+        "diff_summary": "src/apm_cli/commands/install.py: add click.option('--no-cache', is_flag=True). Update install logic to bypass the local cache.",
+        "files_changed": ["src/apm_cli/commands/install.py", "src/apm_cli/install/resolver.py"],
+        "loc_changed": 47
+      },
+      "expected_verdict": "in_place",
+      "expected_scope_pages": ["docs/src/content/docs/consumer/install.md"],
+      "expected_cost_ceiling": 8,
+      "expected_panel_spawns": 5,
+      "expected_panel_outputs": [
+        "doc-writer drafts a flag-table entry for --no-cache",
+        "python-architect verifies via `apm install --help` that the flag exists and the description matches the draft",
+        "editorial-owner trims any marketing voice",
+        "growth-hacker checks the flag is mentioned in the consumer ramp, not just the reference",
+        "CDO confirms the patch fits the consumer promise"
+      ],
+      "value_delta_hypothesis": "Without the skill, the flag would ship undocumented and surface in the next user issue ('how do I bypass the cache?'). With the skill, the patch is attached to the PR comment ready to apply."
+    },
+    {
+      "id": "E3-new-package-format",
+      "label": "New package format -- structural change",
+      "setup": {
+        "pr_title": "feat: add wheel format to apm pack",
+        "diff_summary": "src/apm_cli/commands/pack.py: add --format wheel support. New module src/apm_cli/pack/wheel.py. Update apm.yml schema to allow format: wheel.",
+        "files_changed": [
+          "src/apm_cli/commands/pack.py",
+          "src/apm_cli/pack/wheel.py",
+          "src/apm_cli/models/apm_package.py"
+        ],
+        "loc_changed": 312
+      },
+      "expected_verdict": "structural",
+      "expected_structural_proposal": {
+        "new_pages": ["docs/src/content/docs/reference/package-formats/wheel.md"],
+        "in_place_pages": [
+          "docs/src/content/docs/producer/pack-a-bundle.md",
+          "docs/src/content/docs/reference/package-types/index.md"
+        ]
+      },
+      "expected_cost_ceiling": 14,
+      "expected_panel_spawns": 8,
+      "expected_panel_outputs": [
+        "architect proposes new reference page slug, outlines H2 sections, identifies bridges",
+        "doc-writer drafts the new page outline and the in-place edits on the producer ramp",
+        "python-architect verifies via `apm pack --help` that --format wheel exists and runs apm pack --format wheel --dry-run on a fixture",
+        "editorial-owner ensures the new page reads in APM voice",
+        "growth-hacker checks the new format is referenced from the producer ramp index",
+        "CDO arbitrates whether 'wheel' belongs in reference/package-formats/ or producer/pack-a-bundle.md sub-section -- chooses based on 3-promise narrative"
+      ],
+      "value_delta_hypothesis": "Without the skill, the new format would either be undocumented (silent drift) or get one paragraph crammed into producer/pack-a-bundle.md (concept bloat). With the skill, the structural proposal is on the table at PR-open time and the maintainer ratifies via the docs-sync-confirm label."
+    }
+  ]
+}
diff --git a/.apm/skills/docs-sync/evals/trigger-evals.json b/.apm/skills/docs-sync/evals/trigger-evals.json
new file mode 100644
index 000000000..f0d292860
--- /dev/null
+++ b/.apm/skills/docs-sync/evals/trigger-evals.json
@@ -0,0 +1,41 @@
+{
+  "description": "Trigger evals for the docs-sync skill dispatch description. 10 should-trigger + 10 should-NOT-trigger. 60/40 train/val split. Validation split is the ship gate (>=0.5 on should-trigger AND <0.5 on should-not-trigger).",
+  "should_trigger": {
+    "train": [
+      "PR opened: adds --no-cache flag to apm install",
+      "PR opened: renames apm pack to apm bundle",
+      "PR opened: adds new package format wheel to apm pack",
+      "PR opened: removes the deprecated --legacy-resolver flag from apm install",
+      "PR opened: adds new schema field 'registry-proxy-url' to apm.yml",
+      "this PR changes the default value of apm.lock.yaml integrity field"
+    ],
+    "val": [
+      "PR opened: refactors AuthResolver to support new GHE auth method, changes error messages",
+      "PR opened: adds new apm verb 'apm graph' that visualizes dependency tree",
+      "PR opened: changes the format of apm-policy.yml's allowed-sources field",
+      "PR opened: adds new primitive type 'workflow' to the producer authoring surface"
+    ]
+  },
+  "should_not_trigger": {
+    "train": [
+      "PR opened: refactor internal hashing helper, no public API change",
+      "PR opened: add unit tests for AuthResolver edge cases",
+      "PR opened: bump ruff dev dependency to latest",
+      "PR opened: fix typo in CHANGELOG.md",
+      "PR opened: update copilot-setup-steps.yml runner image",
+      "PR opened: rewrite README intro paragraph (docs-only PR)"
+    ],
+    "val": [
+      "PR opened: extract _build_git_env helper into separate module (internal refactor)",
+      "PR opened: fix flaky integration test test_install_concurrent",
+      "PR opened: rewrite docs/src/content/docs/getting-started/quickstart.md (docs-only PR)",
+      "PR opened: update .github/instructions/changelog.instructions.md"
+    ]
+  },
+  "notes": [
+    "Docs-only PRs explicitly do NOT trigger -- docs-sync reviews CODE PRs for docs impact; docs PRs go through doc-writer review separately.",
+    "Pure refactors with no user-observable surface change must NOT trigger -- the L0 path gate should catch them.",
+    "Test-only PRs and CI-only PRs must NOT trigger.",
+    "The classifier may still emit no_change verdict on a borderline case; the dispatch eval here is about whether the SKILL is invoked, not the verdict."
+  ]
+}
diff --git a/.github/agents/cdo.agent.md b/.github/agents/cdo.agent.md
new file mode 100644
index 000000000..7e071ff52
--- /dev/null
+++ b/.github/agents/cdo.agent.md
@@ -0,0 +1,85 @@
+---
+description: >-
+  APM Chief Documentation Officer. Use this agent as the synthesizer
+  and final arbiter for any multi-persona docs panel -- holds the
+  3-promise narrative (consume / produce / govern), the chapter-start
+  and chapter-end bridges, the TOC integrity, and the persona ramps
+  (consumer / producer / enterprise). Activate to synthesize doc-writer
+  + python-architect + editorial-owner + growth-hacker outputs into a
+  ship recommendation, or to evaluate TOC-level proposals.
+model: claude-opus-4.6
+---
+
+# Chief Documentation Officer (CDO)
+
+You are the editorial director of the APM documentation corpus. Your single responsibility is to hold the **narrative coherence** of the docs site at the level of the whole corpus, while the doc-writer holds the page and the editorial-owner holds the paragraph.
+
+You are the **synthesizer** in any docs panel. You don't write paragraphs; you decide whether the panel's collective output lands the narrative.
+
+## The 3-promise narrative
+
+APM ships three promises, in this order, and the corpus structure must reflect them:
+
+1. **Consume primitives** -- `apm install` brings agent primitives (skills, agents, instructions, prompts) into your project. This is the consumer ramp; it's the first thing a new user does.
+2. **Produce primitives** -- `apm pack`, `apm compile`, `apm publish` ship primitives to a marketplace. This is the producer ramp; it requires owning a package.
+3. **Govern primitives** -- `apm audit`, policy enforcement, registry proxies, drift detection. This is the enterprise ramp; it requires team or org scale.
+
+These are the three personas the docs serve. Every page belongs to exactly one of them. Cross-references between them are bridges, not blurs.
+
+## What you arbitrate
+
+When the docs-sync panel returns its outputs (doc-writer redrafts, python-architect verification reports, editorial-owner tone notes, growth-hacker ramp notes), you decide:
+
+1. **Does this land the right promise?** A patch that fits the consumer page but contains producer concepts has leaked. Push back.
+2. **Are the chapter-start and chapter-end bridges coherent?** The last paragraph of `consumer/install.md` should naturally lead the reader who wants to go further. The first paragraph of `producer/index.md` should welcome a consumer who decided to author. If those bridges break, the corpus reads like a pile of pages instead of a journey.
+3. **Does the patch respect progressive disclosure?** Consumer pages don't pre-teach producer concepts. Producer pages don't pre-teach enterprise concepts. Cross-link, don't inline.
+4. **Does the TOC delta (if any) preserve the 3-ramp narrative?** A new page must belong to exactly one ramp. If a contributor proposes a page that straddles two, you split it or rehouse it.
+
+## How you decide (ALIGNMENT LOOP)
+
+The panel runs in a bounded loop:
+
+1. Panel produces drafts + verification + tone + ramp notes.
+2. You synthesize. If you agree: emit final report.
+3. If you disagree: state the disagreement crisply (which paragraph, which promise it leaks, which bridge it breaks). Send it back. The panel revises.
+4. Bounded N <= 3 redrafts. After 3, ship with `cdo_disagreement_noted` flag so the maintainer sees the unresolved tension. Better to surface than to suppress.
+
+You are NOT a perfectionist. The bar is "does this make the corpus more truthful and more cohesive than it was before this PR". Not "is this the ideal paragraph". Ship-with-followups beats ship-never.
+
+## What you do NOT do
+
+- You do NOT verify technical claims (python-architect owns S7 tool bridge for that).
+- You do NOT redraft paragraphs (doc-writer owns the prose).
+- You do NOT tone-check at the paragraph level (editorial-owner owns voice).
+- You do NOT decide PR merge (the maintainer owns that -- you are advisory).
+
+## Output contract when invoked by docs-sync
+
+When the `docs-sync` skill spawns you as the synthesizer task, you operate under strict rules:
+
+- You read the persona scope above, the panel returns, the `.apm/docs-index.yml` index, and the diff context passed in.
+- You return a SINGLE JSON document with this shape:
+
+```json
+{
+  "verdict": "agree" | "revise" | "ship_with_disagreement",
+  "narrative_assessment": "<2-3 sentence summary of whether the patch lands the 3-promise narrative>",
+  "bridge_check": {
+    "chapter_starts_clean": true | false,
+    "chapter_ends_clean": true | false,
+    "notes": "<bridge concerns if any>"
+  },
+  "toc_integrity": "intact" | "drift" | "improved",
+  "revisions_requested": [
+    {"page": "<path>", "concern": "<one-line>", "fix": "<specific>"}
+  ],
+  "ship_recommendation": "<one paragraph: what to publish, what to defer, what to flag>"
+}
+```
+
+- You MUST NOT call `gh pr comment`, `gh pr edit`, or any GitHub write command.
+- Return JSON as the final message of your task. No prose around the JSON.
+
+## The bar
+
+The corpus is a journey, not a pile. Your job is to make sure every PR leaves the journey at least as coherent as it found it.
diff --git a/.github/agents/editorial-owner.agent.md b/.github/agents/editorial-owner.agent.md
new file mode 100644
index 000000000..7d8bfd439
--- /dev/null
+++ b/.github/agents/editorial-owner.agent.md
@@ -0,0 +1,82 @@
+---
+description: >-
+  APM documentation editorial owner. Use this agent for tone, voice,
+  pragmatism, and readability checks across documentation drafts.
+  Activate whenever doc-writer output needs a final tone-and-clarity
+  pass before publishing -- catches bloat, abstract jargon, marketing
+  voice, redundant explanations, and any prose that fails the
+  "stranger reading at 11pm on Friday" test.
+model: claude-opus-4.6
+---
+
+# Editorial Owner
+
+You are the editorial owner for **APM (Agent Package Manager)** documentation. Your single responsibility is to ensure every paragraph that ships under `docs/src/content/docs/` sounds like APM speaks, reads cleanly to a stranger, and earns its words.
+
+You are NOT the technical reviewer (python-architect verifies claims). You are NOT the narrative steward (CDO holds the 3-promise structure). You are the **voice keeper**.
+
+## Tone the docs MUST have
+
+- **Pragmatic, not aspirational.** "Run `apm install` to fetch your dependencies" beats "APM empowers developers to seamlessly orchestrate their primitive ecosystem".
+- **Concrete examples first, generalization second.** Show the user one real command, one real `apm.yml`, then explain the shape. Never lead with abstractions.
+- **One idea per paragraph.** If a paragraph has two thoughts joined by "and" or "furthermore", split it.
+- **Active voice, present tense.** "APM resolves the dependency graph" not "the dependency graph is resolved by APM".
+- **Plain English over jargon.** "package" beats "primitive bundle artifact". When jargon is unavoidable (compile, manifest, lockfile), introduce it once with one sentence, then use it.
+- **Code is the canonical reference; prose explains intent.** Don't paraphrase what the example already shows.
+
+## Anti-patterns you flag and fix
+
+| Smell | Example | Fix |
+|---|---|---|
+| Marketing voice | "Unlock the power of agent primitives" | "Install agent primitives with `apm install`" |
+| Throat-clearing intro | "In this section, we will explore how to..." | Just start with the thing |
+| Abstract first | "APM is a paradigm for..." | Lead with one command + one outcome |
+| Hedging | "You might want to consider perhaps..." | "Run X." or "Don't run X." |
+| Redundant restatement | h1 says X, intro paragraph says X again, then code says X | Delete the intro paragraph |
+| List-of-features wall | "APM supports A, B, C, D, E, F, G..." | Pick the one that matters HERE; cross-link the rest |
+| Tense slip | "You run X. The system will then resolve..." | "You run X. APM resolves..." |
+| Passive distance | "It is recommended that users..." | "Use..." or "Don't use..." |
+| Unexplained acronym | "Configure your MCP via the manifest" (no anchor) | First mention: spell out + link to glossary entry |
+| Wall of prose before code | 4 paragraphs explaining what the example does | One sentence; let the code carry it |
+| "Note:" boxes for things that should be in the text | "Note: This requires Python 3.10" | Inline it where it matters |
+
+## The "stranger at 11pm" test
+
+Read each draft as if you are a new developer who arrived from a Hacker News link at 11pm on a Friday. You skim. You don't read every word. You scan headings, code blocks, and the first sentence of each paragraph.
+
+Ask:
+
+1. **First-sentence test.** Does the first sentence of each paragraph tell me what I'll learn? If I read only first sentences, do I get the gist?
+2. **Code-first test.** Within 30 seconds of landing on the page, am I looking at a real example I could copy-paste?
+3. **Three-question test.** What three questions does the *next page* answer? The current page should not pre-answer them.
+4. **Stranger-vocabulary test.** Every term in the first three paragraphs -- would a competent dev from outside the APM team recognize it without context?
+
+If any answer is no, the draft needs a revision pass.
+
+## ASCII-only constraint
+
+Repo enforces printable ASCII (U+0020-U+007E). Reject any:
+- Emojis
+- Em dashes (U+2014), en dashes (U+2013) -- use `--` or `-` instead
+- Curly quotes (U+2018, U+2019, U+201C, U+201D) -- use straight `'` or `"`
+- Unicode arrows or box-drawing characters
+- Status symbols outside the canonical `[+]`, `[!]`, `[x]`, `[i]`, `[*]`, `[>]` set
+
+This is non-negotiable -- Windows cp1252 terminals will raise `UnicodeEncodeError` and break the CLI for those users.
+
+## Output contract when invoked by docs-sync
+
+When the `docs-sync` skill spawns you as a panelist task, you operate under strict rules:
+
+- You read the persona scope above and the doc draft(s) passed in the task prompt.
+- You return findings in TWO buckets:
+  - `tone_fixes`: specific prose edits with file:line citations. Format each as `BEFORE: "..."` and `AFTER: "..."`.
+  - `editorial_notes`: structural observations (paragraph order, missing examples, redundancy across pages). One-line each.
+- You MUST NOT call `gh pr comment`, `gh pr edit`, or any GitHub write command.
+- You MUST NOT touch the PR state. The orchestrator is the sole writer.
+- Return JSON as the final message of your task. No prose around the JSON.
+- If a draft is already clean, return `{tone_fixes: [], editorial_notes: []}`. That is preferred over inventing nits.
+
+## The bar
+
+Every paragraph ships ONLY if it earns its words. "Would I miss this paragraph if it was deleted?" -- if no, delete it. If yes, why?
diff --git a/.github/workflows/docs-sync.lock.yml b/.github/workflows/docs-sync.lock.yml
new file mode 100644
index 000000000..8a6feaab5
--- /dev/null
+++ b/.github/workflows/docs-sync.lock.yml
@@ -0,0 +1,1558 @@
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"289fa02cf3ae69ffb9040564cff8dcdb4395ea1b60c43caaee3d5e33ba250057","compiler_version":"v0.71.5","strict":true,"agent_id":"copilot"}
+# gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GH_AW_PLUGINS_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"de0fac2e4500dabe0009e67214ff5f5447ce83dd","version":"v6.0.2"},{"repo":"actions/create-github-app-token","sha":"1b10c78c7865c340bc4f6099eb2f838309f1e8c3","version":"v3.1.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"373c709c69115d41ff229c7e5df9f8788daa9553","version":"v9"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7"},{"repo":"github/gh-aw-actions/setup","sha":"b8068426813005612b960b5ab0b8bd2c27142323","version":"v0.71.5"},{"repo":"microsoft/apm-action","sha":"b48dd081eb0050f6d7f32d0e7caa0a59a2d419fd","version":"v1.7.2"},{"repo":"ruby/setup-ruby","sha":"c4e5b1316158f92e3d49443a9d58b31d25ac0f8f","version":"v1.306.0"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.25.40","digest":"sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.25.40@sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.25.40","digest":"sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.25.40@sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.25.40","digest":"sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.25.40@sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.6","digest":"sha256:2bb8eef86006a4c5963c55616a9c51c32f27bfdecb023b8aa6f91f6718d9171c","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.3.6@sha256:2bb8eef86006a4c5963c55616a9c51c32f27bfdecb023b8aa6f91f6718d9171c"},{"image":"ghcr.io/github/github-mcp-server:v1.0.3","digest":"sha256:2ac27ef03461ef2b877031b838a7d1fd7f12b12d4ace7796d8cad91446d55959","pinned_image":"ghcr.io/github/github-mcp-server:v1.0.3@sha256:2ac27ef03461ef2b877031b838a7d1fd7f12b12d4ace7796d8cad91446d55959"},{"image":"node:lts-alpine","digest":"sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f","pinned_image":"node:lts-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f"}]}
+#    ___                   _   _      
+#   / _ \                 | | (_)     
+#  | |_| | __ _  ___ _ __ | |_ _  ___ 
+#  |  _  |/ _` |/ _ \ '_ \| __| |/ __|
+#  | | | | (_| |  __/ | | | |_| | (__ 
+#  \_| |_/\__, |\___|_| |_|\__|_|\___|
+#          __/ |
+#  _    _ |___/ 
+# | |  | |                / _| |
+# | |  | | ___ _ __ _  __| |_| | _____      ____
+# | |/\| |/ _ \ '__| |/ /|  _| |/ _ \ \ /\ / / ___|
+# \  /\  / (_) | | | | ( | | | | (_) \ V  V /\__ \
+#  \/  \/ \___/|_| |_|\_\|_| |_|\___/ \_/\_/ |___/
+#
+# This file was automatically generated by gh-aw (v0.71.5). DO NOT EDIT.
+#
+# To update this file, edit the corresponding .md file and run:
+#   gh aw compile
+# Not all edits will cause changes to this file.
+#
+# For more information: https://github.github.com/gh-aw/introduction/overview/
+#
+# Per-PR documentation impact panel; posts a single advisory recommendation comment.
+#
+# Resolved workflow manifest:
+#   Imports:
+#     - shared/apm.md
+#
+# Secrets used:
+#   - COPILOT_GITHUB_TOKEN
+#   - GH_AW_GITHUB_MCP_SERVER_TOKEN
+#   - GH_AW_GITHUB_TOKEN
+#   - GH_AW_PLUGINS_TOKEN
+#   - GITHUB_TOKEN
+#
+# Custom actions used:
+#   - actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+#   - actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+#   - actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+#   - actions/github-script@373c709c69115d41ff229c7e5df9f8788daa9553 # v9
+#   - actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+#   - actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+#   - actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+#   - actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+#   - github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+#   - microsoft/apm-action@b48dd081eb0050f6d7f32d0e7caa0a59a2d419fd # v1.7.2
+#   - ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+#
+# Container images used:
+#   - ghcr.io/github/gh-aw-firewall/agent:0.25.40@sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504
+#   - ghcr.io/github/gh-aw-firewall/api-proxy:0.25.40@sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280
+#   - ghcr.io/github/gh-aw-firewall/squid:0.25.40@sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51
+#   - ghcr.io/github/gh-aw-mcpg:v0.3.6@sha256:2bb8eef86006a4c5963c55616a9c51c32f27bfdecb023b8aa6f91f6718d9171c
+#   - ghcr.io/github/github-mcp-server:v1.0.3@sha256:2ac27ef03461ef2b877031b838a7d1fd7f12b12d4ace7796d8cad91446d55959
+#   - node:lts-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f
+
+name: "Docs Sync Advisory"
+"on":
+  pull_request_target:
+    types:
+    - labeled
+  # roles: # Roles processed as role check in pre-activation job
+  # - admin # Roles processed as role check in pre-activation job
+  # - maintainer # Roles processed as role check in pre-activation job
+  # - write # Roles processed as role check in pre-activation job
+  workflow_dispatch:
+    inputs:
+      aw_context:
+        default: ""
+        description: Agent caller context (used internally by Agentic Workflows).
+        required: false
+        type: string
+      pr_number:
+        description: Pull request number to assess (works for fork PRs)
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: "gh-aw-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref || github.run_id }}"
+  cancel-in-progress: true
+
+run-name: "Docs Sync Advisory"
+
+jobs:
+  activation:
+    needs: pre_activation
+    if: >
+      needs.pre_activation.outputs.activated == 'true' && (github.event_name == 'workflow_dispatch' || github.event.label.name == 'docs-sync')
+    runs-on: ubuntu-slim
+    permissions:
+      actions: read
+      contents: read
+    outputs:
+      body: ${{ steps.sanitized.outputs.body }}
+      comment_id: ""
+      comment_repo: ""
+      engine_id: ${{ steps.generate_aw_info.outputs.engine_id }}
+      lockdown_check_failed: ${{ steps.generate_aw_info.outputs.lockdown_check_failed == 'true' }}
+      model: ${{ steps.generate_aw_info.outputs.model }}
+      secret_verification_result: ${{ steps.validate-secret.outputs.verification_result }}
+      setup-trace-id: ${{ steps.setup.outputs.trace-id }}
+      stale_lock_file_failed: ${{ steps.check-lock-file.outputs.stale_lock_file_failed == 'true' }}
+      text: ${{ steps.sanitized.outputs.text }}
+      title: ${{ steps.sanitized.outputs.title }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+          trace-id: ${{ needs.pre_activation.outputs.setup-trace-id }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Generate agentic run info
+        id: generate_aw_info
+        env:
+          GH_AW_INFO_ENGINE_ID: "copilot"
+          GH_AW_INFO_ENGINE_NAME: "GitHub Copilot CLI"
+          GH_AW_INFO_MODEL: ${{ vars.GH_AW_MODEL_AGENT_COPILOT || 'claude-sonnet-4.6' }}
+          GH_AW_INFO_VERSION: "1.0.40"
+          GH_AW_INFO_AGENT_VERSION: "1.0.40"
+          GH_AW_INFO_CLI_VERSION: "v0.71.5"
+          GH_AW_INFO_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_INFO_EXPERIMENTAL: "false"
+          GH_AW_INFO_SUPPORTS_TOOLS_ALLOWLIST: "true"
+          GH_AW_INFO_STAGED: "false"
+          GH_AW_INFO_ALLOWED_DOMAINS: '["defaults","github"]'
+          GH_AW_INFO_FIREWALL_ENABLED: "true"
+          GH_AW_INFO_AWF_VERSION: "v0.25.40"
+          GH_AW_INFO_AWMG_VERSION: ""
+          GH_AW_INFO_FIREWALL_TYPE: "squid"
+          GH_AW_COMPILED_STRICT: "true"
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/generate_aw_info.cjs');
+            await main(core, context);
+      - name: Validate COPILOT_GITHUB_TOKEN secret
+        id: validate-secret
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/validate_multi_secret.sh" COPILOT_GITHUB_TOKEN 'GitHub Copilot CLI' https://github.github.com/gh-aw/reference/engines/#github-copilot-default
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      - name: Checkout .github and .agents folders
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .github
+            .agents
+            .claude
+            .codex
+            .crush
+            .gemini
+            .opencode
+            .pi
+          sparse-checkout-cone-mode: true
+          fetch-depth: 1
+      - name: Save agent config folders for base branch restoration
+        env:
+          GH_AW_AGENT_FOLDERS: ".agents .claude .codex .crush .gemini .github .opencode .pi"
+          GH_AW_AGENT_FILES: ".crush.json AGENTS.md CLAUDE.md GEMINI.md PI.md opencode.jsonc"
+        # poutine:ignore untrusted_checkout_exec
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/save_base_github_folders.sh"
+      - name: Check workflow lock file
+        id: check-lock-file
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_WORKFLOW_FILE: "docs-sync.lock.yml"
+          GH_AW_CONTEXT_WORKFLOW_REF: "${{ github.workflow_ref }}"
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/check_workflow_timestamp_api.cjs');
+            await main();
+      - name: Check compile-agentic version
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_COMPILED_VERSION: "v0.71.5"
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/check_version_updates.cjs');
+            await main();
+      - name: Compute current body text
+        id: sanitized
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_ALLOWED_DOMAINS: "*.githubusercontent.com,api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,codeload.github.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,docs.github.com,github-cloud.githubusercontent.com,github-cloud.s3.amazonaws.com,github.blog,github.com,github.githubassets.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,lfs.github.com,objects.githubusercontent.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com,www.googleapis.com"
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/compute_text.cjs');
+            await main();
+      - name: Create prompt with built-in context
+        env:
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+          GH_AW_SAFE_OUTPUTS: ${{ runner.temp }}/gh-aw/safeoutputs/outputs.jsonl
+          GH_AW_EXPR_A0E5D436: ${{ github.event.pull_request.number || inputs.pr_number }}
+          GH_AW_GITHUB_ACTOR: ${{ github.actor }}
+          GH_AW_GITHUB_EVENT_COMMENT_ID: ${{ github.event.comment.id }}
+          GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: ${{ github.event.discussion.number }}
+          GH_AW_GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+          GH_AW_GITHUB_REPOSITORY: ${{ github.repository }}
+          GH_AW_GITHUB_RUN_ID: ${{ github.run_id }}
+          GH_AW_GITHUB_WORKSPACE: ${{ github.workspace }}
+        # poutine:ignore untrusted_checkout_exec
+        run: |
+          bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh"
+          {
+          cat << 'GH_AW_PROMPT_940262bde32bec5c_EOF'
+          <system>
+          GH_AW_PROMPT_940262bde32bec5c_EOF
+          cat "${RUNNER_TEMP}/gh-aw/prompts/xpia.md"
+          cat "${RUNNER_TEMP}/gh-aw/prompts/temp_folder_prompt.md"
+          cat "${RUNNER_TEMP}/gh-aw/prompts/markdown.md"
+          cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_prompt.md"
+          cat << 'GH_AW_PROMPT_940262bde32bec5c_EOF'
+          <safe-output-tools>
+          Tools: add_comment(max:2), remove_labels, missing_tool, missing_data, noop
+          </safe-output-tools>
+          GH_AW_PROMPT_940262bde32bec5c_EOF
+          cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md"
+          cat << 'GH_AW_PROMPT_940262bde32bec5c_EOF'
+          <github-context>
+          The following GitHub context information is available for this workflow:
+          {{#if __GH_AW_GITHUB_ACTOR__ }}
+          - **actor**: __GH_AW_GITHUB_ACTOR__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_REPOSITORY__ }}
+          - **repository**: __GH_AW_GITHUB_REPOSITORY__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_WORKSPACE__ }}
+          - **workspace**: __GH_AW_GITHUB_WORKSPACE__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_EVENT_ISSUE_NUMBER__ }}
+          - **issue-number**: #__GH_AW_GITHUB_EVENT_ISSUE_NUMBER__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER__ }}
+          - **discussion-number**: #__GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER__ }}
+          - **pull-request-number**: #__GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_EVENT_COMMENT_ID__ }}
+          - **comment-id**: __GH_AW_GITHUB_EVENT_COMMENT_ID__
+          {{/if}}
+          {{#if __GH_AW_GITHUB_RUN_ID__ }}
+          - **workflow-run-id**: __GH_AW_GITHUB_RUN_ID__
+          {{/if}}
+          </github-context>
+          
+          GH_AW_PROMPT_940262bde32bec5c_EOF
+          cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md"
+          cat << 'GH_AW_PROMPT_940262bde32bec5c_EOF'
+          </system>
+          
+          
+          
+          {{#runtime-import .github/workflows/docs-sync.md}}
+          GH_AW_PROMPT_940262bde32bec5c_EOF
+          } > "$GH_AW_PROMPT"
+      - name: Interpolate variables and render templates
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+          GH_AW_ENGINE_ID: "copilot"
+          GH_AW_EXPR_A0E5D436: ${{ github.event.pull_request.number || inputs.pr_number }}
+          GH_AW_GITHUB_REPOSITORY: ${{ github.repository }}
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/interpolate_prompt.cjs');
+            await main();
+      - name: Substitute placeholders
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+          GH_AW_EXPR_A0E5D436: ${{ github.event.pull_request.number || inputs.pr_number }}
+          GH_AW_GITHUB_ACTOR: ${{ github.actor }}
+          GH_AW_GITHUB_EVENT_COMMENT_ID: ${{ github.event.comment.id }}
+          GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: ${{ github.event.discussion.number }}
+          GH_AW_GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+          GH_AW_GITHUB_REPOSITORY: ${{ github.repository }}
+          GH_AW_GITHUB_RUN_ID: ${{ github.run_id }}
+          GH_AW_GITHUB_WORKSPACE: ${{ github.workspace }}
+          GH_AW_MCP_CLI_SERVERS_LIST: '- `safeoutputs` — run `safeoutputs --help` to see available tools'
+          GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED: ${{ needs.pre_activation.outputs.activated }}
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            
+            const substitutePlaceholders = require('${{ runner.temp }}/gh-aw/actions/substitute_placeholders.cjs');
+            
+            // Call the substitution function
+            return await substitutePlaceholders({
+              file: process.env.GH_AW_PROMPT,
+              substitutions: {
+                GH_AW_EXPR_A0E5D436: process.env.GH_AW_EXPR_A0E5D436,
+                GH_AW_GITHUB_ACTOR: process.env.GH_AW_GITHUB_ACTOR,
+                GH_AW_GITHUB_EVENT_COMMENT_ID: process.env.GH_AW_GITHUB_EVENT_COMMENT_ID,
+                GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: process.env.GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER,
+                GH_AW_GITHUB_EVENT_ISSUE_NUMBER: process.env.GH_AW_GITHUB_EVENT_ISSUE_NUMBER,
+                GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: process.env.GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER,
+                GH_AW_GITHUB_REPOSITORY: process.env.GH_AW_GITHUB_REPOSITORY,
+                GH_AW_GITHUB_RUN_ID: process.env.GH_AW_GITHUB_RUN_ID,
+                GH_AW_GITHUB_WORKSPACE: process.env.GH_AW_GITHUB_WORKSPACE,
+                GH_AW_MCP_CLI_SERVERS_LIST: process.env.GH_AW_MCP_CLI_SERVERS_LIST,
+                GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED: process.env.GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED
+              }
+            });
+      - name: Validate prompt placeholders
+        env:
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+        # poutine:ignore untrusted_checkout_exec
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/validate_prompt_placeholders.sh"
+      - name: Print prompt
+        env:
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+        # poutine:ignore untrusted_checkout_exec
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/print_prompt_summary.sh"
+      - name: Upload activation artifact
+        if: success()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: activation
+          include-hidden-files: true
+          path: |
+            /tmp/gh-aw/aw_info.json
+            /tmp/gh-aw/aw-prompts/prompt.txt
+            /tmp/gh-aw/github_rate_limits.jsonl
+            /tmp/gh-aw/base
+          if-no-files-found: ignore
+          retention-days: 1
+
+  agent:
+    needs:
+      - activation
+      - apm
+      - apm-prep
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+    env:
+      DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+      GH_AW_ASSETS_ALLOWED_EXTS: ""
+      GH_AW_ASSETS_BRANCH: ""
+      GH_AW_ASSETS_MAX_SIZE_KB: 0
+      GH_AW_MCP_LOG_DIR: /tmp/gh-aw/mcp-logs/safeoutputs
+      GH_AW_WORKFLOW_ID_SANITIZED: docssync
+    outputs:
+      agentic_engine_timeout: ${{ steps.detect-copilot-errors.outputs.agentic_engine_timeout || 'false' }}
+      checkout_pr_success: ${{ steps.checkout-pr.outputs.checkout_pr_success || 'true' }}
+      effective_tokens: ${{ steps.parse-mcp-gateway.outputs.effective_tokens }}
+      has_patch: ${{ steps.collect_output.outputs.has_patch }}
+      inference_access_error: ${{ steps.detect-copilot-errors.outputs.inference_access_error || 'false' }}
+      mcp_policy_error: ${{ steps.detect-copilot-errors.outputs.mcp_policy_error || 'false' }}
+      model: ${{ needs.activation.outputs.model }}
+      model_not_supported_error: ${{ steps.detect-copilot-errors.outputs.model_not_supported_error || 'false' }}
+      output: ${{ steps.collect_output.outputs.output }}
+      output_types: ${{ steps.collect_output.outputs.output_types }}
+      setup-trace-id: ${{ steps.setup.outputs.trace-id }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+          trace-id: ${{ needs.activation.outputs.setup-trace-id }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Set runtime paths
+        id: set-runtime-paths
+        run: |
+          {
+            echo "GH_AW_SAFE_OUTPUTS=${RUNNER_TEMP}/gh-aw/safeoutputs/outputs.jsonl"
+            echo "GH_AW_SAFE_OUTPUTS_CONFIG_PATH=${RUNNER_TEMP}/gh-aw/safeoutputs/config.json"
+            echo "GH_AW_SAFE_OUTPUTS_TOOLS_PATH=${RUNNER_TEMP}/gh-aw/safeoutputs/tools.json"
+          } >> "$GITHUB_OUTPUT"
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+        with:
+          ruby-version: '3.3'
+      - name: Create gh-aw temp directory
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/create_gh_aw_tmp_dir.sh"
+      - name: Configure gh CLI for GitHub Enterprise
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/configure_gh_for_ghe.sh"
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - name: Download APM bundle artifacts (all groups)
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          merge-multiple: false
+          path: /tmp/gh-aw/apm-bundles
+          pattern: ${{ needs.activation.outputs.artifact_prefix }}apm-*
+      - env:
+          ARTIFACT_PREFIX: ${{ needs.activation.outputs.artifact_prefix }}
+          EXPECTED_MATRIX: ${{ needs.apm-prep.outputs.matrix }}
+        name: Normalise bundle layout (single-artifact flatten workaround)
+        run: "set -euo pipefail\n# actions/download-artifact (>=v5) flattens contents directly into `path/`\n# whenever exactly one artifact matches the pattern, ignoring\n# `merge-multiple: false`. Re-shape into the per-group subdir layout so\n# downstream validation sees a stable structure regardless of matrix size.\n# Upstream reference:\n# https://github.com/actions/download-artifact/blob/v8.0.1/src/download-artifact.ts\n# (see the `isSingleArtifactDownload || mergeMultiple || artifacts.length === 1`\n# branch). Remove this step once download-artifact stops flattening or\n# exposes an opt-out.\nexpected_count=$(echo \"$EXPECTED_MATRIX\" | jq '.group // [] | length')\nif [ \"$expected_count\" -eq 1 ]; then\n  group_id=$(echo \"$EXPECTED_MATRIX\" | jq -r '.group[0].id')\n  # Defence-in-depth: group_id is interpolated into a shell path. apm-prep\n  # produces a sanitised id today, but enforce a strict allowlist here so\n  # any future schema drift cannot smuggle traversal sequences.\n  if ! printf '%s' \"$group_id\" | grep -Eq '^[A-Za-z0-9_-]+$'; then\n    echo \"::error::unsafe group_id '$group_id' (must match ^[A-Za-z0-9_-]+$)\"\n    exit 1\n  fi\n  group_dir=\"/tmp/gh-aw/apm-bundles/${ARTIFACT_PREFIX}apm-${group_id}\"\n  if [ ! -d \"$group_dir\" ]; then\n    mkdir -p \"$group_dir\"\n    find /tmp/gh-aw/apm-bundles -mindepth 1 -maxdepth 1 ! -path \"$group_dir\" -exec mv {} \"$group_dir/\" \\;\n  fi\nfi\n"
+      - env:
+          ARTIFACT_PREFIX: ${{ needs.activation.outputs.artifact_prefix }}
+          EXPECTED_MATRIX: ${{ needs.apm-prep.outputs.matrix }}
+        name: Validate downloaded bundles match matrix manifest
+        run: "set -euo pipefail\nexpected=$(echo \"$EXPECTED_MATRIX\" | jq -r --arg prefix \"$ARTIFACT_PREFIX\" '.group | map($prefix + \"apm-\" + .id) | sort | .[]')\nactual=$(ls /tmp/gh-aw/apm-bundles | sort)\nmissing=$(comm -23 <(echo \"$expected\") <(echo \"$actual\") || true)\nunexpected=$(comm -13 <(echo \"$expected\") <(echo \"$actual\") || true)\nif [ -n \"$missing\" ]; then\n  echo \"::error::missing APM bundles (group did not pack successfully): $missing\"\n  exit 1\nfi\nif [ -n \"$unexpected\" ]; then\n  echo \"::error::unexpected artifact in apm bundle download (collision attack?): $unexpected\"\n  exit 1\nfi\n"
+      - id: bundles
+        name: Build bundle list
+        run: "set -euo pipefail\nmapfile -t list < <(find /tmp/gh-aw/apm-bundles -name '*.tar.gz' | sort)\n[ ${#list[@]} -gt 0 ] || { echo '::error::no apm bundles found'; exit 1; }\nprintf '%s\\n' \"${list[@]}\" > /tmp/gh-aw/apm-bundle-list.txt\n"
+      - name: Restore APM packages (all bundles)
+        uses: microsoft/apm-action@b48dd081eb0050f6d7f32d0e7caa0a59a2d419fd # v1.7.2
+        with:
+          bundles-file: /tmp/gh-aw/apm-bundle-list.txt
+
+      - name: Checkout PR branch
+        id: checkout-pr
+        if: |
+          github.event.pull_request || github.event.issue.pull_request
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/checkout_pr_branch.cjs');
+            await main();
+      - name: Install GitHub Copilot CLI
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/install_copilot_cli.sh" 1.0.40
+        env:
+          GH_HOST: github.com
+      - name: Install AWF binary
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/install_awf_binary.sh" v0.25.40
+      - name: Determine automatic lockdown mode for GitHub MCP Server
+        id: determine-automatic-lockdown
+        uses: actions/github-script@373c709c69115d41ff229c7e5df9f8788daa9553 # v9
+        env:
+          GH_AW_GITHUB_TOKEN: ${{ secrets.GH_AW_GITHUB_TOKEN }}
+          GH_AW_GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN }}
+        with:
+          script: |
+            const determineAutomaticLockdown = require('${{ runner.temp }}/gh-aw/actions/determine_automatic_lockdown.cjs');
+            await determineAutomaticLockdown(github, context, core);
+      - name: Download activation artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: activation
+          path: /tmp/gh-aw
+      - name: Restore agent config folders from base branch
+        if: steps.checkout-pr.outcome == 'success'
+        env:
+          GH_AW_AGENT_FOLDERS: ".agents .claude .codex .crush .gemini .github .opencode .pi"
+          GH_AW_AGENT_FILES: ".crush.json AGENTS.md CLAUDE.md GEMINI.md PI.md opencode.jsonc"
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/restore_base_github_folders.sh"
+      - name: Download container images
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/download_docker_images.sh" ghcr.io/github/gh-aw-firewall/agent:0.25.40@sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504 ghcr.io/github/gh-aw-firewall/api-proxy:0.25.40@sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280 ghcr.io/github/gh-aw-firewall/squid:0.25.40@sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51 ghcr.io/github/gh-aw-mcpg:v0.3.6@sha256:2bb8eef86006a4c5963c55616a9c51c32f27bfdecb023b8aa6f91f6718d9171c ghcr.io/github/github-mcp-server:v1.0.3@sha256:2ac27ef03461ef2b877031b838a7d1fd7f12b12d4ace7796d8cad91446d55959 node:lts-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f
+      - name: Generate Safe Outputs Config
+        run: |
+          mkdir -p "${RUNNER_TEMP}/gh-aw/safeoutputs"
+          mkdir -p /tmp/gh-aw/safeoutputs
+          mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_958c8bb971e6a6e0_EOF'
+          {"add_comment":{"max":2},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"remove_labels":{"allowed":["docs-sync"],"max":1},"report_incomplete":{}}
+          GH_AW_SAFE_OUTPUTS_CONFIG_958c8bb971e6a6e0_EOF
+      - name: Generate Safe Outputs Tools
+        env:
+          GH_AW_TOOLS_META_JSON: |
+            {
+              "description_suffixes": {
+                "add_comment": " CONSTRAINTS: Maximum 2 comment(s) can be added. Supports reply_to_id for discussion threading.",
+                "remove_labels": " CONSTRAINTS: Maximum 1 label(s) can be removed. Only these labels can be removed: [docs-sync]."
+              },
+              "repo_params": {},
+              "dynamic_tools": []
+            }
+          GH_AW_VALIDATION_JSON: |
+            {
+              "add_comment": {
+                "defaultMax": 1,
+                "fields": {
+                  "body": {
+                    "required": true,
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 65000
+                  },
+                  "item_number": {
+                    "issueOrPRNumber": true
+                  },
+                  "reply_to_id": {
+                    "type": "string",
+                    "maxLength": 256
+                  },
+                  "repo": {
+                    "type": "string",
+                    "maxLength": 256
+                  }
+                }
+              },
+              "missing_data": {
+                "defaultMax": 20,
+                "fields": {
+                  "alternatives": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 256
+                  },
+                  "context": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 256
+                  },
+                  "data_type": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 128
+                  },
+                  "reason": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 256
+                  }
+                }
+              },
+              "missing_tool": {
+                "defaultMax": 20,
+                "fields": {
+                  "alternatives": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 512
+                  },
+                  "reason": {
+                    "required": true,
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 256
+                  },
+                  "tool": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 128
+                  }
+                }
+              },
+              "noop": {
+                "defaultMax": 1,
+                "fields": {
+                  "message": {
+                    "required": true,
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 65000
+                  }
+                }
+              },
+              "remove_labels": {
+                "defaultMax": 5,
+                "fields": {
+                  "item_number": {
+                    "issueNumberOrTemporaryId": true
+                  },
+                  "labels": {
+                    "required": true,
+                    "type": "array",
+                    "itemType": "string",
+                    "itemSanitize": true,
+                    "itemMaxLength": 128
+                  },
+                  "repo": {
+                    "type": "string",
+                    "maxLength": 256
+                  }
+                }
+              },
+              "report_incomplete": {
+                "defaultMax": 5,
+                "fields": {
+                  "details": {
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 65000
+                  },
+                  "reason": {
+                    "required": true,
+                    "type": "string",
+                    "sanitize": true,
+                    "maxLength": 1024
+                  }
+                }
+              }
+            }
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/generate_safe_outputs_tools.cjs');
+            await main();
+      - name: Generate Safe Outputs MCP Server Config
+        id: safe-outputs-config
+        run: |
+          # Generate a secure random API key (360 bits of entropy, 40+ chars)
+          # Mask immediately to prevent timing vulnerabilities
+          API_KEY=$(openssl rand -base64 45 | tr -d '/+=')
+          echo "::add-mask::${API_KEY}"
+          
+          PORT=3001
+          
+          # Set outputs for next steps
+          {
+            echo "safe_outputs_api_key=${API_KEY}"
+            echo "safe_outputs_port=${PORT}"
+          } >> "$GITHUB_OUTPUT"
+          
+          echo "Safe Outputs MCP server will run on port ${PORT}"
+          
+      - name: Start Safe Outputs MCP HTTP Server
+        id: safe-outputs-start
+        env:
+          DEBUG: '*'
+          GH_AW_SAFE_OUTPUTS: ${{ steps.set-runtime-paths.outputs.GH_AW_SAFE_OUTPUTS }}
+          GH_AW_SAFE_OUTPUTS_PORT: ${{ steps.safe-outputs-config.outputs.safe_outputs_port }}
+          GH_AW_SAFE_OUTPUTS_API_KEY: ${{ steps.safe-outputs-config.outputs.safe_outputs_api_key }}
+          GH_AW_SAFE_OUTPUTS_TOOLS_PATH: ${{ runner.temp }}/gh-aw/safeoutputs/tools.json
+          GH_AW_SAFE_OUTPUTS_CONFIG_PATH: ${{ runner.temp }}/gh-aw/safeoutputs/config.json
+          GH_AW_MCP_LOG_DIR: /tmp/gh-aw/mcp-logs/safeoutputs
+        run: |
+          # Environment variables are set above to prevent template injection
+          export DEBUG
+          export GH_AW_SAFE_OUTPUTS
+          export GH_AW_SAFE_OUTPUTS_PORT
+          export GH_AW_SAFE_OUTPUTS_API_KEY
+          export GH_AW_SAFE_OUTPUTS_TOOLS_PATH
+          export GH_AW_SAFE_OUTPUTS_CONFIG_PATH
+          export GH_AW_MCP_LOG_DIR
+          
+          bash "${RUNNER_TEMP}/gh-aw/actions/start_safe_outputs_server.sh"
+          
+      - name: Start MCP Gateway
+        id: start-mcp-gateway
+        env:
+          GH_AW_SAFE_OUTPUTS: ${{ steps.set-runtime-paths.outputs.GH_AW_SAFE_OUTPUTS }}
+          GH_AW_SAFE_OUTPUTS_API_KEY: ${{ steps.safe-outputs-start.outputs.api_key }}
+          GH_AW_SAFE_OUTPUTS_PORT: ${{ steps.safe-outputs-start.outputs.port }}
+          GITHUB_MCP_GUARD_MIN_INTEGRITY: ${{ steps.determine-automatic-lockdown.outputs.min_integrity }}
+          GITHUB_MCP_GUARD_REPOS: ${{ steps.determine-automatic-lockdown.outputs.repos }}
+          GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -eo pipefail
+          mkdir -p "${RUNNER_TEMP}/gh-aw/mcp-config"
+          
+          # Export gateway environment variables for MCP config and gateway script
+          export MCP_GATEWAY_PORT="8080"
+          export MCP_GATEWAY_DOMAIN="host.docker.internal"
+          export MCP_GATEWAY_HOST_DOMAIN="localhost"
+          MCP_GATEWAY_API_KEY=$(openssl rand -base64 45 | tr -d '/+=')
+          echo "::add-mask::${MCP_GATEWAY_API_KEY}"
+          export MCP_GATEWAY_API_KEY
+          export MCP_GATEWAY_PAYLOAD_DIR="/tmp/gh-aw/mcp-payloads"
+          mkdir -p "${MCP_GATEWAY_PAYLOAD_DIR}"
+          export MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD="524288"
+          export DEBUG="*"
+          
+          export GH_AW_ENGINE="copilot"
+          MCP_GATEWAY_UID=$(id -u 2>/dev/null || echo '0')
+          MCP_GATEWAY_GID=$(id -g 2>/dev/null || echo '0')
+          DOCKER_SOCK_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || echo '0')
+          export MCP_GATEWAY_DOCKER_COMMAND='docker run -i --rm --network host --add-host host.docker.internal:127.0.0.1 --user '"${MCP_GATEWAY_UID}"':'"${MCP_GATEWAY_GID}"' --group-add '"${DOCKER_SOCK_GID}"' -v /var/run/docker.sock:/var/run/docker.sock -e MCP_GATEWAY_PORT -e MCP_GATEWAY_DOMAIN -e MCP_GATEWAY_API_KEY -e MCP_GATEWAY_PAYLOAD_DIR -e MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD -e DEBUG -e MCP_GATEWAY_LOG_DIR -e GH_AW_MCP_LOG_DIR -e GH_AW_SAFE_OUTPUTS -e GH_AW_SAFE_OUTPUTS_CONFIG_PATH -e GH_AW_SAFE_OUTPUTS_TOOLS_PATH -e GH_AW_ASSETS_BRANCH -e GH_AW_ASSETS_MAX_SIZE_KB -e GH_AW_ASSETS_ALLOWED_EXTS -e DEFAULT_BRANCH -e GITHUB_MCP_SERVER_TOKEN -e GITHUB_MCP_GUARD_MIN_INTEGRITY -e GITHUB_MCP_GUARD_REPOS -e GITHUB_REPOSITORY -e GITHUB_SERVER_URL -e GITHUB_SHA -e GITHUB_WORKSPACE -e GITHUB_TOKEN -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RUN_ATTEMPT -e GITHUB_JOB -e GITHUB_ACTION -e GITHUB_EVENT_NAME -e GITHUB_EVENT_PATH -e GITHUB_ACTOR -e GITHUB_ACTOR_ID -e GITHUB_TRIGGERING_ACTOR -e GITHUB_WORKFLOW -e GITHUB_WORKFLOW_REF -e GITHUB_WORKFLOW_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REF_TYPE -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GH_AW_SAFE_OUTPUTS_PORT -e GH_AW_SAFE_OUTPUTS_API_KEY -v /tmp/gh-aw/mcp-payloads:/tmp/gh-aw/mcp-payloads:rw -v /opt:/opt:ro -v /tmp:/tmp:rw -v '"${GITHUB_WORKSPACE}"':'"${GITHUB_WORKSPACE}"':rw ghcr.io/github/gh-aw-mcpg:v0.3.6'
+          
+          mkdir -p /home/runner/.copilot
+          GH_AW_NODE=$(which node 2>/dev/null || command -v node 2>/dev/null || echo node)
+          cat << GH_AW_MCP_CONFIG_47af7b1bafe70d76_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
+          {
+            "mcpServers": {
+              "github": {
+                "type": "stdio",
+                "container": "ghcr.io/github/github-mcp-server:v1.0.3",
+                "env": {
+                  "GITHUB_HOST": "\${GITHUB_SERVER_URL}",
+                  "GITHUB_PERSONAL_ACCESS_TOKEN": "\${GITHUB_MCP_SERVER_TOKEN}",
+                  "GITHUB_READ_ONLY": "1",
+                  "GITHUB_TOOLSETS": "context,repos,issues,pull_requests"
+                },
+                "guard-policies": {
+                  "allow-only": {
+                    "min-integrity": "$GITHUB_MCP_GUARD_MIN_INTEGRITY",
+                    "repos": "$GITHUB_MCP_GUARD_REPOS"
+                  }
+                }
+              },
+              "safeoutputs": {
+                "type": "http",
+                "url": "http://host.docker.internal:$GH_AW_SAFE_OUTPUTS_PORT",
+                "headers": {
+                  "Authorization": "\${GH_AW_SAFE_OUTPUTS_API_KEY}"
+                },
+                "guard-policies": {
+                  "write-sink": {
+                    "accept": [
+                      "*"
+                    ]
+                  }
+                }
+              }
+            },
+            "gateway": {
+              "port": $MCP_GATEWAY_PORT,
+              "domain": "${MCP_GATEWAY_DOMAIN}",
+              "apiKey": "${MCP_GATEWAY_API_KEY}",
+              "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}"
+            }
+          }
+          GH_AW_MCP_CONFIG_47af7b1bafe70d76_EOF
+      - name: Mount MCP servers as CLIs
+        id: mount-mcp-clis
+        continue-on-error: true
+        env:
+          MCP_GATEWAY_API_KEY: ${{ steps.start-mcp-gateway.outputs.gateway-api-key }}
+          MCP_GATEWAY_DOMAIN: ${{ steps.start-mcp-gateway.outputs.gateway-domain }}
+          MCP_GATEWAY_PORT: ${{ steps.start-mcp-gateway.outputs.gateway-port }}
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/mount_mcp_as_cli.cjs');
+            await main();
+      - name: Clean credentials
+        continue-on-error: true
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/clean_git_credentials.sh"
+      - name: Audit pre-agent workspace
+        id: pre_agent_audit
+        continue-on-error: true
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/audit_pre_agent_workspace.sh"
+      - name: Execute GitHub Copilot CLI
+        id: agentic_execution
+        # Copilot CLI tool arguments (sorted):
+        timeout-minutes: 30
+        run: |
+          set -o pipefail
+          touch /tmp/gh-aw/agent-step-summary.md
+          GH_AW_NODE_BIN=$(command -v node 2>/dev/null || true)
+          export GH_AW_NODE_BIN
+          (umask 177 && touch /tmp/gh-aw/agent-stdio.log)
+          printf '%s\n' '{"$schema":"https://github.com/github/gh-aw-firewall/releases/download/v0.25.40/awf-config.schema.json","network":{"allowDomains":["*.githubusercontent.com","api.business.githubcopilot.com","api.enterprise.githubcopilot.com","api.github.com","api.githubcopilot.com","api.individual.githubcopilot.com","api.snapcraft.io","archive.ubuntu.com","azure.archive.ubuntu.com","codeload.github.com","crl.geotrust.com","crl.globalsign.com","crl.identrust.com","crl.sectigo.com","crl.thawte.com","crl.usertrust.com","crl.verisign.com","crl3.digicert.com","crl4.digicert.com","crls.ssl.com","docs.github.com","github-cloud.githubusercontent.com","github-cloud.s3.amazonaws.com","github.blog","github.com","github.githubassets.com","host.docker.internal","json-schema.org","json.schemastore.org","keyserver.ubuntu.com","lfs.github.com","objects.githubusercontent.com","ocsp.digicert.com","ocsp.geotrust.com","ocsp.globalsign.com","ocsp.identrust.com","ocsp.sectigo.com","ocsp.ssl.com","ocsp.thawte.com","ocsp.usertrust.com","ocsp.verisign.com","packagecloud.io","packages.cloud.google.com","packages.microsoft.com","ppa.launchpad.net","raw.githubusercontent.com","registry.npmjs.org","s.symcb.com","s.symcd.com","security.ubuntu.com","telemetry.enterprise.githubcopilot.com","ts-crl.ws.symantec.com","ts-ocsp.ws.symantec.com","www.googleapis.com"]},"apiProxy":{"enabled":true,"models":{"auto":["large"],"deep-research":["copilot/deep-research*","google/deep-research*"],"gemini-flash":["copilot/gemini-*flash*","google/gemini-*flash*"],"gemini-pro":["copilot/gemini-*pro*","google/gemini-*pro*"],"gpt-4.1":["copilot/gpt-4.1*","openai/gpt-4.1*"],"gpt-5":["copilot/gpt-5*","openai/gpt-5*"],"gpt-5-codex":["copilot/gpt-5*codex*","openai/gpt-5*codex*"],"gpt-5-mini":["copilot/gpt-5*mini*","openai/gpt-5*mini*"],"gpt-5-nano":["copilot/gpt-5*nano*","openai/gpt-5*nano*"],"gpt-5-pro":["copilot/gpt-5*pro*","openai/gpt-5*pro*"],"haiku":["copilot/*haiku*","anthropic/*haiku*"],"large":["sonnet","gpt-5-pro","gpt-5","gemini-pro"],"mini":["haiku","gpt-5-mini","gpt-5-nano","gemini-flash"],"opus":["copilot/*opus*","anthropic/*opus*"],"reasoning":["copilot/o1*","copilot/o3*","copilot/o4*","openai/o1*","openai/o3*","openai/o4*"],"small":["mini"],"sonnet":["copilot/*sonnet*","anthropic/*sonnet*"]}},"container":{"imageTag":"0.25.40,squid=sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51,agent=sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504,api-proxy=sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280,cli-proxy=sha256:3e7152911d4b4b7b97beef9d3d7d924ff7902227e86001ef3838fb728d5d514c"}}' > "${RUNNER_TEMP}/gh-aw/awf-config.json" && cp "${RUNNER_TEMP}/gh-aw/awf-config.json" /tmp/gh-aw/awf-config.json
+          # shellcheck disable=SC1003
+          sudo -E awf --config "${RUNNER_TEMP}/gh-aw/awf-config.json" --container-workdir "${GITHUB_WORKSPACE}" --mount "${RUNNER_TEMP}/gh-aw:${RUNNER_TEMP}/gh-aw:ro" --mount "${RUNNER_TEMP}/gh-aw:/host${RUNNER_TEMP}/gh-aw:ro" --env-all --exclude-env COPILOT_GITHUB_TOKEN --exclude-env GITHUB_MCP_SERVER_TOKEN --exclude-env MCP_GATEWAY_API_KEY --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --audit-dir /tmp/gh-aw/sandbox/firewall/audit --enable-host-access --allow-host-ports 80,443,8080 --skip-pull \
+            -- /bin/bash -c 'export PATH="${RUNNER_TEMP}/gh-aw/mcp-cli/bin:$PATH" && export PATH="$(find /opt/hostedtoolcache /home/runner/work/_tool -maxdepth 4 -type d -name bin 2>/dev/null | tr '\''\n'\'' '\'':'\'')$PATH"; [ -n "$GOROOT" ] && export PATH="$GOROOT/bin:$PATH" || true && GH_AW_NODE_EXEC="${GH_AW_NODE_BIN:-}"; if [ -z "$GH_AW_NODE_EXEC" ] || [ ! -x "$GH_AW_NODE_EXEC" ]; then GH_AW_NODE_EXEC="$(command -v node 2>/dev/null || echo node)"; fi; "$GH_AW_NODE_EXEC" ${RUNNER_TEMP}/gh-aw/actions/copilot_harness.cjs /usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --disable-builtin-mcps --no-ask-user --allow-all-tools --allow-all-paths --add-dir "${GITHUB_WORKSPACE}" --prompt-file /tmp/gh-aw/aw-prompts/prompt.txt' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log
+        env:
+          COPILOT_AGENT_RUNNER_TYPE: STANDALONE
+          COPILOT_API_KEY: dummy-byok-key-for-offline-mode
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          COPILOT_MODEL: ${{ vars.GH_AW_MODEL_AGENT_COPILOT || 'claude-sonnet-4.6' }}
+          GH_AW_MCP_CONFIG: /home/runner/.copilot/mcp-config.json
+          GH_AW_PHASE: agent
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+          GH_AW_SAFE_OUTPUTS: ${{ steps.set-runtime-paths.outputs.GH_AW_SAFE_OUTPUTS }}
+          GH_AW_VERSION: v0.71.5
+          GITHUB_API_URL: ${{ github.api_url }}
+          GITHUB_AW: true
+          GITHUB_COPILOT_INTEGRATION_ID: agentic-workflows
+          GITHUB_HEAD_REF: ${{ github.head_ref }}
+          GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_STEP_SUMMARY: /tmp/gh-aw/agent-step-summary.md
+          GITHUB_WORKSPACE: ${{ github.workspace }}
+          GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
+          GIT_AUTHOR_NAME: github-actions[bot]
+          GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+          GIT_COMMITTER_NAME: github-actions[bot]
+          XDG_CONFIG_HOME: /home/runner
+      - name: Detect Copilot errors
+        id: detect-copilot-errors
+        if: always()
+        continue-on-error: true
+        run: node "${RUNNER_TEMP}/gh-aw/actions/detect_copilot_errors.cjs"
+      - name: Copy Copilot session state files to logs
+        if: always()
+        continue-on-error: true
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/copy_copilot_session_state.sh"
+      - name: Stop MCP Gateway
+        if: always()
+        continue-on-error: true
+        env:
+          MCP_GATEWAY_PORT: ${{ steps.start-mcp-gateway.outputs.gateway-port }}
+          MCP_GATEWAY_API_KEY: ${{ steps.start-mcp-gateway.outputs.gateway-api-key }}
+          GATEWAY_PID: ${{ steps.start-mcp-gateway.outputs.gateway-pid }}
+        run: |
+          bash "${RUNNER_TEMP}/gh-aw/actions/stop_mcp_gateway.sh" "$GATEWAY_PID"
+      - name: Redact secrets in logs
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/redact_secrets.cjs');
+            await main();
+        env:
+          GH_AW_SECRET_NAMES: 'COPILOT_GITHUB_TOKEN,GH_AW_GITHUB_MCP_SERVER_TOKEN,GH_AW_GITHUB_TOKEN,GITHUB_TOKEN'
+          SECRET_COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          SECRET_GH_AW_GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN }}
+          SECRET_GH_AW_GITHUB_TOKEN: ${{ secrets.GH_AW_GITHUB_TOKEN }}
+          SECRET_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Append agent step summary
+        if: always()
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/append_agent_step_summary.sh"
+      - name: Copy Safe Outputs
+        if: always()
+        env:
+          GH_AW_SAFE_OUTPUTS: ${{ steps.set-runtime-paths.outputs.GH_AW_SAFE_OUTPUTS }}
+        run: |
+          mkdir -p /tmp/gh-aw
+          cp "$GH_AW_SAFE_OUTPUTS" /tmp/gh-aw/safeoutputs.jsonl 2>/dev/null || true
+      - name: Ingest agent output
+        id: collect_output
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_SAFE_OUTPUTS: ${{ steps.set-runtime-paths.outputs.GH_AW_SAFE_OUTPUTS }}
+          GH_AW_ALLOWED_DOMAINS: "*.githubusercontent.com,api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,codeload.github.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,docs.github.com,github-cloud.githubusercontent.com,github-cloud.s3.amazonaws.com,github.blog,github.com,github.githubassets.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,lfs.github.com,objects.githubusercontent.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com,www.googleapis.com"
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_API_URL: ${{ github.api_url }}
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/collect_ndjson_output.cjs');
+            await main();
+      - name: Parse agent logs for step summary
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: /tmp/gh-aw/sandbox/agent/logs/
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/parse_copilot_log.cjs');
+            await main();
+      - name: Parse MCP Gateway logs for step summary
+        if: always()
+        id: parse-mcp-gateway
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/parse_mcp_gateway_log.cjs');
+            await main();
+      - name: Print firewall logs
+        if: always()
+        continue-on-error: true
+        env:
+          AWF_LOGS_DIR: /tmp/gh-aw/sandbox/firewall/logs
+        run: |
+          # Fix permissions on firewall logs/audit dirs so they can be uploaded as artifacts
+          # AWF runs with sudo, creating files owned by root
+          sudo chmod -R a+r /tmp/gh-aw/sandbox/firewall 2>/dev/null || true
+          # Only run awf logs summary if awf command exists (it may not be installed if workflow failed before install step)
+          if command -v awf &> /dev/null; then
+            awf logs summary | tee -a "$GITHUB_STEP_SUMMARY"
+          else
+            echo 'AWF binary not installed, skipping firewall log summary'
+          fi
+      - name: Parse token usage for step summary
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/parse_token_usage.cjs');
+            await main();
+      - name: Print AWF reflect summary
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/awf_reflect_summary.cjs');
+            await main();
+      - name: Write agent output placeholder if missing
+        if: always()
+        run: |
+          if [ ! -f /tmp/gh-aw/agent_output.json ]; then
+            echo '{"items":[]}' > /tmp/gh-aw/agent_output.json
+          fi
+      - name: Upload agent artifacts
+        if: always()
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: agent
+          path: |
+            /tmp/gh-aw/aw-prompts/prompt.txt
+            /tmp/gh-aw/sandbox/agent/logs/
+            /tmp/gh-aw/redacted-urls.log
+            /tmp/gh-aw/mcp-logs/
+            /tmp/gh-aw/agent_usage.json
+            /tmp/gh-aw/agent-stdio.log
+            /tmp/gh-aw/pre-agent-audit.txt
+            /tmp/gh-aw/agent/
+            /tmp/gh-aw/github_rate_limits.jsonl
+            /tmp/gh-aw/safeoutputs.jsonl
+            /tmp/gh-aw/agent_output.json
+            /tmp/gh-aw/aw-*.patch
+            /tmp/gh-aw/aw-*.bundle
+            /tmp/gh-aw/awf-config.json
+            /tmp/gh-aw/sandbox/firewall/logs/
+            /tmp/gh-aw/sandbox/firewall/audit/
+            /tmp/gh-aw/sandbox/firewall/awf-reflect.json
+          if-no-files-found: ignore
+
+  apm:
+    needs:
+      - activation
+      - apm-prep
+    runs-on: ubuntu-slim
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.apm-prep.outputs.matrix) }}
+    permissions:
+      {}
+
+    steps:
+      - name: Configure GH_HOST for enterprise compatibility
+        id: ghes-host-config
+        shell: bash
+        run: |
+          # Derive GH_HOST from GITHUB_SERVER_URL so the gh CLI targets the correct
+          # GitHub instance (GHES/GHEC). On github.com this is a harmless no-op.
+          GH_HOST="${GITHUB_SERVER_URL#https://}"
+          GH_HOST="${GH_HOST#http://}"
+          echo "GH_HOST=${GH_HOST}" >> "$GITHUB_ENV"
+      - name: Mint installation token
+        id: token
+        if: ${{ matrix.group.app-id != '' }}
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ matrix.group.app-id }}
+          owner: ${{ matrix.group.owner != '' && matrix.group.owner || github.repository_owner }}
+          private-key: ${{ matrix.group.private-key }}
+          repositories: ${{ matrix.group.repositories }}
+      - name: Render package list
+        id: list
+        run: |
+          DEPS=$(echo "$AW_PKG" | jq -r '.[] | "- " + .')
+          {
+            echo "deps<<APMDEPS"
+            printf '%s\n' "$DEPS"
+            echo "APMDEPS"
+          } >> "$GITHUB_OUTPUT"
+        env:
+          AW_PKG: ${{ toJSON(matrix.group.packages) }}
+      - name: Pack APM packages
+        id: pack
+        uses: microsoft/apm-action@b48dd081eb0050f6d7f32d0e7caa0a59a2d419fd # v1.7.2
+        env:
+          GITHUB_TOKEN: ${{ steps.token.outputs.token || secrets.GH_AW_PLUGINS_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+        with:
+          archive: "true"
+          dependencies: ${{ steps.list.outputs.deps }}
+          isolated: "true"
+          pack: "true"
+          target: copilot
+          working-directory: /tmp/gh-aw/apm-workspace
+      - name: Upload APM bundle artifact
+        if: success()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: ${{ needs.activation.outputs.artifact_prefix }}apm-${{ matrix.group.id }}
+          path: ${{ steps.pack.outputs.bundle-path }}
+          retention-days: "1"
+
+  apm-prep:
+    needs: activation
+    runs-on: ubuntu-slim
+    permissions:
+      {}
+
+    outputs:
+      matrix: ${{ steps.compute.outputs.matrix }}
+    steps:
+      - name: Configure GH_HOST for enterprise compatibility
+        id: ghes-host-config
+        shell: bash
+        run: |
+          # Derive GH_HOST from GITHUB_SERVER_URL so the gh CLI targets the correct
+          # GitHub instance (GHES/GHEC). On github.com this is a harmless no-op.
+          GH_HOST="${GITHUB_SERVER_URL#https://}"
+          GH_HOST="${GH_HOST#http://}"
+          echo "GH_HOST=${GH_HOST}" >> "$GITHUB_ENV"
+      - name: Compute APM credential-group matrix
+        id: compute
+        run: |
+          set -euo pipefail
+          packages_json=${AW_APM_PACKAGES:-null}
+          apps_json=${AW_APM_APPS:-null}
+          legacy_id=${AW_APM_LEGACY_APP_ID:-}
+
+          # gh-aw substitutes `["microsoft/apm#main"]` at
+          # compile time using Go's default slice formatter, which emits
+          # `[a b c]` (space-separated, no quotes) instead of valid JSON.
+          # That breaks `jq --argjson` below. Repair string-array inputs
+          # in place; leave already-valid JSON untouched. apps[] (objects)
+          # is not repairable this way -- consumers must use the legacy
+          # single-app inputs until upstream gh-aw exposes a JSON-encoding
+          # helper for import-inputs.
+          repair_string_array() {
+            local raw="$1"
+            if [ -z "$raw" ] || [ "$raw" = "null" ]; then
+              echo "$raw"; return
+            fi
+            if printf '%s' "$raw" | jq -e 'type=="array"' >/dev/null 2>&1; then
+              echo "$raw"; return
+            fi
+            python3 -c 'import json, re, sys; s=sys.argv[1].strip(); s=s[1:-1] if s.startswith("[") and s.endswith("]") else s; print(json.dumps([t for t in re.split(r"[\s,]+", s) if t]))' "$raw"
+          }
+          packages_json=$(repair_string_array "$packages_json")
+
+          groups=$(jq -nc \
+            --argjson packages "$packages_json" \
+            --argjson apps "$apps_json" \
+            --arg legacy_id "$legacy_id" \
+            --arg legacy_pk "${AW_APM_LEGACY_PRIVATE_KEY:-}" \
+            --arg legacy_owner "${AW_APM_LEGACY_OWNER:-}" \
+            --arg legacy_repos "${AW_APM_LEGACY_REPOS:-}" \
+            'def slug(s): s | gsub("[^a-zA-Z0-9-]"; "-") | ascii_downcase | .[0:32];
+             def with_id(g):
+               g + (if (g.id // "") == "" then {id: ("auto-" + slug(g.owner // "default"))} else {} end);
+             [
+               (if (($packages // []) | length) > 0 and $legacy_id == ""
+                  then [{id:"default",("app-id"):"",("private-key"):"",owner:"",repositories:"",packages:$packages}]
+                  else [] end),
+               (if $legacy_id != ""
+                  then [with_id({id:"legacy",("app-id"):$legacy_id,("private-key"):$legacy_pk,owner:$legacy_owner,repositories:$legacy_repos,packages:($packages // [])})]
+                  else [] end),
+               (($apps // []) | map(with_id(.)))
+             ] | add // []')
+
+          count=$(echo "$groups" | jq 'length')
+          if [ "$count" = "0" ]; then
+            echo "::error::shared/apm.md import provided no packages. Add packages: <list>, single-app inputs (app-id + private-key), or apps: <list> in the with: block."
+            exit 1
+          fi
+
+          dups=$(echo "$groups" | jq -r '[.[].id] | group_by(.) | map(select(length > 1) | first) | join(", ")')
+          if [ -n "$dups" ]; then
+            echo "::error::duplicate apm group ids after auto-derivation: $dups. Set apps[].id explicitly when two entries share the same owner."
+            exit 1
+          fi
+
+          while IFS= read -r id; do
+            if ! echo "$id" | grep -Eq '^[a-z0-9-]{1,32}$'; then
+              echo "::error::invalid apm group id: '$id' (lowercase alphanumeric and dashes, 1-32 chars). Set apps[].id explicitly."
+              exit 1
+            fi
+          done < <(echo "$groups" | jq -r '.[].id')
+
+          # SAFE: emit only id + package-count to logs. Never $groups in full.
+          {
+            echo "matrix={\"group\":$groups}"
+          } >> "$GITHUB_OUTPUT"
+          printf "::notice::APM matrix: %d credential group(s)\n" "$count"
+          echo "$groups" | jq -r '.[] | "  - " + .id + " (" + (.packages | length | tostring) + " package(s))"'
+        env:
+          AW_APM_APPS: ${{ github.aw.import-inputs.apps }}
+          AW_APM_LEGACY_APP_ID: ${{ github.aw.import-inputs.app-id }}
+          AW_APM_LEGACY_OWNER: ${{ github.aw.import-inputs.owner }}
+          AW_APM_LEGACY_PRIVATE_KEY: ${{ github.aw.import-inputs.private-key }}
+          AW_APM_LEGACY_REPOS: ${{ github.aw.import-inputs.repositories }}
+          AW_APM_PACKAGES: "[\"microsoft/apm#main\"]"
+
+  conclusion:
+    needs:
+      - activation
+      - agent
+      - apm
+      - apm-prep
+      - detection
+      - safe_outputs
+    if: >
+      always() && (needs.agent.result != 'skipped' || needs.activation.outputs.lockdown_check_failed == 'true' ||
+      needs.activation.outputs.stale_lock_file_failed == 'true')
+    runs-on: ubuntu-slim
+    permissions:
+      contents: read
+      discussions: write
+      issues: write
+      pull-requests: write
+    concurrency:
+      group: "gh-aw-conclusion-docs-sync"
+      cancel-in-progress: false
+    outputs:
+      incomplete_count: ${{ steps.report_incomplete.outputs.incomplete_count }}
+      noop_message: ${{ steps.noop.outputs.noop_message }}
+      tools_reported: ${{ steps.missing_tool.outputs.tools_reported }}
+      total_count: ${{ steps.missing_tool.outputs.total_count }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+          trace-id: ${{ needs.activation.outputs.setup-trace-id }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Download agent output artifact
+        id: download-agent-output
+        continue-on-error: true
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: agent
+          path: /tmp/gh-aw/
+      - name: Setup agent output environment variable
+        id: setup-agent-output-env
+        if: steps.download-agent-output.outcome == 'success'
+        run: |
+          mkdir -p /tmp/gh-aw/
+          find "/tmp/gh-aw/" -type f -print
+          echo "GH_AW_AGENT_OUTPUT=/tmp/gh-aw/agent_output.json" >> "$GITHUB_OUTPUT"
+      - name: Process no-op messages
+        id: noop
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_NOOP_MAX: "1"
+          GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }}
+          GH_AW_NOOP_REPORT_AS_ISSUE: "true"
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/handle_noop_message.cjs');
+            await main();
+      - name: Log detection run
+        id: detection_runs
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          GH_AW_DETECTION_CONCLUSION: ${{ needs.detection.outputs.detection_conclusion }}
+          GH_AW_DETECTION_REASON: ${{ needs.detection.outputs.detection_reason }}
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/handle_detection_runs.cjs');
+            await main();
+      - name: Record missing tool
+        id: missing_tool
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_MISSING_TOOL_CREATE_ISSUE: "true"
+          GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/missing_tool.cjs');
+            await main();
+      - name: Record incomplete
+        id: report_incomplete
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_REPORT_INCOMPLETE_CREATE_ISSUE: "true"
+          GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/report_incomplete_handler.cjs');
+            await main();
+      - name: Handle agent failure
+        id: handle_agent_failure
+        if: always()
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }}
+          GH_AW_WORKFLOW_ID: "docs-sync"
+          GH_AW_ACTION_FAILURE_ISSUE_EXPIRES_HOURS: "168"
+          GH_AW_ENGINE_ID: "copilot"
+          GH_AW_SECRET_VERIFICATION_RESULT: ${{ needs.activation.outputs.secret_verification_result }}
+          GH_AW_CHECKOUT_PR_SUCCESS: ${{ needs.agent.outputs.checkout_pr_success }}
+          GH_AW_INFERENCE_ACCESS_ERROR: ${{ needs.agent.outputs.inference_access_error }}
+          GH_AW_MCP_POLICY_ERROR: ${{ needs.agent.outputs.mcp_policy_error }}
+          GH_AW_AGENTIC_ENGINE_TIMEOUT: ${{ needs.agent.outputs.agentic_engine_timeout }}
+          GH_AW_MODEL_NOT_SUPPORTED_ERROR: ${{ needs.agent.outputs.model_not_supported_error }}
+          GH_AW_ENGINE_API_HOSTS: "api.enterprise.githubcopilot.com,api.githubcopilot.com,api.business.githubcopilot.com,api.individual.githubcopilot.com"
+          GH_AW_LOCKDOWN_CHECK_FAILED: ${{ needs.activation.outputs.lockdown_check_failed }}
+          GH_AW_STALE_LOCK_FILE_FAILED: ${{ needs.activation.outputs.stale_lock_file_failed }}
+          GH_AW_GROUP_REPORTS: "false"
+          GH_AW_FAILURE_REPORT_AS_ISSUE: "true"
+          GH_AW_MISSING_TOOL_REPORT_AS_FAILURE: "true"
+          GH_AW_MISSING_DATA_REPORT_AS_FAILURE: "true"
+          GH_AW_TIMEOUT_MINUTES: "30"
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/handle_agent_failure.cjs');
+            await main();
+
+  detection:
+    needs:
+      - activation
+      - agent
+    if: >
+      always() && needs.agent.result != 'skipped' && (needs.agent.outputs.output_types != '' || needs.agent.outputs.has_patch == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      detection_conclusion: ${{ steps.detection_conclusion.outputs.conclusion }}
+      detection_reason: ${{ steps.detection_conclusion.outputs.reason }}
+      detection_success: ${{ steps.detection_conclusion.outputs.success }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+          trace-id: ${{ needs.activation.outputs.setup-trace-id }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Download agent output artifact
+        id: download-agent-output
+        continue-on-error: true
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: agent
+          path: /tmp/gh-aw/
+      - name: Setup agent output environment variable
+        id: setup-agent-output-env
+        if: steps.download-agent-output.outcome == 'success'
+        run: |
+          mkdir -p /tmp/gh-aw/
+          find "/tmp/gh-aw/" -type f -print
+          echo "GH_AW_AGENT_OUTPUT=/tmp/gh-aw/agent_output.json" >> "$GITHUB_OUTPUT"
+      - name: Checkout repository for patch context
+        if: needs.agent.outputs.has_patch == 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      # --- Threat Detection ---
+      - name: Clean stale firewall files from agent artifact
+        run: |
+          rm -rf /tmp/gh-aw/sandbox/firewall/logs
+          rm -rf /tmp/gh-aw/sandbox/firewall/audit
+      - name: Download container images
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/download_docker_images.sh" ghcr.io/github/gh-aw-firewall/agent:0.25.40@sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504 ghcr.io/github/gh-aw-firewall/api-proxy:0.25.40@sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280 ghcr.io/github/gh-aw-firewall/squid:0.25.40@sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51
+      - name: Check if detection needed
+        id: detection_guard
+        if: always()
+        env:
+          OUTPUT_TYPES: ${{ needs.agent.outputs.output_types }}
+          HAS_PATCH: ${{ needs.agent.outputs.has_patch }}
+        run: |
+          if [[ -n "$OUTPUT_TYPES" || "$HAS_PATCH" == "true" ]]; then
+            echo "run_detection=true" >> "$GITHUB_OUTPUT"
+            echo "Detection will run: output_types=$OUTPUT_TYPES, has_patch=$HAS_PATCH"
+          else
+            echo "run_detection=false" >> "$GITHUB_OUTPUT"
+            echo "Detection skipped: no agent outputs or patches to analyze"
+          fi
+      - name: Clear MCP Config for detection
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        run: |
+          rm -f "${RUNNER_TEMP}/gh-aw/mcp-config/mcp-servers.json"
+          rm -f /home/runner/.copilot/mcp-config.json
+          rm -f "$GITHUB_WORKSPACE/.gemini/settings.json"
+      - name: Prepare threat detection files
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        run: |
+          mkdir -p /tmp/gh-aw/threat-detection/aw-prompts
+          cp /tmp/gh-aw/aw-prompts/prompt.txt /tmp/gh-aw/threat-detection/aw-prompts/prompt.txt 2>/dev/null || true
+          cp /tmp/gh-aw/agent_output.json /tmp/gh-aw/threat-detection/agent_output.json 2>/dev/null || true
+          for f in /tmp/gh-aw/aw-*.patch; do
+            [ -f "$f" ] && cp "$f" /tmp/gh-aw/threat-detection/ 2>/dev/null || true
+          done
+          for f in /tmp/gh-aw/aw-*.bundle; do
+            [ -f "$f" ] && cp "$f" /tmp/gh-aw/threat-detection/ 2>/dev/null || true
+          done
+          echo "Prepared threat detection files:"
+          ls -la /tmp/gh-aw/threat-detection/ 2>/dev/null || true
+      - name: Setup threat detection
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          WORKFLOW_NAME: "Docs Sync Advisory"
+          WORKFLOW_DESCRIPTION: "Per-PR documentation impact panel; posts a single advisory recommendation comment."
+          HAS_PATCH: ${{ needs.agent.outputs.has_patch }}
+        with:
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/setup_threat_detection.cjs');
+            await main();
+      - name: Ensure threat-detection directory and log
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        run: |
+          mkdir -p /tmp/gh-aw/threat-detection
+          touch /tmp/gh-aw/threat-detection/detection.log
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          package-manager-cache: false
+      - name: Install GitHub Copilot CLI
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/install_copilot_cli.sh" 1.0.40
+        env:
+          GH_HOST: github.com
+      - name: Install AWF binary
+        run: bash "${RUNNER_TEMP}/gh-aw/actions/install_awf_binary.sh" v0.25.40
+      - name: Execute GitHub Copilot CLI
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        continue-on-error: true
+        id: detection_agentic_execution
+        # Copilot CLI tool arguments (sorted):
+        timeout-minutes: 20
+        run: |
+          set -o pipefail
+          touch /tmp/gh-aw/agent-step-summary.md
+          GH_AW_NODE_BIN=$(command -v node 2>/dev/null || true)
+          export GH_AW_NODE_BIN
+          (umask 177 && touch /tmp/gh-aw/threat-detection/detection.log)
+          printf '%s\n' '{"$schema":"https://github.com/github/gh-aw-firewall/releases/download/v0.25.40/awf-config.schema.json","network":{"allowDomains":["api.business.githubcopilot.com","api.enterprise.githubcopilot.com","api.github.com","api.githubcopilot.com","api.individual.githubcopilot.com","github.com","host.docker.internal","telemetry.enterprise.githubcopilot.com"]},"apiProxy":{"enabled":true},"container":{"imageTag":"0.25.40,squid=sha256:b084f4a2c771f584ee68084ced52fa6b3245197a1889645d817462d307d3ac51,agent=sha256:14ff567e8d9d4c2fbc5e55c973488381c71d7e0fdbe72d30ee7b8a738fd86504,api-proxy=sha256:2883ca3e5ae9f330cafdd9345bfd4ae17fc8da36c96d4c9a1f76e922b4c45280,cli-proxy=sha256:3e7152911d4b4b7b97beef9d3d7d924ff7902227e86001ef3838fb728d5d514c"}}' > "${RUNNER_TEMP}/gh-aw/awf-config.json" && cp "${RUNNER_TEMP}/gh-aw/awf-config.json" /tmp/gh-aw/awf-config.json
+          # shellcheck disable=SC1003
+          sudo -E awf --config "${RUNNER_TEMP}/gh-aw/awf-config.json" --container-workdir "${GITHUB_WORKSPACE}" --mount "${RUNNER_TEMP}/gh-aw:${RUNNER_TEMP}/gh-aw:ro" --mount "${RUNNER_TEMP}/gh-aw:/host${RUNNER_TEMP}/gh-aw:ro" --env-all --exclude-env COPILOT_GITHUB_TOKEN --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --audit-dir /tmp/gh-aw/sandbox/firewall/audit --enable-host-access --allow-host-ports 80,443,8080 --skip-pull \
+            -- /bin/bash -c 'export PATH="$(find /opt/hostedtoolcache /home/runner/work/_tool -maxdepth 4 -type d -name bin 2>/dev/null | tr '\''\n'\'' '\'':'\'')$PATH"; [ -n "$GOROOT" ] && export PATH="$GOROOT/bin:$PATH" || true && GH_AW_NODE_EXEC="${GH_AW_NODE_BIN:-}"; if [ -z "$GH_AW_NODE_EXEC" ] || [ ! -x "$GH_AW_NODE_EXEC" ]; then GH_AW_NODE_EXEC="$(command -v node 2>/dev/null || echo node)"; fi; "$GH_AW_NODE_EXEC" ${RUNNER_TEMP}/gh-aw/actions/copilot_harness.cjs /usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --disable-builtin-mcps --no-ask-user --allow-all-tools --add-dir "${GITHUB_WORKSPACE}" --prompt-file /tmp/gh-aw/aw-prompts/prompt.txt' 2>&1 | tee -a /tmp/gh-aw/threat-detection/detection.log
+        env:
+          COPILOT_AGENT_RUNNER_TYPE: STANDALONE
+          COPILOT_API_KEY: dummy-byok-key-for-offline-mode
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          COPILOT_MODEL: ${{ vars.GH_AW_MODEL_DETECTION_COPILOT || 'claude-sonnet-4.6' }}
+          GH_AW_PHASE: detection
+          GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
+          GH_AW_VERSION: v0.71.5
+          GITHUB_API_URL: ${{ github.api_url }}
+          GITHUB_AW: true
+          GITHUB_COPILOT_INTEGRATION_ID: agentic-workflows
+          GITHUB_HEAD_REF: ${{ github.head_ref }}
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_STEP_SUMMARY: /tmp/gh-aw/agent-step-summary.md
+          GITHUB_WORKSPACE: ${{ github.workspace }}
+          GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
+          GIT_AUTHOR_NAME: github-actions[bot]
+          GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+          GIT_COMMITTER_NAME: github-actions[bot]
+          XDG_CONFIG_HOME: /home/runner
+      - name: Upload threat detection log
+        if: always() && steps.detection_guard.outputs.run_detection == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: detection
+          path: /tmp/gh-aw/threat-detection/detection.log
+          if-no-files-found: ignore
+      - name: Parse and conclude threat detection
+        id: detection_conclusion
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          RUN_DETECTION: ${{ steps.detection_guard.outputs.run_detection }}
+          GH_AW_DETECTION_CONTINUE_ON_ERROR: "true"
+        with:
+          script: |
+            try {
+              const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+              setupGlobals(core, github, context, exec, io, getOctokit);
+              const { main } = require('${{ runner.temp }}/gh-aw/actions/parse_threat_detection_results.cjs');
+              await main();
+            } catch (loadErr) {
+              const continueOnError = process.env.GH_AW_DETECTION_CONTINUE_ON_ERROR !== 'false';
+              const msg = 'ERR_SYSTEM: \u274C Unexpected error loading threat detection module: ' + (loadErr && loadErr.message ? loadErr.message : String(loadErr));
+              core.error(msg);
+              core.setOutput('reason', 'parse_error');
+              if (continueOnError) {
+                core.warning('\u26A0\uFE0F ' + msg);
+                core.setOutput('conclusion', 'warning');
+                core.setOutput('success', 'false');
+              } else {
+                core.setOutput('conclusion', 'failure');
+                core.setOutput('success', 'false');
+                core.setFailed(msg);
+              }
+            }
+
+  pre_activation:
+    if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'docs-sync'
+    runs-on: ubuntu-slim
+    outputs:
+      activated: ${{ steps.check_membership.outputs.is_team_member == 'true' }}
+      matched_command: ''
+      setup-trace-id: ${{ steps.setup.outputs.trace-id }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Check team membership for workflow
+        id: check_membership
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_REQUIRED_ROLES: "admin,maintainer,write"
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/check_membership.cjs');
+            await main();
+
+  safe_outputs:
+    needs:
+      - activation
+      - agent
+      - detection
+    if: (!cancelled()) && needs.agent.result != 'skipped' && needs.detection.result == 'success'
+    runs-on: ubuntu-slim
+    permissions:
+      contents: read
+      discussions: write
+      issues: write
+      pull-requests: write
+    timeout-minutes: 15
+    env:
+      GH_AW_CALLER_WORKFLOW_ID: "${{ github.repository }}/docs-sync"
+      GH_AW_DETECTION_CONCLUSION: ${{ needs.detection.outputs.detection_conclusion }}
+      GH_AW_DETECTION_REASON: ${{ needs.detection.outputs.detection_reason }}
+      GH_AW_EFFECTIVE_TOKENS: ${{ needs.agent.outputs.effective_tokens }}
+      GH_AW_ENGINE_ID: "copilot"
+      GH_AW_ENGINE_MODEL: ${{ needs.agent.outputs.model }}
+      GH_AW_ENGINE_VERSION: "1.0.40"
+      GH_AW_WORKFLOW_ID: "docs-sync"
+      GH_AW_WORKFLOW_NAME: "Docs Sync Advisory"
+    outputs:
+      code_push_failure_count: ${{ steps.process_safe_outputs.outputs.code_push_failure_count }}
+      code_push_failure_errors: ${{ steps.process_safe_outputs.outputs.code_push_failure_errors }}
+      comment_id: ${{ steps.process_safe_outputs.outputs.comment_id }}
+      comment_url: ${{ steps.process_safe_outputs.outputs.comment_url }}
+      create_discussion_error_count: ${{ steps.process_safe_outputs.outputs.create_discussion_error_count }}
+      create_discussion_errors: ${{ steps.process_safe_outputs.outputs.create_discussion_errors }}
+      process_safe_outputs_processed_count: ${{ steps.process_safe_outputs.outputs.processed_count }}
+      process_safe_outputs_temporary_id_map: ${{ steps.process_safe_outputs.outputs.temporary_id_map }}
+    steps:
+      - name: Setup Scripts
+        id: setup
+        uses: github/gh-aw-actions/setup@b8068426813005612b960b5ab0b8bd2c27142323 # v0.71.5
+        with:
+          destination: ${{ runner.temp }}/gh-aw/actions
+          job-name: ${{ github.job }}
+          trace-id: ${{ needs.activation.outputs.setup-trace-id }}
+        env:
+          GH_AW_SETUP_WORKFLOW_NAME: "Docs Sync Advisory"
+          GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/docs-sync.lock.yml@${{ github.ref }}
+          GH_AW_INFO_VERSION: "1.0.40"
+      - name: Download agent output artifact
+        id: download-agent-output
+        continue-on-error: true
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: agent
+          path: /tmp/gh-aw/
+      - name: Setup agent output environment variable
+        id: setup-agent-output-env
+        if: steps.download-agent-output.outcome == 'success'
+        run: |
+          mkdir -p /tmp/gh-aw/
+          find "/tmp/gh-aw/" -type f -print
+          echo "GH_AW_AGENT_OUTPUT=/tmp/gh-aw/agent_output.json" >> "$GITHUB_OUTPUT"
+      - name: Configure GH_HOST for enterprise compatibility
+        id: ghes-host-config
+        shell: bash
+        run: |
+          # Derive GH_HOST from GITHUB_SERVER_URL so the gh CLI targets the correct
+          # GitHub instance (GHES/GHEC). On github.com this is a harmless no-op.
+          GH_HOST="${GITHUB_SERVER_URL#https://}"
+          GH_HOST="${GH_HOST#http://}"
+          echo "GH_HOST=${GH_HOST}" >> "$GITHUB_ENV"
+      - name: Process Safe Outputs
+        id: process_safe_outputs
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }}
+          GH_AW_ALLOWED_DOMAINS: "*.githubusercontent.com,api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,codeload.github.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,docs.github.com,github-cloud.githubusercontent.com,github-cloud.s3.amazonaws.com,github.blog,github.com,github.githubassets.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,lfs.github.com,objects.githubusercontent.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com,www.googleapis.com"
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_API_URL: ${{ github.api_url }}
+          GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":2},\"create_report_incomplete_issue\":{},\"missing_data\":{},\"missing_tool\":{},\"noop\":{\"max\":1,\"report-as-issue\":\"true\"},\"remove_labels\":{\"allowed\":[\"docs-sync\"],\"max\":1},\"report_incomplete\":{}}"
+        with:
+          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('${{ runner.temp }}/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io, getOctokit);
+            const { main } = require('${{ runner.temp }}/gh-aw/actions/safe_output_handler_manager.cjs');
+            await main();
+      - name: Upload Safe Outputs Items
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: safe-outputs-items
+          path: |
+            /tmp/gh-aw/safe-output-items.jsonl
+            /tmp/gh-aw/temporary-id-map.json
+          if-no-files-found: ignore
+
diff --git a/.github/workflows/docs-sync.md b/.github/workflows/docs-sync.md
new file mode 100644
index 000000000..80915696e
--- /dev/null
+++ b/.github/workflows/docs-sync.md
@@ -0,0 +1,170 @@
+---
+name: Docs Sync Advisory
+description: Per-PR documentation impact panel; posts a single advisory recommendation comment.
+
+# Triggers (cost-gated, fork-safe, GHES-compatible):
+#
+# 1. pull_request_target: fires when a label is applied. We use _target
+#    (NOT plain pull_request) so that fork PRs run in the BASE repo
+#    context with full secrets (COPILOT_GITHUB_TOKEN etc.). gh-aw does
+#    not expose `names:` on `pull_request_target` in v0.68.x (the
+#    first-class `on.labels` filter landed post-v0.71.1 and is not yet
+#    released, see github/gh-aw ADR-28737). To filter by label name
+#    without producing a red-X failed CI check on every unrelated label
+#    change, we use the top-level frontmatter `if:` field below. Same
+#    pattern as `pr-review-panel.md`.
+#
+#    Why pull_request_target is safe here despite the well-known
+#    "pwn-request" pattern:
+#      - permissions are read-only (no write to contents / actions)
+#      - we never `actions/checkout` the PR head; only `gh pr view` /
+#        `gh pr diff` which return inert text
+#      - imports are pinned to microsoft/apm#main (docs-sync skill +
+#        sibling skills + persona definitions are trusted, not from
+#        the PR head)
+#      - write surfaces are tightly scoped:
+#          add-comment max 2 (one advisory + one safety overflow)
+#          remove-labels allowed [docs-sync] max 1
+#            (clear the trigger label so re-applying it re-runs the
+#             skill idempotently)
+#      - companion-PR creation (Step 7 of the skill) requires a
+#        SECOND label `docs-sync-confirm` -- A9 SUPERVISED EXECUTION
+#        boundary. The agent suggests; the maintainer ratifies.
+#      - `roles: [admin, maintainer, write]` ensures only repo
+#        maintainers can trigger -- matches the trust model that
+#        applying the `docs-sync` label requires write access.
+#
+#    `synchronize` is intentionally NOT subscribed at rung 1.
+#    Re-apply the label (remove + add) to re-run after addressing
+#    findings. Rung 2 (default-on) will subscribe to synchronize;
+#    not yet enabled, see .apm/skills/docs-sync/evals/README.md
+#    ship gates.
+#
+# 2. workflow_dispatch: manual fallback. Reads YAML from the dispatched
+#    ref (default main) and accepts any PR number. Useful if a
+#    maintainer needs to re-run without touching labels.
+on:
+  pull_request_target:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "Pull request number to assess (works for fork PRs)"
+        required: true
+        type: string
+  roles: [admin, maintainer, write]
+
+# Label-name gate: skip (not fail) when the triggering label isn't
+# `docs-sync`. gh-aw injects this `if:` into both pre_activation and
+# activation jobs, producing a gray Skipped status for unrelated label
+# changes instead of a red Failed check. workflow_dispatch is always
+# allowed through.
+if: ${{ github.event_name == 'workflow_dispatch' || github.event.label.name == 'docs-sync' }}
+
+# Defense-in-depth against the "pwn request" attack pattern: never check out
+# the PR head. We only consume the diff via `gh pr view` / `gh pr diff` which
+# return inert text. Combined with read-only permissions below, this makes
+# arbitrary code in the PR head physically unreachable from the workflow.
+checkout: false
+
+# Agent job runs READ-ONLY. Safe-output jobs are auto-granted scoped write.
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+
+# Pull docs-sync skill + sibling skills + persona agents from
+# microsoft/apm@main.
+# Why main and not ${{ github.sha }}: a malicious PR could otherwise modify
+# the skill or persona definitions and trick its own review. Pinning to
+# main means the assessment always runs against the trusted, already-
+# reviewed skill -- changes to .apm/ only take effect after they
+# themselves have been reviewed and merged.
+imports:
+  - uses: shared/apm.md
+    with:
+      target: copilot
+      packages:
+        - microsoft/apm#main
+
+tools:
+  github:
+    toolsets: [default]
+  bash: true
+
+network:
+  allowed:
+    - defaults
+    - github
+
+safe-outputs:
+  # Single advisory comment per run. max:2 is a fail-soft ceiling; the
+  # one-comment discipline lives inside the docs-sync skill (idempotent
+  # edit-in-place using the stable `## Docs sync advisory` header).
+  add-comment:
+    max: 2
+  # Label cleanup. The orchestrator removes `docs-sync` so re-applying
+  # the label re-runs the skill idempotently. `docs-sync-confirm` is
+  # NOT swept -- it is the maintainer's ratification signal for the
+  # optional companion PR (see Step 7 of the skill).
+  remove-labels:
+    allowed: [docs-sync]
+    max: 1
+
+timeout-minutes: 30
+---
+
+# Docs Sync Advisory
+
+You are orchestrating the **docs-sync** skill against pull request
+**#${{ github.event.pull_request.number || inputs.pr_number }}** in `${{ github.repository }}`.
+
+> The label-name guard runs at the workflow level via the top-level
+> frontmatter `if:` field (skips both `pre_activation` and `activation`
+> for unrelated labels). If you are reading this prompt, the triggering
+> label is `docs-sync` or this is a manual `workflow_dispatch` --
+> proceed.
+
+## Step 1: Gather PR context (read-only)
+
+Use `gh` CLI -- never `git checkout` of PR head. We are running in the
+base repo context with read-only permissions; the PR diff is the only
+untrusted input we touch, and `gh` returns it as inert data.
+
+```bash
+PR=${{ github.event.pull_request.number || inputs.pr_number }}
+gh pr view "$PR" --json title,body,author,additions,deletions,changedFiles,files,labels
+gh pr diff "$PR"
+gh pr diff "$PR" --name-only
+```
+
+Also check for the `docs-sync-confirm` label on this PR -- it gates
+the optional companion-PR step (Step 7 of the skill).
+
+```bash
+gh pr view "$PR" --json labels --jq '.labels[].name' | grep -q docs-sync-confirm && echo "CONFIRM_PRESENT=true" || echo "CONFIRM_PRESENT=false"
+```
+
+## Step 2: Run the docs-sync skill
+
+Load the **docs-sync** skill and follow its execution checklist
+(Steps 1-7) and output contract exactly. The skill owns:
+
+- Classifier dispatch (the cost gate)
+- Localizer or architect dispatch on in_place / structural verdicts
+- Per-page fan-out panel (doc-writer + python-architect verifier)
+- Editorial-owner and growth-hacker single passes
+- CDO synthesis with bounded ALIGNMENT LOOP (N <= 3 redrafts)
+- Cost ceiling enforcement (15 LLM calls max per run)
+- Single-comment emission via `safe-outputs.add-comment` (NOT the
+  GitHub API directly)
+- Label sweep via `safe-outputs.remove-labels` (drops `docs-sync` so
+  re-applying it re-runs the skill)
+- Companion-PR creation IF AND ONLY IF the `docs-sync-confirm`
+  label is present (the A9 SUPERVISED EXECUTION boundary)
+
+The skill body is at `.apm/skills/docs-sync/SKILL.md` (resolved
+from the import above).
+
+The advisory comment uses the stable header `## Docs sync advisory`
+for idempotent edit-in-place on re-runs.
diff --git a/.gitignore b/.gitignore
index dc9710329..5026da659 100644
--- a/.gitignore
+++ b/.gitignore
@@ -76,3 +76,4 @@ scout-pipeline-result.png
 .cursor/mcp.json
 .playwright-mcp/
 server.pid
+.docs-rewrite-plan/
diff --git a/apm.lock.yaml b/apm.lock.yaml
index 1c7666e82..84da61a45 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -8,6 +8,10 @@ local_deployed_files:
 - .agents/skills/auth
 - .agents/skills/cli-logging-ux
 - .agents/skills/devx-ux
+- .agents/skills/docs-impact-architect
+- .agents/skills/docs-impact-classifier
+- .agents/skills/docs-impact-localizer
+- .agents/skills/docs-sync
 - .agents/skills/oss-growth
 - .agents/skills/pr-description-skill
 - .agents/skills/python-architecture
@@ -16,10 +20,12 @@ local_deployed_files:
 - .github/agents/apm-ceo.agent.md
 - .github/agents/apm-primitives-architect.agent.md
 - .github/agents/auth-expert.agent.md
+- .github/agents/cdo.agent.md
 - .github/agents/cli-logging-expert.agent.md
 - .github/agents/devx-ux-expert.agent.md
 - .github/agents/doc-analyser.agent.md
 - .github/agents/doc-writer.agent.md
+- .github/agents/editorial-owner.agent.md
 - .github/agents/oss-growth-hacker.agent.md
 - .github/agents/python-architect.agent.md
 - .github/agents/supply-chain-security-expert.agent.md
@@ -38,10 +44,12 @@ local_deployed_file_hashes:
   .github/agents/apm-ceo.agent.md: sha256:484da64428ea46a6183dffd3f30c9fc5fc5c747639c0c79e55be69dba0899323
   .github/agents/apm-primitives-architect.agent.md: sha256:6c01eab74ba18d70f21d45010d636cc6535d63cee81da12e61898d8036e0b028
   .github/agents/auth-expert.agent.md: sha256:18264a933cba432b77d133e6ae11eee294c92ed245629af8c9b7a5bb7a9a300c
+  .github/agents/cdo.agent.md: sha256:71e7684942679f86199b6720fc69d52ef796a0ec28981250b9ad275a1ed41d31
   .github/agents/cli-logging-expert.agent.md: sha256:3ed7fe1a2e28e03a40311d4999ef54330908920d6515205708dd3f037abfcf0f
   .github/agents/devx-ux-expert.agent.md: sha256:8310d130cca5bc548baf4a2a84e3c9680c9dc5d83a2718150636896ab2aa1f30
   .github/agents/doc-analyser.agent.md: sha256:47b1d0204904b786c19d4fe84343e86cdab6f92f862f676ba741ffe6e1385679
   .github/agents/doc-writer.agent.md: sha256:328a5b9ea079869b8ccd914a6e2135c204225a5eedb42f59a1ec73058f7f0b47
+  .github/agents/editorial-owner.agent.md: sha256:9dd101a9476dd93b67da1b823cc3b649f1227168fd809b108c74f9304262d860
   .github/agents/oss-growth-hacker.agent.md: sha256:1cd56bb78ab37d52c50e45ab69d759f775cd49cdf35981b3dc6c4004315c6b83
   .github/agents/python-architect.agent.md: sha256:7587ee7c684c61046a83dfa1b7e39d1345f2f119c3395478e3ca2dbbaaaff0e9
   .github/agents/supply-chain-security-expert.agent.md: sha256:8fb8cc426d6af17ba084a28b3f026c2b475b62e3ca63ed2f88b83bd823f877af
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 3a8229bd8..6966d22c3 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -1,6 +1,7 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import sitemap from '@astrojs/sitemap';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import starlightLinksValidator from 'starlight-links-validator';
 import mermaid from 'astro-mermaid';
@@ -9,16 +10,71 @@ import mermaid from 'astro-mermaid';
 export default defineConfig({
 	site: 'https://microsoft.github.io',
 	base: '/apm/',
+	trailingSlash: 'always',
+	prefetch: {
+		prefetchAll: true,
+		defaultStrategy: 'viewport',
+	},
 	redirects: {
+		// Legacy enterprise slugs
 		'/enterprise/teams': '/enterprise/making-the-case',
 		'/enterprise/governance': '/enterprise/governance-guide',
+		// Legacy intro section -> concepts
+		'/introduction/what-is-apm': '/concepts/what-is-apm',
+		'/introduction/why-apm': '/concepts/the-three-promises',
+		'/introduction/how-it-works': '/concepts/lifecycle',
+		'/introduction/key-concepts': '/concepts/glossary',
+		'/introduction/anatomy-of-an-apm-package': '/concepts/package-anatomy',
+		// Legacy getting-started -> persona ramps
+		'/getting-started/quick-start': '/quickstart',
+		'/getting-started/installation': '/quickstart',
+		'/getting-started/authentication': '/consumer/authentication',
+		'/getting-started/migration': '/troubleshooting/migration',
+		// Legacy guides -> consumer/producer ramps
+		'/guides/dependencies': '/consumer/manage-dependencies',
+		'/guides/skills': '/producer/author-primitives/skills',
+		'/guides/prompts': '/producer/author-primitives/prompts',
+		'/guides/agent-workflows': '/producer/author-primitives/instructions-and-agents',
+		'/guides/compilation': '/producer/compile',
+		'/guides/dev-only-primitives': '/producer/author-primitives',
+		'/guides/package-relative-links': '/producer/package-relative-links',
+		'/guides/marketplaces': '/consumer/private-and-org-packages',
+		'/guides/marketplace-authoring': '/producer/publish-to-a-marketplace',
+		'/guides/plugins': '/producer/author-primitives',
+		'/guides/mcp-servers': '/consumer/install-mcp-servers',
+		'/guides/pack-distribute': '/producer',
+		'/guides/private-packages': '/consumer/private-and-org-packages',
+		'/guides/org-packages': '/consumer/private-and-org-packages',
+		'/guides/ci-policy-setup': '/enterprise/enforce-in-ci',
+		'/guides/drift-detection': '/enterprise/drift-detection',
+		// Legacy reference monolith -> per-command
+		'/reference/cli-commands': '/reference/cli/install',
 	},
 	integrations: [
+		sitemap(),
 		mermaid(),
 		starlight({
 			title: 'Agent Package Manager',
-			description: 'An open-source, community-driven dependency manager for AI agents. Declare skills, prompts, instructions, and tools in apm.yml — install with one command.',
+			description: 'An open-source dependency manager for AI agents. Declare skills, prompts, instructions, and tools in apm.yml -- install with one command.',
 			favicon: '/favicon.svg',
+			editLink: {
+				baseUrl: 'https://github.com/microsoft/apm/edit/main/docs/',
+			},
+			lastUpdated: true,
+			head: [
+				{
+					tag: 'meta',
+					attrs: { name: 'theme-color', content: '#1d4ed8' },
+				},
+				{
+					tag: 'meta',
+					attrs: { property: 'og:type', content: 'website' },
+				},
+				{
+					tag: 'meta',
+					attrs: { name: 'twitter:card', content: 'summary_large_image' },
+				},
+			],
 			social: [
 				{ icon: 'github', label: 'GitHub', href: 'https://github.com/microsoft/apm' },
 			],
@@ -29,6 +85,16 @@ export default defineConfig({
 			pagination: true,
 			customCss: ['./src/styles/custom.css'],
 			expressiveCode: {
+				themes: ['github-dark', 'github-light'],
+				styleOverrides: {
+					borderRadius: '0.5rem',
+					borderWidth: '1px',
+					codeFontSize: '0.875rem',
+					codeLineHeight: '1.5',
+					frames: {
+						shadowColor: 'transparent',
+					},
+				},
 				frames: {
 					showCopyToClipboardButton: true,
 				},
@@ -40,80 +106,155 @@ export default defineConfig({
 				}),
 				starlightLlmsTxt({
 					description: 'APM (Agent Package Manager) is an open-source dependency manager for AI agents. It lets you declare skills, prompts, instructions, agents, hooks, plugins, and MCP servers in a single apm.yml manifest, resolving transitive dependencies automatically.',
+					exclude: ['contributing/**'],
+					customSets: [
+						{
+							label: 'Consumer ramp',
+							description: 'How to install and use APM packages in your project.',
+							paths: ['quickstart', 'consumer/**'],
+						},
+						{
+							label: 'Producer ramp',
+							description: 'How to author, validate, and publish APM packages.',
+							paths: ['producer/**', 'getting-started/first-package'],
+						},
+						{
+							label: 'Enterprise ramp',
+							description: 'Policy, audit, and CI gating for platform teams.',
+							paths: ['enterprise/**'],
+						},
+						{
+							label: 'CLI reference',
+							description: 'Per-command reference for the apm CLI.',
+							paths: ['reference/cli/**'],
+						},
+					],
 				}),
 			],
 			sidebar: [
 				{
-					label: 'Understanding APM',
+					label: 'Start here',
 					items: [
-						{ label: 'What is APM?', slug: 'introduction/what-is-apm' },
-						{ label: 'Why APM?', slug: 'introduction/why-apm' },
-						{ label: 'How It Works', slug: 'introduction/how-it-works' },
-						{ label: 'Key Concepts', slug: 'introduction/key-concepts' },
-						{ label: 'Anatomy of an APM Package', slug: 'introduction/anatomy-of-an-apm-package' },
+						{ label: 'Quickstart', slug: 'quickstart' },
+						{ label: 'Your first package', slug: 'getting-started/first-package' },
 					],
 				},
 				{
-					label: 'Getting Started',
+					label: 'Use a package (Consumer)',
 					items: [
-						{ label: 'Installation', slug: 'getting-started/installation' },
-						{ label: 'Quick Start', slug: 'getting-started/quick-start' },
-						{ label: 'Your First Package', slug: 'getting-started/first-package' },
-						{ label: 'Authentication', slug: 'getting-started/authentication' },
-						{ label: 'Existing Projects', slug: 'getting-started/migration' },
+						{ label: 'Overview', slug: 'consumer' },
+						{ label: 'Install packages', slug: 'consumer/install-packages' },
+						{ label: 'Manage dependencies', slug: 'consumer/manage-dependencies' },
+						{ label: 'Run scripts', slug: 'consumer/run-scripts' },
+						{ label: 'Update and refresh', slug: 'consumer/update-and-refresh' },
+						{ label: 'Install MCP servers', slug: 'consumer/install-mcp-servers' },
+						{ label: 'Authentication', slug: 'consumer/authentication' },
+						{ label: 'Private and org packages', slug: 'consumer/private-and-org-packages' },
+						{ label: 'Deploy a local bundle', slug: 'consumer/deploy-a-bundle' },
+						{ label: 'Drift and secure-by-default', slug: 'consumer/drift-and-secure-by-default' },
+						{ label: 'Governance on the consumer ramp', slug: 'consumer/governance-on-the-consumer-ramp' },
 					],
 				},
 				{
-					label: 'Guides',
+					label: 'Author a package (Producer)',
 					items: [
-						{ label: 'Compilation & Optimization', slug: 'guides/compilation' },
-						{ label: 'Skills', slug: 'guides/skills' },
-						{ label: 'Prompts', slug: 'guides/prompts' },
-						{ label: 'Plugins', slug: 'guides/plugins' },
-						{ label: 'MCP Servers', slug: 'guides/mcp-servers' },
-						{ label: 'Dependencies & Lockfile', slug: 'guides/dependencies' },
-						{ label: 'Pack & Distribute', slug: 'guides/pack-distribute' },
-						{ label: 'Private Packages', slug: 'guides/private-packages' },
-						{ label: 'Org-Wide Packages', slug: 'guides/org-packages' },
-						{ label: 'Marketplaces', slug: 'guides/marketplaces' },
-						{ label: 'Marketplace Authoring', slug: 'guides/marketplace-authoring' },
-						{ label: 'CI Policy Enforcement', slug: 'guides/ci-policy-setup' },
-						{ label: 'Agent Workflows (Experimental)', slug: 'guides/agent-workflows' },
+						{ label: 'Overview', slug: 'producer' },
+						{
+							label: 'Author primitives',
+							items: [
+								{ label: 'Overview', slug: 'producer/author-primitives' },
+								{ label: 'Skills', slug: 'producer/author-primitives/skills' },
+								{ label: 'Prompts', slug: 'producer/author-primitives/prompts' },
+								{ label: 'Instructions and agents', slug: 'producer/author-primitives/instructions-and-agents' },
+								{ label: 'Hooks and commands', slug: 'producer/author-primitives/hooks-and-commands' },
+								{ label: 'MCP as a primitive', slug: 'producer/author-primitives/mcp-as-primitive' },
+							],
+						},
+						{ label: 'Compile your package', slug: 'producer/compile' },
+						{ label: 'Preview and validate', slug: 'producer/preview-and-validate' },
+						{ label: 'Pack a bundle', slug: 'producer/pack-a-bundle' },
+						{ label: 'Publish to a marketplace', slug: 'producer/publish-to-a-marketplace' },
+						{ label: 'Package-relative links', slug: 'producer/package-relative-links' },
 					],
 				},
 				{
-					label: 'Troubleshooting',
+					label: 'Govern at scale (Enterprise)',
 					items: [
-						{ label: 'SSL / TLS issues', slug: 'troubleshooting/ssl-issues' },
+						{ label: 'Overview', slug: 'enterprise' },
+						{ label: 'Making the case', slug: 'enterprise/making-the-case' },
+						{ label: 'Adoption playbook', slug: 'enterprise/adoption-playbook' },
+						{ label: 'Governance overview', slug: 'enterprise/governance-overview' },
+						{ label: 'Governance guide', slug: 'enterprise/governance-guide' },
+						{ label: 'Policy: getting started', slug: 'enterprise/apm-policy-getting-started' },
+						{ label: 'Policy pilot', slug: 'enterprise/policy-pilot' },
+						{ label: 'Policy files', slug: 'enterprise/apm-policy' },
+						{ label: 'Policy reference', slug: 'enterprise/policy-reference' },
+						{ label: 'Enforce in CI', slug: 'enterprise/enforce-in-ci' },
+						{ label: 'Security model', slug: 'enterprise/security' },
+						{ label: 'Security and supply chain', slug: 'enterprise/security-and-supply-chain' },
+						{ label: 'Drift detection', slug: 'enterprise/drift-detection' },
+						{ label: 'Registry proxy and air-gapped', slug: 'enterprise/registry-proxy' },
+						{ label: 'GitHub rulesets', slug: 'enterprise/github-rulesets' },
 					],
 				},
 				{
-					label: 'Enterprise',
+					label: 'Integrations',
 					items: [
-						{ label: 'Enterprise', slug: 'enterprise' },
-						{ label: 'Making the Case', slug: 'enterprise/making-the-case' },
-						{ label: 'Adoption Playbook', slug: 'enterprise/adoption-playbook' },
-						{ label: 'Security Model', slug: 'enterprise/security' },
-						{ label: 'Governance', slug: 'enterprise/governance-guide' },
-						{ label: 'Registry Proxy & Air-gapped', slug: 'enterprise/registry-proxy' },
-						{ label: 'Policy Files', slug: 'enterprise/apm-policy' },
-						{ label: 'Policy Reference', slug: 'enterprise/policy-reference' },
+						{ label: 'IDE and tool integration', slug: 'integrations/ide-tool-integration' },
+						{ label: 'CI/CD pipelines', slug: 'integrations/ci-cd' },
+						{ label: 'GitHub Agentic Workflows', slug: 'integrations/gh-aw' },
+						{ label: 'Microsoft 365 Copilot Cowork (Experimental)', slug: 'integrations/copilot-cowork' },
+						{ label: 'AI runtime compatibility', slug: 'integrations/runtime-compatibility' },
+						{ label: 'GitHub rulesets', slug: 'integrations/github-rulesets' },
 					],
 				},
 				{
-					label: 'Integrations',
+					label: 'CLI reference',
 					items: [
-						{ label: 'CI/CD Pipelines', slug: 'integrations/ci-cd' },
-						{ label: 'GitHub Agentic Workflows', slug: 'integrations/gh-aw' },
-						{ label: 'IDE & Tool Integration', slug: 'integrations/ide-tool-integration' },
-						{ label: 'Microsoft 365 Copilot Cowork (Experimental)', slug: 'integrations/copilot-cowork' },
-						{ label: 'AI Runtime Compatibility', slug: 'integrations/runtime-compatibility' },
-						{ label: 'GitHub Rulesets', slug: 'integrations/github-rulesets' },
+						{ label: 'Overview', slug: 'reference' },
+						{
+							label: 'Commands',
+							autogenerate: { directory: 'reference/cli' },
+						},
+					],
+				},
+				{
+					label: 'Schemas and specs',
+					items: [
+						{ label: 'Manifest schema', slug: 'reference/manifest-schema' },
+						{ label: 'Lockfile spec', slug: 'reference/lockfile-spec' },
+						{ label: 'Policy schema', slug: 'reference/policy-schema' },
+						{ label: 'Targets matrix', slug: 'reference/targets-matrix' },
+						{ label: 'Primitive types', slug: 'reference/primitive-types' },
+						{ label: 'Package types', slug: 'reference/package-types' },
+						{ label: 'Baseline checks', slug: 'reference/baseline-checks' },
+						{ label: 'Environment variables', slug: 'reference/environment-variables' },
+						{ label: 'Examples', slug: 'reference/examples' },
+						{ label: 'Experimental', slug: 'reference/experimental' },
 					],
 				},
 				{
-					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					label: 'Concepts',
+					items: [
+						{ label: 'What is APM?', slug: 'concepts/what-is-apm' },
+						{ label: 'The three promises', slug: 'concepts/the-three-promises' },
+						{ label: 'Lifecycle', slug: 'concepts/lifecycle' },
+						{ label: 'Primitives and targets', slug: 'concepts/primitives-and-targets' },
+						{ label: 'Package anatomy', slug: 'concepts/package-anatomy' },
+						{ label: 'Glossary', slug: 'concepts/glossary' },
+					],
+				},
+				{
+					label: 'Troubleshooting',
+					items: [
+						{ label: 'Overview', slug: 'troubleshooting' },
+						{ label: 'Common errors', slug: 'troubleshooting/common-errors' },
+						{ label: 'Install failures', slug: 'troubleshooting/install-failures' },
+						{ label: 'Compile produced no output', slug: 'troubleshooting/compile-zero-output-warning' },
+						{ label: 'Policy debugging', slug: 'troubleshooting/policy-debugging' },
+						{ label: 'SSL / TLS issues', slug: 'troubleshooting/ssl-issues' },
+						{ label: 'Migration paths', slug: 'troubleshooting/migration' },
+					],
 				},
 				{
 					label: 'Contributing',
diff --git a/docs/package-lock.json b/docs/package-lock.json
index 364f65348..3f13ff402 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -8,6 +8,7 @@
       "name": "apm-docs",
       "version": "0.0.1",
       "dependencies": {
+        "@astrojs/sitemap": "^3.7.2",
         "@astrojs/starlight": "0.38.4",
         "astro": "6.2.1",
         "astro-mermaid": "^2.0.1",
@@ -254,45 +255,10 @@
         "node": ">=18"
       }
     },
-    "node_modules/@chevrotain/cst-dts-gen": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
-      "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
-      "license": "Apache-2.0",
-      "peer": true,
-      "dependencies": {
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/gast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
-      "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
-      "license": "Apache-2.0",
-      "peer": true,
-      "dependencies": {
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/regexp-to-ast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
-      "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==",
-      "license": "Apache-2.0",
-      "peer": true
-    },
     "node_modules/@chevrotain/types": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
-      "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==",
-      "license": "Apache-2.0",
-      "peer": true
-    },
-    "node_modules/@chevrotain/utils": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
-      "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==",
+      "version": "11.1.2",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
+      "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
       "license": "Apache-2.0",
       "peer": true
     },
@@ -889,15 +855,15 @@
       "peer": true
     },
     "node_modules/@iconify/utils": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.1.1.tgz",
-      "integrity": "sha512-MwzoDtw9rO1x+qfgLTV/IVXsHDBqeYZoMIQC8SfxfYSlaSUG+oWiAcoiB1yajAda6mqblm4/1/w2E8tRu7a7Tw==",
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.1.3.tgz",
+      "integrity": "sha512-LPKOXPn/zV+zis1oOfGWogaXVpqUybF3ZS6SCZIsz8vg0ivVp9+fVqyYB7xq0aiST/VhUQYGO1qo6uoYSiEJqw==",
       "license": "MIT",
       "peer": true,
       "dependencies": {
         "@antfu/install-pkg": "^1.1.0",
         "@iconify/types": "^2.0.0",
-        "mlly": "^1.8.2"
+        "import-meta-resolve": "^4.2.0"
       }
     },
     "node_modules/@img/colour": {
@@ -1457,13 +1423,13 @@
       }
     },
     "node_modules/@mermaid-js/parser": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
-      "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.1.tgz",
+      "integrity": "sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==",
       "license": "MIT",
       "peer": true,
       "dependencies": {
-        "langium": "^4.0.0"
+        "@chevrotain/types": "~11.1.1"
       }
     },
     "node_modules/@oslojs/encoding": {
@@ -1598,9 +1564,9 @@
       "license": "MIT"
     },
     "node_modules/@rollup/rollup-android-arm-eabi": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.2.tgz",
-      "integrity": "sha512-dnlp69efPPg6Uaw2dVqzWRfAWRnYVb1XJ8CyyhIbZeaq4CA5/mLeZ1IEt9QqQxmbdvagjLIm2ZL8BxXv5lH4Yw==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.3.tgz",
+      "integrity": "sha512-x35CNW/ANXG3hE/EZpRU8MXX1JDN86hBb2wMGAtltkz7pc6cxgjpy1OMMfDosOQ+2hWqIkag/fGok1Yady9nGw==",
       "cpu": [
         "arm"
       ],
@@ -1611,9 +1577,9 @@
       ]
     },
     "node_modules/@rollup/rollup-android-arm64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.2.tgz",
-      "integrity": "sha512-OqZTwDRDchGRHHm/hwLOL7uVPB9aUvI0am/eQuWMNyFHf5PSEQmyEeYYheA0EPPKUO/l0uigCp+iaTjoLjVoHg==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.3.tgz",
+      "integrity": "sha512-xw3xtkDApIOGayehp2+Rz4zimfkaX65r4t47iy+ymQB2G4iJCBBfj0ogVg5jpvjpn8UWn/+q9tprxleYeNp3Hw==",
       "cpu": [
         "arm64"
       ],
@@ -1624,9 +1590,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-arm64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.2.tgz",
-      "integrity": "sha512-UwRE7CGpvSVEQS8gUMBe1uADWjNnVgP3Iusyda1nSRwNDCsRjnGc7w6El6WLQsXmZTbLZx9cecegumcitNfpmA==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.3.tgz",
+      "integrity": "sha512-vo6Y5Qfpx7/5EaamIwi0WqW2+zfiusVihKatLvtN1VFVy3D13uERk/6gZLU1UiHRL6fDXqj/ELIeVRGnvcTE1g==",
       "cpu": [
         "arm64"
       ],
@@ -1637,9 +1603,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-x64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.2.tgz",
-      "integrity": "sha512-gjEtURKLCC5VXm1I+2i1u9OhxFsKAQJKTVB8WvDAHF+oZlq0GTVFOlTlO1q3AlCTE/DF32c16ESvfgqR7343/g==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.3.tgz",
+      "integrity": "sha512-D+0QGcZhBzTN82weOnsSlY7V7+RMmPuF1CkbxyMAGE8+ZHeUjyb76ZiWmBlCu//AQQONvxcqRbwZTajZKqjuOw==",
       "cpu": [
         "x64"
       ],
@@ -1650,9 +1616,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-arm64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.2.tgz",
-      "integrity": "sha512-Bcl6CYDeAgE70cqZaMojOi/eK63h5Me97ZqAQoh77VPjMysA/4ORQBRGo3rRy45x4MzVlU9uZxs8Uwy7ZaKnBw==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.3.tgz",
+      "integrity": "sha512-6HnvHCT7fDyj6R0Ph7A6x8dQS/S38MClRWeDLqc0MdfWkxjiu1HSDYrdPhqSILzjTIC/pnXbbJbo+ft+gy/9hQ==",
       "cpu": [
         "arm64"
       ],
@@ -1663,9 +1629,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-x64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.2.tgz",
-      "integrity": "sha512-LU+TPda3mAE2QB0/Hp5VyeKJivpC6+tlOXd1VMoXV/YFMvk/MNk5iXeBfB4MQGRWyOYVJ01625vjkr0Az98OJQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.3.tgz",
+      "integrity": "sha512-KHLgC3WKlUYW3ShFKnnosZDOJ0xjg9zp7au3sIm2bs/tGBeC2ipmvRh/N7JKi0t9Ue20C0dpEshi8WUubg+cnA==",
       "cpu": [
         "x64"
       ],
@@ -1676,9 +1642,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.2.tgz",
-      "integrity": "sha512-2QxQrM+KQ7DAW4o22j+XZ6RKdxjLD7BOWTP0Bv0tmjdyhXSsr2Ul1oJDQqh9Zf5qOwTuTc7Ek83mOFaKnodPjg==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.3.tgz",
+      "integrity": "sha512-DV6fJoxEYWJOvaZIsok7KrYl0tPvga5OZ2yvKHNNYyk/2roMLqQAbGhr78EQ5YhHpnhLKJD3S1WFusAkmUuV5g==",
       "cpu": [
         "arm"
       ],
@@ -1692,9 +1658,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.2.tgz",
-      "integrity": "sha512-TbziEu2DVsTEOPif2mKWkMeDMLoYjx95oESa9fkQQK7r/Orta0gnkcDpzwufEcAO2BLBsD7mZkXGFqEdMRRwfw==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.3.tgz",
+      "integrity": "sha512-mQKoJAzvuOs6F+TZybQO4GOTSMUu7v0WdxEk24krQ/uUxXoPTtHjuaUuPmFhtBcM4K0ons8nrE3JyhTuCFtT/w==",
       "cpu": [
         "arm"
       ],
@@ -1708,9 +1674,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.2.tgz",
-      "integrity": "sha512-bO/rVDiDUuM2YfuCUwZ1t1cP+/yqjqz+Xf2VtkdppefuOFS2OSeAfgafaHNkFn0t02hEyXngZkxtGqXcXwO8Rg==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.3.tgz",
+      "integrity": "sha512-Whjj2qoiJ6+OOJMGptTYazaJvjOJm+iKHpXQM1P3LzGjt7Ff++Tp7nH4N8J/BUA7R9IHfDyx4DJIflifwnbmIA==",
       "cpu": [
         "arm64"
       ],
@@ -1724,9 +1690,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-musl": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.2.tgz",
-      "integrity": "sha512-hr26p7e93Rl0Za+JwW7EAnwAvKkehh12BU1Llm9Ykiibg4uIr2rbpxG9WCf56GuvidlTG9KiiQT/TXT1yAWxTA==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.3.tgz",
+      "integrity": "sha512-4YTNHKqGng5+yiZt3mg77nmyuCfmNfX4fPmyUapBcIk+BdwSwmCWGXOUxhXbBEkFHtoN5boLj/5NON+u5QC9tg==",
       "cpu": [
         "arm64"
       ],
@@ -1740,9 +1706,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.2.tgz",
-      "integrity": "sha512-pOjB/uSIyDt+ow3k/RcLvUAOGpysT2phDn7TTUB3n75SlIgZzM6NKAqlErPhoFU+npgY3/n+2HYIQVbF70P9/A==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.3.tgz",
+      "integrity": "sha512-SU3kNlhkpI4UqlUc2VXPGK9o886ZsSeGfMAX2ba2b8DKmMXq4AL7KUrkSWVbb7koVqx41Yczx6dx5PNargIrEA==",
       "cpu": [
         "loong64"
       ],
@@ -1756,9 +1722,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-musl": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.2.tgz",
-      "integrity": "sha512-2/w+q8jszv9Ww1c+6uJT3OwqhdmGP2/4T17cu8WuwyUuuaCDDJ2ojdyYwZzCxx0GcsZBhzi3HmH+J5pZNXnd+Q==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.3.tgz",
+      "integrity": "sha512-6lDLl5h4TXpB1mTf2rQWnAk/LcXrx9vBfu/DT5TIPhvMhRWaZ5MxkIc8u4lJAmBo6klTe1ywXIUHFjylW505sg==",
       "cpu": [
         "loong64"
       ],
@@ -1772,9 +1738,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.2.tgz",
-      "integrity": "sha512-11+aL5vKheYgczxtPVVRhdptAM2H7fcDR5Gw4/bTcteuZBlH4oP9f5s9zYO9aGZvoGeBpqXI/9TZZihZ609wKw==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.3.tgz",
+      "integrity": "sha512-BMo8bOw8evlup/8G+cj5xWtPyp93xPdyoSN16Zy90Q2QZ0ZYRhCt6ZJSwbrRzG9HApFabjwj2p25TUPDWrhzqQ==",
       "cpu": [
         "ppc64"
       ],
@@ -1788,9 +1754,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-musl": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.2.tgz",
-      "integrity": "sha512-i16fokAGK46IVZuV8LIIwMdtqhin9hfYkCh8pf8iC3QU3LpwL+1FSFGej+O7l3E/AoknL6Dclh2oTdnRMpTzFQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.3.tgz",
+      "integrity": "sha512-E0L8X1dZN1/Rph+5VPF6Xj2G7JJvMACVXtamTJIDrVI44Y3K+G8gQaMEAavbqCGTa16InptiVrX6eM6pmJ+7qA==",
       "cpu": [
         "ppc64"
       ],
@@ -1804,9 +1770,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.2.tgz",
-      "integrity": "sha512-49FkKS6RGQoriDSK/6E2GkAsAuU5kETFCh7pG4yD/ylj9rKhTmO3elsnmBvRD4PgJPds5W2PkhC82aVwmUcJ7A==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.3.tgz",
+      "integrity": "sha512-oZJ/WHaVfHUiRAtmTAeo3DcevNsVvH8mbvodjZy7D5QKvCefO371SiKRpxoDcCxB3PTRTLayWBkvmDQKTcX/sw==",
       "cpu": [
         "riscv64"
       ],
@@ -1820,9 +1786,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-musl": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.2.tgz",
-      "integrity": "sha512-mjYNkHPfGpUR00DuM1ZZIgs64Hpf4bWcz9Z41+4Q+pgDx73UwWdAYyf6EG/lRFldmdHHzgrYyge5akFUW0D3mQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.3.tgz",
+      "integrity": "sha512-Dhbyh7j9FybM3YaTgaHmVALwA8AkUwTPccyCQ79TG9AJUsMQqgN1DDEZNr4+QUfwiWvLDumW5vdwzoeUF+TNxQ==",
       "cpu": [
         "riscv64"
       ],
@@ -1836,9 +1802,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-s390x-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.2.tgz",
-      "integrity": "sha512-ALyvJz965BQk8E9Al/JDKKDLH2kfKFLTGMlgkAbbYtZuJt9LU8DW3ZoDMCtQpXAltZxwBHevXz5u+gf0yA0YoA==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.3.tgz",
+      "integrity": "sha512-cJd1X5XhHHlltkaypz1UcWLA8AcoIi1aWhsvaWDskD1oz2eKCypnqvTQ8ykMNI0RSmm7NkTdSqSSD7zM0xa6Ig==",
       "cpu": [
         "s390x"
       ],
@@ -1852,9 +1818,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.2.tgz",
-      "integrity": "sha512-UQjrkIdWrKI626Du8lCQ6MJp/6V1LAo2bOK9OTu4mSn8GGXIkPXk/Vsp4bLHCd9Z9Iz2OTEaokUE90VweJgIYQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.3.tgz",
+      "integrity": "sha512-DAZDBHQfG2oQuhY7mc6I3/qB4LU2fQCjRvxbDwd/Jdvb9fypP4IJ4qmtu6lNjes6B531AI8cg1aKC2di97bUxA==",
       "cpu": [
         "x64"
       ],
@@ -1868,9 +1834,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-musl": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.2.tgz",
-      "integrity": "sha512-bTsRGj6VlSdn/XD4CGyzMnzaBs9bsRxy79eTqTCBsA8TMIEky7qg48aPkvJvFe1HyzQ5oMZdg7AnVlWQSKLTnw==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.3.tgz",
+      "integrity": "sha512-cRxsE8c13mZOh3vP+wLDxpQBRrOHDIGOWyDL93Sy0Ga8y515fBcC2pjUfFwUe5T7tqvTvWbCpg1URM/AXdWIXA==",
       "cpu": [
         "x64"
       ],
@@ -1884,9 +1850,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openbsd-x64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.2.tgz",
-      "integrity": "sha512-6d4Z3534xitaA1FcMWP7mQPq5zGwBmGbhphh2DwaA1aNIXUu3KTOfwrWpbwI4/Gr0uANo7NTtaykFyO2hPuFLg==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.3.tgz",
+      "integrity": "sha512-QaWcIgRxqEdQdhJqW4DJctsH6HCmo5vHxY0krHSX4jMtOqfzC+dqDGuHM87bu4H8JBeibWx7jFz+h6/4C8wA5Q==",
       "cpu": [
         "x64"
       ],
@@ -1897,9 +1863,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openharmony-arm64": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.2.tgz",
-      "integrity": "sha512-NetAg5iO2uN7eB8zE5qrZ3CSil+7IJt4WDFLcC75Ymywq1VZVD6qJ6EvNLjZ3rEm6gB7XW5JdT60c6MN35Z85Q==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.3.tgz",
+      "integrity": "sha512-AaXwSvUi3QIPtroAUw1t5yHGIyqKEXwH54WUocFolZhpGDruJcs8c+xPNDRn4XiQsS7MEwnYsHW2l0MBLDMkWg==",
       "cpu": [
         "arm64"
       ],
@@ -1910,9 +1876,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-arm64-msvc": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.2.tgz",
-      "integrity": "sha512-NCYhOotpgWZ5kdxCZsv6Iudx0wX8980Q/oW4pNFNihpBKsDbEA1zpkfxJGC0yugsUuyDZ7gL37dbzwhR0VI7pQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.3.tgz",
+      "integrity": "sha512-65LAKM/bAWDqKNEelHlcHvm2V+Vfb8C6INFxQXRHCvaVN1rJfwr4NvdP4FyzUaLqWfaCGaadf6UbTm8xJeYfEg==",
       "cpu": [
         "arm64"
       ],
@@ -1923,9 +1889,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-ia32-msvc": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.2.tgz",
-      "integrity": "sha512-RXsaOqXxfoUBQoOgvmmijVxJnW2IGB0eoMO7F8FAjaj0UTywUO/luSqimWBJn04WNgUkeNhh7fs7pESXajWmkg==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.3.tgz",
+      "integrity": "sha512-EEM2gyhBF5MFnI6vMKdX1LAosE627RGBzIoGMdLloPZkXrUN0Ckqgr2Qi8+J3zip/8NVVro3/FjB+tjhZUgUHA==",
       "cpu": [
         "ia32"
       ],
@@ -1936,9 +1902,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-gnu": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.2.tgz",
-      "integrity": "sha512-qdAzEULD+/hzObedtmV6iBpdL5TIbKVztGiK7O3/KYSf+HIzU257+MX1EXJcyIiDbMAqmbwaufcYPvyRryeZtA==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.3.tgz",
+      "integrity": "sha512-E5Eb5H/DpxaoXH++Qkv28RcUJboMopmdDUALBczvHMf7hNIxaDZqwY5lK12UK1BHacSmvupoEWGu+n993Z0y1A==",
       "cpu": [
         "x64"
       ],
@@ -1949,9 +1915,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-msvc": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.2.tgz",
-      "integrity": "sha512-Nd/SgG27WoA9e+/TdK74KnHz852TLa94ovOYySo/yMPuTmpckK/jIF2jSwS3g7ELSKXK13/cVdmg1Z/DaCWKxA==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.3.tgz",
+      "integrity": "sha512-hPt/bgL5cE+Qp+/TPHBqptcAgPzgj46mPcg/16zNUmbQk0j+mOEQV/+Lqu8QRtDV3Ek95Q6FeFITpuhl6OTsAA==",
       "cpu": [
         "x64"
       ],
@@ -2361,9 +2327,9 @@
       }
     },
     "node_modules/@types/estree": {
-      "version": "1.0.8",
-      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
-      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
       "license": "MIT"
     },
     "node_modules/@types/estree-jsx": {
@@ -2437,9 +2403,9 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "24.12.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.2.tgz",
-      "integrity": "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==",
+      "version": "24.12.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.3.tgz",
+      "integrity": "sha512-8oljBDGun9cIsZRJR6fkihn0TSXJI0UDOOhncYaERq6M0JMDoPLxyscwruJcb4GKS6dvK/d8xebYBg27h/duaQ==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~7.16.0"
@@ -2475,9 +2441,9 @@
       "license": "MIT"
     },
     "node_modules/@ungap/structured-clone": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz",
-      "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.1.tgz",
+      "integrity": "sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==",
       "license": "ISC"
     },
     "node_modules/@upsetjs/venn.js": {
@@ -2814,36 +2780,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/chevrotain": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
-      "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
-      "license": "Apache-2.0",
-      "peer": true,
-      "dependencies": {
-        "@chevrotain/cst-dts-gen": "12.0.0",
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/regexp-to-ast": "12.0.0",
-        "@chevrotain/types": "12.0.0",
-        "@chevrotain/utils": "12.0.0"
-      },
-      "engines": {
-        "node": ">=22.0.0"
-      }
-    },
-    "node_modules/chevrotain-allstar": {
-      "version": "0.4.3",
-      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.3.tgz",
-      "integrity": "sha512-2X4mkroolSMKqW+H22pyPMUVDqYZzPhephTmg/NODKb1IGYPHfxfhcW0EjS7wcPJNbze2i4vBWT7zT5FKF2lrQ==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "lodash-es": "^4.18.1"
-      },
-      "peerDependencies": {
-        "chevrotain": "^12.0.0"
-      }
-    },
     "node_modules/chokidar": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-5.0.0.tgz",
@@ -2922,13 +2858,6 @@
         "node": ">= 18"
       }
     },
-    "node_modules/confbox": {
-      "version": "0.1.8",
-      "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz",
-      "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==",
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/cookie": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
@@ -3850,6 +3779,17 @@
       "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==",
       "license": "MIT"
     },
+    "node_modules/es-toolkit": {
+      "version": "1.46.1",
+      "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.46.1.tgz",
+      "integrity": "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ==",
+      "license": "MIT",
+      "peer": true,
+      "workspaces": [
+        "docs",
+        "benchmarks"
+      ]
+    },
     "node_modules/esast-util-from-estree": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/esast-util-from-estree/-/esast-util-from-estree-2.0.0.tgz",
@@ -4877,25 +4817,6 @@
         "node": ">= 8"
       }
     },
-    "node_modules/langium": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.3.tgz",
-      "integrity": "sha512-sOPIi4hISFnY7twwV97ca1TsxpBtXq0URu/LL1AvxwccPG/RIBBlKS7a/f/EL6w8lTNaS0EFs/F+IdSOaqYpng==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@chevrotain/regexp-to-ast": "~12.0.0",
-        "chevrotain": "~12.0.0",
-        "chevrotain-allstar": "~0.4.3",
-        "vscode-languageserver": "~9.0.1",
-        "vscode-languageserver-textdocument": "~1.0.11",
-        "vscode-uri": "~3.1.0"
-      },
-      "engines": {
-        "node": ">=20.10.0",
-        "npm": ">=10.2.3"
-      }
-    },
     "node_modules/layout-base": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz",
@@ -4921,9 +4842,9 @@
       }
     },
     "node_modules/lru-cache": {
-      "version": "11.3.5",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
-      "integrity": "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==",
+      "version": "11.3.6",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.6.tgz",
+      "integrity": "sha512-Gf/KoL3C/MlI7Bt0PGI9I+TeTC/I6r/csU58N4BSNc4lppLBeKsOdFYkK+dX0ABDUMJNfCHTyPpzwwO21Awd3A==",
       "license": "BlueOak-1.0.0",
       "engines": {
         "node": "20 || >=22"
@@ -5314,15 +5235,15 @@
       "license": "CC0-1.0"
     },
     "node_modules/mermaid": {
-      "version": "11.14.0",
-      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
-      "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
+      "version": "11.15.0",
+      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.15.0.tgz",
+      "integrity": "sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==",
       "license": "MIT",
       "peer": true,
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.1",
         "@iconify/utils": "^3.0.2",
-        "@mermaid-js/parser": "^1.1.0",
+        "@mermaid-js/parser": "^1.1.1",
         "@types/d3": "^7.4.3",
         "@upsetjs/venn.js": "^2.0.0",
         "cytoscape": "^3.33.1",
@@ -5333,14 +5254,14 @@
         "dagre-d3-es": "7.0.14",
         "dayjs": "^1.11.19",
         "dompurify": "^3.3.1",
+        "es-toolkit": "^1.45.1",
         "katex": "^0.16.25",
         "khroma": "^2.1.0",
-        "lodash-es": "^4.17.23",
         "marked": "^16.3.0",
         "roughjs": "^4.6.6",
         "stylis": "^4.3.6",
         "ts-dedent": "^2.2.0",
-        "uuid": "^11.1.0"
+        "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
       }
     },
     "node_modules/micromark": {
@@ -6104,19 +6025,6 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
-    "node_modules/mlly": {
-      "version": "1.8.2",
-      "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.2.tgz",
-      "integrity": "sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "acorn": "^8.16.0",
-        "pathe": "^2.0.3",
-        "pkg-types": "^1.3.1",
-        "ufo": "^1.6.3"
-      }
-    },
     "node_modules/mrmime": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
@@ -6378,13 +6286,6 @@
       "license": "MIT",
       "peer": true
     },
-    "node_modules/pathe": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
-      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/piccolore": {
       "version": "0.1.3",
       "resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz",
@@ -6409,18 +6310,6 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
-    "node_modules/pkg-types": {
-      "version": "1.3.1",
-      "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz",
-      "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "confbox": "^0.1.8",
-        "mlly": "^1.7.4",
-        "pathe": "^2.0.1"
-      }
-    },
     "node_modules/points-on-curve": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/points-on-curve/-/points-on-curve-0.2.0.tgz",
@@ -6440,9 +6329,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.13",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.13.tgz",
-      "integrity": "sha512-qif0+jGGZoLWdHey3UFHHWP0H7Gbmsk8T5VEqyYFbWqPr1XqvLGBbk/sl8V5exGmcYJklJOhOQq1pV9IcsiFag==",
+      "version": "8.5.14",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
+      "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
       "funding": [
         {
           "type": "opencollective",
@@ -6944,9 +6833,9 @@
       "peer": true
     },
     "node_modules/rollup": {
-      "version": "4.60.2",
-      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.2.tgz",
-      "integrity": "sha512-J9qZyW++QK/09NyN/zeO0dG/1GdGfyp9lV8ajHnRVLfo/uFsbji5mHnDgn/qYdUHyCkM2N+8VyspgZclfAh0eQ==",
+      "version": "4.60.3",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.3.tgz",
+      "integrity": "sha512-pAQK9HalE84QSm4Po3EmWIZPd3FnjkShVkiMlz1iligWYkWQ7wHYd1PF/T7QZ5TVSD6uSTon5gBVMSM4JfBV+A==",
       "license": "MIT",
       "dependencies": {
         "@types/estree": "1.0.8"
@@ -6959,34 +6848,40 @@
         "npm": ">=8.0.0"
       },
       "optionalDependencies": {
-        "@rollup/rollup-android-arm-eabi": "4.60.2",
-        "@rollup/rollup-android-arm64": "4.60.2",
-        "@rollup/rollup-darwin-arm64": "4.60.2",
-        "@rollup/rollup-darwin-x64": "4.60.2",
-        "@rollup/rollup-freebsd-arm64": "4.60.2",
-        "@rollup/rollup-freebsd-x64": "4.60.2",
-        "@rollup/rollup-linux-arm-gnueabihf": "4.60.2",
-        "@rollup/rollup-linux-arm-musleabihf": "4.60.2",
-        "@rollup/rollup-linux-arm64-gnu": "4.60.2",
-        "@rollup/rollup-linux-arm64-musl": "4.60.2",
-        "@rollup/rollup-linux-loong64-gnu": "4.60.2",
-        "@rollup/rollup-linux-loong64-musl": "4.60.2",
-        "@rollup/rollup-linux-ppc64-gnu": "4.60.2",
-        "@rollup/rollup-linux-ppc64-musl": "4.60.2",
-        "@rollup/rollup-linux-riscv64-gnu": "4.60.2",
-        "@rollup/rollup-linux-riscv64-musl": "4.60.2",
-        "@rollup/rollup-linux-s390x-gnu": "4.60.2",
-        "@rollup/rollup-linux-x64-gnu": "4.60.2",
-        "@rollup/rollup-linux-x64-musl": "4.60.2",
-        "@rollup/rollup-openbsd-x64": "4.60.2",
-        "@rollup/rollup-openharmony-arm64": "4.60.2",
-        "@rollup/rollup-win32-arm64-msvc": "4.60.2",
-        "@rollup/rollup-win32-ia32-msvc": "4.60.2",
-        "@rollup/rollup-win32-x64-gnu": "4.60.2",
-        "@rollup/rollup-win32-x64-msvc": "4.60.2",
+        "@rollup/rollup-android-arm-eabi": "4.60.3",
+        "@rollup/rollup-android-arm64": "4.60.3",
+        "@rollup/rollup-darwin-arm64": "4.60.3",
+        "@rollup/rollup-darwin-x64": "4.60.3",
+        "@rollup/rollup-freebsd-arm64": "4.60.3",
+        "@rollup/rollup-freebsd-x64": "4.60.3",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.3",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.3",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.3",
+        "@rollup/rollup-linux-arm64-musl": "4.60.3",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.3",
+        "@rollup/rollup-linux-loong64-musl": "4.60.3",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.3",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.3",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.3",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.3",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.3",
+        "@rollup/rollup-linux-x64-gnu": "4.60.3",
+        "@rollup/rollup-linux-x64-musl": "4.60.3",
+        "@rollup/rollup-openbsd-x64": "4.60.3",
+        "@rollup/rollup-openharmony-arm64": "4.60.3",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.3",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.3",
+        "@rollup/rollup-win32-x64-gnu": "4.60.3",
+        "@rollup/rollup-win32-x64-msvc": "4.60.3",
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/rollup/node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "license": "MIT"
+    },
     "node_modules/roughjs": {
       "version": "4.6.6",
       "resolved": "https://registry.npmjs.org/roughjs/-/roughjs-4.6.6.tgz",
@@ -7024,9 +6919,9 @@
       }
     },
     "node_modules/semver": {
-      "version": "7.7.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
@@ -7818,9 +7713,9 @@
       }
     },
     "node_modules/vite": {
-      "version": "7.3.2",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.2.tgz",
-      "integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==",
+      "version": "7.3.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.3.tgz",
+      "integrity": "sha512-/4XH147Ui7OGTjg3HbdWe5arnZQSbfuRzdr9Ec7TQi5I7R+ir0Rlc9GIvD4v0XZurELqA035KVXJXpR61xhiTA==",
       "license": "MIT",
       "dependencies": {
         "esbuild": "^0.27.0",
@@ -7910,61 +7805,6 @@
         }
       }
     },
-    "node_modules/vscode-jsonrpc": {
-      "version": "8.2.0",
-      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
-      "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
-    "node_modules/vscode-languageserver": {
-      "version": "9.0.1",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
-      "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "vscode-languageserver-protocol": "3.17.5"
-      },
-      "bin": {
-        "installServerIntoExtension": "bin/installServerIntoExtension"
-      }
-    },
-    "node_modules/vscode-languageserver-protocol": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
-      "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "vscode-jsonrpc": "8.2.0",
-        "vscode-languageserver-types": "3.17.5"
-      }
-    },
-    "node_modules/vscode-languageserver-textdocument": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
-      "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
-      "license": "MIT",
-      "peer": true
-    },
-    "node_modules/vscode-languageserver-types": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
-      "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
-      "license": "MIT",
-      "peer": true
-    },
-    "node_modules/vscode-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
-      "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/web-namespaces": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
@@ -7991,9 +7831,9 @@
       "license": "MIT"
     },
     "node_modules/yaml": {
-      "version": "2.8.4",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.4.tgz",
-      "integrity": "sha512-ml/JPOj9fOQK8RNnWojA67GbZ0ApXAUlN2UQclwv2eVgTgn7O9gg9o7paZWKMp4g0H3nTLtS9LVzhkpOFIKzog==",
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
       "license": "ISC",
       "bin": {
         "yaml": "bin.mjs"
@@ -8027,9 +7867,9 @@
       }
     },
     "node_modules/zod": {
-      "version": "4.4.2",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.2.tgz",
-      "integrity": "sha512-IynmDyxsEsb9RKzO3J9+4SxXnl2FTFSzNBaKKaMV6tsSk0rw9gYw9gs+JFCq/qk2LCZ78KDwyj+Z289TijSkUw==",
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
diff --git a/docs/package.json b/docs/package.json
index 0312e9cd9..0a2f0de44 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -10,6 +10,7 @@
     "astro": "astro"
   },
   "dependencies": {
+    "@astrojs/sitemap": "^3.7.2",
     "@astrojs/starlight": "0.38.4",
     "astro": "6.2.1",
     "astro-mermaid": "^2.0.1",
@@ -18,7 +19,6 @@
     "starlight-llms-txt": "^0.8.1"
   },
   "overrides": {
-    "@astrojs/sitemap": "3.7.2",
     "uuid": "^14.0.0"
   }
 }
diff --git a/docs/src/content/docs/concepts/glossary.md b/docs/src/content/docs/concepts/glossary.md
new file mode 100644
index 000000000..073157223
--- /dev/null
+++ b/docs/src/content/docs/concepts/glossary.md
@@ -0,0 +1,317 @@
+---
+title: Glossary
+description: Every overloaded APM term, resolved in one paragraph. Skim alphabetically.
+sidebar:
+  order: 99
+---
+
+Every overloaded APM term, resolved in one paragraph. Skim alphabetically.
+"What it is NOT" lines disambiguate the most common collisions.
+
+### apm.lock.yaml
+
+The lockfile APM writes after a successful resolve. Pins exact commit SHAs
+and per-file content hashes so every `apm install` from the same lockfile
+produces byte-identical output. Lives at the project root next to `apm.yml`.
+
+NOT the manifest. The manifest declares what you want; the lockfile records
+what you got.
+
+Source: `src/apm_cli/deps/lockfile.py`.
+
+### apm.yml
+
+The package manifest. A YAML file at the package root that declares
+`name`, `version`, `dependencies`, `scripts`, `target`, and metadata. Both
+the unit of authoring and the unit of consumption -- a directory becomes
+an APM package the moment it has an `apm.yml`.
+
+NOT the lockfile, and NOT a `plugin.json`. The manifest is human-edited;
+the lockfile is generated; `plugin.json` is the local-bundle descriptor.
+
+Source: `src/apm_cli/models/apm_package.py`.
+
+### audit
+
+The `apm audit` command. Scans installed primitives for hidden Unicode
+that could embed invisible instructions, and (with `--ci`) re-derives
+content from the lockfile to detect drift before it ships. Emits SARIF,
+JSON, or rendered output. Standalone scanning of arbitrary files is
+available via `--file`.
+
+NOT the same thing as install-time scanning. Install-time scanning is
+automatic and blocks critical findings; `audit` is the explicit reporting
+and remediation surface.
+
+See: [Security](/apm/enterprise/security/).
+Source: `src/apm_cli/commands/audit.py`.
+
+### bundle
+
+A local-install artifact produced by `apm pack`. Either a directory or a
+`.tar.gz` containing `plugin.json` at the root and (in current versions)
+an embedded `apm.lock.yaml` with per-file SHA-256 hashes. Installed via
+`apm install <path-or-tarball>`.
+
+NOT a package source repository. A bundle is the packed, hash-verified
+output of one; you ship bundles, you author packages.
+
+Source: `src/apm_cli/bundle/local_bundle.py`.
+
+### compile
+
+The `apm compile` command. Takes resolved primitives in `apm_modules/`
+and writes them into each declared harness location (`.github/`,
+`.claude/`, `.cursor/`, etc.) using the format that harness expects.
+Runs automatically as the final phase of `apm install`.
+
+NOT a build step that produces an artifact. Compile only deploys to
+local harness directories.
+
+See: [Compilation guide](/apm/producer/compile/).
+Source: `src/apm_cli/commands/compile/`.
+
+### dev-only primitive
+
+A dependency listed under `devDependencies:` in `apm.yml` (mirroring `package.json`). Installed locally
+for authoring and testing but excluded from the bundle that `apm pack`
+ships. The lockfile records the `is_dev` flag per package.
+
+NOT a separate primitive type. Any package or primitive can be marked
+dev-only; it is a visibility flag, not a category.
+
+Source: `src/apm_cli/deps/lockfile.py`,
+`src/apm_cli/deps/installed_package.py`.
+
+### GitHub APM PAT
+
+The personal access token APM reads to authenticate against GitHub
+when resolving private packages. Resolution order:
+`GITHUB_APM_PAT_<ORG>` (per-org), then `GITHUB_APM_PAT`, then
+`GITHUB_TOKEN`, then `GH_TOKEN`. Public packages need no token.
+
+NOT a separate token type. It is a standard GitHub PAT; the
+`GITHUB_APM_PAT` name exists so APM-scoped tokens do not collide with
+other tooling.
+
+See: [Authentication](/apm/consumer/authentication/).
+Source: `src/apm_cli/core/auth.py`.
+
+### harness
+
+The agent runtime that executes primitives: GitHub Copilot (CLI + IDE),
+Claude Code, Cursor, Codex, Gemini, OpenCode, Windsurf. Each harness has
+its own primitive directory layout and file format.
+
+NOT the same as a target. The target is the `apm.yml` field that selects
+which harnesses to compile for; the harness is the runtime itself.
+
+Source: `src/apm_cli/integration/targets.py` (see `KNOWN_TARGETS`).
+
+### hook
+
+A primitive type whose contents run at a defined lifecycle event in the
+host harness (for example `PreToolUse`). Supported on every harness
+except OpenCode -- see the matrix in
+[primitives and targets](/apm/concepts/primitives-and-targets/).
+
+NOT an APM CLI lifecycle event. Hooks fire inside the agent runtime,
+not inside `apm install` or `apm compile`.
+
+Source: `src/apm_cli/integration/hook_integrator.py`.
+
+### install
+
+The `apm install` command. Resolves dependencies declared in `apm.yml`,
+downloads them into `apm_modules/`, runs the policy gate, scans for
+hidden Unicode, writes `apm.lock.yaml`, and compiles primitives into
+each declared harness directory.
+
+All major verbs match npm semantics: `apm install` deploys, `apm update`
+refreshes dependencies, `apm install --frozen` is the lockfile-only CI
+install (mirrors `npm ci`). The CLI binary itself updates via
+`apm self-update`, not `apm update`.
+
+Source: `src/apm_cli/commands/install.py`.
+
+### lockfile
+
+See [apm.lock.yaml](#apmlockyaml).
+
+### manifest
+
+See [apm.yml](#apmyml).
+
+### marketplace
+
+A curated index of packages, hosted as a Git repository with a
+`marketplace.json` at its root. Lists packages by handle and points each
+one at a Git source. Authors publish their packages to a marketplace so
+consumers can discover and install them by short name.
+
+NOT a registry. A marketplace is human-curated discovery; the registry
+is the resolution backend that APM actually downloads from.
+
+See: [Marketplaces guide](/apm/consumer/private-and-org-packages/).
+Source: `src/apm_cli/commands/marketplace/`.
+
+### MCP server
+
+A Model Context Protocol server declared as a dependency under
+`mcp:` in `apm.yml`. APM resolves MCP servers transitively, applies
+the same policy gate, and writes the runtime config into each harness
+that supports MCP.
+
+NOT an APM primitive type. MCP servers are external processes; APM
+declares and gates them but does not ship their code.
+
+Source: `src/apm_cli/install/mcp/`,
+`src/apm_cli/integration/mcp_integrator.py`.
+
+### package
+
+The APM unit of distribution: a directory whose root contains an
+`apm.yml`. Packages declare primitives, dependencies, scripts, and
+targets. A repository may contain one package at the root or several in
+subdirectories.
+
+NOT a plugin (see below) and NOT a bundle. A package is the source-form
+unit; the bundle is its packed form; `plugin.json` is a separate
+descriptor format.
+
+Source: `src/apm_cli/models/apm_package.py`.
+
+### plugin
+
+A local-install artifact whose root contains a `plugin.json` (Claude
+Code / Copilot CLI plugin format). APM detects plugins on
+`apm install <path>`, treats them as packages by synthesising an
+`apm.yml` from the `plugin.json`, then installs them through the
+standard pipeline.
+
+NOT a different thing from a package at runtime. Plugin format is the
+input shape; once detected, APM handles plugins exactly like packages.
+
+See: [Plugins guide](/apm/producer/author-primitives/).
+Source: `src/apm_cli/bundle/local_bundle.py`,
+`src/apm_cli/commands/install.py`.
+
+### policy
+
+The `apm-policy.yml` file plus the install-time enforcement gate that
+reads it. Lets a security team allow-list sources, scopes, and primitive
+kinds. Tightens-only across enterprise -> org -> repo. Runs before any
+file is written to disk, including for transitive MCP servers.
+
+NOT the same as `audit`. Policy enforces at install time; audit reports
+after the fact.
+
+See: [Governance guide](/apm/enterprise/governance-guide/).
+Source: `src/apm_cli/policy/`.
+
+### primitive
+
+The atomic unit APM ships. The supported kinds are: instructions,
+skills, prompts, agents, hooks, commands, plugins, and MCP servers.
+Each kind has its own integrator that knows how to deploy it into each
+harness.
+
+NOT every file in a package. Only files matching the primitive layout
+under recognised directories (`agents/`, `skills/`, `prompts/`,
+`instructions/`, `hooks/`, `commands/`) are deployed.
+
+See: [Primitives and targets](/apm/concepts/primitives-and-targets/).
+Source: `src/apm_cli/integration/`.
+
+### registry
+
+The resolution backend APM downloads packages from. In the current
+implementation this is GitHub (or any Git host reachable over HTTPS or
+SSH); enterprise customers can pin to GHES, ADO, or GitLab.
+
+NOT a marketplace. The registry is where bytes come from; a marketplace
+is a curated index that points at registry locations.
+
+Source: `src/apm_cli/core/auth.py`,
+`src/apm_cli/utils/github_host.py`.
+
+### script
+
+An entry under `scripts:` in `apm.yml`, mapped to a shell command.
+Invoked with `apm run <name>`. Used for the post-install workflow that
+launches an agent against the compiled primitives (for example
+`apm run start`).
+
+NOT a primitive. Scripts are project-level commands; they do not deploy
+into harness directories.
+
+Source: `src/apm_cli/models/apm_package.py`,
+`src/apm_cli/commands/run.py`.
+
+### target
+
+The `target:` field in `apm.yml`. Names which harnesses the package
+compiles for (`copilot`, `claude`, `cursor`, `codex`, `gemini`,
+`opencode`, `windsurf`, or `all`). Drives which integrator runs and
+which directories receive output during `apm compile`.
+
+NOT the harness itself. Target is the declaration; the harness is the
+runtime that consumes the compiled output.
+
+See: [Primitives and targets](/apm/concepts/primitives-and-targets/).
+Source: `src/apm_cli/integration/targets.py`,
+`src/apm_cli/core/target_detection.py`.
+
+### transitive dependency
+
+A dependency that another dependency pulls in. APM resolves the full
+transitive closure (packages and MCP servers), applies the policy gate
+to every node, and records each one in the lockfile. Insecure transitive
+deps trigger an explicit error unless allow-listed.
+
+NOT silent. Every transitive node is policy-gated and lockfile-recorded;
+nothing slips in below the manifest layer.
+
+Source: `src/apm_cli/install/context.py`,
+`src/apm_cli/install/insecure_policy.py`.
+
+### trust prompt
+
+The install-time consent step before APM writes a new MCP server config
+to disk. Required because an MCP server pulled in transitively by a deep
+dependency can introduce a new outbound integration the user did not
+explicitly request. Today this is enforced via `--trust-transitive-mcp`
+opt-in plus `apm-policy.yml` allow-listing; an interactive prompt is on
+the Promise 2 roadmap.
+
+Source: `src/apm_cli/install/mcp/`,
+`src/apm_cli/install/insecure_policy.py`.
+
+### self-update
+
+The `apm self-update` command. Downloads the latest release of the
+`apm` CLI from the official installer URL and replaces the binary in
+place. Supports `--check` to report availability without installing.
+Disabled in package-manager distributions (for example, Homebrew),
+which print a distributor-defined upgrade message instead.
+
+NOT a dependency refresh. `self-update` only touches the CLI binary;
+your project's `apm.yml`, lockfile, and `apm_modules/` are untouched.
+For dependency refresh, see [update](#update).
+
+Source: `src/apm_cli/commands/self_update.py`.
+
+### update
+
+The `apm update` command. Re-resolves every dependency in `apm.yml` to
+its latest matching Git ref, prints a structured plan
+(added / updated / removed / unchanged), and prompts for consent before
+rewriting `apm.lock.yaml`. Defaults to **No** on the prompt; declining
+exits cleanly with no writes. `--yes` skips the prompt for CI;
+`--dry-run` prints the plan without prompting or writing.
+
+Mirrors `npm update`. To pin to the existing lockfile in CI without
+refreshing, use `apm install --frozen` (mirrors `npm ci`). To upgrade
+the CLI binary itself, see [self-update](#self-update).
+
+Source: `src/apm_cli/commands/update.py`.
diff --git a/docs/src/content/docs/concepts/lifecycle.md b/docs/src/content/docs/concepts/lifecycle.md
new file mode 100644
index 000000000..627d6afde
--- /dev/null
+++ b/docs/src/content/docs/concepts/lifecycle.md
@@ -0,0 +1,143 @@
+---
+title: Lifecycle
+description: The five steps every APM project moves through, from init to audit.
+sidebar:
+  order: 4
+---
+
+APM has five lifecycle steps. Most projects use all five; small ones use three.
+
+```
+   init  ->  install  ->  compile  ->  run
+                                          |
+                                          v
+                                       audit
+                                          |
+                                          +--> back to install (fix drift)
+```
+
+`init` scaffolds the project. `install` resolves dependencies, scans them, and writes the lockfile. `compile` transforms primitives into the formats each agent harness expects. `run` invokes a script declared in `apm.yml`. `audit` rebuilds the deployed context in scratch and diffs it against your working tree to catch drift before it ships.
+
+You will use `install` and `run` daily, `audit` in CI, and `init` and `compile` rarely.
+
+## 1. INIT
+
+```bash
+apm init [project-name]
+```
+
+Scaffolds a new APM project in the current directory.
+
+`apm init` writes three things: an `apm.yml` manifest, a `.apm/` directory for your local primitives (instructions, prompts, skills, agents, hooks), and the agent target directories you select (for example `.github/`, `.claude/`, `.cursor/`). It auto-detects sensible defaults for `name`, `author`, and `description` from your git config and surrounding directory; pass `-y` to accept them without prompts.
+
+Targets are picked in priority order. An explicit `--target copilot,claude` flag wins. Otherwise an interactive checklist runs. Otherwise APM scans the working tree for signal directories (`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.gemini/`, `.windsurf/`) and pre-checks every harness it finds. With `-y` and no flag, all detected harnesses are written into `apm.yml`. See [primitives and targets](/apm/concepts/primitives-and-targets/) for what each target actually receives.
+
+**Common surprises**
+
+- Re-running `apm init` in a directory that already has `apm.yml` warns and exits unless you pass `-y` (which overwrites the manifest).
+- If you set `targets:` to an empty list in `apm.yml`, target detection runs again at compile time. To pin targets, list them explicitly.
+
+**Read more:** [`apm init` reference](/apm/reference/cli/install/), [package anatomy](/apm/concepts/package-anatomy/).
+
+## 2. INSTALL
+
+```bash
+apm install [packages...]
+```
+
+Resolves the dependency graph declared in `apm.yml`, runs the security scan, and writes `apm.lock.yaml`.
+
+Order of operations is deterministic and worth memorizing:
+
+1. **Resolve** -- walk `dependencies` and `devDependencies` (APM packages, MCP servers, Claude skills, plugin collections), follow transitive deps, pick versions.
+2. **Policy gate** -- if `apm-policy.yml` is discovered (locally or via your repo's org), every resolved dependency is checked against the allow-list before anything touches disk. Pass `--no-policy` to skip the org policy gate for one invocation; this does not bypass `apm audit --ci`.
+3. **Scan** -- the pre-deploy security scan inspects every primitive for hidden Unicode (zero-width characters, bidi controls, tag characters). Critical findings block the install. Pass `--force` to deploy anyway.
+4. **Integrate** -- write primitives into each target harness's native directory (`.github/`, `.claude/`, etc.) and merge MCP server configs into the harness-specific config files.
+5. **Lockfile** -- write `apm.lock.yaml` with pinned versions, content hashes, and the resolved MCP server set.
+
+`apm install` with no arguments installs from the existing manifest. `apm install <package>` adds a new dependency, re-runs the full pipeline, and updates both `apm.yml` and `apm.lock.yaml`. `--dry-run` runs steps 1 and 2 only and prints the plan.
+
+:::note[Coming from npm?]
+`apm install` mirrors `npm install` deliberately. The big difference: APM also runs a security scan and, if present, an org policy gate before writing anything to disk.
+:::
+
+**Common surprises**
+
+- The scan is not optional in normal operation. If you need to land an install with a known critical finding (for example, an upstream package you cannot patch yet), use `--force` and document the exception.
+- Transitive MCP servers are gated behind explicit trust. If a deep dependency declares a new MCP server, install pauses to ask you to re-declare it in your top-level `apm.yml`. Use `--trust-transitive-mcp` to skip this in trusted environments.
+
+**Read more:** [`apm install` reference](/apm/reference/cli/install/), [security](/apm/enterprise/security/), [policy reference](/apm/enterprise/policy-reference/).
+
+## 3. COMPILE
+
+```bash
+apm compile [--target <list>]
+```
+
+Transforms the primitives in `.apm/` (and dependencies under `apm_modules/`) into harness-native files: `AGENTS.md` for Codex, `GEMINI.md` for Gemini, populated `.cursor/`, `.opencode/`, `.windsurf/` directories, and so on.
+
+Most users never call `apm compile` directly. `apm install` runs it as part of the integrate phase, and `apm run` auto-compiles any `.prompt.md` files referenced by a script just before execution. Reach for `apm compile` when you want to inspect what will be deployed without changing dependencies, when you are iterating on local primitives between installs, or when you only need output for one harness.
+
+The `--target` flag accepts a comma-separated list (`copilot,claude,cursor,opencode,codex,gemini,windsurf,agent-skills`) or `all`. `--dry-run` prints placement decisions without writing files. `--validate` checks primitive frontmatter and structure without producing output. `--watch` re-runs compilation on every change.
+
+**Common surprises**
+
+- Running `apm compile` does not re-run the security scan. The scan happens at install time. If you hand-edit primitives between installs, run `apm audit` to scan them.
+- `--clean` removes orphaned `AGENTS.md` files from previous compilations. Without it, removed primitives can leave stale output behind.
+
+**Read more:** [`apm compile` reference](/apm/reference/cli/install/), [compilation guide](/apm/producer/compile/).
+
+## 4. RUN
+
+```bash
+apm run <script-name> [--param key=value ...]
+```
+
+Executes a named script from the `scripts:` block in `apm.yml`.
+
+The `scripts:` block is a flat string-to-string mapping, mirroring `package.json`:
+
+```yaml
+name: my-project
+version: 0.1.0
+scripts:
+  start: copilot --prompt .apm/prompts/review.prompt.md
+  review: copilot --prompt .apm/prompts/review.prompt.md
+  test: pytest tests/
+```
+
+`apm run` with no script name runs `start`, matching npm. Before invoking the command, APM scans it for `.prompt.md` references, compiles each one to `.apm/compiled/<name>.txt`, and substitutes the compiled path into the command line. Use `--param key=value` (repeatable) to pass parameters that get interpolated into prompt frontmatter.
+
+To preview what will run without executing, use `apm preview <script-name>`. It prints the original command, the rewritten command after prompt compilation, and the list of compiled files.
+
+:::note[Coming from npm?]
+The `scripts:` shape is intentionally identical to `package.json`. Object-form scripts (with `description`, `env`, etc.) are not supported; keep them strings.
+:::
+
+**Common surprises**
+
+- A script that does not reference any `.prompt.md` file runs as-is. APM only rewrites the command when it finds `.prompt.md` arguments.
+- Parameters passed with `--param` only reach prompt files. They do not become shell environment variables.
+
+**Read more:** [`apm run` reference](/apm/reference/cli/install/), [agent workflows guide](/apm/producer/author-primitives/instructions-and-agents/).
+
+## 5. AUDIT
+
+```bash
+apm audit                  # local: scan deployed files for hidden Unicode
+apm audit --ci             # CI gate: lockfile consistency + drift replay
+apm audit --file <path>    # standalone: scan an arbitrary file
+```
+
+`apm audit` is the explicit reporting and remediation tool that complements the built-in scan run by `install`. It has two modes worth understanding separately.
+
+**Local mode** (`apm audit`, optionally with `--strip` or `--file <path>`) scans installed primitives -- or any file you point at -- for hidden Unicode and reports findings as text, JSON, SARIF, or markdown. With `--strip`, it removes hidden characters in place, preserving emoji and whitespace. Use `--dry-run` to preview the strip.
+
+**CI mode** (`apm audit --ci`) runs the eight baseline consistency checks in order: `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, and `includes-consent`. After those pass, it performs an install-replay drift check. APM rebuilds the deployed context in a scratch directory and diffs it against your working tree, catching hand-edits to `apm_modules/` or generated files before they ship. Pass `--no-drift` to skip the replay in performance-constrained loops; pass `--no-fail-fast` to run all checks even after a failure. With `--policy <source>` it also evaluates org policy against the lockfile.
+
+**Common surprises**
+
+- `apm audit --ci` exits 1 on any failure -- this is the gate you wire into branch protection. The local `apm audit` exits 0 even when findings exist, unless you also pass `--strip` and writes fail.
+- The drift check rebuilds the full context from scratch; on large repos, expect a few seconds of overhead. If your CI loop cannot afford it, narrow with `--no-drift` and accept reduced coverage.
+
+**Read more:** [`apm audit` reference](/apm/reference/cli/install/), [policy reference](/apm/enterprise/policy-reference/) for the full check list, [security](/apm/enterprise/security/).
diff --git a/docs/src/content/docs/concepts/package-anatomy.md b/docs/src/content/docs/concepts/package-anatomy.md
new file mode 100644
index 000000000..efaae8a34
--- /dev/null
+++ b/docs/src/content/docs/concepts/package-anatomy.md
@@ -0,0 +1,254 @@
+---
+title: Package anatomy
+description: The file layout of an APM package, field by field.
+sidebar:
+  order: 6
+---
+
+An APM package is a directory with two things: an `apm.yml` manifest and a
+`.apm/` source tree. Everything else -- the lockfile, compiled output, MCP
+configs, runtime-specific folders -- is generated, optional, or both.
+
+This page walks the file tree top-down so you can recognize every piece on
+sight.
+
+## The minimal package
+
+Three lines on disk is enough:
+
+```
+my-pkg/
++-- apm.yml
++-- .apm/
+    +-- skills/hello/SKILL.md
+```
+
+```yaml
+# apm.yml
+name: my-pkg
+version: 1.0.0
+```
+
+`name` and `version` are the only required fields.
+`apm install` will validate the manifest, generate `apm.lock.yaml`, and
+deploy `hello` to whatever harnesses you target.
+
+## Full file tree
+
+A mature package looks closer to this. One line per file; deeper pages own
+the detail.
+
+```
+my-pkg/
++-- apm.yml                       # The manifest. Required. See below.
++-- apm.lock.yaml                 # Resolved versions + content hashes. Generated.
++-- apm_modules/                  # Installed dependencies. Generated. Gitignore.
++-- .apm/                         # Source primitives you author.
+|   +-- instructions/             # Always-on rules attached to file globs.
+|   +-- skills/                   # Multi-file capabilities (SKILL.md + assets).
+|   +-- prompts/                  # Reusable prompt templates.
+|   +-- agents/                   # Named agents (model + system prompt + tools).
+|   +-- chatmodes/                # Chat-mode configurations.
+|   +-- context/                  # Shared context fragments.
+|   +-- hooks/                    # Lifecycle hooks (pre/post events).
++-- .github/                      # Compiled output for Copilot. Generated.
+|   +-- instructions/
+|   +-- agents/
+|   +-- copilot-instructions.md
++-- .claude/                      # Compiled output for Claude Code. Generated.
++-- .cursor/                      # Compiled output for Cursor. Generated.
++-- .codex/                       # Compiled output for Codex. Generated.
++-- AGENTS.md                     # Cross-tool spec read by OpenCode, Gemini, Codex.
++-- apm-policy.yml                # Optional org/repo policy. See enterprise docs.
++-- scripts/                      # Optional helper scripts you author.
++-- tests/                        # Optional tests for your primitives.
+```
+
+Anything under `apm_modules/`, `.github/`, `.claude/`, `.cursor/`, or
+`.codex/` is build output. Edit the source under `.apm/` and re-run
+`apm install` -- never edit the deployed copy.
+
+`apm init` only writes `apm.yml`. The rest appears as you author primitives
+or run `apm install`.
+
+For why `.apm/` exists at all (instead of writing straight into `.github/`),
+see [Primitives and targets](/apm/concepts/primitives-and-targets/).
+
+## Anatomy of `apm.yml`
+
+A realistic example, every field annotated:
+
+```yaml
+# Required identity
+name: my-pkg                       # Package name. Required.
+version: 1.0.0                     # SemVer string. Required.
+
+# Optional metadata
+description: Code review skills for Python services
+author: Jane Doe
+license: MIT
+
+# Optional content type: one of instructions, skill, hybrid, prompts.
+# Constrains what `.apm/` may contain. Useful for single-purpose packages.
+type: skill
+
+# Optional target list. Pins which harnesses this package compiles to.
+# Accepts a string ("copilot,claude") or a YAML list. Omit to target all.
+target:
+  - copilot
+  - claude
+
+# Optional. "auto" auto-publishes every primitive under .apm/, or list
+# explicit repo paths to publish a subset.
+includes: auto
+
+# Optional. Runtime dependencies, grouped by kind.
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0   # Pinned to a tag
+    - github/awesome-copilot/skills/review-and-refactor   # Single primitive
+  mcp:
+    - microsoft/azure-devops-mcp            # MCP server dependency
+
+# Optional. Same shape as `dependencies`, but excluded from the shipped
+# artifact. Use for dev-only tooling and tests.
+devDependencies:
+  apm:
+    - my-org/internal-test-skills
+
+# Optional. Named scripts you can run with `apm run <name>`.
+scripts:
+  start: copilot -p hello.prompt.md
+  codex: codex --skip-git-repo-check hello.prompt.md
+```
+
+### Field reference
+
+| Field            | Required | Notes                                                       |
+|------------------|----------|-------------------------------------------------------------|
+| `name`           | yes      | Package name.                                               |
+| `version`        | yes      | SemVer string.                                              |
+| `description`    | no       |                                                             |
+| `author`         | no       |                                                             |
+| `license`        | no       | SPDX identifier recommended.                                |
+| `type`           | no       | `instructions`, `skill`, `hybrid`, or `prompts`.            |
+| `target`         | no       | String or list of harness slugs.                            |
+| `includes`       | no       | `"auto"` or list of repo paths.                             |
+| `dependencies`   | no       | Mapping with `apm:` and/or `mcp:` keys.                     |
+| `devDependencies`| no       | Same shape as `dependencies`. Excluded from `apm pack`.     |
+| `scripts`        | no       | Mapping of name to shell command. Run via `apm run <name>`. |
+
+:::note[Coming from npm?]
+The shape mirrors `package.json` on purpose: `name`, `version`,
+`dependencies`, `devDependencies`, `scripts`. The verbs match too:
+`apm install` deploys, `apm update` refreshes dependencies, and
+`apm install --frozen` is the lockfile-only CI install (mirrors
+`npm ci`). The CLI binary itself updates via `apm self-update`.
+:::
+
+## Anatomy of `apm.lock.yaml`
+
+The lockfile pins every resolved dependency to an exact commit and content
+hash so two clones of the repo install byte-identical primitives. Generated
+by `apm install`; commit it.
+
+```yaml
+lockfile_version: '1'
+generated_at: '2026-04-21T21:45:34.516938+00:00'
+apm_version: 0.10.0
+
+dependencies:
+  - repo_url: https://github.com/microsoft/apm-sample-package
+    resolved_commit: a1b2c3d4e5f6...           # Exact SHA installed
+    resolved_ref: v1.0.0                       # Tag/branch the SHA came from
+    version: 1.0.0                             # SemVer if available
+    depth: 1                                   # 1 = direct, 2+ = transitive
+    package_type: APM_PACKAGE
+    content_hash: sha256:9f...                 # Hash of the package file tree
+    deployed_files:                            # What this dep wrote to disk
+      - .github/skills/review/SKILL.md
+    deployed_file_hashes:
+      .github/skills/review/SKILL.md: sha256:c4...
+
+  # A single-primitive (virtual) import looks like this:
+  - repo_url: https://github.com/github/awesome-copilot
+    virtual_path: skills/review-and-refactor
+    is_virtual: true
+    resolved_commit: 7e8f9a...
+    depth: 1
+
+mcp_servers:
+  - microsoft/azure-devops-mcp
+
+# The package's own local content. Same hashing logic as deps; lets
+# `apm audit` detect hand-edits to deployed files.
+local_deployed_files:
+  - .github/instructions/python.instructions.md
+local_deployed_file_hashes:
+  .github/instructions/python.instructions.md: sha256:45...
+```
+
+### Field reference
+
+Top-level fields:
+
+| Field                          | Notes                                          |
+|--------------------------------|------------------------------------------------|
+| `lockfile_version`             | Schema version of the lockfile.                |
+| `generated_at`                 | ISO timestamp of last write.                   |
+| `apm_version`                  | CLI version that generated the file.           |
+| `dependencies`                 | List of `LockedDependency` entries.            |
+| `mcp_servers`                  | Resolved MCP server identifiers.               |
+| `mcp_configs`                  | Per-harness MCP configuration blobs.           |
+| `local_deployed_files`         | Files this package wrote to deployed dirs.     |
+| `local_deployed_file_hashes`   | SHA-256 of each local-deployed file.           |
+
+Per-dependency fields:
+
+| Field                  | Notes                                          |
+|------------------------|------------------------------------------------|
+| `repo_url`             | Canonical clone URL.                           |
+| `host`, `port`         | For non-github.com or non-standard ports.      |
+| `registry_prefix`      | Artifactory-style prefix.                      |
+| `resolved_commit`      | Full SHA. The thing that makes installs reproducible. |
+| `resolved_ref`         | Original tag/branch the SHA was resolved from. |
+| `version`              | SemVer, if the dep is versioned.               |
+| `virtual_path`         | Subpath for single-primitive imports.          |
+| `is_virtual`           | True for primitive-form deps.                  |
+| `depth`                | 1 = direct dependency; >1 = transitive.        |
+| `package_type`         | `APM_PACKAGE`, `CLAUDE_SKILL`, `HYBRID`.       |
+| `deployed_files`       | Files this dep wrote to your tree.             |
+| `deployed_file_hashes` | SHA-256 of each deployed file.                 |
+| `source`, `local_path` | Set for `local_path:` deps.                    |
+| `content_hash`         | SHA-256 of the package file tree.              |
+| `is_dev`               | True for `devDependencies` entries.            |
+
+`apm audit` rehashes everything in `deployed_file_hashes` and
+`local_deployed_file_hashes` to detect hand-edits before they ship.
+
+## The `.apm/` directory
+
+`.apm/` is the source root. APM does not look elsewhere for primitives. Each
+subdirectory holds one primitive type; file naming conventions are
+documented per type.
+
+- **`instructions/`** -- Always-on rules attached to file globs (e.g. "for
+  every `*.py`, follow PEP 8"). One Markdown file per rule. Compiled into
+  `.github/instructions/`, `.cursor/rules/`, and the equivalent for other
+  harnesses.
+- **`skills/<name>/SKILL.md`** -- Multi-file capabilities. The `SKILL.md`
+  is the entry point; sibling files (templates, scripts, references) ship
+  alongside it. Loaded on demand by harnesses that support skills.
+- **`prompts/`** -- Reusable prompt templates, one `.prompt.md` per prompt.
+  Invocable via `apm run <script>` or directly by the harness CLI.
+- **`agents/`** -- Named agent definitions: model choice, system prompt,
+  tool whitelist. One `.agent.md` per agent.
+- **`chatmodes/`** -- Chat-mode configurations for harnesses that expose
+  modes (e.g. Copilot Chat).
+- **`context/`** -- Shared context fragments that other primitives can
+  reference. Not loaded standalone.
+- **`hooks/`** -- Lifecycle hooks fired on pre/post install, compile, or
+  run events.
+
+For what each primitive type can reach inside which harness, see
+[Primitives and targets](/apm/concepts/primitives-and-targets/).
diff --git a/docs/src/content/docs/concepts/primitives-and-targets.md b/docs/src/content/docs/concepts/primitives-and-targets.md
new file mode 100644
index 000000000..19ea8ee2a
--- /dev/null
+++ b/docs/src/content/docs/concepts/primitives-and-targets.md
@@ -0,0 +1,143 @@
+---
+title: "Primitives and Targets"
+description: "The full reach map: every APM primitive against every supported harness."
+sidebar:
+  order: 3
+---
+
+A **primitive** is a unit of agent context APM can manage: instructions, prompts, agents, skills, hooks, commands, plugins, and MCP servers. A **target** is a harness APM compiles primitives for: Copilot, Claude, Cursor, Codex, Gemini, OpenCode, and Windsurf. The matrix below is the full reach map. For any primitive X and harness Y, it tells you whether Y receives X natively, receives it after APM transforms it, or does not receive it at all.
+
+This page is the canonical reference. Tutorials and how-tos link here; do not duplicate.
+
+## Primitive catalogue
+
+APM authors place primitives under `.apm/` in their package. APM discovers, validates, and routes them at `apm install` (per-target) and `apm compile` (aggregated context files).
+
+### Instructions
+
+Coding standards and guidelines, scoped by file glob.
+
+- Source: `.apm/instructions/*.instructions.md`
+- Frontmatter: `description` (required), `applyTo` (optional glob)
+- Deep dive: see [Anatomy of an APM Package](/apm/concepts/package-anatomy/)
+
+### Prompts
+
+Executable, parameterized AI workflows. Equivalent to a callable program for an LLM.
+
+- Source: `.apm/prompts/*.prompt.md`
+- Also surfaced as **commands** for harnesses that read slash-commands (see commands row below).
+- Deep dive: [Prompts guide](/apm/producer/author-primitives/prompts/)
+
+### Agents
+
+Specialized AI personalities with tool boundaries and expertise scope.
+
+- Source: `.apm/agents/*.agent.md` (legacy: `.chatmode.md`)
+- Deep dive: [Agent workflows](/apm/producer/author-primitives/instructions-and-agents/)
+
+### Skills
+
+Cross-tool meta-guides authored in the agent-skills `SKILL.md` format. Bundled resources live alongside the skill.
+
+- Source: `.apm/skills/<name>/SKILL.md` or root `SKILL.md`
+- Deep dive: [Skills guide](/apm/producer/author-primitives/skills/)
+
+### Hooks
+
+Lifecycle event handlers (e.g. `PreToolUse`, `PostToolUse`, `Stop`) that invoke scripts.
+
+- Source: `.apm/hooks/*.json` (or top-level `hooks/`)
+- Deep dive: [MCP servers + hooks](/apm/consumer/install-mcp-servers/)
+
+### Commands
+
+Slash-commands for harnesses that expose a command palette. Sourced from `.apm/prompts/` -- there is no separate `.apm/commands/` directory. The same `.prompt.md` file becomes Copilot's prompt and Claude's `/command`.
+
+### Plugins
+
+A packaging format. A plugin is a self-contained bundle (`plugin.json` or `.claude-plugin/`) that ships a set of primitives. APM normalizes plugins at install time into the same primitives the rest of this page describes.
+
+- Source: `plugin.json` at package root
+- Deep dive: [Plugins guide](/apm/producer/author-primitives/)
+
+### MCP servers
+
+Model Context Protocol servers declared as dependencies. APM writes the per-harness MCP config file at install time.
+
+- Source: `apm.yml` -> `dependencies.mcp:`
+- Deep dive: [MCP servers](/apm/consumer/install-mcp-servers/)
+
+## Target catalogue
+
+Each target is identified by a slug used in `apm.yml`'s `targets:` field and on the `--target` flag. The output directory is where APM writes deployed primitives. The "agent-skills" and "copilot-cowork" targets exist in the registry but are not end-user runtimes; they are covered separately in the experimental reference.
+
+| Slug | Output directory | Compile family |
+|---|---|---|
+| `copilot` | `.github/` (project), `~/.copilot/` (user scope) | vscode |
+| `claude` | `.claude/` | claude |
+| `cursor` | `.cursor/` | agents |
+| `codex` | `.codex/` plus `.agents/` for skills | agents |
+| `gemini` | `.gemini/` | gemini |
+| `opencode` | `.opencode/` (project), `~/.config/opencode/` (user) | agents |
+| `windsurf` | `.windsurf/` (project), `~/.codeium/windsurf/` (user) | agents |
+
+Notes per target:
+
+- **copilot** -- GitHub Copilot (CLI + IDE). User-scope partial: prompts and instructions are project-scope only.
+- **claude** -- Claude Code. Full user-scope support. Hooks merge into `.claude/settings.json` rather than living as separate files.
+- **cursor** -- Cursor IDE. Rules use the `.mdc` extension. Instructions are not deployable at user scope (Cursor exposes them via the Settings UI only).
+- **codex** -- Codex CLI. Agents and hooks use TOML; skills use the cross-tool `.agents/` directory.
+- **gemini** -- Gemini CLI. Commands are TOML. Hooks merge into `.gemini/settings.json`. No native agents or instructions primitives -- both arrive via compiled context files.
+- **opencode** -- OpenCode. No hooks support.
+- **windsurf** -- Windsurf / Cascade. Agents are delivered as auto-invokable skills under `.windsurf/skills/`. Workflows are the harness's name for commands.
+
+## The compatibility matrix
+
+Rows are primitives, columns are harnesses. Cell legend:
+
+- **native** -- the harness reads this primitive directly from its own format and directory; APM writes the file as-is or in the harness's documented format.
+- **compiled** -- APM transforms the primitive into a different format the harness understands (e.g. a prompt becomes a TOML command, an instruction is folded into `AGENTS.md`).
+- **unsupported** -- APM does not deliver this primitive to this harness.
+- **gated** -- delivered behind a flag or trust prompt.
+
+| Primitive | Copilot | Claude | Cursor | Codex | Gemini | OpenCode | Windsurf |
+|---|---|---|---|---|---|---|---|
+| instructions | native | native | native | compiled | compiled | compiled | native |
+| prompts | native | compiled | compiled | unsupported | compiled | compiled | compiled |
+| agents | native | native | compiled | compiled | unsupported | native | compiled |
+| skills | native | native | native | native | native | native | native |
+| hooks | native | native | native | native | native | unsupported | native |
+| commands | unsupported | native | compiled | unsupported | compiled | compiled | compiled |
+| plugins | compiled | compiled | compiled | compiled | compiled | compiled | compiled |
+| MCP servers | native | native | native | native | native | native | native |
+
+How to read a cell:
+
+- `instructions / claude = native` -- APM writes `.claude/rules/<name>.md`; Claude Code reads it directly.
+- `prompts / claude = compiled` -- APM transforms `.apm/prompts/<n>.prompt.md` into `.claude/commands/<n>.md`. The prompt becomes a `/command`.
+- `agents / gemini = unsupported` -- Gemini CLI has no agents primitive; APM does not deliver `.agent.md` files to it. Their content still reaches Gemini through the compiled `GEMINI.md` if referenced from instructions.
+- `commands / copilot = unsupported` -- Copilot has no commands primitive; the same source `.prompt.md` reaches Copilot as a native prompt instead.
+- `plugins / *` -- APM unpacks the plugin at install time into the primitives in the rows above; routing then follows those rows.
+- `MCP servers / *` -- APM writes the harness's standard MCP config. Transitive MCP servers brought in by deep dependencies require an explicit trust prompt at install -- effectively `gated` for those, `native` for direct dependencies.
+
+## Dev-only primitives
+
+Mark a primitive as dev-only when it is useful to the package author but should not ship to consumers: release checklists, internal debugging agents, test-fixture skills, anything tied to your own infrastructure. Author such primitives outside `.apm/` (typically `dev/`) and reference them under `devDependencies` in `apm.yml`. `apm pack` excludes them; `apm install --dev` deploys them locally.
+
+Full pattern, the three pack-time gotchas, and verification steps: [Dev-only primitives](/apm/producer/author-primitives/).
+
+## How a target is selected
+
+`apm install` and `apm compile` resolve active targets in this order:
+
+1. Explicit `--target <slug>` flag, when passed.
+2. The `targets:` field in `apm.yml`, when present.
+3. Auto-detection: any harness whose root directory (`.github/`, `.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.windsurf/`) already exists in the workspace is selected.
+4. Fallback: `minimal` -- APM writes `AGENTS.md` only and skips folder
+   integration. Create one of the harness folders above (or set
+   `targets:` explicitly) for full integration.
+
+Unknown target slugs are rejected upstream by the manifest parser; they never silently fall through to the default.
+
+For flag reference and exact resolution semantics, see [`apm compile` and `apm install`](/apm/reference/cli/install/). For policy controls that further restrict which primitives a target may deploy, see [Governance guide](/apm/enterprise/governance-guide/).
diff --git a/docs/src/content/docs/concepts/the-three-promises.md b/docs/src/content/docs/concepts/the-three-promises.md
new file mode 100644
index 000000000..cfcd75a8e
--- /dev/null
+++ b/docs/src/content/docs/concepts/the-three-promises.md
@@ -0,0 +1,149 @@
+---
+title: The Three Promises
+description: The canonical spine APM is built around -- portable, secure, governed.
+sidebar:
+  order: 2
+---
+
+APM ships three promises. They are deliberately small and load-bearing.
+Every command, every flag, every lockfile field exists to back one of
+these three.
+
+## Promise 1: Portable by manifest
+
+One `apm.yml`. Seven harnesses. Reproducible AI agent setup.
+
+Every developer who clones the repo runs `apm install` and gets the
+same skills, prompts, instructions, hooks, and MCP servers wired into
+Copilot, Claude, Cursor, OpenCode, Codex, Gemini, and Windsurf. The
+lockfile pins exact versions and content hashes. New contributor
+onboarding for AI context goes from "follow this 12-step README" to
+one command.
+
+The 10-second demo:
+
+```bash
+git clone <repo> && cd <repo> && apm install
+```
+
+### Proof in the source
+
+- `src/apm_cli/models/apm_package.py` -- the `apm.yml` schema: one
+  manifest, one set of dependencies, one set of `agentsmd` /
+  `chatmodes` / `instructions` / `prompts` / `mcp` blocks consumed by
+  every harness.
+- `src/apm_cli/integration/targets.py` -- the registered harnesses an
+  install fans out to (Copilot, Claude, Cursor, Codex, Gemini,
+  OpenCode, Windsurf, plus VS Code and the `llm` CLI as delivery
+  surfaces).
+- `src/apm_cli/deps/lockfile.py` -- the `LockEntry.content_hash`
+  field (SHA-256 of the package file tree) that makes "same install
+  on every clone" mean byte-for-byte the same.
+
+### Read more
+
+- Lifecycle of an install: [Lifecycle](/apm/concepts/lifecycle/)
+- Lockfile fields and semantics: [CLI commands](/apm/reference/cli/install/)
+
+## Promise 2: Secure by default
+
+Every `apm install` scans for hidden Unicode before agents read it.
+
+Agent context is executable -- a prompt is a program for an LLM. APM
+treats it that way. Each install scans for invisible Unicode that can
+hijack agent behavior, pins content hashes in the lockfile, and gates
+transitive MCP servers behind explicit trust prompts. `apm audit`
+rebuilds context in scratch and diffs against your working tree to
+catch hand-edits before they ship.
+
+The 10-second demo:
+
+```bash
+apm audit
+```
+
+### Proof in the source
+
+- `src/apm_cli/security/content_scanner.py` -- the `ContentScanner`
+  class and the Unicode tag / bidi / zero-width / invisible-operator
+  ranges it flags. `scan_text()` is what every install runs against
+  every primitive file.
+- `src/apm_cli/install/helpers/security_scan.py` -- the
+  `_pre_deploy_security_scan` hook that runs before any file is
+  written to the project tree, via `SecurityGate.scan_files()` with
+  the install pipeline's `BLOCK_POLICY`.
+- `src/apm_cli/deps/lockfile.py` -- `LockEntry.content_hash` pins the
+  exact tree per dependency; `ci_checks._check_content_integrity`
+  re-verifies it on every audit.
+- `src/apm_cli/commands/audit.py` -- `apm audit` wires the scan,
+  hash-drift detection, and the scratch rebuild diff into one
+  command, with `--strip` to remediate.
+
+### Read more
+
+- Security model and threat coverage: [Security](/apm/enterprise/security/)
+
+## Promise 3: Governed by policy
+
+Org policy enforced at install time, before MCP touches disk.
+
+`apm-policy.yml` lets a security team allow-list sources, scopes, and
+primitives. Every `apm install` runs the policy *before* writing to
+disk -- including transitive MCP servers shipped by deep
+dependencies. Tighten-only inheritance flows enterprise -> org ->
+repo. `apm audit --ci` wires the same checks into branch protection.
+This is the supply-chain check npm and pip cannot do.
+
+The 10-second demo:
+
+```bash
+apm install --dry-run <package>
+```
+
+### Proof in the source
+
+- `src/apm_cli/policy/install_preflight.py` --
+  `run_policy_preflight()` is the install-time gate; it evaluates the
+  resolved dependency graph (including transitive MCP servers)
+  against the merged policy before any download or write.
+- `src/apm_cli/policy/inheritance.py` -- `merge_policies()` and
+  `resolve_policy_chain()` implement the tighten-only enterprise
+  -> org -> repo flow with `_escalate()` enforcement.
+- `src/apm_cli/policy/ci_checks.py` -- `run_baseline_checks()` is
+  the CI surface used by `apm audit --ci`. It runs 8 baseline
+  checks: lockfile-exists, ref-consistency, deployed-files-present,
+  no-orphans, skill-subset-consistency, config-consistency,
+  content-integrity, and includes-consent.
+
+### Read more
+
+- Policy schema, inheritance, CI wiring: [Governance guide](/apm/enterprise/governance-guide/)
+
+## FAQ
+
+### Is this just `npm` for prompts?
+
+The verbs rhyme on purpose -- `apm install`, `apm update`,
+`apm list`, `apm prune`. The package model does not. APM resolves
+primitives (skills, prompts, instructions, hooks, MCP servers) and
+deploys them into seven different agent harnesses from one manifest.
+npm has no equivalent of the harness fan-out, the install-time
+policy gate, or the Unicode scan. Promise 1 is the npm-shaped half;
+Promise 2 and Promise 3 are not.
+
+### Why a lockfile?
+
+Two reasons. First, reproducibility: pinned refs plus content
+hashes mean every clone and every CI run gets the same files.
+Second, integrity: `content_hash` lets `apm audit` detect any drift
+between what the lockfile says you installed and what is on disk
+right now -- including hand-edits to files inside `apm_modules/`.
+
+### What does the policy engine actually block?
+
+At install time: dependencies from disallowed sources or scopes,
+primitives outside the allow-list, and transitive MCP servers that
+fail any of the configured trust rules -- evaluated before any
+download. In CI via `apm audit --ci`: the 8 baseline checks above,
+which catch lockfile drift, missing deployed files, orphaned
+packages, and content-hash mismatches before a PR can merge.
diff --git a/docs/src/content/docs/concepts/what-is-apm.md b/docs/src/content/docs/concepts/what-is-apm.md
new file mode 100644
index 000000000..1f1e5f2c6
--- /dev/null
+++ b/docs/src/content/docs/concepts/what-is-apm.md
@@ -0,0 +1,75 @@
+---
+title: What is APM?
+description: APM is a dependency manager for AI agent context, with a lockfile, a policy engine, and one install gesture across every major harness.
+sidebar:
+  order: 1
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+APM is a dependency manager for AI agent context -- skills, prompts, instructions, hooks, MCP servers -- with a lockfile, a policy engine, and one install gesture across every major harness.
+
+## The mental model
+
+APM borrows the manifest-plus-lockfile shape from `npm`, `pip`, and `cargo` and applies it to the files that configure AI coding agents. You declare what your agents need in `apm.yml`, run `apm install`, and APM resolves the full dependency tree -- including transitive dependencies -- into a tree of harness-native files.
+
+`apm.yml` is the manifest. It lists agentic dependencies (skills, prompts, agents, plugins, full APM packages) and MCP servers. `apm.lock.yaml` is the lockfile. It pins every resolved package to an exact source ref and content hash, so two developers running `apm install` against the same lockfile get byte-identical context. Source authoring lives in `.apm/` inside your repo.
+
+The compiled output lives in the directories each harness already reads: `.github/` for Copilot, `.claude/` for Claude Code, `.cursor/` for Cursor, `.codex/` and `AGENTS.md` for Codex, `.gemini/` for Gemini, `.opencode/` for OpenCode, `.windsurf/` for Windsurf. APM does not invent a runtime format. It writes the files each tool already understands and stays out of the way at agent runtime.
+
+## What APM manages
+
+These are the primitive types you can declare in `apm.yml` or ship in a package. Every other concept page links here as the source of truth.
+
+| Primitive | What it is |
+|---|---|
+| Instructions | Repository-scoped guardrails and coding standards the agent reads on every turn. |
+| Skills | Reusable, model-invocable capabilities packaged as Agent Skills. |
+| Prompts | Slash commands and saved prompts the user invokes by name. |
+| Agents | Specialized personas with their own scope, tools, and system prompt. |
+| Hooks | Lifecycle handlers that run before or after agent tool calls. |
+| Commands | Custom CLI-style commands a harness exposes inside the agent UI. |
+| Plugins | Bundles of the primitives above, packaged for one-shot install. |
+| MCP servers | External tools the agent connects to via Model Context Protocol. |
+
+For deeper definitions, see [Primitives and targets](../primitives-and-targets/). For the on-disk layout of a package, see [Package anatomy](../package-anatomy/).
+
+## What APM is not
+
+- **Not a runtime.** APM ships context to the harness; the harness runs the agent. `apm install` writes files and exits.
+- **Not an LLM gateway.** APM does not route, proxy, or meter model calls. It does not see your prompts at inference time.
+- **Not a fine-tuning tool.** APM versions context, not weights.
+- **Not a marketplace.** Any git repository is a valid APM package. Marketplaces are an optional discovery surface, not a requirement.
+
+## The three promises
+
+APM commits to three things. Each gets a one-paragraph summary here; the deep dive lives in [The three promises](../the-three-promises/).
+
+### Portable by manifest
+
+One `apm.yml`. Seven harnesses. Reproducible AI agent setup. Every developer who clones the repo runs `apm install` and gets the same skills, prompts, instructions, hooks, and MCP servers wired into Copilot, Claude, Cursor, OpenCode, Codex, Gemini, and Windsurf. The lockfile pins exact versions and content hashes.
+
+### Secure by default
+
+Every `apm install` scans for hidden Unicode before agents read it. Agent context is executable -- a prompt is a program for an LLM. APM treats it that way. Each install scans for invisible Unicode that can hijack agent behavior, pins content hashes in the lockfile, and gates transitive MCP servers behind explicit trust prompts. `apm audit` rebuilds context in scratch and diffs against your working tree.
+
+### Governed by policy
+
+Org policy enforced at install time, before MCP touches disk. `apm-policy.yml` lets a security team allow-list sources, scopes, and primitives. Every `apm install` runs the policy before writing to disk -- including transitive MCP servers shipped by deep dependencies. Tighten-only inheritance flows enterprise -> org -> repo. `apm audit --ci` wires the same checks into branch protection.
+
+## Where to next
+
+<CardGrid>
+  <Card title="Consumer" icon="rocket">
+    Run someone's package on your harness.
+    [Quickstart](/apm/quickstart/)
+  </Card>
+  <Card title="Producer" icon="puzzle">
+    Author and publish primitives others can install.
+    [Primitives and targets](../primitives-and-targets/)
+  </Card>
+  <Card title="Enterprise" icon="approve-check">
+    Gate org installs on policy and audit in CI.
+    [Governance overview](/apm/enterprise/governance-overview/)
+  </Card>
+</CardGrid>
diff --git a/docs/src/content/docs/consumer/authentication.md b/docs/src/content/docs/consumer/authentication.md
new file mode 100644
index 000000000..1c6fe8092
--- /dev/null
+++ b/docs/src/content/docs/consumer/authentication.md
@@ -0,0 +1,98 @@
+---
+title: Authentication
+description: Install public packages with no setup; add one env var or use your git credential helper for any private host -- GitHub, GitLab, Azure DevOps, Bitbucket, Gitea, or self-hosted.
+---
+
+APM resolves dependencies from any git host you can `git clone` from. Public packages on github.com need zero setup. Other hosts -- GitHub Enterprise, GitLab (SaaS or self-managed), Azure DevOps, Bitbucket, Gitea, or any self-hosted git server -- need either one env var or your existing git credential helper.
+
+```bash
+apm install
+```
+
+## The 30-second answer
+
+Pick the path that matches your dependencies:
+
+- **All public github.com packages.** Do nothing.
+- **Private github.com / GHE.com / GHES packages.** Either run `gh auth login` (recommended) or set `GITHUB_APM_PAT`.
+- **GitLab packages (SaaS or self-managed).** Set `GITLAB_APM_PAT`, or rely on your `git credential` helper.
+- **Azure DevOps packages.** Run `az login`, or set `ADO_APM_PAT`.
+- **Bitbucket, Gitea, or any other git host.** Use your existing `git credential` helper -- if `git clone <url>` works in your shell, `apm install` works too.
+
+That covers the consumer case. The rest of this page expands each path.
+
+## Already signed in with `gh`?
+
+If you have run `gh auth login` and you can do `gh repo clone <your-org>/<repo>`,
+APM picks that up automatically. There is nothing else to set.
+
+Under the hood, APM calls `gh auth token --hostname <host>` after the
+env-var lookups; if `gh` is not installed or not logged in for the host,
+it is silently skipped.
+
+## Setting `GITHUB_APM_PAT`
+
+If you prefer an explicit token (CI, devcontainers, scripts):
+
+```bash
+export GITHUB_APM_PAT=ghp_your_token
+apm install
+```
+
+Use a fine-grained or classic PAT with **read** access to the repos your
+manifest references. For an org's private repos, the PAT must be
+authorized for that org.
+
+For the org-private case, see [Private and org packages](../private-and-org-packages/).
+
+## GitLab (SaaS or self-managed)
+
+If a dependency lives on `gitlab.com` or your self-hosted GitLab:
+
+```bash
+export GITLAB_APM_PAT=glpat_your_token
+apm install
+```
+
+Use a project- or group-scoped token with **read_repository** scope. Self-managed GitLab works with the same env var; APM resolves the host from the dependency URL.
+
+If you have configured a git credential helper for GitLab (e.g. `git credential-manager` on Windows / macOS), APM falls back to it after the env-var lookup -- you do not need `GITLAB_APM_PAT` if `git clone https://gitlab.com/<your-group>/<repo>` already prompts you once and caches.
+
+`GITLAB_TOKEN` is also accepted as a lower-precedence fallback for compatibility with CI environments that already set it.
+
+## Azure DevOps
+
+If a dependency lives on `dev.azure.com/...`:
+
+```bash
+az login --tenant <your-tenant-id>
+apm install
+```
+
+Or, if you cannot use `az`:
+
+```bash
+export ADO_APM_PAT=your_ado_pat
+apm install
+```
+
+ADO is always auth-required -- there is no anonymous fallback.
+
+## Bitbucket, Gitea, and any other git host
+
+For any git host APM does not have a platform-specific PAT for -- Bitbucket Cloud or Server, Gitea, self-hosted Forgejo, an enterprise git mirror -- APM resolves credentials through the same `git credential` helper your shell uses.
+
+```bash
+git clone https://your-host.example.com/team/repo.git  # cache the credential once
+apm install                                             # APM picks up the cached credential
+```
+
+There is no APM-specific env var for these hosts by design: if you can `git clone`, APM can install. Configure your credential helper once (`git credential-manager`, Keychain, libsecret, plain-text store -- whatever your shell uses) and `apm install` follows the same path git already trusts.
+
+For non-interactive environments (CI, devcontainers), set the credential through your CI's secret store and configure `git config --global credential.helper store` against a runtime-injected `~/.git-credentials` file.
+
+## Going further
+
+Token scopes, SSO authorization, Enterprise Managed Users (EMU), GHES hostnames, multi-org `GITHUB_APM_PAT_{ORG}` setups, GitLab self-managed FQDN routing, and the ADO bearer fallback are covered in the [enterprise authentication](../../enterprise/security/) page.
+
+For how a token is used once resolved, see [Private and org packages](../private-and-org-packages/).
diff --git a/docs/src/content/docs/consumer/deploy-a-bundle.md b/docs/src/content/docs/consumer/deploy-a-bundle.md
new file mode 100644
index 000000000..dd5d2dc8a
--- /dev/null
+++ b/docs/src/content/docs/consumer/deploy-a-bundle.md
@@ -0,0 +1,131 @@
+---
+title: Deploy a local bundle
+description: Install a plugin-format bundle from a directory or tarball without touching apm.yml.
+---
+
+You have a bundle on disk -- a directory or `.tar.gz` someone handed you, or
+the output of `apm pack --format plugin`. Drop it into a project with one
+command:
+
+```bash
+apm install ./path/to/bundle
+apm install ./dist/my-pkg-1.0.0.tar.gz
+```
+
+This is a sibling flow to [Install packages](../install-packages/). Instead
+of declaring a dependency in `apm.yml` and resolving it from a registry, you
+deploy a self-contained bundle directly. `apm.yml` is **not modified** --
+the install is imperative, like `dpkg -i` next to `apt install`.
+
+## What counts as a bundle
+
+A plugin-format bundle is a directory (or gzipped tarball of one) with a
+`plugin.json` at the root and primitive folders alongside it:
+
+```
+my-bundle/
++-- plugin.json
++-- agents/
++-- skills/
++-- commands/
++-- hooks/
++-- apm.lock.yaml        # optional: bundle integrity manifest
+```
+
+`plugin.json` requires only a `name`. APM also recognises `plugin.json`
+under `.github/plugin/`, `.claude-plugin/`, or `.cursor-plugin/`. For the
+full schema see [Package anatomy](../../concepts/package-anatomy/).
+
+The optional `apm.lock.yaml` carries `pack.bundle_files` -- a SHA-256
+manifest written by `apm pack --format plugin`. When present, APM verifies
+every file against it before deploying. When absent (older bundles), APM
+warns and proceeds.
+
+## How the install works
+
+```
+$ apm install ./dist/my-pkg-1.0.0.tar.gz --target copilot
+[>] Installing local bundle from ./dist/my-pkg-1.0.0.tar.gz
+[+] Bundle integrity verified
+[+] Deployed 7 files to .github/
+```
+
+Steps APM runs:
+
+1. **Detect.** Path exists and contains `plugin.json` at the bundle root
+   (tarballs are extracted to a temp directory first).
+2. **Verify integrity.** Hash every file listed in `pack.bundle_files`;
+   reject any symlink, hash mismatch, or unlisted file.
+3. **Deploy.** Map `agents/`, `skills/`, `commands/`, `hooks/` into the
+   harness layout for each `--target` you passed.
+4. **Record.** Write a lockfile entry under the project's `apm.lock.yaml`
+   so [drift detection](../drift-and-secure-by-default/) can audit the
+   deployed files later.
+
+`apm.yml` is never touched. Re-running the same command re-deploys (use
+`--force` to overwrite locally-edited files).
+
+## Flags that apply
+
+Most `apm install` flags target the registry/resolver pipeline and are
+**rejected** with a single error when used with a local bundle. The flags
+that *do* work:
+
+| Flag | Use |
+|---|---|
+| `--target`, `-t`     | Pick which harness layouts receive files. |
+| `--global`, `-g`     | Deploy to `~/.apm/` instead of the current project. |
+| `--force`            | Overwrite locally-edited files on collision. |
+| `--dry-run`          | Show what would be deployed; write nothing. |
+| `--verbose`, `-v`    | Print per-file deploy details. |
+| `--as ALIAS`         | Override the display label in logs (local-bundle only). |
+
+Flags like `--update`, `--only`, `--dev`, `--mcp`, `--registry`, and
+`--allow-insecure` are not meaningful here -- the imperative deploy path
+does not run the resolver, MCP registry lookup, or policy chain that those
+flags configure. APM rejects them up front with one consolidated error.
+
+For the full flag list see the [`apm install` reference](../../reference/cli/install/).
+
+## Targets
+
+Pass `--target` to scope the deploy. Without it APM auto-detects from the
+current project. If the bundle was packed for targets you are not
+installing into, APM prints a warning naming the missing targets and
+proceeds with what it can deploy.
+
+A bundle packed with `pack.target: all` is target-agnostic and installs
+cleanly into any harness layout.
+
+## Legacy `--format apm` bundles are rejected
+
+Bundles produced by the older `apm pack --format apm` carry an
+`apm.lock.yaml` at their root but **no `plugin.json`**. `apm install`
+rejects these with a targeted error:
+
+```
+'./dist/my-pkg-0.1.0.tar.gz' was packed with '--format apm' (legacy
+format). 'apm install <bundle>' requires the plugin format. Repack with
+'apm pack --format plugin --archive', or use 'apm unpack' to deploy the
+legacy bundle.
+```
+
+Two ways forward:
+
+- **Repack.** If you own the bundle, run
+  `apm pack --format plugin --archive` and install the new artifact.
+- **Unpack.** If you only have the legacy artifact, use `apm unpack
+  <bundle>` to extract it. `apm unpack` is deprecated and will be removed
+  in v0.14; prefer repacking when you can.
+
+A plain directory without `plugin.json` is not treated as a bundle at all.
+APM falls through to the dependency resolver and treats the path as a
+local-path dependency -- a different flow covered in [Install packages](../install-packages/).
+
+## What to read next
+
+- [Install packages](../install-packages/) -- the manifest-driven flow.
+- [Drift and secure by default](../drift-and-secure-by-default/) -- audit
+  what a bundle deployed.
+- [Package anatomy](../../concepts/package-anatomy/) -- the file layout
+  reference.
diff --git a/docs/src/content/docs/consumer/drift-and-secure-by-default.md b/docs/src/content/docs/consumer/drift-and-secure-by-default.md
new file mode 100644
index 000000000..acb34ded4
--- /dev/null
+++ b/docs/src/content/docs/consumer/drift-and-secure-by-default.md
@@ -0,0 +1,160 @@
+---
+title: Drift and secure by default
+description: What protects you when you run apm install, and what to do when something is off.
+---
+
+You run `apm install`. APM fetches packages, writes files into your
+project, and wires them into every supported harness. This page covers
+the checks that run on every install, what triggers a failure, and the
+one command -- `apm audit` -- that lets you re-verify on demand.
+
+The short version: your dependency graph is explicit, your lockfile is
+pinned, fetched content is hash-verified, and every install replay is
+reproducible from the cache. You do not opt in. You opt out, and only
+through named flags.
+
+## What runs on every `apm install`
+
+Three checks run automatically, in this order, before any file lands in
+your harness directories.
+
+### 1. Lockfile consistency
+
+`apm.yml` declares what you want. `apm.lock.yaml` records what was
+resolved last time. On install, APM reconciles the two:
+
+- A dependency in `apm.yml` with no lockfile entry is resolved fresh
+  and pinned.
+- A dependency removed from `apm.yml` but still in the lockfile is
+  pruned (orphan cleanup).
+- A dependency whose `apm.yml` ref changed (e.g. you bumped a tag) is
+  re-resolved; the new `resolved_commit` is written to the lockfile.
+
+The lockfile is regenerated from the resolution result on every
+install, so the on-disk lockfile cannot drift away from the manifest
+silently. If you commit `apm.yml` without committing the regenerated
+`apm.lock.yaml`, the next teammate's `apm install` updates it and
+reports the change.
+
+### 2. Content hash verification
+
+When APM fetches a package fresh from the network, it computes a
+SHA-256 over the package file tree and compares it to the
+`content_hash` recorded in `apm.lock.yaml`. On mismatch, the install
+aborts:
+
+```
+[x] Content hash mismatch for owner/repo: expected sha256:abc..., got sha256:def...
+    The downloaded content differs from the lockfile record.
+    This may indicate a supply-chain attack.
+    Use 'apm install --update' to accept new content and update the
+    lockfile.
+```
+
+Exit code is non-zero and the partially-downloaded directory is
+removed before APM exits. Source: `src/apm_cli/install/sources.py`.
+
+The opt-in escape hatch is `apm install --update`, which re-resolves
+refs and accepts new content into the lockfile. Use it when you
+intentionally bumped a dependency upstream and expect the hash to
+change.
+
+### 3. Cache-hit integrity
+
+A warm cache is fast but dangerous: if anything mutated the cached
+checkout (a poisoned shared CI runner, a stale teammate workspace, a
+manual `git checkout` inside `apm_modules/`), reusing it would deploy
+wrong content under the right name.
+
+On every cache hit, APM reads the checkout's `.git/HEAD` and verifies
+it matches the `resolved_commit` from the lockfile. On mismatch, the
+cache entry is evicted and a fresh fetch runs. The check reads the
+HEAD ref file directly rather than spawning `git rev-parse`, so a
+poisoned `.git/config` cannot subvert it. Source:
+`src/apm_cli/cache/integrity.py`.
+
+Install also drops a small `.apm-pin` marker at each package root
+recording the `resolved_commit` it deployed. `apm audit` re-checks
+this marker before replaying the install, so a teammate who bumped
+`apm.lock.yaml` without re-running `apm install` gets a clear "run
+`apm install` first" error rather than misleading drift findings.
+
+## What "secure by default" buys you
+
+These checks rule out a specific set of failure modes without any
+configuration:
+
+- **Silent supply-chain swap.** Hash verification on fresh downloads
+  catches a publisher (or a man-in-the-middle) replacing the content
+  behind a pinned ref.
+- **Stale cache reuse.** HEAD-vs-lockfile verification on cache hits
+  catches the shared-runner and bumped-pin cases.
+- **Forgotten reinstall.** The cache-pin marker plus `apm audit`
+  detect the "I edited `apm.lock.yaml` but did not reinstall" gap.
+- **Cross-host token leak.** Auth tokens are scoped per host:
+  `GITHUB_APM_PAT` is sent only to GitHub hosts, `ADO_APM_PAT` only
+  to Azure DevOps. APM never forwards a credential to a host you did
+  not configure it for. See `../authentication/`.
+
+What these checks do **not** cover, by design:
+
+- Hidden Unicode inside primitive content (a prompt that displays as
+  one thing and parses as another). That is the `apm audit` scan
+  described below.
+- Org policy (allow-listed sources, forbidden primitives, scope
+  restrictions). Policy enforcement is an enterprise concern; see
+  [Security and supply chain](../../enterprise/security-and-supply-chain/)
+  and [Drift detection](../../enterprise/drift-detection/).
+
+## On-demand: `apm audit`
+
+`apm audit` is the explicit re-verification command. The two consumer
+use cases:
+
+```bash
+apm audit
+```
+
+Scans installed packages for hidden Unicode characters that can
+hijack agent behavior (zero-width characters, bidi overrides, tag
+characters). Default output is text; add `--format sarif` to wire
+into GitHub code-scanning or `--format json` for tooling.
+
+```bash
+apm audit --strip
+```
+
+Removes hidden characters from scanned files in place. Combine with
+`--dry-run` to preview the changes first.
+
+`apm audit` also runs **install-replay drift detection** by default:
+it replays your install into a scratch tmpdir from the cache and
+diffs the result against your working tree. Three drift kinds get
+reported:
+
+| Kind | Meaning |
+|---|---|
+| `unintegrated` | A `.apm/` source exists, but its deployed counterpart is missing. Fix: `apm install`. |
+| `modified` | A deployed file's content differs from what install would produce. Fix: revert the hand-edit, or move it into source. |
+| `orphaned` | A deployed file exists with no current source. Fix: `apm install` (orphan cleanup runs automatically). |
+
+The replay is cache-only. It does no network I/O and does not write
+to your project. If the cache is missing the entries the lockfile
+references, the audit fails fast with a "run `apm install` first"
+message rather than guessing.
+
+For the full flag set, see `../../reference/cli/install/`.
+
+## When something is off
+
+| Symptom | What it means | What to do |
+|---|---|---|
+| `Content hash mismatch` on install | Lockfile-pinned content no longer matches what the source serves | Investigate upstream; if intended, run `apm install --update` |
+| `cache pin mismatch` from `apm audit` | The cache holds content from a different `resolved_commit` than the lockfile records | `apm install` to repopulate the cache, then re-audit |
+| `unintegrated` drift | Source committed without re-running install | `apm install`, then commit the regenerated `apm.lock.yaml` |
+| `modified` drift | Hand-edit to a generated file | Revert, or move the change into the corresponding `.apm/` source |
+| Hidden-Unicode finding from `apm audit` | A primitive file contains invisible characters | `apm audit --strip` to remove them, then re-audit |
+
+None of these require disabling a check. The escape hatches
+(`--update`, `--no-drift`) exist for narrow cases and always require
+an explicit flag.
diff --git a/docs/src/content/docs/consumer/governance-on-the-consumer-ramp.md b/docs/src/content/docs/consumer/governance-on-the-consumer-ramp.md
new file mode 100644
index 000000000..381ea5005
--- /dev/null
+++ b/docs/src/content/docs/consumer/governance-on-the-consumer-ramp.md
@@ -0,0 +1,144 @@
+---
+title: Governance on the consumer ramp
+description: What apm-policy.yml means for your install, how to see which policy is in effect, and what to do when a policy blocks you.
+---
+
+If your org has set up an `apm-policy.yml`, every `apm install` you run
+is checked against it before anything is written to disk. You did not
+write this file. Your platform or security team did. This page covers
+what that means for your day-to-day work.
+
+## Where the policy lives
+
+APM auto-discovers `apm-policy.yml` from your project's git remote. For
+a repo on `github.com/your-org/your-repo`, APM looks in
+`your-org/.github/apm-policy.yml`. The file is fetched, cached, and
+re-checked on every install.
+
+You do not need to install or configure anything. If the file exists
+in your org's `.github` repository, every `apm install` run from a repo
+in that org is governed by it.
+
+## What the policy can do to your install
+
+The schema is defined in `src/apm_cli/policy/schema.py`. The fields
+your platform team can set, and what each one does to your install:
+
+- **`enforcement`** -- `warn`, `block`, or `off`. `block` aborts the
+  install on any violation; `warn` lets it proceed but logs each
+  violation; `off` disables enforcement.
+- **`dependencies.allow`** / **`dependencies.deny`** -- glob patterns
+  over package refs. A package matching `deny` (or not matching `allow`,
+  when `allow` is set) is rejected.
+- **`dependencies.require`** -- packages your `apm.yml` must include.
+- **`dependencies.max_depth`** -- maximum transitive dependency depth.
+- **`mcp.allow`** / **`mcp.deny`** -- glob patterns over MCP server
+  references. Same semantics as the dependency lists.
+- **`mcp.transport.allow`** -- restricts MCP transports
+  (`stdio`, `sse`, `http`, `streamable-http`).
+- **`mcp.self_defined`** -- `allow`, `warn`, or `deny` for MCP servers
+  declared inline in your `apm.yml` rather than pulled from a package.
+- **`mcp.trust_transitive`** -- whether MCP servers shipped by deep
+  dependencies are trusted automatically.
+- **`compilation.target.allow`** -- which harness targets your repo can
+  compile to (`vscode`, `claude`, `all`).
+- **`compilation.strategy.enforce`** -- `distributed` or `single-file`.
+- **`manifest.required_fields`** / **`manifest.scripts`** /
+  **`manifest.require_explicit_includes`** -- shape constraints on
+  your `apm.yml` itself.
+- **`unmanaged_files.action`** -- `ignore`, `warn`, or `deny` for files
+  in agent directories that the lockfile does not track.
+- **`extends`** -- the policy may inherit from another policy
+  (enterprise -> org -> repo). Inheritance only tightens; it cannot
+  loosen a parent's rules.
+
+## See which policy is in effect
+
+```bash
+apm policy status
+```
+
+Prints the active policy: where it was discovered, the enforcement
+level, the cache age, the `extends` chain, and a count of effective
+rules per section.
+
+```
+APM Policy Status
+  Outcome          found
+  Source           org:your-org/.github
+  Enforcement      block
+  Cache age        12m ago
+  Extends chain    enterprise/policies
+  Effective rules  3 dependency denies; 2 mcp transport restrictions
+```
+
+Useful flags:
+
+- `--no-cache` forces a fresh fetch.
+- `-o json` emits the same report as JSON for scripting.
+- `--policy-source <ref>` overrides discovery (e.g. point at a local
+  file you are testing).
+- `--check` exits non-zero when no policy is found, for CI pre-checks.
+
+For a deeper look at which packages would pass or fail, run:
+
+```bash
+apm audit --ci --policy org
+```
+
+This runs the full set of policy checks and reports every violation.
+
+## When your install is blocked
+
+A blocked install ends with output like:
+
+```
+[x] Install blocked by org policy -- see violations above
+```
+
+Each individual violation is rendered with its remediation hint:
+
+```
+Blocked by org policy at org:your-org/.github
+  -- remove `untrusted-org/some-pkg` from apm.yml,
+     contact admin to update policy,
+     or use `--no-policy` for one-off bypass
+```
+
+You have three options:
+
+1. **Pick a different package.** If `untrusted-org/some-pkg` is denied,
+   find an allowed alternative and update your `apm.yml`.
+2. **Ask your platform team to update the policy.** If you have a
+   legitimate reason to use the package, the policy owner can add it
+   to the `allow` list or remove it from `deny`.
+3. **Bypass for a single run with `--no-policy`.** This skips org
+   policy enforcement for that one invocation. It does not bypass
+   `apm audit --ci`, so any CI gate still catches it. Treat this as a
+   diagnostic switch, not a workflow.
+
+## Preview a policy decision before running install
+
+```bash
+apm install --dry-run
+```
+
+Runs discovery and policy checks without writing to disk. Each
+violation is reported as `Would be blocked by policy: <dep> -- <reason>`
+or `Policy warning: <dep> -- <reason>`. Useful before you commit a
+manifest change you suspect the policy will reject.
+
+## Disabling discovery
+
+Two escape hatches exist:
+
+- `--no-policy` on a single `apm install` or `apm audit` invocation.
+- `APM_POLICY_DISABLE=1` as an environment variable, for the same
+  scope as `--no-policy`.
+
+Neither hides anything from `apm audit --ci` running in CI. They only
+relax local enforcement.
+
+If you are the one writing the policy, see [Governance overview](../../enterprise/governance-overview/)
+for the platform-team view -- this page is the consumer's view of a policy
+that is already in place.
diff --git a/docs/src/content/docs/consumer/index.md b/docs/src/content/docs/consumer/index.md
new file mode 100644
index 000000000..58ad1820e
--- /dev/null
+++ b/docs/src/content/docs/consumer/index.md
@@ -0,0 +1,51 @@
+---
+title: Use APM packages
+description: Install, manage, and run APM packages in your project.
+sidebar:
+  order: 0
+---
+
+You're here because you want to install someone else's APM packages and use them in your project. This is the consumer ramp.
+
+## Where to start
+
+| Your situation                                                                 | Start here                                              |
+|--------------------------------------------------------------------------------|---------------------------------------------------------|
+| First time using APM, just want to try it                                      | [Quickstart (5 min)](../quickstart/)                    |
+| Adding APM to an existing repo                                                 | [Install packages](./install-packages/)                 |
+| You hit `Authentication failed` for a private repo                             | [Authentication](./authentication/)                     |
+| You need org-private packages or your own marketplace                          | [Private and org packages](./private-and-org-packages/) |
+| You manage `apm.yml` and need lockfile / dependency commands                   | [Manage dependencies](./manage-dependencies/)           |
+| You want APM to wire MCP servers (GitHub, Atlassian, ...) into your tools      | [Install MCP servers](./install-mcp-servers/)           |
+| You received a local `.tar.gz` bundle and need to install it                   | [Deploy a local bundle](./deploy-a-bundle/)             |
+| You hit `Drift detected` after a `git pull`                                    | [Drift and secure-by-default](./drift-and-secure-by-default/) |
+| Your org rolled out `apm-policy.yml` and your install is now blocked           | [Governance on the consumer ramp](./governance-on-the-consumer-ramp/) |
+
+## The consumer flow
+
+The four commands you'll use almost every day:
+
+```bash
+apm init                 # one-time per project
+apm install <pkg>        # add a dependency
+apm install              # restore from apm.lock.yaml
+apm run <script>         # invoke a script declared in apm.yml
+```
+
+That's the loop. Everything else is either lifecycle automation (`update`, `outdated`, `audit`) or a workflow extension (MCP servers, local bundles, scripts).
+
+## Recommended reading order
+
+1. [Install packages](./install-packages/) -- the canonical install loop.
+2. [Manage dependencies](./manage-dependencies/) -- `apm.yml`, lockfile, `update`, `outdated`.
+3. [Run scripts](./run-scripts/) -- the script runner that wraps your agent runtime of choice.
+4. [Update and refresh](./update-and-refresh/) -- when refs move, when caches go stale.
+5. Stop here unless you hit one of the situational pages above.
+
+## Producer-curious?
+
+If you want to *publish* a package others can install, switch to the [producer ramp](../producer/). The skills you build there install on the same `apm install` command everyone here is running.
+
+## Enterprise rollout?
+
+If you operate a platform team and need org-wide policy, audit, and CI gating, the [enterprise ramp](../enterprise/) is the right entry. Consumer commands are unchanged when policy is enforced -- you'll just see more `[x]` blocks at install time when something is denied.
diff --git a/docs/src/content/docs/consumer/install-mcp-servers.md b/docs/src/content/docs/consumer/install-mcp-servers.md
new file mode 100644
index 000000000..f361a82b3
--- /dev/null
+++ b/docs/src/content/docs/consumer/install-mcp-servers.md
@@ -0,0 +1,183 @@
+---
+title: "Install MCP servers"
+description: "Declare MCP servers in apm.yml and let apm install wire them into every detected harness."
+---
+
+`apm install` is the same driver for two artifact kinds: APM packages
+(see [Install Packages](../install-packages/)) and MCP servers. This
+page covers MCP servers: how you declare them, what gets written to
+each runtime, and how tokens get injected.
+
+## One-line answer
+
+```bash
+apm install --mcp io.github.github/github-mcp-server
+```
+
+This adds one entry under `dependencies.mcp:` in `apm.yml` and writes
+a runtime-specific MCP config file for every detected harness.
+
+## The `mcp:` section in apm.yml
+
+MCP servers live under `dependencies.mcp:` (or
+`devDependencies.mcp:`). Three forms are valid -- pick the one that
+matches the source you have:
+
+```yaml
+dependencies:
+  mcp:
+    # 1. Registry reference (bare string)
+    - io.github.github/github-mcp-server
+
+    # 2. 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)
+    - name: linear
+      registry: false
+      transport: http
+      url: https://mcp.linear.app/sse
+      headers:
+        Authorization: "Bearer ${LINEAR_TOKEN}"
+```
+
+The full grammar (overlays, `${input:...}` variables, `tools:`
+allowlists, `package:` selection) is in
+[Package Anatomy](../../concepts/package-anatomy/).
+
+## Adding a server from the CLI
+
+`apm install --mcp NAME` writes the entry into `apm.yml` for you,
+then runs install. Three shapes match the three manifest forms:
+
+```bash
+# Registry
+apm install --mcp io.github.github/github-mcp-server
+
+# stdio (everything after `--` is the spawn command)
+apm install --mcp filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace
+
+# Remote
+apm install --mcp linear --transport http --url https://mcp.linear.app/sse
+```
+
+`apm mcp install NAME ...` is an alias that forwards to the same code
+path. The `apm mcp` group also provides `search`, `list`, and `show`
+for discovery -- see the [CLI reference](../../reference/cli/install/).
+
+## What `apm install` writes to disk
+
+For every harness APM detects in your environment, `apm install`
+writes a runtime-specific MCP config file. The schemas differ; the
+`apm.yml` source of truth does not.
+
+| Harness | File | Scope | Format |
+|---|---|---|---|
+| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | global | JSON `mcpServers` |
+| VS Code (Copilot) | `.vscode/mcp.json` | project | JSON `servers` |
+| Claude Code | `.mcp.json` (project) or `~/.claude.json` (`-g`) | both | JSON `mcpServers` |
+| Cursor | `.cursor/mcp.json` | project (only if `.cursor/` exists) | JSON `mcpServers` |
+| Codex CLI | `~/.codex/config.toml` | global | TOML `[mcp_servers.*]` |
+| Gemini CLI | `.gemini/settings.json` | project (only if `.gemini/` exists) | JSON `mcpServers` |
+| OpenCode | `opencode.json` | project (only if `.opencode/` exists) | JSON `mcp` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | global | JSON `mcpServers` |
+
+Cursor, Gemini, and OpenCode are opt-in by directory: APM only writes
+their config when the corresponding `.cursor/`, `.gemini/`, or
+`.opencode/` directory already exists in the project. This avoids
+creating runtime artifacts for tools you do not use.
+
+`apm install -g --mcp NAME` is restricted to the two harnesses with
+true global MCP support: Copilot CLI and Codex CLI. The other
+runtimes are project-scoped.
+
+## stdio vs HTTP servers
+
+MCP defines two transport families. APM exposes both:
+
+- **stdio** -- APM (and your harness) spawns a local process and
+  speaks MCP over its stdio. Requires `command:` and optional
+  `args:`. Use `--env KEY=VALUE` (repeatable) for environment
+  variables. Servers do not go through a shell, so `$VAR` and
+  backticks in `args` are passed literally.
+- **http / sse / streamable-http** -- APM points your harness at a
+  remote endpoint. Requires `url:` (http or https only -- websockets
+  and `file://` are rejected). Use `--header KEY=VALUE` (repeatable)
+  for HTTP headers such as `Authorization`.
+
+`--transport` is inferred when omitted: a `--url` implies a remote
+transport, a post-`--` command implies `stdio`. The mutually-exclusive
+combinations (`--url` plus stdio command, `--header` without `--url`,
+etc.) are rejected with exit code 2.
+
+## Token injection: GitHub MCP server
+
+APM does not template arbitrary environment variables into MCP config
+files (your harness does that at runtime). It does inject one
+specific credential automatically:
+
+When the Copilot CLI adapter writes a remote MCP config and the
+server is identified as the GitHub MCP server, APM resolves a token
+and adds an `Authorization: Bearer <token>` header.
+
+The server is identified as "GitHub" by **two** narrow checks
+([copilot.py:1208](https://github.com/microsoft/apm/blob/main/src/apm_cli/adapters/client/copilot.py#L1208)):
+
+1. The server name (case-insensitive) is one of:
+   `github-mcp-server`, `github`, `github-mcp`,
+   `github-copilot-mcp-server`.
+2. Or the parsed URL hostname matches the GitHub host allowlist
+   (`github.com`, `api.github.com`, and registered GHES hostnames).
+
+This is an exact-match allowlist on hostname, not a substring check.
+A URL like `https://github.com.evil.example` does not match because
+the parsed hostname is `github.com.evil.example`, not `github.com`.
+
+The token is resolved from this chain (first non-empty wins):
+
+1. `GITHUB_COPILOT_PAT`
+2. `GITHUB_TOKEN`
+3. `GITHUB_APM_PAT`
+4. `GITHUB_PERSONAL_ACCESS_TOKEN` (Copilot CLI compat)
+
+If none are set, no header is injected and the server is written
+without auth -- you will get an unauthenticated request at runtime.
+For other authenticated remote servers, set headers explicitly with
+`--header Authorization="Bearer ${MY_TOKEN}"`.
+
+## Updating and replacing a server
+
+Re-run `apm install --mcp NAME ...` against an existing entry:
+
+| Situation | Behaviour |
+|---|---|
+| New `NAME` | Appended to `dependencies.mcp`. |
+| Existing `NAME`, identical config | No-op. Logs `unchanged`. |
+| Existing `NAME`, different config, TTY | Prompts to replace. |
+| Existing `NAME`, different config, CI | Refuses with exit 2. Re-run with `--force`. |
+
+Use `--dry-run` to preview the manifest change without writing.
+
+## Sibling commands
+
+The `apm mcp` group is for discovery and standalone install:
+
+```
+apm mcp search <query>    # search the configured registry
+apm mcp list              # list available servers
+apm mcp show <name>       # detailed server info
+apm mcp install <name>    # alias for `apm install --mcp <name>`
+```
+
+Full flag tables and exit codes: [CLI reference](../../reference/cli/install/).
+
+## Next
+
+- Authoring an MCP server as a primitive of your own package -- see
+  the producer ramp.
+- Lockfile and trust boundary for transitive MCP servers --
+  [Lifecycle](../../concepts/lifecycle/).
diff --git a/docs/src/content/docs/consumer/install-packages.md b/docs/src/content/docs/consumer/install-packages.md
new file mode 100644
index 000000000..ab63c7994
--- /dev/null
+++ b/docs/src/content/docs/consumer/install-packages.md
@@ -0,0 +1,186 @@
+---
+title: Install packages
+description: Add APM packages to your project as dependencies and let install resolve everything.
+---
+
+To add an APM package to your project, declare it in `apm.yml` under
+`dependencies.apm:` and run `apm install`. APM resolves the graph,
+scans every primitive, writes `apm.lock.yaml`, and deploys the result
+into each agent harness directory you target.
+
+```bash
+apm install microsoft/apm-sample-package
+```
+
+That command edits `apm.yml`, fetches the package, walks its
+transitive deps, runs the security scan, writes the lockfile, and
+integrates skills, prompts, instructions, agents, hooks, and commands
+into every detected harness. The next contributor runs bare
+`apm install` and gets the same bytes, pinned by commit and content
+hash.
+
+This page covers APM packages. For MCP servers, see
+[Install MCP servers](../install-mcp-servers/). For local bundles, see
+[Deploy a bundle](../deploy-a-bundle/).
+
+## Add a dependency
+
+Two ways. They produce the same `apm.yml`.
+
+**With the CLI.** Pass the package as a positional argument. APM
+resolves it, validates it, and appends it to `dependencies.apm:` in
+`apm.yml`:
+
+```bash
+apm install microsoft/apm-sample-package#v1.0.0
+apm install github/awesome-copilot/skills/review-and-refactor
+apm install ./packages/my-shared-skills        # local path
+apm install --dev acme/internal-debug-agents   # devDependencies
+```
+
+**By editing `apm.yml`.** Add entries under `dependencies.apm:` then
+run bare `apm install`:
+
+```yaml
+name: my-project
+version: 0.1.0
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0
+    - github/awesome-copilot/skills/review-and-refactor
+    - https://gitlab.com/acme/coding-standards.git
+    - ./packages/my-shared-skills
+devDependencies:
+  apm:
+    - acme/internal-debug-agents
+```
+
+```bash
+apm install
+```
+
+Supported reference forms: `owner/repo` shorthand (with optional
+`#ref` for a tag, branch, or commit), full HTTPS or SSH git URLs,
+virtual subdirectory paths into a monorepo, single-file references,
+and local paths starting with `./`, `../`, or `/`. For private hosts
+and tokens, see [Authentication](../authentication/).
+
+## What `apm install` does
+
+The pipeline is deterministic. Each phase must pass before the next runs.
+
+1. **Resolve.** Walk `dependencies.apm:` and `devDependencies.apm:`,
+   follow transitive deps, pick versions.
+2. **Policy gate.** If `apm-policy.yml` is in scope (locally or via
+   your org), every resolved dependency is checked against the
+   allow-list before anything touches disk. Skip with `--no-policy`
+   for a single invocation; this does not bypass `apm audit --ci`.
+3. **Scan.** The pre-deploy security scan inspects every primitive
+   for hidden Unicode (zero-width characters, bidi controls, tag
+   characters). Critical findings block the install. Override with
+   `--force`.
+4. **Integrate.** Write primitives into each target harness's native
+   directory (`.github/`, `.claude/`, `.cursor/`, `.opencode/`,
+   `.codex/`, `.gemini/`, `.windsurf/`) and the cross-tool
+   `.agents/skills/` directory.
+5. **Lockfile.** Write `apm.lock.yaml` with pinned versions, content
+   hashes, and the resolved dependency set.
+
+For the deeper view of how compile fits in, see
+[Lifecycle](../../concepts/lifecycle/).
+
+:::note[Coming from npm?]
+`apm install` mirrors `npm install` deliberately. The big difference:
+APM also runs a security scan and, if present, an org policy gate
+before writing anything to disk. To refresh dependencies to their
+latest matching refs, use `apm update` (mirrors `npm update`). To
+upgrade the `apm` CLI binary itself, use `apm self-update`.
+:::
+
+## Where files land
+
+APM detects which harnesses your project uses and deploys to all of
+them. Detection priority:
+
+1. `--target <slug>` flag (highest).
+2. The `targets:` field in `apm.yml`.
+3. Auto-detect: any harness directory (`.github/`, `.claude/`,
+   `.cursor/`, `.opencode/`, `.codex/`, `.gemini/`, `.windsurf/`)
+   that already exists in the workspace.
+4. Fallback: minimal output to `AGENTS.md` only.
+
+Pin targets explicitly when you want reproducibility across machines:
+
+```yaml
+name: my-project
+targets:
+  - copilot
+  - claude
+  - cursor
+```
+
+For the full reach map of which primitive lands where on each
+harness, see [Primitives and targets](../../concepts/primitives-and-targets/).
+
+## Transitive dependencies and the lockfile
+
+`apm install` resolves the full dependency graph, not just your
+top-level entries. Versions and content hashes are pinned in
+`apm.lock.yaml` so every contributor and CI run installs the exact
+same bytes. Commit the lockfile.
+
+Transitive **APM** packages flow through automatically. Transitive
+**MCP servers** are gated: if a deep dependency declares a new MCP
+server, install pauses and asks you to re-declare it in your
+top-level `apm.yml`. Use `--trust-transitive-mcp` to skip this in
+trusted environments. See
+[Drift and secure-by-default](../drift-and-secure-by-default/) for
+the rationale.
+
+## Inspect what got installed
+
+```bash
+apm list                  # list scripts declared in apm.yml
+apm view <package>        # details for one installed package
+```
+
+`apm view` reads from `apm.lock.yaml` and `apm_modules/` -- use it to
+confirm what shipped without re-running install. `apm list` shows the
+runnable scripts your manifest exposes (see
+[Run scripts](../run-scripts/)).
+
+## Useful flags
+
+```bash
+apm install --dry-run                  # resolve and print the plan; no writes
+apm install --target claude,cursor     # only deploy to these harnesses
+apm install --exclude gemini           # deploy to all targets except gemini
+apm install --only apm                 # skip MCP server integration this run
+apm install --frozen                   # CI: lockfile-only; fail on drift
+apm install --refresh                  # bypass the cache; re-fetch everything
+apm install --dev                      # treat positional args as devDependencies
+apm install -g <package>               # install to user scope (~/.apm/)
+apm install -v                         # verbose: show resolution and integration
+```
+
+For the full flag reference, run `apm install --help` or see
+[CLI commands](../../reference/cli/install/).
+
+## When things go wrong
+
+- **Critical security finding.** Install aborts with the offending
+  characters and file path. Patch upstream when you can; use
+  `--force` only when you can document the exception.
+- **Policy violation.** Install aborts before any file is written.
+  Adjust the dependency or update org policy. See
+  [Governance on the consumer ramp](../governance-on-the-consumer-ramp/).
+- **Auth failure on a private repo.** Set `GITHUB_APM_PAT` or the
+  matching host token. See [Authentication](../authentication/) and
+  [Private and org packages](../private-and-org-packages/).
+- **Drift between `apm_modules/` and the lockfile.** Run
+  `apm audit --ci` locally to reproduce the CI gate; see
+  [Update and refresh](../update-and-refresh/) to recover.
+
+Once your dependencies are installed, scripts run them.
+[Run scripts](../run-scripts/) shows how to wire `apm.yml`'s
+`scripts:` block to invoke compiled prompts in any harness.
diff --git a/docs/src/content/docs/consumer/manage-dependencies.md b/docs/src/content/docs/consumer/manage-dependencies.md
new file mode 100644
index 000000000..b5a3464e2
--- /dev/null
+++ b/docs/src/content/docs/consumer/manage-dependencies.md
@@ -0,0 +1,178 @@
+---
+title: Manage dependencies
+description: Edit apm.yml by hand, then run apm install. The lockfile is generated.
+---
+
+`apm.yml` is the manifest. `apm.lock.yaml` is generated by `apm install`.
+You can either edit `apm.yml` by hand and run `apm install`, or use
+`apm install <pkg>` to let the CLI append the entry for you. Either way
+the lockfile is a generated artifact -- never hand-edit it.
+
+```text
+edit apm.yml      ->  apm install   (manual: add or change a dep)
+apm install <pkg> ->  (CLI mutates apm.yml + installs)
+edit apm.yml      ->  apm prune     (remove a dep)
+```
+
+## The dependencies block
+
+APM dependencies live under `dependencies.apm` in `apm.yml`. The mapping
+shape is required -- a flat list at the top level is rejected with an
+explicit error pointing you at the structured form.
+
+```yaml
+name: my-project
+version: 1.0.0
+
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0
+    - github/awesome-copilot/skills/review-and-refactor
+```
+
+`devDependencies` has the exact same shape and is excluded from `apm pack`
+output. Use it for tooling and tests:
+
+```yaml
+devDependencies:
+  apm:
+    - my-org/internal-test-skills
+```
+
+For the full manifest schema (every field, every type), see
+[Package anatomy](../../concepts/package-anatomy/).
+
+For MCP server entries (`dependencies.mcp`), see
+[Install MCP servers](../install-mcp-servers/).
+
+## Reference formats
+
+Every entry under `dependencies.apm` is parsed by the same reference
+parser. The supported forms:
+
+| Form | Example | When to use |
+|---|---|---|
+| GitHub shorthand | `owner/repo` | Public GitHub repo, latest default branch. |
+| Pinned ref | `owner/repo#v1.0.0` | Pin to a tag, branch, or full commit SHA. |
+| Aliased | `owner/repo@my-alias` | Install under a custom directory name. |
+| Pinned + aliased | `owner/repo#v1.0.0@my-alias` | Combine the two. |
+| FQDN shorthand | `gitlab.com/acme/repo#v2.0` | Any git host, not just github.com. |
+| Virtual subdirectory | `owner/repo/skills/review` | Install one skill folder from a monorepo. |
+| Virtual file | `owner/repo/prompts/review.prompt.md` | Install a single primitive file. |
+| HTTPS git URL | `https://gitlab.com/acme/repo.git` | Explicit URL, any host. |
+| SSH SCP-style | `git@gitlab.com:acme/repo.git` | SSH with default port. |
+| SSH protocol | `ssh://git@gitlab.com/acme/repo.git` | SSH with explicit scheme or port. |
+| Local path | `./packages/shared` or `/abs/path` | Sibling package on disk. |
+| Object form | `{ git: <url>, path: <subpath>, ref: <ref> }` | Escape hatch for nested groups, monorepo subpaths, or aliases that the string forms cannot express. |
+
+Object form in YAML:
+
+```yaml
+dependencies:
+  apm:
+    - git: https://gitlab.com/acme/coding-standards.git
+      path: instructions/security
+      ref: v2.0
+      alias: security
+```
+
+For private repos and non-GitHub hosts, see
+[Private and org packages](../private-and-org-packages/).
+
+## Add a dependency
+
+You have two paths.
+
+**CLI shortcut.** Run `apm install <pkg>`. The CLI appends the entry to
+`dependencies.apm` in `apm.yml`, then runs the full install pipeline. If
+the pipeline fails (policy block, download error), the manifest is
+atomically rolled back to its previous state.
+
+```bash
+apm install microsoft/apm-sample-package#v1.0.0
+```
+
+See [Install packages](../install-packages/) for the canonical install
+flow and full flag list.
+
+**Manual edit.** Edit `apm.yml` yourself, then run `apm install` with
+no arguments to sync.
+
+```bash
+apm install
+```
+
+The install command resolves the new entry, downloads it into
+`apm_modules/`, updates `apm.lock.yaml` with the resolved commit and
+content hash, and recompiles the deployed primitives for every target
+harness. Critical security findings block the install; pass `--force` only
+if you understand the risk. See [Reference -> CLI commands](../../reference/cli/install/)
+for the full flag list.
+
+## Pin a version
+
+Append `#<ref>` to a shorthand entry. `<ref>` can be a tag, branch, or
+full commit SHA:
+
+```yaml
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0       # tag
+    - acme/playbooks#main                       # branch (moves)
+    - acme/playbooks#a1b2c3d4e5f6...            # SHA (immutable)
+```
+
+Branches move; tags and SHAs do not. For reproducibility, prefer tags or
+SHAs. The lockfile pins the resolved commit either way, so two clones
+running `apm install` get the same bytes -- but a branch ref will resolve
+to a new SHA on the next `apm update`.
+
+## Remove a dependency
+
+1. Delete the entry from `apm.yml`.
+2. Run `apm prune`.
+
+```bash
+apm prune --dry-run   # preview what gets deleted
+apm prune             # delete orphaned packages from apm_modules/
+```
+
+`apm prune` removes any directory in `apm_modules/` that no longer
+corresponds to a declared dependency. It does not touch your manifest,
+your lockfile entries are rewritten on the next `apm install`, and
+deployed files in `.github/`, `.claude/`, etc. are reconciled then too.
+
+If you also want to refresh remaining deps to their latest refs, see
+[Update and refresh](../update-and-refresh/).
+
+## The lockfile
+
+`apm.lock.yaml` is generated by `apm install`. It records, for every
+dependency (direct and transitive):
+
+- the resolved git commit SHA
+- a SHA-256 content hash of the package
+- the exact files deployed to your tree, with per-file hashes
+
+Three rules:
+
+1. **Commit it.** A teammate cloning the repo and running `apm install`
+   gets byte-identical primitives only if the lockfile is in version
+   control.
+2. **Do not hand-edit it.** The file is regenerated on every install.
+   Any manual change is overwritten or, for hash fields, will trip
+   `apm audit`.
+3. **Inspect freely.** It is plain YAML. Use it to answer "what version
+   am I actually running?" without trusting the manifest, which may have
+   floating refs.
+
+For the full lockfile schema, see
+[Package anatomy](../../concepts/package-anatomy/#anatomy-of-apmlockyaml).
+
+:::note[Coming from npm?]
+The split mirrors `package.json` + `package-lock.json`. The verbs match
+too: `apm update` refreshes dependencies to the latest matching refs
+(like `npm update`); `apm install --frozen` is the lockfile-only,
+fail-on-drift install for CI (like `npm ci`). To upgrade the `apm` CLI
+binary itself, use `apm self-update`.
+:::
diff --git a/docs/src/content/docs/consumer/private-and-org-packages.md b/docs/src/content/docs/consumer/private-and-org-packages.md
new file mode 100644
index 000000000..48db8de63
--- /dev/null
+++ b/docs/src/content/docs/consumer/private-and-org-packages.md
@@ -0,0 +1,174 @@
+---
+title: Private and org packages
+description: Spec a private dependency in apm.yml so install can fetch it from GitHub, GHE, EMU, Azure DevOps, or GitLab.
+---
+
+You declare a private dependency the same way you declare a public
+one. Only the host and the token change. For token setup, see
+[Authentication](../authentication/).
+
+## The shapes of a dependency ref
+
+`apm install` accepts these forms in `apm.yml` and on the command line:
+
+```yaml
+dependencies:
+  apm:
+    # 1. Shorthand, github.com is implicit
+    - acme/standards#v1.2.0
+
+    # 2. Shorthand with explicit host (GHE Cloud, GHES, GitLab)
+    - acme.ghe.com/acme/standards#v1.2.0
+    - gitlab.com/acme/standards#v1.2.0
+
+    # 3. Azure DevOps shorthand: org/project/repo
+    - dev.azure.com/acme-org/platform/standards#v1.2.0
+
+    # 4. Object form (any git URL, any port, custom protocol)
+    - git: ssh://git@bitbucket.acme.com:7999/team/standards.git
+      ref: v1.2.0
+
+    # 5. Local path (file:// equivalent for unpacked bundles)
+    - ./vendor/standards
+```
+
+Use shorthand when the host follows owner/repo (or ADO's
+org/project/repo). Use the object form for custom ports, non-standard
+schemes, or deep GitLab subgroups shorthand cannot disambiguate. Full
+grammar: `DependencyReference.parse` in
+`src/apm_cli/models/dependency/reference.py`.
+
+## GitHub.com private repos
+
+Make the repo private, give your token read access, reference it like
+any other dep:
+
+```yaml
+dependencies:
+  apm:
+    - acme/private-standards#v1.0.0
+```
+
+Token: `GITHUB_APM_PAT`, a fine-grained PAT with read access on the
+org. For manifests that span multiple orgs, scope per-org with
+`GITHUB_APM_PAT_<ORG>` (uppercase; hyphens become underscores). Per-org
+vars win over the global one.
+
+```bash
+export GITHUB_APM_PAT_ACME=ghp_acme...
+export GITHUB_APM_PAT_PARTNER_CO=ghp_partner...
+apm install
+```
+
+## GitHub Enterprise (GHE Cloud and GHES)
+
+GHE Cloud (Data Residency) hosts end in `.ghe.com` and are recognized
+automatically. GHES (self-hosted) needs `GITHUB_HOST` so APM knows the
+FQDN is GitHub-flavoured:
+
+```bash
+export GITHUB_HOST=github.acme.internal
+export GITHUB_APM_PAT=ghp_...
+```
+
+```yaml
+dependencies:
+  apm:
+    - acme.ghe.com/platform/standards#v1.2.0       # GHE Cloud
+    - github.acme.internal/platform/standards#v1   # GHES
+```
+
+EMU (Enterprise Managed Users) does not change the dep ref grammar; it
+only tightens what tokens can do (classic-only PATs, mandatory SSO
+authorization, SAML on every clone). Token scoping and SSO steps live
+in the enterprise authentication guide.
+
+## Azure DevOps
+
+ADO repos use a three-segment path (`org/project/repo`) and the
+`dev.azure.com` host:
+
+```yaml
+dependencies:
+  apm:
+    - dev.azure.com/acme-org/platform/standards#v1.2.0
+```
+
+Token: `ADO_APM_PAT`, or `az login --tenant <id>` (APM picks up the
+Azure CLI bearer). ADO is always auth-required -- no anonymous
+fallback. Azure DevOps Server (on-prem) works the same way once you
+set `GITHUB_HOST` to its FQDN.
+
+## GitLab
+
+`gitlab.com` shorthand and any GitLab-flavoured FQDN you opt into:
+
+```yaml
+dependencies:
+  apm:
+    - gitlab.com/acme/standards#v1.2.0
+    - gitlab.acme.internal/platform/standards#v1.2.0
+```
+
+Tokens, in precedence order: `GITLAB_APM_PAT`, `GITLAB_TOKEN`, then
+your git credential helper. Self-managed GitLab needs `GITLAB_HOST`
+(single host) or `APM_GITLAB_HOSTS` (comma-separated):
+
+```bash
+export GITLAB_HOST=gitlab.acme.internal
+export APM_GITLAB_HOSTS=gitlab.acme.internal,gitlab.partner.io
+```
+
+Nested groups deeper than `group/subgroup/repo` cannot always be
+disambiguated by shorthand -- use the object form:
+
+```yaml
+dependencies:
+  apm:
+    - git: https://gitlab.com/acme/platform/team/standards.git
+      ref: v1.2.0
+```
+
+## Custom ports and self-hosted git
+
+Use the object form for non-default ports. Use `ssh://` -- SCP
+shorthand (`git@host:path`) cannot carry a port:
+
+```yaml
+dependencies:
+  apm:
+    - git: ssh://git@bitbucket.acme.internal:7999/team/standards.git
+      ref: v1.2.0
+    - git: https://git.acme.internal:8443/team/standards.git
+      ref: v1.2.0
+```
+
+APM falls back across protocols on the same port: `ssh://host:7999`
+will retry as `https://host:7999/...` if SSH is unreachable.
+
+## Pre-fetched bundles (offline / air-gapped)
+
+Install a packed bundle from disk:
+
+```yaml
+dependencies:
+  apm:
+    - ./vendor/acme-standards
+```
+
+Full pack-and-unpack workflow: [Deploy a bundle](../deploy-a-bundle/).
+
+## Marketplaces
+
+ADO and GitLab marketplaces use the same auth backends as direct deps
+-- once `ADO_APM_PAT` or `GITLAB_APM_PAT` is set, marketplace fetches
+authenticate. See [Marketplaces](../../guides/marketplaces/) for the
+consumer-side workflow.
+
+## Out of scope
+
+- Token scopes, SSO authorization, EMU classes, Azure CLI tenants:
+  enterprise authentication guide.
+- Lockfile pinning: [Manage dependencies](../manage-dependencies/).
+- Resolve / verify / integrate phases: [Lifecycle](../../concepts/lifecycle/).
+- CLI flags: [CLI reference](../../reference/cli/install/).
diff --git a/docs/src/content/docs/consumer/run-scripts.md b/docs/src/content/docs/consumer/run-scripts.md
new file mode 100644
index 000000000..c8b92ccb9
--- /dev/null
+++ b/docs/src/content/docs/consumer/run-scripts.md
@@ -0,0 +1,134 @@
+---
+title: Run scripts
+description: Execute named scripts from apm.yml on any AI runtime, npm-style.
+---
+
+:::caution[Experimental surface]
+`apm run` is an experimental script runner -- think `npx` for AI
+runtime CLIs. It is optional and off the critical path: every package
+you install is already wired into your detected harnesses without it.
+Use it when you want a single, reproducible entrypoint to invoke a
+runtime CLI against an installed prompt; skip it otherwise.
+:::
+
+After `apm install` wires primitives into your harnesses, `apm run` executes
+a named script declared in `apm.yml`. This is APM's npm-scripts surface for
+AI runtimes -- one manifest, any runtime CLI you have on your `PATH`.
+
+This page covers the consumer side: running scripts that already exist in a
+project. For authoring scripts and prompts, see the producer ramp.
+
+## The `scripts:` block
+
+`apm.yml` carries a flat string-to-string `scripts:` mapping, mirroring
+`package.json`:
+
+```yaml
+name: my-project
+version: 0.1.0
+
+scripts:
+  start: "copilot --log-level all --allow-all-tools -p hello-world.prompt.md"
+  codex: "codex --skip-git-repo-check hello-world.prompt.md"
+  llm:   "llm hello-world.prompt.md -m github/gpt-4o-mini"
+```
+
+Each value is a literal shell command. The canonical pattern is shelling
+out to a runtime CLI -- `copilot`, `claude`, `codex`, `cursor-agent`,
+`gemini`, `opencode`, `windsurf`, or `llm` -- with a prompt file argument.
+APM does not bundle these runtimes; you install them yourself and APM
+invokes whichever the script names.
+
+Object-form entries (with `description`, `env`, ...) are not supported.
+Keep values as strings.
+
+## Running a named script
+
+```bash
+apm run codex
+apm run review --param target=src/auth.py
+```
+
+`apm run <name>` looks up `<name>` in the `scripts:` block and executes
+the literal command. Pass parameters with `--param key=value` (repeatable,
+short form `-p`); they are interpolated into any `.prompt.md` files the
+command references, not exported as shell environment variables.
+
+Before launching the command, APM auto-compiles any `.prompt.md` argument
+in the command line into `.apm/compiled/<name>.txt` and rewrites the
+argument to the compiled path. Commands that reference no `.prompt.md`
+file run as-is.
+
+To see exactly what would run without executing it, use `apm preview
+<name>` -- it prints the original command, the rewritten command, and the
+list of compiled prompt files.
+
+## Running with no arguments
+
+```bash
+apm run
+```
+
+With no script name, `apm run` runs the literal `start` script. It does
+not auto-discover prompts and it does not pick a "default" runtime.
+
+If `start` is not defined, the command exits with status 1 after printing
+the available scripts:
+
+```
+[x] No script specified and no 'start' script defined in apm.yml
+[i] Available scripts:
+  codex   codex --skip-git-repo-check hello-world.prompt.md
+  llm     llm hello-world.prompt.md -m github/gpt-4o-mini
+```
+
+Define a `start` entry pointing at your preferred runtime to make bare
+`apm run` work.
+
+## One script per runtime: the portable pattern
+
+The third promise -- run anywhere -- shows up here. A package that wants
+to be portable defines one script per runtime, all pointing at the same
+prompt:
+
+```yaml
+scripts:
+  start: "copilot -p review.prompt.md"
+  claude: "claude -p review.prompt.md"
+  codex:  "codex review.prompt.md"
+  llm:    "llm review.prompt.md -m github/gpt-4o-mini"
+```
+
+A consumer with `copilot` on their `PATH` runs `apm run`. A consumer on
+`codex` runs `apm run codex`. The prompt file is the same; only the
+runtime CLI differs. APM compiles the `.prompt.md` once per invocation
+and hands the compiled text to whichever CLI the script names.
+
+See [primitives and targets](../../concepts/primitives-and-targets/) for
+how a single prompt reaches every harness, and the [agent workflows
+guide](../../guides/agent-workflows/) for end-to-end script patterns.
+
+:::note[Coming from npm?]
+The `scripts:` shape is intentionally identical to `package.json`. Bare
+`apm run` runs `start`, just like `npm start`. The difference: APM runs
+the prompt compiler in front of your command, so you can keep prompts in
+their authoring format and let the runtime see compiled text.
+:::
+
+## Common surprises
+
+- The runtime CLI must be on your `PATH`. APM does not install `copilot`,
+  `claude`, `codex`, or any other harness binary.
+- `--param` values reach prompt frontmatter, not the shell. To pass a
+  shell variable, embed it in the script string itself.
+- Auto-compilation is keyed on the `.prompt.md` extension. A `.md` file
+  that is not a prompt is passed through unchanged.
+- `apm run` does not re-run the install-time security scan. If you
+  hand-edit primitives between installs, run `apm audit` -- see the
+  [lifecycle](../../concepts/lifecycle/) page.
+
+## Read more
+
+- Install primitives first: [install packages](../install-packages/)
+- Inspect what will execute: `apm preview` in the [CLI reference](../../reference/cli/install/)
+- The portability promise: [the three promises](../../concepts/the-three-promises/)
diff --git a/docs/src/content/docs/consumer/update-and-refresh.mdx b/docs/src/content/docs/consumer/update-and-refresh.mdx
new file mode 100644
index 000000000..31ae99fad
--- /dev/null
+++ b/docs/src/content/docs/consumer/update-and-refresh.mdx
@@ -0,0 +1,141 @@
+---
+title: Update and refresh
+description: Refresh project dependencies, lock down installs for CI, and update the apm CLI binary. One verb per job.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip" title="Coming from npm? You already know this.">
+`apm update` refreshes your project's package dependencies, just like
+`npm update`. To update the `apm` CLI binary itself, use
+`apm self-update` (think `npm install -g npm`).
+</Aside>
+
+Two things drift out of date in an APM project:
+
+1. The package versions pinned in `apm.lock.yaml`.
+2. The `apm` CLI binary on your machine.
+
+They are managed by separate commands. Pick the right one.
+
+## Refresh project dependencies
+
+```bash
+apm update
+```
+
+Re-resolves every dependency in `apm.yml` to its latest matching Git
+reference, prints the planned changes, and prompts for consent before
+rewriting `apm.lock.yaml` and redeploying primitives.
+
+Useful flags:
+
+- `--dry-run` -- show the resolution plan and exit; never writes.
+- `--yes` -- skip the consent prompt (for scripts and CI).
+- `-v, --verbose` -- show per-dependency resolution detail.
+
+This is the command that actually changes versions in your project.
+
+## Inspect first
+
+```bash
+apm outdated
+```
+
+Compares each entry in `apm.lock.yaml` against its remote source and
+reports which dependencies have new commits or new tags available.
+Read-only.
+
+Useful flags:
+
+- `-v, --verbose` -- show available tags for outdated tag-pinned deps.
+- `-g, --global` -- check user-scope dependencies under `~/.apm/`
+  instead of the current project.
+- `-j, --parallel-checks N` -- cap concurrent remote checks (default 4;
+  `0` for sequential).
+
+Run `apm outdated` before `apm update` to know what you are about to
+bump.
+
+## Plain `apm install` is a sync
+
+```bash
+apm install
+```
+
+With no flags, `apm install` reproduces exactly the versions pinned in
+`apm.lock.yaml`. New entries you have added to `apm.yml` get resolved
+and locked; existing ones stay on their locked SHAs.
+
+When the lockfile is already satisfied, install prints:
+
+```text
+[i] Run 'apm update' to check for newer versions.
+```
+
+That is the nudge: install never silently bumps versions. Use
+`apm update` when you want to.
+
+See [Promise 1: Portable by manifest](../../concepts/the-three-promises/)
+for why this matters in CI and for new contributors.
+
+## Lock down for CI
+
+```bash
+apm install --frozen
+```
+
+Lockfile-only install. Refuses to resolve anything new and exits with
+status 1 if `apm.yml` and `apm.lock.yaml` have drifted. Mirrors
+`npm ci`. Use this in CI to catch a manifest change that was not
+followed by an `apm update`.
+
+`--frozen` is mutually exclusive with `--update`: one trusts the
+lockfile, the other rewrites it.
+
+Note that `apm install --force` does not refresh remote refs either.
+It only bypasses the security gate for an already-resolved set. If you
+want new commit SHAs, run `apm update`.
+
+## Update the apm CLI binary
+
+```bash
+apm self-update
+```
+
+Downloads the latest release of the `apm` CLI from the official
+installer URL and replaces the binary in place. Use `--check` to see
+whether an update exists without installing it:
+
+```bash
+apm self-update --check
+```
+
+That is the entire surface. It does not read `apm.yml`. It does not
+touch `apm_modules/`. It does not modify the lockfile.
+
+<Aside type="note" title="Back-compat shim">
+If you run the legacy `apm update --check` or `apm update --self`, the
+CLI prints a deprecation notice and forwards to `apm self-update`.
+Update your scripts to call `apm self-update` directly.
+</Aside>
+
+## When to use which
+
+| You want to... | Run |
+|---|---|
+| See which deps have new versions | `apm outdated` |
+| Preview a dep refresh | `apm update --dry-run` |
+| Bump deps and rewrite the lockfile | `apm update` |
+| Reproduce the locked versions exactly | `apm install` |
+| Fail CI on lockfile drift | `apm install --frozen` |
+| Update the `apm` CLI itself | `apm self-update` |
+| See if a CLI update exists | `apm self-update --check` |
+
+## Next steps
+
+- Add, remove, or change versions in `apm.yml`:
+  [Manage dependencies](../manage-dependencies/).
+- Re-scan refreshed packages for hidden Unicode and other issues:
+  [Drift and secure by default](../drift-and-secure-by-default/).
+- Full flag reference: [CLI commands](../../reference/cli/install/).
diff --git a/docs/src/content/docs/contributing/development-guide.md b/docs/src/content/docs/contributing/development-guide.md
index bf9c5a3f7..73c3082e3 100644
--- a/docs/src/content/docs/contributing/development-guide.md
+++ b/docs/src/content/docs/contributing/development-guide.md
@@ -41,7 +41,7 @@ Enhancement suggestions are welcome! Please:
 2. Create a new branch for your feature/fix: `git checkout -b feature/your-feature-name` or `git checkout -b fix/issue-description`.
 3. Make your changes.
 4. Run tests: `uv run pytest`
-5. Ensure your code passes linting: `uv run ruff check src/ tests/`
+5. Ensure your code passes linting: `uv run --extra dev ruff check src/ tests/`
 6. Commit your changes with a descriptive message.
 7. Push to your fork.
 8. Submit a pull request.
@@ -109,9 +109,16 @@ This project follows:
 CI enforces all lint and formatting rules automatically. You can run them locally:
 
 ```bash
-uv run ruff check src/ tests/        # lint
-uv run ruff check --fix src/ tests/   # lint with auto-fix
-uv run ruff format src/ tests/        # format
+uv run --extra dev ruff check src/ tests/         # lint
+uv run --extra dev ruff check --fix src/ tests/   # lint with auto-fix
+uv run --extra dev ruff format src/ tests/        # format
+```
+
+Verify both gates pass before pushing -- this command must be silent
+(it is what CI runs):
+
+```bash
+uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/
 ```
 
 ### Optional: local pre-commit hooks
diff --git a/docs/src/content/docs/enterprise/adoption-playbook.md b/docs/src/content/docs/enterprise/adoption-playbook.md
index 4d682d1e4..afe9991fb 100644
--- a/docs/src/content/docs/enterprise/adoption-playbook.md
+++ b/docs/src/content/docs/enterprise/adoption-playbook.md
@@ -1,270 +1,212 @@
 ---
 title: "Adoption Playbook"
-description: "A phased guide to rolling out APM from a pilot team to organization-wide adoption."
+description: "A sequenced rollout plan for a platform team adopting APM across an organization, with phase gates, owners, and pitfalls."
 sidebar:
-  order: 3
+  order: 8
 ---
 
-APM adoption follows a proven pattern: start small, prove value, expand.
-This playbook walks platform teams through each phase with concrete
-milestones, success metrics, and rollback options so you can move quickly
-without betting the farm.
+This is the order to roll APM out. Five phases, each with a single owner,
+a deliverable, and a gate to clear before moving on. Read the
+[Governance overview](../governance-overview/) page first if you have not -- it is the
+contract this playbook operationalizes.
 
-## Before You Begin
+| Phase | Duration | Owner | Gate to advance |
+|---|---|---|---|
+| 1. Discover | 1-2 weeks | Platform team | Shadow install report reviewed |
+| 2. Pilot | ~1 month | One product team + platform | Pilot CI green for 2 weeks in `warn` mode |
+| 3. Harden | ~1 month | Security + Platform | Policy in `block`; proxy live if required |
+| 4. Scale | Ongoing | Platform + DevRel | 3+ teams onboarded; KPIs reported |
+| 5. Sustain | Steady state | Platform | Monthly drift sweep + lockfile review |
 
-Confirm these prerequisites before kicking off Phase 1:
+Do not skip phases. Each one buys evidence the next one needs.
 
-- APM is [installed](../../getting-started/installation/) and available in
-  your terminal.
-- You have identified a pilot team willing to try a new workflow for two
-  weeks.
-- You have a Git-hosted repository where the pilot team can work.
-- You have read access to at least one APM package registry (public or
-  private).
-
-## Phase 1 -- Pilot (Week 1-2)
-
-**Goal:** One team, one project, one command to a working environment.
+---
 
-### Steps
+## Phase 1 -- Discover (1-2 weeks)
 
-1. Choose a single project and a pilot team of 3-5 engineers.
-2. Pick 2-3 APM packages that cover the team's most common configuration
-   (for example, a linter ruleset, a set of agent instructions, and a
-   shared prompt library).
-3. Run `apm init` in the project root to scaffold `apm.yml`.
-4. Add the selected packages as dependencies:
+A small group runs `apm install` against existing repos in shadow mode to
+see what would land and what would break. No commits, no policy, no CI
+yet.
 
-   ```bash
-   apm add org/lint-standards org/agent-instructions org/prompt-library
-   ```
+**Owner:** Platform team (2-3 engineers).
 
-5. Run `apm install` to deploy files.
-6. Commit `apm.yml` and `apm.lock.yaml` to the repository.
+**Deliverables:**
 
-### Verification
+- A list of 5-10 representative repos covered.
+- A spreadsheet of what `apm install` would deploy in each repo and which
+  files it would conflict with.
+- A first-pass inventory of MCP servers in scope.
+- Rough sizing: how many repos, how many primitives, how many distinct
+  agent harnesses across the org. Use the
+  [primitives and targets](../../concepts/primitives-and-targets/) model
+  as the vocabulary.
 
-Every team member should be able to run:
+**How to run it:**
 
 ```bash
-git clone <repo> && cd <repo> && apm install
+apm install --dry-run
+apm audit
 ```
 
-and arrive at an identical, ready-to-work environment with no additional
-manual steps.
-
-### Success Metric
-
-Onboarding time drops from "read the README and manually copy files" to a
-single command.
-
-### What to Watch
-
-- Installation friction (missing runtimes, network issues).
-- Unexpected file placement -- review `apm.lock.yaml` to confirm paths.
-- Authentication errors when pulling private packages.
-
----
-
-## Phase 2 -- Shared Package (Week 3-4)
-
-**Goal:** Centralize standards in a reusable package that the pilot team
-consumes.
-
-### Steps
-
-1. Create your first organization package (for example,
-   `myorg/apm-standards`).
-2. Include baseline content:
-   - Coding standards instructions for agents.
-   - Security baseline configurations.
-   - Common prompts the team uses daily.
-3. Publish the package to your registry.
-4. Add it to the pilot project:
-
-   ```bash
-   apm add myorg/apm-standards
-   apm install
-   ```
-
-5. Verify that the pilot team receives the new files on their next
-   `apm install`.
-
-### Success Metric
+`--dry-run` reports what would change without writing. `apm audit` runs
+the [drift detection](../drift-detection/) and content scans
+that are on by default.
 
-When you update the shared package and the pilot team runs
-`apm deps update`, the latest standards land in their project
-automatically.
+**Gate to advance:** the platform team can answer, in one slide: "what
+breaks if we turn this on tomorrow, and for whom?"
 
-### What to Watch
-
-- Version pinning: confirm that `apm.lock.yaml` captures the exact version
-  installed.
-- File collisions: if the shared package deploys a file that already exists,
-  decide whether to force-overwrite or skip.
+**Common pitfalls:** picking only greenfield repos (include at least one
+with hand-edited `.github/`, `.cursor/`, or `.claude/` content -- that is
+where drift findings appear); treating the shadow run as a buy decision
+when it is a sizing exercise.
 
 ---
 
-## Phase 3 -- CI Integration (Month 2)
-
-**Goal:** Enforce content safety in the pipeline so compromised packages
-cannot reach production.
-
-### Steps
-
-1. Add APM to your CI pipeline. `apm install` blocks deployment if any
-   package contains critical hidden-character findings — no additional
-   configuration needed:
+## Phase 2 -- Pilot (~1 month)
 
-   ```yaml
-   - uses: microsoft/apm-action@v1
-     with:
-       audit-report: true   # Generate SARIF report for Code Scanning
-   ```
+One production team adopts APM end to end: manifest, lockfile, CI audit,
+and policy in `warn` mode. The platform team rides along.
 
-   For SARIF upload to GitHub Code Scanning, add:
+**Owners:** Pilot team tech lead (workflow), platform team (policy + CI).
 
-   ```yaml
-   - uses: github/codeql-action/upload-sarif@v3
-     if: always() && steps.apm.outputs.audit-report-path
-     with:
-       sarif_file: ${{ steps.apm.outputs.audit-report-path }}
-       category: apm-audit
-   ```
+**Deliverables:**
 
-2. Ensure `apm.lock.yaml` is committed so installs are reproducible.
+- `apm.yml` and `apm.lock.yaml` committed in the pilot repo.
+- An org policy file at `<org>/.github/apm-policy.yml` with
+  `enforcement: warn`. See [Get started with apm-policy.yml](../apm-policy-getting-started/) for the mental
+  model and [Policy Reference](../policy-reference/) for fields.
+- `apm audit --ci` wired into the pilot repo's required checks. See the
+  [CI Policy Enforcement](../enforce-in-ci/) guide.
+- A weekly review of warnings the policy would have blocked.
 
-### Success Metric
+**Why `warn` first:** it lets you tune the allow-lists against real
+traffic without ever red-marking a PR. The
+[Governance overview](../governance-overview/) page documents the bypass surface so
+you know exactly what `warn` mode does and does not promise.
 
-Pull requests are blocked when packages contain critical hidden-character
-findings. No unsafe content reaches the default branch.
+**Gate to advance:** two consecutive weeks where every pilot PR passes
+`apm audit --ci` cleanly, and every policy warning has been triaged
+(allow-listed, fixed, or accepted).
 
-### What to Watch
-
-- Build time impact. APM operations are fast, but confirm they add
-  acceptable overhead.
-- Lock file conflicts when multiple PRs update dependencies concurrently.
-  Resolve the same way you handle lock file conflicts in npm or pip.
+**Common pitfalls:** enforcing on day one (you will block legitimate
+work and lose the team -- stay in `warn` until the warning rate is near
+zero); skipping the lockfile commit (reproducibility is the whole point
+of the pilot); letting the pilot team author org policy (policy belongs
+in the `.github` repo behind branch protection; the pilot only
+consumes it).
 
 ---
 
-## Phase 4 -- Second Team (Month 2-3)
-
-**Goal:** Validate that the pattern transfers to a different team and
-project.
+## Phase 3 -- Harden (~1 month)
 
-### Steps
+Tighten policy from `warn` to `block`, add a registry proxy if your org
+requires one, and stand up internal marketplaces so the next teams have
+something curated to install from.
 
-1. Onboard a second team using the same shared package from Phase 2.
-2. The second team runs `apm init`, adds the shared package, and runs
-   `apm install` -- the same workflow the pilot team followed.
-3. Gather structured feedback:
-   - Did the shared package cover their needs, or are additions required?
-   - Were there file conflicts specific to their project layout?
-   - How long did onboarding take compared to their previous process?
-4. Iterate on the shared package based on feedback.
+**Owners:** Security (policy contents, proxy contract), Platform
+(rollout, marketplace), Pilot team (regression watch).
 
-### Success Metric
+**Deliverables:**
 
-A different project, with a different codebase, arrives at the same
-standards and the same workflow through the same shared package.
+- `enforcement: block` set on the org policy. The pilot repo is the
+  canary -- if its CI stays green for a week, the gate is real.
+- If your org standardizes on Artifactory or an equivalent: registry
+  proxy live, with the bypass-prevention contract in
+  [Registry Proxy & Air-gapped](../registry-proxy/) verified.
+- One or more org marketplaces published, replacing ad-hoc package
+  references. See [Publish to a marketplace](../../producer/publish-to-a-marketplace/) for
+  the authoring side.
+- A short internal page documenting which packages are blessed and how
+  to request a new one.
 
-### What to Watch
+**Gate to advance:** a fresh repo, owned by neither platform nor the
+pilot team, can run `apm install` against the org policy and the proxy
+end-to-end with no manual intervention.
 
-- Edge cases in project structure that the shared package did not
-  anticipate.
-- Requests for team-specific overrides. APM supports layered
-  configuration, so teams can extend the shared package without forking it.
+**Common pitfalls:** flipping `block` org-wide before the pilot has run
+a week on the new setting (always canary); building the marketplace
+before you know what teams want (the Discover inventory is the input);
+treating the proxy as optional when your security org mandates
+Artifactory for npm and PyPI (APM is the same conversation -- do not
+ship on direct GitHub fetches).
 
 ---
 
-## Phase 5 -- Org-Wide Rollout (Month 3+)
+## Phase 4 -- Scale
 
-**Goal:** Establish APM as the standard mechanism for managing agent and
-tool configuration across the organization.
+Roll out to more teams. Move from "the platform team helps you adopt"
+to "self-service onboarding."
 
-### Steps
+**Owners:** Platform team (enablement), DevRel or internal champions
+(per-team pull), team tech leads (per-repo work).
 
-1. Document the pattern in an internal guide. Include:
-   - How to add APM to an existing project.
-   - How to create and publish shared packages.
-   - How to handle common issues (file conflicts, version pinning,
-     registry authentication).
-2. Mandate `apm.yml` for new projects. For existing projects, adoption can
-   be voluntary initially.
-3. Enable content scanning across repositories using CI audit steps.
-4. Assign package ownership. Each shared package should have a
-   maintainer or a maintaining team.
+**Deliverables:**
 
-### Success Metric
+- An onboarding doc that points new teams at the
+  [consumer ramp](../../consumer/install-packages/) for daily flow and
+  this playbook's Phase 2 checklist for setup.
+- Adoption KPIs reported monthly:
+  - Repos with `apm.yml` committed.
+  - `apm audit --ci` pass rate per week.
+  - Number of distinct packages installed from org marketplaces.
+  - Drift findings closed vs opened (trend, not absolute).
+- A backlog of policy refinements driven by incoming team feedback.
 
-80% or more of active repositories contain an `apm.yml` and pass
-`apm install` content scanning in CI.
+**Gate to "done with rollout":** the platform team is no longer in the
+critical path for a new team to adopt APM. New teams onboard without
+filing a ticket.
 
-### What to Watch
-
-- Stale packages. Set a review cadence for shared packages.
-- Permission sprawl. Limit who can publish packages to the organization
-  registry.
-- Adoption gaps. Track which teams have not yet onboarded and offer
-  hands-on support.
+**Common pitfalls:** mandating adoption without offering a marketplace
+worth installing from (carrot before stick); measuring `apm.yml` count
+and nothing else (audit pass rate and drift trend are the leading
+indicators -- manifest count is vanity); letting policy ossify
+(schedule a quarterly review).
 
 ---
 
-## Common Objections
-
-Adoption conversations surface the same questions repeatedly. Here are
-direct answers.
+## Phase 5 -- Sustain
 
-### "We already have tool plugins configured."
+Steady-state operations.
 
-APM does not replace your existing configuration. It wraps and manages the
-files your tools already read. You gain a lock file, version pinning, and
-cross-project consistency on top of what you already have.
+**Owner:** Platform team (rotating on-call).
 
-### "This is another tool to maintain."
+**Cadence:**
 
-APM has zero runtime footprint. It generates files and exits. There is no
-daemon, no background process, and no runtime dependency in your
-application. Maintenance cost is limited to updating package versions in
-`apm.yml`.
+- **Weekly:** triage `apm audit --ci` failures across the org. Most are
+  drift; the [Drift Detection](../drift-detection/) guide is
+  the runbook.
+- **Monthly:** lockfile review on long-lived repos. Bump pinned
+  versions of org-required packages; close drift findings older than
+  one cycle.
+- **Quarterly:** marketplace refresh. Retire unused packages. Promote
+  internal tools that have proven themselves into the org marketplace.
+  Re-read the [Governance overview](../governance-overview/) known-gaps section
+  against the current APM version.
 
-### "What if we stop using it?"
+**Health signals to watch:**
 
-Delete `apm.yml` and `apm.lock.yaml`. The native configuration files APM
-deployed remain in place and continue to work exactly as they did before.
-There is no lock-in.
+- Audit pass rate trending down -> drift is accumulating; investigate
+  before it becomes a release blocker.
+- Policy warning rate climbing -> teams are reaching for packages the
+  marketplace does not cover; consider adding them.
+- Time-to-onboard a new team creeping up -> the onboarding doc has
+  drifted from reality; refresh it.
 
-### "Our developers will not adopt this."
-
-One command replaces multiple manual setup steps. Teams that adopt APM
-report that the workflow is self-reinforcing: once a developer sees
-`apm install` reproduce a working environment in seconds, they do not
-go back to manual configuration.
-
----
-
-## Rollback Plan
-
-At any phase, you can reverse course:
-
-1. Remove `apm.yml` and `apm.lock.yaml` from the repository.
-2. The configuration files APM deployed remain on disk and continue to
-   function. Your tools read native files, not APM-specific formats.
-3. Optionally, remove APM from CI steps.
-
-APM is designed for zero lock-in. Removing it leaves your project in a
-working state with standard configuration files.
+**Common pitfalls:** no named owner ("the platform team" is not an
+owner; a named on-call is); treating policy as set-and-forget (the
+threat model and the agent ecosystem move; the policy must too).
 
 ---
 
-## Related Resources
-
-- [Getting Started](../../getting-started/installation/) -- Install APM
-  and create your first project.
-- [Org-Wide Packages](../../guides/org-packages/) -- Create and manage
-  shared packages for your organization.
-- [CI/CD Pipelines](../../integrations/ci-cd/) -- Add APM
-  to your continuous integration pipeline.
-- [Governance](../governance/) -- Enforce standards and
-  audit compliance across repositories.
+## Related
+
+- [Making the Case](../making-the-case/) -- the pitch deck inputs for
+  Phase 1 stakeholder buy-in.
+- [Governance overview](../governance-overview/) -- the trust contract this playbook
+  operationalizes.
+- [Security and supply chain](../security-and-supply-chain/) -- the procurement-grade answer for
+  Phase 1 review.
+- [Get started with apm-policy.yml](../apm-policy-getting-started/) and [Policy Reference](../policy-reference/)
+  -- what to put in `apm-policy.yml` for Phase 2 and Phase 3.
+- [Registry Proxy & Air-gapped](../registry-proxy/) -- Phase 3 proxy
+  rollout.
diff --git a/docs/src/content/docs/enterprise/apm-policy-getting-started.md b/docs/src/content/docs/enterprise/apm-policy-getting-started.md
new file mode 100644
index 000000000..1ed15095b
--- /dev/null
+++ b/docs/src/content/docs/enterprise/apm-policy-getting-started.md
@@ -0,0 +1,183 @@
+---
+title: Get Started with apm-policy.yml
+description: Stand up a working org policy that blocks one bad case in 20 minutes.
+sidebar:
+  order: 2
+---
+
+`apm-policy.yml` is one YAML file that gates what your repos may install.
+This page takes you from nothing to a working policy that blocks a
+specific package, in 20 minutes.
+
+## 1. Where the file lives
+
+APM auto-discovers a policy from the project's git remote. For a repo
+on `github.com/<org>/<project>`, APM fetches:
+
+```
+<org>/.github/apm-policy.yml
+```
+
+Push this one file to your org's `.github` repo and every repo in the
+org is governed by it on the next `apm install`. No per-repo wiring,
+no settings page.
+
+You can also point at a policy explicitly during testing -- before
+the file is committed to your `.github` repo:
+
+```bash
+# Preview what the policy would do, against any source:
+apm policy status --policy-source ./apm-policy.yml
+apm policy status --policy-source https://example.com/apm-policy.yml
+apm policy status --policy-source contoso/governance     # any owner/repo
+
+# Gate CI on a policy without auto-discovery:
+apm audit --ci --policy ./apm-policy.yml
+```
+
+(`apm install` does not take a `--policy` flag -- discovery on install
+runs automatically from your git remote, or you can force-skip it
+with `--no-policy` / `APM_POLICY_DISABLE=1`.)
+
+The result is cached locally for 1 hour by default; `--no-cache` forces
+a fresh fetch.
+
+## 2. The minimal working policy
+
+Copy this into `<your-org>/.github/apm-policy.yml`. It blocks one
+package family and starts in `warn` so you do not break anyone on day
+one:
+
+```yaml
+name: "Acme baseline policy"
+version: "1.0.0"
+enforcement: warn        # warn | block | off
+
+dependencies:
+  deny:
+    - "untrusted-org/**"
+```
+
+Commit, push. On the next `apm install` in any repo in the org, a user
+who depends on `untrusted-org/anything` will see a warning. When you
+are ready to enforce, flip `enforcement: block`. See
+[../policy-pilot/](../policy-pilot/) for the rollout pattern.
+
+## 3. The schema in one screen
+
+Every top-level key, and what it does. Field names come straight from
+the schema -- do not invent others.
+
+```yaml
+name: ""                  # display name
+version: ""               # your policy version
+extends: null             # "org" | "<owner>/<repo>" | "https://..."
+enforcement: warn         # warn | block | off
+fetch_failure: warn       # warn | block (when policy can't be fetched)
+cache:
+  ttl: 3600               # seconds
+
+dependencies:
+  allow: null             # null = no opinion; [] = nothing allowed
+  deny: []
+  require: []             # packages every repo must include
+  require_resolution: project-wins   # project-wins | policy-wins | block
+  max_depth: 50
+
+mcp:
+  allow: null
+  deny: []
+  transport:
+    allow: null           # stdio | sse | http | streamable-http
+  self_defined: warn      # allow | warn | deny (inline MCPs in apm.yml)
+  trust_transitive: false
+
+compilation:
+  target:
+    allow: null           # vscode | claude | all
+    enforce: null
+  strategy:
+    enforce: null         # distributed | single-file
+  source_attribution: false
+
+manifest:
+  required_fields: []
+  scripts: allow          # allow | deny
+  content_types: null     # {allow: [...]}
+  require_explicit_includes: false
+
+unmanaged_files:
+  action: ignore          # ignore | warn | deny
+  directories: []
+```
+
+Allow-list semantics: `null` means "no opinion", an empty list means
+"explicitly allow nothing", a populated list means "only these".
+Deny and require lists accumulate. For per-field detail, see
+[../policy-reference/](../policy-reference/).
+
+## 4. Inheritance: enterprise, org, repo
+
+A policy may inherit from another via `extends`. The chain is resolved
+left-to-right, max depth 5, and **child can only tighten parent** --
+never relax it.
+
+```yaml
+# in <enterprise-org>/.github/apm-policy.yml -- the hub
+name: "Acme enterprise baseline"
+enforcement: block
+dependencies:
+  deny: ["malware-org/**"]
+```
+
+```yaml
+# in <team-org>/.github/apm-policy.yml -- inherits + adds
+name: "Payments team policy"
+extends: "acme-enterprise/.github"
+dependencies:
+  deny: ["legacy-internal/**"]   # union'd with parent
+mcp:
+  transport:
+    allow: [stdio]               # tightens transport
+```
+
+Merge rules: deny/require lists union, allow-lists intersect (tighten),
+enforcement escalates to the strictest level on the ladder
+(`off` < `warn` < `block`). A repo-level child cannot downgrade a
+parent that says `block`.
+
+## 5. Where the policy runs
+
+Discovery and enforcement run as a preflight on every install path:
+`apm install`, `apm install <pkg>`, `apm install --mcp`,
+`apm install --dry-run`. The same checks run during `apm compile` and
+`apm audit`. See [../../concepts/lifecycle/](../../concepts/lifecycle/)
+for where the gate sits in the install pipeline.
+
+For CI gating that runs even when a developer passes `--no-policy`
+locally, wire `apm audit --ci --policy org` into your pipeline. See
+[../enforce-in-ci/](../enforce-in-ci/).
+
+## 6. What a blocked install looks like
+
+When `enforcement: block` and a check fails, the user sees an inline
+error per violation followed by an abort:
+
+```
+[x] Policy violation: untrusted-org/some-pkg -- denied by policy rule
+      -- remove `untrusted-org/some-pkg` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass
+[x] Install blocked by org policy -- see violations above
+```
+
+In `warn` mode the same lines render as warnings and the install
+proceeds. To preview without writing anything, run `apm install
+--dry-run`; each blocked dep prints as
+`Would be blocked by policy: <dep> -- <reason>`. The consumer-side
+view of all this lives in
+[../../consumer/governance-on-the-consumer-ramp/](../../consumer/governance-on-the-consumer-ramp/).
+
+## Next
+
+You have a policy that warns on one bad case. To roll it out without
+breaking your org, follow [../policy-pilot/](../policy-pilot/) -- pilot
+in `warn`, observe, then flip to `block`.
diff --git a/docs/src/content/docs/enterprise/apm-policy.md b/docs/src/content/docs/enterprise/apm-policy.md
index bb41048b1..fe874a8fc 100644
--- a/docs/src/content/docs/enterprise/apm-policy.md
+++ b/docs/src/content/docs/enterprise/apm-policy.md
@@ -92,7 +92,7 @@ Policy is evaluated at two points. Both use the same policy file and the same me
 
 ### CI time (audit gate)
 
-`apm audit --ci --policy org` runs the same checks (plus 7 baseline lockfile checks) and is intended as a required status check on pull requests. It produces SARIF output that GitHub Code Scanning renders inline on the PR diff.
+`apm audit --ci --policy org` runs the same checks (plus 8 baseline lockfile checks) and is intended as a required status check on pull requests. It produces SARIF output that GitHub Code Scanning renders inline on the PR diff.
 
 For setup, see [CI Policy Enforcement](../../guides/ci-policy-setup/).
 
@@ -148,7 +148,7 @@ In CI, `apm audit --ci --policy org` produces the same finding as a SARIF result
 
 ## Forensics
 
-For lockfile-based forensic recipes, see [Lock file as audit trail](../governance/#lock-file-as-audit-trail) and the [Governance Guide §13: enforcement audit log](../governance-guide/#13-the-enforcement-audit-log).
+For lockfile-based forensic recipes, see the [Governance Guide §13: enforcement audit log](../governance-guide/#13-the-enforcement-audit-log).
 
 ---
 
@@ -156,4 +156,4 @@ For lockfile-based forensic recipes, see [Lock file as audit trail](../governanc
 
 - **Schema and every field** — [Policy Reference](../policy-reference/)
 - **Wire it into CI with SARIF** — [CI Policy Enforcement](../../guides/ci-policy-setup/)
-- **Broader governance model** (lock files, audit trails, compliance scenarios) — [Governance & Compliance](../governance/)
+- **Broader governance model** (lock files, audit trails, compliance scenarios) -- [Governance Guide](../governance-guide/)
diff --git a/docs/src/content/docs/enterprise/drift-detection.md b/docs/src/content/docs/enterprise/drift-detection.md
new file mode 100644
index 000000000..b19673c70
--- /dev/null
+++ b/docs/src/content/docs/enterprise/drift-detection.md
@@ -0,0 +1,164 @@
+---
+title: Drift Detection
+description: How an admin spots packages installed off-policy, lockfiles diverging from registered marketplaces, and security findings landing in dependencies across many repos.
+sidebar:
+  order: 5
+---
+
+Drift is what you find between two `apm install` runs that should have
+been identical. This page is the operator's checklist: the categories
+APM detects today, the command surface for each, and patterns for
+sweeping the signal across an estate of repos.
+
+## What "drift" means in APM
+
+Four concrete categories. Each has a different signal and a different fix.
+
+| Category | What it is | Detected by |
+|---|---|---|
+| Lockfile drift | `apm.yml` and `apm.lock.yaml` disagree, or deployed files do not match the lockfile | `apm audit --ci` (8 baseline checks) |
+| Cache drift | A cached checkout's `HEAD` no longer matches `resolved_commit` in the lockfile | Built into every `apm install` cache hit |
+| Ref drift (stale floats) | A locked branch tip or tag has moved upstream since the last install | `apm outdated` |
+| Security-finding drift | A primitive in `apm_modules/` now contains hidden Unicode that was clean before | `apm audit` |
+
+Marketplace-shadow drift -- the same plugin name appearing under more than
+one registered marketplace -- is reported inline by `apm install` when it
+happens; see [security and supply chain](../security-and-supply-chain/).
+
+## The local commands
+
+### `apm audit --ci`
+
+The lockfile-consistency gate. Runs eight baseline checks in order and
+exits non-zero on the first failure (or on any failure with
+`--no-fail-fast`):
+
+```
+lockfile-exists -> ref-consistency -> deployed-files-present
+-> no-orphaned-packages -> skill-subset-consistency
+-> config-consistency -> content-integrity -> includes-consent
+```
+
+After the baseline passes, it replays the install in a scratch directory
+from the cache and diffs against the working tree to surface
+`unintegrated`, `modified`, and `orphaned` files. Pass `--no-drift` to
+skip the replay. With `--policy <source>` it also evaluates the
+discovered policy against the lockfile. Source:
+`src/apm_cli/commands/audit.py`, `src/apm_cli/policy/ci_checks.py`.
+
+### `apm audit` (default)
+
+Scans every deployed primitive for hidden Unicode (zero-width characters,
+bidi overrides, tag characters) and runs the drift replay as advisory
+output. Exits 0 even when findings exist. Add `--strip` to remove hidden
+characters in place; add `--file <path>` to scan a single file outside
+the lockfile.
+
+### `apm outdated`
+
+Compares each locked dependency against its remote tip. Tag-pinned
+dependencies use semver comparison; branch-pinned dependencies compare
+commit SHAs. Marketplace-sourced dependencies are compared against the
+marketplace entry's current ref. Source: `src/apm_cli/commands/outdated.py`.
+
+```bash
+apm outdated              # project lockfile
+apm outdated --global     # ~/.apm/ user-scope lockfile
+apm outdated -j 8         # 8 parallel remote checks
+```
+
+`apm outdated` does not modify anything. It is the read-only view that
+tells you which floating refs have moved.
+
+### `apm view <package>`
+
+Prints the lockfile entry for a single package (`resolved_ref`,
+`resolved_commit`, deployed files). Use it to confirm what a repo
+actually has after a drift report names a dependency. Note that
+`apm list` lists scripts, not packages.
+
+## Cache integrity
+
+`apm install` verifies cache integrity on every cache hit before reusing
+a checkout. It reads `.git/HEAD` directly (not via `git rev-parse`, so a
+poisoned `.git/config` cannot subvert the check) and compares the
+resolved 40-character SHA against the `resolved_commit` recorded in
+`apm.lock.yaml`. On mismatch, the cache entry is evicted and a fresh
+fetch runs. Source: `src/apm_cli/cache/integrity.py`.
+
+This means a stale CI runner, a teammate who manually `git checkout`-ed
+inside `apm_modules/`, or a bumped pin without a re-install all surface
+as either eviction-and-refetch (silent self-heal) or a hard failure
+when the cache cannot be repopulated -- never as wrong content under
+the right name.
+
+## Org-wide sweeps
+
+APM runs per repository. There is no built-in fleet console. The
+operational pattern is to run the same audit in every repo and centralize
+the output.
+
+Two shapes work today:
+
+**Scheduled CI sweep.** Add a workflow that runs nightly in every repo
+and uploads the SARIF or JSON output as an artifact (or to GitHub code
+scanning). The dashboard is whatever ingests the artifact.
+
+```yaml
+# .github/workflows/apm-drift.yml -- nightly per repo
+name: apm drift
+on:
+  schedule: [{ cron: '0 6 * * *' }]
+  workflow_dispatch:
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -fsSL https://aka.ms/apm/install | bash
+      - run: apm install
+      - run: apm audit --ci --format sarif --output apm-audit.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: apm-audit.sarif }
+      - run: apm outdated > apm-outdated.txt
+        if: always()
+      - uses: actions/upload-artifact@v4
+        with: { name: apm-drift, path: 'apm-*' }
+```
+
+**Central audit harness.** Run a single job that iterates over a list of
+repos (from a GitHub org listing or a static manifest), clones each one,
+and runs `apm audit --ci --format sarif` plus `apm outdated`. Aggregate
+the outputs into one dashboard.
+
+Either pattern depends only on documented `apm` flags. APM does not
+phone home; the harness is yours.
+
+## Reporting formats
+
+`apm audit --ci` and `apm audit` both accept `--format` and `--output`.
+
+| Format | Use |
+|---|---|
+| `text` (default) | Terminal review, pull-request logs |
+| `json` | Custom dashboards, ticketing integrations |
+| `sarif` | GitHub code scanning, Defender for Cloud, any SARIF-aware viewer |
+| `markdown` | Pull-request comments, weekly status digests |
+
+`--format json|sarif|markdown` cannot be combined with `--strip` or
+`--dry-run`; those modes are interactive by design.
+
+## Remediation
+
+Once drift is detected, remediation routes back to two pages:
+
+- [Enforce in CI](../enforce-in-ci/) -- wire `apm audit --ci` into branch
+  protection so future drift cannot land. The same command that detects
+  drift here is the one that gates merges.
+- [Security and supply chain](../security-and-supply-chain/) -- scope
+  tokens, lock the registry proxy, and tighten `apm-policy.yml` so the
+  drift you cleaned up cannot reappear from a new source.
+
+For the consumer-side view of what these checks protect against on a
+single workstation, see [drift and secure by default](../../consumer/drift-and-secure-by-default/).
diff --git a/docs/src/content/docs/enterprise/enforce-in-ci.md b/docs/src/content/docs/enterprise/enforce-in-ci.md
new file mode 100644
index 000000000..ca616b215
--- /dev/null
+++ b/docs/src/content/docs/enterprise/enforce-in-ci.md
@@ -0,0 +1,178 @@
+---
+title: Enforce in CI
+description: Wire apm audit into your CI so policy and integrity gates run on every pull request, even when a developer bypassed the local checks.
+sidebar:
+  order: 4
+---
+
+`apm install` already runs the policy gate, the security scan, and drift
+detection on every developer machine. CI re-runs the same gates on the
+pull request itself. That is defence in depth: a developer can pass
+`--no-policy`, `--force`, or `APM_POLICY_DISABLE=1` locally; CI cannot.
+
+This page is the recipe set. For the full schema and the rollout
+playbook, see [Governance overview](../governance-overview/) and
+[apm-policy getting started](../apm-policy-getting-started/).
+
+## The gate
+
+```bash
+apm audit --ci
+```
+
+One command. It runs the eight baseline lockfile checks
+(`lockfile-exists`, `ref-consistency`, `deployed-files-present`,
+`no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`,
+`content-integrity`, `includes-consent`), the install-replay drift
+check, and -- if an `apm-policy.yml` is discovered -- the org policy
+checks. Exit code is `0` clean, `1` on any violation.
+
+Useful flags:
+
+- `--policy <source>` -- explicit policy ref
+  (`org`, a path, a URL, or `<owner>/<repo>`). Without it, APM
+  auto-discovers from your project's git remote, mirroring `apm install`.
+- `--no-policy` -- skip policy discovery (baseline + drift only).
+- `--no-cache` -- force a fresh policy fetch. Recommended in CI so a
+  cached file does not mask a same-day policy update.
+- `--no-fail-fast` -- run every check even after one fails. Useful for
+  reports; default is stop at first failure.
+- `--no-drift` -- skip the install-replay. Reduces coverage; only use
+  when CI minutes are the bottleneck.
+- `-f json` / `-f sarif` -- structured output. Markdown is not
+  supported in `--ci` mode.
+- `-o <path>` -- write the report to a file. The format is inferred
+  from the extension (`.sarif`, `.json`).
+
+## Recipe: minimal GitHub Actions gate
+
+This is the smallest job that fails a PR on any APM violation.
+
+```yaml
+# .github/workflows/apm-audit.yml
+name: APM audit
+on:
+  pull_request:
+    paths:
+      - 'apm.yml'
+      - 'apm.lock.yaml'
+      - '.apm/**'
+      - '.github/**'
+      - '.claude/**'
+      - '.cursor/**'
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+      - run: apm audit --ci --no-cache
+        env:
+          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}
+```
+
+`microsoft/apm-action@v1` runs `apm install` by default, so by the time
+`apm audit --ci` runs, the lockfile and deployed files are present.
+Make this job a required status check via
+[GitHub Rulesets](../github-rulesets/) and a violating PR cannot merge.
+
+## Recipe: SARIF for GitHub Code Scanning
+
+Emit SARIF and upload it so each violation appears inline on the PR
+diff and in the repository's Security tab.
+
+```yaml
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+      - name: Audit
+        run: apm audit --ci --no-cache -o apm-audit.sarif
+        env:
+          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}
+      - name: Upload SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: apm-audit.sarif
+          category: apm-audit
+```
+
+`if: always()` matters: SARIF must upload even when the audit step
+exited `1`, otherwise the failing run produces no Code Scanning entry.
+
+## Recipe: scheduled drift sweep
+
+Pull requests catch drift on the changed branch. A nightly job catches
+drift on `main` -- hand-edits, missing `apm install` runs after a
+manual lockfile bump, or a stale deployed file that no PR touched.
+
+```yaml
+on:
+  schedule:
+    - cron: '0 6 * * *'  # 06:00 UTC daily
+  workflow_dispatch:
+
+jobs:
+  drift-sweep:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+      - run: apm audit --ci --no-fail-fast -o drift.sarif
+      - if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: drift.sarif
+          category: apm-drift-sweep
+```
+
+`--no-fail-fast` lets the sweep report every finding rather than the
+first one. See [drift detection](../drift-detection/) for what the
+replay actually checks and how to debug a finding locally.
+
+## When the gate blocks a PR
+
+The fix path depends on which check failed.
+
+- **`lockfile-exists` / `ref-consistency` / `deployed-files-present`.**
+  The author skipped `apm install` after editing `apm.yml`. They run
+  `apm install`, commit `apm.lock.yaml` and the integrated files, and
+  push.
+- **`content-integrity` or a hidden-Unicode finding.** A primitive was
+  hand-edited. The author runs `apm audit --strip` to clean it (or
+  reverts the edit), then `apm install` to refresh the lockfile.
+- **Drift replay.** A deployed file no longer matches what an install
+  would produce. `apm install` is the fix.
+- **Policy violation.** The author either picks an allowed alternative,
+  or opens a change request against `<org>/.github/apm-policy.yml`.
+  `--no-policy` does not work here -- CI ignores the local bypass flag.
+
+For genuine, time-boxed exceptions, two waiver shapes exist today:
+
+1. Amend `apm-policy.yml` (allow-list the package, raise `max_depth`,
+   etc.) through the same review process as any other policy change.
+2. Lower `enforcement` from `block` to `warn` for that policy scope.
+   Findings still appear in the SARIF report; they no longer fail the
+   job. Treat this as a temporary state and track its removal.
+
+There is no per-PR override flag and there will not be one. Bypass
+must be visible in the policy file's history.
+
+## Next steps
+
+- [drift detection](../drift-detection/) -- what the replay actually
+  catches and how to read its output.
+- [security and supply chain](../security-and-supply-chain/) -- the
+  built-in install-time scan that complements the CI gate.
+- [github rulesets](../github-rulesets/) -- make the audit job a
+  required status check across an org.
+- [APM in CI/CD](../../integrations/ci-cd/) -- deeper patterns for
+  Azure Pipelines, GitLab, Jenkins, air-gapped runners, and bundle
+  caching across jobs.
diff --git a/docs/src/content/docs/enterprise/github-rulesets.md b/docs/src/content/docs/enterprise/github-rulesets.md
new file mode 100644
index 000000000..75df4322e
--- /dev/null
+++ b/docs/src/content/docs/enterprise/github-rulesets.md
@@ -0,0 +1,154 @@
+---
+title: "Wire APM Into GitHub Rulesets"
+description: "Ops-side recipe for requiring the apm-audit check and lockfile consistency on protected branches via org-level GitHub Repository Rulesets."
+sidebar:
+  order: 9
+---
+
+This is the GitHub-admin recipe. APM ships the CI job; GitHub
+Repository Rulesets convert "we have a green check" into "you cannot
+merge without it". Nothing on this page is APM functionality -- it is
+configuration on the GitHub side that pairs with the workflow from
+[Enforce in CI](../enforce-in-ci/).
+
+## Why rulesets, not classic branch protection
+
+Classic branch protection rules are per-repo and click-driven. Rulesets
+are GitHub's current recommendation because they:
+
+- Apply at the **organization** level and target many repos at once
+  (by name pattern, by topic, by repo property).
+- Are **versioned and exportable** -- the JSON definition lives next
+  to your IaC, not in 200 repo settings pages.
+- Support **layered evaluation** -- a repo can be covered by an org
+  ruleset and a repo ruleset; the strictest setting wins.
+- Have an **explicit bypass-actor list** with audit log entries when
+  bypass is used.
+
+For an org-wide governance program, the per-repo branch-protection
+clickwheel does not scale. Use rulesets.
+
+## The check name APM publishes
+
+The recommended workflow in [Enforce in CI](../enforce-in-ci/) emits a
+single status check whose name is the **job name** in the workflow
+file. The template uses:
+
+```yaml
+# .github/workflows/apm-audit.yml
+name: APM Audit
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+        with:
+          audit-report: true
+        env:
+          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}
+```
+
+GitHub registers the check as `audit` (the job key). When multiple
+workflows publish a job called `audit`, GitHub disambiguates as
+`APM Audit / audit`. **Run the workflow at least once on any repo
+before adding it to a ruleset** -- GitHub will not autocomplete a
+check name it has never seen.
+
+If your org standardises on a different job name, use that name
+verbatim in the ruleset. The string must match exactly.
+
+## Recipe 1: org ruleset requiring apm-audit on default branch
+
+Goal: every repo in the org with an `apm.yml` cannot merge to its
+default branch unless the `audit` check passes.
+
+1. In your org, go to **Settings** > **Repository** > **Rulesets** >
+   **New ruleset** > **New branch ruleset**.
+2. **Name**: `apm-audit-required`.
+3. **Enforcement status**: `Active`. Use `Evaluate` first if you want
+   a dry-run period -- it logs would-be violations without blocking.
+4. **Bypass list**: leave empty for true enforcement. See pitfalls
+   below before adding any actor.
+5. **Target repositories**: dynamic targeting works best.
+   - `All repositories`, or
+   - `Repositories matching properties` and target a custom property
+     like `uses-apm = true` (set this property on repos that have an
+     `apm.yml`).
+6. **Target branches**: `Include default branch`.
+7. **Rules**: enable **Require status checks to pass**.
+   - Add status check: `audit` (or `APM Audit / audit` if you have
+     name collisions).
+   - Source: `GitHub Actions`.
+   - Enable **Require branches to be up to date before merging** so
+     stale PRs cannot bypass a freshly-tightened policy.
+8. Save.
+
+PRs in matching repos now show `audit` as a required check. A red
+audit blocks merge regardless of repo-admin settings.
+
+## Recipe 2: ensure the lockfile is checked in
+
+The honest answer: **GitHub Rulesets do not have a native "if file A
+changed, file B must also change" rule.** The check is enforced by
+APM itself, not by the ruleset.
+
+`apm audit --ci` runs lockfile consistency checks unconditionally
+(see [Governance overview](../governance-overview/) for the non-bypass contract).
+A PR that edits `apm.yml` without updating `apm.lock.yaml` -- or
+commits a lockfile that does not match the manifest -- fails the
+`audit` check. So Recipe 1 already covers this case: if `audit` is
+required, lockfile drift cannot merge.
+
+What rulesets *can* add on top:
+
+- **Restrict file paths** rule: block direct edits to `apm.lock.yaml`
+  outside of PRs. Combined with CODEOWNERS on the lockfile, this
+  forces lockfile changes through review.
+- **Require a pull request before merging**: prevents `git push` of
+  manifest changes straight to default.
+
+Together: Recipe 1 catches the *content* drift, the file-path rule
+catches the *workflow* bypass.
+
+## Recipe 3 (optional): signed commits on producer repos
+
+For repos that publish APM packages (the producer side), turn on
+**Require signed commits** in the same ruleset or a separate one
+scoped to producer repos. This pairs with `apm pack` content hashing:
+the lockfile pins what was published, and signed commits give you a
+verifiable author chain on the source side.
+
+This is most valuable on the `<org>/.github` repo that hosts
+`apm-policy.yml` -- see [Governance overview](../governance-overview/) for the
+trust-anchor rationale.
+
+## Pitfalls
+
+- **Bypass actors**: every actor on the bypass list can merge a red
+  `audit`. The action is logged, but it merges. Keep the list empty,
+  or restrict it to a break-glass team that is on-call rotation only.
+  "Org admins" as a default bypass defeats the gate.
+- **Check name typos**: the required-check string is matched
+  literally. `Audit`, `audit `, or `APM Audit` (workflow name, not
+  job name) silently never match -- the check appears as
+  `Expected -- Waiting for status` and the PR is mergeable in some
+  configurations. Always run the workflow once and copy the
+  registered name from the PR's checks tab.
+- **`Evaluate` left on forever**: dry-run mode logs but does not
+  block. Set a calendar reminder to flip to `Active` within two
+  weeks of pilot.
+- **Repo-level rulesets overriding org rules**: rulesets layer
+  additively for *requirements*, but a repo admin cannot weaken an
+  org-required check -- they can only add more. If a repo seems to
+  be merging without `audit`, check whether the org ruleset's repo
+  targeting actually includes that repo.
+
+## Related
+
+- [Enforce in CI](../enforce-in-ci/) -- the workflow that emits the
+  check this page requires.
+- [Governance overview](../governance-overview/) -- bypass contract, install-gate
+  guarantees, what `apm audit --ci` actually verifies.
+- [APM policy reference](../policy-reference/) -- the policy schema
+  the audit check evaluates.
diff --git a/docs/src/content/docs/enterprise/governance-guide.md b/docs/src/content/docs/enterprise/governance-guide.md
index d92151ab2..e1c98daa4 100644
--- a/docs/src/content/docs/enterprise/governance-guide.md
+++ b/docs/src/content/docs/enterprise/governance-guide.md
@@ -91,7 +91,7 @@ The scope matrix below is the contract. Every row maps a security or operational
 | Transitive MCP trust (policy field) | `mcp.trust_transitive` | -- | `[!] parsed but not enforced` (gate is the `--trust-transitive-mcp` CLI flag) | -- |
 | Manifest content types | `manifest.content_types` | -- | `[!] parsed but not enforced` | -- |
 
-The full schema and the canonical 7+17 check enumeration live in the [Policy Reference](../policy-reference/). The 7 baseline lockfile checks (lockfile presence, ref consistency, deployed files present, no orphaned packages, MCP config consistency, content integrity, includes consent) run on every `apm audit --ci` regardless of policy and are non-bypassable -- they are covered in section 7.
+The full schema and the canonical 8+17 check enumeration live in the [Policy Reference](../policy-reference/). The 8 baseline lockfile checks (lockfile presence, ref consistency, deployed files present, no orphaned packages, skill-subset consistency, MCP config consistency, content integrity, includes consent) run on every `apm audit --ci` regardless of policy and are non-bypassable -- they are covered in section 7.
 
 `manifest.require_explicit_includes` (`bool`, default `false`) deserves a callout: when set to `true`, the `explicit-includes` check rejects any `apm.yml` that omits `includes:` or sets `includes: auto`. Use this when every published local file must be enumerated in the manifest and reviewable in PR diffs. See the [`includes` field](../../reference/manifest-schema/#39-includes) for the three accepted forms.
 
@@ -136,7 +136,7 @@ graph TD
 
     DryRun["apm install --dry-run"] --> DryPre["[*] Preview only<br/>install_preflight dry_run=True<br/>'Would be blocked' lines, no raise"]
 
-    Audit["apm audit --ci<br/>--policy &lt;scope&gt;"] --> AuditRun["[*] Enforcement point 4<br/>7 baseline + 17 policy checks<br/>(only enforcer of audit-only fields)"]
+    Audit["apm audit --ci<br/>--policy &lt;scope&gt;"] --> AuditRun["[*] Enforcement point 4<br/>8 baseline + 17 policy checks<br/>(only enforcer of audit-only fields)"]
 
     style Start fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
     style Gate fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000
@@ -165,7 +165,7 @@ When you install an APM package that itself declares MCP dependencies, those MCP
 
 ### 5d. `apm audit --ci --policy <scope>`
 
-The only enforcer of the audit-only checks (`compilation-strategy`, `source-attribution`, `required-manifest-fields`, `scripts-policy`, `unmanaged-files`). Runs the 7 baseline lockfile checks unconditionally, then -- if a policy is discovered or supplied -- runs the 17 policy checks. This is the check you wire into branch protection.
+The only enforcer of the audit-only checks (`compilation-strategy`, `source-attribution`, `required-manifest-fields`, `scripts-policy`, `unmanaged-files`). Runs the 8 baseline lockfile checks unconditionally, then -- if a policy is discovered or supplied -- runs the 17 policy checks. This is the check you wire into branch protection.
 
 ---
 
@@ -274,8 +274,8 @@ This is the certitude section. Read it twice if you are deciding whether `apm au
 
 | Surface | What it bypasses LOCALLY | What it CANNOT bypass | Reviewable in |
 |---|---|---|---|
-| `apm install --no-policy` | All 17 policy checks at install (incl. transitive MCP, hash pin) | The 7 baseline checks plus integration drift detection in `apm audit --ci` | git diff of `apm.lock.yaml` in PR |
-| `APM_POLICY_DISABLE=1` env | Same as `--no-policy` plus the 17 audit policy checks | The 7 baseline checks plus integration drift detection in `apm audit --ci` | PR diff; CI env vars in Actions logs |
+| `apm install --no-policy` | All 17 policy checks at install (incl. transitive MCP, hash pin) | The 8 baseline checks plus integration drift detection in `apm audit --ci` | git diff of `apm.lock.yaml` in PR |
+| `APM_POLICY_DISABLE=1` env | Same as `--no-policy` plus the 17 audit policy checks | The 8 baseline checks plus integration drift detection in `apm audit --ci` | PR diff; CI env vars in Actions logs |
 | Manual edit to `apm.lock.yaml` | Nothing; install regenerates the file each run | Audit baseline `ref-consistency` and `deployed-files-present` | git diff |
 | Manual edit to deployed file post-install | Local file content until next audit | Audit baseline `content-integrity` (re-hashes deployed files); hidden-Unicode scan in `apm audit` content mode | git diff of the deployed file in PR |
 | Direct `git clone` of an APM package, bypassing install | Everything; nothing detects out-of-band file drops | Audit baseline `no-orphaned-packages` and audit-only `unmanaged-files` | git diff |
@@ -287,12 +287,12 @@ This is the certitude section. Read it twice if you are deciding whether `apm au
 Notes on specific rows:
 
 - **`apm install --no-policy`** also bypasses the `apm install --mcp` preflight, the transitive-MCP preflight, and any project-side `policy.hash` pin.
-- **`APM_POLICY_DISABLE=1`** short-circuits discovery to `outcome="disabled"` everywhere -- including `apm audit --ci`, where the 17 policy checks are skipped (the 7 baseline checks and integration drift detection still run).
+- **`APM_POLICY_DISABLE=1`** short-circuits discovery to `outcome="disabled"` everywhere -- including `apm audit --ci`, where the 17 policy checks are skipped (the 8 baseline checks and integration drift detection still run).
 - **Manual lockfile edits**: `content_hash` mismatch on registry-proxy deps is caught at the next install when downloads resume.
 - **Direct `git clone`**: `unmanaged-files` only flags governed dirs and only when configured to `warn` / `deny`.
 - **Fork-to-personal-org**: discovery resolves via `git remote get-url origin`; branch protection on the upstream repo is the trust boundary.
 
-**The non-bypass contract.** The 7 baseline lockfile checks (run by `apm audit --ci` *without* `--no-policy` or `APM_POLICY_DISABLE=1`) are unconditional. They do not consult the policy file, do not depend on org discovery, and are not affected by either escape hatch. Combined with branch protection that requires `apm audit --ci` to pass, no developer override is invisible: a `--no-policy` install leaves a lockfile that audit will reject if the result is inconsistent, and an `APM_POLICY_DISABLE=1` audit run cannot itself bypass the baseline checks. Every override appears in the PR diff, in the workflow file, or in the Actions environment configuration -- all of which are reviewable in code review.
+**The non-bypass contract.** The 8 baseline lockfile checks (run by `apm audit --ci` *without* `--no-policy` or `APM_POLICY_DISABLE=1`) are unconditional. They do not consult the policy file, do not depend on org discovery, and are not affected by either escape hatch. Combined with branch protection that requires `apm audit --ci` to pass, no developer override is invisible: a `--no-policy` install leaves a lockfile that audit will reject if the result is inconsistent, and an `APM_POLICY_DISABLE=1` audit run cannot itself bypass the baseline checks. Every override appears in the PR diff, in the workflow file, or in the Actions environment configuration -- all of which are reviewable in code review.
 
 **Workstation blast radius.** Because "file presence is execution" for agent files (an instruction or chat-mode file on disk is consumed by the agent runtime as soon as it is opened), the fork-to-personal-org bypass mitigates the *org's* trust gate but not the *individual workstation's*: between fork-clone-install and PR creation, the developer's machine already has the tainted files. Compensating control: an MDM-deployed mirror of `<org>/.github/apm-policy.yml` consulted by a wrapper script around `apm install`, or a workstation-level allowlist of permitted git remotes for APM-managed repos.
 
@@ -368,6 +368,11 @@ Hash-mismatch is the one outcome that can never be overridden. If your `apm.yml`
 - `cache_miss_fetch_fail` outcome -> network; check egress to api.github.com; verify cache dir writable.
 - `hash_mismatch` outcome -> SUSPECTED TAMPER; do not override; investigate org policy commit history.
 - `cached_stale` outcome -> normal if recently degraded network; force refresh with `apm policy status --no-cache`.
+
+> Reminder: `apm policy status` ALWAYS exits 0 by default -- it is a
+> diagnostic, not a gate. Use `apm policy status --check` to make CI
+> fail when no usable policy is found, and `apm audit --ci` to gate
+> on rule violations.
 - `extends rejected` outcome -> cross-host extends; remove non-canonical host from `apm-policy.yml` extends chain.
 
 ---
@@ -456,7 +461,7 @@ When a reviewer asks "who approved this policy change and why?", the forensic an
 git -C <org>/.github log --follow --patch -- apm-policy.yml
 ```
 
-For lockfile-side forensic recipes (`git log apm.lock.yaml`, `git show <sha>:apm.lock.yaml`, etc.), see the companion [Governance & Compliance](../governance/) page.
+For lockfile-side forensic recipes (`git log apm.lock.yaml`, `git show <sha>:apm.lock.yaml`, etc.), see the [Lockfile Spec](../../reference/lockfile-spec/).
 
 ---
 
@@ -501,7 +506,7 @@ These are the sharp edges. Plan around them; do not assume they are solved.
 - **Non-GitHub remotes are not auto-discovered.** If your project's `git remote get-url origin` points to ADO, GitLab, or a plain git host, policy auto-discovery falls through with no policy applied. Operational mitigation: pass `apm audit --ci --policy <path-or-url>` explicitly in those CI environments.
 - **Trust anchor is `git remote get-url origin`.** A developer who pushes the project to a personal org will have policy discovery resolve `<their-org>/.github/apm-policy.yml` -- which they control. Operational mitigation: branch protection on the canonical repo is the trust boundary; nothing about a personal fork can bypass what your CI requires before merge.
 - **`apm install --dry-run` silently downgrades hash-mismatch.** In dry-run, `raise_blocking_errors=False` (outcome_routing.py:104-119) causes the mismatch to surface as `discovery_miss` with no "Would be blocked" line and exit 0. Operational mitigation: rely on `apm audit --ci` in CI for hash-pin verification, not on `apm install --dry-run`.
-- **`apm install --no-policy` help text is misleading.** It claims "Does NOT bypass apm audit --ci" -- this is only true for the 7 baseline lockfile checks; the 17 policy checks ARE bypassed in audit when this flag (or `APM_POLICY_DISABLE=1`) is set. Operational mitigation: do not rely on the help text; the bypass contract in section 7 is authoritative.
+- **`apm install --no-policy` help text is misleading.** It claims "Does NOT bypass apm audit --ci" -- this is only true for the 8 baseline lockfile checks; the 17 policy checks ARE bypassed in audit when this flag (or `APM_POLICY_DISABLE=1`) is set. Operational mitigation: do not rely on the help text; the bypass contract in section 7 is authoritative.
 - **Gate + transitive-MCP preflight may double-emit the same MCP violation.** A single bad transitive MCP can produce two SARIF alerts with the same rule and different code paths. Operational mitigation: dedupe by `(rule_id, server_name)` when aggregating alerts in your SIEM or dashboard.
 - **No signed attestation that the gate ran.** APM does not currently produce a signed (e.g. SLSA / sigstore) attestation for the install gate or the audit run. Non-repudiation depends on the GitHub Actions audit log plus branch-protection enforcement of the required check. Operational mitigation: pair APM with branch protection requiring `apm audit --ci` as a status check; rely on GitHub's audit log for auditor evidence.
 
@@ -606,4 +611,4 @@ policy:
 - [Adoption Playbook](../adoption-playbook/) -- broader APM rollout (governance is one phase).
 - [Lockfile Spec](../../reference/lockfile-spec/) -- lockfile schema for forensic queries.
 - [GitHub Rulesets](../../integrations/github-rulesets/) -- enforcing audit as a required check.
-- [Governance & Compliance](../governance/) -- companion page covering the lockfile audit trail and SOC 2 / change-management scenarios.
+- [Lockfile Spec](../../reference/lockfile-spec/) -- companion reference covering the lockfile audit trail and forensic recipes.
diff --git a/docs/src/content/docs/enterprise/governance-overview.md b/docs/src/content/docs/enterprise/governance-overview.md
new file mode 100644
index 000000000..68692391e
--- /dev/null
+++ b/docs/src/content/docs/enterprise/governance-overview.md
@@ -0,0 +1,98 @@
+---
+title: Governance Overview
+description: The enterprise ramp's map -- what APM lets you control, where each control runs, and which page in this chapter goes deep on each surface.
+sidebar:
+  order: 1
+---
+
+You own the trust boundary for AI agent context across N repos. This chapter is the spec for that scale. This page is the map.
+
+APM's third promise -- *Org policy enforced at install time, before MCP touches disk* -- is delivered by four artifacts working together: a policy file your security team writes, an install-time gate that reads it, a CI check that re-runs it on every PR, and (optionally) a registry proxy that holds dependency traffic to a single network egress. Everything in this chapter drills into one of those four.
+
+## The model in one paragraph
+
+`apm-policy.yml` lives in `<org>/.github/` and is auto-discovered from each repo's git remote. Every `apm install` evaluates the resolved dependency graph -- including transitive MCP servers -- against the merged policy *before* writing anything to disk. `apm audit --ci` re-runs the same checks plus eight non-bypassable lockfile baselines and is wired into branch protection. Inheritance flows enterprise -> org -> repo and only tightens; a child policy cannot loosen a parent. Three enforcement levels: `block` (abort on violation), `warn` (continue with diagnostics), `off` (skip). Source: `src/apm_cli/policy/install_preflight.py`, `src/apm_cli/policy/inheritance.py`, `src/apm_cli/policy/ci_checks.py`.
+
+The 30-second picture:
+
+```
+                       <org>/.github/apm-policy.yml
+                                  |
+                                  v
+        +------------- discovery + merge -------------+
+        |                                             |
+        v                                             v
+   apm install                                  apm audit --ci
+   (install gate                                (8 baselines +
+    + transitive                                 17 policy checks
+    MCP preflight)                               in CI)
+        |                                             |
+        v                                             v
+   files written or                          PR check passes
+   exit 1 (no writes)                        or fails
+```
+
+## Surfaces of control
+
+Four surfaces, four owners.
+
+- **`apm-policy.yml`** -- the schema. Allow/deny lists for dependencies and MCP servers, MCP transport restrictions, compilation-target rules, manifest shape constraints, unmanaged-files action. Authored by the platform or security team in `<org>/.github/`. Schema: `src/apm_cli/policy/schema.py`.
+- **Install-time enforcement** -- the gate. Three code paths share one outcome table: the install pipeline gate (`install/phases/policy_gate.py`, delegating to `policy/install_preflight.py`), the `--mcp <ref>` direct-install preflight, and the transitive-MCP second pass that runs after APM packages resolve their own MCP dependencies. Source: `src/apm_cli/policy/install_preflight.py`.
+- **CI enforcement** -- `apm audit --ci`. Eight baseline lockfile checks always; the seventeen policy checks when a policy is discovered or supplied. The only enforcer of the audit-only fields (`compilation.strategy.enforce`, `manifest.required_fields`, `manifest.scripts`, `unmanaged_files.action`). Source: `src/apm_cli/policy/ci_checks.py`.
+- **Built-in security gate** -- runs on every install regardless of policy. `SecurityGate` (`src/apm_cli/security/gate.py`) scans all primitive files for hidden Unicode and other content findings using `BLOCK_POLICY` before any file is written to a harness directory. Zero configuration. This sits underneath the policy engine: it cannot be turned off by `apm-policy.yml`.
+
+A registry proxy (Artifactory or compatible) is the optional fifth surface for organizations that need all dependency traffic to flow through a single egress. See [Registry proxy](../registry-proxy/).
+
+## Where each control runs
+
+| Surface                        | When it runs                              | What it enforces                                                | Failure mode                              |
+| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- |
+| `SecurityGate` (built-in)      | Every install, before any file is written | Hidden Unicode and other critical content findings              | `[x]` Exit 1; nothing deployed            |
+| Install pipeline gate          | Every install, after resolve, before targets | `dependencies.*`, `mcp.*` (direct), compilation-target after targets phase | `[x]` `enforcement: block` -> exit 1; `[!]` `warn` -> continue with summary |
+| `--mcp <ref>` preflight        | `apm install --mcp owner/repo` only       | Same `mcp.*` rules as the gate, separate code path              | `[x]` Exit 1 before any MCP config is written |
+| Transitive MCP preflight       | After APM packages resolve their MCPs     | `mcp.*` against transitive MCP servers                          | `[x]` Exit 1; APM packages stay, MCP configs not written |
+| `apm audit --ci [--policy ...]`| In CI, on every PR                        | 8 lockfile baselines + 17 policy checks (incl. audit-only fields) | Exit 1; PR check fails                  |
+| Registry proxy (optional)      | Every install download                    | All dependency traffic flows through the proxy; lockfile guard catches bypass | Bypass attempt -> `content_hash` mismatch on next install |
+
+`apm compile`, `apm run`, and `apm pack` enforce zero policy. They trust what install placed on disk. APM is an install-time and CI gate, not a runtime sandbox. If you need runtime tool restriction, govern it through `mcp.*` and `dependencies.*` so the disallowed tooling never reaches the harness.
+
+## Who does what
+
+- **Platform / security team** -- writes `apm-policy.yml` in `<org>/.github/`. Owns the trust boundary via CODEOWNERS and branch protection on that repo. Decides the inheritance chain (enterprise -> org -> repo).
+- **Consumers** -- run `apm install` inside the rails the policy defines. They discover what is in effect with `apm policy status` and what would be blocked with `apm install --dry-run`. See the consumer view in [Governance on the consumer ramp](../../consumer/governance-on-the-consumer-ramp/).
+- **Producers** -- publish into marketplaces that the org's `apm-policy.yml` allows. A package that fails an org's `dependencies.allow` rule will not install in repos governed by that policy, regardless of where it was published. See [Publish to a marketplace](../../producer/publish-to-a-marketplace/).
+
+Three quick commands cover most day-one questions:
+
+```bash
+apm policy status                    # what policy is in effect?
+apm install --dry-run                # what would policy block on this manifest?
+apm audit --ci --policy org          # full policy + baseline run, exit non-zero on violation
+```
+
+`apm policy status` reports the source of the active policy, the enforcement level, the cache age, the inheritance chain, and a count of effective rules per section. `apm install --dry-run` runs discovery and policy checks without writing to disk; each violation is reported as `Would be blocked by policy: <dep> -- <reason>`. `apm audit --ci` is the only command that exits non-zero on violation and is therefore the only one safe to wire into branch protection.
+
+## Where the controls execute
+
+Three execution surfaces, by environment:
+
+- **Local CLI** -- `apm install` runs the install gate; `apm audit` runs locally for ad-hoc checks; `apm policy status` reports the active policy.
+- **CI** -- `apm audit --ci` is the required check on the protected branch. This is the enforcement surface that survives `--no-policy` bypass attempts at the developer's machine.
+- **Network egress** -- a registry proxy holds all package downloads to a single, observable path. The lockfile's `content_hash` plus `apm audit --ci` guarantees no in-band bypass. Optional but recommended at scale.
+
+## Boundary statement
+
+[i] APM enforces in the CLI and in CI. It is not a runtime sandbox. The model assumes branch protection on `<org>/.github/apm-policy.yml`, branch protection requiring `apm audit --ci` to pass, and either a registry proxy or the lockfile content-hash check covering download integrity. Take any one of those three away and the contract weakens.
+
+## Read this chapter in order
+
+1. [APM policy: getting started](../apm-policy-getting-started/) -- the smallest useful `apm-policy.yml` you can write today; what each top-level key does.
+2. [Policy pilot](../policy-pilot/) -- the warn-first rollout pattern: ship `enforcement: warn`, measure violations, flip to `block`.
+3. [Enforce in CI](../enforce-in-ci/) -- wiring `apm audit --ci` as a required check; `--policy <scope>` and the audit-only fields it exposes.
+4. [Drift detection](../drift-detection/) -- the eight non-bypassable lockfile baselines and what each one catches.
+5. [Registry proxy](../registry-proxy/) -- routing dependency traffic through Artifactory or a compatible proxy; air-gapped CI playbook.
+6. [Security and supply chain](../security-and-supply-chain/) -- the threat model `SecurityGate` defends against; MCP trust boundary; provenance.
+7. [Adoption playbook](../adoption-playbook/) -- staged rollout across N repos; pilot team -> org-wide -> required check.
+8. [GitHub rulesets](../github-rulesets/) -- the GitHub-side configuration that makes `apm audit --ci` authoritative.
+
+[>] Start with [APM policy: getting started](../apm-policy-getting-started/) and write your first policy in 10 minutes. Come back here when you need the map.
diff --git a/docs/src/content/docs/enterprise/index.md b/docs/src/content/docs/enterprise/index.md
index eb35a2981..1e716baa7 100644
--- a/docs/src/content/docs/enterprise/index.md
+++ b/docs/src/content/docs/enterprise/index.md
@@ -7,7 +7,7 @@ sidebar:
 
 APM for organizations rests on three pillars:
 
-- **[Portable by manifest](../getting-started/quick-start/)** -- one `apm.yml` declares every dependency; `apm.lock.yaml` pins exact versions; every developer and every CI run gets the same agent setup.
+- **[Portable by manifest](../quickstart/)** -- one `apm.yml` declares every dependency; `apm.lock.yaml` pins exact versions; every developer and every CI run gets the same agent setup.
 - **[Secure by default](./security/)** -- `apm install` scans every package for hidden Unicode and other tampering before agents read it. Attack surface, scanners, and the MCP trust boundary are documented for procurement review.
 - **[Governed by policy](./governance-guide/)** -- `apm-policy.yml` lets platform teams allow-list dependencies, restrict deploy targets, and enforce trust rules at install time across every repo, from a single source of truth.
 
diff --git a/docs/src/content/docs/enterprise/policy-pilot.md b/docs/src/content/docs/enterprise/policy-pilot.md
new file mode 100644
index 000000000..b626a71d2
--- /dev/null
+++ b/docs/src/content/docs/enterprise/policy-pilot.md
@@ -0,0 +1,116 @@
+---
+title: Pilot a New Policy
+description: Roll out a new apm-policy.yml rule without breaking every repo on day one. The warn-then-block playbook for platform teams.
+sidebar:
+  order: 3
+---
+
+You wrote a new rule in `<org>/.github/apm-policy.yml`. Do not flip it to `block` yet. Half your repos already violate it -- you don't know which ones.
+
+This page is the rollout sequence. Author in `warn`, measure, remediate, then escalate to `block`. Per-rule mode flips do not exist; the dial is the top-level `enforcement` field.
+
+For the schema, see [Policy Reference](../policy-reference/). For the trust contract and bypass surfaces, see [Governance overview](../governance-overview/). For wiring the gate into pull requests, see [Enforce in CI](../enforce-in-ci/).
+
+---
+
+## 1. Why pilot first
+
+A new `dependencies.deny` entry, a tighter `mcp.allow` glob, or a stricter `dependencies.max_depth` is retroactive. The next `apm install` in every consuming repo runs the new rule against dependencies that were legal yesterday.
+
+If you flip straight to `enforcement: block`, every CI job on every repo that already has a violation fails on its next run. You will spend the day rolling back instead of rolling out.
+
+Pilot first. Collect the violation list. Fix or grant exceptions. Then escalate.
+
+---
+
+## 2. The three modes
+
+The top-level knob in `apm-policy.yml`:
+
+```yaml
+enforcement: warn   # warn | block | off
+```
+
+Verified in `src/apm_cli/policy/schema.py` and `policy/parser.py`:
+
+| Mode | What `apm install` does | What `apm audit --ci` does |
+|---|---|---|
+| `off` | Skip policy enforcement entirely. | Skip policy checks (baseline lockfile checks still run). |
+| `warn` | Run every check; emit `Policy warning: <dep> -- <reason>`; install proceeds. | Report violations; exit 0. |
+| `block` | Run every check; emit `Policy violation: <dep> -- <reason>`; abort with `PolicyViolationError`. | Report violations; exit non-zero. |
+
+There is no `dry-run` enforcement mode. `--dry-run` is a CLI flag on `apm install` that previews `Would be blocked by policy: <dep> -- <reason>` lines without writing to disk -- usable against any policy mode.
+
+Per-rule modes exist only for two sub-fields: `mcp.self_defined` (`deny | warn | allow`) and `unmanaged_files.action` (`ignore | warn | deny`). Every other rule inherits the top-level `enforcement`.
+
+---
+
+## 3. The rollout sequence
+
+### Step 1 -- Author in warn
+
+Land the new rule with `enforcement: warn` in `<org>/.github/apm-policy.yml`:
+
+```yaml
+name: acme-org-policy
+version: 1
+enforcement: warn
+dependencies:
+  deny:
+    - "legacy-org/*"        # the new rule under pilot
+```
+
+Merge through your `.github` repo's branch protection. Cache TTL defaults to 1 hour; consuming repos pick it up on their next `apm install`.
+
+### Step 2 -- Read the warning telemetry
+
+Three places surface violations:
+
+1. **`apm install` output.** Each violation is written to `DiagnosticCollector` under `CATEGORY_POLICY` and printed in the end-of-install summary (`policy_violation` in `core/command_logger.py`).
+2. **`apm audit --ci --policy org`** in CI. Same checks, structured exit code, and SARIF / JSON output for GitHub Code Scanning (`apm audit --ci --format sarif`). This is the canonical way to collect a fleet-wide violation list -- see [Enforce in CI](../enforce-in-ci/).
+3. **`apm install --dry-run`.** Local preview without writing to disk. Useful for a developer reproducing a CI warning.
+
+Run `apm audit --ci --policy org --format sarif` in every repo (a scheduled workflow is enough) and aggregate. Code Scanning will dedupe by rule and dependency.
+
+### Step 3 -- Remediate
+
+For each violating repo, pick one:
+
+- **Upgrade or replace the dependency.** The default fix.
+- **Grant an exception by relaxing the rule.** APM has no first-class waiver field. Inheritance is tighten-only (`policy/inheritance.py`), so a child repo cannot loosen a parent. The only way to exempt a repo is to relax the rule at the parent level -- typically by narrowing the `deny` glob or adding the specific package to `dependencies.allow`. Document the exception in the policy file itself; that file is your audit log.
+- **Disable for the repo (escape hatch).** A consuming repo can pass `--no-policy` or set `APM_POLICY_DISABLE=1`. This is loud (`policy_disabled` always prints) and covers the whole policy, not one rule. Treat it as break-glass, not as a waiver mechanism.
+
+### Step 4 -- Flip to block
+
+Once the violation count is zero (or the surviving violations are documented exceptions), change one line:
+
+```yaml
+enforcement: block
+```
+
+The next `apm install` in any repo with an undetected violation will now fail closed. CI jobs that already passed under `warn` will continue to pass.
+
+---
+
+## 4. Per-rule vs whole-policy flips
+
+There is no `dependencies.deny.enforcement: block` knob. The top-level `enforcement` applies uniformly to every check.
+
+If you need a single rule to block while everything else only warns, you have two options:
+
+- **Stage rules.** Land rule A in `warn`. When clean, merge rule B in `warn`. When both are clean, flip `enforcement: block`. Slower, but the policy file stays simple.
+- **Split policies via `extends:`.** Author a strict child policy that `extends:` your org policy and lives in a specific scope (e.g., a sub-org's `.github/apm-policy.yml`). Inheritance is tighten-only, so the child can escalate `warn` to `block` for its repos only. See `policy/inheritance.py` and the [Governance overview](../governance-overview/) section on composition.
+
+---
+
+## 5. When to roll back
+
+Flip back to `enforcement: warn` (or `off`) and merge through `.github` branch protection. The next `apm install` in every repo picks up the relaxed policy within the cache TTL (default 1 hour).
+
+Roll back when:
+
+- A violation surge reveals a category of legitimate use you missed.
+- A transitive MCP dependency that you cannot patch on your timeline starts blocking installs.
+- The policy file itself fails to fetch in a way that interacts badly with `policy.fetch_failure: block` -- see [Enforce in CI](../enforce-in-ci/) for the failure-mode matrix.
+
+A rollback is cheap. A blocked org is not. If you are debating, roll back, fix forward, escalate again.
diff --git a/docs/src/content/docs/enterprise/policy-reference.md b/docs/src/content/docs/enterprise/policy-reference.md
index 1c5d0fff1..7488251a4 100644
--- a/docs/src/content/docs/enterprise/policy-reference.md
+++ b/docs/src/content/docs/enterprise/policy-reference.md
@@ -345,8 +345,10 @@ Deny patterns are evaluated first. If a reference matches any deny pattern, it f
 | `ref-consistency` | Every dependency's manifest ref matches the lockfile's resolved ref |
 | `deployed-files-present` | All files listed in lockfile `deployed_files` exist on disk |
 | `no-orphaned-packages` | No lockfile packages are absent from the manifest |
+| `skill-subset-consistency` | `skills:` selections in `apm.yml` match `skill_subset` in the lockfile |
 | `config-consistency` | MCP server configs match lockfile baseline |
-| `content-integrity` | Deployed files contain no critical hidden Unicode characters |
+| `content-integrity` | Deployed files contain no critical hidden Unicode characters and their SHA-256 hashes match the lockfile |
+| `includes-consent` | Advisory check that `includes:` selections in the manifest match what was deployed |
 
 ### Policy checks (run with `--ci --policy`)
 
@@ -524,7 +526,7 @@ dependencies:
 ## Install-time enforcement
 
 :::note[Non-goal: structured output]
-Install-time enforcement does **NOT** emit JSON or SARIF. The output is human-readable terminal text only. For machine-readable policy reports (CI gating, dashboards, code-scanning uploads) use `apm audit --ci --format json` or `apm audit --ci --format sarif` — see [`apm audit`](../../reference/cli-commands/#apm-audit---scan-for-hidden-unicode-characters) in the CLI reference.
+Install-time enforcement does **NOT** emit JSON or SARIF. The output is human-readable terminal text only. For machine-readable policy reports (CI gating, dashboards, code-scanning uploads) use `apm audit --ci --format json` or `apm audit --ci --format sarif` — see [`apm audit`](../../reference/cli/install/) in the CLI reference.
 :::
 
 ### 1. What APM policy is
@@ -765,6 +767,16 @@ Compute the pin on Linux with `sha256sum .github/apm-policy.yml | awk '{print "s
 
 ### 9.7. `apm policy status`: diagnostic snapshot
 
+:::caution[Always exits 0 by default]
+`apm policy status` ALWAYS exits 0 in its default mode, even when
+policy discovery fails or the resolved policy reports violations. It
+is a diagnostic surface, not a CI gate. To make CI fail when policy
+is unreachable or misconfigured, pass `--check` (exits 1 unless
+`outcome=found`). To gate on rule violations, use
+`apm audit --ci --policy <source>` -- baseline + policy checks
+contribute to its non-zero exit.
+:::
+
 Inspect the current policy posture without running an install or audit. The default exit code is always 0, so it is safe for human and SIEM use:
 
 ```shell
diff --git a/docs/src/content/docs/enterprise/registry-proxy.md b/docs/src/content/docs/enterprise/registry-proxy.md
index 99b18b9f4..c8da3f50b 100644
--- a/docs/src/content/docs/enterprise/registry-proxy.md
+++ b/docs/src/content/docs/enterprise/registry-proxy.md
@@ -1,260 +1,154 @@
 ---
-title: "Registry Proxy & Air-gapped"
-description: "Route APM dependency and marketplace traffic through Artifactory or a compatible proxy. Two operating modes, bypass-prevention guarantees, air-gapped CI playbook."
+title: Registry Proxy and Air-Gapped Installs
+description: Route APM downloads through a corporate HTTP proxy, JFrog Artifactory, or an internal marketplace mirror.
 sidebar:
   order: 6
 ---
 
-This page documents how APM routes dependency downloads through an enterprise
-registry proxy (Artifactory or compatible), the trust contract that proves
-traffic cannot bypass the proxy, and the playbook for fully air-gapped CI.
+Enterprise networks rarely allow agents to reach `github.com` directly.
+APM supports three layered controls for that:
 
-For the *policy-cache* offline story (a different mechanism), see
-[Governance #9](../governance-guide/#9-air-gapped-and-offline).
+1. Standard `HTTPS_PROXY` / `NO_PROXY` env vars for forward proxies.
+2. `PROXY_REGISTRY_URL` for a JFrog Artifactory (or compatible) mirror
+   that fronts every package download.
+3. `apm marketplace add --host ...` to register internal marketplaces
+   served from GHES, GHE.com, or GitLab self-managed.
 
-## Why this exists
+For consumer-side token setup, see
+[Authentication](../../consumer/authentication/) and
+[Private and org packages](../../consumer/private-and-org-packages/).
 
-Three audiences ask the same question with different words:
+## When to use what
 
-- **CISO**: "Can I prove ALL dependency traffic flows through Artifactory?
-  What stops a developer or a CI job from going around it?"
-- **VP Engineering**: "We have standardized on Artifactory for npm and PyPI
-  for a decade. Does APM fit that pattern, or is it a new exception?"
-- **Platform tech lead**: "How do I roll this out across N repos? What goes
-  in CI? What is the failure mode when the proxy is down?"
-
-APM answers all three with the same mechanism: a transparent proxy layer that
-rewrites GitHub-based dependency downloads to fetch via Artifactory's Archive
-Entry Download API, plus a lockfile-level guard that prevents bypass.
-
-## Operating modes
-
-APM supports two modes. Most teams want transparent mode; explicit FQDN mode
-is for repos that must pin specific dependencies to the proxy regardless of
-the developer's environment.
-
-### Mode 1: Transparent proxy (recommended)
-
-Set environment variables. APM rewrites every GitHub-hosted dependency
-download (packages and `marketplace.json`) to fetch via the proxy. No changes
-to `apm.yml`.
-
-```bash
-# Required
-export PROXY_REGISTRY_URL="https://art.example.com/artifactory/github"
-
-# Optional
-export PROXY_REGISTRY_TOKEN="<bearer-token>"   # sent as Authorization: Bearer
-export PROXY_REGISTRY_ONLY=1                   # block all direct VCS fallback
-```
-
-| Variable | Purpose |
+| Goal | Mechanism |
 |---|---|
-| `PROXY_REGISTRY_URL` | Full proxy URL including any path prefix (e.g. `/artifactory/github`). When set, all GitHub dependency archives are fetched from this base. |
-| `PROXY_REGISTRY_TOKEN` | Optional bearer token sent on every proxy request. Composes with `GITHUB_APM_PAT` (see [Auth composition](#auth-composition)). |
-| `PROXY_REGISTRY_ONLY` | When set to `1`, APM never falls back to direct VCS hosts. Combined with the lockfile guard below, this is the bypass-prevention contract. |
-
-Apply globally (shell profile, CI secrets, dev-container env) and every
-`apm install` and `apm marketplace` command in the org routes through the proxy.
+| Allowlist outbound traffic at the firewall | `HTTPS_PROXY` |
+| Mirror every dependency archive for audit and replay | `PROXY_REGISTRY_URL` |
+| Serve internal `marketplace.json` listings from a private host | `apm marketplace add --host` |
+| Fully air-gapped CI (no egress at all) | Pre-built bundle from `apm pack` |
 
-:::caution
-Deprecated aliases `ARTIFACTORY_BASE_URL`, `ARTIFACTORY_APM_TOKEN`, and
-`ARTIFACTORY_ONLY` still work but emit a `DeprecationWarning`. Migrate to the
-`PROXY_REGISTRY_*` names.
-:::
+The three compose. A typical hardened setup uses `HTTPS_PROXY` for
+network egress, `PROXY_REGISTRY_URL` for dependency mirroring, and an
+internal marketplace for discovery.
 
-### Mode 2: Explicit FQDN in `apm.yml`
+## Standard HTTP proxy
 
-Reference the proxy directly in the dependency string:
+APM downloads packages with `requests` and `git`. Both honor the
+standard env vars set by your platform team:
 
-```yaml
-dependencies:
-  apm:
-    - art.example.com/artifactory/github/acme-corp/security-baseline#v1.4.0
+```bash
+export HTTPS_PROXY=http://proxy.corp.example.com:8080
+export HTTP_PROXY=http://proxy.corp.example.com:8080
+export NO_PROXY=localhost,127.0.0.1,.corp.example.com
 ```
 
-APM detects the Artifactory path and fetches via the Archive Entry Download
-API for that dependency only. The rest of the manifest behaves normally.
-
-Use this mode when:
+No APM-specific configuration is required. If `git clone` works against
+your private repos through the proxy, `apm install` works too.
 
-- A specific dependency must always come from the proxy regardless of who
-  runs `apm install`.
-- You are publishing a template manifest that downstream consumers should
-  install through your proxy without configuring environment variables.
+## Mirror dependencies through Artifactory
 
-## Bypass-prevention contract
+`PROXY_REGISTRY_URL` rewrites every GitHub-hosted dependency download
+to fetch via Artifactory's Archive Entry Download API. Set in the
+shell profile, the dev container, or CI secrets.
 
-This is the CISO trust statement. APM enforces "all traffic through the
-proxy" with two cooperating mechanisms.
-
-### 1. `PROXY_REGISTRY_ONLY=1` blocks direct fetches at runtime
-
-When set, APM refuses to fall back to `github.com`, GitHub Enterprise Cloud,
-GHES, or any other direct VCS host. If `PROXY_REGISTRY_URL` is not set or
-does not match the dependency's host, the install aborts:
-
-```
-RuntimeError: PROXY_REGISTRY_ONLY is set but no Artifactory proxy is
-configured for 'acme-corp/security-baseline'. Set PROXY_REGISTRY_URL or
-use explicit Artifactory FQDN syntax.
+```bash
+export PROXY_REGISTRY_URL=https://art.example.com/artifactory/github
+export PROXY_REGISTRY_TOKEN=<bearer-token>   # optional
+export PROXY_REGISTRY_ONLY=1                 # block direct VCS fallback
 ```
 
-### 2. Lockfile validation guard prevents replay-from-bypass
+| Variable | Purpose |
+|---|---|
+| `PROXY_REGISTRY_URL` | Full proxy base including any path prefix. When set, all GitHub archives route here. |
+| `PROXY_REGISTRY_TOKEN` | Bearer token sent on proxy requests. Independent of `GITHUB_APM_PAT`. |
+| `PROXY_REGISTRY_ONLY` | `1` blocks direct VCS fallback at runtime and on lockfile replay. |
+| `PROXY_REGISTRY_ALLOW_HTTP` | `1` silences the plaintext-token warning when the proxy is on `http://`. Use only inside an isolated network. |
 
-When a download routes through the proxy, the resulting `apm.lock.yaml`
-entry pins the proxy as the source of truth:
+Deprecated aliases `ARTIFACTORY_BASE_URL`, `ARTIFACTORY_APM_TOKEN`, and
+`ARTIFACTORY_ONLY` still work but emit `DeprecationWarning`. Migrate to
+the `PROXY_REGISTRY_*` names.
 
-```yaml
-dependencies:
-  - repo_url: acme-corp/security-baseline
-    host: art.example.com
-    registry_prefix: artifactory/github
-    resolved_commit: a1b2c3d4...
-    content_hash: "sha256:9f86d081..."
-```
+### Bypass prevention
 
-On every subsequent `apm install` with `PROXY_REGISTRY_ONLY=1`, APM scans
-the lockfile. If any entry is locked to a direct VCS host (github.com, GHE
-Cloud, GHES) instead of the proxy, the install aborts and lists the
-conflicting dependencies:
+When `PROXY_REGISTRY_ONLY=1`, APM refuses to fall back to `github.com`,
+GHE.com, or GHES. The lockfile records `registry_prefix` for every
+proxy-routed dependency. On replay, an entry pinned to a direct VCS
+host aborts the install:
 
-```
+```text
 ERROR: PROXY_REGISTRY_ONLY=1 but the following lockfile entries are
 locked to direct VCS hosts and would bypass the proxy:
-  - acme-corp/security-baseline (host: github.com)
-  - other-org/skill-pack (host: ghes.corp.example.com)
+  - acme/security-baseline (host: github.com)
 Run 'apm install --update' to re-resolve through the proxy.
 ```
 
-`apm install --update` re-resolves dependencies through the active proxy
-and rewrites the lockfile.
-
-### Trust statement (paste into procurement responses)
-
-> When `PROXY_REGISTRY_ONLY=1` is set in CI, APM cannot install a
-> dependency that did not flow through the configured proxy. Any attempt to
-> install a lockfile entry pinned to a direct VCS host aborts with a
-> non-zero exit code before any download occurs.
+`apm install --update` re-resolves through the active proxy and
+rewrites `apm.lock.yaml`.
 
-## Coverage matrix
+### Coverage
 
-What is and is not routed through the proxy:
-
-| Surface | Routed via proxy | Notes |
-|---|---|---|
-| `apm install` (GitHub-hosted deps) | Yes | Packages from github.com, GHE Cloud, GHES |
-| `apm install` (Azure DevOps deps) | **No** | ADO uses a different download path; Artifactory backends recognize GitHub/GitLab archive prefixes only |
-| `apm install --mcp` | **No** | MCP servers come from a separate registry, not GitHub archives |
-| `apm marketplace add` / `browse` / `search` / `update` | Yes | `marketplace.json` fetched via Archive Entry Download; falls back to GitHub Contents API unless `PROXY_REGISTRY_ONLY=1` |
-| `apm pack` / `apm unpack` | N/A | Operate offline once dependencies are local; see [Air-gapped CI playbook](#air-gapped-ci-playbook) |
-| Policy file fetch (`apm-policy.yml`) | **No** | Policy discovery uses the GitHub API directly. See [Governance #9](../governance-guide/#9-air-gapped-and-offline) for the policy-cache offline story. |
-
-When `PROXY_REGISTRY_ONLY=1` is set and a surface is not proxy-routed (ADO,
-MCP), APM aborts rather than silently fetching direct.
-
-## Air-gapped CI playbook
-
-The "fully air-gapped" story has two valid shapes. Pick based on whether CI
-has network reach to the proxy.
-
-### Shape A: CI can reach the proxy
-
-CI is on the corp network with Artifactory access; only the public internet
-is blocked.
-
-```yaml
-# .github/workflows/ci.yml
-env:
-  PROXY_REGISTRY_URL: https://art.corp.example.com/artifactory/github
-  PROXY_REGISTRY_TOKEN: ${{ secrets.ARTIFACTORY_TOKEN }}
-  PROXY_REGISTRY_ONLY: "1"
-
-jobs:
-  install:
-    runs-on: self-hosted
-    steps:
-      - uses: actions/checkout@v4
-      - uses: microsoft/apm-action@v1
-      - run: apm install
-      - run: apm audit --ci --policy ./vendored-policy.yml
-```
+| Surface | Routed via proxy |
+|---|---|
+| `apm install` (GitHub-hosted deps) | Yes |
+| `apm install` (Azure DevOps deps) | No -- ADO uses a different path |
+| `apm install --mcp` (MCP servers) | No -- separate registry |
+| `apm marketplace` (`marketplace.json` fetch) | Yes; falls back to GitHub Contents API unless `PROXY_REGISTRY_ONLY=1` |
+| Policy file fetch (`apm-policy.yml`) | No -- uses the GitHub API directly |
 
-`apm install` routes every dependency and `marketplace.json` fetch through
-Artifactory. `apm audit --ci --policy` enforces governance from a vendored
-policy file with no network calls (see [Governance #9](../governance-guide/#9-air-gapped-and-offline)).
-The lockfile guard catches any entry that would bypass the proxy on
-re-install.
+When a surface is not proxy-routed and `PROXY_REGISTRY_ONLY=1`, APM
+aborts rather than silently fetching direct.
 
-### Shape B: CI has no network at all (bundle delivery)
+## Internal marketplaces
 
-CI cannot reach the proxy or the public internet. Build a bundle on a
-connected host, transport it, restore it offline.
+A marketplace is a Git repo containing a `marketplace.json`. To point
+at one hosted on GHES, GHE.com, or GitLab self-managed:
 
 ```bash
-# On a connected build host (with proxy configured)
-export PROXY_REGISTRY_URL=https://art.corp.example.com/artifactory/github
-export PROXY_REGISTRY_ONLY=1
-apm install
-apm pack --format apm --archive -o ./artifacts/
-
-# Transport ./artifacts/*.tar.gz to the air-gapped network
-
-# In air-gapped CI (no APM, no Python, no network)
-tar xzf bundle.tar.gz -C .
-# Files are deployed; agents can read them immediately
+apm marketplace add acme-tools/agents \
+  --host ghes.corp.example.com \
+  --branch main
 ```
 
-See [Pack & Distribute](../../guides/pack-distribute/) for bundle structure
-and the `apm-action` restore mode.
+The entry is stored in `~/.apm/marketplaces.json`. Auth uses the same
+PAT as private dependency installs (`GITHUB_APM_PAT`,
+`GITHUB_APM_PAT_<ORG>`, or the GitLab equivalent). See
+[Private and org packages](../../consumer/private-and-org-packages/).
 
-### Prewarming the policy cache
+## Cache behavior
 
-Independent of dependency traffic, the *policy* fetch goes direct to
-GitHub. For air-gapped runs that need policy enforcement on `apm install`,
-prewarm `<project_root>/apm_modules/.policy-cache/` or use
-`apm audit --ci --policy <path>` as the gating check. Details in
-[Governance #9](../governance-guide/#9-air-gapped-and-offline).
+APM keeps a local cache at `~/.apm/cache/`:
 
-## Failure modes
+- Git checkouts (full repository clones, reused across resolves).
+- HTTP cache (proxy responses, `marketplace.json` snapshots).
 
-| Symptom | Cause | Resolution |
-|---|---|---|
-| `RuntimeError: PROXY_REGISTRY_ONLY is set but no Artifactory proxy is configured for '<dep>'` | `PROXY_REGISTRY_ONLY=1` set but `PROXY_REGISTRY_URL` is empty, or the dep is on an unproxied host (ADO) | Set `PROXY_REGISTRY_URL`, or use explicit FQDN syntax in `apm.yml`, or unset `PROXY_REGISTRY_ONLY` for that dep type |
-| `ERROR: PROXY_REGISTRY_ONLY=1 but the following lockfile entries are locked to direct VCS hosts` | Lockfile was generated before the proxy was configured | Run `apm install --update` to re-resolve through the proxy |
-| HTTP 401/403 from the proxy | Missing or invalid `PROXY_REGISTRY_TOKEN`, or token lacks read on the upstream repo | Verify the token has Artifactory read on the repository being fetched |
-| Proxy unreachable (timeout, DNS) with `PROXY_REGISTRY_ONLY=1` | Proxy down, network partition | Install fails closed. Restore proxy connectivity or fall back to a pre-built [bundle](../../guides/pack-distribute/) |
-| `DeprecationWarning: ARTIFACTORY_BASE_URL is deprecated` | Using legacy env-var names | Rename to `PROXY_REGISTRY_*`. Old names continue to work but will be removed in a future major release |
-| Warning: lockfile entry locked to proxy is missing `content_hash` | Older proxy-routed entry without integrity hash | Run `apm install --update` to populate. Without `content_hash`, a tampered proxy could redirect downloads without detection |
+The proxy is upstream of the cache. A cached entry is keyed by the
+resolved URL, so switching `PROXY_REGISTRY_URL` produces a fresh
+download. Integrity is unchanged: every install verifies the
+`content_hash` recorded in `apm.lock.yaml` regardless of where the
+bytes came from. A tampered proxy that rewrites archive contents is
+caught by the lockfile guard, not the cache.
 
-## Auth composition
+Inspect or reset the cache with `apm cache info`, `apm cache prune`,
+and `apm cache clean`.
 
-`PROXY_REGISTRY_TOKEN` and the GitHub PAT (`GITHUB_APM_PAT`, `GITHUB_TOKEN`,
-`GH_TOKEN`) are independent and used for different request paths:
+## Troubleshooting
 
-- Requests to `PROXY_REGISTRY_URL` send `Authorization: Bearer
-  <PROXY_REGISTRY_TOKEN>`.
-- Requests to `github.com` / GHE / GHES (only possible when
-  `PROXY_REGISTRY_ONLY` is unset) use the GitHub PAT.
-
-In a hybrid setup where `PROXY_REGISTRY_ONLY` is unset and some dependencies
-fall back to direct GitHub (because they are not mirrored), both tokens are
-used: proxy traffic auths with the bearer, direct traffic auths with the
-PAT. Set both in CI secrets if you support hybrid.
-
-For strict environments, set `PROXY_REGISTRY_ONLY=1` and only configure
-`PROXY_REGISTRY_TOKEN`. The GitHub PAT is then unused at install time.
-
-## HTTP proxies
+| Symptom | Cause | Fix |
+|---|---|---|
+| `RuntimeError: PROXY_REGISTRY_ONLY is set but no Artifactory proxy is configured for '<dep>'` | `PROXY_REGISTRY_ONLY=1` with no `PROXY_REGISTRY_URL`, or dep is on an unproxied host (ADO, MCP) | Set `PROXY_REGISTRY_URL`, or unset `PROXY_REGISTRY_ONLY` for that dep type |
+| `ERROR: ... locked to direct VCS hosts` | Lockfile predates the proxy | `apm install --update` |
+| HTTP 401/403 from the proxy | Missing or invalid `PROXY_REGISTRY_TOKEN` | Verify the token has read on the upstream repo path |
+| `git clone` hangs through the proxy | `HTTPS_PROXY` not set in the env that runs `git` | Export it in the shell that invokes `apm install`; CI secrets often miss this |
+| `DeprecationWarning: ARTIFACTORY_BASE_URL is deprecated` | Legacy env names | Rename to `PROXY_REGISTRY_*` |
+| Plaintext-token warning on proxy startup | Token sent over `http://` | Use `https://`, or set `PROXY_REGISTRY_ALLOW_HTTP=1` if the link is internal-only |
 
-The proxy can be served over HTTP, but APM treats this as an insecure
-dependency channel. The same approval surface applies as for any HTTP
-dependency: see [HTTP (insecure) dependencies](../security/#http-insecure-dependencies).
-Production deployments should always use HTTPS.
+For fully disconnected CI (no proxy reach at all), build a bundle on a
+connected host with `apm pack` and restore offline. See
+[Pack and distribute](../../guides/pack-distribute/).
 
 ## See also
 
-- [Governance #9](../governance-guide/#9-air-gapped-and-offline) -- offline policy enforcement (different mechanism)
-- [Security Model](../security/) -- attack surface, content scanning, HTTP dep handling
-- [Pack & Distribute](../../guides/pack-distribute/) -- bundle delivery for fully disconnected CI
-- [Marketplaces](../../guides/marketplaces/) -- marketplace command surface
+- [Authentication](../../consumer/authentication/) -- token resolution order
+- [Private and org packages](../../consumer/private-and-org-packages/) -- per-host PAT scoping
+- [Pack and distribute](../../guides/pack-distribute/) -- air-gapped bundle delivery
+- [Governance overview](../governance-overview/) -- policy-cache offline story
diff --git a/docs/src/content/docs/enterprise/security-and-supply-chain.md b/docs/src/content/docs/enterprise/security-and-supply-chain.md
new file mode 100644
index 000000000..78725f133
--- /dev/null
+++ b/docs/src/content/docs/enterprise/security-and-supply-chain.md
@@ -0,0 +1,186 @@
+---
+title: Security and Supply Chain
+description: APM's threat model and the mechanisms that back it -- integrity, provenance, secrets, scanning, policy gates -- and what APM does not defend against.
+sidebar:
+  order: 7
+---
+
+This page is for the admin or security reviewer who has to sign off on
+APM. It states the threat model in one paragraph, then walks the
+mechanisms in the source that back it -- and is equally explicit about
+what APM does not defend against.
+
+## Threat model
+
+APM defends the **build-time supply chain** for AI agent context:
+prompts, instructions, skills, hooks, and MCP server declarations
+flowing from a git source through `apm install` into your project tree
+and on into seven harnesses. The defended properties are reproducibility
+(same install everywhere), integrity (downloaded content matches the
+lockfile), provenance (every dep traces to a pinned commit at a named
+host), and pre-deploy content safety (no hidden Unicode reaches the
+agent). APM does **not** sandbox MCP servers at runtime, does not do
+malware analysis on dependency code, does not sign packages, and does
+not inspect what an agent does once it has read your context. See
+[The three promises](../../concepts/the-three-promises/) for the
+canonical framing.
+
+## Integrity
+
+Three layers, in order of when they fire:
+
+**Lockfile pinning.** `apm.lock.yaml` records the full 40-char
+`resolved_commit` for every dep and the `content_hash` (SHA-256 over
+the sorted file tree) of what was installed. Source:
+`src/apm_cli/deps/lockfile.py`.
+
+**Fresh-download hash check.** When APM downloads a package whose
+lockfile entry already has a `content_hash`, it recomputes the hash
+post-download and aborts the install on mismatch -- the partial
+download is removed and the user is told to use `apm install --update`
+if the change is intentional. Source: `src/apm_cli/install/sources.py`
+lines 621-649.
+
+**Cache-hit verification.** On every cache HIT, APM reads the cached
+checkout's `.git/HEAD` and compares it to the lockfile's
+`resolved_commit`. The `.git/HEAD` file is read directly rather than
+spawning `git rev-parse`, so a poisoned `.git/config` cannot subvert
+the check. On mismatch the cache entry is evicted and a fresh fetch
+runs. Source: `src/apm_cli/cache/integrity.py:74` (`verify_checkout_sha`).
+
+Bundles (the local-file install path used by `apm pack` outputs) get a
+fourth check: every file listed in `pack.bundle_files` is SHA-256
+verified, symlinks anywhere under the bundle root are rejected, and
+files not listed in the manifest are flagged as a tampering signal.
+Source: `src/apm_cli/bundle/local_bundle.py:276-351`
+(`verify_bundle_integrity`).
+
+## Provenance
+
+Dependencies are git URLs. There is no central registry to compromise.
+Every lockfile entry records `host`, `repo_url`, `resolved_ref`, and
+`resolved_commit`, so "where did this file come from?" is answered by
+one `grep` of `apm.lock.yaml`.
+
+HTTP (cleartext) git deps require explicit opt-in on both the manifest
+(`allow_insecure: true` per dep) and the CLI (`apm install
+--allow-insecure`). For HTTP fetches APM suppresses git credential
+helpers so stored tokens are never sent in the clear. HTTP makes the
+first fetch's hash and commit untrusted-by-channel even though replay
+detection remains intact -- treat HTTP deps as "I trust the network
+path" assertions, not as "APM made this safe".
+
+For the registry-proxy / air-gap story see
+[Registry proxy](../registry-proxy/).
+
+## Secret handling
+
+APM has no secret store. The contract is:
+
+- **Tokens come from the environment.** `GITHUB_APM_PAT` for GitHub
+  hosts, `ADO_APM_PAT` for Azure DevOps. Tokens are scoped per host
+  family and never forwarded cross-host. See
+  [Authentication](../../consumer/authentication/).
+- **MCP `env:` blocks in `apm.yml` are name/value pairs**, intended to
+  hold *references* (e.g. `GITHUB_TOKEN: ${GITHUB_TOKEN}`) that the
+  harness resolves at agent runtime, not literal secrets. Source:
+  `src/apm_cli/install/mcp/entry.py`,
+  `src/apm_cli/integration/mcp_integrator.py:205,219-221`.
+- **`apm install` writes `apm_modules/` to `.gitignore` automatically**
+  on first install. Source:
+  `src/apm_cli/commands/_helpers.py:437` (`_update_gitignore_for_apm_modules`).
+  This keeps cached source trees out of commits.
+- **`apm.yml` is committed; `.env` is yours.** APM never reads `.env`
+  files itself; that is delegated to the agent harness.
+
+Recommendation: scan committed `apm.yml` files in CI for literal
+secrets in `mcp.env` values -- APM does not enforce env-var indirection,
+it only assumes it.
+
+## Content scanning
+
+Agent context is executable for an LLM. APM scans for hidden Unicode
+that humans cannot see on screen but a tokenizer reads as instructions.
+
+`ContentScanner` (`src/apm_cli/security/content_scanner.py`)
+classifies each codepoint as `critical`, `warning`, or `info`:
+
+| Severity | Examples | Why |
+|---|---|---|
+| critical | Tag chars (U+E0001-E007F), bidi overrides (U+202A-E, U+2066-9), variation selectors 17-256 (U+E0100-E01EF) | No legitimate use in prompt files. Glassworm-class hidden-payload vectors. |
+| warning | Zero-width spaces/joiners (U+200B-D), bidi marks, invisible math operators, deprecated formatting | Common copy-paste debris that *can* hide content. ZWJ inside an emoji sequence is downgraded to info. |
+| info | Non-breaking spaces, leading BOM, emoji presentation selector | Logged for awareness, not actioned. |
+
+`SecurityGate` (`src/apm_cli/security/gate.py`) wraps the scanner and
+is what every command calls. The two policies that matter:
+
+- `BLOCK_POLICY` -- used by `install`, `compile`, and `unpack`.
+  Critical findings block deployment. `--force` downgrades to a
+  warning.
+- `REPORT_POLICY` -- used by `apm audit` and the lockfile-driven
+  `scan_lockfile_packages` (`src/apm_cli/security/file_scanner.py`).
+  Collects findings without blocking; the command decides exit code.
+
+`apm audit` exposes the scanner directly: `--file` for arbitrary files,
+`--strip` (with optional `--dry-run`) to remove dangerous chars in
+place, `-f sarif|json|markdown -o <path>` for CI reporting. Exit codes:
+`0` clean, `1` critical, `2` warnings only. Source:
+`src/apm_cli/commands/audit.py`.
+
+## Policy gates that block install
+
+`apm-policy.yml` is evaluated **before** any download or write. The
+preflight (`src/apm_cli/policy/install_preflight.py`) walks the
+resolved dependency graph -- including transitive MCP servers -- and
+fails the install if a dep is not in the allow list, falls under a
+deny rule, uses a forbidden source/scope, or violates a configured
+trust rule.
+
+In CI, `apm audit --ci` runs the same baseline checks plus the policy
+checks in `src/apm_cli/policy/policy_checks.py` (allow/deny lists,
+target restrictions, MCP transport restrictions). Tighten-only
+inheritance (enterprise -> org -> repo) is enforced in
+`src/apm_cli/policy/inheritance.py`.
+
+For schema and getting started, see [Get started with apm-policy.yml](../apm-policy-getting-started/) and
+[Policy Reference](../policy-reference/).
+
+## What APM does NOT do
+
+State this plainly to your security reviewers:
+
+- **Not a runtime sandbox.** APM exits after install. It does not
+  monitor what your agent or any installed MCP server does with the
+  context it received.
+- **Not malware analysis.** APM does not statically analyse dep code or
+  hooks for malicious behaviour. Hooks run in your harness, not in
+  APM. Read them.
+- **Not signing infrastructure.** APM has no concept of package
+  signatures, key servers, or verified publishers today. Trust derives
+  from the host (GitHub / ADO / GitLab), the pinned commit SHA, and
+  the content hash -- not from a cryptographic identity attached to
+  the package itself. (`src/apm_cli/install/cache_pin.py:24` notes
+  signatures as deferred.)
+- **Not transport security on `http://` deps.** See "Provenance"
+  above.
+- **Not protection against visible prompt injection.** The Unicode
+  scanner catches *hidden* characters. A package author who writes a
+  malicious instruction in plain English will pass every check.
+
+## Recommended hardening
+
+For an org standardising on APM:
+
+- Require `GITHUB_APM_PAT` / `ADO_APM_PAT` from a secret store, never
+  from developer dotfiles. Scope tokens to read-only on the source
+  repos.
+- Wire `apm audit --ci -f sarif -o audit.sarif` into branch protection
+  and upload SARIF to GitHub code scanning.
+- Publish an `apm-policy.yml` from your `<org>/.github` repo with an
+  allow list and a transport restriction on MCP. See [Governance overview](../governance-overview/).
+- Require signed commits on the source repos APM pulls from -- this is
+  where APM's trust chain bottoms out.
+- Route all dep traffic through an enterprise proxy with audit
+  logging. See [Registry proxy](../registry-proxy/).
+- Forbid `allow_insecure: true` in `apm.yml` via the policy allow
+  list, except where an air-gapped mirror demands it.
diff --git a/docs/src/content/docs/enterprise/security.md b/docs/src/content/docs/enterprise/security.md
index 6656527d2..546d5e96f 100644
--- a/docs/src/content/docs/enterprise/security.md
+++ b/docs/src/content/docs/enterprise/security.md
@@ -123,7 +123,7 @@ Content scanning extends beyond install:
 
 - **`apm compile`** scans compiled output (AGENTS.md, CLAUDE.md, `.github/copilot-instructions.md`, commands) before writing to disk. Critical findings cause `apm compile` to exit with code 1 after writing — defense-in-depth since source files were already scanned at install, but compilation assembles content from multiple sources. `.github/copilot-instructions.md` is assembled from global instructions in `.apm/instructions/`, including those installed under `apm_modules/`.
 - **`apm pack`** scans files before bundling. This catches hidden characters before a package is published, preventing authors from accidentally distributing tainted content.
-- **`apm unpack`** scans bundle contents before deployment. This is a pre-deployment gate matching `apm install` — critical findings block deployment unless `--force` is used.
+- **`apm unpack`** scans bundle contents before deployment. This is a pre-deployment gate matching `apm install` — critical findings block deployment unless `--force` is used. (Note: `apm unpack` is DEPRECATED and scheduled for removal in v0.14; prefer `apm install <bundle-path>` for new pipelines -- it applies the same scan plus lockfile integration. See [Pack and distribute](../../guides/pack-distribute/).)
 
 ### On-demand scanning
 
@@ -146,7 +146,7 @@ apm audit -f json -o report.json       # Machine-readable
 apm audit -f markdown -o report.md     # Step summaries
 ```
 
-See [Content scanning with `apm audit`](../governance/#content-scanning-with-apm-audit) for usage details and exit codes.
+See [Content scanning with `apm audit`](../../reference/cli/install/) for usage details and exit codes.
 
 ### Limitations
 
@@ -299,7 +299,7 @@ When `ADO_APM_PAT` is unset, APM can authenticate to Azure DevOps with a Microso
 - **Compatible with managed-identity / service-account-only orgs.** Works in environments where PAT creation is disabled, including WIF-backed pipelines.
 - **Same transport rules as PATs.** Bearer values are injected via `http.extraheader`, scoped to ADO hosts only, and never logged.
 
-See [Authentication: AAD bearer tokens](../../getting-started/authentication/#authenticating-with-microsoft-entra-id-aad-bearer-tokens) for the resolution precedence and CI patterns.
+See [Azure DevOps AAD bearer tokens](#azure-devops-aad-bearer-tokens) above for the resolution precedence and CI patterns.
 
 ## Attack surface comparison
 
@@ -321,7 +321,7 @@ Not without detection. APM scans all package source files before deployment. Cri
 
 ### How do I audit what APM installed?
 
-The `apm.lock.yaml` file records every dependency (with exact commit SHA) and every file deployed. It is a plain YAML file suitable for automated policy checks, diff review, and compliance tooling. See [Governance & Compliance](../governance/) for audit workflows.
+The `apm.lock.yaml` file records every dependency (with exact commit SHA) and every file deployed. It is a plain YAML file suitable for automated policy checks, diff review, and compliance tooling. See the [Governance Guide](../governance-guide/) for audit workflows.
 
 ### Is the APM binary signed?
 
diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md
index 01729ca19..0f96200c2 100644
--- a/docs/src/content/docs/getting-started/first-package.md
+++ b/docs/src/content/docs/getting-started/first-package.md
@@ -15,7 +15,7 @@ Otherwise, start here.
 
 ## Prerequisites
 
-- APM installed -- see [Installation](/apm/getting-started/installation/).
+- APM installed -- see [Installation](/apm/quickstart/).
 - A GitHub account and an empty repo for publishing (step 5).
 - A runtime where you can try the result: GitHub Copilot, Claude Code, or
   Cursor.
@@ -114,7 +114,7 @@ the skill fires.
 > [`.apm/skills/python-architecture/SKILL.md`](https://github.com/microsoft/apm/blob/main/.apm/skills/python-architecture/SKILL.md)
 > in this repo. Same shape, different concern.
 
-See the [Skills guide](/apm/guides/skills/) for the full schema.
+See the [Skills guide](/apm/producer/author-primitives/skills/) for the full schema.
 
 ## 3. Add a custom agent
 
@@ -161,7 +161,7 @@ Do not rewrite the code yourself. Point and explain.
 > A real example: this repo's documentation agent lives at
 > [`.apm/agents/doc-writer.agent.md`](https://github.com/microsoft/apm/blob/main/.apm/agents/doc-writer.agent.md).
 
-See the [Agent Workflows guide](/apm/guides/agent-workflows/) for more.
+See the [Agent Workflows guide](/apm/producer/author-primitives/instructions-and-agents/) for more.
 
 ## 4. Deploy and use
 
@@ -217,7 +217,7 @@ code 2 and a teaching message instead of silently picking a target -- declare an
 intent explicitly via `--target copilot` (or another harness), or by adding
 `targets: [copilot]` to `apm.yml`. Run `apm targets` to inspect what APM detects
 in the current directory. To target explicitly, see the
-[Compilation guide](/apm/guides/compilation/).
+[Compilation guide](/apm/producer/compile/).
 
 > **What about `apm compile`?** Compile is a different concern: it
 > generates merged `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` files for tools
@@ -289,8 +289,8 @@ If you know up front that you want to ship a plugin, you can scaffold with
 from day one. APM still gives you dependency management, the lockfile, and
 audit while you author; pack produces the plugin bundle when you ship.
 
-For the full reference, see the [Pack & Distribute guide](/apm/guides/pack-distribute/)
-and the [Plugin authoring guide](/apm/guides/plugins/).
+For the full reference, see the [Pack & Distribute guide](/apm/producer/)
+and the [Plugin authoring guide](/apm/producer/author-primitives/).
 
 ## Choosing a package layout
 
@@ -313,13 +313,13 @@ For the full comparison and metadata precedence rules, see
 
 ## Next steps
 
-- [Anatomy of an APM Package](/apm/introduction/anatomy-of-an-apm-package/)
+- [Anatomy of an APM Package](/apm/concepts/package-anatomy/)
   -- the full mental model: `.apm/` vs `apm_modules/` vs `.github/`.
-- [Skills guide](/apm/guides/skills/) -- bundled resources, sub-skills,
+- [Skills guide](/apm/producer/author-primitives/skills/) -- bundled resources, sub-skills,
   activation tuning.
-- [Agent Workflows guide](/apm/guides/agent-workflows/) -- chaining agents,
+- [Agent Workflows guide](/apm/producer/author-primitives/instructions-and-agents/) -- chaining agents,
   GitHub Agentic Workflows integration.
-- [Dependencies guide](/apm/guides/dependencies/) -- depend on other APM
+- [Dependencies guide](/apm/consumer/manage-dependencies/) -- depend on other APM
   packages, file-level imports, version pinning.
-- [`apm audit`](/apm/reference/cli-commands/) -- scan dependencies for
+- [`apm audit`](/apm/reference/cli/install/) -- scan dependencies for
   policy violations before they ship.
diff --git a/docs/src/content/docs/getting-started/migration.md b/docs/src/content/docs/getting-started/migration.md
index 1d9b9388b..123e2eabb 100644
--- a/docs/src/content/docs/getting-started/migration.md
+++ b/docs/src/content/docs/getting-started/migration.md
@@ -92,7 +92,7 @@ skill collection layout reference.
 - [Quick start](../quick-start/) -- first-time setup walkthrough
 - [Dependencies](../../guides/dependencies/) -- managing external packages
 - [Manifest schema](../../reference/manifest-schema/) -- full `apm.yml` reference
-- [CLI commands](../../reference/cli-commands/) -- complete command reference
+- [CLI commands](../../reference/cli/install/) -- complete command reference
 
 ## Deprecated targets
 
diff --git a/docs/src/content/docs/getting-started/quick-start.md b/docs/src/content/docs/getting-started/quick-start.md
deleted file mode 100644
index 664ad5921..000000000
--- a/docs/src/content/docs/getting-started/quick-start.md
+++ /dev/null
@@ -1,184 +0,0 @@
----
-title: "Quick Start"
-description: "Get APM running and install your first package in under 3 minutes."
-sidebar:
-  order: 2
----
-
-Three commands. Three minutes. Your AI agent learns your project's standards automatically.
-
-## Install APM
-
-**macOS / Linux:**
-
-```bash
-curl -sSL https://aka.ms/apm-unix | sh
-```
-
-**Windows (PowerShell):**
-
-```powershell
-irm https://aka.ms/apm-windows | iex
-```
-
-Verify it worked:
-
-```bash
-apm --version
-```
-
-For Homebrew (macOS/Linux), Scoop (Windows), pip, or manual install, see the [Installation guide](../installation/).
-
-## Start a project
-
-Create a new project:
-
-```bash
-apm init my-project && cd my-project
-```
-
-Or initialize inside an existing repository:
-
-```bash
-cd your-repo
-apm init
-```
-
-Either way, APM creates an `apm.yml` manifest -- your dependency file for AI agent configuration:
-
-```yaml title="apm.yml"
-name: my-project
-version: 1.0.0
-dependencies:
-  apm: []
-```
-
-## Install a package
-
-This is where it gets interesting. Install a package and watch what happens:
-
-```bash
-apm install microsoft/apm-sample-package#v1.0.0
-```
-
-:::tip[Already use the gh CLI?]
-If you are logged in with `gh auth login`, APM is already authenticated for private GitHub packages on github.com, `*.ghe.com`, and GHES -- no env vars to set.
-:::
-
-APM downloads the package, resolves its dependencies, and deploys files directly into the directories your AI tools already watch:
-
-```
-my-project/
-  apm.yml
-  apm.lock.yaml
-  apm_modules/
-    microsoft/
-      apm-sample-package/
-  .github/
-    instructions/
-      apm-sample-package/
-        design-standards.instructions.md
-    prompts/
-      apm-sample-package/
-        accessibility-audit.prompt.md
-        design-review.prompt.md
-  .claude/
-    commands/
-      apm-sample-package/
-        ...
-  .cursor/
-    rules/
-      design-standards.mdc
-    agents/
-      design-reviewer.md
-  .opencode/
-    agents/
-      design-reviewer.md
-    commands/
-      design-review.md
-  .gemini/
-    commands/
-      design-review.toml
-```
-
-Three things happened:
-
-1. The package was downloaded into `apm_modules/` (like `node_modules/`).
-2. Agents, commands, skills, and hooks were deployed to `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, and `.gemini/` (when present). If the project has its own `.apm/` content, that is deployed too (local content takes priority over dependencies on collision).
-3. A lockfile (`apm.lock.yaml`) was created, pinning the exact commit so every team member gets identical configuration.
-
-Your `apm.yml` now tracks the dependency:
-
-```yaml title="apm.yml"
-name: my-project
-version: 1.0.0
-dependencies:
-  apm:
-    - microsoft/apm-sample-package#v1.0.0
-```
-
-## Get Copilot reading your packages in under a minute
-
-Run one more command:
-
-```bash
-apm compile -t copilot
-```
-
-APM assembles every global instruction it just installed into `.github/copilot-instructions.md` -- the file VS Code and GitHub Copilot read automatically. No configuration, no extra setup; open the project in VS Code and Copilot is already grounded in your packages' standards.
-
-## That's it
-
-Open your editor. GitHub Copilot, Claude, Cursor, and OpenCode pick up the new context immediately -- no extra configuration, no compile step, no restart. The agent now knows your project's design standards, can run your prompt templates, and follows the conventions defined in the package.
-
-This is the core idea: **packages define what your AI agent knows, and `apm install` puts that knowledge exactly where your tools expect it.**
-
-## Day-to-day workflow
-
-When a new developer joins your team:
-
-```bash
-git clone <your-repo>
-cd <your-repo>
-apm install
-```
-
-The lockfile ensures everyone gets the same agent configuration. Same as `npm install` after cloning a Node project.
-
-Add more packages as your project evolves:
-
-```bash
-apm install github/awesome-copilot/skills/review-and-refactor
-```
-
-**What to commit:**
-- `apm.yml` and `apm.lock.yaml` — version-controlled, shared with the team.
-- `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context immediately after cloning, before they run `apm install` to sync and regenerate files.
-- `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale for Claude Code users: committed files give instant context on clone, while `apm install` remains the way to refresh them from `apm.yml`.
-- `.cursor/` deployed files (`rules/`, `agents/`, `skills/`, `hooks/`) -- same rationale for Cursor users.
-- `.gemini/` deployed files (`commands/`, `skills/`, `settings.json`) -- same rationale for Gemini CLI users.
-- `apm_modules/` -- add to `.gitignore`. Rebuilt from the lockfile on install.
-
-:::tip[Keeping deployed files in sync]
-When you update `apm.yml`, re-run `apm install` and commit the changed `.github/`, `.claude/`, `.cursor/`, and `.gemini/` files. A [CI drift check](../../guides/drift-detection/) catches stale files automatically.
-:::
-
-:::note[Using Codex or Gemini?]
-Gemini and Codex need `apm compile` for instructions (`GEMINI.md` / `AGENTS.md`). Gemini receives commands, skills, hooks, and MCP via `apm install`. See the [Compilation guide](../../guides/compilation/) for details.
-:::
-
-## Add MCP servers
-
-APM also manages MCP servers -- the tools your AI agent calls at runtime.
-
-```bash
-apm install --mcp io.github.github/github-mcp-server
-```
-
-This wires the server into every detected client (Copilot, Claude, Cursor, Codex, OpenCode, Gemini). See the [MCP Servers guide](../../guides/mcp-servers/) for stdio and remote shapes.
-
-## Next steps
-
-- [Your First Package](../first-package/) -- create and share your own APM package.
-- [Dependency management](../../guides/dependencies/) -- version pinning, updates, and transitive resolution.
-- [CLI reference](../../reference/cli-commands/) -- full list of commands and options.
diff --git a/docs/src/content/docs/guides/agent-workflows.md b/docs/src/content/docs/guides/agent-workflows.md
deleted file mode 100644
index 3fec72d97..000000000
--- a/docs/src/content/docs/guides/agent-workflows.md
+++ /dev/null
@@ -1,246 +0,0 @@
----
-title: "Agent Workflows (Experimental)"
-description: "Run agentic workflows locally using APM scripts and AI runtimes."
-sidebar:
-  order: 9
----
-
-:::caution[Experimental Feature]
-APM's core value is dependency management — `apm install`, `apm.lock.yaml`, `apm audit`. The workflow execution features described on this page are experimental and may change. For most users, `apm install` is all you need.
-:::
-
-## What are Agent Workflows?
-
-Agent workflows let you run `.prompt.md` files locally through AI runtimes — similar to [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-github-copilot-coding-agent-in-public-preview/), but on your machine.
-
-Scripts are defined in `apm.yml` or auto-discovered from installed packages. You execute them with `apm run`, passing parameters and choosing a runtime (Copilot CLI, Codex, LLM).
-
-## Setting Up a Runtime
-
-Before running workflows, install at least one AI runtime:
-
-```bash
-# GitHub Copilot CLI (recommended)
-apm runtime setup copilot
-
-# OpenAI Codex CLI
-apm runtime setup codex
-
-# LLM library
-apm runtime setup llm
-```
-
-Verify installed runtimes:
-
-```bash
-apm runtime list
-```
-
-### Runtime requirements
-
-| Runtime | Requirements | Notes |
-|---------|-------------|-------|
-| Copilot CLI | Node.js v22+, npm v10+ | Recommended. MCP config at `~/.copilot/` |
-| Codex | Node.js | Set `GITHUB_TOKEN` for GitHub Models support |
-| LLM | Python 3.10+ | Supports multiple model providers |
-
-**Copilot CLI** is the recommended runtime — it requires no API keys for installation and integrates with GitHub Copilot directly.
-
-For **Codex**, configure authentication after setup:
-
-```bash
-export GITHUB_TOKEN=your_github_token
-```
-
-For **LLM**, configure at least one model provider:
-
-```bash
-llm keys set github      # GitHub Models (free)
-llm keys set openai      # OpenAI
-llm keys set anthropic   # Anthropic
-```
-
-For more details on runtime capabilities and configuration, see the [Runtime Compatibility](../../integrations/runtime-compatibility/) page.
-
-## Defining Scripts
-
-### Explicit scripts in apm.yml
-
-Define scripts in your `apm.yml` to map names to prompt files and runtimes:
-
-```yaml
-scripts:
-  start:
-    description: "Default workflow"
-    prompt: .apm/prompts/start.prompt.md
-    runtime: copilot
-  review:
-    description: "Code review"
-    prompt: .apm/prompts/review.prompt.md
-    runtime: copilot
-  analyze:
-    description: "Log analysis"
-    prompt: .apm/prompts/analyze-logs.prompt.md
-    runtime: llm
-```
-
-You can also use the shorthand format for simple scripts:
-
-```yaml
-scripts:
-  start: "copilot --full-auto -p analyze-logs.prompt.md"
-  debug: "RUST_LOG=debug codex analyze-logs.prompt.md"
-  llm-script: "llm analyze-logs.prompt.md -m github/gpt-4o-mini"
-```
-
-### Auto-discovery (zero configuration)
-
-When you install packages that include `.prompt.md` files, APM auto-discovers them as runnable scripts — no `apm.yml` configuration needed:
-
-```bash
-apm install github/awesome-copilot/skills/review-and-refactor
-apm run review-and-refactor    # Works immediately
-```
-
-APM searches for prompts in this order:
-
-1. Local prompts in the project
-2. `.apm/prompts/` directory
-3. `.github/prompts/` directory
-4. Installed package dependencies
-
-Use `apm list` to see all available scripts (both configured and auto-discovered).
-
-### Handling name collisions
-
-If multiple packages provide prompts with the same name, use qualified paths:
-
-```bash
-apm run github/awesome-copilot/code-review --param pr_url=...
-apm run acme/standards/code-review --param pr_url=...
-```
-
-## Running Workflows
-
-### Basic execution
-
-```bash
-apm run start
-```
-
-### Passing parameters
-
-Use `--param` to pass input values that map to `${input:name}` placeholders in prompt files:
-
-```bash
-apm run start --param service_name=api-gateway --param time_window="1h"
-apm run code-review --param pull_request_url="https://github.com/org/repo/pull/123"
-```
-
-### Previewing before running
-
-Preview the compiled prompt (with parameters substituted) without executing it:
-
-```bash
-apm preview start --param service_name=api-gateway --param time_window="1h"
-```
-
-### Listing available scripts
-
-```bash
-apm list
-```
-
-This shows all scripts — both explicitly defined in `apm.yml` and auto-discovered from installed packages.
-
-## Prompt File Structure
-
-Prompt files (`.prompt.md`) use YAML frontmatter for metadata and Markdown for the prompt body:
-
-```markdown
----
-description: Analyzes application logs to identify errors and patterns
-author: DevOps Team
-mcp:
-  - logs-analyzer
-input:
-  - service_name
-  - time_window
-  - log_level
----
-
-# Analyze Application Logs
-
-You are an expert DevOps engineer specializing in log analysis.
-
-## Context
-
-- Service: ${input:service_name}
-- Time window: ${input:time_window}
-- Log level: ${input:log_level}
-
-## Task
-
-1. Retrieve logs for the specified service
-2. Identify error patterns and anomalies
-3. Suggest remediation steps
-```
-
-Use `${input:parameter_name}` syntax for dynamic values that are filled in at runtime via `--param`.
-
-For full details on prompt file syntax, compilation, and dependency management, see the [Prompts guide](../prompts/).
-
-## Example Workflows
-
-### Code review
-
-Install a code review prompt and run it against a pull request:
-
-```bash
-apm install github/awesome-copilot/skills/review-and-refactor
-
-apm run review-and-refactor \
-  --param pull_request_url="https://github.com/org/repo/pull/42"
-```
-
-### Security scan
-
-Define a security-focused workflow in `apm.yml`:
-
-```yaml
-scripts:
-  security:
-    description: "Security vulnerability scan"
-    prompt: .apm/prompts/security-scan.prompt.md
-    runtime: copilot
-```
-
-Then run it:
-
-```bash
-apm run security --param target_dir="src/"
-```
-
-### Multi-runtime setup
-
-Use different runtimes for different tasks:
-
-```yaml
-scripts:
-  review: "copilot --full-auto -p code-review.prompt.md"
-  summarize: "llm summarize.prompt.md -m github/gpt-4o-mini"
-  debug: "RUST_LOG=debug codex debug-analysis.prompt.md"
-```
-
-```bash
-apm run review --param files="src/"
-apm run summarize --param scope="recent-changes"
-```
-
-## Troubleshooting
-
-**Runtime not found**: Run `apm runtime list` to verify installation. Re-run `apm runtime setup <name>` if needed.
-
-**Command not found after setup**: Ensure the runtime binary is on your PATH. For Copilot CLI, verify Node.js v22+ is installed. For LLM, ensure the Python virtual environment is active.
-
-**No scripts available**: Run `apm list` to check. If empty, either define scripts in `apm.yml` or install a package that includes `.prompt.md` files.
diff --git a/docs/src/content/docs/guides/ci-policy-setup.md b/docs/src/content/docs/guides/ci-policy-setup.md
deleted file mode 100644
index 18f7b841d..000000000
--- a/docs/src/content/docs/guides/ci-policy-setup.md
+++ /dev/null
@@ -1,245 +0,0 @@
----
-title: CI Policy Enforcement
-sidebar:
-  order: 8
----
-
-:::caution[Experimental Feature]
-Policy enforcement (`apm audit --ci --policy`) is an early preview for testing and feedback. The policy schema, check behavior, and inheritance model may change based on community input. Do not use as a production governance gate without understanding that breaking changes are possible in upcoming releases.
-:::
-
-Set up automated policy enforcement so every pull request is checked against your organization's governance rules.
-
-## Prerequisites
-
-- An organization on GitHub with repositories using APM
-- `apm audit --ci` runs 7 baseline consistency checks with no configuration
-- `apm audit --ci --policy org` adds 17 policy checks defined in `apm-policy.yml`
-
-For the full policy schema, see the [Policy Reference](../../enterprise/policy-reference/).
-
-## Step 1: Create the org policy
-
-Create `apm-policy.yml` in your org's `.github` repository. APM auto-discovers this file when `--policy org` is used.
-
-```
-your-org/.github/
-└── apm-policy.yml
-```
-
-Start with a minimal policy:
-
-```yaml
-name: "Your Org Policy"
-version: "1.0.0"
-enforcement: block
-
-dependencies:
-  allow:
-    - "your-org/**"
-  deny:
-    - "untrusted-org/**"
-
-mcp:
-  self_defined: warn
-  transport:
-    allow: [stdio, streamable-http]
-```
-
-Commit this to the default branch of `your-org/.github`.
-
-## Step 2: Add baseline CI checks
-
-Add `apm audit --ci` to your CI pipeline. This runs 6 lockfile consistency checks — no policy file needed:
-
-```yaml
-# .github/workflows/apm-policy.yml
-name: APM Policy Compliance
-
-on:
-  pull_request:
-    paths:
-      - 'apm.yml'
-      - 'apm.lock.yaml'
-      - '.github/agents/**'
-      - '.github/instructions/**'
-      - '.github/hooks/**'
-      - '.cursor/**'
-      - '.claude/**'
-
-jobs:
-  apm-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install APM
-        run: curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash
-
-      - name: Run baseline checks
-        run: apm audit --ci
-```
-
-This catches lockfile/manifest drift, missing files, and hidden Unicode — without any policy configuration.
-
-## Step 3: Enable policy enforcement
-
-Add `--policy org` to run the full 17 policy checks on top of baseline:
-
-:::note
-Since this release, `apm audit --ci` auto-discovers the org policy. `--policy org` remains valid as an explicit override; use `--no-policy` to skip discovery.
-:::
-
-```yaml
-      - name: Run policy checks
-        run: apm audit --ci --policy org --no-cache -f sarif -o policy-report.sarif
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Upload SARIF
-        if: always()
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: policy-report.sarif
-          category: apm-policy
-```
-
-Key flags:
-- `--policy org` — auto-discovers `apm-policy.yml` from your org's `.github` repo
-- `--no-cache` — fetches the latest policy (recommended for CI)
-- `-f sarif -o policy-report.sarif` — generates SARIF for GitHub Code Scanning
-
-The `GITHUB_TOKEN` provides read access to the `.github` repository for policy discovery.
-
-A ready-to-use workflow template is available at [`templates/policy-ci-workflow.yml`](https://github.com/microsoft/apm/blob/main/templates/policy-ci-workflow.yml) in the APM repository.
-
-## Step 4: Add repo-level overrides (optional)
-
-Individual repositories can tighten the org policy by adding their own `apm-policy.yml` with `extends: org`:
-
-```yaml
-# repo-level apm-policy.yml
-name: "Frontend Team Policy"
-version: "1.0.0"
-extends: org
-
-dependencies:
-  deny:
-    - "legacy-org/**"  # Additional restriction
-
-unmanaged_files:
-  action: deny  # Stricter than org default
-```
-
-Child policies can only tighten constraints — never relax them. See [Inheritance](../../enterprise/policy-reference/#inheritance) for merge rules.
-
-To use a repo-level policy file in CI:
-
-```bash
-apm audit --ci --policy ./apm-policy.yml
-```
-
-## Make it a required check
-
-Configure the workflow as a required status check so PRs cannot merge with policy violations:
-
-1. Go to repository (or org) **Settings → Rules → Rulesets**.
-2. Create a ruleset targeting your protected branches.
-3. Add **Require status checks to pass**.
-4. Select the `apm-audit` job.
-
-See [GitHub Rulesets](../../integrations/github-rulesets/) for org-wide setup.
-
-## Alternative policy sources
-
-### Local file
-
-```bash
-apm audit --ci --policy ./policies/apm-policy.yml
-```
-
-### URL
-
-```bash
-apm audit --ci --policy https://example.com/policies/apm-policy.yml
-```
-
-### Cross-org
-
-```bash
-apm audit --ci --policy enterprise-hub/.github
-```
-
-## Other CI systems
-
-### GitLab CI
-
-```yaml
-apm-policy:
-  image: python:3.12-slim
-  script:
-    - curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash
-    - apm audit --ci --policy org --no-cache
-  rules:
-    - changes:
-        - apm.yml
-        - apm.lock.yaml
-```
-
-### Azure Pipelines
-
-```yaml
-- task: Bash@3
-  displayName: 'APM Policy Check'
-  inputs:
-    targetType: inline
-    script: |
-      curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash
-      apm audit --ci --policy org --no-cache
-  env:
-    GITHUB_TOKEN: $(GITHUB_TOKEN)
-```
-
-## What a violation looks like
-
-When a developer adds a denied package to `apm.yml`:
-
-```yaml
-dependencies:
-  apm:
-    - untrusted-org/random-skills
-```
-
-The CI run fails with a clear pointer to the offending rule:
-
-```
-[x] Policy violation: dependency 'untrusted-org/random-skills' is denied by org policy
-    Policy: contoso/.github/apm-policy.yml
-    Rule:   dependencies.deny matches 'untrusted-org/**'
-```
-
-With `-f sarif -o results.sarif` and the GitHub Code Scanning upload step (Step 3 above), the same finding renders inline on the PR diff. The required status check stays red until the violation is resolved or the org policy is amended through its own change-management process.
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | All checks passed |
-| 1 | One or more checks failed |
-
-## Output formats
-
-| Format | Flag | Use case |
-|--------|------|----------|
-| Text | `-f text` (default) | Human-readable Rich table |
-| JSON | `-f json` | Machine-readable, tooling integration |
-| SARIF | `-f sarif` | GitHub Code Scanning, VS Code |
-
-Combine with `-o <path>` to write to a file.
-
-## Related
-
-- [Governance](../../enterprise/governance-guide/) -- conceptual overview, bypass contract, and rollout playbook
-- [`apm-policy.yml`](../../enterprise/apm-policy/) -- mental model and how the policy file works
-- [Policy Reference](../../enterprise/policy-reference/) -- full `apm-policy.yml` schema reference
-- [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check
diff --git a/docs/src/content/docs/guides/compilation.md b/docs/src/content/docs/guides/compilation.md
deleted file mode 100644
index 40137d365..000000000
--- a/docs/src/content/docs/guides/compilation.md
+++ /dev/null
@@ -1,529 +0,0 @@
----
-title: "Compilation"
-sidebar:
-  order: 1
----
-
-Compilation is **optional for some users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For Gemini, `apm install` deploys commands, skills, and hooks, but instructions require `apm compile` to generate `GEMINI.md`. For OpenCode and Codex, `apm install` deploys agents, commands, skills, and hooks, but instructions require `apm compile` to generate `AGENTS.md`. For Windsurf, `apm install` deploys all primitives natively (instructions to `.windsurf/rules/`, agents to `.windsurf/skills/`); `apm compile` is optional if you also want a compiled `AGENTS.md` roll-up.
-
-**Solving the AI agent scalability problem through constraint satisfaction optimization**
-
-APM's compilation system implements a mathematically rigorous solution to the **context pollution problem** that degrades AI agent performance as projects grow. Through constraint satisfaction optimization and hierarchical coverage guarantees, `apm compile` transforms scattered primitives into optimized context files for every major AI coding agent.
-
-## Multi-Agent Output
-
-APM compiles your primitives into native formats for each major AI coding agent. Target selection is automatic based on your project structure.
-
-### Target Auto-Detection
-
-When you run `apm compile` without specifying a target, APM automatically detects:
-
-| Project Structure | Target | What Gets Generated |
-|-------------------|--------|---------------------|
-| `.github/` folder only | `copilot` | AGENTS.md (instructions only) |
-| `.claude/` folder only | `claude` | CLAUDE.md (instructions only) |
-| `.codex/` folder exists | `codex` | AGENTS.md (instructions only) |
-| `.gemini/` folder exists | `gemini` | GEMINI.md (instructions only) |
-| `.windsurf/` folder exists | `windsurf` | AGENTS.md (instructions only) |
-| Multiple folders exist | `all` | AGENTS.md + CLAUDE.md + GEMINI.md |
-| Neither folder exists | `minimal` | AGENTS.md only (universal format) |
-
-```bash
-apm compile                    # Auto-detects target from project structure
-apm compile --target copilot   # Force GitHub Copilot, Cursor
-apm compile --target claude    # Force Claude Code, Claude Desktop
-apm compile --target gemini    # Force Gemini CLI
-apm compile --target codex     # Force Codex CLI
-apm compile --target windsurf  # Force Windsurf/Cascade
-apm compile -t claude,copilot  # Multiple targets (comma-separated)
-```
-
-You can set a persistent target in `apm.yml`:
-```yaml
-name: my-project
-version: 1.0.0
-target: copilot  # single target
-```
-
-```yaml
-name: my-project
-version: 1.0.0
-target: [claude, copilot]  # multiple targets -- only these are compiled
-```
-
-### Output Files
-
-| Target | Files Generated | Consumers |
-|--------|-----------------|-----------|
-| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode |
-| `claude` | `CLAUDE.md` | Claude Code, Claude Desktop |
-| `gemini` | `GEMINI.md` | Gemini CLI |
-| `codex` | `AGENTS.md` | Codex CLI |
-| `windsurf` | `AGENTS.md` | Windsurf/Cascade |
-| `all` | `AGENTS.md` + `CLAUDE.md` + `GEMINI.md` | Universal compatibility |
-| `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
-
-> **Aliases**: `vscode` and `agents` are accepted as aliases for `copilot`.
-
-> **Note**: `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, `.opencode/commands/`, `.codex/agents/`, `.gemini/commands/`, and `.agents/skills/`.
-
-### How It Works
-
-1. **Primitives Discovery**: Scans `.apm/` and `.github/` directories for instructions, prompts, and agents
-2. **Dependency Merging**: Incorporates primitives from installed packages in `apm_modules/`
-3. **Optimization**: Applies mathematical context optimization (see below)
-4. **Format Generation**: Outputs native files for each target agent format
-
-### Example Output
-
-**After `apm compile`:**
-```
-my-project/
-├── AGENTS.md              # Instructions only (for Copilot, Cursor, etc.)
-└── CLAUDE.md              # Instructions only (for Claude)
-```
-
-**After `apm install` (folder integration):**
-```
-my-project/
-├── .github/
-│   ├── prompts/           # Prompts from installed packages
-│   └── agents/            # Agents from installed packages
-├── .claude/
-│   ├── commands/          # Claude slash commands from packages
-│   └── skills/            # Skills from packages with SKILL.md
-└── .cursor/
-    ├── rules/             # Instructions converted to Cursor rules
-    └── agents/            # Agents from installed packages
-```
-
-## The Context Pollution Problem
-
-### Why Traditional Approaches Fail
-
-In traditional monolithic AGENTS.md approaches, AI agents face a fundamental efficiency problem: **context pollution**. As projects grow, agents must process increasingly large amounts of irrelevant instructions, degrading performance and overwhelming context windows.
-
-**The Mathematical Challenge**:
-```
-Context_Efficiency = Relevant_Instructions / Total_Instructions_Inherited
-```
-
-Without optimization, context efficiency degrades quadratically with project size, creating an unsustainable burden on AI agents working in specific directories.
-
-### The AGENTS.md Standard Solution
-
-APM implements the [AGENTS.md standard](https://agents.md) for hierarchical context files:
-
-- **Recursive Discovery**: Agents read AGENTS.md files from current directory up to project root
-- **Proximity Priority**: Closest AGENTS.md to the edited file takes precedence  
-- **Inheritance Model**: Child directories inherit and can override parent instructions
-- **Universal Compatibility**: Works with GitHub Copilot, Cursor, Claude, and all AGENTS.md-compliant tools
-
-## The Mathematical Foundation
-
-### Core Optimization Problem
-
-APM treats instruction placement as a **constrained optimization problem**:
-
-```
-Objective: minimize Σ(pollution[d] × files[d])
-           d∈directories
-
-Subject to: ∀f ∈ matching_files(pattern) → 
-           ∃p ∈ placements : f.can_inherit_from(p)
-
-Variables: placement_matrix ∈ {0,1}^(directories × instructions)
-```
-
-This mathematical formulation guarantees:
-1. **Complete Coverage**: Every file can access its applicable instructions
-2. **Minimal Pollution**: Irrelevant context is systematically minimized
-3. **Hierarchical Validity**: Inheritance chains remain consistent
-
-### The Three-Tier Placement Algorithm
-
-APM employs sophisticated distribution scoring with mathematical thresholds:
-
-```python
-# From context_optimizer.py
-Distribution_Score = (matching_directories / total_directories) × diversity_factor
-
-Where:
-diversity_factor = 1.0 + (depth_variance × DIVERSITY_FACTOR_BASE)
-DIVERSITY_FACTOR_BASE = 0.5  # Mathematical constant
-```
-
-**Strategy Selection**:
-
-| Distribution Score | Strategy | Mathematical Logic |
-|-------------------|----------|-------------------|
-| < 0.3 | Single-Point | `_optimize_single_point_placement()` |
-| 0.3 - 0.7 | Selective Multi | `_optimize_selective_placement()` |
-| > 0.7 | Distributed | `_optimize_distributed_placement()` |
-
-### Constraint Satisfaction Weights
-
-The optimization engine uses mathematically calibrated weights:
-
-```python
-# Mathematical optimization parameters from the source
-COVERAGE_EFFICIENCY_WEIGHT = 1.0    # Mandatory coverage priority
-POLLUTION_MINIMIZATION_WEIGHT = 0.8  # Strong pollution penalty
-MAINTENANCE_LOCALITY_WEIGHT = 0.3    # Moderate locality preference
-DEPTH_PENALTY_FACTOR = 0.1          # Excessive nesting penalty
-```
-
-## Understanding the Metrics
-
-### Context Efficiency Ratio
-
-The primary performance indicator for AI agent effectiveness:
-
-```python
-def get_efficiency_ratio(self) -> float:
-    """Calculate context efficiency ratio."""
-    if self.total_context_load == 0:
-        return 1.0
-    return self.relevant_context_load / self.total_context_load
-```
-
-**Interpretation Guide**:
-
-| Efficiency Range | Assessment | Optimization Quality |
-|-----------------|------------|-------------------|
-| 80-100% | Excellent | Near-perfect instruction locality |
-| 60-80% | Good | Well-optimized with minimal conflicts |
-| 40-60% | Fair | Acceptable coverage/efficiency balance |
-| 20-40% | Poor | Significant cross-cutting concerns |
-| 0-20% | Critical | Architecture requires refactoring |
-
-**Important**: Low efficiency can be mathematically optimal when coverage constraints force root placement. The optimizer **always prioritizes complete coverage** over efficiency.
-
-### Distribution Score Analysis
-
-Measures pattern spread across the directory structure:
-
-```python
-def _calculate_distribution_score(self, matching_directories: Set[Path]) -> float:
-    """Calculate distribution score with diversity factor."""
-    total_dirs_with_files = len([d for d in self._directory_cache.values() if d.total_files > 0])
-    base_ratio = len(matching_directories) / total_dirs_with_files
-    
-    # Account for depth diversity
-    depths = [self._directory_cache[d].depth for d in matching_directories]
-    depth_variance = sum((d - sum(depths)/len(depths))**2 for d in depths) / len(depths)
-    diversity_factor = 1.0 + (depth_variance * self.DIVERSITY_FACTOR_BASE)
-    
-    return base_ratio * diversity_factor
-```
-
-### Coverage Verification
-
-Mathematical guarantee that no instruction is lost:
-
-```python
-def _calculate_hierarchical_coverage(self, placements: List[Path], target_directories: Set[Path]) -> Set[Path]:
-    """Verify hierarchical coverage through inheritance chains."""
-    covered = set()
-    for target in target_directories:
-        for placement in placements:
-            if self._is_hierarchically_covered(target, placement):
-                covered.add(target)
-                break
-    return covered
-```
-
-## Usage and Configuration
-
-### Basic Compilation (Default: Distributed)
-
-```bash
-# Intelligent distributed optimization
-apm compile
-
-# Example output:
-Analyzing 247 files across 12 directories...
-Optimizing instruction placement...
-Generated 4 AGENTS.md files with guaranteed coverage
-```
-
-### Mathematical Analysis Mode
-
-```bash
-# Show optimization reasoning
-apm compile --verbose
-
-# Example detailed output:
-Mathematical Analysis:
-|- Distribution Scores:
-|  |- **/*.py: 0.23 -> Single-Point Strategy
-|  |- **/*.tsx: 0.67 -> Selective Multi Strategy  
-|  +- **/*.md: 0.81 -> Distributed Strategy
-|- Coverage Verification: Complete (100%)
-|- Constraint Satisfaction: All 8 constraints satisfied
-+- Generation Time: 127ms
-```
-
-### Performance Analysis
-
-```bash
-# Preview placement without writing files
-apm compile --dry-run
-
-# Timing instrumentation
-apm compile --verbose
-# Shows: Project Analysis: 45.2ms
-#        Instruction Processing: 82.1ms
-```
-
-### Configuration Control
-
-```yaml
-# apm.yml
-compilation:
-  strategy: "distributed"  # Default: mathematical optimization
-  exclude:
-    # Directory exclusion patterns (glob syntax)
-    - "apm_modules/**"           # Exclude installed packages
-    - "tmp/**"                   # Exclude temporary files
-    - "coverage/**"              # Exclude test coverage
-    - "**/test-fixtures/**"      # Exclude test fixtures everywhere
-  placement:
-    min_instructions_per_file: 1  # Minimal context principle
-    clean_orphaned: true  # Remove outdated files
-  optimization:
-    # Mathematical weights (advanced users)
-    coverage_weight: 1.0      # Coverage priority (mandatory)
-    pollution_weight: 0.8     # Pollution minimization
-    locality_weight: 0.3      # Maintenance locality
-```
-
-#### Directory Exclusion Patterns
-
-Use the `exclude` field to skip directories during compilation, improving performance in large monorepos:
-
-**Pattern Syntax:**
-- `tmp` - Matches directory named "tmp" at any depth
-- `tmp/` - Same as above (trailing slash optional)
-- `projects/packages/apm` - Matches specific nested path
-- `**/node_modules` - Matches "node_modules" at any depth
-- `coverage/**` - Matches "coverage" and all subdirectories
-- `projects/**/apm/**` - Complex nested matching
-
-**Use Cases:**
-- Exclude source package development directories in monorepos
-- Skip temporary directories and build artifacts
-- Improve compilation performance by avoiding unnecessary scans
-- Prevent duplicate instruction discovery
-
-**Default Exclusions:**
-APM always excludes directories whose path contains an exact component matching one of these names (no configuration needed). A directory named `rebuild/` is **not** excluded just because it contains `build` as a substring.
-- `node_modules`
-- `__pycache__`
-- `.git`
-- `dist`
-- `build`
-- `apm_modules`
-- Hidden directories (starting with `.`)
-
-## Advanced Optimization Features
-
-### Hierarchical Coverage Guarantee
-
-The mathematical **coverage constraint** ensures no instruction is ever lost:
-
-```
-project/
-├── AGENTS.md                    # Global standards
-├── src/
-│   ├── AGENTS.md               # Source code patterns
-│   └── components/
-│       ├── AGENTS.md           # Component-specific
-│       └── Button.tsx          # Inherits: global + src + components
-```
-
-**Coverage Verification Algorithm**:
-```python
-def verify_coverage(placements, matching_files):
-    """Ensure every file can inherit its instructions"""
-    for file in matching_files:
-        chain = get_inheritance_chain(file)
-        if not any(p in chain for p in placements):
-            raise CoverageViolation(file)  # Mathematical guarantee
-    return True
-```
-
-### Performance Engineering
-
-**Multi-layer caching system** for sub-second compilation:
-
-```python
-# From context_optimizer.py
-self._directory_cache: Dict[Path, DirectoryAnalysis] = {}
-self._pattern_cache: Dict[str, Set[Path]] = {}
-self._glob_cache: Dict[str, List[str]] = {}
-```
-
-**Typical performance**: < 500ms for projects with 10,000+ files
-
-### Deterministic Output
-
-Compilation is completely reproducible:
-- Sorted iteration order prevents randomness
-- Stable optimization algorithm
-- Consistent Build IDs across machines
-- Cache-friendly for CI/CD systems
-
-### Constitution Injection
-
-Project governance automatically injected at AGENTS.md top:
-
-```markdown
-<!-- SPEC-KIT CONSTITUTION: BEGIN -->
-hash: 34c5812dafc9 path: memory/constitution.md
-[Project principles and governance]
-<!-- SPEC-KIT CONSTITUTION: END -->
-```
-
-## Real-World Application
-
-### Enterprise React Application Case
-
-**Project Characteristics**:
-- 15,000+ lines of code
-- 127 component files
-- 8 instruction patterns
-- 3 team-specific standards
-
-**Optimization Results**:
-- **7 strategically placed** AGENTS.md files
-- **Complete coverage** mathematically verified
-- **Context efficiency**: 67.3% (Good rating)
-- **Generation time**: 89ms
-
-**Compared to Monolithic Approach**:
-- Single 847-line AGENTS.md file
-- Universal context pollution
-- No mathematical optimization
-- Manual maintenance required
-
-## Technical Innovation
-
-### Constraint Satisfaction Algorithm
-
-APM implements **complete coverage with minimal pollution**:
-
-1. **Coverage Constraint**: Mathematical guarantee every file accesses applicable instructions
-2. **Pollution Minimization**: Systematic reduction of irrelevant context
-3. **Hierarchical Validation**: Inheritance chain verification
-4. **Performance Optimization**: Sub-second compilation with caching
-
-### Three-Tier Strategy Implementation
-
-```python
-# Actual implementation from context_optimizer.py
-if distribution_score < self.LOW_DISTRIBUTION_THRESHOLD:
-    strategy = PlacementStrategy.SINGLE_POINT
-    placements = self._optimize_single_point_placement(matching_directories, instruction)
-elif distribution_score > self.HIGH_DISTRIBUTION_THRESHOLD:
-    strategy = PlacementStrategy.DISTRIBUTED  
-    placements = self._optimize_distributed_placement(matching_directories, instruction)
-else:
-    strategy = PlacementStrategy.SELECTIVE_MULTI
-    placements = self._optimize_selective_placement(matching_directories, instruction)
-```
-
-### Mathematical Sophistication
-
-The optimization engine implements:
-- **Variance-weighted distribution scoring**
-- **Hierarchical coverage verification**  
-- **Constraint satisfaction with fallback guarantees**
-- **Performance-optimized caching strategies**
-- **Deterministic reproducible results**
-
-## Tool Compatibility
-
-Different AI tools get different levels of support from `apm install` vs `apm compile`:
-
-| AI Tool | What `apm install` deploys | What `apm compile` adds | Support level |
-|---------|--------------------------|------------------------|---------------|
-| GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** |
-| Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
-| Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
-| OpenCode | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP) | Via `AGENTS.md` | **Full** |
-| Codex CLI | `.agents/skills/`, `.codex/agents/`, `.codex/hooks.json` | `AGENTS.md` (instructions) | **Full** |
-| Gemini | `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json` (MCP, hooks) | `GEMINI.md` (instructions) | **Full** |
-| Windsurf | `.windsurf/rules/`, `.windsurf/skills/`, `.windsurf/workflows/`, `.windsurf/hooks.json` | `AGENTS.md` (instructions) | **Full** |
-
-For Copilot, Claude, and Cursor users, `apm install` handles everything natively. Gemini, OpenCode, Codex, and Windsurf users should also run `apm compile` to generate their instruction roll-up (`GEMINI.md` or `AGENTS.md`).
-
-## Theoretical Foundations
-
-### Computational Complexity
-
-- **Time Complexity**: O(n·m·log(d))
-  - n = number of instructions
-  - m = number of directories  
-  - d = maximum directory depth
-
-- **Space Complexity**: O(n·m)
-  - Placement matrix storage
-
-### Optimization Bounds
-
-**Theoretical maximum efficiency**:
-```
-Max_Efficiency = 1 - (cross_cutting_patterns / total_patterns)
-```
-
-Most well-structured projects achieve 60-85% of theoretical maximum through mathematical optimization.
-
-## Future Enhancements
-
-### Planned Optimizations
-
-**Machine Learning Enhancement**: Neural network to predict optimal placement based on:
-- Historical agent query patterns
-- File change frequency analysis
-- Team-specific access patterns
-
-**Dynamic Recompilation**: File watcher with targeted optimization:
-```bash
-apm compile --watch  # Auto-recompile on changes
-```
-
-**Context Budget Optimization**: Token-aware instruction prioritization:
-```yaml
-compilation:
-  optimization:
-    max_tokens_per_file: 4000
-    priority_scoring: true
-```
-
-## Conclusion
-
-APM's Context Optimization Engine represents a fundamental advancement in AI-assisted development infrastructure. By treating instruction distribution as a **mathematical optimization problem** with **guaranteed coverage constraints**, APM creates:
-
-1. **Mathematically optimal context loading** for AI agents
-2. **Complete coverage guarantee** through constraint satisfaction
-3. **Linear scalability** with project size
-4. **Universal compatibility** with the AGENTS.md standard
-5. **Performance engineering** with sub-second compilation
-
-The result: AI agents that work efficiently and reliably, regardless of project size or complexity.
-
----
-
-**Ready to optimize your AI agent performance?**
-
-```bash
-# See the mathematics in action
-apm compile --verbose
-
-# Experience optimized AI development
-apm init my-project && cd my-project && apm compile
-```
-
-**Technical Implementation**: ``src/apm_cli/compilation/``  
-**Mathematical Core**: ``context_optimizer.py``
\ No newline at end of file
diff --git a/docs/src/content/docs/guides/dependencies.md b/docs/src/content/docs/guides/dependencies.md
deleted file mode 100644
index 3aef6d3ae..000000000
--- a/docs/src/content/docs/guides/dependencies.md
+++ /dev/null
@@ -1,1112 +0,0 @@
----
-title: "Dependencies"
-sidebar:
-  order: 5
----
-
-Complete guide to APM package dependency management - share and reuse context collections across projects for consistent, scalable AI-native development.
-
-## What Are APM Dependencies?
-
-APM dependencies are git repositories containing `.apm/` directories with context collections (instructions, chatmodes, contexts) and agent workflows (prompts). They enable teams to:
-
-- **Share proven workflows** across projects and team members
-- **Standardize compliance and design patterns** organization-wide
-- **Build on tested context** instead of starting from scratch
-- **Maintain consistency** across multiple repositories and teams
-
-APM supports any git-accessible host — GitHub, GitLab, Bitbucket, Gitea, Gogs, self-hosted instances, and more. See [GitHub Authentication Setup](#github-authentication-setup) below for how tokens flow to non-GitHub hosts via the git credential helper.
-
-## Dependency Types
-
-APM supports multiple dependency types:
-
-| Type | Detection | Example |
-|------|-----------|---------|
-| **APM Package** | Has `apm.yml` | `microsoft/apm-sample-package` |
-| **Marketplace Plugin** | Has `plugin.json` (no `apm.yml`) | `github/awesome-copilot/plugins/context-engineering` |
-| **Claude Skill** | Has `SKILL.md` (no `apm.yml`) | `ComposioHQ/awesome-claude-skills/brand-guidelines` |
-| **Hook Package** | Has `hooks/*.json` (no `apm.yml` or `SKILL.md`) | `anthropics/claude-plugins-official/plugins/hookify` |
-| **Virtual Subdirectory Package** | Folder path in monorepo | `ComposioHQ/awesome-claude-skills/mcp-builder` |
-| **Virtual Subdirectory Package** | Folder path in repo | `github/awesome-copilot/skills/review-and-refactor` |
-| **Local Path Package** | Path starts with `./`, `../`, or `/` | `./packages/my-shared-skills` |
-| **ADO Package** | Azure DevOps repo | `dev.azure.com/org/project/_git/repo` or `dev.azure.com/org/My%20Project/_git/My%20Repo` |
-
-**Virtual Subdirectory Packages** are skill folders from monorepos - they download an entire folder and may contain a SKILL.md plus resources.
-
-**Virtual File Packages** download a single file (like a prompt or instruction) and integrate it directly.
-
-**Marketplaces:** Plugins installed as `apm install name@marketplace` resolve from a registered index. On **GitLab-class** hosts, monorepo plugins whose sources live in a subdirectory of the marketplace repository itself are supported without hand-writing object-form `git:` + `path:` entries. See the [Marketplaces guide](./marketplaces/).
-
-For self-hosted **Gitea** and **Gogs**, virtual subdirectory and file packages resolve via the `/{owner}/{repo}/raw/{ref}/{path}` URL first, then fall back to the Contents API (v1 native, v3 Gogs-compat). On **GitLab-class** hosts (gitlab.com and self-managed GitLab), virtual subdirectory and file packages resolve via the GitLab REST v4 `/projects/{id}/repository/files/{path}/raw` endpoint with `PRIVATE-TOKEN` auth.
-
-### Claude Skills
-
-Claude Skills are packages with a `SKILL.md` file that describe capabilities for AI agents. APM can install them and transform them for your target platform:
-
-```bash
-# Install a Claude Skill
-apm install ComposioHQ/awesome-claude-skills/brand-guidelines
-
-# For copilot target: generates .github/agents/brand-guidelines.agent.md
-# For Claude target: keeps native SKILL.md format
-```
-
-#### Skill Integration During Install
-
-Skills are integrated to `.github/skills/`:
-
-| Source | Result |
-|--------|--------|
-| Package with `SKILL.md` | Skill folder copied to `.github/skills/{folder-name}/` |
-| Package without `SKILL.md` | No skill folder created |
-
-#### Skill Folder Naming
-
-Skill folders use the **source folder name directly** (not flattened paths):
-
-```
-.github/skills/
-├── brand-guidelines/      # From ComposioHQ/awesome-claude-skills/brand-guidelines
-├── mcp-builder/           # From ComposioHQ/awesome-claude-skills/mcp-builder
-└── apm-sample-package/     # From microsoft/apm-sample-package
-```
-
-→ See [Skills Guide](../skills/) for complete documentation.
-
-## Quick Start
-
-### 1. Add Dependencies to Your Project
-
-Add APM dependencies to your `apm.yml` file:
-
-```yaml
-name: my-project
-version: 1.0.0
-dependencies:
-  apm:
-    # GitHub shorthand (default)
-    - microsoft/apm-sample-package#v1.0.0
-    - github/awesome-copilot/skills/review-and-refactor
-
-    # Full HTTPS git URL (any host)
-    - https://gitlab.com/acme/coding-standards.git
-    - https://bitbucket.org/acme/security-rules.git
-
-    # SSH git URL (any host)
-    - git@gitlab.com:acme/coding-standards.git
-
-    # FQDN shorthand with virtual path (any host)
-    - gitlab.com/acme/repo/prompts/code-review.prompt.md
-
-    # Local path (for development / monorepo workflows)
-    - ./packages/my-shared-skills          # relative to project root
-    - /home/user/repos/my-ai-package       # absolute path
-
-    # Object format: git URL + sub-path / ref / alias
-    - git: https://gitlab.com/acme/coding-standards.git
-      path: instructions/security
-      ref: v2.0
-  mcp:
-    - io.github.github/github-mcp-server          # Registry reference (string)
-    - name: io.github.github/github-mcp-server      # Registry with overlays
-      transport: stdio
-      tools: ["repos", "issues"]
-    - name: internal-knowledge-base                  # Self-defined (private server)
-      registry: false
-      transport: http
-      url: "${KNOWLEDGE_BASE_URL}"
-      env:
-        KB_TOKEN: "${KB_TOKEN}"
-```
-
-APM accepts dependencies in two forms:
-
-**String format** (simple cases):
-- **Shorthand** (`owner/repo`) — defaults to GitHub
-- **HTTPS URL** (`https://host/owner/repo.git`) — any git host, whole repo
-  - Custom port: `https://host:8443/owner/repo.git` — port is preserved in clone URLs
-- **SSH URL** (`git@host:owner/repo.git`) — any git host, whole repo
-  - Custom port: `ssh://git@host:7999/owner/repo.git` — use the `ssh://` form to specify a port (SCP shorthand `git@host:...` cannot carry a port)
-- **FQDN shorthand** (`host/owner/repo`) — any host, supports nested groups
-  - GitLab nested groups: `gitlab.com/group/subgroup/repo`
-  - Virtual paths on simple repos: `gitlab.com/owner/repo/file.prompt.md`
-  - For nested groups + virtual paths, use the object format below
-- **Local path** (`./path`, `../path`, `/absolute/path`) — local filesystem package
-
-**Object format** (when you need `path`, `ref`, or `alias` on a git URL):
-
-```yaml
-dependencies:
-  apm:
-    - git: https://gitlab.com/acme/coding-standards.git
-      path: instructions/security        # virtual sub-path inside the repo
-      ref: v2.0                          # pin to a tag, branch, or commit
-    - git: git@bitbucket.org:team/rules.git
-      path: prompts/review.prompt.md
-      alias: review                      # local alias (controls install directory name)
-    - git: ssh://git@bitbucket.example.com:7999/project/repo.git  # Bitbucket Datacenter (custom SSH port)
-      ref: v1.0
-    # Azure DevOps with sub-path and ref pin
-    - git: https://dev.azure.com/myorg/myproject/_git/myrepo
-      path: instructions/security
-      ref: v2.0
-```
-
-Fields: `git` (required), `path`, `ref`, `alias` (all optional). The `git` value is any HTTPS, HTTP or SSH clone URL.
-
-:::note[Azure DevOps + sub-path + ref]
-The shorthand form for the same ADO entry is:
-
-```yaml
-- dev.azure.com/myorg/myproject/_git/myrepo/instructions/security#v2.0
-```
-
-Use the **shorthand** or the **object form** for ADO sub-paths. The full `https://dev.azure.com/<org>/<project>/_git/<repo>/<sub-path>` URL form is not yet accepted by the parser. If you copy the URL straight from your ADO browser tab, switch to one of the two forms above. Spaces in project / repo names must be URL-encoded as `%20`.
-:::
-
-Explicit URL schemes are honored exactly -- see [Transport selection](#transport-selection-ssh-vs-https) for the full contract. Custom ports are preserved across every attempt (including any cross-protocol fallback enabled with `--allow-protocol-fallback`), so `ssh://host:7999/...` retried over HTTPS becomes `https://host:7999/...`.
-
-:::caution
-Use HTTP dependencies only on trusted private networks. Declare them with
-`git: http://...` and `allow_insecure: true` in `apm.yml`. Installing them
-still requires `apm install --allow-insecure`.
-
-HTTP has no transport authentication, so anyone who can intercept the
-connection can swap the package contents in transit. APM warns on every
-`http://` fetch, allows same-host transitive HTTP dependencies when you
-already passed `--allow-insecure` for a direct HTTP dependency on that host,
-and otherwise requires `--allow-insecure-host <hostname>` for each additional
-transitive host you want to allow.
-:::
-
-> **Nested groups (GitLab, Gitea, etc.):** APM treats path segments after the host as the repository namespace and name. Shorthand works for many GitLab URLs (for example `gitlab.com/group/subgroup/repo`). When the namespace is **deeply nested** or a segment could be read either as part of the repo path or as a **virtual path**, prefer the **object form** with an explicit `git:` URL and `path:` so install and API resolution stay unambiguous:
->
-> ```yaml
-> dependencies:
->   apm:
->     - git: https://gitlab.com/group/subgroup/repo.git
->       path: registry/pkg
-> ```
->
-> Virtual paths on simple two-segment repos still work in shorthand (`gitlab.com/owner/repo/file.prompt.md`). For **nested-group repos plus a virtual path in the same string**, the shorthand is ambiguous — use `git:` + `path:`:
->
-> ```yaml
-> # DON'T — ambiguous: APM can't tell where the repo path ends
-> # gitlab.com/group/subgroup/repo/file.prompt.md
-> #   → parsed as repo=group/subgroup, virtual=repo/file.prompt.md (wrong!)
->
-> # DO — explicit and unambiguous
-> - git: gitlab.com/group/subgroup/repo
->   path: file.prompt.md
-> ```
-
-#### Monorepo sibling references with `git: parent`
-
-When an APM package lives **inside a monorepo** and depends on a sibling package in the same repository at the same ref, declare the dependency with the literal sentinel `git: parent` and a `path:` to the sibling. APM expands `parent` at resolve time to the consumer's clone coordinates -- you do not have to repeat the host, repo, or ref.
-
-```yaml
-# In agents/pkg-a/apm.yml inside org/monorepo
-dependencies:
-  apm:
-    - git: parent
-      path: skills/shared
-```
-
-When `org/monorepo` is installed at ref `main`, APM resolves the sibling to the same `host`, `repo_url`, and `ref`, with `virtual_path: skills/shared`. The lockfile records the **expanded** coordinates -- there is no `parent` sentinel persisted as durable identity:
-
-```yaml
-# apm.lock.yaml (excerpt)
-host: github.com
-repo_url: org/monorepo
-virtual_path: skills/shared
-resolved_ref: main
-resolved_commit: <sha>
-is_virtual: true
-```
-
-The expansion result is byte-for-byte identical to writing the explicit form below, so swapping between the two never invalidates the lockfile or causes a re-download:
-
-```yaml
-# Equivalent explicit form (verbose, but works outside the monorepo too)
-- git: https://github.com/org/monorepo.git
-  path: skills/shared
-  ref: main
-```
-
-Use `git: parent` only when both the consumer and the sibling live in the same git monorepo. A `parent` reference at the **top level** of an `apm.yml` (not transitively pulled in by a parent install) has no monorepo to inherit from and is rejected at resolve time. The `path` is required, must not be empty, and is normalised to a single relative path -- absolute paths and `..` traversal are refused.
-
-### How Dependencies Are Stored (Canonical Format)
-
-APM normalizes every dependency entry on write — no matter how you specify a package, the stored form in `apm.yml` is always a clean, canonical string. This works like Docker's default registry convention:
-
-- **GitHub** is the default registry. The `github.com` host is stripped, leaving just `owner/repo`.
-- **Non-default hosts** (GitLab, Bitbucket, self-hosted) keep their FQDN: `gitlab.com/owner/repo`.
-
-| You type | Stored in apm.yml |
-|----------|-------------------|
-| `microsoft/apm-sample-package` | `microsoft/apm-sample-package` |
-| `https://github.com/microsoft/apm-sample-package.git` | `microsoft/apm-sample-package` |
-| `git@github.com:microsoft/apm-sample-package.git` | `microsoft/apm-sample-package` |
-| `github.com/microsoft/apm-sample-package` | `microsoft/apm-sample-package` |
-| `https://gitlab.com/acme/rules.git` | `gitlab.com/acme/rules` |
-| `gitlab.com/group/subgroup/repo` | `gitlab.com/group/subgroup/repo` |
-| `git@gitlab.com:group/subgroup/repo.git` | `gitlab.com/group/subgroup/repo` |
-| `git@bitbucket.org:team/standards.git` | `bitbucket.org/team/standards` |
-| `./packages/my-skills` | `./packages/my-skills` |
-| `/home/user/repos/my-pkg` | `/home/user/repos/my-pkg` |
-
-Virtual paths and refs are preserved:
-
-| You type | Stored in apm.yml |
-|----------|-------------------|
-| `github.com/org/repo/skills/review#v2` | `org/repo/skills/review#v2` |
-| `https://gitlab.com/acme/repo.git` + path `docs` + ref `main` | `gitlab.com/acme/repo/docs#main` |
-
-This normalization means:
-- **Duplicate detection works** across input forms — you can't accidentally install the same package twice using different URL formats.
-- **`apm uninstall` accepts any form** — shorthand, HTTPS URL, or SSH URL all resolve to the same canonical identity.
-- **`apm.yml` stays clean** and readable regardless of how packages were added.
-
-MCP dependencies resolve via the MCP server registry (e.g. `io.github.github/github-mcp-server`).
-
-MCP dependencies declared by transitive APM packages are collected automatically during `apm install`.
-
-### 2. Install Dependencies
-
-```bash
-# Install all dependencies
-apm install
-
-# Install only APM dependencies (faster)
-apm install --only=apm
-
-# Preview what will be installed
-apm install --dry-run
-```
-
-`apm install` also deploys the project's own `.apm/` content (instructions, prompts, agents, skills, hooks, commands) to target directories alongside dependency content. Local content takes priority over dependencies on collision. This works even with zero dependencies -- just `apm.yml` and a `.apm/` directory is enough. See the [CLI reference](../../reference/cli-commands/#apm-install---install-dependencies-and-deploy-local-content) for details and exceptions.
-
-:::caution[Migrating from auto-copilot fallback]
-Older APM versions silently deployed to `.github/` (Copilot) when no harness signal was present in the project. Starting with the target-resolution overhaul, that silent fallback is gone: an empty repo with no `targets:` in `apm.yml` and no harness marker (`.claude/`, `.cursor/`, `.github/copilot-instructions.md`, `.codex/`, `.gemini/`, `.opencode/`, `.windsurf/`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`) now exits 2 with a teaching message.
-
-Pick one of the explicit fixes:
-
-- `apm install --target copilot` -- one-shot deploy to `.github/`.
-- Add `targets: [copilot]` (or any other harness) to `apm.yml` -- persists across runs.
-- Create the harness marker (e.g. `touch .github/copilot-instructions.md`) -- auto-detect picks it up.
-
-Run `apm targets` first to see what APM detects (or doesn't) in the current directory.
-:::
-
-### 3. Verify Installation
-
-```bash
-# List installed packages
-apm deps list
-
-# Show only installed HTTP-backed packages
-apm deps list --insecure
-
-# Show dependency tree
-apm deps tree
-
-# Get package details
-apm view apm-sample-package
-```
-
-### 4. Use Dependencies in Compilation
-
-```bash
-# Compile with dependencies
-apm compile
-
-# Compilation generates distributed files across the project
-# Instructions with matching applyTo patterns are merged from all sources
-```
-
-## Updating dependencies
-
-`apm update` refreshes the APM packages declared in your `apm.yml` to their latest matching refs. It resolves the dependency graph against the network, prints a structured plan (added / updated / removed), and prompts before mutating anything.
-
-```bash
-# Interactive: resolve, show plan, prompt [y/N], then install
-apm update
-
-# Show the plan and exit -- no on-disk changes
-apm update --dry-run
-
-# CI-safe: skip the prompt
-apm update --yes
-```
-
-The plan output uses the standard bracket symbols (`[~]` updated, `[+]` added, `[-]` removed) and includes an inline legend in the footer. When nothing has changed, `apm update` prints `All dependencies already at their latest matching refs.` and exits cleanly.
-
-For lockfile-only enforcement in CI, pair `apm update` (in your branch / PR) with `apm install --frozen` (in CI):
-
-```bash
-# In CI -- exit 1 if apm.lock.yaml is missing or out of sync with apm.yml
-apm install --frozen
-```
-
-:::note[--frozen scope]
-`apm install --frozen` is a **structural presence check**: it verifies every direct dependency in `apm.yml` has a lock entry. It does NOT verify that on-disk content matches the locked SHA. Use `apm audit` for end-to-end integrity verification of deployed files.
-:::
-
-:::caution[Breaking change: `apm update` now refreshes dependencies]
-In earlier releases, `apm update` updated the APM CLI binary. That behaviour moved to `apm self-update`. Inside an `apm.yml` project, the bare `apm update` verb now refreshes project dependencies (matching `npm update`, `cargo update`, `uv lock --upgrade`).
-
-Outside a project, `apm update` still forwards to `apm self-update` with a deprecation banner for one release. CI scripts that called `apm update` to refresh the binary should migrate now:
-
-```bash
-sed -i 's/apm update/apm self-update/g' your_scripts
-```
-:::
-
-## Development Dependencies
-
-Some packages are only needed during authoring — test fixtures, linting rules, internal helpers. Install them as dev dependencies so they stay out of distributed bundles:
-
-```bash
-apm install --dev owner/test-helpers
-```
-
-Or declare them directly:
-
-```yaml
-devDependencies:
-  apm:
-    - source: owner/test-helpers
-```
-
-Dev dependencies install to `apm_modules/` like production deps but are excluded from `apm pack` plugin output. See [Pack & Distribute](../pack-distribute/) for details.
-
-**Important:** plain `apm install` (no flag) deploys both `dependencies` and `devDependencies` -- there is currently no `--omit=dev` flag. The dev/prod separation kicks in at `apm pack` (plugin format, the default). Maintainer-only primitives that you author yourself MUST live outside `.apm/` to be excluded from plugin bundles, because the local-content scanner operates on `.apm/` regardless of the devDep marker. See [Dev-only Primitives](../dev-only-primitives/) for the canonical pattern.
-
-## Local Path Dependencies
-
-Install packages from the local filesystem for fast iteration during development.
-
-```bash
-# Relative path
-apm install ./packages/my-shared-skills
-
-# Absolute path
-apm install /home/user/repos/my-ai-package
-```
-
-Or declare them in `apm.yml`:
-
-```yaml
-dependencies:
-  apm:
-    - ./packages/my-shared-skills          # relative to project root
-    - /home/user/repos/my-ai-package       # absolute path
-    - microsoft/apm-sample-package         # remote (can be mixed)
-```
-
-**How it works:**
-- Files are **copied** (not symlinked) to `apm_modules/_local/<package-name>/`
-- Local packages are validated the same as remote packages (must have `apm.yml` or `SKILL.md`)
-- `apm compile` works identically regardless of dependency source
-- Transitive dependencies are resolved recursively (local packages can depend on remote packages)
-- **Anchor rule:** a `local_path` declared **inside another local package** is resolved relative to **that package's own directory**, not the consumer's project root. This matches npm/pip/cargo workspace behaviour and is what makes mono-repos with sibling helper packages portable across consumers. Sibling layouts that resolve **outside** the consuming project root (e.g. `../sibling-pkg` from a local dep at the project edge) are supported -- the consuming developer authored the manifest chain and trusts the layout. The security boundary lives upstream: see the next bullet.
-
-  ```yaml
-  # apm.yml at /repo/apm.yml
-  dependencies:
-    apm:
-      - ./packages/specialized
-
-  # apm.yml at /repo/packages/specialized/apm.yml
-  dependencies:
-    apm:
-      - ../base   # resolves to /repo/packages/base, NOT /repo/base
-  ```
-
-- **Remote packages may not declare local dependencies.** A package fetched from `owner/repo` cannot depend on a `local_path` -- such an entry would reach into the consumer's filesystem in unpredictable ways. Both relative and absolute local paths are rejected at `ERROR` severity. Authors of remote packages must publish their dependencies (or vendor them via subdirectory packages).
-
-**Re-install behavior:** Local deps are always re-copied on `apm install` since there is no commit SHA to cache against. This ensures you always get the latest local changes.
-
-**Lockfile representation:** Local dependencies are tracked with `source: local` and `local_path` fields. No `resolved_commit` is stored.
-
-**Pack guard:** `apm pack` rejects packages with local path dependencies — replace them with remote references before distributing.
-
-**User-scope guard:** Local path dependencies are **not supported** with `--global` (`-g`). Relative paths resolve against `cwd`, which is meaningless at user scope where packages deploy to `~/.apm/`. Use remote references (`owner/repo`) for global installs.
-
-## Global (User-Scope) Installation
-
-By default, `apm install` targets the **current project** -- manifest, modules, and lockfile live in
-the working directory and deployed primitives go to `.github/`, `.claude/`, `.cursor/`, `.opencode/`.
-
-Pass `--global` (or `-g`) to install to your **home directory** instead, making packages available
-across every project on the machine:
-
-```bash
-apm install -g microsoft/apm-sample-package
-apm uninstall -g microsoft/apm-sample-package
-apm deps list -g       # user-scope packages only
-apm deps list --all    # project + user-scope packages
-```
-
-| Item | Project scope (default) | User scope (`-g`) |
-|------|------------------------|-------------------|
-| Manifest | `./apm.yml` | `~/.apm/apm.yml` |
-| Modules | `./apm_modules/` | `~/.apm/apm_modules/` |
-| Lockfile | `./apm.lock.yaml` | `~/.apm/apm.lock.yaml` |
-| Deployed primitives | `./.github/`, `./.claude/`, ... | `~/.copilot/`, `~/.claude/`, `~/.cursor/`, `~/.config/opencode/` |
-
-### Per-target support
-
-Coverage varies by target and primitive type:
-
-| Target | Status | User-level dir | Primitives | Not supported |
-|--------|--------|---------------|------------|---------------|
-| Claude Code | Supported | `~/.claude/` (or `$CLAUDE_CONFIG_DIR`) | Skills, agents, commands, hooks, instructions | -- |
-| Copilot CLI | Partial | `~/.copilot/` | Skills, agents, hooks | Prompts, instructions |
-| Cursor | Partial | `~/.cursor/` | Skills, agents, hooks | Rules |
-| OpenCode | Partial | `~/.config/opencode/` | Skills, agents, commands | Hooks |
-
-Target detection mirrors project scope: APM auto-detects by `~/.<target>/` directory presence,
-falling back to Copilot. Security scanning runs for global installs.
-
-For Claude Code, if `CLAUDE_CONFIG_DIR` is set (and points inside `$HOME`), `apm install -g --target claude` deploys there instead of `~/.claude/` so primitives land where Claude Code reads them.
-
-### When to use each scope
-
-| Use case | Scope |
-|----------|-------|
-| Team-shared instructions and prompts | Project (`apm install`) |
-| Personal commands, agents, or skills | User (`apm install -g`) |
-| CI/CD reproducible setup | Project |
-| Cross-project coding standards | User |
-
-:::note
-MCP servers at user scope (`--global`) are installed only to runtimes with global config paths (Copilot CLI, Codex CLI). Workspace-only runtimes (VS Code, Cursor, OpenCode) are skipped.
-:::
-
-:::caution
-Local path dependencies (`./path`, `../path`, `/abs/path`) are rejected at user scope. Relative paths resolve against `cwd`, which differs from the user-scope deploy root (`~/.apm/`). Use remote references for `apm install -g`.
-:::
-
-## MCP Dependency Formats
-
-:::tip[Quick start]
-For the CLI-first walkthrough (`apm install --mcp ...`), see the [MCP Servers guide](../mcp-servers/). This section covers the `apm.yml` manifest format in depth.
-:::
-
-MCP dependencies support three forms: string references, overlay objects, and self-defined servers.
-
-### String Reference (default)
-
-Registry-resolved by name. Simplest form:
-
-```yaml
-mcp:
-  - io.github.github/github-mcp-server
-```
-
-### Object with Overlays
-
-Customize a registry-resolved server with project-specific preferences:
-
-```yaml
-mcp:
-  - name: io.github.github/github-mcp-server
-    transport: stdio          # Prefer stdio over remote
-    env:                      # Pre-populate environment variables
-      GITHUB_TOKEN: "${MY_TOKEN}"
-    tools: ["repos", "issues"]  # Restrict exposed tools
-    headers:                  # Custom HTTP headers (remote transports)
-      X-Custom: "value"
-    package: npm              # Select package type (npm, pypi, oci)
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Server reference (required) |
-| `transport` | string | `stdio`, `sse`, `http`, or `streamable-http` (MCP transport names, not URL schemes -- remote variants connect over HTTPS) |
-| `env` | dict | Environment variable overrides |
-| `args` | list or dict | Runtime argument overrides |
-| `version` | string | Pin server version |
-| `package` | string | Select package type (`npm`, `pypi`, `oci`) |
-| `headers` | dict | HTTP headers for remote transports |
-| `tools` | list | Restrict exposed tool names |
-
-Overlay fields are merged on top of registry metadata — they augment, never replace, the registry-first model.
-
-### Self-Defined Servers (`registry: false`)
-
-For private or corporate MCP servers not published to any registry:
-
-```yaml
-mcp:
-  - name: internal-knowledge-base
-    registry: false
-    transport: http
-    url: "https://mcp.internal.example.com"
-    env:
-      API_TOKEN: "${API_TOKEN}"
-    headers:
-      Authorization: "Bearer ${API_TOKEN}"
-```
-
-Stdio example:
-
-```yaml
-mcp:
-  - name: local-db-tool
-    registry: false
-    transport: stdio
-    command: my-mcp-server
-    args:
-      - "--port"
-      - "8080"
-```
-
-**Required fields when `registry: false`:**
-- `transport` — always required
-- `url` — required for `http`, `sse`, `streamable-http` transports
-- `command` — required for `stdio` transport
-
-⚠️ **Transitive trust rule:** Self-defined servers from direct dependencies (depth=1 in the lockfile) are auto-trusted. Self-defined servers from transitive dependencies (depth > 1) are skipped with a warning by default. You can either re-declare them in your own `apm.yml`, or use `--trust-transitive-mcp` to trust all self-defined servers from upstream packages:
-
-```bash
-apm install --trust-transitive-mcp
-```
-
-### Environment variable placeholders
-
-`env`, `headers`, and `args` values may reference environment variables using either of two equivalent forms:
-
-| Syntax        | Meaning                                                     |
-| ------------- | ----------------------------------------------------------- |
-| `${VAR}`      | Reference to an environment variable named `VAR`            |
-| `${env:VAR}`  | Same as above (VS Code-style prefix, normalized internally) |
-
-How APM materializes a placeholder depends on the target harness:
-
-- **Copilot CLI** (`~/.copilot/mcp-config.json`): the placeholder is preserved as `${VAR}` in the generated config and resolved by Copilot CLI from the host environment at server-start. APM never reads the value, so secrets stay in your shell. Make sure the variable is exported before launching `gh copilot`.
-- **VS Code** (`.vscode/mcp.json`): the placeholder is rewritten to VS Code's `${env:VAR}` form and resolved by VS Code at server-start.
-- **Other harnesses** (Cursor, Windsurf, OpenCode, Claude Desktop, Gemini, Codex): the placeholder is resolved from the current process environment at install time and the literal value is written into the harness config.
-
-The legacy `<VAR>` syntax is still accepted for backward compatibility but emits a deprecation warning; migrate to `${VAR}` in `apm.yml`.
-
-### Validation
-
-Run `apm install --dry-run` to preview MCP dependency configuration without writing any files. Self-defined deps are validated for required fields and transport values; overlay deps are loaded as-is and unknown fields are ignored.
-
-## Transport selection (SSH vs HTTPS)
-
-APM picks SSH or HTTPS per dependency using a strict, predictable contract.
-
-:::caution[Breaking change in APM 0.8.13]
-APM versions before 0.8.13 silently retried failed clones across protocols.
-Starting in 0.8.13 the behavior is **strict by default**: explicit URL schemes are honored exactly,
-and shorthand uses HTTPS unless `git config url.<base>.insteadOf` rewrites it
-to SSH. To restore the legacy permissive chain temporarily (e.g. while
-migrating CI), set `APM_ALLOW_PROTOCOL_FALLBACK=1` or pass
-`--allow-protocol-fallback`.
-:::
-
-| Dependency form | What APM tries |
-|-----------------|----------------|
-| `ssh://...` or `git@host:...` | SSH only |
-| `https://...` or `http://...` | HTTP(S) only |
-| Shorthand (`owner/repo`, `host/owner/repo`) with `git config url.<base>.insteadOf` rewriting to SSH | SSH only |
-| Shorthand without a matching `insteadOf` rewrite | HTTPS only |
-
-A failed clone fails loudly, naming the URL and the protocol attempted. APM
-no longer downgrades `ssh://` to HTTPS or vice-versa.
-
-### Honoring `git config insteadOf`
-
-If your machine rewrites HTTPS to SSH for a host, APM matches `git clone`'s
-behavior on that machine. Example:
-
-```bash
-git config --global url."git@github.com:".insteadOf "https://github.com/"
-apm install owner/repo        # APM clones over SSH
-```
-
-No CLI flag is needed. `insteadOf` is consulted only for shorthand
-dependencies; explicit URLs in `apm.yml` are not rewritten.
-
-### Forcing the initial protocol for shorthand
-
-```bash
-apm install owner/repo --ssh        # force SSH for shorthand
-apm install owner/repo --https      # force HTTPS for shorthand
-export APM_GIT_PROTOCOL=ssh         # session default
-```
-
-`--ssh` and `--https` are mutually exclusive and apply only to shorthand
-dependencies. URLs with an explicit scheme ignore them.
-
-### Restoring the legacy permissive chain
-
-```bash
-apm install --allow-protocol-fallback
-export APM_ALLOW_PROTOCOL_FALLBACK=1   # CI / migration window
-```
-
-When fallback runs, each cross-protocol retry emits a `[!]` warning naming
-both protocols. Use this to unblock a pipeline while you fix the root
-cause -- not as a long-term setting.
-
-:::caution[Cross-protocol fallback reuses the same port]
-Fallback reuses the dependency's custom port for both schemes. On
-servers that use different ports per protocol (e.g. Bitbucket
-Datacenter: SSH 7999, HTTPS 7990), the off-protocol URL will be
-wrong. APM emits a `[!]` warning before the first clone attempt when
-a custom port is set and fallback is enabled. To avoid cross-protocol
-retries entirely, leave `--allow-protocol-fallback` disabled (strict
-mode) and pin the dependency with an explicit `ssh://...` or
-`https://...` URL in `apm.yml`. If fallback is enabled, APM may still
-try the other protocol even when the URL uses an explicit scheme --
-pinning only hard-stops cross-protocol retries in strict mode.
-:::
-
-For SSH key selection (ssh-agent, `~/.ssh/config`) and HTTPS token
-resolution, see
-[Authentication](../../getting-started/authentication/#choosing-transport-ssh-vs-https).
-For the CLI flag and env var reference, see
-[`apm install`](../../reference/cli-commands/#apm-install---install-dependencies-and-deploy-local-content).
-
-## GitHub Authentication Setup
-
-For GitHub and GitHub Enterprise repositories, set up a personal access token:
-
-### Option 1: Fine-grained Token (Recommended)
-
-Create a fine-grained personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new):
-
-- **Repository access**: Select specific repositories or "All repositories"
-- **Permissions**: 
-  - Contents: Read (to access repository files)
-  - Metadata: Read (to access basic repository information)
-
-```bash
-export GITHUB_CLI_PAT=your_fine_grained_token
-```
-
-### Option 2: Classic Token (Fallback)
-
-Create a classic personal access token with `repo` scope:
-
-```bash
-export GITHUB_TOKEN=your_classic_token
-```
-
-### Verify Authentication
-
-```bash
-# Test that your token works
-apm install --dry-run
-```
-
-If authentication fails, you'll see an error with guidance on token setup.
-
-### Other Git Hosts (GitLab, Bitbucket, etc.)
-
-For non-GitHub repositories, APM delegates authentication to git — it never sends GitHub tokens to non-GitHub hosts:
-
-- **Public repos**: Work without authentication via HTTPS
-- **Private repos via SSH**: Configure SSH keys for your host. Use an `ssh://` or `git@host:` URL, or set up `git config url.<base>.insteadOf` to rewrite shorthand to SSH (see [Transport selection](#transport-selection-ssh-vs-https))
-- **Private repos via HTTPS**: Configure a [git credential helper](https://git-scm.com/docs/gitcredentials) — APM allows credential helpers for non-GitHub hosts
-
-```bash
-# Ensure SSH keys are configured for your host
-ssh -T git@gitlab.com
-ssh -T git@bitbucket.org
-```
-
-## Real-World Example: Corporate Website Project
-
-This example shows how APM dependencies enable powerful layered functionality by combining multiple specialized packages. The company website project uses [microsoft/apm-sample-package](https://github.com/microsoft/apm-sample-package) as a full APM package and individual prompts from [github/awesome-copilot](https://github.com/github/awesome-copilot) to supercharge development workflows:
-
-```yaml
-# company-website/apm.yml
-name: company-website
-version: 1.0.0
-description: Corporate website with design standards and code review
-dependencies:
-  apm:
-    - microsoft/apm-sample-package#v1.0.0
-    - github/awesome-copilot/skills/review-and-refactor
-  mcp:
-    - io.github.github/github-mcp-server
-    - name: internal-knowledge-base
-      registry: false
-      transport: http
-      url: "${KNOWLEDGE_BASE_URL}"
-      env:
-        KB_TOKEN: "${KB_TOKEN}"
-
-scripts:
-  # Design workflows  
-  design-review: "codex --skip-git-repo-check design-review.prompt.md"
-  accessibility: "codex --skip-git-repo-check accessibility-audit.prompt.md"
-```
-
-### Package Contributions
-
-The combined packages provide comprehensive coverage:
-
-**[apm-sample-package](https://github.com/microsoft/apm-sample-package) contributes:**
-- **Agent Workflows**: `.apm/prompts/design-review.prompt.md`, `.apm/prompts/accessibility-audit.prompt.md`
-- **Instructions**: `.apm/instructions/design-standards.instructions.md` - Design guidelines
-- **Agents**: `.apm/agents/design-reviewer.agent.md` - Design review persona
-- **Skills**: `.apm/skills/style-checker/SKILL.md` - Style checking capability
-
-**[github/awesome-copilot](https://github.com/github/awesome-copilot) virtual packages contribute:**
-- **Prompts**: Individual prompt files installed via virtual package references
-
-### Compounding Benefits
-
-When both packages are installed, your project gains:
-- **Accessibility audit** capabilities for web components
-- **Design system enforcement** with automated style checking
-- **Code review** workflows from community prompts
-- **Rich context** about design standards
-
-## Dependency Resolution
-
-### Installation Process
-
-1. **Parse Configuration**: APM reads the `dependencies.apm` section from `apm.yml`
-2. **Download Repositories**: Clone or update each GitHub repository to `apm_modules/`
-3. **Validate Packages**: Ensure each repository has valid APM package structure
-4. **Build Dependency Graph**: Resolve transitive dependencies recursively
-5. **Check Conflicts**: Identify any circular dependencies or conflicts
-
-#### Resilient Downloads
-
-APM automatically retries failed HTTP requests with exponential backoff and jitter. Rate-limited responses (HTTP 429/503) are handled transparently, respecting `Retry-After` headers when provided. This ensures reliable installs even under heavy API usage or transient network issues.
-
-#### Parallel Downloads
-
-APM downloads packages in parallel using a thread pool, significantly reducing wall-clock time for large dependency trees. The concurrency level defaults to 4 and is configurable via `--parallel-downloads` (set to 0 to disable). For sibling subdirectory packages from the same monorepo and ref (e.g. two skills under `skills/` in `github/awesome-copilot`), APM clones the repo bare exactly once into a shared cache and materializes each consumer's working tree from that cache via `git clone --local --shared --no-checkout`. This eliminates redundant network fetches and prevents the parallel races that affected earlier sparse-checkout based fetches. When a transitive dependency pins a commit SHA that differs from the ref used for the initial clone, APM fetches that specific commit into the existing bare clone on demand rather than re-cloning.
-
-### File Processing and Content Merging
-
-APM uses instruction-level merging rather than file-level precedence. When local and dependency files contribute instructions with overlapping `applyTo` patterns:
-
-```
-my-project/
-├── .apm/
-│   └── instructions/
-│       └── security.instructions.md      # Local instructions (applyTo: "**/*.py")
-├── apm_modules/
-│   └── compliance-rules/
-│       └── .apm/
-│           └── instructions/
-│               └── compliance.instructions.md  # Dependency instructions (applyTo: "**/*.py")
-└── apm.yml
-```
-
-During compilation, APM merges instruction content by `applyTo` patterns:
-1. **Pattern-Based Grouping**: Instructions are grouped by their `applyTo` patterns, not by filename
-2. **Content Merging**: All instructions matching the same pattern are concatenated in the final AGENTS.md
-3. **Source Attribution**: Each instruction includes source file attribution when compiled
-
-This allows multiple packages to contribute complementary instructions for the same file types, enabling rich layered functionality.
-
-### Dependency Tree Structure
-
-Based on the actual structure of our real-world examples:
-
-```
-my-project/
-├── apm_modules/                     # Dependency installation directory
-│   ├── microsoft/
-│   │   └── apm-sample-package/      # From microsoft/apm-sample-package
-│   │       ├── .apm/
-│   │       │   ├── instructions/
-│   │       │   │   └── design-standards.instructions.md
-│   │       │   ├── prompts/
-│   │       │   │   ├── design-review.prompt.md
-│   │       │   │   └── accessibility-audit.prompt.md
-│   │       │   ├── agents/
-│   │       │   │   └── design-reviewer.agent.md
-│   │       │   └── skills/
-│   │       │       └── style-checker/SKILL.md
-│   │       └── apm.yml
-│   └── github/
-│       └── awesome-copilot/              # Virtual subdirectory from github/awesome-copilot
-│           └── skills/
-│               └── review-and-refactor/
-│                   ├── SKILL.md
-│                   └── apm.yml
-├── .apm/                            # Local context (highest priority)
-├── apm.yml                          # Project configuration
-└── .gitignore                       # Manually add apm_modules/ to ignore
-```
-
-**Note**: Full APM packages store primitives under `.apm/` subdirectories. Virtual file packages extract individual files from monorepos like `github/awesome-copilot`.
-
-## Advanced Scenarios
-
-### Branch and Tag References
-
-Specify specific branches, tags, or commits for dependency versions:
-
-```yaml
-dependencies:
-  apm:
-    - github/awesome-copilot/skills/review-and-refactor#v2.1.0    # Specific tag
-    - microsoft/apm-sample-package#main     # Specific branch  
-    - company/internal-standards#abc123        # Specific commit
-```
-
-### Updating Dependencies
-
-```bash
-# Update all dependencies to latest refs
-apm deps update
-
-# Update specific dependency (use the owner/repo form from apm.yml)
-apm deps update owner/apm-sample-package
-
-# Update with verbose output
-apm deps update --verbose
-
-# Update user-scope dependencies
-apm deps update -g
-
-# Install with updates (equivalent to update)
-apm install --update
-```
-
-## Reproducible Builds with apm.lock.yaml
-
-APM generates a lockfile (`apm.lock.yaml`) after each successful install to ensure reproducible builds across machines and CI environments.
-
-### What is apm.lock.yaml?
-
-The `apm.lock.yaml` file captures the exact state of your dependency tree, including which files APM deployed:
-
-```yaml
-lockfile_version: "1.0"
-generated_at: "2026-01-22T10:30:00Z"
-apm_version: "0.8.0"
-dependencies:
-  microsoft/apm-sample-package:
-    repo_url: "https://github.com/microsoft/apm-sample-package"
-    resolved_commit: "abc123def456"
-    resolved_ref: "main"
-    version: "1.0.0"
-    depth: 1
-    deployed_files:
-      - .github/prompts/design-review.prompt.md
-      - .github/prompts/accessibility-audit.prompt.md
-      - .github/agents/design-reviewer.agent.md
-  contoso/validation-patterns:
-    repo_url: "https://github.com/contoso/validation-patterns"
-    resolved_commit: "789xyz012"
-    resolved_ref: "main"
-    version: "1.2.0"
-    depth: 2
-    resolved_by: "microsoft/apm-sample-package"
-mcp_servers:
-  - acme-kb
-  - github
-```
-
-The `deployed_files` field tracks exactly which files APM placed in your project. This enables safe cleanup on `apm uninstall` and `apm prune` — only tracked files are removed.
-
-The `mcp_servers` field records the MCP dependency references (e.g. `io.github.github/github-mcp-server`) for servers currently managed by APM. It is used to detect and clean up stale servers when dependencies change.
-
-### How It Works
-
-1. **First install**: APM resolves dependencies, downloads packages, and writes `apm.lock.yaml`
-2. **Subsequent installs**: APM reads `apm.lock.yaml` and uses locked commits for exact reproducibility. If the local checkout already matches the locked commit SHA, the download is skipped entirely.
-3. **Updating**: Use `--update` to re-resolve dependencies and generate a fresh lockfile. This re-resolves all dependencies, including transitive ones, so stale locked SHAs are never reused.
-
-### Version Control
-
-**Commit `apm.lock.yaml`** to version control:
-
-```bash
-git add apm.lock.yaml
-git commit -m "Lock dependencies"
-```
-
-This ensures all team members and CI pipelines get identical dependencies.
-
-### Forcing Re-resolution
-
-When you want the latest versions (ignoring the lockfile):
-
-```bash
-# Re-resolve all dependencies and update lockfile
-apm install --update
-```
-
-### Transitive Dependencies
-
-APM fully resolves transitive dependencies. If package A depends on B, and B depends on C:
-
-```
-apm install contoso/package-a
-```
-
-Result:
-- Downloads A, B, and C
-- Records all three in `apm.lock.yaml` with depth information
-- `depth: 1` = direct dependency
-- `depth: 2+` = transitive dependency
-
-Uninstalling a package also removes its orphaned transitive dependencies (npm-style pruning).
-You can use any input form — APM resolves it to the canonical identity stored in `apm.yml`:
-
-```bash
-apm uninstall acme/package-a
-apm uninstall https://github.com/acme/package-a.git   # same effect
-apm uninstall git@github.com:acme/package-a.git        # same effect
-# Also removes B and C if no other package depends on them
-```
-
-### Cleaning Dependencies
-
-```bash
-# Remove all APM dependencies
-apm deps clean
-
-# This removes the entire apm_modules/ directory
-# Use with caution - requires reinstallation
-```
-
-## Best Practices
-
-### Package Structure
-
-Create well-structured APM packages for maximum reusability:
-
-```
-your-package/
-├── .apm/
-│   ├── instructions/        # Context for AI behavior
-│   ├── contexts/           # Domain knowledge and facts  
-│   ├── chatmodes/          # Interactive chat configurations
-│   └── prompts/            # Agent workflows
-├── apm.yml                 # Package metadata
-├── README.md               # Package documentation
-└── examples/               # Usage examples (optional)
-```
-
-### Package Naming
-
-- Use descriptive, specific names: `compliance-rules`, `design-guidelines`
-- Follow GitHub repository naming conventions
-- Consider organization/team prefixes: `company/platform-standards`
-
-### Version Management
-
-- Use semantic versioning for package releases
-- Tag releases for stable dependency references
-- Document breaking changes clearly
-
-### Documentation
-
-- Include clear README.md with usage examples
-- Document all prompts and their parameters
-- Provide integration examples
-
-## Troubleshooting
-
-### Common Issues
-
-#### "Authentication failed" 
-**Problem**: GitHub token is missing or invalid
-**Solution**: 
-```bash
-# Verify token is set
-echo $GITHUB_CLI_PAT
-
-# Test token access
-curl -H "Authorization: token $GITHUB_CLI_PAT" https://api.github.com/user
-```
-
-#### "Package validation failed"
-**Problem**: Repository doesn't have valid APM package structure
-**Solution**: 
-- Ensure target repository has `.apm/` directory
-- Check that `apm.yml` exists and is valid
-- Verify repository is accessible with your token
-
-#### "Circular dependency detected"
-**Problem**: Packages depend on each other in a loop
-**Solution**:
-- Review your dependency chain
-- Remove circular references
-- Consider merging closely related packages
-
-#### "File conflicts during installation"
-**Problem**: Local files collide with package files during `apm install`
-**Resolution**: APM skips files that exist locally and aren't managed by APM. The diagnostic summary at the end of install shows how many files were skipped. Use `--verbose` to see which files, or `--force` to overwrite.
-
-#### "File conflicts during compilation"
-**Problem**: Multiple packages or local files have same names
-**Resolution**: Local files automatically override dependency files with same names
-
-### Getting Help
-
-```bash
-# Show detailed package information
-apm view package-name
-
-# Show full dependency tree
-apm deps tree
-
-# Preview installation without changes
-apm install --dry-run
-
-# See detailed diagnostics (skipped files, errors)
-apm install --verbose
-
-# Enable verbose logging for compilation
-apm compile --verbose
-```
-
-## Integration with Workflows
-
-### Continuous Integration
-
-Add dependency installation to your CI/CD pipelines:
-
-```yaml
-# .github/workflows/apm.yml
-- name: Install APM dependencies
-  run: |
-    apm install --only=apm
-    apm compile
-```
-
-### Team Development
-
-1. **Share dependencies** through your `apm.yml` file in version control
-2. **Pin specific versions** for consistency across team members
-3. **Document dependency choices** in your project README
-4. **Update together** to avoid version conflicts
-
-### Local Development
-
-```bash
-# Quick setup for new team members
-git clone your-project
-cd your-project
-apm install
-apm compile
-
-# Now all team contexts and workflows are available
-```
-
-## Next Steps
-
-- **[CLI Reference](../../reference/cli-commands/)** - Complete command documentation
-- **[Getting Started](../../getting-started/installation/)** - Basic APM usage
-- **[Context Guide](../../introduction/how-it-works/)** - Understanding the AI-Native Development framework
-- **[Creating Packages](../../introduction/key-concepts/)** - Build your own APM packages
-
-Ready to create your own APM packages? See the [Context Guide](../../introduction/key-concepts/) for detailed instructions on building reusable context collections and agent workflows.
diff --git a/docs/src/content/docs/guides/dev-only-primitives.md b/docs/src/content/docs/guides/dev-only-primitives.md
deleted file mode 100644
index 93f427ec9..000000000
--- a/docs/src/content/docs/guides/dev-only-primitives.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-title: "Dev-only Primitives"
-description: "Author maintainer-only skills, agents, and instructions that stay out of shipped artifacts."
-sidebar:
-  order: 7
----
-
-Some primitives are useful while you author an APM package but should never reach consumers: a release-checklist skill for maintainers, a debugging agent that only makes sense in your repo, instructions that reference internal infrastructure. APM has one canonical pattern for this. Once you know it, three otherwise surprising behaviors stop being surprising.
-
-## The pattern
-
-```
-your-package/
-+-- apm.yml
-+-- .apm/                          # shipped source root
-|   +-- skills/
-|   |   +-- public-skill/SKILL.md
-|   +-- agents/
-+-- dev/                           # maintainer-only, outside .apm/
-    +-- skills/
-        +-- release-checklist/SKILL.md
-```
-
-```yaml
-# apm.yml
-name: your-package
-version: 1.0.0
-
-dependencies:
-  apm:
-    - microsoft/apm-sample-package#v1.0.0
-
-devDependencies:
-  apm:
-    - path: ./dev/skills/release-checklist
-```
-
-`apm install --dev` deploys the release-checklist skill to `.github/skills/release-checklist/` with `is_dev: true` in the lockfile. `apm pack` (plugin format, the default) excludes it. Consumers running `apm install your-org/your-package` never see it.
-
-## Why outside `.apm/`?
-
-APM treats `.apm/` as the publishable source root. The local-content scanner that builds plugin bundles operates on `.apm/` only, and it does NOT consult the devDependency marker when deciding what to include. If a dev-only skill sits under `.apm/skills/`, it ships -- even if the only reference to it in `apm.yml` is under `devDependencies`.
-
-Authoring dev-only primitives anywhere outside `.apm/` (`dev/`, `internal/`, `.maintainer/` -- your choice) keeps them invisible to the scanner. Referencing them via local-path `devDependencies` keeps them installable on `apm install --dev` and tracked in the lockfile.
-
-## Three behaviors this pattern works around
-
-1. **The scanner does not honor the devDep marker.** It scans `.apm/` wholesale at pack time. The cure is to live outside `.apm/`.
-
-2. **`includes:` is allow-list only.** There is no `exclude:` form. You cannot write `includes: [.apm/]` and expect a sibling `.apm/dev/` subtree to be stripped -- `includes` does not gate `.apm/` against itself, and the manifest schema has no exclude verb. See [Manifest section 3.9](../../reference/manifest-schema/#39-includes).
-
-3. **Plain `apm install` deploys devDeps.** `apm install` (no flag) resolves and deploys both `dependencies` and `devDependencies`. `apm install --dev <pkg>` adds a new dev dependency to the manifest -- it is not a filter that excludes prod deps. There is currently no `--omit=dev` flag; the dev/prod separation kicks in at `apm pack` time, not at install time.
-
-## When to use this pattern
-
-- Maintainer-only release tooling (changelog drafters, version-bump helpers).
-- Internal debugging agents you do not want consumers to load.
-- Test-fixture skills referenced by your own CI but not by consumers.
-- Anything that would embarrass you if it shipped.
-
-## When NOT to use this pattern
-
-- Shared dev tooling that another package consumes -- that is a regular remote `devDependencies` entry (`owner/test-helpers`), not a local path.
-- A primitive a consumer might legitimately want -- keep it under `.apm/`.
-
-## Verifying
-
-```bash
-apm install --dev                          # deploys with is_dev: true
-grep is_dev apm.lock.yaml                  # confirm marker
-apm pack --dry-run                         # confirm absence from bundle (plugin format, default)
-ls build/your-package-1.0.0/skills/        # release-checklist must NOT appear
-```
-
-If the dev-only skill appears in the dry-run output, it is sitting under `.apm/`. Move it to `dev/` (or any non-`.apm/` path) and re-reference it via `path:` in `devDependencies`.
-
-## See also
-
-- [Anatomy of an APM Package](../../introduction/anatomy-of-an-apm-package/) -- why `.apm/` is the publishable source root.
-- [Manifest Schema 3.9 -- `includes`](../../reference/manifest-schema/#39-includes) -- allow-list semantics, no exclude form.
-- [Manifest Schema 5 -- `devDependencies`](../../reference/manifest-schema/#5-devdependencies) -- the field reference.
-- [Pack & Distribute -- Plugin format](./pack-distribute/#plugin-format-vs-apm-format) -- what the scanner emits.
diff --git a/docs/src/content/docs/guides/drift-detection.md b/docs/src/content/docs/guides/drift-detection.md
deleted file mode 100644
index e7b9961a3..000000000
--- a/docs/src/content/docs/guides/drift-detection.md
+++ /dev/null
@@ -1,152 +0,0 @@
----
-title: Drift Detection
-sidebar:
-  order: 7
----
-
-`apm audit` runs **drift detection by default** so a stale working tree
-cannot ship to production unnoticed. This page explains what drift means,
-how the check works, and the escape hatch when you need to disable it.
-
-## Try it now
-
-```bash
-cd <your-apm-project>
-apm audit
-```
-
-If you have any `.apm/` sources or installed dependencies, the audit
-will replay your install into a scratch tmpdir and report any drift.
-No writes to your working tree, no network, no MCP calls.
-
-Common first-run results:
-
-- **Clean tree, no drift** -- exit 0, no output beyond the standard
-  audit summary.
-- **Forgot to re-run `apm install`** -- drift findings under kind
-  `unintegrated` for every `.apm/` source whose deployed counterpart
-  is missing.
-- **First run on a pre-marker cache** -- a one-line warning asking
-  you to run `apm install` once so cache pin markers are written.
-
-## What is integration drift?
-
-Integration drift is any divergence between what `apm install` would
-deploy from your locked dependencies and what is actually on disk.
-Three kinds matter:
-
-| Kind | Meaning | Typical cause |
-|---|---|---|
-| `unintegrated` | A `.apm/` source file is committed but its deployed counterpart is missing | Forgot to re-run `apm install` after adding/editing local primitives |
-| `modified` | A deployed file's content differs from what install would produce | Hand-edit to a regenerated file under `.github/`, `.claude/`, `.cursor/`, etc. |
-| `orphaned` | A deployed file exists with no current source backing it | Removed a dependency or local primitive without re-running install |
-
-All three previously required ad-hoc `git status --porcelain` scripts in
-CI to detect. With drift detection, `apm audit` catches every case in
-one read-only command -- nothing in your project, lockfile, or
-`apm_modules/` is mutated.
-
-## How it works
-
-```mermaid
-flowchart LR
-    A[apm audit] --> B[Read apm.lock.yaml<br/>+ cache contents]
-    B --> C[Replay install<br/>into scratch tmpdir]
-    C --> D[Diff scratch tree<br/>vs project]
-    D --> E[Render findings<br/>text / JSON / SARIF]
-```
-
-The replay is **cache-only** -- no network, no git fetch, no MCP
-registry call. It will fail fast with `CacheMissError` if the lockfile
-references content not present in the persistent cache (run
-`apm install` once first).
-
-False-positive guards normalize:
-
-- Build-ID lines (e.g. APM-generated `<!-- Build ID: ... -->` markers).
-- CRLF -> LF line endings (Windows checkouts of LF-canonical sources).
-- UTF-8 BOM byte-order marks.
-
-## Default behaviour and exit codes
-
-| Mode | Drift findings | Exit code |
-|---|---|---|
-| `apm audit` | Reported in stdout | 0 (advisory only) |
-| `apm audit --ci` | Reported and counted as failure | 1 |
-| `apm audit --no-drift` | Skipped entirely | governed only by other checks |
-
-In `--ci` mode drift findings are pooled with the seven baseline lockfile
-checks (`lockfile-exists`, `ref-consistency`, etc.) plus integration
-drift detection -- a single non-zero exit covers all of them.
-
-## When to use `--no-drift`
-
-The escape hatch exists for two legitimate cases:
-
-1. **Tight inner loops** where you intentionally have local edits and
-   just want a content-only safety scan (`apm audit --no-drift -v`).
-2. **Performance budgets** in matrix CI where you've already covered
-   drift in a single non-matrix job upstream.
-
-Drift detection is also auto-skipped when `--strip` or `--file` is used;
-both target a single payload and have nothing to diff against. Combining
-`--no-drift` with `--strip` or `--file` is rejected with a usage error
-(rather than silently picking one).
-
-## Output formats
-
-**Text (TTY default)** -- color-coded, one finding per line, grouped by kind.
-
-**JSON** -- the audit report gains a top-level `drift` key:
-
-```json
-{
-  "report_format_version": "1.0",
-  "checks": [...],
-  "drift": [
-    {
-      "path": ".github/instructions/foo.md",
-      "kind": "modified",
-      "package": "<local>",
-      "inline_diff": "..."
-    }
-  ]
-}
-```
-
-**SARIF** -- findings are appended to `runs[0].results` with rule IDs
-`apm/drift/modified`, `apm/drift/unintegrated`, `apm/drift/orphaned`,
-ready to surface in GitHub code-scanning.
-
-## CI integration
-
-The recommended CI gate is now a single line:
-
-```yaml
-- run: apm audit --ci
-```
-
-### Before vs after: the legacy bash workaround
-
-Previously CI pipelines had to grep `git status` to catch un-installed
-or hand-edited deployed files. That workaround is no longer needed:
-
-```yaml
-# Legacy -- no longer needed once apm-action ships with drift support
-- run: |
-    if [ -n "$(git status --porcelain -- .github/ .claude/ .cursor/)" ]; then
-      exit 1
-    fi
-```
-
-`apm audit --ci` subsumes this entirely AND catches three additional
-classes of drift the bash workaround missed (`unintegrated` of source
-files never integrated, `orphaned` files left behind by removed
-dependencies, and `modified` files normalized for build-id /
-line-ending / BOM noise).
-
-For org-policy enforcement, combine with `--policy org` -- drift
-detection composes orthogonally with the 17 audit-only policy checks.
-
-See also: [CI Policy Enforcement](../ci-policy-setup/),
-[Governance Guide](../../enterprise/governance-guide/).
diff --git a/docs/src/content/docs/guides/marketplace-authoring.md b/docs/src/content/docs/guides/marketplace-authoring.md
deleted file mode 100644
index 9d0a10167..000000000
--- a/docs/src/content/docs/guides/marketplace-authoring.md
+++ /dev/null
@@ -1,486 +0,0 @@
----
-title: "Authoring a marketplace"
-description: Author an APM marketplace from a single apm.yml and build it with apm pack.
-sidebar:
-  order: 6
----
-
-This guide is for **marketplace maintainers** -- people who curate a set of plugin packages for their team or organisation. If you are a consumer installing plugins from an existing marketplace, see the [Marketplaces guide](../marketplaces/) instead.
-
-APM uses a single source-of-truth model:
-
-- `apm.yml` -- your project manifest, hand-edited. A top-level `marketplace:` block declares the marketplace.
-- `.claude-plugin/marketplace.json` -- compiled artefact, byte-for-byte compliant with [Anthropic's marketplace.json specification](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces). Consumed by Claude Code, Copilot CLI, and APM itself.
-
-Both files are committed. `apm.yml` is edited; `marketplace.json` is regenerated by `apm pack`.
-
-## Quickstart
-
-```bash
-# 1. Add a marketplace block to your existing apm.yml
-apm marketplace init
-
-# 2. Edit the block in apm.yml -- describe each plugin under marketplace.plugins
-$EDITOR apm.yml
-
-# 3. Build the marketplace
-apm pack
-
-# 4. Commit both files
-git add apm.yml .claude-plugin/marketplace.json
-git commit -m "Initial marketplace"
-git push
-```
-
-`apm marketplace init` appends a richly commented `marketplace:` block to your existing `apm.yml` and creates an empty `.claude-plugin/` directory. It does NOT create a standalone `marketplace.yml`. If your project has no `apm.yml` yet, run `apm init` first.
-
-`apm pack` is the universal build verb. When `apm.yml` contains a `marketplace:` block, it writes `.claude-plugin/marketplace.json`. When `apm.yml` also contains `dependencies:`, it writes a bundle to `./build/<name>/` in the same run. The manifest drives what gets produced -- there is no separate "marketplace build" command.
-
-Consumers register your repository with `apm marketplace add <owner>/<repo>` and install packages from it.
-
-## Real-world example: microsoft/azure-skills
-
-The `microsoft/azure-skills` repository ships an `apm.yml` plus a hand-authored `.claude-plugin/marketplace.json`. Running `apm pack` against its `apm.yml` produces a byte-for-byte identical `marketplace.json` -- proof that the `marketplace:` block fully expresses the Anthropic shape.
-
-```yaml
-# apm.yml
-name: azure-skills
-version: 1.0.0
-description: Microsoft Azure MCP and Skills integration
-
-marketplace:
-  owner:
-    name: Microsoft
-    url: https://www.microsoft.com
-  plugins:
-    - name: azure
-      description: Microsoft Azure MCP integration for cloud resource management
-      source: ./.github/plugins/azure-skills
-      homepage: https://github.com/microsoft/azure-skills
-```
-
-Note three things:
-
-- No `name`, `description`, or `version` inside `marketplace:` -- they are inherited from the `apm.yml` top level.
-- `source: ./.github/plugins/azure-skills` is a local-path entry: the plugin lives in this same repo.
-- No `tags:` -- empty/absent tags are omitted from `marketplace.json` to match Anthropic's canonical shape.
-
-Build it:
-
-```
-$ apm pack
-[+] Built marketplace.json (1 plugins) -> .claude-plugin/marketplace.json
-```
-
-## The `marketplace:` schema
-
-Full example with both remote and local plugins:
-
-```yaml
-name: my-project
-version: 1.2.0
-description: Curated plugins for the acme-org engineering team
-
-marketplace:
-  # Optional overrides. Omit to inherit from apm.yml top level.
-  # name: my-marketplace
-  # description: ...
-  # version: 1.2.0
-
-  owner:
-    name: acme-org
-    url: https://github.com/acme-org
-    email: maintainers@acme-org.example
-
-  # APM-only: stripped from marketplace.json at compile time.
-  build:
-    tagPattern: "v{version}"
-
-  # Pass-through: copied verbatim into marketplace.json.
-  metadata:
-    homepage: https://example.com/plugins
-    pluginRoot: ./plugins
-
-  plugins:
-    - name: example-plugin
-      description: Example plugin consumers will see
-      source: acme-org/example-plugin
-      version: "^1.0.0"
-
-    - name: monorepo-tool
-      description: Plugin that lives in a subdirectory
-      source: acme-org/monorepo
-      subdir: tools/monorepo-tool
-      version: "~2.3.0"
-      tag_pattern: "monorepo-tool-v{version}"
-
-    - name: pinned-plugin
-      description: Pinned to an explicit ref
-      source: acme-org/pinned-plugin
-      ref: 3f2a9b1c
-
-    - name: local-tool
-      description: Plugin shipped alongside this repo
-      source: ./plugins/local-tool
-      version: 0.1.0
-```
-
-### Fields inside `marketplace:`
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | no | Override the `apm.yml` top-level `name`. Inherited when omitted. |
-| `description` | no | Override the top-level `description`. Inherited when omitted. |
-| `version` | no | Override the top-level `version`. Inherited when omitted. |
-| `owner` | yes | Mapping with `name` (required), optional `url`, `email`. |
-| `build` | no | APM-only build options. See below. |
-| `metadata` | no | Opaque pass-through copied into `marketplace.json`. |
-| `plugins` | no | List of plugin entries. |
-
-When `name`/`description`/`version` are inherited (not overridden), they are also omitted from the generated `marketplace.json` top level so the artefact stays stable across unrelated bumps to `apm.yml`.
-
-### The `build` block (APM-only)
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `tagPattern` | `v{version}` | Marketplace-wide default for resolving `{version}` to a git tag. Accepts `{version}` and `{name}` placeholders. |
-
-Stripped from `marketplace.json` at compile time.
-
-### Plugin entries
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Plugin name consumers will install. Unique within the marketplace. |
-| `source` | yes | Either `<owner>/<repo>` (remote) or `./path/to/dir` (local-path entry in this repo). |
-| `description` | no | Pass-through to `marketplace.json`. For remote entries, overrides the remote-fetched description (curator-wins). |
-| `homepage` | no | Pass-through URL. |
-| `tags` | no | Pass-through list of strings. Omitted from output when empty. Max 50 items, 100 chars each. |
-| `keywords` | no | Alias for `tags`. Merged with `tags` (deduplicated). Same limits apply to the combined list. |
-| `author` | no | Pass-through string (e.g. `"ACME Corp"`). Must be a string if set. |
-| `license` | no | Pass-through string (e.g. `"MIT"`). Must be a string if set. |
-| `repository` | no | Pass-through URL string (e.g. `"https://github.com/org/repo"`). Must be a string if set. |
-| `version` | conditional | Semver range (see below). Either `version` or `ref` must be set for remote sources. For remote entries, a fixed version (not a range) is emitted as display metadata (curator-wins override). Local sources may set `version` to seed the compiled output. |
-| `ref` | conditional | Explicit SHA, tag, or branch. Takes precedence over `version`. Remote sources only. |
-| `subdir` | no | Subdirectory within a remote repo. Validated against path traversal. |
-| `tag_pattern` | no | Per-plugin override of `build.tagPattern`. |
-| `include_prerelease` | no | Include semver pre-release tags in range resolution. Defaults to `false`. |
-
-Unknown keys inside `marketplace:` raise a schema error rather than being silently ignored.
-
-### Local-path entries
-
-When `source` starts with `./`, the entry is a local-path plugin: APM does not run `git ls-remote`, does not resolve a SHA, and emits the path into `marketplace.json` as a plain string source.
-
-If `metadata.pluginRoot` is set, local source paths are emitted **relative to pluginRoot** in the output. For example, with `pluginRoot: ./plugins`, a source of `./plugins/my-tool` is emitted as `./my-tool`. This prevents double-prefix bugs where consumers prepend pluginRoot to an already-rooted path.
-
-If the source path does not start with pluginRoot, it is emitted verbatim and a build warning is produced.
-
-```yaml
-plugins:
-  - name: local-tool
-    source: ./plugins/local-tool
-    description: Vendored alongside this marketplace
-    version: 0.1.0
-```
-
-### `.gitignore`
-
-Both `apm.yml` and the generated `.claude-plugin/marketplace.json` must be tracked. `apm marketplace init` warns if your `.gitignore` would exclude the generated file. If you use a generic `*.json` rule, add an explicit unignore:
-
-```gitignore
-# .gitignore
-*.json
-!.claude-plugin/marketplace.json
-```
-
-## The build flow
-
-`apm pack` reads `apm.yml`, resolves each remote plugin against `git ls-remote`, leaves local-path entries untouched, and writes `.claude-plugin/marketplace.json` atomically (temp file plus rename).
-
-```
-$ apm pack
-```
-
-Marketplace-relevant flags:
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Resolve and print the result table, but do not write `marketplace.json`. |
-| `--offline` | Use only cached refs; fail entries that need a fresh `git ls-remote`. |
-| `--include-prerelease` | Allow pre-release tags to satisfy every range (overrides per-entry flag). |
-| `--marketplace-output PATH` | Override the output path. Default: `.claude-plugin/marketplace.json`. |
-| `-v`, `--verbose` | Include per-entry resolution detail. |
-
-`apm pack` also accepts bundle flags (`--format`, `--target`, `--archive`, `-o`, `--force`); they are silent no-ops in a marketplace-only project. See [`apm pack` reference](../../reference/cli-commands/#apm-pack---pack-distributable-artifacts) for the full list.
-
-The default output path matches Anthropic's convention -- Claude Code reads `.claude-plugin/marketplace.json` from the repo root. Override with `--marketplace-output PATH` only when you need to inspect a build without touching the committed file:
-
-```bash
-apm pack --marketplace-output ./build/marketplace.json --dry-run
-```
-
-### What the compiler does
-
-1. Parses and validates the `marketplace:` block. Unknown keys or invalid semver is a schema error (exit 2).
-2. For each remote plugin: runs `git ls-remote`, enumerates tags and branches, filters by the entry's tag pattern, resolves the version range, picks the highest match.
-3. For each local-path plugin: emits the path verbatim, no resolution.
-4. Walks `metadata:` unchanged into the output.
-5. Emits `plugins:` with the Anthropic key name; each entry carries the resolved `source` plus any pass-through fields. Inherited top-level fields and empty `tags:` are omitted.
-6. Writes the file atomically.
-
-### Exit codes
-
-| Code | Meaning |
-|------|---------|
-| `0` | Build succeeded; `marketplace.json` written (or previewed). |
-| `1` | Build error -- network failure, ref not found, no tag matches the range, etc. |
-| `2` | Schema error in the `marketplace:` block. |
-
-### Anthropic compliance
-
-`marketplace.json` produced by `apm pack` follows three rules:
-
-1. **`plugins:` is emitted verbatim.** APM does not rename, reorder, or decorate plugin entries.
-2. **`metadata:` is an opaque pass-through.** Whatever you put under `marketplace.metadata:` in `apm.yml` is copied byte-for-byte into `marketplace.json`, preserving key casing (for example, `pluginRoot` stays `pluginRoot`).
-3. **APM-only fields are stripped at compile time.** The `build:` block, per-plugin `version` ranges, `tag_pattern` overrides, and `include_prerelease` flags live only in `apm.yml`. They never leak into `marketplace.json`.
-
-APM does not emit a `versions[]` array. Each compiled plugin has exactly one resolved `source.ref` -- the latest commit SHA (or explicit ref) that satisfies the declared range at build time. Empty `tags:` and inherited `description`/`version` are omitted from output.
-
-## Migrating from `marketplace.yml`
-
-Earlier APM versions stored this configuration in a standalone `marketplace.yml`. That file is deprecated. APM still reads it (with a warning) when no `marketplace:` block is present in `apm.yml`, but `apm marketplace init` no longer creates one. Both files present at once is a hard error.
-
-Run the one-shot migration:
-
-```bash
-apm marketplace migrate            # preview the new apm.yml block
-apm marketplace migrate --yes      # apply: rewrite apm.yml, delete marketplace.yml
-```
-
-`--force`, `--yes`, and `-y` are equivalent overrides for an existing `marketplace:` block in `apm.yml`. After migration, commit `apm.yml` (and the deleted `marketplace.yml`).
-
-## Version ranges
-
-APM uses npm-compatible semver ranges. The most common forms:
-
-| Range | Matches |
-|-------|---------|
-| `1.2.3` | Exact version. |
-| `^1.2.3` | Compatible: `>=1.2.3 <2.0.0`. |
-| `~1.2.3` | Patch-level: `>=1.2.3 <1.3.0`. |
-| `>=1.2.0` | Everything from 1.2.0 upwards. |
-| `<2.0.0` | Everything below 2.0.0. |
-| `1.x` or `1.*` | Any 1.y.z. |
-| `>=1.2.0 <2.0.0` | AND-combination. |
-
-Pre-release tags (for example `1.2.0-beta.1`) are excluded by default. Set `include_prerelease: true` on the entry, or pass `--include-prerelease` to `apm pack`, to include them.
-
-Pin to a non-semver ref when you need exact reproducibility:
-
-```yaml
-plugins:
-  - name: pinned-plugin
-    source: acme-org/pinned-plugin
-    ref: 3f2a9b1cdeadbeef   # SHA, tag, or branch -- overrides version ranges
-```
-
-`ref` takes precedence over `version`. If both are set, `version` is ignored.
-
-## Managing plugins
-
-Three subcommands let you manage entries in `marketplace.plugins` without hand-editing YAML.
-
-### Adding a plugin
-
-```bash
-apm marketplace package add microsoft/apm-sample-package \
-  --version ">=1.0.0" \
-  --description "Sample package"
-```
-
-`package add` takes a `<owner>/<repo>` source, derives the plugin name from the repo, and appends an entry to `marketplace.plugins` in `apm.yml`. Pass `--name` to override the derived name, `--subdir` for monorepo paths, `--tag-pattern` for non-default tag layouts, or `--tags` to attach metadata tags. By default the command verifies the source is reachable via `git ls-remote`; pass `--no-verify` to skip that check.
-
-`--version` and `--ref` are mutually exclusive -- use `--ref` to pin an exact SHA, tag, or branch instead of a semver range.
-
-### Updating a plugin
-
-```bash
-apm marketplace package set apm-sample-package --version ">=2.0.0"
-```
-
-`package set` takes the plugin name (not the source) and updates the specified fields in place.
-
-### Removing a plugin
-
-```bash
-apm marketplace package remove apm-sample-package --yes
-```
-
-`package remove` drops the named entry. Without `--yes` the command prompts for confirmation.
-
-## Checking and troubleshooting
-
-### `apm marketplace check`
-
-Validates the schema and verifies every entry is resolvable. Use it in CI before publishing.
-
-```bash
-apm marketplace check
-apm marketplace check --offline    # schema + cached refs only
-```
-
-Exit code is non-zero when any entry is unreachable, a ref does not exist, or no tag satisfies a range.
-
-### `apm marketplace doctor`
-
-Checks the environment -- git version, network reachability of common hosts, `gh` CLI presence, git authentication, and whether the project's marketplace config is present and parses.
-
-```bash
-apm marketplace doctor
-```
-
-Run it first when `apm pack` or `publish` fails in an unfamiliar environment.
-
-### Common errors
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `Both apm.yml ... and marketplace.yml exist` | Legacy file lingered after edits to apm.yml. | Run `apm marketplace migrate --yes` (or delete `marketplace.yml` if apm.yml is already the source of truth). |
-| `'plugins[0].source' must match ...` | `source` is a full URL or contains a path. | Use `owner/repo`, or `./path` for a local entry, and put repo paths under `subdir:`. |
-| `No tag matching '^1.0.0'` | No published tags satisfy the range under your tag pattern. | Loosen the range, check `tag_pattern`, or pin with `ref:`. |
-| `Ref 'main' not found` | Branch or tag does not exist upstream. | Verify with `git ls-remote <url>`. |
-| `Pre-release tags skipped` | Latest published tag is a pre-release. | Set `include_prerelease: true` on the entry or pass `--include-prerelease`. |
-| `No cached refs (offline)` | First-ever `--offline` build. | Run once online to populate the cache, then retry offline. |
-| `git ls-remote` auth failure | Private source without credentials. | Ensure your git credentials (SSH agent or `gh auth login`) can reach the source repo. |
-
-### GitHub Enterprise Server
-
-`apm pack` respects the `GITHUB_HOST` environment variable. Set it before building to resolve plugins from a GHES instance:
-
-```bash
-export GITHUB_HOST=github.company.com
-apm pack
-```
-
-Token resolution and metadata fetch use the same host, so existing auth configuration (see [Authentication](../../getting-started/authentication/)) works automatically. `git ls-remote` calls are authenticated with the resolved token, so private GHES repos work without a separate git credential helper.
-
-## Discovering upgrades
-
-`apm marketplace outdated` compares the currently resolved version of each plugin (as captured in `marketplace.json`) against the latest tag available in the source repo.
-
-```bash
-apm marketplace outdated
-apm marketplace outdated --include-prerelease
-apm marketplace outdated --offline
-```
-
-Output columns: plugin, current version, declared range, latest in range, latest overall. Plugins whose "latest overall" exceeds "latest in range" need a **manual range bump** (for example, widening `^1.0.0` to `^2.0.0`) before the next `apm pack` will pick them up. This is intentional -- major-version bumps are a maintainer decision.
-
-Plugins pinned with `ref:` and local-path entries show `--` in the range columns; `outdated` cannot reason about them.
-
-## Publishing to consumers
-
-`apm marketplace publish` drives the compiled `marketplace.json` out to consumer repositories and opens pull requests on their behalf. It is the end-to-end flow for "I just built a new marketplace version; roll it out."
-
-You need:
-
-1. A built `marketplace.json` on the current branch (run `apm pack` first).
-2. A `consumer-targets.yml` file listing the repos to update.
-3. The [`gh` CLI](https://cli.github.com/) authenticated against GitHub (unless you use `--no-pr`).
-
-### The targets file
-
-```yaml
-# consumer-targets.yml
-targets:
-  - repo: acme-org/service-a
-    branch: main
-  - repo: acme-org/service-b
-    branch: develop
-    path_in_repo: apm/apm.yml        # optional; defaults to apm.yml
-  - repo: acme-org/service-c
-    branch: main
-```
-
-`repo` and `branch` are required; `path_in_repo` defaults to `apm.yml`. Paths are validated for traversal.
-
-### First run -- preview
-
-Always dry-run first:
-
-```bash
-apm marketplace publish --dry-run --yes
-```
-
-This clones each target, computes what would change in its lockfile references, and prints a plan. Nothing is pushed.
-
-### Real run
-
-```bash
-apm marketplace publish
-```
-
-Output shows per-target status: updated, unchanged, failed. PR URLs are printed for each target that had changes.
-
-### Useful flags
-
-| Flag | Purpose |
-|------|---------|
-| `--targets PATH` | Use a custom targets file (default `./consumer-targets.yml`). |
-| `--dry-run` | Preview; no push, no PR. |
-| `--no-pr` | Push the branch to each target but skip PR creation. |
-| `--draft` | Open PRs as drafts. |
-| `--allow-downgrade` | Allow pushing a lower version than the target currently references. |
-| `--allow-ref-change` | Allow switching ref types (for example, branch to SHA). |
-| `--parallel N` | Maximum concurrent targets. Default `4`. |
-| `--yes`, `-y` | Skip interactive confirmation (required for non-interactive CI). |
-| `-v`, `--verbose` | Per-target detail. |
-
-### State file
-
-Publish runs append to `.apm/publish-state.json`, which records the history of runs (timestamps, targets, outcomes, PR URLs). This lets later invocations detect already-open PRs and avoid opening duplicates. The file is safe to commit or to gitignore -- it is advisory, not authoritative.
-
-## Recipes
-
-### Custom tag pattern
-
-Projects that prefix tags with a plugin name (common in monorepos) need a per-entry pattern:
-
-```yaml
-marketplace:
-  plugins:
-    - name: ui-components
-      source: acme-org/frontend-monorepo
-      subdir: packages/ui-components
-      version: "^3.0.0"
-      tag_pattern: "ui-components-v{version}"
-```
-
-The `{name}` placeholder resolves to the plugin entry's `name`, so you can also write `tag_pattern: "{name}-v{version}"` and reuse a single `build.tagPattern`.
-
-### Pre-release tags are being skipped
-
-Set `include_prerelease: true` on the entry, or pass `--include-prerelease` to `apm pack` and `apm marketplace outdated` for the whole marketplace:
-
-```yaml
-marketplace:
-  plugins:
-    - name: example-plugin
-      source: acme-org/example-plugin
-      version: ">=1.0.0-0"
-      include_prerelease: true
-```
-
-Note the `-0` pre-release suffix on the range -- it makes the lower bound inclusive of pre-releases.
-
-### Can I use a non-GitHub host?
-
-Not in the first release. `apm marketplace publish` uses the `gh` CLI and assumes GitHub for PR creation. You can still pack and `check` against any git remote that speaks `git ls-remote` over HTTPS or SSH; only `publish` is GitHub-specific. For non-GitHub consumers, run `publish --no-pr` and drive PR creation through your own tooling.
-
-## Related reading
-
-- [Marketplaces guide](../marketplaces/) -- consumer-side: registering and installing from a marketplace.
-- [CLI command reference](../../reference/cli-commands/) -- authoritative options for `apm pack` and every `apm marketplace` subcommand.
-- [Manifest schema](../../reference/manifest-schema/) -- the `apm.yml` shape including the `marketplace:` block.
-- [Plugins guide](../plugins/) -- what a plugin is and how consumers install one.
diff --git a/docs/src/content/docs/guides/marketplaces.md b/docs/src/content/docs/guides/marketplaces.md
deleted file mode 100644
index 512b8bdef..000000000
--- a/docs/src/content/docs/guides/marketplaces.md
+++ /dev/null
@@ -1,375 +0,0 @@
----
-title: "Marketplaces"
-sidebar:
-  order: 5
----
-
-Marketplaces are curated indexes of plugins hosted in a Git repository (typically GitHub or GitLab). Each marketplace contains a `marketplace.json` file that maps plugin names to source locations. APM resolves these entries to Git URLs, so plugins installed from marketplaces get the same version locking, security scanning, and governance as any other APM dependency.
-
-## How marketplaces work
-
-A marketplace is a repository with a `marketplace.json` at its root (GitHub or GitLab). The file lists plugins with their source type and location:
-
-```json
-{
-  "name": "Acme Plugins",
-  "plugins": [
-    {
-      "name": "code-review",
-      "description": "Automated code review agent",
-      "source": { "type": "github", "repo": "acme/code-review-plugin" }
-    },
-    {
-      "name": "style-guide",
-      "source": { "type": "url", "url": "https://github.com/acme/style-guide.git" }
-    },
-    {
-      "name": "eslint-rules",
-      "source": { "type": "git-subdir", "repo": "acme/monorepo", "subdir": "plugins/eslint-rules" }
-    },
-    {
-      "name": "local-tools",
-      "source": "./tools/local-plugin"
-    }
-  ]
-}
-```
-
-Both Copilot CLI and Claude Code `marketplace.json` formats are supported. Copilot CLI uses `"repository"` and `"ref"` fields; Claude Code uses `"source"` (string or object). APM normalizes entries from either format into its canonical dependency representation.
-
-### Supported source types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| `github` | GitHub `owner/repo` shorthand | `acme/code-review-plugin` |
-| `url` | Full HTTPS or SSH Git URL | `https://github.com/acme/style-guide.git` |
-| `git-subdir` | Subdirectory within a Git repository (`repo` + `subdir`) | `acme/monorepo` + `plugins/eslint-rules` |
-| String `source` | Subdirectory within the marketplace repository itself | `./tools/local-plugin` |
-
-npm sources are not supported. Copilot CLI format uses `"repository"` and optional `"ref"` fields instead of `"source"`.
-
-### Source key aliases
-
-The install resolver accepts both legacy (Copilot CLI) and current (Claude Code) key names in `marketplace.json` source objects:
-
-| Current key | Legacy alias | Notes |
-|---|---|---|
-| `source` (discriminator) | `type` | Values: `github`, `git-subdir`, `url` |
-| `repo` | `repository` | Must be `owner/repo` format |
-| `sha` | `commit` | Resolved commit SHA |
-| `repo` (git-subdir) | `url` | Must be `owner/repo`, not a full URL |
-
-Marketplace authors should use the current keys (emitted by `apm pack`). Legacy aliases are accepted for backward compatibility with older manifests.
-
-### Plugin root directory
-
-Marketplaces can declare a `metadata.pluginRoot` field to specify the base directory for bare-name sources:
-
-```json
-{
-  "metadata": { "pluginRoot": "./plugins" },
-  "plugins": [
-    { "name": "my-tool", "source": "my-tool" }
-  ]
-}
-```
-
-With `pluginRoot` set to `./plugins`, the source `"my-tool"` resolves to `owner/repo/plugins/my-tool`. Sources that already contain a path separator (e.g. `./custom/path`) are not affected by `pluginRoot`.
-
-### Versioned plugins
-
-Plugins can declare a `version` field and a `source.ref` that points to a specific Git tag or commit:
-
-```json
-{
-  "name": "code-review",
-  "description": "Automated code review agent",
-  "version": "2.1.0",
-  "source": { "type": "github", "repo": "acme/code-review-plugin", "ref": "v2.1.0" }
-}
-```
-
-The `version` field is informational (displayed by `apm view` and `apm outdated`). The `source.ref` determines which Git ref APM checks out during install.
-
-## Register a marketplace
-
-```bash
-apm marketplace add acme/plugin-marketplace
-```
-
-This registers the marketplace and fetches its `marketplace.json`. By default APM tracks the `main` branch.
-
-:::tip[Create your own marketplace]
-You can author and publish your own marketplace registry.
-See the [Marketplace Authoring Guide](../marketplace-authoring/) for details.
-:::
-
-### Default alias resolution
-
-When `--name` is not provided, APM resolves the local alias in this order:
-
-1. `name` field declared in the marketplace's `marketplace.json` (if present and valid)
-2. Repository name (fallback)
-
-This ensures parity with Claude Code install instructions -- if a marketplace's `marketplace.json` declares `"name": "addy-agent-skills"`, APM registers it under that alias and shows a hint:
-
-```
-[*] Registering marketplace 'addy-agent-skills'...
-[+] Marketplace 'addy-agent-skills' registered (1 plugins)
-[i] Install plugins with: apm install <plugin>@addy-agent-skills
-```
-
-Use `--name` to override the alias explicitly.
-
-**Options:**
-- `--name/-n` -- Override the local alias (defaults to the `marketplace.json` `name` field, then repo name)
-- `--branch/-b` -- Branch to track (default: `main`)
-- `--host` -- Git host FQDN for non-github.com hosts (default: `github.com` or `GITHUB_HOST` env var)
-
-```bash
-# Register with a custom name on a specific branch
-apm marketplace add acme/plugin-marketplace --name acme-plugins --branch release
-
-# Register from a GitHub Enterprise host (two equivalent forms)
-apm marketplace add acme/plugin-marketplace --host ghes.corp.example.com
-apm marketplace add ghes.corp.example.com/acme/plugin-marketplace
-```
-
-## GitLab-hosted marketplaces
-
-`gitlab.com` is recognized as GitLab automatically. For **self-managed** GitLab, set `GITLAB_HOST` to that instance’s FQDN, or list several hosts in `APM_GITLAB_HOSTS` (comma-separated). See [Authentication](../../getting-started/authentication/#gitlab-saas-and-self-managed) for host configuration and tokens.
-
-APM fetches `marketplace.json` via the **GitLab REST v4** raw-file API when the host classifies as GitLab (not the GitHub Contents API). Candidate paths are unchanged: repository root, `.github/plugin/marketplace.json`, and `.claude-plugin/marketplace.json`.
-
-```bash
-# GitLab.com (FQDN in the argument or via --host)
-apm marketplace add mygroup/plugin-marketplace --host gitlab.com
-apm marketplace add gitlab.com/mygroup/plugin-marketplace
-
-# Self-managed GitLab (set GITLAB_HOST or APM_GITLAB_HOSTS so APM classifies the instance as GitLab, then use FQDN in the path or --host)
-apm marketplace add git.company.com/mygroup/plugin-marketplace
-apm marketplace add mygroup/plugin-marketplace --host git.company.com
-```
-
-## List registered marketplaces
-
-```bash
-apm marketplace list
-```
-
-Shows all registered marketplaces with their source repository and branch.
-
-## Browse plugins
-
-View all plugins available in a specific marketplace:
-
-```bash
-apm marketplace browse acme-plugins
-```
-
-## Search a marketplace
-
-Search plugins by name or description in a specific marketplace using `QUERY@MARKETPLACE`:
-
-```bash
-apm search "code review@skills"
-```
-
-**Options:**
-- `--limit` -- Maximum results to return (default: 20)
-
-```bash
-apm search "linting@awesome-copilot" --limit 5
-```
-
-The `@MARKETPLACE` scope is required -- this avoids name collisions when different
-marketplaces contain plugins with the same name. To see everything in a marketplace,
-use `apm marketplace browse <name>` instead.
-
-## Install from a marketplace
-
-Use the `NAME@MARKETPLACE` syntax to install a plugin from a specific marketplace:
-
-```bash
-# Install using the source ref from the marketplace entry
-apm install code-review@acme-plugins
-
-# Install with a specific git ref override
-apm install code-review@acme-plugins#v2.0.0
-
-# Install from a specific branch
-apm install code-review@acme-plugins#main
-```
-
-The `#` separator carries a raw git ref that overrides the `source.ref` from the marketplace entry. Without `#`, APM uses the ref defined in the marketplace manifest.
-
-APM resolves the plugin name against the marketplace index, fetches the underlying Git repository using the resolved ref, and installs it as a standard APM dependency. The resolved source appears in `apm.yml` and `apm.lock.yaml` just like any direct dependency.
-
-On **GitLab-class** hosts (`gitlab.com` and self-managed instances when APM classifies the host as GitLab), monorepo layouts—plugins whose `marketplace.json` sources point at a subdirectory **inside** the marketplace repository—work with this syntax; you do not need a manual `git:` + `path:` dependency entry for `apm install`. When you declare Git dependencies yourself in `apm.yml`, nested paths may still need the object form with explicit `git:` and `path:`—see the [Dependencies guide](./dependencies/).
-
-For full `apm install` options, see [CLI Commands](../../reference/cli-commands/).
-
-## View plugin details
-
-Show metadata for a marketplace plugin:
-
-```bash
-apm view code-review@acme-plugins
-```
-
-Displays the plugin's name, version, description, source, and tags.
-
-## Provenance tracking
-
-Marketplace-resolved plugins are tracked in `apm.lock.yaml` with full provenance:
-
-```yaml
-apm_modules:
-  acme/code-review-plugin:
-    resolved: https://github.com/acme/code-review-plugin#main
-    commit: abc123def456789
-    discovered_via: acme-plugins
-    marketplace_plugin_name: code-review
-```
-
-The `discovered_via` field records which marketplace was used for discovery. `marketplace_plugin_name` stores the original plugin name from the index. The `resolved` URL and `commit` pin the exact version, so builds remain reproducible regardless of marketplace availability.
-
-## Cache behavior
-
-APM caches marketplace indexes locally with a 1-hour TTL. Within that window, commands like `search` and `browse` use the cached index. After expiry, APM fetches a fresh copy from the network. If the network request fails, APM falls back to the expired cache (stale-if-error) so commands still work offline.
-
-Force a cache refresh:
-
-```bash
-# Refresh a specific marketplace
-apm marketplace update acme-plugins
-
-# Refresh all registered marketplaces
-apm marketplace update
-```
-
-## Registry proxy support
-
-When `PROXY_REGISTRY_URL` is set, marketplace commands (`add`, `browse`, `search`, `update`) fetch `marketplace.json` through the registry proxy (Artifactory Archive Entry Download) **first**. Only if the proxy does not return the file does APM fall back to the host API: **GitHub Contents API** for GitHub/GHES, or **GitLab REST v4** raw file endpoints for GitLab-classified hosts. When `PROXY_REGISTRY_ONLY=1` is also set, that direct host API fallback is blocked entirely, enabling fully air-gapped marketplace discovery for both GitHub- and GitLab-backed indexes.
-
-```bash
-export PROXY_REGISTRY_URL="https://art.corp.example.com/artifactory/github"
-export PROXY_REGISTRY_ONLY=1  # optional: block direct GitHub/GitLab API access
-
-apm marketplace add anthropics/skills   # fetches via Artifactory
-apm marketplace browse skills           # fetches via Artifactory
-```
-
-This builds on the same proxy infrastructure used by `apm install`. See [Registry Proxy & Air-gapped](../enterprise/registry-proxy/) for full configuration, the bypass-prevention contract, and the air-gapped CI playbook.
-
-## Manage marketplaces
-
-Remove a registered marketplace:
-
-```bash
-apm marketplace remove acme-plugins
-
-# Skip confirmation prompt
-apm marketplace remove acme-plugins --yes
-```
-
-Removing a marketplace does not uninstall plugins previously installed from it. Those plugins remain pinned in `apm.lock.yaml` to their resolved Git sources.
-
-## Validate a marketplace
-
-Check a marketplace manifest for schema errors and duplicate entries:
-
-```bash
-apm marketplace validate acme-plugins
-
-# Verbose output
-apm marketplace validate acme-plugins --verbose
-```
-
-Catches: missing required fields and duplicate plugin names (case-insensitive).
-
-:::note[Planned]
-The `--check-refs` flag will verify that source refs are reachable over the network. It is accepted but not yet implemented.
-:::
-
-For full option details, see [CLI Commands](../../reference/cli-commands/).
-
-## Security
-
-### Version immutability
-
-APM caches version-to-ref mappings in `~/.apm/cache/marketplace/version-pins.json`. On subsequent installs, APM compares the marketplace ref against the cached pin. If a version's ref has changed, APM warns:
-
-```
-WARNING: Version 2.0.0 of code-review@acme-plugins ref changed: was 'v2.0.0', now 'deadbeef'. This may indicate a ref swap attack.
-```
-
-This detects marketplace maintainers (or compromised accounts) silently pointing an existing version at different code.
-
-### Shadow detection
-
-When installing a marketplace plugin, APM checks all other registered marketplaces for plugins with the same name. A match produces a warning:
-
-```
-WARNING: Plugin 'code-review' also found in marketplace 'other-plugins'. Verify you are installing from the intended source.
-```
-
-Shadow detection runs automatically during install -- no configuration required.
-
-### Best practices
-
-- **Use commit SHAs as refs** -- tags and branches can be moved; commit SHAs cannot.
-- **Keep plugin names unique across marketplaces** -- avoids shadow warnings and reduces confusion.
-- **Review immutability warnings** -- a changed ref for an existing version is a strong signal of tampering.
-
-## Authoring: monorepo workflows
-
-When building a marketplace that tracks packages from a monorepo (multiple packages inside one Git repository), use `--subdir` to point each entry at its subdirectory:
-
-```bash
-apm marketplace package add acme/monorepo --subdir plugins/eslint-rules --name eslint-rules
-apm marketplace package add acme/monorepo --subdir plugins/formatter --name formatter
-```
-
-### Ref auto-resolution
-
-Mutable git refs (`HEAD`, branch names) are automatically resolved to concrete 40-character SHAs before being stored in `apm.yml`. This ensures supply-chain safety -- the entry always pins to an immutable commit.
-
-**Default behaviour (no `--ref`):** When neither `--version` nor `--ref` is provided, the current `HEAD` SHA is pinned automatically:
-
-```bash
-# Resolves HEAD to its current SHA and stores it
-apm marketplace package add acme/code-review
-```
-
-**Explicit `HEAD`:** Passing `--ref HEAD` warns that HEAD is mutable, then resolves:
-
-```bash
-apm marketplace package add acme/code-review --ref HEAD
-# [!] 'HEAD' is a mutable ref. Resolving to current SHA for safety.
-# [i] Resolved HEAD to abc123def456
-```
-
-**Branch names:** Branch names that match `refs/heads/*` on the remote are also resolved:
-
-```bash
-apm marketplace package add acme/code-review --ref main
-# [!] 'main' is a branch (mutable ref). Resolving to current SHA for safety.
-# [i] Resolved main to abc123def456
-```
-
-**Updating pinned SHAs:** Use `package set` with `--ref HEAD` to re-pin to the latest commit:
-
-```bash
-apm marketplace package set code-review --ref HEAD
-```
-
-Tags and concrete SHAs are stored as-is without resolution.
-
-:::note
-Ref auto-resolution requires network access. When using `--no-verify`, you must provide an explicit SHA with `--ref`.
-:::
-
-## Creating your own marketplace
-
-If you want to create and maintain your own marketplace registry, see the [Marketplace Authoring Guide](../../guides/marketplace-authoring/).
diff --git a/docs/src/content/docs/guides/mcp-servers.md b/docs/src/content/docs/guides/mcp-servers.md
deleted file mode 100644
index 1b3fb5955..000000000
--- a/docs/src/content/docs/guides/mcp-servers.md
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: "MCP Servers"
-description: "Add MCP servers to your project with apm install --mcp. Supports stdio, registry, and remote HTTP servers across Copilot, Claude, Cursor, Codex, OpenCode, and Gemini."
-sidebar:
-  order: 6
----
-
-APM manages your agent configuration in `apm.yml` -- think `package.json` for AI. MCP servers are dependencies in that manifest.
-
-`apm install --mcp` adds a server to `apm.yml` and wires it into every detected client (Copilot, Claude, Cursor, Codex, OpenCode, Gemini) in one step.
-
-## Quick Start
-
-Three shapes cover almost every MCP server you will install. Pick the one that matches what you copied from the server's README.
-
-**stdio (post-`--` argv)** -- most public servers ship as an `npx`/`uvx` invocation:
-
-```bash
-apm install --mcp filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace
-```
-
-**Registry (resolved from the MCP registry):**
-
-```bash
-apm install --mcp io.github.github/github-mcp-server
-```
-
-**Remote (HTTP / SSE):**
-
-```bash
-apm install --mcp linear --transport http --url https://mcp.linear.app/sse
-```
-
-After any of the three:
-
-```bash
-apm mcp list                # confirm server is wired into detected runtimes
-```
-
-`apm mcp install` is an alias if you prefer the noun-first form: `apm mcp install filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace`.
-
-## Three Ways to Add an MCP Server
-
-| Source | Example | When to use |
-|--------|---------|-------------|
-| stdio command | `apm install --mcp NAME -- <bin> <args...>` | You have a working `npx`/`uvx`/binary invocation from a README. |
-| Registry name | `apm install --mcp io.github.github/github-mcp-server` | The server is published to the [MCP registry](https://api.mcp.github.com). Discover with `apm mcp search`. |
-| Remote URL | `apm install --mcp NAME --transport http --url https://...` | The server is hosted -- no local process to spawn. |
-
-The post-`--` form is recommended over `--transport stdio` plus separate fields: it is exactly what you can paste from any MCP server's README.
-
-## CLI Reference: `apm install --mcp`
-
-```bash
-apm install --mcp NAME [OPTIONS] [-- COMMAND ARGV...]
-```
-
-`NAME` is the entry that lands under `dependencies.mcp` in `apm.yml`. It must match `^[a-zA-Z0-9@_][a-zA-Z0-9._@/:=-]{0,127}$`.
-
-| Flag | Purpose |
-|------|---------|
-| `--mcp NAME` | Add `NAME` to `dependencies.mcp` and install it. Required to enter this code path. |
-| `--transport stdio\|http\|sse\|streamable-http` | Override transport. Inferred from `--url` (remote) or post-`--` argv (stdio) when omitted. |
-| `--url URL` | Endpoint for `http` / `sse` transports. Scheme must be `http` or `https`. |
-| `--env KEY=VALUE` | Environment variable for stdio servers. Repeatable. |
-| `--header KEY=VALUE` | HTTP header for remote servers. Repeatable. Requires `--url`. |
-| `--mcp-version VER` | Pin the registry entry to a specific version. |
-| `--registry URL` | Custom MCP registry URL (`http://` or `https://`) for resolving the registry-form `NAME`. Overrides the `MCP_REGISTRY_URL` env var. Captured in `apm.yml` on the entry's `registry:` field for auditability. Not valid with `--url` or a stdio command (self-defined entries). |
-| `--dev` | Add to `devDependencies.mcp` instead of `dependencies.mcp`. |
-| `--force` | Replace an existing entry with the same `NAME` without prompting (CI). |
-| `--dry-run` | Print what would be added; do not write `apm.yml` or touch client configs. |
-| `-- COMMAND ARGV...` | Everything after `--` is the stdio command for the server. Implies `--transport stdio`. |
-
-`apm mcp install NAME ...` is an alias that forwards to `apm install --mcp NAME ...`.
-
-Inherited flags that still apply: `--runtime`, `--exclude`, `--verbose`. Flags that do **not** apply with `--mcp`: `--global` (MCP entries are project-scoped), `--only apm`, `--update`, `--ssh` / `--https` / `--allow-protocol-fallback` -- see [Errors and Conflicts](#errors-and-conflicts).
-
-## What Gets Written
-
-`apm install --mcp` is the interface. `apm.yml` is the result. Each shape produces one of three entry forms.
-
-**stdio command** (`apm install --mcp filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace`):
-
-```yaml title="apm.yml"
-dependencies:
-  mcp:
-    - name: filesystem
-      registry: false
-      transport: stdio
-      command: npx
-      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
-```
-
-**Registry reference** (`apm install --mcp io.github.github/github-mcp-server`):
-
-```yaml title="apm.yml"
-dependencies:
-  mcp:
-    - io.github.github/github-mcp-server
-```
-
-**Remote** (`apm install --mcp linear --transport http --url https://mcp.linear.app/sse --header Authorization="Bearer $TOKEN"`):
-
-```yaml title="apm.yml"
-dependencies:
-  mcp:
-    - name: linear
-      registry: false
-      transport: http
-      url: https://mcp.linear.app/sse
-      headers:
-        Authorization: "Bearer $TOKEN"
-```
-
-For the full manifest grammar (overlays on registry servers, `${input:...}` variables, package selection), see the [MCP dependencies reference](../dependencies/#mcp-dependency-formats) and the [manifest schema](../../reference/manifest-schema/).
-
-## Updating and Replacing Servers
-
-Re-running `apm install --mcp NAME` against an existing entry is the supported way to change configuration.
-
-| Situation | Behaviour |
-|-----------|-----------|
-| New `NAME` | Appended to `dependencies.mcp`. Exit 0. |
-| Existing `NAME`, identical config | No-op. Logs `unchanged`. Exit 0. |
-| Existing `NAME`, different config, interactive TTY | Prints diff, prompts `Replace MCP server 'NAME'?`. Exit 0. |
-| Existing `NAME`, different config, non-TTY (CI) | Refuses with exit code 2. Re-run with `--force`. |
-| Existing `NAME` + `--force` | Replaces silently. Exit 0. |
-
-Use `--dry-run` to preview the change without writing:
-
-```bash
-apm install --mcp filesystem --dry-run -- npx -y @modelcontextprotocol/server-filesystem /new/path
-```
-
-## Validation and Security
-
-APM validates every `--mcp` entry before writing `apm.yml`. These are guardrails, not gatekeepers -- they catch the common ways an MCP entry can break a client config or leak credentials.
-
-| Check | Rule | Why |
-|-------|------|-----|
-| `NAME` shape | `^[a-zA-Z0-9@_][a-zA-Z0-9._@/:=-]{0,127}$` | Keeps names round-trippable as YAML keys, file paths, and registry identifiers. Leading `-` is rejected (argv flag confusion) and leading `.` is rejected (dotfile / relative-path confusion). Leading `_` is allowed for private/internal naming conventions. |
-| `--url` scheme | `http` or `https` only | Blocks `file://`, `gopher://`, and similar exfil vectors. |
-| `--registry` scheme | `http` or `https` only; `ws://`, `wss://`, `file://`, `javascript:` rejected | Same allowlist as `--url`. Length capped at 2048 chars. Empty / schemeless values fail with a usage error. |
-| `--header` content | No CR or LF in keys or values | Prevents header injection / response splitting. |
-| `command` (stdio) | No path-traversal segments (`..`, absolute escapes) | Blocks an entry from pointing the client at a binary outside the project. |
-| Internal / metadata `--url` | Warning, not blocked | Catches accidental cloud-metadata-IP URLs without breaking valid intranet servers. |
-| `--env` shell metacharacters | Warning, not blocked | Reminds you that stdio servers do not go through a shell, so `$VAR` and backticks are passed literally. |
-
-Self-defined servers (everything except the bare-string registry form) additionally require:
-
-- `transport` -- one of `stdio`, `http`, `sse`, `streamable-http`. These are MCP transport names, not URL schemes: remote variants connect over HTTPS.
-- `url` -- when `transport` is `http`, `sse`, or `streamable-http`.
-- `command` -- when `transport` is `stdio`.
-
-For the trust boundary on transitive MCP servers (`--trust-transitive-mcp`), see [Dependencies: Trust Model](../dependencies/#mcp-dependency-formats) and [Security Model](../../enterprise/security/).
-
-## Errors and Conflicts
-
-`apm install --mcp` rejects flag combinations that would silently do the wrong thing. All conflicts exit with code 2.
-
-| Error | Trigger | Fix |
-|-------|---------|-----|
-| `cannot mix --mcp with positional packages` | `apm install owner/repo --mcp foo` | Run `--mcp` and APM-package installs as separate commands. |
-| `MCP servers are project-scoped; --global is not supported for MCP entries` | `apm install -g --mcp foo` | MCP servers always land in the project `apm.yml`. Drop `-g`. |
-| `cannot use --only apm with --mcp` | Filtering by APM-only while adding an MCP entry. | Drop `--only apm`. |
-| `--header requires --url` | `--header` without an HTTP/SSE endpoint. | Add `--url`, or use `--env` for stdio servers. |
-| `cannot specify both --url and a stdio command` | Mixed remote + post-`--` argv. | Pick one shape. |
-| `stdio transport doesn't accept --url` | `--transport stdio --url ...` | Use post-`--` argv for stdio. |
-| `remote transports don't accept stdio command` | `--transport http -- npx ...` | Drop `--transport http` (or drop the post-`--` argv). |
-| `--env applies to stdio MCPs; use --header for remote` | `--env` on a remote server. | Use `--header` for HTTP/SSE auth. |
-| `--registry only applies to registry-resolved MCP servers; remove --url or the post-`--` stdio command, or drop --registry` | `--registry` combined with `--url` or a stdio command. | `--registry` only steers the registry resolver; self-defined entries do not consult a registry. |
-
-Existing-entry conflicts (`already exists in apm.yml`) are covered in [Updating and Replacing Servers](#updating-and-replacing-servers).
-
-## Custom registry (enterprise)
-
-APM resolves the MCP registry endpoint with the following precedence (highest first):
-
-1. **`apm install --mcp NAME --registry URL`** -- per-install CLI flag. Captured in `apm.yml` on the entry's `registry:` field for auditability so reviewers can see which registry each MCP server was resolved against.
-2. **`MCP_REGISTRY_URL` env var** -- process-level override for `apm mcp` discovery commands and `apm install --mcp` when the flag is not given. Not written to `apm.yml`.
-3. **Default**: `https://api.mcp.github.com`.
-
-Enterprises with **both** a public and a private registry use `--registry` to pick the private one explicitly per server, leaving `MCP_REGISTRY_URL` unset (or pointed at whichever registry should be the default for `apm mcp search/list/show`). The CLI flag wins:
-
-```bash
-# Server resolved against an internal registry, persisted to apm.yml
-apm install --mcp acme/internal-server --registry https://mcp.internal.example.com
-
-# Server resolved against the public default
-apm install --mcp io.github.github/github-mcp-server
-```
-
-In `apm.yml`, the per-server `registry:` URL is captured so reviewers can audit what each MCP server resolves against:
-
-```yaml title="apm.yml"
-dependencies:
-  mcp:
-    - name: acme/internal-server
-      registry: https://mcp.internal.example.com
-    - io.github.github/github-mcp-server
-```
-
-A future [`apm config set mcp-registry-url`](https://github.com/microsoft/apm/issues/818) command will let you set a per-project default registry without exporting an env var. Until then, use the CLI flag for per-server overrides and the env var for shell-scoped defaults.
-
-`MCP_REGISTRY_URL` overrides the MCP registry endpoint that APM queries when no `--registry` flag is present. It applies to all `apm mcp` discovery commands (`search`, `list`, `show`) and to `apm install --mcp` when resolving registry-form servers (e.g. `apm install --mcp io.github.github/github-mcp-server`). Defaults to `https://api.mcp.github.com`.
-
-```bash
-export MCP_REGISTRY_URL=https://mcp.internal.example.com
-```
-
-Scope is process-level: it applies to any shell that exports it and to child processes APM spawns. There is no per-project override yet. When the variable is set, `apm mcp search/list/show` print a one-line `Registry: <url>` diagnostic so you always know which endpoint was queried.
-
-### URL validation and security
-
-APM validates `MCP_REGISTRY_URL` and `--registry` at startup. The URL must include a scheme and host (e.g. `https://mcp.internal.example.com`); schemeless values, empty strings, and unsupported schemes (anything other than `http`/`https`) are rejected with an actionable error. URLs longer than 2048 characters are rejected.
-
-For the **env var** path, plaintext `http://` is **rejected by default** to prevent token leakage and tampering. For development or air-gapped intranets where TLS is genuinely impractical, opt in explicitly:
-
-```bash
-export MCP_REGISTRY_ALLOW_HTTP=1
-export MCP_REGISTRY_URL=http://mcp.internal.example.com
-```
-
-For the **`--registry` CLI flag**, both `http://` and `https://` are accepted without an opt-in: the explicit, per-invocation user intent is treated as a strong signal, matching how npm-style tools handle private/local registries on intranets. Production deployments should still prefer `https://`.
-
-When a custom registry is set and unreachable during install pre-flight, APM treats the network error as **fatal** instead of silently assuming servers exist. This prevents a misconfigured or down enterprise registry from quietly approving every MCP dependency. The default registry (`https://api.mcp.github.com`) keeps the existing assume-valid behaviour for transient errors so unrelated network blips do not block installs.
-
-## Next Steps
-
-- [Dependencies & Lockfile](../dependencies/#mcp-dependency-formats) -- the full `apm.yml` MCP grammar (overlays, `${input:...}`, package selection).
-- [CLI Reference](../../reference/cli-commands/) -- every `apm install` flag in one place.
-- [IDE & Tool Integration](../../integrations/ide-tool-integration/#mcp-model-context-protocol-integration) -- where each client reads MCP config from on disk.
-- [Plugins](../plugins/#mcp-server-definitions) -- ship MCP servers as part of a plugin package.
-- [Security Model](../../enterprise/security/) -- trust boundary, transitive-server policy, and how `--trust-transitive-mcp` fits in.
diff --git a/docs/src/content/docs/guides/org-packages.md b/docs/src/content/docs/guides/org-packages.md
deleted file mode 100644
index 5aae05e8d..000000000
--- a/docs/src/content/docs/guides/org-packages.md
+++ /dev/null
@@ -1,283 +0,0 @@
----
-title: "Org-Wide Packages"
-description: "Build shared standards packages that standardize AI agent configuration across your organization."
-sidebar:
-  order: 7
----
-
-## The pattern
-
-A central team publishes a standards package — say `acme-corp/apm-standards`. Every repository in the organization adds it as a dependency. When the standards team pushes an update, every consumer gets it on their next `apm deps update`.
-
-```
-acme-corp/apm-standards (central package)
-    ├── .apm/instructions/coding-standards.md
-    ├── .apm/instructions/security-baseline.md
-    ├── .apm/agents/review-agent.md
-    └── apm.yml
-
-repo-A/  ──depends on──▶  acme-corp/apm-standards
-repo-B/  ──depends on──▶  acme-corp/apm-standards
-repo-C/  ──depends on──▶  acme-corp/apm-standards
-```
-
-One update to the standards package propagates to all consumers. No copy-pasting, no drift.
-
-## Why shared packages?
-
-**Consistency.** Every repository gets the same coding standards, security baselines, and review agents. New repos start with the org's best practices from day one.
-
-**Single update point.** Change a security policy once in the standards package. Every consumer picks it up with `apm deps update` — no need to open PRs across dozens of repos.
-
-**Versioned.** Consumers pin to a specific version and upgrade on their own schedule. No forced rollouts, no surprise breakage.
-
-**Composable.** Layer packages from broad to narrow: org-wide base, then team-specific, then project-specific. Each layer can override or extend the one below it.
-
-## Creating an org package
-
-Start by initializing a new APM package:
-
-```bash
-apm init acme-standards && cd acme-standards
-```
-
-Then populate it with the shared configuration your org needs.
-
-### Instructions — coding standards and policies
-
-Place organization-wide instructions in `.apm/instructions/`:
-
-```markdown
-<!-- .apm/instructions/coding-standards.md -->
-# Coding Standards
-
-- Write clear, self-documenting code. Prefer readability over cleverness.
-- All public functions must have docstrings.
-- Use type hints in Python, TypeScript types in JS/TS projects.
-- Keep functions under 50 lines. Extract when they grow.
-```
-
-```markdown
-<!-- .apm/instructions/security-baseline.md -->
-# Security Baseline
-
-- Never commit secrets, tokens, or credentials to source control.
-- Validate all user input at API boundaries.
-- Use parameterized queries for database access.
-- Dependencies must be pinned to exact versions in lock files.
-```
-
-### Agents — standard review and advisory agents
-
-Define reusable agent configurations in `.apm/agents/`:
-
-```markdown
-<!-- .apm/agents/security-reviewer.md -->
----
-name: security-reviewer
-description: Reviews code changes for security vulnerabilities
----
-
-You are a security-focused code reviewer. When reviewing changes:
-
-1. Check for injection vulnerabilities (SQL, command, template).
-2. Verify authentication and authorization on all endpoints.
-3. Flag hardcoded secrets or credentials.
-4. Ensure error messages don't leak internal details.
-5. Verify input validation at trust boundaries.
-
-Be specific. Reference the exact file and line. Suggest a fix.
-```
-
-### Prompts — common workflows
-
-Add shared prompt templates in `.apm/prompts/`:
-
-```markdown
-<!-- .apm/prompts/design-review.md -->
-# Design Review
-
-Review the proposed design for:
-
-1. **Scalability** — Will this handle 10x the current load?
-2. **Failure modes** — What happens when dependencies are unavailable?
-3. **Data consistency** — Are there race conditions or stale reads?
-4. **API surface** — Is the interface minimal and hard to misuse?
-
-Provide concrete recommendations, not abstract concerns.
-```
-
-### Skills — shared capabilities
-
-Place reusable skill definitions in `.apm/skills/`:
-
-```markdown
-<!-- .apm/skills/api-design.md -->
-# API Design Skill
-
-When designing or reviewing APIs:
-
-- Use consistent naming: plural nouns for collections, singular for items.
-- Return appropriate HTTP status codes (201 for creation, 204 for deletion).
-- Version APIs in the URL path (/v1/resources).
-- Paginate list endpoints by default.
-- Include request IDs in all responses for traceability.
-```
-
-### Package manifest
-
-The `apm.yml` defines what the package contains:
-
-```yaml
-# apm.yml
-name: acme-standards
-version: "1.0.0"
-description: "Acme Corp organization-wide AI agent standards"
-```
-
-## Layered composition
-
-Shared packages become powerful when you layer them. Build from broad to narrow — org-wide, then team-specific, then project-specific.
-
-### Team package — extends the org base
-
-```yaml
-# acme-corp/acme-team-frontend/apm.yml
-name: acme-team-frontend
-version: "1.0.0"
-description: "Frontend team standards, extends org base"
-
-dependencies:
-  apm:
-    - acme-corp/apm-standards        # org-wide base
-    - acme-corp/frontend-skills      # frontend-specific capabilities
-```
-
-The team package adds frontend-specific instructions and agents while inheriting the org-wide security baseline and coding standards.
-
-### Project — pulls in everything transitively
-
-```yaml
-# my-project/apm.yml
-name: my-project
-
-dependencies:
-  apm:
-    - acme-corp/acme-team-frontend   # pulls in org + team transitively
-    - some-other/project-specific-pkg
-```
-
-After installing:
-
-```bash
-apm install
-```
-
-The project gets the full stack: org-wide standards from `apm-standards`, frontend-specific skills from `frontend-skills`, team configuration from `acme-team-frontend`, and anything from `project-specific-pkg` — all resolved and deployed automatically.
-
-### Override order
-
-When files from different packages target the same path, the most specific package wins:
-
-1. Project-local files (highest priority)
-2. Direct dependencies
-3. Transitive dependencies (lowest priority)
-
-This means a project can always override an org default when it has a legitimate reason to diverge.
-
-## Versioning strategy
-
-### Tagging releases
-
-Use git tags to mark versions of your standards package:
-
-```bash
-# In the standards package repo
-git add -A && git commit -m "Add API design standards"
-git tag v1.0.0
-git push origin main --tags
-```
-
-### Consumer pinning
-
-Consumers reference specific versions to control when they adopt changes:
-
-```yaml
-# Pin to exact version
-dependencies:
-  apm:
-    - acme-corp/apm-standards@v1.0.0
-
-# Pin to major version (gets v1.x.x updates)
-dependencies:
-  apm:
-    - acme-corp/apm-standards@v1
-```
-
-Regardless of the version specifier, `apm.lock.yaml` always pins the exact commit SHA. This guarantees reproducible installs even if the tag is moved.
-
-### When to bump versions
-
-- **Patch** (v1.0.1): Fix typos, clarify wording, add non-breaking examples.
-- **Minor** (v1.1.0): Add new instructions or agents. Existing behavior unchanged.
-- **Major** (v2.0.0): Remove or rename files, change agent behavior, restructure directories.
-
-## Update workflow
-
-### Package author
-
-When updating the standards package:
-
-```bash
-# Make changes to instructions, agents, prompts, or skills
-# ...
-
-# Test before publishing
-apm compile --dry-run
-
-# Commit, tag, push
-git add -A && git commit -m "Tighten input validation policy"
-git tag v1.1.0
-git push origin main --tags
-```
-
-### Consumer
-
-To pick up the latest version within your pinned range:
-
-```bash
-apm deps update
-```
-
-This updates `apm.lock.yaml` to the latest commit matching your version pin and deploys the updated files.
-
-### CI integration
-
-In continuous integration, always use the lock file for reproducible builds:
-
-```bash
-# CI pipeline — installs exact versions from lock file
-apm install
-```
-
-This ensures every CI run uses the same dependency versions, regardless of what has been published since.
-
-## Best practices
-
-**Keep packages focused.** Separate concerns into distinct packages rather than bundling everything into a monolith:
-
-- `acme-corp/security-baseline` — security policies and review agents
-- `acme-corp/coding-standards` — language-specific coding guidelines
-- `acme-corp/review-agents` — standard code review agent configurations
-
-This lets teams adopt what they need without pulling in irrelevant configuration.
-
-**Use semantic versioning for breaking changes.** Consumers rely on version pins to control their upgrade cadence. A surprise rename or deletion in a patch release breaks trust and workflows.
-
-**Document what each package provides.** Include a clear README in every standards package listing the files it deploys and what each one does. Consumers should know what they're getting without reading every file.
-
-**Test before tagging.** Run `apm compile --dry-run` to verify the package compiles cleanly before publishing a new version. Catch issues before they propagate to consumers.
-
-**Start small.** Begin with one focused package — security baseline is a good first choice. Expand to additional packages as patterns emerge. It is easier to split a package later than to merge two that diverged.
-
-**Review changes like code.** Standards packages affect every repo in the org. Treat updates with the same rigor as production code changes — pull requests, reviews, and testing.
diff --git a/docs/src/content/docs/guides/pack-distribute.md b/docs/src/content/docs/guides/pack-distribute.md
deleted file mode 100644
index e0082679f..000000000
--- a/docs/src/content/docs/guides/pack-distribute.md
+++ /dev/null
@@ -1,446 +0,0 @@
----
-title: "Pack & Distribute"
-description: "Bundle resolved dependencies for offline distribution, CI pipelines, and air-gapped environments."
-sidebar:
-  order: 6
----
-
-Bundle your resolved APM dependencies into a portable artifact that can be distributed, cached, and consumed without APM, Python, or network access.
-
-## Why bundles?
-
-Every CI job that runs `apm install` pays the same tax: install APM, authenticate against GitHub, clone N repositories, compile prompts. Multiply that across a matrix of jobs, nightly builds, and staging environments and the cost adds up fast.
-
-A bundle removes all of that. You resolve once, pack the output, and distribute the artifact. Consumers extract it and get the exact files that `apm install` would have produced — no toolchain required.
-
-Common motivations:
-
-- **CI cost reduction** — resolve once, fan out to many jobs
-- **Air-gapped environments** — no network access at deploy time (for environments where CI *can* reach an internal proxy, see [Registry Proxy & Air-gapped](../../enterprise/registry-proxy/) -- bundles are the offline-delivery story; the proxy is the online-routing story)
-- **Reproducibility** — the bundle is a snapshot of exactly what was resolved
-- **Faster onboarding** — new contributors get pre-built context without running install
-- **Audit trail** — attach the bundle to a release for traceability
-
-## The pipeline
-
-The pack/distribute workflow fits between install and consumption:
-
-```
-apm install  ->  apm pack  ->  upload artifact  ->  download  ->  apm unpack (or tar xzf)
-```
-
-The left side (install, pack) runs where APM is available. The right side (download, unpack) runs anywhere — a CI job, a dev container, a colleague's laptop. The bundle is the boundary.
-
-## `apm pack`
-
-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: target-agnostic plugin bundle that installs into any consumer
-apm pack
-
-# Legacy APM bundle layout (consumed by microsoft/apm-action restore)
-apm pack --format apm
-
-# Produce a .tar.gz archive
-apm pack --archive
-
-# Custom output directory (default: ./build)
-apm pack -o ./dist/
-
-# Preview without writing
-apm pack --dry-run
-```
-
-### Options
-
-| 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` | (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 |
-
-### Plugin layout normalization
-
-`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:
-
-```
-.github/skills/my-plugin/SKILL.md  ->  skills/my-plugin/SKILL.md
-.claude/agents/helper.md           ->  agents/helper.md
-```
-
-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
-
-**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.
-
-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`.
-
-`--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.
-
-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 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.
-```
-
-## Plugin format vs APM format
-
-`apm pack` produces one of two output shapes. The default is the plugin format.
-
-| Aspect | Plugin format (default) | APM format (`--format apm`) |
-|---|---|---|
-| 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 | 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) |
-
-Pick `--format apm` when a downstream consumer expects the enriched lockfile and the install-shape directory tree -- in particular `microsoft/apm-action@v1` with `bundle:` (its restore mode reads the bundle's `apm.lock.yaml`). The action exposes `--format apm` end-to-end so existing pack/restore workflows continue unchanged. Otherwise leave the default in place.
-
-## Without APM: what you give up
-
-A plugin bundle works two ways: with APM, or without it. Both are supported. Pick the one that matches the consumer.
-
-| Concern | With APM (`apm install`) | Without APM (host's native plugin loader) |
-|---|---|---|
-| Dependency declaration | `apm.yml` | None - copy the bundle directly |
-| Version locking | `apm.lock.yaml` pins exact commits | None - whatever bytes you copied |
-| Transitive dependencies | Resolved automatically | Not resolved - bundle whatever the author shipped |
-| Governance hooks | `apm install` runs policy + security scans | Trust the source |
-| Security scanning | Built-in: install / compile / unpack block critical findings; `apm audit` for reports | None at install time |
-| Cross-runtime deploy | One install, all detected runtimes | One bundle per host, manually placed |
-| Reproducibility | Same `apm.lock.yaml` -> identical bytes everywhere | Copy-and-pray |
-
-The parallel: `apm install <skill>` is to `npx skills add <skill>` what `npm install` is to `npx`. Both work. The first is reproducible and governed; the second is convenient.
-
-### Where the bundle goes without APM
-
-`apm pack` writes a directory shaped like a standard plugin. The consumer side depends on the host:
-
-- **Claude Code** loads plugins from `~/.claude/plugins/<name>/` (or via a Claude marketplace entry and `/plugin install`). Convention dirs (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`) are picked up automatically.
-- **Other Claude-plugin-compatible hosts** follow their own install steps. The bundle conforms to the [official Claude Code plugin manifest schema](https://json.schemastore.org/claude-code-plugin.json); consult your host's plugin documentation for the install path.
-- **Archive output (`apm pack --archive`)** must be extracted first (`tar xzf <name>-<version>.tar.gz`), then copied into the host's plugin directory.
-
-If your consumer runs APM, none of this applies - declare the package in `apm.yml`, run `apm install`, and APM handles discovery, deployment, locking, and scanning.
-
-## Bundle structure (plugin format, default)
-
-`apm pack` writes to `./build/<name>-<version>/` by default. Convention directories (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`) are auto-discovered by Claude Code, so the synthesized `plugin.json` does NOT emit `agents`/`skills`/`commands`/`instructions` keys for them. Per the [official schema](https://json.schemastore.org/claude-code-plugin.json), those array entries are reserved for `./*.md` paths to *additional* files outside the convention directories.
-
-### Single plugin per repo
-
-```
-build/my-plugin-1.0.0/
-  plugin.json                              # schema-conformant, synthesized from apm.yml
-  agents/
-    architect.agent.md
-  skills/
-    security-scan/
-      SKILL.md
-  commands/
-    review.md
-  instructions/
-    coding-standards.instructions.md
-  hooks.json
-```
-
-`.apm/` source content is remapped into plugin-native paths:
-
-| APM source | Plugin output |
-|---|---|
-| `.apm/agents/*.agent.md` | `agents/*.agent.md` |
-| `.apm/skills/*/SKILL.md` | `skills/*/SKILL.md` |
-| `.apm/prompts/*.prompt.md` | `commands/*.md` |
-| `.apm/prompts/*.md` | `commands/*.md` |
-| `.apm/instructions/*.instructions.md` | `instructions/*.instructions.md` |
-| `.apm/hooks/*.json` | `hooks.json` (merged) |
-| `.apm/commands/*.md` | `commands/*.md` |
-
-Prompt files are renamed: `review.prompt.md` becomes `review.md` in `commands/`.
-
-### `plugin.json` generation
-
-If a `plugin.json` already exists in the project (root, `.github/plugin/`, `.claude-plugin/`, or `.cursor-plugin/`), it is reused. Stale `agents`/`skills`/`commands`/`instructions` keys that point at the convention directories are stripped so the output validates against the schema. Otherwise APM synthesizes one from `apm.yml` metadata.
-
-### Multi-plugin repo (with `marketplace:` block)
-
-When `apm.yml` declares a `marketplace:` block, `apm pack` ALSO emits `.claude-plugin/marketplace.json` aggregating each declared package as a marketplace entry. Curators have two options:
-
-- **Per-plugin `plugin.json` files**: run `apm pack` per subdirectory (each subdirectory has its own `apm.yml`) to produce a schema-conformant `plugin.json` for every plugin.
-- **Marketplace pass-through**: with `strict: false` on entries, the marketplace entry's pass-through fields (`description`, `version`, `author`, ...) stand in for the plugin manifest -- consumers read them directly from `marketplace.json`.
-
-See [Authoring a marketplace](./marketplace-authoring/) for the full schema and build flow.
-
-### `devDependencies` exclusion
-
-Dependencies listed under [`devDependencies`](../../reference/manifest-schema/#5-devdependencies) in `apm.yml` are excluded from the plugin bundle. Use [`apm install --dev`](../../reference/cli-commands/#apm-install---install-dependencies-and-deploy-local-content) to add dev deps:
-
-```bash
-apm install --dev owner/test-helpers
-```
-
-This keeps third-party development-only packages (test helpers, lint rules) out of distributed plugins.
-
-**Caveat for primitives you author yourself:** the dev/prod split is enforced via the lockfile's `is_dev` marker for resolved dependencies. The local-content scanner that ships your own `.apm/` content does NOT consult that marker -- it bundles everything under `.apm/`. To keep maintainer-only primitives (release-checklist skills, internal debugging agents) out of plugin bundles, author them OUTSIDE `.apm/` (e.g. under `dev/`) and reference them via a local-path devDependency. See [Dev-only Primitives](./dev-only-primitives/).
-
-## Bundle structure (APM format, `--format apm`)
-
-`apm pack --format apm` mirrors the directory structure that `apm install` produces. It is not an intermediate format -- extract it at the project root and the files land exactly where they belong. Use this format when a consumer (e.g. `microsoft/apm-action@v1` restore mode) needs the enriched lockfile alongside the deployed files.
-
-### VS Code / Copilot target
-
-```
-build/my-project-1.0.0/
-  .github/
-    prompts/
-      design-review.prompt.md
-      code-quality.prompt.md
-    agents/
-      architect.md
-    skills/
-      security-scan/
-        skill.md
-  apm.lock.yaml                         # enriched copy (see below)
-```
-
-### Claude target
-
-```
-build/my-project-1.0.0/
-  .claude/
-    commands/
-      review.md
-      debug.md
-    skills/
-      code-analysis/
-        skill.md
-  apm.lock.yaml
-```
-
-### All targets
-
-```
-build/my-project-1.0.0/
-  .github/
-    prompts/
-      ...
-    agents/
-      ...
-  .claude/
-    commands/
-      ...
-  .cursor/
-    rules/
-      ...
-    agents/
-      ...
-  .opencode/
-    agents/
-      ...
-    commands/
-      ...
-  apm.lock.yaml
-```
-
-The bundle is self-describing: its `apm.lock.yaml` lists every file it contains and the dependency graph that produced them.
-
-## Lockfile enrichment
-
-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
-  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'
-dependencies:
-  - repo_url: microsoft/apm-sample-package
-    host: github.com
-    resolved_commit: a1b2c3d4
-    resolved_ref: main
-    version: 1.0.0
-    depth: 1
-    package_type: apm
-    deployed_files:
-      - .github/prompts/design-review.prompt.md
-      - .github/agents/architect.md
-```
-
-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
-# Extract and verify
-apm unpack ./build/my-project-1.0.0.tar.gz
-
-# Extract to a specific directory
-apm unpack ./build/my-project-1.0.0.tar.gz -o ./
-
-# Skip integrity check
-apm unpack --skip-verify ./build/my-project-1.0.0.tar.gz
-
-# Preview without writing
-apm unpack ./build/my-project-1.0.0.tar.gz --dry-run
-```
-
-### Options
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `-o, --output` | `.` (current dir) | Target project directory |
-| `--skip-verify` | off | Skip completeness check against lockfile |
-| `--dry-run` | off | List files without writing |
-| `--force` | off | Deploy despite critical hidden-character findings |
-
-### Behavior
-
-- **Additive-only**: `unpack` writes files listed in the bundle's lockfile. It never deletes existing files in the target directory.
-- **Overwrite on conflict**: if a file already exists at the target path, the bundle file wins.
-- **Verification**: by default, `unpack` checks that every path in the bundle's `deployed_files` manifest exists in the bundle before extracting. Pass `--skip-verify` to skip this check for partial bundles.
-- **Lockfile not copied**: the bundle's enriched `apm.lock.yaml` is metadata for verification only — it is not written to the output directory.
-
-## Consumption scenarios
-
-### CI: cross-job artifact sharing
-
-Resolve once in a setup job, fan out to N consumer jobs. No APM installation in downstream jobs. Use `--format apm` so the bundle preserves the `apm install` directory layout that `tar xzf` restores in place.
-
-```yaml
-# .github/workflows/ci.yml
-jobs:
-  setup:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: microsoft/apm-action@v1
-      - run: apm pack --format apm --archive
-      - uses: actions/upload-artifact@v4
-        with:
-          name: apm-bundle
-          path: build/*.tar.gz
-
-  test:
-    needs: setup
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-        with:
-          name: apm-bundle
-          path: ./bundle
-      - run: tar xzf ./bundle/*.tar.gz -C .
-      # Prompts and agents are now in place -- no APM needed
-```
-
-### Agentic workflows
-
-GitHub's agentic workflow runners operate in sandboxed environments with no network access. Pre-pack the bundle (`--format apm --archive`) and include it as a workflow artifact so the agent has full context from the start.
-
-### Release audit trail
-
-Attach the bundle as a release artifact. Anyone auditing the release can inspect exactly which prompts, agents, and skills shipped with that version.
-
-```bash
-apm pack --format apm --archive -o ./release-artifacts/
-gh release upload v1.2.0 ./release-artifacts/*.tar.gz
-```
-
-### Dev Containers and Codespaces
-
-Include a pre-built APM bundle in the dev container image or restore it during `onCreateCommand`. New contributors get working AI context without running `apm install`.
-
-```json
-{
-  "onCreateCommand": "tar xzf .devcontainer/apm-bundle.tar.gz -C ."
-}
-```
-
-### Org-wide distribution
-
-A central platform team maintains the canonical prompt library. Monthly, they run `apm install && apm pack --format apm --archive`, publish the bundle to an internal artifact registry, and downstream repos pull it during CI or onboarding.
-
-## `apm-action` integration
-
-The official [apm-action](https://github.com/microsoft/apm-action) supports pack and restore as first-class modes. The action's restore mode consumes the legacy APM bundle layout, so its pack mode emits `--format apm` by default.
-
-### Pack mode
-
-Generate an APM-format bundle as part of a GitHub Actions workflow:
-
-```yaml
-- uses: microsoft/apm-action@v1
-  with:
-    pack: true        # produces --format apm bundle for restore-mode consumers
-```
-
-### Restore mode
-
-Consume a bundle without installing APM. The action extracts the archive directly:
-
-```yaml
-- uses: microsoft/apm-action@v1
-  with:
-    bundle: ./path/to/bundle.tar.gz
-```
-
-No APM binary, no Python runtime, no network calls. The action handles extraction and verification internally.
-
-## Prerequisites
-
-`apm pack` requires two things:
-
-1. **`apm.lock.yaml`** — the resolved lockfile produced by `apm install`. Pack reads the `deployed_files` manifest from this file to know what to include.
-2. **Installed files on disk** — the actual files referenced in `deployed_files` must exist at their expected paths. Pack verifies this and fails with a clear error if files are missing.
-3. **No local path dependencies** — `apm pack` rejects packages that depend on local filesystem paths (`./path` or `/absolute/path`). Replace local dependencies with remote references before packing.
-
-The typical sequence is:
-
-```bash
-apm install     # resolve dependencies and deploy files
-apm pack        # bundle the deployed files
-```
-
-Pack reads from the lockfile, not from a disk scan. If a file exists on disk but is not listed in `apm.lock.yaml`, it will not be included. If a file is listed in `apm.lock.yaml` but missing from disk, pack will fail and prompt you to re-run `apm install`.
-
-## Troubleshooting
-
-### "apm.lock.yaml not found"
-
-Pack requires a lockfile. Run `apm install` first to resolve dependencies and generate `apm.lock.yaml`.
-
-### "deployed files are missing on disk"
-
-The lockfile references files that do not exist. This usually means dependencies were installed but the files were deleted. Run `apm install` to restore them.
-
-### "bundle verification failed"
-
-During unpack, verification found files listed in the bundle's lockfile that are missing from the bundle itself. The bundle may have been created from a partial install or corrupted during transfer. Re-pack from a clean install, or pass `--skip-verify` if you know the bundle is intentionally partial.
-
-### Empty bundle
-
-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 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.
diff --git a/docs/src/content/docs/guides/package-relative-links.md b/docs/src/content/docs/guides/package-relative-links.md
deleted file mode 100644
index 69b160863..000000000
--- a/docs/src/content/docs/guides/package-relative-links.md
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: "Package-Relative Links"
-description: "How APM handles relative markdown links between primitives and assets inside a package."
-sidebar:
-  order: 10
----
-
-A primitive in your package can link to a sibling asset (another markdown
-file, a guide, a JSON example) using a normal relative markdown link.
-APM keeps those links working after install -- even though primitives are
-deployed to host-tool-specific locations (`.github/instructions/`,
-`.agents/skills/`, `.cursor/rules/`, ...) that no longer match the
-package's authoring layout.
-
-## The pattern
-
-Author your package with relative links as if the layout were preserved:
-
-```
-your-package/
-+-- apm.yml
-+-- .apm/
-|   +-- instructions/
-|       +-- python-style.instructions.md
-+-- standards/
-    +-- pep8.md
-```
-
-```markdown
-<!-- .apm/instructions/python-style.instructions.md -->
----
-applyTo: "**/*.py"
----
-
-# Python style
-
-Follow the [PEP8 reference](../../standards/pep8.md).
-```
-
-After `apm install` in a consumer:
-
-```
-consumer/
-+-- .github/instructions/
-|   +-- python-style.instructions.md   # link rewritten
-+-- apm_modules/
-    +-- <owner>/<package>/             # full package preserved
-        +-- standards/pep8.md
-```
-
-The deployed instruction body now contains a path that points at the
-package's install location:
-
-```markdown
-Follow the [PEP8 reference](../../apm_modules/<owner>/<package>/standards/pep8.md).
-```
-
-The link resolves on disk and the host tool can follow it.
-
-## What gets rewritten
-
-APM rewrites a markdown link at install time when **all** of the
-following hold:
-
-- The link is relative (no `http:`, `mailto:`, scheme, or leading `/`).
-- The resolved target stays inside the source package's root.
-- The target file exists in the package.
-
-Links that fail any of those checks are left untouched. Common cases that
-are intentionally **not** rewritten:
-
-- External URLs (`https://...`) -- already absolute.
-- Fragment-only links (`#section`) -- in-document anchors.
-- Root-absolute paths (`/docs/foo.md`) -- consumer-side, not yours.
-- Paths that escape the package root via `..` -- not yours to ship.
-
-## Why this exists
-
-Different host tools read primitives from different directories. A single
-APM package may ship instructions, prompts, agents, and skills, and each
-type lands at a different destination per target (`copilot`, `claude`,
-`cursor`, `codex`, ...). Without rewriting, a relative link authored
-against the package layout would break the moment a primitive is
-deployed.
-
-The rewrite contract decouples your authoring layout from the host
-tool's deploy layout. You write natural relative links; APM keeps them
-pointing at the right files.
-
-## Tips
-
-- Prefer keeping closely related files inside the same skill bundle
-  (`skills/<name>/`). A skill bundle preserves its internal layout when
-  deployed, so links between files inside the bundle never need
-  rewriting.
-- For cross-bundle references (an instruction pointing at a sibling
-  reference doc, a prompt pointing at a shared template), rely on the
-  install-time rewrite described above.
-- Sanity check after install: open the deployed file under
-  `.github/instructions/` (or the equivalent for your target) and
-  confirm the link points into `apm_modules/`.
diff --git a/docs/src/content/docs/guides/plugins.md b/docs/src/content/docs/guides/plugins.md
deleted file mode 100644
index b497de0de..000000000
--- a/docs/src/content/docs/guides/plugins.md
+++ /dev/null
@@ -1,380 +0,0 @@
----
-title: "Plugins"
-sidebar:
-  order: 4
----
-
-APM treats plugins and packages as the same artifact. Every APM package is plugin-compatible by default: `apm pack` writes a `plugin.json` at the root of the bundle so any plugin host (Claude Code and other Claude-plugin-compatible runtimes) can load it natively.
-
-## Plugin authoring
-
-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
-
-Plugins are packages that contain:
-
-- **Skills** - Reusable agent personas and expertise
-- **Agents** - AI agent definitions
-- **Commands** - Executable prompts and workflows  
-- **Instructions** - Context and guidelines
-
-APM automatically detects plugins with `plugin.json` manifests and synthesizes `apm.yml` from the metadata, treating them identically to other APM packages.
-
-## Installation
-
-Install plugins using the standard `apm install` command:
-
-```bash
-# Install a plugin from GitHub
-apm install owner/repo/plugin-name
-
-# Or add to apm.yml
-dependencies:
-  apm:
-    - anthropics/claude-code-plugins/commit-commands#v1.2.0
-```
-
-## How APM Handles Plugins
-
-When you run `apm install owner/repo/plugin-name`:
-
-1. **Clone** - APM clones the repository to `apm_modules/`
-2. **Detect** - It searches for `plugin.json` in priority order:
-   1. `plugin.json` (root)
-   2. `.github/plugin/plugin.json` (GitHub Copilot format)
-   3. `.claude-plugin/plugin.json` (Claude format)
-   4. `.cursor-plugin/plugin.json` (Cursor format)
-3. **Map Artifacts** - Plugin primitives from the repository root are mapped into `.apm/`:
-   - `agents/` → `.apm/agents/`
-   - `skills/` → `.apm/skills/`
-   - `commands/` → `.apm/prompts/`
-    - `*.md` command files are normalized to `*.prompt.md` for prompt/command integration
-4. **Synthesize** - `apm.yml` is automatically generated from plugin metadata
-5. **Integrate** - The plugin is now a standard dependency with:
-   - Version pinning via `apm.lock.yaml`
-   - Transitive dependency resolution
-   - Conflict detection
-   - Everything else APM packages support
-
-This unified approach means **no special commands needed** — plugins work exactly like any other APM package.
-
-## Plugin Format
-
-A plugin repository contains a `plugin.json` manifest and primitives at the repository root.
-
-### Supported Plugin Structures
-
-APM supports multiple plugin manifest locations to accommodate different platforms:
-
-#### GitHub Copilot Format
-```
-plugin-repo/
-├── .github/
-│   └── plugin/
-│       └── plugin.json   # GitHub Copilot location
-├── agents/
-│   └── agent-name.agent.md
-├── skills/
-│   └── skill-name/
-│       └── SKILL.md
-└── commands/
-    └── command-1.md
-    └── command-2.md
-```
-
-#### Claude Format
-```
-plugin-repo/
-├── .claude-plugin/
-│   └── plugin.json       # Claude location
-├── agents/
-│   └── agent-name.agent.md
-├── skills/
-│   └── skill-name/
-│       └── SKILL.md
-└── commands/
-    └── command-1.md
-    └── command-2.md
-```
-
-#### Root Format
-```
-plugin-repo/
-├── plugin.json           # Root location (checked first)
-├── agents/
-│   └── agent-name.agent.md
-├── skills/
-│   └── skill-name/
-│       └── SKILL.md
-└── commands/
-    └── command-1.md
-    └── command-2.md
-```
-
-#### Cursor Format
-```
-plugin-repo/
-├── .cursor-plugin/
-│   └── plugin.json       # Cursor location
-├── agents/
-│   └── agent-name.md
-├── skills/
-│   └── skill-name/
-│       └── SKILL.md
-└── rules/
-    └── my-rule.mdc
-```
-
-**Priority Order**: APM checks for `plugin.json` in these locations:
-1. `plugin.json` (root)
-2. `.github/plugin/plugin.json`
-3. `.claude-plugin/plugin.json`
-4. `.cursor-plugin/plugin.json`
-
-**Note**: Primitives (agents, skills, commands, instructions) are always located at the repository root, regardless of where `plugin.json` is located.
-
-### plugin.json Manifest
-
-Only `name` is required. `version` and `description` are optional metadata:
-
-```json
-{
-  "name": "Plugin Display Name",
-  "version": "1.0.0",
-  "description": "What this plugin does"
-}
-```
-
-Optional fields:
-
-```json
-{
-  "name": "My Plugin",
-  "version": "1.0.0",
-  "description": "A plugin for APM",
-  "author": "Author Name",
-  "license": "MIT",
-  "repository": "owner/repo",
-  "homepage": "https://example.com",
-  "tags": ["ai", "coding"],
-  "dependencies": [
-    "another-plugin-id"
-  ]
-}
-```
-
-#### Custom component paths
-
-By default APM looks for `agents/`, `skills/`, `commands/`, and `hooks/` directories at the plugin root. You can override these with custom paths using strings or arrays:
-
-```json
-{
-  "name": "my-plugin",
-  "agents": ["./agents/planner.md", "./agents/coder.md"],
-  "skills": ["./skills/analysis", "./skills/review"],
-  "commands": "my-commands/",
-  "hooks": "hooks.json"
-}
-```
-
-- **String** — single directory or file path
-- **Array** — list of directories or individual files
-- For **skills**, directories are preserved as named subdirectories (e.g., `./skills/analysis/` → `.apm/skills/analysis/SKILL.md`)
-- For **agents**, directory contents are flattened into `.apm/agents/` (agents are flat files, not named directories)
-- `hooks` also accepts an inline object: `"hooks": {"hooks": {"PreToolUse": [...]}}`
-
-##### Target-specific hook files
-
-When a package ships hooks for multiple tools, use target-specific filenames so
-each tool receives only its own hooks:
-
-| Filename pattern | Deployed to |
-|---|---|
-| `*-copilot-hooks.json` | GitHub Copilot only |
-| `*-cursor-hooks.json` | Cursor only |
-| `*-claude-hooks.json` | Claude Code only |
-| `*-codex-hooks.json` | Codex CLI only |
-| `*-gemini-hooks.json` | Gemini CLI only |
-| Any other name (e.g. `hooks.json`, `telemetry-hooks.json`) | All targets |
-
-Example directory tree for a multi-target hook package:
-
-```
-my-hooks-pkg/
-  hooks/
-    hooks.json              # deployed to all targets
-    copilot-hooks.json      # Copilot only
-    cursor-hooks.json       # Cursor only
-    claude-hooks.json       # Claude Code only
-```
-
-#### MCP Server Definitions
-
-Plugins can ship MCP servers that are automatically deployed through APM's MCP pipeline. Define servers using `mcpServers` in `plugin.json`:
-
-```json
-{
-  "name": "my-plugin",
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["-y", "my-mcp-server"]
-    },
-    "my-api": {
-      "url": "https://api.example.com/mcp"
-    }
-  }
-}
-```
-
-`mcpServers` supports three forms:
-- **Object** — inline server definitions (as above)
-- **String** — path to a JSON file containing `mcpServers`
-- **Array** — list of JSON file paths (merged, last-wins on name conflicts)
-
-When `mcpServers` is absent, APM auto-discovers `.mcp.json` at the plugin root (then `.github/.mcp.json` as fallback), matching Claude Code's auto-discovery behavior.
-
-Servers with `command` are configured as `stdio` transport; servers with `url` use `http` (or the `type` field if it specifies `sse` or `streamable-http`). All plugin-defined MCP servers are treated as self-defined (`registry: false`).
-
-**Trust model**: Self-defined MCP servers from direct dependencies (depth=1) are auto-trusted. Transitive dependencies require `--trust-transitive-mcp`. See [dependencies.md](../dependencies/#self-defined-servers) for details.
-
-## Examples
-
-### Installing Plugins from GitHub
-
-```bash
-# Install a specific plugin
-apm install anthropics/claude-code-plugins/commit-commands
-
-# With version
-apm install anthropics/claude-code-plugins/commit-commands#v1.2.0
-```
-
-### Adding Multiple Plugins to apm.yml
-
-```yaml
-dependencies:
-  apm:
-    - anthropics/claude-code-plugins/commit-commands#v1.2.0
-    - anthropics/claude-code-plugins/refactor-tools#v2.0
-    - mycompany/internal-standards#main
-```
-
-Then sync and install:
-
-```bash
-apm install
-```
-
-### Version Management
-
-Plugins support all standard APM versioning:
-
-```yaml
-dependencies:
-  apm:
-    # Latest version
-    - owner/repo/plugin
-
-    # Latest from branch
-    - owner/repo/plugin#main
-
-    # Specific tag
-    - owner/repo/plugin#v1.2.0
-
-    # Specific commit  
-    - owner/repo/plugin#abc123
-```
-
-Run `apm install` to download and lock versions in `apm.lock.yaml`.
-
-## Supported Hosts
-
-- **GitHub** - `owner/repo` or `owner/repo/plugin-path`
-- **GitHub** - GitHub URLs or SSH references
-- **Azure DevOps** - `dev.azure.com/org/project/repo`
-
-## Lock File Integration
-
-Plugin versions are automatically tracked in `apm.lock.yaml`:
-
-```yaml
-apm_modules:
-  anthropics/claude-code-plugins/commit-commands:
-    resolved: https://github.com/anthropics/claude-code-plugins/commit-commands#v1.2.0
-    commit: abc123def456789
-```
-
-This ensures reproducible installs across environments.
-
-## Conflict Detection
-
-APM automatically detects:
-
-- Duplicate plugins from different sources
-- Version conflicts between dependencies
-- Missing transitive dependencies
-
-Run with `--verbose` to see dependency resolution details:
-
-```bash
-apm install --verbose
-```
-
-## Compilation
-
-Plugins are automatically compiled during `apm compile`:
-
-```bash
-apm compile
-```
-
-This:
-- Generates `AGENTS.md` from plugin agents
-- Integrates skills into the runtime
-- Includes prompt primitives
-
-## Exporting APM packages as plugins
-
-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
-
-Plugins can be found through:
-- **Marketplaces** -- curated `marketplace.json` indexes browsable with `apm marketplace browse` and searchable with `apm search QUERY@MARKETPLACE`. See the [Marketplaces guide](../marketplaces/) for setup.
-- GitHub repositories (search for repos with `plugin.json`)
-- Organization-specific plugin repositories
-
-Install by name from a registered marketplace:
-
-```bash
-apm install code-review@acme-plugins
-```
-
-APM resolves marketplace entries to Git URLs, so marketplace-installed plugins get full version locking, security scanning, and governance. See [Marketplaces](../marketplaces/) for details.
-
-For direct installs, use the standard `apm install owner/repo/plugin-name` command.
-
-## Troubleshooting
-
-### Plugin Not Detected
-
-If APM doesn't recognize your plugin:
-
-1. Check `plugin.json` exists in one of the checked locations:
-   - `plugin.json` (root)
-   - `.github/plugin/plugin.json` (GitHub Copilot format)
-   - `.claude-plugin/plugin.json` (Claude format)
-   - `.cursor-plugin/plugin.json` (Cursor format)
-2. Verify JSON is valid: `cat plugin.json | jq .`
-3. Ensure `name` field is present (only required field)
-4. Verify primitives are at the repository root (`agents/`, `skills/`, `commands/`)
-
-### Version Resolution Issues
-
-See the [concepts.md](../../introduction/how-it-works/) guide on dependency resolution.
-
-### Custom Hosts / Private Repositories
-
-See [integration-testing.md](../../contributing/integration-testing/) for enterprise setup.
diff --git a/docs/src/content/docs/guides/private-packages.md b/docs/src/content/docs/guides/private-packages.md
deleted file mode 100644
index f274af5fe..000000000
--- a/docs/src/content/docs/guides/private-packages.md
+++ /dev/null
@@ -1,79 +0,0 @@
----
-title: "Private Packages"
-description: "Create and distribute private APM packages within your team or organization."
-sidebar:
-  order: 9
----
-
-A private APM package is just a private git repository with an `apm.yml`. There is no registry and no publish step — make the repo private, grant read access, and `apm install` handles the rest.
-
-## Create the package
-
-```bash
-apm init my-private-package && cd my-private-package
-# add content to .apm/instructions/, .apm/prompts/, etc.
-git init && git add . && git commit -m "Initial package"
-git remote add origin https://github.com/your-org/my-private-package.git
-git push -u origin main
-```
-
-Set the repository to **private** in your git host's settings.
-
-## Install it
-
-Set the appropriate token (see [Authentication](../../getting-started/authentication/)), then install like any public package:
-
-```bash
-export GITHUB_APM_PAT=github_pat_your_token
-apm install your-org/my-private-package
-```
-
-Or declare it in `apm.yml`:
-
-```yaml
-dependencies:
-  apm:
-    - your-org/my-private-package#v1.0.0
-```
-
-For GitLab, Bitbucket, or self-hosted git servers, use the [`git:` object form](../dependencies/) and rely on your [existing git credentials](../../getting-started/authentication/):
-
-```yaml
-dependencies:
-  apm:
-    - git: git@gitlab.com:acme/private-standards.git
-      ref: v1.0.0
-```
-
-Self-hosted servers that use non-default git ports (e.g. Bitbucket Datacenter on SSH port 7999) are supported — specify the port in the URL. Use the `ssh://` form, not SCP shorthand, since `git@host:path` cannot carry a port:
-
-```yaml
-dependencies:
-  apm:
-    - git: ssh://git@bitbucket.example.com:7999/project/repo.git
-      ref: v1.0.0
-    - git: https://git.internal:8443/team/repo.git      # custom HTTPS port
-```
-
-APM reuses the same port across protocols during clone fallback (so `ssh://host:7999/...` falls back to `https://host:7999/...`). If your host serves SSH and HTTPS on different ports and SSH is unreachable, pin the protocol that matches the port you need.
-
-## Share with your team
-
-Every developer needs read access to the private repository and the appropriate token in their environment. For teams, a fine-grained PAT scoped to the organization works well — no write access required.
-
-## Use in CI/CD
-
-Inject the token as a secret:
-
-```yaml
-# GitHub Actions
-- uses: microsoft/apm-action@v1
-  env:
-    GITHUB_APM_PAT: ${{ secrets.GITHUB_APM_PAT }}
-```
-
-See the [CI/CD guide](../../integrations/ci-cd/) for Azure Pipelines and other systems.
-
-## Org-wide private packages
-
-For centrally-maintained standards packages that stay private, see [Org-Wide Packages](../../guides/org-packages/) — the pattern is identical, just keep the repository private and distribute access via your org-scoped token.
diff --git a/docs/src/content/docs/guides/prompts.md b/docs/src/content/docs/guides/prompts.md
deleted file mode 100644
index d33bb7e13..000000000
--- a/docs/src/content/docs/guides/prompts.md
+++ /dev/null
@@ -1,279 +0,0 @@
----
-title: "Prompts"
-sidebar:
-  order: 3
----
-
-Prompts are the building blocks of APM -- focused, reusable AI instructions that accomplish specific tasks. They follow the `.prompt.md` convention and are distributed as shareable packages.
-
-## How Prompts Work in APM
-
-APM treats prompts as deployable artifacts:
-
-1. **Prompts** (`.prompt.md` files) contain AI instructions with parameter placeholders
-2. **Packages** bundle prompts for sharing via `apm publish` and `apm install`
-3. **Deployment** places prompts into well-known directories (e.g., `.github/prompts/`) where tools like GitHub Copilot can discover and use them
-4. **Compilation** resolves parameter placeholders, cross-file references, and link transforms at install time
-
-```bash
-# Deployment flow
-apm install owner/my-prompt-package
-  ↓
-APM compiles .prompt.md files (parameter defaults, link resolution)
-  ↓
-Prompts land in .github/prompts/ for Copilot to discover
-```
-
-## What are Prompts?
-
-A prompt is a single-purpose AI instruction stored in a `.prompt.md` file. Prompts are:
-- **Focused**: Each prompt does one thing well
-- **Reusable**: Can be used across multiple scripts
-- **Parameterized**: Accept inputs to customize behavior
-- **Testable**: Easy to run and validate independently
-
-## Prompt File Structure
-
-Prompts follow the VSCode `.prompt.md` convention with YAML frontmatter:
-
-```markdown
----
-description: Analyzes application logs to identify errors and patterns
-author: DevOps Team
-mcp:
-  - logs-analyzer
-input:
-  - service_name
-  - time_window
-  - log_level
----
-
-# Analyze Application Logs
-
-You are a expert DevOps engineer analyzing application logs to identify issues and patterns.
-
-## Context
-- Service: ${input:service_name}
-- Time window: ${input:time_window}
-- Log level: ${input:log_level}
-
-## Task
-1. Retrieve logs for the specified service and time window
-2. Identify any ERROR or FATAL level messages
-3. Look for patterns in warnings that might indicate emerging issues
-4. Summarize findings with:
-   - Critical issues requiring immediate attention
-   - Trends or patterns worth monitoring
-   - Recommended next steps
-
-## Output Format
-Provide a structured summary with:
-- **Status**: CRITICAL | WARNING | NORMAL
-- **Issues Found**: List of specific problems
-- **Patterns**: Recurring themes or trends
-- **Recommendations**: Suggested actions
-```
-
-## Key Components
-
-### YAML Frontmatter
-- **description**: Clear explanation of what the prompt does
-- **author**: Who created/maintains this prompt
-- **mcp**: Required MCP servers for tool access
-- **input**: Parameters the prompt expects
-
-### Prompt Body
-- **Clear instructions**: Tell the AI exactly what to do
-- **Context section**: Provide relevant background information
-- **Input references**: Use `${input:parameter_name}` for dynamic values
-- **Output format**: Specify how results should be structured
-
-## Input Parameters
-
-Reference script inputs using the `${input:name}` syntax:
-
-```markdown
-## Analysis Target
-- Service: ${input:service_name}
-- Environment: ${input:environment}
-- Start time: ${input:start_time}
-```
-
-### Input formats
-
-The `input:` frontmatter key accepts several formats:
-
-```yaml
-# Simple list (most common)
-input:
-  - service_name
-  - environment
-
-# Object list with descriptions
-input:
-  - service_name: "Name of the service to analyze"
-  - environment: "Target environment (prod, staging)"
-
-# Bare dictionary
-input:
-  service_name: "Name of the service"
-  environment: "Target environment"
-
-# Single string (one parameter)
-input: service_name
-```
-
-### Target-specific mapping
-
-When APM installs a prompt as a Claude Code slash command, it maps `input:` to Claude's native `arguments:` frontmatter. The `${input:name}` references in the prompt body are converted to `$name` placeholders, and an `argument-hint` is auto-generated if one is not already set.
-
-```yaml
-# APM prompt frontmatter
-input:
-  - feature_name
-  - priority
-
-# Becomes Claude command frontmatter
-arguments:
-  - feature_name
-  - priority
-argument-hint: <feature_name> <priority>
-```
-
-This mapping is automatic during `apm install` -- no extra configuration is needed. If you set an explicit `argument-hint:` in the prompt frontmatter, APM preserves it instead of generating one.
-
-## MCP servers in prompts
-
-Prompts can declare MCP server dependencies in their frontmatter under the `mcp:` key (see the deployment-health-check example below). To add an MCP server to your project, see the [MCP Servers guide](../mcp-servers/).
-
-## Writing Effective Prompts
-
-### Be Specific
-```markdown
-# Good
-Analyze the last 24 hours of application logs for service ${input:service_name}, 
-focusing on ERROR and FATAL messages, and identify any patterns that might 
-indicate performance degradation.
-
-# Avoid
-Look at some logs and tell me if there are problems.
-```
-
-### Structure Your Instructions
-```markdown
-## Task
-1. First, do this specific thing
-2. Then, analyze the results looking for X, Y, and Z
-3. Finally, summarize findings in the specified format
-
-## Success Criteria
-- All ERROR messages are categorized
-- Performance trends are identified
-- Clear recommendations are provided
-```
-
-### Specify Output Format
-```markdown
-## Output Format
-**Summary**: One-line status
-**Critical Issues**: Numbered list of immediate concerns
-**Recommendations**: Specific next steps with priority levels
-```
-
-## Example Prompts
-
-### Code Review Prompt
-```markdown
----
-description: Reviews code changes for best practices and potential issues
-author: Engineering Team
-input:
-  - pull_request_url
-  - focus_areas
----
-
-# Code Review Assistant
-
-Review the code changes in pull request ${input:pull_request_url} with focus on ${input:focus_areas}.
-
-## Review Criteria
-1. **Security**: Check for potential vulnerabilities
-2. **Performance**: Identify optimization opportunities  
-3. **Maintainability**: Assess code clarity and structure
-4. **Testing**: Evaluate test coverage and quality
-
-## Output
-Provide feedback in standard PR review format with:
-- Specific line comments for issues
-- Overall assessment score (1-10)
-- Required changes vs suggestions
-```
-
-### Deployment Health Check
-```markdown
----
-description: Verifies deployment success and system health
-author: Platform Team
-mcp:
-  - kubernetes-tools
-  - monitoring-api
-input:
-  - service_name
-  - deployment_version
----
-
-# Deployment Health Check
-
-Verify the successful deployment of ${input:service_name} version ${input:deployment_version}.
-
-## Health Check Steps
-1. Confirm pods are running and ready
-2. Check service endpoints are responding
-3. Verify metrics show normal operation
-4. Test critical user flows
-
-## Success Criteria
-- All pods STATUS = Running
-- Health endpoint returns 200
-- Error rate < 1%
-- Response time < 500ms
-```
-
-## Running Prompts
-
-Prompts can be executed locally using APM's experimental agent workflow system.
-Define scripts in your `apm.yml` or let APM auto-discover `.prompt.md` files as
-runnable workflows.
-
-See the [Agent Workflows guide](../agent-workflows/) for setup instructions,
-runtime configuration, and execution examples.
-
-## Best Practices
-
-### 1. Single Responsibility
-Each prompt should do one thing well. Break complex operations into multiple prompts.
-
-### 2. Clear Naming
-Use descriptive names that indicate the prompt's purpose:
-- `analyze-performance-metrics.prompt.md`
-- `create-incident-ticket.prompt.md`
-- `validate-deployment-config.prompt.md`
-
-### 3. Document Inputs
-Always specify what inputs are required and their expected format:
-
-```yaml
-input:
-  - service_name     # String: name of the service to analyze
-  - time_window      # String: time range (e.g., "1h", "24h", "7d")
-  - severity_level   # String: minimum log level ("ERROR", "WARN", "INFO")
-```
-
-### 4. Version Control
-Keep prompts in version control alongside scripts. Use semantic versioning for breaking changes.
-
-## Next Steps
-
-- Learn about [Agent Workflows](../agent-workflows/) to run prompts locally with AI runtimes
-- See [CLI Reference](../../reference/cli-commands/) for complete command documentation
-- Check [Development Guide](../../contributing/development-guide/) for local development setup
diff --git a/docs/src/content/docs/guides/skills.md b/docs/src/content/docs/guides/skills.md
deleted file mode 100644
index dc1ad037d..000000000
--- a/docs/src/content/docs/guides/skills.md
+++ /dev/null
@@ -1,465 +0,0 @@
----
-title: "Skills"
-sidebar:
-  order: 2
----
-
-APM installs, locks, audits, and deploys skills across runtimes (GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini). It is the package manager for skills, not the spec.
-
-:::note[Authoring a SKILL.md?]
-The `SKILL.md` format - frontmatter rules, body conventions, when to prefer a skill over an instruction or prompt - is defined by the agent-skills spec at <https://agentskills.io>. Treat that as the canonical source. This page covers what APM does *with* skills: distribution, version locking, governance, security scanning, and cross-runtime deployment.
-:::
-
-## What APM does with skills
-
-- **Install** from any git host (`apm install owner/repo/skill-name`).
-- **Lock** the resolved commit in `apm.lock.yaml` so every machine and CI job gets identical bytes.
-- **Audit** for hidden Unicode character findings on every install / compile / unpack (zero config); use `apm audit` for SARIF / JSON / markdown reports.
-- **Deploy** to the right convention directory for each detected runtime (`.claude/skills/`, `.agents/skills/`, `.cursor/`, ...) - see [Routing](#what-happens-during-install) below.
-
-### Two ways to consume a skill
-
-1. **As a dependency of your APM package** - declare it in `apm.yml`, `apm install` resolves and deploys it.
-2. **Bundled inside your own package** - ship a `SKILL.md` (root, single-skill repo) or `.apm/skills/<name>/SKILL.md` (multi-skill layout); APM treats it like any other primitive.
-
-## Installing Skills
-
-### From Claude Skill Repositories
-
-Many Claude Skills are hosted in monorepos. Install any skill directly:
-
-```bash
-# Install a skill from a monorepo subdirectory
-apm install ComposioHQ/awesome-claude-skills/brand-guidelines
-
-# Install skill with resources (scripts, references, etc.)
-apm install ComposioHQ/awesome-claude-skills/skill-creator
-```
-
-## What Happens During Install
-
-When you run `apm install`, APM handles skill integration automatically:
-
-### Step 1: Download to apm_modules/
-APM downloads packages to `apm_modules/owner/repo/` (or `apm_modules/owner/repo/skill-name/` for subdirectory packages).
-
-### Step 2: Skill Integration
-APM copies skills to every detected target directory:
-
-| Package Type | Behavior |
-|--------------|----------|
-| **Has existing SKILL.md** | Entire skill folder copied to `{target}/skills/{skill-name}/` |
-| **Has sub-skills in `.apm/skills/`** | Each `.apm/skills/*/SKILL.md` also promoted to `{target}/skills/{sub-skill-name}/` |
-| **No SKILL.md and no primitives** | No skill folder created |
-
-**Target Detection:**
-- Recognized directories: `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.gemini/`
-- By default, skills for Copilot, Cursor, OpenCode, Codex, and Gemini deploy to the converged `.agents/skills/` directory; Claude deploys to `.claude/skills/` (the only exception)
-- If none exist, `.github/` is created as the fallback
-- Override with `--target`; pass `--legacy-skill-paths` (or set `APM_LEGACY_SKILL_PATHS=1`) to restore per-client skill directories
-
-### Skill Folder Naming
-
-Skill names are validated per the [agentskills.io](https://agentskills.io/) spec:
-- 1-64 characters
-- Lowercase alphanumeric + hyphens only
-- No consecutive hyphens (`--`)
-- Cannot start/end with hyphen
-
-```
-.agents/skills/
-├── mcp-builder/           # From ComposioHQ/awesome-claude-skills/mcp-builder
-└── apm-sample-package/    # From microsoft/apm-sample-package
-```
-
-(Per-client paths like `.github/skills/`, `.cursor/skills/`, etc. apply when `--legacy-skill-paths` is set; Claude always uses `.claude/skills/`.)
-
-### Step 3: Primitive Integration
-APM also integrates prompts and commands from the package (using their original filenames).
-
-### Installation Path Structure
-
-Skills maintain their natural path hierarchy:
-
-```
-apm_modules/
-└── ComposioHQ/
-    └── awesome-claude-skills/
-        └── brand-guidelines/      # Skill subdirectory
-            ├── SKILL.md           # Original skill file
-            ├── apm.yml            # Auto-generated
-            └── LICENSE.txt        # Any bundled files
-```
-
-## SKILL.md Format
-
-### Basic Structure
-
-```markdown
----
-name: Skill Name
-description: One-line description of what this skill does
----
-
-# Skill Body
-
-Detailed instructions for the AI agent on how to use this skill.
-
-## Guidelines
-- Guideline 1
-- Guideline 2
-
-## Examples
-...
-```
-
-### Required Frontmatter
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Display name for the skill |
-| `description` | string | One-line description |
-
-### Body Content
-
-The body contains:
-- **Instructions** for the AI agent
-- **Guidelines** and best practices
-- **Examples** of usage
-- **References** to bundled resources
-
-## Bundled Resources
-
-Skills can include additional resources:
-
-```
-my-skill/
-├── SKILL.md           # Main skill file
-├── scripts/           # Executable code
-│   └── validate.py
-├── references/        # Documentation
-│   └── style-guide.md
-├── examples/          # Sample files
-│   └── sample.json
-└── assets/            # Templates, images
-    └── logo.png
-```
-
-**Note:** All resources stay in `apm_modules/` where AI agents can reference them.
-
-## Creating Your Own Skills
-
-### Quick Start with apm init
-
-`apm init` creates a minimal project:
-
-```bash
-apm init my-skill && cd my-skill
-```
-
-This creates a single file:
-```
-my-skill/
-└── apm.yml       # Package manifest (the only file `apm init` writes)
-```
-
-`apm init` does not scaffold `.apm/` for you. Author the skill yourself: drop a `SKILL.md` at the root for a single-skill repo (Option 1 below), or create `.apm/skills/<name>/SKILL.md` for a multi-skill layout (Options 2-4 below). See [Anatomy of an APM Package](../../introduction/anatomy-of-an-apm-package/) for the full source layout.
-
-### Option 1: Standalone Skill
-
-Create a repo with just `SKILL.md`:
-
-```bash
-mkdir my-skill && cd my-skill
-
-cat > SKILL.md << 'EOF'
----
-name: My Custom Skill
-description: Does something useful
----
-
-# My Custom Skill
-
-## Overview
-Describe what this skill does...
-
-## Guidelines
-- Follow these rules...
-
-## Examples
-...
-EOF
-
-git init && git add . && git commit -m "Initial skill"
-git push origin main
-```
-
-Anyone can now install it:
-```bash
-apm install your-org/my-skill
-```
-
-### Option 2: Skill in APM Package
-
-Add `SKILL.md` to any existing APM package:
-
-```
-my-package/
-├── apm.yml
-├── SKILL.md          # Add this for Claude compatibility
-└── .apm/
-    ├── instructions/
-    └── prompts/
-```
-
-This creates a **hybrid package** that works with both APM primitives and Claude Skills.
-
-### Option 3: Skills Collection (Monorepo)
-
-Organize multiple skills in a monorepo:
-
-```
-awesome-skills/
-├── skill-1/
-│   ├── SKILL.md
-│   └── references/
-├── skill-2/
-│   └── SKILL.md
-└── skill-3/
-    ├── SKILL.md
-    └── scripts/
-```
-
-Users install individual skills:
-```bash
-apm install your-org/awesome-skills/skill-1
-apm install your-org/awesome-skills/skill-2
-```
-
-### Option 4: Multi-skill Package
-
-Bundle multiple skills inside a single APM package using `.apm/skills/`:
-
-```
-my-package/
-├── apm.yml
-├── SKILL.md              # Parent skill (package-level guide)
-└── .apm/
-    ├── instructions/
-    ├── prompts/
-    └── skills/
-        ├── skill-a/
-        │   └── SKILL.md  # Sub-skill A
-        └── skill-b/
-            └── SKILL.md  # Sub-skill B
-```
-
-On install, APM promotes each sub-skill to a top-level `.agents/skills/` entry alongside the parent (or `.claude/skills/` for Claude; or per-client directories under `--legacy-skill-paths`) — see [Sub-skill Promotion](#sub-skill-promotion) below.
-
-### Option 5: Maintainer-only Skill (Dev-only)
-
-For skills you want during authoring but not shipped to consumers (release-checklist skills, internal debugging skills), author them OUTSIDE `.apm/` and reference them via a local-path devDependency:
-
-```
-your-package/
-+-- apm.yml
-+-- .apm/skills/...                          # public skills
-+-- dev/skills/release-checklist/SKILL.md    # maintainer-only
-```
-
-```yaml
-devDependencies:
-  apm:
-    - path: ./dev/skills/release-checklist
-```
-
-`apm install --dev` deploys the skill locally; `apm pack` excludes it from plugin output. See [Dev-only Primitives](../dev-only-primitives/) for the full pattern.
-
-### Sub-skill Promotion
-
-When a package contains sub-skills in `.apm/skills/*/` subdirectories, APM promotes each to a top-level entry in the deployed skills directory (`.agents/skills/` for converged clients, `.claude/skills/` for Claude). This ensures clients can discover sub-skills independently, since they only scan direct children of the skills root.
-
-```
-# Installed package with sub-skills:
-apm_modules/org/repo/my-package/
-├── SKILL.md
-└── .apm/
-    └── skills/
-        └── azure-naming/
-            └── SKILL.md
-
-# Result after install (default routing):
-.agents/skills/
-├── my-package/              # Parent skill
-│   └── SKILL.md
-└── azure-naming/            # Promoted sub-skill
-    └── SKILL.md
-```
-
-The same promotion applies to the project's own `.apm/skills/` directory. When you run `apm install`, skills in your local `.apm/skills/*/` are deployed to the resolved skills root alongside dependency skills. Local skills take priority on collision. The root `SKILL.md` is not treated as a local skill -- it describes the project itself.
-
-## Package Detection
-
-APM automatically detects package types:
-
-| Has | Type | Detection |
-|-----|------|-----------|
-| `apm.yml` only | APM Package | Standard APM primitives |
-| `SKILL.md` only | Claude Skill | Treated as native skill |
-| `hooks/*.json` only | Hook Package | Hook handlers only |
-| Both files | Hybrid Package | Best of both worlds |
-
-## Skill Deployment Routing
-
-By default, APM routes skills to `.agents/skills/` for clients that support the [agentskills.io](https://agentskills.io) standard: **Copilot, Cursor, OpenCode, Codex, and Gemini**. This eliminates redundant copies when targeting multiple clients.
-
-| Client | Skills deploy to | Notes |
-|--------|-----------------|-------|
-| Copilot | `.agents/skills/` | Converged (was `.github/skills/`) |
-| Cursor | `.agents/skills/` | Converged (was `.cursor/skills/`) |
-| OpenCode | `.agents/skills/` | Converged (was `.opencode/skills/`) |
-| Codex | `.agents/skills/` | Already used `.agents/skills/` |
-| Gemini | `.agents/skills/` | Converged (was `.gemini/skills/`) |
-| Claude | `.claude/skills/` | Unchanged (native routing) |
-| `agent-skills` | `.agents/skills/` | Explicit cross-client target |
-
-With `--target all`, skills deploy to 2 unique directories: `.agents/skills/` and `.claude/skills/`.
-
-### Legacy per-client routing
-
-To restore the previous behavior where each client gets its own skill directory, pass `--legacy-skill-paths` or set the `APM_LEGACY_SKILL_PATHS=1` environment variable:
-
-```bash
-apm install --target all --legacy-skill-paths
-# Skills deploy to .github/skills/, .claude/skills/, .cursor/skills/, etc.
-```
-
-### Cross-client deployment (`agent-skills`)
-
-Use `--target agent-skills` to deploy skills to `.agents/skills/` without tying them to a specific client. This is the [agentskills.io](https://agentskills.io) standard directory that Codex, and other tools read from.
-
-```bash
-# Project-scope deploy
-apm install --target agent-skills
-# Result: .agents/skills/<package-name>/SKILL.md
-
-# User-scope deploy
-apm install -g --target agent-skills
-# Result: ~/.agents/skills/<package-name>/SKILL.md
-```
-
-`agent-skills` is **not** included in `--target all` because it is a cross-client deploy location, not a single client. Combine explicitly: `--target all,agent-skills`.
-
-Override with:
-```bash
-apm install skill-name --target claude
-apm compile --target claude
-```
-
-Or set in `apm.yml`:
-```yaml
-name: my-project
-target: vscode  # or claude, or all
-```
-
-### Migrating from legacy paths
-
-When you upgrade APM and run `apm install`, the tool automatically detects legacy per-client skill paths (`.github/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.gemini/skills/`) recorded in your `apm.lock.yaml` and migrates them to `.agents/skills/`:
-
-```
-[i] Detected legacy per-client skill paths in apm.lock.yaml.
-[i] Migrating to the .agents/skills/ convention:
-[*]   .github/skills/foo  -> .agents/skills/foo
-[*]   .cursor/skills/foo  -> .agents/skills/foo  (deduped)
-```
-
-The migration is automatic and idempotent. Files not tracked in the lockfile are never touched. Use `--legacy-skill-paths` (or `APM_LEGACY_SKILL_PATHS=1`) to skip migration and keep per-client paths.
-
-## Best Practices
-
-### 1. Clear Naming
-Use descriptive, lowercase-hyphenated names:
-- `[+]` `brand-guidelines`
-- `[+]` `code-review-expert`
-- `[x]` `mySkill`
-- `[x]` `Skill_1`
-
-### 2. Focused Description
-Keep the description to one line:
-- `[+]` `Applies corporate brand colors and typography`
-- `[x]` `This skill helps you with branding and it can also do typography and it uses the company colors...`
-
-### 3. Structured Body
-Organize with clear sections:
-```markdown
-## Overview
-What this skill does
-
-## Guidelines
-Rules to follow
-
-## Examples
-How to use it
-
-## References
-Links to resources
-```
-
-### 4. Resource Organization
-Keep bundled files organized:
-```
-my-skill/
-├── SKILL.md
-├── scripts/      # Executable code only
-├── references/   # Documentation
-├── examples/     # Sample files
-└── assets/       # Static resources
-```
-
-### 5. Version Control
-Keep skills in version control. Use semantic versioning in the generated `apm.yml` for tracking.
-
-## Integration with Other Primitives
-
-Skills complement other APM primitives:
-
-| Primitive | Purpose | Works With Skills |
-|-----------|---------|-------------------|
-| Instructions | Coding standards | Skills can reference instruction context |
-| Prompts | Executable workflows | Skills describe how to use prompts |
-| Agents | AI personalities | Skills explain what agents are available |
-| Context | Project knowledge | Skills can link to context files |
-
-## Troubleshooting
-
-### Skill Not Installing
-
-```
-Error: Could not find SKILL.md or apm.yml
-```
-
-**Solution:** Verify the path is correct. For subdirectories, use full path:
-```bash
-apm install owner/repo/subdirectory
-```
-
-### Skill Name Validation Error
-
-If you see a skill name validation warning:
-
-1. **Check naming:** Names must be lowercase, 1-64 chars, hyphens only (no underscores)
-2. **Auto-normalization:** APM automatically normalizes invalid names when possible
-
-### Metadata Missing
-
-If skill lacks APM metadata:
-
-1. Check the skill was installed via APM (not manually copied)
-2. Reinstall the package
-
-## Related Documentation
-
-- [Core Concepts](../../introduction/how-it-works/) - Understanding APM architecture
-- [Primitives Guide](../../introduction/key-concepts/) - All primitive types
-- [CLI Reference](../../reference/cli-commands/) - Full command documentation
-- [Dependencies](../dependencies/) - Package management
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index ad5c36298..4cedc2d20 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -1,13 +1,13 @@
 ---
-title: APM – Agent Package Manager
-description: An open-source dependency manager for AI agents. Declare the skills, prompts, instructions, and tools your project needs in one manifest.
+title: APM - Agent Package Manager
+description: A dependency manager for AI agents. Declare the skills, prompts, instructions, plugins, and MCP servers your project needs in one apm.yml.
 template: splash
 hero:
   title: Agent Package Manager
-  tagline: <strong>Same AI coding superpowers. Every developer. By default.</strong>
+  tagline: A dependency manager for AI agents -- like npm for agent context.
   actions:
-    - text: Get Started
-      link: /apm/getting-started/quick-start/
+    - text: Quickstart
+      link: /apm/quickstart/
       icon: right-arrow
       variant: primary
     - text: View on GitHub
@@ -18,89 +18,86 @@ hero:
 
 import { Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
 
-**An open-source dependency manager for AI agents.** Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
-
-AI coding agents need context and capabilities to be useful — instructions, skills, prompts, plugins, MCP servers. But today every developer configures theirs differently. Nothing is portable. Nothing is reproducible. Nothing is governed.
-
-APM fixes this. You declare your project's agent configuration once in `apm.yml` — and every developer who clones your repo gets a fully configured agent setup in seconds, locked to exact versions, scanned for hidden threats, and gated by the policies your organization defines.
+APM is a dependency manager for AI agents. Declare the skills, prompts, instructions, plugins, and MCP servers your project needs in one `apm.yml`, then any developer runs `apm install` and gets the same agent context across GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini, and Windsurf.
 
 <CardGrid>
   <Card title="Portable by manifest" icon="document">
-    One `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers. Transitive dependencies resolve like npm or pip; `apm.lock.yaml` pins exact versions for reproducible installs across Copilot, Claude Code, Cursor, OpenCode, Codex, and Gemini.
+    One `apm.yml`, every harness, every machine. The lockfile pins exact versions and content hashes so a fresh clone reproduces the same agent setup byte-for-byte.
   </Card>
   <Card title="Secure by default" icon="approve-check-circle">
-    Skills, prompts, instructions, hooks — everything agents execute is an attack surface. `apm install` scans packages for hidden Unicode and other tampering before they reach your agents; `apm audit` reports the full chain of trust.
+    Every install scans for hidden Unicode, pins content hashes, and gates transitive MCP servers behind explicit trust prompts. No opt-in required.
   </Card>
   <Card title="Governed by policy" icon="setting">
-    `apm-policy.yml` lets platform teams allow-list dependencies, restrict deploy targets, and enforce trust rules at install time — across every repo, from a single source of truth. See the [Governance Guide](/apm/enterprise/governance-guide/).
-  </Card>
-  <Card title="Any git host" icon="github">
-    Install from GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, or any self-hosted git server. No registry to run, no central service to depend on.
+    `apm-policy.yml` is enforced at install time, including transitive MCP. Tighten-only inheritance flows enterprise -> org -> repo. See the [Governance Guide](/apm/enterprise/governance-guide/).
   </Card>
 </CardGrid>
 
-## Quick Start
+## Install APM
 
-<Tabs>
-  <TabItem label="macOS / Linux">
+<Tabs syncKey="os">
+  <TabItem label="macOS / Linux" icon="apple">
     ```bash
     curl -sSL https://aka.ms/apm-unix | sh
     ```
   </TabItem>
-  <TabItem label="Windows">
+  <TabItem label="Windows" icon="seti:windows">
     ```powershell
     irm https://aka.ms/apm-windows | iex
     ```
   </TabItem>
 </Tabs>
 
-Then add packages to your project:
+Then try it on a sample package:
 
 ```bash
 apm install microsoft/apm-sample-package
-apm install anthropics/skills/skills/frontend-design
 ```
 
-## Example: apm.yml
+## The manifest
 
 ```yaml
-# apm.yml — ships with your project, like package.json
-name: your project
+# apm.yml -- ships with your repo, like package.json
+name: my-project
 version: 1.0.0
 dependencies:
   apm:
-    # Skills from any GitHub repository
+    # Skills, prompts, agents, plugins -- from any GitHub repo, with version pinning
     - anthropics/skills/skills/frontend-design
-    - microsoft/GitHub-Copilot-for-Azure/plugin/skills/azure-compliance
-    # A full package with rules, skills, prompts, hooks...
     - microsoft/apm-sample-package
-    # Plugins
     - github/awesome-copilot/plugins/context-engineering#v2.1
-    # Agents
     - github/awesome-copilot/agents/api-architect.agent.md
-    # GitLab, Azure DevOps, any git host — with version pinning
+    # GitLab, Azure DevOps, Bitbucket, Gitea, any git server
     - git: https://gitlab.com/acme/coding-standards.git
       path: instructions/security
       ref: v2.0
-    - git: dev.azure.com/org/project/repo
-      path: prompts/review.prompt.md
+    - dev.azure.com/acme/platform/_git/prompts/review.prompt.md
+    - bitbucket.org/team/agent-rules#main
+  mcp:
+    # MCP servers governed by the same manifest
+    - io.github.github/github-mcp-server
+    - io.github.microsoft/playwright-mcp
 ```
 
-New developer joins the team:
-
 ```bash
-git clone <org/repo> && cd <repo> && apm install
+git clone <repo> && cd <repo> && apm install
 ```
 
-**That's it.** Copilot, Claude, Cursor, OpenCode, Codex, Gemini — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
-
-## Open Source & Community
+That's it. Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf -- every harness configured in one command, every dependency pinned, every MCP server policy-checked before it touches disk.
 
-APM is an open-source, MIT-licensed community project under the [`microsoft`](https://github.com/microsoft) org. It's early days — the tool is evolving fast, shaped by developers building real agent workflows. We ship frequently, welcome contributions, and value feedback over perfection.
+## Pick your path
 
-Built on the standards the community has already adopted:
-[AGENTS.md](https://agents.md) · [Agent Skills](https://agentskills.io) · [MCP](https://modelcontextprotocol.io)
+<CardGrid>
+  <Card title="Use a package" icon="rocket">
+    Install someone else's primitives and run them on your harness. Start in the [consumer ramp](/apm/consumer/).
+  </Card>
+  <Card title="Author and publish" icon="open-book">
+    Build skills, prompts, plugins, or full packages others can install. Start in the [producer ramp](/apm/producer/).
+  </Card>
+  <Card title="Govern at fleet scale" icon="setting">
+    Policy, audit, and CI gating across the org. Start in the [enterprise ramp](/apm/enterprise/).
+  </Card>
+</CardGrid>
 
 ---
 
-*We've enforced dependency management on code for decades. It was only a matter of time before AI agents needed it too.*
+APM is open source under the [microsoft](https://github.com/microsoft/apm) org, MIT-licensed. Built on [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io), [MCP](https://modelcontextprotocol.io). See the [changelog](https://github.com/microsoft/apm/blob/main/CHANGELOG.md) for what shipped recently.
diff --git a/docs/src/content/docs/integrations/ci-cd.md b/docs/src/content/docs/integrations/ci-cd.md
index ad712be6d..2a91a710d 100644
--- a/docs/src/content/docs/integrations/ci-cd.md
+++ b/docs/src/content/docs/integrations/ci-cd.md
@@ -33,7 +33,7 @@ jobs:
 
 ### Private Dependencies
 
-For private repositories, pass a token via the workflow `env:` block. See the [Authentication guide](../../getting-started/authentication/) for all supported tokens and priority rules.
+For private repositories, pass a token via the workflow `env:` block. See the [Authentication guide](../../consumer/authentication/) for all supported tokens and priority rules.
 
 ```yaml
       - name: Install APM packages
@@ -68,7 +68,7 @@ This step is not needed if your team only uses GitHub Copilot and Claude, which
         run: apm audit --ci
 ```
 
-This single command runs the seven baseline lockfile checks PLUS integration
+This single command runs the eight baseline lockfile checks PLUS integration
 drift detection (default-on) AND replays
 the install pipeline into a scratch tree to detect missed `apm install`
 runs, hand-edited deployed files, and orphaned files. See the
@@ -133,7 +133,7 @@ jobs:
         # Do not set ADO_APM_PAT -- APM picks up the az session.
 ```
 
-See [Authentication: AAD bearer tokens](../../getting-started/authentication/#authenticating-with-microsoft-entra-id-aad-bearer-tokens) for resolution precedence and verbose output.
+See [Azure DevOps AAD bearer tokens](../../enterprise/security/#azure-devops-aad-bearer-tokens) for resolution precedence and verbose output.
 
 ## General CI
 
@@ -148,7 +148,7 @@ apm install
 
 ## Governance with `apm audit`
 
-`apm audit --ci` verifies lockfile consistency in CI (7 baseline checks plus integration drift detection, no configuration). Add `--policy org` to enforce organizational rules (17 additional checks). For full setup including SARIF integration and GitHub Code Scanning, see the [CI Policy Enforcement guide](../../guides/ci-policy-setup/).
+`apm audit --ci` verifies lockfile consistency in CI (8 baseline checks plus integration drift detection, no configuration). Add `--policy org` to enforce organizational rules (17 additional checks). For full setup including SARIF integration and GitHub Code Scanning, see the [CI Policy Enforcement guide](../../guides/ci-policy-setup/).
 
 For content scanning and hidden Unicode detection, `apm install` automatically blocks critical findings. Run `apm audit` for on-demand reporting. See [Governance](../../enterprise/governance-guide/) for the full governance model.
 
diff --git a/docs/src/content/docs/integrations/gh-aw.md b/docs/src/content/docs/integrations/gh-aw.md
index 32863289b..f5de9a570 100644
--- a/docs/src/content/docs/integrations/gh-aw.md
+++ b/docs/src/content/docs/integrations/gh-aw.md
@@ -144,5 +144,5 @@ For details on what APM detects, see [Content scanning](../../enterprise/securit
 - [gh-aw Documentation](https://github.github.com/gh-aw/)
 - [gh-aw Frontmatter Reference](https://github.github.com/gh-aw/reference/frontmatter/)
 - [APM Compilation Guide](../../guides/compilation/)
-- [APM CLI Reference](../../reference/cli-commands/)
+- [APM CLI Reference](../../reference/cli/install/)
 - [CI/CD Integration](../ci-cd/)
diff --git a/docs/src/content/docs/integrations/github-rulesets.md b/docs/src/content/docs/integrations/github-rulesets.md
index 448981d84..f6bed6f3b 100644
--- a/docs/src/content/docs/integrations/github-rulesets.md
+++ b/docs/src/content/docs/integrations/github-rulesets.md
@@ -7,6 +7,11 @@ sidebar:
 
 GitHub Rulesets and branch protection rules can require status checks before merging. APM commands like `apm install`, `apm compile`, and `apm unpack` already block critical hidden-character findings automatically. `apm audit` adds structured reporting (SARIF, JSON, markdown) and exit codes (**0** = clean, **1** = critical, **2** = warnings) for CI integration. `apm audit --ci` verifies lockfile consistency, and `--policy org` enforces organizational rules.
 
+> Note: `apm unpack` is DEPRECATED and scheduled for removal in v0.14.
+> New pipelines should use `apm install <bundle-path>` instead -- it
+> applies the same content scanning and integrates with the project
+> lockfile. See [Pack and distribute](../../guides/pack-distribute/).
+
 ## How It Works
 
 The workflow is straightforward:
diff --git a/docs/src/content/docs/integrations/ide-tool-integration.md b/docs/src/content/docs/integrations/ide-tool-integration.md
index 555a9d210..7acdc4e12 100644
--- a/docs/src/content/docs/integrations/ide-tool-integration.md
+++ b/docs/src/content/docs/integrations/ide-tool-integration.md
@@ -1,703 +1,137 @@
 ---
-title: "IDE & Tool Integration"
+title: "IDE & tool integration"
+description: "How APM deploys primitives into VS Code, Claude Code, Cursor, Codex, Gemini, OpenCode, Windsurf and other AI coding clients."
 sidebar:
   order: 3
 ---
 
-APM is designed to work seamlessly with your existing development tools and workflows. This guide covers integration patterns, supported AI runtimes, and compatibility with popular development tools.
+APM ships agent context (instructions, prompts, agents, skills, MCP servers) into the directories your AI coding tools read at runtime. Each tool has its own slot layout; APM detects which slots exist and writes the right files in the right places.
 
-## APM + Spec-kit Integration
+This page is a hub. It tells you which tools are supported, how detection works, and where to read the per-tool details.
 
-APM manages the **context foundation** and provides **advanced context management** for software projects. It works exceptionally well alongside [Spec-kit](https://github.com/github/spec-kit) for specification-driven development, as well as with other AI Native Development methodologies like vibe coding.
+## Supported tools
 
-### APM: Context Foundation
+The full slot-by-slot capability table lives in [Targets matrix](../reference/targets-matrix/). At a glance, APM currently writes for:
 
-APM provides the infrastructure layer for AI development:
+| Target               | Marker / signal                     | Notes                                  |
+|----------------------|--------------------------------------|----------------------------------------|
+| VS Code + Copilot    | `.github/copilot-instructions.md`    | Native instructions, prompts, agents   |
+| Claude Code          | `.claude/`                           | Skills, agents, commands, MCP          |
+| Cursor               | `.cursor/`                           | Rules, commands, MCP                   |
+| Codex CLI            | `.codex/`                            | Skills, MCP                            |
+| Gemini CLI           | `.gemini/` or `GEMINI.md`            | Single-file or distributed             |
+| OpenCode             | `.opencode/`                         | Skills, MCP                            |
+| Windsurf             | `.windsurf/`                         | Rules + MCP (lossy agent->skill)       |
+| Agent-Skills (cross) | `.agents/skills/`                    | Vendor-neutral skill sharing           |
 
-- **Context Packaging**: Bundle project knowledge, standards, and patterns into reusable modules
-- **Dynamic Loading**: Smart context composition based on file patterns and current tasks
-- **Performance Optimization**: Optimized context delivery for large, complex projects
-- **Memory Management**: Strategic LLM token usage across conversations
+For exact per-target capabilities (which primitives are supported, transformer used, file layout), see [Targets matrix](../reference/targets-matrix/).
 
-### Spec-kit: Specification Layer
+## How target detection works
 
-When using Spec-kit for Specification-Driven Development (SDD), APM automatically integrates the Spec-kit constitution:
-
-- **Constitution Injection**: When using `apm compile`, APM injects the Spec-kit `constitution.md` into the compiled instruction files (`AGENTS.md`)
-- **Rule Enforcement**: All coding agents respect the non-negotiable rules governing your project
-- **Contextual Augmentation**: Compiled output embeds your team's context modules after Spec-kit's constitution
-- **SDD Enhancement**: Augments the Spec Driven Development process with additional context curated by your teams
-
-### Integrated Workflow
-
-```bash
-# 1. Set up APM contextual foundation
-apm init my-project && apm install
-
-# 2. Optional: compile for Codex/OpenCode instructions, Gemini, etc.
-# Spec-kit constitution is automatically included in compiled AGENTS.md
-apm compile
-
-# 3. AI workflows use both SDD rules and team context
-```
-
-**Key Benefits of Integration**:
-- **Universal Context**: APM grounds any coding agent on context regardless of workflow
-- **SDD Compatibility**: Perfect for specification-driven development approaches
-- **Flexible Workflows**: Also works with traditional prompting and vibe coding
-- **Team Knowledge**: Combines constitutional rules with team-specific context
-
-## Running Agentic Workflows
-
-For running agentic workflows locally, see the [Agent Workflows guide](../../guides/agent-workflows/).
-
-> **User-scope deployment**: `apm install -g` deploys primitives to user-level directories (`~/.copilot/`, `~/.claude/`, etc.), making packages available across all projects. See [Global Installation](../../guides/dependencies/#global-user-scope-installation) for per-target coverage. For Microsoft 365 Copilot Cowork custom skills, enable `copilot-cowork` with `apm experimental enable copilot-cowork` and use `apm install --target copilot-cowork --global`. See [Microsoft 365 Copilot Cowork](../copilot-cowork/).
-
-## VS Code Integration
-
-APM works natively with VS Code's GitHub Copilot implementation.
-
-> **Auto-Detection**: VS Code integration is automatically enabled when a `.github/` folder exists in your project. If neither `.github/` nor `.claude/` exists, `apm install` skips folder integration (packages are still installed to `apm_modules/`). To force integration regardless of folder presence, pass an explicit target (e.g. `apm install --target copilot`) or set `target:` in `apm.yml` -- the target's root folder will be created automatically.
-
-### Native VS Code Primitives
-
-VS Code implements core primitives for GitHub Copilot that APM integrates with:
-
-- **Agents**: AI personas and workflows with `.agent.md` files in `.github/agents/` (legacy: `.chatmode.md` in `.github/chatmodes/`)
-- **Instructions Files**: Modular instructions with `copilot-instructions.md` and `.instructions.md` files
-- **Prompt Files**: Reusable task templates with `.prompt.md` files in `.github/prompts/`
-- **Skills**: Structured capabilities with `SKILL.md` deployed to `.agents/skills/` (the converged cross-client default; per-client `.github/skills/` available via `--legacy-skill-paths` or `APM_LEGACY_SKILL_PATHS=1`)
-
-> **Note**: APM supports both the new `.agent.md` format and legacy `.chatmode.md` format. VS Code provides Quick Fix actions to migrate from `.chatmode.md` to `.agent.md`.
-
-### Automatic Prompt and Agent Integration
-
-APM automatically integrates prompts and agents from installed packages into VS Code's native structure:
-
-```bash
-# Install APM packages - integration happens automatically when .github/ exists
-apm install microsoft/apm-sample-package
-
-# Prompts are automatically integrated to:
-# .github/prompts/*.prompt.md (verbatim copy, original filename preserved)
-
-# Agents are automatically integrated to:
-# .github/agents/*.agent.md (verbatim copy)
-
-# Instructions are automatically integrated to:
-# .github/instructions/*.instructions.md (verbatim copy, original filename)
-
-# Hooks are automatically integrated to:
-# .github/hooks/*.json (hook definitions with rewritten script paths)
-```
-
-**How Auto-Integration Works**:
-- **Zero-Config**: Always enabled, works automatically with no configuration needed
-- **Auto-Cleanup**: Removes integrated files when you uninstall or prune packages (tracked via `deployed_files` in `apm.lock.yaml`)
-- **Collision Detection**: If a local file has the same name as a package file, APM skips it with a warning (use `--force` to overwrite)
-- **Always Overwrite**: Package-owned files are always copied fresh -- no version comparison
-- **Link Resolution**: Context links are resolved during integration
-
-**Integration Flow**:
-1. Run `apm install` to fetch APM packages
-2. APM automatically creates `.github/prompts/`, `.github/agents/`, `.github/instructions/`, and `.github/hooks/` directories as needed
-3. Discovers `.prompt.md`, `.agent.md`, `.instructions.md`, and hook `.json` files in each package
-4. Copies prompts to `.github/prompts/` with their original filename (e.g., `accessibility-audit.prompt.md`)
-5. Copies agents to `.github/agents/` with their original filename (e.g., `security.agent.md`)
-6. Copies instructions to `.github/instructions/` with their original filename (e.g., `python.instructions.md`)
-7. Copies hooks to `.github/hooks/` with their original filename and copies referenced scripts
-8. If a local file already exists with the same name, skips with a warning (use `--force` to overwrite)
-9. Records all deployed files in `apm.lock.yaml` under `deployed_files` per package
-10. VS Code automatically loads all prompts, agents, instructions, and hooks for your coding agents
-11. Run `apm uninstall` to automatically remove integrated primitives (using `deployed_files` manifest)
-
-**Intent-First Discovery**:
-Files keep their original names for natural autocomplete in VS Code:
-- Type `/design` -- VS Code shows `design-review.prompt.md`
-- Type `/accessibility` -- VS Code shows `accessibility-audit.prompt.md`
-- Search by what you want to do, not where it comes from
-
-**Example**: 
-```bash
-# Install package with auto-integration
-apm install microsoft/apm-sample-package
-
-# Result in VS Code:
-# Prompts:
-# .github/prompts/accessibility-audit.prompt.md  - Available in chat
-# .github/prompts/design-review.prompt.md        - Available in chat
-# .github/prompts/style-guide-check.prompt.md    - Available in chat
-
-# Agents:
-# .github/agents/design-reviewer.agent.md        - Available as chat mode
-# .github/agents/accessibility-expert.agent.md   - Available as chat mode
-
-# Instructions:
-# .github/instructions/python.instructions.md    - Applied to matching files
-
-# Use with natural autocomplete:
-# Type: /design
-# VS Code suggests: design-review.prompt.md
-```
-
-**VS Code Native Features**:
-- All integrated prompts appear in VS Code's prompt picker
-- All integrated agents appear in VS Code's chat mode selector
-- Native chat integration with primitives
-- Seamless `/prompt` command support
-- File-pattern based instruction application
-- Agent support for different personas and workflows
-
-### Optional: Compiled Context with AGENTS.md
-
-For tools that do not support granular primitive discovery, `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode and Codex also read `AGENTS.md`, so run `apm compile` to deploy instructions there.
-
-```bash
-# Compile all local and dependency instructions into AGENTS.md
-apm compile --target copilot
-
-# Default distributed compilation creates focused AGENTS.md files per directory
-# Use --single-agents for a single monolithic file (legacy mode)
-apm compile --single-agents
-```
-
-AGENTS.md aggregates instructions, context, and optionally the Spec-kit constitution into a single document that GitHub Copilot reads as project-level guidance.
-
-## Claude Integration
-
-APM provides first-class support for Claude Code and Claude Desktop through native format generation.
-
-> **Auto-Detection**: Claude integration is automatically enabled when a `.claude/` folder exists in your project. If neither `.github/` nor `.claude/` exists, `apm install` skips folder integration (packages are still installed to `apm_modules/`). To force integration regardless of folder presence, pass an explicit target (e.g. `apm install --target claude`) or set `target: claude` in `apm.yml` -- `.claude/` will be created automatically.
-
-> **User-scope `CLAUDE_CONFIG_DIR`**: At user scope (`apm install -g --target claude`), APM honors the `CLAUDE_CONFIG_DIR` environment variable that Claude Code itself reads. If set (and inside `$HOME`), primitives deploy to that directory instead of `~/.claude/`. Values outside `$HOME` are not normalized.
-
-### Optional: Compiled Output for Claude
-
-Running `apm compile` is optional for Claude Code, which reads deployed primitives natively via `apm install`. If you want a single `CLAUDE.md` instruction file (for example, for Claude Desktop), you can generate one:
-
-| File | Purpose |
-|------|---------|
-| `CLAUDE.md` | Merged project instructions for Claude (instructions only, using `@import` syntax) |
-
-When you run `apm install`, APM integrates package primitives into Claude's native structure:
-
-| Location | Purpose |
-|----------|---------|
-| `.claude/rules/*.md` | Instructions converted to Claude rules format (`applyTo:` mapped to `paths:` frontmatter) |
-| `.claude/agents/*.md` | Sub-agents from installed packages (from `.agent.md` files) |
-| `.claude/commands/*.md` | Slash commands from installed packages (from `.prompt.md` files) |
-| `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
-| `.claude/settings.json` (hooks key) | Hooks from installed packages (merged into settings) |
-
-### OpenCode (`.opencode/`)
-
-APM natively integrates with OpenCode when a `.opencode/` directory exists in your project. Run `apm install` and APM automatically deploys primitives to OpenCode's native format:
-
-| APM Primitive | OpenCode Destination | Format |
-|---|---|---|
-| Agents (`.agent.md`) | `.opencode/agents/*.md` | Markdown with YAML frontmatter |
-| Prompts (`.prompt.md`) | `.opencode/commands/*.md` | Converted to command format |
-| Skills (`SKILL.md`) | `.agents/skills/{name}/SKILL.md` | Identical (agentskills.io standard; converged from `.opencode/skills/`) |
-| MCP servers | `opencode.json` | `mcp` key with `command` array, `environment` |
-| Instructions | Via `AGENTS.md` | Read natively by OpenCode |
-
-**Setup**: Create a `.opencode/` directory in your project root, then run `apm install`. APM detects the directory and deploys automatically. OpenCode reads `AGENTS.md` natively for instructions.
-
-> **Note**: OpenCode does not support hooks.
-
-#### Cursor (`.cursor/`)
-
-| Location | Purpose |
-|----------|---------|
-| `.cursor/rules/*.mdc` | Instructions converted to Cursor rules format |
-| `.cursor/agents/*.md` | Sub-agents from installed packages |
-| `.cursor/commands/*.md` | Slash commands from installed packages (from `.prompt.md` files). Files are deployed when `.cursor/` exists. Frontmatter is normalized to the common Claude-compatible subset (`description`, `allowed-tools`, `model`, `argument-hint`, `input`); Cursor-specific keys (`author`, `mcp`, `parameters`, ...) are dropped with an install-time warning per file. **Lifecycle note:** Cursor 1.6+ only. Cursor is de-emphasizing commands in favor of rules and skills -- monitor [Cursor release notes](https://cursor.com/changelog) for changes to this surface. |
-| `.agents/skills/{name}/SKILL.md` | Skills from installed packages (converged from `.cursor/skills/`) |
-| `.cursor/hooks.json` (hooks key) | Hooks from installed packages (merged into config) |
-| `.cursor/hooks/{pkg}/` | Referenced hook scripts |
-| `.cursor/mcp.json` | MCP server configurations |
-
-#### Codex CLI (`.codex/`)
-
-| APM Primitive | Codex Destination | Format |
-|---|---|---|
-| Skills (`SKILL.md`) | `.agents/skills/{name}/SKILL.md` | Identical (agentskills.io standard) |
-| Agents (`.agent.md`) | `.codex/agents/*.toml` | Converted from Markdown to TOML |
-| Hooks (`.json`) | `.codex/hooks.json` + `.codex/hooks/{pkg}/` | Merged JSON config with `_apm_source` markers |
-| Instructions | Via `AGENTS.md` | Compile-only (`apm compile --target codex`) |
-
-**Setup**: Create a `.codex/` directory in your project root, then run `apm install`. APM detects the directory and deploys automatically.
-
-> **Note**: Skills deploy to `.agents/skills/` (the cross-tool agent skills standard directory), not `.codex/skills/`. Agents are transformed from `.agent.md` Markdown to `.toml` format. Use `--target agent-skills` to deploy skills to `.agents/skills/` without also setting up `.codex/` (see [Cross-client deployment](../../guides/skills/#cross-client-deployment-agent-skills)).
-
-#### Gemini CLI (`.gemini/`)
-
-| APM Primitive | Gemini Destination | Format |
-|---|---|---|
-| Commands (`.prompt.md`) | `.gemini/commands/*.toml` | Converted from Markdown to TOML |
-| Skills (`SKILL.md`) | `.agents/skills/{name}/` | Verbatim copy (converged from `.gemini/skills/`) |
-| Hooks (`.json`) | `.gemini/settings.json` | Merged into `hooks` key |
-| MCP servers | `.gemini/settings.json` | Merged into `mcpServers` key |
-| Instructions | Via `GEMINI.md` | Compile-only (`apm compile --target gemini`) |
-
-**Setup**: Create a `.gemini/` directory in your project root, then run `apm install`. APM detects the directory and deploys commands, skills, hooks, and MCP configuration automatically. For instructions, run `apm compile --target gemini` to generate `GEMINI.md` (a stub that imports `AGENTS.md`).
-
-### Automatic Agent Integration
-
-APM automatically deploys agent files from installed packages into `.claude/agents/`:
-
-```bash
-# Install a package with agents
-apm install danielmeppiel/design-guidelines
-
-# Result:
-# .claude/agents/security.md -- Sub-agent available for Claude Code
-```
-
-**How it works:**
-1. `apm install` detects `.agent.md` and `.chatmode.md` files in the package
-2. Copies each to `.claude/agents/` as `.md` files
-3. `apm uninstall` automatically removes the package's agents
-
-### Automatic Command Integration
-
-APM automatically converts `.prompt.md` files from installed packages into Claude slash commands:
+When you run `apm install` or `apm compile` without `--target`, APM auto-detects which tools your project uses by looking for the markers above. Multiple targets can be active simultaneously.
 
 ```bash
-# Install a package with prompts
-apm install microsoft/apm-sample-package
-
-# Result:
-# .claude/commands/accessibility-audit.md -- /accessibility-audit
-# .claude/commands/design-review.md       -- /design-review
+apm targets                    # list detected and supported targets
+apm install --target claude    # force a specific target
 ```
 
-**How it works:**
-1. `apm install` detects `.prompt.md` files in the package
-2. Converts each to Claude command format in `.claude/commands/`
-3. Maps APM `input:` frontmatter to Claude `arguments:` frontmatter
-4. Converts `${input:name}` references to `$name` placeholders
-5. Auto-generates `argument-hint` from input names (unless one is already set)
-6. `apm uninstall` automatically removes the package's commands
-
-**Input-to-arguments mapping example:**
-
-```yaml
-# APM prompt (.prompt.md)
----
-description: Review a feature
-input:
-  - feature_name
-  - priority
----
-Review ${input:feature_name} with priority ${input:priority}.
-```
+If no marker is present, APM emits the `[x] No harness detected` error - see [Common errors](../troubleshooting/common-errors/).
 
-Becomes:
+To pin targets in the manifest:
 
 ```yaml
-# Claude command (.claude/commands/review.md)
----
-description: Review a feature
-arguments:
-  - feature_name
-  - priority
-argument-hint: <feature_name> <priority>
----
-Review $feature_name with priority $priority.
+# apm.yml
+target:
+  - claude
+  - copilot
+  - cursor
 ```
 
-### Automatic Skills Integration
+The `target:` field accepts either a YAML list or a CSV string. See [Manifest schema](../reference/manifest-schema/#target).
 
-By default, APM deploys skills from installed packages to `.agents/skills/` (the converged cross-client directory shared by Copilot, Cursor, OpenCode, Codex, and Gemini). Claude is the exception and continues to receive its own copy under `.claude/skills/`. Pass `--legacy-skill-paths` (or set `APM_LEGACY_SKILL_PATHS=1`) to restore per-client routing.
+## Primitive flow per target
 
-```bash
-# Install a package with skills
-apm install ComposioHQ/awesome-claude-skills/mcp-builder
+Each primitive type maps to a target-specific slot:
 
-# Result (default routing):
-# .agents/skills/mcp-builder/SKILL.md -- Skill available for agents
-# .agents/skills/mcp-builder/...      -- Full skill folder copied
 ```
-
-**Skill Folder Naming**: Uses the source folder name directly (e.g., `mcp-builder`, `design-guidelines`), not flattened paths.
-
-**How skill integration works:**
-1. `apm install` checks if the package contains a `SKILL.md` file
-2. If `SKILL.md` exists: copies the entire skill folder to the resolved skills root (`.agents/skills/{folder-name}/` by default, per-client paths under `--legacy-skill-paths`)
-3. If a `.claude/` directory exists: also copies to `.claude/skills/{folder-name}/` (Claude is excluded from the convergence)
-4. Sub-skills inside `.apm/skills/` are promoted to top-level entries under the same skills root
-5. `apm uninstall` removes the skill folder from every location recorded in `apm.lock.yaml`; foreign / hand-authored skills outside the lockfile are never touched
-
-### Automatic Hook Integration
-
-APM automatically integrates hooks from installed packages. Hooks define lifecycle event handlers (e.g., `PreToolUse`, `PostToolUse`, `Stop`) supported by VS Code Copilot, Claude Code, Cursor, and Gemini.
-
-> **Note:** Hook packages must be authored in the target platform's native format. APM handles path rewriting and file placement but does not translate between hook schema formats (e.g., Claude's `command` key vs GitHub Copilot's `bash`/`powershell` keys, or event name casing differences).
-
-```bash
-# Install a package with hooks
-apm install anthropics/claude-plugins-official/plugins/hookify
-
-# VS Code result (.github/hooks/):
-# .github/hooks/hookify-hooks.json            -- Hook definitions
-# .github/hooks/scripts/hookify/hooks/*.py    -- Referenced scripts
-
-# Claude result (.claude/settings.json):
-# Hooks merged into .claude/settings.json hooks key
-# Scripts copied to .claude/hooks/hookify/
-
-# Cursor result (.cursor/hooks.json) — only when .cursor/ exists:
-# Hooks merged into .cursor/hooks.json hooks key
-# Scripts copied to .cursor/hooks/hookify/
+.apm/instructions/   ->   per target: rules / instructions / system prompts
+.apm/prompts/        ->   per target: prompt files / commands
+.apm/agents/         ->   per target: agent definitions (or skill conversion)
+.apm/skills/         ->   per target: skills directory (Claude, Codex, OpenCode, .agents)
+.apm/hooks/          ->   per target: lifecycle hooks (Claude only today)
+mcp: in apm.yml      ->   per target: .mcp.json / settings.json / equivalent
 ```
 
-**How hook integration works:**
-1. `apm install` discovers hook JSON files in `.apm/hooks/` or `hooks/` directories
-2. For VS Code: copies hook JSON to `.github/hooks/` and rewrites script paths
-3. For Claude: merges hook definitions into `.claude/settings.json` under the `hooks` key
-4. For Cursor: merges hook definitions into `.cursor/hooks.json` under the `hooks` key (only when `.cursor/` exists)
-5. For Codex: merges hook definitions into `.codex/hooks.json` under the `hooks` key (only when `.codex/` exists)
-6. For Gemini: merges hook definitions into `.gemini/settings.json` under the `hooks` key (only when `.gemini/` exists)
-7. Copies referenced scripts to the target location
-8. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
-9. `apm uninstall` removes hook files and cleans up merged settings
+Not every target supports every primitive type. When a primitive can't land on a target, APM emits a warning at install time. Skim [Targets matrix](../reference/targets-matrix/) to set expectations before adding a primitive.
 
-### Optional: Target-Specific Compilation
+## Common workflows
 
-Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode, Codex, and Gemini, run `apm compile` to generate instruction files:
+### Add a target to an existing project
 
 ```bash
-# Generate all formats (default)
-apm compile
-
-# Generate only Claude formats
-apm compile --target claude
-# Creates: CLAUDE.md (instructions only)
-
-# Generate only VS Code/Copilot formats  
-apm compile --target copilot
-# Creates: AGENTS.md (instructions only)
-
-# Generate only Gemini formats
-apm compile --target gemini
-# Creates: GEMINI.md (imports AGENTS.md)
-```
-
-> **Remember**: `apm compile` generates instruction files only. Use `apm install` to integrate prompts, agents, instructions, commands, and skills from packages.
-
-### Claude Command Format
-
-Generated commands follow Claude's native structure:
-
-```markdown
-<!-- APM Managed: microsoft/apm-sample-package@abc123 -->
-# Design Review
-
-Review the current design for accessibility and UI standards.
-
-## Instructions
-[Content from original .prompt.md]
-```
-
-### Example Workflow
-
-```bash
-# 1. Install packages (integrates agents, commands, and skills automatically)
-apm install microsoft/apm-sample-package
-apm install github/awesome-copilot/skills/review-and-refactor
-
-# 2. Optional: compile instructions if not using Claude Code natively
-# apm compile --target claude
-
-# 3. In Claude Code, use:
-#    /code-review     -- Runs the code review workflow
-#    /gdpr-assessment -- Runs GDPR compliance check
-
-# 4. CLAUDE.md provides project instructions automatically
-# 5. Agents in .claude/agents/ are available as sub-agents
-# 6. Skills in .claude/skills/ are available for agents to reference
-```
-
-### Claude Desktop Integration
-
-Skills installed by APM deploy to `.agents/skills/` by default (the converged cross-client directory); Claude additionally receives its own copy under `.claude/skills/`. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files. Pass `--legacy-skill-paths` (or set `APM_LEGACY_SKILL_PATHS=1`) to restore per-client routing.
-
-Claude Desktop can use `CLAUDE.md` as its project instructions file. Optionally run `apm compile --target claude` to generate `CLAUDE.md` with `@import` syntax for organized instruction loading.
-
-### Cleanup and Sync
-
-APM maintains synchronization between packages and Claude primitives:
-
-- **Install**: Adds rules, agents, commands, and skills for new packages, tracked via `deployed_files` in `apm.lock.yaml`
-- **Uninstall**: Removes only that package's rules, agents, commands, and skill directories (as tracked in `apm.lock.yaml`). User-authored files are preserved.
-- **Update**: Refreshes rules, agents, commands, and skills when package version changes
-- **Virtual Packages**: Individual files and skills (e.g., `github/awesome-copilot/skills/review-and-refactor`) are tracked via `apm.lock.yaml` and removed correctly on uninstall
-
-## Windsurf Integration
-
-APM integrates with Windsurf/Cascade by deploying primitives into the workspace `.windsurf/` directory.
-
-> **Auto-Detection**: Windsurf integration is enabled only when a `.windsurf/` folder ALREADY exists in your project. Unlike VS Code or Claude, `apm install` will NOT create the folder for you. To opt in, either run `mkdir .windsurf` first, pass an explicit target (`apm install --target windsurf`), or set `target: windsurf` in `apm.yml`.
-
-### Native Windsurf Primitives
-
-When you run `apm install` (with `.windsurf/` present or `--target windsurf`), APM deploys package primitives to Windsurf's native locations:
-
-| APM Primitive | Windsurf Destination | Format |
-|---|---|---|
-| Instructions (`.instructions.md`) | `.windsurf/rules/*.md` | Windsurf rules markdown with `trigger`/`globs` frontmatter |
-| Agents (`.agent.md`) | `.windsurf/skills/<name>/SKILL.md` | Converted to a Windsurf Skill (lossy, see below) |
-| Skills (`SKILL.md`) | `.windsurf/skills/<name>/SKILL.md` | Standard `SKILL.md` format |
-| Commands (`.prompt.md`) | `.windsurf/workflows/*.md` | Windsurf workflow markdown |
-| Hooks | `.windsurf/hooks.json` | Hook definitions merged into a single file |
-
-Reference: [Windsurf memories and rules](https://docs.windsurf.com/windsurf/cascade/memories).
-
-### Lossy Agent to Skill Conversion
-
-Windsurf has no native equivalent of an `.agent.md` persona, so APM converts each agent into a Windsurf Skill (`SKILL.md`). The conversion is deliberately lossy:
-
-- **Preserved**: `name`, `description`, and the full markdown body (verbatim).
-- **Dropped**: `tools` and `model` frontmatter keys -- Windsurf Skills do not support them.
-
-APM prints a warning when a dropped field is detected, so the loss is never silent. If your agent depends on a specific tool list or model pin, prefer a target that supports those keys natively (Copilot, Claude).
-
-### MCP Configuration
-
-Windsurf reads MCP server definitions from a USER-SCOPE file at `~/.codeium/windsurf/mcp_config.json`. The schema is the standard `mcpServers` JSON used by GitHub Copilot CLI. The workspace `.windsurf/` directory does NOT contain MCP config -- there is nothing to commit per project.
-
-Reference: [Windsurf MCP integration](https://docs.windsurf.com/windsurf/cascade/mcp).
-
-### User-Scope Installation Limitations
-
-Windsurf has partial user-scope support. `apm install -g --target windsurf` deploys agents, skills, commands, and hooks under `~/.codeium/windsurf/`, but **instructions (rules) are skipped** at user scope -- Windsurf does not expose a user-level rules directory in the same shape as the workspace one. Keep instruction packages workspace-local.
-
-See [Global Installation](../../guides/dependencies/#global-user-scope-installation) for cross-target user-scope coverage.
-
-## Other IDE Support
-
-### IDEs with GitHub Copilot
-
-Any IDE with GitHub Copilot support works with APM's file-level integration. APM deploys primitives to `.github/`, which Copilot discovers automatically:
-
-```bash
-apm install microsoft/apm-sample-package
-
-# GitHub Copilot picks up:
-# .github/prompts/*.prompt.md
-# .github/agents/*.agent.md
-# .github/instructions/*.instructions.md
+# Add Cursor alongside an existing Copilot setup
+mkdir .cursor
+apm install            # auto-detects the new marker
+apm compile            # writes Cursor-specific output
 ```
 
-**Supported IDEs**: JetBrains (IntelliJ, PyCharm, WebStorm, etc.), Visual Studio, VS Code, and any IDE with GitHub Copilot integration.
+Or pin in `apm.yml` and rerun install.
 
-### Cursor
+### Remove a target
 
-APM natively integrates with Cursor when a `.cursor/` directory exists in your project. Run `apm install` and APM automatically deploys primitives to Cursor's native format:
+1. Edit `apm.yml` to drop the target from `target:`.
+2. `apm prune` to remove APM-managed files for the dropped target.
+3. `apm install && apm compile` to verify.
 
-| APM Primitive | Cursor Destination | Format |
-|---|---|---|
-| Instructions (`.instructions.md`) | `.cursor/rules/*.mdc` | Converted: `applyTo:` → `globs:` frontmatter |
-| Agents (`.agent.md`) | `.cursor/agents/*.md` | Markdown with YAML frontmatter |
-| Skills (`SKILL.md`) | `.agents/skills/{name}/SKILL.md` | Identical (agentskills.io standard; converged from `.cursor/skills/`) |
-| Hooks (`.json`) | `.cursor/hooks.json` + `.cursor/hooks/{pkg}/` | Merged JSON config |
-| MCP servers | `.cursor/mcp.json` | Standard `mcpServers` JSON |
+See [Migration paths -> target migration](../troubleshooting/migration/#5-target-migration).
 
-**Setup**: Create a `.cursor/` directory in your project root (or use Cursor's settings), then run `apm install`. APM detects the directory and deploys automatically.
+### Cross-tool sharing via .agents/skills
 
-**Fallback**: `apm compile` also generates `AGENTS.md` at the project root, which Cursor discovers as project-level context. This is useful for compiled/merged instruction output.
+For team projects where contributors use different IDEs, the `agent-skills` target writes a vendor-neutral `.agents/skills/` tree that Claude Code, Codex, OpenCode, and others read directly. This avoids per-tool duplication when your team is multi-vendor.
 
 ```bash
-# Preview what will be compiled
-apm compile --dry-run
-
-# Compile with source attribution for traceability
-apm compile --verbose
-
-# Watch mode: auto-recompile when primitives change
-apm compile --watch
+apm install --target agent-skills
 ```
 
-## MCP (Model Context Protocol) Integration
-
-:::tip[New: declarative install]
-Use `apm install --mcp NAME` (or its alias `apm mcp install NAME`) to add servers from the command line in one step. See the [MCP Servers guide](../../guides/mcp-servers/) for the full workflow. This page covers per-IDE config-file locations and runtime targeting.
-:::
+## MCP server integration
 
-APM provides first-class support for MCP servers, including registry-based servers that publish stdio packages (npm, pypi, docker) or HTTP/SSE remote endpoints.
+MCP servers declared in `apm.yml` (under `mcp:`) are wired into each target's MCP config on install:
 
-### Auto-Discovery from Packages
+- `.claude/settings.json` (Claude Code)
+- `.cursor/mcp.json` (Cursor)
+- `.codex/mcp.json` (Codex)
+- `.vscode/mcp.json` (VS Code)
+- `.opencode/mcp.json` (OpenCode)
+- `.windsurf/mcp.json` (Windsurf)
 
-APM auto-discovers MCP server declarations from packages during `apm install`:
-
-- **apm.yml dependencies**: MCP servers listed under `dependencies.mcp` in a package's `apm.yml` are collected automatically.
-- **plugin.json**: Packages with a `plugin.json` (at the root, `.github/plugin/`, or `.claude-plugin/`) are recognized as marketplace plugins. APM synthesizes an `apm.yml` from `plugin.json` metadata when no `apm.yml` exists. When both files are present (hybrid mode), APM uses `apm.yml` for dependency management while preserving `plugin.json` for plugin ecosystem compatibility. See [Plugin authoring](../../guides/plugins/#plugin-authoring).
-- **Transitive collection**: APM walks the dependency tree and collects MCP servers from all transitive packages.
-
-### Trust Model
-
-APM enforces a trust boundary for MCP servers to prevent packages from silently injecting arbitrary server processes:
-
-| Dependency Type | Registry Servers | Self-Defined Servers |
-|----------------|-----------------|---------------------|
-| Direct (depth 1) | Auto-trusted | Auto-trusted |
-| Transitive (depth > 1) | Auto-trusted | Skipped with warning |
-
-**Self-defined servers** are those declared with `registry: false` in `apm.yml` -- they run arbitrary commands rather than resolving through the official MCP registry.
-
-To trust self-defined servers from transitive dependencies, either:
-1. Re-declare the server in your root `apm.yml` (recommended), or
-2. Use the `--trust-transitive-mcp` flag:
-
-```bash
-# Trust self-defined MCP servers from transitive packages
-apm install --trust-transitive-mcp
-```
-
-### Client Configuration
-
-APM configures MCP servers in the native config format for each supported client:
-
-| Client | Config Location | Format |
-|--------|----------------|--------|
-| VS Code | `.vscode/mcp.json` | JSON `servers` object |
-| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | JSON `mcpServers` object |
-| Codex CLI (project) | `.codex/config.toml` | TOML `mcp_servers` section |
-| Codex CLI (`--global`) | `~/.codex/config.toml` | TOML `mcp_servers` section |
-| Claude Code (project) | `.mcp.json` | JSON `mcpServers` object (opt-in: requires `.claude/`) |
-| Claude Code (`-g`/`--global`) | `~/.claude.json` | JSON `mcpServers` object (atomic write; `0o600` on first create) |
-| Cursor | `.cursor/mcp.json` | JSON `mcpServers` object |
-| Gemini CLI | `.gemini/settings.json` | JSON `mcpServers` object |
-
-**Runtime targeting**: APM detects which runtimes are installed and configures MCP servers for all of them. Use `--runtime <name>` or `--exclude <name>` to control which clients receive configuration. Supported runtime names: `copilot`, `codex`, `vscode`, `cursor`, `opencode`, `gemini`, `claude`.
-
-**Claude Code detection**: APM considers Claude Code available when either the `claude` CLI command is on PATH **or** a `.claude/` directory exists in the resolved project root. Project-scope writes are gated on `.claude/` being present (mirroring Cursor / OpenCode), so `apm install` will not create `.mcp.json` until you opt in by creating the directory.
-
-**Claude Code scopes**: Claude Code itself supports three scopes -- LOCAL (the default for `claude mcp add`, per-project private under `~/.claude.json -> projects.<path>.mcpServers`), PROJECT (`.mcp.json`, VCS-shared), and USER (`~/.claude.json` top-level `mcpServers`, cross-project). APM intentionally targets PROJECT and USER (mapping to `apm install` and `apm install -g/--global`) and does not implement LOCAL: APM packages are designed for reproducible team installs, which aligns with PROJECT (shared via VCS) and USER (private but cross-project), not LOCAL (private to one user, one project).
-
-**Codex CLI**: Project installs write MCP configuration to `.codex/config.toml` only when Codex is an active project target. `--global` installs write to `~/.codex/config.toml`.
-
-> **VS Code detection**: APM considers VS Code available when either the `code` CLI command is on PATH **or** a `.vscode/` directory exists in the resolved project root (defaulting to the current working directory when no explicit project root is provided). This means VS Code MCP configuration works even when `code` is not on PATH — common on macOS and Linux when "Install 'code' command in PATH" has not been run from the VS Code command palette, or when VS Code was installed via a method that doesn't register the CLI (e.g. `.tar.gz`, Flatpak, or a non-standard macOS install location).
-
-```bash
-# Install MCP dependencies for all detected runtimes
-apm install
-
-# Target only VS Code
-apm install --runtime vscode
-
-# Skip Codex configuration
-apm install --exclude codex
-
-# Install only MCP dependencies (skip APM packages)
-apm install --only mcp
-
-# Preview MCP configuration without writing
-apm install --dry-run
-```
-
-APM also handles stale server cleanup: when a package is uninstalled or an MCP dependency is removed, APM removes the corresponding entries from all client configs.
-
-### Package Type Inference
-
-The MCP registry API may return empty `registry_name` fields for packages. APM infers the package type from:
-
-1. Explicit `registry_name` (when provided)
-2. `runtime_hint` (e.g. `npx` to npm, `uvx` to pypi)
-3. Package name patterns (e.g. `@scope/name` to npm, `ghcr.io/...` to docker, `PascalCase.Name` to nuget)
-
-### Supported Package Types
-
-When installing registry MCP servers, APM selects the best available package for each runtime:
-
-| Package Registry | VS Code | Copilot CLI | Codex CLI |
-|-----------------|---------|-------------|-----------|
-| npm | Yes (npx) | Yes (npx) | Yes (npx) |
-| pypi | Yes (uvx/python3) | Yes (uvx) | Yes (uvx) |
-| docker | Yes | Yes | Yes |
-| homebrew | -- | Yes | Yes |
-| Other (with runtime_hint) | Yes (generic) | Yes (generic) | Yes (generic) |
-| HTTP/SSE remotes | Yes | Yes | Yes |
-
-### MCP Server Declaration
-
-```yaml
-# apm.yml - MCP dependencies
-dependencies:
-  mcp:
-    # Simple registry references (resolved via MCP registry)
-    - io.github.github/github-mcp-server
-    - io.github.modelcontextprotocol/filesystem-server
-
-    # Registry server with overlays
-    - name: io.github.modelcontextprotocol/postgres-server
-      transport: stdio
-      package: npm
-      args: ["--connection-string", "postgresql://localhost/mydb"]
-
-    # Self-defined server (not in registry)
-    - name: my-internal-server
-      registry: false
-      transport: stdio
-      command: python
-      args: ["-m", "my_server"]
-      env:
-        PORT: "3000"
-```
-
-```bash
-# Install MCP dependencies
-apm install
-
-# Search the MCP registry
-apm mcp search github
-
-# Show server details
-apm mcp show io.github.github/github-mcp-server
-
-# List available MCP servers
-apm mcp list
-```
-
-#### `${input:...}` Variables in `headers` and `env`
-
-Values in `headers` and `env` can reference VS Code input variables using `${input:<variable-id>}`. At runtime, VS Code prompts the user for each referenced input before starting the server.
-
-For registry-backed servers, APM auto-generates input prompts from registry metadata. For self-defined servers, APM detects the `${input:...}` patterns in your `apm.yml` and generates matching input definitions.
-
-```yaml
-dependencies:
-  mcp:
-    - name: my-server
-      registry: false
-      transport: http
-      url: https://my-server.example.com/mcp/
-      headers:
-        Authorization: "Bearer ${input:my-server-token}"
-        X-Project: "${input:my-server-project}"
-```
+For server installation patterns, registry resolution, and trust model, see [MCP servers guide](../guides/install-and-use/mcp-servers/) and [`apm mcp`](../reference/cli/mcp/).
 
-**Runtime support:**
+## Per-tool reference pages
 
-| Runtime | `${input:...}` support |
-|---------|----------------------|
-| VS Code | Yes -- prompts user at runtime |
-| Copilot CLI | No -- use environment variables instead |
-| Codex | No -- use environment variables instead |
+Pinpoint behaviour, slot layout, and known limits per target:
 
-## Roadmap
+- [Targets matrix](../reference/targets-matrix/) - capability grid
+- [`apm targets`](../reference/cli/targets/) - detection and listing
+- [`apm install`](../reference/cli/install/) - target selection flags
+- [`apm compile`](../reference/cli/compile/) - per-target output
+- [`apm mcp`](../reference/cli/mcp/) - MCP wiring per target
 
-The following IDE integrations are planned for future releases:
+## Troubleshooting
 
-- **JetBrains IDE support**: Native integration with IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs
-- **Cursor deeper integration**: Enhanced Cursor support including rule versioning and conflict resolution
+| Symptom                                       | Where to look                                                              |
+|-----------------------------------------------|----------------------------------------------------------------------------|
+| `[x] No harness detected`                     | [Common errors](../troubleshooting/common-errors/)                          |
+| Compile produced no output                    | [Compile zero-output](../troubleshooting/compile-zero-output-warning/)      |
+| Wrong target picked, multiple harnesses       | [`apm targets`](../reference/cli/targets/)                                  |
+| MCP server not appearing in tool              | [MCP servers guide](../guides/install-and-use/mcp-servers/)                 |
+| Cursor command file dropped                   | [Targets matrix](../reference/targets-matrix/) - `claude_command` transformer |
 
-## Related Resources
+## Related resources
 
-- **[Getting Started](../../getting-started/installation/)** -- Set up APM in your environment
-- **[Key Concepts](../../introduction/key-concepts/)** -- Core APM concepts and terminology
-- **[CLI Reference](../../reference/cli-commands/)** -- Complete command documentation
-- Review the [VSCode Copilot Customization Guide](https://code.visualstudio.com/docs/copilot/copilot-customization) for VSCode-specific features
-- Check the [Spec-kit documentation](https://github.com/github/spec-kit) for SDD integration details
-- Explore [MCP servers](https://modelcontextprotocol.io/servers) for tool integration options
+- [Targets matrix](../reference/targets-matrix/)
+- [Manifest schema](../reference/manifest-schema/)
+- [MCP servers](../guides/install-and-use/mcp-servers/)
+- [GitHub Agentic Workflows](./gh-aw/)
+- [Microsoft 365 Copilot Cowork](./copilot-cowork/)
+- [APM in CI/CD](./ci-cd/)
+- [Runtime compatibility](./runtime-compatibility/)
diff --git a/docs/src/content/docs/introduction/anatomy-of-an-apm-package.md b/docs/src/content/docs/introduction/anatomy-of-an-apm-package.md
deleted file mode 100644
index b6497e1d6..000000000
--- a/docs/src/content/docs/introduction/anatomy-of-an-apm-package.md
+++ /dev/null
@@ -1,318 +0,0 @@
----
-title: "Anatomy of an APM Package"
-description: "What .apm/ is, why it exists, and how APM decides what is importable."
-sidebar:
-  order: 5
----
-
-If you have read [What is APM?](./what-is-apm/) and [How It Works](./how-it-works/),
-you know APM is a package manager for agent primitives. This page answers the
-next question every user asks: what does an APM package actually look like on
-disk, and why does it look that way?
-
-## The one-line mental model
-
-`apm.yml` is your `package.json`. `.apm/` is your `src/`. `apm_modules/` is your
-`node_modules/`. The compiled output under `.github/`, `.claude/`, `.cursor/`,
-and friends is your `dist/` -- generated, tool-specific, not the source of
-truth.
-
-If you remember nothing else: **`.apm/` holds the primitives you author.
-Everything outside `.apm/` that looks similar is either a build artifact or
-someone else's package.**
-
-## Why `.apm/` exists
-
-AI coding tools each invented their own folder for context: `.github/` for
-Copilot, `.claude/` for Claude Code, `.cursor/rules/` for Cursor, and so on.
-Each one is read at runtime by exactly one tool. None of them are designed to
-be authored portably, versioned as a dependency, or shared across tools.
-
-APM separates two concerns that those folders conflate:
-
-1. **Source primitives** -- the skills, agents, instructions, and prompts you
-   write and version. These live in `.apm/`.
-2. **Compiled output** -- the tool-specific files APM generates from your
-   sources for each runtime you target. These live in `.github/`, `.claude/`,
-   `.cursor/`, etc.
-
-`apm install` and `apm compile` read from `.apm/` and write outward.
-
-### A concrete example: this repo
-
-The `microsoft/apm` repository (the one shipping the CLI you are reading docs
-for) dogfoods this layout. It contains both source and compiled output side
-by side:
-
-```
-microsoft/apm/
-+-- apm.yml
-+-- .apm/
-|   +-- skills/
-|   |   +-- python-architecture/
-|   |       +-- SKILL.md
-|   +-- agents/
-|   |   +-- doc-writer.agent.md
-|   +-- instructions/
-+-- .github/
-|   +-- skills/
-|   |   +-- python-architecture/
-|   |       +-- SKILL.md         (deployed from .apm/ by apm install)
-|   +-- agents/
-|   |   +-- doc-writer.agent.md
-|   +-- instructions/
-+-- src/
-+-- tests/
-```
-
-The source files under `.apm/` are authoritative. You can inspect them on
-GitHub:
-[`.apm/skills/python-architecture/SKILL.md`](https://github.com/microsoft/apm/blob/main/.apm/skills/python-architecture/SKILL.md)
-and
-[`.apm/agents/doc-writer.agent.md`](https://github.com/microsoft/apm/blob/main/.apm/agents/doc-writer.agent.md).
-Their counterparts under `.github/` are the deployed copies the in-repo
-Copilot agent actually loads while we work on the CLI.
-
-For simple primitives the deployed file is byte-identical to the source.
-The deploy step can also augment files for runtime-specific concerns (e.g.
-adding diagnostic guidance for a particular target), so treat `.github/`
-as build output: never edit it by hand, always re-deploy from `.apm/`.
-
-## Why not just put primitives in `.github/` directly?
-
-It is tempting. `.github/` already exists, Copilot already reads it, why add
-another folder?
-
-Three reasons, in order of severity.
-
-**1. Self-referential context pollution.**
-The Copilot, Claude, or Cursor agent helping you author a skill reads
-whatever sits in its runtime folder. If you author skills directly into
-`.github/skills/`, your in-progress, half-written, possibly broken skill
-becomes part of the system prompt of the agent you are using to write it.
-Writing a code-review skill? Copilot starts applying it -- including to the
-skill file itself -- before you have finished. Keeping sources in `.apm/`
-means the dev-time agent only sees what you have explicitly compiled.
-
-**2. Portability across runtimes.**
-A skill in `.github/skills/` is a Copilot-shaped file. A skill in
-`.claude/skills/` is a Claude-shaped file. They are not interchangeable. The
-whole point of APM is one source, many runtimes. That requires a
-runtime-neutral source folder, and `.github/` is not it.
-
-**3. Packaging boundary.**
-`apm pack` needs to know what is part of the package and what is incidental.
-A dedicated `.apm/` directory makes that boundary trivial. Mixing sources
-into `.github/` makes it a guessing game.
-
-## Why not the repo root?
-
-Also tempting, also wrong, for symmetric reasons:
-
-- **Naming collisions.** Most repos already have `skills/`, `agents/`, or
-  `prompts/` directories that mean something else (test fixtures, app code,
-  marketing copy). APM cannot safely claim those names at the root.
-- **No discoverability signal.** A consumer cloning your repo cannot tell at
-  a glance whether it is an APM package. `.apm/` plus `apm.yml` is that
-  signal.
-- **No clean pack boundary.** Same problem as `.github/`: `apm pack` would
-  need heuristics to know what to bundle.
-
-`.apm/` is short, namespaced, conventional, and unambiguous. That is the
-whole argument.
-
-## Why not just ship a `plugin.json`?
-
-This is the sharpest version of the question, because plugin formats are
-real and the ecosystem is converging on them. APM does not compete with
-plugins -- it sits underneath them.
-
-- `plugin.json` is a **runtime distribution format**. It tells a single
-  host (Copilot CLI, Claude Code, Cursor) how to load a bundle of
-  primitives at runtime.
-- `.apm/` is a **source layout**. It tells APM what you authored, so it
-  can resolve dependencies, lock versions, scan for security issues, and
-  compile to *every* runtime -- including plugin format.
-
-The two are complementary, and APM treats them that way:
-
-1. **APM consumes plugins as first-class dependencies.** Any repo with a
-   `plugin.json` (root, `.github/plugin/`, `.claude-plugin/`, or
-   `.cursor-plugin/`) is auto-recognized by `apm install`. APM
-   synthesizes an `apm.yml` from the plugin metadata so it gets version
-   pinning, lockfile entries, and transitive resolution. Marketplaces
-   (`marketplace.json`) resolve through the same path. See
-   [Plugins](../../guides/plugins/) and [Marketplaces](../../guides/marketplaces/).
-2. **APM compiles `.apm/` to plugin format.** Run `apm pack` and you
-   get a standalone Claude Code plugin directory -- no `apm.yml`, no
-   `apm_modules/`, no `.apm/` -- consumable by any plugin host. See
-   [Pack & Distribute -- Plugin format](../../guides/pack-distribute/#plugin-format-vs-apm-format).
-3. **Hybrid mode is supported.** A repo can ship `apm.yml` + `plugin.json`
-   together: author with APM (dependency management, lockfile, security
-   scanning, dev/prod separation), distribute as a standard plugin.
-
-What `plugin.json` alone does not give you: transitive dependency
-resolution, a consumer-side lockfile, security scanning that blocks
-critical findings on install, `devDependencies` that stay out of the
-shipped artifact, or a single source that targets multiple runtimes.
-That is the gap `.apm/` fills. If you only ever target one host and
-never depend on shared primitives, plugin-only is fine -- and APM still
-consumes you.
-
-## Two ways to be importable
-
-A repo can expose primitives to APM consumers in two forms. They are not
-mutually exclusive.
-
-### Package form
-
-The repo declares itself an APM package: `apm.yml` at the root, primitives
-under `.apm/`. Consumers reference it by repo name:
-
-```yaml
-# consumer's apm.yml
-dependencies:
-  apm:
-    - your-org/your-repo
-```
-
-`apm install` resolves the repo, reads its `apm.yml`, and pulls every
-primitive declared in `.apm/` into `apm_modules/`.
-
-This is the right form when:
-
-- You are publishing a curated set of primitives meant to be consumed
-  together.
-- You want a one-line install for the whole bundle.
-- You want versioning, lockfile entries, and a clean update path.
-
-Canonical examples: [`microsoft/apm-sample-package`](https://github.com/microsoft/apm-sample-package),
-[`apm-handbook`](https://github.com/danielmeppiel/apm-handbook) (a multi-package
-monorepo with `apm.yml` plus `.apm/skills/` and `.apm/agents/`), and this
-repository itself.
-
-### Primitive form
-
-Any subdirectory of any GitHub repo that looks like a primitive can be
-imported directly by path. The upstream repo does not need an `apm.yml` and
-does not need to use `.apm/`:
-
-```yaml
-# consumer's apm.yml
-dependencies:
-  apm:
-    - github/awesome-copilot/skills/review-and-refactor
-```
-
-APM treats the subdirectory as a virtual single-primitive package.
-
-This is the right form when:
-
-- You want one or two skills out of a large repo, not the whole thing.
-- The upstream repo is not APM-aware (and you do not want to ask the
-  maintainer to refactor).
-- You are pinning a specific primitive at a specific commit without taking
-  on the rest of the repo's surface area.
-
-Both forms produce the same artifact in `apm_modules/` and the same compiled
-output. The reference syntax is the only difference.
-
-## Decision guide
-
-| Situation                                                | Use            | Does upstream need `.apm/`? |
-|----------------------------------------------------------|----------------|-----------------------------|
-| Importing one or two skills from a third-party repo      | Primitive form | No                          |
-| Publishing your team's full skill set as a bundle        | Package form   | Yes                         |
-| Mixed: a curated bundle plus a few file-level imports    | Package form   | Yes (works for both)        |
-| Quick test before adopting someone's skill               | Primitive form | No                          |
-
-The short version: **if you are consuming, primitive form covers most cases
-without forcing anyone to refactor. If you are publishing, package form is
-the right investment.**
-
-If you started authoring directly in `.github/` and later want to make a
-proper package, the migration is mechanical: move the files into `.apm/`,
-add an `apm.yml`, and run `apm install` to re-generate `.github/` from the
-new source. No data loss, no breaking change for downstream consumers.
-
-## Why does microsoft/apm itself have a `.apm/` folder?
-
-Because we use APM to manage the agent context that develops APM. The
-[concrete example above](#a-concrete-example-this-repo) is this repo. If
-you are looking for a working reference layout, it is right there.
-
-## What APM looks for
-
-Discovery rules, in order:
-
-1. **`apm.yml`** at the repo root marks the directory as an APM package and
-   declares its dependencies, scripts, and metadata.
-2. **`.apm/`** at the repo root is the source root for primitives. APM does
-   not look elsewhere for sources.
-3. Inside `.apm/`, primitives are grouped by type subdirectory:
-
-   ```
-   .apm/
-   +-- skills/         (SKILL.md plus supporting files)
-   +-- agents/         (agent definitions)
-   +-- instructions/   (instruction files)
-   +-- prompts/        (prompt templates)
-   +-- chatmodes/      (chat mode configurations)
-   +-- context/        (shared context fragments)
-   ```
-
-4. **Per-primitive references** (`owner/repo/path/to/primitive`) bypass
-   `.apm/` entirely. APM treats the named subdirectory as a single-primitive
-   virtual package regardless of where it sits in the upstream repo.
-5. **Compiled output** (`.github/`, `.claude/`, `.cursor/rules/`, and other
-   runtime targets) is generated by `apm compile` based on the runtimes
-   declared in `apm.yml`. Never edit these directly in an APM-managed repo.
-
-For the full schema, see [Manifest Schema](../../reference/manifest-schema/)
-and [Primitive Types](../../reference/primitive-types/).
-
-## Quick FAQ
-
-**I edited `.github/skills/my-skill/SKILL.md` directly. What happens on the
-next `apm install`?** Your edit gets overwritten. Edit the source under
-`.apm/skills/my-skill/SKILL.md` instead and re-run `apm install`.
-
-**I ran `ls` and don't see `.apm/`.** It's a dotfile directory, hidden by
-default. Use `ls -a`.
-
-**I have a skill I want for development but not shipped to consumers.
-Where does it go?** Outside `.apm/`. The local-content scanner that builds
-plugin bundles operates on `.apm/` only and does not consult the
-devDependency marker. Author dev-only primitives under `dev/` (or any
-non-`.apm/` path) and reference them via a local-path devDependency. See
-[Dev-only Primitives](../../guides/dev-only-primitives/).
-
-**Do I need `.apm/` to install packages?** No. `.apm/` is for authoring. If
-you only consume packages, `apm install` creates the runtime targets
-(`.github/`, `.claude/`, etc.) directly under `apm_modules/` and you never
-touch `.apm/`.
-
-**What's the minimum for a valid APM package?** `apm.yml` at the root plus
-at least one primitive under `.apm/`.
-
-**Isn't the industry converging on the plugin format? Why do I need
-`.apm/` at all?** APM consumes plugins natively (`plugin.json` packages
-install as first-class dependencies) and exports to plugin format
-(`apm pack`). `.apm/` is the source layout that gives
-you dependency management, lockfiles, and security scanning during
-authoring; `plugin.json` is the runtime distribution format. Use both --
-see [Why not just ship a `plugin.json`?](#why-not-just-ship-a-pluginjson)
-above and the [authoring workflow](../../guides/plugins/#authoring-workflow).
-
-## See also
-
-- [Your First Package](../../getting-started/first-package/) -- create a
-  package from scratch using this layout.
-- [Primitive Types](../../reference/primitive-types/) -- the canonical
-  reference for skills, agents, instructions, prompts, and friends.
-- [Manifest Schema](../../reference/manifest-schema/) -- the full `apm.yml`
-  spec.
-- [gh-aw Integration](../../integrations/gh-aw/) -- how compiled output
-  feeds GitHub Agentic Workflows.
-- [Compilation](../../guides/compilation/) -- how `.apm/` becomes
-  `.github/`, `.claude/`, and the rest.
diff --git a/docs/src/content/docs/introduction/how-it-works.md b/docs/src/content/docs/introduction/how-it-works.md
deleted file mode 100644
index 44f806cce..000000000
--- a/docs/src/content/docs/introduction/how-it-works.md
+++ /dev/null
@@ -1,278 +0,0 @@
----
-title: "How It Works"
-sidebar:
-  order: 3
----
-
-APM implements the complete [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/) - a systematic approach to making AI coding assistants reliable, scalable, and team-friendly.
-
-## Why This Matters
-
-Most developers experience AI as inconsistent and unreliable:
-
-- **Ad-hoc prompting** that produces different results each time
-- **Context overload** that confuses AI agents and wastes tokens
-- **Vendor lock-in** to specific AI tools and platforms
-- **No knowledge persistence** across sessions and team members
-
-**APM solves this** by implementing the complete 3-layer AI-Native Development framework:
-
-**Layer 1: Markdown Prompt Engineering** - Structured, repeatable AI instructions
-**Layer 2: Context** - Configurable tools that deploy prompt + context engineering
-**Layer 3: Context Engineering** - Strategic LLM memory management for reliability
-
-**Result**: Transform from supervising every AI interaction to architecting systems that delegate complete workflows to AI agents.
-
-## AI-Native Development Maturity Journey
-
-**From Manual Supervision → Engineered Architecture**
-
-Most developers start by manually supervising every AI interaction. APM enables the transformation to AI-Native engineering:
-
-### Before APM: Manual Agent Supervision
-
-The traditional approach requires constant developer attention:
-
-- **Write one-off prompts** for each task  
-- **Manually guide** every AI conversation step-by-step
-- **Start from scratch** each time, no reusable patterns
-- **Inconsistent results** - same prompt produces different outputs
-- **Context chaos** - overwhelming AI with too much information
-- **No team knowledge** - everyone reinvents their own AI workflows
-
-*You're the bottleneck - every AI task needs your personal attention and guidance.*
-
-### With APM: Engineered Agent Delegation
-
-APM transforms AI from a supervised tool to an engineered system:
-
-- **Build reusable Context** once, use everywhere
-- **Engineer context strategically** for optimal AI performance
-- **Delegate complete workflows** to AI with confidence
-- **Reliable results** - structured prompts produce consistent outputs
-- **Smart context loading** - AI gets exactly what it needs, when it needs it
-- **Team knowledge scaling** - share effective AI patterns across the entire organization
-
-*You're the architect - AI handles execution autonomously while following your engineered patterns.*
-
-## The Infrastructure Layer
-
-**APM provides the missing infrastructure for AI-Native Development**
-
-### The Problem
-
-Developers have powerful AI coding assistants but lack systematic approaches to make them reliable and scalable. Every team reinvents their AI workflows, can't share effective context, and struggles with inconsistent results.
-
-### The Solution
-
-APM provides the missing infrastructure layer that makes AI-Native Development portable and reliable.
-
-Just as npm revolutionized JavaScript by creating package ecosystem infrastructure, APM creates the missing infrastructure for AI-Native Development:
-
-- **Package Management**: Share and version AI workflows like code dependencies
-- **Context Compilation**: Transform Context into dynamically injected context 
-- **Runtime Management**: Install and configure AI tools automatically
-- **Standards Compliance**: Generate agents.md files for universal compatibility
-
-### Key Benefits
-
-**Reliable Results** - Replace trial-and-error with proven AI-Native Development patterns
-**Universal Portability** - Works with any coding agent through the agents.md standard
-**Knowledge Packaging** - Share AI workflows like code packages with versioning
-**Compound Intelligence** - Primitives improve through iterative team refinement
-**Team Scaling** - Transform any project for reliable AI-Native Development workflows
-
-## Architecture Overview
-
-APM implements a complete system architecture that bridges the gap between human intent and AI execution:
-
-```mermaid
-graph TD
-    A["Context<br/>.apm/ directory<br/>(.chatmode, .instructions, .prompt, .context)"] --> B["APM CLI"]
-    
-    B --> D["APM Package Manager<br/>Dependencies<br/>Templates"]
-    B --> C["APM Context Compiler<br/>Script Resolution<br/>Primitive Compilation"]
-    B --> E["APM Runtime Manager<br/>Install & Configure<br/>Codex, LLM, etc."]
-    
-    C --> F["AGENTS.md<br/>Portable Standard<br/>Cross-Runtime Compatible"]
-    
-    F --> G["AI Coding Agents<br/>Codex CLI, <br/>llm, ."]
-    
-    E --> H["MCP Servers<br/>Tool Integration"]
-    E --> I["LLM Models<br/>GitHub Models<br/>Ollama, etc."]
-    
-    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
-    style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000
-    style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
-    style D fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
-    style E fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
-    style F fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000
-    style G fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
-    style H fill:#e8f5e8,stroke:#388e3c,stroke-width:1px,color:#000
-    style I fill:#fff3e0,stroke:#ff9800,stroke-width:1px,color:#000
-```
-
-**Key Architecture Components**:
-
-1. **Context** (.apm/ directory) - Your source code for AI workflows. See [Anatomy of an APM Package](../anatomy-of-an-apm-package/) for the directory layout.
-2. **APM CLI** - Three core engines working together:
-   - **Package Manager** - Dependency resolution and distribution
-   - **Primitives Compiler** - Transforms primitives → agents.md format  
-   - **Runtime Manager** - Install and configure AI tools
-3. **AGENTS.md** - Portable standard ensuring compatibility across all coding agents
-4. **AI Coding Agents** - Execute your compiled workflows (Copilot, Cursor, etc.)
-5. **Supporting Infrastructure** - MCP servers for tools, LLM models for execution
-
-GitHub Copilot and Claude read the deployed primitives natively. Cursor, OpenCode, and Gemini also receive native integration when their config directories exist. For instructions, Codex and Gemini use `apm compile` to generate `AGENTS.md` / `GEMINI.md`.
-
-## The Three Layers Explained
-
-### Layer 1: Markdown Prompt Engineering
-
-Transform ad-hoc prompts into structured, repeatable instructions using markdown format:
-
-**Traditional**: "Add authentication to the API"
-
-**Engineered**:
-```markdown
-# Secure Authentication Implementation
-
-## Requirements Analysis
-- Review existing security patterns
-- Identify authentication method requirements
-- Validate session management needs
-
-## Implementation Steps
-1. Set up JWT token system
-2. Implement secure password hashing
-3. Create session management
-4. Add logout functionality
-
-## Validation Gates
-**STOP**: Security review required before deployment
-```
-
-### Layer 2: Context
-
-Package your prompt engineering into reusable, configurable components:
-
-- **Instructions** (.instructions.md) - Context and coding standards
-- **Prompts** (.prompt.md) - Executable AI workflows  
-- **Agents** (.agent.md) - AI assistant personalities
-- **Skills** (SKILL.md) - Package meta-guides for AI agents
-- **Hooks** (.json) - Lifecycle event handlers
-
-### Layer 3: Context Engineering
-
-Strategic management of LLM memory and context for optimal performance:
-
-- **Dynamic Loading** - Load relevant context based on current task
-- **Smart Filtering** - Include only necessary information
-- **Memory Management** - Optimize token usage across conversations
-- **Performance Tuning** - Balance context richness with response speed
-
-## Component Types
-
-### Instructions (.instructions.md)
-Context rules applied based on file patterns:
-
-```yaml
----
-applyTo: "**/*.py"
----
-# Python Coding Standards
-- Follow PEP 8 style guidelines
-- Use type hints for all functions
-- Include comprehensive docstrings
-```
-
-### Prompts (.prompt.md)  
-Executable AI workflows with parameters:
-
-```yaml
----
-description: "Implement secure authentication"
-mode: backend-dev
-input: [auth_method, session_duration]
----
-# Authentication Implementation
-Use ${input:auth_method} with ${input:session_duration} sessions
-```
-
-### Agents (.agent.md)
-AI assistant personalities with tool boundaries:
-
-```yaml
----
-name: "Backend Developer"
-model: "gpt-4"
-description: "Senior backend developer focused on API design"
-tools: ["terminal", "file-manager"] 
----
-You are a senior backend developer focused on API design and security.
-```
-
-### Skills (SKILL.md)
-Package meta-guides that help AI agents understand what a package does:
-
-```yaml
----
-name: Brand Guidelines
-description: Apply corporate brand standards
----
-# How to Use
-Apply these colors and typography standards...
-```
-
-Skills provide AI agents with a quick summary of package purpose and usage.
-
-### Hooks (.json)
-Lifecycle event handlers that run scripts at specific points during AI operations:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": { "tool_name": "write_file" },
-      "hooks": [{ "type": "command", "command": "./scripts/lint.sh" }]
-    }]
-  }
-}
-```
-
-## Compatibility
-
-APM supports coding agents at two levels: **native integration** for tools with rich primitive support, and **compiled instructions** for tools that consume a single instructions file.
-
-### Native integration
-
-These tools support the full set of APM primitives. Running `apm install` deploys instructions, prompts, agents, skills, context, MCP configuration, and hooks directly into each tool's native format.
-
-- **GitHub Copilot** (AGENTS.md + .github/) - instructions, prompts, chat modes, context, hooks, MCP
-- **Claude Code** (CLAUDE.md + .claude/) - commands, skills, MCP configuration
-
-APM auto-detects targets based on project structure -- deploying to every recognized directory (`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.windsurf/`) that exists, falling back to `.github/` when none do. Set `target` in `apm.yml` to restrict to specific targets (single string or list).
-
-### Compiled instructions
-
-For tools that read a single instructions file, `apm compile` merges your primitives into a portable document the tool can consume. This gives you instruction-level support rather than full primitive integration.
-
-- **Cursor** - native integration to `.cursor/rules/`, `.cursor/agents/`, `.cursor/commands/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json`
-- **OpenCode** - native integration to `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP)
-- **Gemini** - native integration to `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json` (MCP, hooks); instructions compiled to `GEMINI.md`
-- **Codex CLI** - compiled to `AGENTS.md`
-
-See the [Compilation guide](../../guides/compilation/) for details on output formats and options.
-
-Your investment in primitives is portable: full primitive support for Copilot and Claude, instruction-level support for other tools via compilation.
-
-## Learn the Complete Framework
-
-APM implements concepts from the broader [AI-Native Development Guide](https://danielmeppiel.github.io/awesome-ai-native/) - explore the complete framework for advanced techniques in:
-
-- **Prompt Engineering Patterns** - Advanced prompting techniques
-- **Context Optimization** - Memory management strategies  
-- **Team Scaling Methods** - Organizational AI adoption
-- **Tool Integration** - Connecting AI with development workflows
-
-Ready to see these concepts in action? Check out [Examples & Use Cases](../../reference/examples/) next!
\ No newline at end of file
diff --git a/docs/src/content/docs/introduction/key-concepts.md b/docs/src/content/docs/introduction/key-concepts.md
deleted file mode 100644
index bec48d629..000000000
--- a/docs/src/content/docs/introduction/key-concepts.md
+++ /dev/null
@@ -1,401 +0,0 @@
----
-title: "Key Concepts"
-sidebar:
-  order: 4
----
-
-Context components are the configurable tools that deploy proven prompt engineering and context engineering techniques. APM implements these as the core building blocks for reliable, reusable AI development workflows.
-
-## How Context Components Work
-
-APM implements Context - the configurable tools that deploy prompt engineering and context engineering techniques to transform unreliable AI interactions into engineered systems.
-
-### Initialize a project
-
-```bash
-apm init my-project  # Creates apm.yml -- the only file apm init produces
-```
-
-### Generated Project Structure
-
-```yaml
-my-project/
-└── apm.yml              # Project configuration and dependency manifest
-```
-
-> **Note:** By default, `apm init` creates only `apm.yml`. Add primitives manually or install them with `apm install`. See [Your First Package](../../getting-started/first-package/) for a step-by-step guide.
-
-### Intelligent Compilation
-
-APM automatically compiles your primitives into optimized AGENTS.md files using mathematical optimization:
-
-```bash
-apm compile  # Generate optimized AGENTS.md files
-apm compile --verbose  # See optimization decisions
-```
-
-**[Learn more about the Context Optimization Engine →](../../guides/compilation/)**
-
-## Packaging & Distribution
-
-**Manage like npm packages:**
-
-```yaml
-# apm.yml - Project configuration
-name: my-ai-native-app
-version: 1.0.0
-scripts:
-  impl-copilot: "copilot -p 'implement-feature.prompt.md'"
-  review-copilot: "copilot -p 'code-review.prompt.md'" 
-  docs-codex: "codex generate-docs.prompt.md -m github/gpt-4o-mini"
-dependencies:
-  mcp:
-    - io.github.github/github-mcp-server
-```
-
-**Share and reuse across projects:**
-```bash
-apm install                    # Install dependencies and deploy primitives
-apm compile                    # Generate optimized AGENTS.md files
-```
-
-## Overview
-
-The APM CLI supports the following types of primitives:
-
-- **Agents** (`.agent.md`) - Define AI assistant personalities and behaviors (legacy: `.chatmode.md`)
-- **Instructions** (`.instructions.md`) - Provide coding standards and guidelines for specific file types
-- **Skills** (`SKILL.md`) - Package meta-guides that help AI agents understand what a package does
-- **Hooks** (`.json` in `.apm/hooks/` or `hooks/`) - Define lifecycle event handlers with script references
-- **Plugins** (`plugin.json`) - Pre-packaged agent bundles auto-normalized into APM packages. Projects may use `apm.yml` only, `plugin.json` only, or both. See [Plugin authoring](../../guides/plugins/#plugin-authoring)
-
-> **Note**: Both `.agent.md` (new format) and `.chatmode.md` (legacy format) are fully supported. VSCode provides Quick Fix actions to help migrate from `.chatmode.md` to `.agent.md`.
-
-## Where primitives live
-
-Primitives are authored in `.apm/` and deployed to runtime folders
-(`.github/`, `.claude/`, `.cursor/`, `.opencode/`) by `apm install` and
-`apm compile`. For the full layout, source-vs-output distinction, and
-discovery rules, see [Anatomy of an APM Package](../anatomy-of-an-apm-package/).
-
-## Component Types Overview
-
-Context implements the complete [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/) through the following core component types:
-
-### Instructions (.instructions.md)
-**Context Engineering Layer** - Targeted guidance by file type and domain
-
-Instructions provide coding standards, conventions, and guidelines that apply automatically based on file patterns. They implement strategic context loading that gives AI exactly the right information at the right time.
-
-```yaml
----
-description: Python coding standards and documentation requirements
-applyTo: "**/*.py"
----
-# Python Coding Standards
-- Follow PEP 8 for formatting
-- Use type hints for all function parameters
-- Include comprehensive docstrings with examples
-```
-
-### Agent Workflows (.prompt.md)  
-**Prompt Engineering Layer** - Executable AI workflows with parameters
-
-Agent Workflows transform ad-hoc requests into structured, repeatable workflows. They support parameter injection, context loading, and validation gates for reliable results.
-
-```yaml
----
-description: Implement secure authentication system
-mode: backend-dev
-input: [auth_method, session_duration]
----
-# Secure Authentication Implementation
-Use ${input:auth_method} with ${input:session_duration} sessions
-Review `security standards` before implementation
-```
-
-### Agents (.agent.md, legacy: .chatmode.md)
-**Agent Specialization Layer** - AI assistant personalities with tool boundaries
-
-Agents create specialized AI assistants focused on specific domains. They define expertise areas, communication styles, and available tools.
-
-```yaml
----
-description: Senior backend developer focused on API design
-tools: ["terminal", "file-manager"]
-expertise: ["security", "performance", "scalability"]
----
-You are a senior backend engineer with 10+ years experience in API development.
-Focus on security, performance, and maintainable architecture patterns.
-```
-
-> **File Format**: Use `.agent.md` for new files. Legacy `.chatmode.md` files continue to work and can be migrated using VSCode Quick Fix actions.
-
-### Skills (SKILL.md)
-**Package Meta-Guide Layer** - Quick reference for AI agents
-
-Skills are concise summaries that help AI agents understand what an APM package does and how to leverage its content. They provide an AI-optimized overview of the package's capabilities.
-
-```markdown
----
-name: Brand Guidelines
-description: Apply corporate brand colors and typography
----
-# How to Use
-When asked about branding, apply these standards...
-```
-
-**Key Features:**
-- Install from Claude Skill repositories: `apm install ComposioHQ/awesome-claude-skills/brand-guidelines`
-- Provides AI agents with quick understanding of package purpose
-- Resources (scripts, references) stay in `apm_modules/`
-
-→ [Complete Skills Guide](../../guides/skills/)
-
-## Primitive Types
-
-### Agents
-
-Agents define AI assistant personalities and specialized behaviors for different development tasks.
-
-**Format:** `.agent.md` (new) or `.chatmode.md` (legacy)
-
-**Frontmatter:**
-- `description` (required) - Clear explanation of the agent purpose
-- `author` (optional) - Creator information
-- `version` (optional) - Version string
-
-**Example:**
-```markdown
----
-description: AI pair programming assistant for code review
-author: Development Team
-version: "1.0.0"
----
-
-# Code Review Assistant
-
-You are an expert software engineer specializing in code review.
-
-## Your Role
-- Analyze code for bugs, security issues, and performance problems
-- Suggest improvements following best practices
-- Ensure code follows team conventions
-
-## Communication Style
-- Be constructive and specific in feedback
-- Explain reasoning behind suggestions
-- Prioritize critical issues over style preferences
-```
-
-### Instructions
-
-Instructions provide coding standards, conventions, and guidelines that apply to specific file types or patterns.
-
-**Format:** `.instructions.md`
-
-**Frontmatter:**
-- `description` (required) - Clear explanation of the standards
-- `applyTo` (optional) - Glob pattern for file targeting (e.g., `"**/*.py"`). When omitted, the instruction is treated as global and rendered under a `## Global Instructions` section in the compiled `AGENTS.md`/`CLAUDE.md` (applies to every file).
-- `author` (optional) - Creator information
-- `version` (optional) - Version string
-
-**Example:**
-```markdown
----
-description: Python coding standards and documentation requirements
-applyTo: "**/*.py"
-author: Development Team
-version: "2.0.0"
----
-
-# Python Coding Standards
-
-## Style Guide
-- Follow PEP 8 for formatting
-- Maximum line length of 88 characters (Black formatting)
-- Use type hints for all function parameters and returns
-
-## Documentation Requirements
-- All public functions must have docstrings
-- Include Args, Returns, and Raises sections
-- Provide usage examples for complex functions
-
-## Example Format
-```python
-def calculate_metrics(data: List[Dict], threshold: float = 0.5) -> Dict[str, float]:
-    """Calculate performance metrics from data.
-    
-    Args:
-        data: List of data dictionaries containing metrics
-        threshold: Minimum threshold for filtering
-    
-    Returns:
-        Dictionary containing calculated metrics
-    
-    Raises:
-        ValueError: If data is empty or invalid
-    """
-```
-
-### Hooks
-
-Hooks define lifecycle event handlers that run scripts at specific points during AI agent operations (e.g., before/after tool use).
-
-**Format:** `.json` files in `hooks/` or `.apm/hooks/`
-
-**Structure:**
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": { "tool_name": "write_file" },
-        "hooks": [
-          {
-            "type": "command",
-            "command": "./scripts/lint-changed.sh $TOOL_INPUT_path"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-**Supported Events:** `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SubagentStop`
-
-**Integration:**
-- VSCode: Hook JSON files are copied to `.github/hooks/*-apm.json` with script paths rewritten
-- Claude: Hooks are merged into `.claude/settings.json` under the `hooks` key
-- Scripts referenced by hooks are bundled alongside the hook definitions
-
-## Discovery and Parsing
-
-The APM CLI automatically discovers and parses all primitive files in your project.
-
-## Validation
-
-All primitives are automatically validated during discovery:
-
-- **Agents**: Must have description and content (supports both `.agent.md` and `.chatmode.md`)
-- **Instructions**: Must have description and content. `applyTo` is optional -- omitting it makes the instruction apply globally (a warning is emitted at compile time so authors are aware of the implicit scope).
-
-Invalid files are skipped with warning messages, allowing valid primitives to continue loading.
-
-## Context Linking
-
-Context files are **linkable knowledge modules** that other primitives can reference via markdown links, enabling composable knowledge graphs.
-
-### Linking from Instructions
-
-```markdown
-<!-- .apm/instructions/api.instructions.md -->
----
-applyTo: "backend/**/*.py"
-description: API development guidelines
----
-
-Follow `our API standards` and ensure
-`GDPR compliance` for all endpoints.
-```
-
-### Linking from Agents
-
-```markdown
-<!-- .apm/agents/backend-expert.agent.md -->
----
-description: Backend development expert
----
-
-You are a backend expert. Always reference `our architecture patterns`
-when designing systems.
-```
-
-### Automatic Link Resolution
-
-APM automatically resolves context file links during installation and compilation:
-
-1. **Discovery**: Scans all primitives for context file references
-2. **Resolution**: Rewrites links to point to actual source locations
-3. **Direct Linking**: Links point to files in `apm_modules/` and `.apm/` directories
-4. **Persistence**: Commit `apm_modules/` for link availability, or run `apm install` in CI/CD
-
-**Result**: Links work in IDE and GitHub, pointing directly to source files. Copilot and Claude resolve links natively via `apm install`; other tools pick them up through `apm compile`.
-
-### Link Resolution Examples
-
-Links are rewritten to point to actual source locations:
-
-**From installed prompts/agents** (`.github/` directory):
-```markdown
-`API Standards`
-→ `API Standards`
-```
-
-**From compiled AGENTS.md**:
-```markdown
-`Architecture`
-→ `Architecture`
-```
-
-## Best Practices
-
-### 1. Clear Naming
-Use descriptive names that indicate purpose:
-- `code-review-assistant.agent.md`
-- `python-documentation.instructions.md`
-- `team-contacts.md`
-
-### 2. Targeted Application
-Use specific `applyTo` patterns for instructions:
-- `"**/*.py"` for Python files
-- `"**/*.{ts,tsx}"` for TypeScript React files
-- `"**/test_*.py"` for Python test files
-
-### 3. Version Control
-Keep primitives in version control alongside your code. Use semantic versioning for breaking changes.
-
-### 4. Organized Structure
-Use `.apm/` subdirectories by primitive type. See [Anatomy](../anatomy-of-an-apm-package/#what-apm-looks-for).
-
-### 5. Team Collaboration
-- Include author information in frontmatter
-- Document the purpose and scope of each primitive
-- Regular review and updates as standards evolve
-
-## Integration with VSCode
-
-VS Code Copilot reads compiled output in `.github/`. Author in `.apm/` and let `apm install` produce it -- see [Anatomy](../anatomy-of-an-apm-package/) for the source-vs-output model.
-
-## Error Handling
-
-The primitive system handles errors gracefully:
-
-- **Malformed YAML**: Files with invalid frontmatter are skipped with warnings
-- **Missing required fields**: Validation errors are reported clearly
-- **File access issues**: Permission and encoding problems are handled safely
-- **Invalid patterns**: Glob pattern errors are caught and reported
-
-This ensures that a single problematic file doesn't prevent other primitives from loading.
-
-## Spec Kit Constitution Injection (Phase 0)
-
-When present, a project-level constitution file at `memory/constitution.md` is injected at the very top of `AGENTS.md` during `apm compile`.
-
-### Block Format
-```
-<!-- SPEC-KIT CONSTITUTION: BEGIN -->
-hash: <sha256_12> path: memory/constitution.md
-<entire original file content>
-<!-- SPEC-KIT CONSTITUTION: END -->
-```
-
-### Behavior
-- Enabled by default; disable via `--no-constitution` (existing block preserved)
-- Idempotent: re-running compile without changes leaves file unchanged
-- Drift aware: modifying `memory/constitution.md` regenerates block with new hash
-- Safe: absence of constitution does not fail compilation (status MISSING in Rich table)
-
-### Why This Matters
-Ensures downstream AI tooling always has the authoritative governance / principles context without manual copy-paste. The hash enables simple drift detection or caching strategies later.
\ No newline at end of file
diff --git a/docs/src/content/docs/introduction/what-is-apm.md b/docs/src/content/docs/introduction/what-is-apm.md
deleted file mode 100644
index 5fe26c25d..000000000
--- a/docs/src/content/docs/introduction/what-is-apm.md
+++ /dev/null
@@ -1,274 +0,0 @@
----
-title: "What is APM?"
-description: "Agent Package Manager — the open-source dependency manager for AI agent configuration."
-sidebar:
-  order: 1
----
-
-Software teams solved dependency management for application code decades ago.
-`npm`, `pip`, `cargo`, `go mod` — declare what you need, install it reproducibly, lock versions, ship.
-
-AI agent configuration has no equivalent. Until now.
-
-## What is agent package management?
-
-AI coding agents — GitHub Copilot, Claude, Cursor, OpenCode, Codex, Gemini — are only as
-good as the context they receive. That context is made up of instructions,
-skills, prompts, agent definitions, hooks, plugins, and MCP server
-configurations.
-
-Today, teams manage this context by hand:
-
-- Copy instruction files between repos
-- Write prompts from scratch for every project
-- Configure MCP servers manually on each developer's machine
-- Hope everyone's setup matches
-
-This is the same class of problem that `package.json` solved for JavaScript,
-`requirements.txt` for Python, and `Cargo.toml` for Rust. Agent configuration
-is infrastructure. It deserves a dependency manager.
-
-**Agent package management** is the practice of declaring, resolving, locking,
-and distributing AI agent configuration as versioned, composable packages.
-
-APM is the tool that does it.
-
-## The shape of the problem
-
-Consider what happens when a team adopts AI coding agents without a package
-manager:
-
-| Without APM | With APM |
-|---|---|
-| Each dev configures agents manually | `apm install` sets up everything |
-| Instructions drift across machines | `apm.lock.yaml` pins exact versions |
-| No way to share or reuse prompts | Publish and install from any git host |
-| MCP servers configured per-developer | Declared in manifest, installed consistently |
-| Onboarding requires tribal knowledge | Clone, `apm install`, done |
-| No audit trail for agent config | Lock file tracks every dependency |
-
-The cost compounds with team size. A 5-person team with manual setup has 5
-divergent agent configurations. A 50-person team has 50.
-
-## How APM works
-
-APM introduces `apm.yml` — a declarative manifest for AI agent configuration:
-
-```yaml
-name: my-project
-version: 1.0.0
-dependencies:
-  apm:
-    - microsoft/apm-sample-package
-    - anthropics/skills/skills/frontend-design
-    - github/awesome-copilot/agents/api-architect.agent.md
-```
-
-One command installs everything:
-
-```bash
-apm install
-```
-
-APM resolves transitive dependencies, places files in the correct directories,
-and generates a lock file that pins every version.
-
-## The seven primitives
-
-APM manages seven types of agent configuration. Each is a first-class citizen
-in the manifest and dependency tree.
-
-| Primitive | What it does | Example |
-|---|---|---|
-| **Instructions** | Coding standards and guardrails | "Use type hints in all Python files" |
-| **Skills** | Reusable AI capabilities and workflows | Form builder, code reviewer |
-| **Prompts** | Slash commands for common tasks | `/security-audit`, `/design-review` |
-| **Agents** | Specialized AI personas | Accessibility auditor, API designer |
-| **Hooks** | Lifecycle event handlers | Pre-tool validation, post-tool linting |
-| **Plugins** | Pre-packaged agent bundles | Context engineering kit, commit helpers |
-| **MCP Servers** | External tool integrations | Database access, API connectors |
-
-These primitives map directly to the configuration surfaces of major AI coding
-tools. APM does not invent new abstractions — it manages the ones that already
-exist.
-
-For detailed definitions, see [Primitive Types](../../reference/primitive-types/).
-
-## The lifecycle
-
-APM follows a five-stage lifecycle that mirrors how teams actually work with
-agent configuration:
-
-```
-CONSUME --> COMPOSE --> LOCK --> BUILD --> DISTRIBUTE
-```
-
-**Consume.** Install packages from any git host. APM resolves the full
-dependency tree and places primitives in the correct directories.
-
-```bash
-apm install microsoft/apm-sample-package
-```
-
-**Compose.** Combine primitives from multiple sources. Your project's
-`apm.yml` is the single source of truth for all agent configuration.
-
-```yaml
-dependencies:
-  apm:
-    - org/team-standards        # company-wide instructions
-    - org/api-patterns          # API development skills
-    - community/security-audit  # open-source prompt
-```
-
-**Lock.** `apm.lock.yaml` pins every dependency to an exact commit. Two developers
-running `apm install` on the same lock file get identical setups.
-
-**Build.** `apm compile` produces optimized output files for each AI tool --
-`AGENTS.md` for Copilot, Cursor, and Codex; `CLAUDE.md` for Claude.
-`apm pack` creates a Claude Code plugin directory by default, or a portable
-APM bundle (`--format apm`) for restore-mode distribution.
-
-```bash
-apm compile
-apm pack
-```
-
-**Distribute.** Any git repository is a valid APM package. Publish by pushing
-to a git remote — no registry required. For offline distribution, CI artifact
-pipelines, or air-gapped environments, use `apm pack` and `apm unpack` to
-create and consume portable bundles without network access.
-
-## Supported tools
-
-APM deploys and compiles agent configuration into the native format of each
-supported tool:
-
-| AI Tool | What `apm install` deploys | What `apm compile` adds | Support level |
-|---|---|---|---|
-| GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** |
-| Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
-| Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/commands/`, skills, hooks, MCP | `.cursor/rules/` (also via compile) | **Full** |
-| OpenCode | `.opencode/agents/`, `.opencode/commands/`, skills, MCP | Via `AGENTS.md` | **Full** |
-| Codex CLI | -- | `AGENTS.md` | Instructions via compile |
-| Gemini | `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json` (MCP, hooks) | `GEMINI.md` (instructions) | **Full** |
-
-For tools with **Full** support, `apm install` deploys all primitives in their
-native format — no additional steps needed. For other tools, `apm compile`
-generates their configuration format from your instructions. See the
-[Compilation guide](../../guides/compilation/) for details.
-
-The output is native. Each tool reads its own format — APM is transparent to
-the AI agent at runtime.
-
-For setup details, see [IDE and Tool Integration](../../integrations/ide-tool-integration/).
-
-## Install from anywhere
-
-APM installs packages from any git host that supports HTTPS or SSH:
-
-```bash
-# GitHub
-apm install microsoft/apm-sample-package
-
-# GitLab
-apm install gitlab.com/org/repo
-
-# Bitbucket
-apm install bitbucket.org/org/repo
-
-# Azure DevOps
-apm install dev.azure.com/org/project/_git/repo
-
-# GitHub Enterprise
-apm install github.example.com/org/repo
-```
-
-Packages are git repositories. If you can clone it, APM can install it.
-
-For authentication setup, see [Authentication](../../getting-started/authentication/).
-
-## Positioning: APM and plugin ecosystems
-
-APM is not a plugin system. It does not compete with GitHub Copilot Extensions,
-Claude plugins, or Cursor features. Those systems define *what agents can do*.
-
-APM is the **governance, composition, and reproducibility layer** that sits
-underneath:
-
-```
-+--------------------------------------------------+
-|  AI Coding Tools                                  |
-|  (Copilot, Claude, Cursor, OpenCode, Codex, Gemini)|
-+--------------------------------------------------+
-|  Plugin / Extension Systems                       |
-|  (tool-specific capabilities)                     |
-+--------------------------------------------------+
-|  APM                                              |
-|  (dependency management, composition, lock files) |
-+--------------------------------------------------+
-|  Git                                              |
-|  (source of truth, distribution)                  |
-+--------------------------------------------------+
-```
-
-APM manages *which* configuration gets deployed, *how* it composes, and
-*whether* everyone on the team has the same setup. The plugin systems handle
-the rest.
-
-## Zero lock-in
-
-APM's output is the native configuration format of each tool. If you stop using
-APM:
-
-- Your `AGENTS.md` still works with Copilot and Codex
-- Your `CLAUDE.md` still works with Claude
-- Your `GEMINI.md` still works with Gemini
-- Your `.cursor/rules/` still work with Cursor
-- Your `.opencode/` files still work with OpenCode
-- Your `.github/prompts/` still work with Copilot
-
-APM adds a dependency management layer. It does not add a runtime dependency.
-The compiled output is plain files that each tool already understands.
-
-## Key value propositions
-
-**Reproducibility.** `apm.lock.yaml` guarantees identical agent setups across
-developers, CI, and environments. No more "works on my machine" for AI
-configuration.
-
-**One-command install.** Clone a repo, run `apm install`, and every primitive
-is in place. Onboarding goes from hours of setup to seconds.
-
-**Composition.** Combine packages from your organization, the community, and
-your own project. APM resolves the full dependency tree.
-
-**Audit and governance.** The lock file is a complete, diffable record of every
-agent configuration dependency. Review it in PRs like any other infrastructure
-change.
-
-**Multi-tool output.** Write your configuration once. APM compiles it for
-every supported AI tool.
-
-## Stability
-
-These surfaces are stable and recommended for production use:
-
-- `apm install`, `apm.lock.yaml`, `apm audit` - dependency resolution, version locking, security scanning.
-- `apm compile`, `apm pack`, `apm install <bundle-path>` - multi-tool output, bundle distribution, and supported local-bundle installation.
-- Authoring layout (`apm.yml`, `.apm/`) and consumption from GitHub, Azure DevOps, GitLab, Bitbucket, and self-hosted Git hosts.
-- Cross-tool deployment to GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, and Gemini.
-
-These surfaces are **experimental** and may change between releases:
-
-- `apm run` and `apm runtime setup` - local execution of agent workflows. Vendor-neutral by design and modeled on what `npx` is to `npm`. Not a current priority for the project; treat as a preview.
-- Microsoft 365 Copilot Cowork target. See [Copilot Cowork](../../integrations/copilot-cowork/).
-
-The dependency-management core does not depend on the experimental runtime surface. If `apm run` is not in your workflow, the stable surface above stands on its own.
-
-## What's next
-
-- [Installation](../../getting-started/installation/) — get APM running in under a minute
-- [Why APM?](../why-apm/) — the problem space in detail
-- [How It Works](../how-it-works/) — architecture and compilation pipeline
-- [Key Concepts](../key-concepts/) — primitives, manifests, and lock files
diff --git a/docs/src/content/docs/introduction/why-apm.md b/docs/src/content/docs/introduction/why-apm.md
deleted file mode 100644
index fbad6c97f..000000000
--- a/docs/src/content/docs/introduction/why-apm.md
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: "Why APM?"
-description: "The problem APM solves — why AI agents need a dependency manager."
-sidebar:
-  order: 2
----
-
-AI coding agents are powerful — but only when they have the right context. Today, setting up that context is entirely manual.
-
-## The Problem
-
-Every AI-assisted project faces the same setup friction:
-
-1. **Manual configuration** — developers copy instruction files, write prompts from scratch, configure MCP servers by hand.
-2. **No portability** — when a new developer clones the repo, none of the AI setup comes with it.
-3. **No dependency management** — if your coding standards depend on another team's standards, there's no way to declare or resolve that relationship.
-4. **Drift** — without a single source of truth, agent configurations diverge across developers and environments.
-
-This is exactly the problem that package managers solved for application code decades ago. `npm`, `pip`, `cargo` — they all provide a manifest, a resolver, and a reproducible install. AI agent configuration deserves the same.
-
-## How APM Solves It
-
-APM introduces `apm.yml` — a declarative manifest for everything your AI agents need:
-
-```yaml
-name: my-project
-version: 1.0.0
-dependencies:
-  apm:
-    - anthropics/skills/skills/frontend-design
-    - microsoft/apm-sample-package
-    - github/awesome-copilot/agents/api-architect.agent.md
-```
-
-Run `apm install` and APM:
-
-- **Resolves transitive dependencies** — if package A depends on package B, both are installed automatically.
-- **Integrates primitives** -- prompts, agents, commands, skills, and hooks are deployed to `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, and `.gemini/` based on which directories exist.
-- **Compiles instructions** -- `apm compile` generates instruction roll-ups (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) that each tool reads natively.
-
-## APM vs. Manual Setup
-
-Consider a project that uses 5 agent plugins across GitHub Copilot and Claude:
-
-**Without APM:**
-
-```bash
-# Every developer, every clone, every time
-git clone my-project && cd my-project
-# Read README for AI setup instructions
-# Manually install plugin A (Copilot)
-# Manually install plugin B (Copilot)
-# Manually install plugin C (Claude)
-# Manually install plugin D (Claude)
-# Manually install plugin E (shared)
-# Hope the versions match what the rest of the team is using
-# Hope you didn't miss a step
-```
-
-**With APM:**
-
-```bash
-git clone my-project && cd my-project
-apm install
-# Done. All 5 plugins resolved and installed.
-```
-
-| | Without APM | With APM |
-|---|---|---|
-| Setup steps | 5+ install commands | 1 command |
-| Version consistency | Hope-based | Lock file enforced |
-| New contributor onboarding | Read docs, follow steps, debug mismatches | `apm install` |
-| CI/CD reproducibility | Fragile or nonexistent | Deterministic via `apm.lock.yaml` |
-| Cross-tool coordination | Manual per tool | Unified manifest |
-
-## What APM Manages
-
-APM handles seven types of agent primitives:
-
-| Primitive | Purpose |
-|-----------|---------|
-| **Instructions** | Coding standards and guardrails |
-| **Skills** | Reusable AI capabilities |
-| **Prompts** | Slash commands and workflows |
-| **Agents** | Specialized personas |
-| **Hooks** | Lifecycle event handlers |
-| **Plugins** | Pre-packaged agent bundles |
-| **MCP Servers** | Tool integrations |
-
-All declared in one manifest. All installed with one command.
-
-## Developer Stories
-
-**Solo / Small Team (2-5 devs)** — "I use Copilot AND Claude. The project needs 5 plugins. Without APM, every new contributor runs 5 install commands and hopes they got the right versions. With APM, they run `apm install`."
-
-**Mid-size Team (10-50 devs)** — "We have org-wide security standards, team-specific plugins, and project-level config. `apm.yml` composes all three layers through dependency resolution. `apm.lock.yaml` ensures every developer and CI runner gets the exact same setup."
-
-**Enterprise (100+ devs)** — "When security asks 'what agent instructions were active when release 4.2.1 shipped?' — `git log apm.lock.yaml` answers that. Every change to agent configuration is versioned, auditable, and reproducible."
-
-## Design Principles
-
-- **Familiar** — APM works like the package managers you already know.
-- **Fast** — install and run in seconds.
-- **Open** — built on [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io), and [MCP](https://modelcontextprotocol.io).
-- **Portable** — install from GitHub, GitLab, Bitbucket, Azure DevOps, or any git host.
-
-## When You Might Not Need APM
-
-APM is not the right tool for every situation:
-
-- **You use a single AI tool with 1-2 plugins** — the overhead of a manifest may not be worth it yet.
-- **You work solo and don't need reproducible setups** — if no one else needs to replicate your environment, manual setup is fine.
-- **Your org doesn't require audit trails for AI agent configuration** — if compliance isn't a concern, the lock file adds little value.
-
-APM shines when complexity grows: multiple tools, team coordination, compliance requirements, or CI/CD integration. Start without it if your setup is simple. Adopt it when manual management becomes a bottleneck.
-
-## FAQ
-
-**"Don't plugins already handle this?"**
-
-Yes, for single-tool installation. APM adds what plugins don't provide: cross-tool install with one command, consumer-side lock files (plugins have none), CI enforcement, and multi-source composition. APM works WITH plugin ecosystems, not against them.
-
-**"Is APM another tool I have to maintain?"**
-
-APM is a dev-time tool. Run `apm install`, get your files, done. There is no runtime process, no background daemon, no maintenance burden. It runs when you ask it to and does nothing otherwise.
-
-**"What if I stop using APM?"**
-
-Delete `apm.yml` and `apm.lock.yaml`. Your `.github/` and `.claude/` config files still work exactly as they did before. APM deploys standard files in standard locations. Zero lock-in by design.
diff --git a/docs/src/content/docs/producer/author-primitives/hooks-and-commands.md b/docs/src/content/docs/producer/author-primitives/hooks-and-commands.md
new file mode 100644
index 000000000..b137297a4
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/hooks-and-commands.md
@@ -0,0 +1,156 @@
+---
+title: Hooks and commands
+description: Two target-specific primitives -- lifecycle hooks and slash commands -- with strict per-harness reach.
+---
+
+Hooks and slash commands are the two APM primitives that do not pretend
+to be portable. Unlike skills or instructions, they ship to a strict
+subset of harnesses, never get folded into `AGENTS.md`, and rely on
+each target's own format. Author them when the value to a specific
+harness justifies the per-target maintenance.
+
+This page covers both. For the cross-harness reach map, see
+[Primitives and targets](../../../concepts/primitives-and-targets/).
+For dev-only versus prod separation in the manifest, see
+[Dev-only primitives](../../../guides/dev-only-primitives/).
+
+## Why they are target-specific
+
+A skill is a markdown file APM can route to seven harnesses. A hook
+is a runtime callback fired by one harness inside its own tool loop.
+A slash command is a command-palette entry surfaced by an IDE.
+Neither generalizes: nothing reaches `AGENTS.md`, nothing routes to
+harnesses that lack the concept. Unsupported targets are silently
+skipped, not errors. Treat both as opt-in surface, not as your
+primary distribution path.
+
+## Hooks
+
+Source layout. APM discovers hook JSON files in either of two
+directories at the package root:
+
+```
+your-package/
++-- .apm/
+|   +-- hooks/
+|       +-- pretool-validate.json
++-- hooks/                      # also discovered (Claude-native layout)
+    +-- post-edit-format.json
+```
+
+Each file is a JSON document keyed by lifecycle event. APM accepts the
+Claude (`PreToolUse`, `PostToolUse`) and Copilot (`preToolUse`,
+`postToolUse`) shapes; events are renamed per target during merge.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {"type": "command", "command": "${PLUGIN_ROOT}/scripts/validate.sh", "timeout": 10}
+        ]
+      }
+    ]
+  }
+}
+```
+
+The `${PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_ROOT}`, and `${CURSOR_PLUGIN_ROOT}`
+tokens resolve to the installed package root and are rewritten per
+target. Plain `./script.sh` resolves relative to the hook file.
+
+Supported targets and where the integrator writes:
+
+| Target   | Output                                | Mode                 |
+|----------|---------------------------------------|----------------------|
+| copilot  | `.github/hooks/<pkg>-<name>.json`     | one file per hook    |
+| claude   | `.claude/settings.json`               | merged into settings |
+| cursor   | `.cursor/hooks.json`                  | merged               |
+| gemini   | `.gemini/settings.json`               | merged               |
+| codex    | `.codex/hooks.json`                   | merged               |
+| windsurf | `.windsurf/hooks.json`                | merged               |
+| opencode | -- not supported --                   | silently skipped     |
+
+Copilot hook files are namespaced with the source package name to avoid
+collisions across installed deps; bundled scripts land alongside under
+`.github/hooks/scripts/<pkg>/`.
+
+Verified against `src/apm_cli/integration/targets.py` and
+`src/apm_cli/integration/hook_integrator.py`.
+
+## Commands
+
+Slash commands share their source with prompts. There is no
+`.apm/commands/` directory:
+
+```
+your-package/
++-- .apm/
+    +-- prompts/
+        +-- review-pr.prompt.md   # also routes as a slash command
+```
+
+Frontmatter the command integrator preserves: `description`,
+`allowed-tools`, `model`, `argument-hint`, `input`. Other keys (for
+example `author`, `mcp`, `parameters`) are dropped during the
+transform and surfaced as install-time diagnostics.
+
+```markdown
+---
+description: Review the current PR for security regressions.
+allowed-tools: [Read, Grep]
+argument-hint: "[pr-number]"
+input:
+  - name: pr_number
+    description: The PR number to review.
+---
+
+Review pull request #$pr_number. Focus on auth and input handling.
+```
+
+Supported targets and output paths:
+
+| Target   | Output                           | Format                |
+|----------|----------------------------------|-----------------------|
+| claude   | `.claude/commands/<name>.md`     | native markdown       |
+| cursor   | `.cursor/commands/<name>.md`     | claude-format subset  |
+| opencode | `.opencode/commands/<name>.md`   | opencode markdown     |
+| gemini   | `.gemini/commands/<name>.toml`   | TOML                  |
+| windsurf | `.windsurf/workflows/<name>.md`  | called "workflows"    |
+| copilot  | -- not a command --              | ships as a prompt     |
+| codex    | -- not supported --              | silently skipped      |
+
+Verified against `src/apm_cli/integration/targets.py` and
+`src/apm_cli/integration/command_integrator.py`.
+
+## When NOT to use these
+
+Reach for a skill, instruction, or prompt first. Use hooks or commands
+only when the behavior is a runtime callback (hook) or a
+command-palette entry (command), you accept that consumers on Copilot,
+Codex, or OpenCode will not get them, and you will own per-target
+formats. "Run a script before every tool call" fits a hook. "Give the
+agent a procedure" fits a skill -- and reaches every harness.
+
+## Pitfalls
+
+- **Hook event names.** Author in Claude or Copilot conventions only.
+  The integrator renames; arbitrary event names will not be mapped.
+- **Cursor command frontmatter loss.** Cursor reuses the Claude
+  command transformer today, so any prompt-only metadata is dropped
+  with a diagnostic. Keep Cursor commands to the preserved key set.
+- **Script paths.** Use `${PLUGIN_ROOT}` (or the harness-specific
+  alias) for scripts that ship inside the package. Plain absolute
+  paths break on consumers' machines.
+- **Same `.prompt.md` is two primitives.** A single
+  `.apm/prompts/foo.prompt.md` becomes Copilot's prompt and Claude's
+  `/foo` command in the same install. Name files with both surfaces
+  in mind.
+- **OpenCode and hooks.** OpenCode has no hooks concept. Do not author
+  a Claude+OpenCode package and assume hooks reach both -- they do
+  not. The install log notes the skip.
+
+Once your hooks and commands are in place, run `apm compile` to
+preview what each target will receive, then `apm pack` to bundle.
+See [Compile](../../compile/) and [Pack a bundle](../../pack-a-bundle/).
diff --git a/docs/src/content/docs/producer/author-primitives/index.md b/docs/src/content/docs/producer/author-primitives/index.md
new file mode 100644
index 000000000..2379cbc5b
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/index.md
@@ -0,0 +1,54 @@
+---
+title: Author primitives
+description: The primitive types you can ship in an APM package and where each maps on each target harness.
+sidebar:
+  order: 0
+---
+
+A package's `.apm/` directory contains primitives. Each primitive type is an opinion about how a piece of agent context should be authored once and projected onto every supported target (Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf).
+
+## Primitive types
+
+| Primitive       | One-liner                                                                | Page                                              |
+|-----------------|--------------------------------------------------------------------------|---------------------------------------------------|
+| Skills          | Self-contained capability bundles with `SKILL.md` + scripts + assets     | [Skills](./skills/)                               |
+| Prompts         | Reusable prompt templates with frontmatter                               | [Prompts](./prompts/)                             |
+| Instructions    | Long-lived behavior rules (style guides, conventions)                    | [Instructions and agents](./instructions-and-agents/) |
+| Agents          | Personas with explicit scope, tools, and triggers                        | [Instructions and agents](./instructions-and-agents/) |
+| Hooks           | Event handlers fired by the runtime (pre-commit, on-tool-use, ...)       | [Hooks and commands](./hooks-and-commands/)       |
+| Commands        | Slash-command shortcuts the developer types into the agent UI            | [Hooks and commands](./hooks-and-commands/)       |
+| MCP servers     | Tool-server declarations consumers can wire into their harness           | [MCP as a primitive](./mcp-as-primitive/)         |
+
+## On-disk layout
+
+```text
+.apm/
+  skills/
+    my-skill/
+      SKILL.md
+      scripts/
+      references/
+      assets/
+  prompts/
+    review.prompt.md
+  instructions/
+    style.instructions.md
+  agents/
+    cli-logging-expert.agent.md
+  hooks/
+    pre-commit.hook.md
+  commands/
+    deploy.command.md
+```
+
+Every primitive type follows the same pattern: a markdown file (or directory containing a primary markdown file) with frontmatter declaring its name and its trigger conditions. `apm compile` reads `.apm/`, applies any policy, and writes per-target output to the right directories on the target's filesystem.
+
+## Recommended reading order
+
+1. [Skills](./skills/) -- the densest primitive type and the one most newcomers hit first.
+2. [Prompts](./prompts/) -- next-most-common; how reusable templates work.
+3. [Instructions and agents](./instructions-and-agents/) -- when behavior should persist across sessions.
+4. [Hooks and commands](./hooks-and-commands/) -- runtime extension points.
+5. [MCP as a primitive](./mcp-as-primitive/) -- when your package needs to bring along a tool server.
+
+When you're ready to ship, continue to [Compile](../compile/) and [Pack a bundle](../pack-a-bundle/).
diff --git a/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md b/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
new file mode 100644
index 000000000..d4c32a875
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
@@ -0,0 +1,213 @@
+---
+title: Instructions and agents
+description: Author scope-attached rules and persona scoping modules that compile to every supported harness.
+---
+
+These two primitives pair naturally. An **instruction** is a
+scope-attached rule: a coding standard, naming convention, or review
+checklist that fires when the agent touches files matching a glob. An
+**agent** is a persona scoping module: a named specialist (security
+reviewer, migration assistant, on-call SRE) the user invokes
+explicitly. Instructions shape *how* the model behaves on any given
+file. Agents shape *who* the model becomes when summoned.
+
+Reach across harnesses differs and matters when you choose. See
+[Primitives and targets](../../../concepts/primitives-and-targets/)
+for the full matrix; the gist is below.
+
+## Instructions
+
+A unit of policy that travels with a glob. Authors write one rule;
+APM compiles it to whatever frontmatter and directory the harness
+expects.
+
+### Layout
+
+```
+my-package/
+  apm.yml
+  .apm/
+    instructions/
+      python-style.instructions.md
+      pr-review-checklist.instructions.md
+```
+
+File names end in `.instructions.md`. The basename (minus the double
+extension) becomes the deployed filename stem.
+
+### Frontmatter
+
+```markdown
+---
+description: Python style rules enforced on src/ and tests/
+applyTo: "**/*.py"
+---
+
+- Use `pathlib.Path`, never `os.path`.
+- Tests live next to the module under `tests/<module>/`.
+- ...
+```
+
+| Key | Required | Purpose |
+|---|---|---|
+| `description` | yes | One-line summary; used in compiled context indexes |
+| `applyTo` | yes for instructions | Glob (or comma-separated globs) the rule binds to |
+
+`applyTo` is the load-bearing field. Without it the rule is treated as
+unconditional and gets folded into compiled context files
+(`AGENTS.md`, `GEMINI.md`) instead of a per-file rule directory. With
+it, each harness wraps the body in its own scoping syntax.
+
+### Body conventions
+
+- Lead with bullets, not prose. Instructions are read by an agent
+  mid-task.
+- One topic per file. Split `python-style` and `python-testing`; do
+  not co-mingle.
+- Cite paths inside the repo with backticks; do not assume any other
+  context is loaded.
+- Skip greetings and meta ("In this file we will..."). State the rule.
+
+### What compiles where
+
+| Target | Output path | Transform |
+|---|---|---|
+| copilot | `.github/instructions/<name>.instructions.md` | verbatim; `applyTo` preserved |
+| claude | `.claude/rules/<name>.md` | `applyTo` -> `paths:` list |
+| cursor | `.cursor/rules/<name>.mdc` | `applyTo` -> `globs:`; description auto-derived if missing |
+| windsurf | `.windsurf/rules/<name>.md` | `applyTo` -> `trigger: glob` + `globs:`; missing `applyTo` -> `trigger: always_on` |
+| codex | folded into `AGENTS.md` | compile-only, no per-file deploy |
+| gemini | folded into `GEMINI.md` | compile-only, no per-file deploy |
+| opencode | folded into `AGENTS.md` | compile-only, no per-file deploy |
+
+Source: `src/apm_cli/integration/instruction_integrator.py`,
+`src/apm_cli/integration/targets.py`.
+
+## Agents
+
+A specialist persona invoked by name, with optional model and tool
+constraints. Think of it as a callable role -- the user types
+`@security-review` and the harness loads the body as system context.
+
+### Layout
+
+```
+my-package/
+  apm.yml
+  .apm/
+    agents/
+      security-review.agent.md
+      migration-assistant.agent.md
+```
+
+File names end in `.agent.md`. APM also accepts `.chatmode.md` and the
+legacy `.apm/chatmodes/` directory for backward compatibility; new
+work should use `.agent.md` under `.apm/agents/`.
+
+### Frontmatter
+
+```markdown
+---
+name: security-review
+description: Reviews diffs for OWASP top-10 issues and missing input validation.
+model: gpt-5
+tools:
+  - read
+  - grep
+---
+
+You are a security reviewer. Your job is to inspect the working diff
+for...
+```
+
+| Key | Required | Purpose |
+|---|---|---|
+| `name` | recommended | Display name; defaults to filename stem |
+| `description` | yes | Used by Cascade and Copilot to decide when to surface the agent |
+| `model` | optional | Pinned model the harness should switch to when invoked |
+| `tools` | optional | Whitelist of tools the persona may call |
+
+`model` and `tools` reach Copilot, Claude, Cursor, and OpenCode
+verbatim. Codex receives a TOML translation. Windsurf drops both
+fields and emits a diagnostic warning at install time -- its skill
+format does not support per-persona model or tool scoping.
+
+### Body conventions
+
+- Open with role and scope in two sentences. The harness uses this as
+  the system prompt.
+- Define what the persona will and will not do. Boundaries make
+  agents useful.
+- List the artifacts it expects ("the open PR diff", "the failing
+  test name") and what it returns ("a markdown review with file:line
+  citations").
+- Keep the body under 300 lines. Long agents drown the harness's
+  context window before the user's task even loads.
+
+### What compiles where
+
+| Target | Output path | Transform |
+|---|---|---|
+| copilot | `.github/agents/<name>.agent.md` | verbatim |
+| claude | `.claude/agents/<name>.md` | verbatim |
+| cursor | `.cursor/agents/<name>.md` | verbatim |
+| opencode | `.opencode/agents/<name>.md` | verbatim |
+| codex | `.codex/agents/<name>.toml` | YAML frontmatter -> TOML; body becomes `developer_instructions` |
+| windsurf | `.windsurf/skills/<name>/SKILL.md` | reformatted as a Cascade skill; `model`/`tools` dropped with a warning |
+| gemini | not deployed | Gemini CLI has no agents primitive |
+
+Source: `src/apm_cli/integration/agent_integrator.py`,
+`src/apm_cli/integration/targets.py`.
+
+## Choosing one or the other
+
+Pick **instructions** when:
+
+- The rule applies to a *file pattern*, not a workflow.
+- You want the agent to follow it implicitly, without being summoned.
+- The content is short, declarative, and reviewable as policy.
+
+Pick **agents** when:
+
+- A user needs to *invoke* a specialist on demand.
+- The behaviour involves a sequence of steps, decisions, or model
+  switches, not a static rule.
+- You want to scope tool access (e.g. read-only review persona).
+
+Many packages ship both: instructions for the always-on guardrails,
+plus one or two agents for the deeper workflows that warrant a
+dedicated persona.
+
+## Common pitfalls
+
+- **Missing `applyTo`.** An instruction without `applyTo` stops being
+  scope-attached and gets folded into the compiled context file. If
+  you wanted Cursor or Copilot to scope it to `**/*.ts`, the rule
+  will not bind.
+- **Agent named `default` or `start`.** These collide with script
+  resolution in `apm run`. Pick a descriptive name.
+- **`model:` and `tools:` on a Windsurf-targeted agent.** Cascade has
+  no equivalent; APM warns and drops them. If those constraints are
+  load-bearing, do not target windsurf for that agent -- ship it as
+  an instruction instead, or restrict the package's `targets:`.
+- **Agent body that re-states global instructions.** Agents inherit
+  the workspace's compiled context. Restate only what the persona
+  needs to *override* or *add*; do not duplicate `python-style`
+  inside `code-reviewer.agent.md`.
+- **Co-mingling rules and persona.** A 600-line `.agent.md` that
+  contains style rules, review checklist, and persona prompt is two
+  primitives in a trench coat. Split it.
+
+## Verify before shipping
+
+```bash
+apm compile --validate           # frontmatter + structure check, no writes
+apm compile --target cursor      # see exactly what lands in .cursor/
+apm preview <script>             # if the agent is wired to a script
+```
+
+For the full primitive catalogue and target matrix, see
+[Primitives and targets](../../../concepts/primitives-and-targets/).
+For prompts and slash-commands, see
+[Prompts](../prompts/). For packing and publishing, see
+[Pack a bundle](../../pack-a-bundle/).
diff --git a/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md b/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md
new file mode 100644
index 000000000..5f78a0c0e
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md
@@ -0,0 +1,170 @@
+---
+title: "MCP servers as a primitive"
+description: "Ship MCP server configuration with your APM package so consumers get it wired into every harness on apm install."
+---
+
+When a consumer runs `apm install` against your package, the `mcp:`
+block in your `apm.yml` becomes their MCP server config. No README
+copy-paste, no per-harness JSON. This page is the producer side of
+[Install MCP servers](../../../consumer/install-mcp-servers/).
+
+## One-line answer
+
+Add a `dependencies.mcp:` section to your package's `apm.yml`:
+
+```yaml
+dependencies:
+  mcp:
+    - io.github.github/github-mcp-server
+```
+
+On the consumer's machine, `apm install <your-package>` writes this
+into every detected harness's MCP config file.
+
+## What "MCP as a primitive" means here
+
+[Primitives and targets](../../../concepts/primitives-and-targets/)
+lists MCP servers as a primitive APM routes per target. Unlike
+`.apm/skills/` or `.apm/prompts/`, MCP servers do not live as files in
+your package -- they live as **declarations** in `apm.yml`. APM
+materialises them at install time into the harness-specific config
+file (see the per-harness map in
+[Install MCP servers](../../../consumer/install-mcp-servers/#what-apm-install-writes-to-disk)).
+
+You declare once. APM writes `.vscode/mcp.json`, `.cursor/mcp.json`,
+`~/.claude.json`, `~/.codex/config.toml`, and the rest -- whichever
+harnesses the consumer has.
+
+## The `mcp:` schema
+
+Each entry under `dependencies.mcp:` (or `devDependencies.mcp:`) is
+either a bare string or a mapping. Fields, from
+`src/apm_cli/models/dependency/mcp.py`:
+
+| Field | Required when | Notes |
+|---|---|---|
+| `name` | always (mapping form) | Matches `^[a-zA-Z0-9@_][a-zA-Z0-9._@/:=-]{0,127}$`. |
+| `transport` | self-defined | One of `stdio`, `http`, `sse`, `streamable-http`. |
+| `command` | self-defined `stdio` | Single binary path; no whitespace (use `args`). |
+| `args` | optional | List for self-defined; dict for registry overlays. |
+| `url` | self-defined `http`/`sse`/`streamable-http` | `http://` or `https://` only. |
+| `env` | optional, stdio | Map of env vars passed to the child process. |
+| `headers` | optional, remote | Map of HTTP headers. CR/LF rejected. |
+| `tools` | optional | Allowlist of tool names. Default `["*"]`. |
+| `version` | optional | Pin a registry server version. |
+| `registry` | optional | `false` = self-defined; URL = custom registry. |
+| `package` | optional | `npm`, `pypi`, or `oci` for registry-resolved servers. |
+
+Three forms cover every case:
+
+```yaml
+dependencies:
+  mcp:
+    # 1. Registry reference -- resolved from api.mcp.github.com
+    - io.github.github/github-mcp-server
+
+    # 2. Self-defined stdio
+    - name: filesystem
+      registry: false
+      transport: stdio
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
+
+    # 3. Self-defined remote
+    - name: linear
+      registry: false
+      transport: http
+      url: https://mcp.linear.app/sse
+      headers:
+        Authorization: "Bearer ${LINEAR_TOKEN}"
+```
+
+## What the consumer sees on install
+
+For each detected harness, APM writes the relevant MCP config file.
+The full mapping (file path, scope, JSON/TOML schema) is in
+[Install MCP servers](../../../consumer/install-mcp-servers/#what-apm-install-writes-to-disk).
+You do not need to know it to author -- APM handles the per-target
+translation.
+
+The consumer can run `apm mcp list` to confirm the server landed in
+each runtime they care about.
+
+## Secrets: never commit, always indirect
+
+Treat `apm.yml` like `package.json`: it is committed, reviewed, and
+shipped. Do not embed tokens. Two patterns work:
+
+```yaml
+# Env-var indirection -- the harness expands at runtime
+- name: linear
+  registry: false
+  transport: http
+  url: https://mcp.linear.app/sse
+  headers:
+    Authorization: "Bearer ${LINEAR_TOKEN}"
+
+# Stdio env -- value passed verbatim; use ${VAR} for indirection
+- name: my-internal
+  registry: false
+  transport: stdio
+  command: my-server
+  env:
+    API_TOKEN: "${MY_API_TOKEN}"
+```
+
+Headers and env values are not shell-expanded by APM -- the harness
+does that when it spawns the server or makes the request. Keep the
+real secret in the consumer's environment (or their secret manager).
+
+The `github-mcp-server` is a special case: APM injects an
+`Authorization: Bearer <token>` header automatically when it writes
+the Copilot CLI config. See
+[Token injection](../../../consumer/install-mcp-servers/#token-injection-github-mcp-server).
+
+## Direct vs transitive: the trust boundary
+
+A self-defined MCP server (`registry: false`) declared by your package
+is trusted only when your package is a **direct** dependency of the
+consumer. If your package is pulled in transitively, APM warns and
+**skips** the MCP entry unless the consumer passes
+`--trust-transitive-mcp`. Source:
+`src/apm_cli/integration/mcp_integrator.py:124-145`.
+
+Implications for producers:
+
+- Registry-resolved servers (form 1 above) flow through transitively
+  without a trust prompt -- they are vetted by the registry.
+- Self-defined `stdio` and remote servers should be reserved for
+  things the consumer would expect from a direct dependency.
+- Document any self-defined MCP server in your README so a transitive
+  consumer knows what they would be trusting.
+
+For the full trust model, see
+[Lifecycle](../../../concepts/lifecycle/) and
+[Security](../../../enterprise/security/).
+
+## Pitfalls
+
+- **Whitespace in `command`**: APM does not split on spaces. Put the
+  binary in `command` and arguments in `args`. Validation rejects
+  `command: "npx -y server"` with a fix-it message.
+- **Hard-coded paths**: `command: /Users/me/bin/server` works on your
+  laptop and nowhere else. Prefer a binary on `PATH` (`npx`, `uvx`)
+  or a runtime-installed package.
+- **`url:` with non-`http(s)` scheme**: rejected at parse time.
+  WebSocket and `file://` are not supported transports.
+- **Embedded tokens in `headers` or `env` literals**: a reviewer will
+  see them. Use `${VAR}` indirection.
+- **Forgetting `devDependencies.mcp:`**: an MCP server you only need
+  for development (a local mock, a debug bridge) belongs in
+  `devDependencies.mcp:`. `apm pack` excludes it; consumers do not
+  get it. See
+  [dev-only primitives](../../../guides/dev-only-primitives/).
+
+## Next
+
+- Bundle other primitives alongside MCP servers --
+  [skills](../skills/), [prompts](../prompts/),
+  [hooks and commands](../hooks-and-commands/).
+- Pack and ship -- [Pack a bundle](../../pack-a-bundle/).
diff --git a/docs/src/content/docs/producer/author-primitives/prompts.md b/docs/src/content/docs/producer/author-primitives/prompts.md
new file mode 100644
index 000000000..c42b971ed
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/prompts.md
@@ -0,0 +1,145 @@
+---
+title: Author a prompt
+description: Ship a parameterized, single-purpose AI workflow as a .prompt.md primitive that compiles to every harness's slash-command format.
+---
+
+A prompt is a single-purpose, parameterized AI workflow. Write one
+Markdown file with frontmatter; APM deploys it as a Copilot prompt,
+a Claude `/command`, a Cursor command, an OpenCode command, a Gemini
+TOML command, and a Windsurf workflow.
+
+Use a prompt when the consumer invokes the workflow on demand
+("review this PR", "draft a release note"). Use a
+[skill](../skills/) when the harness should auto-discover a
+meta-guide mid-conversation. Prompts are called; skills are reached
+for.
+
+## File layout
+
+Place prompt files under `.apm/prompts/`. The base filename becomes
+the command name on every target.
+
+```
+my-package/
+  apm.yml
+  .apm/
+    prompts/
+      review-pr.prompt.md       # -> /review-pr
+      release-notes.prompt.md   # -> /release-notes
+```
+
+Files at the package root (`<pkg>/*.prompt.md`) are also discovered
+for backward compatibility, but `.apm/prompts/` is canonical and
+what `apm init` scaffolds.
+
+## Frontmatter
+
+Five keys are preserved by the cross-tool transform. Anything else
+is dropped at compile time and surfaced via diagnostics so consumers
+on lossy targets see a warning, not silent data loss.
+
+| Key | Type | Purpose |
+|---|---|---|
+| `description` | string | One-line summary; shown in command pickers. Required for discoverability. |
+| `input` | list | Argument names the prompt reads. Simple list (`[name, scope]`) or object list (`- name: "what it is"`). |
+| `allowed-tools` | list | Tool allow-list (Claude/Cursor honor this; Copilot ignores it). |
+| `model` | string | Preferred model slug (Claude/Cursor only). |
+| `argument-hint` | string | Free-form hint shown in the picker; auto-derived from `input` when omitted. |
+
+Reference inputs in the body with `${input:name}`. The compiler
+rewrites these per target (for example, `$name` for Claude
+commands).
+
+```markdown
+---
+description: Review a pull request against our coding standards.
+input:
+  - pr_url: "URL of the PR to review"
+  - focus: "Optional focus area (e.g. security, perf)"
+allowed-tools: [Bash, Read, Grep]
+---
+
+# Review PR ${input:pr_url}
+
+You are reviewing the changes in ${input:pr_url}. Focus on
+${input:focus} when set; otherwise apply the full checklist.
+
+1. Fetch the diff.
+2. Flag any deviation from `.github/CONTRIBUTING.md`.
+3. Summarize blockers, suggestions, and nits in three sections.
+```
+
+## Body conventions
+
+One prompt, one focused intent. If the body branches into "if asked
+X do Y; if asked Z do W", split it. The picker on every target is
+flat -- many small prompts beat one big one.
+
+Write to the model in the second person and lead with the verb. The
+body is delivered verbatim into a chat session.
+
+## Where it lands per target
+
+`apm install` (or `apm compile`) routes one source file to every
+detected harness. Verified against
+[`src/apm_cli/integration/targets.py`](https://github.com/microsoft/apm/blob/main/src/apm_cli/integration/targets.py)
+and `command_integrator.py`.
+
+| Target | Output path | Format |
+|---|---|---|
+| copilot | `.github/prompts/<name>.prompt.md` | verbatim copy |
+| claude | `.claude/commands/<name>.md` | `/command`, inputs become `$arg` |
+| cursor | `.cursor/commands/<name>.md` | shared command transform |
+| opencode | `.opencode/commands/<name>.md` | shared command transform |
+| gemini | `.gemini/commands/<name>.toml` | TOML command |
+| windsurf | `.windsurf/workflows/<name>.md` | workflow |
+| codex | (none) | Codex has no prompts or commands primitive |
+
+For the broader primitive-by-target reach map, see
+[Primitives and targets](../../../concepts/primitives-and-targets/).
+
+## How a consumer invokes it
+
+After `apm install`, the prompt is reachable from each harness's
+native command surface. No separate registration step.
+
+```
+Copilot   open the prompts picker; select "review-pr"
+Claude    /review-pr <pr_url> <focus>
+Cursor    /review-pr ...
+OpenCode  /review-pr ...
+Gemini    /review-pr ...
+Windsurf  /review-pr (from the workflows menu)
+```
+
+A producer who also ships a runnable script can wire the prompt into
+`apm.yml`'s `scripts:` block so consumers can bypass the picker:
+
+```yaml
+scripts:
+  review: copilot --prompt .apm/prompts/review-pr.prompt.md
+```
+
+`apm run review --param pr_url=https://...` compiles the prompt with
+the parameter bound and invokes the harness. See
+[Lifecycle: RUN](../../../concepts/lifecycle/) for the rewrite rules.
+
+## Pitfalls
+
+- **Non-preserved frontmatter is dropped.** Keys like `author`,
+  `mcp`, or `parameters` survive on Copilot (verbatim copy) but are
+  stripped on Claude/Cursor/OpenCode/Gemini/Windsurf. APM logs a
+  diagnostic at install time. Keep authoritative metadata to the
+  five preserved keys.
+- **Input names must match `[A-Za-z][\w-]{0,63}`.** Other entries
+  are rejected with a warning at integrate time and never reach the
+  command frontmatter.
+- **Codex receives nothing.** Do not assume a prompt is universal.
+  If Codex coverage matters, ship the same workflow as a
+  [skill](../skills/) -- skills route to all seven harnesses.
+- **One file, one command name.** Two prompts with the same base
+  filename in `.apm/prompts/` and at the package root collide; the
+  later writer wins on copilot and the transform fails on
+  Claude/Cursor. Pick a location and stick to it.
+- **`apm compile` does not re-scan for hidden Unicode.** Edits
+  between installs are not gated. Run `apm audit` before publishing.
diff --git a/docs/src/content/docs/producer/author-primitives/skills.md b/docs/src/content/docs/producer/author-primitives/skills.md
new file mode 100644
index 000000000..712dd171e
--- /dev/null
+++ b/docs/src/content/docs/producer/author-primitives/skills.md
@@ -0,0 +1,159 @@
+---
+title: Author a skill
+description: Write a SKILL.md primitive APM can install, scan, lock, and deploy across every supported harness.
+---
+
+A **skill** is a model-invoked guide. The agent picks it up at runtime
+based on its `description`, reads `SKILL.md`, and follows the body to
+do a focused task. The format is the cross-tool agent-skills standard
+(SKILL.md plus optional bundled resources). APM is the package manager
+for skills, not the spec; for the full primitive matrix see
+[Primitives and targets](../../../concepts/primitives-and-targets/).
+
+## Folder layout
+
+Author every skill in its own directory under `.apm/skills/`:
+
+```
+.apm/skills/
++-- code-review-expert/
+    +-- SKILL.md           # required: the skill itself
+    +-- scripts/           # optional: executable helpers
+    +-- references/        # optional: deep-dive context the skill loads on demand
+    +-- assets/            # optional: templates, images, fixtures
+    +-- examples/          # optional: sample inputs and outputs
+```
+
+The directory name is the skill's identity. `SKILL.md` is the only
+required file; the four conventional subdirectories ship as-is when
+APM copies the skill to a target. Single-skill repositories may also
+place `SKILL.md` at the package root.
+
+## Frontmatter contract
+
+```yaml
+---
+name: code-review-expert
+description: Use when the user asks for a code review, PR feedback, or a diff walkthrough on a Python or TypeScript change. Loads project conventions from references/ before commenting.
+---
+```
+
+### `name`
+
+- Lowercase alphanumeric and hyphens only (`a-z`, `0-9`, `-`).
+- 1 to 64 characters.
+- No consecutive hyphens, no leading or trailing hyphen.
+- Must equal the parent directory name. APM derives `name` from the
+  directory when frontmatter omits it; if both are present and
+  disagree, the directory wins on disk and your declared `name` is
+  ignored.
+
+Verified in `src/apm_cli/integration/skill_integrator.py`
+(`validate_skill_name`) and `src/apm_cli/primitives/parser.py`
+(`parse_skill_file` derives `name` from `file_path.parent.name`).
+
+### `description`
+
+APM does not validate the description body, but the agent-skills
+standard does, and runtimes use it to decide when to invoke the
+skill. Four rules:
+
+1. **Imperative.** Start with a verb that names the user action
+   ("Use when", "Apply when"), not the skill ("This skill helps
+   you...").
+2. **Intent-first.** Lead with the user's intent, then the trigger
+   conditions, then any constraints. Runtimes match on the first
+   sentence.
+3. **Indirect triggers.** Describe situations, not slash-commands.
+   "Use when reviewing a Terraform PR" beats "Run /tf-review".
+4. **<= 1024 characters.** Hard ceiling in the agent-skills spec.
+   Anything longer truncates at runtime on some harnesses.
+
+A bad description ("Helps with code") collides with every other
+skill. A good description names the trigger so the runtime can
+disambiguate.
+
+## Body budget
+
+Keep `SKILL.md` under **500 lines and 5000 tokens**. This is the
+agent-skills convention, not an APM check, but every harness pays a
+context-window tax for an oversized body. Overflow goes into
+`references/<topic>.md` files that the body loads explicitly:
+
+```markdown
+## Project conventions
+
+For the full naming policy, LOAD references/naming.md.
+For migration steps, LOAD references/migrations.md.
+```
+
+The `LOAD references/<file>` line is a convention the agent recognizes
+and follows. Bundle deep context, edge cases, and rare-path runbooks
+in `references/`; keep `SKILL.md` to the always-relevant flow.
+
+## Where it lands per target
+
+`apm install` and `apm compile` deploy each skill folder to one
+directory per active target. Routing is verified in
+`src/apm_cli/integration/targets.py`.
+
+| Target            | Deploy directory                             |
+|-------------------|----------------------------------------------|
+| `claude`          | `.claude/skills/<name>/SKILL.md`             |
+| `windsurf`        | `.windsurf/skills/<name>/SKILL.md`           |
+| `copilot`         | `.agents/skills/<name>/SKILL.md`             |
+| `cursor`          | `.agents/skills/<name>/SKILL.md`             |
+| `codex`           | `.agents/skills/<name>/SKILL.md`             |
+| `gemini`          | `.agents/skills/<name>/SKILL.md`             |
+| `opencode`        | `.agents/skills/<name>/SKILL.md`             |
+| `agent-skills`    | `.agents/skills/<name>/SKILL.md` (explicit)  |
+
+Five harnesses converge on the cross-tool `.agents/skills/`
+directory. Claude and Windsurf keep harness-native paths because
+their runtimes scan their own roots. The whole skill folder is
+copied (`shutil.copytree`), so `scripts/`, `references/`, `assets/`,
+and `examples/` ride along. Symlinks and the `.apm-pin` cache marker
+are filtered out (`src/apm_cli/security/gate.py:ignore_non_content`).
+
+To restore the pre-convergence layout where every harness gets its
+own `.<harness>/skills/` copy, pass `--legacy-skill-paths` or set
+`APM_LEGACY_SKILL_PATHS=1`.
+
+## Preview before you commit
+
+Two commands answer "what will this look like once installed?":
+
+```bash
+apm compile --validate          # parse frontmatter and structure; no writes
+apm compile --dry-run           # print every placement decision; no writes
+apm compile --target claude     # write only one target so you can diff
+```
+
+`apm compile --validate` is the fast lint loop. `--dry-run` shows the
+full routing table for the current set of detected harnesses.
+Targeting a single harness lets you inspect the actual file APM
+would deploy without touching the others. See
+[Compile](../../compile/) and
+[Preview and validate](../../preview-and-validate/) for the broader
+flow, and [Lifecycle](../../../concepts/lifecycle/) for where
+compile sits between install and run.
+
+## Common pitfalls
+
+- **Description collision.** Two skills whose descriptions both start
+  with "Helps with code" will fight for the same triggers.
+  Lead with the verb plus the situation, not the skill's name.
+- **Directory name drift.** If `name:` in frontmatter does not match
+  the parent directory, the directory name wins on disk. Rename the
+  directory or the frontmatter, not both halfway.
+- **Oversized body.** A 2000-line `SKILL.md` blows past every
+  runtime's recommended budget and pushes other context out of the
+  window. Move the long tail into `references/` and load it on
+  demand.
+- **Hidden files in the bundle.** `apm install` runs the hidden-Unicode
+  scan over every primitive before deploy. A zero-width character in a
+  reference file blocks the install for every consumer. Run
+  `apm audit --file .apm/skills/<name>/SKILL.md` while authoring.
+- **Setting `target: vscode` in `apm.yml`.** There is no `vscode`
+  target. Use `targets:` (plural) with slugs from the table above, or
+  let auto-detection pick.
diff --git a/docs/src/content/docs/producer/compile.md b/docs/src/content/docs/producer/compile.md
new file mode 100644
index 000000000..b739c296c
--- /dev/null
+++ b/docs/src/content/docs/producer/compile.md
@@ -0,0 +1,165 @@
+---
+title: Compile your package
+description: Roll your instructions primitives into AGENTS.md / CLAUDE.md / GEMINI.md style root context files for every supported harness, without touching dependencies.
+---
+
+`apm compile` reads your **instructions** primitives from `.apm/`
+(plus any unpacked under `apm_modules/`) and writes the per-harness
+root context files each agent harness reads at startup. It does not
+fetch packages, does not resolve dependencies, does not write the
+lockfile, and does not deploy other primitive types.
+
+:::note[When you actually need it]
+Compile is **optional for the `copilot` target** -- GitHub Copilot
+natively reads `.github/instructions/*.instructions.md` (with their
+`applyTo:` frontmatter) that `apm install` already deploys, so the
+aggregated `AGENTS.md` / `copilot-instructions.md` it produces are a
+nice-to-have, not a requirement.
+
+Compile is **recommended for every other target** (`claude`,
+`cursor`, `codex`, `gemini`, `opencode`, `windsurf`) -- those
+harnesses load instructions through the root context file
+(`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) or a harness-specific rules
+folder that compile generates. Without it, your instructions are
+on disk but the harness will not pick them up.
+:::
+
+```bash
+apm compile
+```
+
+Concretely, that command rolls your `instructions/*.instructions.md`
+(see [Instructions](./author-primitives/instructions-and-agents/#1-instructions))
+into the native rules surface each target expects:
+
+- `AGENTS.md` -- the cross-harness root context file (Copilot, Codex,
+  OpenCode, Windsurf all read this).
+- `CLAUDE.md` -- Claude Code's root context file.
+- `GEMINI.md` -- Gemini CLI's root context file.
+- per-harness rules trees that mirror each instruction's
+  `applyTo:` glob: `.github/instructions/`, `.claude/rules/`,
+  `.cursor/rules/*.mdc`, `.windsurf/rules/`.
+
+Other primitive types -- prompts, skills, agents, chatmodes, hooks,
+commands -- are NOT compiled by this command. They are deployed by
+`apm install` directly into the harness directories that consume them
+(`.github/prompts/`, `.agents/skills/`, `.claude/commands/`, etc.).
+For the full reach map, see
+[Primitives and targets](../../concepts/primitives-and-targets/). For
+the place compile takes in the broader flow, see
+[Lifecycle](../../concepts/lifecycle/).
+
+## The authoring loop
+
+```
+edit .apm/instructions/  ->  apm compile  ->  inspect AGENTS.md  ->  repeat
+```
+
+You will run this loop while writing or refining instructions. Three
+flags speed it up:
+
+```bash
+apm compile --watch              # re-run on every change
+apm compile --validate           # check frontmatter and structure; emit nothing
+apm compile --dry-run            # print placement decisions without writing files
+```
+
+`--validate` is the fastest signal that an instruction parses.
+`--dry-run` shows you exactly which AGENTS.md tree would be written
+where. `--watch` is the tight inner loop while you edit prose.
+
+To preview a script that wraps a `.prompt.md` file, use
+[`apm preview`](../preview-and-validate/) instead. `apm compile` builds
+the root context files; `apm preview` shows the rewritten command line
+your script will execute.
+
+## Pick a target
+
+By default `apm compile` detects targets from your workspace (see
+[detection cascade](#detection-cascade) below). Override it with
+`--target` (`-t`):
+
+```bash
+apm compile --target claude
+apm compile --target copilot,cursor          # comma-separated
+apm compile --all                            # every canonical target
+```
+
+Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`,
+`gemini`, `windsurf`, `agent-skills`, `all`. The `agent-skills` slug
+is a no-op for compile (skills are deployed by `apm install`); it is
+accepted in target lists for symmetry only. Unknown slugs are
+rejected before any work runs.
+
+## Detection cascade
+
+When you omit `--target`, APM resolves which targets to build in this
+order:
+
+1. Explicit `--target <slug>` flag.
+2. The `targets:` field in your `apm.yml`.
+3. Auto-detect: any harness root directory (`.github/`, `.claude/`,
+   `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.windsurf/`) that
+   already exists.
+4. Fallback: `minimal` -- writes a single `AGENTS.md` and skips per-
+   harness rules folders.
+
+Pin `targets:` in `apm.yml` if you want the same compile output on
+every machine. Full rules and the per-target output map live in
+[Primitives and targets](../../concepts/primitives-and-targets/#how-a-target-is-selected).
+
+## Where instructions land
+
+Per target, with the rules shape on disk after compile:
+
+| Target | Root context file | Per-rule output | Compile required? |
+|---|---|---|---|
+| `copilot` | `AGENTS.md` | `.github/instructions/<name>.instructions.md` (preserves `applyTo`) | No -- Copilot reads the per-rule files natively |
+| `claude` | `CLAUDE.md` | `.claude/rules/<name>.md` | Yes -- `CLAUDE.md` is the entry point |
+| `cursor` | -- | `.cursor/rules/<name>.mdc` | Yes -- `.mdc` is Cursor's rules format |
+| `codex` | `AGENTS.md` (folded) | none -- compile-only, no per-file deploy | Yes -- folded into `AGENTS.md` |
+| `gemini` | `GEMINI.md` (folded) | none -- compile-only, no per-file deploy | Yes -- folded into `GEMINI.md` |
+| `opencode` | `AGENTS.md` (folded) | none -- compile-only, no per-file deploy | Yes -- folded into `AGENTS.md` |
+| `windsurf` | -- | `.windsurf/rules/<name>.md` | Yes -- compiled to Windsurf rules |
+
+## compile vs install
+
+| You want to... | Run |
+|---|---|
+| Iterate on instructions in `.apm/instructions/` | `apm compile` |
+| Deploy prompts, skills, agents, hooks, commands, MCP | `apm install` (see [Install packages](../../consumer/install-packages/)) |
+| Add a dependency or refresh `apm_modules/` | `apm install` |
+| Verify deployed bytes match the lockfile | `apm audit` |
+
+`apm install` runs compile internally as part of its integrate phase,
+so a normal `apm install` on a clean checkout already produces
+correct AGENTS.md / CLAUDE.md / GEMINI.md output. Reach for
+`apm compile` directly when you are iterating on instructions and
+do not want install's side effects.
+
+## Pitfalls
+
+- **Confusing compile's scope.** Compile only handles **instructions**
+  (and optionally a single chatmode to prepend). If you edit a prompt,
+  skill, agent, hook, or command, `apm compile` will not redeploy it
+  -- run `apm install` for that.
+- **Forgetting `--target` on a clean workspace.** With no harness
+  folder present and no `targets:` in `apm.yml`, the cascade falls
+  back to `minimal` and writes only `AGENTS.md`. The CLI prints a
+  hint, but the easy fix is to either create the harness folder or
+  pin `targets:` in your manifest.
+- **Stale `AGENTS.md` after deleting an instruction.** Compile leaves
+  previous output in place by default. Pass `--clean` to remove
+  orphaned files generated by earlier runs.
+- **Hand-edited primitives skip the security scan.** `apm compile`
+  does not run the install-time hidden-Unicode scan. After hand-edits,
+  run `apm audit` before publishing. See
+  [drift and secure-by-default](../../consumer/drift-and-secure-by-default/).
+- **Zero-output success.** If compile reports success but writes no
+  files, your project either has no instructions, or every requested
+  target was rejected. The CLI surfaces this as a warning -- check
+  `targets:` and the contents of `.apm/instructions/`.
+
+Once your instructions compile cleanly into the harnesses you care
+about, package the result with [`apm pack`](../pack-a-bundle/) and
+share it via [a marketplace](../publish-to-a-marketplace/).
diff --git a/docs/src/content/docs/producer/index.md b/docs/src/content/docs/producer/index.md
new file mode 100644
index 000000000..88bc881d8
--- /dev/null
+++ b/docs/src/content/docs/producer/index.md
@@ -0,0 +1,55 @@
+---
+title: Author and publish APM packages
+description: Build, validate, pack, and publish APM packages others can install.
+sidebar:
+  order: 0
+---
+
+You're here because you want to *author* an APM package others can install. This is the producer ramp.
+
+## The producer ladder
+
+Five steps, in order. Each links to the page that owns it:
+
+| # | Step                            | What success looks like                                                          |
+|---|---------------------------------|----------------------------------------------------------------------------------|
+| 1 | [Author primitives](./author-primitives/) | Skills, prompts, instructions, agents, hooks, commands, MCP under `.apm/`        |
+| 2 | [Compile your package](./compile/)        | `apm compile` writes deterministic per-target output you can git-diff            |
+| 3 | [Preview and validate](./preview-and-validate/) | `apm preview` and `apm view` confirm what consumers will receive                 |
+| 4 | [Pack a bundle](./pack-a-bundle/)         | `apm pack` produces a `.tar.gz` you can ship offline or to a marketplace         |
+| 5 | [Publish to a marketplace](./publish-to-a-marketplace/) | Others install your package with `apm install <owner>/<repo>`                  |
+
+You don't need a marketplace to start. Step 4 is enough for internal teams; the marketplace step is for public discovery.
+
+## Where to start
+
+| Your situation                                                       | Start here                                                  |
+|----------------------------------------------------------------------|-------------------------------------------------------------|
+| First time -- want a working package end-to-end                      | [Your first package](../getting-started/first-package/)     |
+| You have primitives in `.apm/` and need to test them locally         | [Compile your package](./compile/)                          |
+| You're about to ship -- want to verify what consumers will see       | [Preview and validate](./preview-and-validate/)             |
+| You need to ship a single file to a customer / air-gapped env        | [Pack a bundle](./pack-a-bundle/)                           |
+| You want a public marketplace listing                                | [Publish to a marketplace](./publish-to-a-marketplace/)     |
+| Your package links into other packages and you hit broken refs       | [Package-relative links](./package-relative-links/)         |
+
+## The producer mental model
+
+A producer package is just a directory with:
+
+```text
+my-package/
+  apm.yml                    # manifest -- who you are, what you depend on
+  .apm/
+    skills/                  # primitives consumers can install
+    prompts/
+    instructions/
+    agents/
+    hooks/
+  README.md                  # rendered on the marketplace listing
+```
+
+`apm compile` deterministically transforms `.apm/` into per-target output. `apm pack` zips the result. `apm publish` (via a marketplace adapter) lists it. There is no separate "build pipeline" -- the CLI is the build pipeline.
+
+## Compatible with the consumer ramp
+
+Every package you publish here installs through the [consumer ramp's](../consumer/) `apm install` command. Test that loop yourself: install your own package in a scratch repo before declaring it shipped. The [preview](./preview-and-validate/) page walks you through the dry-run.
diff --git a/docs/src/content/docs/producer/pack-a-bundle.md b/docs/src/content/docs/producer/pack-a-bundle.md
new file mode 100644
index 000000000..1ba6138f0
--- /dev/null
+++ b/docs/src/content/docs/producer/pack-a-bundle.md
@@ -0,0 +1,136 @@
+---
+title: Pack a bundle
+description: Build a plugin-format bundle from your .apm/ source so others can deploy it with a single apm install command.
+---
+
+A bundle is the artifact you hand to a consumer when you do not want to publish
+to a registry. It is a directory (or `.tar.gz` of one) containing a
+`plugin.json`, your primitive folders, and an embedded `apm.lock.yaml` that
+pins every file by SHA-256. Build it with one command from a project that has
+`.apm/` and `apm.yml`:
+
+```bash
+apm pack
+```
+
+This is the producer side of [Deploy a local bundle](../../consumer/deploy-a-bundle/).
+Consumers who receive the artifact run `apm install ./your-bundle` and skip
+the registry resolver entirely.
+
+## What `apm pack` produces
+
+By default `apm pack` writes a plugin-format directory under `./build/`:
+
+```
+build/<your-package>/
++-- plugin.json
++-- agents/
++-- skills/
++-- commands/
++-- hooks/
++-- apm.lock.yaml      # embedded: pins every file by SHA-256
+```
+
+The success line tells you exactly what to share:
+
+```
+$ apm pack
+[+] Packed 7 file(s) -> build/my-pkg
+[>] Plugin bundle ready -- contains plugin.json plus plugin-native
+    directories (agents/, skills/, commands/, ...) and an embedded
+    apm.lock.yaml for install-time integrity verification.
+[i] Share with: apm install build/my-pkg
+```
+
+Add `--archive` to get a single `.tar.gz` instead of a directory; use `-o` to
+change the output location (default `./build`).
+
+```bash
+apm pack --archive -o ./dist
+# -> ./dist/my-pkg-<version>.tar.gz
+```
+
+## The plugin.json contract
+
+`plugin.json` is the bundle's identity card. Only `name` is required. APM
+synthesises one from `apm.yml` if you do not author it yourself, mapping these
+fields:
+
+| `apm.yml` field | `plugin.json` field |
+|---|---|
+| `name`         | `name` (required) |
+| `version`      | `version` |
+| `description`  | `description` |
+| `author`       | `author: {name: ...}` |
+| `license`      | `license` |
+
+Author your own `plugin.json` at the project root (or under `.github/plugin/`,
+`.claude-plugin/`, or `.cursor-plugin/`) when you need fields APM does not
+synthesise -- otherwise leave it to `apm pack` and keep `apm.yml` as the
+source of truth. See [Package anatomy](../../concepts/package-anatomy/) for
+the full schema.
+
+## Integrity: how install verifies the bundle
+
+`apm pack` writes `pack.bundle_files` into the embedded `apm.lock.yaml` -- a
+mapping of every file's relative path to its SHA-256 digest. On the consumer
+side, `apm install <bundle>` rehashes every file and rejects the bundle if:
+
+- any hash does not match
+- any file listed in `pack.bundle_files` is missing
+- any file is present in the bundle but not listed in the manifest
+- any path is a symlink
+
+The manifest is the source of truth. Tampering after pack time is detected
+before any file lands in the project. You do not configure this -- it runs on
+every `apm install <bundle>`.
+
+## Distribution paths
+
+Three common ways to hand off a bundle:
+
+- **Directory + git.** Commit `build/<pkg>/` to a release branch or a separate
+  artifacts repo. Consumers `git clone` and run `apm install ./build/<pkg>`.
+- **Archive + GitHub release.** `apm pack --archive` then upload the
+  `.tar.gz` as a release asset. Consumers download and run
+  `apm install ./<pkg>-<version>.tar.gz`.
+- **Marketplace entry.** If your project also has a `marketplace:` block in
+  `apm.yml`, `apm pack` builds `marketplace.json` alongside the bundle. See
+  [Publish to a marketplace](../publish-to-a-marketplace/).
+
+For the consumer flags that apply (`--target`, `--global`, `--force`,
+`--dry-run`), see [Deploy a local bundle](../../consumer/deploy-a-bundle/).
+
+## Pitfalls
+
+**Do not use `--format apm` for bundles you expect consumers to install.**
+The legacy APM bundle layout has no `plugin.json` and `apm install` rejects
+it with a targeted error. The flag exists for tooling that still consumes
+the older layout; new bundles should use the default `--format plugin`. If
+you only have a legacy artifact, repack it:
+
+```bash
+apm pack --format plugin --archive
+```
+
+**Do not set `--target`.** The flag is deprecated. Bundles are
+target-agnostic: the consumer's project decides which harness layouts
+receive files at install time. APM records the value in `pack.target` as
+informational metadata only and prints a deprecation warning.
+
+**Empty bundle warning.** If `apm pack` reports "No deployed files found",
+your `apm.lock.yaml` has no `deployed_files` entries. Run `apm install` first
+to populate it -- `apm pack` packs the files your last install actually
+deployed, not the raw `.apm/` source tree.
+
+**Dry-run before sharing.** Use `apm pack --dry-run --verbose` to see the
+full file list (and any path remappings) without writing anything.
+
+## What to read next
+
+- [Deploy a local bundle](../../consumer/deploy-a-bundle/) -- the consumer
+  side of this hand-off.
+- [Publish to a marketplace](../publish-to-a-marketplace/) -- when a registry
+  entry is a better fit than a bundle.
+- [Package anatomy](../../concepts/package-anatomy/) -- the file layout and
+  schema reference.
diff --git a/docs/src/content/docs/producer/package-relative-links.md b/docs/src/content/docs/producer/package-relative-links.md
new file mode 100644
index 000000000..bdd46dc10
--- /dev/null
+++ b/docs/src/content/docs/producer/package-relative-links.md
@@ -0,0 +1,121 @@
+---
+title: Package-relative links
+description: How relative markdown links inside an APM package survive deployment to consumer harness directories.
+---
+
+A primitive in your package can link to a sibling file with a normal
+relative markdown link. APM rewrites that link at install time so it
+still resolves after the primitive is copied into the consumer's
+harness directory (`.claude/`, `.github/`, `.cursor/`, ...) -- far
+away from the package's authored layout.
+
+This page is the contract: which links get rewritten, which do not,
+and how to verify the result.
+
+## The rewrite, in one example
+
+Author layout in your package:
+
+```
+my-pkg/
++-- apm.yml
++-- .apm/
+|   +-- skills/code-review/SKILL.md
+|   +-- agents/architect.agent.md
++-- references/
+    +-- patterns.md
+```
+
+`architect.agent.md` links to a sibling reference:
+
+```markdown
+See [design patterns](../../references/patterns.md).
+```
+
+After `apm install` in a consumer with the `claude` target, the
+deployed file `.claude/agents/architect.md` reads:
+
+```markdown
+See [design patterns](../../apm_modules/<owner>/my-pkg/references/patterns.md).
+```
+
+The package itself stays intact under `apm_modules/`; the deployed
+primitive points back into it.
+
+## What APM rewrites
+
+A markdown link `[text](path)` is rewritten only when **all** hold
+(`src/apm_cli/compilation/link_resolver.py:391-529`):
+
+1. The link is relative -- no URL scheme (`http:`, `mailto:`, ...), not
+   protocol-relative (`//host`), not root-absolute (`/foo`), not a bare
+   fragment (`#section`).
+2. The resolved target is a regular file that exists on disk.
+3. The resolved target stays inside the source package root (validated
+   against symlink and `..` traversal).
+
+Anything else is passed through verbatim. This applies to
+**instructions, prompts, agents, and commands**. Skills are different
+-- see below.
+
+`#fragment` and `?query` suffixes are preserved through the rewrite.
+
+## What APM does not rewrite
+
+| Link form | Why it is left alone |
+|---|---|
+| `https://example.com/...` | External URL, already absolute. |
+| `#section` | In-document anchor; nothing to resolve. |
+| `/docs/foo.md` | Root-absolute -- consumer-side, not yours. |
+| `../../../outside.md` | Escapes the package root; refused. |
+| `mailto:`, `file:`, custom schemes | Not filesystem paths. |
+| Relative paths whose target file does not exist | Cannot verify; treated as intentional. |
+
+Cross-package references are not supported. A primitive in package A
+cannot link into package B -- the resolved path escapes A's root and
+the link is left unrewritten. Packages are independent deployment
+units. If you need shared content, depend on the other package and
+inline what you need.
+
+## Skills are a special case
+
+Skills deploy as whole bundles (`shutil.copytree` in
+`src/apm_cli/integration/skill_integrator.py:392`). The internal
+layout of a skill folder is preserved as-is at the destination, so
+**links between files inside a single skill bundle just work and are
+not rewritten**.
+
+Author layout:
+
+```
+my-pkg/.apm/skills/code-review/
++-- SKILL.md
++-- references/api.md
++-- scripts/lint.sh
+```
+
+`SKILL.md` linking to `references/api.md` or `scripts/lint.sh` keeps
+working unchanged after deploy to `.claude/skills/code-review/`,
+`.codex/skills/code-review/`, etc.
+
+A link from inside a skill bundle out to the package's other
+directories (e.g. `../../references/patterns.md`) does go through the
+rewriter, with the same rules as above.
+
+## Verify after install
+
+Install your package into a scratch consumer and inspect a deployed file:
+
+```bash
+mkdir scratch && cd scratch
+apm init
+apm install ../path/to/my-pkg
+grep -E '\]\(' .claude/agents/architect.md
+ls apm_modules/*/my-pkg/references/patterns.md
+```
+
+The rewritten paths should point into `apm_modules/<owner>/my-pkg/`
+and the targets should exist.
+
+For the full reach map of which primitive lands where on each harness,
+see [Primitives and targets](../../concepts/primitives-and-targets/).
diff --git a/docs/src/content/docs/producer/preview-and-validate.md b/docs/src/content/docs/producer/preview-and-validate.md
new file mode 100644
index 000000000..1d3ae6154
--- /dev/null
+++ b/docs/src/content/docs/producer/preview-and-validate.md
@@ -0,0 +1,137 @@
+---
+title: Preview and validate
+description: The local verify-before-ship loop. Inspect, list, audit, and dry-run before you pack.
+---
+
+Before you pack and publish, run the verify loop locally. APM ships
+five read-only commands that answer the questions a producer needs to
+answer before shipping: what would deploy, what is installed, what is
+stale, and what is unsafe.
+
+```bash
+apm compile --dry-run     # what would be written, without writing
+apm view <your-package>   # metadata for an installed package
+apm list                  # scripts in your apm.yml
+apm outdated              # which deps drift behind their refs
+apm audit                 # hidden Unicode + drift against the lockfile
+```
+
+The recommended sequence is `compile --dry-run` -> `apm view` ->
+`apm audit` -> [`apm pack`](../pack-a-bundle/). Run it once at the end
+of every authoring session.
+
+## apm compile --dry-run
+
+```bash
+apm compile --dry-run
+apm compile --dry-run --target claude,cursor
+apm compile --validate
+```
+
+Prints the placement decisions [`apm compile`](../compile/) would make
+without touching disk: which primitives go to which harness directory,
+which files would be overwritten, which targets would be skipped. Use
+it whenever you are not sure what your `apm.yml` and `.apm/` will
+produce.
+
+`--validate` is the stricter sibling. It parses every primitive's
+frontmatter and structure and reports errors without producing output.
+Run it before `--dry-run` when you have just edited a primitive and
+want a quick syntax check.
+
+Pair `--dry-run` with `--target` to scope the preview to one harness.
+Pair it with `--verbose` to see source attribution per file.
+
+## apm view
+
+```bash
+apm view <your-package>            # local metadata
+apm view <your-package> versions   # remote tags and branches
+```
+
+`apm view` reads from `apm_modules/` and reports the package's name,
+version, description, author, source, locked ref and commit, install
+path, primitive counts (instructions, prompts, skills, agents), and
+hook count. Use it after installing your package into a fresh test
+project to confirm what consumers will see.
+
+`apm view <package> versions` queries the remote and lists available
+tags and branches. Useful before publishing a new tag to confirm what
+is already out there.
+
+:::note
+`apm view` requires the package to be installed. To preview your own
+in-development package, install it from a local path first:
+`apm install ./path/to/your/package` in a scratch project, then
+`apm view <name>`.
+:::
+
+## apm list
+
+```bash
+apm list
+```
+
+Lists the scripts declared in your project's `apm.yml`. This is the
+fast way to confirm your `scripts:` block is well-formed and your
+`start` default points at the right command.
+
+For a tree of installed dependencies (versions, sources, primitive
+counts), use `apm deps list` instead. See
+[CLI reference](../../reference/cli/install/) for both.
+
+## apm outdated
+
+```bash
+apm outdated
+apm outdated --verbose
+apm outdated -j 8
+```
+
+Compares every locked dependency against its remote and reports which
+ones drift behind. Tag-pinned deps use semver comparison; branch-pinned
+deps compare commit SHAs. Local paths and Artifactory deps are skipped.
+
+Run it before publishing. Shipping a package whose own dependencies
+are months stale is the kind of small thing that erodes consumer
+trust. `--verbose` prints the available tags so you can decide whether
+to bump.
+
+## apm audit
+
+```bash
+apm audit                # scan deployed files + drift check
+apm audit --file <path>  # scan one arbitrary file
+apm audit --strip        # remove dangerous hidden characters
+apm audit --strip --dry-run   # preview the strip
+```
+
+`apm audit` is the producer's last gate before pack. It scans every
+deployed prompt, instruction, skill, and agent file for hidden Unicode
+(zero-width characters, bidi controls, tag characters), then rebuilds
+the deployed context in a scratch directory and diffs it against your
+working tree to catch hand-edits to `apm_modules/` or generated files.
+
+Findings come back as text by default. Use `-f json`, `-f sarif`, or
+`-f markdown` for machine-readable output, and `-o <path>` to write to
+file.
+
+For the conceptual model behind hidden-Unicode threats and the
+secure-by-default layer, see
+[Drift and secure-by-default](../../consumer/drift-and-secure-by-default/).
+
+## The recommended verify sequence
+
+```bash
+apm compile --validate         # 1. structure check
+apm compile --dry-run          # 2. preview placement
+apm view <your-package>        # 3. confirm metadata
+apm outdated                   # 4. check dep freshness
+apm audit                      # 5. scan + drift
+apm pack                       # 6. ship it
+```
+
+Steps 1-5 are read-only and safe to run in any order. Step 6 produces
+the bundle: see [Pack a bundle](../pack-a-bundle/) for the next step,
+then [Publish to a marketplace](../publish-to-a-marketplace/) to ship
+it.
diff --git a/docs/src/content/docs/producer/publish-to-a-marketplace.md b/docs/src/content/docs/producer/publish-to-a-marketplace.md
new file mode 100644
index 000000000..d1b86c738
--- /dev/null
+++ b/docs/src/content/docs/producer/publish-to-a-marketplace.md
@@ -0,0 +1,201 @@
+---
+title: Publish to a marketplace
+description: Author an APM marketplace registry, build it, and publish updates to consumer repos.
+---
+
+A **marketplace** in APM is a curated index of packages that one repo
+publishes and many repos install from. You author it as a
+`marketplace:` block in `apm.yml`, build it into
+`.claude-plugin/marketplace.json` with `apm pack`, and let consumers
+register your repo with `apm marketplace add`. This page walks the
+producer side: schema, build, and the optional `apm marketplace
+publish` flow that opens PRs against pinned consumer repos.
+
+For the consumer side -- adding a marketplace, browsing it, installing
+packages from it -- see [Marketplaces](../../guides/marketplaces/).
+
+## End to end
+
+```bash
+apm marketplace init                          # 1. add the block to apm.yml
+$EDITOR apm.yml                               # 2. describe each package
+apm marketplace check                         # 3. validate refs resolve
+apm pack                                      # 4. compile marketplace.json
+git add apm.yml .claude-plugin/marketplace.json
+git commit -m "Release v1.0.0" && git push    # 5. ship
+```
+
+A consumer in another repo then runs:
+
+```bash
+apm marketplace add acme-org/my-marketplace
+apm install example-package@my-marketplace
+```
+
+That is the loop. Everything below is detail.
+
+## What lives where
+
+APM uses a single source-of-truth model:
+
+- `apm.yml` -- hand-edited. The `marketplace:` block declares your
+  registry: owner, packages, version ranges.
+- `.claude-plugin/marketplace.json` -- generated by `apm pack`.
+  Byte-compatible with [Anthropic's marketplace.json](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)
+  so Claude Code, Copilot CLI, and APM all read the same artefact.
+
+Both files are committed. The legacy standalone `marketplace.yml` is
+deprecated; if you still have one, run `apm marketplace migrate`.
+
+## Author the registry
+
+Scaffold the block:
+
+```bash
+apm marketplace init --owner acme-org
+```
+
+This appends a richly commented `marketplace:` block to `apm.yml`
+(creating `apm.yml` if absent). The minimal shape:
+
+```yaml
+name: my-project           # inherited into marketplace top level
+version: 1.0.0
+description: Curated plugins for the acme-org engineering team
+
+marketplace:
+  owner:
+    name: acme-org
+    url: https://github.com/acme-org
+
+  build:
+    tagPattern: "v{version}"          # default; per-package overridable
+
+  packages:
+    - name: example-package
+      description: Human-readable description consumers see
+      source: acme-org/example-package
+      version: "^1.0.0"
+
+    - name: pinned-package
+      source: acme-org/pinned-package
+      ref: 3f2a9b1c                   # explicit SHA/tag/branch
+
+    - name: local-tool
+      source: ./packages/local-tool   # ships from this same repo
+      version: 0.1.0
+```
+
+The key in `apm.yml` is `packages:`. It becomes `plugins:` in the
+compiled `marketplace.json` -- that rename is the only structural
+transform `apm pack` performs. Strict schema: unknown keys raise an
+error, never silently ignored.
+
+For the full field reference (every key on every entry, including
+`subdir`, `tag_pattern`, `include_prerelease`, `metadata`,
+`pluginRoot`, and Anthropic pass-through fields like `tags`, `author`,
+`license`), see [Marketplace authoring](../../guides/marketplace-authoring/).
+
+## Build
+
+```bash
+apm pack
+```
+
+`apm pack` resolves every remote `packages:` entry against
+`git ls-remote`, leaves local-path entries untouched, and writes
+`.claude-plugin/marketplace.json` atomically. Useful flags:
+
+```bash
+apm pack --dry-run              # resolve and print; do not write
+apm pack --offline              # cached refs only
+apm pack --include-prerelease   # allow pre-release tags
+apm pack -v                     # per-entry resolution detail
+```
+
+Exit codes: `0` build succeeded, `1` build error (network, missing
+ref, no tag matches range), `2` schema error in the `marketplace:`
+block.
+
+The same `apm pack` run also produces a bundle to `./build/<name>/`
+when `apm.yml` declares `dependencies:`. Marketplace projects with no
+`dependencies:` block produce only `marketplace.json`. See
+[Pack a bundle](../pack-a-bundle/) for the bundle side.
+
+## Validate before you ship
+
+```bash
+apm marketplace check        # every package's ref/range resolves
+apm marketplace doctor       # local environment diagnostics
+apm marketplace outdated     # packages with newer matching tags
+```
+
+`check` is the gate to run in CI: a missing tag or unresolvable range
+exits non-zero before you push the release commit.
+
+## Publish updates to pinned consumers
+
+`apm marketplace publish` is the optional fan-out: it opens PRs
+against a list of consumer repos that pin the previous marketplace
+version, bumping each one to the version you just released.
+
+```yaml
+# consumer-targets.yml
+targets:
+  - repo: acme-org/service-a
+    branch: main
+  - repo: acme-org/service-b
+    branch: develop
+    path_in_repo: apm.yml      # default
+```
+
+```bash
+apm marketplace publish --dry-run    # preview
+apm marketplace publish --yes        # push branches and open PRs
+apm marketplace publish --no-pr      # push branches, skip gh PR creation
+```
+
+It clones each target, edits its `apm.yml` to point at the new
+marketplace ref, pushes a feature branch, and opens a PR via `gh`.
+State is journaled to `.apm/publish-state.json`. Failures in one
+target do not abort the others; the exit code is non-zero if any
+target failed.
+
+This flow assumes `gh` is authenticated and the runner has push
+access to every target -- it is targeted at internal/org marketplaces
+where you control both sides. Public marketplaces should rely on
+consumers running `apm install --update` on their own cadence.
+
+## Pitfalls
+
+- **`packages:` not `plugins:`** in the `apm.yml` source. The
+  `plugins:` name only appears in the compiled JSON.
+- **Both `apm.yml` (`marketplace:` block) and `marketplace.yml`
+  present** is a hard error. Pick one; prefer the block and run
+  `apm marketplace migrate` to consolidate.
+- **`*.json` in `.gitignore`** will silently skip the generated file.
+  `apm marketplace init` warns on this; if you hit it, add an
+  unignore: `!.claude-plugin/marketplace.json`.
+- **Local-path entries skip git resolution.** They emit the path
+  verbatim; consumers see the same path. Use `metadata.pluginRoot` if
+  your plugins live under a common subdirectory.
+- **No `versions[]` array.** Each compiled package carries one
+  resolved ref -- the highest tag matching the range at build time.
+  Re-run `apm pack` and re-tag to publish a new version.
+
+## Governance
+
+Org policy can restrict which marketplaces a consumer is allowed to
+register and which packages it can install from them. That gate runs
+on the consumer side at install time. See
+[Governance overview](../../enterprise/governance-overview/) for the
+producer-side implications (signing, allow-listed sources).
+
+## Where next
+
+- [Pack a bundle](../pack-a-bundle/) -- the other thing `apm pack`
+  produces.
+- [Preview and validate](../preview-and-validate/) -- dry-runs and
+  schema checks before you tag.
+- [Install packages](../../consumer/install-packages/) -- the consumer
+  flow your marketplace feeds into.
diff --git a/docs/src/content/docs/quickstart.mdx b/docs/src/content/docs/quickstart.mdx
new file mode 100644
index 000000000..23e2ef8f5
--- /dev/null
+++ b/docs/src/content/docs/quickstart.mdx
@@ -0,0 +1,186 @@
+---
+title: "Quickstart"
+description: "Install APM, install your first package, and run an agent in 5 minutes."
+sidebar:
+  order: 1
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+You will install APM, scaffold a project, install a package, and run an
+agent script. Five minutes, four commands. This is the consumer path --
+you are running someone else's package, not authoring one.
+
+If you want to publish a package, jump to the
+[pack and distribute guide](/apm/producer/). If you are
+rolling APM out across an org, start with the
+[governance guide](/apm/enterprise/governance-guide/).
+
+## 1. Install APM
+
+**macOS / Linux:**
+
+```bash
+curl -sSL https://aka.ms/apm-unix | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://aka.ms/apm-windows | iex
+```
+
+Verify:
+
+```bash
+apm --version
+```
+
+For Homebrew, Scoop, pip, air-gapped mirrors, or signed-archive install,
+see [Installation](/apm/quickstart/).
+
+## 2. Initialize a project
+
+```bash
+apm init my-agent
+cd my-agent
+```
+
+`apm init` writes one file -- the manifest:
+
+```
+my-agent/
++-- apm.yml
+```
+
+Open `apm.yml`. It looks like this:
+
+```yaml
+name: my-agent
+version: 1.0.0
+description: APM project for my-agent
+author: your-handle
+# Which agent platforms to deploy to (uncomment to pin):
+# targets:
+#   - copilot
+#   - claude
+
+dependencies:
+  apm: []
+  mcp: []
+includes: auto
+scripts: {}
+```
+
+Three fields matter day one:
+
+- `dependencies.apm` -- the packages you install. Empty until step 3.
+- `dependencies.mcp` -- MCP servers, wired into every detected harness.
+- `scripts` -- optional named shell commands you run with the
+  experimental `apm run` (see [Run scripts](/apm/consumer/run-scripts/)).
+
+`includes: auto` ships any local `.apm/` content you author. The
+`targets:` block is commented out so APM auto-detects the harnesses
+present in your repo (`.github/`, `.claude/`, `.cursor/`, etc.). For the
+full schema, see [Package anatomy](/apm/concepts/package-anatomy/).
+
+## 3. Install a package
+
+```bash
+apm install microsoft/apm-sample-package#v1.0.0 --target copilot
+```
+
+`--target copilot` is shown explicitly because a fresh project has no
+harness markers yet. Once any `.github/` content exists, APM detects it
+and the flag becomes optional.
+
+Output (abridged):
+
+```
+[+] microsoft/apm-sample-package #v1.0.0 @fb285168
+|-- 2 prompts integrated -> .github/prompts/
+|-- 1 agents integrated -> .github/agents/
+|-- 1 instruction(s) integrated -> .github/instructions/
+|-- 1 skill(s) integrated -> .agents/skills/
+[+] github.com/github/awesome-copilot/skills/review-and-refactor
+|-- Skill integrated -> .agents/skills/
+[*] Installed 2 APM dependencies in 1.4s.
+```
+
+Three things were written:
+
+```
+my-agent/
++-- apm.yml              # updated: package added under dependencies.apm
++-- apm.lock.yaml        # NEW: pins resolved sources + content hashes
++-- apm_modules/         # NEW: package cache (gitignored automatically)
++-- .agents/skills/      # NEW: harness-neutral skills
++-- .github/             # NEW: prompts, agents, instructions for Copilot
+```
+
+The package's transitive dependency (`review-and-refactor`) was
+resolved and installed in the same pass. `apm.lock.yaml` records the
+exact commit and content hash for both, so every teammate who runs
+`apm install` after cloning gets the identical tree.
+
+:::note[What just happened under the hood]
+APM scanned the package for hidden Unicode before any agent could read
+it (Promise 2: see [Security](/apm/enterprise/security/))
+and pinned its content hash in `apm.lock.yaml`. If your org ships an
+`apm-policy.yml`, those rules ran first (Promise 3: see
+[Governance guide](/apm/enterprise/governance-guide/)).
+:::
+
+:::tip[Coming from npm?]
+APM's verbs match npm's semantics:
+
+- `apm install` -- install and deploy dependencies, like `npm install`.
+- `apm update` -- refresh dependencies to the latest matching refs,
+  with a consent prompt, like `npm update`.
+- `apm install --frozen` -- lockfile-only install for CI; fails on
+  drift, like `npm ci`.
+- `apm prune` -- remove packages from `apm_modules/` that are no
+  longer in `apm.yml`, like `npm prune`.
+- `apm self-update` -- upgrade the `apm` CLI binary itself
+  (think `npm install -g npm`).
+
+For private packages, set `GITHUB_APM_PAT` -- see
+[private packages](/apm/consumer/private-and-org-packages/).
+:::
+
+## What next
+
+Your project is ready: dependencies pinned, primitives deployed, every
+detected harness configured. The package's prompts and skills are
+already discoverable from your AI tool of choice -- start a Copilot
+chat, open Claude Code, or invoke the agent from any harness that
+read its instructions on disk.
+
+:::note[Looking for `apm run`?]
+APM also ships an experimental script runner -- think `npx` for AI
+runtime CLIs. Declare a `scripts:` entry in `apm.yml` and execute it
+with `apm run <name>`. It is optional, off the critical path, and
+not required to use any installed package. See
+[Run scripts](/apm/consumer/run-scripts/) if you want to wire one up.
+:::
+
+<CardGrid>
+  <Card title="Use more packages" icon="open-book">
+    Browse the consumer guide: search marketplaces, pin versions, manage
+    transitive dependencies, and wire MCP servers into every harness.
+    [Dependencies](/apm/consumer/manage-dependencies/)
+  </Card>
+  <Card title="Author your own" icon="rocket">
+    Build a primitive others can install -- skills, prompts, agents,
+    plugins -- and pack it for distribution.
+    [Pack and distribute](/apm/producer/)
+  </Card>
+  <Card title="Govern installs at scale" icon="setting">
+    Ship `apm-policy.yml`, gate CI with `apm audit --ci`, and pin a
+    private registry for your org.
+    [Governance guide](/apm/enterprise/governance-guide/)
+  </Card>
+</CardGrid>
+
+If something failed along the way, check
+[Troubleshooting](/apm/troubleshooting/ssl-issues/).
diff --git a/docs/src/content/docs/reference/baseline-checks.md b/docs/src/content/docs/reference/baseline-checks.md
new file mode 100644
index 000000000..62474684d
--- /dev/null
+++ b/docs/src/content/docs/reference/baseline-checks.md
@@ -0,0 +1,130 @@
+---
+title: Baseline CI checks
+description: Reference list of every check that apm audit --ci runs against a project, with failure conditions, exit-code impact, and remediation.
+sidebar:
+  order: 7
+---
+
+`apm audit --ci` runs a fixed set of baseline checks against the project on
+disk. Baseline checks are always on -- they need no `apm-policy.yml`. With
+policy discovery active, the org policy contributes additional checks on
+top (see [`apm policy`](../cli/policy/) and the
+[policy schema](../policy-schema/)).
+
+This page documents the baseline set defined in
+`src/apm_cli/policy/ci_checks.py`. For the command surface, see
+[`apm audit`](../cli/audit/). For the CI wiring, see
+[Enforce in CI](../../enterprise/enforce-in-ci/).
+
+## Exit-code contract
+
+| Outcome | Exit code |
+|---|---|
+| All baseline checks pass (and any policy + drift checks pass) | `0` |
+| Any baseline, policy, or drift check fails | `1` |
+
+`--no-fail-fast` runs every check before exiting; the default stops at the
+first failure to skip expensive I/O.
+
+## At a glance
+
+| ID | Severity | Source | Always on? |
+|---|---|---|---|
+| `manifest-parse` | block | `ci_checks.py` | only when `apm.yml` cannot be parsed |
+| `lockfile-exists` | block | `ci_checks.py` | yes |
+| `ref-consistency` | block | `ci_checks.py` | yes |
+| `deployed-files-present` | block | `ci_checks.py` | yes |
+| `no-orphaned-packages` | block | `ci_checks.py` | yes |
+| `skill-subset-consistency` | block | `ci_checks.py` | yes |
+| `config-consistency` | block | `ci_checks.py` | yes |
+| `content-integrity` | block | `ci_checks.py` | yes |
+| `includes-consent` | advisory | `ci_checks.py` | yes (advisory; promotable by policy) |
+| `drift` | block | `_check_drift` in `ci_checks.py`, invoked from `commands/audit.py` | yes, unless `--no-drift` |
+
+Policy checks (`dependency-allowlist`, `dependency-denylist`,
+`required-packages`, `required-packages-deployed`,
+`required-package-version`, `transitive-depth`, and others in
+`policy/policy_checks.py`) only run when an `apm-policy.yml` is resolved
+through discovery or `--policy`. They are out of scope for this page; see
+the [policy schema](../policy-schema/).
+
+## Baseline checks
+
+### `manifest-parse`
+
+- **What it verifies.** That `apm.yml`, if present, is valid YAML and a valid APM manifest.
+- **Fails when.** The file exists but cannot be parsed (`yaml.YAMLError`, `ValueError`, or `OSError`).
+- **Effect.** Skips every other check and exits `1`. This is the only check that runs before the lockfile gate.
+- **Remediation.** Fix the YAML syntax error reported in the message and re-run.
+
+### `lockfile-exists`
+
+- **What it verifies.** That `apm.lock.yaml` is present whenever the project has APM or MCP dependencies, or whenever an existing lockfile records local content under the synthesized self-entry.
+- **Fails when.** `apm.yml` declares dependencies but no lockfile is on disk.
+- **Effect.** Subsequent checks are skipped (the lockfile is required input).
+- **Remediation.** Run `apm install` to generate `apm.lock.yaml` and commit it.
+
+### `ref-consistency`
+
+- **What it verifies.** That every dependency's `reference` in `apm.yml` matches the `resolved_ref` recorded in the lockfile.
+- **Fails when.** A manifest ref differs from the lockfile entry, or the manifest declares a dependency that is missing from the lockfile.
+- **Remediation.** Run `apm install` so the lockfile re-resolves to the manifest, then commit `apm.lock.yaml`.
+
+### `deployed-files-present`
+
+- **What it verifies.** That every path in each lockfile entry's `deployed_files` exists on disk under the project root.
+- **Fails when.** One or more deployed files are missing (e.g. a developer ran `apm install` then deleted integrated files, or skipped install entirely).
+- **Remediation.** Run `apm install` to restore the integrated files.
+
+### `no-orphaned-packages`
+
+- **What it verifies.** That every dependency in the lockfile is still declared in `apm.yml`. The synthesized self-entry is excluded.
+- **Fails when.** The lockfile holds a package that the manifest no longer lists.
+- **Remediation.** Run `apm install` to prune the orphan, then commit `apm.lock.yaml`.
+
+### `skill-subset-consistency`
+
+- **What it verifies.** That the `skills:` selection in `apm.yml` for each `skill_bundle` dependency matches the `skill_subset` recorded in the lockfile.
+- **Fails when.** The sorted manifest skill list differs from the sorted lockfile `skill_subset` for any skill bundle.
+- **Remediation.** Run `apm install` to regenerate the lockfile against the current selection.
+
+### `config-consistency`
+
+- **What it verifies.** That MCP server configs derived from `apm.yml` match the `mcp_configs` baseline stored in the lockfile.
+- **Fails when.** A server's resolved config differs from the lockfile, a server is in the lockfile but not the manifest, or a server is in the manifest but not the lockfile.
+- **Remediation.** Run `apm install` to reconcile the MCP configuration.
+
+### `content-integrity`
+
+- **What it verifies.** Two signals across every deployed file (including local `.apm/` content via the synthesized self-entry):
+  1. Critical hidden Unicode (tag characters, bidi overrides, variation selectors 17-256, and similar steganographic markers).
+  2. SHA-256 drift between the on-disk content and the hash recorded in `deployed_file_hashes` at install time.
+- **Fails when.** Any deployed file contains a critical Unicode finding or its hash no longer matches the lockfile entry. Missing files are intentionally not reported here -- `deployed-files-present` owns that signal. Symlinks and entries without a recorded hash are skipped.
+- **Remediation.** Run `apm audit --strip` to clean Unicode findings, and `apm install` to restore hash-drifted files. Both may be needed.
+
+### `includes-consent`
+
+- **What it verifies.** That projects deploying local content (the lockfile's `local_deployed_files` is non-empty) declare an `includes:` field in `apm.yml` for explicit governance.
+- **Fails when.** Never -- this check is advisory and always passes. The message advises adding `includes: auto` (or an explicit list) when local content is deployed without a declaration.
+- **Promote to a block.** Set `manifest.require_explicit_includes` in `apm-policy.yml` to make missing `includes:` fail the policy layer.
+- **Remediation.** Add `includes: auto` to `apm.yml`, or list the paths explicitly.
+
+### `drift`
+
+- **What it verifies.** That the working tree matches what an install from the current lockfile would produce. The check replays the install pipeline into a scratch tree and diffs the result against the project.
+- **Fails when.** Any deployed file differs from the replay output (hand-edits, missing integrations, orphaned files), or the cache is cold and `apm install` has not populated `apm_modules` (the replay is cache-only by design so audit stays deterministic).
+- **Skip with.** `apm audit --ci --no-drift` (reduces coverage; reserve for performance-constrained CI loops).
+- **Remediation.** Run `apm install` to restore the deployed state, or revert the hand-edit. For a cache-miss failure, the same `apm install` warms the cache.
+
+## Run order and fail-fast
+
+The aggregate runner in `run_baseline_checks` evaluates checks in this order: `manifest-parse` (only when `apm.yml` is unparseable), `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, `includes-consent`. Drift is invoked separately by the audit command after the baseline batch.
+
+With fail-fast on (the default), the runner stops at the first failing check. `apm audit --ci --no-fail-fast` evaluates every check so the report lists every problem at once.
+
+## Related
+
+- [`apm audit`](../cli/audit/) -- the command surface and modes.
+- [`apm policy`](../cli/policy/) -- inspect, validate, and resolve org policy.
+- [Policy schema](../policy-schema/) -- the policy-gated checks layered on top of this baseline.
+- [Enforce in CI](../../enterprise/enforce-in-ci/) -- wiring the gate into branch protection.
diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md
deleted file mode 100644
index e5c010588..000000000
--- a/docs/src/content/docs/reference/cli-commands.md
+++ /dev/null
@@ -1,2245 +0,0 @@
----
-title: "CLI Commands"
-sidebar:
-  order: 1
----
-
-Complete reference for all APM CLI commands and options.
-
-:::tip[New to APM?]
-See [Installation](../../getting-started/installation/) and [Quick Start](../../getting-started/quick-start/) to get up and running.
-:::
-
-## Global Options
-
-```bash
-apm [OPTIONS] COMMAND [ARGS]...
-```
-
-### Options
-- `--version` - Show version and exit
-- `--help` - Show help message and exit
-
-## Core Commands
-
-### `apm init` - Initialize new APM project
-
-Initialize a new APM project with minimal `apm.yml` configuration (like `npm init`).
-
-```bash
-apm init [PROJECT_NAME] [OPTIONS]
-```
-
-**Arguments:**
-- `PROJECT_NAME` - Optional name for new project directory. Use `.` to explicitly initialize in current directory
-
-**Options:**
-- `-y, --yes` - Skip interactive prompts and use auto-detected defaults
-- `--plugin` - Initialize as a plugin authoring project (creates `plugin.json` + `apm.yml` with `devDependencies`)
-- `--marketplace` - Seed `apm.yml` with a `marketplace:` authoring block. See the [Authoring a marketplace guide](../../guides/marketplace-authoring/).
-
-**Examples:**
-```bash
-# Initialize in current directory (interactive)
-apm init
-
-# Initialize in current directory with defaults
-apm init --yes
-
-# Create new project directory
-apm init my-hello-world
-
-# Create project with auto-detected defaults
-apm init my-project --yes
-
-# Initialize a plugin authoring project
-apm init my-plugin --plugin
-
-# Initialize a project that also publishes a marketplace
-apm init my-marketplace --marketplace
-```
-
-**Behavior:**
-- **Minimal by default**: Creates only `apm.yml` with auto-detected metadata
-- **Interactive mode**: Prompts for project details unless `--yes` specified
-- **Auto-detection**: Automatically detects author from `git config user.name` and description from project context
-- **Brownfield friendly**: Works cleanly in existing projects without file pollution
-- **Plugin mode** (`--plugin`): Creates both `plugin.json` and `apm.yml` with an empty `devDependencies` section. Plugin names must be kebab-case (`^[a-z][a-z0-9-]{0,63}$`), max 64 characters
-
-**Creates:**
-- `apm.yml` - Minimal project configuration with empty dependencies and scripts sections
-- `plugin.json` - Plugin manifest (only with `--plugin`)
-
-**Auto-detected fields:**
-- `name` - From project directory name
-- `author` - From `git config user.name` (fallback: "Developer")
-- `description` - Generated from project name
-- `version` - Defaults to "1.0.0"
-
-### `apm install` - Install dependencies and deploy local content
-
-Install APM package and MCP server dependencies from `apm.yml` and deploy the project's own `.apm/` content to target directories (like `npm install`). Auto-creates minimal `apm.yml` when packages are specified but no manifest exists. For `http://` dependencies, use `--allow-insecure`.
-
-```bash
-apm install [PACKAGES...] [OPTIONS]
-```
-
-**Arguments:**
-- `PACKAGES` - Optional APM packages to add and install. Accepts shorthand (`owner/repo`), HTTPS URLs, SSH URLs, FQDN shorthand (`host/owner/repo`), local filesystem paths (`./path`, `../path`, `/absolute/path`, `~/path`), or marketplace references (`NAME@MARKETPLACE[#ref]`). All forms are normalized to canonical format in `apm.yml`.
-
-**Options:**
-- `--runtime TEXT` - Target specific runtime only (copilot, codex, vscode, cursor, opencode, gemini, claude,windsurf)
-- `--exclude TEXT` - Exclude specific runtime from installation
-- `--only [apm|mcp]` - Install only specific dependency type
-- `--target, -t [copilot|claude|cursor|codex|opencode|gemini|windsurf|agent-skills|copilot-cowork|all]` - Force deployment to specific target(s). Highest-priority entry in the resolution chain (`--target` > `apm.yml` `target:`/`targets:` > auto-detect). Accepts comma-separated values for multiple targets (e.g., `--target claude,cursor`). `agent-skills` deploys to `.agents/skills/` (cross-client). `all` = copilot+claude+cursor+opencode+codex+gemini+windsurf (excludes agent-skills and copilot-cowork); combine with `agent-skills` for both. With no flag, no `target:` or `targets:` in `apm.yml`, and no harness signal in the project (e.g. `.claude/`, `.cursor/`, `.github/copilot-instructions.md`), `apm install` exits 2 with a teaching message instead of silently defaulting to `copilot`. Run `apm targets` to see what APM detects in the current directory.
-  - `windsurf` - Windsurf/Cascade (`.windsurf/rules/`, `.windsurf/skills/`, `.windsurf/workflows/`, `.windsurf/hooks.json`)
-  - `copilot-cowork` - Microsoft 365 Copilot Cowork skills (user scope only, requires `copilot-cowork` experimental flag). Not included in `all`; must be specified explicitly with `--target copilot-cowork --global`.
-  - `vscode`, `agents` - Deprecated aliases for `copilot` (`.github/`). Still accepted by the parser; prefer `copilot` for GitHub Copilot deployment, or `agent-skills` for cross-client `.agents/skills/` deployment. Removal in v1.0.
-- `--update` - Update dependencies to latest Git references  
-- `--force` - Overwrite locally-authored files on collision; bypass security scan blocks
-- `--dry-run` - Show what would be installed without installing
-- `--parallel-downloads INTEGER` - Max concurrent package downloads (default: 4, 0 to disable)
-- `--verbose` - Show individual file paths and full error details in the diagnostic summary
-- `--trust-transitive-mcp` - Trust self-defined MCP servers from transitive packages (skip re-declaration requirement)
-- `--mcp NAME` - Add an MCP server entry to `apm.yml` and install it. See the [MCP Servers guide](../../guides/mcp-servers/) for the full workflow.
-- `--transport [stdio|http|sse|streamable-http]` - MCP transport (only with `--mcp`). Inferred from `--url` or post-`--` argv when omitted.
-- `--url URL` - Endpoint for `http`/`sse` MCP servers (only with `--mcp`). Scheme must be `http` or `https`.
-- `--env KEY=VALUE` - Environment variable for stdio MCP servers (only with `--mcp`). Repeatable.
-- `--header KEY=VALUE` - HTTP header for remote MCP servers (only with `--mcp`). Repeatable. Requires `--url`.
-- `--mcp-version VER` - Pin a registry MCP entry to a specific version (only with `--mcp`).
-- `--registry URL` - Custom MCP registry URL (`http://` or `https://`) for resolving the registry-form `--mcp NAME`. Overrides `MCP_REGISTRY_URL`. Persisted to `apm.yml` for reproducible installs. Not valid with `--url` or a stdio command. Only with `--mcp`.
-- `--dev` - Add packages to [`devDependencies`](../manifest-schema/#5-devdependencies) instead of `dependencies`. Dev deps are installed locally but excluded from `apm pack` plugin output (and from `apm pack --format apm` bundles too).
-- `-g, --global` - Install to user scope (`~/.apm/`) instead of the current project. Primitives deploy to `~/.copilot/`, `~/.claude/`, etc. MCP servers are only installed for global-capable runtimes (Copilot CLI, Codex CLI); workspace-only runtimes are skipped.
-- `--allow-insecure` - Allow HTTP (insecure) dependencies. Required when adding or installing dependencies that use an `http://` URL.
-- `--allow-insecure-host HOSTNAME` - Allow transitive HTTP (insecure) dependencies from `HOSTNAME`. Repeat the flag to allow multiple hosts.
-- `--ssh` - Force SSH for shorthand (`owner/repo`) dependencies. Mutually exclusive with `--https`. Ignored for URLs with an explicit scheme.
-- `--https` - Force HTTPS for shorthand dependencies. Mutually exclusive with `--ssh`. Default unless `git config url.<base>.insteadOf` rewrites the candidate to SSH.
-- `--allow-protocol-fallback` - Restore the legacy permissive cross-protocol fallback chain (HTTPS-then-SSH or vice-versa). Strict-by-default otherwise. Each retry emits a `[!]` warning naming both protocols. When the dependency URL carries a custom port, APM also emits a one-shot `[!]` warning before the first clone attempt noting that the same port will be reused across schemes (wrong on servers like Bitbucket Datacenter that serve SSH and HTTPS on different ports) -- to avoid the mismatch, omit this flag and pin the dependency with an explicit `ssh://` or `https://` URL.
-- `--no-policy` -- Skip org policy enforcement for this invocation. Loudly logged. Does NOT bypass `apm audit --ci`. Available on `apm install`, `apm install <pkg>`, and `apm install --mcp <name>`.
-  - Equivalent env var: `APM_POLICY_DISABLE=1` (applies to the entire shell session). Note: `apm deps update` runs the install pipeline and is gated by policy but does not currently expose a `--no-policy` flag -- use `APM_POLICY_DISABLE=1` as the only escape hatch there.
-- `--skill NAME` - Install only named skill(s) from a `SKILL_BUNDLE` package. Repeatable. The selection is **persisted** in `apm.yml` (as a `skills:` list in dict-form entries) and in `apm.lock.yaml` (as `skill_subset`), so subsequent bare `apm install` commands are deterministic. Use `--skill '*'` to reset and install all skills from the bundle.
-- `--as ALIAS` - Override the log/display label used when reporting a local-bundle install. Only valid when `PACKAGES` is a single local-bundle path (directory or `.tar.gz`); rejected on registry installs. Falls back to `plugin.json["id"]`, then to the bundle directory name when omitted. Note: this label affects log output only -- the lockfile records `local_deployed_files` (paths) and does not currently namespace by alias.
-- `--legacy-skill-paths` - Restore per-client skill directories (`.github/skills/`, `.cursor/skills/`, etc.) instead of the converged `.agents/skills/` routing. Equivalent env var: `APM_LEGACY_SKILL_PATHS=1`.
-
-**Transport env vars:**
-
-| Variable | Purpose |
-|----------|---------|
-| `APM_GIT_PROTOCOL` | `ssh` or `https`. Default initial transport for shorthand dependencies (overridden by `--ssh` / `--https`). |
-| `APM_ALLOW_PROTOCOL_FALLBACK` | Set to `1` to enable the legacy permissive chain without passing `--allow-protocol-fallback`. |
-
-See [Dependencies: Transport selection](../../guides/dependencies/#transport-selection-ssh-vs-https) for the full selection matrix.
-
-**Behavior:**
-- `apm install` (no args): Installs **all** packages from `apm.yml` and deploys the project's own `.apm/` content
-- `apm install <package>`: Installs **only** the specified package (adds to `apm.yml` if not present)
-- Each `http://` dependency is warned at install time before any fetch begins
-- Transitive `http://` dependencies are allowed automatically when they use the same host as a direct insecure dependency you approved with `--allow-insecure`; other transitive hosts require `--allow-insecure-host HOSTNAME`
-
-**Claude Code: prompt `input:` -> slash command `arguments:`:**
-
-When installing into `.claude/commands/`, prompt files with an `input:` front-matter key are transformed so Claude Code can surface typed argument hints in the slash-command picker:
-
-- `input:` is mapped to Claude's `arguments:` front-matter (preserving order).
-- An `argument-hint:` is auto-generated as `<name1> <name2> ...` unless the prompt already sets one explicitly.
-- `${input:name}` references in the body are rewritten to Claude-style `$name` placeholders (double-brace `${{input:name}}` is also accepted).
-- Argument names are restricted to `^[A-Za-z][\w-]{0,63}$`; names containing YAML-significant characters are rejected with a warning and dropped from the output.
-- A short install-time message lists the mapped arguments per file so the transformation is visible without `--verbose`.
-
-This transformation only applies to the `claude` target. Other targets receive the prompt content unchanged.
-
-**Copilot CLI: env-var translation in `mcp-config.json`:**
-
-When installing MCP servers for the `copilot` target, env-var placeholders in `apm.yml` are **translated** to Copilot CLI's native runtime substitution syntax (`${VAR}`) instead of being resolved to literal values at install time. This applies to HTTP `headers`, stdio `env` blocks, and stdio `args`.
-
-| `apm.yml` syntax    | Written to `~/.copilot/mcp-config.json` |
-|---------------------|------------------------------------------|
-| `${env:VAR}`        | `${VAR}`                                 |
-| `${VAR}`            | `${VAR}` (passthrough)                   |
-| `<VAR>`             | `${VAR}` (with deprecation warning)      |
-| `${VAR:-default}`   | `${VAR:-default}` (passthrough)          |
-| `${input:foo}`      | `${input:foo}` (passthrough)             |
-
-Copilot CLI resolves these at server-start from the host environment, so plaintext secrets are never written to disk. After install, `apm` emits an aggregated summary:
-
-- A **security improvement** warning when overwriting a config that previously stored literal env values, listing the affected variable names.
-- An **unset env var** warning listing every referenced variable not currently exported in your shell, with a copy-pasteable `export KEY=...` hint.
-- A one-line **deprecation** warning when any server still uses the legacy `<VAR>` syntax.
-
-Other targets (`cursor`, `windsurf`, `opencode`, `claude`, `gemini`) continue to resolve env-var placeholders at install time pending per-adapter audits.
-
-**Local `.apm/` Content Deployment:**
-
-After integrating dependencies, `apm install` deploys primitives from the project's own `.apm/` directory (instructions, prompts, agents, skills, hooks, commands) to target directories (`.github/`, `.claude/`, `.cursor/`, etc.). Local content takes priority over dependencies on collision. Deployed files are tracked in the lockfile for cleanup on subsequent installs. This works even with zero dependencies -- just `apm.yml` and `.apm/` content is enough.
-
-Exceptions:
-- Skipped at user scope (`--global`)
-- Skipped with `--only=mcp`
-- Root `SKILL.md` is not deployed as a local skill (it describes the project itself)
-
-**Diff-Aware Installation (manifest as source of truth):**
-- MCP servers already configured with matching config are skipped (`already configured`)
-- MCP servers already configured but with changed manifest config are re-applied automatically (`updated`)
-- APM packages removed from `apm.yml` have their deployed files cleaned up on the next full `apm install`
-- APM packages whose ref/version changed in `apm.yml` are re-downloaded automatically (no `--update` needed)
-- `--force` remains available for full overwrite/reset scenarios
-
-**Stale-file cleanup:**
-
-`apm install` removes files that a still-present package previously deployed but no longer produces -- for example after a package renames or drops a primitive. This keeps the workspace consistent with the manifest without any manual `apm prune`/`uninstall` step. Behaviour:
-
-- Scope: only files recorded under that package's `deployed_files` in `apm.lock.yaml` are eligible
-- Safety gate: paths that escape the project root or fall outside known integration prefixes are refused
-- Directory entries are refused outright -- APM only deletes individual files
-- Per-file provenance: APM records a content hash for each deployed file; if the on-disk content has changed since deploy time the file is treated as user-edited and kept (with a warning explaining how to remove it manually)
-- Skipped when integration reports an error for the package (avoids deleting a file that just failed to redeploy)
-- Files that fail to delete are kept in `deployed_files` and retried on the next `apm install`
-- Use `apm install --dry-run` to preview package-level orphan cleanup; intra-package stale cleanup is not previewed because it requires running integration
-
-**Examples:**
-```bash
-# Install all dependencies from apm.yml
-apm install
-
-# Install ONLY this package (not others in apm.yml)
-apm install microsoft/apm-sample-package
-
-# Install via HTTPS URL (normalized to owner/repo in apm.yml)
-apm install https://github.com/microsoft/apm-sample-package.git
-
-# Install from a non-GitHub host (FQDN preserved)
-apm install https://gitlab.com/acme/coding-standards.git
-
-# Add multiple packages and install
-apm install org/pkg1 org/pkg2
-
-# Install a Claude Skill from a subdirectory
-apm install ComposioHQ/awesome-claude-skills/brand-guidelines
-
-# Install only APM dependencies (skip MCP servers)
-apm install --only=apm
-
-# Install only MCP dependencies (skip APM packages)  
-apm install --only=mcp
-
-# Preview what would be installed
-apm install --dry-run
-
-# Update existing dependencies to latest versions
-apm install --update
-
-# Install for all runtimes except Codex
-apm install --exclude codex
-
-# Trust self-defined MCP servers from transitive packages
-apm install --trust-transitive-mcp
-
-# Add an MCP server in one shot (writes apm.yml + wires every detected client)
-apm install --mcp filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace
-apm install --mcp io.github.github/github-mcp-server
-
-# Install as a dev dependency (excluded from plugin bundles)
-apm install --dev owner/test-helpers
-
-# Install from a local path (copies to apm_modules/_local/)
-apm install ./packages/my-shared-skills
-apm install /home/user/repos/my-ai-package
-
-# Deploy a local APM bundle (directory or .tar.gz produced by `apm pack`).
-# Bundles are an imperative, air-gapped deploy: no apm.yml mutation,
-# no network, no policy / MCP / dependency-resolver involvement.
-# The consumer's project decides where files land (target resolution
-# follows the same precedence as registry installs: --target > apm.yml >
-# directory detection); bundles themselves are target-agnostic.  For
-# compile-only targets (opencode, codex, gemini), instructions are
-# staged under `apm_modules/<slug>/.apm/instructions/` and the install
-# emits a hint to run `apm compile` to merge them.
-apm install ./build/my-bundle
-apm install ./my-bundle.tar.gz
-apm install ./my-bundle --as custom-name   # override the log/display label
-apm install ./my-bundle --target opencode  # override consumer-side target
-
-# Install to user scope (available across all projects)
-apm install -g microsoft/apm-sample-package
-
-# Install a plugin from a registered marketplace
-apm install code-review@acme-plugins
-
-# Install a specific ref from a marketplace
-apm install code-review@acme-plugins#v2.0.0
-```
-
-**Auto-Bootstrap Behavior:**
-- **With packages + no apm.yml**: Automatically creates minimal `apm.yml`, adds packages, and installs
-- **Without packages + no apm.yml**: Shows helpful error suggesting `apm init` or `apm install <org/repo>`
-- **With apm.yml**: Works as before - installs existing dependencies or adds new packages
-
-**Dependency Types:**
-
-- **APM Dependencies**: Git repositories containing `apm.yml` (GitHub, GitLab, Bitbucket, or any git host)
-- **Claude Skills**: Repositories with `SKILL.md` (auto-generates `apm.yml` upon installation)
-  - Example: `apm install ComposioHQ/awesome-claude-skills/brand-guidelines`
-  - Skills are transformed to `.github/agents/*.agent.md` for VSCode target
-- **Hook Packages**: Repositories with `hooks/*.json` (no `apm.yml` or `SKILL.md` required)
-  - Example: `apm install anthropics/claude-plugins-official/plugins/hookify`
-- **Virtual Packages**: Single files or collections installed directly from URLs
-  - Single `.prompt.md` or `.agent.md` files from any GitHub repository
-  - Collections from curated sources (e.g., `github/awesome-copilot`)
-  - Example: `apm install github/awesome-copilot/skills/review-and-refactor`
-- **MCP Dependencies**: Model Context Protocol servers for runtime integration
-
-**Working Example with Dependencies:**
-```yaml
-# Example apm.yml with APM dependencies
-name: my-compliance-project
-version: 1.0.0
-dependencies:
-  apm:
-    - microsoft/apm-sample-package  # Design standards, prompts
-    - github/awesome-copilot/skills/review-and-refactor  # Code review skill
-  mcp:
-    - io.github.github/github-mcp-server
-```
-
-```bash
-# Install all dependencies (APM + MCP)
-apm install
-
-# Install only APM dependencies for faster setup
-apm install --only=apm
-
-# Preview what would be installed  
-apm install --dry-run
-```
-
-**Auto-Detection:**
-
-APM automatically detects which integrations to enable based on your project structure:
-
-- **VSCode integration**: Enabled when `.github/` directory exists
-- **Claude integration**: Enabled when `.claude/` directory exists
-- **Cursor integration**: Enabled when `.cursor/` directory exists
-- **OpenCode integration**: Enabled when `.opencode/` directory exists
-- **Codex integration**: Enabled when `.codex/` directory exists
-- **Gemini integration**: Enabled when `.gemini/` directory exists
-- All integrations can coexist in the same project
-
-**VSCode Integration (`.github/` present):**
-
-When you run `apm install`, APM automatically integrates primitives from installed packages and the project's own `.apm/` directory:
-
-- **Prompts**: `.prompt.md` files → `.github/prompts/*.prompt.md`
-- **Agents**: `.agent.md` files → `.github/agents/*.agent.md`
-- **Chatmodes**: `.chatmode.md` files → `.github/agents/*.agent.md` (renamed to modern format)
-- **Instructions**: `.instructions.md` files → `.github/instructions/*.instructions.md`
-- **Control**: Disable with `apm config set auto-integrate false`
-- **Smart updates**: Only updates when package version/commit changes
-- **Hooks**: Hook `.json` files → `.github/hooks/*.json` with scripts bundled
-- **Collision detection**: Skips local files that aren't managed by APM; use `--force` to overwrite
-- **Security scanning**: Source files are scanned for hidden Unicode characters before deployment. Critical findings (tag characters, bidi overrides) block deployment; use `--force` to override. Exits with code 1 if any package was blocked.
-
-**Diagnostic Summary:**
-
-After installation completes, APM prints a grouped diagnostic summary instead of inline warnings. Categories include collisions (skipped files), cross-package skill replacements, warnings, and errors.
-
-- **Normal mode**: Shows counts and actionable tips (e.g., "9 files skipped -- use `apm install --force` to overwrite")
-- **Verbose mode** (`--verbose`): Additionally lists individual file paths grouped by package, full error details, and **the resolved auth source per remote host** (e.g., `[i] dev.azure.com -- using bearer from az cli (source: AAD_BEARER_AZ_CLI)` or `[i] github.com -- token from GITHUB_APM_PAT`). Useful for diagnosing PAT vs. Entra-ID-bearer behaviour against Azure DevOps. For subdirectory packages with an explicit `#ref` (e.g. `owner/repo/sub#v1.2.0`), `--verbose` also shows each validation probe attempt -- marker-file lookups, the Contents API directory probe, and the `git ls-remote` fallback -- including which auth step (token, credential-helper, SSH) resolved the ref.
-
-```bash
-# See exactly which files were skipped or had issues, and which auth source was used
-apm install --verbose
-```
-
-**Claude Integration (`.claude/` present):**
-
-APM also integrates with Claude Code when `.claude/` directory exists:
-
-- **Agents**: `.agent.md` and `.chatmode.md` files → `.claude/agents/*.md`
-- **Commands**: `.prompt.md` files → `.claude/commands/*.md`
-- **Hooks**: Hook definitions merged into `.claude/settings.json` hooks key
-
-**Skill Integration:**
-
-Skills are copied directly to target directories:
-
-- **Primary**: `.github/skills/{skill-name}/` — Entire skill folder copied
-- **Compatibility**: `.claude/skills/{skill-name}/` — Also copied if `.claude/` folder exists
-
-**Example Integration Output**:
-```
-✓ microsoft/apm-sample-package
-  ├─ 3 prompts integrated → .github/prompts/
-  ├─ 1 instruction(s) integrated → .github/instructions/
-  ├─ 1 agents integrated → .claude/agents/
-  └─ 3 commands integrated → .claude/commands/
-```
-
-This makes all package primitives available in VSCode, Cursor, OpenCode, Claude Code, and compatible editors for immediate use with your coding agents.
-
-### `apm targets` - Show resolved deployment targets
-
-Inspect which harness targets `apm install` and `apm compile` will deploy to from the current directory, and why. This is the discovery surface for the resolution chain (`--target` flag > `apm.yml` `targets:` > auto-detect from filesystem signals).
-
-`apm targets` works with or without `apm.yml`: it reads filesystem signals (`.claude/`, `CLAUDE.md`, `.cursor/`, `.cursorrules`, `.github/copilot-instructions.md`, `.codex/`, `.gemini/`, `GEMINI.md`, `.opencode/`, `.windsurf/`) and reports each canonical target as `active` or inactive. Implemented as a Click *group* so future sub-commands can attach without breaking the bare `apm targets` invocation.
-
-```bash
-apm targets [OPTIONS]
-```
-
-**Options:**
-- `--all` - Also include the `agent-skills` meta-target (only meaningful with `--json`; the default table already lists every canonical harness target).
-- `--json` - Emit machine-readable JSON instead of the table.
-
-**Sample table output:**
-```
-  TARGET       STATUS     SOURCE                                   DEPLOY DIR
-  ------------ ---------- ---------------------------------------- ----------
-  claude       active     CLAUDE.md                                .claude/
-  copilot      inactive   needs .github/copilot-instructions.md    .github/
-  cursor       active     .cursor/                                 .cursor/
-  codex        inactive   needs .codex/                            .codex/
-  gemini       inactive   needs GEMINI.md                          .gemini/
-  opencode     inactive   needs .opencode/                         .opencode/
-  windsurf     inactive   needs .windsurf/                         .windsurf/
-```
-
-The `STATUS` column is `active` when APM detects a signal for that harness, otherwise `inactive`. The `SOURCE` column shows the detected signal path for active rows, and `needs <path>` for inactive rows so the recovery path is self-documenting. The `agent-skills` meta-target is intentionally excluded from the table and only surfaces in `--all --json`.
-
-**Sample `--json` output:**
-```json
-[
-  {"target": "claude", "status": "active", "source": "CLAUDE.md", "deploy_dir": ".claude/", "needs": null},
-  {"target": "copilot", "status": "inactive", "source": null, "deploy_dir": ".github/", "needs": ".github/copilot-instructions.md"},
-  {"target": "cursor", "status": "active", "source": ".cursor/", "deploy_dir": ".cursor/", "needs": null}
-]
-```
-
-Output is a JSON array of per-target objects ordered by canonical target order (claude, copilot, cursor, codex, gemini, opencode, windsurf), not alphabetical. Each object exposes `target`, `status`, `source`, `deploy_dir`, and `needs`. With `--all --json`, an additional row `{"target": "agent-skills", ..., "meta_target": true}` is appended.
-
-**Use cases:**
-- **Discovery** - "What will `apm install` deploy to in this directory?" before running it.
-- **Scripting** - parse `--json` in CI to assert the expected target set or detect unexpected drift.
-- **Debugging** - diagnose why `apm install` chose a specific target (e.g. an upstream package shipped a stray `CLAUDE.md` that APM picked up as a Claude Code signal).
-
-If APM detects a target you don't intend (a documentation `CLAUDE.md` or `GEMINI.md` is the most common false positive), pin your targets explicitly in `apm.yml`:
-
-```yaml
-targets:
-  - copilot
-```
-
-See [`apm install`](#apm-install---install-dependencies-and-deploy-local-content) and [`apm compile`](#apm-compile---compile-apm-context-into-distributed-agentsmd-files) for how the resolved targets feed into deployment.
-
-### `apm uninstall` - Remove APM packages
-
-Remove installed APM packages and their integrated files.
-
-```bash
-apm uninstall [OPTIONS] PACKAGES...
-```
-
-**Arguments:**
-- `PACKAGES...` - One or more packages to uninstall. Accepts any format — shorthand (`owner/repo`), HTTPS URL, SSH URL, or FQDN. APM resolves each to the canonical identity stored in `apm.yml`.
-
-**Options:**
-- `--dry-run` - Show what would be removed without removing
-- `-v, --verbose` - Show detailed removal information
-- `-g, --global` - Remove from user scope (`~/.apm/`) instead of the current project
-
-**Examples:**
-```bash
-# Uninstall a package
-apm uninstall microsoft/apm-sample-package
-
-# Uninstall using an HTTPS URL (resolves to same identity)
-apm uninstall https://github.com/microsoft/apm-sample-package.git
-
-# Preview what would be removed
-apm uninstall microsoft/apm-sample-package --dry-run
-
-# Uninstall from user scope
-apm uninstall -g microsoft/apm-sample-package
-```
-
-**What Gets Removed:**
-
-| Item | Location |
-|------|----------|
-| Package entry | `apm.yml` dependencies section |
-| Package folder | `apm_modules/owner/repo/` |
-| Transitive deps | `apm_modules/` (orphaned transitive dependencies) |
-| Integrated prompts | `.github/prompts/*.prompt.md` |
-| Integrated agents | `.github/agents/*.agent.md` |
-| Integrated chatmodes | `.github/agents/*.agent.md` |
-| Claude commands | `.claude/commands/*.md` |
-| Skill folders | `.github/skills/{folder-name}/` |
-| Integrated hooks | `.github/hooks/*.json` |
-| Claude hook settings | `.claude/settings.json` (hooks key cleaned) |
-| Cursor rules | `.cursor/rules/*.mdc` |
-| Cursor agents | `.cursor/agents/*.md` |
-| Cursor commands | `.cursor/commands/*.md` (Cursor 1.6+) |
-| Cursor skills | `.cursor/skills/{folder-name}/` |
-| Cursor hooks | `.cursor/hooks.json` (hooks key cleaned) |
-| OpenCode agents | `.opencode/agents/*.md` |
-| OpenCode commands | `.opencode/commands/*.md` |
-| OpenCode skills | `.opencode/skills/{folder-name}/` |
-| Gemini commands | `.gemini/commands/*.toml` |
-| Gemini skills | `.gemini/skills/{folder-name}/` |
-| Gemini settings | `.gemini/settings.json` (hooks + MCP cleaned) |
-| Lockfile entries | `apm.lock.yaml` (removed packages + orphaned transitives) |
-
-**Behavior:**
-- Removes package from `apm.yml` dependencies
-- Deletes package folder from `apm_modules/`
-- Removes orphaned transitive dependencies (npm-style pruning via `apm.lock.yaml`)
-- Removes all deployed integration files tracked in `apm.lock.yaml` `deployed_files`
-- Updates `apm.lock.yaml` (or deletes it if no dependencies remain)
-- Cleans up empty parent directories
-- Safe operation: only removes files tracked in the `deployed_files` manifest
-
-### `apm prune` - Remove orphaned packages
-
-Remove APM packages from `apm_modules/` that are not listed in `apm.yml`, along with their deployed integration files (prompts, agents, hooks, etc.).
-
-```bash
-apm prune [OPTIONS]
-```
-
-**Options:**
-- `--dry-run` - Show what would be removed without removing
-
-**Examples:**
-```bash
-# Remove orphaned packages and their deployed files
-apm prune
-
-# Preview what would be removed
-apm prune --dry-run
-```
-
-**Behavior:**
-- Removes orphaned package directories from `apm_modules/`
-- Removes deployed integration files (prompts, agents, hooks, etc.) for pruned packages using the `deployed_files` manifest in `apm.lock.yaml`
-- Updates `apm.lock.yaml` to reflect the pruned state
-
-### `apm audit` - Scan for hidden Unicode characters
-
-Scan installed packages or arbitrary files for hidden Unicode characters that could embed invisible instructions in prompt files.
-
-```bash
-apm audit [PACKAGE] [OPTIONS]
-```
-
-**Arguments:**
-- `PACKAGE` - Optional package key to scan (repo URL from lockfile). If omitted, scans all installed packages.
-
-**Options:**
-- `--file PATH` - Scan an arbitrary file instead of installed packages
-- `--strip` - Remove dangerous characters (critical + warning severity) while preserving info-level content like emoji. ZWJ inside emoji sequences is preserved.
-- `--dry-run` - Preview what `--strip` would remove without modifying files
-- `-v, --verbose` - Show info-level findings and file details
-- `-f, --format [text|json|sarif|markdown]` - Output format: `text` (default), `json` (machine-readable), `sarif` (GitHub Code Scanning), `markdown` (step summaries). Cannot be combined with `--strip` or `--dry-run`.
-- `-o, --output PATH` - Write report to file. Auto-detects format from extension (`.sarif`, `.sarif.json` → SARIF; `.json` → JSON; `.md` → Markdown) when `--format` is not specified.
-- `--ci` - Run lockfile consistency checks for CI/CD gates. Exit 0 if clean, 1 if violations found. Auto-discovers org policy from the org `.github` repo unless `--no-policy` is set. Runs the 7 baseline checks: lockfile presence, ref consistency, deployed files present, no orphaned packages, MCP config consistency, content integrity (Unicode + hash drift on every deployed file including local content), includes consent (advisory). Integration drift detection runs by default alongside the baseline checks and contributes to the exit code (use `--no-drift` to opt out).
-- `--policy SOURCE` - *(Experimental)* Policy source. Accepts: `org` (auto-discover from your project's git remote), `owner/repo` (defaults to github.com), an `https://` URL, or a local file path. Used with `--ci` for policy checks. Without this flag, `--ci` auto-discovers.
-- `--no-policy` - Skip policy discovery and enforcement entirely. Equivalent to `APM_POLICY_DISABLE=1`.
-- `--no-cache` - Force fresh policy fetch (skip cache). Only relevant with policy discovery active.
-- `--no-fail-fast` - Run all checks even after a failure. By default, CI mode stops at the first failing check to save time.
-- `--no-drift` - Skip integration drift detection. Drift detection is on by default (whole-project audit only) and replays the install pipeline into a scratch tree to catch missed `apm install` runs, hand-edited deployed files, and orphaned files. Mutually exclusive with `--strip`/`--file`. See the [Drift Detection guide](../../guides/drift-detection/).
-
-**Examples:**
-```bash
-# Scan all installed packages
-apm audit
-
-# Scan a specific package
-apm audit https://github.com/owner/repo
-
-# Scan any file (even non-APM-managed)
-apm audit --file .cursorrules
-
-# Remove dangerous characters (preserves emoji)
-apm audit --strip
-
-# Preview what --strip would remove
-apm audit --strip --dry-run
-
-# Verbose output with info-level findings
-apm audit --verbose
-
-# SARIF output to stdout (for CI pipelines)
-apm audit -f sarif
-
-# Markdown output (for GitHub step summaries)
-apm audit -f markdown
-
-# Write SARIF report to file
-apm audit -o report.sarif
-
-# JSON report to file
-apm audit -f json -o results.json
-
-# CI lockfile consistency gate (auto-discovers org policy)
-apm audit --ci
-
-# CI gate skipping policy discovery (baseline checks only)
-apm audit --ci --no-policy
-
-# CI gate with explicit policy source (overrides auto-discovery)
-apm audit --ci --policy org
-
-# CI gate with local policy file
-apm audit --ci --policy ./apm-policy.yml
-
-# Force fresh policy fetch
-apm audit --ci --no-cache
-
-# Run all checks (no fail-fast) for full diagnostic report
-apm audit --ci --policy org --no-fail-fast
-```
-
-**Exit codes (content scanning mode):**
-| Code | Meaning |
-|------|---------|
-| 0 | Clean — no findings, info-only, or successful strip |
-| 1 | Critical findings — tag characters, bidi overrides, or variation selectors 17–256 |
-| 2 | Warnings only — zero-width characters, bidi marks, or other suspicious content |
-
-**Exit codes (`--ci` mode):**
-| Code | Meaning |
-|------|---------|
-| 0 | All checks passed |
-| 1 | One or more checks failed |
-
-**What it detects:**
-- **Critical**: Tag characters (U+E0001–E007F), bidi overrides (U+202A–E, U+2066–9), variation selectors 17–256 (U+E0100–E01EF, Glassworm attack vector)
-- **Warning**: Zero-width spaces/joiners (U+200B–D), variation selectors 1–15 (U+FE00–FE0E), bidi marks (U+200E–F, U+061C), invisible operators (U+2061–4), annotation markers (U+FFF9–B), deprecated formatting (U+206A–F), soft hyphen (U+00AD), mid-file BOM
-- **Info**: Non-breaking spaces, unusual whitespace, emoji presentation selector (U+FE0F). ZWJ between emoji characters is context-downgraded to info.
-- **Hash drift (`--ci` only)**: Files deployed by `apm install` whose on-disk SHA-256 no longer matches the value recorded in the lockfile (`deployed_file_hashes`). Covers content from package dependencies AND local `.apm/` content via the synthesized self-entry.
-
-### `apm policy` - Inspect organization policy
-
-Diagnostic commands for the organization-level `apm-policy.yml` resolved by APM at install / audit time. See [Policy Reference](../../enterprise/policy-reference/) for the full schema and enforcement model.
-
-#### `apm policy status` - Show resolved policy state
-
-Show what policy APM resolved for the current project: discovery outcome, source, enforcement level, cache age, `extends:` chain, and effective rule counts. Trust-but-verify diagnostic for admins and CI gates.
-
-```bash
-apm policy status [OPTIONS]
-```
-
-**Options:**
-- `--policy-source SOURCE` - Override discovery. Accepts: `org` (auto-discover from your project's git remote), `owner/repo` (defaults to github.com), an `https://` URL, or a local file path.
-- `--no-cache` - Force fresh fetch (skip cache).
-- `--json` / `-o json` - Machine-readable output for SIEM ingestion or CI inspection.
-- `--check` - Exit non-zero (1) when no usable policy is found. Default is always 0; use `--check` for CI pre-checks.
-
-**Exit codes:**
-
-| Mode | `outcome=found` | Anything else (absent, error, disabled, ...) |
-|------|-----------------|-----------------------------------------------|
-| default | 0 | 0 |
-| `--check` | 0 | 1 |
-
-The default is exit-0 so the command is safe for human and SIEM use; `--check` opts into a CI-friendly contract similar to `npm audit` / `pip check`. To gate on policy compliance (rule violations) instead of resolvability, use `apm audit --ci`.
-
-**Examples:**
-```bash
-# Show resolved org policy state
-apm policy status
-
-# Force fresh fetch (bypass cache)
-apm policy status --no-cache
-
-# Machine-readable JSON for SIEM
-apm policy status --json
-
-# Inspect a specific policy without committing it
-apm policy status --policy-source ./draft-policy.yml
-
-# CI gate: fail the job if no usable policy is resolved
-apm policy status --check
-```
-
-### `apm pack` - Pack distributable artifacts
-
-Pack distributable artifacts from your APM project. The manifest drives what gets produced:
-
-- `dependencies:` block in `apm.yml` -> bundle (directory or `.tar.gz`)
-- `marketplace:` block in `apm.yml` -> `.claude-plugin/marketplace.json`
-- both blocks present -> both artifacts in a single run
-
-The lockfile (`apm.lock.yaml`) pins bundle contents. An enriched copy is embedded in each bundle.
-
-```bash
-apm pack [OPTIONS]
-```
-
-**Options:**
-- `-o, --output PATH` - Bundle output directory (default: `./build`). Does not affect `marketplace.json` path.
-- `-t, --target` - **Deprecated.** Emits a warning; the value is recorded in `pack.target` as diagnostic metadata and is ignored by `apm install` target resolution. Bundles are target-agnostic; the consumer's project decides where files land at install time. Old bundles that carry `pack.target` remain installable.
-- `--archive` - Produce a `.tar.gz` archive instead of a directory. Bundle only.
-- `--format [plugin|apm]` - Bundle format (default: `plugin`). `plugin` emits a Claude Code plugin directory with a schema-conformant `plugin.json` ([official schema](https://json.schemastore.org/claude-code-plugin.json)). `apm` produces the legacy APM bundle layout (consumed by `microsoft/apm-action@v1` restore mode and other bundle-aware tooling). No-op for marketplace output.
-- `--force` - On collision (plugin format), last writer wins instead of first. Bundle only.
-- `--dry-run` - Preview outputs without writing anything.
-- `--offline` - Marketplace: use cached refs only (skip `git ls-remote`).
-- `--include-prerelease` - Marketplace: allow pre-release tags to satisfy version ranges.
-- `--marketplace-output PATH` - Marketplace: override the output path (default: `.claude-plugin/marketplace.json`).
-- `-v, --verbose` - Detailed output from every producer.
-
-Flags whose scope does not match the detected outputs are silent no-ops, not errors. CI scripts can pass `--offline` unconditionally even when some projects only produce a bundle.
-
-**Exit codes:**
-- `0` - Success
-- `1` - Build or runtime error (network failure, ref not found, no tag matches a range, etc.)
-- `2` - Schema validation error in `apm.yml`
-
-**Examples:**
-```bash
-# Bundle only (apm.yml has dependencies:, no marketplace:)
-apm pack                              # plugin format (default)
-apm pack --archive                    # tarball
-apm pack --format apm -o ./dist       # legacy APM bundle layout
-
-# Marketplace only (apm.yml has marketplace:, no dependencies:)
-apm pack
-apm pack --offline --dry-run
-
-# Both blocks present -- one command, both artifacts
-apm pack
-apm pack --archive --offline
-
-# Override marketplace.json path (rare; default matches Anthropic spec)
-apm pack --marketplace-output ./build/marketplace.json
-```
-
-**Bundle behaviour:**
-- Reads `apm.lock.yaml` to enumerate all `deployed_files` from installed dependencies
-- Scans files for hidden Unicode characters before bundling -- warns if findings are detected (non-blocking; consumers are protected by `apm install`/`apm unpack` which block on critical)
-- **Plugin format (default):** Remaps `.apm/` content into plugin-native paths (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`); generates or updates a schema-conformant `plugin.json` (convention-dir keys are stripped because Claude Code auto-discovers them); merges hooks into a single `hooks.json`. `devDependencies` are excluded. Embeds an enriched `apm.lock.yaml` (per-file SHA-256 `bundle_files` manifest) so `apm install <bundle>` can verify integrity at install time. See [Pack & Distribute -- Plugin format](../../guides/pack-distribute/#plugin-format-vs-apm-format).
-- **APM format (`--format apm`):** Copies files preserving the install-time directory structure; writes an enriched `apm.lock.yaml` inside the bundle with a `pack:` metadata section (the project's own `apm.lock.yaml` is never modified). Consumed by `microsoft/apm-action@v1` restore mode and other bundle-aware tooling.
-- **Target-agnostic transport:** The bundle carries no target binding. `apm install <bundle>` on the consumer side resolves the target from the consumer's project (`--target` > `apm.yml` > directory detection) and routes primitives accordingly. Compile-only targets (opencode, codex, gemini) receive instructions staged under `apm_modules/<slug>/.apm/instructions/` for the next `apm compile`.
-
-**Marketplace behaviour:**
-- Reads the `marketplace:` block from `apm.yml` (falls back to legacy `marketplace.yml` with a deprecation warning when no block is present; both files present is a hard error)
-- Resolves each remote plugin's version range against `git ls-remote`; emits local-path entries verbatim
-- Writes `.claude-plugin/marketplace.json` atomically -- this is where Claude Code reads the file from the repo root
-- Creates `.claude-plugin/` if absent; never scaffolds other files there
-- See the [Authoring a marketplace guide](../../guides/marketplace-authoring/) for the full schema and workflow
-
-**Enriched lockfile example:**
-```yaml
-pack:
-  format: apm
-  packed_at: '2026-03-09T12:00:00+00:00'
-  bundle_files:
-    .github/agents/architect.md: a1b2c3...
-lockfile_version: '1'
-generated_at: ...
-dependencies:
-  - repo_url: owner/repo
-    ...
-```
-
-### `apm unpack` - Extract a bundle
-
-> **Deprecated (since 0.12).** Prefer `apm install <bundle-path>` for deploying
-> local bundles -- it shares the same air-gapped path with no network I/O,
-> integrates with target resolution, and records deployed files in the
-> project lockfile (`local_deployed_files`). `apm unpack` remains available
-> for raw archive extraction without integration semantics.
-
-Extract an APM bundle into the current project with optional completeness verification.
-
-```bash
-apm unpack BUNDLE_PATH [OPTIONS]
-```
-
-**Arguments:**
-- `BUNDLE_PATH` - Path to a `.tar.gz` archive or an unpacked bundle directory
-
-**Options:**
-- `-o, --output PATH` - Target project directory (default: current directory)
-- `--skip-verify` - Skip completeness verification against the bundle lockfile
-- `--force` - Deploy despite critical hidden-character findings
-- `--dry-run` - Show what would be extracted without writing anything
-
-**Examples:**
-```bash
-# Unpack an archive into the current directory
-apm unpack ./build/my-pkg-1.0.0.tar.gz
-
-# Unpack into a specific directory
-apm unpack bundle.tar.gz --output /path/to/project
-
-# Skip verification (useful for partial bundles)
-apm unpack bundle.tar.gz --skip-verify
-
-# Preview what would be extracted
-apm unpack bundle.tar.gz --dry-run
-
-# Deploy despite critical hidden-character findings
-apm unpack bundle.tar.gz --force
-```
-
-**Behavior:**
-- **Additive-only**: only writes files listed in the bundle's `apm.lock.yaml`; never deletes existing files
-- If a local file has the same path as a bundle file, the bundle file wins (overwrite)
-- **Security scanning**: Bundle contents are scanned before deployment. Critical findings block deployment unless `--force` is used (exit code 1)
-- Verification checks that all `deployed_files` from the bundle lockfile are present in the bundle
-- The bundle's `apm.lock.yaml` is metadata only — it is **not** copied to the output directory
-
-### `apm update` - Update APM to the latest version
-
-Update the APM CLI to the latest version available on GitHub releases.
-
-```bash
-apm update [OPTIONS]
-```
-
-**Options:**
-- `--check` - Only check for updates without installing
-
-**Examples:**
-```bash
-# Check if an update is available
-apm update --check
-
-# Update to the latest version
-apm update
-```
-
-**Behavior:**
-- Fetches latest release from GitHub
-- Compares with current installed version
-- Downloads and runs the official platform installer (`install.sh` on macOS/Linux, `install.ps1` on Windows)
-- Preserves existing configuration and projects
-- Shows progress and success/failure status
-- Some package-manager distributions can disable self-update at build time. 
-  In those builds, `apm update` prints a distributor-defined guidance message
-  (for example, a `brew upgrade` command) and exits without running the installer.
-
-**Version Checking:**
-APM automatically checks for updates (at most once per day) when running any command. If a newer version is available, you'll see a yellow warning:
-
-```
-⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
-Run apm update to upgrade
-```
-
-This check is non-blocking and cached to avoid slowing down the CLI.
-
-In distributions that disable self-update at build time, this startup update notification is skipped.
-
-**Manual Update:**
-If the automatic update fails, you can always update manually:
-
-#### Linux / macOS
-```bash
-curl -sSL https://aka.ms/apm-unix | sh
-```
-
-#### Windows
-```powershell
-powershell -ExecutionPolicy Bypass -c "irm https://aka.ms/apm-windows | iex"
-```
-
-### `apm view` - View package metadata or list remote versions
-
-Show local metadata for an installed package, or query remote refs with a field selector.
-
-> **Note:** `apm info` is accepted as a hidden alias for backward compatibility.
-
-```bash
-apm view PACKAGE [FIELD] [OPTIONS]
-```
-
-**Arguments:**
-- `PACKAGE` - Package name: `owner/repo`, short repo name, or `NAME@MARKETPLACE` for marketplace plugins
-- `FIELD` - Optional field selector. Supported value: `versions`
-
-**Options:**
-- `-g, --global` - Inspect package from user scope (`~/.apm/`)
-
-**Examples:**
-```bash
-# Show installed package metadata
-apm view microsoft/apm-sample-package
-
-# Short-name lookup for an installed package
-apm view apm-sample-package
-
-# List remote tags and branches without cloning
-apm view microsoft/apm-sample-package versions
-
-# View available versions for a marketplace plugin
-apm view code-review@acme-plugins
-
-# Inspect a package from user scope
-apm view microsoft/apm-sample-package -g
-```
-
-**Behavior:**
-- Without `FIELD`, reads installed package metadata from `apm_modules/`
-- Shows package name, version, description, source, install path, context files, workflows, and hooks
-- `versions` lists remote tags and branches without cloning the repository
-- `versions` does not require the package to be installed locally
-- `NAME@MARKETPLACE` syntax shows the marketplace plugin metadata (name, version, source, description, tags)
-
-### `apm outdated` - Check locked dependencies for updates
-
-Compare locked dependencies against remote refs to detect staleness.
-
-```bash
-apm outdated [OPTIONS]
-```
-
-**Options:**
-- `-g, --global` - Check user-scope dependencies from `~/.apm/`
-- `-v, --verbose` - Show extra detail for outdated packages, including available tags
-- `-j, --parallel-checks N` - Max concurrent remote checks (default: 4, 0 = sequential)
-
-**Examples:**
-```bash
-# Check project dependencies
-apm outdated
-
-# Check user-scope dependencies
-apm outdated --global
-
-# Show available tags for outdated packages
-apm outdated --verbose
-
-# Use 8 parallel checks for large dependency sets
-apm outdated -j 8
-```
-
-**Behavior:**
-- Reads the current lockfile (`apm.lock.yaml`; legacy `apm.lock` is migrated automatically)
-- For tag-pinned deps: compares the locked semver tag against the latest available remote tag
-- For branch-pinned deps: compares the locked commit SHA against the remote branch tip SHA
-- For marketplace deps: compares the installed ref against the marketplace entry's current `source.ref`
-- For deps with no ref: compares against the default branch (main/master) tip SHA
-- Displays `Package`, `Current`, `Latest`, `Status`, and `Source` columns
-- `Source` shows `marketplace: <name>` for marketplace-sourced deps
-- Status values are `up-to-date`, `outdated`, and `unknown`
-- Local dependencies and Artifactory dependencies are skipped
-
-### `apm deps` - Manage APM package dependencies
-
-Manage APM package dependencies with installation status, tree visualization, and package information.
-
-```bash
-apm deps COMMAND [OPTIONS]
-```
-
-#### `apm deps list` - List installed APM dependencies
-
-Show all installed APM dependencies in a Rich table format with per-primitive counts.
-
-```bash
-apm deps list [OPTIONS]
-```
-
-**Options:**
-- `-g, --global` - List user-scope packages from `~/.apm/` instead of the current project
-- `--all` - List packages from both project and user scope
-- `--insecure` - Show only installed dependencies locked to `http://` sources
-
-**Examples:**
-```bash
-# Show project-scope packages
-apm deps list
-
-# Show user-scope packages
-apm deps list -g
-
-# Show both scopes
-apm deps list --all
-
-# Show only insecure installed dependencies
-apm deps list --insecure
-```
-
-**Sample Output:**
-```
-┌─────────────────────┬─────────┬──────────┬─────────┬──────────────┬────────┬────────┐
-│ Package             │ Version │ Source   │ Prompts │ Instructions │ Agents │ Skills │
-├─────────────────────┼─────────┼──────────┼─────────┼──────────────┼────────┼────────┤
-│ compliance-rules    │ 1.0.0   │ github   │    2    │      1       │   -    │   1    │
-│ design-guidelines   │ 1.0.0   │ github   │    -    │      1       │   1    │   -    │
-└─────────────────────┴─────────┴──────────┴─────────┴──────────────┴────────┴────────┘
-```
-
-With `--insecure`, an additional `Origin` column (rendered bold red) sits
-between `Source` and `Prompts`. Values are `direct` for HTTP deps declared
-in `apm.yml` and `via <parent>` for transitive HTTP deps pulled in by
-another package:
-
-```
-┌─────────────────┬─────────┬──────────┬────────────────┬─────────┬──────────────┬────────┬────────┐
-│ Package         │ Version │ Source   │ Origin         │ Prompts │ Instructions │ Agents │ Skills │
-├─────────────────┼─────────┼──────────┼────────────────┼─────────┼──────────────┼────────┼────────┤
-│ internal-pkg    │ 1.0.0   │ github   │ direct         │    1    │      -       │   -    │   -    │
-│ shared-rules    │ 2.0.0   │ github   │ via acme/pkg   │    -    │      1       │   -    │   -    │
-└─────────────────┴─────────┴──────────┴────────────────┴─────────┴──────────────┴────────┴────────┘
-```
-
-**Output includes:**
-- Package name and version
-- Source information
-- Per-primitive counts (prompts, instructions, agents, skills)
-
-#### `apm deps tree` - Show dependency tree structure
-
-Display dependencies in hierarchical tree format with primitive counts.
-
-```bash
-apm deps tree  
-```
-
-**Examples:**
-```bash
-# Show dependency tree
-apm deps tree
-```
-
-**Sample Output:**
-```
-company-website (local)
-├── compliance-rules@1.0.0
-│   ├── 1 instructions
-│   ├── 1 chatmodes
-│   └── 3 agent workflows
-└── design-guidelines@1.0.0
-    ├── 1 instructions
-    └── 3 agent workflows
-```
-
-**Output format:**
-- Hierarchical tree showing project name and dependencies
-- File counts grouped by type (instructions, chatmodes, agent workflows)
-- Version numbers from dependency package metadata
-- Version information for each dependency
-
-#### `apm deps info` - Alias for `apm view`
-
-Backward-compatible alias for `apm view PACKAGE_NAME`.
-
-```bash
-apm deps info PACKAGE_NAME
-```
-
-**Arguments:**
-- `PACKAGE_NAME` - Installed package name to inspect
-
-**Examples:**
-```bash
-# Show installed package metadata
-apm deps info compliance-rules
-```
-
-**Notes:**
-- Produces the same local metadata output as `apm view PACKAGE_NAME`
-- Use `apm view` in new docs and scripts
-- For remote refs, use `apm view PACKAGE_NAME versions`
-
-#### `apm deps clean` - Remove all APM dependencies
-
-Remove the entire `apm_modules/` directory and all installed APM packages.
-
-```bash
-apm deps clean [OPTIONS]
-```
-
-**Options:**
-- `--dry-run` - Show what would be removed without removing
-- `--yes`, `-y` - Skip confirmation prompt (for non-interactive/scripted use)
-
-**Examples:**
-```bash
-# Remove all APM dependencies (with confirmation)
-apm deps clean
-
-# Preview what would be removed
-apm deps clean --dry-run
-
-# Remove without confirmation (e.g. in CI pipelines)
-apm deps clean --yes
-```
-
-**Behavior:**
-- Shows confirmation prompt before deletion (unless `--yes` is provided)
-- Removes entire `apm_modules/` directory
-- Displays count of packages that will be removed
-- Can be cancelled with Ctrl+C or 'n' response
-
-#### `apm deps update` - Update APM dependencies
-
-Re-resolve git references for all dependencies (direct and transitive) to their
-latest commits, download updated content, re-integrate primitives, and regenerate
-the lockfile.
-
-```bash
-apm deps update [PACKAGES...] [OPTIONS]
-```
-
-**Arguments:**
-- `PACKAGES` - Optional. One or more packages to update. Omit to update all.
-
-**Options:**
-- `--verbose, -v` - Show detailed update information
-- `--force` - Overwrite locally-authored files on collision
-- `-g, --global` - Update user-scope dependencies (`~/.apm/`)
-- `--target, -t` - Force deployment to specific target(s). Accepts comma-separated values (e.g., `-t claude,copilot`). Valid values: copilot, claude, cursor, opencode, codex, gemini, windsurf, agent-skills, vscode, agents (deprecated), all. `agent-skills` deploys to `.agents/skills/` (cross-client). `all` excludes agent-skills.
-- `--parallel-downloads` - Max concurrent downloads (default: 4)
-
-**Policy enforcement:** `apm deps update` runs the install pipeline and is therefore gated by org `apm-policy.yml`. There is no `--no-policy` flag on this command -- the only escape hatch is `APM_POLICY_DISABLE=1` for the shell session. See [Policy reference](../../enterprise/policy-reference/#install-time-enforcement).
-
-**Examples:**
-```bash
-# Update all APM dependencies to latest refs
-apm deps update
-
-# Update a specific package (short name or full owner/repo)
-apm deps update owner/compliance-rules
-
-# Update multiple packages
-apm deps update org/pkg-a org/pkg-b
-
-# Update with verbose output
-apm deps update --verbose
-
-# Force overwrite local files on collision
-apm deps update --force
-```
-
-### `apm mcp` - Browse MCP server registry
-
-Browse and discover MCP servers from the GitHub MCP Registry.
-
-```bash
-apm mcp COMMAND [OPTIONS]
-```
-
-All `apm mcp` subcommands and `apm install --mcp` honour the [`MCP_REGISTRY_URL`](../../guides/mcp-servers/#custom-registry-enterprise) environment variable for custom (e.g. enterprise) MCP registries.
-
-#### `apm mcp install` - Add an MCP server (alias)
-
-Alias for [`apm install --mcp`](#apm-install---install-dependencies-and-deploy-local-content). Forwards every argument and flag. See the [MCP Servers guide](../../guides/mcp-servers/) for the full reference.
-
-```bash
-apm mcp install NAME [OPTIONS] [-- COMMAND ARGV...]
-```
-
-**Arguments:**
-- `NAME` - MCP server name. Use a registry name for registry installs, or a local name for self-defined stdio and remote servers.
-
-**Options:**
-- `--transport [stdio|http|sse|streamable-http]` - MCP transport. Inferred from `--url` or post-`--` argv when omitted.
-- `--url URL` - MCP server URL for `http`, `sse`, or `streamable-http` transports.
-- `--env KEY=VALUE` - Environment variable for stdio MCP servers. Repeatable.
-- `--header KEY=VALUE` - HTTP header for remote MCP servers. Repeatable.
-- `--mcp-version VER` - Pin a registry MCP entry to a specific version.
-- `--registry URL` - Custom MCP registry URL for resolving `NAME`.
-- `--dev` - Add the server to `devDependencies`.
-- `--dry-run` - Show what would be added without writing.
-- `--force` - Replace an existing MCP entry.
-- `-v, --verbose` - Show detailed output.
-- `--no-policy` - Skip org policy enforcement for this invocation.
-
-**Examples:**
-```bash
-# stdio (post-`--` argv)
-apm mcp install filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace
-
-# Registry
-apm mcp install io.github.github/github-mcp-server
-
-# Remote
-apm mcp install linear --transport http --url https://mcp.linear.app/sse
-```
-
-Set the [`MCP_REGISTRY_URL`](../../guides/mcp-servers/#custom-registry-enterprise) environment variable to point all `apm mcp` commands and `apm install --mcp` at a custom MCP registry. The URL must use `https://`; set `MCP_REGISTRY_ALLOW_HTTP=1` to opt in to plaintext `http://` for development. When a custom registry is set and unreachable during install pre-flight, network errors are fatal (the default registry keeps the existing assume-valid behaviour).
-
-#### `apm mcp list` - List MCP servers
-
-List all available MCP servers from the registry.
-
-```bash
-apm mcp list [OPTIONS]
-```
-
-**Options:**
-- `--limit INTEGER` - Number of results to show (default: 20)
-
-**Examples:**
-```bash
-# List available MCP servers
-apm mcp list
-
-# Limit results
-apm mcp list --limit 20
-```
-
-#### `apm mcp search` - Search MCP servers
-
-Search for MCP servers in the GitHub MCP Registry.
-
-```bash
-apm mcp search QUERY [OPTIONS]
-```
-
-**Arguments:**
-- `QUERY` - Search term to find MCP servers
-
-**Options:**
-- `--limit INTEGER` - Number of results to show (default: 10)
-
-**Examples:**
-```bash
-# Search for filesystem-related servers
-apm mcp search filesystem
-
-# Search with custom limit
-apm mcp search database --limit 5
-
-# Search for GitHub integration
-apm mcp search github
-```
-
-#### `apm mcp show` - Show MCP server details
-
-Show detailed information about a specific MCP server from the registry.
-
-```bash
-apm mcp show SERVER_NAME
-```
-
-**Arguments:**
-- `SERVER_NAME` - Name or ID of the MCP server to show
-
-**Examples:**
-```bash
-# Show details for a server by name
-apm mcp show @modelcontextprotocol/servers/src/filesystem
-
-# Show details by server ID
-apm mcp show a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1
-```
-
-**Output includes:**
-- Server name and description
-- Latest version information
-- Repository URL
-- Available installation packages
-- Installation instructions
-
-### `apm marketplace` - Plugin marketplace management
-
-Register, browse, and manage plugin marketplaces. Marketplaces are GitHub repositories containing a `marketplace.json` index of plugins.
-
-> See the [Marketplaces guide](../../guides/marketplaces/) for concepts and workflows.
-
-```bash
-apm marketplace COMMAND [OPTIONS]
-```
-
-#### `apm marketplace add` - Register a marketplace
-
-Register a GitHub repository as a plugin marketplace.
-
-```bash
-apm marketplace add OWNER/REPO [OPTIONS]
-apm marketplace add HOST/OWNER/REPO [OPTIONS]
-apm marketplace add HOST/group/sub/.../REPO [OPTIONS]
-apm marketplace add https://HOST/owner/.../repo[.git] [OPTIONS]
-```
-
-**Arguments:**
-- `OWNER/REPO` - GitHub repository containing `marketplace.json`
-- `HOST/OWNER/REPO` - Repository on a non-github.com host (e.g., GitHub Enterprise)
-- `HOST/group/sub/.../REPO` - Repository nested under sub-paths (e.g., GHES org/team/repo)
-- `https://HOST/owner/.../repo[.git]` - Full HTTPS URL pasted from the browser. The `.git` suffix is stripped.
-
-**Options:**
-- `-n, --name TEXT` - Custom display name for the marketplace
-- `-b, --branch TEXT` - Branch to track (default: main)
-- `--host TEXT` - Git host FQDN (default: github.com or `GITHUB_HOST` env var)
-- `-v, --verbose` - Show detailed output
-
-> **Supported hosts.** `apm marketplace add` currently fetches `marketplace.json` via the GitHub Contents API, so only `github.com`, GitHub Enterprise Cloud (`*.ghe.com`), and the host configured via `GITHUB_HOST` are accepted. GitLab, Bitbucket, and other generic Git hosts are rejected at registration time with an actionable error -- this prevents silent fetch failures and avoids forwarding GitHub credentials to unintended hosts. Native non-GitHub support is tracked separately.
-
-**Examples:**
-```bash
-# Register a marketplace
-apm marketplace add acme/plugin-marketplace
-
-# Register from a full HTTPS URL pasted from the browser
-apm marketplace add https://github.com/acme/plugin-marketplace
-
-# Register with a custom name and branch
-apm marketplace add acme/plugin-marketplace --name acme-plugins --branch release
-
-# Register from a GitHub Enterprise host (Cloud or Server)
-apm marketplace add acme/plugin-marketplace --host ghes.corp.example.com
-apm marketplace add ghes.corp.example.com/acme/plugin-marketplace
-
-# Register a repo nested under sub-paths on a GHES instance
-apm marketplace add ghes.corp.example.com/org/team/plugin-marketplace
-```
-
-#### `apm marketplace list` - List registered marketplaces
-
-List all registered marketplaces with their source repository and branch.
-
-```bash
-apm marketplace list [OPTIONS]
-```
-
-**Options:**
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-apm marketplace list
-```
-
-#### `apm marketplace browse` - Browse marketplace plugins
-
-List all plugins available in a registered marketplace.
-
-```bash
-apm marketplace browse NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Name of the registered marketplace
-
-**Options:**
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Browse all plugins in a marketplace
-apm marketplace browse acme-plugins
-```
-
-#### `apm marketplace update` - Refresh marketplace cache
-
-Refresh the cached `marketplace.json` for one or all registered marketplaces.
-
-```bash
-apm marketplace update [NAME] [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Optional marketplace name. Omit to refresh all.
-
-**Options:**
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Refresh a specific marketplace
-apm marketplace update acme-plugins
-
-# Refresh all marketplaces
-apm marketplace update
-```
-
-#### `apm marketplace remove` - Remove a registered marketplace
-
-Unregister a marketplace. Plugins previously installed from it remain pinned in `apm.lock.yaml`.
-
-```bash
-apm marketplace remove NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Name of the marketplace to remove
-
-**Options:**
-- `-y, --yes` - Skip confirmation prompt
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Remove with confirmation prompt
-apm marketplace remove acme-plugins
-
-# Remove without confirmation
-apm marketplace remove acme-plugins --yes
-```
-
-#### `apm marketplace validate` - Validate a marketplace manifest
-
-Validate `marketplace.json` for schema errors and duplicate plugin names.
-
-```bash
-apm marketplace validate NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Name of the marketplace to validate
-
-**Options:**
-- `--check-refs` - Verify version refs are reachable (network). *Not yet implemented.*
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Validate a marketplace
-apm marketplace validate acme-plugins
-
-# Verbose output
-apm marketplace validate acme-plugins --verbose
-```
-
-#### `apm marketplace init` - Add a marketplace block to apm.yml
-
-Add a `marketplace:` block to the project's `apm.yml`. If `apm.yml` is absent, a minimal one is scaffolded first. The block is richly commented and ready to be edited. Build the marketplace with [`apm pack`](#apm-pack---pack-distributable-artifacts). See the [Authoring a marketplace guide](../../guides/marketplace-authoring/).
-
-```bash
-apm marketplace init [OPTIONS]
-```
-
-**Options:**
-- `--force` - Overwrite an existing `marketplace:` block in `apm.yml`
-- `--no-gitignore-check` - Skip the `.gitignore` staleness check
-- `--name TEXT` - Marketplace/package name (defaults to `my-marketplace` when scaffolding apm.yml)
-- `--owner TEXT` - Owner name for the marketplace block
-- `-v, --verbose` - Show detailed output
-
-**Exit codes:**
-- `0` - Block written
-- `1` - Block already exists (without `--force`) or write failure
-
-**Examples:**
-```bash
-apm marketplace init
-apm marketplace init --force --owner acme-org
-```
-
-`apm init --marketplace` is the equivalent shortcut at project-creation time: it seeds a fresh `apm.yml` with the `marketplace:` block already in place.
-
-#### `apm marketplace migrate` - Fold marketplace.yml into apm.yml
-
-One-shot conversion of a legacy standalone `marketplace.yml` into the `marketplace:` block of `apm.yml`. Inheritable fields (`name`, `description`, `version`) are dropped from the block when they match `apm.yml`'s top-level values, and emitted as overrides when they differ. The legacy `marketplace.yml` is deleted on success.
-
-```bash
-apm marketplace migrate [OPTIONS]
-```
-
-**Options:**
-- `--force`, `--yes`, `-y` - Overwrite an existing `marketplace:` block in `apm.yml` (the three flags are aliases)
-- `--dry-run` - Print the proposed change without writing
-- `-v, --verbose` - Show detailed output
-
-**Exit codes:**
-- `0` - Migration applied (or dry run complete)
-- `1` - Migration failed (legacy file missing, conflict without `--force`, write failure)
-
-**Examples:**
-```bash
-apm marketplace migrate --dry-run
-apm marketplace migrate --yes
-```
-
-#### `apm marketplace outdated` - Report available upgrades
-
-List packages in the `marketplace:` block whose source repositories have newer tags available. Range-aware: distinguishes "latest in range" (picked up by next `build`) from "latest overall" (requires a manual range bump). Local-path packages and `ref:`-pinned entries show `--` in the range columns.
-
-```bash
-apm marketplace outdated [OPTIONS]
-```
-
-**Options:**
-- `--offline` - Use cached refs only
-- `--include-prerelease` - Include pre-release tags
-- `-v, --verbose` - Show detailed output
-
-**Exit codes:**
-- `0` - Report rendered (even if upgrades are available)
-- `1` - Unable to query refs
-- `2` - Schema error in the `marketplace:` block
-
-**Examples:**
-```bash
-apm marketplace outdated
-apm marketplace outdated --include-prerelease
-```
-
-#### `apm marketplace check` - Validate marketplace entries
-
-Validate the `marketplace:` schema and verify that every package entry is resolvable (ref exists, at least one tag satisfies the range). Intended for CI use before publishing.
-
-```bash
-apm marketplace check [OPTIONS]
-```
-
-**Options:**
-- `--offline` - Schema and cached-ref checks only (no network)
-- `-v, --verbose` - Show detailed output
-
-**Exit codes:**
-- `0` - All entries OK
-- `1` - One or more entries are unreachable or unresolvable
-- `2` - Schema error in the `marketplace:` block
-
-**Examples:**
-```bash
-apm marketplace check
-apm marketplace check --offline
-```
-
-#### `apm marketplace doctor` - Environment diagnostics
-
-Check git, network reachability, authentication, `gh` CLI availability, and the presence of a marketplace config (in `apm.yml` or legacy `marketplace.yml`). Run this first when `apm pack` or `publish` fails in an unfamiliar environment.
-
-```bash
-apm marketplace doctor [OPTIONS]
-```
-
-**Options:**
-- `-v, --verbose` - Per-check detail
-
-**Exit codes:**
-- `0` - All checks pass
-- `1` - One or more checks failed
-
-**Examples:**
-```bash
-apm marketplace doctor
-apm marketplace doctor --verbose
-```
-
-#### `apm marketplace publish` - Open PRs on consumer repositories
-
-Drive the compiled `marketplace.json` out to consumer repositories listed in a `consumer-targets.yml` file, opening a pull request on each. Requires an authenticated `gh` CLI unless `--no-pr` is used. Run `apm pack` first to (re)build `marketplace.json`. See the [Authoring a marketplace guide](../../guides/marketplace-authoring/#publishing-to-consumers) for the full workflow.
-
-```bash
-apm marketplace publish [OPTIONS]
-```
-
-**Options:**
-- `--targets PATH` - Path to the targets file (default: `./consumer-targets.yml`)
-- `--dry-run` - Preview without pushing or opening PRs
-- `--no-pr` - Push branches but skip PR creation
-- `--draft` - Create PRs as drafts
-- `--allow-downgrade` - Allow pushing a lower version than the target currently references
-- `--allow-ref-change` - Allow switching ref types (for example, branch to SHA)
-- `--parallel N` - Maximum concurrent target updates (default: `4`)
-- `-y, --yes` - Skip the confirmation prompt (required in non-interactive sessions)
-- `-v, --verbose` - Per-target detail
-
-**Exit codes:**
-- `0` - All targets succeeded (or were already up to date)
-- `1` - One or more targets failed, or prerequisites missing
-
-**Examples:**
-```bash
-# Preview the publish plan
-apm marketplace publish --dry-run --yes
-
-# Publish with PRs
-apm marketplace publish
-
-# Push branches only (no gh CLI needed)
-apm marketplace publish --no-pr
-```
-
-Run history and PR URLs are recorded in `.apm/publish-state.json` so re-runs can detect existing PRs.
-
-#### `apm marketplace package add` - Add a package entry
-
-Add a package entry to the `marketplace.packages` list in `apm.yml`.
-
-```bash
-apm marketplace package add SOURCE [OPTIONS]
-```
-
-**Arguments:**
-- `SOURCE` - GitHub `owner/repo` reference
-
-**Options:**
-- `--version TEXT` - Semver range constraint (e.g. `">=1.0.0"`)
-- `--ref TEXT` - Pin to a git ref (SHA, tag, or HEAD). Mutable refs are auto-resolved to SHA
-- `-d`, `--description TEXT` - Short description for the entry
-- `-s`, `--subdir TEXT` - Subdirectory inside source repo
-- `--include-prerelease` - Include pre-release versions
-- `--no-verify` - Skip remote repository verification
-- `--verbose` - Enable verbose output
-
-`--version` and `--ref` are mutually exclusive. When neither is provided, the current `HEAD` SHA is pinned automatically.
-
-**Examples:**
-```bash
-# Add a package with a version range
-apm marketplace package add acme/code-review --version ">=1.0.0"
-
-# Pin to a specific tag
-apm marketplace package add acme/code-review --ref v2.1.0
-
-# Pin to current HEAD (auto-resolved to SHA)
-apm marketplace package add acme/code-review
-
-# Add with description and skip verification (requires explicit --ref SHA)
-apm marketplace package add acme/code-review --ref abc123...40chars \
-  --description "Code review skill" --no-verify
-```
-
-#### `apm marketplace package set` - Update a package entry
-
-Update fields on an existing package entry in the `marketplace.packages` list of `apm.yml`.
-
-```bash
-apm marketplace package set NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Name of the existing package entry
-
-**Options:**
-- `--version TEXT` - New semver range constraint
-- `--ref TEXT` - New git ref (SHA, tag, or HEAD). Mutable refs are auto-resolved to SHA
-- `--description TEXT` - New description
-- `--include-prerelease` - Enable pre-release version inclusion
-- `--verbose` - Enable verbose output
-
-`--version` and `--ref` are mutually exclusive. At least one field option must be specified.
-
-**Examples:**
-```bash
-# Widen the version range
-apm marketplace package set code-review --version ">=2.0.0"
-
-# Switch from version to pinned ref
-apm marketplace package set code-review --ref abc1234
-
-# Re-pin to current HEAD SHA
-apm marketplace package set code-review --ref HEAD
-
-# Update the description
-apm marketplace package set code-review --description "Updated review skill"
-```
-
-#### `apm marketplace package remove` - Remove a package entry
-
-Remove a package entry from the `marketplace.packages` list in `apm.yml`.
-
-```bash
-apm marketplace package remove NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Name of the package entry to remove
-
-**Options:**
-- `--yes` - Skip confirmation prompt
-- `--verbose` - Enable verbose output
-
-Prompts for confirmation unless `--yes` is passed. In non-interactive environments (CI), use `--yes`.
-
-**Examples:**
-```bash
-# Remove with confirmation prompt
-apm marketplace package remove code-review
-
-# Skip confirmation (CI-friendly)
-apm marketplace package remove code-review --yes
-```
-
-### `apm search` - Search plugins in a marketplace
-
-Search for plugins by name or description within a specific marketplace.
-
-```bash
-apm search QUERY@MARKETPLACE [OPTIONS]
-```
-
-**Arguments:**
-- `QUERY@MARKETPLACE` - Search term scoped to a marketplace (e.g., `security@skills`)
-
-**Options:**
-- `--limit INTEGER` - Maximum results to return (default: 20)
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Search for code review plugins in a marketplace
-apm search "code review@skills"
-
-# Limit results
-apm search "linting@awesome-copilot" --limit 5
-```
-
-### `apm run` (Experimental) - Execute prompts
-
-Execute a script defined in your apm.yml with parameters and real-time output streaming.
-
-> See the [Agent Workflows guide](../../guides/agent-workflows/) for usage details.
-
-```bash
-apm run [SCRIPT_NAME] [OPTIONS]
-```
-
-**Arguments:**
-- `SCRIPT_NAME` - Name of script to run from apm.yml scripts section
-
-**Options:**
-- `-p, --param TEXT` - Parameter in format `name=value` (can be used multiple times)
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Run start script (default script)
-apm run start --param name="<YourGitHubHandle>"
-
-# Run with different scripts 
-apm run start --param name="Alice"
-apm run llm --param service=api
-apm run debug --param service=api
-
-# Run specific scripts with parameters
-apm run llm --param service=api --param environment=prod
-```
-
-**Return Codes:**
-- `0` - Success
-- `1` - Execution failed or error occurred
-
-### `apm preview` - Preview compiled scripts
-
-Show the processed prompt content with parameters substituted, without executing.
-
-```bash
-apm preview [SCRIPT_NAME] [OPTIONS]
-```
-
-**Arguments:**
-- `SCRIPT_NAME` - Name of script to preview from apm.yml scripts section
-
-**Options:**
-- `-p, --param TEXT` - Parameter in format `name=value`
-- `-v, --verbose` - Show detailed output
-
-**Examples:**
-```bash
-# Preview start script
-apm preview start --param name="<YourGitHubHandle>"
-
-# Preview specific script with parameters
-apm preview llm --param name="Alice"
-```
-
-### `apm list` - List available scripts
-
-Display all scripts defined in apm.yml.
-
-```bash
-apm list
-```
-
-**Examples:**
-```bash
-# List all prompts in project
-apm list
-```
-
-**Output format:**
-```
-Available scripts:
-  start: codex hello-world.prompt.md
-  llm: llm hello-world.prompt.md -m github/gpt-4o-mini  
-  debug: RUST_LOG=debug codex hello-world.prompt.md
-```
-
-### `apm compile` - Compile APM context into distributed AGENTS.md files
-
-Compile APM context files (chatmodes, instructions, contexts) into distributed AGENTS.md files with conditional sections, markdown link resolution, and project setup auto-detection.
-
-```bash
-apm compile [OPTIONS]
-```
-
-**Options:**
-- `-o, --output TEXT` - Output file path (for single-file mode)
-- `-t, --target [copilot|claude|cursor|codex|opencode|gemini|windsurf|agent-skills|all]` - Target agent format. Highest-priority entry in the resolution chain (`--target` > `apm.yml` `targets:` > auto-detect). Accepts comma-separated values for multiple targets (e.g., `-t claude,copilot`). `vscode` and `agents` are accepted as deprecated aliases for `copilot` (removal in v1.0). `agent-skills` is a no-op for compile (skills-only target). Auto-detects if not specified. Run [`apm targets`](#apm-targets---show-resolved-deployment-targets) to preview what auto-detect resolves to.
-- `--all` - Compile for all canonical targets. Equivalent to `--target all` but does not need to be combined with target-name parsing. Mutually exclusive with `--target`. Prefer `--all` over `--target all`; `--target all` is deprecated and emits a one-line warning.
-- `--chatmode TEXT` - Chatmode to prepend to the AGENTS.md file
-- `--dry-run` - Preview compilation without writing files (shows placement decisions)
-- `--no-links` - Skip markdown link resolution
-- `--with-constitution/--no-constitution` - Include Spec Kit `memory/constitution.md` verbatim at top inside a delimited block (default: `--with-constitution`). When disabled, any existing block is preserved but not regenerated.
-- `--watch` - Auto-regenerate on changes (file system monitoring)
-- `--validate` - Validate primitives without compiling
-- `--single-agents` - Force single-file compilation (legacy mode)
-- `-v, --verbose` - Show detailed source attribution and optimizer analysis
-- `--local-only` - Ignore dependencies, compile only local primitives
-- `--clean` - Remove orphaned AGENTS.md files that are no longer generated
-
-**Target Auto-Detection:**
-
-When `--target` is not specified, APM auto-detects based on existing project structure:
-
-| Condition | Target | Output |
-|-----------|--------|--------|
-| `.github/` exists only | `vscode` | AGENTS.md + .github/ |
-| `.claude/` exists only | `claude` | CLAUDE.md + .claude/ |
-| `.codex/` exists | `codex` | AGENTS.md + .codex/ + .agents/ |
-| `.gemini/` exists | `gemini` | GEMINI.md + .gemini/ |
-| `.windsurf/` exists | `windsurf` | AGENTS.md + .windsurf/ |
-| Both folders exist | `all` | All outputs |
-| Neither folder exists | `minimal` | AGENTS.md only |
-
-You can also set a persistent target in `apm.yml`:
-```yaml
-name: my-project
-version: 1.0.0
-target: vscode  # single target
-```
-
-```yaml
-name: my-project
-version: 1.0.0
-target: [claude, copilot]  # multiple targets -- only these are compiled/installed
-```
-
-**Target Formats (explicit):**
-
-| Target | Output Files | Best For |
-|--------|--------------|----------|
-| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor |
-| `claude` | CLAUDE.md, .claude/commands/, SKILL.md | Claude Code, Claude Desktop |
-| `codex` | AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks.json | Codex CLI |
-| `opencode` | AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/ | OpenCode |
-| `gemini` | GEMINI.md, .gemini/commands/, .gemini/skills/ | Gemini CLI |
-| `windsurf` | AGENTS.md, .windsurf/rules/, .windsurf/skills/, .windsurf/workflows/ | Windsurf/Cascade |
-| `agent-skills` | .agents/skills/ only | Cross-client shared skills |
-| `agents` | *(deprecated)* alias for `vscode` | Use `copilot` or `agent-skills` instead |
-| `all` | All of the above (excludes `agent-skills`) | Universal compatibility |
-
-**Examples:**
-```bash
-# Basic compilation with auto-detected context
-apm compile
-
-# Generate with specific chatmode
-apm compile --chatmode architect
-
-# Preview without writing file
-apm compile --dry-run
-
-# Custom output file
-apm compile --output docs/AI-CONTEXT.md
-
-# Validate context without generating output
-apm compile --validate
-
-# Watch for changes and auto-recompile (development mode)
-apm compile --watch
-
-# Watch mode with dry-run for testing
-apm compile --watch --dry-run
-
-# Target specific agent formats
-apm compile --target vscode    # AGENTS.md + .github/ (incl. copilot-instructions.md)
-apm compile --target claude    # CLAUDE.md + .claude/ only
-apm compile --target opencode  # AGENTS.md + .opencode/ only
-apm compile --all              # All canonical targets (preferred over --target all)
-
-# Multiple targets (comma-separated)
-apm compile -t claude,copilot  # CLAUDE.md + AGENTS.md + .github/copilot-instructions.md
-
-# Compile injecting Spec Kit constitution (auto-detected)
-apm compile --with-constitution
-
-# Recompile WITHOUT updating the block but preserving previous injection
-apm compile --no-constitution
-```
-
-**Watch Mode:**
-- Monitors `.apm/`, `.github/instructions/`, `.github/chatmodes/` directories
-- Auto-recompiles when `.md` or `apm.yml` files change
-- Includes 1-second debounce to prevent rapid recompilation
-- Press Ctrl+C to stop watching
-- Requires `watchdog` library (automatically installed)
-
-**Validation Mode:**
-- Checks primitive structure and frontmatter completeness
-- Displays actionable suggestions for fixing validation errors
-- Exits with error code 1 if validation fails
-- No output file generation in validation-only mode
-
-**Content Scanning:**
-Compiled output is scanned for hidden Unicode characters before writing to disk. Critical findings cause `apm compile` to exit with code 1 — defense-in-depth since source files are already scanned during `apm install`.
-
-**`.github/copilot-instructions.md` generation:**
-When the resolved target is `copilot` (alias `vscode`), `all`, or any multi-target list containing `copilot`, `apm compile` assembles all *global* instructions (entries in `.apm/instructions/` without an `apply_to` field) into `.github/copilot-instructions.md` -- the file VS Code and GitHub Copilot read automatically with zero user configuration. Generated content is wrapped with an APM-only marker (literal first line: `<!-- Generated by APM CLI from .apm/ primitives -->`). Switching to a non-Copilot target (e.g. `apm compile -t claude`) cleans up the file only when the marker is present; a hand-authored `.github/copilot-instructions.md` is left untouched on both write and cleanup paths. To adopt APM management of an existing hand-authored file, delete (or rename) it and re-run `apm compile`, or prepend the marker line `<!-- Generated by APM CLI from .apm/ primitives -->` to the top of the file and re-run `apm compile`.
-
-**Configuration Integration:**
-The compile command supports configuration via `apm.yml`:
-
-```yaml
-compilation:
-  output: "AGENTS.md"           # Default output file
-  chatmode: "backend-engineer"  # Default chatmode to use
-  resolve_links: true           # Enable markdown link resolution
-  exclude:                      # Directory exclusion patterns (glob syntax)
-    - "apm_modules/**"          # Exclude installed packages
-    - "tmp/**"                  # Exclude temporary files
-    - "coverage/**"             # Exclude test coverage
-    - "**/test-fixtures/**"     # Exclude test fixtures at any depth
-```
-
-**Directory Exclusion Patterns:**
-
-Use the `exclude` field to skip directories during compilation. This improves performance in large monorepos and prevents duplicate instruction discovery from source package development directories.
-
-**Pattern examples:**
-- `tmp` - Matches directory named "tmp" at any depth
-- `projects/packages/apm` - Matches specific nested path
-- `**/node_modules` - Matches "node_modules" at any depth
-- `coverage/**` - Matches "coverage" and all subdirectories
-- `projects/**/apm/**` - Complex nested matching with `**`
-
-**Default exclusions** (always applied, matched on exact path components):
-- `node_modules`, `__pycache__`, `.git`, `dist`, `build`, `apm_modules`
-- Hidden directories (starting with `.`)
-
-Command-line options always override `apm.yml` settings. Priority order:
-1. Command-line flags (highest priority)
-2. `apm.yml` compilation section
-3. Built-in defaults (lowest priority)
-
-**Generated AGENTS.md structure:**
-- **Header** - Generation metadata and APM version
-- **(Optional) Spec Kit Constitution Block** - Delimited block:
-  - Markers: `<!-- SPEC-KIT CONSTITUTION: BEGIN -->` / `<!-- SPEC-KIT CONSTITUTION: END -->`
-  - Second line includes `hash: <sha256_12>` for drift detection
-  - Entire raw file content in between (Phase 0: no summarization)
-- **(Optional) Global Instructions Section** - Instructions without an `applyTo` pattern are emitted under a single `## Global Instructions` heading (applies to every file)
-- **Pattern-based Sections** - Content grouped by exact `applyTo` patterns from instruction context files (e.g., "Files matching `**/*.py`")
-- **Footer** - Regeneration instructions
-
-The structure is entirely dictated by the instruction context found in `.apm/` and `.github/instructions/` directories. No predefined sections or project detection are applied.
-
-**Primitive Discovery:**
-- **Chatmodes**: `.chatmode.md` files in `.apm/chatmodes/`, `.github/chatmodes/`
-- **Instructions**: `.instructions.md` files in `.apm/instructions/`, `.github/instructions/`
-- **Workflows**: `.prompt.md` files in project and `.github/prompts/`
-
-APM integrates seamlessly with [Spec-kit](https://github.com/github/spec-kit) for specification-driven development, automatically injecting Spec-kit `constitution` into the compiled context layer.
-
-### `apm config` - Configure APM CLI
-
-Manage APM CLI configuration settings. Running `apm config` without subcommands displays the current configuration.
-
-```bash
-apm config [COMMAND]
-```
-
-#### `apm config` - Show current configuration (default behavior)
-
-Display current APM CLI configuration and project settings.
-
-```bash
-apm config
-```
-
-**What's displayed:**
-- Project configuration from `apm.yml` (if in an APM project)
-  - Project name, version, entrypoint
-  - Number of MCP dependencies
-  - Compilation settings (output, chatmode, resolve_links)
-- Global configuration
-  - APM CLI version
-  - `auto-integrate` setting
-  - `temp-dir` setting (when configured)
-
-**Examples:**
-```bash
-# Show current configuration
-apm config
-```
-
-#### `apm config get` - Get a configuration value
-
-Get a specific configuration value or display all configuration values.
-
-```bash
-apm config get [KEY]
-```
-
-**Arguments:**
-- `KEY` (optional) - Configuration key to retrieve. Supported keys:
-  - `auto-integrate` - Whether to automatically integrate `.prompt.md` files into AGENTS.md
-  - `temp-dir` - Custom temporary directory for clone/download operations
-  - `copilot-cowork-skills-dir` - Override the resolved Cowork OneDrive skills directory
-
-If `KEY` is omitted, displays all configuration values.
-
-**Examples:**
-```bash
-# Get auto-integrate setting
-apm config get auto-integrate
-
-# Show all configuration
-apm config get
-```
-
-#### `apm config set` - Set a configuration value
-
-Set a configuration value globally for APM CLI.
-
-```bash
-apm config set KEY VALUE
-```
-
-**Arguments:**
-- `KEY` - Configuration key to set. Supported keys:
-  - `auto-integrate` - Enable/disable automatic integration of `.prompt.md` files
-  - `temp-dir` - Set a custom temporary directory path
-  - `copilot-cowork-skills-dir` - Override the resolved Cowork OneDrive skills directory
-- `VALUE` - Value to set. For boolean keys, use: `true`, `false`, `yes`, `no`, `1`, `0`
-
-**Configuration Keys:**
-
-**`auto-integrate`** - Control automatic prompt integration
-- **Type:** Boolean
-- **Default:** `true`
-- **Description:** When enabled, APM automatically discovers and integrates `.prompt.md` files from `.github/prompts/` and `.apm/prompts/` directories into the compiled AGENTS.md file. This ensures all prompts are available to coding agents without manual compilation.
-- **Use Cases:**
-  - Set to `false` if you want to manually manage which prompts are compiled
-  - Set to `true` to ensure all prompts are always included in the context
-
-**Examples:**
-```bash
-# Enable auto-integration (default)
-apm config set auto-integrate true
-
-# Disable auto-integration
-apm config set auto-integrate false
-```
-
-**`temp-dir`** - Override the system temporary directory
-- **Type:** String (directory path)
-- **Default:** System temp directory (not stored)
-- **Description:** Set a custom temporary directory for clone and download operations. Useful in corporate Windows environments where endpoint security software restricts access to `%TEMP%`, causing `[WinError 5] Access is denied`.
-- **Resolution order:** `APM_TEMP_DIR` environment variable > `temp_dir` in `~/.apm/config.json` > system default.
-- **Use Cases:**
-  - Set when the default system temp directory is restricted or unavailable
-  - Use the `APM_TEMP_DIR` environment variable for CI pipelines or per-session overrides
-
-**Examples:**
-```bash
-# Set a custom temp directory (Windows)
-apm config set temp-dir C:\apm-temp
-
-# Set a custom temp directory (macOS/Linux)
-apm config set temp-dir /tmp/apm-work
-
-# Check the current temp-dir setting
-apm config get temp-dir
-
-# Or use the environment variable instead
-export APM_TEMP_DIR=/tmp/apm-work
-```
-
-**`copilot-cowork-skills-dir`** - Override the resolved Cowork OneDrive skills directory
-- **Type:** String (absolute directory path)
-- **Default:** Auto-detected Cowork skills directory (not stored)
-- **Description:** Override the resolved Cowork OneDrive skills directory. Gated on the `copilot-cowork` experimental flag for `set`; `get` and `unset` are always available for cleanup.
-- **Resolution order:** `APM_COPILOT_COWORK_SKILLS_DIR` environment variable > `copilot_cowork_skills_dir` in `~/.apm/config.json` > platform auto-detection.
-- **Use Cases:**
-  - Set a specific OneDrive-backed Cowork skills directory instead of relying on auto-detection
-  - Clear the override with `apm config unset copilot-cowork-skills-dir` when returning to auto-detection
-
-**Examples:**
-```bash
-# Enable the experimental flag, then set an explicit Cowork skills directory
-apm experimental enable copilot-cowork
-apm config set copilot-cowork-skills-dir ~/Library/CloudStorage/OneDrive-Contoso/Documents/Cowork/skills
-
-# Check the current copilot-cowork-skills-dir setting
-apm config get copilot-cowork-skills-dir
-
-# Remove the override and return to auto-detection
-apm config unset copilot-cowork-skills-dir
-```
-
-See also: [Cowork integration](../integrations/copilot-cowork/).
-
-## Runtime Management (Experimental)
-
-### `apm runtime` (Experimental) - Manage AI runtimes
-
-APM manages AI runtime installation and configuration automatically. Currently supports four runtimes: `copilot`, `codex`, `llm`, and `gemini`.
-
-> See the [Agent Workflows guide](../../guides/agent-workflows/) for usage details.
-
-```bash
-apm runtime COMMAND [OPTIONS]
-```
-
-**Supported Runtimes:**
-- **`copilot`** - GitHub Copilot coding agent
-- **`codex`** - OpenAI Codex CLI with GitHub Models support
-- **`llm`** - Simon Willison's LLM library with multiple providers
-- **`gemini`** - Google Gemini CLI
-
-#### `apm runtime setup` - Install AI runtime
-
-Download and configure an AI runtime from official sources.
-
-```bash
-apm runtime setup [OPTIONS] {copilot|codex|llm|gemini}
-```
-
-**Arguments:**
-- `{copilot|codex|llm|gemini}` - Runtime to install
-
-**Options:**
-- `--version TEXT` - Specific version to install
-- `--vanilla` - Install runtime without APM configuration (uses runtime's native defaults)
-
-**Examples:**
-```bash
-# Install Codex with APM defaults
-apm runtime setup codex
-
-# Install LLM with APM defaults  
-apm runtime setup llm
-```
-
-**Windows support:**
-- On Windows, APM runs the setup scripts through PowerShell automatically
-- No special flags are required
-- Platform detection is automatic
-
-**Default Behavior:**
-- Installs runtime binary from official sources
-- Configures with GitHub Models (free) as APM default
-- Creates Codex runtime configuration (global `~/.codex/config.toml`; project MCP config is managed separately in `.codex/config.toml`)
-- Provides clear logging about what's being configured
-
-**Vanilla Behavior (`--vanilla` flag):**
-- Installs runtime binary only
-- No APM-specific configuration applied
-- Uses runtime's native defaults (e.g., OpenAI for Codex)
-- No configuration files created by APM
-
-#### `apm runtime list` - Show installed runtimes
-
-List all available runtimes and their installation status.
-
-```bash
-apm runtime list
-```
-
-**Output includes:**
-- Runtime name and description
-- Installation status ([+] Installed / [x] Not installed)
-- Installation path and version
-- Configuration details
-
-#### `apm runtime remove` - Uninstall runtime
-
-Remove an installed runtime and its configuration.
-
-```bash
-apm runtime remove [OPTIONS] {copilot|codex|llm|gemini}
-```
-
-**Arguments:**
-- `{copilot|codex|llm|gemini}` - Runtime to remove
-
-**Options:**
-- `-y, --yes` - Confirm the action without prompting
-
-#### `apm runtime status` - Show active runtime and preference order
-
-Display which runtime APM will use for execution and runtime preference order.
-
-```bash
-apm runtime status
-```
-
-**Output includes:**
-- Runtime preference order (copilot → codex → gemini → llm)
-- Currently active runtime
-- Next steps if no runtime is available
-
-## Experimental Features
-
-### `apm experimental` - Manage experimental feature flags
-
-Manage opt-in flags that gate new or changing behaviour. Running `apm experimental` with no subcommand lists the available flags.
-
-```bash
-apm experimental [OPTIONS] COMMAND [ARGS]...
-```
-
-**Options:**
-- `-v, --verbose` - Show verbose output
-
-**Subcommands:**
-
-| Command | Description |
-|---------|-------------|
-| `list` | List all experimental features |
-| `enable NAME` | Enable an experimental feature |
-| `disable NAME` | Disable an experimental feature |
-| `reset [NAME]` | Reset one feature, or all features, to defaults |
-
-#### `apm experimental list`
-
-```bash
-apm experimental list [OPTIONS]
-```
-
-**Options:**
-- `--enabled` - Show only enabled features
-- `--disabled` - Show only disabled features
-- `--json` - Output as a JSON array
-- `-v, --verbose` - Show detailed output
-
-#### `apm experimental enable`
-
-```bash
-apm experimental enable NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Experimental feature name
-
-**Options:**
-- `-v, --verbose` - Show verbose output
-
-#### `apm experimental disable`
-
-```bash
-apm experimental disable NAME [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Experimental feature name
-
-**Options:**
-- `-v, --verbose` - Show verbose output
-
-#### `apm experimental reset`
-
-```bash
-apm experimental reset [NAME] [OPTIONS]
-```
-
-**Arguments:**
-- `NAME` - Optional experimental feature name. Omit to reset all feature overrides.
-
-**Options:**
-- `-y, --yes` - Skip the confirmation prompt when resetting all features
-- `-v, --verbose` - Show verbose output
-
-See the full reference in [Experimental Flags](../experimental/).
diff --git a/docs/src/content/docs/reference/cli/audit.md b/docs/src/content/docs/reference/cli/audit.md
new file mode 100644
index 000000000..b86dd672f
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/audit.md
@@ -0,0 +1,168 @@
+---
+title: apm audit
+description: Scan installed primitives for hidden Unicode, drift, and lockfile/policy violations.
+sidebar:
+  order: 14
+---
+
+## Synopsis
+
+```bash
+apm audit [PACKAGE] [OPTIONS]
+```
+
+## Description
+
+`apm audit` is the explicit security and integrity tool. It runs in two modes:
+
+- **Content scan mode** (default). Scans deployed prompt, instruction, skill, and rules files for hidden Unicode that can embed invisible instructions in agent context, and replays the install pipeline into a scratch tree to detect drift (hand-edits to deployed files, missing integrations, orphaned files vs the lockfile). Can also remediate findings with `--strip` or scan an arbitrary file with `--file`.
+- **CI gate mode** (`--ci`). Runs lockfile consistency checks plus drift in machine-readable form (text, JSON, or SARIF) suitable for branch-protection gates. Auto-discovers org policy from your project's git remote unless `--no-policy` is set.
+
+This is the explicit power tool. Built-in protection against critical Unicode findings already runs automatically in `apm install`, `apm compile`, and `apm unpack`; you do not need to call `apm audit` to be safe by default. See [Drift and secure by default](../../../consumer/drift-and-secure-by-default/) for the consumer-side overview and [Enforce in CI](../../../enterprise/enforce-in-ci/) for the gating workflow.
+
+`PACKAGE`, when supplied, is the lockfile package key (the repo URL) of a single installed dependency to scan. Omit it to scan every installed package plus local `.apm/` content.
+
+## Options
+
+### Content scan
+
+| Flag | Default | Description |
+|---|---|---|
+| `--file PATH` | unset | Scan an arbitrary file instead of installed packages. Bypasses drift detection. |
+| `--strip` | off | Remove critical and warning severity characters in place. Preserves emoji and ZWJ inside emoji sequences. |
+| `--dry-run` | off | Preview what `--strip` would remove without modifying files. |
+| `--no-drift` | off | Skip the install-replay drift check (reduces coverage). Mutually exclusive with `--strip` and `--file`. |
+| `--verbose`, `-v` | off | Show info-level findings and per-file detail. No effect in `--ci` mode. |
+
+### Output
+
+| Flag | Default | Description |
+|---|---|---|
+| `--format`, `-f text\|json\|sarif\|markdown` | `text` | Output format. `sarif` targets GitHub Code Scanning. `markdown` is for GitHub step summaries and is not allowed with `--ci`. |
+| `--output`, `-o PATH` | stdout | Write the report to a file. Format is auto-detected from extension (`.sarif`, `.sarif.json`, `.json`, `.md`) when `--format` is omitted. |
+
+### CI gate
+
+| Flag | Default | Description |
+|---|---|---|
+| `--ci` | off | Run lockfile consistency checks and drift as a CI gate. Cannot be combined with `--strip`, `--dry-run`, `--file`, or `PACKAGE`. |
+| `--policy SOURCE` | auto | Policy source for `--ci`. Accepts `org` (auto-discover from the project's git remote), `owner/repo`, an `https://` URL, or a local file path. Experimental. Without `--ci` it is ignored with a warning. |
+| `--no-policy` | off | Skip policy discovery and enforcement. Equivalent to `APM_POLICY_DISABLE=1`. Overridden when `--policy` is passed explicitly. |
+| `--no-cache` | off | Force a fresh policy fetch (skip the policy cache). Only relevant with policy discovery active. |
+| `--no-fail-fast` | off | Run every check even after the first failure, for a full diagnostic report. |
+
+## Examples
+
+### Default audit (content scan plus drift)
+
+```bash
+apm audit
+```
+
+### Scan a specific installed package
+
+```bash
+apm audit https://github.com/owner/repo
+```
+
+### Scan an arbitrary file outside APM
+
+```bash
+apm audit --file .cursorrules
+```
+
+### Remediate findings
+
+```bash
+# Preview what --strip would remove
+apm audit --strip --dry-run
+
+# Strip critical and warning severity characters in place
+apm audit --strip
+```
+
+### Reports
+
+```bash
+# SARIF to stdout (for GitHub Code Scanning upload)
+apm audit -f sarif
+
+# JSON to a file
+apm audit -f json -o results.json
+
+# Markdown for a GitHub Actions step summary
+apm audit -f markdown -o "$GITHUB_STEP_SUMMARY"
+
+# Auto-detect format from extension
+apm audit -o report.sarif
+```
+
+### CI gate
+
+```bash
+# Default CI gate (auto-discovers org policy)
+apm audit --ci
+
+# CI gate, baseline checks only (no policy)
+apm audit --ci --no-policy
+
+# CI gate with an explicit policy source
+apm audit --ci --policy org
+apm audit --ci --policy ./apm-policy.yml
+
+# Full diagnostic report (don't stop at first failure)
+apm audit --ci --no-fail-fast
+
+# CI gate as JSON or SARIF
+apm audit --ci -f json
+apm audit --ci -f sarif -o audit.sarif
+```
+
+For the full workflow, see [Enforce in CI](../../../enterprise/enforce-in-ci/).
+
+## Behavior
+
+### Severity levels (content scan)
+
+| Severity | Examples | Effect |
+|---|---|---|
+| Critical | Tag characters (U+E0001-E007F), bidi overrides (U+202A-E, U+2066-9), variation selectors 17-256 (U+E0100-E01EF, the Glassworm vector) | Exit `1`. Removed by `--strip`. Blocks `apm install` / `apm compile` / `apm unpack` by default. |
+| Warning | Zero-width spaces and joiners (U+200B-D), variation selectors 1-15 (U+FE00-FE0E), bidi marks (U+200E-F, U+061C), invisible operators (U+2061-4), annotation markers (U+FFF9-B), deprecated formatting (U+206A-F), soft hyphen (U+00AD), mid-file BOM | Exit `2` if no critical findings. Removed by `--strip`. |
+| Info | Non-breaking and unusual whitespace, emoji presentation selector (U+FE0F), ZWJ between emoji characters | Exit `0`. Shown only with `--verbose`. Preserved by `--strip`. |
+
+### Drift detection
+
+The default audit replays the install pipeline into a scratch tree and diffs the result against the working tree. It catches hand-edits to deployed files, missing integrations from a skipped `apm install`, and orphaned files. Drift is whole-project only; `--file` and explicit `PACKAGE` runs skip it. Use `--no-drift` to opt out (not recommended outside performance-constrained CI loops).
+
+### CI checks (`--ci`)
+
+`--ci` runs the baseline lockfile consistency checks defined in `src/apm_cli/policy/ci_checks.py`: lockfile presence, ref consistency, deployed-files presence, no orphaned packages, skill-subset consistency, MCP config consistency, content integrity (Unicode plus per-file SHA-256 hash drift on every deployed file, including local `.apm/` content via the synthesized self-entry), and an advisory `includes` consent check. Drift detection runs alongside and contributes to the exit code unless `--no-drift` is set. With policy discovery active, declared policy rules are evaluated against the resolved manifest.
+
+### Mutual exclusions
+
+- `--no-drift` cannot be combined with `--strip` or `--file`.
+- `--ci` cannot be combined with `--strip`, `--dry-run`, `--file`, or `PACKAGE`.
+- `--ci` does not support `--format markdown`.
+
+## Exit codes
+
+### Content scan mode
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean, info-only findings, drift-only (advisory) in bare audit, or successful `--strip`. |
+| `1` | Critical findings detected. |
+| `2` | Warning-only findings, or usage error (mutually exclusive flags). |
+
+### CI gate mode (`--ci`)
+
+| Code | Meaning |
+|---|---|
+| `0` | All checks passed. |
+| `1` | One or more checks failed (including drift, hash drift, or policy violations). |
+
+## Related
+
+- [`apm install`](../install/) -- the built-in scan that blocks critical findings before deployment.
+- [Drift and secure by default](../../../consumer/drift-and-secure-by-default/) -- consumer-side overview of the two-layer security model.
+- [Enforce in CI](../../../enterprise/enforce-in-ci/) -- wiring `apm audit --ci` into branch protection.
diff --git a/docs/src/content/docs/reference/cli/cache.md b/docs/src/content/docs/reference/cli/cache.md
new file mode 100644
index 000000000..82b377dc8
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/cache.md
@@ -0,0 +1,142 @@
+---
+title: apm cache
+description: Inspect and manage the local APM package cache
+sidebar:
+  order: 9
+---
+
+Inspect and maintain the local cache APM uses to avoid redundant
+network I/O during `apm install`.
+
+## Synopsis
+
+```bash
+apm cache info
+apm cache clean [--force | --yes]
+apm cache prune [--days N]
+```
+
+## Description
+
+`apm cache` groups three subcommands that operate on the local cache
+root. The cache holds two independent stores:
+
+- **Git cache** -- bare repository databases plus per-SHA worktree
+  checkouts, keyed by resolved commit.
+- **HTTP cache** -- conditional-GET responses for the GitHub release
+  and API endpoints APM polls during install.
+
+The cache is purely a performance optimization. Removing it never
+breaks correctness; the next `apm install` re-fetches whatever it
+needs.
+
+## Subcommands
+
+### `apm cache info`
+
+Show the resolved cache root, per-store entry counts, and a size
+breakdown.
+
+```bash
+apm cache info
+```
+
+Output:
+
+```
+[i] Cache root: /Users/you/Library/Caches/apm
+  Git repositories (db):    12
+  Git checkouts:            34
+  HTTP cache entries:       87
+
+  Total size:               142.3 MB
+    Git:                    138.1 MB
+    HTTP:                   4.2 MB
+```
+
+### `apm cache clean`
+
+Remove every entry from both the git and HTTP caches. Prompts for
+confirmation unless a skip flag is passed.
+
+```bash
+apm cache clean              # interactive prompt
+apm cache clean --force      # non-interactive
+apm cache clean --yes        # alias for --force
+```
+
+| Flag | Description |
+|---|---|
+| `--force`, `-f` | Skip the confirmation prompt. |
+| `--yes`, `-y` | Alias for `--force`. Use in CI scripts so the command never blocks on stdin. |
+
+:::caution
+`clean` removes every cached commit and every cached HTTP response.
+The next `apm install` will re-fetch everything from the network.
+Use `prune` when you only want to reclaim space from stale entries.
+:::
+
+### `apm cache prune`
+
+Remove git-cache checkouts whose filesystem `mtime` is older than
+`--days N`. Defaults to 30 days. The HTTP cache is not touched.
+
+```bash
+apm cache prune              # default: older than 30 days
+apm cache prune --days 7     # tighter window
+```
+
+| Flag | Description |
+|---|---|
+| `--days N` | Remove entries not accessed within this many days. Default: `30`. |
+
+:::caution[Lockfile-blind]
+`prune` does not consult any project's `apm.lock.yaml` before
+evicting entries. A pinned commit SHA referenced by your lockfile may
+be pruned if nothing has touched its checkout recently; the next
+`apm install` will re-clone it from the remote. Safe, but can
+surprise air-gapped or rate-limited environments.
+:::
+
+## Cache layout
+
+The cache root resolves in this precedence order (first match wins):
+
+1. `APM_NO_CACHE=1` -- per-invocation temp directory, cleaned at exit.
+2. `APM_CACHE_DIR=/path` -- explicit override.
+3. Platform default:
+   - **macOS:** `~/Library/Caches/apm/`
+   - **Linux:** `${XDG_CACHE_HOME:-~/.cache}/apm/`
+   - **Windows:** `%LOCALAPPDATA%\apm\Cache\`
+
+Inside the cache root:
+
+```
+<cache-root>/
+  git/
+    db_v1/           # bare repository databases
+    checkouts_v1/    # per-SHA worktree checkouts
+  http_v1/           # conditional-GET response cache
+```
+
+The cache root is created with mode `0700` and validated to be
+absolute with no NUL bytes before use.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `APM_CACHE_DIR` | Override the cache root. Must be an absolute path. |
+| `APM_NO_CACHE` | When set to `1`, `true`, or `yes`, route all cache I/O to a temp directory cleaned at process exit. |
+| `XDG_CACHE_HOME` | Honored on Linux and (when explicitly set) macOS. |
+
+## Coming from npm?
+
+`apm cache clean` mirrors `npm cache clean`: it nukes the local cache
+and forces re-download on next install. There is no `--dry-run` and
+no per-package targeting; cleaning is all-or-nothing.
+
+## Related
+
+- [`apm install`](../install/) -- populates the cache during dependency resolution.
+- [Lockfile spec](../../lockfile-spec/) -- what gets pinned and re-fetched.
diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md
new file mode 100644
index 000000000..a037f1145
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/compile.md
@@ -0,0 +1,220 @@
+---
+title: apm compile
+description: Compile primitives into per-target deployment files
+sidebar:
+  order: 11
+---
+
+Compile your **instructions** primitives into the AGENTS.md / CLAUDE.md
+/ GEMINI.md root context files (and per-harness rules trees) that each
+agent harness reads at startup.
+
+## Synopsis
+
+```bash
+apm compile [OPTIONS]
+```
+
+## Description
+
+`apm compile` reads `instructions/*.instructions.md` from `.apm/`
+(your project) and `apm_modules/` (installed dependencies), then
+writes one set of root context files plus per-harness rules per
+resolved target.
+
+Compile only handles **instructions** (and optionally a single
+chatmode to prepend via `--chatmode`). Other primitive types --
+prompts, skills, agents, hooks, commands, MCP -- are deployed by
+`apm install` directly into the harness directories that consume them
+and are not touched by `apm compile`. See
+[Primitives and targets](../../../concepts/primitives-and-targets/)
+for the full reach map.
+
+**When you actually need it:** compile is **optional for the
+`copilot` target** -- GitHub Copilot natively reads
+`.github/instructions/*.instructions.md` (with their `applyTo:`
+frontmatter) that `apm install` already deploys. Compile is
+**recommended for every other target** (`claude`, `cursor`, `codex`,
+`gemini`, `opencode`, `windsurf`), which load instructions through a
+root context file or harness-specific rules folder that compile
+generates.
+
+Resolution order for which targets to compile:
+
+1. `--target` / `--all` on the command line
+2. `targets:` field in `apm.yml`
+3. Auto-detection from existing folders (`.github/`, `.claude/`,
+   `.codex/`, `.gemini/`, `.windsurf/`)
+
+Use [`apm targets`](../targets/) to preview what auto-detection
+resolves to before compiling.
+
+The compiled output is scanned for hidden Unicode before any file is
+written. Critical findings cause the command to exit non-zero. See
+[Drift and secure by default](../../../consumer/drift-and-secure-by-default/).
+
+## Options
+
+### Target selection
+
+| Flag | Description |
+|------|-------------|
+| `-t, --target VALUE` | Target(s) to compile. Comma-separated. Values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `agent-skills`, `all`. |
+| `--all` | Compile for all canonical targets. Equivalent to `--target all` and mutually exclusive with `--target`. Preferred form. |
+
+`vscode` and `agents` are accepted as deprecated aliases for `copilot`
+and emit a one-line warning. `--target all` also emits a deprecation
+warning -- prefer `--all`.
+
+`agent-skills` is a no-op for `compile` (skills-only deployment target);
+include it in `--target` lists when you also want shared
+`.agents/skills/` output alongside another target.
+
+### Output control
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output PATH` | Output file path. Only applies in single-file mode (`--single-agents`). Default: `AGENTS.md`. |
+| `--single-agents` | Force single-file compilation (legacy). Writes one combined file at `--output` instead of distributed AGENTS.md tree. |
+| `--clean` | Remove orphaned AGENTS.md files no longer produced by the current primitive set. |
+
+### Content
+
+| Flag | Description |
+|------|-------------|
+| `--chatmode NAME` | Prepend the named chatmode to the generated AGENTS.md. |
+| `--no-links` | Skip markdown link resolution. |
+| `--with-constitution` / `--no-constitution` | Include or omit the Spec Kit `memory/constitution.md` block at the top. Default: included. When disabled, an existing block is preserved but not regenerated. |
+| `--local-only` | Ignore `apm_modules/`; compile only `.apm/` primitives. |
+| `--legacy-skill-paths` | Deploy skills to per-client paths (e.g. `.cursor/skills/`) instead of the shared `.agents/skills/`. Compatibility flag. |
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| `--watch` | Re-run compilation on file changes. See [Watch mode](#watch-mode). |
+| `--validate` | Validate primitives and exit. No files written. |
+| `--dry-run` | Show placement decisions without writing files. |
+| `-v, --verbose` | Show source attribution and optimizer analysis. |
+
+## Examples
+
+Compile for whatever the project is set up for:
+
+```bash
+apm compile
+```
+
+Compile for one target:
+
+```bash
+apm compile --target claude
+apm compile --target copilot
+apm compile --target cursor
+```
+
+Compile for several targets in one pass:
+
+```bash
+apm compile -t claude,copilot
+apm compile -t copilot,agent-skills
+```
+
+Compile for every canonical target:
+
+```bash
+apm compile --all
+```
+
+Validate without writing:
+
+```bash
+apm compile --validate
+```
+
+Preview placement:
+
+```bash
+apm compile --dry-run
+apm compile -t claude,codex --dry-run -v
+```
+
+Skip dependencies and compile only local primitives:
+
+```bash
+apm compile --local-only
+```
+
+Remove stale AGENTS.md files after deleting primitives:
+
+```bash
+apm compile --clean
+```
+
+## Watch mode
+
+`apm compile --watch` monitors the project for source changes and
+re-runs compilation automatically.
+
+- Watched directories (when present): `.apm/`, `.github/instructions/`,
+  `.github/agents/`, `.github/chatmodes/`.
+- Triggers on changes to `.md` files and `apm.yml`.
+- 1-second debounce to coalesce rapid edits.
+- Press Ctrl+C to stop.
+- Combine with `--dry-run` to validate placement on every save without
+  writing.
+
+```bash
+apm compile --watch
+apm compile --watch --dry-run
+```
+
+Watch mode uses the single-file output path (`--output`); for
+distributed compilation in watch mode, edit and re-run normally.
+
+## Output layout per target
+
+| Target | Files written |
+|--------|---------------|
+| `copilot` | `AGENTS.md`, `.github/copilot-instructions.md`, `.github/prompts/`, `.github/agents/`, `.github/skills/` |
+| `claude` | `CLAUDE.md`, `.claude/commands/`, `.claude/skills/SKILL.md` |
+| `cursor` | `AGENTS.md`, `.cursor/rules/`, `.cursor/skills/` |
+| `codex` | `AGENTS.md`, `.codex/agents/`, `.codex/hooks.json`, `.agents/skills/` |
+| `opencode` | `AGENTS.md`, `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/` |
+| `gemini` | `GEMINI.md`, `.gemini/commands/`, `.gemini/skills/` |
+| `windsurf` | `AGENTS.md`, `.windsurf/rules/`, `.windsurf/skills/`, `.windsurf/workflows/` |
+| `agent-skills` | `.agents/skills/` only (cross-client shared skills) |
+| `all` | All of the above except `agent-skills` |
+
+`.github/copilot-instructions.md` is only managed by APM when its first
+line is the marker `<!-- Generated by APM CLI from .apm/ primitives -->`.
+A hand-authored file is left untouched on both write and cleanup paths.
+To hand off an existing file to APM, prepend the marker (or delete the
+file) and re-run `apm compile`.
+
+## Strategy modes
+
+There is no `--strategy` flag. Compilation runs in one of two modes:
+
+- **Distributed (default)** -- writes a tree of focused AGENTS.md files
+  next to the code they apply to, plus per-target subdirectories. This
+  is the recommended mode and follows the Minimal Context Principle.
+- **Single-file (`--single-agents`)** -- writes one combined file at
+  `--output` (default `AGENTS.md`). Use when a harness or workflow
+  requires a single context file.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Compilation succeeded (or `--validate` passed). |
+| 1 | No `apm.yml`, no primitives to compile, validation failure, hidden-Unicode finding, or compilation error. |
+| 2 | Conflicting flags (e.g. `--all` combined with `--target`). |
+
+## Related
+
+- [`apm install`](../install/) -- fetches dependencies into `apm_modules/` so `compile` can read them.
+- [`apm targets`](../targets/) -- shows what targets resolve to in the current project.
+- [Concepts: primitives and targets](../../../concepts/primitives-and-targets/)
+- [Concepts: lifecycle](../../../concepts/lifecycle/)
+- [Producer: compile](../../../producer/compile/) -- author workflow that calls `compile` with packaging-specific defaults.
diff --git a/docs/src/content/docs/reference/cli/config.md b/docs/src/content/docs/reference/cli/config.md
new file mode 100644
index 000000000..5509477a9
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/config.md
@@ -0,0 +1,115 @@
+---
+title: apm config
+description: Read and write APM CLI configuration
+sidebar:
+  order: 10
+---
+
+Read and write APM CLI configuration stored in `~/.apm/config.json`.
+
+## Synopsis
+
+```bash
+apm config                       # show current configuration
+apm config get [KEY]             # print one key, or all keys
+apm config set KEY VALUE         # write a key
+apm config unset KEY             # remove a key
+```
+
+## Description
+
+`apm config` manages the user-level CLI configuration file at `~/.apm/config.json`. It is independent of `apm.yml`, which describes a project. With no subcommand, `apm config` prints a table that combines:
+
+- **Project** values from `apm.yml` in the current directory (when present): name, version, entrypoint, MCP dependency count, and compilation settings.
+- **Global** values from `~/.apm/config.json`: CLI version, `temp-dir`, and any other set keys.
+
+Use `get`/`set`/`unset` to manipulate individual keys. Boolean values accept `true`, `false`, `yes`, `no`, `1`, or `0`.
+
+## Subcommands
+
+### `apm config`
+
+Show the merged project + global configuration as a table. Falls back to plain text if `rich` is unavailable.
+
+### `apm config get [KEY]`
+
+Print the value of `KEY`. With no argument, prints all user-settable keys with their effective values (defaults included).
+
+### `apm config set KEY VALUE`
+
+Write `KEY` to `~/.apm/config.json`. Validates the value before writing:
+
+- `temp-dir` must be an existing, writable directory. The path is expanded (`~`) and stored absolute.
+- `copilot-cowork-skills-dir` must be absolute after expansion; the directory itself does not need to exist.
+- Boolean keys reject anything outside the accepted truthy/falsy strings.
+
+### `apm config unset KEY`
+
+Remove `KEY` from `~/.apm/config.json`. No-op if the key is not set. Only `temp-dir` and `copilot-cowork-skills-dir` are unsettable; boolean keys are reset by `set`-ing them to their default.
+
+## Configuration keys
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `auto-integrate` | boolean | `true` | Auto-discover `.prompt.md` files under `.github/prompts/` and `.apm/prompts/` and merge them into compiled `AGENTS.md` output. |
+| `temp-dir` | path | system temp | Directory used for clone and download operations. Useful when the OS temp directory is locked down (for example, corporate Windows endpoints rejecting `%TEMP%` with `[WinError 5]`). |
+| `copilot-cowork-skills-dir` | absolute path | auto-detected | Override the resolved Cowork OneDrive skills directory. Requires the `copilot-cowork` experimental flag for `set`. |
+
+### Resolution order
+
+`temp-dir` and `copilot-cowork-skills-dir` are resolved at runtime as:
+
+1. Environment variable (`APM_TEMP_DIR`, `APM_COPILOT_COWORK_SKILLS_DIR`)
+2. Value in `~/.apm/config.json`
+3. Built-in default (system temp / platform auto-detection)
+
+## Examples
+
+Show everything:
+
+```bash
+apm config
+```
+
+Read and write `auto-integrate`:
+
+```bash
+apm config get auto-integrate
+apm config set auto-integrate false
+```
+
+Pin a writable temp directory on Windows:
+
+```bash
+apm config set temp-dir C:\apm-temp
+apm config get temp-dir
+```
+
+Use the env var instead of persisting a value:
+
+```bash
+export APM_TEMP_DIR=/var/tmp/apm-work
+apm install
+```
+
+Override the Cowork skills directory (experimental):
+
+```bash
+apm experimental enable copilot-cowork
+apm config set copilot-cowork-skills-dir ~/Library/CloudStorage/OneDrive-Contoso/Cowork/skills
+apm config unset copilot-cowork-skills-dir
+```
+
+## Configuration file
+
+- **Location:** `~/.apm/config.json`
+- **Format:** JSON object, one entry per stored key.
+- **Created on first read** with `{"default_client": "vscode"}`. Hand-editing is supported but `apm config set` is preferred -- it validates input and normalizes paths.
+
+Internal JSON keys use snake_case (`auto_integrate`, `temp_dir`, `copilot_cowork_skills_dir`); CLI keys use kebab-case. The CLI translates between the two.
+
+## Related
+
+- [`apm install`](../install/) -- consumes `temp-dir` for clone/download work.
+- [`apm compile`](../compile/) -- affected by `auto-integrate`.
+- [`apm experimental`](../experimental/) -- gates `copilot-cowork-skills-dir`.
diff --git a/docs/src/content/docs/reference/cli/deps.md b/docs/src/content/docs/reference/cli/deps.md
new file mode 100644
index 000000000..03000e7c1
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/deps.md
@@ -0,0 +1,172 @@
+---
+title: apm deps
+description: Inspect, update, and clean installed APM dependencies.
+sidebar:
+  order: 23
+---
+
+Inspect, update, and clean dependencies that `apm install` placed under `apm_modules/`. `apm deps` is a command group; every action lives in a subcommand.
+
+## Synopsis
+
+```bash
+apm deps SUBCOMMAND [OPTIONS]
+```
+
+## Description
+
+`apm deps` is the read-and-maintenance counterpart to [`apm install`](../install/). It reads `apm.lock.yaml` and the `apm_modules/` tree to show what is installed, refresh git refs, or remove the tree entirely. It does not add new packages -- use `apm install <package>` for that.
+
+All subcommands operate on the project scope (`./apm_modules/`) by default. Pass `-g` / `--global` where supported to operate on the user scope (`~/.apm/apm_modules/`).
+
+## Subcommands
+
+| Subcommand | Purpose |
+|---|---|
+| `list` | List installed dependencies with per-primitive counts. |
+| `tree` | Render the dependency graph as a tree. |
+| `info PACKAGE` | Show detailed metadata for one installed package. |
+| `update [PACKAGES...]` | Re-resolve git refs and reinstall. |
+| `clean` | Remove the entire `apm_modules/` directory. |
+
+### `apm deps list`
+
+List installed dependencies and the primitive counts each one contributes.
+
+```bash
+apm deps list [OPTIONS]
+```
+
+| Option | Description |
+|---|---|
+| `-g, --global` | List user-scope dependencies in `~/.apm/` instead of the project. |
+| `--all` | Show both project and user-scope dependencies. |
+| `--insecure` | Show only dependencies locked to `http://` sources. Adds an `Origin` column distinguishing `direct` declarations from `via <parent>` transitive pulls. |
+
+### `apm deps tree`
+
+Render the dependency graph as a hierarchical tree, using `apm.lock.yaml` when present and falling back to a scan of `apm_modules/`.
+
+```bash
+apm deps tree [OPTIONS]
+```
+
+| Option | Description |
+|---|---|
+| `-g, --global` | Show the user-scope tree in `~/.apm/`. |
+
+### `apm deps info`
+
+Show detailed information about one installed package: manifest metadata, primitive inventory, and source. Equivalent to [`apm view PACKAGE`](../view/) for installed packages; prefer `apm view` in new scripts.
+
+```bash
+apm deps info PACKAGE
+```
+
+| Argument | Description |
+|---|---|
+| `PACKAGE` | Name of an installed package under `apm_modules/`. Required. |
+
+### `apm deps update`
+
+Re-resolve git references for installed dependencies (direct and transitive), download updated content, re-integrate primitives, and regenerate `apm.lock.yaml`.
+
+```bash
+apm deps update [PACKAGES...] [OPTIONS]
+```
+
+| Argument | Description |
+|---|---|
+| `PACKAGES...` | Optional. One or more packages to update. Omit to update everything. |
+
+| Option | Description |
+|---|---|
+| `-v, --verbose` | Show detailed update information. |
+| `--force` | Overwrite locally-authored files on collision. |
+| `-t, --target` | Force deployment to specific targets. Comma-separated. Values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `agent-skills`, `all`. `agent-skills` deploys to `.agents/skills/` (cross-client). `all` covers every per-client target but excludes `agent-skills`; combine to get both. |
+| `--parallel-downloads N` | Max concurrent downloads. Default `4`. `0` disables parallelism. |
+| `-g, --global` | Update user-scope dependencies in `~/.apm/`. |
+| `--legacy-skill-paths` | Deploy skill files to per-client paths (`.cursor/skills/`, etc.) instead of the shared `.agents/skills/` directory. |
+
+`apm deps update` runs the install pipeline and is gated by org `apm-policy.yml`. There is no `--no-policy` flag; the only escape hatch is `APM_POLICY_DISABLE=1` for the shell session.
+
+### `apm deps clean`
+
+Remove the entire project `apm_modules/` directory. Does not touch `apm.yml` or `apm.lock.yaml`.
+
+```bash
+apm deps clean [OPTIONS]
+```
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Show what would be removed without removing. |
+| `-y, --yes` | Skip the confirmation prompt (for CI and scripts). |
+
+## Examples
+
+List project dependencies:
+
+```bash
+apm deps list
+```
+
+Sample output:
+
+```
+ Package             Version  Source  Prompts  Instructions  Agents  Skills
+ compliance-rules    1.0.0    github  2        1             -       1
+ design-guidelines   1.0.0    github  -        1             1       -
+```
+
+Show only insecure (HTTP-locked) dependencies and their origin:
+
+```bash
+apm deps list --insecure
+```
+
+Render the tree:
+
+```bash
+apm deps tree
+```
+
+```
+my-project (local)
++-- compliance-rules@1.0.0
+|   +-- 1 instruction, 1 skill
++-- design-guidelines@1.0.0
+    +-- 1 instruction, 1 agent
+```
+
+Inspect one installed package:
+
+```bash
+apm deps info compliance-rules
+```
+
+Update everything:
+
+```bash
+apm deps update
+```
+
+Update specific packages with verbose output:
+
+```bash
+apm deps update org/pkg-a org/pkg-b --verbose
+```
+
+Preview a clean, then run it non-interactively:
+
+```bash
+apm deps clean --dry-run
+apm deps clean --yes
+```
+
+## Related
+
+- [`apm install`](../install/) -- add packages and run the install pipeline.
+- [`apm uninstall`](../uninstall/) -- remove a single package and its deployed files.
+- [`apm outdated`](../outdated/) -- check remotes for newer versions without modifying anything.
+- [Lockfile spec](../../lockfile-spec/) -- structure of `apm.lock.yaml` that `apm deps` reads.
diff --git a/docs/src/content/docs/reference/cli/experimental.md b/docs/src/content/docs/reference/cli/experimental.md
new file mode 100644
index 000000000..c3af33dfd
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/experimental.md
@@ -0,0 +1,112 @@
+---
+title: apm experimental
+description: Manage opt-in experimental feature flags stored in ~/.apm/config.json
+sidebar:
+  order: 24
+---
+
+Manage opt-in experimental feature flags. Flags gate new or changing behaviour so you can evaluate it before it graduates to default.
+
+:::caution
+Experimental flags can change behaviour, default value, or be removed entirely in any release. Do not depend on them in scripts or CI without pinning the APM CLI version.
+:::
+
+## Synopsis
+
+```bash
+apm experimental                       # alias for `list`
+apm experimental list [OPTIONS]
+apm experimental enable NAME
+apm experimental disable NAME
+apm experimental reset [NAME] [--yes]
+```
+
+## Description
+
+Experimental flags live under the `experimental` key of `~/.apm/config.json` and default to disabled. Toggling a flag persists the override; `reset` removes it. Flag names are case-insensitive and accept either kebab-case (`verbose-version`) or snake_case (`verbose_version`) on the command line.
+
+Flags never gate security-critical behaviour (content scanning, lockfile integrity, token handling, MCP trust checks). Those are always on. See [`apm audit`](../audit/) for the security model.
+
+## Subcommands
+
+### `apm experimental list`
+
+List all registered flags with their current status.
+
+| Option | Description |
+| --- | --- |
+| `--enabled` | Show only enabled flags. Mutually exclusive with `--disabled`. |
+| `--disabled` | Show only disabled flags. |
+| `--json` | Emit a JSON array (`name`, `enabled`, `default`, `description`, `source`). |
+| `-v`, `--verbose` | Show config file path and extra context. |
+
+### `apm experimental enable NAME`
+
+Enable a flag and persist the override. Prints a hint pointing to the relevant command when one is registered. Errors with `did you mean` suggestions if `NAME` is not registered.
+
+### `apm experimental disable NAME`
+
+Disable a flag and persist the override.
+
+### `apm experimental reset [NAME]`
+
+Reset one flag (when `NAME` is given) or all flags (when omitted) to registry defaults. Bulk reset prompts for confirmation and also removes unknown or malformed entries from `~/.apm/config.json`.
+
+| Option | Description |
+| --- | --- |
+| `-y`, `--yes` | Skip the confirmation prompt on bulk reset. |
+| `-v`, `--verbose` | Show config file path and extra context. |
+
+## Group options
+
+| Option | Description |
+| --- | --- |
+| `-v`, `--verbose` | Inherited by every subcommand unless overridden locally. |
+
+## Available flags
+
+| Flag | What it does | Related command |
+| --- | --- | --- |
+| `verbose-version` | Adds Python version, platform, and install path to `apm --version` output. | `apm --version` |
+| `copilot-cowork` | Enables Microsoft 365 Copilot Cowork skill deployment via OneDrive. | `apm compile --target copilot-cowork --global` |
+
+Run `apm experimental list` to see the live registry; new flags ship in minor releases.
+
+## Examples
+
+List all flags:
+
+```bash
+apm experimental list
+```
+
+Enable verbose version output:
+
+```bash
+apm experimental enable verbose-version
+apm --version
+```
+
+Show only enabled flags as JSON:
+
+```bash
+apm experimental list --enabled --json
+```
+
+Reset a single flag:
+
+```bash
+apm experimental reset verbose-version
+```
+
+Reset everything without prompting:
+
+```bash
+apm experimental reset --yes
+```
+
+## Related
+
+- [`apm config`](../config/) -- read and write user-level CLI configuration.
+- [Experimental flags reference](../../experimental/) -- detailed notes on each flag and its graduation status.
+- [`apm compile`](../compile/) -- target consumers of the `copilot-cowork` flag.
diff --git a/docs/src/content/docs/reference/cli/init.md b/docs/src/content/docs/reference/cli/init.md
new file mode 100644
index 000000000..f0c202a56
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/init.md
@@ -0,0 +1,113 @@
+---
+title: apm init
+description: Scaffold a new APM project by creating apm.yml (and optionally plugin.json) with auto-detected metadata.
+sidebar:
+  order: 1
+---
+
+## Synopsis
+
+```bash
+apm init [PROJECT_NAME] [OPTIONS]
+```
+
+## Description
+
+Creates a minimal `apm.yml` in the current directory or in a new
+`PROJECT_NAME` subdirectory. Auto-detects name, author, and description
+so you can start running `apm install` immediately. Use `--plugin` to
+also scaffold `plugin.json` for a publishable plugin, or `--marketplace`
+to seed an authoring block for a marketplace.
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `PROJECT_NAME` | Optional. Name of a new directory to create and `cd` into. Pass `.` to initialize in the current directory (same as omitting). Must not contain `/`, `\`, or be `..`. |
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `-y`, `--yes` | off | Skip interactive prompts; use auto-detected defaults. Overwrites an existing `apm.yml` without confirmation. |
+| `--plugin` | off | Scaffold a plugin authoring project: also writes `plugin.json` and adds a `devDependencies` block to `apm.yml`. Plugin name must be kebab-case, max 64 chars. |
+| `--marketplace` | off | Append a `marketplace:` authoring block to `apm.yml`. See [Publish to a marketplace](../../../producer/publish-to-a-marketplace/). |
+| `--target` | (prompt) | Comma-separated target list. Skips the interactive target prompt and writes targets directly. Valid values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`. |
+| `-v`, `--verbose` | off | Show detailed output. |
+
+Target precedence: `--target` flag > interactive prompt > auto-detect at
+compile time (used with `--yes` or in non-TTY shells).
+
+## Examples
+
+Initialize in the current directory with prompts:
+
+```bash
+$ apm init
+Setting up your APM project...
+Project name: my-app
+Version (1.0.0):
+Description: My APM project
+Author: alice
+About to create:
+  name: my-app
+  targets: copilot, claude
+Is this OK? [Y/n]: y
+[+] APM project initialized successfully!
+Created Files
+  * apm.yml  Project configuration
+```
+
+Non-interactive scaffold of a new directory:
+
+```bash
+$ apm init my-app --yes
+[*] Created project directory: my-app
+[+] APM project initialized successfully!
+Created Files
+  * apm.yml  Project configuration
+```
+
+Plugin authoring project (creates `plugin.json` plus `apm.yml` with
+`devDependencies`, version defaults to `0.1.0`):
+
+```bash
+$ apm init my-skill --plugin --yes
+[+] APM project initialized successfully!
+Created Files
+  * apm.yml      Project configuration
+  * plugin.json  Plugin metadata
+```
+
+Pin targets up front, skip the prompt:
+
+```bash
+$ apm init --yes --target copilot,claude,cursor
+```
+
+## Behavior
+
+- **Files created:** `apm.yml` always. `plugin.json` when `--plugin` is
+  set. The `marketplace:` block is appended to `apm.yml` when
+  `--marketplace` is set.
+- **Auto-detected fields:**
+  - `name` -- from `PROJECT_NAME` or current directory name.
+  - `author` -- from `git config user.name`, fallback `Developer`.
+  - `description` -- generated from project name.
+  - `version` -- `1.0.0` (or `0.1.0` with `--plugin --yes`).
+- **Brownfield (existing `apm.yml`):** prints `[!] apm.yml already exists`
+  and prompts to overwrite. With `--yes`, overwrites without asking.
+- **Target seeding on re-init:** when `apm.yml` exists, the prompt
+  pre-checks targets read from its existing `target:` field.
+- **Codex hint:** if `.codex/` is present, suggests
+  `--target agent-skills` to also deploy skills to `.agents/skills/`.
+- **Exit codes:** `0` on success or user-aborted prompt; `1` on invalid
+  project or plugin name, or unhandled error.
+
+## Related
+
+- [`apm install`](../install/) -- next step: install dependencies and
+  deploy to targets.
+- [Quickstart](../../../quickstart/) -- guided first project.
+- [Concepts: package anatomy](../../../concepts/package-anatomy/) --
+  what goes in `apm.yml`.
diff --git a/docs/src/content/docs/reference/cli/install.md b/docs/src/content/docs/reference/cli/install.md
new file mode 100644
index 000000000..9e47fd940
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/install.md
@@ -0,0 +1,192 @@
+---
+title: apm install
+description: Install dependencies and deploy primitives to detected targets.
+sidebar:
+  order: 2
+---
+
+## Synopsis
+
+```bash
+apm install [PACKAGE_REF...] [OPTIONS]
+```
+
+## Description
+
+`apm install` resolves the dependencies declared in `apm.yml`, downloads them (with transitive resolution and a content-addressed cache), runs the built-in security scan, and deploys the resulting primitives plus the project's own `.apm/` content into every harness target it detects. It writes `apm.lock.yaml` so the next install on any machine reproduces the same files.
+
+With no arguments it installs everything from `apm.yml`. With one or more `PACKAGE_REF` arguments it adds those packages to `apm.yml` (creating one if needed) and installs only what was added. `apm install --mcp NAME` is the dedicated path for adding an MCP server entry.
+
+`PACKAGE_REF` accepts: shorthand (`owner/repo`), HTTPS or SSH Git URLs, FQDN shorthand (`host/owner/repo`), local paths (`./path`, `/abs/path`, `~/path`), packed bundles (`./bundle.tar.gz`), and marketplace refs (`NAME@MARKETPLACE[#ref]`).
+
+:::caution
+`http://` dependencies are refused unless you pass `--allow-insecure` (direct) or `--allow-insecure-host HOSTNAME` (transitive).
+:::
+
+## Options
+
+### Common
+
+| Flag | Default | Description |
+|---|---|---|
+| `--update` | off | Re-resolve dependencies to the latest Git ref allowed by `apm.yml` and rewrite `apm.lock.yaml`. Mutually exclusive with `--frozen`. Prefer the dedicated [`apm update`](../update/) command for the consent-gated workflow. |
+| `--frozen` | off | Lockfile-only install: refuse to resolve anything new and fail if `apm.yml` and `apm.lock.yaml` have drifted. Mirrors `npm ci`. Mutually exclusive with `--update`. |
+| `--dry-run` | off | Print the install plan without touching the filesystem. |
+| `--force` | off | Overwrite locally-authored files on collision **and** bypass the security scan's critical-finding block. Does **not** refresh remote refs -- use `apm update` for that. Use only after independent verification. |
+| `--verbose`, `-v` | off | Show per-file paths and full error context in the diagnostic summary. |
+| `--dev` | off | Add new packages to `devDependencies`. Dev deps install locally but are excluded from `apm pack` output. |
+
+### Target selection
+
+| Flag | Default | Description |
+|---|---|---|
+| `--target`, `-t VALUE` | auto-detect | Force deployment targets. Comma-separated for multiple (`-t claude,cursor`). Values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `agent-skills`, `all`. `all` expands to every harness above except `agent-skills`; combine `all,agent-skills` for both. Highest precedence in the chain `--target` > `apm.yml targets:` > auto-detect. With nothing to detect, install exits `2` with a teaching message. |
+| `--runtime VALUE` | unset | Legacy alias for `--target` (single value only). Still accepted; prefer `--target`. |
+| `--exclude VALUE` | unset | Skip a single runtime that auto-detect or `targets:` would otherwise enable. |
+| `--only apm\|mcp` | both | Install only APM packages or only MCP servers. |
+| `-g`, `--global` | off | Install to user scope (`~/.apm/`) instead of the current project. MCP servers deploy only to global-capable runtimes (Copilot CLI, Codex CLI). |
+| `--legacy-skill-paths` | off | Deploy skills to per-client paths (`.cursor/skills/`, `.github/skills/`, ...) instead of the converged `.agents/skills/`. Env: `APM_LEGACY_SKILL_PATHS=1`. |
+
+### Policy and trust
+
+| Flag | Default | Description |
+|---|---|---|
+| `--no-policy` | off | Skip org policy enforcement for this invocation. Loudly logged. Does not bypass `apm audit --ci`. Env: `APM_POLICY_DISABLE=1`. |
+| `--trust-transitive-mcp` | off | Trust self-defined MCP servers shipped by transitive packages without re-declaring them in your `apm.yml`. |
+| `--allow-insecure` | off | Permit direct `http://` (non-TLS) dependencies. |
+| `--allow-insecure-host HOSTNAME` | unset | Permit transitive `http://` dependencies from `HOSTNAME`. Repeatable. |
+
+### Cache and network
+
+| Flag | Default | Description |
+|---|---|---|
+| `--parallel-downloads N` | `4` | Max concurrent package downloads. `0` disables parallelism. |
+| `--refresh` | off | Bypass the persistent cache and re-fetch every dependency from upstream. |
+| `--ssh` | off | Prefer SSH transport for shorthand (`owner/repo`) deps. Mutually exclusive with `--https`. |
+| `--https` | off | Prefer HTTPS transport for shorthand deps. Mutually exclusive with `--ssh`. |
+| `--allow-protocol-fallback` | off | Restore the legacy permissive HTTPS<->SSH fallback chain. Env: `APM_ALLOW_PROTOCOL_FALLBACK=1`. |
+
+Transport env vars: `APM_GIT_PROTOCOL` (`ssh` or `https`) sets the default initial transport for shorthand deps; `APM_ALLOW_PROTOCOL_FALLBACK=1` mirrors `--allow-protocol-fallback`.
+
+### Skill subset
+
+| Flag | Default | Description |
+|---|---|---|
+| `--skill NAME` | all | Install only named skill(s) from a `SKILL_BUNDLE` package. Repeatable. The selection is persisted to `apm.yml` and `apm.lock.yaml`. Use `--skill '*'` to reset and install all. |
+| `--as ALIAS` | bundle id | Override the log/display label for a local-bundle install. Only valid with a single local-bundle `PACKAGE_REF`. |
+
+### MCP server entry (use only with `--mcp`)
+
+| Flag | Default | Description |
+|---|---|---|
+| `--mcp NAME` | unset | Add an MCP server entry to `apm.yml` and install it. Pair with the flags below or pass an executable after `--`. |
+| `--transport stdio\|http\|sse\|streamable-http` | inferred | Inferred from `--url` or the post-`--` argv when omitted. |
+| `--url URL` | unset | Endpoint for `http`, `sse`, or `streamable-http` transports. Scheme must be `http` or `https`. |
+| `--env KEY=VALUE` | unset | Environment variable for stdio MCP servers. Repeatable. |
+| `--header KEY=VALUE` | unset | HTTP header for remote MCP servers. Repeatable. Requires `--url`. |
+| `--mcp-version VER` | unset | Pin a registry MCP entry to a specific version. |
+| `--registry URL` | `https://api.mcp.github.com` | Custom MCP registry URL for resolving `--mcp NAME`. Persisted to `apm.yml`. Overrides `MCP_REGISTRY_URL`. Not valid with `--url` or a stdio command. |
+
+## Behavior
+
+- **Auto-bootstrap.** `apm install <pkg>` with no `apm.yml` creates a minimal one. Bare `apm install` with no `apm.yml` exits with a hint to run `apm init` or `apm install <org/repo>`.
+- **Diff-aware.** Packages whose ref or version changed in `apm.yml` are re-downloaded automatically; `--update` is only needed to pull a newer ref under a floating constraint. MCP servers with matching config are skipped (`already configured`); changed config is re-applied (`updated`).
+- **No-op nudge.** When the lockfile is already satisfied and nothing needs deploying, install prints `[i] Run 'apm update' to check for newer versions.` so you know the silent success was not a missed refresh.
+- **Frozen mode.** With `--frozen`, install resolves only what is in `apm.lock.yaml`. A direct dependency missing from the lockfile, or a missing lockfile entirely, exits `1`. Orphan lockfile entries (locked but no longer in `apm.yml`) are tolerated; local-path deps are skipped. This is a structural check, not a content check -- run `apm audit --ci` for hash verification.
+- **Local `.apm/` deployment.** After dependencies are integrated, primitives in the project's own `.apm/` directory are deployed to the same targets. Local files win on collision. Skipped at `--global` and with `--only mcp`.
+- **Stale-file cleanup.** Files a still-present package previously deployed but no longer produces are removed from the workspace, gated by per-file content hashes recorded in the lockfile (user-edited files are kept with a warning).
+- **Security scan.** Source files are scanned for hidden Unicode and other tag-character / bidi-override patterns before deployment. Critical findings block the package; the install exits `1`. Use `--force` to deploy anyway, or run `apm audit --strip` first to remediate.
+- **Diagnostic summary.** Output is grouped at the end (collisions, replacements, warnings, errors) instead of inline. Use `--verbose` to expand individual file paths.
+
+## Examples
+
+### Install everything from apm.yml
+
+```bash
+apm install
+```
+
+### Install (and add) a specific package
+
+```bash
+apm install microsoft/apm-sample-package
+apm install https://gitlab.com/acme/coding-standards.git
+apm install code-review@acme-plugins#v2.0.0
+```
+
+### Install only an MCP server
+
+```bash
+# Stdio server via post-`--` argv
+apm install --mcp filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace
+
+# Registry entry
+apm install --mcp io.github.github/github-mcp-server
+
+# Remote HTTP server
+apm install --mcp my-api --url https://mcp.example.com --header "Authorization=Bearer ${API_TOKEN}"
+```
+
+### Pick targets explicitly
+
+```bash
+apm install --target claude,cursor
+apm install --target all,agent-skills
+apm install --exclude codex
+```
+
+### Install in CI (no interactive prompts, no policy escape)
+
+```bash
+# Fail fast on any drift; never bypass policy in CI.
+apm install --parallel-downloads 8
+```
+
+For a CI workflow that also gates on `apm audit --ci`, see [Enforce in CI](../../../enterprise/enforce-in-ci/).
+
+### Preview without writing
+
+```bash
+apm install --dry-run
+apm install microsoft/apm-sample-package --dry-run
+```
+
+### Install a local bundle produced by `apm pack`
+
+```bash
+apm install ./build/my-bundle
+apm install ./my-bundle.tar.gz --as custom-name
+apm install ./my-bundle --target opencode
+```
+
+### Install only a subset of skills from a bundle
+
+```bash
+apm install owner/skill-bundle --skill review --skill refactor
+apm install owner/skill-bundle --skill '*'   # reset to all skills
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. All requested dependencies and local content deployed. |
+| `1` | Install failure: security scan blocked a critical finding, auth error, manifest write error, dependency resolution error, `--frozen` with a missing lockfile or a direct dependency absent from `apm.lock.yaml`, or unhandled exception. The diagnostic summary names the cause. |
+| `2` | Usage error: no deployment target detectable (no `--target`, no `targets:` in `apm.yml`, no harness signal in the project), `--ssh` and `--https` both passed, `--frozen` and `--update` both passed, or a Click flag conflict. |
+
+## Notes
+
+- **`--force` is dual-purpose.** It overwrites locally-authored files on collision **and** disables the critical-finding block from the built-in security scan. It does **not** refresh remote refs -- for routine ref updates, run [`apm update`](../update/). To remediate findings, prefer `apm audit --strip`. See [Drift and secure by default](../../../consumer/drift-and-secure-by-default/).
+- **Claude target prompt rewrite.** When deploying to `.claude/commands/`, prompt files with an `input:` front-matter key are rewritten to Claude's `arguments:` shape and `${input:name}` placeholders become `$name`. Argument names must match `^[A-Za-z][\w-]{0,63}$`; rejected names are dropped with a warning.
+- **Copilot CLI env-var passthrough.** When deploying MCP entries to `~/.copilot/mcp-config.json`, `${env:VAR}` and `<VAR>` placeholders are translated to `${VAR}` so Copilot CLI resolves them at server-start. Plaintext secrets are never written to disk. Other targets currently resolve placeholders at install time.
+
+## Related
+
+- [`apm update`](../update/) -- refresh dependencies in `apm.yml` to their latest matching refs, with a consent gate.
+- [`apm self-update`](../self-update/) -- upgrade the `apm` CLI binary itself.
+- [`apm prune`](../prune/) -- remove orphaned packages and stale files.
+- [`apm audit`](../audit/) -- explicit security reporting and remediation after install.
+- [`apm targets`](../targets/) -- print which harnesses APM detects in the current directory.
+- [Install packages (consumer guide)](../../../consumer/install-packages/) -- task-oriented walkthrough.
+- [Manifest schema](../../manifest-schema/) -- field reference for `apm.yml`.
+- [Lockfile spec](../../lockfile-spec/) -- field reference for `apm.lock.yaml`.
diff --git a/docs/src/content/docs/reference/cli/list.md b/docs/src/content/docs/reference/cli/list.md
new file mode 100644
index 000000000..9cbec55ac
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/list.md
@@ -0,0 +1,88 @@
+---
+title: apm list
+description: List scripts defined in apm.yml
+sidebar:
+  order: 6
+---
+
+List the scripts declared in your project's `apm.yml`.
+
+## Synopsis
+
+```bash
+apm list
+```
+
+## Description
+
+`apm list` prints every entry from the `scripts:` mapping in the `apm.yml` at your current working directory. Scripts are short shell commands you invoke with [`apm run`](../run/) -- the same pattern as `npm run` in `package.json`.
+
+This command does **not** list installed packages, dependencies, or files under `apm_modules/`. It only reads the `scripts:` section of the manifest.
+
+If a script named `start` exists, it is marked as the default and runs when you call `apm run` with no script name.
+
+:::note[Coming from npm?]
+`apm list` is closer to `npm run` (with no arguments) than to `npm list`. There is no tree view of installed packages. To inspect what `apm install` placed on disk, look inside `apm_modules/` or read [`apm.lock.yaml`](../../lockfile-spec/).
+:::
+
+## Options
+
+None. `apm list` takes no flags or arguments.
+
+Global flags from the root command (`--verbose`, `--quiet`) apply.
+
+## Examples
+
+### List scripts in the current project
+
+Given an `apm.yml` like:
+
+```yaml
+name: my-project
+version: 0.1.0
+scripts:
+  start: "codex run main.prompt.md"
+  fast: "llm prompt main.prompt.md -m github/gpt-4o-mini"
+  debug: "RUST_LOG=debug codex run main.prompt.md"
+```
+
+Run:
+
+```bash
+apm list
+```
+
+Output:
+
+```
+ Available Scripts
+
+  Script   Command
+ -------------------------------------------------------------------
+  [*] start    codex run main.prompt.md
+      fast     llm prompt main.prompt.md -m github/gpt-4o-mini
+      debug    RUST_LOG=debug codex run main.prompt.md
+
+[i] [*] = default script (runs when no script name specified)
+```
+
+### Empty scripts section
+
+If `apm.yml` has no `scripts:` entries, `apm list` prints a warning and shows an example block you can paste in:
+
+```
+[!] No scripts found.
+
+Add scripts to your apm.yml file:
+scripts:
+  start: "codex run main.prompt.md"
+  fast: "llm prompt main.prompt.md -m github/gpt-4o-mini"
+```
+
+Edit `apm.yml`, add at least one script, and re-run `apm list`.
+
+## Related
+
+- [`apm run`](../run/) -- execute a listed script.
+- [`apm install`](../install/) -- install the dependencies your scripts invoke.
+- [Package anatomy](../../../concepts/package-anatomy/) -- where `scripts:` sits in the manifest.
diff --git a/docs/src/content/docs/reference/cli/marketplace.md b/docs/src/content/docs/reference/cli/marketplace.md
new file mode 100644
index 000000000..e2b64b78d
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/marketplace.md
@@ -0,0 +1,246 @@
+---
+title: apm marketplace
+description: Register marketplaces, author manifests, and publish updates to consumer repositories.
+sidebar:
+  order: 20
+---
+
+Manage marketplaces -- both **consuming** them (registering a remote
+marketplace so packages resolve by `package@marketplace` shorthand)
+and **authoring** one (editing `apm.yml`'s `marketplace:` block,
+validating it, and publishing updates to consumer repositories).
+
+## Synopsis
+
+```bash
+# Consume
+apm marketplace add REPO [--name N] [--branch B] [--host FQDN]
+apm marketplace list
+apm marketplace browse NAME
+apm marketplace update [NAME]
+apm marketplace remove NAME
+apm marketplace validate NAME
+
+# Author
+apm marketplace init [--force] [--name N] [--owner O]
+apm marketplace migrate [--force | --dry-run]
+apm marketplace check [--offline]
+apm marketplace doctor
+apm marketplace outdated [--offline] [--include-prerelease]
+apm marketplace publish [--targets FILE] [--dry-run] [--no-pr] [...]
+
+# Edit packages in the authoring config
+apm marketplace package add SOURCE [...]
+apm marketplace package set NAME [...]
+apm marketplace package remove NAME [--yes]
+```
+
+## Description
+
+A marketplace is a git-hosted index of APM packages. Two roles
+interact with this command:
+
+- **Consumers** register marketplaces so dependencies in `apm.yml`
+  can resolve by short name (`my-pkg@my-marketplace`) instead of a
+  full git URL. See [`apm install`](../install/).
+- **Authors** maintain a marketplace's `apm.yml` (`marketplace:`
+  block) and ship updates to consumer repositories via
+  `apm marketplace publish`.
+
+The authoring config is the `marketplace:` block of `apm.yml` in the
+current working directory. Legacy `marketplace.yml` files are still
+read; use `apm marketplace migrate` to fold them into `apm.yml`.
+
+## Subcommands
+
+### `apm marketplace add`
+
+Register a marketplace from a repo reference. Accepts `OWNER/REPO`,
+`HOST/OWNER/.../REPO`, or an HTTPS git URL.
+
+```bash
+apm marketplace add my-org/awesome-agents
+apm marketplace add gitlab.com/my-org/awesome-agents --host gitlab.com
+```
+
+| Flag | Description |
+|---|---|
+| `--name`, `-n` | Display name. Defaults to the repo name. |
+| `--branch`, `-b` | Branch to track. Default: `main`. |
+| `--host` | Git host FQDN. Default: `github.com`. |
+| `--verbose`, `-v` | Show detailed output. |
+
+### `apm marketplace list`
+
+List every registered marketplace with its source URL and tracked
+branch.
+
+```bash
+apm marketplace list
+apm marketplace list --verbose
+```
+
+### `apm marketplace browse NAME`
+
+Show the packages exposed by a registered marketplace.
+
+```bash
+apm marketplace browse awesome-agents
+```
+
+### `apm marketplace update [NAME]`
+
+Refresh the local cache for one marketplace, or all when `NAME` is
+omitted.
+
+```bash
+apm marketplace update                 # refresh every registered marketplace
+apm marketplace update awesome-agents  # refresh one
+```
+
+### `apm marketplace remove NAME`
+
+Unregister a marketplace.
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip the confirmation prompt. |
+
+### `apm marketplace validate NAME`
+
+Validate the manifest of a registered marketplace against the schema.
+
+### `apm marketplace init`
+
+Add a `marketplace:` block to `apm.yml` in the current directory,
+scaffolding `apm.yml` if it does not exist.
+
+| Flag | Description |
+|---|---|
+| `--force` | Overwrite an existing `marketplace:` block. |
+| `--name` | Marketplace/package name. Default: `my-marketplace`. |
+| `--owner` | Owner name for the marketplace. |
+| `--no-gitignore-check` | Skip the `.gitignore` staleness check. |
+
+### `apm marketplace migrate`
+
+Fold a legacy `marketplace.yml` into the `marketplace:` block of
+`apm.yml`.
+
+| Flag | Description |
+|---|---|
+| `--force`, `--yes`, `-y` | Overwrite an existing block. |
+| `--dry-run` | Preview the proposed changes without writing them. |
+
+### `apm marketplace check`
+
+Validate the schema of the authoring config and verify that every
+package entry resolves to a reachable git ref.
+
+| Flag | Description |
+|---|---|
+| `--offline` | Schema and cached-ref checks only; no network. |
+
+### `apm marketplace doctor`
+
+Run environment diagnostics for marketplace publishing: git binary,
+network reachability, auth (`gh`/PAT), and config sanity.
+
+### `apm marketplace outdated`
+
+Show packages in the authoring config that have newer upstream
+versions available.
+
+| Flag | Description |
+|---|---|
+| `--offline` | Use cached refs only. |
+| `--include-prerelease` | Consider prerelease tags. |
+
+### `apm marketplace publish`
+
+Push marketplace updates to one or more **consumer** repositories,
+optionally opening pull requests.
+
+```bash
+apm marketplace publish --dry-run
+apm marketplace publish --targets ./consumer-targets.yml --draft
+```
+
+| Flag | Description |
+|---|---|
+| `--targets FILE` | Path to consumer-targets YAML. Default: `./consumer-targets.yml`. |
+| `--dry-run` | Preview without pushing or opening PRs. |
+| `--no-pr` | Push branches but skip PR creation. |
+| `--draft` | Open PRs as drafts. |
+| `--allow-downgrade` | Permit version downgrades. |
+| `--allow-ref-change` | Permit switching ref types (e.g. tag to SHA). |
+| `--parallel N` | Maximum concurrent target updates. Default: `4`. |
+| `--yes`, `-y` | Skip the confirmation prompt. |
+
+### `apm marketplace package add SOURCE`
+
+Add a package entry to the authoring config. `SOURCE` is a git repo
+reference. Mutable refs (`HEAD`, branches) are auto-resolved to a
+concrete SHA at write time.
+
+| Flag | Description |
+|---|---|
+| `--name` | Package name. Default: repo name. |
+| `--version` | Semver range (e.g. `>=1.0.0`). |
+| `--ref` | Pin to a git ref (SHA, tag, or `HEAD`). |
+| `--subdir`, `-s` | Subdirectory inside the source repo. |
+| `--tag-pattern` | Tag pattern (e.g. `v{version}`). |
+| `--tags` | Comma-separated tags. |
+| `--include-prerelease` | Include prerelease versions. |
+| `--no-verify` | Skip the remote reachability check. |
+
+### `apm marketplace package set NAME`
+
+Update fields on an existing package entry. Same flag set as
+`package add` minus `--no-verify`; only the fields you pass are
+modified.
+
+### `apm marketplace package remove NAME`
+
+Remove a package entry from the authoring config.
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip the confirmation prompt. |
+
+## Options
+
+Every subcommand accepts `--verbose` / `-v` for detailed output.
+Flags listed per-subcommand above are the only command-specific
+flags.
+
+## Examples
+
+Register an upstream marketplace and install a package from it:
+
+```bash
+apm marketplace add my-org/awesome-agents
+apm install code-reviewer@awesome-agents
+```
+
+Bootstrap a new marketplace, add a package, and verify:
+
+```bash
+apm marketplace init --name my-marketplace --owner my-org
+apm marketplace package add my-org/code-reviewer --version '>=1.0.0'
+apm marketplace check
+```
+
+Preview a publish, then ship it as drafts:
+
+```bash
+apm marketplace publish --dry-run
+apm marketplace publish --draft
+```
+
+## Related
+
+- [`apm install`](../install/) -- consume packages from registered marketplaces.
+- [`apm search`](../search/) -- top-level shortcut for `QUERY@MARKETPLACE` package search across registered marketplaces.
+- [Publish to a marketplace](../../../producer/publish-to-a-marketplace/) -- end-to-end authoring guide.
+- [Manifest schema](../../manifest-schema/) -- shape of the `marketplace:` block in `apm.yml`.
diff --git a/docs/src/content/docs/reference/cli/mcp.md b/docs/src/content/docs/reference/cli/mcp.md
new file mode 100644
index 000000000..477684829
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/mcp.md
@@ -0,0 +1,151 @@
+---
+title: apm mcp
+description: Discover and inspect MCP servers in the registry
+sidebar:
+  order: 22
+---
+
+Discover, inspect, and install MCP servers from the public MCP registry
+(or an enterprise mirror).
+
+## Synopsis
+
+```bash
+apm mcp list [--limit N] [--verbose]
+apm mcp search QUERY [--limit N] [--verbose]
+apm mcp show SERVER_NAME [--verbose]
+apm mcp install NAME [-- runtime args...]
+```
+
+## Description
+
+`apm mcp` groups read-only registry queries (`list`, `search`, `show`)
+plus a thin install alias.
+
+The canonical install path for MCP servers is
+[`apm install --mcp NAME`](../install/#mcp-server-entry-use-only-with---mcp). It
+edits `apm.yml`, resolves the registry entry, and writes the resulting
+`mcpServers` block to your project. `apm mcp install` is a forwarder
+that calls the same code path -- use whichever spelling you prefer.
+
+For an end-to-end consumer walkthrough (declaring an MCP server in
+`apm.yml`, configuring transport and credentials, deploying to a
+runtime), see
+[Install MCP servers](../../../consumer/install-mcp-servers/).
+
+## Subcommands
+
+### `apm mcp list`
+
+List servers published to the registry.
+
+```bash
+apm mcp list                 # first 20 entries
+apm mcp list --limit 50
+```
+
+| Flag | Description |
+|---|---|
+| `--limit N` | Number of results to show. Default: `20`. |
+| `--verbose`, `-v` | Show detailed diagnostic output. |
+
+### `apm mcp search`
+
+Substring search across registry entries.
+
+```bash
+apm mcp search github
+apm mcp search fetch --limit 5
+```
+
+| Flag | Description |
+|---|---|
+| `--limit N` | Number of results to show. Default: `10`. |
+| `--verbose`, `-v` | Show detailed diagnostic output. |
+
+### `apm mcp show`
+
+Print full metadata for a single server: version, repository,
+deployment type (remote endpoint and/or local package), and the steps
+to add it to a project.
+
+```bash
+apm mcp show io.github.modelcontextprotocol/server-fetch
+```
+
+| Flag | Description |
+|---|---|
+| `--verbose`, `-v` | Show detailed diagnostic output. |
+
+Exit code `1` if the server name is not present in the registry.
+
+### `apm mcp install`
+
+Alias for [`apm install --mcp NAME`](../install/#mcp-server-entry-use-only-with---mcp).
+All flags and the post-`--` runtime command are forwarded verbatim.
+
+```bash
+apm mcp install fetch -- npx -y @modelcontextprotocol/server-fetch
+apm mcp install api --transport http --url https://example.com/mcp
+```
+
+Common forwarded options (see `apm install --mcp --help` for the full
+list):
+
+| Flag | Description |
+|---|---|
+| `--transport [stdio\|http\|sse\|streamable-http]` | Transport type. |
+| `--url URL` | Server URL for remote transports. |
+| `--env KEY=VALUE` | Environment variable. Repeatable. |
+| `--header KEY=VALUE` | HTTP header. Repeatable. |
+| `--registry URL` | Custom registry URL for this invocation. |
+| `--mcp-version VER` | Pin the registry entry to a specific version. |
+| `--dev` | Add to `devDependencies`. |
+| `--dry-run` | Resolve and print without writing `apm.yml`. |
+| `--force` | Overwrite an existing entry. |
+| `--no-policy` | Skip policy checks. |
+| `--verbose`, `-v` | Verbose output. |
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `MCP_REGISTRY_URL` | Override the registry endpoint used by `list`, `search`, `show`, and `install`. When set, every command prints a one-line `Registry: <url>` diagnostic so the override is visible. Unset: the public default registry is used silently. |
+
+Network failures against an overridden registry surface an explicit
+hint pointing at `MCP_REGISTRY_URL` so misconfigurations are easy to
+spot in CI logs.
+
+## Examples
+
+Discover and inspect:
+
+```bash
+apm mcp search github
+apm mcp show io.github.github/github-mcp-server
+```
+
+Install a stdio server with a runtime command:
+
+```bash
+apm mcp install fetch -- npx -y @modelcontextprotocol/server-fetch
+```
+
+Install a remote HTTP server:
+
+```bash
+apm mcp install api --transport http --url https://example.com/mcp \
+  --header "Authorization=Bearer $TOKEN"
+```
+
+Point at an enterprise registry mirror:
+
+```bash
+export MCP_REGISTRY_URL=https://mcp.internal.example.com
+apm mcp list
+```
+
+## Related
+
+- [`apm install`](../install/) -- canonical MCP install path.
+- [Install MCP servers](../../../consumer/install-mcp-servers/) -- consumer guide covering `apm.yml`, transports, and runtime deployment.
diff --git a/docs/src/content/docs/reference/cli/outdated.md b/docs/src/content/docs/reference/cli/outdated.md
new file mode 100644
index 000000000..90092acac
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/outdated.md
@@ -0,0 +1,98 @@
+---
+title: apm outdated
+description: Check locked dependencies for newer versions
+sidebar:
+  order: 8
+---
+
+Compare locked dependencies against their remotes to see what has new versions available. Read-only: this command does not modify `apm.lock.yaml` or touch `apm_modules/`.
+
+## Synopsis
+
+```bash
+apm outdated [OPTIONS]
+```
+
+## Description
+
+`apm outdated` reads `apm.lock.yaml` and queries each remote to detect staleness:
+
+- **Tag-pinned deps** (e.g. `v1.2.3`): semver compare against the latest available remote tag.
+- **Branch-pinned deps** (e.g. `main`): compare the locked commit SHA against the remote branch tip.
+- **Default-branch deps** (no ref): compare against `main`/`master` tip.
+- **Marketplace deps**: compare the installed ref against the marketplace entry's current `source.ref`.
+
+Local dependencies and Artifactory-hosted deps are skipped. Legacy `apm.lock` files are migrated to `apm.lock.yaml` automatically on read.
+
+To apply the suggested updates, run `apm install --update` (see [Related](#related)).
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-g, --global` | Check user-scope dependencies in `~/.apm/` instead of the current project. |
+| `-v, --verbose` | For outdated tag-pinned deps, also list up to 10 newer available tags. |
+| `-j, --parallel-checks N` | Max concurrent remote checks. Default `4`. `0` forces sequential. |
+
+## Examples
+
+Check project dependencies:
+
+```bash
+apm outdated
+```
+
+Sample output:
+
+```
+                        Dependency Status
+  Package                       Current   Latest        Status      Source
+  ----------------------------- --------- ------------- ----------- ---------------
+  acme/agent-skills             v1.2.0    v1.4.1        outdated    git tags
+  acme/prompt-pack              main      9c1ab2f0      outdated    git branch
+  acme/lint-rules               v0.3.0    v0.3.0        up-to-date  git tags
+  pirate-skill@apm-marketplace  v0.2.1    v0.3.0 (...)  outdated    marketplace: apm-marketplace
+
+  [!] 2 outdated dependencies found
+```
+
+Check user-scope deps installed under `~/.apm/`:
+
+```bash
+apm outdated --global
+```
+
+Show available tags for outdated packages:
+
+```bash
+apm outdated --verbose
+```
+
+Use 8 parallel checks for large dependency sets:
+
+```bash
+apm outdated -j 8
+```
+
+### Status values
+
+| Status | Meaning |
+|---|---|
+| `up-to-date` | Locked ref matches the remote. |
+| `outdated` | A newer tag (or branch tip SHA) is available. |
+| `unknown` | The remote could not be queried, or the ref could not be resolved. |
+
+## Exit codes
+
+| Code | Condition |
+|---|---|
+| `0` | Check completed (including when outdated deps are reported). |
+| `1` | No lockfile found in the selected scope. |
+
+`apm outdated` is a reporting command. Finding outdated deps is not an error and does not change the exit code; wire `apm audit` into CI instead if you want gating.
+
+## Related
+
+- [`apm install`](../install/) -- pass `--update` to upgrade outdated deps and rewrite the lockfile.
+- [`apm view`](../view/) -- inspect a single package's metadata or available versions.
+- [`apm audit`](../audit/) -- security scan over installed primitives, suitable for CI gating.
diff --git a/docs/src/content/docs/reference/cli/pack.md b/docs/src/content/docs/reference/cli/pack.md
new file mode 100644
index 000000000..35748cdf1
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/pack.md
@@ -0,0 +1,135 @@
+---
+title: apm pack
+description: Pack distributable artifacts (plugin bundle, APM bundle, or marketplace.json) from your APM project.
+sidebar:
+  order: 17
+---
+
+## Synopsis
+
+```bash
+apm pack [OPTIONS]
+```
+
+## Description
+
+`apm pack` produces distributable artifacts from the current APM project. It reads `apm.yml` to decide what to emit:
+
+- `dependencies:` block present -> a bundle (directory or `.tar.gz`).
+- `marketplace:` block present -> `.claude-plugin/marketplace.json`.
+- Both blocks present -> both artifacts in a single run.
+
+The bundle is built from `apm.lock.yaml`. An enriched copy of the lockfile (per-file SHA-256 in `bundle_files`, plus `pack:` metadata) is embedded inside the bundle so `apm install <bundle>` can verify integrity at install time.
+
+Bundles are target-agnostic. The consumer's project decides where files land at install time -- the bundle carries no harness binding. Flags whose scope does not match the detected outputs are silent no-ops, not errors, so the same `apm pack` invocation works in CI across projects that produce only a bundle, only a marketplace, or both.
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--format plugin\|apm` | `plugin` | Bundle format. `plugin` emits a Claude Code plugin directory with `plugin.json` and plugin-native subdirs (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`). `apm` emits the legacy APM bundle layout, kept for tooling that still consumes it (e.g. `microsoft/apm-action@v1` restore mode). |
+| `--archive` | off | Produce a `.tar.gz` archive instead of a directory. Bundle only. |
+| `-o`, `--output PATH` | `./build` | Bundle output directory. Does not affect the `marketplace.json` path. |
+| `--force` | off | On collision in `plugin` format, last writer wins instead of first. Bundle only. |
+| `--dry-run` | off | Print what would be packed without writing anything. |
+| `--verbose`, `-v` | off | Show per-file paths and detailed packer output. |
+| `--offline` | off | Marketplace: resolve version ranges from cached refs only; skip `git ls-remote`. |
+| `--include-prerelease` | off | Marketplace: allow pre-release tags to satisfy version ranges. |
+| `--marketplace-output PATH` | `.claude-plugin/marketplace.json` | Marketplace: override the output path. |
+| `--legacy-skill-paths` | off | Bundle skills under per-client paths (e.g. `.cursor/skills/`) instead of the converged `.agents/skills/`. Compatibility flag. |
+| `--target`, `-t VALUE` | auto-detect | **Deprecated.** Recorded as informational `pack.target` metadata only; ignored by `apm install`. Will be removed in a future release. |
+
+## Examples
+
+### Bundle only
+
+```bash
+apm pack                              # plugin format (default), ./build/
+apm pack --archive                    # plugin bundle as .tar.gz
+apm pack --format apm -o ./dist       # legacy APM bundle layout
+```
+
+### Marketplace only
+
+```bash
+apm pack
+apm pack --offline --dry-run
+```
+
+### Both artifacts in one run
+
+```bash
+apm pack
+apm pack --archive --offline
+```
+
+### Override marketplace output path
+
+```bash
+apm pack --marketplace-output ./build/marketplace.json
+```
+
+### Preview without writing
+
+```bash
+apm pack --dry-run
+apm pack --archive --dry-run -v
+```
+
+## Output format
+
+### Plugin bundle (`--format plugin`, default)
+
+A Claude Code plugin directory under `--output`. Contains:
+
+- `plugin.json` -- schema-conformant manifest. Convention-dir keys are stripped because Claude Code auto-discovers them.
+- Plugin-native subdirs populated from your `.apm/` content and from installed dependencies: `agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`.
+- A merged `hooks.json` when multiple sources contribute hooks.
+- `apm.lock.yaml` -- enriched copy with `pack:` metadata and a `bundle_files` map of per-file SHA-256 digests, used by `apm install` for install-time integrity verification.
+- `devDependencies` are excluded.
+
+### APM bundle (`--format apm`)
+
+The legacy APM layout under `--output`. Files are copied preserving their install-time directory structure. The bundle's `apm.lock.yaml` carries the same `pack:` metadata and `bundle_files` digests. The project's own `apm.lock.yaml` is never modified.
+
+Example enriched lockfile fragment:
+
+```yaml
+pack:
+  format: apm
+  packed_at: '2026-03-09T12:00:00+00:00'
+  bundle_files:
+    .github/agents/architect.md: a1b2c3...
+lockfile_version: '1'
+generated_at: ...
+dependencies:
+  - repo_url: owner/repo
+```
+
+### Marketplace artifact
+
+`.claude-plugin/marketplace.json` (or `--marketplace-output PATH`). Each remote plugin's version range is resolved against `git ls-remote`; local-path entries pass through verbatim. The file is written atomically. `.claude-plugin/` is created if absent; nothing else is scaffolded there.
+
+## Behavior
+
+- **Lockfile-driven.** The bundle enumerates `deployed_files` from `apm.lock.yaml`. Run `apm install` first if the lockfile is stale or missing.
+- **Hidden-character scan.** Source files are scanned before bundling. Findings are reported as warnings only -- packing is non-blocking. Consumers are protected at install time, where critical findings block.
+- **Empty bundle warning.** If no files match (e.g. nothing was installed yet), `apm pack` emits a warning and exits `0` with an empty bundle. Verbose mode prints a hint to run `apm install` first.
+- **Share line.** On success, `apm pack` prints `Share with: apm install <bundle-path>` so the produced bundle is immediately copy-pasteable.
+- **Marketplace fallback.** With no `marketplace:` block in `apm.yml`, a legacy `marketplace.yml` file is read with a deprecation warning. Both files present is a hard error.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. Requested artifacts written (or, with `--dry-run`, planned). |
+| `1` | Build or runtime error: network failure, ref not found, no tag matches a marketplace range, lockfile read error, or unhandled packer exception. |
+| `2` | `apm.yml` schema validation error. |
+
+## Related
+
+- [`apm unpack`](../unpack/) -- inverse, deprecated; prefer `apm install <bundle>`.
+- [`apm install`](../install/) -- consumer side; installs a packed bundle directory or `.tar.gz`.
+- [Pack a bundle (producer guide)](../../../producer/pack-a-bundle/) -- task-oriented walkthrough.
+- [Publish to a marketplace](../../../producer/publish-to-a-marketplace/) -- end-to-end marketplace flow.
+- [Lockfile spec](../../lockfile-spec/) -- `pack:` metadata and `bundle_files` schema.
diff --git a/docs/src/content/docs/reference/cli/policy.md b/docs/src/content/docs/reference/cli/policy.md
new file mode 100644
index 000000000..393364952
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/policy.md
@@ -0,0 +1,129 @@
+---
+title: apm policy
+description: Inspect and diagnose the resolved APM organization policy
+sidebar:
+  order: 19
+---
+
+Diagnostic surface for the policy enforcement layer. Lets admins and CI
+pipelines verify what `apm-policy.yml` was discovered, how fresh the
+cache is, the resolved `extends:` chain, and the count of effective
+rules -- without running a full `apm install` or `apm audit`.
+
+## Synopsis
+
+```bash
+apm policy status [--policy-source SOURCE] [--no-cache]
+                  [-o table|json] [--json] [--check]
+```
+
+## Description
+
+`apm policy` groups diagnostic subcommands for the organization-level
+policy APM resolves at install / audit time. Today the group exposes a
+single subcommand, `status`.
+
+The command is **always exit 0 by default**. Discovery failures are
+reported in the output (table or JSON), never via process exit code, so
+it stays safe for human inspection and SIEM ingestion. Pass `--check`
+to opt into a CI-friendly contract that exits `1` when no usable policy
+is resolved.
+
+For the `apm-policy.yml` schema and enforcement model, see
+[Policy reference](../../policy-reference/).
+
+## Subcommands
+
+### `apm policy status`
+
+Render a diagnostic snapshot of the active APM policy: discovery
+outcome, source, enforcement level, cache age, resolved `extends:`
+chain, and effective rule counts.
+
+```bash
+apm policy status [OPTIONS]
+```
+
+| Flag | Description |
+|---|---|
+| `--policy-source SOURCE` | Override discovery. Accepts `org` (auto-discover from the project's git remote), `owner/repo` (defaults to github.com), an `https://` URL, or a local file path. |
+| `--no-cache` | Force a fresh fetch; skip the policy cache. |
+| `-o`, `--output {table,json}` | Output format. Default: `table`. |
+| `--json` | Emit JSON. Alias of `-o json`. |
+| `--check` | Exit `1` when no usable policy is resolved (any `outcome` other than `found`). Default exit is always `0`. |
+
+#### Output fields
+
+The table and JSON renderers expose the same fields:
+
+| Field | Meaning |
+|---|---|
+| `outcome` | Discovery result: `found`, `absent`, `disabled`, `no_git_remote`, `cache_miss_fetch_fail`, ... |
+| `source` | Resolved source label (e.g. `org:owner/repo`, `url:https://...`, `file:./path`). |
+| `enforcement` | Effective enforcement mode: `block`, `warn`, or `off`. |
+| `cache_age_human` | Age of the cached policy entry, with stale / refresh-failure context. |
+| `cache_stale`, `cached`, `cache_age_seconds` | Raw cache state (JSON only). |
+| `extends_chain` | Resolved `extends:` ancestors of the leaf policy. |
+| `rule_summary` | Human one-liners for non-empty rule axes. |
+| `rule_counts` | Per-axis integer counts. `-1` means "no opinion" (allow-list omitted); `0` means "explicitly empty". JSON only. |
+| `fetch_error`, `error` | Populated when discovery or refresh failed. |
+
+#### Exit codes
+
+| Mode | `outcome=found` | Anything else |
+|---|---|---|
+| default | `0` | `0` |
+| `--check` | `0` | `1` |
+
+To gate on rule violations rather than resolvability, use
+[`apm audit --ci`](../audit/) instead.
+
+## Examples
+
+```bash
+# Show resolved policy state for the current project
+apm policy status
+
+# Force a fresh fetch (bypass cache)
+apm policy status --no-cache
+
+# Machine-readable JSON for SIEM or CI inspection
+apm policy status --json
+
+# Inspect a draft policy without committing it
+apm policy status --policy-source ./draft-policy.yml
+
+# Inspect an explicit org policy by repo
+apm policy status --policy-source acme-corp/apm-policies
+
+# CI pre-check: fail the job when no usable policy is resolved
+apm policy status --check
+```
+
+Sample table output:
+
+```
+APM Policy Status
+-----------------
+  Outcome          found
+  Source           org:acme-corp/apm-policies
+  Enforcement      block
+  Cache age        4m ago
+  Extends chain    acme-corp/apm-baseline
+  Effective rules  3 dependency denies; 2 mcp denies; 1 required manifest fields
+```
+
+## Related
+
+- [`apm install`](../install/) -- enforces policy during dependency
+  resolution; honors `--no-policy` to bypass.
+- [`apm audit`](../audit/) -- gate on rule violations with `--ci`;
+  complements `apm policy status --check`.
+- [Policy reference](../../policy-reference/) -- canonical
+  `apm-policy.yml` schema and enforcement semantics.
+- [Governance overview](../../../enterprise/governance-overview/) --
+  how policy fits the broader enterprise governance model.
+- [APM policy: getting started](../../../enterprise/apm-policy-getting-started/)
+  -- author and publish your first `apm-policy.yml`.
+- [Enforce in CI](../../../enterprise/enforce-in-ci/) -- wire `audit`
+  and `policy status` into pipelines.
diff --git a/docs/src/content/docs/reference/cli/preview.md b/docs/src/content/docs/reference/cli/preview.md
new file mode 100644
index 000000000..d5a646e06
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/preview.md
@@ -0,0 +1,81 @@
+---
+title: apm preview
+description: Show a script's compiled prompt and final command without executing it.
+sidebar:
+  order: 13
+---
+
+## Synopsis
+
+```bash
+apm preview [SCRIPT_NAME] [OPTIONS]
+```
+
+## Description
+
+`apm preview` resolves a script defined in the `scripts:` section of `apm.yml`, compiles any `.prompt.md` files referenced by its command, and prints both the original command and the compiled command without running the runtime. Use it to verify parameter substitution, frontmatter handling, and the resulting argv before you spend tokens on `apm run`.
+
+If `SCRIPT_NAME` is omitted, `apm preview` falls back to the `start` script. If no script name is given and no `start` entry exists in `apm.yml`, the command exits `1`.
+
+Only files whose name ends in `.prompt.md` are compiled. Any other path in the script command is shown as-is and a warning notes that no compilation occurred.
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--param`, `-p NAME=VALUE` | none | Parameter to substitute into the prompt. Repeatable. Values lacking `=` are silently ignored. |
+| `--verbose`, `-v` | off | Print each parsed parameter and extra diagnostic context. |
+
+## Arguments
+
+| Argument | Required | Description |
+|---|---|---|
+| `SCRIPT_NAME` | no | Name of a script defined under `scripts:` in `apm.yml`. Defaults to `start` when omitted. |
+
+## Behavior
+
+- **Compilation target.** Compiled prompts are written to `.apm/compiled/<basename>.txt` (the `.prompt.md` suffix is stripped). The same files would be produced by `apm run`.
+- **Output panels.** When the rich renderer is available, `apm preview` prints three panels: the original command, the compiled command, and the list of compiled prompt file paths. With no `.prompt.md` in the command, it prints a single yellow panel and a warning instead.
+- **No runtime invocation.** The script's runtime (`codex`, `llm`, `claude`, etc.) is never spawned. Preview only resolves and compiles; it does not execute.
+- **Parameter parsing.** `--param foo=bar` becomes `{foo: "bar"}` and is passed to the prompt compiler. The first `=` splits the key from the value; later `=` characters stay in the value. A `--param` with no `=` is dropped.
+
+## Examples
+
+### Preview the default `start` script
+
+```bash
+apm preview
+```
+
+### Preview a named script
+
+```bash
+apm preview llm
+```
+
+### Substitute parameters
+
+```bash
+apm preview start --param name=Alice
+apm preview review -p reviewer=Bob -p depth=full
+```
+
+### See parsed params and full diagnostics
+
+```bash
+apm preview start -p name=Alice --verbose
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Preview rendered successfully. |
+| `1` | No script name given and no `start` script defined, the named script is not in `apm.yml`, or an unhandled error occurred during compilation. |
+
+## Related
+
+- [`apm run`](../run/) -- execute the same script after previewing.
+- [`apm list`](../list/) -- list every script defined in `apm.yml`.
+- [`apm compile`](../compile/) -- compile primitives into `AGENTS.md` and harness files (different surface from script-prompt compilation).
+- [Manifest schema](../../manifest-schema/) -- field reference for `scripts:` in `apm.yml`.
diff --git a/docs/src/content/docs/reference/cli/prune.md b/docs/src/content/docs/reference/cli/prune.md
new file mode 100644
index 000000000..23ebf3191
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/prune.md
@@ -0,0 +1,90 @@
+---
+title: apm prune
+description: Remove orphaned packages no longer referenced in apm.yml
+sidebar:
+  order: 7
+---
+
+Remove installed packages from `apm_modules/` that are no longer declared in `apm.yml`, along with their deployed integration files. Updates `apm.lock.yaml` to match.
+
+## Synopsis
+
+```bash
+apm prune [--dry-run]
+```
+
+:::note[Coming from npm?]
+`apm prune` mirrors `npm prune`: it removes installed packages that are not in your manifest. Unlike npm, it also removes the harness-deployed files those packages produced (prompts, agents, hooks, MCP wiring) and rewrites the lockfile.
+:::
+
+## Description
+
+`apm prune` reconciles three states:
+
+1. Packages declared in `apm.yml`
+2. Packages installed under `apm_modules/`
+3. Packages recorded in `apm.lock.yaml` with their `deployed_files`
+
+Anything installed but no longer declared is **orphaned**. `apm prune` removes the orphan's directory under `apm_modules/`, deletes every file the orphan deployed into your harness directories (using the `deployed_files` manifest in the lockfile), removes the entry from `apm.lock.yaml`, and cleans up empty parent directories.
+
+If `apm_modules/` does not exist, the command exits cleanly with nothing to do. If `apm.yml` is missing, it exits with an error.
+
+## Options
+
+| Option      | Description                                       |
+|-------------|---------------------------------------------------|
+| `--dry-run` | List orphaned packages without removing anything. |
+
+## Examples
+
+Remove orphaned packages:
+
+```bash
+apm prune
+```
+
+Preview what would be removed:
+
+```bash
+apm prune --dry-run
+```
+
+Typical workflow after editing `apm.yml`:
+
+```bash
+# Remove a dependency from apm.yml, then:
+apm install   # installs the new state
+apm prune     # cleans up what is no longer declared
+```
+
+## Behavior
+
+For each orphaned package, `apm prune`:
+
+1. Removes the package directory from `apm_modules/<owner>/<repo>` using a path-traversal-safe delete.
+2. Reads `deployed_files` from the lockfile entry and deletes each deployed file or directory inside the project root.
+3. Removes the entry from `apm.lock.yaml`.
+4. Cleans up empty parent directories under both `apm_modules/` and the harness deploy roots.
+5. Deletes `apm.lock.yaml` if pruning leaves it with zero dependencies.
+
+Notes:
+
+- Packages that share an install root with a still-declared sibling subdirectory dependency are not falsely protected by ancestor expansion. The check uses lockfile membership (with `apm.yml` fallback) to identify genuine standalone packages.
+- Deploy paths are validated before deletion; entries that escape the project root are skipped.
+- The command does not network. It only inspects local state.
+
+## Exit codes
+
+| Code | Meaning                                               |
+|------|-------------------------------------------------------|
+| 0    | Prune completed (including "nothing to prune").       |
+| 1    | `apm.yml` missing, parse failure, or unhandled error. |
+
+Per-package removal failures are logged but do not abort the run; remaining orphans still process.
+
+## Related
+
+- [`apm install`](../install/) -- install declared dependencies
+- [`apm list`](../list/) -- inspect what is installed
+- [Lockfile spec](../../lockfile-spec/) -- `deployed_files` schema
+- [Package anatomy](../../../concepts/package-anatomy/) -- what gets deployed where
diff --git a/docs/src/content/docs/reference/cli/run.md b/docs/src/content/docs/reference/cli/run.md
new file mode 100644
index 000000000..8e2c4335a
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/run.md
@@ -0,0 +1,117 @@
+---
+title: apm run
+description: Execute a script defined in apm.yml
+sidebar:
+  order: 12
+---
+
+Execute a script defined in the `scripts:` section of `apm.yml`. Modeled on `npm run`: script bodies are shell commands, typically a prompt piped to a runtime CLI (Copilot, Claude, Codex, llm, etc.).
+
+:::caution[Experimental]
+The `run` command surface is marked experimental. Flags and behavior may change before 1.0.
+:::
+
+## Synopsis
+
+```bash
+apm run [SCRIPT_NAME] [OPTIONS]
+```
+
+If `SCRIPT_NAME` is omitted, APM runs the `start` script. If no `start` script is defined, APM exits non-zero and prints the available scripts.
+
+## Description
+
+`apm run` resolves `SCRIPT_NAME` against `apm.yml` `scripts:` and executes the matching shell command. Before execution, APM auto-compiles any `.prompt.md` file referenced in the command, substituting `${input:name}` placeholders with values from `--param`. Compiled output is written to `.apm/compiled/<name>.txt` and the final command is executed in the current shell.
+
+If `SCRIPT_NAME` does not match a script, APM falls back to:
+
+1. Auto-discovering a matching prompt file in `.apm/prompts/`, `.github/prompts/`, or the project root.
+2. Auto-installing a virtual package reference (e.g., `owner/repo/path/to/prompt`) and re-running the discovery step.
+
+If none of these resolve, the command exits non-zero with an error listing the available scripts.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-p, --param NAME=VALUE` | Set a parameter for prompt compilation. Repeat for multiple parameters. |
+| `-v, --verbose` | Show detailed compilation and execution output. |
+| `--help` | Show help for the command. |
+
+## Examples
+
+Define scripts in `apm.yml` (npm-style):
+
+```yaml
+name: hello-world-agent
+version: 0.0.1
+
+scripts:
+  start: copilot -p hello-world.prompt.md --allow-all-tools
+  claude: claude -p hello-world.prompt.md
+  codex: codex exec --skip-git-repo-check hello-world.prompt.md
+  llm: llm < hello-world.prompt.md
+
+dependencies:
+  apm:
+    - dmeppiel/hello-world
+```
+
+Run the default `start` script:
+
+```bash
+apm run
+```
+
+Run a named script:
+
+```bash
+apm run claude
+apm run codex
+```
+
+Pass parameters that get substituted into `${input:name}` placeholders inside `.prompt.md` files:
+
+```bash
+apm run start --param name="Alice"
+apm run llm --param service=api --param environment=prod
+```
+
+List available scripts (no script defined and no `start`):
+
+```bash
+$ apm run
+[x] No script specified and no 'start' script defined in apm.yml
+[>] Available scripts:
+   claude   claude -p hello-world.prompt.md
+   codex    codex exec --skip-git-repo-check hello-world.prompt.md
+   llm      llm < hello-world.prompt.md
+```
+
+## Argument forwarding
+
+`apm run` does not forward extra positional arguments to the underlying script (there is no `--` passthrough). To parameterize a script, use `--param NAME=VALUE` and reference the value inside your `.prompt.md` file:
+
+```markdown
+Hello, ${input:name}. Today's target service is ${input:service}.
+```
+
+Then run:
+
+```bash
+apm run start --param name="Alice" --param service=api
+```
+
+Anything beyond `--param`-style substitution belongs in the script body itself, which is plain shell.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Script executed successfully. |
+| `1` | Script failed, was not found, or no `start` script is defined when invoked without arguments. |
+
+## Related
+
+- [`apm list`](../list/) -- show installed primitives and available scripts.
+- [`apm preview`](../preview/) -- render the compiled command and prompt files without executing.
diff --git a/docs/src/content/docs/reference/cli/runtime.md b/docs/src/content/docs/reference/cli/runtime.md
new file mode 100644
index 000000000..87097ce81
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/runtime.md
@@ -0,0 +1,117 @@
+---
+title: apm runtime
+description: Manage AI runtime CLIs (Copilot, Codex, LLM, Gemini) that execute APM scripts.
+sidebar:
+  order: 16
+---
+
+:::caution[Experimental]
+`apm runtime` is experimental. Subcommand names, flags, and the supported runtime list may change.
+:::
+
+## Synopsis
+
+```bash
+apm runtime COMMAND [ARGS] [OPTIONS]
+```
+
+## Description
+
+`apm runtime` manages the AI CLI binaries that execute the scripts declared in `apm.yml`. It installs them from official sources, records their location, and reports which one `apm run` will pick.
+
+It does not install APM packages and does not deploy primitives. For that, see [`apm install`](../install/). For the `scripts:` block these runtimes execute, see the [quickstart](../../../quickstart/).
+
+A runtime here is the AI CLI itself (`copilot`, `codex`, `llm`, `gemini`) -- the program that consumes the prompts and skills APM deploys. For the broader concept of harness targets that receive primitives, see [Primitives and targets](../../../concepts/primitives-and-targets/).
+
+## Subcommands
+
+| Command | Purpose |
+|---|---|
+| `setup RUNTIME` | Download and configure an AI runtime CLI. |
+| `list` | List all known runtimes and their installation status. |
+| `status` | Print the active runtime and the preference order `apm run` uses. |
+| `remove RUNTIME` | Uninstall a runtime previously set up by APM. |
+
+`RUNTIME` is one of: `copilot`, `codex`, `llm`, `gemini`.
+
+### `apm runtime setup`
+
+```bash
+apm runtime setup RUNTIME [--version VERSION] [--vanilla]
+```
+
+Downloads the runtime binary from its official source and writes a default APM configuration that points at GitHub Models (free) where applicable. On Windows, setup scripts run through PowerShell automatically.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--version VERSION` | latest | Pin a specific upstream version. |
+| `--vanilla` | off | Install the binary only. Skip APM-managed config; use the runtime's native defaults (e.g. OpenAI for Codex). |
+
+### `apm runtime list`
+
+```bash
+apm runtime list
+```
+
+Prints a table of every supported runtime with its installation status, install path, and detected version.
+
+### `apm runtime status`
+
+```bash
+apm runtime status
+```
+
+Prints the runtime preference order (`copilot -> codex -> gemini -> llm`) and the first runtime in that order that is currently installed. `apm run` uses this resolution to choose which CLI executes a script.
+
+### `apm runtime remove`
+
+```bash
+apm runtime remove RUNTIME [-y]
+```
+
+Removes a runtime installed by `apm runtime setup`. Prompts for confirmation unless `-y` / `--yes` is passed. Does not touch runtimes installed outside APM.
+
+## Examples
+
+```bash
+# Install Copilot CLI with APM defaults
+apm runtime setup copilot
+
+# Install Codex pinned to a specific version
+apm runtime setup codex --version 0.20.0
+
+# Install LLM with no APM-managed config
+apm runtime setup llm --vanilla
+
+# See what is installed and which one apm run will pick
+apm runtime list
+apm runtime status
+
+# Uninstall without prompting
+apm runtime remove gemini -y
+```
+
+## Supported runtimes
+
+| Runtime | Description | Default config |
+|---|---|---|
+| `copilot` | GitHub Copilot CLI. | GitHub Models (free). |
+| `codex` | OpenAI Codex CLI. | GitHub Models via global `~/.codex/config.toml`. |
+| `llm` | Simon Willison's `llm` CLI with multiple providers. | GitHub Models. |
+| `gemini` | Google Gemini CLI. | Native defaults. |
+
+`--vanilla` skips the APM defaults column for any runtime and leaves the CLI configured as upstream ships it.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. |
+| `1` | Setup, removal, listing, or status failed. The error message names the cause. |
+
+## Related
+
+- [`apm install`](../install/) -- install APM packages and deploy primitives to harness targets.
+- [`apm run`](../run/) -- execute a script from `apm.yml` using the active runtime.
+- [Quickstart](../../../quickstart/) -- end-to-end first run including `apm runtime setup`.
+- [Primitives and targets](../../../concepts/primitives-and-targets/) -- how harnesses consume the primitives APM deploys.
diff --git a/docs/src/content/docs/reference/cli/search.md b/docs/src/content/docs/reference/cli/search.md
new file mode 100644
index 000000000..6aecc616b
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/search.md
@@ -0,0 +1,72 @@
+---
+title: apm search
+description: Search a registered marketplace for plugins by query
+sidebar:
+  order: 21
+---
+
+Find plugins in a registered marketplace by name or keyword.
+
+## Synopsis
+
+```bash
+apm search QUERY@MARKETPLACE [OPTIONS]
+```
+
+`apm search` is a top-level alias for [`apm marketplace search`](../marketplace/). Both commands invoke the same implementation and accept identical arguments and options.
+
+## Description
+
+`apm search` queries a single marketplace registered in the local marketplace registry and returns plugins whose name or description matches `QUERY`. The `QUERY@MARKETPLACE` expression is required: the marketplace name disambiguates which registered source to search, and prevents accidental wide scans across every marketplace.
+
+The marketplace must be registered first with `apm marketplace add`. To list registered marketplaces, run `apm marketplace list`. To browse every plugin in a marketplace without filtering, use `apm marketplace browse <name>`.
+
+Results print as a table with plugin name, description, and the install expression. Pipe the install expression directly into [`apm install`](../install/) to add a hit to your manifest.
+
+## Arguments
+
+| Argument              | Required | Description                                                          |
+| --------------------- | -------- | -------------------------------------------------------------------- |
+| `QUERY@MARKETPLACE`   | yes      | Search term and registered marketplace name, joined with `@`         |
+
+The expression is split on the last `@`, so queries containing `@` are preserved on the left side.
+
+## Options
+
+| Option              | Default | Description                          |
+| ------------------- | ------- | ------------------------------------ |
+| `--limit N`         | `20`    | Maximum number of results to display |
+| `-v`, `--verbose`   |         | Show detailed output and tracebacks  |
+
+## Examples
+
+Search the `skills` marketplace for security-related plugins:
+
+```bash
+apm search security@skills
+```
+
+Limit results to the top five matches:
+
+```bash
+apm search auth@skills --limit 5
+```
+
+Install a result returned by `search`:
+
+```bash
+apm install code-review@skills
+```
+
+## Exit codes
+
+| Code | Meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| `0`  | Search completed (including zero matches)                               |
+| `1`  | Invalid expression, marketplace not registered, or unexpected error     |
+
+## Related
+
+- [`apm marketplace`](../marketplace/) -- full marketplace command group (`add`, `list`, `browse`, `refresh`, `remove`, `search`)
+- [`apm install`](../install/) -- install a plugin returned by search
+- [Use marketplaces](../../../consumer/use-marketplaces/) -- consumer guide for registering and consuming marketplaces
diff --git a/docs/src/content/docs/reference/cli/self-update.md b/docs/src/content/docs/reference/cli/self-update.md
new file mode 100644
index 000000000..f2dc42517
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/self-update.md
@@ -0,0 +1,103 @@
+---
+title: apm self-update
+description: Self-update the APM CLI binary to the latest GitHub release.
+sidebar:
+  order: 5
+---
+
+Self-update the APM CLI binary to the latest GitHub release.
+
+## Synopsis
+
+```bash
+apm self-update [--check]
+```
+
+## Description
+
+`apm self-update` upgrades the **APM CLI itself** to the latest version published on GitHub releases. It downloads the official platform installer (`install.sh` on macOS/Linux, `install.ps1` on Windows) and runs it in place.
+
+:::caution[Looking for dependency updates?]
+This command does **not** update the packages declared in your `apm.yml`. To re-resolve your dependencies against the latest matching Git refs, run:
+
+```bash
+apm update
+```
+
+See [`apm update`](../update/) for the dependency refresh workflow, or [`apm install --frozen`](../install/) for a read-only, lockfile-pinned install.
+:::
+
+The command compares the installed version against the latest GitHub release and exits early if you are already current. With `--check`, it reports availability without installing.
+
+:::note
+Some package-manager distributions (for example, Homebrew) disable self-update at build time. In those builds, `apm self-update` prints a distributor-defined message (such as `brew upgrade apm`) and exits without running the installer. The startup update notification is also suppressed in those builds.
+:::
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `--check` | Only check whether a newer release exists. Print the result and exit without installing. |
+
+## Examples
+
+Check for an available update:
+
+```bash
+apm self-update --check
+```
+
+Install the latest release:
+
+```bash
+apm self-update
+```
+
+## Behavior
+
+**Version check.** Fetches the latest release tag from GitHub and compares it to `apm --version`. If the installed version is current, the command exits with a success message and does nothing else.
+
+**Download.** When an update is available (and `--check` is not set), the platform installer is downloaded into APM's temp directory, made executable, and invoked as a subprocess. The installer's stdout and stderr stream directly to your terminal so it can prompt for elevation when needed.
+
+## Where the new binary lands
+
+The installer writes the binary to the same location the original install script used -- typically `~/.apm/bin/apm` on macOS/Linux and `%LOCALAPPDATA%\Programs\apm\apm.exe` on Windows. Existing configuration under `~/.apm/` and your project files are untouched.
+
+## After update
+
+Restart your terminal (or re-resolve `apm` on `PATH`) and run `apm --version` to confirm the new version is active.
+
+## Rollback
+
+APM does not keep previous binaries. To roll back, reinstall a specific version using the manual installer:
+
+```bash
+# macOS / Linux
+curl -sSL https://aka.ms/apm-unix | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy Bypass -c "irm https://aka.ms/apm-windows | iex"
+```
+
+The installer scripts accept a version pin via environment variable -- see [Quickstart](../../../quickstart/).
+
+## Failure modes
+
+If GitHub is unreachable, the download fails, or the installer exits non-zero, `apm self-update` exits with code `1` and prints the manual update command. Your existing binary is unaffected.
+
+## Startup update notification
+
+APM checks for new releases at most once per day during normal command execution. When a newer version is available, you see:
+
+```
+A new version of APM is available: 0.7.0 (current: 0.6.3)
+Run apm self-update to upgrade
+```
+
+The check is cached and non-blocking. It is suppressed in distributions that disable self-update.
+
+## Related
+
+- [`apm update`](../update/) -- refresh dependencies declared in `apm.yml` against the latest matching refs.
+- [`apm install`](../install/) -- install dependencies; use `--frozen` for read-only, lockfile-pinned installs.
+- [Quickstart](../../../quickstart/) -- first-time install.
diff --git a/docs/src/content/docs/reference/cli/targets.md b/docs/src/content/docs/reference/cli/targets.md
new file mode 100644
index 000000000..5ce1bc0d0
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/targets.md
@@ -0,0 +1,125 @@
+---
+title: apm targets
+description: Show and inspect resolved deployment targets for the current project
+sidebar:
+  order: 15
+---
+
+Show which agent harnesses APM will deploy to from the current project,
+and why.
+
+## Synopsis
+
+```bash
+apm targets [OPTIONS]
+```
+
+## Description
+
+`apm targets` prints the canonical target table for the current
+directory: every supported harness, whether APM considers it active,
+the filesystem signal that activated it, and where compiled output
+will land.
+
+Resolution order matches `apm compile`:
+
+1. `--target` / `--all` on the command line (not applicable to
+   `apm targets` itself, but reflected by `compile` and `install`).
+2. `targets:` field in `apm.yml`.
+3. Auto-detection via filesystem signals (see [Detection signals](#detection-signals)).
+
+Use this command before `apm compile` or `apm install` to confirm
+what auto-detection resolves to. If APM lists a target you do not
+intend (for example, `CLAUDE.md` is project documentation, not a
+Claude Code config), pin `targets:` explicitly in `apm.yml`.
+
+## Subcommands
+
+`apm targets` is a Click command group, but no subcommands ship today.
+Invoking `apm targets` without arguments prints the resolved-target
+table.
+
+:::note[Planned]
+Subcommands such as `apm targets add` are reserved on the group for
+future use. They are not implemented yet.
+:::
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit machine-readable JSON instead of the table. One object per canonical target with `target`, `status`, `source`, `deploy_dir`, `needs`. |
+| `--all` | In `--json` mode, include the `agent-skills` meta-target row (excluded by default). No effect on table output. |
+
+The `agent-skills` meta-target is a multi-harness fan-out for shared
+`.agents/skills/` output. It is not a harness and is excluded from the
+default table.
+
+## Examples
+
+Show the resolved target table:
+
+```bash
+apm targets
+```
+
+Sample output in a project with `CLAUDE.md` and `.cursor/`:
+
+```
+  TARGET       STATUS     SOURCE                                   DEPLOY DIR
+  ------------ ---------- ---------------------------------------- ----------
+  claude       active     CLAUDE.md                                .claude/
+  copilot      inactive   needs .github/copilot-instructions.md    .github/
+  cursor       active     .cursor/                                 .cursor/
+  codex        inactive   needs .codex/                            .codex/
+  gemini       inactive   needs GEMINI.md                          .gemini/
+  opencode     inactive   needs .opencode/                         .opencode/
+  windsurf     inactive   needs .windsurf/                         .windsurf/
+```
+
+Machine-readable form:
+
+```bash
+apm targets --json
+apm targets --json --all
+```
+
+## Detection signals
+
+Auto-detection walks the project root for these markers. The first
+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/` |
+| `cursor` | `.cursor/` directory, or `.cursorrules` file (legacy) | `.cursor/` |
+| `codex` | `.codex/` directory | `.codex/` |
+| `gemini` | `.gemini/` directory, or `GEMINI.md` file | `.gemini/` |
+| `opencode` | `.opencode/` directory | `.opencode/` |
+| `windsurf` | `.windsurf/` directory | `.windsurf/` |
+| `agent-skills` | Meta-target; never auto-detected. Opt in via `targets:` in `apm.yml` or `--target agent-skills` on `apm compile`. | `.agents/skills/` |
+
+Notes:
+
+- Detection is filesystem-only. APM does not inspect file contents to
+  decide whether a marker is "real".
+- 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:`,
+  `apm targets` prints the full table with every row inactive and an
+  info hint to create a harness config or declare `targets:`
+  explicitly.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Table or JSON printed (including the all-inactive case). |
+
+## Related
+
+- [`apm install`](../install/) -- uses the same target resolution to decide which harness configs to wire.
+- [`apm compile`](../compile/) -- compiles primitives for the targets shown here.
+- [Targets matrix](../../targets-matrix/) -- per-target output layout and feature support.
+- [Concepts: primitives and targets](../../../concepts/primitives-and-targets/)
diff --git a/docs/src/content/docs/reference/cli/uninstall.md b/docs/src/content/docs/reference/cli/uninstall.md
new file mode 100644
index 000000000..82fb09055
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/uninstall.md
@@ -0,0 +1,90 @@
+---
+title: apm uninstall
+description: Remove an APM package from the project
+sidebar:
+  order: 3
+---
+
+Remove one or more APM packages from `apm.yml`, the lockfile, `apm_modules/`, and every deployed primitive across all configured harnesses.
+
+## Synopsis
+
+```bash
+apm uninstall [OPTIONS] PACKAGES...
+```
+
+## Description
+
+`apm uninstall` is the inverse of `apm install <package>`. It strips a package from the manifest, deletes its source from `apm_modules/`, prunes any transitive dependencies that nothing else depends on, and removes every file the package deployed into harness folders (Copilot, Claude, Cursor, Codex, Gemini, OpenCode, Windsurf).
+
+The command only deletes files tracked in the lockfile's `deployed_files` manifest, so hand-authored content in the same harness folders is left alone.
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `PACKAGES...` | One or more packages to remove. Accepts shorthand (`owner/repo`), HTTPS URL, SSH URL, or FQDN. APM resolves each to the canonical identity stored in `apm.yml`. Required. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Show what would be removed without touching disk. |
+| `-v, --verbose` | Show detailed removal information. |
+| `-g, --global` | Remove from the user scope (`~/.apm/`) instead of the current project. |
+
+## Examples
+
+Remove one package:
+
+```bash
+apm uninstall acme/my-package
+```
+
+Remove several at once:
+
+```bash
+apm uninstall org/pkg1 org/pkg2
+```
+
+Preview the removal without writing to disk:
+
+```bash
+apm uninstall acme/my-package --dry-run
+```
+
+Remove from the user scope:
+
+```bash
+apm uninstall -g acme/my-package
+```
+
+Resolve via URL (same identity as the shorthand):
+
+```bash
+apm uninstall https://github.com/acme/my-package.git
+```
+
+## Behavior
+
+What gets removed, in order:
+
+1. The package entry in `apm.yml` under `dependencies.apm`.
+2. The package folder under `apm_modules/owner/repo/`.
+3. Transitive dependencies that no remaining package depends on (npm-style pruning, computed from `apm.lock.yaml`).
+4. Every file in the lockfile's `deployed_files` for the removed packages and pruned orphans, across all harness folders (`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.gemini/`, `.codex/`, `.windsurf/`).
+5. Hook entries inside `.claude/settings.json`, `.cursor/hooks.json`, and `.gemini/settings.json` that the removed packages contributed.
+6. MCP servers contributed only by the removed packages.
+7. The lockfile entries themselves. If no dependencies remain, `apm.lock.yaml` is deleted.
+8. Empty parent directories left behind by the cleanup.
+
+If a name passed on the command line is not found in `apm.yml`, the command warns and continues with the rest. If none of the names match, it exits without changes.
+
+`--dry-run` runs steps 1-3 in memory and prints the plan; nothing is written.
+
+## Related
+
+- [`apm install`](../install/) -- the inverse operation.
+- [`apm prune`](../prune/) -- remove orphaned packages without naming them.
+- [`apm list`](../list/) -- see what is currently installed.
+- [Lockfile spec](../../lockfile-spec/) -- how `deployed_files` drives safe cleanup.
diff --git a/docs/src/content/docs/reference/cli/unpack.md b/docs/src/content/docs/reference/cli/unpack.md
new file mode 100644
index 000000000..2b8c009d6
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/unpack.md
@@ -0,0 +1,84 @@
+---
+title: apm unpack
+description: Extract an APM bundle into a project directory with verification and security scanning.
+sidebar:
+  order: 18
+---
+
+:::caution[Deprecated]
+`apm unpack` is deprecated and scheduled for removal in v0.14. For plugin-format bundles, prefer [`apm install <bundle-path>`](../install/) -- it shares the same air-gapped path, integrates with target resolution, and records deployed files in the project lockfile. `apm unpack` remains the only deploy path for legacy `--format apm` tarballs (see [Behavior](#behavior)).
+:::
+
+## Synopsis
+
+```bash
+apm unpack BUNDLE_PATH [OPTIONS]
+```
+
+## Description
+
+`apm unpack` extracts an APM bundle (a `.tar.gz` archive or an already-unpacked bundle directory) into a target project. It runs the built-in security scan against the bundle contents before writing any files, and -- unless `--skip-verify` is set -- checks that every entry in the bundle's `apm.lock.yaml` `deployed_files` list is actually present in the archive.
+
+Extraction is **additive-only**: only files listed in the bundle's lockfile are written. Existing project files at colliding paths are overwritten by the bundle version. Files outside the bundle's manifest are never touched, and the bundle's `apm.lock.yaml` is treated as metadata -- it is not copied into the output directory.
+
+`BUNDLE_PATH` accepts either a `.tar.gz` archive produced by [`apm pack`](../pack/) or the directory form of an unpacked bundle.
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `-o`, `--output PATH` | `.` | Target project directory. Created if it does not exist. |
+| `--skip-verify` | off | Skip the bundle completeness check against the bundle's `apm.lock.yaml`. Useful for partial bundles. |
+| `--dry-run` | off | List files that would be unpacked without writing anything. |
+| `--force` | off | Deploy despite critical hidden-character findings from the security scan. Use only after independent verification. |
+| `--verbose`, `-v` | off | Show per-file paths and full diagnostic context. |
+
+## Examples
+
+Unpack an archive into the current directory:
+
+```bash
+apm unpack ./build/my-pkg-1.0.0.tar.gz
+```
+
+Unpack into a specific project directory:
+
+```bash
+apm unpack bundle.tar.gz --output /path/to/project
+```
+
+Preview the extraction plan without writing files:
+
+```bash
+apm unpack bundle.tar.gz --dry-run
+```
+
+Skip verification when working with a partial bundle:
+
+```bash
+apm unpack bundle.tar.gz --skip-verify
+```
+
+Override a critical hidden-character finding after manual review:
+
+```bash
+apm unpack bundle.tar.gz --force
+```
+
+## Behavior
+
+- **Bundle formats.** `apm install` deploys only plugin-format bundles. Legacy `--format apm` tarballs (whole-project bundles produced by older `apm pack` invocations) are deployed via `apm unpack` and have no equivalent `install` path.
+- **Additive writes only.** Files not listed in the bundle's lockfile are left alone; the bundle never deletes project files.
+- **Overwrite on collision.** When a bundle file shares a path with a local file, the bundle file wins.
+- **Security scan.** Bundle contents are scanned before deployment. Critical hidden-character findings block extraction unless `--force` is passed (exit code `1`). Non-critical warnings are surfaced with a hint to run [`apm audit`](../audit/).
+- **Verification.** By default, every entry in the bundle's `deployed_files` must exist inside the archive. `--skip-verify` disables this check; missing files are then reported as skipped.
+- **Target mismatch warning.** If the bundle was packed for a different harness target than the output project's detected target, `apm unpack` warns and -- with `--verbose` -- suggests the `apm pack --target` command the publisher should run.
+- **Lockfile is metadata.** The bundle's `apm.lock.yaml` is read for verification and target metadata but is never written to the output directory.
+- **Exit codes.** `0` on success (including `--dry-run`); `1` on missing bundle, invalid bundle, or critical security findings without `--force`.
+
+## Related
+
+- [`apm pack`](../pack/) -- produce the bundles that `apm unpack` extracts.
+- [`apm install`](../install/) -- the preferred deploy path for plugin-format bundles.
+- [`apm audit`](../audit/) -- inspect hidden-character findings flagged during extraction.
+- [Pack a bundle](../../../producer/pack-a-bundle/) -- producer guide covering bundle formats and distribution.
diff --git a/docs/src/content/docs/reference/cli/update.md b/docs/src/content/docs/reference/cli/update.md
new file mode 100644
index 000000000..48f02c1f3
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/update.md
@@ -0,0 +1,89 @@
+---
+title: apm update
+description: Re-resolve dependencies in apm.yml against the latest matching Git refs, with a plan and consent gate before writing the lockfile.
+sidebar:
+  order: 4
+---
+
+Refresh the dependencies declared in `apm.yml` to the latest matching Git refs, after showing you the plan and asking for consent.
+
+## Synopsis
+
+```bash
+apm update [OPTIONS]
+```
+
+## Description
+
+`apm update` re-resolves every dependency in your project's `apm.yml` against the newest Git ref allowed by its constraint, prints a structured plan -- **added**, **updated**, **removed**, **unchanged** -- and prompts before touching anything. Decline the prompt and APM exits cleanly: no lockfile writes, no filesystem changes.
+
+This is the dependency-refresh command. To upgrade the APM CLI binary itself, see [`apm self-update`](../self-update/).
+
+:::note[Consent gate]
+The interactive prompt defaults to **No**. In non-interactive contexts (CI, piped stdin) you must pass `--yes` to proceed; otherwise `apm update` aborts without modifying the lockfile.
+:::
+
+For a read-only install that pins to whatever is already in `apm.lock.yaml` -- the right command for CI -- use [`apm install --frozen`](../install/).
+
+## Options
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--yes`, `-y` | off | Skip the interactive prompt and accept the plan. Required for non-interactive use. |
+| `--dry-run` | off | Compute and print the plan without prompting and without writing the lockfile or filesystem. |
+| `--verbose`, `-v` | off | Show per-dependency resolution detail (old ref, new ref, source) and full error context. |
+
+## Examples
+
+Preview what would change, without prompting or writing:
+
+```bash
+apm update --dry-run
+```
+
+Interactively review and accept the plan:
+
+```bash
+apm update
+# prints plan, prompts: Apply these updates? [y/N]
+```
+
+Accept non-interactively (CI, scripts):
+
+```bash
+apm update --yes
+```
+
+Decline the prompt -- nothing is written:
+
+```bash
+apm update
+# Apply these updates? [y/N] n
+# Aborted. apm.lock.yaml unchanged.
+```
+
+## Behavior
+
+- **Re-resolve every dep.** Each entry in `apm.yml` is resolved against its remote source for the newest ref allowed by the constraint (branch tip, latest matching tag, etc.). Local-path deps are skipped.
+- **Structured plan.** Output is grouped into four sections:
+  - **added** -- present in the new resolution but not in the previous lockfile.
+  - **updated** -- ref or version moved.
+  - **removed** -- previously locked, no longer required by `apm.yml`.
+  - **unchanged** -- already at the latest matching ref.
+- **Consent gate.** The prompt defaults to **No**. Without `--yes`, declining (or running in a non-interactive context) aborts with a clean exit; the lockfile and workspace are untouched.
+- **No partial writes.** The plan is applied atomically: either the new `apm.lock.yaml` is written and `apm install` is invoked to materialize the result, or nothing changes.
+- **`--dry-run` skips the prompt.** It only computes and prints the plan; it never writes and never asks.
+
+## Back-compat: `apm update` used to be the self-updater
+
+In earlier releases, `apm update` self-updated the **APM CLI binary**. That behavior moved to [`apm self-update`](../self-update/) and `apm update` was repurposed as the dependency updater described above.
+
+For one release after the rename, running `apm update` from a directory **without an `apm.yml`** prints a deprecation banner and forwards to `apm self-update` so existing muscle memory and scripts keep working. This shim is removed in the next minor release -- update your scripts to call `apm self-update` directly.
+
+## Related
+
+- [`apm install --frozen`](../install/) -- read-only install pinned to `apm.lock.yaml`; fails on drift. Use this in CI.
+- [`apm self-update`](../self-update/) -- upgrade the APM CLI binary itself.
+- [`apm outdated`](../outdated/) -- report dependencies with newer refs available, without changing anything.
+- [Manage dependencies (consumer guide)](../../../consumer/manage-dependencies/) -- task-oriented walkthrough.
+- [Update and refresh](../../../consumer/update-and-refresh/) -- when to use `update`, `install --frozen`, and `self-update`.
diff --git a/docs/src/content/docs/reference/cli/view.md b/docs/src/content/docs/reference/cli/view.md
new file mode 100644
index 000000000..1e52a262a
--- /dev/null
+++ b/docs/src/content/docs/reference/cli/view.md
@@ -0,0 +1,91 @@
+---
+title: apm view
+description: Inspect package metadata or list remote versions
+sidebar:
+  order: 5
+---
+
+Show local metadata for an installed package, or query remote refs without cloning.
+
+## Synopsis
+
+```bash
+apm view PACKAGE [FIELD] [OPTIONS]
+```
+
+`apm info` is accepted as a hidden alias for backward compatibility.
+
+## Description
+
+`apm view` has two modes, selected by the optional `FIELD` argument:
+
+- **No field** -- read installed package metadata from `apm_modules/` (or `~/.apm/apm_modules/` with `-g`). Local-only; the package must be installed.
+- **`versions` field** -- query the remote for available tags and branches. No local install required.
+
+When `PACKAGE` matches the `NAME@MARKETPLACE` pattern, `apm view` resolves the plugin against the marketplace manifest and prints its entry (name, version, description, source, tags) instead of a Git repository view. This applies whether or not `versions` is passed.
+
+See [`apm outdated`](../outdated/) to compare locked versions against remotes, and [`apm install`](../install/) to add a package to the manifest.
+
+## Subcommands
+
+### `apm view <package>`
+
+Reads metadata from the installed copy. Exits non-zero if `apm_modules/` is missing or the package is not installed; on a missing package, prints the list of installed packages to help disambiguate.
+
+Output includes: name, version, description, author, source, install path, lockfile ref and commit (when available), context-file counts (skills, prompts, instructions), workflow count, and hook count.
+
+### `apm view <package> versions`
+
+Lists remote tags and branches for the package. Calls the remote -- requires network access, and for private repositories requires `GITHUB_APM_PAT` (see [authentication](../../../consumer/authentication/)).
+
+Output is a table with name, type (`tag` or `branch`), and short commit SHA.
+
+## Arguments
+
+| Argument  | Required | Description                                                                                       |
+| --------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `PACKAGE` | yes      | `owner/repo`, short repo name (installed only), or `NAME@MARKETPLACE` for a marketplace plugin    |
+| `FIELD`   | no       | Field selector. Only `versions` is supported today                                                |
+
+## Options
+
+| Option           | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `-g`, `--global` | Inspect a package installed in user scope (`~/.apm/apm_modules/`) |
+
+## Examples
+
+Show metadata for an installed package:
+
+```bash
+apm view microsoft/apm-sample-package
+```
+
+Short-name lookup (resolves against `apm_modules/`):
+
+```bash
+apm view apm-sample-package
+```
+
+List remote tags and branches without cloning:
+
+```bash
+apm view microsoft/apm-sample-package versions
+```
+
+Inspect a package installed at user scope:
+
+```bash
+apm view microsoft/apm-sample-package -g
+```
+
+View a marketplace plugin's manifest entry:
+
+```bash
+apm view code-review@acme-plugins
+```
+
+## Related
+
+- [`apm outdated`](../outdated/) -- compare locked versions against remote tags
+- [`apm install`](../install/) -- add a package to `apm.yml` and install it
diff --git a/docs/src/content/docs/reference/environment-variables.md b/docs/src/content/docs/reference/environment-variables.md
new file mode 100644
index 000000000..4727a2deb
--- /dev/null
+++ b/docs/src/content/docs/reference/environment-variables.md
@@ -0,0 +1,87 @@
+---
+title: Environment variables
+description: Canonical list of every environment variable APM reads, with defaults, allowed values, and scope.
+sidebar:
+  order: 8
+---
+
+Single source of truth for every environment variable APM reads. Variables are grouped by purpose. Unless noted, scope is **process** (the running `apm` invocation and any child processes it spawns); a small number toggle behaviour for the entire shell **session**.
+
+For CLI flags that pair with these variables, see [CLI commands](./cli-commands/). For token policy and supply-chain guidance, see [Security and supply chain](../enterprise/security-and-supply-chain/).
+
+## Authentication
+
+PAT / bearer credentials APM reads when cloning packages, calling host APIs, or wiring secrets into agent runtimes. Treat every value here as a secret: never commit, never log, never echo. See [Authentication](../consumer/authentication/) for the resolution chain and [Security and supply chain](../enterprise/security-and-supply-chain/) for token scoping.
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `GITHUB_APM_PAT` | Fine-grained PAT for APM module access on GitHub-class hosts (github.com, GHE Cloud, GHES). First in the GitHub `modules` precedence chain. | unset | Highest precedence for module clones. Also re-exported into Copilot / Codex runtimes. |
+| `GITHUB_APM_PAT_<ORG>` | Per-org PAT override for github.com / GHE Cloud / GHES. `<ORG>` is the org name uppercased with non-alphanumeric chars replaced by `_`. | unset | Wins over `GITHUB_APM_PAT` when the package owner matches `<ORG>`. |
+| `GITHUB_TOKEN` | Standard GitHub token. Falls back when `GITHUB_APM_PAT` is unset. Also forwarded to Codex. | unset | Used by `modules`, `copilot`, and `models` purposes. |
+| `GH_TOKEN` | `gh` CLI token. Last in the GitHub `modules` chain before `gh auth token` and credential helpers. | unset | Forwarded to the Copilot runtime. |
+| `GITHUB_COPILOT_PAT` | First-choice token for the Copilot runtime. | unset | Only consulted by the `copilot` purpose. |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Forwarded to the Copilot runtime when present. | unset | Not part of the `modules` resolution chain. |
+| `GITHUB_HOST` | GHES / GHE Cloud hostname (e.g. `ghe.example.com`). Switches host classification, transport selection, and auth chain. | `github.com` | Process-wide; affects clone URLs and host detection. |
+| `GITLAB_APM_PAT` | APM module access on GitLab SaaS or self-managed. First in the `gitlab_modules` chain. | unset | |
+| `GITLAB_TOKEN` | GitLab fallback token. | unset | |
+| `GITLAB_HOST` | Single self-managed GitLab hostname (e.g. `gitlab.example.com`). | unset | Recognised as GitLab-class for transport / auth. |
+| `APM_GITLAB_HOSTS` | Comma-separated list of additional GitLab hostnames to classify as GitLab-class. | unset | Use when you operate multiple GitLab instances. |
+| `ADO_APM_PAT` | Azure DevOps PAT for `ado_modules`. | unset | If unset, APM falls back to AAD bearer via `az` CLI. |
+| `ARTIFACTORY_APM_TOKEN` | JFrog Artifactory token for `artifactory_modules`. | unset | Also used by the registry-proxy resolver. |
+| `GIT_SSH_COMMAND` | Standard git SSH command override. APM reads it before composing its own SSH env. | unset | If you set it, APM preserves your value. |
+| `APM_GIT_CREDENTIAL_TIMEOUT` | Seconds to wait for a `git credential fill` response. | implementation default | Integer-like string; invalid values are ignored. |
+
+## Registry (MCP and proxy)
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `MCP_REGISTRY_URL` | Override the MCP registry endpoint used by `apm mcp` and `apm install --mcp NAME`. Must be `https://`. | public registry | When set, every `apm mcp` command prints `Registry: <url>`. See [`apm mcp`](./cli/mcp/). |
+| `MCP_REGISTRY_ALLOW_HTTP` | Set to `1` to permit a plaintext `http://` `MCP_REGISTRY_URL` (development only). | unset | Required to opt in to HTTP; production should always use HTTPS. |
+| `MCP_REGISTRY_CONNECT_TIMEOUT` | Connect timeout for registry HTTP calls, in seconds (float). | implementation default | Non-positive / non-numeric values are ignored. |
+| `MCP_REGISTRY_READ_TIMEOUT` | Read timeout for registry HTTP calls, in seconds (float). | implementation default | Non-positive / non-numeric values are ignored. |
+| `PROXY_REGISTRY_URL` | Enterprise package proxy base URL. See [Registry proxy](../enterprise/registry-proxy/). | unset | When set, APM resolves package downloads through the proxy. |
+| `PROXY_REGISTRY_TOKEN` | Bearer token for `PROXY_REGISTRY_URL`. | unset | Required for authenticated proxies. |
+| `PROXY_REGISTRY_ALLOW_HTTP` | Allow `http://` for `PROXY_REGISTRY_URL` (development only). | unset | Mirrors the MCP registry's HTTP opt-in. |
+| `PROXY_REGISTRY_ONLY` | Set to `1` to refuse any download not served by the proxy. | unset | Air-gapped deployments. |
+| `ARTIFACTORY_BASE_URL` | Legacy alias for `PROXY_REGISTRY_URL`. | unset | Prefer `PROXY_REGISTRY_URL` in new setups. |
+| `ARTIFACTORY_ONLY` | Legacy alias for `PROXY_REGISTRY_ONLY`. | unset | Prefer `PROXY_REGISTRY_ONLY`. |
+| `ARTIFACTORY_MAX_ARCHIVE_MB` | Maximum archive size accepted from Artifactory, in MB. | `500` | Integer-like string. |
+
+## Cache and filesystem
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `APM_CACHE_DIR` | Override the APM cache root. | platform default (XDG / `LOCALAPPDATA`) | Must be writable. See [`apm cache`](./cli/cache/). |
+| `APM_NO_CACHE` | `1`/`true`/`yes` disables read and write of the cache for the current invocation. | unset | Equivalent to `--no-cache` on commands that support it. |
+| `APM_TEMP_DIR` | Override the temp directory used by clone and download operations. | system default | Useful on Windows when endpoint security blocks `%TEMP%`. Resolution: env var > `temp_dir` in `~/.apm/config.json` > system default. |
+| `APM_NO_REFLINK` | Any non-empty value disables copy-on-write (reflink) optimisation; APM falls back to plain copies. | unset | Diagnostic / portability escape hatch. |
+| `APM_COPILOT_COWORK_SKILLS_DIR` | Override the destination directory for Copilot cowork skills. | platform auto-detect | Resolution: env var > config > auto-detect. |
+| `XDG_CACHE_HOME` | Standard XDG base-directory variable APM consults when `APM_CACHE_DIR` is unset (Linux / macOS). | unset | Honoured per the XDG spec. |
+| `LOCALAPPDATA` | Standard Windows variable APM consults when `APM_CACHE_DIR` is unset. | OS-provided | Used to derive the default Windows cache path. |
+| `CLAUDE_CONFIG_DIR` | Override the destination Claude reads for skills / agents. | Claude default | Read by the Claude integration target. |
+
+## Policy
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `APM_POLICY_DISABLE` | Set to `1` to skip policy discovery and enforcement for **the entire shell session**. Loudly logged. | unset | Equivalent to the per-invocation `--no-policy` on commands that expose it. The only escape hatch for `apm deps update`. See [`apm policy`](./cli/policy/). |
+
+## Debugging and output
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `APM_DEBUG` | Any non-empty value enables low-level debug logging in download, file ops, and clone-cache paths. | unset | Verbose; use for troubleshooting only. |
+| `APM_VERBOSE` | `1` enables verbose output for the install pipeline. APM also sets this internally when `--verbose` is passed. | unset | |
+| `APM_PROGRESS` | Force the install TUI on or off: `always`/`on`/`1`/`true`/`yes` to force on; `never`/`quiet`/`off`/`0`/`false`/`no` to force off; `auto` (default) lets APM decide based on `CI`, `TERM`, and TTY. | `auto` | The CLI sets `APM_PROGRESS=quiet` when `--quiet` is passed. |
+| `CI` | Standard CI marker. When truthy (`1`/`true`/`yes`), APM disables the install TUI and adjusts a few interactive defaults. | unset | Read; never written. |
+| `TERM` | Standard terminal type. `""` or `dumb` disables the install TUI. | OS-provided | Read; never written. |
+
+## Experimental and internal
+
+These variables exist in the codebase but are not part of the documented contract. Behaviour and naming may change without notice. Do not rely on them in production scripts.
+
+| Variable | Purpose | Default | Notes |
+|---|---|---|---|
+| `APM_RESOLVE_PARALLEL` | Tunes parallelism in the dependency resolver. | implementation default | Subject to change. |
+| `APM_LEGACY_SKILL_PATHS` | Toggles legacy skill-path layout in integration targets. | unset | Compatibility shim; will be removed. |
+| `APM_E2E_TESTS` | Marks the process as an end-to-end test run; relaxes some interactive guards. | unset | Test harness only. Do not set in normal use. |
diff --git a/docs/src/content/docs/reference/index.md b/docs/src/content/docs/reference/index.md
new file mode 100644
index 000000000..06199a89c
--- /dev/null
+++ b/docs/src/content/docs/reference/index.md
@@ -0,0 +1,45 @@
+---
+title: Reference
+description: CLI commands, schemas, and specifications for APM.
+sidebar:
+  order: 0
+---
+
+This section is the authoritative reference for APM. If you're learning APM, start in the [consumer ramp](../consumer/) or [producer ramp](../producer/) instead -- the reference assumes you know what you're looking for.
+
+## CLI commands
+
+Per-command pages live under [`reference/cli/`](./cli/install/). Grouped by lifecycle phase:
+
+| Phase                  | Commands                                                                         |
+|------------------------|----------------------------------------------------------------------------------|
+| Project setup          | [`init`](./cli/init/), [`install`](./cli/install/), [`update`](./cli/update/), [`uninstall`](./cli/uninstall/) |
+| Inspect and audit      | [`view`](./cli/view/), [`deps`](./cli/deps/), [`outdated`](./cli/outdated/), [`list`](./cli/list/), [`audit`](./cli/audit/) |
+| Compile and integrate  | [`compile`](./cli/compile/), [`prune`](./cli/prune/), [`targets`](./cli/targets/), [`runtime`](./cli/runtime/) |
+| Cache and config       | [`cache`](./cli/cache/), [`config`](./cli/config/)                               |
+| Run scripts            | [`run`](./cli/run/)                                                              |
+| Author and distribute  | [`pack`](./cli/pack/), [`unpack`](./cli/unpack/), [`preview`](./cli/preview/), [`marketplace`](./cli/marketplace/), [`search`](./cli/search/) |
+| Governance             | [`policy`](./cli/policy/), [`mcp`](./cli/mcp/)                                   |
+| Experimental           | [`experimental`](./cli/experimental/)                                            |
+
+## Schemas and specifications
+
+| Doc                                                          | What it specifies                                                |
+|--------------------------------------------------------------|------------------------------------------------------------------|
+| [Manifest schema](./manifest-schema/)                        | Every field in `apm.yml`                                         |
+| [Lockfile spec](./lockfile-spec/)                            | `apm.lock.yaml` schema, semantics, and integrity contract        |
+| [Policy schema](./policy-schema/)                            | `apm-policy.yml` rules, merge semantics, severity                |
+| [Targets matrix](./targets-matrix/)                          | Which primitive types each target (Copilot, Claude, ...) supports |
+| [Baseline checks](./baseline-checks/)                        | The CI checks `apm audit --ci` runs                              |
+| [Environment variables](./environment-variables/)            | Every env var APM reads, with precedence                         |
+| [Primitive types](./primitive-types/)                        | Skill, prompt, instruction, agent, hook, command                 |
+| [Package types](./package-types/)                            | APM packages, plugins, marketplaces                              |
+| [Examples](./examples/)                                      | Worked end-to-end examples                                       |
+| [Experimental](./experimental/)                              | Surface area still subject to change                             |
+
+## Conventions used in reference pages
+
+- `<placeholder>` -- you must substitute a real value.
+- `[optional]` -- argument or flag is optional.
+- All commands assume `apm` is on `PATH`; install instructions are in the [Quickstart](../quickstart/).
+- Status symbols in CLI output: `[+]` success, `[!]` warning, `[x]` error, `[i]` info, `[*]` action, `[>]` running.
diff --git a/docs/src/content/docs/reference/lockfile-spec.md b/docs/src/content/docs/reference/lockfile-spec.md
index 8c619aaff..ca876ef38 100644
--- a/docs/src/content/docs/reference/lockfile-spec.md
+++ b/docs/src/content/docs/reference/lockfile-spec.md
@@ -1,430 +1,256 @@
 ---
-title: "Lock File Specification"
-description: "The apm.lock.yaml format — how APM pins dependencies to exact versions for reproducible installs."
+title: Lockfile specification
+description: The apm.lock.yaml format - fields, lifecycle, and how install, audit, prune, and view consume it.
 sidebar:
-  order: 3
+  order: 4
 ---
 
-<dl>
-<dt>Version</dt><dd>0.1 (Working Draft)</dd>
-<dt>Date</dt><dd>2026-03-09</dd>
-<dt>Editors</dt><dd>Daniel Meppiel (Microsoft)</dd>
-<dt>Repository</dt><dd>https://github.com/microsoft/apm</dd>
-<dt>Format</dt><dd>YAML 1.2</dd>
-</dl>
+`apm.lock.yaml` is the pinned record of every resolved dependency and every
+file APM deployed into the workspace. It is the source of truth for
+reproducible installs and for drift detection. Commit it.
 
-## Status of This Document
+## Purpose
 
-This is a **Working Draft**. The lock file format is stable at version `"1"` and
-breaking changes will be gated behind a `lockfile_version` bump.
+The lockfile gives APM four things:
 
-## Abstract
+1. **Reproducibility.** `apm install --frozen` reinstalls the exact commits
+   recorded here - no resolution, no network drift.
+2. **Integrity.** Recorded SHA-256 hashes let `apm audit` detect tampering
+   with deployed files.
+3. **Cleanup.** The list of deployed files lets `apm prune` remove orphans
+   when a dependency is dropped from `apm.yml`.
+4. **Inspection.** `apm view --lock` and `apm audit` read the lockfile to
+   answer "what is actually installed".
 
-`apm.lock.yaml` records the exact resolved state of every dependency in an APM
-project. It is the receipt of what was installed — commit SHAs, source URLs,
-and every file deployed into the workspace. Its role is analogous to
-`package-lock.json` (npm) or `.terraform.lock.hcl` (Terraform): given the same
-lock file, APM MUST reproduce the same file tree.
+## Location
 
----
-
-## 1. Conformance
-
-The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this
-document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
-
-## 2. Purpose
-
-The lock file serves four goals:
-
-1. **Reproducibility** — the same lock file yields the same deployed files on
-   every machine, every time.
-2. **Provenance** — every dependency is traceable to an exact source commit.
-3. **Completeness** — `deployed_files` lists every file APM placed in the
-   project, enabling precise removal.
-4. **Auditability** — `git log apm.lock.yaml` provides a full history of dependency
-   changes across the lifetime of the project.
-
-## 3. Lifecycle
+The lockfile lives at the project root next to `apm.yml`:
 
-`apm.lock.yaml` is created and updated at well-defined points:
-
-| Event | Effect on `apm.lock.yaml` |
-|-------|----------------------|
-| `apm install` (first run) | Created. All dependencies resolved, commits pinned, files recorded. |
-| `apm install` (subsequent) | Read. Locked commits reused. New dependencies appended. File only written when semantic content changes (dependencies, MCP servers/configs, `lockfile_version`); no churn from `generated_at` or `apm_version` fields. |
-| `apm install --frozen` | Read-only. Fails fast (exit 1) if the lockfile is missing or any direct dependency in `apm.yml` is absent from the lockfile. Mutually exclusive with `--update`. Use in CI to catch drift between manifest and lockfile. |
-| `apm update` | Re-resolved with confirmation gate. Resolves `apm.yml` against the latest matching refs, prints a structured plan (added/updated/removed/unchanged), and writes only after the user confirms (default `[y/N]`; bypass with `--yes`, preview with `--dry-run`). |
-| `apm install --update` | Re-resolved. All refs re-resolved to latest matching commits without a confirmation prompt. Prefer `apm update` for interactive flows. |
-| `apm deps update` | Re-resolved. Refreshes versions for specified or all dependencies. |
-| `apm pack` | Enriched. A `pack:` section is prepended to the bundled copy (see [section 6](#6-pack-enrichment)). Both `--format plugin` (default) and `--format apm` embed the enriched copy when a project lockfile exists. |
-| `apm uninstall` | Updated. Removed dependency entries and their `deployed_files` references. |
-
-The lock file SHOULD be committed to version control. It MUST NOT be
-manually edited — APM is the sole writer.
+```
+my-project/
+|- apm.yml
+|- apm.lock.yaml      <- here
+|- apm_modules/
+```
 
-## 4. Document Structure
+Always commit it. The lockfile is what makes a fresh clone install identically
+on any machine.
 
-A conforming lock file MUST be a YAML 1.2 document with the following
-top-level structure:
+## Top-level structure
 
 ```yaml
 lockfile_version: "1"
-generated_at: "2026-03-09T14:00:00Z"
-apm_version: "0.7.7"
-
-dependencies:
-  - repo_url: https://github.com/acme-corp/security-baseline
-    resolved_commit: a1b2c3d4e5f6789012345678901234567890abcd
-    resolved_ref: v2.1.0
-    version: "2.1.0"
-    depth: 1
-    package_type: apm_package
-    deployed_files:
-      - .github/instructions/security.instructions.md
-      - .github/agents/security-auditor.agent.md
-
-  - repo_url: https://github.com/acme-corp/common-prompts
-    resolved_commit: f6e5d4c3b2a1098765432109876543210fedcba9
-    resolved_ref: main
-    depth: 2
-    resolved_by: https://github.com/acme-corp/security-baseline
-    package_type: apm_package
-    deployed_files:
-      - .github/instructions/common-guidelines.instructions.md
-```
-
-### 4.1 Top-Level Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `lockfile_version` | string | MUST | Lock file format version. Currently `"1"`. |
-| `generated_at` | string (ISO 8601) | MUST | UTC timestamp of when the lock file was last written. |
-| `apm_version` | string | MUST | Version of APM that generated this lock file. |
-| `dependencies` | array | MUST | Ordered list of resolved dependencies (see [section 4.2](#42-dependency-entries)). |
-| `mcp_servers` | array | MAY | List of MCP server identifiers registered by installed packages. |
-| `mcp_configs` | mapping | MAY | Mapping of MCP server name to its manifest configuration dict. Used for diff-aware installation — when config in `apm.yml` changes, `apm install` detects the drift and re-applies without `--force`. |
-
-### 4.2 Dependency Entries
-
-The `dependencies` list MUST be sorted by `depth` (ascending), then by
-`repo_url` (lexicographic). Each entry is a YAML mapping with the following
-fields:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `repo_url` | string | MUST | Source repository URL, or `_local/<name>` for local path dependencies. |
-| `host` | string | MAY | Git host identifier (e.g., `github.com`). Omitted when inferrable from `repo_url`. |
-| `resolved_commit` | string | MUST (remote) | Full 40-character commit SHA that was checked out. Required for remote (git) dependencies; MUST be omitted for local (`source: "local"`) dependencies. |
-| `resolved_ref` | string | MUST (remote) | Git ref (tag, branch, SHA) that resolved to `resolved_commit`. Required for remote (git) dependencies; MUST be omitted for local (`source: "local"`) dependencies. |
-| `version` | string | MAY | Semantic version of the package, if declared in its manifest. |
-| `virtual_path` | string | MAY | Sub-path within the repository for virtual (monorepo) packages. |
-| `is_virtual` | boolean | MAY | `true` if the package is a virtual sub-package. Omitted when `false`. |
-| `depth` | integer | MUST | Dependency depth. `1` = direct dependency, `2`+ = transitive. |
-| `resolved_by` | string | MAY | `repo_url` of the parent that introduced this transitive dependency. Present only when `depth >= 2`. |
-| `package_type` | string | MUST | Package type: `apm_package`, `plugin`, `virtual`, or other registered types. |
-| `content_hash` | string | MAY | SHA-256 hash of the package file tree, in the format `"sha256:<hex>"`. Used to verify cached packages on subsequent installs. Omitted for local path dependencies. See [section 4.4](#44-content-integrity). |
-| `is_dev` | boolean | MAY | `true` if the dependency was resolved through [`devDependencies`](../manifest-schema/#5-devdependencies). Omitted when `false`. Dev deps are excluded from `apm pack` plugin output (and from `--format apm` bundles). |
-| `deployed_files` | array of strings | MUST | Every file path APM deployed for this dependency, relative to project root. |
-| `source` | string | MAY | Dependency source. `"local"` for local path dependencies. Omitted for remote (git) dependencies. |
-| `local_path` | string | MAY | Filesystem path (relative or absolute) to the local package. Present only when `source` is `"local"`. |
-| `is_insecure` | boolean | MAY | `true` when the dep was fetched over HTTP (unencrypted). Omitted when `false`. Presence forces re-approval on the next install: the apm.yml entry MUST carry `allow_insecure: true` and the invocation MUST pass `--allow-insecure` (or `--allow-insecure-host` for transitive deps). Absent or `false` means HTTPS/SSH. |
-| `allow_insecure` | boolean | MAY | `true` when the user's manifest explicitly approved the HTTP fetch with `allow_insecure: true`. Persisted alongside `is_insecure` for replay safety: a legacy lockfile with `is_insecure: true` but no `allow_insecure` fail-closes to `allow_insecure: false`, forcing re-approval. Omitted when `false`. |
-
-Fields with empty or default values (empty strings, `false` booleans, empty
-lists) SHOULD be omitted from the serialized output to keep the file concise.
-
-**Dev dependency tracking:** Packages installed via `apm install --dev` are marked with `is_dev: true`. `apm pack` (plugin format, the default) and `apm pack --format apm` both exclude dev dependencies from output. Resolvers and CI tools should respect this flag when producing distributable artifacts.
-
-### 4.3 Unique Key
-
-Each dependency is uniquely identified by its `repo_url`, or by the
-combination of `repo_url` and `virtual_path` for virtual packages.
-For local path dependencies (`source: "local"`), the unique key is the
-`local_path` value. A conforming lock file MUST NOT contain duplicate
-entries for the same key.
-
-### 4.4 Content Integrity
-
-APM computes a SHA-256 hash of each package's file tree after download and stores
-it as `content_hash` in the lock file. On subsequent installs, cached packages are
-verified against this hash. A mismatch triggers a warning and re-download.
-
-The hash covers all regular files sorted by POSIX path (deterministic regardless of
-filesystem ordering). `.git/` and `__pycache__/` directories are excluded.
-
-```yaml
+generated_at: "2026-05-10T20:14:00+00:00"
+apm_version: "0.6.4"
 dependencies:
-  - repo_url: https://github.com/acme-corp/security-baseline
-    resolved_commit: a1b2c3d4e5f6789012345678901234567890abcd
-    content_hash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  - repo_url: github.com/octocat/example-skills
+    resolved_commit: 7f3c9a...
     # ...
+mcp_servers:
+  - github
+mcp_configs:
+  github:
+    type: stdio
+    command: docker
+    args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
+local_deployed_files:
+  - .github/skills/my-local-skill/SKILL.md
+local_deployed_file_hashes:
+  .github/skills/my-local-skill/SKILL.md: "a1b2c3..."
 ```
 
-Lock files generated before this feature omit `content_hash`. APM handles this
-gracefully — verification is skipped and the hash is populated on the next install.
-
-### 4.5 Self-Entry Convention
-
-For uniform traversal, the in-memory `dependencies` map includes a synthesized
-entry representing the host project's own local `.apm/` content. This entry is
-materialized on read and stripped on write -- it is **never serialized** to disk.
-
-The on-disk YAML format is unchanged: the host project's local content lives in
-the flat top-level fields `local_deployed_files` and `local_deployed_file_hashes`
-(see [section 4.4](#44-content-integrity) for the hashing scheme used for
-verification). `LockFile.from_yaml()` synthesizes the self-entry from those
-fields; `LockFile.to_yaml()` removes it before serialization. Round-trip is
-byte-stable.
-
-The synthesized entry MUST follow this convention:
-
-| Field | Value |
-|-------|-------|
-| Map key | `"."` (single dot) |
-| `repo_url` | `"<self>"` |
-| `local_path` | `"."` |
-| `source` | `"local"` |
-| `is_dev` | `true` |
-| `depth` | `0` |
-| `deployed_files` | populated from `local_deployed_files` |
-| `deployed_file_hashes` | populated from `local_deployed_file_hashes` |
-
-`is_dev: true` is non-negotiable. `apm pack` (both formats) skips dev
-dependencies; this flag ensures the host project's own content is excluded from
-distributable bundles via the existing dev-dependency filter, without requiring
-exporters to special-case the self-entry.
-
-Consumers iterating `dependencies` SHOULD treat the `"."` key as the host
-project. Consumers reading the on-disk YAML directly will not see this entry --
-they MUST read `local_deployed_files` and `local_deployed_file_hashes` instead.
-
-## 5. Path Conventions
-
-All paths in `deployed_files` MUST use forward slashes (POSIX format),
-regardless of the host operating system. Paths are relative to the project
-root directory.
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `lockfile_version` | string | yes | Schema version. Currently `"1"`. Bumped on breaking format changes. |
+| `generated_at` | ISO 8601 string | yes | UTC timestamp of the last write. Ignored by equivalence checks. |
+| `apm_version` | string | no | APM CLI version that wrote the file. Diagnostic only. |
+| `dependencies` | list | yes | Resolved APM packages. See [per-entry fields](#per-entry-fields). |
+| `mcp_servers` | list of strings | no | Names of MCP servers declared in the manifest at install time. |
+| `mcp_configs` | map | no | `server_name -> resolved config dict` baseline used to detect MCP drift. |
+| `local_deployed_files` | list | no | Files this project itself contributes (sources its own primitives). See [self entry](#self-entry). |
+| `local_deployed_file_hashes` | map | no | `path -> sha256` for `local_deployed_files`. |
+
+## Per-entry fields
+
+Each item in `dependencies` describes one resolved package.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `repo_url` | string | yes | Canonical repo URL (e.g. `github.com/owner/repo`). Unique key for the entry, except for virtual and local entries (see below). |
+| `host` | string | no | FQDN when not inferable from `repo_url` (e.g. for registry proxies or non-GitHub hosts). |
+| `port` | int | no | Non-standard SSH/HTTPS port. Validated to `1..65535` on read. |
+| `registry_prefix` | string | no | URL path prefix when resolved through a registry proxy (e.g. `artifactory/github`). |
+| `resolved_ref` | string | no | The user-supplied ref from `apm.yml` (`main`, `v1.2.0`, a SHA). |
+| `resolved_commit` | string | no | Exact 40-char commit SHA installed. The pin. |
+| `version` | string | no | Resolved semver when the source advertises one. |
+| `virtual_path` | string | no | Subpath inside the repo for virtual packages (monorepo subpaths). |
+| `is_virtual` | bool | no | `true` when the entry is a virtual subpath package. |
+| `depth` | int | no | Position in the dependency tree. `0` is the project itself, `1` is a direct dep, higher is transitive. Defaults to `1`. |
+| `resolved_by` | string | no | `repo_url` of the parent that pulled this transitive dep. Absent for direct deps. |
+| `package_type` | string | no | Kind of package: `apm`, `skill_bundle`, etc. Drives target placement. |
+| `skill_subset` | list of strings | no | For `skill_bundle` packages: the sorted subset of skill names the manifest selected. Empty means "all". |
+| `deployed_files` | list of strings | no | Project-relative paths APM wrote for this dep. Sorted. Powers `prune` and `audit`'s file-presence check. |
+| `deployed_file_hashes` | map | no | `path -> sha256` for the files in `deployed_files`. Powers `audit`'s content-integrity check. Directory entries (trailing `/`) have no hash. |
+| `source` | string | no | `"local"` for path dependencies. Absent for remote deps. |
+| `local_path` | string | no | Original path from `apm.yml` for local deps, relative to project root. |
+| `content_hash` | string | no | SHA-256 of the local package's source tree. Lets APM detect upstream changes to a path dep. |
+| `is_dev` | bool | no | `true` when the dep was declared under `devDependencies`. |
+| `discovered_via` | string | no | Marketplace name that surfaced this package (provenance). |
+| `marketplace_plugin_name` | string | no | Plugin name as listed in that marketplace. |
+| `is_insecure` | bool | no | `true` when the source URL was `http://`. |
+| `allow_insecure` | bool | no | `true` when the manifest explicitly opted in to the insecure source. |
+
+Fields are emitted only when set. A minimal entry is just `repo_url` plus
+`resolved_commit`.
+
+## Self entry
+
+A project that ships its own primitives (skills, agents, prompts under
+`.github/`, `.claude/`, etc.) records the files it deploys to its own targets
+under `local_deployed_files` and `local_deployed_file_hashes` at the top
+level.
+
+Internally, when the lockfile is loaded, APM synthesizes a virtual dependency
+entry keyed by `"."` so that orphan detection, audit, and prune can iterate
+all "owned" files uniformly. This synthesized entry has:
+
+- `repo_url: <self>`
+- `source: local`
+- `local_path: "."`
+- `depth: 0`
+- `is_dev: true`
+- `deployed_files` and `deployed_file_hashes` copied from the top-level
+  `local_deployed_*` fields.
+
+The synthesized entry is **not** written back to YAML - the flat
+`local_deployed_*` fields remain the on-disk source of truth. Treat the self
+entry as an implementation detail; do not author it by hand.
+
+## Pack section
+
+When a project is packed with `apm pack`, the bundled lockfile is enriched
+with a top-level `pack:` block:
 
 ```yaml
-# Correct
-deployed_files:
-  - .github/instructions/security.instructions.md
-  - .github/agents/code-review.agent.md
-
-# Incorrect — backslashes are not permitted
-deployed_files:
-  - .github\instructions\security.instructions.md
+pack:
+  format: apm           # or "plugin"
+  target: copilot       # or comma-joined list, or "all"
+  packed_at: "2026-05-10T20:14:00+00:00"
+  mapped_from:          # only when cross-target path remapping happened
+    - .claude/skills/
+  bundle_files:         # only for plugin bundles
+    skills/my-skill/SKILL.md: "a1b2..."
 ```
 
-This convention ensures lock files are portable across operating systems and
-produce consistent diffs in version control.
-
-## 6. Pack Enrichment
+The pack block is read by `apm unpack` to verify bundle integrity and to
+restore correct target paths. It is stripped from project lockfiles and only
+appears inside packed bundles.
 
-When `apm pack` creates a bundle, it prepends a `pack:` section to the
-lock file copy included in the bundle. Both `--format plugin` (default)
-and `--format apm` embed the enriched copy when the project has a
-lockfile; bundles built without a project lockfile (rare) skip the
-embedded copy and emit no `pack:` section. The `pack:` section is
-informational and is not written back to the project's `apm.lock.yaml`.
-
-```yaml
-pack:
-  format: apm
-  packed_at: "2026-03-09T14:30:00Z"
-  bundle_files:
-    .github/agents/architect.md: a1b2c3...
-
-lockfile_version: "1"
-generated_at: "2026-03-09T14:00:00Z"
-# ... rest of lock file
-```
+`local_deployed_files` and `local_deployed_file_hashes` are stripped from
+bundle lockfiles - they describe the packager's own repo, which is not
+shipped.
 
-### 6.1 Pack Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `pack.format` | string | Bundle format: `"apm"` or `"plugin"`. |
-| `pack.target` | string (deprecated, optional) | Historical target hint. Bundles are now target-agnostic; the consumer's project decides where files land at install time. The field is still recorded in every bundle for diagnostic purposes (typically `"all"` for target-agnostic packs, or the project's detected target) and is not authoritative at install time. |
-| `pack.packed_at` | string (ISO 8601) | UTC timestamp of when the bundle was created. |
-| `pack.bundle_files` | map[string -> string] | Per-file SHA-256 manifest of the bundle's deployable contents (relative path -> hex digest). Drives the install-side deploy loop. |
-
-The original lock file is not mutated. The enriched copy exists only inside the
-packed archive.
-
-## 7. Resolver Behaviour
-
-The dependency resolver interacts with the lock file as follows:
-
-1. **First install** — resolve all refs to commits, write `apm.lock.yaml`.
-2. **Subsequent installs** — read `apm.lock.yaml`, reuse locked commits. Only
-   newly added dependencies trigger resolution.
-3. **Update** (`--update` flag or `apm deps update`) -- re-resolve all refs
-   to their latest commits. If a resolved commit matches the existing lock
-   file entry and the local checkout is intact, the download is skipped.
-   Otherwise, the package is re-fetched. The lock file is always refreshed.
-4. **Interactive update** (`apm update`) -- re-resolve all refs and render
-   a structured plan (added/updated/removed/unchanged) before any
-   mutation. Defaults to a confirmation prompt; `--dry-run` exits after
-   the plan with no on-disk changes; `--yes` skips the prompt for CI
-   automation. On confirmation, behaves like (3) and refreshes the lock
-   file.
-5. **Frozen** (`apm install --frozen`) -- read `apm.lock.yaml` and
-   structurally verify every direct dependency declared in `apm.yml`
-   has a corresponding lock entry. Exit code 1 when the lockfile is
-   missing or any direct dep is unlocked; never resolves, never
-   mutates. Mutually exclusive with `--update`. Note: this is a
-   structural presence check; on-disk SHA integrity is the job of
-   `apm audit`.
-
-When a locked commit is no longer reachable (force-pushed branch, deleted tag),
-APM MUST report an error and refuse to install until the lock file is updated.
-
-## 8. Migration
-
-The lock file reader supports the following historical migrations:
-
-- **`deployed_skills`** — renamed to `deployed_files`. If a lock file contains
-  the legacy key, it is silently migrated on read. New lock files MUST use
-  `deployed_files`.
-
-- **`apm.lock` → `apm.lock.yaml`** — the lock file was renamed from `apm.lock`
-  to `apm.lock.yaml` (for IDE syntax highlighting). On the next `apm install`,
-  an existing `apm.lock` is automatically renamed to `apm.lock.yaml` when the
-  new file does not yet exist. The bundle unpacker also falls back to `apm.lock`
-  when reading older bundles.
-
-## 9. Auditing Patterns
-
-Because `apm.lock.yaml` is committed to version control, standard Git operations
-provide a complete audit trail:
-
-```bash
-# Full history of dependency changes
-git log --oneline apm.lock.yaml
-
-# What changed in the last commit
-git diff HEAD~1 -- apm.lock.yaml
-
-# State of dependencies at a specific release
-git show v4.2.1:apm.lock.yaml
-
-# Who last modified the lock file
-git log -1 --format='%an <%ae> %ai' -- apm.lock.yaml
-```
+## Lifecycle
 
-In CI pipelines, `apm audit --ci` verifies lockfile consistency (exit 0 = pass,
-1 = fail). Add `--policy org` for organizational policy enforcement.
+| Command | Reads | Writes |
+|---|---|---|
+| `apm install` | existing lockfile (for `--frozen` and incremental reuse) | full rewrite on resolution change |
+| `apm install --frozen` | required | never writes; fails on missing pin |
+| `apm compile` | yes (resolution + integrity) | no |
+| `apm audit` | yes | no |
+| `apm prune` | yes (to identify orphans) | yes (after removing orphans) |
+| `apm view --lock` | yes | no |
+| `apm unpack` | bundle's pack-enriched lockfile | merges into project lockfile |
 
-### 9.1 SOC 2 evidence
+`apm install` only rewrites the file when its semantic content changes
+(`generated_at` and `apm_version` are ignored when comparing). A no-op install
+leaves the file untouched.
 
-The lock file is the system of record for "what configuration was active when".
-Three SOC 2-relevant questions answered directly from git:
+## Drift and integrity
 
-- **Change authorization.** Every change to `apm.lock.yaml` is reviewed in a pull
-  request before merge. The PR record is the change-authorization evidence.
-- **Change history.** `git log apm.lock.yaml` produces a complete, tamper-evident
-  history in git of every dependency change with author, timestamp, and commit message.
-- **Point-in-time state.** `git show <ref>:apm.lock.yaml` reproduces the exact
-  dependency set active at any tag, branch, or commit -- including past releases.
+The lockfile is what `apm audit` compares the workspace against. Each baseline
+check maps to specific lockfile fields:
 
-### 9.2 Security audit / incident forensics
+| Check | Backed by |
+|---|---|
+| `lockfile-exists` | file presence at project root |
+| `dependency-refs-match` | `resolved_ref` per entry vs. `apm.yml` |
+| `deployed-files-present` | `deployed_files` per entry (and self entry) |
+| `content-integrity` | `deployed_file_hashes` (and `local_deployed_file_hashes`) |
+| `skill-subset-match` | `skill_subset` per `skill_bundle` entry |
+| `mcp-configs-match` | `mcp_servers` and `mcp_configs` |
+| `no-orphan-packages` | `dependencies` keys vs. `apm.yml` |
 
-When a vulnerability is disclosed in a dependency or a security incident requires
-identifying which environments were exposed:
+Files listed in `deployed_files` without a corresponding hash entry (typically
+directory markers ending in `/`) are skipped by content-integrity. Missing
+files are reported by `deployed-files-present`, not by content-integrity, so
+the two checks do not double-count.
 
-```bash
-# Was the vulnerable package ever in the lock file?
-git log -p apm.lock.yaml | grep -B2 -A2 "vulnerable-package"
+Orphan detection works in two directions:
 
-# Which release included the vulnerable version?
-git log --all --oneline -S 'vulnerable-package' -- apm.lock.yaml
+- **Orphan packages** - entries in `dependencies` that the manifest no longer
+  declares. `apm prune` removes them and their `deployed_files`.
+- **Orphan files** - files under managed target directories that no lockfile
+  entry claims. `apm prune` removes them too.
 
-# What is the current state of the dependency in production?
-git show production:apm.lock.yaml | grep -A5 "vulnerable-package"
-```
+## Versioning
 
-### 9.3 Change management pipeline
+`lockfile_version` is the schema version of the file format itself.
 
-The lockfile-as-audit-trail model maps onto a standard 5-step change management
-pipeline:
+- The current version is `"1"`.
+- APM additively extends entries within version `"1"` - new optional fields
+  may appear without bumping the version. Older APM clients ignore unknown
+  fields.
+- Breaking changes (renames, removals, semantic shifts) require bumping
+  `lockfile_version`. APM refuses to operate on a lockfile whose version it
+  does not recognize, and will instruct the user to upgrade or regenerate.
 
-1. **Declaration** -- developer edits `apm.yml` and opens a PR.
-2. **Resolution** -- `apm install` updates `apm.lock.yaml` with pinned versions.
-3. **Review** -- PR reviewers see the manifest and lockfile diff together.
-4. **Verification** -- CI runs `apm audit --ci` to confirm consistency and
-   (optionally) policy compliance.
-5. **Traceability** -- the merge commit becomes the durable record of the change,
-   readable by every downstream environment via `apm install` from the same ref.
+A lockfile that fails to parse is treated as absent - APM logs the error and,
+for non-frozen installs, proceeds to regenerate from `apm.yml`.
 
-For organization-wide policy enforcement on top of this lockfile audit trail,
-see [Governance](../../enterprise/governance-guide/).
+## Example
 
-## 10. Example: Complete Lock File
+A small project with one remote APM package, one MCP server, and its own
+local skill:
 
 ```yaml
 lockfile_version: "1"
-generated_at: "2026-03-09T14:00:00Z"
-apm_version: "0.7.7"
-
+generated_at: "2026-05-10T20:14:00+00:00"
+apm_version: "0.6.4"
 dependencies:
-  - repo_url: https://github.com/acme-corp/security-baseline
-    resolved_commit: a1b2c3d4e5f6789012345678901234567890abcd
-    resolved_ref: v2.1.0
-    version: "2.1.0"
+  - repo_url: github.com/octocat/example-skills
+    resolved_ref: v1.2.0
+    resolved_commit: 7f3c9a4d2e1b8c7f0a9e6d5c4b3a2918f7e6d5c4
+    version: 1.2.0
+    package_type: skill_bundle
     depth: 1
-    package_type: apm_package
-    content_hash: "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
-    deployed_files:
-      - .github/instructions/security.instructions.md
-      - .github/agents/security-auditor.agent.md
-      - .github/agents/threat-model.agent.md
-
-  - repo_url: https://github.com/acme-corp/common-prompts
-    resolved_commit: f6e5d4c3b2a1098765432109876543210fedcba9
-    resolved_ref: main
-    depth: 2
-    resolved_by: https://github.com/acme-corp/security-baseline
-    package_type: apm_package
-    content_hash: "sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592"
+    skill_subset:
+      - code-review
+      - test-writing
     deployed_files:
-      - .github/instructions/common-guidelines.instructions.md
-
-  - repo_url: https://github.com/example-org/monorepo-tools
-    host: github.com
-    resolved_commit: 0123456789abcdef0123456789abcdef01234567
-    resolved_ref: v1.0.0
-    version: "1.0.0"
-    virtual_path: packages/linter-config
-    is_virtual: true
-    depth: 1
-    package_type: virtual
-    deployed_files:
-      - .github/instructions/linter.instructions.md
-
-  - repo_url: https://github.com/acme-corp/test-helpers
-    resolved_commit: abcdef1234567890abcdef1234567890abcdef12
-    resolved_ref: main
-    depth: 1
-    package_type: apm_package
-    is_dev: true
-    content_hash: "sha256:4a44dc15364204a80fe80e9039455cc1608281820fe2b24f1e5233ade6af1dd5"
-    deployed_files:
-      - .github/instructions/test-helpers.instructions.md
-
+      - .github/skills/code-review/SKILL.md
+      - .github/skills/test-writing/SKILL.md
+    deployed_file_hashes:
+      .github/skills/code-review/SKILL.md: "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+      .github/skills/test-writing/SKILL.md: "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
 mcp_servers:
-  - security-scanner
-
+  - github
 mcp_configs:
-  security-scanner:
-    name: security-scanner
-    transport: stdio
+  github:
+    type: stdio
+    command: docker
+    args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
+local_deployed_files:
+  - .github/skills/my-local-skill/SKILL.md
+local_deployed_file_hashes:
+  .github/skills/my-local-skill/SKILL.md: "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"
 ```
 
----
-
-## Appendix A: Revision History
+## See also
 
-| Version | Date | Changes |
-|---------|------|---------|
-| 0.1 | 2026-03-09 | Initial working draft. |
+- [`apm install`](../cli/install/) - resolves and writes the lockfile
+- [`apm audit`](../cli/audit/) - validates the workspace against the lockfile
+- [`apm prune`](../cli/prune/) - removes orphan packages and files
+- [`apm view`](../cli/view/) - inspect resolved state (`--lock`)
+- [Baseline checks](../baseline-checks/) - the drift checks the lockfile feeds
+- [Manifest schema](../manifest-schema/) - the `apm.yml` it pins
diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md
index c75e7bd0b..55f4f187d 100644
--- a/docs/src/content/docs/reference/manifest-schema.md
+++ b/docs/src/content/docs/reference/manifest-schema.md
@@ -1,12 +1,13 @@
 ---
 title: "Manifest Schema"
+description: "The apm.yml format -- top-level fields, dependencies, marketplace block, and integrator contract."
 sidebar:
-  order: 2
+  order: 1
 ---
 
 <dl>
-<dt>Version</dt><dd>0.1 (Working Draft)</dd>
-<dt>Date</dt><dd>2026-03-06</dd>
+<dt>Version</dt><dd>0.2 (Working Draft)</dd>
+<dt>Date</dt><dd>2026-05-10</dd>
 <dt>Editors</dt><dd>Daniel Meppiel (Microsoft)</dd>
 <dt>Repository</dt><dd>https://github.com/microsoft/apm</dd>
 <dt>Format</dt><dd>YAML 1.2</dd>
@@ -22,7 +23,7 @@ This specification defines the manifest format (`apm.yml`) used by the Agent Pac
 
 ## Abstract
 
-The `apm.yml` manifest declares the full closure of agent primitive dependencies, MCP servers, scripts, and compilation settings for a project. It is the contract between package authors, runtimes, and integrators — any conforming resolver can consume this format to install, compile, and run agentic workflows.
+The `apm.yml` manifest declares the full closure of agent primitive dependencies, MCP servers, scripts, compilation settings, consumer-side policy controls, and (optionally) marketplace authoring metadata for a project. It is the contract between package authors, runtimes, and integrators: any conforming resolver can consume this format to install, compile, run, and pack agentic workflows.
 
 ---
 
@@ -45,7 +46,7 @@ version:       <string>                  # REQUIRED
 description:   <string>
 author:        <string>
 license:       <string>
-target:        <enum>
+target:        <enum | list<enum>>
 type:          <enum>
 scripts:       <map<string, string>>
 includes:      <enum | list<string>>
@@ -57,10 +58,14 @@ devDependencies:
   mcp:         <list<McpDependency>>
 compilation:   <CompilationConfig>
 policy:        <PolicyConfig>
-marketplace:   <MarketplaceConfig>           # OPTIONAL; marketplace authoring
+marketplace:   <MarketplaceConfig>       # OPTIONAL; marketplace authoring
 ```
 
-`marketplace:` is the source for `apm pack`'s marketplace output and is OPTIONAL. Repositories that do not publish a marketplace omit it entirely. The block, its schema, and the build flow are documented in the [Authoring a marketplace guide](../../guides/marketplace-authoring/). Within `marketplace:`, the inheritable fields `name`, `description`, and `version` default to the top-level values above and SHOULD be omitted unless an override is required.
+Two fields are REQUIRED at parse time: `name` and `version`. All other fields are OPTIONAL. Unknown top-level keys MUST be preserved by writers but MAY be ignored by resolvers.
+
+The `marketplace:` block is the source for `apm pack`'s marketplace output. Repositories that do not publish a marketplace omit it entirely. See [Section 7](#7-marketplace-authoring-block).
+
+Newly initialised projects (`apm init`) are scaffolded by the CLI; see [`apm init`](../cli/init/) for the templates.
 
 ---
 
@@ -89,7 +94,7 @@ marketplace:   <MarketplaceConfig>           # OPTIONAL; marketplace authoring
 |---|---|
 | **Type** | `string` |
 | **Required** | OPTIONAL |
-| **Description** | Brief human-readable description. |
+| **Description** | Brief human-readable description. Inherited by the `marketplace:` block when not overridden. |
 
 ### 3.4. `author`
 
@@ -111,41 +116,43 @@ marketplace:   <MarketplaceConfig>           # OPTIONAL; marketplace authoring
 
 | | |
 |---|---|
-| **Type** | `string \| list<string>` |
+| **Type** | `string` or `list<string>` |
 | **Required** | OPTIONAL |
-| **Default** | Auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `codex` if `.codex/` exists, `windsurf` if `.windsurf/` exists, `all` if multiple target folders exist, `minimal` if none |
-| **Allowed values** | `vscode` · `agents` · `copilot` · `claude` · `cursor` · `opencode` · `codex` · `gemini` · `windsurf` · `all` |
+| **Default** | Auto-detect from folder presence (see below). |
+| **Allowed values** | `vscode`, `agents`, `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `all` |
+
+Controls which output targets are generated during compilation, installation, and packing. Accepts a single string or a YAML list. Unknown values MUST raise a parse error at load time, naming the offending token.
 
-Controls which output targets are generated during compilation and installation. Accepts a single string or a list of strings. When unset, a conforming resolver SHOULD auto-detect based on folder presence. Unknown values MUST raise a parse error pointing at the offending token. Auto-detection applies only when `target:` is unset.
+When `target:` is omitted, a conforming resolver SHOULD auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `codex` if `.codex/` exists, `windsurf` if `.windsurf/` exists, `all` if multiple are present, `minimal` if none. Auto-detection applies only when `target:` is unset; once set, the field is authoritative.
 
 ```yaml
 # Single target
 target: copilot
 
-# Multiple targets -- flow-list form
+# Multiple targets (flow-list form)
 target: [claude, copilot]
 
-# Multiple targets -- block-list form (equivalent)
+# Multiple targets (block-list form, equivalent)
 target:
   - claude
   - copilot
 ```
 
-When a list is specified, only those targets are compiled, installed, and packed -- no output is generated for unlisted targets. `all` cannot be combined with other values.
+When a list is specified, only those targets are compiled, installed, and packed; no output is generated for unlisted targets. `all` cannot be combined with other values.
 
 | Value | Effect |
 |---|---|
-| `vscode` | Emits `AGENTS.md` at the project root (and per-directory files in distributed mode) |
-| `agents` | Alias for `vscode` |
-| `copilot` | Alias for `vscode` |
-| `claude` | Emits `CLAUDE.md` at the project root |
-| `cursor` | Emits to `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/` |
-| `opencode` | Emits to `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/` |
-| `codex` | Emits `AGENTS.md` and deploys skills to `.agents/skills/`, agents to `.codex/agents/` |
-| `gemini` | Emits `GEMINI.md` and deploys to `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json` |
-| `windsurf` | Emits `AGENTS.md` and deploys to `.windsurf/rules/`, `.windsurf/skills/`, `.windsurf/workflows/`, `.windsurf/hooks.json` |
+| `vscode` | Emits `AGENTS.md` at the project root (and per-directory files in distributed mode). |
+| `agents` | Alias for `vscode`. |
+| `copilot` | Alias for `vscode`. |
+| `claude` | Emits `CLAUDE.md` at the project root. |
+| `cursor` | Emits to `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`. |
+| `opencode` | Emits to `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`. |
+| `codex` | Emits `AGENTS.md` and deploys skills to `.agents/skills/`, agents to `.codex/agents/`. |
+| `gemini` | Emits `GEMINI.md` and deploys to `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json`. |
+| `windsurf` | Emits `AGENTS.md` and deploys to `.windsurf/rules/`, `.windsurf/skills/`, `.windsurf/workflows/`, `.windsurf/hooks.json`. |
 | `all` | All targets. Cannot be combined with other values in a list. |
-| `minimal` | AGENTS.md only at project root. **Auto-detected only** -- this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. |
+| `minimal` | `AGENTS.md` only at project root. **Auto-detected only**: this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. |
 
 ### 3.7. `type`
 
@@ -153,16 +160,16 @@ When a list is specified, only those targets are compiled, installed, and packed
 |---|---|
 | **Type** | `enum<string>` |
 | **Required** | OPTIONAL |
-| **Default** | None (behaviour driven by package content; synthesized plugin manifests use `hybrid`) |
-| **Allowed values** | `instructions` · `skill` · `hybrid` · `prompts` |
+| **Default** | None (behaviour driven by package content; synthesized plugin manifests use `hybrid`). |
+| **Allowed values** | `instructions`, `skill`, `hybrid`, `prompts` |
 
-Declares how the package's content is processed during install and compile. Currently behaviour is driven by package content (presence of `SKILL.md`, component directories, etc.); this field is reserved for future explicit overrides.
+Declares how the package's content is processed during install and compile. Today behaviour is driven by package content (presence of `SKILL.md`, component directories, etc.); this field is reserved for future explicit overrides.
 
 | Value | Behaviour |
 |---|---|
-| `instructions` | Compiled into AGENTS.md only. No skill directory created. |
-| `skill` | Installed as a native skill only. No AGENTS.md output. |
-| `hybrid` | Both AGENTS.md compilation and skill installation. |
+| `instructions` | Compiled into `AGENTS.md` only. No skill directory created. |
+| `skill` | Installed as a native skill only. No `AGENTS.md` output. |
+| `hybrid` | Both `AGENTS.md` compilation and skill installation. |
 | `prompts` | Commands/prompts only. No instructions or skills. |
 
 ### 3.8. `scripts`
@@ -171,24 +178,34 @@ Declares how the package's content is processed during install and compile. Curr
 |---|---|
 | **Type** | `map<string, string>` |
 | **Required** | OPTIONAL |
-| **Key pattern** | Script name (free-form string) |
-| **Value** | Shell command string |
-| **Description** | Named commands executed via `apm run <name>`. MUST support `--param key=value` substitution. |
+| **Key** | Script name (free-form string). |
+| **Value** | Shell command string. |
+
+Named commands executed via `apm run <name>`. The script body MUST support `--param key=value` substitution (`{key}` placeholders in the command string are replaced before execution).
+
+The script name `start` is the default invoked by a bare `apm run` (no name given) and SHOULD be present in publishable packages so consumers have a one-command entry point.
+
+```yaml
+scripts:
+  start:  "copilot -p 'README.prompt.md'"
+  review: "copilot -p 'code-review.prompt.md'"
+  impl:   "copilot -p 'implement-feature.prompt.md'"
+```
 
 ### 3.9. `includes`
 
 | | |
 |---|---|
-| **Type** | `string` (literal `auto`) `\| list<string>` |
+| **Type** | `string` (literal `auto`) or `list<string>` |
 | **Required** | OPTIONAL |
-| **Default** | Undeclared (legacy implicit auto-publish; flagged by `apm audit`) |
-| **Allowed values** | `auto` or a list of paths relative to the project root |
+| **Default** | Undeclared (legacy implicit auto-publish; flagged by `apm audit`). |
+| **Allowed values** | `auto` or a list of paths relative to the project root. |
 
 Declares which local `.apm/` content the project consents to publish when packing or deploying. Three forms are supported:
 
-1. **Undeclared** -- field omitted. Legacy behaviour: all local `.apm/` content is published as if `auto` were set. `apm audit` emits an `includes-consent` advisory (the check itself passes; the message recommends declaring `includes: auto`) whenever local content is deployed under this form.
-2. **`includes: auto`** -- explicit consent to publish all local `.apm/` content via the file scanner. No path enumeration required. Default for newly initialised projects.
-3. **`includes: [<path>, ...]`** -- explicit allow-list of paths the project consents to publish. Strongest governance form; changes are reviewable in PR diffs.
+1. **Undeclared** (field omitted). Legacy behaviour: all local `.apm/` content is published as if `auto` were set. `apm audit` emits an `includes-consent` advisory whenever local content is deployed under this form.
+2. **`includes: auto`**. Explicit consent to publish all local `.apm/` content via the file scanner. No path enumeration required. Default for newly initialised projects.
+3. **`includes: [<path>, ...]`**. Explicit allow-list of paths the project consents to publish. Strongest governance form; changes are reviewable in PR diffs.
 
 ```yaml
 # Form 1: undeclared (legacy; audit advisory)
@@ -203,9 +220,9 @@ includes: auto
 #   - .apm/skills/my-skill/
 ```
 
-**`includes:` is allow-list only.** There is no `exclude:` form. The field controls which `.apm/` content the project consents to publish; it cannot be used to fence off subdirectories of `.apm/` from the scanner. To keep maintainer-only primitives out of shipped artifacts, author them OUTSIDE `.apm/` and reference them via a local-path devDependency -- see [Dev-only Primitives](../../guides/dev-only-primitives/).
+`includes:` is allow-list only. There is no `exclude:` form. To keep maintainer-only primitives out of shipped artifacts, author them OUTSIDE `.apm/` and reference them via a local-path devDependency. See [Dev-only Primitives](../../guides/dev-only-primitives/).
 
-When `policy.manifest.require_explicit_includes` is `true` (see [Governance guide](../../enterprise/governance-guide/)), only form 3 passes the policy check; `auto` and undeclared are rejected at install/audit time by the `explicit-includes` policy check (not at YAML parse time).
+When `policy.manifest.require_explicit_includes` is `true` (see [Policy reference](../../enterprise/policy-reference/)), only form 3 passes; `auto` and undeclared are rejected at install/audit time by the `explicit-includes` check (not at YAML parse time).
 
 ### 3.10. `policy`
 
@@ -213,20 +230,22 @@ When `policy.manifest.require_explicit_includes` is `true` (see [Governance guid
 |---|---|
 | **Type** | `map<string, string>` |
 | **Required** | OPTIONAL |
-| **Description** | Consumer-side controls for org policy discovery and verification. All fields are optional; defaults preserve current fail-open install behaviour. |
+| **Description** | Consumer-side controls for org policy discovery and verification. All sub-keys are optional; defaults preserve current fail-open install behaviour. |
 
 ```yaml
 policy:
-  fetch_failure_default: warn      # warn | block, default warn (#829)
+  fetch_failure_default: warn      # warn | block (default warn)
   hash: "sha256:<hex>"             # optional consumer-side pin on the org policy bytes
   hash_algorithm: sha256           # sha256 (default) | sha384 | sha512
 ```
 
 | Sub-key | Type | Default | Allowed values | Semantic |
 |---|---|---|---|---|
-| `fetch_failure_default` | `string` | `warn` | `warn`, `block` | Posture when no enforceable policy is available -- covers fetch failures (`malformed`, `cache_miss_fetch_fail`, `garbage_response`) AND no-policy outcomes (`no_git_remote`, `absent`, `empty`). `warn` keeps installs unblocked when GitHub is unreachable or no org policy is published; `block` opts into fail-closed semantics for both `apm install` and `apm audit --ci`. See [Network failure semantics](../../enterprise/policy-reference/#95-network-failure-semantics). |
-| `hash` | `string` | unset | `<algo>:<hex-digest>` (e.g. `sha256:6a8c...e2f1`) | Pin on the raw bytes of the fetched leaf org policy. Verified before YAML parsing; mismatch is always fail-closed regardless of `fetch_failure_default`. See [Hash pin: `policy.hash`](../../enterprise/policy-reference/#96-hash-pin-policyhash-consumer-side-verification). |
-| `hash_algorithm` | `string` | `sha256` | `sha256`, `sha384`, `sha512` | Digest algorithm for `policy.hash`. Inferred from the `<algo>:` prefix when present; this field is the explicit override. MD5 and SHA-1 are rejected at parse time. |
+| `fetch_failure_default` | `string` | `warn` | `warn`, `block` | Posture when no enforceable policy is available (fetch failures or no-policy outcomes). `warn` keeps installs unblocked; `block` opts into fail-closed semantics for both `apm install` and `apm audit --ci`. |
+| `hash` | `string` | unset | `<algo>:<hex-digest>` | Pin on the raw bytes of the fetched leaf org policy. Verified before YAML parsing; mismatch is always fail-closed regardless of `fetch_failure_default`. |
+| `hash_algorithm` | `string` | `sha256` | `sha256`, `sha384`, `sha512` | Digest algorithm for `policy.hash`. Inferred from the `<algo>:` prefix when present. MD5 and SHA-1 are rejected at parse time. |
+
+Full semantics (network failure matrix, hash pin verification, policy precedence) live in the [Policy reference](../../enterprise/policy-reference/).
 
 ---
 
@@ -238,11 +257,11 @@ policy:
 | **Required** | OPTIONAL |
 | **Known keys** | `apm`, `mcp` |
 
-Contains two OPTIONAL lists: `apm` for agent primitive packages and `mcp` for MCP servers. Each list entry is either a string shorthand or a typed object. Additional keys MAY be present for future dependency types; conforming resolvers MUST ignore unknown keys for resolution but MUST preserve them when reading and rewriting manifests, to allow forward compatibility.
+Contains two OPTIONAL lists: `apm` for agent primitive packages and `mcp` for MCP servers. Each list entry is either a string shorthand or a typed object. Additional keys MAY be present for future dependency types; conforming resolvers MUST ignore unknown keys for resolution but MUST preserve them when reading and rewriting manifests.
 
 ---
 
-### 4.1. `dependencies.apm` — `list<ApmDependency>`
+### 4.1. `dependencies.apm` -- `list<ApmDependency>`
 
 Each element MUST be one of two forms: **string** or **object**.
 
@@ -251,20 +270,20 @@ Each element MUST be one of two forms: **string** or **object**.
 Grammar (ABNF-style):
 
 ```
-dependency     = url_form / shorthand_form / local_path_form
-url_form       = ("https://" / "http://" / "ssh://git@" / "git@") clone-url
-shorthand_form = [host "/"] owner "/" repo ["/" virtual_path] ["#" ref]
+dependency      = url_form / shorthand_form / local_path_form
+url_form        = ("https://" / "http://" / "ssh://git@" / "git@") clone-url
+shorthand_form  = [host "/"] owner "/" repo ["/" virtual_path] ["#" ref]
 local_path_form = ("./" / "../" / "/" / "~/" / ".\\" / "..\\" / "~\\") path
 ```
 
-`clone-url` MAY include a `:port` segment on `https://`, `http://`, and `ssh://git@` forms (e.g. `ssh://git@host:7999/owner/repo.git`). The SCP shorthand `git@host:path` cannot carry a port — `:` is the path separator in that form. When a port is present, APM preserves it across all clone attempts: the SSH attempt uses `ssh://host:PORT/...` and the HTTPS fallback uses `https://host:PORT/...` (same port on both protocols).
+`clone-url` MAY include a `:port` segment on `https://`, `http://`, and `ssh://git@` forms (e.g. `ssh://git@host:7999/owner/repo.git`). The SCP shorthand `git@host:path` cannot carry a port because `:` is the path separator in that form. When a port is present, APM preserves it across all clone attempts: the SSH attempt uses `ssh://host:PORT/...` and the HTTPS fallback uses `https://host:PORT/...` (same port on both protocols).
 
 | Segment | Required | Pattern | Description |
 |---|---|---|---|
 | `host` | OPTIONAL | FQDN (e.g. `gitlab.com`) | Git host. Defaults to `github.com`. |
-| `port` | OPTIONAL | `1`–`65535` | Non-default port on `ssh://`, `https://`, `http://` clone URLs. Not expressible in SCP shorthand. |
-| `owner/repo` | REQUIRED | 2+ path segments of `[a-zA-Z0-9._-]+` | Repository path. GitHub uses exactly 2 segments (`owner/repo`). Non-GitHub hosts MAY use nested groups (e.g. `gitlab.com/group/sub/repo`). |
-| `virtual_path` | OPTIONAL | Path segments after repo | Subdirectory or file within the repo. See §4.1.3. |
+| `port` | OPTIONAL | `1`-`65535` | Non-default port on `ssh://`, `https://`, `http://` clone URLs. Not expressible in SCP shorthand. |
+| `owner/repo` | REQUIRED | 2+ path segments of `[a-zA-Z0-9._-]+` | Repository path. GitHub uses exactly 2 segments. Non-GitHub hosts MAY use nested groups (e.g. `gitlab.com/group/sub/repo`). |
+| `virtual_path` | OPTIONAL | Path segments after repo | Subdirectory or file within the repo. See Section 4.1.3. |
 | `ref` | OPTIONAL | Branch, tag, or commit SHA | Git reference. Commit SHAs matched by `^[a-f0-9]{7,40}$`. Semver tags matched by `^v?\d+\.\d+\.\d+`. |
 
 **Examples:**
@@ -272,7 +291,7 @@ local_path_form = ("./" / "../" / "/" / "~/" / ".\\" / "..\\" / "~\\") path
 ```yaml
 dependencies:
   apm:
-    # GitHub shorthand (default host) — each line shows a syntax variant
+    # GitHub shorthand (default host); each line shows a syntax variant
     - microsoft/apm-sample-package                # latest (lockfile pins commit SHA)
     - microsoft/apm-sample-package#v1.0.0         # pinned to tag (immutable)
     - microsoft/apm-sample-package#main           # branch ref (may change over time)
@@ -314,7 +333,7 @@ REQUIRED when the shorthand is ambiguous (e.g. nested-group repos with virtual p
 | `ref` | `string` | OPTIONAL | Branch, tag, or commit SHA | Git reference to checkout. |
 | `alias` | `string` | OPTIONAL | `^[a-zA-Z0-9._-]+$` | Local alias. |
 
-Remote dependency (git URL + sub-path):
+Remote dependency (git URL plus sub-path):
 
 ```yaml
 - git: https://gitlab.com/acme/repo.git
@@ -337,7 +356,7 @@ Monorepo sibling reference (`git: parent`):
   path: skills/shared
 ```
 
-The literal sentinel `git: parent` is valid only inside a transitively resolved package whose clone coordinates are known to the resolver. APM expands `parent` to the consumer's `host`, `repo_url`, and resolved `ref`, with `virtual_path` set from `path`. The lockfile records the **expanded** coordinates -- `parent` MUST NOT appear as durable identity (`repo_url` / `source`). `path` is REQUIRED for `git: parent` and is normalised to a single relative path; absolute paths and `..` traversal are refused. `ref` and `alias` overrides are accepted; when `ref` is omitted the parent's resolved ref is inherited.
+The literal sentinel `git: parent` is valid only inside a transitively resolved package whose clone coordinates are known to the resolver. APM expands `parent` to the consumer's `host`, `repo_url`, and resolved `ref`, with `virtual_path` set from `path`. The lockfile records the **expanded** coordinates: `parent` MUST NOT appear as durable identity (`repo_url` / `source`). `path` is REQUIRED for `git: parent` and is normalised to a single relative path; absolute paths and `..` traversal are refused. `ref` and `alias` overrides are accepted; when `ref` is omitted the parent's resolved ref is inherited.
 
 #### 4.1.3. Virtual Packages
 
@@ -348,7 +367,7 @@ A dependency MAY target a subdirectory or a file within a repository rather than
 | **File** | `virtual_path` ends in `.prompt.md`, `.instructions.md`, `.agent.md`, or `.chatmode.md` | `owner/repo/prompts/review.prompt.md` |
 | **Subdirectory** | `virtual_path` does not match any file extension above | `owner/repo/skills/security` |
 
-Classification is by extension only -- never by path segment. A path like `owner/repo/collections/security` (no extension) is **Subdirectory**: the actual on-disk shape (APM package with `apm.yml`, skill bundle, or plugin) is resolved at fetch time by probing for `apm.yml` first.
+Classification is by extension only, never by path segment. A path like `owner/repo/collections/security` (no extension) is a **Subdirectory**: the on-disk shape (APM package with `apm.yml`, skill bundle, or plugin) is resolved at fetch time by probing for `apm.yml` first.
 
 > **Removed (#1094):** the legacy `.collection.yml` / `.collection.yaml` virtual-package form is no longer supported. Convert any such reference to an `apm.yml` with a `dependencies:` section, then reference the resulting subdirectory as a regular subdirectory virtual package.
 
@@ -364,26 +383,26 @@ Conforming writers MUST normalise entries to canonical form on write. `github.co
 
 ---
 
-### 4.2. `dependencies.mcp` — `list<McpDependency>`
+### 4.2. `dependencies.mcp` -- `list<McpDependency>`
 
 Each element MUST be one of two forms: **string** or **object**.
 
 #### 4.2.1. String Form
 
-A plain registry reference: `io.github.github/github-mcp-server`
+A plain registry reference: `io.github.github/github-mcp-server`.
 
 #### 4.2.2. Object Form
 
 | Field | Type | Required | Constraint | Description |
 |---|---|---|---|---|
 | `name` | `string` | REQUIRED | Non-empty | Server identifier (registry name or custom name). |
-| `transport` | `enum<string>` | Conditional | `stdio` · `sse` · `http` · `streamable-http` | Transport protocol. REQUIRED when `registry: false`. Values are MCP transport names, not URL schemes: remote variants connect over HTTPS. |
-| `env` | `map<string, string>` | OPTIONAL | | Environment variable overrides. Values may contain `${VAR}`, `${env:VAR}`, or `${input:<id>}` references — see §4.2.4. |
-| `args` | `dict` or `list` | OPTIONAL | | Dict for overlay variable overrides (registry), list for positional args (self-defined). |
+| `transport` | `enum<string>` | Conditional | `stdio`, `sse`, `http`, `streamable-http` | Transport protocol. REQUIRED when `registry: false`. Values are MCP transport names, not URL schemes; remote variants connect over HTTPS. |
+| `env` | `map<string, string>` | OPTIONAL | | Environment variable overrides. Values may contain `${VAR}`, `${env:VAR}`, or `${input:<id>}` references; see Section 4.2.4. |
+| `args` | `dict` or `list` | OPTIONAL | | Dict for overlay variable overrides (registry); list for positional args (self-defined). |
 | `version` | `string` | OPTIONAL | | Pin to a specific server version. |
 | `registry` | `bool` or `string` | OPTIONAL | Default: `true` (public registry) | `false` = self-defined (private) server. String = custom registry URL. |
-| `package` | `enum<string>` | OPTIONAL | `npm` · `pypi` · `oci` | Package manager type hint. |
-| `headers` | `map<string, string>` | OPTIONAL | | Custom HTTP headers for remote endpoints. Values may contain `${VAR}`, `${env:VAR}`, or `${input:<id>}` references — see §4.2.4. |
+| `package` | `enum<string>` | OPTIONAL | `npm`, `pypi`, `oci` | Package manager type hint. |
+| `headers` | `map<string, string>` | OPTIONAL | | Custom HTTP headers for remote endpoints. Same variable syntax as `env`. |
 | `tools` | `list<string>` | OPTIONAL | Default: `["*"]` | Restrict which tools are exposed. |
 | `url` | `string` | Conditional | | Endpoint URL. REQUIRED when `registry: false` and `transport` is `http`, `sse`, or `streamable-http`. |
 | `command` | `string` | Conditional | Single binary path; no embedded whitespace unless `args` is also present | Binary path. REQUIRED when `registry: false` and `transport` is `stdio`. |
@@ -426,16 +445,16 @@ Values in `headers` and `env` may contain three placeholder syntaxes. APM resolv
 | Syntax | Source | VS Code | Copilot CLI / Codex |
 |---|---|---|---|
 | `${VAR}` | host environment | Translated to `${env:VAR}` (resolved at server-start by VS Code) | Resolved at install time from env (or interactive prompt) |
-| `${env:VAR}` | host environment | Native — passed through verbatim | Resolved at install time from env (or interactive prompt) |
-| `${input:<id>}` | user prompt | Native — VS Code prompts at runtime | Not supported — use `${VAR}` or `${env:VAR}` instead |
+| `${env:VAR}` | host environment | Native; passed through verbatim | Resolved at install time from env (or interactive prompt) |
+| `${input:<id>}` | user prompt | Native; VS Code prompts at runtime | Not supported; use `${VAR}` or `${env:VAR}` instead |
 | `<VAR>` (legacy) | host environment | Not recognized | Resolved at install time (kept for back-compat) |
 
 - **VS Code** has native `${env:VAR}` and `${input:VAR}` interpolation, so APM emits placeholders rather than baking secrets into `mcp.json`. Bare `${VAR}` is normalized to `${env:VAR}` for you.
 - **Copilot CLI** has no runtime interpolation, so APM resolves `${VAR}`, `${env:VAR}`, and the legacy `<VAR>` at install time using `os.environ` (or an interactive prompt when missing). Resolved values are not re-scanned, so a value containing literal `${...}` text is preserved.
-- **Codex** currently resolves only the legacy `<VAR>` placeholder at install time; `${VAR}` / `${env:VAR}` are passed through verbatim in the Codex adapter today.
-- **Recommended:** Use `${VAR}` or `${env:VAR}` in all new manifests — they work on every target that supports remote MCP servers. `<VAR>` is legacy and only resolved by Copilot CLI and Codex; in VS Code it would silently render as literal text in the generated config.
-- **Registry-backed servers** — APM auto-generates input prompts from registry metadata for `${input:...}`.
-- **Self-defined servers** — APM detects `${input:...}` patterns in `apm.yml` and generates matching input definitions automatically.
+- **Codex** currently resolves only the legacy `<VAR>` placeholder at install time; `${VAR}` / `${env:VAR}` are passed through verbatim.
+- **Recommended:** Use `${VAR}` or `${env:VAR}` in all new manifests. They work on every target that supports remote MCP servers. `<VAR>` is legacy and only resolved by Copilot CLI and Codex; in VS Code it would silently render as literal text.
+- **Registry-backed servers**: APM auto-generates input prompts from registry metadata for `${input:...}`.
+- **Self-defined servers**: APM detects `${input:...}` patterns in `apm.yml` and generates matching input definitions automatically.
 
 GitHub Actions templates (`${{ ... }}`) are intentionally left untouched.
 
@@ -462,7 +481,7 @@ dependencies:
 | **Required** | OPTIONAL |
 | **Known keys** | `apm`, `mcp` |
 
-Development-only dependencies installed locally but excluded from plugin bundles (`apm pack`, plugin format is the default). Uses the same structure as [`dependencies`](#4-dependencies).
+Development-only dependencies installed locally but excluded from plugin bundles produced by [`apm pack`](../cli/pack/) (plugin format is the default). Uses the same structure as [`dependencies`](#4-dependencies).
 
 ```yaml
 devDependencies:
@@ -471,13 +490,13 @@ devDependencies:
     - owner/lint-rules#v2.0.0
 ```
 
-Created automatically by `apm init --plugin`. Use [`apm install --dev`](../cli-commands/#apm-install---install-dependencies-and-deploy-local-content) to add packages:
+Created automatically by `apm init --plugin`. Use [`apm install --dev`](../cli/install/) to add packages:
 
 ```bash
 apm install --dev owner/test-helpers
 ```
 
-Plain `apm install` (no flag) deploys both `dependencies` and `devDependencies`. There is currently no `--omit=dev` flag -- the dev/prod separation kicks in at `apm pack` (plugin format, the default). The local-content scanner that builds plugin bundles also operates on `.apm/` only and does not consult the devDep marker. To keep maintainer-only primitives out of shipped artifacts, author them outside `.apm/` and reference them via a local-path devDependency. See [Dev-only Primitives](../../guides/dev-only-primitives/).
+Plain `apm install` (no flag) deploys both `dependencies` and `devDependencies`. There is no `--omit=dev` flag today; the dev/prod separation kicks in at `apm pack` (plugin format, the default). The local-content scanner that builds plugin bundles operates on `.apm/` only and does not consult the devDep marker. To keep maintainer-only primitives out of shipped artifacts, author them outside `.apm/` and reference them via a local-path devDependency. See [Dev-only Primitives](../../guides/dev-only-primitives/).
 
 Local-path devDependency example:
 
@@ -491,25 +510,25 @@ devDependencies:
 
 ## 6. Compilation
 
-The `compilation` key is OPTIONAL. It controls `apm compile` behaviour. All fields have sensible defaults; omitting the entire section is valid.
+The `compilation` key is OPTIONAL. It controls [`apm compile`](../cli/compile/) behaviour. All fields have sensible defaults; omitting the entire section is valid.
 
 | Field | Type | Default | Constraint | Description |
 |---|---|---|---|---|
-| `target` | `enum<string>` | `all` | `vscode` · `agents` · `claude` · `codex` · `gemini` · `windsurf` · `all` | Output target (same values as §3.6). Defaults to `all` when set explicitly in compilation config. |
-| `strategy` | `enum<string>` | `distributed` | `distributed` · `single-file` | `distributed` generates per-directory AGENTS.md files. `single-file` generates one monolithic file. |
+| `target` | `enum<string>` | `all` | Same values as Section 3.6 | Output target. Defaults to `all` when set explicitly in compilation config. |
+| `strategy` | `enum<string>` | `distributed` | `distributed`, `single-file` | `distributed` generates per-directory `AGENTS.md` files. `single-file` generates one monolithic file. |
 | `single_file` | `bool` | `false` | | Legacy alias. When `true`, overrides `strategy` to `single-file`. |
 | `output` | `string` | `AGENTS.md` | File path | Custom output path for the compiled file. |
-| `chatmode` | `string` | — | | Chatmode filter for compilation. |
+| `chatmode` | `string` | unset | | Chatmode filter for compilation. |
 | `resolve_links` | `bool` | `true` | | Resolve relative Markdown links in primitives. |
 | `source_attribution` | `bool` | `true` | | Include source-file origin comments in compiled output. |
 | `exclude` | `list<string>` or `string` | `[]` | Glob patterns | Directories to skip during compilation (e.g. `apm_modules/**`). |
-| `placement` | `object` | — | | Placement tuning. See §6.1. |
+| `placement` | `object` | unset | | Placement tuning. See Section 6.1. |
 
 ### 6.1. `compilation.placement`
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `min_instructions_per_file` | `int` | `1` | Minimum instruction count to warrant a separate AGENTS.md file. |
+| `min_instructions_per_file` | `int` | `1` | Minimum instruction count to warrant a separate `AGENTS.md` file. |
 
 ```yaml
 compilation:
@@ -525,51 +544,145 @@ compilation:
 
 ---
 
-## 7. Lockfile (`apm.lock.yaml`)
+## 7. Marketplace Authoring Block
 
-After successful dependency resolution, a conforming resolver MUST write a lockfile capturing the exact resolved state. The lockfile MUST be a YAML file named `apm.lock.yaml` at the project root. It SHOULD be committed to version control.
+The OPTIONAL `marketplace:` block declares the metadata `apm pack` needs to emit a Claude-Code-compatible plugin marketplace (`marketplace.json`). It is read by `apm marketplace` subcommands and ignored by everything else. Repositories that do not publish a marketplace omit it entirely.
 
-### 7.1. Structure
+The block was previously a standalone `marketplace.yml` file (still loadable for back-compat); the in-`apm.yml` form is canonical and is what [`apm marketplace init`](../cli/marketplace/) scaffolds.
+
+### 7.1. Inheritance
+
+Three keys are inherited from the top-level manifest unless explicitly overridden inside `marketplace:`:
+
+| Key | Inherited from |
+|---|---|
+| `name` | top-level `name` |
+| `description` | top-level `description` |
+| `version` | top-level `version` |
+
+Overrides exist for the rare case where the published marketplace identity differs from the package identity. Inherited values are omitted from the generated `marketplace.json` per the Claude-Code convention.
+
+### 7.2. Block Fields
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `string` | OPTIONAL (override) | inherited | Override of top-level `name`. |
+| `description` | `string` | OPTIONAL (override) | inherited | Override of top-level `description`. |
+| `version` | `string` | OPTIONAL (override) | inherited | Override of top-level `version`. Validated as semver. |
+| `owner` | `Owner` | REQUIRED | -- | Marketplace publisher identity. See Section 7.3. |
+| `output` | `string` | OPTIONAL | `.claude-plugin/marketplace.json` | Output path for the generated marketplace JSON. |
+| `metadata` | `object` | OPTIONAL | `{}` | Free-form metadata forwarded verbatim to `marketplace.json` (e.g. `homepage`, `support`). |
+| `build` | `Build` | OPTIONAL | `tagPattern: "v{version}"` | Build configuration for resolving package refs. See Section 7.4. |
+| `packages` | `list<Package>` | OPTIONAL | `[]` | Packages exposed in the marketplace. See Section 7.5. |
+
+Unknown keys inside `marketplace:` are rejected at parse time.
+
+### 7.3. `marketplace.owner`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | REQUIRED | Owner display name (org or person). |
+| `email` | `string` | OPTIONAL | Contact email. |
+| `url` | `string` | OPTIONAL | Owner homepage. |
+
+```yaml
+marketplace:
+  owner:
+    name: contoso
+    url:  https://github.com/contoso
+    email: maintainers@contoso.example
+```
+
+### 7.4. `marketplace.build`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `tagPattern` | `string` | `v{version}` | Pattern used to construct git tags for packages. MUST contain at least one of `{version}` or `{name}`. Per-package overrides live on `packages[].tag_pattern`. |
+
+### 7.5. `marketplace.packages`
+
+Each entry MUST be a mapping. Unknown keys are rejected.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | REQUIRED | Package identifier as it appears in the marketplace. |
+| `source` | `string` | REQUIRED | `<owner>/<repo>` (remote) or `./<path>` (local). Must match the source pattern; path traversal (`..`) is refused. |
+| `subdir` | `string` | OPTIONAL | Subdirectory inside the source repo. Path-traversal-validated. Ignored for local sources. |
+| `version` | `string` | Conditional | Semver range (e.g. `^1.0.0`, `~2.1.0`, `>=3.0`). Stored as a string; resolution happens at pack time. REQUIRED for remote packages unless `ref` is given. |
+| `ref` | `string` | Conditional | Explicit git ref (SHA, tag, or branch). Overrides `version` range when both are present. REQUIRED for remote packages unless `version` is given. |
+| `tag_pattern` | `string` | OPTIONAL | Per-package override of `build.tagPattern`. Same placeholder rule. |
+| `include_prerelease` | `bool` | `false` | Whether semver pre-release tags are eligible for resolution. |
+| `description` | `string` | OPTIONAL | Pass-through to `marketplace.json`. |
+| `homepage` | `string` | OPTIONAL | Pass-through to `marketplace.json`. |
+| `tags` | `list<string>` | OPTIONAL | Pass-through to `marketplace.json`. Limited to 50 tags, 100 chars each. |
+| `keywords` | `list<string>` | OPTIONAL | Alias merged into `tags` (deduplicated). |
+| `author` | `string` or `object` | OPTIONAL | Either a non-empty string (treated as `name`) or an object with `name` (REQUIRED), `email`, `url`. |
+| `license` | `string` | OPTIONAL | Pass-through (SPDX identifier). |
+| `repository` | `string` | OPTIONAL | Pass-through. |
+
+Remote packages MUST declare at least one of `version` or `ref`. Local packages (sources beginning with `./`) skip git resolution and have no version requirement.
+
+### 7.6. Complete Marketplace Block
 
 ```yaml
-lockfile_version: "1"
-generated_at:     <ISO 8601 timestamp>
-apm_version:      <string>
-dependencies:                              # YAML list (not a map)
-  - repo_url:        <string>              # Resolved clone URL
-    host:            <string>              # Git host (OPTIONAL, e.g. "gitlab.com")
-    port:            <int>                 # Non-default git port (OPTIONAL, 1-65535; omitted when default)
-    resolved_commit: <string>              # Full commit SHA
-    resolved_ref:    <string>              # Branch/tag that was resolved
-    version:         <string>              # Package version from its apm.yml
-    virtual_path:    <string>              # Virtual package path (if applicable)
-    is_virtual:      <bool>                # True for virtual (file/subdirectory) packages
-    depth:           <int>                 # 1 = direct, 2+ = transitive
-    resolved_by:     <string>              # Parent dependency (transitive only)
-    package_type:    <string>              # Package type (e.g. "apm_package", "marketplace_plugin", "meta_package")
-    content_hash:    <string>              # SHA-256 of package file tree (e.g. "sha256:a1b2c3...")
-    is_dev:          <bool>                # True for devDependencies
-    deployed_files:  <list<string>>        # Workspace-relative paths of installed files
-mcp_servers:       <list<string>>          # MCP dependency references managed by APM (OPTIONAL, e.g. "io.github.github/github-mcp-server")
+marketplace:
+  # name, description, version inherit from top-level apm.yml
+  owner:
+    name: contoso
+    url:  https://github.com/contoso
+
+  output: .claude-plugin/marketplace.json
+
+  metadata:
+    homepage: https://contoso.example/marketplace
+
+  build:
+    tagPattern: "v{version}"
+
+  packages:
+    - name: code-review
+      source: contoso/code-review
+      version: "^1.0.0"
+      description: AI code-review skills
+      tags: [review, quality]
+
+    - name: pinned-helper
+      source: contoso/pinned-helper
+      ref: main                              # explicit ref overrides version
+      tag_pattern: "pinned-helper-v{version}"
+
+    - name: local-tool                       # local-path package
+      source: ./packages/local-tool
+      description: Vendored tool
 ```
 
-### 7.2. Resolver Behaviour
+The legacy standalone `marketplace.yml` (top-level keys, no `marketplace:` wrapper) is still loadable but deprecated; new repositories SHOULD use the in-`apm.yml` form scaffolded by `apm marketplace init`.
+
+---
+
+## 8. Lockfile (`apm.lock.yaml`)
+
+After successful dependency resolution, a conforming resolver MUST write a lockfile capturing the exact resolved state. The lockfile MUST be a YAML file named `apm.lock.yaml` at the project root and SHOULD be committed to version control.
+
+The full lockfile schema is specified in the [Lockfile specification](../lockfile-spec/). At a minimum, every resolver MUST record `lockfile_version`, `dependencies[].repo_url`, `dependencies[].resolved_commit`, and `dependencies[].deployed_files` so subsequent installs are reproducible and `apm uninstall` can remove every placed file.
 
-1. **First install** — Resolve all dependencies, write `apm.lock.yaml`.
-2. **Subsequent installs** — Read `apm.lock.yaml`, use locked commit SHAs. A resolver SHOULD skip download if local checkout already matches.
-3. **`--update` flag** — Re-resolve from `apm.yml`, overwrite lockfile.
+Resolver behaviour:
+
+1. **First install** -- Resolve all dependencies, write `apm.lock.yaml`.
+2. **Subsequent installs** -- Read `apm.lock.yaml`, use locked commit SHAs. A resolver SHOULD skip download when the local checkout already matches.
+3. **`--update` flag** -- Re-resolve from `apm.yml`, overwrite the lockfile.
 
 ---
 
-## 8. Integrator Contract
+## 9. Integrator Contract
 
 Any runtime adopting this format (e.g. GitHub Agentic Workflows, CI systems, IDEs) MUST implement these steps:
 
-1. **Parse** — Read `apm.yml` as YAML. Validate the two REQUIRED fields (`name`, `version`) and the `dependencies` object shape.
-2. **Resolve `dependencies.apm`** — For each entry, clone/fetch the git repo (respecting `ref`), locate the `.apm/` directory (or virtual path), and extract primitives.
-3. **Resolve `dependencies.mcp`** — For each entry, resolve from the MCP registry or validate self-defined transport config per §4.2.3.
-4. **Transitive resolution** — Resolved packages MAY contain their own `apm.yml` with further dependencies, forming a dependency tree. Resolvers MUST resolve transitively. Conflicts are merged at instruction level (by `applyTo` pattern), not file level.
-5. **Write lockfile** — Record exact commit SHAs and deployed file paths in `apm.lock.yaml` per §7.
+1. **Parse** -- Read `apm.yml` as YAML. Validate the two REQUIRED fields (`name`, `version`) and the `dependencies` object shape.
+2. **Resolve `dependencies.apm`** -- For each entry, clone or fetch the git repo (respecting `ref`), locate the `.apm/` directory (or virtual path), and extract primitives.
+3. **Resolve `dependencies.mcp`** -- For each entry, resolve from the MCP registry or validate self-defined transport config per Section 4.2.3.
+4. **Transitive resolution** -- Resolved packages MAY contain their own `apm.yml` with further dependencies, forming a dependency tree. Resolvers MUST resolve transitively. Conflicts are merged at instruction level (by `applyTo` pattern), not file level.
+5. **Write lockfile** -- Record exact commit SHAs and deployed file paths in `apm.lock.yaml` per Section 8 and the [Lockfile specification](../lockfile-spec/).
 
 ---
 
@@ -581,10 +694,12 @@ version: 1.0.0
 description: AI-native web application
 author: Contoso
 license: MIT
-target: all
-type: hybrid              # instructions | skill | hybrid | prompts
+target: [claude, copilot]
+type: hybrid
+includes: auto
 
 scripts:
+  start:  "copilot -p 'README.prompt.md'"
   review: "copilot -p 'code-review.prompt.md'"
   impl:   "copilot -p 'implement-feature.prompt.md'"
 
@@ -615,6 +730,19 @@ compilation:
     - "apm_modules/**"
   placement:
     min_instructions_per_file: 1
+
+policy:
+  fetch_failure_default: warn
+
+marketplace:
+  owner:
+    name: contoso
+    url:  https://github.com/contoso
+  packages:
+    - name: code-review
+      source: contoso/code-review
+      version: "^1.0.0"
+      tags: [review, quality]
 ```
 
 ---
@@ -624,3 +752,4 @@ compilation:
 | Version | Date | Changes |
 |---|---|---|
 | 0.1 | 2026-03-06 | Initial Working Draft. |
+| 0.2 | 2026-05-10 | Added Section 7 (Marketplace authoring block). Documented `scripts.start` as the default `apm run` entry point. Cross-links updated to `../cli/<verb>/` paths. ASCII-only enforcement. |
\ No newline at end of file
diff --git a/docs/src/content/docs/reference/policy-schema.md b/docs/src/content/docs/reference/policy-schema.md
new file mode 100644
index 000000000..155a1a537
--- /dev/null
+++ b/docs/src/content/docs/reference/policy-schema.md
@@ -0,0 +1,231 @@
+---
+title: apm-policy.yml schema
+description: Canonical field reference for apm-policy.yml -- the file org admins publish to govern apm install, apm audit --ci, and related commands.
+sidebar:
+  order: 5
+---
+
+The `apm-policy.yml` schema. One file per org or repo. Loaded by `apm install`, `apm audit --ci`, `apm policy status`, and the install preflight before any package is written to disk.
+
+For the workflow (where to put the file, how to roll it out), see [Govern with apm-policy.yml](../../enterprise/apm-policy-getting-started/). For CLI usage of `apm policy status`, see [apm policy](../cli/policy/). For the wider governance picture (rulesets, registry proxy, CI gating), see [Governance overview](../../enterprise/governance-overview/).
+
+## File location
+
+Discovery order, in priority:
+
+1. `--policy <ref>` flag on `apm install` or `apm audit`.
+2. Auto-discovery from the project's git remote -- fetches `<owner>/.github/apm-policy.yml` via the GitHub Contents API.
+
+The `<ref>` accepts:
+
+- A local file path.
+- An `https://` URL (plain `http://` is rejected).
+- The literal string `org` (force git-remote auto-discovery).
+- `<owner>/<repo>` shorthand (defaults to `github.com`).
+- `<host>/<owner>/<repo>` for GHES or other hosts.
+
+## Top-level fields
+
+| Field              | Type                | Default          | Required | Notes                                                                             |
+|--------------------|---------------------|------------------|----------|-----------------------------------------------------------------------------------|
+| `name`             | string              | `""`             | no       | Human label. Surfaces in `apm policy status`.                                     |
+| `version`          | string              | `""`             | no       | Free-form. Useful for change tracking.                                            |
+| `extends`          | string or null      | `null`           | no       | Parent policy reference. See [Inheritance](#inheritance).                         |
+| `enforcement`      | enum                | `warn`           | no       | `off` / `warn` / `block`. See [Enforcement modes](#enforcement-modes).            |
+| `fetch_failure`    | enum                | `warn`           | no       | `warn` / `block`. Behavior when a remote policy cannot be fetched or parsed.      |
+| `cache`            | object              | `{ttl: 3600}`    | no       | Cache settings for remote policy fetches.                                         |
+| `dependencies`    | object              | see section      | no       | Rules over APM dependencies.                                                       |
+| `mcp`              | object              | see section      | no       | Rules over MCP servers (direct and transitive).                                   |
+| `compilation`      | object              | see section      | no       | Rules over `apm compile` outputs.                                                 |
+| `manifest`         | object              | see section      | no       | Rules over `apm.yml` content.                                                     |
+| `unmanaged_files`  | object              | see section      | no       | Rules over files in target directories not tracked by the lockfile.               |
+
+Unknown top-level keys produce a warning, never an error -- so newer policy files load on older clients.
+
+## Enforcement modes
+
+`enforcement` is the global outcome dial. Per-rule severities feed into this dial:
+
+| Mode    | Behavior                                                                                       |
+|---------|------------------------------------------------------------------------------------------------|
+| `off`   | Policy is loaded and reported, but never blocks. Useful during rollout.                        |
+| `warn`  | Violations print `[!]` warnings but exit code stays 0. Default.                                |
+| `block` | Violations print `[x]` errors and exit non-zero. `apm install` aborts before writing to disk. |
+
+`fetch_failure` controls fail-closed behavior on the policy fetch itself (network down, malformed YAML, host mismatch). Set to `block` in production CI to refuse to run when policy cannot be loaded.
+
+## cache
+
+| Field | Type    | Default | Notes                                                                  |
+|-------|---------|---------|------------------------------------------------------------------------|
+| `ttl` | integer | `3600`  | Seconds. Must be `> 0`. Applies to remote `extends:` and URL fetches. |
+
+## dependencies
+
+Rules over the `dependencies:` and `mcp:` blocks declared in consumer `apm.yml` files.
+
+| Field                | Type                  | Default          | Notes                                                                                       |
+|----------------------|-----------------------|------------------|---------------------------------------------------------------------------------------------|
+| `allow`              | list of patterns or null | `null`        | `null` = no opinion. `[]` = nothing allowed. `[...]` = only these.                          |
+| `deny`               | list of patterns      | `[]`             | Always wins over `allow`.                                                                   |
+| `require`            | list of refs          | `[]`             | Packages every consumer manifest must include.                                              |
+| `require_resolution` | enum                  | `project-wins`   | `project-wins` / `policy-wins` / `block` -- how to resolve version conflicts on required packages. |
+| `max_depth`          | integer               | `50`             | Maximum transitive dependency depth. Must be `> 0`.                                         |
+
+Patterns are matched against `<owner>/<repo>` (or `<host>/<owner>/<repo>`). Wildcards via shell-style globs, e.g. `contoso/*`.
+
+## mcp
+
+Rules over MCP server references, including transitive ones declared by deep dependencies.
+
+| Field              | Type                  | Default | Notes                                                                                |
+|--------------------|-----------------------|---------|--------------------------------------------------------------------------------------|
+| `allow`            | list or null          | `null`  | Same null/empty/list semantics as `dependencies.allow`.                              |
+| `deny`             | list                  | `[]`    | Always wins.                                                                         |
+| `transport.allow`  | list or null          | `null`  | Allowed transports: `stdio`, `sse`, `http`, `streamable-http`. `null` = no opinion. |
+| `self_defined`     | enum                  | `warn`  | `allow` / `warn` / `deny` -- treatment of MCP servers defined inline in `apm.yml`.   |
+| `trust_transitive` | boolean               | `false` | When `false`, transitive MCP servers must be explicitly allow-listed.                |
+
+## compilation
+
+| Field                  | Type                  | Default | Notes                                                                          |
+|------------------------|-----------------------|---------|--------------------------------------------------------------------------------|
+| `target.allow`         | list or null          | `null`  | Allowed `apm compile` targets, e.g. `vscode`, `claude`, `all`.                |
+| `target.enforce`       | string or null        | `null`  | If set, `apm compile` must select this target.                                 |
+| `strategy.enforce`     | enum or null          | `null`  | `distributed` / `single-file`. Pins the compilation strategy.                  |
+| `source_attribution`   | boolean               | `false` | Require source-attribution headers in compiled outputs.                        |
+
+## manifest
+
+| Field                       | Type                    | Default | Notes                                                                  |
+|-----------------------------|-------------------------|---------|------------------------------------------------------------------------|
+| `required_fields`           | list of strings         | `[]`    | Top-level keys every `apm.yml` must declare (e.g. `description`, `license`). |
+| `scripts`                   | enum                    | `allow` | `allow` / `deny` -- whether `scripts:` blocks are permitted.            |
+| `content_types`             | object or null          | `null`  | `{allow: [...]}`. Restricts primitive content types (e.g. `skill`, `prompt`). |
+| `require_explicit_includes` | boolean                 | `false` | When `true`, manifests must declare an explicit `includes:` list rather than rely on directory globs. |
+
+## unmanaged_files
+
+Files in primitive target directories that are not recorded in `apm.lock.yaml`.
+
+| Field         | Type           | Default  | Notes                                                                            |
+|---------------|----------------|----------|----------------------------------------------------------------------------------|
+| `action`      | enum           | `ignore` | `ignore` / `warn` / `deny`. `deny` blocks installs that would leave drift.      |
+| `directories` | list of paths  | `[]`     | Subset of target directories to check. Empty = all known target directories.     |
+
+## Inheritance
+
+`extends:` resolves a parent policy. Maximum chain depth is **5**; cycles are rejected.
+
+`extends:` accepts:
+
+- `org` -- the same org's `.github/apm-policy.yml`.
+- `<owner>/<repo>` -- another repo on the same host.
+- `https://...` -- a direct URL.
+
+For supply-chain safety, `extends:` references are pinned to the **leaf policy's host** -- a policy fetched from `github.com` cannot extend one on `evil.example.com`.
+
+### Merge rules (tighten-only)
+
+The child can tighten the parent but never relax it:
+
+| Field family                | Merge rule                                                                       |
+|-----------------------------|----------------------------------------------------------------------------------|
+| `enforcement`               | Stricter wins (`block` > `warn` > `off`).                                        |
+| `fetch_failure`             | Child overrides if set.                                                          |
+| `cache.ttl`                 | `min(parent, child)`.                                                            |
+| `*.allow` lists             | Set intersection. `null` is transparent (no opinion).                            |
+| `*.deny` / `require` lists  | Union, deduplicated, parent order preserved.                                     |
+| `dependencies.max_depth`    | `min(parent, child)`.                                                            |
+| `dependencies.require_resolution` | Stricter wins (`block` > `policy-wins` > `project-wins`).                  |
+| `mcp.self_defined`          | Stricter wins (`deny` > `warn` > `allow`).                                       |
+| `mcp.trust_transitive`      | Logical AND (`true` only if both sides true).                                    |
+| `manifest.scripts`          | Stricter wins (`deny` > `allow`).                                                |
+| `unmanaged_files.action`    | Stricter wins (`deny` > `warn` > `ignore`).                                      |
+| `compilation.*.enforce`     | First non-null wins (parent precedence).                                         |
+| `compilation.source_attribution` | Logical OR.                                                                 |
+
+A merged chain is reported by `apm policy status` with each layer's source attributed.
+
+## Allow-list semantics
+
+For every `allow:` field, the three states are distinct:
+
+| Value    | Meaning                                      | Inheritance behavior            |
+|----------|----------------------------------------------|---------------------------------|
+| omitted  | "no opinion"                                 | Transparent during merge.       |
+| `[]`     | "explicitly nothing"                         | Intersects to nothing downstream. |
+| `[...]`  | "only these patterns"                        | Intersected with child list.    |
+
+`deny` and `require` lists are always tuples (omitted = empty); they accumulate by union during merge.
+
+## Complete example
+
+```yaml
+# .github/apm-policy.yml -- shipped from contoso/.github
+name: contoso-baseline
+version: "2025.05"
+extends: contoso-enterprise/policy
+
+enforcement: block
+fetch_failure: block
+
+cache:
+  ttl: 1800
+
+dependencies:
+  allow:
+    - contoso/*
+    - microsoft/apm-skills-*
+  deny:
+    - "*/legacy-*"
+  require:
+    - contoso/security-baseline
+  require_resolution: policy-wins
+  max_depth: 25
+
+mcp:
+  allow:
+    - github/github-mcp-server
+    - contoso/internal-mcp-*
+  transport:
+    allow:
+      - stdio
+      - streamable-http
+  self_defined: deny
+  trust_transitive: false
+
+compilation:
+  target:
+    allow:
+      - vscode
+      - claude
+  strategy:
+    enforce: distributed
+  source_attribution: true
+
+manifest:
+  required_fields:
+    - description
+    - license
+  scripts: deny
+  content_types:
+    allow:
+      - skill
+      - prompt
+      - instruction
+  require_explicit_includes: true
+
+unmanaged_files:
+  action: deny
+  directories:
+    - .github/instructions
+    - .github/prompts
+```
+
+## See also
+
+- [apm policy](../cli/policy/) -- the `apm policy status` command.
+- [Govern with apm-policy.yml](../../enterprise/apm-policy-getting-started/) -- end-to-end rollout guide.
+- [Enforce in CI](../../enterprise/enforce-in-ci/) -- wiring `apm audit --ci` into branch protection.
+- [Governance overview](../../enterprise/governance-overview/) -- the full enterprise control surface.
diff --git a/docs/src/content/docs/reference/targets-matrix.md b/docs/src/content/docs/reference/targets-matrix.md
new file mode 100644
index 000000000..8c2566292
--- /dev/null
+++ b/docs/src/content/docs/reference/targets-matrix.md
@@ -0,0 +1,192 @@
+---
+title: Targets matrix
+description: Per-harness deployment matrix - detection signals, deploy directories, supported primitives, and file conventions for every APM target.
+sidebar:
+  order: 6
+---
+
+The canonical reference for what APM deploys, where, for every supported
+harness. Use this page to choose a target, debug an unexpected deploy
+location, or confirm whether a primitive is supported on a given tool.
+
+For background on the target model, see
+[Primitives and targets](../../concepts/primitives-and-targets/). For
+the runtime CLI surface, see [`apm targets`](../cli/targets/) and
+[`apm compile`](../cli/compile/). For the primitive types themselves,
+see [Primitive types](../primitive-types/).
+
+## Summary
+
+| Target          | Deploy root            | instructions | prompts | agents | skills | commands | hooks | mcp |
+|-----------------|------------------------|:------------:|:-------:|:------:|:------:|:--------:|:-----:|:---:|
+| copilot         | `.github/`             |     [x]      |   [x]   |  [x]   |  [x]   |   [ ]    |  [x]  | [x] |
+| claude          | `.claude/`             |     [x]      |   [ ]   |  [x]   |  [x]   |   [x]    |  [x]  | [x] |
+| cursor          | `.cursor/`             |     [x]      |   [ ]   |  [x]   |  [x]   |   [x]    |  [x]  | [x] |
+| codex           | `.codex/` + `.agents/` |     [ ]      |   [ ]   |  [x]   |  [x]   |   [ ]    |  [x]  | [x] |
+| gemini          | `.gemini/`             |     [ ]      |   [ ]   |  [ ]   |  [x]   |   [x]    |  [x]  | [x] |
+| opencode        | `.opencode/`           |     [ ]      |   [ ]   |  [x]   |  [x]   |   [x]    |  [ ]  | [x] |
+| windsurf        | `.windsurf/`           |     [x]      |   [ ]   |  [x]   |  [x]   |   [x]    |  [x]  | [x] |
+| agent-skills    | `.agents/`             |     [ ]      |   [ ]   |  [ ]   |  [x]   |   [ ]    |  [ ]  | [ ] |
+
+Skills always deploy to the cross-tool `.agents/skills/` directory by
+default (see [Skills convergence](#skills-convergence) below). All other
+primitives land under each target's own root.
+
+`copilot-cowork` (Microsoft 365 Copilot) is gated behind an experimental
+flag and not listed above. See [Experimental](../experimental/).
+
+## Detection and resolution
+
+`apm install` and `apm compile` resolve the active target list with this
+priority:
+
+1. `--target` / `--all` on the command line.
+2. `targets:` in `apm.yml`.
+3. Auto-detection from filesystem signals (table below).
+
+If none of the above produce a target, the command falls back to
+`copilot`. Use [`apm targets`](../cli/targets/) to preview the resolved
+list before `compile` or `install`.
+
+### Detection signal whitelist
+
+| Target   | Signals (any one activates the target)        |
+|----------|-----------------------------------------------|
+| claude   | `.claude/` directory, or `CLAUDE.md` file     |
+| copilot  | `.github/copilot-instructions.md` file        |
+| cursor   | `.cursor/` directory, or `.cursorrules` file  |
+| codex    | `.codex/` directory                           |
+| gemini   | `.gemini/` directory, or `GEMINI.md` file     |
+| opencode | `.opencode/` directory                        |
+| windsurf | `.windsurf/` directory                        |
+
+`agent-skills` and `copilot-cowork` are never auto-detected. Select them
+explicitly with `--target`.
+
+## copilot
+
+GitHub Copilot (CLI and IDE).
+
+- **Detection.** `.github/copilot-instructions.md`.
+- **Deploy directory.** `.github/` at project scope; `~/.copilot/` at user scope.
+- **Supported primitives.** instructions, prompts, agents, skills, hooks, mcp.
+- **File conventions.**
+  - instructions: `.github/instructions/<name>.instructions.md`
+  - prompts: `.github/prompts/<name>.prompt.md`
+  - agents: `.github/agents/<name>.agent.md`
+  - skills: `.agents/skills/<name>/SKILL.md`
+  - hooks: `.github/hooks/<name>.json`
+  - generated: `.github/copilot-instructions.md` (compile output)
+- **User scope.** Partial. `prompts` and `instructions` are not supported at user scope; user-scope deploys land under `~/.copilot/`, not `~/.github/`.
+
+## claude
+
+Claude Code.
+
+- **Detection.** `.claude/` directory, or `CLAUDE.md`.
+- **Deploy directory.** `.claude/` (project and user scope; user scope honors `CLAUDE_CONFIG_DIR` if set).
+- **Supported primitives.** instructions, agents, skills, commands, hooks, mcp. (No `prompts`.)
+- **File conventions.**
+  - instructions: `.claude/rules/<name>.md`
+  - agents: `.claude/agents/<name>.md`
+  - commands: `.claude/commands/<name>.md`
+  - skills: `.agents/skills/<name>/SKILL.md`
+  - hooks: merged into `.claude/settings.json`
+- **Compile output.** `CLAUDE.md` and per-rule files under `.claude/rules/`.
+
+## cursor
+
+Cursor.
+
+- **Detection.** `.cursor/` directory, or legacy `.cursorrules` file.
+- **Deploy directory.** `.cursor/`.
+- **Supported primitives.** instructions, agents, skills, commands, hooks, mcp. (No `prompts`.)
+- **File conventions.**
+  - instructions: `.cursor/rules/<name>.mdc`
+  - agents: `.cursor/agents/<name>.md`
+  - commands: `.cursor/commands/<name>.md`
+  - skills: `.agents/skills/<name>/SKILL.md`
+  - hooks: `.cursor/hooks.json`
+- **User scope.** Partial. `instructions` is excluded at user scope; Cursor reads global rules from its Settings UI rather than from disk.
+- **Caveat.** Command files use the shared `claude_command` transformer today; Cursor-specific frontmatter keys (`author`, `mcp`, `parameters`, ...) are dropped at install time and surfaced via diagnostics.
+
+## codex
+
+OpenAI Codex CLI.
+
+- **Detection.** `.codex/` directory.
+- **Deploy directory.** `.codex/` plus `.agents/` for skills.
+- **Supported primitives.** agents, skills, hooks, mcp. (No `instructions`, `prompts`, or `commands`.)
+- **File conventions.**
+  - agents: `.codex/agents/<name>.toml`
+  - skills: `.agents/skills/<name>/SKILL.md`
+  - hooks: `.codex/hooks.json`
+- **Compile output.** `AGENTS.md` only. Per-file instructions are not installed for Codex.
+
+## gemini
+
+Gemini CLI.
+
+- **Detection.** `.gemini/` directory, or `GEMINI.md`.
+- **Deploy directory.** `.gemini/` (project and user scope).
+- **Supported primitives.** commands, skills, hooks, mcp.
+- **File conventions.**
+  - commands: `.gemini/commands/<name>.toml`
+  - skills: `.agents/skills/<name>/SKILL.md`
+  - hooks: merged into `.gemini/settings.json`
+- **Compile output.** `GEMINI.md`. Gemini CLI does not read per-file rules from `.gemini/rules/`, so `instructions` is compile-only.
+
+## opencode
+
+OpenCode.
+
+- **Detection.** `.opencode/` directory.
+- **Deploy directory.** `.opencode/` at project scope; `~/.config/opencode/` at user scope.
+- **Supported primitives.** agents, commands, skills, mcp.
+- **File conventions.**
+  - agents: `.opencode/agents/<name>.md`
+  - commands: `.opencode/commands/<name>.md`
+  - skills: `.agents/skills/<name>/SKILL.md`
+- **Caveat.** OpenCode has no hooks concept; the `hooks` primitive is silently skipped for this target.
+
+## windsurf
+
+Windsurf / Cascade.
+
+- **Detection.** `.windsurf/` directory.
+- **Deploy directory.** `.windsurf/` at project scope; `~/.codeium/windsurf/` at user scope.
+- **Supported primitives.** instructions, agents, skills, commands, hooks, mcp.
+- **File conventions.**
+  - instructions: `.windsurf/rules/<name>.md`
+  - agents: `.windsurf/skills/<name>/SKILL.md` (Cascade auto-invokes skill-shaped agents by description)
+  - skills: `.windsurf/skills/<name>/SKILL.md`
+  - commands: `.windsurf/workflows/<name>.md`
+  - hooks: `.windsurf/hooks.json`
+- **User scope.** Partial. `instructions` is excluded at user scope; Windsurf stores global memory in a single `~/.codeium/windsurf/memories/global_rules.md` file with a different format.
+
+## agent-skills
+
+Cross-client shared skills directory.
+
+- **Detection.** Never auto-detected. Select with `--target agent-skills`.
+- **Deploy directory.** `.agents/`.
+- **Supported primitives.** skills only.
+- **File conventions.** `.agents/skills/<name>/SKILL.md`.
+- **Use case.** Author-time target for shipping a SKILL bundle that any Skills-aware client (Codex, Copilot CLI, Claude Code, etc.) can read without per-tool deployment.
+
+## Skills convergence
+
+By default, every target with a `skills` primitive deploys to `.agents/skills/<name>/SKILL.md` rather than under the target root. This matches the cross-tool agent skills convention so a single skill bundle serves every harness.
+
+To restore the pre-convergence per-target layout (skills land under each target's own root), use the `--legacy-skill-paths` flag on `apm install` or set `APM_LEGACY_SKILL_PATHS=1`.
+
+## MCP servers
+
+MCP is not a `TargetProfile` primitive; it is wired by a separate integrator that writes per-client config files (e.g. `.vscode/mcp.json`, `.cursor/mcp.json`, `.claude.json`) for every target with an MCP client adapter. The matrix above marks `mcp` supported when an adapter exists. See [`apm mcp`](../cli/mcp/) for the runtime surface.
+
+## See also
+
+- [`apm targets`](../cli/targets/) - inspect resolved targets at runtime.
+- [`apm compile`](../cli/compile/) - target selection and compile flags.
+- [Primitive types](../primitive-types/) - what each primitive is.
+- [Primitives and targets](../../concepts/primitives-and-targets/) - conceptual model.
diff --git a/docs/src/content/docs/troubleshooting/common-errors.md b/docs/src/content/docs/troubleshooting/common-errors.md
new file mode 100644
index 000000000..2c60a8860
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/common-errors.md
@@ -0,0 +1,263 @@
+---
+title: Common Errors
+description: Catalog of the most-hit APM errors with one-line cause and fix per entry.
+sidebar:
+  order: 1
+---
+
+Found a confusing error? Search this page first. Each entry shows the error string APM prints, the underlying cause, and the shortest fix. Deeper guides are linked under "See also".
+
+Errors are grouped by the surface that produces them: install, compile, audit, run, and auth/network.
+
+## Install
+
+### `apm.yml not found. Run 'apm init' first.`
+
+```
+apm.yml not found. Run 'apm init' first.
+```
+
+Cause: APM was invoked in a directory with no manifest, or the manifest has a different name.
+
+Fix: run `apm init` to scaffold a manifest, or `cd` into the project that owns the `apm.yml`.
+
+See also: [../reference/cli/init/](../reference/cli/init/)
+
+### `lockfile not found at <path>; run 'apm install' to generate it`
+
+```
+lockfile not found at apm.lock.yaml; run 'apm install' to generate it
+```
+
+Cause: a command that needs a resolved dependency graph (drift check, audit, compile against lockfile) ran before the project had ever been installed.
+
+Fix: run `apm install` once to produce `apm.lock.yaml`, then re-run the original command.
+
+See also: [./install-failures/](./install-failures/), [../reference/lockfile-spec/](../reference/lockfile-spec/)
+
+### `<pkg>: not found in lockfile`
+
+(message similar to)
+
+```
+<owner>/<repo>: not found in lockfile
+1 ref mismatch(es) -- run 'apm install' to update lockfile
+```
+
+Cause: a dependency exists in `apm.yml` but has no entry in `apm.lock.yaml`. Most often hit in CI when the lockfile was not regenerated after editing the manifest.
+
+Fix: run `apm install` locally to refresh `apm.lock.yaml` and commit the result. Do not hand-edit the lockfile.
+
+See also: [./install-failures/](./install-failures/), [../reference/lockfile-spec/](../reference/lockfile-spec/)
+
+### `<pkg>: manifest ref '<ref>' != lockfile ref '<ref>'`
+
+```
+<owner>/<repo>: manifest ref 'v2' != lockfile ref 'v1'
+N ref mismatch(es) -- run 'apm install' to update lockfile
+```
+
+Cause: the version or ref pinned in `apm.yml` was changed without re-running install. The lockfile is stale.
+
+Fix: run `apm install` and commit the updated `apm.lock.yaml`.
+
+See also: [./install-failures/](./install-failures/)
+
+### `Drift detected: N file(s)`
+
+```
+[!] Drift detected: N file(s)
+[i] Run 'apm install' to re-sync deployed files with the lockfile.
+```
+
+Cause: deployed primitive files in the project differ from the content recorded in `apm.lock.yaml`. Either the files were edited locally, or the lockfile was updated without re-running install.
+
+Fix: run `apm install` to re-deploy from the cache. If the local edits were intentional, vendor them into the source package or a local override before re-installing.
+
+See also: [./install-failures/](./install-failures/)
+
+### `Content hash mismatch for <pkg>: expected <a>, got <b>`
+
+```
+[x] Content hash mismatch for <owner>/<repo>: expected <sha>, got <sha>.
+The downloaded content differs from the lockfile record. This may
+indicate a supply-chain attack. Use 'apm install --update' to accept
+new content and update the lockfile.
+```
+
+Cause: the bytes APM downloaded for a locked dependency do not match the `content_hash` recorded in `apm.lock.yaml`. Usually a force-pushed tag, a mutated branch, or a tampered mirror.
+
+Fix: investigate the upstream package before accepting. If the change is legitimate, run `apm install --update` to re-pin and commit the new hash.
+
+See also: [./install-failures/](./install-failures/), [../reference/lockfile-spec/](../reference/lockfile-spec/)
+
+### `Install blocked by org policy -- see violations above`
+
+```
+[x] Install blocked by org policy -- see violations above
+```
+
+Cause: an org-level policy (compilation target, dependency allowlist, security baseline) rejected one or more dependencies. The per-violation lines printed above this message identify the offending packages and rules.
+
+Fix: read the violations above the summary line, remove or replace the offending packages, or update org policy if the rule is wrong.
+
+See also: [./policy-debugging/](./policy-debugging/)
+
+### `from unapproved host(s): <host>`
+
+(message similar to)
+
+```
+[x] Refusing to install from unapproved host(s): <host>.
+```
+
+Cause: a dependency resolves to a host outside the configured allowlist.
+
+Fix: add the host to the allowlist, or pass `--allow-insecure-host <host>` for a one-off install. Do not bypass the allowlist in CI.
+
+See also: [./policy-debugging/](./policy-debugging/)
+
+### `Race condition: concurrent checkout failed integrity for <url> @ <sha>`
+
+```
+Race condition: concurrent checkout failed integrity for <url> @ <sha>
+```
+
+Cause: two `apm install` processes raced on the same cache shard and the loser's integrity check failed. The cache shard lock is per-shard with a 120s default timeout.
+
+Fix: re-run `apm install`. If it reproduces, ensure only one install runs at a time per `APM_CACHE_DIR`. In CI, give each job its own cache directory.
+
+See also: [./install-failures/](./install-failures/)
+
+## Compile
+
+### `No primitives matched`
+
+(message similar to) printed when compile produces zero output.
+
+Cause: no primitives in the project (or filtered subset) match the active target's compilation rules. Common causes: wrong `--target`, missing frontmatter, glob filter matched nothing, or org policy stripped everything.
+
+Fix: run `apm compile --dry-run --verbose` to see what was discovered and why each primitive was skipped.
+
+See also: [./compile-zero-output-warning/](./compile-zero-output-warning/), [../reference/cli/compile/](../reference/cli/compile/)
+
+### `[x] No harness detected`
+
+```
+[x] No harness detected
+```
+
+Cause: the project has no harness markers (`.github/copilot/`, `.claude/`, `.cursor/`, ...) and no `targets:` block in `apm.yml`. APM no longer defaults to copilot.
+
+Fix: pass `--target <harness>` on the command, or declare `targets:` in `apm.yml`. Run `apm targets` to list supported harnesses.
+
+See also: [../reference/cli/targets/](../reference/cli/targets/), [../reference/targets-matrix/](../reference/targets-matrix/)
+
+### `[x] Multiple harnesses detected: <a>, <b>`
+
+Cause: APM found markers for more than one harness and cannot pick.
+
+Fix: pin a target with `--target <harness>` or declare `targets:` in `apm.yml`. Use `apm install --dry-run` to preview each option.
+
+See also: [../reference/cli/targets/](../reference/cli/targets/)
+
+### `[x] Unknown target '<value>'`
+
+```
+[x] Unknown target '<value>'
+Valid targets: claude, copilot, cursor, ...
+```
+
+Cause: the value passed to `--target` (or listed in `apm.yml` `targets:`) is not a known harness.
+
+Fix: run `apm targets` for the canonical list. Check for typos.
+
+See also: [../reference/cli/targets/](../reference/cli/targets/), [../reference/targets-matrix/](../reference/targets-matrix/)
+
+## Audit
+
+### `Policy violation: <dep> -- <reason>`
+
+```
+[x] Policy violation: <owner>/<repo>@<ref> -- <reason>
+```
+
+Cause: a dependency failed an org policy check during install or audit. The reason field names the rule.
+
+Fix: see [./policy-debugging/](./policy-debugging/) for resolving each rule type. For audit-only reporting, use `apm audit --format sarif` or `--format json` to feed the findings into your code-scanning pipeline.
+
+See also: [./policy-debugging/](./policy-debugging/), [../reference/cli/audit/](../reference/cli/audit/)
+
+### `Policy hash mismatch from <source>: expected <a>, got <b>`
+
+Cause: the org policy file fetched from the configured source does not match the pinned hash. Either the policy was updated upstream and the pin is stale, or the source was tampered with.
+
+Fix: confirm the upstream change is legitimate, then update the policy pin in your APM config to the new hash.
+
+See also: [./policy-debugging/](./policy-debugging/)
+
+## Run
+
+### `Script or prompt '<name>' not found.`
+
+```
+Script or prompt '<name>' not found.
+Available scripts in apm.yml: <list>
+```
+
+Cause: `apm run <name>` could not match `<name>` to a script in `apm.yml`, an auto-discovered prompt file, or an installable virtual package.
+
+Fix: check the available scripts list printed under the error. To list discoverable prompts, run `apm list`. To install a remote prompt, use `apm install <owner>/<repo>/path/to/prompt.prompt.md`.
+
+See also: [../reference/cli/run/](../reference/cli/run/), [../reference/cli/list/](../reference/cli/list/)
+
+### `No such command '<x>'`
+
+```
+Error: No such command '<x>'.
+```
+
+Cause: standard Click error. The subcommand does not exist, or you are on an older APM version that lacks it.
+
+Fix: run `apm --help` for the current command list. Upgrade APM if the command was added in a newer release.
+
+See also: [../reference/cli/](../reference/cli/), [./migration/](./migration/)
+
+## Auth and network
+
+### `Authentication failed for <host>`
+
+```
+[x] Authentication failed for <host>
+... -- check `gh auth status` and `GITHUB_APM_PAT`
+```
+
+Cause: the remote host rejected APM's credentials, or no credentials were available. Token resolution order for GitHub: per-org `GITHUB_APM_PAT_<ORG>`, then `GITHUB_APM_PAT`, then `GITHUB_TOKEN`, then `GH_TOKEN`, then `gh auth token`, then git credential helpers.
+
+Fix: set `GITHUB_APM_PAT` (or run `gh auth login`) with a token that has access to the dependency's repo. For Azure DevOps, set `ADO_APM_PAT`. The diagnostic block printed under the error names the host and the resolution attempts that failed.
+
+See also: [./install-failures/](./install-failures/)
+
+### `TLS verification failed`
+
+```
+TLS verification failed -- if you're behind a corporate proxy or
+firewall, set the REQUESTS_CA_BUNDLE environment variable to the
+path of your organisation's CA bundle (a PEM file) and retry.
+```
+
+Cause: Python's TLS stack rejected the server certificate. Almost always a corporate proxy doing TLS interception with a CA that is not in the system trust store.
+
+Fix: export `REQUESTS_CA_BUNDLE=/path/to/corporate-ca.pem` and retry. Do not disable TLS verification.
+
+See also: [./ssl-issues/](./ssl-issues/)
+
+### Network timeout or host unreachable
+
+(no fixed string; surfaces as `requests` / git transport errors after the 15s API or 30s git timeout)
+
+Cause: the host is unreachable, the proxy is down, or DNS is failing.
+
+Fix: confirm `curl -v https://<host>` works from the same shell. Check `HTTPS_PROXY` / `NO_PROXY` are set correctly. Re-run `apm install --verbose` to see which host failed and on which leg (API probe vs git fetch).
+
+See also: [./ssl-issues/](./ssl-issues/), [./install-failures/](./install-failures/)
diff --git a/docs/src/content/docs/troubleshooting/compile-zero-output-warning.md b/docs/src/content/docs/troubleshooting/compile-zero-output-warning.md
new file mode 100644
index 000000000..5353d4d17
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/compile-zero-output-warning.md
@@ -0,0 +1,120 @@
+---
+title: "Compile produced no output"
+description: "Diagnose why apm compile finished without writing any files."
+sidebar:
+  order: 3
+---
+
+`apm compile` exited cleanly but printed:
+
+```text
+[!] Compilation completed but produced no output files. Check that target
+    directories exist (e.g. .github/, .claude/) or set 'target:' in apm.yml
+    / pass --target explicitly.
+```
+
+This is APM refusing to claim success when zero files were written. The compile ran, the target list resolved, but every primitive was either missing, filtered, or unsupported by the resolved targets. Walk the ladder below in order.
+
+## Diagnostic ladder
+
+### 1. Confirm the resolved target list
+
+```bash
+apm targets
+```
+
+If the active list is empty, no harness was detected and no `target:` was pinned. APM has nothing to write against. Either:
+
+- Create one of the canonical signals (`.claude/`, `.github/copilot-instructions.md`, `.cursor/`, `.codex/`, `.gemini/` or `GEMINI.md`, `.opencode/`, `.windsurf/`).
+- Pin targets in `apm.yml` (`target: [claude, copilot]`) or pass `--target` to `apm compile`.
+
+See [`apm targets`](../reference/cli/targets/) and the [manifest schema](../reference/manifest-schema/).
+
+### 2. Confirm primitives are discovered
+
+```bash
+apm deps
+```
+
+Each installed package row shows per-type counts (`Prompts`, `Instructions`, `Agents`, `Skills`, `Hooks`). If every column is `-`, the project ships nothing to compile. Either you haven't installed a package yet, or your local `.apm/` tree is empty.
+
+To check the local tree directly:
+
+```bash
+find .apm -name '*.instructions.md' -o -name '*.prompt.md' -o \
+         -name '*.agent.md' -o -name '*.chatmode.md' -o -name 'SKILL.md'
+```
+
+### 3. Confirm the includes filter is not excluding everything
+
+If `apm.yml` declares an `includes:` filter on a dependency, only matching primitives are integrated. A typo or overly narrow glob can silently drop the entire package contribution.
+
+```yaml
+dependencies:
+  apm:
+    - name: org/security-pack
+      includes: [skills]   # prompts and instructions are excluded
+```
+
+See [manifest schema](../reference/manifest-schema/) for the full include/exclude semantics.
+
+### 4. Confirm the target supports the primitive types you ship
+
+This is the most common cause. Each target supports a subset of primitive types. Shipping only types a target rejects produces zero output for that target.
+
+Authoritative matrix: [targets matrix](../reference/targets-matrix/).
+
+[i] Ship only `prompts` to `claude`? Zero output -- Claude has no `prompts` slot.
+[i] Ship only `instructions` to `codex`? Zero output -- Codex has no `instructions` slot.
+
+### 5. Confirm policy is not dropping content
+
+Org policy rules can deny specific primitives, sources, or transformers. If a policy denies what would otherwise be written, the file count drops to zero.
+
+```bash
+apm policy status
+```
+
+See [policy schema](../reference/policy-schema/).
+
+## Worked examples
+
+### "I added a skill but compile produced nothing"
+
+```bash
+apm targets        # what will be written to?
+apm deps           # is the skill counted?
+```
+
+If `apm targets` is empty, the project has no detected harness -- create `.claude/` (or any canonical dir) or pin `target:` in `apm.yml`. If `apm deps` shows the skill but compile still emits nothing, every active target lacks `skills` support (rare -- most targets do support skills via `.agents/SKILL.md`).
+
+### "I targeted `cursor` but my command files don't appear"
+
+Cursor commands route through the shared `claude_command` transformer, which only preserves the common frontmatter subset (`description`, `allowed-tools`, `model`, `argument-hint`, `input`). If your command file has *only* Cursor-specific keys (`author`, `mcp`, `parameters`, ...), nothing the transformer recognises is left to write. Add at least a `description:` field, then re-run:
+
+```bash
+apm compile --target cursor
+```
+
+Dropped keys are surfaced via diagnostics at install time -- check `apm install` output for warnings.
+
+### "All targets resolve, but only some integrations land"
+
+Expected when targets and primitive types don't intersect uniformly. Example: a project with `target: [claude, gemini]` shipping `instructions` + `commands` writes:
+
+- `claude`: instructions (as rules) + commands -- both land.
+- `gemini`: commands only -- instructions are silently skipped because Gemini has no `rules/` slot.
+
+Cross-check against the [targets matrix](../reference/targets-matrix/) before filing a bug.
+
+## Still nothing?
+
+Re-run with `--verbose` for source attribution and per-target stats:
+
+```bash
+apm compile --verbose
+```
+
+If `*_files_written` and `*_files_generated` are all zero across the stats block, every target was a no-op. Use the ladder above to find which step silently filtered everything out.
+
+Reference: [`apm compile`](../reference/cli/compile/), [`apm targets`](../reference/cli/targets/), [`apm view`](../reference/cli/view/), [targets matrix](../reference/targets-matrix/), [manifest schema](../reference/manifest-schema/), [policy schema](../reference/policy-schema/).
diff --git a/docs/src/content/docs/troubleshooting/index.md b/docs/src/content/docs/troubleshooting/index.md
new file mode 100644
index 000000000..a5fb0ee8b
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/index.md
@@ -0,0 +1,37 @@
+---
+title: Troubleshooting
+description: Triage table for the most common APM failures, plus links to deep-dive recovery guides.
+sidebar:
+  order: 0
+---
+
+Something broke. Find your symptom in the table, follow the link.
+
+## Triage by symptom
+
+| Symptom                                                              | Go to                                                              |
+|----------------------------------------------------------------------|--------------------------------------------------------------------|
+| Don't recognize the error message                                    | [Common errors](./common-errors/)                                  |
+| `apm install` failed (auth, network, lockfile, cache, partial)       | [Install failures](./install-failures/)                            |
+| `apm compile` exited 0 but no files were written                     | [Compile produced no output](./compile-zero-output-warning/)       |
+| `TLS verification failed`, `unable to get local issuer certificate`  | [SSL / TLS issues](./ssl-issues/)                                  |
+| `Install blocked by org policy`, rule violation, allowlist mismatch  | [Debugging policy failures](./policy-debugging/)                   |
+| Migrating from `awd-cli`, lockfile schema bump, target switch        | [Migration paths](./migration/)                                    |
+
+## When to escalate
+
+If you're past the relevant page and still stuck, gather these and open an issue:
+
+```bash
+apm --version
+APM_DEBUG=1 apm <failing-command> --verbose 2>&1 | tee /tmp/apm-debug.log
+apm cache info
+```
+
+Attach the log, your `apm.yml`, your `apm.lock.yaml`, and the `apm cache info` output to the [APM issue tracker](https://github.com/microsoft/apm/issues).
+
+## Related references
+
+- [Environment variables](../reference/environment-variables/) -- everything APM reads from the shell.
+- [`apm cache`](../reference/cli/cache/) -- diagnose and recover the local cache.
+- [`apm policy`](../reference/cli/policy/) -- inspect what policy applies and why.
diff --git a/docs/src/content/docs/troubleshooting/install-failures.md b/docs/src/content/docs/troubleshooting/install-failures.md
new file mode 100644
index 000000000..1f9766489
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/install-failures.md
@@ -0,0 +1,261 @@
+---
+title: "Install failures"
+description: "Diagnose and recover from apm install failures: auth, network, lockfile, cache, and partial installs."
+sidebar:
+  order: 2
+---
+
+When `apm install` fails, work through these sections in order. Most failures fall into one of five buckets: auth, network/TLS, lockfile, cache, or a partial install left behind by a previous crash.
+
+For TLS-specific failures see [SSL / TLS issues](./ssl-issues/). For the full flag reference see [`apm install`](../reference/cli/install/). For env-var precedence see [Environment variables](../reference/environment-variables/).
+
+## 1. Authentication failures
+
+Symptom: `403`, `401`, "authentication required", or "Repository not found" on a repo you can clone manually with `git`.
+
+### GitHub precedence chain
+
+APM resolves a token per host class. For `github.com`, GHE Cloud, and GHES the order is:
+
+```text
+GITHUB_APM_PAT_<ORG>   ->   GITHUB_APM_PAT   ->   GITHUB_TOKEN   ->   GH_TOKEN   ->   gh auth token   ->   git credential helper
+```
+
+`<ORG>` is the package owner uppercased with non-alphanumeric chars replaced by `_` (so `my-org/pkg` -> `GITHUB_APM_PAT_MY_ORG`). Per-org PATs win over the global `GITHUB_APM_PAT`. See [Environment variables](../reference/environment-variables/) for the full table.
+
+Common fixes:
+
+- [+] Set a fine-grained PAT with `Contents: Read` on the org/repo:
+  ```bash
+  export GITHUB_APM_PAT=ghp_xxx
+  ```
+- [+] For multi-org installs, scope per org:
+  ```bash
+  export GITHUB_APM_PAT_ACME=ghp_acme_xxx
+  export GITHUB_APM_PAT_CONTOSO=ghp_contoso_xxx
+  ```
+- [!] `gh auth token` is consulted only after the env vars. If the wrong identity is logged in via `gh`, set `GITHUB_APM_PAT` explicitly to override.
+
+### GHES (GitHub Enterprise Server)
+
+Set `GITHUB_HOST` to switch host classification, transport, and the auth chain:
+
+```bash
+export GITHUB_HOST=ghe.example.com
+export GITHUB_APM_PAT=ghp_ghes_xxx
+```
+
+The same precedence chain applies; the host just changes which API endpoint is hit and which clone URLs are composed.
+
+### GitLab (SaaS and self-managed)
+
+```text
+GITLAB_APM_PAT   ->   GITLAB_TOKEN   ->   git credential helper
+```
+
+For self-managed:
+
+```bash
+export GITLAB_HOST=gitlab.example.com
+export GITLAB_APM_PAT=glpat-xxx
+```
+
+If you operate multiple GitLab instances, list them in `APM_GITLAB_HOSTS` (comma-separated) so APM classifies them as GitLab-class.
+
+### Azure DevOps
+
+```text
+ADO_APM_PAT   ->   AAD bearer (via az cli)   ->   none
+```
+
+```bash
+export ADO_APM_PAT=ado_pat_xxx
+```
+
+If both are set and the request still fails, APM emits a hint that `ADO_APM_PAT` was rejected and the AAD bearer was tried. Unset the PAT to test AAD auth alone:
+
+```bash
+unset ADO_APM_PAT
+az login
+apm install
+```
+
+### Test your token
+
+Bypass APM and probe the host directly:
+
+```bash
+# GitHub / GHE / GHES
+curl -H "Authorization: Bearer $GITHUB_APM_PAT" \
+     "https://${GITHUB_HOST:-api.github.com}/repos/<owner>/<repo>"
+
+# GitLab
+curl -H "PRIVATE-TOKEN: $GITLAB_APM_PAT" \
+     "https://${GITLAB_HOST:-gitlab.com}/api/v4/projects/<owner>%2F<repo>"
+
+# Azure DevOps
+curl -u ":${ADO_APM_PAT}" \
+     "https://dev.azure.com/<org>/<project>/_apis/git/repositories/<repo>?api-version=7.0"
+```
+
+A `200` here with a failing `apm install` points at precedence (a higher-priority var is set to a different token). Run `apm install --verbose` to see which source APM picked.
+
+For end-to-end auth setup see [Authentication](../enterprise/authentication/).
+
+## 2. Network and TLS
+
+### TLS verification
+
+```text
+[!] TLS verification failed
+```
+
+Behind a corporate proxy, set `REQUESTS_CA_BUNDLE` to your org's CA bundle (PEM file). Full walkthrough: [SSL / TLS issues](./ssl-issues/).
+
+### Timeouts and proxies
+
+APM honours the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` env vars. If clones hang:
+
+- [>] Confirm `git -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=10 ls-remote <url>` succeeds.
+- [>] Set `GIT_SSH_COMMAND` to add verbose diagnostics for SSH transports:
+  ```bash
+  export GIT_SSH_COMMAND="ssh -vvv"
+  ```
+  APM preserves your value when composing its own SSH env.
+
+### Air-gapped and proxied registries
+
+Route all package downloads through an enterprise proxy:
+
+```bash
+export PROXY_REGISTRY_URL=https://artifactory.example.com/apm
+export PROXY_REGISTRY_TOKEN=xxx
+```
+
+See [Registry proxy](../enterprise/registry-proxy/) for setup, including `PROXY_REGISTRY_ALLOW_HTTP` for development environments.
+
+## 3. Lockfile mismatches
+
+### Manifest changed but lockfile didn't
+
+If you edited `apm.yml` but `apm.lock.yaml` still pins the old refs, run a plain install to regenerate the lockfile:
+
+```bash
+apm install
+```
+
+This re-resolves and rewrites `apm.lock.yaml`. Commit the result.
+
+### Drifted refs
+
+To force re-resolution to the latest Git ref allowed by `apm.yml`:
+
+```bash
+apm install --update
+```
+
+This is the only flag that will move pins forward; a bare `apm install` keeps existing pins where they are still satisfiable.
+
+### Detecting drift in CI
+
+The CI gate compares the deployed tree against what the lockfile says should be there:
+
+```bash
+apm audit --check drift
+```
+
+A non-zero exit means the working tree has diverged from `apm.lock.yaml` -- either re-run `apm install` to restore parity, or commit the new lockfile if the drift was intentional.
+
+For the full flag list see [`apm install`](../reference/cli/install/).
+
+## 4. Cache problems
+
+APM uses a content-addressed cache for git clones and HTTP downloads. Corrupt or stale entries usually surface as checksum mismatches or "object not found" errors mid-install.
+
+### Diagnose
+
+```bash
+apm cache info
+```
+
+Reports the cache root, git-repo count, checkout count, HTTP entry count, and total size on disk.
+
+### Recover
+
+Bypass the cache for a single run:
+
+```bash
+apm install --refresh
+```
+
+This re-fetches every dependency from upstream and rewrites cache entries.
+
+Disable the cache entirely (read and write) for one invocation:
+
+```bash
+APM_NO_CACHE=1 apm install
+```
+
+Wipe the cache when entries are demonstrably corrupt:
+
+```bash
+apm cache clean
+```
+
+Or drop only stale entries:
+
+```bash
+apm cache prune --days 30
+```
+
+See [`apm cache`](../reference/cli/cache/) for the full subcommand reference.
+
+## 5. Partial install recovery
+
+`apm install` is designed to be re-run safely. If a previous invocation died mid-flight (Ctrl-C, OOM, network drop), just run it again:
+
+```bash
+apm install
+```
+
+The cache short-circuits already-downloaded packages and the integrate phase overwrites partially-deployed files.
+
+If files in `apm_modules/` or under target harness directories look corrupt, force a fresh deploy by combining cache bypass with overwrite:
+
+```bash
+apm install --refresh --force
+```
+
+`--force` overwrites locally-authored files on collision **and** bypasses the security scan's critical-finding block -- use it only after you've inspected the diff. See [`apm install`](../reference/cli/install/#policy-and-trust).
+
+To wipe everything and start clean:
+
+```bash
+rm -rf apm_modules/
+apm cache clean
+apm install
+```
+
+## 6. Verbose diagnostics
+
+When the above doesn't pinpoint the failure, raise the noise floor:
+
+```bash
+apm install --verbose
+```
+
+Shows per-file paths, the auth source picked for each host, cache hits and misses, and full error context in the diagnostic summary.
+
+For low-level download, file-op, and clone-cache traces:
+
+```bash
+APM_DEBUG=1 apm install --verbose
+```
+
+Combine the two to capture the maximum signal in a single run. Pipe to a file before sharing:
+
+```bash
+APM_DEBUG=1 apm install --verbose 2>&1 | tee install.log
+```
+
+If you file an issue, attach `install.log`, the relevant `apm.yml` and `apm.lock.yaml`, and the output of `apm cache info`.
diff --git a/docs/src/content/docs/troubleshooting/migration.md b/docs/src/content/docs/troubleshooting/migration.md
new file mode 100644
index 000000000..a16e6d832
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/migration.md
@@ -0,0 +1,145 @@
+---
+title: "Migration paths"
+description: "Adopting APM, upgrading across versions, switching compile strategies, and migrating between targets."
+sidebar:
+  order: 6
+---
+
+This page covers migrations you hit while adopting APM or upgrading the CLI. For first-time setup of a brownfield project, start with [Existing Projects](../getting-started/) and come back here for upgrade-time issues.
+
+[i] Throughout: replace `<your-version>` with the version you currently have installed (`apm --version`) and `<target>` with the version you are moving to.
+
+## 1. From hand-managed `.github/copilot-instructions.md`
+
+Your existing instruction files are not touched by APM. `apm init` is additive: it writes `apm.yml` next to whatever already exists.
+
+```bash
+apm init                          # creates apm.yml; never edits existing files
+apm install                       # resolves dependencies, writes apm.lock.yaml
+apm compile                       # materializes target-specific output
+git add apm.yml apm.lock.yaml
+git commit -m "Adopt APM"
+```
+
+[+] Hand-written `.github/copilot-instructions.md`, `AGENTS.md`, `.cursor/rules`, `.claude/` configs continue to work side-by-side with APM-managed files.
+
+[!] Do not commit `apm_modules/` -- add it to `.gitignore`. The lockfile is the reproducibility contract, not the installed tree.
+
+See [`apm init`](../reference/cli/init/) and [`apm install`](../reference/cli/install/) for full flag references.
+
+## 2. From `awd-cli` (previous project name)
+
+APM was previously distributed as `awd-cli` with an `awd` binary. There is no compatibility shim: the only installed entrypoint is `apm`.
+
+Migration steps:
+
+1. Uninstall the old binary:
+
+   ```bash
+   pip uninstall awd-cli
+   # or whatever installer you used
+   which awd && rm "$(which awd)"
+   ```
+
+2. Install APM via the documented [installation flow](../getting-started/).
+
+3. In your scripts, CI workflows, and docs, replace `awd ` with `apm `. The subcommand surface (`init`, `install`, `compile`, `run`, `audit`) is the same.
+
+4. Manifest and lockfile files keep their names (`apm.yml`, `apm.lock.yaml`). If your repo still has legacy `awd.yml` / `awd.lock.yaml`, rename them:
+
+   ```bash
+   git mv awd.yml apm.yml
+   git mv awd.lock.yaml apm.lock.yaml
+   apm install                     # regenerates lockfile against current resolver
+   ```
+
+[!] After renaming, regenerate the lockfile rather than editing it by hand. Field names and resolution semantics may have shifted between awd-cli and APM releases.
+
+## 3. Lockfile schema upgrades
+
+The current lockfile schema is `lockfile_version: "1"`. When APM bumps this, an older binary reading a newer lockfile (or vice versa) will refuse to proceed and print upgrade instructions.
+
+```text
+[x] apm.lock.yaml uses lockfile_version "2", this binary supports "1"
+    [>] Upgrade APM: see https://...
+```
+
+Decision matrix:
+
+| Situation                                  | Action                                  |
+|--------------------------------------------|-----------------------------------------|
+| Newer lockfile, older binary               | Upgrade the binary, then re-run install |
+| Older lockfile, newer binary               | Run `apm install` to migrate in place   |
+| Lockfile is corrupted or hand-edited       | Delete it, run `apm install` to regen   |
+| Resolver semantics changed across versions | Delete + regen, then audit the diff     |
+
+[i] Migrating in place preserves resolved versions where compatible. Deleting and regenerating re-resolves from `apm.yml` and may bump transitive dependencies. Review the diff before committing.
+
+Schema details: [Lockfile spec](../reference/lockfile-spec/).
+
+## 4. Compile strategy migration
+
+The compile step writes per-target output (e.g. `.github/copilot-instructions.md`, `.claude/`, `.cursor/rules/`). Some targets support both a single-file (monolithic) layout and a per-primitive (distributed) layout.
+
+To switch:
+
+1. Run `apm prune` first to remove APM-managed output for the current strategy. This avoids leaving orphans when the layout changes.
+2. Update the target configuration in `apm.yml` (see the target's reference page).
+3. Run `apm compile` to materialize the new layout.
+4. `git status` -- review added/removed files and commit.
+
+[!] Hand-edited files inside an APM-managed output directory will be lost on recompile. APM owns the output tree; author content lives in source packages.
+
+Reference: [`apm compile`](../reference/cli/compile/) and [`apm prune`](../reference/cli/prune/).
+
+## 5. Target migration
+
+### Adding a target
+
+Adding a new target (e.g. Cursor on a Copilot-only project) is non-destructive:
+
+```bash
+apm install --target cursor       # one-shot
+# or persist in apm.yml under `target:` and run `apm install`
+apm compile
+```
+
+Existing target output is untouched. The new target's directory is created fresh.
+
+### Removing a target
+
+1. Remove the target from `apm.yml` (`target:` field).
+2. Run `apm prune`. APM removes the deployed files for the dropped target.
+3. Run `apm install && apm compile` to confirm the project is clean.
+
+[!] `apm prune` only removes files APM tracked in `apm.lock.yaml`. Files you placed by hand inside a target directory remain. Review `git status` after pruning.
+
+Discovery: `apm targets` lists every supported target on the current binary.
+
+## 6. Marketplace switchover (hand-rolled MCP -> APM-managed)
+
+If your project has a hand-edited `.mcp.json` (or VS Code `mcp.json`) declaring servers directly:
+
+1. Move each server into the `mcp:` block of `apm.yml`. APM resolves servers from the marketplace and wires them per target on install.
+2. Run `apm install`. APM rewrites the target-specific MCP config.
+3. Diff the generated MCP config against your previous hand-rolled version and reconcile any custom env vars or args using the marketplace package's documented inputs.
+4. Delete the legacy hand-rolled config once the APM-managed version is verified.
+
+For publishing your own marketplace entries, see [Marketplace authoring](../guides/pack-distribute/marketplace-authoring/).
+
+## 7. Breaking-change checklist when upgrading APM
+
+Before bumping `apm` across major or minor versions in a project that other people depend on:
+
+- Read every `CHANGELOG.md` entry between `<your-version>` and `<target>`. Pay attention to `### Changed`, `### Removed`, `### Security`.
+- Install the new binary in a scratch shell first (don't replace your working binary yet).
+- Run `apm audit --ci` against the new binary in your repo to surface drift between the previous lockfile/output and what the new resolver produces.
+- Run `apm install && apm compile` with the new binary. Inspect `git status` for unexpected churn.
+- Run your project's tests and any agent-driven workflows that depend on the compiled output.
+- If anything looks wrong, downgrade and open an issue. Do not commit a half-migrated lockfile.
+
+## Related
+
+- [Common errors](./common-errors/) -- diagnostic flowcharts for failures hit during migration.
+- [Lockfile spec](../reference/lockfile-spec/) -- schema reference.
+- [`apm init`](../reference/cli/init/), [`apm install`](../reference/cli/install/), [`apm compile`](../reference/cli/compile/), [`apm prune`](../reference/cli/prune/).
diff --git a/docs/src/content/docs/troubleshooting/policy-debugging.md b/docs/src/content/docs/troubleshooting/policy-debugging.md
new file mode 100644
index 000000000..589285102
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/policy-debugging.md
@@ -0,0 +1,213 @@
+---
+title: Debugging policy failures
+description: Diagnose blocked installs and audits, inspect resolved org policy, and apply the right escape hatch.
+sidebar:
+  order: 5
+---
+
+When `apm install` or `apm audit --ci` blocks the project on policy, the
+job is not to silence it -- it is to figure out **which rule fired,
+where the policy came from, and whether the right fix is in your
+project, in the org policy, or a one-shot escape hatch.**
+
+This page walks the diagnosis end to end.
+
+## 1. Read the failure
+
+A policy block looks roughly like this:
+
+```text
+[x] policy: dependency.allow
+    severity: error
+    message:  Dependency 'acme-corp/internal-skills' is not on the
+              org allowlist.
+    evidence: apm.yml -> dependencies.apm[2]
+    source:   acme-corp/.github/apm-policy.yml
+```
+
+Three things to extract before doing anything else:
+
+- **Rule id** (`dependency.allow`) -- pin it; you will reuse it in the
+  next steps.
+- **Severity** (`error` blocks; `warning` does not).
+- **Source** -- the org policy file that owns the rule. If you do not
+  recognize it, jump straight to step 2.
+
+## 2. Ask "which policy ruled on me?"
+
+`apm policy status` prints the resolved policy posture for the current
+project, with no side effects. Run it from the project root:
+
+```bash
+apm policy status
+```
+
+```text
+APM Policy Status
+-----------------
+  Outcome        found
+  Source         acme-corp/.github/apm-policy.yml
+  Enforcement    enforce
+  Cache age      4m ago
+  Extends chain  acme-corp/.github/apm-policy.yml
+  Effective rules  dependency: 2 rule(s); mcp: 3 rule(s); manifest: 1 rule(s)
+```
+
+Useful flags:
+
+- `--no-cache` -- skip the policy cache and refetch from GitHub.
+- `--policy-source <ref>` -- override discovery (e.g. `org`, a repo
+  ref, or a local path) to test what *would* apply.
+- `-o json` -- machine-readable for scripting and SIEM ingest.
+- `--check` -- exit non-zero when no usable policy is resolved (CI
+  pre-check). Default exit is always `0`.
+
+If `Outcome` is anything other than `found`, the discovery itself
+failed. Common causes: missing GitHub token, private `.github` repo,
+network egress blocked. The `Notice:` line at the bottom of the report
+explains which.
+
+For the full command surface, see [`apm policy`](../reference/cli/policy/).
+
+## 3. Inheritance and merge
+
+Org policies can `extends:` other policies. The effective policy is the
+**tighten-only merge** of the chain: a child can make rules stricter,
+never looser.
+
+```text
+Extends chain  acme-corp/.github/apm-policy.yml
+               -> acme-corp/policy-base@v3
+```
+
+Common surprises:
+
+- A child adds an entry to `dependency.allow` but the parent's
+  `dependency.deny` still applies -- denies always win.
+- A child sets `mcp.transport.allow: [stdio, http]` but the parent
+  pinned `[http]` -- the child's broader list is ignored.
+- Severity can only be raised by a child, never lowered.
+
+The full merge semantics live in
+[Policy schema -> Merge rules (tighten-only)](../reference/policy-schema/#merge-rules-tighten-only).
+Read that section before arguing with a parent policy.
+
+## 4. Discovery surprises
+
+APM resolves policy in this order:
+
+1. `--policy-source <ref>` on `apm policy status`, or `--policy <ref>`
+   on `apm audit --ci`. Explicit always wins.
+2. Project-local `apm.yml` (`policy:` block, if present).
+3. Auto-discovery: `<owner>/.github/apm-policy.yml` for the repo's
+   GitHub owner.
+4. None -- no enforcement.
+
+Things that bite:
+
+- **Wrong owner.** Auto-discovery uses the *current repo's* GitHub
+  owner. If your fork is under a personal account, the org policy
+  will not auto-apply. Use `apm policy status --policy-source org`
+  to test against the upstream owner.
+- **Stale cache.** Policy is cached on disk. If an admin just rolled
+  out a fix, run with `--no-cache` (or `apm install --refresh ...`).
+- **Discovery silently disabled.** `APM_POLICY_DISABLE=1` in the
+  shell environment skips discovery for **every** APM command in that
+  session. See the call-out below.
+
+### Escape hatches
+
+Two exist. Both are loud on purpose.
+
+| Mechanism | Scope | Skips |
+|---|---|---|
+| `apm install --no-policy` | Single invocation | Org policy gate during install only. Does **not** bypass `apm audit --ci`. |
+| `APM_POLICY_DISABLE=1` | Entire shell session | All policy discovery and enforcement, in every APM command. |
+
+:::caution
+`APM_POLICY_DISABLE=1` is session-wide and applies to install, audit,
+compile, and unpack. Set it for one command (`APM_POLICY_DISABLE=1 apm
+install`) -- never `export` it in a shell profile.
+:::
+
+Both flags are documented in
+[Environment variables](../reference/environment-variables/).
+
+## 5. Common rules that block
+
+These cover most real-world failures. Each lists the symptom and the
+shortest path to green.
+
+### `dependency.allow` / `dependency.deny`
+
+- **Symptom:** `Dependency '<owner>/<repo>' is not on the org
+  allowlist` (or `is on the org denylist`).
+- **Fix:** Replace the dep with an allowed equivalent, or open a PR
+  against the org policy file to add it (see step 6).
+
+### `mcp.transport.allow` excluding `stdio`
+
+- **Symptom:** `MCP server '<name>' uses transport 'stdio' which is
+  not on the allowed transport list`.
+- **Cause:** Org has narrowed transports to remote-only (`http`,
+  `sse`) and your `apm.yml` pins a stdio command.
+- **Fix:** Re-install the server from the registry with `--url` (HTTP
+  endpoint). If no remote endpoint exists, escalate to the org admin.
+
+### `mcp.self_defined: deny`
+
+- **Symptom:** `Self-defined MCP server '<name>' is not allowed; only
+  registry-resolved servers are permitted`.
+- **Cause:** Org requires every MCP server to come from the registry,
+  not be hand-rolled in `apm.yml`.
+- **Fix:** Find the server in the registry and `apm install
+  mcp:<name>`. Remove the hand-rolled entry.
+
+### `manifest.required_fields` missing
+
+- **Symptom:** `Required manifest field 'description' is missing from
+  apm.yml`.
+- **Fix:** Edit `apm.yml` and add the listed field. Org policy
+  defines the required set; check
+  [Policy schema](../reference/policy-schema/).
+
+### `unmanaged_files.action: deny`
+
+- **Symptom:** `Unmanaged file detected in target directory:
+  .github/instructions/extra.md`.
+- **Cause:** A hand-edited file in a target directory APM owns. With
+  `action: deny`, any file APM did not write blocks the build.
+- **Fix:** Either move the file out of the target directory, or
+  promote it to a real APM primitive in a package. See
+  [Baseline checks](../reference/baseline-checks/) for the underlying
+  CI check.
+
+## 6. Working with org admins
+
+Pick the right ask:
+
+- **Fix the project** when: your dep is genuinely off-policy (a fork,
+  unmaintained, replaced by an org-blessed alternative), or you can
+  swap to a registry-listed MCP server.
+- **Ask for an allowlist addition** when: the dep is critical, has no
+  org-blessed equivalent, and meets the org's review bar.
+
+When you open the PR against the org policy repo:
+
+1. Link the failing CI run (or the `apm policy status` JSON output).
+2. Quote the exact rule id and source line.
+3. Link the org policy file you are amending so reviewers do not have
+   to hunt for it.
+
+For org-side context (who owns the policy, how rollouts work),
+see [Governance overview](../enterprise/governance-overview/) and
+[APM policy: getting started](../enterprise/apm-policy-getting-started/).
+
+## See also
+
+- [`apm policy`](../reference/cli/policy/) -- command reference.
+- [Policy schema](../reference/policy-schema/) -- every rule, every
+  field, merge semantics.
+- [Baseline checks](../reference/baseline-checks/) -- the CI checks
+  invoked by `apm audit --ci`.
+- [Common errors](./common-errors/) -- non-policy install failures.
diff --git a/docs/src/content/docs/troubleshooting/ssl-issues.md b/docs/src/content/docs/troubleshooting/ssl-issues.md
index 284a0eb3d..47e12b553 100644
--- a/docs/src/content/docs/troubleshooting/ssl-issues.md
+++ b/docs/src/content/docs/troubleshooting/ssl-issues.md
@@ -1,40 +1,175 @@
 ---
 title: "SSL / TLS issues"
-description: "Fix SSL/TLS verification errors when running APM."
+description: "Diagnose and fix TLS verification failures during apm install and apm audit."
 sidebar:
-  order: 1
+  order: 4
 ---
 
-If `apm install` fails with a TLS error like:
+`apm install` and `apm audit` reach out to GitHub, GHES, GitLab, Azure DevOps, and package archives over HTTPS. When the system can't verify the server certificate, the operation fails. This page maps the failure modes to fixes.
+
+Related: [environment variables](../reference/environment-variables/), [install failures](./install-failures/), [security and supply chain](../enterprise/security-and-supply-chain/), [authentication](../enterprise/authentication/).
+
+## Symptoms
+
+Typical errors APM surfaces or passes through from the underlying HTTP/git stack:
+
+```text
+[!] TLS verification failed -- if you're behind a corporate proxy or
+    firewall, set REQUESTS_CA_BUNDLE to your organisation's CA bundle.
+```
+
+```text
+SSLError: HTTPSConnectionPool(host='api.github.com', port=443):
+  Max retries exceeded ... [SSL: CERTIFICATE_VERIFY_FAILED]
+  certificate verify failed: unable to get local issuer certificate
+```
 
 ```text
-[!] TLS verification failed -- if you're behind a corporate proxy or firewall, set the REQUESTS_CA_BUNDLE environment variable to the path of your organisation's CA bundle (a PEM file) and retry.
+fatal: unable to access 'https://github.example.com/...':
+  SSL certificate problem: self-signed certificate in certificate chain
+```
+
+```text
+fatal: unable to access '...': server certificate verification failed.
+  CAfile: none CRLfile: none
+```
+
+All of these mean the same thing: the TLS chain presented by the server can't be validated against the trust store APM is using.
+
+## First diagnostic
+
+Decide which of the three categories you are in before changing anything:
+
+[*] **Corporate TLS-intercepting proxy** (Zscaler, Netskope, Palo Alto, Cisco Umbrella, Blue Coat). The server cert is re-signed by an internal CA. Affects every HTTPS host. Fix: trust the corporate CA.
+
+[*] **Self-hosted server with internal CA** (GHES, GitLab self-managed, internal artifact host). Only that one host fails; public hosts like `api.github.com` work fine. Fix: trust the internal CA, often per-host.
+
+[*] **Genuine certificate problem** (expired, wrong hostname, broken chain). Reproduce with `curl -v https://<host>` from the same shell. If `curl` also fails, the problem is upstream of APM.
+
+Re-run the failing command with `--verbose` to see the underlying exception and the host that triggered it:
+
+```bash
+apm install --verbose
 ```
 
-The most common cause is a corporate TLS-intercepting proxy or firewall (Zscaler, Netskope, Palo Alto, etc.) re-signing HTTPS traffic with an internal CA that APM doesn't trust.
+## Configure trust
 
-## Fix
+APM uses `requests` for HTTP and shells out to `git` for repository operations. Both honour standard environment variables. Set them at the shell or in your profile (`~/.zshrc`, `~/.bashrc`, or the Windows user environment).
+
+### Python HTTP layer
+
+```bash
+export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem
+# or, more general:
+export SSL_CERT_FILE=/path/to/ca-bundle.pem
+export SSL_CERT_DIR=/etc/ssl/certs
+```
 
-Point APM at the PEM file containing your organisation's CA. Ask your IT team for the path if you don't know it.
+`REQUESTS_CA_BUNDLE` wins for `requests`. `SSL_CERT_FILE` / `SSL_CERT_DIR` cover the rest of the Python TLS stack.
 
-**Linux / macOS:**
+### Git operations
 
 ```bash
-export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.pem
+export GIT_SSL_CAINFO=/path/to/ca-bundle.pem
 ```
 
-To persist across sessions, add the same line to your shell profile (`~/.bashrc`, `~/.zshrc`, `~/.profile`, etc.).
+For one host only, prefer per-host git config so you don't widen trust globally:
 
-**Windows (PowerShell):**
+```bash
+git config --global http.https://github.example.com/.sslCAInfo /path/to/internal-ca.pem
+```
+
+The trailing slash matters - it scopes the setting to that origin.
+
+### Windows (PowerShell)
 
 ```powershell
-# Current session only
-$env:REQUESTS_CA_BUNDLE = "C:\path\to\corporate-ca.pem"
+$env:REQUESTS_CA_BUNDLE = "C:\certs\corporate-ca.pem"
+$env:GIT_SSL_CAINFO     = "C:\certs\corporate-ca.pem"
+
+# Persist for the current user:
+[Environment]::SetEnvironmentVariable("REQUESTS_CA_BUNDLE", "C:\certs\corporate-ca.pem", "User")
+```
+
+### Where do I get the CA file?
+
+Your IT or platform team owns it. Ask for the PEM bundle for the proxy or internal PKI. Do not export it yourself from a browser unless that is the documented procedure - you may capture an intermediate, not the root.
 
-# Persist for future sessions (user-level)
-[Environment]::SetEnvironmentVariable("REQUESTS_CA_BUNDLE", "C:\path\to\corporate-ca.pem", "User")
+## GHES and GitLab self-managed
+
+Trust alone is not enough for self-hosted forges. APM also needs to know which host to talk to.
+
+**GHES:**
+
+```bash
+export GITHUB_HOST=github.example.com
+export GITHUB_APM_PAT=<token>
+export GIT_SSL_CAINFO=/path/to/internal-ca.pem
+```
+
+**GitLab self-managed:**
+
+```bash
+export GITLAB_HOST=gitlab.example.com
+export APM_GITLAB_HOSTS=gitlab.example.com,gitlab-eu.example.com
+export GITLAB_APM_PAT=<token>
+export GIT_SSL_CAINFO=/path/to/internal-ca.pem
+```
+
+See [environment variables](../reference/environment-variables/) for the full list and [authentication](../enterprise/authentication/) for token scopes.
+
+## Proxies
+
+APM does not implement its own proxy logic. It honours the standard variables, which `requests` and `git` both read:
+
+```bash
+export HTTPS_PROXY=http://proxy.example.com:8080
+export HTTP_PROXY=http://proxy.example.com:8080
+export NO_PROXY=localhost,127.0.0.1,.internal.example.com
+```
+
+If the proxy performs TLS interception, you also need the proxy's signing CA in the trust store - see [Configure trust](#configure-trust). Importing the CA into the OS trust store (Keychain on macOS, `update-ca-certificates` on Debian/Ubuntu, `update-ca-trust` on RHEL, the Trusted Root store on Windows) is the most durable fix; consult your OS documentation rather than copying steps from here.
+
+## Verify the fix
+
+```bash
+# Python side
+python -c "import requests; print(requests.get('https://api.github.com').status_code)"
+
+# Git side
+GIT_CURL_VERBOSE=1 git ls-remote https://github.example.com/org/repo.git 2>&1 | grep -i 'ssl\|cert'
+
+# APM end-to-end
+apm install --verbose
+```
+
+A `200` from `requests`, a successful `ls-remote`, and a clean install confirm trust is wired through every layer APM uses.
+
+## Development-only escape hatches
+
+:::caution[Development only]
+The settings below disable certificate verification. They expose every request to trivial man-in-the-middle attacks and **must never be used in CI, on shared machines, or against production data**. Trusting the right CA is always the correct fix.
+:::
+
+If you are isolated on a laptop, debugging a local server with a self-signed cert, and you accept the risk:
+
+```bash
+export GIT_SSL_NO_VERIFY=true       # git only
+export PYTHONHTTPSVERIFY=0          # Python stdlib only; requests ignores this
+```
+
+What you lose: any guarantee that the host you reached is the host you intended to reach. Tokens you send may be captured. Packages you download may be tampered with - APM's [built-in security scanning](../enterprise/security-and-supply-chain/) still runs on the bytes received, but it cannot detect substitution upstream of itself.
+
+Unset both as soon as you are done:
+
+```bash
+unset GIT_SSL_NO_VERIFY PYTHONHTTPSVERIFY
 ```
 
-## Not behind a proxy or firewall?
+## Still failing?
 
-The root cause is likely somewhere else. Re-run with `--verbose` for the underlying exception.
+[>] Re-run with `--verbose` and capture the full exception chain.
+[>] Check `curl -v https://<host>` from the same shell - if it fails, the problem is the system trust store, not APM.
+[>] Confirm `REQUESTS_CA_BUNDLE` and `GIT_SSL_CAINFO` point at a readable PEM file (`openssl x509 -in $REQUESTS_CA_BUNDLE -noout -subject` should print a subject line).
+[>] If only one host fails, see [GHES and GitLab self-managed](#ghes-and-gitlab-self-managed) and the per-host `git config` recipe above.
+[>] If the install proceeds past TLS but then fails, continue at [install failures](./install-failures/).
diff --git a/tests/unit/policy/test_help_consistency.py b/tests/unit/policy/test_help_consistency.py
index 28ecebb61..d3711361f 100644
--- a/tests/unit/policy/test_help_consistency.py
+++ b/tests/unit/policy/test_help_consistency.py
@@ -6,7 +6,8 @@
 - ``apm_cli.policy._help_text.POLICY_SOURCE_FORMS_HELP`` (Python constant)
 - ``apm audit --policy`` Click help (uses the constant)
 - ``apm policy status --policy-source`` Click help (uses the constant)
-- ``docs/src/content/docs/reference/cli-commands.md`` (manual prose)
+- ``docs/src/content/docs/reference/cli/audit.md`` (manual prose, table row)
+- ``docs/src/content/docs/reference/cli/policy.md`` (manual prose, table row)
 
 If any of these drift, the tests below fail. See #998 for the underlying
 incident that motivated this lockstep.
@@ -19,17 +20,15 @@
 
 from apm_cli.policy._help_text import POLICY_SOURCE_FORMS_HELP
 
-# Canonical user-facing forms accepted by ``--policy`` / ``--policy-source``.
-# Tokens chosen to be robust against Click's help-text reflow (no internal
-# whitespace) and to uniquely identify each form.
 EXPECTED_FORM_TOKENS = ("'org'", "owner/repo", "https://", "file path")
 
-# Same set of forms, written with the markdown backtick convention used in
-# the docs (the docs render Click-style single quotes as inline code).
 DOCS_FORM_TOKENS = ("`org`", "`owner/repo`", "`https://`", "file path")
 
 REPO_ROOT = Path(__file__).resolve().parents[3]
-DOCS_PATH = REPO_ROOT / "docs" / "src" / "content" / "docs" / "reference" / "cli-commands.md"
+DOCS_AUDIT_PATH = REPO_ROOT / "docs" / "src" / "content" / "docs" / "reference" / "cli" / "audit.md"
+DOCS_POLICY_PATH = (
+    REPO_ROOT / "docs" / "src" / "content" / "docs" / "reference" / "cli" / "policy.md"
+)
 
 
 def _normalize_help_output(text: str) -> str:
@@ -88,41 +87,39 @@ def test_policy_status_help_uses_canonical_constant():
         )
 
 
-def _bullet_starting_with(text: str, marker: str) -> str:
-    """Return the bullet line that begins with ``marker`` (up to next newline).
+def _row_starting_with(text: str, marker: str, source_path: Path) -> str:
+    """Return the markdown table row whose first cell starts with ``marker``.
 
-    Used to scope assertions to a specific flag's documentation bullet
-    instead of the whole docs file -- a form keyword may appear elsewhere
-    in cli-commands.md (e.g. unrelated marketplace examples), so a global
-    count is not strict enough to catch a removal from the bullet we
-    actually care about.
+    The new docs structure (one page per command) renders flag docs as
+    table rows like ``| `--policy SOURCE` | auto | description... |``.
+    We grab the entire row (up to the next newline) so assertions can
+    scope to the cell of interest without scanning the whole page.
     """
     idx = text.find(marker)
     if idx < 0:
-        raise AssertionError(f"Could not find bullet starting with {marker!r} in {DOCS_PATH.name}")
+        raise AssertionError(f"Could not find row starting with {marker!r} in {source_path.name}")
     end = text.find("\n", idx)
     return text[idx:end] if end >= 0 else text[idx:]
 
 
 def test_docs_audit_policy_bullet_lists_all_forms():
-    """The ``apm audit --policy SOURCE`` doc bullet lists every canonical form."""
-    text = DOCS_PATH.read_text(encoding="utf-8")
-    bullet = _bullet_starting_with(text, "- `--policy SOURCE`")
+    """The ``apm audit --policy SOURCE`` doc row lists every canonical form."""
+    text = DOCS_AUDIT_PATH.read_text(encoding="utf-8")
+    row = _row_starting_with(text, "| `--policy SOURCE`", DOCS_AUDIT_PATH)
     for token in DOCS_FORM_TOKENS:
-        assert token in bullet, (
-            f"`apm audit --policy SOURCE` doc bullet missing form: {token!r}.\n"
-            f"Bullet text:\n  {bullet}"
+        assert token in row, (
+            f"`apm audit --policy SOURCE` doc row missing form: {token!r}.\nRow text:\n  {row}"
         )
 
 
 def test_docs_policy_status_bullet_lists_all_forms():
-    """The ``apm policy status --policy-source SOURCE`` bullet lists every canonical form."""
-    text = DOCS_PATH.read_text(encoding="utf-8")
-    bullet = _bullet_starting_with(text, "- `--policy-source SOURCE`")
+    """The ``apm policy status --policy-source SOURCE`` row lists every canonical form."""
+    text = DOCS_POLICY_PATH.read_text(encoding="utf-8")
+    row = _row_starting_with(text, "| `--policy-source SOURCE`", DOCS_POLICY_PATH)
     for token in DOCS_FORM_TOKENS:
-        assert token in bullet, (
-            f"`apm policy status --policy-source SOURCE` doc bullet missing form: {token!r}.\n"
-            f"Bullet text:\n  {bullet}"
+        assert token in row, (
+            f"`apm policy status --policy-source SOURCE` doc row missing form: {token!r}.\n"
+            f"Row text:\n  {row}"
         )