busa-cli 0.18.0 → 0.19.1

package/dist/{run-DD52HeGA.js → run--bA-jLSP.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
@@ -56,7 +56,7 @@ const OPERATIONS$1 = [
 * audience, the exact silent-drop failure the server-side rejection exists to
 * end. `params.appliesWhen` still documents which operations accept it.
 */
-const mergeIntent$4 = (input) => {
+const mergeIntent$5 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -246,7 +246,7 @@ const baseFieldChangeTask = {
 			baseId: input.baseId,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$4(input)
+			...mergeIntent$5(input)
 		};
 		switch (input.operation) {
 			case "add": return client.bases.fieldChangeRequest({
@@ -629,7 +629,7 @@ const nodeReadFileTask = {
 * A batch containing a `delete` is review-first server-side no matter what this
 * sends, so don't imply otherwise in the flag's description.
 */
-const mergeIntent$3 = (input) => {
+const mergeIntent$4 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -699,7 +699,7 @@ const nodeFilesChangeRequestTask = {
 			operations: input.operations,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$3(input)
+			...mergeIntent$4(input)
 		};
 		return client.fileTrees.createChangeRequest(payload);
 	}
@@ -1424,7 +1424,7 @@ const rejectMismatchedPayload = (input) => {
 	if (wrong.length > 0) throw new Error(`${wrong.join(", ")} ${wrong.length > 1 ? "are" : "is"} not valid for --type ${type}.`);
 };
 /** `autoMerge` is tri-state: unset (permission-aware default), forced on, forced off. */
-const mergeIntent$2 = (input) => {
+const mergeIntent$3 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -1637,7 +1637,7 @@ const nodeCreateTask = {
 			name: input.name,
 			description: input.description,
 			parentNodeId: input.parentNodeId,
-			...mergeIntent$2(input)
+			...mergeIntent$3(input)
 		};
 		if (FILE_TREE_TYPES.has(type)) {
 			const payload = {
@@ -1675,7 +1675,7 @@ const nodeCreateTask = {
 		return client.nodes.createChangeRequest({
 			message: input.message ?? `Create ${type} ${input.name}`,
 			submittedBy: input.submittedBy,
-			...mergeIntent$2(input),
+			...mergeIntent$3(input),
 			operations: [{
 				kind: "create",
 				nodeType: type,
@@ -1688,6 +1688,74 @@ const nodeCreateTask = {
 	}
 };
 //#endregion
+//#region ../../packages/busabase-contract/src/tasks/record-bulk-update.ts
+const mergeIntent$2 = (input) => {
+	if (input.requireReview) return { autoMerge: false };
+	if (input.autoMerge) return { autoMerge: true };
+	return {};
+};
+const recordBulkUpdateTask = {
+	name: "record_bulk_update_change_request",
+	cliPath: ["records", "bulk-update-change-request"],
+	summary: "Propose partial updates to many records in one ChangeRequest",
+	guidance: "All updates must target active records in the same Base. Each recordId may appear once. Each fields object is a partial update: omitted keys stay unchanged and null clears a field. The batch is reviewed and merged atomically. Use baseCommitId per update when the caller must pin the version it read. Review is permission-aware; pass requireReview to force a pending ChangeRequest even when the key has write access.",
+	annotations: {
+		readOnly: false,
+		destructive: false
+	},
+	params: [
+		{
+			name: "baseId",
+			kind: "string",
+			required: true,
+			description: "Base owning every record."
+		},
+		{
+			name: "updates",
+			kind: "json",
+			required: true,
+			description: "JSON array of {recordId, fields, baseCommitId?, message?}, e.g. [{\"recordId\":\"rec_1\",\"fields\":{\"status\":\"published\"}}]."
+		},
+		{
+			name: "message",
+			kind: "string",
+			description: "Reviewer-facing message for the batch."
+		},
+		{
+			name: "submittedBy",
+			kind: "string",
+			description: "Producer label recorded on the change."
+		},
+		{
+			name: "idempotencyKey",
+			kind: "string",
+			description: "Retry key scoped to this Base and submitter."
+		},
+		{
+			name: "autoMerge",
+			kind: "boolean",
+			description: "Apply immediately when the actor has write access."
+		},
+		{
+			name: "requireReview",
+			kind: "boolean",
+			description: "Force one pending ChangeRequest even when the actor has write access."
+		}
+	],
+	examples: ["busabase-cli records bulk-update-change-request --base-id bas_1 --updates-json '[{\"recordId\":\"rec_1\",\"fields\":{\"status\":\"published\"}}]' --require-review", "busabase-cli records bulk-update-change-request --base-id bas_1 --updates-json @updates.json --idempotency-key august-review-v1"],
+	execute: async (client, input) => {
+		if (!Array.isArray(input.updates)) throw new Error("`updates` must be a JSON array.");
+		return client.bases.createBulkUpdateChangeRequest({
+			baseId: input.baseId,
+			updates: input.updates,
+			...input.message ? { message: input.message } : {},
+			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
+			...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+			...mergeIntent$2(input)
+		});
+	}
+};
+//#endregion
 //#region ../../packages/busabase-contract/src/tasks/record-change.ts
 /**
 * Changing an existing record: update, delete (archive), or restore — one task
@@ -1905,7 +1973,7 @@ const recordQueryTask = {
 	examples: [
 		"busabase-cli records query --base-id bas_123 --limit 100",
 		"busabase-cli records count --base-id bas_123",
-		"busabase-cli records count --base-id bas_123 --filters '[{\"fieldSlug\":\"branch\",\"fieldType\":\"text\",\"operator\":\"equals\",\"value\":\"main\"}]'",
+		"busabase-cli records count --base-id bas_123 --filters-json '[{\"fieldSlug\":\"branch\",\"fieldType\":\"text\",\"operator\":\"equals\",\"value\":\"main\"}]'",
 		"busabase-cli records count --base-id bas_123 --view-id viw_456"
 	],
 	execute: async (client, input) => {
@@ -2120,11 +2188,60 @@ const BUSABASE_TASKS = [
 	changeRequestMergeTask,
 	baseFieldChangeTask,
 	recordChangeTask,
+	recordBulkUpdateTask,
 	viewChangeTask,
 	nodePermissionTask,
 	nodeShareTask,
 	listArchivedTask
 ];
+/**
+* Endpoint-level MCP tools fully covered by a task above, keyed by the tool name
+* the OpenAPI generator produces. The MCP adapter excludes these so a catalog
+* carries one way to do each job rather than two.
+*
+* Kept as tool names (not contract paths) because that is what the MCP layer
+* filters on, and it is the name an agent would actually have seen.
+*
+* NOT listed on purpose:
+*   - `nodes_create_change_request` — `node_create` covers only a single `create`
+*     operation. The endpoint also does `rename`, and composes several operations
+*     into one change request (`ref`/`parentNodeRef` builds a whole subtree
+*     atomically). Excluding it would be a capability regression, not a cleanup.
+*   - `forms_create` — configures an existing node, so it is a second step after
+*     `node_create --type form`, not a duplicate of it.
+*   - `nodes_purge` — permanent delete is a genuinely different operation from
+*     `node_archive`, and `node_archive`'s guidance now tells an agent when each
+*     one applies.
+*/
+const TASK_SUPERSEDED_MCP_TOOLS = [
+	"file_trees_create",
+	"docs_create",
+	"bases_create",
+	"files_create",
+	"records_search",
+	"file_trees_list_files",
+	"file_trees_read_file",
+	"file_trees_create_change_request",
+	"records_list",
+	"records_count",
+	"change_requests_list",
+	"change_requests_counts",
+	"change_requests_review",
+	"change_requests_review_many",
+	"change_requests_merge",
+	"change_requests_merge_many",
+	"bases_field_change_request",
+	"records_change_request",
+	"bases_create_bulk_update_change_request",
+	"views_change_request",
+	"nodes_principals_list",
+	"nodes_principals_add",
+	"nodes_principals_remove",
+	"nodes_share_get",
+	"nodes_share_set",
+	"nodes_share_disable",
+	"bases_list_deleted_fields"
+];
 //#endregion
 //#region src/config-file.ts
 /**
@@ -3269,15 +3386,168 @@ function banner(baseUrl) {
 	return out.join("\n");
 }
 //#endregion
+//#region src/errors.ts
+/**
+* Process exit code per class.
+*
+* `1` stays the code for an unclassified error, so a script testing `!= 0` is
+* unaffected and only a script testing `== 1` sees a change.
+*/
+const EXIT_CODES = {
+	ERROR: 1,
+	USAGE: 2,
+	UNAUTHORIZED: 3,
+	FORBIDDEN: 3,
+	NOT_FOUND: 4,
+	VALIDATION: 5,
+	CONFLICT: 6,
+	RATE_LIMITED: 7,
+	SERVER_ERROR: 8,
+	NETWORK: 9,
+	REVIEW_REJECTED: 10,
+	TIMEOUT: 11
+};
+const RETRYABLE = /* @__PURE__ */ new Set([
+	"RATE_LIMITED",
+	"SERVER_ERROR",
+	"NETWORK"
+]);
+/** `data.issues` as the server sends it, flattened. Shared with `explainError`'s prose rendering. */
+function toIssues(raw) {
+	if (!Array.isArray(raw) || raw.length === 0) return void 0;
+	const issues = raw.map((issue) => {
+		if (!issue || typeof issue !== "object") return {
+			path: "",
+			message: String(issue)
+		};
+		const { path, message } = issue;
+		return {
+			path: Array.isArray(path) ? path.join(".") : typeof path === "string" ? path : "",
+			message: String(message ?? issue)
+		};
+	});
+	return issues.length > 0 ? issues : void 0;
+}
+const codeForStatus = (status) => {
+	if (status === 401) return "UNAUTHORIZED";
+	if (status === 403) return "FORBIDDEN";
+	if (status === 404) return "NOT_FOUND";
+	if (status === 409) return "CONFLICT";
+	if (status === 429) return "RATE_LIMITED";
+	if (status === 400 || status === 422) return "VALIDATION";
+	if (status >= 500) return "SERVER_ERROR";
+	return "ERROR";
+};
+/**
+* A transport failure never reaches the server, so it has no status to read.
+* Node reports every one of them as a bare `TypeError: fetch failed` with the
+* real reason on `.cause`, which is why this matches on text rather than type.
+*/
+const isNetworkFailure = (message) => /fetch failed|econnrefused|enotfound|getaddrinfo|econnreset|etimedout|socket hang up|network/i.test(message);
+/**
+* `rawFetch` (health / openapi / `api` passthrough) throws a plain `Error`
+* carrying `HTTP <status> <statusText>: …` rather than an `ORPCError`, so the
+* status has to be read back out of the message for those paths.
+*/
+const statusFromMessage = (message) => {
+	const match = /\bHTTP (\d{3})\b/.exec(message);
+	return match ? Number(match[1]) : void 0;
+};
+/** Classify any thrown value into the stable shape above. Never throws. */
+function classifyError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	const outcome = error?.cliCode;
+	if (typeof outcome === "string" && outcome in EXIT_CODES) {
+		const code = outcome;
+		return {
+			code,
+			message,
+			retryable: RETRYABLE.has(code),
+			exitCode: EXIT_CODES[code]
+		};
+	}
+	const issues = toIssues(error?.data?.issues);
+	const status = typeof error?.status === "number" ? error.status : statusFromMessage(message);
+	let code;
+	if (status !== void 0) code = codeForStatus(status);
+	else if (isNetworkFailure(message)) code = "NETWORK";
+	else code = "ERROR";
+	const orpcCode = error?.code;
+	if (code === "ERROR" && typeof orpcCode === "string") {
+		if (orpcCode === "NOT_FOUND") code = "NOT_FOUND";
+		else if (orpcCode === "UNAUTHORIZED") code = "UNAUTHORIZED";
+		else if (orpcCode === "FORBIDDEN") code = "FORBIDDEN";
+		else if (orpcCode === "CONFLICT") code = "CONFLICT";
+		else if (orpcCode === "BAD_REQUEST" || orpcCode === "UNPROCESSABLE_CONTENT") code = "VALIDATION";
+		else if (orpcCode === "TOO_MANY_REQUESTS") code = "RATE_LIMITED";
+	}
+	return {
+		code,
+		...status !== void 0 ? { status } : {},
+		message,
+		...issues ? { issues } : {},
+		retryable: RETRYABLE.has(code),
+		exitCode: EXIT_CODES[code]
+	};
+}
+/** The stdout envelope for a failed command under `--output json`. */
+function errorEnvelope(classified) {
+	return {
+		ok: false,
+		code: classified.code,
+		...classified.status !== void 0 ? { status: classified.status } : {},
+		message: classified.message,
+		...classified.issues ? { issues: classified.issues } : {},
+		retryable: classified.retryable
+	};
+}
+/**
+* A command that ran fine but ended in an outcome the caller must branch on —
+* a proposal a reviewer turned down, or a `--wait` that ran out of budget.
+*
+* Carries its own class so {@link classifyError} does not have to guess from a
+* message, and so the envelope reports it exactly like any other failure.
+*/
+var CliOutcomeError = class extends Error {
+	cliCode;
+	constructor(cliCode, message) {
+		super(message);
+		this.name = "CliOutcomeError";
+		this.cliCode = cliCode;
+	}
+};
+//#endregion
 //#region src/format.ts
 /** Render a command result as JSON, a compact text view, or an aligned table. */
 function render(value, output) {
 	if (output === "json") return JSON.stringify(value, null, 2);
 	if (output === "text") return renderText(value);
 	if (Array.isArray(value)) return renderTable(value);
+	const envelope = asEnvelope(value);
+	if (envelope) return renderEnvelope(envelope, renderTable);
 	if (value && typeof value === "object") return renderRecord(value);
 	return String(value);
 }
+function asEnvelope(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const entries = Object.entries(value);
+	const arrays = entries.filter((entry) => Array.isArray(entry[1]));
+	if (arrays.length !== 1) return void 0;
+	const meta = entries.filter(([, item]) => !Array.isArray(item));
+	if (!meta.every(([, item]) => item === null || item === void 0 || typeof item !== "object")) return void 0;
+	return {
+		key: arrays[0][0],
+		rows: arrays[0][1],
+		meta
+	};
+}
+function renderEnvelope(envelope, renderRows) {
+	const body = envelope.rows.length === 0 ? `(no ${envelope.key})` : renderRows(envelope.rows);
+	const meta = envelope.meta.filter(([, item]) => item !== null && item !== void 0);
+	if (meta.length === 0) return body;
+	const width = Math.max(...meta.map(([key]) => key.length));
+	return `${body}\n\n${meta.map(([key, item]) => `${key.padEnd(width)}  ${cell(item)}`).join("\n")}`;
+}
 function cell(value) {
 	if (value === null || value === void 0) return "";
 	if (typeof value === "object") return compactJson(value);
@@ -3320,6 +3590,8 @@ function renderTable(rows) {
 	].join("\n");
 }
 function renderText(value) {
+	const envelope = asEnvelope(value);
+	if (envelope) return renderEnvelope(envelope, renderText);
 	if (Array.isArray(value)) {
 		if (value.length === 0) return "(no rows)";
 		if (isNodeTree(value)) return renderNodeTree$1(value);
@@ -3369,6 +3641,48 @@ function nodeIcon(type) {
 		default: return "[node]";
 	}
 }
+/**
+* Drop hydrated parents from a result, keeping the id that points at them.
+*
+* A record VO is ~4.5 KB, of which 3.6 KB is a full copy of its parent `base`
+* — repeated identically on every row, so ten records cost 151 KB and nine
+* copies of that Base are pure waste to any caller that already knows which
+* Base it asked about. `createdByUser` and `headCommit` are the same pattern.
+*
+* The test for "this is a hydration, not content" is deliberately structural
+* rather than a list of field names, so it does not rot as VOs change: an
+* object-valued key is dropped only when a sibling STRING key already
+* identifies the same thing — `base`/`baseId`, `headCommit`/`headCommitId`,
+* `createdByUser`/`createdBy`. Nothing that lacks such a sibling is touched,
+* which is why a Base's `fields`, a node's `children`, and `whoami`'s `space`
+* all survive: dropping those would remove the answer, not a duplicate.
+*/
+function slim(value) {
+	if (Array.isArray(value)) return value.map(slim);
+	if (!value || typeof value !== "object") return value;
+	const row = value;
+	const scalarKeys = Object.entries(row).filter(([, item]) => typeof item === "string").map(([key]) => key);
+	const out = {};
+	for (const [key, item] of Object.entries(row)) {
+		if (isHydrated(key, item, scalarKeys)) continue;
+		out[key] = slim(item);
+	}
+	return out;
+}
+/**
+* `carriesPayload` is the guard that stops this from eating the answer. A
+* record's `headCommit` is structurally indistinguishable from its `base` — an
+* object whose `id` is already on the row as `headCommitId` — but it is where
+* the record's FIELD VALUES live (`headCommit.payload`), so dropping it would
+* return ten rows of ids and no data. Every commit-shaped object in this
+* contract carries `payload`; no hydrated parent does.
+*/
+const isHydrated = (key, item, scalarKeys) => {
+	if (item === null || typeof item !== "object") return false;
+	if (carriesPayload(item)) return false;
+	return scalarKeys.some((scalar) => scalar !== key && (scalar === `${key}Id` || key.startsWith(scalar)));
+};
+const carriesPayload = (item) => Array.isArray(item) ? item.some((entry) => entry !== null && typeof entry === "object" && carriesPayload(entry)) : "payload" in item;
 //#endregion
 //#region ../../packages/busabase-contract/src/auth/device-authorization.ts
 /** Public client identifier shared by the Busabase CLI and Cloud auth server. */
@@ -3958,6 +4272,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: [
@@ -4341,8 +4859,7 @@ z.discriminatedUnion("operation", [archiveBaseInputSchema.extend({
 * when a node carries no `icon`, every host falls back to the type icon, same
 * as before this field existed.
 *
-* The `attachment` variant mirrors buda's `NodeLogo` shape (see
-* `apps/buda/src/domains/agent-controller/components/use-logo-crop-upload.tsx`):
+* The `attachment` variant follows the shared avatar-cropping model:
 * `url`/`attachmentId` are the CROPPED display image actually rendered, while
 * `originalUrl`/`originalAttachmentId` + `crop` are kept so the crop dialog can
 * re-open non-destructively against the untouched source image instead of
@@ -5080,7 +5597,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 +5852,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 +5872,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 +5885,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 +6013,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 +6023,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 +6082,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 +6099,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 +6174,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 +6185,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 +6203,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 +6247,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 +6277,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 +6292,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 +6319,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 +6467,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 +6478,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 +6582,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,175 +7011,10 @@ 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:
-*
-* 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/frontmatter.ts
-/**
-* YAML frontmatter for doc nodes (§6.3): `name`, `description?`, `position?` above
-* the markdown body.
+* 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.
@@ -6523,6 +7066,78 @@ const serializeDoc = (fields, body) => {
 	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, "\\$&");
+/**
+* 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 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;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		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 {
+		regex: patternToRegex(pattern, anchored),
+		negated,
+		directoryOnly
+	};
+};
+const parseIgnoreFile = (contents) => {
+	const rules = contents.split(/\r?\n/).map(parseRule).filter((rule) => rule !== void 0);
+	return {
+		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;
+		}
+	};
+};
+/** 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
 /**
 * Layout reader: a package's files (from a repo dir, or an extracted zip held in
@@ -6537,6 +7152,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 +7223,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 +7340,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 +7382,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,199 +7470,157 @@ 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");
-};
-/**
-* 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));
-	renderNodes(tree.nodes, `${PACKAGE_CONTENT_DIRNAME}/`, files);
-	renderDocAssets(tree.assets ?? [], files);
-	return files;
+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 } : {}
+	};
 };
 /**
-* `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).
+* 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 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);
-	}
+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.
+`;
 };
 //#endregion
 //#region ../../packages/busabase-package/src/plan.ts
@@ -7025,9 +7671,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 +7691,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
@@ -7183,65 +7907,632 @@ const countTree = (tree) => {
 			counts.records += node.records.length;
 			break;
 		case "skill":
-			counts.skills++;
-			counts.files += node.files.length;
-			break;
+			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);
+	}
+};
+/**
+* `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":
-			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 +8548,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 +8581,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 +8595,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 +8671,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 +8699,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 +8751,207 @@ 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/paginate.ts
+/**
+* `--all`: follow the cursor to the end instead of making the caller loop.
+*
+* Every listing in this CLI is bounded — that is the point of the `limit` work —
+* but "bounded" moves the burden onto the caller, who now has to notice
+* `nextCursor`, thread it back in, and know when to stop. An agent that misses
+* that reports a truncated answer as the whole answer, which is the failure the
+* `record_query` task guidance warns about in prose. This does it in code.
+*
+* Rows stream out as NDJSON — one JSON object per line — rather than
+* accumulating into one array, so memory stays flat and a consumer can start
+* work on page 1 while page 9 is still in flight. That is why `--all` overrides
+* `--output`: a 40,000-row table is not a thing anyone wanted.
+*/
+/**
+* Read a page out of whatever the command returned.
+*
+* Two protocols exist and both are honoured. Most paginated endpoints return
+* `{ rows, nextCursor }`. `GET /assets` returns a bare array and pages by the
+* last row's `id`, with a short page meaning the end — a shape chosen there to
+* keep the response backwards compatible for the web and mobile clients.
+*/
+function readPage(result, limit) {
+	const envelope = asEnvelope(result);
+	if (envelope) {
+		const cursor = envelope.meta.find(([key]) => key === "nextCursor")?.[1];
+		if (cursor === void 0) return void 0;
+		return {
+			rows: envelope.rows,
+			nextCursor: typeof cursor === "string" ? cursor : null
+		};
+	}
+	if (!Array.isArray(result)) return void 0;
+	if (limit === void 0 || result.length < limit) return {
+		rows: result,
+		nextCursor: null
+	};
+	const id = result[result.length - 1]?.id;
+	return {
+		rows: result,
+		nextCursor: typeof id === "string" ? id : null
+	};
+}
+/** Stops a broken server or a cursor that never advances from looping forever. */
+const MAX_PAGES = 1e4;
+/**
+* Stream every page as NDJSON. Returns the number of rows written.
+*
+* A cap that truncates is always announced on stderr: a silently short answer
+* that looks complete is the exact failure this is meant to prevent.
+*/
+async function paginateAll(options) {
+	const { fetchPage, limit, maxItems, write, notify } = options;
+	let cursor;
+	let written = 0;
+	let seen = 0;
+	for (let pageIndex = 0; pageIndex < MAX_PAGES; pageIndex += 1) {
+		const result = await fetchPage(cursor);
+		const page = readPage(result, limit);
+		if (!page) {
+			write(JSON.stringify(result));
+			return 1;
+		}
+		seen += page.rows.length;
+		for (const row of page.rows) {
+			if (maxItems !== void 0 && written >= maxItems) {
+				notify(`[busabase-cli] --max-items ${maxItems} reached; stopped early with more rows available.`);
+				return written;
+			}
+			write(JSON.stringify(row));
+			written += 1;
+		}
+		if (!page.nextCursor) return written;
+		if (page.nextCursor === cursor) {
+			notify("[busabase-cli] the server returned the same cursor twice; stopping to avoid a loop.");
+			return written;
+		}
+		cursor = page.nextCursor;
+	}
+	notify(`[busabase-cli] stopped after ${MAX_PAGES} pages (${seen} rows scanned).`);
+	return written;
+}
+//#endregion
+//#region src/retry.ts
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 2e4;
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isNetworkError = (error) => error instanceof TypeError || /fetch failed|econnreset|econnrefused|etimedout|socket hang up/i.test(error instanceof Error ? error.message : String(error));
+/** `Retry-After` is either delay-seconds or an HTTP-date; both are legal. */
+function parseRetryAfter(header, now = Date.now()) {
+	if (!header) return void 0;
+	const seconds = Number(header.trim());
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, MAX_DELAY_MS);
+	const at = Date.parse(header);
+	if (Number.isNaN(at)) return void 0;
+	return Math.min(Math.max(at - now, 0), MAX_DELAY_MS);
+}
+/** Whether this outcome is worth another attempt for a request using `method`. */
+function shouldRetry(method, status) {
+	if (status === 429) return true;
+	if (!READ_METHODS.has(method.toUpperCase())) return false;
+	return status === void 0 || status >= 500;
+}
+/**
+* Wrap a fetch so transient failures are retried with exponential backoff.
+* Returns `base` unchanged when `retries` is 0, so the no-retry path adds no
+* wrapper and no behaviour.
+*/
+function withRetry(base, options) {
+	const { retries } = options;
+	if (retries <= 0) return base;
+	const sleep = options.sleep ?? defaultSleep;
+	const notify = options.notify ?? ((message) => console.error(message));
+	const jitter = options.jitter ?? Math.random;
+	return (async (input, init) => {
+		const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+		for (let attempt = 0;; attempt += 1) {
+			let response;
+			let failure;
+			try {
+				response = await base(input, init);
+			} catch (error) {
+				if (!isNetworkError(error)) throw error;
+				failure = error;
+			}
+			const status = response?.status;
+			const last = attempt >= retries;
+			if (!shouldRetry(method, status) || last) {
+				if (response) return response;
+				throw failure;
+			}
+			const backoff = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+			const delay = parseRetryAfter(response?.headers.get("retry-after") ?? null) ?? Math.round(backoff * (.5 + jitter() * .5));
+			notify(`[busabase-cli] ${status ? `HTTP ${status}` : "connection failed"} — retrying in ${Math.round(delay / 1e3)}s (attempt ${attempt + 2} of ${retries + 1})`);
+			await sleep(delay);
+		}
+	});
+}
 //#endregion
 //#region src/task-command.ts
 const collect = (value, previous = []) => [...previous, value];
@@ -7417,10 +8991,13 @@ const applyParam = (cmd, param) => {
 		case "stringArray":
 			cmd.option(`${flag} <value>`, `${description} (repeatable)`, collect);
 			return;
-		case "json":
-			cmd.option(`${jsonFlagFor(param)} <json|@file>`, description);
+		case "json": {
+			const jsonOption = `${jsonFlagFor(param)} <json|@file>`;
+			if (param.required) cmd.requiredOption(jsonOption, description);
+			else cmd.option(jsonOption, description);
 			if (param.cliShorthand) cmd.option(`${param.cliShorthand.flag} ${param.cliShorthand.placeholder}`, param.cliShorthand.description, collect);
 			return;
+		}
 		default: if (param.required) cmd.requiredOption(`${flag} <value>`, description);
 		else cmd.option(`${flag} <value>`, description);
 	}
@@ -7470,6 +9047,7 @@ const registerOne = (program, task, deps, path, preset = {}, summaryOverride) =>
 		}
 		applyParam(cmd, param);
 	}
+	if (task.guidance) cmd.addHelpText("after", `\n${wrapGuidance(rewriteTaskNames(task.guidance))}`);
 	if (task.examples && task.examples.length > 0 && Object.keys(preset).length === 0) cmd.addHelpText("after", `\nExamples:\n  ${task.examples.join("\n  ")}`);
 	cmd.action(deps.runAction(async (client, opts) => task.execute(client, {
 		...buildInput(task, opts, deps),
@@ -7477,11 +9055,108 @@ const registerOne = (program, task, deps, path, preset = {}, summaryOverride) =>
 	})));
 };
 const registerTaskCommands = (program, tasks, deps) => {
+	for (const task of tasks) cliPathByTaskName.set(task.name, `busabase-cli ${task.cliPath.join(" ")}`);
 	for (const task of tasks) {
 		registerOne(program, task, deps, task.cliPath);
 		for (const variant of task.cliVariants ?? []) registerOne(program, task, deps, variant.path, variant.preset, variant.summary);
 	}
 };
+/**
+* Guidance is written once and read by two surfaces, so it names sibling tasks
+* by their MCP tool name (`record_find_by_field`). That is not something a CLI
+* caller can type — the command is `records by-field-text` — so the shared text
+* is rewritten to this surface's vocabulary rather than forked.
+*/
+const rewriteTaskNames = (text) => text.replace(/`([a-z][a-z0-9_]*)`/g, (match, name) => {
+	const path = cliPathByTaskName.get(name);
+	return path ? `\`${path}\`` : match;
+});
+/** Filled by {@link registerTaskCommands}; empty until the surface is built. */
+const cliPathByTaskName = /* @__PURE__ */ new Map();
+/** Reflow guidance to the width commander uses for the rest of the help screen. */
+const wrapGuidance = (text, width = 78) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/).filter(Boolean)) if (line && `${line} ${word}`.length > width) {
+		lines.push(line);
+		line = word;
+	} else line = line ? `${line} ${word}` : word;
+	if (line) lines.push(line);
+	return lines.join("\n");
+};
+//#endregion
+//#region src/wait.ts
+/**
+* `--wait`: block until a submitted proposal is actually decided.
+*
+* Review-first is the product's whole point, so the useful unit of work for a
+* caller is not "the change request was filed" — it is "the change request was
+* merged, or it wasn't". Without this every caller writes the same poll loop
+* against `change-requests get`, and an agent that skips it reports a proposal
+* nobody has looked at as a completed task.
+*/
+/** Statuses that will not change again on their own. */
+const TERMINAL = /* @__PURE__ */ new Set([
+	"merged",
+	"rejected",
+	"closed",
+	"abandoned"
+]);
+const isChangeRequest = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const row = value;
+	return typeof row.id === "string" && row.id.startsWith("crq") && typeof row.status === "string";
+};
+/**
+* Find the change request a command's result is about.
+*
+* The shape differs across the surface — some routes return the change request
+* itself, some wrap it (`{ changeRequest }`), some return the materialized thing
+* with `materialized: false` alongside — so this looks for the id rather than
+* asking every command to declare it.
+*/
+function findChangeRequestId(result) {
+	if (isChangeRequest(result)) return result.id;
+	if (Array.isArray(result)) {
+		for (const item of result) {
+			const found = findChangeRequestId(item);
+			if (found) return found;
+		}
+		return;
+	}
+	if (!result || typeof result !== "object") return void 0;
+	const row = result;
+	if (typeof row.changeRequestId === "string") return row.changeRequestId;
+	for (const key of ["changeRequest", "changeRequests"]) {
+		const found = findChangeRequestId(row[key]);
+		if (found) return found;
+	}
+}
+const DEFAULT_POLL_MS = 3e3;
+/** Poll until the change request settles or the budget runs out. */
+async function waitForChangeRequest(options) {
+	const { changeRequestId, read, timeoutMs, pollMs = DEFAULT_POLL_MS, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, notify = () => {} } = options;
+	const deadline = now() + timeoutMs;
+	let latest;
+	let status = "unknown";
+	for (;;) {
+		latest = await read(changeRequestId);
+		status = isChangeRequest(latest) ? latest.status : "unknown";
+		if (TERMINAL.has(status)) return {
+			kind: "settled",
+			status,
+			changeRequest: latest
+		};
+		const remaining = deadline - now();
+		if (remaining <= 0) return {
+			kind: "timeout",
+			status,
+			changeRequest: latest
+		};
+		notify(`[busabase-cli] ${changeRequestId} is ${status}; waiting for a reviewer (${Math.round(remaining / 1e3)}s left)`);
+		await sleep(Math.min(pollMs, remaining));
+	}
+}
 //#endregion
 //#region src/run.ts
 /** Public docs page covering every error below, for both Cloud and local. Linked from each error. */
@@ -7513,9 +9188,12 @@ function resolveConfig(opts) {
 		webUrl: process.env.BUSABASE_WEB_URL ?? file.BUSABASE_WEB_URL ?? baseUrl,
 		apiKey: opts.apiKey ?? process.env.BUSABASE_API_KEY ?? file.BUSABASE_API_KEY,
 		spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
-		output: opts.output ?? configuredOutput() ?? "text"
+		output: opts.output ?? configuredOutput() ?? "text",
+		fetch: withRetry(fetch, { retries: opts.retries ?? DEFAULT_RETRIES })
 	};
 }
+/** Enough to ride out a rate limiter or a proxy blip; not enough to hide a real outage. */
+const DEFAULT_RETRIES = 2;
 /**
 * Config flags accepted anywhere on the line (`busabase-cli --output json bases list` and
 * `busabase-cli bases list --output json` both work): declared on the root program AND on every
@@ -7528,14 +9206,20 @@ const GLOBAL_LONG_FLAGS = /* @__PURE__ */ new Set([
 	"--space-id",
 	"--output",
 	"--profile",
-	"--config"
+	"--config",
+	"--slim",
+	"--retries",
+	"--all",
+	"--max-items",
+	"--wait",
+	"--wait-timeout"
 ]);
 function addGlobalFlags(cmd) {
 	return cmd.option("--base-url <url>", `server base URL (env BUSABASE_BASE_URL, default ${DEFAULT_BASE_URL})`).option("--api-key <token>", "bearer token for cloud hosts (env BUSABASE_API_KEY)").option("--space-id <id>", "target Busabase space (env BUSABASE_SPACE_ID)").option("--profile <name>", "account to use for this command (env BUSABASE_PROFILE)").option("--config <path>", "read credentials from this file instead (env BUSABASE_CONFIG)").addOption(new Option("--output <fmt>", "text | table | json (default text)").choices([
 		"text",
 		"table",
 		"json"
-	]));
+	])).option("--slim", "drop hydrated parents (a record's full `base`, `createdByUser`, `headCommit`) and keep their ids").option("--retries <n>", "extra attempts on 429 / 5xx / dropped connections (default 2, 0 disables)", parseNonNegativeInt).option("--all", "follow the cursor to the end and stream every row as NDJSON").option("--max-items <n>", "stop --all after this many rows", parsePositiveInt).option("--wait", "after submitting a Change Request, block until a reviewer merges or rejects it").option("--wait-timeout <seconds>", "budget for --wait (default 300)", parsePositiveInt);
 }
 const parseNum = (value) => {
 	const parsed = Number(value);
@@ -7547,6 +9231,11 @@ const parsePositiveInt = (value) => {
 	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("expected a positive integer");
 	return parsed;
 };
+const parseNonNegativeInt = (value) => {
+	const parsed = parseNum(value);
+	if (!Number.isInteger(parsed) || parsed < 0) throw new InvalidArgumentError("expected a non-negative integer");
+	return parsed;
+};
 const parseBoolean = (value) => {
 	if (value === "true") return true;
 	if (value === "false") return false;
@@ -7623,13 +9312,9 @@ function parseJsonValue(raw, flagName) {
 * better off than when the field was silently dropped.
 */
 function formatIssues(issues) {
-	if (!Array.isArray(issues) || issues.length === 0) return void 0;
-	return issues.map((issue) => {
-		if (!issue || typeof issue !== "object") return String(issue);
-		const { path, message } = issue;
-		const pathLabel = Array.isArray(path) && path.length > 0 ? path.join(".") : void 0;
-		return pathLabel ? `${pathLabel}: ${message}` : String(message ?? issue);
-	}).join("; ");
+	const parsed = toIssues(issues);
+	if (!parsed) return void 0;
+	return parsed.map(({ path, message }) => path ? `${path}: ${message}` : message).join("; ");
 }
 function formatRawErrorBody(status, statusText, text) {
 	try {
@@ -7644,7 +9329,7 @@ function formatRawErrorBody(status, statusText, text) {
 /** Raw fetch for endpoints outside the typed contract (health / openapi / api passthrough). */
 async function rawFetch(config, method, path, body) {
 	const url = `${normalizeBaseUrl(config.baseUrl)}${path}`;
-	const res = await fetch(url, {
+	const res = await (config.fetch ?? fetch)(url, {
 		method: method.toUpperCase(),
 		headers: {
 			...body !== void 0 ? { "content-type": "application/json" } : {},
@@ -7762,10 +9447,60 @@ function runAction(state, handler) {
 		if (refreshedToken) config.apiKey = refreshedToken;
 		state.config = config;
 		assertCredentialNotExpired(config.apiKey);
-		const result = await handler(createBusabaseClient(config), opts, config);
-		console.log(render(result, config.output));
+		const client = createBusabaseClient(config);
+		if (opts.all) {
+			await streamAllPages(client, opts, config, handler);
+			return;
+		}
+		const result = await handler(client, opts, config);
+		console.log(render(opts.slim ? slim(result) : result, config.output));
+		if (opts.wait) await awaitReview(client, opts, config, result);
 	};
 }
+/** Default `--wait` budget: long enough for a reviewer who is at their desk. */
+const DEFAULT_WAIT_SECONDS = 300;
+/**
+* Block until the Change Request this command just filed is decided.
+*
+* The result is printed first, so a caller that times out still has the id it
+* needs to come back to. Exit codes carry the outcome (see `errors.ts`): merged
+* is success, rejected is a decision the caller must branch on, and a timeout is
+* neither — nothing was decided, so the write must NOT be retried.
+*/
+async function awaitReview(client, opts, config, result) {
+	const changeRequestId = findChangeRequestId(result);
+	if (!changeRequestId) {
+		console.error("[busabase-cli] --wait: this command filed no Change Request; nothing to wait for.");
+		return;
+	}
+	const outcome = await waitForChangeRequest({
+		changeRequestId,
+		read: (id) => client.changeRequests.get({ changeRequestId: id }),
+		timeoutMs: (opts.waitTimeout ?? DEFAULT_WAIT_SECONDS) * 1e3,
+		notify: (message) => console.error(message)
+	});
+	console.log(render(opts.slim ? slim(outcome.changeRequest) : outcome.changeRequest, config.output));
+	if (outcome.kind === "timeout") throw new CliOutcomeError("TIMEOUT", `--wait timed out: ${changeRequestId} is still ${outcome.status}. Nothing was decided — do NOT resubmit; poll it with \`busabase-cli change-requests get --change-request-id ${changeRequestId}\`.`);
+	if (outcome.status !== "merged") throw new CliOutcomeError("REVIEW_REJECTED", `${changeRequestId} was ${outcome.status}, not merged.`);
+}
+/**
+* `--all` re-runs the same handler with a moving cursor. The handler reads its
+* input off `opts`, so advancing the page is a matter of setting `opts.cursor`
+* before each call rather than teaching every command a second code path.
+*/
+async function streamAllPages(client, opts, config, handler) {
+	if (await paginateAll({
+		fetchPage: async (cursor) => {
+			opts.cursor = cursor;
+			const result = await handler(client, opts, config);
+			return opts.slim ? slim(result) : result;
+		},
+		limit: typeof opts.limit === "number" ? opts.limit : void 0,
+		maxItems: typeof opts.maxItems === "number" ? opts.maxItems : void 0,
+		write: (line) => console.log(line),
+		notify: (message) => console.error(message)
+	}) === 0) console.error("[busabase-cli] no rows.");
+}
 /**
 * {@link runAction} for a command with one positional argument. Commander passes
 * `(arg, opts, cmd)` to such an action, so the arity differs from a flags-only leaf.
@@ -7779,7 +9514,24 @@ function runArgAction(state, handler) {
 		state.config = config;
 		assertCredentialNotExpired(config.apiKey);
 		const result = await handler(arg, createBusabaseClient(config), opts, config);
-		console.log(render(result, config.output));
+		console.log(render(opts.slim ? slim(result) : 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(opts.slim ? slim(result) : result, config.output));
 	};
 }
 function pkgVersion() {
@@ -7912,11 +9664,33 @@ function unionVariants(inputSchema, discriminator = "operation") {
 	return variants;
 }
 /**
+* Words of an identifier, however it was spelled: `changeRequests` + `reviewMany`
+* and `change_requests_review_many` both reduce to
+* `change requests review many`. Lets the CLI compare its own generated command
+* paths against the MCP tool names in {@link TASK_SUPERSEDED_MCP_TOOLS} without
+* either side having to know how the other spells things.
+*/
+const identifierWords = (parts) => parts.flatMap((part) => part.split(/[_\-\s]+/)).flatMap((part) => part.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(" ")).filter(Boolean).map((word) => word.toLowerCase()).join(" ");
+/**
+* Endpoint commands a curated task command already covers.
+*
+* The MCP adapter has always dropped these so "a catalog carries one way to do
+* each job rather than two" — and then the CLI published BOTH spellings, which
+* is a third of a 30 KB help screen an agent reads to orient itself. Same list,
+* same reason, one more consumer.
+*
+* Hidden, never removed: every one of them still runs, so no existing script
+* breaks, and `--help-all` prints them.
+*/
+const SUPERSEDED_COMMAND_PATHS = new Set(TASK_SUPERSEDED_MCP_TOOLS.map((tool) => identifierWords([tool])));
+/**
 * Procedures a curated command already exposes under a DIFFERENT name (so the
 * name-collision guard wouldn't catch them). Keyed `group.procKey`.
 */
 const GENERATED_SKIP = /* @__PURE__ */ new Set([
 	"search",
+	"guides.list",
+	"guides.read",
 	"auth.verify",
 	"records.search",
 	"records.listChangeRequests",
@@ -7946,7 +9720,8 @@ function registerGeneratedCommands(program, state) {
 	const addOneLeaf = (parent, navPath, procKey, proc, name, fields, description) => {
 		const { route } = proc["~orpc"];
 		if (parent.commands.some((c) => c.name() === name || c.aliases().includes(name))) return;
-		const leaf = parent.command(name).description(description ?? route.summary ?? `${route.method} ${route.path}`);
+		const superseded = SUPERSEDED_COMMAND_PATHS.has(identifierWords([parent.name(), name]));
+		const leaf = parent.command(name, superseded ? { hidden: true } : void 0).description(description ?? route.summary ?? `${route.method} ${route.path}`);
 		for (const f of fields) {
 			if (f.pinned !== void 0) continue;
 			const flag = `--${kebab(f.key)}`;
@@ -8021,14 +9796,26 @@ function flagSignature(cmd) {
 	}
 	return parts.join(" ");
 }
-const isHelpHidden = (cmd) => Boolean(cmd._noHelp);
+/**
+* Commander records `command(name, { hidden })` and `{ noHelp }` on `_hidden`;
+* this read `_noHelp`, which commander never sets, so it always answered false
+* and nothing was ever actually hidden from the root help.
+*/
+const isHelpHidden = (cmd) => Boolean(cmd._hidden) || Boolean(cmd._noHelp);
+/**
+* Set for the duration of a `--help-all` render. A module-level flag rather than
+* a parameter because commander calls the help hook itself, with no way to
+* thread an argument through.
+*/
+let showAllCommands = false;
 /**
 * Root help "Commands:" section: every leaf with its full flag signature (the flat
 * commander listing would only show group names). Generated from the command tree,
 * never hand-written.
 */
-function commandsSection(program) {
+function commandsSection(program, showAll = false) {
 	const lines = ["Commands:"];
+	const skip = (cmd) => cmd.name() === "help" || !showAll && isHelpHidden(cmd);
 	const entry = (prefix, cmd) => {
 		const sig = [prefix, flagSignature(cmd)].filter(Boolean).join(" ");
 		const desc = cmd.description();
@@ -8037,12 +9824,12 @@ function commandsSection(program) {
 		return `  ${sig}\n${" ".repeat(44)}${desc}`;
 	};
 	for (const cmd of program.commands) {
-		if (cmd.name() === "help" || isHelpHidden(cmd)) continue;
-		const leaves = cmd.commands.filter((leaf) => leaf.name() !== "help" && !isHelpHidden(leaf));
+		if (skip(cmd)) continue;
+		const leaves = cmd.commands.filter((leaf) => !skip(leaf));
 		if (leaves.length > 0) {
 			lines.push("");
 			for (const leaf of leaves) lines.push(entry(`${cmd.name()} ${leaf.name()}`, leaf));
-		} else lines.push(entry(cmd.name(), cmd));
+		} else if (cmd.commands.length === 0) lines.push(entry(cmd.name(), cmd));
 	}
 	return lines.join("\n");
 }
@@ -8054,7 +9841,12 @@ Several accounts: \`login --profile <name>\` adds one, \`auth status\` lists the
 \`auth switch\` changes which is active. Several spaces on one account (the norm on
 Cloud): \`space list\` / \`space use\`.
 
+New here? \`busabase-cli guide\` is the operating manual — read \`workspace\` before
+proposing changes. Endpoint commands a task command already covers are hidden;
+\`--help-all\` prints them (they all still run).
+
 Docs: https://busabase.com/docs · Troubleshooting: ${DOCS_TROUBLESHOOTING}`;
+/** Exported for the help-example test, which walks the command tree in-process. */
 function buildProgram(state = {}) {
 	const program = new Command("busabase-cli");
 	program.description("Client for the Busabase OpenAPI REST API — talks to `busabase server` or Cloud.").usage("[global flags] <command> [flags]").version(pkgVersion(), "-v, --version", "print busabase-cli version").exitOverride().showHelpAfterError("(run `busabase-cli --help` for the full command list)").addHelpText("beforeAll", () => banner(resolveConfig(program.opts()).baseUrl));
@@ -8062,6 +9854,29 @@ function buildProgram(state = {}) {
 	addGlobalFlags(program.command("health")).description("Server health check (GET /api/health)").action(runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/health")));
 	addGlobalFlags(program.command("openapi")).description("Fetch the OpenAPI document").action(runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/v1/openapi.json")));
 	addGlobalFlags(program.command("whoami")).description("Active space, user, and membership").action(runAction(state, (client) => client.auth.verify()));
+	addGlobalFlags(program.command("guide")).argument("[topic]", "which guide to read; omit to list the topics this server serves").description("Read the Busabase operating manual (approval-first rules, AirApp contract)").addHelpText("after", `
+Read this BEFORE unfamiliar work. It carries the conventions this workspace
+expects, which no flag or schema can express on its own.
+
+Examples:
+  busabase-cli guide                 # what is available here
+  busabase-cli guide workspace       # the approval-first workflow
+  busabase-cli guide airapp          # REQUIRED before writing any AirApp file`).action(async (topic, _opts, cmd) => {
+		const config = resolveConfig(cmd.optsWithGlobals());
+		state.config = config;
+		const client = createBusabaseClient(config);
+		if (!topic) {
+			console.log(render(await client.guides.list(), config.output));
+			return;
+		}
+		const guide = await client.guides.read({ topic });
+		if (config.output === "json") {
+			console.log(render(guide, config.output));
+			return;
+		}
+		console.log(guide.content);
+		console.error(`\n[busabase-cli] other topics: ${guide.otherTopics.join(", ") || "(none)"}`);
+	});
 	addGlobalFlags(program.command("login")).description("Connect the CLI to Busabase — Personal/local, Cloud, or self-hosted").option("--device-code", "force device authorization and skip the method prompt").option("--oauth", "legacy same-machine OAuth callback flow").option("--no-browser", "print the sign-in URL instead of opening a browser").option("--refresh", "rotate the saved OAuth token set (no browser, no re-login)").addHelpText("after", `
 Busabase is an approval-first database and knowledge base for AI agents: agents
 propose changes, humans review and merge what becomes trusted data.
@@ -8311,7 +10126,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 +10140,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 +10158,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
 	})));
@@ -8445,7 +10296,7 @@ To add content to a space that is already in use, use \`busabase-cli install\` i
 			leaf.usage(`${sig ? `${sig} ` : ""}[global flags]`);
 		}
 	}
-	program.addHelpText("after", () => `\n${commandsSection(program)}\n${HELP_FOOTER}`);
+	program.addHelpText("after", () => `\n${commandsSection(program, showAllCommands)}\n${HELP_FOOTER}`);
 	program.configureHelp({ visibleCommands: () => [] });
 	return program;
 }
@@ -8460,17 +10311,48 @@ async function runCli(argv) {
 		program.outputHelp();
 		return 0;
 	}
+	if (argv.includes("--help-all")) {
+		console.log(renderedHelp({ showAll: true }));
+		return 0;
+	}
 	try {
 		await program.parseAsync(argv, { from: "user" });
 		return 0;
 	} catch (error) {
-		if (error instanceof CommanderError) return error.exitCode === 0 ? 0 : 1;
+		const json = errorOutputIsJson(state, argv);
+		if (error instanceof CommanderError) {
+			if (error.exitCode === 0) return 0;
+			if (json) console.log(JSON.stringify({
+				ok: false,
+				code: "USAGE",
+				message: error.message,
+				retryable: false
+			}, null, 2));
+			return EXIT_CODES.USAGE;
+		}
+		const classified = classifyError(error);
+		if (json) console.log(JSON.stringify(errorEnvelope(classified), null, 2));
 		console.error(explainError(error, state.config ?? resolveConfig({})));
-		return 1;
+		return classified.exitCode;
 	}
 }
-function renderedHelp() {
+/**
+* Whether a failed run should print the machine-readable envelope.
+*
+* `state.config` is set by the first command that resolves one, but a failure
+* can happen before that (an unknown option, a bad `--config` path), so the raw
+* argv is the fallback. Both spellings commander accepts are checked.
+*/
+function errorOutputIsJson(state, argv) {
+	if (state.config) return state.config.output === "json";
+	const flag = argv.indexOf("--output");
+	if (flag !== -1 && argv[flag + 1] === "json") return true;
+	if (argv.includes("--output=json")) return true;
+	return configuredOutput() === "json";
+}
+function renderedHelp({ showAll = false } = {}) {
 	let out = "";
+	showAllCommands = showAll;
 	const program = buildProgram();
 	program.configureOutput({
 		writeOut: (str) => {
@@ -8479,10 +10361,12 @@ function renderedHelp() {
 		writeErr: () => {}
 	});
 	program.outputHelp();
+	showAllCommands = false;
 	return out;
 }
 /** Full root help text (what `busabase-cli --help` prints). Generated from the command tree. */
 const HELP = renderedHelp();
+renderedHelp({ showAll: true });
 /**
 * Turn a low-level transport/HTTP error into an actionable message: which host was tried, the
 * concrete next step (set a key for Cloud, point at a local server, or check connectivity), and a
@@ -8492,7 +10376,7 @@ function explainError(error, config) {
 	const base = config.baseUrl;
 	const rawMessage = error instanceof Error ? error.message : String(error);
 	const issueDetail = formatIssues(error.data?.issues);
-	const msg = issueDetail ? `${rawMessage} — ${issueDetail}` : rawMessage;
+	const msg = issueDetail && !rawMessage.includes(issueDetail) ? `${rawMessage} — ${issueDetail}` : rawMessage;
 	const status = error.status;
 	const lower = msg.toLowerCase();
 	let body;