@ghilteras/opencode-agent-memory 1.0.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 >
 > Originally created by Joshua David Thomas and licensed under the MIT license. Attribution preserved below; see License section.
 
-A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local semantic search.
+A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local lexical search.
 
 ## Experimental
 
@@ -17,7 +17,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 ## Features
 
 - **Append-only journal** - Entries survive across sessions and context compaction
-- **Local semantic search** - Find entries by meaning, not just keywords
+- **Local lexical search** - Find candidate entries by matching query words in titles and bodies
 - **Metadata on every entry** - Project, model, provider, agent, session, timestamp, tags
 - **Guidance in tool descriptions** - Journal usage guidance lives in the descriptions of the journal tools, so an agent sees it only when it is allowed to call them
 - **No data leaves the machine** - Embeddings run locally
@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugins": ["@ghilteras/opencode-agent-memory@1.0.0"]
+  "plugins": ["@ghilteras/opencode-agent-memory@2.0.0"]
 }
 ```
 
@@ -63,7 +63,7 @@ The agent gets 3 tools:
 | Tool | Description |
 |------|-------------|
 | `journal_write` | Write a new append-only entry (title, body, optional tags) |
-| `journal_search` | Search entries semantically, filter by project or tags, with pagination |
+| `journal_search` | Find lexical candidates by matching query words in titles and bodies; filter by project or tags, with pagination |
 | `journal_read` | Read a specific journal entry by ID |
 
 ### Entry format
@@ -85,9 +85,9 @@ tags: [plugin, wiring]
 Body text...
 ```
 
-### Semantic search
+### Text search
 
-Search uses local embeddings ([paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2), 384d, multilingual EN/IT) - no data leaves your machine. An `.embedding` sidecar is written next to each entry in a versioned format (`{ v: 2, model, dimension, vector }`). The search gate is a **dimension** check: an entry whose recorded `dimension` differs from the plugin's expected dimension is not cosine-compared - it falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
+Text search runs one MiniSearch BM25+ pass over title and body. Query terms are OR-matched, with native score order and a deterministic tie-break by creation time and ID. This is keyword matching, not a claim of semantic relevance: results are candidates for the agent to inspect. Matching works across languages by matching literal words, not by meaning. When a query has no tokenizable terms (for example, `!!!`), search falls back to case-insensitive exact-substring matching over title and body. The retained index is reused while the ordered candidate-entry ID list is unchanged, avoiding repeated index construction. Embedding sidecars are still written in the versioned `{ v: 2, model, dimension, vector }` format for compatibility, but search does not read them.
 
 ### Suggested tags
 
@@ -129,6 +129,12 @@ Two behaviour changes:
 - **The journal tools are registered by default.** Previously you had to opt in through `agent-memory.json`; now an absent config means the tools are on, and you turn them off with `"enabled": false`.
 - **Storage is unchanged.** Existing entries under `~/.config/opencode/journal/` and their `.embedding` sidecars stay readable; nothing is migrated or rewritten.
 
+## Upgrading to lexical candidate search
+
+- Text search now ranks entries with lexical OR matching: a candidate may match any query term in its title or body.
+- Results are candidates, not relevance claims. `Found N` reports the candidate count before pagination and will usually be large.
+- A punctuation-only query falls back to case-insensitive substring matching over title and body.
+
 ## Upgrading from 0.4.x
 
 Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
@@ -140,7 +146,7 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 - **Requires OpenCode v2.** This release uses the OpenCode v2 plugin API and does not run on v1.
 - **Restart after config changes.** Plugin config changes require a full OpenCode restart to take effect; editing the config file alone is not sufficient.
 - **Journal is on by default.** Turn it off with `"enabled": false`; an explicit disable is silent, while a config that exists but is unreadable, malformed, or schema-invalid logs a warning and registers no tools (fail-closed).
-- **Local embeddings, no data leaves the machine.** Semantic search uses a locally cached transformers.js model; no external API calls are made for search or embedding.
+- **Embedding sidecars remain compatible.** They are written locally for the existing format contract, diagnostics, and future consumers; text search is lexical and does not read embeddings.
 - **Known limitation (since 0.5.1): guidance-in-descriptions depends on an unverified premise.** 0.5.1 moved journal guidance from the injected system-prompt note into the three journal tool descriptions, so only agents allowed to call those tools should see it. That relies on opencode omitting a permission-denied tool from the definitions sent to the model. This is **unverified**: a `tool.definition` probe on the isolated instance fires before permission filtering, so it cannot confirm what the model actually receives. If the premise does not hold, an agent denied `journal_*` may still read the description text; `deny` still blocks execution, so there is no capability escalation and no data disclosure — the blast radius is the three tools' description strings.
 
 ## Inspiration
@@ -156,3 +162,11 @@ Originally created by Joshua David Thomas and licensed under the MIT license. Ma
 opencode-agent-memory is not built by, or affiliated with, the OpenCode team.
 
 OpenCode is ©2025 Anomaly.
+# Journal diagnostics
+
+Run `bun run journal:doctor [config-dir]` to inspect flat journal Markdown files
+and their `.embedding` sidecars without repairing or changing them. The optional
+directory is the OpenCode state/config directory (the journal is read from its
+`journal/` subdirectory); without it, the default is `~/.config/opencode`.
+The command prints a deterministic JSON report and exits 0 for a complete scan
+without errors, 1 for validation errors, or 2 for an incomplete scan/root error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -17,13 +17,17 @@
     "src"
   ],
   "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "test": "bun run test:core && bun run test:plugin",
+    "test:core": "bun test src/test-suite.test.ts src/doctor.test.ts src/embeddings.test.ts src/tools.test.ts src/journal.test.ts",
+    "test:plugin": "HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 HOME=$(mktemp -d) bun test src/plugin.test.ts src/plugin-disabled.test.ts",
+    "typecheck": "tsc --noEmit",
+    "journal:doctor": "bun run src/journal-doctor.ts"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@opencode/plugin": "^2.0.18",
     "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
     "zod": "^4.1.13"
   },
   "overrides": {

package/src/doctor.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { diagnoseJournal } from "./doctor";
+
+const roots: string[] = [];
+async function fixture() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "journal-doctor-"));
+  roots.push(root);
+  await fs.mkdir(path.join(root, "journal"));
+  return path.join(root, "journal");
+}
+async function entry(dir: string, name: string, yamlText?: string, sidecar?: string) {
+  await fs.writeFile(path.join(dir, `${name}.md`), yamlText === undefined ? "plain text" : `---\n${yamlText}\n---\nbody\n`);
+  if (sidecar !== undefined) await fs.writeFile(path.join(dir, `${name}.embedding`), sidecar);
+}
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+
+test("classifies frontmatter, created values, sidecars and multiple findings deterministically", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "00-valid", valid, JSON.stringify({ v: 2, model: "wrong-model", dimension: 2, vector: [0.1, 0.2] }));
+  await entry(dir, "01-missing-title", "created: \"2025-01-01\"");
+  await entry(dir, "02-empty-title", 'title: ""');
+  await entry(dir, "03-wrong-title", "title: 42");
+  await entry(dir, "04-missing-created", "title: Present", "[1,2]");
+  await entry(dir, "05-date-only", "title: Present\ndate: \"2025-01-01\"");
+  await entry(dir, "06-invalid-created", 'title: Present\ncreated: "not a date"');
+  await entry(dir, "07-wrong-created", "title: Present\ncreated: 42");
+  await entry(dir, "08-yaml-timestamp", "title: Present\ncreated: 2025-01-01T00:00:00Z");
+  await entry(dir, "09-bad-yaml", "title: [broken");
+  await entry(dir, "10-no-frontmatter");
+  await entry(dir, "11-malformed-json", valid, "{");
+  await entry(dir, "12-vector-type", valid, '{"v":2,"model":"m","dimension":1,"vector":["x"]}');
+  await entry(dir, "13-empty-vector", valid, '{"v":2,"model":"m","dimension":0,"vector":[]}');
+  await entry(dir, "14-vector-dimension", valid, '{"v":2,"model":"m","dimension":3,"vector":[1,2]}');
+  await entry(dir, "15-legacy", valid, "[1,2]");
+  await entry(dir, "16-legacy-invalid", valid, '[1,"x"]');
+  await entry(dir, "17-missing-sidecar", valid);
+
+  const inventory = async () => Promise.all((await fs.readdir(dir)).sort().map(async (f) => [f, await fs.readFile(path.join(dir, f)), (await fs.stat(path.join(dir, f))).mtimeMs] as const));
+  const before = await inventory();
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(await diagnoseJournal(path.dirname(dir))).toEqual(report);
+  expect(report.counts.files).toBe(18);
+  const codes = (name: string) => report.findings.filter((f) => f.path.startsWith(name)).map((f) => f.code);
+  expect(codes("01-missing-title")).toContain("frontmatter_title_invalid");
+  expect(codes("02-empty-title")).toContain("frontmatter_title_invalid");
+  expect(codes("03-wrong-title")).toContain("frontmatter_title_invalid");
+  expect(codes("04-missing-created")).toContain("created_missing");
+  expect(codes("05-date-only")).toContain("created_missing");
+  expect(codes("06-invalid-created")).toContain("created_invalid");
+  expect(codes("07-wrong-created")).toContain("frontmatter_created_invalid");
+  expect(codes("08-yaml-timestamp")).toContain("frontmatter_created_invalid");
+  expect(codes("09-bad-yaml")).toContain("yaml_malformed");
+  expect(codes("10-no-frontmatter")).toContain("frontmatter_missing_or_malformed");
+  expect(codes("11-malformed-json")).toContain("embedding_json_malformed");
+  for (const name of ["12-vector-type", "13-empty-vector", "14-vector-dimension", "16-legacy-invalid"]) expect(codes(name)).toContain("embedding_invalid");
+  expect(codes("00-valid")).toContain("embedding_incompatible");
+  expect(codes("15-legacy")).toContain("embedding_model_unknown");
+  expect(codes("17-missing-sidecar")).toContain("embedding_missing");
+  expect(codes("04-missing-created")).toEqual(expect.arrayContaining(["created_missing", "embedding_model_unknown"]));
+  expect(report.findings).toEqual([...report.findings].sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code) || a.severity.localeCompare(b.severity)));
+  expect(report.findings.some((f) => /broken|Good|Present|not a date/.test(JSON.stringify(f)))).toBe(false);
+  expect(await inventory()).toEqual(before);
+});
+
+test("empty, missing, and injected unreadable roots/files have explicit incomplete semantics", async () => {
+  const missing = await diagnoseJournal("/path/that/does/not/exist");
+  expect(missing.complete).toBe(false);
+  expect(missing.findings[0]?.code).toBe("root_unreadable");
+  const dir = await fixture();
+  expect((await diagnoseJournal(path.dirname(dir))).complete).toBe(true);
+  await entry(dir, "a", "title: A"); await entry(dir, "b", "title: B");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw new Error("injected");
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(report.complete).toBe(false);
+  expect(report.findings.some((f) => f.path === "a.md" && f.code === "file_unreadable")).toBe(true);
+  expect(report.findings.some((f) => f.path === "b.md" && f.code === "created_missing")).toBe(true);
+});
+
+test("CLI emits exact bytes and exit codes for clean, warning, error, incomplete and bad invocation", async () => {
+  const dir = await fixture();
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const invoke = (...args: string[]) => Bun.spawnSync([process.execPath, "run", cli, ...args], { stdout: "pipe", stderr: "pipe" });
+  const assertCli = (result: ReturnType<typeof invoke>, stdout: string, stderr: string, exitCode: number) =>
+    expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout, stderr, exitCode });
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":0,"errors":0,"warnings":0},"findings":[]}\n', "", 0);
+
+  await entry(dir, "warning", 'title: Warn\ncreated: "2025-01-01"');
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":1,"errors":0,"warnings":1},"findings":[{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 0);
+
+  await entry(dir, "invalid", "title: 12");
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":2,"errors":1,"warnings":2},"findings":[{"path":"invalid.embedding","code":"embedding_missing","severity":"warning"},{"path":"invalid.md","code":"frontmatter_title_invalid","severity":"error"},{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 1);
+
+  assertCli(invoke("/path/that/does/not/exist"), '{"complete":false,"counts":{"files":0,"errors":1,"warnings":0},"findings":[{"path":".","code":"root_unreadable","severity":"error"}]}\n', "", 2);
+  assertCli(invoke(path.dirname(dir), "extra"), "", "usage: bun run journal:doctor [config-dir]\n", 2);
+});
+
+test("inventories orphan and associated sidecars independently and emits stable full report", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "A", valid);
+  await entry(dir, "a", valid, "{");
+  await fs.writeFile(path.join(dir, "_.embedding"), "{");
+  const expected = { complete: true, counts: { files: 2, errors: 2, warnings: 2 }, findings: [
+    { path: "A.embedding", code: "embedding_missing", severity: "warning" },
+    { path: "_.embedding", code: "embedding_json_malformed", severity: "error" },
+    { path: "_.embedding", code: "embedding_orphan", severity: "warning" },
+    { path: "a.embedding", code: "embedding_json_malformed", severity: "error" },
+  ] };
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(JSON.stringify(report)).toBe(JSON.stringify(expected));
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const result = Bun.spawnSync([process.execPath, "run", cli, path.dirname(dir)], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: `${JSON.stringify(expected)}\n`, stderr: "", exitCode: 1 });
+});
+
+test("sidecar validation survives markdown read failure; listed sidecar disappearance is incomplete", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "{");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw Object.assign(new Error("denied"), { code: "EACCES" });
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const failed = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(failed.complete).toBe(false);
+  expect(failed.findings.map((f) => f.code)).toEqual(expect.arrayContaining(["file_unreadable", "embedding_json_malformed"]));
+
+  let removed = false;
+  const disappearing = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.embedding") && !removed) { removed = true; throw Object.assign(new Error("gone"), { code: "ENOENT" }); }
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const gone = await diagnoseJournal(path.dirname(dir), disappearing);
+  expect(gone.complete).toBe(false);
+  expect(gone.findings.some((f) => f.path === "a.embedding" && f.code === "embedding_unreadable")).toBe(true);
+});
+
+test("diagnosis never initializes model pipeline or fetches, while warmup activates trap in child", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"');
+  const childCode = `
+    import { mock } from "bun:test";
+    let pipelines = 0, fetches = 0;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (...args) => { fetches++; throw new Error("FETCH_SENTINEL"); };
+    mock.module("@huggingface/transformers", () => ({ pipeline: async () => { pipelines++; throw new Error("PIPELINE_SENTINEL"); } }));
+    const { diagnoseJournal } = await import(${JSON.stringify(path.resolve(import.meta.dir, "doctor.ts"))});
+    const { warmupEmbedder } = await import(${JSON.stringify(path.resolve(import.meta.dir, "embeddings.ts"))});
+    await diagnoseJournal(${JSON.stringify(path.dirname(dir))});
+    if (pipelines !== 0 || fetches !== 0) throw new Error("diagnosis activated model/fetch trap");
+    try { await warmupEmbedder(); throw new Error("pipeline sentinel was not caught"); } catch (error) { if (!String(error).includes("PIPELINE_SENTINEL")) throw error; }
+    if (pipelines !== 1 || fetches !== 0) throw new Error("pipeline trap count mismatch");
+    globalThis.fetch = originalFetch;
+    console.log(JSON.stringify({ pipelines, fetches }));
+  `;
+  const result = Bun.spawnSync([process.execPath, "-e", childCode], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: '{"pipelines":1,"fetches":0}\n', stderr: "", exitCode: 0 });
+});
+
+test("only flat regular inventory files are read and each sidecar is read once", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "[1]");
+  await fs.mkdir(path.join(dir, "nested"));
+  await fs.writeFile(path.join(dir, "nested", "hidden.md"), "bad");
+  await fs.writeFile(path.join(dir, "nested", "hidden.embedding"), "{");
+  await fs.writeFile(path.join(dir, "ignored.txt"), "bad");
+  await fs.symlink(path.join(dir, "a.md"), path.join(dir, "linked.md"));
+  const reads = new Map<string, number>();
+  const counting = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    const name = path.basename(String(p)); reads.set(name, (reads.get(name) ?? 0) + 1);
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), counting);
+  expect(report.counts.files).toBe(1);
+  expect([...reads.entries()].sort()).toEqual([["a.embedding", 1], ["a.md", 1]]);
+  expect(report.findings.map((f) => f.path)).toEqual(["a.embedding", "a.embedding"]);
+});

package/src/doctor.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { z } from "zod";
+import { EMBEDDING_DIMENSION, embeddingModelName } from "./embeddings";
+import { splitFrontmatter } from "./frontmatter";
+import { EntryFrontmatterSchema } from "./journal";
+
+export type JournalFinding = { path: string; code: string; severity: "error" | "warning" };
+export type JournalDiagnosticReport = {
+  complete: boolean;
+  counts: { files: number; errors: number; warnings: number };
+  findings: JournalFinding[];
+};
+type FileSystem = Pick<typeof fs, "readdir" | "readFile" | "stat">;
+
+export async function diagnoseJournal(configDir?: string, fileSystem: FileSystem = fs): Promise<JournalDiagnosticReport> {
+  const root = path.resolve(configDir ?? path.join(os.homedir(), ".config", "opencode"), "journal");
+  const findings: JournalFinding[] = [];
+  let complete = true;
+  const add = (file: string, code: string, severity: JournalFinding["severity"]) => findings.push({ path: file, code, severity });
+  let entries: import("node:fs").Dirent[];
+  try { entries = await fileSystem.readdir(root, { withFileTypes: true }); }
+  catch { add(".", "root_unreadable", "error"); complete = false; entries = []; }
+
+  const inventory = entries.filter((entry) => entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".embedding"))).map((entry) => entry.name).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  const files = inventory.filter((name) => name.endsWith(".md"));
+  const sidecars = inventory.filter((name) => name.endsWith(".embedding"));
+  const sidecarSet = new Set(sidecars);
+  for (const name of files) {
+    const relative = name;
+    let raw: string | undefined;
+    try { raw = await fileSystem.readFile(path.join(root, name), "utf8"); }
+    catch { add(relative, "file_unreadable", "error"); complete = false; }
+    if (raw !== undefined) {
+      const { frontmatterText } = splitFrontmatter(raw);
+      if (frontmatterText === undefined) add(relative, "frontmatter_missing_or_malformed", "error");
+      else {
+        let value: unknown;
+        try { value = yaml.load(frontmatterText); }
+        catch { add(relative, "yaml_malformed", "error"); value = undefined; }
+        {
+          const parsed = EntryFrontmatterSchema.safeParse(value);
+          if (!parsed.success) {
+            const fields = [...new Set(parsed.error.issues.map((issue) => String(issue.path[0] ?? "document")))].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+            for (const field of fields) add(relative, `frontmatter_${field}_invalid`, "error");
+          } else {
+            if (parsed.data.created === undefined) add(relative, "created_missing", "warning");
+            else if (!Number.isFinite(new Date(parsed.data.created).getTime())) add(relative, "created_invalid", "error");
+          }
+        }
+      }
+    }
+  }
+
+  for (const sidecar of sidecars) {
+    const associatedMarkdown = `${sidecar.slice(0, -".embedding".length)}.md`;
+    if (!files.includes(associatedMarkdown)) add(sidecar, "embedding_orphan", "warning");
+    try {
+      const content = await fileSystem.readFile(path.join(root, sidecar), "utf8");
+      let value: unknown;
+      try { value = JSON.parse(content); } catch { add(sidecar, "embedding_json_malformed", "error"); continue; }
+      let vector: unknown; let dimension: unknown; let model: unknown; let legacy = false;
+      if (Array.isArray(value)) { vector = value; dimension = value.length; legacy = true; }
+      else if (value && typeof value === "object") {
+        const envelope = z.object({ v: z.literal(2), model: z.string(), dimension: z.number().int().positive(), vector: z.array(z.number().finite()).min(1) }).safeParse(value);
+        if (!envelope.success) { add(sidecar, "embedding_invalid", "error"); continue; }
+        ({ vector, dimension, model } = envelope.data);
+      } else { add(sidecar, "embedding_invalid", "error"); continue; }
+      if (!Array.isArray(vector) || vector.length === 0 || !vector.every((n) => typeof n === "number" && Number.isFinite(n)) || vector.length !== dimension) {
+        add(sidecar, "embedding_invalid", "error"); continue;
+      }
+      if (legacy) add(sidecar, "embedding_model_unknown", "warning");
+      if (vector.length !== EMBEDDING_DIMENSION || (!legacy && model !== embeddingModelName())) add(sidecar, "embedding_incompatible", "warning");
+    } catch (error) {
+      add(sidecar, "embedding_unreadable", "error"); complete = false;
+    }
+  }
+  for (const name of files) {
+    const expectedSidecar = `${name.slice(0, -".md".length)}.embedding`;
+    if (!sidecarSet.has(expectedSidecar)) add(expectedSidecar, "embedding_missing", "warning");
+  }
+  const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+  findings.sort((a, b) => compare(a.path, b.path) || compare(a.code, b.code) || compare(a.severity, b.severity));
+  return { complete, counts: { files: files.length, errors: findings.filter((f) => f.severity === "error").length, warnings: findings.filter((f) => f.severity === "warning").length }, findings };
+}

package/src/journal-doctor.ts

@@ -0,0 +1,11 @@
+import { diagnoseJournal } from "./doctor";
+
+const args = process.argv.slice(2);
+if (args.length > 1 || args.some((arg) => arg.startsWith("-"))) {
+  console.error("usage: bun run journal:doctor [config-dir]");
+  process.exitCode = 2;
+} else {
+  const report = await diagnoseJournal(args[0]);
+  console.log(JSON.stringify(report));
+  process.exitCode = !report.complete ? 2 : report.counts.errors > 0 ? 1 : 0;
+}