@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/design/design-md.mjs

@@ -0,0 +1,793 @@
+/**
+ * lib/design/design-md.mjs — the brand foundation, rendered as DESIGN.md and
+ * PRODUCT.md (WP-M7 mechanic 4).
+ *
+ * WHAT THIS IS FOR. Every design skill on a seat (vendored or authored) is told
+ * to read `$AGENT_ROOT/DESIGN.md` before it picks a colour, a typeface or a
+ * radius. That file must therefore be a faithful, mechanical projection of the
+ * workspace's SAVED brand foundation — `branding.getFoundation` / the
+ * `design_foundation` tool — in the shape the ecosystem already reads: the
+ * google-labs-code/design.md spec (YAML frontmatter carrying `colors`,
+ * `typography`, `rounded`, `spacing` and `components` written with
+ * `{colors.primary}`-style refs, then prose).
+ *
+ * PURE. Everything that could differ between two runs is injected: there is no
+ * clock read, no `process.env`, no filesystem and no network here. Given the
+ * same `(foundation, opts)` it returns the same bytes — which is what makes the
+ * CLI's "re-running with an unchanged foundation rewrites nothing" claim
+ * checkable by comparing rendered bytes, and what makes the golden test honest.
+ *
+ * TOLERANT BY CONTRACT. The foundation is a stored JSON blob that a newer hq
+ * may extend (hq's own `coerceFoundation` is deliberately lenient for the same
+ * reason). A key this renderer does not model is NOT dropped: it lands in the
+ * "Additional tokens" section verbatim, so a token added upstream is visible to
+ * a designer on the seat the day it ships, before anyone teaches this module
+ * about it. Silence is the failure mode worth engineering against — a dropped
+ * token looks exactly like a token that was never set.
+ *
+ * Node builtins only (none needed). ESM.
+ *
+ * @module lib/design/design-md
+ */
+
+"use strict";
+
+/**
+ * Top-level foundation keys this renderer EMITS somewhere. Anything else is
+ * "additional" — see the module docstring.
+ *
+ * "Models" means emits, not "recognises". `examples` is a real hq field
+ * (`z.any()` in `brandFoundationSchema`) that no renderer here reads, so it is
+ * deliberately ABSENT from this list and lands in "Additional tokens" verbatim.
+ * Listing a key here that nothing emits is how a token gets dropped in silence
+ * — the one failure this module is built to make impossible.
+ * @type {string[]}
+ */
+export const KNOWN_FOUNDATION_KEYS = [
+  "v",
+  "colors",
+  "fonts",
+  "type",
+  "space",
+  "radii",
+  "shadow",
+  "border",
+  "voice",
+  "positioning",
+  "taglines",
+  "toneTraits",
+  "logos",
+  "visualLanguage",
+  "system",
+];
+
+/**
+ * `system.*` sub-keys this renderer emits (DESIGN.md, except `voice` which is
+ * PRODUCT.md's). `system` is a known TOP-LEVEL key, so without this list an
+ * unmodelled sub-block — `system.imagery` was exactly this — would be invisible
+ * to "Additional tokens" as well as to the prose. Keep in step with hq
+ * `src/lib/branding/foundation.ts#brandSystemSchema`.
+ * @type {string[]}
+ */
+export const KNOWN_SYSTEM_KEYS = [
+  "typography",
+  "color",
+  "imagery",
+  "motifs",
+  "iconography",
+  "layoutPrinciples",
+  "voice",
+];
+
+/**
+ * `visualLanguage.*` sub-keys this renderer emits. Same reasoning as
+ * {@link KNOWN_SYSTEM_KEYS}; mirrors hq's `visualLanguageSchema`.
+ * @type {string[]}
+ */
+export const KNOWN_VISUAL_LANGUAGE_KEYS = [
+  "v",
+  "source",
+  "imagery",
+  "iconography",
+  "motion",
+  "texture",
+  "guardrails",
+  "promptSeed",
+  "seedLocked",
+  "negativeSeed",
+  "references",
+];
+
+/** Canonical colour ROLES a component ref may name, in preference order. */
+const COLOR_ROLES = [
+  "primary",
+  "secondary",
+  "accent",
+  "ink",
+  "paper",
+  "muted",
+  "line",
+  "background",
+  "foreground",
+];
+
+// ── small pure helpers ──────────────────────────────────────────────────────
+
+/** Is this a plain object (not null, not an array)? */
+function isObj(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** An array, or []. */
+function arr(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+/** A trimmed non-empty string, or "". */
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : "";
+}
+
+/**
+ * A token name → a YAML/ref-safe key. `"Primary · Moss"` → `"primary-moss"`,
+ * `"2xl"` → `"2xl"`. Empty input yields `""` so the caller can skip it.
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function slugToken(name) {
+  return String(name ?? "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Double-quote a scalar for YAML, escaping backslashes and quotes. */
+function q(v) {
+  return `"${String(v ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** A dimension token value: numbers become px, strings pass through. */
+function dim(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return `${v}px`;
+  return str(v);
+}
+
+/** `[key, value]` pairs of an ordered map, as YAML lines at `indent`. */
+function yamlMap(pairs, indent) {
+  return pairs.map(([k, v]) => `${indent}${k}: ${q(v)}`);
+}
+
+/**
+ * Insert into an ordered map only when the key is free and the value real.
+ * First writer wins — the foundation's own palette outranks a derived alias.
+ */
+function put(map, key, value) {
+  const k = slugToken(key);
+  const v = str(value);
+  if (!k || !v || Object.prototype.hasOwnProperty.call(map, k)) return;
+  map[k] = v;
+}
+
+// ── token extraction ────────────────────────────────────────────────────────
+
+/**
+ * The `colors` block: every palette entry by slugified name, then the canonical
+ * role aliases a component ref can name (`primary`, `accent`, …) resolved from
+ * `system.color.roles` and, failing that, from a `"<role> · <shade>"` palette
+ * name. Also folds in `system.color.semantic` and `system.color.neutralRamp`,
+ * which are real tokens no other block would carry.
+ *
+ * @param {object} foundation
+ * @returns {{light:Record<string,string>, dark:Record<string,string>}}
+ */
+export function colorTokens(foundation) {
+  const light = {};
+  const dark = {};
+  for (const c of arr(foundation && foundation.colors)) {
+    if (!isObj(c)) continue;
+    const key = slugToken(c.name);
+    if (!key) continue;
+    put(light, key, c.value);
+    if (str(c.dark)) put(dark, key, c.dark);
+  }
+  const roles = isObj(foundation && foundation.system) && isObj(foundation.system.color) ? foundation.system.color.roles : null;
+  if (isObj(roles)) {
+    for (const role of ["primary", "secondary", "accent"]) {
+      const r = roles[role];
+      if (!isObj(r)) continue;
+      put(light, role, r.value);
+      if (str(r.dark)) put(dark, role, r.dark);
+    }
+  }
+  // Alias `primary` → `primary-moss` etc. so `{colors.primary}` always resolves
+  // on a palette that names its shades.
+  for (const role of COLOR_ROLES) {
+    if (light[role]) continue;
+    const hit = Object.keys(light).find((k) => k.startsWith(`${role}-`));
+    if (hit) {
+      light[role] = light[hit];
+      if (dark[hit]) dark[role] = dark[hit];
+    }
+  }
+  const colorBlock = isObj(foundation && foundation.system) ? foundation.system.color : null;
+  if (isObj(colorBlock)) {
+    if (isObj(colorBlock.semantic)) {
+      for (const [name, value] of Object.entries(colorBlock.semantic)) {
+        const k = slugToken(name);
+        if (!k) continue;
+        put(light, Object.prototype.hasOwnProperty.call(light, k) ? `semantic-${k}` : k, value);
+      }
+    }
+    for (const step of arr(colorBlock.neutralRamp)) {
+      if (!isObj(step)) continue;
+      put(light, `neutral-${slugToken(step.step)}`, step.value);
+    }
+  }
+  return { light, dark };
+}
+
+/**
+ * A `[{name, value}]` token array → an ordered map of slug → dimension string.
+ * @param {unknown} list
+ * @returns {Record<string,string>}
+ */
+export function scaleTokens(list) {
+  const out = {};
+  for (const t of arr(list)) {
+    if (!isObj(t)) continue;
+    put(out, t.name, dim(t.value));
+  }
+  return out;
+}
+
+/**
+ * The `typography` block: the three faces plus the role scale.
+ * @param {object} foundation
+ * @returns {{faces:Record<string,string>, scale:Array<{key:string, size:string, weight:string, leading:string, tracking:string}>}}
+ */
+export function typographyTokens(foundation) {
+  const fonts = isObj(foundation && foundation.fonts) ? foundation.fonts : {};
+  const faces = {};
+  for (const role of ["display", "heading", "body", "mono"]) {
+    if (str(fonts[role])) faces[role] = str(fonts[role]);
+  }
+  const families = isObj(foundation && foundation.system) && isObj(foundation.system.typography)
+    ? foundation.system.typography.families
+    : null;
+  if (isObj(families)) {
+    for (const role of ["display", "heading", "body", "mono"]) {
+      if (faces[role]) continue;
+      const f = families[role];
+      if (isObj(f) && str(f.family)) faces[role] = str(f.family);
+    }
+  }
+  // WHERE LEADING AND TRACKING ACTUALLY LIVE. `foundation.type` is hq's
+  // `typeRoleSchema` — `{role, size, weight}`, and nothing else, ever. The
+  // line-height and letter-spacing a workspace tunes are carried by
+  // `system.typography.scale` (`{role, size, weight, leading, tracking}`), a
+  // separate array keyed by the same role names. Reading them off `type` was
+  // dead code: the fields are never there. So the two are merged by role —
+  // `type` wins on size/weight (it is the block the Design surface writes),
+  // the system scale supplies leading/tracking and any role `type` omits.
+  const systemScale = isObj(foundation && foundation.system) && isObj(foundation.system.typography)
+    ? arr(foundation.system.typography.scale)
+    : [];
+  const bySystemRole = new Map();
+  for (const t of systemScale) {
+    if (!isObj(t)) continue;
+    const key = slugToken(t.role);
+    if (!key || bySystemRole.has(key)) continue;
+    bySystemRole.set(key, t);
+  }
+  const num = (v) => (Number.isFinite(v) ? String(v) : "");
+  const seen = new Set();
+  const scale = [];
+  for (const t of arr(foundation && foundation.type)) {
+    if (!isObj(t)) continue;
+    const key = slugToken(t.role);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    const sys = bySystemRole.get(key) || {};
+    scale.push({
+      key,
+      size: dim(t.size) || dim(sys.size),
+      weight: num(t.weight) || num(sys.weight),
+      leading: num(sys.leading),
+      tracking: num(sys.tracking),
+    });
+  }
+  for (const [key, sys] of bySystemRole) {
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const row = { key, size: dim(sys.size), weight: num(sys.weight), leading: num(sys.leading), tracking: num(sys.tracking) };
+    if (row.size || row.weight || row.leading || row.tracking) scale.push(row);
+  }
+  return { faces, scale };
+}
+
+/**
+ * Resolve a `{group.key}` ref against a token map, preferring the named keys
+ * and falling back to the map's first key. `null` when the group is empty — the
+ * caller then omits the field rather than emitting a ref that resolves to
+ * nothing, which is the one thing worse than an absent component field.
+ * @param {string} group
+ * @param {Record<string,string>} map
+ * @param {string[]} prefer
+ * @returns {string|null}
+ */
+export function tokenRef(group, map, prefer) {
+  const keys = Object.keys(map || {});
+  if (keys.length === 0) return null;
+  const hit = (prefer || []).find((p) => keys.includes(p)) || keys[0];
+  return `{${group}.${hit}}`;
+}
+
+/**
+ * The `components` block: the four primitives every design skill reaches for,
+ * written entirely as refs so a token change propagates without touching them.
+ * A field whose ref cannot resolve is omitted (see {@link tokenRef}).
+ * @param {{colors:Record<string,string>, rounded:Record<string,string>, spacing:Record<string,string>, shadow:Record<string,string>, border:Record<string,string>, faces:Record<string,string>}} t
+ * @returns {Array<[string, Array<[string,string]>]>}
+ */
+export function componentRefs(t) {
+  const c = (prefer) => tokenRef("colors", t.colors, prefer);
+  const r = (prefer) => tokenRef("rounded", t.rounded, prefer);
+  const s = (prefer) => tokenRef("spacing", t.spacing, prefer);
+  const sh = (prefer) => tokenRef("shadow", t.shadow, prefer);
+  const b = (prefer) => tokenRef("border", t.border, prefer);
+  const f = (prefer) => tokenRef("typography", t.faces, prefer);
+  const pad = (a, bb) => {
+    const one = s(a);
+    const two = s(bb);
+    return one && two ? `${one} ${two}` : one || two;
+  };
+  const spec = [
+    ["button", [
+      ["background", c(["primary"])],
+      ["foreground", c(["paper", "background"])],
+      ["radius", r(["pill", "chip"])],
+      ["padding", pad(["sm", "xs"], ["lg", "md"])],
+      ["font", f(["body"])],
+    ]],
+    ["card", [
+      ["background", c(["paper", "background"])],
+      ["foreground", c(["ink", "foreground"])],
+      ["border", b(["hairline"])],
+      ["radius", r(["card"])],
+      ["padding", s(["xl", "lg"])],
+      ["shadow", sh(["md", "sm"])],
+    ]],
+    ["input", [
+      ["background", c(["paper", "background"])],
+      ["border", b(["hairline"])],
+      ["radius", r(["field", "chip"])],
+      ["padding", pad(["sm", "xs"], ["md", "sm"])],
+      ["font", f(["body"])],
+    ]],
+    ["surface", [
+      ["background", c(["paper", "background"])],
+      ["foreground", c(["ink", "foreground"])],
+      ["muted", c(["muted"])],
+      ["radius", r(["modal", "card"])],
+    ]],
+  ];
+  return spec
+    .map(([name, fields]) => [name, fields.filter(([, v]) => !!v)])
+    .filter(([, fields]) => fields.length > 0);
+}
+
+/**
+ * Foundation keys this renderer does not emit, in stable key order — the thing
+ * the "Additional tokens" section exists to make visible.
+ *
+ * Nested one level into `system` and `visualLanguage` as well, reported as
+ * dotted paths (`"system.imagery"`). Those two are the blocks hq actually
+ * grows, and a top-level-only sweep calls the whole of `system` "modelled"
+ * while a new sub-block inside it vanishes. One level is deliberate: it covers
+ * every sub-block hq defines today without turning the guarantee into a
+ * recursive diff of two schemas.
+ *
+ * @param {object} foundation
+ * @returns {Array<[string, unknown]>}
+ */
+export function additionalTokens(foundation) {
+  if (!isObj(foundation)) return [];
+  const out = Object.keys(foundation)
+    .filter((k) => !KNOWN_FOUNDATION_KEYS.includes(k))
+    .sort()
+    .map((k) => [k, foundation[k]]);
+  for (const [block, known] of [["system", KNOWN_SYSTEM_KEYS], ["visualLanguage", KNOWN_VISUAL_LANGUAGE_KEYS]]) {
+    const v = foundation[block];
+    if (!isObj(v)) continue;
+    for (const k of Object.keys(v).filter((key) => !known.includes(key)).sort()) {
+      out.push([`${block}.${k}`, v[k]]);
+    }
+  }
+  return out;
+}
+
+// ── prose helpers ───────────────────────────────────────────────────────────
+
+/** A markdown bullet list, or [] when there is nothing real to list. */
+function bullets(list, map = (x) => str(x)) {
+  return arr(list).map(map).filter(Boolean).map((line) => `- ${line}`);
+}
+
+/** `key: value` lines for a plain object's string-ish fields. */
+function fieldLines(obj, fields) {
+  const out = [];
+  for (const [key, label] of fields) {
+    const v = obj ? obj[key] : undefined;
+    if (Array.isArray(v)) {
+      const items = v.map((x) => str(x)).filter(Boolean);
+      if (items.length) out.push(`- **${label}:** ${items.join(", ")}`);
+    } else if (typeof v === "number" && Number.isFinite(v)) {
+      out.push(`- **${label}:** ${v}`);
+    } else if (typeof v === "boolean") {
+      out.push(`- **${label}:** ${v ? "yes" : "no"}`);
+    } else if (str(v)) {
+      out.push(`- **${label}:** ${str(v)}`);
+    }
+  }
+  return out;
+}
+
+/** Drop trailing blank lines and end with exactly one newline. */
+function finish(lines) {
+  const out = [...lines];
+  while (out.length && out[out.length - 1] === "") out.pop();
+  return `${out.join("\n")}\n`;
+}
+
+/** The provenance footer both files carry. Everything here is injected. */
+function provenance(opts) {
+  const o = isObj(opts) ? opts : {};
+  const lines = [];
+  if (str(o.versionLabel)) lines.push(`- **Version:** ${str(o.versionLabel)}`);
+  if (str(o.versionId)) lines.push(`- **Version id:** ${str(o.versionId)}`);
+  if (str(o.generatedAt)) lines.push(`- **Synced:** ${str(o.generatedAt)}`);
+  lines.push(`- **Source:** ${str(o.source) || "cohort · branding.getFoundation"}`);
+  return lines;
+}
+
+// ── the two renderers ───────────────────────────────────────────────────────
+
+/**
+ * Render DESIGN.md — the token contract.
+ *
+ * @param {object} foundation the saved brand foundation (`branding.getFoundation` → `result.foundation`)
+ * @param {object} [opts]
+ * @param {string} [opts.name]          workspace/brand name for the heading
+ * @param {string} [opts.generatedAt]   ISO string; INJECTED (this module never reads a clock)
+ * @param {string} [opts.versionId]     `headVersionId` from the read
+ * @param {string} [opts.versionLabel]  human label of that version
+ * @param {string} [opts.source]        provenance line
+ * @returns {string} the file's bytes
+ */
+export function renderDesignMd(foundation, opts = {}) {
+  const f = isObj(foundation) ? foundation : {};
+  const o = isObj(opts) ? opts : {};
+  const name = str(o.name) || "Workspace";
+  const { light, dark } = colorTokens(f);
+  const rounded = scaleTokens(f.radii);
+  const spacing = scaleTokens(f.space);
+  const shadow = scaleTokens(f.shadow);
+  const border = scaleTokens(f.border);
+  const { faces, scale } = typographyTokens(f);
+
+  const fm = ["---", `name: ${q(name)}`];
+  if (str(o.versionId)) fm.push(`version: ${q(o.versionId)}`);
+  if (str(o.generatedAt)) fm.push(`generatedAt: ${q(o.generatedAt)}`);
+  fm.push(`source: ${q(str(o.source) || "cohort · branding.getFoundation")}`);
+
+  fm.push("colors:");
+  const lightPairs = Object.entries(light);
+  if (lightPairs.length) fm.push(...yamlMap(lightPairs, "  "));
+  else fm.push("  {}");
+  if (Object.keys(dark).length) {
+    fm.push("colorsDark:");
+    fm.push(...yamlMap(Object.entries(dark), "  "));
+  }
+
+  fm.push("typography:");
+  if (Object.keys(faces).length) fm.push(...yamlMap(Object.entries(faces), "  "));
+  if (scale.length) {
+    fm.push("  scale:");
+    for (const row of scale) {
+      const parts = [];
+      if (row.size) parts.push(`size: ${q(row.size)}`);
+      if (row.weight) parts.push(`weight: ${row.weight}`);
+      if (row.leading) parts.push(`leading: ${row.leading}`);
+      if (row.tracking) parts.push(`tracking: ${row.tracking}`);
+      fm.push(`    ${row.key}: { ${parts.join(", ")} }`);
+    }
+  }
+  if (!Object.keys(faces).length && !scale.length) fm.push("  {}");
+
+  for (const [label, map] of [["rounded", rounded], ["spacing", spacing], ["shadow", shadow], ["border", border]]) {
+    fm.push(`${label}:`);
+    const pairs = Object.entries(map);
+    if (pairs.length) fm.push(...yamlMap(pairs, "  "));
+    else fm.push("  {}");
+  }
+
+  const components = componentRefs({ colors: light, rounded, spacing, shadow, border, faces });
+  fm.push("components:");
+  if (components.length) {
+    for (const [comp, fields] of components) {
+      fm.push(`  ${comp}:`);
+      fm.push(...yamlMap(fields, "    "));
+    }
+  } else {
+    fm.push("  {}");
+  }
+  fm.push("---");
+
+  const body = [
+    "",
+    `# ${name} — design system`,
+    "",
+    "The frontmatter above is the token contract: it is generated from the workspace's",
+    "saved brand foundation and is the source of truth for colour, type, radius and",
+    "spacing. Read it before you pick a value. Component entries are written as",
+    "`{group.key}` refs, so changing a token changes every component that names it.",
+    "",
+    "This file is GENERATED — edits here are overwritten on the next sync. To change",
+    "the foundation itself, propose the change (`design_propose_change`); a human",
+    "reviews and applies it, and the next sync brings it back down.",
+    "",
+  ];
+
+  body.push("## Palette", "");
+  if (lightPairs.length) {
+    for (const [k, v] of lightPairs) {
+      body.push(`- \`{colors.${k}}\` — ${v}${dark[k] ? ` (dark ${dark[k]})` : ""}`);
+    }
+  } else {
+    body.push("_No palette in the foundation._");
+  }
+  body.push("");
+
+  body.push("## Typography", "");
+  if (Object.keys(faces).length) {
+    for (const [role, family] of Object.entries(faces)) body.push(`- **${role}:** ${family}`);
+  }
+  if (scale.length) {
+    body.push("");
+    for (const row of scale) {
+      const bits = [
+        row.size,
+        row.weight ? `weight ${row.weight}` : "",
+        row.leading ? `leading ${row.leading}` : "",
+        row.tracking ? `tracking ${row.tracking}` : "",
+      ].filter(Boolean).join(" · ");
+      body.push(`- \`{typography.scale.${row.key}}\` — ${bits}`);
+    }
+  }
+  if (!Object.keys(faces).length && !scale.length) body.push("_No typography in the foundation._");
+  body.push("");
+
+  const usage = isObj(f.system) && isObj(f.system.typography) ? f.system.typography : null;
+  const typeRules = bullets(usage && usage.usageRules);
+  if (str(usage && usage.pairingRationale) || typeRules.length) {
+    body.push("### Type rules", "");
+    if (str(usage.pairingRationale)) body.push(str(usage.pairingRationale), "");
+    if (typeRules.length) body.push(...typeRules, "");
+  }
+  const colorRules = bullets(isObj(f.system) && isObj(f.system.color) ? f.system.color.usageRules : null);
+  if (colorRules.length) body.push("### Colour rules", "", ...colorRules, "");
+
+  // VISUAL LANGUAGE — assembled first, emitted only if it has content, so a
+  // present-but-empty `visualLanguage` does not leave a bare heading behind.
+  //
+  // TWO SOURCES, ONE SECTION. `visualLanguage.imagery` is the art-direction
+  // block the Design surface writes; `system.imagery` is the brand system's own
+  // (medium / style / treatment / mood / subjects / donts). They are different
+  // hq schemas and a workspace can carry either or both — rendering only the
+  // first is how `system.imagery` came to be dropped in silence.
+  const vlLines = [];
+  const vl = isObj(f.visualLanguage) ? f.visualLanguage : {};
+  const vlImagery = isObj(vl.imagery) ? vl.imagery : {};
+  const img = fieldLines(vlImagery, [
+    ["needsImagery", "Uses imagery"],
+    ["medium", "Medium"],
+    ["secondaryMedia", "Secondary media"],
+    ["colorGrade", "Grade"],
+    ["grain", "Grain"],
+    ["crop", "Crop"],
+    ["aspectRatios", "Aspect ratios"],
+    ["subjects", "Subjects"],
+    ["mood", "Mood"],
+    ["composition", "Composition"],
+  ]);
+  const duo = isObj(vlImagery.duotone) ? vlImagery.duotone : null;
+  if (duo && (str(duo.shadow) || str(duo.highlight))) {
+    img.push(`- **Duotone:** ${[str(duo.shadow) && `shadow ${str(duo.shadow)}`, str(duo.highlight) && `highlight ${str(duo.highlight)}`].filter(Boolean).join(" · ")}`);
+  }
+  if (img.length) vlLines.push("### Imagery", "", ...img, "");
+  const sysImagery = fieldLines(isObj(f.system) && isObj(f.system.imagery) ? f.system.imagery : {}, [
+    ["medium", "Medium"],
+    ["style", "Style"],
+    ["treatment", "Treatment"],
+    ["mood", "Mood"],
+    ["subjects", "Subjects"],
+    ["donts", "Avoid"],
+  ]);
+  if (sysImagery.length) vlLines.push("### Imagery (brand system)", "", ...sysImagery, "");
+  const icon = fieldLines(isObj(vl.iconography) ? vl.iconography : {}, [
+    ["style", "Style"],
+    ["weight", "Weight"],
+    ["corner", "Corner"],
+    ["grid", "Grid"],
+    ["notes", "Notes"],
+  ]);
+  if (icon.length) vlLines.push("### Iconography", "", ...icon, "");
+  const motion = fieldLines(isObj(vl.motion) ? vl.motion : {}, [
+    ["character", "Character"],
+    ["easing", "Easing"],
+    ["durationMs", "Duration (ms)"],
+    ["principles", "Principles"],
+  ]);
+  if (motion.length) vlLines.push("### Motion", "", ...motion, "");
+  const texture = fieldLines(isObj(vl.texture) ? vl.texture : {}, [
+    ["surfaces", "Surfaces"],
+    ["background", "Background"],
+    ["notes", "Notes"],
+  ]);
+  if (texture.length) vlLines.push("### Texture", "", ...texture, "");
+  const guards = isObj(vl.guardrails) ? vl.guardrails : {};
+  const dos = bullets(guards.dos);
+  const donts = bullets(guards.donts);
+  if (dos.length || donts.length) {
+    vlLines.push("### Guardrails", "");
+    if (dos.length) vlLines.push("Do:", "", ...dos, "");
+    if (donts.length) vlLines.push("Do not:", "", ...donts, "");
+  }
+  // The image-generation seeds and the block's own provenance. Modelled here
+  // rather than left to "Additional tokens" because they are what an image
+  // prompt is actually built from.
+  const vlMeta = fieldLines(vl, [
+    ["promptSeed", "Prompt seed"],
+    ["seedLocked", "Seed locked"],
+    ["negativeSeed", "Negative seed"],
+    ["references", "References"],
+    ["source", "Source"],
+    ["v", "Schema version"],
+  ]);
+  if (vlMeta.length) vlLines.push("### Generation seeds", "", ...vlMeta, "");
+  if (vlLines.length) body.push("## Visual language", "", ...vlLines);
+
+  const layout = bullets(isObj(f.system) ? f.system.layoutPrinciples : null);
+  if (layout.length) body.push("## Layout principles", "", ...layout, "");
+
+  const logos = isObj(f.logos) ? f.logos : null;
+  if (logos) {
+    const slots = Object.entries(logos)
+      .filter(([, v]) => str(v))
+      .map(([k]) => `- \`${k}\` — set`);
+    if (slots.length) body.push("## Marks", "", ...slots, "", "Fetch the bytes with `design_export_kit`; never inline them here.", "");
+  }
+
+  const extra = additionalTokens(f);
+  body.push("## Additional tokens", "");
+  if (extra.length) {
+    body.push(
+      "Keys the renderer does not model yet, carried through verbatim so nothing is",
+      "lost between an hq that added a token and an SDK that has not learned it.",
+      "",
+      "```json",
+      JSON.stringify(Object.fromEntries(extra), null, 2),
+      "```",
+      "",
+    );
+  } else {
+    body.push("_None — every key in the foundation is modelled above._", "");
+  }
+
+  body.push("## Provenance", "", ...provenance(o));
+  return finish([...fm, ...body]);
+}
+
+/**
+ * Render PRODUCT.md — the voice and positioning half of the same foundation.
+ * Same purity contract as {@link renderDesignMd}.
+ *
+ * @param {object} foundation
+ * @param {object} [opts] see {@link renderDesignMd}
+ * @returns {string}
+ */
+export function renderProductMd(foundation, opts = {}) {
+  const f = isObj(foundation) ? foundation : {};
+  const o = isObj(opts) ? opts : {};
+  const name = str(o.name) || "Workspace";
+  const sys = isObj(f.system) ? f.system : {};
+  const sysVoice = isObj(sys.voice) ? sys.voice : {};
+
+  const lines = [
+    "---",
+    `name: ${q(name)}`,
+  ];
+  if (str(o.versionId)) lines.push(`version: ${q(o.versionId)}`);
+  if (str(o.generatedAt)) lines.push(`generatedAt: ${q(o.generatedAt)}`);
+  lines.push(`source: ${q(str(o.source) || "cohort · branding.getFoundation")}`, "---", "");
+
+  lines.push(
+    `# ${name} — product voice`,
+    "",
+    "Generated from the workspace's saved brand foundation. It says how this",
+    "product sounds; `DESIGN.md` beside it says how it looks. Read both before",
+    "writing anything a customer sees. Edits here are overwritten on the next",
+    "sync — propose foundation changes with `design_propose_change`.",
+    "",
+  );
+
+  const positioning = str(f.positioning);
+  if (positioning) lines.push("## Positioning", "", positioning, "");
+
+  const taglines = arr(f.taglines).map((t) => str(t)).filter(Boolean);
+  if (taglines.length) lines.push("## Taglines", "", ...taglines.map((t) => `- ${t}`), "");
+
+  const voice = str(f.voice) || str(sysVoice.voice);
+  if (voice) lines.push("## Voice", "", voice, "");
+
+  const traits = [...arr(f.toneTraits), ...arr(sysVoice.toneTraits)]
+    .map((t) => str(t))
+    .filter(Boolean)
+    .filter((t, i, all) => all.indexOf(t) === i);
+  if (traits.length) lines.push("## Tone", "", ...traits.map((t) => `- ${t}`), "");
+
+  const lex = isObj(sysVoice.lexicon) ? sysVoice.lexicon : {};
+  const use = bullets(lex.use);
+  const avoid = bullets(lex.avoid);
+  if (use.length || avoid.length) {
+    lines.push("## Lexicon", "");
+    if (use.length) lines.push("Say:", "", ...use, "");
+    if (avoid.length) lines.push("Avoid:", "", ...avoid, "");
+  }
+
+  const example = str(sysVoice.exampleCopy);
+  if (example) lines.push("## In practice", "", example, "");
+
+  const motifs = bullets(sys.motifs);
+  if (motifs.length) lines.push("## Motifs", "", ...motifs, "");
+  if (str(sys.iconography)) lines.push("## Iconography", "", str(sys.iconography), "");
+
+  if (!positioning && !voice && !traits.length && !use.length && !avoid.length) {
+    lines.push("## Nothing set yet", "", "The foundation carries no voice or positioning. Ask a human to fill it in from", "the Design surface, or propose it with `design_propose_change`.", "");
+  }
+
+  lines.push("## Provenance", "", ...provenance(o));
+  return finish(lines);
+}
+
+/**
+ * Both files, rendered together — the shape the CLI and the daemon both write.
+ * Relative paths, so the caller decides the directory.
+ * @param {object} foundation
+ * @param {object} [opts] see {@link renderDesignMd}
+ * @returns {Array<{rel:string, content:string}>}
+ */
+export function renderDesignBundle(foundation, opts = {}) {
+  return [
+    { rel: "DESIGN.md", content: renderDesignMd(foundation, opts) },
+    { rel: "PRODUCT.md", content: renderProductMd(foundation, opts) },
+  ];
+}
+
+export default {
+  renderDesignMd,
+  renderProductMd,
+  renderDesignBundle,
+  colorTokens,
+  scaleTokens,
+  typographyTokens,
+  componentRefs,
+  additionalTokens,
+  tokenRef,
+  slugToken,
+  KNOWN_FOUNDATION_KEYS,
+  KNOWN_SYSTEM_KEYS,
+  KNOWN_VISUAL_LANGUAGE_KEYS,
+};