@jaimevalasek/aioson 1.4.0 → 1.6.0

package/template/.aioson/skills/process/design-hybrid-forge/references/output-contract.md

@@ -0,0 +1,291 @@
+# Output Contract — design-hybrid-forge
+
+Load when running Phases 4 and 5 (skill generation + preview generation).
+
+Defines exactly what each file must contain and the minimum quality bar.
+
+---
+
+## File generation order
+
+Write in this order — each file informs the next:
+
+1. `SKILL.md` — identity + rules (uses crossover spec from phase 3)
+2. `references/design-tokens.md` — all CSS variables (uses accent + substrate from phase 2)
+3. `references/art-direction.md` — expression modes + signature library (uses pillars from phase 2)
+4. `references/components.md` — component library (uses tokens + art direction)
+5. `references/patterns.md` — page layouts (uses components)
+6. `references/dashboards.md` — dashboard presets (uses patterns + tokens)
+7. `references/websites.md` — landing patterns (uses components + art direction)
+8. `references/motion.md` — animations (uses tokens + components)
+9. `.skill-meta.json` — author, parentage, generator, install/distribution metadata
+10. `previews/{name}.html` — dashboard preview (uses all above)
+11. `previews/{name}-website.html` — landing preview (uses all above)
+12. `AGENTS.md` — register the installed skill section when that file exists
+
+---
+
+## File-by-file requirements
+
+### SKILL.md
+
+Required sections (must all be present):
+- Frontmatter: `name`, `description` (includes activation keywords)
+- One-paragraph system description
+- `## Package structure` (directory tree)
+- `## Activation rules` (when to load / when not to)
+- `## Responsibility boundary` (defines / does not decide)
+- `## Loading guide` (table: task → which references to load)
+- `## Visual signature — three pillars` (the three from phase 2)
+- `## Hybrid DNA` (from A / from B / new in hybrid — explicit)
+- `## Modifier DNA` (only if modifiers were used)
+- `## Variation Overlay` (only if a variation preset / overlay was selected)
+- `## Theme system` (default theme + optional, HTML data-theme snippet)
+- `## Visual DNA` (complete CSS color specs for dark + light, including hex values)
+- `## Layout structure` (ASCII diagram of the main app shell)
+- `## Signature details` (list of specific CSS rules for the signature moves)
+- `## Application rules` (7–10 binding rules)
+- `## Intent before visuals` (3 questions + bad/good examples)
+- `## Workflow discipline` (7-step checklist)
+- `## Non-negotiable quality gates` (8–12 gates)
+- `## Positioning vs parent skills` (comparison table vs both parents)
+- `## Delivery modes` (greenfield + brownfield)
+
+The file must state clearly that the hybrid is selected as one design skill and must not be blended live with other active design skills.
+
+### references/design-tokens.md
+
+Required content:
+- Typography strategy (system vs Google Fonts decision)
+- Complete `:root` block: typography tokens, spacing (4px rhythm), radius, transitions, z-index
+- `[data-theme="dark"]` block: ALL color tokens
+- `[data-theme="light"]` block: ALL color tokens
+- **Hybrid glass/surface tokens** (unique to this hybrid — the new surface system)
+- Shadow tokens (tinted with hybrid accent — never plain black)
+- Layout tokens (sidebar width, nav height, content widths)
+- Breakpoints
+- Interaction guardrails (at least 4 rules)
+- Token scope guardrails (rule 1–4 with safe/unsafe examples)
+- Admin compact density scale (if structure parent = cognitive-core or clean-saas)
+
+If modifiers were used, token changes must stay inside their allowed lane. Example: a motion modifier must not redefine layout width tokens.
+If a variation overlay exists, reflect it in tokens only where it changes expression without violating the parent-owned structure/substrate rules.
+
+Minimum: dark theme has at least 8 bg/surface tokens, 6 accent tokens, 6 semantic tokens, 4 shadow tokens.
+
+### references/art-direction.md
+
+Required content:
+- Core rule ("same system, different expressions")
+- Mandatory pre-build outputs (7 items)
+- **5 expression modes** — each with: for/feel/composition/visual cues/signature ideas
+- Signature library (table with ≥10 reusable details)
+- Anti-generic tests (≥4 tests, at least one unique to this hybrid)
+- What makes each mode distinct (table contrasting the 5 modes)
+
+If modifiers exist, call out exactly where they are allowed to appear and where they are forbidden.
+If a variation overlay exists, describe how it changes the expression modes without turning them into unrelated themes.
+
+### references/components.md
+
+Required: ≥20 named components, each with:
+- Name and purpose
+- Key CSS properties (using tokens, never hardcoded values)
+- Hover/active/focus states
+- The hybrid-specific surface treatment (glass/texture/depth)
+
+Must include: top bar, sidebar, stat card, section header, data table, badge/chip, modal, button variants (primary gradient + secondary + ghost), form input, dropdown, at least one hybrid-specific component that doesn't exist in either parent.
+
+### references/patterns.md
+
+Required: ≥6 page layout patterns, each with:
+- ASCII diagram of the layout
+- CSS skeleton (grid/flex, sizing, overflow)
+- Fallback rules
+- Use case (when to choose this pattern)
+
+Must include: main app shell, dashboard shell (≥1 operational variant), auth page, settings page.
+
+### references/dashboards.md
+
+Required:
+- General rules section (≥6 rules)
+- Chart color palette (CSS variables)
+- Chart rendering rules (one per chart type)
+- **5 dashboard presets**, each with:
+  - Expression mode
+  - Feel (concrete words)
+  - Domain vocabulary
+  - Full layout description (stat row + main panels + table/feed)
+  - Signature move
+
+### references/websites.md
+
+Required:
+- General rules section
+- Page shell CSS
+- ≥2 hero variants (at least one split layout, one centered/atmospheric)
+- ≥4 section patterns (feature grid, proof rail, pricing, testimonials/CTA)
+- Footer pattern
+- Anti-patterns list (≥5)
+
+### references/motion.md
+
+Required:
+- Timing philosophy (3–4 sentences)
+- Core easing functions (CSS custom properties)
+- ≥8 named animations, each with CSS keyframes + usage context
+- Reduced motion block (`@media (prefers-reduced-motion: reduce)`)
+- Performance rules (≥4)
+
+### .skill-meta.json
+
+Required content:
+- `source: "generated"`
+- `generation_mode: "project-local"`
+- `installedAt`
+- `author.name` when the user provided one
+- `generator.skill: "design-hybrid-forge"`
+- `generator.model` when the runtime/tool exposes it
+- `generator.tool` when known (`claude`, `codex`, etc.)
+- `parents.primary` with exactly 2 entries
+- `parents.modifiers` with 0–2 entries by default, or 0–3 only when advanced mode was enabled
+- `promotion.status` (`local`, `candidate`, `promoted`)
+- `variation_profile` when a preset/overlay was selected
+- `variation_profile.modifier_policy` when the active preset declared it
+
+Recommended shape:
+
+```json
+{
+  "source": "generated",
+  "generation_mode": "project-local",
+  "installedAt": "2026-03-30T00:00:00.000Z",
+  "author": {
+    "name": "ACME Design Team"
+  },
+  "generator": {
+    "skill": "design-hybrid-forge",
+    "tool": "codex",
+    "model": "gpt-5.x"
+  },
+  "parents": {
+    "primary": ["cognitive-core-ui", "glassmorphism-ui"],
+    "modifiers": ["bold-editorial-ui"]
+  },
+  "variation_profile": {
+    "modifier_policy": "up_to_2_modifiers",
+    "style_modes": ["cinematic-immersive"],
+    "motion_system": ["scroll-driven-scenes"],
+    "advanced_css": ["scroll-driven-animations", "view-transition-api"]
+  },
+  "promotion": {
+    "status": "local"
+  }
+}
+```
+
+### AGENTS.md registration
+
+When `AGENTS.md` exists in the project, update the "Installed skills" section so Codex can invoke the new hybrid via `@{slug}`.
+
+If `.aioson/context/design-variation-preset.md` was consumed for the generation:
+- preserve the history snapshot under `.aioson/context/history/design-variation-presets/`
+- remove or archive the active preset from `.aioson/context/` after the hybrid files are finished
+- do not treat that preset as the permanent visual configuration of the project
+
+Required row format:
+
+```markdown
+| @{slug} | `.aioson/installed-skills/{slug}/SKILL.md` | {short description} |
+```
+
+---
+
+## Preview requirements
+
+### Dashboard preview (`previews/{name}.html`)
+
+Must show:
+- The aurora/substrate background visible through glass panels
+- Command strip with live dots (if structure parent = cognitive-core)
+- Top bar with logo + tab nav + actions
+- Sidebar with section labels + nav items
+- Stat row (4 cards minimum)
+- At least one chart (can be SVG simulation)
+- At least one feed or alert panel
+- Full data table (with header + 3–5 rows)
+- All glass surfaces with `::before` reflection
+- Hybrid accent gradient on at least 3 visible elements
+- AIOSON badge (fixed, top-right)
+- Must render correctly with no external dependencies beyond Google Fonts
+
+### Landing page preview (`previews/{name}-website.html`)
+
+Must show:
+- Full-page substrate background (fixed, aurora gradient or equivalent)
+- Glass navigation bar (fixed, scroll-opaque behavior via CSS class)
+- Hero section (split or centered — not a plain two-column with no visual punch)
+- At least one decorative atmosphere element (orb, gradient blob, etc.)
+- Proof rail / social proof strip
+- Feature cards section (≥6 cards, 3-column grid)
+- Pricing section (3 tiers, featured card visually distinct with gradient border)
+- Footer with glass treatment
+- Hybrid accent gradient on hero heading or CTA
+- AIOSON badge
+
+### Technical requirements (both previews)
+
+- Single `.html` file (no external CSS or JS files)
+- Google Fonts loaded via `<link>` (Inter + JetBrains Mono)
+- All CSS in `<style>` tag in `<head>`
+- All design tokens as CSS custom properties in `:root`
+- Glass elements use `@supports (backdrop-filter: blur(1px))` fallback or document that they don't need it
+- No JavaScript required for visual display (JS only for optional interactions)
+- Renders at 1440px wide (the preview standard)
+
+---
+
+## Optional promotion requirements
+
+Only for explicit core-promotion mode:
+- prepare a gallery card for `docs/design-previews/index.html`
+- prepare the hybrid for `.aioson/skills/design/{name}/`
+- update naming/registry files only in the AIOSON core repo
+
+### Gallery card requirements
+
+When adding to `index.html` in core-promotion mode:
+
+```html
+<!-- Hybrid card structure -->
+<div class="skill-card">
+  <div class="preview-thumb thumb-{name}">
+    <span class="preview-label">{3-word vibe description}</span>
+  </div>
+  <div class="card-body">
+    <div class="card-header">
+      <span class="card-name accent-{name}">{Display Name}</span>
+      <span class="hybrid-badge">✦ Hybrid</span>    <!-- REQUIRED for hybrids -->
+    </div>
+    <p class="card-description">
+      {Parent A} × {Parent B}. {2–3 sentence description of the hybrid identity.}
+    </p>
+    <div class="card-meta">
+      <!-- 4 use case pills -->
+    </div>
+    <div class="card-links">
+      <a href="{name}.html">Dashboard</a>
+      <a href="{name}-website.html">Landing page</a>
+    </div>
+  </div>
+</div>
+```
+
+Thumbnail CSS must:
+- Use the hybrid's substrate as background
+- Include a `::before` pseudo-element showing the glass surface treatment
+- Include an atmospheric `::after` showing the accent glow
+- Be visually distinct from both parent thumbnails in the gallery
+
+Update the skill count in `hero-meta` and `footer`.

package/template/.aioson/skills/process/design-hybrid-forge/references/pair-compatibility.md

@@ -0,0 +1,117 @@
+# Pair Compatibility — design-hybrid-forge
+
+Load when choosing which two base skills to combine this week.
+
+---
+
+## The tension principle
+
+The best hybrid pairs have **creative tension** — they pull in different directions, and the hybrid resolves the tension into something neither parent could be alone.
+
+Two skills that are too similar produce a redundant hybrid. Two skills that are completely incompatible (same aesthetic, same structure, same depth model) produce noise, not synthesis.
+
+**Rule:** choose pairs where one skill is structure-dominant and the other is aesthetic-dominant, OR where they share a dimension but differ radically in another.
+
+---
+
+## Skill taxonomy
+
+Each base skill has a primary role:
+
+| Skill | Role | Structure model | Aesthetic model | Default theme |
+|---|---|---|---|---|
+| `cognitive-core-ui` | Structure | Command center, dense, mono rails | Solid dark surfaces, teal accent | Dark |
+| `clean-saas-ui` | Structure | Systematic B2B, medium density | Neutral solid surfaces, blue accent | Light |
+| `neo-brutalist-ui` | Structure | Raw grid, brutal honesty | Hard borders, yellow accent, zero blur | Light |
+| `bold-editorial-ui` | Structure + Aesthetic | Editorial rhythm, section contrast | Dark cinematic, red-orange accent | Dark |
+| `glassmorphism-ui` | Aesthetic | Glass layers, gradient substrate | Transparent surfaces, violet-blue | Light |
+| `warm-craft-ui` | Aesthetic | Breathable, serif-driven | Warm solid surfaces, terracotta | Light |
+| `premium-command-center-ui` | Structure + Aesthetic | Tri-rail, operational | Aurora-glass, graphite | Dark |
+| `interface-design` | Neutral | Flexible | Flexible | Adaptive |
+
+---
+
+## Compatibility matrix
+
+`✦` = High tension, strong hybrid potential
+`◈` = Medium tension, viable
+`○` = Low tension, too similar or too incompatible
+`✕` = Avoid, redundant (same family)
+
+| | cognitive-core | clean-saas | neo-brutalist | bold-editorial | glassmorphism | warm-craft | premium-command | interface-design |
+|---|---|---|---|---|---|---|---|---|
+| **cognitive-core** | — | ◈ | ✦ | ✦ | ✦ | ✦ | ✕ | ◈ |
+| **clean-saas** | ◈ | — | ✦ | ◈ | ✦ | ✦ | ◈ | ○ |
+| **neo-brutalist** | ✦ | ✦ | — | ✦ | ✦ | ✦ | ◈ | ◈ |
+| **bold-editorial** | ✦ | ◈ | ✦ | — | ✦ | ◈ | ◈ | ◈ |
+| **glassmorphism** | ✦ | ✦ | ✦ | ✦ | — | ✦ | ✕ | ◈ |
+| **warm-craft** | ✦ | ✦ | ✦ | ◈ | ✦ | — | ◈ | ◈ |
+| **premium-command** | ✕ | ◈ | ◈ | ◈ | ✕ | ◈ | — | ○ |
+| **interface-design** | ◈ | ○ | ◈ | ◈ | ◈ | ◈ | ○ | — |
+
+---
+
+## Completed hybrids (do not repeat)
+
+| Pair | Hybrid name | Shipped |
+|---|---|---|
+| cognitive-core-ui × glassmorphism-ui | `aurora-command-ui` | 2026-03-29 |
+
+---
+
+## Recommended next pairs (high tension, not yet done)
+
+**Tier 1 — Maximum tension, clear identity:**
+
+| Pair | Anticipated identity | Best for |
+|---|---|---|
+| `neo-brutalist-ui` × `glassmorphism-ui` | Raw structural grid over a frosted aurora — brutal honesty made luminous | Indie dev tools, open source dashboards |
+| `warm-craft-ui` × `cognitive-core-ui` | Earthy command center — serifs + mono rails, terracotta + teal tension | AI agent platforms with human focus, productivity SaaS |
+| `neo-brutalist-ui` × `cognitive-core-ui` | Cold data brutalism — raw borders, dense mono, no decoration, only signal | Infrastructure monitoring, CLI-adjacent tools |
+| `bold-editorial-ui` × `glassmorphism-ui` | Dark glass editorial — cinematic depth through transparency, editorial scale | SaaS marketing, product launches, AI platforms |
+| `warm-craft-ui` × `glassmorphism-ui` | Warm aurora — soft glass over warm gradients, terracotta glow, humanized depth | Wellness, productivity, note-taking, B2C SaaS |
+| `clean-saas-ui` × `glassmorphism-ui` | Crystalline enterprise — minimal glass, disciplined structure, enterprise-grade glass | B2B SaaS with premium feel, enterprise admin |
+
+**Tier 2 — Strong but more constrained:**
+
+| Pair | Anticipated identity |
+|---|---|
+| `bold-editorial-ui` × `cognitive-core-ui` | Dark editorial command — large display type + mono rails, red-orange × teal tension |
+| `neo-brutalist-ui` × `warm-craft-ui` | Crafted brutalism — raw structure + handmade warmth, artisan dev aesthetic |
+| `clean-saas-ui` × `bold-editorial-ui` | Enterprise editorial — clean precision + cinematic moments, professional drama |
+
+---
+
+## Pair selection questions
+
+Before committing to a pair, answer:
+
+1. **Can you name the creative tension in one sentence?** If not, the pair may be too similar.
+2. **Which skill wins the substrate?** One parent's background model must dominate — it cannot be 50/50.
+3. **What is genuinely new?** Name one element that exists in neither parent and will only exist in the hybrid.
+4. **Who uses this?** If the target user is identical to both parent skills, the hybrid is redundant.
+5. **Does the name suggest a third thing?** The hybrid's name must not sound like "A + B" but like a new concept.
+
+---
+
+## Optional modifier lane
+
+After the core pair is chosen, you may optionally add up to 2 modifier skills. A 3rd modifier is allowed only when the user explicitly enables advanced mode or the active variation preset carries `modifier_policy: "up_to_3_modifiers"`.
+
+Modifier rules:
+- Modifiers are optional. The hybrid must still stand on the 2 primary parents alone.
+- Modifiers cannot own substrate, layout system, navigation model, or density baseline.
+- Modifiers may influence only accent refinement, motion, website narrative patterns, or one small component family.
+- If a modifier makes the identity harder to describe in one sentence, remove it.
+- `interface-design` is allowed as a modifier, but is too neutral to be a primary parent.
+
+---
+
+## Anti-pairs
+
+Avoid these regardless of aesthetic appeal:
+
+- `cognitive-core-ui` × `premium-command-center-ui` — same domain, same depth model, redundant
+- `glassmorphism-ui` × `premium-command-center-ui` — too similar (both glass + aurora)
+- `interface-design` × any skill — interface-design is a neutral craft package, hybrids require distinct DNA poles
+- Any skill with itself — obvious

package/template/.aioson/skills/process/design-hybrid-forge/references/quality-gates.md

@@ -0,0 +1,188 @@
+# Quality Gates — design-hybrid-forge
+
+Load when validating a hybrid before shipping (Phase 6).
+
+Run all gates in order. A hybrid that fails any gate is not done — return to the phase indicated.
+
+---
+
+## Gate A — Identity clarity
+
+**Question:** Can you describe this hybrid in one sentence without naming its parents?
+
+Pass: The sentence names a specific vibe, specific user, specific use case.
+> "A dark glass command center where operational precision lives inside an aurora gradient — for teams running security operations or AI platforms."
+
+Fail: The sentence is vague, generic, or only makes sense by referencing the parents.
+> "It combines dark dashboard style with glass effects."
+
+**If fail:** Return to Phase 2 (crossover spec) — the identity is not clear enough.
+
+---
+
+## Gate B — The third thing test
+
+**Question:** Name 3 elements in the hybrid that exist in NEITHER parent.
+
+Pass: You can name 3 specific CSS values, interaction patterns, or composition rules that are genuinely new.
+
+Fail: Every element in the hybrid can be traced back to parent A or parent B — the hybrid is a mashup, not a synthesis.
+
+**If fail:** Return to Phase 3 — identify at minimum 3 new elements before writing files.
+
+---
+
+## Gate C — Accent fusion test
+
+**Question:** Is the accent gradient a genuine fusion, or is it just parent A's color + parent B's color next to each other?
+
+Run this test: Cover the gradient label. Show only the gradient swatch to someone who knows both parents. Would they say "oh, that's just A and B stacked"?
+
+Pass: The gradient produces a new color perception. The transition between the two endpoints creates a third color that is the hybrid's identity.
+
+Fail: The gradient is jarring or reads as "two separate accents." No new color emerges.
+
+**If fail:** Adjust the gradient angle, midpoint color, or one endpoint. The goal is a gradient that reads as one accent, not two.
+
+---
+
+## Gate D — Substrate visibility test
+
+**Question:** Is the substrate visible through the glass/surface panels?
+
+Test procedure:
+1. Open the dashboard preview.
+2. Look at the glass stat cards. Can you see the background gradient through them?
+3. Look at the sidebar. Can you see the gradient?
+
+Pass: The aurora/gradient is clearly visible through at least 60% of glass surfaces. The interface "lives inside" the background.
+
+Fail: The glass panels are too opaque — the background looks like a solid dark or light color behind the panels, not a visible gradient.
+
+**If fail:** Reduce glass surface opacity. For dark glass: stay at or below `rgba(r,g,b,0.75)`. For white glass: stay at or below `rgba(255,255,255,0.70)`. Do not "solidify" the panels.
+
+---
+
+## Gate E — Structure legibility test
+
+**Question:** Does the command/layout structure read clearly, or does the aesthetic overwhelm the hierarchy?
+
+Test procedure:
+1. Open the dashboard preview.
+2. Blur your eyes. Can you still see: top bar / sidebar / content area / section headers?
+3. Without reading text, can you identify which element is the stat number vs body copy vs section label?
+
+Pass: The layout structure is clear at a glance, even through the glass/aesthetic treatment.
+
+Fail: The blur/gradient/texture treatment makes sections bleed into each other. Hierarchy is lost.
+
+**If fail:** Increase contrast between structure-defining elements (top bar, sidebar, section headers) and content areas. The glass treatment must respect structure, not obscure it.
+
+---
+
+## Gate F — Sameness test
+
+**Question:** Could this hybrid be mistaken for a default AI dashboard, a Tailwind UI starter, or a generic dark theme?
+
+Test procedure:
+1. Remove all brand names from the preview.
+2. Show it alongside 3 other dark UI screenshots.
+3. Does it have at least one immediately distinctive visual element?
+
+Pass: There is one element that could not exist in a generic dashboard — something that is clearly the result of this specific hybrid pairing.
+
+Fail: The design looks like "dark + blur" with no further identity.
+
+**If fail:** Identify the signature move and amplify it. Make it appear in at least 5 places. The signature should be the first thing you notice.
+
+---
+
+## Gate G — Parent distinction test
+
+**Question:** Is the hybrid visually distinct from BOTH parents?
+
+Test procedure:
+1. Open the dashboard preview alongside `cognitive-core-ui.html` and `glassmorphism-ui.html` (or the two actual parents).
+2. Does the hybrid look like parent A? If yes — the aesthetic from parent B was not applied strongly enough.
+3. Does the hybrid look like parent B? If yes — the structure from parent A was not applied strongly enough.
+
+Pass: Looking at all three side by side, the hybrid is clearly different from both parents while sharing DNA with each.
+
+Fail: The hybrid looks like a minor variant of one parent.
+
+**If fail:** Identify which parent is dominant and push the contribution from the other parent harder. Usually this means making the new elements (Gate B) more prominent.
+
+---
+
+## Gate H — Preview completeness
+
+**Question:** Do both HTML previews satisfy all requirements from `output-contract.md`?
+
+Checklist (dashboard preview):
+- [ ] Substrate background visible through glass panels
+- [ ] Command strip or equivalent live indicator (if structure parent warrants it)
+- [ ] Top bar + sidebar + stat row + chart + feed/alert + data table
+- [ ] Hybrid accent gradient on ≥3 visible elements
+- [ ] `::before` reflection on glass cards
+- [ ] AIOSON badge with hybrid accent
+
+Checklist (landing preview):
+- [ ] Full-page substrate background
+- [ ] Glass navigation bar
+- [ ] Hero section (not a generic centered CTA)
+- [ ] Atmospheric element (orb, gradient blob)
+- [ ] Proof rail + feature grid + pricing (3 tiers, featured card distinct)
+- [ ] Footer with glass treatment
+- [ ] AIOSON badge
+
+Pass: All items checked.
+Fail: Return to Phase 5 and complete the missing elements.
+
+---
+
+## Gate I — Metadata integrity
+
+**Question:** Does `.skill-meta.json` accurately describe the hybrid?
+
+Checklist:
+- [ ] `source` is `generated`
+- [ ] `generation_mode` is `project-local`
+- [ ] `parents.primary` contains exactly 2 skills
+- [ ] `parents.modifiers` contains at most 2 skills by default, or at most 3 only when advanced mode was explicitly enabled
+- [ ] `author.name` is filled when the user provided it
+- [ ] `generator.skill` is `design-hybrid-forge`
+- [ ] `generator.model` is recorded when the runtime exposed it
+- [ ] `variation_profile.modifier_policy` matches the generation mode when a preset was used
+
+Pass: The metadata is present and matches the generated skill.
+Fail: Return to Phase 4 and fix the metadata before distribution.
+
+---
+
+## Final ship checklist — project-local mode
+
+Before marking the project-local hybrid as done:
+
+- [ ] All 8 skill files written (SKILL.md + 7 references)
+- [ ] `.skill-meta.json` written
+- [ ] Both HTML previews written inside `previews/`
+- [ ] Variation overlay reflected in previews and metadata when one was selected
+- [ ] Active preset removed or archived from `.aioson/context/design-variation-preset.md` after successful generation
+- [ ] History snapshot preserved in `.aioson/context/history/design-variation-presets/`
+- [ ] `AGENTS.md` updated when it exists
+- [ ] Tool-native mirrors updated if the directories exist
+- [ ] All quality gates A through I passed
+
+When all are checked: the project-local hybrid is shipped.
+
+## Final ship checklist — core-promotion mode
+
+Only for explicit promotion back to AIOSON core:
+
+- [ ] Project-local checklist already passed
+- [ ] `.aioson/skills/design/{slug}/` prepared in the core repo
+- [ ] `docs/design-previews/index.html` updated with `✦ Hybrid` badge
+- [ ] `naming-registry.md` updated with the new hybrid entry
+- [ ] `pair-compatibility.md` updated (add pair to completed list)
+
+When all are checked: the hybrid is ready for PR / marketplace curation.