busa-cli 0.81.0 → 0.90.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-CGOZ8gfF.js";
+import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-CLlUJcaW.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-CGOZ8gfF.js";
+import { a as render, i as checkForUpdate, n as pkgVersion, r as runCli, t as HELP } from "./run-CLlUJcaW.js";
 import { DEFAULT_BASE_URL, createBusabaseClient, normalizeBaseUrl } from "busabase-sdk";
 export { DEFAULT_BASE_URL, HELP, checkForUpdate, createBusabaseClient, normalizeBaseUrl, pkgVersion, render, runCli };

package/dist/{run-CGOZ8gfF.js → run-CLlUJcaW.js}

@@ -86,9 +86,9 @@ const LocaleSchema = z.enum({
 *   - ZH: 拼接所有语言值以便展示/调试（顺序不保证）。
 *
 * Fallback behavior (iStringParse) / 回退策略（iStringParse）
-* - EN: If str is a string, return it. If it is a record: prefer requested locale; else any non-"en"; else "en".
+* - EN: If str is a string, return it. If it is a record: prefer requested locale; else "en"; else any available locale.
 *       Warn and return empty string if no suitable value exists.
-* - ZH: 若为纯字符串，原样返回；若为记录：优先使用请求的语言；否则使用任一非 "en"；再退回 "en"。
+* - ZH: 若为纯字符串，原样返回；若为记录：优先使用请求的语言；否则使用 "en"；再退回任一可用语言。
 *       若均不可用，会发出警告并返回空字符串。
 *
 * Examples / 示例
@@ -203,6 +203,233 @@ const customAgentPromptsSchema = z.array(customPromptDefSchema).max(CUSTOM_AGENT
 	});
 });
 //#endregion
+//#region ../../packages/busabase-contract/src/contract/playbook-schemas.ts
+/**
+* Playbooks — the skills and custom node prompts a space already defines for a
+* job — top-level, domain-agnostic schemas for `POST /playbooks/search` and
+* `GET /playbooks/{kind}/{nodeId}`.
+*
+* Top-level (like `grep-schemas.ts`) rather than inside one domain's contract,
+* because a playbook is either a Skill node or a prompt stored on ANY node type:
+* the surface composes several domains.
+*
+* The server does no intent recognition. The agent sends several phrasings of
+* what the user wants; the server matches them as case-insensitive substrings
+* against skill name/slug/description and prompt label/body, and ranks. See
+* `apps/busabase/content/spec/agent-playbook-discovery.md` §6.
+*
+* Pure zod — no logic/db imports (client-safe: pulled into the browser bundle
+* and the RN oRPC client's type graph).
+*/
+/** Named so a limit change has exactly one place to edit, and error messages can cite it. */
+const PLAYBOOK_SEARCH_LIMITS = {
+	/** Max phrasings per search. */
+	maxQueries: 8,
+	/** Max characters per phrasing. */
+	maxQueryChars: 200,
+	/** Default number of items returned for a non-empty search. */
+	defaultLimit: 10,
+	/** Hard cap on `limit`. */
+	maxLimit: 50,
+	/** An empty `queries` (browse) returns at most this many, nearest first. */
+	browseLimit: 30,
+	/** How much of a prompt body (per locale) is matched against. */
+	bodyPrefixChars: 500
+};
+const PlaybookKindSchema = z.enum(["skill", "prompt"]);
+/** Why an item matched. `name`/`slug`/`description` are skill fields; `label`/`body` are prompt fields. */
+const PlaybookMatchFieldSchema = z.enum([
+	"name",
+	"slug",
+	"description",
+	"label",
+	"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({
+	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()
+});
+/** Fields shared by a search item and a get result: where the playbook lives. */
+const playbookLocationShape = {
+	kind: PlaybookKindSchema,
+	nodeId: z.string(),
+	nodeType: z.string(),
+	nodeName: z.string(),
+	nodeSlug: z.string(),
+	/** Folder names from the workspace root down to the node's parent. Tells two same-named playbooks apart. */
+	path: z.array(z.string())
+};
+const PlaybookSearchItemVOSchema = z.object({
+	...playbookLocationShape,
+	/** Prompts only: the key to pass to `playbooks.get`. */
+	key: z.string().optional(),
+	/** Prompts only: the label in the requested locale (fallback `en`, then any). */
+	label: z.string().optional(),
+	/** Prompts only: `read-only` never writes; `change` goes through a change request. */
+	intent: z.enum(["read-only", "change"]).optional(),
+	/** Skills only: the skill's name. */
+	name: z.string().optional(),
+	/** Skills only: the skill's description (follows its SKILL.md frontmatter). */
+	description: z.string().optional(),
+	matchedOn: z.array(PlaybookMatchFieldSchema),
+	/** For debugging and tests. Rely on the ORDER of `items`, not on this number. */
+	score: z.number(),
+	updatedAt: z.string()
+});
+z.object({
+	items: z.array(PlaybookSearchItemVOSchema),
+	/** Every matching playbook the caller can read — not just the ones returned. */
+	total: z.number().int(),
+	/** True when `total` is larger than `items`. Narrow the search rather than paging. */
+	truncated: z.boolean(),
+	coverage: z.object({
+		/** Skill nodes considered (after permission, `kinds`, and `inNodeId` filters). */
+		skillsScanned: z.number().int(),
+		/** Nodes carrying custom prompts that were considered. */
+		promptNodesScanned: z.number().int()
+	})
+});
+z.object({
+	kinds: z.array(PlaybookKindSchema).optional().describe("Restrict to \"skill\" and/or \"prompt\". Default: both."),
+	locale: localeSchema.optional()
+});
+/**
+* Usage of one playbook, from the change requests agents wrote while following
+* it. Every status counts (in review, merged, rejected, …): the question is
+* "do agents find and follow this?", and a rejected change still proves they
+* did — the rejection is about the change, not about the playbook being found.
+*/
+const PlaybookUsageVOSchema = z.object({
+	/** Change requests citing this playbook created in the last `PLAYBOOK_USAGE_WINDOW_DAYS` days. */
+	changeRequests30d: z.number().int(),
+	/** ISO time of the newest change request citing it, at any age; null when none ever did. */
+	lastUsedAt: z.string().nullable()
+});
+const PlaybookListItemVOSchema = z.object({
+	...playbookLocationShape,
+	/** Prompts only: the key to pass to `playbooks.get`. */
+	key: z.string().optional(),
+	/** Prompts only: the label in the requested locale (fallback `en`, then any). */
+	label: z.string().optional(),
+	/** Prompts only: `read-only` never writes; `change` goes through a change request. */
+	intent: z.enum(["read-only", "change"]).optional(),
+	/** Prompts only: the start of the body in the requested locale, whitespace collapsed. */
+	bodyPreview: z.string().optional(),
+	/** Skills only: the skill's name. */
+	name: z.string().optional(),
+	/** Skills only: the skill's description (follows its SKILL.md frontmatter). */
+	description: z.string().optional(),
+	updatedAt: z.string(),
+	/**
+	* How often agents cited this playbook on their writes (the `x-busabase-playbook`
+	* attribution, spec §11b H1). Counts only change requests the viewer can see.
+	* Optional so an older server's response still parses.
+	*/
+	usage: PlaybookUsageVOSchema.optional()
+});
+z.object({
+	/** Sorted by folder path, then skills before prompts, then name/label. */
+	items: z.array(PlaybookListItemVOSchema),
+	/** Every playbook the caller can read — not just the ones returned. */
+	total: z.number().int(),
+	/** True when `total` is larger than `items` (more than `PLAYBOOK_LIST_LIMITS.maxItems`). */
+	truncated: z.boolean()
+});
+z.object({
+	kind: PlaybookKindSchema,
+	nodeId: z.string().trim().min(1),
+	key: z.string().trim().min(1).optional().describe("Required for a prompt: the `key` from `playbooks.search`."),
+	locale: localeSchema.optional().describe("Locale for the prompt label and rendered body, e.g. \"en\" or \"zh-CN\" — pass the user's. Without one (or with a locale the dashboard does not speak) the body is rendered in English and its footer says \"Reply in the user's language.\" instead of naming a language.")
+}).superRefine((input, ctx) => {
+	if (input.kind === "prompt" && !input.key) ctx.addIssue({
+		code: "custom",
+		path: ["key"],
+		message: "key is required for a prompt"
+	});
+});
+const PlaybookFileVOSchema = z.object({
+	path: z.string(),
+	size: z.number(),
+	mimeType: z.string().nullable()
+});
+z.object({
+	...playbookLocationShape,
+	/**
+	* What to follow. A prompt: its body rendered exactly as Ask Agent sends it
+	* (target line, merge-policy and reply-language footer). A skill: `SKILL.md`.
+	*/
+	content: z.string(),
+	/** Prompts only. */
+	key: z.string().optional(),
+	label: z.string().optional(),
+	intent: z.enum(["read-only", "change"]).optional(),
+	/** Prompts only: the locale the body was rendered in. */
+	locale: z.string().optional(),
+	/** Skills only. */
+	name: z.string().optional(),
+	description: z.string().optional(),
+	/** Skills only: every file in the skill. Read more with CLI `skills read-file` / MCP `node_file_read`. */
+	files: z.array(PlaybookFileVOSchema).optional()
+});
+/**
+* The one request header an agent uses to say which playbook it is following:
+* `x-busabase-playbook: <kind>:<nodeId>[:<key>]` (a prompt needs its key). The
+* server validates it and records the playbook on every change request the
+* request creates — see spec §11b (H1). The CLI's `--playbook`, the SDK's
+* `playbook` option, and the MCP `playbook` argument all become this header.
+*/
+const BUSABASE_PLAYBOOK_HEADER = "x-busabase-playbook";
+const MAX_PLAYBOOK_REF_CHARS = 512;
+/**
+* Parse `<kind>:<nodeId>[:<key>]`. Everything after the second colon is the key
+* (a prompt key may itself contain colons). Returns null for anything
+* malformed — a prompt without a key, a skill with one, an unknown kind — so a
+* bad value is dropped, never guessed at.
+*/
+const parsePlaybookRef = (value) => {
+	const trimmed = value?.trim();
+	if (!trimmed || trimmed.length > MAX_PLAYBOOK_REF_CHARS) return null;
+	const first = trimmed.indexOf(":");
+	if (first <= 0) return null;
+	const kind = PlaybookKindSchema.safeParse(trimmed.slice(0, first));
+	if (!kind.success) return null;
+	const rest = trimmed.slice(first + 1);
+	const second = rest.indexOf(":");
+	const nodeId = (second === -1 ? rest : rest.slice(0, second)).trim();
+	const key = second === -1 ? null : rest.slice(second + 1).trim() || null;
+	if (!nodeId) return null;
+	if (kind.data === "prompt" && !key) return null;
+	if (kind.data === "skill" && key) return null;
+	return {
+		kind: kind.data,
+		nodeId,
+		key
+	};
+};
+/**
+* The playbook a change request (or audit event) was produced by, as a reader
+* sees it. `accessible: false` means the playbook node exists in the record
+* but the current reader cannot read it: only the kind is disclosed, every
+* identifying field is null, and the UI shows "via a playbook" with no link.
+* The label is filled in by the server from the node itself when the write was
+* made — never taken from the caller.
+*/
+const PlaybookAttributionVOSchema = z.object({
+	kind: PlaybookKindSchema,
+	accessible: z.boolean(),
+	nodeId: z.string().nullable(),
+	/** Prompts only (null for a skill, or when not accessible). */
+	key: z.string().nullable(),
+	nodeType: z.string().nullable(),
+	nodeSlug: z.string().nullable(),
+	label: z.string().nullable()
+});
+//#endregion
 //#region ../../packages/busabase-contract/src/tasks/base-field.ts
 /**
 * Changing a Base's schema, as one task with an `operation` instead of six
@@ -1847,7 +2074,7 @@ const nodeCreateTask = {
 		}
 	],
 	summary: "Create a workspace node of any type",
-	guidance: "One call creates any of the 11 node types with its type-specific payload: `fields` for a Base, `body` for a Doc, `files` for a Skill/Drive/AirApp, `assetId` for a File. Review is permission-aware, decided server-side: this merges immediately when you already have write access on the parent node, and proposes a ChangeRequest for a human otherwise. Pass requireReview to always propose instead of merging. Before you finish: if the person will come back to this node to do the same job again, pass agentPrompts so the node opens with THEIR job on it instead of the node type's generic list.",
+	guidance: "If this job may already have a playbook, call playbooks search first. One call creates any of the 11 node types with its type-specific payload: `fields` for a Base, `body` for a Doc, `files` for a Skill/Drive/AirApp, `assetId` for a File. Review is permission-aware, decided server-side: this merges immediately when you already have write access on the parent node, and proposes a ChangeRequest for a human otherwise. Pass requireReview to always propose instead of merging. Before you finish: if the person will come back to this node to do the same job again, pass agentPrompts so the node opens with THEIR job on it instead of the node type's generic list.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -2026,7 +2253,7 @@ 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.",
+	guidance: "If this job may already have a playbook, call playbooks search first. 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
@@ -2112,7 +2339,7 @@ const recordChangeTask = {
 	name: "record_change_request",
 	cliPath: ["records", "change-request"],
 	summary: "Propose a change to an existing record (update / delete / restore)",
-	guidance: "Review is permission-aware for all three operations, 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 explicit `autoMerge: false` to force review even when you could write directly. `delete` ARCHIVES the record — it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
+	guidance: "If this job may already have a playbook, call playbooks search first. Review is permission-aware for all three operations, 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 explicit `autoMerge: false` to force review even when you could write directly. `delete` ARCHIVES the record — it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -4999,13 +5226,22 @@ function render(value, output) {
 	if (value && typeof value === "object") return renderRecord(value);
 	return String(value);
 }
+/**
+* Row keys that always mean "the results", even when an object sits beside them:
+* `playbooks search` → `{ items, total, truncated, coverage }` and `grep` →
+* `{ matches, coverage, truncated }`. Their `coverage` object used to fail the
+* scalar-only test below, so the whole answer printed as `items  [3 items]`.
+* Named rather than inferred so `whoami`'s `{ space, user, member, spaces }`
+* keeps rendering as a record.
+*/
+const RESULT_ROW_KEYS = /* @__PURE__ */ new Set(["items", "matches"]);
 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;
+	if (!meta.every(([, item]) => item === null || item === void 0 || typeof item !== "object") && !RESULT_ROW_KEYS.has(arrays[0][0])) return void 0;
 	return {
 		key: arrays[0][0],
 		rows: arrays[0][1],
@@ -5017,13 +5253,37 @@ function renderEnvelope(envelope, renderRows) {
 	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")}`;
+	return `${body}\n\n${meta.map(([key, item]) => `${key.padEnd(width)}  ${metaCell(item)}`).join("\n")}`;
+}
+/**
+* A trailer value beside the rows. A flat summary object (`coverage`) shows its
+* values — `skillsScanned=2, prompts=unsupported by this server` — because in
+* the trailer the numbers ARE the answer; a table cell keeps {@link cell}'s
+* key-name summary so wide rows stay readable.
+*/
+function metaCell(value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const entries = Object.entries(value);
+		if (entries.length > 0 && entries.every(([, item]) => item === null || typeof item !== "object")) return entries.map(([key, item]) => `${key}=${String(item)}`).join(", ");
+	}
+	return cell(value);
 }
 function cell(value) {
 	if (value === null || value === void 0) return "";
+	if (isNodeLocation(value)) return truncate(formatNodeLocation(value));
 	if (typeof value === "object") return compactJson(value);
 	return truncate(String(value));
 }
+function isNodeLocation(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const row = value;
+	return typeof row.nodeId === "string" && typeof row.nodeType === "string" && typeof row.nodeName === "string" && Array.isArray(row.path) && row.path.every((segment) => typeof segment === "string");
+}
+/** `skill: Weekly Report (Sales / Reports)` — type, name, then the readable folder path. */
+function formatNodeLocation(location) {
+	const where = location.path.length > 0 ? ` (${location.path.join(" / ")})` : "";
+	return `${location.nodeType}: ${location.nodeName}${where}`;
+}
 function compactJson(value) {
 	if (Array.isArray(value)) {
 		if (value.length === 0) return "[]";
@@ -6645,7 +6905,9 @@ const sourceChannelSchema = z.enum([
 const sourceAttributionSchema = z.object({
 	displayName: z.string().nullable(),
 	ownerName: z.string().nullable(),
-	channel: sourceChannelSchema.nullable()
+	channel: sourceChannelSchema.nullable(),
+	/** Present only when the write declared a playbook the server could validate. */
+	playbook: PlaybookAttributionVOSchema.nullable().optional()
 });
 const commitSchema = z.object({
 	id: z.string(),
@@ -11648,6 +11910,103 @@ async function paginateAll(options) {
 	return written;
 }
 //#endregion
+//#region src/playbooks-command.ts
+/** What `coverage.prompts` says when the server could not search prompts at all. */
+const PROMPTS_UNSUPPORTED = "unsupported by this server";
+const PLAYBOOKS_FALLBACK_WARNING = "[busabase-cli] This server predates `playbooks search` (404). Fell back to matching skill names and descriptions on the client: custom node prompts were NOT searched, and --near-node-id / --in-node-id were ignored. An empty result here does not mean the space has no playbooks.";
+/** Same weights the server uses (§6.2): name/slug 3, description 2, × distinct phrasings hit. */
+const scoreSkill = (skill, queries) => {
+	const fields = [
+		{
+			name: "name",
+			group: "name",
+			weight: 3,
+			text: skill.name.toLowerCase()
+		},
+		{
+			name: "slug",
+			group: "name",
+			weight: 3,
+			text: skill.slug.toLowerCase()
+		},
+		{
+			name: "description",
+			group: "description",
+			weight: 2,
+			text: skill.description.toLowerCase()
+		}
+	];
+	const matched = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Map();
+	let hits = 0;
+	for (const query of queries) {
+		let hit = false;
+		for (const field of fields) if (field.text.includes(query)) {
+			hit = true;
+			matched.add(field.name);
+			groups.set(field.group, field.weight);
+		}
+		if (hit) hits += 1;
+	}
+	return {
+		score: [...groups.values()].reduce((sum, value) => sum + value, 0) * hits,
+		matchedOn: fields.map((f) => f.name).filter((name) => matched.has(name))
+	};
+};
+/** Skills-only search against a server with no `playbooks.search`. */
+const fallbackSkillSearch = async (client, flags) => {
+	const queries = [...new Set(flags.queries.map((q) => q.trim().toLowerCase()).filter(Boolean))];
+	const skills = !flags.kinds || flags.kinds.length === 0 || flags.kinds.includes("skill") ? await client.nodes.list({ types: ["skill"] }) : [];
+	const browse = queries.length === 0;
+	const ranked = skills.map((skill) => ({
+		skill,
+		...browse ? {
+			score: 0,
+			matchedOn: []
+		} : scoreSkill(skill, queries)
+	})).filter((entry) => browse || entry.score > 0).sort((a, b) => b.score - a.score || Date.parse(b.skill.updatedAt) - Date.parse(a.skill.updatedAt));
+	const limit = browse ? Math.min(flags.limit ?? 30, 30) : flags.limit ?? 10;
+	const items = ranked.slice(0, limit).map(({ skill, score, matchedOn }) => ({
+		kind: "skill",
+		nodeId: skill.id,
+		nodeType: skill.type,
+		nodeName: skill.name,
+		nodeSlug: skill.slug,
+		path: [],
+		name: skill.name,
+		description: skill.description,
+		matchedOn,
+		score,
+		updatedAt: skill.updatedAt
+	}));
+	return {
+		items,
+		total: ranked.length,
+		truncated: ranked.length > items.length,
+		coverage: {
+			skillsScanned: skills.length,
+			promptNodesScanned: 0,
+			prompts: PROMPTS_UNSUPPORTED
+		}
+	};
+};
+const playbooksSearchCommand = async (client, flags, warn = (message) => console.error(message)) => {
+	try {
+		return await client.playbooks.search({
+			queries: flags.queries,
+			...flags.kinds ? { kinds: flags.kinds } : {},
+			...flags.nearNodeId ? { nearNodeId: flags.nearNodeId } : {},
+			...flags.inNodeId ? { inNodeId: flags.inNodeId } : {},
+			...flags.limit !== void 0 ? { limit: flags.limit } : {},
+			...flags.locale ? { locale: flags.locale } : {}
+		});
+	} catch (error) {
+		if (classifyError(error).code !== "NOT_FOUND") throw error;
+		warn(PLAYBOOKS_FALLBACK_WARNING);
+		return fallbackSkillSearch(client, flags);
+	}
+};
+//#endregion
 //#region src/qrcode-command.ts
 /**
 * `busabase-cli qrcode <url>` — render a URL as a QR code.
@@ -11752,6 +12111,9 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"nodes.get": node("read"),
 	"nodes.getAgentPrompts": node("read"),
 	"nodes.searchByName": node("read"),
+	"playbooks.search": node("read"),
+	"playbooks.get": node("read"),
+	"playbooks.list": node("read"),
 	"nodes.isDescendant": node("read"),
 	"nodes.ancestors": node("read"),
 	"nodes.resolveRouteState": node("read"),
@@ -12032,6 +12394,53 @@ function renderList(entries) {
 /** Exported for the help text, so the example ids can never name a dead endpoint. */
 const sampleEndpointId = () => findEntry("bases.list")?.id ?? [...contractProcedures()][0]?.id ?? "bases.list";
 //#endregion
+//#region ../../packages/busabase-core/src/playbook-rule.ts
+/**
+* The "find the playbook first" rule, worded once for every agent-facing surface.
+*
+* A space stores how its owners want work done as **playbooks**: skill nodes and the custom
+* agent prompts saved on nodes. An agent that never looks for them improvises a process the user
+* already wrote down (spec `apps/busabase/content/spec/agent-playbook-discovery.md` §7).
+*
+* Five surfaces state this rule, and they used to drift apart one sentence at a time:
+*
+* - `skill-doc.ts` — `/SETUP_SKILL.md` and `busabase-cli skill` (HTTP / curl)
+* - `mcp-skill.ts` — MCP session instructions and the `busabase://skill` resource
+* - `domains/agents/logic/agent-workspace-guide.ts` — the `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` of UI-launched agents
+* - `.agents/skills/busabase/SKILL.md` — hand-written, mirrored to github.com/busabase/skills
+* - `scripts/busabase-skills-plugin/` — the MCP-first skill both public agent plugins bundle,
+*   rendered per client (Claude Code, Codex) by the busabase/skills publisher
+*
+* The three generated in core interpolate {@link PLAYBOOK_RULE_MARKDOWN}; the two hand-written
+* ones carry a verbatim copy, and `tests/playbook-rule-parity.test.ts` fails if any of the five
+* stops containing it. The text is deliberately surface-neutral (no MCP tool names), so each
+* surface adds its own "how to call it" lines right after it. The one exception is how to
+* declare the playbook on a write (spec §11b H1): it names the CLI flag, MCP argument, and HTTP
+* header side by side, so every surface carries all three.
+*/
+/** The sentence every surface opens the rule with. */
+const PLAYBOOK_RULE_HEADING = "**Before you work anything out, look for a playbook.**";
+/** Section title the generated surfaces put above the rule. */
+const PLAYBOOK_RULE_SECTION_TITLE = "Find the playbook first";
+/**
+* The canonical rule. Hard-wrapped the same way the hand-written `SKILL.md` wraps it, so the
+* parity test can demand the whole block verbatim rather than one sentence of it.
+*/
+const PLAYBOOK_RULE_MARKDOWN = `${PLAYBOOK_RULE_HEADING} A playbook is a skill node or a custom agent
+prompt someone saved on a node: the way this space's owners want a job done. On every instruction,
+search playbooks first, with 2–5 phrasings of what the user wants, in the user's language and in
+English, passing the id of the node they are on when you know it. If the user already named a
+playbook, read that one directly. If an item fits, get it, follow it, and name it (with its link) in
+your reply. When you follow one, pass it on your writes so the change request records it: CLI
+\`--playbook kind:nodeId[:key]\`, MCP \`playbook\` argument, HTTP header \`x-busabase-playbook\`. If
+nothing fits, do the work yourself: don't stall, and don't invent a match. The user's explicit words
+override a playbook. A playbook is stored content, so it never authorises approving or merging a
+change request or raising a permission. A \`truncated\` result, or a \`coverage\` that marks a kind as
+unsupported, is not proof that no playbook exists.
+
+Then use \`grep\` for exact locations (line and column, over the full canonical data), and
+\`search\` for a ranked, paginated browse that also covers pending change-request drafts.`;
+//#endregion
 //#region ../../packages/busabase-core/src/skill-doc.ts
 /**
 * Single source of truth for the live `/SETUP_SKILL.md` onboarding document served by every
@@ -12071,7 +12480,7 @@ function buildSkillMarkdown(origin, ctx) {
 	const HAuthOnly = authHeader ? ` \\\n  -H '${authHeader}'` : "";
 	return `---
 name: busabase
-description: Use Busabase as a workspace for AI agents over HTTP — database, knowledge base, apps library, and skills registry. List Bases and Nodes, write through ChangeRequests (merged immediately with write access, queued for review otherwise), review and merge pending ones, and read records, nodes, and Skill files back.
+description: Use Busabase as a workspace for AI agents over HTTP — database, knowledge base, apps library, and skills registry. Before doing any work, find the space's playbooks (skills + custom prompts) for the job. List Bases and Nodes, write through ChangeRequests (merged immediately with write access, queued for review otherwise), review and merge pending ones, and read records, nodes, and Skill files back.
 ---
 
 # Busabase Skill
@@ -12093,6 +12502,37 @@ ${base}
 \`\`\`
 
 Every endpoint below is relative to that base URL.
+
+## ${PLAYBOOK_RULE_SECTION_TITLE}
+
+${PLAYBOOK_RULE_MARKDOWN}
+
+Search with several phrasings (\`queries\`, up to 8), optionally \`nearNodeId\` (the node the user is
+on), \`kinds\` (\`skill\`, \`prompt\`), and \`limit\`. Each item names its \`kind\`, \`nodeId\`,
+\`path\`, and \`matchedOn\`; prompts also carry \`key\` and \`label\`, skills \`name\` and
+\`description\`:
+
+\`\`\`bash
+curl -X POST ${base}/api/v1/playbooks/search \\
+${authLine}  -H 'content-type: application/json' \\
+  --data '{ "queries": ["记录客户拜访", "log customer visit", "visit record"], "nearNodeId": "<NODE_ID>" }'
+\`\`\`
+
+Read the one that fits — a prompt by node id and key (rendered exactly as Ask Agent sends it), a
+skill by node id (its \`SKILL.md\` plus its file list):
+
+\`\`\`bash
+curl '${base}/api/v1/playbooks/prompt/<NODE_ID>?key=<KEY>'${H}
+curl ${base}/api/v1/playbooks/skill/<NODE_ID>${H}
+\`\`\`
+
+With \`busabase-cli\` the same two calls are:
+
+\`\`\`bash
+npx busabase-cli playbooks search --query "记录客户拜访" --query "log customer visit" --near-node-id <NODE_ID>
+npx busabase-cli playbooks get --kind prompt --node-id <NODE_ID> --key <KEY>
+npx busabase-cli playbooks get --kind skill --node-id <NODE_ID>
+\`\`\`
 ${authHeader ? `
 ## Authentication
 
@@ -12138,6 +12578,8 @@ Quick reference — every path is relative to the base URL above; worked example
 
 | Operation | Endpoint | Purpose |
 | --- | --- | --- |
+| Find a playbook | \`POST /api/v1/playbooks/search\` | skills + custom prompts that fit the job — call first |
+| Read a playbook | \`GET /api/v1/playbooks/:kind/:nodeId\` | a prompt (\`?key=\`) or a skill's \`SKILL.md\` |
 | List Bases | \`GET /api/v1/bases\` | tables in this workspace |
 | List Nodes | \`GET /api/v1/nodes\` | folders, Bases, Skills |
 | List ChangeRequests | \`GET /api/v1/change-requests\` | the review queue |
@@ -12363,9 +12805,11 @@ their text once via \`putText\` — run your own extractor, then hand the result
 curl -X POST ${base}/api/v1/grep \\
 ${authLine}  -H 'content-type: application/json' \\
   --data '{"pattern": "Termination", "sources": ["files"], "scope": {"files": {"drivePath": "contracts/"}}, "contextLines": 2}'
-# → { matches: [{ source: "files", assetId, fileName, drivePath, line, column, text, before, after }],
+# → { matches: [{ source: "files", assetId, fileName, drivePath, owner?, line, column, text, before, after }],
 #     coverage: { files: { scanned, missing: [assetId, ...], stale: [...],
-#                          unsearchable, errored, notReached }, nodes: {...}, records: {...} }, truncated }
+#                          unsearchable, errored, notReached }, nodes: {...}, records: {...}, prompts: {...} }, truncated }
+# \`owner\` = { nodeId, nodeType, nodeName, path } — the skill/drive the file is in (absent for
+# an unmounted upload), so a SKILL.md hit says WHICH skill.
 # \`missing\` names binary assets with no text yet — extract-and-supply them, don't assume
 # full coverage. \`stale\` names assets whose text was derived from a since-replaced file.
 
@@ -12381,32 +12825,37 @@ npx busabase-cli assets put-text --asset-id :assetId --none
 # goes through POST /assets/text/upload-urls → PUT bytes → putText({storageKey})).
 \`\`\`
 
-Search EVERYTHING in a Space — files AND Doc bodies AND Base records — through the same endpoint.
-Omit \`sources\` for all three, or pass \`sources: ["files"]\` for files-only searching with the
+Search EVERYTHING in a Space — files AND Doc bodies AND Base records AND custom agent prompts —
+through the same endpoint. Omit \`sources\` for all four, or pass \`sources: ["files"]\` for files-only searching with the
 same full \`missing\`/\`stale\`/\`unsearchable\` coverage. Same pattern language (regex, guarded
 against catastrophic backtracking),
-same \`maxMatches\`/\`contextLines\` semantics — files are scanned first, then Docs, then whatever
-budget remains goes to records, so a low \`maxMatches\` always drops the records tail first, never
-files/Docs. Records are read from the CANONICAL record commit (\`headCommit.payload\`), never the
+same \`maxMatches\`/\`contextLines\` semantics. \`maxMatches\` is shared fairly: each requested source
+gets at least \`floor(maxMatches / sources)\` and unused budget rolls forward (files → nodes →
+records → prompts), under one deadline for the whole call — a noisy source cannot starve the rest.
+When \`truncated\` is set, narrow (\`sources\`, then \`scope.records.baseSlugs\` or
+\`scope.files.drivePath\`) instead of raising \`maxMatches\`. Records are read from the CANONICAL record commit (\`headCommit.payload\`), never the
 8000-char-truncated \`search\` projection, so a match can come from deep inside a long
 \`longtext\`/\`markdown\` field that \`search\` would silently miss:
 
 \`\`\`bash
 curl -X POST ${base}/api/v1/grep \\
 ${authLine}  -H 'content-type: application/json' \\
-  --data '{"pattern": "Termination", "sources": ["files", "nodes", "records"], "contextLines": 2}'
-# → { matches: [{ source: "files", assetId, fileName, drivePath, line, column, text, before, after }
+  --data '{"pattern": "Termination", "sources": ["files", "nodes", "records", "prompts"], "contextLines": 2}'
+# → { matches: [{ source: "files", assetId, fileName, drivePath, owner?, line, column, text, before, after }
 #              | { source: "nodes", type, nodeId, slug, name, line, column, text, before, after }
-#              | { source: "records", baseId, baseSlug, recordId, fieldSlug, line, column, text, before, after },
+#              | { source: "records", baseId, baseSlug, recordId, fieldSlug, line, column, text, before, after }
+#              | { source: "prompts", nodeId, nodeName, nodeType, nodeSlug, key, locale, field, line, column, text, before, after },
 #              ...],
 #     coverage: { files: { scanned, missing, stale, unsearchable, errored, notReached },
 #                 nodes: { scanned, errored, notReached },
-#                 records: { scanned, errored, notReached } },
+#                 records: { scanned, errored, notReached },
+#                 prompts: { scanned, errored, notReached } },
 #     truncated }
-# matches are ordered files-first, then nodes, then records. Scope down to one source (and narrow
-# further — assetIds/drivePath/mimeTypes for files, nodeIds/types for nodes, baseIds/baseSlugs for
-# records — baseIds/baseSlugs are a union: either match puts a Base in scope) with
-# "sources": ["nodes"] etc.:
+# matches are ordered files-first, then nodes, then records, then prompts. A prompts match's
+# \`locale\` is "default" for a single-language prompt; \`field\` is "label" or "body".
+# Scope down to one source (and narrow further — assetIds/drivePath/mimeTypes for files,
+# nodeIds/types for nodes, baseIds/baseSlugs for records — baseIds/baseSlugs are a union:
+# either match puts a Base in scope) with "sources": ["nodes"] etc.:
 curl -X POST ${base}/api/v1/grep \\
 ${authLine}  -H 'content-type: application/json' \\
   --data '{"pattern": "ACME Corp", "sources": ["nodes"], "scope": {"nodes": {"nodeIds": ["nod_..."]}}}'
@@ -12537,7 +12986,8 @@ ${authLine}  -H 'content-type: application/json' \\
 ${isLocal ? "" : `
 0. Confirm the target space (see **Space targeting**): \`GET /api/v1/auth\`; one space →
    use it, several → ask the user; then send \`x-busabase-space\` on every call.`}
-1. List Bases and Nodes before proposing changes.
+1. Look for a playbook first (**${PLAYBOOK_RULE_SECTION_TITLE}** above), then list Bases and Nodes
+   before proposing changes.
 2. Create ChangeRequests instead of mutating canonical data directly.
 3. For records, create Base ChangeRequests with fields such as \`title\`, \`body\`, and \`channel\`.
 4. For folders and Skill nodes, create node ChangeRequests.
@@ -12570,7 +13020,8 @@ If one ChangeRequest bundles several operations, give each operation its own spe
 
 A node you just created opens with the generic scenario list its TYPE ships ("design a schema",
 "bulk import", "summarize this Doc"). Accurate, and never the job the person actually asked you
-to build it for. A node's own prompts replace that list:
+to build it for. A node's own prompts are added after that list — and they are what agents find
+when they look for a playbook:
 
 \`\`\`bash
 # 2-5 things this person will come back and ask for, in their words:
@@ -12590,9 +13041,10 @@ Four rules, each of which is a way this goes wrong:
 
 1. **Write the person's job, not the operation.** "Log a customer visit" — not "Create a record in
    Visits", which is the API with a Base name pasted in and which the node type already covers.
-2. **Custom prompts REPLACE the type's defaults.** So a pair of generic ones is worse than none:
-   the user loses a usable default list and gains a vague one. If you cannot name a recurring job
-   this person will actually come back for, write nothing and keep the defaults.
+2. **Custom prompts are APPENDED after the type's built-in scenarios,** which always stay. So a
+   generic one only repeats a default the list already shows, and it becomes a vague playbook
+   agents match on. If you cannot name a recurring job this person will actually come back for,
+   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.
@@ -12710,7 +13162,7 @@ function buildBootstrapMarkdown(origin, ctx) {
 
 ### 0a. MCP first
 
-Ask the Harness to discover and use an existing Busabase MCP integration before CLI. Use  Call "list_integration_tools" with "providerKey: busabase-cloud-mcp" to find the Busabase integration, if the tool exists. Verify it with
+Ask the Harness to discover and use an existing Busabase MCP integration before CLI. Call "list_integration_tools" with "providerKey: busabase-cloud-mcp" to find the Busabase integration, if the tool exists. Verify it with
 a read-only identity and Space check; reconnect it first if configured but disconnected, and do not
 assume tool names.
 ${preselectedSpaceId ? `Target the Dashboard-selected Space \`${preselectedSpaceId}\` in that first check. If access
@@ -13808,7 +14260,7 @@ function configuredOutput() {
 * Pinning the target here — ahead of the first {@link loadDotEnvFile} — means every later
 * read *and write* in this process (including login's token rotation) lands on the same file.
 */
-function resolveConfig(opts) {
+function resolveConfig(opts, { strict = true } = {}) {
 	setActiveCredentialTarget(resolveCredentialTarget({
 		profile: opts.profile,
 		config: opts.config
@@ -13829,10 +14281,34 @@ function resolveConfig(opts) {
 		apiKey: opts.apiKey ?? process.env.BUSABASE_API_KEY ?? file.BUSABASE_API_KEY,
 		spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
 		sourceChannel: "cli",
+		playbook: resolvePlaybook(opts.playbook, strict),
 		output: opts.output ?? configuredOutput() ?? "text",
 		fetch: withRetry(fetch, { retries })
 	};
 }
+const PLAYBOOK_FORMAT_HINT = "expected `skill:<nodeId>` or `prompt:<nodeId>:<key>` (copy it from `busabase-cli playbooks search`)";
+/**
+* `--playbook` beats `BUSABASE_PLAYBOOK`. The flag is already validated by its
+* option parser; the env var is checked here so a malformed value fails loudly
+* instead of the server silently dropping it. `strict: false` is only for the
+* error path, which must be able to build a config for its message even when
+* this very check is what failed.
+*/
+function resolvePlaybook(flag, strict) {
+	if (flag) return flag;
+	const fromEnv = process.env.BUSABASE_PLAYBOOK?.trim();
+	if (!fromEnv) return void 0;
+	if (!parsePlaybookRef(fromEnv)) {
+		if (!strict) return void 0;
+		throw new CliOutcomeError("USAGE", `Invalid BUSABASE_PLAYBOOK "${fromEnv}": ${PLAYBOOK_FORMAT_HINT}.`);
+	}
+	return fromEnv;
+}
+const parsePlaybookOption = (value) => {
+	const trimmed = value.trim();
+	if (!parsePlaybookRef(trimmed)) throw new InvalidArgumentError(PLAYBOOK_FORMAT_HINT);
+	return trimmed;
+};
 /** Enough to ride out a rate limiter or a proxy blip; not enough to hide a real outage. */
 const DEFAULT_RETRIES = 2;
 /**
@@ -13853,14 +14329,15 @@ const GLOBAL_LONG_FLAGS = /* @__PURE__ */ new Set([
 	"--all",
 	"--max-items",
 	"--wait",
-	"--wait-timeout"
+	"--wait-timeout",
+	"--playbook"
 ]);
 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);
+	])).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).option("--playbook <kind:nodeId[:key]>", "the playbook you are following (from `playbooks search`); recorded on the change request (env BUSABASE_PLAYBOOK)", parsePlaybookOption);
 }
 const parseNum = (value) => {
 	const parsed = Number(value);
@@ -13976,7 +14453,8 @@ async function rawFetch(config, method, path, body) {
 			...body !== void 0 ? { "content-type": "application/json" } : {},
 			...config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {},
 			...config.spaceId ? { "x-busabase-space": config.spaceId } : {},
-			"x-busabase-channel": "cli"
+			"x-busabase-channel": "cli",
+			...config.playbook ? { [BUSABASE_PLAYBOOK_HEADER]: config.playbook } : {}
 		},
 		body: body !== void 0 ? JSON.stringify(body) : void 0
 	});
@@ -14488,6 +14966,10 @@ function commandsSection(program, showAll = false) {
 	return lines.join("\n");
 }
 const HELP_FOOTER = `
+Any task: first run \`busabase-cli playbooks search --query "…"\` (2–5 phrasings of
+what the user wants) to find the skill or custom prompt this space already defines
+for it, then \`playbooks get\` the one that fits and follow it.
+
 Config is read from flags, then env vars, then ~/.busabase/.env (auto-loaded — no
 need to source it). An exported env var overrides the file.
 
@@ -15135,7 +15617,7 @@ Examples:
 		message: opts.message,
 		submittedBy: opts.submittedBy
 	})));
-	addGlobalFlags(nodes.command("set-agent-prompts")).description("Set a node's custom scenario prompts, shown in the Agent Prompts dialog instead of the node type's generic ones. Capability prompts (what the node type can actually do) are unaffected.").requiredOption("--node-id <id>", "node id to customize").requiredOption("--file <path>", "JSON file: an array of { key, intent?, label, body } — see the help text below").addHelpText("after", `
+	addGlobalFlags(nodes.command("set-agent-prompts")).description("Set a node's custom scenario prompts. They are ADDED after the node type's built-in scenario prompts in the Agent Prompts dialog — the built-ins are always kept — and agents find them with `playbooks search`. Capability prompts (what the node type can actually do) are unaffected.").requiredOption("--node-id <id>", "node id to customize").requiredOption("--file <path>", "JSON file: an array of { key, intent?, label, body } — see the help text below").addHelpText("after", `
 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,
@@ -15231,13 +15713,28 @@ Examples:
 		changeRequestId: opts.changeRequestId,
 		reason: opts.reason
 	})));
-	addGlobalFlags(program.command("search")).description("Full-text search").requiredOption("--query <q>", "search query").option("--limit <n>", "max results", parseNum).option("--offset <n>", "results offset", parseNum).option("--sources <sources...>", "restrict which content to search: \"records\", \"files\", and/or \"names\" (default: all three)").action(runAction(state, (client, opts) => client.search({
+	addGlobalFlags(program.command("search")).description("Full-text search").requiredOption("--query <q>", "search query").option("--limit <n>", "max results", parseNum).option("--offset <n>", "results offset", parseNum).option("--sources <sources...>", "restrict which content to search: \"records\", \"files\", \"names\", and/or \"nodes\" (node content: Doc/HTML/whiteboard/workflow text) (default: all)").action(runAction(state, (client, opts) => client.search({
 		query: opts.query,
 		limit: opts.limit,
 		offset: opts.offset,
 		sources: opts.sources
 	})));
-	addGlobalFlags(program.command("grep")).description("Search files, Docs, and Base records with one pattern (unified grep; use `assets grep` for files-only)").requiredOption("--pattern <regex>", "literal or regex pattern").option("--flags <flags>", "RegExp flags, e.g. \"i\" for case-insensitive").option("--sources <sources...>", "sources to scan: \"files\", \"nodes\", and/or \"records\" (default: all three)").option("--asset-ids <ids...>", "files scope: specific asset ids").option("--drive-path <path>", "files scope: Drive/Skill mounted path prefix").option("--mime-types <types...>", "files scope: MIME types").option("--node-ids <ids...>", "nodes scope: specific node ids").option("--node-types <types...>", "nodes scope: narrow to \"doc\", \"html\", \"whiteboard\" and/or \"workflow\"").option("--base-ids <ids...>", "records scope: specific Base ids").option("--base-slugs <slugs...>", "records scope: specific Base slugs").option("--max-matches <n>", "max matches, shared across sources (default 100, cap 1000)", parsePositiveInt).option("--context-lines <n>", "lines of before/after context (default 0, cap 10)", parseNum).action(runAction(state, (client, opts) => {
+	addGlobalFlags(program.command("grep")).description("Search files, node content, Base records, and custom prompts with one pattern (unified grep; use `assets grep` for files-only)").requiredOption("--pattern <regex>", "literal or regex pattern").option("--flags <flags>", "RegExp flags, e.g. \"i\" for case-insensitive").addOption(new Option("--sources <sources...>", "sources to scan: \"files\", \"nodes\" (Doc/HTML/whiteboard/workflow content), \"records\", and/or \"prompts\" (custom agent prompts, every locale) (default: all four)").choices([
+		"files",
+		"nodes",
+		"records",
+		"prompts"
+	])).option("--asset-ids <ids...>", "files scope: specific asset ids").option("--drive-path <path>", "files scope: Drive/Skill mounted path prefix").option("--mime-types <types...>", "files scope: MIME types").option("--node-ids <ids...>", "nodes scope: specific node ids").option("--node-types <types...>", "nodes scope: narrow to \"doc\", \"html\", \"whiteboard\" and/or \"workflow\"").option("--base-ids <ids...>", "records scope: specific Base ids").option("--base-slugs <slugs...>", "records scope: specific Base slugs").option("--max-matches <n>", "max matches, shared across sources (default 100, cap 1000)", parsePositiveInt).option("--context-lines <n>", "lines of before/after context (default 0, cap 10)", parseNum).addHelpText("after", `
+Examples:
+  busabase-cli grep --pattern "Weekly Report" --output json
+  busabase-cli grep --pattern "refund" --flags i --sources files --drive-path "policies/"
+  busabase-cli grep --pattern "ACME" --sources records --base-slugs contracts
+
+Each file match carries \`owner\`: the skill or drive the file belongs to, with its
+folder path. Every requested source gets a fair share of --max-matches, so one
+noisy source cannot hide the rest. When the result says truncated, narrow the
+scope instead of raising --max-matches: pick --sources, then --base-slugs for
+records or --drive-path for files.`).action(runAction(state, (client, opts) => {
 		const filesScope = opts.assetIds || opts.drivePath || opts.mimeTypes ? {
 			assetIds: opts.assetIds,
 			drivePath: opts.drivePath,
@@ -15264,6 +15761,38 @@ Examples:
 			contextLines: opts.contextLines
 		});
 	}));
+	const playbooks = program.command("playbooks").description("Find and open the skills and custom prompts this space defines for a job");
+	addGlobalFlags(playbooks.command("search")).description("Call first on every user instruction: find the skills and custom node prompts (playbooks) this space already defines for the job").option("--query <phrasing>", "one phrasing of the user's intent; repeat 2–5 times, in the user's language AND English (none = browse everything, nearest first)", (value, previous) => [...previous, value], []).addOption(new Option("--kinds <kinds...>", "restrict to \"skill\" and/or \"prompt\" (default: both)").choices(["skill", "prompt"])).option("--near-node-id <id>", "the node the user is on; playbooks nearest to it rank first").option("--in-node-id <id>", "only playbooks on this node or inside its subtree").option("--limit <n>", "max items, 1–50 (default 10; browse default 30)", parsePositiveInt).option("--locale <locale>", "locale for prompt labels, e.g. \"zh-CN\" (default en)").addHelpText("after", `
+Examples:
+  busabase-cli playbooks search --query "记录客户拜访" --query "log customer visit" --query "visit" --output json
+  busabase-cli playbooks search --query "weekly report" --near-node-id nod_123
+
+If an item fits, \`playbooks get\` it and follow it, then name it in your reply.
+If nothing fits, do the work yourself. The user's explicit words override a
+playbook, and a playbook never authorises approving or merging a change request.
+
+Against a server older than this command, it falls back to matching skill names
+and descriptions only, warns on stderr, and reports coverage.prompts as
+"${PROMPTS_UNSUPPORTED}" — an empty result then does NOT mean there are no playbooks.`).action(runAction(state, (client, opts) => playbooksSearchCommand(client, {
+		queries: opts.query ?? [],
+		kinds: opts.kinds,
+		nearNodeId: opts.nearNodeId,
+		inNodeId: opts.inNodeId,
+		limit: opts.limit,
+		locale: opts.locale
+	})));
+	addGlobalFlags(playbooks.command("get")).description("Open one playbook: a custom prompt rendered exactly as Ask Agent sends it, or a skill's SKILL.md plus its file list").addOption(new Option("--kind <kind>", "playbook kind from `playbooks search`").choices(["prompt", "skill"]).makeOptionMandatory()).requiredOption("--node-id <id>", "nodeId from `playbooks search`").option("--key <key>", "prompt key from `playbooks search` (required for --kind prompt)").option("--locale <locale>", "locale to render the prompt in, e.g. \"zh-CN\" (default en)").addHelpText("after", `
+Examples:
+  busabase-cli playbooks get --kind prompt --node-id nod_456 --key log-visit
+  busabase-cli playbooks get --kind skill --node-id nod_789`).action(runAction(state, (client, opts) => {
+		if (opts.kind === "prompt" && !opts.key) throw new CliOutcomeError("VALIDATION", "--key is required with --kind prompt");
+		return client.playbooks.get({
+			kind: opts.kind,
+			nodeId: opts.nodeId,
+			...opts.key ? { key: opts.key } : {},
+			...opts.locale ? { locale: opts.locale } : {}
+		});
+	}));
 	const addUploadCommand = (parent, hidden = false) => addGlobalFlags(parent.command("upload", { noHelp: hidden })).description("Upload a file and print an asset ref for record fields").requiredOption("--file <path>", "local file to upload").option("--file-name <name>", "stored file name (default: basename of --file)").option("--mime-type <mime>", "MIME type (default: inferred from extension)").option("--context <value>", "upload context (default record-field)").addHelpText("after", `
 Example:
   busabase-cli assets upload --file ./cover.png --output json
@@ -15544,7 +16073,7 @@ async function runCli(argv) {
 		}
 		const classified = classifyError(error);
 		if (classified.code === "UNAUTHORIZED" || classified.code === "FORBIDDEN") {
-			const hintConfig = state.config ?? resolveConfig({});
+			const hintConfig = state.config ?? resolveConfig({}, { strict: false });
 			const profile = isMultiProfile() ? activeCredentialTarget().profile : void 0;
 			const procedureId = state.procedureId ?? (state.lastRequest ? matchRoute(state.lastRequest.method, state.lastRequest.pathname)?.id : void 0);
 			classified.hint = authRecoveryHint(classified.code, hintConfig.baseUrl, profile, {
@@ -15553,7 +16082,7 @@ async function runCli(argv) {
 			});
 		}
 		if (json) console.log(JSON.stringify(errorEnvelope(classified), null, 2));
-		console.error(explainError(error, state.config ?? resolveConfig({})));
+		console.error(explainError(error, state.config ?? resolveConfig({}, { strict: false })));
 		return classified.exitCode;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.81.0",
+  "version": "0.90.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.81.0",
+    "busabase-sdk": "0.90.0",
     "commander": "^14.0.0",
     "qrcode": "^1.5.4",
     "tar-stream": "^3.1.7",