docs(smoke): codex-cli loopback template + capability evidence index

Adds two evidence-tracking documents under docs/smoke-evidence/. Both
are templates / tracking sheets — neither claims any smoke run has
actually passed. Operators fill them in as smoke gets executed.

  - 2026-04-28-codex-cli-toml-loopback-template.md (163 lines):
    Codex-CLI-specific TOML bearer-env-headers smoke template.
    Mirrors the exact shape buildTomlMcpBlock emits for Codex CLI
    (HTTP transport with bearer_token_env_var = PERPLEXITY_MCP_BEARER
    and the [mcp_servers.<name>.env_http_headers] sub-table). Has
    separate sign-off sections for Linux / macOS 14+ / Windows 11;
    each contains 7 functional checks plus a bearer-rotation check.
    Every checkbox starts unchecked; every <name>/<date>/<port> is a
    placeholder.

  - INDEX.md (126 lines): tracking sheet listing every IDE in
    IDE_METADATA × httpBearerLoopback claim × current evidence state.
    Today: 11 IDEs claim httpBearerLoopback: true but all are
    "Backed N" because the existing 2026-04-24 evidence doc tested
    "an" IDE on Win11 only (extrapolation). Pending matrix is ~9
    cells, ~3-7h operator time. Methodology note codifies the
    "Backed Y" requirements: named IDE + signed OS section + all
    transport boxes checked.

Both files live under docs/ which is gitignored (.gitignore:66) and
were force-added (git add -f) per the post-public-repo workflow that
keeps .gitignore unchanged but allows narrow per-file inclusion.

The audit found that codexCli's existing evidence reference points
at the 2026-04-24 doc which only shows JSON headers.Authorization
shape and pre-dates commit 895b04d that introduced the TOML
bearer_token_env_var indirection. A follow-up (NOT in this commit)
should update packages/shared/src/constants.ts to point
codexCli.capabilities.evidence.httpBearerLoopback at the new
template doc, or downgrade the claim to false until the new template
is signed off.

Validation:
  - npm run typecheck / build / test:coverage: all green at
    commit 0a003f3 (the prior commit on this branch); these new
    files add no source / test surface.

NO smoke claimed as passed. NO source files modified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: A.R.

docs/smoke-evidence/2026-04-28-codex-cli-toml-loopback-template.md

@@ -0,0 +1,163 @@
+# Codex CLI TOML bearer-env http-loopback — smoke evidence (TEMPLATE)
+
+> Status: **TEMPLATE — UNFILLED.** No checkbox below has been verified. Operator
+> must edit this file in-place when actually running the smoke. Do NOT cite this
+> file as evidence until at least one OS section is signed off.
+
+## Why this addendum exists
+
+The 2026-04-24 evidence doc (`2026-04-24-http-loopback-static-bearer.md`)
+records the JSON-shaped `headers.Authorization: "Bearer <token>"` http-loopback
+shape used by Cursor, Claude Desktop, Claude Code, Cline, Windsurf, Windsurf
+Next, Amp, Roo Code, Continue.dev, and Zed. It does **not** cover Codex CLI:
+
+- Codex CLI consumes `~/.codex/config.toml`, not `mcp.json`.
+- Codex CLI does not accept a literal bearer in `[mcp_servers.<name>]`. Bearer
+  must be referenced indirectly via `bearer_token_env_var` and the actual value
+  set in `[mcp_servers.<name>.env_http_headers]`.
+- The shape was added in commit `895b04d` (2026-04-26),
+  *after* the 2026-04-24 doc was written — so referencing the older doc as
+  evidence for `codexCli.httpBearerLoopback` is structurally wrong.
+
+This template captures the per-OS smoke needed to back the Codex CLI claim.
+
+## Front-matter
+
+- **Date:** 2026-04-XX (operator fills)
+- **Operator:** <name>
+- **Platform:** <Linux distro / macOS version / Windows version>
+- **Codex CLI version:** <version, e.g. output of `codex --version`>
+- **Extension version:** <e.g. perplexity-vscode-0.8.10.vsix>
+- **Daemon port:** <port from `~/.perplexity-mcp/daemon.lock`>
+
+## Setup performed
+
+1. Install the VSIX from a clean profile (or note the prior state).
+2. Open VS Code with the extension installed at the version above.
+3. Open the dashboard, enable the daemon, note the port and the active bearer.
+4. From the command palette, run **"Perplexity: Configure for All"** (or the
+   per-IDE action for `codexCli` from the IDEs tab with transport
+   `http-loopback`).
+5. Verify it writes `~/.codex/config.toml` (Windows: `%USERPROFILE%/.codex/config.toml`)
+   with the HTTP-transport TOML shape shown below.
+6. Restart Codex CLI; verify `Perplexity` appears in its MCP server list with
+   `enabled = true` and reports as authenticated (no `Auth: Unsupported` for
+   the loopback bearer path — that warning is a known cosmetic display for the
+   stdio launcher and is documented in `linux/perplexity-codex-mcp-setup-issue.md`).
+7. List MCP tools — confirm `perplexity_search`, `perplexity_doctor`,
+   `perplexity_models`, `perplexity_research`, `perplexity_compute` appear.
+
+## Expected TOML on disk
+
+The auto-config writer (`buildTomlMcpBlock` in
+`packages/extension/src/auto-config/index.ts`) emits the following exact shape
+when given an `http-loopback` server config (an object with a `url` key and
+`headers.Authorization = "Bearer <token>"`). The env var name is derived as
+`<SERVERNAME>_MCP_BEARER` with non-alphanumerics collapsed to `_`. For server
+name `Perplexity` this yields `PERPLEXITY_MCP_BEARER`.
+
+```toml
+[mcp_servers.Perplexity]
+url = "http://127.0.0.1:<daemon-port>/mcp"
+bearer_token_env_var = "PERPLEXITY_MCP_BEARER"
+enabled = true
+
+[mcp_servers.Perplexity.env_http_headers]
+PERPLEXITY_MCP_BEARER = "<daemon-static-bearer>"
+```
+
+Notes:
+- No `command`/`args` keys appear when `url` is set — that branch is exclusive.
+- No `[mcp_servers.Perplexity.env]` block is written for the loopback transport.
+  (`env` is reserved for the stdio-launcher transport, where things like
+  `PERPLEXITY_HEADLESS_ONLY` belong.)
+- The bearer is a literal value in `env_http_headers`. Codex CLI reads it at
+  spawn time; rotating the bearer requires the file to be re-written and Codex
+  to re-spawn the MCP child (see "Bearer rotation check" below).
+
+Operator: paste the actual TOML written on disk here for the run, and confirm
+it matches the shape above.
+
+```toml
+<paste actual ~/.codex/config.toml [mcp_servers.Perplexity] block here>
+```
+
+## Smoke checks — Linux (Ubuntu 22.04 / Fedora 40 / Arch — pick one)
+
+Distro tested: <fill>
+
+- [ ] `~/.codex/config.toml` contains the exact `[mcp_servers.Perplexity]` shape above
+- [ ] Codex CLI lists Perplexity MCP server as `enabled`
+- [ ] `perplexity_doctor` returns OK; `vault` check `pass`
+- [ ] `perplexity_search` returns results with citations
+- [ ] `perplexity_models` returns the right tier (Pro/Max)
+- [ ] `perplexity_research` with a simple prompt returns a research result
+- [ ] `perplexity_compute` with a file-producing prompt; verify file appears in `~/.perplexity-mcp/downloads/<slug>/`
+
+### Bearer rotation check (Linux)
+
+- [ ] After running the extension command "Rotate bearer", confirm the
+      `env_http_headers` block in `~/.codex/config.toml` updates AND Codex CLI's
+      next call still authenticates without manual restart of Codex itself
+      (or, document the restart requirement here if one is needed).
+
+### Sign-off (Linux)
+
+- [ ] All boxes above are checked (no extrapolation)
+- Operator signature: <name> <date>
+
+## Smoke checks — macOS 14+
+
+- [ ] `~/.codex/config.toml` contains the exact `[mcp_servers.Perplexity]` shape above
+- [ ] Codex CLI lists Perplexity MCP server as `enabled`
+- [ ] `perplexity_doctor` returns OK; `vault` check `pass`
+- [ ] `perplexity_search` returns results with citations
+- [ ] `perplexity_models` returns the right tier (Pro/Max)
+- [ ] `perplexity_research` with a simple prompt returns a research result
+- [ ] `perplexity_compute` with a file-producing prompt; verify file appears in `~/.perplexity-mcp/downloads/<slug>/`
+
+### Bearer rotation check (macOS)
+
+- [ ] After "Rotate bearer", `env_http_headers` updates AND Codex's next call still authenticates
+
+### Sign-off (macOS)
+
+- [ ] All boxes above are checked (no extrapolation)
+- Operator signature: <name> <date>
+
+## Smoke checks — Windows 11
+
+- [ ] `%USERPROFILE%/.codex/config.toml` contains the exact `[mcp_servers.Perplexity]` shape above
+- [ ] Codex CLI lists Perplexity MCP server as `enabled`
+- [ ] `perplexity_doctor` returns OK; `vault` check `pass`
+- [ ] `perplexity_search` returns results with citations
+- [ ] `perplexity_models` returns the right tier (Pro/Max)
+- [ ] `perplexity_research` with a simple prompt returns a research result
+- [ ] `perplexity_compute` with a file-producing prompt; verify file appears in `%USERPROFILE%/.perplexity-mcp/downloads/<slug>/`
+
+### Bearer rotation check (Windows)
+
+- [ ] After "Rotate bearer", `env_http_headers` updates AND Codex's next call still authenticates
+
+### Sign-off (Windows)
+
+- [ ] All boxes above are checked (no extrapolation)
+- Operator signature: <name> <date>
+
+## What was NOT tested by this addendum
+
+- The stdio-launcher transport for Codex CLI (the `command`/`args` shape with
+  `[mcp_servers.Perplexity.env]`) — that is the Linux setup-issue subject of
+  `linux/perplexity-codex-mcp-setup-issue.md` and needs its own evidence doc
+  if/when the headless-vault path is signed off.
+- `httpOAuthLoopback` for Codex CLI — not yet wired in `IDE_METADATA`.
+- `httpOAuthTunnel` for Codex CLI — not yet wired in `IDE_METADATA`.
+
+## Replay (operator quick-reference)
+
+1. Install the VSIX.
+2. Dashboard → enable daemon → note port.
+3. IDEs tab → Codex CLI → transport `http-loopback` → Generate.
+4. Inspect `~/.codex/config.toml` → confirm shape matches "Expected TOML on disk".
+5. Restart Codex CLI → list MCP tools → run smoke checks above.
+6. Rotate bearer from the dashboard → confirm config updates → re-run a tool call.

docs/smoke-evidence/INDEX.md

@@ -0,0 +1,126 @@
+# Smoke-evidence index
+
+## Purpose
+
+This index tracks which (IDE × transport × OS) combinations have *signed*
+smoke evidence under `docs/smoke-evidence/`. An entry is "Backed Y" only when
+an evidence file (a) explicitly names the IDE, (b) has its OS section signed
+off, and (c) has every checkbox for the relevant transport checked. Empty
+entries, generic templates, and extrapolations from a single-IDE, single-OS
+run do **not** count. If a row is "Backed N", the corresponding capability
+claim in `packages/shared/src/constants.ts` is currently asserted without
+matching primary evidence — the parent should treat this as a gap to close
+before the public-repo cut, not as a green-light to ship.
+
+## Capability claims with evidence (current state, 2026-04-28)
+
+Source of claims: `packages/shared/src/constants.ts` (`IDE_METADATA`).
+Evidence files cited in that file: `2026-04-24-http-loopback-static-bearer.md`
+(JSON shape, Win11 only) and the new
+`2026-04-28-codex-cli-toml-loopback-template.md` (Codex TOML shape, all OSes
+unfilled).
+
+| IDE | configFormat | httpBearerLoopback claim | Evidence file currently referenced | Backed Y/N | OS coverage (signed) |
+|---|---|---|---|---|---|
+| cursor | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only, and the Win11 doc does not name this IDE specifically |
+| windsurf | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| windsurfNext | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| claudeDesktop | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| claudeCode | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| cline | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| amp | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| rooCode | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| codexCli | toml | true | 2026-04-24-http-loopback-static-bearer.md (WRONG SHAPE — that doc only shows JSON `headers.Authorization`) | N (wrong-shape reference) | None — the TOML `bearer_token_env_var` indirection is not covered by the cited doc |
+| continueDev | yaml | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated; YAML config shape not shown in the doc either) | Win11 only; IDE not named |
+| zed | json | true | 2026-04-24-http-loopback-static-bearer.md | N (extrapolated) | Win11 only; IDE not named |
+| copilot | ui-only | false | n/a | Y (claim is `false`, no evidence required) | n/a |
+| geminiCli | json | false | n/a | Y (claim is `false`, no evidence required) | n/a |
+| aider | yaml | false | n/a | Y (claim is `false`, no evidence required) | n/a |
+| augment | json | false | n/a | Y (claim is `false`, no evidence required) | n/a |
+
+`httpOAuthLoopback` and `httpOAuthTunnel` are `false` for every IDE in
+`IDE_METADATA` and therefore require no evidence today. If either is flipped
+to `true` for any IDE, a new dated evidence doc must be added and a new row
+appended to this index.
+
+## Pending evidence work
+
+Estimates from the prior audit: ~15 minutes per IDE-specific shape verification
+(when batched into a single VS Code session and a single Codex/Cursor/etc.
+restart), ~30 minutes per OS for a full sweep across all bearer-loopback IDEs
+(setup, install, run, sign off).
+
+### Codex CLI TOML bearer-env (new shape, dedicated template)
+
+Template doc: `docs/smoke-evidence/2026-04-28-codex-cli-toml-loopback-template.md`
+
+- [ ] codexCli × Linux — ~15 min, fills the Linux section
+- [ ] codexCli × macOS 14+ — ~15 min, fills the macOS section
+- [ ] codexCli × Windows 11 — ~15 min, fills the Windows section
+
+### JSON `headers.Authorization` bearer-loopback (existing shape)
+
+Existing doc: `docs/smoke-evidence/2026-04-24-http-loopback-static-bearer.md`
+(currently Win11 only, no per-IDE naming). To convert "extrapolated" to
+"Backed Y", either (a) extend that doc with explicit per-IDE sub-sections and
+sign-offs per OS, or (b) create one new dated doc per OS that enumerates each
+IDE name with a checkbox and sign-off line.
+
+Per-OS sweeps (each ~30 min if batched, covers 9 IDEs: cursor, windsurf,
+windsurfNext, claudeDesktop, claudeCode, cline, amp, rooCode, zed):
+
+- [ ] JSON sweep × Linux
+- [ ] JSON sweep × macOS 14+
+- [ ] JSON sweep × Windows 11 (the existing 2026-04-24 doc partially covers this but does not enumerate per-IDE sign-offs)
+
+### YAML bearer-loopback (Continue.dev — separate shape)
+
+The 2026-04-24 doc does not show the YAML shape. Continue.dev consumes a
+different config format and needs its own dedicated evidence doc per OS.
+
+- [ ] continueDev × Linux — ~15 min (new doc required first)
+- [ ] continueDev × macOS 14+ — ~15 min
+- [ ] continueDev × Windows 11 — ~15 min
+
+### Existing template files awaiting fill
+
+These pre-existing files in `docs/smoke-evidence/` are unfilled v0.8.6
+release-smoke templates. They are not transport-specific; they are
+release-gate checklists. Filling them is part of the release process
+(`docs/release-process.md`), not part of the per-IDE evidence backfill above:
+
+- `2026-04-XX-v0.8.6-win11.md`
+- `2026-04-XX-v0.8.6-macos14.md`
+- `2026-04-XX-v0.8.6-ubuntu22.md`
+
+### Total operator time to fully back the matrix
+
+Lower bound assuming all batched: ~3 hours (3 OSes × 1 hour: one Codex run +
+one JSON sweep + one Continue.dev run per OS, with some setup overlap).
+Upper bound, treating each cell as independent: 9 IDE-specific runs ×
+3 OSes × 15 min = ~7 hours.
+
+## Methodology note
+
+A capability claim is "Backed Y" in this index only when **all three** are true:
+
+1. An evidence doc exists at the path referenced from `IDE_METADATA`.
+2. That doc explicitly names the IDE (so a reader can verify the claim
+   without inference). A doc that says "every JSON IDE" is generic; it does
+   not back any specific IDE row.
+3. The OS section relevant to the operator's platform is fully checked and
+   signed off (operator name + date). An empty checkbox or a placeholder
+   `<name>` does not count.
+
+Generic claims, extrapolations, and template-only files do **not** count as
+backing. Treat them as "we believe this works, but we have not actually
+verified it for this combination."
+
+## Maintenance
+
+When you add a new evidence doc or sign off on a section:
+
+1. Update the row in the table above (Backed Y, list the OS).
+2. Move the corresponding line out of "Pending evidence work".
+3. If you flip a capability from `false` to `true` in
+   `packages/shared/src/constants.ts`, add the row here in the same commit.