@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/definitions/registry/catalog.ts

@@ -0,0 +1,659 @@
+/**
+ * The CATALOG: listing every kind, app manifests, and the state-order/state-entry
+ * projections Studio and the workbench read. Split from definitions.ts 2026-08-29.
+ * Imports the load core lazily at call time — the definitions⇄catalog cycle is
+ * function-level only and safe under ESM live bindings.
+ */
+
+import { readdirSync, existsSync, statSync } from "fs";
+import { join } from "path";
+import { readDefCached, defPath, isDefFile, defName, dirSignature, cachedBySignature } from "../fsCache.js";
+import { SHARED_DIR, appDirs, templateDirs, componentDirs, resolveComponentDirs, parseRef, projectDir, listOrgs } from "./homes.js";
+import type { UnoverseDefinition } from "../model.js";
+import { normalizeDeclaredKind, defaultLayoutOf } from "../model.js";
+import { loadDefinition } from "../load/load.js";
+import { expandNode } from "../load/expand/index.js";
+
+/** List definitions of a kind. Atoms come from the ONE shared home. Components come
+ *  from the marketplace PLUS the org packs — every org's when `org` is omitted
+ *  (each tagged), or just `org`'s own + the shared tier when given (org-private:
+ *  another org's components are never listed into an org-scoped view). Templates
+ *  come from `org`'s folder, or every org's (each tagged). */
+export function listDefinitions(kind: "component" | "app" | "atom" | "template", org?: string): UnoverseDefinition[] {
+  const out: UnoverseDefinition[] = [];
+  const dirs =
+    kind === "app" ? appDirs(org ?? null)
+    : kind === "component" ? componentDirs(org ?? null)
+    : kind === "template" ? templateDirs(org ?? null)
+    : [{ org: undefined as string | undefined, dir: SHARED_DIR[kind] }];
+  for (const { org: o, dir } of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      // PER-ENTRY ISOLATION: a definition MID-EDIT (a saved layout referencing a
+      // states/ file not written yet, malformed JSON) is a normal state of a
+      // live-editing platform. One broken definition must degrade to a skipped
+      // entry with a warning — never fail the whole catalog request (observed
+      // live: an in-flight template edit 500'd /dev/apps for every org).
+      try {
+        if (e.isFile() && isDefFile(e.name)) {
+          /**
+           * A FLAT FILE IS LOADED, NOT READ (2026-08-31).
+           *
+           * This handed the RAW yaml straight to every caller while the folder branch below
+           * composed properly — so a flat definition reached the workbench with none of its
+           * compiled projections: no `layouts`, no `sections`, and its three words still
+           * sitting there as words. A flat BLOCK (`pair`, `feature`) therefore listed by
+           * name and drew as an empty stage, because the screen seeds its preview from
+           * `sections` and there were none. Everything that verified the block used
+           * `loadDefinition`; the screen used this, and the two disagreed.
+           *
+           * ATOMS keep the raw read. They are leaf vocabulary with no projections to
+           * compile, and the FILENAME has to travel: refs address a file atom by its
+           * basename, so the catalogue must name it the same way or an installed atom is
+           * unreachable.
+           */
+          const name = defName(e.name);
+          const loaded = kind === "atom" ? null : loadDefinition(o ? `${o}/${name}` : name, kind);
+          if (loaded) {
+            out.push({ ...loaded, file: e.name } as UnoverseDefinition);
+          } else {
+            const raw = readDefCached<UnoverseDefinition>(join(dir, e.name));
+            const withFile = { ...raw, file: e.name } as UnoverseDefinition;
+            normalizeDeclaredKind(withFile);
+            out.push(o ? { ...withFile, org: o } : withFile);
+          }
+        } else if (e.isDirectory()) {
+          const d = loadDefinition(o ? `${o}/${e.name}` : e.name, kind); // composes the folder ($include + refs)
+          if (d) out.push(d);
+        }
+      } catch (err) {
+        console.warn(
+          `[unoverse] skipping ${kind} '${o ? `${o}/` : ""}${e.name}' — failed to load (mid-edit?): ${(err as Error)?.message ?? err}`,
+        );
+      }
+    }
+  }
+  return out.filter((d) => d.kind === kind);
+}
+
+// ---- MCP apps: a template folder + a manifest.json (UNOVERSE_MCP_APP_PROTOCOL §4b) ----
+//
+// An MCP app is JUST a manifest: self-describing (name/description/category for discovery
+// + selection) and self-running (it OWNS its workflow binding — the §6a flip). Loading an
+// app = trigger the binding → the workflow streams component(s) back → the SDK renders
+// them (no per-app shell; rendering the stream is generic). `template` is OPTIONAL, only
+// for an app that wants fixed layout/chrome. The manifest is also the future
+// spatial-ingestion record.
+
+/** An MCP app manifest — `design/<org>/apps/<id>/manifest.yaml`. */
+export interface AppManifest {
+  /** App id = the folder name (the app URI is `unoverse://apps/<org>/<id>`). */
+  id: string;
+  /** The org tree that serves this app (injected from the folder location, never
+   *  hand-written). Channels use it to address the app's theme (`<org>/light`). */
+  org?: string;
+  name: string;
+  /** WHICH TIER THE DELIVERABLE LIVES IN — the home its definition is loaded from, and the
+   *  home its address names (`componentUri`: "the address says WHAT it is"). Absent =
+   *  component, the tier every app tool had until the Template Model shipped a second one.
+   *
+   *  NOT `type`, which is the legacy full-surface/inline ROUTER word (`type: "template"`
+   *  means a fluid-height app, and says nothing about where its definition lives). Two
+   *  meanings on one field is how a template app would come to be loaded as a component and
+   *  fail with a resolver error nobody could read. */
+  kind?: "component" | "template";
+  /** Human display name; falls back to `name`. */
+  title?: string;
+  description?: string;
+  /** Spatial-discovery selection text — see UnoverseDefinition.whenToUse. */
+  whenToUse?: string;
+  category?: string;
+  version?: string;
+  /** The app's named DEFAULT STATE on load — the single authored field. An OPEN name, not a
+   *  closed enum: apps/channels recognize it by NAME (Switch/visibleWhen), so new states
+   *  need zero protocol change (UNOVERSE_MCP_APP_PROTOCOL §4b). The known names today:
+   *  - "app":       fluid height — the app fills/swaps the whole surface (chat/voice shells)
+   *  - "focus":     fit-to-content AND opens in focus (large overlay) on load (wizards)
+   *  - "component": renders INLINE in the conversation like any card — no focus, no takeover
+   *  Any other name: fit-to-content; the org's apps define what the name renders as.
+   *  `type` + `fluidHeight` below are LEGACY and DERIVED in `loadAppManifest` (full surface ⇒
+   *  type:template + fluid · anything else ⇒ type:component + fit) so existing consumers keep
+   *  reading them unchanged. Author `defaultState`; never set `type`/`fluidHeight` by hand.
+   *  ("template" is the pre-rename spelling of "app", normalized on read; `mode` is the
+   *  pre-rename alias of this whole field, also still read as a fallback.) */
+  defaultState?: string;
+  /** @deprecated pre-rename alias of `defaultState`; read as fallback, never author. */
+  mode?: string;
+  /** @deprecated derived from `defaultState`. The router branch (swap vs inline). */
+  type?: "template" | "component";
+  /** OPTIONAL layout shell template name. Default: none — the SDK renders the raw
+   *  component stream. Set this only when the app wants fixed layout/chrome. */
+  template?: string;
+  /** The DEFAULT LAYOUT — the layouts/<name>.json used as the def's root when the
+   *  envelope authors none (standard folder anatomy). Default: "main". */
+  layout?: string;
+  /** A native service the template binds (UNOVERSE_SPEC §2e-1) — e.g. "voice". The
+   *  channel instantiates the matching service and feeds its state into the scope.
+   *  Manifest-authored so a manifest-only template (no envelope) still declares it. */
+  service?: string;
+  /** Display icon URL (square; shown in catalogs/drawers — never embedded). */
+  icon?: string;
+  /** How to call it — JSON Schema for the input params. */
+  inputSchema?: Record<string, unknown>;
+  /** What to run — the app owns its workflow binding (app ≡ workflow). `autoTrigger`
+   *  lives INSIDE it (owner ruling 2026-08-28: the load mode is part of the feed, so
+   *  the binding block carries it); the loader lifts it to the top-level field every
+   *  existing consumer reads. */
+  binding?: { workflow?: string; trigger?: string; autoTrigger?: boolean };
+  /** Load mode. true = on load, read the template AND fire the workflow (read resource +
+   *  call tool). false/absent = just load the template (read resource), wait for the
+   *  user. DERIVED from `binding.autoTrigger` on read; the top-level spelling remains
+   *  legacy-readable. */
+  autoTrigger?: boolean;
+  /** Publish this app on the EXTERNAL MCP endpoint. OPT-IN: absent/false keeps the app off
+   *  `/mcp` and `/mcp/{org}` entirely (no tool, no template listing) — only `makeMCP: true`
+   *  reaches an outside client. Default-deny, so a new app is never externally callable by
+   *  accident; publishing is always a deliberate line in the manifest.
+   *  Visibility ONLY: orthogonal to auth, which is decided by the workflow's trigger toggle
+   *  (`isPublicEntry`). The org URL picks WHICH SET a connector sees; this picks what is in
+   *  that set at all. */
+  makeMCP?: boolean;
+  /** Asset origins this app's content loads (images, media) — e.g. the org's image CDN.
+   *  Authored per app in manifest.yaml; the server UNIONS them across the connector's
+   *  published apps into the MCP-app shell's CSP (`ui.csp.resourceDomains`). A sandboxed
+   *  host builds its img-src from that list and blocks everything else, so an origin
+   *  missing here renders as broken images in ChatGPT/Claude while working in our own
+   *  hosts. Full origins with scheme, wildcards allowed: "https://*.datocms-assets.com". */
+  assetDomains?: string[];
+  /** Render lifetime (docs/design/04 §Two lifetimes). Default "turn": the instance returns
+   *  to inline/retires on the next user turn (the universal reset). "conversation" = a
+   *  DURABLE conversation-scoped surface (a cart, an itinerary, a composed page): keyed by
+   *  the CONVERSATION (not the turn) so every re-call hydrates the same slice, and the
+   *  client's new-turn reset skips it — it stays on screen until replaced or closed. */
+  lifetime?: "turn" | "conversation";
+  /* NO `latch` HERE (moved 2026-08-31, MCP guide §The Component Latch). It was a manifest
+   * field seeded onto the slice with every render, which said one thing about a component
+   * for the whole of its life; a page is addressable when it is THE PAGE and not when it
+   * is a summary in the flow, and the state is what knows that. It is now declared on the
+   * app's state and compiled to `def.latches` — a fact the client looks up, not one the
+   * server has to send. */
+  /** Workbench MOCK: what each STATE's preview seeds — `{ "<state>": ["course-card",
+   *  "course-card"] }` (a repeated name = several instances, e.g. a card rail). The
+   *  author decides per state; the seeded instances are written INTO that state's view
+   *  (the same setValue the runtime performs). Not used in LIVE — the workflow decides. */
+  preview?: Record<string, string[]>;
+  /** LEGACY workbench mock hint (pre-`preview`): a flat component list seeded for any
+   *  reaction state. Superseded by `preview` — kept as the fallback. */
+  previewComponents?: string[];
+  /** Layout height mode. Absent/true = FLUID: the template fills the available height
+   *  (chat / assistant / voice layouts). false = size to CONTENT: the frame shrinks to the
+   *  rendered component (focused widget apps like Bank Transfer). */
+  fluidHeight?: boolean;
+  /** The app's layer views — AUTO-DERIVED from its `states/` folder (UNOVERSE_LAYERS.md §7),
+   *  NOT hand-written in manifest.json. Injected by `loadAppManifest` so the SERVED manifest
+   *  makes external MCP callers aware of the states with zero drift (folder = source of truth). */
+  states?: StateEntry[];
+}
+
+/** THE FULL-SURFACE STATE. One name, no alias: `"app"`. The pre-rename spelling
+ *  `"template"` is NOT read anywhere — a second accepted spelling is a second code path,
+ *  and those drift into bugs that are miserable to find. A folder still saying "template"
+ *  is a folder to migrate, not a case to handle. */
+export const FULL_SURFACE_STATE = "app";
+
+/** `defaultState` is the authored field (open NAME; `mode` = pre-rename alias); derive the
+ *  legacy `type`/`fluidHeight` the rest of the system still reads (and back-derive
+ *  `defaultState` for any manifest still on the old fields). */
+function normalizeMode(m: AppManifest): AppManifest {
+  // `type: app` is the ARTIFACT DECLARATION (the authored word, 2026-08-28), not the
+  // legacy router field this function derives — strip it before the legacy read so a
+  // declaration can never impersonate a router value.
+  if ((m as { type?: string }).type === "app") {
+    const { type: _declaration, ...rest } = m as AppManifest & { type?: string };
+    m = rest as AppManifest;
+  }
+  const declared = m.defaultState ?? m.mode;
+  if (declared === FULL_SURFACE_STATE) return { ...m, defaultState: declared, type: "template", fluidHeight: true };
+  // Every other name (focus, component, anything future) is an inline/fit app at the router
+  // level — same branch (type:component). What the NAME renders as is the channel's and the
+  // org's apps' business (they branch on `defaultState` by name); e.g. the channel opens the
+  // focus overlay for "focus" and must NOT for "component".
+  if (declared) return { ...m, defaultState: declared, type: "component", fluidHeight: false };
+  // Legacy manifest (no authored field): infer, so new consumers read `defaultState` uniformly.
+  const inferred = m.type === "component" || m.fluidHeight === false ? "focus" : FULL_SURFACE_STATE;
+  // Derive the legacy fields here too: an unauthored manifest (the normal case now —
+  // `defaultState: app` is the default and never written) must still read as a
+  // full-surface app to every legacy `type`/`fluidHeight` consumer.
+  return inferred === FULL_SURFACE_STATE
+    ? { ...m, defaultState: inferred, mode: inferred, type: "template", fluidHeight: true }
+    : { ...m, defaultState: inferred, mode: inferred, type: "component", fluidHeight: false };
+}
+
+/** The definition folder for a ref: the shared home for components/atoms, the ref's
+ *  org (or the compat scan) for templates. */
+function findFolder(kind: "component" | "app" | "atom", ref: string): { folder: string; org?: string } | null {
+  const { org: refOrg, name } = parseRef(ref);
+  const lower = name.toLowerCase();
+  if (kind === "atom") {
+    const folder = join(SHARED_DIR.atom, lower);
+    return existsSync(folder) && statSync(folder).isDirectory() ? { folder } : null;
+  }
+  const dirs =
+    kind === "app" ? appDirs(refOrg) : resolveComponentDirs(componentDirs(refOrg), refOrg, lower);
+  for (const { org, dir } of dirs) {
+    const folder = join(dir, lower);
+    if (existsSync(folder) && statSync(folder).isDirectory()) return { folder, ...(org ? { org } : {}) };
+  }
+  return null;
+}
+
+/** Load one app manifest by `<org>/<id>` (bare id = legacy compat scan). The served
+ *  manifest carries its `org` (a projection from the folder location, like `states` —
+ *  never hand-written); the app's URI is `unoverse://apps/<org>/<id>`. */
+export function loadAppManifest(ref: string): AppManifest | null {
+  const hit = findFolder("app", ref);
+  if (!hit) return null;
+  const path = defPath(hit.folder, "manifest");
+  if (!path) return null;
+  const m = readDefCached<AppManifest>(path);
+  const id = parseRef(ref).name.toLowerCase();
+  // THE CONTAINER BRIDGE (UNOVERSE_INTERFACE_MODEL §4): binding, inputSchema and
+  // autoTrigger belong to a CONTAINER STATE now (the chat state that runs the advisor
+  // owns its own schema). Until per-container send routing lands, the app-level readers
+  // (the MCP app tool, live Studio) keep working by LIFTING the first workflow-bearing
+  // container state's contract when the app authored no top-level copy.
+  const containers = (m as { templates?: Record<string, { binding?: { workflow?: string; trigger?: string; autoTrigger?: boolean; inputSchema?: unknown }; workflow?: string; trigger?: string; autoTrigger?: boolean; inputSchema?: unknown; states?: Record<string, { workflow?: string; trigger?: string; autoTrigger?: boolean; inputSchema?: unknown }> }> }).templates;
+  let lifted: { binding?: { workflow?: string; trigger?: string }; inputSchema?: Record<string, unknown>; autoTrigger?: boolean } = {};
+  if (containers && !(m as { binding?: unknown }).binding) {
+    for (const c of Object.values(containers)) {
+      const carriers = [...(c.binding ? [c.binding] : []), c, ...Object.values(c.states ?? {})];
+      const w = carriers.find((x) => typeof x.workflow === "string" && x.workflow);
+      if (w) {
+        lifted = {
+          binding: { workflow: w.workflow, ...(w.trigger ? { trigger: w.trigger } : {}) },
+          ...(w.inputSchema ? { inputSchema: w.inputSchema as Record<string, unknown> } : {}),
+          ...(typeof w.autoTrigger === "boolean" ? { autoTrigger: w.autoTrigger } : {}),
+        };
+        break;
+      }
+    }
+  }
+  // `states` is AUTO-DERIVED from the states/ folder — never hand-written in manifest.json —
+  // so the SERVED manifest (MCP `resources/read unoverse://apps/{org}/{id}`, discovery) carries
+  // the app's layer views with zero drift. The folder stays the source of truth (§7).
+  // `autoTrigger` is authored INSIDE `binding:`; lift it to the top-level field the
+  // consumers read (an explicit top-level line, the legacy spelling, still wins).
+  const bindingAuto =
+    m.autoTrigger === undefined && typeof m.binding?.autoTrigger === "boolean"
+      ? { autoTrigger: m.binding.autoTrigger }
+      : {};
+  return normalizeMode({ ...lifted, ...bindingAuto, ...m, id, org: hit.org, states: listStates("app", `${hit.org}/${id}`) });
+}
+
+/** Load a COMPONENT as a native MCP app (UNOVERSE_MCP_APP_PROTOCOL §0.1 path B): a
+ *  universal component folder (`rx/components/<id>`) with a `manifest.json` IS a native MCP
+ *  app whose deliverable is the component itself — the server registers it right alongside
+ *  template apps. No `binding` by default (calling it just renders the component + runs the
+ *  `outputs` elicitation); a `binding` MAY be authored to ALSO fire a workflow (optional,
+ *  binding-agnostic handler). `previewComponents` defaults to the component's own id so the
+ *  app-tool handler resolves ITS `outputs` (the elicitation schema) with no handler change. */
+export function loadComponentApp(id: string, org?: string): AppManifest | null {
+  const lower = id.toLowerCase();
+  // TWO TIERS: marketplace (`rx/components/<id>`) or, with an org, the client's own
+  // microapp (`rx/orgs/<org>/components/<id>`) — org in the address, always.
+  const home = org ? join(projectDir(org), "components") : SHARED_DIR.component;
+  const path = defPath(join(home, lower), "manifest");
+  if (!path) return null;
+  const m = readDefCached<AppManifest>(path);
+  return normalizeMode({
+    ...m,
+    id: lower,
+    // Component manifests carry `title`, not `name` — default it so every consumer
+    // (tool registration, referee/mirror text "call <name> again") has a display name.
+    name: m.name ?? m.title ?? lower,
+    ...(org ? { org } : {}),
+    // Default load mode = focus (interactive widgets); author `defaultState` to override.
+    defaultState: m.defaultState ?? m.mode ?? "focus",
+    // The deliverable IS this component — point the handler's outputs/elicitation lookup
+    // at it, by the QUALIFIED ref for an org component: two orgs may share the bare name,
+    // and the bare form here took every /mcp initialize down with the resolver's
+    // ambiguity error (observed live, bppunoverse 2026-08-20).
+    previewComponents: m.previewComponents?.length ? m.previewComponents : [org ? `${org}/${lower}` : lower],
+    states: listStates("component", org ? `${org}/${lower}` : lower),
+  });
+}
+
+/** Load a TEMPLATE MODEL template as a native MCP app — the third path, beside the manifest
+ *  app and the component app. A template folder (`design/<org>/templates/<id>`) with a
+ *  `manifest.yaml` IS an app whose deliverable is the page: the agent fills its parts in ONE
+ *  call and the server renders it.
+ *
+ *  IT WAS NOT ONE UNTIL 2026-08-31, and nothing said so. Templates are discovered (spatial
+ *  carries their rows), read (`unoverse://templates/…` serves the definition) and SCHEMA'd
+ *  (`…/schema` compiles the page's parts) — every surface but the one that answers the call.
+ *  So an agent could find a page, be handed its contract, compose every part of it, and then
+ *  be told the tool does not exist. Observed live: a fully composed Perfect Day, -32602 at the
+ *  door. The kind travels on the manifest as `kind` so the render path loads the definition
+ *  from the right tier; `type` is the legacy full-surface/inline router word and says nothing
+ *  about which home a definition lives in. */
+export function loadTemplateApp(id: string, org?: string): AppManifest | null {
+  const lower = id.toLowerCase();
+  // TWO TIERS, like components: the marketplace shelf (`design/marketplace/templates`) or
+  // an org's own (`design/<org>/templates`). A shelf template carries no org, and its tool
+  // id is the bare name.
+  const home = org ? join(projectDir(org), "templates") : SHARED_DIR.template;
+  const path = defPath(join(home, lower), "manifest");
+  if (!path) return null;
+  const m = readDefCached<AppManifest>(path);
+  return normalizeMode({
+    ...m,
+    id: lower,
+    ...(org ? { org } : {}),
+    // Template manifests carry `title`, never `name` (the folder is the name).
+    name: m.name ?? m.title ?? lower,
+    kind: "template",
+    // A DURABLE SURFACE by nature: a composed page is refined across turns, and every
+    // refinement must hydrate the same instance rather than stack a new page per message.
+    lifetime: m.lifetime ?? "conversation",
+    // The deliverable IS this template — the render path resolves the definition from this
+    // ref, in the tier `kind` names.
+    previewComponents: m.previewComponents?.length ? m.previewComponents : [org ? `${org}/${lower}` : lower],
+  });
+}
+
+/** List MCP apps — every TEMPLATE app (one org's, or all orgs') PLUS every universal
+ *  COMPONENT app (a component with a manifest.json). Both are native MCP app tools.
+ *
+ *  MEMOIZED ON THE TREE'S SIGNATURE, like every other catalogue read. This walk (every
+ *  org's apps, components and templates, a manifest load per entry) ran on every MCP
+ *  initialize, twice per anonymous MCP message, on every app open and every sitetool
+ *  read, and nothing in it changes between requests except when a file is edited. The
+ *  returned array is SHARED: callers read it (find/filter/map), never mutate it. */
+export function listApps(org?: string): AppManifest[] {
+  const orgsToWalk = org != null ? [org] : listOrgs();
+  const dirs = [
+    ...appDirs(org ?? null).map((d) => d.dir),
+    ...(org == null ? [SHARED_DIR.component] : []),
+    ...orgsToWalk.map((o) => join(projectDir(o), "components")),
+    ...templateDirs(org ?? null).map((d) => d.dir),
+  ];
+  return cachedBySignature(`apps:${org ?? "*"}`, dirSignature(dirs), () => walkApps(org, orgsToWalk));
+}
+
+function walkApps(org: string | undefined, orgsToWalk: string[]): AppManifest[] {
+  const out: AppManifest[] = [];
+  // PER-ENTRY ISOLATION (same law as listDefinitions): this list is built INSIDE MCP
+  // server construction, so one unloadable app taking the walk down means EVERY
+  // initialize on every door answers -32603 (observed live: one ambiguous bare ref
+  // dropped the whole universe, 2026-08-20). One broken app degrades to a skipped
+  // entry with a warning, never a dead platform.
+  const push = (load: () => AppManifest | null, label: string) => {
+    try {
+      const m = load();
+      if (m) out.push(m);
+    } catch (err) {
+      console.warn(`[unoverse] skipping app '${label}' — failed to load: ${(err as Error)?.message ?? err}`);
+    }
+  };
+  // APP homes, not template homes: the 2026-08-28 rename split templateDirs (the new
+  // Template Model kind) from appDirs (the org apps/ folders) — this walk kept calling
+  // templateDirs and silently lost every manifest app (bpp-chat/bpp-voice gone, no
+  // makeMCP anywhere → every anonymous lane 401'd; observed live 2026-08-28).
+  for (const { org: o, dir } of appDirs(org ?? null)) {
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      push(() => loadAppManifest(`${o}/${e.name}`), `${o}/${e.name}`);
+    }
+  }
+  // DESIGN-SYSTEM component apps carry no org — include them whenever we're listing all
+  // apps (no org filter), so the MCP server registers them as native app tools.
+  if (org == null && existsSync(SHARED_DIR.component)) {
+    for (const e of readdirSync(SHARED_DIR.component, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      push(() => loadComponentApp(e.name), e.name);
+    }
+  }
+  // ORG component apps (`rx/orgs/<org>/components/<id>` + manifest.json) — the client's
+  // own microapps ARE apps too; without this walk their /mcp tools are never registered
+  // and a discovered org component fails with "Tool <id> not found" (observed live:
+  // PerfectDay after the two-tier move). Tool id stays the bare component id (names are
+  // unique across tiers, lint-enforced); the org rides on the manifest for addressing.
+  for (const o of orgsToWalk) {
+    const dir = join(projectDir(o), "components");
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      push(() => loadComponentApp(e.name, o), `${o}/${e.name}`);
+    }
+  }
+  // TEMPLATE MODEL templates (`design/<org>/templates/<id>`). ASKED FOR, not spelled out:
+  // `templateDirs` is the same enumerator the loader and the catalog walk, so a new org and
+  // a home that moves are covered here the moment they are covered there. Without this walk
+  // a discovered page is uncallable — the agent composes it and the door answers -32602,
+  // which is exactly what the org-component walk above was added to fix, one tier later.
+  for (const { org: o, dir } of templateDirs(org ?? null)) {
+    // The shelf (o === undefined) rides along only on an unfiltered list, exactly as the
+    // design-system component apps above do: an org-scoped door lists that org's own.
+    if (!existsSync(dir) || (!o && org != null)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      push(() => loadTemplateApp(e.name, o), `${o}/${e.name}`);
+    }
+  }
+  return out;
+}
+
+/** A layer view enumerated from a definition's `states/` folder (UNOVERSE_LAYERS.md §7:
+ *  the folder IS the registry). `when` = the state's root `visibleWhen` selector, so a
+ *  viewer can both LIST and ACTIVATE it (set the discriminant that shows it). */
+export interface StateEntry {
+  name: string;
+  when?: unknown;
+  /** The state root's `select.where` (a reaction-contract surface, STATE_MODEL §5b) —
+   *  the viewer activates it by writing `{field: eq}` into a component's slice. */
+  where?: unknown;
+}
+
+/** The order states are referenced from the root `<name>` definition (its `$include:
+ *  "states/…"` sequence — `Switch` cases / children order). The ROOT declares the order;
+ *  reorder the includes and the list reorders. Unreferenced states fall to the end. */
+function stateOrder(kind: "app" | "component", ref: string): string[] {
+  const lower = parseRef(ref).name.toLowerCase();
+  const hit = findFolder(kind, ref);
+  if (!hit) return [];
+  // An EXPLICIT authored order ranks FIRST (v2: the manifest `stateOrder` is the
+  // REACTION-state priority ladder — STATE_MODEL §5 rule 5 — and lists only those).
+  // States it does not name (the base arrangement's private substates, welcome/
+  // conversation) rank AFTER it, in the order the STRUCTURE includes them — the
+  // walk below — so the first included substate is the viewer's landing default.
+  const explicit: string[] = [];
+  const manifestPath = defPath(hit.folder, "manifest");
+  {
+    type TreeStates = Record<string, { states?: Record<string, unknown> } | null>;
+    const m = manifestPath ? readDefCached<{ stateOrder?: unknown; states?: TreeStates; layout?: string }>(manifestPath) : undefined;
+    // ONE FOLDER GRAMMAR (owner ruling 2026-08-29): the ENVELOPE (`<name>.yaml`)
+    // is the tree's home; the manifest's `states:` block is the legacy read.
+    const envPath = defPath(hit.folder, lower);
+    const envStates = envPath ? readDefCached<{ states?: TreeStates }>(envPath).states : undefined;
+    const states = envStates && typeof envStates === "object" && !Array.isArray(envStates) ? envStates : m?.states;
+    // THE TEMPLATE TREE ranks everything by declaration: reaction states (top-level
+    // minus the base) in order, then the base's substates in order — welcome first
+    // because it is declared first. Supersedes an authored stateOrder.
+    if (states && typeof states === "object" && !Array.isArray(states)) {
+      const names = Object.keys(states);
+      const base = defaultLayoutOf({ layout: m?.layout, states });
+      return [
+        ...names.filter((n) => n !== base),
+        ...Object.keys((states[base] as { states?: Record<string, unknown> } | null)?.states ?? {}),
+      ];
+    }
+    if (Array.isArray(m?.stateOrder)) explicit.push(...m.stateOrder.filter((n): n is string => typeof n === "string"));
+  }
+  // The structural walk starts at the envelope when one exists; a MANIFEST-ONLY
+  // template (no envelope) starts at its default layout — that is where its
+  // states/ are actually included from (via the shared chrome), so the include
+  // order still ranks the base's substates (welcome before conversation).
+  let rootPath = defPath(hit.folder, lower);
+  if (rootPath) {
+    const rootDef = readDefCached<{ stateOrder?: unknown }>(rootPath);
+    if (!explicit.length && Array.isArray(rootDef?.stateOrder))
+      explicit.push(...rootDef.stateOrder.filter((n): n is string => typeof n === "string"));
+  } else {
+    const m2 = manifestPath ? readDefCached<{ layout?: string; states?: Record<string, { layout?: unknown } | null> }>(manifestPath) : null;
+    const dflt = m2 ? defaultLayoutOf(m2) : "main";
+    // The base state's DECLARED path wins (2026-08-29 ruling); same-name survives
+    // only for the unswept installed tier.
+    const declared = m2?.states?.[dflt];
+    const declaredPath = declared && typeof declared === "object" && typeof declared.layout === "string" ? declared.layout : undefined;
+    rootPath = (declaredPath ? defPath(hit.folder, declaredPath) : undefined) ?? defPath(join(hit.folder, "layouts"), dflt);
+  }
+  if (!rootPath) return explicit;
+  const order: string[] = [...explicit];
+  const seen = new Set<string>();
+  const visited = new Set<string>([rootPath]);
+  const walk = (v: unknown): void => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v && typeof v === "object") {
+      const inc = (v as { $include?: unknown }).$include;
+      if (typeof inc === "string") {
+        const m = inc.match(/^states\/(.+)$/);
+        if (m && !seen.has(m[1])) (seen.add(m[1]), order.push(m[1]));
+        // Follow NON-state includes (e.g. a switcher root's layouts/full) so the
+        // authored state order survives the layouts/ restructure — the order must
+        // come from where the Switch actually references the states.
+        if (!m) {
+          const p = defPath(hit.folder, inc);
+          if (p && !visited.has(p)) {
+            visited.add(p);
+            walk(readDefCached(p));
+          }
+        }
+      }
+      Object.values(v).forEach(walk);
+    }
+  };
+  walk(readDefCached(rootPath));
+  return order;
+}
+
+/** Enumerate `<kind>/<name>/states/*` → the layer views (name + selector), ordered by
+ *  the root's reference sequence (`stateOrder`); the folder IS the set (§7). Empty if none. */
+export function listStates(kind: "app" | "component", ref: string): StateEntry[] {
+  const hit = findFolder(kind, ref);
+  if (!hit) return [];
+  const order = stateOrder(kind, ref);
+  const rank = (n: string) => { const i = order.indexOf(n); return i === -1 ? Infinity : i; };
+  const dir = join(hit.folder, "states");
+  const entries: StateEntry[] = !existsSync(dir)
+    ? []
+    : readdirSync(dir)
+        .filter(isDefFile)
+        .map((f) => {
+          const j = readDefCached<{ visibleWhen?: unknown; select?: { where?: unknown } }>(join(dir, f));
+          return { name: defName(f), when: j?.visibleWhen, where: j?.select?.where };
+        });
+  // TEMPLATE LAYOUTS (name-sync): each non-default layout of a multi-layout template
+  // is a first-class layer view, activated exactly like a reaction surface — put a
+  // component into the view of the layout's name. Served with that selector so the
+  // Studio's existing preview machinery seeds + activates it with zero special-casing.
+  if (kind === "app") {
+    const manifestPath = defPath(hit.folder, "manifest");
+    const manifest = manifestPath
+      ? readDefCached<{ layout?: string; states?: Record<string, { states?: Record<string, unknown> } | null> }>(manifestPath)
+      : undefined;
+    // ANATOMY UNIFIED (2026-08-22): the manifest TREE is the truth; a substate's
+    // drawing lives in layouts/ like every drawing (states/ read as legacy). Each
+    // declared substate is a layer view carrying its file's own selectors.
+    // A substate's drawing is OWNER-PREFIXED in layouts/ — `<owner>-<sub>` — the
+    // course-application `step-*` convention made law (owner ruling 2026-08-22);
+    // bare and legacy states/ spellings read as fallbacks until installed
+    // universes migrate.
+    const subOwners = new Map<string, string>();
+    // ONE FOLDER GRAMMAR (2026-08-29): the envelope is the tree's home; the
+    // manifest's block is the legacy read.
+    const envPath = defPath(hit.folder, parseRef(ref).name.toLowerCase());
+    const envStates = envPath ? readDefCached<{ states?: Record<string, { states?: Record<string, unknown> } | null> }>(envPath).states : undefined;
+    const mStates = (envStates && typeof envStates === "object" && !Array.isArray(envStates) ? envStates : undefined) ?? manifest?.states;
+    if (mStates && typeof mStates === "object" && !Array.isArray(mStates))
+      for (const [owner, st] of Object.entries(mStates))
+        if (st && typeof st === "object" && st.states && typeof st.states === "object")
+          for (const sub of Object.keys(st.states)) subOwners.set(sub, owner);
+    const subNames = new Set(subOwners.keys());
+    for (const [n, owner] of subOwners) {
+      if (entries.some((e) => e.name === n)) continue;
+      const p =
+        defPath(join(hit.folder, "layouts"), `${owner}-${n}`) ??
+        defPath(join(hit.folder, "layouts"), n) ??
+        defPath(join(hit.folder, "states"), n);
+      if (!p) continue;
+      const j = readDefCached<{ visibleWhen?: unknown; select?: { where?: unknown } }>(p);
+      entries.push({ name: n, when: j?.visibleWhen, where: j?.select?.where });
+    }
+    const ldir = join(hit.folder, "layouts");
+    if (existsSync(ldir)) {
+      const names = readdirSync(ldir).filter(isDefFile).map(defName);
+      if (names.length > 1) {
+        const dflt = defaultLayoutOf({ layout: manifest?.layout, states: mStates });
+        for (const n of names)
+          if (n !== dflt && !subNames.has(n) && !entries.some((e) => e.name === n)) entries.push({ name: n, where: { field: "defaultState", eq: n } });
+      }
+    }
+  }
+  // STATE MODEL v2 (UNOVERSE_STATE_MODEL §5 rule 2): a component with an authored
+  // `state.view` TREE serves its PUBLIC MENU as first-class states — each activated
+  // by the public axis (`view`), in tree order. The tree is the source of truth; this
+  // is its projection, exactly like the states/ folder before it.
+  if (kind === "component") {
+    const rootPath = defPath(hit.folder, parseRef(ref).name.toLowerCase());
+    const tree = rootPath
+      ? ((): { states?: Record<string, unknown> } | undefined => {
+          const raw = readDefCached<{ states?: Record<string, unknown>; state?: { view?: { states?: Record<string, unknown> } } }>(rootPath);
+          const top = raw?.states;
+          return top && typeof top === "object" && !Array.isArray(top) ? { states: top } : raw?.state?.view;
+        })()
+      : undefined;
+    if (tree && typeof tree === "object" && tree.states && typeof tree.states === "object") {
+      for (const n of Object.keys(tree.states))
+        if (!entries.some((e) => e.name === n)) entries.push({ name: n, where: { field: "state", eq: n } });
+      const treeOrder = Object.keys(tree.states);
+      const treeRank = (n: string) => { const i = treeOrder.indexOf(n); return i === -1 ? Infinity : i; };
+      return entries.sort((a, b) => treeRank(a.name) - treeRank(b.name) || rank(a.name) - rank(b.name));
+    }
+  }
+  return entries.sort((a, b) => rank(a.name) - rank(b.name) || a.name.localeCompare(b.name));
+}
+
+/**
+ * Templates for the workbench — each enriched with its app `binding` (and app name)
+ * when the folder carries a manifest. The workbench uses the binding to drive the live
+ * connection (workflow + trigger), so there's no manual entry: the app decides.
+ */
+export function listAppsForWorkbench(org?: string): (UnoverseDefinition & {
+  binding?: AppManifest["binding"];
+  appName?: string;
+  autoTrigger?: boolean;
+  previewComponents?: string[];
+  fluidHeight?: boolean;
+  states?: StateEntry[];
+  /** The full MCP-app manifest when the template folder carries one — so the workbench
+   *  can show the app's meta (description, category, version, binding, expose, schema). */
+  app?: AppManifest;
+})[] {
+  return listDefinitions("app", org)
+    .map((def) => {
+      const ref = `${def.org}/${def.name}`; // folder id = lowercased template name, org-scoped
+      const app = loadAppManifest(ref);
+      const states = listStates("app", ref);
+      return app
+        ? { ...def, states, binding: app.binding, appName: app.name, autoTrigger: app.autoTrigger, previewComponents: app.previewComponents, fluidHeight: app.fluidHeight, app }
+        : { ...def, states };
+    })
+    // Templates view shows only apps that ARE surfaces (manifest defaultState
+    // "template", or a plain layout with no manifest). Component apps (focus /
+    // component / any non-template name) are wizards etc. whose UI is their
+    // COMPONENT — designed in the Components view; their app shell is vestigial
+    // under the reaction contract (STATE_MODEL §5b). They stay fully served for
+    // discovery/launch (resources/list, /registry/spatial) — just not listed here.
+    .filter((def) => !("app" in def) || def.app?.type === "template");
+}