phewsh 0.15.82 → 0.15.83

package/README.md

@@ -1,11 +1,11 @@
 # phewsh
 
-**One mission. Many AI tools. No lost context.**
+**The next AI starts from your files.**
 
 PHEWSH is the continuity layer for AI-assisted work: it turns what you're
 building into durable project intent (`.intent/`) and carries it across
 Claude Code, Codex, Cursor, Gemini, your terminal, and your team — so the
-next AI knows what the last one learned.
+next AI can see what was recorded — and what was not.
 
 ## Install
 
@@ -13,20 +13,35 @@ next AI knows what the last one learned.
 curl -fsSL https://phewsh.com/install.sh | sh
 ```
 
-No sudo, nvm-aware. (Prefer a package manager? `npm install -g phewsh` —
-same artifact, built from this repo.)
+The installer never runs npm with sudo and is nvm-aware. If an older Phewsh
+install is root-owned, it discloses and requests one `sudo chown` repair first.
+(Prefer a package manager? `npm install -g phewsh` installs the same npm package.)
 
 Then let it improve the AI tools you already have — without launching anything:
 
 ```bash
-phewsh ambient on    # your .intent/ + a verified brief reach Claude Code, Codex,
-                     # Gemini, Cursor at the start of every session (reversible)
+phewsh ambient on    # one open intent skill + your verified .intent/ brief reach
+                     # Claude Code, Codex, Gemini, Cursor (reversible)
 ```
 
+A bare first launch keeps adapters off. `ambient on` enumerates every file it
+may write before asking; choosing No changes only Phewsh's local opt-out receipt.
+
 phewsh isn't just a CLI — `ambient` makes every supported tool start aligned to
 what you're building. What it reads, writes, and sends is documented, factually,
-in [SECURITY.md](./SECURITY.md). It's local-first and MIT; this repo is an exact
-mirror of the published npm package.
+in [SECURITY.md](./SECURITY.md), the [threat model](./docs/threat-model.md), and
+the [release checklist](./docs/release-checklist.md). It's local-first and MIT;
+the public source snapshot is manually synchronized today, without release
+provenance yet.
+
+`phewsh init` creates only the tool-neutral `.intent/` project record. Ambient
+installs the same open `intent` skill at user scope for Codex
+(`~/.agents/skills/intent/`) and Claude Code (`~/.claude/skills/intent/`), so
+projects stay clean and neither harness becomes the source of truth.
+If a repository already contains `.agents/skills/intent/` or
+`.claude/skills/intent/`, that user-owned project override may take precedence.
+Phewsh reports it through `status` and `ambient status` but never edits or
+removes it; `.intent/` remains the project truth.
 
 ## Quick Start
 
@@ -38,6 +53,14 @@ phewsh next start 1
 phewsh codex        # verified brief → native tool → automatic postflight
 ```
 
+Every native handoff now leaves an integrity-checksummed local receipt. The next tool sees the
+exact `.intent/` and repository state that crossed the boundary, plus an
+explicit list of what did not: transcripts, model reasoning, editor buffers,
+harness-local memory, and unrecorded decisions. `phewsh status` re-hashes the
+current state and says **verified**, **moved**, **partial**, or **invalid**
+instead of silently claiming continuity. Dirty evidence means Git tracked,
+staged, and untracked-unignored files; ignored files are never hashed or named.
+
 ## No API key needed
 
 phewsh is not another agent — it's the layer that uses the ones you already
@@ -54,17 +77,20 @@ phewsh ai providers                           # see what's installed
 API keys (OpenRouter, Anthropic, Groq, …) and PHEWSH pooled credits remain
 available as alternatives — `phewsh login --set-key`.
 
-## One package, one system
+## One package, modular adapters
 
-Everything ships in `phewsh` — the CLI (intent authoring, sync, bridges,
-receipts, dispatch) *and* the MCP server. `phewsh mcp setup` wires the
-bundled server into Claude Code / Cursor / any MCP client via
-`phewsh mcp serve --stdio`: an *interactive* agent session gets your
-project's briefing, task queue, and enforcement gate over stdio, and shares
-state with the bridges (`~/.phewsh/`). No second install.
+The package includes the CLI plus optional native skills, hooks, projections,
+MCP capabilities, and bridges. They all adapt tools around `.intent/`; none is
+a second project record.
 
-Rule of thumb: `phewsh serve` = dispatch tasks *to* your agents.
-`phewsh mcp setup` = your agents pull tasks *from* PHEWSH mid-session.
+`phewsh mcp setup` adds the bundled stdio adapter to a supported client. That
+client can receive bounded Project, Next, constraints, and task capabilities.
+MCP access does not claim work, transfer private model memory, or grant remote
+execution authority.
+
+Rule of thumb: `phewsh serve` is the same-machine, project-bound worker used
+after a human claim. `phewsh mcp setup` lets a configured client read and report
+through bounded capabilities during its own session.
 
 ## Ambient — continuity without launching phewsh
 
@@ -72,23 +98,41 @@ Rule of thumb: `phewsh serve` = dispatch tasks *to* your agents.
 phewsh ambient on
 ```
 
-A consent screen shows exactly what changes. Phewsh then keeps one canonical
-generated core aligned across `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and
-`.cursorrules`, while preserving human-authored content outside its managed
-blocks. Claude Code also receives a session-start brief and leaves a one-line
-metadata breadcrumb (never transcript contents) in
-`~/.phewsh/ambient-sessions.jsonl`. `phewsh ambient status` shows the ledger;
-`phewsh ambient off` removes Phewsh-managed blocks without deleting your notes.
+A consent screen shows exactly what changes. The layers stay independent:
+
+- one byte-identical open Intent skill installs natively for Claude Code and Codex;
+- generated blocks align `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and
+  `.cursorrules` while preserving human-authored content;
+- Claude Code session hooks add a bounded start brief and a metadata-only end
+  breadcrumb; safety/receipt hooks for Claude and Codex are controlled by the
+  separate `phewsh gate enforce on|off|status` toggle.
 
-## Live Execution
+`phewsh ambient status` reports those layers separately. `phewsh ambient off`
+removes only unchanged Phewsh-managed additions and preserves user-owned skills,
+hooks, and notes. It does not disable the independent safety/receipt layer.
 
-Connect the web app to your local machine for real-time task execution:
+## Ion — work with people and agents
+
+[Phewsh Ion](https://phewsh.com/ion) is the shared project room. A person
+requests work, a human deliberately claims it for a local agent, and the
+branch, pull request, evidence, review, and accepted Record return to the same
+room.
+
+Make a repository available to **your own machine's** worker:
 
 ```bash
-phewsh serve
+phewsh project add    # once inside each repo you explicitly allow
+phewsh serve          # one loopback worker for the whole machine
+phewsh ion doctor     # read-only two-person preflight
 ```
 
-This starts a bridge on `localhost:7483`. Open [phewsh.com/intent](https://phewsh.com/intent) and go to the Work tab — you'll see a green "Live" indicator. Agent tasks get a "Run Live" button that executes on your machine through whichever agent CLIs you have installed: **Claude Code, Codex, Gemini, Cursor Agent, OpenCode**. PHEWSH detects them automatically and every run leaves a receipt (`phewsh receipts`).
+The bridge listens on `localhost:7483`. Registration does not execute work,
+teammates cannot reach your localhost, and Ion does not grant remote execution
+authority. Work begins only after a human clicks **Run on this machine** in
+their browser or runs `phewsh ion claim <task-id>`. The claim runs in an
+isolated Git worktree, opens a PR through your authenticated `gh`, and returns
+bounded evidence to Ion; accepted work becomes project truth only through
+normal review, merge, and Record reconciliation.
 
 ## Interactive Shell
 
@@ -120,7 +164,7 @@ cancel an in-flight provider turn.
 
 ## The four answers
 
-Phewsh keeps the same four answers available to you and every harness:
+Phewsh records four answers that supported harness adapters can read:
 
 - **Project** — what you are building and why (`.intent/`)
 - **Next** — the current task and accepted success criteria (`.intent/next.json`)
@@ -128,8 +172,14 @@ Phewsh keeps the same four answers available to you and every harness:
 - **Record** — what happened, what was kept, and what was learned
 
 The lifecycle is explicit: intent → criteria → verified brief → native tool →
-observed evidence → verdict → approved reconciliation → every other tool
-inherits the updated truth.
+observed evidence → verdict → approved reconciliation → supported adapters can
+read the updated project record. Native transcripts and hidden tool memory do
+not cross that boundary.
+
+Want to falsify that claim without an AI subscription? Run the exact public
+[Claude Code → Codex handoff fixture](./docs/handoff-proof.md). It writes the
+receipt before any destination-model output and verifies the checkout using the
+same receipt code as the CLI.
 
 ## All Commands
 
@@ -141,10 +191,11 @@ phewsh next               # Queue work and define success criteria
 phewsh work               # Current work + verification + human review
 phewsh truth              # Read-only source-of-truth audit
 phewsh brief              # Verified state + accepted work contract
-phewsh watch              # Sync native harness files + optional cloud mirror
-phewsh ambient on         # Automatic cross-tool continuity, with consent
+phewsh seq --write        # One-shot .intent/ refresh into all native project files
+phewsh watch              # Deliberately running native refresh + optional cloud push
+phewsh ambient on         # Preview + install reversible native adapters
 phewsh outcomes           # Decision record — what was kept, reverted, or failed
-phewsh serve              # Live execution bridge for web app
+phewsh serve              # Same-machine worker; human-initiated, project-bound claims
 phewsh clarify            # AI-assisted artifact generation
 phewsh intent --init      # Create .intent/ without entering the shell
 phewsh intent --status    # Check artifact state
@@ -152,8 +203,8 @@ phewsh ai run "prompt"    # One-shot AI with .intent/ context
 phewsh login              # Authenticate + set API key
 phewsh push               # Sync local .intent/ to cloud
 phewsh pull               # Sync cloud to local
-phewsh mcp setup          # Configure MCP server for agent connectivity
-phewsh mcp serve          # Coordination bridge — route work to live agents
+phewsh mcp setup          # Configure the optional bounded MCP adapter
+phewsh mcp serve          # Serve bounded capabilities over stdio/HTTP
 phewsh receipts           # Proof trail — what agents actually did, with evidence
 phewsh update             # Update phewsh to the latest version
 phewsh style              # Build your style identity
@@ -161,8 +212,9 @@ phewsh style              # Build your style identity
 
 ## Receipts
 
-Every task that runs through PHEWSH leaves evidence on your machine —
-sessions, results, blockers, gate checks, spend — in `~/.phewsh/`. See it:
+Every task and native tool handoff that runs through PHEWSH leaves evidence on
+your machine — sessions, results, blockers, gate checks, handoff receipts, spend
+— in `~/.phewsh/`. See it:
 
 ```bash
 phewsh receipts           # merged timeline, newest first
@@ -170,9 +222,14 @@ phewsh receipts --json    # machine-readable, for agents and scripts
 ```
 
 The same trail is visible at [phewsh.com/intent/receipts](https://phewsh.com/intent/receipts)
-while a local bridge is running (`phewsh serve` or `phewsh mcp serve` — the
-first executes tasks directly via Claude Code, the second routes them to
-live connected agents; both record identical receipts).
+only while this browser can reach a local bridge. `phewsh serve` supports the
+same-machine manual-claim path; `phewsh mcp serve` exposes the optional adapter.
+Neither makes a teammate's browser able to reach your localhost or grants
+cross-machine execution authority.
+
+Handoff receipts live in `~/.phewsh/handoffs/`. They contain paths and SHA-256
+fingerprints, never file contents or transcripts. A hash detects corruption or
+an unrecomputed edit; it is integrity evidence, not authenticated identity.
 
 ## Outcomes
 
@@ -202,8 +259,25 @@ phewsh push         # upload .intent/ to cloud
 phewsh pull         # download from cloud
 ```
 
-Cloud sync is manual. Local harness projections self-heal automatically from
-the same canonical `.intent/` source.
+Cloud sync is never triggered by `init`, `ambient`, or `seq`. `phewsh push` is
+the explicit one-shot upload. Deliberately starting `phewsh watch` opts into
+automatic push while that process runs for a signed-in user; use
+`phewsh watch --no-push` for local projections only. Local harness projections
+self-heal from the same canonical `.intent/` source.
+
+## Environment variables
+
+All optional; phewsh needs no configuration to run. None of these hold secrets.
+
+| Variable | Effect |
+|---|---|
+| `PHEWSH_DEBUG` | Verbose diagnostics for session handling |
+| `PHEWSH_OFFLINE` | Skip network checks in the truth audit (`phewsh truth`) |
+| `PHEWSH_WIDTH` | Override terminal width when the terminal misreports it |
+| `PHEWSH_AUTOWORK` | Auto-run `/work` on session start (used by the `phewsh <harness>` shortcut) |
+| `PHEWSH_MCP_PORT` / `PHEWSH_MCP_HOST` | Bind address for the local MCP HTTP bridge |
+| `PHEWSH_ALLOWED_ORIGINS` | Extra CORS origins for the local serve bridge (loopback by default) |
+| `PHEWSH_PROJECT_INDEX` | Override the path of the local project index |
 
 ## Web app
 

package/SECURITY.md

@@ -1,97 +1,117 @@
 # Security & Data Flow — phewsh CLI
 
-phewsh is a **local-first** tool. It runs on your machine, reads your project's
-`.intent/` and your installed AI tools' config, and helps you carry context
-between those tools. This document states — factually, traceable to source —
-what it reads, writes, and sends. No vague claims; if something here is wrong,
-it's a bug: **hello@phewsh.com**.
-
-> Status: this is an honest self-documented inventory, **not** an independent
-> audit. The CLI source is **public and MIT-licensed** at
-> **github.com/cleverIdeaz/phewsh-cli** — an exact mirror of the published npm
-> package, so you can read exactly what you install (`bin/ commands/ lib/ mcp/`).
-> An independent review is still planned (see "Roadmap").
+Phewsh is a **local-first continuity layer**, not a sandbox. It reads project
+records, projects bounded context into supported AI tools, and can launch tools
+that run with your user account's authority. This page is a source-backed
+inventory of what the CLI reads, writes, and sends.
+
+> **Status:** self-documented and tested, **not independently audited**. The
+> MIT-licensed source snapshot is public at
+> [cleverIdeaz/phewsh-cli](https://github.com/cleverIdeaz/phewsh-cli). The npm
+> artifact is manually published today and is not yet cryptographically linked
+> to that repository. See the [threat model](./docs/threat-model.md) and
+> [release integrity checklist](./docs/release-checklist.md).
 
 ## What phewsh reads
-- **`.intent/`** in your project (`vision.md`, `plan.md`, `status.md`, `next.md`,
-  `project.json`, `next.json`). This is the source of truth it projects.
-- **Your tools' context files** when present: `CLAUDE.md`, `AGENTS.md`,
-  `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`, `README.md`.
-- **Your Claude project memory** (`~/.claude/projects/<cwd>/memory/MEMORY.md` and
-  files it links) and **global per-user memory** (`~/.claude/CLAUDE.md`,
-  `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`) — read-only, used to enrich the
-  `phewsh seq` summary. Global memory is **never** written into a project file
-  unless you pass `--include-global` (`lib/sequencer/index.js`).
-- **Git status** of the current repo (read-only: `git status`, HEAD, diff stats).
-
-## What phewsh writes (and where)
-Every generated block is wrapped in `<!-- PHEWSH:START -->` / `<!-- PHEWSH:END -->`
-markers; **content outside the markers is preserved byte-for-byte** (tested).
-- **Project context files** — the canonical `.intent/` projection into
-  `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursorrules` (only files that
-  already exist, unless you create them). One canonical projector
-  (`lib/selfheal.js`) is the single writer.
-- **`~/.phewsh/`** — `config.json` (your settings/keys, mode **0600**, dir 0700),
-  `briefs/` (saved handoff briefs), `sessions/`, `receipts/`, ledger files.
-- **Shell rc** — only if you run `phewsh shim on` (adds one PATH line; reversible
-  with `phewsh shim off`).
-- **Global base files** — only if you run `phewsh ambient on`: a marker-wrapped
-  block in `~/.claude/CLAUDE.md` etc. for tools you already have. Reversible with
-  `phewsh ambient off`.
-- **Claude Code hook** — `phewsh ambient on` registers `SessionStart`/`SessionEnd`
-  hooks (context injection + a metadata breadcrumb; **never your transcript**).
-
-## Network calls (exactly these)
-phewsh makes **no network calls for its core local features** (sequencing,
-projection, briefs, status). Calls happen only for these named actions:
-- **`api.anthropic.com` / `openrouter.ai` / `api.together.xyz`** — only if you set
-  a BYOK key and use `/run` or the API route. Your key goes **directly** to the
-  provider; it is **not** proxied through phewsh servers.
-- **`registry.npmjs.org`** — version check for `phewsh update` (notify-only by
-  default).
-- **`<project>.supabase.co`** — only if you `/login`: auth + optional cloud sync
-  of your `.intent/` (you initiate `push`/`pull`).
-- **`phewsh.com`** — only for `phewsh serve`/cloud-bridge actions you start.
-- **Sustainability telemetry** (`trackSap`, `lib/supabase.js`) — sends **model
-  name, token counts, and a kWh estimate only**. No prompts, no responses, no
-  file contents. Tied to your account id only when logged in.
+
+- Project truth in `.intent/`, plus Git status, HEAD, and diff statistics.
+- Existing native context files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
+  `.cursorrules`, Copilot instructions, and `README.md`.
+- Claude project/global memory and other supported tools' global context files
+  when building a `phewsh seq` summary. Global content is not copied into a
+  project unless you pass `--include-global`.
+- Local Phewsh configuration, receipts, decisions, and session metadata.
+
+Phewsh does not read or store native tool transcripts through its ambient
+hooks. A native tool may still read files or send prompts under that tool's own
+permissions and policy.
+
+## What phewsh writes
+
+- Marker-wrapped projections in supported native context files. Content outside
+  `<!-- PHEWSH:START -->` / `<!-- PHEWSH:END -->` is preserved.
+- Local state under `~/.phewsh/`: configuration, briefs, handoff receipts,
+  session metadata, and ledgers. `config.json` and handoff receipt paths are
+  explicitly owner-only (`0600` files, `0700` directories) on POSIX systems.
+  Other local ledgers rely on the owning account and process umask today; treat
+  the whole directory as sensitive.
+- A reversible PATH line only after `phewsh shim on`.
+- Reversible, marker-wrapped global adapter blocks and unmodified Phewsh-owned
+  intent-skill copies only after `phewsh ambient on`.
+- Claude Code and Codex lifecycle/safety hooks after `phewsh ambient on`.
+
+Handoff receipts contain paths, fingerprints, Git state, route labels, and a
+brief hash—not file contents, prompts, responses, transcripts, or model
+reasoning. Gitignored files are not named or hashed. Browser-facing receipt
+views are redacted. A SHA-256 match detects later change; it is **not a
+signature** and does not prove who created the receipt.
+
+## Network boundaries
+
+Core projection, status, local brief generation, and receipt verification can
+run without network access. Network calls occur when a user selects a feature
+that needs them, including:
+
+- npm registry version checks and optional updates;
+- direct requests to configured model providers, a configured custom endpoint,
+  local Ollama, or Phewsh's pooled provider route;
+- Supabase authentication, cloud sync, Ion/team features, and sustainability
+  telemetry;
+- user-requested URL browsing, YouTube captions, GitHub API feedback/listing,
+  and OAuth flows;
+- same-machine HTTP bridges started by the user.
+
+BYOK requests go to the selected provider or configured endpoint. The endpoint
+receives the prompt supplied to that provider. Sustainability telemetry sends
+the model, prompt/completion token counts, estimated kWh/CO2/water, a session
+identifier, and an account identifier when logged in—never prompt or response
+content. A user-requested browse sends a request to the supplied URL.
 
 ## Credentials
-- A bring-your-own key lives in `~/.phewsh/config.json` at mode **0600**
-  (`lib/config-file.js`) and is sent **directly to the provider**, never to us.
-- phewsh routes through your installed tools on **their own login** (your Claude
-  subscription, your ChatGPT plan) — it does not see or store those credentials.
-
-## The local bridge
-`phewsh serve` binds **`127.0.0.1` only** (loopback), with an origin allowlist,
-and runs only while you run it.
-
-## Known issues / hardening backlog (honest)
-- **Local shell-injection surface (medium, local-only):** a few call sites build
-  shell strings from REPL input via `execSync` (e.g. `commands/session.js` gate /
-  outcomes arg passthrough). Inputs are your own typed/pasted text on your own
-  machine, but crafted args could execute. Fix: convert to argument-safe
-  `execFileSync`/`spawnSync`. Tracked as a Next item.
-- **No release provenance yet** — npm provenance, signed tags, and a public
-  source repo are planned (Roadmap) so the published artifact is verifiable.
+
+Phewsh stores its own Supabase tokens and BYOK values in
+`~/.phewsh/config.json`, hardened to mode `0600` inside a `0700` directory on
+POSIX systems. Phewsh does not read Claude Code, Codex, Gemini, or Cursor
+credentials; spawned tools authenticate themselves.
+
+## Local bridges
+
+`phewsh serve` binds IPv4 and IPv6 loopback (`127.0.0.1` and `::1`) and applies
+a browser-origin allowlist. Project claims are rechecked against registration,
+cloud project identity, and Git origin. The legacy local dispatch surface is
+broader and should be treated as local-user authority.
+
+**Loopback is not authentication.** Another process running as your user may
+be able to call a local service, and non-browser clients do not supply a browser
+Origin header. The optional MCP HTTP transport is also unauthenticated. Never
+set `PHEWSH_MCP_HOST` to a non-loopback interface on an untrusted network.
+
+## Safety gate
+
+The pre-tool gate blocks a narrow set of catastrophic command shapes and may
+ask about high-blast-radius operations depending on autonomy. It is deliberately
+**fail-open** if hook input cannot be understood, uses pattern/segment matching
+rather than a complete shell parser, and covers known tool names. It is a
+last-line safety aid, **not a sandbox or authorization system**.
+
+## Supply chain status
+
+The npm release and public source mirror are synchronized manually. There is
+currently **no release provenance**, signed tag, or registry attestation tying
+an installed tarball to a public commit. Users can inspect `npm pack`, the
+public source snapshot, or the installer before running it, but similarity is
+not cryptographic proof. The required release procedure and promotion gate are
+in the [release integrity checklist](./docs/release-checklist.md).
 
 ## Disable / uninstall
-- `phewsh ambient off` — removes injected hooks and global base files; restores
-  your files.
-- `phewsh shim off` — removes the PATH line.
-- `npm uninstall -g phewsh` — removes the CLI. `rm -rf ~/.phewsh` removes local
-  state. Generated `PHEWSH:START/END` blocks can be deleted by hand; everything
-  outside them is yours and untouched.
-
-## Roadmap to verifiable trust
-Done: this doc, exec hardening, telemetry stays counts-only and explicit, and a
-**public MIT source repo** (`cleverIdeaz/phewsh-cli`) mirroring the npm package.
-Before broad promotion: npm provenance, signed tags, and dependency/secret
-scanning so the published artifact is cryptographically verifiable from the
-public source. For enterprise: a documented threat model and an independent
-security assessment. We will not call phewsh "audited" until an independent
-audit has actually occurred.
+
+- `phewsh ambient off` removes injected hooks, global blocks, and unchanged
+  Phewsh-owned intent-skill copies.
+- `phewsh shim off` removes the PATH line.
+- `npm uninstall -g phewsh` removes the CLI. Local `~/.phewsh/` state and
+  project `.intent/` files remain yours and can be removed separately.
 
 ## Reporting
-Security issues: **hello@phewsh.com**. Please allow reasonable time to remediate
-before public disclosure.
+
+Security issues: **hello@phewsh.com**. Please allow reasonable time to
+remediate before public disclosure.

package/bin/phewsh.js

@@ -7,10 +7,15 @@ const command = args[0];
 // Must be instant and side-effect-free: print the banner, exit. No update
 // check, no network, no session. Intercepted before anything else loads.
 if (command === 'shim-preflight') {
-  try {
-    const bin = args[1] || 'tool';
-    process.stdout.write(require('../lib/shims').preflightBanner(bin) + '\n');
-  } catch { /* a broken banner must never delay the real tool */ }
+  // Machine-readable launches (Codex app-server JSONL, anything spawned with
+  // piped stdio) must get NOTHING on stdout — a banner corrupts the stream
+  // the parent parses. A human terminal has a TTY; everything else stays silent.
+  if (process.stdout.isTTY) {
+    try {
+      const bin = args[1] || 'tool';
+      process.stdout.write(require('../lib/shims').preflightBanner(bin) + '\n');
+    } catch { /* a broken banner must never delay the real tool */ }
+  }
   process.exit(0);
 }
 
@@ -58,7 +63,7 @@ function showBrand() {
   console.log('');
   console.log(`  ${b(w('█▀█ █░█ █▀▀ █░█░█ █▀ █░█'))}`);
   console.log(`  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀▄▀ ▄█ █▀█'))}`);
-  console.log(`  ${g('Keep all your AI tools. phewsh is the one memory they share.')}`);
+  console.log(`  ${g('Keep all your AI tools. phewsh briefs them from one .intent/ folder you own.')}`);
   console.log('');
 
   // Context-aware hint
@@ -86,6 +91,8 @@ const COMMANDS = {
   link:    () => require('../commands/link'),
   sync:    () => require('../commands/sync').main('status'),
   login:   () => require('../commands/login'),
+  // `phewsh logout` = `phewsh login --logout` — the universal spelling.
+  logout:  () => { process.argv.splice(3, 0, '--logout'); return require('../commands/login'); },
   ai:      () => require('../commands/ai'),
   style:   () => require('../commands/style'),
   mbhd:    () => require('../commands/mbhd'),
@@ -133,13 +140,13 @@ function showHelp() {
   const pkg = require('../package.json');
   showBrand();
   console.log(`  ${g('v' + pkg.version)}  ·  ${g('phewsh.com/cli')}\n`);
-  console.log(`  ${g('Phewsh keeps work from getting lost — for you, and every AI tool you use.')}`);
+  console.log(`  ${g('Carry forward what was recorded. See exactly what was not.')}`);
   console.log('');
   console.log(`  ${b(w('the whole idea — four plain words'))}`);
   console.log(`    ${cyan('intent')}     ${g('PROJECT   what you\'re building & why')}`);
   console.log(`    ${cyan('next')}       ${g('NEXT      what should happen next — a zero-AI list')}`);
   console.log(`    ${cyan('work')}       ${g('WORK      what\'s happening now — at a glance')}`);
-  console.log(`    ${cyan('remember')}   ${g('RECORD    jot a decision so it sticks & travels')}`);
+  console.log(`    ${cyan('remember')}   ${g('RECORD    jot a decision so it stays in .intent/')}`);
   console.log(`    ${cyan('status')}     ${g('see all four at a glance')}`);
   console.log('');
   console.log(`  ${b(w('get started'))}`);
@@ -152,38 +159,38 @@ function showHelp() {
   console.log(`    ${cyan('gate')}       ${g('Set constraints (budget, time, skill, urgency)')}`);
   console.log(`    ${cyan('context')}    ${g('Export .intent/ for any AI tool')}`);
   console.log(`    ${cyan('status')}     ${g('git status for AI continuity — truth, record, drift, what\'s wired')}`);
-  console.log(`    ${cyan('next')}       ${g('What should happen next — a zero-AI list every tool reads')}`);
+  console.log(`    ${cyan('next')}       ${g('What should happen next — a zero-AI list compatible adapters read')}`);
   console.log(`    ${cyan('truth')}      ${g('Read-only audit: versions, Git, intent, projections, conflicts')}`);
   console.log(`    ${cyan('brief')}      ${g('Provider-ready briefing built from verified project truth')}`);
   console.log(`    ${cyan('ai')}         ${g('One-shot prompt with .intent/ context')}
     ${cyan('browse')}     ${g('Read any URL — AI summary in your terminal')}`);
   console.log('');
-  console.log(`  ${b(w('sync everywhere'))}`);
-  console.log(`    ${cyan('seq')}        ${g('Sequence all memory → optimal context for any agent')}`);
-  console.log(`    ${cyan('watch')}      ${g('Auto-sync .intent/ → native harness files + cloud')}`);
+  console.log(`  ${b(w('connect your tools'))}`);
+  console.log(`    ${cyan('seq')}        ${g('Compile project truth → native context for a chosen tool')}`);
+  console.log(`    ${cyan('watch')}      ${g('Auto-sync while running; signed-in cloud push unless --no-push')}`);
   console.log(`    ${cyan('push/pull')}  ${g('Manual sync to/from phewsh.com/intent')}`);
-  console.log(`    ${cyan('serve')}      ${g('Execution bridge — run from phewsh.com/ion or /intent')}`);
+  console.log(`    ${cyan('serve')}      ${g('Same-machine worker — project-bound, human-initiated claims')}`);
   console.log(`    ${cyan('project')}    ${g('Choose which projects this machine\'s worker shows on /ion')}`);
-  console.log(`    ${cyan('ion')}        ${g('Shared visual room for humans + local agents')}`);
-  console.log(`    ${cyan('mcp')}        ${g('Connect AI agents via MCP protocol')}`);
-  console.log(`    ${cyan('ambient')}    ${g('Continuity without launching phewsh — enhance your other tools')}`);
+  console.log(`    ${cyan('ion')}        ${g('Shared project room for humans + agents; request → review → Record')}`);
+  console.log(`    ${cyan('mcp')}        ${g('Optional bounded MCP adapter — no project truth or execution authority')}`);
+  console.log(`    ${cyan('ambient')}    ${g('Inspect or install reversible skills, hooks, and context adapters')}`);
   console.log(`    ${cyan('shim')}       ${g('Guaranteed launch banner — phewsh prints status before each tool')}`);
   console.log(`    ${cyan('pack')}       ${g('Opt-in workflow packs (Karpathy guidelines, GSD…) — attributed, reversible')}`);
   console.log(`    ${cyan('task')}       ${g('Shared tasks — request, claim, and ship teammate work via branch + PR')}
     ${cyan('dispatch')}   ${g('Friendly verb over task: dispatch "<title>" to request, <id>|next to claim')}
-    ${cyan('receipts')}   ${g('Proof trail — what agents actually did, with evidence')}`);
-  console.log(`    ${cyan('remember')}   ${g('Jot a decision to .intent/decisions.md — every tool inherits it')}`);
+    ${cyan('receipts')}   ${g('Proof trail — task evidence + cross-tool handoff receipts')}`);
+  console.log(`    ${cyan('remember')}   ${g('Jot a decision to .intent/decisions.md — supported tools can read it')}`);
   console.log(`    ${cyan('outcomes')}   ${g('Decision record — what was kept, reverted, or failed')}`);
   console.log(`    ${cyan('bypass')}     ${g('Went around phewsh? Record why — 10 seconds, no guilt')}`);
   console.log('');
   console.log(`  ${b(w('configure'))}`);
   console.log(`    ${cyan('feedback')}   ${g('Tell us what you need — prefilled GitHub issue; `feedback list` shows the queue')}`);
-  console.log(`    ${cyan('login')}      ${g('Identity + API key + cloud sync')}`);
+  console.log(`    ${cyan('login')}      ${g('Identity + API key + cloud sync — `logout` to sign out')}`);
   console.log(`    ${cyan('link')}       ${g('Link local .intent/ to cloud project')}`);
   console.log(`    ${cyan('update')}     ${g('Update phewsh — or `phewsh update auto on` to stay current automatically')}`);
   console.log('');
-  console.log(`  ${g('Works in: Claude Code · Cursor · ChatGPT · any MCP agent')}`);
-  console.log(`  ${g('No account needed. Account adds sync + sharing.')}`);
+  console.log(`  ${g('Works with: Claude Code · Codex · Cursor · Gemini · compatible MCP clients')}`);
+  console.log(`  ${g('No account needed for local truth. An account adds explicit cloud sync + Ion rooms.')}`);
   console.log('');
 }
 
@@ -249,12 +256,11 @@ async function maybeFirstRunIntro() {
   } catch { /* the intro is a nicety — never let it block the session */ }
 }
 
-// Always-on, frictionless: on the first interactive use, auto-enable ambient
-// across every installed harness (unless the user opted out); on every run
-// after, self-heal so each tool's context files are present and fresh. All
-// best-effort and non-blocking — a launch must never wait on or fail from this.
+// Once a user has explicitly enabled native adapters, keep their existing
+// marked context blocks fresh. A bare launch never installs skills or hooks;
+// first-run setup is offered by the intro and `phewsh ambient on` previews the
+// exact files before asking for consent.
 async function ambientSelfHeal() {
-  try { await require('../commands/ambient').ensureAuto(); } catch { /* never block launch */ }
   // Refresh-only: keep already-present context files fresh, but never CREATE
   // them just because phewsh was opened here — that would dirty a clean repo.
   try { require('../lib/selfheal').syncContextFiles({ createMissing: false }); } catch { /* never block launch */ }