pi-skill-router 0.2.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,60 @@
+# Pi Skill Router
+
+`pi-skill-router` routes to **externally hosted skill collections**. It clones skill repositories into a user-level managed directory, wraps the skills you select as hidden leaves behind a visible gateway, exposes them to Pi, and provides focused routing suggestions.
+
+**Package version:** 0.1.0
+
+The package ships no skill content itself, and routed collections are never npm packages — they are plain Git repositories you add through the `/skill-router` menu.
+
+## Installation
+
+This package has not yet been released to npm. Install it from a local checkout:
+
+```bash
+pi install /path/to/pi-packages/packages/skill-router
+```
+
+## How It Works
+
+```
+~/.pi/agent/skill-router/
+├── collections.json      # registry: source, selection, routing terms
+├── cache/                # raw git clones (upstream content, unmodified)
+└── exposed/              # materialized router output
+    └── collections/
+        └── <collection>/
+            ├── gateway/
+            │   └── SKILL.md            # generated gateway (the only skill Pi sees in `/`)
+            └── leaves/                 # private sub-skills (suggested by router, hidden from `/`)
+                └── <leaf>/SKILL.md
+```
+
+1. **Add**: `/skill-router` → *Add collection* → enter `owner/repo[@ref]`, a GitHub URL, or a local path. The repo is shallow-cloned into `cache/`, scanned for `SKILL.md` files, and you choose which skills to route (or all). No prefix is required.
+2. **Describe and materialize**: after selecting skills, confirm a short capability summary for the whole collection. The suggested text is derived from the selected skill names; edit it to describe the collection's domain and tasks rather than its Git source. The summary becomes the gateway's frontmatter description. Selected skills are saved into `exposed/collections/<collection>/leaves/<name>/`, while the single visible gateway is created in `exposed/collections/<collection>/gateway/SKILL.md`. Keeping the gateway and leaves in one atomic collection tree prevents partial materialization. Its body indexes the selected workflows with descriptions and exact relative leaf paths. Sub-skills remain clean without synthetic name prefixes.
+3. **Expose**: on session start and `/reload`, the extension answers Pi's `resources_discover` event with only the gateway directory, so only `/skill:<gateway>` appears in Pi's slash-command menu. Sub-skills do not clutter `/`.
+4. **Route**: when a prompt matches a route, `before_agent_start` appends a focused suggestion naming the exact sub-skill `SKILL.md` path for the agent to read. Your message is never rewritten. The gateway is the sole slash command; sub-skills are never slash commands.
+
+## Managing Collections
+
+Everything runs through the `/skill-router` menu:
+
+- **Add collection** — clone a repo, pick skills, install.
+- **Update collection** — pull upstream and re-materialize the preserved selection. New upstream skills are reported but stay unrouted until you explicitly select them.
+- **Change routed skills** — add currently available upstream skills to an installed collection's explicit selection.
+- **Edit capability summary** — revise the gateway description for an installed collection, then re-materialize its gateway.
+- **Remove collection** — delete the exposed skills and registry entry (the cached clone is kept).
+- **Enable/disable collection** — toggle exposure and routing without removing anything.
+- **List collections** — show installed collections.
+
+Routing terms are derived from skill names and stored in `~/.pi/agent/skill-router/collections.json`; edit that file to refine terms or collection descriptions. A collection description should be a high-level account of the selected workflows' shared capability, not installation details such as the repository name or gateway mechanics.
+
+## Guarantees
+
+- Gateway names are unique across collections; duplicate upstream skill names inside one collection fail the install instead of colliding.
+- Materialization is atomic (temporary directory + rename); a failed install leaves no partial exposed directory.
+- Invalid registry entries fail closed: they are ignored for both exposure and routing.
+- Only skills you selected are ever exposed.
+
+## Security
+
+Skills are instructions the model follows and may bundle scripts. Review a repository's skills before adding it — installing a collection means trusting its content at user level across all projects.

package/index.ts

@@ -0,0 +1,31 @@
+import type { BeforeAgentStartEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { routerRoot } from "./src/paths";
+import { loadCollections } from "./src/registry";
+import { isExplicitSkillInvocation, routePrompt, routingGuidance } from "./src/router";
+import { exposedSkillPaths } from "./src/sync";
+import { showSkillRouterMenu } from "./src/menu";
+
+export default function skillRouter(pi: ExtensionAPI): void {
+  pi.on("resources_discover", () => ({
+    skillPaths: exposedSkillPaths(routerRoot()),
+  }));
+
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+    if (isExplicitSkillInvocation(event.prompt)) return;
+
+    const skills = event.systemPromptOptions.skills ?? [];
+    const match = routePrompt(event.prompt, loadCollections(routerRoot()), new Map(skills.map((skill) => [skill.name, skill])));
+    if (!match) return;
+
+    return { systemPrompt: `${event.systemPrompt}\n\n${routingGuidance(match)}` };
+  });
+
+  pi.registerCommand("skill-router", {
+    description: "Manage externally hosted skill collections (add, update, remove, toggle, list)",
+    handler: async (_args, ctx) => {
+      await showSkillRouterMenu(ctx);
+    },
+  });
+}
+
+export { routePrompt };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-skill-router",
+  "version": "0.2.0",
+  "description": "Route to externally hosted skill collections: clone GitHub skill repos, wrap them as hidden leaves behind visible gateways, and get focused suggestions",
+  "keywords": [
+    "pi-package",
+    "skills",
+    "skill-router",
+    "routing"
+  ],
+  "author": "Frad LEE <fradser@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FradSer/pi-packages.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@fradser/pi-kit": "0.4.2"
+  }
+}

package/src/menu.ts

@@ -0,0 +1,286 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { CancellableLoader, truncateToWidth } from "@earendil-works/pi-tui";
+import { createPiThemeStyle, notifyPi, renderPiPanel } from "@fradser/pi-kit";
+import { routerRoot } from "./paths";
+import { loadCollections } from "./registry";
+import {
+  addCollection,
+  collectionSkillNames,
+  fetchCollectionSkills,
+  parseRepoSpec,
+  removeCollection,
+  setCollectionEnabled,
+  updateCollection,
+  updateCollectionDescription,
+  updateCollectionSelection,
+  defaultCollectionId,
+  generateWorkflowSummaries,
+  suggestCollectionDescription,
+  type UpstreamSkill,
+} from "./sync";
+
+const RELOAD_HINT = "Run /reload (or restart pi) to apply skill changes.";
+
+type LoadingOutcome<T> =
+  | { status: "success"; value: T }
+  | { status: "error"; error: unknown };
+
+async function runWithLoading<T>(ctx: ExtensionCommandContext, message: string, action: () => T | Promise<T>): Promise<T> {
+  if (!ctx.hasUI) return action();
+
+  const outcome = await ctx.ui.custom<LoadingOutcome<T>>((tui, theme, _keybindings, done) => {
+    const style = createPiThemeStyle(theme);
+    const loader = new CancellableLoader(
+      tui,
+      style.accent,
+      style.muted,
+      message,
+    );
+    loader.start();
+    setTimeout(() => {
+      Promise.resolve()
+        .then(action)
+        .then(
+          (value) => {
+            loader.stop();
+            done({ status: "success", value });
+          },
+          (error) => {
+            loader.stop();
+            done({ status: "error", error });
+          },
+        );
+    }, 0);
+    return {
+      render: (width) => renderPiPanel({
+        width,
+        style,
+        fit: truncateToWidth,
+        title: "Skill Router",
+        body: loader.render(Math.max(1, width - 2)),
+        footer: "esc cancel",
+      }),
+      invalidate: () => {},
+      dispose: () => loader.stop(),
+    };
+  }, {
+    overlay: true,
+    overlayOptions: {
+      anchor: "bottom-center",
+      width: "100%",
+      margin: { bottom: 4 },
+    },
+  });
+
+  if (outcome.status === "error") throw outcome.error;
+  return outcome.value;
+}
+
+async function pickSkills(ctx: ExtensionCommandContext, skills: UpstreamSkill[]): Promise<string[] | "all" | undefined> {
+  const all = await ctx.ui.confirm("Skill selection", `Route all ${skills.length} skills found in this repository?`);
+  if (all) return "all";
+
+  const remaining = new Map(skills.map((skill) => [skill.name, skill]));
+  const selected: string[] = [];
+  while (remaining.size > 0) {
+    const choice = await ctx.ui.select(
+      `Select skills to route (${selected.length} selected)`,
+      [...[...remaining.keys()], "Finish selection"],
+    );
+    if (choice === undefined || choice === "Finish selection") break;
+    remaining.delete(choice);
+    selected.push(choice);
+  }
+  return selected.length > 0 ? selected : undefined;
+}
+
+async function addFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const root = routerRoot();
+  const repo = await ctx.ui.input("Add collection", "owner/repo[@ref], GitHub URL, or local path");
+  if (!repo) return;
+
+  let fetched: { cache: string; ref: string; skills: UpstreamSkill[] };
+  try {
+    const spec = parseRepoSpec(repo);
+    fetched = await runWithLoading(
+      ctx,
+      `Cloning and scanning ${spec.repo}...`,
+      () => fetchCollectionSkills(root, spec),
+    );
+    if (fetched.skills.length === 0) {
+      notifyPi(ctx.ui, `No skills (SKILL.md with name and description) found in ${spec.repo}.`, "warning");
+      return;
+    }
+  } catch (error) {
+    notifyPi(ctx.ui, `Failed to fetch repository: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return;
+  }
+
+  const defaultId = defaultCollectionId(parseRepoSpec(repo));
+  const customId = await ctx.ui.input(
+    `Collection skill name (default: ${defaultId})`,
+    defaultId,
+  );
+  if (customId === undefined) return;
+  const id = customId.trim() || defaultId;
+
+  const selection = await pickSkills(ctx, fetched.skills);
+  if (!selection) return;
+
+  const selectedSkills = selection === "all"
+    ? fetched.skills
+    : fetched.skills.filter((skill) => selection.includes(skill.name));
+  const summaries = await runWithLoading(
+    ctx,
+    "Creating workflow navigation...",
+    () => generateWorkflowSummaries(ctx.modelRegistry, ctx.model, selectedSkills, ctx.signal),
+  );
+  const suggestedDescription = suggestCollectionDescription(selectedSkills);
+  const customDescription = await ctx.ui.input(
+    "Collection capability summary",
+    suggestedDescription,
+  );
+  if (customDescription === undefined) return;
+  const description = customDescription.trim() || suggestedDescription;
+
+  try {
+    const result = await runWithLoading(
+      ctx,
+      `Installing ${repo}...`,
+      () => addCollection(root, { repo, id, description, skills: selection, summaries }),
+    );
+    notifyPi(ctx.ui, `Installed "${result.id}" with ${result.skills.length} skills. ${RELOAD_HINT}`, "info");
+  } catch (error) {
+    notifyPi(ctx.ui, `Failed to install collection: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}
+
+async function pickCollection(ctx: ExtensionCommandContext, action: string) {
+  const collections = loadCollections(routerRoot());
+  if (collections.length === 0) {
+    notifyPi(ctx.ui, "No collections installed. Use Add collection first.", "warning");
+    return;
+  }
+  const choice = await ctx.ui.select(
+    `${action}: choose a collection`,
+    collections.map((collection) => `${collection.id} (${collection.routes.length} skills${collection.enabled ? "" : ", disabled"})`),
+  );
+  if (!choice) return;
+  return collections.find((collection) => choice.startsWith(`${collection.id} (`));
+}
+
+async function selectionFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collection = await pickCollection(ctx, "Change routed skills");
+  if (!collection) return;
+  try {
+    const upstream = collectionSkillNames(routerRoot(), collection.id);
+    const selected = new Set(collection.routes.map((route) => route.skill));
+    const remaining = upstream.filter((name) => !selected.has(name));
+    if (remaining.length === 0) {
+      notifyPi(ctx.ui, "All upstream skills are already selected.", "info");
+      return;
+    }
+    while (remaining.length > 0) {
+      const choice = await ctx.ui.select(
+        `Add skills to ${collection.id} (${selected.size} selected)`,
+        [...remaining, "Finish selection"],
+      );
+      if (!choice || choice === "Finish selection") break;
+      selected.add(choice);
+      remaining.splice(remaining.indexOf(choice), 1);
+    }
+    if (selected.size === collection.routes.length) return;
+    const result = await updateCollectionSelection(routerRoot(), collection.id, [...selected]);
+    notifyPi(ctx.ui, `Updated "${result.id}" with ${result.selected.length} routed skills. ${RELOAD_HINT}`, "info");
+  } catch (error) {
+    notifyPi(ctx.ui, `Selection update failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}
+
+async function descriptionFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collection = await pickCollection(ctx, "Edit capability summary");
+  if (!collection) return;
+  const description = await ctx.ui.input("Collection capability summary", collection.description);
+  if (description === undefined) return;
+  try {
+    updateCollectionDescription(routerRoot(), collection.id, description);
+    notifyPi(ctx.ui, `Updated "${collection.id}" capability summary. ${RELOAD_HINT}`, "info");
+  } catch (error) {
+    notifyPi(ctx.ui, `Capability summary update failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}
+
+async function updateFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collection = await pickCollection(ctx, "Update collection");
+  if (!collection) return;
+  try {
+    const result = await runWithLoading(
+      ctx,
+      `Updating ${collection.id}...`,
+      () => updateCollection(routerRoot(), collection.id),
+    );
+    const notes = [`Updated "${result.id}": ${result.kept.length} skills re-materialized.`];
+    if (result.dropped.length > 0) notes.push(`Removed upstream: ${result.dropped.join(", ")}.`);
+    if (result.newUpstream.length > 0) notes.push(`New upstream skills not routed: ${result.newUpstream.join(", ")}.`);
+    notifyPi(ctx.ui, `${notes.join(" ")} ${RELOAD_HINT}`, "info");
+  } catch (error) {
+    notifyPi(ctx.ui, `Update failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}
+
+async function removeFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collection = await pickCollection(ctx, "Remove collection");
+  if (!collection) return;
+  const confirmed = await ctx.ui.confirm("Remove collection", `Remove "${collection.id}" and its exposed skills? The cached clone is kept.`);
+  if (!confirmed) return;
+  try {
+    removeCollection(routerRoot(), collection.id);
+    notifyPi(ctx.ui, `Removed "${collection.id}". ${RELOAD_HINT}`, "info");
+  } catch (error) {
+    notifyPi(ctx.ui, `Remove failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}
+
+async function toggleFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collection = await pickCollection(ctx, "Enable/disable collection");
+  if (!collection) return;
+  const updated = setCollectionEnabled(routerRoot(), collection.id, !collection.enabled);
+  notifyPi(ctx.ui, `"${updated.id}" is now ${updated.enabled ? "enabled" : "disabled"}. ${RELOAD_HINT}`, "info");
+}
+
+async function listFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const collections = loadCollections(routerRoot());
+  if (collections.length === 0) {
+    notifyPi(ctx.ui, "No collections installed.", "info");
+    return;
+  }
+  await ctx.ui.select(
+    "Installed collections (esc to go back)",
+    collections.map(
+      (collection) =>
+        `${collection.id} — ${collection.source.repo}@${collection.source.ref} — ${collection.routes.length} skills — ${collection.enabled ? "enabled" : "disabled"}`,
+    ),
+  );
+}
+
+export async function showSkillRouterMenu(ctx: ExtensionCommandContext): Promise<void> {
+  for (;;) {
+    const action = await ctx.ui.select("Skill Router", [
+      "Add collection",
+      "Update collection",
+      "Change routed skills",
+      "Edit capability summary",
+      "Remove collection",
+      "Enable/disable collection",
+      "List collections",
+    ]);
+    if (action === undefined) return;
+    if (action === "Add collection") await addFlow(ctx);
+    else if (action === "Update collection") await updateFlow(ctx);
+    else if (action === "Change routed skills") await selectionFlow(ctx);
+    else if (action === "Edit capability summary") await descriptionFlow(ctx);
+    else if (action === "Remove collection") await removeFlow(ctx);
+    else if (action === "Enable/disable collection") await toggleFlow(ctx);
+    else await listFlow(ctx);
+  }
+}

package/src/paths.ts

@@ -0,0 +1,42 @@
+import os from "node:os";
+import { join } from "node:path";
+
+export function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(os.homedir(), ".pi", "agent");
+}
+
+export function routerRoot(): string {
+  return join(agentDir(), "skill-router");
+}
+
+export function registryPath(root: string): string {
+  return join(root, "collections.json");
+}
+
+export function cacheDir(root: string, cacheKey: string): string {
+  return join(root, "cache", cacheKey);
+}
+
+export function exposedDir(root: string, collectionId: string): string {
+  return join(root, "exposed", "collections", collectionId);
+}
+
+export function legacyExposedDir(root: string, collectionId: string): string {
+  return join(root, "exposed", collectionId);
+}
+
+export function gatewayDir(root: string, collectionId: string, _gateway: string): string {
+  return join(exposedDir(root, collectionId), "gateway");
+}
+
+export function leafSkillsDir(root: string, collectionId: string): string {
+  return join(exposedDir(root, collectionId), "leaves");
+}
+
+export function leafSkillDir(root: string, collectionId: string, skillName: string): string {
+  return join(leafSkillsDir(root, collectionId), skillName);
+}
+
+export function leafSkillFile(root: string, collectionId: string, skillName: string): string {
+  return join(leafSkillDir(root, collectionId, skillName), "SKILL.md");
+}

package/src/registry.ts

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { registryPath } from "./paths";
+
+export interface RegistryRoute {
+  skill: string;
+  path: string;
+  terms: string[];
+  summary?: string;
+}
+
+export interface CollectionSource {
+  repo: string;
+  url: string;
+  ref: string;
+  cacheKey: string;
+}
+
+export interface RegistryCollection {
+  id: string;
+  gateway: string;
+  mode: "suggest";
+  enabled: boolean;
+  description: string;
+  source: CollectionSource;
+  routes: RegistryRoute[];
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const RESERVED_COLLECTION_IDS = new Set(["collections"]);
+
+export function isSlug(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+
+export function isCollectionId(value: unknown): value is string {
+  return isSlug(value) && !RESERVED_COLLECTION_IDS.has(value);
+}
+
+function isSafeRelativePath(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    !value.startsWith("/") &&
+    !value.includes("\\") &&
+    !value.split("/").includes("..")
+  );
+}
+
+function parseRoute(value: unknown): RegistryRoute | undefined {
+  if (!isRecord(value) || !isSlug(value.skill) || !isSafeRelativePath(value.path)) return;
+  if (!Array.isArray(value.terms)) return;
+  const terms = value.terms.filter((term): term is string => typeof term === "string" && term.trim().length > 0);
+  if (typeof value.summary !== "undefined" && (typeof value.summary !== "string" || !value.summary.trim())) return;
+  return terms.length > 0 ? { skill: value.skill, path: value.path, terms, summary: value.summary?.trim() } : undefined;
+}
+
+export function isSafeGitRef(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) &&
+    !value.includes("..") &&
+    !value.includes("//") &&
+    !value.endsWith(".") &&
+    !value.endsWith("/")
+  );
+}
+
+function isSafeSourceUrl(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0")) return false;
+  return /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\.git$/.test(value)
+    || value.startsWith("/");
+}
+
+function isSafeCacheKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value) &&
+    !value.includes("..")
+  );
+}
+
+function parseSource(value: unknown): CollectionSource | undefined {
+  if (!isRecord(value)) return;
+  const { repo, url, cacheKey } = value;
+  if (typeof repo !== "string" || !isSafeSourceUrl(url) || !isSafeGitRef(value.ref)) return;
+  if (!repo || !isSafeCacheKey(cacheKey)) return;
+  const ref = value.ref;
+  return { repo, url, ref, cacheKey };
+}
+
+function parseCollection(value: unknown): RegistryCollection | undefined {
+  if (!isRecord(value)) return;
+  if (!isCollectionId(value.id) || !isSlug(value.gateway) || value.mode !== "suggest") return;
+  if (typeof value.description !== "string" || !Array.isArray(value.routes)) return;
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") return;
+  const source = parseSource(value.source);
+  if (!source) return;
+
+  const parsedRoutes = value.routes.map(parseRoute);
+  if (parsedRoutes.some((route) => route === undefined)) return;
+  const routes = parsedRoutes as RegistryRoute[];
+  const routeSkillNames = routes.map((route) => route.skill);
+  if (new Set(routeSkillNames).size !== routeSkillNames.length) return;
+
+  return {
+    id: value.id,
+    gateway: value.gateway,
+    mode: "suggest",
+    enabled: value.enabled !== false,
+    description: value.description,
+    source,
+    routes,
+  };
+}
+
+/** Load the registry, dropping structurally invalid entries and duplicate gateways or ids. */
+export function loadCollections(root: string): RegistryCollection[] {
+  const path = registryPath(root);
+  if (!existsSync(path)) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return [];
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.collections)) return [];
+
+  const collections = parsed.collections
+    .map(parseCollection)
+    .filter((collection): collection is RegistryCollection => collection !== undefined);
+
+  const idCounts = new Map<string, number>();
+  const gatewayCounts = new Map<string, number>();
+  const cacheCounts = new Map<string, number>();
+  const sourceCounts = new Map<string, number>();
+  for (const collection of collections) {
+    idCounts.set(collection.id, (idCounts.get(collection.id) ?? 0) + 1);
+    gatewayCounts.set(collection.gateway, (gatewayCounts.get(collection.gateway) ?? 0) + 1);
+    cacheCounts.set(collection.source.cacheKey, (cacheCounts.get(collection.source.cacheKey) ?? 0) + 1);
+    const sourceKey = `${collection.source.url}\0${collection.source.ref}`;
+    sourceCounts.set(sourceKey, (sourceCounts.get(sourceKey) ?? 0) + 1);
+  }
+  return collections.filter((collection) => {
+    const sourceKey = `${collection.source.url}\0${collection.source.ref}`;
+    return (
+      idCounts.get(collection.id) === 1 &&
+      gatewayCounts.get(collection.gateway) === 1 &&
+      cacheCounts.get(collection.source.cacheKey) === 1 &&
+      sourceCounts.get(sourceKey) === 1
+    );
+  });
+}
+
+export function saveCollections(root: string, collections: RegistryCollection[]): void {
+  const path = registryPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  writeFileSync(temporary, `${JSON.stringify({ collections }, null, 2)}\n`, "utf8");
+  renameSync(temporary, path);
+}