@unoverse-platform/studio 0.1.96 → 0.1.98

package/bin/studio.mjs

@@ -3,7 +3,7 @@
  * unoverse-studio — the authoring tool, run from a developer's own project.
  *
  * Studio is a TOOL, not a starter kit. A developer's repository holds only their assets
- * (rx/, prompts/, nodes/); this is installed alongside and reads them. That is why there
+ * (design/); this is installed alongside and reads them. That is why there
  * is no second repository to keep in step, and why their project contains no Docker, no
  * ansible and no platform source.
  *
@@ -14,7 +14,7 @@
  * to avoid. So the tool starts the same dev server `npm run dev` does.
  *
  * No database, no Redis, no engine, no Docker, and no account: those belong to running a
- * universe, which is a different job. See docs/architecture/LOCAL_STUDIO.md.
+ * universe, which is a different job. See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { createServer } from "vite";
 import { dirname, resolve, join, basename } from "path";
@@ -143,7 +143,7 @@ async function scaffoldIfEmpty() {
   // publishes, so a flat rx/ could hold exactly one project and would read `components`
   // and `apps` as orgs.
   createFirstProject(home, name);
-  console.log(`\n  Created design/${name}/, prompts/ and nodes/ in ${cwd}\n`);
+  console.log(`\n  Created design/${name}/ in ${cwd}\n`);
 }
 
 await scaffoldIfEmpty();

package/local/authoring.ts

@@ -16,7 +16,7 @@
  * completion list is not a hint, it is the whole legal set, and it knows the developer's
  * real tokens in a way a JSON Schema in a text editor cannot.
  *
- * See docs/architecture/LOCAL_STUDIO.md §Authoring in Studio.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md §Authoring in Studio.
  */
 import { designHome } from "./design-home.mjs";
 import { resolve } from "path";

package/local/catalog.ts

@@ -8,7 +8,7 @@
  * the exact problem this migration exists to fix). It imports the SAME modules and sets
  * RX_PATH to the developer's folder before they load.
  *
- * See docs/architecture/LOCAL_STUDIO.md.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { hasDesignHome } from "./design-home.mjs";
 import { resolve } from "path";
@@ -24,6 +24,10 @@ type Loaders = {
   inputPropKeys: (props: unknown) => string[];
   themeOrgs: () => string[];
   listThemeNames: (org: string) => string[];
+  /** The identity documents of one org or every org: `<org>/<doc>` items with manifest and briefed props. */
+  listIdentity: (org?: string) => unknown[];
+  /** The Agents of one org or every org: `<org>/<name>` items with their meta and door. */
+  listAgents: (org?: string) => unknown[];
   resolveTheme: (name: string) => unknown;
   DEFAULT_ORG: string;
   /** A project's on-disk home. The writable set is built from these (see source.ts). */
@@ -44,7 +48,7 @@ export function findProjectRoot(from: string = process.cwd()): string {
     // A developer's project (starter kit): rx/ sits at the root.
     if (hasDesignHome(dir)) return dir;
     // This monorepo, where Studio's author works: rx/ lives under apps/unoverse. Same
-    // shape underneath (rx/ + prompts/), just nested, so return that as the root.
+    // shape underneath (design/), just nested, so return that as the root.
     if (hasDesignHome(resolve(dir, "apps/unoverse"))) return resolve(dir, "apps/unoverse");
     const parent = resolve(dir, "..");
     if (parent === dir) break;
@@ -94,6 +98,9 @@ export async function loadCatalog(
   const defs = await load(resolve(baseSrc, "definitions/definitions.ts"));
   const theme = await load(resolve(baseSrc, "definitions/theme.ts"));
   const inputs = await load(resolve(baseSrc, "definitions/inputs.ts"));
+  const homes = await load(resolve(baseSrc, "definitions/registry/homes.ts"));
+  const identity = await load(resolve(baseSrc, "definitions/registry/orgDocuments.ts"));
+  const agents = await load(resolve(baseSrc, "definitions/registry/agents.ts"));
 
   return {
     listDefinitions: defs.listDefinitions as Loaders["listDefinitions"],
@@ -104,6 +111,19 @@ export async function loadCatalog(
     inputPropKeys: inputs.inputPropKeys as Loaders["inputPropKeys"],
     themeOrgs: theme.themeOrgs as Loaders["themeOrgs"],
     listThemeNames: theme.listThemeNames as Loaders["listThemeNames"],
+    listIdentity: ((org?: string) => {
+      const orgs: string[] = org && org !== "all" ? [org] : (homes.listOrgs as () => string[])();
+      const out: unknown[] = [];
+      for (const o of orgs) {
+        const root = (homes.projectDir as (n: string) => string)(o);
+        for (const doc of identity.ORG_DOCUMENTS as readonly string[]) {
+          const read = (identity.readOrgDocument as (r: string, d: string) => { manifest: unknown; props: unknown; path: string } | null)(root, doc);
+          if (read) out.push({ name: `${o}/${doc}`, org: o, doc, manifest: read.manifest, props: read.props, path: read.path });
+        }
+      }
+      return out;
+    }) as Loaders["listIdentity"],
+    listAgents: agents.listAgents as Loaders["listAgents"],
     resolveTheme: theme.resolveTheme as Loaders["resolveTheme"],
     DEFAULT_ORG: theme.DEFAULT_ORG as string,
     projectDir: defs.projectDir as Loaders["projectDir"],

package/local/keys.ts

@@ -13,7 +13,7 @@
  * snake-cased, so `airtableCredential.personalAccessToken` reads from
  * `AIRTABLE_PERSONAL_ACCESS_TOKEN`.
  *
- * See docs/architecture/LOCAL_STUDIO.md.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { resolve } from "path";
 import { existsSync, readFileSync } from "fs";

package/local/nodes.ts

@@ -1,20 +1,21 @@
 /**
  * The LOCAL node catalog and runner.
  *
- * Scope (decided 2026-07-25): the developer's OWN nodes only, the ones in their
- * project's `nodes/` folder. Local Studio never reads the installed plugins directory,
+ * Scope (decided 2026-07-25): the developer's OWN nodes only, the ones in each of their
+ * projects' `design/<project>/nodes/` folder (org-scoped since 2026-09-08, like skills;
+ * the workspace-root `nodes/` is gone). Local Studio never reads the installed plugins directory,
  * `installed_plugins`, or the marketplace. Acquiring a node is a universe's job; this
  * is developing the nodes you are writing.
  *
  * As with the definitions (catalog.ts), this reuses the server's REAL registration
- * path rather than scraping source: each package is loaded through `loadPlugin`, which
- * calls its `setup(api)` exactly as production does. So what Studio lists is what the
- * platform would register, including config schemas and credential types.
+ * path rather than scraping source: every package goes through `loadManifests` over a
+ * disk source, exactly as the server boots. So what Studio lists is what the platform
+ * would register, including config schemas and credential types.
  *
  * The bootstrap comment is explicit that this path touches neither Redis nor the
  * workflow service, which is what makes it usable with no backend.
  *
- * See docs/architecture/LOCAL_STUDIO.md.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { resolve } from "path";
 import { existsSync } from "fs";
@@ -29,57 +30,43 @@ export interface LocalNodes {
 /**
  * Load the developer's node packages into the in-memory registry.
  *
- * `projectRoot` is the folder holding `nodes/`. Returns null when there is no nodes/
- * folder at all, so Studio can simply omit the section rather than showing an error:
+ * `nodesDirs` is every project's `design/<project>/nodes/`. Returns null when none of
+ * them exists, so Studio can simply omit the section rather than showing an error:
  * plenty of developers only author design assets.
+ *
+ * YAML manifest nodes (package.yaml + nodes/<Node>/*.yaml) are the ONLY authoring
+ * format (DECLARATIVE_NODES.md §10, nothing stays code), so this is one pass over one
+ * disk source per project: local Studio reads the developer's folders, never a
+ * database, and loadManifests registers into the same registry getAllNodes() reads.
+ * The legacy code-package loader that ran ahead of this pass read a `NODES_PATH`
+ * variable paths.ts had stopped honouring, so it loaded nothing and is gone.
  */
 export async function loadLocalNodes(
   baseSrc: string,
   load: (id: string) => Promise<Record<string, unknown>>,
-  projectRoot: string,
+  nodesDirs: string[],
 ): Promise<LocalNodes | null> {
-  const nodesDir = resolve(projectRoot, "nodes");
-  if (!existsSync(nodesDir)) return null;
-
-  // Set BEFORE the modules load: paths.ts reads process.env at module load time.
-  process.env.NODES_PATH = nodesDir;
+  const present = nodesDirs.filter((d) => existsSync(d));
+  if (!present.length) return null;
 
-  const discovery = await load(resolve(baseSrc, "plugins/discovery.ts"));
-  const loader = await load(resolve(baseSrc, "plugins/loader.ts"));
-  const platform = await load(resolve(baseSrc, "platform/index.ts"));
   const registry = await load(resolve(baseSrc, "registry.ts"));
   const executor = await load(resolve(baseSrc, "executor.ts"));
+  const manifests = await load(resolve(baseSrc, "manifests/index.ts"));
+  const msource = await load(resolve(baseSrc, "manifests/source.ts"));
 
-  const api = (platform.createNodeServiceAPI as () => unknown)();
-  const packages = (discovery.discoverNodesHome as () => string[])();
-
-  for (const name of packages) {
+  for (const dir of present) {
+    // One broken project must never stop the others loading. Same posture as the
+    // server's bootstrap, and the same reason: a bad asset cannot take the tool down.
     try {
-      await (loader.loadPlugin as (n: string, a: unknown) => Promise<string[]>)(name, api);
+      const r = await (manifests.loadManifests as (s: unknown) => Promise<{ nodes: number; errors: string[] }>)(
+        (msource.diskSource as (d: string) => unknown)(dir),
+      );
+      for (const e of r.errors) console.warn(`[studio] manifest node: ${e}`);
     } catch (err) {
-      // One broken package must never stop the others loading. Same posture as the
-      // server's bootstrap, and the same reason: a bad asset cannot take the tool down.
-      console.warn(`[studio] could not load node package ${name}: ${(err as Error).message}`);
+      console.warn(`[studio] nodes in ${dir} did not load: ${(err as Error).message}`);
     }
   }
 
-  // YAML manifest nodes (package.yaml + nodes/<Node>/*.yaml) — the DEFAULT authoring
-  // format, and what the scaffolded sample nodes are. The discovery above only finds
-  // legacy CODE packages (a package.json with an entry point), so without this pass a
-  // pure-YAML nodes/ folder — every new developer's — listed NOTHING at all. Explicit
-  // disk source: local Studio reads the developer's folder, never a database, and
-  // loadManifests registers into the same registry getAllNodes() reads.
-  try {
-    const manifests = await load(resolve(baseSrc, "manifests/index.ts"));
-    const msource = await load(resolve(baseSrc, "manifests/source.ts"));
-    const r = await (manifests.loadManifests as (s: unknown) => Promise<{ nodes: number; errors: string[] }>)(
-      (msource.diskSource as (d: string) => unknown)(nodesDir),
-    );
-    for (const e of r.errors) console.warn(`[studio] manifest node: ${e}`);
-  } catch (err) {
-    console.warn(`[studio] manifest nodes did not load: ${(err as Error).message}`);
-  }
-
   return {
     list: () => (registry.getAllNodes as () => unknown[])(),
     credentialTypes: () => (registry.getAllCredentialTypes as () => unknown[])(),

package/local/plugin.ts

@@ -8,12 +8,12 @@
  *
  * Routes mirror the server's shapes exactly, because the screens parse those shapes:
  *   GET /dev/orgs        GET /dev/themes?org=      GET /dev/components?org=
- *   GET /dev/apps?org=   GET /dev/atoms
+ *   GET /dev/apps?org=   GET /dev/atoms         GET /dev/identity?org=   GET /dev/agents?org=
  *   GET /local/theme?ref=     GET /local/definition?uri=
  *   GET /skills  /skills/:name   GET /prompt-blocks
  *   GET|POST /registry/state  (no database locally, see below)
  *
- * See docs/architecture/LOCAL_STUDIO.md.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { designHome } from "./design-home.mjs";
 import { createRequire } from "node:module";
@@ -92,7 +92,12 @@ function json(res: import("http").ServerResponse, body: unknown, status = 200):
 interface MarkdownEntry {
   /** Stable key the screens select on. Derived from the filename, like the server's. */
   id: string;
+  /** The LOOKUP name, org-qualified for an org's own skill or block. Round-trips verbatim. */
   name: string;
+  /** What a person reads. `name` carries the org, and a navigator printing it shows a path. */
+  title?: string;
+  /** The owning org. ABSENT means the universal tier, exactly as the server tags it. */
+  org?: string;
   description: string;
   category?: string;
   version?: string;
@@ -136,6 +141,7 @@ function readMarkdownLibrary(dir: string): MarkdownEntry[] {
       out.push({
         id,
         name: meta.name || id,
+        title: meta.title || meta.name || id,
         description: meta.description ?? "",
         category: meta.category,
         version: meta.version,
@@ -155,6 +161,37 @@ function readMarkdownLibrary(dir: string): MarkdownEntry[] {
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * A MARKDOWN LIBRARY HAS TWO TIERS, and this host only ever read one.
+ *
+ * A skill or a prompt block lives in one of two places, and the NAME's shape is what
+ * carries which:
+ *
+ *   UNIVERSAL  `design/marketplace/<folder>/`, named bare. Published to the marketplace.
+ *   ORG        `design/<org>/<folder>/`, named `<org>/<name>`. Private to that org.
+ *
+ * The universe server resolves both (the items loaders). This host read the universal
+ * home alone, so a developer's OWN skill was missing from local Studio while sitting
+ * correctly in their universe, and the two surfaces disagreed about the same folder.
+ *
+ * Scoping is the server's `?org=`: an org sees the universal tier plus its own and never
+ * another org's, the rule RX_ORG_MODEL.md settled for a project's assets.
+ */
+function readLibrary(projectRoot: string, folder: "skills" | "blocks", orgs: string[], org?: string): MarkdownEntry[] {
+  const out = readMarkdownLibrary(resolve(designHome(projectRoot), "marketplace", folder));
+  for (const o of orgs) {
+    if (org && org !== "all" && o !== org) continue;
+    for (const e of readMarkdownLibrary(resolve(designHome(projectRoot), o, folder))) {
+      // A SKILL's lookup name carries its org, because that is the name every reader
+      // addresses it by and two orgs may hold one bare name. A BLOCK's does not: the
+      // server tags a block with its org and leaves the name alone, and the shape here
+      // has to be the server's or the screens read two different contracts.
+      out.push(folder === "skills" ? { ...e, name: `${o}/${e.id}`, org: o } : { ...e, org: o });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 /**
  * Files this server has just written, so the watcher can tell Studio's own save apart from
  * the developer's other editor. The window only has to outlast the filesystem event, which
@@ -205,7 +242,12 @@ export function localStudioHost(): Plugin {
       // Node packages load lazily: only when the Nodes section is first opened, so a
       // developer authoring only design assets never pays for it at startup.
       let nodesOnce: Promise<LocalNodes | null> | null = null;
-      const nodes = () => (nodesOnce ??= loadLocalNodes(baseSrc, ssr, projectRoot));
+      // Every project's own nodes: design/<project>/nodes/, org-scoped like its skills.
+      const nodesDirs = async () => {
+        const c = await catalog;
+        return c.listOrgs().map((o) => resolve(c.projectDir(o), "nodes"));
+      };
+      const nodes = () => (nodesOnce ??= nodesDirs().then((dirs) => loadLocalNodes(baseSrc, ssr, dirs)));
 
       server.config.logger.info(`\n  Studio reading: ${designHome(projectRoot)}\n`);
 
@@ -220,7 +262,7 @@ export function localStudioHost(): Plugin {
        *
        * Adding the paths puts them in the same watcher, so the existing hook fires.
        */
-      for (const dir of [designHome(projectRoot), resolve(projectRoot, "prompts")]) {
+      for (const dir of [designHome(projectRoot)]) {
         const full = resolve(projectRoot, dir);
         if (existsSync(full)) server.watcher.add(full);
       }
@@ -255,7 +297,7 @@ export function localStudioHost(): Plugin {
               return json(res, {
                 projectRoot,
                 rx: designHome(projectRoot),
-                nodes: resolve(projectRoot, "nodes"),
+                nodes: await nodesDirs(),
                 envFiles: [resolve(projectRoot, "..", ".env"), resolve(projectRoot, ".env")],
               });
 
@@ -360,6 +402,14 @@ export function localStudioHost(): Plugin {
             case path === "/dev/apps":
               return json(res, { apps: c.listAppsForWorkbench(org) });
 
+            // The org's identity documents (design/<org>/identity/<doc>.yaml), one org or all.
+            case path === "/dev/identity":
+              return json(res, { items: c.listIdentity(org) });
+
+            // Agents: the one file authored for the map, design/<org>/agents/<name>.yaml.
+            case path === "/dev/agents":
+              return json(res, { items: c.listAgents(org) });
+
             case path === "/dev/atoms":
               return json(res, { atoms: c.listDefinitions("atom") });
 
@@ -433,7 +483,14 @@ export function localStudioHost(): Plugin {
               if (!p || typeof b.text !== "string") return json(res, { error: "path and text are required" }, 400);
 
               type LintModule = { lintDefinitions(designRoot: string): { problems: { level?: string; file?: string }[] } };
+              type ObjectsLintModule = { lintObjects(designRoot: string): { problems: { level?: string; file?: string }[] } };
+              type PromptsLintModule = { lintPrompts(designRoot: string): { problems: { level?: string; file?: string }[] } };
               const lintMod = (await ssr(`${baseSrc}/lint/design/index.mjs`)) as unknown as LintModule;
+              // OBJECTS AND PIPELINES TOO (objects README 9a, 2026-09-10): the same third linter
+              // the publish gate runs, so a save here meets the sentence publish would print.
+              const objectsMod = (await ssr(`${baseSrc}/lint/objects/index.mjs`)) as unknown as ObjectsLintModule;
+              // SKILLS AND PROMPT BLOCKS TOO (2026-09-18): the fourth linter, same gate.
+              const promptsMod = (await ssr(`${baseSrc}/lint/prompts/index.mjs`)) as unknown as PromptsLintModule;
 
               // Marked BEFORE the write, so the filesystem event can never beat the mark.
               recentSelfWrites.set(resolve(p), Date.now());
@@ -442,7 +499,7 @@ export function localStudioHost(): Plugin {
                 b.text as string,
                 writableRoots(projectRoot, c),
                 projectRoot,
-                (designRoot) => lintMod.lintDefinitions(designRoot),
+                (designRoot) => ({ problems: [...lintMod.lintDefinitions(designRoot).problems, ...objectsMod.lintObjects(designRoot).problems, ...promptsMod.lintPrompts(designRoot).problems] }),
               );
               return json(res, result, result.saved ? 200 : result.error === "lint errors" ? 422 : 403);
             }
@@ -466,9 +523,14 @@ export function localStudioHost(): Plugin {
                   options?: { overlay?: Record<string, string> },
                 ): { problems: { level?: string; file?: string; line?: number; msg?: string }[] };
               };
+              type ObjectsLintModule = { lintObjects(designRoot: string, options?: { overlay?: Record<string, string> }): { problems: { level?: string; file?: string; line?: number; msg?: string }[] } };
+              type PromptsLintModule = { lintPrompts(designRoot: string, options?: { overlay?: Record<string, string> }): { problems: { level?: string; file?: string; line?: number; msg?: string }[] } };
               const lintMod = (await ssr(`${baseSrc}/lint/design/index.mjs`)) as unknown as LintModule;
+              const objectsMod = (await ssr(`${baseSrc}/lint/objects/index.mjs`)) as unknown as ObjectsLintModule;
+              const promptsMod = (await ssr(`${baseSrc}/lint/prompts/index.mjs`)) as unknown as PromptsLintModule;
               const abs = resolve(p);
-              const { problems } = lintMod.lintDefinitions(designHome(projectRoot), { overlay: { [abs]: b.text as string } });
+              const overlay = { [abs]: b.text as string };
+              const problems = [...lintMod.lintDefinitions(designHome(projectRoot), { overlay }).problems, ...objectsMod.lintObjects(designHome(projectRoot), { overlay }).problems, ...promptsMod.lintPrompts(designHome(projectRoot), { overlay }).problems];
               return json(res, {
                 findings: problems.filter((f) => f.file && resolve(f.file) === abs),
                 elsewhere: problems.filter((f) => !f.file || resolve(f.file) !== abs).length,
@@ -507,17 +569,17 @@ export function localStudioHost(): Plugin {
               return json(res, selection ?? { empty: true });
 
             case path === "/skills":
-              return json(res, { skills: readMarkdownLibrary(resolve(projectRoot, "prompts/skills")) });
+              return json(res, { skills: readLibrary(projectRoot, "skills", c.listOrgs(), org) });
 
             case path.startsWith("/skills/"): {
               const name = decodeURIComponent(path.slice("/skills/".length).replace(/\/file$/, ""));
-              const found = readMarkdownLibrary(resolve(projectRoot, "prompts/skills")).find((s) => s.name === name || s.id === name);
+              const found = readLibrary(projectRoot, "skills", c.listOrgs()).find((s) => s.name === name || s.id === name);
               // SkillsView reads `d.skill`, matching the server's shape. Not the bare object.
               return found ? json(res, { skill: found }) : json(res, { error: "skill not found" }, 404);
             }
 
             case path === "/prompt-blocks":
-              return json(res, { blocks: readMarkdownLibrary(resolve(projectRoot, "prompts/blocks")) });
+              return json(res, { blocks: readLibrary(projectRoot, "blocks", c.listOrgs(), org) });
 
             // Registry toggles are a DEPLOYED concept: they persist to installed_plugins
             // and decide what a running universe exposes. Local Studio has no database and
@@ -528,11 +590,11 @@ export function localStudioHost(): Plugin {
               if (req.method === "POST") return json(res, { ok: true });
               return json(res, { entries: [] });
 
-            // ---- The developer's OWN nodes (their nodes/ folder). No marketplace. ----
+            // ---- The developer's OWN nodes (design/<project>/nodes/). No marketplace. ----
 
             case path === "/nodes": {
               const n = await nodes();
-              if (!n) return json(res, { nodes: [], credentialTypes: [], reason: "no nodes/ folder in this project" });
+              if (!n) return json(res, { nodes: [], credentialTypes: [], reason: "no design/<project>/nodes/ folder in this workspace" });
               return json(res, { nodes: n.list(), credentialTypes: n.credentialTypes() });
             }
 
@@ -597,7 +659,7 @@ export function localStudioHost(): Plugin {
      * else, which means the developer's other editor, still reloads.
      */
     handleHotUpdate({ server, file }) {
-      const watched = [designHome(projectRoot), resolve(projectRoot, "prompts")];
+      const watched = [designHome(projectRoot)];
       if (!watched.some((w) => file.startsWith(w))) return;
       const self = recentSelfWrites.get(resolve(file));
       if (self !== undefined && Date.now() - self < SELF_WRITE_WINDOW_MS) return [];

package/local/sample-identity/brand.yaml

@@ -0,0 +1,24 @@
+# The org's brand: its own words, and only those. The briefs, the limits and the shape are the
+# brand object's (design/marketplace/objects/brand/); this file carries the answers as defaults.
+unoverse: "1.0"
+type: identity
+extends: brand
+props:
+  name:
+    default: ""
+  standsFor:
+    default: ""
+  promise:
+    default: ""
+  represents:
+    default: ""
+  positioning:
+    default: ""
+  differentiators:
+    default: []
+  brands:
+    default: []
+  rules:
+    default: []
+  examples:
+    default: []

package/local/sample-identity/organisation.yaml

@@ -0,0 +1,14 @@
+# The org's organisation: its own words, and only those. The briefs, the limits and the shape are the
+# organisation object's (design/marketplace/objects/organisation/); this file carries the answers as defaults.
+unoverse: "1.0"
+type: identity
+extends: organisation
+props:
+  name:
+    default: ""
+  what:
+    default: ""
+  units:
+    default: []
+  vocabulary:
+    default: ""

package/local/sample-identity/purpose.yaml

@@ -0,0 +1,14 @@
+# The org's purpose: its own words, and only those. The briefs, the limits and the shape are the
+# purpose object's (design/marketplace/objects/purpose/); this file carries the answers as defaults.
+unoverse: "1.0"
+type: identity
+extends: purpose
+props:
+  statement:
+    default: ""
+  values:
+    default: []
+  ambition:
+    default: ""
+  goals:
+    default: []

package/local/sample-identity/story.yaml

@@ -0,0 +1,18 @@
+# The org's story: its own words, and only those. The briefs, the limits and the shape are the
+# story object's (design/marketplace/objects/story/); this file carries the answers as defaults.
+unoverse: "1.0"
+type: identity
+extends: story
+props:
+  history:
+    default: ""
+  milestones:
+    default: []
+  present:
+    default: ""
+  vision:
+    default: ""
+  people:
+    default: ""
+  meaning:
+    default: ""

package/local/scaffold.mjs

@@ -11,7 +11,7 @@
  * alike and disagree about what a starting component contains. So this file is plain ESM
  * rather than TypeScript, because the CLI runs unbuilt and cannot transpile.
  *
- * See docs/architecture/LOCAL_STUDIO.md.
+ * See docs/architecture/authoring/LOCAL_STUDIO.md.
  */
 import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, readFileSync } from "node:fs";
 import { designHome } from "./design-home.mjs";
@@ -61,7 +61,7 @@ const WELCOME = [
 ].join("\n");
 
 /**
- * Create `design/<name>/` under `home`, with its three authoring folders and one component.
+ * Create `design/<name>/` under `home`, with its authoring folders, one component and the identity.
  *
  * Refuses an existing name rather than merging into it: "create" that silently adopts a
  * folder is how a developer ends up publishing someone else's work under their own project.
@@ -77,7 +77,7 @@ export function createProject(home, name) {
   // beside components/apps/styles so a skill is org-scoped exactly like a component —
   // two orgs may each ship an `hr-education-coach` without colliding on one flat name
   // (items/collect.ts qualifies a skill's row `<org>/<name>`).
-  for (const d of ["components/welcome", "apps", "styles", "skills", "blocks"]) mkdirSync(join(root, d), { recursive: true });
+  for (const d of ["components/welcome", "apps", "styles", "skills", "blocks", "identity"]) mkdirSync(join(root, d), { recursive: true });
   writeFileSync(join(root, "components/welcome/welcome.yaml"), WELCOME);
 
   // Worked example styles (sample-styles: brand ingredients + the override rules), so
@@ -90,6 +90,15 @@ export function createProject(home, name) {
     cpSync(sampleStyles, join(root, "styles"), { recursive: true });
   }
 
+  // THE IDENTITY (sample-identity: organisation, brand, purpose, story), four instances of
+  // the marketplace's identity objects with their defaults empty, so the org's own words
+  // have a place to land from day one. Generated by base's instanceText (a guard test holds
+  // them equal to what createOrgPack writes). Same rule: copied only into an empty folder.
+  const sampleIdentity = join(dirname(fileURLToPath(import.meta.url)), "sample-identity");
+  if (existsSync(sampleIdentity) && readdirSync(join(root, "identity")).length === 0) {
+    cpSync(sampleIdentity, join(root, "identity"), { recursive: true });
+  }
+
   // A worked example APP (a generic chat: focus overlay + the chat region),
   // so apps/ is never an empty folder and the first app is a rename away. Same
   // rule as the styles: copied only into an empty folder, then the developer's.
@@ -115,7 +124,10 @@ export function createProject(home, name) {
  * makes that safe.
  */
 const SAMPLES = [
-  { id: "nodes/samples", dir: "sample-nodes/samples", to: () => "nodes/samples" },
+  // ORG-SCOPED since 2026-09-08, like the skill and block below: a project's nodes live at
+  // design/<project>/nodes/, the same rule as every other kind it authors. The id keeps
+  // the old flat string for the same reason theirs do.
+  { id: "nodes/samples", dir: "sample-nodes/samples", to: (p) => `design/${p}/nodes/samples` },
   // ORG-SCOPED since 2026-08-24: a sample skill/block lands in the FIRST project's own
   // folder, because that is where authored skills and blocks now live. `to` is a
   // function of the project for exactly that reason — the id stays the old flat string
@@ -180,10 +192,10 @@ export function topUpSamples(home, project) {
 }
 
 /**
- * The FIRST project, plus the folders that live beside the design tree rather than inside it.
- *
- * Skills, prompt blocks and nodes are per-developer and not per-project, so they are made
- * once here and never by `createProject`.
+ * The FIRST project, plus what a workspace needs exactly once: editor settings and the
+ * worked-example samples. Nothing lives beside the design tree any more: skills, blocks
+ * and (since 2026-09-08) nodes are all per-project, made by `createProject` or landed by
+ * topUpSamples inside the first project.
  */
 
 /**
@@ -195,17 +207,34 @@ export function topUpSamples(home, project) {
  */
 const SCHEMAS = "https://docs.unoverse.ai/schemas/nodes";
 const NODE_SCHEMA_MAP = {
-  [`${SCHEMAS}/package.schema.json`]: ["nodes/*/package.yaml"],
-  [`${SCHEMAS}/credential.schema.json`]: ["nodes/*/credentials/*.yaml"],
-  [`${SCHEMAS}/node.schema.json`]: ["nodes/*/nodes/*/node.yaml"],
-  [`${SCHEMAS}/interface.schema.json`]: ["nodes/*/nodes/*/interface.yaml"],
-  [`${SCHEMAS}/config.schema.json`]: ["nodes/*/nodes/*/config.yaml"],
-  [`${SCHEMAS}/test.schema.json`]: ["nodes/*/nodes/*/test.yaml"],
-  [`${SCHEMAS}/run.schema.json`]: ["nodes/*/nodes/*/api/run.yaml"],
-  [`${SCHEMAS}/events.schema.json`]: ["nodes/*/nodes/*/api/events.yaml"],
-  [`${SCHEMAS}/service.schema.json`]: ["nodes/*/nodes/*/api/service.yaml"],
-  [`${SCHEMAS}/toolExchange.schema.json`]: ["nodes/*/nodes/*/api/toolExchange.yaml"],
-  [`${SCHEMAS}/audio.schema.json`]: ["nodes/*/nodes/*/api/audio.yaml"],
+  [`${SCHEMAS}/package.schema.json`]: ["design/*/nodes/*/package.yaml"],
+  [`${SCHEMAS}/credential.schema.json`]: ["design/*/nodes/*/credentials/*.yaml"],
+  [`${SCHEMAS}/node.schema.json`]: ["design/*/nodes/*/nodes/*/node.yaml"],
+  [`${SCHEMAS}/interface.schema.json`]: ["design/*/nodes/*/nodes/*/interface.yaml"],
+  [`${SCHEMAS}/config.schema.json`]: ["design/*/nodes/*/nodes/*/config.yaml"],
+  [`${SCHEMAS}/test.schema.json`]: ["design/*/nodes/*/nodes/*/test.yaml"],
+  [`${SCHEMAS}/run.schema.json`]: ["design/*/nodes/*/nodes/*/api/run.yaml"],
+  [`${SCHEMAS}/events.schema.json`]: ["design/*/nodes/*/nodes/*/api/events.yaml"],
+  [`${SCHEMAS}/service.schema.json`]: ["design/*/nodes/*/nodes/*/api/service.yaml"],
+  [`${SCHEMAS}/toolExchange.schema.json`]: ["design/*/nodes/*/nodes/*/api/toolExchange.yaml"],
+  [`${SCHEMAS}/audio.schema.json`]: ["design/*/nodes/*/nodes/*/api/audio.yaml"],
+  // OBJECTS AND PIPELINES (objects README 9a, 2026-09-10): folders in the node grammar. The
+  // envelope is named for its folder, so its glob excludes the sibling files BY NAME, and
+  // api/service.yaml among them: in the YAML extension's matcher a `*` segment can cross
+  // `api/`, so without `service` in the exclusion the envelope schema claimed the functions
+  // file and red-underlined every key in it (seen live 2026-09-10, redhat.vscode-yaml 1.24.0).
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/object.schema.json`]: ["design/*/objects/*/!(props|test|service|make|dataset).yaml"],
+  // `dataset` joined the exclusion 2026-09-18: an object that owns a table declares its columns
+  // in dataset.yaml, and the envelope schema knows nothing of columns.
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/dataset.schema.json`]: ["design/*/objects/*/dataset.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/props.schema.json`]: ["design/*/objects/*/props.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/service.schema.json`]: ["design/*/objects/*/api/service.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/make.schema.json`]: ["design/*/objects/*/api/make.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/objects")}/test.schema.json`]: ["design/*/objects/*/test.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/pipelines")}/pipeline.schema.json`]: ["design/*/pipelines/*/pipeline.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/pipelines")}/config.schema.json`]: ["design/*/pipelines/*/config.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/pipelines")}/interface.schema.json`]: ["design/*/pipelines/*/interface.yaml"],
+  [`${SCHEMAS.replace(/\/nodes$/, "/pipelines")}/test.schema.json`]: ["design/*/pipelines/*/test.yaml"],
 };
 export function writeEditorSettings(home) {
   const dir = join(home, ".vscode");
@@ -218,9 +247,9 @@ export function writeEditorSettings(home) {
 
 export function createFirstProject(home, name) {
   const root = createProject(home, name);
-  // Only nodes/ remains beside the design tree; skills/ and blocks/ moved INTO the org
-  // (createProject makes them) so every authored kind sits in one place.
-  for (const d of ["nodes"]) mkdirSync(join(home, d), { recursive: true });
+  // NOTHING beside the design tree. skills/ and blocks/ moved INTO the org on 2026-08-24
+  // and nodes/ followed on 2026-09-08 (the sample package lands at design/<org>/nodes/),
+  // so every authored kind sits in one place.
   writeEditorSettings(home);
 
   topUpSamples(home, name);