docs(automations): publish Coven Automations v1 protocol, operator, migration, and troubleshooting documentation

[CompleteDotTech]

Summary

Publishes the Coven Automations v1 documentation set as a new governed Automations section (preview stability), mapped to the cross-repository program in OpenCoven/coven#854.

• Architecture and ownership — end-to-end flow with landed-vs-ratified annotations, the canonical ownership table, explicit non-ownership rules, and the program's non-negotiable invariants (Program: Coven Automations v1 — reliable, identity-bound familiar routines coven#854).
• Safe quickstart — install → capability check → paused draft → schedule preview → binding/policy inspection → explicit activation → observe occurrence/run/delivery → pause/diagnose → remove without erasing history. All examples default to PAUSED and use a low-risk local action; nothing normalizes unattended external effects.
• Protocol reference — the landed routine-definition schema (exact field rules and golden valid/rejected vectors mirrored from the implementation's tests) plus the ratified coven.automations.v1 objects, command/adoption semantics, changefeed envelope, and tombstone rules (P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed coven#855). Documents honestly that domain failures currently arrive inside a 200 action envelope.
• Schedules and timezones — the exact supported RRULE subset with executable vectors, local compatibility-input semantics, the ratified IANA/DST gap-skip and deterministic-fold policy, downtime/sleep/clock-jump behavior, misfire/overlap/retry/cancellation/quarantine status (P0: Harden automation time, retries, cancellation, fencing, and crash recovery coven#856).
• Lifecycle — occurrence/run/attempt state machines, claim/lease/fence ownership, cancellation and delivery-only retry rules, recovery-required semantics, restart reconciliation, and the health projection.
• Identity, authority, approvals — familiar root vs display alias, exact revision embodiment binding, principal binding, R0–R4 risk classes, authority decisions, approval lifecycle, receipt semantics (what a receipt proves and does not), and why prompt text, tags, runtime names, or creation-time approval are not authority. Pins familiar-contract#17 and coven-threads#29.
• Operations runbooks — nine symptom-driven runbooks (missed, duplicate, stuck, unauthorized, stale-identity, failing, delivery, receipts) each with symptoms, authoritative evidence, safe diagnostics, a decision tree, permitted recovery, forbidden shortcuts, and escalation guidance. No runbook recommends raw SQLite repair or blind retry of ambiguous work.
• Migration from Codex — source-preserving import (imported definitions stay paused, sources untouched), refusal of unsupported vocabulary, a review/activation checklist, rollback, and the Cave compatibility-facade retirement story (coven-cave#5217).
• Security and privacy — threat model (replay, confused deputy, capability escalation, TOCTOU), redaction, access control, retention/tombstone, exactly-once limitations, and conservative language rules.
• Conformance and compatibility — the seven conformance profiles reported separately at exact revisions; no generic "compatible" badge. States plainly that the program is foundation-ready, not v1-certified.
• ADR index — each ratified decision linked to its normative source, with the rule that decision changes happen upstream, not in docs.

Verification of claims (source of truth)

• Landed behavior was verified against OpenCoven/coven crates/coven-cli/src/automations/** and crates/coven-cli/src/control_plane.rs at commit 1364cec9dbaf1e2aca2e4544dec0e1ce807d859c (2026-08-30).
• docs/source-lock.json adds a coven-automations-foundation source watching those paths so future upstream changes create a review obligation instead of silent staleness.
• The pre-existing coven-runtime-contract entry had drifted (commits 882fc86, 4aa5b35, c291b72, 3dd51ed, and the automations tick series landed after its verifiedAt). Per the freshness contract, the drifted changes were reviewed against public page claims — the doctor change is additive diagnostics, the setup change is version-parsing robustness, the stream-json change is not a documented claim, and the automations parts are documented by this PR — and the lock was advanced to the same verified commit. pnpm check:source-drift passes with changedPathCount: 0.

Issue

Refs #76.

Refs OpenCoven/coven#854, OpenCoven/coven#816, OpenCoven/coven#855, OpenCoven/coven#856, OpenCoven/coven#857, OpenCoven/coven#858, OpenCoven/sdk#80, OpenCoven/coven-cave#5217, OpenCoven/psyche#18.

Stability impact

• Adds one new section (automations, stability preview, owner OpenCoven/coven) to docs/site-manifest.json and the root navigation. No existing section, route, or redirect changes.

Affected public routes

• New: /docs/automations and its 17 child pages plus /docs/automations/operations/*. No retired URLs are reintroduced; no redirects change.

Test plan

• pnpm typecheck
• pnpm check:content (site-manifest, source-lock, english-only, no-leading-h1, product-scope, fumadocs, daemon/cli/coven-code/harness/memory-models docs, mermaid parse — 26 diagrams valid)
• pnpm check:links (0 errors) and pnpm check:anchors (112 MDX pages)
• pnpm check:automation and pnpm test:api-runner (23 tests pass)
• pnpm check:source-drift (0 drifted watched paths, after the documented lock review)
• pnpm build:site — 122 static pages including all /docs/automations/* routes
• pnpm verify full run with browser smoke test (deferred to CI; requires Chrome install)

[vercel]

@CompleteDotTech is attempting to deploy a commit to the 0xBuns Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
coven-docs	Ready	Preview	Aug 30, 2026 4:19pm