minutework 0.1.53 → 0.1.55

package/README.md

@@ -147,7 +147,7 @@ minutework deploy --preview
 
 Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `minutework dev` or `minutework test`. Sidecar-only scaffolds have no root `package.json`; install Python deps once inside `sidecar/` before running local sidecar workflows.
 
-For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface. To keep `@minutework/web-auth` same-origin on a bring-your-own host, set `MW_GATEWAY_BASE_URL` to the platform gateway base URL — the template's `next.config.mjs` then proxies `/_mw/*` to the gateway — and run `minutework deploy --live --host <your-domain>` so the gateway recognizes that host as your tenant's live canonical customer-web origin.
+For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface. To keep `@minutework/web-auth` same-origin on a bring-your-own host, set `MW_GATEWAY_BASE_URL` to the canonical live customer-web host returned by `minutework deploy --live` — the template's `next.config.mjs` then proxies `/_mw/*` to the gateway — and run `minutework deploy --live --host <your-domain>` so the gateway recognizes that host as your tenant's live canonical customer-web origin. For local auth against dev, target `https://dev.minutework.ai`, deploy live there, then set `MW_GATEWAY_BASE_URL` to the returned `https://<label>.customers.dev.minutework.ai` host, not bare `https://dev.minutework.ai`.
 
 `link` provisions or resolves the default published-site property for the active tenant and stores that property key in repo-local state. The SDK-based `tenant-app/.env.example` contains only the app metadata contract used by the template: `NEXT_PUBLIC_MW_APP_ID`, `MW_TEMPLATE_APP_NAME`, and optional `MW_PUBLIC_BASE_URL`. Browser auth and manifest calls use same-origin `/_mw` routes through `@minutework/web-auth`; do not add platform content tokens or public-site property vars to the tenant app.
 

package/assets/claude-local/preambles/vuilder.md

@@ -21,6 +21,13 @@ published app pack installed, and use it through the branded `vuilder-shell`.
 The Vuilder owns and resells this product; their customers each run an isolated
 tenant.
 
+That signup=auto-spawn path is **Mode A**. Some Vuilders are **Mode B**: they run
+a shared hosted broker/demo on their own operator runtime that customers join via
+`/_mw` and use first, then provision their OWN runtime later as an opt-in step.
+Decide Mode A vs Mode B early — `skills/vuilder-workspace-architecture/SKILL.md`
+leads with that choice and routes Mode B to
+`skills/vuilder-mode-b-hosted-and-spawn/SKILL.md`.
+
 `tenant-app`, `sidecar`, and `mobile` starters are **not** enabled in this
 workspace unless `minutework.config.ts` says otherwise — do not assume those
 surfaces exist. The generic builder guidance below still governs how you write

package/assets/claude-local/skills/README.md

@@ -53,6 +53,7 @@ Generated-workspace-first guidance should live here, especially:
 - `generated-workspace-architecture/SKILL.md`
 - `vuilder-workspace-architecture/SKILL.md`
 - `vuilder-public-site-authoring/SKILL.md`
+- `vuilder-mode-b-hosted-and-spawn/SKILL.md`
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`

package/assets/claude-local/skills/tenant-app-customer-auth-deploy/SKILL.md

@@ -55,6 +55,14 @@ unattended; without `--yes` it returns `confirmation_required`).
   activate. On a BYO host, set `MW_GATEWAY_BASE_URL` in the tenant-app so the
   template's `next.config.mjs` proxies same-origin `/_mw/*` to the gateway
   (managed-subdomain hosts are gateway-fronted and need no rewrite).
+- **Local tenant-app against the dev platform:** target the dev platform
+  explicitly (`export MW_CLI_PLATFORM_BASE_URL=https://dev.minutework.ai` and
+  `minutework login --platform https://dev.minutework.ai`), link a sandbox
+  runtime, then run `minutework deploy --live`. Set `tenant-app/.env.local`
+  `MW_GATEWAY_BASE_URL` to the returned canonical live customer-web host such as
+  `https://<label>.customers.dev.minutework.ai` before running local `next dev`.
+  Do not set it to bare `https://dev.minutework.ai`; the gateway resolves
+  `/_mw` customer auth by the live customer-web host.
 
 ## Boundaries and current limits
 

package/assets/claude-local/skills/vuilder-mode-b-hosted-and-spawn/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: vuilder-mode-b-hosted-and-spawn
+description: "Mode B Vuilder: run a hosted broker/demo on your operator runtime, let customers join via /_mw, and offer opt-in 'spawn my own runtime' later (configurable trigger). Use when customers try a hosted product before getting their own server."
+---
+
+# Vuilder Mode B: Hosted Broker/Demo + Opt-In Spawn
+
+Use this skill when a generated Vuilder workspace runs a **hosted product** on
+its own operator runtime that customers consume first, and only **later** do
+those customers provision their **own** runtime. Read
+`vuilder-workspace-architecture/SKILL.md` first; this skill specializes it.
+
+This skill is vertical-neutral. FleetRun and Ostronaut appear only as clearly
+marked illustrative examples — never as platform behavior to hardcode.
+
+## Mode A vs Mode B — decide which you are
+
+- **Mode A (signup = auto-spawn).** A customer signs up on the Vuilder public
+  site and the platform immediately provisions a fresh customer tenant runtime
+  and installs the app pack. This is the default flow in
+  `vuilder-workspace-architecture` (`customer_vertical_signup`). Pick Mode A
+  when every customer needs their own isolated runtime from day one.
+- **Mode B (hosted broker/demo, then opt-in spawn).** The Vuilder runs a shared
+  hosted product on its **operator runtime**. Customers **join the host
+  runtime** via `/_mw` customer auth and use the product there (a broker, a
+  demo, a shared workspace). Each customer provisions their **own** runtime
+  **later**, as an explicit opt-in step — keeping their identity and history.
+  Pick Mode B when customers should try value before committing to their own
+  server, or when their own runtime should appear only once a condition holds.
+
+> Illustrative only:
+> - *FleetRun* (insurance brokering): carriers sign up as customers of the
+>   host runtime and opt to spawn their own runtime when they are ready.
+> - *Ostronaut* (retail conversation intelligence): stores try a hosted demo
+>   and spawn their own runtime when real store data starts flowing.
+>
+> Both are instances of the same vertical-neutral shape; do not copy their
+> vocabulary into schemas, manifests, or services.
+
+If signup must always provision a runtime, you want Mode A — stop here and use
+`vuilder-workspace-architecture`.
+
+## Surface shape (follow the Starter Choice Matrix; shell-first)
+
+- **`tenant-app`** hosts marketing, native `/_mw` customer signup/login, and the
+  hosted product under `/app`. Browser customer auth uses `@minutework/web-auth`
+  against same-origin `/_mw/auth/*`; the principal is `tenant_customer`. `/_mw`
+  only resolves on a **live, canonical** customer-web host — go live with
+  `minutework deploy --live`. See `tenant-app-customer-auth-deploy/SKILL.md`.
+- **The hosted broker/demo runs on the Vuilder's operator runtime**, not in the
+  browser. `/app` consumes it through `mw.query` / `mw.action` against
+  `webCustomerExposed` query/action manifests (see `app-pack-authoring/SKILL.md`
+  and `generated-workspace-architecture/SKILL.md`). Browser intake is untrusted:
+  it never chooses package refs, runtime providers, tenant ids, or install
+  coordinates.
+- **`vuilder-shell`** remains the branded member/operator surface
+  (`/w/[workspace_slug]`) for the Vuilder's own operators and for customers once
+  they have their own runtime. See `shell-architecture/SKILL.md`. The hard
+  boundary still holds: the shell never owns identity, provisioning, or app-pack
+  install authority.
+
+## Shadow tenant + claim continuity
+
+A Mode B customer exists as identity **before** they have their own runtime:
+
+- When a visitor/customer first appears, Core resolves a **shadow tenant** and a
+  **shadow person** for their external identity (e.g. email). The shadow person
+  is a stable participation anchor, owned by the shadow tenant. See
+  `shadow-participation-and-guest-threads/SKILL.md`.
+- Joining the host runtime via `/_mw` creates a customer membership on the
+  **host** tenant. Claim refs tie that membership back to the customer's shadow
+  identity, so history is preserved across the later spawn.
+- The spawn is an **explicit claim/upgrade**, modeled as a real provisioning
+  step — never a silent mutation. The platform **promotes the customer's
+  existing tenant in place** rather than minting a fresh one, so there is no
+  duplicate identity and no orphaned history.
+
+Do not invent a parallel guest-account or per-customer identity model; reuse the
+external-identity → shadow tenant → shadow person → claim substrate.
+
+## The opt-in spawn action + configurable trigger
+
+Spawn is **product-driven, not hardcoded**. There are two ways to fire it; both
+target the same platform substrate (a `customer_runtime_spawn` onboarding intent
+that promotes the customer's tenant in place and installs the Vuilder's
+published app pack).
+
+### 1. Explicit opt-in action (available now)
+
+Wire a "create my own runtime" affordance in `/app` to the platform's customer
+spawn endpoint:
+
+- The authenticated customer (`tenant_customer` session) POSTs to
+  `/_mw/runtime/spawn` on the live host.
+- The platform gates on an **active, email-verified** customer membership,
+  resolves identity continuity, promotes the customer's tenant, and installs the
+  Vuilder's **published, attested** app pack. It is idempotent.
+- The browser only signals intent. It never picks the package, runtime provider,
+  or tenant — the platform derives those from the host Vuilder + the customer's
+  verified identity.
+
+This is the FleetRun-style "customer opts in" trigger *(illustrative)*.
+
+### 2. App-pack-declared condition (configurable trigger)
+
+To make spawn fire when a **product condition** holds rather than on a button
+press, declare the condition in the app pack instead of hardcoding it. Use the
+local event bus declaration surface (`event-bus/SKILL.md`): emit a
+product-defined event when the condition occurs, then declare an
+`eventSubscription` (with `filters`) whose target flow requests the spawn. Keep
+event types and field names vertical-neutral (they must pass `mw.E002`/`mw.E010`
+— no vertical role/identifier words).
+
+This is the Ostronaut-style "real data starts flowing" trigger *(illustrative)*:
+emit a generic "data received" event, filter for the threshold that means the
+customer is now operating for real, and let the subscription drive the spawn.
+
+> Honesty note: the **declaration surface** (events, subscriptions, filters)
+> ships today, and the **explicit opt-in action** above is fully executable. The
+> automatic condition→spawn leg is delivered by platform substrate that is still
+> being rolled out (a generic emit site, the flow→spawn dispatch, and the
+> local-event dispatch flag). Until that lands in the target runtime, fall back
+> to the explicit opt-in action and keep the declared condition as the
+> product's source of truth. Do not assume auto-fire works without confirming it
+> in `runtime-capability-inventory`.
+
+## Cross-runtime data continuity (scope honestly)
+
+After a customer spawns their own runtime, what carries over?
+
+- **Identity and shared references re-anchor via ontology Core URNs.** Promote
+  local facts to shared `core_urn`s and re-anchor them on the spawned runtime
+  via the reviewable promotion loop. See `ontology-authoring/SKILL.md` and
+  `runtime_ontology_contract.md`. This is the supported continuity primitive.
+- **The spawn does not zero-copy the customer's host-runtime records into the
+  new runtime.** Ad-hoc record-level cross-runtime references (pointer + grant,
+  read at resolve time) are **not executable today**: `runtime_federation`
+  implements dataset publication + change-signal pub/sub only, and the
+  `bridge_protocol.md` hydrate path is design/spec, not built. So **a spawned
+  runtime cannot reference a specific record on the host runtime yet.** See
+  `federation_model.md` and `bridge_protocol.md`.
+- **Therefore scope the product to: spawn starts fresh; shared identity
+  re-anchors via ontology URNs; deep history reference is a follow-on once the
+  federation record-reference primitive exists.** Do not promise zero-copy
+  history in product copy or design. If a Mode B product genuinely needs
+  record-level cross-runtime reads, report it as a capability gap
+  (`capability-gap-reporting/SKILL.md`) instead of inventing a copy-based
+  workaround.
+
+## Server-switcher across host + spawned runtime
+
+After spawn, the customer holds **two memberships**: the customer membership on
+the Vuilder's host runtime and the owner membership on their own spawned
+runtime. Give them a way to switch between the hosted product and their own
+runtime:
+
+- Model this as multi-membership switching in the branded shell
+  (`shell-architecture/SKILL.md`) — each membership opens its own
+  `/w/[workspace_slug]` context; the shell never mixes their sessions.
+- The host membership stays valid after spawn (it is the continuity ledger), so
+  the customer can keep using the shared hosted product and their own runtime
+  side by side.
+- Identity stays single across both via the shared shadow/claim anchor; do not
+  create a second identity for the spawned runtime.
+
+## Related Skills
+
+- `vuilder-workspace-architecture` — the base Vuilder shape and the Mode A
+  signup=auto-spawn flow this skill contrasts with.
+- `tenant-app-customer-auth-deploy` — make `/_mw` customer auth resolve on a
+  live canonical host.
+- `shadow-participation-and-guest-threads` — shadow tenant/person + claim
+  continuity for pre-runtime customers.
+- `app-pack-authoring` and `generated-workspace-architecture` — `webCustomerExposed`
+  query/action manifests consumed by `/app` via `mw.query` / `mw.action`.
+- `event-bus` (and `dataset-subscriber-flow`) — declarative event/subscription
+  surface for the configurable spawn trigger.
+- `ontology-authoring` and `runtime_ontology_contract.md` — Core URN promotion
+  for cross-runtime identity continuity.
+- `shell-architecture` — branded shell + multi-membership server switching.
+- `federation_model.md` and `bridge_protocol.md` — what cross-runtime
+  federation does and does not support today (record-reference is a gap).
+- `capability-gap-reporting` — report record-level cross-runtime read needs
+  rather than working around them.

package/assets/claude-local/skills/vuilder-workspace-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vuilder-workspace-architecture
-description: "First skill for generated Vuilder workspaces: vuilder-app public site, vuilder-shell branded customer shell, app-pack source, and customer signup/install flow."
+description: "First skill for generated Vuilder workspaces: vuilder-app public site, vuilder-shell branded customer shell, app-pack source, and the Mode A signup=auto-spawn flow. For hosted-demo-then-opt-in-spawn, see vuilder-mode-b-hosted-and-spawn."
 ---
 
 # Vuilder Workspace Architecture
@@ -9,6 +9,22 @@ Use this skill first when a generated workspace is a Vuilder workspace or when
 the request mentions Vuilder verticals, Vuilder public sites, branded tenant
 shells, customer vertical signup, or app-pack publishing for customer install.
 
+## Mode A vs Mode B — decide first
+
+A Vuilder ships in one of two shapes; decide which before designing the
+acquisition flow:
+
+- **Mode A (signup = auto-spawn).** Signing up on the public site immediately
+  provisions the customer their own tenant runtime and installs the app pack.
+  This is the default this skill describes (see the Flow section below).
+- **Mode B (hosted broker/demo, then opt-in spawn).** The Vuilder runs a shared
+  hosted product on its own operator runtime; customers join it via `/_mw` and
+  use it there, then provision their OWN runtime later as an opt-in step (with a
+  configurable trigger). If customers should try a hosted product before getting
+  their own server, it is Mode B — **read
+  `vuilder-mode-b-hosted-and-spawn/SKILL.md`** and follow it instead of the Mode
+  A flow below.
+
 ## Default Workspace Shape
 
 A first-class Vuilder workspace is vertical-neutral. FleetRun is an example
@@ -31,9 +47,10 @@ Expected generated layout:
   metadata under the workspace authoring layer.
 - Optional `sidecar/` and `mobile/` starters when selected.
 
-## Flow
+## Flow (Mode A)
 
-The acquisition and install path is:
+The Mode A acquisition and install path is (for Mode B, follow
+`vuilder-mode-b-hosted-and-spawn/SKILL.md` instead):
 
 1. Customer lands on the Vuilder public site (`vuilder-app`).
 2. The public-site BFF creates `customer_vertical_signup` using
@@ -76,3 +93,6 @@ billing policy, or install coordinates.
   marketplace publish output.
 - Use `generated-workspace-architecture` for general local workspace trust
   boundaries.
+- Use `vuilder-mode-b-hosted-and-spawn` when the Vuilder runs a hosted
+  broker/demo customers join first and lets them spawn their own runtime later
+  (Mode B), instead of the Mode A signup=auto-spawn flow above.

package/assets/templates/next-tenant-app/.env.example

@@ -1,7 +1,9 @@
 NEXT_PUBLIC_MW_APP_ID=tenant.app
 MW_TEMPLATE_APP_NAME=Tenant App
 MW_PUBLIC_BASE_URL=
-# Only needed when hosting this app off-platform (Vercel / custom domain). Set to the
-# MinuteWork platform gateway base URL to transparently proxy same-origin /_mw/* customer
-# auth to the gateway. Leave blank for managed-subdomain hosts (gateway-fronted).
+# Only needed when hosting this app off-platform (Vercel / custom domain) or
+# running local next dev against a live customer-web binding. Set this to the
+# canonical live customer-web host returned by `minutework deploy --live`, such as
+# https://<label>.customers.dev.minutework.ai. Do not set it to bare
+# https://dev.minutework.ai.
 MW_GATEWAY_BASE_URL=

package/assets/templates/next-tenant-app/README.md

@@ -64,6 +64,21 @@ runtime-command demo, or a server-only public-content token adapter.
   defaults to `tenant.app`
 - `MW_TEMPLATE_APP_NAME` controls the display name and defaults to `Tenant App`
 - `MW_PUBLIC_BASE_URL` is optional and only affects metadata routes
+- `MW_GATEWAY_BASE_URL` is only needed when the app is not directly
+  gateway-fronted. For local auth against dev, set it to the canonical live
+  customer-web host returned by `minutework deploy --live`, for example
+  `https://<label>.customers.dev.minutework.ai`. Do not set it to bare
+  `https://dev.minutework.ai`; `/_mw` auth is resolved from the live
+  customer-web host.
+
+Local real-auth dev loop:
+
+1. `export MW_CLI_PLATFORM_BASE_URL=https://dev.minutework.ai`
+2. `minutework login --platform https://dev.minutework.ai`
+3. `minutework link --runtime --sandbox`
+4. `minutework deploy --live`
+5. set `MW_GATEWAY_BASE_URL` to the returned `*.customers.dev.minutework.ai`
+   live host, then run local `next dev`.
 
 ## Validation
 

package/assets/templates/next-tenant-app/next.config.mjs

@@ -22,11 +22,11 @@ function resolveTurbopackRoot(startDirectory) {
 
 // Bring-your-own host support: when this tenant-app is hosted off-platform (Vercel
 // or a custom domain) instead of being fronted by the MinuteWork gateway, set
-// MW_GATEWAY_BASE_URL so same-origin `/_mw/*` customer-auth calls are transparently
-// proxied to the platform gateway. The gateway serves customer auth for this tenant's
-// live canonical customer-web host (provisioned via `minutework deploy --live`), so
-// @minutework/web-auth keeps its same-origin contract without a remote project URL.
-// Unset by default: managed-subdomain hosts are gateway-fronted and need no rewrite.
+// MW_GATEWAY_BASE_URL to the live canonical customer-web host returned by
+// `minutework deploy --live`. The gateway serves customer auth only for that
+// host, so local dev should point at e.g. https://<label>.customers.dev.minutework.ai,
+// not the bare platform origin. Unset by default: managed-subdomain hosts are
+// gateway-fronted and need no rewrite.
 const gatewayBaseUrl = (process.env.MW_GATEWAY_BASE_URL || "").trim().replace(/\/+$/, "");
 
 const nextConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutework",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "MinuteWork CLI for workspace scaffolding, local preview workflows, and hosted preview deploys.",
   "type": "module",
   "bin": {