Project Registry

5 min readFor first-time operatorsUpdated 2026-05-19

What you'll do

Register Git repositories as Craik projects so the runtime can build case files from them. By the end, you'll have one or more projects in the local registry, with mutable doc roots and immutable evidence paths configured.

Project

A Git repository registered into Craik's local store, with its docs boundaries, immutable evidence paths, and (optionally) memory backend configuration declared. Projects are the substrate every task, case file, and handoff hangs off.

Where the registry lives

Project records persist in the local SQLite store at $CRAIK_HOME/state/craik.sqlite. Registration writes only to Craik's home — it never creates a .craik/ directory inside your repository, and it doesn't modify Git config.

Register a project

The shortest form takes a path and infers everything else:

Register the current directory

craik project add .

For anything more than a one-off, declare the docs boundaries explicitly so case files and onboarding payloads carry the right shape:

Register with explicit boundaries

craik project add /path/to/repo \
  --name stigmem \
  --docs-path README.md \
  --docs-path docs/ \
  --immutable-path docs/adr/

Flag

Type

Purpose

--name

string

Stable name used in CLI lookups and case files. Defaults to the repo directory name.

--docs-path

path (repeatable)

Mutable documentation roots an agent may edit under policy.

--immutable-path

path (repeatable)

Evidence paths that should never be normal edit targets — ADRs, decisions, frozen specs.

The mutable/immutable distinction is load-bearing. It's how Craik prevents a "fix the docs" agent from quietly overwriting an ADR.

Inspect what got registered

craik project list

Show every registered project with its id, name, and Git head.

craik project show stigmem

Print the full project_profile JSON — boundaries, paths, memory backend status, validation commands.

craik onboard --project stigmem

Print what an agent sees on first contact: project profile, policy, recent handoffs, open contradictions, allowed next actions.

What gets detected automatically

If you skip explicit flags, Craik scans the repo and recognizes conventional roots:

Mutable docs

README.md, files under docs/, and anything else matching the project's declared doc roots.

Immutable evidence

docs/adr/ by convention. Add others (specs/, rfcs/, etc.) with --immutable-path.

Validation commands

Inferred from the project's configured policy posture. Augment them by adding to project.profile in a later step.

Memory backend

Detected from CRAIK_MEMORY_BACKEND and per-project config. Status is reported by craik onboard without printing credentials.

A multi-project workspace

You can register multiple projects under the same CRAIK_HOME. They live in the same registry and reference the same operator identity but have independent policy posture and validation commands.

Register two projects

craik project add /work/app --name app
craik project add /work/docs --name docs
craik project list

Tasks, case files, receipts, and handoffs are always scoped by project — nothing leaks across.

Unregister a project

Remove from the registry

craik project remove stigmem

This removes the project record and unbinds its tasks. It does not delete receipts or handoffs that already reference the project — those stay queryable for audit.

What's next

DoQuickstartTake a freshly registered project and walk it through a full governed task.ReadThe project modelThe typed object Craik builds from a registered repository.DoUse case filesPatterns for assembling, inspecting, and refreshing the per-task case file.