diff --git a/.github/instructions/doc-sync.instructions.md b/.github/instructions/doc-sync.instructions.md
index 1d79c67f..fa6aae81 100644
--- a/.github/instructions/doc-sync.instructions.md
+++ b/.github/instructions/doc-sync.instructions.md
@@ -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: "**"
\ No newline at end of file
+- 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.
diff --git a/packages/apm-guide/.apm/agents/apm-expert.agent.md b/packages/apm-guide/.apm/agents/apm-expert.agent.md
new file mode 100644
index 00000000..3ee2d835
--- /dev/null
+++ b/packages/apm-guide/.apm/agents/apm-expert.agent.md
@@ -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).
diff --git a/packages/apm-guide/.apm/skills/apm-usage/SKILL.md b/packages/apm-guide/.apm/skills/apm-usage/SKILL.md
new file mode 100644
index 00000000..59bccfb6
--- /dev/null
+++ b/packages/apm-guide/.apm/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
diff --git a/packages/apm-guide/.apm/skills/apm-usage/authentication.md b/packages/apm-guide/.apm/skills/apm-usage/authentication.md
new file mode 100644
index 00000000..b5205e98
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/authentication.md
@@ -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
+```
diff --git a/packages/apm-guide/.apm/skills/apm-usage/commands.md b/packages/apm-guide/.apm/skills/apm-usage/commands.md
new file mode 100644
index 00000000..c5a271d6
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/commands.md
@@ -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 |
diff --git a/packages/apm-guide/.apm/skills/apm-usage/dependencies.md b/packages/apm-guide/.apm/skills/apm-usage/dependencies.md
new file mode 100644
index 00000000..99abf2a8
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/dependencies.md
@@ -0,0 +1,123 @@
+# Dependency Reference
+
+## String forms (in apm.yml `dependencies.apm`)
+
+```yaml
+dependencies:
+  apm:
+    # GitHub shorthand
+    - microsoft/apm-sample-package
+    - microsoft/apm-sample-package#v1.0.0       # pinned tag
+    - microsoft/apm-sample-package#main          # branch
+    - microsoft/apm-sample-package#abc123d       # commit SHA (7-40 hex)
+
+    # HTTPS URLs (any git host)
+    - https://github.com/microsoft/apm-sample-package.git
+    - https://gitlab.com/acme/coding-standards.git
+
+    # SSH URLs
+    - git@github.com:microsoft/apm-sample-package.git
+    - git@gitlab.com:group/subgroup/repo.git
+
+    # FQDN shorthand (non-GitHub hosts keep the domain)
+    - gitlab.com/acme/coding-standards
+    - gitlab.com/group/subgroup/repo
+
+    # Azure DevOps
+    - dev.azure.com/org/project/_git/repo
+
+    # Local paths (development only)
+    - ./packages/my-shared-skills
+    - ../sibling-repo/my-package
+```
+
+## Object form (complex cases)
+
+```yaml
+- git: https://gitlab.com/acme/repo.git
+  path: instructions/security                   # virtual sub-path
+  ref: v2.0                                     # tag, branch, or SHA
+  alias: acme-sec                               # local alias
+
+- git: git@gitlab.com:group/subgroup/repo.git
+  path: prompts/review.prompt.md
+
+- path: ./packages/my-skills                    # local only
+```
+
+## Virtual package types
+
+Virtual packages reference a subset of a repository.
+
+| Type | Detection rule | Example |
+|------|---------------|---------|
+| File | Ends in `.prompt.md`, `.instructions.md`, `.agent.md`, `.chatmode.md` | `owner/repo/prompts/review.prompt.md` |
+| Collection (dir) | Contains `/collections/` (no extension) | `owner/repo/collections/security` |
+| Collection (manifest) | Contains `/collections/` + `.collection.yml` | `owner/repo/collections/security.collection.yml` |
+| Subdirectory | Does not match file or collection rules | `owner/repo/skills/security` |
+
+## Canonical storage rules
+
+APM normalizes dependency strings when saving to apm.yml:
+
+| Input | Stored as |
+|-------|-----------|
+| `microsoft/apm-sample-package` | `microsoft/apm-sample-package` |
+| `https://github.com/microsoft/apm-sample-package.git` | `microsoft/apm-sample-package` |
+| `git@github.com:microsoft/apm-sample-package.git` | `microsoft/apm-sample-package` |
+| `https://gitlab.com/acme/rules.git` | `gitlab.com/acme/rules` |
+| Object with `git` + `path: docs` + `ref: main` | `org/repo/docs#main` |
+| `./packages/my-skills` | `./packages/my-skills` |
+
+GitHub URLs are stripped to shorthand; non-GitHub hosts keep the FQDN.
+
+## MCP dependency formats
+
+```yaml
+dependencies:
+  mcp:
+    # Registry reference (string)
+    - io.github.github/github-mcp-server
+
+    # Registry with overlays (object)
+    - name: io.github.github/github-mcp-server
+      transport: stdio                          # stdio|sse|http|streamable-http
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      args: ["--port", "3000"]
+      version: "1.5.0"
+      package: npm                              # npm|pypi|oci
+      headers:
+        X-Custom: "value"
+      tools: ["repos", "issues"]
+
+    # Self-defined server (not in registry)
+    - name: my-private-server
+      registry: false
+      transport: stdio
+      command: ./bin/my-server
+      args: ["--port", "3000"]
+      env:
+        API_KEY: ${{ secrets.KEY }}
+
+    # Self-defined HTTP server
+    - name: internal-kb
+      registry: false
+      transport: http
+      url: "https://mcp.internal.example.com"
+```
+
+## Version pinning
+
+| Strategy | Syntax | When to use |
+|----------|--------|-------------|
+| Tag | `owner/repo#v1.0.0` | Production -- immutable reference |
+| Branch | `owner/repo#main` | Development -- tracks latest |
+| Commit SHA | `owner/repo#abc123d` | Maximum reproducibility |
+| No ref | `owner/repo` | Resolves default branch at install time |
+
+## What the lockfile pins
+
+`apm.lock.yaml` records the exact commit SHA for every dependency, regardless
+of the ref format in apm.yml. Running `apm install` without `--update` always
+uses the locked SHA, ensuring reproducible installs across machines.
diff --git a/packages/apm-guide/.apm/skills/apm-usage/governance.md b/packages/apm-guide/.apm/skills/apm-usage/governance.md
new file mode 100644
index 00000000..fadf0e13
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/governance.md
@@ -0,0 +1,121 @@
+# Governance and Policy
+
+**Note:** The policy engine is experimental (early preview). Schema fields and
+defaults may change between releases. Pin your APM version and monitor the
+CHANGELOG when using policy features.
+
+## Policy file location
+
+- **Org-level:** hosted in a repo, fetched via `--policy org` or `--policy URL`
+- **Repo-level:** `apm-policy.yml` in the repository root
+- **Local override:** `--policy ./path/to/apm-policy.yml`
+
+## Policy schema overview
+
+```yaml
+name: "Contoso Engineering Policy"
+version: "1.0.0"
+extends: org                             # inherit from parent policy
+enforcement: block                       # off | warn | block
+
+cache:
+  ttl: 3600                             # policy cache in seconds
+
+dependencies:
+  allow: []                             # allowed patterns
+  deny: []                              # denied patterns (takes precedence)
+  require: []                           # required packages
+  require_resolution: project-wins      # project-wins | policy-wins | block
+  max_depth: 50                         # transitive depth limit
+
+mcp:
+  allow: []                             # allowed server patterns
+  deny: []                              # denied patterns
+  transport:
+    allow: []                           # stdio | sse | http | streamable-http
+  self_defined: warn                    # deny | warn | allow
+  trust_transitive: false               # trust MCP from transitive deps
+
+compilation:
+  target:
+    allow: [vscode, claude]             # permitted targets
+    enforce: null                       # force specific target
+  strategy:
+    enforce: null                       # distributed | single-file
+  source_attribution: false             # require attribution
+
+manifest:
+  required_fields: []                   # fields that must exist in apm.yml
+  scripts: allow                        # allow | deny
+  content_types:
+    allow: []                           # instructions | skill | hybrid | prompts
+
+unmanaged_files:
+  action: ignore                        # ignore | warn | deny
+  directories: []                       # directories to scan
+```
+
+## Enforcement modes
+
+| Value | Behavior |
+|-------|----------|
+| `off` | Checks skipped entirely |
+| `warn` | Violations reported but do not fail |
+| `block` | Violations cause `apm audit --ci` to exit 1 |
+
+## Inheritance rules (tighten-only)
+
+Child policies can only tighten parent policies, never relax them:
+
+| Field | Merge rule |
+|-------|-----------|
+| `enforcement` | Escalates: `off` < `warn` < `block` |
+| Allow lists | Intersection (child narrows parent) |
+| Deny lists | Union (child adds to parent) |
+| `require` | Union (combines required packages) |
+| `max_depth` | `min(parent, child)` |
+| `mcp.self_defined` | Escalates: `allow` < `warn` < `deny` |
+| `source_attribution` | `parent OR child` (either enables) |
+
+Chain limit: 5 levels max. Cycles are detected and rejected.
+
+## Pattern matching syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `contoso/*` | `contoso/repo` (single segment only) |
+| `contoso/**` | `contoso/repo`, `contoso/org/repo`, any depth |
+| `*/approved` | `any-org/approved` |
+| `exact/match` | Only `exact/match` |
+
+Deny is evaluated first. Empty allow list permits all (except denied).
+
+## Baseline checks (always run with --ci)
+
+These checks run without a policy file:
+
+- `lockfile-exists` -- apm.lock.yaml present
+- `ref-consistency` -- dependency refs match lockfile
+- `deployed-files-present` -- all deployed files exist
+- `no-orphaned-packages` -- no packages in lockfile absent from manifest
+- `config-consistency` -- MCP configs match lockfile
+- `content-integrity` -- no critical Unicode in deployed files
+
+## Policy checks (with --policy)
+
+Additional checks when a policy is provided:
+
+- **Dependencies:** allowlist, denylist, required packages, transitive depth
+- **MCP:** allowlist, denylist, transport, self-defined servers
+- **Compilation:** target, strategy, source attribution
+- **Manifest:** required fields, scripts policy
+- **Unmanaged:** unmanaged file detection
+
+## CLI usage
+
+```bash
+apm audit --ci                              # baseline checks only
+apm audit --ci --policy org                 # auto-discover org policy
+apm audit --ci --policy ./apm-policy.yml    # local policy file
+apm audit --ci --policy https://...         # remote policy URL
+```
diff --git a/packages/apm-guide/.apm/skills/apm-usage/installation.md b/packages/apm-guide/.apm/skills/apm-usage/installation.md
new file mode 100644
index 00000000..dbc44a64
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/installation.md
@@ -0,0 +1,43 @@
+# Installation
+
+## Quick install (recommended)
+
+```bash
+# macOS / Linux
+curl -sSL https://aka.ms/apm-unix | sh
+
+# Windows (PowerShell)
+irm https://aka.ms/apm-windows | iex
+```
+
+## Package managers
+
+```bash
+# Homebrew (macOS / Linux)
+brew install microsoft/apm/apm
+
+# Scoop (Windows)
+scoop bucket add apm https://github.com/microsoft/scoop-apm
+scoop install apm
+
+# pip (all platforms, requires Python 3.10+)
+pip install apm-cli
+```
+
+## Verify
+
+```bash
+apm --version
+```
+
+## Update
+
+```bash
+apm update          # update APM itself
+apm update --check  # check for updates without installing
+```
+
+## Troubleshooting
+
+- **macOS/Linux "command not found":** ensure `/usr/local/bin` is in `$PATH`.
+- **Windows antivirus locks:** set `$env:APM_DEBUG = "1"` and retry.
diff --git a/packages/apm-guide/.apm/skills/apm-usage/package-authoring.md b/packages/apm-guide/.apm/skills/apm-usage/package-authoring.md
new file mode 100644
index 00000000..546d643d
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/package-authoring.md
@@ -0,0 +1,152 @@
+# Package Authoring
+
+## Package directory structure
+
+```
+my-package/
+  apm.yml                              # package manifest (required)
+  .apm/                                # local primitives directory
+    instructions/
+      security.instructions.md
+      python.instructions.md
+    chatmodes/
+      architect.chatmode.md
+    contexts/
+      codebase.context.md
+    prompts/
+      code-review.prompt.md
+    agents/
+      reviewer.agent.md
+    skills/
+      my-skill/
+        SKILL.md
+        resource1.md
+        resource2.md
+```
+
+## The 7 primitive types
+
+### 1. Instruction (`*.instructions.md`)
+
+Contextual guidance scoped to file patterns.
+
+```yaml
+---
+description: "Security best practices for Python"
+applyTo: "**/*.py"
+tags: [security, validation]
+---
+```
+
+### 2. Chatmode (`*.chatmode.md`)
+
+Chat persona configuration.
+
+```yaml
+---
+name: "architect"
+description: "System architecture expert"
+system_prompt: "You are an expert..."
+temperature: 0.7
+---
+```
+
+### 3. Context (`*.context.md`)
+
+Domain knowledge and background information.
+
+```yaml
+---
+description: "Company coding standards"
+applyTo: "**/*"
+---
+```
+
+### 4. Prompt / Agent Workflow (`*.prompt.md`)
+
+Executable workflows with parameters.
+
+```yaml
+---
+description: "Code review workflow"
+model: "gpt-4"
+parameters:
+  - name: pr_url
+    description: "GitHub PR URL"
+    required: true
+---
+```
+
+### 5. Agent (`*.agent.md`)
+
+Agent persona and behavior definition.
+
+```yaml
+---
+name: "code-reviewer"
+description: "Reviews code for quality"
+instructions: |
+  Focus on:
+  - Security
+  - Performance
+---
+```
+
+### 6. Skill (folder-based, `SKILL.md`)
+
+Reusable capability with supporting resources.
+
+```
+my-skill/
+  SKILL.md                             # skill metadata and entry point
+  resource1.md                         # supporting documentation
+  resource2.md
+```
+
+### 7. Marketplace Plugin (`plugin.json`)
+
+Packaged distribution format created with `apm pack --format plugin`.
+
+## Step-by-step: create and publish
+
+```bash
+# 1. Initialize a package project
+apm init my-package --plugin
+
+# 2. Add primitives to .apm/ subdirectories
+#    (instructions, agents, prompts, skills, etc.)
+
+# 3. Test locally
+apm install ./my-package               # install from local path
+apm compile --verbose                  # verify compilation output
+
+# 4. Validate
+apm audit                              # check for security issues
+apm audit --ci                         # run baseline CI checks
+
+# 5. Publish
+#    Push to a Git repository (GitHub, GitLab, ADO)
+git init && git add . && git commit -m "Initial package"
+git remote add origin git@github.com:org/my-package.git
+git push -u origin main
+git tag v1.0.0 && git push --tags
+
+# 6. Consumers install via
+apm install org/my-package#v1.0.0
+```
+
+## Org-wide packages
+
+For organization-wide standards, create a single repository with shared
+primitives and have all team repos depend on it:
+
+```yaml
+# In each team repo's apm.yml
+dependencies:
+  apm:
+    - contoso/engineering-standards#v2.0.0
+```
+
+This ensures consistent instructions, agents, and policies across the org.
+Local `.apm/` primitives in each repo can extend or override the shared ones
+(local always takes priority over dependencies).
diff --git a/packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md b/packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md
new file mode 100644
index 00000000..2411cfce
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md
@@ -0,0 +1,14 @@
+# Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `apm: command not found` | Install APM: `curl -sSL https://aka.ms/apm-unix \| sh` (macOS/Linux) or `irm https://aka.ms/apm-windows \| iex` (Windows). Ensure `/usr/local/bin` is in `$PATH`. |
+| Authentication errors (401/403) | Set the correct token. Run `apm install --verbose` to see which token source is used. See [Authentication](./authentication.md). |
+| File collision on install | A local file conflicts with a dependency file. Use `--force` to overwrite, or rename the local file. |
+| Stale dependencies | Run `apm install --update` to refresh to latest refs. |
+| Orphaned packages in lockfile | Run `apm prune` to remove packages no longer in apm.yml. |
+| Security findings block install | Run `apm audit` to review findings, then `apm install --force` if acceptable. |
+| Compilation not picking up changes | Run `apm compile --clean` to remove orphaned output, or `apm compile --watch` for auto-regeneration. |
+| Windows encoding / charmap errors | Ensure all source files and CLI output use printable ASCII only (U+0020-U+007E). No emojis or unicode symbols. |
+| Fine-grained PAT cannot access org | The PAT resource owner must be the org, not your user account. Recreate with org as owner. |
+| SSO-protected repo access denied | Authorize the token: Settings > Tokens > Configure SSO for the org. |
diff --git a/packages/apm-guide/.apm/skills/apm-usage/workflow.md b/packages/apm-guide/.apm/skills/apm-usage/workflow.md
new file mode 100644
index 00000000..83450a22
--- /dev/null
+++ b/packages/apm-guide/.apm/skills/apm-usage/workflow.md
@@ -0,0 +1,89 @@
+# Core Workflow
+
+## 5-step workflow
+
+```bash
+# 1. Install APM (one-time)
+curl -sSL https://aka.ms/apm-unix | sh        # or irm on Windows
+
+# 2. Initialize project
+apm init my-project && cd my-project           # new project
+cd existing-repo && apm init                   # existing repo
+
+# 3. Install packages
+apm install microsoft/apm-sample-package#v1.0.0
+
+# 4. Compile (needed for Codex, Gemini, single-file targets)
+apm compile
+
+# 5. Commit and share
+git add apm.yml apm.lock.yaml .apm/ .github/ .claude/ .cursor/
+git commit -m "Add APM dependencies"
+```
+
+## apm.yml schema overview
+
+```yaml
+name:          <string>                    # REQUIRED -- package identifier
+version:       <string>                    # REQUIRED -- semver (e.g. 1.0.0)
+description:   <string>                    # optional
+author:        <string>                    # optional
+license:       <string>                    # optional -- SPDX (e.g. MIT)
+target:        <enum>                      # optional -- vscode|claude|codex|opencode|all
+type:          <enum>                      # optional -- instructions|skill|hybrid|prompts
+scripts:       <map<string, string>>       # optional -- named commands
+dependencies:
+  apm:         <list<ApmDependency>>       # optional
+  mcp:         <list<McpDependency>>       # optional
+devDependencies:                           # optional -- excluded from bundles
+  apm:         <list<ApmDependency>>
+  mcp:         <list<McpDependency>>
+compilation:                               # optional
+  target:      <enum>                      # vscode|claude|codex|opencode|all
+  strategy:    <enum>                      # distributed|single-file
+  output:      <string>                    # custom output path
+  chatmode:    <string>                    # chatmode to prepend
+  resolve_links: <bool>                    # resolve markdown links (default true)
+  source_attribution: <bool>              # include source comments
+```
+
+### Type behavior
+
+| Value | Behavior |
+|-------|----------|
+| `instructions` | Compiled into AGENTS.md only; no skill directory |
+| `skill` | Installed as skill only; no AGENTS.md |
+| `hybrid` | Both AGENTS.md + skill installation |
+| `prompts` | Commands/prompts only; no instructions/skills |
+
+### Target auto-detection
+
+| Condition | Detected target |
+|-----------|-----------------|
+| `.github/` exists only | `vscode` |
+| `.claude/` exists only | `claude` |
+| `.codex/` exists | `codex` |
+| Both `.github/` and `.claude/` | `all` |
+| Neither exists | `minimal` (AGENTS.md only) |
+
+## What to commit
+
+| Path | Commit? | Why |
+|------|---------|-----|
+| `apm.yml` | Yes | Manifest -- declares dependencies |
+| `apm.lock.yaml` | Yes | Lockfile -- pins exact commits for reproducibility |
+| `.apm/` | Yes | Local primitives (instructions, agents, etc.) |
+| `.github/`, `.claude/`, `.cursor/` | Yes | Deployed files for agent runtimes |
+| `apm_modules/` | **No** | Downloaded sources -- add to `.gitignore` |
+
+## Team member setup
+
+```bash
+git clone <repo-url>
+cd <repo>
+apm install            # restores all deps from lockfile
+```
+
+The lockfile ensures every team member gets the exact same dependency versions.
+Subsequent `apm install` reads locked commit SHAs for reproducible installs.
+Use `apm install --update` to refresh to latest refs.
diff --git a/packages/apm-guide/apm.yml b/packages/apm-guide/apm.yml
new file mode 100644
index 00000000..3905d0bc
--- /dev/null
+++ b/packages/apm-guide/apm.yml
@@ -0,0 +1,6 @@
+name: apm-guide
+version: 1.0.0
+description: Teach AI agents how to use APM (Agent Package Manager)
+author: Microsoft
+license: MIT
+type: skill