howone 0.1.28 → 0.1.30

package/templates/vite/.howone/skills/howone/03-sdk/07-ai-action-calls.md

@@ -62,27 +62,14 @@ type AiActionConfig<TInput, TOutput> = {
 ```ts
 type AiResult = {
   success: boolean
+  runId?: string
   /** Terminal outcome of the run */
   outcome: 'success' | 'credit_insufficient' | 'run_error' | null
-  finalResult: Record<string, unknown> | null  // the workflow output payload (from run_complete)
-  /** Accumulated state data from state_update / state_snapshot events */
-  stateData: Record<string, unknown>
-  nodeExecutions: Array<{
-    nodeName: string
-    agentName?: string
-    timestamp: number
-  }>
-  toolExecutions: Array<{
-    toolCallId: string
-    toolName: string
-    args?: Record<string, unknown>
-    result?: unknown
-    durationMs?: number
-    cost?: number
-    timestamp: number
-  }>
+  finalResult: Record<string, unknown> | null  // run_complete.message
+  progressLogs: string[]                       // progress.message lines
   totalDuration: number
   errors: string[]
+  events: AiEvent[]
 }
 ```
 
@@ -98,42 +85,20 @@ type AiSession = {
 
 ### AiEvent (SSE events)
 
-All events share a common base, then carry a typed `payload`:
+All workflow execute SSE events use the current envelope shape:
 
 ```ts
 type AiEvent = {
-  type: string          // see channel catalog below
   id: string
-  run_id: string
-  workflow_id: string
-  timestamp: string     // ISO 8601 UTC
-  seq: number           // monotonic ordering within the run
-  // Context fields — present when applicable
-  node_name?: string
-  node_status?: 'pending' | 'running' | 'completed' | 'failed'
-  action_step?: number
-  agent_name?: string
-  action_name?: string
-  agent_loop_step?: number
-  message_id?: string
-  tool_call_id?: string
-  payload?: Record<string, unknown>
+  type: 'run_start' | 'progress' | 'run_complete' | 'run_error' | 'credit_insufficient'
+  event: AiEvent['type']
+  message: string | Record<string, unknown>
+  payload?: Record<string, unknown> // present for run_complete as a compatibility alias of message
 }
 ```
 
-**SSE Channels and event types:**
-
-| Channel | Key event types |
-|---|---|
-| `lifecycle` | `run_start`, `run_complete`, `credit_insufficient`, `run_error` |
-| `node` | `node_scheduled`, `node_start`, `node_complete`, `node_failed` |
-| `action` | `action_scheduled`, `action_start`, `action_complete` |
-| `messages` | `ai_message_start`, `ai_message_chunk`, `ai_message_end`, `action_output` |
-| `tools` | `tool_call_start`, `tool_call_end`, `tool_call_error` |
-| `state` | `state_update`, `state_snapshot` |
-| `metadata` | `progress` |
-
 Stream terminates after exactly one of: `run_complete`, `credit_insufficient`, or `run_error`.
+For the full wire protocol, read `03-sdk/09-workflow-execute-sse.md`.
 
 ---
 
@@ -230,17 +195,12 @@ When an action omits `outputSchema`, `run()` returns the raw `AiResult` executio
 
 ```ts
 const result = await howone.ai.generateStory.run(input, {
-  onMessageChunk: (text) => {
-    console.log('chunk:', text)
-  },
-  onNodeStart: (event) => {
-    console.log(`Node ${event.node_name} started`)
-  },
-  onStateUpdate: (delta) => {
-    console.log('State delta:', delta)
+  onMessageChunk: (line) => {
+    appendLog(line)
   },
-  onProgress: (percent) => {
-    setProgress(percent)
+  onProgress: (percent, line) => {
+    if (line?.startsWith('[DISPLAY]')) setStatus(line.replace('[DISPLAY]', '').trim())
+    if (percent === 100) setProgress(100)
   },
   onError: (error) => {
     console.error('SSE error:', error)
@@ -302,27 +262,20 @@ const result = await session.result
 async function consumeEvents(input: GenerateStoryInput) {
   for await (const event of howone.ai.generateStory.events(input)) {
     switch (event.type) {
-      case 'ai_message_chunk':
-        // streaming LLM text delta
-        setOutput(prev => prev + (event.payload?.content_block?.text ?? event.payload?.content ?? ''))
+      case 'run_start':
+        setStatus('running')
         break
-      case 'node_start':
-        console.log('Node started:', event.node_name)
-        break
-      case 'tool_call_end':
-        console.log('Tool result:', event.tool_call_id, event.payload?.result)
-        break
-      case 'state_update':
-        console.log('State delta:', event.payload?.delta)
+      case 'progress':
+        appendLog(String(event.message))
         break
       case 'run_complete':
-        console.log('Final result:', event.payload?.result)
+        console.log('Final result:', event.message)
         break
       case 'credit_insufficient':
-        showCreditError(event.payload?.details?.reason)
+        showCreditError(String(event.message))
         break
       case 'run_error':
-        showExecutionError(event.payload?.details?.reason)
+        showExecutionError(String(event.message))
         break
     }
   }
@@ -397,7 +350,7 @@ export const analyzeDataInputSchema = z.object({
 
 ```ts
 type SSEExecutionOptions = {
-  // Called for every parsed event with its SSE channel
+  // Called for every parsed workflow envelope. channel is always "workflow".
   onEvent?: (event: AiEvent, channel: string) => void
 
   // Lifecycle
@@ -408,23 +361,10 @@ type SSEExecutionOptions = {
   /** Workflow logic failed — show retry/support UI */
   onRunError?: (event: RunErrorEvent) => void
 
-  // Nodes
-  onNodeStart?: (event: NodeStartEvent) => void
-  onNodeComplete?: (event: NodeCompleteEvent) => void
-
-  // Messages — streaming LLM text
-  onMessageChunk?: (text: string, event: AiMessageChunkEvent) => void
-  onMessageEnd?: (event: AiMessageEndEvent) => void
-
-  // Tools
-  onToolCallStart?: (event: ToolCallStartEvent) => void
-  onToolCallEnd?: (event: ToolCallEndEvent) => void
-  onToolCallError?: (event: ToolCallErrorEvent) => void
-
-  // State — live output panel updates
-  onStateUpdate?: (delta: Record<string, unknown>, event: StateUpdateEvent) => void
+  // Progress log lines from progress.message
+  onMessageChunk?: (text: string, event: ProgressEvent) => void
 
-  // Progress percent 0-100
+  // Progress compatibility callback: progress lines fire as (0, message), success fires as (100)
   onProgress?: (percent: number, message?: string) => void
 
   // Internal transport log
@@ -448,6 +388,8 @@ type SSEExecutionOptions = {
 }
 ```
 
+> The current workflow execute SSE endpoint does not emit `node_start`, `tool_call_end`,
+> `state_update`, or `ai_message_chunk`. Do not write generated app code that expects those events.
 > `onCreditInsufficient` and `onRunError` are **mutually exclusive** terminal events.
 > Do not use a generic `onError` to distinguish them — use the dedicated callbacks.
 

package/templates/vite/.howone/skills/howone/03-sdk/09-workflow-execute-sse.md

@@ -0,0 +1,105 @@
+# Workflow Execute SSE
+
+Use this reference for `@howone/sdk` AI action streaming and raw workflow execution calls.
+
+## Endpoint Contract
+
+The SDK uses the current workflow execute SSE endpoint:
+
+| Method | Path |
+|---|---|
+| `POST` | `/workflow/execute/{project_short_id}/{config_id}` |
+
+The request body is:
+
+```json
+{
+  "inputs": {},
+  "priority": "normal"
+}
+```
+
+`priority` is optional. All requests require `Authorization: Bearer <JWT>`.
+
+The successful HTTP response includes:
+
+| Header | Meaning |
+|---|---|
+| `Content-Type: text/event-stream` | Streaming response |
+| `X-Run-Id` | Execution task id for status/cancel follow-up |
+
+Do not use or generate code for old endpoints such as
+`/workflow/{appId}/{workflowId}/execute_sse`.
+
+## Wire Format
+
+Frames contain only a `data:` line and a blank line:
+
+```text
+data: {"id":"evt_8ae6d6e8a4ea","event":"run_start","message":"execution with sse is started"}
+
+data: {"id":"evt_241ff985450b","event":"progress","message":"[DISPLAY] Executing node: Extract"}
+
+data: {"id":"evt_f3a1b2c3d4e5","event":"run_complete","message":{"video_url":"https://..."}}
+```
+
+There are no separate SSE `event:` or `id:` lines. The JSON envelope owns those fields.
+
+## Envelope
+
+```ts
+type WorkflowSseEnvelope = {
+  id: string
+  event: 'run_start' | 'progress' | 'run_complete' | 'run_error' | 'credit_insufficient'
+  message: string | Record<string, unknown>
+}
+```
+
+Event meanings:
+
+| Event | Message | Meaning |
+|---|---|---|
+| `run_start` | string | Stream opened and execution started. |
+| `progress` | string | One worker log line. `[DISPLAY]` lines are intended for UI. |
+| `run_complete` | object | Final workflow-specific output. SDK maps this to `AiResult.finalResult`. |
+| `run_error` | string | Workflow failed. |
+| `credit_insufficient` | string | Billing/credit block. |
+
+The terminal event is exactly one of `run_complete`, `run_error`, or `credit_insufficient`.
+There is no `stream_end` event.
+
+## SDK Mapping
+
+`howone.ai.run(configId, inputs)` and typed action `.run()` call the endpoint above.
+
+`AiResult` maps the stream as:
+
+```ts
+type AiResult = {
+  success: boolean
+  runId?: string
+  outcome: 'success' | 'credit_insufficient' | 'run_error' | null
+  finalResult: Record<string, unknown> | null
+  progressLogs: string[]
+  errors: string[]
+  events: AiEvent[]
+}
+```
+
+For typed actions with an `outputSchema`, `.run()` returns the validated `run_complete.message`
+object directly.
+
+## Callback Rules
+
+- `onRunStart(event)` receives the `run_start` envelope.
+- `onMessageChunk(text, event)` receives each `progress.message` line.
+- `onProgress(0, message)` receives each progress line; `onProgress(100)` fires on success.
+- `onRunComplete(event, result)` receives `event.message` as the final object.
+- `onRunError(event)` receives `event.message` as the error string.
+- `onCreditInsufficient(event)` receives `event.message` as the credit error string.
+- `onEvent(event, 'workflow')` fires for every parsed envelope.
+
+Do not write UI code that expects `event.payload.result`, `event.payload.details.reason`,
+`node_start`, `tool_call_end`, `state_update`, or `ai_message_chunk`. Those belong to an old
+multi-channel protocol and are not part of the current workflow execute SSE contract.
+

package/templates/vite/.howone/skills/howone/04-ai/03-ai-sdk-handoff.md

@@ -6,6 +6,9 @@ workflow through `@howone/sdk`.
 This file answers: **how does `.howone/ai/manifest.json` become `src/lib/sdk.ts`, and how should UI
 call it?**
 
+For live stream wire details, read `03-sdk/09-workflow-execute-sse.md`. The current endpoint emits
+only `run_start`, `progress`, `run_complete`, `run_error`, and `credit_insufficient`.
+
 ## Binding Source
 
 Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory,
@@ -117,11 +120,13 @@ Use `.stream()` when UI needs live output or cancellation:
 
 ```ts
 const session = howone.ai.generateStory.stream(input, {
-  onMessageChunk: (text) => setDraft((prev) => prev + text),
-  onStateUpdate: (delta) => updateLivePanel(delta),
-  onProgress: (percent) => setProgress(percent),
-  onCreditInsufficient: (event) => showCreditError(event.payload?.details?.reason),
-  onRunError: (event) => showExecutionError(event.payload?.details?.reason),
+  onMessageChunk: (line) => appendLog(line),
+  onProgress: (percent, line) => {
+    if (line?.startsWith('[DISPLAY]')) setStatus(line.replace('[DISPLAY]', '').trim())
+    if (percent === 100) setProgress(100)
+  },
+  onCreditInsufficient: (event) => showCreditError(event.message),
+  onRunError: (event) => showExecutionError(event.message),
   onError: (error) => setError(error.message),
   onComplete: (result) => setRawResult(result),
 })
@@ -134,20 +139,17 @@ Use `.events()` when code wants an async iterable:
 
 ```ts
 for await (const event of howone.ai.generateStory.events(input)) {
-  if (event.type === 'ai_message_chunk') {
-    appendText(String(event.payload?.content_block?.text ?? event.payload?.content ?? ''))
-  }
-  if (event.type === 'state_update') {
-    updateLivePanel(event.payload?.delta ?? {})
+  if (event.type === 'progress') {
+    appendLog(String(event.message))
   }
   if (event.type === 'run_complete') {
-    setFinalResult(event.payload?.result)
+    setFinalResult(event.message)
   }
   if (event.type === 'credit_insufficient') {
-    showCreditError(event.payload?.details?.reason)
+    showCreditError(String(event.message))
   }
   if (event.type === 'run_error') {
-    showExecutionError(event.payload?.details?.reason)
+    showExecutionError(String(event.message))
   }
 }
 ```

package/templates/vite/.howone/skills/howone/SKILL.md

@@ -50,7 +50,7 @@ Read references by task shape. Prefer exact references over generic examples.
 - File upload: read `03-sdk/05-file-upload.md`.
 - Raw HTTP escape hatch: read `03-sdk/06-raw-http.md`.
 - App-side AI action calls after `.howone/ai/manifest.json` exists: read
-  `03-sdk/07-ai-action-calls.md`.
+  `03-sdk/07-ai-action-calls.md` and `03-sdk/09-workflow-execute-sse.md`.
 - External workflow create/update/status: read `04-ai/05-workflow-operations.md`.
 - Common AI feature templates: read `04-ai/06-ai-feature-playbooks.md`.
 
@@ -71,7 +71,7 @@ Before writing code, classify the touched surfaces:
 | AI capability or workflow design | `04-ai/01-ai-capability-architecture.md`, `04-ai/04-service-capability-catalog.md`, `04-ai/02-workflow-contract-rules.md` |
 | External workflow create/update/status | `04-ai/05-workflow-operations.md` |
 | Common AI feature examples | `04-ai/06-ai-feature-playbooks.md` |
-| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md` |
+| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md`, `03-sdk/09-workflow-execute-sse.md` |
 | File upload | `03-sdk/05-file-upload.md` |
 | Raw HTTP escape hatch | `03-sdk/06-raw-http.md` |
 | SDK extensibility / adapter boundaries | `03-sdk/08-extension-boundaries.md` |

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.20",
+    "@howone/sdk": "2.0.0-beta.21",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/.howone/skills/hallmark/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Hallmark contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/templates/vite/.howone/skills/hallmark/README.md

@@ -1,147 +0,0 @@
-# Hallmark
-
-**A design skill for Claude Code, Cursor, and Codex that refuses to look AI-generated.**
-
-[Live demo →](https://www.usehallmark.com)  ·  twenty-two themes  ·  four verbs  ·  press `T` to cycle.
-
-Made by Together AI.
-
-<p align="center">
-  <img src="site/OG-hallmark.png" alt="Hallmark — A design skill that refuses to look AI-generated" />
-</p>
-
-Hallmark encodes the anti-AI-slop consensus — typography, colour, layout, motion, microinteractions, structural variety — into one opinionated rule-set. It picks a macrostructure for the brief, dresses it in one of twenty-two themes, runs sixty-five slop-test gates plus a pre-emit self-critique before handing back, and refuses the on-distribution defaults every LLM was trained into.
-
-> **v1.0.0** — pre-emit critique on six axes, honest-copy enforcement, locked-token discipline, re-drawn-chrome ban, and a no-wrap rule for clickable text. Five new slop-test gates (56–60). The full rule-set lives in [`SKILL.md`](SKILL.md) and [`references/`](references/).
-
-
----
-
-## What's distinct — quick map vs the field
-
-|  | Hallmark | [frontend-design](https://github.com/anthropics/skills) (Anthropic) | [Open Design](https://github.com/nexu-io/open-design) | [Dembrandt](https://github.com/dembrandt/dembrandt) |
-| --- | --- | --- | --- | --- |
-| **Source of taste** | extracts DNA from a screenshot OR a URL (`study` verb) — image mode names roles + candidates; URL mode names exact fonts + tokens | art-director brief + ban list | menu of 72 brand presets (Linear, Stripe, Vercel, Notion…) | scrapes a live URL, emits computed tokens |
-| **Output unit** | macrostructure + theme + custom-craft, optional portable `design.md` | bans + brief framing | preset application | DTCG `tokens.json` |
-| **Refuses font ID** | image mode: yes — names role only; URL mode: names what the page declares | n/a | n/a | n/a (computes from CSS) |
-| **Refuses pixel-clone** | yes — DNA only, never pixels (both modes) | n/a | n/a | n/a (full token export) |
-| **Refuses third-party extraction** | yes — paid templates / competitors / unrelated sites auto-refused; `design.md` emission has a tighter layer with URL-mode attestation | n/a | n/a | n/a (extracts anything) |
-| **Tactile-rebellion alignment** | warm-paper, custom-craft, slopless canon | strong | medium | none — token-only |
-| **Pages by archetype** | 21 named macrostructures, picked per brief | by brief | 5 deterministic directions | n/a |
-| **Verbs** | 4 (default · `audit` · `redesign` · `study`) | 1 | 31 | 1 (CLI) |
-
-Hallmark's edge is **`study`** — every other tool ships a preset menu or a scraper. Hallmark is the only one that takes a screenshot *or* a URL of a design you admire, names what it sees (roles in image mode, exact fonts + tokens in URL mode), refuses paid-template-marketplace listings outright, and either rebuilds your content with the extracted DNA or emits a portable `design.md` you can hand to another AI tool — with a tighter refusal layer for the portable spec than for the diagnosis itself. Three worked study examples in [`docs/study-examples.md`](docs/study-examples.md).
-
----
-
-## Four verbs
-
-| Verb | What it does |
-| --- | --- |
-| *(default)* | Build new UI. Asks for audience + use + tone (skippable — the skill states what it inferred). Picks a macrostructure, applies the rule-set, runs the slop test before handing back. |
-| `hallmark audit <target>` | Score existing code against the named anti-patterns + structural sameness. Punch list, no edits. |
-| `hallmark redesign <target> [--mood <name>]` | Throw out the structure, keep copy + IA + brand, rebuild with a deliberately different fingerprint. |
-| **`hallmark study <screenshot \| URL>`** | The differentiator. Extract the **DNA** from a design the user admires — macrostructure, archetypes, type-pairing, colour anchor — and produce a diagnosis report. Accepts either an attached screenshot or a URL to a live page. After the diagnosis the user can optionally rebuild *their* content using the extracted DNA, **or** lock the DNA into a portable `design.md` other AI tools (Cursor, v0, Bolt) can read directly. **URL mode** reads HTML / CSS via WebFetch — names exact fonts and exact colour values, can't judge rhythm, and falls back to asking for a screenshot if the page is auth-walled or a JS-only shell. **Refuses paid templates and competitor pages. Image mode names font roles (never font IDs); URL mode names actual fonts (the page declares them). Never copies pixels. `design.md` emission has a tighter refusal layer than the diagnosis itself — URL-mode emission asks the user to attest the source is theirs or a public reference for their own brand.** |
-
----
-
-## Different briefs, different shapes
-
-A handful of examples below — each generated by exercising the skill on a different brief. The skill picks differently for every prompt; no two share a macrostructure or theme.
-
-<table>
-  <tr>
-    <td width="25%"><a href="https://www.usehallmark.com/examples/tally/"><img src="docs/screenshots/hero-tally.jpg" alt="Tally — SaaS product page hero" /></a></td>
-    <td width="25%"><a href="https://www.usehallmark.com/examples/wayfare/"><img src="docs/screenshots/hero-wayfare.jpg" alt="Wayfare travel booking hero" /></a></td>
-    <td width="25%"><a href="https://www.usehallmark.com/_tests/09-slow-pour/"><img src="docs/screenshots/hero-slow-pour.jpg" alt="Slow Pour coffee subscription hero" /></a></td>
-    <td width="25%"><a href="https://www.usehallmark.com/examples/bananastudio/"><img src="docs/screenshots/hero-bananastudio.jpg" alt="BananaStudio creative studio hero" /></a></td>
-  </tr>
-  <tr>
-    <td><b>Tally</b><br/><sub>SaaS product page · modern-minimal</sub></td>
-    <td><b>Wayfare</b><br/><sub>Travel booking · atmospheric</sub></td>
-    <td><b>Slow Pour</b><br/><sub>Small-batch coffee subscription</sub></td>
-    <td><b>BananaStudio</b><br/><sub>Creative studio · playful motion</sub></td>
-  </tr>
-  <tr>
-    <td><a href="https://www.usehallmark.com/_tests/06-anya-portfolio/"><img src="docs/screenshots/hero-anya.jpg" alt="Anya Reis personal site hero" /></a></td>
-    <td><a href="https://www.usehallmark.com/examples/najm/"><img src="docs/screenshots/hero-najm.jpg" alt="NAJM Moroccan fashion brand hero" /></a></td>
-    <td><a href="https://www.usehallmark.com/_tests/11-soroe-ceramics/"><img src="docs/screenshots/hero-soroe.jpg" alt="Søroe ceramics studio hero" /></a></td>
-    <td><a href="https://www.usehallmark.com/examples/hyperlane/"><img src="docs/screenshots/hero-hyperlane.jpg" alt="Hyperlane developer infrastructure hero" /></a></td>
-  </tr>
-  <tr>
-    <td><b>Anya Reis</b><br/><sub>Software architect personal site</sub></td>
-    <td><b>NAJM</b><br/><sub>Moroccan fashion brand</sub></td>
-    <td><b>Søroe</b><br/><sub>Small ceramics studio</sub></td>
-    <td><b>Hyperlane</b><br/><sub>Developer infrastructure</sub></td>
-  </tr>
-</table>
-
-Each page is its own self-contained HTML + CSS — no shared theme, no shared layout. Every one carries a `/* Hallmark · macrostructure: … */` stamp at the top of its CSS. See the full set under [`site/_tests/`](site/_tests/) or live at [www.usehallmark.com](https://www.usehallmark.com).
-
----
-
-## What's inside
-
-- **[`SKILL.md`](SKILL.md)** — the routing file. Six-step design flow (including `Step 2.5 · Check project memory` reading `.hallmark/log.json`), 65-gate slop test, output contract, always-on `tokens.css` export.
-- **[`references/`](references/)** — short, opinionated rule files: typography, colour, layout, motion, microinteractions, interaction-and-states (with the input-state checklist), responsive, copy, anti-patterns, the 21 named macrostructures, the **40 component archetypes** with variation knobs (9 hero · 6 feature · 4 CTA · 4 testimonial · **8 footer · 9 nav**), the **4 hero polish patterns** (in `hero-enrichment.md`), the 6 primitive structure axes, the vision-extraction protocol for `study`, hero enrichment, custom-craft (CSS art over Lottie), assets, the slop-test gates, four genre rule-overlays (each with nav + footer voice routing), per-verb dispatchers, and the export-formats reference (Tailwind / DTCG / shadcn / tokens.css).
-- **[`docs/`](docs/)** — human-reading content: **[`recipes.md`](docs/recipes.md)** (8 worked briefs + a canonical try-it prompt) and **[`study-examples.md`](docs/study-examples.md)** (3 worked DNA-extractions). Not auto-loaded by the skill.
-- **[`site/`](site/)** — a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. **Twenty-two themes** clustered into four genres: **editorial** (Specimen, Editorial, Atelier, Newsprint, Salon, Linen, Almanac, Garden, Studio, Sport, Riso, Brutal, Manifesto), **modern-minimal** (Quiet, Coral, Violet), **atmospheric** (Midnight, Terminal, Bloom, Aurora, Halo), **playful** (Plume). Switching themes literally rebuilds the page — different hero archetype, different footer archetype, different nav archetype.
-
----
-
-## What's distinct (the long list)
-
-- **One skill, four verbs.** Not eighteen commands.
-- **Genres broaden the range.** Hallmark routes a brief through one of four genres before picking a theme: **editorial** (default · the canonical anti-slop voice), **modern-minimal** (Stripe / Linear / ElevenLabs school), **atmospheric** (Suno / Runway / dark-AI-tool school), **playful** (post-Linear soft school). Each genre is its own rule overlay — atmospheric allows radial blooms; modern-minimal allows pure white and pill CTAs; editorial bans both. Detection is signal-based, silent default to editorial.
-- **Tone is a first-class decision.** "Clean and modern" is rejected. Pick an extreme — *editorial · brutalist · soft · technical · luxury · playful · austere*.
-- **Macrostructures over axes.** Pick one of 21 named whole-page shapes wholesale; the macrostructure stamp lives in the CSS comment, so the next Hallmark run picks something different.
-- **Within-archetype variation.** Two Bento Grids should not be twins; each archetype has 2–3 picked-per-output knobs.
-- **Microinteractions as discipline.** Silent success over celebratory toasts. Optimistic update + Undo over confirm dialogs. Hover delay 800 ms, focus delay 0 ms.
-- **A 65-gate slop test** runs before every output. One yes fails the build. Recent additions: typography discipline gates (39–40: max three font families per page, outlier face used in ≤ 2 slots), input-state gates (41–45: no border-width layout shift, focus ring via outline not border, input height matches button height, helper-text slot reserves height, disabled state needs three independent signals), contrast gates (46–50: APCA / WCAG thresholds, accent-ink token requirement, dark-section ink-on-ink check), **nav · footer · hero structural gates (51–55: AI nav fingerprint, AI footer fingerprint, hero centred-everything, hero padding asymmetry, decorative-without-purpose)**, **honest-copy + chrome + token + responsive gates (56–60: invented metrics, re-drawn UI chrome, mid-render token improvisation, two-line clickable text, emoji-as-feature-icon)**, and **layout-safety gates (61–65: 1fr image-track overflow, missing `overflow-x: clip`, display-header word-break, theme section-head mobile collapse, CSS-only radio tabs scroll-jumping)**.
-- **Project memory.** A per-project `.hallmark/log.json` records each run's macrostructure + theme + enrichment + brief summary. The skill reads the last 3–5 entries before picking and writes a new entry after each build, so consecutive Hallmark outputs in the same project don't repeat shapes or themes.
-- **Theme-diversification rule.** Two consecutive themes must differ on at least one of three axes: paper band (dark / mid / light), display style (italic-serif / roman-serif / geometric-sans / mono / display-heavy / system-native), accent hue (warm / cool / neutral / chromatic-other).
-- **Voice fixtures over LLM defaults.** Each of the 21 macrostructures ships with 2–3 example opening lines tuned to its tone. "Built for the modern team" is in the banned-phrases list.
-- **Hero enrichment is opt-in.** A typographic-only hero is always acceptable. When enrichment is right, the skill picks from a six-tier hierarchy: typography only → custom-built CSS art → hand-built SVG → generated illustration (Nanobanana / Recraft) → library → Lottie (last resort).
-- **Microinteractions default-on for SaaS-shaped archetypes.** Bento Grid, Stat-Led, Workbench, Marquee Hero pages ship with 2–3 purposeful microinteractions (number reveal, pricing lift, marquee, stagger) without the user having to ask. Editorial / Manifesto / Letter / Quote-Led pages stay still.
-- **SaaS page sequence.** Hero → social proof → features → testimonials → pricing → FAQ → CTA → footer. Real prices, not "contact sales for pricing." Specific testimonials with role + company.
-- **Wordmark may use a different display face.** A Geist-bodied SaaS page can set its wordmark in Fraunces. Same-family collapse on Bento / Stat-Led / Workbench / Marquee Hero is the new "un-branded" tell.
-- **`study` extracts DNA, not pixels.** Refusal heuristics, type-role vocabulary (no font ID guessing in image mode), confirmation step before any code. Accepts a screenshot *or* a URL — URL mode reads HTML / CSS via WebFetch and names exact fonts + exact tokens (trades the rhythm pass for accuracy on everything else), with a graceful screenshot fallback when the URL is auth-walled or a JS-only shell. Three worked examples in [`docs/study-examples.md`](docs/study-examples.md).
-- **Opt-in `design.md` lock-the-system flow — two entry points.** Iterate freely on the first builds; when the system is settled, say *"lock the system"* (or *"give me a design.md"*) and Hallmark extracts the build's tokens + voice into a portable design system at the project root. **Or**, after a `study` diagnosis, say *"lock the DNA"* and Hallmark emits the same `design.md` format seeded from the studied source — URL mode populates exact tokens + fonts; image mode populates estimated bands + candidate fonts. From that point on every Hallmark run defers to the file, the diversification rule inverts to consistency, and the file becomes the single source of truth for scaling the design across a real app. The study-mode emission carries a tighter refusal layer than the diagnosis itself — third-party URLs require user attestation (your own site / public reference for your own brand), competitors and paid templates are auto-refused. Phrase-triggered from either entry point, never auto-emitted. See [`references/design-md.md`](references/design-md.md).
-
----
-
-## Install
-
-```
-npx skills add nutlope/hallmark
-```
-
-Or copy [`SKILL.md`](SKILL.md) + [`references/`](references/) into one of:
-
-- **Claude Code** — `~/.claude/skills/hallmark/`
-- **Cursor** — `.cursor/rules/hallmark.mdc` (body of `SKILL.md`, no frontmatter)
-- **Codex** — `~/.codex/skills/hallmark/` (personal, all projects) or `.codex/skills/hallmark/` (project-scoped, commit to repo)
-
-## Updating
-
-```
-npx skills add nutlope/hallmark
-```
-
-Re-run any time to pull the latest. If the CLI complains the skill already exists, delete the install path first (`~/.claude/skills/hallmark/` on Claude Code, or `.agents/skills/hallmark/` if you ran `skills add` from a project directory) and re-run.
-
-To preview the landing page locally:
-
-```
-cd site && python3 -m http.server 4173    # → http://localhost:4173
-```
-
-Press `T` to cycle themes, the **shuffle button** (or `R`) to randomise, `?theme=studio` for a shareable link.
-
-Or visit the live deploy at **[www.usehallmark.com](https://www.usehallmark.com)**.
-
----
-
-## Licence
-
-MIT. Use it, fork it, ship it.