@thebackstoryis/engineering-with-ai 0.3.1-beta.0 → 0.3.2

package/Docs/context-management-and-token-efficiency.md

@@ -8,7 +8,7 @@ Context preparation doesn't approve Build or Manual QA, accept risk, certify qua
 
 ## Concise answers and guided decisions
 
-**Availability:** This guidance is included in `0.3.1-beta.0`. Follow [beta installation](operations/installation-updating-and-entitlements.md#try-the-beta-channel), then initialise the project or run its normal EWAI check-in to refresh the managed instructions in `AGENTS.md` and `CLAUDE.md`. Start a fresh host conversation after the refresh. Project-authored guidance outside the managed block is preserved. npm `0.3.0` does not include these new instructions. Tool-result compaction remains planned, and no incremental token or cost saving has been measured for this update.
+**Availability:** This guidance is included from `0.3.1`. [Update EWAI](operations/installation-updating-and-entitlements.md), then initialise the project or run its normal EWAI check-in to refresh the managed instructions in `AGENTS.md` and `CLAUDE.md`. Start a fresh host conversation after the refresh. Project-authored guidance outside the managed block is preserved. Versions `0.3.0` and earlier don't include these instructions. Tool-result compaction remains planned, and no incremental token or cost saving has been measured for this update.
 
 ### Get a useful short answer
 

package/Docs/maintainers/contributing.md

@@ -14,6 +14,14 @@ npm run check
 
 Read the repository instructions and inspect your branch and uncommitted changes before editing. Keep test projects disposable and separate from active customer work. Don't install local changes over a global release as an incidental verification step.
 
+## Public development and release communication
+
+Commit messages, pull-request discussions, GitHub comments and release notes are externally visible. Describe the product behaviour, scope and verified checks. Keep credentials, customer information, private deliberations, internal correspondence and conversation-only research out of those records. Review staged files and the exact public text before committing or publishing. Release notes must distinguish shipped capability from planned work and report limitations without claiming unobserved acceptance or savings.
+
+## Native provider changes
+
+Bind unattended capability to the reviewed native CLI identity and verify coding, read-only review and restricted proposal modes separately. Grok fixtures use a synthetic loopback model and kernel confinement; they must never call paid model endpoints or load personal credentials. A passing fixture proves its boundary, not authentication, model quality or Manual QA. A version change requires renewed conformance evidence. Preserve default native model choice and stop when a requested restriction cannot be enforced.
+
 ## Development commands
 
 ```bash

package/Docs/operations/dashboard-configuration.md

@@ -2,6 +2,28 @@
 
 The dashboard starts with its everyday tools. Extra views are off by default, so you don't have to navigate portfolio management, policy controls or integration tools when your project doesn't need them.
 
+## Coding provider settings
+
+Open **Configuration → Coding providers** to choose which coding CLIs EWAI uses. These settings govern host selection and AFK/autonomy dispatch; saving them does not start a delivery or approve execution.
+
+Choose the primary coding provider, secondary and tertiary reviewers, and an eligible pool. **Existing behaviour** preserves normal host selection and checkpoint policy. **Choose automatically** creates a draft with automatic roles; it does not run anything or approve a grant. Required review capacity cannot be weakened, and reviewers must differ from the actual coding agent.
+
+Leave optional model fields blank to let each CLI decide. A suggestion supplies advisory guidance without forcing a model. A permitted-model list is a strict boundary: unsupported enforcement stops invocation. The current adapters do not have verified permitted-list enforcement. Recommended: leave this list blank for native selection unless a verified adapter is available. This is not a token or spending cap, and no savings have been measured.
+
+Use **Save provider settings** to apply the draft. **Cancel changes** restores the last saved policy in the form; **Restore existing behaviour** removes only the additive provider policy when saved. If another editor changes configuration, the draft is retained. Compare the latest settings, then explicitly keep the draft against those settings before saving again. That replaces the provider policy, while preserving other project configuration.
+
+For automatic unattended work, save an eligible pool, then choose **Automatic from saved pool** in the autonomy controls. Preview and review the exact providers, intents, actions, expiry and limits before approving a grant. Selection uses only providers inside both the saved pool and approved grant that can perform the requested action and enforce any configured model restriction. Automatic roles skip ineligible providers; explicitly selected or inherited required providers stop instead of changing your choice. Changing settings invalidates the old grant: review a fresh one.
+
+Installed CLI status does not prove authentication or unattended capability. Grok coding, review and proposal modes each run an offline conformance check before dispatch. See [Grok setup and limitations](installation-updating-and-entitlements.md#grok-build). A failed check stops the run; inspect its reason before retrying.
+
+## Grok Build credentials
+
+Open **Configuration → Grok Build credentials** to enter an xAI API key in a password field, then choose **Check and save key**. This performs an authentication-only check and saves a key for your account on this computer, across EWAI projects. It does not start work or select a model. The owner-only local credential file is outside the project and is not encrypted.
+
+The status distinguishes a saved key from `XAI_API_KEY` in the launching environment, which takes precedence. **Check connection** checks the active credential without generating output; it does not prove available credit or coding readiness. **Remove saved key** removes only EWAI's saved copy; it does not revoke the key or clear an environment override. **Cancel key entry** clears the input while retaining the previous saved key.
+
+The password is cleared after every submission, including a failed check, and is never put in browser storage. Failed replacement retains the previous saved key. If a saved revision changed, refresh status before retrying. For storage, CLI alternatives and recovery, see [private Grok setup](installation-updating-and-entitlements.md#private-grok-key-setup-and-recovery).
+
 ## Show an extra view
 
 1. Open your project's dashboard.

package/Docs/operations/installation-updating-and-entitlements.md

@@ -6,7 +6,7 @@ This guide covers the harness installation. For a persona licence, use [Set up a
 
 ## Before you start
 
-You'll need Node.js 22.5 or newer, npm, Git for project version control, and a supported host: Codex, Claude Code or Google Antigravity's `agy` CLI. Technology packs can have further requirements.
+You'll need Node.js 22.5 or newer, npm, Git for project version control, and a supported host: Codex, Claude Code, Google Antigravity's `agy` CLI or Grok Build. Technology packs can have further requirements.
 
 EWAI includes its own parsers. Don't add Tree-sitter dependencies to your application just to use the harness.
 
@@ -20,7 +20,7 @@ ewai install --host auto
 ewai
 ```
 
-The installation command makes the host skills and MCP connection available. You can choose one host explicitly with `--host codex`, `--host claude` or `--host antigravity`.
+The installation command makes the host skills and MCP connection available. You can choose one host explicitly with `--host codex`, `--host claude`, `--host antigravity` or `--host grok`. For Grok Build, see [Grok Build](#grok-build) for authentication and unattended worker setup.
 
 If npm returns `E404`, check the exact package name and configured registry first. That response alone doesn't tell you whether the package is unpublished, unavailable to your account or missing its requested version. If the intended package still isn't available, contact the publisher; don't install a similarly named package as a substitute.
 
@@ -48,7 +48,7 @@ This asks npm to obtain and run the package. It doesn't create a standing global
 
 ## Try the beta channel
 
-The beta channel is an opt-in prerelease. Version `0.3.1-beta.0` adds [concise answers and guided decisions](../context-management-and-token-efficiency.md#concise-answers-and-guided-decisions); production remains `0.3.0`.
+The beta channel is an opt-in prerelease for trying changes before they reach production. Check what each channel currently points to with `npm view @thebackstoryis/engineering-with-ai dist-tags`.
 
 For one project:
 
@@ -57,7 +57,7 @@ npm install --save-dev @thebackstoryis/engineering-with-ai@beta
 npx ewai
 ```
 
-To pin this specific beta instead of following the beta channel, replace `@beta` with `@0.3.1-beta.0`. For a global beta installation, use `npm install --global @thebackstoryis/engineering-with-ai@beta`, then start EWAI in your project folder.
+To pin a specific beta instead of following the beta channel, replace `@beta` with that exact version, for example `@0.3.1-beta.0`. For a global beta installation, use `npm install --global @thebackstoryis/engineering-with-ai@beta`, then start EWAI in your project folder.
 
 Initialisation or normal check-in refreshes the EWAI-managed block in `AGENTS.md` and `CLAUDE.md`. Guidance outside that block is preserved. In an existing project, you can refresh explicitly with `npx ewai checkin --project . --json` for a project dependency, or `ewai checkin --project . --json` for a global installation. Start a fresh host conversation after refreshing so it reads the new instructions. Review changes to your project's package, lockfile and instruction files before committing them.
 
@@ -125,9 +125,47 @@ Check-in can start or reuse the dashboard, refresh derived state and check the p
 | Codex | `.agents/skills/` | `.codex/config.toml` |
 | Claude Code | `.claude/skills/` | `.mcp.json` |
 | Google Antigravity | `.agents/skills/` | `.agents/mcp_config.json` |
+| Grok Build | `.grok/skills/` | `.grok/config.toml` |
 
 EWAI merges its entries with unrelated host configuration. Don't replace the entire file to update one entry. After an update, check that your other MCP servers are still present.
 
+From `0.3.1`, `EWAI_HOST=grok ewai` opens the native Grok companion without a model override. Install and authenticate the CLI through the [official Grok Build instructions](https://docs.x.ai/build/overview). CLI installation alone does not prove account access or project trust.
+
+For explicitly selected global skill installation, EWAI respects `GROK_HOME`; project installation uses `.grok/skills/`. Malformed, conflicting or unsafe TOML configuration stops MCP setup without rewriting that file. Resolve the reported configuration issue and retry; keep other MCP entries.
+
+### Grok Build
+
+1. Install and authenticate Grok Build using its official instructions. For isolated unattended workers, the supported identity is `grok 1.0.44 (5b807183dd79) [stable]` on macOS. Other identities stop until their conformance contract is reviewed.
+2. Enable Grok with `ewai validation set grok available --enabled --project .`. For a new project, `ewai init --grok` records the same explicit availability choice.
+3. Choose providers in **Configuration → Coding providers**, or use `ewai providers set --primary grok --secondary codex --tertiary claude --pool grok,codex,claude --project .`. Enable and authenticate the selected reviewers too. Leave model fields blank for native selection.
+4. Before unattended work, open **Configuration → Grok Build credentials** and use **Check and save key**, or run `ewai providers credentials grok configure` in an interactive terminal for hidden input. The key is saved for your account on this computer, outside the project, in an owner-only local file. `XAI_API_KEY` in the launching environment takes precedence. Interactive OAuth sessions can still use the native companion; isolated workers do not copy your personal authentication files. Never put keys in project YAML, command arguments, chat, commits or release notes.
+5. Run the usual AFK preflight or preview and approve an autonomy grant. Full automatic selection stays inside the approved scope and preserves Build approval, required review and Manual QA checkpoints.
+
+Grok coding, review and restricted proposal modes each verify the installed binary and their own offline confinement contract. The worker has a fresh private home and no inherited project instructions, hooks, skills, MCP servers or personal model configuration. EWAI supplies approved task context; Grok retains native model choice without a model override. Its bounded session-title metadata request is separate from the coding/proposal tools. Offline conformance makes no paid model requests and does not prove your account access or the quality of a real response.
+
+Coding copies declared task files into a disposable workspace. The worker may edit only that copy; EWAI checks scope, unchanged source predecessors and current authority before accepting changes. Review is read-only. EWAI's conductor runs approved commands and owns commits and integration. Snapshots accept regular files only, up to 900 KB per file, 256 files and 16 MiB overall. Root-wide globs and copied CLI/credential configuration are unsupported: narrow the task's file sets instead.
+
+For coding and review, the conductor includes the complete cited standards and recorded check outputs in mandatory task context. Review also receives the exact implementation commit diff. Git history and canonical SPECS remain outside the worker's filesystem. Evidence is bound to its task, source contents and revision, then checked again before dispatch and acceptance. Missing, changed or oversized evidence stops the run; restore the required evidence or narrow the approved task and prepare fresh context. Mandatory evidence is never silently truncated to fit a prompt.
+
+If a version, isolation check, unsupported system configuration, credential or model restriction blocks the run, inspect the recorded reason. Recommended: use the supported CLI identity, configure the private key, or remove an unsupported permitted-model restriction for native selection, as applicable, then repeat preflight. If source files changed, prepare a fresh task snapshot. Preserve partial edits and uncertain execution for recovery; do not blindly retry. No model setting is a token or spending cap.
+
+#### Private Grok key setup and recovery
+
+```bash
+ewai providers credentials grok configure
+ewai providers credentials grok status --json
+ewai providers credentials grok check
+ewai providers credentials grok remove --yes
+```
+
+Configure requires a real interactive terminal; keys cannot be passed through flags or input files. The local dashboard password form is the alternative. Both routes share validation and recovery. Submitting a key authenticates against xAI's [model-list endpoint](https://docs.x.ai/developers/rest-api-reference/inference/models) without requesting generated output. Success proves that endpoint accepted the key, not available credit, permission to every model, or coding readiness. The check does not select a model or start a delivery.
+
+On supported POSIX systems, explicit setup stores plaintext in `~/.ewai/credentials/grok.json` with owner-only file permissions (`0600`) in a private directory (`0700`). It is not encrypted or an OS keychain; processes running as your account can read it. The key applies across EWAI projects for that account. EWAI rejects insecure permissions, links, shared files and storage inside the project. On Windows, use a privately supplied launching environment; this file-storage route is unavailable.
+
+Status shows only the credential source and whether a saved key exists. It never returns the key. Connection checks run only when explicitly requested. Failed or stale replacement keeps the previous saved key; refresh status, correct the problem and submit again. The dashboard clears the password after success, failure or cancellation and does not store it in browser storage. Removing a saved key does not revoke it at xAI, and does not clear an environment override. Remove `XAI_API_KEY` from the launching environment and restart EWAI if you want the saved key to become active. Use xAI's own account controls to revoke a key.
+
+Saved keys are resolved at each isolated-worker invocation. The worker receives only the credential in its private environment; no personal authentication/configuration files are copied. Native model selection and conformance requirements remain unchanged.
+
 ## Premium personas
 
 Enter your licence through **Configuration → Premium personas → Manage licence** in the dashboard, or use the hidden terminal prompt:

package/Docs/reference/capabilities-and-project-layout.md

@@ -73,11 +73,12 @@ project/
 
 Initialisation preserves existing files unless `--force` is explicitly supplied.
 
-It also safely merges project MCP entries for the three supported hosts:
+It also safely merges project MCP entries for the supported hosts:
 
 ```text
 .mcp.json                 Claude Code
 .codex/config.toml        Codex
+.grok/config.toml         Grok Build
 .agents/mcp_config.json   Google Antigravity / AGY CLI
 ```
 
@@ -85,7 +86,11 @@ Each host launches the same project-bound `ewai mcp --project .` stdio server. E
 
 Before creating EWAI artefacts, initialization checks for existing source files, manifests, and project definitions. The conversational companion first captures a human project briefing, then optionally asks whether the user has a folder of emails, meeting transcripts, documentation, research, requirements, or other project material that could enrich the project. For an existing codebase, EWAI offers optional Archaeology. If the owner accepts, it compares the confirmed purpose and reviewed imported context with repository evidence before deeper reconstruction. A fresh project uses the same context to make discovery more specific.
 
-`--claude`, `--codex`, and `--antigravity` record validation CLIs that the user has explicitly confirmed are available and initially enabled. Antigravity access uses the `agy` executable. These flags do not install or authenticate those services. At delivery time EWAI excludes the active orchestrator from the independent reviewer set.
+`--claude`, `--codex`, `--grok`, and `--antigravity` record validation CLIs that the user has explicitly confirmed are available and initially enabled. Antigravity access uses the `agy` executable. These flags do not install or authenticate those services. At delivery time EWAI excludes the active orchestrator from the independent reviewer set.
+
+## Coding provider and model preferences
+
+Choose a primary coding CLI and distinct secondary/tertiary reviewers in the dashboard or through `ewai providers`. Without this optional policy, existing selection and native models remain unchanged. Suggestions are advisory; unsupported permitted-model restrictions stop invocation. Automatic selection remains inside configured and approved provider pools and does not bypass human checkpoints. Grok unattended modes require their separately verified native identity and private environment authentication. See [provider controls](cli-and-configuration.md#coding-provider-settings) and [Grok setup](../operations/installation-updating-and-entitlements.md#grok-build).
 
 ## Enrich a project from supplied context
 
@@ -259,7 +264,7 @@ ewai validation checkpoint implementation-plan --cycles 2 \
 
 Availability records what the project can access; `enabled` records what the project chooses to spend. Each implementation-plan, test-plan, and code checkpoint independently controls its reviewers, maximum review/fix cycles, breadth, analysis depth, and output size. The active orchestrator is excluded from independent validation. Unsupported stages remain visible in delivery state and must not be marked passed.
 
-The EWAI method is provider-neutral. One capable AI can run the workflow without pretending self-review is independent; additional Claude CLI, Codex CLI, or Antigravity (`agy`) systems can provide independent perspectives where available and proportionate. Standards compliance is always required, even when no external validator is configured.
+The EWAI method is provider-neutral. One capable AI can run the workflow without pretending self-review is independent; additional Claude CLI, Codex CLI, Grok Build, or Antigravity (`agy`) systems can provide independent perspectives where available and proportionate. Standards compliance is always required, even when no external validator is configured.
 
 ## Create an intent
 
@@ -453,7 +458,7 @@ ewai afk resume <run-id>
 ewai afk cancel <run-id>
 ```
 
-Each task runs on a real task branch in an isolated Git worktree using an enabled local Claude, Codex, or Antigravity CLI. Concurrency never exceeds the validated task graph. Workers cannot own central delivery state or merges; the conductor enforces write sets, captures structured evidence, obtains a fresh-context review, merges in declared order, and runs post-merge verification before committing. Runtime state and raw provider logs live under ignored `.ewai-pipeline/afk/`; task reports and hashed evidence remain under `6.Build/<slug>/tasks/` in the configured SPECS repository.
+Each task runs on a real task branch in an isolated Git worktree using an enabled local Claude, Codex, Grok Build, or Antigravity CLI. Concurrency never exceeds the validated task graph. Workers cannot own central delivery state or merges; the conductor enforces write sets, captures structured evidence, obtains a fresh-context review, merges in declared order, and runs post-merge verification before committing. Runtime state and raw provider logs live under ignored `.ewai-pipeline/afk/`; task reports and hashed evidence remain under `6.Build/<slug>/tasks/` in the configured SPECS repository.
 
 AFK detects topology from the configured `pipeline.yaml`. A simple project maps tasks to its single repository. A multi-repository project maps each task's `repo` to a named configured repository, creates and integrates its task branch there, and commits canonical evidence in the repository containing the configured SPECS root. The workspace itself does not need to be a Git repository. `task-graph.json.repository_branches` can declare different integration branches per repository; its scalar `parent_branch` remains the backwards-compatible default. When a declared integration branch does not exist, `afk start` creates it from that repository's clean current branch. Preflight blocks missing mappings, ambiguous SPECS ownership, nested non-root repository paths, dirty repositories, detached heads, or drift from an integration branch that already exists instead of guessing. A completed AFK run means eligible Build tasks were integrated; the canonical Build gate, Standards Sweep, Test Execute, external code validation, Delivery, Manual QA, and Retro still run normally.
 
@@ -497,7 +502,7 @@ Without existing work, [6] is absent. With available premium access and a verifi
 
 Conversational actions use the same guarded project-local operations as the dashboard and optional commands. Before moving work forward, EWAI checks the current stage, required documents, evidence, approvals, tests and configured external validators, then explains the proposed next step.
 
-Running `ewai` refreshes the selected host's managed EWAI skills and launches the conversational companion in an available Claude Code, Codex or Google Antigravity host. Initialization adds a small managed instruction block so directly opened agent sessions use the same check-in. The lower-level commands remain available for scripts and integrations; you don't need to learn them to work conversationally.
+Running `ewai` refreshes the selected host's managed EWAI skills and launches the conversational companion in an available Claude Code, Codex, Grok Build or Google Antigravity host. Initialization adds a small managed instruction block so directly opened agent sessions use the same check-in. The lower-level commands remain available for scripts and integrations; you don't need to learn them to work conversationally.
 
 ## Technology and stack packs
 
@@ -614,7 +619,7 @@ If check-in confirms unavailable premium access and no installed premium pack, t
 
 ### MCP access
 
-The MCP server uses stdio and is started by Codex, Claude Code, or Antigravity from the project configuration written during initialization. It exposes intent and work-item reads, guarded intent creation, operational updates, phase and material registration, runtime status, and active-work events. It does not require the HTTP dashboard to be running.
+The MCP server uses stdio and is started by Codex, Claude Code, Grok Build, or Antigravity from the project configuration written during initialization. It exposes intent and work-item reads, guarded intent creation, operational updates, phase and material registration, runtime status, and active-work events. It does not require the HTTP dashboard to be running.
 
 ### Current runtime scope
 

package/Docs/reference/cli-and-configuration.md

@@ -230,6 +230,38 @@ These commands support a prepared Archaeology bundle. The human purpose briefing
 
 Technology and hosting preparation requires a fresh Repository Source Map and a valid, user-reviewed persona-routing gate. It writes an evidence briefing and answer template into the bundle. Recording distinguishes repository-observed, owner-declared and individually human-confirmed claims; it does not rewrite canonical stack strategy. Status reports drift without refreshing or mutating the index. See [Archaeology technology and hosting discovery](../archaeology-technology-and-hosting-discovery.md).
 
+## Coding provider settings
+
+Available from `0.3.1`. CLI and dashboard share the same provider policy. A successful save changes preferences; it does not authorise execution.
+
+```bash
+ewai providers show --project . --json
+ewai providers set --primary grok --secondary codex --tertiary claude --pool grok,codex,claude --project .
+ewai providers auto --pool claude,codex,grok --project .
+ewai providers model grok --suggest <exact-model-id> --project .
+ewai providers model grok --allow-model <exact-model-id> --project .
+ewai providers model grok --clear-suggestion --clear-restriction --project .
+ewai providers defaults --project .
+```
+
+`set` also accepts a complete policy JSON file through `--input <file>`. `--expected-digest <digest>` guards against stale writes. Without that argument, the CLI compares the configuration it just read before saving. Dashboard and CLI use the same validator and atomic settings writer.
+
+The optional `coding_providers` section has an ordered, distinct `pool`; `primary` (`existing`, `auto` or a provider); `secondary`/`tertiary` (also allowing `off`); and per-provider `models` with optional `suggestion` and exact `permitted_models`. Providers are `claude`, `codex`, `grok` and `antigravity`. No executable paths, flags, credentials, wildcard IDs or inferred model ranking are accepted. The absent section preserves existing behaviour; `defaults` removes only this section.
+
+Native model choice is the default. Suggestions are advisory. Permitted-model lists prevent a provider from running where enforcement is unverified; they do not cap tokens or spending. All current adapters lack verified permitted-list enforcement. Automatic roles skip a provider with such a restriction and select an eligible alternative; explicitly selected or inherited required providers stop. If none remain, EWAI explains the unsupported restriction. Recommended: leave it blank unless an enforcing adapter becomes available.
+
+Enable installed providers separately with `ewai validation set <provider> available --enabled --project .`. `ewai providers auto --pool codex,claude,grok --project .` sets automatic coding and review roles; the pool needs enough available, independent providers to satisfy those roles and required checkpoints. Automatic does not mean that missing reviewers are skipped. `existing` retains inherited selection; `off` cannot reduce required review capacity. An explicit AFK `--provider` conflicting with a saved explicit primary stops preflight: update the settings or use `--provider auto`.
+
+For unattended Build, run `ewai afk preflight <slug> --provider auto --project .` after canonical Build approval. Autonomy's `--provider auto` selects inside the intersection of saved settings, installed/configured capabilities and the approved grant. The dashboard previews the exact saved pool before grant approval. A settings or CLI-identity change stops stale dispatch/results and requires a fresh check; changing settings also requires a new autonomy grant. Full auto preserves all human checkpoints.
+
+Grok supports interactive launch, skills and MCP setup, plus separately checked coding, read-only review and restricted proposal modes. Availability of the CLI does not prove mode capability or authentication. See [Grok worker setup](../operations/installation-updating-and-entitlements.md#grok-build) for the supported version, private credentials, snapshot bounds and recovery.
+
+### Grok credentials
+
+`ewai providers credentials grok configure` uses a hidden interactive terminal prompt, authenticates the submitted key without requesting generated output, and saves it outside the project for the current account. Noninteractive setup and key arguments are rejected; use the local dashboard password form instead.
+
+`ewai providers credentials grok status --json` returns safe source/presence/revision metadata. `check` explicitly authenticates the active credential. `remove --yes` removes only the saved copy; optional `--expected-revision` protects a previously inspected revision. Failed or stale replacement preserves the predecessor. `XAI_API_KEY` overrides saved credentials. Keys are never project YAML or provider-policy fields, and connection checks do not grant execution authority. See [storage and recovery](../operations/installation-updating-and-entitlements.md#private-grok-key-setup-and-recovery).
+
 ## Validation configuration
 
 ```bash

package/README.md

@@ -2,20 +2,33 @@
 
 Engineering With AI (EWAI) helps you plan, build and review software with an AI assistant. It gives the assistant a shared record of the project, a delivery workflow and checks against your engineering standards. You keep control of the decisions and approve implementation before it starts.
 
-## Beta: concise answers and useful decision guidance
+[![Intent Studio in the EWAI dashboard: describing a feature, agreeing its acceptance criteria and engaging specialist personas before any code is written](https://www.conversationalcoding.dev/wp-content/uploads/sites/5/2026/09/intent-studio-full-be7758ffd224-1536x704.webp)](https://www.conversationalcoding.dev/engineering-with-ai-harness/?utm_source=readme&utm_medium=referral&utm_campaign=ewai)
 
-Version `0.3.1-beta.0` adds communication guidance that prioritises correctness and usefulness, then brevity. Decision requests include action details, supporting guidance, a recommendation with its reason and a suggested response when useful. Query refinement leads with a recommended interpretation and explains consequential assumptions.
+**Website, guides and books:** [conversationalcoding.dev](https://www.conversationalcoding.dev/engineering-with-ai-harness/?utm_source=readme&utm_medium=referral&utm_campaign=ewai) · [Online documentation](https://www.conversationalcoding.dev/engineering-with-ai-harness/docs/?utm_source=readme&utm_medium=referral&utm_campaign=ewai) · [Persona library](https://www.conversationalcoding.dev/personas/?utm_source=readme&utm_medium=referral&utm_campaign=ewai)
 
-To try this beta in one project:
+## Quick start
+
+EWAI is free and works with Claude Code, Codex, Google Antigravity and Grok Build. You'll need Node.js 22.5 or newer and one of those assistants, installed and signed in.
 
 ```bash
-npm install --save-dev @thebackstoryis/engineering-with-ai@beta
-npx ewai
+npm install --global @thebackstoryis/engineering-with-ai
+cd /path/to/your/project
+ewai
 ```
 
-Initialisation or the next check-in refreshes EWAI's managed instructions in `AGENTS.md` and `CLAUDE.md`, preserving project-authored guidance outside that block. Start a fresh host conversation after the refresh. See [the user guide](Docs/context-management-and-token-efficiency.md#concise-answers-and-guided-decisions) for examples and [beta installation and recovery](Docs/operations/installation-updating-and-entitlements.md#try-the-beta-channel) for other installation choices.
+`ewai` opens your assistant and walks you through setting up the project. See [Install and start](#install-and-start) for details.
+
+Version `0.3.2` updates the package's links and documentation. The features below arrived in `0.3.1`.
+
+## New in 0.3.1: concise answers and Grok Build
+
+Version `0.3.1` makes EWAI's guidance more concise and adds Grok Build as a coding provider.
+
+**Concise answers and guided decisions.** EWAI's managed instructions now prioritise correctness and usefulness, then brevity. Expect the result or recommendation first, with less repetition and routine narration. Decision requests explain the action, options and consequences, then give a recommendation with its reason and a suggested response when useful. When a request is unclear, EWAI leads with its recommended interpretation and states the assumptions that matter. The guidance is designed to cut unnecessary output; tool-result compaction is still planned, and token or cost savings haven't been measured yet. See [concise answers and guided decisions](Docs/context-management-and-token-efficiency.md#concise-answers-and-guided-decisions).
+
+**Grok Build and coding provider settings.** EWAI can open Grok Build as a native companion, install its skills and set up project MCP. **Configuration → Coding providers** in the dashboard, or `ewai providers` in a terminal, lets you choose a primary coding CLI, independent reviewers and an eligible pool for unattended work. Each CLI keeps its own model choice by default. Grok can run isolated coding, read-only review and restricted proposal workers. Each mode passes an offline conformance check before dispatch, and your xAI key is saved privately outside the project. Build approval, required review and Manual QA stay with you. See [provider settings](Docs/reference/cli-and-configuration.md#coding-provider-settings) and [Grok Build setup](Docs/operations/installation-updating-and-entitlements.md#grok-build).
 
-This beta adds communication instructions and documentation. Tool-result compaction remains planned, and incremental token or cost savings have not been measured. Mandatory workflow and human approvals still apply. The production npm channel remains on `0.3.0`.
+After updating, initialisation or the next check-in refreshes EWAI's managed instructions in `AGENTS.md` and `CLAUDE.md`, preserving project-authored guidance outside that block. Start a fresh host conversation after the refresh.
 
 ## EWAI can now pick up the next ready piece of work
 
@@ -122,6 +135,8 @@ Premium personas are optional specialist perspectives. If you have a subscriptio
 - [Capabilities and project layout](Docs/reference/capabilities-and-project-layout.md)
 - [Commands and configuration](Docs/reference/cli-and-configuration.md)
 - [Troubleshooting and recovery](Docs/operations/troubleshooting-and-recovery.md)
+- [EWAI on the web: harness overview, online docs and changelog](https://www.conversationalcoding.dev/engineering-with-ai-harness/?utm_source=readme&utm_medium=referral&utm_campaign=ewai)
+- [Engineering With AI, the book behind the method](https://www.conversationalcoding.dev/books/?utm_source=readme&utm_medium=referral&utm_campaign=ewai)
 
 ## Contributing to EWAI
 

package/config/autonomy.schema.json

@@ -4,20 +4,85 @@
   "title": "Explicit autonomous intent delegation scope",
   "type": "object",
   "additionalProperties": false,
-  "required": ["intentIds", "actions", "providers", "expiresAt", "limits"],
+  "required": [
+    "intentIds",
+    "actions",
+    "providers",
+    "expiresAt",
+    "limits"
+  ],
   "properties": {
-    "intentIds": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*/[a-z0-9]+(?:-[a-z0-9]+)*$" } },
-    "actions": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["begin-harness", "prepare-phase", "afk-build"] } },
-    "providers": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["codex", "claude", "antigravity"] } },
-    "expiresAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d\\.\\d{3}Z$" },
+    "intentIds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 160,
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*/[a-z0-9]+(?:-[a-z0-9]+)*$"
+      }
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "begin-harness",
+          "prepare-phase",
+          "afk-build"
+        ]
+      }
+    },
+    "providers": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "codex",
+          "claude",
+          "antigravity",
+          "grok"
+        ]
+      }
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d\\.\\d{3}Z$"
+    },
     "limits": {
-      "type": "object", "additionalProperties": false,
-      "required": ["maxConcurrentIntents", "maxRuntimeMs", "maxOperationMs", "maxAttempts"],
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxConcurrentIntents",
+        "maxRuntimeMs",
+        "maxOperationMs",
+        "maxAttempts"
+      ],
       "properties": {
-        "maxConcurrentIntents": { "const": 1 },
-        "maxRuntimeMs": { "type": "integer", "minimum": 1, "maximum": 86400000 },
-        "maxOperationMs": { "type": "integer", "minimum": 1, "maximum": 86400000 },
-        "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 100 }
+        "maxConcurrentIntents": {
+          "const": 1
+        },
+        "maxRuntimeMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400000
+        },
+        "maxOperationMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400000
+        },
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        }
       },
       "$comment": "The domain additionally requires maxOperationMs <= maxRuntimeMs. No hard money or token cap is promised."
     }

package/config/project.schema.json

@@ -5,6 +5,24 @@
   "required": ["schema", "project", "specs", "repositories", "approvals", "validation"],
   "properties": {
     "schema": { "const": "ewai.project/v1" },
+    "coding_providers": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "pool": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "enum": ["claude", "codex", "grok", "antigravity"] } },
+        "primary": { "enum": ["existing", "auto", "claude", "codex", "grok", "antigravity"] },
+        "secondary": { "enum": ["existing", "auto", "off", "claude", "codex", "grok", "antigravity"] },
+        "tertiary": { "enum": ["existing", "auto", "off", "claude", "codex", "grok", "antigravity"] },
+        "models": {
+          "type": "object", "additionalProperties": false,
+          "properties": {
+            "claude": { "$ref": "#/$defs/codingModelPolicy" },
+            "codex": { "$ref": "#/$defs/codingModelPolicy" },
+            "grok": { "$ref": "#/$defs/codingModelPolicy" },
+            "antigravity": { "$ref": "#/$defs/codingModelPolicy" }
+          }
+        }
+      }
+    },
     "dashboard": {
       "type": "object",
       "additionalProperties": false,
@@ -165,6 +183,7 @@
               "properties": {
                 "claude": { "$ref": "#/$defs/provider" },
                 "codex": { "$ref": "#/$defs/provider" },
+                "grok": { "$ref": "#/$defs/provider" },
                 "antigravity": { "$ref": "#/$defs/provider" }
               },
               "additionalProperties": false
@@ -284,7 +303,7 @@
             {
               "type": "array",
               "uniqueItems": true,
-              "items": { "enum": ["claude", "codex", "antigravity"] }
+              "items": { "enum": ["claude", "codex", "antigravity", "grok"] }
             }
           ]
         },
@@ -308,6 +327,15 @@
         }
       },
       "additionalProperties": false
+    },
+    "codingModelPolicy": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "suggestion": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$" },
+        "permitted_models": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$" }
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebackstoryis/engineering-with-ai",
-  "version": "0.3.1-beta.0",
+  "version": "0.3.2",
   "description": "A human-centred, AI-augmented engineering pipeline",
   "license": "SEE LICENSE IN LICENSE",
   "author": "The Backstory Is",
@@ -10,13 +10,22 @@
     "specifications",
     "delivery-pipeline",
     "personas",
-    "mcp"
+    "mcp",
+    "ai-coding",
+    "claude-code",
+    "codex",
+    "grok",
+    "ai-agents",
+    "code-review",
+    "developer-tools",
+    "spec-driven-development",
+    "cli"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TheBackstoryIs/EngineeringWithAIHarness.git"
   },
-  "homepage": "https://github.com/TheBackstoryIs/EngineeringWithAIHarness#readme",
+  "homepage": "https://www.conversationalcoding.dev/engineering-with-ai-harness/?utm_source=npm&utm_medium=referral&utm_campaign=ewai",
   "bugs": {
     "url": "https://github.com/TheBackstoryIs/EngineeringWithAIHarness/issues"
   },
@@ -50,7 +59,7 @@
   },
   "scripts": {
     "build": "npm run check",
-    "precheck": "node scripts/publication-check.mjs --source-only && node --check src/runtime/tree-sitter-index.mjs && node --check src/design-system-application.mjs && node --check src/team-hub-resources.mjs && node --check src/dashboard-preferences.mjs && node --check public/dashboard-navigation.js",
+    "precheck": "node scripts/publication-check.mjs --source-only && node --check src/runtime/tree-sitter-index.mjs && node --check src/design-system-application.mjs && node --check src/team-hub-resources.mjs && node --check src/dashboard-preferences.mjs && node --check public/dashboard-navigation.js && node --check src/config-document.mjs && node --check src/coding-providers.mjs && node --check src/runtime/grok-provider.mjs && node --check public/coding-providers.js && node --check src/grok-credentials.mjs && node --check public/grok-credentials.js",
     "publication:check": "node scripts/publication-check.mjs",
     "prepack": "node scripts/publication-check.mjs --quiet",
     "check": "node --check src/error-reporting.mjs && node --check src/team-hub.mjs && node --check src/runtime/team-hub-client.mjs && node --check src/runtime/team-hub-database.mjs && node --check src/runtime/team-hub-server.mjs && node --check src/runtime/team-hub.mjs && node --check src/runtime/error-reporting.mjs && node --check src/launcher.mjs && node --check src/afk-worker.mjs && node --check src/companion-opening.mjs && node --check src/companion.mjs && node --check src/cli.mjs && node --check src/checkin.mjs && node --check src/persona-licence-config.mjs && node --check src/persona-website-provider.mjs && node --check src/persona-zip.mjs && node --check src/persona-entitlements.mjs && node --check src/context.mjs && node --check src/archaeology.mjs && node --check src/evidence-depth.mjs && node --check src/prototype-iterations.mjs && node --check src/solution-readiness.mjs && node --check src/delivery-artifacts.mjs && node --check src/delivery-documents.mjs && node --check src/delivery-gates.mjs && node --check src/delivery.mjs && node --check src/design-systems.mjs && node --check src/design-system-authoring.mjs && node --check src/execution-state.mjs && node --check src/intent-dependencies.mjs && node --check src/task-graph.mjs && node --check src/test-scenarios.mjs && node --check src/security-validation-config.mjs && node --check src/starter-materialisation-contract.mjs && node --check src/validation-config.mjs && node --check src/project.mjs && node --check src/install.mjs && node --check src/intents.mjs && node --check src/intent-maps.mjs && node --check src/discovery.mjs && node --check src/packs.mjs && node --check src/organisation-blueprints.mjs && node --check src/organisation-policies.mjs && node --check src/policy-design-gates.mjs && node --check src/policy-gate-integration.mjs && node --check src/personas.mjs && node --check src/platform-metadata-analysis.mjs && node --check src/power-platform-source-map.mjs && node --check src/salesforce-source-map.mjs && node --check src/repository-source-map.mjs && node --check src/runtime/context-assembly.mjs && node --check src/runtime/context-benchmarks.mjs && node --check src/runtime/database.mjs && node --check src/runtime/execution-leases.mjs && node --check src/runtime/provider-adapters.mjs && node --check src/runtime/security-validation.mjs && node --check src/runtime/starter-materialisation.mjs && node --check src/runtime/policy-workspace.mjs && node --check src/runtime/lifecycle-hooks.mjs && node --check src/runtime/afk-conductor.mjs && node --check src/runtime/dashboard-actions.mjs && node --check src/runtime/dashboard-handoffs.mjs && node --check src/runtime/persona-engagement.mjs && node --check src/runtime/evidence-depth-workspace.mjs && node --check src/runtime/prototype-iterations.mjs && node --check src/runtime/guided-discovery.mjs && node --check src/runtime/guided-intents.mjs && node --check src/runtime/phase-contributions.mjs && node --check src/runtime/impact-analysis.mjs && node --check src/runtime/paths.mjs && node --check src/runtime/intents.mjs && node --check src/runtime/knowledge.mjs && node --check src/runtime/palace.mjs && node --check src/runtime/repository-index.mjs && node --check src/runtime/runs.mjs && node --check src/runtime/work.mjs && node --check src/runtime/version.mjs && node --check src/runtime/dashboard.mjs && node --check src/runtime/dashboard-server.mjs && node --check src/runtime/mcp-config.mjs && node --check src/runtime/mcp-server.mjs && node --check src/autonomy.mjs && node --check src/autonomy-phase-contracts.mjs && node --check src/autonomy-worker.mjs && node --check src/runtime/autonomy-supervisor.mjs && node --check src/runtime/autonomy-operations.mjs && node --check src/runtime/autonomy-workers.mjs && node --check src/runtime/autonomy-workspace.mjs && node --check public/autonomy.js && node --check public/app.js && node --check public/team-hub/app.js && node --check scripts/setup.mjs",
@@ -64,6 +73,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "smol-toml": "^1.9.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-javascript": "^0.21.4",
     "tree-sitter-php": "^0.23.12",

package/public/autonomy.js

@@ -3,7 +3,7 @@
 const $ = id => document.getElementById(id);
 const view = { status: null, preview: null, draftPreview: null, draftIds: new Set(), poolSignature: '',
   draftTouched: false, draftHydrated: false, loading: false, busy: false, dispatching: false,
-  resuming: new Set(), error: '', notice: '', requestRevision: 0, control: null, answer: null, runIntentId: '' };
+  resuming: new Set(), error: '', notice: '', requestRevision: 0, control: null, answer: null, runIntentId: '', codingPolicy:null };
 let host = null;
 
 function node(tag, content = '', className = '') {
@@ -40,6 +40,8 @@ function safeError(error) {
     || code === 'autonomy-policy-stale') return 'The evidence changed. Refresh and review the current state before trying again.';
   if (code === 'autonomy-repository-dirty') return 'The repository has uncommitted work. Resolve it before dispatch.';
   if (code === 'autonomy-canonical-decision-required') return 'A named human decision is required before this run can continue.';
+  if (code === 'autonomy-model-restriction-unsupported') return 'This CLI cannot enforce the permitted-model list. Recommended: clear that restriction for native model selection, or use a verified enforcing adapter, then review a fresh grant.';
+  if (code === 'autonomy-provider-unavailable') return 'No eligible provider can perform this action. Recommended: enable an installed provider inside the saved and approved pools, then repeat preflight. Grok requires its supported native version and mode conformance.';
   return /^autonomy-[a-z0-9-]+$/.test(code ?? '') ? `EWAI stopped at ${humanReason(code)}. Refresh and inspect the recorded prerequisite.`
     : 'Autonomy is unavailable. Refresh the dashboard and inspect the project checks.';
 }
@@ -77,6 +79,7 @@ function selectedProposal() {
   const intents = [...view.draftIds].sort();
   const actions = [...document.querySelectorAll('[name="autonomyAction"][aria-checked="true"]')].map(input => input.value);
   const provider = $('autonomyProvider').value;
+  if(provider==='auto'&&!view.codingPolicy?.pool?.length)throw new Error('Save a coding provider pool first, then preview the exact providers for this grant.');
   const hours = Number($('autonomyExpiryHours').value), runtimeMinutes = Number($('autonomyRuntimeMinutes').value);
   const operationSeconds = Number($('autonomyOperationSeconds').value), attempts = Number($('autonomyAttempts').value);
   if (!intents.length || !actions.length || !Number.isSafeInteger(hours) || hours < 1 || hours > 24
@@ -85,7 +88,7 @@ function selectedProposal() {
     || operationSeconds > runtimeMinutes * 60 || !Number.isSafeInteger(attempts) || attempts < 1 || attempts > 100) {
     throw new Error('Choose at least one exact intent and action, then enter valid expiry and limits.');
   }
-  return { intentIds: intents, actions, providers: [provider], expiresAt: new Date(Date.now() + hours * 3600000).toISOString(),
+  return { intentIds: intents, actions, providers: provider==='auto'?[...view.codingPolicy.pool]:[provider], expiresAt: new Date(Date.now() + hours * 3600000).toISOString(),
     limits: { maxConcurrentIntents: 1, maxRuntimeMs: runtimeMinutes * 60000, maxOperationMs: operationSeconds * 1000, maxAttempts: attempts } };
 }
 function grantSummary(scope) {
@@ -243,7 +246,7 @@ function openDialog(id, opener, focusId) {
 function openDispatch(intentId, opener) {
   if (view.status?.status !== 'current' || view.preview?.executable[0]?.intentId !== intentId) return;
   view.runIntentId = intentId;
-  view.dispatch = { intentId, grantDigest: view.status.grant.digest, provider: view.status.grant.scope.providers[0] };
+  view.dispatch = { intentId, grantDigest: view.status.grant.digest, provider: view.status.grant.scope.providers.length>1?'auto':view.status.grant.scope.providers[0] };
   set('autonomyDispatchSummary', `${titleFor(intentId)} is next by recorded priority. ${grantSummary(view.status.grant.scope)}`);
   openDialog('autonomyDispatchDialog', opener, 'autonomyDispatchMode');
 }
@@ -308,7 +311,7 @@ export async function loadAutonomyState() {
         button.setAttribute('aria-checked', String(scope.actions.includes(button.value)));
       }
       if ([...$('autonomyProvider').options].some(option => option.value === scope.providers[0])) {
-        $('autonomyProvider').value = scope.providers[0];
+        $('autonomyProvider').value = scope.providers.length>1?'auto':scope.providers[0];
       }
       $('autonomyRuntimeMinutes').value = String(Math.round(scope.limits.maxRuntimeMs / 60000));
       $('autonomyOperationSeconds').value = String(Math.round(scope.limits.maxOperationMs / 1000));
@@ -339,6 +342,9 @@ export async function loadAutonomyState() {
 export function configureAutonomyDashboard(options) {
   host = options;
   $('autonomyPreviewButton').addEventListener('click', () => perform(async () => {
+    // Provider settings can be saved in the same dashboard without a reload.
+    // Review the current exact pool, never an earlier form-load snapshot.
+    view.codingPolicy = (await host.api('/api/coding-providers')).policy;
     const proposal = selectedProposal();
     view.draftPreview = await mutation('preview', { proposal, record: false, confirmed: false });
     view.notice = 'Preview only. No grant or provider has started.';