@karajan-family/atril 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,123 @@
+# atril
+
+Skills, commands and subagents for every AI CLI, on demand.
+
+An agent loads every skill and command it finds when a session starts, and each one costs context whether the task needs it or not. atril keeps them in a **store** instead, finds the ones a task needs, and hands back the files to read. Claude Code, Codex, OpenCode and any CLI that reads Markdown can use the same store.
+
+atril is a module of the [Karajan](https://karajancode.com) family. It imports nothing from Karajan: Karajan calls it exactly as any other project would.
+
+## Install
+
+```sh
+npm install -g @karajan-family/atril
+atril --version
+```
+
+Node.js 22.12 or later.
+
+## The store
+
+A store is a folder with one directory per kind, the layout the CLIs already use:
+
+```
+.atril/
+  skills/<name>/SKILL.md      a skill: a folder, so it can carry references
+  commands/<name>.md          a command
+  agents/<name>.md            a subagent
+  atril.json                  the store's config
+```
+
+Every artifact is Markdown with frontmatter, and declares at least `name`, `description` and `kind`:
+
+```markdown
+---
+name: review
+description: Review a pull request for correctness and risk
+kind: command
+---
+Read the diff, then...
+```
+
+The root is `.atril/` by default; `--root <dir>` or `ATRIL_ROOT` change it (Karajan uses `.karajan/`). A user-level store in `~/.atril` (or `ATRIL_USER_ROOT`) is read too; the project's artifact wins a clash.
+
+## Find and use
+
+```sh
+atril scan                      # what the stores hold
+atril search "flaky test"       # ranked hits, installed and available
+atril route "fix the flaky login test" --role coder
+```
+
+`atril route` resolves a task into a **block**: the best artifact plus what it `uses` (and the agents it `delegates` to, as subagents), ordered so each piece comes after what it depends on, within a budget. It prints the files to read, not their content. `atril enrich` completes each artifact's frontmatter with the relations it discovers, and `atril graph` shows them.
+
+## Install and remove
+
+```sh
+atril install ./my-skill        # a local skill folder, command or agent file
+atril install skill:lint        # an artifact a catalog offers (see below)
+atril remove command:review
+```
+
+An install is validated first, refuses symlinks, and never overwrites different content.
+
+## Catalogs
+
+A catalog lists what you can install without installing it. List catalogs in `atril.json`:
+
+```json
+{ "catalogs": ["vendor/kit", "catalogs/team.json"] }
+```
+
+Each entry is either a folder in a store's layout, or a JSON file of git sources, each pinned to a commit with a note on what it is for:
+
+```json
+{
+  "sources": [
+    { "source": "owner/repo/skills", "commit": "<40-character sha>", "note": "process skills" }
+  ]
+}
+```
+
+Sources use the OpenSkills form `owner/repo[/path]`, read as GitHub repositories.
+
+```sh
+atril catalog sync              # fetch every pinned source into the cache, once
+atril search lint               # catalog hits come back with installed: false
+atril install skill:lint        # install one, from its pinned commit
+```
+
+The fetch runs no hooks, lands symlinks as plain files and verifies the commit. Skills installed by OpenSkills into `.claude/skills` or `.agent/skills` move into the store with `atril import --from openskills`.
+
+## Persistent pieces through rulesync
+
+CLIs only accept slash commands they know. atril registers **one** in each CLI, the bridge `/atril <name or task>`, plus a router rule that tells the agent to ask atril before a task. Everything else stays on demand, unless you choose to expose it permanently:
+
+```sh
+atril expose command:review     # recorded in atril.json
+atril sync                      # write the bridge, the rule and the exposed artifacts
+atril sync --check              # for CI: exit 1 while .rulesync/ is out of date
+```
+
+`atril sync` writes into [rulesync](https://github.com/dyoshikawa/rulesync)'s sources (`.rulesync/`), owning only what it wrote through rulesync's ownership ledger: a hand edit, a file of yours or another writer's entry stops it with nothing changed. With `"rulesync": { "generate": true }` in `atril.json` it then runs `rulesync generate`, which spreads the pieces to every CLI.
+
+## MCP server
+
+```sh
+atril mcp --root .atril
+```
+
+Serves `search`, `resolve`, `install` and `remove` as MCP tools over stdio. The store is fixed when the server starts; a tool call never chooses it.
+
+## API
+
+```js
+import { search, resolve, install, sync, catalogSync } from "@karajan-family/atril";
+
+const { block, available } = resolve({ task: "fix the flaky login test", role: "coder", root: ".atril" });
+```
+
+The entry exports `search`, `resolve`, `resolveBlock`, `install`, `remove`, `expose`, `unexpose`, `persistentPieces`, `sync`, `generate`, `catalogSync`, `installFromCatalog`, `importSkills`, `MARKER` and `VERSION`.
+
+## License
+
+MIT

package/bin/atril.js

@@ -7,14 +7,69 @@ import { graph } from "../src/graph.js";
 import { scan } from "../src/scan.js";
 import { SEARCH_MODE, search } from "../src/search.js";
 import { install, remove } from "../src/store.js";
+import { generate } from "../src/generate.js";
 import { readConfig } from "../src/config.js";
+import { expose, unexpose } from "../src/bridge.js";
+import { sync } from "../src/sync.js";
+import { blockPaths } from "../src/resolve.js";
+import { serve } from "../src/mcp.js";
+import { catalogSync } from "../src/fetch.js";
+import { installFromCatalog, isCatalogRef } from "../src/catalog-install.js";
+import { importSkills } from "../src/import.js";
 
 const USAGE = "Usage: atril --version\n       atril scan [--root <dir>] [--json]\n"
   + "       atril enrich [--root <dir>] [--check]\n       atril graph [<kind:name>] [--root <dir>] [--json]\n"
   + "       atril search <query> [--kind <kind>] [--root <dir>] [--json]\n"
   + "       atril route <task> [--role <role>] [--root <dir>] [--json]\n"
-  + "       atril install <path> [--kind <kind>] [--root <dir>]\n       atril remove <kind:name> [--root <dir>]\n"
-  + "       atril config [--root <dir>] [--json]";
+  + "       atril install <path | kind:name> [--kind <kind>] [--root <dir>]\n       atril remove <kind:name> [--root <dir>]\n"
+  + "       atril config [--root <dir>] [--json]\n"
+  + "       atril expose <kind:name>... [--root <dir>]\n       atril unexpose <kind:name>... [--root <dir>]\n"
+  + "       atril sync [--check] [--root <dir>]\n       atril mcp [--root <dir>]\n"
+  + "       atril catalog sync [--root <dir>]\n       atril import --from openskills [--root <dir>]";
+
+function runImport(args) {
+  const { values } = parseArgs({ args, options: { from: { type: "string" }, root: { type: "string" } } });
+  if (!values.from) throw new Error(`import needs --from\n${USAGE}`);
+  const done = importSkills(values.from, { root: values.root });
+  if (done.length === 0) console.log(`nothing to import from ${values.from}`);
+  for (const { kind, name, from, path } of done) console.log(`imported\t${kind}:${name}\t${from} -> ${path}`);
+}
+
+function runCatalog(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { root: { type: "string" } } });
+  if (positionals.join(" ") !== "sync") throw new Error(USAGE);
+  const done = catalogSync({ root: values.root });
+  if (done.length === 0) console.log("no git sources to fetch");
+  for (const { status, source, commit, catalog } of done) console.log(`${status}\t${source}@${commit.slice(0, 12)}\t${catalog}`);
+}
+
+async function runMcp(args) {
+  const { values } = parseArgs({ args, options: { root: { type: "string" } } });
+  await serve({ root: values.root });
+}
+
+function runSync(args) {
+  const { values } = parseArgs({ args, options: { root: { type: "string" }, check: { type: "boolean" } } });
+  const changed = sync({ root: values.root, check: values.check }).filter(({ action }) => action !== "unchanged");
+  for (const { action, path } of changed) console.log(`${action}\t${path}`);
+  if (values.check) {
+    if (changed.length > 0) {
+      console.error(`atril: ${changed.length} piece(s) out of date: run atril sync`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (changed.length === 0) console.log("up to date");
+  if (generate({ root: values.root })) console.log("rulesync generate: done");
+  else console.error("atril: run rulesync generate to reach your agents, or declare rulesync.generate: true in atril.json");
+}
+
+function runExpose(command, args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { root: { type: "string" } } });
+  if (positionals.length === 0) throw new Error(`${command} takes at least one kind:name\n${USAGE}`);
+  const done = (command === "expose" ? expose : unexpose)(positionals, { root: values.root });
+  for (const ref of done) console.log(`${command}d\t${ref}`);
+}
 
 function runConfig(args) {
   const { values } = parseArgs({ args, options: { root: { type: "string" }, json: { type: "boolean" } } });
@@ -33,6 +88,11 @@ function runStore(command, args) {
   const { values, positionals } = parseArgs({ args, options: { root: { type: "string" }, kind: { type: "string" } }, allowPositionals: true });
   if (positionals.length !== 1) throw new Error(`${command} takes exactly one argument\n${USAGE}`);
   const [ref] = positionals;
+  if (command === "install" && isCatalogRef(ref)) {
+    const { status, kind, name, path, catalog } = installFromCatalog(ref, { root: values.root });
+    console.log(`${status}\t${kind}:${name}\t${path}\tfrom ${printable(catalog)}`);
+    return;
+  }
   if (command === "install") {
     const { status, kind, name, path } = install(ref, { root: values.root, kind: values.kind });
     console.log(`${status}\t${kind}:${name}\t${path}`);
@@ -92,11 +152,6 @@ function runSearch(args) {
   for (const hit of hits) console.log(`${hit.score}\t${hit.kind}\t${printable(hit.name)}\t${hit.source}\t${printable(hit.description)}`);
 }
 
-// The files to read, not their content: a subagent carries its own block.
-const pathsOf = (block) => block.map(({ name, kind, path, as, block: own }) => ({
-  name, kind, path, as,
-  ...(own && { block: pathsOf(own) }),
-}));
 const printBlock = (block, indent = "") => {
   for (const item of block) {
     console.log(`${indent}${item.as}\t${printable(item.path)}`);
@@ -109,10 +164,18 @@ function runRoute(args) {
     args, allowPositionals: true,
     options: { role: { type: "string" }, root: { type: "string" }, json: { type: "boolean" } },
   });
-  const { block, suggested, left, reason } = resolve({ task: positionals.join(" "), role: values.role, root: values.root });
-  if (values.json) console.log(JSON.stringify({ block: pathsOf(block), suggested, left, ...(reason && { reason }) }, null, 2));
-  else if (reason) console.log(reason);
-  else printBlock(block);
+  const { block, suggested, left, reason, available } = resolve({ task: positionals.join(" "), role: values.role, root: values.root });
+  if (values.json) {
+    console.log(JSON.stringify({ block: blockPaths(block), suggested, left, available, ...(reason && { reason }) }, null, 2));
+    return;
+  }
+  if (reason) {
+    console.log(reason);
+  } else {
+    printBlock(block);
+  }
+  // Either way, what fits from the catalogs follows.
+  for (const { kind, name, catalog } of available) console.log(`available\t${kind}:${name}\tfrom ${printable(catalog)}`);
 }
 
 const [command, ...rest] = process.argv.slice(2);
@@ -125,6 +188,11 @@ try {
   else if (command === "route") runRoute(rest);
   else if (command === "install" || command === "remove") runStore(command, rest);
   else if (command === "config") runConfig(rest);
+  else if (command === "expose" || command === "unexpose") runExpose(command, rest);
+  else if (command === "sync") runSync(rest);
+  else if (command === "mcp") await runMcp(rest);
+  else if (command === "catalog") runCatalog(rest);
+  else if (command === "import") runImport(rest);
   else throw new Error(command ? `unknown command "${command}"\n${USAGE}` : USAGE);
 } catch (err) {
   console.error(`atril: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karajan-family/atril",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Skills, commands and subagents for every AI CLI, on demand: search, install and resolve the Markdown each task needs without loading it into the initial context.",
   "type": "module",
   "main": "src/index.js",
@@ -17,6 +17,9 @@
   "dependencies": {
     "js-yaml": "^4.2.0"
   },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
   "engines": {
     "node": ">=22.12.0"
   },

package/src/atomic.js

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+
+/** Write through a temp file and a rename, so a reader never sees half a file. */
+export function writeAtomic(path, text) {
+  // A random name created exclusively: "wx" fails on anything already there, a symlink included.
+  const temp = `${path}.${randomUUID()}.tmp`;
+  let created = false;
+  try {
+    writeFileSync(temp, text, { flag: "wx" });
+    created = true;
+    renameSync(temp, path);
+  } catch (err) {
+    if (created) rmSync(temp, { force: true });
+    throw err;
+  }
+}

package/src/bridge.js

@@ -0,0 +1,109 @@
+/**
+ * atril's persistent pieces (ADR 0021, decision 10; plan step 8): the bridge command, the router
+ * rule and the artifacts exposed in atril.json, each a path under `.rulesync/` plus its content.
+ * Writing them is the sync's job (step 9).
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { readConfig, writeConfig } from "./config.js";
+import { FRONTMATTER, KINDS } from "./model.js";
+import { keyOf, scan } from "./scan.js";
+
+export const MARKER = "<!-- atril:managed -->";
+const RULESYNC_DIR = { skill: "skills", command: "commands", agent: "subagents" };
+
+/** The marker goes right after the frontmatter, in the file's own newline style. */
+const withMarker = (text) => {
+  const match = FRONTMATTER.exec(text);
+  if (!match) throw new Error("a persistent piece needs frontmatter");
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const head = text.slice(0, text.length - match[2].length);
+  return `${head}${head.endsWith("\n") ? "" : eol}${MARKER}${eol}${match[2]}`;
+};
+
+const bridgeCommand = () => ({
+  path: "commands/atril.md",
+  content: withMarker(`---
+description: "Run any atril skill, command or agent: /atril <name or task>"
+targets: ["*"]
+---
+Run \`atril route --json "$ARGUMENTS"\` and follow the plan it prints:
+read each block's file in order and apply it to the task; run an entry
+of kind "subagent" as a subagent. If the route is empty, say so.
+`),
+});
+
+const routerRule = () => ({
+  path: "rules/atril-router.md",
+  content: withMarker(`---
+root: false
+targets: ["*"]
+description: "Ask atril which skills, commands and agents fit a task"
+globs: ["**/*"]
+---
+Before starting a task, run \`atril route "<the task>"\` and use what it
+returns. Run \`/atril <name>\` to load one artifact on demand.
+`),
+});
+
+/** A skill brings its whole folder; the marker goes only in SKILL.md. */
+function exposedPiece(artifact) {
+  const base = RULESYNC_DIR[artifact.kind];
+  const own = withMarker(readFileSync(artifact.path, "utf8"));
+  if (artifact.kind !== "skill") return [{ path: `${base}/${artifact.name}.md`, content: own }];
+  const folder = dirname(artifact.path);
+  const files = readdirSync(folder, { recursive: true, withFileTypes: true }).filter((dirent) => dirent.isFile());
+  return files.map((dirent) => join(dirent.parentPath, dirent.name)).toSorted().map((file) => {
+    const rel = relative(folder, file).split(sep).join("/");
+    const text = readFileSync(file, "utf8");
+    return { path: `${base}/${artifact.name}/${rel}`, content: rel === "SKILL.md" ? withMarker(text) : text };
+  });
+}
+
+/** @param {{ projectDir?: string, root?: string, userRoot?: string, env?: object }} [opts] */
+export function persistentPieces(opts) {
+  const { expose } = readConfig(opts);
+  const byKey = new Map(scan(opts).artifacts.map((artifact) => [keyOf(artifact), artifact]));
+  const pieces = [bridgeCommand(), routerRule()];
+  for (const kind of KINDS) {
+    for (const name of expose[kind]) {
+      const key = `${kind}:${name}`;
+      if (key === RESERVED) throw new Error(`atril.json exposes ${key}, reserved for the bridge: atril unexpose ${key}`);
+      if (!byKey.has(key)) throw new Error(`atril.json exposes ${key}, which is not in the store: atril unexpose ${key}`);
+      pieces.push(...exposedPiece(byKey.get(key)));
+    }
+  }
+  return pieces;
+}
+
+const RESERVED = "command:atril";
+const parseRef = (ref) => {
+  const [kind, name, extra] = String(ref).split(":");
+  if (extra !== undefined || !KINDS.includes(kind) || !name) {
+    throw new Error(`"${ref}" is not kind:name (kind one of ${KINDS.join(", ")})`);
+  }
+  return { kind, name, key: `${kind}:${name}` };
+};
+
+/** Record the refs in atril.json's expose, each checked against the store. Returns the refs. */
+export function expose(refs, opts) {
+  const parsed = refs.map(parseRef);
+  const held = new Set(scan(opts).artifacts.map(keyOf));
+  for (const { key } of parsed) {
+    if (key === RESERVED) throw new Error(`${key} is reserved for the bridge`);
+    if (!held.has(key)) throw new Error(`${key} is not in the store`);
+  }
+  const config = readConfig(opts);
+  for (const { kind, name } of parsed) if (!config.expose[kind].includes(name)) config.expose[kind].push(name);
+  writeConfig(config, opts);
+  return parsed.map(({ key }) => key);
+}
+
+/** Take the refs out of expose, unchecked on purpose: a removed artifact must stay retractable. */
+export function unexpose(refs, opts) {
+  const parsed = refs.map(parseRef);
+  const config = readConfig(opts);
+  for (const { kind, name } of parsed) config.expose[kind] = config.expose[kind].filter((item) => item !== name);
+  writeConfig(config, opts);
+  return parsed.map(({ key }) => key);
+}

package/src/catalog-install.js

@@ -0,0 +1,66 @@
+/**
+ * Install from a catalog (ADR 0021, decision 12; plan step 11c): `atril install kind:name`
+ * takes an available artifact into the store, through the same validated install as a local
+ * path. A fetched source's artifact comes from its pinned commit in the cache. An OpenSkills
+ * skill declares no kind; the store needs one, so the installed SKILL.md gets `kind: skill`.
+ */
+import { cpSync, lstatSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { availableArtifacts } from "./catalog.js";
+import { keyOf, scan } from "./scan.js";
+import { install } from "./store.js";
+
+const BOM = String.fromCodePoint(0xfeff);
+
+/** A catalog reference, as opposed to a local path. */
+export const isCatalogRef = (ref) => /^(skill|command|agent):[a-z0-9][a-z0-9._-]*$/.test(ref);
+
+/**
+ * @param {string} ref kind:name of an available artifact
+ * @param {{ projectDir?: string, root?: string, userRoot?: string, env?: object }} [opts]
+ * @returns {{ kind: string, name: string, path: string, status: string, catalog: string }}
+ */
+export function installFromCatalog(ref, opts = {}) {
+  const artifact = availableArtifacts(opts).find((candidate) => keyOf(candidate) === ref);
+  if (!artifact) {
+    const held = scan(opts).artifacts.some((candidate) => keyOf(candidate) === ref);
+    throw new Error(held ? `${ref} is already installed` : `${ref} is not in any catalog (atril catalog sync fetches the git sources)`);
+  }
+  if (artifact.kind === "skill") return { ...installSkillFolder(dirname(artifact.path), opts, artifact.kindDefaulted), catalog: artifact.catalog };
+  return { ...install(artifact.path, { ...opts, kind: artifact.kind }), catalog: artifact.catalog };
+}
+
+/**
+ * A skill folder that is a symlink, or holds one, is refused without following any link: run
+ * before reading, copying or rewriting anything in it, a link could reach outside the folder.
+ */
+export function refuseLinks(source) {
+  if (lstatSync(source).isSymbolicLink()) throw new Error(`${source}: an artifact may not be a symlink`);
+  const link = readdirSync(source, { recursive: true, withFileTypes: true }).find((entry) => entry.isSymbolicLink());
+  if (link) throw new Error(`${join(link.parentPath, link.name)}: a skill may not hold symlinks`);
+}
+
+/**
+ * Install a skill folder. One whose SKILL.md declares no kind (OpenSkills' format) is copied to
+ * a temporary folder whose SKILL.md gets `kind: skill` first, because the store needs a kind.
+ * @param {string} source the skill folder
+ * @param {object} opts install()'s options
+ * @param {boolean} [kindDefaulted] the SKILL.md declares no kind
+ */
+export function installSkillFolder(source, opts, kindDefaulted = false) {
+  refuseLinks(source);
+  if (!kindDefaulted) return install(source, { ...opts, kind: "skill" });
+  const stage = mkdtempSync(join(tmpdir(), "atril-install-"));
+  try {
+    const folder = join(stage, basename(source));
+    cpSync(source, folder, { recursive: true });
+    const file = join(folder, "SKILL.md");
+    const text = readFileSync(file, "utf8");
+    const bom = text.startsWith(BOM) ? BOM : "";
+    writeFileSync(file, bom + text.slice(bom.length).replace(/^(---(\r?\n))/, "$1kind: skill$2"));
+    return install(folder, { ...opts, kind: "skill" });
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}

package/src/catalog.js

@@ -0,0 +1,110 @@
+/**
+ * Catalogs (ADR 0021, decision 12; plan step 11a). Each entry of atril.json's `catalogs`,
+ * relative to the project, is either a folder in a store's layout (a bundled catalog, such as
+ * a consumer's own or the recommended set) or a JSON file of git sources:
+ * `{ "sources": [{ "source": "owner/repo[/path]", "commit": "<40 hex>", "note": "..." }] }`,
+ * each pinned to a commit and saying what it is for. What a catalog offers that the stores do
+ * not hold is "available": search shows it, installing it stays an explicit step.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, resolve as resolvePath } from "node:path";
+import { readConfig } from "./config.js";
+import { isMapping, parseArtifact } from "./model.js";
+import { keyOf, resolveRoot, scan, scanStore } from "./scan.js";
+
+const SEGMENT = /^[A-Za-z0-9_.-]+$/;
+const COMMIT = /^[0-9a-f]{40}$/;
+const isSource = (source) => typeof source === "string"
+  && source.split("/").length >= 2
+  && source.split("/").every((part) => SEGMENT.test(part) && part !== "." && part !== "..");
+
+function readSources(ref, file) {
+  const fail = (why, cause) => { throw new Error(`catalog "${ref}": ${why}`, { cause }); };
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    fail(`invalid JSON (${err.message})`, err);
+  }
+  if (!isMapping(raw) || !Array.isArray(raw.sources)) fail('must be { "sources": [...] }');
+  return raw.sources.map((entry, index) => {
+    if (!isMapping(entry)) fail(`sources[${index}] must be an object`);
+    const { source, commit, note } = entry;
+    if (!isSource(source)) fail(`source ${JSON.stringify(source)} is not owner/repo[/path]`);
+    if (typeof commit !== "string" || !COMMIT.test(commit)) fail(`source "${source}": commit must be 40 hex characters (a pinned commit)`);
+    if (typeof note !== "string" || !note.trim()) fail(`source "${source}": a note on what it is for is required`);
+    return { source, commit, note };
+  });
+}
+
+/** Where fetched sources live: under the store, never scanned as artifacts (a dot folder). */
+export const cacheRoot = ({ projectDir = process.cwd(), root, env = process.env } = {}) =>
+  join(resolvePath(projectDir, resolveRoot({ root, env })), ".cache", "catalogs");
+
+/** A source's pinned commit in the cache; owner and repo are validated segments. */
+export function sourceDir(opts, { source, commit }) {
+  const [owner, repo] = source.split("/");
+  return join(cacheRoot(opts), owner, repo, commit);
+}
+
+/** @param {{ projectDir?: string, root?: string, env?: object }} [opts] */
+export function catalogs(opts = {}) {
+  const projectDir = opts.projectDir ?? process.cwd();
+  return readConfig(opts).catalogs.map((ref) => {
+    const path = resolvePath(projectDir, ref);
+    if (!existsSync(path)) throw new Error(`catalog "${ref}": ${path} not found`);
+    if (statSync(path).isDirectory()) return { ref, type: "store", dir: path };
+    return { ref, type: "sources", sources: readSources(ref, path) };
+  });
+}
+
+/**
+ * A fetched source (step 11b): a store's layout, one OpenSkills skill folder, or a folder of
+ * them. A SKILL.md that declares no kind is a skill, and must be named after its folder.
+ */
+function scanFetched(dir, source) {
+  if (["skills", "commands", "agents"].some((kind) => existsSync(join(dir, kind)))) return scanStore(dir, source);
+  const skillAt = (folder) => {
+    const artifact = parseArtifact(join(folder, "SKILL.md"), { defaultKind: "skill" });
+    if (artifact.kind !== "skill" || artifact.name !== basename(folder)) {
+      throw new Error(`${folder}: a catalog skill must be kind skill and named after its folder, not "${artifact.name}"`);
+    }
+    return { ...artifact, source };
+  };
+  if (existsSync(join(dir, "SKILL.md"))) return [skillAt(dir)];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && existsSync(join(dir, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .toSorted()
+    .map((name) => skillAt(join(dir, name)));
+}
+
+/** The folders a catalog offers: a store catalog itself, or each source already fetched. */
+function offered(opts, catalog) {
+  if (catalog.type === "store") return [{ dir: catalog.dir, scanOf: scanStore }];
+  return catalog.sources
+    .map((entry) => join(sourceDir(opts, entry), ...entry.source.split("/").slice(2)))
+    .filter((dir) => existsSync(dir))
+    .map((dir) => ({ dir, scanOf: scanFetched }));
+}
+
+/**
+ * What the catalogs offer that the stores do not hold, each with its `catalog`. The first
+ * catalog listed wins a name two of them share; a source not fetched yet offers nothing.
+ * @param {Parameters<typeof scan>[0]} [opts]
+ * @param {object[]} [held] the stores' artifacts, when the caller already scanned them
+ */
+export function availableArtifacts(opts = {}, held = scan(opts).artifacts) {
+  const seen = new Set(held.map(keyOf));
+  const found = [];
+  for (const catalog of catalogs(opts)) {
+    for (const { dir, scanOf } of offered(opts, catalog)) {
+      for (const artifact of scanOf(dir, `catalog:${catalog.ref}`)) {
+        if (seen.has(keyOf(artifact))) continue;
+        seen.add(keyOf(artifact));
+        found.push({ ...artifact, catalog: catalog.ref });
+      }
+    }
+  }
+  return found;
+}

package/src/config.js

@@ -4,9 +4,9 @@
  * and the rulesync opt-in. An absent file is DEFAULT_CONFIG; a bad field
  * fails loudly, naming it. Writes are atomic and deterministic.
  */
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { writeAtomic } from "./atomic.js";
 import { isMapping, KINDS, SLUG, sortKeys } from "./model.js";
 import { resolveRoot } from "./scan.js";
 
@@ -85,16 +85,6 @@ export function writeConfig(config, opts) {
   const path = configPath(opts);
   const text = `${JSON.stringify(normalize(config, path), sortKeys, 2)}\n`;
   mkdirSync(dirname(path), { recursive: true });
-  // A random name created exclusively: "wx" fails on anything already there, a symlink included.
-  const temp = `${path}.${randomUUID()}.tmp`;
-  let created = false;
-  try {
-    writeFileSync(temp, text, { flag: "wx" });
-    created = true;
-    renameSync(temp, path);
-  } catch (err) {
-    if (created) rmSync(temp, { force: true });
-    throw err;
-  }
+  writeAtomic(path, text);
   return path;
 }

package/src/fetch.js

@@ -0,0 +1,60 @@
+/**
+ * atril catalog sync (ADR 0021, decision 12; plan step 11b): every git source of the catalogs
+ * is fetched into its cache folder (catalog.js `sourceDir`), at exactly its pinned commit, and
+ * nothing is installed. A cached commit is immutable, so it is fetched once. The fetch happens
+ * in a temporary folder renamed into place only once verified: a failure leaves nothing
+ * behind. Symlinks are checked out as plain files and no hook runs.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { catalogs, sourceDir } from "./catalog.js";
+
+const defaultGit = (args, cwd) => execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+// Never a hook, never a symlink, never a detached-HEAD lecture.
+const SAFE = ["-c", "core.hooksPath=/dev/null", "-c", "core.symlinks=false", "-c", "advice.detachedHead=false"];
+
+function fetchInto(target, url, commit, git) {
+  const temp = `${target}.${randomUUID()}.tmp`;
+  mkdirSync(temp, { recursive: true });
+  try {
+    git([...SAFE, "init", "--quiet"], temp);
+    git([...SAFE, "fetch", "--quiet", "--depth", "1", url, commit], temp);
+    git([...SAFE, "checkout", "--quiet", "FETCH_HEAD"], temp);
+    const head = git([...SAFE, "rev-parse", "HEAD"], temp).trim();
+    if (head !== commit) throw new Error(`got ${head}, not the pinned commit`);
+    rmSync(join(temp, ".git"), { recursive: true, force: true });
+    renameSync(temp, target);
+  } catch (err) {
+    rmSync(temp, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+/**
+ * @param {{ projectDir?: string, root?: string, env?: object }} [opts]
+ * @param {{ gitBase?: string, git?: (args: string[], cwd: string) => string }} [how] where
+ *   owner/repo lives (GitHub, as OpenSkills reads it) and how git runs; for tests
+ * @returns {{ catalog: string, source: string, commit: string, status: "fetched" | "cached" }[]}
+ */
+export function catalogSync(opts = {}, { gitBase = "https://github.com", git = defaultGit } = {}) {
+  const done = [];
+  for (const catalog of catalogs(opts).filter(({ type }) => type === "sources")) {
+    for (const { source, commit } of catalog.sources) {
+      const target = sourceDir(opts, { source, commit });
+      const status = existsSync(target) ? "cached" : "fetched";
+      if (status === "fetched") {
+        const [owner, repo] = source.split("/");
+        mkdirSync(dirname(target), { recursive: true });
+        try {
+          fetchInto(target, `${gitBase}/${owner}/${repo}.git`, commit, git);
+        } catch (err) {
+          throw new Error(`catalog "${catalog.ref}": ${source}@${commit.slice(0, 12)} could not be fetched (${err.message})`, { cause: err });
+        }
+      }
+      done.push({ catalog: catalog.ref, source, commit, status });
+    }
+  }
+  return done;
+}

package/src/generate.js

@@ -0,0 +1,30 @@
+/**
+ * rulesync generate (ADR 0021, decision 11; ADR 0022): run only when atril.json declares
+ * `rulesync.generate: true`, with the canonical arguments (whole generation), and never a package
+ * fetched on the fly: the project's own binary, or `npx --no-install`.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readConfig } from "./config.js";
+
+const ARGS = ["generate", "--targets", "*", "--features", "*"];
+const defaultRun = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+
+/**
+ * @param {{ projectDir?: string, root?: string, env?: object }} [opts]
+ * @param {(cmd: string, args: string[], cwd: string) => unknown} [run]
+ * @returns {boolean} whether rulesync generate ran
+ */
+export function generate(opts = {}, run = defaultRun) {
+  if (readConfig(opts).rulesync.generate !== true) return false;
+  const projectDir = opts.projectDir ?? process.cwd();
+  const local = join(projectDir, "node_modules", ".bin", "rulesync");
+  const [cmd, args] = existsSync(local) ? [local, ARGS] : ["npx", ["--no-install", "rulesync", ...ARGS]];
+  try {
+    run(cmd, args, projectDir);
+  } catch (err) {
+    throw new Error(`rulesync generate failed (${err.message}); the pieces are in .rulesync/, run it yourself`, { cause: err });
+  }
+  return true;
+}

package/src/import.js

@@ -0,0 +1,45 @@
+/**
+ * atril import --from openskills (ADR 0021, decision 12; plan step 11d): the skills OpenSkills
+ * installed into folders the CLIs load on their own (`.claude/skills`, `.agent/skills`) move
+ * into atril's store, where they are used on demand. Each one leaves its folder only once it
+ * is installed (or the store already holds it, same content); a refusal keeps the original.
+ */
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { installSkillFolder, refuseLinks } from "./catalog-install.js";
+import { parseArtifact } from "./model.js";
+
+const SOURCES = { openskills: [join(".claude", "skills"), join(".agent", "skills")] };
+
+/**
+ * @param {string} from where the skills come from: "openskills"
+ * @param {{ projectDir?: string, root?: string, env?: object }} [opts]
+ * @returns {{ kind: string, name: string, path: string, status: string, from: string }[]}
+ */
+export function importSkills(from, opts = {}) {
+  if (!Object.hasOwn(SOURCES, from)) throw new Error(`atril imports from ${Object.keys(SOURCES).join(", ")}, not "${from}"`);
+  const projectDir = opts.projectDir ?? process.cwd();
+  const done = [];
+  for (const rel of SOURCES[from]) {
+    const base = join(projectDir, rel);
+    if (!existsSync(base)) continue;
+    // A symlinked entry stays in the list so refuseLinks() refuses it out loud, before any read.
+    const entries = readdirSync(base, { withFileTypes: true })
+      .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith("."))
+      .map((entry) => entry.name)
+      .toSorted();
+    for (const name of entries) {
+      const folder = join(base, name);
+      refuseLinks(folder);
+      if (!existsSync(join(folder, "SKILL.md"))) continue;
+      const artifact = parseArtifact(join(folder, "SKILL.md"), { defaultKind: "skill" });
+      if (artifact.kind !== "skill" || artifact.name !== name) {
+        throw new Error(`${folder}: an imported skill must be kind skill and named after its folder, not "${artifact.name}"`);
+      }
+      const result = installSkillFolder(folder, opts, Boolean(artifact.kindDefaulted));
+      rmSync(folder, { recursive: true });
+      done.push({ ...result, from: join(rel, name) });
+    }
+  }
+  return done;
+}

package/src/index.js

@@ -8,3 +8,10 @@ import { readFileSync } from "node:fs";
 export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 export { search } from "./search.js";
 export { resolve, resolveBlock } from "./resolve.js";
+export { MARKER, expose, persistentPieces, unexpose } from "./bridge.js";
+export { sync } from "./sync.js";
+export { generate } from "./generate.js";
+export { install, remove } from "./store.js";
+export { catalogSync } from "./fetch.js";
+export { installFromCatalog } from "./catalog-install.js";
+export { importSkills } from "./import.js";

package/src/ledger.js

@@ -0,0 +1,78 @@
+/**
+ * The ownership ledger of `.rulesync/` (ADR 0022, decision 3), atril's own implementation of the
+ * contract it shares with kj and the user (ADR 0021, decision 11: no code shared with the core).
+ * `.rulesync/.owners.json` is { version: 1, entries: { "<posix path under .rulesync>[#block]":
+ * { owner, hash: "sha256:<hex>" } } }, changed only under `.rulesync/.owners.lock` and written
+ * atomically, in the same layout kj writes it, so the two writers never churn the file.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomic } from "./atomic.js";
+import { isMapping } from "./model.js";
+
+export const LEDGER_FILE = join(".rulesync", ".owners.json");
+export const LOCK_FILE = join(".rulesync", ".owners.lock");
+export const OWNER = "atril";
+export const USER_OWNER = "user";
+const VERSION = 1;
+const HASH = /^sha256:[0-9a-f]{64}$/;
+
+export const hashContent = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+
+function validate(file, ledger) {
+  if (ledger?.version !== VERSION) throw new Error(`${file}: version ${ledger?.version} is not supported (expected ${VERSION})`);
+  if (!isMapping(ledger.entries)) throw new Error(`${file}: entries must be an object of key to { owner, hash }`);
+  for (const [key, entry] of Object.entries(ledger.entries)) {
+    if (typeof entry?.owner !== "string" || !entry.owner || !HASH.test(entry.hash)) {
+      throw new Error(`${file}: entry "${key}" needs a non-empty owner and a sha256:<hex> hash`);
+    }
+  }
+}
+
+/** The ledger, or an empty one when absent; a broken, malformed or unknown one fails loudly. */
+export function readLedger(projectDir) {
+  const file = join(projectDir, LEDGER_FILE);
+  if (!existsSync(file)) return { version: VERSION, entries: {} };
+  let ledger;
+  try {
+    ledger = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(`${file}: not valid JSON (${err.message})`, { cause: err });
+  }
+  validate(file, ledger);
+  return ledger;
+}
+
+function takeLock(lock) {
+  try {
+    writeFileSync(lock, `${OWNER} ${process.pid}`, { flag: "wx" });
+  } catch (err) {
+    if (err.code === "ENOENT") throw new Error(`${lock}: .rulesync/ is missing (run rulesync init)`, { cause: err });
+    if (err.code !== "EEXIST") throw err;
+    let holder = "unknown";
+    try { holder = readFileSync(lock, "utf8").trim() || holder; } catch { /* released meanwhile */ }
+    throw new Error(`${lock}: held by ${holder}, another writer is updating the ledger; retry when it ends `
+      + `(if no writer is running, delete ${lock})`, { cause: err });
+  }
+}
+
+/**
+ * Read, change and write the ledger under its lock. A change that throws, or leaves an entry
+ * malformed, writes nothing; a lock left by a crashed writer is never stolen.
+ * @param {string} projectDir
+ * @param {(ledger: object) => void} change - mutates the ledger in place
+ */
+export function withLedger(projectDir, change) {
+  const lock = join(projectDir, LOCK_FILE);
+  takeLock(lock);
+  try {
+    const ledger = readLedger(projectDir);
+    change(ledger);
+    validate(join(projectDir, LEDGER_FILE), ledger);
+    writeAtomic(join(projectDir, LEDGER_FILE), JSON.stringify(ledger, null, 2));
+    return ledger;
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}

package/src/mcp.js

@@ -0,0 +1,94 @@
+/**
+ * atril mcp (ADR 0021, plan step 14): the store's search, resolve, install and remove as MCP tools
+ * over stdio. The store is fixed when the server starts (`atril mcp --root <dir>`): a tool call
+ * never chooses it. A failed call comes back as an error result; the server stays up. No MCP SDK:
+ * four methods over JSON lines do not justify its dependency tree in a package that installs offline.
+ */
+import { createInterface } from "node:readline";
+import { VERSION } from "./index.js";
+import { KINDS } from "./model.js";
+import { blockPaths, resolve } from "./resolve.js";
+import { SEARCH_MODE, search } from "./search.js";
+import { install, remove } from "./store.js";
+
+const kind = { type: "string", enum: KINDS };
+const text = (description) => ({ type: "string", description });
+const input = (properties, required) => ({ type: "object", properties, required, additionalProperties: false });
+
+export const TOOLS = [
+  { name: "search", description: "Search atril's store for skills, commands and agents",
+    inputSchema: input({ query: text("what to look for"), kind }, ["query"]) },
+  { name: "resolve", description: "The artifacts that fit a task, as the files to read in order",
+    inputSchema: input({ task: text("the task at hand"), role: text("the role that will use them") }, ["task"]) },
+  { name: "install", description: "Install a local skill folder, command or agent file into the store",
+    inputSchema: input({ path: text("the skill folder or .md file"), kind }, ["path"]) },
+  { name: "remove", description: "Remove an artifact from the store",
+    inputSchema: input({ kind, name: text("the artifact's name") }, ["kind", "name"]) },
+];
+
+const string = (args, field, required = false) => {
+  if (args[field] === undefined && !required) return undefined;
+  if (typeof args[field] !== "string" || !args[field].trim()) throw new Error(`${field} must be a non-empty string`);
+  return args[field];
+};
+
+const HANDLERS = {
+  search: (args, opts) => ({ mode: SEARCH_MODE, hits: search(string(args, "query", true), { ...opts, kind: string(args, "kind") }) }),
+  resolve: (args, opts) => {
+    const result = resolve({ ...opts, task: string(args, "task", true), role: string(args, "role") });
+    return { ...result, block: blockPaths(result.block) };
+  },
+  install: (args, opts) => install(string(args, "path", true), { ...opts, kind: string(args, "kind") }),
+  remove: (args, opts) => remove(string(args, "name", true), { ...opts, kind: string(args, "kind", true) }),
+};
+
+/** One tool call: its result as JSON text, or its error as an error result. */
+export function callTool(name, args, opts) {
+  try {
+    if (!Object.hasOwn(HANDLERS, name)) throw new Error(`unknown tool "${name}"`);
+    return { content: [{ type: "text", text: JSON.stringify(HANDLERS[name](args ?? {}, opts), null, 2) }] };
+  } catch (err) {
+    return { isError: true, content: [{ type: "text", text: `atril: ${err.message}` }] };
+  }
+}
+
+// The protocol versions this server speaks; a client asking for another gets the latest.
+const PROTOCOLS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+
+function answer({ method, params }, opts) {
+  if (method === "initialize") {
+    const protocolVersion = PROTOCOLS.includes(params?.protocolVersion) ? params.protocolVersion : PROTOCOLS[0];
+    return { protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "atril", version: VERSION } };
+  }
+  if (method === "ping") return {};
+  if (method === "tools/list") return { tools: TOOLS };
+  if (method === "tools/call") return callTool(params?.name, params?.arguments, opts);
+  throw Object.assign(new Error(`method "${method}" not found`), { code: -32601 });
+}
+
+/**
+ * MCP's stdio transport: one JSON-RPC message per line. A notification (no id) needs no answer.
+ * @param {{ root?: string, projectDir?: string }} opts the store, fixed for the server's life
+ * @returns {Promise<void>} settles when the input closes
+ */
+export function serve(opts, { input = process.stdin, output = process.stdout } = {}) {
+  const send = (message) => output.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ id: null, error: { code: -32700, message: "parse error" } });
+      return;
+    }
+    if (message?.id === undefined) return;
+    try {
+      send({ id: message.id, result: answer(message, opts) });
+    } catch (err) {
+      send({ id: message.id, error: { code: err.code ?? -32603, message: err.message } });
+    }
+  });
+  return new Promise((done) => lines.on("close", done));
+}

package/src/model.js

@@ -54,8 +54,10 @@ function validate(path, front) {
  * Parse and validate one artifact file. Invalid frontmatter fails loudly,
  * naming the file and the field.
  * @param {string} path
+ * @param {{ defaultKind?: string }} [opts] the kind of a file that declares none: catalog
+ *   sources in OpenSkills' format write a SKILL.md without `kind` (step 11b)
  */
-export function parseArtifact(path) {
+export function parseArtifact(path, { defaultKind } = {}) {
   const match = FRONTMATTER.exec(readFileSync(path, "utf8").replace(/^\uFEFF/, ""));
   if (!match) throw new Error(`${path}: no frontmatter (--- … --- lines at the top)`);
   let front;
@@ -64,6 +66,8 @@ export function parseArtifact(path) {
   } catch (err) {
     throw new Error(`${path}: invalid frontmatter (${err.message})`, { cause: err });
   }
+  const kindDefaulted = defaultKind !== undefined && isMapping(front) && front.kind === undefined;
+  if (kindDefaulted) front = { ...front, kind: defaultKind };
   validate(path, front);
   const body = match[2];
   const { atril = {}, ...author } = front;
@@ -77,5 +81,7 @@ export function parseArtifact(path) {
     atril,
     body,
     hash,
+    // The file itself declares no kind (an OpenSkills skill): installing it must write one.
+    ...(kindDefaulted && { kindDefaulted }),
   };
 }

package/src/resolve.js

@@ -146,10 +146,20 @@ export function resolve({ task, role, budget = {}, projectDir, root, userRoot, e
   if (typeof task !== "string" || !task.trim()) throw new Error("resolve needs a non-empty task");
   if (role !== undefined && (typeof role !== "string" || !role.trim())) throw new Error("role must be a non-empty string");
   const byKey = new Map(scan(scanOpts).artifacts.map((a) => [keyOf(a), a]));
-  const best = search(task, scanOpts).find((hit) => servesRole(byKey.get(keyOf(hit)), role));
+  const hits = search(task, scanOpts);
+  const best = hits.find((hit) => hit.installed && servesRole(byKey.get(keyOf(hit)), role));
+  // Step 11a: what fits from the catalogs is proposed, never loaded; installing stays explicit.
+  const available = hits.filter((hit) => !hit.installed).slice(0, 3)
+    .map(({ name, kind, description, catalog }) => ({ name, kind, description, catalog }));
   if (!best) {
     const reason = `no artifact matches ${JSON.stringify(task)}${role === undefined ? "" : ` for role ${role}`}`;
-    return { block: [], suggested: [], left: [], reason };
+    return { block: [], suggested: [], left: [], reason, available };
   }
-  return resolveBlock(keyOf(best), scanOpts, budget);
+  return { ...resolveBlock(keyOf(best), scanOpts, budget), available };
 }
+
+/** A block as the files to read, not their content: a subagent carries its own block. */
+export const blockPaths = (block) => block.map(({ name, kind, path, as, block: own }) => ({
+  name, kind, path, as,
+  ...(own && { block: blockPaths(own) }),
+}));

package/src/search.js

@@ -4,6 +4,7 @@
  * A query term scores by the field it appears in, the name weighing most
  * and the body least; ties break on kind, then name.
  */
+import { availableArtifacts } from "./catalog.js";
 import { KINDS } from "./model.js";
 import { keyOf, scan } from "./scan.js";
 
@@ -30,20 +31,25 @@ const scoreOf = (fields, terms) =>
   Object.entries(WEIGHTS).reduce((sum, [field, weight]) => sum + weight * terms.filter((term) => fields[field].has(term)).length, 0);
 
 /**
+ * The stores' artifacts, and (step 11a) what the catalogs offer, marked `installed: false`
+ * with its `catalog`.
  * @param {string} query
- * @param {{ kind?: string } & Parameters<typeof scan>[0]} [opts] the rest goes to scan()
- * @returns {{ name: string, kind: string, description: string, source: string, installed: boolean, score: number }[]}
+ * @param {{ kind?: string, catalogs?: boolean } & Parameters<typeof scan>[0]} [opts] the rest goes to scan()
+ * @returns {{ name: string, kind: string, description: string, source: string, installed: boolean, score: number, catalog?: string }[]}
  */
-export function search(query, { kind, ...scanOpts } = {}) {
+export function search(query, { kind, catalogs: withCatalogs = true, ...scanOpts } = {}) {
   const terms = typeof query === "string" ? [...tokenize(query)] : [];
   if (terms.length === 0) throw new Error("search needs a non-empty query");
   if (kind !== undefined && !KINDS.includes(kind)) throw new Error(`kind ${JSON.stringify(kind)} is not one of ${KINDS.join(", ")}`);
-  return scan(scanOpts)
-    .artifacts.filter((artifact) => kind === undefined || artifact.kind === kind)
+  const { artifacts } = scan(scanOpts);
+  const pool = withCatalogs ? [...artifacts, ...availableArtifacts(scanOpts, artifacts)] : artifacts;
+  return pool
+    .filter((artifact) => kind === undefined || artifact.kind === kind)
     .map((artifact) => ({ artifact, score: scoreOf(fieldsOf(artifact), terms) }))
     .filter(({ score }) => score > 0)
     .toSorted((a, b) => b.score - a.score || (keyOf(a.artifact) < keyOf(b.artifact) ? -1 : 1))
-    .map(({ artifact: { name, kind: artifactKind, description, source }, score }) => ({
-      name, kind: artifactKind, description, source, installed: true, score,
+    .map(({ artifact: { name, kind: artifactKind, description, source, catalog }, score }) => ({
+      name, kind: artifactKind, description, source, installed: catalog === undefined, score,
+      ...(catalog !== undefined && { catalog }),
     }));
 }

package/src/sync.js

@@ -0,0 +1,94 @@
+/**
+ * atril sync (ADR 0021, decision 11; plan step 9b): write the persistent pieces into `.rulesync/`
+ * through the ownership ledger of ADR 0022. Every piece is judged before anything is written, so
+ * a hand edit, a user's file or another writer's entry stops the whole sync with nothing changed.
+ * A piece no longer wanted is removed when it is still as atril wrote it.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeAtomic } from "./atomic.js";
+import { MARKER, persistentPieces } from "./bridge.js";
+import { hashContent, OWNER, readLedger, withLedger } from "./ledger.js";
+
+const RULESYNC = ".rulesync";
+// A key atril writes: a whole file under one of rulesync's kind folders, never `..` nor a block.
+const OWN_KEY = /^(commands|rules|skills|subagents)\/[^#]+$/;
+const ownKey = (key) => OWN_KEY.test(key) && !key.split("/").some((part) => part === "" || part === "." || part === "..");
+
+/** What happens to one key; throws on anything atril must not touch. */
+function judge(key, entry, current, wanted) {
+  const file = join(RULESYNC, key);
+  if (!ownKey(key)) throw new Error(`"${key}" is not a path atril writes; fix .rulesync/.owners.json`);
+  if (entry && entry.owner !== OWNER) throw new Error(`${file}: belongs to ${entry.owner}; atril will not touch it`);
+  // Already gone and no longer wanted: only its entry is left to drop.
+  if (entry && current === null && wanted === undefined) return "removed";
+  if (entry && (current === null || hashContent(current) !== entry.hash)) {
+    throw new Error(`${file}: edited by hand (or deleted) since atril wrote it; atril will not overwrite it. `
+      + "Restore it as it was, or move your change into atril's store");
+  }
+  if (!entry && current !== null && !current.includes(MARKER)) {
+    throw new Error(`${file}: not written by atril; atril will not write over it`);
+  }
+  if (wanted === undefined) return "removed";
+  if (!entry) return current === null ? "written" : "claimed";
+  return current === wanted ? "unchanged" : "written";
+}
+
+const readOrNull = (path) => (existsSync(path) ? readFileSync(path, "utf8") : null);
+
+// A symlink anywhere below .rulesync/ would carry a write outside it: refused before any write.
+function refuseSymlinks(projectDir, key) {
+  let at = join(projectDir, RULESYNC);
+  for (const part of key.split("/")) {
+    at = join(at, part);
+    if (lstatSync(at, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      throw new Error(`${join(RULESYNC, key)}: ${at} is a symlink; atril writes only inside .rulesync/`);
+    }
+  }
+}
+
+/** Every step of a sync, judged and nothing written. */
+export function plan(projectDir, ledger, wanted) {
+  const stale = Object.entries(ledger.entries).filter(([key, { owner }]) => owner === OWNER && !wanted.has(key));
+  return [...wanted.keys(), ...stale.map(([key]) => key)].map((key) => {
+    if (ownKey(key)) refuseSymlinks(projectDir, key);
+    const current = readOrNull(join(projectDir, RULESYNC, key));
+    return { path: key, action: judge(key, ledger.entries[key], current, wanted.get(key)) };
+  });
+}
+
+// After removing a skill's file, its folders go too while empty, up to the kind folder.
+function pruneEmpty(start, stop) {
+  for (let at = start; at !== stop && existsSync(at) && readdirSync(at).length === 0; at = dirname(at)) rmdirSync(at);
+}
+
+/**
+ * @param {{ projectDir?: string, root?: string, userRoot?: string, env?: object, check?: boolean }} [opts]
+ * @returns {{ path: string, action: "written"|"claimed"|"removed"|"unchanged" }[]}
+ */
+export function sync(opts = {}) {
+  const projectDir = opts.projectDir ?? process.cwd();
+  if (!existsSync(join(projectDir, RULESYNC))) {
+    throw new Error(`${projectDir}: no .rulesync/; atril installs nothing persistent without rulesync (run rulesync init)`);
+  }
+  const wanted = new Map(persistentPieces({ ...opts, projectDir }).map(({ path, content }) => [path, content]));
+  // --check (step 9c): the same judgment, read-only and without the lock.
+  if (opts.check) return plan(projectDir, readLedger(projectDir), wanted);
+  let steps;
+  withLedger(projectDir, (ledger) => {
+    steps = plan(projectDir, ledger, wanted);
+    for (const { path, action } of steps) {
+      const target = join(projectDir, RULESYNC, path);
+      if (action === "removed") {
+        rmSync(target, { force: true });
+        pruneEmpty(dirname(target), join(projectDir, RULESYNC, path.split("/")[0]));
+        delete ledger.entries[path];
+      } else if (action !== "unchanged") {
+        mkdirSync(dirname(target), { recursive: true });
+        writeAtomic(target, wanted.get(path));
+        ledger.entries[path] = { owner: OWNER, hash: hashContent(wanted.get(path)) };
+      }
+    }
+  });
+  return steps;
+}