everything-dev 1.53.1 → 2.0.0-rc.0

package/skills/cli-reference/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   sources: "packages/everything-dev/src/contract.ts,packages/everything-dev/src/contract.meta.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/cli/catalog.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`.
+
 # CLI Command Reference
 
 17 `bos` commands organised by workflow category.
@@ -29,7 +31,7 @@ bos dev --remote-plugins auth,registry  # force specific plugins remote
 
 ### `bos start`
 
-Start the production host. Loads config from `bos.config.json`, wires MF remotes, serves SSR.
+Start the production host. Loads the authored config (`bos.app.ts`), wires MF remotes, serves SSR.
 
 **Flags:** `--env <production|staging>` `--port <n>` `--account <id>` `--domain <domain>` `--no-interactive`
 
@@ -45,15 +47,18 @@ bos start --account myapp.near     # tenant override
 
 Build all workspace packages (or a subset) for production.
 
-**Flags:** `--packages <list>` `--force` `--deploy`
+**Flags:** `--packages <list|all|local>` `--force` `--deploy`
 
 ```bash
-bos build                    # build all workspaces
-bos build --packages ui,api  # build specific packages
-bos build --force            # rebuild even if up-to-date
-bos build --deploy           # build + deploy to Zephyr
+bos build                       # build all workspaces
+bos build --packages ui,api     # build specific packages (csv)
+bos build --packages local      # build only workspaces whose development starts with local:
+bos build --force               # rebuild even if up-to-date
+bos build --deploy              # build + write deploy URLs
 ```
 
+`--packages` accepts a comma-separated key list, `all` (default), or `local`. `local` selects only entries whose `development` field starts with `local:`, so the build set auto-tracks whatever apps and plugins live in this repo. CI deploy now invokes `bos publish --deploy --packages local` instead of a hand-maintained CSV.
+
 → [`publish-sync`](.) skill for full deploy+publish workflow.
 
 ### `bos config`
@@ -63,7 +68,7 @@ Print the loaded configuration (plain or fully resolved).
 **Flags:** `--full`
 
 ```bash
-bos config        # print bos.config.json with env overrides applied
+bos config        # print the authored config with env overrides applied
 bos config --full # print fully resolved config (extends + deep merge)
 ```
 
@@ -128,29 +133,43 @@ Output includes installed vs latest versions for each workspace package, whether
 
 ### `bos publish`
 
-Publish `bos.config.json` to the FastKV on-chain registry. Optionally build and deploy workspaces first.
+Publish the resolved config to the FastKV on-chain registry. Optionally build and deploy workspaces first.
 
-**Flags:** `--deploy` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--env <production|staging>` `--packages <list>`
+**Flags:** `--deploy` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--env <production|staging>` `--packages <list|all|local>`
 
 ```bash
-bos publish                    # publish current config snapshot
-bos publish --deploy           # build all + deploy + publish
-bos publish --dry-run          # preview what would be published
-bos publish --network testnet  # publish to testnet registry
+bos publish                          # publish current config snapshot
+bos publish --deploy                 # build all + deploy + publish
+bos publish --deploy --packages local   # build/deploy only the workspaces owned by this repo (CI default)
+bos publish --dry-run                # preview what would be published
+bos publish --network testnet        # publish to testnet registry
 ```
 
 → [`publish-sync`](.) skill for config sections, SRI integrity, rollback, and FastKV troubleshooting.
 
+### `bos mf check`
+
+Verify Module Federation runtime compatibility across the published host + plugin config. Fetches every `<remote>/mf-manifest.json`, asserts `metaData.pluginVersion` matches the host, and confirms each plugin provides the shared dependencies the host requires at compatible versions.
+
+```bash
+bos mf check     # exits 0 if compatible, 1 with diagnostic output if not
+```
+
+Use after redeploying any plugin to verify federation reachability before the next deploy. CI runs this on every push/PR; do not disable the gate. When it fails, redeploy the lagging plugin via `cd plugins/<key> && pnpm run deploy && bos publish --deploy`.
+
+→ [`publish-sync`](.) skill for the federation-compat failure mode and the recovery workflow.
+
 ### `bos deploy`
 
 Publish config and trigger a Railway redeploy. Builds and deploys by default.
 
-**Flags:** `--env <production|staging>` `--no-build` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--service <name>` `--packages <list>`
+**Flags:** `--env <production|staging>` `--no-build` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--service <name>` `--packages <list|all|local>`
 
 ```bash
-bos deploy                        # build + publish + trigger deploy
-bos deploy --no-build             # publish only, skip workspace build
-bos deploy --service my-railway   # override Railway service name
+bos deploy                              # build + publish + trigger deploy
+bos deploy --packages local             # build/deploy only this repo's local workspaces
+bos deploy --no-build                   # publish only, skip workspace build
+bos deploy --service my-railway         # override Railway service name
 ```
 
 → [`publish-sync`](.) skill and [`super-app`](.) for tenant-aware deploy considerations.
@@ -173,7 +192,7 @@ Outputs the public key, private key, and registry contract address. The generate
 
 ### `bos plugin add`
 
-Add a plugin attachment to `bos.config.json` from a local path, BOS reference, or remote URL.
+Add a plugin attachment to the authored config from a local path, BOS reference, or remote URL.
 
 **Flags:** `<source>` (positional) `--as <alias>` `--production <url>`
 
@@ -189,7 +208,7 @@ bos plugin add local:plugins/my-plugin --production <prod-url>  # separate prod
 
 ### `bos plugin remove`
 
-Remove a plugin attachment from `bos.config.json`.
+Remove a plugin attachment from the authored config (inherited parent plugins cannot be removed locally).
 
 **Flags:** `<key>` (positional)
 
@@ -209,7 +228,7 @@ Outputs each plugin's key, development source, production URL, local path, versi
 
 ### `bos plugin publish`
 
-Build and publish a single plugin to Zephyr CDN, then update `bos.config.json` with the production URL and SRI integrity hash.
+Build a single plugin, then pin its deterministic image-native production URL into the published config (`https://<domain>/bundles/<account>/<gateway>/<key>/`).
 
 **Flags:** `<key>` (positional)
 
@@ -223,7 +242,7 @@ bos plugin publish my-plugin
 
 ### `bos types gen`
 
-Generate and fetch type definitions from configured API and plugin contracts. Runs automatically on `bun install`, `bos dev`, `bos build`, `bos plugin add`, and `bos plugin remove`.
+Generate and fetch type definitions from configured API and plugin contracts. Runs automatically on `pnpm install`, `bos dev`, `bos build`, `bos plugin add`, and `bos plugin remove`.
 
 **Flags:** `--env <development|production>` `--dry-run`
 
@@ -248,3 +267,11 @@ bos db studio my-plugin   # open for a custom plugin
 ```
 
 Requires the `DATABASE_URL` secret to be set on the target plugin. Uses the plugin's drizzle.config.ts for schema discovery.
+
+## The tasks you will actually be given
+
+**"Regenerate the types."** `bos types gen` — or just `pnpm run typecheck`, which regenerates first and then checks. Never hand-edit `*.gen.ts` files.
+
+**"Which command deploys?"** `pnpm run deploy` (the full train: preflight → build → upload → publish → image). Config-only is `bos publish`; one plugin is `bos plugin publish <key>`.
+
+**"What is running right now?"** `bos ps` for tracked dev processes, `bos status` for health and versions, `ls .bos/logs/` for per-service logs.

package/skills/code-style/SKILL.md

@@ -60,3 +60,11 @@ metadata:
 - If neighboring files use `function Component()`, don't use `const Component: React.FC = () =>`
 - If neighboring files group imports by type (React, third-party, local), do the same
 - Consistent file structure within a directory is more important than personal preference
+
+## The tasks you will actually be given
+
+**"Review my new component for style."** Check four things: file is kebab-case with a PascalCase named export, classes use semantic tokens (`bg-background`, `text-muted-foreground`) not hardcoded colors, no inline comments, imports use `@/` aliases grouped like the neighbors.
+
+**"Where does this shared component go?"** `ui/src/components/ui/<name>.tsx`, named export, added to `ui/src/components/index.ts`. Feature-specific components stay colocated with the route that uses them.
+
+**"Is this file name ok?"** Lowercase kebab-case for every file and directory, including routes. PascalCase file names are the only hard violation; route path segments follow TanStack conventions (`_` prefix for layouts).

package/skills/dev-workflow/SKILL.md

@@ -2,9 +2,11 @@
 name: dev-workflow
 description: Development workflow for everything-dev projects using bos dev, bos start, and the Module Federation runtime. Use when starting dev servers, debugging hot reload, or understanding the service-descriptor architecture.
 metadata:
-  sources: "packages/everything-dev/src/service-descriptor.ts,packages/everything-dev/src/orchestrator.ts,packages/everything-dev/src/dev-logs.ts,packages/everything-dev/src/dev-session.ts,packages/everything-dev/src/process-registry.ts,packages/everything-dev/src/app.ts"
+  sources: "packages/everything-dev/src/service-descriptor.ts,packages/everything-dev/src/orchestrator.ts,packages/everything-dev/src/dev-logs.ts,packages/everything-dev/src/dev-session.ts,packages/everything-dev/src/process-registry.ts,packages/everything-dev/src/app.ts,packages/everything-dev/src/infra/preflight.ts,packages/everything-dev/src/dev-program.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 Development Workflow
 
 ## Starting Development
@@ -18,22 +20,29 @@ bos dev --api remote     # UI only
 bos dev --ui remote      # API only
 bos dev                  # Full local (rarely needed)
 
-# Pin individual service ports (unset flags are picked automatically and persisted)
+# Pin individual service ports (explicitly-passed flags are pinned; unset services derive from the base)
 bos dev --port 3100 --api-port 3101 --ui-port 3103 --auth-port 3102 --plugin-port-start 3110
 ```
 
-### Port persistence
+### Port persistence (ADR 0012)
 
-`bos dev` writes the resolved host/api/ui/auth/plugin-port-start values to `.bos/infra-state.json`
-under a `devPorts` key. Subsequent runs reuse the same ports unless you pass an explicit flag
-(or delete the file). This keeps CORS, browser bookmarks, and wallet-allowlisted origins stable
-across restarts.
+Port allocation is atomic block allocation: the layout derives deterministically from one base
+(`--port N` → api N+1, auth N+2, ui N+3, plugins N+10+), and the whole block is validated before
+anything spawns. Only explicitly-passed port flags persist to `.bos/infra-state.json` under
+`devPorts` — never drift. If the preferred block is occupied, the session takes the next block
+(+100) with a prominent notice naming the holders (live sibling sessions via registry claims;
+foreign processes via an lsof ownership probe), and restarts re-try the preferred base.
+Explicitly-passed flags are pinned: an occupied explicit port fails loudly instead of silently
+moving. `bos kill` escalates SIGTERM → 5s → SIGKILL, reaps orphaned children of dead sessions,
+and verifies ports actually freed; new sessions adopt-and-reap orphaned children from dead
+same-project sessions at boot. Test-spawned stacks never persist ports (`BOS_NO_PERSIST_PORTS=1`,
+plus `NODE_ENV=test` / `BOS_TEST=1` are honored).
 
 ### Port budgets (forward-compat for `--workspaces`)
 
-`prepareDevelopmentRuntimeConfig` accepts an optional `portBudget: { min, max }`. When set,
-`pickAvailablePort` skips candidates outside the budget and throws `RangeError` if no free port
-is found inside it. The standalone `bos dev` path does not pass a budget today; a future
+The allocator accepts an optional `portBudget: { min, max }`. When set,
+`pickAvailablePort` skips candidates outside the budget and throws `PortAllocationError` if no
+free port is found inside it. The standalone `bos dev` path does not pass a budget today; a future
 `bos dev --workspaces` orchestrator will slice disjoint budgets per child project.
 
 ## Port Assignments
@@ -44,12 +53,11 @@ is found inside it. The standalone `bos dev` path does not pass a budget today;
 | api | 3001 | http://localhost:3001 |
 | auth | 3002 | http://localhost:3002 |
 | ui | 3003 | http://localhost:3003 |
-| ui-ssr | 3004 | http://localhost:3004 |
 | plugins | 3010+ | http://localhost:3010+ (incremental — one per plugin in config order) |
 
 ## Service-Descriptor Architecture
 
-The orchestrator builds a `ServiceDescriptorMap` from `bos.config.json`. Each descriptor defines:
+The orchestrator builds a `ServiceDescriptorMap` from the resolved config. Each descriptor defines:
 - `key` — service identifier (host, ui, api, auth, plugin:*)
 - `source` — `"local"` or `"remote"` (determines if process is spawned or URL is probed)
 - `port` / `defaultPort` — TCP port for local services
@@ -57,7 +65,7 @@ The orchestrator builds a `ServiceDescriptorMap` from `bos.config.json`. Each de
 - `readyPatterns` / `errorPatterns` — Regexes matched against stdout/stderr
 
 The orchestrator:
-1. Spawns local services via `bun run dev` in each package directory
+1. Spawns local services via `pnpm run dev` in each package directory
 2. Probes remote services via HTTP GET to their readiness path
 3. Tracks process state: pending → starting → ready → error
 4. Writes logs to `.bos/logs/{service}.log`
@@ -67,20 +75,19 @@ The orchestrator:
 - **UI changes**: Rsbuild HMR — instant at :3003, no rebuild
 - **API changes**: Rspack HMR — instant at :3001, no rebuild
 - **Auth / Plugin changes**: No HMR — require full restart (`bos kill && bos dev`)
-- **SSR (ui-ssr)**: No HMR — restart required after UI changes
+- **SSR (`bos dev --ssr`)**: source-composed SSR in the host dev process — manifests read from disk; restart not required
 - **Config changes**: Require host restart (`bos kill && bos dev`)
 
 ## Contract Sync & Type Generation
 
-Plugin types are auto-generated from `bos.config.json` via `bos types gen`:
+Plugin types are auto-generated from the authored config via `bos types gen`:
 
 ```bash
 bos types gen   # Regenerate ui/src/lib/api-types.gen.ts and api/src/lib/plugins-types.gen.ts
 ```
 
 **When it auto-runs:**
-- `bun install` (postinstall hook)
-- `bun typecheck`
+- `pnpm run typecheck`
 - `bos dev` startup
 - `bos build`, `bos deploy`, `bos publish`
 - `bos pluginAdd` / `bos pluginRemove`
@@ -90,15 +97,15 @@ bos types gen   # Regenerate ui/src/lib/api-types.gen.ts and api/src/lib/plugins
 2. Remote URL → fetches contract types from the deployed plugin's manifest
 3. Missing local path with no URL → skipped with a warning
 
-**Source of truth:** `bos.config.json`. If a plugin is listed there, its routes appear on `ApiContract`. If removed, TypeScript catches stale usage.
+**Source of truth:** the authored config (`bos.app.ts`). If a plugin is listed there, its routes appear on `ApiContract`. If removed, TypeScript catches stale usage.
 
-**After hand-editing `bos.config.json`:** Run `bos types gen` or restart `bos dev` to pick up changes.
+**After hand-editing the authored config:** Run `bos types gen` or restart `bos dev` to pick up changes.
 
 ## Runtime Config Loading
 
-The host reads `BOS_RUNTIME_CONFIG` at startup (resolved from `bos.config.json` by the CLI). `ConfigService` is an immutable Effect Layer — every service is built from that one snapshot.
+The host reads `BOS_RUNTIME_CONFIG` at startup (resolved from the authored config by the CLI). `ConfigService` is an immutable Effect Layer — every service is built from that one snapshot.
 
-**Override for testing**: Set `BOS_RUNTIME_CONFIG` env var to a JSON string or file path to bypass config loading from disk. Useful for testing with different configs without modifying `bos.config.json`.
+**Override for testing**: Set `BOS_RUNTIME_CONFIG` env var to a JSON string or file path to bypass config loading from disk. Useful for testing with different configs without modifying the authored config.
 
 On page refresh:
 1. Browser re-fetches HTML shell from host
@@ -111,9 +118,9 @@ This means a new deployment requires a host restart to pick up new URLs.
 
 `bos dev` and `bos build` write the fully-merged config to `.bos/bos.resolved-config.json` (gitignored). This file includes `_resolved` metadata with env, timestamp, and extends chain.
 
-**`bos.config.json` is NOT modified during dev.** Only `bos publish --deploy`, `bos plugin publish/add/remove`, and `bos sync` write to `bos.config.json`.
+**The authored config is NOT modified during dev.** Only `bos publish --deploy`, `bos plugin publish/add/remove`, and `bos sync` write to it (`bos.app.ts` for TS-form projects; legacy JSON children keep their `bos.config.json`).
 
-Build configs (rsbuild/rspack) read from `.bos/bos.resolved-config.json` first, falling back to `bos.config.json`. This allows slim child configs with `extends` to work correctly — the merged parent+child config is what the build sees.
+Build configs (rsbuild/rspack) read from `.bos/bos.resolved-config.json` first, falling back to the authored config. This allows slim child configs with `extends` to work correctly — the merged parent+child config is what the build sees.
 
 ## Debugging
 
@@ -156,15 +163,14 @@ bos dev                                # Start fresh
 ### UI not loading
 
 1. Check browser console for Module Federation errors
-2. `bos.config.json` — is `app.ui.development` correct?
+2. The authored config — is `app.ui.development` correct?
 3. Clear browser cache and hard reload (Cmd+Shift+R)
-4. Verify UI SSR restart if using SSR
 
 ### Module Federation errors
 
 - Verify shared dependency versions match across package.json files
 - Clear browser cache (Cmd+Shift+R)
-- Check `bos.config.json` URLs are accessible
+- Check the config URLs (authored config / FastKV) are accessible
 
 ## Production Mode
 
@@ -192,3 +198,21 @@ planned `bos dev --workspaces` orchestrator), `ports`, optional `budget`, `start
 orchestrator owns registry entries.
 
 Process tracking uses `~/.cache/everything-dev/pids.json` (global, atomic writes).
+
+## The tasks you will actually be given
+
+**"Start dev on my own ports."** `bos dev --port 3100` (api 3101, auth 3102, ui 3103, plugins 3110+ derive from the base). Explicit `--*-port` flags are pinned and persisted; derived ones are not.
+
+**"My change didn't show up."** Match the change type to the reload path: UI and API hot-reload instantly; auth/plugins/config changes need `bos kill && bos dev`; stale generated types need `pnpm run typecheck`.
+
+**"API is down."** `bos ps` → read `.bos/logs/api.log` → `curl http://localhost:3001/remoteEntry.js` — in that order.
+
+## What comes back when it fails
+
+| word | do |
+|---|---|
+| `Infra preflight failed: …` | the DB preflight probes localhost ports and auto-runs `docker compose up -d --wait` when every failure is a down local service — if it still fails, start Postgres (`pnpm run dev:postgres`) and read the failure messages |
+| `PortAllocationError` on an explicit port | the pinned port is occupied and allocation fails loudly — free it or pick another; it never silently moves an explicit choice |
+| `+100` port-shift notice at startup | expected drift: the preferred block was busy, holders are named in the notice, nothing is persisted — restarts re-try the preferred base |
+| service stuck in `starting` | probe its readiness path directly (e.g. `curl http://localhost:3003/remoteEntry.js`) and read `.bos/logs/<service>.log` |
+| stale registry entries blocking restart | `bos ps` / `bos kill` prune dead PIDs on read; to wipe manually: `rm ~/.cache/everything-dev/pids.json` |

package/skills/extends-config/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: extends-config
-description: How bos.config.json extends chains work, deep merge semantics, resolved config lifecycle, env-specific extends, and canonical field ordering. Use when debugging extends inheritance, configuring per-environment parents, understanding what dev writes vs publish writes, or reasoning about config merging.
+description: How the authored config's extends chains work (bos.app.ts preferred; legacy bos.config.json supported), deep merge semantics, resolved config lifecycle, env-specific extends, and canonical field ordering. Use when debugging extends inheritance, configuring per-environment parents, understanding what dev writes vs publish writes, or reasoning about config merging.
 metadata:
   sources: "packages/everything-dev/src/merge.ts,packages/everything-dev/src/config.ts,packages/everything-dev/src/shared-deps.ts,packages/everything-dev/src/types.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`.
+
 # extends & Config Merging
 
 ## extends Field
 
-The `extends` field in `bos.config.json` specifies a parent config to inherit from. Supports two forms:
+The `extends` field in the authored config (`bos.app.ts`, or legacy `bos.config.json`) specifies a parent config to inherit from. Supports two forms:
 
 ### String (all environments use same parent)
 ```json
@@ -73,13 +75,7 @@ Use this mental model:
 - `domain` is the public ingress for this runtime
 - a runtime can be a child in lineage and still become a new tenant root on its own domain
 
-With host env like:
-
-```bash
-ALLOW_OVERRIDE=ui,plugins.*
-TENANT_WHITELIST=pizza.pingpayio.near
-ALLOW_UNTRUSTED_SSR=false
-```
+Tenant permissions come from the DB, not env vars. The host fetches the tenant bindings map from the API's `GET /tenants/bindings` endpoint (cached for 30s), and the tenant record's allow flags gate what may be overridden and whether SSR is permitted.
 
 Design target for request mapping:
 - `pizza.com` -> base runtime `bos://pizza.pingpayio.near/pizza.com`
@@ -101,9 +97,8 @@ The tenant config must extend the base BOS runtime. Tenant API/auth overrides an
 ### SSR behavior
 
 Tenant SSR is gated separately from inheritance:
-- if `ALLOW_UNTRUSTED_SSR=true`, any valid tenant with SSR config may SSR
-- otherwise the tenant account must be listed in `TENANT_WHITELIST`
-- non-whitelisted tenants fall back to client rendering
+- a tenant may SSR only when its record has `allow_ssr` set
+- tenants without `allow_ssr` fall back to client rendering
 
 ## Resolved Config: `.bos/bos.resolved-config.json`
 
@@ -113,7 +108,7 @@ Tenant SSR is gated separately from inheritance:
 When `bos dev` or `bos build` runs:
 1. The full extends chain is resolved in memory
 2. The merged config is written to `.bos/bos.resolved-config.json`
-3. **`bos.config.json` is NOT modified** during dev
+3. **The authored config is NOT modified** during dev
 
 Structure:
 ```json
@@ -132,13 +127,13 @@ Structure:
 
 ### Build configs read resolved config first
 
-All build configs (ui/rsbuild.config.ts, host/rsbuild.config.ts, api/rspack.config.js, plugins/*/rspack.config.js) try `.bos/bos.resolved-config.json` first, falling back to `bos.config.json`.
+All build configs (ui/rsbuild.config.ts, host/rsbuild.config.ts, api/rspack.config.js, plugins/*/rspack.config.js) try `.bos/bos.resolved-config.json` first, falling back to the authored config.
 
 The `_resolved` metadata is stripped before use.
 
-### When bos.config.json IS written
+### When the authored config IS written
 
-| Command | Writes bos.config.json? | Why |
+| Command | Writes the authored config? | Why |
 |---------|------------------------|-----|
 | `bos dev` | No | Uses resolved config |
 | `bos build` | No | Uses resolved config |
@@ -149,7 +144,7 @@ The `_resolved` metadata is stripped before use.
 
 ### Remote host mode (bos->catalog)
 
-When host is remote, `syncResolvedSharedDeps()` reads versions from `bos.config.json` and writes them into `package.json` catalog. No resolved config is written — the remote host reads `bos.config.json` directly.
+When host is remote, `syncResolvedSharedDeps()` reads versions from the authored config and writes them into `package.json` catalog. No resolved config is written — the remote host reads the published config directly.
 
 ### `_resolved.resolvedAt`
 
@@ -184,8 +179,8 @@ Unknown keys go after known keys. `rebuildOrderedConfig()` is applied before eve
 From `packages/everything-dev/src/config.ts`:
 - `writeResolvedConfig(configDir, config, env, extendsChain?)` — writes `.bos/bos.resolved-config.json`
 - `loadResolvedConfig(configDir)` — reads resolved config, returns `BosConfig | null`
-- `resolveBosConfigPath(configDir)` — returns resolved config path if exists, else `bos.config.json`
-- `readBosConfigForBuild(configDir)` — reads resolved config stripping `_resolved`, falls back to `bos.config.json`
+- `resolveBosConfigPath(configDir)` — returns resolved config path if exists, else the authored config
+- `readBosConfigForBuild(configDir)` — reads resolved config stripping `_resolved`, falls back to the authored config
 
 From `packages/everything-dev/src/merge.ts`:
 - `mergeBosConfigWithExtends(parent, child)` — deep merge for extends chain
@@ -193,3 +188,20 @@ From `packages/everything-dev/src/merge.ts`:
 - `resolveExtendsRef(extendsField, env)` — resolve string|object extends for a given env
 - `rebuildOrderedConfig(config)` — enforce canonical ordering
 - `BOS_CONFIG_ORDER` — ordered field names
+
+## The tasks you will actually be given
+
+**"Remove a plugin I inherited."** Set it to `null` in the authored config's `plugins` — the null sentinel deletes it from the merged result. Deleting the entry entirely just inherits the parent's.
+
+**"Different parent for staging."** Object-form `extends` keyed by env (`development` / `staging` / `production`); the fallback chain is requested env → `production` → first defined value.
+
+**"Why doesn't the runtime see my config edit?"** Dev reads `.bos/bos.resolved-config.json` (regenerated on every `bos dev`); production reads FastKV. The authored config is only the publish input — `bos publish` is the write.
+
+## What comes back when it refuses
+
+| word | do |
+|---|---|
+| `CircularExtendsError` — "Circular extends detected: A -> B -> A" | stop — the extends chain loops; restructure so no runtime extends itself transitively |
+| `Circular dependency detected among: … dependsOn` | build-order cycle in the build train — fix the `dependsOn` declarations in the authored config |
+| inherited plugin still present after "removing" it | deep merge keeps parent plugins unless nulled — you need the explicit `null` sentinel, keyed exactly as the parent's plugin key |
+| your section is missing from `.bos/bos.resolved-config.json` | ordering never drops keys — if it's absent, the authored config or its parent didn't define it; check the `extends` chain with `bos config --full` |

package/skills/init-upgrade/SKILL.md

@@ -2,9 +2,11 @@
 name: init-upgrade
 description: bos init, bos sync, and bos upgrade workflows — template download, snapshot-based conflict detection, package version bumps, and how init/sync select and own files. Use when scaffolding new projects, syncing upstream changes, or upgrading framework packages.
 metadata:
-  sources: "packages/everything-dev/src/cli/init.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/cli/snapshot.ts,packages/everything-dev/src/merge.ts"
+  sources: "packages/everything-dev/src/cli/init.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/cli/snapshot.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/merge.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`.
+
 # bos init, sync, upgrade
 
 ## bos init
@@ -25,7 +27,7 @@ bos init --overrides ui,api,host                          # Include host locally
 5. `personalizeConfig()` — sets `extends`, `account`, `domain`, removes production URLs
 6. `resolveWorkspaceRefs()` — normalizes each workspace `package.json`: rewrites `file:`/`workspace:*` refs to `catalog:`, ensures all workspace packages are listed in root `workspaces.catalog`, pins framework versions (`everything-dev`, `every-plugin`)
 7. Write initial snapshot (`.bos/sync-snapshot.json`) — records file path → content hash for all template-origin files, used later by `bos sync` for conflict detection
-8. `bun install` + `bos types gen`
+8. `pnpm install` + `bos types gen`
 
 ## Shared Host + Custom Child App
 
@@ -43,7 +45,7 @@ This base runtime is the app the host boots from.
 
 ### 2. Create the child app from the base runtime
 
-Create a second app whose `bos.config.json` extends the base runtime:
+Create a second app whose authored config extends the base runtime:
 
 ```json
 {
@@ -81,15 +83,9 @@ Child apps can either run as their own base runtime on their own domain, or as r
 
 Shared-host children must extend the base runtime and do not introduce new server-side plugin IDs dynamically.
 
-### 4. Host deployment env for shared-host mode
+### 4. Host resolution for shared-host mode
 
-The shared host uses these env vars to resolve descendant requests:
-
-```bash
-ALLOW_OVERRIDE=ui,plugins.*
-TENANT_WHITELIST=pizza.pingpayio.near,chicago.pizza.pingpayio.near
-ALLOW_UNTRUSTED_SSR=false
-```
+The shared host resolves descendant requests via a DB-backed binding map. It fetches tenant permissions from the API's `GET /tenants/bindings` endpoint (cached for 30s) — no env vars are needed:
 
 Design target, for example:
 - `pingpay.io` -> base runtime `bos://pingpayio.near/pingpay.io`
@@ -105,7 +101,7 @@ Use the `extends-config` skill when reasoning about how the tenant config merges
 ### Init File Selection
 
 `buildInitPatterns(overrides, plugins)` chooses what init copies from the template source:
-- Scaffold runtime files (bos.config.json, package.json, biome.json, rsbuild configs)
+- Scaffold runtime files (bos.app.ts, bos.dev.ts, package.json, biome.json, rsbuild configs)
 - UI structure (routes/__root.tsx, components/index.ts, providers, hooks, lib)
 - API structure (contract.ts, index.ts, db/, drizzle.config.ts)
 - Selected plugin workspaces (`plugins/<selected-plugin>/**`)
@@ -152,7 +148,7 @@ Framework-owned files (from `FRAMEWORK_OWNED_SYNC_FILES`) are always updated whe
 ### What gets synced
 
 From parent template → local:
-- `app.*.production` — Zephyr URLs
+- `app.*.production` — bundle URLs
 - `app.api.shared`, `app.auth.shared`, `plugins.*.shared` — dependency versions
 - Framework-owned files (rsbuild configs, routers, etc.)
 
@@ -177,7 +173,7 @@ bos upgrade --dry-run    # Preview without making changes
 1. Check npm registry for latest versions of `everything-dev` and `every-plugin`
 2. Update root `package.json` workspaces.catalog
 3. Update all workspace `package.json` to use `catalog:` references
-4. `bun install` + `bos types gen`
+4. `pnpm install` + `bos types gen`
 5. Run `bos sync` to pull template updates matching new version
 6. Rewrite legacy UI imports (e.g., `from "@/auth"` → `from "@/app"`)
 7. Remove obsolete files
@@ -195,11 +191,28 @@ bos publish                  # Publish config to FastKV
 bos publish --deploy         # Build, deploy to CDN, then publish
 ```
 
-`bos publish --deploy` builds, deploys to Zephyr, auto-updates `bos.config.json` with production URLs + integrity hashes, then publishes the config to FastKV.
+`bos publish --deploy` builds, pins deterministic bundle URLs into the published config, then publishes to FastKV (a legacy JSON child's `bos.config.json` is also updated locally).
 
 ## Canonical Ordering
 
-All writes to `bos.config.json` enforce `BOS_CONFIG_ORDER`:
+All writes to the authored config enforce `BOS_CONFIG_ORDER`:
 `extends` → `account` → `domain` → `title` → `description` → `testnet` → `staging` → `repository` → `ci` → `app` → `plugins`
 
 Unknown keys go after known keys. See `everything-dev#extends-config` for full ordering details.
+
+## The tasks you will actually be given
+
+**"Scaffold a child that extends the base runtime."** `bos init --extends bos://<parent-account>/<gateway> --account <you>.near --domain <your.domain> --no-interactive`, then customize `account` / `domain` / `app.ui` in the authored config; init's tail runs `pnpm install` + `bos types gen` (unless `--no-install`).
+
+**"Sync reports conflicted files."** Your local edits diverged from the snapshot; upgrade applies the template version and leaves your copy in `.bos/sync-backup/` — diff and merge back, or `bos sync --force` deliberately.
+
+**"Upgrade framework packages."** `bos upgrade --dry-run` first, then `bos upgrade` — it bumps the root catalog, rewrites workspace refs to `catalog:`, syncs the template, and rewrites legacy imports.
+
+## What comes back when it refuses
+
+| word | do |
+|---|---|
+| file listed as `conflicted` in sync results | local file modified since the snapshot AND the template changed — take the template version (your copy is backed up at `.bos/sync-backup/`) or re-apply your change on top |
+| sync keeps skipping my file | app-owned files that diverged from the snapshot are skipped without `--force`; framework-owned files always update when the template changes |
+| `Circular extends detected while resolving upgrade source` | the upgrade source's extends chain loops — resolve from a non-cyclic parent |
+| init copies fewer files than expected | `buildInitPatterns` filters to the selected plugins + their routes; pass `--overrides ui,api,host` to widen the scaffold |