@unoverse-platform/studio 0.1.85 → 0.1.86

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