@thebackstoryis/engineering-with-ai 0.3.0 → 0.3.1

package/Docs/README.md

@@ -30,6 +30,8 @@ If you have a persona licence, [set it up before the analysis](operations/premiu
 
 If you're contributing without an engineering background, use the [non-technical team guide](adoption/non-technical-team-guide.md). For examples of the wider workflow, see [worked examples](examples/worked-examples.md).
 
+To try the beta communication guidance, read [concise answers and guided decisions](context-management-and-token-efficiency.md#concise-answers-and-guided-decisions), including examples and installation instructions.
+
 ## Make the dashboard work for you
 
 [Choose which views you need](operations/dashboard-configuration.md). Portfolio, Team Hub, policy tools and the other advanced views are optional and start hidden. Showing a view doesn't configure the service behind it; hiding one doesn't remove checks your project requires.

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

@@ -6,6 +6,48 @@ You normally don't prepare context manually: the relevant EWAI skill does that f
 
 Context preparation doesn't approve Build or Manual QA, accept risk, certify quality, deploy or release.
 
+## Concise answers and guided decisions
+
+**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
+
+Describe the result you need, for example:
+
+> “Give me the result and next action concisely. Keep the evidence, exact commands, important risks and anything you couldn't verify.”
+
+The guidance prioritises correctness and usefulness, then brevity. Expect the result or recommendation first, with less repetition and routine narration. Required status, warnings and approval steps still appear. A short answer should retain prerequisites, meaningful action order, failures and uncertainty; it should not replace working instructions with shorthand.
+
+When you need more detail, ask for it:
+
+> “Expand the migration steps, including prerequisites, verification and recovery.”
+
+Detailed requests still need complete answers. If a concise answer leaves you unable to act safely or understand the evidence, ask for the missing detail before acting.
+
+### Make an informed decision
+
+A decision request should explain the action, consequences, material options and tradeoffs, then give a recommendation with its reason. A suggested response can help you express your choice; it does not record approval on your behalf.
+
+You can ask:
+
+> “Explain what I need to decide, recommend an option with its reason, and suggest a reply. Include what happens next and any uncertainty.”
+
+When the evidence cannot support a choice, expect a recommendation for the next evidence-gathering step. Build approval, Manual QA and release decisions still need their own explicit authority; see [who approves what](human-approval-and-assurance-guide.md).
+
+### Refine an unclear request
+
+The guidance leads with a recommended interpretation and explains assumptions that affect the outcome. It asks one focused question when missing information materially changes the scope or next action, with guidance and a recommended response.
+
+For example, if you say “Make onboarding simpler”, an illustrative response is:
+
+> “I recommend reviewing the existing onboarding journey first to identify where people get stuck. I'm assuming you want the journey assessed before changing the implementation. Should we start with that review? Suggested response: ‘Yes, review the journey first and recommend changes.’”
+
+Correct the interpretation when it misses your intent. Work already authorised and independent of your answer can continue; a proposed interpretation or suggested reply does not expand that authority.
+
+### Understand savings claims
+
+Shorter replies aim to reduce output tokens. The context preparation described below addresses input tokens. Neither a shorter example nor the packaged context benchmark establishes whole-session cost savings. Assess equivalent work using actual provider usage where available, including retries and clarification rounds, alongside correctness and how well the answer supports your decision. Unknown usage remains unknown.
+
 ## Inspect the evidence sent to the model
 
 Open **Configuration**, enable **AI context diagnostics** and save, then open that view in the sidebar. See [dashboard configuration](operations/dashboard-configuration.md) if you need help finding it.

package/Docs/guide-catalogue.md

@@ -20,6 +20,7 @@ Choose the section that matches your job. The optional team tools aren't prerequ
 - [Facilitate project Discovery](guided-discovery-facilitator-guide.md)
 - [Create or revise an intent in Intent Studio](guided-intent-workspace-guide.md)
 - [Choose work with the Companion](context-aware-delivery-companion-user-guide.md)
+- [Get concise answers and useful decision guidance (beta)](context-management-and-token-efficiency.md#concise-answers-and-guided-decisions)
 - [Delegate an exact pool of intents with guarded autonomy](autonomous-intent-delivery.md)
 - [Contribute information to work in progress](guided-phase-evidence-drafting-guide.md)
 - [Review evidence from meeting notes or transcripts](meeting-evidence-user-guide.md)

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

@@ -46,6 +46,23 @@ npx --yes @thebackstoryis/engineering-with-ai@latest
 
 This asks npm to obtain and run the package. It doesn't create a standing global installation.
 
+## Try the beta channel
+
+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:
+
+```bash
+npm install --save-dev @thebackstoryis/engineering-with-ai@beta
+npx ewai
+```
+
+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.
+
+Beta check-in offers updates from the beta channel. To return to production deliberately, install `@latest` using the same project-local or global scope, then run that version's check-in and start a fresh conversation. Review the instruction changes and use [dashboard recovery](troubleshooting-and-recovery.md#dashboard-will-not-start) if an older runtime is still running. Returning to production does not undo work already performed in your application.
+
 ## Start your project
 
 Open your project folder in the host and start EWAI. Agree where its SPECS folder should live before initialising it. For existing code, EWAI offers Archaeology to reconstruct missing project knowledge; you can accept or decline it.
@@ -108,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,6 +2,16 @@
 
 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.
 
+## 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).
+
+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
 
 If you’ve prepared several work items, you can choose which ones EWAI is allowed to take on. EWAI checks what’s ready, uses the priorities you’ve recorded to pick the next item, and starts its delivery workflow. Once you’ve separately approved the Build, it can run the approved build tasks, their tests and a fresh review.

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.0",
+  "version": "0.3.1",
   "description": "A human-centred, AI-augmented engineering pipeline",
   "license": "SEE LICENSE IN LICENSE",
   "author": "The Backstory Is",
@@ -50,7 +50,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 +64,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.';