Section Designer

Marketplace listing update: added the launch explainer film (`media.demo_video_url`). No code, schema, copy or guidance changes; hero and screenshots unchanged from 0.3.3.

A new section type: the live AI agent. section-designer now knows how to place an OPVS agent (SDR / support / concierge / booking) on a SpiderPublish page as a designed section, and — more importantly — how to be honest about the part of that section it cannot measure.

### Added

- **`references/spiderpublish-agent-embed-mechanics.md`** — the contract. The two-MCP naming split (scoped `@spideriq/mcp-publish` routes everything through one `agent_flow({op})` tool; the kitchen-sink `@spideriq/mcp` uses separate `agent_flow_*` names), the 9-op table with real required params, the 3 server-bootstrapped mount surfaces, the `form_factor` → runtime-surface map, the 3 design tiers, origin allowlisting, hydration verification, and a troubleshooting matrix.
- **`recipes/add-a-spiderpublish-agent-to-a-page.md`** — the design loop: placement brief → pick a persona-rich agent → map design-system tokens onto the 8 skin keys → compose + slop-check the header copy → critique with the carve-out → hand off with `unverified` + `post_deploy_checks`.
- **`learnings/2026-07-30-designing-a-section-you-dont-own/`** — why an embedded third-party surface gets a carve-out rather than a weaker gate, and why you verify against the live tool schema instead of the guide.
- **3 triggers** — "add an agent to my page", "embed a SpiderPublish agent", "put a chatbot on this page".

### Changed

- **`SKILL.md`** — new decision-tree branch for the agent-embed flow, new Limitations bullet stating the shadow-root carve-out, 3 new rows in the references table.

### Fixed

- **`scripts/verify-coordination.mjs` was unrunnable in every bundle up to 0.3.2.** It shipped the *draft* variant of its import, pointing at a workbench-relative path that does not exist inside the bundle, so the Layer-7 coordination gate threw `ERR_MODULE_NOT_FOUND` on first run. The shared helper is now vendored alongside it and the import is local, matching the shape sibling skills already ship. The gate now runs and passes 4/4.

### Fixed (corrections to the absorbed source material, verified against `@spideriq/mcp-publish@1.35.0`)

- **`primary_fg` is not a `skin` param.** The live tool exposes exactly 8 skin keys. This has a design consequence, not just a documentation one: the foreground-on-accent contrast cannot be fixed at Tier 1, so the accent must clear WCAG AA *before* it is picked. Promoted to a pre-compose HARD-GATE in the recipe.
- **`escalation` is required** on the `agent` binding (and `escalation.board_id` inside it), not optional.
- **Two opposite dry-run defaults in one tool** — `op=publish` dry-runs by default (needs a `confirm_token` round-trip or nothing happens); `op=create` / `op=update` are opt-in (a single call mutates). Both documented explicitly so neither gets generalized to the other.

### Fixed

- **Feature bullet "HARD-GATE on AI-slop"** — the description was truncated on the live 0.3.1 card because an unquoted `#3b82f6` was parsed as a YAML comment. Quoted the value so the full bullet ("Trips on the default #3b82f6 / Inter / system-ui before it composes.") renders.

Marketplace card asset kit (SPEC-3 pilot). No skill-logic changes.

### Added

- **`media:` block** — top-level marketplace card visuals: hero (150 systems → CRITIQUE gate → finished section) + 3 illustrated panels (concept loop · peer chain · before/after output). Dark-board chalk, rendered on SpiderGate kie/nano-banana-2, hosted on SpiderMedia. First `@di-atomic` card to ship the full asset kit.
- **`marketing.features[].icon`** — each feature bullet now carries an emoji glyph.

### Changed

- **`marketing.long_description`** — rewritten to first-person Martin voice, numbers over adjectives (Problem → Solution → Worked example → peer chain), tightened to ~185 words.
- **`marketing.features`** — 6 multi-sentence entries → 5 verb-led one-liners (≤90 chars) with icons.

Reverse-flow lessons from analyzing `opvs-ui-designer` (Martin's own project skill, 2026-06-17). Four load-bearing changes.

### Added

- **`molds/`** — physical HTML blueprints as first-class artifacts (pattern stolen from `opvs-ui-designer`'s molds/). Each `.html` file begins with an `<!-- MOLD: ... -->` frontmatter block declaring family, dial_compatibility, when_to_use, not_for, components_used, requires_tokens, canonical_specs, provenance, and a ready-to-publish SpiderPublish block_payload. Agents copy the mold's HTML verbatim + prepend a MOLD declaration comment at the top of their output.
- **`molds/README.md`** — searchable index of every mold with dial_compatibility + when_to_use + SpiderPublish block-type. Turns molds/ into a scannable library, not a flat directory of filenames.
- **3 seed mold files** (migrated from v0.2.1 registry entries):
  - `molds/stripe-fintech-pricing-hero.html`
  - `molds/linear-app-b2b-cta-section.html`
  - `molds/apple-premium-consumer-features-grid.html`
- **`scripts/batch-generate-tokens.mjs`** — offline batch generator that walks every `references/design-systems/<system>/DESIGN.md` and emits a pre-parsed `tokens.yaml` alongside each. Ran once against 150 systems → 150 `tokens.yaml` files committed.
- **Rule 8 in `critique-score.sh`: MOLD DECLARATION** — enforces that composed output starts with `<!-- MOLD: <slug>.html -->` naming the copied mold, OR `<!-- MOLD: none (reason) -->` for compose-from-tokens flows. Skipping the declaration = skipping Step 2 of the compose flow. Stolen from `opvs-ui-designer`'s rule 7.
- **Rule 9 in `critique-score.sh`: COMPONENT SPEC** — if a mold IS declared, reads that mold's `canonical_specs` frontmatter and verifies the composed output respects every spec value (font-family, weight, size, line-height, letter-spacing, color, padding, border-radius, grid columns, gap). Catches "agent copied the mold BUT tweaked the button padding" silent-degradation. Stolen from `opvs-ui-designer`'s rule 11.

### Changed

- **`scripts/critique-score.sh`** — 7 measurable dims → **9 measurable dims** (added mold_declaration + component_spec). JSON schema bumped to `section-designer.critique.v3`. Honesty footer updated to reference both new dims.
- **`scripts/extract-tokens.sh`** — fast-path: prefers pre-parsed `tokens.yaml` (~2ms lookup) over re-parsing DESIGN.md at runtime (~200ms). Falls back to inline parsing if `tokens.yaml` is missing or stale. ~100× speedup + eliminates LLM transcription drift when the agent iterates.
- **`SKILL.md` Step 2 (Grab tokens)** — renamed to "Grab a mold OR extract tokens." Agent scans `molds/README.md` first for a matching physical blueprint; falls back to `extract-tokens.sh` when no mold matches. MOLD declaration comment is now mandatory at the top of every composed output.
- **`SKILL.md` Step 4 (Critique gate)** — now says "9 dimensions" instead of "7." Rules 8 + 9 called out by name.

### Deprecated / archived

- **v0.2.1 `registry/` directory** — superseded by `molds/`. Moved to `source/legacy/registry-v0.2.1/` for provenance. The 3 REGISTRY.md entries there are the source-of-truth for the 3 seed molds' provenance blocks.

### Not changed (deliberate)

- Guidance-only shape unchanged: `skills: []` + 6 peer_dependencies. This is still a Tier-2 pure-guidance skill.
- v2.2 Coordination block unchanged. `verify-coordination.mjs` still PASSes.
- The 47-item `PRE-FLIGHT-check.md` unchanged.
- All 150 `references/design-systems/<name>/DESIGN.md` files unchanged (only their sibling `tokens.yaml` is new).
- SpiderPublish handoff contract unchanged (`references/spiderpublish-handoff.md`).

### Migration for agents already using v0.2.1

1. Composed sections from v0.2.1 that lack a MOLD declaration now trip rule 8. Prepend `<!-- MOLD: none (v0.2.1 legacy) -->` to grandfather old outputs.
2. If your v0.2.1 composition happened to match a shipped mold's shape, replace the free-hand HTML with a copy of the mold's file — you'll pick up automatic rule 9 spec verification.
3. Re-run `bash scripts/critique-score.sh <composed>` — the JSON schema is now v3 with 2 new keys under `measurable`. Existing `pre-flight-check.md` walk is unchanged.

Taste-skill deep-dive lessons applied. All 7 stolen patterns + SpiderPublish bridge throughout. Source: `Leonxlnx/taste-skill` (MIT, Vercel OSS Program 2026). Full provenance in `learnings/2026-06-17-taste-skill-deep-dive-applied/learning.md`.

### New references

- **`references/dials.md`** — The Three Dials (DESIGN_VARIANCE / MOTION_INTENSITY / VISUAL_DENSITY). Orthogonal register vocabulary on top of the 150 named systems. Includes brief→dial inference table + use-case presets + dial→SpiderPublish-Tier mapping.
- **`references/ai-tells-catalog.md`** — 13-section catalog of production-tested LLM Tells. Visual / typography / layout / content / hero / eyebrows / separators / em-dash ban / CTAs / marketing copy / layout patterns / decoration / locale. Machine-readable ABSENCE SIGNALS block feeds `critique-score.sh`.
- **`references/vertical-anti-defaults.md`** — Per-vertical banned palette + font defaults. Stole the premium-consumer beige+brass ban verbatim from taste-skill, extended to fintech, B2B SaaS, agency, and REACH-compliance verticals. Rotation alternatives table per vertical.
- **`references/pre-flight-check.md`** — 47-item checklist the agent walks after `critique-score.sh` PASSes. Section L is the SpiderPublish hand-off readiness block (block_payload + tenant-scope + two-phase deploy + spidermedia + `template_inspect_block_fields` pre-checks).

### Script extensions (`critique-score.sh`)

- **6th measurable dim: dash discipline.** Zero em-dash + en-dash tolerance. Regex `[—–]` against visible text. Single hit auto-fails. Context shown for first 3 hits.
- **7th measurable dim: eyebrow count.** Heuristic detection of `uppercase tracking` micro-labels + common eyebrow class names. Cap: ≤ `ceil(sectionCount / 3)`. Catches the #1 production-tested violated rule (every section getting a templated eyebrow).
- AI-slop blacklist now sources from `ai-tells-catalog.md` (filler verbs / eyebrow phrases / hero version labels / brand-slop names / scroll-cue phrases) — adding new Tells to the catalog auto-extends the script.
- Honesty footer now references `pre-flight-check.md` as the mandatory next step after script PASS.

### New registry entries (seeded)

- **`registry/stripe-fintech-pricing-hero/`** — Reproduced verbatim from v0.1.0's tested 4.82/5 conversation example. Includes SpiderPublish `hero` block_payload.
- **`registry/linear-app-b2b-cta-section/`** — Composed 2026-06-17, 4.74/5 on real critique-score.sh. Demonstrates the "single CTA per pre-footer" discipline.
- **`registry/apple-premium-consumer-features-grid/`** — Demonstrates vertical-default ROTATION. Apple tokens applied verbatim BUT palette rotated to Cold Luxury (silver-grey + smoke) per premium-consumer ban in `vertical-anti-defaults.md`.

### SKILL.md updates

- Step 1 (Discover) now leads with purpose + audience + **vertical** + **Three Dials**, not just purpose + audience.
- Design Read one-liner discipline added: agent emits a one-line declarative read BEFORE composing.
- HARD-GATE extended: now checks (a) system chosen, (b) `extract-tokens.sh` run, AND (c) dials set. Skipping the dials → silently composing at the AI-competent middle.
- Step 4 (Critique gate) extended to reference Pre-Flight as mandatory companion after script PASS.
- References table at bottom expanded with 4 new entries + the registry path.

### v0.2.0 unchanged

- Guidance-only canonical shape (`skills: []` + 6 peers) — unchanged
- v2.2 Coordination block — unchanged, still PASS
- All 7 v0.2.0 tests still apply

Guidance-only conversion + Hyperframes-deep-dive lessons applied.

### Per the 2026-06-17 DIRECTIVE on board card `fc031f4b-fdbc-4627-8b65-b66407445166`

- **Removed** `client/schema.yaml` and the parity-placeholder `designSection` method.
  Archived to `source/legacy/client-v0.1.0/`. Per OPVS DEFINITIVE rule (2026-06-17):
  section-designer is guidance-only — no backend, no callable API. v0.1.0 declared a
  fake method that would have 404'd on any `skill_call`.
- **Added** `skills: []` + 6 `peer_dependencies` at live marketplace versions
  (agentdocs ≥1.1.0, agentmemory ≥1.0.0, agentboard ≥1.2.0, opvs-protocol ≥1.0.0,
  voice-builder ≥0.2.0, copy-engine ≥0.4.1).
- **Renamed** `manifest.yaml` → `package.yaml` per OPVS canonical guidance-only shape.
- **Fixed** `docs:` block — `docs.skill_guide` now points at `SKILL.md` (what
  `skill_read` returns); `docs.readme` is `README.md` (marketplace listing);
  `docs.changelog` is this file. Same fix copy-engine made v0.4.0 → v0.4.1.
- **Created** `README.md` + `CHANGELOG.md` at bundle root to satisfy security check 7
  (required-docs).
- **Bumped** version 0.1.0 → 0.2.0. v0.1.0 (package_id `d824f541-…`) stays in
  registry as prior release.

### Per the Hyperframes deep-dive (`research-hyperframes-deep-dive-2026-05-23.md`)

- **Added** `scripts/critique-score.sh` — script-driven 5-dim critique gate (WCAG AA
  contrast, tap-target 44px, AI-slop blacklist, token-verbatim, heading hierarchy).
  Output JSON + honesty footer the agent pastes verbatim. **The single biggest
  v0.2.0 change.** Eliminates the agent-self-grades-4.82/5 theater that bit v0.1.0
  when actually tested 2026-05-24 ("not useful at all").
- **Added** `scripts/extract-tokens.sh` — deterministic token derivation from a
  chosen DESIGN.md. Output JSON becomes the comparison vocabulary for
  `critique-score.sh`'s token-verbatim check. Eliminates LLM transcription drift.
- **Rewrote** `SKILL.md` per Hyperframes anatomy:
  - Description is now ~120 words enumerating phrasings + routing to peers
    (router-config pattern).
  - One `<HARD-GATE>` between discovery and compose, naming the most-likely
    AI-slop default values (#3b82f6, Inter, system-ui, Roboto) so violations are
    self-evident.
  - Discovery flow reordered — purpose+audience FIRST, system pick AFTER
    (Hyperframes Story 4: concept-first beats step-by-step).
  - References indexed at the bottom with `**Always read**` markers.
  - "Build what was asked" + auto-mode-verification corollary added.
  - "What I did NOT verify" honest-disclosure pattern in every hand-off.
- **Rewrote** `references/critique-rubric.md` as prose-per-dim (what excellence
  *feels like* per system type) instead of fill-in score template. Hyperframes
  Story 2: lookup tables get cargo-culted; prose gets adapted.
- **Reordered** `references/discovery-rules.md` — mode picker first, then
  purpose + audience + constraints + design language.
- **Added** `references/spiderpublish-handoff.md` — the consumer contract for
  agents that publish via @spideriq/spiderpublish.
- **Added** `references/media-handoff.md` — the asset upload contract via
  @spideriq/spidermedia (returns CDN URL, never hand-build).

### v2.2 Coordination

- **Added** `## Coordination` block to `SKILL.md` declaring all 4 OPVS upstream
  surfaces:
  - `/#agentboard` — n/a (single-pass design, no multi-step state to track)
  - `/#agentdocs` — section archive in project `di-atomic-section-archive`
  - `/#agentmemory` — recall prior brand+system pairings + WCAG override deviations
  - `/#opvs-protocol` — inbound from copy-engine; outbound to spidermedia → spiderpublish
- **Added** `scripts/verify-coordination.mjs` — Layer-7 wrapper of the shared
  workbench helper. PASS/FAIL on the 4 cross-refs.

Initial Path-A marketplace publish at 100/100 security score.

- 6 declared triggers + 5-dim self-critique gate
- 150 DESIGN.md design-system references + 5 quick-pick directions
- Adapted from `nexu-io/open-design` (Apache-2.0)
- Mac-local install at `~/.claude/skills/section-designer/` + marketplace listing
- Package id `d824f541-47cb-40fb-93c1-a4657e2b34dc`

**Known issue (caught 2026-05-24):** the LLM-self-graded critique was the wrong
shape. Despite scoring 100/100 on validator gates and passing the convergence
rule on every test, an actual end-to-end live test was judged "not useful at all."
v0.2.0 fixes this by moving the gate into `scripts/critique-score.sh`.