feat(specs): make built-in inventory visibility configurable

docs/as-built/cli-reference.md

@@ -628,7 +628,7 @@ Only Claude and Codex tenures can be woken.
 | Invocation | Aliases | Declared options |
 |---|---|---|
 | `rig specs` | — | — |
-| `rig specs ls` | — | `--kind <kind>`<br>`--json` |
+| `rig specs ls` | — | `--kind <kind>`<br>`--include-builtins`<br>`--json` |
 | `rig specs show <name-or-id>` | — | `--kind <kind>`<br>`--json` |
 | `rig specs preview <name-or-id>` | — | `--kind <kind>`<br>`--json` |
 | `rig specs add <path>` | — | `--json` |

docs/reference/rig-spec.md

@@ -1274,3 +1274,15 @@ These are the built-in specs shipped with OpenRig. Read them as worked examples.
 Also shipped, in the same tree: `launch/kernel`, OpenRig's own team, which starts automatically. `first-project` is
 starter's old name and still resolves to it. `workshop`, the four-agent middle team, is a rig bundle rather than a
 built-in. List the built-ins with `rig specs ls --kind rig`.
+
+To omit built-in rigs, agents and workflows from the shared spec inventory, run
+`rig config set specs.builtins_visible false`. This changes the CLI, TUI and other
+consumers of the library listing; user specs remain visible. Use
+`rig specs ls --include-builtins` to list them deliberately, and set the value
+back to `true` to restore the default. Explicit `show`, `preview`, and launch
+lookups can still find hidden built-ins. When built-ins are hidden and a user
+spec has the same name, the user spec wins the name lookup; use the built-in's
+ID from `rig specs ls --include-builtins --json` to select it. With built-ins visible,
+same-name matches remain ambiguous. This is an inventory preference, not an
+access-control boundary; other endpoints and on-disk files can still expose the
+built-ins.

packages/cli/src/commands/config.ts

@@ -69,6 +69,7 @@ Keys:
   topology.root          the topology tree root (instance altitude at its top; default $OPENRIG_HOME/topology)
   context.root           addressable context library for 'rig context add' (default $OPENRIG_HOME/context)
   context.system_world   default System World, replacement manifest path, or disabled
+  specs.builtins_visible show built-ins in spec inventory (default true)
   skills.root            versioned skill catalog (default $OPENRIG_HOME/skills)
   skills.router_line.enabled  the person's yes to the seat-skills line (one line plus OpenRig's markers) in AGENTS.md / CLAUDE.md (default false)
   onboarding.default_pack.enabled  deliver the two-part fresh-seat mental-model pack (default on)

packages/cli/src/commands/specs.ts

@@ -157,21 +157,25 @@ export async function resolveLibrarySpec(
   nameOrId: string,
   opts?: { kind?: string },
 ): Promise<LibraryEntry> {
-  const res = await client.get<LibraryEntry[]>(
-    opts?.kind !== undefined ? `/api/specs/library?kind=${encodeURIComponent(opts.kind)}` : "/api/specs/library",
-  );
-  const rawEntries = res.data ?? [];
-  const entries =
+  const url = opts?.kind !== undefined ? `/api/specs/library?kind=${encodeURIComponent(opts.kind)}` : "/api/specs/library";
+  const res = await client.get<LibraryEntry[]>(url);
+  const filterKind = (entries: LibraryEntry[]) =>
     opts?.kind !== undefined && !KNOWN_SPEC_KINDS.includes(opts.kind as (typeof KNOWN_SPEC_KINDS)[number])
-      ? rawEntries.filter((e) => e.kind === opts.kind)
-      : rawEntries;
-
-  // Try exact ID match first
+      ? entries.filter((entry) => entry.kind === opts.kind)
+      : entries;
+  const visibleEntries = filterKind(res.data ?? []);
+  // An exact ID always wins, including when a visible name matches a hidden ID.
+  const visibleId = visibleEntries.find((entry) => entry.id === nameOrId);
+  if (visibleId) return visibleId;
+  const separator = opts?.kind !== undefined ? "&" : "?";
+  const all = await client.get<LibraryEntry[]>(`${url}${separator}include_builtins=true`);
+  const entries = filterKind(all.data ?? []);
   const byId = entries.find((e) => e.id === nameOrId);
   if (byId) return byId;
 
-  // Try name match
-  const byName = entries.filter((e) => e.name === nameOrId);
+  // Visible names take precedence over hidden built-ins with the same name.
+  const visibleNames = visibleEntries.filter((e) => e.name === nameOrId);
+  const byName = visibleNames.length ? visibleNames : entries.filter((e) => e.name === nameOrId);
   if (byName.length === 1) return byName[0]!;
 
   if (byName.length > 1) {
@@ -230,12 +234,16 @@ Examples:
   cmd.command("ls")
     .description("List library rigs, agents, and managed apps")
     .option("--kind <kind>", "Filter by kind (rig, agent, or workflow)")
+    .option("--include-builtins", "Include built-ins hidden by the visibility setting")
     .option("--json", "JSON output")
-    .action(async (opts: { kind?: string; json?: boolean }) => {
+    .action(async (opts: { kind?: string; json?: boolean; includeBuiltins?: boolean }) => {
       try {
         warnIfUnknownKind(opts.kind);
         const client = await getClient();
-        const url = opts.kind !== undefined ? `/api/specs/library?kind=${encodeURIComponent(opts.kind)}` : "/api/specs/library";
+        const params = new URLSearchParams();
+        if (opts.kind !== undefined) params.set("kind", opts.kind);
+        if (opts.includeBuiltins) params.set("include_builtins", "true");
+        const url = `/api/specs/library${params.size ? `?${params}` : ""}`;
         const res = await client.get<LibraryEntry[]>(url);
         if (res.status !== 200) throw new Error(`Daemon returned HTTP ${res.status}`);
         const rawEntries = res.data ?? [];

packages/cli/src/commands/topology-default-agent.ts

@@ -11,7 +11,7 @@ interface AgentLibraryEntry {
 /** Resolve the runtime's terminal seat or the shipped general-purpose agent. */
 export async function resolveDefaultAgentRef(client: DaemonClient, runtime: string): Promise<string> {
   if (runtime === "terminal") return "builtin:terminal";
-  const res = await client.get<AgentLibraryEntry[]>("/api/specs/library?kind=agent");
+  const res = await client.get<AgentLibraryEntry[]>("/api/specs/library?kind=agent&include_builtins=true");
   const entry = res.data?.find(
     (candidate) =>
       candidate.kind === "agent"

packages/cli/src/config-store.ts

@@ -13,6 +13,7 @@ import {
 // truth at ~/.openrig/config.json. Resolution stays env > file > default.
 
 export interface RiggedConfig {
+  specs: { builtinsVisible: boolean };
   launch: { nonInterruptive: boolean };
   daemon: { port: number; host: string; dbConflict?: "warn" | "stop" };
   // OPR.0.4.6.MH1 FR-1 — the persisted host-selection pointer.
@@ -283,6 +284,7 @@ const DEFAULTS = {
   topology: { root: getDefaultOpenRigPath("topology") },
   // OPR.0.5.9.5 Wave B — canonical addressable context library.
   context: { root: getDefaultOpenRigPath("context"), systemWorld: "default" },
+  specs: { builtinsVisible: true },
   skills: { root: getDefaultOpenRigPath("skills"), routerLine: { enabled: false } },
   onboarding: { defaultPack: { enabled: true } },
   health: { contextPressure: { warningPercent: 95, criticalPercent: 99 } },
@@ -454,6 +456,7 @@ export const VALID_KEYS = [
   // OPR.0.5.9.5 Wave B — canonical context library; old key is refused.
   "context.root",
   "context.system_world",
+  "specs.builtins_visible",
   "skills.root",
   // OPR.0.7.0.13 (router): the person's recorded yes to OpenRig's one-line seat-skills bootstrap in AGENTS.md / CLAUDE.md.
   "skills.router_line.enabled",
@@ -581,6 +584,7 @@ export const ENV_MAP: Record<ValidKey, { primary: string; legacy?: string }> = {
   "topology.root": { primary: "OPENRIG_TOPOLOGY_ROOT" },
   "context.root": { primary: "OPENRIG_CONTEXT_ROOT" },
   "context.system_world": { primary: "OPENRIG_CONTEXT_SYSTEM_WORLD" },
+  "specs.builtins_visible": { primary: "OPENRIG_SPECS_BUILTINS_VISIBLE" },
   "skills.root": { primary: "OPENRIG_SKILLS_ROOT" },
   "skills.router_line.enabled": { primary: "OPENRIG_SKILLS_ROUTER_LINE_ENABLED" },
   "onboarding.default_pack.enabled": { primary: "OPENRIG_ONBOARDING_DEFAULT_PACK_ENABLED" },
@@ -688,6 +692,7 @@ const KEY_TO_PATH: Record<ValidKey, string[]> = {
   "topology.root": ["topology", "root"],
   "context.root": ["context", "root"],
   "context.system_world": ["context", "systemWorld"],
+  "specs.builtins_visible": ["specs", "builtinsVisible"],
   "skills.root": ["skills", "root"],
   "skills.router_line.enabled": ["skills", "routerLine", "enabled"],
   "onboarding.default_pack.enabled": ["onboarding", "defaultPack", "enabled"],
@@ -1259,6 +1264,7 @@ export class ConfigStore {
         root: v("context.root") as string,
         systemWorld: v("context.system_world") as string,
       },
+      specs: { builtinsVisible: v("specs.builtins_visible") as boolean },
       skills: {
         root: v("skills.root") as string,
         routerLine: { enabled: v("skills.router_line.enabled") as boolean },

packages/cli/test/bootstrap-source-paths.test.ts

@@ -46,7 +46,7 @@ describe("bootstrap source paths respect the daemon target", () => {
     // The responder reads relative paths from a different root, like an already-running daemon.
     server = http.createServer(async (req, res) => {
       res.setHeader("Content-Type", "application/json");
-      if (req.url === "/api/specs/library") {
+      if (req.url === "/api/specs/library" || req.url === "/api/specs/library?include_builtins=true") {
         catalogReads++;
         res.end(JSON.stringify(catalog));
         return;
@@ -184,15 +184,15 @@ describe("bootstrap source paths respect the daemon target", () => {
     ("preserves catalog source paths (explicit URL=%s, plan=%s)", async (explicitUrl, plan) => {
       if (explicitUrl) vi.stubEnv("OPENRIG_URL", daemonUrl);
       await run("bootstrap", "catalog-rig", [plan ? "--plan" : "--yes"]);
-      expect(catalogReads).toBe(1);
+      expect(catalogReads).toBe(2);
       expect(requests[0]?.sourceRef).toBe(catalog[0]!.sourcePath);
       expect(requests[0]?.content).toBe("name: daemon\n");
     });
 
   it.each([false, true])("preserves unresolved bare-name fallback (explicit URL=%s)", async (explicitUrl) => {
     if (explicitUrl) vi.stubEnv("OPENRIG_URL", daemonUrl);
     await run("bootstrap", "unlisted", ["--plan"]);
-    expect(catalogReads).toBe(1);
+    expect(catalogReads).toBe(2);
     expect(requests[0]?.sourceRef).toBe("unlisted");
   });
 
@@ -208,7 +208,7 @@ describe("bootstrap source paths respect the daemon target", () => {
     if (explicitUrl) vi.stubEnv("OPENRIG_URL", daemonUrl);
     catalog.push({ ...catalog[0]!, id: "other-id", sourcePath: path.join(callerDir, "rig.yaml") });
     await run("bootstrap", "catalog-rig", ["--plan"]);
-    expect(catalogReads).toBe(1);
+    expect(catalogReads).toBe(2);
     expect(requests).toEqual([]);
     expect(process.exitCode).toBe(1);
   });

packages/cli/test/bootstrap.test.ts

@@ -400,7 +400,7 @@ describe("Bootstrap CLI", () => {
       let body = "";
       req.on("data", (chunk: Buffer) => { body += chunk; });
       req.on("end", () => {
-        if (url === "/api/specs/library") {
+        if (url === "/api/specs/library" || url === "/api/specs/library?include_builtins=true") {
           res.writeHead(200, { "Content-Type": "application/json" });
           res.end(JSON.stringify([{ id: "lib1", name: "my-lib-rig", sourcePath: "/specs/my-lib-rig.yaml", kind: "rig", version: "0.2", sourceType: "user_file" }]));
         } else if (url.includes("/api/bootstrap")) {

packages/cli/test/config-store-extended.test.ts

@@ -138,6 +138,7 @@ describe("ConfigStore — extended namespaces (User Settings v0)", () => {
       "topology.root",
       "context.root",
       "context.system_world",
+      "specs.builtins_visible",
       "skills.root",
       "skills.router_line.enabled",
       "onboarding.default_pack.enabled",

packages/cli/test/config.test.ts

@@ -63,6 +63,14 @@ describe("ConfigStore", () => {
   });
 
   // Test 1
+  it("persists the built-in inventory preference as a validated boolean", () => {
+    const store = new ConfigStore(join(tmpDir, "config.json"));
+    expect(store.resolveOne("specs.builtins_visible").value).toBe(true);
+    store.set("specs.builtins_visible", "false");
+    expect(store.resolve().specs.builtinsVisible).toBe(false);
+    expect(() => store.set("specs.builtins_visible", "no")).toThrow();
+  });
+
   it("resolve() returns defaults when no config file and no env", () => {
     const store = new ConfigStore(join(tmpDir, "config.json"));
     const config = store.resolve();

packages/cli/test/specs-alias.test.ts

@@ -7,6 +7,23 @@ const clientFor = (entries: object[]) => ({ get: vi.fn(async () => ({ status: 20
 afterEach(() => vi.restoreAllMocks());
 
 describe("first-project compatibility alias", () => {
+  it("keeps same-name user and built-in specs ambiguous when both are visible", async () => {
+    const user = { ...starter, id: "user-id", sourceType: "user_file" };
+    await expect(resolveLibrarySpec(clientFor([starter, user]), "starter", { kind: "rig" })).rejects.toThrow("ambiguous");
+  });
+  it("finds an explicitly requested hidden built-in without shadowing a visible user spec", async () => {
+    const user = { ...starter, id: "user-id", sourceType: "user_file" };
+    const get = vi.fn(async (url: string) => ({ status: 200, data: url.includes("include_builtins=true") ? [starter, user] : [user] }));
+    const client = { get } as unknown as DaemonClient;
+    expect(await resolveLibrarySpec(client, "starter", { kind: "rig" })).toEqual(user);
+    expect(await resolveLibrarySpec(client, "starter-id", { kind: "rig" })).toEqual(starter);
+    expect(get).toHaveBeenCalledWith("/api/specs/library?kind=rig&include_builtins=true");
+  });
+  it("prefers a hidden exact ID over a visible spec with that name", async () => {
+    const user = { ...starter, id: "user-id", name: "starter-id", sourceType: "user_file" };
+    const get = vi.fn(async (url: string) => ({ status: 200, data: url.includes("include_builtins=true") ? [starter, user] : [user] }));
+    expect(await resolveLibrarySpec({ get } as unknown as DaemonClient, "starter-id")).toEqual(starter);
+  });
   it("resolves the built-in starter without creating a second library entry, with a stderr notice", async () => {
     const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
     const stdout = vi.spyOn(console, "log").mockImplementation(() => {});

packages/cli/test/specs.test.ts

@@ -60,6 +60,7 @@ const RIG_REVIEW = {
 describe("Specs CLI", () => {
   let server: http.Server;
   let port: number;
+  let lastLibraryUrl = "";
   const libraryRequests: string[] = [];
 
   beforeAll(async () => {
@@ -68,6 +69,7 @@ describe("Specs CLI", () => {
       libraryRequests.push(rawUrl);
       const url = decodeURIComponent(rawUrl);
       if (url === "/api/specs/library" || url.startsWith("/api/specs/library?")) {
+        lastLibraryUrl = url;
         res.writeHead(200, { "Content-Type": "application/json" });
         const kind = new URL(`http://localhost${url}`).searchParams.get("kind");
         const filtered = kind ? LIBRARY_ENTRIES.filter((e) => e.kind === kind) : LIBRARY_ENTRIES;
@@ -137,6 +139,13 @@ describe("Specs CLI", () => {
     expect(parsed.length).toBe(2);
   });
 
+  it("requests hidden built-ins only when explicitly asked", async () => {
+    await captureLogs(async () => { await makeCmd().parseAsync(["node", "rig", "specs", "ls", "--include-builtins", "--kind", "rig"]); });
+    const params = new URL(`http://localhost${lastLibraryUrl}`).searchParams;
+    expect(params.get("kind")).toBe("rig");
+    expect(params.get("include_builtins")).toBe("true");
+  });
+
   it("specs ls --kind warns on unrecognized kind and still queries daemon", async () => {
     const requestStart = libraryRequests.length;
     const { stdout, stderr, exitCode } = await captureOutputs(async () => {
@@ -165,6 +174,16 @@ describe("Specs CLI", () => {
     expect(libraryRequests.slice(requestStart)).toContain("/api/specs/library?kind=rig%23draft");
   });
 
+  it("filters an unknown kind even when built-ins are requested", async () => {
+    const { stdout, stderr } = await captureOutputs(async () => {
+      await makeCmd().parseAsync(["node", "rig", "specs", "ls", "--kind", "rig&kind=agent", "--include-builtins", "--json"]);
+    });
+    expect(stderr.join("\n")).toContain("Warning: unrecognized --kind");
+    expect(JSON.parse(stdout.join("\n"))).toEqual([]);
+    expect(new URL(`http://localhost${libraryRequests.at(-1)}`).searchParams.get("kind")).toBe("rig&kind=agent");
+    expect(new URL(`http://localhost${libraryRequests.at(-1)}`).searchParams.get("include_builtins")).toBe("true");
+  });
+
   it.each(["rig", "agent", "workflow"])("specs ls --kind %s runs without warning", async (kind) => {
     const requestStart = libraryRequests.length;
     const { stderr, exitCode } = await captureOutputs(async () => {
@@ -231,7 +250,7 @@ describe("Specs CLI", () => {
   it("specs show --kind resolves same-name rig/workflow entries", async () => {
     const dupServer = http.createServer((req, res) => {
       const url = decodeURIComponent(req.url ?? "");
-      if (url === "/api/specs/library?kind=rig") {
+      if (url.startsWith("/api/specs/library?kind=rig")) {
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify([{ ...LIBRARY_ENTRIES[0], id: "rig-same", kind: "rig", name: "conveyor" }]));
       } else {

packages/cli/test/topology-default-agent.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import type { DaemonClient } from "../src/client.js";
+import { resolveDefaultAgentRef } from "../src/commands/topology-default-agent.js";
+
+describe("default agent lookup", () => {
+  it("finds the built-in orchestrator when inventory hides built-ins", async () => {
+    const client = {
+      get: async (url: string) => ({
+        data: url.includes("include_builtins=true")
+          ? [{ kind: "agent", name: "orchestrator", sourceType: "builtin", sourcePath: "/builtin/orchestrator/agent.yaml" }]
+          : [],
+      }),
+    } as unknown as DaemonClient;
+    expect(await resolveDefaultAgentRef(client, "codex")).toBe("path:/builtin/orchestrator");
+  });
+});

packages/cli/test/up.test.ts

@@ -1408,7 +1408,7 @@ describe("Up CLI", () => {
       let body = "";
       for await (const chunk of req) body += chunk;
       const url = decodeURIComponent(req.url ?? "");
-      if (url === "/api/specs/library?kind=rig") {
+      if (url.startsWith("/api/specs/library?kind=rig")) {
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify([{ id: "rig1", kind: "rig", name: "conveyor", sourceType: "builtin", sourcePath: "/specs/rigs/conveyor/rig.yaml" }]));
       } else if (url === "/api/rigs/summary") {

packages/daemon/src/domain/spec-library-workflow-scanner.ts

@@ -401,6 +401,8 @@ export interface ScanWorkflowSpecFolderOpts {
    *  its source file disappeared (OQ-4 acceptance: deletion + audit log).
    *  Omitted in unit tests that don't care about emission. */
   eventBus?: EventBus;
+  /** A user file with the same bytes and identity as an existing built-in row. */
+  onBuiltinAlias?: (name: string, version: string, sourcePath: string, sourceHash: string) => void;
 }
 
 export interface ScanWorkflowSpecFolderResult {
@@ -498,7 +500,11 @@ export function scanWorkflowSpecFolder(
     // validation error), record a diagnostic row keyed by source_path
     // so the Library UI can render the error inline.
     try {
-      opts.cache.readThrough(filePath);
+      const cached = opts.cache.readThrough(filePath);
+      if (opts.onBuiltinAlias && opts.builtinDir && cached.sourcePath !== filePath
+          && isUnderDir(cached.sourcePath, opts.builtinDir)) {
+        opts.onBuiltinAlias(cached.name, cached.version, filePath, cached.sourceHash);
+      }
       result.valid += 1;
     } catch (err) {
       // Diagnostic: hash the raw content best-effort so we can detect