Skip to content

README.md

Latest commit

 

History

History
196 lines (153 loc) · 22.6 KB

README.md

File metadata and controls

196 lines (153 loc) · 22.6 KB
Raw

Documentation index

Every document in docs/ is one of four things, and the difference matters more than the subject does. A reader who mistakes a proposal for a description of the product will implement something that already exists — or worse, trust a contract nothing enforces.

State What it means How to treat it
Living Describes how the product behaves now Trust it; fix it when it drifts
Program An active initiative, partly shipped Trust the "shipped" parts, check the rest against code
Historical A point-in-time record — a plan, proposal, draft, or measurement Read as evidence of intent on its date, never as current behavior
Tombstone Something deliberately removed The removal is the content

Dated design work does not live here. It goes in superpowers/specs and superpowers/plans — see that store's README for the point-in-time contract. A document in docs/ proper should be one somebody keeps current.

Living

Working in this repo

  • workflows/github-work-tracking.md: GitHub Issues and the Cave Project, ownership, Git-only hooks, worktrees, and handoff
  • multi-session-coordination.md — how concurrent agent sessions produce overlapping or orphaned work, and the hooks that catch it
  • workflows/work-continuity.md — skill-driven discovery of existing work before planning or dispatch, with scoped evidence and honest handoff receipts
  • source-text-pins.md — contract-first source-reading tests, deliberate adoption counts, parser-over-regex guidance, safe extraction, and mutation testing
  • performance-budgets.md — the single catalogue of approved production performance budgets: which gate enforces each, why a missing measurement fails closed, and how a limit is seeded and re-seeded
  • workflows/ — branching, release, and PR mechanics

Public APIs

  • api/client-v1.md — the Client v1 HTTP surface: the shared envelope, the loopback ingress rules, the pairing handshake, the administrator routes, the rate limits, and the routes that do not exist yet

Platform and runtime

  • audits/home-route-js-budget.md — the home route's first-load JavaScript budget: 2,800 KiB, enforced after every production build by scripts/bundle-budget.mjs, with how to reproduce and attribute a regression
  • client-v1-release.md — the compatibility metadata a release advertises on /api/client/v1/health, and the fixture-check and release-smoke gates that protect it
  • client-v1-settings.md — approving, denying, auditing, and revoking native client access in Cave Settings
  • event-plane-operations.md — the invalidation WebSocket: switches, rollout modes, what each platform pauses, security, recovery and diagnostics
  • device-access.md — opt-in tailnet allowlists, desktop-managed browser/iOS pairing, durable grants, revocation, and audit
  • cross-environment.md — neutral defaults across Linux, macOS, and Windows, plus the per-OS deltas and the suite that enforces them
  • runtime-startup-supervision.md — how Cave supervises the daemon and its own startup workers: the readiness contract, the projected lifecycle states, the one mutation owner, where the fault matrix and diagnostics live, and the startup-worker coordinator with its switches; pinned to the code by scripts/runtime-startup-supervision-doc.test.mjs (#6334)
  • model-catalog-pipeline.md — the declarative source, generator, and validation workflow for harness model catalogs and context metadata
  • first-run-setup-diagnostics.md — server-classified failure codes for the first-run bootstrap
  • settings-persistence.md — why the desktop shell cannot use origin-keyed browser storage as its authoritative store
  • windows-startup-diagnostics.md — per-port relaunch, native failure reporting and retained private startup evidence
  • windows-window-placement.md — fitted and persisted main-window geometry, Quick Chat placement, title-bar/tray appearance, recovery and outstanding Windows acceptance
  • windows-runtime-cache.md — the content-addressed archive layer and its two digests
  • windows-sidecar-recovery.md — loaded-shell recovery, native Retry and Windows qualification limits
  • windows-update-preparation.md — download, verify, and install as three distinct phases
  • windows-upgrade-benchmark.md — what scripts/windows-upgrade-diagnostics.ps1 captures
  • workflows/windows-msi-signing.md — SSL.com eSigner setup, the five signing inputs, and the release gate that publishes only the Authenticode-verified MSI (#5739)
  • performance/daemon-lifecycle.md — the opt-in real-daemon lifecycle probe and its 2026-10-20 diagnostic observation (#6120)
  • daemon-connectivity-reliability.md — the daemon connectivity launch flow, readiness checks, fault coverage, and measurement contract; the cave-58eoq program's tracked work all merged (#4485–#4528); #6298 owns the lifecycle, fault-matrix and diagnostics-export follow-ups and #6303 the boundary proof

Mobile and handoff

  • mobile-tailscale.md — exposing the browser surface to a phone over Tailscale Serve, including tokenless tailnet-device access
  • ios-current-direction.md — the canonical native iOS product shape, active priorities, and historical-plan boundary
  • workflows/ios-testflight-rollout.md: iOS rollout preparation, exact-artifact/device receipts, cohort HOLD decisions, and non-destructive recovery. #5319 closed as not planned on 2026-10-18 (an obsolete v0.4-era gate); release tags already upload iOS builds to TestFlight, and a future external-tester cohort needs a new issue
  • ios-webrtc-dsym-symbolication.md — why TestFlight uploads warn that the vendored WebRTC.framework has no dSYM, and how the release pipeline audits and restores symbolication coverage

Chat, familiars, and tasks

For saved transcript loading, start with these bounded entrypoints:

Responsibility Implementation and contracts Focused verification
Cache/network history, offline/flow fallback, cancellation src/lib/chat/history-load.ts; ChatHistorySources and ChatHistoryView are its explicit ports node --experimental-strip-types --import ./scripts/test-alias-register.mjs --test src/lib/chat/history-load.test.ts
Existing browser transport and encrypted caches src/lib/chat/history-sources.ts, conversation-cache.ts, offline-cache.ts Run src/lib/chat/history-sources.test.ts, src/lib/conversation-cache.test.ts, and src/lib/offline-cache.test.ts with the same Node test command
Live-generation admission, run ownership, effect cleanup and current-ref binding src/components/chat-view.tsx, chat-turn-state.ts src/lib/chat-transcript-load.test.ts, src/components/chat-view-lifecycle.test.ts, src/components/chat-switching.test.ts
Import boundary eslint.config.mjs explicitly limits coordinator and transport imports; dynamic imports are rejected node --test scripts/eslint/chat-history-boundary.test.mjs; pnpm lint:source, pnpm typecheck, pnpm check:tests-wired

The coordinator receives current ownership through callbacks. A pending history response cannot replace a send, edit, explicit reset or active generation. Cancellation suppresses publication without aborting shared requests. A 404 is authoritative absence; only a network failure can use offline history. The transport reuses the existing authenticated cache and revision/write guards.

  • thread-self-reports.md — familiar/session ownership, atomic automatic admission, manual repeats, and the persisted-report generation precheck
  • familiar-identity-context.md — how a familiar's declared identity reaches the model, and what the injection may not do
  • local-models.md — Codex local mode on Ollama and LM Studio: setup, addresses, what stays on this computer, how Full access relates to Codex's own sandbox (cloud Codex too), limitations and troubleshooting
  • auto-mission-mode.md — /auto, its status blocks, and the closing questionnaire
  • orchestration-ready-tasks.md — the shared task contract every familiar and orchestrator reads and writes
  • role-surfaces.md — role-aware rooms, and why the Cave is not role-hardcoded
  • chat-github-integration.md — the shipped GitHub integration and its turn-marker protocol
  • chat-image-carousel.md — image carousel markers, reusing the protocol above
  • chat-proposal-review-card.md — proposal-review receipt marker and evidence-only card (#5520)
  • research-host-contract.md — explicit core adapters and shared saved links for the optional Research package, plus the activation owner and hot-disable teardown contract (#6332)
  • research-core-boundary.md — the optional Research boundary and the shared contracts core keeps; shipped in #6025 and enforced by research-core-boundary.test.ts and research-maintenance-boundary.test.ts
  • research-run-surface.md — durable ResearchMission projections across Chat, Quick Chat, and Research Desk
  • execution-analytics.md — model- and harness-level analytics: the three model identities, why harness version is never recorded, coverage as the honesty layer, and what the aggregate discards

Knowledge, authoring, and marketplace

  • knowledge-vault.md — curated reference knowledge injected into every harness, and how it differs from memory
  • knowledge-packs.md — marketplace-distributed starter kits for a linked knowledge base
  • covenwiki-render.md — reading generated CovenWiki manifests at /wikis: the read-only store, slug rules, the three API reads, and what the reader refuses
  • prompt-packs.md — where prompt templates come from and how they merge
  • authoring-assist.md — templating and agentic assistance across stitches, skills, and crafts
  • marketplace.md — the checked-in publisher catalog, and why the in-app view is deliberately narrower
  • opencoven-submissions.md — runtime and harness submission, validation, and publication
  • mcp-doctor.md — debugging the two places MCP servers are listed

Compatibility registries

Design

  • coven-design-language.md — the consolidated reference for how the product looks, moves, and speaks, written from shipped code
  • beautiful-ui.md — the vendored Beautiful UI primitives: what the token adapter maps, why their CSS is scoped out of the root bundle, and why they are reference implementations rather than drop-in components

Integrity and integrations

  • upstream-api-anomaly-suite.md — the registry of every upstream API the server calls, the relevance scan that keeps it honest, the upstreamFetch primitive that classifies, retries, cools down and publishes a live health ledger, and the anomaly matrix each caller is proven against (#6359)
  • dependency-advisories.md — open Dependabot alerts whose patched version is unreachable from this dependency graph: the resolver refusal, the exposure assessment, and the upstream change that would lift each
  • stuck-action-runs.md — the four Actions runs wedged in queued since 2026-07-25 (issue #4905, closed as not planned 2026-09-16; the runs remain queued): the HTTP-500 history, the 2026-08-30 HTTP-403 retry record, the do-not-delete-workflow-history rule, and the retry tooling
  • project-permission-integrity.md — reconciling stale grants against the project registry
  • discord-rich-presence.md — privacy-safe local activity publishing

Program

Active initiatives. Parts have shipped; parts have not. Each states which.

  • core-contract-and-room-boundaries.md — the minimal product contract and source inventory for #6119: all workspace modes, role rooms, auxiliary subsystems and startup workers, with current boundaries separated from unverified extraction and recovery acceptance
  • desktop-onboarding.md — the evidence baseline and product contract for download → first successful familiar response, separating confirmed behavior from proposals still needing usability and packaged-app testing
  • chat-native-ui-tier.md — coven:ui blocks: the component catalog, expression whitelist, and streaming and failure contracts; the parser and renderer merged in #6073 and are wired into Main Chat, every other surface shows readable text (#6060), and no familiar prompt teaches the syntax until the rollout decision (#6063)
  • ci-implementation-plan.md — the release-candidate CI rollout: signed promotion, full validation, the parallel PR checks context, and promotion at real release cuts have shipped; the protection switch, retiring routine PR fanout, and verifying the lean gate remain, tracked in #6257
  • roadmaps/coven-automations-v1.md — the cross-repository Coven Automations v1 program (OpenCoven/coven#854) and its machine-readable mapping: foundation, protocol, scheduler reliability, embodiment, and authority have closed; dispatch-time trust (coven#857), certification (coven#858), the SDK, Cave oversight (#5217), Psyche, Docs, and organization canaries remain, and the 2026-10-18 release checkpoint is no-go
  • performance/ios-performance-audit.md — the native iOS performance record (opened 2026-08-10, updated through 2026-10-03): instrumentation, the Release capture driver, and the budgets ratified on 2026-10-02 (#5292), none CI-enforced; the main-thread hitch budget (#5748), inline-zoom device evidence (#5314), and the physical-device gates (#6259) remain

Historical

Point-in-time records. Read for intent, not for current behavior.

Tombstone

  • codeql.md — the CodeQL Advanced workflow and required context, retired 2026-07-31 in three ordered steps; GitHub's default setup now scans, advisory only
  • mobile-memory.md — Coven Memory's mobile routes, removed with the canonical memory vault in #5418 (2026-09-16)

Other trees under docs/

Keeping this honest

When you add a document here, add its line to the right section. When a document stops describing the product, move it to Historical rather than deleting it — and when you remove a subsystem, leave a tombstone like codeql.md instead of leaving a gap where the explanation used to be.