minutework 0.1.19 → 0.1.21

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`, `deploy --preview`, and `publish` 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` and `publish --json` never prompt — pair them with `--yes` to authorize, otherwise they return `status: "confirmation_required"` and exit non-zero. For `publish`, a rejected publication-review attestation is reported as `ok: false` with the gate findings in `result.findings` (a real review outcome, not a transport error). 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

@@ -1,16 +1,17 @@
 # `minutework`
 
-MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, and submitting hosted preview deploys.
+MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, submitting hosted preview deploys, and publishing app packs to the marketplace through the publication-review gate.
 
 ## External alpha scope
 
 The current external alpha is intentionally narrow:
 
-- Starter: `tenant-app`
+- Starters: `tenant-app` (the deployable web surface) and `mobile` (init-only)
 - Developer-local broker surface: `minutework session start|resume|status`
 - Hosted release class: `ssr_container`
 - Deploy surface: `minutework deploy --preview`
-- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, marketplace publish flows
+- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, and the commercial marketplace listing/pricing layer
+- Marketplace publish: `minutework publish` submits the compiled, digest-bound app pack through the platform publication-review + attestation gate and publishes it to the public marketplace catalog **only** on an approved (or approved-with-warnings) attestation; a rejected attestation prints the review findings and exits 1 without publishing
 
 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
@@ -43,7 +44,20 @@ npx minutework login
 npx minutework link
 ```
 
-After `link`, the current alpha has two supported lanes.
+After `link`, the current alpha has two supported lanes (both `tenant-app`).
+
+For a native mobile client, scaffold the **`mobile`** starter instead:
+
+```bash
+npx minutework init my-app --starter mobile
+```
+
+It is **init-only** and bring-your-own-UI: a minimal Expo (React Native) client
+that authenticates **directly** against the platform with a native device-flow
+session token (PKCE authorize -> exchange -> bearer + refresh in the device
+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`.
 
 ### Developer-local broker lane
 
@@ -74,8 +88,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 +119,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,8 +29,10 @@ 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`
+- `standalone-mobile-client/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`
 - `layering-and-import-modes/SKILL.md`
 - `capability-gap-reporting/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

@@ -19,9 +19,23 @@ the monorepo or a live tenant runtime.
   - app packs
   - skills
   - tenant overlays
-- `tenant-app` and optional `sidecar` are implementation surfaces inside the
-  tenant product, not the whole architecture.
+- `tenant-app`, optional `sidecar`, and the optional `mobile` starter are
+  implementation surfaces inside the tenant product, not the whole architecture.
 - `tenant-app` is the combined public plus private web starter.
+- A mobile / native client (Expo, React Native, native iOS/Android) is a
+  standalone-client exception authored in the `mobile` starter, not in
+  `tenant-app` or `sidecar`. It is a direct platform API client that consumes
+  the platform native-token API (`/api/v1/native/...`) directly with a
+  platform-issued native session token, rather than the `tenant-app` BFF cookie
+  session.
+- 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.
 - 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/shell-architecture/SKILL.md

@@ -44,6 +44,9 @@ threads, channels, inboxes, guest collaboration, approvals, dashboards, or
   - the surface is public marketing
   - the surface is public intake for non-members
   - the surface is an embeddable widget
+  - 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`
 - 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/standalone-mobile-client/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: standalone-mobile-client
+description: "Building a native mobile app (Expo / React Native / native iOS/Android). It is a standalone-client exception authored in the mobile starter as a direct platform API client using a native session token, not in tenant-app or sidecar."
+---
+
+# Standalone Mobile Client
+
+Use this skill when the request is "can I build a mobile app?", or anything
+that involves a native iOS/Android surface (Expo, React Native, or fully native).
+The answer is yes, and the shape is fixed. Do not flip-flop on it.
+
+## Where it lives
+
+- A native mobile app is a **standalone-client exception**. It is authored in
+  the `mobile` starter (`destinationDirectory: mobile`), enabled via the
+  workspace config key `starters.mobile = { enabled: true, path: "mobile" }`.
+- It is **not** part of `tenant-app`, and **not** part of `sidecar`. Do not put
+  native code, Expo config, or React Native screens inside either of those
+  surfaces.
+- `tenant-app` stays web-only. The mobile app is a sibling client, not a tab or
+  route inside the web BFF.
+
+## What it is
+
+- The mobile app is a **direct platform API client**. It talks to the platform
+  HTTP API at `/api/v1/native/session/...` and nothing else. It does not go
+  through the `tenant-app` BFF.
+- Authentication uses a platform-issued **native session token** -- a distinct
+  principal class, the "native app session token holder". This is exactly what
+  the auth contract anticipates: non-browser clients must mint explicit scoped
+  tokens after browser-assisted login or a device flow
+  (`reference/mwv3-dj6-docs/auth_and_credential_contract.md`, Rule 7).
+- The app reads the platform base URL from `EXPO_PUBLIC_MW_PLATFORM_BASE_URL`.
+
+## Endpoints (shipped)
+
+All native endpoints live under `/api/v1/native/session/`:
+
+- `authorize/` -- browser-assisted consent (GET renders the login/consent page
+  or redirects to the onboarding host; POST confirms and 302-redirects to the
+  app `redirect_uri` with `?code=...&state=...`).
+- `token-exchange/` -- POST `{code, code_verifier, redirect_uri}` -> `{access,
+  refresh, expires_at, ...}`. No bearer required.
+- `refresh/` -- POST `{refresh_token}` -> a new `{access, refresh}` pair. No
+  bearer required.
+- `me/` and `context/` -- GET (bearer) -> the tenant session payload for the
+  bound user/tenant. `context/` is currently identical to `me/`.
+- `logout/` -- POST (bearer) -> revokes the presented token's access/refresh
+  family.
+
+## Auth flow
+
+The native token flow mirrors the existing CLI developer-token flow
+(PKCE authorize -> exchange -> opaque scoped tokens):
+
+1. **Authorize (browser-assisted device flow):** the app generates a PKCE
+   verifier and opens `GET /api/v1/native/session/authorize/` (with
+   `code_challenge`, `state`, `redirect_uri`) in a system browser. The user logs
+   in and confirms on the platform; the platform POSTs the confirmation and
+   302-redirects back to the app's `redirect_uri` with a one-time `code` and the
+   `state`.
+2. **Exchange:** the app POSTs that one-time `code` plus the matching PKCE
+   `code_verifier` and the same `redirect_uri` to
+   `/api/v1/native/session/token-exchange/`, receiving an **access token +
+   refresh token** (opaque, scoped; access ~15 min, refresh ~30 days).
+3. **Store:** both tokens are persisted in `expo-secure-store` (the device
+   keystore), never in plain React/web state.
+4. **Call:** every request to `/api/v1/native/session/...` carries
+   `Authorization: Bearer <access>`.
+5. **Refresh:** on access-token expiry (`401`), POST the refresh token to
+   `/api/v1/native/session/refresh/` to mint a new pair, then retry. Refresh is
+   **rotating** -- the old access/refresh family is revoked, so persist the
+   freshly returned pair. Re-run the browser-assisted authorize step only when
+   the refresh token itself is invalid or revoked.
+
+The browser/BFF cookie path belongs to `tenant-app` and is **web-only**. The
+mobile app does not ride the `tenant-app` cookie jar, and it does not read or
+forward CSRF -- native uses the bearer token directly against the platform.
+
+### Token binding (what is and isn't enforced)
+
+The token is bound to one tenant + membership, and that binding **is** enforced:
+a request that names a different tenant is rejected, and a token whose membership
+has been deactivated stops authenticating. The optional `audience` and
+`device_id` fields are **informational only** -- the platform carries them
+through authorize -> exchange (and preserves them across refresh) but does **not**
+validate or compare them. Do not treat `audience` or `device_id` as a security
+boundary.
+
+## What not to do
+
+- Do not build a parallel auth stack.
+- Do not mint a JWT inside the app or stand up a local user table / token issuer.
+- Do not expose access or refresh tokens to web pages or generic React state;
+  keep them in `expo-secure-store`.
+- Do not route the mobile app through the `tenant-app` BFF cookie session.
+- Do not read or forward CSRF from native; bearer-token auth does not use it.
+- Do not put native code inside `tenant-app` or `sidecar`.
+
+## Distribution
+
+- The `mobile` starter is **init-only**. Scaffolding it lands the app in the
+  workspace; it does not deploy it.
+- Distribution is the developer's own pipeline: EAS Build, TestFlight, and the
+  Play Store. It is **not** `minutework deploy`.