Add setup wizard for T3-scoped Codex MCP installation

.plans/setup-and-release.md

@@ -1,6 +1,6 @@
 # Setup and release work order
 
-Status: Windows x64 support is implemented and tested on Gideon; see [verification](../docs/compatibility.md#windows-verification). The wizard, automatic update handoff, and release workflow remain planned from the September 11 setup discussion.
+Status: Windows x64 support is implemented and tested on Gideon; see [verification](../docs/compatibility.md#windows-verification). The setup installer is implemented; see [installer usage](../docs/installer.md). Automatic update handoff and the release workflow remain planned.
 
 ## Order of work
 
@@ -24,7 +24,7 @@ Provide instance selection and custom-location fallback, resolve the selected Co
 
 Default to T3-only tool availability. Update both Codex MCP registration and the selected T3 provider's launch arguments, checking environment overrides. Keep each installation's destination separate when multiple T3 instances share Codex configuration. See [T3 scoping](t3-only-mcp.md).
 
-Default to the stable update channel, with explicit nightly opt-in. Persist the selected channel independently of the exact package version used to run setup. Do not pin ordinary installations to the setup version. An explicit version may remain an advanced troubleshooting option.
+Inherit the release channel from the invoked package version; do not ask a channel question. Stable packages configure latest and nightly packages configure nightly. Do not pin ordinary installations to the setup version. A local runtime path supports checkout use before publication.
 
 Verification must not send messages or restart existing watches as a side effect. Preserve running T3 conversations and state which checks require a fresh provider session.
 

README.md

@@ -4,6 +4,18 @@ Watch a GitHub PR and notify an existing T3 Code conversation when something cha
 
 Three MCP tools: `watch`, `list`, and `stop`. `watch` automatically starts a background worker that polls every 60 seconds without invoking a model. It survives MCP disconnection and exits when there is nothing left to watch. No skill or service installation is required.
 
+## Setup wizard
+
+With T3 running, build this checkout and run the installer:
+
+```sh
+npm ci
+npm run build
+node dist/cli.js setup --runtime-path ./dist/cli.js
+```
+
+It discovers T3, configures Codex with T3-only tools, preserves existing launch arguments, backs up changed files, and verifies the connection. Add `--dry-run` to preview. The local runtime option works before npm publication; after release, use `npx t3poll@latest setup` or `npx t3poll@nightly setup`. See the [installer guide](docs/installer.md).
+
 ## Agent setup
 
 Copy this into your coding agent:

docs/compatibility.md

@@ -81,3 +81,13 @@ node scripts/prove-t3.mjs
 ```
 
 For an npm-installed T3 CLI, set only `T3POLL_TEST_T3_BIN` to its `dist/bin.mjs`. To check real Codex tool scoping without a model call, set `T3POLL_TEST_CODEX_BIN` to the installed native `codex.exe` and run `node scripts/prove-codex.mjs`. This creates a disposable Codex home, verifies no t3poll tools are exposed by default, then verifies `list`, `stop`, and `watch` with `-c mcp_servers.t3poll.enabled=true`. It does not edit the user's Codex or T3 configuration. Both proof scripts accept `T3POLL_TEST_CLI` to exercise a separately installed tarball's `dist/cli.js` instead of the checkout build.
+
+## Setup installer verification
+
+Verified September 11, 2026 with 45 tests: all passed on Gideon Windows x64; 43 passed on Linux with the two Windows-only checks skipped. Installer coverage includes no-write dry runs, separate instance destinations, quoted launch arguments, environment precedence, private backups, stale reviews, rollback after failed credential verification, and idempotent reruns. Type checking passes.
+
+The installer completed against isolated copies of T3 `0.0.41-nightly.20260911.1551` on Linux and the packaged Windows desktop app, using real Codex for the executable check. It created managed credentials, verified MCP connectivity, and reran without duplicate config. No threads or messages were created. The real Codex proof now invokes the installer instead of writing MCP config by hand; it confirms the generated entry is disabled by default and exposes all three tools through the generated T3 launch arguments.
+
+Packed installs in paths containing spaces and non-ASCII characters passed the installer and real Codex scoping proof on Linux and Windows. These checks use `--runtime-path` to exercise the packed CLI before npm publication. Public npm channel resolution and automatic worker handoff remain release work; the installer does not claim to hot-update running workers.
+
+To repeat the stock installer proof, set `T3POLL_TEST_T3_BIN` and `T3POLL_TEST_CODEX_BIN`, optionally `T3POLL_TEST_T3_RUNTIME` for Electron, and run `node scripts/prove-installer.mjs`. All configuration is disposable. `scripts/prove-codex.mjs` separately verifies actual tool availability without model calls.

docs/installer.md

@@ -0,0 +1,59 @@
+# Setup installer
+
+Build the checkout and run setup with T3 open and GitHub CLI signed in:
+
+```sh
+npm ci
+npm run build
+node dist/cli.js setup --runtime-path ./dist/cli.js
+```
+
+Until the first npm release, `--runtime-path` uses this checkout's built CLI. Keep the checkout in place. After publication, use:
+
+```sh
+npx t3poll@latest setup
+# or
+npx t3poll@nightly setup
+```
+
+There is no release-channel question. A stable package configures `latest`; a package whose version contains the nightly prerelease identifier configures `nightly`. npm does not pass its original tag to the program, so setup derives the channel from the running package's version. Unknown prerelease versions are rejected. An explicit local runtime opts out of npm updates.
+
+## Flow
+
+Setup checks GitHub sign-in and finds supported running local T3 instances from `T3CODE_HOME`, the default home, and ancestor `.t3` directories. It asks you to choose when more than one is found. A custom directory can identify other installations. It reads both legacy `providers.codex` and named `providerInstances` settings, with explicit instances taking precedence.
+
+Setup opens with a welcome and a Yes/No prompt to proceed. It asks for an instance or provider only when selection is needed, and offers migration if an existing global entry is enabled. The summary identifies the T3 instance by URL and names the Codex configuration. It explains the tool registration, launch enablement, managed credential, connection checks, and backups before the Install confirmation. File paths are included in `--dry-run` details. Custom paths can be supplied through command-line options. To preview from a script without changing files or credentials:
+
+```sh
+node dist/cli.js setup --base-dir /path/to/t3 --provider codex --dry-run
+```
+
+Other options are `--codex-home`, `--state-home`, and `--yes`. `--yes` accepts the plan but does not guess when multiple instances or providers are available. `--help` lists all options. Setup does not start T3, sign into GitHub, or alter login credentials. If GitHub sign-in is needed, run `gh auth login` in another terminal, then retry.
+
+## Configuration and scope
+
+Each T3 home and Codex provider gets a deterministic `t3poll_<id>` MCP entry, disabled by default. Its environment binds the selected T3 home and t3poll state directory. Multiple installations can share Codex configuration without replacing each other's destinations.
+
+The installer appends the corresponding `-c mcp_servers.t3poll_<id>.enabled=true` to the selected T3 provider's launch arguments. It preserves unrelated arguments, Codex text and comments, and other T3 settings. T3 JSON formatting may change. A rerun updates the owned MCP block and does not duplicate launch flags. Unknown entries and damaged managed blocks require correction rather than being overwritten. If a global `mcp_servers.t3poll` entry is enabled, setup asks whether to disable it and recommends Yes. Yes includes the change in the reviewed plan, preserves its other settings and comments, and backs it up. No preserves it and clearly notes that t3poll remains available outside T3. `--yes` accepts the recommended migration; add `--keep-global` to preserve the global entry when scripting setup.
+
+Configuration files receive adjacent private `.t3poll-<id>.bak` backups before changes. The installer compares the files with the reviewed snapshot and refuses stale writes. If credential verification fails after applying, it restores the previous configuration unless another process has edited it. Backups remain for manual recovery. Adjacent `.t3poll-lock` files prevent overlapping installer writes; after a crashed installer, verify it is no longer running before removing a leftover lock. T3 itself does not participate in those locks, so review-time comparisons and rollback checks also protect against its edits.
+
+The installer checks the selected Codex executable, starts the exact configured MCP command, and verifies the tool catalog. It then creates or reuses a managed T3 credential and reads the thread list to verify connectivity. It never calls `watch`, sends a message, or restarts a worker. Runtime checks can create t3poll state files, and failed attempts can leave those and credential metadata for recovery. Dry runs do not run these checks or write state.
+
+Open a fresh Codex session in the selected T3 instance after setup. Existing sessions keep their current tool catalog. Scoping controls tool availability, not security isolation; users can deliberately enable the MCP entry elsewhere. Project-level or administratively managed Codex configuration can impose additional overrides outside this installer's control.
+
+## Launch-argument conflicts
+
+Having existing arguments is not a conflict. For example, `--enable some_feature -c model_reasoning_effort=high` is retained and the MCP flag is appended.
+
+Setup stops when arguments override the same managed MCP entry, replace its parent `mcp_servers` table, have an unclosed quote or malformed config assignment, or contain `--` after which appending configuration flags is unsafe. The existing exact `enabled=true` override is reused. Other MCP entries are left alone.
+
+`T3CODE_CODEX_LAUNCH_ARGS` is a precedence issue: a nonempty value overrides the saved launch arguments. Setup reads the live T3 process environment and the selected provider's environment, not just the terminal running setup. If the override already enables this entry, it can remain. Otherwise the wizard gives the exact flag to add and asks you to restart T3 and rerun setup. A global override affecting multiple Codex providers must be removed or moved into the selected provider's environment to preserve provider scoping. It never silently edits shell profiles, shortcuts, or another running process's environment.
+
+T3 builds must contain support for `T3CODE_CODEX_LAUNCH_ARGS` in their server bundle. Unrecognized builds are rejected rather than silently installing an ignored setting. Shadow Codex homes use the shared configuration directory; setup follows an existing config symlink without replacing it.
+
+## Updates
+
+The npm launch command uses Node to run npm's CLI directly, including on Windows, avoiding batch-file quoting. It resolves the package channel at MCP startup and needs npm/network access. Verification must succeed before config is changed; there is no cached-version fallback during a failed install.
+
+Running MCP processes and detached workers keep their loaded code. Automatic worker handoff is a separate planned change; this installer does not implement hot updates. Before upgrading a runtime with active watches, follow the existing update guidance in the README.

package.json

@@ -28,8 +28,11 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@clack/prompts": "1.8.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "koffi": "3.2.1",
+    "smol-toml": "1.8.0",
+    "toml-eslint-parser": "1.0.3",
     "zod": "4.6.2"
   },
   "devDependencies": {