barry-cache 0.2.2 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # Barry Cache
 
 <p align="center">
-  <img src="assets/barry-cache.png" alt="Barry Cache" width="420">
+  <img src="https://unpkg.com/barry-cache@latest/assets/barry-cache.png" alt="Barry Cache" width="420">
 </p>
 
 Barry Cache remembers your repo.
@@ -72,7 +72,7 @@ Checks whether the repo context is structurally valid.
 barry-cache validate
 ```
 
-It verifies required context files exist and validates every fact row in `docs/context/features/*/FACTS.jsonl`.
+It verifies required context files, ADR frontmatter, and every fact row in `docs/context/features/*/FACTS.jsonl`.
 
 Use this after editing context files, importing memory, or before committing Barry Cache changes.
 
@@ -100,13 +100,13 @@ Use this when deciding which context pack an agent should load before doing work
 
 ### `barry-cache search`
 
-Searches feature packs and facts for a query.
+Searches feature packs, facts, and ADRs for a query.
 
 ```bash
 barry-cache search --query "transport clock"
 ```
 
-It returns matching feature packs and fact records with route, score, source, and text.
+It returns matching feature packs, fact records, and ADR records with route, score, source, and text.
 
 Use this when you know a term, file, component, or concept and want to find the relevant memory.
 
@@ -118,7 +118,7 @@ Loads one feature context pack.
 barry-cache load --route renderer-runtime
 ```
 
-It returns the feature README, facts, and source file list for `docs/context/features/<route>/`.
+It returns the feature README, facts, linked ADRs, and source file list for `docs/context/features/<route>/`.
 
 Use this after `route` or `search` selects a specific feature.
 
@@ -156,6 +156,33 @@ Statuses:
 - `blocked`: the task cannot proceed without external input.
 - `failed`: the attempted approach did not work.
 
+### `barry-cache adr`
+
+Creates and lists architecture decision records.
+
+```bash
+barry-cache adr new --title "Use repo-native context"
+barry-cache adr new --title "Keep generated indexes disposable" --tags context,cache
+barry-cache adr list
+```
+
+ADRs live in `docs/context/adrs/` as Markdown files with frontmatter. Use them for durable architectural decisions, then reference the ADR file from decision facts with `src`.
+
+```json
+{
+  "id": "CTX001",
+  "subject": "Barry",
+  "predicate": "stores canonical context in",
+  "object": "docs/context/",
+  "src": ["docs/context/adrs/ADR-0001-use-repo-native-context.md"],
+  "status": "active",
+  "kind": "decision",
+  "updated_at": "2026-05-19"
+}
+```
+
+Barry can then search the ADR, route tasks through feature facts linked to it, load it with the relevant feature pack, and show it in review data.
+
 ### `barry-cache review`
 
 Opens a local browser tool for inspecting memory.
@@ -228,6 +255,12 @@ npx barry-cache init
 
 After this, Barry Cache writes short instructions into agent-facing files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/barry-cache.mdc`, and `.github/copilot-instructions.md`.
 
+When a package manager is detected, those instructions use the repo package script instead of assuming `barry-cache` is on `PATH`. For a Bun repo, agents are told to run commands like:
+
+```bash
+bun run barry -- resume --task "fix playback drift in the editor"
+```
+
 For a Codex-only repo, use:
 
 ```bash
@@ -238,7 +271,7 @@ Those generated files tell coding agents how to use Barry before they edit the r
 
 ### Ask An Agent To Work On A Task
 
-Usually, you do not need to run `barry-cache resume` yourself.
+Usually, you do not need to run Barry yourself.
 
 Ask your coding agent normally:
 
@@ -249,13 +282,15 @@ Fix playback drift in the editor.
 Because `barry-cache init` added instructions to the repo, the agent should run this before non-trivial work:
 
 ```bash
-barry-cache resume --task "fix playback drift in the editor"
+bun run barry -- resume --task "fix playback drift in the editor"
 ```
 
+The generated instruction file uses the package manager Barry detected for that repo, for example `bun`, `npm`, `pnpm`, or `yarn`.
+
 The agent then uses the returned routes to load focused context:
 
 ```bash
-barry-cache load --route editor-media-runtime
+bun run barry -- load --route editor-media-runtime
 ```
 
 This keeps the agent from reading every context file in the repo.
@@ -264,7 +299,7 @@ If an agent ignores the repo instructions, prompt it explicitly:
 
 ```text
 Before editing, follow Barry Cache protocol:
-1. Run barry-cache resume --task "<my task>".
+1. Run the repo's Barry package script, for example bun run barry -- resume --task "<my task>".
 2. Load the returned route context.
 3. Do the work.
 4. Run validation.
@@ -287,6 +322,16 @@ Use the browser review tool for a broader overview:
 barry-cache review
 ```
 
+### Record An Architectural Decision
+
+Create an ADR when a decision explains why future agents should preserve or intentionally change architecture:
+
+```bash
+barry-cache adr new --title "Use repo-native context" --tags context,agents
+```
+
+Then add or update a `kind: "decision"` fact in the relevant feature pack and point `src` to the ADR file. That keeps the human-readable reasoning and the machine-routable fact connected.
+
 ### Save Agent Sessions
 
 At the end of a meaningful session, ask the agent:

package/dist/cli.js

@@ -2,9 +2,9 @@
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
-// src/core/context.ts
-import { appendFile, mkdir as mkdir2 } from "node:fs/promises";
-import { basename, join as join3 } from "node:path";
+// src/core/adr.ts
+import { readdir as readdir2 } from "node:fs/promises";
+import { basename, join as join2 } from "node:path";
 
 // src/core/fs.ts
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
@@ -50,8 +50,223 @@ function repoPath(repo, ...parts) {
   return join(repo, ...parts);
 }
 
+// src/core/adr.ts
+var adrStatuses = ["active", "superseded", "deprecated"];
+async function createAdr(options) {
+  const title = options.title.trim();
+  if (title.length === 0)
+    throw new Error("ADR title is required");
+  const status = options.status ?? "active";
+  if (!isAdrStatus(status))
+    throw new Error(`invalid ADR status: ${status}`);
+  const existing = await listAdrFiles(options.repo);
+  const id = nextAdrId(existing);
+  const path = `docs/context/adrs/${id}-${slug(title)}.md`;
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const content = formatAdr({
+    id,
+    title,
+    status,
+    date,
+    supersedes: options.supersedes ?? [],
+    tags: options.tags ?? []
+  });
+  await writeText(repoPath(options.repo, path), content);
+  return {
+    id,
+    title,
+    status,
+    date,
+    supersedes: options.supersedes ?? [],
+    tags: options.tags ?? [],
+    path,
+    content
+  };
+}
+async function listAdrs({ repo }) {
+  const catalog = await readAdrCatalog(repo);
+  return catalog.adrs;
+}
+async function readAdrCatalog(repo) {
+  const files = await listAdrFiles(repo);
+  const adrs = [];
+  const errors = [];
+  for (const path of files) {
+    const absolute = repoPath(repo, path);
+    const content = await readText(absolute);
+    const parsed = parseAdr(repo, path, content);
+    if (parsed.record)
+      adrs.push(parsed.record);
+    errors.push(...parsed.errors);
+  }
+  adrs.sort((a, b) => a.id.localeCompare(b.id));
+  errors.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0));
+  return { adrs, errors };
+}
+function linkedAdrsForSources(sources, adrs) {
+  const linked = new Map;
+  for (const source of sources) {
+    for (const adr of adrs) {
+      if (adrMatchesSource(adr, source))
+        linked.set(adr.id, adr);
+    }
+  }
+  return [...linked.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function adrMatchesSource(adr, source) {
+  const normalized = source.split("#")[0] ?? source;
+  const filename = basename(adr.path);
+  return normalized === adr.id || normalized === adr.path || normalized === filename || normalized.endsWith(`/${filename}`);
+}
+function looksLikeAdrSource(source) {
+  const normalized = source.split("#")[0] ?? source;
+  return /^ADR-\d{4}\b/.test(normalized) || /(?:^|\/)ADR-\d{4}-.+\.md$/.test(normalized) || normalized.startsWith("docs/context/adrs/");
+}
+function adrToText(adr) {
+  return [
+    adr.id,
+    adr.title,
+    adr.status,
+    adr.date,
+    ...adr.tags,
+    ...adr.supersedes,
+    adr.content
+  ].join(" ");
+}
+async function listAdrFiles(repo) {
+  const dir = repoPath(repo, "docs/context/adrs");
+  if (!await exists(dir))
+    return [];
+  const entries = await readdir2(dir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && /^ADR-\d{4}-.+\.md$/.test(entry.name)).map((entry) => rel(repo, join2(dir, entry.name))).sort();
+}
+function parseAdr(repo, path, content) {
+  const errors = [];
+  const frontmatter = parseFrontmatter(path, content);
+  if (!frontmatter.data)
+    return { errors: [frontmatter.error] };
+  const id = stringField(frontmatter.data, "id");
+  const title = stringField(frontmatter.data, "title");
+  const status = stringField(frontmatter.data, "status");
+  const date = stringField(frontmatter.data, "date");
+  const supersedes = arrayField(frontmatter.data, "supersedes");
+  const tags = arrayField(frontmatter.data, "tags");
+  if (!id)
+    errors.push({ file: path, message: "missing ADR field: id" });
+  if (!title)
+    errors.push({ file: path, message: "missing ADR field: title" });
+  if (!status)
+    errors.push({ file: path, message: "missing ADR field: status" });
+  if (!date)
+    errors.push({ file: path, message: "missing ADR field: date" });
+  if (id && !/^ADR-\d{4}$/.test(id))
+    errors.push({ file: path, message: `invalid ADR id: ${id}` });
+  if (id && !basename(path).startsWith(`${id}-`))
+    errors.push({ file: path, message: "ADR id does not match filename" });
+  if (status && !isAdrStatus(status))
+    errors.push({ file: path, message: `invalid ADR status: ${status}` });
+  if (date && !/^\d{4}-\d{2}-\d{2}$/.test(date))
+    errors.push({ file: path, message: `invalid ADR date: ${date}` });
+  if (errors.length > 0 || !id || !title || !status || !date || !isAdrStatus(status))
+    return { errors };
+  return {
+    record: {
+      id,
+      title,
+      status,
+      date,
+      supersedes,
+      tags,
+      path: rel(repo, repoPath(repo, path)),
+      content
+    },
+    errors
+  };
+}
+function parseFrontmatter(path, content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== "---")
+    return { error: { file: path, line: 1, message: "ADR frontmatter is missing" } };
+  const end = lines.findIndex((line, index) => index > 0 && line === "---");
+  if (end < 0)
+    return { error: { file: path, line: 1, message: "ADR frontmatter is not closed" } };
+  const data = new Map;
+  for (let index = 1;index < end; index++) {
+    const line = lines[index]?.trim() ?? "";
+    if (line.length === 0)
+      continue;
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match || !match[1]) {
+      return { error: { file: path, line: index + 1, message: "invalid ADR frontmatter line" } };
+    }
+    data.set(match[1], match[2] ?? "");
+  }
+  return { data, error: { file: path, message: "" } };
+}
+function stringField(data, key) {
+  const value = data.get(key)?.trim();
+  if (!value)
+    return;
+  return unquote(value);
+}
+function arrayField(data, key) {
+  const value = data.get(key)?.trim();
+  if (!value || value === "[]")
+    return [];
+  const bracketed = value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1) : value;
+  return bracketed.split(",").map((item) => unquote(item.trim())).filter(Boolean);
+}
+function nextAdrId(files) {
+  const next = files.reduce((max, path) => {
+    const match = basename(path).match(/^ADR-(\d{4})-/);
+    return match?.[1] ? Math.max(max, Number(match[1])) : max;
+  }, 0) + 1;
+  return `ADR-${String(next).padStart(4, "0")}`;
+}
+function formatAdr(options) {
+  return `---
+id: ${options.id}
+title: ${options.title}
+status: ${options.status}
+date: ${options.date}
+supersedes: ${formatArray(options.supersedes)}
+tags: ${formatArray(options.tags)}
+---
+
+# ${options.id}: ${options.title}
+
+## Context
+
+Describe the forces, constraints, and history that make this decision necessary.
+
+## Decision
+
+Describe the chosen direction.
+
+## Consequences
+
+Describe the tradeoffs, follow-up work, and facts that should reference this ADR.
+`;
+}
+function formatArray(values) {
+  return values.length === 0 ? "[]" : `[${values.join(", ")}]`;
+}
+function isAdrStatus(value) {
+  return adrStatuses.includes(value);
+}
+function slug(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "decision";
+}
+function unquote(input) {
+  return input.replace(/^['"]|['"]$/g, "");
+}
+
+// src/core/context.ts
+import { appendFile, mkdir as mkdir2 } from "node:fs/promises";
+import { basename as basename2, join as join4 } from "node:path";
+
 // src/core/validate.ts
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var requiredFiles = [
   "docs/context/INDEX.md",
   "docs/context/LOG.md",
@@ -61,6 +276,8 @@ var requiredFiles = [
 async function validateProject({ repo }) {
   const errors = [];
   const warnings = [];
+  const adrCatalog = await readAdrCatalog(repo);
+  errors.push(...adrCatalog.errors);
   for (const file of requiredFiles) {
     if (!await exists(repoPath(repo, file))) {
       errors.push({ file, message: "required context file is missing" });
@@ -68,8 +285,8 @@ async function validateProject({ repo }) {
   }
   const featureRoot = repoPath(repo, "docs/context/features");
   const features = await listDirs(featureRoot);
-  for (const slug of features) {
-    const factsPath = join2(featureRoot, slug, "FACTS.jsonl");
+  for (const slug2 of features) {
+    const factsPath = join3(featureRoot, slug2, "FACTS.jsonl");
     if (!await exists(factsPath)) {
       warnings.push({ file: rel(repo, factsPath), message: "feature pack has no FACTS.jsonl" });
       continue;
@@ -84,6 +301,14 @@ async function validateProject({ repo }) {
         const message = validateFact(value);
         if (message)
           errors.push({ file: rel(repo, factsPath), line, message });
+        if (!message) {
+          const fact = value;
+          for (const source of fact.src) {
+            if (looksLikeAdrSource(source) && !adrCatalog.adrs.some((adr) => adrMatchesSource(adr, source))) {
+              warnings.push({ file: rel(repo, factsPath), line, message: `fact references missing ADR source: ${source}` });
+            }
+          }
+        }
       } catch {
         errors.push({ file: rel(repo, factsPath), line, message: "invalid JSON" });
       }
@@ -116,12 +341,14 @@ function validateFact(value) {
 // src/core/context.ts
 async function routeTask({ repo, task }) {
   const features = await readFeaturePacks(repo);
+  const adrs = await listAdrs({ repo });
   const taskTokens = tokens(task);
-  const routes = features.map((feature) => scoreFeature(feature, taskTokens)).filter((route) => route.score > 0).sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
+  const routes = features.map((feature) => scoreFeature(feature, taskTokens, adrs)).filter((route) => route.score > 0).sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
   return { task, routes };
 }
 async function searchContext({ repo, query }) {
   const features = await readFeaturePacks(repo);
+  const adrs = await listAdrs({ repo });
   const queryTokens = tokens(query);
   const results = [];
   for (const feature of features) {
@@ -147,28 +374,43 @@ async function searchContext({ repo, query }) {
           route: feature.slug,
           score,
           text: factText,
-          source: `${rel(repo, join3(feature.dir, "FACTS.jsonl"))}#${fact.id}`
+          source: `${rel(repo, join4(feature.dir, "FACTS.jsonl"))}#${fact.id}`
         });
       }
     }
   }
+  for (const adr of adrs) {
+    const score = scoreText(adrToText(adr), queryTokens);
+    if (score > 0) {
+      results.push({
+        type: "adr",
+        id: adr.id,
+        route: "adrs",
+        score,
+        text: adr.title,
+        source: adr.path
+      });
+    }
+  }
   results.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
   return { query, results };
 }
 async function loadContext({ repo, route }) {
   const features = await readFeaturePacks(repo);
+  const adrs = await listAdrs({ repo });
   const feature = features.find((item) => item.slug === route) ?? null;
   if (!feature)
-    return { feature: null, facts: [], sources: [] };
+    return { feature: null, facts: [], sources: [], adrs: [] };
   return {
     feature,
     facts: feature.facts,
     sources: [
-      rel(repo, join3(feature.dir, "README.md")),
-      rel(repo, join3(feature.dir, "IDMAP.md")),
-      rel(repo, join3(feature.dir, "KG.adj")),
-      rel(repo, join3(feature.dir, "FACTS.jsonl"))
-    ]
+      rel(repo, join4(feature.dir, "README.md")),
+      rel(repo, join4(feature.dir, "IDMAP.md")),
+      rel(repo, join4(feature.dir, "KG.adj")),
+      rel(repo, join4(feature.dir, "FACTS.jsonl"))
+    ],
+    adrs: linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs)
   };
 }
 async function resumeProject({ repo, task }) {
@@ -181,7 +423,7 @@ async function resumeProject({ repo, task }) {
     execution_contract: {
       task_goal: task,
       first_action: firstAction,
-      edit_scope: selected.map((slug) => `docs/context/features/${slug}/**`),
+      edit_scope: selected.map((slug2) => `docs/context/features/${slug2}/**`),
       validation_commands: ["barry-cache validate"],
       contract_strength: "soft"
     }
@@ -190,7 +432,7 @@ async function resumeProject({ repo, task }) {
 async function finalizeProject(options) {
   const dir = repoPath(options.repo, ".context-state/handoffs");
   await mkdir2(dir, { recursive: true });
-  const path = join3(dir, "handoffs.jsonl");
+  const path = join4(dir, "handoffs.jsonl");
   const record = {
     id: `handoff-${new Date().toISOString()}`,
     updated_at: new Date().toISOString(),
@@ -207,15 +449,15 @@ async function readFeaturePacks(repo) {
   const root = repoPath(repo, "docs/context/features");
   const slugs = await listDirs(root);
   const features = [];
-  for (const slug of slugs) {
-    const dir = join3(root, slug);
+  for (const slug2 of slugs) {
+    const dir = join4(root, slug2);
     features.push({
-      slug,
+      slug: slug2,
       dir,
-      readme: await readTextIfExists(join3(dir, "README.md")),
-      idmap: await readTextIfExists(join3(dir, "IDMAP.md")),
-      graph: await readTextIfExists(join3(dir, "KG.adj")),
-      facts: await readFacts(join3(dir, "FACTS.jsonl"))
+      readme: await readTextIfExists(join4(dir, "README.md")),
+      idmap: await readTextIfExists(join4(dir, "IDMAP.md")),
+      graph: await readTextIfExists(join4(dir, "KG.adj")),
+      facts: await readFacts(join4(dir, "FACTS.jsonl"))
     });
   }
   return features;
@@ -232,14 +474,16 @@ async function readFacts(path) {
   }
   return facts;
 }
-function scoreFeature(feature, taskTokens) {
+function scoreFeature(feature, taskTokens, adrs) {
+  const linkedAdrs = linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs);
   const text = [
     feature.slug,
-    basename(feature.dir),
+    basename2(feature.dir),
     feature.readme,
     feature.idmap,
     feature.graph,
-    ...feature.facts.map(factToText)
+    ...feature.facts.map(factToText),
+    ...linkedAdrs.map(adrToText)
   ].join(" ");
   const score = scoreText(text, taskTokens);
   return {
@@ -263,6 +507,7 @@ function factToText(fact) {
     fact.object,
     fact.status,
     fact.kind,
+    ...fact.src,
     ...fact.tags ?? []
   ].join(" ");
 }
@@ -271,7 +516,7 @@ function firstLine(value) {
 }
 
 // src/core/import-pulpcut.ts
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 async function importPulpcutKb(options) {
   const dryRun = options.dryRun ?? false;
   const result = {
@@ -286,34 +531,34 @@ async function importPulpcutKb(options) {
     warnings: []
   };
   const sourceDocs = repoPath(options.from, "docs");
-  const kbIndex = await readTextIfExists(join4(sourceDocs, "KB_INDEX.md"));
+  const kbIndex = await readTextIfExists(join5(sourceDocs, "KB_INDEX.md"));
   if (kbIndex.trim().length === 0) {
-    throw new Error(`PulpCut KB index not found at ${join4(sourceDocs, "KB_INDEX.md")}`);
+    throw new Error(`PulpCut KB index not found at ${join5(sourceDocs, "KB_INDEX.md")}`);
   }
   const routes = parseKbIndex(kbIndex);
   const slugs = await listDirs(sourceDocs);
-  for (const slug of slugs) {
-    const sourceDir = join4(sourceDocs, slug);
-    const rawFacts = await readTextIfExists(join4(sourceDir, "FACTS.jsonl"));
+  for (const slug2 of slugs) {
+    const sourceDir = join5(sourceDocs, slug2);
+    const rawFacts = await readTextIfExists(join5(sourceDir, "FACTS.jsonl"));
     if (rawFacts.trim().length === 0)
       continue;
-    const idmap = await readTextIfExists(join4(sourceDir, "IDMAP.md"));
-    const graph = await readTextIfExists(join4(sourceDir, "KG.adj"));
+    const idmap = await readTextIfExists(join5(sourceDir, "IDMAP.md"));
+    const graph = await readTextIfExists(join5(sourceDir, "KG.adj"));
     if (idmap.trim().length === 0)
-      result.warnings.push(`${slug}: missing IDMAP.md`);
+      result.warnings.push(`${slug2}: missing IDMAP.md`);
     if (graph.trim().length === 0)
-      result.warnings.push(`${slug}: missing KG.adj`);
-    const facts = parsePulpcutFacts(rawFacts, slug, result.warnings);
-    const route = routes.get(slug);
-    const targetPrefix = `docs/context/features/${slug}`;
-    await writePlanned(options.repo, result, `${targetPrefix}/README.md`, featureReadme(slug, route, idmap), dryRun);
+      result.warnings.push(`${slug2}: missing KG.adj`);
+    const facts = parsePulpcutFacts(rawFacts, slug2, result.warnings);
+    const route = routes.get(slug2);
+    const targetPrefix = `docs/context/features/${slug2}`;
+    await writePlanned(options.repo, result, `${targetPrefix}/README.md`, featureReadme(slug2, route, idmap), dryRun);
     await writePlanned(options.repo, result, `${targetPrefix}/IDMAP.md`, normalizeText(idmap), dryRun);
     await writePlanned(options.repo, result, `${targetPrefix}/KG.adj`, normalizeText(graph), dryRun);
     await writePlanned(options.repo, result, `${targetPrefix}/FACTS.jsonl`, facts.map((fact) => JSON.stringify(fact)).join(`
 `) + `
 `, dryRun);
     result.imported++;
-    result.features.push(slug);
+    result.features.push(slug2);
   }
   if (result.imported === 0) {
     result.warnings.push("No PulpCut KB feature folders with FACTS.jsonl were found.");
@@ -321,7 +566,7 @@ async function importPulpcutKb(options) {
   result.features.sort();
   return result;
 }
-function parsePulpcutFacts(input, slug, warnings) {
+function parsePulpcutFacts(input, slug2, warnings) {
   const facts = [];
   const seen = new Set;
   input.split(/\r?\n/).forEach((line, index) => {
@@ -332,7 +577,7 @@ function parsePulpcutFacts(input, slug, warnings) {
       parsed = JSON.parse(line);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      warnings.push(`${slug}/FACTS.jsonl:${index + 1} invalid JSON: ${message}`);
+      warnings.push(`${slug2}/FACTS.jsonl:${index + 1} invalid JSON: ${message}`);
       return;
     }
     const id = stringValue(parsed.id);
@@ -341,11 +586,11 @@ function parsePulpcutFacts(input, slug, warnings) {
     const object = objectValue(parsed.o);
     const src = arrayOfStrings(parsed.src);
     if (!id || !subject || !predicate || !object || src.length === 0) {
-      warnings.push(`${slug}/FACTS.jsonl:${index + 1} skipped row with missing id/s/p/o/src`);
+      warnings.push(`${slug2}/FACTS.jsonl:${index + 1} skipped row with missing id/s/p/o/src`);
       return;
     }
     if (seen.has(id))
-      warnings.push(`${slug}/FACTS.jsonl:${index + 1} duplicate fact id ${id}`);
+      warnings.push(`${slug2}/FACTS.jsonl:${index + 1} duplicate fact id ${id}`);
     seen.add(id);
     const fact = {
       id,
@@ -405,10 +650,10 @@ function parseKbIndex(input) {
   }
   return routes;
 }
-function featureReadme(slug, route, idmap) {
+function featureReadme(slug2, route, idmap) {
   const scope = extractScope(idmap);
   const sections = [
-    `# ${titleFromSlug(slug)}`,
+    `# ${titleFromSlug(slug2)}`,
     "",
     "Imported from a PulpCut KB feature folder.",
     ""
@@ -456,8 +701,8 @@ function normalizeText(input) {
   return input.trimEnd().length === 0 ? "" : `${input.trimEnd()}
 `;
 }
-function titleFromSlug(slug) {
-  return slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+function titleFromSlug(slug2) {
+  return slug2.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 }
 function stringValue(value) {
   return typeof value === "string" && value.length > 0 ? value : undefined;
@@ -483,7 +728,7 @@ function stringOrStringArray(value) {
 
 // src/core/init.ts
 import { mkdir as mkdir3 } from "node:fs/promises";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // src/core/templates.ts
 var managedStart = "<!-- barry-cache:start -->";
@@ -507,37 +752,42 @@ function applyManagedBlock(existing, body) {
 ` : "";
   return `${prefix}${nextBlock}`;
 }
-var agentInstructions = `
+function agentInstructions(commandPrefix = "barry-cache", installCommand) {
+  const commandNote = installCommand ? `Use the repo package script so Barry Cache runs from the local npm dependency without relying on shell PATH. If the dependency is missing, run \`${installCommand}\` first. Use \`npx barry-cache <command>\` only when package scripts are unavailable.` : "Use `barry-cache` directly. If it is unavailable, run it through your package runner, for example `npx barry-cache <command>`.";
+  return `
 ## Barry Cache
 
 Barry Cache remembers this repo through source-backed context files.
 
+${commandNote}
+
 Start task context with:
 
 \`\`\`bash
-barry-cache resume --task "<task>"
+${commandPrefix} resume --task "<task>"
 \`\`\`
 
 Use focused retrieval during work:
 
 \`\`\`bash
-barry-cache route --task "<task>"
-barry-cache search --query "<query>"
-barry-cache load --route "<route>"
+${commandPrefix} route --task "<task>"
+${commandPrefix} search --query "<query>"
+${commandPrefix} load --route "<route>"
 \`\`\`
 
 When context files change, run:
 
 \`\`\`bash
-barry-cache validate
+${commandPrefix} validate
 \`\`\`
 
 Before handing off substantial work, record factual evidence:
 
 \`\`\`bash
-barry-cache finalize --status success --summary "<summary>"
+${commandPrefix} finalize --status success --summary "<summary>"
 \`\`\`
 `;
+}
 var indexMd = `# Context Index
 
 This directory stores source-backed context for coding agents and humans.
@@ -552,6 +802,10 @@ barry-cache validate
 ## Routes
 
 Feature context packs live in \`docs/context/features/*\`.
+
+## Decisions
+
+Architecture decision records live in \`docs/context/adrs/*\`.
 `;
 var logMd = `# Context Log
 
@@ -561,7 +815,8 @@ var maintenanceMd = `# Context Maintenance
 
 - Keep project truth in Git.
 - Add source-backed facts to feature \`FACTS.jsonl\` files.
-- Use ADRs for decisions that change architecture.
+- Use \`barry-cache adr new --title "<decision>"\` for decisions that change architecture.
+- Reference ADR files from decision facts through the fact \`src\` array.
 - Treat \`.context-state/\` as operational memory, not canonical truth.
 - Run \`barry-cache validate\` after context changes.
 
@@ -596,6 +851,19 @@ This directory is the canonical project memory for Barry Cache. It keeps durable
 
 Barry separates three concerns: \`docs/context/\` is reviewed truth, \`.context-state/\` is operational session continuity, and \`.context-cache/\` is disposable retrieval data. Use this structure to explain existing behavior, route tasks, validate facts, and resume agent work without loading the whole repo.
 `;
+var adrReadmeMd = `# Architecture Decision Records
+
+ADRs explain why durable architectural decisions exist. Keep them short, source-backed, and linked from feature facts when a decision affects implementation behavior.
+
+Use:
+
+\`\`\`bash
+barry-cache adr new --title "<decision>"
+barry-cache adr list
+\`\`\`
+
+Facts can reference ADRs with \`src: ["docs/context/adrs/ADR-0001-example.md"]\`. Barry can then route, search, load, and review the decision together with the facts it supports.
+`;
 var conceptOverviewMd = `# Project Context Model
 
 Barry Cache separates canonical context, operational state, and generated caches.
@@ -622,6 +890,20 @@ var factSchema = {
     tags: { type: "array", items: { type: "string" } }
   }
 };
+var adrSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "Barry Cache ADR frontmatter",
+  type: "object",
+  required: ["id", "title", "status", "date"],
+  properties: {
+    id: { type: "string", pattern: "^ADR-[0-9]{4}$" },
+    title: { type: "string", minLength: 1 },
+    status: { enum: ["active", "superseded", "deprecated"] },
+    date: { type: "string", pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    supersedes: { type: "array", items: { type: "string" } },
+    tags: { type: "array", items: { type: "string" } }
+  }
+};
 var routeSchema = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
   title: "Barry Cache route",
@@ -646,11 +928,11 @@ var failureSchema = {
 // src/core/init.ts
 var allAgentTargets = ["codex", "cursor", "copilot", "claude", "gemini", "llms"];
 var adapterFiles = [
-  { target: "cursor", path: ".cursor/rules/barry-cache.mdc", content: adapterFile("Cursor") },
-  { target: "copilot", path: ".github/copilot-instructions.md", content: adapterFile("GitHub Copilot") },
-  { target: "claude", path: "CLAUDE.md", content: adapterFile("Claude Code") },
-  { target: "gemini", path: "GEMINI.md", content: adapterFile("Gemini") },
-  { target: "llms", path: "llms.txt", content: llmsTxt() }
+  { target: "cursor", path: ".cursor/rules/barry-cache.mdc", agent: "Cursor" },
+  { target: "copilot", path: ".github/copilot-instructions.md", agent: "GitHub Copilot" },
+  { target: "claude", path: "CLAUDE.md", agent: "Claude Code" },
+  { target: "gemini", path: "GEMINI.md", agent: "Gemini" },
+  { target: "llms", path: "llms.txt", agent: "LLM" }
 ];
 async function initProject(options) {
   const repo = options.repo;
@@ -661,7 +943,10 @@ async function initProject(options) {
     { path: "docs/context/INDEX.md", content: indexMd },
     { path: "docs/context/LOG.md", content: logMd },
     { path: "docs/context/MAINTENANCE.md", content: maintenanceMd },
+    { path: "docs/context/adrs/README.md", content: adrReadmeMd },
     { path: "docs/context/concepts/project-context-model.md", content: conceptOverviewMd },
+    { path: "docs/context/schema/adr.schema.json", content: `${JSON.stringify(adrSchema, null, 2)}
+` },
     { path: "docs/context/schema/fact.schema.json", content: `${JSON.stringify(factSchema, null, 2)}
 ` },
     { path: "docs/context/schema/route.schema.json", content: `${JSON.stringify(routeSchema, null, 2)}
@@ -677,17 +962,18 @@ async function initProject(options) {
     const status = await writeIfChanged(repoPath(repo, file.path), file.content, dryRun);
     record(result, status, file.path);
   }
-  await patchAgentInstructions(repo, dryRun, result, options.agents);
-  await patchGitignore(repo, dryRun, result);
   const packageManager = await patchPackageJson(repo, dryRun, result);
   if (packageManager)
     result.packageManager = packageManager;
+  const commandPrefix = barryCommandPrefix(packageManager);
+  await patchAgentInstructions(repo, dryRun, result, options.agents, commandPrefix, packageManager);
+  await patchGitignore(repo, dryRun, result);
   if (!dryRun) {
-    await mkdir3(join5(repo, ".context-state/work/threads"), { recursive: true });
-    await mkdir3(join5(repo, ".context-state/handoffs"), { recursive: true });
-    await mkdir3(join5(repo, ".context-state/failures"), { recursive: true });
-    await mkdir3(join5(repo, ".context-state/strategies"), { recursive: true });
-    await mkdir3(join5(repo, ".context-cache"), { recursive: true });
+    await mkdir3(join6(repo, ".context-state/work/threads"), { recursive: true });
+    await mkdir3(join6(repo, ".context-state/handoffs"), { recursive: true });
+    await mkdir3(join6(repo, ".context-state/failures"), { recursive: true });
+    await mkdir3(join6(repo, ".context-state/strategies"), { recursive: true });
+    await mkdir3(join6(repo, ".context-cache"), { recursive: true });
   }
   result.changed = result.written.length > 0 || result.updated.length > 0;
   return result;
@@ -700,20 +986,21 @@ function record(result, status, path) {
   if (status === "skipped")
     result.skipped.push(path);
 }
-async function patchAgentInstructions(repo, dryRun, result, agents) {
+async function patchAgentInstructions(repo, dryRun, result, agents, commandPrefix, packageManager) {
   const selected = new Set(agents ?? allAgentTargets);
   if (selected.has("codex"))
-    await patchCodexAgents(repo, dryRun, result);
+    await patchCodexAgents(repo, dryRun, result, commandPrefix, packageManager);
   for (const file of adapterFiles) {
     if (!selected.has(file.target))
       continue;
-    record(result, await writeIfChanged(repoPath(repo, file.path), file.content, dryRun), file.path);
+    const content = file.target === "llms" ? llmsTxt() : adapterFile(file.agent, commandPrefix);
+    record(result, await writeIfChanged(repoPath(repo, file.path), content, dryRun), file.path);
   }
 }
-async function patchCodexAgents(repo, dryRun, result) {
+async function patchCodexAgents(repo, dryRun, result, commandPrefix, packageManager) {
   const path = repoPath(repo, "AGENTS.md");
   const existing = await exists(path) ? await readText(path) : "";
-  const content = applyManagedBlock(existing, agentInstructions);
+  const content = applyManagedBlock(existing, agentInstructions(commandPrefix, packageManager?.installCommand));
   record(result, await writeIfChanged(path, content, dryRun), "AGENTS.md");
 }
 async function patchGitignore(repo, dryRun, result) {
@@ -764,7 +1051,10 @@ function packageManagerHint(name) {
     installCommand: `${name} install`
   };
 }
-function adapterFile(agent) {
+function barryCommandPrefix(packageManager) {
+  return packageManager ? `${packageManager.name} run barry --` : "barry-cache";
+}
+function adapterFile(agent, commandPrefix) {
   return `# Barry Cache for ${agent}
 
 Canonical context lives in \`docs/context/\`.
@@ -772,13 +1062,13 @@ Canonical context lives in \`docs/context/\`.
 Start by running:
 
 \`\`\`bash
-barry-cache resume --task "<task>"
+${commandPrefix} resume --task "<task>"
 \`\`\`
 
 Validate context changes with:
 
 \`\`\`bash
-barry-cache validate
+${commandPrefix} validate
 \`\`\`
 `;
 }
@@ -794,7 +1084,7 @@ function llmsTxt() {
 }
 
 // src/core/review-model.ts
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/core/review-tree.ts
 function buildReviewTree(facts) {
@@ -852,7 +1142,7 @@ function buildReviewTree(facts) {
       const grouped = groupFacts(routeFacts, groupBy);
       for (const [value, groupFacts] of grouped) {
         groups.push({
-          id: `tree:group:${route}:${groupBy}:${slug(value)}`,
+          id: `tree:group:${route}:${groupBy}:${slug2(value)}`,
           route,
           groupBy,
           value,
@@ -933,10 +1223,10 @@ function sortedRecord(record2) {
 function mapSetToRecord(map) {
   return Object.fromEntries([...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, values]) => [key, [...values].sort()]));
 }
-function titleFromSlug2(slug) {
-  return slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+function titleFromSlug2(slug2) {
+  return slug2.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 }
-function slug(input) {
+function slug2(input) {
   return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "value";
 }
 
@@ -947,6 +1237,9 @@ async function buildReviewModel({ repo }) {
   const facts = [];
   const timeline = [];
   const features = await readFeaturePacks(repo);
+  const adrs = await listAdrs({ repo });
+  for (const adr of adrs)
+    addAdr(graph, adr);
   for (const feature of features) {
     addFeature(graph, repo, feature);
     const sourceMap = parseIdMap(feature.idmap);
@@ -954,10 +1247,10 @@ async function buildReviewModel({ repo }) {
     for (const fact of feature.facts) {
       facts.push({
         route: feature.slug,
-        source: `${rel(repo, join6(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+        source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
         fact
       });
-      addFact(graph, repo, feature, fact, sourceMap);
+      addFact(graph, repo, feature, fact, sourceMap, adrs);
     }
   }
   timeline.push(...await addOperationalRecords({
@@ -999,6 +1292,7 @@ async function buildReviewModel({ repo }) {
     summary: {
       features: features.length,
       facts: facts.length,
+      adrs: adrs.length,
       entities: nodes.filter((node) => node.kind === "entity").length,
       sources: nodes.filter((node) => node.kind === "source").length,
       handoffs: timeline.filter((item) => item.kind === "handoff").length,
@@ -1028,14 +1322,14 @@ function addFeature(graph, repo, feature) {
     }
   });
 }
-function addFact(graph, repo, feature, fact, sourceMap) {
+function addFact(graph, repo, feature, fact, sourceMap, adrs) {
   const factId = `fact:${fact.id}`;
   addNode(graph, {
     id: factId,
     kind: "fact",
     label: fact.id,
     subtitle: `${fact.subject} ${fact.predicate} ${fact.object}`,
-    source: `${rel(repo, join6(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+    source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
     meta: {
       route: feature.slug,
       status: fact.status,
@@ -1069,7 +1363,8 @@ function addFact(graph, repo, feature, fact, sourceMap) {
   });
   for (const source of fact.src) {
     const resolved = sourceMap.get(source) ?? source;
-    const sourceId = addSource(graph, resolved, { alias: resolved === source ? undefined : source });
+    const adr = adrs.find((item) => adrMatchesSource(item, resolved) || adrMatchesSource(item, source));
+    const sourceId = adr ? `adr:${adr.id}` : addSource(graph, resolved, { alias: resolved === source ? undefined : source });
     addEdge(graph, {
       source: factId,
       target: sourceId,
@@ -1087,6 +1382,30 @@ function addFact(graph, repo, feature, fact, sourceMap) {
     });
   }
 }
+function addAdr(graph, adr) {
+  const nodeId = `adr:${adr.id}`;
+  addNode(graph, {
+    id: nodeId,
+    kind: "adr",
+    label: adr.id,
+    subtitle: adr.title,
+    source: adr.path,
+    meta: {
+      status: adr.status,
+      date: adr.date,
+      supersedes: adr.supersedes,
+      tags: adr.tags
+    }
+  });
+  for (const superseded of adr.supersedes) {
+    addEdge(graph, {
+      source: nodeId,
+      target: `adr:${superseded}`,
+      kind: "supersedes",
+      meta: {}
+    });
+  }
+}
 function addKgEdges(graph, feature) {
   for (const line of feature.graph.split(/\r?\n/)) {
     const trimmed = line.trim();
@@ -1175,7 +1494,7 @@ async function readJsonl(path, displayPath, warnings) {
   return records;
 }
 function addEntity(graph, label) {
-  const id = `entity:${slug2(label)}`;
+  const id = `entity:${slug3(label)}`;
   addNode(graph, {
     id,
     kind: "entity",
@@ -1250,7 +1569,7 @@ function firstMarkdownHeading(input) {
   const heading = input.split(/\r?\n/).find((line) => line.startsWith("# "));
   return heading?.replace(/^#\s*/, "").trim() ?? "";
 }
-function slug2(input) {
+function slug3(input) {
   return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
 }
 function stripBackticks(input) {
@@ -3599,6 +3918,10 @@ async function main(argv = process.argv.slice(2)) {
         print(await finalizeProject({ repo, status, summary }), json);
         break;
       }
+      case "adr": {
+        await handleAdrCommand(parsed, repo, json);
+        break;
+      }
       case "import": {
         const source = requiredString(parsed, "source", commandUsage("import"), { source: [...importSources] });
         const from = requiredString(parsed, "from", commandUsage("import"), { source: [...importSources] });
@@ -3671,10 +3994,14 @@ async function main(argv = process.argv.slice(2)) {
 function parseArgs(argv) {
   const [command = "help", ...rest] = argv;
   const flags = new Map;
+  const positionals = [];
   for (let index = 0;index < rest.length; index++) {
     const arg = rest[index];
-    if (!arg?.startsWith("--"))
+    if (!arg?.startsWith("--")) {
+      if (arg)
+        positionals.push(arg);
       continue;
+    }
     const key = arg.slice(2);
     const next = rest[index + 1];
     if (next && !next.startsWith("--")) {
@@ -3684,7 +4011,7 @@ function parseArgs(argv) {
       flags.set(key, true);
     }
   }
-  return { command, flags };
+  return { command, positionals, flags };
 }
 function requiredString(parsed, key, usageValue, options) {
   const value = parsed.flags.get(key);
@@ -3719,6 +4046,14 @@ function optionalChoice(parsed, key, choices, fallback, usageValue) {
   }
   return value;
 }
+function optionalList(parsed, key, usageValue) {
+  const value = parsed.flags.get(key);
+  if (value === undefined)
+    return [];
+  if (typeof value !== "string")
+    throw new CliArgumentError(`--${key} requires a comma-separated value`, { usage: usageValue });
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
 function parseAgentTargets(value) {
   if (value === undefined)
     return;
@@ -3759,6 +4094,36 @@ function print(value, json, message) {
   }
   console.log(JSON.stringify(value, null, 2));
 }
+async function handleAdrCommand(parsed, repo, json) {
+  const action = parsed.positionals[0];
+  if (action === "new") {
+    const title = requiredString(parsed, "title", commandUsage("adr new"));
+    const status = optionalChoice(parsed, "status", adrStatuses, "active", commandUsage("adr new"));
+    const adr = await createAdr({
+      repo,
+      title,
+      status,
+      supersedes: optionalList(parsed, "supersedes", commandUsage("adr new")),
+      tags: optionalList(parsed, "tags", commandUsage("adr new"))
+    });
+    print(adr, json, `Created ${adr.id} at ${adr.path}.`);
+    return;
+  }
+  if (action === "list") {
+    const adrs = await listAdrs({ repo });
+    print({ adrs }, json, formatAdrList(adrs));
+    return;
+  }
+  throw new CliArgumentError(action ? `Unknown ADR action: ${action}` : "Missing ADR action", {
+    usage: commandUsage("adr")
+  });
+}
+function formatAdrList(adrs) {
+  if (adrs.length === 0)
+    return "No ADRs found.";
+  return adrs.map((adr) => `${adr.id}  ${adr.status}  ${adr.title} (${adr.path})`).join(`
+`);
+}
 function formatInitMessage(result) {
   if (!result.dryRun) {
     const lines2 = [`Barry Cache init ${result.changed ? "changed files" : "already up to date"}.`];
@@ -3827,6 +4192,9 @@ function errorMessage(error) {
 function commandUsage(command) {
   const usages = {
     init: "barry-cache init [--yes] [--dry-run] [--agents all|none|codex,cursor,copilot,claude,gemini,llms]",
+    adr: "barry-cache adr <new|list> [--json]",
+    "adr new": 'barry-cache adr new --title "..." [--status active|superseded|deprecated] [--supersedes ADR-0001] [--tags context,agents] [--json]',
+    "adr list": "barry-cache adr list [--json]",
     route: 'barry-cache route --task "..." [--json]',
     search: 'barry-cache search --query "..." [--json]',
     load: 'barry-cache load --route "..." [--json]',
@@ -3853,6 +4221,8 @@ Usage:
   barry-cache load --route "..." [--json]
   barry-cache resume --task "..." [--json]
   barry-cache finalize --summary "..." [--status success] [--json]
+  barry-cache adr new --title "..." [--status active] [--tags context,agents]
+  barry-cache adr list [--json]
   barry-cache import --source pulpcut-kb --from /path/to/repo [--dry-run] [--json]
   barry-cache review [--port 8787] [--open]
   barry-cache review --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barry-cache",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Barry Cache remembers your repo.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "assets/barry-cache.png",
     "README.md"
   ],
   "engines": {
@@ -25,4 +26,4 @@
     "@types/node": "^25.8.0",
     "typescript": "^6.0.3"
   }
-}
+}