everything-dev 1.53.2 → 2.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-dev",
-  "version": "1.53.2",
+  "version": "2.0.0-rc.0",
   "type": "module",
   "engines": {
     "node": ">=20.11"
@@ -19,6 +19,16 @@
       "import": "./dist/types.mjs",
       "require": "./dist/types.cjs"
     },
+    "./descriptor": {
+      "types": "./dist/descriptor/index.d.mts",
+      "import": "./dist/descriptor/index.mjs",
+      "require": "./dist/descriptor/index.cjs"
+    },
+    "./resolution": {
+      "types": "./dist/resolution/session.d.mts",
+      "import": "./dist/resolution/session.mjs",
+      "require": "./dist/resolution/session.cjs"
+    },
     "./config": {
       "types": "./dist/config.d.mts",
       "import": "./dist/config.mjs",
@@ -29,6 +39,26 @@
       "import": "./dist/dag.mjs",
       "require": "./dist/dag.cjs"
     },
+    "./bundle-cache": {
+      "types": "./dist/bundle-cache.d.mts",
+      "import": "./dist/bundle-cache.mjs",
+      "require": "./dist/bundle-cache.cjs"
+    },
+    "./fingerprint": {
+      "types": "./src/fingerprint.ts",
+      "import": "./src/fingerprint.ts",
+      "require": "./src/fingerprint.ts"
+    },
+    "./version-manifest-resolve": {
+      "types": "./src/version-manifest-resolve.ts",
+      "import": "./src/version-manifest-resolve.ts",
+      "require": "./src/version-manifest-resolve.ts"
+    },
+    "./bundle-fs-resolve": {
+      "types": "./dist/bundle-fs-resolve.d.mts",
+      "import": "./dist/bundle-fs-resolve.mjs",
+      "require": "./dist/bundle-fs-resolve.cjs"
+    },
     "./fastkv": {
       "types": "./dist/fastkv.d.mts",
       "import": "./dist/fastkv.mjs",
@@ -89,6 +119,11 @@
       "import": "./dist/ui/head.mjs",
       "require": "./dist/ui/head.cjs"
     },
+    "./ui/i18n": {
+      "types": "./dist/ui/i18n.d.mts",
+      "import": "./dist/ui/i18n.mjs",
+      "require": "./dist/ui/i18n.cjs"
+    },
     "./ui/metadata": {
       "types": "./dist/ui/metadata.d.mts",
       "import": "./dist/ui/metadata.mjs",
@@ -99,11 +134,75 @@
       "import": "./dist/ui/router.mjs",
       "require": "./dist/ui/router.cjs"
     },
+    "./ui/api": {
+      "types": "./dist/ui/api.d.mts",
+      "import": "./dist/ui/api.mjs",
+      "require": "./dist/ui/api.cjs"
+    },
+    "./ui/auth": {
+      "types": "./dist/ui/auth.d.mts",
+      "import": "./dist/ui/auth.mjs",
+      "require": "./dist/ui/auth.cjs"
+    },
+    "./api": {
+      "types": "./dist/api/auth-middleware.d.mts",
+      "import": "./dist/api/auth-middleware.mjs",
+      "require": "./dist/api/auth-middleware.cjs"
+    },
+    "./ui/tenant": {
+      "types": "./dist/ui/tenant.d.mts",
+      "import": "./dist/ui/tenant.mjs",
+      "require": "./dist/ui/tenant.cjs"
+    },
+    "./ui/entry": {
+      "types": "./dist/ui/entry.d.mts",
+      "import": "./dist/ui/entry.mjs",
+      "require": "./dist/ui/entry.cjs"
+    },
+    "./ui/hydrate": {
+      "types": "./dist/ui/hydrate.d.mts",
+      "import": "./dist/ui/hydrate.mjs",
+      "require": "./dist/ui/hydrate.cjs"
+    },
+    "./ui/router-client": {
+      "types": "./dist/ui/router-client.d.mts",
+      "import": "./dist/ui/router-client.mjs",
+      "require": "./dist/ui/router-client.cjs"
+    },
+    "./ui/router-server": {
+      "types": "./dist/ui/router-server.d.mts",
+      "import": "./dist/ui/router-server.mjs",
+      "require": "./dist/ui/router-server.cjs"
+    },
+    "./ui/router-error": {
+      "types": "./dist/ui/router-error.d.mts",
+      "import": "./dist/ui/router-error.mjs",
+      "require": "./dist/ui/router-error.cjs"
+    },
+    "./ui/router-defaults": {
+      "types": "./dist/ui/router-defaults.d.mts",
+      "import": "./dist/ui/router-defaults.mjs",
+      "require": "./dist/ui/router-defaults.cjs"
+    },
+    "./ui/manifest": {
+      "types": "./dist/ui/manifest/index.d.mts",
+      "import": "./dist/ui/manifest/index.mjs",
+      "require": "./dist/ui/manifest/index.cjs"
+    },
+    "./ui/manifest-generator": {
+      "types": "./dist/ui/manifest-generator.d.mts",
+      "import": "./dist/ui/manifest-generator.mjs",
+      "require": "./dist/ui/manifest-generator.cjs"
+    },
     "./package.json": "./package.json",
     "./db": {
-      "types": "./dist/db.d.mts",
-      "import": "./dist/db.mjs",
-      "require": "./dist/db.cjs"
+      "types": "./dist/db/index.d.mts",
+      "import": "./dist/db/index.mjs",
+      "require": "./dist/db/index.cjs"
+    },
+    "./ui/version-check": {
+      "types": "./src/ui/version-check.ts",
+      "import": "./src/ui/version-check.ts"
     }
   },
   "files": [
@@ -135,52 +234,105 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.10.1",
-    "@effect/platform": "^0.96.1",
-    "@effect/platform-node": "^0.106.0",
-    "@module-federation/enhanced": "^2.4.0",
-    "@module-federation/node": "^2.7.42",
-    "@module-federation/runtime-core": "^2.4.0",
+    "@module-federation/enhanced": "^2.9.0",
+    "@module-federation/node": "^2.7.50",
+    "@module-federation/runtime-core": "^2.9.0",
     "chalk": "^5.6.2",
     "defu": "^6.1.7",
     "dotenv": "^17.3.1",
-    "effect": "^3.21.0",
+    "effect": "4.0.0-rc.117",
+    "every-plugin": "^3.0.0-rc.0",
     "execa": "^9.5.2",
-    "every-plugin": "^2.10.1",
     "glob": "^13.0.6",
-    "gradient-string": "^3.0.0",
-    "ink": "^6.8.0",
+    "near-kit": "^0.20.2",
     "pg": "^8.12.0",
-    "tar": "^7.4.3"
+    "tar": "^7.4.3",
+    "yaml": "2.9.0",
+    "zod": "4.6.5"
   },
   "peerDependencies": {
+    "@better-auth/api-key": "1.6.25",
+    "@better-auth/passkey": "1.6.25",
+    "@lingui/core": "5.9.0",
+    "@lingui/react": "5.9.0",
+    "@orpc/client": "2.0.0-beta.35",
+    "@orpc/contract": "2.0.0-beta.35",
+    "@orpc/tanstack-query": "2.0.0-beta.35",
     "@tanstack/react-query": ">=5.0.0",
     "@tanstack/react-router": ">=1.0.0",
-    "react": ">=19.0.0",
-    "react-dom": ">=19.0.0",
-    "effect": "3.21.2",
-    "zod": "4.4.3"
+    "better-auth": "1.6.25",
+    "better-near-auth": "^2.0.0-rc.0",
+    "effect": "4.0.0-rc.117",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "sonner": ">=2.0.0",
+    "zod": "4.6.5"
   },
   "peerDependenciesMeta": {
+    "@lingui/core": {
+      "optional": true
+    },
+    "@lingui/react": {
+      "optional": true
+    },
+    "@better-auth/api-key": {
+      "optional": true
+    },
+    "@better-auth/passkey": {
+      "optional": true
+    },
+    "@orpc/client": {
+      "optional": true
+    },
+    "@orpc/contract": {
+      "optional": true
+    },
+    "@orpc/tanstack-query": {
+      "optional": true
+    },
     "@tanstack/react-query": {
       "optional": true
     },
     "@tanstack/react-router": {
       "optional": true
+    },
+    "sonner": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "better-near-auth": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@better-auth/api-key": "1.6.25",
+    "@better-auth/passkey": "1.6.25",
+    "@lingui/core": "5.9.0",
+    "@lingui/react": "5.9.0",
+    "@module-federation/rsbuild-plugin": "^2.9.0",
+    "@orpc/client": "2.0.0-beta.35",
+    "@orpc/contract": "2.0.0-beta.35",
+    "@orpc/openapi": "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/intent": "^0.3.5",
-    "@tanstack/react-query": "5.90.20",
-    "@tanstack/react-router": "1.157.16",
-    "@types/gradient-string": "^1.1.6",
-    "@types/node": "^22.10.2",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@tanstack/react-query": "5.102.8",
+    "@tanstack/react-router": "1.170.32",
+    "@tanstack/router-generator": "1.167.33",
+    "@tanstack/router-plugin": "1.168.35",
+    "@types/node": "^25.0.3",
     "@types/tar": "^7.0.0",
-    "react-devtools-core": "^7.0.1",
+    "better-auth": "1.6.25",
+    "better-near-auth": "^2.0.0-rc.0",
+    "jsdom": "^30.0.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "tsdown": "^0.22.0",
-    "typescript": "^5.7.2",
+    "typescript": "^7.0.2",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.8"
   }
 }

package/skills/add-a-route/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: add-a-route
+description: Add one API endpoint end to end in everything.dev — contract route with Zod schemas, Effect-native handler in the plugin router, UI call via useApiClient, route file rendering the data, typecheck, publish. Use when adding an API endpoint, wiring a new UI page to app data, or debugging the contract/handler/client chain.
+metadata:
+  sources: "api/src/contract.ts,api/src/index.ts,plugins/_template/src/contract.ts,plugins/_template/src/index.ts,packages/every-plugin/src/errors.ts,ui/src/routes,packages/everything-dev/skills/ui-integration/SKILL.md"
+---
+
+# Add a route
+
+One endpoint, end to end. The slice below is complete — copy it, rename, and
+it runs. Everything is typed from the contract: the handler's `input`/`context`,
+the generated client, and the UI's response shape.
+
+## Where the route lives
+
+| The task in front of you | Put it in |
+|---|---|
+| App-shell glue (health, infra) | `api/src/contract.ts` + `api/src/index.ts` |
+| A feature (things, registry, proposals, votes, chat) | a plugin under `plugins/<name>/` |
+
+Feature routes live in plugins; `api/` is a slim shell. New plugins: copy
+`plugins/_template/` (`everything-dev#plugin-development`).
+
+## The slice
+
+### 1. Contract (`plugins/<name>/src/contract.ts`)
+
+```ts
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { FORBIDDEN, NOT_FOUND, UNAUTHORIZED } from "every-plugin/errors";
+
+export const WidgetSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+});
+
+export const contract = oc.router({
+  getWidget: oc
+    .route({ method: "GET", path: "/widgets/{id}" })
+    .input(z.object({ id: z.string().min(1) }))
+    .output(z.object({ widget: WidgetSchema }))
+    .errors({ NOT_FOUND, UNAUTHORIZED, FORBIDDEN }),
+});
+
+export type ContractType = typeof contract;
+```
+
+Path params (`{id}`) bind to the Zod input keys automatically.
+
+### 2. Handler (`plugins/<name>/src/index.ts`)
+
+```ts
+export default createPlugin.withPlugins<PluginsClient>()({
+  // variables, secrets, context, contract — see the template
+  createRouter: (builder) => ({
+    getWidget: builder.getWidget.effect(function* ({ input, context, errors }) {
+      if (!context.userId) {
+        return yield* Effect.fail(errors.UNAUTHORIZED({ apiKeyProvided: !!context.apiKey }));
+      }
+      const widgets = yield* WidgetsService;
+      const widget = yield* widgets.getWidget(input.id);
+      return { widget };
+    }),
+  }),
+});
+```
+
+The tag (`WidgetsService`) must be exposed from the returned `initialize`
+layer. Handlers are Effect generators — see **Rules** below.
+
+### 3. UI call (any component)
+
+```ts
+import { useApiClient } from "@/app";
+
+const apiClient = useApiClient();
+const { data } = await apiClient.template.listThings({ limit: 20 });
+```
+
+The client is namespaced by the plugin key in `bos.app.ts` — a `widgets`
+plugin is `apiClient.widgets.*` — and typed from the contract;
+`ui/src/lib/api-types.gen.ts` regenerates on `pnpm run typecheck` / `bos dev`.
+
+### 4. Route file (`ui/src/routes/<area>.tsx`)
+
+File-based routing — TanStack Router generates the tree. See
+`everything-dev#ui-integration` for loaders, SSR, and the page-header/testid
+conventions.
+
+### 5. Verify, then publish
+
+```bash
+pnpm run typecheck    # regenerates types, then checks everything
+pnpm run build        # the train — never per-workspace raw builds
+pnpm run deploy       # preflight → build → upload → publish → image
+```
+
+## The tasks you will actually be given
+
+**"Add a read-only endpoint for X."** Contract → handler → UI query. No auth
+schema needed; still add `.errors({ NOT_FOUND })` for typed misses.
+
+**"Add an endpoint only signed-in users can write."** Same slice, plus the
+`context.userId` guard from step 2. For roles, orgs, or API-key permissions,
+load `everything-dev#api-and-auth` for the middleware pattern.
+
+**"The UI can't see the new route."** Types are generated: run
+`pnpm run typecheck` (self-sufficient), or restart `bos dev`. If the client
+name is wrong, the plugin key in `bos.app.ts` is the namespace.
+
+## What comes back when it fails
+
+| word | do |
+|---|---|
+| `Type 'DecoratedMiddleware'…` in `.use()` | middleware typing does not compose with `.use()` — use the local-middleware pattern (`plugins/proposals/src`) |
+| `UNAUTHORIZED` type error | its `data` requires `{ apiKeyProvided: boolean }`; all-optional shapes still need explicit `data: {}` |
+| Effect lint flags floating effects | `pnpm run lint:effect`; `tsc` clean is not enough |
+| `ModuleFederationError` / `__webpack_modules__` | the deployed plugin's `mf-manifest.json` is older than the host's — `bos mf check`, then republish the plugin |
+| 404 on the new route | the route lives in a plugin — the path is `/api/rpc/<pluginKey>/…` or `/api/<contract path>` |
+
+## Rules to work by
+
+- **`.effect(function* ...)`, never new `.handler(async)`.** Services come
+  from `yield* Tag` in generators; `Context.get(context["effect/context"], Tag)`
+  is reserved for streaming (async-generator) handlers.
+- **`Effect.fail`, not throws.** Definitive failure exits are
+  `return yield* Effect.fail(...)`; shared shapes come from `every-plugin/errors`.
+- **No `Effect.provide(Tag, Layer.effect(...))` for persistent deps.** Build
+  scoped services with `buildScoped(...)` inside `initialize` — transient
+  scopes release immediately.
+- **Typecheck before publish.** `pnpm run typecheck` regenerates all types.

package/skills/api-and-auth/SKILL.md

@@ -2,7 +2,7 @@
 name: api-and-auth
 description: API architecture, oRPC contracts, auth middleware, plugin-client composition, session handling, and client-side auth. Use when adding API routes, creating middleware, calling other plugins in-process, or integrating auth in routes and UI.
 metadata:
-  sources: "api/src/index.ts,api/src/contract.ts,api/src/lib/auth.ts,host/src/services/auth.ts,host/src/services/plugins.ts,host/src/program.ts,ui/src/lib/auth.ts,ui/src/lib/api.ts"
+  sources: "api/src/index.ts,api/src/contract.ts,packages/everything-dev/src/api/auth-middleware.ts,packages/every-plugin/src/errors.ts,host/src/services/auth.ts,host/src/services/plugins.ts,host/src/program.ts,ui/src/lib/auth.ts,ui/src/lib/api.ts"
 ---
 
 # API Architecture & Auth
@@ -17,22 +17,21 @@ export default createPlugin.withPlugins<PluginsClient>()({
   secrets: z.object({ /* typed env vars, defaults for dev */ }),
   context: z.object({ /* per-request context injected by host */ }),
   contract,
-  initialize: (config, plugins, tools) =>
+  initialize: (config, plugins) =>
     Effect.gen(function* () {
-      const registry = yield* tools.buildService(
+      const registry = yield* buildScoped(
         RegistryTag,
         RegistryLive.pipe(Layer.provide(DatabaseLive(config.secrets.API_DATABASE_URL))),
       );
       return { registry, publisher, auth: plugins.auth, plugins };
     }),
-  shutdown: (deps) => Effect.promise(async () => { /* cleanup */ }),
-  createRouter: (deps, builder) => ({
+  createRouter: (builder, plugins) => ({
     ping: builder.ping.handler(async () => ({ status: "ok", timestamp })),
   }),
 });
 ```
 
-Fields: `variables` (public config), `secrets` (private env), `context` (per-request host context), `contract` (oRPC router), `initialize` (startup, returns services; third arg `tools` for scoped resources), `createRouter` (maps procedures to handlers), `shutdown` (cleanup). `plugins` in `initialize` gives typed factories for all other plugins. Use `tools.buildService(tag, layer)` for DB-backed services, caches, and other scoped resources.
+Fields: `variables` (public config), `secrets` (private env), `context` (per-request host context), `contract` (oRPC router), `initialize` (startup — build a Layer and let the runtime scope it), `createRouter` (maps procedures to handlers; `(builder, plugins)`). `plugins` in `initialize` gives typed factories for all other plugins. Use `buildScoped(tag, layer)` from `"every-plugin"` for DB-backed services, caches, and other scoped resources — teardown lives in Layer finalizers (there is no `shutdown`).
 
 ## oRPC Contract Design
 
@@ -40,8 +39,8 @@ Defined in `api/src/contract.ts`:
 
 ```ts
 import { BAD_REQUEST, NOT_FOUND, UNAUTHORIZED } from "every-plugin/errors";
-import { eventIterator, oc } from "every-plugin/orpc";
-import { z } from "every-plugin/zod";
+import { eventIterator, oc } from "@orpc/contract";
+import { z } from "zod";
 
 export const contract = oc.router({
   ping: oc.route({ method: "GET", path: "/ping" }).output(
@@ -95,7 +94,7 @@ Handler receives `{ input, context, signal?, lastEventId? }`.
 
 ## Middleware
 
-Create auth middleware with `createAuthMiddleware(builder)` in `api/src/lib/auth.ts`. Each middleware narrows the context type through `.use()` — no non-null assertions needed.
+Create auth middleware with `createAuthMiddleware(builder)` in `packages/everything-dev/src/api/auth-middleware.ts`. Each middleware narrows the context type through `.use()` — no non-null assertions needed.
 
 ```ts
 const { requireAuth } = createAuthMiddleware(builder);
@@ -112,14 +111,14 @@ builder.authHealth.use(requireAuth).handler(...)
 builder.adminAction.use(requireRole("admin")).handler(...)
 ```
 
-See `references/middleware.md` for the full middleware table, org metadata validation, and typed context helpers.
+See [middleware](references/middleware.md) for the full middleware table, org metadata validation, and typed context helpers.
 
 ## Error Handling
 
 Use `ORPCError` from `every-plugin/errors`:
 
 ```ts
-import { ORPCError } from "every-plugin/orpc";
+import { ORPCError } from "@orpc/server";
 import { BAD_REQUEST, UNAUTHORIZED } from "every-plugin/errors";
 
 throw new ORPCError("UNAUTHORIZED", {
@@ -308,22 +307,23 @@ Rules: API owns `thingId`, `pluginId`, timestamps. Plugin owns `type` and `paylo
 
 ### Effect and DB Lifecycle
 
-Prefer `Layer` for long-lived resources (DB, service singletons) and `Effect` for the work itself. Use `runEffect()` to bridge Effect and async handlers with clean ORPC error boundaries — unwraps `ORPCError` from Effect and converts unknown errors to `INTERNAL_SERVER_ERROR`:
+Prefer `Layer` for long-lived resources (DB, service singletons) and `Effect` for the work itself. Handlers are Effect-native: use `.effect()` generator handlers and access services with `yield* Tag` — oRPC bridges to async at the boundary (plain async handlers read services via `Context.get(context["effect/context"], Tag)`):
 
 ```ts
-import { runEffect } from "@/lib/context";
-
-const result = await runEffect(services.myService.doSomething(input));
+ping: builder.ping.effect(function* () {
+  const myService = yield* MyServiceTag;
+  return yield* myService.doSomething();
+}),
 ```
 
-Best practices: Keep service interfaces Effect-native, bridge to async only at the handler boundary via `runEffect()`. Use `Context.Tag` for DI between services.
+Best practices: Keep service interfaces Effect-native. Use `Context.Service<Self, Shape>()("id")` class tags for DI between services (Effect 4 removed `Context.Tag`).
 
-**Scoped resources** — For DB pools, caches, publishers, or any resource that must live for the plugin's lifetime, build them inside `initialize` using `tools.buildService(tag, layer)`. This binds the resource to the plugin lifecycle scope — it persists until plugin shutdown and is automatically released.
+**Scoped resources** — For DB pools, caches, publishers, or any resource that must live for the plugin's lifetime, build them inside `initialize` using `buildScoped(tag, layer)` from `"every-plugin"`. This binds the resource to the plugin lifecycle scope — it persists until plugin shutdown and is automatically released.
 
 ```ts
-initialize: (config, plugins, tools) =>
+initialize: (config, plugins) =>
   Effect.gen(function* () {
-    const repo = yield* tools.buildService(
+    const repo = yield* buildScoped(
       MyRepoTag,
       MyRepoLive.pipe(Layer.provide(DatabaseLive(config.secrets.MY_DATABASE_URL))),
     );
@@ -331,7 +331,7 @@ initialize: (config, plugins, tools) =>
   }),
 ```
 
-Do **not** use `Effect.provide(Tag, Layer.scoped(...))` inside `initialize` for long-lived resources — it creates a transient scope that closes immediately. `tools.buildService(...)` uses the plugin's lifecycle scope instead.
+Do **not** use `Effect.provide(Tag, Layer.scoped(...))` inside `initialize` for long-lived resources — it creates a transient scope that closes immediately. `buildScoped(...)` uses the plugin's lifecycle scope instead.
 
 ### SSR Proxy Client
 
@@ -356,9 +356,57 @@ export function createPluginsClient(result, context) {
 }
 ```
 
+### Tenant-Scoped Data
+
+A **tenant** is a deployment record (subdomain + NEAR account + UI/backend/SSR override
+permissions) — distinct from an organization (a group of users) and from a user's own data.
+If your plugin stores data that belongs to a specific tenant deployment (not just a user or
+org), resolve the tenant and scope every query to it.
+
+The `api` plugin owns the `tenants` table and exposes public lookup routes (no auth required —
+tenant lookups are read-only and safe to expose):
+
+```ts
+// From any plugin, via pluginsClient.api (injected through withPlugins<PluginsClient>())
+const tenant = context.organization?.activeOrganizationId
+  ? await plugins.api().resolveTenantByOrgId({ orgId: context.organization.activeOrganizationId })
+  : await plugins.api().resolveTenant({ accountId: context.near?.primaryAccountId ?? "" });
+```
+
+Build a local `requireTenant` middleware in your own plugin (mirrors `requireOrganization`):
+
+```ts
+const requireTenant = builder.middleware(async ({ context, next }) => {
+  const activeOrgId = context.organization?.activeOrganizationId;
+  const tenant = activeOrgId
+    ? await plugins.api().resolveTenantByOrgId({ orgId: activeOrgId }).catch(() => null)
+    : null;
+  if (!tenant) {
+    throw new ORPCError("FORBIDDEN", { message: "No tenant found for this organization" });
+  }
+  return next({ context: { ...context, tenant } });
+});
+
+builder.listReports.use(requireTenant).handler(async ({ context }) => {
+  return await services.reports.listByTenant(context.tenant.id); // always filtered
+});
+```
+
+**Row-level convention (interim isolation)**: add a `tenantId` column to any table holding
+tenant-specific application data, resolved server-side and never trusted from client input —
+same discipline the `tenants` table itself uses for `orgId` scoping. See
+`plugins/_template/src/db/schema.ts` for a commented example table.
+
+**Forward path**: the target architecture (see `docs/plans/beta-v2/tenants.md`) is per-tenant-per-plugin
+Postgres schema isolation (`tenant_<id>_plugin_<name>`, `search_path` injected per request). That
+requires request-scoped DB access instead of the current initialize-time singleton pattern — a
+larger change, only worth it once there's a real multi-tenant plugin ecosystem to isolate. The
+`tenantId` column convention above is forward-compatible: when schema isolation lands, the column
+becomes redundant and can be dropped without reworking query logic.
+
 ## Generated Types
 
-See `references/generated-types.md` for the full table — files, contents, and regeneration triggers.
+See [generated-types](references/generated-types.md) for the full table — files, contents, and regeneration triggers.
 
 ## SSE Notes
 
@@ -375,3 +423,21 @@ for await (const event of iterator) {
 ## How Routes Are Mounted
 
 The host (`host/src/program.ts`) creates RPC and OpenAPI handlers from each plugin's router, mounted at `/api/rpc/<plugin-namespace>`. The session middleware runs on `/api/*` before the RPC handlers, ensuring context is set.
+
+## The tasks you will actually be given
+
+**"Add an admin-only route."** Contract declares `.errors({ UNAUTHORIZED, FORBIDDEN })`; handler is `.effect(function* ...)` and guards with `return yield* Effect.fail(errors.UNAUTHORIZED({ apiKeyProvided: !!context.apiKey }))` — note all-optional error shapes still need an explicit `data: {}`. For shared middleware shapes, see `packages/everything-dev/src/api/auth-middleware.ts`.
+
+**"Call the auth plugin from my route."** `getAuthClient(services, { reqHeaders: context.reqHeaders })` then `await authClient.getSession()` — in-process, no HTTP roundtrip.
+
+**"Wire an SSE route."** Contract: `.output(eventIterator(Schema))`. Handler: async generator that subscribes to the publisher and yields per event, filtering server-side on `pluginId`/query params.
+
+## What comes back when it fails
+
+| word | do |
+|---|---|
+| `Type 'DecoratedMiddleware'…` on `.use()` | middleware typing does not compose with the `.use()` builder — use the local-middleware pattern (`plugins/proposals/src`) |
+| `UNAUTHORIZED` type error on the fail call | its `data` requires `{ apiKeyProvided: boolean }`; all-optional error shapes still need explicit `data: {}` |
+| runtime 401 with what looks like a valid session | the session middleware resolution returned nulls — check `GET /api/auth/getSession` before blaming the route |
+| `tsc` clean but Effect diagnostics | run `pnpm run lint:effect` (oxlint type-aware) — floating effects and tag mismatches surface there |
+| `ModuleFederationError` / `N plugin(s) failed to load` at startup | the API plugin itself failed to load — `bos mf check`, republish the lagging plugin, restart the host |

package/skills/api-and-auth/references/middleware.md

@@ -16,7 +16,7 @@
 Pass an optional Zod schema to `createAuthMiddleware` for runtime validation:
 
 ```ts
-import { z } from "every-plugin/zod";
+import { z } from "zod";
 
 const orgMetaSchema = z.object({ plan: z.enum(["free", "pro"]), seats: z.number() });
 const { requireOrganization } = createAuthMiddleware(builder, { orgMetaSchema });