microsoft · danielmeppiel · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
@@ -5,8 +5,10 @@ description: "Rules to keep documentation synchronized with code changes"
 
 # Rules to keep documentation up-to-date
 
-- Rule 1: Whenever changes are made to the codebase, it's important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [Starlight content pages in docs/src/content/docs/](../../docs/src/content/docs/). Each page uses Starlight frontmatter (title, sidebar order). Cross-page links use relative paths (e.g., `../../guides/compilation/`).
+- Rule 1: Whenever changes are made to the codebase, it is important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [Starlight content pages in docs/src/content/docs/](../../docs/src/content/docs/). Each page uses Starlight frontmatter (title, sidebar order). Cross-page links use relative paths (e.g., `../../guides/compilation/`).
 
-- Rule 2: The main [README.md](../../README.md) file is a special case that requires user approval before changes, so, if there is a deviation in the code that affects what is stated in the main [README.md](../../README.md) file, you must warn the user and describe the drift and [README.md](../../README.md) update proposal, and wait for confirmation before updating it. 
+- Rule 2: The main [README.md](../../README.md) file is a special case that requires user approval before changes, so, if there is a deviation in the code that affects what is stated in the main [README.md](../../README.md) file, you must warn the user and describe the drift and [README.md](../../README.md) update proposal, and wait for confirmation before updating it.
 
-- Rule 3: Documentation is meant to be very simple and straightforward, we must avoid bloating it with unnecessary information. It must be pragmatic, to the point, succint and practical.To: "**"
+- Rule 3: Documentation is meant to be very simple and straightforward, we must avoid bloating it with unnecessary information. It must be pragmatic, to the point, succinct and practical.
+
+- Rule 4: When changing CLI commands, flags, dependency formats, authentication flow, policy schema, or primitive file formats, also update the corresponding resource files in [packages/apm-guide/.apm/skills/apm-usage/](../../packages/apm-guide/.apm/skills/apm-usage/). Map changes to the correct file: commands.md for CLI changes, dependencies.md for reference formats, authentication.md for token resolution, governance.md for policy schema, package-authoring.md for primitive formats.
@@ -0,0 +1,49 @@
+---
+name: apm-expert
+description: >
+  Expert on APM (Agent Package Manager). Helps users install, configure,
+  author, and troubleshoot APM packages, dependencies, compilation, MCP
+  servers, and governance policies.
+---
+
+# APM Expert
+
+You are an expert on APM (Agent Package Manager), the open-source package
+manager for AI coding agents by Microsoft. You help developers install, manage,
+and author packages that deliver instructions, prompts, agents, skills, and MCP
+server configurations to their projects.
+
+## When to use APM
+
+- Sharing reusable AI instructions, prompts, or agents across repos
+- Installing community or org-wide coding standards packages
+- Managing MCP server configurations declaratively
+- Enforcing governance policies on AI agent dependencies
+- Compiling agent context for targets like Codex or Gemini
+
+## When NOT to use APM
+
+- Managing traditional code libraries (use npm, pip, cargo, etc.)
+- Deploying production applications or services
+- Managing infrastructure or cloud resources
+- Version-controlling non-AI configuration files
+- Tasks unrelated to AI coding agent setup
+
+## Essential workflow (5 commands)
+
+```bash
+apm init                                # 1. initialize project
+apm install owner/package#v1.0.0        # 2. install dependencies
+apm compile                             # 3. compile agent context
+apm run <script>                        # 4. run a named script
+apm audit --ci                          # 5. validate in CI
+```
+
+**Always commit:** apm.yml, apm.lock.yaml, .apm/, .github/, .claude/, .cursor/
+**Never commit:** apm_modules/ (add to .gitignore)
+
+## Detailed reference
+
+For detailed reference on commands, authentication, dependencies, governance,
+and package authoring, see the
+[APM Usage Skill](../skills/apm-usage/SKILL.md).
@@ -0,0 +1,47 @@
+---
+name: apm-usage
+description: >
+  Activate when the user asks about APM (Agent Package Manager): installing,
+  configuring, authoring, or troubleshooting AI-agent packages, dependencies,
+  compilation, MCP servers, policy, or any `apm` CLI command.
+---
+
+# APM Usage
+
+APM (Agent Package Manager) is the open-source package manager for AI coding
+agents. It lets teams install, share, and govern reusable instructions, prompts,
+agents, skills, and MCP server configurations across projects.
+
+## When to activate
+
+- User mentions `apm` or "Agent Package Manager"
+- Questions about installing or managing AI-agent packages
+- Setting up instructions, prompts, agents, skills, or chatmodes
+- Configuring MCP servers through apm.yml
+- Authentication for private repos (GitHub, ADO, GHES, Artifactory)
+- Policy enforcement or `apm audit`
+- Package authoring or publishing
+- Compiling agent context (`apm compile`)
+- Troubleshooting apm errors
+
+## Key rules
+
+- **Commit these files:** apm.yml, apm.lock.yaml, .apm/, .github/, .claude/, .cursor/
+- **Never commit:** apm_modules/ (add to .gitignore)
+- **Team sync:** after `git clone`, run `apm install` to restore dependencies
+- **Update deps:** `apm install --update` refreshes to latest refs
+- **Pin versions:** use tags (`#v1.0.0`) in production, branches for development
+- **ASCII only:** all CLI output and source must stay within printable ASCII
+
+## Reference
+
+For detailed guidance, see the following resources:
+
+- [Installation](./installation.md) -- install and update APM
+- [Workflow](./workflow.md) -- core workflow, apm.yml format, what to commit
+- [Commands](./commands.md) -- full CLI command reference
+- [Dependencies](./dependencies.md) -- all dependency formats and version pinning
+- [Authentication](./authentication.md) -- token setup for private repos
+- [Governance](./governance.md) -- policy engine and audit checks
+- [Package Authoring](./package-authoring.md) -- creating APM packages
+- [Troubleshooting](./troubleshooting.md) -- common errors and fixes
@@ -0,0 +1,98 @@
+# Authentication
+
+## Token precedence chain
+
+APM checks these sources in order, using the first valid token found:
+
+| Priority | Variable | Scope | Notes |
+|----------|----------|-------|-------|
+| 1 | `GITHUB_APM_PAT_{ORG}` | Per-org | Org name uppercased, hyphens to underscores |
+| 2 | `GITHUB_APM_PAT` | Global | Falls back to git credential if rejected |
+| 3 | `GITHUB_TOKEN` | Global | Shared with GitHub Actions |
+| 4 | `GH_TOKEN` | Global | Set by `gh auth login` |
+| 5 | `git credential fill` | Per-host | System credential manager |
+| -- | None | -- | Unauthenticated (public GitHub repos only) |
+
+## Per-org setup
+
+Use per-org tokens when accessing packages across multiple organizations:
+
+```bash
+export GITHUB_APM_PAT_CONTOSO=ghp_token_for_contoso
+export GITHUB_APM_PAT_FABRIKAM=ghp_token_for_fabrikam
+```
+
+**Naming rules:**
+- Uppercase the org name
+- Replace hyphens with underscores
+- Example: `contoso-microsoft` -> `GITHUB_APM_PAT_CONTOSO_MICROSOFT`
+
+## Fine-grained PAT requirements
+
+Required permissions:
+- **Metadata:** Read
+- **Contents:** Read
+- **Repository access:** All repos or specific repos
+
+**Important:** The resource owner must be the **organization**, not your user
+account. User-scoped fine-grained PATs cannot access org repos even if you are
+a member.
+
+For SSO-protected orgs, authorize the token under Settings > Tokens > Configure SSO.
+
+## Azure DevOps (ADO)
+
+ADO uses a dedicated token variable -- the GitHub token chain does not apply:
+
+```bash
+export ADO_APM_PAT=your_ado_pat
+apm install dev.azure.com/org/project/_git/repo
+```
+
+ADO paths use the 3-segment format: `org/project/repo`. Auth is always required.
+
+## GitHub Enterprise Server (GHES)
+
+```bash
+export GITHUB_HOST=github.company.com
+export GITHUB_APM_PAT_MYORG=ghp_ghes_token
+apm install myorg/internal-package       # resolves to github.company.com
+```
+
+## GHE Cloud data residency (*.ghe.com)
+
+```bash
+export GITHUB_APM_PAT_MYENTERPRISE=ghp_enterprise_token
+apm install myenterprise.ghe.com/platform/standards
+```
+
+No public repos exist on `*.ghe.com` -- auth is always required.
+
+## Enterprise Managed Users (EMU)
+
+- EMU orgs live on `github.com` (e.g., `contoso-microsoft`) or `*.ghe.com`
+- Use standard PAT prefixes (`ghp_`, `github_pat_`)
+- Fine-grained PATs must use the EMU org as resource owner
+- EMU accounts cannot access public repos on github.com
+- If mixing enterprise and public repos, use separate tokens
+
+## Artifactory proxy (air-gapped environments)
+
+```bash
+export PROXY_REGISTRY_URL=https://artifactory.company.com/apm-remote
+export PROXY_REGISTRY_TOKEN=your_bearer_token
+export PROXY_REGISTRY_ONLY=1                   # optional: proxy-only mode
+```
+
+When `PROXY_REGISTRY_ONLY=1`, APM routes all traffic through the proxy and
+never contacts GitHub directly.
+
+## Troubleshooting
+
+```bash
+# Diagnose the auth chain -- shows which token source is used
+apm install --verbose your-org/package
+
+# Increase git credential timeout (default 30s, max 180s)
+export APM_GIT_CREDENTIAL_TIMEOUT=120
+```
@@ -0,0 +1,84 @@
+# CLI Command Reference
+
+## Project setup
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm init [NAME]` | Initialize a new APM project | `-y` skip prompts, `--plugin` authoring mode |
+
+## Dependency management
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm install [PKGS...]` | Install packages | `--update` refresh refs, `--force` overwrite, `--dry-run`, `--verbose`, `--only [apm\|mcp]`, `--target`, `--dev`, `-g` global, `--trust-transitive-mcp`, `--parallel-downloads N` |
+| `apm uninstall PKGS...` | Remove packages | `--dry-run`, `-g` global |
+| `apm prune` | Remove orphaned packages | `--dry-run` |
+| `apm deps list` | List installed packages | `-g` global, `--all` both scopes |
+| `apm deps tree` | Show dependency tree | -- |
+| `apm deps info PKG` | Show package details | -- |
+| `apm deps clean` | Clean dependency cache | `--dry-run`, `-y` skip confirm |
+| `apm deps update [PKGS...]` | Update specific packages | `--verbose`, `--force`, `--target`, `--parallel-downloads N` |
+
+## Compilation
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm compile` | Compile agent context | `-o` output, `-t` target, `--chatmode`, `--dry-run`, `--no-links`, `--watch`, `--validate`, `--single-agents`, `-v` verbose, `--local-only`, `--clean`, `--with-constitution/--no-constitution` |
+
+## Scripts
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm run SCRIPT` | Execute a named script | `-p name=value` (repeatable) |
+| `apm preview SCRIPT` | Preview script without running | `-p name=value` |
+| `apm list` | List available scripts | -- |
+
+## Security and audit
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm audit [PKG]` | Scan for security issues | `--file PATH`, `--strip`, `--dry-run`, `-v`, `-f [text\|json\|sarif\|md]`, `-o PATH`, `--ci`, `--policy SOURCE`, `--no-cache`, `--no-fail-fast` |
+
+## Distribution
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm pack` | Bundle package for distribution | `-o PATH`, `-t TARGET`, `--archive`, `--dry-run`, `--format [apm\|plugin]`, `--force` |
+| `apm unpack BUNDLE` | Extract a bundle | `-o PATH`, `--skip-verify`, `--force`, `--dry-run` |
+
+## Marketplace
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm marketplace add OWNER/REPO` | Register a marketplace | `-n NAME`, `-b BRANCH` |
+| `apm marketplace list` | List registered marketplaces | -- |
+| `apm marketplace browse NAME` | Browse marketplace packages | -- |
+| `apm marketplace update [NAME]` | Update marketplace index | -- |
+| `apm marketplace remove NAME` | Remove a marketplace | `-y` skip confirm |
+| `apm search QUERY@MARKETPLACE` | Search marketplace | `--limit N` |
+
+## MCP servers
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm mcp list` | List MCP servers in project | `--limit N` |
+| `apm mcp search QUERY` | Search MCP registry | `--limit N` |
+| `apm mcp show SERVER` | Show server details | -- |
+
+## Runtime management (experimental)
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm runtime setup {copilot\|codex\|llm}` | Install a runtime | `--version`, `--vanilla` |
+| `apm runtime list` | Show installed runtimes | -- |
+| `apm runtime remove {copilot\|codex\|llm}` | Remove a runtime | `--yes` |
+| `apm runtime status` | Show active runtime | -- |
+
+## Configuration and updates
+
+| Command | Purpose | Key flags |
+|---------|---------|-----------|
+| `apm config` | Show current configuration | -- |
+| `apm config get [KEY]` | Get a config value | -- |
+| `apm config set KEY VALUE` | Set a config value | -- |
+| `apm update` | Update APM itself | `--check` only check |