# Add a harness or revisit a release

The content is the project. The website is a generated reading surface over that content. There are no harness-specific branches in the comparison renderer.

## Files and ownership

| File | Role |
| --- | --- |
| `registry.json` | Harness identities, repositories, snapshot metadata, common comparison axes, and guide navigation. |
| Each snapshot's chapter | Human-readable explanation with evidence and a source reading path. |
| Each snapshot's facts JSON | One qualified, cited record per comparison axis. Powers the website's comparison explorer. |
| `guide/` | Cross-harness teaching material. Update its synthesis when the selected snapshots change. |
| `templates/chapter.md` | Common research assignment and chapter structure. |
| `website/` | Renderer and interactive learning interface. Generated output lives in `website/dist/`. |
| `scripts/validate.mjs` | Structural checks, citation pin checks, and optional local source-range verification. |

## Add a harness

1. Identify the repository, commit, release tag if known, and precise runtime/application scope. Do not use a moving branch URL as evidence.
2. Create a new directory under `snapshots/<harness-id>/<short-sha>/`. Copy the chapter template and write `chapter.md` plus `facts.json` there.
3. Research the same axes as the existing harnesses. Use `unknown` with a bounded explanation when evidence is missing. Do not copy a competitor's behavior into a blank cell.
4. Add a harness record to `registry.json`, set `current` to its snapshot ID, and add the snapshot's commit, review date, label, chapter path, and facts path. Keep IDs lowercase and stable.
5. Review claims and source links. Update the guide where the new harness changes a comparison or teaches a distinct design.
6. Run validation and render the site. The new harness appears in navigation, snapshot selectors, and comparison columns from the registry.

A fact record has this shape:

```json
{
  "context": {
    "summary": "A short description of the observed behavior.",
    "detail": "Trigger, state transition, scope, and important qualification.",
    "availability": "core",
    "evidence": [
      {
        "label": "Source symbol and path",
        "url": "https://github.com/OWNER/REPO/blob/FULL_COMMIT/path/to/file#L10-L40"
      }
    ]
  }
}
```

Include every axis from the registry. Allowed availability labels are `core`, `optional`, `library`, `example`, `partial`, and `unknown`. Established claims need evidence. An unknown finding may have an empty evidence array only when its text explains the bounded inspection scope. Cite the source path that owns the behavior, not just a marketing description.

## Revisit a new release

Create a new snapshot; preserve the previous files and metadata. Resolve the release tag to a full commit and record both. A review date is not a release date.

Start with a diff between the old and new commit for the source paths in the evidence records. Then read the changed owning functions and their callers in full. A path that did not change can still behave differently because a caller, default, feature gate, or provider adapter changed.

For each axis, answer:

- Did runtime behavior change, or only an implementation detail?
- Did the default or feature gate change?
- Did responsibility move between the core, application, extension, and provider?
- Do cancellation, context, approval, and persistence still compose the same way?
- Is a formerly missing capability now established, or was the old comparison incomplete?

Write `changes.md` beside the new snapshot with four categories: **behavior changes**, **newly established evidence**, **documentation corrections**, and **still unresolved**. Include old/new source references. Add the new entry to `snapshots` and update `current` only after review. The website keeps older snapshots selectable; its release comparison shows record changes for a selected harness. Text differences are a review aid, not proof of a semantic behavior change.

## Keep the comparison fair

Do not give one project credit for an optional SDK while evaluating another only by its default terminal application. Use the detail field to identify layers. A source checkout with a feature is not proof that a released binary enables it.

Avoid boolean cells for nuanced behavior. “MCP supported” is less useful than the discovery path, transport, tool catalog lifetime, nested-call policy boundary, and error handling. “Multi-player” should separately evaluate client attachment, authorship, active-run arbitration, event distribution, and approval authority.

## Add a guide topic

Give each topic a Markdown file and a page record in `registry.json`. Set `parent` to the overview page's ID to place it in that page's collapsible submenu. Keep child pages immediately after their overview in registry order so the complete guide follows the same reading order. Use a short `title` for navigation and a descriptive heading in the Markdown file.

The overview uses `layout: "topic-overview"`; its top-level Markdown list renders as linked topic cards. Add the new topic's link and description there. Routes, downloads, and submenu entries are generated from the registry. A topic route automatically expands its parent's submenu; the parent's title opens the overview independently of the disclosure button.

## Verify and regenerate

From the comparison project directory:

```sh
cd website
npm install --ignore-scripts
cd ..
node scripts/validate.mjs
node scripts/validate.mjs --source-root /absolute/path/to/parent-of-checkouts
node --test scripts/validate.test.mjs website/render.test.mjs
node website/render.mjs
python3 -m http.server 4173 --directory website/dist --bind 127.0.0.1
```

The second validator command assumes checkout directories match harness IDs (`codex`, `pi`, `goose`, `sidekick`). When repositories live under different parents, create a temporary directory with one symlink per harness ID pointing to its checkout, and pass that directory as `--source-root`. It uses `git show` against the pinned commit, so a changed checkout branch does not silently change the evidence being checked. Missing repositories or objects fail source validation; obtain the intended source explicitly before retrying. Private source citations require an authorized local checkout; a public GitHub 404 does not establish that a private citation is invalid.

The generated site opens directly from `dist/index.html` as well as through a static server. It uses no live provider calls or runtime server state. Check navigation, matrix filters, snapshot selection, the learning walkthrough, deep links, and a narrow viewport after UI changes. Re-render after content changes so the guide and website agree.

Keep package versions exact and refresh the website's own lockfile with dependency changes. Do not install or build the compared harnesses merely to regenerate this resource. The host repository's required checks remain applicable to code edits.

## Suggested research delegation

Assign one researcher per harness, each owning its new snapshot directory. Ask a second researcher to challenge claims involving authority, replay, concurrency, and default settings. The coordinator owns cross-project vocabulary and synthesis. Verify citations mechanically and review semantics manually: a valid line number alone does not establish a claim.