feat(cli): COR-35 batch surfaces and lock v2 boards (COR-362–376)

README.md

@@ -140,6 +140,7 @@ Check it worked with `cortex whoami`. See
 | [The TUI](./docs/guides/tui.md) | Timeline, composer, modes, approvals |
 | [Sessions](./docs/guides/sessions.md) | Resume, export, import, share |
 | [Headless / exec mode](./docs/guides/exec.md) | Scripts and CI |
+| [CI cookbook](./docs/guides/ci.md) | Secret-via-env, exit codes, parsing the result |
 | [Plan and Spec modes](./docs/guides/plan.md) | Approve a plan before anything changes |
 | [Configuration](./docs/configuration/config.md) | Files, keys, profiles, permissions |
 | [Agents](./docs/customization/agents.md) · [Skills](./docs/customization/skills.md) · [MCP](./docs/customization/mcp.md) · [Hooks](./docs/customization/hooks.md) · [Plugins](./docs/customization/plugins.md) | Extending Cortex |

design/cli-lock-board-index.md

@@ -5,7 +5,7 @@ Generated from the id lists in the tree at `3035361` (`v0.1.10`):
 `is_lock_board()` in `src/cortex-tui/src/lock_boards.rs:44-99`,
 `LOCK_V2_WIDE_IDS` / `LOCK_V2_NARROW_IDS` in `src/cortex-tui/src/lock_v2_ids.rs`.
 
-Current Designer lock: **v2** (89 wide / 43 narrow), green focus `#1F4945`.
+Current Designer lock: **v2** (110 wide / 58 narrow), green focus `#1F4945`.
 Committed PNGs under `docs/media/tui-lock/` and `docs/media/tui-lock-v2/`
 still include historical violet `#A78BFA` pixels (see those READMEs). The
 ids and tests below are the source of truth:
@@ -249,7 +249,7 @@ Every v2 id is covered by `lock_v2_wide_frames_are_unique` (and
 | Pack | Ids | Sizes | Frames | Live / real | Painted or synthetic | PNGs in repo (all violet) |
 |---|---|---|---|---|---|---|
 | v1 | 72 | 40×12, 120×40 | 144 (+144 macOS composites) | 17 | 51 painted + 4 aliases | 65/72 files carry `#A78BFA` at each size |
-| v2 | 89 wide / 43 narrow | 120×40 / 40×12 | 132 | 72 (7 seeded) | 14 synthetic | runtime 89/89 + 43/43; designer boards 89/89 + 43/43 |
+| v2 | 110 wide / 58 narrow | 120×40 / 40×12 | 168 | 93 (7 seeded) | 14 synthetic | runtime 110/110 + 58/58; designer boards 89/89 + 43/43 |
 
 Regenerate captures: `./scripts/render-tui-lock.sh`,
 `./scripts/render-tui-lock-v2.sh`, `python3 docs/media/tui-lock-v2/tools/render_lock_v2.py --index`.

docs/README.md

@@ -20,6 +20,7 @@ New here? Start with **[Getting started](guides/getting-started.md)**, then keep
 | [The TUI](guides/tui.md) | The interactive UI: timeline, composer, modes, approvals |
 | [Sessions](guides/sessions.md) | Resume, list, export, import, share, protect |
 | [Headless / exec mode](guides/exec.md) | Non-interactive runs for scripts and CI |
+| [CI cookbook](guides/ci.md) | Authenticate from a secret store, run, and parse the result |
 | [Plan and Spec modes](guides/plan.md) | Get a plan approved before anything is written |
 | [Long-horizon persisted goals](guides/goal.md) | `/goal` session-backed objectives |
 | [Editor integration](guides/editor.md) | What running Cortex inside an editor terminal does and does not provide |

docs/customization/mcp.md

@@ -143,14 +143,25 @@ A tool from server `myserver` called `search` is presented as
 
 ## Running Cortex as an MCP-adjacent server
 
-`cortex acp` starts an Agent Client Protocol server for IDE integration:
+`cortex acp` starts an Agent Client Protocol server for IDE integration. **Only
+stdio transport is supported**, and agent selection and per-tool allow/deny
+controls are not implemented — those flags fail closed before the server starts
+rather than running with wider authority than requested:
 
 ```bash
 cortex acp --stdio
-cortex acp --port 8123 --host 127.0.0.1
-cortex acp --allow-tool Read --allow-tool Grep --deny-tool Execute
 ```
 
+The server implements four methods: `initialize`, `session/new`,
+`session/prompt`, and `session/cancel`. `session/load`, `session/list`,
+`models/list`, and `agents/list` are not implemented. Prompts are text-only, and
+approval requests are denied rather than auto-approved, because no permission
+round trip is advertised to the client.
+
+`--port`, `--host`, `--agent`, `--allow-tool`, and `--deny-tool` are parsed but
+rejected. See [Editor integration](../guides/editor.md) for the packaging
+boundary.
+
 ## See also
 
 - [Tools](../reference/tools.md)

docs/guides/ci.md

@@ -0,0 +1,209 @@
+# CI cookbook
+
+Run Cortex CLI in a pipeline without a terminal. This is the consolidated
+cookbook: how to authenticate from a secret store, which command to use, what
+each exit code means, and what to do with the output.
+
+The headless entrypoints are `cortex run` (one message, one result) and
+`cortex exec` (one task, richer output and autonomy control). Both are
+non-interactive and both fail closed when the coding service is unreachable.
+
+## 1. Authenticate from the environment
+
+Never paste a token into a workflow file. Every supported CI system has a secret
+store; put the token there and export it as an environment variable.
+
+| Variable | Use |
+|---|---|
+| `CORTEX_API_KEY` | API key. Set this in CI. |
+| `CORTEX_AUTH_TOKEN` | Session / bearer token. Checked before `CORTEX_API_KEY`. |
+| `CORTEX_API_URL` | Override the API origin. Operators and tests only. |
+
+Resolution order is the stored auth file, then `CORTEX_AUTH_TOKEN`, then
+`CORTEX_API_KEY`. In CI there is no keyring, so an environment variable is the
+only working path — `cortex login` cannot complete without a browser.
+
+Verify the token before spending a turn:
+
+```bash
+cortex whoami
+```
+
+A non-zero exit means the credential is missing or rejected. Fail the job there
+rather than letting every later step fail on its own.
+
+## 2. GitHub Actions
+
+```yaml
+name: cortex-review
+on: pull_request
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # a base branch needs real history
+
+      - name: Install Cortex CLI
+        run: curl -fsSL https://software.cortex.foundation/install.sh | sh
+
+      - name: Review the change
+        env:
+          CORTEX_API_KEY: ${{ secrets.CORTEX_API_KEY }}
+        run: |
+          cortex run --bare --ephemeral \
+            --format json \
+            "Review the diff against origin/${{ github.base_ref }}. Report findings only."
+```
+
+`fetch-depth: 0` matters: a shallow clone has no merge base, so a
+`git diff base...head` review sees the wrong change set.
+
+## 3. GitLab CI
+
+```yaml
+cortex-review:
+  stage: test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    # Masked + protected in Settings → CI/CD → Variables.
+    CORTEX_API_KEY: $CORTEX_API_KEY
+  script:
+    - curl -fsSL https://software.cortex.foundation/install.sh | sh
+    - cortex exec --review-only --auto read-only
+        --output-format json
+        --review-base "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+        "Report findings only."
+```
+
+Mark the variable **masked** so it never appears in job logs, and **protected**
+if only protected branches should be able to read it.
+
+## 4. Any other CI
+
+```bash
+set -euo pipefail
+
+export CORTEX_API_KEY="$(cat /run/secrets/cortex_api_key)"
+cortex whoami
+
+cortex run --bare --ephemeral \
+  --format json \
+  --output-file result.json \
+  "Summarize what changed in this branch and flag anything risky."
+
+# `--format json` prints one document; `result.json` holds the message text.
+```
+
+## 5. Pick the right command
+
+| Need | Command |
+|---|---|
+| One message, one result, no session file | `cortex run --bare --ephemeral` |
+| Structured result for a parser | `cortex run --format json` |
+| Event-by-event stream | `cortex run --format jsonl` |
+| Read-only review that never writes | `cortex exec --review-only` |
+| Autonomy pinned by risk | `cortex exec --auto read-only` |
+| Several turns over one pipe | `cortex exec --input-format stream-jsonl -o stream-json` |
+| Validate the result shape | `cortex run --format json --json-schema` |
+
+`--bare` drops the terminal chrome (progress lines, spacing, annotations) so
+stdout is only the result. `--ephemeral` removes the session rollout file when
+the run finishes, so a CI job leaves nothing behind for `cortex sessions`.
+
+## 6. Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | The task completed. |
+| non-zero | The task did not complete: the run failed, was interrupted, was truncated, or the service was unreachable. |
+
+A non-zero exit is the contract. Do not wrap a failing run in `|| true`; the
+result document also carries `success`, `complete`, `interrupted`, and
+`truncated` so a parser can tell the cases apart without reading stderr.
+
+When the coding service cannot be reached, the CLI prints
+*The coding service is temporarily unavailable* and exits non-zero. It never
+falls back to a local model.
+
+## 7. Read the result
+
+`cortex run --format json` prints one document:
+
+```json
+{
+  "type": "result",
+  "session_id": "…",
+  "message": "the final answer",
+  "events": 12,
+  "success": true,
+  "interrupted": false,
+  "complete": true,
+  "truncated": false,
+  "finish_reason": "stop"
+}
+```
+
+`--json-schema` validates that document against the shipped schema before it is
+printed, so a shape change fails the job instead of silently breaking a parser.
+Print the schema itself when writing the parser:
+
+```bash
+cortex schema list
+cortex schema print run-result
+cortex schema print exec-result
+```
+
+`cortex exec -o json` prints the same idea with its own field names
+(`subtype`, `is_error`, `duration_ms`, `num_turns`) and validates against
+`exec-result`.
+
+## 8. Multi-turn over one pipe
+
+`cortex exec --input-format stream-jsonl -o stream-json` reads one JSON object
+per line and writes one stream back. The connection outlives each turn, so a
+caller can follow up without restarting the process.
+
+```bash
+printf '%s\n' \
+  '{"text":"add a retry helper to the api client"}' \
+  '{"text":"now cover the give-up path with a test"}' \
+  '{"control":"shutdown"}' \
+| CORTEX_API_KEY="$CORTEX_API_KEY" \
+  cortex exec --input-format stream-jsonl -o stream-json --auto read-only
+```
+
+`{"control":"interrupt"}` stops the running turn without ending the stream. A
+line that is not a usable turn produces an error event and the stream
+continues, so one bad line does not drop the rest of the input.
+
+## 9. Keep the run contained
+
+- `--auto read-only` is the default and the safest: the sandbox cannot write.
+- `--review-only` pins both halves (read-only sandbox, no auto-approved writes)
+  and refuses to start when combined with a write-widening flag.
+- `--ephemeral` leaves no session file.
+- Network egress is blocked by default. A run that needs a host needs it in
+  `.cortex/sandbox.toml`; the list is explicit and fails closed.
+- `--bare` keeps stdout to the result, so a stray log line cannot corrupt a
+  parsed document.
+
+## 10. Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `cortex whoami` fails in CI | The secret is not exported for this step, or the job is on an unprotected branch. |
+| Exit non-zero with *The coding service is temporarily unavailable* | The API is unreachable from the runner, or a proxy blocks egress. |
+| The review sees no changes | The clone is shallow. Use `fetch-depth: 0`. |
+| A parse error on stdout | Something else printed to stdout. Add `--bare` and read stderr for logs. |
+| The job leaves sessions behind | Add `--ephemeral`. |
+
+## See also
+
+- [Headless execution](exec.md) — every flag on `run` and `exec`.
+- [Environment variables](../configuration/env.md) — the full variable list.
+- [Login reference](../reference/login.md) — tokens, `--with-api-key`, and CI notes.
+- [CI secrets](../CI_SECRETS.md) — secrets for this repository's own release pipeline.

docs/media/tui-lock-v2/SPEC.md

@@ -10,7 +10,7 @@ runtime chrome ships in `cortex-tui` (`lock_v2_*` scenes plus production paints
 and lock flags: `computer_held`, `show_computer_default`, `offline_held`,
 `rate_limit_held`, `share_link`) so MockTerminal captures can lock the live UI.
 
-- Boards: [`index.md`](index.md) — **96** runtime boards at 120×40, 50 of them also at 40×12. Designer PNG files under `{40x12,120x40}/` from other PRs are not rewritten; new scenes are captured with `generate_tui_lock_screenshots --v2 --only`.
+- Boards: [`index.md`](index.md) — **110** runtime boards at 120×40, 58 of them also at 40×12. Designer PNG files under `{40x12,120x40}/` from other PRs are not rewritten; new scenes are captured with `generate_tui_lock_screenshots --v2 --only`.
 - Grids: `txt/<size>/<board>.txt` — the exact character grid of every board (diff a
   `MockTerminal` capture against these).
 - Renderer: `tools/render_lock_v2.py` + `tools/boards.py` (Python 3 + Pillow, IBM Plex Mono
@@ -433,6 +433,7 @@ Narrow: no bars, `used / total  pct%`.
 | compact chat (ref 5) | `compact-chat` |
 | other product surfaces (not in the brief, kept complete) | `shortcuts-overlay`, `resume-picker`, `clear-confirm`, `plan-confirm`, `queue`, `files-picker`, `jobs`, `skills`, `todos`, `question`, `sudo`, `config-tree`, `btw` |
 | local-tools consent · @file chip · undo/redo/rewind | `consent-local-tools`, `composer-file-chip`, `undo-sheet` |
+| COR-35 batch: headless CI · permission DSL · checkpoints · CI cookbook · JSON Schema · teleport · review-only · marketplace · sandbox allowlist · auto-approval · PR apply-back · ACP · browser use · stdin stream | `bare-ci`, `ci-cookbook`, `permission-rules`, `checkpoint-rewind`, `json-schema`, `cloud-teleport`, `review-only`, `plugin-marketplace`, `sandbox-allowlist`, `auto-approval`, `pr-apply-back`, `acp-editor`, `browser-use`, `stdin-multiturn` |
 
 Narrow (40×12) set: `welcome-cortex`, `welcome-agent`, `first-run-tips`, `session-empty`, `session-user-bars`,
 `session-thinking-live`, `session-assistant`, `session-optin`, `session-shared`, `composer-empty`, `composer-typing`,

docs/media/tui-lock-v2/index.md

@@ -127,6 +127,31 @@ Regenerate: `python3 tools/render_lock_v2.py --index` (fetches IBM Plex Mono on
 | `composer-file-chip` | Composer with attached @file chip in prompt | [120x40](120x40/composer-file-chip.png) | [40x12](40x12/composer-file-chip.png) |
 | `undo-sheet` | /undo /redo /rewind sheet | [120x40](120x40/undo-sheet.png) | [40x12](40x12/undo-sheet.png) |
 
-**96** runtime boards at 120x40 · **50** at 40x12. Designer PNG pack from other PRs is unchanged; new COR-18/225/227/228 scenes are runtime captures. Computer lock boards from #69 stay in the pack. `session-shared` (COR-226) is at both sizes.
+**110** runtime boards at 120x40 · **58** at 40x12. Designer PNG pack from other PRs is unchanged; new COR-18/225/227/228 scenes are runtime captures. Computer lock boards from #69 stay in the pack. `session-shared` (COR-226) is at both sizes.
 
-Runtime MockTerminal pack (same ids): [`runtime/120x40`](runtime/120x40/) (96) · [`runtime/40x12`](runtime/40x12/) (50).
+## F. COR-35 batch (runtime only)
+
+| Board | State | Wide | Narrow |
+|---|---|---|---|
+| `bare-ci` | `cortex run --bare --ephemeral` — no session file, no chrome | [runtime 120x40](runtime/120x40/bare-ci.png) | [runtime 40x12](runtime/40x12/bare-ci.png) |
+| `ci-cookbook` | `docs/guides/ci.md` — secret via env, per-platform recipes | [runtime 120x40](runtime/120x40/ci-cookbook.png) | — |
+| `permission-rules` | `/permissions rules` — committed allow / ask / deny rules | [runtime 120x40](runtime/120x40/permission-rules.png) | [runtime 40x12](runtime/40x12/permission-rules.png) |
+| `checkpoint-rewind` | `/rewind` — restore the files a turn changed | [runtime 120x40](runtime/120x40/checkpoint-rewind.png) | [runtime 40x12](runtime/40x12/checkpoint-rewind.png) |
+| `json-schema` | `--json-schema` and `cortex schema print` | [runtime 120x40](runtime/120x40/json-schema.png) | — |
+| `cloud-teleport` | `&` teleport to Cortex Cloud with `/teleport back` | [runtime 120x40](runtime/120x40/cloud-teleport.png) | — |
+| `review-only` | `cortex exec --review-only` — reads the diff, never writes | [runtime 120x40](runtime/120x40/review-only.png) | — |
+| `plugin-marketplace` | `/plugins` — installed plugins and the signed registry | [runtime 120x40](runtime/120x40/plugin-marketplace.png) | — |
+| `sandbox-allowlist` | `/sandbox network` — the domain allowlist, fail-closed | [runtime 120x40](runtime/120x40/sandbox-allowlist.png) | [runtime 40x12](runtime/40x12/sandbox-allowlist.png) |
+| `auto-approval` | Auto-approval classifier — safe reads pass, the rest asks | [runtime 120x40](runtime/120x40/auto-approval.png) | — |
+| `pr-apply-back` | `cortex pr <n> --apply` — patch into the working tree | [runtime 120x40](runtime/120x40/pr-apply-back.png) | [runtime 40x12](runtime/40x12/pr-apply-back.png) |
+| `acp-editor` | `/ide` — ACP over stdio, approvals unchanged | [runtime 120x40](runtime/120x40/acp-editor.png) | [runtime 40x12](runtime/40x12/acp-editor.png) |
+| `browser-use` | `/browser` — browser automation comes from an MCP server, not the CLI | [runtime 120x40](runtime/120x40/browser-use.png) | [runtime 40x12](runtime/40x12/browser-use.png) |
+| `stdin-multiturn` | `--input-format stream-jsonl` — one line per turn | [runtime 120x40](runtime/120x40/stdin-multiturn.png) | [runtime 40x12](runtime/40x12/stdin-multiturn.png) |
+
+The COR-35 batch is runtime-only: the Designer pack from other PRs is not
+rewritten. Every board above is produced by a real builder or a real command
+surface — `/permissions rules` and `/sandbox network` render the committed
+`.cortex/permissions.toml` and `.cortex/sandbox.toml`, and `/plugins` renders
+the live plugin state file.
+
+Runtime MockTerminal pack (same ids): [`runtime/120x40`](runtime/120x40/) (110) · [`runtime/40x12`](runtime/40x12/) (58).

docs/media/tui-lock-v2/runtime/README.md

@@ -8,11 +8,15 @@ is banner green `#1F4945`; historical violet `#A78BFA` is not the lock.
 Designer boards (pixel target) live in `docs/media/tui-lock-v2/{40x12,120x40}/`.
 These runtime frames are what Designer cli signs off against.
 
-SPEC §7: **96** boards at 120×40 and **50** at 40×12. Each filename is one
-distinct live state — no two PNGs share a sha256. Includes `/goal` composer
-chips (`goal-chip-*`), distinct `offline` and `rate-limit` diagnostics,
-Computer lock boards (`computer-disconnected`, `computer-cloud-default`),
-local-tools consent, composer `@file` chip, `/undo` `/redo` `/rewind` sheet,
-runtime-only COR-18/225/227/228 scenes (`theme-picker`, `handoff-confirm`,
-`session-fork`, `init-agents`, `custom-commands`, `hooks-lifecycle`),
-and the `session-shared` status-line marker while a read-only `/share` link is live.
+SPEC §7 plus the COR-35 batch: **110** boards at 120×40 and **58** at 40×12. Each
+filename is one distinct live state — no two PNGs share a sha256. Includes
+`/goal` composer chips (`goal-chip-*`), distinct `offline` and `rate-limit`
+diagnostics, Computer lock boards (`computer-disconnected`,
+`computer-cloud-default`), local-tools consent, composer `@file` chip, `/undo`
+`/redo` `/rewind` sheet, runtime-only COR-18/225/227/228 scenes
+(`theme-picker`, `handoff-confirm`, `session-fork`, `init-agents`,
+`custom-commands`, `hooks-lifecycle`), the `session-shared` status-line marker
+while a read-only `/share` link is live, and the COR-35 batch (`bare-ci`,
+`ci-cookbook`, `permission-rules`, `checkpoint-rewind`, `json-schema`,
+`cloud-teleport`, `review-only`, `plugin-marketplace`, `sandbox-allowlist`,
+`auto-approval`, `pr-apply-back`, `acp-editor`, `stdin-multiturn`).