Operate Craik

This section is for the people running Craik in anger — daily diagnostics, release practice, the operator views that surface what's happening inside a run, and the supporting subsystems (gateway, channels, companion apps, multimodal, locale).

Implementation paths

01

Day-to-day operations

The four commands you reach for most often.

Read-only diagnostics, the contributor quality gates, the safe-update flow, and the release cadence. Start here if you're picking up an already-running install or preparing to cut a release.

Diagnostic · 01

Doctor diagnostics

The read-only health check. Inspects local home, SQLite store, memory backend, every auth profile, gateway config, gateway prerequisites, and policy state — without contacting Stigmem or writing receipts. Run it before going live or whenever something feels off.

• read-only
• auth-profile health
• structured statuses
• CI-friendly JSON

Run doctor

Read-only

craik doctor inspects existing local state and environment variables. It does not create CRAIK_HOME, initialize a database, contact Stigmem, start a gateway, or write receipts.

— Doctor diagnostics · §Read-only

1. 02Quality gates

   Development checks

   The four core gates contributors run before opening a PR: pytest, ruff, mypy, and craik policy test. Same set CI exercises on every push — green locally usually means green in CI.

   Guide
2. 03Safe update

   Updating Craik

   craik update prints safe update guidance only — it does not modify the installed package, rewrite source checkouts, fetch remote release metadata, or migrate local state. Operator stays in control of the actual upgrade.

   Guide
3. 04Release

   Release management

   The release cadence and gates for the 0.x.0 MVP series. Each published release must be installable, documented, and recoverable — contracts can change between minor releases but never without docs and tests.

   Guide

02

Local state & migrations

Where state lives — and how to move it.

Four docs cover the on-disk layout, the SQLite local store, the forward-only migration discipline, and the strict secret-handling policy that applies whenever data crosses runtime boundaries.

Persistence · 01

Local store

SQLite at $CRAIK_HOME/state/craik.sqlite3. Holds projects, tasks, intent locks, case files, run state, receipts, handoffs, memory proposals, contradictions, and work-graph projections. Schema is versioned; migrations run on LocalStore.initialize().

• SQLite
• versioned schema
• forward-only
• single source of truth

Read the store

Persistence

Craik uses SQLite for local runtime persistence.

— Local store · §Intro

1. 02On-disk layout

   Local state layout

   The full ~/.craik/ directory map: config/, secrets/, state/, cache/, logs/, receipts/, handoffs/, case-files/, projects/. Override the root with CRAIK_HOME.

   Reference
2. 03Migrations

   Local store migrations

   Migrations are forward-only and run during LocalStore.initialize(). Each step is versioned; a schema-version table tracks what has applied so a re-initialization is idempotent.

   Guide
3. 04Policy

   Secret migration policy

   Migration workflows must never copy secret values across runtime boundaries. Secret-bearing fields are handled through one of four policy outcomes — redact, strip, reference, or reject — never copied as-is.

   Reference

03

Operator views

Seventeen read-only inspection surfaces.

Every typed runtime record has a matching named view. Work graph, handoffs, receipts, contradictions, evidence, delegation queues, budget, quality, run deltas, memory previews, traps, preferences, and instruction provenance — each surfaces what an operator needs without mutating state.

Current scope: Craik ships the typed view contracts and formatter helpers today. A complete TUI or dashboard is post-MVP scope.

Catalog · 01

Operator surface

The umbrella catalog. Names every operator view, the records it reads, and the formatter helpers Craik ships for rendering them. The contracts are stable enough today that any TUI or dashboard can be built on top without renegotiating with core.

• view contracts
• formatter helpers
• read-only
• dashboard substrate

Read the catalog

Today

Craik has read-only operator view contracts and formatter helpers. A complete TUI or dashboard is post-MVP scope.

— Operator surface · §Intro

1. 02View · graph

   Work graph explorer

   Reads craik.work_graph_export and craik.work_graph_event records. Renders the connected state of tasks, case files, handoffs, receipts, memory proposals, evidence, assumptions, and contradictions.

   Reference
2. 03View · handoff

   Handoff viewer

   Renders one craik.handoff record with its receipts, memory proposals, assumptions, context debt, and self-audit. The default surface for picking up a paused or completed run.

   Reference
3. 04View · receipt

   Receipt viewer

   Renders one craik.capability_receipt with operator, credential, capability, target, reason, result, and the policy envelope that gated it. Joins back to the task and handoff.

   Reference
4. 05View · contradiction

   Contradiction inbox view

   Read-only view over craik.contradiction_report records. Surfaces open contradictions with their evidence, owner, proposed resolution, status, and optional Stigmem conflict id.

   Reference
5. 06View · evidence

   Evidence & assumption view

   Renders craik.evidence_reference and craik.assumption records side by side so a reviewer can tell what was cited from what was guessed.

   Reference
6. 07View · delegation

   Delegation queue view

   Read-only view over craik.human_delegation_point records — the things a run paused on, waiting for a human decision.

   Reference
7. 08View · budget

   Budget & quota view

   Configured limits, observed usage, missing data, exceeded limits, and operator notes for tokens, time, and credentials.

   Reference
8. 09View · quality

   Quality gate view

   Handoff quality scores, evidence coverage, runtime critic findings, and red-team outcomes — every quality signal in one operator panel.

   Reference
9. 10View · delta

   Run delta view

   Continuity-relevant changes since the previous usable handoff or resume point. The "what's new since I was last here?" surface.

   Reference
10. 11View · memory

    Memory impact preview view

    Read-only preview of proposed memory writes before promotion or direct write attempts. Surfaces facts that would be added or invalidated and likely contradictions.

    Reference
11. 12View · memory

    Memory review nudges

    Identifies facts that should be reviewed without directly rewriting memory. Nudges are signals for the reviewer, never autonomous edits.

    Reference
12. 13View · traps

    Known traps view

    Surfaces known traps and negative knowledge — what not to do on this project, with reasons. The institutional memory of failed approaches.

    Reference
13. 14View · preferences

    Preference facts

    Models user and team preferences as reviewable records. Preferences are facts with explicit scope, not implicit settings buried in config.

    Reference
14. 15View · instructions

    Instruction distillation view

    Renders declared instruction sources, observed source snapshots, provenance, and distilled proposals so a reviewer can see where each runtime constraint actually came from.

    Reference
15. 16Workflow · instructions

    Instruction distillation workflow

    Turns declared instruction files into reviewed, provenance-linked runtime constraints. Raw instruction files are evidence — never authority — until distilled through review.

    Workflow
16. 17Registry · instructions

    Instruction sources

    Registries declaring which project files Craik may use for runtime instruction distillation. Craik does not treat every Markdown file as an instruction by default.

    Reference

04

Agents, context & learning

How agents onboard, budget context, and feed back into the runtime.

Fifteen docs cover the agent lifecycle: onboarding, context budgeting and debt, scratchpad rules, exit discipline, knowledge boundaries (traps, freshness, quality), the learning loop, and the multi-agent coordination primitives. Every typed object here is reviewable — nothing rewrites itself silently.

Onboarding · 01

Agent onboarding

craik onboard emits the canonical craik.agent_onboarding payload — project model, policy envelope, docs boundaries, recent handoffs, unresolved contradictions, stale-risk warnings, validation commands, Stigmem backend status, known traps, and allowed next actions.

• onboarding payload
• policy envelope
• continuity context
• safe for runners

Run onboarding

Before any work

Use onboarding before starting project work. The command prints a JSON craik.agent_onboarding report — safe for runners to parse directly.

— Agent onboarding · §Intro

1. 02Guide · context

   Context budgeting

   Case files are bounded. The context budget records what was included and what was omitted — every cut is auditable, every inclusion is justifiable.

   Guide
2. 03Contract · context

   Context debt

   Records preserve known gaps in the context an agent used. Future agents decide whether to continue, refresh, or stop — instead of inheriting silent omissions.

   Reference
3. 04Contract · context

   Scratchpad & unknowns

   Scratchpad records are temporary working notes. They must expire and must not be treated as durable context unless promoted through an explicit review path.

   Reference
4. 05Contract · context

   Context requests & exit discipline

   Structured asks for information needed before work can continue safely. Link to handoffs, recovery sessions, and unresolved delegation points so a stop is never silent.

   Reference
5. 06Contract · knowledge

   Known traps & negative knowledge

   Evidence-backed pitfalls agents should avoid, plus statements about what is not true or not available. Negative knowledge is first-class, not implied by absence.

   Reference
6. 07Contract · knowledge

   Tool attestations & freshness

   Attestations record observed command or tool results with a trust boundary. Freshness probes track when knowledge should be considered fresh, expiring, or stale.

   Reference
7. 08Contract · knowledge

   Quality scores

   Derived review records. They help agents decide whether a handoff or evidence set is ready to rely on — but they are not proof of truth or a substitute for evidence.

   Reference
8. 09Guide · learning

   Learning loops

   Turn observed skill behavior into reviewable improvement records. Loops do not let an agent silently rewrite reusable guidance — proposals route through the skill promotion gates.

   Guide
9. 10Contract · learning

   Learning receipts

   Normal craik.capability_receipt records for self-improvement decisions. Every promotion or rollback is receipted the same way every other governed action is.

   Reference
10. 11Contract · learning

    Training trajectory exports

    Stable review and replay format for self-improvement loops. Exports are deterministic, redacted, and joinable to the runs that produced the trajectory.

    Reference
11. 12Contract · multi-agent

    Cross-agent review

    Lets one specialist role request review from another without collapsing distinct decisions into a single worker result.

    Reference
12. 13Contract · multi-agent

    Structured debates

    Captures bounded multi-agent disagreement without erasing minority positions. Debates are coordination records, not a consensus mechanism.

    Reference
13. 14Contract · multi-agent

    Human delegation & scope changes

    Human delegation points mark places where autonomous agents must stop or hand off instead of continuing silently. The "ask a human" surface is itself a typed object.

    Reference
14. 15Contract · multi-agent

    Runtime critics & red team

    Critic and red-team findings are typed review inputs — not facts, final decisions, or policy overrides — until a separate adjudication accepts them.

    Reference

05

Gateway & channels

Always-on Craik — channels, schedules, webhooks.

Eleven docs cover the gateway surface: the daemon mode, channel ingress contracts, identity pairing, allowlists, policy envelopes for externally-driven runs, webhook validation, scheduled task creation, scheduled automations, and gateway-specific receipts.

Current scope: gateway daemon mode is a foreground local service with /health, pid-file locking, persisted runtime state, webhook validation, and policy-bound channel contracts. The first messaging adapter is still fixture-only (no Slack / Discord / email / SMS yet), and hosted/public dispatch remains post-MVP.

Mode · 01

Gateway daemon mode

The always-on entry point — channels, webhooks, schedules, and policy ingress all hang off this surface. The foreground daemon, health endpoint, pid-file lock, and persisted lifecycle state ship today; hosted dispatch and broad third-party adapters remain future work.

• foreground daemon
• health endpoint
• policy ingress
• post-MVP hosted dispatch

Read gateway mode

Scope today

Gateway daemon mode is foreground and local-first. The production dispatch loop and hosted operation remain post-MVP.

— Gateway daemon · §Intro

1. 02Guide

   Gateway troubleshooting

   Walks the v0.8 gateway surfaces — setup, diagnostics, channels, webhooks, schedules, policies, receipts — and the failure modes that deserve operator attention.

   Guide
2. 03Contract · channel

   Channel adapter contract

   craik.channel_adapter_contract defines the boundary for external operator ingress through always-on gateway channels — the typed surface every adapter implements against.

   Reference
3. 04Adapter · fixture

   Messaging channel adapter

   The first messaging channel adapter is a fixture-only adapter for controlled gateway ingress. Slack, Discord, email, and SMS adapters are explicitly out of scope until daemon mode promotes.

   Reference
4. 05Contract · identity

   Channel identity pairing

   craik.channel_identity_pairing records the relationship between an external channel account and a Craik subject — so receipts can name the human, not just the channel id.

   Reference
5. 06Contract · ingress

   Channel allowlists

   craik.channel_allowlist controls which normalized inbound channel events may continue past the gateway ingress boundary — the "who is allowed to ask" surface.

   Reference
6. 07Policy · ingress

   Channel policy envelopes

   Channel ingress uses normal craik.policy_envelope records — but the selected envelope is intentionally narrower than local operator authority.

   Reference
7. 08Contract · ingress

   Webhook ingress

   Validates one request boundary before any gateway dispatch. Signature, allowlist, payload shape, and identity binding all happen before the runtime sees the request.

   Reference
8. 09Contract · schedule

   Scheduled task creation

   Cron-like gateway schedules convert one schedule tick into one deterministic craik.task_request. Same shape that operator-initiated tasks use.

   Reference
9. 10Contract · schedule

   Scheduled automations

   Enabled gateway definitions backed by cron-like schedules. Each evaluation operates on one observed schedule tick at a time so missed ticks don't pile up into surprise bursts.

   Reference
10. 11Contract · receipt

    Gateway receipts

    Redacted craik.capability_receipt records for always-on service actions — same shape as task-driven receipts, but tagged with the channel and ingress path that produced them.

    Reference

06

Companion apps & visual workspaces

Governed operator surfaces — not autonomous agents.

Six docs cover the decisions and contracts for desktop and mobile companions plus live visual workspaces. Every companion is a governed operator surface over existing work records — it can expose status, review, and explicit operator-triggered actions, but it cannot widen runtime authority on its own.

Security · 01

Companion app security

The umbrella for every companion surface. Companions are read- and review-oriented; they may surface notifications and explicit operator actions but never grant runtime authority or sidestep policy. The security guide is what every desktop / mobile / visual-workspace adapter must implement against.

• read + review
• operator-triggered actions
• no widening of authority
• policy parity

Read the security model

Governed surfaces

Companion app surfaces are governed operator surfaces. They can expose status, review notifications, and explicit operator-triggered actions, but they must not [grant runtime authority on their own].

— Companion app security · §Intro

1. 02Decision · desktop

   Desktop companion

   The desktop companion decision: status, notifications, and controlled actions in a tray-style app — bounded by the same governance the CLI runs under.

   Reference
2. 03Decision · mobile

   Mobile companion

   The mobile companion decision: review notifications and operator-triggered approvals — phone surface focused on review, not edit.

   Reference
3. 04Decision · visual

   Live visual workspace

   Treats visual workspaces and canvases as governed operator surfaces over existing work records. May make work-graph state easier to read; must not silently mutate it.

   Reference
4. 05Bridge · visual

   Work graph visual bridge

   Projects craik.work_graph_export records into portable visual-workspace records. The contract every visual workspace adapter implements against.

   Reference
5. 06A11y

   Accessibility requirements

   Multimodal and companion surfaces must remain usable without relying on a single input mode, visual presentation, or motion pattern. A11y is a contract, not a polish step.

   Reference

07

Multimodal & voice

Audio, image, video — under the same governance.

Four docs cover the contracts for non-text artifacts. Multimodal artifact references travel as typed citations (not embedded media); voice and speech adapters convert between redacted transcripts and referenced artifacts while preserving Craik's policy, evidence, and receipt model.

Contract · 01

Multimodal artifact references

The typed citation surface for audio, image, video, transcript, canvas, document, and other media. Workflows cite media by reference, not by embedded payload — keeps case files, receipts, and handoffs deterministic and redaction-friendly.

• typed citations
• no embedded media
• redaction-friendly
• deterministic

Read the contract

By reference

Multimodal artifact references let Craik workflows cite audio, image, video, transcript, canvas, document, and other media without embedding raw media.

— Multimodal artifacts · §Intro

1. 02Posture · voice

   Voice input & output posture

   Treats voice input and output as governed operator surfaces — not as an always-on assistant layer. Voice is opt-in, scoped, and receipted.

   Reference
2. 03Adapter · STT

   Speech-to-text adapter contract

   Converts referenced audio artifacts into redacted transcripts while preserving Craik's policy, evidence, and receipt model. STT is a boundary, not a passthrough.

   Reference
3. 04Adapter · TTS

   Text-to-speech adapter contract

   Converts redacted text requests into referenced generated speech artifacts while preserving policy, evidence, and receipt model. The inverse of STT, same boundary discipline.

   Reference

08

Translation & locale

Localized docs — without forking the source of truth.

Craik docs start from English source-of-truth pages and use translation metadata to expose localized versions without changing runtime identifiers. Two docs cover the strategy and the framework that implements it.

Strategy · 01

Translated documentation strategy

English pages are the source of truth. Translations live alongside them via translation metadata, so runtime identifiers, command names, and schema names stay stable across locales — only operator-facing prose changes.

• English source-of-truth
• translation metadata
• stable identifiers
• locale-aware prose

Read the strategy

Approach

Craik documentation starts from English source-of-truth pages and uses translation metadata to expose localized docs without changing runtime identifiers.

— Translated docs · §Intro

1. 02Framework · locale

   Locale i18n framework

   Keeps runtime identifiers stable and language-neutral while allowing docs and operator-facing text to resolve through locale preferences and translation metadata.

   Reference

Where to go next

• Build something new → Build
• Govern execution → Secure
• Understand the model → Learn