everything-dev 1.28.5 → 1.28.7

package/skills/init-upgrade/SKILL.md

@@ -27,6 +27,71 @@ bos init --overrides ui,api,host                          # Include host locally
 7. Write initial snapshot (`.bos/sync-snapshot.json`)
 8. `bun install` + `bos types gen`
 
+## Shared Host + Custom Tenant App
+
+Use this pattern when you want one deployed host runtime and separate tenant apps that inherit from it.
+
+### 1. Create the base host runtime
+
+Create the app that owns the shared host, auth, API, and base plugin list:
+
+```bash
+bos init --overrides ui,api,host
+```
+
+This base runtime is the app the host boots from.
+
+### 2. Create the tenant app from the base runtime
+
+Create a second app whose `bos.config.json` extends the base runtime:
+
+```json
+{
+  "extends": "bos://linktree.near/linktree.com",
+  "account": "alice.near",
+  "domain": "linktree.com"
+}
+```
+
+Then customize the tenant-owned sections, usually:
+- `account`
+- `repository`
+- `app.ui`
+- existing `plugins.<id>.ui`
+- existing `plugins.<id>.sidebar`
+
+### 3. Understand fixed-core tenant mode
+
+Today the shared host stays fixed to the base runtime for:
+- `app.host`
+- `app.api`
+- `app.auth`
+- server-side plugin loading
+
+Tenant apps are request-scoped overlays on top of that base host. In fixed-core mode, the supported tenant overrides are:
+- `app.ui`
+- existing `plugins.<id>.ui`
+- existing `plugins.<id>.sidebar`
+
+Tenant apps must extend the base runtime and do not introduce new server-side plugin IDs dynamically.
+
+### 4. Host deployment env for tenant mode
+
+The shared host uses these env vars to resolve tenant requests:
+
+```bash
+NETWORK_ID=mainnet
+ALLOW_OVERRIDE=ui,plugins.*
+TENANT_WHITELIST=alice.near,bob.near
+ALLOW_UNTRUSTED_SSR=false
+```
+
+Subdomains resolve by convention, for example:
+- `linktree.com` -> base runtime
+- `alice.linktree.com` -> `bos://alice.near/linktree.com`
+
+Use the `extends-config` skill when reasoning about how the tenant config merges with the base runtime.
+
 ### Init File Selection
 
 `buildInitPatterns(overrides, plugins)` chooses what init copies from the template source:

package/skills/super-app/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: super-app
+description: Build shared-host, shared-API super apps with tenant-specific UI composition. Use when setting up a base runtime plus custom tenant apps, configuring fixed-core multi-tenancy, or reasoning about what tenants can override today.
+metadata:
+  sources: "host/src/services/tenant-runtime.ts,host/src/program.ts,host/src/services/federation.server.ts,packages/everything-dev/src/config.ts"
+---
+
+# Super Apps
+
+Use this skill for the shared-host pattern where one runtime owns the host, auth, API, and base plugin set, while many tenant apps extend that runtime and swap UI-facing pieces per request.
+
+## Mental Model
+
+- The base runtime is the server core and trust boundary.
+- Tenant apps are published BOS configs that extend the base runtime.
+- The host resolves the tenant config from the request hostname.
+- In fixed-core mode, the host, auth, API, and server-side plugins stay fixed to the base runtime.
+- Tenant-specific UI composition is applied per request.
+
+Example mapping:
+- `linktree.com` -> base runtime `bos://linktree.near/linktree.com`
+- `alice.linktree.com` -> tenant runtime `bos://alice.near/linktree.com`
+
+## What Works Today
+
+Supported tenant overrides in fixed-core mode:
+- `app.ui`
+- existing `plugins.<id>.ui`
+- existing `plugins.<id>.sidebar`
+
+Still fixed to the base runtime:
+- `app.host`
+- `app.api`
+- `app.auth`
+- server-side plugin loading and router mounting
+
+Not part of this mode:
+- tenant-specific API overrides
+- tenant-specific auth overrides
+- introducing new plugin IDs dynamically per tenant
+- full per-request host/plugin/auth/api hot swap
+
+## Setup Flow
+
+### 1. Create the base runtime
+
+The base runtime owns the shared host and API surface:
+
+```bash
+bos init --overrides ui,api,host
+```
+
+This app is the one you deploy as the shared host.
+
+### 2. Publish the base runtime
+
+The base runtime must be published before tenants can extend it:
+
+```bash
+bos publish --deploy
+```
+
+### 3. Create a tenant app that extends the base runtime
+
+Tenant `bos.config.json`:
+
+```json
+{
+  "extends": "bos://linktree.near/linktree.com",
+  "account": "alice.near",
+  "domain": "linktree.com",
+  "repository": "https://github.com/example/alice-app",
+  "app": {
+    "ui": {
+      "name": "ui",
+      "development": "local:ui",
+      "production": "https://cdn.example.com/alice-ui",
+      "integrity": "sha384-..."
+    }
+  }
+}
+```
+
+You can also override existing plugin UIs and sidebar entries for tenant-specific navigation.
+
+## Host Env For Tenant Mode
+
+The shared host uses these env vars to resolve tenants:
+
+```bash
+NETWORK_ID=mainnet
+ALLOW_OVERRIDE=ui,plugins.*
+TENANT_WHITELIST=alice.near,bob.near
+ALLOW_UNTRUSTED_SSR=false
+```
+
+Meaning:
+- `NETWORK_ID` controls whether subdomains resolve to `.near` or `.testnet`
+- `ALLOW_OVERRIDE` controls which tenant config sections can affect request-scoped composition
+- `TENANT_WHITELIST` controls which tenants may use SSR
+- `ALLOW_UNTRUSTED_SSR=true` allows SSR for any valid tenant with SSR config
+
+## Resolution Rules
+
+Tenant resolution is convention-based:
+- bare domain serves the base runtime
+- a single subdomain label resolves to a tenant account
+- nested labels are rejected in tenant mode
+
+The tenant config must:
+- exist in FastKV
+- extend the base runtime
+- resolve to the expected tenant account
+- provide integrity for overridden remote UIs
+
+## Security Model
+
+- Tenant UI overrides are integrity-checked before trust is established.
+- Integrity verification uses bounded streaming, not full-response buffering.
+- Asset requests use stale-while-revalidate verification to avoid latency spikes.
+- HTML and SSR requests use blocking verification.
+- SSR module cache identity includes `ssrIntegrity`, not just the SSR URL.
+
+## Recommended Workflow
+
+For the base runtime:
+
+```bash
+bos dev --host remote
+bos publish --deploy
+```
+
+For a tenant UI app:
+
+```bash
+bos dev --host remote --api remote
+bos publish --deploy
+```
+
+After publishing config changes that affect the base host runtime, restart the host process so it reloads the latest base config snapshot.
+
+## When To Load Other Skills
+
+- Use `everything-dev#init-upgrade` for scaffold/sync/upgrade mechanics.
+- Use `everything-dev#extends-config` for deep-merge and resolved-config semantics.
+- Use `everything-dev#publish-sync` for publish and deploy steps.
+- Use this `super-app` skill when the question is specifically about the shared-host, shared-API multi-tenant architecture.