@meyverick/agentic 5.0.2

package/skills/design-craft/references/art-direction.md

@@ -0,0 +1,89 @@
+---
+type: Reference
+title: Art Direction
+description: Reading the brief, grounding the work in its subject, composing the hero, and keeping assets honest.
+generated: { by: agentic/1.0, at: 2026-09-21T00:00:00Z }
+sources:
+  - { id: frontend-design, resource: references/design-skills/frontend-design.md, license: absent-terms (ideas distilled and rewritten, attributed) }
+  - { id: awwwards, resource: references/design-skills/build-awwwards-quality-sites.md, license: absent-terms }
+  - { id: impeccable, resource: references/design-skills/impeccable.md, license: Apache-2.0 }
+status: stable
+---
+
+# Art Direction
+
+One visual thesis, executed consistently. Direction is decided before code, stated in one line, and held.
+
+## 1. Read the brief
+
+Extract before designing: **subject**, **audience**, **job** (what the surface must accomplish), **tone**, **constraints** (brand, era, material, palette, typeface, supplied references), and anything the client explicitly rejected.
+
+- The brief's own words outrank taste, trends, and every anti-slop rule.
+- Where the brief is silent, decide — and say why. Free axes are where defaults sneak in.
+- Ask exactly one question when subject, audience, or job is unknown. Never invent all three.
+
+## 2. Ground in the subject, not the category
+
+Distinctive work comes from the subject's own world: its industry, materials, vocabulary, tools, and history. A page about children's toys and a page about financial analysis should share no visual DNA.
+
+Reject the category reflex — the look any competent page in this field would have. If the first idea works for a competitor too, it is not yet a direction.
+
+## 3. Name the surface intent
+
+What does success look like for the visitor here? It changes what the design optimizes:
+
+| Intent | Visitor's success | Design priority |
+| --- | --- | --- |
+| Persuade | decides and acts | attention, argument, one clear next step |
+| Operate | completes a task | scanability, consistency, predictable states |
+| Read | understands something | structure, measure, comfortable rhythm |
+| Experience | is inside the work | the artifact leads; interface recedes |
+
+Intent is chosen per surface, not per product: a tool's marketing page is still Persuade; a brand's documentation is still Read.
+
+## 4. Write the direction before the first edit
+
+A compact plan with five lines — it becomes the Design Read:
+
+1. **Visual thesis** — the one idea the page is built around.
+2. **Type hierarchy** — families, roles, scale steps.
+3. **Colour system** — 4–6 named base values and their roles.
+4. **Section sequence** — the order of argument, with the hero's job named.
+5. **Motion narrative** — where movement explains, and where stillness is correct.
+
+**Review the plan against the brief before building.** Walk a similar prompt mentally; if the plan reads like what you would produce for any comparable page, revise that part and say what changed and why. Only then write code.
+
+## 5. Compose the hero
+
+The first viewport is the strongest authored moment and must work before any motion runs.
+
+- The primary call to action belongs inside the first viewport — never behind a scroll.
+- Headline: two lines maximum. Subtext: twenty words maximum, three to four lines.
+- Four text elements maximum: optional label, headline, subtext, one primary action plus at most one secondary.
+- Cap top padding (~6rem) so content does not float mid-viewport; if it feels tight, raise type scale or asset size instead of padding.
+- No trust strips, taglines below the action, pricing teasers, or logo walls inside the hero — those are separate sections directly below.
+- Navigation renders on one line at desktop widths and stays under ~80px tall; condensation beats wrapping.
+- Design a complete static first frame: it must be whole when motion, media, or any script is unavailable.
+
+## 6. Section composition
+
+- Use a layout family at most **once** per page; a page of eight sections needs at least four distinct families.
+- Never place more than **two** image-plus-text zigzags in a row; break the rhythm with a full-width, stacked, or grid section.
+- Grids contain exactly as many cells as there is content — no empty or filler tiles.
+- Multi-cell grids need real visual variation: a genuine image, a subject-derived texture or tint, or varied cell sizes.
+- Small labels above headings are rationed: at most **one per three sections**, including the hero.
+- A split header (large headline beside a small floating paragraph) is not the default; stack the two unless the right column carries real content.
+- Numbered markers are only for genuine sequences.
+
+## 7. Keep the asset system honest
+
+- References are inspected for **traits** — hierarchy, pacing, contrast, image treatment, motion principles. Never reuse, trace, or closely reproduce assets, layouts, identity, or copy.
+- Illustrations are authored or licensed, never faked with ad-hoc vector paths; interface symbols come from one consistent set.
+- People are photographs, sourced or licensed. No initials, silhouettes, or generated faces presented as real customers or staff.
+- No invented partnerships, logo walls, testimonials, or metrics. If proof cannot be sourced, omit the section.
+- Record provenance for every asset in the source or the handoff notes.
+- Describe the result in terms of the bar it meets; never claim an award, recognition, or ranking.
+
+## 8. Restraint
+
+Spend boldness in one place. Let a single element be memorable and keep everything around it quiet, disciplined, and unchanging. Before finishing, remove one accessory: if the page survives the removal, it is better.

package/skills/design-craft/references/design-engineering.md

@@ -0,0 +1,122 @@
+---
+type: Reference
+title: Design Engineering
+description: Type, colour, layout, materiality, states, forms, density, theming, and locale-handling rules.
+generated: { by: agentic/1.0, at: 2026-09-21T00:00:00Z }
+sources:
+  - { id: taste-skill, resource: references/design-skills/taste-skill.md, license: absent-terms (ideas distilled and rewritten, attributed) }
+  - { id: impeccable, resource: references/design-skills/impeccable.md, license: Apache-2.0 }
+  - { id: web-design-guidelines, resource: https://github.com/vercel-labs/web-interface-guidelines, license: MIT }
+status: stable
+---
+
+# Design Engineering
+
+Concrete rules for the decisions that make an interface feel authored rather than generated.
+
+## 1. Typography
+
+- One family, or two that are clearly distinct in role. Never a third.
+- Set a scale with intentional steps; a page needs four to six sizes, not ten.
+- Body measure stays under ~80 characters; serif body text may run slightly longer with correspondingly more leading.
+- Numbers that are compared or stacked use tabular figures; numerals in prose stay proportional.
+- Loading, saving, and pending labels end with an ellipsis character, not three periods. Use typographic quotes and non-breaking spaces in units and brand names.
+- Balance headings so they do not orphan a single word.
+
+**Tell-tale treatments to avoid:** accenting one word of a headline with a different weight, colour, or style; all-caps labels; a decorative label above every heading; type chosen because it is the default rather than because the subject called for it.
+
+## 2. Colour
+
+- Name 4–6 base values and give each a role (surface, raised surface, text, muted text, accent, state). Everything else derives.
+- Contrast: body text meets AA; hero copy and the primary action target AAA.
+- Hierarchy parity: if the primary action dominates in one theme, it dominates in every theme.
+- Brand fidelity: keep the brand colour recognisable rather than desaturating it into a theme.
+- Avoid pure black and pure white; near-values preserve depth.
+- Ship one token strategy for the whole project: either variant values per theme or semantic custom properties swapped per theme — never both, never ad-hoc overrides.
+
+## 3. Layout and space
+
+- Use a spacing scale and stay on it: airy 24–96px, standard 16–64px, dense 8–32px (see the density dial).
+- Lay out with grid rather than percentage arithmetic; avoid computed widths that only work at one viewport.
+- Contain the page with a readable maximum width and consistent gutters; alignment across sections beats novelty within one.
+- Full-height sections use dynamic viewport units so mobile chrome does not cause a jump, and never force the call to action below the fold.
+- Declare the collapse behaviour for every multi-column section explicitly, at the breakpoint where it breaks — not "it will reflow".
+- Fix overflow at the content level; do not hide it with a clipped container.
+- Full-bleed sections account for device safe areas.
+
+## 4. Materiality
+
+- Borders before shadows; one elevation recipe per level, applied consistently.
+- Blur and glow are decisions with a reason, not a default finish on every surface.
+- Radius is hierarchical: one value applied to everything flattens hierarchy.
+- Backgrounds vary where content varies; a grid of identical white cells reads as unfinished.
+
+## 5. Interactive states
+
+Every interactive element defines: **default, hover, active, focus, disabled, loading, empty, error**.
+
+- Interactive states increase contrast — hover, active, and focus are more prominent than rest.
+- Focus is always visible and never removed without an equal replacement; focus styling uses `:focus-visible` semantics so a mouse click does not draw a ring.
+- Focus is never obscured by sticky headers, footers, or overlays; add scroll margin where anchors or focused elements can be covered.
+- Disabled means unavailable, not unreadable — keep it legible and explain why when the reason is not obvious.
+- Loading shows progress on the element that started the work, not a page-level veil.
+- Hover-only affordances need touch and keyboard equivalents.
+
+## 6. Forms and data
+
+- Every control has a real label, clickable as part of the control's hit target; placeholders are examples, never the label.
+- Errors appear inline beside the field, name the problem and the fix, and the first error receives focus on submit.
+- Do not block paste. Do not disable the submit button before the request starts; show progress once it has.
+- Choose input types that match the data and set autocomplete intentions so assistive tools and password managers behave.
+- Warn before leaving with unsaved changes.
+- Destructive actions require confirmation or an undo window — never immediate and irreversible.
+- Tables: align numbers right with tabular figures, keep header alignment consistent with cells, and give every table a defined empty state.
+- Long lists are virtualised or windowed once they grow past ordinary scroll length, and rendering never performs layout reads.
+
+## 7. Content handling and density
+
+- Text containers survive long content: truncate, clamp, or break long tokens deliberately, and let children shrink where truncation is expected.
+- Test short, average, and very long inputs — including user-generated ones.
+- Empty states are directional: say what belongs here and how to add it. A blank panel is a dead end.
+- Density follows the dial: dense surfaces group and compress, airy surfaces let sections breathe. Never a dense table on an airy page without a reason.
+- Copy is content, not decoration: active voice, specific labels ("Save API key", not "Continue"), sentence case, second person, errors that state the fix, and one job per written element.
+
+## 8. Theme protocol
+
+- Support the themes the project ships; do not assume a single mode. Respect the system preference unless the brand insists otherwise.
+- Decide the mode earlier, not later: retrofitting a dark theme into hardcoded light values is a rewrite.
+- Set the document colour scheme so native controls, scrollbars, and form widgets match the active theme.
+- Test every shipped theme before finishing: contrast, hierarchy, imagery, and brand expression all hold in each.
+
+## 9. Media and imagery
+
+- Choose aspect ratios deliberately and crop for them; never letterbox or distort at any size.
+- Give every image alternative text, and define a fallback for media that is missing or fails to load.
+- Set explicit dimensions so loading media cannot shift the layout.
+- Decorative media earns its place only when it carries narrative; otherwise omit it. Abstract gradient shapes standing in for art direction are not imagery.
+- No filler stock: when nothing honest exists, a typographic or colour-driven composition is stronger than a borrowed photograph.
+- Weight follows role — hero media may be generous, thumbnails may not.
+- Record provenance for every asset, licensed or generated, in the source or the handoff.
+
+## 10. Non-text surfaces and contrast detail
+
+- Non-text elements that carry meaning — borders of inputs, icons, chart series, focus rings — meet a 3:1 contrast ratio against their surroundings.
+- Text placed over imagery sits on a deliberate scrim, tint, or solid panel; never rely on the photograph staying dark in that spot.
+- Sticky headers and footers stay thin (well under a tenth of the viewport), and any anchored or focused element is offset so it is not hidden beneath them.
+- Disabled controls remain legible; reduce affordance, not readability.
+- Charts and data graphics label series directly where possible rather than relying on a legend the eye must travel to.
+
+## 11. Quotes and social proof
+
+- Quotes are short, real, and attributed to a named person or role. Never invent a customer, metric, or partnership.
+- Testimonial treatment stays quiet: no oversized quotation marks as decoration, no carousel that hides the substance behind interaction.
+- Proof is placed below the hero and beside the claim it supports, never stuffed into the opening viewport.
+- Absent real proof, omit the section rather than implying it.
+
+## 12. Locale and internationalisation
+
+- Format dates, times, numbers, and currency with platform internationalisation APIs, never hardcoded patterns.
+- Detect language from request or client preferences, never from location.
+- Mark brand names, code tokens, and identifiers as untranslatable so machine translation does not garble them.
+- Leave room for text expansion (allow roughly 30% growth) and avoid text baked into images.
+- Ensure interactive targets meet minimum touch size and account for safe-area insets.

package/skills/design-craft/references/motion-craft.md

@@ -0,0 +1,124 @@
+---
+type: Reference
+title: Motion Craft
+description: Deciding whether to animate, then choosing easing, duration, springs, technique, and cleanup.
+generated: { by: agentic/1.0, at: 2026-09-21T00:00:00Z }
+sources:
+  - { id: emil-design-eng, resource: references/design-skills/emil-design-eng.md, license: absent-terms (ideas distilled and rewritten, attributed) }
+  - { id: taste-skill, resource: references/design-skills/taste-skill.md, license: absent-terms }
+  - { id: awwwards, resource: references/design-skills/build-awwwards-quality-sites.md, license: absent-terms }
+  - { id: web-design-guidelines, resource: https://github.com/vercel-labs/web-interface-guidelines, license: MIT }
+status: stable
+---
+
+# Motion Craft
+
+Motion is a decision before it is a technique. Answer the four questions in order, then build.
+
+## 1. Should this animate at all?
+
+Ask how often a given person will trigger it:
+
+| Frequency | Decision |
+| --- | --- |
+| Many times a day (command palette, keyboard shortcuts, list navigation) | none — instant |
+| Tens of times a day (hover, row selection) | remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | standard animation |
+| Rare or first-time (onboarding, celebration) | delight is allowed |
+
+Never animate a keyboard-initiated action: repetition makes animation read as lag.
+
+## 2. What is its purpose?
+
+Every animation answers "why does this move?" Valid purposes:
+
+- **Feedback** — the interface acknowledges the action.
+- **Spatial consistency** — an element enters and leaves along the same path, so dismissal feels predictable.
+- **State indication** — a control shows that something changed.
+- **Explanation** — a sequence demonstrates how a feature works.
+- **Preventing a jarring change** — something appearing or disappearing with no transition reads as broken.
+
+If the honest answer is "it looks cool" on a frequently seen surface, do not animate it.
+
+## 3. Which easing?
+
+| Situation | Easing |
+| --- | --- |
+| Entering the screen | ease-out (immediate movement, then settle) |
+| Moving or morphing on screen | ease-in-out |
+| Hover or colour change | ease |
+| Continuous motion (marquee, progress) | linear |
+| Leaving the screen | ease-in (or ease-out with a shorter duration) |
+
+- **Never use ease-in for an entrance** — starting slow reads as sluggish precisely when attention is highest.
+- Default curves are weak; prefer steeper custom curves. Useful starting values: entrance `cubic-bezier(0.23, 1, 0.32, 1)`; on-screen movement `cubic-bezier(0.77, 0, 0.175, 1)`; drawer/tray `cubic-bezier(0.32, 0.72, 0, 1)`.
+- Enter and exit need not mirror: exits are usually faster and quieter than entrances.
+
+## 4. How long?
+
+| Element | Duration |
+| --- | --- |
+| Press feedback | 100–160ms |
+| Tooltip, small popover | 125–200ms |
+| Dropdown, select, menu | 150–250ms |
+| Modal, drawer, sheet | 200–500ms |
+| Explanatory or marketing sequence | longer is permitted |
+
+- Interactive UI stays under ~300ms. Distance, size, and element weight justify the upper end; frequency argues for the lower.
+- A faster spinner makes identical load times feel shorter. Speed is perceived as quality.
+
+## 5. Springs
+
+Use a spring when the motion is **interruptible** or follows a **gesture** — dragging, flicking, sheets, anything a person can grab or reverse mid-flight. Springs preserve velocity when interrupted; fixed-duration curves restart and feel mechanical.
+
+- Tuning intuition: higher stiffness settles faster and tighter; lower damping produces more overshoot. For UI, aim for minimal overshoot — enough to feel physical, not bouncy.
+- Do not spring simple fades, colour changes, or entrances that nobody interrupts; a short ease-out is cheaper and cleaner.
+- Spring motion must still respect reduced motion and must not delay a state change the person is waiting on.
+
+## 6. Technique
+
+- **Distance-independent motion**: translate by percentage when the element's size varies.
+- **Scale children too**: scaling a parent scales its contents; compensate or animate the inner element separately to avoid distorted text.
+- **Transform origin**: set it deliberately — popovers and menus originate from their trigger, not from their own centre.
+- **Depth**: a small 3D rotation or perspective can imply layering; keep it subtle and never for text.
+- **Clip-path reveals**: an inset clip animates cleanly for image and panel reveals, and pairs well with a slight translate.
+- **Stagger**: offset siblings by small increments with a capped total; direction stays consistent. Do not stagger the primary action.
+- **Interruptibility**: a user who changes their mind mid-animation should be able to reverse it immediately.
+- Prefer the simplest mechanism that works — platform transitions for state, the platform animation API for sequenced or programmatic motion. One motion system per project.
+
+## 7. Gesture and drag
+
+- Momentum: a flick continues and settles naturally rather than stopping dead.
+- Boundaries: resistance rather than hard stops, so the user feels the edge instead of hitting it.
+- Feedback during drag: disable text selection and make the dragged element the obvious focus of the interaction.
+- Every gesture needs a tap, click, and keyboard alternative unless the gesture is truly essential.
+
+## 8. Performance
+
+- Animate **transform and opacity**; anything that triggers layout or paint on every frame is a defect.
+- Never animate every property — list the properties explicitly.
+- Pause or stop animation when the element is offscreen or the document is hidden.
+- Continuous canvas or WebGL work caps device pixel ratio, throttles input, and allocates nothing per frame.
+- Media: short non-essential loops use compressed video with a still fallback rather than animated images.
+
+## 9. Accessibility
+
+- `prefers-reduced-motion` renders final states immediately — do not merely shorten the animation.
+- Decorative loops stop entirely under reduced motion.
+- Motion is never the only signal for a state change; pair it with a visible state.
+- Autoplaying motion longer than five seconds alongside other content needs pause, stop, or hide controls.
+
+## 10. Debugging motion
+
+- Slow playback down (roughly 8–10×) to inspect timing and easing; most defects are invisible at full speed.
+- Step frame by frame around the start and end of a transition to catch jumps and double-triggers.
+- Test on real devices, and under load: smooth on a fast machine says nothing about a mid-range phone.
+- Add instrumentation to find dropped frames, and re-measure after every content or font change.
+
+## 11. Forbidden
+
+- Animation with no narrative or feedback role.
+- Infinite offscreen animation; continuously animated backgrounds.
+- Layout-affecting animation, per-frame allocation, or unbounded blur and glow.
+- Entrances from zero scale, or from a different origin than the element's own.
+- Animating keyboard-driven actions, or making a person wait for an animation to act.

package/skills/design-craft/references/process.md

@@ -0,0 +1,47 @@
+---
+type: Reference
+title: Process
+description: Detection first, design-system decisions, token persistence, knowledge lookups, and handoff.
+generated: { by: agentic/1.0, at: 2026-09-21T00:00:00Z }
+sources:
+  - { id: ui-ux-pro-max, resource: references/design-skills/ui-ux-pro-max.md, license: absent-terms (procedure distilled and rewritten, attributed) }
+  - { id: impeccable, resource: references/design-skills/impeccable.md, license: Apache-2.0 }
+  - { id: frontend-design, resource: references/design-skills/frontend-design.md, license: absent-terms }
+status: stable
+---
+
+# Process
+
+The order of operations that keeps the work honest, whatever the stack.
+
+## 1. Detect before you decide
+
+Inspect the project before proposing anything visual: framework and rendering model, styling approach and where tokens live, any motion mechanism already present, the icon set in use, existing design system or brand assets, the build and test commands, and whether the app can be run and inspected.
+
+**Never assume.** A hardcoded default silently misroutes every recommendation. If something material cannot be detected — the audience, or which of two surfaces is in scope — ask one question rather than choosing for the user.
+
+## 2. Design system: adopt, extend, or build
+
+- If the project already has a system or tokens, work inside it. Extending beats introducing a second one.
+- If the brief names an established system, use its official implementation rather than recreating the look by hand — and do not import its tokens only to override most of them.
+- **One system per project.** Mixing two in one surface is a defect, not a style.
+- An aesthetic rather than a system usually has no official package: build it from the platform's own capabilities, and be honest in comments about what is borrowed inspiration versus official material.
+- A system is a floor, not a direction: never ship its default state as the final design.
+
+## 3. Persist the direction
+
+Write the system down so the next session does not guess: a **master file** (palette with roles, type scale, spacing rhythm, motion rules, component conventions) plus **per-surface overrides** that win for that surface only. Read the master before writing anything, and read the override before touching that surface. Never regenerate or overwrite the master without explicit authorization — prior decisions, yours or a teammate's, outrank a fresh run.
+
+## 4. Look things up, verify, then apply
+
+Prefer the project's own sources: tokens, components, documentation, history. Query with one dominant intent and a few meaningful terms, not a paragraph. If a lookup returns nothing useful, retry once narrower; if it still returns nothing, say no verified match was found and label any general guidance as a fallback. **Never persist unverified output** — no invented palette, no unconfirmed token, no rule recalled from memory and presented as project convention. Retrieved guidance is a recommendation: the user, the brief, and the project's rules outrank it.
+
+## 5. Verify in bounded passes
+
+Build fully → inspect once in a single batch (desktop and mobile together on web; the shipped device classes elsewhere) → fix everything that batch showed in one pass → confirm with at most one further round → stop.
+
+Open-ended polishing behind a working interface is waste: it burns budget doing worse what the final handoff does better. Screenshots beat prose — one image settles a debate paragraphs cannot. Aesthetic choices are arguable; accessibility, honesty, and performance are not.
+
+## 6. Hand off
+
+Report briefly, in this order: the **Design Read** (mode, subject, audience, job, dials); what changed and which dials drove it; findings fixed with severities; what remains open plus any assumption to confirm; and asset provenance with any license note for shipped media. Keep it short — the work is the deliverable, the report is the receipt.

package/skills/design-craft/references/review-checklist.md

@@ -0,0 +1,121 @@
+---
+type: Reference
+title: Review Checklist
+description: Review method, severity ladder, and the checklist used for interface reviews, including the vendored Web Interface Guidelines digest.
+generated: { by: agentic/1.0, at: 2026-09-21T00:00:00Z }
+sources:
+  - { id: emil-design-eng, resource: references/design-skills/emil-design-eng.md, license: absent-terms (ideas distilled and rewritten, attributed) }
+  - { id: impeccable, resource: references/design-skills/impeccable.md, license: Apache-2.0 }
+  - { id: taste-skill, resource: references/design-skills/taste-skill.md, license: absent-terms }
+  - { id: web-interface-guidelines, resource: https://github.com/vercel-labs/web-interface-guidelines, license: MIT, captured: 2026-09-21 }
+status: stable
+---
+
+# Review Checklist
+
+Review produces findings, not opinions. Evidence first, fix second.
+
+## Method
+
+1. **Scope** — name what is under review (files, routes, or surfaces) before starting.
+2. **Gather evidence** — read the source, and inspect the rendered surface when the environment allows: one batch covering desktop and mobile together. A screenshot settles arguments that prose cannot.
+3. **Check in order** — blockers first (accessibility, honesty, broken behaviour), then hierarchy and craft, then polish. Stop escalating once the surface is sound.
+4. **Report** — one line per finding, severity-ranked, `file:line` locatable:
+   `<severity> · <file>:<line> · <rule violated> · <fix>`
+5. **Do not edit** unless fixes were requested. When they were, re-run the checklist afterwards.
+
+Severity ladder: **blocker** (inaccessible, dishonest, or broken) · **major** (hierarchy, contrast, motion, performance) · **minor** (polish).
+
+## Checklist
+
+### Accessibility
+
+- Every interactive element has a visible focus indicator, never removed without an equal replacement.
+- Icon-only controls carry an accessible name; images carry alternative text (empty for decorative).
+- Controls use real labels, associated with the control and clickable as one hit target.
+- Semantic elements before ARIA: a button for actions, a link for navigation — never a clickable container.
+- Headings are ordered and hierarchical; the page has a skip path to the main content.
+- Sticky headers, footers, and overlays never obscure the focused element.
+- Async updates (toasts, validation) are announced to assistive technology.
+- Decorative media is hidden from assistive technology; meaningful media has captions or a transcript.
+- Zoom is never disabled.
+
+### Forms
+
+- Correct input type and autocomplete intention per field; paste is never blocked.
+- Errors appear inline beside the field, state the fix, and the first error receives focus on submit.
+- The submit control stays enabled until the request starts, then shows progress.
+- Unsaved changes warn before navigation.
+- Checkboxes and radios share a single hit target with their label.
+
+### Motion
+
+- `prefers-reduced-motion` renders final states; decorative loops stop entirely.
+- Only compositor-friendly properties animate; properties are listed, never "all".
+- Transform origin is deliberate; animations are interruptible.
+- Motion longer than five seconds alongside other content offers pause, stop, or hide.
+- No gesture-only action without a click and keyboard equivalent.
+
+### Typography and content
+
+- Body measure under ~80 characters; headings do not orphan a single word.
+- Ellipsis character for truncation and loading labels; typographic quotes; non-breaking spaces in units and brand names.
+- Numeric columns use tabular figures.
+- Long, short, and very long content all render without breaking layout; empty states give direction.
+- Copy is active voice, sentence case, second person, with specific labels and errors that state the next step.
+- Dates, times, numbers, and currency use internationalisation APIs; brand and code tokens are marked untranslatable.
+
+### Images and media
+
+- Explicit dimensions on media to prevent layout shift; below-fold media loads lazily.
+- Above-fold critical media is prioritised.
+- Compressed video with a still fallback rather than animated images for short loops.
+- Provenance recorded; no unlicensed or invented assets.
+
+### Performance
+
+- Targets: largest contentful paint under 2.5s, interaction latency under 200ms, cumulative layout shift under 0.1.
+- No layout reads during rendering; DOM reads and writes are batched.
+- Long lists are virtualised or windowed.
+- Fonts are preloaded where critical with a swap strategy; third-party origins are preconnected.
+- Motion and canvas work pause offscreen; per-frame allocation is absent.
+
+### Layout and touch
+
+- Full-bleed layouts respect device safe areas; content overflow is fixed rather than clipped.
+- Touch targets meet minimum size; tap highlight and double-tap zoom are handled deliberately.
+- Containers inside sheets and drawers contain their overscroll.
+- Multi-column sections declare their narrow-width collapse.
+
+### State and navigation
+
+- Addressable state (filters, tabs, pagination, open panels) is reflected in the URL and deep-linkable.
+- Navigation uses real links so open-in-new-tab and modifier-click work.
+- Destructive actions require confirmation or an undo window.
+- Empty, loading, and error states exist for every data surface.
+
+### Theming
+
+- Every shipped theme holds contrast, hierarchy, and brand expression.
+- The document colour scheme matches the active theme so native controls follow.
+- Theme values come from one token strategy, not scattered overrides.
+
+## Vendored Web Interface Guidelines digest
+
+Upstream: `https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md` (MIT), captured **2026-09-21**. This digest is the offline floor; re-fetch to refresh. Rules are restated in stack-neutral terms. Areas already covered by the checklist above — accessibility, focus, forms, motion, layout, touch, images, theming, navigation and state — are not repeated; what follows is the remainder of the upstream rule set.
+
+**Typography** — ellipsis character; curly quotes; non-breaking spaces for units and shortcuts; loading labels end with an ellipsis; tabular figures for numeric columns; balanced heading wrapping.
+
+**Content handling** — long content truncates, clamps, or wraps deliberately; shrinkable children where truncation is expected; empty states handled; short, average, and very long user input all anticipated.
+
+**Performance detail** — virtualise long lists; no layout reads while rendering; batch DOM reads and writes; uncontrolled inputs preferred, controlled inputs cheap per keystroke; preconnect asset origins; preload critical fonts with swap; compressed video over animated images with a still alternative.
+
+**Locale** — internationalisation APIs for dates, times, numbers, and currency; language detected from preferences rather than location; brand and code tokens marked untranslatable.
+
+**Hydration safety** — inputs with a value must handle change or default explicitly; server and client rendering of dates and times must agree; suppression of hydration warnings only where genuinely required.
+
+**Hover and states** — buttons and links have a hover state; interactive states increase contrast above rest.
+
+**Copy** — active voice; title case for headings and buttons; numerals for counts; specific button labels; errors with a fix; second person.
+
+**Flag on sight** — disabled zoom; blocked paste; animating all properties; removed outlines; click handlers on non-interactive containers; images without dimensions; unvirtualised large lists; inputs without labels; icon buttons without names; hardcoded date or number formats; unjustified autofocus; animated images where video fits; gesture-only actions.

package/skills/guardrails/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: guardrails
+description: >
+  Cross-cutting hardening for security, deprecated APIs, and system gotchas. Use when writing or modifying code that touches dependencies, Docker, HTML/auth, or secrets. Use when reviewing code for security pitfalls. Do NOT use when only reading or exploring without code changes.
+allowed-tools: Bash(*)
+license: MIT
+compatibility: Requires bun >= 1.0.
+metadata:
+  author: agentic
+  version: "1.0"
+positive_triggers:
+  - "check for security pitfalls before committing code"
+  - "prevent deprecated API usage in this change"
+  - "review system gotchas for Docker and HTML handling"
+  - "harden code touching dependencies or auth"
+anti_triggers:
+  - "only reading code without modifying it"
+  - "exploring the codebase without code changes"
+---
+
+# Guardrails
+
+Cross-cutting hardening that loads first — before domain skills — to prevent the 5 mistakes that recur across reports: `on*` stripping, secret leaks, deprecated adapter, `null` vs `Option`, lifetime elision. Tiny Level 1 inline; Level 2 behind `references/guardrails-patterns.md`.
+
+## Activation Boundary
+
+**Triggers on:**
+- Writing/modifying code that touches `deps` (package.json, Cargo.toml), `Docker` (Dockerfile, compose), `HTML` (Svelte, templ), `auth` (tokens, cookies, sessions), or secrets
+- Reviewing a change for security or deprecated usage
+- Handling `on*` event handlers, `innerHTML`, or secret-like strings
+
+**Does NOT trigger on:**
+- Only reading or exploring without mutations (use explore mode)
+- Pure planning (proposal/design/tasks) before code
+- Skills that explicitly state `Do NOT use guardrails` (none today)
+
+## When to Use
+
+Load this skill **first** before any domain skill when the task touches the 4 high-risk surfaces above. Check the 5 anti-examples below, then proceed to domain logic. If no high-risk surface, skip guardrails — save tokens.
+
+## Contrast
+
+| Before (old) | After (new) | Why different |
+|--------------|-------------|---------------|
+| `on*` handlers stripped silently | Preserve `on:click` explicitly or sanitize intentionally | Svelte 5 strips unknown `on*` — must be explicit, not accidental |
+| `if (user != null)` | `if let Some(user) = user` | Rust absence is type-level `Option`, not runtime `null` |
+| `svelte-adapter-bun` | `@sveltejs/adapter-static` + `tower-http` | 3.0.0 canonical: Axum serves static, not Bun adapter |
+| `Embedded SQLite per container` | `Central PostgreSQL via SQLx` | Single owner `crates/api/migrations/` — no `../` traversal |
+| `cargo build` in handler | `queue + worker + WSS` | Heavy CPU never blocks request path — coordinator delegates |
+
+## Anti-examples
+
+**1. Do NOT: Strip `on*` silently**
+```svelte
+<!-- before (wrong) — Svelte strips on* without warning -->
+<div oncustom={handler}>click</div>
+```
+```svelte
+<!-- after (right) — explicit Svelte 5 handling -->
+<div on:click={handler}>click</div>
+```
+Why: Svelte 5 sanitizes `on*` — undetected loss of interactivity.
+
+**2. Do NOT: Commit secrets**
+```bash
+# before (wrong)
+git commit -m "add .env with WARERA_KEY=abc"
+```
+```bash
+# after (right) — .env is gitignored, secrets via envx
+echo ".env" >> .gitignore && envx set WARERA_KEY
+```
+Why: `NEVER commit credentials/.env` — `AGENTS.md` Must-follow, leaked secrets rotate.
+
+**3. Do NOT: Use deprecated adapter**
+```js
+// before (wrong)
+import adapter from 'svelte-adapter-bun';
+```
+```js
+// after (right)
+import adapter from '@sveltejs/adapter-static';
+export default { kit: { adapter: adapter({ fallback: 'index.html' }) } };
+```
+Why: 3.0.0 stack inversion — Axum `tower-http` serves static, single distroless binary.
+
+**4. Do NOT: Check null in Rust**
+```rust
+// before (wrong)
+if user != null { /* ... */ }
+```
+```rust
+// after (right)
+if let Some(u) = user { /* use u */ }
+```
+Why: Rust has no `null`; absence is `Option<T>` — compiler forces handling.
+
+**5. Do NOT: Elide lifetimes unsafely**
+```rust
+// before (wrong)
+fn longest(x: &str, y: &str) -> &str { x }
+```
+```rust
+// after (right)
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { if x.len() > y.len() { x } else { y } }
+```
+Why: Borrow checker requires explicit `'a` when output borrows input.
+
+## References
+
+- `references/guardrails-patterns.md` — Level 2 detail for each anti-example (code before/after, signal, Why) — on-demand, not startup cost
+- `project/AGENTS.md` Must-read pointer — this skill is first-loaded via `Must-read: project/skills/guardrails/SKILL.md before any code touching deps/Docker/HTML/auth`
+
+## Gotchas
+
+- Loads first, but only when high-risk surface present — `only reading` anti-triggers prevent bloat on explore tasks
+- Never duplicate domain anti-examples — domain skills link here via `See ../../guardrails/SKILL.md — cross-cutting anti-examples`
+- Single source for cross-cutting: this skill, not `AGENTS.md` body (AGENTS.md only holds the pointer)