docs: spec — templates create Cabinets, libraries extend them

[oxedom]

Design spec only. No code changes. Lowest priority of the three current specs.

The taxonomy

Two catalogs look alike but do different things:

• Template → POST /api/registry/import scaffolds a new Cabinet. A bootstrap.
• Library → POST /api/agents/library/[slug]/add copies one part into an existing Cabinet. An extend.

The boundary is the action, not the size of the thing. A single merged "Gallery" was considered and rejected: it hides the one distinction that matters at click time — does this create a Cabinet, or add to the one I'm in? See ADR-0003.

Today "template" means three different things in code and "getting started" means two.

Scope

• Kill the template overload (resolveAgentTemplateDir → resolveLibraryAgentDir, response keys, and the four duplicate LibraryTemplate declarations collapsed to one export). RegistryTemplate keeps its name — it's a genuine template.
• Empty-state discovery: "＋ Add from Agent Library" / "＋ Add from Job Library" at the point of need.
• A Templates sidebar rail entry next to Integrations.
• Extend preview to the Home carousel.

What verification cut

Most of the draft. Checked line-by-line against the code:

• Preview already exists. RegistryBrowser has rendered a full org chart from /api/registry/[slug] since before this spec — the route already returns agents[], jobs[], children[], and README. No manifest change needed. Only the Home carousel imports blind, so this work is a fraction of what was drafted.
• Import is already transactional (github-fetch.ts:109-112, import/route.ts:82-86). The draft's "possible bug" was wrong.
• /api/agents/library has three consumers, not two — the draft missed use-agent-picker.ts:27.

Cut from scope: the resources/getting-started rename

Production-breaking for too little value:

• prepare-electron-package.mjs:252 hardcodes "getting-started", and its copyDirectory (:133-141) opens with if (!(await pathExists(fromPath))) return; — a missing source is a no-op, not an error. So the rename produces a green electron:make that ships a .seed with no guide content. No build error, no test failure.
• Proof the drift is already live: :253 copies resources/example-cabinet-carousel-factory, which does not exist. It has been silently skipping for some time.

The bigger bug found underneath (follow-up, not fixed here)

seedGettingStartedDir is already a no-op in every packaged build. PROJECT_ROOT = process.cwd() (runtime-config.ts:5) is not derived from resourcesPath/__dirname, main.cjs spawns the standalone server with no cwd, and .next/standalone contains no resources/. Packaged installs seed one guide at the data root via .seed; dev seeds one per Cabinet. Dev and production have silently diverged, and any CI test of the seeder passes while proving nothing about production. Filed as its own issue — and it's the prerequisite that would make the rename cheap later.

A decision reversed

The draft said the tour-tail template path should "import into the empty Cabinet in place". That would let a failed download delete the user's Cabinet. targetPath is a parent path that 409s on an existing dir, and downloadRegistryTemplate rolls back with fs.rm(targetDir, { recursive: true, force: true }) — safe only because that path is always newly created. The spec now requires a distinct intoPath, server-side emptiness checks, temp-dir staging with merge-on-success, and a rollback that can only touch the temp dir.

Note

Depends on CONTEXT.md, which lands via #256 (the onboarding spec).

🤖 Generated with Claude Code