@etus/seven-skill 0.1.0-beta.3 → 0.1.0-beta.5

package/.claude/skills/seven/reference/harden.md

@@ -0,0 +1,36 @@
+# Harden — make the surface production-complete
+
+Harden an existing Seven implementation against real data, failure, accessibility needs, and hostile runtime conditions. Do not redesign it while hardening.
+
+## Build the risk matrix
+
+For every primary workflow, cover:
+
+- initial loading, background refresh, and partial loading;
+- empty first-use versus empty filtered result;
+- validation, permission, authentication, network, server, and unknown errors;
+- retry, cancel, undo, and recovery paths;
+- success confirmation and stale data;
+- disabled, read-only, pending, destructive, and concurrent-action states;
+- minimum, typical, maximum, long localized, missing, malformed, and duplicate content;
+- narrow viewport, zoom, reduced motion, keyboard-only, screen reader, and high contrast;
+- slow network, offline behavior where relevant, and aborted requests.
+
+Use the matched surface brief as the contract. Ask when a business outcome is unknown; never invent recovery behavior that could lose or mutate data.
+
+## Implementation rules
+
+- Use Seven components for every control, message, skeleton, progress indicator, alert, dialog, and toast.
+- Keep inline form errors associated through the component API; do not replace them with toast-only feedback.
+- Prevent duplicate submissions and make pending state perceivable without removing the accessible name.
+- Preserve user input on recoverable failure.
+- Give images dimensions, meaningful alt text when informative, and a safe fallback.
+- Guard async races and unmounts; errors must not strand focus or leave an irreversible optimistic state.
+- Keep content visible when enhancement JavaScript fails where progressive rendering applies.
+- Use Error Boundaries only at recovery boundaries, not to hide deterministic bugs.
+
+## Verification
+
+Tests must encode why each adverse state matters. Include at least one keyboard path, one assistive-name assertion, one long-content case, one network/error recovery case, and one repeated-action case when applicable. Run `node .claude/skills/seven/scripts/run-seven.mjs check`, unit/integration tests, and rendered browser validation for the target.
+
+Finish with a residual-risk list. “Works on the happy path” is never a hardened result.

package/.claude/skills/seven/reference/hooks.md

@@ -0,0 +1,11 @@
+# Hooks
+
+Seven consumer hooks are project-local guardrails. Claude uses `.claude/settings.json`; Codex uses `.codex/hooks.json` and requires the user to review/trust the exact definition; Cursor uses `.cursor/hooks.json`; Grok uses `.grok/hooks/seven.json` and requires project hook trust. Seven merges only its own entries and preserves every third-party hook. Hosts without a compatible project hook API still receive the skill and are covered by the provider-independent local Git pre-commit gate.
+
+`PreToolUse` injects product and release context before UI writes. `PostToolUse` runs the immediate deterministic tier on touched UI files. `Stop` runs the full pass over the UI files touched in the session plus every staged, unstaged, or untracked UI path in the Git working tree. That final union also catches files created through shell commands that bypass the provider's structured edit tools. Active errors or warnings return the provider-native structured continuation decision, asking the agent to correct the UI before it stops. Claude Code re-entry with `stop_hook_active: true` exits silently because the prior response already surfaced the findings; providers without that signal use a three-attempt cap for an unchanged finding set. The authoritative `node .claude/skills/seven/scripts/run-seven.mjs check --all` result remains blocking after either loop guard. Advisories are surfaced without blocking.
+
+Parser, dependency, and runtime failures fail open and exit zero so a broken local hook never traps the agent. A valid Seven finding is not a hook failure: it uses the host's supported JSON protocol to continue the task.
+
+Use `node .claude/skills/seven/scripts/run-seven.mjs hooks status|on|off`. Machine-local `ignore-file` and `ignore-rule` controls affect hook noise only, never the shared `node .claude/skills/seven/scripts/run-seven.mjs check` result. Never edit `.github/**` to enable Seven hooks.
+
+Host discovery may require a one-time action that npm cannot perform: enable Agent Skills in Cursor/Gemini, review project hooks in Codex with `/hooks`, trust Grok hooks with `/hooks-trust` (or `--trust`), and restart Trae after installation. Treat the corresponding `node .claude/skills/seven/scripts/run-seven.mjs doctor` information item as an activation checklist, not as proof that the host's private setting was changed.

package/.claude/skills/seven/reference/init.md

@@ -0,0 +1,5 @@
+# Init — compatibility alias
+
+`init` is retained for projects and prompts created before `setup` became the canonical skill workflow.
+
+Read [setup.md](setup.md) completely and follow it without changing its behavior. Do not confuse the skill invocation `/seven init` with the `seven init` CLI subcommand: the former delegates to context setup; the latter installs the Seven release and consumer governance through the local runner.

package/.claude/skills/seven/reference/layout.md

@@ -0,0 +1,33 @@
+# Layout — composition and responsive structure
+
+Improve the spatial system of an existing Seven surface without changing its product meaning or inventing new design tokens.
+
+## Diagnose the structure
+
+Inspect DOM/read order and rendered geometry for:
+
+- primary task and reading path;
+- alignment lines, container ownership, and spacing rhythm;
+- unnecessary centering, edge-flush cards, nested cards, and repeated wrappers;
+- fixed dimensions, overflow, clipping, and first-viewport column failure;
+- relationship between app shell, content canvas, panels, overlays, and actions;
+- mobile reflow and keyboard order.
+
+State the layout invariant before editing: for example, “navigation stays fixed, the result list owns remaining width, detail collapses below at the content breakpoint.”
+
+## Apply
+
+- Compose installed Seven templates/blocks and component slots first.
+- Use Grid for two-dimensional structure and Flexbox for one-dimensional alignment.
+- Choose content-driven breakpoints; do not scatter device-specific magic numbers.
+- Preserve DOM order so visual rearrangement does not break screen-reader or keyboard sequence.
+- Use Seven spacing tokens. Vary rhythm intentionally: tighter within components, wider between groups and sections.
+- Keep shell chrome borderless according to [app-shell.md](app-shell.md); content surfaces own their borders.
+- Bound prose and forms; let data surfaces use width where it improves comparison.
+- Overlays must escape clipping ancestors and retain a logical trigger/focus relationship.
+
+Do not solve layout with absolute positioning, negative margins, transforms that only look aligned at one width, or duplicate mobile markup unless semantics genuinely differ.
+
+## Verify
+
+Inspect breakpoint boundaries, 320 px, a wide viewport, 200% zoom, long content, empty and maximum data, keyboard sequence, and browser overflow/clipping checks. Run Seven validation for every changed file.

package/.claude/skills/seven/reference/live.md

@@ -0,0 +1,106 @@
+# Live — reversible browser iteration
+
+Run an interactive Seven session against a rendered React 19 surface. The browser may preview inert HTML/CSS directions, but accepted previews become production only after a source edit using installed Seven components, declared variants, tokens, focused tests, and `run-seven.mjs check`.
+
+## Phase 0 — prerequisites
+
+1. Load the normal Seven context and run `node .claude/skills/seven/scripts/run-seven.mjs doctor --quick --target <source>`.
+2. Confirm the app is a local or explicitly trusted development origin and its dev server is already running.
+3. Resolve the smallest source target inside the consumer project. Native and Svelte adapters are intentionally unsupported.
+4. Confirm the packaged extension is available:
+
+   ```bash
+   node .claude/skills/seven/scripts/run-seven.mjs extension path
+   ```
+
+   npm cannot activate a browser extension without browser/user consent. On first use, load that directory unpacked from `chrome://extensions`; this is the only manual installation step.
+
+## Phase 1 — start and connect
+
+Start the loopback bridge in a persistent/background terminal:
+
+```bash
+node .claude/skills/seven/scripts/run-seven.mjs live start --url http://127.0.0.1:5173/route --target src/path/Surface.tsx
+```
+
+The command prints a `serverUrl` and random session `token`. Treat the token as ephemeral capability data: paste it into Seven UI Guardian, do not put it in chat transcripts, source, screenshots, shell history snippets, or commits. The extension retains it only in memory.
+
+The bridge binds to `127.0.0.1`, validates extension/local origins, restricts page events to the declared app origin, caps payloads, rejects sensitive fields, and accepts preview HTML/CSS only. It never accepts JavaScript, event handlers, embedded documents, CSS imports, or CSS network URLs.
+
+## Phase 2 — event loop
+
+Keep a one-shot foreground poll active whenever the user can interact with the Live panel:
+
+```bash
+node .claude/skills/seven/scripts/run-seven.mjs live poll
+```
+
+Dispatch the returned event, reply, then poll again immediately.
+
+### `generate`
+
+The event contains the action, optional prompt, target selector, bounded outer HTML, a Seven-relevant computed-style subset, viewport rectangle, page URL, and source target. It contains no cookies, request bodies, headers, browser storage, or network responses.
+
+1. Load the action's normal Seven reference plus [visual-probes.md](visual-probes.md).
+2. Use the target evidence and installed Seven contracts; do not infer a new token or component API from computed CSS.
+3. Produce one to three materially distinct directions. Each direction must be one inert HTML root plus optional local preview CSS.
+4. Save the payload inside the ignored `.seven/live/` directory and deliver it:
+
+```json
+{
+  "status": "done",
+  "message": "Direções que preservam o job e o release Seven instalado.",
+  "variants": [
+    {
+      "id": "hierarchy",
+      "label": "Hierarquia explícita",
+      "html": "<section>...</section>",
+      "css": ".seven-live-probe { color: var(--foreground); }"
+    }
+  ]
+}
+```
+
+```bash
+node .claude/skills/seven/scripts/run-seven.mjs live reply --id <event-id> --file .seven/live/reply-<event-id>.json
+node .claude/skills/seven/scripts/run-seven.mjs live poll
+```
+
+Preview CSS is disposable evidence. Do not copy it mechanically into the source.
+
+### `steer`
+
+Read the message, make only the requested source/navigation adjustment when authorized, and reply with a short `message`. Do not treat steering as permission to redesign adjacent UI.
+
+### `accept`
+
+Acceptance identifies the chosen direction and current preview evidence. It authorizes applying that direction to the declared source target, not pasting DOM output blindly.
+
+1. Re-resolve the real React component and any shared composition.
+2. Apply the smallest source edit using existing Seven components, variants, tokens, semantics, and pt-BR copy.
+3. Run focused tests and `node .claude/skills/seven/scripts/run-seven.mjs check --file <changed-file>`.
+4. Refresh/reinspect the rendered surface. If source and preview conflict, source truth wins and the difference is reported.
+5. Reply `done` to the accept event and poll again.
+
+Use the manual-edit-applier agent when the provider exposes it. The finish-reviewer may independently verify the result; neither agent may invent missing Seven contracts.
+
+### `discard`
+
+The extension restores the original DOM snapshot. Reply `done`; make no source edit.
+
+## Recovery and completion
+
+The append-only journal and session metadata live under ignored `.seven/live/` state:
+
+```bash
+node .claude/skills/seven/scripts/run-seven.mjs live status
+node .claude/skills/seven/scripts/run-seven.mjs live start --resume --url <same-url> --target <same-target>
+```
+
+An unanswered event is replayed after bridge restart. A replied event is not reissued. Stop explicitly when the user exits:
+
+```bash
+node .claude/skills/seven/scripts/run-seven.mjs live stop
+```
+
+Report accepted/discarded directions, source files changed, Seven components/variants/tokens used, checks run, unresolved conflicts, and confirmation that the temporary browser layer was disconnected. Never create `.github/**` or persist the token.

package/.claude/skills/seven/reference/motion-design.md

@@ -27,7 +27,7 @@ Every clickable affordance in Seven gets the same micro-press, not just `<Button
 }
 ```
 
-Apply to `<button>`, `<a>` with `role="button"`, the trigger row of `<Combobox>`, the avatar pill in the topbar, table row click affordances, every interactive list item. The detector ships a `missing-tactile-press` rule (Phase 2) that catches affordances that opted out.
+Apply to `<button>`, `<a>` with `role="button"`, the trigger row of `<Combobox>`, the avatar pill in the topbar, table row click affordances, every interactive list item. The detector ships a `missing-tactile-press` rule that catches affordances that opted out.
 
 Disabled state does not press. Loading state does not press. Reduced-motion users do not press: the entire system honors `prefers-reduced-motion: reduce` and falls back to instant state changes plus an opacity fade.
 

package/.claude/skills/seven/reference/onboard.md

@@ -0,0 +1,35 @@
+# Onboard — first-run and activation UX
+
+Design the product experience for a user who has not yet completed setup or reached first value. This is not context capture; use `init` for `PRODUCT.md` and surface briefs.
+
+## Define activation
+
+From product context, identify:
+
+- who is new and what they already know;
+- the first meaningful outcome, not merely account completion;
+- required versus deferrable setup;
+- permissions, external dependencies, waiting states, and failure recovery;
+- whether the user can explore safely before connecting real data.
+
+Do not invent an activation metric or mandatory step. Ask when the product decision is absent.
+
+## Shape the shortest safe path
+
+- Start in context, preferably where the product will be used, rather than a detached tour.
+- Ask only for information needed for the next meaningful action.
+- Explain permissions immediately before requesting them and provide a retry/recovery path.
+- Use real previews or safe sample data when it reduces uncertainty; label it clearly.
+- Preserve progress, support resume, and make optional steps skippable.
+- Distinguish first-use empty state from a filtered/no-results state.
+- End at the activated product surface with a clear next action, not a celebratory dead end.
+
+Use existing Seven Stepper, Form, Alert, Dialog, Progress, Skeleton, EmptyState, Button, and navigation contracts where available. Missing components/variants are Seven gaps, not permission for raw local substitutes.
+
+## State matrix
+
+Cover new, returning-incomplete, invitation, permission-denied, integration-waiting, validation-error, partial-success, complete, and abandoned/resumed states. Include keyboard, screen-reader, mobile, reduced-motion, and long-copy behavior.
+
+## Verify
+
+Measure steps to first value, avoid duplicate data entry, test refresh/back/retry, and prove the user can recover without support. Run Seven checks and relevant E2E paths. Report assumptions that still need product validation.

package/.claude/skills/seven/reference/optimize.md

@@ -0,0 +1,34 @@
+# Optimize — measured UI performance
+
+Improve measured and perceived performance without changing product behavior or sacrificing accessibility and Seven fidelity.
+
+## Establish a baseline
+
+Measure the real target and record environment, viewport, data size, cache state, and build mode. Use evidence appropriate to the problem:
+
+- browser performance trace and React Profiler;
+- LCP, INP, CLS, long tasks, layout/recalc cost, and interaction latency;
+- JavaScript/CSS bundle analysis and route chunks;
+- image/font requests, transfer size, decoding, and cache behavior;
+- render counts and expensive computations under realistic data;
+- memory growth during repeated navigation or live updates.
+
+Do not optimize from intuition or a synthetic score alone.
+
+## Fix the dominant cost
+
+- Remove work before memoizing it.
+- Keep state local, selectors narrow, and stable references where measurement proves rerender cost.
+- Lazy-load route/feature code and heavy assets at a meaningful boundary; do not create waterfalls.
+- Size and compress images, set dimensions, use responsive sources, and defer offscreen media.
+- Load only used font weights; keep fallback metrics compatible.
+- Virtualize only lists whose measured size warrants it, while preserving keyboard and screen-reader access.
+- Move CPU-heavy deterministic work off the render path or into a worker when justified.
+- Pause invisible animation, polling, canvas, and observers.
+- Preserve Skeleton/Spinner semantics and avoid hiding real latency behind excessive choreography.
+
+React 19 patterns must match the consumer architecture. Do not add `useMemo`, `memo`, Suspense, a worker, or a dependency speculatively.
+
+## Verify
+
+Repeat the same measurement at least three times and compare medians. Confirm no visual, keyboard, focus, screen-reader, loading, error, or data-freshness regression. Report before/after numbers, variance, remaining bottleneck, and test scope.

package/.claude/skills/seven/reference/overdrive.md

@@ -0,0 +1,32 @@
+# Overdrive — one justified technical leap
+
+Apply a single high-ambition enhancement only after the surface is already sound. The technique must create a product outcome users can feel, not advertise implementation novelty.
+
+## Admission test
+
+Proceed only when all are true:
+
+- context, core flow, accessibility, responsive behavior, and Seven checks are healthy;
+- one specific opportunity has a measurable user benefit;
+- simpler Seven-native approaches cannot deliver the same result;
+- the target browsers/devices and performance budget are known;
+- the user explicitly approves any new dependency, experimental browser API, generated asset, or meaningful maintenance burden.
+
+Otherwise route to `polish`, `harden`, or `optimize`.
+
+## Suitable outcomes
+
+- spatial continuity that makes a complex state transition immediately understandable;
+- virtualization or worker-backed computation that keeps a large operational surface responsive;
+- a high-density visualization that remains accessible and useful at real data scale;
+- a reversible, progressive enhancement that materially reduces time or error in the primary job.
+
+Marketing spectacle, shaders, parallax, audio, device APIs, and cinematic scroll are not defaults for Seven product surfaces. They require explicit product/brand context and a fallback that remains complete.
+
+## Engineering contract
+
+Define baseline, target metric, supported matrix, fallback, reduced-motion behavior, failure mode, cleanup/lifecycle, and removal plan before coding. Isolate the enhancement behind a small boundary. Keep Seven components/tokens as the visible control language.
+
+## Verify
+
+Test the baseline and enhanced paths on representative mid-range hardware, interruption/repeat use, keyboard/screen reader, reduced motion, slow network, unsupported browser, and runtime failure. Ship only if the measured gain survives those paths and the plain fallback remains good.

package/.claude/skills/seven/reference/polish.md

@@ -19,12 +19,12 @@ Every polish finding falls into one of three buckets. Name the bucket in your fi
 1. **Run the detector first**:
 
    ```bash
-   npx seven detect <path>
+   node .claude/skills/seven/scripts/run-seven.mjs check --file <path>
    ```
 
    The deterministic findings cover token drift and identity-level violations. Address them before manual review.
 
-2. **Read the implementation alongside the matching Figma node.** If there is no Figma node for the variant, flag it as a "variant invented in code" finding; do not silently align to whatever the code already does.
+2. **Read the implementation against the exact installed registry metadata and component API.** If the variant is absent, flag it as a "variant invented in code" finding; do not reach into Figma or a newer release from a consumer project.
 
 3. **Manual review pass** covering:
    - Spacing rhythm (vary intentionally; same padding everywhere reads flat).
@@ -43,13 +43,13 @@ Every polish finding falls into one of three buckets. Name the bucket in your fi
 
 ## What polish never does
 
-- Add new variants that do not exist in Figma. Surface the gap, do not invent.
+- Add new variants that do not exist in the installed Seven contract. Surface the gap, do not invent.
 - Refactor unrelated code because it "looks bad". Surgical changes only.
 - Change public component APIs. If a prop should change, that is a separate proposal, not polish.
-- Touch `packages/tokens/sources/`. Token changes flow from Figma via the figma-sync skill, not from polish.
+- Define or override visual tokens in the consumer. Token changes belong in the Seven repository and a new release, not in polish.
 
 ## Refusals
 
 - "Refactor the whole file while you are in there" — Polish is surgical. Document the additional issues as a follow-up, do not bundle them.
 - "Add a fancy hover state to make it pop" — Seven hover is the tactile press. Adding decorative hover is drift. Surface and decline.
-- "Replace the import with a custom component because the variant is missing" — That is a Figma variant request. Document it, ask the user, do not duplicate.
+- "Replace the import with a custom component because the variant is missing" — That is a Seven contract request. Document it, ask the user, do not duplicate.

package/.claude/skills/seven/reference/product.md

@@ -38,8 +38,6 @@ Surface the conflict, do not silently comply.
 - "Add a glow under the active row" — Seven does not use glow on chrome. Recommend a brand-tinted background or a left-accent rule that is part of the row's structure, not a decorative halo.
 - "Show this metric in a gradient" — Seven prose forbids gradient text. The metric belongs in a solid `var(--foreground)` with hierarchy from scale and weight.
 
-## Sub-commands that apply
+## Workflows that apply
 
-All four Phase 1 sub-commands (`shape`, `audit`, `polish`, `clarify`) apply to product surfaces.
-
-For Phase 2 brand register surfaces, load [reference/brand.md](brand.md) instead. The shared design laws in `SKILL.md` apply to both.
+Every Seven workflow may apply to product surfaces when its stated preconditions are met. Load [reference/brand.md](brand.md) only for public marketing/storytelling surfaces. The shared design laws and installed release authority apply to both registers.

package/.claude/skills/seven/reference/quieter.md

@@ -0,0 +1,31 @@
+# Quieter — less noise, preserved hierarchy
+
+Reduce visual intensity without turning the interface into undifferentiated grey UI.
+
+## Find the noise
+
+Inspect the rendered surface and identify evidence, not adjectives:
+
+- too many filled actions or semantic colors;
+- repeated cards, borders, badges, icons, labels, or dividers that convey no new hierarchy;
+- competing font weights and size jumps;
+- decorative motion, gradients, glow, stripes, shadows, or hover transforms;
+- dense metadata presented at the same priority as the primary task;
+- multiple simultaneous attention anchors.
+
+Name the one or two elements that must remain prominent.
+
+## Reduce with Seven roles
+
+- Keep the true primary action; demote siblings to declared secondary, outline, ghost, or link variants.
+- Replace decorative color with `background`, `surface`, `muted`, `border`, and foreground roles already present in Seven.
+- Remove nested cards and use spacing or a divider when grouping is enough.
+- Keep borders for hierarchy and shadows only for overlays.
+- Reduce decorative motion; retain state feedback and focus visibility.
+- Collapse repeated explanatory copy while preserving information required for safe decisions.
+
+Do not change token values, lower contrast below WCAG AA, make targets smaller, remove status meaning, or invent a “subtle” local palette.
+
+## Verification
+
+The primary task remains obvious; semantic states remain distinguishable without color alone; keyboard/focus behavior is unchanged; and all changed files pass Seven checks. Report what was removed, what stayed intentionally strong, and why.

package/.claude/skills/seven/reference/routing.md

@@ -0,0 +1,28 @@
+# No-argument routing
+
+Use this workflow when Seven is invoked without an intent. Do not dump a generic command list first and do not auto-run a workflow.
+
+1. Load the normal Seven context.
+2. Run once:
+
+   ```bash
+   node .claude/skills/seven/scripts/context-signals.mjs --target <target>
+   ```
+
+3. Recommend the two or three highest-value next workflows with the exact invocation and one evidence-based reason each.
+
+Route by current evidence:
+
+- Missing or placeholder product context: lead with `/seven setup`.
+- A new feature with unresolved job, states, or architecture: `shape`.
+- Repetition across two or more real surfaces: `extract`.
+- No persisted critique for a rendered surface: `critique`.
+- A recent critique with P0/P1 findings: `polish` for an agreed fix scope, or `critique` again if the implementation materially changed.
+- Changed UI files: scope `audit`, `critique`, or `polish` to those files instead of the whole project.
+- Excessive detector findings: use the workflow matching the root cause (`typeset`, `layout`, `colorize`, `quieter`, `harden`) rather than recommending every repair command.
+- An existing `live.session` or a running local dev surface: `live` is available. Do not lead with it when no dev surface can run.
+- A sound surface whose measured performance is weak: `optimize`.
+
+Then show the remaining workflows grouped as: establish context, build/structure, evaluate, refine, validate/operate. A recommendation is a suggestion; wait for the user's choice before mutating files.
+
+If `update.notify` is true, keep the release update separate from the workflow recommendation. Never let maintenance displace the requested product work.

package/.claude/skills/seven/reference/setup.md

@@ -0,0 +1,38 @@
+# Setup — capture UI context
+
+Capture the facts later Seven workflows need. This is the skill-level setup workflow; the CLI subcommand `seven init` installs Seven, while product and surface context are written with `seven onboard`. Execute CLI subcommands through the installed `run-seven.mjs` path shown below.
+
+## Boundaries
+
+- Product context owns users, jobs, critical workflows, voice, accessibility needs, constraints, and non-goals.
+- Surface briefs own behavior, states, data ranges, responsive constraints, and known risks for one target.
+- Neither file may define colors, fonts, radii, shadows, spacing scales, component variants, or alternate UI primitives.
+- Never create a consumer `DESIGN.md`. The installed Seven release is the visual authority.
+
+## Workflow
+
+1. Run `node .claude/skills/seven/scripts/run-seven.mjs doctor --quick`. If Seven is not installed, instruct the user to install the exact desired `@etus/seven` release and invoke its `seven init` CLI subcommand.
+2. Read existing product/project/surface context. Preserve confirmed facts; do not overwrite mature context without `--force` and explicit review.
+3. Ask only for facts that remain unknown. At minimum establish:
+   - product name and primary users;
+   - job to be done and critical workflows;
+   - product voice and domain vocabulary;
+   - product-specific accessibility needs;
+   - technical/business constraints and explicit non-goals;
+   - owner responsible for freshness.
+4. For a monorepo, identify the app root and its product context. For a surface, identify target paths and complete the state matrix: idle, loading, empty, error, success, disabled, permission-limited, and content extremes.
+5. Write through the CLI:
+
+   ```bash
+   node .claude/skills/seven/scripts/run-seven.mjs onboard --name "..." --users "..." --job "..." --workflows "..." \
+     --voice "..." --accessibility "..." --constraints "..." --owner "..."
+   node .claude/skills/seven/scripts/run-seven.mjs onboard --surface <id> --target <path-or-glob> --purpose "..." \
+     --states "..." --data "..." --responsive "..." --accessibility "..." \
+     --primary-action "..." --owner "..."
+   ```
+
+6. Reload context for the target and prove the expected app and surface resolve.
+
+## Completion
+
+Report which facts came from the user, which existing files were retained, which context paths changed, and any unresolved product decision. Do not start a UI implementation while a material product decision is still being guessed.

package/.claude/skills/seven/reference/shape.md

@@ -4,7 +4,7 @@ Shape the UX of a feature before any code is written. This command produces a **
 
 **Scope**: design planning only. Shape does not write code. It produces the thinking that makes code good.
 
-**Output**: a design brief that can be handed off to a downstream command (`polish`, `audit`, or freeform implementation by Claude). For product surfaces, the brief is text-only. Visual probes and image generation are deferred to Phase 2.
+**Output**: a design brief that can be handed off to a downstream command (`polish`, `audit`, or implementation by Claude). When a materially ambiguous visual decision remains, read [visual-probes.md](visual-probes.md); probes never authorize tokens, components, or variants outside Seven.
 
 ## Philosophy
 
@@ -18,7 +18,7 @@ Do not write code or commit design decisions during this phase. use the AskUserQ
 
 - 2-3 questions per round. Stop and wait for answers.
 - One round is the default. Add a second only if the first leaves material gaps.
-- Use `PRODUCT.md` and `DESIGN.md` as anchors; they reduce repeated questions but do not replace shape for a specific task.
+- Use `PRODUCT.md`, `.seven/project.yml`, the release lock, and the matched surface brief as anchors. Never use a consumer `DESIGN.md` as visual authority.
 - **Assert-then-confirm**, not menu-with-escape. When `PRODUCT.md` makes one path obvious, name it and ask the user to confirm or override. Avoid four-option menus when the answer is already clear.
 
 ### Purpose and context
@@ -39,7 +39,7 @@ Do not write code or commit design decisions during this phase. use the AskUserQ
 
 For Seven, register is almost always `product`. Confirm once:
 
-- Is this an app/admin/dashboard surface (product) or a marketing surface (brand, Phase 2)?
+- Is this an app/admin/dashboard surface (`product`) or a public marketing/storytelling surface (`brand`)?
 - What is the surface type? Page, panel, dialog, popover, table row, empty state, navigation.
 
 ### Scope
@@ -68,7 +68,7 @@ After discovery, write a short brief (under one page) covering:
 1. **Surface description** in one sentence.
 2. **Register and scope** confirmed.
 3. **Component reuse plan**: which `@etus/ui` components are already in the surface. Which are missing.
-4. **Variant inventory**: for each component, which variant. If a variant is missing from `@etus/ui` and Figma, flag it explicitly; do not invent.
+4. **Variant inventory**: for each component, which variant. If a variant is missing from the exact installed registry contract, flag it explicitly; do not invent or reach into a newer release.
 5. **State matrix**: idle, loading, empty, error, success, disabled. For each state, the visual approach.
 6. **Token plan**: which `@etus/tokens` variables compose the surface. Call out any place a token is missing and a hex would be needed; surface that as a question, do not invent.
 7. **Copy direction**: pt-BR examples for labels, buttons, empty state, errors. Sentence case, no trailing periods, imperative leads.
@@ -82,4 +82,4 @@ After discovery, write a short brief (under one page) covering:
 ## Refusals
 
 - "Just write the code, skip the brief" — Shape exists because skipping the brief produces generic output. Offer a 5-minute Quick Shape (3 questions instead of 8) as a middle ground; do not skip entirely.
-- "Generate three visual variants" — Phase 1 product shape is text-only. Phase 2 will add visual probes for brand surfaces. Surface this and proceed with the text brief.
+- "Generate three visual variants" — Do so only when the decision is genuinely visual and the user asks. Keep the same Seven token/component authority in every probe, label the decision being tested, and discard probes that do not answer it.

package/.claude/skills/seven/reference/spatial-design.md

@@ -25,7 +25,7 @@ Seven runs two radius stacks. They are not interchangeable. Mixing them within t
 - Avatar triggers in the topbar (round avatars).
 - Status indicators (dots and pills).
 
-Never pill on buttons. Buttons stay on the component scale. The detector ships a `pill-on-button` rule (Phase 2) that catches drift.
+Never pill on buttons. Buttons stay on the component scale. The detector ships a `pill-on-button` rule that catches drift.
 
 ## Spacing
 
@@ -41,7 +41,7 @@ Borders carry hierarchy in Seven, not shadows.
 
 - 1 px `var(--border)` is the workhorse. Cards, inputs, dividers, table rows all use it.
 - 2 px borders are reserved for focus and active states (4 px on focus rings).
-- Side-stripe borders (`border-left` or `border-right` greater than 1 px as a colored accent) are banned. The detector ships a `side-stripe-border` rule (Phase 2). Use full borders, background tints, leading icons, or restructure the element.
+- Side-stripe borders (`border-left` or `border-right` greater than 1 px as a colored accent) are banned. The detector ships a `side-stripe-border` rule. Use full borders, background tints, leading icons, or restructure the element.
 
 ## Shadows
 
@@ -56,5 +56,5 @@ Card chrome uses borders, not shadows. If a card needs more weight, deepen the b
 ## Refusals
 
 - "Add a soft shadow under the card" — Seven cards use borders for hierarchy. Suggest a tinted background or a 2 px accent border. If the user insists, document the deviation in the audit.
-- "Use a 16 px radius on the button" — Surface scale on a button reads as a chip from a different design system. Recommend `md 8` or surface as a variant request to Figma.
+- "Use a 16 px radius on the button" — Surface scale on a button reads as a chip from a different design system. Recommend `md 8` or surface as a Seven component-contract request.
 - "Stack a card inside a card" — Nested cards are a Seven anti-pattern. Recommend a section divider, a labeled list, or a `Tabs` view instead.

package/.claude/skills/seven/reference/typeset.md

@@ -0,0 +1,28 @@
+# Typeset — Seven typography under stress
+
+Refine hierarchy, readability, and delivery using the installed Seven Text component roles, Inter, and JetBrains Mono. Read [typography.md](typography.md) first.
+
+## Two-pass assessment
+
+Keep these passes separate before synthesizing:
+
+1. Rendered typography: identify roles, hierarchy, reading measure, density, line breaks, numeric alignment, long pt-BR copy, zoom, and fallback behavior.
+2. Mechanical scan: run `node .claude/skills/seven/scripts/run-seven.mjs check --file <target>` and inspect arbitrary/dynamic styles the detector cannot resolve.
+
+For every claim, cite a component, selector, computed value, or screenshot state.
+
+## Apply
+
+- Use the fewest Text variants that make heading, body, label, metadata, and numeric roles unmistakable.
+- Reuse declared Text variants instead of rebuilding a type ramp with utilities.
+- Keep product body text at the Seven base role; dense captions must remain readable and cannot become body copy by volume.
+- Keep prose near 45–75 characters per line and adjust layout before inventing a font size.
+- Use tabular figures for tables, KPIs, timestamps, and aligned numbers.
+- Preserve browser zoom and user font scaling. Test long words, names, values, and localization expansion.
+- Load only used Inter/JetBrains Mono assets and weights; avoid invisible text and disruptive metric changes.
+
+Never introduce another font family, letter spacing for generic labels, extreme negative tracking, all-caps body copy, oversized H1s, or arbitrary scale values. A missing role is a Seven contract gap.
+
+## Verify
+
+Confirm hierarchy without reading the words, long-content wrapping, 200% zoom, narrow containers, dark mode, and final detector output. Report each Text variant used and any unresolved contract gap.

package/.claude/skills/seven/reference/typography.md

@@ -34,7 +34,7 @@ Inter ships tabular figures via the `tnum` feature. Apply `font-feature-settings
 
 ## Display surfaces
 
-Display typography (hero headings, marketing pages) follows the brand register, not product. Phase 2 brand layer documents Display rules; for Phase 1 product chrome, do not call out Display.
+Display typography (hero headings and marketing pages) follows the brand register in [brand.md](brand.md), not product chrome. Do not import display treatment into application UI.
 
 ## Refusals
 

package/.claude/skills/seven/reference/visual-probes.md

@@ -0,0 +1,36 @@
+# Visual probes
+
+Use probes only when a real product decision remains visually ambiguous after context and component-contract inspection. A probe answers one named question; it is not a license for arbitrary redesign.
+
+## Contract
+
+- Keep the product job, information, behavior, states, content, and accessibility target constant across directions.
+- Use the exact installed Seven components, declared variants, tokens, icon system, typography, radii, and motion language in every direction.
+- Vary one decision family at a time: hierarchy, density, composition, disclosure, emphasis, or responsive reflow.
+- Produce one strong default when evidence points clearly to it. Produce up to three directions only when comparison creates information.
+- Label each direction by its tradeoff, not by generic adjectives such as "modern" or "clean".
+- State what would falsify each direction and which user/job it benefits.
+
+## Direction shape
+
+For every probe record:
+
+1. decision being tested;
+2. hypothesis and affected user job;
+3. composition/component changes;
+4. Seven contracts reused;
+5. behavior across mobile, desktop, keyboard, reduced motion, loading, empty, error, and long-content cases;
+6. cost/risk;
+7. verification criterion.
+
+In Live Mode, deliver inert HTML/CSS previews only. Outside Live Mode, prefer a concise written probe or throwaway local mock; do not leave exploration code in production paths.
+
+## Anti-patterns
+
+- Three variants that differ only by color, radius, or decoration.
+- A "bold" direction that introduces tokens or variants absent from Seven.
+- Comparing different content/data while claiming to compare layout.
+- Selecting the most visually novel direction without product evidence.
+- Treating accepted browser DOM as source code.
+
+Finish with one recommendation and the evidence that selects it. If no direction is defensible, return to `shape` rather than averaging them.