@k2b/cloud 0.6.0 → 0.7.0

package/README.md

@@ -78,9 +78,9 @@ A standard app declares four prefixes (`/api/<id>`, `/app/<id>`, `/admin/<id>`,
 
 ## Documentation
 
-Full walkthroughs, the per-app anatomy, deployment templates, and a reference app:
+Application setup, public contracts, and deployment guidance:
 
-- **[github.com/ValentinKolb/cloud-template](https://github.com/ValentinKolb/cloud-template)** — starter repo with a working reference app + the complete app-authoring guide
+- **[Create the first application](https://github.com/k2b-dev/cloud/blob/main/docs-site/docs/en/build/getting-started.md)** — standalone project setup and a verified API endpoint
 - **[github.com/k2b-dev/cloud](https://github.com/k2b-dev/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -18,7 +18,8 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.integration.test.ts",
-    "!scripts/**/*.test.ts"
+    "!scripts/**/*.test.ts",
+    "!scripts/runtime-recovery-*.ts"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -31,9 +32,13 @@
     "./browser/live": "./src/browser/live-websocket.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
+    "./browser/commands": "./src/browser/commands.ts",
+    "./browser/search": "./src/browser/search.ts",
+    "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
+    "./capabilities/store": "./src/capabilities/executions.ts",
     "./capabilities/testing": "./src/capabilities/testing.ts",
     "./cli": "./src/cli/index.ts",
     "./cli/access": "./src/cli/access.ts",
@@ -59,6 +64,7 @@
     "./access/ui": "./src/access/ui.ts",
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
+    "./ssr/WorkspaceNavigation.island": "./src/ssr/WorkspaceNavigation.island.tsx",
     "./ssr/*": "./src/ssr/*",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
@@ -77,19 +83,22 @@
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
-    "test": "bun test",
+    "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.tsx' --path-ignore-patterns '**/*.dom.test.tsx' && bun run test:dom",
+    "test:dom": "bun test --isolate --conditions=browser --preload ../ui/test/solid-dom-preload.ts behavior.test.tsx dom.test.tsx",
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
   },
   "dependencies": {
     "@firecrawl/anydoc": "0.1.9",
+    "@napi-rs/canvas": "1.0.8",
+    "pdfjs-dist": "6.3.289",
     "@hono/standard-validator": "0.2.2",
     "@simplewebauthn/server": "13.3.2",
     "@tabler/icons": "3.46.0",
     "@tailwindcss/typography": "0.5.20",
-    "@k2b/nessi": "0.11.0",
-    "@k2b/ssr": "0.12.0",
-    "@k2b/ui": "0.2.0",
-    "@k2b/stdlib": "0.22.0",
+    "@k2b/nessi": "0.12.0",
+    "@k2b/ssr": "0.14.0",
+    "@k2b/ui": "0.3.0",
+    "@k2b/stdlib": "0.25.0",
     "@k2b/sync": "6.4.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
@@ -107,6 +116,7 @@
     "seroval": "1.6.0",
     "tailwindcss": "4.3.3",
     "web-push": "3.6.7",
+    "web-vitals": "6.2.1",
     "yaml": "2.9.0",
     "hash-wasm": "4.12.0",
     "@types/nodemailer": "7.0.12",
@@ -116,12 +126,12 @@
   "devDependencies": {
     "@babel/core": "7.29.7",
     "@babel/preset-typescript": "7.29.7",
-    "@types/bun": "1.3.14",
+    "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.12",
     "hono": "4.12.32",
     "solid-js": "1.9.14",
     "typescript": "5.9.3",
-    "zod": "4.4.3"
+    "zod": "4.6.2"
   },
   "peerDependencies": {
     "hono": "^4.12.25",

package/scripts/browser-performance.ts

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { WEB_VITALS_ASSET_NAME } from "../src/_internal/web-vitals-asset";
+
+export async function buildBrowserPerformance(publicDir: string, appId: string): Promise<void> {
+  if (appId !== "core") return;
+  const result = await Bun.build({
+    entrypoints: [resolve(import.meta.dir, "../src/browser/web-vitals.ts")],
+    outdir: publicDir,
+    naming: WEB_VITALS_ASSET_NAME,
+    target: "browser",
+    minify: true,
+  });
+  if (!result.success) throw new AggregateError(result.logs, "Browser performance build failed");
+}

package/scripts/build-pdf-renderer.ts

@@ -0,0 +1,39 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Package the decoder and native assets only for bundles importing PDF vision. */
+export async function buildPdfRenderer(dist: string) {
+  const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const out = resolve(dist, "pdf-render");
+  await mkdir(out, { recursive: true });
+  const worker = await Bun.build({
+    entrypoints: [resolve(framework, "src/ai/pdf-render-worker.ts")],
+    target: "bun",
+    outdir: out,
+    naming: "worker.js",
+    external: ["pdfjs-dist", "@napi-rs/canvas"],
+  });
+  if (!worker.success) throw new Error(`PDF decoder build failed: ${worker.logs.join("\n")}`);
+  for (const name of ["pdfjs-dist", "@napi-rs/canvas"]) {
+    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
+    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
+    if (name !== "@napi-rs/canvas") continue;
+    const manifest = z
+      .object({ optionalDependencies: z.record(z.string(), z.string()) })
+      .parse(await Bun.file(resolve(source, "package.json")).json());
+    let nativePackages = 0;
+    for (const dependency of Object.keys(manifest.optionalDependencies)) {
+      let location: string;
+      try {
+        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
+      } catch {
+        continue;
+      } // Only the installed target-platform binary is needed.
+      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
+      nativePackages++;
+    }
+    if (!nativePackages) throw new Error("PDF decoder needs an installed native canvas binary for the build platform.");
+  }
+}

package/scripts/build.ts

@@ -4,11 +4,11 @@
  * Two consumer shapes:
  *
  *   Monorepo (this repo):
- *     APP_ID=<id> bun run packages/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> bun run packages/cloud/scripts/build.ts
  *     # appDir defaults to packages/<APP_ID>, run from workspace root.
  *
  *   Standalone (npm consumer, see cloud-template):
- *     APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
  *     # appDir = APP_DIR (resolved against cwd) and must be the directory
  *     # that CONTAINS src/, since entrypoints resolve to <appDir>/src/*.
  *
@@ -22,20 +22,21 @@
  * it ships a `scripts/build-extras.ts` that this script runs at the end.
  */
 import { existsSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
-import { CryptoHasher, Glob } from "bun";
+import { Glob } from "bun";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
+import { buildPdfRenderer } from "./build-pdf-renderer";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
 
-// `root` = wherever the user is building from. SSR plugin's rootDir is
-// process.cwd() (set in defineApp), so we use the same here for hash parity.
+// Build output is relative to the consuming project, including npm consumers.
 const root = process.cwd();
 
 // Framework dir — works whether this script is in packages/cloud/scripts/
@@ -59,6 +60,8 @@ const syncVersion = syncPackage.version;
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const dist = resolve(root, "dist");
 const distPublic = resolve(dist, "public");
@@ -68,14 +71,6 @@ const compressGzip = promisify(gzip);
 await rm(dist, { recursive: true, force: true });
 await mkdir(distPublic, { recursive: true });
 
-// Mirrors @k2b/ssr's island-id (md5 of POSIX path relative to the
-// SSR plugin's rootDir, truncated to 12 chars). Both this script and the
-// plugin use process.cwd() as the rootDir, so hashes match.
-const islandId = (file: string): string => {
-  const rel = file.slice(root.length + 1).replace(/\\/g, "/");
-  return new CryptoHasher("md5").update(rel).digest("hex").slice(0, 12);
-};
-
 const compressibleExtensions = new Set([".css", ".html", ".js", ".json", ".map", ".svg", ".txt", ".xml"]);
 
 async function precompressDistAssets(dir: string): Promise<void> {
@@ -124,11 +119,13 @@ try {
     naming: "server.js",
     target: "bun",
     minify: true,
+    metafile: true,
     define: {
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
+      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
     },
-    plugins: [plugin()],
+    plugins: [(app?.plugin ?? plugin)()],
   });
 } finally {
   await rm(serverEntry, { force: true });
@@ -137,26 +134,8 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-
-// 1b. The SSR plugin scans the project root and emits one chunk per island
-//     across every reachable package (including any island-shaped files in
-//     other workspace packages or in node_modules). Keep only this app's own
-//     islands plus the framework's; drop the rest. chunk-* files are shared
-//     splits and always kept.
-const ssrDir = resolve(dist, "_ssr");
-if (existsSync(ssrDir)) {
-  const allowedDirs = [frameworkDir, appDir];
-  const allowedIds = new Set<string>();
-  for (const dir of allowedDirs) {
-    for await (const file of new Glob("**/*.{island,client}.tsx").scan({ cwd: dir, absolute: true })) {
-      allowedIds.add(islandId(file));
-    }
-  }
-  for (const entry of await readdir(ssrDir)) {
-    if (entry.startsWith("chunk-") || !entry.endsWith(".js")) continue;
-    const id = entry.slice(0, -3);
-    if (!allowedIds.has(id)) await rm(resolve(ssrDir, entry));
-  }
+if (Object.keys(server.metafile?.inputs ?? {}).some(path => path.endsWith("/ai/pdf-render.ts"))) {
+  await buildPdfRenderer(dist);
 }
 
 // 2. Per-app Tailwind stylesheet.
@@ -199,6 +178,7 @@ if (existsSync(extras)) {
   await import(extras);
 }
 
+await buildBrowserPerformance(distPublic, appId);
 await precompressDistAssets(resolve(dist, "public"));
 await precompressDistAssets(resolve(dist, "_ssr"));
 

package/scripts/preload.ts

@@ -23,6 +23,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
 
 const appId = process.env.APP_ID ?? "core";
 
@@ -38,9 +39,11 @@ const frameworkDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const { app, plugin } = await import(resolve(appDir, "src/config"));
-Bun.plugin(plugin());
+Bun.plugin((app?.plugin ?? plugin)());
 
 // ── Build CSS ───────────────────────────────────────────────────────────────
 const publicDir = resolve(root, "public");
@@ -125,15 +128,6 @@ if (appId === "core" && existsSync(globalCssEntry)) {
   await cp(resolve(frameworkDir, "public/logo.svg"), resolve(publicDir, "logo.svg"));
 }
 
-// katex.css is only needed by notebooks (served by core via Traefik /public/katex.css)
-if (appId === "notebooks") {
-  try {
-    await cp(resolve(root, "node_modules/katex/dist/katex.min.css"), resolve(publicDir, "katex.css"));
-  } catch {
-    console.warn("[preload] katex.css not found, skipping");
-  }
-}
-
 // Each app builds its own app.css
 const appPublicDir = resolve(publicDir, appId);
 await mkdir(appPublicDir, { recursive: true });
@@ -146,9 +140,12 @@ if (appId !== "core" && app) {
   });
 }
 
-await buildAppCss();
+if (existsSync(appCssPath)) {
+  await buildAppCss();
+  watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+}
+await buildBrowserPerformance(publicDir, appId);
 
-watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
 if (appId === "core" && existsSync(globalCssEntry)) {
   watchDevCss("global.css", [globalCssEntry, resolve(frameworkDir, "src/styles")], buildGlobalCss);
 }

package/scripts/sync-recovery-smoke.ts

@@ -7,6 +7,7 @@
  * No provider or application-domain effects; successful recovery deletes only
  * the exact test streams after checking their broker identity metadata.
  */
+import { env } from "../src/config/env";
 import { createSync, type SyncResourceSummary, type Worker } from "@k2b/sync";
 import { connect, type NatsConnection } from "@nats-io/transport-node";
 
@@ -57,7 +58,7 @@ export const main = async (): Promise<void> => {
     .map((value) => value.trim())
     .filter(Boolean);
   const connection = await connect({ servers, name: `${APPLICATION}-${phase}`, ignoreClusterUpdates: true });
-  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: 3 } });
+  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: env.SYNC_REPLICAS } });
   const job = sync.job<{ preparedAt: string }>({
     id: JOB_ID,
     delivery: { ackWaitMs: 30_000, maxAttempts: 3, backoffMs: [1_000, 2_000] },

package/src/_internal/app-presentation.ts

@@ -11,12 +11,12 @@ const text = (value: string, label: string, max = MAX_SHORT_TEXT): string => {
   return normalized;
 };
 
-const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string) => {
+const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string, max = MAX_SHORT_TEXT) => {
   if (!values) return undefined;
   const normalized: Record<string, string> = {};
   for (const [key, value] of Object.entries(values)) {
     if (!allowed.has(key)) throw new Error(`${label} contains unknown key ${JSON.stringify(key)}`);
-    normalized[key] = text(value, `${label}.${key}`);
+    normalized[key] = text(value, `${label}.${key}`, max);
   }
   return normalized;
 };
@@ -34,6 +34,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
     groupIds.add(group.id);
   }
   const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
+  const searchHrefs = new Set((app.searchLinks ?? []).map((link) => link.href));
   const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
   const translations: Record<string, AppPresentationTranslation> = {};
 
@@ -49,6 +50,17 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
         : {}),
       ...(translation.adminGroups ? { adminGroups: labels(translation.adminGroups, groupIds, `${canonical}.adminGroups`) } : {}),
       ...(translation.adminLinks ? { adminLinks: labels(translation.adminLinks, adminHrefs, `${canonical}.adminLinks`) } : {}),
+      ...(translation.searchLinks ? { searchLinks: labels(translation.searchLinks, searchHrefs, `${canonical}.searchLinks`) } : {}),
+      ...(translation.searchLinkDescriptions
+        ? {
+            searchLinkDescriptions: labels(
+              translation.searchLinkDescriptions,
+              searchHrefs,
+              `${canonical}.searchLinkDescriptions`,
+              MAX_DESCRIPTION,
+            ),
+          }
+        : {}),
       ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
     };
   }

package/src/_internal/capabilities.ts

@@ -11,6 +11,8 @@ import {
   type CapabilityActionReviewResult,
   CapabilityActionReviewSchema,
   type CapabilityDefinitions,
+  type CapabilityCommandManifest,
+  CapabilityCommandManifestSchema,
   type CapabilityError,
   CapabilityErrorSchema,
   type CapabilityExecutionContext,
@@ -190,12 +192,14 @@ const compileSchemaPresentation = (
 
 const compileOperationPresentation = (
   value: unknown,
-  operation: CapabilityQueryManifest | CapabilityActionManifest,
+  operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
   label: string,
 ): CapabilityOperationPresentationTranslation => {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const translation = value as Record<string, unknown>;
-  const allowed = new Set(["title", "description", "input", "data", "searchTags"]);
+  const allowed = new Set(
+    "path" in operation ? ["title", "description", "input"] : ["title", "description", "input", "data", "searchTags"],
+  );
   const extra = Object.keys(translation).find((key) => !allowed.has(key));
   if (extra) throw new Error(`${label} contains unsupported field "${extra}"`);
   if (translation.title !== undefined) {
@@ -238,7 +242,7 @@ const compileOperationPresentation = (
     );
   }
   const input = compileSchemaPresentation(translation.input, operation.inputSchema, `${label}.input`);
-  const data = compileSchemaPresentation(translation.data, operation.dataSchema, `${label}.data`);
+  const data = "dataSchema" in operation ? compileSchemaPresentation(translation.data, operation.dataSchema, `${label}.data`) : undefined;
   return {
     ...(typeof translation.title === "string" ? { title: translation.title.trim() } : {}),
     ...(typeof translation.description === "string" ? { description: translation.description.trim() } : {}),
@@ -263,6 +267,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
   const types = new Map(manifest.types.map((type) => [type.localId, type]));
   const queries = new Map(manifest.queries.map((operation) => [operation.localId, operation]));
   const actions = new Map(manifest.actions.map((operation) => [operation.localId, operation]));
+  const commands = new Map(manifest.commands.map((operation) => [operation.localId, operation]));
   const translations: Record<string, CapabilityPresentationTranslation> = {};
   for (const [locale, rawTranslation] of Object.entries(catalog.translations as Record<string, unknown>)) {
     const canonical = canonicalLocale(locale);
@@ -273,7 +278,7 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
       throw new Error(`Capability presentation translation ${canonical} must be an object`);
     }
     const raw = rawTranslation as Record<string, unknown>;
-    const extra = Object.keys(raw).find((key) => key !== "types" && key !== "queries" && key !== "actions");
+    const extra = Object.keys(raw).find((key) => key !== "types" && key !== "queries" && key !== "actions" && key !== "commands");
     if (extra) throw new Error(`Capability presentation translation ${canonical} contains unsupported field "${extra}"`);
     const compileGroup = <T>(
       group: unknown,
@@ -311,10 +316,12 @@ export const compileCapabilityPresentation = (manifest: CapabilityManifest, valu
     });
     const translatedQueries = compileGroup(raw.queries, queries, "Query", compileOperationPresentation);
     const translatedActions = compileGroup(raw.actions, actions, "Action", compileOperationPresentation);
+    const translatedCommands = compileGroup(raw.commands, commands, "Command", compileOperationPresentation);
     translations[canonical] = {
       ...(translatedTypes ? { types: translatedTypes } : {}),
       ...(translatedQueries ? { queries: translatedQueries } : {}),
       ...(translatedActions ? { actions: translatedActions } : {}),
+      ...(translatedCommands ? { commands: translatedCommands } : {}),
     };
   }
   return { baseLocale, translations };
@@ -406,7 +413,7 @@ const normalizeSearchTags = (definition: CapabilityQueryDefinition, label: strin
       ...(aliases.length > 0 ? { aliases } : {}),
     };
   });
-  return { tags };
+  return { tags, ...(definition.universalSearch.scopeTypes ? { scopeTypes: [...new Set(definition.universalSearch.scopeTypes)] } : {}) };
 };
 
 const compileOperationSchemas = (definition: CapabilityQueryDefinition | CapabilityActionDefinition, label: string) => {
@@ -426,7 +433,7 @@ const compileOperationSchemas = (definition: CapabilityQueryDefinition | Capabil
     inputSchema,
     dataSchema,
     resultZodSchema,
-    schemaHash: capabilityHash({ inputSchema, dataSchema }),
+    schemaHash: capabilityHash({ inputSchema, dataSchema, ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}) }),
   };
 };
 
@@ -462,6 +469,8 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
   for (const [localId, definition] of Object.entries(definitions.queries ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
     registerLocalId(localId, "Query");
     const label = `Query ${localId}`;
+    if (definition.stream && ((definition.stream.direction === "write" && !("idempotency" in definition)) || definition.stream.maxBytes <= 0)) throw new Error(`${label}: write streams require an Action and a positive byte budget`);
+    if (definition.stream?.direction === "write" && "idempotency" in definition && definition.idempotency !== "required") throw new Error(`${label}: write streams require idempotency`);
     const schemas = compileOperationSchemas(definition, label);
     if (definition.universalSearch) {
       const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
@@ -480,9 +489,13 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       openWorld: definition.openWorld,
       universalSearch: normalizeSearchTags(definition, label),
     } satisfies CapabilityQueryManifest;
+    for (const type of manifest.universalSearch?.scopeTypes ?? []) {
+      if (!typeIds.has(qualifiedId(appId, type))) throw new Error(`${label} declares an unknown search scope type ${type}`);
+    }
     queries.set(localId, {
       definition,
       manifest,
@@ -499,12 +512,36 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
   for (const [localId, definition] of Object.entries(definitions.actions ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
     registerLocalId(localId, "Action");
     const label = `Action ${localId}`;
+    // Declaration rule, documented in docs/platform/capabilities.md:
+    // destructive means irreversible or externally visible. An irreversible or
+    // open-world effect must always be reviewable and safely repeatable, and
+    // must never be approved once and then replayed silently.
+    if (definition.destructive && !definition.review) {
+      throw new Error(`${label} is destructive and must declare review()`);
+    }
+    if (definition.destructive && definition.idempotency !== "required") {
+      throw new Error(`${label} is destructive and must declare idempotency: "required"`);
+    }
+    if (definition.openWorld && !definition.review) {
+      throw new Error(`${label} is open-world and must declare review()`);
+    }
+    if (definition.openWorld && definition.idempotency !== "required") {
+      throw new Error(`${label} is open-world and must declare idempotency: "required"`);
+    }
     if (definition.approval === "rememberable" && definition.openWorld) {
       throw new Error(`${label} cannot remember approval for an open-world effect`);
     }
+    if (definition.approval === "rememberable" && definition.destructive) {
+      throw new Error(`${label} cannot remember approval for a destructive effect`);
+    }
+    if (definition.approval === "none" && (definition.destructive || definition.openWorld)) {
+      throw new Error(`${label} cannot skip approval for destructive or open-world effects`);
+    }
     if (definition.approval === "rememberable" && !definition.review) {
       throw new Error(`${label} must provide a review before approval can be remembered`);
     }
+    if (definition.stream && ((definition.stream.direction === "write" && !("idempotency" in definition)) || definition.stream.maxBytes <= 0)) throw new Error(`${label}: write streams require an Action and a positive byte budget`);
+    if (definition.stream?.direction === "write" && "idempotency" in definition && definition.idempotency !== "required") throw new Error(`${label}: write streams require idempotency`);
     const schemas = compileOperationSchemas(definition, label);
     const manifest = {
       localId,
@@ -513,6 +550,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       destructive: definition.destructive,
       openWorld: definition.openWorld,
       idempotency: definition.idempotency,
@@ -526,12 +564,30 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     });
   }
 
+  const commands = Object.entries(definitions.commands ?? {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([localId, definition]) => {
+      registerLocalId(localId, "Command");
+      const inputSchema = projectSchema(definition.input, `Command ${localId} input`, "input");
+      assertClosedObjectInput(inputSchema, `Command ${localId} input`);
+      return CapabilityCommandManifestSchema.parse({
+        localId,
+        title: definition.title.trim(),
+        description: definition.description.trim(),
+        icon: definition.icon,
+        keywords: [...(definition.keywords ?? [])],
+        inputSchema,
+        path: definition.path,
+      });
+    });
+
   const manifestBase = {
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
     appId,
     types,
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
+    commands,
   };
   const manifest = CapabilityManifestSchema.parse({
     ...manifestBase,
@@ -614,6 +670,7 @@ export const resolveCapabilityManifestPresentation = (
           ...(operation.universalSearch
             ? {
                 universalSearch: {
+                  ...operation.universalSearch,
                   tags: operation.universalSearch.tags.map((tag) => {
                     const tagCopy = copy.searchTags?.[tag.tag];
                     return tagCopy
@@ -625,6 +682,17 @@ export const resolveCapabilityManifestPresentation = (
             : {}),
         };
       }),
+      commands: current.commands.map((operation) => {
+        const copy = translation.commands?.[operation.localId];
+        return copy
+          ? {
+              ...operation,
+              title: copy.title ?? operation.title,
+              description: copy.description ?? operation.description,
+              inputSchema: applySchemaPresentation(operation.inputSchema, copy.input),
+            }
+          : operation;
+      }),
       actions: current.actions.map((operation) => {
         const copy = translation.actions?.[operation.localId];
         return copy
@@ -668,10 +736,19 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
       );
     }
     assertClosedObjectInput(inputSchema, `Operation ${operation.localId} input`);
-    const expectedSchemaHash = capabilityHash({ inputSchema: operation.inputSchema, dataSchema: operation.dataSchema });
+    if (
+      operation.stream?.direction === "write" &&
+      (!("idempotency" in operation) || operation.idempotency !== "required")
+    ) {
+      throw new Error(`Operation ${operation.localId} write streams require an idempotent Action`);
+    }
+    const expectedSchemaHash = capabilityHash({ inputSchema: operation.inputSchema, dataSchema: operation.dataSchema, ...(operation.stream ? { stream: operation.stream } : {}) });
     if (operation.schemaHash !== expectedSchemaHash)
       throw new Error(`Operation ${operation.localId} schemaHash does not match its schemas`);
     if ("universalSearch" in operation && operation.universalSearch) {
+      for (const type of operation.universalSearch.scopeTypes ?? []) {
+        if (!manifest.types.some((entry) => entry.localId === type)) throw new Error(`Unknown search scope type ${type}`);
+      }
       const expectedInput = projectSchema(UniversalSearchInputSchema, "Universal Search input", "input");
       const expectedData = projectSchema(UniversalSearchDataSchema, "Universal Search data", "output");
       if (
@@ -682,6 +759,11 @@ export const parseCapabilityManifest = (value: unknown, expectedAppId: string):
       }
     }
   }
+  for (const command of manifest.commands) {
+    registerLocalId(command.localId, "Command");
+    z.fromJSONSchema(structuredClone(command.inputSchema));
+    assertClosedObjectInput(command.inputSchema, `Command ${command.localId} input`);
+  }
   const queries = new Map(manifest.queries.map((query) => [query.localId, query]));
   for (const type of manifest.types) {
     if (!type.reader) continue;
@@ -787,6 +869,12 @@ export const capabilityManifestEvolutionIssues = (previous: CapabilityManifest,
     else if (type.reader && current.reader !== type.reader) issues.push(`Type ${type.localId} reader changed`);
   }
 
+  const nextCommands = new Map(next.commands.map((command) => [command.localId, command]));
+  for (const command of previous.commands) {
+    const current = nextCommands.get(command.localId);
+    if (!current) issues.push(`Command ${command.localId} was removed`);
+    else issues.push(...schemaEvolutionIssues(command.inputSchema, current.inputSchema, `Command ${command.localId} input`, "input"));
+  }
   const nextQueries = new Map(next.queries.map((operation) => [operation.localId, operation]));
   const nextActions = new Map(next.actions.map((operation) => [operation.localId, operation]));
   for (const operation of previous.queries) {
@@ -982,11 +1070,24 @@ export const invokeCompiledCapability = async (params: {
       },
     };
   }
+  if ("universalSearch" in operation.manifest && operation.manifest.universalSearch) {
+    const search = UniversalSearchInputSchema.parse(input.data);
+    if (
+      search.scope &&
+      !(operation.manifest.universalSearch.scopeTypes ?? []).some(
+        (type) => qualifiedId(params.compiled.manifest.appId, type) === search.scope!.type,
+      )
+    )
+      return { ok: false, error: { code: "VALIDATION_FAILED", message: "Unsupported search scope", status: 400 } };
+  }
   try {
     const invoked = await operation.definition.run(input.data, context);
     if (!invoked.ok) {
       return normalizeProviderError(invoked.error, "Capability returned an invalid error", params.onUnexpectedError);
     }
+    const stream = invoked.data.stream;
+    if (stream && (Buffer.byteLength(stream.id) > 2048 || !operation.definition.stream || stream.direction !== operation.definition.stream.direction || stream.size > operation.definition.stream.maxBytes || Date.parse(stream.expiresAt) <= Date.now() || Date.parse(stream.expiresAt) > Date.now() + 86_400_000))
+      return invalidProviderError("Stream is outside its declared policy or 24 hour lifetime");
     const validated = validateCapabilityResult(params.compiled, operation, invoked.data, params.onUnexpectedError);
     return validated.ok
       ? ({