unoverse 0.1.183 → 0.1.184

package/operator/ansible/playbooks/deploy-images.yml

@@ -2,14 +2,19 @@
 # DEPLOY IMAGES — the images half of the platform deploy.
 #
 # Pull the latest DOCR images and restart. That's the whole deployment:
-#   - platform code (incl. plugin-base, baked in the unoverse image) = the images
-#   - marketplace nodes CONVERGE at boot (keep-latest: the shared installed_plugins
-#     row is "the newest version anyone chose"; boot reinstalls anything missing
-#     or older — see runtime/plugins/startup.ts)
+#   - platform code = the images
+#   - node manifests are declarative YAML, loaded at boot
 #   - component nodes synthesize from design/ definitions at boot (no build, ever)
+#   - marketplace CONTENT is database rows and does not ride a deploy at all
 #
-# The CLI's `unoverse deploy` runs this first, then deploy-packages.yml (the
-# local-source half). Use directly only when images alone changed.
+# CORRECTED 2026-08-30. This used to say marketplace nodes "CONVERGE at boot (keep-latest:
+# the shared installed_plugins row... boot reinstalls anything missing or older — see
+# runtime/plugins/startup.ts)". That module is deleted, along with the whole npm install
+# lane; nothing is fetched from a registry (MARKETPLACE.md §10 q3). It also named
+# plugin-base, retired to _legacy, and chained to deploy-packages.yml, which does not
+# exist. Three things this playbook claimed on every deploy, none of them true.
+#
+# The CLI's `unoverse deploy` runs this. Use directly only when images alone changed.
 #
 # Usage (via CLI — recommended):
 #   unoverse deploy
@@ -71,10 +76,17 @@
       debug:
         msg: "{{ pull_result.stdout_lines[-8:] | default(['done']) }}"
 
-    - name: "[3/4] Restart on the new images (marketplace converges at boot)"
+    # A DEPLOY TAKES THE NEWEST NODE RUNTIME. The entrypoint installs
+    # @unoverse-platform/base within the range the image declares, but it only goes to the
+    # registry when the volume is cold or the range moved — otherwise a restart would be a
+    # network call, and a restart must be instant and offline. A DEPLOY is the moment the
+    # operator asked for "make this current" (MARKETPLACE.md §5a), so it says so explicitly.
+    # Scoped to this one `up`, never written into .env: a later `docker restart` must not
+    # inherit it.
+    - name: "[3/4] Restart on the new images (and take the newest base in range)"
       shell: |
         cd {{ gravity_dir }}
-        docker compose up -d 2>&1 | tail -6
+        UNOVERSE_BASE_REFRESH=1 docker compose up -d 2>&1 | tail -6
       register: up_result
 
     # `up -d` RECREATES ON CONFIG CHANGE, NOT ON IMAGE CHANGE — not reliably, and not on
@@ -120,7 +132,8 @@
           ============================================
           Host:   {{ inventory_hostname }} ({{ ansible_host }})
           {{ status_result.stdout }}
-          Marketplace nodes converge to the recorded
-          versions at boot; component nodes synthesize
-          from design/ definitions.
+          Node manifests load at boot; component nodes
+          synthesize from design/ definitions.
+          Marketplace content is rows and is unchanged
+          by a deploy.
           ============================================

package/operator/ansible/playbooks/restore.yml

@@ -80,14 +80,18 @@
         chdir: /opt/gravity
       when: restore_umap
 
+    # THROUGH THE DOCKER NETWORK, not the host. umap publishes no port (docker-compose.yml,
+    # 2026-08-30: it is internal to Docker, full stop), so `http://localhost:5001` reaches
+    # nothing from here and this wait would spin for 60s and fail a good restore.
     - name: Wait for UMAP to be healthy
-      uri:
-        url: "http://localhost:5001/health"
-        status_code: 200
+      shell: |
+        cd /opt/gravity
+        docker compose exec -T umap python3 -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:5001/health', timeout=5).status == 200 else 1)"
       register: health_check
-      until: health_check.status == 200
+      until: health_check.rc == 0
       retries: 30
       delay: 2
+      changed_when: false
       when: restore_umap
 
     - name: Cleanup restore files

package/operator/ansible/playbooks/test-connectivity.yml

@@ -36,12 +36,14 @@
         host: localhost
         port: "{{ item.port }}"
         timeout: 5
+      # UMAP is deliberately absent: it publishes no port to the host (internal to Docker
+      # only). Its reachability is proved by the Docker-DNS check below, which is the only
+      # thing that was ever actually load-bearing for it.
       loop:
         - { name: "Canvas", port: 3001 }
         - { name: "Engine", port: 4101 }
         - { name: "Unoverse", port: 4105 }
         - { name: "Memory", port: 4104 }
-        - { name: "UMAP", port: 5001 }
       register: port_checks
       ignore_errors: yes
 
@@ -83,7 +85,6 @@
         - { name: "Engine", port: 4101 }
         - { name: "Unoverse", port: 4105 }
         - { name: "Memory", port: 4104 }
-        - { name: "UMAP", port: 5001 }
       register: health_checks
       ignore_errors: yes
 
@@ -162,10 +163,12 @@
       register: plugin_check
       ignore_errors: yes
 
-    # NO PACKAGES CHECK. It looked for /app/host_packages, a bind mount that was retired
-    # when nodes moved to npm at runtime plus the marketplace. Nothing declares
+    # NO PACKAGES CHECK. It looked for /app/host_packages, a bind mount retired when nodes
+    # became declarative YAML and marketplace content became rows. Nothing declares
     # PACKAGES_PATH any more and docker-compose.yml has no such volume, so the check could
     # only ever report 0 and tell the operator to run a command that would not fix it.
+    # (The original note said nodes "moved to npm at runtime"; that lane never survived and
+    # was removed outright on 2026-08-30. MARKETPLACE.md §10 q3.)
 
     # SINCE THE SERVICES RESTARTED, NOT SINCE FIVE MINUTES AGO.
     #

package/operator/docker-compose.yml

@@ -130,11 +130,35 @@ services:
   # Studio is NOT a platform image (removed 2026-07-28): it ships from npm and
   # connects to a universe over the API with a publish key.
 
-  # UMAP Service - Python ML service
+  # UMAP Service - Python ML service.
+  #
+  # THE ENGINE REACHES IT AS http://umap:5001 OVER THE DOCKER NETWORK, which needs no
+  # published port at all. It used to read "5001:5001", which binds 0.0.0.0 and put an ML
+  # service on the internet, and until 2026-08-30 that service also failed OPEN:
+  # its `require_auth` returned the handler unguarded whenever OIDC was unconfigured, and no
+  # AUTH_ISSUER was ever passed here. So `/train` answered anyone who could reach the port.
+  #
+  # It was the only service in this file that was both externally bound and ungated: 4101 and
+  # 4106 are loopback-pinned with comments saying never to widen them, and 4105 is published
+  # but JWT-gated. This one had neither half.
+  #
+  # NOT PUBLISHED AT ALL. Owner ruling 2026-08-30: this is internal to Docker, full stop.
+  # There is no `ports:` block below and that is the whole point — a service reachable only
+  # over the compose network cannot be bound to the wrong interface by a later edit, because
+  # there is no line to get wrong. 4101 and 4106 publish to loopback because a developer's
+  # tooling on the host genuinely needs them; nothing on the host needs this.
+  #
+  # Auth stays configured anyway. The network boundary and the gate are not alternatives,
+  # and this service is the proof: it had a `ports:` line and a fail-open decorator, so
+  # losing either one lost everything.
   umap:
     image: registry.digitalocean.com/gravity-repo/umap:latest
-    ports:
-      - "5001:5001"
+    environment:
+      # app.py refuses to boot if auth is on and these are missing (assert_auth_startup),
+      # which is the point: an unconfigured deployment fails loudly instead of open.
+      - AUTH_ENABLED=${AUTH_ENABLED:-true}
+      - AUTH_ISSUER=${AUTH_ISSUER}
+      - AUTH_AUDIENCE=${AUTH_AUDIENCE}
     volumes:
       - umap_models:/app/models
     logging: *default-logging
@@ -251,8 +275,20 @@ services:
       # copy carrying a built dist. Without this the runtime hits MODULE_NOT_FOUND and
       # the nodes show "Package not installed".
       - NODE_PATH=/app/host_node_modules:/app/plugins/node_modules
+      # PASSTHROUGH, not a setting. `unoverse deploy` runs `UNOVERSE_BASE_REFRESH=1 docker
+      # compose up -d` to mean "take the newest node runtime in range"; without this line
+      # that variable would reach the compose CLI and stop there, never the container.
+      # Defaults to 0, so an ordinary restart stays offline and instant.
+      - UNOVERSE_BASE_REFRESH=${UNOVERSE_BASE_REFRESH:-0}
     volumes:
       - unoverse_plugins:/app/plugins
+      # THE NODE RUNTIME, which this image does not carry (MARKETPLACE.md §5a). The
+      # entrypoint installs @unoverse-platform/base here at startup, within the range
+      # apps/unoverse/package.json declares, and symlinks it into
+      # /app/node_modules/@unoverse-platform/base. A volume rather than a layer so a plain
+      # restart is offline and instant: the fetch happens on a cold volume, or when the
+      # declared range changes, or when a deploy sets UNOVERSE_BASE_REFRESH=1.
+      - unoverse_base:/app/base
       # ── Platform-dev mounts (monorepo only; sync-starter strips these three
       # lines from the starter's copy — a customer universe serves what the DB
       # says). Local edits are picked up on restart; design/prompts are data, no build.
@@ -371,3 +407,4 @@ services:
 volumes:
   umap_models:
   unoverse_plugins: # Marketplace-installed node packages (persisted across restarts)
+  unoverse_base: # @unoverse-platform/base, installed at startup (MARKETPLACE.md §5a)

package/operator/lib/check.sh

@@ -77,6 +77,32 @@ cmd_check() {
   done
   echo ""
 
+  # 1b. THE NODE RUNTIME THIS UNIVERSE IS ACTUALLY RUNNING.
+  #
+  # base is installed at startup, not baked into the image (MARKETPLACE.md §5a), so a
+  # universe's platform version and its runtime version are two different numbers that move
+  # independently. Nobody updates what they cannot see: this is the line that turns "which
+  # base am I on?" into something answerable, and shows the gap when the registry has newer.
+  # Read out of the RUNNING container rather than off this machine's disk, because the
+  # container is the only thing whose answer counts.
+  local base_installed base_range base_latest
+  base_installed=$(docker compose -f "$ROOT/docker-compose.yml" exec -T unoverse \
+    node -p "require('/app/node_modules/@unoverse-platform/base/package.json').version" 2>/dev/null | tr -d '\r')
+  if [ -n "$base_installed" ]; then
+    base_range=$(docker compose -f "$ROOT/docker-compose.yml" exec -T unoverse \
+      node -p "require('/app/apps/unoverse/package.json').dependencies['@unoverse-platform/base']" 2>/dev/null | tr -d '\r')
+    base_latest=$(curl -s --max-time 5 "https://registry.npmjs.org/-/package/@unoverse-platform%2Fbase/dist-tags" 2>/dev/null \
+      | node -pe 'try{JSON.parse(require("fs").readFileSync(0,"utf8")).latest ?? ""}catch(e){""}' 2>/dev/null)
+    if [ -n "$base_latest" ] && [ "$base_latest" != "$base_installed" ]; then
+      # NOT a failure. A universe is entitled to sit on an older runtime; it is not entitled
+      # to be unable to find out. `deploy` and `update` are what take the newer one.
+      warn "node runtime ${BOLD}$base_installed${NC} ${DIM}(range $base_range · npm has $base_latest — 'unoverse deploy' takes it)${NC}"
+    else
+      ok "node runtime ${BOLD}$base_installed${NC} ${DIM}(range ${base_range:-unknown})${NC}"
+    fi
+    echo ""
+  fi
+
   # 2. Health endpoints
   for endpoint in 4105:unoverse 4101:engine 5001:umap 4104:memory; do
     local port="${endpoint%%:*}" name="${endpoint##*:}"

package/operator/lib/db-verify.sh

@@ -40,7 +40,8 @@ cmd_db_verify() {
       ],
       workflow_executions: [
         "execution_id", "workflow_id", "status", "start_time", "end_time",
-        "duration", "error", "result", "created_at", "was_from_cache", "source"
+        "duration", "error", "result", "created_at", "was_from_cache", "source",
+        "user_id"
       ],
       node_traces: [
         "trace_id", "execution_id", "node_id", "node_type", "start_time",
@@ -52,7 +53,7 @@ cmd_db_verify() {
       ],
       token_usage: [
         "id", "workflow_id", "execution_id", "node_id", "node_type",
-        "model", "usage", "timestamp", "created_at"
+        "model", "usage", "timestamp", "created_at", "user_id"
       ],
       raw_messages: [
         "id", "user_id", "workflow_id", "conversation_id", "chat_id",

package/operator/lib/deploy.sh

@@ -892,9 +892,13 @@ EOF
   case "$subcommand" in
     ""|deploy)
       # THE deploy: the server takes the latest platform images (pull + restart).
-      # Content does NOT ride deploys — it arrives via git (`unoverse update`
-      # pulls the starter clone incl. the carve-out), the marketplace (DB-driven,
-      # self-healing at boot) and, when the gate lands, Studio publish.
+      # Content does NOT ride deploys — it arrives from the marketplace as database
+      # ROWS (`POST /marketplace/install`) or from `unoverse deploy studio`.
+      #
+      # "self-healing at boot" was the npm install lane (`plugins/startup.ts`),
+      # deleted 2026-08-30 — nothing is fetched from a registry (MARKETPLACE.md §10 q3).
+      # The one fetch that is coming is the node runtime, `@unoverse-platform/base`,
+      # installed here within a range the image declares (§5a, NOT YET BUILT).
       info "Deploying platform images..."
       echo ""
       ansible-playbook \

package/operator/operator.sh

@@ -155,6 +155,12 @@ case "${1:-}" in
         exit 1
       fi
       if [ -n "$(docker compose -f "$ROOT/docker-compose.yml" ps -q 2>/dev/null)" ]; then
+        # THE NODE RUNTIME UPDATES LIKE THE IMAGES DO. base is installed at startup, not
+        # baked (MARKETPLACE.md §5a), and the entrypoint only goes to the registry on a cold
+        # volume or a changed range — otherwise every restart would be a network call. An
+        # UPDATE is exactly the moment the operator asked for the newest of everything, so
+        # it says so. Scoped to this command; nothing is written to .env.
+        UNOVERSE_BASE_REFRESH=1 \
         docker compose -f "$ROOT/docker-compose.yml" --env-file "$ROOT/.env" up -d --remove-orphans >/dev/null 2>&1 \
           && ok "Running services moved to the new images"
         # MIGRATIONS RUN ON UPDATE, same as deploy and start. An update is exactly when a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unoverse",
-  "version": "0.1.183",
+  "version": "0.1.184",
   "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/items/collect.js

@@ -93,9 +93,9 @@ export function collectProject(designRoot, project) {
     // `course-card` or `hr-education-coach`, so the org must be in the name for the
     // rows to coexist (the same trick a style row already uses: its name IS the org).
     // A prompt block is NEVER qualified this way — see the blocks/ walk below for why.
-    // Templates keep their bare ids: those are org-qualified by convention
-    // (`<org>-chat-layout`). docs/unoverse/UNOVERSE_COMPONENT_ORGS.md.
-    const QUALIFIED_KINDS = new Set(["component", "skill", "design-template"]);
+    // Apps keep their bare ids: those are org-qualified by convention
+    // (`<org>-chat`). docs/unoverse/UNOVERSE_COMPONENT_ORGS.md.
+    const QUALIFIED_KINDS = new Set(["component", "skill", "template"]);
     const add = (kind, name, definition) => items.push({
         kind,
         name: QUALIFIED_KINDS.has(kind) ? `${project}/${name}` : name,
@@ -104,9 +104,9 @@ export function collectProject(designRoot, project) {
         org: project,
         base_version,
     });
-    // `templates` publishes as kind `template`, NOT `recipe`. A recipe is a workflow graph
+    // `apps` publishes as kind `app`, NOT `recipe`. A recipe is a workflow graph
     // that is copied onto a canvas and never installed; an app is installed and tracked, so
-    // taking a newer version is the point rather than a hazard (migration 017).
+    // taking a newer version is the point rather than a hazard (migrations 017 + 029).
     //
     // A DEFINITION IS EITHER A FOLDER OR A SINGLE FILE, and both are normal. A component
     // that grew layouts and states is a folder; an atom is one file, and templates are a
@@ -115,11 +115,11 @@ export function collectProject(designRoot, project) {
     //
     // Both become the same shape, a map of relative path to contents, so nothing downstream
     // has to care which it was. A single file is simply a map with one entry.
-    // `templates/` (the Template Model kind, 2026-08-28) stores as `design-template`:
-    // the natural word `template` is FROZEN as the apps' stored kind (migration-free
-    // legacy), and overloading it would make hydrate guess. Forgetting this dir here
-    // shipped design deploys that silently dropped every authored template.
-    for (const [dir, kind] of [["components", "component"], ["apps", "template"], ["templates", "design-template"], ["atoms", "atom"]]) {
+    // APP MEANS APP, TEMPLATE MEANS TEMPLATE (owner ruling 2026-08-28, migration
+    // 029): apps publish as kind `app` and the Template Model kind owns the bare
+    // word. Forgetting a design dir here ships deploys that silently drop every
+    // artifact of that kind.
+    for (const [dir, kind] of [["components", "component"], ["apps", "app"], ["templates", "template"], ["atoms", "atom"]]) {
         const home = join(root, dir);
         if (!existsSync(home))
             continue;

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

@@ -14,11 +14,39 @@
  */
 import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
 import { join, dirname, basename, relative, sep } from "node:path";
-import { RAW_VALUE, PARTIAL_DIRS } from "./vocabulary.mjs";
+import { RAW_VALUE, PARTIAL_DIRS, PROP_KEYS, INTERFACE_FIELDS, AUTHORED_CONTROLS } from "./vocabulary.mjs";
 import { isDefFile, defName, defPath, readDef, parseDef } from "./defs.mjs";
 
+/**
+ * THE PROPS MAP IS THE CONTRACT (UNOVERSE_AUTHORING §3b, ruled 2026-08-30). Every field's
+ * description, limits, mock and hydration live here now, so this is where they are held
+ * to a shape — and where a prop wearing an INTERFACE FIELD's name is told what happens
+ * when a delivery carries that field.
+ */
+function checkProps(props, file, report, path) {
+  if (!props || typeof props !== "object" || Array.isArray(props)) return;
+  for (const [name, spec] of Object.entries(props)) {
+    if (name.startsWith("_comment")) continue; // a JSON comment, not a prop
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) continue;
+    const where = path ? `${path}${name}` : name;
+    for (const k of Object.keys(spec))
+      if (!PROP_KEYS.includes(k))
+        report("error", file, `prop "${where}" has no "${k}". A prop reads ${PROP_KEYS.map((x) => `"${x}"`).join(", ")} — everything it needs to be understood and written (UNOVERSE_AUTHORING §3b)`);
+    // THE DELIVERY WINS. A row fills a component by name with no mapping layer
+    // (docs.unoverse.ai/design/interface-data), so `title` on a content-attached card is
+    // the row's title. Using the name is right and expected; writing a brief for a field
+    // the delivery supplies is the part that quietly never applies.
+    if (!path && INTERFACE_FIELDS.has(name)) {
+      const controls = AUTHORED_CONTROLS.filter((k) => spec[k] !== undefined);
+      if (controls.length)
+        report("warn", file, `prop "${name}" is an INTERFACE FIELD, so a delivery fills it by name — and a row's value is not measured against the ${controls.map((c) => `"${c}"`).join(", ")} written here. Keep the name (binding is by name, never mapped); the limit applies only to a value an Agent writes (docs.unoverse.ai/design/interface-data)`);
+    }
+    if (spec.items && typeof spec.items === "object") checkProps(spec.items, file, report, `${where}.items.`);
+  }
+}
+
 export function makeLintFile(ctx) {
-  const { report, walkNode, isFixture, isHook, isManifest, isAppPath, defRoot, componentNamesForFile, DS, orgDirs, RX, readText } = ctx;
+  const { report, walkNode, isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePart, defRoot, componentNamesForFile, DS, orgDirs, RX, readText } = ctx;
 
 function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
   if (!Array.isArray(order)) return;
@@ -42,6 +70,86 @@ function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
       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)`);
 }
 
+
+// THE APP TREE CHECK (extracted 2026-08-29: the tree's home is the ENVELOPE —
+// one folder grammar — while a manifest-held tree remains the legacy read, so
+// both call sites validate identically).
+function checkAppTree(json, root, file) {
+      if (json.states !== undefined) {
+        if (!json.states || typeof json.states !== "object" || Array.isArray(json.states)) {
+          report("error", file, `manifest "states" must be an object — the template tree: { <base>: { states: {…} }, <reaction>: {}, … } (STATE_MODEL §5)`);
+        } else {
+          const names = Object.keys(json.states);
+          const base = json.layout ?? Object.keys(json.states)[0] ?? "main";
+          if (!names.includes(base))
+            report("error", file, `the template tree must include the BASE state "${base}" (named for the default layout) — the ladder derives as the top level minus it (STATE_MODEL §5)`);
+          const subs = [];
+          for (const [n, s] of Object.entries(json.states)) {
+            if (s !== null && (typeof s !== "object" || Array.isArray(s)))
+              report("error", file, `tree state "${n}" must be an object declaring its layout path (STATE_MODEL §5)`);
+            // EXPLICIT PATHS (owner ruling 2026-08-29): every state DECLARES the
+            // layout it draws as a root-relative path (layout: layouts/<file>);
+            // nothing is assumed from the state's name and no folder is magic.
+            const declared = s && typeof s === "object" && typeof s.layout === "string" ? s.layout : undefined;
+            if (!declared)
+              report("error", file, `tree state "${n}" declares no layout. Every state names its drawing as a path — layout: layouts/${n} (2026-08-29 ruling; the same-name default is retired) (STATE_MODEL §5)`);
+            else if (!defPath(root, declared))
+              report("error", file, `tree state "${n}" declares layout "${declared}" but no such file exists (STATE_MODEL §5)`);
+            const nested = s && typeof s === "object" ? s.states : undefined;
+            if (nested && typeof nested === "object" && !Array.isArray(nested))
+              for (const [sub, sv] of Object.entries(nested)) {
+                subs.push(sub);
+                const subDeclared = sv && typeof sv === "object" && typeof sv.layout === "string" ? sv.layout : undefined;
+                if (!subDeclared)
+                  report("error", file, `substate "${sub}" (under "${n}") declares no layout. Every state names its drawing as a path — layout: layouts/${n}-${sub} (the owner-prefix naming convention survives as readability) (2026-08-29 ruling) (LAYERS §3)`);
+                else if (!defPath(root, subDeclared))
+                  report("error", file, `substate "${sub}" (under "${n}") declares layout "${subDeclared}" but no such file exists (LAYERS §3)`);
+              }
+          }
+          for (const sub of subs)
+            if (names.includes(sub))
+              report("error", file, `"${sub}" is declared both as a top-level state and a substate — nesting IS containment; a name lives at exactly one level (STATE_MODEL §5)`);
+          // THE FOLDER CANNOT LIE (owner ruling 2026-08-22): every layouts/ file is
+          // either a SCREEN (a bare name declaring a top-level state) or a substate
+          // drawing (<owner>-<sub>, both declared). Anything else is an error — a
+          // shared part belongs in components/.
+          {
+            const ldir = join(root, "layouts");
+            if (existsSync(ldir)) {
+              const declaredSubs = new Map();
+              for (const [n2, s2] of Object.entries(json.states)) {
+                const nested2 = s2 && typeof s2 === "object" ? s2.states : undefined;
+                if (nested2 && typeof nested2 === "object" && !Array.isArray(nested2))
+                  for (const sub2 of Object.keys(nested2)) declaredSubs.set(`${n2}-${sub2}`, n2);
+              }
+              // A file NAMED by any state's/substate's declared path is accounted
+              // for wherever it sits (2026-08-29: declarations, not names, link).
+              const declaredPaths = new Set();
+              for (const s3 of Object.values(json.states)) {
+                if (s3 && typeof s3 === "object" && typeof s3.layout === "string") declaredPaths.add(s3.layout);
+                const nested3 = s3 && typeof s3 === "object" ? s3.states : undefined;
+                if (nested3 && typeof nested3 === "object" && !Array.isArray(nested3))
+                  for (const sv3 of Object.values(nested3))
+                    if (sv3 && typeof sv3 === "object" && typeof sv3.layout === "string") declaredPaths.add(sv3.layout);
+              }
+              for (const f of readdirSync(ldir).filter(isDefFile)) {
+                const nm = defName(f);
+                if (declaredPaths.has(`layouts/${nm}`)) continue;
+                if (names.includes(nm) || declaredSubs.has(nm)) continue;
+                const owner = names.find((n2) => nm.startsWith(`${n2}-`));
+                if (owner)
+                  report("error", file, `layouts/${nm} is prefixed for state "${owner}" but "${nm.slice(owner.length + 1)}" is not declared as its substate — declare it in the tree, or move the file to components/ if it is a shared part (LAYERS §3)`);
+                else
+                  report("error", file, `layouts/${nm} is neither a declared state nor an <owner>-<sub> substate drawing — bare names are the app's screens; declare it, prefix it with its owner, or move it to components/ (LAYERS §3)`);
+              }
+            }
+          }
+          if (json.stateOrder !== undefined)
+            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);
+}
+
 // ── lint one file ──
 function lintFile(file) {
   // `readText` is disk unless the caller supplied an overlay for this path (index.mjs).
@@ -87,6 +195,7 @@ function lintFile(file) {
 
   if (isFixture(file)) return; // legacy fixture, unused: don't choke
   if (isHook(file)) return;    // a lifecycle hook: calls + a projection, not a UI tree
+  if (isPropsExtract(file)) return; // the envelope's props map, composed there — not a UI tree
 
   if (isManifest(file)) {
     const root = dirname(file);
@@ -106,9 +215,19 @@ function lintFile(file) {
         const firstState = json.states && typeof json.states === "object" && !Array.isArray(json.states)
           ? Object.keys(json.states)[0]
           : undefined;
-        const layoutName = json.layout ?? firstState ?? "main";
-        if (!defPath(join(root, "layouts"), layoutName))
-          report("error", file, `manifest.layout "${layoutName}" → layouts/${layoutName} does not exist (and no <name> envelope) (docs.unoverse.ai/design/apps)`);
+        // The base state's DECLARED path wins (2026-08-29 ruling: layout is a
+        // root-relative path, nothing assumed); the name fallback survives only
+        // for the unswept installed tier.
+        const firstEntry = firstState ? json.states[firstState] : undefined;
+        const declaredBase = firstEntry && typeof firstEntry === "object" && typeof firstEntry.layout === "string" ? firstEntry.layout : undefined;
+        if (declaredBase) {
+          if (!defPath(root, declaredBase))
+            report("error", file, `base state "${firstState}" declares layout "${declaredBase}" but no such file exists (docs.unoverse.ai/design/apps)`);
+        } else {
+          const layoutName = json.layout ?? firstState ?? "main";
+          if (!defPath(join(root, "layouts"), layoutName))
+            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:
@@ -123,59 +242,7 @@ function lintFile(file) {
       // into layouts/ and update $include paths.
       if (existsSync(join(root, "states")))
         report("error", file, `template carries a states/ folder — templates have ONE drawings folder. Move states/* into layouts/ and update every "$include: states/<name>" to "layouts/<name>" (anatomy unified with components, LAYERS §3)`);
-      if (json.states !== undefined) {
-        if (!json.states || typeof json.states !== "object" || Array.isArray(json.states)) {
-          report("error", file, `manifest "states" must be an object — the template tree: { <base>: { states: {…} }, <reaction>: {}, … } (STATE_MODEL §5)`);
-        } else {
-          const names = Object.keys(json.states);
-          const base = json.layout ?? Object.keys(json.states)[0] ?? "main";
-          if (!names.includes(base))
-            report("error", file, `the template tree must include the BASE state "${base}" (named for the default layout) — the ladder derives as the top level minus it (STATE_MODEL §5)`);
-          const subs = [];
-          for (const [n, s] of Object.entries(json.states)) {
-            if (s !== null && (typeof s !== "object" || Array.isArray(s)))
-              report("error", file, `tree state "${n}" must be an object ({} is a complete state) (STATE_MODEL §5)`);
-            if (n !== base && !defPath(join(root, "layouts"), n))
-              report("error", file, `tree state "${n}" has no layouts/${n}. Every state's drawing — a full arrangement or a stacked overlay — lives in layouts/, the template's ONE drawings folder (anatomy unified with components, LAYERS §3) (STATE_MODEL §5)`);
-            const nested = s && typeof s === "object" ? s.states : undefined;
-            if (nested && typeof nested === "object" && !Array.isArray(nested))
-              for (const sub of Object.keys(nested)) {
-                subs.push(sub);
-                if (!defPath(join(root, "layouts"), `${n}-${sub}`))
-                  report("error", file, `substate "${sub}" (under "${n}") has no layouts/${n}-${sub} file — a substate's drawing is OWNER-PREFIXED in layouts/ (the step-* convention: bare names are the app's screens, <owner>-<sub> their sub-drawings) (LAYERS §3)`);
-              }
-          }
-          for (const sub of subs)
-            if (names.includes(sub))
-              report("error", file, `"${sub}" is declared both as a top-level state and a substate — nesting IS containment; a name lives at exactly one level (STATE_MODEL §5)`);
-          // THE FOLDER CANNOT LIE (owner ruling 2026-08-22): every layouts/ file is
-          // either a SCREEN (a bare name declaring a top-level state) or a substate
-          // drawing (<owner>-<sub>, both declared). Anything else is an error — a
-          // shared part belongs in components/.
-          {
-            const ldir = join(root, "layouts");
-            if (existsSync(ldir)) {
-              const declaredSubs = new Map();
-              for (const [n2, s2] of Object.entries(json.states)) {
-                const nested2 = s2 && typeof s2 === "object" ? s2.states : undefined;
-                if (nested2 && typeof nested2 === "object" && !Array.isArray(nested2))
-                  for (const sub2 of Object.keys(nested2)) declaredSubs.set(`${n2}-${sub2}`, n2);
-              }
-              for (const f of readdirSync(ldir).filter(isDefFile)) {
-                const nm = defName(f);
-                if (names.includes(nm) || declaredSubs.has(nm)) continue;
-                const owner = names.find((n2) => nm.startsWith(`${n2}-`));
-                if (owner)
-                  report("error", file, `layouts/${nm} is prefixed for state "${owner}" but "${nm.slice(owner.length + 1)}" is not declared as its substate — declare it in the tree, or move the file to components/ if it is a shared part (LAYERS §3)`);
-                else
-                  report("error", file, `layouts/${nm} is neither a declared state nor an <owner>-<sub> substate drawing — bare names are the app's screens; declare it, prefix it with its owner, or move it to components/ (LAYERS §3)`);
-              }
-            }
-          }
-          if (json.stateOrder !== undefined)
-            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);
+      checkAppTree(json, root, file);
       // 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.
@@ -185,7 +252,7 @@ function lintFile(file) {
           if (Array.isArray(n)) return n.forEach((c) => collectClaims(c, from));
           if (!n || typeof n !== "object") return;
           const w = n.type === "ComponentSlot" ? n.select?.where : null;
-          if ((w?.field === "view" || w?.field === "defaultState") && typeof w.eq === "string") {
+          if ((w?.field === "state" || 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.unoverse.ai/design/state)`);
             else claims.set(w.eq, from);
@@ -227,9 +294,16 @@ function lintFile(file) {
           // The resolver already looks both ways (definitions.ts, template tree); without
           // the same lookup here a correctly-migrated template lints as though every one
           // of its substates had vanished.
-          const declared = json.states && typeof json.states === "object" && !Array.isArray(json.states) ? json.states : {};
-          for (const [parent, node] of Object.entries(declared))
+          // The tree's home is the ENVELOPE (one folder grammar, 2026-08-29); a
+          // manifest-held tree is the legacy read.
+          const envPath = defPath(root, basename(root));
+          const envStates = envPath ? readDef(envPath)?.states : undefined;
+          const treeStates = (json.states && typeof json.states === "object" && !Array.isArray(json.states) ? json.states : undefined)
+            ?? (envStates && typeof envStates === "object" && !Array.isArray(envStates) ? envStates : {});
+          for (const [parent, node] of Object.entries(treeStates)) {
+            states.add(parent);
             for (const sub of Object.keys(node?.states ?? {})) if (states.has(`${parent}-${sub}`)) states.add(sub);
+          }
           const comps = componentNamesForFile(file);
           for (const [state, list] of Object.entries(json.preview)) {
             if (!states.has(state))
@@ -283,39 +357,104 @@ function lintFile(file) {
   const root = defRoot(file);
 
   if (isEnvelope) {
-    // COMPONENT envelope (templates have no envelope — their manifest is it).
     // The declaration word is `type:`; `kind:` is the legacy spelling, still read.
+    // ONE FOLDER GRAMMAR (owner ruling 2026-08-29): every kind has an envelope
+    // saying what it IS. component/atom = root; template = parts+shapes; app =
+    // the states tree (its manifest stays the MCP face).
     const declared = json.type ?? json.kind;
-    for (const req of ["name", "root"])
+    // Template grammar §9b (2026-08-29): states like every kind; parts/shapes = legacy.
+    // ONE REQUIREMENT SHAPE (2026-08-29): a kind declares its tree (`states:`) OR
+    // its drawing (`root` — flat components/atoms). A tree component's root is
+    // SYNTHESIZED by the compiler, never required.
+    const envelopeRequired =
+      declared === "app" || declared === "template" ? ["name", "states"]
+      : declared === "component" ? ["name", ...(json.states !== undefined || json.state?.view !== undefined ? [] : ["root"])]
+      : ["name", "root"];
+    if (declared === "template" && json.states === undefined && (json.parts !== undefined || json.shapes !== undefined)) envelopeRequired.pop();
+    for (const req of envelopeRequired)
       if (json[req] === undefined) report("error", file, `envelope missing "${req}" (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
     if (declared === undefined) report("error", file, `envelope missing "type" (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
     if (json.kind !== undefined && json.type === undefined)
       report("warn", file, `"kind" is the legacy spelling of the declaration — write "type: ${json.kind}"`);
-    if (declared && !["component", "template", "atom"].includes(declared))
+    if (declared && !["component", "template", "atom", "app"].includes(declared))
       report("error", file, `unknown type "${declared}"`);
     if (declared === "component" && !json.category)
       report("warn", file, `component has no "category". Used to group it in the palette (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+    // APP envelope: the states tree lives HERE (one folder grammar) — validate it
+    // exactly as the legacy manifest-held tree was.
+    if (declared === "app") checkAppTree(json, root, file);
     if (json.root) walkNode(json.root, file, root);
 
     // ── the contained-microapp discipline (mirrors microapp-structure.test.ts) ──
     if (declared === "component") {
-      const hasLayouts = existsSync(join(root, "layouts"));
+      // A TEMPLATE'S OWN PART IS A FLAT COMPONENT (TEMPLATE_MODEL §9b rule 7): one file,
+      // no manifest, no state tree — the face IS the filename. Its `root` here is the
+      // TEMPLATE's folder, which does carry `layouts/`, so without this the whole faced-
+      // component discipline fires on every part and demands a Switch it must not have.
+      const hasLayouts = !isTemplatePart(file) && existsSync(join(root, "layouts"));
       const statesDir = join(root, "states");
       const stateFiles = existsSync(statesDir)
         ? readdirSync(statesDir).filter(isDefFile).map(defName).sort()
         : [];
       const hasStateBlock = json.state && typeof json.state === "object";
 
-      // the discovery manifest is the single home for description/whenToUse — no dup
-      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.unoverse.ai/design/components)`);
+      // THE DISCOVERY MANIFEST IS THE SINGLE HOME for the meta — but the envelope's own
+      // `description` is now COMPOSITION CONTEXT (UNOVERSE_AUTHORING §3b, 2026-08-30):
+      // what an Agent filling the WHOLE of this must know, which used to ride an unbound
+      // `brief` on the layout root. Two files, two audiences. Only a COPY of the
+      // manifest's text is the duplication this rule exists to stop.
+      {
+        const mPath = defPath(root, "manifest");
+        let m = null;
+        if (mPath) { try { m = readDef(mPath); } catch { m = null; } }
+        if (m) {
+          if (json.whenToUse !== undefined)
+            report("error", file, `envelope duplicates manifest meta "whenToUse". The discovery manifest is the single home (docs.unoverse.ai/design/components)`);
+          if (typeof json.description === "string" && json.description.trim() === String(m.description ?? "").trim())
+            report("error", file, `the envelope's "description" is a copy of the manifest's. The manifest is the single home for the DISCOVERY line; the envelope's own description is composition context — what an Agent filling the whole of this must know (UNOVERSE_AUTHORING §3b)`);
+        }
+      }
 
       // deprecated bridge: a top-level `defaultState` triggers the component node APP_DATA emit
       if (json.defaultState !== undefined)
         report("warn", file, `top-level "defaultState" is the deprecated bridge (component-node APP_DATA emit). The master state lives in the \`state\` block; templates react via ComponentSlot.select.where (STATE_MODEL §5b)`);
 
+      // THE PROP IS THE BRIEF (UNOVERSE_AUTHORING §3b, 2026-08-30): a prop declares
+      // everything about itself, so the props map is the whole contract and is held to a
+      // closed shape. The props extract composes first (`props: { $include: props }` —
+      // the loader does the same before any reader sees the map).
+      let judgedProps = json.props ?? {};
+      if (typeof judgedProps.$include === "string") {
+        const incPath = defPath(root, judgedProps.$include);
+        if (!incPath) {
+          report("error", file, `props $include "${judgedProps.$include}" resolves to no file in the definition folder (docs.unoverse.ai/design/components)`);
+          judgedProps = {};
+        } else {
+          try { judgedProps = readDef(incPath) ?? {}; } catch { judgedProps = {}; }
+        }
+      }
+      checkProps(judgedProps, file, report, "");
+
+      // EVERY PROP CARRIES A DESCRIPTION (UNOVERSE_AUTHORING §3b, RULED 2026-08-30).
+      //
+      // It reads BOTH ways, which is why it is compulsory rather than encouraged. A
+      // description is not only what a copywriter fills against: it is what lets an agent
+      // UNDERSTAND the screen it is looking at. `read` reports where the person is; the
+      // descriptions say what is actually in front of them. A screen of unnamed fields is
+      // one no agent can reason about, in either direction.
+      //
+      // AND IT SAYS NOTHING ABOUT PERMISSION. That is the layout's word — `static` /
+      // `copywriter` / `director` (TEMPLATE_MODEL §9b) — never a prop's. The rule this
+      // replaces was "a described prop is a writable prop", which made silence the safety
+      // mechanism: a field was protected because nobody had explained it, and explaining it
+      // was what exposed it. Describing a field is now free of consequence, so there is no
+      // longer any reason to leave one blank.
+      const undescribed = Object.entries(judgedProps)
+        .filter(([, v]) => !(v && typeof v === "object" && typeof v.description === "string" && v.description.trim()))
+        .map(([k]) => k);
+      if (undescribed.length)
+        report("error", file, `props [${undescribed.join(", ")}] carry no "description". Every prop says what it IS, so an agent can read the screen as well as fill it. A description grants nothing: permission is the layout's word (static / copywriter / director), never a prop's (UNOVERSE_AUTHORING §3b)`);
+
       // only components that ADOPTED the structure are held to the full discipline
       if (hasLayouts || stateFiles.length || hasStateBlock) {
         // Every prop declares what fills it. Was "must be input:true", from when props
@@ -323,12 +462,15 @@ function lintFile(file) {
         // preview axis, literals passed via `Ref with`) — input:true there is false AND
         // load-bearing, since configSchema derives from it. Silence is the error:
         // unflagged props default to INPUTS.
-        const undeclared = Object.entries(json.props ?? {})
+        // The props extract composes first (`props: { $include: props }` — the loader
+        // does the same before any reader sees the map).
+        const undeclared = Object.entries(judgedProps)
           .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.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.
         // Well-formed = { initial?: string, states: { <name>: { layout?/layouts?/on?/
@@ -344,38 +486,53 @@ function lintFile(file) {
               (s.layout === undefined || typeof s.layout === "string"),
           );
         };
-        const viewTree = hasStateBlock && isViewTree(json.state.view) ? json.state.view : null;
+        // THE RULED FORM (2026-08-29): the tree lives at TOP-LEVEL `states:` like
+        // every kind; `state.view` is the legacy wrapper, still read.
+        const topTree = json.states && typeof json.states === "object" && !Array.isArray(json.states) && isViewTree({ states: json.states }) ? { states: json.states } : null;
+        const viewTree = topTree ?? (hasStateBlock && isViewTree(json.state.view) ? json.state.view : null);
 
         // the state block holds SCALAR internal view-state ONLY — an array/object (a
         // finder's result rows) or a URL is content/data slop: hardcode it in the layout,
         // or move workflow-fed data to props (input:true) (AUTHORING §3). The one
         // exception: a well-formed v2 `state.view` tree (STATE_MODEL §5 rule 1).
-        if (hasStateBlock)
-          for (const [k, v] of Object.entries(json.state)) {
-            if (k === "view" && viewTree) continue;
+        const scalarHomes = [];
+        if (hasStateBlock) scalarHomes.push(["state", json.state]);
+        if (json.values && typeof json.values === "object" && !Array.isArray(json.values)) scalarHomes.push(["values", json.values]);
+        for (const [home, blk] of scalarHomes)
+          for (const [k, v] of Object.entries(blk)) {
+            if (home === "state" && k === "view" && viewTree && !topTree) continue; // legacy wrapper only
             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.unoverse.ai/design/components)`);
+              report("error", file, `${home}.${k} is an ${Array.isArray(v) ? "array" : "object"}. The values block is SCALAR starting values 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.unoverse.ai/design/components)`);
+              report("error", file, `${home}.${k} is a URL. Content, not a starting value; hardcode it in the layout (or props input:true if workflow-fed) (docs.unoverse.ai/design/components)`);
           }
 
         if (hasLayouts) {
           const raw = JSON.stringify(json.root ?? {}).replace(/\s/g, "");
-          if (viewTree) {
-            // v2: the tree owns the states; the root switches the PUBLIC axis (`view`).
-            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)`);
+          if (viewTree && json.root == null) {
+            // THE TREE IS THE MACHINE (2026-08-29 late): no authored root — the
+            // compiler synthesizes the Switch from the tree. Nothing to check.
+          } else if (viewTree) {
+            // An AUTHORED root is a real shell (beyond the plain Switch) — it must
+            // still switch the public axis. A root that merely restates the tree is
+            // redundant: delete it and let the compiler synthesize.
+            if ((!raw.includes('"on":"state"') && !raw.includes('"on":"view"')) || !/"\$include":"layouts\//.test(raw))
+              report("error", file, `a tree component's authored root must Switch on "state" (the ruled public-axis word; "view" is the legacy spelling) → $include layouts/<layout> (STATE_MODEL §5)`);
+            const rootObj = json.root ?? {};
+            const kids = Array.isArray(rootObj.children) ? rootObj.children : [];
+            if (rootObj.type === "Box" && kids.length === 1 && kids[0]?.type === "Switch")
+              report("warn", file, `the root is only the tree's Switch restated — delete it; the compiler synthesizes the root from \`states:\` (2026-08-29 ruling)`);
           } 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.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
           // path both derive from them, so cases and layout files must agree exactly.
-          const axis = viewTree ? "view" : "defaultState";
+          const axes = viewTree ? ["state", "view"] : ["defaultState"];
           const findFaceSwitch = (n) => {
             if (!n || typeof n !== "object") return null;
             if (Array.isArray(n)) { for (const c of n) { const r = findFaceSwitch(c); if (r) return r; } return null; }
-            if (n.type === "Switch" && n.on === axis && n.cases && typeof n.cases === "object") return n;
+            if (n.type === "Switch" && axes.includes(n.on) && n.cases && typeof n.cases === "object") return n;
             for (const v of Object.values(n)) { const r = findFaceSwitch(v); if (r) return r; }
             return null;
           };
@@ -414,8 +571,13 @@ function lintFile(file) {
               const layoutName = inc.slice("layouts/".length);
               usedLayouts.add(layoutName);
               // v2: the STATE owns its layout — the tree's declaration decides which
-              // file draws it (same-name by default). Legacy: same-name is the law.
-              const expected = viewTree?.states?.[name]?.layout ?? name;
+              // file draws it. Declarations are root-relative PATHS (2026-08-29
+              // ruling); a bare name still reads as layouts/<name> for the unswept
+              // installed tier.
+              const declaredLayout = viewTree?.states?.[name]?.layout;
+              const expected = declaredLayout
+                ? (declaredLayout.includes("/") ? declaredLayout : `layouts/${declaredLayout}`).replace(/^layouts\//, "")
+                : name;
               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)`
@@ -424,12 +586,16 @@ function lintFile(file) {
             // v2: tree-declared layouts (including nested substates' and variants') are
             // reachable by declaration — seed them so the orphan check knows them.
             if (viewTree) {
+              // Declared values are PATHS (2026-08-29); the orphan set is keyed by
+              // layouts/-relative names, so strip the prefix (bare legacy names
+              // pass through unchanged).
+              const asName = (l) => l.replace(/^layouts\//, "");
               const seed = (states) => {
                 for (const s of Object.values(states ?? {})) {
                   if (!s || typeof s !== "object") continue;
-                  if (typeof s.layout === "string") usedLayouts.add(s.layout);
+                  if (typeof s.layout === "string") usedLayouts.add(asName(s.layout));
                   if (s.layouts && typeof s.layouts === "object")
-                    for (const l of Object.values(s.layouts)) if (typeof l === "string") usedLayouts.add(l);
+                    for (const l of Object.values(s.layouts)) if (typeof l === "string") usedLayouts.add(asName(l));
                   if (s.states) seed(s.states);
                 }
               };
@@ -480,7 +646,7 @@ function lintFile(file) {
               for (const lf of readdirSync(d).filter(isDefFile)) {
                 try {
                   if (/"key":"defaultState"/.test(JSON.stringify(readDef(join(d, lf)))))
-                    report("warn", file, `${sub}/${lf} writes setValue "defaultState" but this component declares a v2 tree — write "view" (the alias is scheduled for deletion) (STATE_MODEL §2)`);
+                    report("warn", file, `${sub}/${lf} writes setValue "defaultState" but this component declares a tree — write "state" (the ruled word; "view"/"defaultState" are legacy) (STATE_MODEL §2)`);
                 } catch { /* that file lints separately */ }
               }
             }

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

@@ -163,8 +163,33 @@ const isHook = (f) => {
   const stem = basename(f).replace(/\.(json|ya?ml)$/, "").toLowerCase();
   return life.some((e) => typeof e === "object" && e && typeof e.handler === "string" && e.handler.toLowerCase() === stem);
 };
+// THE PROPS EXTRACT (UNOVERSE_MCP_FORMS §Per-field purpose): a folder-root file the
+// envelope pulls in with `props: { $include: <stem> }`. It is a props MAP, not a
+// drawing — the node walk must not judge it, and the props rules read it composed.
+const isPropsExtract = (f) => {
+  const dir = dirname(f);
+  const env = defPath(dir, basename(dir));
+  if (!env || env === f) return false;
+  let inc;
+  try { inc = readDef(env).props?.$include; } catch { return false; }
+  if (typeof inc !== "string") return false;
+  return basename(f).replace(/\.(json|ya?ml)$/, "").toLowerCase() === inc.toLowerCase();
+};
 const isManifest = (f) => /^manifest\.(json|yaml)$/.test(basename(f));
-const isAppPath = (f) => f.includes(`${sep}apps${sep}`);
+// WHICH HOME A FILE IS IN — asked of the path BELOW the design root, never the absolute
+// one. Testing the absolute path for an `apps` segment was true of every file in this
+// monorepo, because the design tree itself lives at `apps/unoverse/design`: every
+// component manifest in the repo was linted as an APP manifest (two bogus warnings each,
+// while the real component-manifest rules never ran once). A rule that cannot tell the
+// homes apart is worse than no rule — it trains people to ignore its output.
+const homeSegments = (f) => relative(DESIGN_ROOT, f).split(sep);
+const isAppPath = (f) => homeSegments(f).includes("apps");
+// THE TEMPLATE KIND (UNOVERSE_TEMPLATE_MODEL.md §9b). Its folders answer to different
+// rules than an app's or a component's, so the rules that would misfire have to be able
+// to ask. `isTemplatePart` is the template's OWN components/ folder — flat parts that
+// carry no manifest and declare no state tree, the face being the filename (§9b rule 7).
+const isTemplatePath = (f) => homeSegments(f).includes("templates");
+const isTemplatePart = (f) => isTemplatePath(f) && homeSegments(f).includes("components");
 // The DEFINITION ROOT folder for a file: a bare partial lives one level under it
 // (layouts/ states/ components/ blocks/); every `$include` resolves against it.
 const defRoot = (file) => {
@@ -424,6 +449,22 @@ for (const orgDir of orgDirs) {
     }
   orgComponentNames.set(basename(orgDir), set);
 }
+// TEMPLATE-LOCAL PARTS are addressed `<template>/<part>` (§9b rule 7) — the same
+// qualified shape as `<org>/<name>`, resolved against the template homes. The runtime
+// resolver has always done this (componentDirs' fallback); the lint did not, so a part
+// composing a sibling part read as an unresolvable Ref while it rendered perfectly.
+const templatePartNames = new Map(); // template folder name -> Set(lower part names)
+for (const root of [DS, ...orgDirs]) {
+  const home = join(root, "templates");
+  if (!existsSync(home)) continue;
+  for (const t of readdirSync(home)) {
+    const parts = join(home, t, "components");
+    if (!existsSync(parts)) continue;
+    const set = templatePartNames.get(t.toLowerCase()) ?? new Set();
+    for (const e of readdirSync(parts)) if (isDefFile(e)) set.add(defName(e).toLowerCase());
+    templatePartNames.set(t.toLowerCase(), set);
+  }
+}
 const orgOfFile = (file) => {
   const home = orgDirs.find((d) => file.startsWith(d + sep));
   return home ? basename(home) : null;
@@ -436,9 +477,12 @@ const refResolves = (ref, file) => {
   const fileOrg = file ? orgOfFile(file) : null;
   const slash = lower.indexOf("/");
   if (slash > 0) {
-    const org = lower.slice(0, slash);
-    if (org !== fileOrg) return false; // another org's, or a DS file naming any org
-    return orgComponentNames.get(org)?.has(lower.slice(slash + 1)) ?? false;
+    const qualifier = lower.slice(0, slash);
+    const name = lower.slice(slash + 1);
+    // A template's own part, composing another part of the same template.
+    if (templatePartNames.get(qualifier)?.has(name)) return true;
+    if (qualifier !== fileOrg) return false; // another org's, or a DS file naming any org
+    return orgComponentNames.get(qualifier)?.has(name) ?? false;
   }
   if (atomNames.has(lower) || dsComponentNames.has(lower)) return true;
   return fileOrg ? (orgComponentNames.get(fileOrg)?.has(lower) ?? false) : false;
@@ -564,11 +608,19 @@ for (const [dir, isDir] of keyHomes) {
   }
 }
 
-// definition homes: marketplace components/atoms + each org's templates AND
-// components (same law everywhere — an org component is a component, just org-private)
-const homes = [{ dir: join(DS, "components") }, { dir: join(DS, "atoms") }];
+// definition homes: the marketplace's components/atoms/templates + each org's apps,
+// components and templates (same law everywhere — an org component is a component,
+// just org-private).
+//
+// TEMPLATES ARE A KIND, AND A KIND IS LINTED (2026-08-30). The Template Model's
+// `templates/` folders were never added here, so the entire kind was invisible: an
+// invented token or an off-scale space step inside `<org>/templates/**` reported clean,
+// while the same file under `components/` threw two errors. A home that is not
+// enumerated is a home where every rule is off, silently — and the parts a template
+// carries are ordinary components, so they were never exempt from anything.
+const homes = [{ dir: join(DS, "components") }, { dir: join(DS, "atoms") }, { dir: join(DS, "templates") }];
 for (const orgDir of orgDirs) {
-  for (const sub of ["apps", "components"]) {
+  for (const sub of ["apps", "components", "templates"]) {
     const d = join(orgDir, sub);
     if (existsSync(d) && statSync(d).isDirectory()) homes.push({ dir: d });
   }
@@ -855,12 +907,24 @@ const componentNamesCache = new Map();
 // Components an ORG's template may reference: the marketplace tier + that org's OWN
 // components — never another org's (org-privacy). Cached per org.
 function componentNamesForFile(file) {
-  const m = file.split(`${sep}orgs${sep}`);
-  if (m.length < 2) return null;
-  const org = m[1].split(sep)[0];
+  // THE PROJECT A FILE BELONGS TO, from the path below the design root. This read
+  // `${sep}orgs${sep}` and returned null for anything else, so on the flat layout — which
+  // is every project now (`design/<org>/…`, "flat wins") — it answered "no list" and
+  // every rule that asks it, preview names included, silently stopped checking.
+  const segs = relative(DESIGN_ROOT, file).split(sep);
+  if (segs.length < 2 || segs[0] === "..") return null;
+  const projectSegs = segs[0] === "orgs" ? segs.slice(0, 2) : segs.slice(0, 1);
+  const org = projectSegs.join("/");
   const cached = componentNamesCache.get(org);
   if (cached !== undefined) return cached;
-  const dirs = [join(m[0], "components"), join(m[0], "orgs", org, "components")];
+  const dirs = [
+    join(DS, "components"),
+    join(DESIGN_ROOT, ...projectSegs, "components"),
+    // TEMPLATES ARE PEERS (§9c): a state that holds one seeds it by name like any
+    // component, so the name set a preview is checked against includes them.
+    join(DS, "templates"),
+    join(DESIGN_ROOT, ...projectSegs, "templates"),
+  ];
   let names = null;
   for (const dir of dirs) {
     if (!existsSync(dir)) continue;
@@ -877,7 +941,7 @@ function componentNamesForFile(file) {
   const ctx = {
     DESIGN_ROOT, DS, orgDirs, report, spaceSteps, stepList, checkDimension, checkToken, checkCondition,
     appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists,
-    isFixture, isHook, isManifest, isAppPath, defRoot, readText,
+    isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePath, isTemplatePart, defRoot, readText,
   };
   const walkNode = makeWalkNode(ctx);
   const lintFile = makeLintFile({ ...ctx, walkNode });

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

@@ -33,10 +33,44 @@ export const CONDITION_KEYS = new Set(["field", "eq", "ne", "in"]);
  * Schema halves, so the editor squiggle and the publish gate cannot disagree.
  */
 export const UNIVERSAL_PROPS = new Set([
-  // read for every node before dispatch; `brief` rides the tree for the composer
-  "type", "style", "visibleWhen", "bind", "action", "analytics", "skeleton", "brief", "$include",
+  // read for every node before dispatch. `brief` is GONE (UNOVERSE_AUTHORING §3b, ruled
+  // 2026-08-30): a field's contract lives on its prop, and the layout only arranges.
+  "type", "style", "visibleWhen", "bind", "action", "analytics", "skeleton", "$include",
 ]);
 
+/**
+ * A PROP, whole (UNOVERSE_AUTHORING §3b): JSON Schema's own words plus the platform's
+ * four. Closed, because the prop is now the only place a field's contract can live —
+ * a misspelled `maxlength` there is a limit that silently never applies.
+ */
+export const PROP_KEYS = [
+  "type", "input", "description", "maxLength", "minItems", "maxItems",
+  "hydrate", "optional", "enum", "preview", "default", "items",
+];
+
+/**
+ * THE INTERFACE FIELDS (packages/docs/design/interface-data.md): the names a content row
+ * carries. A row fills a component BY NAME with no mapping layer, so a prop wearing one
+ * of these names is filled by the delivery — whatever the definition declares about it.
+ * Layer 1 arrives with every card; the `service`/`need` editorial fields arrive with the
+ * row that has them; layer 2 arrives when `getDetail` runs.
+ */
+export const INTERFACE_FIELDS = new Set([
+  "universal_id", "title", "description", "object_type", "key_need", "source_url", "source_id",
+  "tagline", "shortDescription", "introParagraph", "callToAction", "actionPrompt", "primaryImage", "images", "action",
+  "bodyCopy", "features", "mainCategory", "section", "needs",
+]);
+
+/**
+ * The keys that only make sense if an AUTHOR, not a delivery, decides the value — a cap,
+ * a count, a closed set. `description` is deliberately NOT one: every prop describes
+ * itself as standard (UNOVERSE_AUTHORING §3b), including the ones a row fills, so
+ * flagging a described `title` would fire on every content card in the estate and teach
+ * people to ignore the rule. What is worth saying is narrower and still true: a LIMIT you
+ * wrote does not apply to a value the delivery brings.
+ */
+export const AUTHORED_CONTROLS = ["maxLength", "minItems", "maxItems", "enum"];
+
 export const PRIMITIVE_PROPS = {
   Box: ["children", "autoScroll", "revealOnStick", "selection", "appWidth"],
   Stack: ["children", "autoScroll", "revealOnStick", "appWidth"],

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

@@ -17,8 +17,14 @@ import { join, dirname, basename, relative, sep } from "node:path";
 import { PRIMITIVES, CONDITION_KEYS, STYLE_KEYS, RAW_VALUE, CHILD_NODE_KEYS, PARTIAL_DIRS, DIMENSION_KEYS, UNIVERSAL_PROPS, PRIMITIVE_PROPS, PRIMITIVE_BINDS } from "./vocabulary.mjs";
 import { isDefFile, defName, defPath, readDef } from "./defs.mjs";
 
+// THE THREE WORDS and the director's closed block (UNOVERSE_TEMPLATE_MODEL.md §9b).
+const SECTION_WORDS = ["static", "copywriter", "director"];
+const DIRECTOR_KEYS = ["state", "limit", "rules", "preview"];
+
 export function makeWalkNode(ctx) {
-  const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, defRoot } = ctx;
+  const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, defRoot } = ctx;
+  // One director per LAYOUT FILE, tracked for this run only (each file is walked once).
+  const directorsSeen = new Map();
 
 function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
   if (Array.isArray(node)) return node.forEach((n) => walkNode(n, file, root, widthCap));
@@ -33,6 +39,81 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     return; // the included file is linted on its own
   }
 
+  // THE THREE WORDS (UNOVERSE_TEMPLATE_MODEL.md §9b): a template layout's parts say HOW
+  // they are filled instead of naming a primitive. They compile to ComponentSlots at
+  // serve time, so the linter checks the authored word here and hands the rest of the
+  // node to the ordinary walk as the slot it becomes.
+  const word = SECTION_WORDS.find((w) => node[w] !== undefined);
+  if (word && node.type === undefined) {
+    if (!isTemplatePath(file))
+      report("error", file, `"${word}:" is template grammar — only a template layout's parts say how they are filled. Apps and components author ComponentSlot directly (UNOVERSE_TEMPLATE_MODEL §9b)`);
+    if (word === "director") {
+      const d = node.director;
+      if (!d || typeof d !== "object" || Array.isArray(d))
+        report("error", file, `"director:" is a block, not a path — no component is ever named there: it is the one part whose content nobody knows at design time (§9b rule 1)`);
+      else {
+        for (const k of Object.keys(d))
+          if (!DIRECTOR_KEYS.includes(k))
+            report("error", file, `director has no "${k}". It reads ${DIRECTOR_KEYS.map((x) => `"${x}"`).join(", ")} (§9b)`);
+        if (d.limit !== undefined && typeof d.limit !== "number")
+          report("error", file, `director.limit is a NUMBER — a hard cap the machine enforces, never trusted to the model (§9b)`);
+        if (d.rules !== undefined && typeof d.rules !== "string")
+          report("error", file, `director.rules is written like a brief: one string of English (§9b)`);
+        if (d.preview !== undefined && (!Array.isArray(d.preview) || d.preview.some((c) => typeof c !== "string")))
+          report("error", file, `director.preview is an array of component names — Studio's stand-ins until a real run exists (§9b rule 6)`);
+        else if (Array.isArray(d.preview)) {
+          const comps = componentNamesForFile(file);
+          for (const c of d.preview)
+            if (comps && !comps.has(String(c).toLowerCase()))
+              report("error", file, `director.preview names unknown component "${c}". No match in the design system or this org's components (lookup is case-insensitive)`);
+        }
+      }
+      // ONE MIND, MANY BANDS (§9b rule 3, amended 2026-08-30): a layout may hold several
+      // directed bands — one verdict, arranged — but each must claim a DISTINCT face, or
+      // the surface is ambiguous (the reaction contract's one-view-one-surface rule). So
+      // on a multi-band layout every director declares its `state:`; two bands claiming
+      // the same face is the error this rule now exists for.
+      const seen = directorsSeen.get(file) ?? [];
+      const face = typeof d?.state === "string" ? d.state : null;
+      if (seen.length && !face)
+        report("error", file, `a second "director:" in this layout declares no "state:". Several bands are allowed — one mind, arranged — but each must claim a DISTINCT face, so every one of them names it (§9b rule 3)`);
+      else if (face && seen.includes(face))
+        report("error", file, `two directed bands claim the face "${face}". A face has exactly one surface, or the active one is ambiguous (§9b rule 3, the reaction contract)`);
+      directorsSeen.set(file, [...seen, face]);
+    } else if (typeof node[word] !== "string") {
+      report("error", file, `"${word}:" links a component by PATH (${word}: components/<part>) — that is what makes it a known part (§9b rule 1)`);
+    } else {
+      const path = node[word];
+      if (!defPath(root, path) && !existsSync(join(root, path)))
+        report("error", file, `${word} "${path}" does not resolve under ${relative(process.cwd(), root)}/ (§9b rule 1)`);
+    }
+    // Everything else on the line rides through to the slot it compiles into. The select
+    // is SYNTHESIZED here exactly as the compiler builds it (a linked part claims its own
+    // face, limit 1; the director's claim is its `state:` pin) so the rest of the walk
+    // sees what will actually be served — and an authored one is the ceremony §9b rule 9
+    // exists to abolish.
+    if (node.select !== undefined)
+      report("error", file, `a template part never authors "select" — the three words compile to the wire primitives at serve time (§9b rule 9)`);
+    const { static: _s, copywriter: _c, director: _d, select: _sel, ...rest } = node;
+    // An unpinned director claims the OWNING STATE's name (arrivals keep their own state
+    // and the template's states react by name — the free grid↔page dance), so the face
+    // comes from whichever state in the envelope declares this layout.
+    const owningState = () => {
+      const env = defPath(root, basename(root));
+      const states = env ? readDef(env)?.states : undefined;
+      if (!states || typeof states !== "object") return undefined;
+      const here = defName(basename(file));
+      return Object.keys(states).find((s) => {
+        const l = states[s]?.layout;
+        return typeof l === "string" && basename(l).toLowerCase() === here.toLowerCase();
+      });
+    };
+    const face = word === "director" ? (node.director?.state ?? owningState()) : String(node[word]).split("/").pop();
+    const limit = word === "director" ? node.director?.limit : 1;
+    const select = { from: "all", ...(face ? { where: { field: "state", eq: face } } : {}), ...(typeof limit === "number" ? { limit } : {}) };
+    return walkNode({ type: "ComponentSlot", select, ...rest }, file, root, widthCap);
+  }
+
   const t = node.type;
   if (typeof t !== "string")
     report("error", file, `node without "type" (and no $include). Every node names a primitive (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
@@ -136,12 +217,12 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
     // PUBLIC state — the `view` axis (`defaultState` = legacy alias) — never to a
     // component's internal state (step/phase/…) which is private to the component.
     // Selecting on any other field reaches past the boundary the whole model rests on.
-    else if (node.select.where && node.select.where.field && node.select.where.field !== "view" && node.select.where.field !== "defaultState")
-      report("warn", file, `reaction surface selects on "${node.select.where.field}". A template reacts to a component's PUBLIC state ("view"; legacy "defaultState"), never its internal state (that is private to the component) (STATE_MODEL §5)`);
+    else if (node.select.where && node.select.where.field && node.select.where.field !== "state" && node.select.where.field !== "view" && node.select.where.field !== "defaultState")
+      report("warn", file, `reaction surface selects on "${node.select.where.field}". A template reacts to a component's PUBLIC state ("state"; legacy "view"/"defaultState"), never its internal state (that is private to the component) (STATE_MODEL §5)`);
     // ONE STATE AT A TIME: the template is in exactly one state, so a surface must
     // 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")
+    else if (node.select.where && (node.select.where.field === "state" || 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.unoverse.ai/design/state)`);
   }