busa-cli 0.96.0 → 0.98.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-B3hHU9aE.js";
+import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-BVOkW2wU.js";
 //#region src/flush-stdio.ts
 /**
 * Wait for stdout/stderr to reach the other side before the process is torn down.

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as render, i as checkForUpdate, n as pkgVersion, r as runCli, t as HELP } from "./run-B3hHU9aE.js";
+import { a as render, i as checkForUpdate, n as pkgVersion, r as runCli, t as HELP } from "./run-BVOkW2wU.js";
 import { DEFAULT_BASE_URL, createBusabaseClient, normalizeBaseUrl } from "busabase-sdk";
 export { DEFAULT_BASE_URL, HELP, checkForUpdate, createBusabaseClient, normalizeBaseUrl, pkgVersion, render, runCli };

package/dist/{run-B3hHU9aE.js → run-BVOkW2wU.js}

@@ -18,7 +18,8 @@ import { checkAirApp } from "busabase-sdk/airapp-check";
 import { fileURLToPath } from "node:url";
 import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
 import QRCode from "qrcode";
-const LocaleSchema = z.enum({
+//#region ../../packages/openlib/i18n/i18n.ts
+const i18n = {
 	defaultLocale: "en",
 	locales: [
 		"en",
@@ -46,7 +47,8 @@ const LocaleSchema = z.enum({
 		"vi",
 		"pt"
 	]
-}.locales);
+};
+const LocaleSchema = z.enum(i18n.locales);
 //#endregion
 //#region ../../packages/openlib/i18n/i-string.ts
 /**
@@ -158,15 +160,15 @@ const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
 const customPromptLabelSchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => v.length <= CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars), { message: `label must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars} characters per locale` });
 const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => utf8ByteLength(v) <= CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes), { message: `body must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes} bytes (UTF-8) per locale` });
 /**
-* One custom scenario prompt. `body`'s `{target}` placeholder is substituted at
-* render time with the same target string `PromptDef.body(target)` receives
-* today (see `node-agent-prompts.ts`) — this schema does not interpolate it.
+* One custom scenario prompt. `body` is only the task: every rendered prompt
+* opens with the node's target line, the same one a built-in prompt opens with
+* (see `node-agent-prompts.ts`), so authors never place it and this schema
+* interpolates nothing.
 *
-* The placeholder is OPTIONAL and chooses placement only: a `body` that never
-* mentions `{target}` gets the target line prepended as its first paragraph, so
-* a custom prompt can never reach an agent without naming the node it acts on.
-* That is why the schema does not require it — forgetting it is not an error to
-* reject, it is a default to supply.
+* `{target}` is a retired placeholder that is still accepted, because bodies
+* saved before the target line became fixed contain it: a line that is only
+* `{target}` is dropped (the target already opens the prompt), and one inside a
+* sentence reads as the node's name. Rejecting it would break those prompts.
 */
 const customPromptDefSchema = z.object({
 	/** Stable id, unique within this node's custom list. */
@@ -178,7 +180,7 @@ const customPromptDefSchema = z.object({
 	intent: customPromptIntentSchema.optional(),
 	/** Short title shown in the dialog's left list. */
 	label: customPromptLabelSchema,
-	/** Template text; "{target}" is substituted with the rendered target line. */
+	/** The task. The node's target line is added ahead of it when the prompt renders. */
 	body: customPromptBodySchema
 });
 /**
@@ -246,14 +248,15 @@ const PlaybookMatchFieldSchema = z.enum([
 	"body"
 ]);
 const localeSchema = z.string().trim().min(1).max(20).describe("Locale for prompt labels and the rendered prompt body, e.g. \"en\" or \"zh-CN\". Falls back to English, then to whatever locale the prompt has.");
-z.object({
+const playbookSearchInputShape = {
 	queries: z.array(z.string().max(PLAYBOOK_SEARCH_LIMITS.maxQueryChars)).max(PLAYBOOK_SEARCH_LIMITS.maxQueries).default([]).describe("2–5 phrasings of what the user wants, in the user's language AND in English (e.g. [\"记录客户拜访\", \"log customer visit\", \"visit\"]). Each is matched as a case-insensitive substring; an item hit by more phrasings ranks higher. Empty = browse: every playbook, nearest first (at most 30)."),
 	kinds: z.array(PlaybookKindSchema).optional().describe("Restrict to \"skill\" and/or \"prompt\". Default: both."),
 	nearNodeId: z.string().trim().min(1).optional().describe("The node the user is on. Playbooks on that node rank first, then its folder, then ancestor folders (closest first)."),
 	inNodeId: z.string().trim().min(1).optional().describe("Only return playbooks on this node or inside its subtree."),
 	limit: z.coerce.number().int().min(1).max(PLAYBOOK_SEARCH_LIMITS.maxLimit).optional().describe("Max items (1–50). Default 10 for a search; 30 for a browse."),
 	locale: localeSchema.optional()
-});
+};
+z.strictObject(playbookSearchInputShape, { error: (issue) => issue.code === "unrecognized_keys" ? `Unknown key${issue.keys.length === 1 ? "" : "s"} ${issue.keys.map((key) => `"${key}"`).join(", ")}. playbooks search accepts: ${Object.keys(playbookSearchInputShape).join(", ")}${issue.keys.includes("query") ? " (did you mean \"queries\", an array of phrasings?)" : ""}.` : void 0 });
 /** Fields shared by a search item and a get result: where the playbook lives. */
 const playbookLocationShape = {
 	kind: PlaybookKindSchema,
@@ -1597,7 +1600,7 @@ const driveNodeType = makeFileTreeNodeType({
 	routeBase: "drives",
 	tag: "Drives",
 	entryFile: "README.md",
-	publicAccess: "no"
+	publicAccess: "detail"
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/file-node/definition.ts
@@ -1696,7 +1699,7 @@ const htmlNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
-		publicAccess: "no"
+		publicAccess: "detail"
 	},
 	operations: [{
 		kind: "html_document_update",
@@ -1714,7 +1717,7 @@ const skillNodeType = makeFileTreeNodeType({
 	routeBase: "skills",
 	tag: "Skills",
 	entryFile: "SKILL.md",
-	publicAccess: "no"
+	publicAccess: "detail"
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/whiteboard/definition.ts
@@ -1883,6 +1886,7 @@ const rejectMismatchedPayload = (input) => {
 	const type = input.type;
 	const wrong = [];
 	if (input.fields !== void 0 && type !== "base") wrong.push("fields");
+	if (input.skipDefaultView !== void 0 && type !== "base") wrong.push("skipDefaultView");
 	if (input.body !== void 0 && type !== "doc") wrong.push("body");
 	if (input.assetId !== void 0 && type !== "file") wrong.push("assetId");
 	if ((input.files !== void 0 || input.mergeMode !== void 0) && !FILE_TREE_TYPES.has(type)) wrong.push(input.files !== void 0 ? "files" : "mergeMode");
@@ -2012,7 +2016,8 @@ const createNode = async (client, input) => {
 	if (type === "base") {
 		const payload = {
 			...common,
-			fields: asFieldArray(input.fields) ?? []
+			fields: asFieldArray(input.fields) ?? [],
+			...input.skipDefaultView ? { defaultView: false } : {}
 		};
 		return client.bases.create(payload);
 	}
@@ -2135,6 +2140,15 @@ const nodeCreateTask = {
 				parser: "fieldSpecs"
 			}
 		},
+		{
+			name: "skipDefaultView",
+			appliesWhen: {
+				param: "type",
+				values: ["base"]
+			},
+			kind: "boolean",
+			description: "Base only. Create the Base WITHOUT its default \"Grid view\" (a table of every record and field). Only when you add your own views right after with view_change_request — a Base must keep at least one view, and the first one is what it opens on."
+		},
 		{
 			name: "body",
 			kind: "string",
@@ -2225,7 +2239,7 @@ const nodeCreateTask = {
 		{
 			name: "agentPrompts",
 			kind: "json",
-			description: "Scenario prompts shown when someone opens this node and asks an agent for something: [{\"key\":\"log-visit\",\"label\":\"Log a customer visit\",\"body\":\"{target}\\n\\nAdd a visit record with today's date, the contact I name, and a one-line summary.\",\"intent\":\"change\"}]. Write what the PERSON wants in their own words (\"Log a customer visit\"), not the operation (\"Create a record in Visits\") — the node type already covers the operations. These REPLACE the node type's default scenario prompts, so 2-5 real recurring jobs help and a generic pair is worse than none: omit this when you cannot name one. `{target}` expands to a complete sentence naming the node and space, so give it its own line. Stored in a second call after the node exists, so they are skipped (and reported) when this call proposes a ChangeRequest instead of creating the node; add them afterwards with `nodes set-agent-prompts`."
+			description: "Scenario prompts shown when someone opens this node and asks an agent for something: [{\"key\":\"log-visit\",\"label\":\"Log a customer visit\",\"body\":\"Add a visit record with today's date, the contact I name, and a one-line summary.\",\"intent\":\"change\"}]. Write what the PERSON wants in their own words (\"Log a customer visit\"), not the operation (\"Create a record in Visits\") — the node type already covers the operations. These are added after the node type's built-in scenario prompts, so 2-5 real recurring jobs help and a generic pair only repeats the defaults: omit this when you cannot name one. Write only the task: Busabase opens every prompt with a line naming the node and space, so do not write `{target}`. Stored in a second call after the node exists, so they are skipped (and reported) when this call proposes a ChangeRequest instead of creating the node; add them afterwards with `nodes set-agent-prompts`."
 		}
 	],
 	examples: [
@@ -2570,7 +2584,7 @@ const viewChangeTask = {
 	name: "view_change_request",
 	cliPath: ["views", "change-request"],
 	summary: "Propose a Base view change (create / update / delete / restore)",
-	guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content — when you are building starter structure (a Base plus the views that make it usable) let it merge so the workspace is not left half-built behind a review queue, exactly as you would for `node_create` and `POST /bases`. `create` needs the BASE id; update / delete / restore need the VIEW id — the endpoint split follows whichever id identifies the target, which this task handles for you.",
+	guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content — when you are building starter structure (a Base plus the views that make it usable) let it merge so the workspace is not left half-built behind a review queue, exactly as you would for `node_create` and `POST /bases`. `create` needs the BASE id; update / delete / restore need the VIEW id — the endpoint split follows whichever id identifies the target, which this task handles for you. View order is shared by everyone: a new view joins the end, `update` with `position` moves one (0 = leftmost), and the leftmost view is what the Base opens on. Every Base keeps at least one view, so deleting its last one is rejected — create the replacement first. A new Base already starts with a default \"Grid view\" (every record and field): when you are about to add your own views, create the Base with `node_create` `skipDefaultView` (REST `defaultView: false`) so your first view is the one it opens on.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -2641,6 +2655,16 @@ const viewChangeTask = {
 			},
 			description: "Changes to apply to the view (update only)."
 		},
+		{
+			name: "position",
+			kind: "number",
+			min: 0,
+			appliesWhen: {
+				param: "action",
+				values: ["update"]
+			},
+			description: "Move the view to this 0-based index among the Base's views (update only); the others shift to make room. 0 makes it the view the Base opens on."
+		},
 		{
 			name: "message",
 			kind: "string",
@@ -2665,6 +2689,7 @@ const viewChangeTask = {
 	examples: [
 		"busabase-cli views change-request --action create --base-id bas_1 --name \"Published\" --type table",
 		"busabase-cli views change-request --action create --base-id bas_1 --name \"Published\" --require-review",
+		"busabase-cli views change-request --action update --view-id viw_1 --position 0",
 		"busabase-cli views change-request --action delete --view-id viw_1"
 	],
 	execute: async (client, input) => {
@@ -2690,11 +2715,12 @@ const viewChangeTask = {
 			...meta
 		};
 		if (input.action === "update") {
-			if (!input.patch) throw new Error("action \"update\" requires patch.");
+			if (!input.patch && input.position === void 0) throw new Error("action \"update\" requires patch or position.");
 			return client.views.changeRequest({
 				operation: "update",
 				...target,
-				...input.patch
+				...input.patch ?? {},
+				...input.position !== void 0 ? { position: input.position } : {}
 			});
 		}
 		if (input.action === "delete") return client.views.changeRequest({
@@ -2793,6 +2819,162 @@ const TASK_SUPERSEDED_MCP_TOOLS = [
 	"bases_list_deleted_fields"
 ];
 //#endregion
+//#region ../../packages/busabase-contract/src/contract/agent-client.ts
+/**
+* Agent client attribution — "which agent program made this change".
+*
+* The API key says WHO is accountable (its name, its owner). On one machine,
+* several agents often share one key (`~/.busabase/.env`), so the key alone
+* cannot tell "Claude Code added this" from "Codex added this". A caller names
+* its agent client with ONE request header; busabase-cli detects it from the
+* environment and sends it on every request.
+*
+* It is SELF-REPORTED: a label for people reading the history, never identity,
+* authorization or anything security relevant. The server normalizes it with
+* `normalizeAgentClient` and stores only the normalized `{ id, name }`.
+*/
+const BUSABASE_AGENT_HEADER = "x-busabase-agent";
+const AgentClientVOSchema = z.object({
+	/** Normalized, lowercase `[a-z0-9-]`, at most 40 characters (e.g. `codex`). */
+	id: z.string(),
+	/** Display name: a known agent's product name, otherwise derived from the id. */
+	name: z.string()
+});
+const MAX_AGENT_ID_CHARS = 40;
+/** Longer raw values are not an agent name; don't spend work on them. */
+const MAX_RAW_CHARS = 256;
+/**
+* Agents whose names we know, keyed by every id they are commonly reported
+* as. Only agents whose environment markers were verified (see busabase-cli
+* `agent-client.ts`) get a canonical entry; anything else still works through
+* the generic path below.
+*/
+const KNOWN_AGENTS = {
+	"claude-code": {
+		id: "claude-code",
+		name: "Claude Code"
+	},
+	claudecode: {
+		id: "claude-code",
+		name: "Claude Code"
+	},
+	codex: {
+		id: "codex",
+		name: "Codex"
+	},
+	"codex-cli": {
+		id: "codex",
+		name: "Codex"
+	},
+	"openai-codex": {
+		id: "codex",
+		name: "Codex"
+	},
+	opencode: {
+		id: "opencode",
+		name: "OpenCode"
+	},
+	"gemini-cli": {
+		id: "gemini-cli",
+		name: "Gemini CLI"
+	},
+	gemini: {
+		id: "gemini-cli",
+		name: "Gemini CLI"
+	},
+	pi: {
+		id: "pi",
+		name: "Pi"
+	},
+	"pi-coding-agent": {
+		id: "pi",
+		name: "Pi"
+	}
+};
+/**
+* `AI_AGENT` is a cross-tool convention shaped `<tool>_<version>_agent`
+* (Claude Code: `claude-code_2-1-304_agent`); some tools set just `<tool>`
+* (OpenCode: `opencode`). Keep the tool part.
+*/
+const stripAiAgentConvention = (value) => {
+	return /^([^_]+)_[^_]*_agent$/.exec(value)?.[1] ?? value;
+};
+const toDisplayName = (id) => id.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+/**
+* Normalize a self-reported agent client (the `x-busabase-agent` header, or a
+* raw `AI_AGENT` value) to `{ id, name }`, or null when there is nothing
+* usable. Known agents map to their product name; anything else is reduced to
+* a lowercase `[a-z0-9-]` id of at most 40 characters with a name derived from
+* it — so the output never carries markup, whitespace or control characters.
+*/
+const normalizeAgentClient = (raw) => {
+	const trimmed = raw?.trim();
+	if (!trimmed || trimmed.length > MAX_RAW_CHARS) return null;
+	const id = stripAiAgentConvention(trimmed.toLowerCase()).replace(/[^a-z0-9]+/g, "-").slice(0, MAX_AGENT_ID_CHARS).replace(/^-+|-+$/g, "");
+	if (!id) return null;
+	return KNOWN_AGENTS[id] ?? {
+		id,
+		name: toDisplayName(id)
+	};
+};
+//#endregion
+//#region src/agent-client.ts
+const isSet = (value) => {
+	const trimmed = value?.trim().toLowerCase();
+	return Boolean(trimmed) && trimmed !== "0" && trimmed !== "false";
+};
+/**
+* Environment markers each agent puts on the commands it runs. Checked in
+* order; only markers backed by evidence are listed:
+* - Claude Code: `CLAUDECODE=1` (measured in a command Claude Code ran).
+* - Codex CLI: `CODEX_SESSION_ID` / `CODEX_THREAD_ID` (measured, Codex 0.163).
+* - OpenCode: `OPENCODE=1` (its shell tool sets it — packages/core/src/tool/plugin/shell.ts).
+* - Gemini CLI: `GEMINI_CLI=1` (ShellExecutionService, @google/gemini-cli-core 0.65).
+* - Pi: `PI_CODING_AGENT=true` (set in its own process, inherited by its bash
+*   tool; @mariozechner/pi-coding-agent 0.73).
+* Anything else is left to the generic `AI_AGENT` or the `BUSABASE_AGENT` override.
+*/
+const AGENT_MARKERS = [
+	{
+		id: "claude-code",
+		vars: ["CLAUDECODE"]
+	},
+	{
+		id: "codex",
+		vars: ["CODEX_SESSION_ID", "CODEX_THREAD_ID"]
+	},
+	{
+		id: "opencode",
+		vars: ["OPENCODE"]
+	},
+	{
+		id: "gemini-cli",
+		vars: ["GEMINI_CLI"]
+	},
+	{
+		id: "pi",
+		vars: ["PI_CODING_AGENT"]
+	}
+];
+const normalizedId = (value) => normalizeAgentClient(value)?.id;
+/**
+* Which agent client is running this CLI, as the id sent in `x-busabase-agent`.
+* Precedence: an explicit `BUSABASE_AGENT` → a specific agent's marker → the
+* cross-tool `AI_AGENT` convention (`<tool>_<version>_agent`) → none.
+* Self-reported attribution only — it labels the change, it grants nothing.
+*/
+const detectAgentClient = (env) => {
+	const explicit = normalizedId(env.BUSABASE_AGENT);
+	if (explicit) return explicit;
+	for (const marker of AGENT_MARKERS) if (marker.vars.some((name) => isSet(env[name]))) return marker.id;
+	return normalizedId(env.AI_AGENT);
+};
+/** The request header for the detected agent client, or undefined when there is none. */
+const agentClientHeaders = (env) => {
+	const agent = detectAgentClient(env);
+	return agent ? { [BUSABASE_AGENT_HEADER]: agent } : void 0;
+};
+//#endregion
 //#region src/config-file.ts
 /**
 * Credential + settings storage for every Busabase client.
@@ -6199,6 +6381,27 @@ const TemplateSecretSchema = z.object({
 	description: z.string().default(""),
 	required: z.boolean().default(true)
 });
+/**
+* One locale's own gallery media — the value side of `template.locales`.
+*
+* Both fields optional and independent: a locale that only re-recorded the clip
+* declares just `video` and keeps the default screenshots. Paths are
+* package-relative in `busabase.json` and absolute URLs on the catalog card;
+* the shape is the same, which is why the card VO reuses this schema.
+*/
+const TemplateLocaleMediaSchema = z.object({
+	/** Replaces the default list WHOLE for this locale — never merged per index. */
+	screenshots: z.array(z.string()).optional(),
+	video: z.string().optional()
+});
+/**
+* Per-locale media keyed by locale (`"zh-CN"`, `"ja"`).
+*
+* Keys are plain strings on purpose, not the supported-locale enum: a template
+* written for a locale this server does not know yet must still install. The
+* audit warns about such keys; the schema never rejects them.
+*/
+const TemplateLocalesSchema = z.record(z.string(), TemplateLocaleMediaSchema);
 const TemplateManifestSchema = z.object({
 	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
 	category: z.string().min(1),
@@ -6219,6 +6422,21 @@ const TemplateManifestSchema = z.object({
 	*/
 	video: z.string().optional(),
 	/**
+	* Localized gallery media, the App Store / Google Play rule: a viewer whose
+	* locale has an entry sees that entry's `screenshots` / `video`; anything the
+	* entry leaves out, and every locale without an entry, falls back to the two
+	* fields above. Those stay the English/default set — they are what every
+	* deployed server and CLI already reads, so their meaning cannot change.
+	*
+	* `{ "zh-CN": { "screenshots": ["assets/screenshots/cover-zh-CN.webp"],
+	*               "video": "assets/recordings/busa-rnd-zh-CN.mp4" } }`
+	*
+	* Additive by construction: an older parser strips the key (see the note on
+	* `video`), so an older server simply shows the defaults. Selection lives in
+	* one place — `pickTemplateMedia` in `domains/templates/media`.
+	*/
+	locales: TemplateLocalesSchema.optional(),
+	/**
 	* 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
@@ -6546,6 +6764,7 @@ z.object({
 		required: z.boolean().default(false),
 		options: fieldOptionsSchema.optional().default({})
 	})).default([]),
+	defaultView: z.boolean().optional().describe("Whether the new Base gets its default \"Grid view\" (a table view showing every record and field). Defaults to true. Pass false only when you add your own views right away — a Base must always keep at least one view, and the leftmost one is what it opens on."),
 	autoMerge: z.boolean().optional()
 });
 const createBaseFieldInputSchema = z.object({
@@ -6805,9 +7024,9 @@ z.object({
 	createdAt: z.string()
 });
 z.object({
-	parentId: z.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
-	depth: z.coerce.number().int().min(1).max(5).optional().describe("How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."),
-	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` walks the live TREE. `archived` returns a FLAT list of soft-archived nodes (the Trash view) with no parent/depth walk — so the response shape you can rely on differs between the two, not just the rows."),
+	parentId: z.string().nullable().optional().describe("Folder to start from: a node id or a folder slug. Omit or null to start from the space root. An unknown ref is a 404 and a node that is not a folder is a 400 — never an empty list. With `types`, scopes the flat list to this folder's subtree."),
+	depth: z.coerce.number().int().min(1).max(5).optional().describe("How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5. With `types` and `parentId`, how many levels of the folder's subtree to search (default: all of it)."),
+	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` walks the live TREE. `archived` returns a FLAT list of soft-archived nodes (the Trash view) with no parent/depth walk — so the response shape you can rely on differs between the two, not just the rows. `parentId` with `archived` is a 400."),
 	/**
 	* Narrow to specific node types and return a FLAT list of lightweight node
 	* summaries (`children: []`) instead of walking the tree. This is what
@@ -6831,7 +7050,7 @@ z.object({
 	* bare string, not a 1-element array — only a REPEATED occurrence
 	* (`?types=doc&types=file`) becomes an array. Accept both and normalize.
 	*/
-	types: z.union([z.array(z.enum(NODE_TYPES)), z.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe("Return a flat list of lightweight summaries for these node types instead of the tree. Read one node's full detail with GET /nodes/{nodeId}.")
+	types: z.union([z.array(z.enum(NODE_TYPES)), z.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe("Return a flat list of lightweight summaries for these node types instead of the tree — across the space, or within `parentId`'s subtree when given. Read one node's full detail with GET /nodes/{nodeId}.")
 }).optional();
 z.object({
 	nodeId: z.string().describe("The node walked UPWARDS from — the possible descendant."),
@@ -6932,7 +7151,12 @@ const sourceAttributionSchema = z.object({
 	ownerName: z.string().nullable(),
 	channel: sourceChannelSchema.nullable(),
 	/** Present only when the write declared a playbook the server could validate. */
-	playbook: PlaybookAttributionVOSchema.nullable().optional()
+	playbook: PlaybookAttributionVOSchema.nullable().optional(),
+	/**
+	* Present only when the write named its agent client (`x-busabase-agent`;
+	* busabase-cli sends it automatically). Self-reported — a label, not identity.
+	*/
+	agent: AgentClientVOSchema.nullable().optional()
 });
 const commitSchema = z.object({
 	id: z.string(),
@@ -7135,6 +7359,7 @@ const changeRequestSchema = z.object({
 	operationCount: z.number(),
 	reviews: z.array(reviewSchema)
 });
+changeRequestSchema.extend({ materialized: z.literal(false) });
 z.object({
 	changeRequest: changeRequestSchema,
 	trigger: z.enum(["changes_requested", "ai_mention"]),
@@ -7359,7 +7584,7 @@ z.object({
 	autoMerge: destructiveAutoMerge("Archiving is reversible: the record leaves every listing but is restored intact by `operation: \"restore\"`.")
 });
 z.object({
-	fields: z.record(z.string(), z.unknown()).describe("Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere."),
+	fields: z.record(z.string(), z.unknown()).describe("Updated field values keyed by field slug. A field id or its exact display name (any language, unambiguous) is mapped to the slug; a write in which no key names a field of the Base is a 400 listing the valid slugs. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere."),
 	message: z.string().optional().default("Revise operation").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Update deal stage to qualified — demo booked for July 8\"."),
 	author: z.string().optional().default("local-producer"),
 	baseCommitId: z.string().optional()
@@ -7615,6 +7840,7 @@ z.object({
 	type: viewTypeSchema,
 	config: viewConfigSchema,
 	status: z.enum(["active", "archived"]),
+	position: z.number().int(),
 	createdBy: z.string(),
 	createdByUser: userRefSchema.nullable().optional().default(null),
 	archivedAt: z.string().nullable(),
@@ -7648,6 +7874,7 @@ const updateViewInputSchema = z.object({
 	message: z.string().optional().default("Update view"),
 	name: z.string().min(1).optional(),
 	type: viewTypeSchema.optional(),
+	position: z.number().int().min(0).optional().describe("Move the view to this 0-based index among the Base's active views; the others shift to make room. The order is shared by everyone, and the leftmost view (0) is the one the Base opens on. Out-of-range values clamp to the end."),
 	submittedBy: z.string().optional().default("local-producer"),
 	autoMerge: autoMergeSchema
 });
@@ -8246,6 +8473,25 @@ const TEXT_EXTENSIONS = /\.(?:js|mjs|cjs|ts|mts|cts|json|ndjson|md|html|css|ya?m
 const IS_ASSERTION_CODE = /(?:^|\/)(?:scripts\/check\.mjs|tests?\/|[^/]*\.test\.[cm]?[jt]s)$/;
 /** Lockfiles carry integrity hashes that are not ours to interpret. */
 const NOT_SOURCE = /(?:^|\/)(?:package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/;
+/**
+* The locales Busabase renders its interface in — the same list `iStringParse`'s
+* `LocaleSchema` is built from, never a second copy. A `template.locales` key
+* outside it is legal (the schema accepts any string so an install never fails
+* over one) but no viewer is ever served it.
+*/
+const SUPPORTED_LOCALES = i18n.locales;
+/**
+* A file name that marks itself as one non-English locale's media —
+* `cover-zh-CN.webp`, `busa-rnd-ja.mp4` — following the `<name>-<locale>.<ext>`
+* convention. Case-insensitive because file systems and authors disagree on
+* `zh-cn` versus `zh-CN`; the separator may be `-`, `_` or `.`.
+*/
+const LOCALIZED_FILE = new RegExp(`[-_.](${SUPPORTED_LOCALES.filter((locale) => locale !== i18n.defaultLocale).join("|")})\\.[a-z0-9]+$`, "i");
+const localeMarkedIn = (path) => {
+	const match = LOCALIZED_FILE.exec(path);
+	if (!match) return void 0;
+	return SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === match[1].toLowerCase());
+};
 const relativePaths = (files, root = "") => {
 	const prefix = root ? `${root.replace(/\/+$/, "")}/` : "";
 	const out = [];
@@ -8283,6 +8529,24 @@ const auditPackage = (tree, files, options = {}) => {
 	for (const screenshot of tree.manifest.template?.screenshots ?? []) if (!present.has(screenshot)) error("package/screenshot-missing", `busabase.json declares screenshot "${screenshot}", which is not in the package. The Template Center card would render a broken image.`);
 	const video = tree.manifest.template?.video;
 	if (video && !present.has(video)) error("package/video-missing", `busabase.json declares video "${video}", which is not in the package. The Template Center detail page would show a play button that leads nowhere.`);
+	for (const [locale, media] of Object.entries(tree.manifest.template?.locales ?? {})) {
+		if (!SUPPORTED_LOCALES.includes(locale)) warn("package/locale-unknown", `busabase.json declares media for locale "${locale}", which is not one Busabase shows its interface in (${SUPPORTED_LOCALES.join(", ")}). It still installs, but no viewer is ever served it — check the spelling (keys are exact, e.g. "zh-CN", not "zh").`);
+		else if (locale === i18n.defaultLocale) warn("package/locale-default-language", `busabase.json declares \`template.locales.${locale}\`, but the default \`screenshots\` / \`video\` already are the English set — and they, not \`locales.${locale}\`, are what every language without its own entry falls back to. Put English media in the defaults and drop \`locales.${locale}\`, or the two drift apart.`);
+		for (const screenshot of media.screenshots ?? []) if (!present.has(screenshot)) error("package/screenshot-missing", `busabase.json declares ${locale} screenshot "${screenshot}" (template.locales.${locale}.screenshots), which is not in the package. A ${locale} viewer's Template Center card would render a broken image.`);
+		if (media.video && !present.has(media.video)) error("package/video-missing", `busabase.json declares ${locale} video "${media.video}" (template.locales.${locale}.video), which is not in the package. A ${locale} viewer's detail page would show a play button that leads nowhere.`);
+	}
+	const defaults = [...(tree.manifest.template?.screenshots ?? []).map((path) => ({
+		path,
+		field: "screenshots"
+	})), ...video ? [{
+		path: video,
+		field: "video"
+	}] : []];
+	for (const { path, field } of defaults) {
+		const locale = localeMarkedIn(path);
+		if (!locale) continue;
+		warn("package/localized-default-media", `"${path}" is in the default \`template.${field}\`, but its name marks it ${locale}. The defaults are the English set every language without its own entry falls back to; move it to \`template.locales.${locale}.${field}\`.`);
+	}
 	for (const relative of paths) {
 		const base = relative.slice(relative.lastIndexOf("/") + 1);
 		if (/^\.env(?!\.example$)(?:\.|$)/.test(base)) error("package/dotenv", `${relative} is part of the package. Credentials belong in Vault, never in something people install.`);
@@ -9802,6 +10066,7 @@ const createBase = async (client, node, parentNodeId, options, state, bases, fie
 		name: node.name,
 		description: node.description,
 		fields: immediateFields,
+		...node.base.views.length > 0 ? { defaultView: false } : {},
 		autoMerge: true
 	});
 	if (!result.materialized) throw new Error(`Base "${node.slug}" was requested immediately but the server returned a pending change request; install cannot attach its views or records to it.`);
@@ -10329,7 +10594,10 @@ const collectBase = async (client, source, common, options) => {
 	const base = await client.bases.get({ baseId });
 	if (!base) throw new Error(`Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run export.`);
 	const allViews = await client.bases.listViews({ baseId: base.id });
-	const views = allViews.filter((view) => view.slug.length > 0);
+	const views = allViews.filter((view) => view.slug.length > 0).map((view, index) => ({
+		view,
+		index
+	})).sort((left, right) => (left.view.position ?? 0) - (right.view.position ?? 0) || left.index - right.index).map(({ view }) => view);
 	if (views.length !== allViews.length) options.warn(`Base "${common.slug}" has ${allViews.length - views.length} view(s) with no slug — they were dropped (predates the slug requirement; rename it in the UI to keep it).`);
 	const { baseSlugById, fieldSlugById } = await buildIndexes(client, options.baseResourceKeys ?? /* @__PURE__ */ new Map());
 	const fields = [...base.fields].sort((a, b) => a.position - b.position).map((field) => toPackageField(field, {
@@ -10591,6 +10859,41 @@ const assertSelfContained = (tree, options) => {
 	}
 };
 //#endregion
+//#region ../../packages/busabase-contract/src/domains/templates/media.ts
+const nonEmptyStrings = (value) => {
+	if (!Array.isArray(value)) return void 0;
+	const list = value.filter((item) => typeof item === "string" && item !== "");
+	return list.length > 0 ? list : void 0;
+};
+const nonEmptyString = (value) => typeof value === "string" && value !== "" ? value : void 0;
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Normalize an untrusted `locales` value, or `undefined` when nothing usable is
+* left.
+*
+* Never throws — the catalog is fetched JSON from a repository the server does
+* not control, and one malformed entry must not blank the gallery for every
+* other card. A non-object `locales`, a non-object entry, a non-array
+* `screenshots` or a non-string `video` is ignored, and the viewer gets the
+* defaults. An empty `screenshots: []` or `video: ""` counts as "not declared":
+* a locale that ships no gallery should see the default one, not a placeholder.
+*/
+const parseTemplateLocales = (raw) => {
+	if (!isPlainObject(raw)) return void 0;
+	const locales = {};
+	for (const [locale, entry] of Object.entries(raw)) {
+		if (!locale || !isPlainObject(entry)) continue;
+		const screenshots = nonEmptyStrings(entry.screenshots);
+		const video = nonEmptyString(entry.video);
+		if (!screenshots && !video) continue;
+		locales[locale] = {
+			...screenshots ? { screenshots } : {},
+			...video ? { video } : {}
+		};
+	}
+	return Object.keys(locales).length > 0 ? locales : void 0;
+};
+//#endregion
 //#region ../../packages/busabase-package/src/plan.ts
 /**
 * Install planning: package tree + the target space's current state → a plan, a
@@ -11048,6 +11351,7 @@ const discoverPackages = (files) => {
 		}
 		const validation = validateTemplate(tree);
 		const claimsTemplate = Boolean(tree.rootSkill) || Boolean(tree.manifest.template);
+		const locales = parseTemplateLocales(tree.manifest.template?.locales);
 		found.push({
 			subdir,
 			name: tree.manifest.name,
@@ -11061,6 +11365,7 @@ const discoverPackages = (files) => {
 			...validation.risk ? { risk: validation.risk } : {},
 			screenshots: tree.manifest.template?.screenshots ?? [],
 			...tree.manifest.template?.video ? { video: tree.manifest.template.video } : {},
+			...locales ? { locales } : {},
 			tags: [.../* @__PURE__ */ new Set([...tree.manifest.tags, ...tree.manifest.template?.tags ?? []])],
 			agentPrompts: tree.manifest.template?.agentPrompts ?? [],
 			...tree.manifest.version ? { version: tree.manifest.version } : {},
@@ -11288,6 +11593,7 @@ const toEntry = (found, airapps) => ({
 	tags: found.tags ?? [],
 	screenshots: found.screenshots,
 	...found.video ? { video: found.video } : {},
+	...found.locales ? { locales: found.locales } : {},
 	agentPrompts: found.agentPrompts ?? [],
 	...found.version ? { version: found.version } : {},
 	...found.author ? { author: found.author } : {},
@@ -12634,6 +12940,7 @@ Quick reference — every path is relative to the base URL above; worked example
 | Bulk create records CR | \`POST /api/v1/bases/:baseId/records/bulk-change-request\` | propose many records (≤1000) as ONE CR |
 | Bulk update records CR | \`POST /api/v1/bases/:baseId/records/bulk-update-change-request\` | partially update many existing records (≤1000) as ONE atomic CR |
 | Create node CR | \`POST /api/v1/nodes/change-requests\` | propose folder / Skill structure changes (supports in-CR \`ref\`/\`parentNodeRef\`) |
+| View CR | \`POST /api/v1/views/change-requests\` | create / update / delete / restore a Base view. Order is shared: \`update\` with \`position\` reorders, the leftmost view is what the Base opens on, and a Base's last view can't be deleted. A new Base starts with a "Grid view" unless created with \`"defaultView": false\` |
 | Read Skill files | \`GET /api/v1/file-trees/:nodeId/files/:filePath\` | read a Skill file (same route for Drives and AirApps) |
 | Create Skill file CR | \`POST /api/v1/file-trees/:nodeId/change-requests\` | propose a Skill file edit |
 | Request asset upload | \`POST /api/v1/assets/upload-urls\` | request an upload target for attachment-field files |
@@ -12984,7 +13291,9 @@ curl ${base}/api/v1/openapi.json
 \`\`\`
 
 It is large — **do not load the whole file into context.** Pull out only the path you need
-(e.g. \`curl ${base}/api/v1/openapi.json | jq '.paths["/api/v1/records"]'\`), or browse the
+(e.g. \`curl ${base}/api/v1/openapi.json | jq '.paths["/api/v1/records"]'\`); shared types such as
+\`ChangeRequest\`, \`Base\`, and \`Record\` are \`$ref\`s into \`.components.schemas\` (e.g.
+\`jq '.components.schemas.ChangeRequest'\`). Or browse the
 interactive docs at \`${base}/api/v1/doc\`. MCP-capable agents can skip docs entirely and
 connect to \`${base}/api/mcp\` (Streamable HTTP) — the most context-efficient path.
 
@@ -13077,9 +13386,9 @@ ${authLine}  -H 'content-type: application/json' \\
   --data '{
     "agentPrompts": [
       { "key": "log-visit", "label": "Log a customer visit",
-        "body": "{target}\\n\\nAdd a visit record with the date I give, the contact I name, and a one-line summary." },
+        "body": "Add a visit record with the date I give, the contact I name, and a one-line summary." },
       { "key": "quarter-recap", "intent": "read-only", "label": "What did we discuss this quarter",
-        "body": "{target}\\n\\nSummarize every visit to the account I name since the quarter started." }
+        "body": "Summarize every visit to the account I name since the quarter started." }
     ]
   }'
 \`\`\`
@@ -13094,8 +13403,8 @@ Four rules, each of which is a way this goes wrong:
    write nothing — the defaults already cover the generic work.
 3. **Only write them when you know the job.** You usually do — the user just told you why they
    wanted this node. A scratch table, a one-off Doc, a folder that only groups things: no prompts.
-4. **\`{target}\` expands to a full sentence** naming the node and space, so give it its own line.
-   Dropped mid-sentence it reads as a run-on with two full stops.
+4. **Write only the task.** Busabase opens every prompt with a line naming the node and space, so
+   do not write \`{target}\` — the target is no longer yours to place.
 
 Prompts are addressed by node id, so they are a second call after the node exists. When your
 create was proposed for review instead of merged, there is no node id yet — say so, and write
@@ -14329,6 +14638,7 @@ function resolveConfig(opts, { strict = true } = {}) {
 		spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
 		sourceChannel: "cli",
 		playbook: resolvePlaybook(opts.playbook, strict),
+		headers: agentClientHeaders(process.env),
 		output: opts.output ?? configuredOutput() ?? "text",
 		fetch: withRetry(fetch, { retries })
 	};
@@ -14501,7 +14811,8 @@ async function rawFetch(config, method, path, body) {
 			...config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {},
 			...config.spaceId ? { "x-busabase-space": config.spaceId } : {},
 			"x-busabase-channel": "cli",
-			...config.playbook ? { [BUSABASE_PLAYBOOK_HEADER]: config.playbook } : {}
+			...config.playbook ? { [BUSABASE_PLAYBOOK_HEADER]: config.playbook } : {},
+			...typeof config.headers === "object" ? config.headers : {}
 		},
 		body: body !== void 0 ? JSON.stringify(body) : void 0
 	});
@@ -15444,10 +15755,11 @@ function buildProgram(state = {}) {
 Answers "what do I send, and what comes back" without fetching anything. The
 contract is compiled into this CLI, so \`schema\` works offline and unauthenticated.
 
-Prefer it over \`busabase-cli openapi\`: that returns the WHOLE document — 936 KB
-across 103 endpoints as of 2026-09-04, with every type inlined per endpoint — so
-reading one endpoint's arguments out of it costs roughly 234k tokens. One
-endpoint through \`schema\` is a few KB.
+Prefer it over \`busabase-cli openapi\`: that returns the WHOLE document — about
+240 KB across 106 endpoints as of 2026-10-20, with shared types behind \`$ref\`s
+into \`components.schemas\` — so reading one endpoint's arguments out of it costs
+tens of thousands of tokens plus chasing references. One endpoint through
+\`schema\` is a few KB and self-contained.
 
   busabase-cli schema                                 # every endpoint: id, method, path
   busabase-cli schema ${sampleEndpointId()}                       # input + output schema
@@ -15678,8 +15990,8 @@ Each entry: { key: string (unique per node), intent?: "read-only" | "change",
 label: string | { <locale>: string }, body: string | { <locale>: string } }.
 Locale keys (when using the object form): en, zh-CN, zh-TW, ja, ko, de, fr, es,
 pt — anything else fails validation as "Invalid input" on that field.
-"body" may contain a literal "{target}" placeholder, substituted at render time
-with the same node/space description every built-in prompt uses. At most 50
+"body" is only the task: every prompt opens with the same node/space line the
+built-in prompts use, added for you, so do not write "{target}". At most 50
 entries per node, 80 characters per localized label, 8 KiB per localized body.
 
 The file is validated against this exact schema BEFORE any network request —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.96.0",
+  "version": "0.98.0",
   "description": "Command-line client for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server`. Short-name alias for busabase-cli.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-cli",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@zip.js/zip.js": "^2.8.20",
     "busabase-package": "workspace:*",
-    "busabase-sdk": "0.96.0",
+    "busabase-sdk": "0.98.0",
     "commander": "^14.0.0",
     "qrcode": "^1.5.4",
     "tar-stream": "^3.1.7",