@sksoftofficial/mindroot 1.0.6 → 1.1.0

package/src/server.js

@@ -12,6 +12,8 @@ const DASHBOARD = path.join(DASHBOARD_DIR, "index.html");
 const DASHBOARD_ASSETS = new Map([
   ["/favicon.png", ["favicon.png", "image/png"]],
   ["/logo.png", ["logo.png", "image/png"]],
+  ["/graph.js", ["graph.js", "text/javascript; charset=utf-8"]],
+  ["/vendor/force-graph.min.js", [fileURLToPath(new URL("./force-graph.min.js", import.meta.resolve("force-graph"))), "text/javascript; charset=utf-8"]],
 ]);
 
 export function createServer(db, cfg) {
@@ -29,10 +31,10 @@ export function createServer(db, cfg) {
 
       const asset = DASHBOARD_ASSETS.get(url.pathname);
       if (req.method === "GET" && asset) {
-        const body = await fs.readFile(path.join(DASHBOARD_DIR, asset[0]));
+        const body = await fs.readFile(path.resolve(DASHBOARD_DIR, asset[0]));
         res.writeHead(200, {
           "content-type": asset[1],
-          "cache-control": "public, max-age=86400",
+          "cache-control": asset[0] === "graph.js" ? "no-cache" : "public, max-age=86400",
         });
         res.end(body);
         return;
@@ -97,13 +99,30 @@ async function handleApi(req, res, url, db) {
     if (parts.length === 3) {
       if (req.method === "GET") {
         const project = getProjectRow(db, slug);
-        const [docs, memories] = await Promise.all([core.listDocs(db, slug), core.listMemories(db, slug)]);
-        return sendJson(res, 200, { slug, id: project.id, docs, memories });
+        const [docs, memories, skills] = await Promise.all([
+          core.listDocs(db, slug), core.listMemories(db, slug), core.listSkills(db, slug),
+        ]);
+        return sendJson(res, 200, { slug, id: project.id, docs, memories, skills });
       }
       if (req.method === "DELETE") return sendJson(res, 200, await core.deleteProject(db, slug));
       throw methodNotAllowed();
     }
 
+    if (parts[3] === "skills") {
+      if (parts.length === 4 && req.method === "GET") return sendJson(res, 200, core.listSkills(db, slug));
+      if (parts.length !== 5) throw notFound();
+      const name = decodeURIComponent(parts[4]);
+      if (req.method === "GET") {
+        const revision = url.searchParams.get("revision");
+        return sendJson(res, 200, core.readSkill(db, slug, name, revision === null ? undefined : Number(revision)));
+      }
+      if (req.method === "PUT") {
+        const body = await readJson(req);
+        return sendJson(res, 200, await core.saveSkill(db, slug, name, body.description, body.content, body.expected_revision));
+      }
+      if (req.method === "DELETE") return sendJson(res, 200, core.deleteSkill(db, slug, name));
+      throw methodNotAllowed();
+    }
     if (parts[3] === "docs") {
       if (req.method === "GET") return sendJson(res, 200, await core.listDocs(db, slug));
       throw methodNotAllowed();
@@ -153,6 +172,8 @@ async function handleApi(req, res, url, db) {
       hits = await core.searchMemories(db, body.project, body.query, limit);
     } else if (body.kind === "notes") {
       hits = await core.searchNotes(db, body.project, body.query, limit);
+    } else if (body.kind === "skills") {
+      hits = await core.searchSkills(db, body.project, body.query, limit);
     } else {
       const [memories, notes] = await Promise.all([
         core.searchMemories(db, body.project, body.query, limit),

package/src/skills.js

@@ -0,0 +1,133 @@
+import { validSlug, ensureProject, getProjectRow, httpError } from "./indexer.js";
+import { embedDoc, embedQuery } from "./embedder.js";
+import { ONNX_MODEL_ID } from "./paths.js";
+import { rankSkills } from "./search.js";
+
+function validateProject(slug) {
+  if (!slug) throw httpError(400, "project is required");
+  if (!validSlug(slug)) throw httpError(400, `invalid project slug: ${slug}`);
+}
+
+function validateName(name) {
+  if (typeof name !== "string" || name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    throw httpError(400, "skill name must be 1-64 lowercase letters/digits separated by single hyphens");
+  }
+}
+
+function validateRevision(revision, minimum) {
+  if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < minimum)) {
+    throw httpError(400, `revision must be an integer >= ${minimum}`);
+  }
+}
+
+function findSkill(db, projectId, name) {
+  return db.prepare("SELECT * FROM skills WHERE project_id = ? AND name = ?").get(projectId, name);
+}
+
+function summary(row) {
+  return {
+    name: row.name,
+    description: row.description,
+    revision: row.revision,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+export function listSkills(db, slug) {
+  validateProject(slug);
+  const project = getProjectRow(db, slug);
+  return db.prepare(
+    "SELECT name, description, revision, created_at, updated_at FROM skills WHERE project_id = ? ORDER BY name",
+  ).all(project.id);
+}
+
+export function readSkill(db, slug, name, revision) {
+  validateProject(slug);
+  validateName(name);
+  validateRevision(revision, 1);
+  const project = getProjectRow(db, slug);
+  const current = findSkill(db, project.id, name);
+  if (!current) throw httpError(404, `skill not found: ${name}`);
+  const row = revision === undefined ? current : db.prepare(
+    "SELECT description, content, revision, saved_at AS updated_at FROM skill_revisions WHERE skill_id = ? AND revision = ?",
+  ).get(current.id, revision);
+  if (!row) throw httpError(404, `skill revision not found: ${name}@${revision}`);
+  return { ...summary({ ...current, ...row }), content: row.content, current_revision: current.revision };
+}
+
+// Embed before opening the transaction; never hold a write lock during model inference.
+export async function saveSkill(db, slug, name, description, content, expectedRevision, embed = embedDoc) {
+  validateProject(slug);
+  validateName(name);
+  validateRevision(expectedRevision, 0);
+  if (typeof description !== "string" || !description.trim() || description.length > 2000) {
+    throw httpError(400, "skill description is required (maximum 2000 characters)");
+  }
+  if (typeof content !== "string" || !content.trim()) throw httpError(400, "skill content is required");
+  description = description.trim();
+  const project = db.prepare("SELECT id FROM projects WHERE slug = ?").get(slug);
+  const previous = project && findSkill(db, project.id, name);
+  const previousRevision = previous?.revision ?? 0;
+  if (expectedRevision !== undefined && expectedRevision !== previousRevision) {
+    throw httpError(409, "skill changed; read the latest revision before saving");
+  }
+  if (previous?.description === description && previous.content === content) {
+    return { ...summary(previous), unchanged: true };
+  }
+
+  const vec = await embed(`${name}\n${description}`);
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const currentProject = db.prepare("SELECT id FROM projects WHERE slug = ?").get(slug);
+    if (project && currentProject?.id !== project.id) {
+      throw httpError(409, "project changed while saving skill; resolve the project again");
+    }
+    const target = currentProject ?? ensureProject(db, slug);
+    const current = findSkill(db, target.id, name);
+    if ((current?.revision ?? 0) !== previousRevision || current?.id !== previous?.id) {
+      throw httpError(409, "skill changed; read the latest revision before saving");
+    }
+    const now = Date.now();
+    const revision = previousRevision + 1;
+    const row = db.prepare(
+      `INSERT INTO skills (project_id, name, description, content, revision, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(project_id, name) DO UPDATE SET
+         description = excluded.description, content = excluded.content,
+         revision = excluded.revision, updated_at = excluded.updated_at
+       RETURNING *`,
+    ).get(target.id, name, description, content, revision, now, now);
+    db.prepare(
+      "INSERT INTO skill_revisions (skill_id, revision, description, content, saved_at) VALUES (?, ?, ?, ?, ?)",
+    ).run(row.id, revision, description, content, now);
+    db.prepare(
+      `INSERT INTO skill_embeddings (skill_id, dim, model, vec) VALUES (?, ?, ?, ?)
+       ON CONFLICT(skill_id) DO UPDATE SET dim = excluded.dim, model = excluded.model, vec = excluded.vec`,
+    ).run(row.id, vec.length, ONNX_MODEL_ID, Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength));
+    db.exec("COMMIT");
+    return { ...summary(row), unchanged: false };
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
+export function deleteSkill(db, slug, name) {
+  validateProject(slug);
+  validateName(name);
+  const project = getProjectRow(db, slug);
+  const result = db.prepare("DELETE FROM skills WHERE project_id = ? AND name = ?").run(project.id, name);
+  if (!result.changes) throw httpError(404, `skill not found: ${name}`);
+  return { deleted: name };
+}
+
+export async function searchSkills(db, slug, query, limit = 8) {
+  validateProject(slug);
+  if (typeof query !== "string" || !query.trim()) throw httpError(400, "query is required");
+  const project = getProjectRow(db, slug);
+  const n = Number(limit);
+  const count = Number.isFinite(n) ? Math.min(Math.max(Math.floor(n), 1), 100) : 8;
+  if (!db.prepare("SELECT 1 FROM skills WHERE project_id = ? LIMIT 1").get(project.id)) return [];
+  return rankSkills(db, project.id, await embedQuery(query), query, count);
+}

package/src/store/db.js

@@ -55,6 +55,56 @@ CREATE TABLE IF NOT EXISTS project_embeddings (
   vec BLOB NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS skills (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  description TEXT NOT NULL,
+  content TEXT NOT NULL,
+  revision INTEGER NOT NULL CHECK (revision > 0),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(project_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS skill_revisions (
+  skill_id INTEGER NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  revision INTEGER NOT NULL,
+  description TEXT NOT NULL,
+  content TEXT NOT NULL,
+  saved_at INTEGER NOT NULL,
+  PRIMARY KEY(skill_id, revision)
+);
+
+CREATE TABLE IF NOT EXISTS skill_embeddings (
+  skill_id INTEGER PRIMARY KEY REFERENCES skills(id) ON DELETE CASCADE,
+  dim INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  vec BLOB NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
+  name,
+  description,
+  content='skills',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS skills_ai AFTER INSERT ON skills BEGIN
+  INSERT INTO skills_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_ad AFTER DELETE ON skills BEGIN
+  INSERT INTO skills_fts(skills_fts, rowid, name, description)
+  VALUES ('delete', old.id, old.name, old.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_au AFTER UPDATE OF name, description ON skills BEGIN
+  INSERT INTO skills_fts(skills_fts, rowid, name, description)
+  VALUES ('delete', old.id, old.name, old.description);
+  INSERT INTO skills_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+END;
+
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   text,
   content='memories',

package/test/install-clients.test.js

@@ -0,0 +1,187 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse as parseToml } from "@decimalturn/toml-patch";
+import { configureClaude, configureCodex } from "../src/commands/install.js";
+
+let dir;
+const cfg = { port: 8765, apiKey: "test-only-key" };
+const policy = (await fs.readFile(new URL("../INSTRUCTIONS.md", import.meta.url), "utf8")).trim();
+const savedEnv = {};
+
+beforeEach(async () => {
+  dir = await fs.mkdtemp(path.join(os.tmpdir(), "mindroot-install-clients-"));
+  for (const name of ["CLAUDE_CONFIG_DIR", "CODEX_HOME"]) {
+    savedEnv[name] = process.env[name];
+    delete process.env[name];
+  }
+});
+
+afterEach(async () => {
+  for (const [name, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+test("claude: defaults keep .claude.json outside ~/.claude; a rerun is byte-identical", async (t) => {
+  const home = path.join(dir, "home");
+  t.mock.method(os, "homedir", () => home);
+  const { configPath, agentsPath } = configureClaude(cfg);
+  assert.equal(configPath, path.join(home, ".claude.json"));
+  assert.equal(agentsPath, path.join(home, ".claude", "CLAUDE.md"));
+  const configText = await fs.readFile(configPath, "utf8");
+  assert.deepEqual(JSON.parse(configText), {
+    mcpServers: { mindroot: {
+      type: "http", url: "http://127.0.0.1:8765/mcp",
+      headers: { Authorization: "Bearer test-only-key" },
+    } },
+  });
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  configureClaude(cfg);
+  assert.equal(await fs.readFile(configPath, "utf8"), configText);
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  if (process.platform !== "win32") assert.equal((await fs.stat(configPath)).mode & 0o777, 0o600);
+});
+
+test("claude: explicit directories and CLAUDE_CONFIG_DIR keep both files inside", async () => {
+  const explicit = configureClaude(cfg, path.join(dir, "explicit"));
+  assert.equal(explicit.configPath, path.join(dir, "explicit", ".claude.json"));
+  assert.equal(explicit.agentsPath, path.join(dir, "explicit", "CLAUDE.md"));
+  process.env.CLAUDE_CONFIG_DIR = path.join(dir, "envdir");
+  const env = configureClaude(cfg);
+  assert.equal(env.configPath, path.join(dir, "envdir", ".claude.json"));
+  assert.equal(env.agentsPath, path.join(dir, "envdir", "CLAUDE.md"));
+});
+
+test("claude: preserves unrelated settings and refreshes the owned entry", async () => {
+  const configPath = path.join(dir, ".claude.json");
+  await fs.writeFile(configPath, JSON.stringify({
+    model: "claude-opus",
+    mcpServers: { other: { type: "stdio", command: ["x"] }, mindroot: { type: "sse", url: "stale" } },
+    projects: { "/work": { allowed: true } },
+  }));
+  configureClaude(cfg, dir);
+  const config = JSON.parse(await fs.readFile(configPath, "utf8"));
+  assert.equal(config.model, "claude-opus");
+  assert.deepEqual(config.projects, { "/work": { allowed: true } });
+  assert.deepEqual(config.mcpServers.other, { type: "stdio", command: ["x"] });
+  assert.deepEqual(config.mcpServers.mindroot, {
+    type: "http", url: "http://127.0.0.1:8765/mcp",
+    headers: { Authorization: "Bearer test-only-key" },
+  });
+  configureClaude({ port: 9876, apiKey: "replacement-test-key" }, dir);
+  const updated = JSON.parse(await fs.readFile(configPath, "utf8")).mcpServers.mindroot;
+  assert.equal(updated.url, "http://127.0.0.1:9876/mcp");
+  assert.equal(updated.headers.Authorization, "Bearer replacement-test-key");
+});
+
+test("claude: malformed config or markers leave both files untouched", async () => {
+  const configPath = path.join(dir, ".claude.json");
+  const agentsPath = path.join(dir, "CLAUDE.md");
+  const cases = [
+    ["{ broken", "Keep me", /invalid Claude configuration/],
+    ["[1]", "Keep me", /invalid Claude configuration/],
+    ['{"mcpServers": []}', "Keep me", /expected an mcpServers object/],
+    ["{}", "<!-- mindroot:start -->\nunfinished", /unbalanced mindroot markers/],
+  ];
+  for (const [config, agents, error] of cases) {
+    await fs.writeFile(configPath, config);
+    await fs.writeFile(agentsPath, agents);
+    assert.throws(() => configureClaude(cfg, dir), error);
+    assert.equal(await fs.readFile(configPath, "utf8"), config);
+    assert.equal(await fs.readFile(agentsPath, "utf8"), agents);
+  }
+});
+
+test("codex: creates config and policy, preserves TOML comments; a rerun is byte-identical", async () => {
+  const configPath = path.join(dir, "config.toml");
+  await fs.writeFile(configPath, `# Codex config
+model = "gpt-5-codex"
+
+[mcp_servers.other]
+url = "https://example.com/mcp" # keep me
+`);
+  const { configPath: returned, agentsPath } = configureCodex(cfg, dir);
+  assert.equal(returned, configPath);
+  assert.equal(agentsPath, path.join(dir, "AGENTS.md"));
+  const first = await fs.readFile(configPath, "utf8");
+  assert.ok(first.includes("# Codex config"));
+  assert.ok(first.includes('model = "gpt-5-codex"'));
+  assert.ok(first.includes('url = "https://example.com/mcp" # keep me'));
+  const config = parseToml(first);
+  assert.deepEqual(config.mcp_servers.mindroot, {
+    url: "http://127.0.0.1:8765/mcp",
+    http_headers: { Authorization: "Bearer test-only-key" },
+  });
+  assert.equal(config.model, "gpt-5-codex");
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  configureCodex(cfg, dir);
+  assert.equal(await fs.readFile(configPath, "utf8"), first);
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  if (process.platform !== "win32") assert.equal((await fs.stat(configPath)).mode & 0o777, 0o600);
+});
+
+test("codex: honors CODEX_HOME or ~/.codex by default and refreshes the owned entry", async (t) => {
+  const home = path.join(dir, "home");
+  t.mock.method(os, "homedir", () => home);
+  const defaulted = configureCodex(cfg);
+  assert.equal(defaulted.configPath, path.join(home, ".codex", "config.toml"));
+  assert.equal(defaulted.agentsPath, path.join(home, ".codex", "AGENTS.md"));
+  process.env.CODEX_HOME = path.join(dir, "custom");
+  const env = configureCodex({ port: 9876, apiKey: "replacement-test-key" });
+  assert.equal(env.configPath, path.join(dir, "custom", "config.toml"));
+  const config = parseToml(await fs.readFile(env.configPath, "utf8"));
+  assert.equal(config.mcp_servers.mindroot.url, "http://127.0.0.1:9876/mcp");
+  assert.equal(config.mcp_servers.mindroot.http_headers.Authorization, "Bearer replacement-test-key");
+});
+
+test("codex: syncs a non-empty AGENTS.override.md; an empty override falls back to AGENTS.md", async () => {
+  const basePath = path.join(dir, "AGENTS.md");
+  const overridePath = path.join(dir, "AGENTS.override.md");
+  await fs.writeFile(basePath, "# Base\nKeep me.\n");
+  await fs.writeFile(overridePath, "Override content.\n");
+  const active = configureCodex(cfg, dir);
+  assert.equal(active.agentsPath, overridePath);
+  assert.equal(await fs.readFile(overridePath, "utf8"), "Override content.\n\n" + policy + "\n");
+  assert.equal(await fs.readFile(basePath, "utf8"), "# Base\nKeep me.\n");
+
+  await fs.writeFile(overridePath, "\n");
+  const fallback = configureCodex(cfg, dir);
+  assert.equal(fallback.agentsPath, basePath);
+  assert.equal(await fs.readFile(overridePath, "utf8"), "\n");
+  assert.equal(await fs.readFile(basePath, "utf8"), "# Base\nKeep me.\n\n" + policy + "\n");
+});
+
+test("codex: malformed TOML, bad shapes, or markers leave both files untouched", async () => {
+  const configPath = path.join(dir, "config.toml");
+  const agentsPath = path.join(dir, "AGENTS.md");
+  const cases = [
+    ["model = ", "Keep me", /invalid Codex configuration/],
+    ["mcp_servers = 3", "Keep me", /expected an mcp_servers table/],
+    ["mcp_servers.mindroot = 5", "Keep me", /expected mcp_servers\.mindroot to be a table/],
+    ["", "<!-- mindroot:end -->", /unbalanced mindroot markers/],
+  ];
+  for (const [config, agents, error] of cases) {
+    await fs.writeFile(configPath, config);
+    await fs.writeFile(agentsPath, agents);
+    assert.throws(() => configureCodex(cfg, dir), error);
+    assert.equal(await fs.readFile(configPath, "utf8"), config);
+    assert.equal(await fs.readFile(agentsPath, "utf8"), agents);
+  }
+});
+
+test("both clients replace marked policies and preserve surrounding instructions", async () => {
+  const prefix = "# User instructions\nKeep these.\n\n";
+  const suffix = "\nCustom footer without a trailing newline";
+  const old = "<!-- mindroot:start -->\nOld policy\n<!-- mindroot:end -->";
+  for (const configure of [(d) => configureClaude(cfg, d), (d) => configureCodex(cfg, d)]) {
+    const agentsPath = path.join(dir, "AGENTS.md");
+    await fs.writeFile(agentsPath, prefix + old + suffix);
+    configure(dir);
+    assert.equal(await fs.readFile(agentsPath, "utf8"), prefix + policy + suffix);
+  }
+});

package/test/install.test.js

@@ -0,0 +1,127 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse } from "jsonc-parser";
+import { configureOpencode, install } from "../src/commands/install.js";
+
+let dir;
+const cfg = { port: 8765, apiKey: "test-only-key" };
+const policy = (await fs.readFile(new URL("../INSTRUCTIONS.md", import.meta.url), "utf8")).trim();
+beforeEach(async () => { dir = await fs.mkdtemp(path.join(os.tmpdir(), "mindroot-install-")); });
+afterEach(() => fs.rm(dir, { recursive: true, force: true }));
+
+test("creates global config and policy; a rerun is byte-identical", async () => {
+  const configDir = path.join(dir, "opencode");
+  const { configPath, agentsPath } = configureOpencode(cfg, configDir);
+  const configText = await fs.readFile(configPath, "utf8");
+  assert.deepEqual(JSON.parse(configText), {
+    $schema: "https://opencode.ai/config.json",
+    mcp: { mindroot: {
+      type: "remote", url: "http://127.0.0.1:8765/mcp", enabled: true,
+      headers: { Authorization: "Bearer test-only-key" },
+    } },
+  });
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  configureOpencode(cfg, configDir);
+  assert.equal(await fs.readFile(configPath, "utf8"), configText);
+  assert.equal(await fs.readFile(agentsPath, "utf8"), policy + "\n");
+  if (process.platform !== "win32") assert.equal((await fs.stat(configPath)).mode & 0o777, 0o600);
+});
+
+test("refreshes the owned MCP entry while preserving JSONC and unrelated settings", async () => {
+  const jsonPath = path.join(dir, "opencode.json");
+  const jsoncPath = path.join(dir, "opencode.jsonc");
+  const json = '{"model":"keep/this"}\n';
+  await fs.writeFile(jsonPath, json);
+  await fs.writeFile(jsoncPath, `{
+  // Keep this comment and setting.
+  "model": "provider/model",
+  "mcp": {
+    // Another server stays untouched.
+    "other": { "type": "local", "command": ["other-mcp"] },
+    "mindroot": { "type": "local", "command": ["old"], "enabled": false },
+  },
+}\n`);
+  const { configPath } = configureOpencode(cfg, dir);
+  assert.equal(configPath, jsoncPath);
+  assert.equal(await fs.readFile(jsonPath, "utf8"), json);
+  const text = await fs.readFile(jsoncPath, "utf8");
+  assert.ok(text.includes("// Keep this comment and setting."));
+  assert.ok(text.includes('// Another server stays untouched.\n    "other": { "type": "local", "command": ["other-mcp"] },'));
+  const config = parse(text);
+  assert.equal(config.model, "provider/model");
+  assert.equal(config.mcp.mindroot.command, undefined);
+  assert.equal(config.mcp.mindroot.enabled, true);
+  configureOpencode({ port: 9876, apiKey: "replacement-test-key" }, dir);
+  const updated = parse(await fs.readFile(jsoncPath, "utf8")).mcp.mindroot;
+  assert.equal(updated.url, "http://127.0.0.1:9876/mcp");
+  assert.equal(updated.headers.Authorization, "Bearer replacement-test-key");
+});
+
+test("replaces marked policies, removes duplicates, and preserves surrounding instructions", async () => {
+  const agentsPath = path.join(dir, "AGENTS.md");
+  const old = "<!-- mindroot:start -->\nOld policy\n<!-- mindroot:end -->";
+  const prefix = "# User instructions\nKeep these.\n\n";
+  const middle = "\n\n<!-- another:start -->\nOther policy\n<!-- another:end -->\n";
+  const suffix = "\nCustom footer without a trailing newline";
+  await fs.writeFile(agentsPath, prefix + old + middle + old + suffix);
+  configureOpencode(cfg, dir);
+  const expected = prefix + policy + middle + suffix;
+  assert.equal(await fs.readFile(agentsPath, "utf8"), expected);
+  configureOpencode(cfg, dir);
+  assert.equal(await fs.readFile(agentsPath, "utf8"), expected);
+});
+
+test("appends a separated policy when no marked block exists", async () => {
+  const agentsPath = path.join(dir, "AGENTS.md");
+  for (const existing of ["", "Keep me", "Keep me\n", "Keep me\n\n"]) {
+    await fs.writeFile(agentsPath, existing);
+    configureOpencode(cfg, dir);
+    assert.equal(await fs.readFile(agentsPath, "utf8"), (existing ? "Keep me\n\n" : "") + policy + "\n");
+  }
+});
+
+test("malformed config or markers leave both files untouched", async () => {
+  const configPath = path.join(dir, "opencode.json");
+  const agentsPath = path.join(dir, "AGENTS.md");
+  const cases = [
+    ["{ broken", "Keep me", /invalid OpenCode configuration/],
+    ["[]", "Keep me", /invalid OpenCode configuration/],
+    ['{"mcp": []}', "Keep me", /expected an mcp object/],
+    ['{"mcp": null}', "Keep me", /expected an mcp object/],
+    ["{}", "<!-- mindroot:start -->\nunfinished", /unbalanced mindroot markers/],
+    ["{}", "<!-- mindroot:end -->", /unbalanced mindroot markers/],
+    ["{}", "<!-- mindroot:start --><!-- mindroot:start --><!-- mindroot:end --><!-- mindroot:end -->", /unbalanced mindroot markers/],
+  ];
+  for (const [config, agents, error] of cases) {
+    await fs.writeFile(configPath, config);
+    await fs.writeFile(agentsPath, agents);
+    assert.throws(() => configureOpencode(cfg, dir), error);
+    assert.equal(await fs.readFile(configPath, "utf8"), config);
+    assert.equal(await fs.readFile(agentsPath, "utf8"), agents);
+  }
+});
+
+test("respects XDG_CONFIG_HOME and the explicit OpenCode directory override", (t) => {
+  const previous = { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME, OPENCODE_CONFIG_DIR: process.env.OPENCODE_CONFIG_DIR };
+  t.after(() => {
+    for (const [name, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+  process.env.XDG_CONFIG_HOME = dir;
+  delete process.env.OPENCODE_CONFIG_DIR;
+  assert.equal(configureOpencode(cfg).configPath, path.join(dir, "opencode", "opencode.json"));
+  const custom = path.join(dir, "custom");
+  process.env.OPENCODE_CONFIG_DIR = custom;
+  assert.equal(configureOpencode(cfg).agentsPath, path.join(custom, "AGENTS.md"));
+});
+
+test("rejects missing or unsupported install targets before initialization", async () => {
+  for (const args of [[], ["unknown"], ["opencode", "extra"], ["claude", "codex"]]) {
+    await assert.rejects(install(args), /usage: mindroot install <opencode\|claude\|codex>/);
+  }
+});

package/test/mcp.test.js

@@ -22,6 +22,10 @@ const EXPECTED_TOOLS = [
   "save_note",
   "update_section",
   "delete_note",
+  "search_skills",
+  "read_skill",
+  "save_skill",
+  "delete_skill",
 ];
 
 before(async () => {

package/test/paths.test.js

@@ -0,0 +1,53 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+let dir;
+let paths;
+beforeEach(async () => {
+  dir = await fs.mkdtemp(path.join(os.tmpdir(), "mindroot-paths-"));
+  process.env.MINDROOT_DIR = dir;
+  paths = await import("../src/paths.js");
+});
+afterEach(async () => {
+  delete process.env.MINDROOT_DIR;
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+test("ensureConfig generates the key once and keeps it stable across runs", async () => {
+  const first = paths.ensureConfig();
+  assert.equal(first.created, true);
+  assert.ok(first.cfg.apiKey);
+  const second = paths.ensureConfig();
+  assert.equal(second.created, false);
+  assert.equal(second.cfg.apiKey, first.cfg.apiKey);
+  assert.equal(second.cfg.port, paths.DEFAULT_PORT);
+  if (process.platform !== "win32") {
+    assert.equal((await fs.stat(path.join(dir, "config.json"))).mode & 0o777, 0o600);
+  }
+});
+
+test("ensureConfig keeps a stored key and port", async () => {
+  await fs.writeFile(path.join(dir, "config.json"), JSON.stringify({ apiKey: "keep-me", port: 9999 }));
+  const { cfg, created } = paths.ensureConfig();
+  assert.equal(created, false);
+  assert.equal(cfg.apiKey, "keep-me");
+  assert.equal(cfg.port, 9999);
+});
+
+test("missing config reads as empty without creating one", () => {
+  const { cfg, created } = paths.ensureConfig();
+  assert.equal(created, true);
+  assert.ok(cfg.apiKey);
+});
+
+test("corrupt or non-object configs fail loudly instead of rotating the key", async () => {
+  const configPath = path.join(dir, "config.json");
+  for (const content of ['{ broken', "", "[]", '"x"']) {
+    await fs.writeFile(configPath, content);
+    assert.throws(() => paths.ensureConfig(), /invalid mindroot configuration|expected a JSON object/);
+    assert.equal(await fs.readFile(configPath, "utf8"), content);
+  }
+});