@unoverse-platform/studio 0.1.25 → 0.1.27

package/vendor/skills/unoverse-create/references/template.md

@@ -1,115 +1,175 @@
-# Playbook — Templates (MCP apps)
+# Playbook: Templates (MCP apps)
 
 **Read first:** `docs/design/templates.md` (layouts + manifest-as-envelope) +
-`docs/design/state.md` (the reaction contract + name-sync). Deep law:
-`UNOVERSE_STATE_MODEL.md` §5b, `UNOVERSE_LAYERS.md`. Everything in the component
-playbook (closed vocabulary, tokens, scale steps) applies here too.
-
-## THE model — layouts sync by name
-
-A component is a Switch of **faces**; a template is a set of **layouts** — same
-mechanism, two tiers, connected by ONE rule:
-
-> A component enters a view → the template presents the layout of the same name.
-> No matching layout → the default layout; the component renders inline.
-
-Derived off the store, never stored, no wiring — the component never knows templates
-exist. **Rule of thumb: component causes it = layout; template knows it = state.**
+`docs/design/state.md` (the state model). Deep law: `UNOVERSE_STATE_MODEL.md` §5
+(the six rules), `UNOVERSE_LAYERS.md`. Everything in the component playbook (closed
+vocabulary, tokens, scale steps) applies here too. **Study the exemplar before
+writing**: `rx/sab/templates/sab-chat-layout` is the canonical State Model v2 template.
+
+## THE model: the component drives; the template reacts by name
+
+A component is a state tree whose public states are its whole interface; a template
+declares its OWN state tree in the manifest and reacts to components by name:
+
+> A component enters a public view → the template asks "do I have a state with that
+> name?" Match: the template enters that state and its layout draws. No match: the
+> component renders inline in the flow. Always.
+
+Derived off the store, never stored, no wiring. The component never knows templates
+exist, and post-spawn the template NEVER writes a component's state. Name-match is the
+default convention (`reactsTo:` on a template state is the rare escape hatch for
+vocabulary mismatches). **Rule of thumb: component causes it = a reaction state;
+template knows it = a base substate or template state.**
+
+## The manifest states tree: one declaration, everything follows
+
+The canonical shape (`rx/sab/templates/sab-chat-layout/manifest.yaml`):
+
+```yaml
+states:
+  main:                 # the base arrangement, FIRST
+    states:
+      welcome: {}       # contained substate; first substate = the landing default
+  focus: {}             # then the reaction ladder, in priority order
+  products: {}
+  detail: {}
+```
 
-## The anatomy — manifest-only (NO `<name>.json` envelope)
+- **Top-level order IS the priority ladder**, base first. The template can be in ONE
+  state at a time: it walks the list top-down and enters the first of its states that
+  ANY hosted component currently matches. The ladder is DERIVED from the tree; never
+  author `stateOrder` (that field survives only as the legacy form for templates
+  without a tree).
+- **Nesting IS containment, enforced by compilation.** A declared base substate
+  (`welcome`) is stripped from every non-base arrangement; no hand-written guard ever
+  polices it. The substate's file keeps its own condition (`visibleWhen: isEmpty`).
+- **The shell rule.** Base content drawn in every arrangement is NOT declared as a
+  substate. sab's conversation timeline is main's own shell, included by the shared
+  chat chrome and legitimately drawn beside the rail, the page and under focus;
+  declaring it would contain it to `main` and empty the chat column in every reaction
+  state. Only states the template must scope get declared.
+- **Arrival honors the component's declared initial** when the template has a matching
+  state; otherwise the template scans its own states in declared order and takes the
+  first name on the component's public menu; no overlap and the component rides inline.
+- **A higher state CANCELS the claims below it**: while active, hosted components in
+  lower-ranked states retract to inline (durable `lifetime: "conversation"` slices opt
+  out), so releasing it lands on the BASE arrangement, never a stale lower one.
+- Ties (two components in the same view): most recent write wins (`limit: 1`).
+- **No word is special.** `focus` outranks `products` by list position only; the engine
+  matches names and walks the list. Even priority is data.
+- The template's own condition-guarded moods (a welcome hero on an empty conversation)
+  are private substates of the base, never ladder entries: the template does not
+  rearrange between them.
+
+## The anatomy: manifest-only (NO `<name>.yaml` envelope)
 
 ```
-apps/unoverse/rx/orgs/<org>/templates/<name>/
-  manifest.json    # THE ENVELOPE — the whole app contract (below)
-  layouts/         # the ARRANGEMENTS — one per component view + the default
-    standard.json  #   the default (manifest.layout): the core alone
-    products.json  #   view "products" → core + cards rail
-    product.json   #   view "product"  → core + detail panel
+apps/unoverse/rx/<project>/templates/<name>/
+  manifest.yaml    # THE ENVELOPE: the whole app contract, incl. the states tree
+  layouts/         # the ARRANGEMENTS: one per state that owns one (same-name default)
+    main.yaml      #   the base: the core alone
+    products.yaml  #   state "products" → core + cards rail
+    detail.yaml    #   state "detail"  → core + full record page
   components/      # template-local partials (core, header, composer-bar, turns…)
-  states/          # LOCAL states only (welcome, conversation, call phases) —
-                   # available in exactly the layouts whose trees include them
+  states/          # base substates' drawings (welcome): included plainly by the
+                   # chrome, own condition inside, containment compiled from the tree
 ```
 
-Each layout = a complete arrangement: `{ "$include": "components/core" }` + that view's
-surface. Shared chrome lives ONCE in `components/`; every layout includes it. A layout
-named after a view MUST contain a surface selecting that view (guard-enforced) — the
-name claims the instance, the surface renders it.
+Each layout = a complete arrangement: `$include: components/core` + that state's
+surface. Shared chrome lives ONCE in `components/`; every layout includes it. The tree
+claims the instance, the layout's surface renders it: a reaction state's layout holds a
+ComponentSlot selecting the matching view.
 
-## manifest.json (the app contract)
+## manifest.yaml (the app contract)
 
-Required: `name` · `description` (what it IS, ≤120) · `whenToUse` (utterance-shaped — the
-USER's words; findIntent ranks on it — the OPENING words carry the ranking; disqualify by
+Required: `name` · `description` (what it IS, ≤120) · `whenToUse` (utterance-shaped: the
+USER's words; findIntent ranks on it, the OPENING words carry the ranking; disqualify by
 property, never by naming siblings; full contract: docs/design/05 §Naming) ·
-`category` · `defaultState` (`"template"` = the full surface) · `inputSchema` ·
-`layout` (the DEFAULT layout name) · `stateOrder` (local states + layouts, picker order) ·
-`binding` (`workflow` + `trigger` — the app OWNS its workflow; without a real binding it
-is not done). Optional: `preview` (the per-LAYOUT mock map for Studio —
-`{ "products": ["productcard", "productcard"] }`; repeated name = several instances),
-`autoTrigger`, `expose`, `service` (`"voice"` — the channel instantiates the native
-service, which projects `callState` into scope).
+`category` · `defaultState: "template"` (the app-level LOAD state, a protocol field,
+nothing to do with component views) · `inputSchema` · `layout` (the BASE layout name) ·
+`states` (the tree above) · `binding` (`workflow` + `trigger`: the app OWNS its
+workflow; without a real binding it is not done). Optional: `preview` (the per-state
+mock map for Studio: `{ "products": ["product-card", "product-card"] }`; repeated
+name = several instances), `autoTrigger`, `expose`, `service` (`"voice"`: the channel
+instantiates the native service, which projects `callState` into scope).
 
-**The generalist trap:** a home/fallback surface must NOT enumerate its siblings' jobs —
-it owns general help and cedes specific jobs by property, naming none.
+**The generalist trap:** a home/fallback surface must NOT enumerate its siblings' jobs.
+It owns general help and cedes specific jobs by property, naming none.
 
-## Sizing — each layout owns its widths
+## Sizing: each layout owns its widths
 
 The app = the ACTIVE layout's total, nothing else ever. Inside a layout: the core panel
 is always open (`appWidth` on the core box), the surface panel declares its width on the
 ComponentSlot. Lint-enforced:
-- `appWidth` = a NAMED size from the org's `styles/semantic/app-sizes.json`
-  (`chat` · `chat-slim` · `rail` · `panel`) — raw CSS is an ERROR.
-- ONE declaration per panel — the frame never declares width/flex.
+- `appWidth` = a NAMED size from the project's `styles/semantic/app-sizes`
+  (`chat` · `chat-slim` · `rail` · `panel` · `flex`). Raw CSS is an ERROR.
+- ONE declaration per panel; the frame never declares width/flex.
 - NEVER on a layout root; NEVER `visibleWhen`-guarded (a conditional arrangement is a
-  LAYOUT, selected by name).
-- An OVERLAY surface (`inset: 0` over the core) declares NO appWidth and needs NO layout
-  of its own — reach for a layout when the ARRANGEMENT changes.
-- Nothing in the manifest sizes the app (`width`/`focusWidth` dead — lint error).
+  STATE with its own layout).
+- An OVERLAY surface (`inset: 0` over the core) declares NO appWidth and needs NO state
+  of its own. Reach for a state when the ARRANGEMENT changes.
+- Nothing in the manifest sizes the app (`width`/`focusWidth` dead, a lint error).
 - Layout root: `overflow: hidden`.
 
-## Surfaces — templates REACT, they never own
-
-One instance → one placeholder: the flow is the placeholder for `inline`; a surface (or
-a layout, via its inner surface) is the placeholder for a named view. The SDK keeps a
-claimed instance out of the flow — never hide a flow copy yourself.
-
-- **Flow slot**: `{ "type": "ComponentSlot", "select": {} }` — always present.
-- **Reaction surface**: select by the VIEW, never by type/id:
-  ```jsonc
-  { "type": "ComponentSlot", "appWidth": "panel",
-    "select": { "from": "all", "where": { "field": "defaultState", "eq": "product" }, "limit": 1 },
-    "frame": { /* chrome; an inner bare ComponentSlot marks the placement */ } }
+## Surfaces: templates REACT, they never own
+
+One instance → one placeholder: the flow is the placeholder for `inline`; a reaction
+state's layout (via its inner surface) is the placeholder for a matched view. The SDK
+keeps a claimed instance out of the flow; never hide a flow copy yourself.
+
+- **Flow slot**: `{ type: ComponentSlot, select: {} }`, always present.
+- **Reaction surface**: select by the public `view`, never by type/id:
+  ```yaml
+  type: ComponentSlot
+  appWidth: panel
+  select:
+    from: all
+    where: { field: view, eq: detail }
+    limit: 1
+  frame:  # chrome; an inner bare ComponentSlot marks the placement
   ```
-  ❌ `select: { type: [...] }`, ❌ `where.field` ≠ `defaultState`, ❌ template chrome
-  writing a component's slice — all lint-flagged.
+  ❌ `select: { type: [...] }`, ❌ `where.field` ≠ `view`, ❌ template chrome
+  writing a component's slice, all lint-flagged. (`defaultState` as the select field
+  is the v1 legacy spelling.)
+- **Input tools are template chrome** (unchanged rule): a composer, an edit form, a
+  picker is owned by the template, never a streamed component state; chrome never
+  "arrives". A card's Edit stages its data into the template's one input tool.
 - **Template state** (`setTemplateValue`) is ONLY for the template's own chrome (a
-  disclosure, the composer `draft`). "Is something focused" is DERIVED — never stored.
+  disclosure, the composer `draft`). "Is something focused" is DERIVED, never stored.
 - **Chrome reacts via `surfacedView`** (SDK-projected active view name, `""` = all
-  inline): `visibleWhen { "field": "surfacedView", "in": ["", "products"] }`.
-- **A `limit: 1` surface's occupant FILLS it** automatically — never sprinkle
-  `minHeight: full` through faces. Rails (no limit) keep content-sized cards.
+  inline): `visibleWhen { field: surfacedView, in: ["", "products"] }`.
+- **A `limit: 1` surface's occupant FILLS it** automatically; never sprinkle
+  `minHeight: full` through component layouts. Rails (no limit) keep content-sized cards.
 - A full layer caps its height and scrolls its BODY only (`flex: 1` + `minHeight: 0` +
   `overflow: auto`; header/footer pinned).
+- `pinned: true` on a reaction layout keeps late-arriving components from yanking the
+  page from under a reading guest; the guest's own tap still moves it.
 
 ## Voice templates
 
-`"service": "voice"` in the manifest. Call phases (`states/idle…user-speaking`) are
-LOCAL states included by the cores; typically a wide core in the default layout and a
-slim core (`chat-slim`) in the card layouts. Cards during a call select layouts by name
-exactly as in chat. Audio is never wired in a definition.
+`"service": "voice"` in the manifest. Call phases (idle…user-speaking) branch off the
+projected `callState` discriminant inside the base; typically a wide core in the base
+layout and a slim core (`chat-slim`) in the card layouts. Cards during a call match
+template states by name exactly as in chat. Audio is never wired in a definition.
 
-## New org?
+## New project?
 
-`rx/orgs/<org>/` = `templates/` + optional `components/` (org-private microapps, names
-unique across tiers) + a **complete self-contained** `styles/` (copy
-`rx/orgs/default/styles` and re-value the base scales). Addresses: apps
-`unoverse://apps/<org>/<name>`, org components `unoverse://components/<org>/<name>`,
-themes `unoverse://theme/<org>/<theme>`.
+`rx/<project>/` = `templates/` + optional `components/` (project-private microapps,
+names unique across tiers) + a **complete self-contained** `styles/` (copy an existing
+project's `styles/` and re-value the base scales). Addresses: apps
+`unoverse://apps/<project>/<name>`, project components
+`unoverse://components/<project>/<name>`, themes `unoverse://theme/<project>/<theme>`.
 
 ## Validate & ship
 
-1. Publish from Studio — its lint must report 0 errors (layout/name-sync rules, widths, reaction rules, tokens).
-2. Restart unoverse — the node re-synthesizes.
-3. **See it**: Studio — layout pills on top (default first, stateOrder order), local
-   states down the left, freely combinable; acting inside the preview transitions like
-   the runtime. Then run it live: the bound workflow streams components, and entering a
-   view swaps the layout end-to-end.
+1. Manifest declares the states tree: base first, reaction states in priority order,
+   base-only moods nested inside the base, shell content NOT declared. No authored
+   `stateOrder`, no hand-written containment guards.
+2. Publish from Studio; its lint must report 0 errors (the rules are v2-aware:
+   state/layout ownership, widths, reaction rules, tokens).
+3. Restart unoverse; the node re-synthesizes.
+4. **See it**: in Studio, the state switcher reads the tree (base first, ladder order),
+   base substates beneath, freely combinable; acting inside the preview transitions
+   like the runtime. Then run it live: the bound workflow streams components, a card
+   entering a public view walks the ladder and rearranges the template end-to-end,
+   and its ✕ hands the lower state back.

package/vendor/skills/unoverse-create/references/workflow.md

@@ -1,6 +1,6 @@
 # Playbook: Build a workflow (via the builder MCP)
 
-Workflows are NOT files in the carve-out — they live in the platform and are built
+Workflows are NOT files in the carve-out. They live in the platform and are built
 through the **builder MCP** (`canvas`, auto-registered by this repo's
 `.mcp.json`). You drive the platform's own authoring tools; the canvas updates live
 in the developer's browser as you build.
@@ -8,15 +8,15 @@ in the developer's browser as you build.
 ## Prerequisites (check before starting)
 
 1. **The platform is running** (`unoverse start`, or `npm run dev` in the platform
-   repo). The builder listens on `localhost:4106` — local machine only, by design.
+   repo). The builder listens on `localhost:4106`, local machine only, by design.
 2. **The MCP is connected**: `canvas` should show connected with 14 tools.
-   If it shows failed, the platform wasn't up when the session started — reconnect
+   If it shows failed, the platform wasn't up when the session started. Reconnect
    via `/mcp` after starting it.
 3. **The developer gives you a pairing code.** Ask them to open a **new empty
    workflow in Canvas** (http://localhost:3001), click **"Connect agent"** in the
    toolbar, and paste the short code it shows (e.g. `FW9D-6QKA`). The code binds you
-   to that one workflow — single use, expires in 10 minutes. There is deliberately no
-   way to list or discover workflows from here — the code must come from the developer.
+   to that one workflow: single use, expires in 10 minutes. There is deliberately no
+   way to list or discover workflows from here. The code must come from the developer.
    Prefer a fresh workflow: saves are provenance-scoped, so wiring into nodes you
    didn't create may be rejected.
 
@@ -25,19 +25,19 @@ in the developer's browser as you build.
 1. **`bindWorkflow` first.** Every other tool refuses until the session is bound,
    and every call after is pinned server-side to that one canvas.
 2. **Read the in-band guides before building.** The deep how-to is served by the
-   platform itself via `readBuilderSkill` — always current, never duplicated here:
-   - `solution-design` — read FIRST on any new goal
-   - `workflow-building` — the build protocol + response-field semantics
-   - `workflow-testing` — runTest / stepNode / reading traces
-   - `template-references` — the `{{...}}` grammar + fixing lint errors
+   platform itself via `readBuilderSkill`, always current, never duplicated here:
+   - `solution-design`: read FIRST on any new goal
+   - `workflow-building`: the build protocol + response-field semantics
+   - `workflow-testing`: runTest / stepNode / reading traces
+   - `template-references`: the `{{...}}` grammar + fixing lint errors
 3. **Build ONE stage at a time.** The loop is: `saveWorkflow` one stage → `runTest`
    → read the trace → add the next stage based on that evidence. Never design or
-   pre-wire the whole graph up front — you learn a node's real output fields by
+   pre-wire the whole graph up front. You learn a node's real output fields by
    running it, not by planning.
 4. **Ground truth rules:** `getCanvas` is the real graph; a nodeType is valid only
    if `getNodeCatalog` returned it (search it fresh per step, with a one-line
    `task`); layout and node ids are not yours to set.
-5. **The developer judges the result — never self-certify.** When the workflow runs
+5. **The developer judges the result. Never self-certify.** When the workflow runs
    end-to-end with real, non-empty output, report what you built and what the test
    showed. They watch the canvas live and accept, or ask for changes (which continue
    on the same bound canvas).
@@ -47,6 +47,6 @@ in the developer's browser as you build.
 | Symptom | Cause / fix |
 |---|---|
 | Every tool returns "No workflow bound" | Call `bindWorkflow` with the pairing code from Canvas "Connect agent" |
-| Bind fails "invalid or expired pairing code" | Codes are single-use + 10-min TTL — ask the developer to click "Connect agent" again for a fresh one |
-| Tool calls error after working earlier | The platform restarted mid-session — `/mcp` → reconnect |
-| saveWorkflow rejects an edge into an existing node | Provenance guard: that node wasn't built this session — build on a fresh workflow, or recreate the stage yourself |
+| Bind fails "invalid or expired pairing code" | Codes are single-use + 10-min TTL: ask the developer to click "Connect agent" again for a fresh one |
+| Tool calls error after working earlier | The platform restarted mid-session: `/mcp` → reconnect |
+| saveWorkflow rejects an edge into an existing node | Provenance guard: that node wasn't built this session. Build on a fresh workflow, or recreate the stage yourself |