busa-cli 0.18.0 → 0.19.0

package/dist/{run-DD52HeGA.js → run-FjzYcGKi.js}

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join } from "node:path";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
 import { z } from "zod";
 import { DEFAULT_BASE_URL, cloudContract, createBusabaseClient, getRecordByField, grepAssets, normalizeBaseUrl } from "busabase-sdk";
 import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
@@ -12,9 +12,9 @@ import { ZstdCompress, ZstdDecompress } from "node:zlib";
 import * as tar from "tar-stream";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { parse, stringify } from "yaml";
+import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
 //#region ../../packages/busabase-contract/src/tasks/base-field.ts
 /**
 * Changing a Base's schema, as one task with an `operation` instead of six
@@ -3958,6 +3958,210 @@ async function runLogout(options) {
 		config: activeCredentialPath()
 	};
 }
+//#endregion
+//#region ../../packages/busabase-contract/src/domains/package/template.ts
+/**
+* Template extension of the `busabase-package@1` format (pure zod, client-safe).
+*
+* A **template** is a package that is ALSO an Agent Skill: the same directory
+* carries a root `SKILL.md` (what an agent reads) next to `busabase.json` +
+* `content/` (what installs into a space). Nothing under `content/` changes —
+* the whole increment lives OUTSIDE it:
+*
+*   my-app/
+*   ├── SKILL.md          ← root skill entry (+ references/ agents/ scripts/)
+*   ├── busabase.json     ← manifest, now with an optional `template` object
+*   └── content/          ← byte-identical to a plain busabase-package@1 tree
+*
+* Consequences worth stating once, because they are what make the format
+* "multiplexed" rather than a second format:
+*   - A template directory is already a VALID package. Today's `install` can
+*     install it (it just won't land the Skill node, stamp ownership, or merge
+*     the sample records).
+*   - Any package becomes a template by adding a root `SKILL.md` plus the
+*     `template` object — no migration, no v2.
+*   - `export --template` emits a `content/` byte-identical to plain `export`.
+*
+* See `apps/busabase/content/spec/template-center.md` (§5, §6.2a, §13).
+*/
+/**
+* The root skill entry file. Deliberately the same name a `skill` NODE uses as
+* its entry file, because it becomes exactly that on install: the reader lifts
+* it (plus the sidecar dirs below) into a `skill` node inside the target
+* folder, so the manual travels with the resources instead of staying on the
+* publisher's disk.
+*/
+const PACKAGE_SKILL_ENTRY = "SKILL.md";
+/**
+* Directories carried into the Skill node alongside `SKILL.md`.
+*
+* `scripts/` is included on purpose even though Busabase never executes it: the
+* Skill node is a file tree, a shell agent that pulls the skill back out gets a
+* working copy, and dropping the scripts would make the round-trip lossy. The
+* safety property comes from *nothing in Busabase running them*, not from
+* refusing to store them.
+*/
+const PACKAGE_SKILL_SIDECAR_DIRS = [
+	"references",
+	"agents",
+	"scripts"
+];
+/**
+* Per-AirApp ignore file (gitignore syntax), read at
+* `content/<airapp>/.busabaseignore`.
+*
+* An AirApp node IS the project — nodepod runs `npm run dev` against it — so the
+* package cannot simply carry "the deployable subset" as a separate copy without
+* reintroducing the two-sources-of-truth problem the template format exists to
+* remove. The ignore file lets one directory be both: the repo keeps `test/`,
+* lockfiles and coverage; the node receives only what has to run.
+*
+* `package.json` and the entry it declares can never be ignored — a validator
+* error rather than a warning, because the resulting AirApp would install fine
+* and then fail to boot, which is the failure mode hardest to attribute.
+*/
+const PACKAGE_AIRAPP_IGNORE = ".busabaseignore";
+const TemplateAirAppRefSchema = z.object({
+	/** Slug of the `content/<dir>` holding the AirApp. */
+	slug: z.string().min(1),
+	role: z.enum([
+		"primary",
+		"admin",
+		"public",
+		"tool"
+	]),
+	label: z.string().optional()
+});
+/**
+* Secrets the app expects to find in the Vault.
+*
+* DECLARED, never created: the package format has no slot for secret values and
+* must not grow one (the same "you cannot leak what the format cannot express"
+* rule the whole format is built on). Install surfaces these as a post-install
+* prompt; the user fills them in the Vault themselves.
+*/
+const TemplateSecretSchema = z.object({
+	key: z.string().min(1),
+	description: z.string().default(""),
+	required: z.boolean().default(true)
+});
+const TemplateManifestSchema = z.object({
+	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
+	category: z.string().min(1),
+	tags: z.array(z.string()).default([]),
+	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
+	screenshots: z.array(z.string()).default([]),
+	/**
+	* Ready-made prompts shown after install ("Ask agent" prefills the first).
+	*
+	* They are the difference between a folder of tables and something a user can
+	* *use*: the point of a template is that the agent already knows the job, and
+	* these are how that is made visible rather than left for the user to guess.
+	*/
+	agentPrompts: z.array(z.string()).default([]),
+	/** Single-AirApp shorthand. Mutually exclusive with `airapps`. */
+	airapp: z.string().optional(),
+	/** Multi-AirApp form. Exactly one entry must have `role: "primary"`. */
+	airapps: z.array(TemplateAirAppRefSchema).optional(),
+	/**
+	* Bumped by the author when the declared resource shape changes.
+	*
+	* Part of the ownership stamp, so BOTH doors must agree on it: the installer
+	* writes it, and a skill's own `setup.mjs` compares against it to decide
+	* whether a node it finds is its own current shape or an older one to repair.
+	* Defaulted rather than required so an author who never versions their app
+	* still gets a stamp both sides recognise.
+	*/
+	schemaVersion: z.number().int().nonnegative().default(1),
+	vaultNamespace: z.string().optional(),
+	secrets: z.array(TemplateSecretSchema).default([]),
+	requires: z.object({ airapp: z.boolean().optional() }).default({})
+});
+/**
+* `metadata.busabase` inside the root `SKILL.md`'s YAML frontmatter.
+*
+* `template: true` is an EXPLICIT opt-in, not an inference from "this skill
+* happens to contain a package". Publishing a template means accepting that
+* installers will run its AirApp code and feed its SKILL.md to their agent; that
+* deserves a deliberate flag rather than a side effect of directory shape.
+*/
+const SkillBusabaseMetadataSchema = z.object({
+	template: z.boolean().default(false),
+	folderSlug: z.string().optional(),
+	/** Resource keys the manual talks about; each must exist under `content/`. */
+	resources: z.array(z.string()).default([]),
+	risk: z.string().optional()
+});
+/** Root `SKILL.md` frontmatter, as far as the template format cares about it. */
+const SkillFrontmatterSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().default(""),
+	metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional()
+});
+/**
+* Resolve which AirApp is the app, or explain why it cannot be resolved.
+*
+* Order matters and mirrors §5.4: an explicit declaration always wins, a single
+* candidate is unambiguous enough to accept, and anything else is an error the
+* publisher must resolve. Ambiguity is never resolved by picking the first
+* alphabetically — a template that silently opens the wrong app is worse than
+* one that refuses to publish.
+*/
+const resolvePrimaryAirApp = (template, airAppSlugsInContent) => {
+	if (template?.airapp && template.airapps?.length) return { error: "`template.airapp` and `template.airapps` are mutually exclusive." };
+	if (template?.airapp) return airAppSlugsInContent.includes(template.airapp) ? { slug: template.airapp } : { error: `template.airapp "${template.airapp}" has no matching AirApp under content/.` };
+	if (template?.airapps?.length) {
+		const primaries = template.airapps.filter((entry) => entry.role === "primary");
+		if (primaries.length !== 1) return { error: `template.airapps must declare exactly one entry with role "primary" (found ${primaries.length}).` };
+		const [primary] = primaries;
+		const unknown = template.airapps.filter((entry) => !airAppSlugsInContent.includes(entry.slug));
+		if (unknown.length) return { error: `template.airapps references AirApps missing from content/: ${unknown.map((entry) => entry.slug).join(", ")}.` };
+		return { slug: primary.slug };
+	}
+	if (airAppSlugsInContent.length === 1) return { slug: airAppSlugsInContent[0] };
+	if (airAppSlugsInContent.length === 0) return { error: "This package contains no AirApp." };
+	return { error: `content/ has ${airAppSlugsInContent.length} AirApps; declare which one is primary via template.airapp or template.airapps.` };
+};
+/** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
+const AppResourceOwnershipSchema = z.object({
+	appId: z.string().min(1),
+	/** Stable internal handle (`"contacts"`), NOT the installed slug. */
+	resourceKey: z.string().min(1),
+	schemaVersion: z.number().int().nonnegative()
+});
+/**
+* The `resourceKey` reserved for an app's root Folder.
+*
+* `busabase-sdk` recognises an app's own Folder by looking for exactly this
+* value (`ownsAppRoot`), so the installer must write it too — a Folder stamped
+* with anything else reads as a stranger's, and the skill's own `setup.mjs`
+* then refuses to touch its own workspace with `SETUP_CONFLICT`. Exported so
+* neither side carries the string literal privately.
+*/
+const APP_ROOT_RESOURCE_KEY = "app-root";
+AppResourceOwnershipSchema.extend({
+	resourceKey: z.literal(APP_ROOT_RESOURCE_KEY),
+	version: z.string().optional(),
+	source: z.object({
+		repo: z.string().optional(),
+		ref: z.string().optional(),
+		subdir: z.string().optional()
+	}).optional(),
+	installedAt: z.string().optional()
+});
+/**
+* Marks the Skill node lifted from the package root.
+*
+* Needed in both directions: export lifts exactly this node back out to the
+* package root instead of writing it under `content/` (which would create the
+* duplicate the format exists to avoid), and the agent wiring lists exactly
+* these nodes as "app manuals available in this space".
+*/
+const TEMPLATE_SKILL_METADATA_KEY = "isTemplateSkill";
+z.object({
+	appId: z.string().min(1),
+	[TEMPLATE_SKILL_METADATA_KEY]: z.literal(true)
+});
 const LocaleSchema = z.enum({
 	defaultLocale: "en",
 	locales: [
@@ -5080,7 +5284,15 @@ const PackageManifestSchema = z.object({
 	author: z.string().optional(),
 	license: z.string().optional(),
 	homepage: z.string().url().optional(),
-	tags: z.array(z.string()).default([])
+	tags: z.array(z.string()).default([]),
+	/**
+	* Present ⇢ this package is also an Agent Skill (a "template"): see
+	* `./template.ts`. Optional and additive — a package without it behaves
+	* exactly as before, and a reader that ignores it still installs correctly.
+	* The flag alone is not enough to be treated as a template; the root
+	* `SKILL.md` must opt in too (`validateTemplate`).
+	*/
+	template: TemplateManifestSchema.optional()
 });
 /** `_node.json` — marks a directory as a verbatim-content file-tree node. */
 const PackageFileTreeNodeMetaSchema = z.object({
@@ -5327,6 +5539,18 @@ const compareNodes = (a, b) => {
 const sortNodes = (nodes) => [...nodes].sort(compareNodes);
 /** `getting-started` → `Getting Started`; the default name for a folder with no `_folder.json`. */
 const humanizeSlug = (slug) => slug.split("-").filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+/**
+* Extension → mime type, which decides one thing that matters: a text file goes
+* INLINE into a file-tree create, and anything else has to be uploaded as an
+* asset first (see `isTextMimeType`). Getting it wrong on a source file means
+* the app's own code takes the binary path — it needs an upload endpoint to
+* install at all, and it lands as an opaque blob rather than something a
+* reviewer or an agent can read.
+*
+* The module-flavoured JavaScript and TypeScript extensions are here because
+* real projects use them: `scripts/setup.mjs` is the ordinary name for a Node
+* script, and installing kelly-email surfaced exactly that gap.
+*/
 const MIME_BY_EXT$1 = {
 	".css": "text/css",
 	".csv": "text/csv",
@@ -5335,7 +5559,12 @@ const MIME_BY_EXT$1 = {
 	".html": "text/html",
 	".jpeg": "image/jpeg",
 	".jpg": "image/jpeg",
+	".cjs": "text/javascript",
+	".cts": "text/typescript",
 	".js": "text/javascript",
+	".jsx": "text/javascript",
+	".mjs": "text/javascript",
+	".mts": "text/typescript",
 	".json": "application/json",
 	".md": "text/markdown",
 	".pdf": "application/pdf",
@@ -5343,6 +5572,7 @@ const MIME_BY_EXT$1 = {
 	".py": "text/x-python",
 	".svg": "image/svg+xml",
 	".ts": "text/typescript",
+	".tsx": "text/typescript",
 	".txt": "text/plain",
 	".webp": "image/webp",
 	".yaml": "text/yaml",
@@ -5470,6 +5700,7 @@ const applyInstall = async (client, plan, options) => {
 	const fieldIds = /* @__PURE__ */ new Map();
 	const bases = [];
 	const progress = options.onProgress ?? (() => {});
+	const app = resolveAppContext(plan, options);
 	const docAssetIds = await uploadDocAssets(client, plan.tree.assets ?? [], state, progress, options.serverUrl);
 	progress("Pass 1/5: creating the node tree…");
 	if (plan.existingTargetFolderNodeId) state.targetFolderNodeId = plan.existingTargetFolderNodeId;
@@ -5479,11 +5710,23 @@ const applyInstall = async (client, plan, options) => {
 			slug: plan.targetFolderSlug,
 			name: plan.tree.manifest.name,
 			description: plan.tree.manifest.description,
-			submittedBy: options.submittedBy
+			submittedBy: options.submittedBy,
+			metadata: app?.rootMetadata
 		});
 		state.created.folders++;
 	}
-	await createStructure(client, plan.tree.nodes, state.targetFolderNodeId, options, state, bases, fieldIds, docAssetIds);
+	await createStructure(client, plan.tree.nodes, state.targetFolderNodeId, options, state, bases, fieldIds, docAssetIds, app);
+	if (app?.rootSkill) {
+		progress("Pass 1/5: installing the app skill…");
+		await createFileTreeNode(client, {
+			type: "skill",
+			slug: app.rootSkill.slug,
+			name: app.rootSkill.name,
+			description: app.rootSkill.description,
+			position: void 0,
+			files: app.rootSkill.files
+		}, state.targetFolderNodeId, options, state, app, { [TEMPLATE_SKILL_METADATA_KEY]: true });
+	}
 	const deferred = bases.filter((base) => base.node.base.fields.some(isDeferredField));
 	if (deferred.length > 0) {
 		progress("Pass 2/5: adding relation and AI fields…");
@@ -5526,7 +5769,7 @@ const applyInstall = async (client, plan, options) => {
 	const withRecords = bases.filter((base) => base.node.records.length > 0);
 	if (withRecords.length > 0) {
 		progress("Pass 4/5: creating records…");
-		for (const base of withRecords) await createRecords(client, base, plan, options, state, recordIdsByKey);
+		for (const base of withRecords) await createRecords(client, base, plan, options, state, recordIdsByKey, app);
 	}
 	const relationFieldSlugs = /* @__PURE__ */ new Map();
 	for (const base of bases) {
@@ -5543,6 +5786,58 @@ const applyInstall = async (client, plan, options) => {
 	}
 	return state;
 };
+const resolveAppContext = (plan, options) => {
+	if (!plan.isTemplate) return void 0;
+	const manifest = plan.tree.manifest;
+	const schemaVersion = manifest.template?.schemaVersion ?? 1;
+	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const rootStamp = {
+		appId: manifest.name,
+		resourceKey: APP_ROOT_RESOURCE_KEY,
+		schemaVersion,
+		...manifest.version ? { version: manifest.version } : {},
+		...options.source ? { source: options.source } : {},
+		installedAt: now()
+	};
+	return {
+		appId: manifest.name,
+		schemaVersion,
+		rootMetadata: rootStamp,
+		rootSkill: plan.tree.rootSkill,
+		resourceKeysBySlug: plan.resourceKeysBySlug,
+		mergeSampleRecords: options.installSampleRecords ?? true
+	};
+};
+/**
+* Stamp a node the installer just created.
+*
+* Separate from creation because `bases.create` and `fileTrees.create` take no
+* metadata — only `nodes.createChangeRequest` does, which is why the Folder can
+* be stamped inline and these cannot. A stamp that fails is a warning, never a
+* failed install: the resources are already there and useful, and the only loss
+* is that the skill's own `setup.mjs` will later offer to re-claim them, which
+* it is built to do (that is its "repair" path).
+*/
+const resourceStamp = (app, installedSlug, extra = {}) => {
+	return {
+		appId: app.appId,
+		resourceKey: app.resourceKeysBySlug[installedSlug] ?? installedSlug,
+		schemaVersion: app.schemaVersion,
+		...extra
+	};
+};
+const stampResource = async (client, app, nodeId, installedSlug, state, extra = {}) => {
+	if (!app) return;
+	const stamp = resourceStamp(app, installedSlug, extra);
+	try {
+		await client.nodes.updateMetadata({
+			nodeId,
+			metadata: stamp
+		});
+	} catch (error) {
+		state.warnings.push(`Could not record app ownership on "${installedSlug}": ${error.message}. The node installed fine; running the app's own setup will claim it.`);
+	}
+};
 /**
 * Re-create the package's carried Doc images on THIS host and return the
 * old id → new id map the Doc bodies are rewritten through.
@@ -5566,7 +5861,7 @@ const uploadDocAssets = async (client, assets, state, progress, serverUrl) => {
 	}
 	return idMap;
 };
-const createStructure = async (client, nodes, parentNodeId, options, state, bases, fieldIds, docAssetIds) => {
+const createStructure = async (client, nodes, parentNodeId, options, state, bases, fieldIds, docAssetIds, app) => {
 	for (const node of nodes) switch (node.type) {
 		case "folder": {
 			const nodeId = await createFolderNode(client, {
@@ -5577,7 +5872,7 @@ const createStructure = async (client, nodes, parentNodeId, options, state, base
 				submittedBy: options.submittedBy
 			});
 			state.created.folders++;
-			await createStructure(client, node.children, nodeId, options, state, bases, fieldIds, docAssetIds);
+			await createStructure(client, node.children, nodeId, options, state, bases, fieldIds, docAssetIds, app);
 			break;
 		}
 		case "doc": {
@@ -5595,12 +5890,12 @@ const createStructure = async (client, nodes, parentNodeId, options, state, base
 			break;
 		}
 		case "base":
-			await createBase(client, node, parentNodeId, options, state, bases, fieldIds);
+			await createBase(client, node, parentNodeId, options, state, bases, fieldIds, app);
 			break;
 		case "skill":
 		case "airapp":
 		case "drive":
-			await createFileTreeNode(client, node, parentNodeId, options, state);
+			await createFileTreeNode(client, node, parentNodeId, options, state, app);
 			break;
 		case "file": {
 			let asset;
@@ -5639,13 +5934,14 @@ const createFolderNode = async (client, input) => {
 			slug: input.slug,
 			name: input.name,
 			description: input.description,
-			parentNodeId: input.parentNodeId
+			parentNodeId: input.parentNodeId,
+			...input.metadata ? { metadata: input.metadata } : {}
 		}]
 	})).operations[0]?.nodeId;
 	if (!nodeId) throw new Error(`Folder "${input.slug}" was created but the server returned no node id, so nothing could be installed inside it.`);
 	return nodeId;
 };
-const createBase = async (client, node, parentNodeId, options, state, bases, fieldIds) => {
+const createBase = async (client, node, parentNodeId, options, state, bases, fieldIds, app) => {
 	const immediateFields = node.base.fields.filter((field) => !isDeferredField(field)).map((field) => ({
 		slug: field.slug,
 		name: field.name,
@@ -5668,6 +5964,7 @@ const createBase = async (client, node, parentNodeId, options, state, bases, fie
 		baseId: result.id
 	});
 	indexFields(fieldIds, node.slug, result.fields);
+	await stampResource(client, app, result.nodeId, node.slug, state);
 	for (const view of node.base.views) {
 		if (!(await client.views.changeRequest({
 			operation: "create",
@@ -5682,7 +5979,7 @@ const createBase = async (client, node, parentNodeId, options, state, bases, fie
 		state.created.views++;
 	}
 };
-const createFileTreeNode = async (client, node, parentNodeId, options, state) => {
+const createFileTreeNode = async (client, node, parentNodeId, options, state, app, extraMetadata = {}) => {
 	const files = (await Promise.all(node.files.map(async (entry) => {
 		const mimeType = guessMimeType$1(entry.path);
 		if (isTextMimeType(mimeType)) return {
@@ -5709,6 +6006,7 @@ const createFileTreeNode = async (client, node, parentNodeId, options, state) =>
 		name: node.name,
 		description: node.description,
 		files,
+		...app ? { metadata: resourceStamp(app, node.slug, extraMetadata) } : {},
 		mergeMode: "replace",
 		autoMerge: options.autoMerge
 	})).materialized) {
@@ -5856,7 +6154,8 @@ const toCreatableFields = (node, fields) => {
 	}
 	return result;
 };
-const createRecords = async (client, base, plan, options, state, recordIdsByKey) => {
+const createRecords = async (client, base, plan, options, state, recordIdsByKey, app) => {
+	const mergeRecords = options.autoMerge || (app?.mergeSampleRecords ?? false);
 	const records = [...base.node.records].sort((a, b) => a.key.localeCompare(b.key, "en"));
 	for (let offset = 0; offset < records.length; offset += 200) {
 		const batch = records.slice(offset, offset + 200);
@@ -5866,9 +6165,9 @@ const createRecords = async (client, base, plan, options, state, recordIdsByKey)
 			message: `Install ${batch.length} record(s) into ${base.node.slug}`,
 			submittedBy: options.submittedBy,
 			idempotencyKey: batchIdempotencyKey(plan.tree.manifest.name, batch[0].key),
-			autoMerge: options.autoMerge
+			autoMerge: mergeRecords
 		});
-		if (!options.autoMerge) {
+		if (!mergeRecords) {
 			state.pendingChangeRequests++;
 			continue;
 		}
@@ -5970,19 +6269,115 @@ const findSourceNode = (nodes, slugOrId) => {
 };
 const collectPackageTree = async (client, root, options) => {
 	const children = root.children ?? [];
-	const nodes = await collectNodes(client, children, options);
+	const { skillSource, rest } = partitionTemplateSkill(children);
+	const nodes = await collectNodes(client, rest, options);
 	const tree = {
 		manifest: {
 			...options.manifest,
 			format: PACKAGE_FORMAT
 		},
-		nodes,
+		nodes: restorePackageSlugs(nodes, children),
+		...skillSource ? { rootSkill: await collectRootSkill(client, skillSource, options) } : {},
 		assets: await collectDocAssets(client, nodes, options)
 	};
 	assertSelfContained(tree, options);
 	return tree;
 };
 /**
+* Undo the slugs INSTALL chose, restoring the ones the package declared.
+*
+* Install prefixes a template's Base slugs with the target folder (`contacts` →
+* `kelly-crm-contacts`) and records the original as the node's `resourceKey`.
+* Exporting the installed slug would make the package say something its author
+* never wrote — and re-installing it would prefix the prefix, or collide
+* outright. Reading the stamp back makes export→install→export a fixed point,
+* which is the property that lets a user install a template, adjust it, and
+* publish the result without the names drifting a little further each time.
+*
+* The root folder's own stamp is skipped: its `resourceKey` is the reserved
+* `app-root` marker, not a slug anything should be named after.
+*/
+const restorePackageSlugs = (nodes, sources) => {
+	const renames = /* @__PURE__ */ new Map();
+	const index = (list) => {
+		for (const source of list) {
+			const key = source.metadata?.resourceKey;
+			if (typeof key === "string" && key !== "app-root" && key !== source.slug && NODE_SLUG_PATTERN.test(key)) renames.set(source.slug, key);
+			if (source.children) index(source.children);
+		}
+	};
+	index(sources);
+	if (renames.size === 0) return [...nodes];
+	const rewriteField = (field) => {
+		const target = field.options.targetBaseSlug;
+		if (!target) return field;
+		const renamed = renames.get(target);
+		return renamed ? {
+			...field,
+			options: {
+				...field.options,
+				targetBaseSlug: renamed
+			}
+		} : field;
+	};
+	const rewrite = (node) => {
+		const slug = renames.get(node.slug) ?? node.slug;
+		if (node.type === "folder") return {
+			...node,
+			slug,
+			children: node.children.map(rewrite)
+		};
+		if (node.type === "base") return {
+			...node,
+			slug,
+			base: {
+				...node.base,
+				fields: node.base.fields.map(rewriteField)
+			}
+		};
+		return {
+			...node,
+			slug
+		};
+	};
+	return nodes.map(rewrite);
+};
+/**
+* Separate the app's manual from its resources.
+*
+* The Skill node stamped `isTemplateSkill` is the one an install lifted out of a
+* package root, so export has to put it back there rather than under `content/`.
+* Writing it as a normal node would make every export→install cycle add another
+* copy of the manual beside the previous one.
+*
+* Only the FIRST such node is lifted: two of them in one folder is a state no
+* install can produce, and silently merging them would be a guess. The extra one
+* is exported as an ordinary Skill node, which is visible and fixable, rather
+* than dropped.
+*/
+const partitionTemplateSkill = (children) => {
+	const index = children.findIndex((node) => node.type === "skill" && node.metadata?.["isTemplateSkill"] === true);
+	if (index === -1) return { rest: [...children] };
+	return {
+		skillSource: children[index],
+		rest: children.filter((_, position) => position !== index)
+	};
+};
+const collectRootSkill = async (client, source, options) => {
+	const node = await collectFileTree(client, source, "skill", {
+		slug: source.slug,
+		name: source.name,
+		description: source.description ?? "",
+		position: source.position
+	}, options);
+	return {
+		slug: source.slug,
+		name: source.name,
+		description: source.description ?? "",
+		files: node.files
+	};
+};
+/**
 * The bytes behind every `![](/api/assets/{id}/raw)` in every exported Doc.
 *
 * A Doc's images are the one part of a Doc that is not in its markdown, and
@@ -6303,224 +6698,131 @@ const assertSelfContained = (tree, options) => {
 	}
 };
 //#endregion
-//#region ../../packages/busabase-package/src/github.ts
+//#region ../../packages/busabase-package/src/frontmatter.ts
 /**
-* GitHub source for `busabase-cli install`: parse a repo URL, fetch the ref's
-* zipball, and extract it into memory.
-*
-* Ported from Buda's GitHub skill importer (Buda stays as-is; a shared package
-* is warranted only once the Phase-2 server consumer actually exists). Three
-* deliberate divergences from that original:
+* YAML frontmatter for doc nodes (§6.3): `name`, `description?`, `position?` above
+* the markdown body.
 *
-* 1. **Host is parsed, not pattern-matched.** buda's regex matches `github.com/…`
-*    anywhere in the string, so `https://evil.example/github.com/o/r` passes. This
-*    parses with `URL` and checks `hostname` against an allowlist.
-* 2. **Any git ref, not just branches.** buda fetches `/archive/refs/heads/<b>.zip`,
-*    which resolves branches only — tags (the package format's version scheme)
-*    would 404. This uses codeload's `/zip/<ref>`, which takes a branch, tag, or SHA.
-* 3. **Extraction is to memory with the caps applied first**, so an oversized or
-*    zip-bomb archive never reaches the disk.
+* Writing is deterministic (§6.6): a fixed key order and LF endings, so re-exporting
+* an unchanged doc is byte-identical.
 */
-/** Hosts the installer may ever connect to. Also the Phase-2 server guard's allowlist. */
-const GITHUB_ALLOWED_HOSTS = [
-	"github.com",
-	"api.github.com",
-	"codeload.github.com"
-];
-/** Hosts accepted in a user-supplied install URL (the web UI form of a repo). */
-const GITHUB_URL_HOSTS = ["github.com", "www.github.com"];
-const isAllowedGithubHost = (hostname) => GITHUB_ALLOWED_HOSTS.includes(hostname.toLowerCase());
+const DELIMITER = "---";
 /**
-* Parse a GitHub repo URL.
-*
-* Supported forms:
-*   https://github.com/owner/repo
-*   https://github.com/owner/repo.git
-*   https://github.com/owner/repo/tree/<ref>
-*   https://github.com/owner/repo/tree/<ref>/<subdir…>
+* The canonical on-disk body: LF endings, no leading or trailing blank lines. Applied
+* on both read and write so the round trip is a fixed point — without it, the blank
+* line the writer puts after the closing `---` and the file's trailing newline would
+* accumulate into the body on every export→install→export cycle.
 *
-* A ref containing `/` (e.g. `feature/x`) is indistinguishable from `<ref>/<subdir>`
-* in a `/tree/` URL — GitHub's own web URLs have the same ambiguity — so the first
-* segment after `/tree/` is taken as the ref and the rest as the subdir.
+* Leading/trailing blank lines around a doc body are therefore normalized away on the
+* first export; internal blank lines are untouched.
 */
-const parseGithubUrl = (rawUrl) => {
-	let url;
+const normalizeDocBody = (body) => body.replaceAll("\r\n", "\n").replace(/^\n+/, "").replace(/\n+$/, "");
+/** Split `---\n<yaml>\n---\n<body>`. A doc with no frontmatter is all body. */
+const parseFrontmatter = (text, filePath) => {
+	const normalized = text.replaceAll("\r\n", "\n");
+	if (!normalized.startsWith(`${DELIMITER}\n`)) return {
+		data: {},
+		body: normalizeDocBody(normalized)
+	};
+	const end = normalized.indexOf(`\n${DELIMITER}`, 3);
+	if (end === -1) throw new Error(`${filePath} opens YAML frontmatter with "---" but never closes it. Add a closing "---" line.`);
+	const rawYaml = normalized.slice(4, end);
+	const body = normalizeDocBody(normalized.slice(end + 1 + 3));
+	let data;
 	try {
-		url = new URL(rawUrl.trim());
-	} catch {
-		throw new Error(`Not a valid URL: "${rawUrl}". Expected a GitHub repo URL, e.g. https://github.com/acme/support-kb-template`);
+		data = parse(rawYaml);
+	} catch (error) {
+		throw new Error(`${filePath} has invalid YAML frontmatter: ${error.message}`);
 	}
-	if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`Unsupported URL scheme "${url.protocol}" — expected an https:// GitHub URL.`);
-	if (!GITHUB_URL_HOSTS.includes(url.hostname.toLowerCase())) throw new Error(`Not a GitHub URL: host "${url.hostname}" is not github.com. Only GitHub packages can be installed.`);
-	const [owner, rawRepo, marker, ref, ...rest] = url.pathname.split("/").filter(Boolean);
-	if (!owner || !rawRepo) throw new Error(`GitHub URL is missing owner/repo: "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`);
-	const repo = rawRepo.replace(/\.git$/, "");
-	if (!marker) return {
-		owner,
-		repo,
-		ref: void 0,
-		subdir: void 0
+	if (data === null || data === void 0) return {
+		data: {},
+		body
 	};
-	if (marker !== "tree") throw new Error(`Unsupported GitHub URL form "/${marker}/" in "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`);
-	if (!ref) throw new Error(`GitHub URL has "/tree/" but no ref: "${rawUrl}".`);
+	if (typeof data !== "object" || Array.isArray(data)) throw new Error(`${filePath} frontmatter must be a YAML mapping (key: value pairs).`);
 	return {
-		owner,
-		repo,
-		ref: decodeURIComponent(ref),
-		subdir: rest.length > 0 ? rest.map((segment) => decodeURIComponent(segment)).join("/") : void 0
+		data,
+		body
 	};
 };
-/** Encode a ref for a URL path while keeping its `/` separators (e.g. `feature/x`). */
-const encodeRefPath = (ref) => ref.split("/").map(encodeURIComponent).join("/");
+/** Serialize a doc to `---\n<frontmatter>\n---\n<body>` with a trailing newline. */
+const serializeDoc = (fields, body) => {
+	const data = { name: fields.name };
+	if (fields.description) data.description = fields.description;
+	if (fields.position !== void 0) data.position = fields.position;
+	const yaml = stringify(data, { lineWidth: 0 }).replace(/\n$/, "");
+	return `${DELIMITER}\n${yaml}\n${DELIMITER}\n\n${normalizeDocBody(body)}\n`;
+};
+//#endregion
+//#region ../../packages/busabase-package/src/ignore.ts
+const escapeLiteral = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
 /**
-* Download the zipball for `owner/repo` at `ref` (default branch when `ref` is
-* undefined). Tries the public codeload host first, then the authenticated API when
-* a token is available — so a private repo works iff `GITHUB_TOKEN` is set.
+* Translate one gitignore-ish pattern into a regex over a POSIX relative path.
+*
+* The three globs are handled in one pass so that `**` is recognised before the
+* `*` it starts with — splitting on `*` first would turn `**` into two
+* segment-local wildcards and quietly stop matching across directories.
 */
-const downloadGithubZip = async (source, options = {}) => {
-	const fetcher = options.fetcher ?? fetch;
-	const { owner, repo, ref } = source;
-	const slug = `${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
-	const label = `${owner}/${repo}${ref ? `@${ref}` : ""}`;
-	const publicUrl = `https://codeload.github.com/${slug}/zip/${ref ? encodeRefPath(ref) : "HEAD"}`;
-	assertAllowedUrl(publicUrl);
-	const publicResponse = await fetcher(publicUrl);
-	if (publicResponse.ok) return Buffer.from(await publicResponse.arrayBuffer());
-	if (!options.githubToken) throw new Error(publicResponse.status === 404 ? `GitHub repo or ref not found: ${label} (HTTP 404).\n  • Check the URL, and that the branch/tag exists.\n  • Private repo? Set GITHUB_TOKEN=<a token with repo read access> and re-run.` : `Failed to download ${label} from GitHub (HTTP ${publicResponse.status} ${publicResponse.statusText}).`);
-	const apiUrl = `https://api.github.com/repos/${slug}/zipball${ref ? `/${encodeRefPath(ref)}` : ""}`;
-	assertAllowedUrl(apiUrl);
-	const authedResponse = await fetcher(apiUrl, { headers: {
-		Accept: "application/vnd.github+json",
-		Authorization: `Bearer ${options.githubToken}`,
-		"X-GitHub-Api-Version": "2022-11-28"
-	} });
-	if (authedResponse.ok) return Buffer.from(await authedResponse.arrayBuffer());
-	if (authedResponse.status === 401 || authedResponse.status === 403) throw new Error(`GitHub rejected GITHUB_TOKEN for ${label} (HTTP ${authedResponse.status}). The token is invalid, expired, or lacks read access to this repo.`);
-	throw new Error(`GitHub repo or ref not found: ${label} (HTTP ${authedResponse.status}), even with GITHUB_TOKEN. Check the owner, repo, and ref.`);
-};
-/** SSRF guard: refuse anything off the GitHub allowlist before a connection is made. */
-const assertAllowedUrl = (rawUrl) => {
-	const url = new URL(rawUrl);
-	if (url.protocol !== "https:" || !isAllowedGithubHost(url.hostname)) throw new Error(`Refusing to fetch ${rawUrl} — only https on ${GITHUB_ALLOWED_HOSTS.join(", ")} is allowed.`);
-};
-/**
-* Zip-slip guard. Normalizes an archive entry path to a repo-relative path and
-* rejects anything that could escape the extraction root: `..`/`.` segments,
-* and Windows drive prefixes. A leading `/` is stripped rather than rejected —
-* that makes the path relative, which is already safe.
-*/
-const normalizeArchivePath = (value) => {
-	const normalized = value.replaceAll("\\", "/").replace(/^\/+|\/+$/g, "");
-	const segments = normalized.split("/");
-	if (!normalized || segments.some((segment) => segment === "." || segment === ".." || /^[a-zA-Z]:$/.test(segment))) throw new Error(`Unsafe archive path rejected: ${value}`);
-	return normalized;
-};
-/**
-* Extract a GitHub zipball into memory, keyed by repo-relative path (the archive's
-* single generated root directory — `owner-repo-<sha>/` — is stripped).
-*
-* Caps are enforced against the archive's declared entry sizes BEFORE any bytes are
-* read, so an oversized archive or zip bomb is refused up front and nothing is ever
-* written to disk.
-*/
-const extractZip = async (zipBuffer, options = {}) => {
-	const maxFiles = options.maxFiles ?? 5e3;
-	const maxTotalBytes = options.maxTotalBytes ?? 262144e3;
-	const maxFileBytes = options.maxFileBytes ?? 26214400;
-	const reader = new ZipReader(new Uint8ArrayReader(new Uint8Array(zipBuffer)));
-	try {
-		const files = (await reader.getEntries()).filter((entry) => !entry.directory);
-		const archiveRoot = files[0]?.filename.split("/")[0];
-		if (!archiveRoot) throw new Error("The downloaded repository archive is empty.");
-		const subdir = options.subdir ? normalizeArchivePath(options.subdir) : void 0;
-		const prefix = `${archiveRoot}/${subdir ? `${subdir}/` : ""}`;
-		for (const entry of files) normalizeArchivePath(entry.filename);
-		const selected = files.filter((entry) => entry.filename.startsWith(prefix));
-		if (selected.length > maxFiles) throw new Error(`Package has ${selected.length} files, above the ${maxFiles}-file limit. Nothing was installed.`);
-		let totalBytes = 0;
-		for (const entry of selected) {
-			const size = entry.uncompressedSize ?? 0;
-			const relativePath = entry.filename.slice(prefix.length);
-			if (size > maxFileBytes) throw new Error(`File "${relativePath}" is ${formatBytes(size)}, above the ${formatBytes(maxFileBytes)} per-file limit. Nothing was installed.`);
-			totalBytes += size;
-			if (totalBytes > maxTotalBytes) throw new Error(`Package unpacks to more than the ${formatBytes(maxTotalBytes)} total limit. Nothing was installed.`);
+const patternToRegex = (pattern, anchored) => {
+	let source = "";
+	for (let index = 0; index < pattern.length; index += 1) {
+		const char = pattern[index];
+		if (char === "*") {
+			if (pattern[index + 1] === "*") {
+				index += 1;
+				if (pattern[index + 1] === "/") {
+					index += 1;
+					source += "(?:.*/)?";
+				} else source += ".*";
+			} else source += "[^/]*";
+			continue;
 		}
-		const result = /* @__PURE__ */ new Map();
-		for (const entry of selected) {
-			const relativePath = normalizeArchivePath(entry.filename.slice(prefix.length));
-			if (!entry.getData) continue;
-			const data = await entry.arrayBuffer();
-			result.set(relativePath, Buffer.from(data));
+		if (char === "?") {
+			source += "[^/]";
+			continue;
 		}
-		return result;
-	} finally {
-		await reader.close();
-	}
-};
-const formatBytes = (bytes) => bytes >= 1048576 ? `${Math.round(bytes / 1048576)}MB` : `${Math.round(bytes / 1024)}KB`;
-/** Parse, fetch, and extract in one step — the `install` command's entry point. */
-const fetchGithubPackageFiles = async (repoUrl, options = {}) => {
-	const source = parseGithubUrl(repoUrl);
-	const zipBuffer = await downloadGithubZip(source, options);
+		if (char === "/") {
+			source += "/";
+			continue;
+		}
+		source += escapeLiteral(char);
+	}
+	return new RegExp(`${anchored ? "^" : "^(?:.*/)?"}${source}(?:/.*)?$`);
+};
+const parseRule = (line) => {
+	let pattern = line.trim();
+	if (!pattern || pattern.startsWith("#")) return void 0;
+	const negated = pattern.startsWith("!");
+	if (negated) pattern = pattern.slice(1);
+	const directoryOnly = pattern.endsWith("/");
+	if (directoryOnly) pattern = pattern.slice(0, -1);
+	const anchored = pattern.startsWith("/");
+	if (anchored) pattern = pattern.slice(1);
+	if (!pattern) return void 0;
 	return {
-		source,
-		files: await extractZip(zipBuffer, { subdir: source.subdir })
+		regex: patternToRegex(pattern, anchored),
+		negated,
+		directoryOnly
 	};
 };
-//#endregion
-//#region ../../packages/busabase-package/src/frontmatter.ts
-/**
-* YAML frontmatter for doc nodes (§6.3): `name`, `description?`, `position?` above
-* the markdown body.
-*
-* Writing is deterministic (§6.6): a fixed key order and LF endings, so re-exporting
-* an unchanged doc is byte-identical.
-*/
-const DELIMITER = "---";
-/**
-* The canonical on-disk body: LF endings, no leading or trailing blank lines. Applied
-* on both read and write so the round trip is a fixed point — without it, the blank
-* line the writer puts after the closing `---` and the file's trailing newline would
-* accumulate into the body on every export→install→export cycle.
-*
-* Leading/trailing blank lines around a doc body are therefore normalized away on the
-* first export; internal blank lines are untouched.
-*/
-const normalizeDocBody = (body) => body.replaceAll("\r\n", "\n").replace(/^\n+/, "").replace(/\n+$/, "");
-/** Split `---\n<yaml>\n---\n<body>`. A doc with no frontmatter is all body. */
-const parseFrontmatter = (text, filePath) => {
-	const normalized = text.replaceAll("\r\n", "\n");
-	if (!normalized.startsWith(`${DELIMITER}\n`)) return {
-		data: {},
-		body: normalizeDocBody(normalized)
-	};
-	const end = normalized.indexOf(`\n${DELIMITER}`, 3);
-	if (end === -1) throw new Error(`${filePath} opens YAML frontmatter with "---" but never closes it. Add a closing "---" line.`);
-	const rawYaml = normalized.slice(4, end);
-	const body = normalizeDocBody(normalized.slice(end + 1 + 3));
-	let data;
-	try {
-		data = parse(rawYaml);
-	} catch (error) {
-		throw new Error(`${filePath} has invalid YAML frontmatter: ${error.message}`);
-	}
-	if (data === null || data === void 0) return {
-		data: {},
-		body
-	};
-	if (typeof data !== "object" || Array.isArray(data)) throw new Error(`${filePath} frontmatter must be a YAML mapping (key: value pairs).`);
+const parseIgnoreFile = (contents) => {
+	const rules = contents.split(/\r?\n/).map(parseRule).filter((rule) => rule !== void 0);
 	return {
-		data,
-		body
+		isEmpty: rules.length === 0,
+		ignores: (relativePath) => {
+			let ignored = false;
+			for (const rule of rules) {
+				if (rule.directoryOnly && !rule.regex.test(`${relativePath}/`)) continue;
+				if (!rule.regex.test(relativePath)) continue;
+				ignored = !rule.negated;
+			}
+			return ignored;
+		}
 	};
 };
-/** Serialize a doc to `---\n<frontmatter>\n---\n<body>` with a trailing newline. */
-const serializeDoc = (fields, body) => {
-	const data = { name: fields.name };
-	if (fields.description) data.description = fields.description;
-	if (fields.position !== void 0) data.position = fields.position;
-	const yaml = stringify(data, { lineWidth: 0 }).replace(/\n$/, "");
-	return `${DELIMITER}\n${yaml}\n${DELIMITER}\n\n${normalizeDocBody(body)}\n`;
+/** A matcher that installs everything — used when no ignore file is present. */
+const IGNORE_NOTHING = {
+	ignores: () => false,
+	isEmpty: true
 };
 //#endregion
 //#region ../../packages/busabase-package/src/layout-read.ts
@@ -6537,6 +6839,12 @@ const serializeDoc = (fields, body) => {
 *
 * Outside `content/`, the optional `assets/` directory carries the bytes for the
 * images the Docs embed — see {@link readDocAssets}. Nothing in there is a node.
+*
+* Rule 0 sits ahead of all of them but reads a different place: a `SKILL.md` at
+* the package ROOT (beside the manifest, not under `content/`) makes this
+* package a *template*, and is lifted into `tree.rootSkill` — see
+* {@link readRootSkill}. `content/` itself is untouched by that rule, which is
+* what keeps a template byte-identical to a plain package below the root.
 */
 const decodeText = (bytes, filePath) => {
 	const text = bytes.toString("utf8");
@@ -6602,13 +6910,65 @@ const readPackageTree = (files, options = {}) => {
 	assertKnownFormat(rawManifest, manifestPath);
 	const manifest = zodParse(PackageManifestSchema, rawManifest, manifestPath);
 	const contentDir = `${root}${PACKAGE_CONTENT_DIRNAME}/`;
+	const nodes = readNodes(files, contentDir);
+	const rootSkill = readRootSkill(files, root, manifest.name, manifest.description);
 	return {
 		manifest,
-		nodes: readNodes(files, contentDir),
+		nodes,
+		...rootSkill ? { rootSkill } : {},
 		assets: readDocAssets(files, root)
 	};
 };
 /**
+* Rule 0 — the package root's `SKILL.md` plus its sidecar directories.
+*
+* Absent → a plain package, and every downstream consumer behaves exactly as it
+* did before. Present → the manual travels with the resources: the installer
+* turns this into a Skill node inside the target folder, which is what lets the
+* agent that a user talks to after installing actually know what the app is for.
+*
+* The node's slug comes from the MANIFEST name rather than the skill
+* frontmatter's, because the manifest name is already the default target folder
+* name and is validated as a slug elsewhere; the validator separately requires
+* the two names to agree, so this is not a silent tie-break.
+*/
+const readRootSkill = (files, root, manifestName, manifestDescription) => {
+	const entryPath = `${root}${PACKAGE_SKILL_ENTRY}`;
+	const entryBytes = files.get(entryPath);
+	if (!entryBytes) return void 0;
+	const entries = [{
+		path: PACKAGE_SKILL_ENTRY,
+		bytes: entryBytes
+	}];
+	for (const dirName of PACKAGE_SKILL_SIDECAR_DIRS) {
+		const dir = `${root}${dirName}/`;
+		for (const entry of collectSubtree(files, dir)) entries.push({
+			path: `${dirName}/${entry.path}`,
+			bytes: entry.bytes
+		});
+	}
+	assertNoReservedNames(entries.map((entry) => entry.path), `root skill "${manifestName}"`);
+	const parsed = parseSkillFrontmatterSafely(decodeText(entryBytes, entryPath), entryPath);
+	return {
+		slug: manifestName,
+		name: parsed?.name ?? manifestName,
+		description: parsed?.description ?? manifestDescription,
+		files: entries.sort((a, b) => a.path.localeCompare(b.path, "en"))
+	};
+};
+const parseSkillFrontmatterSafely = (text, filePath) => {
+	try {
+		const { data } = parseFrontmatter(text, filePath);
+		const record = data;
+		return {
+			name: typeof record.name === "string" ? record.name : void 0,
+			description: typeof record.description === "string" ? record.description : void 0
+		};
+	} catch {
+		return;
+	}
+};
+/**
 * `assets/` — the bytes for the images the Docs embed. Driven off the sidecars,
 * not off the byte files: the sidecar is what carries the source asset id, so a
 * stray file with no `.asset.json` beside it is simply not an asset this package
@@ -6667,8 +7027,10 @@ const readDirNode = (files, dir, slug) => {
 	if (files.has(`${dir}_node.json`)) {
 		const metaPath = `${dir}${PACKAGE_NODE_META_FILENAME}`;
 		const meta = zodParse(PackageFileTreeNodeMetaSchema, parseJsonFile(files, metaPath), metaPath);
-		const entries = collectSubtree(files, dir).filter((entry) => entry.path !== PACKAGE_NODE_META_FILENAME);
+		const ignore = readIgnoreFile(files, dir);
+		const entries = collectSubtree(files, dir).filter((entry) => entry.path !== "_node.json" && entry.path !== ".busabaseignore" && !ignore.ignores(entry.path));
 		assertNoReservedNames(entries.map((entry) => entry.path), `${meta.type} "${slug}"`);
+		if (meta.type === "airapp" && !entries.some((entry) => entry.path === "package.json")) throw new Error(`AirApp "${slug}" has no package.json to install${ignore.isEmpty ? "" : ` — check ${dir}${PACKAGE_AIRAPP_IGNORE}, which must never exclude it`}. Nothing was installed.`);
 		return {
 			type: meta.type,
 			slug,
@@ -6707,6 +7069,19 @@ const readDirNode = (files, dir, slug) => {
 		children: readNodes(files, dir)
 	};
 };
+/**
+* `.busabaseignore` inside a file-tree node directory.
+*
+* Read here rather than at the package level because the exclusions are a
+* property of one project (an AirApp's `test/` is noise; a Drive's files are
+* the point), and a package-wide ignore list would make it possible to
+* accidentally strip another node's content from a distance.
+*/
+const readIgnoreFile = (files, dir) => {
+	const bytes = files.get(`${dir}${PACKAGE_AIRAPP_IGNORE}`);
+	if (!bytes) return IGNORE_NOTHING;
+	return parseIgnoreFile(decodeText(bytes, `${dir}${PACKAGE_AIRAPP_IGNORE}`));
+};
 const readRecords = (files, dir, slug) => {
 	const recordsPath = `${dir}${PACKAGE_RECORDS_FILENAME}`;
 	const bytes = files.get(recordsPath);
@@ -6782,202 +7157,160 @@ const stripExtension = (fileName) => {
 	return dot > 0 ? fileName.slice(0, dot) : fileName;
 };
 //#endregion
-//#region ../../packages/busabase-package/src/layout-write.ts
+//#region ../../packages/busabase-package/src/template.ts
 /**
-* Layout writer: the in-memory tree → a repo directory (§6.1), deterministically
-* (§6.6). "Clean diffs" is a feature: for an unchanged space, `export` twice must
-* produce byte-identical output, so re-exporting after one record edit diffs as
-* exactly one changed NDJSON line.
+* Is this package a **template** — a package that is also an Agent Skill?
 *
-* Determinism rules, all enforced here:
-*   • 2-space-indented JSON with a schema-defined key order
-*   • `options` blobs (carried verbatim from the server, whose JSONB key order is
-*     not a contract) are deep key-sorted
-*   • records sorted by `key`, one per line
-*   • LF endings, trailing newline on every file
+* One function answers that for all four consumers, which is the point: the
+* Template Center's index CI, `busabase-cli install`, the dashboard's install
+* preview, and an agent checking its own output must never disagree about what
+* counts. A skill that shows up as a card but installs as a plain package (or
+* the reverse) is a trust bug, not a cosmetic one.
+*
+* Purely static: no AirApp is started, no script is executed, no server is
+* contacted. That is what lets it run in CI over a whole repo and inline in an
+* install preview without a timeout budget.
+*
+* **Hard conditions** (any failure ⇒ not a template). They are deliberately few,
+* and every one of them is something that would otherwise become a confusing
+* runtime failure for the installing user rather than a publishing error for
+* the author.
+*
+* **Soft conditions** are warnings: the package still installs and still lists,
+* the card is just honest about what is missing. A data-only template is a
+* legitimate thing to publish; one that silently claims to have an app is not.
+*
+* Crucially, a package that fails validation is NOT rejected from installing —
+* it installs as a plain `busabase-package@1`, exactly as it did before
+* templates existed. Failing to be a template is never a reason to refuse a
+* valid package.
+*
+* Spec: `apps/busabase/content/spec/template-center.md` §5.3.
 */
 /**
-* Deep key-sort. Applied to blobs the server owns the key order of (field
-* `options`), never to arrays — `choices`, `filters`, and `sorts` are ordered data.
+* `PackageFileTreeNode.type` is the whole skill|airapp|drive union rather than a
+* literal, so a discriminated-union `Extract` narrows to `never` here — the
+* predicate does the narrowing instead.
 */
-const sortKeysDeep = (value) => {
-	if (Array.isArray(value)) return value.map(sortKeysDeep);
-	if (value === null || typeof value !== "object") return value;
-	const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a.localeCompare(b, "en"));
-	return Object.fromEntries(entries.map(([key, item]) => [key, sortKeysDeep(item)]));
-};
-/** 2-space JSON + trailing LF. Key order is the insertion order of `value`. */
-const toJsonFile = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
-/** Drop `undefined` so optional keys vanish rather than serializing inconsistently. */
-const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
-const serializeManifest = (manifest) => toJsonFile(compact({
-	format: manifest.format,
-	name: manifest.name,
-	description: manifest.description || void 0,
-	version: manifest.version,
-	author: manifest.author,
-	license: manifest.license,
-	homepage: manifest.homepage,
-	tags: manifest.tags.length > 0 ? manifest.tags : void 0
-}));
-const serializeField = (field) => compact({
-	slug: field.slug,
-	name: field.name,
-	type: field.type,
-	required: field.required,
-	position: field.position,
-	options: sortKeysDeep(field.options)
-});
-const serializeView = (view) => compact({
-	slug: view.slug,
-	name: view.name,
-	description: view.description || void 0,
-	type: view.type,
-	config: compact({
-		filters: view.config.filters.map((filter) => compact({
-			fieldSlug: filter.fieldSlug,
-			operator: filter.operator,
-			value: filter.value
-		})),
-		sorts: view.config.sorts.map((sort) => ({
-			direction: sort.direction,
-			fieldSlug: sort.fieldSlug
-		})),
-		visibleFieldSlugs: view.config.visibleFieldSlugs ?? void 0,
-		fieldWidths: view.config.fieldWidths
-	})
-});
-const serializeBase = (base, position) => toJsonFile(compact({
-	name: base.name,
-	description: base.description || void 0,
-	position,
-	reviewPolicy: base.reviewPolicy,
-	fields: base.fields.map(serializeField),
-	views: base.views.map(serializeView)
-}));
-/** One JSON object per line, sorted by `key` — determinism (§6.4). */
-const serializeRecords = (records) => {
-	const lines = [...records].sort((a, b) => a.key.localeCompare(b.key, "en")).map((record) => JSON.stringify({
-		key: record.key,
-		fields: record.fields
-	}));
-	return Buffer.from(lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
+const isAirApp = (node) => node.type === "airapp";
+const airAppSlugs = (tree) => [...walkNodes(tree.nodes)].filter(isAirApp).map((node) => node.slug);
+const baseSlugs = (tree) => new Set([...walkNodes(tree.nodes)].filter((node) => node.type === "base").map((node) => node.slug));
+const validateTemplate = (tree) => {
+	const errors = [];
+	const warnings = [];
+	const template = tree.manifest.template;
+	if (!tree.rootSkill) return {
+		ok: false,
+		errors: [`No ${PACKAGE_SKILL_ENTRY} at the package root — this is a plain package.`],
+		warnings
+	};
+	const entry = tree.rootSkill.files.find((file) => file.path === PACKAGE_SKILL_ENTRY);
+	let frontmatter;
+	if (entry) try {
+		const { data } = parseFrontmatter(entry.bytes.toString("utf8"), PACKAGE_SKILL_ENTRY);
+		frontmatter = SkillFrontmatterSchema.safeParse(data);
+		if (!frontmatter.success) errors.push(`${PACKAGE_SKILL_ENTRY} frontmatter is not a valid skill declaration: ${frontmatter.error.issues.map((issue) => `${issue.path.join(".") || "(root)"} ${issue.message}`).join("; ")}`);
+	} catch (error) {
+		errors.push(`${PACKAGE_SKILL_ENTRY}: ${error.message}`);
+	}
+	const skill = frontmatter?.success ? frontmatter.data : void 0;
+	const busabaseMeta = skill?.metadata?.busabase;
+	if (skill && busabaseMeta?.template !== true) errors.push(`${PACKAGE_SKILL_ENTRY} does not opt in as a template. Add \`metadata.busabase.template: true\` to publish it in the Template Center.`);
+	if (!template) errors.push(`${PACKAGE_SKILL_ENTRY} declares a template but busabase.json has no \`template\` object (at least \`category\` is required).`);
+	if (skill && skill.name !== tree.manifest.name) errors.push(`Name mismatch: ${PACKAGE_SKILL_ENTRY} declares "${skill.name}" but busabase.json declares "${tree.manifest.name}". They are the same app and must agree.`);
+	const bases = baseSlugs(tree);
+	for (const key of busabaseMeta?.resources ?? []) if (!bases.has(key)) errors.push(`${PACKAGE_SKILL_ENTRY} lists resource "${key}", but content/ has no Base with that slug. An agent told about a table that does not exist will write to the wrong one.`);
+	const airapps = airAppSlugs(tree);
+	const resolved = resolvePrimaryAirApp(template, airapps);
+	let primaryAirApp;
+	if ("slug" in resolved) primaryAirApp = resolved.slug;
+	else if (airapps.length > 0 || template?.airapp || template?.airapps?.length) errors.push(resolved.error);
+	for (const node of walkNodes(tree.nodes)) {
+		if (!isAirApp(node)) continue;
+		const manifestFile = node.files.find((file) => file.path === "package.json");
+		if (!manifestFile) continue;
+		let scripts;
+		try {
+			scripts = JSON.parse(manifestFile.bytes.toString("utf8")).scripts;
+		} catch (error) {
+			errors.push(`AirApp "${node.slug}": package.json is not valid JSON (${error.message}).`);
+			continue;
+		}
+		if (typeof scripts?.dev !== "string") errors.push(`AirApp "${node.slug}": package.json has no \`dev\` script. Busabase starts an AirApp with \`npm run dev\`, so without it the app installs and then never boots.`);
+	}
+	if (airapps.length === 0) warnings.push("No AirApp — this template installs data only. Users will see tables, not an app.");
+	if (template?.requires?.airapp && airapps.length === 0) errors.push("template.requires.airapp is true, but content/ contains no AirApp.");
+	let hasSamples = false;
+	for (const node of walkNodes(tree.nodes)) {
+		if (node.type !== "base") continue;
+		if (node.records.length > 0) hasSamples = true;
+		if (node.records.length > 50) errors.push(`Base "${node.slug}" carries ${node.records.length} sample records, above the 50 per-Base limit for templates. A template seeds a demo; it does not ship a dataset.`);
+	}
+	if (!hasSamples) warnings.push("No sample records — the app will be empty on first open.");
+	if (!template?.screenshots.length) warnings.push("No screenshots declared — the Template Center card will use a placeholder.");
+	if (!template?.agentPrompts.length) warnings.push("No agentPrompts declared — \"Ask agent\" will open with an empty prompt.");
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings,
+		...primaryAirApp ? { primaryAirApp } : {},
+		...template ? { template } : {}
+	};
 };
 /**
-* Render a tree to package-relative paths + bytes, validating §6.3 as it goes.
-* Pure: no disk access, so the round-trip and determinism tests exercise it directly.
+* A starting SKILL.md for a folder that has resources but no manual yet.
+*
+* Deterministic, never generated by a model: this text becomes instructions an
+* agent will act on, and a plausible-sounding invention about what a table means
+* is worse than an obvious blank to fill in. Everything here is read off the
+* structure that actually exists — table names, their fields, whether there is
+* an app — and every judgement the author has to make is left as an explicit
+* TODO rather than guessed at.
+*
+* Used by `export --template` and by "Publish as template" in the dashboard.
 */
-const renderPackageTree = (tree) => {
-	const files = /* @__PURE__ */ new Map();
-	files.set(PACKAGE_MANIFEST_FILENAME, serializeManifest(tree.manifest));
-	renderNodes(tree.nodes, `${PACKAGE_CONTENT_DIRNAME}/`, files);
-	renderDocAssets(tree.assets ?? [], files);
-	return files;
+const deriveSkillDraft = (tree) => {
+	const nodes = [...walkNodes(tree.nodes)];
+	const bases = nodes.filter((node) => node.type === "base");
+	const airapps = nodes.filter(isAirApp);
+	const name = tree.manifest.name;
+	const description = tree.manifest.description || `TODO: one line on what ${name} does.`;
+	const yamlString = (value) => JSON.stringify(value);
+	const resourceLines = bases.map((node) => `      - ${yamlString(node.slug)}`).join("\n");
+	const resourceDocs = bases.map((node) => {
+		if (node.type !== "base") return "";
+		const fields = node.base.fields.map((field) => field.slug).join(", ");
+		return `- \`${node.slug}\`: ${node.description || "TODO: what this table is for."}${fields ? ` Fields: ${fields}.` : ""}`;
+	}).filter(Boolean).join("\n");
+	return `---
+name: ${yamlString(name)}
+description: ${yamlString(description)}
+metadata:
+  busabase:
+    template: true
+${bases.length ? `    resources:\n${resourceLines}\n` : ""}---
+
+# ${name}
+
+TODO: describe the job this app does, and when an agent should reach for it.
+
+## Busabase resources
+
+${resourceDocs || "TODO: list this app's tables and what each one holds."}
+${airapps.length ? `\n## App\n\n\`${airapps[0].slug}\` is the app's interface. Point the user at it rather than describing rows back to them.\n` : ""}
+## Boundary
+
+TODO: state what this app must never do — send messages, call external APIs,
+merge its own proposals. Be explicit; an agent follows what is written here.
+
+## Workflow
+
+Propose changes as Change Requests and wait for a human to review them. Never
+review or merge your own proposal.
+`;
 };
-/**
-* `assets/<assetId><ext>` + its `.asset.json` sidecar, for every image the Docs
-* embed. Deduped by asset id (one image in three Docs is one pair of files) and
-* emitted in a fixed order, so a re-export of an unchanged space is still
-* byte-identical (§6.6).
-*/
-const renderDocAssets = (assets, files) => {
-	const byId = /* @__PURE__ */ new Map();
-	for (const asset of assets) if (!byId.has(asset.assetId)) byId.set(asset.assetId, asset);
-	for (const asset of [...byId.values()].sort((a, b) => a.assetId.localeCompare(b.assetId, "en"))) {
-		const bytesPath = docAssetBytesPath(asset);
-		assertSafeFilePath(bytesPath, `doc asset "${asset.assetId}"`);
-		files.set(bytesPath, asset.bytes);
-		files.set(`${bytesPath}${PACKAGE_ASSET_META_SUFFIX}`, toJsonFile(compact({
-			assetId: asset.assetId,
-			fileName: asset.fileName,
-			mimeType: asset.mimeType,
-			contentHash: asset.contentHash
-		})));
-	}
-};
-const renderNodes = (nodes, dir, files) => {
-	const ordered = sortNodes(nodes);
-	assertNoSiblingCaseCollisions(ordered.map((node) => node.slug), `in ${dir}`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const node of ordered) {
-		assertSafeNodeSlug(node.slug, `${node.type} node`);
-		if (seen.has(node.slug)) throw new Error(`Two nodes in ${dir} would be written as "${node.slug}". Sibling slugs must be unique.`);
-		seen.add(node.slug);
-		renderNode(node, dir, files);
-	}
-};
-const renderNode = (node, dir, files) => {
-	switch (node.type) {
-		case "folder":
-			if (node.children.length === 0 || node.description !== "" || node.position !== void 0 || node.name !== void 0) files.set(`${dir}${node.slug}/${PACKAGE_FOLDER_META_FILENAME}`, toJsonFile(compact({
-				name: node.name,
-				description: node.description || void 0,
-				position: node.position
-			})));
-			renderNodes(node.children, `${dir}${node.slug}/`, files);
-			return;
-		case "doc":
-			files.set(`${dir}${node.slug}.md`, Buffer.from(serializeDoc({
-				name: node.name,
-				description: node.description,
-				position: node.position
-			}, node.body), "utf8"));
-			return;
-		case "base": {
-			files.set(`${dir}${node.slug}/${PACKAGE_BASE_FILENAME}`, serializeBase(node.base, node.position));
-			const records = serializeRecords(node.records);
-			if (records.byteLength > 0) files.set(`${dir}${node.slug}/${PACKAGE_RECORDS_FILENAME}`, records);
-			return;
-		}
-		case "skill":
-		case "airapp":
-		case "drive": {
-			const nodeDir = `${dir}${node.slug}/`;
-			assertNoReservedNames(node.files.map((entry) => entry.path), `${node.type} "${node.slug}"`);
-			files.set(`${nodeDir}${PACKAGE_NODE_META_FILENAME}`, toJsonFile(compact({
-				type: node.type,
-				name: node.name,
-				description: node.description || void 0,
-				position: node.position
-			})));
-			for (const entry of [...node.files].sort((a, b) => a.path.localeCompare(b.path, "en"))) {
-				assertSafeFilePath(entry.path, `${node.type} "${node.slug}"`);
-				files.set(`${nodeDir}${entry.path}`, entry.bytes);
-			}
-			return;
-		}
-		case "file":
-			assertSafeFilePath(node.fileName, `file node "${node.slug}"`);
-			files.set(`${dir}${node.fileName}`, node.bytes);
-			if (node.name !== node.fileName || node.description !== "" || node.position !== void 0) files.set(`${dir}${node.fileName}${PACKAGE_NODE_META_SUFFIX}`, toJsonFile(compact({
-				name: node.name,
-				description: node.description || void 0,
-				position: node.position
-			})));
-			return;
-	}
-};
-/** Write rendered files under `outDir`, creating directories as needed. */
-const writePackageFiles = async (files, outDir, options = {}) => {
-	if (options.clean) {
-		await rm(join(outDir, PACKAGE_CONTENT_DIRNAME), {
-			recursive: true,
-			force: true
-		});
-		await rm(join(outDir, PACKAGE_ASSETS_DIRNAME), {
-			recursive: true,
-			force: true
-		});
-		await rm(join(outDir, PACKAGE_MANIFEST_FILENAME), { force: true });
-	}
-	for (const [filePath, bytes] of [...files].sort(([a], [b]) => a.localeCompare(b, "en"))) {
-		const target = join(outDir, filePath);
-		await mkdir(dirname(target), { recursive: true });
-		await writeFile(target, bytes);
-	}
-};
-//#endregion
-//#region ../../packages/busabase-package/src/plan.ts
+//#endregion
+//#region ../../packages/busabase-package/src/plan.ts
 /**
 * Install planning: package tree + the target space's current state → a plan, a
 * collision report, and the `--dry-run` rendering. Creates nothing.
@@ -7025,9 +7358,16 @@ const buildInstallPlan = (tree, target, options = {}) => {
 	const targetFolderSlug = options.intoFolder ?? suggestSlug(tree.manifest.name);
 	const warnings = [];
 	assertPackageNodeIdentitiesUnique(tree);
-	const collisions = findCollisions(tree, targetFolderSlug, target);
-	let planned = tree;
-	if (options.rename && collisions.length > 0) planned = applyRenames(tree, collisions, target.existingNodeSlugsByType);
+	const isTemplate = validateTemplate(tree).ok;
+	const prefixed = options.prefixBaseSlugs ?? isTemplate ? prefixBaseSlugs(tree, targetFolderSlug) : tree;
+	const resourceKeysBySlug = {};
+	for (const [installedSlug, originalSlug] of collectSlugRewrites(tree, prefixed)) resourceKeysBySlug[installedSlug] = originalSlug;
+	const collisions = findCollisions(prefixed, targetFolderSlug, target);
+	let planned = prefixed;
+	if (options.rename && collisions.length > 0) {
+		planned = applyRenames(prefixed, collisions, target.existingNodeSlugsByType);
+		for (const [installedSlug, originalSlug] of collectSlugRewrites(tree, planned)) resourceKeysBySlug[installedSlug] = originalSlug;
+	}
 	collectWarnings(planned, warnings);
 	const counts = countTree(planned);
 	if (counts.files > 5e3) throw new Error(`Package has ${counts.files} files, above the ${PACKAGE_MAX_FILE_COUNT}-file limit. Nothing was installed.`);
@@ -7038,8 +7378,79 @@ const buildInstallPlan = (tree, target, options = {}) => {
 		collisions,
 		warnings,
 		counts,
-		requiresAutoMerge: collectBaseNodes(planned.nodes).some(hasUnlinkableRelationValues)
+		requiresAutoMerge: collectBaseNodes(planned.nodes).some(hasUnlinkableRelationValues) && !(isTemplate && (options.installSampleRecords ?? true)),
+		resourceKeysBySlug,
+		isTemplate
+	};
+};
+/**
+* Rewrite every Base slug to `<folder>-<slug>`, following relation targets.
+*
+* A Base already carrying the prefix is left alone, so re-planning an installed
+* package (an upgrade, a retry) does not stack `kelly-email-kelly-email-…`.
+* Only Bases are prefixed: every other node type is scoped to its parent
+* folder, so only Bases can collide across folders in the first place.
+*/
+const prefixBaseSlugs = (tree, folderSlug) => {
+	const renames = /* @__PURE__ */ new Map();
+	for (const node of walkNodes(tree.nodes)) {
+		if (node.type !== "base") continue;
+		if (node.slug === folderSlug || node.slug.startsWith(`${folderSlug}-`)) continue;
+		renames.set(node.slug, `${folderSlug}-${node.slug}`);
+	}
+	if (renames.size === 0) return tree;
+	const rewriteField = (field) => {
+		const target = field.options.targetBaseSlug;
+		if (!target) return field;
+		const renamed = renames.get(target);
+		return renamed ? {
+			...field,
+			options: {
+				...field.options,
+				targetBaseSlug: renamed
+			}
+		} : field;
+	};
+	const rewrite = (node) => {
+		if (node.type === "folder") return {
+			...node,
+			children: node.children.map(rewrite)
+		};
+		if (node.type !== "base") return node;
+		return {
+			...node,
+			slug: renames.get(node.slug) ?? node.slug,
+			base: {
+				...node.base,
+				fields: node.base.fields.map(rewriteField)
+			}
+		};
+	};
+	return {
+		...tree,
+		nodes: tree.nodes.map(rewrite)
+	};
+};
+/**
+* Pair up two trees that differ only in slugs, walking them in lockstep.
+*
+* Position-based rather than slug-based on purpose: after a rewrite the slugs
+* are exactly what no longer match, so they cannot be the join key. Both trees
+* come from the same source and every rewrite preserves order, so position is
+* stable.
+*/
+const collectSlugRewrites = (original, rewritten) => {
+	const pairs = [];
+	const walk = (before, after) => {
+		for (const [index, beforeNode] of before.entries()) {
+			const afterNode = after[index];
+			if (!afterNode) continue;
+			pairs.push([afterNode.slug, beforeNode.slug]);
+			if (beforeNode.type === "folder" && afterNode.type === "folder") walk(beforeNode.children, afterNode.children);
+		}
 	};
+	walk(original.nodes, rewritten.nodes);
+	return pairs;
 };
 /**
 * The ONLY thing that genuinely can't survive a review-first install: a record that
@@ -7119,129 +7530,696 @@ const applyRenames = (tree, collisions, existingNodeSlugsByType) => {
 		if (node.type === "base") baseRenames.set(node.slug, renamed);
 		collision.renamedTo = renamed;
 	}
-	const rewriteNode = (node) => {
-		const slug = nodeRenames.get(nodeIdentityKey(node)) ?? node.slug;
-		if (node.type === "base") return {
-			...node,
-			slug,
-			base: {
-				...node.base,
-				fields: node.base.fields.map(rewriteFieldTarget)
-			}
-		};
-		if (node.type === "folder") return {
-			...node,
-			slug,
-			children: node.children.map(rewriteNode)
-		};
-		return {
-			...node,
-			slug
-		};
-	};
-	const rewriteFieldTarget = (field) => {
-		const targetBaseSlug = field.options.targetBaseSlug;
-		if (!targetBaseSlug) return field;
-		const renamed = baseRenames.get(targetBaseSlug);
-		if (!renamed) return field;
-		return {
-			...field,
-			options: {
-				...field.options,
-				targetBaseSlug: renamed
-			}
-		};
-	};
-	return {
-		...tree,
-		nodes: tree.nodes.map(rewriteNode)
-	};
+	const rewriteNode = (node) => {
+		const slug = nodeRenames.get(nodeIdentityKey(node)) ?? node.slug;
+		if (node.type === "base") return {
+			...node,
+			slug,
+			base: {
+				...node.base,
+				fields: node.base.fields.map(rewriteFieldTarget)
+			}
+		};
+		if (node.type === "folder") return {
+			...node,
+			slug,
+			children: node.children.map(rewriteNode)
+		};
+		return {
+			...node,
+			slug
+		};
+	};
+	const rewriteFieldTarget = (field) => {
+		const targetBaseSlug = field.options.targetBaseSlug;
+		if (!targetBaseSlug) return field;
+		const renamed = baseRenames.get(targetBaseSlug);
+		if (!renamed) return field;
+		return {
+			...field,
+			options: {
+				...field.options,
+				targetBaseSlug: renamed
+			}
+		};
+	};
+	return {
+		...tree,
+		nodes: tree.nodes.map(rewriteNode)
+	};
+};
+const collectWarnings = (tree, warnings) => {
+	for (const baseNode of collectBaseNodes(tree.nodes)) if (baseNode.base.reviewPolicy) warnings.push(`Base "${baseNode.slug}" declares a reviewPolicy (${baseNode.base.reviewPolicy.kind}, ${baseNode.base.reviewPolicy.requiredApprovals} approval(s)), but reviewPolicy cannot be set when creating a Base — the target's default applies. Adjust it in the UI afterwards if needed.`);
+};
+const countTree = (tree) => {
+	const counts = {
+		folders: 0,
+		docs: 0,
+		bases: 0,
+		records: 0,
+		skills: 0,
+		airapps: 0,
+		drives: 0,
+		files: 0
+	};
+	for (const node of walkNodes(tree.nodes)) switch (node.type) {
+		case "folder":
+			counts.folders++;
+			break;
+		case "doc":
+			counts.docs++;
+			break;
+		case "base":
+			counts.bases++;
+			counts.records += node.records.length;
+			break;
+		case "skill":
+			counts.skills++;
+			counts.files += node.files.length;
+			break;
+		case "airapp":
+			counts.airapps++;
+			counts.files += node.files.length;
+			break;
+		case "drive":
+			counts.drives++;
+			counts.files += node.files.length;
+			break;
+		case "file": counts.files++;
+	}
+	counts.files += (tree.assets ?? []).length;
+	return counts;
+};
+/** §4: "What will this do?" — the `--dry-run` report. Creates nothing. */
+const renderPlan = (plan) => {
+	const lines = [];
+	lines.push(`Package: ${plan.tree.manifest.name}`);
+	if (plan.tree.manifest.description) lines.push(`  ${plan.tree.manifest.description}`);
+	lines.push("");
+	lines.push(`Target folder: ${plan.targetFolderSlug}`);
+	lines.push("");
+	lines.push("Node tree:");
+	for (const line of renderNodeTree(plan.tree.nodes, "  ")) lines.push(line);
+	lines.push("");
+	lines.push(`Totals: ${plan.counts.folders} folder(s), ${plan.counts.docs} doc(s), ${plan.counts.bases} base(s) with ${plan.counts.records} record(s), ${plan.counts.skills} skill(s), ${plan.counts.airapps} airapp(s), ${plan.counts.drives} drive(s), ${plan.counts.files} file(s)`);
+	if (plan.collisions.length > 0) {
+		lines.push("");
+		lines.push("Collisions:");
+		for (const collision of plan.collisions) lines.push(collision.renamedTo ? `  • ${collision.kind} "${collision.slug}" already exists → will be created as "${collision.renamedTo}"` : `  • ${collision.kind} "${collision.slug}" already exists (${collision.path})`);
+	}
+	if (plan.warnings.length > 0) {
+		lines.push("");
+		lines.push("Warnings:");
+		for (const warning of plan.warnings) lines.push(`  • ${warning}`);
+	}
+	return lines.join("\n");
+};
+const renderNodeTree = (nodes, indent) => {
+	const lines = [];
+	for (const node of nodes) {
+		const detail = node.type === "base" ? ` (base, ${node.base.fields.length} field(s), ${node.records.length} record(s))` : node.type === "folder" ? " (folder)" : node.type === "doc" ? " (doc)" : node.type === "file" ? " (file)" : ` (${node.type}, ${node.files.length} file(s))`;
+		lines.push(`${indent}${node.slug}${detail}`);
+		if (node.type === "folder") lines.push(...renderNodeTree(node.children, `${indent}  `));
+	}
+	return lines;
+};
+/**
+* §4 + §12: without `--auto-merge` an unmerged base has no field ids to patch and no
+* records to link, so passes 2-5 cannot run. Fail fast and say exactly why.
+*/
+const assertPlanIsApplicable = (plan, autoMerge) => {
+	if (plan.collisions.some((collision) => !collision.renamedTo)) {
+		const list = plan.collisions.filter((collision) => !collision.renamedTo).map((collision) => `  • ${collision.kind} "${collision.slug}" (${collision.path})`).join("\n");
+		throw new Error(`Install would collide with content that already exists:\n${list}\n\nNothing was created. Re-run with --rename to install the colliding items under suffixed slugs (e.g. "-2"), or pick a different --into-folder.`);
+	}
+	if (plan.requiresAutoMerge && !autoMerge) throw new Error("This package's records carry relation values, and a relation stores the ids of the records it points at — which only exist once the records are merged. Installing review-first would leave every relation empty.\n\nRe-run with --auto-merge to install it (this trusts the package author: records are created immediately instead of landing as change requests you review first).");
+};
+//#endregion
+//#region ../../packages/busabase-package/src/discover.ts
+/**
+* What is at the end of this URL — one package, one template, or a repository
+* full of them?
+*
+* A user pasting a GitHub URL does not think in terms of "package roots". They
+* paste the repo they were looking at. Sometimes that repo IS the package;
+* sometimes it is `busabase/skills`, which holds dozens under `skills/*`. Before
+* this, the second case was only ever an error message with a list of
+* subdirectories to paste instead — correct, and a dead end for anyone who did
+* not want to edit a URL by hand.
+*
+* Discovery answers it once for every caller: the CLI turns the result into a
+* pick-one list, the dashboard's install dialog into a chooser, the Template
+* Center's index CI into the set of cards to publish. All three must agree on
+* what counts as a template, which is why the verdict comes from the same
+* `validateTemplate` they would each otherwise re-implement.
+*
+* Spec: `apps/busabase/content/spec/template-center.md` §6.2a.
+*/
+/**
+* Only one level deep, matching the `skills/<name>/` layout the skills CLI
+* already established and the Template Center reads. Walking arbitrarily deep
+* would turn one paste into an unbounded scan of a monorepo and surface vendored
+* copies inside `node_modules` as installable products.
+*/
+const MAX_DISCOVERY_DEPTH = 2;
+const manifestDirectories = (files) => {
+	const dirs = /* @__PURE__ */ new Set();
+	for (const filePath of files.keys()) {
+		if (filePath === "busabase.json") {
+			dirs.add("");
+			continue;
+		}
+		if (!filePath.endsWith(`/busabase.json`)) continue;
+		const dir = filePath.slice(0, -14);
+		if (dir.split("/").length > MAX_DISCOVERY_DEPTH) continue;
+		dirs.add(dir);
+	}
+	return [...dirs].sort((a, b) => a.localeCompare(b, "en"));
+};
+/**
+* Every package at or below the fetched root, root first.
+*
+* A directory whose manifest or content does not parse is SKIPPED rather than
+* failing the whole discovery: one malformed skill in a repository of fifty must
+* not make the other forty-nine unreachable. The user is choosing from a list,
+* and an entry that cannot be read has nothing to offer that list.
+*/
+const discoverPackages = (files) => {
+	const found = [];
+	for (const subdir of manifestDirectories(files)) {
+		if (found.length >= 200) break;
+		let tree;
+		try {
+			tree = readPackageTree(files, subdir ? { root: subdir } : {});
+		} catch {
+			continue;
+		}
+		const validation = validateTemplate(tree);
+		const claimsTemplate = Boolean(tree.rootSkill) || Boolean(tree.manifest.template);
+		found.push({
+			subdir,
+			name: tree.manifest.name,
+			description: tree.manifest.description,
+			isTemplate: validation.ok,
+			templateErrors: validation.ok || !claimsTemplate ? [] : validation.errors,
+			counts: countTree(tree),
+			...validation.primaryAirApp ? { primaryAirApp: validation.primaryAirApp } : {},
+			...tree.manifest.template?.category ? { category: tree.manifest.template.category } : {},
+			screenshots: tree.manifest.template?.screenshots ?? [],
+			tags: [.../* @__PURE__ */ new Set([...tree.manifest.tags, ...tree.manifest.template?.tags ?? []])],
+			agentPrompts: tree.manifest.template?.agentPrompts ?? [],
+			...tree.manifest.version ? { version: tree.manifest.version } : {},
+			...tree.manifest.author ? { author: tree.manifest.author } : {},
+			...tree.manifest.license ? { license: tree.manifest.license } : {}
+		});
+	}
+	return found;
+};
+/**
+* Resolve a pasted URL to the ONE package to install, or explain the choice.
+*
+* `wanted` is a name or subdir the caller already picked (the CLI's `--skill`,
+* the dialog's selection). Matching on either is deliberate: a user reading a
+* list sees names, a user reading a repo sees directories, and asking them to
+* know which one the tool wants is a distinction without a purpose.
+*/
+const resolvePackageToInstall = (files, wanted) => {
+	const discovered = discoverPackages(files);
+	if (discovered.length === 0) return { kind: "none" };
+	if (wanted) {
+		const match = discovered.find((entry) => entry.name === wanted || entry.subdir === wanted || entry.subdir.endsWith(`/${wanted}`));
+		if (match) return {
+			kind: "package",
+			subdir: match.subdir,
+			discovered: match
+		};
+		return {
+			kind: "choose",
+			candidates: discovered
+		};
+	}
+	const root = discovered.find((entry) => entry.subdir === "");
+	if (root) return {
+		kind: "package",
+		subdir: "",
+		discovered: root
+	};
+	if (discovered.length === 1) return {
+		kind: "package",
+		subdir: discovered[0].subdir,
+		discovered: discovered[0]
+	};
+	return {
+		kind: "choose",
+		candidates: discovered
+	};
+};
+//#endregion
+//#region ../../packages/busabase-package/src/github.ts
+/**
+* GitHub source for `busabase-cli install`: parse a repo URL, fetch the ref's
+* zipball, and extract it into memory.
+*
+* Ported from Buda's GitHub skill importer (Buda stays as-is; a shared package
+* is warranted only once the Phase-2 server consumer actually exists). Three
+* deliberate divergences from that original:
+*
+* 1. **Host is parsed, not pattern-matched.** buda's regex matches `github.com/…`
+*    anywhere in the string, so `https://evil.example/github.com/o/r` passes. This
+*    parses with `URL` and checks `hostname` against an allowlist.
+* 2. **Any git ref, not just branches.** buda fetches `/archive/refs/heads/<b>.zip`,
+*    which resolves branches only — tags (the package format's version scheme)
+*    would 404. This uses codeload's `/zip/<ref>`, which takes a branch, tag, or SHA.
+* 3. **Extraction is to memory with the caps applied first**, so an oversized or
+*    zip-bomb archive never reaches the disk.
+*/
+/** Hosts the installer may ever connect to. Also the Phase-2 server guard's allowlist. */
+const GITHUB_ALLOWED_HOSTS = [
+	"github.com",
+	"api.github.com",
+	"codeload.github.com"
+];
+/** Hosts accepted in a user-supplied install URL (the web UI form of a repo). */
+const GITHUB_URL_HOSTS = ["github.com", "www.github.com"];
+const isAllowedGithubHost = (hostname) => GITHUB_ALLOWED_HOSTS.includes(hostname.toLowerCase());
+/**
+* Parse a GitHub repo URL.
+*
+* Supported forms:
+*   https://github.com/owner/repo
+*   https://github.com/owner/repo.git
+*   https://github.com/owner/repo/tree/<ref>
+*   https://github.com/owner/repo/tree/<ref>/<subdir…>
+*
+* A ref containing `/` (e.g. `feature/x`) is indistinguishable from `<ref>/<subdir>`
+* in a `/tree/` URL — GitHub's own web URLs have the same ambiguity — so the first
+* segment after `/tree/` is taken as the ref and the rest as the subdir.
+*/
+const parseGithubUrl = (rawUrl) => {
+	let url;
+	try {
+		url = new URL(rawUrl.trim());
+	} catch {
+		throw new Error(`Not a valid URL: "${rawUrl}". Expected a GitHub repo URL, e.g. https://github.com/acme/support-kb-template`);
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`Unsupported URL scheme "${url.protocol}" — expected an https:// GitHub URL.`);
+	if (!GITHUB_URL_HOSTS.includes(url.hostname.toLowerCase())) throw new Error(`Not a GitHub URL: host "${url.hostname}" is not github.com. Only GitHub packages can be installed.`);
+	const [owner, rawRepo, marker, ref, ...rest] = url.pathname.split("/").filter(Boolean);
+	if (!owner || !rawRepo) throw new Error(`GitHub URL is missing owner/repo: "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`);
+	const repo = rawRepo.replace(/\.git$/, "");
+	if (!marker) return {
+		owner,
+		repo,
+		ref: void 0,
+		subdir: void 0
+	};
+	if (marker !== "tree") throw new Error(`Unsupported GitHub URL form "/${marker}/" in "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`);
+	if (!ref) throw new Error(`GitHub URL has "/tree/" but no ref: "${rawUrl}".`);
+	return {
+		owner,
+		repo,
+		ref: decodeURIComponent(ref),
+		subdir: rest.length > 0 ? rest.map((segment) => decodeURIComponent(segment)).join("/") : void 0
+	};
+};
+/** Encode a ref for a URL path while keeping its `/` separators (e.g. `feature/x`). */
+const encodeRefPath = (ref) => ref.split("/").map(encodeURIComponent).join("/");
+/**
+* Download the zipball for `owner/repo` at `ref` (default branch when `ref` is
+* undefined). Tries the public codeload host first, then the authenticated API when
+* a token is available — so a private repo works iff `GITHUB_TOKEN` is set.
+*/
+const downloadGithubZip = async (source, options = {}) => {
+	const fetcher = options.fetcher ?? fetch;
+	const { owner, repo, ref } = source;
+	const slug = `${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+	const label = `${owner}/${repo}${ref ? `@${ref}` : ""}`;
+	const publicUrl = `https://codeload.github.com/${slug}/zip/${ref ? encodeRefPath(ref) : "HEAD"}`;
+	assertAllowedUrl(publicUrl);
+	const publicResponse = await fetcher(publicUrl);
+	if (publicResponse.ok) return Buffer.from(await publicResponse.arrayBuffer());
+	if (!options.githubToken) throw new Error(publicResponse.status === 404 ? `GitHub repo or ref not found: ${label} (HTTP 404).\n  • Check the URL, and that the branch/tag exists.\n  • Private repo? Set GITHUB_TOKEN=<a token with repo read access> and re-run.` : `Failed to download ${label} from GitHub (HTTP ${publicResponse.status} ${publicResponse.statusText}).`);
+	const apiUrl = `https://api.github.com/repos/${slug}/zipball${ref ? `/${encodeRefPath(ref)}` : ""}`;
+	assertAllowedUrl(apiUrl);
+	const authedResponse = await fetcher(apiUrl, { headers: {
+		Accept: "application/vnd.github+json",
+		Authorization: `Bearer ${options.githubToken}`,
+		"X-GitHub-Api-Version": "2022-11-28"
+	} });
+	if (authedResponse.ok) return Buffer.from(await authedResponse.arrayBuffer());
+	if (authedResponse.status === 401 || authedResponse.status === 403) throw new Error(`GitHub rejected GITHUB_TOKEN for ${label} (HTTP ${authedResponse.status}). The token is invalid, expired, or lacks read access to this repo.`);
+	throw new Error(`GitHub repo or ref not found: ${label} (HTTP ${authedResponse.status}), even with GITHUB_TOKEN. Check the owner, repo, and ref.`);
+};
+/** SSRF guard: refuse anything off the GitHub allowlist before a connection is made. */
+const assertAllowedUrl = (rawUrl) => {
+	const url = new URL(rawUrl);
+	if (url.protocol !== "https:" || !isAllowedGithubHost(url.hostname)) throw new Error(`Refusing to fetch ${rawUrl} — only https on ${GITHUB_ALLOWED_HOSTS.join(", ")} is allowed.`);
+};
+/**
+* Zip-slip guard. Normalizes an archive entry path to a repo-relative path and
+* rejects anything that could escape the extraction root: `..`/`.` segments,
+* and Windows drive prefixes. A leading `/` is stripped rather than rejected —
+* that makes the path relative, which is already safe.
+*/
+const normalizeArchivePath = (value) => {
+	const normalized = value.replaceAll("\\", "/").replace(/^\/+|\/+$/g, "");
+	const segments = normalized.split("/");
+	if (!normalized || segments.some((segment) => segment === "." || segment === ".." || /^[a-zA-Z]:$/.test(segment))) throw new Error(`Unsafe archive path rejected: ${value}`);
+	return normalized;
+};
+/**
+* Extract a GitHub zipball into memory, keyed by repo-relative path (the archive's
+* single generated root directory — `owner-repo-<sha>/` — is stripped).
+*
+* Caps are enforced against the archive's declared entry sizes BEFORE any bytes are
+* read, so an oversized archive or zip bomb is refused up front and nothing is ever
+* written to disk.
+*/
+const extractZip = async (zipBuffer, options = {}) => {
+	const maxFiles = options.maxFiles ?? 5e3;
+	const maxTotalBytes = options.maxTotalBytes ?? 262144e3;
+	const maxFileBytes = options.maxFileBytes ?? 26214400;
+	const reader = new ZipReader(new Uint8ArrayReader(new Uint8Array(zipBuffer)));
+	try {
+		const files = (await reader.getEntries()).filter((entry) => !entry.directory);
+		const archiveRoot = files[0]?.filename.split("/")[0];
+		if (!archiveRoot) throw new Error("The downloaded repository archive is empty.");
+		const subdir = options.subdir ? normalizeArchivePath(options.subdir) : void 0;
+		const prefix = `${archiveRoot}/${subdir ? `${subdir}/` : ""}`;
+		for (const entry of files) normalizeArchivePath(entry.filename);
+		const selected = files.filter((entry) => entry.filename.startsWith(prefix));
+		if (selected.length > maxFiles) throw new Error(`Package has ${selected.length} files, above the ${maxFiles}-file limit. Nothing was installed.`);
+		let totalBytes = 0;
+		for (const entry of selected) {
+			const size = entry.uncompressedSize ?? 0;
+			const relativePath = entry.filename.slice(prefix.length);
+			if (size > maxFileBytes) throw new Error(`File "${relativePath}" is ${formatBytes(size)}, above the ${formatBytes(maxFileBytes)} per-file limit. Nothing was installed.`);
+			totalBytes += size;
+			if (totalBytes > maxTotalBytes) throw new Error(`Package unpacks to more than the ${formatBytes(maxTotalBytes)} total limit. Nothing was installed.`);
+		}
+		const result = /* @__PURE__ */ new Map();
+		for (const entry of selected) {
+			const relativePath = normalizeArchivePath(entry.filename.slice(prefix.length));
+			if (!entry.getData) continue;
+			const data = await entry.arrayBuffer();
+			result.set(relativePath, Buffer.from(data));
+		}
+		return result;
+	} finally {
+		await reader.close();
+	}
+};
+const formatBytes = (bytes) => bytes >= 1048576 ? `${Math.round(bytes / 1048576)}MB` : `${Math.round(bytes / 1024)}KB`;
+/** Parse, fetch, and extract in one step — the `install` command's entry point. */
+const fetchGithubPackageFiles = async (repoUrl, options = {}) => {
+	const source = parseGithubUrl(repoUrl);
+	const zipBuffer = await downloadGithubZip(source, options);
+	return {
+		source,
+		files: await extractZip(zipBuffer, { subdir: source.subdir })
+	};
+};
+//#endregion
+//#region ../../packages/busabase-package/src/index-build.ts
+/**
+* Build the Template Center's catalog from a directory of skills.
+*
+* The catalog is not hand-maintained. A card that says "6 tables" for a package
+* that installs five is a trust bug, not a typo — so every field here is read
+* off the package itself, and whether an entry appears at all is decided by the
+* SAME `validateTemplate` the installer uses. A skill that would install as a
+* plain package can never be listed as a template, because one function answers
+* that question for both.
+*
+* Deliberately a plain function over a file map rather than something that
+* walks a disk: the CLI hands it a checkout, and a future CI job could hand it
+* a fetched zipball, without either needing its own notion of what counts.
+*
+* Spec: `apps/busabase/content/spec/template-center.md` §6.4.
+*/
+/** Bumped when a consumer would misread an older file. */
+const TEMPLATE_INDEX_FORMAT = "busabase-template-index@1";
+const toEntry = (found, airapps) => ({
+	subdir: found.subdir,
+	name: found.name,
+	description: found.description,
+	category: found.category ?? "uncategorized",
+	tags: found.tags ?? [],
+	screenshots: found.screenshots,
+	agentPrompts: found.agentPrompts ?? [],
+	...found.version ? { version: found.version } : {},
+	...found.author ? { author: found.author } : {},
+	...found.license ? { license: found.license } : {},
+	stats: {
+		folders: found.counts.folders,
+		docs: found.counts.docs,
+		bases: found.counts.bases,
+		records: found.counts.records,
+		files: found.counts.files,
+		airapps,
+		skill: true
+	}
+});
+const buildTemplateIndex = (files, options) => {
+	const discovered = discoverPackages(files);
+	const templates = [];
+	const rejected = [];
+	for (const found of discovered) {
+		if (found.isTemplate) {
+			templates.push(toEntry(found, found.primaryAirApp ? 1 : 0));
+			continue;
+		}
+		if (found.templateErrors.length > 0) rejected.push({
+			subdir: found.subdir,
+			name: found.name,
+			errors: found.templateErrors
+		});
+	}
+	return {
+		format: TEMPLATE_INDEX_FORMAT,
+		repo: options.repo,
+		ref: options.ref,
+		templates: templates.sort((a, b) => a.name.localeCompare(b.name, "en")),
+		rejected: rejected.sort((a, b) => a.name.localeCompare(b.name, "en"))
+	};
+};
+const renderTemplateIndex = (index) => `${JSON.stringify(index, null, 2)}\n`;
+//#endregion
+//#region ../../packages/busabase-package/src/layout-write.ts
+/**
+* Layout writer: the in-memory tree → a repo directory (§6.1), deterministically
+* (§6.6). "Clean diffs" is a feature: for an unchanged space, `export` twice must
+* produce byte-identical output, so re-exporting after one record edit diffs as
+* exactly one changed NDJSON line.
+*
+* Determinism rules, all enforced here:
+*   • 2-space-indented JSON with a schema-defined key order
+*   • `options` blobs (carried verbatim from the server, whose JSONB key order is
+*     not a contract) are deep key-sorted
+*   • records sorted by `key`, one per line
+*   • LF endings, trailing newline on every file
+*/
+/**
+* Deep key-sort. Applied to blobs the server owns the key order of (field
+* `options`), never to arrays — `choices`, `filters`, and `sorts` are ordered data.
+*/
+const sortKeysDeep = (value) => {
+	if (Array.isArray(value)) return value.map(sortKeysDeep);
+	if (value === null || typeof value !== "object") return value;
+	const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a.localeCompare(b, "en"));
+	return Object.fromEntries(entries.map(([key, item]) => [key, sortKeysDeep(item)]));
+};
+/** 2-space JSON + trailing LF. Key order is the insertion order of `value`. */
+const toJsonFile = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+/** Drop `undefined` so optional keys vanish rather than serializing inconsistently. */
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+const serializeManifest = (manifest) => toJsonFile(compact({
+	format: manifest.format,
+	name: manifest.name,
+	description: manifest.description || void 0,
+	version: manifest.version,
+	author: manifest.author,
+	license: manifest.license,
+	homepage: manifest.homepage,
+	tags: manifest.tags.length > 0 ? manifest.tags : void 0,
+	template: manifest.template
+}));
+const serializeField = (field) => compact({
+	slug: field.slug,
+	name: field.name,
+	type: field.type,
+	required: field.required,
+	position: field.position,
+	options: sortKeysDeep(field.options)
+});
+const serializeView = (view) => compact({
+	slug: view.slug,
+	name: view.name,
+	description: view.description || void 0,
+	type: view.type,
+	config: compact({
+		filters: view.config.filters.map((filter) => compact({
+			fieldSlug: filter.fieldSlug,
+			operator: filter.operator,
+			value: filter.value
+		})),
+		sorts: view.config.sorts.map((sort) => ({
+			direction: sort.direction,
+			fieldSlug: sort.fieldSlug
+		})),
+		visibleFieldSlugs: view.config.visibleFieldSlugs ?? void 0,
+		fieldWidths: view.config.fieldWidths
+	})
+});
+const serializeBase = (base, position) => toJsonFile(compact({
+	name: base.name,
+	description: base.description || void 0,
+	position,
+	reviewPolicy: base.reviewPolicy,
+	fields: base.fields.map(serializeField),
+	views: base.views.map(serializeView)
+}));
+/** One JSON object per line, sorted by `key` — determinism (§6.4). */
+const serializeRecords = (records) => {
+	const lines = [...records].sort((a, b) => a.key.localeCompare(b.key, "en")).map((record) => JSON.stringify({
+		key: record.key,
+		fields: record.fields
+	}));
+	return Buffer.from(lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
+};
+/**
+* Render a tree to package-relative paths + bytes, validating §6.3 as it goes.
+* Pure: no disk access, so the round-trip and determinism tests exercise it directly.
+*/
+const renderPackageTree = (tree) => {
+	const files = /* @__PURE__ */ new Map();
+	files.set(PACKAGE_MANIFEST_FILENAME, serializeManifest(tree.manifest));
+	renderRootSkill(tree.rootSkill, files);
+	renderNodes(tree.nodes, `${PACKAGE_CONTENT_DIRNAME}/`, files);
+	renderDocAssets(tree.assets ?? [], files);
+	return files;
+};
+/**
+* The root skill's files, back at the package root — NOT under `content/`.
+*
+* This asymmetry with every other node is the whole point: writing it as
+* `content/<slug>/` would produce a package whose next install created a second
+* Skill node beside the first, and each export→install cycle would add another.
+* Round-tripping through the root is what keeps exactly one copy in existence.
+*/
+const renderRootSkill = (rootSkill, files) => {
+	if (!rootSkill) return;
+	for (const entry of rootSkill.files) {
+		assertSafeFilePath(entry.path, `root skill "${rootSkill.slug}"`);
+		files.set(entry.path, entry.bytes);
+	}
 };
-const collectWarnings = (tree, warnings) => {
-	for (const baseNode of collectBaseNodes(tree.nodes)) if (baseNode.base.reviewPolicy) warnings.push(`Base "${baseNode.slug}" declares a reviewPolicy (${baseNode.base.reviewPolicy.kind}, ${baseNode.base.reviewPolicy.requiredApprovals} approval(s)), but reviewPolicy cannot be set when creating a Base — the target's default applies. Adjust it in the UI afterwards if needed.`);
+/**
+* `assets/<assetId><ext>` + its `.asset.json` sidecar, for every image the Docs
+* embed. Deduped by asset id (one image in three Docs is one pair of files) and
+* emitted in a fixed order, so a re-export of an unchanged space is still
+* byte-identical (§6.6).
+*/
+const renderDocAssets = (assets, files) => {
+	const byId = /* @__PURE__ */ new Map();
+	for (const asset of assets) if (!byId.has(asset.assetId)) byId.set(asset.assetId, asset);
+	for (const asset of [...byId.values()].sort((a, b) => a.assetId.localeCompare(b.assetId, "en"))) {
+		const bytesPath = docAssetBytesPath(asset);
+		assertSafeFilePath(bytesPath, `doc asset "${asset.assetId}"`);
+		files.set(bytesPath, asset.bytes);
+		files.set(`${bytesPath}${PACKAGE_ASSET_META_SUFFIX}`, toJsonFile(compact({
+			assetId: asset.assetId,
+			fileName: asset.fileName,
+			mimeType: asset.mimeType,
+			contentHash: asset.contentHash
+		})));
+	}
 };
-const countTree = (tree) => {
-	const counts = {
-		folders: 0,
-		docs: 0,
-		bases: 0,
-		records: 0,
-		skills: 0,
-		airapps: 0,
-		drives: 0,
-		files: 0
-	};
-	for (const node of walkNodes(tree.nodes)) switch (node.type) {
+const renderNodes = (nodes, dir, files) => {
+	const ordered = sortNodes(nodes);
+	assertNoSiblingCaseCollisions(ordered.map((node) => node.slug), `in ${dir}`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const node of ordered) {
+		assertSafeNodeSlug(node.slug, `${node.type} node`);
+		if (seen.has(node.slug)) throw new Error(`Two nodes in ${dir} would be written as "${node.slug}". Sibling slugs must be unique.`);
+		seen.add(node.slug);
+		renderNode(node, dir, files);
+	}
+};
+const renderNode = (node, dir, files) => {
+	switch (node.type) {
 		case "folder":
-			counts.folders++;
-			break;
+			if (node.children.length === 0 || node.description !== "" || node.position !== void 0 || node.name !== void 0) files.set(`${dir}${node.slug}/${PACKAGE_FOLDER_META_FILENAME}`, toJsonFile(compact({
+				name: node.name,
+				description: node.description || void 0,
+				position: node.position
+			})));
+			renderNodes(node.children, `${dir}${node.slug}/`, files);
+			return;
 		case "doc":
-			counts.docs++;
-			break;
-		case "base":
-			counts.bases++;
-			counts.records += node.records.length;
-			break;
+			files.set(`${dir}${node.slug}.md`, Buffer.from(serializeDoc({
+				name: node.name,
+				description: node.description,
+				position: node.position
+			}, node.body), "utf8"));
+			return;
+		case "base": {
+			files.set(`${dir}${node.slug}/${PACKAGE_BASE_FILENAME}`, serializeBase(node.base, node.position));
+			const records = serializeRecords(node.records);
+			if (records.byteLength > 0) files.set(`${dir}${node.slug}/${PACKAGE_RECORDS_FILENAME}`, records);
+			return;
+		}
 		case "skill":
-			counts.skills++;
-			counts.files += node.files.length;
-			break;
 		case "airapp":
-			counts.airapps++;
-			counts.files += node.files.length;
-			break;
-		case "drive":
-			counts.drives++;
-			counts.files += node.files.length;
-			break;
-		case "file": counts.files++;
-	}
-	counts.files += (tree.assets ?? []).length;
-	return counts;
-};
-/** §4: "What will this do?" — the `--dry-run` report. Creates nothing. */
-const renderPlan = (plan) => {
-	const lines = [];
-	lines.push(`Package: ${plan.tree.manifest.name}`);
-	if (plan.tree.manifest.description) lines.push(`  ${plan.tree.manifest.description}`);
-	lines.push("");
-	lines.push(`Target folder: ${plan.targetFolderSlug}`);
-	lines.push("");
-	lines.push("Node tree:");
-	for (const line of renderNodeTree(plan.tree.nodes, "  ")) lines.push(line);
-	lines.push("");
-	lines.push(`Totals: ${plan.counts.folders} folder(s), ${plan.counts.docs} doc(s), ${plan.counts.bases} base(s) with ${plan.counts.records} record(s), ${plan.counts.skills} skill(s), ${plan.counts.airapps} airapp(s), ${plan.counts.drives} drive(s), ${plan.counts.files} file(s)`);
-	if (plan.collisions.length > 0) {
-		lines.push("");
-		lines.push("Collisions:");
-		for (const collision of plan.collisions) lines.push(collision.renamedTo ? `  • ${collision.kind} "${collision.slug}" already exists → will be created as "${collision.renamedTo}"` : `  • ${collision.kind} "${collision.slug}" already exists (${collision.path})`);
-	}
-	if (plan.warnings.length > 0) {
-		lines.push("");
-		lines.push("Warnings:");
-		for (const warning of plan.warnings) lines.push(`  • ${warning}`);
+		case "drive": {
+			const nodeDir = `${dir}${node.slug}/`;
+			assertNoReservedNames(node.files.map((entry) => entry.path), `${node.type} "${node.slug}"`);
+			files.set(`${nodeDir}${PACKAGE_NODE_META_FILENAME}`, toJsonFile(compact({
+				type: node.type,
+				name: node.name,
+				description: node.description || void 0,
+				position: node.position
+			})));
+			for (const entry of [...node.files].sort((a, b) => a.path.localeCompare(b.path, "en"))) {
+				assertSafeFilePath(entry.path, `${node.type} "${node.slug}"`);
+				files.set(`${nodeDir}${entry.path}`, entry.bytes);
+			}
+			return;
+		}
+		case "file":
+			assertSafeFilePath(node.fileName, `file node "${node.slug}"`);
+			files.set(`${dir}${node.fileName}`, node.bytes);
+			if (node.name !== node.fileName || node.description !== "" || node.position !== void 0) files.set(`${dir}${node.fileName}${PACKAGE_NODE_META_SUFFIX}`, toJsonFile(compact({
+				name: node.name,
+				description: node.description || void 0,
+				position: node.position
+			})));
+			return;
 	}
-	return lines.join("\n");
 };
-const renderNodeTree = (nodes, indent) => {
-	const lines = [];
-	for (const node of nodes) {
-		const detail = node.type === "base" ? ` (base, ${node.base.fields.length} field(s), ${node.records.length} record(s))` : node.type === "folder" ? " (folder)" : node.type === "doc" ? " (doc)" : node.type === "file" ? " (file)" : ` (${node.type}, ${node.files.length} file(s))`;
-		lines.push(`${indent}${node.slug}${detail}`);
-		if (node.type === "folder") lines.push(...renderNodeTree(node.children, `${indent}  `));
+/** Write rendered files under `outDir`, creating directories as needed. */
+const writePackageFiles = async (files, outDir, options = {}) => {
+	if (options.clean) {
+		await rm(join(outDir, PACKAGE_CONTENT_DIRNAME), {
+			recursive: true,
+			force: true
+		});
+		await rm(join(outDir, PACKAGE_ASSETS_DIRNAME), {
+			recursive: true,
+			force: true
+		});
+		await rm(join(outDir, PACKAGE_MANIFEST_FILENAME), { force: true });
+		await rm(join(outDir, PACKAGE_SKILL_ENTRY), { force: true });
+		for (const dirName of PACKAGE_SKILL_SIDECAR_DIRS) await rm(join(outDir, dirName), {
+			recursive: true,
+			force: true
+		});
 	}
-	return lines;
-};
-/**
-* §4 + §12: without `--auto-merge` an unmerged base has no field ids to patch and no
-* records to link, so passes 2-5 cannot run. Fail fast and say exactly why.
-*/
-const assertPlanIsApplicable = (plan, autoMerge) => {
-	if (plan.collisions.some((collision) => !collision.renamedTo)) {
-		const list = plan.collisions.filter((collision) => !collision.renamedTo).map((collision) => `  • ${collision.kind} "${collision.slug}" (${collision.path})`).join("\n");
-		throw new Error(`Install would collide with content that already exists:\n${list}\n\nNothing was created. Re-run with --rename to install the colliding items under suffixed slugs (e.g. "-2"), or pick a different --into-folder.`);
+	for (const [filePath, bytes] of [...files].sort(([a], [b]) => a.localeCompare(b, "en"))) {
+		const target = join(outDir, filePath);
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, bytes);
 	}
-	if (plan.requiresAutoMerge && !autoMerge) throw new Error("This package's records carry relation values, and a relation stores the ids of the records it points at — which only exist once the records are merged. Installing review-first would leave every relation empty.\n\nRe-run with --auto-merge to install it (this trusts the package author: records are created immediately instead of landing as change requests you review first).");
 };
 //#endregion
 //#region src/package/commands.ts
@@ -7257,11 +8235,26 @@ const runInstall = async (client, repoUrl, options) => {
 	reportProgress(`Fetching ${repoUrl} …`);
 	const { source, files } = await fetchGithubPackageFiles(repoUrl, { githubToken: options.githubToken });
 	reportProgress(`Downloaded ${files.size} file(s) from ${source.owner}/${source.repo}.`);
-	const tree = readPackageTree(files);
+	const resolved = resolvePackageToInstall(files, options.skill);
+	if (resolved.kind === "none") {
+		readPackageTree(files);
+		throw new Error("Not a Busabase package.");
+	}
+	if (resolved.kind === "choose") {
+		const report = renderPackageChoices(repoUrl, resolved.candidates, options.skill);
+		if (options.json) return {
+			chooseOne: true,
+			candidates: resolved.candidates.map(toCandidateSummary)
+		};
+		return report;
+	}
+	const tree = readPackageTree(files, resolved.subdir ? { root: resolved.subdir } : {});
+	if (resolved.subdir) reportProgress(`Installing "${resolved.discovered.name}" from ${resolved.subdir}/ …`);
 	const targetFolderSlug = options.intoFolder ?? suggestSlug(tree.manifest.name);
 	const plan = buildInstallPlan(tree, await resolveTargetState(client, targetFolderSlug), {
 		intoFolder: options.intoFolder,
-		rename: options.rename
+		rename: options.rename,
+		installSampleRecords: !options.noSampleRecords
 	});
 	if (options.dryRun) {
 		const report = `${renderPlan(plan)}\n\nDry run — nothing was created.`;
@@ -7275,7 +8268,13 @@ const runInstall = async (client, repoUrl, options) => {
 		autoMerge: Boolean(options.autoMerge),
 		submittedBy: `busabase-cli install (${tree.manifest.name})`,
 		onProgress: reportProgress,
-		serverUrl: options.serverUrl
+		serverUrl: options.serverUrl,
+		installSampleRecords: !options.noSampleRecords,
+		source: {
+			repo: `${source.owner}/${source.repo}`,
+			ref: source.ref,
+			...resolved.subdir ? { subdir: resolved.subdir } : source.subdir ? { subdir: source.subdir } : {}
+		}
 	});
 	if (options.json) return {
 		installed: true,
@@ -7283,6 +8282,45 @@ const runInstall = async (client, repoUrl, options) => {
 	};
 	return renderInstallReport(plan.targetFolderSlug, result);
 };
+const toCandidateSummary = (candidate) => ({
+	name: candidate.name,
+	subdir: candidate.subdir,
+	description: candidate.description,
+	isTemplate: candidate.isTemplate,
+	counts: candidate.counts
+});
+/**
+* The list a user sees when their URL pointed at a repository of packages.
+*
+* Templates are listed first and labelled, because that is the difference the
+* user actually cares about: one installs an app, the other installs tables. A
+* package that TRIED to be a template and failed says so with its reasons —
+* that reader is usually its author.
+*/
+const renderPackageChoices = (repoUrl, candidates, wanted) => {
+	const lines = [];
+	if (wanted) lines.push(`No package named "${wanted}" in ${repoUrl}. It contains:`);
+	else lines.push(`${repoUrl} contains ${candidates.length} packages. Pick one:`);
+	lines.push("");
+	const ordered = [...candidates].sort((a, b) => {
+		if (a.isTemplate !== b.isTemplate) return a.isTemplate ? -1 : 1;
+		return a.name.localeCompare(b.name, "en");
+	});
+	for (const candidate of ordered) {
+		const shape = [
+			candidate.isTemplate ? "template" : "package",
+			candidate.counts.bases > 0 ? `${candidate.counts.bases} base(s)` : void 0,
+			candidate.primaryAirApp ? "app" : void 0
+		].filter(Boolean).join(" · ");
+		lines.push(`  ${candidate.name}  (${shape})`);
+		if (candidate.description) lines.push(`    ${candidate.description}`);
+		for (const error of candidate.templateErrors) lines.push(`    not a template: ${error}`);
+	}
+	lines.push("");
+	lines.push("Install one with:");
+	lines.push(`  busabase-cli install ${repoUrl} --skill ${ordered[0]?.name ?? "<name>"}`);
+	return lines.join("\n");
+};
 const toPlanSummary = (plan) => ({
 	targetFolder: plan.targetFolderSlug,
 	package: plan.tree.manifest.name,
@@ -7320,6 +8358,27 @@ const runExport = async (client, nodeSlugOrId, options) => {
 		warn: (message) => warnings.push(message),
 		baseUrl: options.baseUrl
 	});
+	if (options.template) {
+		if (!tree.rootSkill) {
+			warnings.push(`No Skill node in "${source.slug}", so a ${PACKAGE_SKILL_ENTRY} draft was written from the folder's structure. Fill in its TODOs before publishing — an agent acts on what it says.`);
+			tree.rootSkill = {
+				slug: manifest.name,
+				name: manifest.name,
+				description: manifest.description,
+				files: [{
+					path: PACKAGE_SKILL_ENTRY,
+					bytes: Buffer.from(deriveSkillDraft(tree), "utf8")
+				}]
+			};
+		}
+		if (!tree.manifest.template) tree.manifest = {
+			...tree.manifest,
+			template: TemplateManifestSchema.parse({ category: "uncategorized" })
+		};
+		const validation = validateTemplate(tree);
+		for (const warning of validation.warnings) warnings.push(warning);
+		for (const error of validation.errors) warnings.push(`Not yet a valid template: ${error}`);
+	}
 	const files = renderPackageTree(tree);
 	if (!options.dryRun) await writePackageFiles(files, options.outDir, { clean: true });
 	if (options.json) return {
@@ -7327,6 +8386,7 @@ const runExport = async (client, nodeSlugOrId, options) => {
 		package: manifest.name,
 		outDir: options.outDir,
 		files: [...files.keys()].sort(),
+		...options.template ? { isTemplate: validateTemplate(tree).ok } : {},
 		warnings
 	};
 	return renderExportReport(options, manifest, files, warnings);
@@ -7378,6 +8438,62 @@ const renderExportReport = (options, manifest, files, warnings) => {
 	}
 	return lines.join("\n");
 };
+/**
+* Build the Template Center's catalog from a checkout.
+*
+* Lives here rather than in the skills repository so the catalog and the
+* installer share one answer to "is this a template". A repository that decided
+* for itself could list a card whose install then behaves differently — which
+* is a trust problem, not a formatting one.
+*/
+const runIndex = async (options) => {
+	const files = await readDirectoryFiles(options.dir);
+	const index = buildTemplateIndex(files, {
+		repo: options.repo,
+		ref: options.ref
+	});
+	const rendered = renderTemplateIndex(index);
+	if (options.check) {
+		if (!options.out) throw new Error("--check needs --out: there is nothing to compare against.");
+		if (await readFile(options.out, "utf8").catch(() => null) !== rendered) throw new Error(`${options.out} is out of date. Run the same command without --check to rebuild it.`);
+		return options.json ? {
+			upToDate: true,
+			templates: index.templates.length
+		} : `${options.out} is up to date (${index.templates.length} template(s)).`;
+	}
+	if (options.out) {
+		await mkdir(dirname(options.out), { recursive: true });
+		await writeFile(options.out, rendered);
+	}
+	if (options.json) return index;
+	if (!options.out) return rendered.trimEnd();
+	const lines = [`Wrote ${options.out}: ${index.templates.length} template(s).`];
+	for (const entry of index.templates) lines.push(`  ${entry.name}  (${entry.category} · ${entry.stats.bases} base(s))`);
+	if (index.rejected.length > 0) {
+		lines.push("", "Declared a template but did not qualify:");
+		for (const entry of index.rejected) {
+			lines.push(`  ${entry.name}`);
+			for (const error of entry.errors) lines.push(`    ${error}`);
+		}
+	}
+	return lines.join("\n");
+};
+/** Every file under `dir`, keyed by its POSIX path relative to it. */
+const readDirectoryFiles = async (dir) => {
+	const files = /* @__PURE__ */ new Map();
+	const walk = async (current) => {
+		for (const entry of await readdir(current, { withFileTypes: true })) {
+			if (entry.name === "node_modules" || entry.name === ".git") continue;
+			const absolute = join(current, entry.name);
+			const info = await stat(absolute).catch(() => null);
+			if (!info) continue;
+			if (info.isDirectory()) await walk(absolute);
+			else if (info.isFile()) files.set(relative(dir, absolute).split(sep).join("/"), await readFile(absolute));
+		}
+	};
+	await walk(dir);
+	return files;
+};
 //#endregion
 //#region src/task-command.ts
 const collect = (value, previous = []) => [...previous, value];
@@ -7782,6 +8898,23 @@ function runArgAction(state, handler) {
 		console.log(render(result, config.output));
 	};
 }
+/**
+* A command that touches only the local filesystem.
+*
+* `runArgAction` resolves credentials and builds a client before it calls the
+* handler, which is right for everything that talks to a workspace — and wrong
+* for `index`, whose whole job is to read a checkout. A CI runner building the
+* catalog has no Busabase server and no key, and demanding one would make the
+* catalog impossible to build in exactly the place it is meant to be built.
+*/
+function runLocalArgAction(handler) {
+	return async (arg, _opts, cmd) => {
+		const opts = cmd.optsWithGlobals();
+		const config = resolveConfig(opts);
+		const result = await handler(arg, opts, config);
+		console.log(render(result, config.output));
+	};
+}
 function pkgVersion() {
 	try {
 		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -8311,7 +9444,7 @@ Examples:
 		startLine: opts.startLine,
 		endLine: opts.endLine
 	})));
-	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo into this space").argument("<github-url>", "GitHub repo URL, optionally /tree/<ref>[/<subdir>]").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot instead of leaving them as change requests to review — this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").addHelpText("after", `
+	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo into this space").argument("<github-url>", "GitHub repo URL, optionally /tree/<ref>[/<subdir>]").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot instead of leaving them as change requests to review — this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").option("--skill <name>", "which package to install when the URL is a repository holding several (e.g. busabase/skills)").option("--no-sample-records", "propose a template's sample rows for review instead of merging them (default: merged, so the app is not empty on first open)").addHelpText("after", `
 The URL's git ref is the version pin — a tag installs that tag's content forever,
 even after the branch moves on. GITHUB_TOKEN is honored for private repos.
 
@@ -8325,6 +9458,16 @@ Folders, Bases, their fields and their views are structure and are always create
 immediately. Records are content: by default they land as change requests for you
 to review, and --auto-merge merges them on the spot instead.
 
+A TEMPLATE (a package that also carries a SKILL.md) installs as an app: its
+manual lands as a Skill node, its nodes are stamped as belonging to that app, its
+Base slugs are prefixed with the target folder so two templates cannot collide on
+a name like "settings", and its sample rows are merged so the app is not empty
+when you open it (--no-sample-records opts out). Its AirApp code and its Skill
+still wait for your review.
+
+If the URL is a repository that holds several packages rather than being one,
+install lists them and you pick with --skill <name>.
+
 A package whose records carry relation values requires --auto-merge — a relation
 stores the ids of the records it points at, and those exist only once the records
 are merged, so review-first would install every relation empty. Defining a relation
@@ -8333,20 +9476,46 @@ field with nothing linked yet does not trigger this.`).action(runArgAction(state
 		dryRun: Boolean(opts.dryRun),
 		autoMerge: Boolean(opts.autoMerge),
 		rename: Boolean(opts.rename),
+		skill: opts.skill,
+		noSampleRecords: opts.sampleRecords === false,
 		json: config.output === "json",
 		githubToken: process.env.GITHUB_TOKEN,
 		serverUrl: config.baseUrl
 	})));
-	addGlobalFlags(program.command("export")).description("Export a node subtree as a Busabase package directory you can push to GitHub").argument("<node-slug-or-id>", "the folder/node to export").requiredOption("-o, --out-dir <dir>", "output directory for the package").option("--name <name>", "package name (default: reuse busabase.json, else the node slug)").option("--dry-run", "list the files that would be written and write nothing").addHelpText("after", `
+	addGlobalFlags(program.command("index")).description("Build the Template Center catalog from a directory of skills").argument("<dir>", "directory to scan (a checkout of the skills repository)").requiredOption("--repo <owner/repo>", "repository the entries' subdirs are relative to").option("--ref <ref>", "git ref the entries are read at", "main").option("-o, --out <file>", "write the catalog here (default: print it)").option("--check", "exit non-zero if the file on disk is not what would be written").addHelpText("after", `
+Whether a skill is listed is decided by the same rules that decide how it
+installs, so a card can never promise something its install does not do. A skill
+that declared itself a template and did not qualify is reported with the reason
+rather than silently left out.
+
+Examples:
+  busabase-cli index . --repo busabase/skills -o templates.json
+  busabase-cli index . --repo busabase/skills -o templates.json --check`).action(runLocalArgAction((dir, opts, config) => runIndex({
+		dir,
+		repo: opts.repo,
+		ref: opts.ref || "main",
+		out: opts.out,
+		check: Boolean(opts.check),
+		json: config.output === "json"
+	})));
+	addGlobalFlags(program.command("export")).description("Export a node subtree as a Busabase package directory you can push to GitHub").argument("<node-slug-or-id>", "the folder/node to export").requiredOption("-o, --out-dir <dir>", "output directory for the package").option("--name <name>", "package name (default: reuse busabase.json, else the node slug)").option("--dry-run", "list the files that would be written and write nothing").option("--template", "export as a template (an installable app): check it against the template rules and write a SKILL.md draft if the folder has no Skill node yet").addHelpText("after", `
 Output is deterministic: exporting twice from an unchanged space produces
 byte-identical files, so a GitHub diff shows exactly what changed.
 
 Examples:
   busabase-cli export support-kb -o ./support-kb-template
-  busabase-cli export support-kb -o ./support-kb-template --name "Support KB" --dry-run`).action(runArgAction(state, (nodeSlugOrId, client, opts, config) => runExport(client, nodeSlugOrId, {
+  busabase-cli export support-kb -o ./support-kb-template --name "Support KB" --dry-run
+  busabase-cli export kelly-email -o ./kelly-email --template
+
+--template makes the result installable as an APP rather than as a pile of
+tables: the folder's Skill node is lifted to the package root as SKILL.md (or a
+draft is written from the folder's structure for you to fill in), and anything
+still missing is reported. The same directory then works both as an Agent Skill
+and as something \`busabase-cli install\` can install.`).action(runArgAction(state, (nodeSlugOrId, client, opts, config) => runExport(client, nodeSlugOrId, {
 		outDir: opts.outDir,
 		name: opts.name,
 		dryRun: Boolean(opts.dryRun),
+		template: Boolean(opts.template),
 		json: config.output === "json",
 		baseUrl: config.baseUrl
 	})));