impel-cli 0.16.5 → 0.17.1

package/README.md

@@ -1,1057 +1,310 @@
-# impel
-
-A tiny, dependency-free CLI for macOS, Linux, and Windows that switches your
-local **Claude Code** and **Codex** between two modes, per tool, reversibly:
-
-- **gateway mode** — route through Impel's custom gateway, authenticated with an
-  Impel Personal Access Token (PAT).
-- **account mode** — your own normal Anthropic / OpenAI login.
-
-The gateway accepts `Authorization: Bearer impel_pat_...` directly. `impel` stores
-that PAT locally and hands it to both tools through the same mechanism they
-already support for external auth commands (`apiKeyHelper` for Claude Code,
-`model_providers.<id>.auth.command` for Codex) — so the token is never written
-into either tool's own config file.
-
-- Claude Code talks to `<gateway>/anthropic`
-- Codex uses `<gateway>/chatgpt_passthrough/backend-api/codex` as its provider
-  base and posts to the resulting `.../responses` compatibility route.
-
-It can also install **isolated Impel desktop experiences**. On macOS, Impel
-Claude and Impel ChatGPT are separate vendored app copies. On Windows, Impel
-Claude launches Anthropic's signed vendor executable with its supported 3P
-profile root, while Impel ChatGPT stages OpenAI's signed Electron payload out
-of the protected Store directory and launches it with tenant-specific Codex and
-browser profiles. Each approach keeps the user's normal app profile and
-signed-in account untouched.
-
-Every Impel-managed Claude Code, Codex CLI, Claude Desktop, and ChatGPT/Codex
-Desktop profile also installs tenant-scoped lifecycle hooks for cloud session
-persistence. Hook input is first written to a private local outbox, so an
-offline network, interrupted hook, force-quit, or client restart cannot make a
-provider turn fail. The next hook invocation retries any pending batches,
-including batches left by an older session. Remote payloads are stored as
-independent zstd frames by `impel-sessions`; the local collector sends bounded
-newline-complete transcript deltas and a compact lifecycle ledger. Pending data
-is capped at 256 MiB or 2,048 batches per session by default; corrupt or
-permanently invalid batches are quarantined so they cannot block later data.
-Set `IMPEL_SESSIONS_MAX_OUTBOX_BYTES` or `IMPEL_SESSIONS_MAX_OUTBOX_BATCHES` to
-lower those local limits.
-
-The service attributes each session to the PAT-resolved user and selected
-tenant and records the provider, CLI/desktop surface, provider session ID, and
-repository metadata. Set `IMPEL_TASK_ID` before launching a client to link new
-sessions explicitly to an Impel task for cross-device discovery. The collector
-never writes the configured PAT into hook configuration, and it redacts Impel
-PAT/tenant credentials found in hook input or transcript content before
-spooling. Task linkage is retried independently and cannot block payload
-persistence when the current PAT lacks the `tasks` scope.
-
-Codex hook trust is pinned to the exact generated handler and its array index.
-If you manually reorder the managed group in `hooks.json`, rerun `impel setup`,
-`impel app update`, or relaunch the isolated CLI to regenerate the trust entry.
-
-## Gateway-only vendor package
-
-White-labelled gateway launchers import the deliberately narrow
-`impel-cli/gateway` subpath. It exports only `createGatewayCli`; the resulting
-CLI accepts `setup`, `auth`, `claude`, `codex`, `status`, `token`, help, and
-version. Tasks, tenants, PAT minting, apps, agents, skills, MCP, updates, and
-other Impel control-plane commands are not part of this package surface.
-
-```js
-import { createGatewayCli } from "impel-cli/gateway";
-
-const cli = createGatewayCli({ brand, entrypoint, version });
-const exitCode = await cli.main(process.argv.slice(2));
-if (exitCode) process.exitCode = exitCode;
-```
+# impel-cli
+
+`impel-cli` prepares isolated Claude and Codex workspaces for every Impel
+tenant you can access. It keeps tenant histories, settings, credentials, and
+desktop app state separate from one another and from your personal Claude and
+Codex profiles.
 
-The caller supplies a validated branding document, its own executable path,
-and its package version. Gateway profile behavior and the command allowlist
-remain in `impel-cli`, so vendor CLIs do not copy or fork those implementations.
+The normal lifecycle has two commands:
 
-## Start here
+```sh
+impel setup
+impel update
+```
 
-You do not need GitHub access to install Impel. You need an Impel account and a
-computer with Node.js installed. Node.js includes the small installer tool
-called `npm` that installs Impel for you.
+## Install
 
-### 1. Install Node.js and npm
+Install the public npm package once per machine:
 
-If `node --version` and `npm --version` already print version numbers, skip to
-the next step.
+```sh
+npm install --global impel-cli
+```
 
-- **Mac or Windows:** visit [nodejs.org/download](https://nodejs.org/en/download),
-  choose the **LTS** installer, and accept the default installer options.
-- **Linux:** follow Node's [official package-manager instructions](https://nodejs.org/en/download/package-manager)
-  for your distribution.
+Node.js 18 or newer is required.
 
-After installing Node.js, close and reopen Terminal (Mac/Linux) or PowerShell
-(Windows), then check that it worked:
+Then run setup and paste an Impel Personal Access Token when prompted:
 
 ```sh
-node --version
-npm --version
+impel setup
 ```
 
-Both commands should print a version number. Impel needs Node.js 18 or newer.
+Setup discovers every tenant available to the PAT and prepares all supported
+surfaces for each tenant. You do not need to repeat setup tenant by tenant.
 
-### 2. Install Impel
+## What setup does
 
-In Terminal or PowerShell, run:
+`impel setup`:
+
+1. Stores the PAT in the private Impel config file.
+2. Fetches the complete live tenant list.
+3. Preserves the current CLI tenant when it is still accessible, or selects the
+   control-plane default.
+4. Creates isolated Claude and Codex CLI profiles for every supported tenant.
+5. Installs or repairs supported tenant desktop apps on macOS and Windows.
+6. Registers tenant apps with Finder/Spotlight or Windows Start/Search.
+7. Verifies every supported tenant surface and prints a tenant-sorted summary.
+
+Use `--tenant` only to choose the default for CLI launches. It does not limit
+which tenants setup prepares:
 
 ```sh
-npm install --global impel-cli
+impel setup --tenant acme
+```
+
+Useful setup options:
+
+```sh
+impel setup --pat <pat>       # non-interactive credential input
+impel setup --skip-apps       # prepare CLI profiles only
+impel setup --skip-clis       # Windows: do not install missing vendor CLIs
+impel setup --no-recovery     # disable local and assisted recovery for this run
 ```
 
-This downloads the public Impel command-line app. It does **not** give anyone
-access to your Impel account, workspace, or data.
+Putting a PAT on a command line can leave it in shell history. Prefer the
+interactive prompt for ordinary use.
 
-### 3. Connect your Impel account
+## Open apps
 
-1. Open [Impel gateway settings](https://www.useimpel.com/settings/gateway).
-2. Create a Personal Access Token and copy it somewhere safe.
-3. Back in Terminal or PowerShell, run:
+After setup, launch the tenant-specific apps through the operating system:
 
-   ```sh
-   impel setup
-   ```
+- macOS: Finder, Spotlight, or `~/Applications`
+- Windows: Start or Search under the Impel program group
 
-4. Paste the token when asked. The input is hidden, and Impel stores it only in
-   your local account configuration.
-5. Choose your organization when prompted and let the setup finish.
+Names include the tenant, such as `Impel Claude (Acme)` and
+`Impel ChatGPT (Acme)`. The selected CLI tenant does not affect which tenant an
+app opens. Tenant variants can remain installed side by side.
 
-Your token is the key to your account. Never paste it into a chat, ticket, or
-shared document.
+Linux does not have managed desktop apps. Use the isolated CLI commands there.
 
-### 4. Start working
+## Use the CLI
+
+Select the tenant used by CLI launches:
 
 ```sh
-impel claude               # open an isolated Impel Claude Code session
-impel codex                # open an isolated Impel Codex session
-impel status               # check your connection and configuration
-impel update               # install the latest Impel CLI later
+impel tenant list
+impel tenant current
+impel tenant use acme
 ```
 
-`impel setup` keeps your normal Claude and Codex profiles separate. On Mac and
-Windows it also prepares the supported isolated desktop experiences. On Windows,
-it installs missing official vendor command-line tools with the vendors'
-checksum-verifying native installers, so Claude Code does not inherit its newer
-Node.js requirement from the deprecated npm package. On Linux, it prepares the
-isolated command-line workflow.
-
-If setup or the CLI self-update fails, Impel first runs deterministic local
-repairs for known failure fingerprints — offline, with no upload. If the
-failure persists, an interactive terminal offers assisted recovery (use
-`impel setup --repair` or `impel update --repair` to opt in explicitly): a
-bounded local loop where a gateway-hosted model selects typed diagnostic and
-repair tools and the CLI validates, approves, and executes them on this
-machine. Before the first upload, the CLI prints the exact sanitized payload.
-Free-form model commands are impossible by construction; repairs limited to
-Impel-owned files need one approval per session, while vendor installers and
-PATH edits always confirm individually. Recovery only reports success after
-the failed steps re-pass their local health checks, and it stops after 12
-model turns or 10 minutes. Use `--no-recovery` or
-`IMPEL_DISABLE_INSTALL_RECOVERY=1` to keep recovery off.
-
-### If something does not work
-
-- **`npm` or `node` is not recognized:** install Node.js from the link above,
-  then close and reopen Terminal or PowerShell.
-- **`impel` is not recognized:** close and reopen the terminal, then run
-  `npm install --global impel-cli` again.
-- **Your token is rejected:** create a fresh token in Impel gateway settings and
-  run `impel setup` again.
-- **You need a different organization:** run `impel tenant list`, then
-  `impel tenant use <organization>`.
-
-The npm package is public so Impel users do not need access to the private
-GitHub repository. The package contains no account credentials or service
-secrets; the Impel gateway and control plane still enforce your token, product
-access, scopes, and organization membership for every protected action.
-
-## Command reference
+Then launch either client:
 
+```sh
+impel claude
+impel codex
 ```
-impel setup [--pat <pat>] [--tenant <org>] [--skip-apps] [--skip-clis]
-            [--repair|--no-recovery]
-                                             Guided setup: token, tenant, platform clients, verify
-                                             (closes running Claude/ChatGPT apps, updates the vendor
-                                              apps, then installs the vendored Impel apps on macOS;
-                                              runs official native vendor CLI installers on Windows)
-impel update [--check] [--skip-apps] [--repair|--no-recovery]
-                                             Update EVERYTHING: reinstall the CLI from npm, then
-                                             cascade to `app update all`, `skills sync all`, and
-                                             `agents sync all`
-impel auth [--pat <pat>] [--gateway <url>] [--app <url>]
-                                             Store your Impel PAT + URLs
-impel pat create --label <label> [options]    Mint a personal PAT through the control plane
-impel pat create --agent <agent-id> [options]
-                                             Mint a PAT associated with an org agent
-impel pat revoke <token-id> --yes             Irreversibly revoke one of your PATs
-impel token [--tenant <org>]                 Print a selected-tenant bearer
-impel mcp                                    Run the local MCP bridge used by Claude/Codex
-impel claude [claude args...]                Launch isolated Impel Claude Code
-impel codex [codex args...]                  Launch isolated Impel Codex
-
-impel tasks list [--org <org>]               List tickets
-impel tasks get <id>                         Read one ticket
-impel tasks create --title <title> [...]     Create a ticket
-impel tasks update <id> [...]                Update a ticket
-impel tasks delete <id> --yes                Delete a ticket
-
-impel tenant list                            List available organizations
-impel tenant current                         Print the selected organization
-impel tenant use <org> [--launch <target>]   Select a tenant; optionally launch claude, codex, or apps
-impel doctor [--tenant <org>|--all-tenants]  Run synthetic provider, routing, and latency checks
-
-impel use gateway [claude|codex|all]         Switch to the Impel gateway  (default: all)
-impel on [claude|codex|all]                  Alias for `impel use gateway`
-impel use account [claude|codex|all]         Revert to your own login    (default: all)
-impel off [claude|codex|all]                 Alias for `impel use account`
-
-impel skills sync [claude|codex|all]         Sync Bifrost shared skills into managed clients (default: all)
-impel agents sync [claude|codex|all]         Sync explicit tenant agents into native clients
-
-impel status                                 Launcher readiness + native mode + gateway reachability
-impel app install [target] [--tenant <org>]  Install isolated apps for one tenant
-impel app update [target] [--tenant <org>] [--force]
-                                             `all` without --tenant updates every installed tenant;
-                                             --force performs a clean full rebuild
-impel app refresh [target] [--tenant <org>]  Configs/catalog/skills/agents only; safe while apps run
-                                             (--stale-only: no-op unless 6h+ since last sync)
-impel app status [target] [--tenant <org>]   Show tenant launcher/vendor status
-impel app open [target] [--tenant <org>]     Install/configure a tenant on first use, then launch
-                                             it (later opens are immediate when nothing changed;
-                                             a detached stale-only refresh keeps things current)
-impel app uninstall [target] [--tenant <org>] [--keep-data]
-                                             Remove one tenant's Impel-managed app files
-impel help                                   Show help
-impel --version                              Show version
-
-For app commands, `target` is `claude`, `chatgpt`/`codex`, or `all` (the
-default). `impel app update all` without `--tenant` updates every locally
-installed tenant. Other app commands, a specific update target, or an explicit
-`--tenant` operate on one organization and default to the current selection.
-
-# `impel setup` no longer takes a per-tool target and never flips native
-# configs; flip a native tool explicitly with `impel use gateway [claude|codex]`.
+
+Arguments after the command are passed to the vendor CLI:
+
+```sh
+impel claude --model opus
+impel codex exec "review this repository"
 ```
 
-### `impel auth [--pat <pat>] [--gateway <url>] [--app <url>]`
+Changing the selected tenant does not install, remove, or rewrite any other
+tenant. It changes only the default used by CLI launches and selected-tenant
+workspace commands.
 
-Stores your PAT, gateway base URL, and app/control-plane URL in `~/.config/impel/config.json`
-(created with mode `0600`, directory `0700`).
+## Update
 
-- If `--pat` isn't given, you're prompted for it (input is masked).
-- If `--gateway` isn't given, it falls back to (in order): the gateway URL you
-  already had stored, the `IMPEL_GATEWAY_URL` environment variable, then the
-  built-in default **`https://gateway.useimpel.com`**.
-- If `--app` isn't given, it falls back to (in order): the app URL you already
-  had stored, the `IMPEL_APP_URL` environment variable, then the built-in
-  default **`https://www.useimpel.com`**.
-- Trailing slashes on the gateway URL are stripped automatically.
+Run one command for routine maintenance:
 
 ```sh
-impel auth --pat impel_pat_xxxxxxxxxxxx --gateway https://gateway.useimpel.com --app https://www.useimpel.com
+impel update
 ```
 
-### `impel pat create ...` / `impel pat revoke ...`
+Update:
 
-Mints a new PAT through the app/control-plane API, authenticated by the PAT
-already stored by `impel auth`. Identity remains the minting authority: the
-control plane verifies the current owner, target-org membership, requested
-scopes, product access, and (when applicable) agent access before it requests a
-new secret. The gateway never mints or verifies PATs.
+1. Checks and installs the latest `impel-cli` package from npm.
+2. Continues under the freshly installed build.
+3. Fetches the current live tenant list.
+4. Fully prepares tenants added since the previous run.
+5. Repairs and upgrades existing tenants in place.
+6. Re-registers operating-system launch entries.
+7. Reports local tenants that are no longer accessible without deleting them.
 
-Use `--label` for a personal token or `--agent` for a token associated with an
-org agent. Agent PATs are still personal credentials: they act as you, are
-org-scoped, and use the same stable `Agent · <agent-id>` association as the agent
-setup UI.
+An update preserves histories, browser state, preferences, permissions, stable
+app identity, and user-authored settings outside Impel-managed blocks. Desktop
+bundles are rebuilt only when missing, corrupt, or stale. An app is closed only
+when its bundle must be replaced, and only an app closed by the update is
+reopened afterward.
+
+Useful update options:
 
 ```sh
-impel pat create --label "Rahul's laptop"
-impel pat create --agent support-agent --org acme
-impel pat create --label ci-automation --scopes codex-gateway,tasks --ttl-days 30 --json
+impel update --check          # inspect npm availability without changing state
+impel update --skip-apps      # reconcile CLI profiles only
+impel update --no-recovery    # disable recovery for this run
 ```
 
-`--org` defaults to the selected tenant (`--tenant` is an alias). `--scopes`
-accepts `claude-code-gateway`, `codex-gateway`, and `tasks`; when omitted, the
-control plane chooses the defaults allowed by your access tier. `--ttl-days`
-accepts 1–365 and defaults to 90 days.
-
-The new secret is returned once on stdout and is deliberately **not** written to
-the config file. To rotate this CLI onto it, explicitly run
-`impel auth --pat <new-pat>` after copying it. `--json` includes the raw secret,
-so treat redirected output as a credential.
+"Latest" means the latest npm CLI plus the exact vendor builds and profile
+schema verified by that CLI. It does not mean cloning an untested moving vendor
+release.
 
-Revoke a token by the token ID printed when it was created:
+## Status and diagnosis
 
 ```sh
-impel pat revoke personal1 --yes
-impel pat revoke personal1 --yes --json
+impel status
+impel doctor
+impel doctor --all-tenants
 ```
 
-Revocation is immediate and irreversible, so `--yes` is required. A full PAT is
-also accepted for recovery from older mint output, but using the token ID avoids
-putting a secret in shell history. The CLI extracts the ID without echoing the
-secret, authenticates with the currently stored PAT, and leaves the local config
-unchanged. If you revoke the stored PAT itself, authenticate again with a live PAT
-before running another protected command.
-
-### `impel update`
-
-One command brings everything current, in dependency order: the CLI itself
-(`npm install -g impel-cli@latest` from npm, with no GitHub credentials),
-then — re-executing the freshly installed build — `impel app update all`
-(update every locally installed tenant and rebuild only stale vendored Impel apps)
-followed by `impel skills sync all` and `impel agents sync all` across every
-native and isolated CLI profile. Each tenant's app step syncs that tenant's app
-profiles; the dedicated steps exclude apps, so every profile is synced once.
-
-Most updates are in place — the desktop apps are **not** closed. A vendored
-bundle is only rebuilt (and therefore only quit) when the bundle-building logic
-or the pinned vendor version actually changes, not on every CLI release, so a
-routine update just rewrites configs, skills, and agents while the apps keep
-running. When a rebuild genuinely is required, `impel app update` closes only
-the app whose bundle it will swap and **reopens it afterward**, so the swap
-lands without you relaunching by hand. Apps you had already closed stay closed.
-
-Update discovery compares the installed package version with npm's public
-`latest` metadata, cached for 6 hours in
-`~/.config/impel/update-check.json`. It does not invoke Git or contact GitHub.
-
-You'll also hear about updates without asking: `impel claude`, `impel codex`,
-`impel status`, and `impel app open` print a one-line notice when the cached
-remote is ahead, and refresh the cache in a detached background process when
-it's stale (TTY-only, never blocks a launch; set `IMPEL_SKIP_UPDATE_CHECK=1`
-to silence). The Impel desktop apps keep themselves current too: their token
-helper kicks off a detached `impel app refresh --stale-only` on use, which
-re-syncs configs, the model catalog, skills, and native agents at most every six
-hours — safe while the apps are running because it never swaps an app bundle.
-
-### `impel tasks ...`  (aliases `impel task`, `impel tickets`, `impel ticket`)
-
-CRUDs Impel tickets through the app/control-plane API using the stored PAT. New
-PATs need the `tasks` scope and the user must be a **Workspace member**. Gateway
-members intentionally cannot access tasks or other workspace features, even if
-an older PAT still contains the scope.
+`impel status` is read-only. It shows authentication, the current CLI tenant,
+and every tenant's local Claude, Codex, and desktop readiness. Its repair path
+is `impel update`.
+
+`impel doctor` sends explicit synthetic provider checks. Those requests may be
+billable, so doctor never runs implicitly.
+
+## Workspace tasks
+
+Workspace members with a PAT carrying the `tasks` scope can use Impel tickets:
 
 ```sh
 impel tasks list --scope visible
 impel tasks get IMP-123
-impel tasks create --title "Fix flaky login test" --priority high --labels bug,engineering
-impel tasks update IMP-123 --progress review --assignee rahulvbrahmal@gmail.com
-impel tasks update IMP-123 --description-file brief.md --description-mode replace
+impel tasks create --title "Harden setup verification"
+impel tasks update IMP-123 --progress review
 impel tasks delete IMP-123 --yes
 ```
 
-Common options: `--org <org>` targets a specific org (default: the PAT's org),
-`--json` prints the raw API response, and `--app <url>` overrides the app URL for
-one command.
-
-### Tenant selection
-
-`impel auth` discovers every organization the PAT owner currently belongs to.
-The default is `impel` when available, otherwise the first organization slug in
-deterministic order. Change it with `impel tenant use <org>`.
-
-The selected tenant controls all gateway-backed surfaces together: subscription
-accounts, usage attribution, model catalog, and specialist discovery. The
-gateway re-verifies both the underlying PAT and current organization membership;
-editing the local config cannot grant access to another tenant.
-
-Isolated CLI state is kept separately under
-`~/.config/impel/cli/tenants/<org>/`, so Claude/Codex history and MCP state do
-not bleed between tenants. `impel tenant use <org> --launch claude|codex|apps`
-selects and launches in one command.
-
-On macOS, desktop app state is isolated under
-`~/.config/impel/apps/tenants/<org>/`. Every installed tenant keeps its own app
-bundles in `~/Applications`, with names such as `Impel Claude (Acme)` and
-`Impel ChatGPT (Acme)`, stable tenant-specific bundle identifiers, and fixed
-tenant profile/auth paths. Different tenants can stay open concurrently.
-`impel app open --tenant <org>` installs and configures a missing tenant variant
-on first use, then launches it directly without changing the globally selected
-tenant. Later opens use the existing isolated app and profile. Switching tenants
-never deletes local history or projects; each tenant's preserved profile reopens
-independently. The first-use setup still requires an authenticated user PAT and
-live membership in the requested organization; it does not create a PAT per
-tenant.
-Windows Claude Desktop keeps each
-tenant under `%LOCALAPPDATA%\Claude-3p\Impel\<org>` and launches the unchanged
-signed vendor executable with that profile selected. Windows ChatGPT keeps its
-Codex and browser state under the same tenant-scoped Impel apps root used on
-macOS and launches a staged copy of the unchanged signed Store payload.
-
-### Product access
-
-Impel has two product access levels, independent of organization membership and
-provider-pool administration:
-
-- **Workspace member** — the complete Impel workspace plus the gateway,
-  tenant-scoped inference, and specialist agents.
-- **Gateway member** — the gateway setup/configuration surface, tenant selector,
-  inference, and specialist agents only. Tasks, workspace rooms, notifications,
-  and other collaboration features are unavailable.
-
-The control plane resolves this entitlement live. The CLI caches it only for
-display; the control plane and gateway enforce it again on every protected
-operation. Changing the selected tenant never changes the user's product access.
-Provider launches and `impel doctor` also preflight the PAT's live
-`claude-code-gateway` / `codex-gateway` scopes, so an older single-provider PAT
-gets a direct rotation instruction instead of a misleading model-capacity error.
-
-### `impel doctor`
-
-Runs a real streaming request through each selected provider, so it consumes a
-small amount of provider capacity. Each request contains only a generated
-synthetic marker and asks the model to acknowledge that marker exactly. The
-report verifies:
-
-- live PAT, entitlement, and tenant membership resolution,
-- the tenant-scoped model catalog,
-- a selected subscription account on the response,
-- the gateway-owned request ID and echoed client correlation ID,
-- HTTP, bounded SSE parsing, provider response ID, and successful terminal event,
-- exact request/response acknowledgement, and
-- headers, first-byte, time-to-first-token (TTFT), and total latency.
-
-It never prints the PAT or any real prompt content. The default TTFT warning
-budgets are 6 seconds for Claude and 5 seconds for Codex. A budget miss is shown
-as a warning; add `--strict-latency` to make it fail the command. Connectivity,
-routing, account selection, or acknowledgement errors always produce a non-zero
-exit code.
-
-Organizations may intentionally have only one provider pool. When the live
-catalog reports an exact `no_seat` state for a requested provider, the doctor
-reports that provider as skipped instead of manufacturing a failed request. The
-tenant can pass when another requested provider completes successfully. Expired
-credentials, exhausted capacity, rate limits, ambiguous catalog responses, and
-tenants with no usable requested provider still fail closed.
-
-Use `--gateway <origin>` for a one-run data-plane override. Doctor resolves the
-gateway in this order: `--gateway`, `IMPEL_GATEWAY_URL`, the saved gateway, then
-the canonical default. The override must be a bare HTTP or HTTPS origin and is
-never written back to the stored authentication config.
+Use `--json` when exact machine-readable fields matter. Gateway-only members
+cannot use task CRUD.
+
+## PAT lifecycle
+
+Minting and revocation remain explicit account operations:
 
 ```sh
-impel doctor
-impel doctor --attempts 2 --strict-latency
-impel doctor --all-tenants --attempts 2 --json > readiness.json
-impel doctor --tenant creador --providers claude
-impel doctor --gateway https://gateway.useimpel.com
+impel pat create --label laptop
+impel pat create --agent <agent-id> --org acme
+impel pat revoke <token-id> --yes
 ```
 
-`--attempts` is capped at five per provider and a single invocation is capped at
-50 total probes to prevent an accidental high-volume run. JSON output is one
-sanitized report suitable for CI or a rollout checklist.
-
-### `impel token`
-
-Prints **only** a bearer derived from the stored PAT and selected tenant to
-stdout, nothing else. Non-zero exit and a
-stderr message if you haven't run `impel auth` yet.
-
-This is the contract both Claude Code's `apiKeyHelper` and Codex's
-command-backed provider auth expect: a command that is invoked on demand and
-whose stdout is the bearer token. Managed Codex auth and MCP entries call the
-current Node executable plus Impel entry point directly, avoiding npm `.cmd`
-resolution on Windows. Rotating your PAT is still one command
-(`impel auth --pat ...`) and every tool picks it up on its next call/refresh.
-
-### Specialist delegation over MCP
-
-Gateway mode also installs an `impel` stdio MCP server in Claude Code and
-Codex, including the isolated Impel ChatGPT profile. The server runs the Impel
-MCP entry point, reads the PAT from the owner-only Impel
-config, and proxies JSON-RPC to `<gateway>/mcp`; the PAT is never written into
-either client's MCP configuration. Available specialists are discovered at
-runtime, so publishing a new opted-in specialist does not require another CLI
-release. The same authenticated catalog is rendered into native Claude Code
-and Codex agent definitions. Each definition carries only the direct
-`impel mcp --tenant <org>` subprocess invocation, never the PAT itself.
-
-### Isolated CLI launchers
-
-`impel claude [args...]` and `impel codex [args...]` launch the installed vendor
-CLIs with every argument, the current working directory, stdin/stdout/stderr,
-and the vendor exit code passed through unchanged. They require `impel auth`
-and load gateway authentication plus the Impel MCP server from private,
-Impel-only profiles:
-
-- Claude: `~/.config/impel/cli/tenants/<org>/claude` via `CLAUDE_CONFIG_DIR`
-- Codex: `~/.config/impel/cli/tenants/<org>/codex` via `CODEX_HOME`
-
-The normal `claude` and `codex` commands still use `~/.claude`, `~/.claude.json`,
-and `~/.codex`. The launchers do not read, copy, modify, or remove those native
-profiles, their credentials, or their conversation history. Project-level
-files and the working directory remain available exactly as they are in the
-normal CLIs.
-
-The isolated launchers also add an Impel-only instruction that checks the live
-tenant specialist catalog before non-trivial work. When one available
-specialist clearly matches, the client starts one idempotent specialist run,
-waits for it to finish, and uses its result instead of repeating the task. It
-continues normally when no specialist matches or delegation is unavailable.
-Claude receives this through `--append-system-prompt`; Codex receives it through
-the invocation-local `developer_instructions` override. Neither instruction is
-written to or loaded by the native `claude` or `codex` commands.
-
-The isolated Codex launcher uses Codex's embedded code-mode runtime so MCP tools
-keep working when a vendor install does not include the optional standalone
-`codex-code-mode-host` companion. Only the four specialist-control tools are
-pre-approved for non-interactive delegation; other MCP tools retain Codex's
-normal approval behavior. Its Codex-only instruction also resolves exact Impel
-specialist tools through `tool_search` when the client defers MCP tools instead
-of showing them directly. These settings apply only to `impel codex`.
-
-The isolated Codex profile disables Codex shell snapshots and explicitly keeps
-the default `KEY`/`SECRET`/`TOKEN` environment filter enabled. Before every
-launch, `impel` removes derived `shell_snapshots`, drops inherited direct-auth
-variables such as `CODEX_ACCESS_TOKEN`, and enforces owner-only permissions on
-the managed profile and credential/config files. It also sweeps inactive tenant
-and pre-tenancy Impel CLI profiles, so switching organizations cannot strand an
-older snapshot. These safeguards apply only to Impel-owned `CODEX_HOME`
-directories; native `~/.codex` remains untouched.
-
-On Windows, `impel setup` installs only missing command-line tools through the
-vendors' current native PowerShell installers. Claude Code's npm installation is
-deprecated and its current package requires Node.js 22, while Impel itself still
-supports Node.js 18 or newer. The native path keeps that valid Impel setup
-working. Codex's installer is run non-interactively. Both installers download
-platform-specific native releases and verify their published SHA-256 checksums.
-Use `--skip-clis` to prepare the profiles without installing missing vendor
-CLIs. Each tool is installed independently, so a failure from one vendor does
-not prevent the other tool from being installed and configured.
-
-The launchers and skill sync still resolve executables through `PATH`/`PATHEXT`,
-including existing global npm `.cmd` and `.bat` shims. Windows environment
-references such as `%NVM_SYMLINK%` are expanded during lookup, and the standard
-npm-global, Claude native-installer, Codex standalone-installer, and Windows
-PowerShell directories are checked even when the parent PowerShell PATH is
-stale. Candidates must also pass a bounded `--version` probe, so a stale or
-half-removed npm shim cannot hide a healthy native install later in the search
-path. Existing batch-shim arguments are forwarded through an explicitly
-escaped `cmd.exe` invocation without Node shell mode; NULs and line breaks,
-which cannot be represented safely through a batch shim, are rejected before
-anything is launched. Managed Codex auth and MCP subprocesses bypass batch
-shims entirely by calling Node directly.
-
-If a native installer fails, the wizard identifies the affected tool, preserves
-the other tool's successful install, and prints that vendor's exact official
-PowerShell command to retry. If an installer exits successfully but its command
-cannot be verified, close and reopen PowerShell, retry the printed command, and
-run `impel setup` again. Setup exits non-zero and says it is incomplete until
-both launchers are ready—it does not print a success banner after a failed
-installation.
-
-Windows receives the complete CLI workflow: setup/auth, tenant selection,
-isolated Claude and Codex launches, native profile switching, tasks, skills,
-status, doctor, self-update, and both isolated desktop apps. `impel app install
-claude` installs/updates Anthropic's signed per-user app through winget, writes
-the selected tenant's 3P gateway configuration beneath Anthropic's reserved
-`%LOCALAPPDATA%\Claude-3p\Impel\<tenant>` root, and leaves the executable and
-normal Claude profile unchanged. `impel app install codex` installs/updates
-OpenAI's `OpenAI.Codex` Store package, stages its unchanged signed app payload
-inside Impel's shared app cache, and writes separate Codex and Chromium
-profiles. `impel app open claude` and `impel app open codex` install a missing
-official app and configure the selected tenant on first use, then launch the
-isolated profile without changing either normal vendor profile.
-
-For Claude, the Impel PAT is supplied only to the launched child process as an
-authentication token and disappears when that process exits; it is never
-written into the isolated Claude profile. The launcher also recognizes
-Claude's standard native-installer location at `~/.local/bin/claude` when that
-directory is not present in the parent process's `PATH`.
+A newly minted PAT is shown once. It is not silently made active. Run
+`impel setup` and provide the new PAT when rotating this machine. Revocation is
+immediate and irreversible.
+
+`impel auth --pat <pat>` remains available for existing automation that only
+needs to store a credential. It does not provision tenants. Interactive users
+should prefer setup because setup also reconciles the complete tenant list.
+
+## Recovery
+
+Setup and update include bounded installation recovery by default:
+
+1. Known deterministic repairs run locally first.
+2. If verification still fails, the CLI prints the exact sanitized diagnostic
+   envelope before assisted diagnosis.
+3. The recovery model can select only strict, typed tools. It cannot run shell
+   text.
+4. Read operations and repairs limited to Impel-owned state run automatically.
+5. Vendor installers and user PATH edits require individual interactive
+   confirmation and are declined without a TTY.
+6. A recovery is accepted as fixed only after fresh local health checks pass.
+
+Tenant failures are recovered serially with a tool context and checkpoint
+bound to the exact tenant. PATs, bearer tokens, home paths, emails, and terminal
+control sequences are removed before any diagnostic request.
+
+Disable all recovery for one run with `--no-recovery`, or globally for a
+process with:
 
 ```sh
-impel claude
-impel claude -p "summarize this repository" --output-format json
-impel codex
-impel codex exec --json "review the current diff"
+IMPEL_DISABLE_INSTALL_RECOVERY=1 impel update
 ```
 
-`impel use gateway` remains available for users who intentionally want to
-switch their native profiles in place; the isolated launchers are the safer
-default when personal and Impel sessions should coexist.
-
-Every Impel-managed Claude configuration uses the same strict sandbox defaults
-with unrestricted outbound network access:
-the isolated `impel claude` profile, each tenant's Claude Desktop Code profile,
-the native profile while `impel use gateway claude` is active, and branded
-gateway-only CLI profiles. App config version 15 also pins managed Claude
-Desktop profiles to third-party deployment mode, enables the 3P Chat tab so
-Code's "Back to Claude" route has a valid destination, and removes the unusable
-Claude.ai sign-in path. Existing tenant profiles refresh onto these policies
-after the CLI update.
-
-### `impel use gateway [claude|codex|all]`  (alias `impel on`)
-
-Turns **on** gateway mode for the given tool (default `all`). Requires `impel auth`
-first.
-
-**Claude Code** — merges into `~/.claude/settings.json` (creating it if needed,
-leaving existing permission rules, hooks, other env vars, and custom sandbox
-filesystem/network rules intact). Gateway mode enables Claude's strict auto-allow sandbox by
-default: Bash runs inside the OS sandbox without routine prompts, the
-`dangerouslyDisableSandbox` escape hatch is disabled, and supported platforms
-fail closed if isolation cannot initialize. Native Windows keeps startup
-available because Claude's sandbox is supported only on macOS, Linux, and WSL2.
-A global `WebFetch(domain:*)` allow rule opens every outbound destination for Bash commands
-while retaining filesystem isolation. Explicit deny rules remain authoritative.
-On macOS, `enableWeakerNetworkIsolation` lets Go-based network tools reach the
-system TLS trust service while remaining sandboxed.
-
-```json
-{
-  "apiKeyHelper": "impel token",
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://gateway.useimpel.com/anthropic"
-  },
-  "permissions": {
-    "allow": ["WebFetch(domain:*)"]
-  },
-  "sandbox": {
-    "enabled": true,
-    "failIfUnavailable": true,
-    "autoAllowBashIfSandboxed": true,
-    "allowUnsandboxedCommands": false,
-    "excludedCommands": [],
-    "enableWeakerNetworkIsolation": true
-  }
-}
-```
+See [docs/assisted-install-recovery.md](docs/assisted-install-recovery.md) for
+the security model and tool registry.
 
-**Codex** — merges into `~/.codex/config.toml`. Codex supports pointing
-`model_provider` at a custom `[model_providers.<id>]` table, plus a
-**command-backed** bearer token via a `[model_providers.<id>.auth]` sub-table
-(`command` + `args`, re-invoked on a timer and on auth retries — the same shape
-as Claude Code's `apiKeyHelper`), so we reuse `impel token` there too instead of
-writing the PAT into `config.toml` or `~/.codex/auth.json`. The block written
-(fenced by markers, so everything else in your `config.toml` — other
-`model_providers`, `mcp_servers`, and unrelated sandbox policy — is left alone).
-Codex defaults to the `workspace-write` filesystem sandbox with unrestricted
-direct outbound access; its optional network proxy stays disabled:
-
-```toml
-model_provider = "impel"
-
-# >>> impel-cli managed block (model_providers.impel) >>>
-# Generated by `impel use gateway codex`. Safe to re-run; do not hand-edit
-# the lines between the markers above/below, they'll be overwritten.
-sandbox_mode = "workspace-write"
-sandbox_workspace_write.network_access = true
-
-[model_providers.impel]
-name = "Impel Gateway"
-base_url = "https://gateway.useimpel.com/chatgpt_passthrough/backend-api/codex"
-wire_api = "responses"
-
-[model_providers.impel.auth]
-command = "impel"
-args = ["token"]
-timeout_ms = 5000
-refresh_interval_ms = 300000
-# <<< impel-cli managed block <<<
-```
+## Personal profiles
 
-Before overwriting anything, `impel` **backs up** what was there (any prior
-`apiKeyHelper`, `ANTHROPIC_BASE_URL`, Claude sandbox/permission policy, and the
-prior Codex `model_provider`, sandbox mode, and workspace network values) into
-`~/.config/impel/config.json`, so `impel use account`
-can restore it exactly. If `config.toml` already has a `[model_providers.impel]` table that
-wasn't written by this tool, `impel` refuses to touch the file and tells you to
-resolve it manually rather than risk emitting invalid/duplicate TOML.
-
-### `impel use account [claude|codex|all]`  (alias `impel off`)
-
-Turns gateway mode **off** and restores your normal account-based setup. It
-removes **only** the Impel-added bits, never your own config:
-
-- **Claude Code** — removes `apiKeyHelper` only if it's `"impel token"`, and
-  `env.ANTHROPIC_BASE_URL` only if it equals `<gateway>/anthropic`. Then restores
-  whatever those keys held before gateway mode (from the backup). If there was
-  nothing before, they're deleted (and an emptied `env` is dropped). It also
-  removes only the Impel-added global `WebFetch(domain:*)` allow rule.
-- **Codex** — removes the marker-fenced `[model_providers.impel]` block, and
-  resets `model_provider` **only if it currently reads `"impel"`** — back to its
-  backed-up prior value, or, if there was none, removes the line entirely so
-  Codex falls back to its built-in default. The prior
-  `sandbox_mode` and `sandbox_workspace_write.network_access` values are
-  restored. All other tables are untouched.
-
-`impel use account` doesn't require the PAT and is safe to run repeatedly (if a
-tool is already in account mode it just says so and changes nothing).
-
-### `impel skills sync [claude|codex|all]`
-
-Syncs Impel's **Bifrost shared skills** into your managed Claude Code and Codex
-clients. The gateway publishes a public, per-client plugin marketplace whose
-bundled plugin — `bifrost-all-skills` — contains every served skill:
-
-- Claude Code registers its manifest URL:
-  `<gateway>/api/skills/serve/claude-code/.claude-plugin/marketplace.json`
-- Codex registers the Git source `<gateway>/api/skills/serve/codex`; its
-  marketplace manifest lives at `<source>/.agents/plugins/marketplace.json`.
-
-The sync is idempotent: it registers the marketplace, ensures `bifrost-all-skills`
-is installed, then runs the client's refresh commands so an already-installed
-plugin picks up a newer bundle. It reads each marketplace's registered `name`
-from the served `marketplace.json` to pin installs and refreshes. Codex receives
-the Git source rather than the nested manifest URL because its CLI clones the
-source before discovering `.agents/plugins/marketplace.json`.
-
-You rarely need to run it by hand — it runs **automatically** at the end of every
-install/update path:
-
-- `impel use gateway ...` / `impel setup ...` (native `~/.claude` / `~/.codex`)
-- `impel app install` / `impel app update` (each isolated desktop app profile)
-
-`impel skills sync` also covers the isolated `impel claude` / `impel codex` CLI
-profiles and installed desktop apps when they exist. Skill syncing is
-best-effort: if a client CLI, its `plugin` subcommand, or the gateway is
-unavailable, it logs a warning and moves on — it never fails the parent command.
-Set `IMPEL_SKIP_SKILL_SYNC=1` to disable it entirely (offline/CI).
-
-### `impel agents sync [claude|codex|all]`
-
-Fetches the selected organization's explicit native-agent catalog through the
-authenticated Impel MCP endpoint, then generates native custom-agent files for
-every managed profile. This catalog is separate from automatic specialists: it
-may include truthfully declared write-capable agents, but those agents require
-explicit user selection before the server will start a run.
-
-- Claude Code / Claude Desktop: `<CLAUDE_CONFIG_DIR>/agents/<agent-name>.md`
-- Codex / ChatGPT Codex mode: `<CODEX_HOME>/agents/impel-<tenant>-<agent-id>.toml`
-
-Each generated agent is bound to one exact `agentId` and
-`scopeParam`. It verifies that the exact agent is still available, starts one
-idempotent run, polls the durable run to a terminal state, and returns
-`result.finalText` without repeating the work. The files include a tenant-bound
-MCP subprocess definition so they also work in isolated desktop profiles. They
-never contain the PAT; the subprocess reads it from Impel's owner-only config
-when invoked.
-
-Visible agent names come from the registry title. Codex keeps that title as the
-custom-agent name; Claude uses the lowercase, hyphenated form required by its
-native agent schema and Desktop's `@` picker requires the Markdown filename to
-match that name. Codex filenames remain stable tenant-and-agent identifiers.
-Duplicate or built-in-reserved titles receive a deterministic disambiguator.
-
-The sync writes atomically and records a manifest beside the generated files.
-It removes only stale filenames from that manifest, so user-authored agents are
-never deleted. Automatic refreshes are best-effort and retain the last good
-catalog when the gateway is unavailable; the explicit command exits non-zero
-on failure. Set `IMPEL_SKIP_AGENT_SYNC=1` to keep the current generated catalog
-without contacting the gateway.
-
-Start a new task after syncing. Claude Code detects updates to an existing
-`agents/` directory within a few seconds, but if the sync created that directory
-for the first time while Claude was already running, restart Claude once.
-In Claude Desktop, selecting an agent on the first turn binds that Code session
-to the agent. Follow-up `@` menus continue to offer that same bound agent and
-insert a normal mention chip. Other agents remain available from a new task,
-because the running Claude session cannot safely switch agents mid-session.
-
-Invocation uses the clients' native agent behavior:
+Impel sessions no longer route native personal `~/.claude` or `~/.codex`
+profiles through Impel. Setup and update use tenant-isolated profiles only.
 
-```text
-# Claude Code / Claude Desktop Code tab: guaranteed explicit selection
-@research-agent investigate the dependency change
+For users of an older release, the first setup or update performs a one-time
+cleanup migration. It removes only exact Impel-owned values and marker blocks,
+restores stored prior values when available, and preserves user-edited or
+unrelated settings. The old account-restore aliases remain as hidden cleanup
+compatibility for one release, but no command can enable native routing.
 
-# Claude blocking CLI
-claude --agent research-agent -p "investigate the dependency change"
+## Platform behavior
 
-# Codex CLI / ChatGPT desktop Codex task
-Explicitly use the configured Research Agent for this request and wait for it.
-```
+### macOS
 
-Claude exposes native custom agents in its `@` typeahead. Current Codex releases
-load the generated standalone definitions directly from `$CODEX_HOME/agents/`
-but do not provide an `@agent`
-mention target; named spawning remains model-mediated and may also be limited by
-the active MultiAgentV2 tool schema. Use `/agent` in Codex to inspect spawned
-agent threads.
+- Tenant apps live in `~/Applications`.
+- LaunchServices registration is non-launching and idempotent.
+- Existing bundle fingerprints and stable signing identity prevent unnecessary
+  rebuilds and permission churn.
+- Shared vendor downloads and bundle swaps are serialized.
 
-### `impel status`
+### Windows
 
-Shows whether the isolated CLI launchers are ready, and whether each native
-tool profile is currently in **GATEWAY** or **ACCOUNT** mode (detected from
-whether the Impel markers / base URL are present), plus:
+- Missing official Claude Code and Codex CLIs can be installed during setup.
+- Signed vendor desktop executables remain unchanged.
+- Tenant profiles and Start entries are isolated per tenant.
+- Shared package-manager/vendor preparation runs once per product.
+- System-level installer and PATH changes require confirmation.
 
-- the configured gateway URL,
-- whether a PAT is stored (masked, e.g. `impel_pat_ab12...wxyz`),
-- the live Workspace member / Gateway member entitlement when available,
-- a best-effort reachability check: a `POST` to `<gateway>/anthropic/v1/messages`
-  with a 5s timeout. Any HTTP response (including a 4xx) counts as "reachable" —
-  this checks the network path and gateway routing, not the request itself. A
-  `401`/`403` is called out separately since it usually just means the stored PAT
-  was rejected, not that the gateway is down.
+### Linux
 
-Codex CLI and the Codex IDE extension / desktop app share the same
-`~/.codex/config.toml`, so they always report the same mode.
+- Every tenant receives isolated CLI profiles.
+- Managed desktop apps are unavailable.
+- Missing vendor CLIs are reported rather than installed through an unverified
+  mechanism.
 
-## Isolated Impel desktop apps
+## Local state
 
-### Windows Claude and ChatGPT Desktop
+Main paths:
 
-```powershell
-impel app open claude
-impel app status claude
-impel app open codex
-impel app status codex
+```text
+~/.config/impel/config.json
+~/.config/impel/cli/tenants/<tenant>/
+~/.config/impel/apps/tenants/<tenant>/
 ```
 
-The Windows path does not clone, patch, or re-sign Claude. It locates either
-Anthropic's standard Squirrel installation or its signed MSIX package, then
-launches the vendor executable with the supported `CLAUDE_USER_DATA_DIR`
-override. Anthropic's MSIX manifest explicitly reserves `%LOCALAPPDATA%\Claude-3p`
-for unvirtualized third-party profiles, so each Impel tenant lives below that
-root. The app's normal first-party profile is not read or changed. `impel setup`
-installs this profile by default; use `--skip-apps` to omit it.
-
-For ChatGPT/Codex Desktop, Windows installs the official Microsoft Store product
-`9PLM9XGG6VKS` (`OpenAI.Codex`). Windows blocks other programs from directly
-executing Electron inside `C:\Program Files\WindowsApps`, so Impel copies the
-vendor's complete `app` payload, unchanged, into a shared managed cache. It
-then launches that copy with a separate `CODEX_HOME` and
-`CODEX_ELECTRON_USER_DATA_PATH` (plus Electron `--user-data-dir` as a legacy
-fallback). The normal Store app, `%USERPROFILE%\.codex`, and the normal ChatGPT
-browser profile are not read or changed. `chatgpt` and `codex` are equivalent
-app-target names.
-
-### macOS Claude and ChatGPT
-
-The first `impel app open --tenant <org>` (or an explicit `impel app install`)
-creates tenant-specific apps such as
-`Impel Claude (acme).app` and `Impel ChatGPT (acme).app` in `~/Applications`.
-Their visible bundle names use the organization display name, for example
-`Impel Claude (Acme)` and `Impel ChatGPT (Acme)`. Each tenant/product pair has
-a stable, unique bundle identifier and gateway configuration:
-
-- Impel Claude is an APFS-cloned vendored copy of the official app with its own
-  bundle and helper identities. Its LaunchServices environment sets both the
-  vendor-supported `CLAUDE_USER_DATA_DIR` and Claude Code's
-  `CLAUDE_CONFIG_DIR` to the tenant-private profile. This isolates browser
-  state, sessions, plugins, MCP servers, skills, and native `@` agents from
-  `~/.claude`, while the app writes the 3P gateway
-  `configLibrary` below `~/.config/impel/apps/tenants/<org>/claude`. A new
-  isolated profile defaults to the Code app while preserving any app selection
-  the user makes afterward. A narrowly version-checked compatibility patch
-  connects Claude's native plan-usage meter to the authenticated aggregate
-  Claude subscription pool exposed by the Impel gateway.
-- Impel ChatGPT wraps an APFS-cloned official app while preserving the nested
-  OpenAI-signed bundle and executable. A wrapper-owned startup preload pins
-  Electron's application name before the native menu is created, so macOS
-  shows `Impel ChatGPT (<org>)` without changing OpenAI's signed code. Its outer
-  resource root contains the narrowly patched renderer ASAR used at runtime.
-  The wrapper sets `CODEX_HOME`,
-  passes a separate Chromium `--user-data-dir`, and writes its provider config
-  and model catalog below `~/.config/impel/apps/tenants/<org>/chatgpt`. It also supplies a
-  process-scoped, Codex-compatible wrapper around the Impel PAT so native
-  `/status` requests can read the organization's aggregated subscription pool
-  from the gateway. Its generated Codex config uses the same snapshot and
-  subprocess-environment hardening as `impel codex`; install, update, and every
-  direct app launch also remove older snapshots for the selected profile, while
-  app install/update/open sweeps inactive tenant and legacy Impel app profiles.
-- Neither app changes `~/.claude`, `~/.claude.json`, `~/.codex`, or the
-  normal vendor app's browser/profile data.
-
-Open several tenants without changing the current selection. A missing variant
-is installed and configured automatically before it opens:
+The config directory is owner-only and the config file is written with mode
+`0600` where supported. Generated client profiles use tenant-bound helper
+invocations; PAT material is not embedded into shell entries.
 
-```sh
-impel app open all --tenant acme
-impel app open all --tenant globex
+Losing membership does not delete local tenant data. A future cleanup feature
+must remain explicit and destructive-state aware.
+
+## Public command surface
+
+```text
+impel setup
+impel update
+impel claude
+impel codex
+impel tenant list|current|use
+impel tasks ...
+impel pat ...
+impel status
+impel doctor
 ```
 
-Updates with `--tenant` and all uninstalls touch only the named tenant variant.
-`impel app update all` without `--tenant` discovers every locally installed
-tenant and updates each sequentially; it does not install variants for tenants
-that have never been installed. The older global `Impel Claude.app` /
-`Impel ChatGPT.app` launcher is removed after the first successful
-tenant-specific rebuild.
-
-`impel app update` compares the installed bundle's build fingerprint, signing
-mode, pinned vendor version, identity, profile paths, and ASAR compatibility
-hash before touching it. The build fingerprint tracks the bundle-BUILDING logic
-(asar patches, plist rewrites, signing), not the CLI version, so a CLI release
-that doesn't change bundle bytes leaves installed bundles — and their macOS
-permission grants — alone. A current bundle is not closed, cloned, patched, or
-codesigned; its config and model catalog are still refreshed. If an interrupted
-update left a machine in a bad state, `impel app update --force` removes the
-selected launcher and performs a clean rebuild while sweeping abandoned
-`.tmp-*` and `.previous-*` staging directories.
-
-Skills plugin subprocesses run asynchronously, so the TTY progress indicator
-continues animating while Claude or Codex refreshes a marketplace. Skill status
-lines temporarily clear and redraw the spinner instead of overwriting it.
-
-The official Claude and ChatGPT apps remain separate installations and keep
-their normal accounts, updater, profiles, and bundle identities. Each CLI
-release pins exact, tested vendor builds (v0.10.0 pins Claude `1.20186.9` and
-ChatGPT `26.707.72221`) and their archive SHA-256 digests. The installer reuses
-an existing official app only when its version exactly matches; otherwise it
-downloads the pinned signed archive into Impel's managed vendor cache under
-`~/.config/impel/vendor`, verifies its digest, bundle version, layout, and code
-signature, and only then rebuilds the isolated app. It never clones a moving
-Homebrew or vendor “latest” release, and it never downgrades or replaces the
-user's normal vendor app. A future app version requires a new tested CLI release
-and pin update. Config refreshes do not download or replace apps. If the model
-endpoint is temporarily unavailable, the installer retains functionality using
-the CLI's bundled catalog.
-
-For ChatGPT/Codex, the gateway controls which models and capabilities are
-enabled while the installer merges those entries with the vendor app's native
-catalog. The Impel copy relaxes the vendor renderer's ChatGPT-account-only Fast
-gate because gateway auth supplies the entitlement instead. The outer wrapper
-is then signed locally (see below) without replacing the nested OpenAI signing
-identity. This preserves model-specific instructions and exposes
-the same reasoning-effort and service-tier controls as the normal app, including
-Ultra where supported and Fast only on models that advertise the `priority`
-tier. Inference uses an explicit non-WebSocket Impel model provider so Codex
-cannot fall back to the vendor's hard-coded `chatgpt.com` transport with an
-Impel PAT. Config refreshes replace only the Impel-managed gateway block; plugins,
-desktop preferences, projects, and other settings written by the isolated app
-are kept.
-
-Impel Claude and the outer Impel ChatGPT wrapper are signed locally after their
-bundle identities and launch wrappers are installed. The nested ChatGPT bundle
-retains OpenAI's signature.
-
-By default the CLI signs each rebuild with a **stable per-machine identity** — a
-self-signed certificate created once in a dedicated keychain under
-`~/.config/impel/codesign` (no Apple Developer account is involved). The
-certificate is trusted locally for the code-signing policy only; it is not a
-TLS or document-signing authority. macOS ties
-every privacy (TCC) grant — microphone, screen recording, folder access,
-Automation, accessibility — to the app's code-signing designated requirement. A
-stable identity keeps that requirement constant across rebuilds, so the grants
-you approve survive `impel app update` the way they do for a normal app instead
-of re-prompting after every rebuild. The one-time switch from the old ad-hoc
-signature to the stable identity triggers a single final round of prompts. If
-the local signing toolchain is unavailable the CLI logs a notice and falls back
-to ad-hoc signing (the previous behavior). Two environment overrides are
-available: `IMPEL_CODESIGN_ADHOC=1` forces ad-hoc signing, and
-`IMPEL_CODESIGN_IDENTITY=<name>` signs with a specific existing identity (e.g. a
-real `Developer ID Application: …`).
-
-Older Claude profiles already encrypt browser data with the macOS login
-Keychain item named `Claude Safe Storage`. Impel keeps that namespace immutable
-so an update never makes existing cookies or storage unreadable. Because each
-tenant app has a distinct bundle identity, macOS asks once before that app may
-use the legacy item: enter the Mac login password and choose **Always Allow**.
-Choosing **Allow** grants access for only that launch and therefore prompts
-again next time. The stable Impel signature keeps a successful Always Allow
-grant valid across later app updates. Clean profiles instead start with a
-persisted tenant-specific Safe Storage namespace, so they never request access
-to the shared vendor item. Impel does not weaken or silently rewrite Keychain
-access lists.
-
-The Claude 3P config necessarily contains the PAT because that app accepts a
-gateway API key rather than a token-helper command. It is stored in the same
-owner-only Impel config tree as the primary credential. ChatGPT/Codex uses a
-command-backed helper and does not copy the PAT into TOML. The installable app
-also reads that helper into its own process environment for Codex account-status
-compatibility; the value disappears when the app exits.
-
-## Switching back and forth
-
-The whole point: flipping between the gateway and your own account is one
-command, per tool, and always reversible.
+Profile helpers, content synchronization, desktop maintenance, and transport
+commands are internal implementation details and intentionally absent from
+normal help.
 
-```sh
-impel on                 # both tools -> gateway
-impel off                # both tools -> your own account (restores prior config exactly)
+## Library export
+
+The package continues to expose `impel-cli/gateway` for approved branded
+vendor integrations. Its CLI allowlist is deliberately narrow and does not
+expose control-plane administration commands.
 
-impel on codex           # just Codex -> gateway, leave Claude Code alone
-impel off claude         # just Claude Code -> account
+## Development
 
-impel status             # see where each tool stands right now
+The project is dependency-free at runtime and uses Node's built-in test runner:
+
+```sh
+npm test
+npm pack --dry-run
 ```
 
-How the clean revert is guaranteed: `impel on` records the pre-existing values
-(your own `apiKeyHelper` / `ANTHROPIC_BASE_URL` / Claude sandbox and permission
-policy, and Codex's prior `model_provider`, sandbox mode, and workspace network
-value) into
-`~/.config/impel/config.json` **before** overwriting them,
-and only ever captures a real *account-mode* value (re-running `impel on` never
-clobbers the backup with Impel's own values). `impel off` removes only keys that
-still point at Impel and restores those backups — so a full `on` → `off`
-round-trip leaves `settings.json` and `config.toml` byte-for-byte back to where
-they started, with all your unrelated keys and tables intact.
-
-If you'd rather revert by hand: delete `apiKeyHelper`, the Impel
-`ANTHROPIC_BASE_URL`, and the Impel-managed sandbox keys from
-`~/.claude/settings.json`, plus the Impel-added `WebFetch(domain:*)` allow rule; delete the block between the
-`# >>> impel-cli managed block ... >>>` / `# <<< impel-cli managed block <<<`
-markers in `~/.codex/config.toml`, reset `model_provider`, and restore or remove
-`sandbox_mode` and `sandbox_workspace_write.network_access`; and
-`rm -rf ~/.config/impel` to forget the PAT + gateway entirely.
-
-## Codex compatibility route
-
-The installable app uses an explicit Codex model provider at
-`<gateway>/chatgpt_passthrough/backend-api/codex`, producing the request path
-`/chatgpt_passthrough/backend-api/codex/responses`. The provider disables
-WebSockets because the vendor's built-in ChatGPT provider derives that URL from
-`chatgpt.com` rather than the configured account-service base. The gateway
-preserves the request body while replacing the Impel PAT with the selected
-ChatGPT subscription credential.
-
-The installable Impel ChatGPT app also points Codex's account client at
-`<gateway>/chatgpt_passthrough/backend-api`. The gateway exposes a virtual Impel
-pool identity and `GET .../wham/usage`, aggregating each primary and secondary
-subscription window across all active Codex seats with equal-seat weighting.
-This lets the native `/status` surface show pool capacity without exposing any
-provider account identity or OAuth credential.
-
-Before every launch, the wrapper refreshes Codex's supported personal-access-token
-login record from the tenant helper. That keeps the desktop app in native
-ChatGPT-account mode, allowing `/status` to request the aggregate five-hour and
-weekly windows instead of treating Impel as an API-key-only provider.
-
-The gateway also exposes `POST /v1/responses`, but that is the conventional
-OpenAI Responses front door for SDK/Eve traffic and may normalize the body
-(including enforcing `store: false`). The CLI deliberately does not use it.
-
-## Design notes
-
-- **Zero dependencies.** Arg parsing, JSON/TOML merging, masked prompts, and the
-  reachability check are all hand-rolled against Node stdlib (`fs`, `os`,
-  `path`, `readline`, global `fetch`). No `chalk`, no `commander`, no `inquirer`.
-- **The PAT lives in exactly one place:** `~/.config/impel/config.json` (mode
-  `0600`). Both Claude Code and Codex fetch it on demand by shelling out to
-  `impel token` rather than copying it into their own config files — one token,
-  one rotation path, no stale copies.
-- **The `config.toml` merge is intentionally narrow**, not a general TOML
-  parser: it touches the top-level `model_provider`, sandbox mode, the
-  workspace-write network toggle, and its own fenced `[model_providers.impel*]` block, leaving unrelated
-  tables (other providers, MCP servers, sandbox policy, etc.) untouched.
-
-## Sources consulted for the Codex config
-
-- https://developers.openai.com/codex/config-reference
-- https://developers.openai.com/codex/config-advanced
-- https://developers.openai.com/codex/auth
-- https://developers.openai.com/codex/ide
-
-## Sources consulted for the Claude sandbox config
-
-- https://code.claude.com/docs/en/settings#sandbox-settings
-- https://code.claude.com/docs/en/sandboxing#configure-the-sandbox-for-your-organization
-- https://github.com/anthropics/claude-code/blob/v2.1.214/examples/settings/settings-bash-sandbox.json
-
-## Sources consulted for concurrent tenant apps
-
-- Electron v43.1.0 release: https://github.com/electron/electron/releases/tag/v43.1.0
-- Electron applies `--user-data-dir` before app JavaScript:
-  https://github.com/electron/electron/blob/b5c102b3f0f7e9c5be064ba337a3547a83cf7d09/shell/app/electron_main_delegate.cc#L247-L256
-- Electron scopes its single-instance lock to the resolved user-data directory:
-  https://github.com/electron/electron/blob/b5c102b3f0f7e9c5be064ba337a3547a83cf7d09/shell/browser/api/electron_api_app.cc#L1049-L1073
-- Electron macOS bundle rebranding requirements:
-  https://github.com/electron/electron/blob/b5c102b3f0f7e9c5be064ba337a3547a83cf7d09/docs/tutorial/application-distribution.md#L79-L96
-- Apple `CFBundleIdentifier` reference:
-  https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundleidentifier
+Tests use temporary homes, injected process runners, fake catalogs, and local
+HTTP fixtures. They must not require a live PAT, launch or close a real app,
+run a real package manager, or modify native personal profiles.
+
+CI runs on Ubuntu, macOS, and Windows with supported Node versions. See
+[RELEASING.md](RELEASING.md) for the npm release process.