Lore CLIOpen Knowledge Format v0.1MIT licensed
Your agent shouldn’t have to guess how your system works.
The Lore CLI turns the docs already in your repository into a typed, validated knowledge graph your coding agent can query. Deterministic, with no LLM in the core — same repo, same answer, every time.
npx @salient-data/lore initPre-1.0 and under active development — no tagged release yet. See what’s landed so far.
Runs on Node, via npx. No global install required. Read the quickstart → · View on GitHub
Obsidian, MkDocs, and GitHub each read this file directly. None of them need lore installed.
One file, three renderings
Identity constant, view variable.
One real OKF concept, unedited, rendered three ways: as authored markdown with frontmatter, as a linked graph, and as a terminal query result.
Storystories/onboard-private-beta-users
Guide entitled users from sign-in through repository readiness and MCP connection.
---
type: Story
title: Onboard private-beta users
tags:
- onboarding
- github
- mcp
summary: Guide entitled users from sign-in through repository readiness and MCP connection.
timestamp: 2026-07-29T02:19:25.851Z
status: done
tasks:
- lweb-1
---
# Onboard private-beta users
## Goal
Give an entitled design partner a clear path from Clerk sign-in to one personal
project, GitHub App connection, selection of up to three repositories,
synchronization readiness, and Claude/Codex MCP connection.
## Acceptance criteria
1. Authentication and privileged API calls stay server-side and the first
entitled visit creates exactly one editable personal project.
2. Only installation-authorized default-branch repositories are selectable,
with a hard limit of three.
3. Entitlement-denied, disconnected, empty, queued, active, ready,
partial-failure, revoked, and deletion states are explicit and accessible.
4. Active syncs poll every three seconds, stop on terminal state, and expose
manual retry only for actionable failures.
5. Responsive tested guidance connects Claude and Codex to
`mcp.loregraph.dev` without exposing credentials.
## Tasks
<!-- lore:tasks:begin -->
| Task | Title | Status |
|---|---|---|
| [LWEB-1](../../backlog/tasks/lweb-1%20-%20Build-beta-onboarding-and-repository-synchronization-UI.md) | Build beta onboarding and repository synchronization UI | Done |
<!-- lore:tasks:end -->
## Notes
See [Beta onboarding experience](../specs/beta-onboarding-experience.md). The
web app renders `lore-api` state and never owns entitlement decisions,
ingestion, graph access, or MCP transport.
$ lore query --type Story --tag onboarding
query (filters): 1 match
stories/onboard-private-beta-users [Story] — Guide entitled users from sign-in through repository readiness and MCP connection.Drift is the failure mode. check detects it, sync repairs it.
The problem
Docs drift away from the work, and your agent is the last to know.
By the time a decision matters, the file explaining it is months stale and nothing says so. An agent asked to change that system has two options: read the entire docs/ tree and burn the context window, or skip it and guess.
lore types the tree instead. Every file declares what it is, what it links to, and which tasks it owns — so retrieval is exact rather than approximate, and drift becomes something CI can fail on.
No LLM anywhere on this path. Same repo in, same bytes out.
The mechanism
Four parts, pulled apart.
Nothing here is inferred. Each stage is a pure function of the one before it, which is why the same repository always produces the same answer and the same exit code.
- You write the markdown. lore scaffolds and validates, but never authors prose.
- Frontmatter types it.
typeis the only field OKF requires. - Relative links become edges.
lore renamerepoints every inbound one. - Retrieval stays bounded.
lore contextfills a token budget and stops.
Unknown types still validate — leniently, with a warning. The bundle degrades; it doesn’t break.
The vocabulary
Six types. Closed set, strictly validated.
OKF itself defines no closed vocabulary — a concept only needs a non-empty type. lore supplies one as a producer profile: six values it validates strictly and scaffolds from templates. An unknown type still passes, with a warning.
A large body of work. Parents a set of Stories.
A unit of deliverable behaviour. Owns Backlog.md task ids.
Feature design, written before the work.
A decision, its context, and what it cost.
An operational procedure someone follows under pressure.
A stable fact: a schema, a contract, a metric.
21 commands in total. These six carry most of the work.
What it does
lore writes the mechanical parts. You write the prose.
Everything between the markers below is machine-owned — lore rewrites it from live repository state every time you run lore sync. Everything outside a managed block is yours, and lore never touches it. That line is the product.
lore init
Scaffold the OKF bundle. A bare, interactive run also wizards the agent bridge, doc-site scaffolds, and a Backlog.md check.
lore check
Validate links, anchors, and status drift across the bundle — the CI gate. A bundle out of date exits 6. Add --strict to also fail on portability warnings.
lore rename
Move a concept and repoint every inbound link and reference across the bundle.
lore link
Couple a Story to its Backlog.md task ids, writing the back-reference on the task too.
lore context
Assemble a concept and its neighbours inside a token budget.
lore graph
Emit the bundle’s cross-link graph as JSON or DOT.
Twenty-one commands in all. Authoring, validation, graph, query, context, and scaffold work standalone. link, unlink, sync, tasks, orphans, and the drift tier of check are the ones that need a --json-capable Backlog.md on PATH — see the Backlog.md prerequisite for the exact split.
Full command reference, source, and issues: github.com/salient-data/lore-cli.
No MCP server ships with the CLI. Figures recorded in ADR-0004.
Agent integration
A command line, not an MCP server.
Registering an MCP server injects its full tool and resource schemas into every turn, whether or not a tool is called. lore doesn’t ship one: the CLI is the agent surface, bridged by a generated SKILL.md plus lore instructions, which cost almost nothing and cover nearly the same ground.
Figures recorded in ADR-0004, alongside a 2026 benchmark that found a CLI completing agent tasks in roughly a tenth of the tokens an equivalent MCP path used. Local MCP is on hold; a separate hosted MCP endpoint exists only inside the private beta below. The bundle itself still renders on GitHub, in Obsidian, and under MkDocs or Docusaurus, with or without lore installed.
Access is admin-assigned. No checkout, no self-serve tier.
Hosted Lore · private beta
The CLI is free and local. The hosted platform is invite-only.
Hosted Lore keeps a project in sync across up to three repositories and serves it to Claude and Codex over a remote, project-scoped endpoint, with the same provenance the CLI attaches locally. There’s no self-serve signup, and joining the waitlist doesn’t grant access. Read more about Hosted Lore.