@opum-ai/lore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Newhouse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# lore
+
+> A thin, OKF-native documentation CLI that couples repo-resident docs to
+> Backlog.md and serves them to coding agents and humans — CLI-first.
+
+`lore` makes your repository's `docs/` tree a first-class, agent-readable
+[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+(OKF v0.1) bundle, couples that bundle to [Backlog.md](https://github.com/MrLesk/Backlog.md)
+tasks, and exposes it through a deterministic, non-interactive CLI. The
+repository is the single source of truth — the bundle is plain markdown with
+YAML frontmatter that renders on GitHub, in Obsidian, and under
+MkDocs/Docusaurus, with or without `lore` installed.
+
+`lore` is **thin** and **zero-config** by design. It does not reimplement
+Backlog.md, Confluence, or the documentation consumers it scaffolds for. Its
+core is **deterministic with no LLM dependency** — every command is
+reproducible, idempotent, and CI/agent-safe (non-interactive by default, stable
+semantic exit codes, machine-readable `--json`).
+
+- Built on **Bun + TypeScript** with an exact-pinned **Commander** parser fed by
+  Lore's capability manifest; Lore still owns output, errors, and process lifecycle.
+- Prepared for npm distribution as **`@opum-ai/lore@0.1.0`** (bin `lore`);
+  registry publication is not claimed until the release-truth evidence lands.
+- The agent bridge is a generated **`.claude/skills/lore/SKILL.md`** plus a tiny
+  CLAUDE.md nudge and `lore instructions`. An **MCP server is secondary and
+  deferred to v2**.
+
+> **Status: prepared 0.1.0 release candidate.** The six manifests and exact
+> optional-dependency pins are set to `0.1.0`, but the repository has no
+> release tag or artifact and `@opum-ai/lore` is absent from npm. The upstream
+> Backlog.md dependency gate is complete
+> (LCLI-253), but the repository-owner publication-control gate remains open
+> (LCLI-278). See [Lore CLI release truth](docs/reference/lore-cli-release-truth.md).
+
+---
+
+## The headline: lore reads Backlog.md via JSON
+
+`lore` couples docs to tasks by reading Backlog.md's **JSON** output — not by
+scraping text and not by importing Backlog.md internals or hand-editing its task
+files. It parses a canonical `{schemaVersion, kind, data}` envelope from
+`backlog task list --json`, `backlog task view --json`, and `backlog search
+--json`. There is **no `--plain` text-parser fallback** — that is a deliberate
+decision to keep the coupling robust.
+
+Backlog.md did not originally ship this JSON surface. It merged upstream in
+MrLesk/Backlog.md as PR #790 and shipped in the v1.49.0 tagged release
+(2026-08-02). `lore` has no package or git dependency on Backlog.md and invokes
+the user-installed `backlog` executable (>=1.49.0) on `PATH`. A capability
+probe enforces the JSON contract and **fails loud** when the installed binary
+cannot provide it.
+
+See the runbook: [Backlog.md `--json` patch](docs/runbooks/backlog-json-patch.md).
+
+Coexistence rules `lore` follows so it never fights Backlog.md:
+
+- Writes go through `backlog task create` / `backlog task edit` — `lore` captures
+  the new id from the `Created task <ID>` line and **never** writes
+  `backlog/tasks/*.md` directly.
+- Back-references live on the task as a queryable label `doc:<conceptId>`
+  (Backlog drops unknown frontmatter on edit, so `lore` never stores its own
+  metadata on tasks).
+- Backlog runs with `auto_commit=false`; `lore` is the **sole committer** of
+  `backlog/` (it does the `git add`/`commit` of task files itself), with
+  `check_active_branches=false` and `remote_operations=false`.
+
+Full details: [Backlog CLI contract](docs/reference/backlog-cli-contract.md) and
+[Backlog JSON schema](docs/reference/backlog-json-schema.md).
+
+---
+
+## Install
+
+`@opum-ai/lore` is not published. Until the release-truth evidence is
+complete, use a trusted source checkout and its pinned toolchain; do not expect
+these planned registry commands to work.
+
+After a verified release, the intended package and bin are
+`@opum-ai/lore` and `lore`:
+
+```bash
+# Node / npm
+npx @opum-ai/lore --help
+
+# Bun
+bunx @opum-ai/lore --help
+```
+
+Or add it to a project:
+
+```bash
+bun add -d @opum-ai/lore   # or: npm i -D @opum-ai/lore
+```
+
+The planned npm package is a dual artifact: a Node `.cjs` launcher plus a
+per-platform compiled binary delivered as `optionalDependencies` (built with
+`bun build --compile`, `-baseline` x64 targets). You also need a
+`--json`-capable Backlog.md (>=1.49.0) on `PATH` — e.g. `npm install -g
+backlog.md`; see the [runbook](docs/runbooks/backlog-json-patch.md).
+
+### Private-repository CI before npm publication
+
+Repositories inside the `opum-ai` organization can run strict Lore gates
+without a cross-repository PAT or a public npm release:
+
+```yaml
+- uses: actions/checkout@v6
+- uses: opum-ai/lore-cli/.github/actions/strict-check@<full-commit-sha>
+```
+
+The private composite action installs Bun 1.2.23 and this action revision's
+frozen dependencies, installs the published JSON-capable `backlog.md` version
+pinned by the Docker E2E harness, then runs `lore validate --strict` and `lore
+check --strict` against the caller workspace. Consumer workflows must replace
+the placeholder with the full immutable commit SHA. Private-action access
+remains limited to organization repositories.
+
+---
+
+## Quickstart (CLI-first)
+
+Every command is idempotent and emits stable exit codes. All of them are
+non-interactive by default — the one exception is `lore init`, which runs a
+guided wizard on a bare, interactive-terminal invocation (detecting and offering
+Claude Code and Codex agent bridges, downstream doc-site scaffolds, and a backlog
+capability check); it is strictly TTY-gated, so a non-TTY stdin or stderr,
+`--json`, or any of its own flags runs it fully non-interactively too — see
+[ADR-0017](docs/adr/0017-interactive-init-wizard-tty-gated.md). Output has
+three modes with precedence `--json` > `--plain` > pretty:
+
+- **pretty** — default; color on a TTY, honoring `NO_COLOR`.
+- **`--plain`** — ANSI-free, stable text; the automatic mode when stdout is not
+  a TTY (pipes, CI, agents).
+- **`--json`** — a `{schemaVersion, kind, data}` envelope on stdout; errors go to
+  stderr as `{error_type, message, hint, input}`.
+
+```bash
+# 1. Scaffold the OKF bundle (docs/, .lore/, root index.md). On a bare TTY
+#    invocation this runs a guided wizard for the rest of onboarding too
+#    (agent bridge, doc-site scaffolds, backlog check); off a TTY (CI, this
+#    snippet) it's exactly this — the bundle only, non-interactively.
+lore init
+
+# 2. Create typed concepts from frontmatter templates.
+lore new story "Bulk archive completed orders"
+lore new spec  "Order archival" --story stories/bulk-archive-completed-orders
+lore new adr   "Use soft deletes"
+
+# 3. Couple a story to Backlog.md tasks (writes frontmatter + a doc:<id> label).
+lore link stories/bulk-archive-completed-orders task-42 task-57
+
+# 4. Reconcile status and rewrite the managed task block from live JSON.
+lore sync
+
+# 5. CI gate: report drift / broken links / portability issues (no writes).
+lore check
+
+# 6. Retrieve: full-text search and deterministic graph-context export.
+lore query "archive retention" --type story
+lore context stories/bulk-archive-completed-orders --max-tokens 4000
+```
+
+`--plain` is stable, line-oriented text — ideal for pipes and grep:
+
+```bash
+$ lore tasks stories/bulk-archive-completed-orders --plain
+task-42  Bulk archive          Done
+task-57  Archive UI            In Progress
+```
+
+`--json` is the additive-only machine contract:
+
+```bash
+$ lore check --json
+{
+  "schemaVersion": "1",
+  "kind": "check.report",
+  "data": {
+    "ok": false,
+    "drift": [
+      { "concept": "stories/bulk-archive-completed-orders",
+        "field": "status", "have": "todo", "want": "in-progress" }
+    ],
+    "brokenLinks": [],
+    "portability": []
+  }
+}
+```
+
+```bash
+$ lore validate --json && echo "conformant"   # exit 6 on validation/drift
+```
+
+Semantic exit codes (uniform across commands): `0` ok, `2` usage, `3`
+not-found, `4` denied, `5` conflict/exists, `6` validation-or-drift. See the
+[CLI contract](docs/reference/cli-contract.md) for the full output and exit-code
+spec, and the [CLI surface](docs/reference/cli-surface.md) for every command and
+flag.
+
+### Refactoring and navigation
+
+```bash
+lore graph --json                     # cross-link graph + token estimates
+lore graph --dot                      # Graphviz DOT
+lore export > lore-projection.jsonl   # full consumer-neutral OKF/task projection
+lore orphans                          # tasks with no owning doc; docs whose tasks vanished
+lore replace "OldName" "NewName" --in 'reference/**' --dry-run
+lore rename reference/orders reference/order-lines   # graph-aware: rewrites inbound links
+lore supersede adr/0004-foo adr/0009-bar             # sets superseded_by/supersedes/status
+```
+
+`replace` skips `lore`-managed regions; `rename`/`supersede` use the bundle
+graph to rewrite all inbound links and frontmatter refs.
+
+---
+
+## How coding agents use lore
+
+`lore` is CLI-first for humans **and** agents. Its agent bridges are generated,
+not bespoke:
+
+- `lore agents` emits `.claude/skills/lore/SKILL.md` — a skill that teaches
+  Claude Code when and how to drive `lore` (always with `--json` for
+  structured results).
+- `lore init --codex` emits `.codex/skills/lore/SKILL.md`; a managed block in
+  `AGENTS.md` points Codex at that skill without overwriting repository guidance.
+- A tiny managed block in `CLAUDE.md` points Claude Code at its skill.
+- `lore instructions` prints task-shaped guidance on demand for any agent or
+  human.
+
+An agent's typical loop: read `lore context <id> --json` to pull a concept plus
+1-line neighbor summaries within a token budget, do the work, then run
+`lore sync` and `lore check --json` to keep docs coherent — all deterministic,
+all without an LLM in `lore`'s core.
+
+See [Agent onboarding](docs/runbooks/agent-onboarding.md).
+
+---
+
+## One bundle, many consumers
+
+`docs/` is a valid OKF v0.1 bundle on its own. To keep it portable across
+renderers, every cross-link is **relative, URL-encoded, `.md`-suffixed, with no
+leading slash and no wikilinks** — the only form that resolves identically on
+**GitHub**, in **Obsidian** (graph + backlinks), under **MkDocs**, and under
+**Docusaurus**. `lore`'s portability lint warns on non-portable syntax.
+
+`lore scaffold` writes consumer configs **additively, outside `docs/`** so the
+bundle stays clean:
+
+```bash
+lore scaffold mkdocs        # mkdocs.yml
+lore scaffold docusaurus    # docusaurus.config + markdown.format:'detect'
+lore scaffold obsidian      # .obsidian/ vault config
+```
+
+A **one-way Confluence publish** adapter (Cloud/ADF) is planned as an isolated
+module with zero core dependency, but its **implementation is deferred**
+(Server/DC is deferred-not-dropped). See
+[Consumer compatibility](docs/reference/consumer-compatibility.md) and
+[Portable Markdown](docs/reference/portable-markdown.md).
+
+---
+
+## Roadmap
+
+Tracked as Backlog.md milestones, built in order:
+
+| Milestone | Scope |
+|---|---|
+| **BJP** | Upstream stable JSON for Backlog.md reads (completed in PR #790; tagged-release adoption gates lore 0.1) |
+| **M0** | Foundations: repo, runtime pin, build/distribution skeleton |
+| **M1** | Core + scaffolding: `init`, `new`, `validate`, concept/frontmatter lib (gray-matter + Zod), bundle walk |
+| **M2** | Backlog coupling: `link`, `sync`, `check`, managed block (remark), status reconciliation |
+| **M3** | Navigability, search & refactoring: `graph`, `orphans`, `query`, `context`, `replace`, `rename`, `supersede` |
+| **M4** | Agent bridge: generated `SKILL.md`, CLAUDE.md nudge, `lore instructions` |
+| **M5** | Browsable + graph consumers: `lore scaffold` for MkDocs/Docusaurus/Obsidian |
+| _M6 (deferred)_ | MCP server — same core functions over a deferred transport |
+| _M7–M8 (deferred)_ | Confluence: one-way publish, then mirror |
+
+---
+
+## Documentation
+
+The full design lives in this repo's OKF bundle under [`docs/`](docs/index.md):
+
+- [Documentation index](docs/index.md) — the OKF root and reading hub.
+- [Architecture](docs/reference/architecture.md) — the deterministic-core /
+  thin-transport shape.
+- [lore design spec](docs/specs/lore-design.md) — the end-to-end design.
+- [CLI surface](docs/reference/cli-surface.md) and
+  [CLI contract](docs/reference/cli-contract.md).
+- [ADRs](docs/adr/index.md) — the significant, hard-to-reverse decisions.
+- [MCP tools (deferred)](docs/reference/mcp-tools.md) — the v2 MCP design.
+
+---
+
+## Contributing
+
+This is a private repo (`main` + `dev`; `dev` is the default branch). See
+[CONTRIBUTING](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md), and
+[SECURITY](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Jeremy Newhouse.

package/bin/lore.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * bin/lore.cjs — the published package's future `bin` entry (ADR-0001 §"Distribution", LORE-9).
+ *
+ * This is the ONLY file that runs under plain Node rather than Bun: it is what makes
+ * `npx @opum-ai/lore` / a global `npm install -g` work for a user who has Node
+ * but not Bun. Its entire job is to locate the compiled binary for the current
+ * platform (installed as one of the package's `optionalDependencies`, gated by npm's
+ * `os`/`cpu` fields so only the matching one lands in `node_modules`) and exec it,
+ * forwarding argv/stdio/exit code verbatim.
+ *
+ * NOT YET the active `bin` target: `package.json`'s `bin.lore` still points at
+ * `src/cli.ts` (the pre-publish install path — git dependency, `npm`/`bun link`), because
+ * this file only works once the five platform packages it resolves are actually published.
+ * Flipping `bin.lore` to this file is the first step of cutting a real release, not a
+ * standing state — see docs/runbooks/release-publishing.md.
+ *
+ * Kept deliberately tiny and dependency-free plain CommonJS (`.cjs`, so it runs as
+ * CJS regardless of the package's own `"type": "module"`) — per ADR-0001, "the
+ * launcher must stay plain, dependency-light, Node-compatible CJS: it cannot use
+ * Bun-only APIs." All of lore's actual logic lives in the compiled binary; this file
+ * never imports `src/`.
+ */
+
+const { spawnSync } = require("node:child_process");
+const os = require("node:os");
+const path = require("node:path");
+
+/** The compiled binary's name inside its platform package (`.exe` on Windows). */
+const BINARY_NAME = process.platform === "win32" ? "lore.exe" : "lore";
+
+/**
+ * The `optionalDependencies` package name for the current platform, matching
+ * `process.platform`/`process.arch` directly (`darwin-arm64`, `linux-x64`, …) so the
+ * mapping needs no lookup table — it must stay byte-identical to the `npm/<name>/`
+ * directories this repo publishes from and to `package.json`'s `optionalDependencies`.
+ */
+function platformPackageName() {
+  return `@opum-ai/lore-${process.platform}-${process.arch}`;
+}
+
+/**
+ * Resolve the absolute path to the current platform's compiled binary, or `null` when its
+ * optional package genuinely never installed (npm skips `optionalDependencies` whose `os`/`cpu`
+ * don't match the host). Only `require.resolve`'s own `MODULE_NOT_FOUND` is treated as "not
+ * installed" — any other thrown error (a permission error reading the package directory, a
+ * corrupted install, `ERR_PACKAGE_PATH_NOT_EXPORTED`, …) propagates to the caller instead of
+ * being silently folded into the same "unsupported platform" message, which would misdirect a
+ * user with a real, fixable install problem.
+ */
+function resolveBinaryPath() {
+  const pkgName = platformPackageName();
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+  } catch (err) {
+    if (err && err.code === "MODULE_NOT_FOUND") {
+      return null;
+    }
+    throw err;
+  }
+  return path.join(path.dirname(pkgJsonPath), "bin", BINARY_NAME);
+}
+
+/**
+ * The exit code to forward for a `spawnSync` result with no exit `status` (i.e. the child was
+ * terminated by a signal, `result.signal` set). Uses the conventional `128 + signal number`
+ * (matching a POSIX shell) so a caller inspecting `$?` — e.g. to tell a user's Ctrl-C (SIGINT,
+ * conventionally 130) apart from a genuine tool failure — sees the real signal, not a generic 1.
+ * Falls back to `1` only if the signal name is somehow unrecognized (`os.constants.signals` has
+ * no entry for it), which should not happen for any signal Node itself can report.
+ */
+function exitCodeForSignal(signal) {
+  const signalNumber = os.constants.signals[signal];
+  return signalNumber === undefined ? 1 : 128 + signalNumber;
+}
+
+function main() {
+  let binaryPath;
+  try {
+    binaryPath = resolveBinaryPath();
+  } catch (err) {
+    process.stderr.write(
+      `lore: unexpected error resolving the compiled binary for ${platformPackageName()}: ${err.message}\n`,
+    );
+    process.exit(1);
+  }
+  if (binaryPath === null) {
+    process.stderr.write(
+      `lore: no compiled binary found for this platform (${process.platform}-${process.arch}).\n` +
+        `Expected the optional dependency "${platformPackageName()}" to be installed alongside\n` +
+        `@opum-ai/lore, but it is missing. If your platform/architecture is one lore\n` +
+        `ships (macOS x64/arm64, Linux x64/arm64, Windows x64), try reinstalling with npm;\n` +
+        `otherwise this platform is not yet supported.\n`,
+    );
+    process.exit(1);
+  }
+
+  const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) {
+    process.stderr.write(`lore: failed to run the compiled binary at ${binaryPath}: ${result.error.message}\n`);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? exitCodeForSignal(result.signal) : result.status);
+}
+
+main();

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@opum-ai/lore",
+  "version": "0.1.0",
+  "description": "Thin, OKF-native documentation CLI that couples repo-resident docs to Backlog.md and serves them to agents and humans.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "module": "src/cli.ts",
+  "bin": {
+    "lore": "bin/lore.cjs"
+  },
+  "license": "MIT",
+  "author": "Jeremy Newhouse",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opum-ai/lore-cli.git"
+  },
+  "packageManager": "bun@1.2.23",
+  "engines": {
+    "bun": ">=1.2.23"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "optionalDependencies": {
+    "@opum-ai/lore-darwin-arm64": "0.1.0",
+    "@opum-ai/lore-darwin-x64": "0.1.0",
+    "@opum-ai/lore-linux-arm64": "0.1.0",
+    "@opum-ai/lore-linux-x64": "0.1.0",
+    "@opum-ai/lore-win32-x64": "0.1.0"
+  },
+  "scripts": {
+    "lore": "bun run src/cli.ts",
+    "build": "bun build --compile src/cli.ts --outfile dist/lore",
+    "typecheck": "tsc --noEmit",
+    "format": "biome format --write .",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "bun test",
+    "test:browser": "playwright test",
+    "test:coverage": "bun test --coverage"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.12",
+    "@playwright/test": "1.62.1",
+    "@types/bun": "^1.2.23",
+    "@types/mdast": "4.0.4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@ladybugdb/core": "0.19.0",
+    "commander": "15.0.0",
+    "github-slugger": "2.0.0",
+    "ipaddr.js": "2.4.0",
+    "js-yaml": "5.2.2",
+    "mdast-util-from-markdown": "2.0.3",
+    "string-width": "8.2.2",
+    "zod": "4.4.3"
+  },
+  "trustedDependencies": [
+    "@ladybugdb/core"
+  ]
+}