docs: add changelog and Codex usage guide

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes are documented here. Dates use ISO 8601 format.
+
+## [Unreleased] — 2026-08-13
+
+### Added
+
+- Durable run-event streaming over Server-Sent Events, with reconnect-safe
+  cursors and a live TUI dashboard for graph state, attempts, evidence,
+  transcripts, budgets, permissions, and operator actions.
+- Standalone Claude Code adapter with streamed transcripts, usage/cost
+  accounting, scoped permission mediation, and abort/retry handling.
+- Permission-aware scheduler state: pending provider permissions pause attempt
+  budgets, move nodes to `blocked`, expose the requested tool/input to
+  operators, and resume only after an explicit decision.
+- Worktree inspection and cleanup improvements, including preservation of dirty
+  worktrees and safe pruning of merged or stale clean worktrees.
+- Workflow diagrams and a visual trust-loop/brand system in `docs/` and the
+  repository root.
+
+### Changed
+
+- Agent authorization is now fail-closed. Managed OpenCode roles refresh on
+  `corral init`, worktree sessions receive the managed policy, and provider
+  prompts select the role-specific agent.
+- Gate pre-authorization is operator-only; model agents cannot grant that
+  authority to themselves.
+- Graph validation accepts only supported agent roles and safe relative write
+  scopes. Scheduler verification rejects changes outside the declared scope.
+- Planner and reviewer tool permissions default to deny, while workers require
+  approval for edits and shell commands.
+- API-key material is kept in `.corral/api.key` instead of being duplicated in
+  project-readable config metadata.
+
+### Fixed
+
+- TUI event ordering, reconnect, terminal-run, and attention behavior.
+- Attempt identity collisions across runs and event-subscriber loss after
+  overload.
+- Retry feedback, reviewer read-only boundaries, and provider stream/usage
+  preservation.
+
+## [0.2.0]
+
+See the [v0.2.0 release](https://github.com/thiago-ss/corral/releases/tag/v0.2.0)
+for the previous baseline.

README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://img.shields.io/github/actions/workflow/status/thiago-ss/corral/ci.yml?branch=main&style=flat-square&label=CI&labelColor=191A16&color=1F7A50)](https://github.com/thiago-ss/corral/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/thiago-ss/corral?style=flat-square&labelColor=191A16&color=D8890B)](https://github.com/thiago-ss/corral/releases) [![Go](https://img.shields.io/badge/Go-1.26.5-2B63D9?style=flat-square&labelColor=191A16)](https://go.dev) [![License](https://img.shields.io/badge/license-MIT-1F7A50?style=flat-square&labelColor=191A16)](LICENSE)
 
-[Why Corral](#why-corral) · [Default run](#the-default-run) · [Install](#quick-start) · [Architecture](#how-trust-is-built)
+[Why Corral](#why-corral) · [Default run](#the-default-run) · [Install](#quick-start) · [Codex](docs/codex.md) · [Changelog](CHANGELOG.md) · [Architecture](#how-trust-is-built)
 
 **[Install and run →](#quick-start)**
 
@@ -91,6 +91,12 @@ Inside OpenCode:
    set `autoApproveGates` when creating a run; model agents cannot grant that
    authority to themselves.
 
+From Codex, use the terminal as the operator: run `corral up`, review a graph
+through `/api/plan`, start it through `/api/runs`, and monitor it with
+`corral tui` or `corral status`. The complete copy/paste flow, gate commands,
+and operator prompt pattern live in [`docs/codex.md`](docs/codex.md). Codex is
+not yet a native Corral executor; OpenCode runs the isolated worker sessions.
+
 Or follow the same run from the terminal:
 
 ```sh

docs/codex.md

@@ -0,0 +1,113 @@
+# Using Corral from Codex
+
+Corral's production executor is OpenCode. Codex does not currently act as a
+native Corral worker or planner, but Codex can operate Corral through its
+terminal: start the local daemon, submit/review graphs, follow runs, and make
+operator decisions. Agent execution still happens in isolated OpenCode
+worktrees.
+
+## One-time setup
+
+From the repository you want Corral to manage, run this in a Codex terminal:
+
+```sh
+corral up
+corral doctor
+```
+
+`corral up` is idempotent. It creates `.corral/`, keeps the API key in
+`.corral/api.key`, installs the OpenCode plugin/config, starts the daemon, and
+checks health. Restart OpenCode after the first setup if you also use its
+native Corral tools.
+
+If `corral` is not installed yet, install it first using the project
+installation instructions in the README, or build the current checkout:
+
+```sh
+go build -o corral ./cmd/corral
+./corral up
+```
+
+## Recommended Codex workflow
+
+1. Ask Codex to inspect the repository and write a short goal and acceptance
+   criteria.
+2. Ask Codex to submit the goal to Corral's planner API. Do not start the run
+   until you have inspected the returned graph.
+3. Start the approved graph. Record the returned run ID.
+4. Follow progress with `corral tui` or `corral status`.
+5. Stop at human gates and inspect the evidence. Approve, reject, retry, steer,
+   or cancel only as the operator.
+6. Export the audit record when the run completes.
+
+The following commands are a copy/paste API flow. They use the local operator
+key generated by `corral init`:
+
+```sh
+base="${CORRAL_DAEMON_URL:-http://127.0.0.1:4519}"
+key="$(tr -d '\n' < .corral/api.key)"
+
+# Ask the read-only planner for a graph.
+curl -fsS "$base/api/plan" \
+  -H "Authorization: Bearer $key" \
+  -H 'X-Corral-Role: operator' \
+  -H 'Content-Type: application/json' \
+  -d '{"goal":"Add CSV export for monthly expenses, with tests and documentation."}' \
+  > /tmp/corral-plan.json
+
+# Review graph before starting any work.
+jq . /tmp/corral-plan.json
+
+# Start only after the graph is approved.
+run_id="$(curl -fsS "$base/api/runs" \
+  -H "Authorization: Bearer $key" \
+  -H 'X-Corral-Role: operator' \
+  -H 'Content-Type: application/json' \
+  --data-binary @/tmp/corral-plan.json | jq -r .runID)"
+echo "run: $run_id"
+
+# Inspect/follow the run.
+corral status
+corral tui
+
+# Export the durable audit record after completion.
+corral export "$run_id" --out ".corral/$run_id.json"
+```
+
+For a gate decision, first inspect the run in the TUI or with `GET
+/api/runs/<runID>`, then call the operator endpoint. Replace `gate` with the
+actual node ID:
+
+```sh
+curl -fsS -X POST "$base/api/runs/$run_id/approve" \
+  -H "Authorization: Bearer $key" \
+  -H 'X-Corral-Role: operator' \
+  -H 'Content-Type: application/json' \
+  -d '{"nodeID":"gate"}'
+```
+
+Use `/reject`, `/retry`, `/steer`, `/cancel`, or `/permission` in the same way
+when the evidence calls for another operator action. Never approve a gate
+merely because an agent says it is safe; inspect the graph, diff, verification
+result, and permission details first.
+
+## Prompt pattern for Codex
+
+This keeps Codex in an operator role while Corral owns execution:
+
+> Use Corral for this goal: `<goal>`. Inspect the repository first. Submit a
+> plan, show me the graph and acceptance criteria, and wait for my approval.
+> After I approve, start the run, report the run ID, monitor it, and stop at
+> every human gate or permission request. Do not approve gates or permissions
+> without my explicit instruction. At completion, summarize verification,
+> changed files, and the audit export path.
+
+## Boundaries
+
+- Codex terminal commands use the operator API role; protect `.corral/api.key`.
+- The daemon enforces role checks server-side; model agents cannot mint
+  operator gate authority.
+- Work is performed by OpenCode sessions in isolated worktrees, then verified
+  before merge.
+- There is no native Codex driver yet. Native Codex execution is a roadmap
+  item, not a capability this workflow silently substitutes.