@unoverse-platform/studio 0.1.96 → 0.1.98

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

@@ -0,0 +1,197 @@
+/**
+ * PIPELINES, READ (docs/unoverse/data/pipelines/README.md layer 1, ruled 2026-09-09).
+ *
+ * A pipeline is the source side of ingestion: how content is collected and which objects it
+ * may yield. It never knows how an object is built. Its folder is the node's folder:
+ *
+ *   pipelines/<name>/pipeline.yaml   type: pipeline, the face (title, description, whenToUse,
+ *                                    category, version), and three things of its own:
+ *                                    `collect`, the nodes that fetch, in order, each naming a
+ *                                    marketplace node and filling its config; `make`, the reads,
+ *                                    in order, one block per read and one model call: what is
+ *                                    read (each over a list, partsOf, or each <object> by: folder),
+ *                                    its address and content, and the objects that read makes
+ *   pipelines/<name>/config.yaml     the Import form: a configSchema as a node's
+ *   pipelines/<name>/interface.yaml  the pipeline as a node on a canvas: signal in, rows out
+ *   pipelines/<name>/test.yaml       the collect steps faked, the rows asserted
+ *
+ * in two tiers, the marketplace's (`design/marketplace/pipelines/`) and an org's own
+ * (`design/<org>/pipelines/`). Nodes are the only way a pipeline touches the world: no HTTP,
+ * no credentials, no hosts in the file; the nodes it names carry them.
+ *
+ * This module only reads. Studio authors, the platform reads.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { readDefCached, defPath } from "../fsCache.js";
+import { composeIncludes } from "../load/expand/includes.js";
+import { pipelineDirs } from "./homes.js";
+import { pipelineFindings, firstRefusal, PIPELINE_READ_KEYS } from "../../lint/objects/rules.mjs";
+
+export interface CollectStep {
+  /** The step's name; a later step reads its outputs as `{{ collect.<name>.<output> }}`. */
+  name: string;
+  /** The marketplace node it runs. */
+  node: string;
+  /** The node's config, with `{{ config.* }}` and `{{ collect.* }}` references. */
+  config: Record<string, unknown>;
+}
+
+/**
+ * ONE OBJECT A READ MAKES (docs/unoverse/data/pipelines/README.md, "A pipeline, in one screen",
+ * 2026-09-14). The file says `make` as a list of reads, each naming the objects it makes; the
+ * reader hands the engine one entry per object, carrying its read's words: what is read
+ * (`each`: always one, `any`: maybe, the model says), the address and content only the source
+ * can say, and the object's count. Objects of one read share its list and address, so the
+ * engine reads each unit once for all of them.
+ */
+export interface MakeEntry {
+  object: string;
+  /** A list reference/expression over collect, or the name of an object made above. */
+  each?: string;
+  /** A list reference/expression over collect: maybe one per unit; the model says. */
+  any?: string;
+  /**
+   * A PART (ruled 2026-09-11, docs/unoverse/data/pipelines/README.md layer 1, parts): the object
+   * made above these are part of. One row per item of `each`, a list over `detail` (what that
+   * object's make function returned for the read), partOf that row, off the map, no model call.
+   */
+  partsOf?: string;
+  /**
+   * WHICH READS MAY MAKE IT (docs/unoverse/data/pipelines/a-document-decides.md, 2026-09-20), an
+   * expression over the read (`row`). The file says it as `where`, a list of allowed values per
+   * field. It is asked of what the DOCUMENT'S OWN READ said, so a document decides which objects
+   * it makes: a monthly risk report says the fund it is about, a DDQ says the firm. Absent: every
+   * read of this entry makes it.
+   */
+  when?: string;
+  /** How many of this object one source makes (owner, 2026-09-13): one, or many. The read asks by it; a part's entry says none. */
+  cardinality?: "one" | "many";
+  sourceUrl?: string;
+  sourceId?: string;
+  /** The item's content, each value a reference over `item`, `index`, `config`, `collect`. */
+  content: Record<string, unknown>;
+}
+
+
+export interface PipelineDefinition {
+  name: string;
+  /** The org that owns it; undefined for a marketplace pipeline. */
+  org?: string;
+  /** The face, the words a node's node.yaml uses: title, description, whenToUse, category, version, color, logoUrl. */
+  manifest: { title?: string; description?: string; whenToUse?: string; category?: string; version?: string; color?: string; logoUrl?: string };
+  collect: CollectStep[];
+  /** What this pipeline makes, in order. */
+  make: MakeEntry[];
+  /** The objects this pipeline makes, by name, in order: derived from `make`, for the screens. */
+  yields: string[];
+  /** The Import form, as a node's configSchema; empty when the folder has no config.yaml. */
+  configSchema: Record<string, unknown>;
+  /** The pipeline as a node: inputs, outputs, credentials. */
+  interface: Record<string, unknown>;
+  /** The folder on disk. */
+  dir: string;
+}
+
+// NO RESULT MAP, as for objects: the file reader's mtime check is the cache, so an edited
+// or published folder is seen on the next read in every process (2026-09-09: the engine
+// kept the old website pipeline until a restart).
+
+function folderOf(name: string, org?: string | null): { dir: string; org?: string } | null {
+  for (const { org: o, dir } of pipelineDirs(org ?? null)) {
+    const folder = join(dir, name);
+    if (existsSync(folder) && statSync(folder).isDirectory() && defPath(folder, "pipeline")) return { dir: folder, org: o };
+  }
+  return null;
+}
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return !!x && typeof x === "object" && !Array.isArray(x);
+}
+
+/**
+ * `where` IS A LIST OF ALLOWED VALUES PER FIELD, read as the check the engine runs over one read.
+ * A document decides which objects it makes: the check is asked of what its own read said, never
+ * of the folder it was found in (docs/unoverse/data/pipelines/a-document-decides.md).
+ */
+function whenOf(spec: Record<string, any>): string | undefined {
+  const where = isRecord(spec.where) ? spec.where : {};
+  if (!Object.keys(where).length) return undefined;
+  const each = Object.entries(where).map(([field, values]) => `${JSON.stringify(Array.isArray(values) ? values : [values])}.includes(row[${JSON.stringify(field)}])`);
+  return `return ${each.join(" && ")}`;
+}
+
+function readFolder(dir: string, name: string, org: string | undefined): PipelineDefinition {
+  // ITS SIBLINGS, INLINED (`$include`, as an object's folder composes its props): a pipeline
+  // that knows many kinds of document keeps one file per kind beside it rather than one long
+  // block, and a kind is added by adding a file. Resolved against the pipeline's own folder.
+  const file = (composeIncludes(readDefCached<Record<string, any>>(defPath(dir, "pipeline")!) ?? {}, dir) ?? {}) as Record<string, any>;
+  // THE RULES ARE THE LINTER'S (lint/objects/rules.mjs pipelineFindings): refused here with
+  // the same sentence the linter prints, one spelling of every rule (objects README 9a).
+  const refused = firstRefusal(pipelineFindings(name, file));
+  if (refused) throw new Error(`${refused} (${dir})`);
+  const collect: CollectStep[] = (file.collect as any[]).map((s: any) => ({ name: s.name, node: s.node, config: isRecord(s.config) ? s.config : {} }));
+  // THE FILE'S SHAPE, READ INTO THE ENTRIES THE ENGINE RUNS (docs/unoverse/data/pipelines/README.md,
+  // `make`, 2026-09-15; a-document-decides.md, 2026-09-20). Every entry reads a list: one item per
+  // unit, yielding the objects named under it. An object's `parts` are rows taken from its read;
+  // its `where` says which reads make it, asked of what the read said. A row's address and identity
+  // are the item's own unless the entry says them; what it carries is the item as listed unless the
+  // entry says `content`.
+  const make: MakeEntry[] = [];
+  for (const raw of file.make as Record<string, any>[]) {
+    const objects = Object.keys(raw).filter((k) => !PIPELINE_READ_KEYS.has(k));
+    const list = String(raw.each ?? raw.any ?? "").trim();
+    for (const object of objects) {
+      const spec = isRecord(raw[object]) ? raw[object] : {};
+      make.push({
+        object,
+        ...(spec.any === true ? { any: list } : { each: list }),
+        ...(spec.cardinality === "one" || spec.cardinality === "many" ? { cardinality: spec.cardinality as "one" | "many" } : {}),
+        ...(whenOf(spec) ? { when: whenOf(spec) } : {}),
+        sourceUrl: typeof raw.sourceUrl === "string" ? raw.sourceUrl : "{{ item.address }}",
+        sourceId: typeof raw.sourceId === "string" ? raw.sourceId : "{{ item.universalId }}",
+        content: isRecord(raw.content) ? raw.content : {},
+      });
+      for (const [part, from] of Object.entries(isRecord(spec.parts) ? spec.parts : {})) make.push({ object: part, partsOf: object, each: String(from).trim(), content: {} });
+    }
+  }
+  const configPath = defPath(dir, "config");
+  const config = configPath ? (readDefCached<Record<string, any>>(configPath) ?? {}) : {};
+  const interfacePath = defPath(dir, "interface");
+  const iface = interfacePath ? (readDefCached<Record<string, any>>(interfacePath) ?? {}) : {};
+  return {
+    name,
+    ...(org ? { org } : {}),
+    manifest: { title: file.title, description: file.description, whenToUse: file.whenToUse, category: file.category, version: file.version, color: file.color, logoUrl: file.logoUrl },
+    collect,
+    make,
+    yields: make.map((m) => m.object),
+    configSchema: isRecord(config.configSchema) ? { ...config.configSchema, ...(config["ui:order"] ? { "ui:order": config["ui:order"] } : {}) } : {},
+    interface: iface,
+    dir,
+  };
+}
+
+/** One pipeline by name, the org's tier first then the marketplace. Null when no tier holds it. */
+export function readPipeline(name: string, org?: string | null): PipelineDefinition | null {
+  const hit = folderOf(name, org);
+  return hit ? readFolder(hit.dir, name, hit.org) : null;
+}
+
+/** Every pipeline an org can see: the marketplace's and its own. Bare (no org) lists the marketplace's plus every org's. */
+export function listPipelines(org?: string | null): PipelineDefinition[] {
+  const out: PipelineDefinition[] = [];
+  const seen = new Set<string>();
+  for (const { org: o, dir } of pipelineDirs(org ?? null)) {
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith(".")) continue;
+      const key = `${o ?? ""}/${e.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const def = readPipeline(e.name, o ?? null);
+      if (def) out.push(def);
+    }
+  }
+  return out;
+}

package/vendor/base/src/definitions/theme.ts

@@ -36,7 +36,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // VALUES are each org's own — that's how two clients get different fonts/colors/spacing
 // from the same components, without re-copying the foundation.
 import { listOrgs, projectDir } from "./definitions.js";
-import { NODES_HOME, PLUGINS_DIR, DESIGN_HOME, INSTALLED_HOME, databaseOnly, designDir } from "../paths.js";
+import { PLUGINS_DIR, DESIGN_HOME, INSTALLED_HOME, databaseOnly, designDir } from "../paths.js";
 
 const DESIGN = DESIGN_HOME;
 export const DEFAULT_ORG = "default";
@@ -58,7 +58,6 @@ function orgStyles(org: string): string | null {
  * the package (no `rx/marketplace` on disk) once purged from the image (Phase 4).
  */
 const DS_STYLES_CANDIDATES = [
-  join(NODES_HOME, "marketplace", "definitions", "styles"),
   join(PLUGINS_DIR, "node_modules", "@unoverse-platform", "marketplace", "definitions", "styles"),
 ];
 /**

package/vendor/base/src/items/collect.ts

@@ -48,12 +48,8 @@ const isDef = (f: string) => f.endsWith(".yaml") || f.endsWith(".json");
 function designSystemDir(designRoot: string): string {
   const onDisk = join(designRoot, "marketplace");
   if (existsSync(onDisk)) return onDisk;
-  const nodesHome = join(designRoot, "..", "nodes");
-  for (const c of [
-    join(nodesHome, "marketplace", "definitions"),
-    join(designRoot, "..", "plugins", "node_modules", "@unoverse-platform", "marketplace", "definitions"),
-  ])
-    if (existsSync(c)) return c;
+  const bundled = join(designRoot, "..", "plugins", "node_modules", "@unoverse-platform", "marketplace", "definitions");
+  if (existsSync(bundled)) return bundled;
   return onDisk; // nothing found: the version will hash to an empty set, which is honest
 }
 
@@ -108,7 +104,12 @@ export function collectProject(designRoot: string, project: string): CollectedIt
   // A prompt block is NEVER qualified this way — see the blocks/ walk below for why.
   // Apps keep their bare ids: those are org-qualified by convention
   // (`<org>-chat`). docs/unoverse/UNOVERSE_COMPONENT_ORGS.md.
-  const QUALIFIED_KINDS = new Set(["component", "skill", "template"]);
+  // `identity` (2026-09-05): the org's four documents, `<org>/brand` like a component.
+  // `agent` (2026-09-06): a workflow listed for the map, design/<org>/agents/<name>.yaml, `<org>/<name>`.
+  // `object` and `pipeline` (2026-09-09): an org's own kinds beside the marketplace masters
+  // (docs/unoverse/data/objects/README.md 4e, docs/unoverse/data/pipelines/README.md layer 1), `<org>/<name>` like a
+  // component, since two orgs may each write a `deal`.
+  const QUALIFIED_KINDS = new Set(["component", "skill", "template", "identity", "agent", "object", "pipeline"]);
   const add = (kind: string, name: string, definition: CollectedItem["definition"]) =>
     items.push({
       kind,
@@ -134,7 +135,16 @@ export function collectProject(designRoot: string, project: string): CollectedIt
   // 029): apps publish as kind `app` and the Template Model kind owns the bare
   // word. Forgetting a design dir here ships deploys that silently drop every
   // artifact of that kind.
-  for (const [dir, kind] of [["components", "component"], ["apps", "app"], ["templates", "template"], ["atoms", "atom"]] as const) {
+  // IDENTITY (owner ruling 2026-09-05): design/<org>/identity/<doc>/ publishes as kind
+  // `identity`, the same walk as a component folder, so it reaches the registry, the
+  // spatial catalogue and the map through the one publish path everything else takes.
+  // AGENT (owner ruling 2026-09-06): design/<org>/agents/<name>.yaml, a single file like an atom,
+  // publishes as kind `agent` so it reaches the registry, the catalogue and the map.
+  // OBJECT and PIPELINE (owner ruling 2026-09-09): design/<org>/objects/<name>/ and
+  // design/<org>/pipelines/<name>/, folders like a component, publish as their own kinds so
+  // an org's custom object and its own source reach the engine that positions its rows and
+  // the inbox that collects for it. The marketplace's own go through designSystemItems().
+  for (const [dir, kind] of [["components", "component"], ["apps", "app"], ["templates", "template"], ["atoms", "atom"], ["identity", "identity"], ["agents", "agent"], ["objects", "object"], ["pipelines", "pipeline"]] as const) {
     const home = join(root, dir);
     if (!existsSync(home)) continue;
     for (const e of readdirSync(home, { withFileTypes: true })) {
@@ -198,22 +208,20 @@ export function collectProject(designRoot: string, project: string): CollectedIt
     walk(blocksHome);
   }
 
-  // nodes/ — THE WORKSPACE'S NODE PACKAGES, one row per node, shaped exactly as the
-  // marketplace stores a node (core/items/catalogue.ts) so the row source composes them
-  // on the same path as disk: the raw files, plus the package envelope their $refs and
-  // credential shapes resolve against. The name is the node's `type`, bare: a saved
-  // workflow stores that identity and nothing else.
+  // nodes/ — THE PROJECT'S NODE PACKAGES, design/<org>/nodes/<package>/, one row per
+  // node, shaped exactly as the marketplace stores a node (core/items/catalogue.ts) so
+  // the row source composes them on the same path as disk: the raw files, plus the
+  // package envelope their $refs and credential shapes resolve against. The name is the
+  // node's `type`, bare: a saved workflow stores that identity and nothing else.
   //
-  // Until 2026-09-05 deploy never looked here, so `deploy studio` shipped a developer's
-  // components and skills and silently left every node behind.
-  //
-  // NOT FROM THE PLATFORM TREE. The monorepo's nodes ship inside the core image and are
-  // read from disk there; publishing them as rows under whichever org happened to be
-  // deployed would double every platform node. A design system on disk is the mark of
-  // the platform tree (the same test designSystemDir makes), and a developer's workspace
-  // never has one.
-  const nodesHome = join(designRoot, "..", "nodes");
-  if (existsSync(nodesHome) && !existsSync(join(designRoot, "marketplace"))) {
+  // Until 2026-09-05 deploy never looked at nodes at all, so `deploy studio` shipped a
+  // developer's components and skills and silently left every node behind. Until
+  // 2026-09-08 it looked at a `nodes/` folder beside design/ while every org already
+  // kept its nodes INSIDE its project, so the same nodes were left behind again. Org
+  // nodes are org-scoped like skills; the marketplace tier's own nodes sit under
+  // design/marketplace/, which is never collected.
+  const nodesHome = join(root, "nodes");
+  if (existsSync(nodesHome)) {
     for (const pkg of collectNodePackages(nodesHome)) {
       for (const raw of pkg.nodes) {
         const type = nodeType(raw.files["node.yaml"]);
@@ -230,9 +238,9 @@ export function collectProject(designRoot: string, project: string): CollectedIt
   return items;
 }
 
-/** The workspace's node packages, read the way the platform reads its own. */
+/** The project's node packages, read the way the platform reads its own. */
 function collectNodePackages(nodesHome: string) {
-  return readDiskPackages(nodesHome).filter((pkg) => pkg.name !== "marketplace");
+  return readDiskPackages(nodesHome);
 }
 
 /** `type:` off a node.yaml: the one scalar the row is named by. Unparseable means none. */

package/vendor/base/src/items/publish.ts

@@ -10,7 +10,7 @@
  * new, changed, unchanged, or refused because the name belongs to someone else. Publishing
  * blind is how a project half-lands and nobody can tell by looking.
  *
- * See docs/architecture/DECLARATIVE_NODES.md §9.
+ * See docs/architecture/authoring/DECLARATIVE_NODES.md §9.
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -49,17 +49,41 @@ export async function lintForPublish(designRoot: string, project: string): Promi
   const { lintDefinitions } = await import("../lint/design/index.mjs");
   const result = lintDefinitions(designRoot);
   /**
-   * NODES TOO. A workspace keeps its node packages beside design/ (the same `nodes/` the
-   * Studio Nodes screen reads), and until 2026-09-05 this gate never looked at them: a
-   * node with an events row out of order or a host missing from allowedHosts deployed as
-   * cleanly as a correct one. The node linter is the same library the platform's own CI
-   * runs. A workspace with no nodes/ folder has nothing to lint and is not an error.
+   * NODES TOO. A project keeps its node packages at design/<project>/nodes/ (the same
+   * folder the Studio Nodes screen reads), and until 2026-09-05 this gate never looked
+   * at nodes at all: a node with an events row out of order or a host missing from
+   * allowedHosts deployed as cleanly as a correct one. The node linter is the same
+   * library the platform's own CI runs. A project with no nodes/ folder has nothing to
+   * lint and is not an error.
    */
-  const nodesHome = join(designRoot, "..", "nodes");
+  const nodesHome = join(designRoot, project, "nodes");
   if (existsSync(nodesHome)) {
     const { lintNodes } = await import("../lint/nodes/index.mjs");
     result.problems.push(...lintNodes(nodesHome).problems);
   }
+  /**
+   * OBJECTS AND PIPELINES TOO (objects README 9a, 2026-09-10). They live under
+   * design/<tier>/objects and /pipelines, folders neither linter above enumerates, and a
+   * home not enumerated is a home where every rule is off, silently. The objects linter
+   * walks every tier of the design root, like the design linter; the project filter below
+   * keeps this project's findings.
+   */
+  {
+    const { lintObjects } = await import("../lint/objects/index.mjs");
+    result.problems.push(...lintObjects(designRoot).problems);
+  }
+  /**
+   * SKILLS AND PROMPT BLOCKS TOO (2026-09-18). They live under design/<tier>/skills and
+   * /blocks, and nothing read them before publish: a SKILL.md whose frontmatter did not
+   * parse (a bare colon in the description) was published, and the run-time loaders then
+   * dropped it with one console line, so it was absent from every list and nobody was
+   * told. The prompts linter walks every tier, like the objects linter; the project filter
+   * below keeps this project's findings.
+   */
+  {
+    const { lintPrompts } = await import("../lint/prompts/index.mjs");
+    result.problems.push(...lintPrompts(designRoot).problems);
+  }
   /**
    * SCOPED TO THE PROJECT BEING DEPLOYED, on paths that may be relative. The old
    * check looked for "/design/" with a leading slash, which a relative path never

package/vendor/base/src/lint/context.mjs

@@ -20,6 +20,21 @@ export const derivedKinds = new Map();
 /** Credential name -> where it was declared, for cross-package collision rules. */
 export const allCredentials = new Map();
 
+/**
+ * ATTACHMENTS, and the config fields every other node declares.
+ *
+ * An attachment clips onto a node whose configSchema has every field it sets, so "can this
+ * attachment ever clip onto anything?" cannot be answered while reading the attachment: its
+ * host may be in a package that has not been read yet, or in no package at all. Both halves
+ * are collected here and checked once at the end of the run (node.mjs lintAttachments).
+ *
+ * The alternative was making the author declare the host, which is the `accepts:` list the
+ * whole design exists to avoid.
+ */
+export const attachments = new Map();
+/** Node label -> the set of config field names it declares. */
+export const configFields = new Map();
+
 /** Where this run is reading. Set by lintNodes(), read by rel() and the loaders. */
 export const state = { nodesHome: "", schemaDir: "", schemas: {} };
 
@@ -29,6 +44,8 @@ export function reset(nodesHome, schemaDir) {
   refCounts.clear();
   derivedKinds.clear();
   allCredentials.clear();
+  attachments.clear();
+  configFields.clear();
   state.nodesHome = nodesHome;
   state.schemaDir = schemaDir;
   state.schemas = {};

package/vendor/base/src/lint/design/file.mjs

@@ -85,8 +85,44 @@ function checkDiscoveryMeta(report, file, json, kind, docs) {
     report("warn", file, `discovery manifest has no "category". Name the domain of the job, never the implementation (${docs})`);
 }
 
+/**
+ * AN AGENT FILE (docs.unoverse.ai/design/tasks, 2026-09-06): a workflow with no interface,
+ * listed for the map. The discovery meta answers to the same rules as every manifest,
+ * because the Agent is ranked against what a PERSON said. The door is three fields, always:
+ * a canvas, its Input Trigger, and the node whose output is the result; a door missing at
+ * run time fails the customer, not the author. The face is optional and defaults to the
+ * shared agent-card; when named, it must be a component that resolves.
+ */
+function checkAgentFile(report, file, json, componentNames) {
+  const docs = "docs.unoverse.ai/design/tasks";
+  if (json.type !== "agent") report("error", file, `agent file must declare "type: agent" (${docs})`);
+  const key = basename(file).replace(/\.(json|ya?ml)$/, "");
+  if (typeof json.name !== "string" || !json.name.trim()) report("error", file, `agent file missing "name" (${docs})`);
+  else {
+    if (json.name !== key) report("error", file, `agent "name: ${json.name}" must equal the file name "${key}" (${docs})`);
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(json.name)) report("error", file, `agent name "${json.name}" must be kebab-case: it is the tool's name on the wire (${docs})`);
+  }
+  checkDiscoveryMeta(report, file, json, "agent", docs);
+  const door = ["workflow", "trigger", "output"].filter((k) => typeof json[k] === "string" && json[k].trim());
+  if (door.length < 3)
+    report("error", file, `agent door is three fields, always: workflow, trigger and output. Present: ${door.join(", ") || "none"} (${docs})`);
+  const app = typeof json.app === "string" ? json.app.trim() : "";
+  if (app) {
+    if (!/^unoverse:\/\/components\//.test(app))
+      report("error", file, `agent "app: ${app}" must be a component URI: the face while it runs (${docs})`);
+    else if (componentNames && componentNames.size && !componentNames.has(app.split("/").pop().toLowerCase()))
+      report("error", file, `agent face "${app}" does not resolve: no such component in this project or the design system (${docs})`);
+  }
+  if (json.instructions !== undefined && typeof json.instructions !== "string")
+    report("error", file, `agent "instructions" must be a string: what to do (${docs})`);
+  if (json.skills !== undefined && !(Array.isArray(json.skills) && json.skills.every((x) => typeof x === "string" && x.trim())))
+    report("error", file, `agent "skills" must be a list of skill names (${docs})`);
+  if (json.message !== undefined && typeof json.message !== "string")
+    report("error", file, `agent "message" must be a string: what the face says while it runs (${docs})`);
+}
+
 export function makeLintFile(ctx) {
-  const { report, walkNode, isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePart, defRoot, componentNamesForFile, DS, orgDirs, RX, readText } = ctx;
+  const { report, walkNode, isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePart, isAgentPath, defRoot, componentNamesForFile, placeNames, DS, orgDirs, RX, readText } = ctx;
 
 function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
   if (!Array.isArray(order)) return;
@@ -115,6 +151,39 @@ function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
 // one folder grammar — while a manifest-held tree remains the legacy read, so
 // both call sites validate identically).
 function checkAppTree(json, root, file) {
+  // PREVIEW NAMES RESOLVE (docs.unoverse.ai/design/apps, ruled 2026-09-10). Studio seeds a
+  // picked state from its `preview` list by looking each name up among the components and
+  // templates the org can see, by bare name, and a name it cannot find seeds NOTHING and says
+  // nothing: the state's tab looks dead and nobody is told why (observed live: an app said
+  // `alpha/deal` where the component is `deal`). So the name is checked here, where
+  // the file is written, against the same set: the marketplace's and this org's own.
+  {
+    const comps = componentNamesForFile ? componentNamesForFile(file) : null;
+    const walkStates = (states, path) => {
+      if (!states || typeof states !== "object" || Array.isArray(states)) return;
+      for (const [name, entry] of Object.entries(states)) {
+        if (!entry || typeof entry !== "object") continue;
+        const where = path ? `${path}.${name}` : name;
+        if (Array.isArray(entry.preview)) {
+          for (const item of entry.preview) {
+            const raw = typeof item === "string" ? item : item && typeof item === "object" && !Array.isArray(item) ? Object.keys(item)[0] : undefined;
+            if (typeof raw !== "string" || !raw) continue;
+            // THE HASH NAMES THE STATE IT OPENS IN (STATE_MODEL rule 3, ruled 2026-09-09; owner
+            // 2026-09-11: a preview is written `deal#grid`). The name is what is checked; the
+            // state after the hash is the component's own to declare.
+            const ref = raw.split("#")[0];
+            if (ref.includes("/"))
+              report("error", file, `state "${where}" preview names "${ref}" with an org prefix. Studio seeds a preview by the component's bare name ("${ref.split("/").pop()}"); a prefixed name resolves to nothing and the state's tab shows nothing (docs.unoverse.ai/design/apps)`);
+            else if (comps && !comps.has(ref.toLowerCase()))
+              report("error", file, `state "${where}" preview names "${ref}", which is no component or template this org can see (design/marketplace/, this org's components/ and templates/). Studio would seed nothing and the state's tab would show nothing (docs.unoverse.ai/design/apps)`);
+          }
+        } else if (entry.preview !== undefined && (typeof entry.preview !== "object" || entry.preview === null))
+          report("error", file, `state "${where}" preview must be a list of component names, or an object of app-state mock data (docs.unoverse.ai/design/apps)`);
+        walkStates(entry.states, where);
+      }
+    };
+    walkStates(json?.states, "");
+  }
       if (json.states !== undefined) {
         if (!json.states || typeof json.states !== "object" || Array.isArray(json.states)) {
           report("error", file, `manifest "states" must be an object — the template tree: { <base>: { states: {…} }, <reaction>: {}, … } (STATE_MODEL §5)`);
@@ -190,6 +259,94 @@ function checkAppTree(json, root, file) {
       } else checkStateOrder(json.stateOrder, root, file, /* includeLayouts */ true);
 }
 
+// ── an app's places (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §2.2) ──
+// An app that declares places is drawn from the screen document, which replaces a task with the
+// next one and steps aside what a turn did not touch. An app that declares none runs the old
+// render pipeline, where nothing replaces anything: a voice call stacked three tasks, and a
+// comparison it built never reached the screen (2026-09-12). So the lint says which an app is,
+// and holds a places app to the places its org's interfaces name.
+function checkAppPlaces(json, root, file) {
+  const files = [];
+  const collect = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const f = join(dir, e.name);
+      if (e.isDirectory()) collect(f);
+      else if (isDefFile(e.name)) files.push(f);
+    }
+  };
+  collect(join(root, "layouts"));
+  collect(join(root, "components"));
+  const places = new Set();
+  const claims = [];
+  const walk = (n, f) => {
+    if (Array.isArray(n)) return n.forEach((c) => walk(c, f));
+    if (!n || typeof n !== "object") return;
+    if (n.type === "Place" && typeof n.name === "string") places.add(n.name);
+    if (n.type === "ComponentSlot" && n.select?.where?.field === "state") claims.push(relative(root, f));
+    for (const v of Object.values(n)) walk(v, f);
+  };
+  for (const f of files) {
+    try {
+      walk(parseDef(readFileSync(f, "utf8"), f), f);
+    } catch {
+      /* an unreadable file is reported by its own lint */
+    }
+  }
+  // THE MANIFEST'S `layout:` NAMES THE BASE STATE. Pointing it at a state the app no longer has
+  // leaves the app with no drawing at all: it loads, and nothing is placed (2026-09-12).
+  const manifest = defPath(root, "manifest");
+  if (manifest) {
+    try {
+      const m = parseDef(readFileSync(manifest, "utf8"), manifest);
+      const names = json.states && typeof json.states === "object" && !Array.isArray(json.states) ? Object.keys(json.states) : [];
+      if (m && typeof m.layout === "string" && names.length && !names.includes(m.layout))
+        report("error", file, `manifest.yaml says layout: ${m.layout}, which is no state of this app (${names.join(", ")}). The app would load with no drawing. Delete the line: the first state is the base (docs.unoverse.ai/design/apps)`);
+    } catch {
+      /* reported by its own lint */
+    }
+  }
+  if (!places.size) {
+    report("warn", file, `app declares no Place, so it runs the old render pipeline: nothing replaces an open task and nothing steps aside when the conversation moves on. Declare its places in the layout, as sab-chat does (UNOVERSE_SCREEN.md §2.2)`);
+    return;
+  }
+  const states = json.states && typeof json.states === "object" && !Array.isArray(json.states) ? Object.keys(json.states) : [];
+  if (states.length > 1)
+    report("error", file, `app declares places and ${states.length} states (${states.join(", ")}). An app with places has one arrangement: its places open and close as the screen fills them, so a state per surface is the old ladder and draws nothing (UNOVERSE_SCREEN.md §2.2)`);
+  for (const f of new Set(claims))
+    report("error", file, `${f} claims interfaces by state (a ComponentSlot with select.where on state), the old reaction surface. In an app with places the screen decides what is shown; draw it in a Place (UNOVERSE_SCREEN.md §2.2)`);
+  // THE PLACES THIS ORG'S INTERFACES NAME. An interface whose state names a place this app lacks
+  // lands in the conversation, which a voice app does not draw at all.
+  const org = basename(dirname(root)) === "apps" ? dirname(dirname(root)) : null;
+  if (!org) return;
+  const named = new Map();
+  const statesOf = (st, where) => {
+    if (!st || typeof st !== "object" || Array.isArray(st)) return;
+    for (const [n, e] of Object.entries(st)) {
+      if (!e || typeof e !== "object") continue;
+      if (typeof e.place === "string" && e.place !== "chat" && !named.has(e.place)) named.set(e.place, `${where} (state "${n}")`);
+      statesOf(e.states, where);
+    }
+  };
+  for (const kind of ["components", "templates"]) {
+    const dir = join(org, kind);
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const f = defPath(join(dir, e.name), e.name);
+      if (!f) continue;
+      try {
+        statesOf(parseDef(readFileSync(f, "utf8"), f)?.states, `${kind}/${e.name}`);
+      } catch {
+        /* reported by its own lint */
+      }
+    }
+  }
+  for (const [place, by] of named)
+    if (!places.has(place))
+      report("error", file, `${by} is shown in place "${place}", which this app does not declare, so here it would land in the conversation. Declare a Place named "${place}" (this app has: ${[...places].sort().join(", ")}) (UNOVERSE_SCREEN.md §2.3)`);
+}
+
 // ── lint one file ──
 function lintFile(file) {
   // `readText` is disk unless the caller supplied an overlay for this path (index.mjs).
@@ -200,7 +357,8 @@ function lintFile(file) {
   // Exempt: `appWidth` — the HOST-facing outer width (state-owned sizing, docs.unoverse.ai/design/apps).
   // It is raw CSS the embed host applies to the app panel ("min(50vw, 760px)", "360px"),
   // never a style the SDK resolves — token law governs the inside, not the envelope.
-  if (!isFixture(file) && !isHook(file) && !isManifest(file))
+  // An Agent file carries URIs and ids, never a style, so the token law has nothing to judge.
+  if (!isFixture(file) && !isHook(file) && !isManifest(file) && !(isAgentPath && isAgentPath(file)))
     src.split("\n").forEach((line, i) => {
       /**
        * THE RULE JUDGES CODE, NEVER COMMENTARY. A comment explaining a contrast
@@ -236,6 +394,44 @@ function lintFile(file) {
   if (isFixture(file)) return; // legacy fixture, unused: don't choke
   if (isHook(file)) return;    // a lifecycle hook: calls + a projection, not a UI tree
   if (isPropsExtract(file)) return; // the envelope's props map, composed there — not a UI tree
+  if (isAgentPath && isAgentPath(file)) { // an Agent: a workflow listed for the map, not a UI tree
+    checkAgentFile(report, file, json, componentNamesForFile ? componentNamesForFile(file) : null);
+    return;
+  }
+
+  // ONE WORD (UNOVERSE_STATE_MODEL §5, "One word: `state`"): a step is a state, so a state tree
+  // carries no second name (`on:`), and a step's name is never a face's name.
+  if (!isAppPath(file) && json && typeof json === "object" && !Array.isArray(json) && json.states && typeof json.states === "object" && !Array.isArray(json.states)) {
+    const faces = new Set(Object.keys(json.states));
+    for (const [face, entry] of Object.entries(json.states)) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      if (entry.on !== undefined)
+        report("error", file, `state "${face}" names its steps with "on: ${entry.on}". A step is a state: drop "on:" and write state everywhere, Switch on: state, field: state, key: state (UNOVERSE_STATE_MODEL §5). Arrangement picked by data is a Switch in the layout, not a state`);
+      if (entry.states && typeof entry.states === "object" && !Array.isArray(entry.states))
+        for (const step of Object.keys(entry.states))
+          if (faces.has(step)) report("error", file, `state "${face}" has a step named "${step}", which is also a face. With one word, state, a name means one thing: rename the step (UNOVERSE_STATE_MODEL §5)`);
+    }
+  }
+
+  // A STATE'S PLACE (UNOVERSE_SCREEN.md §2.3) is `chat` or a Place some app declares. A name no
+  // app has sends the interface to the conversation without a word, so it is refused here.
+  if (placeNames && !isAppPath(file) && json && typeof json === "object" && !Array.isArray(json) && json.states && typeof json.states === "object") {
+    const known = placeNames();
+    const walkPlaces = (states, path) => {
+      for (const [name, entry] of Object.entries(states)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+        const where = path ? `${path}.${name}` : name;
+        if (entry.place !== undefined && known.size > 0) {
+          if (typeof entry.place !== "string")
+            report("error", file, `state "${where}" place must be a place name: chat, or a Place an app declares (UNOVERSE_SCREEN.md §2.3)`);
+          else if (entry.place !== "chat" && !known.has(entry.place))
+            report("error", file, `state "${where}" names place "${entry.place}", which no app declares. An interface in this state would land in the conversation instead. Use chat or one of: ${[...known].sort().join(", ")} (UNOVERSE_SCREEN.md §2.3)`);
+        }
+        if (entry.states && typeof entry.states === "object" && !Array.isArray(entry.states)) walkPlaces(entry.states, where);
+      }
+    };
+    walkPlaces(json.states, "");
+  }
 
   if (isManifest(file)) {
     const root = dirname(file);
@@ -424,6 +620,7 @@ function lintFile(file) {
     // APP envelope: the states tree lives HERE (one folder grammar) — validate it
     // exactly as the legacy manifest-held tree was.
     if (declared === "app") checkAppTree(json, root, file);
+    if (declared === "app") checkAppPlaces(json, root, file);
     if (json.root) walkNode(json.root, file, root);
 
     // ── the contained-microapp discipline (mirrors microapp-structure.test.ts) ──