@unoverse-platform/studio 0.1.26 → 0.1.28

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

@@ -1,116 +1,186 @@
-# Playbook — Components & Atoms (rx data)
+# Playbook: Components & Atoms (rx data)
 
 **Read first:** `docs/design/components.md` (the microapp anatomy) + `docs/design/state.md`
-(the reaction contract). Deep law: [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3 (three homes),
-`UNOVERSE_STATE_MODEL.md` §5b. **Study the exemplars before writing**: `rx/components/journeyfinder`
-and cardfinder — mirror them exactly.
+(the state model). Deep law: [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3 (three homes),
+`UNOVERSE_STATE_MODEL.md` §5 (the six rules), `UNOVERSE_LAYERS.md` (states own layouts).
+**Study the exemplar before writing**: `rx/sab/components/product-card` is the canonical
+State Model v2 component; mirror it exactly.
 
 ## The anatomy
 
 ```
-apps/unoverse/rx/components/<name>/            # DESIGN SYSTEM tier (generic, universal)
-apps/unoverse/rx/orgs/<org>/components/<name>/ # ORG tier (the client's own microapp, org-private)
-  <name>.json      # envelope: name/category/nodeSize/outputs/props/state/stateOrder/root
-  manifest.json    # RENDER CONTRACT: arrival defaultState (open name, default "inline")
-                   #   + discovery meta (title / description ≤120 / whenToUse utterance-shaped).
-                   #   Presence = spatially discoverable; envelope NEVER duplicates the meta.
-  layouts/         # the FACES — filename = state name: inline.json, focused.json, (custom).json
-  states/          # the component's PRIVATE steps (wizard questions) — listed in stateOrder
-  components/      # component-local shared partials (earned: 2+ states share a shape)
+apps/unoverse/rx/<project>/components/<name>/
+  <name>.yaml      # ROOT: envelope (name/category/nodeSize/outputs/props) + the STATE TREE + root
+  manifest.yaml    # RENDER CONTRACT + discovery meta (title / description ≤120 /
+                   #   whenToUse utterance-shaped). Presence = spatially discoverable;
+                   #   the envelope NEVER duplicates the meta.
+  layouts/         # the DRAWINGS: one file per state that owns an arrangement
+  components/      # component-local shared partials (earned: 2+ layouts share a shape)
 ```
 
-A **flat component** (simple card/chart) is just `<name>.json` + `root` — one face, no manifest,
-no folders. Structure is EARNED; start flat.
+A **flat component** (simple card/chart) is just `<name>.yaml` + `root`: one drawing, no
+manifest, no folders. Structure is EARNED; start flat.
 
-## The rules (Studio's publish lint enforces all of these — 0 errors required)
+## The state model (v2): data + a state tree
+
+A component is **data plus a state tree**; each state owns the layout(s) that draw it.
+The root's `state:` block IS the design, readable top to bottom. The canonical shape
+(`rx/sab/components/product-card/product-card.yaml`):
+
+```yaml
+state:
+  view:                      # the PUBLIC axis
+    initial: products
+    states:
+      products: {}                          # no layout key: same-name default, {} is complete
+      detail:                               # the full page
+        layout: product                     # declared ONLY because the filename differs
+        on: step                            # a PRIVATE axis: the steps inside detail
+        initial: detail
+        states:
+          detail: { layout: product-detail }
+          apply:  { layout: product-apply }
+root:
+  type: Box
+  children:
+    - type: Switch
+      on: view                              # the root switches on `view`, ONE case active
+      cases:
+        products: { $include: layouts/products }
+        detail:   { $include: layouts/product }
+```
+
+The rules, in the order they bite:
+
+- **The axis is `view`.** The component's public state lives in its slice under `view`.
+  The root is a `Switch on view`; buttons transition with
+  `setValue { values: [{ key: view, value: detail }] }`. That write is the ENTIRE
+  transition machinery: no guards, no events, no per-component machines.
+- **Public states are the top level of the `view` axis** and they are the template's
+  WHOLE vocabulary: everything templates can react to, nothing more. Steps nest
+  privately (`on: <key>` + `initial` + `states`), invisible outside the component.
+  The placement rule: **if the template must rearrange to show it, make it public;
+  if the template wouldn't move, nest it privately.** Privacy is the default;
+  promotion is deliberate.
+- **Each state owns its layout(s).** `layout:` is OPTIONAL: a state with no declaration
+  draws the layout of its own name, and `{}` is a complete state. Write `layout:` only
+  when the filename differs. A layout is never addressable on its own; only its owning
+  state selects it. Name states for what they MEAN (`detail`), never for their drawing.
+- **Shell vs steps.** A state's own layout is its SHELL, always on while the state is
+  active. Its nested substates are the STEPS, the only choices inside it, addressed by
+  state names (layout filenames are plumbing).
+- **Variants**: one meaning, several arrangements:
+  `focused: { layouts: { horizontal: focused-h, vertical: focused-v } }`. Variants bind
+  the SAME fields; anything that changes meaning or bound data is a second state
+  (lint-enforced). The component picks its variant by the space it finds itself in
+  (container queries); templates influence it only by controlling the container.
+- **Arrival: nobody sends a state.** The host template places the spawned actor: it
+  honors the component's declared `initial` when it has a matching state; otherwise it
+  scans its own states in declared order and takes the first name on the component's
+  public menu; no overlap and the component wakes in its own initial chain and renders
+  inline. The server compiles the tree to the public menu + initials it serves
+  (`publicStates`, `initialView`). Post-spawn, the template NEVER writes a component's
+  state.
+- **Unmatched view = inline. Always.** An ignored public state does not stay put, it
+  FALLS INLINE in the flow. A step that must never move the page belongs in the nest,
+  not on the public menu.
+- Legacy: v1's `defaultState` field and layout-name-sync are superseded; the SDK reads
+  `defaultState` only as a migration alias for `view`. New authoring writes `view`.
+
+## The rules (Studio's publish lint enforces all of these; 0 errors required)
 
 1. **Three homes for everything it shows** (AUTHORING §3):
    - static content → **hardcoded literals** in the layout (`value`, literal `items: []` on
-     Each, `src`) — never props, never `state`;
+     Each, `src`), never props, never `state`;
    - internal view-state → the **`state` block, SCALARS ONLY** (`step`, `phase`,
-     `progressPct`) — an array/object/URL in `state` is slop (workflow data → props;
+     `progressPct`): an array/object/URL in `state` is slop (workflow data → props;
      static → hardcode);
    - workflow-fed data → **`props` with `input: true`** (the `default` is the preview mock).
      Usually empty.
-   - **Prop names = the data contract — never invent them.** Source data hydrates props
+   - **Prop names = the data contract. Never invent them.** Source data hydrates props
      BY NAME (as-is, no mapping); a name the source doesn't carry silently renders the
      preview default (tell: title streams, image stays mock). Content-attached cards use
      the writer vocabulary: `title` `tagline` `description` `bodyCopy` `introParagraph`
      `primaryImage` `images` `link` `callToAction`. Guard:
      `server/src/runtime/content-card-hydration.test.ts`; law:
      `UNOVERSE_MCP_TEMPLATE_PROTOCOL.md` §Content-attached cards.
-2. **Root = `Switch on defaultState`** — the component is a switch of **views**, ONE active.
-   Cases `$include layouts/<state>` (filename = view name); `default` → the inline layout.
-   Arrival view = **manifest.defaultState**. Keep an `inline` case for any component that
-   lives in a conversation flow — it is its placeholder there. EXCEPTION — the
-   **single-face (permanent) component**: exactly ONE named view + `default` pointing at
-   the SAME face, NO inline. It arrives in its surface, cannot leave it (no ✕, no other
-   view), and is enriched in place via data merges to one stable instance — e.g. a
-   continuously-updated page living in a template's focus surface. Permanence is by
-   construction, never by a pinning rule.
-   **Lifetime (OPTIONAL manifest flag)** — `"lifetime": "conversation"` marks a durable,
+2. **Root = `Switch on view`**, cases per PUBLIC state, each `$include` of the state's
+   layout (the tree above). Keep an `inline` state for any component that lives in a
+   conversation flow: the flow is its placeholder there. One EXCEPTION is the
+   **single-state (permanent) component**: exactly ONE public state, NO inline. It
+   arrives in its surface, cannot leave it (no ✕, no other state), and is enriched in
+   place via data merges to one stable instance, e.g. a continuously-updated page
+   living in a template's focus state. Permanence is by construction, never by a
+   pinning rule.
+   **Lifetime (OPTIONAL manifest flag).** `"lifetime": "conversation"` marks a durable,
    conversation-scoped surface (a cart, an itinerary, a composed page): the platform keys
-   its instance by the CONVERSATION (every re-call hydrates the SAME slice — merge, not
+   its instance by the CONVERSATION (every re-call hydrates the SAME slice: merge, not
    re-place) and the new-turn reset skips it, so it stays on screen until it is replaced,
    closes itself, or a NEW TEMPLATE loads (the template swap is the hard refresh boundary).
-   Default `"turn"`: the instance returns to inline / retires on the next user turn.
-   Values are a closed set — `turn | conversation` (lint-checked; docs/design/04).
-3. **State is local; the VIEW is the interface** (STATE_MODEL §5b). Internal `state`
-   (`step`, `phase`, …) is the component's own business — the template never sees it. The
-   only thing that crosses to the template is the **active view** (`defaultState`). The
-   component writes ONLY its own slice (`setValue`): expand = `setValue { defaultState:
-   "course" }`; its expanded face carries its own ✕ back to `"inline"`. When a template has
-   a surface for that view, the instance **lifts out of the flow into the surface** — the
-   SDK renders each instance in exactly ONE placeholder, so you never hide a flow copy
-   yourself (no `hideBelow`, no overlay hack). ❌ NEVER `setTemplateValue` to open a surface
-   (the deprecated bridge — linted).
-4. **`stateOrder`** names exactly the `states/*.json` files, in order.
-5. **Atoms** (`rx/atoms/`, via `Ref`) are for shapes shared across components — authoring-time
+   Durable slices also opt out of `cancelBelow` retraction when a higher template state
+   takes over. Default `"turn"`: the instance returns to inline / retires on the next
+   user turn. Values are a closed set: `turn | conversation` (lint-checked; docs/design/04).
+3. **State is local; the `view` is the interface** (STATE_MODEL §5). Private axes
+   (`step`, `phase`, …) are the component's own business; the template never sees them.
+   The only thing that crosses is the public `view`. The component writes ONLY its own
+   slice (`setValue`): expand = `setValue { view: "detail" }`; its expanded layout
+   carries its own ✕ back down. When a hosting template has a state of that name, the
+   instance **lifts out of the flow into that state's slot**. The SDK renders each
+   instance in exactly ONE placeholder, so you never hide a flow copy yourself (no
+   `hideBelow`, no overlay hack). ❌ NEVER `setTemplateValue` to open a surface
+   (the deprecated bridge, linted). ❌ Never guard a layout against its own state:
+   the tree owns "which state is active"; a layout re-checking its discriminant is
+   the double-guard smell the model removes.
+4. **A new layout file is earned only by a different arrangement** (or a different set
+   of bound fields). Same shape, different values = ONE state, data-driven: seven wizard
+   questions sharing one shape are one `question` state whose data changes, never seven
+   files (LAYERS §4, §7).
+5. **Atoms** (`rx/atoms/`, via `Ref`) are for shapes shared across components, authoring-time
    only (the server expands them before serving; no Studio view). `Ref props` remaps FIELDS;
    **`Ref with` passes LITERALS**: `{ "type": "Ref", "ref": "button", "with": { "label":
-   "Learn more", "icon": "arrowRight" }, "action": { … } }` — a bind whose field is a `with`
+   "Learn more", "icon": "arrowRight" }, "action": { … } }`. A bind whose field is a `with`
    key becomes a hardcoded attribute, a truthy `with` key drops a matching `visibleWhen`
    guard (unprovided ⇒ that piece stays hidden), `{{key}}` style bindings take the value.
    ⚠ Icon: literal = `icon: "phone"`; bound = `bind: { name: field }`.
-6. **Briefs — components an AI fills** (docs/design/03 §Briefed components; deep law: [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3b). A `brief`
-   sits ON the node that renders what it describes, next to its `bind` — never in the
+6. **Briefs: components an AI fills** (docs/design/03 §Briefed components; deep law: [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3b). A `brief`
+   sits ON the node that renders what it describes, next to its `bind`, never in the
    manifest, never a separate file:
    - bound element → `"brief": { "description": "…", "maxLength": 60 }`
    - Each → `"brief": { "description": "…", "minItems": 3, "maxItems": 5 }` (its template's
-     binds define the item shape — brief those fields too)
-   - face/partial ROOT (no bind) → a plain-string brief = composition context
+     binds define the item shape; brief those fields too)
+   - layout/partial ROOT (no bind) → a plain-string brief = composition context
      (ordering, refinement rules like "update, never discard").
    The platform compiles briefs into the component's MCP tool schema (keys pass through
-   verbatim — the brief uses JSON Schema's OWN vocabulary) and injects the grounding law (fill ONLY from
-   spatial search results — never invent). The server REFEREES (invalid/empty args →
+   verbatim; the brief uses JSON Schema's OWN vocabulary) and injects the grounding law (fill ONLY from
+   spatial search results, never invent). The server REFEREES (invalid/empty args →
    instructive result, no render) and MIRRORS (success result returns the rendered page
-   for surgical refinement). **The schema IS the instruction channel** —
-   write briefs, never side-channel prompts/skills for filling a component. Shape is
-   closed + linted. Pairs with the single-face permanent pattern (rule 2) for
+   for surgical refinement). **The schema IS the instruction channel.**
+   Write briefs, never side-channel prompts/skills for filling a component. Shape is
+   closed + linted. Pairs with the single-state permanent pattern (rule 2) for
    continuously-enriched pages; exemplar: `rx/components/perfectday`.
 7. **Tokens only** (LAW 1) + closed style keys + real space-scale steps
-   (`docs/design/06`) — an invented step is silently broken CSS.
-8. **Lifecycle handlers — a component's own server-side code** (deep law:
+   (`docs/design/06`): an invented step is silently broken CSS.
+8. **Lifecycle handlers: a component's own server-side code** (deep law:
    [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3c). When a component needs live data from an
    API or a computation (not from an AI = brief, not from the workflow = `input` props), it
    may bring a small server-side script that runs when the component renders. It's for DATA,
    not styling or logic-in-the-def.
    - **Opt in via the manifest** (authorizes execution; auditable): `"lifecycle":
-     ["onStart"]` in `manifest.json`. A handler file with no opt-in is INERT.
-   - **The code is a sibling file named for the lifecycle** — `onStart` → `onstart.js`,
-     beside `<name>.json`. Its **default export** is the handler.
+     ["onStart"]` in the manifest. A handler file with no opt-in is INERT.
+   - **The code is a sibling file named for the lifecycle**: `onStart` → `onstart.js`,
+     beside the root file. Its **default export** is the handler.
    - **`onStart`** is the only lifecycle today; it runs SERVER-SIDE when the instance is
      created (the MCP render path), and whatever it returns is **merged into the instance
-     by prop name** (unknown keys inert — same contract as workflow-fed props). Return only
+     by prop name** (unknown keys inert, same contract as workflow-fed props). Return only
      the fields you're filling; **never overwrite a curated prop** you didn't intend to.
    - **`ctx` is a bounded sandbox**: `ctx.props` (the instance's current data),
      `ctx.instanceId`, `ctx.env(name)` (server config). The **API key comes from
-     `ctx.env`, NEVER hardcoded** — `rx/` is a shared design folder; a secret in it leaks.
+     `ctx.env`, NEVER hardcoded**: `rx/` is a shared design folder; a secret in it leaks.
    - Self-contained (the external call lives in the handler); errors never break the render.
-   Exemplar: `rx/orgs/yasisland/components/restaurantcard/onstart.js` (Google Maps details).
+   Exemplar: `rx/yasisland/components/restaurantcard/onstart.js` (Google Maps details).
 
    ```js
-   // onstart.js — manifest opts in with "lifecycle": ["onStart"]
+   // onstart.js: manifest opts in with "lifecycle": ["onStart"]
    export default async function onStart(ctx) {
      const key = ctx.env("SEARCHAPI_KEY");                 // secret from server config
      const res = await fetch(`https://…&q=${encodeURIComponent(ctx.props.title)}&api_key=${key}`);
@@ -119,34 +189,39 @@ no folders. Structure is EARNED; start flat.
    }
    ```
 
-## Discovery meta — write it to RANK (docs/nodes/node-discoverability.md)
+## Discovery meta: write it to RANK (docs/nodes/node-discoverability.md)
 
 A component with a manifest is an **MCP app**: spatial embeds `` `title. whenToUse||description
 [category]` `` and ranks it against the USER'S OWN WORDS (`findIntent`). The meta is the
-selection text, not documentation — weak meta makes a working component invisible. The
+selection text, not documentation. Weak meta makes a working component invisible. The
 strict contract (doc 14, applies verbatim):
 
-- **`title`** = the thing itself, human display name — no mechanism, no org prefix.
-- **`description`** = what it IS, ONE line ≤120 chars — the listing subtitle; never
+- **`title`** = the thing itself, human display name, no mechanism, no org prefix.
+- **`description`** = what it IS, ONE line ≤120 chars, the listing subtitle; never
   "use when…" inside it.
 - **`whenToUse`** = the selection text, **utterance-shaped**: the words a user would
-  actually say, outcome first — the OPENING words dominate the embedding. Never
+  actually say, outcome first; the OPENING words dominate the embedding. Never
   selector-shaped dev framing ("Pick when the user asks…"), never layout/mechanism first
-  ("A single-face page that…" ranks near rendering concepts and loses every intent query).
+  ("A single-state page that…" ranks near rendering concepts and loses every intent query).
 - **Disqualify by PROPERTY, never by naming a sibling** ("Not for answering a single
-  question, not for one item on its own") — naming rivals dates and tangles; the ranking
+  question, not for one item on its own"). Naming rivals dates and tangles; the ranking
   surfaces the alternative. A fallback/home surface never enumerates siblings' jobs
   (the generalist trap).
 - **`category`** = the domain of the JOB (Travel, Payments…), not the implementation.
 - Meta embeds **AS-IS** (no LLM rewrite); editing `whenToUse` re-embeds on the next train.
 
 Self-test before shipping: write the sentence the user would actually say to want this
-component — its key nouns/verbs must appear in `whenToUse`'s first sentence.
+component. Its key nouns/verbs must appear in `whenToUse`'s first sentence.
 
 ## Workflow
 
-1. Study the closest exemplar; copy its folder shape.
-2. Write the envelope + manifest + layouts; put every shown thing in its ONE home.
-3. Publish from Studio — its lint must report 0 errors (it cites the doc for every rule).
-4. Restart unoverse → Studio: mock (prop defaults + state picker + Inline/Focused
-   toggle), then live. Debug: stream log → state inspector → definition; never guess.
+1. Study `rx/sab/components/product-card`; copy its folder shape.
+2. Declare the state tree first: public states on top, steps nested, each state owning
+   its layout (same-name default, `layout:` only when the filename differs).
+3. Write the envelope + manifest + layouts; root = `Switch on view`; every shown thing
+   in its ONE home; transitions are `setValue` writes to `view` (or a private axis).
+4. Publish from Studio; its lint must report 0 errors (the rules are v2-aware and cite
+   the doc for every rule).
+5. Restart unoverse → Studio: mock (prop defaults + the state switcher reads the tree:
+   public states on top, steps beneath by state name), then live. Debug: stream log →
+   state inspector → definition; never guess.

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

@@ -161,7 +161,7 @@ the manifest describes the real service rather than something merely coherent.
   returns: "return response.items.map(helpers.row)"
   ```
 
-  A helper sees ONLY its arguments and its sibling helpers — never `config`, `credentials`
+  A helper sees ONLY its arguments and its sibling helpers, never `config`, `credentials`
   or the caller's scope. Same sandbox, no extra authority.
 
 ## Do not

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.