platform/docs/opencode-api-2-assessment.md

# OpenCode's newer API — what it is, what it would cost, what it buys

Written 2026-08-11 against **opencode 1.18.16**, from three sources: the running server's own OpenAPI
document (`GET /doc` on `opencode serve`), live probes against a real serve, and upstream docs/npm.
Every claim below is marked by where it came from. Measurements were taken on the local serve
(port 49698, the `officer-opencode` sidecar's own) and cleaned up afterwards — the session store is
back to the 50 rows it started with.

Read this before starting any opencode work. Two live defects fell out of writing it (§1), and the
naming is actively misleading (§2).

---

## 1. Two live defects, found while measuring

Neither is a migration concern. Both are broken right now, in production, and both are consequences of
being half-migrated.

### 1a. Every OpenCode conversation created since 2026-08-10 opens EMPTY

Since Phase D, turns run through `POST /api/session/{id}/prompt`, so the session belongs to the newer
engine. But `loadOpenCodeSession` reads the transcript through the legacy route
(`client.ts:51` → `GET /session/{id}/message`).

**The two surfaces are mutually blind.** Measured, both directions, on a session created via `/api` and
run to completion with a real model reply:

| read | api-created session | legacy-created session |
|---|---|---|
| `GET /session/{id}/message` (what we call) | **`[]` — 0 messages** | 200, full transcript |
| `GET /api/session/{id}/message` | 200, 3 messages | **500** |
| `GET /session/{id}` (the record) | 200, title + directory | 200 |

So the row appears in the list with its title and directory, and opens with nothing in it. And the
inverse is equally true: switching the reader to `/api` without keeping the old one would empty every
conversation from before 2026-08-10.

The fix is not "swap the endpoint" — it is "route by which engine owns the session", and there is no
field that says so. The one usable discriminator found tonight is that the legacy read returns `[]`
rather than erroring.

### 1b. The session list silently truncates at 50

`GET /api/session` defaults to **50 rows** and returns a `cursor.next`. Measured: with 50 sessions in
the store the list returns 50 *and still offers a next cursor*; adding a 51st and asking `?limit=200`
returns 51 (and `limit` is capped at 100 — 200 is accepted for the list but `/history` rejects >100
with `Expected a value less than or equal to 100`).

`client.ts:36` sends neither `limit` nor `cursor`, so **once the store passes 50 sessions the oldest
stop appearing in `/chat`**. The local store is at exactly 50 today. This is in code shipped this
morning (`adaaba6`).

The same endpoint takes `directory=` — verified filtering correctly (`?directory=/tmp/oc-cap` → 11
rows, all in that directory). We fetch everything and filter client-side in `opencode-sessions.ts:49`.
Pushing the filter down fixes the normal case and brings `search=`, `order=`, `project=` with it.

---

## 2. The naming, because "API 2.0" means two different things

There is no version string "2.0" in the running server. `GET /doc` self-reports
`{"openapi":"3.1.0","info":{"title":"opencode","version":"1.0.0"}}`. What actually exists:

| | **legacy** | **the `/api/*` surface** | **OpenCode 2.0 beta** |
|---|---|---|---|
| where | in 1.18.16 | in 1.18.16 | separate product, binary `opencode2`, npm `@next` |
| routes | 111 paths | 51 paths | ~100 paths, still moving |
| operationIds | `session.list` | **`v2.session.list`** | — |
| we use it | reads: transcript, delete, rename | writes: every turn since 2026-08-10 | not at all |
| docs | opencode.ai/docs/server (stale — never mentions `/api/*`) | undocumented publicly | opencode.ai/v2/docs |

So "API 2.0" most likely means **the `/api/*` surface — which we already run on for turns**. Its
operation ids are literally `v2.*`. It is not something to adopt; it is something to *finish*.

Two qualifications, both from the source at tag `v1.18.16`:

- **Upstream calls it experimental.** `packages/protocol/src/api.ts` titles it `"opencode HttpApi"`,
  version `"0.0.1"`, described as *"Experimental HttpApi surface for selected instance routes"*, with
  every group annotated the same way. Meanwhile `/session/*` is the surface the public docs actually
  document, and it is not deprecated. The internal direction is unambiguous; the external commitment is
  nil.
- **`session.next` is the event family of that rewritten engine, and the name is already dead
  upstream.** It arrived in **1.15.0** (PR #27415, "Add Effect-native core event system", merged
  2026-05-15) as an interim prefix. On the `v2` branch all 36 session events have dropped `.next.` —
  `session.step.started`, `session.text.delta` — along with renames: `agent.switched` →
  `agent.selected`, `model.switched` → `model.selected`, `prompted` → `prompt.promoted`. Those renames
  are **v2-branch only**; the 1.x line we run still emits `session.next.*`. Code against
  `session.next.*` today, but put the names behind one mapping table, because they are scheduled to
  change wholesale.

Same for the `v2` suffix itself. `packages/schema/AGENTS.md`: *"V1 coexistence is temporary… delete the
V1 subtree when the legacy runtime is retired"* and *"Do not preserve `V2` as the permanent name for the
replacement architecture."* Both halves of today's naming are transitional.

**OpenCode 2.0 the product is a different question**, and the answer tonight is not yet: the beta docs
carry the banner *"we may wipe your data, things may break, and APIs, configuration, and plugin APIs
may change"*, releases ship ~6/day, and the migration guide states three intentional breaking changes
(plugin API, server API contracts, TUI config), with *"Integrations that call the V1 server API must
migrate to the V2 API"*. No deprecation date for the legacy surface is published anywhere.

Two facts worth knowing regardless:

- **The repo moved.** `github.com/sst/opencode` 301s to **`github.com/anomalyco/opencode`**. Every npm
  package now points there. No announcement was found explaining it.
- **There is already a typed client for the surface we run.** `@opencode-ai/sdk@1.18.16` ships two
  generated clients: the default export covers legacy only, and **`@opencode-ai/sdk/v2` covers all 51
  `/api/*` routes**. We have no opencode dependency at all today — every call is hand-rolled `fetch`.

---

## 3. What we call today

Two of our processes talk to one serve, with no shared client.

**Sidecar (`src/servers/sidecar/opencode/`) — already on `/api/*`:** `POST /api/session`
(`serve-runner.ts:222`), `POST …/model` (`:236`), `POST …/prompt` (`:266`, `:199`), `POST …/interrupt`
(`:328`), `GET /api/event` (`:86`), `GET /api/health` (`index.ts:79`),
`POST /api/integration/{provider}/connect/key` (`connect-credential.ts:66`).

**API server (`src/servers/api/chat/opencode/client.ts`) — still legacy:** `GET /session/{id}` (`:45`),
`GET /session/{id}/message` (`:51`), `DELETE /session/{id}` (`:57`), `PATCH /session/{id}` (`:62`),
plus `GET /config/providers` for the model list (`list-models.ts:58`). The one exception is
`GET /api/session` for the list (`:36`), moved this morning.

51 routes exist. We call 7.

---

## 4. What the newer surface has that we don't use

### 4a. Adding context to a turn that is already running

The capability the subprocess path could never have, and the reason the migration happened.

```
POST /api/session/{id}/prompt
{ "id": "msg_…", "prompt": { "text", "files": [{uri,name,description,source}],
                             "agents": [{name,source}] },
  "delivery": "steer" | "queue", "resume": true|false }
```

Spec description: *"Durably admit one session input and schedule agent-loop execution unless resume is
false."*

- **`delivery: "steer"` injects into the RUNNING turn** — the model takes the new text as part of the
  work in flight. No kill, no restart, no lost context. We already send it (`serve-runner.ts:199`) but
  only on the accidental path: a message that happens to arrive mid-turn. Nothing in the UI *asks* for
  it, and nothing distinguishes "add this to what you're doing" from "here's my next message".
- **`delivery: "queue"`** runs after the current turn. It must be stated explicitly — **the field
  defaults to `steer`** — or two quick messages merge into one turn (`serve-runner.ts:268`).
- **`prompt.files[]`** attaches content to that same input; measured last night, it must be a `data:`
  URI (a `file://` one is accepted with 200 and dies inside the provider). Each attachment also takes
  a `description`, which we don't send.
- **`prompt.agents[]`** attaches an agent to the input. Unused, unexplored.
- **`id`** lets the caller mint the `msg_…` id, which is how a send survives a retry without
  double-posting. We let the server mint it and therefore can't.

Measured: the POST returns in **22 ms** with `{"admittedSeq":1,"id":"msg_…","delivery":"queue"}`. It is
an admission receipt, not a turn — and `admittedSeq` is the durable cursor for everything that follows.

### 4b. Surviving a restart mid-turn — verified working

```
GET /api/session/{id}/event?after=<seq>    "Replay durable events after an aggregate sequence,
                                            then continue with new durable events."
GET /api/session/{id}/history?limit=&after=  "Read one finite page of public durable Session events
                                            after an exclusive aggregate sequence."
```

Driven end to end tonight on a real turn (free model, "Reply with exactly: hi"):

```
seq 1 session.next.prompt.admitted     seq 6  session.next.context.updated
seq 2 session.next.prompted            seq 7  session.next.step.started
seq 3 session.next.model.switched      seq 8  session.next.text.started
seq 4 session.next.prompt.admitted     seq 9  session.next.text.ended
seq 5 session.next.prompted            seq 10 session.next.step.ended
```

`?after=5` returned exactly 6–10. `GET …/event?after=7` replayed 8, 9, 10 and then held the socket open
for more. Every durable event carries `{aggregateID, seq: integer, version}`, so `after=` is that
integer. This is the documented, working answer to the gap Phase B left open and
`docs/opencode-testing-checklist.md` calls the most likely thing to be broken.

The upstream implementation (`packages/core/src/event.ts`, `durable()`) makes three things explicit
that matter for building on it:

- `after` is an **exclusive** lower bound on the durable seq, and the aggregate is the session.
  Omitting it replays the session from 0.
- **Replay-then-live is gap-free by construction**: it reads `WHERE seq > after ORDER BY seq ASC`,
  advances its cursor to the last row, and on every wake re-reads *the database* rather than draining a
  pubsub buffer. Sequences are strictly monotonic and contiguous per session, enforced with explicit
  `Sequence mismatch` / `Replay diverged` errors.
- **The first cursor is free.** `POST …/prompt` returns `{admittedSeq, id, sessionID, prompt, delivery,
  timeCreated, promotedSeq?}` — measured at 22 ms — and `admittedSeq` feeds straight back as `after`.

Note the two cursor kinds are unrelated: the session *list* uses an opaque base64url cursor
(`cursor.previous` / `cursor.next`), this one is a plain integer.

**But the two streams are not interchangeable, and the schema says why.** `SessionDurableEvent` is a
`oneOf` of exactly 28 members, and the five it omits are `text.delta`, `tool.input.delta`,
`reasoning.delta`, `compaction.delta` and the retry error. **Deltas are live-only by design; the
durable log stores whole values.** So a client that wants both token streaming and restart recovery
must read both streams: the global live one for deltas, the per-session durable one for the replayable
spine. Last night's 13-vs-21 event count was this same fact, found by counting instead of by reading.

### 4c. Knowing what is running, without having started it

```
GET /api/session/active   "Retrieve foreground Session drains currently owned by this OpenCode
                           process. Sessions absent from the result are inactive."
POST /api/session/{id}/wait  "Wait for a session agent loop to become idle."
```

Today "what is running" is an in-memory map in our sidecar (`serve-runner.ts:66`). Restart the sidecar
and the truth is gone — which is why `/chat/live` can be wrong after a restart. `session/active` is the
server's own answer and survives us.

### 4d. Permissions and questions — nothing in officer models this

```
GET|POST /api/session/{id}/permission            POST …/permission/{requestID}/reply
GET  /api/permission/saved                       DELETE /api/permission/saved/{id}
GET  /api/session/{id}/question                  POST …/question/{requestID}/reply | /reject
```

Plus `permission.v2.asked` / `question.v2.asked` events (the v1 families still exist alongside; the
only `deprecated: true` operation in the entire document is `POST /session/{id}/permissions/{id}`).

The two "v2"s are not the same kind of change, which matters if we implement one of them:

- **Permissions v2 is a real contract change.** A rule goes from `{permission, pattern, action}` to
  `{action, resource, effect}`; a request from `{permission, patterns[], metadata, always[], tool?}` to
  `{action, resources[], save?[], metadata?, source?}`, with the tool linkage becoming a tagged union
  `source: {type:"tool", messageID, callID}`; and the reply loses its free-text `message`. The public
  V2 docs say the same in config terms: *"Do not use `permission`, `bash`, or `task` in V2
  configuration."*
- **Questions v2 is a re-homing.** Field shapes are byte-identical to v1 — `questions[]` of
  `{question, header, options[], multiple?, custom?}`, answers as `string[][]`. Only the namespace and
  event names changed.

Which family a 1.18.16 agent actually emits is worth measuring before building UI: the manifest the
`/api` protocol is *built* from excludes the v1 families, but the server wires the **full** manifest
(`makeApi({definitions: EventManifest.Latest.values()})`), which is why both appear in the `/api/event`
union on our own `/doc`.

An opencode agent that wants consent, or that asks a question mid-turn, gets no answer from officer. We
don't subscribe to those events and have no route to reply on. Claude's harness runs
`--dangerously-skip-permissions`, so this has never been modelled for either harness. Largest single
behavioural gap.

### 4e. Undo, compaction, context

```
POST /api/session/{id}/revert/stage {messageID, files?}   …/revert/commit   …/revert/clear
POST /api/session/{id}/compact      GET /api/session/{id}/context
```

Stage a revert to a message, then commit or discard. Explicit compaction with
`compaction.started/delta/ended` events, and a readable context state. Officer has none of this.

### 4f. The rest

`GET /api/agent`, `/api/skill`, `/api/command`, `/api/model`, `/api/provider`, `/api/fs/{list,find,read}`,
`GET|POST /api/pty` (+`connect`, `connect-token`), `POST /api/session/{id}/agent` (switch agent
mid-session), `/api/reference`, `/api/location`, `/api/integration`, `/api/credential/{id}`.

`GET /api/model` and `/api/provider` are the `/api` equivalents of the `/config/providers` call our
model list is built on (87 models locally). `/api/pty` overlaps our own pty sidecar.

---

## 5. What the event stream carries that we drop

Our mapper recognises 18 names and maps 7. The server emits **130 event type strings**, 32 in the
`session.next.*` family plus eight plain `session.*` (`idle`, `status`, `error`, `compacted`,
`created`, `deleted`, `updated`, `diff`).

| dropped | what it would give |
|---|---|
| `reasoning.started/delta/ended` | thinking, streamed — we show none for opencode |
| `tool.input.delta` / `.started` / `.ended` | a tool call rendering as its arguments arrive |
| `tool.progress` | long tools reporting instead of appearing hung |
| `shell.started/ended` | shell commands as a first-class thing |
| `compaction.*` | telling the user the context was compacted |
| `revert.*` | §4e |
| `retried` | a retry that currently looks like a stall |
| `prompt.admitted` / `prompted` | acknowledgement — the exact window where silence has twice cost an afternoon |
| `session.idle` | the real turn-end signal (see below) |

We end a turn on `step.ended` with `finish !== 'tool-calls'` (`serve-runner.ts:139`), because there is
no turn-ended event in what we read. `session.idle` looks like what that rule approximates, and it is
not in our `KNOWN` set.

---

## 6. Two silent-failure modes, both reproduced tonight

Both produce the identical signature — `prompt.admitted`, `prompted`, then **nothing, forever**:

1. **No credential connected** for the `/api` surface. Already known and fixed at boot
   (`connect-credential.ts`), but the failure has no error.
2. **No model on the session and no server default.** New tonight: my first probe sat at
   `admitted → prompted` and stopped. `GET /config` reports `model: None`, and the session had no model
   because I hadn't set one. `POST …/model` then re-prompting produced the full 10-event turn above.

Our runner only sends `POST …/model` when `params.model` is set (`serve-runner.ts:231`). **A turn sent
with no model, against a serve with no configured default, hangs silently.** Worth an explicit check.

---

## 7. What finishing the migration would cost

- **Both readers stay.** §1a: `/api` reads 500 on legacy-owned sessions, legacy reads `[]` on
  api-owned ones. Routing by ownership is required, and no field declares ownership.
- **Delete and rename cannot move.** `/api/session/{sessionID}` is **GET only**; `DELETE` and `PATCH`
  exist only on the legacy route (spec-verified, and a live `DELETE` returned 200).
- **The transcript shape differs.** Legacy items are `{info:{role,…}, parts:[…]}` — what
  `opencode-sessions.ts:81` parses. `/api` items are
  `{id, time, type:'assistant', agent, model:{id,providerID,variant}, content:[{type:'text',id,text}],
  finish, cost, tokens}`. A second mapper, or a shared normaliser.
- **The SSE parser needs to grow up.** `serve-runner.ts:89` is `data:`-only: no `event:`, no `id:`, no
  comments, no `retry:`, no multi-line frames, fixed 1 s reconnect with no backoff. A cursored stream
  must resume at `?after=<last seq>`, not restart.
- **Two envelope unwrappers and three hand-written type sets** (`serve-runner.ts:161`, `client.ts:38`;
  types pinned by comment to two different opencode versions, 1.17.9 and 1.18.16). This is the part a
  dependency would delete outright — see below.
- **Stale comments in at least nine files** still describe the deleted `opencode run` subprocess path
  (`protocol.ts:198`, `serve-events.ts:5`, `connect-credential.ts:24`, `index.ts:137`,
  `websocket.ts:454`, `chat.ts:127`, `list-models.ts:75`, `sidecar-server.ts:8`, `send-opencode.ts:7`).
  Two of them actively lie: they say turns read `auth.json` and don't depend on the credential connect.
  They now do.

Unrelated but found while inventorying: the settings UI writes provider keys to `~/.pi/agent/auth.json`
(`chat-providers.ts:10`) while the credential connect reads `~/.local/share/opencode/auth.json`
(`connect-credential.ts:29`). Two different files.

---

## 7b. The SDK is generated from the document we have been reading by hand

`@opencode-ai/sdk@1.18.16` (published 2026-08-10, versioned in lockstep with the CLI) is built by
`packages/sdk/js/script/build.ts`, which runs opencode's own `generate` to produce the OpenAPI document
and feeds it to `@hey-api/openapi-ts`. **It is generated from the same `/doc` we probed**, which is
about as good a guarantee of shape-agreement as exists.

It ships two clients. The default export is the legacy surface. `@opencode-ai/sdk/v2` is ours:

```ts
import { createOpencodeClient } from '@opencode-ai/sdk/v2';

const client = createOpencodeClient({ baseUrl });
const admitted = await client.v2.session.prompt({ sessionID, prompt: { text }, delivery: 'steer' });
const events = await client.v2.session.events({ sessionID, after: admitted.data.admittedSeq });
for await (const ev of events.stream) { /* ev.type, ev.durable.seq */ }
```

`client.v2.session.*` covers list/create/active/get/switchAgent/switchModel/prompt/compact/wait/
context/history/events/interrupt/message(s); there is also `client.v2.event.subscribe`,
`client.v2.permission.*`, `client.v2.question.*`, `fs`, `model`, `provider`, `agent`, `skill`, `pty`.
`createOpencodeClient` takes `directory` and injects it as both the `x-opencode-*` headers and the
`location[directory]` query param — the thing we hand-roll in two places.

That would delete: our hand-rolled SSE reader, both envelope unwrappers, three hand-written type sets,
and the model-id string splitting. It is a dependency change, and installs here are frozen, so it is a
deliberate `bun install --no-frozen-lockfile` plus a read of the lockfile diff. Worth noting the
package's only dependency is `cross-spawn`.

Not to be confused with two siblings the v2 docs mention: `@opencode-ai/sdk-next` is marked private and
is not on npm, and `@opencode-ai/client` is a private generation target for the beta line.

---

## 8. What we'd gain immediately

Ordered by value over effort. 1–3 are bug fixes, not features.

1. **Transcripts that aren't empty** — route the read by session ownership. This is broken in
   production now. (§1a)
2. **A list that doesn't stop at 50**, filtered server-side by `?directory=`. One call site. (§1b)
3. **A turn that can't hang silently** — set a model explicitly, or check `/config` for a default, and
   say so out loud when neither exists. (§6)
4. **"Add to what you're doing" as a real control** — `delivery: "steer"` on a deliberate trigger
   rather than only when a message happens to land mid-turn. The plumbing already exists. (§4a)
5. **Idempotent sends** — mint our own `msg_…`. One field. (§4a)
6. **Restart recovery** — subscribe `?after=<seq>` alongside the live stream. Verified working. (§4b)
7. **A truthful live panel** — `GET /api/session/active`. (§4c)
8. **Richer streaming for free** — reasoning deltas, tool-input deltas, tool progress, retries. Already
   arriving on the socket we already read, and dropped in a `default:` case. (§5)
9. **Explicit compaction and context** instead of a long conversation quietly getting more expensive.

Then the two that are real features needing UI: **permissions/questions** (§4d) and **revert** (§4e).

---

## 9. What this does NOT get us

- It does not retire the legacy surface: delete, rename and every pre-2026-08-10 transcript stay there,
  with no deprecation date published.
- It does not touch the Claude harness — a different sidecar, a different protocol. Every gain above
  lands on one harness only, while the chat UI assumes the two behave alike.
- It does not put us on OpenCode 2.0. Note the direction of travel there: the beta **removes**
  `/api/session/{id}/history` and `/api/session/{id}/event` — the two durable routes item 6 depends on
  — replacing them with `GET /api/experimental/session/{id}/log?after=&follow=`. Same idea, new path,
  `experimental/` prefix. So item 6 is worth doing *and* worth writing behind one function.

---

## 10. Open questions

1. Is there a field that says which engine owns a session? Tonight's only discriminator is behavioural
   (legacy returns `[]`). If not, we need our own record — we already store `sessionKey → ses_…` in
   `opencode/state.ts` and could record the surface with it.
2. Which permission/question family does a 1.18.16 agent actually emit? Both are declared and both
   appear in our `/doc`, because the server wires the full manifest. Measure before building UI.
3. What is `/api/*`'s auth story? The spec declares no `securitySchemes` yet every route declares a
   `401`. The v1 docs describe HTTP Basic via `OPENCODE_SERVER_PASSWORD`; we run with none, on
   loopback. In the 2.0 beta this is formalised as basic auth read from
   `~/.local/state/opencode/service.json`.
4. Does `@opencode-ai/sdk/v2` work against 1.18.16 exactly? It is generated from this exact server's
   OpenAPI output and versioned in lockstep, so it should — but nobody here has run it.
5. When did `/api/*` first appear in the 1.x line? UNKNOWN; the changelog names no `/api/` additions.
   The event family underneath it landed in 1.15.0. And no dated removal plan exists for `/session/*`,
   `permission.asked/replied` or `question.*` — only the undated internal intent quoted in §2.
6. Will the `v2`-branch event renames reach the 1.x line, or only ship with OpenCode 2.0? No merge
   found, no statement either way. This decides whether the mapping table in §2 is a one-off or a
   permanent seam.
7. Is a durable `seq` stable across a server restart or a session move? It is a database column, so it
   should be, but no durability guarantee is documented and we have not tested it. Item 6 in §8 depends
   on the answer.

Version state at the time of writing: **1.18.16 is the newest release** (2026-08-10) and contains
nothing API-facing. The active stream is the 2.0 beta, cutting releases continuously — the most recent
was published hours before this file was written.

---

## 11. Sources

- Live: `GET /doc` on `opencode serve` 1.18.16 (162 paths, 51 under `/api/`), plus the probes recorded
  above against the local sidecar's serve on port 49698.
- Code: `src/servers/sidecar/opencode/*`, `src/servers/api/chat/opencode/*`, `opencode-sessions.ts`,
  `list-models.ts`, `send-opencode.ts`.
- Upstream, docs: opencode.ai/v2/docs/migrate-v1, opencode.ai/v2/docs, opencode.ai/v2/docs/permissions,
  opencode.ai/docs/server, opencode.ai/changelog.
- Upstream, source at tag `v1.18.16` in **github.com/anomalyco/opencode** (formerly `sst/opencode`,
  which 301s): `packages/protocol/src/api.ts` and `groups/session.ts` (the surface's own "experimental"
  self-description, the `after` parameter), `packages/schema/src/session-event.ts` (`DurableDefinitions`
  vs `Definitions` — the delta exclusion), `packages/schema/src/{permission,question}.ts` and their
  `v1/` counterparts, `packages/schema/src/session-input.ts` (`admittedSeq`), `packages/schema/AGENTS.md`
  (the V1/V2 naming intent), `packages/core/src/event.ts` (replay-then-live), `packages/sdk/js/script/
  build.ts` and `src/v2/client.ts`. PRs #27415 (the engine landing in 1.15.0), #33993, #35217, #35229
  (the renames).
- npm: `@opencode-ai/sdk` 1.18.16, `@opencode-ai/client@next`.
- Prior art in this repo: `docs/opencode-parity.md`, `-fork-decision.md`, `-serve-migration-plan.md`,
  `-serve-path.md`, `-testing-checklist.md`, `-phase0-review.md`, `-phase1-report.md`,
  `-phase1-review.md`.