feat: add simple artifact exploration

Author: carlrannaberg

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "visualize",
-  "version": "0.3.0",
-  "description": "Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards.",
+  "version": "0.4.0",
+  "description": "Generate, explore, and refine beautiful on-brand HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards.",
   "author": { "name": "display.dev", "url": "https://display.dev" },
   "homepage": "https://display.dev/docs/visualize",
   "repository": "https://github.com/display-dev/visualize",
@@ -10,7 +10,7 @@
   "interface": {
     "displayName": "visualize",
     "shortDescription": "Generate beautiful, on-brand HTML artifacts.",
-    "longDescription": "visualize lets agents generate self-contained HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards — that read as your brand. Captures brand from your codebase, asking, or live site, then applies it consistently across 35 templates and 103 reference design systems. Iteration verbs (polish, review, simplify, bolder, quieter, animate) keep the loop tight. See https://display.dev/docs/visualize for the full feature set.",
+    "longDescription": "visualize lets agents generate self-contained HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards — that read as your brand. Artifact Explore compares responsive document structures while the current visual system and content stay fixed. Brand capture and focused refine verbs work across 35 templates and 103 reference design systems. See https://display.dev/docs/visualize for the full feature set.",
     "developerName": "display.dev",
     "category": "Design",
     "websiteURL": "https://display.dev/docs/visualize",

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "visualize",
-  "description": "Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards. Captures brand from your codebase, asking, or live site, then applies it consistently across 35 templates and 103 reference design systems.",
-  "version": "0.3.0",
+  "description": "Generate, explore, and refine beautiful on-brand HTML artifacts. Artifact Explore compares responsive structures while the current visual system and content stay fixed.",
+  "version": "0.4.0",
   "author": { "name": "display.dev", "url": "https://display.dev" },
   "homepage": "https://display.dev/docs/visualize",
   "repository": "https://github.com/display-dev/visualize",

HARNESSES.md

@@ -50,3 +50,7 @@ This table records observed host/route evidence, not operating instructions. The
 | `openai-api` | verified with configured OpenAI API on 2026-08-24 | `gpt-image-2` through the Images API; one no-reference generation produced a visually inspected 1024×1024 PNG (1,465,663 bytes), and one single-reference edit produced a visually inspected 1536×1024 JPEG (149,859 bytes); `api-key` billing diagnostic; provider bytes and dimensions preserved; one request in each successful run, with no retry or fallback |
 
 Distribution evidence is credential-free: `skills@1.5.20` resolved exactly one local candidate skill and exactly one current public skill in isolated workspaces; Pi's pinned Git package exposed exactly one skill under `pi/agent/skills`; Codex/Cursor manifests parse; and all three committed mirrors match the canonical mount.
+
+## Artifact Explore evidence
+
+Fresh-context acceptance on 2026-08-26 assigned Briefing rail, Evidence ledger, and Decision sequence to three independent subagents with one shared Relay Press brief. The coordinator assembled their scoped fragments into one 38 KB HTML file. Browser checks passed all six direction/viewport states: three same-DOM directions, 1180 px wide and 390 px phone frames, natural heights from 1,195 to 1,925 px, no iframe, no nested scroller, no crop, no horizontal overflow, fixed-content parity, restored URL/selection state, and no console or page errors. Full-page screenshots were visually inspected; the evidence remains disposable under `temp/artifact-explore-single-file-acceptance-2026-08-26/`. The maintained workflow lives in [`visualize/reference/explore-artifact.md`](visualize/reference/explore-artifact.md).

README.md

@@ -16,13 +16,15 @@ Works across Claude Code, Cursor, Codex, OpenCode, Hermes, and Pi.
 
 ## Why visualize?
 
-Three problems with how agents publish HTML today:
+Four problems with how agents publish HTML today:
 
 **1. Every artifact looks the same.** Every coding agent was trained on the same SaaS templates: Inter for everything, purple-to-blue gradients, rounded-square icon tile above every heading, six metric cards in a row, "Get started for free" CTA. Skip the brand guidance and every Report reads as the same Report. A Report from your company should look like your company's Report; today it looks like a generic shadcn demo regardless of who shipped it.
 
 **2. No brand context.** Pasting brand colors into every prompt isn't sustainable, and the agent forgets between sessions. visualize captures voice + visual identity once via `teach`, then every render reads the brand profile and produces a Report that visibly belongs to your company.
 
-**3. Iteration verbs with real contracts.** visualize has five Refine verbs (`simplify`, `bolder`, `quieter`, `animate`, `polish`) plus one Evaluate verb (`review`). Each does one specific thing — `bolder` amplifies visual punch, `simplify` strips decoration, `quieter` tones intensity, `animate` covers motion, `polish` is the terminal quality pass the other Refine verbs hand off to. `review` reports findings without modifying the file.
+**3. Compare real directions before choosing.** `explore artifact` holds the current visual system, content, facts, assets, and actions fixed while it builds materially different responsive document structures in one self-contained HTML review. Switch between wide and 390 px states, scroll each full document normally, and choose before the target changes.
+
+**4. Iteration verbs with real contracts.** visualize has five Refine verbs (`simplify`, `bolder`, `quieter`, `animate`, `polish`) plus one Evaluate verb (`review`). Each does one specific thing — `bolder` amplifies visual punch, `simplify` strips decoration, `quieter` tones intensity, `animate` covers motion, `polish` is the terminal quality pass the other Refine verbs hand off to. `review` reports findings without modifying the file.
 
 ## What's inside
 
@@ -111,6 +113,7 @@ See [`visualize/reference/image-generation.md`](visualize/reference/image-genera
 |---|---|
 | `/visualize <topic-or-path>` | Pick template from intent; compose against brand tokens; write self-contained HTML |
 | `/visualize teach` | Bootstrap (or refresh) the brand profile |
+| `/visualize explore artifact <topic-or-path>` | Compare responsive document structures inside the current visual system |
 | `/visualize polish <path>` | Iteration: alignment, spacing, consistency |
 | `/visualize review <path>` | Iteration: detector findings + LLM judgment |
 | `/visualize simplify <path>` | Iteration: strip decoration |

hermes/design/visualize/AUTHORING.md

@@ -18,6 +18,8 @@ The composition reflex check runs in preflight, before shape sketching. Its outp
 
 `design-systems/catalog-index.json` and the per-system `DESIGN.md` files are reference packages `teach` reads when *deriving* a brand profile. At creation time the model uses the brand profile it has — browsing the catalog as a substitute for the resolved brand is drift, not fidelity. No per-artifact creation pass browses the catalog.
 
+Artifact Explore is also catalog-blind. It explores document structure inside an already resolved visual world; catalog access would silently reopen the identity decision. The future System Explore scope may use catalog entries only as calibration evidence under its own contract.
+
 ### 4. Required shape-gate fields are source-conditional
 
 Unconditional gate fields — pre-committed visible ingredients, primitive budgets, mandatory signature moves — induce format-induced collapse (Findings-EMNLP 2025: SFT 20.8% → DPO 10.8% diversity drop under structured-output requirements). Primitives follow sections that need them. Signature moves exist only when the source motivates one. Ingredients are derived from sections + primitives, not separately listed.
@@ -59,6 +61,8 @@ Recipes live at `patterns/<slug>.md`. They are creation guidance for recurring r
 
 Shells live at `shells/<slug>/` and exist only for behavior-heavy mechanics: slide navigation, keyboard control, hash sync, scaling, print, or similar. A shell README documents content slots, behaviors, accessibility invariants, print/export expectations, and what an agent may customize. Runtime files are read only when the artifact needs to inline or modify mechanics.
 
+Artifact Explore follows the same single-file harness shape as a prototype exploration: review controls sit outside same-DOM candidate roots, each direction scopes its CSS to its own root, and width controls never impose a fixed document height. Temporary candidate drafts and screenshots are construction evidence, not fixtures or a publishable package.
+
 ## Fixtures
 
 Fixtures live under `fixtures/` and are tooling assets. They are not authoring inputs and templates do not reference them. If `fixtures/manifest.json` lists a file, validators must be able to resolve it. Keep fixtures targeted to detector coverage, contrast checks, mobile overflow checks, shell smoke, or human visual inspection.

hermes/design/visualize/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: visualize
-version: 0.3.0
+version: 0.4.0
 license: MIT
 user-invocable: true
-argument-hint: "[teach | simplify | bolder | quieter | animate | polish | review | publish] [<topic-or-path>]"
+argument-hint: "[teach | explore | simplify | bolder | quieter | animate | polish | review | publish] [<topic-or-path>]"
 allowed-tools:
   - Bash(node $SKILL_DIR/scripts/detect.mjs*)
   - Bash(node $SKILL_DIR/scripts/browser-contrast.mjs*)
@@ -31,7 +31,8 @@ description: >
   intents ("create a plan", "make me an implementation plan",
   "generate a diagram", "build a slide deck", "draft a recap",
   "visualize this", "render this as HTML", "make me a status update")
-  and iteration intents ("make this beautiful", "polish this report",
+  and exploration intents ("show me three layouts", "explore document
+  shapes", "compare page directions") and iteration intents ("make this beautiful", "polish this report",
   "make this less generic", "design this", "theme this", "use my
   brand", "iterate on this design", "review this artifact", "make
   this bolder", "make this quieter", "simplify this design",
@@ -63,6 +64,7 @@ Visual conviction can come from composition, typography, density, spatial rhythm
 | Category | Command | Argument | What it does | Reference |
 |---|---|---|---|---|
 | **Build** | `teach` | none | Bootstrap (or refresh) the brand profile. Writes `DESIGN.md` + `PRODUCT.md` at the project root. | `reference/teach.md` |
+| **Build** | `explore` | `artifact <topic-or-path>` | Compare responsive document structures inside the current visual system; waits for selection before changing the target. | `reference/explore.md` |
 | **Refine** | `simplify` | `<path>` | Strip decoration that isn't earning its pixel. Hands off to `polish`. | `reference/simplify.md` |
 | **Refine** | `bolder` | `<path>` | Amplify visual punch on safe / generic artifacts. Hands off to `polish`. | `reference/bolder.md` |
 | **Refine** | `quieter` | `<path>` | Tone down over-decoration without going generic. Hands off to `polish`. | `reference/quieter.md` |
@@ -71,7 +73,7 @@ Visual conviction can come from composition, typography, density, spatial rhythm
 | **Evaluate** | `review` | `<path>` | Deterministic detector findings + LLM judgment. Reports; doesn't modify the file. | `reference/review.md` |
 | **Publish** | `publish` | `<path>` | Push the artifact to display.dev via MCP / CLI / HTTP cascade. | `reference/publish.md` |
 
-Invocation forms: `/visualize teach`, `/visualize polish ./report.html`, `/visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there.
+Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html`, `/visualize polish ./report.html`, `/visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there.
 
 ## Routing rules
 
@@ -80,6 +82,7 @@ Invocation forms: `/visualize teach`, `/visualize polish ./report.html`, `/visua
 3. **First word doesn't match a command**: treat the whole argument as the topic for the default creation flow. Load `reference/create.md`.
 4. **Relationship-diagram route during creation**: when preflight first identifies a likely relationship diagram, load `reference/diagram.md` and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: `reference/diagram-flow.md`, `reference/diagram-system.md`, `reference/diagram-sequence.md`, `reference/diagram-state.md`, or `reference/diagram-hierarchy.md`. Spatial figures use `reference/diagram.md` alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families.
 5. **Generated-image route during creation**: when the approved shape requires generated bitmap imagery, load `reference/image-generation.md` before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt.
+6. **Explore scope**: `explore` always loads `reference/explore.md`, which dispatches the named scope. Artifact Explore has no missing-brand fallback: it stops for `teach` when an incumbent is uncaptured and stops truthfully when no visual authority exists. It never reads the design-system catalog.
 
 ## Hand-off output shape