@unoverse-platform/studio 0.1.96 → 0.1.98

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

@@ -67,7 +67,7 @@ export function lintDefinitions(designRoot, options = {}) {
         try {
           return (
             statSync(d).isDirectory() &&
-            ["components", "atoms", "styles", "apps"].some((s) => existsSync(join(d, s)))
+            ["components", "atoms", "styles", "apps", "agents"].some((s) => existsSync(join(d, s)))
           );
         } catch {
           return false;
@@ -96,9 +96,7 @@ export function lintDefinitions(designRoot, options = {}) {
   const DS = (() => {
     const onDisk = join(DESIGN_ROOT, "marketplace");
     if (existsSync(onDisk)) return onDisk;
-    const nodesHome = resolve(DESIGN_ROOT, "..", "nodes");
     for (const c of [
-      join(nodesHome, "marketplace", "definitions"),
       join(resolve(DESIGN_ROOT, "..", "plugins"), "node_modules", "@unoverse-platform", "marketplace", "definitions"),
     ])
       if (existsSync(c)) return c;
@@ -190,6 +188,9 @@ const isAppPath = (f) => homeSegments(f).includes("apps");
 // carry no manifest and declare no state tree, the face being the filename (§9b rule 7).
 const isTemplatePath = (f) => homeSegments(f).includes("templates");
 const isTemplatePart = (f) => isTemplatePath(f) && homeSegments(f).includes("components");
+// THE AGENT KIND (docs.unoverse.ai/design/tasks, 2026-09-06): one file under <org>/agents/,
+// a workflow listed for the map. Not a UI tree, so the tree rules do not apply; its own check does.
+const isAgentPath = (f) => homeSegments(f).includes("agents");
 // The DEFINITION ROOT folder for a file: a bare partial lives one level under it
 // (layouts/ states/ components/ blocks/); every `$include` resolves against it.
 const defRoot = (file) => {
@@ -597,7 +598,7 @@ const keyHomes = [
   [join(DS, "components"), true],
 ];
 for (const orgDir of orgDirs) {
-  keyHomes.push([join(orgDir, "components"), true], [join(orgDir, "apps"), true]);
+  keyHomes.push([join(orgDir, "components"), true], [join(orgDir, "apps"), true], [join(orgDir, "agents"), false]);
 }
 for (const [dir, isDir] of keyHomes) {
   if (!existsSync(dir)) continue;
@@ -638,7 +639,9 @@ for (const [dir, isDir] of keyHomes) {
 // carries are ordinary components, so they were never exempt from anything.
 const homes = [{ dir: join(DS, "components") }, { dir: join(DS, "atoms") }, { dir: join(DS, "templates") }];
 for (const orgDir of orgDirs) {
-  for (const sub of ["apps", "components", "templates"]) {
+  // `agents` (2026-09-06): a kind is linted; a home not enumerated is a home where every
+  // rule is off, silently.
+  for (const sub of ["apps", "components", "templates", "agents"]) {
     const d = join(orgDir, sub);
     if (existsSync(d) && statSync(d).isDirectory()) homes.push({ dir: d });
   }
@@ -701,64 +704,27 @@ for (const orgDir of orgDirs) {
         );
   }
 
-/**
- * ── the LATCH, on a state (docs/MCP_COMPLETE_GUIDE.md §The Component Latch) ──
- *
- * Declaring it makes whatever wears that face ADDRESSABLE: the pill goes up and the guest's
- * next sentences travel to that instance instead of opening a new answer. Every finding here
- * is something that produces a pill which looks fine and behaves wrongly, which is why they
- * are errors rather than warnings.
- *
- * Read from the ENVELOPE first and the manifest second, the same order the loader reads the
- * states tree in — a rule that judged only one home would pass whatever was authored in the
- * other.
- */
-const LATCH_KEYS = new Set(["title", "icon"]);
+// ── `latch`, RETIRED (2026-09-07) ──
+// The conversation is never "addressed at" a component: what is on screen is the server's
+// fact and the model reads it. A leftover block is an intent nothing honours, so it errors.
 for (const orgDir of orgDirs) {
   const adir = join(orgDir, "apps");
   if (!(existsSync(adir) && statSync(adir).isDirectory())) continue;
   for (const e of readdirSync(adir)) {
     const folder = join(adir, e);
-    let src, states;
     try {
       if (!statSync(folder).isDirectory()) continue;
-      // The envelope (`<name>.yaml`) is the app tree's home; the manifest is the legacy one.
-      const envelope = defPath(folder, e);
-      const manifest = defPath(folder, "manifest");
-      for (const p of [envelope, manifest]) {
+      for (const p of [defPath(folder, e), defPath(folder, "manifest")]) {
         if (!p || !existsSync(p)) continue;
-        const s = readDef(p).states;
-        if (s && typeof s === "object" && !Array.isArray(s)) {
-          src = p;
-          states = s;
-          break;
-        }
+        const states = readDef(p).states;
+        if (!states || typeof states !== "object" || Array.isArray(states)) continue;
+        for (const [sname, sentry] of Object.entries(states))
+          if (sentry && typeof sentry === "object" && !Array.isArray(sentry) && sentry.latch !== undefined)
+            report("error", p, `state "${sname}": "latch" is retired (2026-09-07). Delete the block — the model reads what is on screen; nothing addresses a component`);
       }
     } catch {
       continue; // a malformed envelope is reported elsewhere
     }
-    if (!states) continue;
-    for (const [sname, sentry] of Object.entries(states)) {
-      const latch = sentry && typeof sentry === "object" && !Array.isArray(sentry) ? sentry.latch : undefined;
-      if (latch === undefined) continue;
-      if (typeof latch !== "object" || latch === null || Array.isArray(latch)) {
-        report("error", src, `state "${sname}": "latch" must be a block ({ title, icon }), not ${Array.isArray(latch) ? "a list" : typeof latch}. Presence is what makes a state addressable, so a malformed one is an intent nothing can honour (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`);
-        continue;
-      }
-      // The pill is the ONLY sign the guest has that their words are landing on this page
-      // rather than the conversation. Unlabelled, it says nothing — and the compiler drops
-      // a titleless block, so the state would silently stop being addressable.
-      if (typeof latch.title !== "string" || !latch.title.trim())
-        report("error", src, `state "${sname}": "latch" needs a "title" — it is what the pill reads, and the pill is the only thing telling the guest what they are addressing. Name the thing, not the verb ("Your Perfect Day", not "Edit the day")`);
-      const extra = Object.keys(latch).filter((k) => !LATCH_KEYS.has(k));
-      if (extra.length)
-        report("error", src, `state "${sname}": "latch" has no key(s) ${extra.join(", ")}. The block is exactly ${[...LATCH_KEYS].join(", ")} — an invented key is silently ignored, so whatever it was meant to do never happens. The pill's colours belong to the design system's composer-bar, never to a state`);
-      // A STATE NOTHING CAN ENTER CANNOT BE ADDRESSED. The base state is the app at rest —
-      // the conversation itself — and `stateOrder` excludes it, so `resolveLatch` can never
-      // rank a base-state instance and the pill would never appear.
-      if (sname === Object.keys(states)[0])
-        report("error", src, `state "${sname}": it is the BASE state — the app at rest, which the priority ladder excludes by construction (stateOrder is every state BUT the base). A latch here can never resolve, so no pill would ever draw. Declare it on a state something ARRIVES into`);
-    }
   }
 }
 
@@ -778,8 +744,14 @@ const PLATFORM_HANDLERS = new Set(["getDetail"]); // named handlers needing no f
 // silently disable every rule after it.
 const credentialDefs = new Set();
 {
-  const nodesHome = resolve(DESIGN_ROOT, "..", "nodes");
+  // Every tier's node packages: the marketplace's and each org's, all at <tier>/nodes/.
+  const nodesHomes = [];
   try {
+    for (const tier of readdirSync(DESIGN_ROOT)) nodesHomes.push(join(DESIGN_ROOT, tier, "nodes"));
+  } catch {
+    /* no design root: nothing declares a credential */
+  }
+  for (const nodesHome of nodesHomes) try {
     for (const pkg of readdirSync(nodesHome)) {
       try {
         for (const f of readdirSync(join(nodesHome, pkg, "credentials"))) if (isDefFile(f)) credentialDefs.add(defName(f));
@@ -859,24 +831,8 @@ for (const orgDir of [DS, ...orgDirs]) {
       if (f.endsWith(".js") && !declared.has(f.slice(0, -3)))
         report("error", join(folder, f), `${f} is a lifecycle handler no manifest opted into. Add "${f.slice(0, -3)}" to the manifest's lifecycle array, or delete the file — un-opted code never runs`);
 
-    /**
-     * LATCH, RETIRED FROM THE MANIFEST (2026-08-31, MCP guide §The Component Latch).
-     *
-     * It moved to the STATE, in the app's own tree, beside that state's `layout:` and
-     * `preview:`. A component said one thing about itself for the whole of its life, but a
-     * page is addressable when it IS the page and not when it is a summary in the flow, and
-     * only the state knows which of those is on screen.
-     *
-     * An ERROR rather than a silent ignore: nothing reads this key any more, so a manifest
-     * still carrying it declares an intent that never happens, and the author has no way to
-     * tell that from a latch that simply does not work.
-     */
     if (readDef(mf).latch !== undefined)
-      report(
-        "error",
-        mf,
-        `"latch" is no longer a manifest key — it moved to the STATE (2026-08-31). Declare it on the app state this component is addressable IN, beside that state's layout: \`states: { <state>: { layout: ..., latch: { title: "..." } } }\`. Nothing reads a manifest latch, so this one produces no pill (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`,
-      );
+      report("error", mf, `"latch" is retired (2026-09-07). Delete the key — nothing reads it`);
   }
 }
 
@@ -910,9 +866,20 @@ function readAppSizes(dir) {
   try {
     const sizes = {};
     for (const [k, v] of Object.entries(readDef(p).appSize ?? {})) sizes[k] = typeof v === "string" ? v : v?.$value;
+    // `flex` IS THE SDK'S OWN WORD, NEVER A TOKEN (docs.unoverse.ai/design/apps): it means
+    // "fill the space remaining beside whatever core is open", on a slot and on a mounted
+    // template alike. A token named flex hard-codes ONE core's width and is wrong beside every
+    // other core: observed live 2026-09-10, an org's flex of 100% minus a 360px rail left a
+    // mounted grid overlapping a 480px voice core. The word is reserved; the file says so.
+    if (Object.prototype.hasOwnProperty.call(sizes, "flex"))
+      report("error", p, `app-sizes names "flex". flex is the SDK's own word (fill the space remaining beside whatever core is open), never a token: a token named flex hard-codes one core's width and is wrong beside every other core. Delete it; layouts keep writing appWidth: flex (docs.unoverse.ai/design/apps)`);
     return sizes;
-  } catch {
-    return null; // the file lints separately
+  } catch (e) {
+    // SAID, NOT SWALLOWED (2026-09-10): a sizes file that will not parse used to return null
+    // here, and the org silently inherited the foundation's set, so every width of its own
+    // "named no app size" and the real fault, a stray colon in the file, was never named.
+    report("error", p, `app-sizes is not valid ${p.endsWith(".json") ? "JSON" : "YAML"}: ${String(e?.message ?? e).split("\n")[0]}. Until it parses, none of this org's own sizes exist`);
+    return null;
   }
 }
 function appSizesForFile(file) {
@@ -975,13 +942,39 @@ function componentNamesForFile(file) {
   return names;
 }
 
+// THE PLACES APPS DECLARE (UNOVERSE_SCREEN.md §2.2), across the whole tree. A component is shared
+// by every app that shows it, so a state's `place:` is checked against every app's places, plus
+// `chat`. Read once per run: every app layout under any `apps/` folder, every `Place` node in it.
+let placeNamesCache;
+function placeNames() {
+  if (placeNamesCache !== undefined) return placeNamesCache;
+  const names = new Set();
+  const walk = (n) => {
+    if (Array.isArray(n)) return n.forEach(walk);
+    if (!n || typeof n !== "object") return;
+    if (n.type === "Place" && typeof n.name === "string") names.add(n.name);
+    for (const v of Object.values(n)) walk(v);
+  };
+  const roots = [DS, ...readdirSync(DESIGN_ROOT).filter((e) => !e.startsWith(".")).map((e) => join(DESIGN_ROOT, e))];
+  for (const root of new Set(roots))
+    for (const f of jsonFiles(join(root, "apps"))) {
+      try {
+        walk(parseDef(readText(f), f));
+      } catch {
+        /* an unreadable file is reported by its own lint; it declares no place here */
+      }
+    }
+  placeNamesCache = names;
+  return names;
+}
+
 
   // The run context: everything the extracted rule modules close over. Built here so it
   // cannot outlive the run, and passed once rather than threaded as ten parameters.
   const ctx = {
     DESIGN_ROOT, DS, orgDirs, report, spaceSteps, stepList, checkDimension, checkToken, checkCondition,
-    appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists,
-    isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePath, isTemplatePart, defRoot, readText,
+    appSizesForFile, componentNamesForFile, placeNames, refResolves, canonicalRef, declaredProps, atomsDirExists,
+    isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePath, isTemplatePart, isAgentPath, defRoot, readText,
   };
   const walkNode = makeWalkNode(ctx);
   const lintFile = makeLintFile({ ...ctx, walkNode });

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

@@ -13,7 +13,7 @@
 // ── ground truth (mirrors design/_schema/unoverse.schema.json + server guards) ──
 export const PRIMITIVES = new Set([
   "Box", "Stack", "Row", "Column", "Each", "Switch", "ComponentSlot", "Timeline",
-  "Text", "Image", "Button", "Input", "Select", "Markdown", "Skeleton", "Icon", "Ref", "Orb", "Template",
+  "Text", "Image", "Button", "Input", "Select", "Markdown", "Skeleton", "Icon", "Ref", "Orb", "Template", "Place",
 ]);
 export const CONDITION_KEYS = new Set(["field", "eq", "ne", "in"]);
 
@@ -57,7 +57,7 @@ export const PROP_KEYS = [
  */
 export const INTERFACE_FIELDS = new Set([
   "universal_id", "title", "description", "object_type", "key_need", "source_url", "source_id",
-  "tagline", "shortDescription", "introParagraph", "callToAction", "actionPrompt", "primaryImage", "images", "action",
+  "tagline", "shortDescription", "introParagraph", "callToAction", "primaryImage", "images", "action",
   "bodyCopy", "features", "mainCategory", "section", "needs",
 ]);
 
@@ -78,7 +78,7 @@ export const PRIMITIVE_PROPS = {
   Column: ["children", "autoScroll", "revealOnStick", "appWidth"],
   Text: ["value"],
   Image: ["src", "alt"],
-  Markdown: ["value", "inheritLinkColor"],
+  Markdown: ["value", "inheritLinkColor", "citeAction"],
   Icon: ["icon", "name"],
   Skeleton: ["variant"],
   Orb: ["state", "size"],
@@ -94,6 +94,9 @@ export const PRIMITIVE_PROPS = {
   // template's machinery. `name` addresses the manifest's `templates:` entry;
   // `frame` is the dressing drawn around it when occupied.
   Template: ["name", "frame", "template", "director", "appWidth"],
+  // A PLACE (UNOVERSE_SCREEN.md §2.2): a named spot the screen shows interfaces into.
+  // `holds` is one or many; `frame` and `fallback` work as they do on a ComponentSlot.
+  Place: ["name", "holds", "frame", "fallback", "appWidth"],
   Timeline: ["user", "assistant", "userData", "assistantData", "autoScroll"],
 };
 

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

@@ -25,10 +25,12 @@ const SEARCH_KEYS = ["component", "type", "include", "pick", "items"];
 // The `object_type`s a place may admit. Apps and skills are absent by construction: the
 // page's own searches are SILENT (no app unlocked, no tool minted, no card lane, no
 // director woken), or every place would rain cards onto a page still assembling itself.
-const QUERY_TYPES = ["services", "images", "needs", "actions"];
+// `products` since migration 035 (2026-09-05; `services` retired 2026-09-07, `actions` with it:
+// no row is written as one). Each word maps to a declared spatial type (guarded by a test).
+const QUERY_TYPES = ["products", "images", "needs"];
 
 export function makeWalkNode(ctx) {
-  const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, defRoot } = ctx;
+  const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, isTemplatePart, defRoot } = ctx;
   // One director per LAYOUT FILE, tracked for this run only (each file is walked once).
   const directorsSeen = new Map();
 
@@ -36,6 +38,13 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
   if (Array.isArray(node)) return node.forEach((n) => walkNode(n, file, root, widthCap));
   if (!node || typeof node !== "object") return;
 
+  // THE ✕ BELONGS TO THE TEMPLATE'S LAYOUT, NEVER TO A PART (2026-09-07). `setValue` writes
+  // the interface's OWN slice (docs/design/state.md) and a part is its own interface, so a
+  // close inside a part retracts the PART into the chat column while the page stays open
+  // beside it (observed live: a page's hero, ✕ and all, sitting in the flow).
+  if (node.type === "Ref" && node.ref === "close-button" && isTemplatePart(file))
+    report("error", file, `a close-button inside a template PART writes the part's own slice, not the template's — the page stays open and the part falls into the chat. Move the ✕ to the template's layout (layouts/<state>.yaml), where its setValue writes the template's state`);
+
   // $include — resolves against the DEFINITION ROOT (layouts/ states/ components/…)
   if (typeof node.$include === "string") {
     const a = defPath(root, node.$include);
@@ -129,8 +138,9 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
             report("error", file, `a delivery band has no "${k}". It reads ${DELIVERY_KEYS.map((x) => `"${x}"`).join(", ")} (§9b; a place that names a component is a search place)`);
         if (d.pick !== undefined && (typeof d.pick !== "number" || d.pick < 1))
           report("error", file, `director.pick is a NUMBER — how many the director keeps, a cap the machine enforces (§9e rule 9)`);
-        if (d.rules !== undefined && typeof d.rules !== "string")
-          report("error", file, `director.rules is written like a brief: one string of English (§9b)`);
+        // NOTHING READS `rules`: the director's model was removed (UNOVERSE_SCREEN.md §2.7).
+        if (d.rules !== undefined)
+          report("warn", file, `director.rules is ignored: no model reads it any more. A band holds what arrives in search rank, up to pick. Remove it`);
         if (d.preview !== undefined && (!Array.isArray(d.preview) || d.preview.some((c) => typeof c !== "string")))
           report("error", file, `director.preview is an array of component names — Studio's stand-ins until a real run exists (§9b rule 6)`);
         else if (Array.isArray(d.preview)) {

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

@@ -1,15 +1,19 @@
 /**
- * The linters. TWO of them, because there are two things to validate and they share
- * almost nothing.
+ * The linters. FOUR siblings, one per kind of thing a developer authors, and every kind
+ * is checked the same way: `unoverse lint`, the publish gate, CI, all through
+ * items/publish lintForPublish.
  *
- *   nodes/  node manifests: JSON Schema per part, plus the cross-file rules a schema
- *           cannot express (events matching output connectors, calls reachable by name,
- *           credentials declared in the package that needs them)
- *   design/ definitions: a CLOSED primitive set, a closed style vocabulary, token-only
- *           values, Switch discriminants, layouts reachable from a case
+ *   nodes/    node manifests: JSON Schema per part, plus the cross-file rules a schema
+ *             cannot express (events matching output connectors, calls reachable by name,
+ *             credentials declared in the package that needs them)
+ *   design/   definitions: a CLOSED primitive set, a closed style vocabulary, token-only
+ *             values, Switch discriminants, layouts reachable from a case
+ *   objects/  objects and pipelines: schema per file, plus the rules a schema cannot say
+ *   prompts/  Agent skills and prompt blocks: frontmatter that parses, the fields the
+ *             loaders need, and the discoverability contract on whenToUse
  *
- * They share `context.mjs` and nothing else. One reports on `api/run.yaml`, the other on
- * whether a colour is a raw hex. Merging them would produce a linter that is worse at both.
+ * They share `context.mjs` and nothing else. One reports on `api/run.yaml`, another on
+ * whether a colour is a raw hex. Merging them would produce a linter that is worse at all.
  *
  * WHY THEY LIVE HERE rather than in scripts/. The same rules are needed by four callers,
  * and only one of them is a terminal:
@@ -25,4 +29,6 @@
 
 export { lintNodes, hasErrors as nodesHaveErrors } from "./nodes/index.mjs";
 export { lintDefinitions, hasErrors as definitionsHaveErrors } from "./design/index.mjs";
+export { lintObjects, hasErrors as objectsHaveErrors } from "./objects/index.mjs";
+export { lintPrompts, hasErrors as promptsHaveErrors } from "./prompts/index.mjs";
 export { problems, report, rel, reset } from "./context.mjs";

package/vendor/base/src/lint/nodes/blocks.mjs

@@ -23,7 +23,7 @@ export const HANDLEBARS_HELPERS = new Set([
 ]);
 
 /**
- * The prompt-block library: prompts/blocks/**\/*.md, keyed the way the resolver keys them
+ * The prompt-block library: design/marketplace/blocks/**\/*.md, keyed the way the resolver keys them
  * (engine/src/template/promptBlocks.ts) — the filename camelCased, so markdown-guidelines.md is
  * referenced as {{prompt.markdownGuidelines}}.
  *
@@ -41,7 +41,11 @@ export const HANDLEBARS_HELPERS = new Set([
 const CACHE = new Map();
 
 export function promptBlocks() {
-  const home = resolve(state.nodesHome, "../prompts/blocks");
+  // The block library is the marketplace tier's. Beside the nodes when they ARE that
+  // tier (design/marketplace/{nodes,blocks}); one tier over for an org's own nodes
+  // (design/<org>/nodes → design/marketplace/blocks).
+  const home = [resolve(state.nodesHome, "../blocks"), resolve(state.nodesHome, "../../marketplace/blocks")]
+    .find((d) => existsSync(d)) ?? resolve(state.nodesHome, "../../marketplace/blocks");
   const cached = CACHE.get(home);
   if (cached) return cached;
 

package/vendor/base/src/lint/nodes/index.mjs

@@ -13,7 +13,7 @@
  * without it is the gap LOCAL_STUDIO.md:246 names: "a malformed definition is one restart
  * from a broken server", and a published row does not even need the restart.
  *
- * FOUR TIERS (docs/architecture/DECLARATIVE_NODES.md §6). This is tiers 2 and 3.
+ * FOUR TIERS (docs/architecture/authoring/DECLARATIVE_NODES.md §6). This is tiers 2 and 3.
  *   1  editor    $schema pointers + .vscode yaml.schemas, no tool
  *   2  structural   every part validated against the node schemas (packages/docs/schemas/nodes)
  *   3  semantic     the cross-file rules a schema cannot express
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
 import { problems, derivedKinds, reset, report } from "../context.mjs";
 import { loadSchemas } from "./schema.mjs";
 import { lintPackage } from "./package.mjs";
+import { lintAttachments } from "./node.mjs";
 
 /**
  * Lint every node package under `nodesHome`.
@@ -72,6 +73,10 @@ export function lintNodes(nodesHome) {
     nodeCount += lintPackage(dir);
   }
 
+  // AFTER every package: an attachment names no host, so whether it fits one cannot be known
+  // until every node's configSchema has been read. See lintAttachments.
+  lintAttachments();
+
   const rank = { error: 0, warn: 1, hint: 2 };
   const sorted = [...problems].sort((a, b) => rank[a.level] - rank[b.level] || a.file.localeCompare(b.file));
   return { problems: sorted, derivedKinds: new Map(derivedKinds), nodeCount, pkgCount, nodesHome: home };