@unoverse-platform/studio 0.1.39 → 0.1.40

package/local/scaffold.mjs

@@ -13,7 +13,7 @@
  *
  * See docs/architecture/LOCAL_STUDIO.md.
  */
-import { existsSync, mkdirSync, writeFileSync, cpSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -83,15 +83,23 @@ export function createFirstProject(home, name) {
   const root = createProject(home, name);
   for (const d of ["prompts/skills", "prompts/blocks", "nodes"]) mkdirSync(join(home, d), { recursive: true });
 
-  // The Claude Code authoring skill, so "open the folder and describe what you want"
+  // The Claude Code authoring skills, so "open the folder and describe what you want"
   // works in every Studio project from its first minute. Vendored into the published
   // app (vendor/skills, written by prepack); read from the repo when running as source.
+  //
+  // ALL of them. One Studio project is where a person designs a brand AND writes the node
+  // behind it, so they need the whole set: naming one skill here shipped the authoring
+  // playbooks and silently withheld the rest.
   const app = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-  const skill = [join(app, "vendor/skills/unoverse-create"), resolve(app, "../../.claude/skills/unoverse-create")]
-    .find((d) => existsSync(d));
-  if (skill) {
-    mkdirSync(join(home, ".claude/skills"), { recursive: true });
-    cpSync(skill, join(home, ".claude/skills/unoverse-create"), { recursive: true });
+  const skillsDir = [join(app, "vendor/skills"), resolve(app, "../../.claude/skills")].find((d) => existsSync(d));
+  if (skillsDir) {
+    const names = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && existsSync(join(skillsDir, e.name, "SKILL.md")))
+      .map((e) => e.name);
+    if (names.length) mkdirSync(join(home, ".claude/skills"), { recursive: true });
+    for (const name of names) {
+      cpSync(join(skillsDir, name), join(home, ".claude/skills", name), { recursive: true });
+    }
   }
   return root;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/vendor/sdk/lib/style.ts

@@ -72,13 +72,21 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
     }
   }
   const css: CSSProperties = {};
-  const space = (v: string) => theme.space[v] ?? v;
+  // EVERY bucket read below is optional-chained (`theme.x?.[k] ?? k`), never `theme.x[k]`.
+  // A bucket is absent whenever the theme was built by an OLDER base than the SDK reading
+  // it — a version skew that is normal for an installed Studio or a served app, since the
+  // two ship separately. Without the guard the first element using that vocab throws inside
+  // render, React unmounts the tree, and the whole surface goes blank; with it the unknown
+  // word reaches CSS, CSS drops the declaration, and the element keeps what it inherited.
+  // That silent degrade is the behaviour this file already documents for an unknown TOKEN
+  // (see `weight` below) — a missing BUCKET is the same situation and must not be worse.
+  const space = (v: string) => theme.space?.[v] ?? v;
   // Resolve a dimension: a `space.*` scale step (e.g. "8" → 2rem) → its value; `full` → 100%;
   // else pass through. ONE scale for spacing AND element sizes (Tailwind-style w-5/p-5).
   // A dimension is a scale step ("8") OR a named PAGE WIDTH ("reading"). Both live on
   // the same scale — `layout.*` are aliases onto it — so one lookup order covers both.
   const dim = (v: unknown) =>
-    theme.space[v as string] ?? theme.layout?.[v as string] ?? (v === "full" ? "100%" : (v as CSSProperties["width"]));
+    theme.space?.[v as string] ?? theme.layout?.[v as string] ?? (v === "full" ? "100%" : (v as CSSProperties["width"]));
 
   if (s.width != null) css.width = dim(s.width);
   if (s.height != null) css.height = dim(s.height);
@@ -140,7 +148,7 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
   if (s.textAlign) css.textAlign = (s.textAlign === "start" ? "left" : s.textAlign) as CSSProperties["textAlign"];
   // Generic transform passthrough (values are DATA, e.g. a hover lift) — the SDK maps, never authors.
   if (s.transform) css.transform = s.transform as CSSProperties["transform"];
-  if (s.background) css.background = theme.color[s.background as string] ?? (s.background as string);
+  if (s.background) css.background = theme.color?.[s.background as string] ?? (s.background as string);
   // `radial` — a neutral dial/gauge fill: a `fill` token sweeps from 0 to `at` (a value
   // or {{field}} binding, e.g. "72%"), the rest is the `track` token. The WEB realization
   // is a conic-gradient; a native channel maps the same neutral intent to an arc. Authors
@@ -148,7 +156,7 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
   // as DATA (a circular Box), not a primitive.
   if (s.radial) {
     const r = s.radial as { fill?: string; track?: string; at?: unknown };
-    const col = (t?: string) => (t ? (theme.color[t] ?? t) : "transparent");
+    const col = (t?: string) => (t ? (theme.color?.[t] ?? t) : "transparent");
     const at = r.at != null ? String(resolveValue(r.at, data ?? {})) : "0%";
     css.background = `conic-gradient(${col(r.fill)} ${at}, ${col(r.track)} 0)`;
   }
@@ -157,8 +165,8 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
   const borderVal = (raw: string) => {
     const parts = raw.split(" ");
     const [wTok, cTok] = parts.length > 1 ? parts : ["thin", parts[0]];
-    const width = theme.borderWidth[wTok] ?? wTok;
-    const color = theme.color[`border.${cTok}`] ?? theme.color[cTok] ?? cTok;
+    const width = theme.borderWidth?.[wTok] ?? wTok;
+    const color = theme.color?.[`border.${cTok}`] ?? theme.color?.[cTok] ?? cTok;
     return `${width} solid ${color}`;
   };
   if (s.border === "none") css.border = "none";
@@ -170,8 +178,8 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
   if (s.borderLeft) css.borderLeft = borderVal(s.borderLeft as string);
   // `outline` — pass-through (e.g. "none" to drop the input focus ring inside a pill).
   if (s.outline != null) css.outline = s.outline as CSSProperties["outline"];
-  if (s.shadow) css.boxShadow = theme.shadow[s.shadow as string] ?? (s.shadow as string);
-  const rad = (v: string) => theme.radius[v] ?? v;
+  if (s.shadow) css.boxShadow = theme.shadow?.[s.shadow as string] ?? (s.shadow as string);
+  const rad = (v: string) => theme.radius?.[v] ?? v;
   if (s.radius) css.borderRadius = rad(s.radius as string);
   // Per-corner radius (a chat bubble squares the corner toward its sender).
   if (s.radiusTopLeft) css.borderTopLeftRadius = rad(s.radiusTopLeft as string);
@@ -180,17 +188,17 @@ function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Rec
   if (s.radiusBottomRight) css.borderBottomRightRadius = rad(s.radiusBottomRight as string);
   if (s.overflow) css.overflow = s.overflow as CSSProperties["overflow"];
   if (s.fit) css.objectFit = s.fit as CSSProperties["objectFit"];
-  if (s.font && theme.text[s.font as string]) Object.assign(css, theme.text[s.font as string]);
+  if (s.font && theme.text?.[s.font as string]) Object.assign(css, theme.text[s.font as string]);
   // `weight` — a SERVED token like every other value here. This was the one scale the
   // SDK owned outright: a literal four-name map, which meant the foundation's own
   // `light`/`black` were unreachable and an org that added a weight to its tokens got
   // nothing at all (the unknown word reached CSS, CSS dropped the declaration, and the
   // text kept whatever it inherited — silently). A raw number still passes through.
-  if (s.weight) css.fontWeight = (theme.weight[s.weight as string] ?? s.weight) as CSSProperties["fontWeight"];
+  if (s.weight) css.fontWeight = (theme.weight?.[s.weight as string] ?? s.weight) as CSSProperties["fontWeight"];
   // `lineHeight` — override the text style's line-height (e.g. tighten a single-line
   // card title). Applied AFTER `font` so it wins. Resolves a lineHeight token (tight/…).
-  if (s.lineHeight != null) css.lineHeight = (theme.lineHeight[s.lineHeight as string] ?? s.lineHeight) as CSSProperties["lineHeight"];
-  if (s.color) css.color = theme.color[s.color as string] ?? (s.color as string);
+  if (s.lineHeight != null) css.lineHeight = (theme.lineHeight?.[s.lineHeight as string] ?? s.lineHeight) as CSSProperties["lineHeight"];
+  if (s.color) css.color = theme.color?.[s.color as string] ?? (s.color as string);
   // `transition` — smooth state changes (e.g. hover). The value is authored in the
   // definition (e.g. "all 150ms ease"); the SDK passes it through, authoring nothing.
   if (s.transition) css.transition = s.transition as CSSProperties["transition"];

package/vendor/skills/unoverse-create/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unoverse-create
-description: Create or edit Unoverse platform artifacts: UI components (including briefed/AI-filled components), templates, atoms and styles (rx/), agent skills and prompt blocks (prompts/), custom workflow nodes (nodes/), and workflows built live on the Canvas via the builder MCP. Use when the user wants to create, add, build, or modify a component, template, theme, agent skill, prompt block, custom node, or workflow in an Unoverse starter repo.
+description: Create or edit Unoverse platform artifacts: UI components (including briefed/AI-filled components), templates, atoms and styles (rx/), brand and org packs (themes, tokens, rebranding, cloning a universe for a new client), agent skills and prompt blocks (prompts/), custom workflow nodes (nodes/), and workflows built live on the Canvas via the builder MCP. Use when the user wants to create, add, build, or modify a component, template, theme, brand, org pack, agent skill, prompt block, custom node, or workflow in an Unoverse starter repo.
 ---
 
 # Creating Unoverse Artifacts
@@ -23,7 +23,8 @@ anything**:
 |---|---|
 | A UI component or shared atom, incl. a page/card the AI fills with content (briefed) | `references/component.md` (§Briefs for AI-filled) |
 | A template / app layout (chat surface, wizard shell) | `references/template.md` |
-| A style / theme / token change | `references/component.md` §Tokens |
+| A style / theme / token change on ONE component | `references/component.md` §Tokens |
+| A brand: an org pack, a rebrand, a new client universe, cloning an org | `references/brand.md` |
 | An agent skill (behavior guide the AI follows) | `references/agent-skill.md` |
 | A prompt block (reusable prompt fragment) | `references/block.md` |
 | A custom workflow node (integration, tool, logic) | `references/node.md` |

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

@@ -0,0 +1,158 @@
+# Playbook: Brand a universe (org packs, themes, cloning)
+
+Two jobs live here. **Restyling** an existing org, and **cloning** a universe for a new
+client. They share one discipline and one failure mode.
+
+> **The diagnostic that matters most.** If a rebrand seems to need a component edit, stop.
+> The component has a hardcoded value, and that is the real bug. Fix the component to read
+> a token; do not fork it per brand. A brand changes tokens. It never changes components.
+>
+> UNOVERSE_AUTHORING says the same about org components: they are for
+> "the client's finders/pages, **never a restyle of a shared component (that's the theme's
+> job)**."
+
+## 1. How overriding actually works: name a token to override, omit it to inherit
+
+`rx/marketplace/styles` is the **foundation**: the shared token contract every org
+inherits. Your org pack is read **on top** of it.
+
+The server builds a theme in three passes (`packages/base/src/definitions/theme.ts`,
+`buildTheme`):
+
+1. the foundation's `base/` then `semantic/`, into a flat registry keyed by dotted path
+2. **your org's `base/` then `semantic/`, over the top**
+3. your `themes/<name>.yaml` last
+
+Because it is one flat registry, the cascade is **per token, not per file**:
+
+> an org token overrides the foundation's and an org **OMITS** a token to inherit it
+
+That is the whole mechanism, and it has one practical consequence worth internalising:
+
+**You never copy a file to change one value in it.** To change the CTA outline, your
+`themes/light.yaml` names `border.accent` and nothing else in that group. The neighbouring
+`border.subtle` and `border.strong` keep coming from the foundation. Copying the whole
+`border` block to edit one line silently forks the other two, and they stop tracking
+foundation improvements forever.
+
+**Token NAMES are the shared contract; VALUES are yours.** Components reference names. That
+is how two clients get different fonts and colours from the same components without
+re-copying anything.
+
+> A bare theme name, or the `default` org, resolves to the foundation's own set.
+
+## 2. The health check: count the files
+
+| Pack | `styles/base/` holds |
+|---|---|
+| Foundation (`rx/marketplace/`) | `border` `color` `motion` `radius` `shadow` `spacing` `typography` |
+| A brand (`rx/bpp/`) | `color` `typography` **only** |
+
+BPP names two files and inherits the other five. That ratio is the health check: a pack
+redefining `spacing` or `radius` is not branding, it is forking. The neutral core is
+**never edited for a client**.
+
+## 3. Adding a new org
+
+An org is a folder. There is no registry to edit and nothing to declare.
+
+```
+rx/<neworg>/
+  styles/
+    base/color.yaml          brand INGREDIENTS (color.brand.*)
+    base/typography.yaml     font families only
+    themes/light.yaml        assign MEANING to those ingredients
+    themes/dark.yaml
+    themes/studio.yaml
+    semantic/*.yaml          deltas only, omit what matches the foundation
+  components/                org-private components (optional)
+  templates/                 the org's app layouts (optional)
+```
+
+**`base/` and `semantic/` cascade. The theme file does NOT.**
+
+`buildTheme` reads the foundation's `base` + `semantic`, then yours, then **one** theme
+file: your own. The foundation's `themes/light.yaml` is never read for your theme. So a
+theme file must assign **every** role the semantic layer aliases; one naming a single role
+fails to resolve at all, with `Unknown token alias: {color.action.primary}`.
+
+So start a theme by **copying the foundation's `themes/light.yaml`** and changing the roles
+you want. That is the one place copying is correct, and it is the opposite of the rule for
+`base/` and `semantic/`, where you copy nothing and name only what differs.
+
+Add `base/color.yaml` once you have brand ingredients to name, and `semantic/` only where
+you genuinely differ.
+
+Its theme is then served at `unoverse://theme/<neworg>/light`, and a template points at it.
+
+## 4. Anatomy of an org pack (`rx/<org>/styles/`)
+
+Read `rx/bpp/styles/` as the worked example. Every file there carries a `$description`
+explaining its own job, and those descriptions are the spec.
+
+| File | Holds | Rule |
+|---|---|---|
+| `base/color.yaml` | `color.brand.*` **ingredients** | Name by what it IS (`ink`, `cobalt`, `paper-warm`), never by where it is used |
+| `base/typography.yaml` | Font families only | Not sizes. The type scale is the core's |
+| `themes/light.yaml` `dark.yaml` `studio.yaml` | **Meaning**: `text.primary` → `{color.brand.ink}` | This is where a raw colour becomes a role |
+| `semantic/*.yaml` | Deltas only: `fonts` stylesheet URL, `prose` tone, `icons` additions, `app-sizes` | If it is not different from the core, leave it out |
+
+The two-tier split is the whole design. BPP's own `base/color.yaml` says it plainly:
+
+> lives in the BPP pack so the core token language stays neutral
+
+Ingredients in `base/`, meaning in `themes/`. A theme file that contains a hex value has
+skipped a tier.
+
+## 5. Extracting a real brand
+
+Take values from the live site's **computed styles or CSS custom properties**, not from a
+screenshot read by eye. A sampled screenshot gives you colours that are close and wrong,
+and "close and wrong" survives review.
+
+Where you must invent (hover states, subtle fills, a fourth neutral the site never shows),
+derive it from an observed value and **say so in the `$description`**. A future reader has
+to know which values are evidence and which are inference.
+
+`border.accent` is the deliberate escape hatch, and it documents itself in every theme file:
+
+> The CTA outline colour. Defaults to this theme's strong border; a brand that wants its
+> CTAs to stand out overrides THIS one token.
+
+Reach for it before inventing a new token. A token that already carries a `$description`
+naming your situation is the intended answer.
+
+## 6. Cloning an existing org
+
+Copying an org pack is mechanical, and every gotcha is a name that exists in more than one
+place. Work through them in order.
+
+1. **Copy the folder.** `rx/<source>/` → `rx/<neworg>/`, keeping `styles/`, `components/`,
+   `templates/`.
+2. **Rename the templates.** Folder AND the id inside the manifest. `bpp-chat-layout`
+   becomes `lyceum-chat-layout` in both places. Template ids are org-qualified and they
+   are referenced by string.
+3. **Update every manifest `name`** in the copied components and templates. A duplicate
+   name across packs is a collision: names are unique across all tiers, not per org.
+4. **Register the client surface** if the demo client serves it
+   (`packages/demo/src/demo/clients.js`).
+5. **Point the app at the new theme.** Templates reference `unoverse://theme/<org>/<name>`.
+   A copied template still names the old org until you change it.
+
+## 7. Done means all four
+
+- `grep -ri "<oldorg>" rx/<neworg>/` returns **nothing**. This is the check that catches
+  the id someone missed at midnight, and it is the one people skip.
+- The new org appears in **Studio's universe dropdown** and its theme renders.
+- **Studio's publish lint: 0 errors.** Justify any warning out loud.
+- The conformance checklist passes for every copied component
+  ([UNOVERSE_CONFORMANCE](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_CONFORMANCE.md)).
+
+## Deeper references
+
+Token structure and the resolve order:
+[UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md).
+Which tier owns what:
+[UNOVERSE_LAYERS](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_LAYERS.md).
+Styles are W3C design tokens, two-tier base/semantic, resolved live by the server and
+served at `unoverse://theme/{org}/{name}`. The SDK fetches them and bundles none.

package/vendor/skills/unoverse-prompt-component/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: unoverse-prompt-component
+description: Build or audit a PROMPT component (a briefed, AI-filled Unoverse component) in rx/. Use when adding brief tags, deciding which props an agent may fill, debugging a part the agent never fills or fills wrongly, or checking what a component's MCP tool schema actually contains. Covers the traps that silently discard an authored brief.
+---
+
+# Prompt components: the parts an agent fills
+
+A prompt component is an ordinary `rx/` component whose bound nodes carry `brief` tags.
+The platform compiles those tags into the component's **MCP tool schema**, and that schema
+is the only instruction channel: no side-channel prompt, no per-component agent skill.
+`unoverse-create` covers authoring components in general; this skill is about the briefs.
+
+**The whole discipline is one sentence: what you wrote in YAML is not what the agent
+receives. Compile the schema and read it.** Every failure below is silent. Nothing errors,
+nothing renders wrong in Studio, and the agent simply gets a different instruction from the
+one you wrote.
+
+---
+
+## Step 1 (do this first, and again at the end): compile the schema
+
+```bash
+cp .claude/skills/unoverse-prompt-component/verify.ts ./verify.tmp.ts
+npx tsx verify.tmp.ts <org>/<component>   # e.g. better-alpha/deal-page
+rm -f verify.tmp.ts
+```
+
+It must run from the repo root (it resolves `@unoverse-platform/base`). It prints every
+part the agent can fill, its description, and its limits. Read that output, not the YAML.
+
+Then, always: `node -e "import('./packages/base/src/lint/rx/index.mjs').then(m=>{const r=m.lintDefinitions();console.log(r.problems.length);r.problems.forEach(p=>console.log(p.level,p.file,p.msg))})"`
+
+The linter catches two of the five traps below by name. Read what it says rather than
+silencing it.
+
+---
+
+## Step 2: decide what is briefed
+
+A prop is briefed when **a person reading the source material would write it**. That is the
+whole test.
+
+Briefed: names, classifications, prose, lists of terms, risks, reasons, questions and
+answers, and the deal's own figures where the documents state them.
+
+NOT briefed, with the reason each is excluded:
+
+| Prop | Why not |
+|---|---|
+| A collection people submit (question threads, an uploaded data room) | Briefing it invites the model to write the questions users are supposed to ask |
+| A composer's draft field (`questionDraft`) | The same, one field down |
+| A resolved percentage (`progressPct`) | A definition computes nothing; the producer resolves it |
+| A derived flag (`somethingEmpty`, `ndaRequired`) | Derived state and access decisions are not document facts |
+| A URL or image (`logo`) | The model does not author URLs. If it must reference one, use `hydrate: "image"` so it passes a `universal_id` instead |
+
+### The trap that looks like caution
+
+**Omitting a brief does not protect a field. It makes the field permanently blank.**
+
+If the agent is the only producer in the workflow (file to parser to agent to component),
+an unbriefed prop can never be filled by anything. Leaving fees or dates unbriefed to keep
+a model from "authoring a fee" achieves nothing if a briefed `keyTerms` two sections away
+already asks it for the same figures.
+
+The protection that works is the instruction, not the omission. Write
+"TRANSCRIBED from the documents with its unit exactly as written; never calculate, never
+convert, never round, never a figure the documents do not state."
+
+Check for this contradiction directly: if two parts can carry the same fact, either both
+are briefed or neither is.
+
+---
+
+## Step 3: put the brief on the node that BINDS the field
+
+This is the rule from the rulebook (docs/design/CLAUDE.md §3) and it is where authored
+briefs go to die.
+
+```yaml
+# COMPILES
+- type: Text
+  brief: { description: "...", maxLength: 80 }
+  bind: { value: dealName }
+
+# COMPILES: the Each that binds the array owns the counts
+- type: Each
+  brief: { description: "...", minItems: 4, maxItems: 8 }
+  bind: { items: risks }
+  template: { $include: components/bullet-list }
+```
+
+### Trap 1: a brief on a `Ref` never compiles
+
+A `Ref` has no `bind`. The brief is dropped, and the atom's own brief wins after expansion.
+
+Symptom: several unrelated parts compile to the SAME generic description, for example
+"The passage, in Markdown, taken from the source" or "The items, in the order the source
+gives them". That is `prose` and `list` talking, not you.
+
+The linter says: `brief.maxLength on a node with no bind`.
+
+Fix: draw the markup yourself so a bound node can carry the brief. Copy the atom's `root`
+into a local `components/` partial **with its briefs removed**, then have each section own
+an `Each` or `Markdown` that carries its own brief and includes the shared partial. The
+look is identical; only the prompt is per section. An atom is one file and cannot carry a
+different description for every field that composes it, which `prose.yaml` says itself.
+
+### Trap 2: item counts only compile on the `Each`
+
+`minItems`/`maxItems` on anything that is not the array-binding `Each` are discarded.
+
+The linter says: `brief.minItems/maxItems on a non-Each node`. Do not delete the counts to
+silence it. Move them to the `Each`.
+
+### Trap 3: a briefed atom drags a collection into the schema
+
+Briefs are collected from the **expanded** tree (`packages/base/src/markdown/collect.ts`).
+An `Each` is recorded whenever its template has briefed fields, whether or not the `Ref`
+itself carries a brief.
+
+So `ref: faq` bound to `wmQuestions`, or `ref: list` bound to `documents`, or `ref:
+form-long` bound to a draft, quietly compiles that collection into the fill schema and
+invites the model to write it.
+
+Fix: for any collection people fill, use brief-free markup. Never point a briefed atom at
+one. Assert it in the verify output.
+
+### Trap 4: item briefs and the section brief arguing
+
+When a shared row partial carries item briefs, keep them generic ("what the entry is
+called"). The section's own `Each` brief sits directly above them in the schema and already
+says what its titles and bodies are for. Two specific descriptions of one field contradict
+each other.
+
+### Trap 5: counts that are layout, not preference
+
+If a strip renders `columns: "4"`, then `minItems: 4, maxItems: 4`. Note that `minItems`
+is **guidance only**: the compiler appends it to the description and never gates on it
+(`server/src/mcp/briefSchema.ts`). `maxItems` and `maxLength` are hard. A count that is
+genuinely structural cannot be enforced by the schema alone, so say so in the description.
+
+---
+
+## Step 4: write the description
+
+Length caps are **prose limits**. Over the cap, write a shorter English sentence; never
+abbreviate and never substitute characters. Say so in the page-level brief.
+
+- Put the ground rule once, as a plain-string brief on the layout root: verbatim from the
+  source, omit what the source does not state, merge on refinement turns.
+- Put each section's rules on that section, next to the field they govern. A rule about
+  risks does not belong in a preamble every other part has to carry.
+- Name what the entry is FOR, not just its shape: "the title is the claim, the body is the
+  evidence" beats "a title and a body".
+- Say what NOT to do where a model would plausibly do it: never repeat another tab in
+  reverse, never present a target as a result, never restate a figure another section
+  carries.
+
+## Step 5: the workflow door
+
+If the component is filled by an agent inside a workflow rather than in chat, read
+`docs/unoverse/UNOVERSE_MCP_TEMPLATE_PROTOCOL.md` §The workflow door. The load-bearing law:
+**a blank part is a valid final state.** A part the source does not cover stays blank, the
+`visibleWhen` guards render around it, and the page is complete. Gaps are orientation on
+the first read, never standing debt. This is implemented in
+`server/src/runtime/components/executor/briefService.ts`; a component that fights it burns
+every turn to `maxTurns` and returns an empty text output.
+
+---
+
+## Checklist
+
+1. Schema compiled and read. Every part carries the description you wrote, not an atom's.
+2. No collection people submit, no draft field, no derived flag, no URL in the schema.
+3. Every field a person would write from the source IS in the schema. Nothing is "protected"
+   by omission while a sibling part asks for the same fact.
+4. Counts on the array-binding `Each`; structural counts stated in the description too.
+5. Linter: 0 errors, and every warning read rather than silenced.
+6. Previewed in Studio, then filled once for real. Studio proves the layout; only a fill
+   proves the prompt.

package/vendor/skills/unoverse-prompt-component/verify.ts

@@ -0,0 +1,95 @@
+/**
+ * Compile a prompt component's brief schema and print what the AGENT actually receives.
+ *
+ * What you wrote in YAML is not what the agent gets: a brief on a `Ref` is dropped, an
+ * atom's own brief wins after expansion, and a briefed atom pointed at a user-filled
+ * collection drags that collection in. All of it is silent. This prints the truth.
+ *
+ * Copy to the repo ROOT before running (it resolves @unoverse-platform/base):
+ *   cp .claude/skills/unoverse-prompt-component/verify.ts ./verify.tmp.ts
+ *   npx tsx verify.tmp.ts better-alpha/deal-page
+ *   rm -f verify.tmp.ts
+ */
+import { loadDefinition } from "@unoverse-platform/base/definitions/definitions.js";
+import { compileBriefSchema } from "@unoverse-platform/base/markdown/index.js";
+
+const ref = process.argv[2];
+if (!ref) {
+  console.error("usage: npx tsx verify.tmp.ts <org>/<component>   (org optional)");
+  process.exit(1);
+}
+
+const def = loadDefinition(ref, "component");
+if (!def) {
+  console.error(`No component definition resolved for "${ref}".`);
+  process.exit(1);
+}
+
+const schema: any = compileBriefSchema(def as any, {});
+if (!schema) {
+  console.error(`"${ref}" carries no briefs — it is a plain UI component, not a prompt component.`);
+  process.exit(1);
+}
+
+const props: Record<string, any> = schema.properties ?? {};
+const keys = Object.keys(props);
+
+console.log(`\n${ref} — ${keys.length} fillable part${keys.length === 1 ? "" : "s"}\n`);
+
+// The generic atom descriptions. Seeing one of these means an authored brief was DROPPED:
+// the brief sat on a `Ref`, so the atom's own text won after expansion.
+const ATOM_TEXT = /^The passage, in Markdown|^The items, in the order the source gives|^The question and answer pairs the source states AS SUCH|^The terms, conditions or regulatory wording|^The figures, in the order the source states/;
+
+const dropped: string[] = [];
+for (const key of keys) {
+  const p = props[key];
+  const desc: string = p.description ?? "";
+  const limits = [
+    p.type === "array" ? "array" : "string",
+    p.maxLength != null ? `max ${p.maxLength}` : null,
+    p.minItems != null ? `min ${p.minItems} (GUIDANCE ONLY, never gated)` : null,
+    p.maxItems != null ? `max ${p.maxItems} items` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+  console.log(`### ${key}  [${limits}]`);
+  console.log(desc ? `    ${desc}` : "    (no description)");
+  if (p.items?.properties) {
+    for (const [ik, iv] of Object.entries<any>(p.items.properties)) {
+      console.log(`      - ${ik}${iv.maxLength ? ` (max ${iv.maxLength})` : ""}: ${iv.description ?? ""}`);
+    }
+  }
+  if (ATOM_TEXT.test(desc)) dropped.push(key);
+  console.log("");
+}
+
+console.log("—".repeat(72));
+if (dropped.length) {
+  console.log(`DROPPED BRIEFS (${dropped.length}): ${dropped.join(", ")}`);
+  console.log("  These compiled to a shared ATOM's generic description, not yours. The brief");
+  console.log("  is on a `Ref`, which has no `bind`. Draw the markup so a bound node carries it.");
+} else {
+  console.log("DROPPED BRIEFS: none — every part carries an authored description.");
+}
+
+// Anything a PERSON fills, or the platform derives, must never be in this schema.
+// Name the DERIVED fields, never match on a suffix: `targetReturnPct` is a document fact
+// the agent must fill, while `progressPct` is resolved by the producer. A `Pct$` heuristic
+// called the first one a leak.
+const DERIVED = /^(progressPct|remainingAllocationPct|ndaRequired)$/;
+const forbidden = keys.filter((k) => /Questions$|^documents|Draft$|Empty$|^logo$/i.test(k) || DERIVED.test(k));
+console.log(
+  forbidden.length
+    ? `MUST NOT BE HERE (${forbidden.length}): ${forbidden.join(", ")}\n  A user-filled collection, a draft field, a derived flag or a URL is in the agent's\n  schema. Usually a briefed atom (faq / list / form-long) bound to it.`
+    : "MUST NOT BE HERE: none.",
+);
+
+// Every input prop that is NOT fillable. Review this list: a field nobody else produces
+// and no brief covers is permanently blank, not "protected".
+const inputProps = Object.entries((def as any).props ?? {})
+  .filter(([, v]: any) => v?.input)
+  .map(([k]) => k);
+const unfillable = inputProps.filter((k) => !keys.includes(k));
+console.log(`\nNOT FILLABLE BY THE AGENT (${unfillable.length} of ${inputProps.length} input props):`);
+console.log(`  ${unfillable.join(", ") || "none"}`);
+console.log("  Each needs a producer. If nothing else supplies it, it is permanently blank.");