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 Servingcairnd 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 process…