loaf-reference

name

loaf-reference

description

Documents how agents operate the Loaf CLI: command discovery via loaf --help, JSON diagnosis surfaces, config-aware maintenance, and troubleshooting. Use when unsure which loaf command to invoke, how to validate project state, or when asked to upgrade, diagnose, repair, configure, or bring a Loaf project current. Not for workflow guidance (workflow skills own their CLI contracts) or build internals.

Loaf Reference

Contents

• Operating Rules
• Journal Context (contract v2)
• Command Index
• Topics

The Loaf operating manual for agents: how to discover commands, diagnose project state, and keep configuration current. It teaches reading the CLI, not memorizing it.

Note: This file is auto-generated from native CLI reference metadata. Do not edit manually.

Operating Rules

• Get exact, current syntax live: loaf --help lists every command, loaf <command> --help details one. This index is a map, not the contract.
• Prefer --json surfaces when diagnosing: loaf config check --json, loaf state doctor --json. Parse the structured output instead of scraping human-readable text.
• Run the deterministic CLI command before hand-editing anything it manages; the command owns its files.
• Use --fix only for safe, mechanical repairs, and review what it changed.
• Ask the user for project-owned choices — GitHub account, issue identity (authority and prefix), tracker or integration election, which harnesses to install — never guess them.
• Never hand-edit Loaf-managed hook files; regenerate them through loaf build and loaf install.
• Re-run the relevant check after any change and confirm it passes.
• Log meaningful decisions to the journal: loaf journal log "decision(scope): ...".

Journal Context (contract v2)

loaf journal context is an active-truth read model, not the former latest-arbitrary-wrap plus branch entries plus open tasks summary. Consume its named layers and diagnostics rather than inferring state from an omitted layer.

Layer	Truth it supplies
project-synthesis	The latest wrap(project) synthesis.
scoped-checkpoint	The latest non-project wrap, only when no project synthesis exists; it is explicitly labeled as a fallback.
active-lineage	Journal evidence associated with active Change lineage.
unresolved-blockers	Blocks that do not have a later exact-scope unblock.
deferred-intent	Open deferred-intent decision and spark pairs.
active-changes	Git-derived active Change evidence and worktree state.
branch-recency	Recent entries on the selected branch after entries already surfaced as active truth are removed.
transitional-tasks	Open task-board records retained for compatibility.

Each layer reports source_available, available_count, shown_count, truncated, and an exact expand_command; paginated layers also return a cursor. source_available: false means the source could not be derived and is not an empty result. In particular, an unavailable Change source marks both active-changes and active-lineage unavailable and emits a diagnostic.

Use --branch to select branch-recency scope and bind state cursors. It does not override active Change provenance or reasons, which always use the actual Git branch. Use --layer to request one canonical layer. --limit accepts 1 through 100 only with --layer; --cursor also requires --layer and cannot expand the intrinsic one-item project-synthesis or scoped-checkpoint layers. Reuse the returned expand_command verbatim: cursors are bound to their layer, project, branch, snapshot, and limit. --json is the stable machine surface; human output retains the same counts, unavailable markers, and expansion command.

Command Index

Names and one-line purposes only. Run loaf <command> --help for options, arguments, and current usage.

Command	Purpose	Subcommands
loaf build	Build skill distributions for agent harnesses	—
loaf install	Onboard Loaf into a folder or a not-yet-installed AI tool configuration	—
loaf upgrade	Refresh Loaf in place: harness content sync plus deprecation cleanup anywhere, and project-surface refresh only inside a detected Loaf repo	—
loaf config	Validate and refresh project Loaf config	check
loaf hooks	Inspect and set which Loaf hooks project into an installed harness's hooks file	list, enable, disable
loaf init	Initialize a project with Loaf structure	—
loaf release	Cut a retroactive release from already-landed work	suggest, cut
loaf search	Search SQLite artifact bodies, journal entries, and indexed docs	—
loaf docs	Manage docs/ indexing	index
loaf render	Maintain committed durable Markdown renders	sweep
loaf state	Manage native SQLite state	path, status, init, doctor, repair legacy-project-database, repair relationship-origin, repair journal-search, migrate markdown, migrate storage-home, migrate schema, migrate deferrals, migrate lifecycle-statuses, migrate alias-orphans, migrate journal-duplicates, migrate journal-first, backup, backup verify, backup restore, restore-ephemerals, verify-ephemerals, export, export all, export triage, export spec, export release-readiness
loaf journal	Record and read the project-scoped journal (the durable record across all conversations)	log, recent, search, show, context, export, defer
loaf project	Manage durable project identity	list, show, identity, rename, move, delete
loaf migrate	Run native migration workflows	markdown, storage-home, schema, lifecycle-statuses, journal-first, worktree-storage

Topics

Topic	Reference	Use When
Configuration maintenance	references/configuration.md	Checking whether a project's Loaf config is current and repairing it; wiring project-owned choices
Config-aware maintenance protocol	references/maintenance.md	Upgrading, diagnosing, repairing, or bringing a project current: diagnose, plan, ask, apply, verify
Command routing	references/command-routing.md	Deciding which command a task needs; locating the JSON diagnosis surfaces
Markdown migration	references/markdown-migration.md	Running loaf migrate markdown: simulation vs inventory mode, import_report, origin/status authority
Troubleshooting	references/troubleshooting.md	Diagnosing state, config, or alignment failures; isolating a throwaway database