P1: Publish Coven Automations v1 protocol, operator, migration, and troubleshooting documentation

[BunsDev]

Cross-repository program: OpenCoven/coven#854
Core protocol: OpenCoven/coven#855
Reliability: OpenCoven/coven#856
Identity/authority: OpenCoven/coven#857
Certification/diagnostics: OpenCoven/coven#858
SDK: OpenCoven/sdk#80
Cave: OpenCoven/coven-cave#5217
Psyche: OpenCoven/psyche#18

Outcome

Make Coven Automations v1 understandable, operable, migratable, and difficult to misrepresent. Documentation must be generated from or tested against canonical artifacts where possible, distinguish implementation evidence from certification, and preserve the ownership boundary: Coven owns schedules and lifecycle; identity/authority/Psyche/runtime/Cave/SDK each own their explicit layer.

Docs should become the compatibility ledger and operator guide—not a second specification written from memory.

Required documentation set

1. Architecture and ownership

Explain the end-to-end flow:

AutomationDefinition revision
  -> trigger evaluation / occurrence fence
  -> claim + execution binding
  -> familiar continuity + Threads authority
  -> direct runtime or Psyche orchestration
  -> run/attempt evidence
  -> delivery + AutomationReceipt
  -> Cave/SDK projections

Include a canonical ownership table and explicit non-ownership rules for Familiar Contract, Threads, Psyche, Coven, runtimes, SDK, Cave, and Beads.

2. Safe quickstart

Document a complete local workflow:

• install/verify compatible Coven components;
• inspect automations capability/profile versions;
• create a paused draft;
• preview schedule/timezone behavior;
• inspect familiar binding, risk/capabilities, and approval policy;
• explicitly activate;
• observe occurrence/run/attempt/receipt;
• pause/cancel/retry/reconcile safely;
• diagnose daemon unavailable or stale state;
• remove/tombstone without erasing required history.

All examples must default to paused and use a low-risk local action. No quickstart should normalize unattended external effects.

3. Protocol reference

Document the exact versioned objects and state machines produced by OpenCoven/coven#855:

• AutomationDefinition/Trigger/Condition/Action;
• occurrence/run/attempt/lease;
• command adoption/idempotency and expected revision;
• event/changefeed/cursors;
• typed errors and capability negotiation;
• receipt and lifecycle invariants;
• deletion/tombstone/history semantics.

Generate tables/examples from pinned schemas or mechanically verify them in CI.

4. Time and scheduling semantics

Document:

• supported RRULE subset;
• UTC and IANA timezone behavior;
• migration from local compatibility input;
• DST gap/fold policy;
• clock jumps, suspend/resume, daemon downtime, and startup reconciliation;
• misfire, overlap, retry, backoff/jitter, cancellation, timeout, quarantine;
• schedule preview/dry-run commands;
• explicit unsupported vocabulary and refusal behavior.

Use executable vectors for every edge case.

5. Identity, authority, and approvals

Explain:

• familiar root versus display alias;
• exact revision embodiment binding;
• authenticated principal binding;
• capability/risk classification;
• permit / requires approval / degrade to proposal / reject;
• approval issue/expiry/revocation/consumption and invalidation;
• runtime capability binding;
• what an Automation Receipt proves and does not prove;
• why prompt text, tags, runtime names, or creation-time approval are not authority.

Link and pin Familiar Contract and Threads profile artifacts.

6. Lifecycle and recovery

Publish diagrams and tables for:

• definition revisions;
• occurrence states;
• run/attempt states;
• claim/lease/fence ownership;
• cancellation request/acknowledgement;
• retry and delivery-only retry;
• recovery-required/ambiguous outcomes;
• daemon and Psyche restart reconciliation;
• changefeed reconnect/replay.

Make clear that acceptance, dispatch, and success are distinct states.

7. Operator guide and runbooks

Document supported diagnostics and safe actions for:

• missed/late occurrence;
• suspected duplicate;
• stuck claimed/running attempt;
• expired/stale lease;
• repeated failure/quarantine;
• unauthorized or approval-blocked run;
• stale/revoked familiar identity;
• incompatible runtime capability;
• delivery commit failure;
• invalid/unverifiable receipt;
• event subscriber lag/cursor expiry;
• SQLite integrity/contention/disk pressure;
• daemon unavailable or scheduler unhealthy;
• ambiguous external side effect.

Every runbook must include symptoms, authoritative evidence, safe diagnostic command, decision tree, permitted recovery, forbidden shortcuts, and escalation/evidence packet. Never recommend deleting rows or blindly rerunning ambiguous work.

8. Legacy migration

Document the source-preserving path from Codex-owned definitions:

• what is discovered and normalized;
• what is unsupported/refused;
• imported definitions remain paused;
• source files remain unchanged;
• review/activation checklist;
• Cave compatibility-facade deprecation and retirement schedule;
• rollback and data preservation;
• terminology mapping from Codex automation to Coven automation/routine.

9. SDK and integration guides

Provide:

• read/health/history/receipt examples;
• changefeed subscription and duplicate-safe replay;
• receipt verification and degraded outcomes;
• adoption keys, revision conflicts, unknown outcomes, and reconcile;
• approval/cancel/retry guardrails;
• direct runtime adapter contract;
• Psyche invocation/correlation contract;
• Cave projection boundary;
• no direct SQLite/filesystem/runtime fallback.

Examples must run against packed/released artifacts.

10. Security, privacy, and threat model

Cover:

• principal authentication, nonce/replay, rotation/revocation;
• familiar/authority/runtime binding;
• confused-deputy and capability escalation;
• TOCTOU around authorization/commit/dispatch;
• secret/prompt/memory/path redaction;
• event/history/receipt access control;
• retention/redaction/erasure/tombstone;
• exactly-once limitations and external-effect ambiguity;
• conservative product/legal language.

11. Compatibility and conformance ledger

Generate a current matrix naming exact immutable revisions and supported profiles for:

• Coven automations protocol;
• Familiar Contract embodiment binding;
• Threads authority profile;
• Psyche adapter;
• runtime descriptors;
• SDK;
• Cave;
• conformance runner/vectors;
• release artifacts.

Do not use one generic “compatible” badge. Report Structural, Scheduler Reliability, Runtime Authority, Continuity, Privacy, Interoperability, and Full profiles separately.

12. ADRs and decision log

Publish or link the ratified decisions for:

• Coven as schedule/lifecycle authority;
• protocol object/state ownership;
• at-least-once observation versus no duplicate fenced execution;
• command adoption/idempotency;
• timezone/DST/misfire defaults;
• retry/ambiguity/cancellation semantics;
• familiar embodiment binding;
• automation authority/approval profile;
• direct runtime versus Psyche adapter;
• event/changefeed and retention;
• Beads/GitHub tracker roles;
• v1/P2 boundary.

Documentation quality gates

• Code/schema examples compile or validate in CI.
• CLI examples run against the supported binary or a deterministic fixture.
• SDK examples run against packed packages.
• Schema examples validate against exact pinned artifacts.
• Links, anchors, Mermaid diagrams, accessibility, and spelling pass.
• Version numbers and compatibility tables are generated from manifests where practical.
• Stale-version/orphan-page checks fail CI.
• Deployment emits a docs content hash/version consumed by search/RAG surfaces.
• llms.txt/llms-full.txt or equivalent machine-readable documentation stays synchronized.
• Temporary incident guidance is dated, scoped, and expires; it does not become permanent architecture.

Suggested information architecture

docs/automations/
  index.md
  architecture.md
  quickstart.md
  definitions.md
  schedules-timezones.md
  lifecycle.md
  identity-authority.md
  approvals.md
  runtimes.md
  psyche.md
  sdk.md
  cave-oversight.md
  migration-codex.md
  operations/
    index.md
    missed.md
    duplicate.md
    stuck.md
    unauthorized.md
    stale-identity.md
    failing.md
    delivery.md
    receipts.md
  security-privacy.md
  conformance.md
  compatibility.md
  adr-index.md

Adapt to the docs repository’s current conventions rather than creating a competing navigation system.

Verification scenarios

At minimum, documentation CI/dogfood must cover:

• paused create/activate/observe;
• twice-daily schedule and timezone preview;
• DST gap/fold examples;
• restart/latest-only misfire;
• run-now adoption replay;
• approval/degrade/reject;
• stale/revoked familiar refusal;
• runtime capability mismatch;
• cancel/retry/recovery-required;
• delivery-only retry;
• changefeed reconnect/replay;
• receipt verification/tamper/degraded history;
• legacy import source preservation;
• daemon unavailable with no fallback;
• direct and Psyche-orchestrated runs.

Acceptance criteria

• Complete architecture, quickstart, protocol, scheduling, authority, lifecycle, operations, migration, SDK, security/privacy, compatibility, and ADR documentation ships.
• Examples and diagrams are generated from or tested against exact artifacts.
• Operator runbooks never recommend unsafe raw repair or blind ambiguous retry.
• Compatibility reports each conformance profile separately at immutable revisions.
• Legacy Codex migration and Cave facade retirement are clear and source-preserving.
• Stale-version, broken-link, orphan-page, schema/example, Mermaid, accessibility, and machine-readable-doc gates pass.
• The docs deployment exposes a content/version hash for downstream indexing.

Non-goals

• Making documentation the canonical protocol source when normative artifacts disagree.
• Advertising broad unattended external authority.
• Hiding incomplete certification behind polished prose.
• Duplicating mutable Beads/GitHub status inside manually maintained pages.

Bead packet

Create one P1 documentation Bead mapped exactly to this issue. It depends on stabilized artifacts from OpenCoven/coven#855–#858 and links the SDK/Cave/Psyche/upstream profile outcomes. Evidence must include tested examples, generated compatibility data, runbook dogfood, stale-doc gates, deployment content hash, and exact artifact pins.