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,46 @@ 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` provides two tiers of 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.
+**Baseline checks** (always available):
+- **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
+- **Lockfile consistency** (`apm audit --ci`) -- verifies installed packages match the lockfile, detects missing or modified files, and checks for unresolved dependencies
+
+**Policy enforcement checks** (`apm audit --ci --policy org`):
+- **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
 
 When issues are detected, the command exits with a non-zero status code (1 = critical, 2 = warnings) and the check fails.
 
-## Governance Levels
+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/).
 
-APM's integration with GitHub governance is evolving:
+## 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 via exit codes) | Available |
+| 2 | `apm audit --ci` with lockfile consistency checking | 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 +160,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