docs: narrative redesign for accuracy and cohesion

docs/astro.config.mjs

@@ -55,7 +55,7 @@ export default defineConfig({
 						{ label: 'Quick Start', slug: 'getting-started/quick-start' },
 						{ label: 'Your First Package', slug: 'getting-started/first-package' },
 						{ label: 'Authentication', slug: 'getting-started/authentication' },
-						{ label: 'Migrating Projects', slug: 'getting-started/migration' },
+						{ label: 'Existing Projects', slug: 'getting-started/migration' },
 					],
 				},
 				{
@@ -68,6 +68,7 @@ export default defineConfig({
 						{ label: 'Dependencies & Lockfile', slug: 'guides/dependencies' },
 						{ label: 'Pack & Distribute', slug: 'guides/pack-distribute' },
 						{ label: 'Org-Wide Packages', slug: 'guides/org-packages' },
+						{ label: 'Agent Workflows (Experimental)', slug: 'guides/agent-workflows' },
 					],
 				},
 				{

docs/src/content/docs/enterprise/adoption-playbook.md

@@ -119,8 +119,10 @@ reach production.
    - name: Install APM packages
      run: apm install
 
-   - name: Compile configuration
-     run: apm compile
+   # Optional: only needed if targeting Cursor, Codex, Gemini, or other
+   # tools without native APM integration
+   # - name: Compile configuration
+   #   run: apm compile
 
    - name: Audit for drift
      run: apm audit --ci

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

@@ -102,6 +102,10 @@ No additional tooling is required. The lock file turns git into an agent configu
 
 ## CI enforcement with `apm audit --ci`
 
+:::note[Planned Feature]
+`apm audit --ci` is not yet available. The following describes planned behavior and is provided to illustrate the intended workflow.
+:::
+
 The `apm audit --ci` command is designed to run as a required status check in your CI pipeline. It verifies that the lock file is in sync with the declared manifest and that deployed files match expectations.
 
 ### What it catches
@@ -151,6 +155,10 @@ This ensures every merge to a protected branch has a verified, consistent agent
 
 ## Drift detection with `apm audit --drift`
 
+:::note[Planned Feature]
+`apm audit --drift` is not yet available. The following describes planned behavior and is provided to illustrate the intended workflow.
+:::
+
 Drift occurs when the on-disk state of agent configuration diverges from what the lock file declares. The `apm audit --drift` command detects this divergence.
 
 ### What drift detection catches
@@ -274,9 +282,9 @@ This ensures that organizational rules are consistently applied across all teams
 
 GitHub Rulesets provide a scalable way to enforce APM governance across multiple repositories.
 
-### Level 1: Required status check (available now)
+### Level 1: Required status check
 
-Configure `apm audit --ci` as a required status check through Rulesets:
+Once `apm audit --ci` is available (see [CI enforcement](#ci-enforcement-with-apm-audit---ci) above), configure it as a required status check through Rulesets:
 
 1. Create a new Ruleset at the organization or repository level.
 2. Target the branches you want to protect (e.g., `main`, `release/*`).
@@ -325,7 +333,7 @@ APM enforces change management by design:
 1. **Declaration.** Changes start in `apm.yml`, which is a committed, reviewable file.
 2. **Resolution.** `apm install` resolves declarations to exact commits in `apm.lock`.
 3. **Review.** Both files are included in the PR diff for peer review.
-4. **Verification.** `apm audit --ci` confirms consistency before merge.
+4. **Verification.** `apm audit --ci` confirms consistency before merge (planned — currently achieved through PR review of `apm.lock` diffs).
 5. **Traceability.** Git history provides a permanent record of who changed what and when.
 
 No agent configuration change can reach a protected branch without passing through this pipeline.

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

@@ -35,7 +35,7 @@ An internal advocacy toolkit for APM. Each section is self-contained and designe
 ### For Platform Teams
 
 - **Standardize AI configuration across N repos.** Publish a shared APM package with your organization's coding standards, approved MCP servers, and prompt templates. Every repo that depends on it stays in sync.
-- **Enforce standards via CI gates.** Add `apm install --check` to your CI pipeline. Builds fail if agent configuration has drifted from the declared manifest.
+- **Enforce standards via CI gates.** APM's planned `apm audit --ci` command will gate pull requests when agent configuration drifts from the declared manifest, enabling automated enforcement in your CI pipeline.
 - **Version-controlled standards updates.** When standards change, update the shared package and bump the version. Teams adopt updates through normal dependency management, not ad-hoc communication.
 
 ### For Individual Developers
@@ -54,7 +54,7 @@ Plugins handle single-tool installation for a single AI platform. APM adds capab
 
 - **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, and any other agent runtime simultaneously.
 - **Consumer-side lock files.** Plugins install the latest version. APM pins exact versions so your team stays synchronized.
-- **CI enforcement.** There is no plugin equivalent of `apm install --check` in a CI pipeline.
+- **CI enforcement.** There is no plugin equivalent of `apm audit --ci` for drift detection in a CI pipeline.
 - **Multi-source dependency resolution.** APM resolves transitive dependencies across packages from multiple git hosts.
 - **Shared organizational packages.** Plugins are published by tool vendors. APM packages are published by your own teams, containing your own standards and configurations.
 
@@ -129,7 +129,7 @@ For stakeholders familiar with existing tools, this comparison clarifies where A
 | Version pinning | None | Vendor-controlled | Consumer-side lock file |
 | Cross-tool support | N separate processes | Single tool only | Unified manifest |
 | Dependency resolution | Manual | None | Automatic, transitive |
-| CI enforcement | Custom scripts | Not available | Built-in (`--check` flag) |
+| CI enforcement | Custom scripts | Not available | Planned (`apm audit --ci`) |
 | Shared org standards | Wiki pages, copy-paste | Not available | Versioned packages |
 | Audit trail | Implicit via git | Varies by vendor | Explicit via `apm.lock` |
 | Lock-in | To manual process | To specific vendor | None (native output files) |
@@ -197,4 +197,4 @@ With APM, setup reduces to `apm install` (under 30 seconds). Standards updates r
 1. Review the [Adoption Playbook](../adoption-playbook/) for a phased rollout plan.
 2. Start with a single team or repository as a pilot.
 3. Publish a shared package with your organization's standards using the [APM for Teams](../teams/) guide.
-4. Add `apm install --check` to CI and measure drift reduction over 30 days.
+4. Add `apm audit --ci` to CI when available and measure drift reduction over 30 days.

docs/src/content/docs/enterprise/teams.md

@@ -93,7 +93,7 @@ Configuration is ready. Updates are a pull request to `apm.yml`.
 
 A mid-size organization maintains three layers of configuration: organization-wide security rules, team-specific coding standards, and project-level context. Different teams need different combinations.
 
-APM composes these layers through its dependency model. The organization publishes shared packages. Each team's `apm.yml` references the org packages it needs alongside team and project packages. Compilation merges them in the correct order.
+APM composes these layers through its dependency model. The organization publishes shared packages. Each team's `apm.yml` references the org packages it needs alongside team and project packages. `apm install` deploys them for Copilot and Claude natively; `apm compile` can merge them into instruction files for other tools.
 
 ```yaml
 packages:
@@ -152,5 +152,5 @@ For hands-on setup and deeper topics, start here:
 
 - [Quick Start](../../getting-started/installation/) — install APM and configure your first project in five minutes.
 - [Organization-Wide Packages](../../guides/org-packages/) — publish and maintain shared configuration packages across your organization.
-- [Compilation Guide](../../guides/compilation/) — understand how APM merges and transforms configuration from multiple sources.
+- [Compilation Guide](../../guides/compilation/) — optional: generate instruction files for tools without native APM integration (Cursor, Codex, Gemini).
 - [Dependencies Guide](../../guides/dependencies/) — version constraints, lock file mechanics, and update workflows.

docs/src/content/docs/getting-started/authentication.md

@@ -12,7 +12,7 @@ APM works without any tokens for public packages. Authentication is only needed
 |----------|---------|-------------|
 | `GITHUB_APM_PAT` | Private GitHub/GHE repos | Private GitHub packages |
 | `ADO_APM_PAT` | Private Azure DevOps repos | Private ADO packages |
-| `GITHUB_COPILOT_PAT` | Copilot runtime | `apm run` with Copilot |
+| `GITHUB_COPILOT_PAT` | Copilot runtime | Runtime features (see [Agent Workflows](../../guides/agent-workflows/)) |
 | `GITHUB_HOST` | Default host for bare package names | GitHub Enterprise setups |
 
 ### GITHUB_APM_PAT
@@ -41,7 +41,7 @@ export ADO_APM_PAT=your_ado_pat
 export GITHUB_COPILOT_PAT=ghp_copilot_token
 ```
 
-- **Purpose**: Authentication for `apm run` with Copilot runtime
+- **Purpose**: Authentication for runtime features (see [Agent Workflows guide](../../guides/agent-workflows/))
 - **Type**: Personal Access Token with Copilot access
 - **Fallback**: Falls back to `GITHUB_TOKEN` if not set
 
@@ -87,7 +87,9 @@ export GITHUB_APM_PAT=ghp_enterprise_token
 apm install team/package  # → github.company.com/team/package
 ```
 
-#### Running Prompts
+#### Runtime Features
+
+Authentication may be needed for runtime features. See the [Agent Workflows guide](../../guides/agent-workflows/) for details.
 
 ```bash
 export GITHUB_COPILOT_PAT=ghp_copilot_token
@@ -159,6 +161,6 @@ apm install dev.azure.com/myorg/myproject/myrepo/prompts/code-review.prompt.md
    - Go to `https://dev.azure.com/{org}/_usersSettings/tokens`
    - Create PAT with **Code (Read)** scope
 
-3. **GITHUB_COPILOT_PAT** (Running prompts):
+3. **GITHUB_COPILOT_PAT** (Runtime features -- see [Agent Workflows](../../guides/agent-workflows/)):
    - Go to [github.com/settings/tokens](https://github.com/settings/tokens)
    - Create token with Copilot access

docs/src/content/docs/getting-started/first-package.md

@@ -103,15 +103,15 @@ APM automatically:
 - Copies prompts to `.github/prompts/`
 - Updates `apm.yml` with the dependency
 
-## 7. Compile
+## 7. Optional: Compile for Other Tools
 
-Generate the compiled context files:
+If you use tools beyond GitHub Copilot and Claude (which read deployed primitives natively), generate compiled instruction files:
 
 ```bash
 apm compile
 ```
 
-This produces `AGENTS.md` (for Copilot, Cursor, Codex) and `CLAUDE.md` (for Claude) with all your instructions optimized for each agent.
+This produces `AGENTS.md` (for Cursor, Codex) and `CLAUDE.md` for tools that need a single instructions file. Copilot and Claude users can skip this step.
 
 ## Next Steps