minutework 0.1.19 → 0.1.20

package/EXTERNAL_ALPHA.md

@@ -58,9 +58,16 @@ The broker fails closed when a live session is already active, the selected
 engine is missing, a prior running record has gone stale, or the launch is
 interrupted or fails mid-session.
 
-Generated workspaces receive a root `CLAUDE.md` plus exported `skills/`
-guidance so the local coding agent sees the combined-web, snapshot-delivery,
-and `mw.core.site` baseline workflow.
+Generated workspaces receive a root `CLAUDE.md` and `AGENTS.md` (rendered from
+the same source so they cannot drift) plus exported `skills/` guidance so the
+local coding agent sees the combined-web, snapshot-delivery, and `mw.core.site`
+baseline workflow. Claude Code reads `CLAUDE.md`; Codex and other IDE agents read
+`AGENTS.md`.
+
+The workspace MCP (read-only context tools) is wired for Cursor
+(`.cursor/mcp.json`) and Codex (`.codex/config.toml`, which Codex loads for
+trusted projects); `mcp/claude-desktop.sample.json` is included for Claude
+Desktop.
 
 Generated guidance and MCP wiring can be reconciled later with
 `minutework workspace sync-assets`.
@@ -131,6 +138,10 @@ If the workspace cannot compile hosted preview release metadata for the linked p
 
 The CLI does not fabricate success. If the backend cannot materialize a hosted preview deployment provider, the receipt reports a typed failure and the CLI exits non-zero.
 
+## Machine-readable output (`--json`)
+
+`validate`, `compile`, `codegen`, and `deploy --preview` accept `--json` for unattended, agent-driven use. The command prints a single result envelope to stdout (`{ cliJsonVersion, command, ok, status, result, error }`) and nothing else; `ok` mirrors the exit code (fail-closed). `deploy --preview --json` never prompts — pair it with `--yes` to authorize, otherwise it returns `status: "confirmation_required"` and exits non-zero. The automatic bug report is suppressed in `--json` mode.
+
 ## Failure semantics
 
 - Missing auth: run `minutework login`
@@ -145,7 +156,7 @@ The CLI does not fabricate success. If the backend cannot materialize a hosted p
 
 ## CLI bug reports
 
-- The CLI automatically submits a sanitized bug report for failed commands unless `MW_CLI_BUG_REPORTS=never` is set.
+- The CLI automatically submits a sanitized bug report for failed commands unless `MW_CLI_BUG_REPORTS=never` is set (machine-readable `--json` verbs suppress this automatically).
 - Automatic reports keep a local JSON bundle under the MinuteWork CLI state root for retry and support follow-up.
 - `minutework report-bug --note "..."` sends a manual report for UX issues or suspicious behavior that did not crash.
 - `minutework report-bug --last --note "..."` resends the last saved bundle with extra context.

package/README.md

@@ -11,6 +11,7 @@ The current external alpha is intentionally narrow:
 - Hosted release class: `ssr_container`
 - Deploy surface: `minutework deploy --preview`
 - Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, marketplace publish flows
+- Reserved verb: `minutework publish` is present but **fails closed** (a typed `not_implemented` result) until the marketplace publication-review + attestation backend lands
 
 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
@@ -74,8 +75,14 @@ minutework session resume
 - The broker fails closed on live overlap, missing engine binaries, stale
   session records, interrupts, and launch failures instead of allowing
   overlapping phantom sessions.
-- Generated workspaces receive a root `CLAUDE.md` plus exported `skills/`
-  guidance tailored to the combined web and published-site workflow.
+- Generated workspaces receive a root `CLAUDE.md` and `AGENTS.md` (rendered from
+  the same source so they cannot drift) plus exported `skills/` guidance tailored
+  to the combined web and published-site workflow. Claude Code reads `CLAUDE.md`;
+  Codex and other IDE agents read `AGENTS.md`.
+- The workspace MCP (read-only context tools) is wired for Cursor
+  (`.cursor/mcp.json`) and Codex (`.codex/config.toml`, which Codex loads for
+  trusted projects); `mcp/claude-desktop.sample.json` is included for Claude
+  Desktop.
 - Managed guidance and MCP wiring can be refreshed later with
   `minutework workspace sync-assets`.
 - Runtime-only Claude hooks are not exported into the generated workspace.
@@ -99,10 +106,32 @@ For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Ve
 
 `deploy --preview` always revalidates and recompiles before submit, prints a local-vs-remote diff, requires confirmation unless `--yes` is passed, polls typed receipts until a terminal state, and persists the last known preview deploy state under `.minutework/deploy/preview/status.json`. This alpha is preview-first; live public delivery remains follow-on.
 
+## Machine-readable output (`--json`)
+
+`validate`, `compile`, `codegen`, and `deploy --preview` accept `--json` so an IDE coding agent can drive them unattended and parse one stable shape. With `--json` the command prints a single result envelope to stdout and nothing else:
+
+```json
+{
+  "cliJsonVersion": 1,
+  "command": "validate | compile | codegen | deploy",
+  "ok": true,
+  "status": "ok | compiled | generated | activated | failed | rolled_back | confirmation_required | not_implemented | error",
+  "result": {},
+  "error": null
+}
+```
+
+- `ok` mirrors the process exit code: `0` when `ok` is `true`, non-zero otherwise (fail-closed).
+- `result` is the typed payload — the validate report (`validate`), the compile graph (`compile` / `codegen`), or the terminal deploy receipt (`deploy`).
+- `deploy --preview --json` runs unattended and never prompts. Pair it with `--yes` to authorize the deploy; without `--yes` it returns `status: "confirmation_required"` (exit 1) instead of blocking on a prompt.
+- In `--json` mode the automatic diagnostic report is suppressed — the envelope and exit code are the whole contract.
+
 ## Bug reporting
 
 CLI failures automatically send a sanitized diagnostic report to the MinuteWork platform unless `MW_CLI_BUG_REPORTS=never` is set.
 
+- Machine-readable verbs run with `--json` suppress automatic reporting; rely on the result envelope and exit code instead.
+
 - Automatic reports never include raw `.env` contents, tokens, source files, or full local paths.
 - The CLI keeps a local report bundle under the MinuteWork state root so you can retry or inspect what was sent.
 - Use `minutework report-bug --note "what happened"` for manual reports.

package/assets/claude-local/CLAUDE.md.template

@@ -13,11 +13,23 @@ If this workspace's exported guidance looks stale or a newly added skill is
 missing, run `minutework workspace sync-assets` from the workspace root. See
 `skills/workspace-guidance-refresh/SKILL.md` for the managed refresh flow.
 
+## Workspace MCP
+
+The MinuteWork workspace MCP server exposes read-only context tools (workspace
+snapshot, schema status, capability inventory, deploy status, and a workspace
+doctor; tool names are prefixed `minutework_`). Prefer these over guessing at
+workspace state. It is wired for Cursor (`.cursor/mcp.json`) and Codex
+(`.codex/config.toml`, loaded for trusted projects); for Claude Desktop, copy
+`mcp/claude-desktop.sample.json`. Refresh all of this with
+`minutework workspace sync-assets`.
+
 ## Skills
 
-This workspace includes MinuteWork architecture skills under `skills/`. Claude
-loads them automatically when relevant to your request. Run `/skill-name` to
-invoke one directly, or ask "What skills are available?" to see the full list.
+This workspace includes MinuteWork architecture skills under `skills/`. Your IDE
+coding agent can use them as reference: browse `skills/` and read the relevant
+`SKILL.md` when a topic matches your task. In Claude Code these skills load
+automatically and `/skill-name` invokes one directly; other agents (Codex,
+Cursor) can open the files directly or ask "What skills are available?".
 
 ## Shell-First UI Default
 
@@ -50,6 +62,7 @@ implementation surfaces inside that pack.
 | --- | --- | --- |
 | Authenticated standalone web UI, separate tenant portal, custom client, or other explicit shell exception | `tenant-app` | This is the Next.js UI/BFF surface after shell fit has been checked. |
 | Public website, pricing, docs, blog, landing pages | `tenant-app` | Public web belongs in the web app surface; do not create a sidecar just to render pages. |
+| Vuilder-owned public website, landing/blog/onboarding routes, or public-dj CMS-backed vertical site | `vuilder-public-site` | This is the Vuilder public-site template; code lives in the workspace and content comes from public-dj manifest revisions. |
 | Internal API, webhook handler, worker, cron, queue consumer, ingestion, Python-heavy compute | `sidecar` | This is backend/runtime logic, not a browser app concern. |
 | Web app plus background jobs, integrations, AI processing, or internal APIs | `both` | Put UI in `tenant-app`; put backend execution in `sidecar`. |
 | No UI, only runtime automation or processing | `sidecar` | A web app is unnecessary. |
@@ -115,11 +128,25 @@ a concrete backend responsibility such as:
 
 - Payload-aware drafting and generation should default to the runtime's existing
   AI capability, not direct browser/provider integrations.
+- App-pack-owned runtime agents should be installed with `mw.runtime.agent`
+  seed records. Use `logical_key` as `Agent.slug`, keep prompts in installed
+  manifest data with trace metadata, and declare domain behavior through
+  `capabilities.runtime_kind`.
+- Runtime-kind behavior must be implemented as a namespaced adapter/tool pack
+  registered with the generic runtime-kind registry. Do not put tenant or
+  vertical-specific branches in generic thread, intake, or conversation
+  services.
 - When the runtime already provides an AI capability, reuse it before adding
   bespoke model SDK calls in `tenant-app` or `sidecar`.
 - `tenant-app` should collect inputs, review/edit outputs, and call typed
   platform/runtime surfaces; do not put provider credentials or direct
   browser-to-model calls in the web app.
+- Shell and `tenant-app` should render hydrated thread posts and artifacts only.
+  They should not run agent logic, execute tools, call providers, or infer
+  access policy from raw metadata.
+- Agent drafts, analysis, and operator cards should carry explicit runtime
+  visibility such as `internal_note` or `member_only`; guest-safe content must
+  be server-filtered and explicitly marked safe.
 - Do not add a bespoke AI sidecar for MVP drafting/generation unless you can
   name a concrete gap in the existing runtime AI capability.
 - If runtime AI availability is unclear, inspect the linked runtime/workspace
@@ -130,6 +157,15 @@ a concrete backend responsibility such as:
 
 ## Public Site Defaults
 
+- If `Template: {template_kind}` is `vuilder-public-site`, or the request says
+  Vuilder public site / public-dj CMS, load
+  `skills/vuilder-public-site-authoring/SKILL.md`.
+- Vuilder public sites use public-dj `PublicSiteManifestRevision` as the CMS
+  content source and platform `SiteRelease.content_source` set to
+  `shared_public_content`; they do not use runtime `mw.core.site` as their CMS.
+- Vuilder customer signup routes must create platform onboarding intents from
+  server-pinned release context. Browser labels must not decide runtime
+  provisioning behavior.
 - Treat `mw.core.site` as a runtime baseline capability that already exists. Do
   not model site work as "installing" or "reconciling" the baseline.
 - `mw.core.site` already includes `config`, `page`, `nav`, `form`, and
@@ -188,6 +224,23 @@ a concrete backend responsibility such as:
   Builder/codegen task when the installed product should render it from runtime
   data/content/workflow.
 - `sidecar` is internal-first by default.
+- Do not add tenant-hardcoded code (Django management commands, seeders,
+  fixtures, scripts) to shared platform or runtime modules such as
+  `apps/runtime_app_host/management/commands/`. Tenant-shaped seeders in
+  shared infra are an anti-pattern. Author baseline-extending seed records
+  as workspace-local declarative source and let the runtime App Host's
+  generic install/reconcile path apply them.
+- Do not gate public intake render on a hardcoded client-side token
+  allowlist. Public handoff tokens are platform-validated server-side
+  (Django-signed self-contained payloads); the workspace UI should pass
+  the token through to the BFF and let the platform decide validity.
+- Do not put generated React or component code in public-dj database rows;
+  public-dj stores Vuilder CMS content and immutable manifest revisions.
+- Do not use tenant `/app`, `/w/*`, or runtime `mw.core.site` as the serving or
+  CMS model for `vuilder-public-site`.
+- Do not infer Vuilder authoring, Vuilder operator runtime, or customer tenant
+  provisioning from browser-provided labels. Use platform-owned onboarding
+  intents.
 
 See the files under `skills/` for deeper guidance on schema authoring,
 app-pack structure, published web, content sections, sidecar generation, event

package/assets/claude-local/bundle.json

@@ -2,7 +2,10 @@
   "bundle_version": 1,
   "render": {
     "template": "CLAUDE.md.template",
-    "output": "CLAUDE.md"
+    "outputs": [
+      "CLAUDE.md",
+      "AGENTS.md"
+    ]
   },
   "directories": {
     "skills": "skills"

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

@@ -16,7 +16,9 @@ receive:
 - Builder should compose shared substrate before generating bespoke tenant code
 - `tenant-app` is the combined public plus private web starter
 - `mw.core.site` is a runtime baseline capability
-- public authoring is runtime/CMS-backed
+- tenant public authoring is runtime/CMS-backed through `mw.core.site`
+- Vuilder-owned public sites use `vuilder-public-site` and public-dj CMS
+  manifests
 - anonymous live delivery should prefer published snapshots
 - AI drafting/generation should reuse existing runtime AI capability before new
   model/provider integrations
@@ -27,6 +29,7 @@ receive:
 Generated-workspace-first guidance should live here, especially:
 
 - `generated-workspace-architecture/SKILL.md`
+- `vuilder-public-site-authoring/SKILL.md`
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`

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

@@ -33,6 +33,12 @@ An `app pack` is the shipped product unit.
 - For AI-assisted drafting MVPs, let `tenant-app` collect/edit inputs and
   outputs while an existing runtime AI capability produces the draft when
   available; ask or inspect context if that availability is unclear.
+- For app-pack-owned agents, prefer a declarative `mw.runtime.agent` seed plus
+  a namespaced `capabilities.runtime_kind` adapter over tenant-specific
+  branches in shared runtime services.
+- Shell and `tenant-app` surfaces should render hydrated thread posts and
+  artifacts; they should not run agent logic, execute tools, call providers, or
+  infer access policy from artifact metadata.
 - Public-site authoring should stay CMS/runtime-backed, while anonymous live
   delivery should prefer published snapshots.
 - Prefer this decision order before writing greenfield code:
@@ -52,3 +58,54 @@ An `app pack` is the shipped product unit.
   extension that can later collapse into a reusable primitive, baseline
   capability, reviewed skill, or app pack.
 - Keep platform-owned runtime source untouched; author only workspace-local generated source.
+
+## Baseline-Extending Seed Records
+
+- Builder authors records the runtime should hold (e.g. `mw.core.site.form`,
+  `mw.core.site.page`, `mw.core.site.nav`) as workspace-local declarative
+  source under `schemas/`, collected into a `SeedDataManifest` that the
+  compiler discovers and the CLI ships to the tenant runtime via the
+  install pipe. Treat these as durable Builder artifacts even when no
+  install pipe has applied them yet.
+- Concrete authoring convention (envelope pinned in
+  `runtime_app_pack_contract.md` sec 5.3): a single named
+  `seedDataManifest` export on the schema entrypoint module namespace,
+  either directly in `schemas/schema.ts` or re-exported from a
+  per-domain sibling (e.g. `export { seedDataManifest } from
+  "./site-forms.js"`). Records are `{ schema_key; logical_key; data }`;
+  only `schema_key` values registered in the runtime's
+  `SCHEMA_KEY_UPSERT_REGISTRY` may ship in the active manifest.
+- For `mw.core.site.form`, do not author `form_key` or `app_pack_ref` inside
+  `data`; the install pipe injects both. Keep `surface_key == form_key` for
+  public intake BFFs.
+- For `mw.runtime.agent`, use `logical_key` as the runtime `Agent.slug`.
+  Author stable agent fields in `data` such as `name`, `system_instruction`,
+  `enabled_tools`, `trigger_intents`, `channels_enabled`, and
+  `capabilities.runtime_kind`. The install pipe injects tenant/app-pack
+  ownership and prompt trace metadata. Same app-pack lineage may update the
+  slug; a different pack claiming the same tenant slug fails transactionally.
+- Runtime-kind behavior must live behind a namespaced adapter/tool pack
+  registered with the runtime-kind registry. Generic runtime services call the
+  registry and must not branch on tenant names, app names, or domain-specific
+  runtime kinds.
+- Agent outputs meant for operator/member review should be written as hydrated
+  thread posts/artifacts with explicit visibility such as `internal_note` or
+  `member_only`. Guest/public surfaces only receive guest-safe visibility after
+  server-side filtering.
+- The install path onto a tenant runtime is the runtime App Host's generic
+  reconcile loop (designed in `runtime_app_pack_contract.md` sec 3, 5, 11),
+  invoked from the workspace via the CLI deploy verb. Per-schema upsert
+  services on the runtime (e.g. `upsert_site_form`) are the building blocks
+  that loop calls; they are not directly Builder-callable.
+- Do not bypass the install pipe by writing a tenant-hardcoded Django
+  management command, seeder, or fixture in shared platform/runtime modules.
+  That is an anti-pattern; the right Builder response when the install pipe
+  is missing or unshipped is to author the seed source here and file the
+  missing-pipe gap (see `capability-gap-reporting/SKILL.md`).
+- An operator may apply a one-shot Django shell call to a runtime DB as a
+  stopgap to unblock end-to-end testing; treat it as out-of-band, not as
+  Builder-committed source, and do not codify it as a recurring path.
+- The v1 invariant `surface_key == form_key` (see
+  `contract-first-public-intake/SKILL.md`) constrains the `form_key` value
+  on `mw.core.site.form` seeds: it must equal the public surface key the
+  BFF sends.

package/assets/claude-local/skills/contract-first-public-intake/SKILL.md

@@ -63,6 +63,28 @@ guest-continuity threads, public submission routing, or claim-after-auth flows.
   on retries.
 - For follow-on automation, treat the runtime submission record as the durable
   source that can drive later `action:` or `flow:` execution.
+- Do not gate public intake render on a hardcoded client-side token
+  allowlist. The handoff token is a platform-issued, server-validated
+  payload; the workspace UI should pass it through to the BFF and let the
+  platform decide validity. A client-side allowlist drifts from the real
+  token registry and silently breaks once real tokens are minted.
+
+## Vuilder Vertical Onboarding
+
+- For customer onboarding from a Vuilder public site, also read
+  `vuilder-public-site-authoring/SKILL.md`.
+- Use the platform-owned `OnboardingIntent` contract. Supported intent kinds
+  are `vuilder_authoring`, `vuilder_operator_runtime`, and
+  `customer_vertical_signup`.
+- A Vuilder public-site BFF should create `customer_vertical_signup` intents
+  from server-pinned release context, not from browser-provided provisioning
+  labels.
+- Trusted fields such as Vuilder workspace, published property/release,
+  public-dj manifest ref/digest, vertical package ref/digest, and onboarding
+  flow ref/digest must come from platform/publication context.
+- Browser clients may submit intake answers only. They must not submit trusted
+  package refs, manifest refs, workspace identity, runtime provisioning kind, or
+  billing disposition.
 
 ## Use This Skill To Decide
 

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

@@ -22,6 +22,12 @@ the monorepo or a live tenant runtime.
 - `tenant-app` and optional `sidecar` are implementation surfaces inside the
   tenant product, not the whole architecture.
 - `tenant-app` is the combined public plus private web starter.
+- `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.
 - 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

package/assets/claude-local/skills/published-web-and-mw-core-site/SKILL.md

@@ -9,6 +9,15 @@ Use this skill when the request touches public-site delivery, published-web
 flows, or the default MinuteWork site model.
 
 - Treat `mw.core.site` as a runtime baseline capability that already exists.
+- For Vuilder-owned public websites, read
+  `vuilder-public-site-authoring/SKILL.md`; public-dj
+  `PublicSiteManifestRevision` is the CMS/release content source instead of
+  runtime `mw.core.site`.
+- Vuilder public-site releases use
+  `SiteRelease.content_source = shared_public_content`, with shared public
+  content refs pointing to an immutable public-dj manifest ref and digest.
+- Tenant/customer content created after customer provisioning remains
+  runtime-canonical through `mw.core.site` and installed app-pack data.
 - `tenant-app` is the combined web starter for public routes plus the private
   `/app` workspace.
 - Author public content against runtime/CMS records, not a fixed in-repo site
@@ -56,6 +65,9 @@ flows, or the default MinuteWork site model.
   form/submission model.
 - Form and submission records already carry routing, identity-resolution, and
   continuity fields for public intake and follow-up flows.
+- Seed dispatch and install-time seed manifests that target `mw.core.site.form`
+  require the baseline `mw.core.site` pack to be installed first so `SCHEMA_FORM`
+  is registered before upsert handling runs.
 
 ## Current Baseline Catalog
 

package/assets/claude-local/skills/runtime-capability-inventory/SKILL.md

@@ -44,6 +44,23 @@ generated Builder workspace.
   - installed app packs and their class/status
   - sidecar processes, entrypoints, ports, and health state
   - live runtime descriptor outputs such as public-site route prefixes
+- In the native Builder Harness path, the platform-dispatched
+  `RuntimeHarnessDiagnosticsV1` snapshot is a safe linked-runtime surface for
+  Builder workspace/session status, engine readiness, primitive inventory,
+  installed app-pack status counts, app-host baseline readiness, database
+  migration counts, event-bus counts, and warnings. Treat it as planning
+  context, not as an install or provisioning authority.
+- In the Vuilder Harness path, workspace kickoff uses the platform-dispatched
+  `/api/v1/builder/workspaces/ensure/` runtime endpoint to create or reuse the
+  hosted `BuilderWorkspace` and context snapshot only. Do not infer sandbox
+  files, engine sessions, Claude execution, or app-pack installs from this
+  kickoff.
+- `BuilderMaterializationPreflightV1` from
+  `/api/v1/builder/materialization/preflight/` is a safe readiness report for a
+  digest-reviewed architecture and template key. Treat its findings, policy
+  digest, preflight digest, sandbox driver, and artifact counts as preflight
+  context only; actual sandbox writes, codegen, installation, activation, and
+  publication remain separate effectful actions.
 - Linked runtime surfaces are the authoritative source for live runtime
   inspection, but do not assume every generated workspace has them.
 - Use the more specific workspace MCP tools as needed:

package/assets/claude-local/skills/schema-engine/SKILL.md

@@ -20,6 +20,24 @@ Use this skill when the request needs tenant-defined data structures.
   `platform_submission_ref` and preserve the original record on retry.
 - The default lookup fields that usually deserve indexes for public intake are
   `platform_submission_ref`, `form_key`, and `continuity_ref`.
+- Seed manifests or install-time seeds that upsert `mw.core.site.form` depend on
+  the baseline `mw.core.site` pack already being present so `SCHEMA_FORM` is
+  registered before dispatch.
+- Seed manifests may also install app-pack-owned runtime agents through
+  `mw.runtime.agent`; use `logical_key` as the `Agent.slug`, put stable agent
+  fields under `data`, and let the runtime inject tenant/app-pack ownership.
+- For `mw.runtime.agent`, declare `capabilities.runtime_kind` when the agent
+  needs domain behavior. The runtime resolves that value through the generic
+  runtime-kind adapter registry; do not encode domain branching in generic
+  thread, intake, or conversation services.
+- Agent prompts should be installed as versioned manifest data with traceable
+  source metadata. Do not rely on live workspace file paths at runtime.
+- Runtime posts and artifacts carry first-class visibility. Guest-safe
+  serializers fail closed, so author internal drafts, analysis, and operator
+  cards as `internal_note` or `member_only` until explicitly made guest-safe.
+- Runtime Builder diagnostics may expose safe schema/app-host readiness summaries
+  such as active schema registration counts; treat them as planning context, not
+  as schema definitions or install authority.
 
 ## Current mw.core.site Baseline
 

package/assets/claude-local/skills/vuilder-discovery-output-contract/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: vuilder-discovery-output-contract
+description: "Constrain Vuilder discovery to AI-native service operations and MinuteWork-buildable delivery systems instead of generic startup ideas."
+---
+
+# Vuilder Discovery Output Contract
+
+Use this skill when Vuilder discovery is deciding what to propose from a user's
+profile, resume, pasted context, or refinement request.
+
+Discovery is pre-workspace. It must produce a buildable service direction that
+can flow into the paid Planning Blueprint and later Builder handoff. It must not
+pretend to create projects, runtimes, releases, packages, secrets, or live
+published surfaces.
+
+## Core Output
+
+Discovery cards are build cards, not founder idea cards.
+
+Each card must describe:
+
+- an AI-native service outcome the operator can credibly deliver
+- the buyer or internal team receiving that service outcome
+- evidence from the user's profile that makes the operator credible
+- the MinuteWork delivery system Builder can prepare
+- the first workflow the system should support
+- the runtime records, AI workers, Builder surfaces, and artifacts involved
+- capability gap candidates for unsupported substrate
+
+Discovery should ask:
+
+> What service outcome can this operator credibly deliver, and what
+> MinuteWork-supported system can Builder create to help deliver it?
+
+Do not ask:
+
+> What SaaS startup should this person found?
+
+## Builder Constraints
+
+- Compose shared MinuteWork substrate before bespoke code.
+- Treat the app pack as the shipped product unit.
+- Check shell fit first for member-facing collaboration and operator work.
+- Use `tenant-app` only for public surfaces or explicit standalone UI
+  exceptions after shell fit has been checked.
+- Use `sidecar` only for concrete backend/runtime responsibilities such as
+  webhooks, workers, schedulers, external sync, or Python-heavy compute.
+- Reuse runtime AI for drafting/generation before proposing bespoke provider
+  calls in `tenant-app` or `sidecar`.
+- Per-customer deliverables should come from runtime data/content/workflows, not
+  fresh Builder/codegen work for each customer.
+- Unsupported substrate becomes a capability gap candidate, not a polished
+  promise.
+
+## Banned Framing
+
+Do not make these the primary discovery output:
+
+- generic SaaS ideas
+- founder coaching
+- TAM-first or ARR-first startup cards
+- broad knowledge-management products without a specific service workflow
+- unsupported "Builder can build anything" claims
+
+Service packaging, pricing, market notes, or revenue hypotheses may appear as
+secondary context only after the service outcome and buildable system are clear.
+
+## Discovery Tool Use
+
+The discovery agent may use read-only evaluation and research tools to sharpen
+cards before it saves proposal fields:
+
+- `extract_workflows_from_context` for repeatable work, bottlenecks, buyers, and
+  AI workforce jobs already implied by the user's context.
+- `search_industry_examples` for curated MinuteWork service-business patterns.
+  This is not open web search.
+- `estimate_market_pricing` for bounded pilot and retainer ranges with explicit
+  assumptions and uncertainty.
+- `score_service_card_fit` for use-it-first fit, sell-it-back potential, buyer
+  urgency, founder advantage, implementation difficulty, and jargon risk.
+- `rewrite_card_for_plain_language` for advisory rewrites of user-facing fields.
+- `validate_discovery_proposal` before saving or marking a proposal ready.
+- `research_unknown_entity` only as a confidence-gated fallback for an obscure
+  company, product, acronym, vendor, or niche workflow already present in the
+  resume, pasted context, or user message.
+
+Do not use web research for well-known entities or general concepts the model
+already understands, such as ADP, Workday, Fidelity, COBRA, or 401k, unless the
+user explicitly asks for current/recent information. Web results are cited
+context evidence, not authority for market-size or revenue claims.
+
+## Required Build Card Fields
+
+Use the `DiscoveryBuildCardV1` shape:
+
+- `id`
+- `plain_title`
+- `plain_summary`
+- `work_you_already_do`
+- `ai_workforce_summary`
+- `use_it_first`
+- `sell_it_back`
+- `first_pilot`
+- `market_size_estimate`
+- `yearly_revenue_potential`
+- `pilot_pricing`
+- `why_you_can_win`
+- `who_it_helps`
+- `what_minutework_helps_with`
+- `service_outcome`
+- `buyer`
+- `operator_fit_summary`
+- `evidence_from_profile`
+- `minute_work_build`
+- `builder_surfaces`
+- `shell_fit`
+- `shell_surface`
+- `standalone_ui_exception_reason`
+- `first_workflow`
+- `runtime_records`
+- `ai_workforce`
+- `expected_artifact_graph`
+- `required_capabilities`
+- `capability_gap_candidates`
+- `paid_blueprint_will_create`
+- optional `service_packaging`
+
+Plain-language fields are user-facing. They must express MinuteWork's loop:
+build the AI workforce from work the operator already does, use it first under
+their own judgment, then sell it back to their industry. Do not expose Builder
+jargon such as app pack, schemas, runtime records, right rail, runtime agent seed,
+or capability gaps in those fields.
+
+Capability gap candidates use the same layer vocabulary as
+`MinuteWorkCapabilityGapReportV1`, but they are not the workspace gap report.
+The actual gap report is created later inside the generated Builder workspace.

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

@@ -0,0 +1,76 @@
+---
+name: vuilder-public-site-authoring
+description: "Vuilder-owned public websites, public-dj CMS manifests, vuilder-public-site template work, or customer onboarding from a Vuilder vertical site."
+---
+
+# 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.
+
+## System Boundary
+
+- Vuilder public sites are authored in a Vuilder builder/operator workspace.
+- Generated React, Next.js, route, component, and styling code belongs in the
+  workspace/template source tree, not in public-dj database rows.
+- public-dj is the CMS and revision store for Vuilder-owned public content:
+  pages, blog posts, onboarding flow content, navigation, brand profile, media,
+  theme tokens, and approved package/install metadata.
+- Platform owns `PublishedWebProperty`, `SiteRelease`, domains, hosted
+  deployment receipts, onboarding intents, billing disposition, and runtime
+  provisioning.
+- Tenant/customer runtime content after customer provisioning remains
+  runtime-canonical through `mw.core.site` and app-pack data.
+
+## Template Contract
+
+- Use `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
+  `MW_PUBLIC_DJ_READ_TOKEN`.
+- Resolve CMS data by immutable `content_ref + digest`; do not render live
+  public pages from mutable drafts.
+- The template may be released as `static_export` or `ssr_container` behind the
+  hosted deployment provider abstraction.
+
+## Onboarding Intent Rules
+
+- Vuilder authoring signup uses `vuilder_authoring`: create workspace/profile,
+  no runtime VM.
+- Vuilder upgrade uses `vuilder_operator_runtime`: provision the Vuilder's own
+  builder/operator VM and materialize the public-site template.
+- Customer signup through the Vuilder site uses `customer_vertical_signup`:
+  provision the customer's tenant runtime and install the approved vertical
+  package.
+- 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.
+- Browser intake answers are untrusted input. Browsers must not author package
+  refs, manifest refs, provisioning kind, or workspace identity.
+
+## Release Rules
+
+- Platform `SiteRelease.content_source` should be `shared_public_content` for a
+  Vuilder public site.
+- `shared_public_content_ref` and `shared_public_content_digest` point to the
+  public-dj `PublicSiteManifestRevision`.
+- Live activation remains a platform/manual approval action using approved
+  public content and package refs.
+- Public-dj may store markdown/content/media/theme revisions; it must not store
+  or execute generated React component code as database content.
+
+## Hard Rules
+
+- Do not use tenant `/w/*`, `/app`, or the universal tenant shell in
+  `vuilder-public-site`.
+- Do not use runtime `mw.core.site` as the CMS for Vuilder-owned public
+  websites.
+- Do not infer provisioning behavior from browser labels, hostnames, or query
+  params; use platform-owned onboarding intents.
+- Do not expose platform credentials, public-dj tokens, package refs, or
+  OpenRouter/provider keys to browser bundles.
+- Do not let public-dj execute tenant runtime code or import runtime Django
+  apps for public-site rendering.

package/assets/templates/fastapi-sidecar/README.md

@@ -1,6 +1,12 @@
 # FastAPI Sidecar Template
 
-This directory is the canonical internal FastAPI sidecar scaffold for Builder. Builder will later materialize this bundle into `BuilderWorkspace.sandbox_root/sidecar/` and edit only that workspace copy.
+This directory is the canonical internal FastAPI sidecar scaffold for Builder.
+Builder will later materialize this bundle into
+`BuilderWorkspace.sandbox_root/sidecar/` and edit only that workspace copy.
+
+On managed tenant VMs, `BuilderWorkspace.sandbox_root` normally lives under
+`/srv/minutework/workspaces/<workspace_id>/`, so the Builder-edited sidecar copy
+is typically `/srv/minutework/workspaces/<workspace_id>/sidecar/`.
 
 `seed_source` intentionally points back to this directory because the canonical bundle itself is the v1 source of truth. There is no separate `apps/*` seed app for this template.