litgrok-ai 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.5 (pending) — 2026-09-01
+
+- Add the shared stacked LitFamily ASCII wordmark to the installer and lead both
+  READMEs with the version-free wordmark.
+- Add a CI-enforced, manifest-driven version-lockstep guard for all eight release
+  sites, counting both plain and escaped-regex pins.
+- Report model-picker and output-style selection as Grok host limits rather than
+  shipped surfaces: the installer writes no model or style keys, and
+  `grok inspect --json` exposes no `model`, `outputStyles`, or `settings` keys.
+- Add installer-depth coverage for explicit `--yes` consent, non-interactive
+  no-write behavior, host-limit receipts, measured install phases, and isolated
+  plugin validation.
+
 ## 0.2.4 (pending) — 2026-08-31
 
 - Ship the Grok plugin manifest, eleven Grok-native agents, and complete reference

package/README.md

@@ -1,5 +1,18 @@
 <p align="center"><img src="./cover.png" width="100%" alt="LitGrok — Grok Build skills and project rules, installed with npx" /></p>
 
+```text
+██╗     ██╗████████╗
+██║     ██║╚══██╔══╝
+██║     ██║   ██║   
+███████╗██║   ██║   
+╚══════╝╚═╝   ╚═╝   
+ ██████╗ ██████╗  ██████╗ ██╗  ██╗
+██╔════╝ ██╔══██╗██╔═══██╗██║ ██╔╝
+██║  ███╗██████╔╝██║   ██║█████╔╝ 
+╚██████╔╝██║  ██║╚██████╔╝██║  ██╗
+ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝
+```
+
 <h1 align="center">LitGrok</h1>
 <p align="center">
   <em>Grok Build skills and project rules for evidence-first lit work, installed with <code>npx</code>.</em>
@@ -9,7 +22,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litgrok--ai-cb3837" alt="npm: litgrok-ai" />
-  <img src="https://img.shields.io/badge/version-0.2.4-2ea44f" alt="version 0.2.4" />
+  <img src="https://img.shields.io/badge/version-0.2.5-2ea44f" alt="version 0.2.5" />
   <img src="https://img.shields.io/badge/Grok%20Build-skills%20%2B%20rules-111827" alt="Grok Build skills and project rules" />
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
 </p>
@@ -18,6 +31,37 @@ LitGrok is the Grok Build member of the lit workflow family. The npm package is
 
 This package does not log in to Grok, start the TUI, or claim live host behavior.
 
+### The workflow in one view
+
+```mermaid
+flowchart TD
+    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
+    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
+    P --> GATE{"user approves?"}
+    GATE -->|no| P
+    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]
+
+    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
+        SW --> RED["failing test first"]
+        RED --> GREEN["smallest change that passes"]
+        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
+        SURF --> CLEAN["tear down · cleanup receipt"]
+    end
+
+    CLEAN --> EV{"evidence complete?"}
+    EV -->|"tests only"| SW
+    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
+    RW -->|findings| SW
+    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]
+
+    style GATE fill:#fff3cd,stroke:#856404
+    style EV fill:#fff3cd,stroke:#856404
+    style SURF fill:#d4edda,stroke:#155724
+    style RW fill:#d1ecf1,stroke:#0c5460
+```
+
+> **Execution discipline.** A plan earns approval only when every item has binary verification. A slice closes after the real surface produces an artifact and its QA resources are torn down; passing tests alone never closes it.
+
 ## What it is
 
 - 34 Grok-native skill documents at `.grok/skills/<name>/SKILL.md`.
@@ -31,6 +75,27 @@ This package does not log in to Grok, start the TUI, or claim live host behavior
 
 Grok Build loads skills from project, user, plugin, and configured paths. Project guidance uses AGENTS-family files and `.grok/rules/*.md`; hooks load from project or user `.grok/hooks/`. LitGrok installs only these documented direct surfaces.
 
+### How it connects to Grok Build
+
+```mermaid
+flowchart LR
+    subgraph GB["Grok Build"]
+        PJ["plugin.json"]; HK["hooks"]; RL["rules"]
+    end
+    subgraph LG["LitGrok plugin"]
+        PLAN["plan gate"]
+        HEDGE["deliverable hedge guard"]
+        LEDGER[("session ledger")]
+    end
+    PJ --> LG
+    HK --> PLAN --> LEDGER
+    HK --> HEDGE
+    RL --> LG
+    LG --> S["34 skills · 11 agents"]
+```
+
+> **A narrow host boundary.** `plugin.json` exposes the package, hooks feed the plan gate and hedge guard, and rules provide project guidance while the session ledger records bounded state. Together these surfaces carry LitGrok’s 34 skills and 11 agents into Grok Build.
+
 ## Install
 
 ```bash
@@ -40,7 +105,7 @@ npx --yes litgrok-ai@latest install
 Pin a version when you need a reproducible install:
 
 ```bash
-npx --yes litgrok-ai@0.2.4 install
+npx --yes litgrok-ai@0.2.5 install
 ```
 
 Preview without writing files:
@@ -87,6 +152,24 @@ If any installed payload file was changed, uninstall refuses the whole removal.
 
 After install, trust project hooks, then open or restart Grok Build in that project. Skills and the rule are guidance surfaces; hook commands are the only executable payload files, and they receive documented event JSON on stdin.
 
+### What the packed payload guarantees
+
+```mermaid
+flowchart LR
+    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
+    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
+    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
+    AL --> G1
+    C --> G1["<b>payload-substance</b>"]
+    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
+    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
+    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
+    style C fill:#d4edda,stroke:#155724
+    style OK fill:#d4edda,stroke:#155724
+```
+
+> **The tarball is the shipping boundary.** A file present in the repository is not necessarily shipped. Each `npm pack` gate checks the allowlist or required corpus, parity, and every referenced path, so a missing dependency is caught before release rather than on a user’s machine.
+
 Confirm the files exist:
 
 ```bash
@@ -115,12 +198,12 @@ Review is proposal-only. `autoApply` is always false, transcript text is inert d
 From an installed project, use the package CLI directly when you want a replayable foreground command:
 
 ```bash
-npx --yes litgrok-ai@0.2.4 skill-loop review <session-id>
-npx --yes litgrok-ai@0.2.4 skill-loop list
-npx --yes litgrok-ai@0.2.4 skill-loop apply <proposal-id>
-npx --yes litgrok-ai@0.2.4 skill-loop reject <proposal-id>
-npx --yes litgrok-ai@0.2.4 skill-loop rollback <ledger-id>
-npx --yes litgrok-ai@0.2.4 skill-loop curator
+npx --yes litgrok-ai@0.2.5 skill-loop review <session-id>
+npx --yes litgrok-ai@0.2.5 skill-loop list
+npx --yes litgrok-ai@0.2.5 skill-loop apply <proposal-id>
+npx --yes litgrok-ai@0.2.5 skill-loop reject <proposal-id>
+npx --yes litgrok-ai@0.2.5 skill-loop rollback <ledger-id>
+npx --yes litgrok-ai@0.2.5 skill-loop curator
 ```
 
 `apply` prints the ledger id needed for rollback. The deterministic curator is also user-invoked: by default it runs at most once every seven days, requires at least two idle hours, marks eligible unpinned agent-owned skills stale after 30 idle days, and archives them outside discovery after 90 idle days. It makes a full backup before a transition and never deletes a skill package; `--force` bypasses only the seven-day run interval for an explicit test or maintenance invocation.

package/README_ko-KR.md

@@ -1,5 +1,18 @@
 <p align="center"><img src="./cover.png" width="100%" alt="LitGrok — npx로 설치하는 Grok Build skill과 project rule" /></p>
 
+```text
+██╗     ██╗████████╗
+██║     ██║╚══██╔══╝
+██║     ██║   ██║   
+███████╗██║   ██║   
+╚══════╝╚═╝   ╚═╝   
+ ██████╗ ██████╗  ██████╗ ██╗  ██╗
+██╔════╝ ██╔══██╗██╔═══██╗██║ ██╔╝
+██║  ███╗██████╔╝██║   ██║█████╔╝ 
+╚██████╔╝██║  ██║╚██████╔╝██║  ██╗
+ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝
+```
+
 <h1 align="center">LitGrok</h1>
 <p align="center">
   <em>Grok Build용 skill과 project rule. <code>npx</code>로 설치합니다.</em>
@@ -9,7 +22,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litgrok--ai-cb3837" alt="npm: litgrok-ai" />
-  <img src="https://img.shields.io/badge/version-0.2.4-2ea44f" alt="version 0.2.4" />
+  <img src="https://img.shields.io/badge/version-0.2.5-2ea44f" alt="version 0.2.5" />
   <img src="https://img.shields.io/badge/Grok%20Build-skills%20%2B%20rules-111827" alt="Grok Build skills and project rules" />
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
 </p>
@@ -18,6 +31,37 @@ LitGrok은 lit workflow family의 Grok Build 포트입니다. npm 패키지 이
 
 Grok에 로그인하거나 TUI를 띄우거나, live host 동작을 주장하지 않습니다.
 
+### 작업 흐름 한눈에 보기
+
+```mermaid
+flowchart TD
+    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
+    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
+    P --> GATE{"user approves?"}
+    GATE -->|no| P
+    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]
+
+    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
+        SW --> RED["failing test first"]
+        RED --> GREEN["smallest change that passes"]
+        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
+        SURF --> CLEAN["tear down · cleanup receipt"]
+    end
+
+    CLEAN --> EV{"evidence complete?"}
+    EV -->|"tests only"| SW
+    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
+    RW -->|findings| SW
+    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]
+
+    style GATE fill:#fff3cd,stroke:#856404
+    style EV fill:#fff3cd,stroke:#856404
+    style SURF fill:#d4edda,stroke:#155724
+    style RW fill:#d1ecf1,stroke:#0c5460
+```
+
+> **실행 규율.** 모든 항목에 binary verification이 있어야 계획을 승인할 수 있습니다. 한 slice는 실제 surface에서 artifact를 만들고 QA 자원을 정리한 뒤에야 닫힙니다. 테스트만 통과한 상태는 완료가 아닙니다.
+
 ## 무엇을 제공하나요?
 
 - `.grok/skills/<name>/SKILL.md`에 Grok-native skill 문서 34개
@@ -31,6 +75,27 @@ Grok에 로그인하거나 TUI를 띄우거나, live host 동작을 주장하지
 
 Grok Build는 project, user, plugin, configured path에서 skill을 읽습니다. Project guidance는 AGENTS-family 파일과 `.grok/rules/*.md`이고 hook은 project 또는 user `.grok/hooks/`에서 읽습니다. LitGrok은 이 문서화된 direct surface만 설치합니다.
 
+### Grok Build에 연결되는 구조
+
+```mermaid
+flowchart LR
+    subgraph GB["Grok Build"]
+        PJ["plugin.json"]; HK["hooks"]; RL["rules"]
+    end
+    subgraph LG["LitGrok plugin"]
+        PLAN["plan gate"]
+        HEDGE["deliverable hedge guard"]
+        LEDGER[("session ledger")]
+    end
+    PJ --> LG
+    HK --> PLAN --> LEDGER
+    HK --> HEDGE
+    RL --> LG
+    LG --> S["34 skills · 11 agents"]
+```
+
+> **Host 경계는 좁고 명확합니다.** `plugin.json`이 package를 노출하고, hook은 plan gate와 hedge guard로 연결되며, rule은 project guidance가 됩니다. session ledger에는 bounded state를 기록하고, 이 표면들이 34개 skill과 11개 agent를 Grok Build에서 사용할 수 있게 합니다.
+
 ## 설치
 
 ```bash
@@ -40,7 +105,7 @@ npx --yes litgrok-ai@latest install
 재현 가능한 설치는 버전을 고정합니다.
 
 ```bash
-npx --yes litgrok-ai@0.2.4 install
+npx --yes litgrok-ai@0.2.5 install
 ```
 
 파일을 쓰지 않고 미리보기:
@@ -87,6 +152,24 @@ npx --yes litgrok-ai@latest uninstall --user
 
 설치 후 project hook trust를 허용하고, 그 프로젝트에서 Grok Build를 열거나 재시작합니다. Skill과 rule은 guidance surface이고, hook command만 실행 가능한 payload이며 문서화된 event JSON을 stdin으로 받습니다.
 
+### 새 머신에서도 payload가 작동하는 이유
+
+```mermaid
+flowchart LR
+    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
+    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
+    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
+    AL --> G1
+    C --> G1["<b>payload-substance</b>"]
+    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
+    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
+    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
+    style C fill:#d4edda,stroke:#155724
+    style OK fill:#d4edda,stroke:#155724
+```
+
+> **Shipping의 기준은 tarball입니다.** 저장소 안에 파일이 있다는 것만으로는 package에 포함됐다고 할 수 없습니다. `npm pack`을 기준으로 allowlist/corpus, product 간 substance parity, `SKILL.md`가 가리키는 path까지 확인하므로 빠진 의존성은 사용자 환경에 도달하기 전에 드러납니다.
+
 파일이 생겼는지 확인:
 
 ```bash
@@ -115,12 +198,12 @@ Review는 proposal만 만듭니다. `autoApply`는 항상 false이고 transcript
 설치된 project에서는 다음 package CLI를 foreground command로 실행할 수 있습니다.
 
 ```bash
-npx --yes litgrok-ai@0.2.4 skill-loop review <session-id>
-npx --yes litgrok-ai@0.2.4 skill-loop list
-npx --yes litgrok-ai@0.2.4 skill-loop apply <proposal-id>
-npx --yes litgrok-ai@0.2.4 skill-loop reject <proposal-id>
-npx --yes litgrok-ai@0.2.4 skill-loop rollback <ledger-id>
-npx --yes litgrok-ai@0.2.4 skill-loop curator
+npx --yes litgrok-ai@0.2.5 skill-loop review <session-id>
+npx --yes litgrok-ai@0.2.5 skill-loop list
+npx --yes litgrok-ai@0.2.5 skill-loop apply <proposal-id>
+npx --yes litgrok-ai@0.2.5 skill-loop reject <proposal-id>
+npx --yes litgrok-ai@0.2.5 skill-loop rollback <ledger-id>
+npx --yes litgrok-ai@0.2.5 skill-loop curator
 ```
 
 `apply`는 rollback에 필요한 ledger id를 출력합니다. Deterministic curator도 user-invoked입니다. 기본적으로 7일에 한 번만 실행되고, 마지막 activity 뒤 최소 2시간이 지나야 하며, pin되지 않은 agent-owned skill을 30일 idle 뒤 stale로 표시하고 90일 idle 뒤 discovery 밖으로 archive합니다. Transition 전에는 전체 backup을 만들고 skill package를 삭제하지 않습니다. `--force`는 명시적인 test 또는 maintenance 실행에서 7일 interval만 건너뜁니다.

package/bin/litgrok.mjs

@@ -7,18 +7,57 @@ import { fileURLToPath } from 'node:url';
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const PAYLOAD_ROOT = join(PACKAGE_ROOT, '.grok');
-const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--dry-run] [--no-color]\n       litgrok skill-loop <review|propose|list|apply|reject|rollback|curator> ...\n';
+const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--dry-run] [--no-color] [--yes]\n       litgrok skill-loop <review|propose|list|apply|reject|rollback|curator> ...\n';
+const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 80;
+const CLEAR_LINE = '\r\u001b[2K';
+
+// ANSI Shadow, compressed to 5 rows: the standard 6-row face with its duplicate
+// middle row dropped, keeping the closing row. This matches the approved preview.
+// This table and renderer are ported verbatim from
+// .litclaude/evidence/litfamily-guard-parity-v4/ansi-shadow-authoritative.mjs.
+const GLYPHS = {
+  a:[" █████╗ ","██╔══██╗","███████║","██╔══██║","╚═╝  ╚═╝"],
+  c:[" ██████╗","██╔════╝","██║     ","╚██████╗"," ╚═════╝"],
+  d:["██████╗ ","██╔══██╗","██║  ██║","██████╔╝","╚═════╝ "],
+  e:["███████╗","██╔════╝","█████╗  ","███████╗","╚══════╝"],
+  g:[" ██████╗ ","██╔════╝ ","██║  ███╗","╚██████╔╝"," ╚═════╝ "],
+  h:["██╗  ██╗","██║  ██║","███████║","██║  ██║","╚═╝  ╚═╝"],
+  i:["██╗","██║","██║","██║","╚═╝"],
+  k:["██╗  ██╗","██║ ██╔╝","█████╔╝ ","██║  ██╗","╚═╝  ╚═╝"],
+  l:["██╗     ","██║     ","██║     ","███████╗","╚══════╝"],
+  m:["███╗   ███╗","████╗ ████║","██╔████╔██║","██║ ╚═╝ ██║","╚═╝     ╚═╝"],
+  n:["███╗   ██╗","████╗  ██║","██╔██╗ ██║","██║ ╚████║","╚═╝  ╚═══╝"],
+  o:[" ██████╗ ","██╔═══██╗","██║   ██║","╚██████╔╝"," ╚═════╝ "],
+  p:["██████╗ ","██╔══██╗","██████╔╝","██║     ","╚═╝     "],
+  r:["██████╗ ","██╔══██╗","██████╔╝","██║  ██║","╚═╝  ╚═╝"],
+  s:["███████╗","██╔════╝","███████╗","███████║","╚══════╝"],
+  t:["████████╗","╚══██╔══╝","   ██║   ","   ██║   ","   ╚═╝   "],
+  u:["██╗   ██╗","██║   ██║","██║   ██║","╚██████╔╝"," ╚═════╝ "],
+  x:["██╗  ██╗","╚██╗██╔╝"," ╚███╔╝ ","██╔╝ ██╗","╚═╝  ╚═╝"],
+};
+
+function renderAnsiShadow(word) {
+  const rows = ["", "", "", "", ""];
+  for (const ch of word) {
+    const g = GLYPHS[ch];
+    if (!g) throw new Error(`missing glyph for '${ch}' in '${word}'`);
+    for (let index = 0; index < 5; index += 1) rows[index] += g[index];
+  }
+  return rows;
+}
 
 function parseInstall(args) {
   const remaining = [...args];
   let command = 'install';
   if (['install', 'uninstall'].includes(remaining[0])) command = remaining.shift();
-  if (remaining.some((argument) => !['--user', '--project', '--dry-run', '--no-color'].includes(argument))) return null;
+  if (remaining.some((argument) => !['--user', '--project', '--dry-run', '--no-color', '--yes'].includes(argument))) return null;
   if (remaining.includes('--user') && remaining.includes('--project')) return null;
   return {
     command,
     dryRun: remaining.includes('--dry-run'),
     noColor: remaining.includes('--no-color'),
+    yes: remaining.includes('--yes'),
     scope: remaining.includes('--user') ? 'user' : 'project',
   };
 }
@@ -32,25 +71,168 @@ function packageVersion() {
   }
 }
 
+function paint(value, code, enabled) {
+  return enabled ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
+
+function elapsedSince(start) {
+  return `${(Number(process.hrtime.bigint() - start) / 1e6).toFixed(1)}ms`;
+}
+
+function scopeDescription(options, root) {
+  const alternateFlag = options.scope === 'project' ? '--user' : '--project';
+  const alternateScope = options.scope === 'project' ? 'user' : 'project';
+  return `${options.scope} scope → ${root} (use ${alternateFlag} for ${alternateScope} scope)`;
+}
+
 function printInstallFrame(stdout, options, env, fileCount, root) {
-  const colors = !options.noColor && !Object.hasOwn(env, 'NO_COLOR') && !env.CI && Boolean(stdout.isTTY);
-  const orange = colors ? '' : '';
-  const yellow = colors ? '' : '';
-  const reset = colors ? '' : '';
+  const colors = !options.noColor && !options.dryRun && !Object.hasOwn(env, 'NO_COLOR') && !env.CI && Boolean(stdout.isTTY);
+  const orange = colors ? '\u001b[38;2;255;90;31m' : '';
+  const yellow = colors ? '\u001b[38;2;250;204;21m' : '';
+  const reset = colors ? '\u001b[0m' : '';
   const rule = `  ${'━'.repeat(46)}`;
+  const payloadLabel = Number.isInteger(fileCount) ? `${fileCount} files · byte-identical copies only` : 'packaged .grok tree · byte-identical copies only';
   stdout.write(`${rule}\n`);
   stdout.write('\n');
-  stdout.write(`   ${orange}🔥  l  i  t  grok   v${packageVersion()}${reset}\n`);
+  const wordmarkRows = [
+    ...renderAnsiShadow('lit'),
+    ...renderAnsiShadow('grok').map((row, index) => index === 0 ? `${row}   v${packageVersion()}` : row),
+  ];
+  stdout.write(`${wordmarkRows.map((row) => `   ${orange}${row}${reset}`).join('\n')}\n`);
   stdout.write('       Grok Build skills, project rules, and hooks\n');
   stdout.write('\n');
   stdout.write(`${rule}\n`);
   stdout.write(`  ╭─ ${options.command.toUpperCase()}\n`);
-  stdout.write(`  │ ${yellow}01${reset} · Scope      ${options.scope} → ${root}\n`);
-  stdout.write(`  │ ${yellow}02${reset} · Payload    ${fileCount} files\n`);
+  stdout.write(`  │ ${yellow}01${reset} · Scope      ${scopeDescription(options, root)}\n`);
+  stdout.write(`  │ ${yellow}02${reset} · Payload    ${payloadLabel}\n`);
   stdout.write('  ╰─ whole packaged .grok tree, byte-identical copies only\n');
   stdout.write('  ╭─ MODEL ROUTE\n');
   stdout.write('  │ Model selection: host-owned\n');
   stdout.write('  ╰─ Grok Build owns model and effort; the installer writes no model keys\n');
+  return colors;
+}
+
+function statusMark(status, colors) {
+  if (status === 'ok') return paint('✓', '38;2;80;200;80', colors);
+  if (status === 'failed') return paint('✗', '38;2;230;60;60', colors);
+  return colors ? paint('○', '38;2;148;163;184', true) : '[skip]';
+}
+
+class InstallProgress {
+  constructor(stdout, colors) {
+    this.stdout = stdout;
+    this.colors = colors;
+    this.timer = null;
+    this.frameIndex = 0;
+    this.active = false;
+    this.closed = false;
+  }
+
+  open() {
+    this.stdout.write('  ╭─ INSTALL STEPS\n');
+  }
+
+  start(label) {
+    this.clearTimer();
+    this.active = true;
+    this.frameIndex = 0;
+    this.label = label;
+    if (!this.colors) return;
+    this.render();
+    this.timer = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % BRAILLE_FRAMES.length;
+      this.render();
+    }, SPINNER_INTERVAL_MS);
+    if (typeof this.timer.unref === 'function') this.timer.unref();
+  }
+
+  finish(status, label, detail, elapsed) {
+    this.clearTimer();
+    const suffix = detail ? ` · ${detail}` : '';
+    const line = `  │ ${statusMark(status, this.colors)} ${label}${suffix} · ${elapsed}`;
+    this.stdout.write(this.colors && this.active ? `${CLEAR_LINE}${line}\n` : `${line}\n`);
+    this.active = false;
+  }
+
+  close() {
+    this.clearTimer();
+    if (this.closed) return;
+    this.stdout.write('  ╰─\n');
+    this.closed = true;
+  }
+
+  render() {
+    const frame = paint(BRAILLE_FRAMES[this.frameIndex] ?? BRAILLE_FRAMES[0], '38;2;250;204;21', this.colors);
+    this.stdout.write(`${CLEAR_LINE}  │ ${frame} ${this.label}`);
+  }
+
+  clearTimer() {
+    if (this.timer === null) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+}
+
+function runStep(progress, label, operation) {
+  const started = process.hrtime.bigint();
+  progress.start(label);
+  try {
+    const result = operation();
+    progress.finish('ok', label, result.detail ?? '', elapsedSince(started));
+    return result.value;
+  } catch (error) {
+    progress.finish('failed', label, error instanceof Error ? error.message : String(error), elapsedSince(started));
+    throw error;
+  }
+}
+
+function skipStep(progress, label, detail) {
+  const started = process.hrtime.bigint();
+  progress.finish('skipped', label, detail, elapsedSince(started));
+}
+
+function receiptCard(options, root, colors, { status, written, current }) {
+  const statusColor = status === 'Ready' || status === 'Already current' || status === 'Removed' ? '38;2;80;200;80' : '38;2;230;60;60';
+  const titleColor = status === 'Failed' ? '38;2;230;60;60' : '38;2;255;90;31';
+  return [
+    '',
+    `  ${paint('╭─ INSTALL RECEIPT', titleColor, colors)}`,
+    `  │ Status: ${paint(status, statusColor, colors)}`,
+    `  │ Scope: ${scopeDescription(options, root)}`,
+    `  │ Written vs already-current: ${written} written · ${current} already-current`,
+    '  │ Model route: host-owned; the installer writes no model keys',
+    '  │ Model picker: host limit — Grok Build owns session selection; no model keys are written',
+    '  │ Output styles: host limit — Grok Build exposes no output-style selector; the installer writes no style keys',
+    '  │ Hooks: require trust — /hooks-trust or launch Grok Build with --trust',
+    '  │ Next: restart Grok Build',
+    `  ${paint('╰─', titleColor, colors)}`,
+    '',
+  ].join('\n');
+}
+
+function failureCard(options, root, colors, step, message) {
+  return [
+    '',
+    `  ${paint('╭─ INSTALL FAILED', '38;2;230;60;60', colors)}`,
+    `  │ Status: ${paint('Failed', '38;2;230;60;60', colors)}`,
+    `  │ Scope: ${scopeDescription(options, root)}`,
+    `  │ Step: ${step}`,
+    `  │ Reason: ${message}`,
+    '  │ Hooks: require trust — /hooks-trust or launch Grok Build with --trust',
+    '  │ Next: resolve the issue and rerun the install',
+    `  ${paint('╰─', '38;2;230;60;60', colors)}`,
+    '',
+  ].join('\n');
+}
+
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function reportFailure(error, { stderr, stdout, options, root, colors, step }) {
+  const lines = Array.isArray(error?.stderrLines) ? error.stderrLines : [`litgrok: ${errorText(error)}`];
+  for (const line of lines) stderr.write(`${line}\n`);
+  stdout.write(failureCard(options, root, colors, error?.step ?? step, errorText(error)));
 }
 
 function targetState(source, target) {
@@ -133,19 +315,40 @@ export async function run(args, context = {}) {
 
   const home = env.HOME || env.USERPROFILE || homedir();
   const root = join(options.scope === 'project' ? cwd : home, '.grok');
-  const files = discoverPayloadFiles().map(({ relativePath, source }) => ({
-    relativePath,
-    source,
-    target: join(root, relativePath),
-  }));
-  const projectHooksIncluded =
-    options.command === 'install' && options.scope === 'project' && files.some(({ relativePath }) => relativePath.split(sep)[0] === 'hooks');
+  const displayRoot = resolve(root);
+  const payloadStarted = process.hrtime.bigint();
+  let discoveredPayload;
+  let payloadError;
+  try {
+    discoveredPayload = discoverPayloadFiles();
+  } catch (error) {
+    payloadError = error;
+  }
 
-  function printHookTrustRequirement() {
-    if (projectHooksIncluded) stdout.write('Project hooks require trust before they run: use /hooks-trust or launch Grok Build with --trust.\n');
+  function filesFromPayload(discovered) {
+    return discovered.map(({ relativePath, source }) => ({
+      relativePath,
+      source,
+      target: join(root, relativePath),
+    }));
   }
 
-  printInstallFrame(stdout, options, env, files.length, root);
+  function projectHooksIncluded(files) {
+    return options.command === 'install' && options.scope === 'project' && files.some(({ relativePath }) => relativePath.split(sep)[0] === 'hooks');
+  }
+
+  function printHookTrustRequirement(files) {
+    if (projectHooksIncluded(files)) stdout.write('Project hooks require trust before they run: use /hooks-trust or launch Grok Build with --trust.\n');
+  }
+
+  const files = discoveredPayload ? filesFromPayload(discoveredPayload) : null;
+  const payloadElapsed = payloadError ? null : elapsedSince(payloadStarted);
+  const colors = printInstallFrame(stdout, options, env, files?.length, displayRoot);
+
+  if (payloadError) {
+    reportFailure(payloadError, { stderr, stdout, options, root: displayRoot, colors, step: 'PAYLOAD' });
+    return 1;
+  }
 
   const reasons = [];
   if (options.dryRun) reasons.push('DRY RUN');
@@ -155,52 +358,104 @@ export async function run(args, context = {}) {
   if (reasons.length > 0) {
     stdout.write(`${reasons.join(' / ')} — no files written\n`);
     for (const { target } of files) stdout.write(`would ${options.command} ${target}\n`);
-    printHookTrustRequirement();
+    printHookTrustRequirement(files);
     return 0;
   }
 
-  const unsafeAncestor = unsafeInstallAncestor(root, files);
-  if (unsafeAncestor) {
-    stderr.write(`Refusing ${unsafeAncestor.reason} in install path: ${unsafeAncestor.path}\n`);
-    return 1;
-  }
+  const progress = new InstallProgress(stdout, colors);
+  progress.open();
+  let step = 'PAYLOAD';
+  try {
+    progress.finish('ok', 'PAYLOAD', `${files.length} files discovered`, payloadElapsed);
+
+    step = 'SAFETY';
+    runStep(progress, 'SAFETY', () => {
+      const unsafe = unsafeInstallAncestor(root, files);
+      if (unsafe) {
+        const message = `Refusing ${unsafe.reason} in install path: ${unsafe.path}`;
+        const error = new Error(message);
+        error.step = 'SAFETY';
+        error.stderrLines = [message];
+        throw error;
+      }
+      return { value: null, detail: 'install path clear' };
+    });
+
+    step = 'OWNERSHIP';
+    const states = runStep(progress, 'OWNERSHIP', () => {
+      const owned = files.map(({ source, target }) => targetState(source, target));
+      const counts = {
+        missing: owned.filter((state) => state === 'missing').length,
+        current: owned.filter((state) => state === 'current').length,
+        conflicts: owned.filter((state) => state === 'conflict').length,
+      };
+      if (counts.conflicts > 0) {
+        const stderrLines = [];
+        for (let index = 0; index < files.length; index += 1) {
+          if (owned[index] === 'conflict') stderrLines.push(`Refusing to ${options.command === 'install' ? 'overwrite' : 'remove'} different existing file: ${files[index].target}`);
+        }
+        const error = new Error(`${counts.missing} missing · ${counts.current} already-current · ${counts.conflicts} conflicts`);
+        error.step = 'OWNERSHIP';
+        error.stderrLines = stderrLines;
+        throw error;
+      }
+      return {
+        value: { states: owned, counts },
+        detail: `${counts.missing} missing · ${counts.current} already-current · ${counts.conflicts} conflicts`,
+      };
+    });
 
-  const states = files.map(({ source, target }) => targetState(source, target));
-  if (states.includes('conflict')) {
-    for (let index = 0; index < files.length; index += 1) {
-      if (states[index] === 'conflict') stderr.write(`Refusing to ${options.command === 'install' ? 'overwrite' : 'remove'} different existing file: ${files[index].target}\n`);
+    step = 'WRITE';
+    if (options.command === 'uninstall') {
+      const writeStarted = process.hrtime.bigint();
+      progress.start('WRITE');
+      let removed = 0;
+      for (let index = 0; index < files.length; index += 1) {
+        if (states.states[index] !== 'current') continue;
+        unlinkSync(files[index].target);
+        removed += 1;
+      }
+      progress.finish('ok', 'WRITE', `${removed} removed · ${states.counts.missing} already absent`, elapsedSince(writeStarted));
+      const receipt = receiptCard(options, displayRoot, colors, { status: 'Removed', written: 0, current: states.counts.current });
+      progress.close();
+      stdout.write(receipt);
+      return 0;
     }
-    return 1;
-  }
 
-  if (options.command === 'uninstall') {
-    let removed = 0;
-    for (let index = 0; index < files.length; index += 1) {
-      if (states[index] !== 'current') continue;
-      unlinkSync(files[index].target);
-      removed += 1;
+    if (states.states.every((state) => state === 'current')) {
+      skipStep(progress, 'WRITE', `SKIPPED · 0 written · ${states.counts.current} already-current`);
+      const receipt = receiptCard(options, displayRoot, colors, { status: 'Already current', written: 0, current: states.counts.current });
+      progress.close();
+      stdout.write(receipt);
+      return 0;
     }
-    stdout.write(removed === 0 ? `Already absent: ${files.length} files\n` : `Removed ${removed} files\n`);
-    return 0;
-  }
 
-  if (states.every((state) => state === 'current')) {
-    stdout.write(`Already current: ${files.length} files\n`);
-    printHookTrustRequirement();
+    const writeStarted = process.hrtime.bigint();
+    progress.start('WRITE');
+    let installed = 0;
+    try {
+      for (let index = 0; index < files.length; index += 1) {
+        if (states.states[index] === 'current') continue;
+        const { source, target } = files[index];
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(source, target, constants.COPYFILE_EXCL);
+        installed += 1;
+      }
+      progress.finish('ok', 'WRITE', `${installed} written · ${states.counts.current} already-current`, elapsedSince(writeStarted));
+    } catch (error) {
+      progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));
+      if (error && typeof error === 'object') error.step = 'WRITE';
+      throw error;
+    }
+    const receipt = receiptCard(options, displayRoot, colors, { status: 'Ready', written: installed, current: states.counts.current });
+    progress.close();
+    stdout.write(receipt);
     return 0;
+  } catch (error) {
+    progress.close();
+    reportFailure(error, { stderr, stdout, options, root: displayRoot, colors, step });
+    return 1;
   }
-
-  let installed = 0;
-  for (let index = 0; index < files.length; index += 1) {
-    if (states[index] === 'current') continue;
-    const { source, target } = files[index];
-    mkdirSync(dirname(target), { recursive: true });
-    copyFileSync(source, target, constants.COPYFILE_EXCL);
-    installed += 1;
-  }
-  stdout.write(`Installed ${installed} files\n`);
-  printHookTrustRequirement();
-  return 0;
 }
 
 if (process.argv[1] && realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok-ai",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Grok Build skills, project rules, and hooks installer.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
     "litgrok": "bin/litgrok.mjs"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "check:version": "node tools/check-version-lockstep.mjs"
   },
   "files": [
     "plugin.json",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"