@nadicodeai/ui 12.1.136 → 12.1.138

package/dist/internal/agent-orb.js

@@ -1,5 +1,5 @@
 import { finalizeFrame, MODE_FRAMES, makeProj, radiusScale, resolvePreset, } from "thinking-orbs/engine";
-import { motionPose, nativeSpeed, paintOrbCue, reducedBreath, readOrbTiming, stateSpeed, } from "./agent-orb-motion.js";
+import { motionPose, nativeSpeed, ORB_FRAME_RATE, paintOrbCue, reducedBreath, readOrbTiming, stateSpeed, } from "./agent-orb-motion.js";
 const agentOrbForms = {
     orbit: "working",
     globe: "searching",
@@ -28,14 +28,11 @@ const presenceWeights = {
 const nadiaStripes = ["--nc-identity-azzurro", "--nc-identity-verde", null, "--nc-identity-rosso"];
 const celebrationTokens = ["--nc-acqua-700", "--nc-viola-700", "--nc-warning", "--nc-rosso-700"];
 const statusTokens = { waiting: "--nc-warning-deep", blocked: "--nc-error" };
-const appearanceTokens = [
-    ...celebrationTokens,
-    ...nadiaStripes.filter((token) => token !== null),
-    ...Object.values(statusTokens),
-    "--nc-duration-wait",
-    "--nc-duration-confirm",
-    "--nc-duration-transition",
-];
+/**
+ * WebKit's canvas rejects `color-mix()` in a gradient stop, so a mix is handed
+ * to the canvas as the colour it computes to.
+ */
+const computedColors = new Map();
 /**
  * Sofia's four stripes: cobalto, giallo, the orb's own pigment and arancio, the
  * identity hues Nadia does not wear, so side by side the two carry all six.
@@ -50,6 +47,14 @@ const figureStripes = {
     nadia: nadiaStripes,
     sofia: sofiaStripes,
 };
+const appearanceTokens = [
+    ...celebrationTokens,
+    ...[...nadiaStripes, ...sofiaStripes].filter((token) => token !== null),
+    ...Object.values(statusTokens),
+    "--nc-duration-wait",
+    "--nc-duration-confirm",
+    "--nc-duration-transition",
+];
 /** A stable direction on the unit sphere, the vendor's Fibonacci lattice. */
 function fibonacci(i, n) {
     const y = 1 - (2 * (i + 0.5)) / n;
@@ -120,10 +125,18 @@ function facing(frame, size) {
         dot.x = size - dot.x;
     return frame;
 }
+function detailProfile(drawn) {
+    if (drawn <= 32)
+        return 20;
+    return drawn <= 48 ? 32 : 64;
+}
+function shownState(state, age, motion, timing) {
+    return motion === "ambient" || (state === "done" && age >= timing.doneDuration) ? "idle" : state;
+}
 function paintAgentOrb(context, input) {
     const { form, size, seconds, color, state, age, reduced, breath, celebrationColors, stripeColors, } = input;
     const presence = presenceWeights[input.presence];
-    const preset = resolvePreset(agentOrbForms[form === "nadia" || form === "sofia" ? "ribbon" : form], size <= 32 ? 20 : 64);
+    const preset = resolvePreset(agentOrbForms[form === "nadia" || form === "sofia" ? "ribbon" : form], detailProfile(size));
     const frame = form === "nadia"
         ? stripedRibbonFrame(size, seconds, preset.opts)
         : form === "sofia"
@@ -131,7 +144,7 @@ function paintAgentOrb(context, input) {
             : MODE_FRAMES[preset.mode](size, seconds, preset.opts);
     context.clearRect(0, 0, size, size);
     const done = state === "done" && age >= input.timing.doneDuration;
-    const visualState = input.motion === "ambient" || done ? "idle" : state;
+    const visualState = shownState(state, age, input.motion, input.timing);
     const poseAge = input.motion === "ambient" ? 0 : done ? age - input.timing.doneDuration : age;
     const pose = motionPose(visualState, poseAge, input.timing, reduced);
     const cueAge = done ? age - input.timing.doneDuration : age;
@@ -173,16 +186,137 @@ function paintAgentOrb(context, input) {
         paintOrbCue(context, visualState, size, cueAge, reduced, celebrationColors, "front", breath, input.timing, statusColor);
     }
 }
+function createOrbWatchers(stopped) {
+    const orbs = new Map();
+    const motion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    function changedWithin(roots) {
+        const inside = (canvas) => {
+            for (let node = canvas; node; node = node.parentElement)
+                if (roots.has(node))
+                    return true;
+            return false;
+        };
+        const writes = [...orbs].flatMap(([canvas, orb]) => (inside(canvas) ? [orb.readChange()] : []));
+        for (const write of writes)
+            write?.();
+    }
+    function playAll() {
+        for (const orb of orbs.values())
+            orb.play();
+    }
+    // A browser that cannot tell whether an orb is seen shows it as seen.
+    const visibility = typeof IntersectionObserver === "undefined"
+        ? undefined
+        : new IntersectionObserver((entries) => {
+            for (const entry of entries)
+                orbs.get(entry.target)?.setVisible(entry.isIntersecting);
+        });
+    const appearance = new MutationObserver((records) => {
+        changedWithin(new Set(records.map((record) => record.target)));
+    });
+    appearance.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["class", "style", "data-theme"],
+        subtree: true,
+    });
+    const box = new ResizeObserver((entries) => {
+        const writes = entries.map((entry) => orbs.get(entry.target)?.readResize());
+        for (const write of writes)
+            write?.();
+    });
+    // A colour transition on the canvas or on an element it inherits from hands
+    // the observer the colour the transition starts from, so the orb reads its
+    // colour again when that transition ends. The event bubbles up from where it
+    // ran, never down to the canvas, so it is heard on the document.
+    function settle(event) {
+        if (event.propertyName === "color" && event.target instanceof Node)
+            changedWithin(new Set([event.target]));
+    }
+    function resized() {
+        changedWithin(new Set([document.documentElement]));
+    }
+    document.addEventListener("transitionend", settle, true);
+    motion.addEventListener("change", playAll);
+    document.addEventListener("visibilitychange", playAll);
+    window.addEventListener("resize", resized);
+    return {
+        motion,
+        watch(canvas, orb) {
+            orbs.set(canvas, orb);
+            visibility?.observe(canvas);
+            box.observe(canvas);
+        },
+        unwatch(canvas, orb) {
+            if (orbs.get(canvas) !== orb)
+                return;
+            orbs.delete(canvas);
+            if (orbs.size > 0) {
+                visibility?.unobserve(canvas);
+                box.unobserve(canvas);
+                return;
+            }
+            visibility?.disconnect();
+            appearance.disconnect();
+            box.disconnect();
+            document.removeEventListener("transitionend", settle, true);
+            motion.removeEventListener("change", playAll);
+            document.removeEventListener("visibilitychange", playAll);
+            window.removeEventListener("resize", resized);
+            stopped();
+        },
+    };
+}
+let pageOrbWatchers;
+function createOrbClock() {
+    const running = new Set();
+    let request = 0;
+    function frame(now) {
+        request = 0;
+        for (const orb of [...running])
+            if (!orb(now))
+                running.delete(orb);
+        if (running.size > 0 && request === 0)
+            request = requestAnimationFrame(frame);
+    }
+    return {
+        run(orb) {
+            running.add(orb);
+            if (request === 0)
+                request = requestAnimationFrame(frame);
+        },
+        stop(orb) {
+            running.delete(orb);
+            if (running.size > 0 || request === 0)
+                return;
+            cancelAnimationFrame(request);
+            request = 0;
+        },
+    };
+}
+const orbClock = createOrbClock();
+/**
+ * A display's frames arrive a little early or late, so a paint due within this
+ * many milliseconds is painted on the frame at hand: at 60 Hz a 30 fps orb then
+ * paints every second frame rather than every second or third.
+ */
+const PAINT_SLACK_MS = 4;
+function orbWatchers() {
+    pageOrbWatchers ??= createOrbWatchers(() => {
+        pageOrbWatchers = undefined;
+    });
+    return pageOrbWatchers;
+}
+export const LONGEST_FRAME_SECONDS = 0.1;
 export function mountAgentOrb(canvas, options) {
     const { form, presence = "plain" } = options;
     const context = canvas.getContext("2d");
     if (!context)
         return { destroy() { }, setPaused(_value) { }, setState(_value) { } };
-    const motion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const page = orbWatchers();
+    const { motion } = page;
     let paused = options.paused ?? false;
     let visible = true;
     let disposed = false;
-    let request = 0;
     let seconds = 0.6;
     let age = 0;
     let breath = 0;
@@ -241,11 +375,10 @@ export function mountAgentOrb(canvas, options) {
         return !(state === "blocked" && age >= timing.blockedDuration);
     }
     function tick(now) {
-        request = 0;
         if (!running())
-            return;
+            return false;
         if (previous !== null) {
-            const elapsed = Math.min((now - previous) / 1000, 0.1);
+            const elapsed = Math.min((now - previous) / 1000, LONGEST_FRAME_SECONDS);
             if (motion.matches)
                 breath += elapsed;
             else {
@@ -257,98 +390,92 @@ export function mountAgentOrb(canvas, options) {
             }
         }
         previous = now;
-        if (now - lastPaint >= 1000 / 30 || !running()) {
+        const rate = shownState(state, age, orbMotion, timing) === "idle"
+            ? ORB_FRAME_RATE.resting
+            : ORB_FRAME_RATE.busy;
+        if (now - lastPaint >= 1000 / rate - PAINT_SLACK_MS || !running()) {
             paint();
             lastPaint = now;
         }
-        if (running())
-            request = requestAnimationFrame(tick);
+        return running();
     }
     function play() {
-        cancelAnimationFrame(request);
-        request = 0;
         previous = null;
         paint();
         if (running())
-            request = requestAnimationFrame(tick);
+            orbClock.run(tick);
+        else
+            orbClock.stop(tick);
     }
-    /** WebKit's canvas rejects `color-mix()` in a gradient stop, so a mix is
-     * handed to the canvas as the colour it computes to. */
     function computedColor(declaration) {
+        const known = computedColors.get(declaration);
+        if (known)
+            return known;
         const probe = document.createElement("span");
         probe.hidden = true;
         probe.style.color = declaration;
         (canvas.parentElement ?? document.body).append(probe);
         const resolved = getComputedStyle(probe).color;
         probe.remove();
-        return resolved || color;
-    }
-    function readAppearanceKey(appearance, side) {
-        return [
-            side,
-            window.devicePixelRatio || 1,
-            appearance.color,
-            ...appearanceTokens.map((token) => appearance.getPropertyValue(token)),
-        ].join("|");
+        if (!resolved)
+            return color;
+        computedColors.set(declaration, resolved);
+        return resolved;
     }
-    function refreshIfChanged() {
-        if (readAppearanceKey(getComputedStyle(canvas), measure()) !== appearanceKey)
-            refresh();
+    function readAppearance() {
+        const style = getComputedStyle(canvas);
+        const tokens = new Map(appearanceTokens.map((token) => [token, style.getPropertyValue(token).trim()]));
+        const key = [window.devicePixelRatio || 1, style.color, ...tokens.values()].join("|");
+        return { key, color: style.color, tokens, timing: readOrbTiming(style) };
     }
-    function refresh() {
+    function resize(side) {
         if (disposed || !canvas.isConnected)
             return;
-        painted = measure();
+        painted = side;
         const backing = Math.max(1, Math.round(painted * Math.min(window.devicePixelRatio || 1, 2)));
         canvas.width = backing;
         canvas.height = backing;
         ratio = backing / painted;
-        const appearance = getComputedStyle(canvas);
-        appearanceKey = readAppearanceKey(appearance, painted);
+        play();
+    }
+    function refresh(appearance, side) {
+        appearanceKey = appearance.key;
         color = appearance.color;
-        timing = readOrbTiming(appearance);
+        timing = appearance.timing;
         statusColors = {
-            waiting: computedColor(appearance.getPropertyValue(statusTokens.waiting).trim() || color),
-            blocked: computedColor(appearance.getPropertyValue(statusTokens.blocked).trim() || color),
+            waiting: computedColor(appearance.tokens.get(statusTokens.waiting) || color),
+            blocked: computedColor(appearance.tokens.get(statusTokens.blocked) || color),
         };
-        celebrationColors = celebrationTokens.map((token) => computedColor(`color-mix(in oklch, ${appearance.getPropertyValue(token).trim() || color} 75%, white)`));
-        stripeColors = (figureStripes[form] ?? []).map((token) => (token && appearance.getPropertyValue(token).trim()) || color);
-        play();
+        celebrationColors = celebrationTokens.map((token) => computedColor(`color-mix(in oklch, ${appearance.tokens.get(token) || color} 75%, white)`));
+        stripeColors = (figureStripes[form] ?? []).map((token) => (token && appearance.tokens.get(token)) || color);
+        resize(side);
     }
-    const visibility = new IntersectionObserver(([entry]) => {
-        visible = entry?.isIntersecting ?? false;
-        play();
-    });
-    visibility.observe(canvas);
-    const appearance = new MutationObserver(refreshIfChanged);
-    for (let ancestor = canvas; ancestor; ancestor = ancestor.parentElement) {
-        appearance.observe(ancestor, {
-            attributes: true,
-            attributeFilter: ["class", "style", "data-theme"],
-        });
+    function readResize() {
+        if (disposed || !canvas.isConnected)
+            return undefined;
+        const side = measure();
+        return Math.abs(side - painted) >= 0.5 ? () => resize(side) : undefined;
     }
-    // Layout, not the declared size, decides the pixels, so the box is observed
-    // rather than remounted on: an orb sized by its container stays sharp.
-    const box = new ResizeObserver(() => {
-        if (Math.abs(measure() - painted) >= 0.5)
-            refresh();
-    });
-    box.observe(canvas);
-    // A colour transition on the canvas or on an element it inherits from hands
-    // the observer the colour the transition starts from, so the orb reads its
-    // colour again when that transition ends. The event bubbles up from where it
-    // ran, never down to the canvas, so it is heard on the document.
-    function settle(event) {
-        if (event.propertyName === "color" &&
-            event.target instanceof Node &&
-            event.target.contains(canvas))
-            refreshIfChanged();
+    function readChange() {
+        if (disposed || !canvas.isConnected)
+            return undefined;
+        const appearance = readAppearance();
+        if (appearance.key === appearanceKey)
+            return readResize();
+        const side = measure();
+        return () => refresh(appearance, side);
     }
-    document.addEventListener("transitionend", settle, true);
-    motion.addEventListener("change", play);
-    document.addEventListener("visibilitychange", play);
-    window.addEventListener("resize", refreshIfChanged);
-    refresh();
+    const watched = {
+        readChange,
+        readResize,
+        setVisible(value) {
+            visible = value;
+            play();
+        },
+        play,
+    };
+    page.watch(canvas, watched);
+    readChange()?.();
     return {
         setState(value) {
             state = value;
@@ -362,14 +489,8 @@ export function mountAgentOrb(canvas, options) {
         },
         destroy() {
             disposed = true;
-            cancelAnimationFrame(request);
-            visibility.disconnect();
-            appearance.disconnect();
-            box.disconnect();
-            document.removeEventListener("transitionend", settle, true);
-            motion.removeEventListener("change", play);
-            document.removeEventListener("visibilitychange", play);
-            window.removeEventListener("resize", refreshIfChanged);
+            orbClock.stop(tick);
+            page.unwatch(canvas, watched);
         },
     };
 }

package/dist/showcase/specimens/compositions.js

@@ -64,7 +64,7 @@ const CATALOG = [
         entries: [
             {
                 id: "quotes",
-                mark: { kind: "record", icon: Wrench, tone: "skill" },
+                mark: { kind: "record", icon: Wrench },
                 name: "Write quotes from the price list",
                 description: "Reads listino-2026.xlsx and drafts a quote in the customer's language.",
                 add: { label: "Add skill", onClick: nothing },

package/dist/showcase/specimens/inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../../../src/showcase/specimens/inputs.tsx"],"names":[],"mappings":"AA6BA,iBAAS,gBAAgB,gCAexB;AAED,iBAAS,wBAAwB,gCAqBhC;AAED,iBAAS,sBAAsB,gCAiC9B;AAED,iBAAS,kBAAkB,gCAqC1B;AAED,iBAAS,gBAAgB,gCA2BxB;AAED,iBAAS,cAAc,gCAuCtB;AAqBD,iBAAS,oBAAoB,gCAsD5B;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAoHQ,CAAC"}
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../../../src/showcase/specimens/inputs.tsx"],"names":[],"mappings":"AA6BA,iBAAS,gBAAgB,gCAexB;AAED,iBAAS,wBAAwB,gCAqBhC;AAED,iBAAS,sBAAsB,gCAiC9B;AAED,iBAAS,kBAAkB,gCAqC1B;AAED,iBAAS,gBAAgB,gCA2BxB;AAED,iBAAS,cAAc,gCAuCtB;AAqBD,iBAAS,oBAAoB,gCAoD5B;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAoHQ,CAAC"}

package/dist/showcase/specimens/inputs.js

@@ -54,7 +54,7 @@ function SettingsRowsSpecimen() {
     const [approvals, setApprovals] = useState(true);
     const [reminders, setReminders] = useState(false);
     const [zone, setZone] = useState("Europe/Rome");
-    return (_jsxs("div", { className: "grid gap-6", children: [_jsx(SettingsSection, { description: "Choose which events ask for your attention.", title: "Notifications", children: _jsx(SettingsRows, { kind: "switch", rows: [
+    return (_jsxs("div", { className: "grid gap-6", children: [_jsx(SettingsSection, { description: "Choose which events ask for your attention.", title: "Notifications", children: _jsx(SettingsRows, { rows: [
                         {
                             id: "showcase-rows-approvals",
                             label: "Approvals",
@@ -71,7 +71,7 @@ function SettingsRowsSpecimen() {
                             onCheckedChange: setReminders,
                             name: "reminders",
                         },
-                    ], stateLabels: STATE_LABELS }) }), _jsx(SettingsSection, { description: "Dates and times follow this choice.", title: "Region", children: _jsx(SettingsRows, { kind: "select", rows: [
+                    ], stateLabels: STATE_LABELS }) }), _jsx(SettingsSection, { description: "Dates and times follow this choice.", title: "Region", children: _jsx(SettingsRows, { rows: [
                         {
                             id: "showcase-rows-zone",
                             label: "Time zone",

package/dist/showcase/specimens/status.js

@@ -71,7 +71,7 @@ export const STATUS = {
                         ] }), _jsx(CheckState, { label: "1 check failed", outcome: "failed" })] }), _jsxs("span", { className: "flex items-center gap-3", children: [_jsx("span", { className: "flex-1", children: "Messaging" }), _jsx(CheckState, { label: "All channels connected", outcome: "passed" })] })] })),
     FileTypeIcon: () => (_jsx("div", { className: "grid gap-2 text-sm", children: ["mcp.json", "deploy.sh", "README.md", "schema.sql"].map((path) => (_jsxs("span", { className: "flex items-center gap-2 font-mono", children: [_jsx(FileTypeIcon, { className: "size-4", path: path }), path] }, path))) })),
     Gauge: GaugeSpecimen,
-    IdentityMark: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-4", children: [_jsx(IdentityMark, { kind: "agent", orb: { form: "orbit", color: COBALTO } }), _jsx(IdentityMark, { app: "gmail", kind: "app", logo: composioLogo("gmail") }), _jsx(IdentityMark, { kind: "company", name: "Acme Service & Parts" }), _jsx(IdentityMark, { kind: "company", logo: SAMPLE_LOGO, name: "Studio Rossi" }), _jsx(IdentityMark, { kind: "company", logo: SAMPLE_ICON, name: "Polaris Studio" }), _jsx(IdentityMark, { kind: "person", name: "Ada Rossi" }), _jsx(IdentityMark, { icon: Mail, kind: "record" }), _jsx(IdentityMark, { icon: Wrench, kind: "record", size: 40, tone: "skill" })] })),
+    IdentityMark: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-4", children: [_jsx(IdentityMark, { kind: "agent", orb: { form: "orbit", color: COBALTO } }), _jsx(IdentityMark, { app: "gmail", kind: "app", logo: composioLogo("gmail") }), _jsx(IdentityMark, { kind: "company", name: "Acme Service & Parts" }), _jsx(IdentityMark, { kind: "company", logo: SAMPLE_LOGO, name: "Studio Rossi" }), _jsx(IdentityMark, { kind: "company", logo: SAMPLE_ICON, name: "Polaris Studio" }), _jsx(IdentityMark, { kind: "person", name: "Ada Rossi" }), _jsx(IdentityMark, { icon: Mail, kind: "record" }), _jsx(IdentityMark, { icon: Wrench, kind: "record", size: 40 })] })),
     ModelIdentity: () => (_jsxs("div", { className: "grid gap-2", children: [_jsx(ModelIdentity, { model: "anthropic/claude-opus-5" }), _jsx(ModelIdentity, { model: "openai/gpt-5.6-sol" }), _jsx(ModelIdentity, { model: "x-ai/grok-4.5" })] })),
     ModelMark: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-4", children: [_jsx(ModelMark, { author: "anthropic", name: "Claude Opus 5" }), _jsx(ModelMark, { author: "mistralai", label: "Mistral" })] })),
     PlatformMark: () => (_jsx("div", { className: "flex flex-wrap items-center gap-4 text-sm", children: ["google", "microsoft", "apple", "telegram", "whatsapp", "slack"].map((platform) => (_jsxs("span", { className: "flex items-center gap-2 capitalize", children: [_jsx(PlatformMark, { platform: platform, size: 20 }), platform] }, platform))) })),
@@ -103,7 +103,7 @@ export const STATUS = {
                 action: { label: "Open downloads", onClick: nothing },
             },
         ], title: "Customer setup" })),
-    RecordIdentity: () => (_jsx("div", { className: "max-w-sm", children: _jsx(RecordIdentity, { detail: "Company skill \u00B7 every Agent has it", hint: "skl_0042", mark: { kind: "record", icon: Wrench, tone: "skill" }, name: "Write quotes from the price list" }) })),
+    RecordIdentity: () => (_jsx("div", { className: "max-w-sm", children: _jsx(RecordIdentity, { detail: "Company skill \u00B7 every Agent has it", hint: "skl_0042", mark: { kind: "record", icon: Wrench }, name: "Write quotes from the price list" }) })),
     StatusBadge: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(StatusBadge, { label: "Connected", tone: "success" }), _jsx(StatusBadge, { label: "Waiting for you", since: "2h", tone: "warning" }), _jsx(StatusBadge, { label: "Failed", tone: "danger" }), _jsx(StatusBadge, { label: "Running", tone: "info" }), _jsx(StatusBadge, { label: "Paused", tone: "neutral" })] })),
     ObjectFactValue: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(ObjectFactValue, { kind: "agents", children: "5 active" }), _jsx(ObjectFactValue, { kind: "installations", children: "2" }), _jsx(ObjectFactValue, { kind: "customers", children: "12" })] })),
     Tag: () => (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(Tag, { tone: "blue", children: "Rossi Ottica" }), _jsx(Tag, { tone: "teal", children: "Partner" }), _jsx(Tag, { note: "Your account", quiet: true, children: "Direct customer" })] })),

package/dist/showcase/usage.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.generated.d.ts","sourceRoot":"","sources":["../../src/showcase/usage.generated.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usage.generated.d.ts","sourceRoot":"","sources":["../../src/showcase/usage.generated.ts"],"names":[],"mappings":"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"}

package/dist/showcase/usage.generated.js

@@ -230,7 +230,7 @@ export const USAGE = [
         summary: "A card of one setting that says what changing it does and ends in a footer.",
         when: "One setting a person changes on a SettingsPage or as a section of an ObjectPage: Personal details, Company identity, Notifications. A typed value takes `save`; a switch or a short reversible choice applies at once through its own control's change, with no Save. Also a plan-gated feature, a delete card, one read-only value (an ID in a read-only mono InputGroup with its copy button, no Save), and a paid quantity (its stepper field, the price as the description, a two-fact summary under it).",
         instead: "Read-only facts of an object are a SettingsFactsSection; a table or a list of records is a TableCard; Theme and Language live in the account menu; a record's edit in a list is a RowEditForm.",
-        behaviour: '"Groups related form controls inside a bordered card with optional footer actions." (https://vercel.com/geist/fieldset) Ours: one setting per card: a single SettingsField, the description its only help. A typed value (a name, a URL, a server, a port, a key) gets its own card. A semantic subgroup of related controls inside a field, such as radios or checkboxes, is a `FieldSet` with a `FieldLegend`. One more shape exists, declared by a part and never by classes at the call site. A card of several settings holds SettingsRows, label left and control right, only when every row is a switch or every row is a select. "Use Toggle for a single boolean setting where ON takes effect immediately, like `Password Protection` or `Auto-Cancel Builds`." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: a switch never applies on change; it is a row of the card, a draft until the footer\'s Save, as Vercel\'s settings cards are. A switch blocked from above is shown off and disabled, the footer saying why and never a tooltip. Required: the title and the description. The header\'s actions stand at the title\'s right; on a card narrower than 28 rem they keep the title\'s row and the description runs under both, as Vercel\'s cards read on a phone, and when the title\'s longest word would not fit beside them they move under the title, so they never cover it. The footer\'s left line (`footerHint`, `save.hint`) is optional and specific to the card, never a generic line repeated on every card: a limit, what a value is for, a plan it needs, a link; absent, it is nothing, and a card with neither a line nor a button has no footer. Ours: `save`: a typed value, one card with its own Save in the footer, always visible. The section owns the changed state: Save stays disabled until a field differs from what is saved and says `pendingLabel` while saving with Cancel beside it; a completed save calls `saved`, and the product raises one toast from its catalogue ("Completion toasts follow `{Noun} {past-participle}`: `Blob deleted`, `Domain added`, `Environment variable saved`. Never include `successfully`; the action name implies it." https://vercel.com/geist/toast), and Save returns to disabled, with no saved state in the footer. Ours: the section never raises a toast itself. A failed save keeps every value and shows under its field, or above the footer when no field owns it. `tone` marks a state with a command (a failed payment, a trial ending): a 1px border and a footer tinted in the hue with its line in it, the line saying the condition in words; title, line, fields and buttons stay neutral, an outline secondary then a default primary. A button takes the hue of its command, not of the card: `destructive` (red) for a permanent loss (Delete), `warning` (amber) for a disruptive command that can be undone (Pause, Archive). A delete card is `tone="error"` with the object\'s summary as its body; an archive card is neutral with a `warning` button in the footer. "Use a Note for inline contextual feedback next to the field, card, or section it describes: a region change warning above a region picker, a rate-limit notice next to a usage gauge." (https://vercel.com/geist/note) "One Note per concept." (https://vercel.com/geist/note) Ours: a message about the fields inside is a MessageNotice in the body, the card staying neutral. "Disabled checkboxes still need a Tooltip naming the reason; a greyed box with no explanation reads as a bug." (https://vercel.com/geist/checkbox) Ours: `lockedReason` (Geist\'s disabled wall) is the reason, written as the footer\'s line, not in a tooltip; it keeps the fields in view, inert with muted text, under a not-allowed cursor, the title and line unchanged; `unlock` is the way to get access, left out when nothing the person does unlocks it. A locked section has no `save` and no header `actions`.',
+        behaviour: '"Groups related form controls inside a bordered card with optional footer actions." (https://vercel.com/geist/fieldset) Ours: one setting per card, a single SettingsField with the description its only help, unless the card\'s description covers several settings: then they are its SettingsRows, switches and selects together. A typed value (a name, a URL, a server, a port, a key) gets its own card. A semantic subgroup of related controls inside a field, such as radios or checkboxes, is a `FieldSet` with a `FieldLegend`. Several settings in one card are declared by SettingsRows, never by classes at the call site. "Use Toggle for a single boolean setting where ON takes effect immediately, like `Password Protection` or `Auto-Cancel Builds`." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: a switch never applies on change; it is a row of the card, a draft until the footer\'s Save, as Vercel\'s settings cards are. A switch blocked from above is shown off and disabled, the footer saying why and never a tooltip. Required: the title and the description. The header\'s actions stand at the title\'s right; on a card narrower than 28 rem they keep the title\'s row and the description runs under both, as Vercel\'s cards read on a phone, and when the title\'s longest word would not fit beside them they move under the title, so they never cover it. The footer\'s left line (`footerHint`, `save.hint`) is optional and specific to the card, never a generic line repeated on every card: a limit, what a value is for, a plan it needs, a link; absent, it is nothing, and a card with neither a line nor a button has no footer. Ours: `save`: a typed value, one card with its own Save in the footer, always visible. The section owns the changed state: Save stays disabled until a field differs from what is saved and says `pendingLabel` while saving with Cancel beside it; a completed save calls `saved`, and the product raises one toast from its catalogue ("Completion toasts follow `{Noun} {past-participle}`: `Blob deleted`, `Domain added`, `Environment variable saved`. Never include `successfully`; the action name implies it." https://vercel.com/geist/toast), and Save returns to disabled, with no saved state in the footer. Ours: the section never raises a toast itself. A failed save keeps every value and shows under its field, or above the footer when no field owns it. `tone` marks a state with a command (a failed payment, a trial ending): a 1px border and a footer tinted in the hue with its line in it, the line saying the condition in words; title, line, fields and buttons stay neutral, an outline secondary then a default primary. A button takes the hue of its command, not of the card: `destructive` (red) for a permanent loss (Delete), `warning` (amber) for a disruptive command that can be undone (Pause, Archive). A delete card is `tone="error"` with the object\'s summary as its body; an archive card is neutral with a `warning` button in the footer. "Use a Note for inline contextual feedback next to the field, card, or section it describes: a region change warning above a region picker, a rate-limit notice next to a usage gauge." (https://vercel.com/geist/note) "One Note per concept." (https://vercel.com/geist/note) Ours: a message about the fields inside is a MessageNotice in the body, the card staying neutral. "Disabled checkboxes still need a Tooltip naming the reason; a greyed box with no explanation reads as a bug." (https://vercel.com/geist/checkbox) Ours: `lockedReason` (Geist\'s disabled wall) is the reason, written as the footer\'s line, not in a tooltip; it keeps the fields in view, inert with muted text, under a not-allowed cursor, the title and line unchanged; `unlock` is the way to get access, left out when nothing the person does unlocks it. A locked section has no `save` and no header `actions`.',
         words: '"Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: the description is that helper text for the whole card, and no field has its own. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: a header-switch card\'s description says what turning it on does. The title names the values ("Personal details"); the description says what changing them does, in one line; the footer line is a Learn more link, a limit ("Use 32 characters at most."), what stays unaffected, or what is blocked and why ("Ask an owner to change this."); Save and Saving come from the product\'s catalogue, and so does the toast a `saved` callback raises; a delete card\'s description opens "Permanently delete".',
         access: "\"Provide an accessible name through `children`, `aria-label`, or `aria-labelledby`.\" (https://vercel.com/geist/toggle) Ours: the title is the section's h2 and names the form that saves it, and the header switch. The footer's line is one status, announced politely; a failure under a field marks the control invalid and describes it. Locked fields are inert, so the section's title, description and reason are what a screen reader meets.",
     },
@@ -405,7 +405,7 @@ export const USAGE = [
         family: "Inputs",
         summary: "One setting: its label above its control, and what went wrong under it.",
         when: "The one value of a SettingsSection: a name, an address, a choice, a switch.",
-        instead: "A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only fact is a SettingsFactsSection; several switches or selects in one card are SettingsRows; a switch that is the whole card and applies at once is the section's `headerSwitch`.",
+        instead: "A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only fact is a SettingsFactsSection; several switches and selects in one card are SettingsRows; a switch that is the whole card and applies at once is the section's `headerSwitch`.",
         behaviour: '"Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: label required, no help line: the card\'s description helps, and the (i) `info` is for a part of a value that needs a sentence. The control is 20rem wide under its label (`controlWidth`: `full` for a textarea, `natural` for a segmented control). `control="choice"` puts a checkbox or radio before its sentence; `control="switch"` puts the word for the switch\'s state after it and requires `stateLabel`. "Validate on blur, not on every keystroke; surface the message by passing a string to `error`." (https://vercel.com/geist/input) Ours: a validation `error` updates as the value is corrected, and it or a failed save about this field shows under the control and marks it invalid; colour sits on the control\'s edge and the message, never the label.',
         words: '"Labels are short Title Case nouns: `Project Name`, `Domain`, `Environment Variable Name`." (https://vercel.com/geist/input) Ours: sentence case, a noun for the value ("Display name"). "Validation names the field and the constraint, ends in a period, and skips `please` (`Project name is required.`, `Code must be 6 digits.`)." (https://vercel.com/geist/input) Ours: an error says what to do next; `info.text` is one sentence and `info.label` names its button ("About display name"); a switch shows its state word ("Enabled", "Disabled") beside it.',
         access: '"Don’t wrap a labelled `<Input>` in a `Tooltip`; put the explainer on a sibling icon button so the label stays announced." (https://vercel.com/geist/input) Ours: that sibling button is the (i) `info`. The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, the info and the error are read with it. The info button has its own name and opens on focus.',
@@ -414,10 +414,10 @@ export const USAGE = [
         name: "SettingsRows",
         module: "settings-section",
         family: "Inputs",
-        summary: "Several switches, or several selects, in one card: each row its label on the left and its control on the right.",
-        when: "A card of settings of one kind, all switches or all selects, that the card's one description covers: a project's Git switches, a team's notification channels, a set of defaults.",
-        instead: "One setting is a SettingsField. Fields of different kinds, text boxes among them, are one card each.",
-        behaviour: 'Declares `kind` once; every row is that kind, so a card cannot mix a switch with a select. Required on every row: the label and its `info` (an (i) with its sentence in a tooltip and on the control); no help line sits under a row. A switch row shows its state word beside the switch (`stateLabels`) and is controlled, so the word always follows the switch. Rows stand 16 px apart; below 28rem a row stacks its control under its label. "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) Ours: a switch is a draft the card\'s Save applies.',
+        summary: "Several switches and selects in one card: each row its label on the left and its control on the right.",
+        when: "A card of switches and selects that the card's one description covers: a project's Git switches, a team's notification channels, a set of defaults, how long a computer stays awake beside whether the window goes to the tray.",
+        instead: "One setting is a SettingsField. A text box is a field of its own card.",
+        behaviour: "A row with `options` is a select, a row with `checked` a switch, and a row with `control` draws a control whose usage page puts it in a row, such as ThemeModeSwitcher; a card may hold any of them together, as Vercel's Root Directory card holds its switches; `stateLabels` is required once any row is a switch. Required on every row: the label and its `info` (an (i) with its sentence in a tooltip and on the control); no help line sits under a row. A switch row shows its state word beside the switch (`stateLabels`) and is controlled, so the word always follows the switch. Rows stand 16 px apart; below 28rem a row stacks its control under its label. \"Pair with a form footer only when the setting needs an explicit `Save` step.\" (https://vercel.com/geist/toggle) Ours: a switch is a draft the card's Save applies.",
         words: '"Title Case noun phrase, 1–4 words, naming what is true when ON: `Password Protection`, not `Enable Password Protection`." (https://vercel.com/geist/toggle) Ours: sentence case, a noun for what it controls ("Pull request comments"), the same for a switch as for a select. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: that sentence is `info.text`. "Options are Title Case when short and match canonical branding (`Next.js`, not `NextJS`); keep the same register across the list." (https://vercel.com/geist/select) Ours: a select\'s options are sentence case.',
         access: "Each row's control is named by the row's label and described by its info and its error. The info button has its own name and opens on focus.",
     },
@@ -560,7 +560,7 @@ export const USAGE = [
         summary: "A setting that is on or off.",
         when: '"Use Toggle for a single boolean setting where ON takes effect immediately, like `Password Protection` or `Auto-Cancel Builds`." (https://vercel.com/geist/toggle) Ours: Geist\'s `Toggle` is our `Switch`, inside a settings section.',
         instead: '"Switch to `Checkbox` for a multi-select list, or to `Switch` for 2–3 mutually exclusive views." (https://vercel.com/geist/toggle) Ours: Geist\'s `Switch` is our `SegmentedControl`. Our `Toggle` is a button that stays pressed, and several of them are a `ToggleGroup`. Choosing between named values is a `RadioGroup`.',
-        behaviour: '"`checked` is required and the component is controlled. Own the state and update it from `onChange`." (https://vercel.com/geist/toggle) "Persist on change and surface the result in a `useToasts().success(…)` toast (`Password protection enabled`); don’t leave the user wondering whether the flip stuck." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: `checked` is optional, since a switch also runs uncontrolled with `defaultChecked`; the toast is raised with `showMessageToast`; the reason for a disabled switch is written in the card\'s footer, and it is left off. Always named: `aria-label` or `aria-labelledby`, or an `id` that a `FieldLabel`\'s `htmlFor` points at, and a switch with none of them does not compile. A bare `Switch` is the 28 by 14 px track with an 11 px thumb; `md` is 36 by 20 px and `lg` 40 by 24 px. Colour: off is the input grey, on is ink, and a disabled switch turns grey, on or off, with a greyer thumb and no shadow. Space flips it. On a settings page it is a draft its card\'s footer Save applies, and the product\'s toast confirms the save, in one of two places: in the card\'s body under its label, its state word after it (`SettingsField`\'s `control="switch"`); or at the end of a row of a card of several settings, the label to its left. A failed save keeps the draft and says so under the card.',
+        behaviour: '"`checked` is required and the component is controlled. Own the state and update it from `onChange`." (https://vercel.com/geist/toggle) "Persist on change and surface the result in a `useToasts().success(…)` toast (`Password protection enabled`); don’t leave the user wondering whether the flip stuck." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: `checked` is optional, since a switch also runs uncontrolled with `defaultChecked`; the toast is raised with `showMessageToast`; the reason for a disabled switch is written in the card\'s footer, and it is left off. Always named: `aria-label` or `aria-labelledby`, or an `id` that a `FieldLabel`\'s `htmlFor` points at, and a switch with none of them does not compile. A bare `Switch` is the 28 by 14 px track with an 11 px thumb; `md` is 36 by 20 px and `lg` 40 by 24 px. Colour: off is the input grey, on is cobalto, the thumb white in both themes, and a disabled switch turns grey, on or off, with a greyer thumb and no shadow. Space flips it. On a settings page it is a draft its card\'s footer Save applies, and the product\'s toast confirms the save, in one of two places: in the card\'s body under its label, its state word after it (`SettingsField`\'s `control="switch"`); or at the end of a row of a card of several settings, the label to its left. A failed save keeps the draft and says so under the card.',
         words: '"The label is `children`, not a `label` prop. Title Case noun phrase, 1–4 words, naming what is true when ON: `Password Protection`, not `Enable Password Protection`." (https://vercel.com/geist/toggle) "Render an optional one-sentence description as a sibling under the label that explains ON only." (https://vercel.com/geist/toggle) "Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) "Keep `labelCasing="title"` (the default) so labels match other Title Case surfaces." (https://vercel.com/geist/toggle) "Use `labelCasing="normal"` only when sentence-case content sits inline next to the toggle." (https://vercel.com/geist/toggle) Ours: the label is 12 px at medium weight, in sentence case: *Approvals*, with the card\'s description in one sentence. The state word is a separate word beside the switch, not its name.',
         access: '"Provide an accessible name through `children`, `aria-label`, or `aria-labelledby`." (https://vercel.com/geist/toggle) "Geist warns in development if all three are missing." (https://vercel.com/geist/toggle) "Set `aria-label` only when the visible label sits elsewhere on the row; otherwise let `children` carry it so sighted and screen-reader copy stay aligned." (https://vercel.com/geist/toggle) Ours: `role="switch"` with `aria-checked`, the name the same in both states; a missing name does not compile.',
     },
@@ -580,7 +580,7 @@ export const USAGE = [
         module: "theme-mode-switcher",
         family: "Choices",
         summary: "The three appearances side by side, each with its glyph and its name.",
-        when: "An Appearance setting on a settings page, where the choice has room to show its names.",
+        when: "An Appearance setting on a settings page, where the choice has room to show its names: its own field, or a row of a SettingsRows card, `compact`, beside settings of the same card.",
         instead: "Inside a menu, the same choice is ThemeModeMenu; a choice that is not the appearance is a RadioGroup or a ToggleGroup.",
         behaviour: "Exclusive: one mode is selected; on a settings card the choice is a draft the card's Save applies. The order is System, Light, Dark everywhere.",
         words: 'The setting\'s name, then each mode\'s name from the product\'s catalogue: "System", "Light", "Dark".',
@@ -624,9 +624,9 @@ export const USAGE = [
         module: "agent-orb",
         family: "Status",
         summary: "An Agent, anywhere: her orb, the only thing that moves on its own.",
-        when: 'An Agent, anywhere: 20 in the sidebar, 32 in a row, 64 on her Profile card, 96 in an Agent card, 160 on entry. There is no other Agent picture. The sizes are 20, 24, 32, 40, 64, 96 and 160 px, and no other. On a photograph the orb takes the stronger `presence="over-picture"` weight; everywhere else it is `plain`.',
+        when: "An Agent, anywhere: 20 in the sidebar, 32 in a row, 64 on her Profile card, 96 in an Agent card, 160 on entry. There is no other Agent picture. The sizes are 20, 24, 32, 40, 64, 96 and 160 px, and no other. Detail follows the size the orb is drawn at: up to 32 px it draws the engine's lightest dot profile, at 40 px the middle one and from 64 px the full one, since a small orb cannot show the full profile's dots apart. On a photograph the orb takes the stronger `presence=\"over-picture\"` weight; everywhere else it is `plain`.",
         instead: 'A person is an `Avatar`. The system\'s own wait is the waiting line, never an orb. An orb in artwork, such as a sign-in picture, takes `motion="ambient"` and claims no activity. An orb that stands for an Agent shows her real state.',
-        behaviour: "The only thing that moves on its own. Idle particles turn at 86.4% of the form's native pace, with a separate 6.4 s breath. Working sweeps a ribbon every 3.2 s; thinking passes three pulses over 2.4 s. Waiting leans softly as centered pause bars arrive; blocked recoils as a centered stop sign lands. Both entrances settle over 2 s, then waiting breathes and blocked holds still. Done celebrates once over 4.8 s, then rests at 72% of native particle speed with the Idle breath. A state change interrupts the previous gesture; `motionKey` replays it and `paused` freezes it. A surface that only knows a machine checked in draws idle. No state draws a circle around the orb. Ambient motion moves the form at its own pace with no state pose or cue. Reduced motion: movement stops, a thinking or working orb breathes between full ink and 0.45 opacity so busy still reads as busy, an ambient orb holds still, and waiting and blocked keep their centered signs without an entrance gesture. An orb is one of seven forms, `ribbon`, `lattice`, `orbit`, `globe`, `network`, `braid` and `morph`, in one colour a person chose: cobalto, verde or arancio, or none, which draws it in the text colour. Giallo is not offered because it fails 3:1 on white; rosso is not offered because it is the error red. nadicode's own two Agents are the only ones with a figure nobody chooses, the same at every size and in every state. Nadia is her striped ribbon, the form `nadia`: azzurro, verde, the text colour and rosso along its whole length. Sofia, the Agent that looks up a new company, is her sister, the form `sofia`: the same ribbon turned to face Nadia's, striped cobalto, giallo, the text colour and arancio, the identity hues Nadia does not wear. Neither figure is ever stored as an Agent's look. An Agent's form is stored as `orb:<form>` and its colour as the identity hex or nothing; a template declares its starting look the same way. The stored-appearance resolver reads it: the root Agent always draws as Nadia, an unknown form draws `orbit`, an unknown colour the text colour, and a stored rosso draws arancio. The retired `forma:*` shapes each draw one of the seven forms, so an Agent that chose one before the orbs keeps a distinct look. An Agent's look is a person's choice and is never derived from a name, id or role. A template that names no look is the one exception: `templateAgentOrb` gives it a form and colour fixed by its slug, so the templates in a gallery differ and the Portal and Nadia draw the same one; Nadia and Sofia keep their figures.",
+        behaviour: "The only thing that moves on its own. Idle particles turn at 86.4% of the form's native pace, with a separate 6.4 s breath. Working sweeps a ribbon every 3.2 s; thinking passes three pulses over 2.4 s. Waiting leans softly as centered pause bars arrive; blocked recoils as a centered stop sign lands. Both entrances settle over 2 s, then waiting breathes and blocked holds still. Done celebrates once over 4.8 s, then rests at 72% of native particle speed with the Idle breath. A state change interrupts the previous gesture; `motionKey` replays it and `paused` freezes it. A surface that only knows a machine checked in draws idle. No state draws a circle around the orb. Ambient motion moves the form at its own pace with no state pose or cue. An orb at rest (idle, ambient, or done after its celebration) paints 15 frames a second; every other state, gesture and the celebration paint 30. The pace is the same at either rate. Reduced motion: movement stops, a thinking or working orb breathes between full ink and 0.45 opacity so busy still reads as busy, an ambient orb holds still, and waiting and blocked keep their centered signs without an entrance gesture. An orb is one of seven forms, `ribbon`, `lattice`, `orbit`, `globe`, `network`, `braid` and `morph`, in one colour a person chose: cobalto, verde or arancio, or none, which draws it in the text colour. Giallo is not offered because it fails 3:1 on white; rosso is not offered because it is the error red. nadicode's own two Agents are the only ones with a figure nobody chooses, the same at every size and in every state. Nadia is her striped ribbon, the form `nadia`: azzurro, verde, the text colour and rosso along its whole length. Sofia, the Agent that looks up a new company, is her sister, the form `sofia`: the same ribbon turned to face Nadia's, striped cobalto, giallo, the text colour and arancio, the identity hues Nadia does not wear. Neither figure is ever stored as an Agent's look. An Agent's form is stored as `orb:<form>` and its colour as the identity hex or nothing; a template declares its starting look the same way. The stored-appearance resolver reads it: the root Agent always draws as Nadia, an unknown form draws `orbit`, an unknown colour the text colour, and a stored rosso draws arancio. The retired `forma:*` shapes each draw one of the seven forms, so an Agent that chose one before the orbs keeps a distinct look. An Agent's look is a person's choice and is never derived from a name, id or role. A template that names no look is the one exception: `templateAgentOrb` gives it a form and colour fixed by its slug, so the templates in a gallery differ and the Portal and Nadia draw the same one; Nadia and Sofia keep their figures.",
         words: "Text sits beside the orb, never on it. Where the exact state matters a word names it: *Working*, *Waiting for you*.",
         access: '`role="img"` labelled with the Agent\'s name, and her state where it matters; `decorative` when her name is already beside it.',
     },
@@ -678,8 +678,8 @@ export const USAGE = [
         name: "BrandWordmark",
         module: "brand",
         family: "Status",
-        summary: "The company logo: nadicode in full.",
-        when: "Wherever the company is named by its logo: the Portal's sidebar, the website's header, a footer. `BrandMark`, the plain n, where the name does not fit.",
+        summary: "The wordmark: nadicode in full.",
+        when: "Wherever the company is named: the Portal's sidebar, the website's header, a footer. `BrandMark`, the n, where the company is recognised by its sign or the name does not fit; never the two side by side.",
         instead: "A product's own mark (Nadia, Alveare) is that product's. A platform's is `PlatformMark`. The company named in a sentence is text.",
         behaviour: "The letters take the text colour of what they sit in, so one form serves every ground. The dot is the logo's own colour, which turns to the brighter cobalt under any dark ancestor.",
         words: "None beyond its name, *nadicode*, written as the glossary defines it.",
@@ -714,7 +714,7 @@ export const USAGE = [
         summary: "What says which thing a record is, at a fixed size at the start of its row, its object's head or its feed line: an Agent's orb, an app's logo, a model maker's mark, a company's logo or initials, a person's picture, or a record kind's icon on its tile.",
         when: "The first thing in a record's row (32), at the head of its object page (64), in a feed or a sidebar identity line (24), on a Library entry (40), for the company at the top of Nadia's list (28): wherever it tells a person which thing they are looking at.",
         instead: "An icon beside a card's title, a KPI's label or a section heading only repeats the words and is left out. A picture for a first use or a whole-page moment is the empty state's or the page's own. A model is its `ModelIdentity`; a maker's mark beside a model's name in a list of models is `ModelMark` at 24.",
-        behaviour: "Static, except an Agent's orb, which moves with her state. An Agent is always her real orb from the orb engine, at the largest orb size not above the mark's, with no tile and no ring, never an avatar or a painted circle, and `frame` lets the product wrap that orb, such as in the transition that carries her to her page; an app keeps its own logo in its bordered tile on the page ground, or its first letter when it has no logo; a record that belongs to a model maker, such as a key held at that maker, is the maker's `ModelMark` at the mark's size, with its initials when LobeHub has no mark for it; a company is its own logo, contained whole in its original colours and proportions on a dark ringed tile, as Vercel shows a project's favicon, and until a logo is found, or when the stored logo does not load, its initials in white on that same tile, so a found logo only replaces the letters; a company's mark is the same whatever its standing and whichever directory opened it, and a Partner is said in words where its standing matters, never by a colour; a person is their picture, then their initials, in a round mark; a record with its own object picture, such as a Library skill or plugin, draws that picture on its kind's ground; a record with no picture of its own takes its kind's own icon, the same icon its section has in the navigation (Mail for a mailbox, a server for an MCP server, a key for a password), in a ringed tile on the card ground; a Library skill takes the purple category ground with the Skills icon and a plugin the `info-soft` ground with the Plugins icon, both without a ring, so the ground says which kind it is, and an entry that has its own object picture draws it on that ground in the icon's place. A record tile takes `{rounded.sm}` (6 px) corners, `{rounded.md}` (8 px) at 40 and 64; a company's tile and an app's tile take `{rounded.md}` at every size.",
+        behaviour: "Static, except an Agent's orb, which moves with her state. An Agent is always her real orb from the orb engine, at the largest orb size not above the mark's, with no tile and no ring, never an avatar or a painted circle, and `frame` lets the product wrap that orb, such as in the transition that carries her to her page; an app keeps its own logo in its bordered tile on the page ground, or its first letter when it has no logo; a record that belongs to a model maker, such as a key held at that maker, is the maker's `ModelMark` at the mark's size, with its initials when LobeHub has no mark for it; a company is its own logo, contained whole in its original colours and proportions on a dark ringed tile, as Vercel shows a project's favicon, and until a logo is found, or when the stored logo does not load, its initials in white on that same tile, so a found logo only replaces the letters; a company's mark is the same whatever its standing and whichever directory opened it, and a Partner is said in words where its standing matters, never by a colour; a person is their picture, then their initials, in a round mark; a record with no picture of its own takes its kind's own icon, the same icon its section has in the navigation (Mail for a mailbox, a server for an MCP server, a key for a password), in a ringed tile on the card ground; a skill takes the icon its hub card names, and the Skills icon when it names none, on that same neutral ringed tile, so the icon alone tells one skill from another and no colour stands for the kind; a plugin takes the `info-soft` ground with the Plugins icon, without a ring; a record's own object picture, such as a Library skill's or plugin's, is drawn only at 64, at the head of its own page, on its kind's ground in the icon's place, because at a row's size its detail does not read. A record tile takes `{rounded.sm}` (6 px) corners, `{rounded.md}` (8 px) at 40 and 64; a company's tile and an app's tile take `{rounded.md}` at every size.",
         words: "None of its own: the record's name stands beside it. Initials stand for a company or a person: the first letters of the name's first two words. An app with no logo takes the first letter of its name as a monogram, a model maker with no mark the initials of its slug, and no other kind takes letters.",
         access: "Decorative beside the record's name. Alone, as in a narrow rail, `label` names it.",
     },