@augurworks/augur 0.15.1

package/src/bundle-keys.mjs

@@ -0,0 +1,138 @@
+// The bundle store's KEY SHAPE — the one place a logical store key becomes a physical one.
+//
+// Lifted out of src/_worker.js so the workspace object (src/tenant-do.js) can address the
+// store for the workspace it IS, without a second key computation living beside this one:
+// the seed pack a fresh workspace is furnished with at provisioning is written by the
+// object, and the object has to land it under exactly the segment the front door reads
+// (`F-seed-pack-at-provision`). The worker imports everything here and re-exports it under
+// `__testables`, so every test and rehearsal that reads these names off the worker keeps
+// reading them there. Nothing else changed in the move: the text below is the worker's,
+// verbatim, including the two families that stay shared and why.
+//
+// ⚠️ `scripts/bundle-tenancy-rehearsal.mjs` edits a COPY of this file to run the per-family
+// revert (`BUNDLE_TENANCY.spaces = false`); rename the constant and it says so.
+
+// ---- The workspace segment on a bundle-store key ----------------------------
+//
+// `B-bundle-store-tenancy`. Not one key above carries a workspace: `config/instance.json`
+// is one document for the whole bucket, `spaces/<id>/…` names a SPACE, and one deployment
+// serving several workspaces therefore has them all writing the same keys. Two workspaces
+// publishing a space under the same id write the same object, so the commit CAS, the
+// unpublish guard and the stale-base check all evaluate against a stranger's document —
+// and a route-level gate cannot un-collide a key. So the key gains the segment.
+//
+// THE SHAPE, decided rather than discovered (`DECISION-bundle-store-tenancy.md`, option 1):
+// a tenant PREFIX in the one bucket. `t/<workspace>/spaces/…`,
+// `t/<workspace>/config/instance.json`, `t/<workspace>/assets/…`.
+//
+// ⚠️ TWO FAMILIES STAY GLOBAL AND SHARED, DELIBERATELY. Both exceptions are written out
+// below rather than left to fall out of the change, because falling out of a change is
+// exactly how they would be got wrong.
+//
+//   `blobs/<sha256>` — published bytes. Every write verifies the digest against the key
+//   before storing, so a workspace can only ever write bytes that hash to the name it
+//   used: an overwrite is a no-op by construction and there is nothing to poison. Dedup
+//   across workspaces is load-bearing (a migration's frozen pass uploaded 0 blobs of 854
+//   already present), and `blobGc` is written FOR a shared namespace — it reads every
+//   remaining manifest before deleting anything, because only the sweep can tell an
+//   orphan from a blob another workspace is serving. Prefixing them would break that
+//   design and buy nothing: a SHA-256 is not enumerable, so the disclosure door is the
+//   INDEX, not the bytes — and the index is `spaces/`, which is prefixed.
+//
+//   `spaces/_engine/` — the engine chrome. ONE worker build serves every workspace on a
+//   deployment, so one chrome bundle is correct rather than a leak. Prefix it by accident
+//   and every workspace loses its chrome on the deploy that does it.
+export const BUNDLE_TENANT_PREFIX = "t/";
+export const ENGINE_SPACE_ID = "_engine";
+// Which families take the segment. One word each, and flipping one back is the revert for
+// that family alone — the shape `KV_CUTOVER` uses, for the same reason: a change that has
+// to be reverted as a unit is a change nobody wants to make on a live instance.
+export const BUNDLE_TENANCY = Object.freeze({
+  spaces: true,   // spaces/<id>/manifest.json + spaces/<id>/versions/<n>.json
+  config: true,   // config/instance.json
+  assets: true,   // assets/<sha256[0:40]> — canvas image bytes
+  // blobs: NOT HERE, AND NOT AN OMISSION. See the header above.
+});
+
+/** Which family a bundle-store key belongs to, or "" for one this scheme does not name. */
+export function bundleFamily(key) {
+  const k = String(key || "");
+  if (k.startsWith("blobs/")) return "blobs";
+  if (k.startsWith("assets/")) return "assets";
+  if (k.startsWith("config/")) return "config";
+  if (k.startsWith("spaces/")) return "spaces";
+  return "";
+}
+
+/**
+ * The physical store key for a logical one.
+ *
+ * `workspace` is the second argument and it DEFAULTS TO NONE, which is the whole of the
+ * straddle: a deployment that serves one workspace passes nothing and gets back the string
+ * it has always got back, byte for byte. Only a prefixing deployment passes a segment —
+ * see `bundleWorkspaceSegment`.
+ */
+export function bundleKey(key, workspace = "") {
+  if (!workspace) return key;
+  const family = bundleFamily(key);
+  if (!family || !BUNDLE_TENANCY[family]) return key;
+  // ⚠️ THE ENGINE EXCEPTION, WRITTEN OUT. `spaces/_engine/…` is the chrome one worker
+  // build serves to every workspace on this deployment. It is not this workspace's to
+  // hold and it is not another's to be kept from.
+  if (family === "spaces" && key.startsWith(`spaces/${ENGINE_SPACE_ID}/`)) return key;
+  return BUNDLE_TENANT_PREFIX + workspace + "/" + key;
+}
+
+/**
+ * The bundle store as ONE workspace sees it: the same five verbs over LOGICAL keys, with
+ * the segment applied on the way in and stripped on the way out.
+ *
+ * ⚠️ WITH NO SEGMENT THIS IS THE BINDING ITSELF — not a wrapper around it, the object.
+ * That is deliberate, and it is what makes the change additive for every instance running
+ * today: with no segment this function is the identity, so there is no new code at all
+ * between the worker and R2 and nothing to get subtly wrong on a deployment that never
+ * asked for a segment.
+ *
+ * Stripping on the way out is what lets every caller keep the key it already had: a
+ * listing hands back `spaces/x/versions/3.json`, and handing that straight back to `get`
+ * or `delete` re-applies the segment rather than double-prefixing it.
+ */
+export function bundleStore(env, workspace = "") {
+  const r2 = env && env.BUNDLES;
+  if (!r2 || !workspace) return r2 || null;
+  const seg = BUNDLE_TENANT_PREFIX + workspace + "/";
+  const K = (k) => bundleKey(k, workspace);
+  const un = (k) => (String(k).startsWith(seg) ? String(k).slice(seg.length) : String(k));
+  // ⚠️ A WRITE GOES TO THE SEGMENTED KEY AND NOWHERE ELSE. This view used to write the
+  // unprefixed key too, as a straddle meant to keep the per-family flag a revert rather
+  // than a rollback — and on the one kind of deployment that has a segment at all, it was
+  // never that. Where the bucket is shared an unprefixed key is unattributable: the
+  // deployment's own rule (`legacyIsOurs: false`) already refuses to READ one, and flipping
+  // a family's flag back there reads whatever was last written under the bare key by
+  // whichever workspace wrote it last — the collision this scheme exists to close, not
+  // yesterday. So the second write bought no revert, and it cost a real thing: every
+  // workspace's `config/instance.json` — its roster — and every manifest — its blob index,
+  // the disclosure door the header above names — copied to where every workspace shares.
+  // Found on a live shared deployment, attributed by content, the same second as the
+  // segmented write.
+  //
+  // Deletes never touched the unprefixed key either, for the same reason in the other
+  // direction: removing one is removing an object that may be a neighbour's. That still
+  // holds, so what predates the segment is left exactly where and as it was.
+  const store = {
+    get: (k, opts) => (opts === undefined ? r2.get(K(k)) : r2.get(K(k), opts)),
+    put: (k, v, opts) => (opts === undefined ? r2.put(K(k), v) : r2.put(K(k), v, opts)),
+    list: async (opts = {}) => {
+      const page = await r2.list({ ...opts, prefix: K(opts.prefix || "") });
+      return {
+        ...page,
+        objects: (page.objects || []).map((o) => ({ ...o, key: un(o.key) })),
+        delimitedPrefixes: (page.delimitedPrefixes || []).map(un),
+      };
+    },
+  };
+  if (typeof r2.head === "function") store.head = (k) => r2.head(K(k));
+  if (typeof r2.delete === "function") store.delete = (k) => r2.delete(K(k));
+  return store;
+}
+

package/src/canon/collect-in-browser.js

@@ -0,0 +1,215 @@
+/**
+ * canon — collect evidence from a product you are ALREADY SIGNED IN TO.
+ *
+ * Paste this whole file into your browser's developer console, on a page of your own
+ * product, while you are logged in. It reads what the page actually renders and prints
+ * an `observation` — the same object `augur canon collect <url>` produces for a public
+ * page, so everything downstream is identical whichever way you got here.
+ *
+ * WHY IT RUNS IN YOUR BROWSER. The people who need a design system extracted hold a
+ * login, not repo access, and their product is behind that login. Nothing here leaves
+ * the page: no request is made, no credential is read, no cookie is touched. It walks
+ * the DOM you are looking at, asks the browser what colour and size each element ended
+ * up, and counts. You can read every line of it before you paste it.
+ *
+ * WHAT COMES OUT is evidence, not a design system: ranked colours (weighted by how much
+ * of the screen they actually cover, which is the signal a stylesheet cannot give you),
+ * font stacks, the sizes and gaps in use, the radii, the shadows, whatever custom
+ * properties the product already declares, and the class families that are candidate
+ * components. Deciding which grey is the hairline and which colour is the one hot ink is
+ * the next step, and it is not this file's job.
+ *
+ * Run it on three or four DIFFERENT screens and keep all of them — a login page is not
+ * a design system. `augur canon collect --merge` folds them together.
+ */
+(function () {
+  "use strict";
+
+  var MAX_ELEMENTS = 12000;
+
+  var COLOR_PROPS = ["color", "backgroundColor", "borderTopColor", "borderRightColor",
+    "borderBottomColor", "borderLeftColor", "outlineColor", "fill", "stroke"];
+  /* A border colour on an edge that draws no border is the browser's default, not the
+     product's decision. Counting it puts the user-agent grey of every <table> near the
+     top of the evidence, wearing exactly the profile a hairline colour has — seen on
+     border properties and nothing else — which is the one tell the mapping relies on. */
+  var BORDER_SIDE = {
+    borderTopColor: "borderTop", borderRightColor: "borderRight",
+    borderBottomColor: "borderBottom", borderLeftColor: "borderLeft",
+    outlineColor: "outline",
+  };
+  var SPACE_PROPS = ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft",
+    "marginTop", "marginRight", "marginBottom", "marginLeft", "rowGap", "columnGap"];
+
+  function Tally() { this.m = {}; }
+  Tally.prototype.add = function (value, where, prop, area) {
+    if (!value || value === "none" || value === "normal" || value === "auto" || value === "0px") return;
+    if (value === "rgba(0, 0, 0, 0)" || value === "transparent") return;
+    var e = this.m[value];
+    if (!e) e = this.m[value] = { value: value, count: 0, area: 0, props: {}, where: [] };
+    e.count++;
+    e.area += area || 0;
+    e.props[prop] = 1;
+    if (e.where.length < 4 && where && e.where.indexOf(where) < 0) e.where.push(where);
+  };
+  Tally.prototype.ranked = function (byArea) {
+    var out = [];
+    for (var k in this.m) if (Object.prototype.hasOwnProperty.call(this.m, k)) out.push(this.m[k]);
+    out.sort(function (a, b) {
+      if (byArea && b.area !== a.area) return b.area - a.area;
+      return b.count - a.count || (a.value < b.value ? -1 : 1);
+    });
+    return out.slice(0, 60).map(function (e) {
+      return { value: e.value, count: e.count, area: Math.round(e.area), props: Object.keys(e.props).slice(0, 6), where: e.where };
+    });
+  };
+
+  /* A short, readable description of where a value was seen: tag plus its own classes. */
+  function whereOf(el) {
+    var cls = (el.getAttribute && el.getAttribute("class")) || "";
+    return (el.tagName || "?").toLowerCase() + (cls ? "." + cls.trim().split(/\s+/).slice(0, 2).join(".") : "");
+  }
+
+  var colors = new Tally(), fontStacks = new Tally(), fontSizes = new Tally();
+  var lineHeights = new Tally(), fontWeights = new Tally(), spacings = new Tally();
+  var radii = new Tally(), shadows = new Tally(), motions = new Tally();
+  var fams = {};
+  var elements = 0;
+
+  var all = document.querySelectorAll("body *");
+  for (var i = 0; i < all.length && i < MAX_ELEMENTS; i++) {
+    var el = all[i];
+    var cs;
+    try { cs = getComputedStyle(el); } catch (e) { continue; }
+    if (!cs || cs.display === "none" || cs.visibility === "hidden") continue;
+    var rect = el.getBoundingClientRect();
+    if (!rect.width && !rect.height) continue;
+    elements++;
+    var area = Math.min(rect.width * rect.height, 4000000);
+    var where = whereOf(el);
+    var hasText = false;
+    for (var n = 0; n < el.childNodes.length; n++) {
+      if (el.childNodes[n].nodeType === 3 && el.childNodes[n].nodeValue.trim()) { hasText = true; break; }
+    }
+    /* `fill` and `stroke` are inherited SVG properties, so getComputedStyle answers for a
+       <div> too — and its answer is the initial `rgb(0, 0, 0)`. Counting those puts a
+       black nothing at the top of the evidence on any page with a few large containers. */
+    var isSvg = el.namespaceURI === "http://www.w3.org/2000/svg";
+    for (var c = 0; c < COLOR_PROPS.length; c++) {
+      var prop = COLOR_PROPS[c];
+      if ((prop === "fill" || prop === "stroke") && !isSvg) continue;
+      var side = BORDER_SIDE[prop];
+      if (side && (cs[side + "Style"] === "none" || parseFloat(cs[side + "Width"]) === 0)) continue;
+      /* Text colour is weighted by the ink it puts on the page, not by the box: a huge
+         container inheriting a colour it never paints would otherwise outrank the body. */
+      var weight = prop === "color" ? (hasText ? Math.min(area, 40000) : 0) : area;
+      if (weight) colors.add(cs[prop], where, prop, weight);
+    }
+    fontStacks.add(cs.fontFamily, where, "font-family", hasText ? area : 0);
+    if (hasText) {
+      fontSizes.add(cs.fontSize, where, "font-size", area);
+      lineHeights.add(cs.lineHeight, where, "line-height", area);
+      fontWeights.add(cs.fontWeight, where, "font-weight", area);
+    }
+    for (var s = 0; s < SPACE_PROPS.length; s++) spacings.add(cs[SPACE_PROPS[s]], where, "spacing", 1);
+    radii.add(cs.borderTopLeftRadius, where, "border-radius", area);
+    shadows.add(cs.boxShadow, where, "box-shadow", area);
+    if (cs.transitionDuration && cs.transitionDuration !== "0s") {
+      motions.add(cs.transitionDuration + " " + cs.transitionTimingFunction, where, "transition", 1);
+    }
+    var list = el.classList;
+    for (var q = 0; list && q < list.length; q++) {
+      var name = list[q];
+      if (!/^[a-zA-Z][\w-]{2,}$/.test(name)) continue;
+      var parts = name.split(/[-_]/);
+      if (parts.length < 2) continue;
+      var root = parts.slice(0, 2).join("-");
+      var f = fams[root] || (fams[root] = { root: root, uses: 0, members: {} });
+      f.uses++;
+      f.members[name] = 1;
+    }
+  }
+
+  /* Custom properties the product already declares. A cross-origin stylesheet throws on
+     .cssRules and there is nothing to be done about it — skip it and say so, rather than
+     failing the whole collection over a stylesheet on a CDN. */
+  var props = {}, blockedSheets = 0, readSheets = 0;
+  function eatRules(rules) {
+    for (var r = 0; r < rules.length; r++) {
+      var rule = rules[r];
+      if (rule.style) {
+        for (var k = 0; k < rule.style.length; k++) {
+          var nm = rule.style[k];
+          if (nm.slice(0, 2) === "--" && props[nm] === undefined) props[nm] = rule.style.getPropertyValue(nm).trim();
+        }
+      }
+      if (rule.cssRules) eatRules(rule.cssRules);
+    }
+  }
+  for (var t = 0; t < document.styleSheets.length; t++) {
+    try { eatRules(document.styleSheets[t].cssRules); readSheets++; }
+    catch (e) { blockedSheets++; }
+  }
+
+  var famList = [];
+  for (var key in fams) if (Object.prototype.hasOwnProperty.call(fams, key)) {
+    var mem = Object.keys(fams[key].members);
+    if (fams[key].uses > 1) famList.push({ root: key, uses: fams[key].uses, members: mem.slice(0, 10) });
+  }
+  famList.sort(function (a, b) { return b.members.length - a.members.length || b.uses - a.uses; });
+
+  var propList = [];
+  for (var pk in props) if (Object.prototype.hasOwnProperty.call(props, pk)) propList.push({ name: pk, value: props[pk] });
+  propList.sort(function (a, b) { return a.name < b.name ? -1 : 1; });
+
+  var observation = {
+    observationVersion: 1,
+    source: {
+      url: location.href,
+      collectedAt: new Date().toISOString(),
+      how: "browser",
+      pages: [location.href],
+      title: document.title,
+      viewport: innerWidth + "x" + innerHeight,
+      blockedSheets: blockedSheets,
+    },
+    stats: { sheets: readSheets, rules: 0, declarations: 0, elements: elements },
+    colors: colors.ranked(true),
+    fontStacks: fontStacks.ranked(true),
+    fontSizes: fontSizes.ranked(true),
+    lineHeights: lineHeights.ranked(true),
+    fontWeights: fontWeights.ranked(true),
+    spacings: spacings.ranked(false),
+    radii: radii.ranked(true),
+    shadows: shadows.ranked(true),
+    motions: motions.ranked(false),
+    customProperties: propList,
+    classFamilies: famList.slice(0, 40),
+  };
+
+  var json = JSON.stringify(observation, null, 2);
+  try { window.__augurObservation = observation; } catch (e) { /* sandboxed page */ }
+
+  /* Three ways out, because a console differs by browser and by how locked down the page
+     is. The file download is the one that always works; the rest are conveniences. */
+  try {
+    var name = "observation-" + location.hostname.replace(/[^a-z0-9]+/gi, "-") + "-" + Date.now() + ".json";
+    var a = document.createElement("a");
+    a.href = URL.createObjectURL(new Blob([json], { type: "application/json" }));
+    a.download = name;
+    a.click();
+    setTimeout(function () { URL.revokeObjectURL(a.href); }, 4000);
+    console.log("canon: saved " + name + " to your downloads — move it into your canon folder.");
+  } catch (e) {
+    console.log("canon: could not download; copy the JSON printed below.");
+  }
+  try { if (typeof copy === "function") { copy(json); console.log("canon: also copied to your clipboard."); } } catch (e) { /* not a console */ }
+
+  console.log("canon: " + elements + " elements, " + observation.colors.length + " colours, "
+    + observation.fontStacks.length + " font stacks, " + propList.length + " custom properties"
+    + (blockedSheets ? ", " + blockedSheets + " stylesheet(s) unreadable (cross-origin — computed styles still counted)" : "")
+    + ". It is on window.__augurObservation too.");
+  console.log("canon: run this on three or four DIFFERENT screens and keep every file. One page is not a design system.");
+
+  return observation;
+})();

package/src/canon/emit.mjs

@@ -0,0 +1,232 @@
+/**
+ * canon/emit — a graded canon becomes the workspace's design system.
+ *
+ * Everything here is deterministic text generation from `canon.json`. The judgement was
+ * spent upstream, by the user's own agent, deciding which of a product's colours is the
+ * hairline; this file only writes it down in the one shape the rest of the engine reads
+ * (agents/ui-skill.md): a tokens stylesheet whose custom properties are the roles, a
+ * components stylesheet that names nothing but those tokens, the skill manifest, and the
+ * workspace registry the comment overlay labels components from.
+ *
+ * TWO RULES MAKE IT SAFE TO RUN ON A WORKSPACE THAT ALREADY HAS SCREENS IN IT.
+ *
+ *   1. It REPLACES the tokens file and never touches the components file. The roles are
+ *      the contract; a workspace born from the seed already links `<prefix>-tokens.css`
+ *      from every prototype, so replacing values re-skins every screen at once and
+ *      breaks none of them. `<prefix>-ui.css` is the workspace's own writing and is not
+ *      the extractor's to rewrite.
+ *   2. Extracted components go in their OWN file, `<prefix>-canon.css`, and a class that
+ *      already exists in the workspace is a refusal, not a silent redefinition — two
+ *      rules for `.x-card` in two files is a bug that only shows up on one screen.
+ */
+
+import { ROLES, ROLE_BY_NAME, validateCanon } from "./schema.mjs";
+
+const GROUP_TITLES = {
+  paper: ["Paper", "the surfaces, from the desk up"],
+  ink: ["Ink", "everything written on the paper"],
+  mark: ["The one hot ink", "reserve it for the thing a person is meant to act on"],
+  state: ["States", ""],
+  type: ["Type", ""],
+  space: ["Space", "every gap in the workspace is one of these"],
+  shape: ["Shape", ""],
+  measure: ["Measure", ""],
+  motion: ["Motion", ""],
+};
+
+const rule = (title, sub) => {
+  const head = `  /* ── ${title} ${"─".repeat(Math.max(3, 66 - title.length))} */`;
+  return sub ? `${head}\n  /* ${sub} */` : head;
+};
+
+/** The tokens stylesheet: one custom property per role, in schema order. */
+export function renderTokensCss({ prefix, tokens, extras = {}, derived = [], source = {} }) {
+  const out = [];
+  out.push(`/* Design tokens — every colour, size and rhythm this workspace uses, in one file.`);
+  out.push(`   Change a value here and every screen that links this stylesheet moves with it.`);
+  out.push(``);
+  if (source.url) out.push(`   Extracted from ${source.url}${source.collectedAt ? ` on ${String(source.collectedAt).slice(0, 10)}` : ""}.`);
+  out.push(`   The names are roles, not descriptions: the same list every workspace fills, so a`);
+  out.push(`   prototype written against one design system works against another. Edit the`);
+  out.push(`   values freely — it is yours the moment you change it. */`);
+  out.push(``);
+  out.push(`:root {`);
+  let group = null;
+  const width = Math.max(...ROLES.map((r) => r.role.length)) + prefix.length + 5;
+  for (const r of ROLES) {
+    if (r.group !== group) { if (group) out.push(""); out.push(rule(...GROUP_TITLES[r.group])); group = r.group; }
+    const name = `  --${prefix}-${r.role}:`;
+    const value = String(tokens[r.role]);
+    const note = derived.includes(r.role) ? `   /* computed from what was observed */` : `   /* ${r.what} */`;
+    out.push(`${name.padEnd(width)} ${value};${value.length + name.length < 96 ? note : ""}`);
+  }
+  const extraNames = Object.keys(extras);
+  if (extraNames.length) {
+    out.push("");
+    out.push(rule("This product's own", "values the roles above do not have a slot for"));
+    for (const n of extraNames) out.push(`  --${prefix}-${n}: ${extras[n]};`);
+  }
+  out.push(`}`);
+  out.push(``);
+  return out.join("\n");
+}
+
+/** The extracted components, one block each, in the order the canon lists them. */
+export function renderCanonCss({ prefix, classPrefix, components, source = {} }) {
+  const out = [];
+  out.push(`/* Components extracted from the product itself.`);
+  if (source.url) out.push(`   Source: ${source.url}${source.collectedAt ? `, ${String(source.collectedAt).slice(0, 10)}` : ""}.`);
+  out.push(``);
+  out.push(`   Every rule below reads a token and hard-codes nothing, which is what lets one`);
+  out.push(`   edit in the tokens file move all of them. Add to this file by hand freely; the`);
+  out.push(`   extractor only rewrites it when you run it again. */`);
+  out.push(``);
+  for (const c of components) {
+    out.push(`/* ── ${c.label} — ${c.description} */`);
+    out.push(String(c.css).trim());
+    out.push(``);
+  }
+  if (!components.length) out.push(`/* Nothing named yet — the canon was tokens only. */`);
+  return out.join("\n");
+}
+
+/**
+ * Merge the extracted components into a workspace's `registry.json` BY NAME, keeping
+ * every entry the workspace already had. The registry is the workspace's, not the
+ * extractor's: an entry a person wrote a better description for stays written.
+ */
+export function mergeRegistry(existing, components) {
+  const items = Array.isArray(existing?.items) ? existing.items.slice() : [];
+  const at = new Map(items.map((it, i) => [it.name, i]));
+  const added = [], updated = [];
+  for (const c of components) {
+    const entry = { name: c.name, type: c.type, classes: c.classes, label: c.label, description: c.description };
+    if (at.has(c.name)) {
+      const i = at.get(c.name);
+      // Keep the workspace's own words; only fold in classes it does not know about.
+      const classes = [...new Set([...(items[i].classes || []), ...c.classes])];
+      if (classes.length !== (items[i].classes || []).length) { items[i] = { ...items[i], classes }; updated.push(c.name); }
+    } else { items.push(entry); added.push(c.name); }
+  }
+  return { registry: { ...(existing || {}), items }, added, updated };
+}
+
+/** Add the generated files to the skill's declared inventory, and the prefixes to it. */
+export function mergeSkillJson(existing, { prefix, classPrefix, files }) {
+  const skill = { ...(existing || {}) };
+  const assets = new Set(Array.isArray(skill.assets) ? skill.assets : []);
+  for (const f of files) assets.add(f);
+  skill.assets = [...assets];
+  const prefixes = new Set(Array.isArray(skill.cssPrefixes) ? skill.cssPrefixes : []);
+  prefixes.add(prefix);
+  if (classPrefix) prefixes.add(classPrefix);
+  skill.cssPrefixes = [...prefixes];
+  return skill;
+}
+
+/** The canon's own record: where it came from, what it names, what was computed. */
+export function renderCanonMd({ prefix, classPrefix, tokens, derived, components, source, observation }) {
+  const out = [];
+  out.push(`# The canon`);
+  out.push(``);
+  out.push(`This workspace's design system, ${source?.url ? `extracted from ${source.url}` : "extracted from the product"}${source?.collectedAt ? ` on ${String(source.collectedAt).slice(0, 10)}` : ""}.`);
+  out.push(``);
+  out.push(`- Tokens: \`${prefix}-tokens.css\` — ${ROLES.length} roles, all filled.`);
+  if (derived?.length) out.push(`- ${derived.length} of them were COMPUTED from the ones observed, not seen in the product: ${derived.join(", ")}. Change any of them by hand if the product does have its own.`);
+  out.push(`- Components: \`${prefix}-canon.css\` — ${components.length} named, classed \`.${classPrefix}-*\`.`);
+  if (observation) {
+    out.push(`- Evidence: ${observation.source?.pages?.length || 1} page(s), ${observation.stats?.elements || 0} elements, ${(observation.colors || []).length} distinct colours seen. Collected ${observation.source?.how === "browser" ? "in the browser, signed in" : "over HTTP"}.`);
+  }
+  out.push(``);
+  out.push(`## Pulling from it`);
+  out.push(``);
+  out.push(`Reference the skill by its canonical relative path, exactly as every other`);
+  out.push(`prototype does — the build rewrites it so the page works on disk and on the site:`);
+  out.push(``);
+  out.push("```html");
+  out.push(`<link rel="stylesheet" href="../../../skills/${prefix}-ui/${prefix}-tokens.css">`);
+  out.push(`<link rel="stylesheet" href="../../../skills/${prefix}-ui/${prefix}-canon.css">`);
+  out.push("```");
+  out.push(``);
+  if (components.length) {
+    out.push(`## The vocabulary`);
+    out.push(``);
+    out.push(`| Name | Classes | What it is |`);
+    out.push(`| --- | --- | --- |`);
+    // Every class, not only the first: the modifiers are most of a vocabulary, and a
+    // table that hides them is a document that tells you the parts exist and not how to
+    // ask for the one you want.
+    for (const c of components) out.push(`| ${c.name} | ${c.classes.map((cl) => `\`.${cl}\``).join(" ")} | ${c.description} |`);
+    out.push(``);
+  }
+  out.push(`## Re-running it`);
+  out.push(``);
+  out.push(`Collect again, re-map, \`augur canon apply\`. The tokens file is regenerated and`);
+  out.push(`the components file is rewritten; nothing else in the skill is touched, so a`);
+  out.push(`component you wrote by hand in the workspace's own stylesheet survives.`);
+  out.push(``);
+  return out.join("\n");
+}
+
+/**
+ * Every class a stylesheet defines. Comments are stripped first, or a `/* see foo.css *​/`
+ * lands `.css` in the list — which the brief then hands a person as a name they may not
+ * use. ONE function, exported, because the brief promises exactly what `apply` refuses
+ * and two regexes would eventually promise something else.
+ */
+export function classNamesIn(css) {
+  const bare = String(css).replace(/\/\*[\s\S]*?\*\//g, "");
+  return [...new Set([...bare.matchAll(/\.(-?[a-zA-Z_][\w-]*)/g)].map((m) => m[1]))].sort();
+}
+
+/**
+ * Everything `augur canon apply` would write, as `{path, text}` — plus the refusals.
+ * Pure: the caller does the IO, which is what lets `--dry-run` be the same code path.
+ *
+ * @param {object} a
+ * @param {object} a.canon         the graded answer
+ * @param {string} a.skillDir      relative path of the skill directory, e.g. `skills/x-ui`
+ * @param {string} a.skillPrefix   the workspace's existing token prefix
+ * @param {object} a.existingSkillJson
+ * @param {object} a.existingRegistry
+ * @param {string} a.existingComponentCss  the workspace's own `<prefix>-ui.css`, for collisions
+ * @param {object} [a.observation]
+ */
+export function planApply({ canon, skillDir, skillPrefix, existingSkillJson, existingRegistry, existingComponentCss = "", observation = null }) {
+  const graded = validateCanon(canon);
+  const errors = [...graded.errors];
+  const notes = [];
+  const prefix = skillPrefix || graded.prefix;
+
+  if (skillPrefix && graded.prefix !== skillPrefix) {
+    // Renaming a workspace's tokens would orphan every prototype that reads them.
+    notes.push(`the canon calls itself "${graded.prefix}" and this workspace's design system is "${skillPrefix}" — emitting as "${skillPrefix}" so the screens that already read these tokens keep working`);
+  }
+
+  const components = Array.isArray(canon.components) ? canon.components : [];
+  const taken = new Set(classNamesIn(existingComponentCss));
+  for (const c of components) {
+    for (const cl of c.classes || []) {
+      if (taken.has(cl)) errors.push(`components (${c.name}): .${cl} is already defined in this workspace's own stylesheet — rename it, or the two rules will fight on one screen`);
+    }
+  }
+
+  const extras = {};
+  for (const [k, v] of Object.entries(canon.tokens || {})) if (k.startsWith("x-") && v) extras[k.slice(2)] = v;
+
+  const files = [`${prefix}-tokens.css`, `${prefix}-canon.css`];
+  const { registry, added, updated } = mergeRegistry(existingRegistry, components);
+  const writes = [
+    { path: `${skillDir}/${prefix}-tokens.css`, text: renderTokensCss({ prefix, tokens: graded.tokens, extras, derived: graded.derived, source: canon.source }) },
+    { path: `${skillDir}/${prefix}-canon.css`, text: renderCanonCss({ prefix, classPrefix: graded.classPrefix, components, source: canon.source }) },
+    { path: `${skillDir}/skill.json`, text: JSON.stringify(mergeSkillJson(existingSkillJson, { prefix, classPrefix: graded.classPrefix, files }), null, 2) + "\n" },
+    { path: `registry.json`, text: JSON.stringify(registry, null, 2) + "\n" },
+    { path: `${skillDir}/CANON.md`, text: renderCanonMd({ prefix, classPrefix: graded.classPrefix, tokens: graded.tokens, derived: graded.derived, components, source: canon.source, observation }) },
+  ];
+
+  if (added.length) notes.push(`registry: added ${added.join(", ")}`);
+  if (updated.length) notes.push(`registry: widened ${updated.join(", ")}`);
+  if (graded.derived.length) notes.push(`${graded.derived.length} role(s) computed rather than observed: ${graded.derived.join(", ")}`);
+
+  return { ok: errors.length === 0, errors, warnings: graded.warnings, writes, notes, prefix, graded };
+}