docs: wave 3 corpus audit + IA-reshuffle dead-link cleanup (53 pages)

Second sweep of the regrounding audit. Covers the 57 pages deferred in
wave 2: producer/ (15), enterprise/ (15), concepts/ (6), integrations/
(7), troubleshooting/ (7), contributing/ (3), reference tail (3), 404.

Process: 6 parallel grounding-verifier agents on disjoint scopes; each
agent extracts factual claims, S7-verifies against current source
('apm <verb> --help' + grep src/apm_cli/), and applies surgical edits
inline. Same pattern as wave 2 (PANEL + WAVE EXECUTION + S7 verifier
fan-out). Orchestrator post-pass swept three cross-corpus broken-link
patterns the per-scope agents could not fix alone.

High-signal factual fixes:

enterprise/governance-guide.md:
- --output-file -> --output (real flag is --output / -o)
- 7+17 check count -> 8+17 (8 baseline checks, not 7)

enterprise/apm-policy.md:
- '16 of 22 checks' -> '17 of 25 checks' (phantom counts)
- conflated --no-policy (install-only) with APM_POLICY_DISABLE (env)

enterprise/apm-policy-getting-started.md:
- dropped 'apm compile' from list of commands that run policy
  (compile enforces zero policy per governance-overview.md L57)

enterprise/policy-reference.md:
- compilation.target.allow: added copilot, gemini, vscode, windsurf,
  agent-skills (only 5 of 9 runtimes were listed)

enterprise/registry-proxy.md:
- 'apm marketplace add --branch main' -> '--ref main' (no --branch flag)

enterprise/security-and-supply-chain.md:
- 3 stale source line-number citations corrected

producer/author-primitives/index.md:
- legacy '.hook.md' extension -> '.json' (hook_integrator scans JSON)
- removed nonexistent '.apm/commands/' subdirectory from layout example

concepts/lifecycle.md:
- 4 reference-page links all pointed at install/ (copy-paste)

Cross-corpus IA-reshuffle dead-link cleanup (orchestrator pass):
- introduction/* -> concepts/* (4 links across 2 files)
- guides/ci-policy-setup/ -> enterprise/enforce-in-ci/ (8 links, 4 files)
- guides/pack-distribute/ -> producer/pack-a-bundle/ (5 links, 4 files)
- guides/dependencies/ -> consumer/manage-dependencies/ (1 link)
- guides/agent-workflows/ -> contextual canonical (3 links, 3 files)
- guides/install-and-use/mcp-servers/ -> consumer/install-mcp-servers/ (3)
- guides/compilation/ -> producer/compile/ (1)
- guides/prompts/ -> producer/author-primitives/prompts/ (2)
- guides/drift-detection/ -> enterprise/drift-detection/ (1)

enterprise/security.md side-fix:
- 'apm unpack scheduled for removal in v0.14' -> drop version target
  (APM is 0.15.0 and unpack still ships marked DEPRECATED in --help).
  Upstream remediation (refresh deprecation timeline in source or
  remove the shim) tracked outside this PR.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

docs/src/content/docs/concepts/lifecycle.md

@@ -37,7 +37,7 @@ Targets are picked in priority order. An explicit `--target copilot,claude` flag
 - 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/).
+**Read more:** [`apm init` reference](/apm/reference/cli/init/), [package anatomy](/apm/concepts/package-anatomy/).
 
 ## 2. INSTALL
 
@@ -85,7 +85,7 @@ The `--target` flag accepts a comma-separated list (`copilot,claude,cursor,openc
 - 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/).
+**Read more:** [`apm compile` reference](/apm/reference/cli/compile/), [compilation guide](/apm/producer/compile/).
 
 ## 4. RUN
 
@@ -119,7 +119,7 @@ The `scripts:` shape is intentionally identical to `package.json`. Object-form s
 - 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/).
+**Read more:** [`apm run` reference](/apm/reference/cli/run/), [agent workflows guide](/apm/producer/author-primitives/instructions-and-agents/).
 
 ## 5. AUDIT
 
@@ -140,4 +140,4 @@ apm audit --file <path>    # standalone: scan an arbitrary file
 - `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/).
+**Read more:** [`apm audit` reference](/apm/reference/cli/audit/), [policy reference](/apm/enterprise/policy-reference/) for the full check list, [security](/apm/enterprise/security/).

docs/src/content/docs/consumer/run-scripts.md

@@ -105,8 +105,8 @@ 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.
+how a single prompt reaches every harness, and [authoring prompts](../../producer/author-primitives/prompts/) for
+the prompt-file format that backs these scripts.
 
 :::note[Coming from npm?]
 The `scripts:` shape is intentionally identical to `package.json`. Bare

docs/src/content/docs/enterprise/apm-policy-getting-started.md

@@ -151,9 +151,11 @@ parent that says `block`.
 
 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.
+`apm install --dry-run`. The same checks also run under
+`apm audit --ci --policy <source>`. `apm compile` and `apm run`
+enforce zero policy -- they trust what install placed on disk. 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

docs/src/content/docs/enterprise/apm-policy.md

@@ -13,7 +13,7 @@ The `apm-policy.yml` schema, inheritance, and discovery ship today and are usabl
 
 `apm-policy.yml` is a single YAML file that defines what AI agent dependencies, MCP servers, and compilation targets are allowed across an organization. It is the governance pillar of APM — the file your security team owns and your repos inherit.
 
-This page is the mental model. For the full schema, see the [Policy Reference](../policy-reference/). For wiring it into CI, see the [CI Policy Enforcement guide](../../guides/ci-policy-setup/).
+This page is the mental model. For the full schema, see the [Policy Reference](../policy-reference/). For wiring it into CI, see the [Enforce in CI guide](../enforce-in-ci/).
 
 ---
 
@@ -51,7 +51,7 @@ Alternative sources, useful for testing or non-GitHub setups:
 - **Local file** — `apm audit --ci --policy ./apm-policy.yml`
 - **HTTPS URL** — `apm audit --ci --policy https://example.com/apm-policy.yml`
 
-See [Alternative policy sources](../../guides/ci-policy-setup/#alternative-policy-sources) for details.
+See [Enforce in CI](../enforce-in-ci/) for alternative policy sources and CI wiring details.
 
 ---
 
@@ -88,13 +88,13 @@ Policy is evaluated at two points. Both use the same policy file and the same me
 
 `apm install` resolves the dependency tree, then runs the policy gate against the resolved set, then writes any files. A blocking violation halts the install with a non-zero exit code; nothing is written to disk. This protects developers who run `apm install` locally — they cannot accidentally deploy a denied package even without CI.
 
-> **Bypass note:** `apm install --no-policy` and the `APM_POLICY_DISABLE=1` environment variable skip this gate locally. They also skip 16 of the 22 checks when `apm audit --ci` runs in the same shell. See the [Governance Guide bypass contract](../governance-guide/#7-the-bypass--non-bypass-contract) for the full surface.
+> **Bypass note:** `apm install --no-policy` and the `APM_POLICY_DISABLE=1` environment variable skip this gate locally. The env var also skips all 17 policy checks when `apm audit --ci` runs in the same shell; the 8 baseline lockfile checks still run. See the [Governance Guide bypass contract](../governance-guide/#7-the-bypass--non-bypass-contract) for the full surface.
 
 ### CI time (audit gate)
 
 `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/).
+For setup, see [Enforce in CI](../enforce-in-ci/).
 
 ---
 
@@ -155,5 +155,5 @@ For lockfile-based forensic recipes, see the [Governance Guide §13: enforcement
 ## Next steps
 
 - **Schema and every field** — [Policy Reference](../policy-reference/)
-- **Wire it into CI with SARIF** — [CI Policy Enforcement](../../guides/ci-policy-setup/)
+- **Wire it into CI with SARIF** — [Enforce in CI](../enforce-in-ci/)
 - **Broader governance model** (lock files, audit trails, compliance scenarios) -- [Governance Guide](../governance-guide/)

docs/src/content/docs/enterprise/governance-guide.md

@@ -413,12 +413,12 @@ jobs:
         with: { python-version: "3.12" }
       - run: pip install apm-cli==X.Y.Z  # REPLACE: pin to current version, see /installation
       - run: apm install
-      - run: apm audit --ci -f sarif --output-file apm-audit.sarif
+      - run: apm audit --ci -f sarif --output apm-audit.sarif
       - uses: github/codeql-action/upload-sarif@v3
         with: { sarif_file: apm-audit.sarif }
 ```
 
-For richer customization (matrix builds, monorepo splits, vendored policy paths) see the [CI Policy Enforcement guide](../../guides/ci-policy-setup/).
+For richer customization (matrix builds, monorepo splits, vendored policy paths) see the [Enforce in CI guide](../enforce-in-ci/).
 
 :::caution[Warn mode does not fail CI]
 `apm audit --ci` in warn mode rewrites violations to `passed=True` (audit.py:589-598), so the audit command exits 0 even on policy violations. Visibility is in the SARIF upload + Code Scanning UI, not in branch-protection status. To gate merges on policy violations, you must run in `block` mode.
@@ -430,7 +430,7 @@ For richer customization (matrix builds, monorepo splits, vendored policy paths)
 
 **Circuit-breaker rollout for large fleets.** For 100+ repos, do not flip block org-wide in one commit. Stage: enable `block` for 10% of repos for 1 week (via team-level extends), monitor SARIF alert volume and on-call pages, expand to 50% for 1 week, then 100%. If SARIF volume spikes or on-call escalations cluster, revert to `warn` at the org level (one commit) while you triage.
 
-For step-by-step CI YAML and SARIF upload examples beyond the snippet above, see the [CI Policy Enforcement guide](../../guides/ci-policy-setup/).
+For step-by-step CI YAML and SARIF upload examples beyond the snippet above, see the [Enforce in CI guide](../enforce-in-ci/).
 
 ---
 
@@ -606,8 +606,8 @@ policy:
 :::
 
 - [`apm-policy.yml`](../apm-policy/) -- the file's mental model.
-- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI wiring with YAML.
-- [Policy Reference](../policy-reference/) -- complete schema, the canonical 7+17 check enumeration, the 12-row merge rule table, exit codes.
+- [Enforce in CI](../enforce-in-ci/) -- step-by-step CI wiring with YAML.
+- [Policy Reference](../policy-reference/) -- complete schema, the canonical 8+17 check enumeration, the 12-row merge rule table, exit codes.
 - [Security Model](../security/) -- threat model, MCP trust boundary, content scanning, token handling.
 - [Adoption Playbook](../adoption-playbook/) -- broader APM rollout (governance is one phase).
 - [Lockfile Spec](../../reference/lockfile-spec/) -- lockfile schema for forensic queries.

docs/src/content/docs/enterprise/making-the-case.md

@@ -242,8 +242,8 @@ With APM, setup reduces to `apm install` (under 30 seconds). Standards updates r
 | Governance | [Bypass contract and install gate](../governance-guide/) |
 | Security Model | [Supply-chain posture](../security/) |
 | CI/CD Integration | [Pipeline setup and enforcement](../../integrations/ci-cd/) |
-| Why APM | [Problem statement and design principles](../../introduction/why-apm/) |
-| How It Works | [Architecture and compilation pipeline](../../introduction/how-it-works/) |
+| Why APM | [What is APM](../../concepts/what-is-apm/) |
+| How It Works | [Lifecycle and compilation pipeline](../../concepts/lifecycle/) |
 | Manifest Schema | [apm.yml reference](../../reference/manifest-schema/) |
 | Org-Wide Packages | [Publishing shared configuration](../../guides/org-packages/) |
 

docs/src/content/docs/enterprise/policy-reference.md

@@ -40,7 +40,7 @@ mcp:
 
 compilation:
   target:
-    allow: []                   # vscode | claude | cursor | opencode | codex | all
+    allow: []                   # copilot | claude | cursor | opencode | codex | gemini | vscode | windsurf | agent-skills | all
     enforce: null               # Enforce specific target (must be present in list)
   strategy:
     enforce: null               # distributed | single-file
@@ -915,5 +915,5 @@ manifest:
 ## Related
 
 - [Governance](../../enterprise/governance-guide/) -- conceptual overview, bypass contract, and rollout playbook
-- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI setup tutorial
+- [Enforce in CI](../enforce-in-ci/) -- step-by-step CI setup tutorial
 - [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check

docs/src/content/docs/enterprise/registry-proxy.md

@@ -122,7 +122,7 @@ at one hosted on GHES, GHE.com, or GitLab self-managed:
 ```bash
 apm marketplace add acme-tools/agents \
   --host ghes.corp.example.com \
-  --branch main
+  --ref main
 ```
 
 The entry is stored in `~/.apm/marketplaces.json`. Auth uses the same
@@ -160,11 +160,11 @@ and `apm cache clean`.
 
 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/).
+[Pack and distribute](../../producer/pack-a-bundle/).
 
 ## See also
 
 - [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
+- [Pack and distribute](../../producer/pack-a-bundle/) -- air-gapped bundle delivery
 - [Governance overview](../governance-overview/) -- policy-cache offline story

docs/src/content/docs/enterprise/security-and-supply-chain.md

@@ -39,7 +39,7 @@ 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.
+(`content_hash` mismatch handling around lines 770-784).
 
 **Cache-hit verification.** On every cache HIT, APM reads the cached
 checkout's `.git/HEAD` and compares it to the lockfile's
@@ -52,7 +52,7 @@ 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`
+Source: `src/apm_cli/bundle/local_bundle.py:287-368`
 (`verify_bundle_integrity`).
 
 ## Provenance
@@ -89,7 +89,7 @@ APM has no secret store. The contract is:
   `src/apm_cli/integration/mcp_integrator.py` (runtime wiring).
 - **`apm install` writes `apm_modules/` to `.gitignore` automatically**
   on first install. Source:
-  `src/apm_cli/commands/_helpers.py:437` (`_update_gitignore_for_apm_modules`).
+  `src/apm_cli/commands/_helpers.py:414` (`_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.

docs/src/content/docs/enterprise/security.md

@@ -137,7 +137,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. (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/).)
+- **`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; prefer `apm install <bundle-path>` for new pipelines -- it applies the same scan plus lockfile integration. See [Pack and distribute](../../producer/pack-a-bundle/).)
 
 ### On-demand scanning