busa-cli 0.60.0 → 0.71.0

package/bin/busabase-cli.mjs

@@ -24,7 +24,15 @@ try {
     if (!Array.isArray(delegatedArgv) || delegatedArgv.some((arg) => typeof arg !== "string")) {
       throw new Error("BUSABASE_CLI_DELEGATED_ARGV must be a JSON string array.");
     }
-    process.exit(await runCli(delegatedArgv));
+    const delegatedExit = await runCli(delegatedArgv);
+    // process.exit() drops whatever stdout has not flushed, and stdout is async when
+    // it is a pipe — so a large `--output json` body would arrive truncated at one
+    // pipe buffer. Inlined rather than imported from dist: this file is the entry
+    // point and must keep working even when dist is mid-build. See src/flush-stdio.ts.
+    for (const stream of [process.stdout, process.stderr]) {
+      if (stream.writableLength > 0) await new Promise((done) => stream.write("", done));
+    }
+    process.exit(delegatedExit);
   }
   await import(builtCli.href);
 } catch (error) {

package/dist/cli.js

@@ -1,9 +1,45 @@
 #!/usr/bin/env node
-import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-bQ1VIBLc.js";
+import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-BkaaGFK_.js";
+//#region src/flush-stdio.ts
+/**
+* Wait for stdout/stderr to reach the other side before the process is torn down.
+*
+* `process.exit()` discards whatever is still buffered. That is harmless when stdout
+* is a file or a TTY — Node writes those synchronously — but a PIPE is asynchronous,
+* so exiting immediately after a large `console.log` delivers only what happened to
+* fit in the pipe buffer and drops the rest, with a zero exit code either way.
+*
+* The symptom is brutal to diagnose because it depends on the caller, not the command:
+*
+*     busabase-cli skills read-file … --output json > body.json   # 41970 bytes
+*     busabase-cli skills read-file … --output json | jq .content #  8192 bytes
+*
+* and 8192 is one pipe buffer, so the JSON simply stops mid-string. Anyone piping a
+* large skill or record body into a parser gets a parse error that reads like a server
+* problem. It has been misattributed to stale CLI versions before; the version is
+* irrelevant, the destination is everything.
+*
+* Writing an empty chunk with a callback is the portable way to ask "is everything I
+* queued delivered?" — the callback fires after the stream has flushed what preceded
+* it. A stream that is already drained resolves without queueing anything.
+*/
+const flush = (stream) => new Promise((resolve) => {
+	if (stream.writableLength === 0) {
+		resolve();
+		return;
+	}
+	stream.write("", () => resolve());
+});
+const flushStdio = async () => {
+	await flush(process.stdout);
+	await flush(process.stderr);
+};
+//#endregion
 //#region src/cli.ts
 const exitCode = await runCli(process.argv.slice(2));
 const notice = await checkForUpdate("busabase-cli", pkgVersion());
 if (notice) console.error(notice);
+await flushStdio();
 process.exit(exitCode);
 //#endregion
 export {};

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

package/dist/{run-bQ1VIBLc.js → run-BkaaGFK_.js}

@@ -1420,22 +1420,34 @@ const formNodeType = {
 	label: "Form",
 	icon: "form",
 	/**
-	* `hidden` until a Form can be created from a create surface at all.
+	* No longer `hidden`. The two conditions that hid it are both met:
 	*
-	* `busabase_forms.target_base_id` is NOT NULL and `form` registers no
-	* `node_create` materializer, so a Form built through the generic New-item
-	* flow (which only collects name/slug/description) is a node row with no form
-	* config behind it — it opens to a dead end, every time, for everyone. The
-	* type stays fully `creatable` so `forms.create` (which does take a target
-	* Base) and the REST/MCP surface are untouched; it just no longer offers an
-	* entry point that cannot succeed. Drop this once the New-item flow asks for
-	* the target Base and a materializer writes the config row.
+	* 1. The New-item flow ASKS FOR THE TARGET BASE — `create-node-modal.tsx`
+	*    renders a "Writes into" Base picker (plus the field checklist) whenever
+	*    `form` is the selected type, and keeps its submit disabled until one is
+	*    chosen, the same way it already does for `file` and its asset.
+	* 2. A MATERIALIZER WRITES THE CONFIG ROW — `materializeFormNode`
+	*    (busabase-core `domains/form/logic/form-ops.ts`) inserts the
+	*    `busabase_forms` row inside the merge transaction, from the
+	*    `node_create` operation's `metadata.targetBaseId` / `metadata.formBindings`.
+	*    Both create paths run it, so a Form merged after review is configured
+	*    exactly like one created immediately.
+	*
+	* A Form that still arrives unconfigured (an API caller that sent only the
+	* generic node fields) is no longer a dead end either: the detail view's
+	* "not set up yet" state now carries a "Connect this form to a Base" action.
+	*
+	* `hidden` is read by THREE create surfaces — web's `create-node-modal.tsx`,
+	* `node-agent-prompts.ts`, and React Native's
+	* `apps/busabase-mobile/.../CreateNodeModal.tsx`. Mobile has no Base picker,
+	* so it names `form` in its own `UNSUPPORTED_TYPES` set (alongside `file`,
+	* which is excluded there for the same "can't collect the required input"
+	* reason) rather than re-creating the dead end on another platform.
 	*/
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
-		publicAccess: "submit",
-		hidden: true
+		publicAccess: "submit"
 	},
 	operations: []
 };
@@ -1710,18 +1722,10 @@ const writeAgentPrompts = async (client, type, result, agentPrompts) => {
 			nextStep: "Once the change request merges: busabase-cli nodes set-agent-prompts --node-id <nodeId> --file prompts.json"
 		}
 	};
-	try {
-		await client.nodes.updateAgentPrompts({
-			nodeId,
-			agentPrompts
-		});
-	} catch (error) {
-		if ((isRecord(error) ? error.status : void 0) !== 404) throw error;
-		await client.nodes.updateMetadata({
-			nodeId,
-			metadata: { agentPrompts }
-		});
-	}
+	await client.nodes.updateAgentPrompts({
+		nodeId,
+		agentPrompts
+	});
 	return {
 		...isRecord(result) ? result : { result },
 		agentPromptsWrite: {
@@ -6138,6 +6142,7 @@ const fieldTypeSchema = z.enum([
 	"html",
 	"attachment",
 	"relation",
+	"member",
 	"number",
 	"date",
 	"checkbox",
@@ -6244,8 +6249,7 @@ const baseSchema = z.object({
 		requiredApprovals: z.number()
 	}),
 	createdAt: z.string(),
-	fields: z.array(baseFieldSchema),
-	metadata: z.record(z.string(), z.unknown()).default({})
+	fields: z.array(baseFieldSchema)
 });
 z.object({
 	parentNodeId: z.string().optional().describe("Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."),
@@ -6495,6 +6499,25 @@ z.object({
 	expiresAt: z.string().nullable(),
 	updatedAt: z.string()
 });
+z.object({
+	nodeId: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	type: z.enum(NODE_TYPES),
+	icon: NodeIconSchema.nullable().default(null),
+	capability: z.enum(["read", "submit"]),
+	hasPassword: z.boolean(),
+	expiresAt: z.string().nullable(),
+	/**
+	* When this share ROW was first created — NOT "public continuously since".
+	* `disableNodeShare` flips `scope` to `"none"` and keeps the row, so a node
+	* that was shared, revoked, and shared again still reports the original
+	* date. There is no column recording when `scope` last became `"public"`,
+	* so the UI says "first shared {time}" rather than claiming an exposure
+	* window the data cannot support. Adding that column is the follow-up.
+	*/
+	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."),
@@ -6877,6 +6900,36 @@ z.object({
 	*/
 	contentTruncated: z.boolean().default(false)
 });
+z.discriminatedUnion("event", [
+	z.object({
+		event: z.literal("result_click"),
+		sessionId: z.string().uuid(),
+		surface: z.enum(["quick", "advanced"]),
+		position: z.number().int().min(1).max(100),
+		resultKind: z.enum([
+			"record",
+			"change_request",
+			"base",
+			"file",
+			"node"
+		])
+	}).strict(),
+	z.object({
+		event: z.literal("quick_to_advanced"),
+		sessionId: z.string().uuid(),
+		surface: z.literal("quick"),
+		resultCount: z.number().int().min(0).max(100)
+	}).strict(),
+	z.object({
+		event: z.literal("results_shown"),
+		sessionId: z.string().uuid(),
+		surface: z.enum(["quick", "advanced"]),
+		resultCount: z.number().int().min(0).max(100),
+		durationMs: z.number().int().min(0).max(12e4),
+		hasMore: z.boolean()
+	}).strict()
+]);
+z.object({ accepted: z.literal(true) });
 z.object({
 	kind: z.enum([
 		"change_request.created",
@@ -7101,6 +7154,8 @@ const SearchSortSchema = z.enum([
 ]);
 z.object({
 	query: z.string().default("").describe("Full-text query. An empty string matches nothing."),
+	mode: z.enum(["quick", "full"]).optional().default("full").describe("Search depth. `quick` skips live file-body scans for typeahead; `full` preserves complete search behavior."),
+	surface: z.enum(["quick", "advanced"]).optional().describe("Optional first-party UI surface for aggregate quality metrics. API/CLI callers should omit it."),
 	limit: z.coerce.number().int().min(1).max(100).optional().default(20).describe("Results per page. Capped at 100; note the default is 20, not 50."),
 	offset: z.coerce.number().int().min(0).optional().default(0).describe("0-indexed skip count. This endpoint pages by offset, not by cursor."),
 	/**
@@ -7197,7 +7252,21 @@ z.object({
 	/** Cloud only: the server created this user's first Space during this exact request. */
 	createdSpace: z.boolean().optional(),
 	/** Cloud only: this auto-created Space still needs its idempotent starter initialization. */
-	bootstrapRequired: z.boolean().optional()
+	bootstrapRequired: z.boolean().optional(),
+	/** Cloud only: effective permission ceiling of the credential used for this request. */
+	credentialPermissionLevel: z.enum([
+		"read",
+		"changeRequest",
+		"write",
+		"manage"
+	]).optional(),
+	/** Cloud only: credential ceiling capped by the selected Space membership role. */
+	effectivePermissionLevel: z.enum([
+		"read",
+		"changeRequest",
+		"write",
+		"manage"
+	]).optional()
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
@@ -11674,7 +11743,9 @@ const workspace = (level) => ({
 */
 const PROCEDURE_PERMISSION_POLICY = {
 	"auth.verify": workspace("read"),
+	"spaces.members": workspace("read"),
 	search: node("read"),
+	"searchMetrics.report": node("read"),
 	grep: node("read"),
 	"nodes.list": node("read"),
 	"nodes.get": node("read"),
@@ -11747,6 +11818,7 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"embedLinks.create": workspace("manage"),
 	"embedLinks.list": workspace("manage"),
 	"embedLinks.revoke": workspace("manage"),
+	"nodes.share.list": workspace("manage"),
 	"nodes.listFavorites": node("read"),
 	"auditEvents.list": node("read"),
 	"activity.listPaged": node("read"),
@@ -11787,7 +11859,9 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"agents.catalog": workspace("manage"),
 	"agents.connections.list": workspace("manage"),
 	"agents.disconnect": workspace("manage"),
+	"agents.deleteHistory": workspace("manage"),
 	"agents.sessions.list": workspace("manage"),
+	"agents.sessions.listPaged": workspace("manage"),
 	"agents.sessions.create": workspace("manage"),
 	"agents.sessions.prompt": workspace("manage"),
 	"agents.sessions.setConfigOption": workspace("manage"),
@@ -12632,10 +12706,22 @@ function buildBootstrapMarkdown(origin, ctx) {
 	const ownMachine = isCloud ? "" : " Everything runs and stays on the user's own machine.";
 	const step0 = isCloud ? `## Step 0 — Connect to Busabase Cloud
 
+### 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
+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
+fails, ask the user to switch or reconnect accounts; never choose or create another Space.` : `With no preselected Space, use the only result, ask when there are several, and accept a new
+personal Space when the identity has no memberships.`}
+If verification succeeds, skip **0b** and keep MCP for this run. Otherwise use the CLI fallback.
+
+### 0b. CLI fallback
+
 ${preselectedSpaceId ? `One move: sign in. The dashboard already chose the Space, so there is nothing to confirm
 afterwards.` : `Two moves: sign in, then confirm the Space you landed in.
 
-### 0a. Sign in`}
+#### Sign in`}
 
 Sign-in is two commands, one per conversational turn. The first returns immediately, so the user
 actually receives the link even if your harness only delivers a turn's final message:
@@ -12675,14 +12761,14 @@ Two edge cases fall out of that same rule: an empty *existing* Space has no mark
 connect-only, not a trigger to initialize; and a retry after interrupted initialization still has the
 version-0 marker and safely resumes Step 2.
 ${preselectedSpaceId ? "" : `
-### 0b. Confirm the target Space
+### 0c. Confirm the target Space
 
 Login never asks which Space to use: it takes the server default (the Space the user was most
 recently active in) and lists the rest in \`availableSpaces\`. The user has not seen that choice yet.
 
 Always tell the user which Space was selected (name + id). Then, by \`availableSpaces\` length:
 
-- **One** → nothing to choose. Continue with the \`bootstrapRequired\` branch from 0a.
+- **One** → nothing to choose. Continue with the \`bootstrapRequired\` branch from 0b.
 - **More than one** → ask once, a lettered choice in the user's language: \`A\` keeps the current
   Space, then one letter per remaining entry. Offer Spaces, never commands — switching is your job,
   so never tell the user to run anything.
@@ -12690,13 +12776,18 @@ Always tell the user which Space was selected (name + id). Then, by \`availableS
   > 📂 You're in **{space.name}** (the Space you used most recently). Keep it, or switch?
   > **A.** Keep **{space.name}**   **B.** {otherSpace1.name}   **C.** {otherSpace2.name}
 
-  On a switch, run both and re-decide the 0a branch from the new \`bootstrapRequired\` — the old one
+  On a switch, run both and re-decide the 0b branch from the new \`bootstrapRequired\` — the old one
   belonged to the previous Space:
 
   \`\`\`bash
   ${BUSABASE_CLI} space use <id>
   ${BUSABASE_CLI} whoami --output json
-  \`\`\``}` : `## Step 0 — Connect to Busabase Personal Desktop
+  \`\`\``}
+
+On MCP, resolve the target Space from the verification result: ${preselectedSpaceId ? `it must match \`${preselectedSpaceId}\`.` : `use one result; ask the user when there are several.`} Then follow \`bootstrapRequired\`: \`false\` goes to Step 3 with no writes; \`true\` goes to
+Step 1. Before the first write, require write access plus capabilities to inspect, propose, read
+back, and complete bootstrap. If anything is missing, stop before writing; ask the user to reconnect
+with more access or approve CLI fallback. Keep the same transport for the rest of the run.` : `## Step 0 — Connect to Busabase Personal Desktop
 
 Everything runs locally — no account, no API key. The user has already confirmed this edition, so
 check whether the
@@ -12831,7 +12922,15 @@ until curl -fsS ${local}/api/v1/bases >/dev/null 2>&1; do sleep 2; done && echo
 	const spaceNote = isCloud ? "(Every call carries `x-busabase-space: $BUSABASE_SPACE_ID` — the space picked in Step 0. The API key is user-scoped, so do not omit the header.)" : "(No `spaceId` in local mode.)";
 	const step4 = `## Step ${isCloud ? 3 : 4} — The last setup step: install the permanent skills
 
-One step left before everyday use. Install both permanent skills so any agent on this machine can
+${isCloud ? `Have the Harness install both skills into its persistent skill store. Prefer its native
+installer; otherwise run:
+
+\`\`\`bash
+npx skills add busabase/skills --skill busabase busabase-app-creator
+\`\`\`
+
+MCP remains the transport when it connected successfully; installing skills does not require CLI
+credentials. Finish only after both skills are available in future sessions.` : `One step left before everyday use. Install both permanent skills so any agent on this machine can
 drive this workspace with **busabase** and create complete workspace apps with
 **busabase-app-creator** every session — no re-pasting this onboarding doc:
 
@@ -12841,7 +12940,8 @@ npx skills add busabase/skills --skill busabase busabase-app-creator
 
 The skills are self-describing. \`busabase\` reads \`~/.busabase/.env\` (set up above) and becomes
 the reference for the everyday loop and full API; \`busabase-app-creator\` builds on it when the
-user wants a complete workspace app. This onboarding doc has now done its job.
+user wants a complete workspace app.`}
+This onboarding doc has now done its job.
 
 ## 🎉 You're set up — congratulations!
 
@@ -12858,12 +12958,14 @@ Tell them so, and close the journey with the tracker fully checked — e.g.:
 
 > ✅ Connect · ✅ Initialize (new Spaces only) · ✅ Verify · ✅ Skills
 > 🎉 *You're all set — Busabase is connected, your first workspace is live, and both skills are
-> installed. From here it's everyday use: you ask, I write, and every change keeps a message, an
+> installed.
+> From here it's everyday use: you ask, I write, and every change keeps a message, an
 > author and a history you can undo — and I can build a complete workspace app when you need one.*
 ${isCloud ? `
 Finish the congratulations with a clickable Markdown link labeled **Open Busabase Dashboard**.
-${preselectedSpaceId ? `Step 0 locked the Space ID used below; before replying, verify login confirmed that same Space.` : `Replace \`{space_id}\` with the real Space ID that Step 0 confirmed and saved as
-\`BUSABASE_SPACE_ID\` before replying.`}
+${preselectedSpaceId ? `Step 0 locked the Space ID used below; verify whichever path you connected through confirmed
+that same Space before replying.` : `Replace \`{space_id}\` with the real selected Space ID — whichever path you connected
+through resolved and confirmed it — before replying.`}
 Never show \`$BUSABASE_SPACE_ID\`, \`{space_id}\`, \`YOUR_SPACE_ID\`, or any other placeholder
 literally to the user. The user's final line must be:
 
@@ -12891,10 +12993,10 @@ You are guiding the user through four milestones. Existing users skip initializa
 
 | # | Milestone | Covered by | Done when |
 | - | --------- | ---------- | --------- |
-| 1 | 🔌 **Connect** | ${isCloud ? "Step 0" : "Step 0 + Step 1"} | ${isCloud ? "device login returns the selected Space" : "the local API responds and the connection is saved"} |
+| 1 | 🔌 **Connect** | ${isCloud ? "Step 0" : "Step 0 + Step 1"} | ${isCloud ? "a verified MCP integration, or device login, returns the selected Space" : "the local API responds and the connection is saved"} |
 | 2 | 🏗️ **Initialize if required** | ${isCloud ? "Step 1 + Step 2" : "Step 2 + Step 3"} | version-0 Space gets starter data |
 | 3 | ✅ **Verify** | Step ${isCloud ? 2 : 3} | starter records read back and marker becomes version 1 |
-| 4 | 🎓 **Skills installed** | Step ${isCloud ? 3 : 4} | both skills selected by \`npx skills add\`, 🎉 |
+| 4 | 🎓 **Skills installed** | Step ${isCloud ? 3 : 4} | both skills available in the agent's persistent skill store, 🎉 |
 
 **Conduct rules — these create the step-by-step feel; follow them at every turn:**
 
@@ -12965,7 +13067,15 @@ types (\`auto_number\`, \`created_time\`, \`ai_summary\`, \`ai_tags\`, …).
 This is the everyday write loop, not an exception to it: the user has write access to their own
 new Space, so structure and sample rows land immediately. They already chose this starter — do not
 ask them to approve it, and do not force a review by passing \`autoMerge: false\`. Every write carries system provenance and stable
-identity so retries cannot duplicate data. Briefly show what is being built:
+identity so retries cannot duplicate data.
+
+${isCloud ? `**MCP path:** skip the shell examples and have the Harness run the same sequence: inspect,
+create missing structure/views, seed with stable idempotency keys, read back, then complete
+bootstrap. Require merged structure/records and \`materialized: true\` views; otherwise stop for
+approval and resume only after a canonical View read confirms materialization. The shell examples
+below are for CLI only.
+
+` : ""}Briefly show what is being built:
 
 \`\`\`txt
 📁 CRM
@@ -13090,7 +13200,7 @@ curl -X POST "${api}/api/v1/onboarding/bootstrap-complete"${H}
 \`\`\`
 
 The completion call is idempotent and changes \`agentBootstrapVersion\` from 0 to 1 while preserving
-the rest of the Space onboarding state. Re-run \`whoami\`; \`bootstrapRequired\` must now be false.
+the rest of the Space onboarding state. ${isCloud ? `Recheck through the active transport; \`bootstrapRequired\` must now be false.` : `Re-run \`whoami\`; \`bootstrapRequired\` must now be false.`}
 
 ### Custom blueprint (any scenario — this is what keeps it general)
 
@@ -13283,6 +13393,107 @@ async function resolveSkillDocument(topic, doc, runtime) {
 		source: "server"
 	} : bundled(live.reason ?? "the live document could not be read");
 }
+/**
+* Read `name`/`description` out of a hosted SKILL.md's YAML frontmatter.
+*
+* Deliberately a small hand-rolled reader rather than a YAML dependency: the two fields
+* it needs are flat scalars, and the shapes that actually occur in the wild are plain,
+* quoted, and folded (`>-`) — the last of which every long Busabase description uses.
+* Anything stranger is better rejected loudly here than half-understood.
+*/
+function parseSkillIdentity(body) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(body.trimStart());
+	if (!match) throw new Error("the hosted SKILL.md has no YAML frontmatter");
+	const lines = match[1].split(/\r?\n/);
+	const read = (key) => {
+		const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+		if (start === -1) return void 0;
+		const inline = lines[start].slice(key.length + 1).trim();
+		if (inline === "" || inline === ">" || inline === ">-" || inline === "|" || inline === "|-") {
+			const rest = [];
+			for (const line of lines.slice(start + 1)) {
+				if (!/^\s/.test(line) || line.trim() === "") break;
+				rest.push(line.trim());
+			}
+			return rest.join(" ");
+		}
+		return inline.replace(/^["']|["']$/g, "");
+	};
+	const name = read("name");
+	const description = read("description");
+	if (!name) throw new Error("the hosted SKILL.md frontmatter has no `name`");
+	if (!description) throw new Error("the hosted SKILL.md frontmatter has no `description`; without it no agent would know when to fetch this skill, so a stub for it cannot work");
+	return {
+		name,
+		description
+	};
+}
+/**
+* Render the stub. Two details here are not stylistic:
+*
+* `--output json` — the default text output renders the body as a one-line preview
+* (a 40 KB skill comes back as ~400 bytes ending in an ellipsis), so a stub that
+* omitted it would hand the agent a truncated procedure and no error.
+*
+* `@latest` — `npx` will reuse whatever copy of the CLI it already cached, which may
+* predate the subcommand entirely.
+*
+* The fetch-first wording is equally deliberate. A stub whose fetch fails must stop,
+* not improvise from the one-line description; that failure mode is the whole reason
+* the body is centralized in the first place.
+*/
+function buildPointerStub(input) {
+	const space = input.spaceName ? `${input.spaceName}${input.spaceId ? ` \`${input.spaceId}\`` : ""}` : input.spaceId ?? "—";
+	return `---
+name: ${input.name}
+description: ${JSON.stringify(input.description)}
+---
+
+The body of this skill lives in Busabase, in the same folder as the resources it
+works with, so it moves when they move. **Fetch it before doing anything:**
+
+\`\`\`bash
+npx busabase-cli@latest skills read-file --node-id ${input.nodeId} \\
+  --file-path SKILL.md --output json
+\`\`\`
+
+\`--output json\` is required — the default text output truncates the body to a
+one-line preview. \`@latest\` is required too: \`npx\` will otherwise reuse a cached
+older CLI that may not have this subcommand.
+
+If the fetch fails — no access, the node moved, the network is down — **stop and say
+so.** Do not improvise the procedure from the description above; the body is hosted in
+one place precisely so that every repository runs the same one.
+
+| What | Where |
+| --- | --- |
+| Space | ${space} |
+| Skill node | \`${input.name}\` — \`${input.nodeId}\` |
+`;
+}
+/**
+* Write `<dir>/<name>/SKILL.md`. Same no-clobber rule as `installSkillDoc`, for the
+* same reason: the file already there may be a real skill someone wrote, and replacing
+* a body with a pointer to a different one is not a refresh, it is a swap.
+*/
+function linkSkillDoc(input) {
+	const exists = input.exists ?? existsSync;
+	const write = input.write ?? ((path, body) => {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, body, "utf8");
+	});
+	const path = join(input.dir, input.name, "SKILL.md");
+	if (exists(path) && !input.force) return {
+		path,
+		written: false,
+		reason: `${input.name} already exists there; pass --force to replace it`
+	};
+	write(path, content(input.content));
+	return {
+		path,
+		written: true
+	};
+}
 //#endregion
 //#region src/task-command.ts
 const collect = (value, previous = []) => [...previous, value];
@@ -13868,24 +14079,6 @@ async function putTextCommand(client, opts) {
 	});
 }
 /** Wrap a leaf-command handler: resolve config, build the client, render the result. */
-/**
-* Is this a 404 — either "this server has no such route" or "no such node"?
-*
-* Duck-typed rather than an `instanceof ORPCError` check, because this package
-* deliberately depends on no `@orpc/*` package; the SDK builds the error and
-* only its `status` is needed here.
-*
-* Not distinguishing the two 404s is safe for the one thing this gates: a
-* version fallback whose other branch targets the SAME node. An old server
-* answers 404 because the route is missing and the fallback then succeeds; a
-* current server answers 404 because the node does not exist, the fallback
-* asks about the same missing node and 404s too, and the caller still sees a
-* "not found" error. The cost of guessing wrong is one extra request, not a
-* write landing somewhere unintended.
-*/
-function isNotFound(error) {
-	return typeof error === "object" && error !== null && "status" in error && error.status === 404;
-}
 function runAction(state, handler) {
 	return async (_opts, cmd) => {
 		const opts = cmd.optsWithGlobals();
@@ -14628,6 +14821,64 @@ Default target when neither is present: ${skillsDirDefaultHint()}`).action((dir,
 		console.log(`  ${result.path}`);
 		console.error(`\n[busabase-cli] this copy is bound to this host. For the canonical pair, run:\n  ${SKILL_REGISTRY_HINT}`);
 	});
+	addGlobalFlags(skill.command("link")).argument("[dir]", `skills directory; default: ./.agents/skills, else ./.claude/skills`).description("Point this repo at a Skill node hosted in a workspace, without copying it").requiredOption("--node-id <id>", "the Skill node whose body stays canonical").addOption(new Option("--dir <path>", "same as the positional argument")).addOption(new Option("--force", "replace an existing skill of the same name")).addHelpText("after", `
+\`install\` writes a COPY. \`link\` writes a POINTER: a short SKILL.md holding only the
+hosted skill's own name and description plus the command to fetch its body, so the
+body itself never lands on disk here.
+
+Use it when one skill has to serve several repositories. Vendoring a copy into each
+one means copies that drift; a pointer means every repository reads the one body, and
+an edit to it — reviewed once, through a Change Request — is live for all of them at
+the same moment.
+
+  busabase-cli skill link --node-id nodmtv5rwuofuhaqwl
+
+Writes <dir>/<the skill's own name>/SKILL.md. The name comes from the hosted
+frontmatter, not from you, because that name is how an agent resolves "read the
+crm-visits skill in this folder".
+
+A pointer names a specific node in a specific space, so: everyone who uses it needs
+read access to that space, and it must never be published as a template — a template
+materializes fresh resources in the installer's space, while these ids name yours.
+Default target when neither is present: ${skillsDirDefaultHint()}`).action(async (dir, _opts, cmd) => {
+		const opts = cmd.optsWithGlobals();
+		const config = resolveConfig(opts);
+		state.config = config;
+		const nodeId = String(opts.nodeId);
+		const file = await createBusabaseClient(config).fileTrees.readFile({
+			nodeId,
+			type: "skill",
+			filePath: "SKILL.md"
+		});
+		const identity = parseSkillIdentity(String(file.content ?? ""));
+		const result = linkSkillDoc({
+			dir: resolveSkillsDir({
+				explicit: dir ?? opts.dir,
+				cwd: process.cwd(),
+				home: homedir(),
+				exists: existsSync
+			}),
+			name: identity.name,
+			content: buildPointerStub({
+				...identity,
+				nodeId,
+				spaceId: config.spaceId
+			}),
+			force: Boolean(opts.force)
+		});
+		if (!result.written) throw new CliOutcomeError("CONFLICT", `Not linked: ${result.path} — ${result.reason}`);
+		if (config.output === "json") {
+			console.log(render({
+				path: result.path,
+				name: identity.name,
+				nodeId
+			}, "json"));
+			return;
+		}
+		console.log(`Linked the \`${identity.name}\` skill to node ${nodeId} at:`);
+		console.log(`  ${result.path}`);
+		console.error("\n[busabase-cli] this is a pointer, not a copy — the body stays in the workspace and is fetched on use. Everyone using it needs read access to that space.");
+	});
 	addGlobalFlags(program.command("setup-skill")).description("Alias for `skill setup` — the onboarding document").addOption(modeOption()).addOption(withKeyOption()).addOption(new Option("--offline", "skip the server and print the bundled copy")).action(async (_opts, cmd) => {
 		const opts = cmd.optsWithGlobals();
 		const config = resolveConfig(opts);
@@ -14911,18 +15162,10 @@ Examples:
 			throw new CliOutcomeError("VALIDATION", `Invalid agent prompts in ${filePath}${detail ? ` — ${detail}` : ""}`);
 		}
 		const nodeId = opts.nodeId;
-		try {
-			return await client.nodes.updateAgentPrompts({
-				nodeId,
-				agentPrompts: parsed.data
-			});
-		} catch (error) {
-			if (!isNotFound(error)) throw error;
-			return await client.nodes.updateMetadata({
-				nodeId,
-				metadata: { agentPrompts: parsed.data }
-			});
-		}
+		return await client.nodes.updateAgentPrompts({
+			nodeId,
+			agentPrompts: parsed.data
+		});
 	}));
 	const bases = program.command("bases").description("Bases (structured tables)");
 	addGlobalFlags(bases.command("list")).description("List Bases in the active space").addOption(new Option("--status <active|archived>", "live Bases (default) or archived ones").choices(["active", "archived"])).action(runAction(state, (client, opts) => client.bases.list({ status: opts.status ?? "active" })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.60.0",
+  "version": "0.71.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.60.0",
+    "busabase-sdk": "0.71.0",
     "commander": "^14.0.0",
     "qrcode": "^1.5.4",
     "tar-stream": "^3.1.7",