unoverse 0.1.170 → 0.1.172

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unoverse",
-  "version": "0.1.170",
+  "version": "0.1.172",
   "description": "The Unoverse front door — create a Studio project, a universe, or a client app, and launch Studio.",
   "license": "SEE LICENSE IN README.md",
   "type": "module",

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

@@ -28,7 +28,7 @@ function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
       ? readdirSync(d).filter(isDefFile).map(defName)
       : [];
   };
-  // TEMPLATES: stateOrder lists LOCAL states + LAYOUTS in picker order (docs/design/05) —
+  // TEMPLATES: stateOrder lists LOCAL states + LAYOUTS in picker order (docs.unoverse.ai/design/apps) —
   // a layout name (the view a component enters) is a valid entry. COMPONENTS: states only.
   const stateNames = dirNames("states");
   const onDisk = new Set([...stateNames, ...(includeLayouts ? dirNames("layouts") : [])]);
@@ -39,7 +39,7 @@ function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
   // legitimately omitted, so never warn on layouts.
   for (const name of stateNames)
     if (!order.includes(name))
-      report("warn", file, `states/${name}.json is not in stateOrder. It falls to the end of the picker; add it to lock the order (docs/design/07)`);
+      report("warn", file, `states/${name}.json is not in stateOrder. It falls to the end of the picker; add it to lock the order (docs.unoverse.ai/design/studio)`);
 }
 
 // ── lint one file ──
@@ -49,7 +49,7 @@ function lintFile(file) {
   const src = readText(file);
 
   // LAW 1 — tokens only (skip manifest + fixture; styles/ is never in a def home).
-  // Exempt: `appWidth` — the HOST-facing outer width (state-owned sizing, docs/design/05).
+  // 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))
@@ -74,7 +74,7 @@ function lintFile(file) {
         }
       }
       if (RAW_VALUE.test(code) && !/^\s*"?appWidth"?\s*:/.test(code))
-        report("error", file, `raw value. Token names only; add/scale a token in the org styles instead (LAW 1, docs/design/06): ${code.trim()}`, i + 1);
+        report("error", file, `raw value. Token names only; add/scale a token in the org styles instead (LAW 1, docs.unoverse.ai/design/styles-and-tokens): ${code.trim()}`, i + 1);
     });
 
   let json;
@@ -93,9 +93,9 @@ function lintFile(file) {
     if (isAppPath(file)) {
       // TEMPLATE manifest = the envelope. Requires binding + a resolvable root.
       for (const req of ["name", "whenToUse"])
-        if (!json[req]) report("warn", file, `template manifest missing "${req}": ${req === "whenToUse" ? "the AI selects the app by it" : "the display name"} (docs/design/05)`);
+        if (!json[req]) report("warn", file, `template manifest missing "${req}": ${req === "whenToUse" ? "the AI selects the app by it" : "the display name"} (docs.unoverse.ai/design/apps)`);
       if (!(json.binding && json.binding.workflow))
-        report("warn", file, `template manifest has no binding.workflow. The app owns its workflow binding (docs/design/05)`);
+        report("warn", file, `template manifest has no binding.workflow. The app owns its workflow binding (docs.unoverse.ai/design/apps)`);
       // Two valid roots (definitions.ts:229): the STANDARD manifest-only form (root =
       // layouts/<layout>), OR a `<name>` envelope OVERRIDE (its own root). Only the
       // manifest-only form must resolve a layout; an envelope-form template supplies its own.
@@ -103,7 +103,7 @@ function lintFile(file) {
       if (!hasEnvelope) {
         const layoutName = json.layout ?? "main";
         if (!defPath(join(root, "layouts"), layoutName))
-          report("error", file, `manifest.layout "${layoutName}" → layouts/${layoutName} does not exist (and no <name> envelope) (docs/design/05)`);
+          report("error", file, `manifest.layout "${layoutName}" → layouts/${layoutName} does not exist (and no <name> envelope) (docs.unoverse.ai/design/apps)`);
       }
       // THE TEMPLATE TREE (STATE_MODEL v2, checkpoint 2026-08-08): a manifest
       // `states:` block declares the whole machine — validate the DECLARATION:
@@ -171,7 +171,7 @@ function lintFile(file) {
             report("warn", file, `"stateOrder" is superseded by the "states" tree (the ladder derives from the top level minus the base) — delete it (STATE_MODEL §5)`);
         }
       } else checkStateOrder(json.stateOrder, root, file, /* includeLayouts */ true);
-      // ONE STATE AT A TIME (docs/design/04): the active state is derived from the
+      // ONE STATE AT A TIME (docs.unoverse.ai/design/state): the active state is derived from the
       // latest surfaced VIEW, so no two surfaces in one template may claim the same
       // view — the active surface would be ambiguous.
       {
@@ -182,7 +182,7 @@ function lintFile(file) {
           const w = n.type === "ComponentSlot" ? n.select?.where : null;
           if ((w?.field === "view" || w?.field === "defaultState") && typeof w.eq === "string") {
             if (claims.has(w.eq))
-              report("error", file, `two reaction surfaces claim the view "${w.eq}" (${claims.get(w.eq)} and ${from}). A template is in ONE state at a time; each view has exactly one surface (docs/design/04)`);
+              report("error", file, `two reaction surfaces claim the view "${w.eq}" (${claims.get(w.eq)} and ${from}). A template is in ONE state at a time; each view has exactly one surface (docs.unoverse.ai/design/state)`);
             else claims.set(w.eq, from);
           }
           for (const v of Object.values(n)) if (v && typeof v === "object") collectClaims(v, from);
@@ -200,16 +200,16 @@ function lintFile(file) {
         }
       }
       if (json.mode !== undefined && json.defaultState === undefined)
-        report("warn", file, `"mode" was renamed to "defaultState". Still read as a fallback, but rename it (docs/design/04)`);
+        report("warn", file, `"mode" was renamed to "defaultState". Still read as a fallback, but rename it (docs.unoverse.ai/design/state)`);
       // `preview` — the per-state MOCK map ({ "<state>": ["course-card", …] }): each key
       // must be a states/ file, each name a real component. A repeated name seeds
       // several instances (a card rail).
       if (json.preview !== undefined) {
         if (!json.preview || typeof json.preview !== "object" || Array.isArray(json.preview))
-          report("error", file, `"preview" must be an object mapping state names to component-name arrays (docs/design/07)`);
+          report("error", file, `"preview" must be an object mapping state names to component-name arrays (docs.unoverse.ai/design/studio)`);
         else {
           // preview keys are per-LAYOUT (the component view Studio mocks) or a local state
-          // (docs/design/05) — resolve against states/ ∪ layouts/, same as stateOrder.
+          // (docs.unoverse.ai/design/apps) — resolve against states/ ∪ layouts/, same as stateOrder.
           const viewsIn = (sub) => {
             const d = join(root, sub);
             return existsSync(d)
@@ -228,7 +228,7 @@ function lintFile(file) {
           const comps = componentNamesForFile(file);
           for (const [state, list] of Object.entries(json.preview)) {
             if (!states.has(state))
-              report("error", file, `preview."${state}". No states/${state}.json or layouts/${state}.json in this template (docs/design/07)`);
+              report("error", file, `preview."${state}". No states/${state}.json or layouts/${state}.json in this template (docs.unoverse.ai/design/studio)`);
             // An OBJECT entry is authored TEMPLATE-STATE mock data (what the workflow
             // would have echoed — comments, a discriminant, an anchor), merged verbatim
             // when the state's pill is picked. Only the two shapes; anything else errors.
@@ -243,33 +243,33 @@ function lintFile(file) {
           }
         }
       }
-      // Sizing is STATE-OWNED (docs/design/05): the layout root's `appWidth` is the core
+      // Sizing is STATE-OWNED (docs.unoverse.ai/design/apps): the layout root's `appWidth` is the core
       // surface's constant width; a panel slot's `appWidth` slides out on top. Manifest
       // width/focusWidth are DEAD — nothing reads them; there is no fallback.
       for (const dep of ["width", "focusWidth"])
         if (json[dep] !== undefined)
-          report("error", file, `manifest "${dep}" is dead. Nothing reads it. Sizing is state-owned: \`appWidth\` on the layout root (constant core width) or on a panel (slide-out width) (docs/design/05)`);
+          report("error", file, `manifest "${dep}" is dead. Nothing reads it. Sizing is state-owned: \`appWidth\` on the layout root (constant core width) or on a panel (slide-out width) (docs.unoverse.ai/design/apps)`);
     } else {
       // COMPONENT manifest = OPTIONAL spatial discovery. No binding. Mirrors the
       // discovery-meta assertions in server/src/runtime/microapp-structure.test.ts.
       const desc = typeof json.description === "string" ? json.description.trim() : "";
       if (desc.length < 20)
-        report("error", file, `discovery manifest.description missing/too short. One line (≥20 chars) saying what the component IS (docs/design/03a)`);
+        report("error", file, `discovery manifest.description missing/too short. One line (≥20 chars) saying what the component IS (docs.unoverse.ai/design/components)`);
       else if (desc.length > 120)
-        report("error", file, `discovery manifest.description is ${desc.length} chars: it's the listing subtitle (≤120); move detail into whenToUse (docs/design/03a)`);
+        report("error", file, `discovery manifest.description is ${desc.length} chars: it's the listing subtitle (≤120); move detail into whenToUse (docs.unoverse.ai/design/components)`);
       const wtu = typeof json.whenToUse === "string" ? json.whenToUse.trim() : "";
       if (wtu.length < 20)
-        report("error", file, `discovery manifest.whenToUse missing/too short. The utterance-shaped selection text findIntent ranks on (docs/design/03a)`);
+        report("error", file, `discovery manifest.whenToUse missing/too short. The utterance-shaped selection text findIntent ranks on (docs.unoverse.ai/design/components)`);
       else if (/\b(pick when|use (this|when)|when the user|the user (asks|wants|needs)|select (this|when))\b/i.test(wtu))
-        report("error", file, `discovery manifest.whenToUse is selector-shaped. Write the words the USER would say, not instructions about the user (docs/design/03a)`);
+        report("error", file, `discovery manifest.whenToUse is selector-shaped. Write the words the USER would say, not instructions about the user (docs.unoverse.ai/design/components)`);
       if (json.binding)
-        report("warn", file, `a component discovery manifest has no workflow. Drop "binding" (a component is streamed or node-hydrated) (docs/design/03a)`);
-      // `lifetime` — OPTIONAL render lifetime (docs/design/04 §Two lifetimes). Closed set:
+        report("warn", file, `a component discovery manifest has no workflow. Drop "binding" (a component is streamed or node-hydrated) (docs.unoverse.ai/design/components)`);
+      // `lifetime` — OPTIONAL render lifetime (docs.unoverse.ai/design/state §Two lifetimes). Closed set:
       // "turn" (default — the universal new-turn reset) | "conversation" (durable
       // conversation-scoped surface: conversation-keyed instance, exempt from the
       // new-turn reset, retired only by replacement, self-close, or a template swap).
       if (json.lifetime !== undefined && json.lifetime !== "turn" && json.lifetime !== "conversation")
-        report("error", file, `manifest "lifetime" must be "turn" (default) or "conversation". Got ${JSON.stringify(json.lifetime)} (docs/design/04 §Two lifetimes)`);
+        report("error", file, `manifest "lifetime" must be "turn" (default) or "conversation". Got ${JSON.stringify(json.lifetime)} (docs.unoverse.ai/design/state §Two lifetimes)`);
     }
     return;
   }
@@ -280,11 +280,11 @@ function lintFile(file) {
   if (isEnvelope) {
     // COMPONENT envelope (templates have no envelope — their manifest is it).
     for (const req of ["kind", "name", "root"])
-      if (json[req] === undefined) report("error", file, `envelope missing "${req}" (docs/design/02)`);
+      if (json[req] === undefined) report("error", file, `envelope missing "${req}" (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
     if (json.kind && !["component", "template", "atom"].includes(json.kind))
       report("error", file, `unknown kind "${json.kind}"`);
     if (json.kind === "component" && !json.category)
-      report("warn", file, `component has no "category". Used to group it in the palette (docs/design/02)`);
+      report("warn", file, `component has no "category". Used to group it in the palette (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
     if (json.root) walkNode(json.root, file, root);
 
     // ── the contained-microapp discipline (mirrors microapp-structure.test.ts) ──
@@ -300,7 +300,7 @@ function lintFile(file) {
       if (defPath(root, "manifest"))
         for (const k of ["description", "whenToUse"])
           if (json[k] !== undefined)
-            report("error", file, `envelope duplicates manifest meta "${k}". The discovery manifest is the single home (docs/design/03a)`);
+            report("error", file, `envelope duplicates manifest meta "${k}". The discovery manifest is the single home (docs.unoverse.ai/design/components)`);
 
       // deprecated bridge: a top-level `defaultState` triggers the component node APP_DATA emit
       if (json.defaultState !== undefined)
@@ -317,7 +317,7 @@ function lintFile(file) {
           .filter(([, v]) => !(v && typeof v === "object" && typeof v.input === "boolean"))
           .map(([k]) => k);
         if (undeclared.length)
-          report("error", file, `microapp props [${undeclared.join(", ")}] do not declare "input". Every prop says what fills it: input:true = a workflow streams it (it joins the node's configSchema); input:false = nothing does (a preview axis, or a literal the host passes via Ref with). Unflagged props default to INPUTS (docs/design/03)`);
+          report("error", file, `microapp props [${undeclared.join(", ")}] do not declare "input". Every prop says what fills it: input:true = a workflow streams it (it joins the node's configSchema); input:false = nothing does (a preview axis, or a literal the host passes via Ref with). Unflagged props default to INPUTS (docs.unoverse.ai/design/components)`);
 
         // STATE MODEL v2 (UNOVERSE_STATE_MODEL §5): an authored `state.view` TREE is
         // the component's state machine — the ONE object the scalar rule admits.
@@ -344,9 +344,9 @@ function lintFile(file) {
           for (const [k, v] of Object.entries(json.state)) {
             if (k === "view" && viewTree) continue;
             if (Array.isArray(v) || (v && typeof v === "object"))
-              report("error", file, `state.${k} is an ${Array.isArray(v) ? "array" : "object"}. The state block is SCALAR view-state only (the one object allowed is a well-formed v2 \`state.view\` tree); workflow-fed data → props (input:true), static content → hardcode in the layout (docs/design/03)`);
+              report("error", file, `state.${k} is an ${Array.isArray(v) ? "array" : "object"}. The state block is SCALAR view-state only (the one object allowed is a well-formed v2 \`state.view\` tree); workflow-fed data → props (input:true), static content → hardcode in the layout (docs.unoverse.ai/design/components)`);
             else if (typeof v === "string" && /^https?:\/\//.test(v))
-              report("error", file, `state.${k} is a URL. Content, not view-state; hardcode it in the layout (or props input:true if workflow-fed) (docs/design/03)`);
+              report("error", file, `state.${k} is a URL. Content, not view-state; hardcode it in the layout (or props input:true if workflow-fed) (docs.unoverse.ai/design/components)`);
           }
 
         if (hasLayouts) {
@@ -356,7 +356,7 @@ function lintFile(file) {
             if (!raw.includes('"on":"view"') || !/"\$include":"layouts\//.test(raw))
               report("error", file, `a v2 component (state.view tree) must root-Switch on "view" → $include layouts/<layout> (each state owns its layout; same-name by convention) (STATE_MODEL §5)`);
           } else if (!raw.includes('"on":"defaultState"') || !/"\$include":"layouts\//.test(raw))
-            report("error", file, `a faced component's root must Switch on defaultState → $include layouts/<state> (legacy; or declare a v2 state.view tree and Switch on "view") (docs/design/03)`);
+            report("error", file, `a faced component's root must Switch on defaultState → $include layouts/<state> (legacy; or declare a v2 state.view tree and Switch on "view") (docs.unoverse.ai/design/components)`);
 
           // ── face set ⇄ layouts/ cross-check (OPEN name set — inline/focused/<any>) ──
           // The FACES are the root Switch's cases; Studio's face toggle and the render
@@ -375,7 +375,7 @@ function lintFile(file) {
             const caseNames = Object.keys(cases).filter((k) => k !== "default");
             // inline is the UNIVERSAL default face: an unknown/absent defaultState must
             // render SOMETHING — require an `inline` case or an explicit `default`.
-            // EXCEPTION — a SURFACE-ONLY component (docs/design/03): its manifest
+            // EXCEPTION — a SURFACE-ONLY component (docs.unoverse.ai/design/components): its manifest
             // declares a SURFACED arrival (defaultState naming one of its cases, not
             // inline), and it deliberately renders NOTHING while unsurfaced (e.g. a
             // rail card retired by a new turn). Then omitting inline/default is the
@@ -409,7 +409,7 @@ function lintFile(file) {
               if (name !== "default" && layoutName !== expected)
                 report("error", file, viewTree
                   ? `state "${name}" declares layout "${expected}" but its case includes layouts/${layoutName} — the tree's declaration and the case must agree (STATE_MODEL §5 rule 1)`
-                  : `face case "${name}" includes layouts/${layoutName}. The layout FILENAME is the state name; rename one so they match (docs/design/03)`);
+                  : `face case "${name}" includes layouts/${layoutName}. The layout FILENAME is the state name; rename one so they match (docs.unoverse.ai/design/components)`);
             }
             // v2: tree-declared layouts (including nested substates' and variants') are
             // reachable by declaration — seed them so the orphan check knows them.
@@ -457,7 +457,7 @@ function lintFile(file) {
               for (const lf of readdirSync(layoutsDir).filter(isDefFile)) {
                 const lname = defName(lf);
                 if (!usedLayouts.has(lname))
-                  report("warn", file, `layouts/${lf} is not referenced by any Switch case. An orphan face is unreachable (add a case "${lname}" or delete the file) (docs/design/03)`);
+                  report("warn", file, `layouts/${lf} is not referenced by any Switch case. An orphan face is unreachable (add a case "${lname}" or delete the file) (docs.unoverse.ai/design/components)`);
               }
           }
           // v2 STRAGGLER NUDGE: inside a component that declares a tree, every
@@ -486,14 +486,14 @@ function lintFile(file) {
             ? (viewTree.initial ?? Object.keys(viewTree.states)[0])
             : (mDefault ?? (hasStateBlock ? json.state.defaultState : undefined));
           if (typeof arrival !== "string")
-            report("error", file, `a faced component must declare its base state — a v2 state.view tree \`initial\`, or (legacy) manifest.defaultState / state.defaultState (docs/design/03)`);
+            report("error", file, `a faced component must declare its base state — a v2 state.view tree \`initial\`, or (legacy) manifest.defaultState / state.defaultState (docs.unoverse.ai/design/components)`);
         }
         if (stateFiles.length) {
           const order = Array.isArray(json.stateOrder) ? [...json.stateOrder].sort() : null;
           if (!order || !order.length)
-            report("error", file, `has states/ but no stateOrder in the envelope (docs/design/03)`);
+            report("error", file, `has states/ but no stateOrder in the envelope (docs.unoverse.ai/design/components)`);
           else if (JSON.stringify(order) !== JSON.stringify(stateFiles))
-            report("error", file, `stateOrder and states/*.json must name the same set (docs/design/03)`);
+            report("error", file, `stateOrder and states/*.json must name the same set (docs.unoverse.ai/design/components)`);
         }
       }
     } else {
@@ -502,7 +502,7 @@ function lintFile(file) {
   } else {
     // bare partial (layouts/ states/ components/ blocks/, or an atom). A template
     // layout's TOP-LEVEL node is the app's layout root — the one non-slot home for
-    // `appWidth` (state-owned sizing, docs/design/05).
+    // `appWidth` (state-owned sizing, docs.unoverse.ai/design/apps).
     walkNode(json, file, root, null, /[\\/]layouts[\\/][^\\/]+\.(json|yaml)$/.test(file) && isAppPath(file));
   }
 }

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

@@ -290,7 +290,7 @@ const checkDimension = (file, where, key, v) => {
     // or the scale drifts straight back to two vocabularies for the same number — which is
     // the state the t-shirt aliases left it in, and the reason they were retired.
     if (PAGE_WIDTH_KEYS.has(key) && layoutAlias.has(val))
-      report("error", file, `${where}.${key}: "${val}" has a name — use "${layoutAlias.get(val)}". A page-level width reads as what it IS; a bare step here puts two spellings on one value (docs/design/06)`);
+      report("error", file, `${where}.${key}: "${val}" has a name — use "${layoutAlias.get(val)}". A page-level width reads as what it IS; a bare step here puts two spellings on one value (docs.unoverse.ai/design/styles-and-tokens)`);
     // A shorthand ("auto auto 0 0" on `inset`) is a list of dimensions; each word is one.
     for (const word of val.trim().split(/\s+/)) {
       if (spaceSteps.has(word) || DIMENSION_LITERALS.has(word)) continue;
@@ -298,7 +298,7 @@ const checkDimension = (file, where, key, v) => {
       // percentage value; LAW 1 owns those, and `calc()`/`%` are legitimate escape hatches.
       if (/^\d/.test(word) && !/^\d+(\.\d+)?$/.test(word)) continue;
       if (/[()%]/.test(word)) continue; // calc(), min(), clamp(), 50%
-      report("error", file, `${where}.${key}: "${word}" is not a step on the space scale. Invalid values fall through as broken CSS (auto sizing). Real steps: ${stepList()} (docs/design/06)`);
+      report("error", file, `${where}.${key}: "${word}" is not a step on the space scale. Invalid values fall through as broken CSS (auto sizing). Real steps: ${stepList()} (docs.unoverse.ai/design/styles-and-tokens)`);
     }
   }
 };
@@ -329,7 +329,7 @@ const checkToken = (file, where, key, v) => {
     report(
       "error",
       file,
-      `${where}.${k}: "${val}" is not a ${bucket} token. Unknown names are handed to CSS verbatim and dropped — the style simply does not apply, with no error anywhere${extra}. Known: ${[...T[bucket]].sort().join(", ") || "none"} (docs/design/06)`,
+      `${where}.${k}: "${val}" is not a ${bucket} token. Unknown names are handed to CSS verbatim and dropped — the style simply does not apply, with no error anywhere${extra}. Known: ${[...T[bucket]].sort().join(", ") || "none"} (docs.unoverse.ai/design/styles-and-tokens)`,
     );
 
   // The straightforward one-bucket keys (background/color/shadow/radius*/font/lineHeight).
@@ -354,9 +354,9 @@ const checkToken = (file, where, key, v) => {
     const parts = v.trim().split(/\s+/);
     const [w, c] = parts.length > 1 ? parts : [null, parts[0]];
     if (w !== null && !T.borderWidth.has(w))
-      report("error", file, `${where}.${key}: "${w}" is not a border-width token (the leading word of "<width> <colour>"). Known: ${[...T.borderWidth].sort().join(", ") || "none"} (docs/design/06)`);
+      report("error", file, `${where}.${key}: "${w}" is not a border-width token (the leading word of "<width> <colour>"). Known: ${[...T.borderWidth].sort().join(", ") || "none"} (docs.unoverse.ai/design/styles-and-tokens)`);
     if (!LITERAL_VALUES.has(c) && !T.color.has(`border.${c}`) && !T.color.has(c))
-      report("error", file, `${where}.${key}: "${c}" resolves to no colour token (tried border.${c}, then ${c}). The border renders with no colour and nothing reports it (docs/design/06)`);
+      report("error", file, `${where}.${key}: "${c}" resolves to no colour token (tried border.${c}, then ${c}). The border renders with no colour and nothing reports it (docs.unoverse.ai/design/styles-and-tokens)`);
     return;
   }
 
@@ -407,7 +407,7 @@ const dsComponentNames = new Set(
     .filter((e) => !e.name.startsWith("."))
     .map((e) => (e.isDirectory() ? e.name : defName(e.name)).toLowerCase()),
 );
-// The ORG tier's component names, per org (docs/unoverse/UNOVERSE_COMPONENT_ORGS.md):
+// The ORG tier's component names, per org (docs.unoverse.ai/design/components):
 // a Ref may also resolve an org component — bare from inside that org's own tree (the
 // resolver's context rule), or org-qualified as `<org>/<name>` when two orgs share the
 // name. Org-privacy holds: a file only ever reaches its OWN org's components, and a
@@ -576,7 +576,7 @@ for (const orgDir of orgDirs) {
 
 // ── component-name uniqueness (per tier, no marketplace shadowing) ──
 // Names are unique WITHIN a home: two orgs may ship the same name (each addressed
-// `unoverse://components/<org>/<name>` — docs/unoverse/UNOVERSE_COMPONENT_ORGS.md),
+// `unoverse://components/<org>/<name>` — docs.unoverse.ai/design/components),
 // but an org may never SHADOW a marketplace name, so a bare ref stays unambiguous:
 // bare = the marketplace tier, or the single org that carries the name.
 {
@@ -627,7 +627,7 @@ for (const orgDir of orgDirs) {
         report(
           "error",
           mf,
-          `org "${org}" has ${defaults.length} apps with "default": true. An org has exactly ONE default app (its /mcp/${org} front door). Keep it on one manifest, remove it from the others (docs/unoverse/UNOVERSE_MCP_APP_PROTOCOL.md §4b)`,
+          `org "${org}" has ${defaults.length} apps with "default": true. An org has exactly ONE default app (its /mcp/${org} front door). Keep it on one manifest, remove it from the others (docs.unoverse.ai/design/apps §4b)`,
         );
   }
 
@@ -690,7 +690,7 @@ for (const orgDir of [DS, ...orgDirs]) {
 
     for (const e of entries) {
       if (!KNOWN_LIFECYCLES.has(e.phase))
-        report("error", mf, `lifecycle "${e.phase}" is not a phase the platform fires, so it would never run. Known: ${[...KNOWN_LIFECYCLES].join(", ")} (docs/unoverse/UNOVERSE_AUTHORING.md §3c)`);
+        report("error", mf, `lifecycle "${e.phase}" is not a phase the platform fires, so it would never run. Known: ${[...KNOWN_LIFECYCLES].join(", ")} (docs.unoverse.ai/unoverse/UNOVERSE_AUTHORING §3c)`);
       if (e.layouts !== undefined && !PHASES_WITH_LAYOUTS.has(e.phase))
         report("error", mf, `lifecycle "${e.phase}" declares layouts, but only ${[...PHASES_WITH_LAYOUTS].join(", ")} fires per view — the scope would be ignored`);
       // WHAT RUNS is named by `handler`; the phase only says WHEN. A custom hook is a
@@ -759,7 +759,7 @@ for (const orgDir of [DS, ...orgDirs]) {
         if (T) {
           for (const k of ["background", "color"])
             if (typeof latch[k] === "string" && latch[k].trim() && !T.color.has(latch[k]))
-              report("error", mf, `latch.${k}: "${latch[k]}" is not a colour token. Unknown names reach CSS verbatim and are dropped, so the pill renders unstyled with no error anywhere. Known: ${[...T.color].sort().join(", ") || "none"} (docs/design/06)`);
+              report("error", mf, `latch.${k}: "${latch[k]}" is not a colour token. Unknown names reach CSS verbatim and are dropped, so the pill renders unstyled with no error anywhere. Known: ${[...T.color].sort().join(", ") || "none"} (docs.unoverse.ai/design/styles-and-tokens)`);
         }
 
         /**
@@ -791,13 +791,13 @@ function checkCondition(vw, file, where) {
   if (typeof vw === "string") return; // bare truthy field
   if (vw && typeof vw === "object" && !Array.isArray(vw)) {
     if (typeof vw.field !== "string")
-      report("error", file, `${where}: condition needs a "field" (docs/design/04)`);
+      report("error", file, `${where}: condition needs a "field" (docs.unoverse.ai/design/state)`);
     const extra = Object.keys(vw).filter((k) => !CONDITION_KEYS.has(k));
     if (extra.length)
-      report("error", file, `${where}: illegal condition key(s) ${extra.join(", ")}. Only eq/ne/in/truthy exist; no and/or/arithmetic (derive in the node) (docs/design/03)`);
+      report("error", file, `${where}: illegal condition key(s) ${extra.join(", ")}. Only eq/ne/in/truthy exist; no and/or/arithmetic (derive in the node) (docs.unoverse.ai/design/components)`);
     return;
   }
-  report("error", file, `${where}: visibleWhen must be a field name or { field, eq|ne|in } (docs/design/04)`);
+  report("error", file, `${where}: visibleWhen must be a field name or { field, eq|ne|in } (docs.unoverse.ai/design/state)`);
 }
 
 // ── per-node structural walk ──

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

@@ -29,25 +29,25 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     const a = defPath(root, node.$include);
     const b = join(root, node.$include);
     if (!a && !existsSync(b))
-      report("error", file, `$include "${node.$include}" does not resolve under ${relative(process.cwd(), root)}/ (docs/design/03)`);
+      report("error", file, `$include "${node.$include}" does not resolve under ${relative(process.cwd(), root)}/ (docs.unoverse.ai/design/components)`);
     return; // the included file is linted on its own
   }
 
   const t = node.type;
   if (typeof t !== "string")
-    report("error", file, `node without "type" (and no $include). Every node names a primitive (docs/design/02)`);
+    report("error", file, `node without "type" (and no $include). Every node names a primitive (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
   else if (!PRIMITIVES.has(t))
-    report("error", file, `unknown primitive "${t}". The set is closed; compose, don't invent (docs/design/02)`);
+    report("error", file, `unknown primitive "${t}". The set is closed; compose, don't invent (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
 
   if (t === "Switch") {
     if (typeof node.on !== "string" || !node.cases || typeof node.cases !== "object")
-      report("error", file, `Switch needs "on" (the discriminant field) + "cases" (docs/design/04)`);
+      report("error", file, `Switch needs "on" (the discriminant field) + "cases" (docs.unoverse.ai/design/state)`);
     else
       for (const [caseKey, branch] of Object.entries(node.cases)) {
         const vw = branch && typeof branch === "object" ? branch.visibleWhen : undefined;
         const guarded = typeof vw === "string" ? vw : vw && typeof vw === "object" ? vw.field : null;
         if (guarded === node.on)
-          report("error", file, `Switch on "${node.on}" → case "${caseKey}" re-guards its own discriminant. A layer never guards itself; delete the visibleWhen (docs/design/03)`);
+          report("error", file, `Switch on "${node.on}" → case "${caseKey}" re-guards its own discriminant. A layer never guards itself; delete the visibleWhen (docs.unoverse.ai/design/components)`);
       }
   }
   // Each: a `template` + a list — EITHER a literal `items:[]` (hardcoded content,
@@ -55,11 +55,11 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
   if (t === "Each") {
     const hasList = Array.isArray(node.items) || (node.bind && typeof node.bind === "object" && node.bind.items);
     if (!node.template || !hasList)
-      report("error", file, `Each needs "template" + a list. Literal "items": [...] or "bind": { "items": "<field>" } (docs/design/03)`);
+      report("error", file, `Each needs "template" + a list. Literal "items": [...] or "bind": { "items": "<field>" } (docs.unoverse.ai/design/components)`);
   }
   if (t === "Ref") {
     if (typeof node.ref !== "string")
-      report("error", file, `Ref needs "ref": "<atom name>" (docs/design/03)`);
+      report("error", file, `Ref needs "ref": "<atom name>" (docs.unoverse.ai/design/components)`);
     else if (atomsDirExists && !refResolves(node.ref, file))
       report("error", file, `Ref "${node.ref}". No matching atom, shared component, or own-org component (bare, or "<org>/<name>" for the file's OWN org only — org-privacy); lookup is case-insensitive by name`);
     // RESOLVES IS NOT ENOUGH. Ref lookup ignores case; the marketplace fetches
@@ -96,7 +96,7 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
               file,
               `Ref "${node.ref}" ${key === "props" ? "remaps" : "passes"} "${name}", which the atom does not declare. ` +
                 `Both \`props\` and \`with\` are matched BY NAME against the atom's own props, and an unknown key is ` +
-                `silently ignored: the element renders and does nothing. ${node.ref} declares: ${known} (docs/design/03)`,
+                `silently ignored: the element renders and does nothing. ${node.ref} declares: ${known} (docs.unoverse.ai/design/components)`,
             );
           }
         }
@@ -109,9 +109,9 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     checkToken(file, t, "icon", node.icon);
   if (t === "ComponentSlot") {
     if (!node.select || typeof node.select !== "object")
-      report("error", file, `ComponentSlot needs "select" ({} for the conversation flow) (docs/design/05)`);
+      report("error", file, `ComponentSlot needs "select" ({} for the conversation flow) (docs.unoverse.ai/design/apps)`);
     else if (node.select.from === "all" && !node.select.type && !node.select.where)
-      report("warn", file, `global ComponentSlot (from:"all") with no "type" and no "where". Selects OLDEST-first; a trap in a multi-turn surface. Filter by "where" (the reaction contract, §5b) or pin "type", unless the shell is deliberately catch-all (docs/design/05)`);
+      report("warn", file, `global ComponentSlot (from:"all") with no "type" and no "where". Selects OLDEST-first; a trap in a multi-turn surface. Filter by "where" (the reaction contract, §5b) or pin "type", unless the shell is deliberately catch-all (docs.unoverse.ai/design/apps)`);
     // STATE-SELECTED UI (STATE_MODEL §5): a reaction surface reacts to the component's
     // PUBLIC state — the `view` axis (`defaultState` = legacy alias) — never to a
     // component's internal state (step/phase/…) which is private to the component.
@@ -122,16 +122,16 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     // claim exactly ONE view by `eq` — `ne`/`in`/bare selects make "which state is
     // the template in?" ambiguous.
     else if (node.select.where && (node.select.where.field === "view" || node.select.where.field === "defaultState") && typeof node.select.where.eq !== "string")
-      report("error", file, `a reaction surface claims exactly ONE view: select.where needs "eq": "<view>": ne/in/bare make the template's active state ambiguous (docs/design/04)`);
+      report("error", file, `a reaction surface claims exactly ONE view: select.where needs "eq": "<view>": ne/in/bare make the template's active state ambiguous (docs.unoverse.ai/design/state)`);
   }
 
-  // STATE-OWNED SIZING (docs/design/05): every PANEL states its width once via
+  // STATE-OWNED SIZING (docs.unoverse.ai/design/apps): every PANEL states its width once via
   // `appWidth`; the app is the sum of the open ones. A plain node = always open (the
   // core chat column); a reaction-surface ComponentSlot = open while occupied; a
   // visibleWhen pane = open while its condition matches.
   if (node.appWidth !== undefined) {
     if (typeof node.appWidth !== "string" || node.appWidth.trim() === "")
-      report("error", file, `"appWidth" must be a CSS width string ("360px", "min(50vw, 760px)") or a named app size ("chat", "rail", "panel") (docs/design/05)`);
+      report("error", file, `"appWidth" must be a CSS width string ("360px", "min(50vw, 760px)") or a named app size ("chat", "rail", "panel") (docs.unoverse.ai/design/apps)`);
     // `flex` is contract vocabulary, not a token: the surface takes the REMAINING
     // host space (the SDK reports a full-width app while it is active).
     // Any other bare name is a STANDARD SIZE — it must exist in the org's
@@ -140,17 +140,17 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     else if (node.appWidth !== "flex" && /^[a-z][a-z0-9-]*$/i.test(node.appWidth)) {
       const sizes = appSizesForFile(file);
       if (sizes && !(node.appWidth in sizes))
-        report("error", file, `"appWidth": "${node.appWidth}" names no app size. Use "flex", a CSS width, or a name from styles/semantic/app-sizes (known: ${Object.keys(sizes).join(", ") || "none"}) (docs/design/05)`);
+        report("error", file, `"appWidth": "${node.appWidth}" names no app size. Use "flex", a CSS width, or a name from styles/semantic/app-sizes (known: ${Object.keys(sizes).join(", ") || "none"}) (docs.unoverse.ai/design/apps)`);
     }
     if (t === "ComponentSlot" && !(node.select && node.select.where))
-      report("error", file, `"appWidth" on a ComponentSlot without select.where. Only a reaction surface can slide out; the flow slot never sizes the app (docs/design/05)`);
+      report("error", file, `"appWidth" on a ComponentSlot without select.where. Only a reaction surface can slide out; the flow slot never sizes the app (docs.unoverse.ai/design/apps)`);
     // ONE declaration per panel: the SDK sizes the frame FROM appWidth (width +
     // flex: 0 0 auto) — a frame width/flex alongside it is dead duplication that
     // can silently disagree.
     if (t === "ComponentSlot" && node.frame && node.frame.style) {
       for (const dup of ["width", "flex"])
         if (node.frame.style[dup] !== undefined)
-          report("error", file, `panel frame declares style.${dup} alongside appWidth. The panel states its width ONCE; the SDK sizes the frame from appWidth. Remove the frame ${dup} (docs/design/05)`);
+          report("error", file, `panel frame declares style.${dup} alongside appWidth. The panel states its width ONCE; the SDK sizes the frame from appWidth. Remove the frame ${dup} (docs.unoverse.ai/design/apps)`);
     }
   }
 
@@ -161,7 +161,7 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
   if (node.brief !== undefined) {
     const b = node.brief;
     if (typeof b !== "string" && (typeof b !== "object" || b === null || Array.isArray(b)))
-      report("error", file, `"brief" must be a string (the description) or { description, maxLength | minItems/maxItems } (docs/design/03)`);
+      report("error", file, `"brief" must be a string (the description) or { description, maxLength | minItems/maxItems } (docs.unoverse.ai/design/components)`);
     else if (typeof b === "object") {
       // description/maxLength/minItems/maxItems COMPILE into the tool inputSchema. `hydrate` is a
       // NON-schema brief annotation (a hydration hook naming what to hydrate) — a valid brief key
@@ -172,24 +172,24 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
       const BRIEF_KEYS = new Set(["description", "maxLength", "minItems", "maxItems", "hydrate", "optional"]);
       for (const k of Object.keys(b))
         if (!BRIEF_KEYS.has(k))
-          report("error", file, `brief.${k} is not part of the brief contract. Only description / maxLength / minItems / maxItems / optional (schema) or hydrate (hydration hook) are allowed (docs/design/03)`);
+          report("error", file, `brief.${k} is not part of the brief contract. Only description / maxLength / minItems / maxItems / optional (schema) or hydrate (hydration hook) are allowed (docs.unoverse.ai/design/components)`);
       if (b.description !== undefined && typeof b.description !== "string")
-        report("error", file, `brief.description must be a string. It IS the schema field's description (docs/design/03)`);
+        report("error", file, `brief.description must be a string. It IS the schema field's description (docs.unoverse.ai/design/components)`);
       if (b.optional !== undefined && typeof b.optional !== "boolean")
-        report("error", file, `brief.optional must be a boolean (docs/design/03)`);
+        report("error", file, `brief.optional must be a boolean (docs.unoverse.ai/design/components)`);
       if (b.hydrate !== undefined && typeof b.hydrate !== "string")
-        report("error", file, `brief.hydrate must be a string (names the field/source to hydrate) (docs/design/03)`);
+        report("error", file, `brief.hydrate must be a string (names the field/source to hydrate) (docs.unoverse.ai/design/components)`);
       for (const nk of ["maxLength", "minItems", "maxItems"])
         if (b[nk] !== undefined && (typeof b[nk] !== "number" || b[nk] < 0 || !Number.isInteger(b[nk])))
-          report("error", file, `brief.${nk} must be a non-negative integer. It compiles to the native JSON Schema keyword (docs/design/03)`);
+          report("error", file, `brief.${nk} must be a non-negative integer. It compiles to the native JSON Schema keyword (docs.unoverse.ai/design/components)`);
       if (typeof b.minItems === "number" && typeof b.maxItems === "number" && b.minItems > b.maxItems)
-        report("error", file, `brief.minItems (${b.minItems}) > maxItems (${b.maxItems}). No composition can satisfy this schema (docs/design/03)`);
+        report("error", file, `brief.minItems (${b.minItems}) > maxItems (${b.maxItems}). No composition can satisfy this schema (docs.unoverse.ai/design/components)`);
       const bound = node.bind && (node.bind.value || node.bind.src);
       const isEach = t === "Each" && node.bind && node.bind.items;
       if (b.maxLength !== undefined && !bound)
-        report("warn", file, `brief.maxLength on a node with no bind. A length cap only compiles when the brief sits next to the bound field it governs (docs/design/03)`);
+        report("warn", file, `brief.maxLength on a node with no bind. A length cap only compiles when the brief sits next to the bound field it governs (docs.unoverse.ai/design/components)`);
       if ((b.minItems !== undefined || b.maxItems !== undefined) && !isEach)
-        report("warn", file, `brief.minItems/maxItems on a non-Each node. Item counts only compile on the Each that binds the array (docs/design/03)`);
+        report("warn", file, `brief.minItems/maxItems on a non-Each node. Item counts only compile on the Each that binds the array (docs.unoverse.ai/design/components)`);
     }
   }
 
@@ -225,12 +225,12 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
       widthCap = widthCap == null ? Number(mw) : Math.min(widthCap, Number(mw));
     const hb = node.style.hideBelow;
     if (typeof hb === "string" && /^\d+$/.test(hb) && widthCap != null && Number(hb) >= widthCap)
-      report("warn", file, `hideBelow "${hb}" ≥ an ancestor maxWidth "${widthCap}". The query can only be satisfied by the surrounding surface, so visibility depends on the host, not the card; lower the threshold below the card's own max width (docs/design/06)`);
+      report("warn", file, `hideBelow "${hb}" ≥ an ancestor maxWidth "${widthCap}". The query can only be satisfied by the surrounding surface, so visibility depends on the host, not the card; lower the threshold below the card's own max width (docs.unoverse.ai/design/styles-and-tokens)`);
     const checkKeys = (obj, where) => {
       for (const k of Object.keys(obj)) {
         if (k === "when") continue; // validated below
         if (!STYLE_KEYS.has(k))
-          report("error", file, `${where}: unknown style key "${k}". The style vocabulary is closed (the cross-platform contract). Typo, or a web-ism that won't port (docs/design/06)`);
+          report("error", file, `${where}: unknown style key "${k}". The style vocabulary is closed (the cross-platform contract). Typo, or a web-ism that won't port (docs.unoverse.ai/design/styles-and-tokens)`);
         else if ((k === "hover" || k === "active") && obj[k] && typeof obj[k] === "object")
           checkKeys(obj[k], `${where}.${k}`);
         else if (DIMENSION_KEYS.has(k)) checkDimension(file, where, k, obj[k]);
@@ -244,15 +244,15 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     if (node.style.when !== undefined) {
       const w = node.style.when;
       if (!Array.isArray(w))
-        report("error", file, `${t}.style.when must be an array of { field, eq|ne|in, apply } entries (docs/design/04)`);
+        report("error", file, `${t}.style.when must be an array of { field, eq|ne|in, apply } entries (docs.unoverse.ai/design/state)`);
       else
         for (const e of w) {
           if (!e || typeof e !== "object" || typeof e.field !== "string" || !e.apply)
-            report("error", file, `${t}.style.when entry needs "field" + "apply" (docs/design/04)`);
+            report("error", file, `${t}.style.when entry needs "field" + "apply" (docs.unoverse.ai/design/state)`);
           else {
             const extra = Object.keys(e).filter((k) => !CONDITION_KEYS.has(k) && k !== "apply");
             if (extra.length)
-              report("error", file, `${t}.style.when: illegal key(s) ${extra.join(", ")}. Conditions are eq/ne/in/truthy only (docs/design/04)`);
+              report("error", file, `${t}.style.when: illegal key(s) ${extra.join(", ")}. Conditions are eq/ne/in/truthy only (docs.unoverse.ai/design/state)`);
             if (typeof e.apply === "object") checkKeys(e.apply, `${t}.style.when.apply`);
           }
         }