# Cairn — consolidation observatory

> Cairn tells an agent whether an error, issue, or fix is ALREADY KNOWN before you file a
> duplicate or write a redundant patch. It serves a deduplicated, fix-linked view of a
> repository's issues and PRs over a published read-model.

## Use this FIRST

Before filing an issue or writing a fix, send the error / stack trace / diff to `match`:

    POST https://cairn.observer/api/v1/<org>/<repo>/match
    (body: the raw error text, stack trace, or draft issue — or JSON {"text": "..."})

You get back the best-matching clusters (or a `novel` verdict if nothing matches).

## Endpoints

- `POST /api/v1/<org>/<repo>/match` — paste an error/stack/diff → matching clusters (headline).
- `GET  /api/v1/<org>/<repo>/search?q=...` — free-text search → ranked cluster references.
- `GET  /api/v1/<org>/<repo>/lookup?issue=N` (or `?pr=N` / `?url=...`) → the exact cluster.
- `GET  /api/v1/<org>/<repo>/cluster/<id>.json` — the machine trust contract (typed).
- `GET  /api/v1/<org>/<repo>/cluster/<id>.md` — the human-readable dossier.

## Machine contract

- `https://cairn.observer/openapi.json` — OpenAPI 3.1 for the API above.
- `https://cairn.observer/api/v1/schema.json` — the JSON Schemas an agent validates responses against.

## Doctrine (read this before you act on a result)

- **Verdict-free.** Results state FACTS as events ("a fix was merged to main in PR #N —
  verify"), never a verdict like `resolved`. The `.md` may hedge; the `.json` never does.
- **Resolution is DISTINCT from a merged fix.** `resolution.state` is the maintainers'
  verdict over the issues; a merged fix does NOT imply `resolved`. Weigh them separately.
- **Trust tiers.** Threshold on `tier` (verified vs suggested), NOT on the raw
  `confidence` number. Verified-tier detail shows by default; add `?include=suggested`
  for the rest. Freshness: an `is_stale` fix confirmation is old — re-verify.

## Adopt it

- Drop-in AGENTS.md / CLAUDE.md snippet: `https://cairn.observer/agents.md`
- Skill wrapper: `https://cairn.observer/skill.md`