# Docs that keep up with the API

Example workflow · November 2, 2026

Docs written after the code ships have to reverse-engineer decisions the code already made. Docs written alongside it need to hear about every change.

## At a glance

- **Setup:** Claude Code builds an export API in the API repo. Codex writes the guide in a separate docs repo, at the same time.
- **Rhizome:** `list_sessions` to find the exact session, `subscribe` to follow its progress, `send` for one question the guide can’t answer.
- **Code path:** Two repos, two PRs, plain git. Rhizome never moves files.
- **Result:** One docs PR, revised through two contract changes (`202` with a status URL, `410` on expiry), ready for review with the API PR.

## The situation

Take an example API for asynchronous exports (not a Rhizome endpoint). A client creates an export, polls the job, and downloads the result when it’s ready.

Claude Code is implementing it in the API repository. The user asks Codex, working in the documentation repository, to write the guide while the implementation is still in progress. Both sessions already run on their own; neither launched the other.

## The challenge

The guide has to describe a contract that isn’t finished yet:

- **The contract moves.** The first description is “returns a job ID, then poll”. Later, creation returns `202 Accepted` with a `statusUrl`, and `downloadUrl` only appears once the job is ready.
- **Edge cases aren’t decided yet.** What a client should do when an export expires isn’t in the code when the guide is drafted.
- **Two repos, two agents.** Codex can read the API branch if it has access. It can’t see what the implementing session is deciding, or when.
- **Release timing.** The API and its docs should be reviewed and published together, not weeks apart.

## Without Rhizome

The usual options all leave someone carrying the contract between two sessions by hand:

- **Write the docs after merge.** Someone reconstructs why creation returns `202` and when `downloadUrl` appears. Late changes get lost between code review and the guide.
- **Write them early, once.** The guide documents “returns a job ID” and is wrong by the time the API is reviewed. Nothing tells the docs session the contract changed.
- **Relay by hand.** The user copies each change from Claude Code into Codex, and asks about expiry over Slack. Every relay is a chance to drop a detail.
- **Guess the edge case.** The docs agent fills the gap with plausible behavior, like “retry the download”, that the API doesn’t support.

## How Rhizome helped

1. **Find and follow the exact session.** Codex calls `list_sessions` and checks agent type, project and session name against the export work. Once it’s sure, it calls `subscribe` with that session’s exact ID. A repository name alone isn’t enough.
2. **Draft from the first contract.** An update arrives: “The export endpoint will return a job ID. Clients will poll the job endpoint until the download is ready.” Codex outlines create → poll → download, opens a draft docs PR, and marks status codes, fields and errors as open instead of inventing them.
3. **Catch the late change.** Another update: “Creation now returns 202 Accepted with a status URL. The download URL only appears once the job is ready.” Codex checks the API branch diff and schema, then revises the guide on the same docs PR.
4. **Ask instead of guessing.** The guide needs expiry behavior, so Codex uses `send` to ask that exact session: “What should clients do when an export expires?” Until a reply arrives, expiry stays an open item.
5. **Turn the answer into guidance.** The reply: “An expired export returns 410. Start a new export; retrying the expired download will not renew it.” Codex checks it against the implementation and adds a recovery section.
6. **Align at ready-for-review.** When the API session reports it’s ready for review, Codex re-checks the guide against the branch and schema, runs the docs build, link and example checks, and lists what it validated and what still needs review on the PR.

![Claude Code edits the API repo and Codex edits the docs repo. Codex follows selected Claude activity through Rhizome and exchanges targeted questions and replies; separate git arrows lead to separate PRs.](https://tryrhizome.dev/diagrams/docs-follow-api-flow.svg)

The subscription carries selected API activity to Codex. Questions and replies are direct messages. Each agent updates its own PR through git.

![API contract changes on the left (v1 job ID, v2 202 with statusUrl, an answer that expired exports return 410, ready for review) reach Codex through subscription updates and direct messages. Each becomes a commit on the same docs PR: draft, revise create and polling, add expiry recovery, validate. A direct question about expiry is marked open until answered. The API PR and docs PR are reviewed together.](https://tryrhizome.dev/diagrams/docs-follow-api-sequence.svg)

Example workflow, not a historical timeline. Every dot is a commit on the same docs PR; the open dot is a question asked instead of a guess.

## The outcome

- **One docs PR, revised in place.** Draft, then the `202` and `statusUrl` change, then `410` recovery. The commits show how the contract evolved.
- **No guessed behavior.** Expiry is documented from the implementer’s answer, checked against the code.
- **Reviewed together.** The API PR and the docs PR stay separate, so reviewers can read the code and its explanation side by side and agree on release timing. Rhizome doesn’t merge either one.

The client flow the guide ends up documenting (`{job_id}` stands for the ID returned by creation):

```text
POST /exports
→ 202 Accepted
{ "jobId": "{job_id}", "statusUrl": "/exports/{job_id}" }

GET /exports/{job_id}
→ 200 OK
{ "status": "pending" }

GET /exports/{job_id}
→ 200 OK
{ "status": "ready", "downloadUrl": "/exports/{job_id}/download" }

GET /exports/{job_id}/download  (after expiration)
→ 410 Gone

Recovery: POST /exports, then poll the new statusUrl.
```

## Rough edges and limits

- **Updates aren’t diffs.** A subscription carries selected assistant activity and activity markers, not transcripts, reasoning or file contents. Codex still has to read the API branch and schema; if it can’t, verification stays open.
- **Following can have gaps.** A new subscription starts from now. Reconnects, bounded queues and restarts can drop events. When updates go quiet, check the subscription state and the branch, and ask rather than fill the gap.
- **Sent isn’t answered.** A successful `send` means the message was queued, not that it was read or answered.
- **Ready isn’t tested.** A “ready for review” update doesn’t mean tests pass or the feature shipped. Validation is a step Codex runs, not something it receives.

## Try it on one feature

1. Pick a feature whose API contract is still changing, with docs in a separate repo or session.
2. Start the docs session and have it find and subscribe to the implementing session by exact ID.
3. Open a draft docs PR early, with unknowns marked as open.
4. Ask the implementing session directly for anything the guide can’t safely infer. Review and release both PRs together.

A prompt to start with, in the docs session:

```text
Write the guide for <feature> in this repo. Find the session implementing it,
confirm it's the right one, and subscribe. Keep unknowns open in a draft PR,
check each contract change against the API branch before editing, and ask
that session directly instead of guessing.
```

## About this account

This is an illustrative workflow, not a recorded session. The export API, the messages and the responses are examples written for this page, so there are no session IDs, timestamps, commit hashes or test results to report. The Rhizome behavior described (exact-ID discovery, subscriptions, direct messages and delivery limits) follows the public reference documentation as of November 2, 2026.

## Further reading

- [Discovery, exact identities and messaging tools](https://github.com/aliengiraffe/rhizome/blob/main/docs/reference.md#tools)
- [Subscription activity, replay and delivery limits](https://github.com/aliengiraffe/rhizome/blob/main/docs/reference.md#activity-replay-and-bounded-delivery)
- [Current integrations and session status](https://github.com/aliengiraffe/rhizome/blob/main/README.md#session-status)
- [Install and configure Rhizome](https://tryrhizome.dev/install.md)
- [Following a release from another session](https://tryrhizome.dev/resources/follow-work-happening-elsewhere)