Add experimental Grok Cloud target support

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   preserved, and the targets matrix is updated to reflect the new `agents`
   primitive for `kiro`. Sources: https://kiro.dev/docs/custom-agents/ and
   https://kiro.dev/docs/cli/v3/ (accessed 2026-08-03). (#2089)
+- Stable Grok Build target support for native `.grok/` rules, agents, commands,
+  and skills, plus compiled `AGENTS.md` context.
 
 ### Fixed
 

README.md

@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf · Kiro
+GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304)**
 
@@ -67,7 +67,7 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
 - **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`

docs/src/content/docs/concepts/glossary.md

@@ -100,7 +100,8 @@ Source: `src/apm_cli/core/auth.py`.
 ### harness
 
 The agent runtime that executes primitives: GitHub Copilot (CLI + IDE),
-Claude Code, Cursor, Codex, Gemini, Antigravity, OpenCode, Windsurf, and Kiro. Each harness has
+Claude Code, Grok Build, Cursor, Codex, Gemini, Antigravity, OpenCode,
+Windsurf, and Kiro. Each harness has
 its own primitive directory layout and file format.
 
 NOT the same as a target. The target is the manifest or CLI selector for
@@ -251,8 +252,9 @@ Source: `src/apm_cli/models/apm_package.py`,
 ### target
 
 The `targets:` field in `apm.yml` (or legacy `target:`). Names which harnesses the package
-compiles for (`copilot`, `claude`, `cursor`, `codex`, `gemini`,
-`opencode`, `windsurf`, `kiro`, or `agent-skills`). `all` and `antigravity` are CLI `--target` values only. Drives which integrator runs and
+compiles for (`copilot`, `claude`, `grok-build`, `cursor`, `codex`, `gemini`,
+`antigravity`, `opencode`, `windsurf`, `kiro`, or
+`agent-skills`). `all` is a CLI `--target` value only. Drives which integrator runs and
 which directories receive output during `apm compile`.
 
 NOT the harness itself. Target is the declaration; the harness is the

docs/src/content/docs/concepts/lifecycle.md

@@ -30,7 +30,13 @@ Scaffolds a new APM project in the current directory.
 
 `apm init` writes an `apm.yml` manifest with sensible defaults for `name`, `author`, and `description`, plus empty dependency and script blocks. It records selected targets in `targets:`; author `.apm/` primitives yourself and run `apm install` or `apm compile` to create target output directories.
 
-Targets are picked in priority order. An explicit `--target copilot,claude` flag wins. Otherwise an interactive checklist runs. Otherwise APM scans the working tree for signal directories (`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.gemini/`, `.windsurf/`, `.kiro/`) and pre-checks every harness it finds. With `-y` and no flag, all detected harnesses are written into `apm.yml`. See [primitives and targets](/apm/concepts/primitives-and-targets/) for what each target actually receives.
+Targets are picked in priority order. An explicit `--target copilot,claude`
+flag wins. Otherwise an interactive checklist runs. Otherwise APM scans the
+working tree for recognized
+[filesystem signals](../../reference/cli/targets/#detection-signals) and
+pre-checks every harness it finds. With `-y` and no flag, all detected
+harnesses are written into `apm.yml`. See [primitives and
+targets](../primitives-and-targets/) for what each target receives.
 
 **Common surprises**
 
@@ -84,14 +90,19 @@ context files such as `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`. `apm run`
 still compiles any `.prompt.md` files referenced by a script immediately
 before execution.
 
-The `--target` flag accepts a comma-separated list (`copilot,claude,cursor,opencode,codex,gemini,windsurf,kiro,agent-skills`) or `all`. `--dry-run` prints placement decisions without writing files. `--validate` checks primitive frontmatter and structure without producing output. `--watch` re-runs compilation on every change.
+The `--target` flag accepts comma-separated catalog values; stable examples
+include `copilot`, `claude`, and `grok-build`. `--all` selects the default
+stable set. `--dry-run` prints placement decisions without writing files.
+`--validate` checks primitive frontmatter and structure without producing
+output. `--watch` re-runs compilation on every change.
 
 **Common surprises**
 
 - Running `apm compile` does not re-run the security scan. The scan happens at install time. If you hand-edit primitives between installs, run `apm audit` to scan them.
 - `--clean` removes orphaned `AGENTS.md` files from previous compilations. Without it, removed primitives can leave stale output behind.
 
-**Read more:** [`apm compile` reference](/apm/reference/cli/compile/), [compilation guide](/apm/producer/compile/).
+**Read more:** [`apm compile` reference](../../reference/cli/compile/),
+[compilation guide](../../producer/compile/).
 
 ## 4. RUN
 

docs/src/content/docs/concepts/primitives-and-targets.md

@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-A **primitive** is a unit of agent context APM can manage: instructions, prompts, agents, skills, hooks, commands, plugins, and MCP servers. A **target** is a harness APM compiles primitives for: Copilot, Claude, Cursor, Codex, Gemini, OpenCode, Windsurf, and Kiro, with Antigravity available as an explicit CLI-only target. The matrix below is the full reach map. For any primitive X and harness Y, it tells you whether Y receives X natively, receives it after APM transforms it, or does not receive it at all.
+A **primitive** is a unit of agent context APM can manage: instructions, prompts, agents, skills, hooks, commands, plugins, and MCP servers. A **target** is a harness APM compiles primitives for: Copilot, Claude, Grok Build, Cursor, Codex, Gemini, OpenCode, Windsurf, and Kiro, with Antigravity available as an explicit CLI-only target. The matrix below is the full reach map. For any primitive X and harness Y, it tells you whether Y receives X natively, receives it after APM transforms it, or does not receive it at all.
 
 This page is the canonical reference. Tutorials and how-tos link here; do not duplicate.
 
@@ -78,12 +78,13 @@ GitHub Copilot CLI canvas extensions: a directory bundle whose entry file is `ex
 
 ## Target catalogue
 
-Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`claude`, `copilot`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `kiro`, `agent-skills`); `antigravity` is `--target`-only and explicit-only. The output directory is where APM writes deployed primitives.
+Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`); `antigravity` remains explicit-only. The output directory is where APM writes deployed primitives.
 
 | Slug | Output directory | Compile family |
 |---|---|---|
 | `copilot` | `.github/` (project), `~/.copilot/` (user scope) | vscode |
 | `claude` | `.claude/` | claude |
+| `grok-build` | `.grok/` | agents |
 | `cursor` | `.cursor/` | agents |
 | `codex` | `.codex/` plus `.agents/` for skills | agents |
 | `gemini` | `.gemini/` | gemini |
@@ -96,6 +97,7 @@ Notes per target:
 
 - **copilot** -- GitHub Copilot (CLI + IDE). User-scope partial: prompts and instructions are project-scope only.
 - **claude** -- Claude Code. Full user-scope support. Hooks merge into `.claude/settings.json` rather than living as separate files.
+- **grok-build** -- Grok Build. Rules, agents, commands, and skills use `.grok/`; compiled instructions also produce `AGENTS.md`.
 - **cursor** -- Cursor IDE. Rules use the `.mdc` extension. Instructions are not deployable at user scope (Cursor exposes them via the Settings UI only).
 - **codex** -- Codex CLI. Agents and hooks use TOML; skills use the cross-tool `.agents/` directory.
 - **gemini** -- Gemini CLI. Commands are TOML. Hooks merge into `.gemini/settings.json`. No native agents or instructions primitives -- both arrive via compiled context files.
@@ -113,17 +115,17 @@ Rows are primitives, columns are harnesses. Cell legend:
 - **unsupported** -- APM does not deliver this primitive to this harness.
 - **gated** -- delivered behind an explicit declaration or trust flag.
 
-| Primitive | Copilot | Claude | Cursor | Codex | Gemini | Antigravity | OpenCode | Windsurf | Kiro |
-|---|---|---|---|---|---|---|---|---|---|
-| instructions | native | native | native | compiled | compiled | native | compiled | native | native |
-| prompts | native | compiled | compiled | unsupported | compiled | compiled | compiled | compiled | unsupported |
-| agents | native | native | compiled | compiled | unsupported | unsupported | native | unsupported | compiled |
-| skills | native | native | native | native | native | native | native | native | native |
-| hooks | native | native | native | native | native | native | unsupported | native | native |
-| commands | unsupported | native | compiled | unsupported | compiled | unsupported | compiled | compiled | unsupported |
-| plugins | compiled | compiled | compiled | compiled | compiled | compiled | compiled | compiled | compiled |
-| MCP servers | native | native | native | native | native | native | native | native | native |
-| canvas (experimental) | gated | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported |
+| Primitive | Copilot | Claude | Grok Build | Cursor | Codex | Gemini | Antigravity | OpenCode | Windsurf | Kiro |
+|---|---|---|---|---|---|---|---|---|---|---|
+| instructions | native | native | native | native | compiled | compiled | native | compiled | native | native |
+| prompts | native | compiled | compiled | compiled | unsupported | compiled | compiled | compiled | compiled | unsupported |
+| agents | native | native | native | compiled | compiled | unsupported | unsupported | native | unsupported | compiled |
+| skills | native | native | native | native | native | native | native | native | native | native |
+| hooks | native | native | unsupported | native | native | native | native | unsupported | native | native |
+| commands | unsupported | native | compiled | compiled | unsupported | compiled | unsupported | compiled | compiled | unsupported |
+| plugins | compiled | compiled | compiled | compiled | compiled | compiled | compiled | compiled | compiled | compiled |
+| MCP servers | native | native | unsupported | native | native | native | native | native | native | native |
+| canvas (experimental) | gated | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported | unsupported |
 
 How to read a cell:
 
@@ -171,14 +173,19 @@ Full pattern, the three pack-time gotchas, and verification steps: [Dev-only pri
 
 ## How a target is selected
 
-`apm install` and `apm compile` resolve active targets in this order:
+`apm install` and `apm compile` use the same first three target sources:
 
 1. Explicit `--target <slug>` flag, when passed.
 2. The `targets:` field in `apm.yml`, when present.
-3. Auto-detection: any harness whose root directory (`.github/`, `.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.windsurf/`, `.kiro/`) already exists in the workspace is selected.
-4. Fallback: `copilot` -- greenfield projects get the default Copilot skills root. Create one of the harness folders above (or set
-   `targets:` explicitly) for full integration.
+3. Auto-detection: recognized
+   [filesystem signals](../../reference/cli/targets/#detection-signals) select
+   the matching harness.
+With no signal, `apm install` exits with a target-selection error. `apm compile`
+retains its legacy `vscode`/minimal fallback.
 
 Unknown target slugs are rejected upstream by the manifest parser; they never silently fall through to the default.
 
-For flag reference and exact resolution semantics, see [`apm compile` and `apm install`](/apm/reference/cli/install/). For policy controls that further restrict which primitives a target may deploy, see [Governance guide](/apm/enterprise/governance-guide/).
+For exact resolution semantics, see [`apm install`](../../reference/cli/install/)
+and [`apm compile`](../../reference/cli/compile/). For policy controls that
+further restrict which primitives a target may deploy, see [Governance
+guide](../../enterprise/governance-guide/).

docs/src/content/docs/concepts/the-three-promises.md

@@ -11,11 +11,11 @@ these three.
 
 ## Promise 1: Portable by manifest
 
-One `apm.yml`. Eight default harnesses. Reproducible AI agent setup.
+One `apm.yml`. Nine default harnesses. Reproducible AI agent setup.
 
 Every developer who clones the repo runs `apm install` and gets the
-same skills, prompts, instructions, hooks, and MCP servers wired into
-Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro. The
+same supported primitives wired into Copilot, Claude, Grok Build, Cursor,
+OpenCode, Codex, Gemini, Windsurf, and Kiro. The
 lockfile pins exact versions and content hashes. New contributor
 onboarding for AI context goes from "follow this 12-step README" to
 one command.
@@ -32,8 +32,9 @@ git clone <repo> && cd <repo> && apm install
   manifest with `dependencies`, `devDependencies`, `scripts`, `includes`,
   and `targets` / `target` fields consumed by every harness.
 - `src/apm_cli/integration/targets.py` -- the registered harnesses an
-  install fans out to by default (Copilot, Claude, Cursor, Codex, Gemini,
-  OpenCode, Windsurf, and Kiro); Antigravity is registered as an explicit-only target.
+  install fans out to by default (Copilot, Claude, Grok Build, Cursor, Codex,
+  Gemini, OpenCode, Windsurf, and Kiro); Antigravity is registered as
+  an explicit-only target.
 - `src/apm_cli/deps/lockfile.py` -- the `LockEntry.content_hash`
   field (SHA-256 of the package file tree) that makes "same install
   on every clone" mean byte-for-byte the same.
@@ -128,7 +129,7 @@ apm install --dry-run <package>
 The verbs rhyme on purpose -- `apm install`, `apm update`,
 `apm list`, `apm prune`. The package model does not. APM resolves
 primitives (skills, prompts, instructions, hooks, MCP servers) and
-deploys them into eight default agent harnesses from one manifest.
+deploys them into nine default agent harnesses from one manifest.
 npm has no equivalent of the harness fan-out, the install-time
 policy gate, or the Unicode scan. Promise 1 is the npm-shaped half;
 Promise 2 and Promise 3 are not.

docs/src/content/docs/concepts/what-is-apm.md

@@ -15,7 +15,7 @@ APM borrows the manifest-plus-lockfile shape from `npm`, `pip`, and `cargo` and
 
 `apm.yml` is the manifest. It lists agentic dependencies (skills, prompts, agents, plugins, full APM packages) and MCP servers. `apm.lock.yaml` is the lockfile. It pins every resolved package to an exact source ref and content hash, so two developers running `apm install` against the same lockfile get byte-identical context. Source authoring lives in `.apm/` inside your repo.
 
-The compiled output lives in the directories each harness already reads: `.github/` for Copilot, `.claude/` for Claude Code, `.cursor/` for Cursor, `.codex/` and `AGENTS.md` for Codex, `.gemini/` for Gemini, `.agents/` for Antigravity, `.opencode/` for OpenCode, `.windsurf/` for Windsurf, and `.kiro/` for Kiro. APM does not invent a runtime format. It writes the files each tool already understands and stays out of the way at agent runtime.
+The compiled output lives in the directories each harness already reads: `.github/` for Copilot, `.claude/` for Claude Code, `.grok/` and `AGENTS.md` for Grok Build, `.cursor/` for Cursor, `.codex/` and `AGENTS.md` for Codex, `.gemini/` for Gemini, `.agents/` for Antigravity, `.opencode/` for OpenCode, `.windsurf/` for Windsurf, and `.kiro/` for Kiro. APM does not invent a runtime format. It writes the files each tool already understands and stays out of the way at agent runtime.
 
 ## What APM manages
 
@@ -47,7 +47,7 @@ APM commits to three things. Each gets a one-paragraph summary here; the deep di
 
 ### Portable by manifest
 
-One `apm.yml`. Eight default harnesses. Reproducible AI agent setup. Every developer who clones the repo runs `apm install` and gets the same skills, prompts, instructions, hooks, and MCP servers wired into Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro. Antigravity is available as an explicit CLI target. The lockfile pins exact versions and content hashes.
+One `apm.yml`. Nine default harnesses. Reproducible AI agent setup. Every developer who clones the repo runs `apm install` and gets the same supported primitives wired into Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro. Antigravity is available as an explicit CLI target. The lockfile pins exact versions and content hashes.
 
 ### Secure by default
 

docs/src/content/docs/consumer/governance-on-the-consumer-ramp.md

@@ -48,8 +48,8 @@ your platform team can set, and what each one does to your install:
 - **`mcp.trust_transitive`** -- whether MCP servers shipped by deep
   dependencies are trusted automatically.
 - **`compilation.target.allow`** -- which harness targets your repo can
-  compile to (`claude`, `copilot`, `cursor`, `opencode`, `codex`,
-  `gemini`, `windsurf`, `kiro`, `agent-skills`).
+  compile to (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`,
+  `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`).
 - **`compilation.strategy.enforce`** -- `distributed` or `single-file`.
 - **`manifest.required_fields`** / **`manifest.scripts`** /
   **`manifest.require_explicit_includes`** -- shape constraints on