Quickstart & concepts

Quickstart

1. Install

   lore ships on npm as @salient-data/lore (bin name lore). Run it without installing anything:

   npx @salient-data/lore --help

   To pin it in a project instead, add it as a dev dependency: npm i -D @salient-data/lore or bun add -d @salient-data/lore.

2. Scaffold a bundle

   Run this from the root of a repository:

   npx @salient-data/lore init

   This creates the docs/ OKF bundle (a root index.md plus room for your own concepts) and the .lore/state directory. It’s idempotent — re-running it fills in only whatever is missing and never overwrites an existing file. At an interactive terminal, lore init also offers a short guided wizard for the rest of onboarding (agent bridge, doc-site scaffold, a Backlog.md check); piped or scripted invocations, or any explicit flag, skip straight to the bare scaffold shown above.

3. Verify

   Confirm the new bundle is internally coherent — this is the same command your CI will run as a gate (see The CI gate):

   npx @salient-data/lore check

   On a fresh bundle with nothing linked to Backlog.md yet, this exits 0without needing Backlog.md installed at all — see the Backlog.md prerequisite below.

The six OKF types

Open Knowledge Format defines no closed vocabulary — a concept’s frontmatter just needs a non-empty type.lore supplies one as a producer profile: six typevalues it validates strictly and uses to scaffold new concepts. Anything else still passes through — an unknown type is a warning, never an error.

Epic

A large body of work.Typically links to child Story concepts.

Story

A unit of deliverable behavior.Typically links to Backlog.md task IDs, Spec, and ADR concepts.

Spec

Design or spec for a feature.Typically links to Story, ADR, and code paths.

ADR

An architecture decision record.Typically links to Spec and other ADR concepts.

Runbook

An operational procedure.Typically links to Reference concepts and other resources.

Reference

A stable factual concept — a schema, an API, a metric.Typically links to anything.

Managed blocks

Some regions of a doc are generated, not authored. lore marks them with a visible HTML-comment fence and regenerates everything between the markers on lore sync— for example, the rolled-up task table on a Story:

<!-- lore:tasks:begin -->
| Task | Title | Status |
|---|---|---|
| [task-42](../../backlog/tasks/task-42.md) | Bulk archive | Done |
<!-- lore:tasks:end -->

Hand edits inside a managed block are not protected — the next lore sync overwrites the block wholesale from Backlog data, discarding anything you typed there by design. That is a different case from the denied exit code (4) below: 4 fires when one of lore’s own writes, not a human edit, targets a managed region and is refused. Everything outside the fence is yours; lore never touches it.

Story–to–Task coupling

A Story (or Spec) couples to the Backlog.md tasks that deliver it through two independent references, one per direction:

Doc → task: the Story’s tasks: frontmatter list (tasks: [task-42, task-57]) is the source of truth, edited by lore link / lore unlink or by hand.

Task → doc: the back-reference is a queryable Backlog label, doc:<conceptId>, set by lore linkon the task itself — not a custom frontmatter field, because Backlog.md drops unknown frontmatter keys on edit.

lore syncthen reads each linked task’s live status and reconciles the Story’s authored status to match, rewriting the managed task block at the same time; lore check is the read-only version of that same comparison, reporting drift instead of fixing it.

The Backlog.md prerequisite

A --json-capable Backlog.md on PATH is a hard prerequisite for some commands and irrelevant to others. Stated exactly:

In short: authoring, validating, and navigating the OKF bundle never needs Backlog.md. Coupling a doc to a task, keeping that coupling in sync, and reporting on it do.

Semantic exit codes

Every lore command exits with one of the same six codes, in every output mode, so a script or agent can branch on the exit status alone:

0

success — the command completed, and for a gate, found nothing failing.

2

usage — an unknown flag or command, a malformed argument, a missing required argument.

3

not found — a referenced concept id, task id, file path, or link target doesn’t exist.

4

denied — the operation is refused, such as writing into a managed block.

5

conflict — already exists, or a concurrent-write race.

6

validation or drift — a gate failed: non-conformant OKF (lore validate), or bundle drift, broken links, or portability issues (lore check).

Exit code 1is deliberately never used for an expected condition — it’s reserved for an uncaught, unexpected failure, so a caller can tell “lore told me my input was wrong” (2–6) apart from “lore itself broke” (1).

The CI gate

lore checkis read-only — it never writes — and aggregates status-reconciliation drift, stale managed blocks, broken internal links and heading anchors, and a portability lint, into a single exit code: 0 when the bundle is coherent, 6 when anything above is out of date. That makes it a drop-in CI step:

- run: npx @salient-data/lore check

Pair it with lore validate (per-file OKF conformance, also exit 6on failure) to gate both the shape of each doc and the coherence of the bundle as a whole. Both run against your OKF content alone and don’t require Backlog.md unless your docs link tasks (see the Backlog.md prerequisite).