howone 0.1.20 → 0.1.23

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

@@ -0,0 +1,80 @@
+# AI SDK Handoff
+
+Use this reference after AI capability artifacts have been synced and app code needs to call the
+workflow.
+
+## Binding Source
+
+Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory or
+from the original user prompt.
+
+For each manifest capability:
+
+1. Read `name`.
+2. Read `workflowId`.
+3. Read `inputSchema`.
+4. Read `outputSchema`.
+5. Generate zod input and output schemas from the JSON Schema fields.
+6. Bind with `defineAiAction(name, { workflowId, inputSchema, outputSchema })`.
+
+`workflowId` is mandatory. Without it, the SDK falls back to the action name as the execution URL
+segment, which is not a workflow UUID.
+
+## Output Handling
+
+For a typed action with `outputSchema`, `.run()` returns the validated workflow output payload.
+The SDK unwraps the EAX execution envelope and validates `finalResult` internally.
+
+Use this pattern:
+
+```ts
+const output = await howone.ai.generateSummary.run(input)
+// output is GenerateSummaryOutput when outputSchema is configured.
+```
+
+Do not read `raw.finalResult`, `raw.result`, or `raw.data.result` from a typed action result. Those
+paths are execution/SSE internals. App code should use the value returned by `.run()` directly.
+
+Do not make every output field `.optional()` or add `.passthrough()` to hide validation errors.
+Required fields in the manifest must stay required in Zod. If validation fails, inspect
+`AiSchemaValidationError.issues` and fix the capability contract or workflow output mapping.
+
+## UI State
+
+AI calls should run in event handlers, effects, or explicit async actions. Never call
+`howone.ai.*.run()` inside JSX render.
+
+Recommended UI states:
+
+- idle
+- running
+- succeeded
+- failed
+- cancelled when using streaming
+
+For streaming, keep the `AiSession` in a ref and call `cancel()` from the UI.
+
+## Persistence Handoff
+
+If the app stores generated output:
+
+1. Run the AI workflow.
+2. Use the typed output returned by `.run()`.
+3. Write the resulting data through `howone.entities.*`.
+
+Do not ask the workflow to write to the database. Do not pass owner fields for authenticated
+user-owned entities; HowOne derives ownership from the JWT.
+
+## Workflow Edit Handoff
+
+When editing an external workflow implementation later, use `external-ai-capability` with:
+
+- `mode: "update"`
+- `capabilityName`
+- `workflowConfigID`
+- `updatePrompt`
+
+`workflowConfigID` is not `workflowId`. It comes from a confirmed workflow status result:
+`payload.workflow_details.new_workflow_config_id`.
+
+If the schema changed, update and sync the capability contract before submitting the workflow edit.

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

@@ -1,101 +1,126 @@
 ---
 name: howone-sdk
-description: Build application code with @howone/sdk correctly. Use when implementing or reviewing HowOne app SDK wiring, src/lib/sdk.ts, dynamic entity bindings, AI action bindings, zod runtime schemas, Vite environment variables, calls like howone.entities.* and howone.ai.*.run, file uploads, auth flows, raw HTTP calls, or code generated from .howone/database and .howone/ai manifests.
+description: Required operating manual for HowOne generated apps. Use for backend schema/API design, frontend UI implementation that reads or writes HowOne data, AI capability/workflow design, SDK binding/codegen from .howone manifests, auth, uploads, public/private access, and any code that calls @howone/sdk, howone.entities.*, howone.public.entities.*, or howone.ai.*.
 ---
 
-# HowOne SDK Skill
+# HowOne App Architecture Skill
 
-This skill is the authoritative source of truth for all `@howone/sdk` usage in generated apps. Every capability is documented in a dedicated reference file — use those files to understand the API. Do not read `node_modules` to rediscover imports or signatures.
+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.
 
-## Module Reference Map
+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.
 
-| Module | File | What It Covers |
+## Active Tracks
+
+| Track | Folder | Use For |
 |---|---|---|
-| Client Setup | `references/01-client-setup.md` | `createClient`, env vars, `CreateClientOptions`, all client fields |
-| Entity Operations | `references/02-entity-operations.md` | authenticated CRUD/query, public entity reads/writes, include, pagination, typed records |
-| AI Actions | `references/03-ai-actions.md` | `defineAiAction`, `run`/`stream`/`events`, zod schemas, SSE callbacks |
-| Auth | `references/04-auth.md` | Email OTP, Phone OTP, OAuth (Google/GitHub), token management |
-| File Upload | `references/05-file-upload.md` | `upload.file`, `upload.image`, `upload.batch`, progress, abort |
-| React Integration | `references/06-react-integration.md` | `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading` |
-| Raw HTTP | `references/07-raw-http.md` | `client.raw.*`, custom API calls, interceptors |
-| Manifest Codegen | `references/08-manifest-codegen.md` | Reading `.howone/database` and `.howone/ai`, generating `src/lib/sdk.ts`, public access-aware types |
-
-## Workflow
-
-1. Identify which module(s) the task touches using the map above.
-2. Read the corresponding reference file(s) — they contain complete, runnable code examples.
-3. Read the existing `src/lib/sdk.ts` before editing. Preserve its import style and existing bindings.
-4. For Entity bindings, read `.howone/database/manifest.json`.
-5. For AI action bindings, read `.howone/ai/manifest.json`.
-6. Generate code from the manifests, not from memory.
-7. Keep sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) separate from app-code edits. Those tools write metadata only; the coding agent edits `src/lib/sdk.ts`.
-
-## Minimal App Wiring (Quick Reference)
-
-```ts
-// src/lib/sdk.ts
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  defineEntities,
-  type EntityRecord,
-  withAiActions,
-  withEntities,
-} from '@howone/sdk'
-import { z } from 'zod'
-
-// Types
-export type TodoRecord = EntityRecord & {
-  title: string
-  completed: boolean
-}
-export type TodoCreate = { title: string; completed: boolean }
-export type TodoUpdate = Partial<TodoCreate>
-export type TodoPublicQuery = { completed?: boolean; limit?: number }
-
-// Schemas
-export const summarizeTodoInputSchema = z.object({ title: z.string().min(1) })
-export type SummarizeTodoInput = z.infer<typeof summarizeTodoInputSchema>
-
-// Client
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-})
-
-// Entities
-export const entities = defineEntities({
-  Todo: client.entity<TodoRecord, TodoCreate, TodoUpdate>('Todo'),
-})
-
-// AI Actions
-export const ai = defineAiActions({
-  summarizeTodo: defineAiAction('summarizeTodo', {
-    inputSchema: summarizeTodoInputSchema,
-  }),
-})
-
-// Composed client
-const howone = withAiActions(withEntities(client, entities), ai)
-export default howone
-```
-
-## Hard Rules
-
-- **Vite env only**: use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`. Never hardcode project IDs or add `?? 'prod'` fallbacks.
-- **Single SDK config source**: configure `projectId` and `env` only in `createClient`. Do not pass env/project config to `HowOneProvider`; the React provider reads the SDK config set by `createClient`.
-- **Authenticated owner semantics**: authenticated entity APIs derive owner from the JWT. Do not pass `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` to authenticated queries or writes.
-- **Public namespace**: public reads/writes must use `howone.public.entities.*` or `client.public.entity(...)`. Do not call authenticated `howone.entities.*` from public landing pages.
-- **Public scoped queries**: for `access.public.read = "scoped"`, use `queryScoped` / `query.scoped` and pass every `requiredScopes` field such as `ownerId` and `slug`.
-- **Public writes**: only generate public `create` / `update` calls when manifest access explicitly allows them. Public create must include `created_by_user_id` or the schema-defined owner scope.
-- **Explicit types**: define `EntityRecord`, `Create`, and `Update` types explicitly. Never derive create types from `Omit<EntityRecord & ...>` — it widens the payload.
-- **System fields**: never include `id`, `_id`, `created_date`, `updated_date`, `created_by_id`, `schema_version_id`, `schema_version_number`, or `is_sample` in create/update input types.
-- **Schema versions**: treat `schemaVersionId` / `schemaVersionNumber` on records as write-time schema metadata, not business versioning.
-- **AI action naming**: do not name actions `run`, `stream`, or `events` — those are reserved method names.
-- **Call shape**: `howone.ai.<actionName>.run(input)` / `.stream(input)` / `.events(input)`. Never `howone.ai.run.<actionName>(input)`.
-- **No hooks**: `@howone/sdk/react` provides auth/theme/loading UI only — no entity, query, or AI data hooks.
-- **No codegen under `.howone`**: `.howone/` stores manifests only. Never write generated source files there.
-- **AI-first persistence**: define AI output schema first, sync `.howone/ai`, then derive Entity fields from `outputSchema`.
-- **zod for schemas**: always use zod for AI `inputSchema` / `outputSchema`.
-- **`outputSchema` caution**: `run()` validates the full `ExecutionResult` envelope, not just `finalResult`.
+| `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, 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, external workflow create/update submission, workflow schema rules, persistence boundaries, and SDK handoff. |
+
+## Routing
+
+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` 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: read the `04-ai/` files first, then `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, Email OTP, Phone OTP, Google, GitHub, token persistence, repeated login,
+  or missing token: read `03-sdk/03-auth.md` and `03-sdk/04-react-integration.md`.
+- `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`.
+
+## Reference Selection Protocol
+
+Before writing code, classify the touched surfaces:
+
+| Touched surface | Required references |
+|---|---|
+| 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` |
+| 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/02-workflow-contract-rules.md` |
+| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md` |
+| File upload | `03-sdk/05-file-upload.md` |
+| Raw HTTP escape hatch | `03-sdk/06-raw-http.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, derive entity fields from the AI `outputSchema`, 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`.
+- 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.
+- For custom in-app login, use `HowOneProvider auth="none"`, call
+  `howone.auth.setToken(token)` on success, and verify startup session with `await howone.me()`.
+- 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.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "HowOne SDK"
-  short_description: "Build HowOne SDK integrations correctly."
-  default_prompt: "Use this skill when implementing HowOne SDK client, entity, and AI action code."
+  display_name: "HowOne App Architecture"
+  short_description: "Design HowOne app schema, SDK bindings, and auth/data integration."
+  default_prompt: "Use this skill to choose the HowOne app architecture track, then implement schema, SDK bindings, or frontend SDK calls correctly."

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

@@ -0,0 +1,168 @@
+---
+name: impeccable
+description: "Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks."
+argument-hint: "[{{command_hint}}] [target]"
+user-invocable: true
+allowed-tools:
+  - Bash(npx impeccable *)
+license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
+---
+
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+
+## Setup
+
+Before any design work or file edits:
+
+1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
+2. Identify the register and load the matching register reference (brand.md or product.md).
+3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects.
+
+Skipping these produces generic output that ignores the project.
+
+### 1. Context gathering
+
+Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
+
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
+
+Load both in one call:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
+
+If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `{{command_prefix}}impeccable teach` or `{{command_prefix}}impeccable document` (they rewrite the files), or the user manually edited one.
+
+`{{command_prefix}}impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session.
+
+If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `{{command_prefix}}impeccable teach`, then resume the user's original task with the fresh context. If the original task was `{{command_prefix}}impeccable craft`, resume into `{{command_prefix}}impeccable shape` before any implementation work.
+
+If DESIGN.md is missing: nudge once per session (*"Run `{{command_prefix}}impeccable document` for more on-brand output"*), then proceed.
+
+### 2. Register
+
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
+
+Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
+
+If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `{{command_prefix}}impeccable teach` to add the field explicitly.
+
+Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
+
+## Shared design laws
+
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. {{model}} is capable of extraordinary work. Don't hold back.
+
+### Color
+
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
+- Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
+- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
+- The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+### Theme
+
+Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
+
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
+
+"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
+
+### Typography
+
+- Cap body line length at 65–75ch.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+
+### Layout
+
+- Vary spacing for rhythm. Same padding everywhere is monotony.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Don't wrap everything in a container. Most things don't need one.
+
+### Motion
+
+- Don't animate CSS layout properties.
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
+
+### Absolute bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
+- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
+- **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first.
+
+### Copy
+
+- Every word earns its place. No restated headings, no intros that repeat the title.
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
+
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
+
+Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
+
+### Routing rules
+
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+
+Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `{{command_prefix}}impeccable`.
+
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
+## Pin / Unpin
+
+**Pin** creates a standalone shortcut so `{{command_prefix}}<command>` invokes `{{command_prefix}}impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
+
+```bash
+node {{scripts_path}}/pin.mjs <pin|unpin> <command>
+```
+
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.

package/templates/vite/.howone/skills/impeccable/agents/impeccable-asset-producer.md

@@ -0,0 +1,101 @@
+---
+name: impeccable-asset-producer
+codex-name: impeccable_asset_producer
+description: Produces clean reusable raster assets from approved Impeccable mock references without redesigning the direction.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: inherit
+effort: medium
+max-turns: 12
+providers: codex
+nickname-candidates:
+  - Asset Plate
+  - Clean Plate
+  - Crop Cutter
+---
+
+# Impeccable Asset Producer
+
+You are the asset production agent for Impeccable craft.
+
+Your job is production cleanup, not new art direction. Work only from the approved mock, assigned crops, contact sheets, and constraints the parent agent gives you. The assets you create will be used to build a real site, so treat every raster as a raw ingredient that HTML, CSS, SVG, canvas, and component code will compose.
+
+## Core Rule
+
+Do not redesign. Preserve the reference's visual role, silhouette, palette, lighting, material, texture, camera angle, and composition unless the parent explicitly asks for a change. Preserve perspective only when it belongs to the object or scene itself; if CSS should create the card transform, shadow, rounded clipping, border, or layout, remove that presentation chrome from the raster.
+
+## Input Contract
+
+Expect:
+
+- Approved mock path or screenshot reference.
+- Crop paths or a contact sheet with crop ids.
+- Output directory.
+- Required dimensions, format, transparency needs, and avoid list.
+- Notes on what should remain semantic HTML/CSS/SVG instead of raster.
+
+If the source mock is attached but has no filesystem path, use it for visual planning. Ask for a path only before cropping or writing assets.
+
+Use defaults unless contradicted:
+
+- `.webp` for opaque photos, backgrounds, and textures.
+- `.png` for transparent cutouts, seals, tickets, and illustrations.
+- Target production size or at least 2x display size when dimensions are known. Do not use small full-page mock crop size as the default shipping size.
+- Remove UI text, navigation, buttons, labels, and body copy by default.
+- Keep physical marks only when the parent says they are part of the asset.
+- Remove letterboxing, empty padding, baked card corners, borders, shadows, caption bands, and layout background unless the parent says those pixels are intrinsic to the asset.
+- Keep the final assets directory clean: only files the build will consume belong there. Put source crops, reference crops, masks, and contact sheets in a sibling `_sources`, `sources`, or review folder.
+
+Ask blockers once, globally. Missing source path/crops or output directory blocks production. Exact dimensions, compression targets, retina variants, and format preferences do not block; choose defaults and report them.
+
+## Workflow
+
+1. Inventory the full approved mock or every assigned crop.
+2. Put each visual role in exactly one bucket:
+   - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
+   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
+3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+4. Give the parent an execution order for the `produce` bucket.
+5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
+6. Treat every crop as binding reference. In Codex, use the imagegen skill and built-in `image_gen` path by default when generation or editing is needed.
+7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
+8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
+9. Save outputs non-destructively in the requested project directory.
+10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
+
+Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+
+Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
+
+Use `semantic` for dashboards, charts, controls, screenshots of whole UI sections, data widgets, card chrome, app frames, icon toolbars, logos, wordmarks, and anything the final implementation can render crisply in HTML/CSS/SVG/canvas. Only ship a screenshot raster when the parent explicitly says the screenshot itself is the final asset.
+
+Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
+
+For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
+
+## Prompt Pattern
+
+Use this shape for image-to-image work:
+
+```text
+Use the provided crop as the approved visual reference.
+Recreate the same asset as a clean reusable production image at the target component aspect ratio and at least 2x display resolution.
+Preserve silhouette, object/scene perspective, camera angle, palette, lighting, material, texture, and visual role.
+Remove baked-in UI copy, navigation, buttons, labels, body text, watermarks, and mock chrome unless explicitly part of the asset.
+Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, perspective transforms, caption bands, and layout backgrounds that the implementation should create in code.
+Do not add new objects. Do not change the concept. Do not redesign the composition.
+```
+
+For transparent cutouts, use the imagegen skill's built-in-first chroma-key workflow unless the parent explicitly authorizes a true native transparency fallback.
+
+## Output Contract
+
+Return a complete manifest, grouped by `produce`, `direct`, and `semantic`. For each asset include: `id`, `source_crop`, `output_path` when applicable, `strategy`, `prompt_used` when applicable, `dimensions`, `format`, `transparency`, `deviations`, and `qa_status`.
+
+For each semantic row include `id`, `implementation`, `notes`, and `qa_status`. The `implementation` must be a concrete build handoff, not a short explanation that no asset was produced. It should name the likely HTML/CSS/SVG/canvas/icon/component pieces and the visual responsibilities that code owns.
+
+`qa_status` must be `accepted`, `needs_parent_review`, or `blocked`. Use `accepted` only after visual comparison passes. Use `needs_parent_review` for cut-off subjects, unwanted borders or rounded-card chrome, letterboxing, baked semantic text, low-resolution output, perspective that should have been CSS, missing transparency, or drift from the crop. Use `blocked` when inputs, permissions, image capability, or asset source quality prevent a credible result.
+
+End with `execution_order`, `blockers`, and `assumptions` sections. Keep blockers global and minimal. Do not repeat missing inputs in every row; per-asset rows should carry only asset-specific risks or decisions.
+
+Do not modify implementation code. Do not edit the approved mock. Do not produce final page copy. The parent craft agent owns implementation and final mock fidelity.