@unoverse-platform/studio 0.1.115 → 0.1.117

package/local/catalog.ts

@@ -28,6 +28,7 @@ type Loaders = {
   listIdentity: (org?: string) => unknown[];
   /** The Agents of one org or every org: `<org>/<name>` items with their meta and door. */
   listAgents: (org?: string) => unknown[];
+  listAgentFolders: (org?: string) => unknown[];
   resolveTheme: (name: string) => unknown;
   DEFAULT_ORG: string;
   /** A project's on-disk home. The writable set is built from these (see source.ts). */
@@ -112,6 +113,7 @@ export async function loadCatalog(
   const homes = await load(resolve(baseSrc, "definitions/registry/homes.ts"));
   const identity = await load(resolve(baseSrc, "definitions/registry/orgDocuments.ts"));
   const agents = await load(resolve(baseSrc, "definitions/registry/agents.ts"));
+  const agentFolders = await load(resolve(baseSrc, "definitions/registry/agentFolders.ts"));
 
   return {
     listDefinitions: defs.listDefinitions as Loaders["listDefinitions"],
@@ -135,6 +137,7 @@ export async function loadCatalog(
       return out;
     }) as Loaders["listIdentity"],
     listAgents: agents.listAgents as Loaders["listAgents"],
+    listAgentFolders: agentFolders.listAgentFolders as Loaders["listAgentFolders"],
     resolveTheme: theme.resolveTheme as Loaders["resolveTheme"],
     DEFAULT_ORG: theme.DEFAULT_ORG as string,
     projectDir: defs.projectDir as Loaders["projectDir"],

package/local/plugin.ts

@@ -15,7 +15,7 @@
  *
  * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
-import { designHome, authoringRoot, orgRepoName, lintOptions, platformHome } from "./design-home.mjs";
+import { authoringRoot, orgRepoName, lintOptions, platformHome } from "./design-home.mjs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { resolve, dirname } from "path";
@@ -177,12 +177,15 @@ function readMarkdownLibrary(dir: string): MarkdownEntry[] {
  * Scoping is the server's `?org=`: an org sees the universal tier plus its own and never
  * another org's, the rule RX_ORG_MODEL.md settled for a project's assets.
  */
-function readLibrary(projectRoot: string, marketplace: string, folder: "skills" | "blocks", orgs: string[], org?: string): MarkdownEntry[] {
+function readLibrary(projectDir: (org: string) => string, marketplace: string, folder: "skills" | "blocks", orgs: string[], org?: string): MarkdownEntry[] {
   const out = readMarkdownLibrary(resolve(marketplace, folder));
   for (const o of orgs) {
     if (org && org !== "all" && o !== org) continue;
-    // The org's own folder: the repo root in an org repo (UNO-88), else design/<org>/.
-    const orgHome = orgRepoName(projectRoot) ? projectRoot : resolve(designHome(projectRoot), o);
+    // The org's own folder, found as every other screen here finds it (base projectDir): the
+    // repo root in an org repo (UNO-88), else its authored folder, else the copy the universe
+    // installed. Working it out here alone missed the installed copy, so Studio run from the
+    // platform listed no org's skills while the server listed them all.
+    const orgHome = projectDir(o);
     for (const e of readMarkdownLibrary(resolve(orgHome, folder))) {
       // A SKILL's lookup name carries its org, because that is the name every reader
       // addresses it by and two orgs may hold one bare name. A BLOCK's does not: the
@@ -445,9 +448,9 @@ export function localStudioHost(): Plugin {
             case path === "/dev/identity":
               return json(res, { items: c.listIdentity(org) });
 
-            // Agents: the one file authored for the map, design/<org>/agents/<name>.yaml.
+            // Agents: folders in the one shape (agents/<name>/agent.yaml), and the older flat files.
             case path === "/dev/agents":
-              return json(res, { items: c.listAgents(org) });
+              return json(res, { items: c.listAgents(org), folders: c.listAgentFolders(org) });
 
             case path === "/dev/atoms":
               return json(res, { atoms: c.listDefinitions("atom") });
@@ -611,17 +614,17 @@ export function localStudioHost(): Plugin {
               return json(res, selection ?? { empty: true });
 
             case path === "/skills":
-              return json(res, { skills: readLibrary(projectRoot, c.marketplace, "skills", c.listOrgs(), org) });
+              return json(res, { skills: readLibrary(c.projectDir, c.marketplace, "skills", c.listOrgs(), org) });
 
             case path.startsWith("/skills/"): {
               const name = decodeURIComponent(path.slice("/skills/".length).replace(/\/file$/, ""));
-              const found = readLibrary(projectRoot, c.marketplace, "skills", c.listOrgs()).find((s) => s.name === name || s.id === name);
+              const found = readLibrary(c.projectDir, c.marketplace, "skills", c.listOrgs()).find((s) => s.name === name || s.id === name);
               // SkillsView reads `d.skill`, matching the server's shape. Not the bare object.
               return found ? json(res, { skill: found }) : json(res, { error: "skill not found" }, 404);
             }
 
             case path === "/prompt-blocks":
-              return json(res, { blocks: readLibrary(projectRoot, c.marketplace, "blocks", c.listOrgs(), org) });
+              return json(res, { blocks: readLibrary(c.projectDir, c.marketplace, "blocks", c.listOrgs(), org) });
 
             // Registry toggles are a DEPLOYED concept: they persist to installed_plugins
             // and decide what a running universe exposes. Local Studio has no database and

package/local/scaffold.d.mts

@@ -13,6 +13,7 @@ export function createProject(home: string, name: string): string;
 export function createFirstProject(home: string, name: string): string;
 
 /** Make `dir` one org's own repo (UNO-88): folders at the root, unoverse.yaml declaring the org, samples, editor globs, the check, Git. */
+export const ORG_FOLDERS: string[];
 export function createOrgRepo(dir: string, org: string): { state: "committed" | "no-identity" | "inside-repo" | "no-git"; message?: string };
 
 /** Make `home` a Git repo on main with a first commit, unless it already is one; never an author it was not given. */

package/local/scaffold.mjs

@@ -77,6 +77,9 @@ export function createProject(home, name) {
   return fillOrgFolder(root);
 }
 
+/** The folder of every authored kind, at an org repo's root (packages/docs/onboarding/studio.md). */
+export const ORG_FOLDERS = ["components", "apps", "templates", "atoms", "skills", "blocks", "nodes", "agents", "objects", "pipelines"];
+
 /**
  * One org's folder, filled: the welcome component, the sample styles, identity, app and
  * chat component. Shared by the monorepo shape (design/<org>/) and an org repo, whose root
@@ -93,6 +96,15 @@ function fillOrgFolder(root, { baselineOnly = false } = {}) {
   const dirs = baselineOnly ? ["styles", "identity"] : ["components/welcome", "apps", "styles", "skills", "blocks", "identity"];
   for (const d of dirs) mkdirSync(join(root, d), { recursive: true });
   if (!baselineOnly) writeFileSync(join(root, "components/welcome/welcome.yaml"), WELCOME);
+  // EVERY KIND'S FOLDER, EMPTY (owner, 2026-10-25). The baseline ruling dropped the SAMPLES; the
+  // folders went with them only because they were made beside the samples. A new org shows
+  // where each kind lives from the first minute. `.gitkeep` because Git keeps no empty folder.
+  if (baselineOnly) {
+    for (const d of ORG_FOLDERS) {
+      mkdirSync(join(root, d), { recursive: true });
+      if (readdirSync(join(root, d)).length === 0) writeFileSync(join(root, d, ".gitkeep"), "");
+    }
+  }
 
   // Worked example styles (sample-styles: brand ingredients + the override rules), so
   // styles/ is never an empty folder with no hint of the token cascade. Per PROJECT,

package/package.json

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

package/screens/AgentChain.tsx

@@ -0,0 +1,232 @@
+/**
+ * AN AGENT, DRAWN (docs/architecture/signal/AGENTS.md § 3): a chain read straight off its
+ * agent.yaml, the way a pipeline's chain is read off its pipeline.yaml (Spatial's PipelineChain).
+ * Three kinds, drawn as three: its SKILLS feed in from above (what it knows: read into it before
+ * it starts, never called), its TRIGGERS wake it, and its TASKS are what it does (its org's own,
+ * then the marketplace MCPs). Below: its soul, access and settings. Nothing here is written for any
+ * one Agent: a new folder draws its own chain.
+ */
+import { BookOpen, CalendarDays, ChevronDown, ChevronRight, Compass, Mail, MessageSquare, Mic, Plug, Radio, Workflow } from "lucide-react";
+
+export interface AgentFolderItem {
+  ref: string;
+  org: string;
+  name: string;
+  title?: string;
+  role?: string;
+  description?: string;
+  whenToUse?: string;
+  category?: string;
+  version?: string;
+  /** Its picture, an image URL. */
+  avatar?: string;
+  skills: string[];
+  model?: { use?: string; reasoning?: string; fallback?: string; turns?: number };
+  budget?: { perDay?: string; perRun?: string };
+  tasks: string[];
+  access: string[];
+  triggers: { name: string; node?: string; wakes?: string; config?: Record<string, unknown> }[];
+  checkIn?: string;
+  memory?: { agent?: string };
+  askWhenUnsure?: string;
+  soul: string;
+  path: string;
+  /** Each skill in words, from its SKILL.md (server: devRoutes `withAbout`). */
+  skillsAbout?: { name: string; title: string; description: string }[];
+  /** Each marketplace MCP among its tasks, by URI, as its node names itself. */
+  mcpsAbout?: Record<string, { title: string; description: string }>;
+}
+
+const WAY_ICONS: Record<string, typeof Radio> = { spatial: Compass, slack: MessageSquare, email: Mail, voice: Mic, calendar: CalendarDays };
+const WAKES: Record<string, string> = { mentions: "wakes on a mention", replies: "wakes on a reply", events: "wakes when an event starts" };
+/** What a permission lets it reach, in words; the strict ones said plainly (AGENTS.md § 7a). */
+const ACCESS_WORDS: Record<string, string> = {
+  "signal:read-all": "Can see everyone in Signal",
+  "signal:write": "Can add people to Signal",
+};
+
+/** Triggers | › | the Agent | › | what it does: the skills row above shares these columns. */
+const COLUMNS = "minmax(0,1fr) auto minmax(0,1.1fr) auto minmax(0,1fr)";
+const LABEL = "mb-2 text-[10px] font-semibold uppercase tracking-wider text-gray-500";
+const TILE = "flex items-center gap-2.5 rounded-lg border border-gray-200 bg-white px-3 py-2";
+const GLYPH = "flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-gray-200 bg-white text-gray-800";
+
+/** `unoverse://tasks/<org>/<name>` → its name, and its org when it is not the Agent's own. */
+function taskLabel(uri: string, org: string): { name: string; from?: string } {
+  const m = /^unoverse:\/\/tasks\/([^/]+)\/(.+)$/.exec(uri);
+  if (!m) return { name: uri };
+  return m[1] === org ? { name: m[2] } : { name: m[2], from: m[1] };
+}
+
+/**
+ * `mailbox`: its connected address in this environment (never in the file), drawn on the triggers
+ * its mailbox serves; `says`, by trigger, whether each works here today; `onConnect`, when the
+ * viewer may connect one, puts Connect there.
+ */
+export function AgentChain({ agent: given, mailbox, says, onConnect, connecting }: { agent: AgentFolderItem; mailbox?: string | null; says?: Record<string, string>; onConnect?: () => void; connecting?: boolean }) {
+  // Every list may be absent (a hand-written file, an older server): drawn as empty, never a crash.
+  const agent: AgentFolderItem = {
+    ...given,
+    skills: given.skills ?? [],
+    tasks: given.tasks ?? [],
+    access: given.access ?? [],
+    triggers: given.triggers ?? [],
+    soul: given.soul ?? "",
+  };
+  const ways = agent.triggers;
+  // Its skills in words; a server that sends none still draws each by name.
+  const skills = agent.skillsAbout ?? agent.skills.map((name) => ({ name, title: name, description: "" }));
+  // What it does, in two kinds: its org's own tasks, then the marketplace MCPs it was given.
+  const mcps = agent.tasks.filter((uri) => agent.mcpsAbout?.[uri]);
+  const own = agent.tasks.filter((uri) => !agent.mcpsAbout?.[uri]);
+  return (
+    <>
+      {/* WHAT IT KNOWS: its skills, feeding into it from above */}
+      <div className="mb-1 grid gap-3" style={{ gridTemplateColumns: COLUMNS }}>
+        <div />
+        <ChevronRight size={18} className="invisible" />
+        <div>
+          <div className={LABEL}>Skills · how it works</div>
+          {skills.length === 0 && <div className="text-[12px] text-gray-500">None</div>}
+          <div className="flex flex-col gap-2">
+            {skills.map((k) => (
+              <div key={k.name} className="flex items-start gap-2.5 rounded-lg border border-dashed border-gray-300 bg-white px-3 py-2" title={k.name}>
+                <span className={GLYPH}><BookOpen size={15} strokeWidth={1.8} /></span>
+                <div className="min-w-0">
+                  <div className="truncate text-[13px] font-medium text-gray-900">{k.title}</div>
+                  {k.description && <div className="line-clamp-2 text-[11px] text-gray-500">{k.description}</div>}
+                </div>
+              </div>
+            ))}
+          </div>
+          <div className="flex justify-center py-1 text-gray-300"><ChevronDown size={18} /></div>
+        </div>
+        <ChevronRight size={18} className="invisible" />
+        <div />
+      </div>
+
+      {/* THE CHAIN: triggers → the Agent → what it does */}
+      {/* Top-aligned: the Agent sits right under its skills, however many tasks it has. */}
+      <div className="mb-6 grid items-start gap-3" style={{ gridTemplateColumns: COLUMNS }}>
+        <div className="flex flex-col gap-2">
+          <div className={LABEL}>Triggers · what wakes it</div>
+          {ways.length === 0 && <div className="text-[12px] text-gray-500">None yet</div>}
+          {ways.map((w) => {
+            const Icon = WAY_ICONS[w.name] ?? Radio;
+            const mail = w.node === "MailboxMCP";
+            return (
+              <div key={w.name} className={TILE}>
+                <span className={GLYPH}><Icon size={15} strokeWidth={1.8} /></span>
+                <div className="min-w-0 flex-1">
+                  <div className="truncate text-[13px] font-medium capitalize text-gray-900">{w.name}</div>
+                  <div className="truncate text-[11px] text-gray-500">{mail && mailbox !== undefined ? mailbox ?? "No mailbox connected" : says?.[w.name] ?? (w.name === "spatial" ? "found in Spatial" : [w.node, w.wakes ? WAKES[w.wakes] ?? w.wakes : null].filter(Boolean).join(", "))}</div>
+                </div>
+                {mail && onConnect && (
+                  <button type="button" disabled={connecting} onClick={onConnect} className="shrink-0 rounded-md border border-gray-300 bg-white px-2 py-1 text-[11px] font-medium text-gray-800 hover:bg-gray-50 disabled:opacity-50">
+                    {connecting ? "Connecting" : mailbox ? "Change" : "Connect"}
+                  </button>
+                )}
+              </div>
+            );
+          })}
+        </div>
+
+        <ChevronRight size={18} className="mt-14 text-gray-300" />
+
+        <div className="mt-6 rounded-xl border border-gray-300 bg-gray-50 p-4">
+          <div className="mb-3 flex items-center gap-3">
+            {agent.avatar && <img src={agent.avatar} alt="" className="h-12 w-12 shrink-0 rounded-full border border-gray-200 object-cover" />}
+            <div className="min-w-0">
+              <div className="text-[15px] font-semibold text-gray-900">{agent.title ?? agent.name}</div>
+              {agent.role && <div className="text-[12px] text-gray-600">{agent.role}</div>}
+            </div>
+          </div>
+          <div className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-[12px]">
+            <div className="text-gray-500">Model</div>
+            <div className="truncate font-mono text-gray-800">{agent.model?.use ?? "not set"}</div>
+            <div className="text-gray-500">Reasoning</div>
+            <div className="text-gray-800">{agent.model?.reasoning ?? "the model's default"}</div>
+            <div className="text-gray-500">Turns</div>
+            <div className="text-gray-800">{agent.model?.turns ? `${agent.model.turns} a run` : "the model's default"}</div>
+            <div className="text-gray-500">Budget</div>
+            <div className="text-gray-800">
+              {agent.budget?.perDay ? `${agent.budget.perDay} a day` : "not set"}
+              {agent.budget?.perRun ? `, ${agent.budget.perRun} a run` : ""}
+            </div>
+            <div className="text-gray-500">Memory</div>
+            <div className="text-gray-800">{agent.memory?.agent === "on" ? "its own" : "off"}</div>
+          </div>
+        </div>
+
+        <ChevronRight size={18} className="mt-14 text-gray-300" />
+
+        <div className="flex flex-col gap-2">
+          <div className={LABEL}>Tasks · what it does</div>
+          {agent.tasks.length === 0 && <div className="text-[12px] text-gray-500">None</div>}
+          {own.map((uri) => {
+            const t = taskLabel(uri, agent.org);
+            return (
+              <div key={uri} className={TILE} title={uri}>
+                <span className={GLYPH}><Workflow size={15} strokeWidth={1.8} /></span>
+                <div className="min-w-0">
+                  <div className="truncate text-[13px] font-medium text-gray-900">{t.name.replace(/-/g, " ")}</div>
+                  {t.from && <div className="truncate text-[11px] text-gray-500">from {t.from}</div>}
+                </div>
+              </div>
+            );
+          })}
+          {mcps.length > 0 && <div className={`${LABEL} mt-2`}>From the marketplace</div>}
+          {mcps.map((uri) => {
+            const m = agent.mcpsAbout![uri];
+            return (
+              <div key={uri} className={TILE} title={uri}>
+                <span className={GLYPH}><Plug size={15} strokeWidth={1.8} /></span>
+                <div className="min-w-0">
+                  <div className="truncate text-[13px] font-medium text-gray-900">{m.title}</div>
+                  {m.description && <div className="line-clamp-2 text-[11px] text-gray-500">{m.description}</div>}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* WHO IT IS */}
+      <div className={LABEL}>Soul</div>
+      {agent.soul.trim() ? (
+        <div className="mb-5 space-y-2 rounded-lg border border-gray-200 bg-gray-50 p-4 text-[13px] leading-relaxed text-gray-800">
+          {/* Paragraphs as written: a blank line parts them, a line break inside one is a space. */}
+          {agent.soul.trim().split(/\n\s*\n/).map((para, i) => (
+            <p key={i}>{para.replace(/\s*\n\s*/g, " ")}</p>
+          ))}
+        </div>
+      ) : (
+        <p className="mb-5 text-[12px] text-gray-500">No SOUL.md beside agent.yaml.</p>
+      )}
+
+      <div className={LABEL}>Access</div>
+      <div className="mb-5 flex flex-wrap gap-1.5">
+        {agent.access.length === 0 && <span className="text-[12px] text-gray-500">No one's information</span>}
+        {agent.access.map((a) => (
+          <span key={a} title={a} className="rounded-full border border-gray-200 bg-white px-2 py-0.5 text-[11px] text-gray-700">
+            {ACCESS_WORDS[a] ?? a}
+          </span>
+        ))}
+      </div>
+
+      <div className={LABEL}>Settings</div>
+      <div className="mb-5 grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 rounded-lg border border-gray-200 bg-gray-50 p-4 text-[12px] text-gray-800">
+        {agent.model?.reasoning && (<><div className="text-gray-500">Reasoning</div><div>{agent.model.reasoning}</div></>)}
+        {agent.model?.turns && (<><div className="text-gray-500">Turns</div><div>{agent.model.turns} a run</div></>)}
+        {agent.model?.fallback && (<><div className="text-gray-500">Fallback model</div><div className="font-mono">{agent.model.fallback}</div></>)}
+        <div className="text-gray-500">Check-in</div>
+        <div>{agent.checkIn ? `every ${agent.checkIn}` : "only when reached"}</div>
+        {agent.askWhenUnsure && (<><div className="text-gray-500">Asks when unsure</div><div>in {agent.askWhenUnsure}</div></>)}
+        <div className="text-gray-500">Email</div>
+        <div>its connected mailbox, set in Signal</div>
+        <div className="text-gray-500">Folder</div>
+        <div className="font-mono">{agent.path}</div>
+      </div>
+    </>
+  );
+}

package/screens/AgentsView.tsx

@@ -1,6 +1,7 @@
 /**
- * Agents view — the Agents a project authored (docs.unoverse.ai/design/tasks). Left: a
- * navigator. Right: the selected Agent's meta, its door, and the Available switch.
+ * Agents view — the Agents a project authored. Left: a navigator. Right: the selected Agent.
+ * An Agent in the one shape (agents/<name>/agent.yaml and its soul, AGENTS.md § 3) is drawn as a
+ * chain read off its file (AgentChain); an older flat Agent file shows its door until converted.
  *
  * An Agent is a workflow with no interface of its own, listed on the map so a conversation
  * can reach for it: the one thing authored for the map alone (`design/<org>/agents/<name>.yaml`).
@@ -13,6 +14,7 @@ import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-hos
 import { IdentityHeader } from "./IdentityHeader";
 import { DOC, EMPTY, NAV, NAV_SECTION, PANE, SCREEN, navItem } from "./chrome";
 import { EmptyLibrary } from "./EmptyLibrary";
+import { AgentChain, type AgentFolderItem } from "./AgentChain";
 
 interface AgentItem {
   /** `<org>/<name>`: the identity every registry row and toggle keys on. */
@@ -37,29 +39,57 @@ interface AgentItem {
 }
 
 const ACCENT = "#7c3aed";
+
+/**
+ * COPY FOR CANVAS, AN AGENT WITH A VOICE (AGENTS.md § 5: its `voice` trigger names the node). The
+ * canvas's own clipboard payload, as Components writes it: only her face (the voice-chat component,
+ * her portrait and name). Clicking it starts her call; she works where she was woken, so her tasks
+ * show on that canvas.
+ */
+export function agentForCanvas(a: AgentFolderItem) {
+  if (!a.triggers.some((t) => t.name === "voice" && t.node)) return null;
+  const name = a.title ?? a.name;
+  // ONE NODE, ITS FACE. Its voice and its work are its own (engine agentKeys/talk.ts): `agent` is
+  // its address, and clicking the face starts its call on this canvas.
+  const face = {
+    id: `${a.name}-face1`,
+    type: "Component",
+    position: { x: 0, y: 0 },
+    data: { label: name, status: "ready", agent: `unoverse://agents/${a.org}/${a.name}`, config: { component: "voice-chat", portrait: a.avatar ?? "", orbSize: "360", assistantName: name, tagline: a.role ?? "" } },
+    style: { width: 520 },
+    draggable: true,
+  };
+  return { type: "gravity-workflow", version: 2, nodes: [face], edges: [] };
+}
 /** An Agent's mark: a bot's head, antenna up, two eyes. */
 const AGENT_ICON = `data:image/svg+xml;utf8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="${ACCENT}" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="9" width="16" height="11" rx="3"/><path d="M12 9V5"/><circle cx="12" cy="4" r="1.2" fill="${ACCENT}"/><circle cx="9" cy="14.5" r="1.3" fill="${ACCENT}" stroke="none"/><circle cx="15" cy="14.5" r="1.3" fill="${ACCENT}" stroke="none"/><path d="M2 13v4M22 13v4"/></svg>`)}`;
 
 export function AgentsView({ org = "all" }: { org?: string } = {}) {
   const [agents, setAgents] = useState<AgentItem[]>([]);
+  // AGENTS IN THE ONE SHAPE (agents/<name>/agent.yaml, AGENTS.md § 3), beside the older files.
+  const [folders, setFolders] = useState<AgentFolderItem[]>([]);
   const available = useRegistryToggles("agent");
   const [selected, setSelected] = usePersistentState<string | null>("wb:agents:selected", null);
   const [error, setError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
 
   useEffect(() => {
     fetchUnoverse(`/dev/agents${org !== "all" ? `?org=${encodeURIComponent(org)}` : ""}`)
       .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
       .then((d) => {
         const list: AgentItem[] = d.items ?? [];
+        const own: AgentFolderItem[] = d.folders ?? [];
         setAgents(list);
-        const restore = list.find((a) => a.name === selected) ?? list[0];
-        setSelected(restore ? restore.name : null);
+        setFolders(own);
+        const keys = [...own.map((f) => f.ref), ...list.map((a) => a.name)];
+        setSelected(keys.includes(selected ?? "") ? selected : (keys[0] ?? null));
       })
       .catch((e) => setError(String(e?.message ?? e)));
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [org]);
 
   const detail = agents.find((a) => a.name === selected) ?? null;
+  const folder = folders.find((f) => f.ref === selected) ?? null;
 
   const byCategory = Object.entries(
     agents.reduce<Record<string, AgentItem[]>>((acc, a) => {
@@ -68,7 +98,7 @@ export function AgentsView({ org = "all" }: { org?: string } = {}) {
     }, {}),
   ).sort(([a], [b]) => a.localeCompare(b));
 
-  if (agents.length === 0) {
+  if (agents.length === 0 && folders.length === 0) {
     return (
       <div className={SCREEN}>
         <nav className={NAV} />
@@ -87,6 +117,24 @@ export function AgentsView({ org = "all" }: { org?: string } = {}) {
     <div className={SCREEN}>
       {/* NAVIGATOR */}
       <nav className={NAV}>
+        {folders.length > 0 && (
+          <div className="mb-3">
+            <div className={NAV_SECTION}>Agents</div>
+            {folders.map((f) => (
+              <button
+                key={f.ref}
+                onClick={() => setSelected(f.ref)}
+                className={`block w-full rounded px-2 py-1.5 text-left transition ${navItem(selected === f.ref)}`}
+              >
+                <div className="flex min-w-0 items-baseline gap-2 text-sm font-medium">
+                  <span className="min-w-0 flex-1 truncate">{f.title ?? f.name}</span>
+                  <span className="shrink-0 text-[10px] text-gray-500">{f.org}</span>
+                </div>
+                <div className="truncate text-[11px] text-gray-500">{f.role ?? f.description}</div>
+              </button>
+            ))}
+          </div>
+        )}
         {byCategory.map(([cat, items]) => (
           <div key={cat} className="mb-3">
             <div className={NAV_SECTION}>{cat}</div>
@@ -109,7 +157,38 @@ export function AgentsView({ org = "all" }: { org?: string } = {}) {
 
       {/* DETAIL */}
       <div className={PANE}>
-        {!selected || !detail ? (
+        {selected && folder ? (
+          <div className={DOC}>
+            <IdentityHeader
+              right={
+                <div className="flex items-center gap-3">
+                  {agentForCanvas(folder) && (
+                    <button
+                      onClick={async () => {
+                        await navigator.clipboard.writeText(JSON.stringify(agentForCanvas(folder), null, 2));
+                        setCopied(true);
+                        setTimeout(() => setCopied(false), 1600);
+                      }}
+                      className="rounded border border-gray-300 px-2 py-0.5 text-[11px] font-medium text-gray-600 transition hover:bg-gray-50"
+                      title="Copy this Agent, with its voice, for a canvas: paste (Cmd+V) on any workflow canvas"
+                    >
+                      {copied ? "✓ Copied, paste on canvas" : "⧉ Copy for Canvas"}
+                    </button>
+                  )}
+                  <ToggleSwitch on={available.isEnabled(selected)} onClick={() => available.toggle(selected)} label="Available" />
+                </div>
+              }
+              logoUrl={folder.avatar ?? AGENT_ICON}
+              accent={ACCENT}
+              name={folder.title ? `${folder.title}${folder.role ? `, ${folder.role}` : ""}` : selected}
+              category={folder.category}
+              version={folder.version}
+              description={folder.description}
+              whenToUse={folder.whenToUse}
+            />
+            <AgentChain agent={folder} />
+          </div>
+        ) : !selected || !detail ? (
           <div className={EMPTY}>Select an Agent</div>
         ) : (
           <div className={DOC}>

package/screens/SkillsView.tsx

@@ -14,6 +14,7 @@
  * "run". So this is a neutral chrome surface, not a themed render.
  */
 import { useEffect, useState } from "react";
+import Markdown from "markdown-to-jsx";
 import { fetchUnoverse } from "studio-host";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { IdentityHeader } from "./IdentityHeader";
@@ -182,9 +183,9 @@ export function SkillsView({ org = "all" }: { org?: string } = {}) {
             {loadingDetail && !detail ? (
               <div className="text-sm text-gray-500">Loading…</div>
             ) : (
-              <pre className="overflow-x-auto whitespace-pre-wrap rounded-lg border border-gray-200 bg-gray-50 p-4 font-mono text-[12.5px] leading-relaxed text-gray-800">
-                {detail?.instructions ?? ""}
-              </pre>
+              <div className="rounded-lg border border-gray-200 bg-white p-6 text-sm leading-relaxed text-gray-800">
+                <Markdown options={{ overrides: INSTRUCTION_STYLES }}>{detail?.instructions ?? ""}</Markdown>
+              </div>
             )}
 
             {detail?.contentHash && (
@@ -196,3 +197,20 @@ export function SkillsView({ org = "all" }: { org?: string } = {}) {
     </div>
   );
 }
+
+/** SKILL.md as it reads, not as it is typed: each markdown element styled for the pane. */
+const INSTRUCTION_STYLES = {
+  h1: { props: { className: "mb-3 text-lg font-semibold text-gray-900" } },
+  h2: { props: { className: "mb-2 mt-6 text-base font-semibold text-gray-900" } },
+  h3: { props: { className: "mb-2 mt-4 text-sm font-semibold text-gray-900" } },
+  p: { props: { className: "mb-3" } },
+  ul: { props: { className: "mb-3 list-disc space-y-1 pl-5" } },
+  ol: { props: { className: "mb-3 list-decimal space-y-1 pl-5" } },
+  a: { props: { className: "text-blue-600 underline" } },
+  code: { props: { className: "rounded bg-gray-100 px-1 py-0.5 font-mono text-[12px]" } },
+  pre: { props: { className: "mb-3 overflow-x-auto rounded-lg bg-gray-50 p-3 font-mono text-[12px] [&>code]:bg-transparent [&>code]:p-0" } },
+  table: { props: { className: "mb-3 w-full border-collapse text-left text-[13px]" } },
+  th: { props: { className: "border-b border-gray-200 px-2 py-1 font-semibold" } },
+  td: { props: { className: "border-b border-gray-100 px-2 py-1 align-top" } },
+  blockquote: { props: { className: "mb-3 rounded bg-gray-50 px-3 py-2 text-gray-600" } },
+};

package/screens/TemplatesLibraryView.tsx

@@ -14,7 +14,7 @@
  *
  * NOT TemplatesView.tsx: that name is taken by the Apps screen (the legacy noun).
  */
-import { useEffect, useMemo, useState, useSyncExternalStore, useCallback, type MouseEvent as ReactMouseEvent } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, useCallback, type MouseEvent as ReactMouseEvent } from "react";
 import { ComponentStore, type ResolvedTheme } from "@unoverse/sdk";
 import { UnoverseComponent } from "./react/unoverse";
 import { client, authedFetch, usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
@@ -56,6 +56,9 @@ interface TemplateDef {
   preview?: Record<string, string[]>;
   /** The components it holds, one stand-in per item of its own preview data, per state. */
   heldSeeds?: Record<string, { key: string; component: string; props: Record<string, unknown> }[]>;
+  /** The template's own props (the lists it holds, a picture a hook fills): their previews seed
+   *  the instance, so a layout-level Each has items to walk and a held card a spot to draw in. */
+  props?: Record<string, { preview?: unknown; default?: unknown } | null>;
 }
 
 const PREVIEW_CHAT = "preview";
@@ -184,7 +187,14 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
       type: "COMPONENT_INIT",
       chatId: PREVIEW_CHAT,
       nodeId: TEMPLATE_NODE,
-      component: { type: ref, componentUrl: `unoverse://templates/${ref}`, props: {} },
+      // ITS OWN PROPS, seeded as a part's are (`preview ?? default`): a template whose layout walks
+      // a list it holds drew nothing here, because the instance arrived empty while the held
+      // stand-ins beneath it waited for an Each that never ran (observed 2026-10-23).
+      component: {
+        type: ref,
+        componentUrl: `unoverse://templates/${ref}`,
+        props: Object.fromEntries(Object.entries(current.props ?? {}).map(([k, v]) => [k, v?.preview ?? v?.default]).filter(([, v]) => v !== undefined)),
+      },
     });
     const base = current.defaultLayout ?? (current.layouts ? Object.keys(current.layouts)[0] : undefined);
     if (base) store.mergeComponentState(PREVIEW_CHAT, TEMPLATE_NODE, { state: base });
@@ -246,6 +256,25 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
     if ((own?.state ?? own?.view ?? own?.defaultState) !== activeState) store.mergeComponentState(PREVIEW_CHAT, TEMPLATE_NODE, { state: activeState });
   }, [store, holdsItems, activeState]);
 
+  // A VIEW OPENING RUNS THE HOOK SCOPED TO IT (docs/design/lifecycle-hooks.md), as the app's stream
+  // would: the template's own fields so far as `props`, the state as the layout entered, and what
+  // comes back merged into the instance. Once per view per template; a host with no universe
+  // to run it (local Studio) fails quietly and the preview keeps its stand-ins.
+  const ranHooks = useRef(new Set<string>());
+  useEffect(() => {
+    if (!uri || !activeState || !client.runTask) return;
+    const key = `${uri}#${activeState}`;
+    if (ranHooks.current.has(key)) return;
+    ranHooks.current.add(key);
+    const own = (store.get(PREVIEW_CHAT, TEMPLATE_NODE) ?? {}) as Record<string, unknown>;
+    client
+      .runTask(uri, "onEnterView", own, activeState)
+      .then((fields) => {
+        if (fields && Object.keys(fields).length) store.mergeComponentState(PREVIEW_CHAT, TEMPLATE_NODE, fields);
+      })
+      .catch((e: unknown) => console.warn(`[studio] ${uri} onEnterView(${activeState}) did not run:`, e));
+  }, [store, uri, activeState]);
+
   // GROUPED BY CATEGORY, exactly as Components groups its rail — the shelf is no longer a
   // flat list the moment small templates land on it (the `Blocks` shelf: pair, feature,
   // single, rail, stack, statement) and a page has to be found among them. The category is
@@ -480,7 +509,7 @@ export function TemplatesLibraryView({ theme, org }: { theme: ResolvedTheme; org
             );
           })()}
 
-          <div className="flex-1 overflow-auto p-10">
+          <div data-print-stage className="flex-1 overflow-auto p-10">
             <div className="mx-auto max-w-full transition-[width] duration-200" style={{ width: stageWidth ?? "100%" }}>
               {uri && <UnoverseComponent key={uri} client={client} store={store} chatId={PREVIEW_CHAT} nodeId={TEMPLATE_NODE} theme={theme} />}
             </div>

package/screens/TemplatesView.tsx

@@ -32,7 +32,7 @@ import { NAV, NAV_SECTION, SCREEN, navItem, navSubItem } from "./chrome";
 
 // Per-APP test conversation: each app chats in its own conversation id, so testing
 // one client's app never inherits another's agent history/memory (the "BPP answers
-// about SAB" trap — same workflow, polluted shared context).
+// about a bank" trap — same workflow, polluted shared context).
 // …and a fresh conversation per PAGE LOAD: the nonce is minted once per module load,
 // so refreshing the page naturally starts a NEW conversation (fresh agent thread,
 // fresh durable surfaces) — history never outlives the screen it happened on.
@@ -373,7 +373,7 @@ export function TemplatesView({
     const base = store.getTimeline().length === 0 ? "isEmpty" : "hasMessages";
     return states.find((s) => s.when === base)?.name ?? null;
   }, [storeVersion, store, selectedDef]);
-  // The preview renders under the SELECTED APP'S ORG theme — a SAB app is SAB-red, a
+  // The preview renders under the SELECTED APP'S ORG theme — a a bank app is a bank-red, a
   // BPP app cobalt, whatever the header org scope shows. The header toggle picks the
   // light/dark variant; the app's org picks whose brand. Falls back to the app-level
   // theme until the fetch resolves (or for org-less templates).