docs: fix orphan pages and update stale rulesets content

docs/astro.config.mjs

@@ -69,6 +69,7 @@ export default defineConfig({
 						{ label: 'Pack & Distribute', slug: 'guides/pack-distribute' },
 						{ label: 'Private Packages', slug: 'guides/private-packages' },
 						{ label: 'Org-Wide Packages', slug: 'guides/org-packages' },
+						{ label: 'CI Policy Enforcement', slug: 'guides/ci-policy-setup' },
 						{ label: 'Agent Workflows (Experimental)', slug: 'guides/agent-workflows' },
 					],
 				},
@@ -77,6 +78,7 @@ export default defineConfig({
 					items: [
 						{ label: 'APM for Teams', slug: 'enterprise/teams' },
 						{ label: 'Governance & Compliance', slug: 'enterprise/governance' },
+						{ label: 'Policy Reference', slug: 'enterprise/policy-reference' },
 						{ label: 'Security Model', slug: 'enterprise/security' },
 						{ label: 'Adoption Playbook', slug: 'enterprise/adoption-playbook' },
 						{ label: 'Making the Case', slug: 'enterprise/making-the-case' },

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

@@ -499,3 +499,9 @@ dependencies:
     - "contoso/agent-standards"
   max_depth: 5  # Tightens from 10 to 5
 ```
+
+## Related
+
+- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model
+- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI setup tutorial
+- [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check

docs/src/content/docs/guides/agent-workflows.md

@@ -2,7 +2,7 @@
 title: "Agent Workflows (Experimental)"
 description: "Run agentic workflows locally using APM scripts and AI runtimes."
 sidebar:
-  order: 8
+  order: 9
 ---
 
 :::caution[Experimental Feature]

docs/src/content/docs/guides/ci-policy-setup.md

@@ -1,7 +1,7 @@
 ---
 title: CI Policy Enforcement
 sidebar:
-  order: 5
+  order: 8
 ---
 
 :::caution[Experimental Feature]
@@ -212,3 +212,9 @@ apm-policy:
 | SARIF | `-f sarif` | GitHub Code Scanning, VS Code |
 
 Combine with `-o <path>` to write to a file.
+
+## Related
+
+- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model
+- [Policy Reference](../../enterprise/policy-reference/) -- full `apm-policy.yml` schema reference
+- [GitHub Rulesets](../../integrations/github-rulesets/) -- enforce policy as a required status check

docs/src/content/docs/integrations/github-rulesets.md

@@ -58,36 +58,53 @@ Once configured, any PR that introduces content issues detected by `apm audit` w
 
 ## What It Catches
 
-`apm audit` detects the following content issues:
+`apm audit` operates in three modes, each adding more checks:
 
-- **Hidden Unicode characters** — tag characters, bidi overrides, and variation selectors embedded in prompt files.
-- **Zero-width and invisible characters** — characters that could alter agent behavior without visible changes.
+**Content scanning** (`apm audit`):
+- **Critical: Hidden Unicode characters** -- tag characters (U+E0001-E007F), bidi overrides (U+202A-202E, U+2066-2069), and SMP variation selectors. Exit code **1**.
+- **Warning: Zero-width and invisible characters** -- zero-width spaces/joiners, mid-file BOM, soft hyphens. Exit code **2**. These are suspicious but not attack vectors.
 
-When issues are detected, the command exits with a non-zero status code (1 = critical, 2 = warnings) and the check fails.
+**CI baseline checks** (`apm audit --ci`) -- adds lockfile verification on top of content scanning:
+- **Lockfile exists** -- validates `apm.lock.yaml` is present when dependencies are declared
+- **Ref consistency** -- every dependency's manifest ref matches the lockfile
+- **Deployed files present** -- all files listed in lockfile exist on disk
+- **No orphaned packages** -- no packages in lockfile are absent from manifest
+- **Config consistency** -- MCP server configs match lockfile baseline
+- **Content integrity** -- fails on **critical** Unicode only (warnings are not CI-blocking)
 
-## Governance Levels
+In `--ci` mode, exit codes are binary: **0** = pass, **1** = fail. Warning-level characters do not fail CI.
+
+**Policy enforcement** (`apm audit --ci --policy org`) -- adds organizational rules:
+- **Approved/denied sources** -- restrict which repositories packages can come from
+- **MCP transport controls** -- allow/deny transport types, trust settings for transitive MCP
+- **Manifest requirements** -- enforce required fields, content types, scripts
+- **Compilation rules** -- target and strategy constraints
+- **Unmanaged file detection** -- flag files in integration directories not tracked by the lockfile
 
-APM's integration with GitHub governance is evolving:
+For full setup instructions, see the [CI Policy Enforcement](../../guides/ci-policy-setup/) guide. For the complete policy schema, see the [Policy Reference](../../enterprise/policy-reference/).
+
+## Governance Levels
 
 | Level | Description | Status |
 |-------|-------------|--------|
-| 1 | `apm audit` as a required status check (content scanning via exit codes) | Available now |
-| 1+ | `apm audit --ci` with lockfile consistency checking | Planned |
-| 2 | GitHub recommends apm-action for agent governance | Future |
-| 3 | Native Rulesets UI for agent configuration policy | Future |
+| 1 | `apm audit` as a required status check (content scanning: critical=exit 1, warning=exit 2) | Available |
+| 2 | `apm audit --ci` with lockfile verification (binary pass/fail, warnings do not block) | Available |
+| 3 | `apm audit --ci --policy org` with organization policy enforcement | Available |
+| 4 | GitHub recommends apm-action for agent governance | Future |
+| 5 | Native Rulesets UI for agent configuration policy | Future |
 
-Level 1 is fully functional today using `apm audit` exit codes. Level 1+ (lockfile consistency) and Levels 2–3 represent deeper integration that would reduce setup friction.
+Levels 1-3 are fully functional today. See the [CI Policy Enforcement](../../guides/ci-policy-setup/) guide for step-by-step setup. Levels 4-5 represent deeper GitHub platform integration that would reduce setup friction.
 
 ## Combining with Other Checks
 
-APM audit complements your existing CI checks — it does not replace them. A typical PR pipeline might include:
+APM audit complements your existing CI checks -- it does not replace them. A typical PR pipeline might include:
 
-- **Linting and formatting** — code style enforcement
-- **Unit and integration tests** — functional correctness
-- **Security scanning** — vulnerability detection
-- **APM audit** — hidden Unicode scanning with CI reporting
+- **Linting and formatting** -- code style enforcement
+- **Unit and integration tests** -- functional correctness
+- **Security scanning** -- vulnerability detection
+- **APM audit** -- content scanning, lockfile verification, and policy enforcement
 
-Each check has a distinct purpose. APM audit focuses on detecting hidden Unicode characters that could embed invisible instructions in prompt files.
+Each check has a distinct purpose. APM audit focuses on AI agent configuration integrity -- from hidden Unicode detection to organizational policy compliance.
 
 ## Customizing the Workflow
 
@@ -150,5 +167,8 @@ The status check name must match the **job name** in your workflow file (e.g., `
 
 ## Related
 
-- [CI/CD Pipelines](../ci-cd/) — full CI integration guide
-- [Manifest Schema](../../reference/manifest-schema/) — manifest and lock file reference
+- [CI Policy Enforcement](../../guides/ci-policy-setup/) -- step-by-step CI setup for policy enforcement
+- [Governance & Compliance](../../enterprise/governance/) -- conceptual overview of APM's governance model
+- [Policy Reference](../../enterprise/policy-reference/) -- full `apm-policy.yml` schema reference
+- [CI/CD Pipelines](../ci-cd/) -- general CI integration guide
+- [Manifest Schema](../../reference/manifest-schema/) -- manifest and lock file reference