minutework 0.1.39 → 0.1.41

package/EXTERNAL_ALPHA.md

@@ -19,6 +19,12 @@ The shipped `tenant-app` starter is the combined web surface: public routes at
 the root, a private `/app` workspace, and a MinuteWork-managed public-content
 path over the runtime-baseline `mw.core.site` contract.
 
+Vuilder authoring workspaces can scaffold `vuilder-app` plus `vuilder-shell`.
+`vuilder-app` is the public acquisition/onboarding site and `vuilder-shell` is
+the branded customer tenant shell. The customer signup path remains
+server-authoritative: central SSO and the platform `customer_vertical_signup`
+intent decide provisioning and app-pack install metadata.
+
 ### Developer-local broker lane
 
 Use `minutework session` when you want MinuteWork to assemble the workspace
@@ -103,10 +109,20 @@ React Native client that authenticates directly against the platform with the
 native session-token flow; it is distributed through EAS/App Store/Play Store
 instead of `minutework deploy`.
 
+For Vuilder verticals, scaffold both Vuilder starters:
+
+```bash
+npx minutework init my-vertical --starter vuilder-app --starter vuilder-shell
+```
+
+The Vuilder shell can customize tenant UX and routes such as
+`/w/[workspace_slug]` and `/w/[workspace_slug]/connect`; it does not own central
+identity, runtime provisioning, app-pack install authority, or billing policy.
+
 Anything outside these lanes remains deferred, including `--live`,
 runtime-backed deploy targets, and additional local coding engines.
 
-If you run `minutework init` **without** `--starter` in an interactive terminal, the CLI prompts for tenant-app, sidecar, mobile, common combinations, or base-only. In CI or scripts, use `--starter` or set `MW_CLI_NONINTERACTIVE=1` to skip the prompt (base-only scaffold).
+If you run `minutework init` **without** `--starter` in an interactive terminal, the CLI prompts for tenant-app, Vuilder app/shell, sidecar, mobile, common combinations, or base-only. In CI or scripts, use `--starter` or set `MW_CLI_NONINTERACTIVE=1` to skip the prompt (base-only scaffold).
 
 ## What `link` does
 

package/README.md

@@ -8,7 +8,10 @@ The npm package and primary command are `minutework`. The `pandawork` command re
 
 The current external alpha is intentionally narrow:
 
-- Starters: `tenant-app` (the deployable web surface), `sidecar` (local/internal runtime surface), and `mobile` (init-only native client)
+- Starters: `tenant-app` (combined public/private web surface), `vuilder-app`
+  plus `vuilder-shell` (Vuilder public site plus branded customer shell),
+  `sidecar` (local/internal runtime surface), and `mobile` (init-only native
+  client)
 - Developer-local broker surface: `minutework session start|resume|status`
 - Hosted release class: `ssr_container`
 - Deploy surface: `minutework deploy --preview`
@@ -22,6 +25,12 @@ The shipped `tenant-app` starter is the combined web surface: public routes at
 the root plus a private `/app` workspace. Public-site content follows the
 MinuteWork-managed `mw.core.site` baseline and published-snapshot flow.
 
+For Vuilder verticals, scaffold `vuilder-app` and `vuilder-shell` together.
+`vuilder-app` is the public landing/blog/onboarding site; `vuilder-shell` is the
+branded customer tenant shell opened after central SSO and platform-owned
+`customer_vertical_signup` completion. Browser intake never chooses package
+refs, manifest refs, runtime provider, billing policy, or provisioning kind.
+
 The CLI fails closed when the backend cannot provide typed release metadata, deploy status, receipts, activation state, or rollback state. It does not claim a successful deploy when the provider substrate is unavailable.
 
 ## Install
@@ -65,6 +74,17 @@ keychain), not the `tenant-app` BFF cookie path. There is no `link`/`deploy`
 lane for it — distribution is your own EAS pipeline (`eas build`/`eas submit`,
 EAS Update), not `minutework deploy`.
 
+For a first-class Vuilder workspace, scaffold both web starters:
+
+```bash
+npx minutework init fleet-template --starter vuilder-app --starter vuilder-shell
+```
+
+The Vuilder public site redirects onboarding into central SSO. The approved
+app-pack marketplace coordinate is emitted by `minutework publish` and consumed
+by the platform customer-signup intent; the Vuilder shell customizes tenant UX,
+not platform identity/provisioning authority.
+
 ### Developer-local broker lane
 
 Use this lane when you want MinuteWork to assemble a bounded workspace context,

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

@@ -15,6 +15,8 @@ receive:
 
 - Builder should compose shared substrate before generating bespoke tenant code
 - `tenant-app` is the combined public plus private web starter
+- `vuilder-app` plus `vuilder-shell` are the default first-class Vuilder
+  workspace web starters around app-pack source
 - `tenant-app` auth/data uses `@minutework/web-auth` and thin `src/mw/`
   substrate, not per-app auth/gateway BFF routes
 - `tenant-app` uses cookie-backed `signUp` / `signInWithPassword` aliases and
@@ -25,6 +27,8 @@ receive:
 - tenant public authoring is runtime/CMS-backed through `mw.core.site`
 - Vuilder-owned public sites use `vuilder-public-site` and public-dj CMS
   manifests
+- Vuilder workspace tasks should load `vuilder-workspace-architecture` before
+  the public-site, shell, or app-pack task skill
 - anonymous live delivery should prefer published snapshots
 - AI drafting/generation should reuse existing runtime AI capability before new
   model/provider integrations
@@ -43,10 +47,12 @@ Generated-workspace-first guidance should live here, especially:
 
 - `project-overview-and-strategy/SKILL.md`
 - `generated-workspace-architecture/SKILL.md`
+- `vuilder-workspace-architecture/SKILL.md`
 - `vuilder-public-site-authoring/SKILL.md`
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`
+- `integration-broker-and-connectors/SKILL.md`
 - `layering-and-import-modes/SKILL.md`
 - `standalone-mobile-client/SKILL.md`
 - `capability-gap-reporting/SKILL.md`

package/assets/claude-local/skills/ai-capability-defaults/SKILL.md

@@ -14,6 +14,9 @@ generation, itinerary generation, content generation, or structured-output UX.
 - `tenant-app` should gather inputs, invoke typed platform/runtime surfaces, and
   display or edit outputs; do not embed provider credentials or direct
   browser-to-model calls in the web app for MVP.
+- When AI agents need to drive external providers such as ads, also read
+  `integration-broker-and-connectors/SKILL.md` and use the governed connector
+  capability instead of browser or sidecar provider calls.
 - Do not create a bespoke `sidecar` for drafting/generation unless the existing
   runtime AI capability has a concrete gap or there is another backend-only
   requirement.

package/assets/claude-local/skills/app-pack-authoring/SKILL.md

@@ -10,6 +10,21 @@ An `app pack` is the shipped product unit.
 - Compose shared MinuteWork substrate first: baseline capabilities, runtime
   primitives, reviewed capability skills, app packs, overlays, and hosted
   publication flows.
+- In a Vuilder workspace, app-pack source is the reusable vertical product that
+  customer runtimes receive after `customer_vertical_signup`. The public
+  `vuilder-app` and branded `vuilder-shell` are web surfaces around that pack;
+  they are not substitutes for the installable app-pack contract.
+- `vuilder-shell` is a platform member shell reached after central SSO and
+  app-pack install gating. It uses shell-origin state plus a one-use handoff
+  code exchange to obtain a tenant-bound shell token resolved by the platform
+  shell-context endpoint. Do not reuse the `tenant-app` `@minutework/web-auth`
+  customer-session profile for it, forward raw platform session/CSRF cookies,
+  or add a local password-login BFF.
+- Vuilder publish must produce the marketplace coordinate consumed by customer
+  signup:
+  `core:app_pack_catalog:<publisherTenantId>:<appId>:<appVersion>`. The
+  public-site manifest/release context pins that coordinate and digest; browser
+  code must not invent or modify it.
 - Templates are governed starters, not the full limit of what Builder may use.
 - Builder may adopt open-source libraries, frameworks, and products inside the
   sandbox when that reduces bespoke code and still preserves the MinuteWork

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

@@ -19,8 +19,9 @@ the monorepo or a live tenant runtime.
   - app packs
   - skills
   - tenant overlays
-- `tenant-app`, optional `sidecar`, and the optional `mobile` starter are
-  implementation surfaces inside the tenant product, not the whole architecture.
+- `tenant-app`, `vuilder-app`, `vuilder-shell`, optional `sidecar`, and the
+  optional `mobile` starter are implementation surfaces inside the generated
+  workspace, not the whole architecture.
 - `tenant-app` is the combined public plus private web starter.
 - In `tenant-app`, keep MinuteWork web auth/data access inside the thin
   `src/mw/` substrate and `@minutework/web-auth`. Product UI may call that
@@ -61,12 +62,26 @@ the monorepo or a live tenant runtime.
   same-named method to return tokens.
 - If the `mobile` starter is enabled (`starters.mobile.enabled`), read
   `standalone-mobile-client/SKILL.md` before proposing the mobile surface.
-- `vuilder-public-site` is a Vuilder-owned public-site authoring workspace for
-  landing, blog, and onboarding routes backed by public-dj CMS manifests.
-- If `template_kind` is `vuilder-public-site`, or the workspace profile says
-  `public_dj_cms`, read `vuilder-public-site-authoring/SKILL.md`.
-- `vuilder-public-site` does not own tenant `/app`, `/w/*`, or runtime
-  `mw.core.site`; it renders public-dj content pinned by manifest ref/digest.
+- A first-class Vuilder workspace defaults to `vuilder-app`, `vuilder-shell`,
+  app-pack source, and optional `sidecar` / `mobile` starters when selected.
+  FleetRun is an example vertical, not a hardcoded product.
+- If the workspace has `starters.vuilderApp.enabled`,
+  `starters.vuilderShell.enabled`, `vuilder-app/`, or `vuilder-shell/`, read
+  `vuilder-workspace-architecture/SKILL.md` first.
+- `vuilder-app` is a Vuilder-owned public-site authoring workspace for landing,
+  blog, and onboarding routes backed by public-dj CMS manifests. It is
+  materialized from `vuilder-public-site`.
+- `vuilder-app` does not own tenant `/app`, `/w/*`, or runtime `mw.core.site`;
+  it renders public-dj content pinned by manifest ref/digest and redirects
+  customer signup into central SSO.
+- `vuilder-shell` is a Vuilder-branded customer tenant shell under
+  `/w/[workspace_slug]`; it customizes tenant UX while platform owns identity,
+  provisioning, and app-pack install authority. Use central SSO, shell-origin
+  state, a short-lived one-use handoff code, and the tenant-bound
+  `mw_vuilder_shell_session` context endpoint for `vuilder-shell`; do not use
+  `@minutework/web-auth`, raw platform session/CSRF cookies, same-origin `/_mw`
+  tenant customer routes, local password forms, or local credential-login BFF
+  routes there. Preserve the requested workspace in the SSO return URL.
 - For member-facing collaboration and operator work, the primary product surface
   is the gateway shell under `/w/[workspace_slug]`. Do not default to a bespoke
   standalone tenant frontend when the work belongs in shell threads, cards, or
@@ -96,7 +111,8 @@ the monorepo or a live tenant runtime.
   itineraries, proposals, pages, and generated assets should usually come from
   runtime data/content/workflow, not fresh product rebuilds.
 - Current external alpha constraints matter:
-  - local authoring supports `tenant-app`, `sidecar`, or both
+  - local authoring supports `tenant-app`, `vuilder-app`, `vuilder-shell`,
+    `sidecar`, `mobile`, or selected combinations
   - hosted deploy is preview-first
   - live public delivery and sidecar/runtime-backed deploys are not implied from
     the current external lane

package/assets/claude-local/skills/integration-broker-and-connectors/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: integration-broker-and-connectors
+description: "External integrations, ads, brokered connectors, spend/approval governance, or whether to use mw.connector.ads instead of bespoke provider code."
+---
+
+# Integration Broker And Connectors
+
+Use this skill when a request touches external integrations, paid acquisition,
+ads, provider connectors, agent-driven provider actions, spend limits,
+approvals, credentials, receipts, or questions like "can the agent run ads?"
+
+## What It Is
+
+MinuteWork has a governed integration broker for external systems. The first
+native connector is `mw.connector.ads`.
+
+- Runtime owns the local action surface and exposes connector actions as
+  `workflow.run_action` capability calls.
+- Platform DJ owns provider credentials, provider account scope, tenant broker
+  connections, advertiser identity, spend authorization, approval policy,
+  append-only receipts, webhooks, and adapter execution.
+- Generated apps and sidecars should call the brokered capability instead of
+  storing provider credentials or implementing ad-spend policy locally.
+- Provider availability still depends on configured platform broker accounts.
+  Do not promise a provider is live just because a provider key is reserved.
+
+## Compose, Do Not Rebuild
+
+Before adding ad, spend, approval, credential, or connector logic to
+`tenant-app` or a `sidecar`, check whether the integration belongs on the
+broker path.
+
+- Use `integration_broker.execute` for brokered connector actions.
+- Use `mw.connector.ads` for ads instead of inventing tenant-local ad APIs.
+- Add providers through the platform broker adapter seam, not browser code,
+  generated app credentials, or ungoverned sidecar calls.
+- Keep provider account and organization scope in Platform DJ. Tenant payloads
+  must not supply provider account, ad account, organization, or credential
+  identifiers as a way to bypass the broker connection.
+- Use app-pack or schema changes for tenant product data around the integration,
+  but keep external provider writes on the governed broker.
+
+## Ads Connector
+
+`mw.connector.ads` is a first-party runtime app-pack baseline. It is available
+without a tenant app installing an ads pack.
+
+Mutating actions:
+
+- `ads.create_campaign`
+- `ads.update_campaign`
+- `ads.pause_campaign`
+- `ads.create_group`
+- `ads.create_creative`
+- `ads.create_ad`
+
+Read action:
+
+- `ads.fetch_report`
+
+Reserved future action:
+
+- `ads.record_conversion`
+
+Provider keys:
+
+- Default: `openaiads`
+- Extensible: `googleads`, `metaads`, `tiktokads`
+
+Treat these provider keys as broker-routing keys. Do not infer that a provider
+is configured for a tenant until the runtime capability inventory or platform
+broker preflight reports readiness.
+
+## Governance Model
+
+Rely on the broker safety model instead of recreating it:
+
+- `BrokerProviderAccount` and `BrokerConnection` bind platform-owned provider
+  account scope to tenant broker access.
+- `AdvertiserProfile` represents verified advertiser identity and accepted
+  terms.
+- `AdsSpendAuthorization` defines approved spend caps.
+- `AdsSpendPolicyReceipt` records reserved/released budget decisions.
+- `TenantWallet.reserved_credits_cents` backs approved future ad spend before
+  more metered work can consume the same credits.
+- `BrokerApprovalGrant` gates mutating/spend actions with human approval.
+- `BrokerReceipt` and `BrokerWebhookEvent` provide append-only, payload-digested
+  audit trails.
+- `AdsCampaignProjection` and `AdsObjectProjection` project provider objects
+  back into scoped tenant/runtime state.
+
+Mutating ads actions are approval-gated and budget-gated. Credentials and spend
+policy never belong in browser code, generated app artifacts, or tenant-local
+sidecar configuration.
+
+## Builder Decision Rules
+
+- For paid-acquisition or ads questions, route through this skill before
+  proposing a custom ad manager.
+- For "what can we build?" answers, mention that runtime agents can drive
+  governed external integrations when a first-party or broker-backed connector
+  exists.
+- For AI-agent workflows, keep AI and provider actions inside governed runtime
+  capabilities. UI gathers intent and renders results.
+- For OSS or mature external products, use `attached_app` or sidecar bridge code
+  only when the foreign system should remain foreign. Connector writes still
+  need broker-style governance when credentials, spend, approvals, or audit are
+  involved.
+- If a requested connector is missing, report a platform capability gap instead
+  of adding unreviewed provider credentials or a direct network adapter.
+
+Useful inspection points when source is available:
+
+- `apps/mwv3-platform-dj/apps/integration_broker/models.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/services.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/adapters.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/api/`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/first_party_packs/mw_connector_ads.py`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/ads_connector_services.py`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/integration_broker_capabilities.py`
+- `reference/mwv3-dj6-docs/connector_pack_and_engine_resolution_contract.md`
+- `reference/mwv3-dj6-docs/runtime_app_pack_contract.md`

package/assets/claude-local/skills/layering-and-import-modes/SKILL.md

@@ -16,6 +16,10 @@ Use this skill when choosing between configuration, app-pack changes, overlays,
   or composition inside the Builder sandbox.
 - Durable tenant behavior should usually compile to governed app-pack artifacts,
   not ad hoc backend code.
+- For external integrations that involve credentials, provider writes, spend,
+  approvals, or audit receipts, read
+  `integration-broker-and-connectors/SKILL.md` and use the broker substrate when
+  it fits.
 - Use `attached_app` when a mature foreign system should remain its own
   subsystem and MinuteWork should compile a governed control surface around it.
 - Use `external_repo_intake` only when no reviewed capability skill or cleaner

package/assets/claude-local/skills/project-overview-and-strategy/SKILL.md

@@ -31,6 +31,9 @@ needed:
   belongs in governed runtime capabilities instead of browser/provider calls.
 - `layering-and-import-modes/SKILL.md` for build-native vs govern-existing,
   `attached_app`, OSS adoption, and greenfield-last decisions.
+- `integration-broker-and-connectors/SKILL.md` for external integrations, paid
+  acquisition, ads, brokered connectors, spend/approval governance, and
+  `mw.connector.ads`.
 - `sidecar-generation/SKILL.md` for bridge/integration execution, workers,
   webhooks, schedulers, and backend compute.
 - `standalone-mobile-client/SKILL.md` for Expo/native client boundaries.
@@ -87,6 +90,9 @@ substrate:
 - Runtime agents use `mw.runtime.agent` seed records and namespaced runtime-kind
   tool packs. UI surfaces collect inputs and render governed outputs; they do
   not run model/provider logic directly.
+- Runtime agents can drive external integrations through governed connector
+  capabilities such as `mw.connector.ads`; credentials, spend approvals, and
+  provider writes stay brokered by the platform.
 - OSS and mature external products are adopted before rebuilding when they fit.
   Use `attached_app` when the foreign system should remain independently
   deployed, and use sidecar bridge code plus runtime agents/tool packs to make

package/assets/claude-local/skills/shell-architecture/SKILL.md

@@ -12,6 +12,16 @@ threads, channels, inboxes, guest collaboration, approvals, dashboards, or
 - Default to the member shell first. For collaboration and operator work, the
   primary product surface is the gateway shell under `/w/[workspace_slug]`, not
   a bespoke standalone tenant frontend.
+- `vuilder-shell` is the generated Vuilder-branded customer tenant shell. It
+  keeps `/w/[workspace_slug]` and `/w/[workspace_slug]/connect` as branded
+  customer workspace routes, but it must still rely on platform identity,
+  provisioning, and app-pack install authority. It is a platform member shell
+  using central SSO plus a tenant-bound `mw_vuilder_shell_session` token, not a
+  `tenant-app` `@minutework/web-auth` customer session surface and not raw
+  platform session/CSRF cookies. Its `/login` route sets a shell-origin state
+  cookie before redirecting to central SSO; SSO returns a short-lived one-use
+  code, and the shell exchanges that code server-side before setting the
+  host-only session cookie. Do not add local password-login BFF routes.
 - Treat these nouns as the default mental model:
   - **Server**: the product-facing private tenant space
   - **Channel**: a conversation surface inside the shell
@@ -47,6 +57,11 @@ threads, channels, inboxes, guest collaboration, approvals, dashboards, or
   - the surface is a mobile app (Expo / React Native / native iOS/Android) ->
     author in the `mobile` starter, not `tenant-app`; see
     `standalone-mobile-client/SKILL.md`
+- Do not confuse shell surfaces:
+  - central platform shell: first-party MinuteWork member shell substrate
+  - `vuilder-shell`: generated branded customer tenant shell for a Vuilder
+    vertical, backed by platform member sessions
+  - `tenant-app`: combined public/private web starter for ordinary tenant apps
 - If shell fit is correct but this generated workspace cannot directly author
   the shell extension, keep the shell-first recommendation and record a
   capability gap instead of silently converting the request into standalone

package/assets/claude-local/skills/vuilder-public-site-authoring/SKILL.md

@@ -6,8 +6,9 @@ description: "Vuilder-owned public websites, public-dj CMS manifests, vuilder-pu
 # Vuilder Public Site Authoring
 
 Use this skill when the request touches a Vuilder-owned public website,
-`vuilder-public-site`, public-dj CMS content, or customer signup through a
-Vuilder vertical.
+`vuilder-app`, `vuilder-public-site`, public-dj CMS content, or customer signup
+through a Vuilder vertical. If the workspace also includes `vuilder-shell` or
+app-pack source, read `vuilder-workspace-architecture/SKILL.md` first.
 
 ## System Boundary
 
@@ -25,8 +26,10 @@ Vuilder vertical.
 
 ## Template Contract
 
-- Use `runtime/builder/templates/vuilder-public-site` for Vuilder-owned landing,
-  blog, public onboarding, and other public marketing routes.
+- Use `vuilder-app/` as the generated public starter directory. It is
+  materialized from `runtime/builder/templates/vuilder-public-site` for
+  Vuilder-owned landing, blog, public onboarding, and other public marketing
+  routes.
 - The template reads public-dj through a server-only CMS adapter.
 - Expected release env includes `MW_PUBLIC_DJ_BASE_URL`,
   `MW_PUBLIC_CONTENT_REF`, `MW_PUBLIC_CONTENT_DIGEST`, and
@@ -48,6 +51,9 @@ Vuilder vertical.
 - The public-site BFF creates customer onboarding intents from server-pinned
   release context: property/release refs, manifest ref/digest, package
   ref/digest, onboarding flow ref/digest, and Vuilder workspace context.
+- After creating the intent, redirect the browser to central SSO at an opaque
+  route like `/onboarding/vertical/[intent_id]`. The public site does not log
+  in users or complete provisioning itself.
 - Browser intake answers are untrusted input. Browsers must not author package
   refs, manifest refs, provisioning kind, or workspace identity.
 

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

@@ -0,0 +1,78 @@
+---
+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."
+---
+
+# Vuilder Workspace Architecture
+
+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.
+
+## Default Workspace Shape
+
+A first-class Vuilder workspace is vertical-neutral. FleetRun is an example
+vertical name, not a platform hardcode.
+
+Expected generated layout:
+
+- `vuilder-app/`: public landing, blog, and onboarding site. It uses the
+  `vuilder-public-site` template and public-dj CMS manifests.
+- `vuilder-shell/`: Vuilder-branded customer tenant shell. It opens customer
+  workspace routes like `/w/[workspace_slug]` and
+  `/w/[workspace_slug]/connect`. Its `/login` route sets a host-only shell
+  handoff state cookie, redirects to central platform SSO, receives a
+  short-lived one-use handoff code, exchanges that code server-side for a
+  tenant-bound shell token, and stores that token as a host-only
+  `mw_vuilder_shell_session` cookie. It never receives raw platform session
+  cookies and is not the `tenant-app` `@minutework/web-auth` customer-session
+  profile.
+- App-pack source: schemas, agents, flows, views, seed data, and package
+  metadata under the workspace authoring layer.
+- Optional `sidecar/` and `mobile/` starters when selected.
+
+## Flow
+
+The acquisition and install path is:
+
+1. Customer lands on the Vuilder public site (`vuilder-app`).
+2. The public-site BFF creates `customer_vertical_signup` using
+   server-pinned release context.
+3. The browser is redirected to central SSO.
+4. SSO handles login/signup and completes the opaque onboarding intent
+   server-side.
+5. Platform provisions the customer tenant runtime VM.
+6. Platform installs the approved app pack from the marketplace coordinate.
+7. The branded `vuilder-shell` opens the customer workspace.
+
+## Hard Boundary
+
+`vuilder-shell` customizes tenant UX, navigation, copy, branding, and customer
+workspace presentation. It does not own identity, tenant creation, runtime
+provider selection, billing policy, provisioning, package refs, manifest refs,
+attestation, digest checks, or app-pack install authority.
+
+Do not wire `vuilder-shell` to same-origin `/_mw` tenant customer auth routes.
+Do not render a local password form or expose a local credential-login BFF in
+`vuilder-shell`. `/login` is only a redirect handoff to central SSO with a
+trusted return URL and shell-origin state for the requested workspace. SSO
+completion creates a platform `Membership` and returns a one-use handoff code;
+the shell validates the echoed state, exchanges the code server-side, stores the
+returned `mw_vuilder_shell_session`, and resolves server-authored shell context
+from that token. It must fail closed for missing or mismatched state, missing
+tokens, mismatched workspace slugs, missing member capabilities, or blocked
+workspace-open affordance.
+
+Browser intake is untrusted. Do not let browser code choose package refs,
+manifest refs, Vuilder workspace ids, provisioning kind, runtime provider,
+billing policy, or install coordinates.
+
+## Related Skills
+
+- Use `vuilder-public-site-authoring` for `vuilder-app`, public-dj manifests,
+  and onboarding-intent creation.
+- Use `shell-architecture` for `vuilder-shell` customer workspace routes.
+- Use `app-pack-authoring` for schemas, agents, flows, package metadata, and
+  marketplace publish output.
+- Use `generated-workspace-architecture` for general local workspace trust
+  boundaries.

package/assets/templates/vuilder-public-site/.env.example

@@ -0,0 +1,11 @@
+MW_PUBLIC_DJ_BASE_URL=http://127.0.0.1:8003
+MW_AUTH_BASE_URL=http://127.0.0.1:3400
+MW_PLATFORM_BASE_URL=http://127.0.0.1:8000
+MW_PUBLIC_BASE_URL=http://127.0.0.1:3300
+MW_PUBLIC_SITE_PROPERTY_KEY=main-site
+MW_PUBLIC_SITE_ENV=preview
+MW_PUBLIC_RELEASE_CLASS=ssr_container
+MW_PUBLIC_CONTENT_REF=
+MW_PUBLIC_CONTENT_DIGEST=
+MW_PUBLIC_DJ_READ_TOKEN=
+MW_VUILDER_ONBOARDING_INTENT_TOKEN=

package/assets/templates/vuilder-public-site/README.md

@@ -0,0 +1,15 @@
+# Vuilder Public Site Template
+
+`vuilder-public-site` is the public website template for Vuilder-owned websites.
+Builder edits normal Next.js code in this workspace. Public content comes from
+public-dj through an immutable site manifest ref and digest.
+
+The template supports two release classes:
+
+- `static_export`: content is resolved during build and emitted as static output.
+- `ssr_container`: server code resolves the pinned public-dj manifest at runtime.
+
+The browser never receives public-dj credentials or platform intent credentials.
+Onboarding starts through the server route at `/api/onboarding/start`, which asks
+platform to create a `customer_vertical_signup` intent from release-pinned
+server context.

package/assets/templates/vuilder-public-site/eslint.config.mjs

@@ -0,0 +1,6 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = [...nextVitals, ...nextTs];
+
+export default eslintConfig;

package/assets/templates/vuilder-public-site/next-env.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// This file is automatically generated by Next.js.

package/assets/templates/vuilder-public-site/next.config.mjs

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function resolveTurbopackRoot(startDirectory) {
+  let directory = startDirectory;
+  while (true) {
+    if (existsSync(path.join(directory, "pnpm-workspace.yaml"))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return startDirectory;
+    directory = parent;
+  }
+}
+
+const nextConfig = {
+  reactStrictMode: true,
+  typedRoutes: true,
+  ...(process.env.MW_PUBLIC_RELEASE_CLASS === "static_export" ? { output: "export" } : {}),
+  turbopack: {
+    root: resolveTurbopackRoot(__dirname),
+  },
+};
+
+export default nextConfig;

package/assets/templates/vuilder-public-site/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "vuilder-public-site",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "pnpm@9.0.0",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "dev": "next dev --hostname 127.0.0.1 --port 3300",
+    "build": "next build",
+    "start": "next start -p 3300",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typegen": "next typegen",
+    "template:validate": "node tools/template/validate-template.mjs",
+    "typecheck": "tsc --noEmit",
+    "validate": "pnpm template:validate && pnpm typegen && pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "next": "^16.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "server-only": "^0.0.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "ajv": "^8.17.1",
+    "eslint": "^9.39.1",
+    "eslint-config-next": "^16.2.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.2.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  }
+}

package/assets/templates/vuilder-public-site/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: {},
+};
+
+export default config;

package/assets/templates/vuilder-public-site/src/app/api/onboarding/start/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from "next/server";
+
+import { env } from "@/lib/env.server";
+import { createCustomerVerticalSignupIntent } from "@/lib/platform.server";
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const payload = await createCustomerVerticalSignupIntent({
+    email: String(formData.get("email") ?? ""),
+    name: String(formData.get("name") ?? ""),
+  });
+
+  const nextUrl = new URL(
+    `/onboarding/vertical/${encodeURIComponent(String(payload.intent.id))}`,
+    env.MW_AUTH_BASE_URL,
+  );
+
+  return NextResponse.redirect(nextUrl, { status: 303 });
+}