every-plugin 2.7.1 → 2.9.0

package/dist/runtime/services/plugin-loader.service.mjs

@@ -62,18 +62,18 @@ var PluginLoaderService = class extends Effect.Service()("PluginLoaderService",
 				retryable: false
 			}));
 			const resolvedUrl = resolveUrl(url);
-			yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "register-remote", true)));
+			yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(Effect.tapError((_error) => Effect.logError(`Plugin ${pluginId} failed during register-remote`)), Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "register-remote", true)));
 			yield* Effect.logDebug("Loading plugin from remote", {
 				pluginId,
 				url: resolvedUrl
 			});
 			return {
-				ctor: yield* moduleFederationService.loadRemoteConstructor(pluginId, resolvedUrl).pipe(Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "load-remote", false))),
+				ctor: yield* moduleFederationService.loadRemoteConstructor(pluginId, resolvedUrl).pipe(Effect.tapError((_error) => Effect.logError(`Plugin ${pluginId} failed during load-remote`)), Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "load-remote", false))),
 				metadata: entry.metadata
 			};
 		}),
 		instantiatePlugin: (pluginId, loadedPlugin) => Effect.gen(function* () {
-			const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "instantiate-plugin", false)));
+			const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(Effect.tapError((_error) => Effect.logError(`Plugin ${pluginId} failed during instantiate-plugin`)), Effect.mapError((error) => toPluginRuntimeError(error, pluginId, void 0, "instantiate-plugin", false)));
 			instance.id = pluginId;
 			return {
 				plugin: instance,
@@ -108,7 +108,7 @@ var PluginLoaderService = class extends Effect.Service()("PluginLoaderService",
 			const context = yield* plugin.initialize({
 				variables: _variables,
 				secrets: hydratedConfig.secrets
-			}, plugins ?? {}).pipe(Effect.provideService(Scope.Scope, scope), Effect.mapError((error) => toPluginRuntimeError(error, plugin.id, void 0, "initialize-plugin", false)));
+			}, plugins ?? {}).pipe(Effect.provideService(Scope.Scope, scope), Effect.tapError((_error) => Effect.logError(`Plugin ${plugin.id} failed during initialize-plugin`)), Effect.mapError((error) => toPluginRuntimeError(error, plugin.id, void 0, "initialize-plugin", false)));
 			return {
 				plugin,
 				metadata: pluginInstance.metadata,

package/dist/runtime/services/plugin-loader.service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-loader.service.mjs","names":[],"sources":["../../../src/runtime/services/plugin-loader.service.ts"],"sourcesContent":["import type { InferSchemaInput, InferSchemaOutput } from \"@orpc/contract\";\nimport { Context, Effect, Scope } from \"effect\";\nimport type { z } from \"zod\";\nimport type {\n  AnyPlugin,\n  AnyPluginConstructor,\n  InitializedPlugin,\n  LoadedPlugin,\n  PluginInstance,\n  PluginMetadata,\n  PluginRegistry,\n} from \"../../types\";\nimport { PluginRuntimeError, toPluginRuntimeError } from \"../errors\";\nimport { validate } from \"../validation\";\nimport { ModuleFederationService } from \"./module-federation.service\";\nimport { SecretsService } from \"./secrets.service\";\n\nexport class PluginRegistryTag extends Context.Tag(\"PluginRegistry\")<\n  PluginRegistryTag,\n  PluginRegistry\n>() {}\n\nexport class PluginMapTag extends Context.Tag(\"PluginMap\")<\n  PluginMapTag,\n  Record<string, AnyPluginConstructor>\n>() {}\n\nexport class RegistryService extends Effect.Service<RegistryService>()(\"RegistryService\", {\n  effect: Effect.gen(function* () {\n    const registry = yield* PluginRegistryTag;\n    const pluginMap = yield* PluginMapTag;\n\n    return {\n      get: (pluginId: string) =>\n        Effect.gen(function* () {\n          const entry = registry[pluginId];\n\n          if (!entry) {\n            return yield* Effect.fail(\n              new PluginRuntimeError({\n                pluginId,\n                operation: \"validate-plugin-id\",\n                cause: new Error(`Plugin ${pluginId} not found in registry`),\n                retryable: false,\n              }),\n            );\n          }\n\n          if (\"module\" in entry) {\n            return {\n              constructor: entry.module,\n              metadata: {\n                remoteUrl: entry.remote || \"\",\n                version: entry.version,\n                description: entry.description,\n              } as PluginMetadata,\n            };\n          }\n\n          return {\n            constructor: null,\n            metadata: {\n              remoteUrl: entry.remote,\n              version: entry.version,\n              description: entry.description,\n            } as PluginMetadata,\n          };\n        }),\n\n      getModule: (pluginId: string) => Effect.succeed(pluginMap[pluginId] || null),\n    };\n  }),\n}) {}\n\nexport class PluginLoaderService extends Effect.Service<PluginLoaderService>()(\n  \"PluginLoaderService\",\n  {\n    effect: Effect.gen(function* () {\n      const moduleFederationService = yield* ModuleFederationService;\n      const secretsService = yield* SecretsService;\n      const registryService = yield* RegistryService;\n\n      const resolveUrl = (baseUrl: string, version?: string): string =>\n        version && version !== \"latest\" ? baseUrl.replace(\"@latest\", `@${version}`) : baseUrl;\n\n      return {\n        loadPlugin: (pluginId: string) =>\n          Effect.gen(function* () {\n            const entry = yield* registryService.get(pluginId);\n\n            if (entry.constructor) {\n              yield* Effect.logDebug(\"Loading plugin from direct module\", { pluginId });\n\n              return {\n                ctor: entry.constructor,\n                metadata: entry.metadata,\n              } satisfies LoadedPlugin;\n            }\n\n            const url = entry.metadata.remoteUrl;\n            if (!url) {\n              return yield* Effect.fail(\n                new PluginRuntimeError({\n                  pluginId,\n                  operation: \"load-plugin\",\n                  cause: new Error(`Plugin ${pluginId} has no module or remote URL configured`),\n                  retryable: false,\n                }),\n              );\n            }\n\n            const resolvedUrl = resolveUrl(url);\n\n            yield* moduleFederationService\n              .registerRemote(pluginId, resolvedUrl)\n              .pipe(\n                Effect.mapError((error) =>\n                  toPluginRuntimeError(error, pluginId, undefined, \"register-remote\", true),\n                ),\n              );\n\n            yield* Effect.logDebug(\"Loading plugin from remote\", { pluginId, url: resolvedUrl });\n\n            const ctor = yield* moduleFederationService\n              .loadRemoteConstructor(pluginId, resolvedUrl)\n              .pipe(\n                Effect.mapError((error) =>\n                  toPluginRuntimeError(error, pluginId, undefined, \"load-remote\", false),\n                ),\n              );\n\n            return {\n              ctor,\n              metadata: entry.metadata,\n            } satisfies LoadedPlugin;\n          }),\n\n        instantiatePlugin: <T extends AnyPlugin>(pluginId: string, loadedPlugin: LoadedPlugin<T>) =>\n          Effect.gen(function* () {\n            const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(\n              Effect.mapError((error) =>\n                toPluginRuntimeError(error, pluginId, undefined, \"instantiate-plugin\", false),\n              ),\n            );\n\n            (instance.id as string) = pluginId;\n\n            return {\n              plugin: instance,\n              metadata: loadedPlugin.metadata,\n            } satisfies PluginInstance<T>;\n          }),\n\n        initializePlugin: <T extends AnyPlugin>(\n          pluginInstance: PluginInstance<T>,\n          config: {\n            variables: InferSchemaInput<T[\"configSchema\"][\"variables\"]>;\n            secrets: InferSchemaInput<T[\"configSchema\"][\"secrets\"]>;\n          },\n          plugins?: Record<string, unknown>,\n        ) =>\n          Effect.gen(function* () {\n            const { plugin } = pluginInstance;\n\n            // Validate and hydrate config\n            const validatedVariables = yield* validate(\n              plugin.configSchema.variables as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"variables\"]>\n              >,\n              config.variables,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-config\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Validate secrets\n            const validatedSecrets = yield* validate(\n              plugin.configSchema.secrets as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"secrets\"]>\n              >,\n              config.secrets,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-secrets\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Hydrate secrets in variables\n            const hydratedConfig = yield* secretsService.hydrateSecrets({\n              variables: validatedVariables,\n              secrets: validatedSecrets,\n            });\n\n            const _variables = yield* validate(\n              plugin.configSchema.variables as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"variables\"]>\n              >,\n              hydratedConfig.variables,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-hydrated-config\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Create a long-lived scope for this plugin instance\n            const scope = yield* Scope.make();\n\n            // Initialize plugin within the scope\n            const context = yield* plugin\n              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})\n              .pipe(\n                Effect.provideService(Scope.Scope, scope),\n                Effect.mapError((error) =>\n                  toPluginRuntimeError(error, plugin.id, undefined, \"initialize-plugin\", false),\n                ),\n              );\n\n            return {\n              plugin,\n              metadata: pluginInstance.metadata,\n              config: { variables: _variables, secrets: hydratedConfig.secrets },\n              context,\n              scope,\n            } satisfies InitializedPlugin<T>;\n          }),\n      };\n    }),\n  },\n) {}\n"],"mappings":"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"}
+{"version":3,"file":"plugin-loader.service.mjs","names":[],"sources":["../../../src/runtime/services/plugin-loader.service.ts"],"sourcesContent":["import type { InferSchemaInput, InferSchemaOutput } from \"@orpc/contract\";\nimport { Context, Effect, Scope } from \"effect\";\nimport type { z } from \"zod\";\nimport type {\n  AnyPlugin,\n  AnyPluginConstructor,\n  InitializedPlugin,\n  LoadedPlugin,\n  PluginInstance,\n  PluginMetadata,\n  PluginRegistry,\n} from \"../../types\";\nimport { PluginRuntimeError, toPluginRuntimeError } from \"../errors\";\nimport { validate } from \"../validation\";\nimport { ModuleFederationService } from \"./module-federation.service\";\nimport { SecretsService } from \"./secrets.service\";\n\nexport class PluginRegistryTag extends Context.Tag(\"PluginRegistry\")<\n  PluginRegistryTag,\n  PluginRegistry\n>() {}\n\nexport class PluginMapTag extends Context.Tag(\"PluginMap\")<\n  PluginMapTag,\n  Record<string, AnyPluginConstructor>\n>() {}\n\nexport class RegistryService extends Effect.Service<RegistryService>()(\"RegistryService\", {\n  effect: Effect.gen(function* () {\n    const registry = yield* PluginRegistryTag;\n    const pluginMap = yield* PluginMapTag;\n\n    return {\n      get: (pluginId: string) =>\n        Effect.gen(function* () {\n          const entry = registry[pluginId];\n\n          if (!entry) {\n            return yield* Effect.fail(\n              new PluginRuntimeError({\n                pluginId,\n                operation: \"validate-plugin-id\",\n                cause: new Error(`Plugin ${pluginId} not found in registry`),\n                retryable: false,\n              }),\n            );\n          }\n\n          if (\"module\" in entry) {\n            return {\n              constructor: entry.module,\n              metadata: {\n                remoteUrl: entry.remote || \"\",\n                version: entry.version,\n                description: entry.description,\n              } as PluginMetadata,\n            };\n          }\n\n          return {\n            constructor: null,\n            metadata: {\n              remoteUrl: entry.remote,\n              version: entry.version,\n              description: entry.description,\n            } as PluginMetadata,\n          };\n        }),\n\n      getModule: (pluginId: string) => Effect.succeed(pluginMap[pluginId] || null),\n    };\n  }),\n}) {}\n\nexport class PluginLoaderService extends Effect.Service<PluginLoaderService>()(\n  \"PluginLoaderService\",\n  {\n    effect: Effect.gen(function* () {\n      const moduleFederationService = yield* ModuleFederationService;\n      const secretsService = yield* SecretsService;\n      const registryService = yield* RegistryService;\n\n      const resolveUrl = (baseUrl: string, version?: string): string =>\n        version && version !== \"latest\" ? baseUrl.replace(\"@latest\", `@${version}`) : baseUrl;\n\n      return {\n        loadPlugin: (pluginId: string) =>\n          Effect.gen(function* () {\n            const entry = yield* registryService.get(pluginId);\n\n            if (entry.constructor) {\n              yield* Effect.logDebug(\"Loading plugin from direct module\", { pluginId });\n\n              return {\n                ctor: entry.constructor,\n                metadata: entry.metadata,\n              } satisfies LoadedPlugin;\n            }\n\n            const url = entry.metadata.remoteUrl;\n            if (!url) {\n              return yield* Effect.fail(\n                new PluginRuntimeError({\n                  pluginId,\n                  operation: \"load-plugin\",\n                  cause: new Error(`Plugin ${pluginId} has no module or remote URL configured`),\n                  retryable: false,\n                }),\n              );\n            }\n\n            const resolvedUrl = resolveUrl(url);\n\n            yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(\n              Effect.tapError((_error) =>\n                Effect.logError(`Plugin ${pluginId} failed during register-remote`),\n              ),\n              Effect.mapError((error) =>\n                toPluginRuntimeError(error, pluginId, undefined, \"register-remote\", true),\n              ),\n            );\n\n            yield* Effect.logDebug(\"Loading plugin from remote\", { pluginId, url: resolvedUrl });\n\n            const ctor = yield* moduleFederationService\n              .loadRemoteConstructor(pluginId, resolvedUrl)\n              .pipe(\n                Effect.tapError((_error) =>\n                  Effect.logError(`Plugin ${pluginId} failed during load-remote`),\n                ),\n                Effect.mapError((error) =>\n                  toPluginRuntimeError(error, pluginId, undefined, \"load-remote\", false),\n                ),\n              );\n\n            return {\n              ctor,\n              metadata: entry.metadata,\n            } satisfies LoadedPlugin;\n          }),\n\n        instantiatePlugin: <T extends AnyPlugin>(pluginId: string, loadedPlugin: LoadedPlugin<T>) =>\n          Effect.gen(function* () {\n            const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(\n              Effect.tapError((_error) =>\n                Effect.logError(`Plugin ${pluginId} failed during instantiate-plugin`),\n              ),\n              Effect.mapError((error) =>\n                toPluginRuntimeError(error, pluginId, undefined, \"instantiate-plugin\", false),\n              ),\n            );\n\n            (instance.id as string) = pluginId;\n\n            return {\n              plugin: instance,\n              metadata: loadedPlugin.metadata,\n            } satisfies PluginInstance<T>;\n          }),\n\n        initializePlugin: <T extends AnyPlugin>(\n          pluginInstance: PluginInstance<T>,\n          config: {\n            variables: InferSchemaInput<T[\"configSchema\"][\"variables\"]>;\n            secrets: InferSchemaInput<T[\"configSchema\"][\"secrets\"]>;\n          },\n          plugins?: Record<string, unknown>,\n        ) =>\n          Effect.gen(function* () {\n            const { plugin } = pluginInstance;\n\n            // Validate and hydrate config\n            const validatedVariables = yield* validate(\n              plugin.configSchema.variables as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"variables\"]>\n              >,\n              config.variables,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-config\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Validate secrets\n            const validatedSecrets = yield* validate(\n              plugin.configSchema.secrets as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"secrets\"]>\n              >,\n              config.secrets,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-secrets\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Hydrate secrets in variables\n            const hydratedConfig = yield* secretsService.hydrateSecrets({\n              variables: validatedVariables,\n              secrets: validatedSecrets,\n            });\n\n            const _variables = yield* validate(\n              plugin.configSchema.variables as z.ZodSchema<\n                InferSchemaOutput<T[\"configSchema\"][\"variables\"]>\n              >,\n              hydratedConfig.variables,\n              plugin.id,\n              \"config\",\n            ).pipe(\n              Effect.mapError(\n                (validationError) =>\n                  new PluginRuntimeError({\n                    pluginId: plugin.id,\n                    operation: \"validate-hydrated-config\",\n                    cause: validationError.zodError,\n                    retryable: false,\n                  }),\n              ),\n            );\n\n            // Create a long-lived scope for this plugin instance\n            const scope = yield* Scope.make();\n\n            // Initialize plugin within the scope\n            const context = yield* plugin\n              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})\n              .pipe(\n                Effect.provideService(Scope.Scope, scope),\n                Effect.tapError((_error) =>\n                  Effect.logError(`Plugin ${plugin.id} failed during initialize-plugin`),\n                ),\n                Effect.mapError((error) =>\n                  toPluginRuntimeError(error, plugin.id, undefined, \"initialize-plugin\", false),\n                ),\n              );\n\n            return {\n              plugin,\n              metadata: pluginInstance.metadata,\n              config: { variables: _variables, secrets: hydratedConfig.secrets },\n              context,\n              scope,\n            } satisfies InitializedPlugin<T>;\n          }),\n      };\n    }),\n  },\n) {}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "every-plugin",
-  "version": "2.7.1",
+  "version": "2.9.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -108,7 +108,7 @@
     "@orpc/client": "^1.13.4",
     "@orpc/openapi": "^1.13.4",
     "@rspack/cli": "1.7.11",
-    "@tanstack/intent": "^0.0.40",
+    "@tanstack/intent": "^0.3.5",
     "@types/bun": "^1.3.7",
     "@types/node": "^25.1.0",
     "@vitest/ui": "4.1.5",

package/skills/plugin-client/SKILL.md

@@ -0,0 +1,450 @@
+---
+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"
+---
+
+# Plugin Client — Consuming everything.dev APIs
+
+## Minimal Connection Config
+
+Every everything.dev host exposes two surfaces:
+
+| Surface | URL | Purpose |
+|---------|-----|---------|
+| RPC | `{hostUrl}/api/rpc` | Typed oRPC procedure calls (POST) |
+| OpenAPI / REST | `{hostUrl}/api` | Scalar docs + OpenAPI spec + REST routes |
+
+The host injects a `ClientRuntimeConfig` into `window.__RUNTIME_CONFIG__` via an inline script during SSR. The key fields for client connection:
+
+```ts
+{
+  hostUrl: "https://dev.everything.dev",  // the host server origin
+  apiBase: "/api",
+  rpcBase: "/api/rpc",
+  authAvailable: true,
+  account: "dev.everything.near",
+  networkId: "mainnet",
+}
+```
+
+Read it with `getRuntimeConfig()` from `everything-dev/ui/runtime`:
+
+```ts
+import { getRuntimeConfig } from "everything-dev/ui/runtime";
+
+const config = getRuntimeConfig();  // throws if window.__RUNTIME_CONFIG__ is missing
+```
+
+Or use the `@/app` helpers (in-repo UI only):
+
+```ts
+import { getAccount, getActiveRuntime, getAppName, getRepository } from "@/app";
+
+const account = getAccount();                          // "dev.everything.near"
+const runtime = getActiveRuntime();                    // { accountId, gatewayId, title, ... }
+const appName = getAppName();                           // runtime title or account
+```
+
+All helpers accept an optional config argument for SSR — pass `runtimeConfig` from loader data instead of reading `window`.
+
+## External / Standalone API Client
+
+An external app, script, or child project can connect with just `@orpc/client` and `@orpc/client/fetch`:
+
+```ts
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+
+const HOST = "https://dev.everything.dev";
+
+const link = new RPCLink({
+  url: `${HOST}/api/rpc`,
+  fetch: globalThis.fetch,
+  headers: {
+    "x-api-key": process.env.EVERYTHING_DEV_API_KEY!,
+  },
+});
+
+const client = createORPCClient(link);
+```
+
+### URL Structure
+
+oRPC's RPC protocol encodes the procedure path in the URL segment after the RPC base:
+
+| Call | HTTP Request |
+|------|-------------|
+| `client.ping()` | `POST {hostUrl}/api/rpc/ping` |
+| `client.apps.listRegistryApps({ limit: 24 })` | `POST {hostUrl}/api/rpc/apps/listRegistryApps` |
+| `client.auth.getSession()` | `POST {hostUrl}/api/rpc/auth/getSession` |
+
+The host matches `/api/rpc/{pluginKey}/*` prefixes and dispatches to each plugin's `RPCHandler`. Base API procedures (not namespaced) go to the main API handler at `/api/rpc`.
+
+### Plugin Namespacing
+
+Plugins are namespaced by their `bos.config.json` key. If the config has:
+
+```json
+{
+  "plugins": {
+    "apps": { "production": "https://..." },
+    "template": { "production": "https://..." }
+  }
+}
+```
+
+Then the client surface is:
+
+```ts
+client.ping();                      // base API
+client.apps.listRegistryApps();     // "apps" plugin
+client.template.someProcedure();    // "template" plugin
+client.auth.getSession();           // auth plugin (mounted at /api/rpc/auth)
+```
+
+Without the generated `ApiContract` type, the client is untyped — but the runtime behavior is identical. Use OpenAPI codegen (see below) for typed clients in other languages.
+
+### Auth for External Clients
+
+Two credential mechanisms:
+
+**API key** — pass `x-api-key` header on every request:
+
+```ts
+const link = new RPCLink({
+  url: `${HOST}/api/rpc`,
+  fetch: globalThis.fetch,
+  headers: { "x-api-key": "edk_xxxxxxxxxxxxxxx" },
+});
+```
+
+**Session cookies** — use `credentials: "include"` (browser only, requires CORS origin allowlist):
+
+```ts
+const link = new RPCLink({
+  url: `${HOST}/api/rpc`,
+  fetch: (url, options) => fetch(url, { ...options, credentials: "include" }),
+});
+```
+
+The host's session middleware resolves auth on every `/api/*` request by calling Better-Auth's `getContext()`, which reads session cookies and the `x-api-key` header. The resulting context (user, apiKey, organization) is forwarded into every plugin's oRPC handler.
+
+## In-Repo API Client
+
+Within the everything.dev UI, use `createApiClient` from `@/app`:
+
+```ts
+import { createApiClient, useApiClient, useOrpc } from "@/app";
+
+// In hydration (once):
+const apiClient = createApiClient({
+  hostUrl: runtimeConfig.hostUrl,
+  rpcBase: runtimeConfig.rpcBase,
+});
+
+// In route components:
+const apiClient = useApiClient();
+const result = await apiClient.apps.listRegistryApps({ limit: 24 });
+
+// With TanStack Query utils:
+const orpc = useOrpc();
+const { data } = orpc.apps.listRegistryApps.useQuery({ limit: 24 });
+```
+
+`createApiClient` caches a singleton in the browser (when no SSR headers are passed). SSR builds a fresh client per request with forwarded cookies. See the `ui-integration` skill for route-level patterns, loaders, and error handling.
+
+## Auth Client (Session-Based)
+
+The auth client uses Better-Auth with SIWN (NEAR wallet sign-in). Create it with `createAuthClient` from `@/app`:
+
+```ts
+import { createAuthClient, sessionQueryOptions, useAuthClient } from "@/app";
+
+// In hydration:
+const authClient = createAuthClient({ runtimeConfig, cspNonce });
+
+// In route components:
+const authClient = useAuthClient();
+```
+
+### SIWN Configuration
+
+The auth client reads NEAR recipient config from `runtimeConfig.auth.variables.siwn`:
+
+```ts
+// runtimeConfig.auth.variables.siwn:
+{
+  recipient: "dev.everything.near",           // single network
+  // OR:
+  recipients: {
+    mainnet: "dev.everything.near",
+    testnet: "dev.testnet.near",
+  },
+}
+```
+
+The client resolves `mainnetRecipient` from `recipients.mainnet ?? recipient` and infers `networkId` from the runtime config or the recipient suffix.
+
+### Sign-In Flows
+
+```ts
+// NEAR wallet (SIWN)
+await authClient.signIn.siwn({ networkId: "mainnet" });
+
+// Email/password
+await authClient.signIn.email({ email, password });
+
+// Passkey
+await authClient.signIn.passkey();
+
+// Sign out
+await authClient.signOut();
+
+// Organization switching
+await authClient.organization.setActive({ organizationId: "org_123" });
+```
+
+### Session Query
+
+```ts
+import { sessionQueryOptions } from "@/app";
+
+// In a route loader (SSR-safe with initialData):
+const session = await queryClient.ensureQueryData(
+  sessionQueryOptions(authClient, context.session),
+);
+
+// In a component:
+const { data: session } = useQuery(sessionQueryOptions(authClient));
+```
+
+Session query key is `["session"]` with 1-min stale time and 10-min GC time.
+
+### SSR Cookie Forwarding
+
+On the server, cookies can't be read from `window`. Pass request headers:
+
+```ts
+const authClient = createAuthClient({
+  runtimeConfig,
+  headers: request.headers,    // forwards session cookies
+  cspNonce,
+});
+```
+
+Both API and auth clients use `credentials: "include"` unconditionally. The host's CORS allows any HTTPS origin in production (configurable via `CORS_ORIGIN`).
+
+## API Key Auth
+
+For programmatic access (scripts, backend services, CI), use API keys instead of sessions.
+
+### Creating API Keys
+
+API keys are created via the Better-Auth `apiKeyClient()` plugin (exposed as `authClient.apiKey.*`):
+
+```ts
+const authClient = useAuthClient();
+
+// Create a key (secret returned once!)
+const { data, error } = await authClient.apiKey.create({
+  name: "my-bot-key",
+  configId: "org-keys",           // optional: scope to a key config
+  organizationId: "org_123",      // optional: scope to an org
+  expiresIn: 60 * 60 * 24 * 30,   // optional: 30 days (seconds)
+});
+
+if (data) {
+  console.log(data.apiKey.key);   // "edk_xxxxxxxxx" — save this now
+}
+```
+
+The full key secret is only returned at creation time. Store it immediately.
+
+### Using API Keys
+
+Pass the key in the `x-api-key` header:
+
+```ts
+const link = new RPCLink({
+  url: `${HOST}/api/rpc`,
+  fetch: globalThis.fetch,
+  headers: { "x-api-key": "edk_xxxxxxxxxxxxxxx" },
+});
+```
+
+Or with plain fetch to REST endpoints:
+
+```ts
+const res = await fetch(`${HOST}/api/v1/registry/apps`, {
+  headers: { "x-api-key": "edk_xxxxxxxxxxxxxxx" },
+});
+```
+
+### Permission Scopes
+
+Keys have a `permissions` map (`Record<string, string[]>` — resource to allowed actions). Routes protected by `requireApiKey(requiredPermissions)` check that the key's permissions cover all required resource/action pairs:
+
+```ts
+// Server-side (plugin route):
+builder.deleteThing
+  .use(requireApiKey({ things: ["delete"] }))
+  .handler(async ({ context }) => {
+    context.apiKey.permissions;  // { things: ["delete", "create"], ... }
+  });
+```
+
+If the key lacks a required permission, the server returns `FORBIDDEN` with `{ requiredPermissions, keyPermissions }` in the error data.
+
+### Dual-Mode Auth
+
+`requireAuthOrApiKey` accepts either a session or an API key — useful for routes that serve both interactive UI and programmatic clients:
+
+```ts
+builder.createThing
+  .use(requireAuthOrApiKey)
+  .handler(async ({ input, context }) => {
+    if (context.apiKey) {
+      // API key path
+    } else if (context.user) {
+      // Session path
+    }
+  });
+```
+
+See `references/api-keys.md` for the full API key route table, permission schema, and management examples.
+
+## OpenAPI / REST
+
+The host serves Scalar API reference docs and an OpenAPI spec:
+
+| Endpoint | Content |
+|----------|---------|
+| `GET {hostUrl}/api` | Scalar HTML docs UI |
+| `GET {hostUrl}/api` (Accept: application/json) | OpenAPI JSON spec |
+
+Use the OpenAPI spec to generate typed clients in any language:
+
+```bash
+# Generate a TypeScript client
+npx openapi-typescript-codegen --input https://dev.everything.dev/api --output ./generated-api
+
+# Generate a Python client
+openapi-generator-cli generate -i https://dev.everything.dev/api -g python -o ./api-client
+```
+
+REST routes follow the `oc.route({ method, path })` declarations in each plugin's contract. For example, `GET {hostUrl}/api/v1/registry/apps` maps to the `apps` plugin's `listRegistryApps` procedure.
+
+### Plugin Manifests
+
+Each deployed plugin exposes a manifest at `{pluginUrl}/plugin.manifest.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "every-plugin/manifest",
+  "plugin": { "name": "apps", "version": "1.0.0" },
+  "runtime": { "remoteEntry": "./remoteEntry.js" },
+  "contract": {
+    "kind": "orpc",
+    "types": {
+      "path": "./types/contract.d.ts",
+      "exportName": "contract",
+      "typeName": "ContractType",
+      "sha256": "abc123..."
+    }
+  }
+}
+```
+
+The manifest provides the contract type file path and SHA-256 checksum for verified type generation.
+
+## Typed Clients via `bos types gen`
+
+Child projects and the in-repo UI get typed API clients through generated contract bridge files.
+
+### What It Generates
+
+| File | Contents |
+|------|----------|
+| `ui/src/lib/api-types.gen.ts` | `ApiContract` — merged type of base API + all plugin contracts |
+| `api/src/lib/plugins-types.gen.ts` | `PluginsClient` — factory types for in-process plugin composition |
+| `*/src/lib/auth-types.gen.ts` | Auth plugin session/user/organization types |
+
+### The Merged Contract
+
+`api-types.gen.ts` intersects the base API contract with each plugin's contract as a namespaced key:
+
+```ts
+import type { ContractType as BaseApiContract } from "../../../api/src/contract.ts";
+import type { ContractType as appsContract } from "../../../plugins/apps/src/contract.ts";
+
+export type ApiContract = BaseApiContract & {
+  auth: authContract;
+  apps: appsContract;
+  template: templateContract;
+};
+```
+
+`ContractRouterClient<ApiContract>` turns this into a fully typed callable proxy — `apiClient.apps.listRegistryApps({ limit: 24 })` has complete input/output types.
+
+### 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`
+
+After hand-editing `bos.config.json`, run `bos types gen` or restart `bos dev`.
+
+### Type Resolution
+
+- `local:plugins/<name>` → reads `src/contract.ts` directly from disk
+- Remote URL → fetches `contract.d.ts` from the deployed plugin's manifest (with SHA-256 verification)
+- Missing local path with no URL → skipped with a warning
+
+## Child Project Config
+
+A child project inherits the parent's host, API, auth, and plugins via the `extends` field in `bos.config.json`:
+
+```json
+{
+  "extends": "bos://dev.everything.near/dev.everything.dev",
+  "account": "myapp.near",
+  "domain": "myapp.everything.dev"
+}
+```
+
+This inherits:
+- `app.host` — the parent's host server URL
+- `app.ui` — the parent's UI CDN (overridable)
+- `app.api` — the parent's API
+- `app.auth` — the parent's auth plugin (via nested `extends` ref)
+- `plugins` — all parent plugins (overridable per-key)
+
+### Scaffolding with `bos init`
+
+```bash
+bos init myapp.everything.dev \
+  --extends dev.everything.near/dev.everything.dev \
+  --overrides ui,plugins \
+  --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.
+
+### 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>`).
+
+See the `extends-config` skill for deep merge semantics, per-environment extends, and canonical field ordering.
+
+## Common Mistakes
+
+- **Wrong header for API keys** — use `x-api-key`, not `Authorization: Bearer`. The `Authorization` header is only listed in CORS allowed headers for third-party integrations, not for everything.dev auth.
+- **Missing `credentials: "include"`** — session cookies won't be sent without it. Both `createApiClient` and `createAuthClient` set this automatically; external clients must set it manually.
+- **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.