docs: truth sweep after 1.2.0 — dead install tag, grok omissions, lint inventory, orphan assets

.gitattributes

@@ -11,7 +11,6 @@ PLAN.md             export-ignore
 SOURCE_REF          export-subst
 docs/plan-archive/ export-ignore
 scripts/shadow-brief.py export-ignore
-docs/assets/brief-decision.png export-ignore
 docs/superpowers/ export-ignore
 # Docs authoring surface: claudux preferences and the local VitePress preview
 # scaffold. The shipped product is the Markdown under docs/, never the Node

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- Docs truth sweep: the guide pages no longer pin the never-tagged
+  `shadow-v1.0.1` (install tags are now contract-tested against `VERSION`);
+  Grok joins every host enumeration, the doctor/amp help text, and the config
+  table; the lint inventory names all 32 real checks (`PLAN-SECRET`, not
+  `PROOF-SECRET`; blocking `PROOF-ARGV0` documented); accept's `--repo` rule,
+  the 262144-byte refusal paths with their three remedies, and archive
+  eligibility are documented; two orphaned docs assets deleted;
+  `scripts/shadow_version.py` joins the packaging contract.
+
 ## 1.2.0 — 2026-08-18 — the test layer stops lying, and the plan cannot strand itself
 
 - The starvation guard no longer disables the tests it protects: a caller's

README.md

@@ -1,11 +1,11 @@
-<p align="center"><img src="assets/shadow-banner.svg" alt="Shadow's loop: read the plan, choose the next checkpoint, act, verify, and leave a resumable checkpoint." width="100%" /></p>
+<p align="center"><img src="assets/shadow-banner.svg" alt="The Shadow loop — board, claim, work, prove, accept — orbiting one glowing checkpoint labeled resume here." width="100%" /></p>
 
 # Shadow
 
 **Shadow is you, one step down.** Say what you want in any wired AI coding
-host — Claude Code, Codex, Cursor — and Shadow keeps the work durable: one
-board per computer, one `PLAN.md` per project, a proof receipt on every
-finished step. Kill any chat; the next session resumes where it stopped.
+host — Claude Code, Codex, Cursor, Grok — and Shadow keeps the work
+durable: one board per computer, one `PLAN.md` per project, a proof receipt
+on every finished step. Kill any chat; the next session resumes where it stopped.
 
 Six words carry the system:
 
@@ -29,8 +29,8 @@ cd shadow && bash install.sh && shadow doctor
 
 Git, Bash, Python 3.10+, and a supported host. No Node, no daemon, no
 transcript store. The clone is the install; to upgrade, check out the
-newer `shadow-v*` tag and rerun `install.sh`. If `shadow` is not found,
-add `~/.local/bin` to your PATH.
+newer `shadow-v*` tag and rerun `install.sh`. Missing `shadow`? Add
+`~/.local/bin` to PATH.
 
 ## First run
 
@@ -74,6 +74,8 @@ Shadow refuses unclaimed execution, missing proof, and ambiguous authority.
 ## Docs
 
 The full contract — every verb, plan grammar, extensions, privacy — lives at
-**[the docs site](https://firstbitelabsllc.github.io/shadow/)**; developing Shadow starts at [`AGENT.md`](AGENT.md).
+**[the docs site](https://firstbitelabsllc.github.io/shadow/)**; developing starts at
+[`AGENT.md`](AGENT.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) — external
+PRs are closed.
 
-MIT License.
+[MIT License](LICENSE).

bin/shadow

@@ -175,8 +175,8 @@ requires a live claim owned by --by; use shadow throw to claim new work.
 
 exit codes:
   0   block printed (char count on stderr)
-  1   no open task (mint the successor) or the resume row itself exceeds
-      the budget
+  1   no claim to resume: the row is claimed by another seat, not claimed
+      by --by, or the owned row is not executable work
   2   no plan found or invalid usage
 EOF
       ;;
@@ -346,7 +346,7 @@ shadow doctor — read-only installation and native-host doctor.
 usage: shadow doctor [--json] [--help|-h]
 
 Checks product identity, Python, Git, PATH installation, native Codex/Claude
-Code/Cursor availability, those three skill mounts, and whether each host's
+Code/Cursor/Grok availability, those four skill mounts, and whether each host's
 instruction file carries the current standing goal. It is read-only and never
 fetches, repairs, authenticates, or runs the test suite. Missing optional hosts
 or mounts warn; contradictory product identity or mount custody fails.

docs/guide/index.md

@@ -3,7 +3,7 @@
 Shadow is a local product with two durable jobs:
 
 1. Brief you on the Outcome, active lanes, proof, and any real hard-rail decision.
-2. Claim and dispatch path-disjoint work to native Codex, Claude Code, or Cursor,
+2. Claim and dispatch path-disjoint work to native Codex, Claude Code, Cursor, or Grok,
    then integrate proof and continue through every reachable row.
 
 Its one root board per computer groups entity pointers under projects and

docs/guide/installation.md

@@ -4,7 +4,7 @@ Requirements: Git, Bash, Python 3.10+, and one supported native coding host.
 No Node, no npm, no package manager — the stable release clone *is* the install.
 
 ```bash
-git clone --branch shadow-v1.0.1 --depth 1 \
+git clone --branch shadow-v1.2.0 --depth 1 \
   https://github.com/firstbitelabsllc/shadow.git
 cd shadow
 bash install.sh
@@ -17,7 +17,7 @@ only when you deliberately want moving development source.
 
 `install.sh` links `bin/shadow` into `~/.local/bin` and mounts the skill in
 every host root that already exists (`~/.claude/skills`, `~/.agents/skills`,
-`~/.cursor/skills`). Two flags change that:
+`~/.cursor/skills`, `~/.grok/skills`). Two flags change that:
 
 ```bash
 bash install.sh --bin-dir /usr/local/bin   # put the command somewhere else
@@ -39,5 +39,5 @@ Shadow shipped under a different name before 0.1.0. Its compatibility path is
 gone: evidence lives in `.shadow/`, and a repository still carrying the
 pre-rename evidence directory shows as dirty until that directory is renamed
 to `.shadow/` or deleted. Remove the old global install and its mounts, then
-re-run `bash install.sh` so `~/.claude/skills`, `~/.agents/skills`, and
-`~/.cursor/skills` point at this checkout.
+re-run `bash install.sh` so `~/.claude/skills`, `~/.agents/skills`,
+`~/.cursor/skills`, and `~/.grok/skills` point at this checkout.

docs/guide/other-computer-handoff.md

@@ -5,15 +5,15 @@ This is the portable starting point for Shadow on another Mac.
 ## Bootstrap
 
 ```bash
-git clone --branch shadow-v1.0.1 --depth 1 \
+git clone --branch shadow-v1.2.0 --depth 1 \
   https://github.com/firstbitelabsllc/shadow.git
 cd shadow
 bash install.sh
 shadow doctor
 ```
 
 `install.sh` links the command and mounts the same skill in each native host
-root that exists (`~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills`).
+root that exists (`~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills`, `~/.grok/skills`).
 Pass `--no-skills` to link the command alone.
 
 Expected result: `shadow doctor` reports product identity, command, and the
@@ -47,6 +47,7 @@ transcripts, provider payloads, or absolute private paths in it.
 | Surface | Use it for |
 | --- | --- |
 | `/shadow` | Start/resume work, read the Outcome, drain reachable lanes, and leave proof plus successors. |
+| `/amplify` | Shape a loose intent into one durable PLAN plus a four-line goal launcher. The native `shadow goal` verb prints the standing goal; this skill (renamed from `goal` in 1.2.0) is the shaper. |
 
 `shadow amp` is a CLI subcommand, not a mounted skill: it projects a
 paste-ready resume block for a checkpoint the seat already claimed — see
@@ -58,7 +59,7 @@ adversarial-lens slug — post-work review, a different moment — or a person
 may delegate foresight to their own method). Diagrams stay Brief-contract
 law, no slot involved.
 
-Use native Codex, Claude Code, or Cursor for execution. Provider-specific
+Use native Codex, Claude Code, Cursor, or Grok for execution. Provider-specific
 helpers are adapters; none becomes the plan authority or stores credentials.
 
 ## Read the public state

docs/guide/publishing.md

@@ -20,6 +20,7 @@ flowchart LR
 | ChatGPT and Codex | The `plugins/shadow/.codex-plugin` package and repo marketplace expose the same Shadow skill and goal shaper. | Full status and action require a local host that can read the board and run Shadow. A hosted chat is a coach only. |
 | Claude Code | The existing `.claude-plugin` package installs the same source skill. | Local board access follows the existing install and host rules. |
 | Cursor | The checked-in skill works through Cursor's local skill/plugin support. | Cursor can act only where the local checkout and host integration are available. |
+| Grok | `install.sh` mounts `~/.grok/skills` and `shadow goal --install` writes `~/.grok/AGENTS.md`. | Grok acts only through the sealed native host runner on a local checkout. |
 | Custom GPT | The skill prose can seed a friendly “Shadow Coach” for goal shaping and explanation. | A Custom GPT is not real Shadow until a reviewed remote bridge exists. It must say that it cannot see the local board. |
 | MCP directories | A future remote adapter could expose a privacy-safe brief and typed intent return. | No server is published today. The local board remains authority; a remote service may not copy the queue, credentials, or transcripts. |
 

docs/guide/quickstart.md

@@ -80,6 +80,8 @@ For a passing `cmd` proof, use the only flip path:
 
 ```bash
 shadow accept --repo . --row '~ab12' --by your-seat
+# --repo is where proofs RUN (the product checkout); a machine-local
+# plan's own directory also works when its proof argv cds there itself
 ```
 
 For a remotely coordinated claim, ordinary accept publishes the completed

docs/index.md

@@ -4,7 +4,7 @@ layout: home
 hero:
   name: Shadow
   text: Your coding chief of staff
-  tagline: Understand the work, choose what happens next, and safely use Codex, Claude Code, or Cursor.
+  tagline: Understand the work, choose what happens next, and safely use Codex, Claude Code, Cursor, or Grok.
   actions:
     - theme: brand
       text: Start in five minutes

docs/reference/browser.md

@@ -10,3 +10,9 @@
 Choice receipts are atomic and idempotent under the selected Git project's
 `.shadow/evidence/` directory. The browser never receives a credential,
 prompt, transcript, provider payload, or absolute private path.
+
+## Host header allowance
+
+`shadow browse --allow-host NAME` (repeatable) widens only the accepted
+`Host` header, for a self-run proxy such as `tailscale serve` in front of the
+loopback server. The bind itself never leaves loopback; no flag changes that.

docs/reference/commands.md

@@ -7,17 +7,17 @@ Every verb `bin/shadow` dispatches. `shadow help <command>` gives exact flags.
 | `shadow init --here` | Create `PLAN.md` without overwriting one. |
 | `shadow status --by <seat> [--root PATH] [--shadowed]` | Read this computer's root board, project authenticated active remote coordination locks for known PLAN rows, then rank checkpoints. `--root` changes only the bounded import root; it never bypasses or writes the board. `--shadowed` adds safe reasons for suppressed or retired copies. |
 | `shadow status --in-flight` | Every local claim plus authenticated remote-lock observation, joined at read time to project-owned text and proof — the recovery view after a chat dies. Add `--json` for a machine-readable end-of-chat footer. |
-| `shadow config --explain [--repo PATH]` | Read the optional repository-root `shadow.yaml` declaration, or report the built-in version 1 defaults when it is absent. It prints the attack-then-refute step and active review lenses; the command is read-only and writes no resolved state. |
+| `shadow config --explain [--repo PATH] [--json]` | Read the optional repository-root `shadow.yaml` declaration, or report the built-in version 1 defaults when it is absent. It prints the attack-then-refute step and active review lenses; the command is read-only and writes no resolved state. |
 | `shadow goal [--install|--remove] [--host HOST]` | Print the static standing goal, or install/remove its managed block in supported host instruction files (Claude Code, Codex, Grok). Cursor cold directive activation is unsupported until a reviewed writable user-rule surface exists; its skill mount and sealed host runner remain supported. |
 | `shadow amp --entity ID --by <seat>` | Resume a paste-ready packet for a checkpoint already claimed by that seat. It never dispatches unclaimed work. |
 | `shadow throw --task '~hash' --by <seat> [--repo PATH\|--entity ID]` | Atomically claim an entity checkpoint before work leaves the seat, then print its packet. A unique legacy text alias such as `P9a~formats` may be supplied, but it resolves to the row's canonical `~hash` before the claim. The board records pointer, canonical row id, owner, lease, and recovery action; the entity plan is unchanged. A configured origin upstream also requires the deterministic remote coordination CAS. `--adopt-expired` replaces only an overdue claim after proof was probed. |
-| `shadow return --row '~hash' --by <seat> [--repo PATH\|--entity ID]` | Idempotently append a remote released tombstone when remote coordination is active, then close the named owner's exact local claim after a committed manual proof, a committed blocked state plus one Deferred wake, or an explicit handback. |
-| `shadow priority --value 1..5 --repo PATH` | Change the root-board priority under the same local transaction. The project plan's bootstrap value is unchanged and later discovery cannot overwrite the root decision. |
-| `shadow accept --row '~hash' --repo PATH --by <seat> [--no-push]` | Require that seat's live claim and rerun the committed `cmd` proof in a clean detached checkout. Normally it flips and publishes the paired PROOF commit, appends the remote completed tombstone, then closes the local claim. A registered machine-local plan instead atomically flips only its private authority after the same clean source-checkout proof. For a remotely coordinated claim, `--no-push` keeps both claims open for a later publishing retry. |
-| `shadow lifecycle [--repo PATH] [--milestone 'heading'\|--retirement-manifest /ABS/file.json]` | Dry-run the hot-plan limits or one exact manifested retirement and emit a CAS. Apply requires explicit `--repo PATH --apply --expect CAS --by <seat>`. Archives are content-addressed, recover exact-CAS half-writes, can monotonically compact an over-limit plan across finite passes, and bind one successor row or `null` once the plan is within limits. Retirement paths must use canonical absolute spellings with no symlink component. It accepts only one clean landed non-primary linked worktree without any submodule, or one clean expired same-entity snapshot recoverable from its declared ref; it journals the exact target, never forces deletion, and commits a path-free receipt with the same bound successor. The named seat claims that row only when present, reachable, and unclaimed; the original CAS makes a completed exact repeat a no-op. |
+| `shadow return --row '~hash' --by <seat> [--repo PATH\|--entity ID]` | Idempotently append a remote released tombstone when remote coordination is active, then close the named owner's exact local claim after a committed manual proof, a committed blocked state plus one Deferred wake, or an explicit handback, and advance that claim's resume pointer. |
+| `shadow priority --value 1..5 [--repo PATH]` | Change the root-board priority under the same local transaction. The project plan's bootstrap value is unchanged and later discovery cannot overwrite the root decision. |
+| `shadow accept --row '~hash' --repo PATH --by <seat> [--timeout-seconds N] [--no-push]` | Require that seat's live claim and rerun the committed `cmd` proof in a clean detached checkout. Normally it flips and publishes the paired PROOF commit, appends the remote completed tombstone, then closes the local claim. A registered machine-local plan instead atomically flips only its private authority after the same clean source-checkout proof. For a remotely coordinated claim, `--no-push` keeps both claims open for a later publishing retry. A rejected push exits 3 naming the pull-request path. `--repo` is the root where proofs RUN, not where the plan lives; a machine-local plan's own directory also works when its committed proof argv changes into the product checkout itself. |
+| `shadow lifecycle [--repo PATH] [--json] [--milestone 'heading'\|--retirement-manifest /ABS/file.json]` | Dry-run the hot-plan limits or one exact manifested retirement and emit a CAS. Apply requires explicit `--repo PATH --apply --expect CAS --by <seat>`. Archives are content-addressed, recover exact-CAS half-writes, can monotonically compact an over-limit plan across finite passes, and bind one successor row or `null` once the plan is within limits. Retirement paths must use canonical absolute spellings with no symlink component. It accepts only one clean landed non-primary linked worktree without any submodule, or one clean expired same-entity snapshot recoverable from its declared ref; it journals the exact target, never forces deletion, and commits a path-free receipt with the same bound successor. The named seat claims that row only when present, reachable, and unclaimed; the original CAS makes a completed exact repeat a no-op. |
 | `shadow plan migrate /ABS/PLAN.md --dry-run` | Build and verify the complete partitioned candidate with zero writes. Apply requires `--apply --expect SOURCE_SHA256`; `shadow plan rollback … --expect ROOT_SHA256` restores the exact prior root. An optional absolute `--board` binds the receipt while leaving pointers, claims, owners, and resume unchanged. |
 | `shadow lint [--repo PATH] PLAN.md …` | Check plans against the grammar; blocking findings exit non-zero. A registered machine-local plan uses `--repo` to check proof scripts at its source checkout's committed HEAD. |
-| `shadow browse --root PATH` | Start the loopback briefing UI. |
+| `shadow browse --root PATH [--no-open] [--port N] [--host HOST] [--allow-host NAME ...]` | Start the loopback briefing UI. `--allow-host` (repeatable) only widens the accepted `Host` header for a self-run proxy; the bind stays loopback. |
 | `shadow host probe --host HOST` | Check a native host without using it. |
 | `shadow host run …` | Run a claimed task in its clean worktree; invoke again for path-disjoint lanes. |
 | `shadow slots` | Report which extension slots are filled. Absent is a WARN and exits 0; a wrong binding FAILs. No slot reads tooling Shadow does not itself call. |

docs/reference/config.md

@@ -67,6 +67,7 @@ These environment variables provide runtime defaults:
 | `SHADOW_CODEX_BIN` | Optional Codex executable override. |
 | `SHADOW_CLAUDE_CODE_BIN` | Optional Claude Code executable override. |
 | `SHADOW_CURSOR_BIN` | Optional Cursor executable override. |
+| `SHADOW_GROK_BIN` | Optional Grok executable override. |
 | `SHADOW_TELEMETRY` | Set exactly to `local` to append closed, local-only lifecycle events beneath the current project's `.shadow/evidence/`; unset and every other value write nothing. |
 | `SHADOW_AMP_PACK_ROOT` | Amp-core pack-root override (absolute path, or `off` to disable pack inspection) — not a slot binding. See [amp.md](amp.md). |