Specifications
SPEC-0001Web App Shell and the BinCairn presents every share type — markdown, code, image, generic file, bundle, live webhook, trajectory — inside a single web app shell: a header (logo · type badge · title · one URL control with copy + ◆ mcp · Share)…
SPEC-0002Artifact Core and Share TypesThis capability is the backbone every other Cairn spec builds on. It defines the Artifact aggregate and its lifecycle (create / read / list / delete), the share-type registry that classifies an artifact and selects its…
SPEC-0003Artifact ViewersCairn renders every artifact inside one app shell (SPEC-0001) but gives each share type a type-specific body viewer.
SPEC-0004Trajectory ShareThe trajectory share type (badge TRJ, URL cairn.stump.wtf/run/<id>) captures a whole agent run and lets humans view it.
SPEC-0005Webhook InspectorThe webhook share type (badge HK, URL cairn.stump.wtf/<id>) is a live requestbin: an endpoint an agent or a service points at, whose inbound HTTP requests stream into a web inspector (highlighted JSON, method/status, a…
SPEC-0006Annotations — Reactions & CommentsEvery Cairn share type carries the same two social affordances: emoji reactions and threaded comments.
SPEC-0007MCP Server and OAuth AuthorizationThis capability defines Cairn's MCP server surface — the agent interface — and the OAuth 2.1 authorization that lets an agent (or the CLI) act on a human's behalf.
SPEC-0008The cairn Command-Line InterfaceThe cairn CLI is the human's terminal surface for Cairn. It is pbcopy for cairn: pipe or pass content and files in, get a shareable, agent-native link back — printed to stdout and copied to the clipboard.
SPEC-0009Provenance, Link-Based Access, and RetentionThis capability formalizes the three intertwined policies that govern every Cairn artifact and annotation: provenance, link-based access control, and retention/expiry.
SPEC-0010The Public Website and the Published Design RecordCairn's public website is a Docusaurus 3 application under website/ that builds to a static bundle.
SPEC-0011OTLP Trace IngestionCairn accepts standard OTLP/HTTP trace exports and translates them, at ingest, into the native run/span tree of SPEC-0004.
SPEC-0012Outbound Webhooks(Rendered edges are derived from front-matter; body links to repo paths would break on the generated site page.)
SPEC-0013GitHub Login for the Web App ShellThe web app shell (SPEC-0001) authenticates humans today via Pocket ID OIDC (ADR-0013) and, outside production, dev_login_password.
SPEC-0014Prometheus MetricsCairn exposes a Prometheus text-format endpoint at GET /metrics, led by storage and expiry — the two properties that grow without anyone deciding they should.
SPEC-0015Embedded Documentation Servingcairn serve serves the published documentation itself. The Docusaurus bundle built from website/ (SPEC-0010, ADR-0014) is embedded in the server binary behind the docs build tag and served at /docs/* from the same…
SPEC-0016Annotation and Trace Lifecycle EventsCairn announces artifact.created today (SPEC-0012) and nothing else. This capability adds comment.created, reaction.added, reaction.removed and run.closed on the same envelope, signer and queue.
SPEC-0017Secret Detection and Redaction at IngestEvery text Cairn stores is scanned for credentials before it is persisted:
SPEC-0019Actionable Validation ErrorsA validation_failed response today says only "the request was invalid". This capability defines a violations array: field, location, reason code, limit, a bounded echo of the value, and a human message.
SPEC-0020Opt-In Permanent RetentionThis capability lets an artifact's owner mark it permanent: it never expires, its id never changes, its checksum is published, and removing it leaves an audit tombstone.
SPEC-0021Structured ReceiptsA receipt is the record an agent leaves when it finishes a piece of work. This capability makes it structured: an artifact carries a typed metadata object from a closed, versioned schema registry, and the first schema…
SPEC-0022Search, Semantic Search, and Export by TagThis capability lets a person, and an agent acting for them, find artifacts by content and by meaning.
SPEC-0023Teams and TenancyCairn is multi-tenant. This spec, per ADR-0029, makes the owner of every artifact explicit and adds teams as the second kind of owner, realising the workspace ADR-0001 named and left thin.
SPEC-0024Artifact Relations and Trace ContextAn artifact MAY declare up to 8 relations at creation. Each relation is typed, as reply_to, derived_from or follows, and each target must be an artifact the creator can read.
SPEC-0025Artifact AssignmentAn artifact MAY carry one assignee: a nullable reference to a user, set at creation and changeable or clearable afterwards by the users who may already change the artifact's metadata.