@unoverse-platform/studio 0.1.85 → 0.1.87

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

@@ -16,10 +16,11 @@ folder shape. (In the platform monorepo the richest multi-state exemplar is on d
 
 ```
 design/<project>/components/<name>/
-  <name>.yaml      # ROOT: envelope (name/category/nodeSize/outputs/props) + the STATE TREE + root
+  <name>.yaml      # the envelope: name/category/nodeSize/outputs/props + `states:` + `values:` (root only as a real shell)
   manifest.yaml    # RENDER CONTRACT + discovery meta (title / description ≤120 /
-                   #   whenToUse utterance-shaped). Presence = spatially discoverable;
-                   #   the envelope NEVER duplicates the meta.
+                   #   whenToUse utterance-shaped). REQUIRED on every artifact EXCEPT
+                   #   a flat file nothing discovers (2026-08-30); 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)
 ```
@@ -32,14 +33,14 @@ manifest, no folders. Structure is EARNED; start flat.
 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 GATE — answer this before adding ANY state to `view`:**
+> **THE GATE, answer this before adding ANY state to the tree:**
 > *"Would a hosting app rearrange the page to show this?"*
 > **No → it's a private step**: nest it under `on:` inside an existing public state.
 > **Yes → public.**
 > ⚠ "The user asked for N states" never means N public states. In-place swaps
 > (confirmation, success, empty, error, loading, a form's next step) are almost always
-> PRIVATE. Privacy is the default; promotion to `view` is a deliberate act with a
-> app consequence.
+> PRIVATE. Privacy is the default; promotion to a PUBLIC state is a deliberate act
+> with an app consequence.
 
 The canonical shape (a product-card component). Note where each state landed and why:
 `products` and `detail` are PUBLIC because an app genuinely rearranges for each (a
@@ -47,35 +48,30 @@ grid rail vs a full page); `detail`'s inner `detail`/`apply` are PRIVATE steps b
 applying swaps content in place — the page does not move:
 
 ```yaml
-state:
-  view:                      # the PUBLIC axis
-    initial: products
+states:                      # TOP LEVEL (2026-08-29), like every kind; the word is
+  products:                  #   `state` everywhere (setValue/Switch on/select field)
+    layout: layouts/products            # REQUIRED path: nothing assumed
+  detail:                               # the full page
+    layout: layouts/product
+    on: step                            # a PRIVATE axis: the steps inside detail
     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 }
+      detail: { layout: layouts/product-detail }
+      apply:  { layout: layouts/product-apply }
+values:                      # STARTING VALUES of keys the component writes (scalars)
+  progressPct: 10%
 ```
 
+**No `root`**: the compiler synthesizes the `Switch on state` from the tree. Author
+a root ONLY as a real shell (chrome beyond the plain Switch); a restated Switch is
+linted as redundant.
+
 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
+- **The word is `state`** (ruled 2026-08-29). The component's public state lives in
+  its slice under `state`. The root is a `Switch on state`; buttons transition with
+  `setValue { values: [{ key: state, 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 app's
+- **Public states are the top level of `states:`** and they are the app's
   WHOLE vocabulary: everything apps can react to, nothing more. Steps nest
   privately (`on: <key>` + `initial` + `states`), invisible outside the component.
   The placement rule is THE GATE above: **if the app must rearrange to show it,
@@ -84,11 +80,11 @@ The rules, in the order they bite:
   **The tell in Studio:** non-initial public states preview FULL-BLEED (no stage
   padding), precisely because they are app-liftable surfaces. If a state you
   meant as an in-place swap suddenly renders edge-to-edge, you promoted a private
-  step to `view` — move it into the nest.
-- **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. **Substate drawings are axis-prefixed**: a step's file carries its axis key
+  step to the public menu — move it into the nest.
+- **Each state owns its layout(s), DECLARED as a path** (`layout: layouts/<file>`,
+  REQUIRED — 2026-08-29; no same-name default, `{}` is not complete; the one
+  exception is a FLAT component with no layouts/ folder). 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. **Substate drawings are axis-prefixed**: a step's file carries its axis key
   (`step-register`, `callState-idle`) and is declared via `layout:`; unprefixed
   files are arrangements (exemplars: `course-application`, `voice-chat`).
 - **Shell vs steps.** A state's own layout is its SHELL, always on while the state is
@@ -106,20 +102,20 @@ The rules, in the order they bite:
   inline. The server compiles the tree to the public menu + initials it serves
   (`publicStates`, `initialView`). Post-spawn, the app NEVER writes a component's
   state.
-- **Unmatched view = inline. Always.** An ignored public state does not stay put, it
+- **Unmatched state = 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`.
+- Legacy: `view` (the v2 intermediate) and v1's `defaultState` are read-only
+  aliases; layout-name-sync is superseded. New authoring writes `state`.
 
 ## 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`;
-   - internal view-state → the **`state` block, SCALARS ONLY** (`step`, `phase`,
-     `progressPct`): an array/object/URL in `state` is slop (workflow data → props;
-     static → hardcode);
+   - starting values of keys it writes → the **`values:` block, SCALARS ONLY**
+     (`step`, `phase`, `progressPct`; `state:` scalars = legacy): an array/object/URL
+     there is slop (workflow data → props; static → hardcode);
    - workflow-fed data → **`props` with `input: true`** (the `default` is the preview mock).
      Usually empty.
    - **Projected-field preview rule:** any LOCKED/projected field a
@@ -127,7 +123,7 @@ The rules, in the order they bite:
      a prop with a preview default: Studio's bare component preview supplies ONLY prop
      defaults, so an undeclared projected read renders NOTHING there; live, the projected
      value wins and the default never applies. A Ref-embedded component's root Switch
-     likewise needs a `default:` case (`view` is absent without a spawned slice).
+     likewise needs a `default:` case (`state` is absent without a spawned slice).
    - **Who owns a mood: the DRIVER decides.** Ask what WRITES the discriminant:
      (1) the component's own buttons (`setValue`) → component substates on a private axis,
      names from the design (`course-application`); (2) a service projecting a NAMED value
@@ -143,12 +139,15 @@ The rules, in the order they bite:
    - **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`. Law:
+     the writer vocabulary, listed layer by layer in
+     [design/interface-data](https://docs.unoverse.ai/design/interface-data.md)
+     (`title` `tagline` `description` `bodyCopy` `primaryImage` `images` …). Law:
      `UNOVERSE_MCP_APP_PROTOCOL.md` §Content-attached cards (platform spec; a
      guard test in the platform server enforces it).
-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
+2. **NO root: the compiler synthesizes the `Switch on state`** from `states:` (the tree
+   above), so a hand-written root that merely restates the tree is lint-flagged as
+   redundant. Author a `root:` ONLY for real always-on chrome beyond that Switch.
+   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
@@ -164,14 +163,14 @@ The rules, in the order they bite:
    takes over. Default `"turn"`: the instance returns to inline / retires on the next
    user turn. Values are a closed set: `turn | conversation` (lint-checked;
    [design/components](https://docs.unoverse.ai/design/components.md)).
-3. **State is local; the `view` is the interface** (STATE_MODEL §5). Private axes
+3. **Private state is local; the public `state` is the interface** (STATE_MODEL §5). Private axes
    (`step`, `phase`, …) are the component's own business; the app 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
+   The only thing that crosses is the public `state`. The component writes ONLY its own
+   slice (`setValue`): expand = `setValue { state: "page" }`; its expanded layout
    carries its own ✕ back down. When a hosting app 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
+   `hideBelow`, no overlay hack). ❌ NEVER `setAppValue` 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.
@@ -182,7 +181,7 @@ The rules, in the order they bite:
 5. **Atoms** (the base design system's shared shapes, used via `Ref`; browse them at
    [marketplace/definitions/atoms](https://github.com/unoverse-platform/marketplace/tree/main/definitions/atoms), or on disk at `design/marketplace/atoms/` in the
    platform monorepo) are for shapes shared across components, authoring-time
-   only (the server expands them before serving; no Studio view). `Ref props` remaps FIELDS;
+   only (the server expands them before serving; no Studio entry). `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`
    key becomes a hardcoded attribute, a truthy `with` key drops a matching `visibleWhen`
@@ -225,7 +224,7 @@ The rules, in the order they bite:
      `onEnterView` only. Omit it and every state fires.
    - **Name the handler for what it DOES, never for the phase** (`fetchPlaceDetails`, not
      `onEnterView`): the phase already said the moment.
-   - **Nothing to wire up.** A component changing its own view writes `view`, and that
+   - **Nothing to wire up.** A component changing its own face writes `state`, and that
      write IS the event the hook reacts to. No signal to author, no action to chain.
    - **Prefer a platform-ready handler.** `getDetail` (zero code) reads the instance's
      `universal_id` and merges the stored record's fields in by name, so authored copy
@@ -311,9 +310,11 @@ component. Its key nouns/verbs must appear in `whenToUse`'s first sentence.
 1. Study the closest published exemplar ([marketplace/definitions/components](https://github.com/unoverse-platform/marketplace/tree/main/definitions/components);
    monorepo: `design/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).
+   its layout as a root-relative path (`layout: layouts/<file>`, required; a FLAT
+   component with no layouts/ folder declares face-only states with no layout).
+3. Write the envelope + manifest + layouts; the root is synthesized from `states:`; every
+   shown thing in its ONE home; transitions are `setValue` writes to `state` (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:

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

@@ -5,7 +5,9 @@
 1. [nodes/CLAUDE.md](https://docs.unoverse.ai/nodes/CLAUDE.md): the authoritative agent
    guide. The folder, the eight non-negotiable rules, every file with an example, and
    the lint-error-to-fix table.
-2. [nodes/manifest-nodes](https://docs.unoverse.ai/nodes/manifest-nodes.md): the format in full, including the run context.
+2. [nodes/manifest-nodes](https://docs.unoverse.ai/nodes/manifest-nodes.md): the format in full.
+   [nodes/expressions](https://docs.unoverse.ai/nodes/expressions.md) is the template and
+   expression grammar, the sandbox, and every root the run context carries.
 3. [nodes/node-discoverability](https://docs.unoverse.ai/nodes/node-discoverability.md): **read before writing `whenToUse`**.
 4. As needed: [credentials](https://docs.unoverse.ai/nodes/credentials.md),
    [who-can-run-it](https://docs.unoverse.ai/nodes/who-can-run-it.md),

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

@@ -0,0 +1,133 @@
+# Playbook: Templates
+
+**Read first:** [design/templates](https://docs.unoverse.ai/design/templates.md)
+(the three words, the director, placing one in an app). Deep law:
+[UNOVERSE_TEMPLATE_MODEL](https://docs.unoverse.ai/unoverse/UNOVERSE_TEMPLATE_MODEL.md)
+— §9b is the grammar (RULED 2026-08-29), §5b the fill lanes, §6c the director's
+twelve rules, §12 how a template is placed. Everything in the component playbook
+(closed vocabulary, tokens only, no logic in definitions) applies here too.
+**Study an exemplar before writing**: `design/marketplace/templates/grid-page`
+(two states, the free browse↔detail dance) and
+`design/marketplace/templates/email-digest` (one flat state, all three words,
+template-local components).
+
+## What a template IS
+
+| Kind | Authors say | Decides what appears |
+|---|---|---|
+| **component** | `type: component` | itself — one interface with its own states |
+| **template** | `type: template` | an ARRANGEMENT whose sections deliveries fill |
+| **app** | `type: app` (folder `apps/`) | the reader — the surface a template is placed on |
+
+## The file tree (one folder grammar)
+
+```
+design/<org|marketplace>/templates/<name>/
+  <name>.yaml          # the ENVELOPE: type + name + states (each → its layout path)
+  manifest.yaml        # discovery meta ONLY: description, whenToUse, category, version
+  layouts/<state>.yaml # one arrangement per state — the three-word sections
+  components/          # the template's OWN parts (§9b.7): flat files, no
+                       #   manifests, unprefixed (the folder is the namespace)
+```
+
+## The envelope: states, like every kind
+
+```yaml
+unoverse: "1.0"
+type: template
+name: grid-page
+states:
+  grid:                       # FIRST = the base
+    layout: layouts/grid
+  page:                       # the rest = the reaction ladder
+    layout: layouts/page
+```
+
+Use the standard names **`grid`** (compact collection) and **`page`** (full detail):
+every card in every org declares them, so any card matches any template with zero
+mapping. Browse and detail are ONE template — a card taps itself into `page`, the
+name-matched state draws, its ✕ writes it back. RETIRED spellings (legacy-read, never
+author): `parts`, `shapes`, `slots`, `accepts`, `prompt: {component}`, root `director:`.
+
+## The layout: three words, each says HOW a section fills
+
+```yaml
+type: Box
+children:
+  - static: components/masthead        # placed as designed — nothing writes into it
+  - copywriter: components/subject     # written into through its briefs (must carry briefs)
+  - copywriter: components/body
+  - director:                          # NOT linked: decided from what streams in
+      state: grid                      # arrivals SWITCHED into this state and HELD (flat email);
+      limit: 3                         #   omit to let them keep their own (grid↔page dance)
+      rules: >-                        # ONE home: this section. Marketplace = universal wording;
+        The items most relevant to the reader, strongest matches first.
+      preview: [ card, card, card ]    # Studio's stand-ins until a real run
+  - copywriter: components/signoff
+  - static: components/footer
+```
+
+- **Link what you know; leave open what the delivery decides.** Never name a
+  component in the director section — the delivery decides what arrives (any org's
+  cards), and a universal template may carry no client words.
+- **ONE `director:` per template.** Two directed regions = two templates, composed
+  by the app (the one-mind boundary, law 9.4).
+- **Never author `ComponentSlot`/`select`/`where` in a template** — the three words
+  compile to the wire primitives at serve time; the SDK stays dumb.
+- Linked parts preview THEMSELVES (their mock content lives in the component, once);
+  `preview:` exists only on the director section.
+- `limit` is the hard cap, machine-enforced; `rules` are soft, brief-style English.
+- **One home for the director's brain: its section.** Marketplace templates ship
+  UNIVERSAL rules (the reader's relevance — never client words); an org wanting
+  bespoke judgment ships its own template. No placement grant.
+
+## Template-local components
+
+Parts that exist only for this template live in its `components/` folder as FLAT
+FILES (`components/masthead.yaml`), unprefixed, with NO manifest — a manifest is
+discovery, and a local part is never discovered — and NO state tree: the face IS
+the filename (`body.yaml` → face `body`), so a one-face part is just props + root. Each is a REAL component (own face
+named for itself; briefed ones compile into the copywriter's MCP tool schema).
+Addressed `<template>/<part>` (`email-digest/masthead`) when a global ref is needed.
+Genuinely universal pieces (`card`) stay in the marketplace.
+
+## `manifest.yaml`
+
+```yaml
+description: "What it is, for a human."
+whenToUse: "Ranked against user intent — outcome-first, in the reader's words."
+category: Communication
+version: 1.0.0
+```
+
+Nothing else. `whenToUse` is embedded and ranked, not read — follow
+[node-discoverability](https://docs.unoverse.ai/nodes/node-discoverability.md).
+Quote any string containing `: ` (a bare colon is a YAML parse error, and per-entry
+isolation makes the template silently vanish from the catalogue).
+
+## Placement: how a template gets used (§12)
+
+The template does not name its app; the app places it. In the app state's layout:
+
+```yaml
+- type: Template
+  name: courses          # the app state this place belongs to
+  template: grid-page    # WHAT it holds
+  appWidth: flex         # a place declares its width ONCE
+```
+
+The placement JUST PLACES — the director's rules live in the template (one home).
+An org wanting bespoke judgment ships its own template. (The placement `director:`
+grant is RETIRED; the live BPP mount's grant migrates.)
+
+Empty collapses: a place holding nothing draws nothing, frame included.
+
+## Before you're done
+
+- [ ] `type: template`, kebab-case name matching the folder; `states:` with explicit layout paths
+- [ ] Every layout section is one of the three words; exactly ONE `director:` in the template
+- [ ] No client words, no component names in the director section, no retired spellings
+- [ ] Copywriter sections link components that actually carry briefs
+- [ ] Template-only parts live in `components/`, unprefixed
+- [ ] `manifest.yaml`: description, whenToUse, category, version — nothing else
+- [ ] Tokens only; previewed in Studio's **Templates** screen at multiple widths