docs: migrate to Astro Starlight documentation site by danielmeppiel · Pull Request #243 · microsoft/apm

danielmeppiel · 2026-03-11T06:09:15Z

Summary

Migrates the documentation from plain markdown files to an Astro 5 + Starlight documentation site with search, structured navigation, and GitHub Pages deployment.

Closes #236

What's included

Infrastructure

Astro 5.18 + Starlight 0.37 static site with Pagefind search
GitHub Pages workflow (.github/workflows/docs.yml)
Plugins: starlight-links-validator, starlight-llms-txt, astro-mermaid

Content migration

All 23 existing docs migrated to Starlight content structure
Structured sidebar: Introduction → Getting Started → Guides → Integrations → Reference → Contributing

Landing page

Product narrative rewrite with pain→solution arc
4-card feature grid (primitives, dependencies, any git host, Copilot & Claude)
Quick Start section (no apm compile)
apm.yml manifest example showcasing multi-host sources + version pinning
Open Source & Community section

Authentication split

Installation page now starts with install instructions (no auth wall)
New Authentication page under Getting Started with:
- Token configuration (GITHUB_APM_PAT, ADO_APM_PAT, GITHUB_COPILOT_PAT, GITHUB_HOST)
- GitHub Enterprise support & examples
- Azure DevOps support & URL formats
- Token creation guide

Custom CSS

Refined nav title (uppercase, smaller, lighter)
Hero h1 nowrap
Card grid spacing

How to preview

cd docs && npm install && npx astro dev

Build verification

✅ 24 pages built
✅ All internal links valid (starlight-links-validator)
✅ Pagefind search index generated
✅ Sitemap generated

- Migrate all 23 markdown docs to Astro 5 + Starlight 0.37 - Add Pagefind search, structured sidebar, GitHub Pages workflow - Rewrite landing page with product narrative and manifest example - Split authentication into dedicated page (no auth wall on install) - Custom CSS: refined nav title, hero styling, card grid spacing - Plugins: starlight-links-validator, starlight-llms-txt, astro-mermaid Closes #236

- Fix Codex CLI section: correct setup command to 'apm runtime setup codex', document .github/ primitive discovery and MCP config at ~/.codex/config.toml - Add GitHub Copilot CLI section with setup, MCP config, and features - Add Skills to VSCode native primitives list (.github/skills/) - Add Compiled Context with AGENTS.md subsection to VSCode integration - Enhance Cursor section with AGENTS.md discovery, cursor rules reference, distributed compilation, and compile flags (--dry-run, --verbose, --watch) - Add MCP Auto-Discovery from Packages section (apm.yml, plugin.json, transitive) - Add MCP Trust Model section with direct/transitive trust table and --trust-transitive-mcp flag documentation - Add MCP Client Configuration section with per-client config locations and runtime targeting options (--runtime, --exclude, --only mcp) - Update MCP Supported Package Types table to include Codex CLI column - Enhance MCP Server Management with full dependency format examples (simple, overlay, self-defined) and apm mcp subcommands - Enhance Claude Desktop Integration with .github/skills/ primary location and .claude/skills/ compatibility copy detail - Add sub-skill promotion detail to skills integration - Fix broken markdown table separator in Claude output files table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add 12 new pages: what-is-apm, quick-start, migration, pack-distribute, org-packages, lockfile-spec, github-rulesets, and 5 enterprise pages (teams, governance, security, adoption-playbook, making-the-case) - Enhance 5 existing pages: why-apm, installation, ci-cd, gh-aw, ide-tool-integration - Restructure sidebar into 8 sections with progressive disclosure - Clean up ide-tool-integration (928->616 lines, remove template content) - Remove emojis from all doc headings per project policy - All 36 pages build clean, all internal links validated Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR migrates the repository documentation from standalone Markdown files to an Astro + Starlight docs site under docs/, adds GitHub Pages deployment, and restructures/migrates the content into Starlight’s routing + sidebar model.

Changes:

Adds an Astro/Starlight docs site scaffold (config, deps, TS config, styles, favicon).
Migrates/reorganizes docs into docs/src/content/docs/** with frontmatter and updated internal links.
Adds a GitHub Actions workflow to build and deploy the docs site to GitHub Pages.

Reviewed changes

Copilot reviewed 46 out of 48 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
docs/tsconfig.json	Adds strict Astro TS config for the docs project.
docs/src/styles/custom.css	Adds custom styling tweaks for Starlight UI.
docs/src/content/docs/reference/primitive-types.md	Adds Starlight frontmatter and updates page placement.
docs/src/content/docs/reference/manifest-schema.md	Adds Starlight frontmatter for the manifest spec page.
docs/src/content/docs/reference/lockfile-spec.md	Adds new lockfile specification reference page.
docs/src/content/docs/reference/examples.md	Adds Starlight frontmatter + updates various links/wording.
docs/src/content/docs/reference/cli-commands.md	Adds Starlight frontmatter for CLI reference page.
docs/src/content/docs/introduction/why-apm.md	Adds new “Why APM?” narrative page.
docs/src/content/docs/introduction/what-is-apm.md	Adds new “What is APM?” narrative page.
docs/src/content/docs/introduction/key-concepts.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/introduction/how-it-works.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/integrations/runtime-compatibility.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/integrations/ide-tool-integration.md	Adds Starlight frontmatter and large content rewrite for integrations.
docs/src/content/docs/integrations/github-rulesets.md	Adds new GitHub Rulesets governance page.
docs/src/content/docs/integrations/gh-aw.md	Adds new GitHub Agentic Workflows integration page.
docs/src/content/docs/integrations/ci-cd.md	Adds new CI/CD integration page.
docs/src/content/docs/index.mdx	Adds new Starlight splash/landing page content.
docs/src/content/docs/guides/skills.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/guides/prompts.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/guides/plugins.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/guides/pack-distribute.md	Adds new “Pack & Distribute” guide.
docs/src/content/docs/guides/org-packages.md	Adds new org-wide packages guide.
docs/src/content/docs/guides/dependencies.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/guides/compilation.md	Adds Starlight frontmatter and updates internal links.
docs/src/content/docs/getting-started/quick-start.md	Adds new Quick Start walkthrough page.
docs/src/content/docs/getting-started/migration.md	Adds new migration guide for existing projects.
docs/src/content/docs/getting-started/installation.md	Splits/auth content and refocuses installation page; updates links.
docs/src/content/docs/getting-started/first-package.md	Adds new “Your First Package” tutorial page.
docs/src/content/docs/getting-started/authentication.md	Adds new dedicated authentication page.
docs/src/content/docs/enterprise/teams.md	Adds new teams-focused enterprise narrative page.
docs/src/content/docs/enterprise/security.md	Adds new enterprise security model page.
docs/src/content/docs/enterprise/making-the-case.md	Adds new adoption advocacy/talking points page.
docs/src/content/docs/enterprise/governance.md	Adds new governance & compliance page.
docs/src/content/docs/enterprise/adoption-playbook.md	Adds new phased adoption playbook page.
docs/src/content/docs/contributing/integration-testing.md	Adds Starlight frontmatter for contributing page.
docs/src/content/docs/contributing/development-guide.md	Adds new development guide page.
docs/src/content/docs/contributing/changelog.md	Adds new changelog page linking to root CHANGELOG.md.
docs/src/content/docs/404.md	Adds Starlight 404 page.
docs/src/content.config.ts	Adds Starlight content collection config.
docs/public/favicon.svg	Adds favicon asset.
docs/package.json	Adds docs-site Node dependencies and scripts.
docs/index.md	Removes old docs index markdown (replaced by Starlight index.mdx).
docs/astro.config.mjs	Adds Astro/Starlight config including sidebar + plugins.
docs/README.md	Removes old docs README (superseded by site).
docs/.gitignore	Adds docs-specific ignores (node_modules, dist, .astro).
.github/workflows/docs.yml	Adds CI workflow to build + deploy docs to GitHub Pages.
.github/instructions/doc-sync.instructions.md	Updates doc-sync guidance to target Starlight content tree and linking style.

Comments suppressed due to low confidence (3)

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

This page references apm.yaml, but the repository’s manifest filename is apm.yml (as used throughout the rest of the docs and the manifest schema). Update these references to apm.yml to avoid confusing users.

### No registry

APM does not use a package registry. Dependencies are specified as git repository URLs in `apm.yaml`. This eliminates the registry compromise vector entirely — there is no centralized service that can be poisoned to redirect installs.

### Reproducible installs

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

More apm.yaml references here should be apm.yml (the manifest format in this repo). Updating this avoids implying a different filename and keeps terminology consistent with the manifest schema page.

MCP servers declared by your direct dependencies (packages listed in your `apm.yaml`) are auto-trusted. You explicitly chose to depend on these packages, so their MCP server declarations are accepted.

### Transitive dependencies

MCP servers declared by transitive dependencies (dependencies of your dependencies) are **blocked by default**. APM prints a warning and skips the MCP server entry.

To allow transitive MCP servers, you must either:

- **Re-declare the dependency** in your own `apm.yaml`, promoting it to a direct dependency.
- **Pass `--trust-transitive-mcp`** to explicitly opt in to transitive MCP servers for that install.

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

apm add does not appear to be a supported CLI command in this repo. For adding dependencies, users should either run apm install <pkg>... (which updates apm.yml) or edit dependencies.apm in apm.yml directly.

   ```bash
   apm add org/lint-standards org/agent-instructions org/prompt-library

</details>

Copilot · 2026-03-11T17:58:08Z

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

+```
+apm.yml (declare) -> apm.lock (pin) -> apm audit (verify) -> CI gate (enforce)
+```
+
+| Stage | Purpose | Artifact |
+|-------|---------|----------|
+| **Declare** | Define dependencies and their sources | `apm.yml` |
+| **Pin** | Resolve every dependency to an exact commit | `apm.lock` |
+| **Verify** | Confirm on-disk state matches the lock file | `apm audit` output |
+| **Enforce** | Block merges when verification fails | Required status check |


This governance pipeline references an apm audit command, but there is no audit command implemented in the current CLI (no src/apm_cli/commands/audit.py and no audit registration). Either implement apm audit/apm audit --ci before publishing these docs, or adjust the docs to describe the currently available commands.

This is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

Copilot · 2026-03-11T17:58:09Z

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

+GitHub Rulesets and branch protection rules can require status checks before merging. APM's `apm audit --ci` integrates as a required status check to enforce agent configuration governance, ensuring that changes to agent context go through the manifest and lock file rather than being made ad hoc.
+
+## How It Works
+
+The workflow is straightforward:
+
+1. `apm audit --ci` runs in a GitHub Actions workflow on every pull request.
+2. It verifies that the lock file matches the installed state, no undeclared config changes exist, and all dependencies are resolvable.
+3. You configure this workflow as a required status check in branch protection or Rulesets.


This page repeatedly instructs using apm audit --ci, but the current CLI in this repo does not have an apm audit command. Either implement apm audit or change the guidance/status claims (e.g., ‘Available now’) to avoid publishing non-functional instructions.

This is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

Copilot · 2026-03-11T17:58:09Z

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

+
+### Security properties
+
+- **Never stored in files.** Tokens are read from the environment at runtime. They are never written to `apm.yaml`, `apm.lock`, or any generated file.


This bullet says tokens are never written to apm.yaml, but the manifest filename in this project is apm.yml. Update the filename in this statement for consistency and to prevent confusion in security reviews.

This issue also appears in the following locations of the same file:

line 52

line 108

Suggested change

- **Never stored in files.** Tokens are read from the environment at runtime. They are never written to `apm.yaml`, `apm.lock`, or any generated file.

- **Never stored in files.** Tokens are read from the environment at runtime. They are never written to `apm.yml`, `apm.lock`, or any generated file.

Copilot · 2026-03-11T17:58:10Z

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

+   ```bash
+   apm add myorg/apm-standards
+   apm install
+   ```


This section uses apm add again, but the CLI in this repo doesn’t include an add command. Replace with apm install <pkg> (which updates apm.yml) or instruct editing dependencies.apm in apm.yml directly.

This issue also appears on line 38 of the same file.

Copilot · 2026-03-11T17:58:10Z

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

+
+   - name: Audit for drift
+     run: apm audit --ci
+   ```
+
+2. Make the audit step a **required status check** on pull requests.
+3. Ensure `apm.lock` is committed. Any version drift will cause the audit
+   to fail, surfacing the problem before merge.
+


This CI step uses apm audit --ci, but the current CLI doesn’t implement an apm audit command. Either update the playbook to use existing commands, or mark audit as a planned feature and remove it from the recommended pipeline until it ships.

Suggested change

- name: Audit for drift

run: apm audit --ci

```

2. Make the audit step a **required status check** on pull requests.

3. Ensure `apm.lock` is committed. Any version drift will cause the audit

to fail, surfacing the problem before merge.

Note: An apm audit command is planned but not yet available. Once it
ships, add an audit step here and make it a required CI check to enforce
drift detection.

Make the APM CI step a required status check on pull requests.

Ensure apm.lock is committed and reviewed. This keeps configuration
changes explicit and ready for future audit capabilities.

This is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

Copilot · 2026-03-11T17:58:10Z

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

+### 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.


apm install --check is not a supported CLI flag (there is apm update --check, but no install --check). Replace this with the actual command you want users to run (likely apm audit --ci once implemented, or remove the flag reference until the feature exists).

Suggested change

- **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.** Add `apm update --check` to your CI pipeline. Builds fail if agent configuration has drifted from the declared manifest.

This should be audit ci. That command is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

Copilot · 2026-03-11T17:58:10Z

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

+packages:
+  - name: org-security-rules
+    source: github:your-org/apm-packages
+    version: "^2.0"
+  - name: team-coding-standards
+    source: github:your-org/team-packages
+    version: "~1.3"
+  - name: project-context
+    source: ./local-packages/context


The manifest example uses a top-level packages: key, but the documented manifest schema for this repo uses dependencies: with apm:/mcp: lists. Please rewrite this example to match apm.yml as defined in the Manifest Schema reference so it’s copy/pasteable.

Suggested change

packages:

- name: org-security-rules

source: github:your-org/apm-packages

version: "^2.0"

- name: team-coding-standards

source: github:your-org/team-packages

version: "~1.3"

- name: project-context

source: ./local-packages/context

dependencies:

apm:

- name: org-security-rules

source: github:your-org/apm-packages

version: "^2.0"

- name: team-coding-standards

source: github:your-org/team-packages

version: "~1.3"

- name: project-context

source: ./local-packages/context

Copilot · 2026-03-11T17:58:11Z

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

+packages:
+  - name: code-review-standards
+    source: https://github.com/contoso/agent-standards.git
+    ref: v2.1.0
+  - name: security-policies
+    source: https://github.com/contoso/security-agents.git
+    ref: v1.3.0


This example uses a top-level packages: mapping, which doesn’t match the repo’s apm.yml schema (see reference: dependencies: → apm:/mcp:). Updating this snippet to the real schema will prevent users from copying an invalid manifest.

Suggested change

packages:

- name: code-review-standards

source: https://github.com/contoso/agent-standards.git

ref: v2.1.0

- name: security-policies

source: https://github.com/contoso/security-agents.git

ref: v1.3.0

dependencies:

apm:

- name: code-review-standards

source: https://github.com/contoso/agent-standards.git

ref: v2.1.0

- name: security-policies

source: https://github.com/contoso/security-agents.git

ref: v1.3.0

Copilot · 2026-03-11T17:58:11Z

docs/src/content/docs/integrations/ci-cd.md

+## Governance with `apm audit`
+
+Run `apm audit --ci` in pull requests to verify the lock file matches the installed state. This catches configuration drift before it reaches your default branch.
+
+```yaml
+# .github/workflows/apm-audit.yml
+name: APM Audit
+on: [pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+        with:
+          commands: |
+            apm install
+            apm audit --ci
+        env:
+          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}


This section and workflow YAML reference apm audit --ci, but the current CLI does not implement an apm audit command. Update this doc to either (1) use existing commands, or (2) clearly mark apm audit as not yet available and link to the tracking issue/PR.

This is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

Copilot · 2026-03-11T17:58:11Z

docs/src/content/docs/reference/lockfile-spec.md

+In CI pipelines, `apm audit --ci` verifies the lock file is in sync with the
+manifest and that all deployed files are present.


This spec states that CI uses apm audit --ci, but the current CLI doesn’t include an apm audit command. The spec should describe the actual current verification mechanism, or note apm audit as a planned command (and avoid MUST-level language until it exists).

This is in the roadmap so we could eventually allude to it always making it clear that it's in the roadmap but not yet there (WIP). It's still valuable for the overall positioning and UVP

danielmeppiel · 2026-03-11T18:16:05Z

@copilot address the PR review comments. Consider my own comments authoritative.

Copilot · 2026-03-11T18:16:14Z

@danielmeppiel I've opened a new pull request, #250, to work on those changes. Once the pull request is ready, I'll request review from you.

danielmeppiel added the priority/high Ships in current or next milestone label Mar 11, 2026

danielmeppiel and others added 4 commits March 11, 2026 07:10

Merge branch 'main' into feat/docs-site

51c45f1

Merge branch 'main' into feat/docs-site

9bd7dcb

danielmeppiel marked this pull request as ready for review March 11, 2026 17:50

Copilot AI review requested due to automatic review settings March 11, 2026 17:50

Copilot started reviewing on behalf of danielmeppiel March 11, 2026 17:51 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 11, 2026

docs: fix schema errors, invalid commands, and mark apm audit as roadmap #250

Closed

7 tasks

sergio-sisternes-epam approved these changes Mar 11, 2026

View reviewed changes

sergio-sisternes-epam merged commit 97ed94a into main Mar 11, 2026
49 checks passed

sergio-sisternes-epam deleted the feat/docs-site branch March 11, 2026 18:42

This was referenced Mar 12, 2026

[docs] Update documentation for features from 2026-03-12 #255

Closed

docs: narrative redesign for accuracy and cohesion #258

Merged

chore: update Unreleased changelog with PRs merged since v0.7.7 #271

Merged


		### Security properties

		- Never stored in files. Tokens are read from the environment at runtime. They are never written to `apm.yaml`, `apm.lock`, or any generated file.

	- 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. Add `apm update --check` to your CI pipeline. Builds fail if agent configuration has drifted from the declared manifest.

		In CI pipelines, `apm audit --ci` verifies the lock file is in sync with the
		manifest and that all deployed files are present.

Conversation

danielmeppiel commented Mar 11, 2026

Summary

What's included

Infrastructure

Content migration

Landing page

Authentication split

Custom CSS

How to preview

Build verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

danielmeppiel commented Mar 11, 2026

Uh oh!

Copilot AI commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants