busabase-sdk 0.20.0 → 0.30.0

package/dist/airapp-check.d.ts

@@ -0,0 +1,117 @@
+//#region src/airapp-check.d.ts
+/**
+ * The AirApp runtime contract, as checkable rules.
+ *
+ * These live in the SDK for one reason: **a rule and the runtime it checks must
+ * ship together.** The rules below are about `BUSABASE_AIRAPP_RUNTIME`,
+ * `__airapp/runtime`, `createBusabaseClient` and `isBusabaseAirAppHosted` — all
+ * of which are defined a few files away. Keeping the rules anywhere else means
+ * the two drift, and drift here is not hypothetical: an engine rename from
+ * `local-node` to `local` broke 66 shipped apps whose runtime detection carried
+ * its own private copy of the truth.
+ *
+ * It also makes them *reachable*. Every AirApp already depends on `busabase-sdk`
+ * at an exact pin, so an app's `scripts/check.mjs` shrinks from dozens of
+ * hand-copied assertions to reading its files and calling one function. The
+ * previous delivery mechanism was "copy these into your check script", and it
+ * reached 4 apps out of 67.
+ *
+ * Pure by design: this module reads no files, spawns nothing, and touches no
+ * network. Callers hand it source text. That keeps it usable from a CLI, from an
+ * app's own check script, and from a test, without any of them agreeing on a
+ * filesystem layout.
+ */
+/** Severity split: an error breaks a user of the app; a warning is a default worth defending. */
+type AirAppFindingSeverity = "error" | "warning";
+interface AirAppFinding {
+  severity: AirAppFindingSeverity;
+  /** Stable kebab-case id, so a caller can allowlist or group without matching prose. */
+  rule: string;
+  message: string;
+}
+interface AirAppSources {
+  /** Raw `package.json` text. */
+  packageJson?: string;
+  /**
+   * The host's source. **Concatenate the whole server subtree**, not just the entry
+   * file — a `server.js` that mounts `server/hono.ts` keeps the runtime route in the
+   * module, and passing only the entry reports a correct app as broken. (Observed:
+   * two shipped apps failed this way against a collector that read `server.js` alone.)
+   */
+  server?: string;
+  /**
+   * Which language the host is written in. Inferred from Python syntax when omitted.
+   *
+   * NOT the AirApp *runtime* — that is the engine Busabase spawned the process in
+   * (`nodepod`, `local`, `sandock`, …), which is a value the app reports at runtime,
+   * not a property of its source. Two different things called "runtime" in one
+   * domain is how the wrong one ends up being checked.
+   */
+  serverLanguage?: "node" | "python";
+  /**
+   * The browser files that carry **logic** — app, config, client, runtime probe,
+   * the Busabase provider. The structural rules run over this corpus and no wider.
+   *
+   * Excluding string tables and demo data is deliberate rather than an oversight:
+   * an asset-path or hostname rule false-positives on UI copy that merely *talks*
+   * about localhost or shows a path in an error message.
+   */
+  browserLogic?: string;
+  /**
+   * **Everything** the browser downloads, copy and `index.html` included.
+   *
+   * Credentials are scanned over this wider corpus, because a key pasted into a
+   * string table ships to the browser exactly like one pasted into `app.js` — and
+   * used to pass a gate that only looked at the logic files.
+   *
+   * **Exclude `app/vendor/`.** A bundled `busabase-sdk` legitimately builds an
+   * `Authorization: Bearer …` header from a resolved key, so sweeping the vendor
+   * directory in reports every app that bundles the SDK as leaking a credential.
+   * List the app's own files; never glob the whole `app/` tree.
+   */
+  browserDownloads?: string;
+  /** `app/js/config.js`, when the app declares its own resources. */
+  config?: string;
+  /** The slug the package ships this app under, for the `resourceKey` rule. */
+  shippedSlug?: string;
+}
+/**
+ * The documented interactive page budget. A higher one may be justified — say so in
+ * review — so this is a warning rather than a hard bound. A generator checking its
+ * own output is free to be stricter.
+ */
+declare const AIRAPP_DEFAULT_READ_LIMIT = 50;
+/**
+ * Strip comments before pattern-matching source.
+ *
+ * Load-bearing, not tidiness. A file that explains a rule necessarily *names* the
+ * thing the rule forbids, and matching that prose let a server which had genuinely
+ * stopped reading `BUSABASE_AIRAPP_RUNTIME` pass its gate — the comment about the
+ * variable satisfied the check for the variable. Prose about a rule must never
+ * satisfy the rule.
+ */
+declare const stripComments: (source: string) => string;
+/**
+ * Objects inside a `bases: [ ... ]` literal, brace-matched rather than regexed across
+ * the array, so a nested `fields:` entry is never mistaken for a Base.
+ *
+ * Reading the declaration without evaluating the module is the point: a checker must
+ * not execute the app it is checking.
+ */
+declare const scanAirAppConfig: (source: string) => {
+  bases: {
+    key: string | null;
+    slug: string | null;
+  }[];
+  drive: {
+    slug: string | null;
+  } | null;
+  resourceKey: string | null;
+};
+/**
+ * Check an AirApp against the runtime contract. Returns findings; never throws for a
+ * rule violation, so one caller can report every problem at once instead of the first.
+ */
+declare const checkAirApp: (sources: AirAppSources) => AirAppFinding[];
+//#endregion
+export { AIRAPP_DEFAULT_READ_LIMIT, AirAppFinding, AirAppFindingSeverity, AirAppSources, checkAirApp, scanAirAppConfig, stripComments };

package/dist/airapp-check.js

@@ -0,0 +1,159 @@
+//#region src/airapp-check.ts
+/** A `busabase-sdk` version must be exact. A range is not the app that was reviewed. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** A `start` script may start the server and nothing else. */
+const START_IS_A_BUILD = /(?:&&|\|\||;|\bnpm\s+run\s+build\b|\btsc\b|\bvite\b|\bwebpack\b|\bparcel\b)/;
+/** An AirApp is Hono plus vanilla browser code. `esbuild` is how the SDK gets bundled. */
+const FORBIDDEN_DEPENDENCIES = [
+	"react",
+	"react-dom",
+	"preact",
+	"vite",
+	"@vitejs/plugin-react",
+	"next",
+	"webpack",
+	"parcel"
+];
+/**
+* The documented interactive page budget. A higher one may be justified — say so in
+* review — so this is a warning rather than a hard bound. A generator checking its
+* own output is free to be stricter.
+*/
+const AIRAPP_DEFAULT_READ_LIMIT = 50;
+/**
+* Strip comments before pattern-matching source.
+*
+* Load-bearing, not tidiness. A file that explains a rule necessarily *names* the
+* thing the rule forbids, and matching that prose let a server which had genuinely
+* stopped reading `BUSABASE_AIRAPP_RUNTIME` pass its gate — the comment about the
+* variable satisfied the check for the variable. Prose about a rule must never
+* satisfy the rule.
+*/
+const stripComments = (source) => source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/(^|[^:'"`\\])\/\/[^\n]*/g, "$1 ");
+/**
+* Objects inside a `bases: [ ... ]` literal, brace-matched rather than regexed across
+* the array, so a nested `fields:` entry is never mistaken for a Base.
+*
+* Reading the declaration without evaluating the module is the point: a checker must
+* not execute the app it is checking.
+*/
+const scanAirAppConfig = (source) => {
+	const anchor = /\bbases\s*:\s*\[/.exec(source);
+	const blocks = [];
+	if (anchor) {
+		let depth = 0;
+		let start = -1;
+		for (let index = anchor.index + anchor[0].length - 1; index < source.length; index += 1) {
+			const char = source[index];
+			if (char === "[") depth += 1;
+			else if (char === "]") {
+				depth -= 1;
+				if (depth === 0) break;
+			} else if (char === "{" && depth === 1) {
+				if (start === -1) start = index;
+				depth += 1;
+			} else if (char === "{") depth += 1;
+			else if (char === "}") {
+				depth -= 1;
+				if (depth === 1 && start !== -1) {
+					blocks.push(source.slice(start, index + 1));
+					start = -1;
+				}
+			}
+		}
+	}
+	const literal = (block, key) => new RegExp(`\\b${key}\\s*:\\s*"([^"]*)"`).exec(block)?.[1] ?? null;
+	const drive = /\bdrive\s*:\s*\{([\s\S]*?)\}/.exec(source);
+	return {
+		bases: blocks.map((block) => ({
+			key: literal(block, "key"),
+			slug: literal(block, "slug")
+		})),
+		drive: drive ? { slug: literal(drive[1], "slug") } : null,
+		resourceKey: /\bairApp\s*:\s*\{[^}]*\bresourceKey\s*:\s*"([^"]*)"/.exec(source)?.[1] ?? null
+	};
+};
+/**
+* Check an AirApp against the runtime contract. Returns findings; never throws for a
+* rule violation, so one caller can report every problem at once instead of the first.
+*/
+const checkAirApp = (sources) => {
+	const findings = [];
+	const error = (rule, message) => findings.push({
+		severity: "error",
+		rule,
+		message
+	});
+	const warn = (rule, message) => findings.push({
+		severity: "warning",
+		rule,
+		message
+	});
+	if (sources.packageJson !== void 0) {
+		let manifest;
+		try {
+			manifest = JSON.parse(sources.packageJson);
+		} catch (cause) {
+			error("airapp/package-json", `package.json is not valid JSON (${cause.message}).`);
+		}
+		if (manifest) {
+			const scripts = manifest.scripts ?? {};
+			if (typeof scripts.dev !== "string") error("airapp/dev-script", "package.json has no `dev` script. Busabase boots an app with `npm run dev`, so it installs cleanly and then never starts.");
+			if (typeof scripts.start === "string" && START_IS_A_BUILD.test(scripts.start)) error("airapp/start-pure", `\`start\` is "${scripts.start}" — a deployed start must only run the server, never build or spawn.`);
+			const dependencies = {
+				...manifest.dependencies ?? {},
+				...manifest.devDependencies ?? {}
+			};
+			const sdk = manifest.dependencies?.["busabase-sdk"];
+			if (sdk === void 0) warn("airapp/sdk", "No `busabase-sdk` dependency — the app cannot reach the workspace.");
+			else if (!EXACT_VERSION.test(String(sdk))) error("airapp/sdk-pin", `busabase-sdk is "${String(sdk)}". Pin the exact version — a range means the installed app is not the one that was reviewed.`);
+			for (const forbidden of FORBIDDEN_DEPENDENCIES) if (dependencies[forbidden] !== void 0) error("airapp/no-framework", `Depends on "${forbidden}". An AirApp is Hono plus vanilla HTML/CSS/JS; its files are reviewed and then run as-is, so nothing may need compiling first.`);
+		}
+	}
+	if (sources.browserLogic !== void 0) {
+		const logic = sources.browserLogic;
+		const code = stripComments(logic);
+		if (!logic.includes("createBusabaseClient")) warn("airapp/sdk-client", "Browser code never calls `createBusabaseClient`.");
+		if (logic.includes("__busabase_api__")) error("airapp/legacy-bridge", "The obsolete `/__busabase_api__/` bridge prefix is gone. The API is same-origin `/api/v1`.");
+		if (/baseUrl\s*:\s*["'`]https?:\/\//.test(code)) error("airapp/absolute-url", "A hard-coded absolute Busabase URL in browser code. Use `window.location.origin` — an absolute URL is right in exactly one deployment and wrong in the rest.");
+		if (/(?:src|href)="\/(?!\/)|from\s+["']\/(?!\/)/.test(code)) error("airapp/absolute-asset", "An absolute asset path. Under the Local Node engine the app is proxied onto a sub-path of Busabase's origin, so a leading slash resolves against Busabase itself and 404s.");
+		if (/while\s*\(\s*cursor\s*\)|client\.bases\.list\s*\(/.test(code) || /while\s*\(\s*true\s*\)[\s\S]{0,400}?(?:records\.list|readPage)\s*\(/.test(code)) error("airapp/unbounded-read", "Unbounded loading or runtime Base discovery. Every interactive read gets an explicit budget and fetches one page per user action.");
+		if (/\bmax\w*pages?\w*\s*=\s*\d+[\s\S]{0,400}?(?:client\.)?records\.list\s*\(/i.test(code)) error("airapp/eager-multi-page", "A capped loop fetches several pages of records in one function call. A cap bounds the damage but does not fix the shape: this still hides a multi-page scan behind one loading state instead of fetching one page per user action.");
+		const branches = /createAirAppConnectGate|getRuntime\s*\(|\bhosted\b/.test(code) || sources.server !== void 0 && /createAirAppConnectGate/.test(sources.server);
+		if (/location\s*\.\s*(?:hostname|host)\b/.test(code)) error("airapp/runtime-hostname", "Hostname-based runtime detection. Both directions are wrong: a Busabase-hosted AirApp is served from `localhost` on Desktop, and a standalone `npm run dev` is reached over a LAN IP or a signed dev tunnel. Read the runtime from `__airapp/runtime`.");
+		if (/(?:===|!==|==|!=)\s*["'`][^"'`]*(?:localhost|127\.0\.0\.1)|(?:includes|startsWith|endsWith|indexOf|search|match|test)\s*\(\s*\/?["'`]?[^"'`)]*(?:localhost|127\.0\.0\.1)/.test(code)) error("airapp/runtime-loopback", "A loopback host comparison. Runtime detection must not depend on the URL at all.");
+		if (branches && !logic.includes("__airapp/runtime")) error("airapp/runtime-probe", "This app branches on where it is running but never probes `__airapp/runtime`, so that branch is deciding on something else.");
+		if (/["'`]\/__airapp\/runtime/.test(logic)) error("airapp/runtime-probe-relative", "The runtime probe has a leading slash. It must be relative (`__airapp/runtime`) — a leading slash resolves against Busabase's root under the Local Node sub-path proxy.");
+	}
+	if (sources.server !== void 0) {
+		const server = sources.server;
+		const serverCode = stripComments(server);
+		const readsRuntimeEnv = (sources.serverLanguage ? sources.serverLanguage === "python" : /^\s*(?:import|from)\s+\w+|def\s+\w+\s*\(/m.test(server)) ? /BUSABASE_AIRAPP_RUNTIME/.test(serverCode) : /(?:read|describe)BusabaseAirAppRuntime\s*\(|process\.env\.BUSABASE_AIRAPP_RUNTIME\b/.test(serverCode);
+		const clientBranches = sources.browserLogic !== void 0 && /createAirAppConnectGate|getRuntime\s*\(|\bhosted\b/.test(stripComments(sources.browserLogic));
+		if (clientBranches && !readsRuntimeEnv) error("airapp/runtime-env", "The server never reads `BUSABASE_AIRAPP_RUNTIME`, directly or through the SDK, so it has nothing to serve at `__airapp/runtime`.");
+		if (/AIRAPP_HOSTED_RUNTIMES\s*=\s*new Set|hosted:\s*\w*RUNTIMES?\w*\.has\s*\(/.test(serverCode)) error("airapp/runtime-engine-list", "Hosting is decided from a hardcoded list of engine names. Use presence, not membership — a private list is what broke 66 apps when `local-node` was renamed `local`.");
+		if (clientBranches && !/["'`]\/__airapp\/runtime["'`]/.test(server)) error("airapp/runtime-route", "Browser code branches on the runtime but the server does not serve `/__airapp/runtime`.");
+		if (/Bearer\s+(?!\$\{)[A-Za-z0-9_-]{8,}/.test(server)) error("airapp/credential", "A literal Bearer token in the server source.");
+	}
+	if (sources.browserDownloads !== void 0) {
+		const downloads = sources.browserDownloads;
+		if (/BUSABASE_API_KEY/i.test(downloads)) error("airapp/credential", "An API key reference in browser source.");
+		if (/Bearer\s+(?!\$\{)[A-Za-z0-9_.-]{8,}/.test(downloads)) error("airapp/credential", "A literal Bearer token in browser source.");
+		if (/["'`]\s*Bearer\s*\$\{/.test(downloads)) error("airapp/credential", "Browser code builds an Authorization header. A deployed AirApp uses the viewer's ambient same-origin session and needs none.");
+	}
+	if (sources.config !== void 0) {
+		const config = scanAirAppConfig(sources.config);
+		if (sources.shippedSlug !== void 0 && config.resourceKey !== null && config.resourceKey !== sources.shippedSlug) error("airapp/resource-key", `Config declares resourceKey "${config.resourceKey}" but the package ships this app as "${sources.shippedSlug}". Install stamps nodes with the shipped slug, so the app would not recognise its own node.`);
+		for (const base of config.bases) if (base.slug === null) error("airapp/base-slug", `Config base "${base.key ?? "(unnamed)"}" has no \`slug\`. The SDK needs it to CREATE the Base, so the app's own provisioning fails even though installing from the package succeeds — install reads base.json and never opens that door.`);
+		if (config.drive !== null && config.drive.slug === null) error("airapp/base-slug", "Config `drive` has no `slug`; provisioning it will fail.");
+		if (/vaultValue|vaultSecret\s*:\s*["'`][^"'`]/.test(sources.config)) error("airapp/vault-value", "A Vault value in config. Config may reference secrets, never carry them.");
+		for (const found of sources.config.matchAll(/\breadLimit\s*:\s*(\d+)/g)) {
+			const limit = Number(found[1]);
+			if (limit < 1) error("airapp/read-budget", `readLimit is ${limit}; it must be a positive integer.`);
+			else if (limit > 50) warn("airapp/read-budget", `readLimit is ${limit}, above the 50-record default page budget. Justify it in review, or page.`);
+		}
+	}
+	return findings;
+};
+//#endregion
+export { AIRAPP_DEFAULT_READ_LIMIT, checkAirApp, scanAirAppConfig, stripComments };

package/dist/airapp-node.d.ts

@@ -46,6 +46,39 @@ declare const isBusabaseAirAppHosted: (runtime?: string) => boolean;
  * behaviour rather than break.
  */
 declare const asKnownBusabaseAirAppRuntime: (runtime: string) => BusabaseAirAppRuntime | null;
+/** The body every AirApp serves at `__airapp/runtime`. */
+interface BusabaseAirAppRuntimeReport {
+  /**
+   * The engine name verbatim, or `"standalone"` when nothing hosted this process.
+   *
+   * Deliberately a plain string and not the enum: a newer Busabase naming an engine
+   * this SDK predates must still round-trip, and narrowing here would erase it.
+   */
+  runtime: string;
+  /**
+   * The same value narrowed to what this SDK knows, or `null` for an engine it has
+   * never heard of. This is the field to branch on when behaviour genuinely differs
+   * per engine — and `null` is a normal answer, not an error.
+   */
+  knownRuntime: BusabaseAirAppRuntime | null;
+  /** Presence of the injected variable. Never membership of {@link BUSABASE_AIRAPP_RUNTIMES}. */
+  hosted: boolean;
+  /** Whether a standalone run is proxying to a Busabase base URL. A separate axis. */
+  devProxy: boolean;
+}
+/**
+ * Build the `__airapp/runtime` body.
+ *
+ * This exists because the one line it replaces — `hosted: …` — has now regressed
+ * twice. Both times a correct app was copied from an older source and came back
+ * deciding hosting from a hardcoded list of engine names, and both times every test
+ * stayed green, because nothing asserted the shape of that decision.
+ *
+ * An app that calls this cannot get it wrong: `hosted` is presence by construction,
+ * and the engine name is reported both verbatim (so an unknown one survives) and
+ * narrowed (so code that wants to branch on a specific engine has a type).
+ */
+declare const describeBusabaseAirAppRuntime: (env?: Record<string, string | undefined>) => BusabaseAirAppRuntimeReport;
 declare const BUSABASE_AIRAPP_GATEWAY_REASONS: {
   readonly authRequired: "AUTH_REQUIRED";
   readonly authUnavailable: "AUTH_UNAVAILABLE";
@@ -108,4 +141,4 @@ declare class BusabaseAirAppLocalGateway {
 }
 declare const createBusabaseAirAppLocalGateway: (options: BusabaseAirAppLocalGatewayOptions) => BusabaseAirAppLocalGateway;
 //#endregion
-export { BUSABASE_AIRAPP_GATEWAY_REASONS, BUSABASE_AIRAPP_RUNTIMES, BUSABASE_AIRAPP_RUNTIME_ENV, BusabaseAirAppAuthStatus, BusabaseAirAppLocalGateway, BusabaseAirAppLocalGatewayOptions, BusabaseAirAppRuntime, asKnownBusabaseAirAppRuntime, createBusabaseAirAppLocalGateway, isBusabaseAirAppHosted, readBusabaseAirAppRuntime };
+export { BUSABASE_AIRAPP_GATEWAY_REASONS, BUSABASE_AIRAPP_RUNTIMES, BUSABASE_AIRAPP_RUNTIME_ENV, BusabaseAirAppAuthStatus, BusabaseAirAppLocalGateway, BusabaseAirAppLocalGatewayOptions, BusabaseAirAppRuntime, BusabaseAirAppRuntimeReport, asKnownBusabaseAirAppRuntime, createBusabaseAirAppLocalGateway, describeBusabaseAirAppRuntime, isBusabaseAirAppHosted, readBusabaseAirAppRuntime };

package/dist/airapp-node.js

@@ -55,6 +55,27 @@ const isBusabaseAirAppHosted = (runtime = readBusabaseAirAppRuntime()) => runtim
 * behaviour rather than break.
 */
 const asKnownBusabaseAirAppRuntime = (runtime) => BUSABASE_AIRAPP_RUNTIMES.includes(runtime) ? runtime : null;
+/**
+* Build the `__airapp/runtime` body.
+*
+* This exists because the one line it replaces — `hosted: …` — has now regressed
+* twice. Both times a correct app was copied from an older source and came back
+* deciding hosting from a hardcoded list of engine names, and both times every test
+* stayed green, because nothing asserted the shape of that decision.
+*
+* An app that calls this cannot get it wrong: `hosted` is presence by construction,
+* and the engine name is reported both verbatim (so an unknown one survives) and
+* narrowed (so code that wants to branch on a specific engine has a type).
+*/
+const describeBusabaseAirAppRuntime = (env = process.env) => {
+	const runtime = readBusabaseAirAppRuntime(env);
+	return {
+		runtime: runtime || "standalone",
+		knownRuntime: asKnownBusabaseAirAppRuntime(runtime),
+		hosted: isBusabaseAirAppHosted(runtime),
+		devProxy: (env.BUSABASE_BASE_URL || "").trim() !== ""
+	};
+};
 const BUSABASE_AIRAPP_GATEWAY_REASONS = {
 	authRequired: "AUTH_REQUIRED",
 	authUnavailable: "AUTH_UNAVAILABLE",
@@ -427,4 +448,4 @@ var BusabaseAirAppLocalGateway = class {
 };
 const createBusabaseAirAppLocalGateway = (options) => new BusabaseAirAppLocalGateway(options);
 //#endregion
-export { BUSABASE_AIRAPP_GATEWAY_REASONS, BUSABASE_AIRAPP_RUNTIMES, BUSABASE_AIRAPP_RUNTIME_ENV, BusabaseAirAppLocalGateway, asKnownBusabaseAirAppRuntime, createBusabaseAirAppLocalGateway, isBusabaseAirAppHosted, readBusabaseAirAppRuntime };
+export { BUSABASE_AIRAPP_GATEWAY_REASONS, BUSABASE_AIRAPP_RUNTIMES, BUSABASE_AIRAPP_RUNTIME_ENV, BusabaseAirAppLocalGateway, asKnownBusabaseAirAppRuntime, createBusabaseAirAppLocalGateway, describeBusabaseAirAppRuntime, isBusabaseAirAppHosted, readBusabaseAirAppRuntime };

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { t as BusabaseClient } from "./client-DF6mrd6D.js";
+import { t as BusabaseClient } from "./client-CVz2pqrF.js";
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];

package/dist/airapp.js

@@ -1,4 +1,33 @@
 import { z } from "zod";
+//#region ../../packages/busabase-contract/src/domains/skill/frontmatter.ts
+/**
+* `SKILL.md` frontmatter — the generic shape, independent of Busabase.
+*
+* This used to live inside `domains/package/template.ts`, which encoded an
+* assumption that no longer holds: that a Skill is a *part of* a template. Most
+* Skills are not. A Skill is a directory with a `SKILL.md` an agent reads; it
+* needs no `busabase.json`, ships no `content/`, and never installs into a
+* workspace. Busabase's own `busabase-app-creator` is one.
+*
+* Modelling it only as a template component meant there was nowhere to hang
+* checks for a plain Skill, so there were none. Hence its own file, in the
+* domain it belongs to.
+*
+* `metadata` is deliberately open: a Skill carries whatever its ecosystem
+* defines (categories, tags, risk labels, per-agent hints). The Busabase-specific
+* block that decides template-ness is layered on in `domains/package/template.ts`
+* — the template format knows about Skills, not the other way round.
+*/
+const SkillFrontmatterSchema$1 = z.object({
+	/** Identity. For a Skill inside a package this must equal the package name. */
+	name: z.string().min(1),
+	/**
+	* How an agent decides whether to reach for this Skill at all — so an empty one
+	* is not a cosmetic omission, it is a Skill that never gets picked.
+	*/
+	description: z.string().default(""),
+	metadata: z.object({}).passthrough().optional()
+});
 const TemplateAirAppRefSchema = z.object({
 	/** Slug of the `content/<dir>` holding the AirApp. */
 	slug: z.string().min(1),
@@ -70,11 +99,7 @@ const SkillBusabaseMetadataSchema = z.object({
 	resources: z.array(z.string()).default([]),
 	risk: z.string().optional()
 });
-z.object({
-	name: z.string().min(1),
-	description: z.string().default(""),
-	metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional()
-});
+SkillFrontmatterSchema$1.extend({ metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional() });
 /** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
 const AppResourceOwnershipSchema = z.object({
 	appId: z.string().min(1),

package/dist/{client-DF6mrd6D.d.ts → client-CVz2pqrF.d.ts}

@@ -1,5 +1,13 @@
 import { ContractRouterClient } from "@orpc/contract";
 import { z } from "zod";
+//#region ../../packages/busabase-contract/src/domains/types.d.ts
+/**
+ * Shared interfaces for node-type modules. Each node type lives in its own module
+ * (./folder, ./base, ./skill, …) and exports a definition that satisfies
+ * `NodeTypeDefinition`; the registry composes + registers them.
+ */
+type NodePublicAccess = "detail" | "submit" | "runtime" | "no";
+//#endregion
 //#region ../../packages/busabase-contract/src/domains/registry.d.ts
 declare const GENERIC_NODE_OPERATIONS: readonly [{
   readonly kind: "node_create";
@@ -32,6 +40,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
     readonly container: true;
     readonly creatable: true;
     readonly hasDetail: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [];
 }, {
@@ -41,6 +50,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
     readonly kind: "record_create";
@@ -118,6 +128,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: NodePublicAccess;
   };
   readonly operations: readonly [{
     readonly kind: `${string}_file_create`;
@@ -143,6 +154,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: NodePublicAccess;
   };
   readonly operations: readonly [{
     readonly kind: `${string}_file_create`;
@@ -168,6 +180,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: NodePublicAccess;
   };
   readonly operations: readonly [{
     readonly kind: `${string}_file_create`;
@@ -193,6 +206,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [];
 }, {
@@ -202,6 +216,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
     readonly kind: "doc_update";
@@ -215,6 +230,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "submit";
   };
   readonly operations: readonly [];
 }, {
@@ -224,6 +240,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
     readonly kind: "whiteboard_document_update";
@@ -237,6 +254,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
     readonly kind: "workflow_document_update";
@@ -250,6 +268,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly publicAccess: "no";
   };
   readonly operations: readonly [{
     readonly kind: "html_document_update";
@@ -420,12 +439,14 @@ declare const cloudContract: {
     sources: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
       files: "files";
       names: "names";
+      nodes: "nodes";
       records: "records";
     }>>, z.ZodEnum<{
       files: "files";
       names: "names";
+      nodes: "nodes";
       records: "records";
-    }>]>, z.ZodTransform<("files" | "names" | "records")[], "files" | "names" | "records" | ("files" | "names" | "records")[]>>>;
+    }>]>, z.ZodTransform<("files" | "names" | "nodes" | "records")[], "files" | "names" | "nodes" | "records" | ("files" | "names" | "nodes" | "records")[]>>>;
   }, z.core.$strip>, z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodNumber;
@@ -437,6 +458,7 @@ declare const cloudContract: {
         base: "base";
         change_request: "change_request";
         file: "file";
+        node: "node";
         record: "record";
       }>;
       title: z.ZodString;
@@ -445,6 +467,7 @@ declare const cloudContract: {
       href: z.ZodString;
       updatedAt: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    contentTruncated: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   grep: import("@orpc/contract").ContractProcedure<z.ZodObject<{
     pattern: z.ZodString;
@@ -570,6 +593,14 @@ declare const cloudContract: {
     }, z.core.$strip>, z.ZodObject<{
       isDescendant: z.ZodBoolean;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    ancestors: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+      type: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+      }>>;
+    }, z.core.$strip>, z.ZodObject<{
+      ancestorIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     createChangeRequest: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -14425,7 +14456,12 @@ declare const cloudContract: {
       deletedSessionCount: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     connections: {
-      list: import("@orpc/contract").ContractProcedure<import("@orpc/contract").Schema<unknown, unknown>, z.ZodArray<z.ZodObject<{
+      list: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+        scope: z.ZodDefault<z.ZodEnum<{
+          mine: "mine";
+          space: "space";
+        }>>;
+      }, z.core.$strip>, z.ZodArray<z.ZodObject<{
         slug: z.ZodString;
         agentName: z.ZodString;
         transport: z.ZodEnum<{
@@ -14453,6 +14489,7 @@ declare const cloudContract: {
           lastActivityAt: z.ZodString;
           error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>;
+        ownedByCurrentUser: z.ZodBoolean;
       }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     };
     sessions: {
@@ -14504,10 +14541,12 @@ declare const cloudContract: {
         attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
           kind: z.ZodEnum<{
             audio: "audio";
+            file: "file";
             image: "image";
           }>;
           data: z.ZodString;
           mimeType: z.ZodString;
+          filename: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
       }, z.core.$strip>, z.ZodObject<{
         accepted: z.ZodBoolean;
@@ -15086,7 +15125,9 @@ declare const cloudContract: {
       textContentHash: z.ZodNullable<z.ZodString>;
       byteCount: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
-    importBegin: import("@orpc/contract").ContractProcedure<import("@orpc/contract").Schema<unknown, unknown>, z.ZodObject<{
+    importBegin: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      sourceSpaceId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
       sessionId: z.ZodString;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     importTables: import("@orpc/contract").ContractProcedure<z.ZodObject<{
@@ -24581,7 +24622,7 @@ type OperationStatus = "pending" | "merged" | "archived" | "failed";
 type ChangeRequestTargetType = "base" | "node";
 type BusabaseSourceChannel = "web_ui" | "browser" | "openapi" | "sdk" | "cli" | "mcp" | "skill" | "webhook" | "automation" | "import";
 type ReviewVerdict = "approved" | "rejected";
-type SearchResultKind = "record" | "change_request" | "base" | "file";
+type SearchResultKind = "record" | "change_request" | "base" | "file" | "node";
 type CommentSubjectType = "record" | "change_request" | "operation" | "commit";
 type AuditAction = "record.viewed" | "change_request.created" | "change_request.updated" | "change_request.deleted" | "change_request.reviewed" | "change_request.merged" | "base.created" | "field.created" | "doc.created" | "doc.updated" | "file.created" | "skill.created" | "drive.created" | "airapp.created" | "asset.deleted" | "asset.metadata_updated" | "asset.text_written" | "asset.text_marked_none" | "node.metadata_updated" | "node.purged";
 interface UserRefVO {
@@ -24800,6 +24841,12 @@ interface SearchResponseVO {
   offset: number;
   hasMore: boolean;
   results: SearchResultVO[];
+  /**
+   * True when some in-scope node content was indexed only up to the projection
+   * cap, so this search could not see all of it. Lets a client report an empty
+   * result honestly instead of implying the workspace lacks the phrase.
+   */
+  contentTruncated: boolean;
 }
 interface AuditEventVO {
   id: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-DF6mrd6D.js";
+import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-CVz2pqrF.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**
@@ -317,13 +317,14 @@ declare class Busabase {
     hasMore: boolean;
     results: {
       id: string;
-      kind: "base" | "change_request" | "file" | "record";
+      kind: "base" | "change_request" | "file" | "node" | "record";
       title: string;
       body: string;
       eyebrow: string;
       href: string;
       updatedAt: string | null;
     }[];
+    contentTruncated: boolean;
   }, Error>;
   /**
    * Unified grep — one regex/literal pattern scanned across every in-scope

package/dist/index.js

@@ -136,13 +136,15 @@ const AgentSessionVOSchema = z.object({
 	/** Set when status is "failed"; surfaced verbatim to the user. */
 	error: z.string().nullable().default(null)
 });
-/** One connected agent backend in the current space and authenticated user's scope. */
+/** One connected agent backend visible in the requested workspace scope. */
 const AgentConnectionVOSchema = z.object({
 	slug: z.string(),
 	agentName: z.string(),
 	transport: AgentTransportSchema,
 	sessionCount: z.number().int().nonnegative(),
-	latest: AgentSessionVOSchema.nullable()
+	latest: AgentSessionVOSchema.nullable(),
+	/** Controls owner-only actions such as deleting the saved OAuth grant. */
+	ownedByCurrentUser: z.boolean()
 });
 /**
 * One streamed event from a session.
@@ -178,17 +180,34 @@ const AgentSessionEventVOSchema = z.object({
 	permissionOptionId: z.string().optional(),
 	at: z.string()
 });
+const AgentConnectionScopeSchema = z.enum(["mine", "space"]);
+const ListAgentConnectionsInputSchema = z.object({ scope: AgentConnectionScopeSchema.default("mine") });
 const CreateAgentSessionInputSchema = z.object({ 
 /** Must name a catalog entry. Deliberately NOT a command line — see below. */
 slug: z.string().min(1) });
 const DisconnectAgentInputSchema = z.object({ 
 /** The exact connected-agent slug shown by the sessions/catalog surfaces. */
 slug: z.string().min(1) });
-/** Base64 image/audio the browser attached — ACP's `ImageContent`/`AudioContent` shape verbatim. */
+/**
+* A base64 payload the browser attached.
+*
+* `image`/`audio` map to ACP's `ImageContent`/`AudioContent` verbatim; `file`
+* is everything else (a PDF, a spreadsheet, a Markdown note) and becomes an
+* ACP embedded `resource` block at send time. `data` is base64 for every kind
+* — including textual files — so the browser never has to guess an encoding;
+* whether a file travels to the agent as ACP text or as an ACP blob is decided
+* server-side from the payload itself.
+*/
 const PromptAttachmentInputSchema = z.object({
-	kind: z.enum(["image", "audio"]),
-	data: z.string().min(1),
-	mimeType: z.string().min(1)
+	kind: z.enum([
+		"image",
+		"audio",
+		"file"
+	]),
+	data: z.string().min(1).max(2e7),
+	mimeType: z.string().min(1),
+	/** The original filename, carried for `file` so the agent and the transcript can name it. */
+	filename: z.string().max(255).optional()
 });
 const PromptAgentSessionInputSchema = z.object({
 	sessionId: z.string().min(1),
@@ -219,8 +238,8 @@ const agentsContract = {
 		deletedSessionCount: z.number().int().nonnegative()
 	})),
 	connections: { 
-	/** Connected backends, scoped to the current space and authenticated user. */
-list: oc.output(AgentConnectionVOSchema.array()) },
+	/** Connected backends in the current user's personal or active-space scope. */
+list: oc.input(ListAgentConnectionsInputSchema).output(AgentConnectionVOSchema.array()) },
 	sessions: {
 		list: oc.output(AgentSessionVOSchema.array()),
 		create: oc.input(CreateAgentSessionInputSchema).output(AgentSessionVOSchema),
@@ -663,7 +682,8 @@ const makeFileTreeNodeType = (config) => ({
 	icon: config.icon,
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: config.publicAccess
 	},
 	operations: fileTreeOperations(config.type)
 });
@@ -681,7 +701,8 @@ const airappNodeType = makeFileTreeNodeType({
 	icon: "app-window",
 	routeBase: "airapps",
 	tag: "AirApps",
-	entryFile: "package.json"
+	entryFile: "package.json",
+	publicAccess: "no"
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/base/definition.ts
@@ -692,7 +713,8 @@ const baseNodeType = {
 	icon: "table",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "detail"
 	},
 	operations: [
 		{
@@ -795,7 +817,8 @@ const docNodeType = {
 	icon: "file-text",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "detail"
 	},
 	operations: [{
 		kind: "doc_update",
@@ -812,7 +835,8 @@ const driveNodeType = makeFileTreeNodeType({
 	icon: "hard-drive",
 	routeBase: "drives",
 	tag: "Drives",
-	entryFile: "README.md"
+	entryFile: "README.md",
+	publicAccess: "no"
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/file-node/definition.ts
@@ -824,7 +848,8 @@ const fileNodeType = {
 	icon: "file",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "detail"
 	},
 	operations: []
 };
@@ -839,7 +864,8 @@ const folderNodeType = {
 	capabilities: {
 		container: true,
 		creatable: true,
-		hasDetail: true
+		hasDetail: true,
+		publicAccess: "detail"
 	},
 	operations: []
 };
@@ -860,7 +886,8 @@ const formNodeType = {
 	icon: "form",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "submit"
 	},
 	operations: []
 };
@@ -879,7 +906,8 @@ const htmlNodeType = {
 	icon: "code-xml",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "no"
 	},
 	operations: [{
 		kind: "html_document_update",
@@ -896,7 +924,8 @@ const skillNodeType = makeFileTreeNodeType({
 	icon: "sparkles",
 	routeBase: "skills",
 	tag: "Skills",
-	entryFile: "SKILL.md"
+	entryFile: "SKILL.md",
+	publicAccess: "no"
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/whiteboard/definition.ts
@@ -912,7 +941,8 @@ const whiteboardNodeType = {
 	icon: "pen-tool",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "detail"
 	},
 	operations: [{
 		kind: "whiteboard_document_update",
@@ -935,7 +965,8 @@ const workflowNodeType = {
 	icon: "workflow",
 	capabilities: {
 		hasDetail: true,
-		creatable: true
+		creatable: true,
+		publicAccess: "detail"
 	},
 	operations: [{
 		kind: "workflow_document_update",
@@ -1293,11 +1324,18 @@ const agentTaskSchema = z.object({
 });
 const searchResultSchema = z.object({
 	id: z.string(),
+	/**
+	* `node` covers the CONTENT of a content-bearing node (doc / html /
+	* whiteboard / workflow). Purely additive — callers that do not know it can
+	* ignore the kind, and callers that never asked for it (an explicit
+	* `sources` list without `nodes`) never receive it.
+	*/
 	kind: z.enum([
 		"record",
 		"change_request",
 		"base",
-		"file"
+		"file",
+		"node"
 	]),
 	title: z.string(),
 	body: z.string(),
@@ -1310,7 +1348,17 @@ const searchResponseSchema = z.object({
 	limit: z.number(),
 	offset: z.number(),
 	hasMore: z.boolean(),
-	results: z.array(searchResultSchema)
+	results: z.array(searchResultSchema),
+	/**
+	* True when at least one in-scope node's content was indexed only up to the
+	* projection cap, so this search could not see all of it.
+	*
+	* Exists so an empty result can be reported honestly: without it, "no
+	* results" is ambiguous between "the workspace does not contain this" and
+	* "we did not look at all of it". Clients should surface it — and point at
+	* `grep`, which has no such cap — rather than implying absence.
+	*/
+	contentTruncated: z.boolean().default(false)
 });
 const liveEventSchema = z.object({
 	kind: z.enum([
@@ -1523,7 +1571,8 @@ const inboxSnapshotResponseSchema = listChangeRequestsPageResponseSchema.extend(
 const SEARCH_SOURCES = [
 	"records",
 	"files",
-	"names"
+	"names",
+	"nodes"
 ];
 const searchInputSchema = z.object({
 	query: z.string().default(""),
@@ -2791,6 +2840,19 @@ const ExportAssetTextVOSchema = z.object({
 	textContentHash: z.string().nullable(),
 	byteCount: z.number().int().nonnegative()
 });
+const ImportBeginInputSchema = z.object({ 
+/**
+* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
+* in the `.bbdump`, already integrity-verified before this is called).
+* `importTableRows`'s "nodes" handling needs this to recognize the
+* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
+* scanning each batch's rows for "the one with a null `parentId`" only
+* works when that row happens to land in the SAME batch as its children,
+* which cursor pagination (id-ordered, not tree-ordered) does not
+* guarantee once a space has more nodes than one page. See the matching
+* comment in `import-logic.ts`.
+*/
+sourceSpaceId: z.string() });
 const ImportBeginVOSchema = z.object({ sessionId: z.string() });
 /**
 * `docBodies`, `attachmentBlobs` and `assetTextBlobs` are pseudo-tables: doc
@@ -2854,7 +2916,7 @@ const dumpContract = {
 		tags: ["Dump"],
 		summary: "Begin a full-fidelity import session",
 		successDescription: "Created an import session for the current space. Refused unless the space's node tree is empty (full-fidelity import preserves original ids and cannot merge into existing data)."
-	}).output(ImportBeginVOSchema),
+	}).input(ImportBeginInputSchema).output(ImportBeginVOSchema),
 	importTables: oc.route({
 		method: "POST",
 		path: "/dump/import/tables",
@@ -4233,6 +4295,14 @@ const NodeDetailVOSchema = z.discriminatedUnion("type", [
 * hint. An ambiguous slug with no `type` is refused rather than silently
 * resolved to whichever row sorts first.
 */
+/**
+* `nodes.ancestors` output — the node's ancestor ids, ROOT-FIRST, excluding
+* the node itself. Ids only, deliberately: the sidebar already has (or can
+* lazily fetch) each ancestor's own row, and it only needs to know WHICH
+* folders to expand. Returning full nodes here would duplicate `nodes.list`
+* and make a cheap navigational lookup expensive.
+*/
+const nodeAncestorsVOSchema = z.object({ ancestorIds: z.array(z.string()) });
 const getNodeInputSchema = z.object({
 	nodeId: z.string().describe("Node id, or a slug that is unique within its type."),
 	type: z.enum(NODE_TYPES).optional().describe("Optional disambiguation hint, only needed when `nodeId` is a slug that exists under more than one node type.")
@@ -4355,7 +4425,7 @@ const busabaseContractRoutes = {
 			path: "/nodes/search",
 			tags: ["Nodes", "Search"],
 			summary: "Search nodes by name/slug (cheap, name-only quick-jump)",
-			successDescription: "Plain ilike match on name/slug across every registered node type, scoped by the same node-visibility ACL as `nodes.list`. No content scan and no full-text ranking — ordered exact-slug-match first, then by name. Backs the dashboard search dialog's 'Recent' tab cache-miss path; the heavier `search` endpoint remains the dedicated full-text content search."
+			successDescription: "Plain ilike match on name/slug across every registered node type, scoped by the same node-visibility ACL as `nodes.list`. No content scan and no full-text ranking — ordered exact-slug-match first, then by name. Backs the dashboard search dialog's 'Recent' tab cache-miss path. To search what is written INSIDE nodes, use `search` with the `nodes` source (indexed, paginated) or `grep` (exhaustive, no index)."
 		}).input(searchNodesByNameInputSchema).output(z.array(nodeSearchResultSchema)),
 		isDescendant: oc.route({
 			method: "GET",
@@ -4364,6 +4434,13 @@ const busabaseContractRoutes = {
 			summary: "Check whether a node is a descendant of another",
 			successDescription: "Server-authoritative parentId-chain walk from nodeId up to potentialAncestorId. Used to gate cross-branch drag-and-drop drops in the sidebar, since the full tree is no longer guaranteed to be loaded client-side (depth-bounded lazy load) — a purely local walk could wrongly allow dropping a folder into its own unloaded descendant."
 		}).input(isDescendantInputSchema).output(isDescendantOutputSchema),
+		ancestors: oc.route({
+			method: "GET",
+			path: "/nodes/{nodeId}/ancestors",
+			tags: ["Nodes"],
+			summary: "List a node's ancestor ids",
+			successDescription: "The node's ancestor ids, root-first, excluding the node itself (`[]` directly under the workspace root). `nodeId` accepts an id or a slug, same as `nodes.get`; pass `type` when a slug exists under more than one type. Lets a depth-bounded, lazily-expanded tree open straight to a deep node on a cold load (a refresh, a bookmark, a shared link) without one round trip per level."
+		}).input(getNodeInputSchema).output(nodeAncestorsVOSchema),
 		createChangeRequest: oc.route({
 			method: "POST",
 			path: "/nodes/change-requests",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.20.0",
+  "version": "0.30.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -35,6 +35,10 @@
       "types": "./dist/airapp-node.d.ts",
       "default": "./dist/airapp-node.js"
     },
+    "./airapp-check": {
+      "types": "./dist/airapp-check.d.ts",
+      "default": "./dist/airapp-check.js"
+    },
     "./airapp": {
       "types": "./dist/airapp.d.ts",
       "default": "./dist/airapp.js"
@@ -63,7 +67,7 @@
     "tsx": "^4.20.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "busabase-contract": "0.20.0",
+    "busabase-contract": "0.30.0",
     "open-domains": "0.0.2",
     "openlib": "0.1.1"
   },