r3: Skill for Claude Code

r3's API + CLI surface

This file is the design source of truth for r3's route catalog and CLI usage — update it here when the surface changes. The wire shapes live in shared/artifacts.ts (re-exported by shared/types.ts); this is the map over them.

The HTTP/JSON API is the product, not a detail of the React client — there are three clients (browser, CLI, agent). When you change behavior, change shared/artifacts.ts and keep server + CLI + web in sync.

The conversation hierarchy is Discussion → Thread → Comment. Discussion is the artifact-wide grouping; Threads own targets, claims, and resolution; Comments are authored messages, including archive messages directly in the discussion.

HTTP API

Artifact API

server/artifact-api.ts assembles the API against injected artifact storage. server/artifact-daemon.ts opens and migrates storage before accepting requests. The CLI, browser, and demo all use this protocol; legacy routes are removed.

• GET /api/library-summary?window=daily|weekly returns ArtifactUsage: current backend-wide inventory, published versions, conversation counts, deduplicated content bytes, default-TTL GC eligibility, and activity buckets. Windows are fixed at 14 calendar days or four Monday-start weeks, including the current partial period, in the explicitly returned server timezone. Activity counts survive content deletion; completeSince marks partial pre-upgrade coverage. Reads have no delivery effect.
• POST /api/gc accepts ArtifactGcRequest: optional ttlDays (integer 1..36500), dryRun (default false), and optional confirmed candidates (id, archivedAt). Default TTL is persisted archiveTtlDays, or 30 elapsed days. Only archived artifacts at or before the cutoff qualify. A supplied candidate list restricts deletion to that preview and skips changed archive timestamps, restored artifacts, and missing members. Results include candidates, reclaimable content bytes, deleted/skipped IDs, per-artifact failures and any post-commit blob cleanup error. Cleanup uses whole-artifact cascades, preview revocation, deletion invalidations, and publication-coordinated blob collection. Both routes require normal API auth and origin guards and return no-store. GC is manual, never a startup timer.
• GET/POST /api/sessions lists/registers explicit agent identities; labels are mutable display names and never identity or delivery addresses. Label changes invalidate each referencing artifact, refresh its complete label map, and update both selected and fallback subscription labels. Unchanged labels emit no event; GET/POST /api/projects and PATCH/DELETE /api/projects/:id manage optional grouping. PATCH accepts EditArtifactProjectBody (name, remoteUrl, optional expectedRemoteUrl). Remote backfill can require the current field to be null; concurrent changes conflict. Removing a group preserves its artifacts and deletes its automatic remote mapping.
• GET/POST /api/artifacts, GET/PATCH/DELETE /api/artifacts/:id list, create, inspect, edit metadata, or delete the whole artifact. Creation accepts a sanitized remoteUrl hint for server-configured project inference; explicit projectId, including null, wins. List filters are state, kind, project, and meta.<key>. No repo header or local path is involved. Artifact detail includes a process-scoped syncCursor; ?since=<cursor> returns a bounded delta or a full snapshot on a gap. ?view=summary reads only its Artifact projection. See incremental reads. Artifact detail includes agentLabels, current display labels keyed by the sessions referenced in its creator, versions, threads, comments, claims, and lifecycle events. Unnamed entries are null; unrelated sessions are omitted. The browser uses these labels without fetching the global session list. Artifact reads include computed unhandledCount: open threads whose latest message is from an agent. Reading, delivery, and claims do not clear it. storage.totalBytes and storage.latestVersionBytes report deduplicated published content and the latest publication's full footprint, excluding database/filesystem overhead. See storage accounting. latestVersion is null before publication, otherwise a list projection of the latest committed sequence, label, summary, and publication time; never nextSeq - 1. Artifact metadata has no overview/summary field. Publication summaries remain immutable version metadata; edit --summary is unsupported.
• GET /api/search?q=... returns ArtifactSearchResponse from shared/artifact-search.ts (re-exported by shared/artifacts.ts). Filters: state=active|archived, kind=files|html|diff, project=<id>, attention=true|false, history=latest|all, type=all|content|conversation, limit=1..100 (default 50), and offset=0..100000. Queries contain 1–16 Unicode word prefixes, at most 256 characters, combined with AND; punctuation is a separator and FTS syntax is never executed. Latest scope limits publications; conversation matches retain each message’s recorded context. Results contain plain-text snippets, native targets, thread/comment IDs, per-type counts, and nextOffset. skippedFiles reports excluded binary, invalid UTF-8, or >4 MiB text files in the selected scope. HTML searches static entrypoint text without executing scripts or searching companion source. Same authentication/origin guards as artifact reads; no comment acknowledgment, claim, subscription, or delivery effect. CLI: r3 search "words" with corresponding flags, --attention, and --json.
• GET/POST /api/artifacts/:id/versions lists retained versions or publishes a complete version with expectedSeq, publicationKey, explicit actor, and optional boolean listen (default true). A new commit replaces the fallback using a connected worker destination, or clears it when absent/disabled. Replays cannot reclaim the fallback. The response adds a complete backend-owned url, listenerRegistered, and optional worker listener subscription. CLI text and JSON output preserve that stable URL unchanged, without a browser sign-in ticket. There is no per-version delete. GET .../versions/:seq reads version metadata.
• GET .../versions/:seq/files|source|resource|diff|diff-context|patch reads membership, highlighted source, original bytes, rendered sparse diff, retained context, or original patch. source and resource take ?path=; diff-context takes ?path=&start=&end= in new-side coordinates. Highlighted reads accept ?theme=. Resource GET/HEAD supports ranges and validators; app-origin HTML is always an attachment. Missing bytes never fall back to a different version or the filesystem. Executable rendering belongs to preview.
• GET/PUT /api/artifacts/:id/viewed persists opaque read-progress keys with { key, viewed }. Theme and login-token endpoints retain their response shapes.
• GET/POST /api/artifacts/:id/threads, GET/PATCH/DELETE /api/threads/:id, POST /api/threads/:id/comments and GET/PATCH /api/comments/:id use native immutable original targets and derived comment references. Historical placements remain readable; new placement authoring is removed. A Thread contains one ordered Comment list, including its opening Comment. The common comment read/edit endpoint also accepts artifact-level archive Comments; these are text-only and editable after restore. r3 comment show reads any Comment without acknowledging it; r3 comment edit edits its body and supported images. Every message mutation names an actor; deletion takes { actor }. Only human actors change thread status. Files also accept native media targets with locator: { time, box } and a required mediaSnapshot (full-frame PNG/JPEG upload). Reads add the immutable locator.frame descriptor; bytes use the attachment route. Snapshot evidence is separate from editable message attachments. CLI thread add/comment accept --frame <path> with a media --target; media targets accept --view media. Comment fetch manifests include target frames, including follow-up originals. Rendered locators accept an optional plain-text label for named HTML fix links; matching still uses the selector and native evidence. See r3 guide html for the comment example and the schema document for storage semantics. artifact_summary and version_summary are historical read-only targets; new threads and comment fix targets reject description anchors.
• GET /api/threads/:id/source returns ArtifactSourceRange for the original source/diff line target: artifact, version, path, side (null for source), inclusive start/end, and complete text with LF separators. Rendered, general, and whole-file targets return 400; missing threads return 404. The normal authentication and origin guards apply. This read never acknowledges comments, claims a thread, or establishes a subscription. Source/diff quotes may be nonblank exact excerpts within the complete captured range; range existence, version/file/side, diff gaps, and input limits remain validated. Browser excerpts are capped at four lines and 2,048 UTF-16 code units; existing saved quotes are unchanged.
• POST/DELETE /api/claims { sessionId, threadIds } claims/releases as the named registered agent. Claims change presence, not owner delivery.
• GET .../:id/comments/pending[?threads=<ids>] returns an ArtifactCommentSnapshot: formatted text, itemCount, and an acknowledgment containing the selection and required expectedFingerprint. It is read-only and uncached; archived artifacts return 409. POST .../:id/comments/acknowledge takes that ArtifactCommentAcknowledgment after successful consumption and returns { acknowledgedCount }. Missing/invalid fingerprints return 400; stale revisions, changed selection, or archive return 409 without marking content delivered. An unfiltered snapshot also includes pending artifact-level Comments after restore. The fingerprint binds artifact, selection, and persisted conversation revision, including edit/revert and prior acknowledgment. GET .../:id/comments/history[?threads=<ids>] returns ArtifactCommentRead (text, itemCount) without acknowledgment data: open history by default, or the specified threads including resolved ones. History remains readable after archive. The browser copies only the CLI command and makes no comment-read or acknowledgment request. The former /prompt routes and CLI alias are removed.
• POST .../:id/submit returns { notification }; sent confirms a local harness delivery acknowledgment or a generic watch woken for pending comments. An absent selected subscription (or a watch with no pending work) returns none. Local Codex or Antigravity acceptance returns queued; failure returns failed and HTTP 502. Neither acknowledges comments. POST .../:id/lifecycle takes ArtifactLifecycleBody, returning the persisted event (including its optional artifact-level comment), replay flag, and notification result. Archive input is comment: { body }; blank bodies normalize to no Comment. Delivery failure is HTTP 502; the committed archive remains authoritative. Replays do not notify twice.
• POST /api/artifacts/archive takes ArtifactBulkArchiveBody: explicit actor, 1–100 unique items: [{ id, operationKey }], and optional shared comment: { body }. Validate the whole envelope before writes; malformed requests fail as a whole. A valid batch returns HTTP 200 and ArtifactBulkArchiveResponse.results in input order. Each item independently uses the lifecycle transaction: archived includes eventId, replayed, and notification; skipped has reason already_archived; failed includes HTTP-equivalent status and error. Missing artifacts fail with 404; conflicting operation keys fail with 409. Other artifacts still proceed. Matching operation keys replay before the already-archived check, including after restore, without another transition or notification. Fresh keys skip existing archives without changing timestamps. Notification failure remains an archived result with notification.state: failed, not a batch HTTP 502. Claims, subscriptions, Comments, and invalidations follow the single-artifact lifecycle rules. Requests retain the ordinary 2 MiB streamed body limit, auth/origin guards, and no-store responses. The home page chunks larger selections and keeps each item's retry key.
• GET .../:id/watchers reads subscriptions and POST .../:id/watch { actor, timeoutMs? } establishes an explicit subscription for a bounded long poll. DELETE .../:id/listen { actor } removes that actor's subscriptions. Persistent listen and delivery acknowledgments use the shared worker protocol below. The former per-artifact POST listen stream and /api/connections/:id/acknowledgments are removed. Backend HTTP receives no harness socket, executable path, or harness credential.
• GET /api/events[?artifact=<id>] is an authenticated fetch stream of ArtifactStreamEvent invalidations. ready means refetch current state; heartbeat keeps the connection alive. Neither implies message delivery.