planr 1.7.2 → 1.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![Planr — turn chaotic agent work into a verified task graph](public/planr_banner1.webp)
 
-Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
+Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, Grok Build, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
 
 [**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
 
@@ -44,7 +44,16 @@ Or with the release installer:
 curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
 ```
 
-Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin:
+<!-- planr:linux-release-portability:start surface=README schema=1 -->
+> **Linux release portability — corrected**
+>
+> Contract state: `status=corrected`; `affectedThrough=v1.7.2`; `correctedFrom=v1.7.3`.
+> Published Linux release, installer, and npm binaries through v1.7.2 require GLIBC_2.39; macOS is unaffected.
+> Starting with v1.7.3, current Linux release, installer, and npm artifacts are static-musl executables and do not require glibc.
+> On an affected Linux release, build from source on the target distribution or upgrade to v1.7.3.
+<!-- planr:linux-release-portability:end surface=README schema=1 -->
+
+Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin. Grok Build is a separate explicit opt-in and is not included by `all`:
 
 ```bash
 planr project init "My Product" --client all
@@ -97,6 +106,23 @@ The dry-run also prints a one-click `cursor://` deeplink for user-level MCP inst
 
 </details>
 
+<a id="install-grok-build"></a>
+<details>
+<summary><strong>Grok Build</strong></summary>
+
+Preview, install, and inspect the repository-local integration:
+
+```bash
+planr install grok --dry-run
+planr install grok
+planr doctor --client grok --json
+grok inspect --json
+```
+
+Planr writes portable `.grok/config.toml` MCP configuration plus native `.grok/agents/` and `.grok/skills/` assets. It writes no Grok plugin, hooks, xAI credentials, model setting, or provider runtime dependency. Live authenticated verification is maintainer-local only and never runs in CI. See the [Grok Build guide](https://planr.so/docs/integrations/grok-build).
+
+</details>
+
 <a id="install-plugin-opencode"></a>
 <details>
 <summary><strong>opencode</strong></summary>
@@ -174,6 +200,7 @@ The watcher is likewise a human-only observer. It defaults to the condensed diag
 
 ## What's new
 
+- **1.8.0 — First-class Grok Build integration:** Added an explicit repository opt-in that installs portable project MCP configuration plus native Grok agents and all ten Planr workflow skills. The integration writes no plugin, hooks, model setting, xAI credentials, or provider runtime dependency; authenticated verification remains maintainer-local and never runs in CI. See the [Grok Build guide](https://planr.so/docs/integrations/grok-build) and [1.8.0 changelog](CHANGELOG.md#180---2026-07-27).
 - **1.7.2 — Reproducible release candidates:** Locked the pnpm workspace inventory, made external eval fixtures self-contained, refreshed reviewed workflow runtimes, and made all four published architectures execute the exact tagged version before upload. Model-backed evaluation remains a local, candidate-bound maintainer gate; this patch makes no unmeasured speed or quality claim. See the [1.7.2 changelog](CHANGELOG.md#172---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
 - **1.7.1 — Leaner agent guidance and safer local releases:** Slimmed the hot-path Planr skills while preserving their execution and review contracts, moved maintainer benchmark inputs and results outside the public repository, added a fail-closed local release-evidence gate without API keys in CI, and verified the optional external Switchloom v0.3.2 integration. The public 1.7 eval CLI remains available in this patch. See the [1.7.1 changelog](CHANGELOG.md#171---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
 - **1.7.0 — Evidence-backed evaluations:** Added durable eval suites, runs, comparisons, invalidation and rescoring, correctness/quality/performance gates, cost per verified success, and effort recommendations. The complete workflow is available through the CLI; MCP only mirrors selected surfaces and is optional. Security gates now cover repository leaks, vulnerable dependencies, workflow hardening, privacy, and forbidden staged files. See the [Eval Contract](docs/contracts/EVAL_CONTRACT_V1.md), [CLI Reference](https://planr.so/docs/reference/cli), and the [1.7.0 changelog](CHANGELOG.md#170---2026-07-22).
@@ -193,7 +220,7 @@ Full documentation lives at [planr.so/docs](https://planr.so/docs).
 - [Plugins and Model Routing](https://planr.so/docs/plugins) · [Recipes](https://planr.so/docs/guides/recipes)
 - [Integrations and Host Hooks](https://planr.so/docs/integrations)
 - [CLI Reference](https://planr.so/docs/reference/cli) · [MCP Reference](https://planr.so/docs/reference/mcp)
-- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor)
+- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor) · [Grok Build](https://planr.so/docs/integrations/grok-build)
 - [Daily Worker Loop](https://planr.so/docs/guides/daily-worker-loop)
 - [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness)
 - [Architecture](https://planr.so/docs/contributing/architecture)

package/docs/ARCHITECTURE.md

@@ -19,7 +19,9 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/main.rs`: process composition root. Owns top-level module wiring, process startup, database opening, error printing, and dispatch into `App`.
 - `src/cli.rs`: CLI contract boundary. Owns `clap` command definitions, option parsing types, value enums, and command DTOs used by app dispatch.
 - `src/app/mod.rs`: application composition boundary. Owns the `App` runtime state, top-level dispatch, shared app-local row helpers, and app submodule wiring.
-- `src/app/commands.rs`: CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and install command handlers.
+- `src/app/commands.rs`: general CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and shared install command handlers.
+- `src/app/grok.rs`: Grok-specific install orchestration. Owns safe project TOML reconciliation, repository workflow writes, and the explicit no-hooks result.
+- `src/app/prompts.rs`: CLI, MCP, and HTTP prompt output. Host routing prompt composition remains in `src/app/agents.rs`.
 - `src/app/flow.rs`: compound work-flow boundary. Owns evidence log writing (with heartbeat folding), the close transition core, review-request creation, the pick work packet, and the `done` command that chains them for CLI, HTTP, and MCP surfaces.
 - `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
 - `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
@@ -46,7 +48,8 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/route_audit.rs`: provider-neutral run-observation contract. Owns strict requested/resolved/effective route stages, model/effort/fork enforcement confidence, transition provenance, policy/binding versions, and per-dimension metering confidence. It rejects requested-only values in the effective stage rather than inferring host execution.
 - `src/app/agents.rs`: routing application boundary. Owns the `agents` and `item route` command handlers, the shared `*_value` JSON shapes reused by MCP, per-item route facts assembly, and registry-aware role content selection for installs.
 - `src/app/agents_init.rs`: registry bootstrap boundary. Owns `planr agents init` — the static cost-tiering scaffold and, per the agent-pool plan, the flag-spec builder and interactive wizard.
-- `src/integrations.rs`: agent-client integration descriptor boundary. Owns Codex, Claude Code, Cursor, MCP install metadata, MCP tool schemas, MCP resources, and MCP text response wrapping.
+- `src/integrations.rs`: shared agent-client descriptor boundary. Owns MCP install metadata, tool schemas, resources, and text response wrapping.
+- `src/integrations/grok.rs`: document-preserving Grok project MCP configuration and conflict policy.
 - `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
 - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
 

package/docs/RELEASE.md

@@ -12,18 +12,26 @@ The v1 repository-owned public install order is:
 
 Published npm versions bundle platform-native binaries; see <https://planr.so/docs/operations/release>.
 
-## Version Bump
-
-`scripts/release.sh` is the only supported release path. The version lives in
-`Cargo.toml`; `package.json`, both plugin manifests under `plugins/planr/`, and
-`.cursor-plugin/plugin.json` must match it. Generated CLI and MCP references
-must match the currently committed version before the release branch merges.
-After bumping on clean `main`, the script refreshes pnpm's derived workspace
-metadata with the frozen lockfile and rejects any lockfile byte change. It then
-builds, regenerates, and strictly checks both references before staging them in
-the same atomic release commit as the six synchronized version files. Manual
-tagging or pre-generating a future version skips this ownership boundary and
-can ship stale references.
+## Candidate and publication
+
+`scripts/prepare-release-candidate.sh` is the only supported version-transition
+path. Run it from clean, reviewed source on a release branch. It synchronizes
+`Cargo.toml`, `Cargo.lock`, `package.json`, both plugin manifests under
+`plugins/planr/`, `.cursor-plugin/plugin.json`, and the generated CLI/MCP
+references. It never stages, commits, tags, pushes, or publishes. Commit those
+changes with the changelog and any release-contract transition, then run the
+full candidate verification and independent review on that exact commit.
+
+`scripts/release.sh` is the only supported publication path. It runs on clean
+`main`, requires every version and generated reference to already match the
+requested version, reruns the local eval and deterministic gates, and rejects
+any command that changes the reviewed source. Only then does it create and push
+the annotated tag. Editing manifests by hand or publishing an unprepared commit
+skips this ownership boundary.
+
+```bash
+scripts/prepare-release-candidate.sh 1.2.0
+```
 
 ```bash
 export PLANR_RELEASE_EVAL_SUITE="$HOME/projects/planr-evals/suites/planr-lean-skills-dogfood.suite.json"
@@ -48,23 +56,28 @@ fixture tree; release verification does not read ignored files from the Planr
 checkout.
 
 Generate the candidate revision with
-`node scripts/verify-release-eval-receipt.mjs --print-candidate-revision`. At
-release time the candidate binary canonicalizes the explicitly supplied suite,
+`node scripts/verify-release-eval-receipt.mjs --print-candidate-revision`. The
+revision hashes every tracked or non-ignored release-source file, including its
+normalized executable mode, so changing any candidate source invalidates the
+receipt. The separate evaluated-subject revision binds the stored model run to
+the five workflow files the benchmark evaluates; changing either the exact
+release source or that evaluated subset invalidates the receipt. At release time the candidate binary canonicalizes the explicitly supplied suite,
 requires a Planr-validated effective route observation (host report, telemetry
 receipt, process exit, or local observation), recomputes the comparison from its
 stored baseline/candidate/policy identities, and gates that fresh result.
 Requested-only values and policy or binding metadata are never
 effective-treatment proof.
 
-The script enforces, in order:
+The two scripts enforce, in order:
 
-1. branch is `main`, worktree is clean, `CHANGELOG.md` already has a committed `## [x.y.z]` section, and the tag does not exist;
-2. the version is written into all synchronized manifests;
-3. `pnpm install --frozen-lockfile` refreshes installed workspace metadata, and any `pnpm-lock.yaml` byte change stops the release before build, references, gates, or Git mutation;
-4. the build synchronizes `Cargo.lock`, and the bumped candidate regenerates and strictly verifies both generated references before any later gate or Git mutation;
-5. the candidate binary validates the sanitized receipt, observed effective treatment, candidate binding, and existing Planr comparison/gate before any Git mutation;
-6. deterministic gates: `cargo test` (including manifest drift), `npm pack --dry-run`, and `scripts/security-local.sh` (betterleaks + trivy);
-7. one mechanical commit containing the six version files plus both generated references, an annotated `vx.y.z` tag carrying that summary, and a single push of branch plus tag.
+1. candidate preparation starts from a clean worktree and a nonexistent tag;
+2. the candidate version is written into all synchronized manifests;
+3. frozen workspace synchronization cannot change `pnpm-lock.yaml`;
+4. the candidate build synchronizes `Cargo.lock`, then regenerates and strictly checks both references without Git mutation;
+5. candidate source, changelog, contracts, and generated files are committed and independently reviewed before publication approval;
+6. publication requires clean `main`, the exact prepared versions/references, a committed changelog section, and no existing tag;
+7. the candidate binary validates the sanitized receipt and recomputed comparison, then deterministic tests, package, and security gates run without changing source;
+8. publication creates and pushes only the annotated `vx.y.z` tag for that reviewed commit.
 
 Two independent gates back the script:
 
@@ -96,8 +109,19 @@ Only `-alpha.N`, `-beta.N`, and `-rc.N` suffixes are accepted; everything else t
 
 Pushing a tag `vX.Y.Z` runs `.github/workflows/release.yml`:
 
+<!-- planr:linux-release-portability:start surface=maintainerRelease schema=1 -->
+> **Linux release portability — corrected**
+>
+> Contract state: `status=corrected`; `affectedThrough=v1.7.2`; `correctedFrom=v1.7.3`.
+> Published Linux release, installer, and npm binaries through v1.7.2 require GLIBC_2.39; macOS is unaffected.
+> Starting with v1.7.3, current Linux release, installer, and npm artifacts are static-musl executables and do not require glibc.
+> On an affected Linux release, build from source on the target distribution or upgrade to v1.7.3.
+<!-- planr:linux-release-portability:end surface=maintainerRelease schema=1 -->
+
+When this contract changes, update `docs/contracts/LINUX_RELEASE_PORTABILITY.json`, run `pnpm docs:sync-linux-portability`, and commit every synchronized notice before running the release gates.
+
 1. `create-release` verifies the tag against `Cargo.toml`, all distribution manifests, and the changelog section, then creates a draft GitHub Release.
-2. `build` compiles and packages `planr-<os>-<arch>.tar.gz` for `darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, and `linux-arm64`, then uploads each asset to the draft release.
+2. `build` compiles and packages `planr-<os>-<arch>.tar.gz` for `darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, and `linux-arm64`, then uploads each asset to the draft release. Future Linux candidates use native x86_64/arm64 GitHub runners and the same digest-pinned Rust 1.90.0 Alpine/musl image. Before upload, the extracted tarball must pass embedded checksums, static ELF checks (no interpreter, shared-library dependency, or glibc symbol), a fresh project/plan/map/pick/done/export lifecycle in digest-pinned Alpine 3.20.8 with networking disabled, and exact-byte npm wrapper execution.
 3. `finalize` downloads all uploaded assets, writes one aggregated `SHA256SUMS` covering every tarball, uploads it, and publishes the release.
 4. `npm-publish` downloads the release assets, verifies them against `SHA256SUMS`, bundles the four platform binaries into `npm/native/`, smoke-tests the wrapper, and publishes to npm via Trusted Publishing (OIDC). Runs only when the repository variable `NPM_PUBLISH_ENABLED` is `true`; requires the one-time Trusted Publisher setup described at <https://planr.so/docs/operations/release>.
 5. `homebrew-tap` regenerates `Formula/planr.rb` with `scripts/generate-formula.sh` and pushes it to `instructa/homebrew-tap` (installed as `brew install instructa/tap/planr`).
@@ -122,6 +146,11 @@ scripts/security-local.sh
 ```
 
 The external consumer E2E suite must pass when available on the release machine.
+Pull-request CI separately builds both Linux architectures through the canonical
+containerized release script, runs the full portability contract without
+secrets or publication permissions, and aggregates checksums for the exact two
+candidate tarballs. A same-runner `--version` smoke is useful architecture
+evidence but is not Linux compatibility proof by itself.
 
 ## Build Artifact
 

package/docs/contracts/GROK_INTEGRATION_V1.md

@@ -0,0 +1,139 @@
+# Grok Build Integration Contract v1
+
+Status: frozen for implementation
+
+Frozen: 2026-07-27
+
+Upstream source probe: `xai-org/grok-build` commit
+`b41c75a578f98bddbd326ab02cd53618451d97ee` (2026-07-26)
+
+This contract is the implementation boundary for first-class Grok Build support.
+It reconciles the public xAI documentation, the locally cloned upstream source,
+and Planr's local-first integration rules. Live authenticated verification is a
+separate maintainer-local release gate; it never runs in CI.
+
+## Frozen artifact and discovery policy
+
+`planr install grok` owns exactly the repository paths in the executable
+contract below. Workflow files are copied byte-for-byte from the canonical
+`plugins/planr` sources. There is no second Grok-specific workflow body.
+
+Planr does **not** emit `.grok/plugins/planr` or a Grok plugin manifest in v1.
+Current Grok source discovers project plugins from `.grok/plugins`, but project
+plugins default to disabled and project `.grok/config.toml` does not merge
+`[plugins].enabled`. A repository-local plugin would therefore require
+user-level enablement and would not satisfy one-command project setup. Native
+`.grok/skills/<name>/` and `.grok/agents/*.md` are documented, directly
+discovered project paths and do not depend on Claude compatibility scanners.
+
+Grok's current manifest lookup is still relevant for troubleshooting: a plugin
+root checks `plugin.json`, then `.grok-plugin/plugin.json`, then
+`.claude-plugin/plugin.json`, and finally convention-based component folders.
+That behavior is observed upstream but deliberately not used by Planr v1.
+
+```json
+{
+  "contract_version": 1,
+  "upstream_revision": "b41c75a578f98bddbd326ab02cd53618451d97ee",
+  "artifacts": [
+    {"target": ".grok/config.toml", "source": "generated:grok_project_config", "kind": "mcp"},
+    {"target": ".grok/agents/planr-reviewer.md", "source": "plugins/planr/agents/planr-reviewer.md", "kind": "agent"},
+    {"target": ".grok/agents/planr-worker.md", "source": "plugins/planr/agents/planr-worker.md", "kind": "agent"},
+    {"target": ".grok/skills/planr-goal/SKILL.md", "source": "plugins/planr/skills/planr-goal/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-loop/SKILL.md", "source": "plugins/planr/skills/planr-loop/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-loop/agents/planr-reviewer.md", "source": "plugins/planr/skills/planr-loop/agents/planr-reviewer.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/agents/planr-worker.md", "source": "plugins/planr/skills/planr-loop/agents/planr-worker.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/references/host-dispatch.md", "source": "plugins/planr/skills/planr-loop/references/host-dispatch.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/references/recovery-and-verification.md", "source": "plugins/planr/skills/planr-loop/references/recovery-and-verification.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-plan/SKILL.md", "source": "plugins/planr/skills/planr-plan/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-review/SKILL.md", "source": "plugins/planr/skills/planr-review/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-status/SKILL.md", "source": "plugins/planr/skills/planr-status/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-summary/SKILL.md", "source": "plugins/planr/skills/planr-summary/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-task-graph/SKILL.md", "source": "plugins/planr/skills/planr-task-graph/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-verify-web/SKILL.md", "source": "plugins/planr/skills/planr-verify-web/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-work/SKILL.md", "source": "plugins/planr/skills/planr-work/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr/SKILL.md", "source": "plugins/planr/skills/planr/SKILL.md", "kind": "skill"}
+  ],
+  "mcp": {
+    "table": "mcp_servers.planr",
+    "command": "planr",
+    "args": ["mcp"],
+    "enabled": true,
+    "startup_timeout_sec": 30,
+    "tool_timeout_sec": 6000,
+    "env": {"PLANR_MCP_CLIENT": "grok"},
+    "forbidden_fields": ["XAI_API_KEY", "api_key", "auth", "model", "headers", "url"]
+  },
+  "plugin": {
+    "emitted": false,
+    "project_root": ".grok/plugins",
+    "manifest_precedence": ["plugin.json", ".grok-plugin/plugin.json", ".claude-plugin/plugin.json", "convention"],
+    "project_default": "disabled",
+    "project_config_enabled_merged": false
+  },
+  "hooks": {"supported": false, "artifacts": []},
+  "client_all_includes_grok": false,
+  "headless": {"command": "grok --no-auto-update -p \"<prompt>\" --output-format json"}
+}
+```
+
+The generated `.grok/config.toml` table is therefore:
+
+```toml
+[mcp_servers.planr]
+command = "planr"
+args = ["mcp"]
+enabled = true
+startup_timeout_sec = 30
+tool_timeout_sec = 6000
+env = { PLANR_MCP_CLIENT = "grok" }
+```
+
+`PLANR_MCP_CLIENT=grok` is a narrow adapter marker applied by Grok's MCP
+launcher to the Planr child process. Planr may use the exact value as an
+advisory observed-client signal. It is not authentication, authorization, or a
+general worker identity. Ambient `GROK_*` variables are not accepted as the v1
+signal because the probed Grok MCP launcher does not inject a stable one.
+
+## Merge and overwrite policy
+
+- Missing `.grok/config.toml`: create it with only the Planr MCP table.
+- Existing valid config: perform a document-preserving TOML merge. Preserve
+  every foreign table, key, comment, and order; only `mcp_servers.planr` is
+  owned by Planr.
+- Existing different `mcp_servers.planr`: without `--force`, preserve it and
+  report a conflict; with `--force`, replace only that table.
+- Malformed config: fail with a path-and-parse diagnostic and write nothing,
+  including under `--force`.
+- Workflow target missing: write the canonical source. Existing identical
+  content is unchanged. Existing different content is preserved without
+  `--force` and replaced from the canonical source with `--force`.
+- `--no-mcp` omits `.grok/config.toml` reconciliation. `--no-hooks` is accepted
+  for CLI parity but changes no Grok paths because v1 installs no hooks.
+- Dry-run enumerates the same paths the corresponding write would reconcile.
+
+## Security and CI boundary
+
+Repository artifacts contain no xAI credential, token, auth-file path, model
+selection, endpoint, or absolute maintainer path. Planr never reads or copies
+`~/.grok`, `$GROK_HOME`, session data, `auth.json`, or
+`mcp_credentials.json` while installing.
+
+GitHub Actions and release workflows must not install or invoke Grok, reference
+`XAI_API_KEY`, gate on an xAI secret, or perform live inference. Deterministic
+tests parse and compare generated files without Grok installed. Maintainer-local
+release verification may use an existing login, but recorded evidence is
+limited to redacted discovery/origin, diagnostics, and the disposable Planr
+project identity.
+
+The supported inspection and headless syntax is `grok inspect --json` and
+`grok --no-auto-update -p "<prompt>" --output-format json`; `grok exec` is not part of this contract.
+
+## Sources
+
+- https://docs.x.ai/build/features/skills-plugins-marketplaces
+- https://docs.x.ai/build/settings
+- https://docs.x.ai/build/features/mcp-servers
+- https://docs.x.ai/build/cli/reference
+- https://docs.x.ai/build/cli/headless-scripting
+- https://github.com/xai-org/grok-build/tree/b41c75a578f98bddbd326ab02cd53618451d97ee

package/docs/contracts/LINUX_RELEASE_PORTABILITY.json

@@ -0,0 +1,9 @@
+{
+  "affectedReleases": [
+    "1.7.2"
+  ],
+  "affectedThrough": "1.7.2",
+  "correctedFrom": "1.7.3",
+  "noticeSchema": 1,
+  "status": "corrected"
+}

package/docs/documentation/COVERAGE.md

@@ -4,14 +4,14 @@ This is the canonical inventory that maps shipped public surfaces to repository
 
 ## Published route inventory
 
-The site currently owns 61 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+The site currently owns 62 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
 
 | Section | Published routes |
 | --- | --- |
 | Documentation | `/docs` |
 | Getting started | `/docs/getting-started`, `/docs/getting-started/why-planr`, `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle`, `/docs/getting-started/choose-your-interface` |
 | For Agents | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
-| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
+| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/grok-build`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
 | Plugins | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
 | Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/recipes` |
@@ -64,6 +64,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 | Codex | Codex manifest, generated role/install assets | `/docs/integrations/codex` |
 | Claude Code | Claude manifest, generated role/install assets | `/docs/integrations/claude-code` |
 | Cursor | Cursor manifest, role/skill/install assets | `/docs/integrations/cursor` |
+| Grok Build | Native role/skill assets and portable project MCP config | `/docs/integrations/grok-build` |
 | Generic stdio MCP | MCP server and fixture | `/docs/integrations/generic-mcp` |
 | CLI-only and non-first-class hosts | prompt output and CLI | `/docs/integrations/cli-only` |
 | Privacy, secret handling, localhost boundary | safety spec, `src/app/http.rs`, scrub behavior | `/docs/contributing/security-and-privacy` |
@@ -86,7 +87,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 
 ## Audit completion checklist
 
-- [x] All 61 current MDX routes are explicitly inventoried.
+- [x] All 62 current MDX routes are explicitly inventoried.
 - [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
 - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
 - [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.

package/docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -20,7 +20,7 @@ This file records the implemented route and navigation contract. Routes are publ
 
 ## Implemented route tree
 
-The 61 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
+The 62 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
 
 ```text
 /docs
@@ -38,6 +38,7 @@ The 61 MDX files below are the current page tree and must agree with every `meta
 │   ├── codex
 │   ├── claude-code
 │   ├── cursor
+│   ├── grok-build
 │   ├── generic-mcp
 │   └── cli-only
 ├── plugins

package/docs/fixtures/mcp-contract.json

@@ -92,16 +92,23 @@
       "\"mcpServers\"",
       "\"planr\"",
       "cursor://anysphere.cursor-deeplink/mcp/install?name=planr&config="
+    ],
+    "grok": [
+      "[mcp_servers.planr]",
+      "args = [\"mcp\"]",
+      "PLANR_MCP_CLIENT = \"grok\"",
+      ".grok/skills/planr/SKILL.md",
+      "hooks: unsupported/no-op"
     ]
   },
   "cli_reference_commands": [
-    "planr install codex|claude|cursor",
+    "planr install codex|claude|cursor|grok",
     "planr prompt cli|mcp|http",
     "planr prompt routing",
     "planr agents init",
     "planr agents init --profile|--skill|--route|--default-route|--interactive",
     "planr prime",
-    "planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]",
+    "planr install codex|claude|cursor|grok [--dry-run] [--no-mcp] [--force] [--no-hooks]",
     "planr mcp",
     "planr review annotate",
     "planr review ingest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,7 @@
     "docs:verify-agent-landing": "pnpm --filter @planr/docs verify:agent-landing",
     "docs:verify-concepts": "cargo build --bin planr && pnpm --filter @planr/docs verify:concepts",
     "docs:verify-maintenance": "pnpm --filter @planr/docs verify:maintenance",
+    "docs:sync-linux-portability": "pnpm --filter @planr/docs sync:linux-portability",
     "docs:verify-deployment": "pnpm --filter @planr/docs verify:deployment",
     "docs:verify-release": "pnpm --filter @planr/docs verify:release",
     "docs:verify-release-live": "pnpm --filter @planr/docs verify:release-live",

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",