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

package/public/grok-credentials.js

@@ -0,0 +1,42 @@
+const element=id=>document.getElementById(id),form=element('grokCredentialForm'),field=element('grokCredentialKey');
+let saved=null,busy=false;
+function controls(){
+ field.disabled=busy||!saved||!saved.storageSupported;
+ element('grokCredentialSave').disabled=field.disabled;
+ element('grokCredentialCancel').disabled=busy;
+ element('grokCredentialCheck').disabled=busy||!saved?.configured;
+ element('grokCredentialRemove').disabled=busy||!saved?.saved;
+ element('grokCredentialRefresh').disabled=busy;
+}
+function adopt(data){
+ saved=data;
+ element('grokCredentialStatus').textContent=data.source==='environment'?'Using XAI_API_KEY from the launching environment. '+(data.saved?'A saved key is also available.':'No saved key.'):
+  data.source==='saved'?'Saved Grok key available for this account.':'No Grok key configured. Recommended: check and save a key below.';
+ if(data.storageSupported===false)element('grokCredentialStatus').textContent+=' Local key storage is unavailable on this platform; use the launching environment.';
+ controls();
+}
+async function request(action='',body){
+ const response=await fetch('/api/coding-providers/grok/credentials'+(action?'/'+action:''),{method:action?'POST':'GET',headers:action?{'content-type':'application/json'}:undefined,body:action?JSON.stringify(body):undefined});
+ let data;try{data=await response.json();}catch{throw Error('Credential setup could not be reached. Recheck the local dashboard connection.');}
+ if(!response.ok)throw Error(data.error??'Credential setup failed. Refresh status and try again.');return data;
+}
+async function load(){
+ busy=true;controls();
+ try{adopt(await request());}catch{saved=null;element('grokCredentialNotice').textContent='Credential status could not be read safely. Repair private storage or use XAI_API_KEY in the launching environment, then refresh.';}
+ finally{busy=false;controls();}
+}
+async function action(name){
+ if(busy||!saved)return;
+ const body={confirmed:true,...(name==='check'?{}:{expectedRevision:saved.revision}),...(name==='configure'?{apiKey:field.value}:{})};
+ field.value='';busy=true;controls();element('grokCredentialNotice').textContent=name==='remove'?'Removing saved key…':'Checking xAI authentication without generated output…';
+ try{const result=await request(name,body);adopt(result);element('grokCredentialNotice').textContent=result.message;}
+ catch(error){element('grokCredentialNotice').textContent=error.message+' Refresh status before trying again.';}
+ finally{body.apiKey=undefined;field.value='';busy=false;controls();}
+}
+form.addEventListener('submit',event=>{event.preventDefault();void action('configure');});
+element('grokCredentialCancel').addEventListener('click',()=>{field.value='';element('grokCredentialNotice').textContent='Cancelled. Saved key retained.';});
+element('grokCredentialCheck').addEventListener('click',()=>void action('check'));
+element('grokCredentialRemove').addEventListener('click',()=>void action('remove'));
+element('grokCredentialRefresh').addEventListener('click',()=>{field.value='';element('grokCredentialNotice').textContent='';void load();});
+window.addEventListener('pagehide',()=>{field.value='';});
+controls();void load();

package/public/index.html

@@ -53,13 +53,46 @@
         <header class="configuration-heading"><h2>Make this dashboard work for you.</h2><p>Keep the everyday tools. Add the extra views when your project needs them.</p></header>
         <form id="dashboardPreferencesForm"><div id="dashboardPreferenceGroups"></div><div class="configuration-save"><button id="saveDashboardPreferences" type="submit" class="primary-action" disabled>Save changes</button><button id="cancelDashboardPreferences" type="button" class="quiet-button">Cancel</button><output id="dashboardPreferenceStatus" aria-live="polite"></output></div></form>
         <p class="configuration-assurance">These settings only change what’s shown. Your standards, required checks and approvals still apply. Turning on a view won’t run a scan, connect a team service or install anything.</p>
+        <section class="configuration-group coding-providers" aria-labelledby="codingProvidersTitle">
+          <header><div><h3 id="codingProvidersTitle">Coding providers</h3><p>Choose who codes and who reviews. Recommended: let each CLI choose its own model.</p></div></header>
+          <form id="codingProvidersForm" class="coding-providers-body">
+            <div class="coding-provider-notice"><strong>Models are chosen by your CLI</strong><p>Existing host selection and required reviews continue until you save a new provider policy. Saving does not start work.</p></div>
+            <div id="codingProviderRoles" class="coding-provider-grid"></div>
+            <fieldset><legend>Eligible provider pool</legend><div id="codingProviderPool" class="coding-provider-pool"></div><p id="codingProviderAvailability"></p></fieldset>
+            <details><summary>Optional model suggestions and restrictions</summary><p>Leave these blank for native CLI selection. Suggestions are advisory. A permitted-model list stops execution when enforcement is unsupported. This does not cap tokens or spending.</p>
+              <label>Provider to configure<select id="codingModelProvider"></select></label>
+              <div class="coding-model-grid"><label>Suggested model ID (optional)<input id="codingModelSuggestion" maxlength="128" autocomplete="off"><small>Guidance without a forced model override.</small></label><label>Permitted model IDs (optional)<textarea id="codingModelPermitted" rows="3" autocomplete="off"></textarea><small>One exact provider-specific ID per line. No wildcards or inferred ranking.</small></label></div>
+              <p id="codingModelStatus" role="status"></p>
+            </details>
+            <div id="codingProviderPreview" class="coding-provider-preview" aria-live="polite"></div>
+            <div class="coding-provider-actions"><button id="codingProviderSave" type="submit" class="primary-action" disabled>Save provider settings</button><button id="codingProviderCancel" type="button" class="quiet-button" disabled>Cancel changes</button><button id="codingProviderDefaults" type="button" class="quiet-button" disabled>Restore existing behaviour</button><button id="codingProviderAuto" type="button" class="quiet-button" disabled>Choose automatically</button></div>
+            <output id="codingProviderStatus" role="status" aria-live="polite">Loading provider settings…</output>
+            <div id="codingProviderConflict" hidden><p id="codingProviderLatest"></p><button id="codingProviderCompare" type="button" class="quiet-button">Compare latest settings</button><button id="codingProviderRebase" type="button" class="quiet-button" hidden>Keep my draft against these settings</button></div>
+            <p>Automatic selection uses installed, enabled providers inside the approved delivery pool. Required checks, independent review and human approvals still apply. Grok unattended modes require separate conformance.</p>
+          </form>
+        </section>
+        <section class="configuration-group grok-credentials" aria-labelledby="grokCredentialsTitle">
+          <header><div><h3 id="grokCredentialsTitle">Grok Build credentials</h3><p>Use your xAI API key for automated coding and review. Interactive Grok Build keeps its own login.</p></div></header>
+          <div class="grok-credentials-body">
+            <p id="grokCredentialStatus" role="status">Checking credential status…</p>
+            <form id="grokCredentialForm">
+              <label for="grokCredentialKey">xAI API key</label>
+              <input id="grokCredentialKey" type="password" autocomplete="off" spellcheck="false" autocapitalize="off" maxlength="512" required aria-describedby="grokCredentialHelp" disabled>
+              <p id="grokCredentialHelp">Saved for your account on this computer, across EWAI projects, outside the project in an owner-only local file. The stored key is not encrypted. XAI_API_KEY overrides it.</p>
+              <div class="coding-provider-actions"><button id="grokCredentialSave" type="submit" class="primary-action" disabled>Check and save key</button><button id="grokCredentialCancel" type="button" class="quiet-button" disabled>Cancel key entry</button></div>
+            </form>
+            <div class="coding-provider-actions"><button id="grokCredentialCheck" type="button" class="quiet-button" disabled>Check connection</button><button id="grokCredentialRemove" type="button" class="quiet-button" disabled>Remove saved key</button><button id="grokCredentialRefresh" type="button" class="quiet-button">Refresh status</button></div>
+            <p>Checking authenticates with xAI without generating output. It does not prove available credit or coding readiness. Saving a key does not start work.</p>
+            <output id="grokCredentialNotice" role="status" aria-live="polite"></output>
+          </div>
+        </section>
         <section class="configuration-group autonomy-configuration" aria-labelledby="autonomyConfigurationTitle">
           <header><div><h3 id="autonomyConfigurationTitle">Delegated delivery</h3><p>Choose an exact pool and limits. EWAI can progress only permitted work between your decisions.</p></div><strong id="autonomyMode" class="autonomy-mode">Checking…</strong></header>
           <div class="autonomy-configuration-body">
             <fieldset class="autonomy-pool-field"><legend>Exact intent pool</legend><p>Only the intents you select can enter this grant.</p><div id="autonomyPool" class="autonomy-pool" aria-live="polite">Loading project intents…</div></fieldset>
             <fieldset class="autonomy-actions-field"><legend>Permitted progress</legend><button type="button" role="checkbox" aria-checked="true" name="autonomyAction" value="begin-harness">Begin a ready intent</button><button type="button" role="checkbox" aria-checked="false" name="autonomyAction" value="prepare-phase">Prepare a governed phase</button><button type="button" role="checkbox" aria-checked="false" name="autonomyAction" value="afk-build">Continue approved Build work</button></fieldset>
             <div class="autonomy-limits">
-              <label>Provider<select id="autonomyProvider"><option value="codex">Codex</option><option value="claude">Claude</option><option value="antigravity">Antigravity</option></select></label>
+              <label>Provider<select id="autonomyProvider"><option value="codex">Codex</option><option value="claude">Claude</option><option value="antigravity">Antigravity</option><option value="grok">Grok Build</option><option value="auto">Automatic from saved provider pool</option></select></label>
               <label>New grant expires after, hours<input id="autonomyExpiryHours" type="number" min="1" max="24" value="2" inputmode="numeric"></label>
               <label>Run limit, minutes<input id="autonomyRuntimeMinutes" type="number" min="1" max="1440" value="30" inputmode="numeric"></label>
               <label>Operation limit, seconds<input id="autonomyOperationSeconds" type="number" min="1" max="3600" value="900" inputmode="numeric"></label>
@@ -811,5 +844,7 @@
       </form>
     </dialog>
     <script src="/app.js" type="module"></script>
+    <script src="/coding-providers.js" type="module"></script>
+    <script src="/grok-credentials.js" type="module"></script>
   </body>
 </html>

package/public/styles.css

@@ -2736,6 +2736,27 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
 .autonomy-candidate p, .autonomy-run p, .autonomy-empty p { margin: 10px 0; line-height: 1.5; }
 .autonomy-question-context { padding: 10px 12px; border-left: 3px solid var(--amber); background: var(--amber-soft); color: var(--ink); overflow-wrap: anywhere; }
 .autonomy-reasons { color: var(--amber); font-weight: 700; }
+.coding-providers-body { padding: 24px; display: grid; gap: 20px; }
+.coding-provider-notice, .coding-provider-preview { padding: 16px; border-left: 3px solid var(--green); background: var(--surface-2); }
+.coding-providers p { overflow-wrap: anywhere; }
+.coding-provider-notice p { margin-bottom: 0; }
+.coding-provider-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 16px; }
+.coding-providers label { display: grid; gap: 8px; font-weight: 700; min-width: 0; }
+.coding-providers small { font-weight: 400; color: var(--muted); }
+.coding-providers input, .coding-providers select, .coding-providers textarea { width: 100%; min-width: 0; min-height: 44px; padding: 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--surface); color: var(--ink); font: inherit; }
+.coding-providers textarea { resize: vertical; }
+.coding-provider-pool { display: flex; flex-wrap: wrap; gap: 20px; }
+.coding-provider-pool label { display: flex; align-items: center; min-height: 44px; }
+.coding-provider-pool input { width: 18px; min-height: 18px; }
+.coding-provider-pool button { min-height: 44px; padding: 8px 12px; border: 1px solid var(--line); border-radius: 6px; background: var(--surface); color: var(--ink); font: inherit; cursor: pointer; }
+.coding-provider-pool button::before { content: '□'; margin-right: 8px; }
+.coding-provider-pool button[aria-checked=true]::before { content: '✓'; color: var(--green); }
+.coding-model-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-top: 16px; }
+.coding-providers summary { cursor: pointer; min-height: 44px; font-weight: 700; }
+.coding-provider-actions { display: flex; flex-wrap: wrap; gap: 10px; }
+.coding-providers output { display: block; overflow-wrap: anywhere; }
+.coding-providers :focus-visible { outline: 3px solid var(--blue); outline-offset: 2px; }
+@media (max-width: 720px) { .coding-providers-body { padding: 18px; } .coding-provider-grid, .coding-model-grid { grid-template-columns: minmax(0, 1fr); } .coding-provider-actions button { flex-grow: 1; } }
 .autonomy-candidate .autonomy-card-actions, .autonomy-run .autonomy-card-actions { margin-top: 12px; }
 .autonomy-intent-detail { margin-top: 18px; padding: 16px; border-left: 4px solid var(--green); background: var(--surface-2); }
 .autonomy-intent-detail h3 { margin: 0 0 7px; }
@@ -2755,3 +2776,7 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
   .autonomy-button-row button { width: 100%; }
   .autonomy-dialog .action-sheet > footer { flex-wrap: wrap; }
 }
+.grok-credentials-body { padding: 18px; display: grid; gap: 14px; }
+.grok-credentials-body form { display: grid; gap: 12px; }
+.grok-credentials-body input { width: 100%; box-sizing: border-box; min-height: 40px; border: 1px solid var(--line, #cfd8d5); border-radius: 6px; padding: 8px 10px; }
+.grok-credentials-body p { margin: 0; }

package/skills-src/ewai-context/SKILL.md

@@ -49,6 +49,7 @@ Personas are advisory lenses. They are not user evidence, specialist validation,
 - The loopback dashboard receives only a body-free safe manifest.
 - Never accept a browser-supplied project root, file path, provider command, executable, or credential.
 - Keep estimated input usage clearly separate from optional provider-reported usage.
+- Preserve captured coding-provider policy and the actual coding-agent identity when preparing task/review context. Model suggestions are advisory; never replace native model choice or bypass an unsupported permitted-model boundary to save tokens. Concision must retain decisions, supporting guidance, recommended actions and mandatory evidence.
 - Context preparation cannot approve Build or Manual QA, certify quality, accept security risk, deploy, or release.
 
 ## Verify engineering performance

package/skills-src/ewai-deliver/SKILL.md

@@ -19,7 +19,9 @@ Preserve all fourteen stages, the UI Design and FitCheck adjuncts, shelf/resume
 
 ## Start and resume
 
-For new delivery, call `ewai_delivery_begin` (or `ewai delivery begin`) for an existing project-owned intent and identify the current host as `tool`/`--tool` (`claude`, `codex`, or `antigravity`). Antigravity is invoked through the `agy` CLI. That value defines the orchestrator exclusion boundary. For continuing work, call `ewai_delivery_continue` first. Never reconstruct the next phase from chat memory.
+For new delivery, call `ewai_delivery_begin` (or `ewai delivery begin`) for an existing project-owned intent and identify the current host as `tool`/`--tool` (`claude`, `codex`, `grok`, or `antigravity`). Antigravity is invoked through the `agy` CLI. That value defines the orchestrator exclusion boundary. For continuing work, call `ewai_delivery_continue` first. Never reconstruct the next phase from chat memory.
+
+Optional coding-provider settings select the primary agent and distinct secondary/tertiary reviewers. Native model choice is the default; suggestions are advisory. Stop before invocation when permitted-model enforcement is unsupported. Automatic selection must intersect saved pools, configured capabilities and approved grants; settings never grant Build or Manual QA authority. Grok coding, review and proposal modes require their own verified native identity/conformance and private environment authentication. Keep an incomplete or unconfirmed mode visible and recommend a concrete recovery action.
 
 Before substantial repository navigation or truth claims, call `ewai_index_status`; refresh with `ewai_index_refresh` when the index is missing or stale. Use `ewai_index_search` and `ewai_index_graph` for navigation and blast-radius evidence, then verify material claims against source files.
 

package/skills-src/ewai-pipeline/SKILL.md

@@ -124,6 +124,7 @@ Do not relocate or overwrite an existing SPECS contract through init. Relocation
 - Require human approval before Build when `approvals.build` is `required`.
 - Read the full `validation` contract before scheduling review. Do not infer availability from global machine state, and do not use the active Claude, Codex, or Antigravity orchestrator as its own independent validator.
 - Honour each checkpoint's selected providers, maximum cycles, breadth, depth, and output limit. Standards compliance remains mandatory even when no independent external validator is configured.
+- Use the shared `ewai providers` policy for optional Claude Code, Codex, Grok Build and Antigravity coding/review roles. Keep native model choice by default; suggestions are advisory and unsupported permitted-model restrictions stop dispatch. Automatic selection remains inside configured capability and approved grant pools. Distinguish installed CLI, authenticated account and verified execution mode.
 - Never write project outputs into the global EWAI installation.
 - Never carry repository paths or project state from one project into another.
 

package/src/autonomy.mjs

@@ -5,7 +5,7 @@ import { autonomyError, autonomyGuard, autonomyDigest, autonomyPaths, autonomyFi
   writeAutonomyRecord, withAutonomyLock, readAutonomySnapshot } from './runtime/autonomy-workspace.mjs';
 
 export const AUTONOMY_ACTIONS = Object.freeze(['begin-harness', 'prepare-phase', 'afk-build']);
-export const AUTONOMY_PROVIDERS = Object.freeze(['codex', 'claude', 'antigravity']);
+export const AUTONOMY_PROVIDERS = Object.freeze(['codex', 'claude', 'antigravity', 'grok']);
 export const AUTONOMY_HUMAN_EXCLUSIONS = Object.freeze(['approve-build', 'select-prototype', 'manual-qa', 'accept-risk', 'policy-exception', 'destructive-action', 'deploy', 'release']);
 const intentPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const digestPattern = /^sha256:[a-f0-9]{64}$/;

package/src/cli.mjs

@@ -32,6 +32,8 @@ import {
 } from './design-systems.mjs';
 import { installDesignSystemCandidate, validateDesignSystemCandidate } from './design-system-authoring.mjs';
 import { applyDesignSystem } from './design-system-application.mjs';
+import {readCodingProviders,saveCodingProviders} from './coding-providers.mjs';
+import {grokCredentialStatus,configureGrokCredentials,checkGrokConnection,removeGrokCredentials} from './grok-credentials.mjs';
 import {
   createPersona,
   indexPersonas,
@@ -493,8 +495,13 @@ function usage() {
   return `EWAI Pipeline
 
 Commands:
-  ewai install [--project PATH] [--host auto|codex|claude|antigravity] [--mode copy|link]
-  ewai init [--project PATH] [--name NAME] [--specs PATH] [--init-specs-repo] [--claude] [--codex] [--antigravity] [--force]
+  ewai install [--project PATH] [--host auto|codex|claude|grok|antigravity] [--mode copy|link]
+  ewai providers show|set|auto|defaults [--project PATH] [--json]
+  ewai providers set [--primary PROVIDER|auto|existing] [--secondary PROVIDER|auto|off|existing] [--tertiary PROVIDER|auto|off|existing] [--pool LIST] [--input FILE] [--expected-digest DIGEST]
+  ewai providers model PROVIDER [--suggest MODEL_ID] [--allow-model MODEL_ID] [--clear-suggestion] [--clear-restriction]
+  ewai providers credentials grok status|configure|check|remove [--project PATH] [--json]
+  ewai providers credentials grok remove --yes [--expected-revision REVISION]
+  ewai init [--project PATH] [--name NAME] [--specs PATH] [--init-specs-repo] [--claude] [--codex] [--grok] [--antigravity] [--force]
   ewai checkin [--project PATH]
   ewai dashboard [--project PATH]
   ewai dashboard preferences [--project PATH] [--json]
@@ -502,7 +509,7 @@ Commands:
   ewai autonomy preview [--intent DOMAIN/SLUG --action ACTION --provider PROVIDER --expires-at ISO --max-runtime-ms N --max-operation-ms N --max-attempts N --record] [--project PATH] [--json]
   ewai autonomy approve --expected-digest DIGEST --approved-by NAME --yes [--project PATH] [--json]
   ewai autonomy revoke --expected-digest DIGEST --revoked-by NAME --yes [--project PATH] [--json]
-  ewai autonomy run|service --expected-digest DIGEST --provider PROVIDER --yes [--project PATH] [--json]
+  ewai autonomy run|service --expected-digest DIGEST --provider PROVIDER|auto --yes [--project PATH] [--json]
   ewai autonomy pause|resume|cancel|recover --run ID --expected-revision N --yes [--project PATH] [--json]
   ewai autonomy control --action pause|resume|cancel|revoke|recover --run ID --expected-revision N --yes [--revoked-by NAME] [--project PATH] [--json]
   ewai autonomy answer --input PROJECT_RELATIVE_JSON --yes [--project PATH] [--json]
@@ -569,8 +576,8 @@ Commands:
   ewai archaeology prepare-review BUNDLE [--project PATH] [--force]
   ewai archaeology curate BUNDLE [--project PATH] --yes [--approved-by NAME]
   ewai archaeology validate-completion BUNDLE [--project PATH]
-  ewai validation list [--project PATH] [--orchestrator manual|claude|codex|antigravity]
-  ewai validation set claude|codex|antigravity available|unavailable [--enabled|--disabled] [--project PATH]
+  ewai validation list [--project PATH] [--orchestrator manual|claude|codex|grok|antigravity]
+  ewai validation set claude|codex|grok|antigravity available|unavailable [--enabled|--disabled] [--project PATH]
   ewai validation checkpoint implementation-plan|test-plan|code [--cycles N] [--validators auto|PROVIDER,...] [--breadth targeted|change-set|capability|system] [--depth issues-only|issues-and-fixes|analysis-and-recommendations] [--output small|medium|large] [--enabled|--disabled] [--project PATH]
   ewai security status|providers|adapters|runs|findings|dispositions [--project PATH]
   ewai security adapter-validate FOLDER [--project PATH]
@@ -613,13 +620,13 @@ Commands:
   ewai delivery phase-complete SLUG PHASE [--artefact PATH] [--project PATH]
   ewai delivery ratify-amendments SLUG --yes --approved-by NAME --scope TEXT [--project PATH]
   ewai delivery evidence-amendment SLUG [--yes --approved-by NAME --reason TEXT --expected-state-digest DIGEST] [--project PATH]
-  ewai delivery validation-cycle SLUG PHASE --provider claude|codex|antigravity --outcome pass|issues [--response PATH] [--fix PATH] [--notes TEXT] [--project PATH]
+  ewai delivery validation-cycle SLUG PHASE --provider claude|codex|grok|antigravity --outcome pass|issues [--response PATH] [--fix PATH] [--notes TEXT] [--project PATH]
   ewai delivery approve-build SLUG --yes --approved-by NAME [--scope TEXT] [--project PATH]
   ewai delivery approve-manual-qa SLUG --yes --approved-by NAME --evidence PATH [--notes TEXT] [--project PATH]
   ewai delivery runs [SLUG] [--project PATH]
   ewai delivery runs --mark-stale [--hours N] [--project PATH]
-  ewai afk preflight SLUG [--provider auto|claude|codex|antigravity] [--parallel N] [--project PATH]
-  ewai afk start SLUG [--provider auto|claude|codex|antigravity] [--parallel N] [--timeout-minutes N] [--project PATH]
+  ewai afk preflight SLUG [--provider auto|claude|codex|grok|antigravity] [--parallel N] [--project PATH]
+  ewai afk start SLUG [--provider auto|claude|codex|grok|antigravity] [--parallel N] [--timeout-minutes N] [--project PATH]
   ewai afk status [RUN_ID] [--project PATH]
   ewai afk pause RUN_ID [--project PATH]
   ewai afk resume RUN_ID [--project PATH]
@@ -836,7 +843,7 @@ export async function run(args) {
         name: option(args, '--name'),
         specsRoot: option(args, '--specs') || undefined,
         initSpecsRepository: has(args, '--init-specs-repo'),
-        validators: ['claude', 'codex', 'antigravity'].filter((validator) => has(args, `--${validator}`)),
+        validators: ['claude', 'codex', 'grok', 'antigravity'].filter((validator) => has(args, `--${validator}`)),
         force: has(args, '--force')
       });
       print(json ? result : formatInitResult(result), json);
@@ -902,6 +909,59 @@ export async function run(args) {
       print(json ? result : JSON.stringify(result, null, 2), json); return;
     }
 
+    if(command==='providers'&&subcommand==='credentials'){
+      const action=args[3];
+      if(args[2]!=='grok'||!['status','configure','check','remove'].includes(action))throw new Error('Choose providers credentials grok status, configure, check or remove.');
+      const allowedValues=['--project',...(action==='remove'?['--expected-revision']:[])],allowedFlags=['--json',...(action==='remove'?['--yes']:[])];
+      for(let i=4;i<args.length;i++){
+        if(allowedValues.includes(args[i])){if(!args[i+1]||args[i+1].startsWith('--'))throw new Error('A credential option requires a value.');i++;}
+        else if(!allowedFlags.includes(args[i]))throw new Error('Unsupported credential option. Never put API keys in command arguments.');
+      }
+      const credentialOptions={projectRoot:selectedProject(args)};
+      let result;
+      if(action==='status')result=grokCredentialStatus(credentialOptions);
+      if(action==='check')result=await checkGrokConnection(credentialOptions);
+      if(action==='remove')result=removeGrokCredentials({confirmed:has(args,'--yes'),expectedRevision:option(args,'--expected-revision',grokCredentialStatus(credentialOptions).revision)},credentialOptions);
+      if(action==='configure'){
+        if(!process.stdin.isTTY||!process.stdout.isTTY)throw new Error('Grok setup requires an interactive terminal for hidden input. Use the local dashboard password form instead.');
+        const previous=grokCredentialStatus(credentialOptions),muted=new Writable({write(_chunk,_encoding,callback){callback();}});muted.isTTY=true;muted.columns=process.stdout.columns;
+        const prompt=createInterface({input:process.stdin,output:muted,terminal:true,historySize:0});let apiKey;
+        try{
+          process.stdout.write('This checks xAI authentication without generated output and saves the key for your account on this computer, outside the project, in an owner-only local file (not encrypted). XAI_API_KEY overrides the saved key. Cancel with Ctrl+C.\nxAI API key (hidden): ');
+          apiKey=await prompt.question('');process.stdout.write('\n');
+          result=await configureGrokCredentials({confirmed:true,expectedRevision:previous.revision,apiKey},credentialOptions);
+        }finally{apiKey=undefined;prompt.close();}
+      }
+      print(json?result:result.message??('Grok credential: '+result.source+'. Saved key: '+(result.saved?'available':'absent')+'.'),json);
+      if(result.status==='failed')process.exitCode=1;return;
+    }
+    if(command==='providers'){
+      if(!['show','set','auto','defaults','model'].includes(subcommand))throw new Error('Choose providers show, set, auto, model or defaults.');
+      const valued=new Set(['--project','--expected-digest',...(subcommand==='set'?['--primary','--secondary','--tertiary','--pool','--input']:[]),...(subcommand==='auto'?['--pool']:[]),...(subcommand==='model'?['--suggest','--allow-model']:[])]);
+      const switches=new Set(['--json',...(subcommand==='model'?['--clear-suggestion','--clear-restriction']:[])]),seen=new Set();
+      for(let i=subcommand==='model'?3:2;i<args.length;i++){const arg=args[i];if(valued.has(arg)){if(!args[i+1]||args[i+1].startsWith('--'))throw new Error(arg+' requires a value.');if(seen.has(arg)&&arg!=='--allow-model')throw new Error('Do not repeat '+arg);seen.add(arg);i++;}else if(!switches.has(arg))throw new Error('Unsupported provider argument: '+arg);}
+      const project=selectedProject(args),current=readCodingProviders(project);
+      if(subcommand==='show'){print(json?current:JSON.stringify(current,null,2),json);return;}
+      let policy=structuredClone(current.policy??{});
+      if(subcommand==='defaults')policy=null;
+      if(subcommand==='set'){
+        const input=option(args,'--input');if(input&&['--primary','--secondary','--tertiary','--pool'].some(flag=>has(args,flag)))throw new Error('Use a complete input policy or individual setting flags.');
+        if(input)policy=readProjectJsonInput(project,input,'Provider policy');
+        else{if(!['--primary','--secondary','--tertiary','--pool'].some(flag=>has(args,flag)))throw new Error('Choose provider settings to change.');for(const role of ['primary','secondary','tertiary'])if(has(args,'--'+role))policy[role]=option(args,'--'+role);if(has(args,'--pool'))policy.pool=option(args,'--pool').split(',').map(x=>x.trim());}
+      }
+      if(subcommand==='auto'){policy.primary='auto';policy.secondary='auto';policy.tertiary='auto';if(has(args,'--pool'))policy.pool=option(args,'--pool').split(',').map(x=>x.trim());}
+      if(subcommand==='model'){
+        const provider=args[2];if(!['claude','codex','grok','antigravity'].includes(provider))throw new Error('Choose a supported model provider.');
+        if(has(args,'--suggest')&&has(args,'--clear-suggestion')||has(args,'--allow-model')&&has(args,'--clear-restriction'))throw new Error('Choose one change for each model setting.');
+        if(!['--suggest','--allow-model','--clear-suggestion','--clear-restriction'].some(flag=>has(args,flag)))throw new Error('Choose a model suggestion or restriction to change.');
+        policy.models??={};const model=policy.models[provider]??{};
+        if(has(args,'--clear-suggestion'))delete model.suggestion;if(has(args,'--clear-restriction'))delete model.permitted_models;
+        if(has(args,'--suggest'))model.suggestion=option(args,'--suggest');if(has(args,'--allow-model'))model.permitted_models=options(args,'--allow-model');policy.models[provider]=model;
+      }
+      const saved=saveCodingProviders(project,{confirmed:true,expectedDigest:option(args,'--expected-digest',current.digest),policy});
+      print(json?saved:'Provider settings saved. Models remain native by default; required checks and approvals still apply.',json);return;
+    }
+
     if (command === 'dashboard' && ['preferences','configure'].includes(subcommand)) {
       const valueFlags=['--project','--enable','--disable','--expected-digest'];
       const booleanFlags=['--json','--yes','--collapse','--expand'];

package/src/coding-providers.mjs

@@ -0,0 +1,81 @@
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {readProjectDocument,editProjectDocument} from './config-document.mjs';
+
+export const CODING_PROVIDERS=Object.freeze(['claude','codex','grok','antigravity']);
+export const CODING_PROVIDER_LABELS=Object.freeze({claude:'Claude Code',codex:'Codex',grok:'Grok Build',antigravity:'Antigravity'});
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+function fail(message,statusCode=400,code){const error=new Error(message);error.statusCode=statusCode;error.codingProviderError=true;if(code)error.code=code;throw error;}
+function closed(value,keys,label){if(!object(value)||Object.keys(value).some(k=>!keys.includes(k)))fail(label+' contains unsupported fields.');}
+function provider(value){if(!CODING_PROVIDERS.includes(value))fail('Choose Claude Code, Codex, Grok Build or Antigravity.');return value;}
+function modelId(value){if(typeof value!=='string'||!/^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(value))fail('Use an exact, bounded model ID without spaces or wildcards.');return value;}
+export function normaliseCodingProviders(value){
+  if(value===undefined)return null;
+  closed(value,['pool','primary','secondary','tertiary','models'],'Provider policy');
+  const pool=value.pool??[...CODING_PROVIDERS];
+  if(!Array.isArray(pool)||!pool.length||pool.length>4||new Set(pool).size!==pool.length)fail('Choose a nonempty pool of distinct providers.');pool.forEach(provider);
+  const roles={};
+  for(const role of ['primary','secondary','tertiary']){
+    const choice=value[role]??'existing',allowed=['existing','auto',...CODING_PROVIDERS,...(role==='primary'?[]:['off'])];
+    if(!allowed.includes(choice))fail('Choose a supported '+role+' provider.');
+    if(CODING_PROVIDERS.includes(choice)&&!pool.includes(choice))fail('Include the selected '+role+' provider in the eligible pool.');roles[role]=choice;
+  }
+  const raw=value.models??{};closed(raw,CODING_PROVIDERS,'Model policy');const models={};
+  for(const p of CODING_PROVIDERS){if(raw[p]===undefined)continue;closed(raw[p],['suggestion','permitted_models'],'Model policy');const m={};
+    if(raw[p].suggestion!==undefined)m.suggestion=modelId(raw[p].suggestion);
+    if(raw[p].permitted_models!==undefined){const ids=raw[p].permitted_models;if(!Array.isArray(ids)||!ids.length||ids.length>64||new Set(ids).size!==ids.length)fail('Provide a nonempty list of distinct permitted model IDs.');m.permitted_models=ids.map(modelId);}
+    if(m.suggestion&&m.permitted_models&&!m.permitted_models.includes(m.suggestion))fail('The suggestion must be in the permitted model list.');
+    if(Object.keys(m).length)models[p]=m;
+  }
+  return {pool:[...pool],...roles,models};
+}
+export function codingPolicyDigest(value){return 'sha256:'+createHash('sha256').update(JSON.stringify(value===null?null:normaliseCodingProviders(value))).digest('hex');}
+export function readCodingPolicy(root){const value=readProjectDocument(root).config.coding_providers;const policy=value===undefined?null:normaliseCodingProviders(value);return {policy,policyDigest:codingPolicyDigest(policy)};}
+export function assertCodingPolicyFresh(expected,actual){if(!/^sha256:[a-f0-9]{64}$/.test(String(expected))||expected!==actual)fail('Provider policy changed. Recheck the saved settings and approved scope before continuing.',409);}
+export function assertModelPolicy(selected,raw){
+  provider(selected);const policy=raw==null?null:normaliseCodingProviders(raw),model=policy?.models[selected];
+  if(model?.permitted_models)fail(CODING_PROVIDER_LABELS[selected]+' cannot enforce this permitted-model list through a verified EWAI adapter. Execution stopped. Recommended: clear the restriction to use native model selection, or use an adapter with verified enforcement.',409,'coding-provider-model-restriction-unsupported');
+  return {mode:'native',...(model?.suggestion?{suggestion:model.suggestion}: {})};
+}
+export function modelGuidance(selected,policy){const m=assertModelPolicy(selected,policy);return m.suggestion?'\nAdvisory model suggestion: '+m.suggestion+'. Let the CLI choose the appropriate model.':'';}
+export function resolveCodingProviders(raw,options={}){
+  const policy=raw===null?null:normaliseCodingProviders(raw),orchestrator=options.orchestrator;
+  if(!policy)return {legacy:true,primary:null,reviewers:options.reviewers??[],policyDigest:codingPolicyDigest(null)};
+  const available=options.available??[],permitted=options.allowedProviders??CODING_PROVIDERS;
+  const eligible=policy.pool.filter(p=>available.includes(p)&&permitted.includes(p));
+  const automaticEligible=eligible.filter(p=>{try{assertModelPolicy(p,policy);return true;}catch{return false;}});
+  if(policy.primary==='auto'&&!automaticEligible.length&&eligible.length)assertModelPolicy(eligible[0],policy);
+  const primary=policy.primary==='existing'?(CODING_PROVIDERS.includes(orchestrator)?orchestrator:null):policy.primary==='auto'?automaticEligible[0]:policy.primary;
+  if(policy.primary!=='existing'&&(!primary||!eligible.includes(primary)))fail('No eligible primary provider. Recommended: enable an available provider inside the approved pool.',409);
+  const actual=orchestrator??primary;
+  const inherited=(options.reviewers??[]).filter(p=>p!==actual);
+  const reviewPool=eligible.filter(p=>p!==actual&&(options.reviewers===undefined||inherited.includes(p)));
+  const selected=[];
+  for(const role of ['secondary','tertiary']){
+    const choice=policy[role];if(choice==='off'||choice==='existing')continue;
+    if(!CODING_PROVIDERS.includes(actual))fail('Independent review requires the actual coding agent identity. Recommended: begin delivery with a supported orchestrator.',409);
+    const candidate=choice==='auto'?reviewPool.find(p=>automaticEligible.includes(p)&&!selected.includes(p)):choice;
+    if(choice==='auto'&&!candidate){const unsupported=reviewPool.find(p=>!selected.includes(p));if(unsupported)assertModelPolicy(unsupported,policy);}
+    if(candidate===actual)fail('The reviewer must be independent of the actual coding agent. Choose another provider.',409);
+    if(selected.includes(candidate))fail('Secondary and tertiary reviewers must use distinct providers. Choose another provider.',409);
+    if(!candidate||!reviewPool.includes(candidate))fail('No eligible '+role+' reviewer. Recommended: enable another independent provider in the checkpoint and approved pool.',409);
+    selected.push(candidate);
+  }
+  if(policy.secondary==='existing'||policy.tertiary==='existing')for(const p of reviewPool)if(!selected.includes(p))selected.push(p);
+  if(selected.length<Number(options.requiredReviewers??0))fail('Required independent review capacity is unavailable. Keep the required checkpoint and enable enough distinct reviewers.',409);
+  if(policy.primary!=='existing')assertModelPolicy(primary,policy);
+  for(const p of selected)assertModelPolicy(p,policy);
+  return {legacy:false,primary,reviewers:selected,policyDigest:codingPolicyDigest(policy)};
+}
+export function codingProviderCapabilities(options={}){
+  const probe=options.probe??(p=>{const r=spawnSync(p==='antigravity'?'agy':p,['--version'],{stdio:'pipe',encoding:'utf8',timeout:3000,env:options.env??process.env});return {available:!r.error&&r.status===0};});
+  return CODING_PROVIDERS.map(p=>{const value=probe(p),available=typeof value==='boolean'?value:value?.available===true;
+    return {provider:p,label:CODING_PROVIDER_LABELS[p],available,interactive:available,modelSelection:'native',modelRestrictions:'unsupported',unattended:p==='grok'?'requires-conformance':'existing-adapter',recommendation:available?'Use native model selection. Verify required execution capability before running.':'Install or enable this CLI, then recheck availability.'};});
+}
+function projection(state,options={}){const policy=state.config.coding_providers===undefined?null:normaliseCodingProviders(state.config.coding_providers),capabilities=codingProviderCapabilities(options);return {schema:'ewai.coding-providers/v1',digest:state.digest,policy,policyDigest:codingPolicyDigest(policy),capabilities,defaults:{modelSelection:'native',providerSelection:'existing',reviews:'existing checkpoint policy'},authority:'settings-only'};}
+export function readCodingProviders(root,options={}){return projection(readProjectDocument(root),options);}
+export function saveCodingProviders(root,input,options={}){
+  closed(input,['confirmed','expectedDigest','policy'],'Provider settings request');if(input.confirmed!==true)fail('Confirm provider setting changes before saving.');if(!Object.hasOwn(input,'policy'))fail('Provide a complete policy, or null to restore existing behaviour.');
+  const policy=input.policy===null?null:normaliseCodingProviders(input.policy);
+  const state=editProjectDocument(root,input.expectedDigest,document=>{if(policy===null)document.delete('coding_providers');else document.set('coding_providers',policy);});return projection(state,options);
+}

package/src/companion.mjs

@@ -6,16 +6,19 @@ import { install } from './install.mjs';
 import { detectExistingCodebase } from './project.mjs';
 import { projectPaths, resolveProjectRoot } from './paths.mjs';
 import { dashboardHandoffStatus } from './runtime/dashboard-handoffs.mjs';
+import {readCodingProviders,resolveCodingProviders,modelGuidance} from './coding-providers.mjs';
 
-const HOSTS = ['claude', 'codex', 'antigravity'];
+const HOSTS = ['claude', 'codex', 'antigravity', 'grok'];
 const HOST_LABELS = {
   claude: 'Claude Code',
   codex: 'Codex',
+  grok: 'Grok Build',
   antigravity: 'Google Antigravity'
 };
 const HOST_COMMANDS = {
   claude: 'claude',
   codex: 'codex',
+  grok: 'grok',
   antigravity: 'agy',
 };
 
@@ -102,6 +105,7 @@ export function buildCompanionPrompt(state) {
 export function hostInvocation(host, prompt) {
   if (host === 'claude') return { command: 'claude', args: [prompt] };
   if (host === 'codex') return { command: 'codex', args: [prompt] };
+  if (host === 'grok') return { command: 'grok', args: [prompt] };
   if (host === 'antigravity') return { command: 'agy', args: ['--prompt-interactive', prompt] };
   throw new Error(`Unsupported EWAI agent host: ${host}`);
 }
@@ -209,7 +213,10 @@ export async function runCompanion(options = {}) {
   const errorOutput = options.errorOutput ?? process.stderr;
   const env = options.env ?? process.env;
   const state = projectState(options.cwd ?? process.cwd());
-  const preferredValue = String(options.preferredHost ?? env.EWAI_HOST ?? '').toLowerCase();
+  let policy=null;
+  if(state.initialized)try{policy=readCodingProviders(state.projectRoot,{probe:()=>false}).policy;}catch(error){errorOutput.write(error.message+'\n');return 1;}
+  const policyPrimary=policy&&policy.primary!=='existing'&&policy.primary!=='auto'?policy.primary:undefined;
+  const preferredValue = String(options.preferredHost ?? env.EWAI_HOST ?? policyPrimary ?? '').toLowerCase();
   const preferred = preferredValue === 'agy' ? 'antigravity' : preferredValue;
   const preferredStatuses = HOSTS.includes(preferred)
     ? detectHostStatuses({ env, probe: options.probeHost, hosts: [preferred] }) : [];
@@ -229,15 +236,23 @@ export async function runCompanion(options = {}) {
   }
 
   let host = selectAvailableHost(available, preferred);
+  if(policy&&policy.primary!=='existing'&&!options.preferredHost&&!env.EWAI_HOST){
+    try{host=resolveCodingProviders({...policy,secondary:'off',tertiary:'off'},{available}).primary;}
+    catch(error){errorOutput.write(error.message+'\n');return 1;}
+  }
   if (!host && available.length > 1) {
     if (!options.verbose) output.write(`${formatHostAvailability(statuses)}\n`);
     host = await askForHost(available, { input, output });
   }
   if (!host) {
-    errorOutput.write(`EWAI found ${available.map((item) => HOST_LABELS[item]).join(', ')}, but cannot choose interactively in this session. Set EWAI_HOST to claude, codex, or antigravity.\n`);
+    errorOutput.write(`EWAI found ${available.map((item) => HOST_LABELS[item]).join(', ')}, but cannot choose interactively in this session. Set EWAI_HOST to claude, codex, grok, or antigravity.\n`);
     return 1;
   }
 
+  let guidance='';try{
+    if(policy&&!policy.pool.includes(host))throw new Error('The selected CLI is outside the provider pool. Choose an eligible host or explicitly update the provider settings.');
+    guidance=modelGuidance(host,policy);
+  }catch(error){errorOutput.write(error.message+'\n');return 1;}
   const prepareHost = options.prepareHost ?? ((selectedHost) => refreshHostSkills(selectedHost));
   try {
     await prepareHost(host);
@@ -249,7 +264,7 @@ export async function runCompanion(options = {}) {
 
   output.write(`EWAI · ${basename(state.projectRoot)} → ${HOST_LABELS[host]}\n`);
   const orchestratedState = { ...state, orchestrator: host, startup: companionStartupPlan(state) };
-  const invocation = hostInvocation(host, buildCompanionPrompt(orchestratedState));
+  const invocation = hostInvocation(host, buildCompanionPrompt(orchestratedState)+guidance);
   const hostEnv = { ...env, EWAI_ORCHESTRATOR: host };
   const launch = options.spawnHost ?? ((value) => spawnInteractive(value, { cwd: state.projectRoot, env: hostEnv }));
   return launch(invocation, orchestratedState);

package/src/config-document.mjs

@@ -0,0 +1,49 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync,existsSync} from 'node:fs';
+import {dirname,relative,resolve,isAbsolute} from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import YAML from 'yaml';
+import {projectPaths} from './paths.mjs';
+
+function fail(message,statusCode=409){const error=new Error(message);error.statusCode=statusCode;error.configurationError=true;throw error;}
+function safePath(paths){
+  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
+  if(rel.startsWith('..')||isAbsolute(rel))fail('Settings require a safe project configuration path.',403);
+  let cursor=parent;
+  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Settings cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Settings require a safe project configuration path.',403);cursor=next;}
+  const stat=lstatSync(paths.configPath);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Settings require a regular, non-symbolic configuration file.',403);
+  if(stat.size>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+  return stat;
+}
+export function readProjectDocument(projectRoot){
+  const paths=projectPaths(projectRoot);let fd;
+  try{
+    const stat=safePath(paths);fd=openSync(paths.configPath,constants.O_RDONLY|constants.O_NOFOLLOW);
+    const opened=fstatSync(fd);if(opened.ino!==stat.ino||opened.dev!==stat.dev)fail('Project configuration changed. Reload the settings and try again.');
+    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+    const document=YAML.parseDocument(bytes.toString('utf8'));
+    if(document.errors.length)fail('Project configuration contains invalid YAML. Fix it before editing settings.',422);
+    let config;try{config=document.toJS({maxAliasCount:100});}catch{fail('The project configuration cannot be safely read.',422);}
+    if(config?.schema!=='ewai.project/v1'||config?.specs?.root!==paths.specsRelative)fail('Project configuration and SPECS locator must agree before editing settings.',422);
+    return {paths,document,config,digest:'sha256:'+createHash('sha256').update(bytes).digest('hex'),mode:stat.mode&0o777};
+  }catch(error){if(error.configurationError)throw error;fail('Project settings could not be read. Check configuration and file permissions.');}
+  finally{if(fd!==undefined)closeSync(fd);}
+}
+export function editProjectDocument(projectRoot,expectedDigest,apply){
+  if(!/^sha256:[a-f0-9]{64}$/.test(String(expectedDigest??'')))fail('Reload settings before saving.',400);
+  const paths=projectPaths(projectRoot),lock=paths.configPath+'.configuration.lock';let lockFd,tempFd,temporary;
+  try{
+    safePath(paths);
+    if(existsSync(paths.configPath+'.dashboard-preferences.lock'))fail('Settings are being edited. Retry after that save finishes.');
+    try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Settings are being edited. Retry after that save finishes.');}
+    const before=readProjectDocument(projectRoot);if(before.digest!==expectedDigest)fail('Project configuration changed. Reload the settings and try again.');
+    apply(before.document,before.config);
+    const content=before.document.toString();
+    temporary=paths.configPath+'.settings-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
+    writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
+    if(readProjectDocument(projectRoot).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.');
+    safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
+    return readProjectDocument(projectRoot);
+  }catch(error){if(error.configurationError||error.codingProviderError||error.dashboardPreferenceError)throw error;fail('Project settings could not be saved. Check configuration and file permissions.');}
+  finally{if(tempFd!==undefined)closeSync(tempFd);if(temporary)unlinkSync(temporary);if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}}
+}