@unoverse-platform/studio 0.1.26 → 0.1.28

package/vendor/sdk/lib/template.tsx

@@ -13,8 +13,30 @@
  * chat primitives (Conversation/Input/…) come in later slices.
  */
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
-import { dispatchAction, type ComponentStore, type ResolvedTheme, type UnoverseClient, type UnoverseDefinition, type UnoverseNode } from "./core";
-import { renderNode, styleToCss, keyframesCss, cssWidth, type ActionHandler, type SlotResolver } from "./render";
+import {
+  collectSurfacedViews,
+  cssWidth,
+  dispatchAction,
+  formatRelative,
+  isViewField,
+  orderedClaims,
+  propDefaults,
+  resolveActiveLayout,
+  resolveActiveView,
+  selectPointers,
+  viewOf,
+  type ComponentStore,
+  type ResolvedTheme,
+  type UnoverseClient,
+  type UnoverseDefinition,
+  type UnoverseNode,
+} from "./core";
+import { renderNode, styleToCss, keyframesCss, type ActionHandler, type SlotResolver } from "./render";
+
+// The pure template derivations moved to core/templates.ts (the portable brain —
+// framework-agnostic, guarded by sdk-core-portable.test.ts). Re-exported here so
+// existing consumers keep their import path.
+export { collectSurfacedViews, computeAppWidth, orderedClaims, resolveActiveLayout, resolveActiveView, selectPointers, viewOf } from "./core";
 import { UnoverseComponent } from "./UnoverseComponent";
 import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
 import { IsolatedRoot } from "./isolate";
@@ -49,203 +71,6 @@ const INERT_VOICE: UseVoiceServiceConfig = {
   session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" },
 };
 
-/** The author's declared prop defaults (def.props[k].default) → a flat data object. Content, not policy. */
-function propDefaults(props?: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(props ?? {})) {
-    if (v && typeof v === "object" && "default" in (v as Record<string, unknown>)) {
-      out[k] = (v as { default: unknown }).default;
-    }
-  }
-  return out;
-}
-
-/** Format a turn timestamp as relative copy ("just now" / "5 min ago"). Neutral
- *  projection of a model value (like `text`), not UX policy. Mirrors legacy
- *  ChatHistoryItem.formatRelativeTime. Empty string when unstamped. */
-function formatRelative(ts?: number): string {
-  if (!ts) return "";
-  const diff = Math.floor((Date.now() - ts) / 1000);
-  if (diff < 60) return "just now";
-  if (diff < 3600) return `${Math.floor(diff / 60)} min ago`;
-  if (diff < 86400) return `${Math.floor(diff / 3600)} hr ago`;
-  return new Date(ts).toLocaleDateString();
-}
-
-/**
- * Walk a template tree and collect every VIEW a reaction surface claims — the `eq`
- * value of each `ComponentSlot.select.where { field: "defaultState" }`. State-selected
- * UI (STATE_MODEL §5b): a component instance renders in exactly ONE placeholder. If a
- * surface shows a given view, the conversation flow (the `inline` placeholder) must NOT
- * also render instances in that view — else the same instance paints twice. A view no
- * surface claims is absent from this set, so it stays in the flow (the fallback).
- * Exported for testing.
- */
-export function collectSurfacedViews(node: unknown, out: Set<string> = new Set()): Set<string> {
-  if (Array.isArray(node)) {
-    for (const n of node) collectSurfacedViews(n, out);
-    return out;
-  }
-  if (!node || typeof node !== "object") return out;
-  const n = node as Record<string, unknown>;
-  const sel = n.select as { where?: { field?: string; eq?: unknown } } | undefined;
-  if (n.type === "ComponentSlot" && sel?.where?.field === "defaultState" && typeof sel.where.eq === "string") {
-    out.add(sel.where.eq);
-  }
-  for (const v of Object.values(n)) if (v && typeof v === "object") collectSurfacedViews(v, out);
-  return out;
-}
-
-/**
- * STATE-OWNED APP WIDTH (docs/design/05, layouts era): the app's outer width is
- * declared by its LAYOUT's data, never the manifest. Two declaration points, both
- * the neutral `appWidth` key (a named app size resolved via theme.appSize):
- *   - a plain node's `appWidth` = an always-open panel (the core column) — the
- *     layout's constant term.
- *   - a ComponentSlot surface's `appWidth` = its panel width, counted only while
- *     the surface is OCCUPIED (its view is the active state).
- * The caller passes the ACTIVE layout (resolveActiveLayout) — layout swaps are
- * whole-arrangement swaps, so the width is always the active layout's total.
- * Activation is DERIVED, never stored. No declared width → undefined: the host
- * keeps its own default, the sizing twin of "unmatched view falls back to inline".
- * There is no other path.
- */
-export function computeAppWidth(root: unknown, store: ComponentStore, appSize?: Record<string, string>): string | undefined {
-  // Resolve a declared width: a NAMED SIZE via theme.appSize (like any token), else raw
-  // CSS — guarded so an unresolvable name can never emit invalid CSS.
-  const rw = (w: unknown): string | undefined => cssWidth(typeof w === "string" ? (appSize?.[w] ?? w) : undefined);
-  const r = root as Record<string, unknown> | null | undefined;
-  const widths: string[] = [];
-  // Gather the tree's width-bearing nodes: always-open core panels and the reaction
-  // SURFACES (view → panel width).
-  const surfaces = new Map<string, string | undefined>();
-  const walk = (node: unknown): void => {
-    if (Array.isArray(node)) {
-      for (const c of node) walk(c);
-      return;
-    }
-    if (!node || typeof node !== "object") return;
-    const n = node as Record<string, unknown> & { appWidth?: string; type?: string; select?: { where?: { field?: string; eq?: unknown } } };
-    if (n !== r) {
-      if (n.type === "ComponentSlot") {
-        const claim = n.select?.where;
-        // `appWidth: flex` — the surface takes the REMAINING host space. DATA WINS: an
-        // org may define `flex` as a real appSize token (bpp: calc(100% − chat)) and
-        // that resolves like any name; the marker below is the theme-free fallback,
-        // resolved as "fill the host" when the view is active.
-        if (claim?.field === "defaultState" && typeof claim.eq === "string")
-          surfaces.set(claim.eq, rw(n.appWidth) ?? (n.appWidth === "flex" ? "flex" : undefined));
-      } else if (n.appWidth !== undefined) {
-        const w = rw(n.appWidth);
-        if (w) widths.push(w); // a plain panel (the core column) is ALWAYS open
-      }
-    }
-    for (const v of Object.values(n)) if (v && typeof v === "object") walk(v);
-  };
-  walk(r);
-  // ONE STATE AT A TIME (docs/design/04): the app = core + the ACTIVE state's panel —
-  // the most recently surfaced view. Panel combinations cannot exist, so the width is
-  // always one of a small known set, bounded by construction.
-  let active = "";
-  let activeAt = -1;
-  for (const turn of store.getResponses())
-    for (const p of turn.components) {
-      const { chatId, nodeId } = store.split(p);
-      const view = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
-      if (typeof view === "string" && surfaces.has(view) && store.touchOf(p) > activeAt) {
-        activeAt = store.touchOf(p);
-        active = view;
-      }
-    }
-  const activePanel = active ? surfaces.get(active) : undefined;
-  // An ACTIVE flex surface fills the host viewport (the host caps at its pane); the
-  // surface flexes into whatever the fixed panels leave.
-  if (activePanel === "flex") return "100%";
-  if (activePanel) widths.push(activePanel);
-  if (!widths.length) return undefined;
-  return widths.length === 1 ? widths[0] : `calc(${widths.join(" + ")})`;
-}
-
-/**
- * TEMPLATE LAYOUTS — name-sync (docs/design/05). A template with `layouts` is a set
- * of full arrangements, the template-tier twin of a component's faces: the ACTIVE
- * layout is the one whose NAME matches the latest surfaced component view, falling
- * back to `defaultLayout` when nothing (or nothing matching) is surfaced. Same
- * derivation as the active state — read off the store, never stored. Single-layout
- * templates (`layouts` absent) resolve to `root`: the classic behavior, untouched.
- */
-export function resolveActiveLayout(def: UnoverseDefinition | null | undefined, store: ComponentStore): UnoverseNode | undefined {
-  if (!def) return undefined;
-  const layouts = def.layouts;
-  if (!layouts) return def.root;
-  const { view } = resolveActiveView(def, store, new Set(Object.keys(layouts)));
-  return layouts[view] ?? layouts[def.defaultLayout ?? "main"] ?? def.root;
-}
-
-/**
- * THE ACTIVE VIEW — the ONE derivation every consumer shares (docs/design/04 + the
- * guest-control law). The latest surfaced component view among `validViews`, with
- * PINNED enforcement: while a pinned layout's view is surfaced, a background arrival
- * cannot displace it — only a guest write anywhere can. Layout choice and surface
- * gating MUST both read this function: two loops that each pick "the latest view"
- * disagree the moment pin overrides one of them — the layout renders view A while
- * every surface inside it gates against view B, and the whole panel goes blank.
- */
-export function resolveActiveView(
-  def: UnoverseDefinition | null | undefined,
-  store: ComponentStore,
-  validViews: Set<string>,
-): { view: string; byGuest: boolean } {
-  let view = "";
-  let at = -1;
-  let byGuest = false;
-  let pinnedView = "";
-  let pinnedAt = -1;
-  for (const turn of store.getResponses())
-    for (const p of turn.components) {
-      const { chatId, nodeId } = store.split(p);
-      const v = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
-      if (typeof v !== "string" || !validViews.has(v)) continue;
-      const t = store.touchOf(p);
-      if (t > at) {
-        at = t;
-        view = v;
-        byGuest = store.interactionTouchOf(p) >= t;
-      }
-      if ((def?.layouts?.[v] as { pinned?: boolean } | undefined)?.pinned && t > pinnedAt) {
-        pinnedAt = t;
-        pinnedView = v;
-      }
-    }
-  if (pinnedView && view !== pinnedView && !byGuest) return { view: pinnedView, byGuest: false };
-  return { view, byGuest };
-}
-
-/** Resolve a ComponentSlot's `select` against the store → ordered pointers. Exported for testing. */
-export function selectPointers(store: ComponentStore, node: UnoverseNode): string[] {
-  const sel = node.select ?? {};
-  let pointers =
-    sel.from === "all"
-      ? store.getResponses().flatMap((r) => r.components)
-      : (store.latestResponse()?.components ?? []);
-
-  // `where` — select by COMPONENT STATE (the reaction contract, STATE_MODEL §5b): any
-  // component whose own slice matches, ordered newest state-write first so `limit: 1`
-  // = "most recent wins". The generic replacement for type-pinned surfaces — a
-  // template reacts to whatever component enters the state, never to a named type.
-  if (sel.where) {
-    const { field, eq, ne } = sel.where;
-    pointers = pointers.filter((p) => {
-      const { chatId, nodeId } = store.split(p);
-      const v = (store.get(chatId, nodeId) as Record<string, unknown>)[field];
-      return ne !== undefined ? v !== ne : v === eq;
-    });
-    pointers = [...pointers].sort((a, b) => store.touchOf(b) - store.touchOf(a));
-  }
-  if (sel.limit != null) pointers = pointers.slice(0, sel.limit);
-  return pointers;
-}
-
 export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig }: StreamedUnoverseTemplateProps) {
   const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -271,7 +96,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
   // to their own slices — so streaming chunks never re-walk the whole template tree.
   // Stable subscribe fn: an inline arrow would tear down + re-create the subscription
   // every render.
-  useSyncExternalStore(
+  const structureVersion = useSyncExternalStore(
     useCallback((cb) => store.subscribe(cb), [store]),
     useCallback(() => store.getStructureVersion(), [store]),
   );
@@ -289,18 +114,51 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     };
   }, [client, uri]);
 
-  // NAME-SYNC: the tree this template presents — the layout matching the latest
-  // surfaced component view (multi-layout templates), else the classic root. The
-  // resolved node is a stable per-def object, so downstream memos key off it.
+  // ARRIVAL PLACEMENT (STATE_MODEL v2 §5 rule 3): nobody sends a state — the HOST
+  // places the actor at spawn. For each arrived component whose slice has no view yet:
+  //   1. the component's DECLARED INITIAL, if this template has a state for it (the
+  //      component's preference stands whenever the host can honor it);
+  //   2. else the SCAN — the first name in THIS template's declared order that the
+  //      component's public menu (`publicStates`, server-injected at init) also has;
+  //   3. no overlap at all → leave unset: the component wakes in its own initial and
+  //      rides inline (rule 6).
+  // The write is a data merge (never an interaction touch — placement is not the
+  // guest's hand), it happens ONCE per instance (a placed slice has a view), and the
+  // component owns the axis from then on: the template never writes it again.
+  useEffect(() => {
+    const order = def?.stateOrder;
+    if (!order?.length) return;
+    for (const turn of store.getResponses())
+      for (const p of turn.components) {
+        const { chatId, nodeId } = store.split(p);
+        const slice = store.get(chatId, nodeId) as Record<string, unknown> | undefined;
+        if (!slice || viewOf(slice) !== undefined) continue;
+        const menu = Array.isArray(slice.publicStates) ? (slice.publicStates as unknown[]) : undefined;
+        if (!menu) continue;
+        const initial = typeof slice.initialView === "string" ? slice.initialView : undefined;
+        const face = initial && order.includes(initial) ? initial : order.find((s) => menu.includes(s));
+        if (face) store.apply({ type: "COMPONENT_DATA", chatId, nodeId, data: { view: face } });
+      }
+  }, [def, store, structureVersion]);
+
+  // THE SEVEN RULES (2026-08-09) need no effect here: a higher state MASKS the ones
+  // below (rule 4 — the ladder alone decides what shows; lower states refresh
+  // silently underneath via the store's arrival supersession), and releasing the top
+  // state is just the ladder looking again (rule 6). The earlier cancellation WRITE
+  // (cancelBelow) was superseded by this pure-masking ruling and deleted.
+
+  // STATE OWNS LAYOUT (STATE_MODEL v2): the tree this template presents — the active
+  // state's layout (multi-layout templates), else the classic root. The resolved node
+  // is a stable per-def object, so downstream memos key off it.
   const activeRoot = def ? resolveActiveLayout(def, store) : undefined;
 
-  // The set of VIEWS this template's reaction surfaces claim — computed per active
-  // layout: layout NAMES claim their view (name-sync) alongside the surfaces inside.
-  // The timeline uses it to keep a claimed instance out of the flow (one instance → one
-  // placeholder).
+  // The CLAIM set — the states this template reacts to. v2: the declared order
+  // (stateOrder) IS the claim list; legacy defs fall back to layout names + surface
+  // claims. The timeline uses it to keep a claimed instance out of the flow (one
+  // instance → one placeholder).
   const surfacedViews = useMemo(() => {
-    const views = activeRoot ? collectSurfacedViews(activeRoot) : new Set<string>();
-    for (const name of Object.keys(def?.layouts ?? {})) views.add(name);
+    const views = new Set<string>(orderedClaims(def));
+    if (activeRoot) collectSurfacedViews(activeRoot, views, def?.defs as Record<string, unknown> | undefined);
     return views;
   }, [activeRoot, def]);
 
@@ -326,16 +184,17 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       if (action === "backToChat") voice.endCall();
     }
     // GUEST CLOSE from TEMPLATE CHROME: a ✕ on the layout itself (a rail/panel header —
-    // not inside a single card) fires the CloseButton atom's `setValue defaultState:"inline"`.
-    // Template chrome has no card slice to write, so that write would be inert; instead it
-    // means "un-surface the current view" → the store retracts every surface to base (the
-    // same reset a new turn runs). A card that closes ITSELF keeps using the plain component
-    // write (real ids), untouched. `then` still chains via dispatchAction below.
+    // not inside a single card) fires the CloseButton atom's `setValue view:"inline"`
+    // (legacy defs write `defaultState`). Template chrome has no card slice to write, so
+    // that write would be inert; instead it means "un-surface the current view" → the
+    // store retracts every surface to its declared base (the same reset a new turn
+    // runs). A card that closes ITSELF keeps using the plain component write (real
+    // ids), untouched. `then` still chains via dispatchAction below.
     if (
       action && typeof action === "object" &&
       (action as { type?: string }).type === "setValue" &&
       (action as { values?: { key?: string; value?: unknown }[] }).values?.some(
-        (v) => v.key === "defaultState" && v.value === "inline",
+        (v) => isViewField(v.key) && v.value === "inline",
       )
     ) {
       store.closeSurfaces();
@@ -375,12 +234,12 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     // data is untouched and re-presents the moment its state is active again.
     // Surfaces never stack; panel combinations cannot exist.
     const claim = node.select?.where;
-    if (claim?.field === "defaultState" && typeof claim.eq === "string" && claim.eq !== surfacedView) {
-      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+    if (isViewField(claim?.field) && typeof claim?.eq === "string" && claim.eq !== surfacedView) {
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
     const pointers = selectPointers(store, node);
     if (pointers.length === 0) {
-      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
     // `frame` — chrome that exists ONLY because the slot matched (fallback's twin).
     // The frame subtree renders with a slot resolver that serves the outer slot's
@@ -403,7 +262,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       const frame = appWidth
         ? ({ ...node.frame, style: { ...(node.frame.style ?? {}), width: appWidth, flex: "0 0 auto" } } as UnoverseNode)
         : node.frame;
-      return renderNode(frame, store.getTemplateState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot);
+      return renderNode(frame, store.getTemplateState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot, def?.defs);
     }
     return pointers.map((p) => leaf(p));
   };
@@ -427,15 +286,15 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
             turn.role === "assistant"
               ? turn.components.filter((p) => {
                   const { chatId, nodeId } = store.split(p);
-                  const view = (store.get(chatId, nodeId) as Record<string, unknown> | undefined)?.defaultState;
-                  return typeof view !== "string" || !surfacedViews.has(view);
+                  const view = viewOf(store.get(chatId, nodeId) as Record<string, unknown> | undefined);
+                  return !view || !surfacedViews.has(view);
                 })
               : [];
           // Slot scoped to this turn's UNCLAIMED components (assistant turns only).
           const turnSlot: SlotResolver = (slotNode, k) => {
             let ptrs = [...shown];
             if (slotNode.select?.limit != null) ptrs = ptrs.slice(0, slotNode.select.limit);
-            if (ptrs.length === 0) return slotNode.fallback ? renderNode(slotNode.fallback, {}, dispatch, theme, k ?? "fb") : null;
+            if (ptrs.length === 0) return slotNode.fallback ? renderNode(slotNode.fallback, {}, dispatch, theme, k ?? "fb", undefined, def?.defs) : null;
             // Pass the turn's streaming state into each component's scope so a streamed
             // component (e.g. StreamingText) can stop its own loading dots when complete.
             const streaming = turn.role === "assistant" && turn.streamingState === "streaming";
@@ -463,7 +322,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
                   // inactive → the definition hides it (legacy ChatHistoryItem null-returns).
                   active: turn.streamingState === "streaming" || shown.length > 0,
                 };
-          return renderNode(sub, data, dispatch, theme, turn.id, turnSlot);
+          return renderNode(sub, data, dispatch, theme, turn.id, turnSlot, def?.defs);
         })}
       </div>
     );
@@ -505,7 +364,10 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
   const keyframes = <style>{keyframesCss(theme)}</style>;
   // A layout root never carries `appWidth` (guard-enforced) — panels inside it do.
   const rootNode = (activeRoot ?? def.root) as UnoverseNode;
-  const tree = renderNode(rootNode, rootData, dispatch, theme, undefined, resolve);
+  // The template's own shared pieces, threaded into every branch it draws: chrome, a
+  // slot's fallback, a timeline turn. A reference in any of them resolves against the
+  // same map rather than rendering nothing.
+  const tree = renderNode(rootNode, rootData, dispatch, theme, undefined, resolve, def?.defs);
   // A template is a SURFACE: its render-root fills the box the host gives it, so a root
   // that declares `height: "full"` (DATA) can resolve. This only fills when the host's box
   // is definite-height; when the host sizes to content the 100% resolves to content — so a

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

@@ -1,11 +1,11 @@
 ---
 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/), 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.
 ---
 
 # Creating Unoverse Artifacts
 
-You are helping a developer build in the **Unoverse developer carve-out** — the three
+You are helping a developer build in the **Unoverse developer carve-out**, the three
 editable folders mounted into the running platform:
 
 | Folder | What lives there |
@@ -14,14 +14,14 @@ editable folders mounted into the running platform:
 | `apps/unoverse/prompts/` | **Behavior**: agent skills (`skills/`) + prompt blocks (`blocks/`) |
 | `apps/unoverse/nodes/` | **Logic**: custom workflow nodes, authored as YAML |
 
-## Step 1 — Identify the artifact, read its playbook
+## Step 1: Identify the artifact, read its playbook
 
 Decide what the user is creating, then **read the matching reference file before writing
 anything**:
 
 | The user wants… | Read |
 |---|---|
-| A UI component or shared atom — incl. a page/card the AI fills with content (briefed) | `references/component.md` (§Briefs for AI-filled) |
+| 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 |
 | An agent skill (behavior guide the AI follows) | `references/agent-skill.md` |
@@ -30,11 +30,11 @@ anything**:
 | A workflow (wire nodes into an agent/pipeline on the Canvas) | `references/workflow.md` |
 
 Workflows are the one artifact that is NOT files: they are built live on the running
-platform through the `canvas` MCP (registered by this repo's `.mcp.json`) —
-the playbook covers the bind/build/test contract.
+platform through the `canvas` MCP (registered by this repo's `.mcp.json`).
+The playbook covers the bind/build/test contract.
 
 If it's ambiguous (e.g. "add a card that shows weather"), it's usually a **component**
-(the UI) plus possibly a **node** (the data source) — confirm the scope with the user.
+(the UI) plus possibly a **node** (the data source). Confirm the scope with the user.
 
 **New to design artifacts?** The guided learning journey at `docs/design/` (README →
 quick-start → … → troubleshooting) teaches components, templates, the state model
@@ -42,32 +42,32 @@ quick-start → … → troubleshooting) teaches components, templates, the stat
 `docs/design/CLAUDE.md` is the condensed agent rulebook. The playbooks here assume that
 material.
 
-## Step 2 — Hard rules (apply to every artifact)
+## Step 2: Hard rules (apply to every artifact)
 
 1. **Only edit the three carve-out folders.** Never touch, vendor, or work around the
-   SDK, engine, or server — they are not yours to change. If a task seems to require an
-   SDK change, the answer is almost always "express it as data" — re-read the playbook.
+   SDK, engine, or server. They are not yours to change. If a task seems to require an
+   SDK change, the answer is almost always "express it as data". Re-read the playbook.
 2. **Docs are the source of truth.** The playbooks name the design journey and the deep
    references ([UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md), [UNOVERSE_STATE_MODEL](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_STATE_MODEL.md), [UNOVERSE_LAYERS](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_LAYERS.md),
    [UNOVERSE_CONFORMANCE](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_CONFORMANCE.md)). They live in the docs repo
    (https://github.com/unoverse-platform/docs), not in your repo. When the user's request goes beyond the playbook, read the named section rather
    than improvising conventions.
-3. **UI is data.** No pixels, hex colors, or CSS anywhere — token names only. No logic
-   in definitions — anything computed (totals, formatting, chosen colors) is computed in
+3. **UI is data.** No pixels, hex colors, or CSS anywhere: token names only. No logic
+   in definitions: anything computed (totals, formatting, chosen colors) is computed in
    the node and sent as a plain field.
 4. **Audit before you're done.** Every component/template must pass the conformance
    checklist ([UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §9). Walk it item by item.
-5. **Discovery meta is ranked, not read.** Any spatially-discoverable artifact — a
-   component or template with a manifest, an agent skill, a node — is selected by
+5. **Discovery meta is ranked, not read.** Any spatially-discoverable artifact (a
+   component or template with a manifest, an agent skill, a node) is selected by
    embedding `title`/`name` + `whenToUse`/`description` + `category` against the user's
    own words (or the planner's task). The strict contract is
    `docs/nodes/node-discoverability.md`: outcome-first, utterance-shaped, opening
    words dominate, disqualify by property (never name a sibling). Each playbook carries
    the summary; read doc 14 before writing any meta.
 
-## Step 3 — Deploy loop (after the artifact is written)
+## Step 3: Deploy loop (after the artifact is written)
 
-Components and templates have NO scaffold command — author them from the references
+Components and templates have NO scaffold command. Author them from the references
 (mirror the closest existing artifact). Validation lives in Studio: its publish step
 lints every definition before anything leaves the machine (0 errors required, doc-cited
 messages; justify any warning), and the conformance checklist is
@@ -75,7 +75,7 @@ messages; justify any warning), and the conformance checklist is
 
 | Artifact | To see it live |
 |---|---|
-| Component / atom / template / style | Preview in Studio (`unoverse studio`), then publish from Studio — the publish lint gates it |
+| Component / atom / template / style | Preview in Studio (`unoverse studio`), then publish from Studio: the publish lint gates it |
 | Existing component restyle/edit only | takes effect live (the SDK reads `rx/` directly) |
 | Agent skill / prompt block | publish from Studio, same gate |
 | Node | Studio's Nodes screen: Load sample → Run. A node is YAML; running it is the only proof (no build) |
@@ -85,4 +85,4 @@ on :4108 (`unoverse studio` from the project folder).
 
 > In the platform monorepo (not the starter), the node docs live at
 > `packages/docs/nodes/`, the design journey at `packages/docs/design/`, and the dev loop
-> is just `npm run dev` — component nodes synthesize from rx/ definitions at boot.
+> is just `npm run dev`. Component nodes synthesize from rx/ definitions at boot.

package/vendor/skills/unoverse-create/references/agent-skill.md

@@ -1,4 +1,4 @@
-# Playbook — Agent Skills (prompts/skills)
+# Playbook: Agent Skills (prompts/skills)
 
 An agent skill is a markdown behavior guide the platform's AI agents discover and follow
 at runtime (e.g. how to handle complaints, how to walk a user through a process). It is
@@ -8,7 +8,7 @@ at runtime (e.g. how to handle complaints, how to walk a user through a process)
 
 ```
 apps/unoverse/prompts/skills/<skill-name>/
-  SKILL.md           # required — frontmatter + instructions
+  SKILL.md           # required: frontmatter + instructions
 ```
 
 The runtime scans this folder and serves skills to agents; agents match on the
@@ -19,9 +19,9 @@ The runtime scans this folder and serves skills to agents; agents match on the
 ```markdown
 ---
 name: skill-name                # required: lowercase, numbers, hyphens; max 64 chars
-title: Skill Name               # human display name — shows as the item's title in listings
-description: What this skill IS — ONE short line (≤ 120 chars), the listing subtitle
-whenToUse: The SELECTION text — outcome-first, in the user's vocabulary; ranked against intent for spatial discovery. See docs/nodes/node-discoverability.md — the node rules apply verbatim.
+title: Skill Name               # human display name, shown as the item's title in listings
+description: What this skill IS: ONE short line (≤ 120 chars), the listing subtitle
+whenToUse: The SELECTION text: outcome-first, in the user's vocabulary; ranked against intent for spatial discovery. See docs/nodes/node-discoverability.md. The node rules apply verbatim.
 version: 1.0.0                  # optional, semver
 category: ai                    # optional: ai | integration | workflow | utility
 triggers:                       # optional, max 20 keywords/phrases (2–50 chars each)
@@ -36,24 +36,24 @@ nodeTypes: []                   # optional: workflow node types the skill relies
 [The situations that should activate this behavior]
 
 ## Approach / Instructions
-[Clear, step-by-step guidance. Concrete do/don't phrasing beats abstractions —
-include example lines the agent can use verbatim where tone matters.]
+[Clear, step-by-step guidance. Concrete do/don't phrasing beats abstractions.
+Include example lines the agent can use verbatim where tone matters.]
 
 ## Examples
 [Concrete before/after or dialogue examples]
 ```
 
-Stick to the keys above. The markdown body must exist — a skill with frontmatter only
+Stick to the keys above. The markdown body must exist: a skill with frontmatter only
 is invalid.
 
 ## Writing rules
 
 1. **`whenToUse` does the routing; `description` says what it is.** Never blend them
    into one field. `whenToUse` is embedded and ranked against user intent (spatial
-   discovery / findIntent) — write it **outcome-first in the user's vocabulary**
-   ("Handle an unhappy customer — a complaint, frustration, or a request to
+   discovery / findIntent). Write it **outcome-first in the user's vocabulary**
+   ("Handle an unhappy customer: a complaint, frustration, or a request to
    escalate…"), never mechanism-first. The full rules are
-   `docs/nodes/node-discoverability.md` — they apply to skills verbatim.
+   `docs/nodes/node-discoverability.md`. They apply to skills verbatim.
 2. **Study an existing skill** in `prompts/skills/` and match its voice and structure.
 3. Keep instructions outcome-focused and scannable: short sections, bulleted do/don't
    lists, explicit escalation/stop conditions.
@@ -61,5 +61,5 @@ is invalid.
 
 ## Ship
 
-`docker compose restart unoverse` — the runtime rescans skills at boot. Verify the
+`docker compose restart unoverse`. The runtime rescans skills at boot. Verify the
 skill appears via the platform's skill listing (`unoverse check` for overall health).

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

@@ -1,6 +1,6 @@
-# Playbook — Prompt Blocks (prompts/blocks)
+# Playbook: Prompt Blocks (prompts/blocks)
 
-A prompt block is a **reusable prompt fragment** — a named piece of agent prompt text
+A prompt block is a **reusable prompt fragment**: a named piece of agent prompt text
 (formatting rules, a reasoning pattern, a policy) that workflows compose into agent
 system prompts. Smaller than a skill: a skill is a discoverable behavior guide; a block
 is an ingredient.
@@ -23,7 +23,7 @@ description: What this block contributes to a prompt
 tags: [topic, topic2]
 ---
 
-[The prompt text itself — written as direct instructions to the agent,
+[The prompt text itself, written as direct instructions to the agent,
 present tense, no meta-commentary about being a block.]
 ```
 
@@ -31,7 +31,7 @@ present tense, no meta-commentary about being a block.]
 
 1. **Study an existing block** (e.g. `blocks/formatting/markdown-guidelines.md`) and
    match its shape: tight sections, imperative bullets.
-2. A block must stand alone — no references to other blocks, no assumptions about what
+2. A block must stand alone: no references to other blocks, no assumptions about what
    else is in the prompt.
 3. Keep it generic and reusable. Anything workflow-specific belongs in that workflow's
    own prompt, not in a shared block.
@@ -40,4 +40,4 @@ present tense, no meta-commentary about being a block.]
 
 ## Ship
 
-`docker compose restart unoverse` — the runtime rescans blocks at boot.
+`docker compose restart unoverse`. The runtime rescans blocks at boot.