Make Visualize installations compact by default

.github/workflows/ci.yml

@@ -33,6 +33,7 @@ jobs:
 
       - name: Node syntax check
         run: |
+          node --check visualize/scripts/catalog.mjs
           node --check visualize/scripts/teach.mjs
           node --check visualize/scripts/palette.mjs
           node --check visualize/scripts/detect.mjs
@@ -70,12 +71,18 @@ jobs:
         # ladder self-consistency).
         run: node dev-scripts/palette-smoke.mjs
 
+      - name: Fetch immutable catalog snapshot
+        run: git fetch --no-tags --depth=1 origin "$(node -p "require('./catalog/source.json').revision")"
+
       - name: Catalog selection metadata
         # DESIGN.md frontmatter feeds deterministic catalog-index.json.
         # The check fails on missing / invalid selection metadata or
         # hand-edited index drift.
         run: node dev-scripts/catalog-index.mjs --check
 
+      - name: Selected catalog resolution
+        run: node --test dev-scripts/catalog.test.mjs
+
       - name: slide-canvas unit tests
         # Pure-logic helpers (computeScale, parseSlideHash, static API).
         # Zero deps; runs with the bundled node:test runner.

AGENTS.md

@@ -4,14 +4,16 @@ This repo is the source for the `visualize` agent skill. Most edits land under `
 
 ## Editing workflow
 
-1. Make changes only under `visualize/`.
+1. Edit runtime instructions and helpers under `visualize/`; full catalog sources under `catalog/`; authoring tools under `dev-scripts/`. Run `node dev-scripts/catalog-index.mjs` after catalog edits to regenerate the bundled index and fallback.
 2. Run `bin/sync-mounts.sh` to propagate.
 3. Commit both the canonical change and the mirror updates in the same commit.
 
+`visualize/design-systems/animation-patterns.md` is runtime-owned shared guidance for `animate` and catalog preview authors. Edit it directly; catalog generation does not overwrite it.
+
 ## Adding content
 
 - **Template** → `visualize/templates/<slug>/template.md`. Keep the contract compact: frontmatter, use/exclusion rules, structure, creation guidance, hierarchy/mobile contracts, and concrete failure modes. See `CONTRIBUTING.md` for the canonical shape.
-- **Design system** → `visualize/design-systems/<slug>/{DESIGN.md,tokens.css}`.
+- **Design system** → `catalog/design-systems/<slug>/{DESIGN.md,tokens.css}`.
 - **Pattern recipe** → `visualize/patterns/<slug>.md`. Use for recurring creation guidance, not reusable component CSS.
 - **Reference doc** → `visualize/reference/<topic>.md`. Lean intent + named failure modes only. Don't write defensive scaffolding.
 
@@ -38,19 +40,21 @@ Every constraint the skill imposes must answer: *what bad output would result wi
 ## Repository layout
 
 ```
-visualize/                     ← canonical mount, the only directory humans edit
+visualize/                     ← canonical installed skill
 ├── SKILL.md
 ├── reference/                 ← typography / color / spatial / motion / copy
 ├── patterns/                  ← creation-time pattern recipes
-├── design-systems/            ← 10 design systems (DESIGN.md + tokens.css per system)
+├── design-systems/            ← generated index/source pin/Clean fallback + runtime-owned animation-patterns.md
 ├── templates/                 ← template contracts (template.md per template)
 └── scripts/                   ← bash + Node helpers
 
 skills/visualize/              ← mirror — npm-skills (`npx skills add`)
 hermes/design/visualize/       ← mirror — Hermes well-known
 pi/agent/skills/visualize/     ← mirror — Pi / OpenClaw
 
-fixtures/                      ← 10 brand-profile worked examples (DESIGN.md + PRODUCT.md per fixture)
+catalog/design-systems/        ← full authoritative catalog and generated previews
+dev-scripts/preview-kit/       ← development-only preview sources
+visualize/fixtures/            ← shared fixtures used by shipped check helpers
 bin/sync-mounts.sh             ← regenerate the three mirrors
 .github/workflows/ci.yml       ← mirror-check + JSON lint + shellcheck
 ```

CONTRIBUTING.md

@@ -63,7 +63,7 @@ Generated fixture previews live under `temp/template-previews/` and are intentio
 
 ## Adding a design system
 
-Drop a new directory under `visualize/design-systems/<slug>/` with `DESIGN.md` (Google Stitch's canonical format — YAML frontmatter carrying design tokens + a six-section markdown body: Overview / Colors / Typography / Elevation / Components / Do's and Don'ts) and `tokens.css` (sidecar with CSS custom properties for the `:root` + `.dark` blocks). The worked exemplar is `visualize/design-systems/clean/DESIGN.md` — match its overall shape (YAML structure, evocative subtitles, Named Rules pattern) and adapt the content for the new register.
+Drop a new directory under `catalog/design-systems/<slug>/` with `DESIGN.md` (Google Stitch's canonical format — YAML frontmatter carrying design tokens + a six-section markdown body: Overview / Colors / Typography / Elevation / Components / Do's and Don'ts) and `tokens.css` (sidecar with CSS custom properties for the `:root` + `.dark` blocks). The worked exemplar is `catalog/design-systems/clean/DESIGN.md` — match its overall shape (YAML structure, evocative subtitles, Named Rules pattern) and adapt the content for the new register.
 
 Then add `<slug>` to the `DESIGN_SYSTEMS` array in `dev-scripts/build-previews.sh` (alphabetical) and regenerate the previews:
 
@@ -75,27 +75,37 @@ Commit the generated `preview.html` + `preview-dark.html` alongside `DESIGN.md`
 
 A package may also include a short `README.md` linking its design guidance, tokens, and previews, with an example of theme usage; see Editorial. Keep system-specific identity and adaptation rules in `DESIGN.md`, and application/override procedure in SKILL.md's Artifact themes section. Do not duplicate the shared workflow across package READMEs.
 
+### Catalog distribution
+
+The installed catalog resources are the generated selection index, Clean fallback, and catalog source pin. `catalog/design-systems/` is their single authoring source. Run `node dev-scripts/catalog-index.mjs` to regenerate those bundled files, then `bin/sync-mounts.sh`. CI checks both generations. Authoring metadata is validated from the working catalog; bundled files are generated from the pinned Git snapshot, so a catalog-only PR leaves the installed selection unchanged. Fetch that commit locally first if needed (`git fetch --no-tags --depth=1 origin <revision>`).
+
+Shared motion guidance stays runtime-owned at [`visualize/design-systems/animation-patterns.md`](visualize/design-systems/animation-patterns.md). Edit it directly and sync the mirrors; it serves both `animate` and catalog preview authors and does not require catalog publication or repinning.
+
+Other references are read from the immutable public commit and catalog root recorded in `catalog/source.json`. To distribute catalog changes, first merge/publish the catalog source and previews; then, in a follow-up distribution change, set `revision` to that reachable full commit SHA and `root` to `catalog/design-systems`, regenerate, and sync. Do not point at an unpublished commit, branch, or tag. The initial pin uses the previously published `visualize/design-systems` snapshot. New entries or changed reference guidance must be published and pinned before distributing their updated selection index.
+
+Verify a changed pin with a cold cache by resolving each changed package (including `--previews`) and comparing the returned bytes with the published catalog. `node --test dev-scripts/catalog.test.mjs` covers cache and failure behavior.
+
 ## Adding a per-system preview-template
 
-A design system can ship its own `preview-template.html` that overrides the generic `preview-kit/template.html` shell. Most design systems carry one so the preview can show their signature moves; systems without an override fall back to the preview-kit shell with only their tokens applied.
+A design system can ship its own `preview-template.html` that overrides the generic `dev-scripts/preview-kit/template.html` shell. Most design systems carry one so the preview can show their signature moves; systems without an override fall back to the preview-kit shell with only their tokens applied.
 
-Drop `preview-template.html` in `visualize/design-systems/<slug>/`. The file must carry four placeholders verbatim: `__ROOT_ATTR__` on the `<html>` tag, `__DESIGN_SYSTEM_NAME__` wherever the slug should appear, and `/* __TOKENS_PLACEHOLDER__ */` + the legacy marker `/* __COMPONENTS_PLACEHOLDER__ */` each inside a `<style>` block on a whitespace-only line. The latter now injects preview-only fixture styles from `preview-kit/fixture-styles/`. `dev-scripts/build-previews.sh` auto-detects the override. Per-system templates don't inherit `preview-kit/template.html`, so declare any required Google Fonts inside the per-system `<head>`.
+Drop `preview-template.html` in `catalog/design-systems/<slug>/`. The file must carry four placeholders verbatim: `__ROOT_ATTR__` on the `<html>` tag, `__DESIGN_SYSTEM_NAME__` wherever the slug should appear, and `/* __TOKENS_PLACEHOLDER__ */` + the legacy marker `/* __COMPONENTS_PLACEHOLDER__ */` each inside a `<style>` block on a whitespace-only line. The latter now injects preview-only fixture styles from `dev-scripts/preview-kit/fixture-styles/`. `dev-scripts/build-previews.sh` auto-detects the override. Per-system templates don't inherit `dev-scripts/preview-kit/template.html`, so declare any required Google Fonts inside the per-system `<head>`.
 
-If the brand's synthesised dark mode reads wrong (low contrast or wrong-temperature surfaces), hand-edit the `[data-theme="dark"]` block in `tokens.css` to the brand's actual dark surface. See [`visualize/design-systems/AUTHORING.md`](visualize/design-systems/AUTHORING.md) for pattern references, the dark-mode strategy decision table, and the detect-clean checklist.
+If the brand's synthesised dark mode reads wrong (low contrast or wrong-temperature surfaces), hand-edit the `[data-theme="dark"]` block in `tokens.css` to the brand's actual dark surface. See [`catalog/design-systems/AUTHORING.md`](catalog/design-systems/AUTHORING.md) for pattern references, the dark-mode strategy decision table, and the detect-clean checklist.
 
 After editing:
 
 ```sh
 bash dev-scripts/build-previews.sh
-node visualize/scripts/detect.mjs --strict visualize/design-systems/<slug>/preview.html
+node visualize/scripts/detect.mjs --strict catalog/design-systems/<slug>/preview.html
 bash bin/sync-mounts.sh
 ```
 
 ## Preview kit
 
-`visualize/preview-kit/` carries the canonical token-surface preview page. Each design system gets two generated files at `design-systems/<slug>/preview.html` (light) and `preview-dark.html` (dark).
+`dev-scripts/preview-kit/` carries the canonical token-surface preview page. Each design system gets two generated files at `design-systems/<slug>/preview.html` (light) and `preview-dark.html` (dark).
 
-Do not hand-edit the generated previews. When you change `preview-kit/template.html`, fixture styles under `preview-kit/fixture-styles/`, or a design system's `tokens.css`, regenerate via `dev-scripts/build-previews.sh`. See `visualize/preview-kit/README.md` for the placeholder contract and extension notes.
+Do not hand-edit the generated previews. When you change `dev-scripts/preview-kit/template.html`, fixture styles under `dev-scripts/preview-kit/fixture-styles/`, or a design system's `tokens.css`, regenerate via `dev-scripts/build-previews.sh`. See `dev-scripts/preview-kit/README.md` for the placeholder contract and extension notes.
 
 For targeted fixture previews, use `dev-scripts/build-template-previews.sh`. It renders fixture files from `visualize/fixtures/manifest.json` against any design-system `tokens.css` and writes standalone HTML to `temp/template-previews/`:
 

README.md

@@ -14,6 +14,17 @@ npx skills add display-dev/visualize --skill visualize
 
 Works across Claude Code, Cursor, Codex, OpenCode, Hermes, and Pi.
 
+Installations bundle the selection index, Clean fallback, templates, and runtime helpers. The full catalog and preview sources stay in this repository. Selected reference packages load on demand from a pinned public commit; Node.js 18+ and internet access are needed for the first load of a non-bundled package. Cached packages can be reused offline.
+
+From the installed skill directory:
+
+```sh
+node scripts/catalog.mjs editorial
+node scripts/catalog.mjs editorial --previews
+```
+
+The JSON result gives local file paths and the pinned source URL. Previews load only with `--previews`. Set `VISUALIZE_CATALOG_CACHE_DIR` to relocate the default `~/.cache/visualize-skill/catalog` cache. A failed fetch reports the unavailable reference; it never silently substitutes Clean. For a damaged cache, remove only the directory named in the error and retry.
+
 ## Why visualize?
 
 Four problems with how agents publish HTML today:
@@ -59,7 +70,7 @@ Reference packages with visual guidance, tokens, and previews. Use them when der
 - **40 native register-family references** — Clean (default), Editorial, Console, IDE, Terminal, Blueprint, Brutalist, Deck, Paper-ink, Whitepaper, plus broader artifact registers like Bento, Neon, Riso, Terracotta, Glassmorphism, Dithered, Luxury, Sketch, Monograph, News-print, Swiss, Win98, and more.
 - **63 brand-style entries** — `airbnb-style`, `apple-style`, `cohere-style`, `mistral-ai-style`, etc. All brand-style entries are self-authored from live brand verification and carry `source: live-verified` in their `DESIGN.md` frontmatter.
 
-Each design system has `DESIGN.md` for visual guidance and `tokens.css` for concrete values. A package README, when present, links its references and previews; see [Editorial](visualize/design-systems/editorial/README.md).
+Each design system has `DESIGN.md` for visual guidance and `tokens.css` for concrete values. A package README, when present, links its references and previews; see [Editorial](catalog/design-systems/editorial/README.md).
 
 For example: “Apply Editorial to this report. Replace the project's visual styling for this artifact only; keep its logo, content, section order, and behavior.”