everything-dev 1.53.2 → 2.0.0-rc.1

package/skills/plugin-development/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: plugin-development
-description: Build, register, and deploy plugins within everything.dev. Covers the _template scaffold, contract/service/index pattern, database setup with Drizzle, bos.config.json registration, plugin UI/sidebar, and CLI workflow. Use when creating new plugins, adding database-backed routes, or deploying plugins to production.
+description: Build, register, and deploy plugins within everything.dev. Covers the _template scaffold, contract/service/index pattern, database setup with Drizzle, authored-config registration, plugin UI/sidebar, and CLI workflow. Use when creating new plugins, adding database-backed routes, or deploying plugins to production.
 metadata:
-  sources: "plugins/_template/src/index.ts,plugins/_template/src/contract.ts,plugins/_template/src/service.ts,plugins/_template/rspack.config.js,plugins/_template/plugin.dev.ts,plugins/projects/src/db/schema.ts,plugins/projects/src/db/layer.ts,api/src/db/index.ts,api/src/db/migrator.ts,packages/every-plugin/src/plugin.ts"
+  sources: "plugins/_template/src/index.ts,plugins/_template/src/contract.ts,plugins/_template/src/service.ts,packages/every-plugin/src/build/rspack,plugins/_template/plugin.dev.ts,plugins/_template/src/db/schema.ts,plugins/_template/src/db/layer.ts,api/src/db/index.ts,api/src/db/migrate.ts,packages/every-plugin/src/plugin.ts,packages/everything-dev/src/cli.ts"
 ---
 
+> **Config form:** the authored config is `bos.app.ts` (canonical, preferred when both exist). A legacy `bos.config.json` is still supported for older children. Where this doc says `bos.config.json` for the *local authored file*, read "the authored config". The published artifact on FastKV keeps the key name `bos.config.json`.
+
 # Plugin Development
 
 ## Plugin Structure
@@ -45,8 +47,8 @@ Or use the CLI (no automated command yet — copy template manually).
 Use `oc.router()` to define typed routes. Each route has a method, path, optional input/output schemas, and optional error declarations:
 
 ```ts
-import { eventIterator, oc } from "every-plugin/orpc";
-import { z } from "every-plugin/zod";
+import { eventIterator, oc } from "@orpc/contract";
+import { z } from "zod";
 
 // Define errors this plugin throws
 const Errors = {
@@ -86,7 +88,7 @@ export type ContractType = typeof contract;
 ```
 
 Key rules:
-- Import from `every-plugin/zod`, `every-plugin/orpc`, `every-plugin/errors` — never directly from `zod` or `@orpc/*`
+- Import `z` from `zod`, `oc`/`eventIterator` from `@orpc/contract`, and `Effect`/`Layer` from `effect` directly — the `every-plugin/zod`, `every-plugin/orpc`, and `every-plugin/effect` facade barrels were deleted. Use `every-plugin/errors` for the shared error shapes
 - Path params (`{id}`) automatically bind to Zod input keys
 - `.output(eventIterator(Schema))` enables SSE streaming routes
 - `.errors(Errors)` enables typed error handling in generated clients
@@ -96,7 +98,7 @@ Key rules:
 Services are plain classes or functions, optionally using Effect:
 
 ```ts
-import { Effect } from "every-plugin/effect";
+import { Effect } from "effect";
 
 export class TemplateService {
   constructor(
@@ -127,10 +129,10 @@ Use `Effect.runPromise(service.method())` to bridge Effect and async handlers in
 ## Step 4: Wire with `createPlugin` (`src/index.ts`)
 
 ```ts
+import { ORPCError } from "@orpc/server";
+import { Effect } from "effect";
 import { createPlugin } from "every-plugin";
-import { Effect } from "every-plugin/effect";
-import { MemoryPublisher, ORPCError } from "every-plugin/orpc";
-import { z } from "every-plugin/zod";
+import { z } from "zod";
 import { contract } from "./contract";
 import type { PluginsClient } from "./plugins-client.gen";
 import { TemplateService } from "./service";
@@ -167,7 +169,7 @@ export default createPlugin.withPlugins<PluginsClient>()({
       const publisher = new MemoryPublisher({ resumeRetentionSeconds: 120 });
 
       // For scoped resources (DB pools, caches, repositories):
-      // const repo = yield* tools.buildService(MyRepoTag, MyRepoLive.pipe(...))
+      // const repo = yield* buildScoped(MyRepoTag, MyRepoLive.pipe(...))
 
       return { service, publisher };
     }),
@@ -236,67 +238,21 @@ Good practice:
 
 ### Key Patterns
 
-**`variables`** — Public config exposed in `bos.config.json` (typed, with defaults).  
+**`variables`** — Public config exposed in the authored config (typed, with defaults).  
 **`secrets`** — Private values from `process.env` (typed, dev defaults).  
 **`context`** — Per-request context injected by the host. See "Request Context Reference" below for all available fields.  
-**`initialize`** — Effect-based startup. Create services, publishers, DB connections. Receives an optional third argument `tools` for building scoped resources. Return value is passed as `deps` to `createRouter`.  
-**`tools`** — Framework-provided third argument in `initialize(config, plugins, tools)`. Use `tools.buildService(tag, layer)` to build scoped resources (DB pools, caches, repositories) that live for the plugin's lifetime.  
+**`initialize`** — Effect-based startup. Return an Effect `Layer`; the runtime builds it against the plugin's lifecycle scope. Use `buildScoped(tag, layer)` (or `buildScopedContext(layer)` for multi-service layers) from `"every-plugin"` to build scoped resources (DB pools, caches, repositories) that live for the plugin's lifetime.  
 **`createRouter`** — Maps contract procedures to handlers. Receives the value returned by `initialize` plus a pre-configured `builder`.
 
-## Request Context Reference
+## Request Context
 
-The host injects a per-request context object into every plugin. The plugin **must declare the fields it uses** in its context zod schema. Only declared fields are available to route handlers and middleware:
+The host injects a per-request context object into every plugin. The plugin **must declare the fields it uses** in its context zod schema — the schema is a filter; the host passes all fields, but your plugin only sees what you declare.
 
-```ts
-context: z.object({
-  userId: z.string().optional(),
-  user: z.object({
-    id: z.string(),
-    role: z.string().optional(),   // "admin", "member", or null for anon
-    email: z.string().optional(),
-    name: z.string().optional(),
-  }).optional(),
-  organizationId: z.string().optional(),   // Active organization UUID
-  organization: z.object({
-    activeOrganizationId: z.string().nullable().optional(),
-    organization: z.object({
-      id: z.string(),
-      name: z.string(),
-      slug: z.string(),
-      logo: z.string().nullable().optional(),
-      metadata: z.record(z.string(), z.unknown()).optional(),  // daoAccountId lives here
-    }).nullable().optional(),
-    member: z.object({
-      id: z.string(),
-      role: z.string(),   // User's role within this org ("admin", "member")
-    }).nullable().optional(),
-    isPersonal: z.boolean(),
-    hasOrganization: z.boolean(),
-  }).optional(),
-  near: z.object({
-    primaryAccountId: z.string().nullable(),
-    linkedAccounts: z.array(z.object({
-      accountId: z.string(),
-      network: z.string(),
-      publicKey: z.string(),
-      isPrimary: z.boolean(),
-    })),
-    hasNearAccount: z.boolean(),
-  }).optional(),
-  walletAddress: z.string().optional(),
-  apiKey: z.object({
-    id: z.string(),
-    name: z.string().nullable().optional(),
-    permissions: z.record(z.string(), z.array(z.string())).nullable().optional(),
-  }).optional(),
-  reqHeaders: z.custom<Headers>().optional(),
-  getRawBody: z.custom<() => Promise<string>>().optional(),
-}),
-```
+Available fields: `userId`, `user` (id, role, email, name), `organizationId` / `organization` (active org envelope, `member.role`, `metadata.daoAccountId`), `near` (primaryAccountId, linkedAccounts), `walletAddress`, `apiKey` (id, name, permissions), `reqHeaders`, `getRawBody`.
 
-The zod schema is a filter — the host passes all fields, but your plugin only sees what you declare. For pre-built auth/organization middleware, see the `api-and-auth` skill.
+See [request-context](references/request-context.md) for the full schema and field table. For pre-built auth/organization middleware, see the `api-and-auth` skill.
 
-## Step 5: Register in `bos.config.json`
+## Step 5: Register in the authored config
 
 Add a plugin entry:
 
@@ -323,7 +279,9 @@ Add a plugin entry:
 }
 ```
 
-The CLI updates `bos.config.json` automatically when you run `bos plugin add` / `bos plugin remove`.
+The CLI updates the authored config (`bos.app.ts`) automatically when you run `bos plugin add` / `bos plugin remove`.
+
+**Remote-only plugins:** The `development` key is optional. A plugin can be remote-only (just a `production` URL) — the host/API consume it via `pluginsClient` and HTTP, and types resolve from the deployed manifest. Plugin source does not need to live in the consuming repo. This is how plugins maintained in other repos are mounted.
 
 ## Step 6: `plugin.dev.ts`
 
@@ -393,57 +351,15 @@ export async function createDatabaseDriver(url: string) {
 
 ### Layer Pattern
 
-```ts
-// src/db/layer.ts
-import { Effect, Layer } from "every-plugin/effect";
-import { createDatabaseDriver } from "./index";
-
-export class DatabaseTag extends Context.Tag("plugins/your-plugin/Database")<
-  DatabaseTag,
-  { db: any; close: () => Promise<void> }
->() {}
-
-export function DatabaseLive(url: string) {
-  return Layer.scoped(
-    DatabaseTag,
-    Effect.acquireRelease(
-      Effect.promise(async () => {
-        const driver = await createDatabaseDriver(url);
-        return driver;
-      }),
-      (driver) => Effect.promise(() => driver.close()),
-    ),
-  );
-}
-```
+`DatabaseLive` is a `Layer.scoped` that creates the driver, runs migrations (inside the scoped layer, so the pool stays open for migration queries), and returns the `db`. `acquireRelease` closes the driver on scope release. See [database](references/database.md) for the full implementation.
 
 ### Migration Generation
 
 1. Create `drizzle.config.ts` in your plugin directory
 2. Run `drizzle-kit generate` to produce SQL migration files
-3. Store migrations in `src/db/migrations/`
-4. Use the custom `migrate()` function during `initialize`. Pass an explicit
-   `storage` resolved from the workspace so the journal slug is reliable
-   under rspack/Module Federation bundling (the no-arg fallback reads
-   `npm_package_name`, which is unreliable in bundled remotes):
+3. Store migrations in `src/db/migrations/` with an explicit `storage` resolved from the workspace (the no-arg fallback reads `npm_package_name`, unreliable under rspack/Module Federation bundling)
 
-```ts
-initialize: (config) =>
-  Effect.gen(function* () {
-    const driver = yield* DatabaseLive(config.secrets.DATABASE_URL);
-    // Or load and apply migrations directly:
-    const { loadMigrations } = yield* Effect.promise(() => import("./db/load-migrations"));
-    const { migrate } = yield* Effect.promise(() => import("./db/migrator"));
-    const { getMigrationSlug, getMigrationStorage } = yield* Effect.promise(
-      () => import("everything-dev/db"),
-    );
-    const storage = getMigrationStorage(getMigrationSlug(import.meta.dirname));
-    const migrations = yield* loadMigrations();
-    yield* migrate(driver.db, migrations, storage);
-
-    return { db: driver.db, ... };
-  }),
-```
+Migrations run inside `DatabaseLive`'s scoped layer. The critical rule is to **build the DB-backed service via `buildScoped`** so the scope (and the pool) lives for the plugin's lifetime. Do NOT call `DatabaseLive` directly in `initialize` and extract the driver — that creates a transient scope that releases the pool immediately. See [database](references/database.md) for correct/wrong examples.
 
 ### Per-Plugin Isolation
 
@@ -461,7 +377,7 @@ Use `createPlugin.withPlugins<PluginsClient>()` to get typed access to other plu
 
 ## Plugin UI
 
-Add a UI remote via the `ui` field in `bos.config.json`. Sidebar items are defined manually in `ui/src/routes/_layout.tsx`.
+Add a UI remote via the `ui` field in the authored config. Sidebar items are defined manually in `ui/src/components/layout/nav-items.ts`.
 
 ## Deploy
 
@@ -470,12 +386,30 @@ bos plugin publish          # Build and publish just this plugin
 bos publish --deploy        # Build ALL packages + deploy + publish config
 ```
 
-Deploy builds via `rspack.config.js`, uploads to Zephyr CDN, updates `bos.config.json` with production URL + integrity hash, and publishes to FastKV registry. Restart the host after publishing.
+Builds the plugin, pins the deterministic image-native production URL into the published config (`https://<domain>/bundles/<account>/<gateway>/<key>/`), and publishes to FastKV registry. Restart the host after publishing.
 
 ### CLI Lifecycle
 
 1. `cp -r plugins/_template plugins/your-plugin` then edit names
-2. Register in `bos.config.json` (or `bos plugin add`)
+2. Register in the authored config (or `bos plugin add`)
 3. `bos types gen`
 4. `bos dev` to develop
 5. `bos plugin publish` to deploy
+
+## The tasks you will actually be given
+
+**"Add a DB-backed route."** Schema in `src/db/schema.ts` → `drizzle-kit generate` → inside `initialize`, build the repo with `buildScoped(RepoTag, RepoLive.pipe(Layer.provide(DatabaseLive(config.secrets.YOURPLUGIN_DATABASE_URL))))` → handler is `.effect(function* ...)` and does `yield* RepoTag`.
+
+**"Register and deploy a new plugin."** `bos plugin add local:plugins/your-plugin` (writes the authored config + regenerates types) → `pnpm run typecheck` → `bos plugin publish your-plugin` → restart the host.
+
+**"Expose a service to the host, not just oRPC."** Set `servicesTag` on the plugin definition — handlers keep accessing it with `yield* Tag` as normal.
+
+## What comes back when it fails
+
+| word | do |
+|---|---|
+| pool dead / connection released right after startup | a transient scope — you extracted the driver instead of building the service via `buildScoped(...)` inside `initialize`; rebuild it that way (see [database](references/database.md)) |
+| `ModuleFederationError` / `__webpack_modules__[e].call` in the browser | the deployed `mf-manifest.json` is older than the host's federation runtime — `bos mf check`, then `bos plugin publish <key>`, restart the host |
+| migration never runs | migrations execute inside `DatabaseLive`'s scoped layer at plugin boot — confirm the plugin booted and the `<YOU>_DATABASE_URL` secret resolves |
+| handler can't see `context.userId` | the context zod schema is a filter — declare every field you use or the host's value is stripped |
+| stale types in `plugins-client.gen.ts` | `bos types gen` (or `pnpm run typecheck`) after editing any contract |

package/skills/plugin-development/references/database.md

@@ -0,0 +1,82 @@
+# Database Layer Pattern
+
+`DatabaseLive` is a `Layer.scoped` that creates the driver, runs migrations, and returns the `db`. The `acquireRelease` ensures `driver.close()` runs when the scope is released. Migrations run **inside** the scoped layer so the pool stays open for the migration queries:
+
+```ts
+// src/db/layer.ts
+import { PluginIdTag } from "every-plugin";
+import { Context, Effect, Layer } from "effect";
+import { getMigrationStorage, pluginMigrationSlug } from "everything-dev/db";
+import { createDatabaseDriver, type Database, DatabaseError } from "./index";
+import { detectDrift, loadMigrations, migrate } from "./migrate";
+
+export class DatabaseTag extends Context.Tag("Database")<Database, Database>() {}
+
+export const DatabaseLive = (url: string) =>
+  Layer.scoped(
+    DatabaseTag,
+    Effect.gen(function* () {
+      const pluginId = yield* PluginIdTag;
+      const slug = pluginMigrationSlug(pluginId);
+      const schemaName = `plugin_${slug}`;
+
+      const driver = yield* Effect.acquireRelease(
+        Effect.tryPromise({
+          try: () => createDatabaseDriver(url, schemaName),
+          catch: (cause) => new DatabaseError({ stage: "driver", cause }),
+        }),
+        (driver) =>
+          Effect.tryPromise({
+            try: () => driver.close(),
+            catch: (cause) => new DatabaseError({ stage: "close", cause }),
+          }).pipe(Effect.ignore),
+      );
+
+      const storage = getMigrationStorage(slug);
+      const { migrations, source } = yield* loadMigrations();
+
+      if (migrations.length > 0) {
+        const applied = yield* migrate(driver.db, migrations, storage, schemaName);
+        yield* Effect.logInfo(
+          `[Database] Applied ${applied}/${migrations.length} migration(s) (source: ${source})`,
+        );
+        const drift = yield* detectDrift(driver.db, migrations, storage, schemaName);
+        if (drift.status === "healthy" || drift.status === "untracked-existing-schema") {
+          yield* Effect.logInfo(`[Database] Ready`);
+        }
+      }
+
+      return driver.db;
+    }),
+  );
+```
+
+## Migration Generation
+
+1. Create `drizzle.config.ts` in your plugin directory
+2. Run `drizzle-kit generate` to produce SQL migration files
+3. Store migrations in `src/db/migrations/`
+4. Pass an explicit `storage` resolved from the workspace so the journal slug is reliable
+   under rspack/Module Federation bundling (the no-arg fallback reads
+   `npm_package_name`, which is unreliable in bundled remotes).
+
+Migrations run inside `DatabaseLive`'s scoped layer. The critical rule is to **build the DB-backed service via `buildScoped`** so the scope (and the pool) lives for the plugin's lifetime. Do NOT call `DatabaseLive` directly in `initialize` and extract the driver — that creates a transient scope that releases the pool immediately:
+
+```ts
+// CORRECT — buildScoped binds the scope to the plugin lifecycle
+initialize: (config, _plugins) =>
+  Effect.gen(function* () {
+    const database = DatabaseLive(config.secrets.DATABASE_URL);
+    const serviceLayer = MyServiceLive.pipe(Layer.provide(database));
+    const myService = yield* buildScoped(MyServiceTag, serviceLayer);
+
+    return { myService };
+  }),
+
+// WRONG — transient scope: pool.end() fires immediately, migrations fail
+initialize: (config) =>
+  Effect.gen(function* () {
+    const driver = yield* DatabaseLive(config.secrets.DATABASE_URL);
+    return { db: driver.db };
+  }),
+```

package/skills/plugin-development/references/request-context.md

@@ -0,0 +1,67 @@
+# Request Context Reference
+
+The host injects a per-request context object into every plugin. The plugin **must declare the fields it uses** in its context zod schema. Only declared fields are available to route handlers and middleware — the schema is a filter.
+
+## Full Schema
+
+```ts
+context: z.object({
+  userId: z.string().optional(),
+  user: z.object({
+    id: z.string(),
+    role: z.string().optional(),   // "admin", "member", or null for anon
+    email: z.string().optional(),
+    name: z.string().optional(),
+  }).optional(),
+  organizationId: z.string().optional(),   // Active organization UUID
+  organization: z.object({
+    activeOrganizationId: z.string().nullable().optional(),
+    organization: z.object({
+      id: z.string(),
+      name: z.string(),
+      slug: z.string(),
+      logo: z.string().nullable().optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),  // daoAccountId lives here
+    }).nullable().optional(),
+    member: z.object({
+      id: z.string(),
+      role: z.string(),   // User's role within this org ("admin", "member")
+    }).nullable().optional(),
+    isPersonal: z.boolean(),
+    hasOrganization: z.boolean(),
+  }).optional(),
+  near: z.object({
+    primaryAccountId: z.string().nullable(),
+    linkedAccounts: z.array(z.object({
+      accountId: z.string(),
+      network: z.string(),
+      publicKey: z.string(),
+      isPrimary: z.boolean(),
+    })),
+    hasNearAccount: z.boolean(),
+  }).optional(),
+  walletAddress: z.string().optional(),
+  apiKey: z.object({
+    id: z.string(),
+    name: z.string().nullable().optional(),
+    permissions: z.record(z.string(), z.array(z.string())).nullable().optional(),
+  }).optional(),
+  reqHeaders: z.custom<Headers>().optional(),
+  getRawBody: z.custom<() => Promise<string>>().optional(),
+}),
+```
+
+## Field Summary
+
+| Field | Description |
+|-------|-------------|
+| `userId` | Authenticated user id (absent for anon) |
+| `user` | Full user record (id, role, email, name) |
+| `organizationId` / `organization` | Active org envelope from Better Auth: `activeOrganizationId`, org details (`metadata.daoAccountId`), and the user's `member.role` |
+| `near` | Primary NEAR account + linked accounts (accountId, network, publicKey, isPrimary) |
+| `walletAddress` | Primary NEAR account id, flat |
+| `apiKey` | API key auth: `id`, `name`, `permissions` (resource → action list) |
+| `reqHeaders` | Incoming request `Headers` (forward to auth client) |
+| `getRawBody` | Raw body accessor (webhook-style handlers) |
+
+For pre-built auth/organization middleware, see the `api-and-auth` skill.

package/skills/publish-sync/SKILL.md

@@ -1,50 +1,58 @@
 ---
 name: publish-sync
-description: Publish bos.config.json to the FastKV registry, sync from upstream, and upgrade workspace packages. Use when deploying, syncing, or managing runtime configuration across projects.
+description: Publish the authored config (bos.app.ts) to the FastKV registry, sync from upstream, and upgrade workspace packages. Use when deploying, syncing, or managing runtime configuration across projects.
 metadata:
   sources: "packages/everything-dev/src/plugin.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/fastkv.ts,packages/everything-dev/src/integrity.ts,packages/everything-dev/src/config.ts"
 ---
 
+> **Config form:** the authored config is `bos.app.ts` (canonical, preferred when both exist). A legacy `bos.config.json` is still supported for older children. Where this doc says `bos.config.json` for the *local authored file*, read "the authored config". The published artifact on FastKV keeps the key name `bos.config.json`.
+
 # everything-dev Publish & Sync
 
 ## Core Workflow
 
 ```
-Build → Deploy → Publish → Sync
-  ↓       ↓        ↓        ↓
-rspack  Zephyr   FastKV   bos sync
-        CDN      registry
+Build → Publish → Sync
+  ↓        ↓        ↓
+rspack  FastKV    bos sync
 ```
 
 ## Publish
 
-Publish `bos.config.json` to the configured FastKV registry path for the app account/domain:
+Publish the resolved config to the configured FastKV registry path for the app account/domain:
 
 ```bash
-bos publish                  # Publish config only
-bos publish --deploy         # Build/deploy all workspaces first, then publish
-bos publish --dry-run        # Preview without sending
+bos publish                        # Publish config only
+bos publish --deploy               # Build/deploy all workspaces first, then publish
+bos publish --deploy --packages local   # Build/deploy only the workspaces owned locally (recommended for CI)
+bos publish --dry-run              # Preview without sending
 bos publish --network testnet
-bos publish --packages ui,api
+bos publish --packages ui,api      # Manual subset
 ```
 
+`--packages` accepts a comma-separated key list, `all` (default), or `local`. `local` selects only the entries whose `development` field starts with `local:`, so it auto-tracks whatever plugins or apps live in this repo without you editing workflow files when a plugin is added. CI deploy configuration should use `--packages local` exclusively; remote-only plugins can't be redeployed from this repo and will fail with a missing-local-path error.
+
+The registry transaction is signed in-process via near-kit — key resolution order: explicit key → `NEAR_PRIVATE_KEY` / `BOS_NEAR_PRIVATE_KEY` env → `~/.near-credentials/<network>/<account>.json` → near-cli-rs OS keychain (`sign-with-keychain`, interactive only). Publishes are skipped when FastKV already holds an identical config. Reads are indexed by tx signer, so the config resolves at `bos://<account>/<gateway>` only when signed by `<account>` itself — see the `registry` skill for the namespace=signer law and composing other runtimes (`bos registry use`).
+
 After `bos publish --deploy`:
-1. Each workspace builds and deploys to Zephyr CDN
-2. `bos.config.json` is auto-updated with production URLs + integrity hashes
+1. Each workspace builds; the publish writes deterministic bundle URLs (`https://<domain>/bundles/<account>/<gateway>/<workspace>/`)
+2. Pipeline state (production URLs, integrity) goes to FastKV. For legacy JSON-form projects, `bos.config.json` is also updated locally; for the authored `bos.app.ts` form, nothing is written back — the authoring surface never holds pipeline state
 3. Config is published to the FastKV registry at `{account}/bos/gateways/{gateway}/bos.config.json`
 
 The `--network` flag controls the NEAR network (mainnet by default). With `--network testnet`, publishes go to the NEAR testnet chain under the testnet account specified in config.
 
 ### Rollback
 
-To revert a publish, restore the previous `bos.config.json` from git and re-publish:
+To revert a publish, restore the previous authored config from git and re-publish:
 
 ```bash
-git checkout HEAD~1 -- bos.config.json
+git checkout HEAD~1 -- bos.app.ts
 bos publish
 ```
 
-Or cherry-pick a specific version of `bos.config.json` and publish that snapshot.
+A config-only publish merges the freshly authored config over the currently published one — authored edits win, and the live pipeline state (bundle URLs, integrity) carries over. Removing a slot from the authored config requires `bos deploy`, which regenerates the payload from scratch. Legacy JSON-form children re-publish their `bos.config.json` as-is.
+
+Or cherry-pick a specific version of the authored config and publish that snapshot. Prefer `bos rollback --previous` (or `--version <height>`) — it republishes a verified FastKV snapshot without touching git.
 
 Lineage model:
 - `extends` is the canonical parent edge between published runtimes
@@ -52,9 +60,28 @@ Lineage model:
 - `domain` is the public ingress for that runtime
 - a child runtime can extend a parent and still become a new tenant root on its own domain
 
+### Self-Deployed / Tenant Publishing
+
+You don't need to wait for CI/CD to see changes in production. Publish your own config on-chain under your own NEAR account and run your own host instance, inheriting the base platform via `extends`.
+
+**Same gateway, own account:**
+
+`BOS_GATEWAY` (`domain` in the authored config) is the **FastKV lookup key**, not the DNS domain your Railway instance serves on. By keeping `BOS_GATEWAY` the same as the parent while using your own `BOS_ACCOUNT`, your config lives at a separate FastKV path (`bos://<your-account>/<gateway>`) that `extends` the base runtime. You inherit the full platform — host, API, auth, plugins — and override only what you change. Your Railway URL is the ingress.
+
+**Step-by-step:**
+
+1. Install near-cli-rs (v0.23.5) — only needed for account creation and `bos key generate`; `bos publish` signs transactions in-process via near-kit
+2. Create a NEAR account via near-cli-rs (testnet or mainnet; named accounts can own subaccounts, implicit hex accounts cannot)
+3. `bos key generate` — generates a function-call key scoped to the FastKV registry contract; set the output as `NEAR_PRIVATE_KEY`
+4. Update `bos.config.json`: set `account` to your NEAR account, add `"extends": "bos://<parent-account>/<parent-gateway>"`, keep `domain` as the parent gateway
+5. `bos publish --deploy` — builds workspaces, writes deterministic bundle URLs, publishes config to FastKV at `bos://<your-account>/<gateway>`
+6. Deploy to Railway (one-click template or `railway up`), set `BOS_ACCOUNT`, `BOS_GATEWAY` (same as parent), `BETTER_AUTH_SECRET` — the host fetches your config from FastKV and serves live
+
+**Subaccount creation** (unused by the tenant wizard today — tenants are owned by the connected sputnik-dao account) requires an explicit relayer with a named account: set `siwn.relayer.{mainnet,testnet}.accountId` + a private key, and point `siwn.subAccount.parentAccount`, `siwn.recipients`, and `siwn.relayer.*.whitelistedContracts` to your account.
+
 ## Sync
 
-Pull template updates from the parent referenced by local `bos.config.json`:
+Pull template updates from the parent referenced by the local authored config:
 
 ```bash
 bos sync
@@ -63,7 +90,7 @@ bos sync --dry-run
 ```
 
 What gets synced from the parent template:
-- `app.*.production` — Zephyr URLs
+- `app.*.production` — bundle URLs
 - `app.*.ssr` — SSR URLs
 - `shared` — shared dependency versions
 - framework-owned files like build configs, router wiring, and shared runtime scaffolding
@@ -115,7 +142,7 @@ These are auto-generated during `bos publish --deploy` and verified at runtime b
 
 ## Configuration
 
-All runtime config lives in `bos.config.json`. Key sections:
+All runtime config lives in the authored config. Key sections:
 - `account` — NEAR mainnet account
 - `testnet` — NEAR testnet account
 - `staging.domain` — Staging domain
@@ -153,7 +180,7 @@ For remix-host browsing with the apps plugin:
 
 ### What bos dev writes vs bos publish writes
 
-See `everything-dev#extends-config` for the full table. In short: `bos dev` and `bos build` write to `.bos/bos.resolved-config.json` (gitignored); `bos publish --deploy`, `bos plugin publish`, and `bos sync` write to `bos.config.json`.
+See `everything-dev#extends-config` for the full table. In short: `bos dev` and `bos build` write to `.bos/bos.resolved-config.json` (gitignored); `bos publish --deploy`, `bos plugin publish`, and `bos sync` write to the authored config — `bos.app.ts` for TS-form projects, `bos.config.json` for legacy JSON-form children. Pipeline state (deploy-injected URLs) is written back only for JSON-form.
 
 ## Troubleshooting
 
@@ -165,13 +192,13 @@ bos status            # Check remote health
 ### FastKV publish failures
 
 - **NEAR RPC error**: Verify the configured NEAR account has sufficient gas and the FastKV contract is deployed at `{account}/bos/gateways/{gateway}/bos.config.json`
-- **Account mismatch**: The `bos.config.json` `account` field must match the on-chain account that owns the FastKV path
+- **Account mismatch**: The authored config's `account` field must match the on-chain account that owns the FastKV path
 - **Network mismatch**: Ensure `--network` matches where the account is deployed (mainnet vs testnet)
 - **Dry-run first**: Use `bos publish --dry-run` to preview before sending
 
 ### Integrity verification
 
-During `bos publish --deploy`, integrity SRI hashes are auto-generated for each remote entry and stored in `bos.config.json`. At runtime, the host:
+During `bos publish --deploy`, integrity SRI hashes are auto-generated for each remote entry and stored in the published config (FastKV; also written back to `bos.config.json` for legacy JSON-form children). At runtime, the host:
 - Verifies integrity on first load using bounded streaming (not full-response buffering)
 - Uses stale-while-revalidate for asset requests to avoid latency spikes
 - Blocks HTML and SSR requests on integrity mismatch
@@ -179,10 +206,60 @@ During `bos publish --deploy`, integrity SRI hashes are auto-generated for each
 
 If a remote entry fails integrity check, the host rejects it and falls back to client-rendered output without that remote.
 
+### Federation runtime compatibility (`bos mf check`)
+
+Each deployed bundle's `mf-manifest.json` reports `metaData.pluginVersion` — the version of `@module-federation/runtime` baked into the bundle at build time. The host is the federation **consumer**; each plugin is a **provider** loaded over `mf-manifest.json` and `remoteEntry.js`. When the host's runtime version drifts ahead of a plugin's runtime version, the plugin's `remoteEntry.js` throws:
+
+```
+undefined is not an object (evaluating '__webpack_modules__[e].call')
+```
+
+The host treats this as a soft failure and continues serving with the plugin missing (`⚠ N plugin(s) failed to load`). Production stays live but the plugin is dead.
+
+```bash
+bos mf check                          # exit 0 = all manifests compatible
+bos publish --deploy --packages local # ship a fresh bundle + republish to FastKV
+```
+
+The check fetches `<host>/mf-manifest.json` and every `<plugin>/mf-manifest.json`, asserting:
+
+- `metaData.pluginVersion` matches the host's
+- every `shared[]` dep the host requires (`requiredVersion: ^X.Y.Z`) is provided by the plugin at a compatible version
+
+If `bos mf check` fails for one plugin, redeploy only that plugin from this repo:
+
+```bash
+cd plugins/<key>
+bos plugin publish <key>             # rebuild + pin the workspace's production URL, then publish config
+```
+
+Then from the repo root: `bos publish --deploy --packages local` and `bos mf check` to confirm.
+
+In CI, this runs as a `bos mf check` step on every push/PR (`packages/everything-dev/src/cli.ts:mfCheck`). Treat a failed run as "this bundle is stale; a plugin needs to be redeployed" — never disable.
+
 ### Process issues
 
 ```bash
 bos kill               # Kill all tracked processes
-bun install            # Reinstall deps
+pnpm install           # Reinstall deps
 bos dev                # Restart
 ```
+
+## The tasks you will actually be given
+
+**"Ship one plugin only."** `bos plugin publish <key>` (builds + pins the deterministic URL + publishes config), then `bos mf check` from the repo root to confirm federation compatibility.
+
+**"Roll back a bad publish."** `bos rollback --previous` — republishes a verified FastKV snapshot without touching git; the manual path is `git checkout <ref> -- bos.app.ts` + `bos publish`.
+
+**"Deploy my own runtime under my own account."** NEAR account + `bos key generate` → `NEAR_PRIVATE_KEY`; authored config sets your `account` + `extends` the parent and keeps `domain` as the parent gateway; `bos publish --deploy`; run the image with `BOS_ACCOUNT` / `BOS_GATEWAY`.
+
+## What comes back when it refuses
+
+| word | do |
+|---|---|
+| publish returns `status: "error"` before signing | preflight failed — key resolution (no `NEAR_PRIVATE_KEY` / credentials / keychain) or the registry read; run `bos publish --dry-run` to see the plan |
+| config resolves to nothing at `bos://<account>/<gateway>` | namespace = signer — the tx was signed by a different account than the config's `account`; sign with the publisher's key (see the `registry` skill) |
+| `integrity mismatch for <url>` | the remote entry's SRI hash diverges from the published config — redeploy that workspace and republish; the host blocks HTML/SSR on mismatch and client-renders without the remote |
+| `N plugin(s) failed to load` at host startup | `bos mf check` — a plugin's `metaData.pluginVersion` lags the host; republish that plugin |
+| `missing-local-path` error on `--packages local` | a selected entry has no `development: local:` (remote-only) — it can't be rebuilt from this repo; drop it from the selection |
+| publish prints nothing / skips | FastKV already holds an identical config — a free no-op, nothing to fix |