unoverse 0.1.195 → 0.1.196

package/README.md

@@ -31,7 +31,7 @@ Creating a universe registers the `canvas` MCP (`.mcp.json`): open the folder in
 Claude Code and describe the workflow you want, built live on your Canvas. The
 authoring skills for components, apps, themes, and custom nodes come with Studio
 projects (`unoverse studio`). `unoverse update` keeps the CLI, a universe's images,
-and any installed skills current; to add the skills to your own agent by hand:
-`npx skills add unoverse-platform/skills`.
+and the installed skills current. The skills are pages of the documentation, under
+https://docs.unoverse.ai/skills, and the CLI installs them from there.
 
 Documentation: https://docs.unoverse.ai

package/bin/unoverse.mjs

@@ -96,6 +96,7 @@ const HELP = [
   "",
   `  ${bold("After that")}`,
   row("studio", "Design components, nodes and agent skills"),
+  row("lint", "Check your components, nodes and skills, the same way deploy does"),
   row("deploy", "Ship it"),
   `      ${dim("deploy studio         your components, nodes and skills → your universe")}`,
   `      ${dim("deploy aws            your universe → AWS")}`,
@@ -106,9 +107,14 @@ const HELP = [
 ].join("\n");
 
 switch (cmd) {
-  case "create":
+  case "create": {
     await create(args[0]);
+    // FIRST CONTACT INSTALLS THE SKILLS. They used to arrive only on `unoverse update`,
+    // so a developer's first `claude` in a fresh workspace knew nothing about unoverse.
+    const { installSkills } = await import("../lib/skills.mjs");
+    await installSkills();
     break;
+  }
 
   case "update": {
     // ONE update: the CLI from npm, then everything the CLI is responsible for keeping
@@ -151,8 +157,8 @@ switch (cmd) {
 
   case "_postupdate": {
     // Runs AS the new version, in the developer's cwd. A universe refreshes its
-    // platform images; the authoring skills install to ~/.claude/skills from the public
-    // mirror, so `unoverse update` is the one command that brings everything current.
+    // platform images; the authoring skills install to ~/.claude/skills from the docs
+    // site, so `unoverse update` is the one command that brings everything current.
     //
     // THE SKILLS ARE NOT CWD-SCOPED. This used to refresh `<cwd>/.claude/skills` and only
     // when that folder already existed, which meant it fired on whichever folder update
@@ -163,7 +169,7 @@ switch (cmd) {
       operator(UNIVERSE, ["refresh-images"]);
     }
     const { installSkills } = await import("../lib/skills.mjs");
-    installSkills();
+    await installSkills();
     process.exit(0);
   }
 
@@ -191,6 +197,17 @@ switch (cmd) {
     // quietly keeps talking to last week's build. If the listener IS a studio, it is
     // ours to replace: kill it and wait for the port. Anything else on the port is
     // NOT ours: name it and stop, never kill a stranger's process.
+    // A machine that has never installed the skills gets them here too, since studio is
+    // the other first-contact command. Present means theirs to keep; update refreshes.
+    {
+      const { existsSync: has } = await import("node:fs");
+      const { join: j } = await import("node:path");
+      const { homedir } = await import("node:os");
+      if (!has(j(homedir(), ".claude", "skills", "unoverse-create"))) {
+        const { installSkills } = await import("../lib/skills.mjs");
+        await installSkills();
+      }
+    }
     const STUDIO_PORT = 4108;
     const lsof = spawnSync("lsof", ["-nP", `-iTCP:${STUDIO_PORT}`, "-sTCP:LISTEN", "-Fpc"], { encoding: "utf8" });
     const holder = lsof.status === 0 ? (lsof.stdout.match(/^p(\d+)$/m) || [])[1] : undefined;
@@ -226,6 +243,15 @@ switch (cmd) {
     process.exit(r.status ?? 0);
   }
 
+  case "lint": {
+    // THE DEPLOY GATE, on its own. `deploy studio` runs exactly this before it sends, so a
+    // developer can ask the question without the answer costing them a deploy.
+    const { lint } = await import("../lib/lint.mjs");
+    const { importBase } = await import("../lib/publish.mjs");
+    await lint(args, importBase);
+    break;
+  }
+
   case "login": {
     // Standalone sign-in. publish calls the same flow lazily, so this exists for
     // "set up my machine" moments and for re-authenticating after a permissions change.

package/lib/lint.mjs

@@ -0,0 +1,68 @@
+/**
+ * unoverse lint — check a workspace before you deploy it.
+ *
+ * THE SAME GATE `deploy studio` RUNS, and nothing else: one function in base
+ * (items/publish lintForPublish) lints the project's design/ and the workspace's nodes/,
+ * and this file only prints what it found. A developer who runs this and sees a tick will
+ * deploy without a surprise, because deploy asks the same function the same question.
+ *
+ * It exists because the gate used to be reachable only by deploying (2026-09-05): the
+ * first place a developer met a lint error was halfway through shipping.
+ */
+import { findWorkspace, designHome } from "./workspace.mjs";
+
+const c = { dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", bold: "\x1b[1m", off: "\x1b[0m" };
+
+/**
+ * Lint one project and print the findings. Returns the findings so `deploy studio` can
+ * decide what to do with them; exits nobody.
+ */
+export async function lintProject({ lintForPublish, designRoot, project }) {
+  process.stdout.write(`  ${c.dim}checking…${c.off}`);
+  const { problems, errors } = await lintForPublish(designRoot, project);
+  process.stdout.write("\r                    \r");
+  if (errors.length) {
+    console.error(`  ${c.red}✗ ${errors.length} error(s) in ${project}.${c.off}\n`);
+    for (const p of errors.slice(0, 10)) console.error(`    ${p.file}${p.line ? ":" + p.line : ""}  ${p.msg}`);
+    if (errors.length > 10) console.error(`    ${c.dim}…and ${errors.length - 10} more${c.off}`);
+    console.error("");
+  } else {
+    const warnings = problems.filter((p) => p.level === "warn").length;
+    console.log(`  ${c.green}✓${c.off} checks passed${warnings ? ` ${c.dim}(${warnings} warning(s))${c.off}` : ""}`);
+  }
+  return { problems, errors };
+}
+
+/** `unoverse lint [project]`, from anywhere inside a workspace. Exit 1 on any error. */
+export async function lint(args, importBase) {
+  const positional = args.find((a) => !a.startsWith("--"));
+  const ws = findWorkspace();
+  if (ws?.kind !== "assets") {
+    console.error(`\n  ${c.red}✗${c.off} no design/ folder here or above. Run this inside your workspace.\n`);
+    process.exit(1);
+  }
+  const designRoot = designHome(ws.root);
+  const { listProjects } = await importBase("items/collect.js");
+  const { lintForPublish } = await importBase("items/publish.js");
+
+  const projects = listProjects(designRoot);
+  if (!projects.length) {
+    console.error(`\n  ${c.red}✗${c.off} ${designRoot} holds no projects\n`);
+    process.exit(1);
+  }
+  let project = positional;
+  if (!project) {
+    if (projects.length > 1) {
+      console.error(`\n  several projects here. Say which:\n\n    unoverse lint <project>\n\n  Found: ${projects.join(", ")}\n`);
+      process.exit(1);
+    }
+    project = projects[0];
+  } else if (!projects.includes(project)) {
+    console.error(`\n  ${c.red}✗${c.off} no project "${project}" in ${designRoot}. Found: ${projects.join(", ")}\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n  ${c.bold}lint ${project}${c.off}\n`);
+  const { errors } = await lintProject({ lintForPublish, designRoot, project });
+  process.exit(errors.length ? 1 : 0);
+}

package/lib/publish.mjs

@@ -22,7 +22,7 @@ const here = dirname(fileURLToPath(import.meta.url));
 const IN_REPO_BASE = resolve(here, "../../base/dist");
 const VENDORED_BASE = resolve(here, "../vendor/base");
 
-async function importBase(subpath) {
+export async function importBase(subpath) {
   const root = existsSync(IN_REPO_BASE) ? IN_REPO_BASE : VENDORED_BASE;
   const file = join(root, subpath);
   if (!existsSync(file)) {
@@ -114,18 +114,12 @@ export async function publish(args) {
 
   // ── 1. lint. Nothing is sent if this fails ──────────────────────────────────
   console.log(`\n  ${c.bold}deploy ${project}${c.off} ${c.dim}→ ${universe}${c.off}\n`);
-  process.stdout.write(`  ${c.dim}checking…${c.off}`);
-  const { problems, errors } = await lintForPublish(designRoot, project);
-  process.stdout.write("\r                    \r");
+  const { lintProject } = await import("./lint.mjs");
+  const { errors } = await lintProject({ lintForPublish, designRoot, project });
   if (errors.length) {
-    console.error(`  ${c.red}✗ ${errors.length} error(s) in ${project}. Nothing was sent.${c.off}\n`);
-    for (const p of errors.slice(0, 10)) console.error(`    ${p.file}${p.line ? ":" + p.line : ""}  ${p.msg}`);
-    if (errors.length > 10) console.error(`    ${c.dim}…and ${errors.length - 10} more${c.off}`);
-    console.error("");
+    console.error(`  ${c.red}Nothing was sent.${c.off}\n`);
     process.exit(1);
   }
-  const warnings = problems.filter((p) => p.level === "warn").length;
-  console.log(`  ${c.green}✓${c.off} checks passed${warnings ? ` ${c.dim}(${warnings} warning(s))${c.off}` : ""}`);
 
   // ── 2. the credential, only now that there is something worth sending ───────
   const items = collectProject(designRoot, project);
@@ -147,9 +141,10 @@ export async function publish(args) {
 
   console.log("");
   const label = (i) => `${i.kind}/${i.name}`;
-  const pending = (i) => (i.kind === "node" ? ` ${c.yellow}(lands PENDING review)${c.off}` : "");
-  for (const i of plan.create) console.log(`  ${c.green}+${c.off} ${label(i)} ${c.dim}(new)${c.off}${pending(i)}`);
-  for (const i of plan.update) console.log(`  ${c.yellow}~${c.off} ${label(i)} ${c.dim}(changed)${c.off}${pending(i)}`);
+  // No "(lands PENDING review)" on a node (removed 2026-09-05): the review flow in
+  // DECLARATIVE_NODES.md §9.5 is not built, and the route registers a node row at once.
+  for (const i of plan.create) console.log(`  ${c.green}+${c.off} ${label(i)} ${c.dim}(new)${c.off}`);
+  for (const i of plan.update) console.log(`  ${c.yellow}~${c.off} ${label(i)} ${c.dim}(changed)${c.off}`);
   if (plan.unchanged.length) console.log(`  ${c.dim}= ${plan.unchanged.length} unchanged${c.off}`);
   for (const r of plan.refused) console.log(`  ${c.red}✗ ${label(r)}${c.off} ${c.dim}${r.why}${c.off}`);
   // Deploy is a SYNC: what left the workspace leaves the universe, said before it happens.

package/lib/skills.mjs

@@ -1,57 +1,80 @@
-// Install the Claude Code authoring skills for this developer.
+// Install the Claude Code authoring skills for this developer, FROM THE DOCS SITE.
 //
-// The public mirror github.com/unoverse-platform/skills is the one place installed
-// skills come from (publish syncs it from the platform repo's .claude/skills).
+// The skills are pages of the documentation (packages/docs/skills/<skill>/...), published
+// with every other page and listed in the site's llms.txt (owner ruling 2026-09-05: the
+// docs site is the one public origin, and it already serves every page as raw markdown).
+// The installer reads llms.txt, takes every page under /skills/, and writes each one to
+// disk. There is no GitHub mirror and no tarball any more.
 //
 // PER DEVELOPER, NOT PER PROJECT (2026-08-21). These install to ~/.claude/skills, so
 // Claude Code picks them up in every folder the developer opens and nothing lands
-// inside a workspace where it could be committed. They used to be copied into each
-// Studio workspace's own .claude/skills by Studio's scaffold, out of a snapshot
-// vendored in the Studio npm package: that reproduced the platform repo's .claude
-// folder on every remote developer's disk, pinned to whichever Studio version they
-// installed. Studio no longer writes them (packages/studio/local/scaffold.mjs) and
-// the mirror is the only channel.
+// inside a workspace where it could be committed.
 //
-// INSTALLS, NOT JUST REFRESHES. This used to return early when the folder was absent,
-// because seeding was Studio's job. Nothing seeds them now, so an absent folder is the
-// FIRST install and creating it is the whole point.
-//
-// Runs on `unoverse update` (_postupdate), which is the one command that brings a
-// developer's tooling current.
-import { mkdtempSync, existsSync, mkdirSync, readdirSync, rmSync, cpSync } from "node:fs";
-import { join } from "node:path";
+// Runs on `unoverse create` and on a first `unoverse studio` (first contact), and on
+// `unoverse update` (_postupdate), which is the one command that brings a developer's
+// tooling current.
+import { existsSync, mkdirSync, rmSync, writeFileSync, mkdtempSync, cpSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
 import { tmpdir, homedir } from "node:os";
-import { spawnSync } from "node:child_process";
 
-const TARBALL = "https://codeload.github.com/unoverse-platform/skills/tar.gz/refs/heads/main";
+const DOCS = "https://docs.unoverse.ai";
+
+/**
+ * The skill files a site's llms.txt names: `{ skill, rel, url }` per page under /skills/,
+ * `rel` being the path inside the skill folder. A skill's front page is SKILL.md on disk
+ * whatever case the site serves it in, because Claude Code looks for exactly that name.
+ * Pure, so it can be checked without a network.
+ */
+export function skillFilesFromLlms(text, origin = DOCS) {
+  const out = [];
+  const re = new RegExp(`\\((${origin.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}/skills/([^/\\s)]+)/([^\\s)]+\\.md))\\)`, "g");
+  for (const m of text.matchAll(re)) {
+    const [, url, skill, path] = m;
+    const rel = basename(path).toLowerCase() === "skill.md" ? join(dirname(path), "SKILL.md") : path;
+    out.push({ skill, rel, url });
+  }
+  return out;
+}
 
-export function installSkills() {
+export async function installSkills() {
   const target = join(homedir(), ".claude", "skills");
+  let files;
+  try {
+    const res = await fetch(`${DOCS}/llms.txt`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    files = skillFilesFromLlms(await res.text());
+  } catch {
+    console.log(`  Skills install skipped (${DOCS} unreachable). They install on the next update.`);
+    return;
+  }
+  const skills = [...new Set(files.map((f) => f.skill))];
+  if (!skills.length) {
+    console.log(`  Skills install skipped: ${DOCS}/llms.txt lists no skills yet.`);
+    return;
+  }
+  // Fetched whole into a scratch folder first, so a download that dies halfway leaves the
+  // installed copy untouched rather than half-replaced.
   const tmp = mkdtempSync(join(tmpdir(), "unoverse-skills-"));
   try {
-    const dl = spawnSync("bash", ["-c", `curl -fsSL "${TARBALL}" | tar -xz -C "${tmp}" --strip-components=1`], {
-      stdio: "pipe",
-    });
-    if (dl.status !== 0) {
-      console.log("  Skills install skipped (github.com unreachable). They install on the next update.");
-      return;
+    for (const f of files) {
+      const res = await fetch(f.url);
+      if (!res.ok) throw new Error(`${f.url}: HTTP ${res.status}`);
+      const p = join(tmp, f.skill, f.rel);
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, await res.text());
     }
-    // A skill is a directory holding a SKILL.md. The mirror's README and dotfiles never
-    // install.
-    const names = readdirSync(tmp, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && existsSync(join(tmp, e.name, "SKILL.md")))
-      .map((e) => e.name);
-    if (!names.length) return;
     mkdirSync(target, { recursive: true });
-    // REPLACED WHOLE, ours only. Each skill folder the mirror carries is removed and
+    // REPLACED WHOLE, ours only. Each skill folder the site carries is removed and
     // re-copied, so a deleted file upstream really goes. Anything else in the
     // developer's ~/.claude/skills is THEIRS and is never touched: this folder is
     // shared with every skill they have installed from anywhere else.
-    for (const name of names) {
+    for (const name of skills) {
       rmSync(join(target, name), { recursive: true, force: true });
       cpSync(join(tmp, name), join(target, name), { recursive: true });
     }
-    console.log(`  ✓ authoring skills installed to ~/.claude/skills (${names.join(", ")})`);
+    console.log(`  ✓ authoring skills installed to ~/.claude/skills (${skills.join(", ")})`);
+  } catch (e) {
+    console.log(`  Skills install skipped (${e.message}). They install on the next update.`);
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }

package/operator/lib/db-verify.sh

@@ -133,7 +133,13 @@ cmd_db_verify() {
       goals: [
         "goal_id", "user_id", "workflow_id", "status", "description",
         "acceptance_criteria", "budget", "goal_state", "created_workflow_ids",
-        "created_at", "updated_at", "completed_at"
+        "created_at", "updated_at", "completed_at", "directive", "bar_locked_at"
+      ],
+      goal_attempts: [
+        "id", "goal_id", "attempt", "passed", "results", "deliverables", "judged_at"
+      ],
+      goal_scratch: [
+        "goal_id", "agent_id", "agent_name", "state", "updated_at"
       ],
       knowledge_docs: [
         "id", "workflow_id", "title", "doc_type", "sections", "version",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unoverse",
-  "version": "0.1.195",
+  "version": "0.1.196",
   "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",
@@ -18,6 +18,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "yaml": "^2.8.1"
   },
   "homepage": "https://github.com/unoverse-platform",

package/vendor/base/items/collect.js

@@ -20,6 +20,8 @@
 import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
 import { join, relative, basename } from "node:path";
 import { fingerprintOf } from "./fingerprint.js";
+import { parse as parseYaml } from "yaml";
+import { readDiskPackages } from "../manifests/source.js";
 import { designSystemVersion } from "./baseVersion.js";
 /** Folders under rx/ that are never a developer's own project. */
 const NOT_A_PROJECT = new Set(["marketplace", "_schema", "orgs"]);
@@ -189,6 +191,49 @@ export function collectProject(designRoot, project) {
         };
         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.
+    //
+    // 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"))) {
+        for (const pkg of collectNodePackages(nodesHome)) {
+            for (const raw of pkg.nodes) {
+                const type = nodeType(raw.files["node.yaml"]);
+                if (!type)
+                    continue; // lint has already refused it; nothing to name a row by
+                add("node", type, {
+                    package: { name: pkg.name, packageFile: pkg.packageFile ?? null, credentials: pkg.credentials, shared: pkg.shared },
+                    dir: raw.dir,
+                    files: raw.files,
+                });
+            }
+        }
+    }
     return items;
 }
+/** The workspace's node packages, read the way the platform reads its own. */
+function collectNodePackages(nodesHome) {
+    return readDiskPackages(nodesHome).filter((pkg) => pkg.name !== "marketplace");
+}
+/** `type:` off a node.yaml: the one scalar the row is named by. Unparseable means none. */
+function nodeType(nodeYaml) {
+    try {
+        const doc = parseYaml(nodeYaml ?? "");
+        return typeof doc?.type === "string" ? doc.type : "";
+    }
+    catch {
+        return "";
+    }
+}
 //# sourceMappingURL=collect.js.map

package/vendor/base/items/publish.js

@@ -12,6 +12,8 @@
  *
  * See docs/architecture/DECLARATIVE_NODES.md §9.
  */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { collectProject } from "./collect.js";
 /**
  * Lint a project, returning findings. Errors mean nothing is sent.
@@ -24,6 +26,18 @@ import { collectProject } from "./collect.js";
 export async function lintForPublish(designRoot, project) {
     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.
+     */
+    const nodesHome = join(designRoot, "..", "nodes");
+    if (existsSync(nodesHome)) {
+        const { lintNodes } = await import("../lint/nodes/index.mjs");
+        result.problems.push(...lintNodes(nodesHome).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/lint/context.mjs

@@ -0,0 +1,56 @@
+/**
+ * The state one lint run accumulates, and the only thing every rule module shares.
+ *
+ * It is MUTABLE and RESET per run, deliberately. The linter began as a CLI that ran once
+ * and exited, so module-level arrays were harmless; Studio and the publish route lint over
+ * and over in one process, and findings from the previous run would silently accumulate
+ * into the next. `reset()` is what makes a second call return the same answer as the first.
+ */
+import { relative } from "node:path";
+
+/** Every finding, in discovery order. Sorted for presentation by the caller. */
+export const problems = [];
+
+/** Fragment path -> the set of nodes referencing it. Powers the shared/ pruning rules. */
+export const refCounts = new Map();
+
+/** Node -> the executor kind derived for it, shown as a summary rather than a finding. */
+export const derivedKinds = new Map();
+
+/** Credential name -> where it was declared, for cross-package collision rules. */
+export const allCredentials = new Map();
+
+/** Where this run is reading. Set by lintNodes(), read by rel() and the loaders. */
+export const state = { nodesHome: "", schemaDir: "", schemas: {} };
+
+export function reset(nodesHome, schemaDir) {
+  problems.length = 0;
+  seen.clear();
+  refCounts.clear();
+  derivedKinds.clear();
+  allCredentials.clear();
+  state.nodesHome = nodesHome;
+  state.schemaDir = schemaDir;
+  state.schemas = {};
+}
+
+/**
+ * One finding. `error` fails a build; `warn` and `hint` inform.
+ *
+ * DEDUPED. The design linter walks a definition and its expansions, so the same rule can fire
+ * on the same line twice; a caller seeing it twice would think there were two problems.
+ * `line` is optional: the design linter knows where in the file, the node linter reports per file.
+ */
+const seen = new Set();
+export const report = (level, file, msg, line) => {
+  const key = `${level}|${file}|${line ?? ""}|${msg}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  problems.push(line === undefined ? { level, file, msg } : { level, file, msg, line });
+};
+
+/** Shortest readable form: a walk out of the tree is worse than the absolute path. */
+export const rel = (p) => {
+  const r = relative(process.cwd(), p);
+  return r.startsWith("..") ? p : r;
+};

package/vendor/base/lint/nodes/_schema/_defs.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unoverse/nodes/_defs.schema.json",
+  "title": "Shared node definitions",
+  "description": "Fragments $ref'd by the sibling node schemas. Not authored directly. See docs/architecture/DECLARATIVE_NODES.md.",
+  "definitions": {
+    "nodeType": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9]*$",
+      "description": "The node's stable identity, PascalCase. This is what a saved workflow stores and what the engine resolves. Renaming it orphans every graph that uses it. NOT the same as the `type` field in package.json's gravity.nodes[], which meant PromiseNode or CallbackNode."
+    },
+    "portType": {
+      "enum": [
+        "string",
+        "number",
+        "boolean",
+        "object",
+        "array",
+        "signal"
+      ],
+      "description": "The shape carried on a wire. Mirrors NodeInputType in @unoverse-platform/plugin-base."
+    },
+    "signalType": {
+      "enum": [
+        "EXECUTE",
+        "CONTINUE",
+        "SPAWN",
+        "RESET"
+      ],
+      "description": "Which signal fires this connector. EXECUTE is the default trigger; CONTINUE drives the next iteration of a streaming or looping node; SPAWN initialises an actor; RESET clears it. A node becomes ready when ANY ONE connector has all its required sources populated (signal-routing.md)."
+    },
+    "port": {
+      "type": "object",
+      "required": [
+        "name",
+        "type"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][A-Za-z0-9_]*$",
+          "description": "camelCase by convention. Upstream nodes address it as signal.<sourceId>.<outputHandle>.\n\nsnake_case is ALLOWED because a migrated node must keep the connector names its code version had: a saved workflow references them by name, so renaming `linkedin_url` to `linkedinUrl` would silently stop resolving and the field would read as empty with no error anywhere. Fidelity to the node being replaced beats house style. Prefer camelCase for anything new."
+        },
+        "type": {
+          "$ref": "#/definitions/portType"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Inputs only. A connector is satisfied when all its REQUIRED sources are populated."
+        },
+        "signal": {
+          "$ref": "#/definitions/signalType",
+          "description": "Inputs only. Omit for the EXECUTE default."
+        },
+        "description": {
+          "type": "string",
+          "description": "What travels on this port. Read by developers wiring the graph."
+        }
+      },
+      "additionalProperties": false
+    },
+    "nodeCategory": {
+      "enum": [
+        "AI",
+        "Voice",
+        "Go To Market",
+        "Search",
+        "Web Scraping",
+        "Media & Design",
+        "Documents",
+        "Knowledge & Vectors",
+        "Storage & Data",
+        "Communication",
+        "Flow",
+        "Output"
+      ],
+      "description": "Descriptive taxonomy matching the node's JOB. This is the NODE vocabulary and it is deliberately different from the PACKAGE vocabulary in package.schema.json (ai, storage, ingest, ...). See docs-starter/nodes/CLAUDE.md."
+    },
+    "whenToUse": {
+      "type": "string",
+      "minLength": 40,
+      "description": "AI selection guidance, embedded and semantically ranked by getNodeCatalog, so it decides whether this node SURFACES AT ALL to the workflow-building agent. Rules (node-discoverability.md): 1-2 sentences; OUTCOME first, mechanism last; disqualify yourself by PROPERTY and never name a rival node; put wiring facts last. A node with weak meta is invisible no matter how well it works."
+    },
+    "expression": {
+      "type": "string",
+      "pattern": "^return ",
+      "description": "A sandboxed `return ...` data-shaping expression, evaluated by the platform's existing SafeExpression evaluator (engine/src/template/SafeExpression.ts). Same syntax developers already use in object template config fields, so this format introduces NO second expression language.\n\nSecurity is by ABSENCE: an acorn AST allowlist that never implements process, require, fetch, eval, Function, new, assignment, or constructor/__proto__, so there is nothing to escape to. Allowed: member access, indexing, object and array literals, spread, template strings, operators, ternaries, and safe array/string/JSON/Math methods including arrow callbacks. Anything else throws and is logged."
+    },
+    "templateOrExpression": {
+      "type": "string",
+      "description": "EITHER a Handlebars template or a `return ...` expression, decided by the string itself: anything starting with `return ` is evaluated by SafeExpression, everything else is rendered as a template.\n\nONE RULE FOR EVERY STRING IN A CALL. url, headers, query and the auth fields all take this, exactly as the body already did. The gap used to be arbitrary and it cost a real node: a URL is often assembled from an earlier call's reply, and a vendor's shape is not always uniform (HubSpot's v3 associations return the related id as `toObjectId` on some object pairs and `id` on others). Handlebars has no `??`, so a manifest could not express the fallback that the retired TypeScript wrote as `toObjectId ?? id`, and the only escape was choosing an API version whose shape happened to be predictable. A node should not contort itself around a limitation of the executor.\n\nPrefer the template. Reach for the expression when a template genuinely cannot say it, because a template is what a reader can scan.\n\nNOTE for `url`: the linter checks allowedHosts hosts STATICALLY by blanking `{{ }}` and parsing what is left, and it cannot do that with an expression, so an expression URL is reported as not statically verifiable. It is still enforced at run time: `sendRequest` calls `assertAllowedHost` on the RESOLVED url, and every call in the runtime goes through it.",
+      "examples": [
+        "https://api.example.com/v1/things/{{ calls.search.results.0.id }}",
+        "return 'https://api.example.com/v1/things/' + (calls.search.results[0].toObjectId || calls.search.results[0].id)"
+      ]
+    },
+    "template": {
+      "type": "string",
+      "description": "A Handlebars template resolved against the node's input context before the request is sent.\n\nFive roots:\n  signal.<sourceId>.<outputHandle>.<field>   upstream node output, e.g. {{signal.inputtrigger1.output.message}}\n  config.<field>                              this node's own settings\n  credentials.<name>.<field>                  this node's resolved credential\n  services.<connector>                        RUNTIME service wiring, e.g. {{#unless services.mcpService.tools}}\n  prompt.<blockName>                          a PROMPT BLOCK from the library (alias: blocks.<name>)\n\nThe services root exists because some request shaping depends on what is WIRED rather than configured, a fact only the executor knows at run time.\n\nThe prompt root is why a manifest must NEVER hardcode instruction text. Blocks live in prompts/blocks/**/*.md, are authored and toggled in Studio, and are camelCased from the filename (markdown-guidelines.md becomes {{prompt.markdownGuidelines}}). A copy of a block's words baked into a node is a fork that silently stops tracking the block. Text belongs in the library; the node references it. This is the prompt-side twin of the SDK owning no styles.\n\nEvery root works in ANY template field, including a user's own systemPrompt: that is what lets an author compose blocks and upstream values into a prompt without the node knowing anything about it.\n\nThere is NO {{input.*}} root: a wrong path resolves to EMPTY silently. Array elements and object keys are dot segments, never brackets: records.0.Name, not records[0].Name."
+    }
+  }
+}