howone 0.1.29 → 0.1.31

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

@@ -1,143 +1,110 @@
 ---
 name: howone
-description: Operating manual for HowOne generated app architecture and runtime contracts. Use when a task touches app generation flow, backend/dynamic entity schema design, data access, SDK bindings, frontend code that uses HowOne data, auth, uploads, public/private access, AI capabilities/workflows, AI result persistence, realtime/status/event flows, or any @howone/sdk / howone.entities / howone.public / howone.ai calls. Load first, then read the smallest relevant numbered track: 01-architect, 02-database, 03-sdk, or 04-ai.
+description: HowOne generated app platform. Scope follows the user request. Load for architecture; add entity-schema, ai-capabilities, or app-sdk tracks only when those surfaces are needed.
 ---
 
-# HowOne App Architecture Skill
+# HowOne Skill
 
-This skill is the operating manual for generated HowOne apps. Use it before making platform
-decisions for backend data, frontend data access, auth, AI capabilities, SDK bindings, or generated
-app code that depends on HowOne runtime behavior.
+HowOne apps may be frontend-only, full-stack without AI, AI without custom backend, or full-stack
+with AI and persisted data. **Scope always follows the user's request.** This file is the index;
+processors defer here.
 
-Load the smallest set of numbered references that match the task, but do not skip this skill for
-backend schema design, frontend implementation, or AI features. The references define the contracts
-that app code must follow.
+## Mandatory flow
 
-## Active Tracks
+1. `skill(name="howone")`
+2. `skill_read "01-architect/01-app-generation.md"` — always, before any platform design write
+3. `skill_read` the smallest set from the track index below that architect routing selects
+4. Platform design tools → sync → `{appRoot}/src/lib/sdk.ts` / app code — only for surfaces in scope
 
-| Track | Folder | Use For |
+Inspect-only platform calls do not replace step 2 before the first design write.
+
+## Tracks
+
+| Track | When needed | Design vs implement |
 |---|---|---|
-| `01-architect/` | App generation + manifest flow | End-to-end HowOne app generation flow: when to design backend, when to sync manifests, when to update SDK bindings, and how to choose auth/data posture. |
-| `02-database/` | Backend schema + data access design | Entity schema contract, schema operations, access modes, owner/public data posture, indexes, query DSL, AI output persistence, versions, and guardrails. |
-| `03-sdk/` | Frontend SDK usage | `src/lib/sdk.ts`, auth, React provider, entity calls, public data, uploads, raw HTTP, AI action calls. |
-| `04-ai/` | AI capability + workflow design | HowOne AI capability contracts, service capability selection, workflow create/update/status, schema rules, playbooks, persistence boundaries, and SDK handoff. |
+| `01-architect/` | Always (scope, feasibility, posture, order) | Plan |
+| `02-entity-schema/` | User needs HowOne persisted data | Design contracts |
+| `03-ai-capabilities/` | User needs HowOne AI | Design contracts |
+| `04-app-sdk/` | User calls HowOne via SDK after sync | Implement |
 
-## Routing
+## Platform boundary (read architect for detail)
+
+HowOne platform work must map to **contract evidence**: database manifest, AI manifest, AI service
+catalog, platform tool schemas, or a documented `04-app-sdk/` reference.
+
+| Class | Meaning | Agent action |
+|---|---|---|
+| Platform in scope | Ask is expressible through the surfaces above | Use matching track + design tools |
+| App-owned | User's own ops stack, services, or infra (any technology) | Implement in `{appRoot}` app code/config; do not block |
+| Platform gap | User wants a **platform** feature with no contract evidence | Stop platform path; explain missing surface; Support Policy if needed |
+
+Do not treat unrelated user infrastructure (orchestration, custom servers, third-party products, etc.) as platform stop-loss. Do not model app-owned systems as fake HowOne entities or AI capabilities.
+
+## Track index (skill_read paths)
+
+Read only files required for the current request.
+
+### `01-architect/`
+
+| File | Use for |
+|---|---|
+| `01-app-generation.md` | Scope, platform vs app-owned, feasibility, data/auth posture, workflows, checklist |
+| `02-manifest-codegen.md` | Generate `src/lib/sdk.ts` from synced manifests |
+
+### `02-entity-schema/`
+
+| File | Use for |
+|---|---|
+| `01-schema-design.md` | Entity contract shape, fields, access, indexes |
+| `02-schema-operations.md` | Preview/apply schema patches, versions |
+| `03-data-access-patterns.md` | Public/private/own access, sharing |
+| `04-query-dsl-and-responses.md` | Filters, sort, pagination, response mapping |
+| `05-ai-persistence-patterns.md` | Storing AI results in entities |
+
+### `03-ai-capabilities/`
 
-Read references by task shape. Prefer exact references over generic examples.
-
-- New HowOne app or broad feature planning: read `01-architect/01-app-generation.md`.
-- Any feature touching backend data, frontend data access, or saved records: read the architect
-  flow first, then the relevant database and SDK references below.
-- Any feature touching AI generation, AI workflow behavior, or AI outputs: read the AI references
-  first, then the SDK handoff/action-call references.
-- AI capability, AI workflow generation/editing, or full-stack AI feature planning: read
-  `04-ai/01-ai-capability-architecture.md`, `04-ai/04-service-capability-catalog.md`, and
-  `04-ai/02-workflow-contract-rules.md`.
-- Backend database/schema creation or change: read `02-database/01-schema-design.md` and
-  `02-database/02-schema-operations.md`.
-- AI output persistence, generation history, retry/resume, or saved AI results: read the `04-ai/`
-  files first, then `02-database/05-ai-persistence-patterns.md` and
-  `02-database/01-schema-design.md`.
-- After schema sync, when app code must call the entity: read
-  `01-architect/02-manifest-codegen.md` and `03-sdk/02-entity-operations.md`.
-- Custom login page (your UI, HowOne APIs): `auth: 'custom'` in `createClient` (see `03-sdk/03-auth.md`),
-  `HowOneProvider auth="none"` and keep the default bottom-right HowOne logo unless explicitly hidden. Default without `auth` = hosted HowOne login.
-- `src/lib/sdk.ts`, `createClient`, env vars, or generated bindings: read
-  `03-sdk/01-client-setup.md` and `01-architect/02-manifest-codegen.md`.
-- Public landing pages or share URLs: read `02-database/03-data-access-patterns.md`,
-  `03-sdk/02-entity-operations.md`, and `01-architect/02-manifest-codegen.md`.
-- 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` 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`.
-
-## Reference Selection Protocol
-
-Before writing code, classify the touched surfaces:
-
-| Touched surface | Required references |
+| File | Use for |
 |---|---|
-| New app, feature architecture, or uncertain data posture | `01-architect/01-app-generation.md` |
-| Entity/schema/access/index change | `02-database/01-schema-design.md`, `02-database/02-schema-operations.md` |
-| Existing synced manifest to TypeScript bindings | `01-architect/02-manifest-codegen.md` |
-| UI reads/writes entities | `03-sdk/01-client-setup.md`, `03-sdk/02-entity-operations.md` |
-| Public read/share flow | `02-database/03-data-access-patterns.md`, `03-sdk/02-entity-operations.md` |
-| Query filters/sort/pagination/response mapping | `02-database/04-query-dsl-and-responses.md` |
-| AI output persistence / generation history | `02-database/05-ai-persistence-patterns.md`, `04-ai/01-ai-capability-architecture.md` |
-| Auth/session/login behavior | `03-sdk/03-auth.md`, `03-sdk/04-react-integration.md` |
-| 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`, `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` |
-
-If a task spans multiple surfaces, read one reference from each surface before editing. Do not
-invent API parameters, response shapes, owner fields, workflow IDs, or output paths from memory.
-
-## Core Workflow
-
-For app features that touch backend data:
-
-1. Decide the data posture in the architect track: private user data, authenticated shared data,
-   public list data, or public scoped share data.
-2. Design or update the entity contract in the database track.
-3. Use schema tools to preview/apply the same operations, then sync schema artifacts.
-4. Read `.howone/database/manifest.json`.
-5. Generate or update app SDK bindings from the manifest.
-6. Implement frontend calls using the SDK track.
-7. Validate with the app's typecheck/build.
-
-For app features that touch AI:
-
-1. Decide the AI feature boundary in the AI track: one workflow per feature, except RAG uses
-   indexing and query workflows.
-2. Design or update the AI capability contract with `ai-capability-design`.
-3. Preview/apply the same AI patch, then sync AI artifacts.
-4. Submit external workflow create/update with `external-ai-capability`.
-5. Preserve returned request IDs for the workflow status/background-task layer.
-6. Read `.howone/ai/manifest.json`.
-7. Generate or update app SDK bindings from the manifest.
-8. Implement frontend calls using `howone.ai.*`.
-9. If outputs are saved, map only durable product fields from the AI result into an entity schema,
-   then follow the database workflow.
-
-For frontend-only SDK work:
-
-1. Read existing `src/lib/sdk.ts`.
-2. Read only the SDK reference for the touched surface.
-3. Preserve existing generated bindings and import style.
-4. Validate.
-
-## Non-Negotiable Rules
-
-- Generate SDK bindings from synced manifests, not from memory.
-- Keep `.howone/` as manifest storage only; do not write generated source files there.
-- Configure `projectId` and `env` only in `createClient`. Auth APIs follow the same `env` (dev → `api.howone.dev`, not `api.howone.ai`).
-- Import `src/lib/sdk.ts` before any `@howone/sdk` auth call so environment is pinned.
-- Use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`; do not
-  hardcode project IDs or add fallback env values.
-- For private user-owned data, authenticated APIs derive owner from JWT. Do not pass
-  `created_by_id`, `created_by_user_id`, `createdById`, `ownerId`, or `puid`.
-- For `access.authenticated.read = "own"`, prefer `howone.entities.Entity.query.mine(...)`.
-- Public pages use `howone.public.entities.*` only when manifest access explicitly allows public
-  reads or writes.
-- Default `createClient({ projectId, env })` uses **HowOne hosted login**. For a custom `/login` UI
-  that still calls HowOne OTP/OAuth APIs, add `auth: 'custom'` and `HowOneProvider auth="none"`.
-- `HowOneProvider` may render the bottom-right HowOne `FloatingButton` logo by default. Do not remove
-  it unless the user explicitly asks for `brand="hidden"` or `showBrandButton={false}`.
-- Do not add SDK-owned toast APIs, redirect overlays, or app-specific UI. Expose data, state, events,
-  and callbacks; implement visible feedback in the generated frontend app.
-- SDK extensibility rule: default behavior must work without configuration, and custom behavior must
-  enter through typed adapters/callbacks instead of hardcoded app UI or provider-specific branches.
-- AI workflows are implementation, not persistence. Never put CRUD, auth, upload handling, or app
-  state management into the workflow capability contract.
-- For external workflow edits, pass `workflowConfigID` from a confirmed workflow status result; do
-  not invent it or omit it.
-- If the user explicitly requires AI behavior that the available workflow service cannot support,
-  stop that AI implementation path and report the unsupported requirement instead of faking,
-  silently omitting, or replacing the AI capability with static behavior.
+| `01-ai-capability-architecture.md` | Layers, boundaries, feature flow |
+| `02-workflow-contract-rules.md` | Input/output JSON schemas for capabilities |
+| `03-service-capability-catalog.md` | What the workflow service supports (feasibility) |
+| `04-workflow-operations.md` | External workflow create/update/status |
+| `05-ai-feature-playbooks.md` | Recurring product patterns |
+
+### `04-app-sdk/`
+
+| File | Use for |
+|---|---|
+| `01-client-setup.md` | `createClient`, env, provider |
+| `02-entity-operations.md` | `howone.entities` / public namespace |
+| `03-auth.md` | Login, session, custom auth |
+| `04-react-integration.md` | `HowOneProvider`, hooks |
+| `05-file-upload.md` | Uploads |
+| `06-raw-http.md` | Typed escape hatch |
+| `07-ai-action-calls.md` | `howone.ai.*` runtime calls |
+| `08-ai-manifest-handoff.md` | AI manifest → `src/lib/sdk.ts` |
+| `09-extension-boundaries.md` | Adapters, extension rules |
+| `10-workflow-execute-sse.md` | Documented workflow status/streaming wire format |
+
+## Routing
+
+All surface classification and minimum reads live in `01-architect/01-app-generation.md`. This
+skill index lists files; architect decides which apply.
+
+Mixed scope: read at least one file per touched track before writing.
+
+## Design order
+
+```text
+architect → (optional) entity-schema and/or ai-capabilities → sync → app-sdk → UI
+```
+
+Skip tracks the user did not require.
+
+## Rules
+
+- When platform contracts apply: synced `{appRoot}/.howone/database/manifest.json` and/or
+  `{appRoot}/.howone/ai/manifest.json` plus tool results are source of truth.
+- `.howone/` holds manifests only—not generated app source.
+- Do not invent platform schemas, APIs, or identifiers absent from contracts/catalog/tools.
+- Platform stop-loss: architect. User-owned external systems: integrate in app code.

package/templates/vite/.howone/skills/howone/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "HowOne App Architecture"
-  short_description: "Design HowOne database schemas, AI workflows, SDK bindings, auth, and app integration."
-  default_prompt: "Use this skill to choose the right HowOne architecture track, then implement database schema, AI capability/workflow, SDK bindings, auth, or frontend SDK calls from synced manifests."
+  display_name: "HowOne"
+  short_description: "Generated app platform: scope-first architecture, optional entity schema, AI capabilities, and SDK integration from synced contracts."
+  default_prompt: "Load howone, read 01-architect/01-app-generation.md, then the smallest track files from SKILL.md for this request. Scope follows the user—not every app needs AI or backend."

package/templates/vite/AGENTS.md

@@ -69,8 +69,8 @@ Prefer failure-driven inspection over speculative context loading.
 ## HowOne Runtime and Auth
 
 - Use synced HowOne manifests plus `src/lib/sdk.ts` as the source of truth for generated entity and AI bindings.
-- Use the `howone-sdk` skill for HowOne app architecture, backend database schema design, manifest-to-SDK binding, and app-side SDK code.
-- Inside `howone-sdk`, read the smallest relevant numbered track: `01-architect/` for app flow, `02-database/` for schema/access/data design, and `03-sdk/` for frontend SDK/auth/entity calls.
+- Use the `howone` skill: `skill(howone)` → `SKILL.md` → `01-architect/01-app-generation.md` → smallest track reads from the skill index. Scope follows the user request.
+- Tracks: `01-architect/`, `02-entity-schema/`, `03-ai-capabilities/`, `04-app-sdk/` — include only what the user needs.
 - Choose auth posture from the schema access contract, not from guesswork:
   - authenticated/private app data uses `howone.entities.*`; the backend derives ownership from the JWT
   - public pages use `howone.public.entities.*` only when the manifest explicitly allows public access

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.