every-plugin 2.10.1 → 3.0.0-rc.0

package/dist/version-manifest.mjs

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { createHash } from "node:crypto";
+
+//#region src/version-manifest.ts
+/**
+* WorkspaceVersionManifest — the immutable per-deploy document at
+* `bundles/<account>/<gateway>/<workspace>/versions/<version>.json`
+* (ADR 0020, as amended; atomic-deploys MAP decision 1). The published
+* config's slot pins this document via its `pin` (`manifest` + the
+* manifest's own SRI); every artifact coordinate lives here, so the config
+* stops growing with artifact kinds and old versions stay fully servable.
+*/
+const SRI = z.string().regex(/^sha384-[A-Za-z0-9+/=]+$/);
+const WorkspaceVersionManifestSchema = z.object({
+	version: z.string().regex(/^[0-9a-f]{16}$/),
+	builtAt: z.string().optional(),
+	gitSha: z.string().optional(),
+	entry: z.string().min(1),
+	entryIntegrity: SRI,
+	ssr: z.object({
+		entry: z.string().min(1),
+		integrity: SRI
+	}).optional(),
+	browserManifest: z.object({
+		file: z.string().min(1),
+		integrity: SRI
+	}).optional(),
+	/** extra assets (css, icons) — logical name → served-object SRI */
+	assets: z.record(z.string(), SRI).optional(),
+	/** shared-dependency versions this build was built against */
+	shared: z.record(z.string(), z.string()).optional(),
+	/**
+	* Full per-file digest map of the dist (object path → served-object SRI).
+	* Written by `every-plugin`-based deploys so the next deploy can diff against
+	* it and skip re-uploading unchanged files; readers that predate the field
+	* ignore it (zod strips unknown keys). Participates in the version hash.
+	*/
+	files: z.record(z.string(), SRI).optional()
+});
+/**
+* Compose the manifest with its `version` derived from the canonical content
+* of the artifact coordinates alone (key-sorted, `builtAt` excluded) —
+* identical bytes → identical version id regardless of when they were built,
+* so republishing unchanged content is a pointer no-op. Any changed
+* coordinate → a new version (and a new file).
+*/
+function composeVersionManifest(input) {
+	const { builtAt, ...hashedInputs } = input;
+	const version = createHash("sha256").update(stableStringify(hashedInputs)).digest("hex").slice(0, 16);
+	return WorkspaceVersionManifestSchema.parse({
+		...input,
+		version
+	});
+}
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value && typeof value === "object") return `{${Object.entries(value).filter(([, v]) => v !== void 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).sort().join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+
+//#endregion
+export { WorkspaceVersionManifestSchema, composeVersionManifest };
+//# sourceMappingURL=version-manifest.mjs.map

package/dist/version-manifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-manifest.mjs","names":[],"sources":["../src/version-manifest.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\n\n/**\n * WorkspaceVersionManifest — the immutable per-deploy document at\n * `bundles/<account>/<gateway>/<workspace>/versions/<version>.json`\n * (ADR 0020, as amended; atomic-deploys MAP decision 1). The published\n * config's slot pins this document via its `pin` (`manifest` + the\n * manifest's own SRI); every artifact coordinate lives here, so the config\n * stops growing with artifact kinds and old versions stay fully servable.\n */\n\nconst SRI = z.string().regex(/^sha384-[A-Za-z0-9+/=]+$/);\n\nexport const WorkspaceVersionManifestSchema = z.object({\n  version: z.string().regex(/^[0-9a-f]{16}$/),\n  builtAt: z.string().optional(),\n  gitSha: z.string().optional(),\n  entry: z.string().min(1),\n  entryIntegrity: SRI,\n  ssr: z\n    .object({\n      entry: z.string().min(1),\n      integrity: SRI,\n    })\n    .optional(),\n  browserManifest: z\n    .object({\n      file: z.string().min(1),\n      integrity: SRI,\n    })\n    .optional(),\n  /** extra assets (css, icons) — logical name → served-object SRI */\n  assets: z.record(z.string(), SRI).optional(),\n  /** shared-dependency versions this build was built against */\n  shared: z.record(z.string(), z.string()).optional(),\n  /**\n   * Full per-file digest map of the dist (object path → served-object SRI).\n   * Written by `every-plugin`-based deploys so the next deploy can diff against\n   * it and skip re-uploading unchanged files; readers that predate the field\n   * ignore it (zod strips unknown keys). Participates in the version hash.\n   */\n  files: z.record(z.string(), SRI).optional(),\n});\nexport type WorkspaceVersionManifest = z.infer<typeof WorkspaceVersionManifestSchema>;\n\nexport interface VersionManifestInput {\n  /** Omit: a per-build timestamp makes the same version id map to different\n   * manifest bytes per machine, breaking the pin's SRI against the image's\n   * staged copy and the CDN's immutability for republished versions. */\n  builtAt?: string;\n  gitSha?: string;\n  entry: string;\n  entryIntegrity: string;\n  ssr?: { entry: string; integrity: string };\n  browserManifest?: { file: string; integrity: string };\n  assets?: Record<string, string>;\n  shared?: Record<string, string>;\n  files?: Record<string, string>;\n}\n\n/**\n * Compose the manifest with its `version` derived from the canonical content\n * of the artifact coordinates alone (key-sorted, `builtAt` excluded) —\n * identical bytes → identical version id regardless of when they were built,\n * so republishing unchanged content is a pointer no-op. Any changed\n * coordinate → a new version (and a new file).\n */\nexport function composeVersionManifest(input: VersionManifestInput): WorkspaceVersionManifest {\n  const { builtAt, ...hashedInputs } = input;\n  const version = createHash(\"sha256\")\n    .update(stableStringify(hashedInputs))\n    .digest(\"hex\")\n    .slice(0, 16);\n  return WorkspaceVersionManifestSchema.parse({ ...input, version });\n}\n\nfunction stableStringify(value: unknown): string {\n  if (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n  if (value && typeof value === \"object\") {\n    return `{${Object.entries(value)\n      .filter(([, v]) => v !== undefined)\n      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)\n      .sort()\n      .join(\",\")}}`;\n  }\n  return JSON.stringify(value) ?? \"null\";\n}\n"],"mappings":";;;;;;;;;;;;AAYA,MAAM,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,0BAA0B;AAEvD,MAAa,iCAAiC,EAAE,OAAO;CACrD,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;CAC1C,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;CAC7B,QAAQ,EAAE,OAAO,CAAC,CAAC,SAAS;CAC5B,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACvB,gBAAgB;CAChB,KAAK,EACF,OAAO;EACN,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;EACvB,WAAW;CACb,CAAC,CAAC,CACD,SAAS;CACZ,iBAAiB,EACd,OAAO;EACN,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;EACtB,WAAW;CACb,CAAC,CAAC,CACD,SAAS;;CAEZ,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,GAAG,CAAC,CAAC,SAAS;;CAE3C,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;;;;;;;CAOlD,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,GAAG,CAAC,CAAC,SAAS;AAC5C,CAAC;;;;;;;;AAyBD,SAAgB,uBAAuB,OAAuD;CAC5F,MAAM,EAAE,SAAS,GAAG,iBAAiB;CACrC,MAAM,UAAU,WAAW,QAAQ,CAAC,CACjC,OAAO,gBAAgB,YAAY,CAAC,CAAC,CACrC,OAAO,KAAK,CAAC,CACb,MAAM,GAAG,EAAE;CACd,OAAO,+BAA+B,MAAM;EAAE,GAAG;EAAO;CAAQ,CAAC;AACnE;AAEA,SAAS,gBAAgB,OAAwB;CAC/C,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,IAAI,MAAM,IAAI,eAAe,CAAC,CAAC,KAAK,GAAG,EAAE;CAC1E,IAAI,SAAS,OAAO,UAAU,UAC5B,OAAO,IAAI,OAAO,QAAQ,KAAK,CAAC,CAC7B,QAAQ,GAAG,OAAO,MAAM,MAAS,CAAC,CAClC,KAAK,CAAC,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAC7D,KAAK,CAAC,CACN,KAAK,GAAG,EAAE;CAEf,OAAO,KAAK,UAAU,KAAK,KAAK;AAClC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "every-plugin",
-  "version": "2.10.1",
+  "version": "3.0.0-rc.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -10,122 +10,219 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": {
+      "bun": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts"
+      },
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./identity": {
+      "bun": {
+        "types": "./src/identity.ts",
+        "import": "./src/identity.ts"
+      },
+      "types": "./dist/identity.d.mts",
+      "import": "./dist/identity.mjs",
+      "require": "./dist/identity.cjs"
+    },
+    "./types": {
+      "bun": {
+        "types": "./src/types.ts",
+        "import": "./src/types.ts"
+      },
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs",
+      "require": "./dist/types.cjs"
+    },
+    "./errors": {
+      "bun": {
+        "types": "./src/errors.ts",
+        "import": "./src/errors.ts"
+      },
+      "types": "./dist/errors.d.mts",
+      "import": "./dist/errors.mjs",
+      "require": "./dist/errors.cjs"
+    },
+    "./remote-entry": {
+      "bun": {
+        "types": "./src/remote-entry.ts",
+        "import": "./src/remote-entry.ts"
+      },
+      "types": "./dist/remote-entry.d.mts",
+      "import": "./dist/remote-entry.mjs",
+      "require": "./dist/remote-entry.cjs"
+    },
     "./runtime": {
+      "bun": {
+        "types": "./src/runtime/index.ts",
+        "import": "./src/runtime/index.ts"
+      },
       "types": "./dist/runtime/index.d.mts",
       "import": "./dist/runtime/index.mjs",
       "require": "./dist/runtime/index.cjs"
     },
-    "./testing": {
-      "types": "./dist/testing/index.d.mts",
-      "import": "./dist/testing/index.mjs",
-      "require": "./dist/testing/index.cjs"
-    },
     "./normalize": {
+      "bun": {
+        "types": "./src/runtime/services/normalize.ts",
+        "import": "./src/runtime/services/normalize.ts"
+      },
       "types": "./dist/runtime/services/normalize.d.mts",
       "import": "./dist/runtime/services/normalize.mjs",
       "require": "./dist/runtime/services/normalize.cjs"
     },
-    "./effect": {
-      "types": "./dist/effect.d.mts",
-      "import": "./dist/effect.mjs",
-      "require": "./dist/effect.cjs"
+    "./shared-deps-spec": {
+      "bun": {
+        "types": "./src/shared-deps-spec.ts",
+        "import": "./src/shared-deps-spec.ts"
+      },
+      "types": "./dist/shared-deps-spec.d.mts",
+      "import": "./dist/shared-deps-spec.mjs",
+      "require": "./dist/shared-deps-spec.cjs"
+    },
+    "./build/rspack": {
+      "bun": {
+        "types": "./src/build/rspack/index.ts",
+        "import": "./src/build/rspack/index.ts"
+      },
+      "types": "./dist/build/rspack/index.d.mts",
+      "import": "./dist/build/rspack/index.mjs",
+      "require": "./dist/build/rspack/index.cjs"
     },
-    "./zod": {
-      "types": "./dist/zod.d.mts",
-      "import": "./dist/zod.mjs",
-      "require": "./dist/zod.cjs"
+    "./build/artifact-names": {
+      "bun": {
+        "types": "./src/build/artifact-names.ts",
+        "import": "./src/build/artifact-names.ts"
+      },
+      "types": "./dist/build/artifact-names.d.mts",
+      "import": "./dist/build/artifact-names.mjs",
+      "require": "./dist/build/artifact-names.cjs"
     },
-    "./zod/v4/core": {
-      "types": "./dist/zod-core.d.mts",
-      "import": "./dist/zod-core.mjs",
-      "require": "./dist/zod-core.cjs"
+    "./version-manifest": {
+      "bun": {
+        "types": "./src/version-manifest.ts",
+        "import": "./src/version-manifest.ts"
+      },
+      "types": "./dist/version-manifest.d.mts",
+      "import": "./dist/version-manifest.mjs",
+      "require": "./dist/version-manifest.cjs"
     },
-    "./orpc": {
-      "types": "./dist/orpc.d.mts",
-      "import": "./dist/orpc.mjs",
-      "require": "./dist/orpc.cjs"
+    "./ui/manifest": {
+      "bun": {
+        "types": "./src/ui/manifest/index.ts",
+        "import": "./src/ui/manifest/index.ts"
+      },
+      "types": "./dist/ui/manifest/index.d.mts",
+      "import": "./dist/ui/manifest/index.mjs",
+      "require": "./dist/ui/manifest/index.cjs"
     },
-    "./orpc/openapi": {
-      "types": "./dist/orpc-openapi.d.mts",
-      "import": "./dist/orpc-openapi.mjs",
-      "require": "./dist/orpc-openapi.cjs"
+    "./ui/manifest-generator": {
+      "bun": {
+        "types": "./src/ui/manifest/generator.ts",
+        "import": "./src/ui/manifest/generator.ts"
+      },
+      "types": "./dist/ui/manifest/generator.d.mts",
+      "import": "./dist/ui/manifest/generator.mjs",
+      "require": "./dist/ui/manifest/generator.cjs"
     },
-    "./errors": {
-      "types": "./dist/errors.d.mts",
-      "import": "./dist/errors.mjs",
-      "require": "./dist/errors.cjs"
+    "./ui/manifest/contract": {
+      "bun": {
+        "types": "./src/ui/manifest/contract.ts",
+        "import": "./src/ui/manifest/contract.ts"
+      },
+      "types": "./dist/ui/manifest/contract.d.mts",
+      "import": "./dist/ui/manifest/contract.mjs",
+      "require": "./dist/ui/manifest/contract.cjs"
     },
-    "./types": {
-      "types": "./dist/types.d.mts",
-      "import": "./dist/types.mjs",
-      "require": "./dist/types.cjs"
+    "./build/ui": {
+      "bun": {
+        "types": "./src/build/ui/index.ts",
+        "import": "./src/build/ui/index.ts"
+      },
+      "types": "./dist/build/ui/index.d.mts",
+      "import": "./dist/build/ui/index.mjs",
+      "require": "./dist/build/ui/index.cjs"
     },
-    "./build/rspack": {
-      "types": {
-        "import": "./dist/build/rspack/index.d.mts",
-        "require": "./dist/build/rspack/index.d.cts"
+    "./dev-serve": {
+      "bun": {
+        "types": "./src/dev/serve.ts",
+        "import": "./src/dev/serve.ts"
       },
-      "import": "./dist/build/rspack/index.mjs",
-      "require": "./dist/build/rspack/index.cjs"
+      "types": "./dist/dev/serve.d.mts",
+      "import": "./dist/dev/serve.mjs"
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "every-plugin": "./bin/every-plugin.mjs",
+    "every-plugin-serve": "./bin/every-plugin-serve.mjs"
+  },
   "files": [
     "dist",
     "src",
+    "bin",
     "skills",
     "!skills/_artifacts"
   ],
   "scripts": {
     "build": "tsdown",
-    "build:test": "cd tests/fixtures/test-plugin && bun run build",
+    "exports:sync": "node --import tsx scripts/sync-exports.ts",
+    "exports:check": "node --import tsx scripts/sync-exports.ts --check",
+    "build:test": "cd tests/fixtures/test-plugin && pnpm run build",
     "test": "vitest run --config vitest.config.ts",
     "test:unit": "vitest run --config vitest.config.ts",
-    "test:integration": "bun run build:test && vitest run --config vitest.integration.config.ts",
-    "test:all": "bun run test:unit && bun run test:integration",
+    "test:integration": "pnpm run build:test && vitest run --config vitest.integration.config.ts",
+    "test:all": "pnpm run test:unit && pnpm run test:integration",
     "test:watch": "vitest --config vitest.config.ts --watch",
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@rspack/core": "1.7.11",
-    "typescript": "^5.9.3",
-    "effect": "3.21.2",
-    "zod": "4.4.3",
-    "@orpc/contract": "1.14.3",
-    "@orpc/server": "1.14.3",
-    "@orpc/client": "1.14.3",
-    "@orpc/openapi": "1.14.3",
-    "@orpc/zod": "1.14.3",
-    "@orpc/tanstack-query": "1.14.3"
+    "@orpc/contract": "2.0.0-beta.35",
+    "@orpc/server": "2.0.0-beta.35",
+    "@orpc/tanstack-query": "2.0.0-beta.35",
+    "@orpc/zod": "2.0.0-beta.35",
+    "@proj-airi/unplugin-drizzle-orm-migrations": "*",
+    "@rspack/core": "2.2.8",
+    "@tanstack/react-router": "1.170.32",
+    "@tanstack/router-generator": "1.167.33",
+    "effect": "4.0.0-rc.117",
+    "react": "19.2.4",
+    "typescript": "^7.0.2",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@effect/language-service": "^0.85.1",
-    "@effect/vitest": "^0.29.0",
-    "@orpc/client": "^1.13.4",
-    "@orpc/openapi": "^1.13.4",
-    "@rspack/cli": "1.7.11",
+    "@effect/vitest": "4.0.0-rc.117",
+    "@orpc/client": "2.0.0-beta.35",
+    "@orpc/openapi": "2.0.0-beta.35",
+    "@rspack/cli": "2.2.6",
     "@tanstack/intent": "^0.3.5",
-    "@types/bun": "^1.3.7",
     "@types/node": "^25.1.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@vitest/ui": "4.1.5",
-    "bun-types": "^1.3.7",
-    "sirv": "^3.0.2",
     "tsdown": "^0.22.0",
     "vite-tsconfig-paths": "^6.0.5",
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@module-federation/enhanced": "^2.4.0",
-    "@module-federation/node": "^2.7.42",
-    "@module-federation/runtime-core": "^2.4.0",
-    "@orpc/contract": "1.14.3",
-    "@orpc/experimental-publisher": "1.14.2",
-    "@orpc/server": "1.14.3",
-    "@orpc/tanstack-query": "1.14.3"
+    "@module-federation/enhanced": "^2.9.0",
+    "@module-federation/node": "^2.7.50",
+    "@module-federation/rsbuild-plugin": "^2.9.0",
+    "@module-federation/runtime-core": "^2.9.0",
+    "@module-federation/runtime-tools": "^2.9.0",
+    "@orpc/client": "2.0.0-beta.35",
+    "@orpc/contract": "2.0.0-beta.35",
+    "@orpc/experimental-effect": "2.0.0-beta.35",
+    "@orpc/openapi": "2.0.0-beta.35",
+    "@orpc/publisher": "2.0.0-beta.35",
+    "@orpc/server": "2.0.0-beta.35",
+    "@orpc/tanstack-query": "2.0.0-beta.35",
+    "@rsbuild/core": "2.2.8",
+    "@rsbuild/plugin-react": "2.1.0",
+    "@tanstack/router-generator": "1.167.33",
+    "@tanstack/router-plugin": "1.168.35",
+    "sirv": "3.0.2"
   },
   "keywords": [
     "plugin",

package/skills/plugin-client/SKILL.md

@@ -2,7 +2,7 @@
 name: plugin-client
 description: Connect to and consume deployed everything.dev plugins from an external app, child project, or script. Use when creating API/auth clients, reading runtime config, authenticating with API keys or sessions, or calling plugin routes programmatically.
 metadata:
-  sources: "ui/src/lib/api.ts,ui/src/lib/auth.ts,ui/src/app.ts,everything-dev/src/ui/runtime.ts,everything-dev/src/types.ts,host/src/program.ts,host/src/services/auth.ts,api/src/lib/auth.ts"
+  sources: "ui/src/lib/api.ts,ui/src/lib/auth.ts,ui/src/app.ts,everything-dev/src/ui/runtime.ts,everything-dev/src/types.ts,host/src/program.ts,host/src/services/auth.ts,packages/everything-dev/src/api/auth-middleware.ts"
 ---
 
 # Plugin Client — Consuming everything.dev APIs
@@ -313,7 +313,7 @@ builder.createThing
   });
 ```
 
-See `references/api-keys.md` for the full API key route table, permission schema, and management examples.
+See [api-keys](references/api-keys.md) for the full API key route table, permission schema, and management examples.
 
 ## OpenAPI / REST
 
@@ -392,7 +392,6 @@ export type ApiContract = BaseApiContract & {
 ### Regeneration Triggers
 
 Generated files are gitignored and auto-regenerated on:
-- `bun install` (via postinstall `bos types gen`)
 - `bun typecheck`
 - `bos dev` / `bos build`
 - `bos plugin add` / `bos plugin remove`
@@ -433,11 +432,11 @@ bos init myapp.everything.dev \
   --plugins apps,template
 ```
 
-This writes `bos.config.json` with `extends`, scaffolds the project, and generates types. The child's `postinstall` hook runs `bos types gen` automatically.
+This writes `bos.config.json` with `extends`, scaffolds the project, and generates types. Afterward, `bun typecheck`, `bos dev`, and `bos build` regenerate types on demand.
 
 ### What Can Be Overridden
 
-Child configs can override `app.ui` (custom UI CDN) and `plugins.<key>` (custom plugin URLs). The host's `ALLOW_OVERRIDE` env var controls which sections tenants can customize (`ui`, `plugins`, `plugins.<key>`).
+Child configs can override `app.ui` (custom UI CDN) and `plugins.<key>` (custom plugin URLs). Which sections a tenant can customize is controlled per-tenant by the `allow_ui_overrides` and `allow_backend_overrides` flags on the tenant record, resolved by the host from the API's `GET /tenants/bindings` endpoint (cached for 30s).
 
 See the `extends-config` skill for deep merge semantics, per-environment extends, and canonical field ordering.
 
@@ -448,3 +447,23 @@ See the `extends-config` skill for deep merge semantics, per-environment extends
 - **Not saving the API key secret** — `authClient.apiKey.create()` returns the full key string (`edk_...`) only once. Subsequent calls to `list` or `update` return only the prefix and metadata.
 - **Plugin key vs plugin name confusion** — the client namespace is the `bos.config.json` `plugins` key (e.g., `"apps"`), not the Module Federation `name` field. They often match but are not guaranteed to.
 - **Forgetting to regenerate types** — after adding/removing plugins in `bos.config.json`, run `bos types gen` or restart `bos dev`. Stale `api-types.gen.ts` will have missing or wrong namespace keys.
+
+## The tasks you will actually be given
+
+**"Call a plugin route from a script"** — create a key in the UI under `/settings/api-keys` (the full `edk_...` secret is shown once — copy it), then use the external `RPCLink` + `x-api-key` snippet from the External / Standalone API Client section above. The procedure path is `POST {hostUrl}/api/rpc/{pluginKey}/{procedure}` — e.g. `client.registry.listRegistryApps({ limit: 24 })`.
+
+**"Wire a typed API call into a UI route"** — import `useApiClient` from `@/app`, call `apiClient.<pluginKey>.<procedure>()`. If the namespace key is missing in the types, the plugin was added/removed without regenerating: run `bos types gen` (or restart `pnpm run dev`), never hand-edit `ui/src/lib/api-types.gen.ts`.
+
+**"Set up a typed client for another language"** — pull the spec from `GET {hostUrl}/api/spec.json` and run the openapi codegen commands in the OpenAPI / REST section above.
+
+## What comes back when it refuses
+
+| Error word / shape you see | Meaning | Action |
+|---|---|---|
+| 401 `UNAUTHORIZED` "Authentication required" with `data: { hint: "Sign in or provide an API key" }` | no session cookie and no API key reached the middleware | sign in, or attach `x-api-key: edk_...` |
+| 401 `UNAUTHORIZED` "API key required" with `data: { authType: "apiKey", hint: "Provide a valid API key via x-api-key header" }` | the route is `requireApiKey(...)`-protected and your key was absent — usually `Authorization: Bearer` was used instead | switch to the `x-api-key` header |
+| 403 `FORBIDDEN` "API key lacks permission: <resource>:<action>" with `data: { requiredPermissions, keyPermissions }` | the key's `permissions` map does not cover every required resource/action — partial matches are rejected | re-create (server-side) or update the key with the needed permissions |
+| 403 `FORBIDDEN` "Requires role: ..." / "Requires organization role: ..." | session role gate | sign in with an account holding the role; a key cannot satisfy these |
+| 403 `FORBIDDEN` "Organization requires platform-admin approval" | the org's `status` is not `"active"` | stop — needs platform-admin approval, no client-side fix |
+| `authClient.apiKey.list` / `update` return only `prefix` and metadata | expected — the full secret is returned once at `create` | create a new key; the old secret is unrecoverable |
+| Browser request blocked by CORS despite a valid key | session cookies not sent (`credentials: "include"` missing) or origin not allowed by `CORS_ORIGIN` | add `credentials: "include"` to the fetch wrapper, or fix `CORS_ORIGIN` |