diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b571819e..90066707 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -109,6 +109,15 @@ jobs:
       - run: node scripts/check-hook-tokens.js
       - run: node scripts/check-mirrors.js
       - run: node scripts/check-bundle-defs.js
+      # Strings that must never ship: hardcoded colour literals outside the
+      # token source files, and external URLs in a built bundle. Runs after
+      # check-artifacts.js, which rebuilds dist/ — so the bundle rules have
+      # something to scan.
+      - run: npm run check:forbidden-strings
+      # docs/token-renames.json must stay truthful: every rename target live,
+      # no old name still live. A stale map migrates theme files onto dead
+      # tokens, which is worse than having no map at all.
+      - run: npm run check:token-renames
 
   dependency-audit:
     name: Dependency vulnerability audit
diff --git a/CLAUDE.md b/CLAUDE.md
index 53ab14a8..712f2a21 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,6 +61,9 @@ requires a rebuild+redeploy, not just a file edit.
 | `npm run check:layer-order` | Verify `docs/architecture.md`'s `@layer` block and specificity ladder match `core/layers.css` (CI gate) |
 | `npm run check:macros` | Verify `.sf-*` macro classes match `docs/macros.md` (CI gate) |
 | `npm run check:registry` | Verify `token-registry.json` is in sync with source (CI gate) |
+| `npm run check:forbidden-strings` | Verify no hardcoded colour literal sits outside the token source files and no shipped bundle contains an external URL (CI gate) |
+| `npm run check:token-renames` | Verify `docs/token-renames.json` is truthful — every rename target is a live token, no old name still is (CI gate) |
+| `npm run migrate:theme -- <file> [--write]` | Migrate a `*.slashed-theme.json` theme file onto the current token API |
 | `npm run audit:check` | Verify `docs/registry.json` matches source without writing (CI gate) |
 | `npm run lint:css` | Lint all CSS source with stylelint (CI gate) |
 | `npm run lint:css:fix` | Lint CSS source and auto-fix violations |
@@ -140,6 +143,40 @@ instance token, an example of a component the framework does not ship) — recor
 it in `docs/ref-allowlist.json` with a reason. `docs/migration.md` (historical)
 and `docs/roadmap.md` (forward-looking) are whole-doc exclusions.
 
+## Token renames — MANDATORY
+
+`docs/token-renames.json` is the machine-readable mirror of `docs/migration.md`.
+It is what lets a **theme file** (`*.slashed-theme.json` — the portable,
+name-keyed override snapshot, see `scripts/lib/theme-file.js`) survive a rename:
+`npm run migrate:theme -- <file> --write` rewrites old names, drops removed ones
+with the reason, and never discards an override it does not recognise.
+
+**Any PR that renames or removes a `--sf-*` token must add the corresponding
+entry**, in the same PR as the CSS change:
+
+- **Renamed** → add to `renames` as `"--sf-old": "--sf-new"`. Record the
+  *fully resolved* destination, never an intermediate name: rename targets must
+  be live, so a chain (`a → b → c`) fails the gate by construction.
+- **Removed with no replacement** → add to `removals` with a reason saying what
+  to use instead. A removal without a reason is rejected.
+
+This cannot be generated. `token-registry.json` keeps ids permanent, but
+`check-token-registry.js` deliberately permits renames as *in-place name
+updates on the same id* — so after a rename the old name is simply gone, with
+nothing to look it up by. That is harmless for the share-link codec (it stores
+ids) and fatal for a name-keyed theme file. A rename and a delete+add pair are
+also indistinguishable to a generator, so the map is curated by hand.
+
+```bash
+npm run check:token-renames   # must pass — CI fails if it doesn't
+```
+
+The gate holds the map to three invariants: every rename target is live, no old
+name is still live, and renames and removals are disjoint. Note that "live"
+includes tokens merely *declared* in `core/`/`optional/` CSS — so a leftover
+declaration of a supposedly-renamed token will fail this gate, which is how it
+catches a half-finished rename.
+
 ## Tests
 
 ```bash
diff --git a/configurator/scripts/sync-api.mjs b/configurator/scripts/sync-api.mjs
index c5cf95f9..60529052 100644
--- a/configurator/scripts/sync-api.mjs
+++ b/configurator/scripts/sync-api.mjs
@@ -43,12 +43,14 @@ const SOURCE =
 const ANNOTATIONS_FILE = path.join(FRAMEWORK_ROOT, 'docs', 'token-annotations.json');
 const BUNDLE_CONFIG_FILE = path.join(FRAMEWORK_ROOT, 'bundle.config.json');
 const REGISTRY_FILE = path.join(FRAMEWORK_ROOT, 'token-registry.json');
+const RENAMES_FILE = path.join(FRAMEWORK_ROOT, 'docs', 'token-renames.json');
 
 const OUT_DIR = path.join(CONFIGURATOR_ROOT, 'src', 'data');
 const OUT = path.join(OUT_DIR, 'api-index.generated.json');
 const CLASSES_OUT = path.join(OUT_DIR, 'classes.generated.json');
 const BUNDLES_OUT = path.join(OUT_DIR, 'bundles.generated.json');
 const REGISTRY_OUT = path.join(OUT_DIR, 'token-registry.generated.json');
+const RENAMES_OUT = path.join(OUT_DIR, 'token-renames.generated.json');
 
 // jsDelivr serves the published dist branch (see .github/workflows/publish-dist.yml)
 // at the repo root, so a bundle's minified file is <CDN_BASE>/slashed.<id>.min.css.
@@ -314,6 +316,10 @@ function main() {
   // verbatim so the configurator imports it the same way model.js imports the
   // api-index — and so the runtime can never drift from the committed registry.
   syncRegistry();
+
+  // Rename/removal map for theme-file import (src/lib/themeFile.ts), so an
+  // override set authored against an older SLASHED can be migrated on load.
+  syncRenames();
 }
 
 /**
@@ -348,4 +354,44 @@ function syncRegistry() {
   );
 }
 
+/**
+ * Copy docs/token-renames.json → src/data/token-renames.generated.json, so the
+ * configurator's theme-file import can migrate an old override set without
+ * reaching outside its own package at runtime (the @framework-css alias is
+ * remapped by the WP plugin, so cross-boundary runtime imports are not safe
+ * here — a generated data file is).
+ *
+ * The map's truthfulness is guaranteed upstream by scripts/check-token-renames.js.
+ */
+function syncRenames() {
+  if (!fs.existsSync(RENAMES_FILE)) {
+    console.error(
+      `[configurator:sync] token-renames.json not found at ${RENAMES_FILE}\n` +
+        `It is a hand-maintained mirror of docs/migration.md — it should be committed.`
+    );
+    process.exit(1);
+  }
+  let map;
+  try {
+    map = JSON.parse(fs.readFileSync(RENAMES_FILE, 'utf8'));
+  } catch (err) {
+    console.error(`[configurator:sync] ${RENAMES_FILE} is not valid JSON (${err.message}).`);
+    process.exit(1);
+  }
+  const out = {
+    _sync: {
+      generatedBy: 'configurator/scripts/sync-api.mjs',
+      source: 'docs/token-renames.json',
+    },
+    renames: map.renames ?? {},
+    removals: map.removals ?? {},
+  };
+  fs.writeFileSync(RENAMES_OUT, JSON.stringify(out, null, 2) + '\n', 'utf8');
+  console.log(
+    `[configurator:sync] ${path.relative(FRAMEWORK_ROOT, RENAMES_OUT)} ← ` +
+      `docs/token-renames.json (${Object.keys(out.renames).length} renames, ` +
+      `${Object.keys(out.removals).length} removals)`
+  );
+}
+
 main();
diff --git a/configurator/src/components/DomainPanel.svelte b/configurator/src/components/DomainPanel.svelte
index 89c8b55e..fb7270cb 100644
--- a/configurator/src/components/DomainPanel.svelte
+++ b/configurator/src/components/DomainPanel.svelte
@@ -64,7 +64,7 @@
   {:else if domain === "wcag"}
     <WcagPanel {tokens} {overrides} {onSet} {onBulkChange} />
   {:else if domain === "setup"}
-    <ExportPanel {overrides} />
+    <ExportPanel {overrides} {tokens} {onApplyTheme} />
   {:else if domain === "cheatsheet"}
     <CheatsheetPanel />
   {/if}
diff --git a/configurator/src/components/panels/ExportPanel.svelte b/configurator/src/components/panels/ExportPanel.svelte
index 1d014fbd..1851c829 100644
--- a/configurator/src/components/panels/ExportPanel.svelte
+++ b/configurator/src/components/panels/ExportPanel.svelte
@@ -1,16 +1,61 @@
 <script lang="ts">
-  import { Check, Copy, Download, Link } from '@lucide/svelte';
+  import { Check, Copy, Download, Link, Upload, TriangleAlert } from '@lucide/svelte';
   import { generateCSS, buildShareUrl } from '../../lib/codec';
   import { getShareBaseUrl } from '../../lib/persistence';
+  import { serializeThemeFile, importThemeFile } from '../../lib/themeFile';
+  import type { SlashedToken } from '../../types';
 
-  let { overrides }: {
+  let { overrides, tokens = [], onApplyTheme }: {
     overrides: Record<string, string>;
+    tokens?: SlashedToken[];
+    onApplyTheme?: (overrides: Record<string, string>) => void;
   } = $props();
 
+  // Declared globally in src/vite-env.d.ts, injected by Vite at build time.
+  const frameworkVersion =
+    typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : undefined;
+
   let outputMode = $state<"layer" | "root">("layer");
   let copied = $state(false);
   let copiedLink = $state(false);
 
+  // Theme-file import feedback: what the migration did, or why it refused.
+  let importNotes = $state<string[]>([]);
+  let importErrors = $state<string[]>([]);
+  let fileInput = $state<HTMLInputElement | null>(null);
+
+  let liveTokenNames = $derived(new Set(tokens.map((t) => t.name)));
+
+  function handleDownloadTheme() {
+    const json = serializeThemeFile({ overrides, slashedVersion: frameworkVersion });
+    const blob = new Blob([json], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "slashed-theme.json";
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  async function handleImportTheme(event: Event) {
+    const input = event.target as HTMLInputElement;
+    const file = input.files?.[0];
+    if (!file) return;
+
+    importNotes = [];
+    importErrors = [];
+
+    const result = await importThemeFile(file, liveTokenNames);
+    if (!result.overrides) {
+      importErrors = result.errors;
+    } else {
+      importNotes = result.notes;
+      onApplyTheme?.(result.overrides);
+    }
+    // Allow re-selecting the same file after a fix.
+    input.value = "";
+  }
+
   let css = $derived(generateCSS(overrides, { mode: outputMode, banner: true }));
   let count = $derived(Object.keys(overrides).length);
 
@@ -139,6 +184,64 @@
     </div>
   </div>
 
+  <!-- Portable theme file: the reviewable, committable form of this override set -->
+  <div class="space-y-2">
+    <div class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Theme file</div>
+    <p class="text-[10px] text-slate-600 dark:text-slate-400 leading-relaxed">
+      A named, sorted JSON snapshot you can commit next to your CSS and review in a diff.
+      Importing one migrates tokens renamed since it was written.
+    </p>
+
+    <div class="flex gap-2">
+      <button
+        onclick={handleDownloadTheme}
+        disabled={count === 0}
+        class="flex-1 flex items-center justify-center gap-2 py-2 rounded-lg border border-black/8 dark:border-white/8 bg-black/4 dark:bg-white/4 text-[10px] font-bold text-slate-600 dark:text-slate-400 hover:bg-black/8 dark:hover:bg-white/8 hover:text-slate-800 dark:hover:text-slate-200 transition-all cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
+      >
+        <Download class="w-3 h-3" />
+        Download .json
+      </button>
+      <button
+        onclick={() => fileInput?.click()}
+        class="flex-1 flex items-center justify-center gap-2 py-2 rounded-lg border border-black/8 dark:border-white/8 bg-black/4 dark:bg-white/4 text-[10px] font-bold text-slate-600 dark:text-slate-400 hover:bg-black/8 dark:hover:bg-white/8 hover:text-slate-800 dark:hover:text-slate-200 transition-all cursor-pointer"
+      >
+        <Upload class="w-3 h-3" />
+        Import…
+      </button>
+    </div>
+
+    <input
+      bind:this={fileInput}
+      type="file"
+      accept="application/json,.json"
+      onchange={handleImportTheme}
+      class="hidden"
+    />
+
+    {#if importErrors.length}
+      <div class="rounded-lg bg-red-500/8 border border-red-500/20 p-3 space-y-1">
+        <div class="flex items-center gap-1.5 text-[10px] font-bold text-red-700 dark:text-red-300">
+          <TriangleAlert class="w-3 h-3" />
+          Import refused — nothing was changed
+        </div>
+        {#each importErrors as err}
+          <div class="text-[10px] text-red-700/80 dark:text-red-300/80 leading-relaxed font-mono">{err}</div>
+        {/each}
+      </div>
+    {/if}
+
+    {#if importNotes.length}
+      <div class="rounded-lg bg-amber-500/8 border border-amber-500/20 p-3 space-y-1">
+        <div class="text-[10px] font-bold text-amber-700 dark:text-amber-300">
+          Imported with {importNotes.length} adjustment{importNotes.length !== 1 ? "s" : ""}
+        </div>
+        {#each importNotes as note}
+          <div class="text-[10px] text-amber-700/80 dark:text-amber-300/80 leading-relaxed font-mono">{note}</div>
+        {/each}
+      </div>
+    {/if}
+  </div>
+
   <!-- W3C Design Tokens export -->
   <button
     onclick={handleDownloadW3C}
diff --git a/configurator/src/data/token-renames.generated.json b/configurator/src/data/token-renames.generated.json
new file mode 100644
index 00000000..5bb14446
--- /dev/null
+++ b/configurator/src/data/token-renames.generated.json
@@ -0,0 +1,86 @@
+{
+  "_sync": {
+    "generatedBy": "configurator/scripts/sync-api.mjs",
+    "source": "docs/token-renames.json"
+  },
+  "renames": {
+    "--sf-color-primary-light": "--sf-color-primary-source-light",
+    "--sf-color-primary-dark": "--sf-color-primary-source-dark",
+    "--sf-color-secondary-light": "--sf-color-secondary-source-light",
+    "--sf-color-secondary-dark": "--sf-color-secondary-source-dark",
+    "--sf-color-tertiary-light": "--sf-color-tertiary-source-light",
+    "--sf-color-tertiary-dark": "--sf-color-tertiary-source-dark",
+    "--sf-color-action-light": "--sf-color-action-source-light",
+    "--sf-color-action-dark": "--sf-color-action-source-dark",
+    "--sf-color-neutral-light": "--sf-color-neutral-source-light",
+    "--sf-color-neutral-dark": "--sf-color-neutral-source-dark",
+    "--sf-color-base-light": "--sf-color-base-source-light",
+    "--sf-color-base-dark": "--sf-color-base-source-dark",
+    "--sf-color-success-light": "--sf-color-success-source-light",
+    "--sf-color-success-dark": "--sf-color-success-source-dark",
+    "--sf-color-warning-light": "--sf-color-warning-source-light",
+    "--sf-color-warning-dark": "--sf-color-warning-source-dark",
+    "--sf-color-info-light": "--sf-color-info-source-light",
+    "--sf-color-info-dark": "--sf-color-info-source-dark",
+    "--sf-color-danger-light": "--sf-color-danger-source-light",
+    "--sf-color-danger-dark": "--sf-color-danger-source-dark",
+    "--sf-color-error": "--sf-color-danger",
+    "--sf-color-error-subtle": "--sf-color-danger-subtle",
+    "--sf-color-error-muted": "--sf-color-danger-muted",
+    "--sf-color-error-strong": "--sf-color-danger-strong",
+    "--sf-color-error-source-light": "--sf-color-danger-source-light",
+    "--sf-color-error-source-dark": "--sf-color-danger-source-dark",
+    "--sf-color-primary-ghost": "--sf-color-primary-tint",
+    "--sf-color-secondary-ghost": "--sf-color-secondary-tint",
+    "--sf-color-tertiary-ghost": "--sf-color-tertiary-tint",
+    "--sf-color-action-ghost": "--sf-color-action-tint",
+    "--sf-color-neutral-ghost": "--sf-color-neutral-tint",
+    "--sf-color-base-ghost": "--sf-color-base-tint",
+    "--sf-color-base-superlight": "--sf-color-base-50",
+    "--sf-color-base-xlight": "--sf-color-base-200",
+    "--sf-color-base-lighter": "--sf-color-base-400",
+    "--sf-color-base-darker": "--sf-color-base-600",
+    "--sf-color-base-xdark": "--sf-color-base-800",
+    "--sf-color-base-superdark": "--sf-color-base-950",
+    "--sf-color-text--on-surface": "--sf-color-text--on-base",
+    "--sf-color-text--secondary": "--sf-color-text--subtle",
+    "--sf-z-low": "--sf-z-sticky",
+    "--sf-z-mid": "--sf-z-fixed",
+    "--sf-z-high": "--sf-z-dropdown",
+    "--sf-z-top": "--sf-z-toast",
+    "--sf-avatar-size": "--sf-card-avatar-size"
+  },
+  "removals": {
+    "--sf-z-max": "Ambiguous by design: 0.6.0 split the old top rung into --sf-z-overlay (1030) and --sf-z-modal (1040). Pick the one matching your element's role — this is not auto-migrated because the wrong choice silently reorders your stacking context.",
+    "--sf-blur-xs": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-s": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-m": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-l": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-xl": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-opacity-0": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-10": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-25": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-50": "Removed in 0.6.0 — use --sf-opacity-muted (0.5), or a literal value.",
+    "--sf-opacity-75": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-100": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-stroke-thin": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-regular": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-bold": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-heavy": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-col-width-s": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-m": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-l": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-rule-width-s": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-m": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-l": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-font-weight-thin": "Removed in 0.6.0 — write font-weight: 100 inline, or re-tune a role token (--sf-font-weight-{body,heading,display,interactive,strong}).",
+    "--sf-font-weight-extralight": "Removed in 0.6.0 — write font-weight: 200 inline, or re-tune a role token.",
+    "--sf-font-weight-extrabold": "Removed in 0.6.0 — write font-weight: 800 inline, or re-tune a role token.",
+    "--sf-font-weight-black": "Removed in 0.6.0 — write font-weight: 900 inline, or re-tune a role token.",
+    "--sf-fluid-custom-1": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-2": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-3": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-truncate-suffix": "Removed in 0.6.0 — it was never read. .sf-truncate uses text-overflow: ellipsis.",
+    "--sf-corner-scoop-size": "Removed before 1.0 together with the .sf-corner-scoop macro (issue #484): a single absolute size needed per-element tuning to read well at both button and hero scale, and the mask clipped box-shadow/border."
+  }
+}
diff --git a/configurator/src/lib/themeFile.ts b/configurator/src/lib/themeFile.ts
new file mode 100644
index 00000000..09053f80
--- /dev/null
+++ b/configurator/src/lib/themeFile.ts
@@ -0,0 +1,232 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Theme-file import/export for the configurator.
+ *
+ * A theme file is the third persistence form, alongside localStorage
+ * (savedThemes.ts) and the share link (codec.ts). Unlike those two it is a
+ * FILE: keyed by token name, sorted, pretty-printed — something you commit next
+ * to the CSS it themes and review in a pull request.
+ *
+ * This is a browser-side mirror of scripts/lib/theme-file.js. The two are kept
+ * honest by tests/themeFile.test.ts, which runs both implementations over the
+ * same fixtures and asserts identical results. A runtime import of the Node
+ * module is deliberately avoided: the `@framework-css` alias is remapped by the
+ * WordPress plugin to a vendored dist/ that has no scripts/, so reaching
+ * outside this package at runtime would break that build.
+ */
+import RENAME_MAP from "../data/token-renames.generated.json";
+
+export const THEME_SCHEMA_VERSION = 1;
+export const THEME_SCHEMA_URL = "https://slashed.codeslash.dev/schema/theme/v1.json";
+
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
+
+/**
+ * Non-whitespace control characters (C0 + DEL), checked AFTER whitespace has
+ * been collapsed — so tab/newline in a legitimately multi-line value normalise
+ * away rather than being rejected, matching codec.ts's sanitizeValue(). What
+ * remains (ESC, BEL, NUL …) is meaningless in CSS and is rejected.
+ */
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+
+export interface ThemeFile {
+  schemaVersion: number;
+  slashedVersion: string | null;
+  name: string | null;
+  overrides: Record<string, string>;
+}
+
+export interface MigrationReport {
+  overrides: Record<string, string>;
+  renamed: Array<{ from: string; to: string }>;
+  removed: Array<{ name: string; reason: string }>;
+  unknown: string[];
+  collisions: Array<{ from: string; to: string; kept: string }>;
+}
+
+const renames: Record<string, string> = (RENAME_MAP as any).renames ?? {};
+const removals: Record<string, string> = (RENAME_MAP as any).removals ?? {};
+
+/** Sort an object's keys — stable, diff-friendly output. */
+export function sortKeys(obj: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(obj).sort()) out[key] = obj[key];
+  return out;
+}
+
+export function validateThemeFile(raw: unknown): { theme: ThemeFile | null; errors: string[] } {
+  const errors: string[] = [];
+  const fail = (msg: string) => {
+    errors.push(msg);
+    return { theme: null, errors };
+  };
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return fail("theme file must be a JSON object.");
+  }
+
+  const { schemaVersion, overrides, name, slashedVersion } = raw as any;
+
+  if (!Number.isInteger(schemaVersion)) return fail("`schemaVersion` is missing or not an integer.");
+  if (schemaVersion < 1) return fail(`\`schemaVersion\` must be >= 1 (got ${schemaVersion}).`);
+  if (schemaVersion > THEME_SCHEMA_VERSION) {
+    return fail(
+      `\`schemaVersion\` ${schemaVersion} is newer than this SLASHED understands ` +
+        `(max ${THEME_SCHEMA_VERSION}). Upgrade SLASHED to read this file.`,
+    );
+  }
+
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    return fail("`overrides` is missing or not an object.");
+  }
+  if (name != null && typeof name !== "string") errors.push("`name` must be a string when present.");
+  if (typeof name === "string" && CONTROL_CHAR_RE.test(name)) {
+    errors.push("`name` contains control characters.");
+  }
+  if (slashedVersion != null && typeof slashedVersion !== "string") {
+    errors.push("`slashedVersion` must be a string when present.");
+  }
+
+  const clean: Record<string, string> = {};
+  for (const [key, value] of Object.entries(overrides as Record<string, unknown>)) {
+    if (!TOKEN_NAME_RE.test(key)) {
+      errors.push(`overrides["${key}"]: not a well-formed --sf-* token name.`);
+      continue;
+    }
+    if (typeof value !== "string") {
+      errors.push(`overrides["${key}"]: value must be a string (got ${typeof value}).`);
+      continue;
+    }
+    if (UNSAFE_VALUE_RE.test(value)) {
+      errors.push(`overrides["${key}"]: value contains CSS-breaking characters (; { } or comment markers).`);
+      continue;
+    }
+    // Collapse whitespace exactly as codec.ts's sanitizeValue() does, so the
+    // two paths cannot disagree about what a value means.
+    const normalised = value.replace(/\s+/g, " ").trim();
+    if (CONTROL_CHAR_RE.test(normalised)) {
+      errors.push(`overrides["${key}"]: value contains control characters.`);
+      continue;
+    }
+    if (normalised === "") {
+      // An empty override is not a reset — generateCSS() would emit
+      // `--sf-x: ;`, a broken declaration that shadows the real token with
+      // nothing. codec.ts already drops empty values on encode and decode.
+      errors.push(`overrides["${key}"]: value is empty. Remove the entry to leave the token at its default.`);
+      continue;
+    }
+    clean[key] = normalised;
+  }
+
+  if (errors.length) return { theme: null, errors };
+
+  return {
+    theme: {
+      schemaVersion,
+      slashedVersion: typeof slashedVersion === "string" ? slashedVersion : null,
+      name: typeof name === "string" ? name : null,
+      overrides: clean,
+    },
+    errors: [],
+  };
+}
+
+export function parseThemeFile(text: string): { theme: ThemeFile | null; errors: string[] } {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err: any) {
+    return { theme: null, errors: [`not valid JSON (${err.message}).`] };
+  }
+  return validateThemeFile(raw);
+}
+
+/**
+ * Migrate an override set onto the current token API. Never discards an
+ * override it does not recognise — unknown names are reported and kept.
+ */
+export function migrateOverrides(
+  overrides: Record<string, string>,
+  opts: { live?: Set<string> } = {},
+): MigrationReport {
+  const out: Record<string, string> = {};
+  const renamed: MigrationReport["renamed"] = [];
+  const removed: MigrationReport["removed"] = [];
+  const unknown: string[] = [];
+  const collisions: MigrationReport["collisions"] = [];
+
+  for (const key of Object.keys(overrides).sort()) {
+    const value = overrides[key];
+
+    if (Object.prototype.hasOwnProperty.call(removals, key)) {
+      removed.push({ name: key, reason: removals[key] });
+      continue;
+    }
+
+    const target = renames[key];
+    if (target) {
+      if (Object.prototype.hasOwnProperty.call(overrides, target)) {
+        collisions.push({ from: key, to: target, kept: overrides[target] });
+        continue;
+      }
+      // Two different old names can resolve to the same live token (the map
+      // contains such pairs). Without this branch the later key would silently
+      // overwrite the earlier one. Sorted iteration makes first-claim-wins
+      // deterministic.
+      if (Object.prototype.hasOwnProperty.call(out, target)) {
+        collisions.push({ from: key, to: target, kept: out[target] });
+        continue;
+      }
+      out[target] = value;
+      renamed.push({ from: key, to: target });
+      continue;
+    }
+
+    if (opts.live && !opts.live.has(key)) unknown.push(key);
+    out[key] = value;
+  }
+
+  return { overrides: sortKeys(out), renamed, removed, unknown, collisions };
+}
+
+export function serializeThemeFile(theme: {
+  overrides: Record<string, string>;
+  name?: string;
+  slashedVersion?: string;
+}): string {
+  const doc = {
+    $schema: THEME_SCHEMA_URL,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    ...(theme.slashedVersion ? { slashedVersion: theme.slashedVersion } : {}),
+    ...(theme.name ? { name: theme.name } : {}),
+    overrides: sortKeys(theme.overrides ?? {}),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/**
+ * Read a user-selected file and return the migrated override set plus a
+ * human-readable summary of what changed on the way in.
+ */
+export async function importThemeFile(
+  file: File,
+  live?: Set<string>,
+): Promise<{ overrides: Record<string, string> | null; name: string | null; errors: string[]; notes: string[] }> {
+  const text = await file.text();
+  const { theme, errors } = parseThemeFile(text);
+  if (!theme) return { overrides: null, name: null, errors, notes: [] };
+
+  const result = migrateOverrides(theme.overrides, { live });
+  const notes: string[] = [];
+  for (const { from, to } of result.renamed) notes.push(`renamed ${from} → ${to}`);
+  for (const { from, to } of result.collisions) notes.push(`dropped ${from} (${to} already set)`);
+  for (const { name, reason } of result.removed) notes.push(`removed ${name} — ${reason}`);
+  for (const name of result.unknown) notes.push(`unknown ${name} (kept)`);
+
+  return { overrides: result.overrides, name: theme.name, errors: [], notes };
+}
diff --git a/configurator/tests/themeFile.test.ts b/configurator/tests/themeFile.test.ts
new file mode 100644
index 00000000..379c0322
--- /dev/null
+++ b/configurator/tests/themeFile.test.ts
@@ -0,0 +1,191 @@
+/**
+ * Theme-file import/export, plus the parity contract with the framework's
+ * Node implementation.
+ *
+ * src/lib/themeFile.ts and scripts/lib/theme-file.js are two implementations of
+ * one format. They exist separately on purpose (the configurator cannot import
+ * across the package boundary at runtime — see the header of themeFile.ts), so
+ * the drift risk is real and has to be tested rather than commented about.
+ *
+ * Vitest runs in Node, so this test — unlike the shipped bundle — CAN import
+ * both and run them over the same fixtures.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  THEME_SCHEMA_VERSION,
+  parseThemeFile,
+  migrateOverrides,
+  serializeThemeFile,
+  validateThemeFile,
+} from "../src/lib/themeFile";
+import * as node from "../../scripts/lib/theme-file.js";
+import renameMap from "../src/data/token-renames.generated.json";
+
+/** The rename map as the Node implementation takes it (it is passed explicitly there). */
+const nodeOpts = {
+  renames: (renameMap as any).renames,
+  removals: (renameMap as any).removals,
+};
+
+const FIXTURES: Array<{ label: string; raw: unknown }> = [
+  {
+    label: "well-formed minimal",
+    raw: { schemaVersion: 1, overrides: { "--sf-color-primary-source-light": "#3b5bdb" } },
+  },
+  {
+    label: "legacy names needing migration",
+    raw: {
+      schemaVersion: 1,
+      slashedVersion: "0.6.10",
+      name: "Acme",
+      overrides: {
+        "--sf-color-primary-light": "#3b5bdb",
+        "--sf-color-error": "#e03131",
+        "--sf-opacity-25": "0.25",
+        "--sf-radius-m": "10px",
+      },
+    },
+  },
+  { label: "not an object", raw: "nope" },
+  { label: "missing schemaVersion", raw: { overrides: {} } },
+  { label: "future schemaVersion", raw: { schemaVersion: 99, overrides: {} } },
+  { label: "bad token name", raw: { schemaVersion: 1, overrides: { "color-primary": "red" } } },
+  {
+    label: "CSS-breaking value",
+    raw: { schemaVersion: 1, overrides: { "--sf-color-primary": "red; background: url(x)" } },
+  },
+  { label: "non-string value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": 10 } } },
+  // PR #671 review regressions — both implementations must agree on these.
+  { label: "empty value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "" } } },
+  { label: "whitespace-only value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "   " } } },
+  {
+    label: "control chars in value",
+    raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "10px\u001b[2J" } },
+  },
+  {
+    label: "control chars in name",
+    raw: { schemaVersion: 1, name: "Acme\u001b[31m", overrides: { "--sf-radius-m": "10px" } },
+  },
+  {
+    label: "multi-line value normalises rather than failing",
+    raw: { schemaVersion: 1, overrides: { "--sf-shadow-m": "0 1px 2px #0001,\n  0 2px 4px #0002" } },
+  },
+];
+
+describe("parity with scripts/lib/theme-file.js", () => {
+  test("the schema version matches", () => {
+    expect(THEME_SCHEMA_VERSION).toBe(node.THEME_SCHEMA_VERSION);
+  });
+
+  test.each(FIXTURES)("validate agrees on: $label", ({ raw }) => {
+    const mine = validateThemeFile(raw);
+    const theirs = node.validateThemeFile(raw);
+    expect(mine.theme).toEqual(theirs.theme);
+    expect(mine.errors).toEqual(theirs.errors);
+  });
+
+  test.each(FIXTURES)("migrate agrees on: $label", ({ raw }) => {
+    const mine = validateThemeFile(raw);
+    if (!mine.theme) return; // invalid fixtures are covered by the validate test
+    const live = new Set(["--sf-radius-m", "--sf-color-primary-source-light"]);
+    expect(migrateOverrides(mine.theme.overrides, { live })).toEqual(
+      node.migrateOverrides(mine.theme.overrides, { ...nodeOpts, live }),
+    );
+  });
+
+  test("serialize produces byte-identical output", () => {
+    const args = {
+      overrides: { "--sf-b": "2", "--sf-a": "1" },
+      name: "Acme",
+      slashedVersion: "0.7.31",
+    };
+    expect(serializeThemeFile(args)).toBe(node.serializeThemeFile(args));
+  });
+});
+
+describe("value hygiene", () => {
+  test("an empty or whitespace-only value is refused, not imported as an empty override", () => {
+    // Would otherwise reach generateCSS() and emit `--sf-x: ;`.
+    for (const bad of ["", "   "]) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { "--sf-radius-m": bad },
+      });
+      expect(theme).toBeNull();
+      expect(errors.join(" ")).toMatch(/value is empty/);
+    }
+  });
+
+  test("control characters are refused", () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { "--sf-radius-m": "10px\u001b[2J" },
+    });
+    expect(theme).toBeNull();
+    expect(errors.join(" ")).toMatch(/control characters/);
+  });
+
+  test("a multi-line value is normalised, not rejected", () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { "--sf-shadow-m": "0 1px 2px #0001,\n  0 2px 4px #0002" },
+    });
+    expect(errors).toEqual([]);
+    expect(theme?.overrides["--sf-shadow-m"]).toBe("0 1px 2px #0001, 0 2px 4px #0002");
+  });
+});
+
+describe("theme file round-trip", () => {
+  test("serialize → parse preserves the override set", () => {
+    const overrides = { "--sf-color-primary-source-light": "#3b5bdb", "--sf-radius-m": "10px" };
+    const { theme, errors } = parseThemeFile(serializeThemeFile({ overrides, name: "Acme" }));
+    expect(errors).toEqual([]);
+    expect(theme?.overrides).toEqual(overrides);
+    expect(theme?.name).toBe("Acme");
+  });
+
+  test("output is key-order independent", () => {
+    const a = serializeThemeFile({ overrides: { "--sf-b": "2", "--sf-a": "1" } });
+    const b = serializeThemeFile({ overrides: { "--sf-a": "1", "--sf-b": "2" } });
+    expect(a).toBe(b);
+  });
+});
+
+describe("migration on import", () => {
+  test("rewrites renamed tokens using the synced map", () => {
+    const r = migrateOverrides({ "--sf-color-error": "#e03131" });
+    expect(r.overrides).toEqual({ "--sf-color-danger": "#e03131" });
+    expect(r.renamed).toEqual([{ from: "--sf-color-error", to: "--sf-color-danger" }]);
+  });
+
+  test("drops removed tokens with a reason", () => {
+    const r = migrateOverrides({ "--sf-opacity-25": "0.25" });
+    expect(r.overrides).toEqual({});
+    expect(r.removed[0].name).toBe("--sf-opacity-25");
+    expect(r.removed[0].reason).toBeTruthy();
+  });
+
+  test("keeps an unknown token rather than discarding user data", () => {
+    const r = migrateOverrides({ "--sf-mystery": "1rem" }, { live: new Set(["--sf-radius-m"]) });
+    expect(r.overrides).toEqual({ "--sf-mystery": "1rem" });
+    expect(r.unknown).toEqual(["--sf-mystery"]);
+  });
+
+  test("reports a collision when two old names resolve to one target", () => {
+    // Real pair in the shipped map: both land on --sf-color-danger-source-light.
+    const r = migrateOverrides({
+      "--sf-color-danger-light": "#aaa",
+      "--sf-color-error-source-light": "#bbb",
+    });
+    expect(r.overrides).toEqual({ "--sf-color-danger-source-light": "#aaa" });
+    expect(r.collisions).toHaveLength(1);
+    expect(r.collisions[0].kept).toBe("#aaa");
+  });
+
+  test("is idempotent", () => {
+    const once = migrateOverrides({ "--sf-color-error": "#e03131" });
+    const twice = migrateOverrides(once.overrides);
+    expect(twice.overrides).toEqual(once.overrides);
+    expect(twice.renamed).toEqual([]);
+  });
+});
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2f8be674..2e8b254e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -125,6 +125,44 @@ whole dark palette derive from those six. Prefer to design visually? Open the
 [configurator](https://slashed.codeslash.dev/configurator/) and export the
 override CSS.
 
+### Keeping a theme as a file
+
+Alongside the override CSS, the configurator exports a **theme file** —
+`slashed-theme.json`, a sorted, name-keyed snapshot of your overrides:
+
+```json
+{
+  "$schema": "https://slashed.codeslash.dev/schema/theme/v1.json",
+  "schemaVersion": 1,
+  "slashedVersion": "0.7.31",
+  "name": "Acme Corp",
+  "overrides": {
+    "--sf-color-primary-source-light": "#3b5bdb"
+  }
+}
+```
+
+Unlike a share link (compressed, opaque) this is meant to be committed next to
+the CSS it themes: a `git diff` shows exactly which token changed value, so a
+rebrand is reviewable in a pull request. Import it back into the configurator at
+any time.
+
+When you upgrade SLASHED, a theme file written against an older version is
+migrated onto the current token names **on import** — just load it in the
+configurator and it is brought forward automatically. Renamed tokens are
+rewritten, removed ones are dropped with an explanation of what to use instead,
+and anything unrecognised is reported but left untouched: the migration never
+silently discards your data. The panel lists every adjustment it made.
+
+Working inside a clone of this repository, the same migration is available as a
+CLI, which is useful for migrating committed theme files in bulk or as a CI
+check (it exits non-zero when a file needs migrating):
+
+```bash
+npm run migrate:theme -- acme.slashed-theme.json          # report what would change
+npm run migrate:theme -- acme.slashed-theme.json --write  # apply
+```
+
 ---
 
 ## 6. The one rule that matters
diff --git a/docs/token-renames.json b/docs/token-renames.json
new file mode 100644
index 00000000..dd4da16f
--- /dev/null
+++ b/docs/token-renames.json
@@ -0,0 +1,109 @@
+{
+  "_meta": {
+    "purpose": "Machine-readable map of token names that changed or disappeared, so a theme file authored against an older SLASHED can be migrated forward automatically.",
+    "sourceOfTruth": "docs/migration.md — this file is its machine-readable mirror. Every entry here corresponds to a documented breaking change; do not add an entry that migration.md does not describe.",
+    "whyNotTheRegistry": "token-registry.json cannot answer this. Its ids are permanent, but check-token-registry.js explicitly permits renames as IN-PLACE name updates on the same id — so after a rename the old name is simply gone from the registry, with nothing to look it up by. That is harmless for the share-link codec (it stores ids, not names) but fatal for a name-keyed theme file. Renames are a human fact and cannot be derived from the catalogue: a rename and a (delete + add) pair are indistinguishable to a generator.",
+    "contract": "Every value in `renames` must be a LIVE token, and no key in `renames` or `removals` may be live. Enforced by scripts/check-token-renames.js. Because a rename target must be live, chains are impossible by construction — always record the fully resolved destination, never an intermediate name.",
+    "consumedBy": [
+      "scripts/migrate-theme.js",
+      "scripts/lib/theme-file.js",
+      "configurator (via configurator/src/data/token-renames.generated.json)"
+    ]
+  },
+
+  "renames": {
+    "--sf-color-primary-light": "--sf-color-primary-source-light",
+    "--sf-color-primary-dark": "--sf-color-primary-source-dark",
+    "--sf-color-secondary-light": "--sf-color-secondary-source-light",
+    "--sf-color-secondary-dark": "--sf-color-secondary-source-dark",
+    "--sf-color-tertiary-light": "--sf-color-tertiary-source-light",
+    "--sf-color-tertiary-dark": "--sf-color-tertiary-source-dark",
+    "--sf-color-action-light": "--sf-color-action-source-light",
+    "--sf-color-action-dark": "--sf-color-action-source-dark",
+    "--sf-color-neutral-light": "--sf-color-neutral-source-light",
+    "--sf-color-neutral-dark": "--sf-color-neutral-source-dark",
+    "--sf-color-base-light": "--sf-color-base-source-light",
+    "--sf-color-base-dark": "--sf-color-base-source-dark",
+    "--sf-color-success-light": "--sf-color-success-source-light",
+    "--sf-color-success-dark": "--sf-color-success-source-dark",
+    "--sf-color-warning-light": "--sf-color-warning-source-light",
+    "--sf-color-warning-dark": "--sf-color-warning-source-dark",
+    "--sf-color-info-light": "--sf-color-info-source-light",
+    "--sf-color-info-dark": "--sf-color-info-source-dark",
+    "--sf-color-danger-light": "--sf-color-danger-source-light",
+    "--sf-color-danger-dark": "--sf-color-danger-source-dark",
+
+    "--sf-color-error": "--sf-color-danger",
+    "--sf-color-error-subtle": "--sf-color-danger-subtle",
+    "--sf-color-error-muted": "--sf-color-danger-muted",
+    "--sf-color-error-strong": "--sf-color-danger-strong",
+    "--sf-color-error-source-light": "--sf-color-danger-source-light",
+    "--sf-color-error-source-dark": "--sf-color-danger-source-dark",
+
+    "--sf-color-primary-ghost": "--sf-color-primary-tint",
+    "--sf-color-secondary-ghost": "--sf-color-secondary-tint",
+    "--sf-color-tertiary-ghost": "--sf-color-tertiary-tint",
+    "--sf-color-action-ghost": "--sf-color-action-tint",
+    "--sf-color-neutral-ghost": "--sf-color-neutral-tint",
+    "--sf-color-base-ghost": "--sf-color-base-tint",
+
+    "--sf-color-base-superlight": "--sf-color-base-50",
+    "--sf-color-base-xlight": "--sf-color-base-200",
+    "--sf-color-base-lighter": "--sf-color-base-400",
+    "--sf-color-base-darker": "--sf-color-base-600",
+    "--sf-color-base-xdark": "--sf-color-base-800",
+    "--sf-color-base-superdark": "--sf-color-base-950",
+
+    "--sf-color-text--on-surface": "--sf-color-text--on-base",
+    "--sf-color-text--secondary": "--sf-color-text--subtle",
+
+    "--sf-z-low": "--sf-z-sticky",
+    "--sf-z-mid": "--sf-z-fixed",
+    "--sf-z-high": "--sf-z-dropdown",
+    "--sf-z-top": "--sf-z-toast",
+
+    "--sf-avatar-size": "--sf-card-avatar-size"
+  },
+
+  "removals": {
+    "--sf-z-max": "Ambiguous by design: 0.6.0 split the old top rung into --sf-z-overlay (1030) and --sf-z-modal (1040). Pick the one matching your element's role — this is not auto-migrated because the wrong choice silently reorders your stacking context.",
+
+    "--sf-blur-xs": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-s": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-m": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-l": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-xl": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+
+    "--sf-opacity-0": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-10": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-25": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-50": "Removed in 0.6.0 — use --sf-opacity-muted (0.5), or a literal value.",
+    "--sf-opacity-75": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-100": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+
+    "--sf-stroke-thin": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-regular": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-bold": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-heavy": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+
+    "--sf-col-width-s": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-m": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-l": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-rule-width-s": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-m": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-l": "Removed in 0.6.0 — set the column-rule-width property directly.",
+
+    "--sf-font-weight-thin": "Removed in 0.6.0 — write font-weight: 100 inline, or re-tune a role token (--sf-font-weight-{body,heading,display,interactive,strong}).",
+    "--sf-font-weight-extralight": "Removed in 0.6.0 — write font-weight: 200 inline, or re-tune a role token.",
+    "--sf-font-weight-extrabold": "Removed in 0.6.0 — write font-weight: 800 inline, or re-tune a role token.",
+    "--sf-font-weight-black": "Removed in 0.6.0 — write font-weight: 900 inline, or re-tune a role token.",
+
+    "--sf-fluid-custom-1": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-2": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-3": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+
+    "--sf-truncate-suffix": "Removed in 0.6.0 — it was never read. .sf-truncate uses text-overflow: ellipsis.",
+
+    "--sf-corner-scoop-size": "Removed before 1.0 together with the .sf-corner-scoop macro (issue #484): a single absolute size needed per-element tuning to read well at both button and hero scale, and the mask clipped box-shadow/border."
+  }
+}
diff --git a/optional/components.css b/optional/components.css
index 715167b9..555eeffc 100644
--- a/optional/components.css
+++ b/optional/components.css
@@ -444,7 +444,7 @@
           oklch(from var(--sf-color-neutral-source-light) clamp(0.05, calc(l - 0.4 - var(--sf-contrast-bias)), 0.35) c h),
           oklch(from var(--sf-color-neutral)              clamp(0.70, calc(l + 0.25 + var(--sf-contrast-bias)), 1)    c h));
         --sf-color-text: var(--sf-color-heading);
-        --sf-color-text--secondary: light-dark(
+        --sf-color-text--subtle: light-dark(
           oklch(from var(--sf-color-neutral-source-light) clamp(0.15, calc(l - 0.25 - var(--sf-contrast-bias)), 0.45) c h),
           oklch(from var(--sf-color-neutral)              clamp(0.55, calc(l + 0.1 + var(--sf-contrast-bias)), 0.90) c h));
         --sf-color-border: light-dark(
diff --git a/package.json b/package.json
index f99a4af0..d207f074 100644
--- a/package.json
+++ b/package.json
@@ -48,6 +48,9 @@
     "check:hook-tokens": "node scripts/check-hook-tokens.js",
     "check:mirrors": "node scripts/check-mirrors.js",
     "check:bundle-defs": "node scripts/check-bundle-defs.js",
+    "check:forbidden-strings": "node scripts/check-forbidden-strings.js --check",
+    "check:token-renames": "node scripts/check-token-renames.js",
+    "migrate:theme": "node scripts/migrate-theme.js",
     "configurator:sync": "node configurator/scripts/sync-api.mjs",
     "docs:tokens": "node scripts/gen-token-reference.js",
     "docs:index": "node scripts/gen-token-index.js",
diff --git a/scripts/artifacts.json b/scripts/artifacts.json
index 8bbd936f..462318b5 100644
--- a/scripts/artifacts.json
+++ b/scripts/artifacts.json
@@ -16,18 +16,20 @@
       "configurator/src/data/api-index.generated.json",
       "configurator/src/data/classes.generated.json",
       "configurator/src/data/bundles.generated.json",
-      "configurator/src/data/token-registry.generated.json"
+      "configurator/src/data/token-registry.generated.json",
+      "configurator/src/data/token-renames.generated.json"
     ]
   },
   {
     "name": "configurator api sync",
-    "srcPrefixes": ["docs/token-annotations.json", "docs/api-index.json", "bundle.config.json", "token-registry.json"],
+    "srcPrefixes": ["docs/token-annotations.json", "docs/api-index.json", "bundle.config.json", "token-registry.json", "docs/token-renames.json"],
     "buildCmd": "npm run configurator:sync",
     "outputs": [
       "configurator/src/data/api-index.generated.json",
       "configurator/src/data/classes.generated.json",
       "configurator/src/data/bundles.generated.json",
-      "configurator/src/data/token-registry.generated.json"
+      "configurator/src/data/token-registry.generated.json",
+      "configurator/src/data/token-renames.generated.json"
     ]
   }
 ]
diff --git a/scripts/check-forbidden-strings.js b/scripts/check-forbidden-strings.js
new file mode 100644
index 00000000..b9d200e9
--- /dev/null
+++ b/scripts/check-forbidden-strings.js
@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * CI gate: strings that must never ship.
+ *
+ * The other check:* gates all answer "is X still in sync with Y?" — they prove
+ * generated artifacts match their sources (check-artifacts), that docs only
+ * name live API (check-doc-refs, check-llm-guide), that ids are permanent
+ * (check-token-registry). None of them can answer the different question this
+ * gate exists for: "did something get into the source or the shipped bundle
+ * that has no business being there at all?"
+ *
+ * Two framework promises are currently honour-system only:
+ *
+ *   1. "Every visual value is a named token; hardcoded numbers are treated as
+ *      bugs" (README, CLAUDE.md). Nothing stops a literal `#3b5bdb` landing in
+ *      core/macros.css — it would pass every existing gate.
+ *   2. "Standalone — no runtime dependencies", "no external requests". Nothing
+ *      stops a `@import url(https://fonts.googleapis.com/…)` reaching a dist
+ *      bundle, which would silently make every consumer's page phone home.
+ *
+ * Both are exactly the class of regression that is cheap to prevent and
+ * expensive to notice later. This gate turns each promise into a mechanical
+ * check over the source tree AND the built bundles.
+ *
+ * Deliberate exceptions are recorded per rule in ALLOW, each with a reason —
+ * same contract as docs/ref-allowlist.json. An unexplained exception is not
+ * possible: the allow entry IS the explanation, and it names the exact matched
+ * text, not just the file, so a second unrelated violation in an
+ * already-excepted file still fails.
+ *
+ * Run:
+ *   node scripts/check-forbidden-strings.js          # report, exit 0
+ *   node scripts/check-forbidden-strings.js --check  # report, exit 1 on any hit
+ *   npm run check:forbidden-strings                  # the --check form (CI)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { maskComments } from './lib/parse.js';
+
+// SLASHED_ROOT lets the negative tests run this gate against a fixture tree.
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const checkMode = process.argv.includes('--check');
+
+/**
+ * Files whose entire job is to declare raw values — the bottom of the token
+ * stack, where a literal colour is the definition, not a shortcut.
+ */
+const TOKEN_SOURCE_FILES = [
+  'core/tokens.css',
+  'core/tokens.layout.css',
+  'core/tokens.macros.css',
+  'optional/tokens.components.css',
+];
+
+/**
+ * @typedef {object} Rule
+ * @property {string}   id          stable slug, used in output and in ALLOW
+ * @property {string}   label       one-line description of what was found
+ * @property {string}   why         what breaks if this ships (printed on failure)
+ * @property {RegExp}   pattern     global regex; every match is a candidate hit
+ * @property {string[]} targets     path prefixes to walk, relative to ROOT
+ * @property {string[]} extensions  file extensions to read
+ * @property {string[]} [exclude]   exact relative paths to skip entirely
+ * @property {boolean}  [maskComments] blank comment bodies before matching
+ *                                  (offset-preserving, so line numbers still
+ *                                  point at the original source)
+ */
+
+/** @type {Rule[]} */
+const RULES = [
+  {
+    id: 'hardcoded-color',
+    label: 'hardcoded colour literal outside the token source files',
+    why:
+      'The framework promises every visual value is a named token. A literal colour ' +
+      'here cannot be rebranded, cannot participate in the light-dark() / oklch() ' +
+      'derivation chain, and will not follow a consumer\'s theme.',
+    // Hex literals, the legacy colour functions, and the modern ones.
+    //
+    // The modern functions need a lookahead: oklch(from …) and oklch(var(…))
+    // are the DERIVATION syntax the whole token layer is built on, not
+    // hardcoded values — flagging those would condemn the architecture. A
+    // direct oklch(0.6 0.25 30) is a literal like any other and is flagged.
+    // color-mix( is unaffected: \bcolor\( cannot match across the "-mix".
+    pattern:
+      /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(|\b(?:hwb|lab|lch|oklab|oklch|color)\(\s*(?!from\b|var\()/gi,
+    targets: ['core/', 'optional/'],
+    extensions: ['.css'],
+    exclude: [
+      ...TOKEN_SOURCE_FILES,
+      // A copy-and-customise starter that ships in no bundle (see its own
+      // header, and bundle.config.json). Literal brand colours are the point
+      // of the file — they are what a user replaces.
+      'optional/customize-example.css',
+    ],
+    maskComments: true,
+  },
+  {
+    id: 'external-url',
+    label: 'external URL in a shipped bundle',
+    why:
+      'A shipped bundle must never cause a network request. Any absolute URL here ' +
+      'means every consumer page silently fetches from a third party — breaking the ' +
+      '"standalone, no external requests" guarantee and leaking visitor IPs.',
+    // (?:https?:)? — a protocol-relative //host/path is a real external
+    // request too: CSS accepts @import url(//fonts.example/x.css) and the
+    // browser fetches it using the page's scheme.
+    pattern: /(?:https?:)?\/\/[^\s"')]+/gi,
+    targets: ['dist/'],
+    extensions: ['.css'],
+    // Deliberately NOT comment-masked: a URL in a bundle banner is still a URL
+    // shipped to consumers, and should be a recorded decision.
+  },
+  {
+    id: 'debug-statement',
+    label: 'debug statement left in configurator source',
+    why:
+      'console.log/debug and debugger statements are development leftovers. They ship ' +
+      'to the deployed configurator, clutter the console, and can leak internal state. ' +
+      'Diagnostics that are meant to survive belong in console.warn/error.',
+    pattern: /\bconsole\s*\.\s*(?:log|debug)\s*\(|\bdebugger\b/g,
+    targets: ['configurator/src/'],
+    extensions: ['.ts', '.svelte', '.js'],
+    // scripts/ is deliberately out of scope: those are CLIs whose console.log
+    // IS their output.
+  },
+];
+
+/**
+ * Deliberate, reasoned exceptions.
+ *
+ * Shape: ALLOW[ruleId][relativePath][exactMatchedText] = reason.
+ *
+ * Keyed by the matched TEXT, not just the file, so excepting `#fff` in a file
+ * does not blanket-approve a future `#3b5bdb` in that same file.
+ */
+const ALLOW = {
+  'hardcoded-color': {
+    'core/base.css': {
+      '#fff':
+        'var() fallback of last resort — renders readable if the token layer ' +
+        'failed to load entirely. Not a themeable value by definition.',
+    },
+    'optional/components.css': {
+      '#000':
+        'linear-gradient(#000 0 0) mask stops — a mask reads only the alpha ' +
+        'channel, so the colour is structurally inert and tokenising it would ' +
+        'imply a themeable value that does not exist.',
+    },
+  },
+  'external-url': {
+    'dist/slashed.full.css': {
+      'http://www.w3.org/2000/svg':
+        'XML namespace identifier inside an inline SVG data: URI. Namespaces are ' +
+        'never dereferenced — no network request is made.',
+    },
+  },
+};
+
+// The same inline-SVG namespace appears in every bundle variant; mirror the one
+// documented exception across them rather than repeating the reason four times.
+for (const variant of [
+  'dist/slashed.optimal.css',
+  'dist/slashed.full.flat.css',
+  'dist/slashed.optimal.flat.css',
+  'dist/slashed.full.min.css',
+  'dist/slashed.optimal.min.css',
+  'dist/slashed.full.flat.min.css',
+  'dist/slashed.optimal.flat.min.css',
+]) {
+  ALLOW['external-url'][variant] = ALLOW['external-url']['dist/slashed.full.css'];
+}
+
+/**
+ * Collect every file under a rule's targets matching its extensions.
+ * A target may be a directory prefix ("core/") or an exact file.
+ * @param {Rule} rule
+ * @returns {string[]} repo-relative paths, sorted
+ */
+function collectFiles(rule) {
+  const out = new Set();
+  const exclude = new Set(rule.exclude ?? []);
+
+  const visit = (abs, rel) => {
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      return; // target absent (e.g. dist/ before a build) — nothing to scan
+    }
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(abs)) {
+        if (entry === 'node_modules' || entry.startsWith('.')) continue;
+        visit(path.join(abs, entry), rel ? `${rel}/${entry}` : entry);
+      }
+      return;
+    }
+    if (!rule.extensions.some((ext) => rel.endsWith(ext))) return;
+    if (exclude.has(rel)) return;
+    out.add(rel);
+  };
+
+  for (const target of rule.targets) {
+    const clean = target.replace(/\/$/, '');
+    visit(path.join(ROOT, clean), clean);
+  }
+  return [...out].sort();
+}
+
+/** 1-based line number of a character offset. */
+function lineAt(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) {
+    if (text[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Run one rule over the tree.
+ * @param {Rule} rule
+ * @returns {{ rule: Rule, hits: Array<{file:string,line:number,text:string}>, allowed: number, scanned: number }}
+ */
+function runRule(rule) {
+  const hits = [];
+  let allowed = 0;
+  const files = collectFiles(rule);
+
+  for (const rel of files) {
+    const raw = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    // maskComments blanks comment bodies with same-length whitespace, so match
+    // offsets still line up with the original file's line numbering.
+    const haystack = rule.maskComments ? maskComments(raw) : raw;
+    const allowForFile = ALLOW[rule.id]?.[rel] ?? {};
+
+    rule.pattern.lastIndex = 0;
+    for (const match of haystack.matchAll(rule.pattern)) {
+      const text = match[0];
+      if (Object.prototype.hasOwnProperty.call(allowForFile, text)) {
+        allowed++;
+        continue;
+      }
+      hits.push({ file: rel, line: lineAt(haystack, match.index ?? 0), text });
+    }
+  }
+
+  return { rule, hits, allowed, scanned: files.length };
+}
+
+const results = RULES.map(runRule);
+const failing = results.filter((r) => r.hits.length > 0);
+
+if (failing.length) {
+  console.error('check:forbidden-strings FAILED:\n');
+  for (const { rule, hits } of failing) {
+    console.error(`  [${rule.id}] ${rule.label}`);
+    console.error(`  ${rule.why}\n`);
+    for (const hit of hits) {
+      console.error(`    ${hit.file}:${hit.line}  ${hit.text}`);
+    }
+    console.error('');
+  }
+  console.error(
+    'If a match is deliberate, add it to ALLOW in scripts/check-forbidden-strings.js\n' +
+      'keyed by rule id → file → the exact matched text, with a reason explaining why\n' +
+      'it is safe. An exception without a reason is not an exception.',
+  );
+  if (checkMode) process.exit(1);
+} else {
+  const summary = results
+    .map((r) => `${r.rule.id}: ${r.scanned} file(s)${r.allowed ? `, ${r.allowed} allowed` : ''}`)
+    .join('; ');
+  console.log(`check:forbidden-strings OK — ${summary}.`);
+}
diff --git a/scripts/check-token-renames.js b/scripts/check-token-renames.js
new file mode 100644
index 00000000..9e44db48
--- /dev/null
+++ b/scripts/check-token-renames.js
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * CI gate for docs/token-renames.json — the map that lets an old theme file be
+ * migrated onto the current token set.
+ *
+ * A rename map is only useful if it is TRUE, and it decays silently: a target
+ * token that is later renamed again turns the map into a machine that migrates
+ * users onto a dead name. This gate holds three invariants:
+ *
+ *   1. Every rename TARGET is live. This is what makes the map trustworthy —
+ *      and it forbids chains by construction: if `a → b` and `b → c` were both
+ *      recorded, `b` would be a rename key and therefore not live, so the gate
+ *      fires. Always record the fully resolved destination.
+ *   2. No rename KEY is live. A live old name means the rename never happened,
+ *      was reverted, or the name was recycled for something new — in every case
+ *      migrating away from it would corrupt a working theme.
+ *   3. No removal KEY is live, and removals and renames are disjoint. A token
+ *      cannot be both "gone, here's advice" and "silently rewritten".
+ *
+ * "Live" comes from scripts/lib/live-api.js — the same definition
+ * check-doc-refs.js and check-llm-guide.js use, so all three gates agree on
+ * what the current API is.
+ *
+ * Run:
+ *   node scripts/check-token-renames.js
+ *   npm run check:token-renames
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveTokens } from './lib/live-api.js';
+
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const MAP_FILE = path.join(ROOT, 'docs', 'token-renames.json');
+
+if (!fs.existsSync(MAP_FILE)) {
+  console.error(`check:token-renames FAILED: ${MAP_FILE} not found.`);
+  process.exit(1);
+}
+
+let map;
+try {
+  map = JSON.parse(fs.readFileSync(MAP_FILE, 'utf8'));
+} catch (err) {
+  console.error(`check:token-renames FAILED: docs/token-renames.json is not valid JSON (${err.message}).`);
+  process.exit(1);
+}
+
+const errors = [];
+
+/**
+ * A section must be a plain object. An array passes `typeof x === 'object'`
+ * and yields no entries, so `{"renames": []}` would sail through every
+ * downstream check and leave the CLI silently migrating nothing.
+ */
+function readSection(name) {
+  const value = map[name];
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`\`${name}\` must be an object (got ${Array.isArray(value) ? 'an array' : typeof value}).`);
+    return {};
+  }
+  return value;
+}
+
+if (!map || typeof map !== 'object' || Array.isArray(map)) {
+  console.error('check:token-renames FAILED: docs/token-renames.json must be a JSON object.');
+  process.exit(1);
+}
+
+const renames = readSection('renames');
+const removals = readSection('removals');
+
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+
+// Shape checks first — a malformed entry would otherwise produce a confusing
+// "not live" error for a name that was never well-formed.
+for (const [from, to] of Object.entries(renames)) {
+  if (!TOKEN_NAME_RE.test(from)) errors.push(`rename key "${from}" is not a well-formed --sf-* token name.`);
+  if (typeof to !== 'string' || !TOKEN_NAME_RE.test(to)) {
+    errors.push(`rename target for "${from}" ("${to}") is not a well-formed --sf-* token name.`);
+  }
+  if (from === to) errors.push(`rename "${from}" maps to itself.`);
+}
+for (const [name, reason] of Object.entries(removals)) {
+  if (!TOKEN_NAME_RE.test(name)) errors.push(`removal key "${name}" is not a well-formed --sf-* token name.`);
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    errors.push(`removal "${name}" has no reason — every removal must say what to use instead.`);
+  }
+}
+
+// ── 3 (part): renames and removals must be disjoint ──────────────────────────
+for (const name of Object.keys(removals)) {
+  if (Object.prototype.hasOwnProperty.call(renames, name)) {
+    errors.push(
+      `"${name}" appears in BOTH renames and removals — it cannot be silently rewritten and manually resolved at the same time.`,
+    );
+  }
+}
+
+const live = buildLiveTokens(ROOT);
+
+// ── 1: every rename target is live (and, by consequence, no chains) ──────────
+for (const [from, to] of Object.entries(renames)) {
+  if (typeof to !== 'string' || !live.has(to)) {
+    const chained = Object.prototype.hasOwnProperty.call(renames, to);
+    errors.push(
+      chained
+        ? `rename "${from}" → "${to}" points at another rename key — record the fully resolved destination (${renames[to]}) instead of a chain.`
+        : `rename "${from}" → "${to}" points at a token that is not live. If "${to}" was itself renamed, re-point this entry at its current name.`,
+    );
+  }
+}
+
+// ── 2: no rename key is live ─────────────────────────────────────────────────
+for (const from of Object.keys(renames)) {
+  if (live.has(from)) {
+    errors.push(
+      `rename key "${from}" is still LIVE — migrating away from a token that exists would break a working theme. Drop the entry, or finish the rename in the CSS.`,
+    );
+  }
+}
+
+// ── 3: no removal key is live ────────────────────────────────────────────────
+for (const name of Object.keys(removals)) {
+  if (live.has(name)) {
+    errors.push(
+      `removal "${name}" is still LIVE — a token that exists must not be reported to users as removed.`,
+    );
+  }
+}
+
+if (errors.length) {
+  console.error('check:token-renames FAILED:');
+  for (const e of errors) console.error(`  - ${e}`);
+  console.error('\ndocs/token-renames.json is the machine-readable mirror of docs/migration.md.');
+  console.error('Every rename target must be a live token; no old name may still be live.');
+  process.exit(1);
+}
+
+console.log(
+  `check:token-renames OK — ${Object.keys(renames).length} rename(s), ` +
+    `${Object.keys(removals).length} removal(s), all resolved against the live token set.`,
+);
diff --git a/scripts/lib/theme-file.js b/scripts/lib/theme-file.js
new file mode 100644
index 00000000..e63cf014
--- /dev/null
+++ b/scripts/lib/theme-file.js
@@ -0,0 +1,259 @@
+/**
+ * The SLASHED theme file — a portable, reviewable snapshot of a token override
+ * set.
+ *
+ * The configurator could already persist overrides two ways, and neither is a
+ * file you can put in a repository:
+ *
+ *   - localStorage (savedThemes.ts) — trapped in one browser profile.
+ *   - the share link (codec.ts) — a compressed base64url blob. Ideal for its
+ *     job (a short URL), useless for review: it is opaque in a diff, and it is
+ *     keyed by numeric token id.
+ *
+ * A theme file is keyed by token NAME and pretty-printed with sorted keys, so
+ * `git diff` shows `--sf-color-primary-source-light` changing value, which is
+ * the whole point. It is the artifact you hand a client, commit next to the
+ * CSS it themes, or review in a pull request.
+ *
+ * Consumed by scripts/migrate-theme.js and (mirrored through
+ * configurator/src/data/) by the configurator's import/export.
+ */
+
+/**
+ * Bumped only when the file SHAPE changes (a new/renamed/removed field), never
+ * when the token set changes — token drift is handled by migrateOverrides()
+ * against docs/token-renames.json, which is versionless by design.
+ */
+export const THEME_SCHEMA_VERSION = 1;
+
+export const THEME_SCHEMA_URL = 'https://slashed.codeslash.dev/schema/theme/v1.json';
+
+/** Well-formed `--sf-*` custom property name. */
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+
+/**
+ * Characters that would let a value break out of the `--token: value;`
+ * declaration it is written into and inject arbitrary CSS. Mirrors the intent
+ * of the configurator's sanitizeValue(), but rejects instead of silently
+ * rewriting: a CLI processing a file from disk should say what is wrong, not
+ * quietly alter the user's data.
+ */
+const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
+
+/**
+ * Non-whitespace control characters (C0 + DEL), tested AFTER whitespace has
+ * been collapsed — so tab/newline in a legitimately multi-line value (a long
+ * box-shadow, say) normalise away instead of being rejected, matching how the
+ * configurator's sanitizeValue() treats whitespace.
+ *
+ * What remains (ESC, BEL, NUL …) is meaningless in a CSS value, and echoing one
+ * into a terminal from the migration CLI would emit an ANSI/OSC sequence chosen
+ * by whoever wrote the file. This is the single choke point protecting every
+ * consumer.
+ */
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Validate and normalise a parsed theme file.
+ *
+ * @param {unknown} raw parsed JSON (not a string)
+ * @returns {{ theme: null | { schemaVersion: number, slashedVersion: string|null, name: string|null, overrides: Record<string,string> }, errors: string[] }}
+ */
+export function validateThemeFile(raw) {
+  const errors = [];
+  const fail = (msg) => {
+    errors.push(msg);
+    return { theme: null, errors };
+  };
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return fail('theme file must be a JSON object.');
+  }
+
+  const { schemaVersion, overrides, name, slashedVersion } = /** @type {any} */ (raw);
+
+  if (!Number.isInteger(schemaVersion)) {
+    return fail('`schemaVersion` is missing or not an integer.');
+  }
+  if (schemaVersion < 1) {
+    return fail(`\`schemaVersion\` must be >= 1 (got ${schemaVersion}).`);
+  }
+  if (schemaVersion > THEME_SCHEMA_VERSION) {
+    // Refusing beats guessing: a newer shape may carry fields whose meaning we
+    // cannot know, and silently ignoring them would corrupt the theme.
+    return fail(
+      `\`schemaVersion\` ${schemaVersion} is newer than this SLASHED understands ` +
+        `(max ${THEME_SCHEMA_VERSION}). Upgrade SLASHED to read this file.`,
+    );
+  }
+
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return fail('`overrides` is missing or not an object.');
+  }
+  if (name != null && typeof name !== 'string') errors.push('`name` must be a string when present.');
+  if (typeof name === 'string' && CONTROL_CHAR_RE.test(name)) {
+    errors.push('`name` contains control characters.');
+  }
+  if (slashedVersion != null && typeof slashedVersion !== 'string') {
+    errors.push('`slashedVersion` must be a string when present.');
+  }
+
+  const clean = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!TOKEN_NAME_RE.test(key)) {
+      errors.push(`overrides["${key}"]: not a well-formed --sf-* token name.`);
+      continue;
+    }
+    if (typeof value !== 'string') {
+      errors.push(`overrides["${key}"]: value must be a string (got ${typeof value}).`);
+      continue;
+    }
+    if (UNSAFE_VALUE_RE.test(value)) {
+      errors.push(
+        `overrides["${key}"]: value contains CSS-breaking characters (; { } or comment markers).`,
+      );
+      continue;
+    }
+    // Collapse whitespace exactly as the configurator's sanitizeValue() does,
+    // so the two paths cannot disagree about what a value means.
+    const normalised = value.replace(/\s+/g, ' ').trim();
+    if (CONTROL_CHAR_RE.test(normalised)) {
+      errors.push(`overrides["${key}"]: value contains control characters.`);
+      continue;
+    }
+    if (normalised === '') {
+      // An empty override is not a reset — generateCSS() would emit
+      // `--sf-x: ;`, a broken declaration that shadows the real token with
+      // nothing. The configurator's codec already drops empty values on both
+      // encode and decode; a file gets told instead of silently fixed.
+      errors.push(
+        `overrides["${key}"]: value is empty. Remove the entry to leave the token at its default.`,
+      );
+      continue;
+    }
+    clean[key] = normalised;
+  }
+
+  if (errors.length) return { theme: null, errors };
+
+  return {
+    theme: {
+      schemaVersion,
+      slashedVersion: typeof slashedVersion === 'string' ? slashedVersion : null,
+      name: typeof name === 'string' ? name : null,
+      overrides: clean,
+    },
+    errors: [],
+  };
+}
+
+/**
+ * Parse theme-file JSON text.
+ * @param {string} text
+ * @returns {ReturnType<typeof validateThemeFile>}
+ */
+export function parseThemeFile(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { theme: null, errors: [`not valid JSON (${err.message}).`] };
+  }
+  return validateThemeFile(raw);
+}
+
+/**
+ * Migrate an override set onto the current token API.
+ *
+ * Deliberately never drops an override it does not understand: an unrecognised
+ * token is REPORTED, not deleted. The map is knowledge about the framework's
+ * own history, and absence of knowledge is not evidence the user was wrong —
+ * they may be theming a token from a build this checkout has never seen.
+ *
+ * @param {Record<string,string>} overrides
+ * @param {object} opts
+ * @param {Record<string,string>} opts.renames   old name → current name
+ * @param {Record<string,string>} opts.removals  dead name → guidance
+ * @param {Set<string>} [opts.live]              current token names; omit to skip the unknown-token report
+ * @returns {{
+ *   overrides: Record<string,string>,
+ *   renamed: Array<{ from: string, to: string }>,
+ *   removed: Array<{ name: string, reason: string }>,
+ *   unknown: string[],
+ *   collisions: Array<{ from: string, to: string, kept: string }>,
+ * }}
+ */
+export function migrateOverrides(overrides, { renames = {}, removals = {}, live } = {}) {
+  const out = {};
+  const renamed = [];
+  const removed = [];
+  const unknown = [];
+  const collisions = [];
+
+  for (const key of Object.keys(overrides).sort()) {
+    const value = overrides[key];
+
+    if (Object.prototype.hasOwnProperty.call(removals, key)) {
+      removed.push({ name: key, reason: removals[key] });
+      continue;
+    }
+
+    const target = renames[key];
+    if (target) {
+      // The file may already carry the NEW name too (e.g. it was migrated
+      // halfway, or the user set both). The explicit current-name value wins —
+      // it is the one the author most recently meant.
+      if (Object.prototype.hasOwnProperty.call(overrides, target)) {
+        collisions.push({ from: key, to: target, kept: overrides[target] });
+        continue;
+      }
+      // Two different old names can resolve to the SAME live token — the map
+      // really does contain such pairs (e.g. --sf-color-danger-light and
+      // --sf-color-error-source-light both land on
+      // --sf-color-danger-source-light). Without this branch the later key
+      // would overwrite the earlier one and vanish from the report, which is
+      // precisely the silent data loss this function promises never to do.
+      // Keys are walked in sorted order, so first-claim-wins is deterministic.
+      if (Object.prototype.hasOwnProperty.call(out, target)) {
+        collisions.push({ from: key, to: target, kept: out[target] });
+        continue;
+      }
+      out[target] = value;
+      renamed.push({ from: key, to: target });
+      continue;
+    }
+
+    if (live && !live.has(key)) unknown.push(key);
+    out[key] = value;
+  }
+
+  return { overrides: sortKeys(out), renamed, removed, unknown, collisions };
+}
+
+/** Return a new object with keys in sorted order (stable, diff-friendly output). */
+export function sortKeys(obj) {
+  const out = {};
+  for (const key of Object.keys(obj).sort()) out[key] = obj[key];
+  return out;
+}
+
+/**
+ * Serialise a theme file. Keys are sorted and the output is pretty-printed with
+ * a trailing newline so re-exporting an unchanged theme produces an empty diff.
+ *
+ * @param {object} theme
+ * @param {Record<string,string>} theme.overrides
+ * @param {string} [theme.name]
+ * @param {string} [theme.slashedVersion]
+ * @returns {string}
+ */
+export function serializeThemeFile({ overrides, name, slashedVersion }) {
+  const doc = {
+    $schema: THEME_SCHEMA_URL,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    ...(slashedVersion ? { slashedVersion } : {}),
+    ...(name ? { name } : {}),
+    overrides: sortKeys(overrides ?? {}),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
diff --git a/scripts/migrate-theme.js b/scripts/migrate-theme.js
new file mode 100644
index 00000000..465b7ade
--- /dev/null
+++ b/scripts/migrate-theme.js
@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Migrate a SLASHED theme file onto the current token API.
+ *
+ * A theme file (see scripts/lib/theme-file.js) is keyed by token NAME, which is
+ * what makes it reviewable in a diff — and also what makes it vulnerable to a
+ * rename. This is the tool that repairs one: it rewrites renamed tokens, drops
+ * removed ones with the reason, and reports anything it does not recognise.
+ *
+ * Usage:
+ *   node scripts/migrate-theme.js <file.slashed-theme.json>            # report only
+ *   node scripts/migrate-theme.js <file.slashed-theme.json> --write    # rewrite in place
+ *   npm run migrate:theme -- <file> [--write]
+ *
+ * Exit codes:
+ *   0  nothing to do (or --write succeeded)
+ *   1  the file is invalid, or migration is needed and --write was not passed
+ *
+ * The report-only default is deliberate: exit 1 on "migration needed" makes
+ * this usable as a CI check over a repository's committed theme files, while
+ * --write is the explicit opt-in to mutate someone's file.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveTokens } from './lib/live-api.js';
+import { parseThemeFile, migrateOverrides, serializeThemeFile } from './lib/theme-file.js';
+
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const args = process.argv.slice(2);
+const write = args.includes('--write');
+const files = args.filter((a) => !a.startsWith('--'));
+
+if (files.length === 0) {
+  console.error('Usage: node scripts/migrate-theme.js <file.slashed-theme.json> [--write]');
+  process.exit(1);
+}
+
+/** Read docs/token-renames.json. */
+function readRenameMap() {
+  const file = path.join(ROOT, 'docs', 'token-renames.json');
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    // Mirror check-token-renames.js: an array here would yield no entries and
+    // silently migrate nothing, which is worse than refusing to run.
+    const section = (name) => {
+      const value = parsed?.[name];
+      if (value === undefined) return {};
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        console.error(`migrate-theme: docs/token-renames.json \`${name}\` must be an object.`);
+        process.exit(1);
+      }
+      return value;
+    };
+    return { renames: section('renames'), removals: section('removals') };
+  } catch (err) {
+    console.error(`migrate-theme: cannot read docs/token-renames.json (${err.message}).`);
+    process.exit(1);
+  }
+}
+
+/** Current framework version, stamped into a migrated file. */
+function frameworkVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Escape anything non-printable before echoing a file-supplied value to the
+ * terminal. validateThemeFile() already rejects control characters, so nothing
+ * should reach here — this is the second layer, because migrateOverrides() is
+ * exported and a future caller could feed it unvalidated input, and a terminal
+ * is a control-sequence interpreter, not a text sink.
+ * @param {string} value
+ */
+function forTerminal(value) {
+  return String(value).replace(
+    /[\u0000-\u001f\u007f]/g,
+    (ch) => `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`,
+  );
+}
+
+const { renames, removals } = readRenameMap();
+const live = buildLiveTokens(ROOT);
+const version = frameworkVersion();
+
+let needsWork = false;
+let hadError = false;
+
+for (const rel of files) {
+  const abs = path.resolve(rel);
+  // Echo the path the user typed — a computed relative path turns an absolute
+  // argument into an unrecognisable ../../.. chain.
+  const label = rel;
+
+  if (!fs.existsSync(abs)) {
+    console.error(`${label}: file not found.`);
+    hadError = true;
+    continue;
+  }
+
+  const { theme, errors } = parseThemeFile(fs.readFileSync(abs, 'utf8'));
+  if (!theme) {
+    console.error(`${label}: invalid theme file.`);
+    for (const e of errors) console.error(`  - ${e}`);
+    hadError = true;
+    continue;
+  }
+
+  const result = migrateOverrides(theme.overrides, { renames, removals, live });
+  const changed = result.renamed.length + result.removed.length + result.collisions.length;
+
+  console.log(`${label}${theme.name ? ` (“${forTerminal(theme.name)}”)` : ''}`);
+  console.log(
+    `  ${Object.keys(theme.overrides).length} override(s)` +
+      `${theme.slashedVersion ? `, authored against SLASHED ${theme.slashedVersion}` : ''}.`,
+  );
+
+  for (const { from, to } of result.renamed) console.log(`  renamed  ${from} → ${to}`);
+  for (const { from, to, kept } of result.collisions) {
+    console.log(`  dropped  ${from} (already set as ${to}; kept the current name's value "${forTerminal(kept)}")`);
+  }
+  for (const { name, reason } of result.removed) console.log(`  removed  ${name}\n             ${reason}`);
+  for (const name of result.unknown) {
+    console.log(`  unknown  ${name} (not a live token and not in the rename map — left untouched)`);
+  }
+
+  if (changed === 0) {
+    console.log('  nothing to migrate.\n');
+    continue;
+  }
+  needsWork = true;
+
+  if (write) {
+    fs.writeFileSync(
+      abs,
+      serializeThemeFile({
+        overrides: result.overrides,
+        name: theme.name ?? undefined,
+        slashedVersion: version ?? theme.slashedVersion ?? undefined,
+      }),
+      'utf8',
+    );
+    console.log(`  written — ${changed} change(s) applied${version ? `, stamped SLASHED ${version}` : ''}.\n`);
+  } else {
+    console.log(`  ${changed} change(s) needed. Re-run with --write to apply.\n`);
+  }
+}
+
+if (hadError) process.exit(1);
+if (needsWork && !write) process.exit(1);
diff --git a/tests/check-forbidden-strings.test.js b/tests/check-forbidden-strings.test.js
new file mode 100644
index 00000000..5a7ed88a
--- /dev/null
+++ b/tests/check-forbidden-strings.test.js
@@ -0,0 +1,214 @@
+/**
+ * Negative tests for scripts/check-forbidden-strings.js.
+ *
+ * A gate that has never been observed to fail is indistinguishable from a gate
+ * that cannot fail. Each test below plants exactly one violation in a fixture
+ * tree (SLASHED_ROOT), and asserts the gate reports it and — under --check —
+ * exits non-zero. The passing-fixture test guards the opposite failure mode: a
+ * rule so broad it fires on legitimate source.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const GATE = path.join(ROOT, 'scripts', 'check-forbidden-strings.js');
+
+const tmpDirs = [];
+
+/**
+ * Build a minimal fixture tree. Every file is optional; omitted ones are
+ * written with clean, rule-satisfying content so a test can plant a single
+ * violation without the others interfering.
+ * @param {{ [relPath: string]: string }} files
+ */
+function buildFixture(files = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-forbidden-'));
+  tmpDirs.push(dir);
+
+  const defaults = {
+    // Excluded from hardcoded-color by design — proves the exclusion works.
+    'core/tokens.css': ':root { --sf-color-primary: #3b5bdb; }\n',
+    'core/base.css': 'body { color: var(--sf-color-text); }\n',
+    'optional/forms.css': 'input { border: 1px solid var(--sf-color-border); }\n',
+    'dist/slashed.optimal.css': '/*! SLASHED v0.0.0 */\n:root { --sf-x: 1; }\n',
+    'configurator/src/lib/thing.ts': 'export const x = 1;\n',
+  };
+
+  for (const [rel, content] of Object.entries({ ...defaults, ...files })) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return dir;
+}
+
+function runGate(dir, args = []) {
+  return spawnSync(process.execPath, [GATE, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, SLASHED_ROOT: dir },
+  });
+}
+
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('check-forbidden-strings', () => {
+  test('passes on a clean fixture', () => {
+    const r = runGate(buildFixture(), ['--check']);
+    assert.equal(r.status, 0, `expected pass:\n${r.stderr}`);
+    assert.match(r.stdout, /check:forbidden-strings OK/);
+  });
+
+  test('does not flag colour literals inside the token source files', () => {
+    // core/tokens.css in the default fixture is full of hex; it must stay silent.
+    const r = runGate(buildFixture(), ['--check']);
+    assert.equal(r.status, 0, `token source files must be exempt:\n${r.stderr}`);
+  });
+
+  test('flags a hardcoded hex colour in a non-token CSS file', () => {
+    const dir = buildFixture({
+      'core/macros.css': '.sf-prose { color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'expected a non-zero exit');
+    assert.match(r.stderr, /hardcoded-color/);
+    assert.match(r.stderr, /core\/macros\.css:1/);
+    assert.match(r.stderr, /#3b5bdb/);
+  });
+
+  test('flags a hardcoded rgb() colour', () => {
+    const dir = buildFixture({
+      'optional/utilities.css': '.sf-x { background: rgba(0, 0, 0, 0.5); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /optional\/utilities\.css:1/);
+  });
+
+  test('ignores a colour literal that appears only inside a comment', () => {
+    const dir = buildFixture({
+      'core/macros.css': '/* was #3b5bdb before tokenising, and issue #496 */\n.sf-x { color: var(--sf-color-primary); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `comments must be masked:\n${r.stderr}`);
+  });
+
+  test('reports the original line number despite comment masking', () => {
+    const dir = buildFixture({
+      'core/macros.css': '/* banner\n   spanning\n   lines */\n.sf-x { color: #abc; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    // The violation is on line 4 of the original file; a non-offset-preserving
+    // comment strip would report line 1 or 2 here.
+    assert.match(r.stderr, /core\/macros\.css:4/);
+  });
+
+  test('flags a direct modern colour literal', () => {
+    for (const decl of [
+      'color: oklch(0.6 0.25 30)',
+      'color: oklab(0.5 0.1 0.1)',
+      'color: lch(50% 40 30)',
+      'color: lab(50% 40 30)',
+      'color: hwb(120 10% 20%)',
+      'color: color(display-p3 1 0 0)',
+    ]) {
+      const dir = buildFixture({ 'core/macros.css': `.sf-x { ${decl}; }\n` });
+      const r = runGate(dir, ['--check']);
+      assert.equal(r.status, 1, `expected ${decl} to be flagged`);
+      assert.match(r.stderr, /hardcoded-color/);
+    }
+  });
+
+  test('does not flag relative-colour derivations, which are the token architecture', () => {
+    for (const decl of [
+      'color: oklch(from var(--sf-color-primary) l c h)',
+      'color: oklch(var(--sf-l) var(--sf-c) var(--sf-h))',
+      'color: color-mix(in oklab, red, blue)',
+    ]) {
+      const dir = buildFixture({ 'core/macros.css': `.sf-x { ${decl}; }\n` });
+      const r = runGate(dir, ['--check']);
+      assert.equal(r.status, 0, `${decl} must be allowed:\n${r.stderr}`);
+    }
+  });
+
+  test('flags a protocol-relative external URL in a bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css': '@import url(//fonts.example.com/style.css);\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'a //host reference still causes a network request');
+    assert.match(r.stderr, /external-url/);
+    assert.match(r.stderr, /fonts\.example\.com/);
+  });
+
+  test('flags an external URL in a shipped bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css': "@import url(https://fonts.googleapis.com/css2?family=Inter);\n",
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /external-url/);
+    assert.match(r.stderr, /fonts\.googleapis\.com/);
+  });
+
+  test('allows the inline-SVG XML namespace in a bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css':
+        ".sf-x { background: url('data:image/svg+xml,<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>'); }\n",
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `namespace URI must be allowed:\n${r.stderr}`);
+  });
+
+  test('flags a console.log left in configurator source', () => {
+    const dir = buildFixture({
+      'configurator/src/lib/thing.ts': 'export function f() { console.log("hi"); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /debug-statement/);
+  });
+
+  test('does not flag console.warn in configurator source', () => {
+    const dir = buildFixture({
+      'configurator/src/lib/thing.ts': 'export function f() { console.warn("real diagnostic"); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `console.warn is legitimate:\n${r.stderr}`);
+  });
+
+  test('without --check, reports the violation but exits 0', () => {
+    const dir = buildFixture({
+      'core/macros.css': '.sf-x { color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 0, 'report-only mode must not fail the shell');
+    assert.match(r.stderr, /hardcoded-color/);
+  });
+
+  test('an allowed match does not blanket-approve other matches in the same file', () => {
+    // core/base.css has a real ALLOW entry for `#fff`. A different literal in
+    // that same file must still fail — this is the key property of keying the
+    // allowlist by matched text rather than by path.
+    const dir = buildFixture({
+      'core/base.css': 'body { color: var(--sf-color-bg, #fff); border-color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'a second, unexcepted literal must still fail');
+    assert.match(r.stderr, /#3b5bdb/);
+    assert.doesNotMatch(r.stderr, /#fff/);
+  });
+
+  test('tolerates a missing target directory', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-forbidden-empty-'));
+    tmpDirs.push(dir);
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `an unbuilt tree must not crash the gate:\n${r.stderr}`);
+  });
+});
diff --git a/tests/check-token-renames.test.js b/tests/check-token-renames.test.js
new file mode 100644
index 00000000..6539bc86
--- /dev/null
+++ b/tests/check-token-renames.test.js
@@ -0,0 +1,160 @@
+/**
+ * Negative tests for scripts/check-token-renames.js.
+ *
+ * The rename map's value is entirely in its truthfulness — a stale entry does
+ * not merely fail to help, it actively migrates a user onto a dead token. Each
+ * test plants one violation in a fixture tree (SLASHED_ROOT) and asserts the
+ * gate refuses it.
+ *
+ * The fixture supplies both inputs live-api.js unions: token-registry.json and
+ * the core/ + optional/ CSS declarations.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const GATE = path.join(ROOT, 'scripts', 'check-token-renames.js');
+
+const tmpDirs = [];
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/**
+ * @param {object} map            contents of docs/token-renames.json
+ * @param {string[]} liveTokens   tokens that should count as live
+ */
+function buildFixture(map, liveTokens = ['--sf-color-danger', '--sf-z-toast']) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-renames-'));
+  tmpDirs.push(dir);
+  fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'core'), { recursive: true });
+
+  fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), JSON.stringify(map, null, 2));
+  fs.writeFileSync(
+    path.join(dir, 'token-registry.json'),
+    JSON.stringify({
+      _meta: { nextId: liveTokens.length },
+      tokens: liveTokens.map((name, id) => ({ id, name })),
+    }),
+  );
+  // live-api.js also unions in tokens DECLARED in core/ + optional/ CSS.
+  fs.writeFileSync(
+    path.join(dir, 'core', 'tokens.css'),
+    `:root {\n${liveTokens.map((t) => `  ${t}: red;`).join('\n')}\n}\n`,
+  );
+  return dir;
+}
+
+const runGate = (dir) =>
+  spawnSync(process.execPath, [GATE], { encoding: 'utf8', env: { ...process.env, SLASHED_ROOT: dir } });
+
+describe('check-token-renames', () => {
+  test('passes on a truthful map', () => {
+    const dir = buildFixture({
+      renames: { '--sf-color-error': '--sf-color-danger' },
+      removals: { '--sf-opacity-25': 'Use --sf-opacity-muted.' },
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 0, `expected pass:\n${r.stderr}`);
+    assert.match(r.stdout, /check:token-renames OK/);
+  });
+
+  test('fails when a rename target is not live', () => {
+    const dir = buildFixture({ renames: { '--sf-color-error': '--sf-color-gone' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /points at a token that is not live/);
+  });
+
+  test('fails on a rename chain, naming the resolved destination', () => {
+    const dir = buildFixture({
+      renames: {
+        '--sf-color-error': '--sf-color-middle',
+        '--sf-color-middle': '--sf-color-danger',
+      },
+      removals: {},
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /points at another rename key/);
+    assert.match(r.stderr, /--sf-color-danger/);
+  });
+
+  test('fails when an old name is still live', () => {
+    // --sf-color-danger is live, so claiming it was renamed away is a lie.
+    const dir = buildFixture({ renames: { '--sf-color-danger': '--sf-z-toast' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /is still LIVE/);
+  });
+
+  test('fails when a removed token is still live', () => {
+    const dir = buildFixture({ renames: {}, removals: { '--sf-color-danger': 'gone' } });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /must not be reported to users as removed/);
+  });
+
+  test('fails when a token is both renamed and removed', () => {
+    const dir = buildFixture({
+      renames: { '--sf-color-error': '--sf-color-danger' },
+      removals: { '--sf-color-error': 'gone' },
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /BOTH renames and removals/);
+  });
+
+  test('fails on a self-referential rename', () => {
+    const dir = buildFixture({ renames: { '--sf-color-danger': '--sf-color-danger' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /maps to itself/);
+  });
+
+  test('fails on a malformed token name', () => {
+    const dir = buildFixture({ renames: { 'color-error': '--sf-color-danger' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /well-formed/);
+  });
+
+  test('fails when a removal carries no reason', () => {
+    const dir = buildFixture({ renames: {}, removals: { '--sf-opacity-25': '   ' } });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /no reason/);
+  });
+
+  test('fails when the root value is an array', () => {
+    const dir = buildFixture({ renames: {}, removals: {} });
+    fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), '[]');
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /must be a JSON object/);
+  });
+
+  test('fails when a section is an array rather than an object', () => {
+    // An array yields no entries, so every downstream check would pass
+    // vacuously and the CLI would silently migrate nothing.
+    for (const section of ['renames', 'removals']) {
+      const dir = buildFixture({ renames: {}, removals: {}, [section]: [] });
+      const r = runGate(dir);
+      assert.equal(r.status, 1, `expected ${section}: [] to fail`);
+      assert.match(r.stderr, new RegExp(`\\\`${section}\\\` must be an object`));
+    }
+  });
+
+  test('fails on malformed JSON rather than throwing', () => {
+    const dir = buildFixture({ renames: {}, removals: {} });
+    fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), '{ not json');
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /not valid JSON/);
+  });
+});
diff --git a/tests/theme-file.test.js b/tests/theme-file.test.js
new file mode 100644
index 00000000..2ea7e730
--- /dev/null
+++ b/tests/theme-file.test.js
@@ -0,0 +1,309 @@
+/**
+ * Tests for the portable theme file: the format contract
+ * (scripts/lib/theme-file.js) and the migration CLI (scripts/migrate-theme.js).
+ *
+ * The properties that matter here are the ones a user's data depends on:
+ * a theme file must round-trip byte for byte, migration must be idempotent, and
+ * nothing the tool does not understand may be silently discarded.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  THEME_SCHEMA_VERSION,
+  validateThemeFile,
+  parseThemeFile,
+  migrateOverrides,
+  serializeThemeFile,
+} from '../scripts/lib/theme-file.js';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const CLI = path.join(ROOT, 'scripts', 'migrate-theme.js');
+
+const tmpDirs = [];
+function tmpFile(contents, name = 'x.slashed-theme.json') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-theme-'));
+  tmpDirs.push(dir);
+  const file = path.join(dir, name);
+  fs.writeFileSync(file, contents);
+  return file;
+}
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const RENAMES = { '--sf-color-error': '--sf-color-danger', '--sf-z-top': '--sf-z-toast' };
+const REMOVALS = { '--sf-opacity-25': 'Use --sf-opacity-muted.' };
+
+describe('validateThemeFile', () => {
+  const ok = {
+    schemaVersion: 1,
+    overrides: { '--sf-color-primary-source-light': '#3b5bdb' },
+  };
+
+  test('accepts a minimal well-formed file', () => {
+    const { theme, errors } = validateThemeFile(ok);
+    assert.deepEqual(errors, []);
+    assert.equal(theme.overrides['--sf-color-primary-source-light'], '#3b5bdb');
+    assert.equal(theme.name, null);
+  });
+
+  test('rejects a non-object', () => {
+    for (const bad of [null, [], 'x', 42]) {
+      assert.equal(validateThemeFile(bad).theme, null);
+    }
+  });
+
+  test('rejects a missing or non-integer schemaVersion', () => {
+    assert.equal(validateThemeFile({ overrides: {} }).theme, null);
+    assert.equal(validateThemeFile({ schemaVersion: '1', overrides: {} }).theme, null);
+  });
+
+  test('refuses a schemaVersion from the future rather than guessing', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: THEME_SCHEMA_VERSION + 1,
+      overrides: {},
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /newer than this SLASHED understands/);
+  });
+
+  test('rejects a key that is not an --sf-* token', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { 'color-primary': 'red' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /well-formed/);
+  });
+
+  test('rejects a value that could break out of the declaration', () => {
+    for (const bad of ['red; background: url(evil)', 'red }', '/* x */ red']) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { '--sf-color-primary': bad },
+      });
+      assert.equal(theme, null, `expected rejection of ${JSON.stringify(bad)}`);
+      assert.match(errors[0], /CSS-breaking/);
+    }
+  });
+
+  test('rejects an empty or whitespace-only value', () => {
+    // Regression (PR #671 review): these used to trim to "" and be accepted as
+    // an active override, so generateCSS() emitted `--sf-x: ;` — a broken
+    // declaration shadowing the real token with nothing.
+    for (const bad of ['', '   ', '\t\n']) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { '--sf-color-primary': bad },
+      });
+      assert.equal(theme, null, `expected rejection of ${JSON.stringify(bad)}`);
+      assert.match(errors[0], /value is empty/);
+    }
+  });
+
+  test('rejects control characters in a value', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { '--sf-color-primary': 'red\u001b[2Jwiped' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /control characters/);
+  });
+
+  test('rejects control characters in the theme name', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      name: 'Acme\u001b[31m',
+      overrides: { '--sf-radius-m': '10px' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors.join(' '), /`name` contains control characters/);
+  });
+
+  test('parseThemeFile reports malformed JSON without throwing', () => {
+    const { theme, errors } = parseThemeFile('{ not json');
+    assert.equal(theme, null);
+    assert.match(errors[0], /not valid JSON/);
+  });
+});
+
+describe('migrateOverrides', () => {
+  test('rewrites a renamed token, preserving its value', () => {
+    const r = migrateOverrides({ '--sf-color-error': '#e03131' }, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(r.overrides, { '--sf-color-danger': '#e03131' });
+    assert.deepEqual(r.renamed, [{ from: '--sf-color-error', to: '--sf-color-danger' }]);
+  });
+
+  test('drops a removed token and surfaces its reason', () => {
+    const r = migrateOverrides({ '--sf-opacity-25': '0.25' }, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(r.overrides, {});
+    assert.equal(r.removed[0].name, '--sf-opacity-25');
+    assert.match(r.removed[0].reason, /opacity-muted/);
+  });
+
+  test('keeps an unrecognised token instead of discarding it', () => {
+    const live = new Set(['--sf-color-danger']);
+    const r = migrateOverrides({ '--sf-from-the-future': '1rem' }, { renames: RENAMES, removals: REMOVALS, live });
+    assert.deepEqual(r.overrides, { '--sf-from-the-future': '1rem' });
+    assert.deepEqual(r.unknown, ['--sf-from-the-future']);
+  });
+
+  test('a live token is passed through without being reported unknown', () => {
+    const live = new Set(['--sf-radius-m']);
+    const r = migrateOverrides({ '--sf-radius-m': '10px' }, { renames: RENAMES, removals: REMOVALS, live });
+    assert.deepEqual(r.overrides, { '--sf-radius-m': '10px' });
+    assert.deepEqual(r.unknown, []);
+  });
+
+  test('when both old and new names are set, the current name wins', () => {
+    const r = migrateOverrides(
+      { '--sf-color-error': '#old', '--sf-color-danger': '#new' },
+      { renames: RENAMES, removals: REMOVALS },
+    );
+    assert.deepEqual(r.overrides, { '--sf-color-danger': '#new' });
+    assert.equal(r.collisions.length, 1);
+    assert.equal(r.collisions[0].kept, '#new');
+    assert.deepEqual(r.renamed, []);
+  });
+
+  test('reports a collision when two old names resolve to one target', () => {
+    // Reachable with the real map: --sf-color-danger-light and
+    // --sf-color-error-source-light both land on --sf-color-danger-source-light.
+    // Without a collision record the later key would silently overwrite the
+    // earlier one — the exact data loss this function promises never to do.
+    const renames = {
+      '--sf-color-danger-light': '--sf-color-danger-source-light',
+      '--sf-color-error-source-light': '--sf-color-danger-source-light',
+    };
+    const r = migrateOverrides(
+      { '--sf-color-danger-light': '#aaa', '--sf-color-error-source-light': '#bbb' },
+      { renames, removals: {} },
+    );
+    // Sorted order: --sf-color-danger-light claims the target first.
+    assert.deepEqual(r.overrides, { '--sf-color-danger-source-light': '#aaa' });
+    assert.deepEqual(r.renamed, [
+      { from: '--sf-color-danger-light', to: '--sf-color-danger-source-light' },
+    ]);
+    assert.equal(r.collisions.length, 1);
+    assert.equal(r.collisions[0].from, '--sf-color-error-source-light');
+    assert.equal(r.collisions[0].kept, '#aaa');
+  });
+
+  test('is idempotent — migrating an already-migrated set changes nothing', () => {
+    const once = migrateOverrides({ '--sf-color-error': '#e03131' }, { renames: RENAMES, removals: REMOVALS });
+    const twice = migrateOverrides(once.overrides, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(twice.overrides, once.overrides);
+    assert.equal(twice.renamed.length, 0);
+    assert.equal(twice.removed.length, 0);
+  });
+
+  test('output keys are sorted regardless of input order', () => {
+    const r = migrateOverrides(
+      { '--sf-z-index': '1', '--sf-a-token': '2', '--sf-m-token': '3' },
+      { renames: {}, removals: {} },
+    );
+    assert.deepEqual(Object.keys(r.overrides), ['--sf-a-token', '--sf-m-token', '--sf-z-index']);
+  });
+});
+
+describe('serializeThemeFile', () => {
+  test('round-trips through parseThemeFile unchanged', () => {
+    const overrides = { '--sf-color-primary-source-light': '#3b5bdb', '--sf-radius-m': '10px' };
+    const text = serializeThemeFile({ overrides, name: 'Acme', slashedVersion: '0.7.31' });
+    const { theme, errors } = parseThemeFile(text);
+    assert.deepEqual(errors, []);
+    assert.deepEqual(theme.overrides, overrides);
+    assert.equal(theme.name, 'Acme');
+    assert.equal(theme.slashedVersion, '0.7.31');
+  });
+
+  test('is byte-stable — re-serialising produces an identical string', () => {
+    const a = serializeThemeFile({ overrides: { '--sf-b': '2', '--sf-a': '1' }, name: 'X' });
+    const b = serializeThemeFile({ overrides: { '--sf-a': '1', '--sf-b': '2' }, name: 'X' });
+    assert.equal(a, b, 'key order in the input must not affect the output');
+    assert.match(a, /\n$/, 'must end with a newline');
+  });
+
+  test('omits optional fields rather than writing nulls', () => {
+    const text = serializeThemeFile({ overrides: {} });
+    assert.doesNotMatch(text, /"name"/);
+    assert.doesNotMatch(text, /"slashedVersion"/);
+    assert.match(text, /"schemaVersion": 1/);
+  });
+});
+
+describe('migrate-theme CLI', () => {
+  const run = (args) => spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf8', cwd: ROOT });
+
+  const legacyTheme = JSON.stringify(
+    {
+      schemaVersion: 1,
+      slashedVersion: '0.6.10',
+      name: 'Acme',
+      overrides: { '--sf-color-primary-light': '#3b5bdb', '--sf-color-error': '#e03131' },
+    },
+    null,
+    2,
+  );
+
+  test('report-only mode exits 1 when migration is needed, without touching the file', () => {
+    const file = tmpFile(legacyTheme);
+    const before = fs.readFileSync(file, 'utf8');
+    const r = run([file]);
+    assert.equal(r.status, 1, r.stderr);
+    assert.match(r.stdout, /renamed\s+--sf-color-primary-light → --sf-color-primary-source-light/);
+    assert.equal(fs.readFileSync(file, 'utf8'), before, 'report-only must not write');
+  });
+
+  test('--write applies the migration and then exits 0 on a re-run', () => {
+    const file = tmpFile(legacyTheme);
+    assert.equal(run([file, '--write']).status, 0);
+
+    const migrated = JSON.parse(fs.readFileSync(file, 'utf8'));
+    assert.ok(migrated.overrides['--sf-color-primary-source-light']);
+    assert.ok(migrated.overrides['--sf-color-danger']);
+    assert.equal(migrated.overrides['--sf-color-primary-light'], undefined);
+
+    const second = run([file]);
+    assert.equal(second.status, 0, 'a migrated file needs no further work');
+    assert.match(second.stdout, /nothing to migrate/);
+  });
+
+  test('exits 1 with a readable message on an invalid file', () => {
+    const r = run([tmpFile('{ "schemaVersion": 99, "overrides": {} }')]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /invalid theme file/);
+    assert.match(r.stderr, /newer than this SLASHED understands/);
+  });
+
+  test('refuses a file carrying terminal control sequences', () => {
+    const file = tmpFile(
+      JSON.stringify({
+        schemaVersion: 1,
+        name: 'Acme',
+        overrides: { '--sf-color-primary': 'red\u001b[2J' },
+      }),
+    );
+    const r = run([file]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /control characters/);
+    assert.ok(!r.stderr.includes('\u001b[2J'), 'must not echo the raw escape sequence');
+    assert.ok(!r.stdout.includes('\u001b[2J'), 'must not echo the raw escape sequence');
+  });
+
+  test('exits 1 when the file does not exist', () => {
+    const r = run(['/nonexistent/theme.json']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /file not found/);
+  });
+
+  test('exits 1 with usage when given no file', () => {
+    const r = run([]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Usage:/);
+  });
+});