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

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

@@ -0,0 +1,31 @@
+# Animate — motion with a job
+
+Add motion only when it explains feedback, state, hierarchy, or spatial continuity. Read [motion-design.md](motion-design.md) completely before editing.
+
+## Motion thesis
+
+Before implementation, identify:
+
+- the state or relationship that is currently hard to understand;
+- the smallest motion that would clarify it;
+- frequency, interruption behavior, and performance budget;
+- reduced-motion equivalent;
+- the existing Seven component or motion token that owns the behavior.
+
+If removing the animation would lose no meaning or confidence, do not add it.
+
+## Seven constraints
+
+- Routine feedback uses `var(--duration-fast)`; normal transitions use `var(--duration-normal)`; bounded surface entries may use `var(--duration-slow)`.
+- Use `var(--ease-default)` or the documented Seven exit/entry easing. No bounce, spring, elastic, wiggle, marquee, pulsing chrome, or decorative looping.
+- Animate transform and opacity by default. Do not animate width, height, top, left, margin, or other layout-driving properties.
+- Preserve content visibility in the non-enhanced state.
+- Use the existing tactile micro-press. Do not layer a second hover-lift language over it.
+- Loading is a Seven Skeleton or Spinner appropriate to the region, not a bespoke animation.
+- Reduced motion must keep state changes perceivable with near-instant transitions.
+
+Do not add a motion dependency for behavior the current stack or Seven component already provides. Any new dependency or browser API with partial support requires explicit user approval and a functional fallback.
+
+## Verify
+
+Exercise repeated triggers, interruption, rapid reversal, keyboard activation, reduced motion, background-tab behavior, and a representative mid-range device. Confirm no layout shift, hidden-at-rest content, or long-task illusion. Run Seven checks and relevant interaction tests.

package/.claude/skills/seven/reference/app-shell.md

@@ -2,15 +2,36 @@
 
 The Seven application shell. Source of truth: Figma "Core Components — Seven", Sidebar set `2472:372` and Topbar set `1403:15038`. When the project has `@etus/ui`, compose `<Sidebar>` / `<Topbar>` from the package — never reimplement. When prototyping without the package, reproduce the nominal values below exactly.
 
-## The two laws that kill most drift
+## The three laws that kill most drift
 
 1. **Chrome has no outline.** Sidebar and topbar have **no border and no shadow** — they sit on the same `var(--surface)` (#fafafa) plane. The ONLY divider in the shell is the **`border-left` of the secondary panel** (1 px `var(--border)`), owned by the panel, not the rail. Never add `border-r` to the sidebar or `border-b` to the topbar.
 2. **Chrome is surface, controls are white cards.** The shell background is `var(--surface)`, never white. Interactive controls INSIDE the chrome (selects, search, account switch, toggles) are white cards: `bg-[color:var(--background)]` + 1 px `var(--input)`/`var(--border)` + `rounded-[var(--radius-md)]` (8 px). That contrast — flat grey chrome, bordered white controls — is the Seven shell signature.
+3. **The shell is L-shaped, never T-shaped.** `Sidebar` and `SidebarInset` are siblings inside one `SidebarProvider`; `Topbar` is the first chrome child inside `SidebarInset`, so it starts at the sidebar's right edge instead of spanning above it. Never place `Topbar` outside the provider/inset, wrap it above both columns, or recreate the sidebar offset with `ml-*`, `pl-*`, `left-*`, `width: calc(...)`, or duplicated layout state.
+
+```text
+┌──────────┬──────────────────────────────┐
+│ Sidebar  │ Topbar                      │
+│ full     ├──────────────────────────────┤
+│ height   │ Content                     │
+└──────────┴──────────────────────────────┘
+```
 
-## Sidebar (4 states)
+## Sidebar state model
 
 All states: `bg-[color:var(--surface)]`, padding `12px` horizontal / `24px` vertical, column layout with `justify-between` (top group / bottom group). No border, no shadow.
 
+The provider has three independent state owners. Do not mirror or derive one
+from another:
+
+| State          | Owns              | Required behavior                                                                                    |
+| -------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `open`         | Desktop panel     | `single`: 200↔64px by default. `dual`: shows/hides only the 216px secondary panel.                   |
+| `openMobile`   | Sheet below 768px | Starts closed. `SidebarTrigger.aria-expanded` must read this state on mobile, never `open`.          |
+| `railExpanded` | Dual Rail overlay | Transient. Effective state is hover **OR** focus-within; Escape dismisses it. It is never persisted. |
+
+`mode` defaults to `single`. `collapsible` defaults to `icon`; `offcanvas` is
+explicit opt-in and `none` is static. There is no undefined "legacy" third mode.
+
 | State                | Width                                 | Notes                                                                                      |
 | -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
 | Collapsed (rail)     | **64 px**                             | icons only                                                                                 |
@@ -20,7 +41,18 @@ All states: `bg-[color:var(--surface)]`, padding `12px` horizontal / `24px` vert
 
 Rail contents (top→bottom): Logo 32×32 (icon 24) · AccountSwitch · nav items (gap 20) · … · color-mode toggle (pill 36×24, track `var(--muted)`, white 20 px knob, 12 px icon) · settings item · Avatar 32.
 
-- **Rail item**: 36×36 (20 px Lucide icon + 8 px padding), radius **4 px** (component `sm`). Active: `bg-[color:var(--primary)]` (mint) with dark foreground icon. Expanded item fills the rail width (176 px inside the 200 px rail).
+- **Rail item**: 36×36 (20 px Lucide icon + 8 px padding), radius **4 px** (component `sm`). Active/hover colors come from `--sidebar-rail-item-bg-hover` and `--sidebar-rail-item-fg-active`. Expanded item fills the rail width (176 px inside the 200 px rail).
+- Every `SidebarRailButton` has a non-empty `label`. The primitive emits it as
+  `aria-label` + `data-label`, shows it as text only while expanded, and hides
+  the tooltip while expanded. An icon-only button without `label` is invalid.
+- Navigation is one interactive element:
+  `<SidebarRailButton asChild label="Relatórios"><Link … /></SidebarRailButton>`.
+  Never render `<Link><SidebarRailButton /></Link>`.
+- Hover and keyboard focus are simultaneous sources. `mouseleave` does not
+  collapse while focus remains inside; `focusout` does not collapse while the
+  pointer remains over the Rail.
+- `SidebarRail` (without `Content`) is the thin click target that toggles the
+  panel. It is not draggable and does not resize.
 - **AccountSwitch**: white card, 1 px `var(--input)`, radius 8; brand logo 24×24 radius 4. Collapsed: logo only (px 8). Expanded: logo + account name (16 px, `var(--muted-foreground)`) + ChevronsUpDown 16.
 
 ### Secondary panel (216 px)
@@ -48,23 +80,73 @@ The page content sits next to/below the chrome as **cards on the canvas** — wh
 ## @etus/ui mapping
 
 ```tsx
+import { LayoutDashboard } from "lucide-react";
 import {
-  Sidebar, SidebarProvider, SidebarRailContent, SidebarRailButton,
-  SidebarPanelContent, SidebarPanelItem, SidebarPanelGroup,
-  Topbar, TopbarLeading, TopbarTrailing,
-} from "@etus/ui"
-
-<SidebarProvider mode="dual">           {/* rail + secondary panel */}
+  Sidebar,
+  SidebarProvider,
+  SidebarRailContent,
+  SidebarRailButton,
+  SidebarPanelContent,
+  SidebarPanelItem,
+  SidebarPanelGroup,
+  SidebarInset,
+  SidebarTrigger,
+  Topbar,
+  TopbarLeading,
+  TopbarTrailing,
+} from "@etus/ui";
+
+<SidebarProvider mode="dual">
+  {" "}
+  {/* rail + secondary panel */}
   <Sidebar>
-    <SidebarRailContent>…</SidebarRailContent>      {/* borderless; expands on hover as overlay */}
-    <SidebarPanelContent>…</SidebarPanelContent>    {/* carries the border-l divider */}
+    <SidebarRailContent>
+      {" "}
+      {/* borderless; expands on hover/focus as overlay */}
+      <SidebarRailButton asChild label="Visão geral" tooltip="Visão geral">
+        <a href="/">
+          <LayoutDashboard />
+        </a>
+      </SidebarRailButton>
+    </SidebarRailContent>
+    <SidebarPanelContent>…</SidebarPanelContent>{" "}
+    {/* carries the border-l divider */}
   </Sidebar>
-</SidebarProvider>
-
-<Topbar variant="default">              {/* or "filters" */}
-  <TopbarLeading>{/* Breadcrumb */}</TopbarLeading>
-  <TopbarTrailing>{/* filters + search/bell toggles */}</TopbarTrailing>
-</Topbar>
+  <SidebarInset>
+    <Topbar variant="default">
+      {" "}
+      {/* or "filters"; never border/shadow */}
+      <TopbarLeading>
+        <SidebarTrigger className="md:hidden" />{" "}
+        {/* opens the Sheet below 768px */}
+        {/* Breadcrumb */}
+      </TopbarLeading>
+      <TopbarTrailing>{/* filters + search/bell toggles */}</TopbarTrailing>
+    </Topbar>
+    <main>{/* bordered/rounded content surface */}</main>
+  </SidebarInset>
+</SidebarProvider>;
 ```
 
-`mode="single"` renders the classic one-panel sidebar (also borderless). Copy in pt-BR: `Visão Geral`, `Configurações`, `Buscar...`, `Tema Claro`.
+`mode="single"` renders the classic one-panel sidebar (also borderless), and is
+the runtime default. Its default collapse is `icon` (200→64px).
+`collapsible="none"` is the only case that does not need a trigger because the
+sidebar never becomes hidden. In every collapsible shell, the mobile trigger
+belongs in `TopbarLeading`; a trigger trapped inside the closed mobile Sheet
+cannot open it.
+
+Below 768 px, keep the trigger visible and collapse long breadcrumbs/actions to
+a current-page label or responsive menu. In `dual`, hide
+`SidebarRailContent`; render `SidebarPanelContent` expanded at 100% of the
+Sheet width regardless of desktop `open`. `TopbarLeading` must not overflow
+underneath `TopbarTrailing`; hiding the Sidebar while leaving desktop-only
+chrome wider than its slot still produces a broken mobile shell.
+
+The local detector rule `sidebar-topbar-shell` rejects a Topbar outside
+`SidebarInset`, a bordered/shadowed shell Topbar, the T-shaped rendered
+geometry, a collapsible mobile shell with no visible Topbar trigger, and
+overflowing mobile leading chrome. `sidebar-rail-behavior` rejects unlabeled
+Rail buttons, nested Link/button markup, mobile ARIA drift, and a collapsed or
+narrow panel inside an open mobile Sheet.
+
+Copy in pt-BR: `Visão Geral`, `Configurações`, `Buscar...`, `Tema Claro`.

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

@@ -45,7 +45,7 @@ Check for:
 - Pure `#000` and `#fff`. Detector rule: `pure-black-or-white`.
 - Tailwind v4 arbitrary values referencing color tokens without the `color:` hint. Detector rule: `missing-color-type-hint`.
 - Font-size or line-height arbitrary values without `length:`. Detector rule: `missing-length-type-hint`.
-- `leading-none` combined with `text-[length:var(--*)]`. Detector rule: `leading-none-with-length-var`.
+- `leading-none` combined with a typed length-variable text utility. Detector rule: `leading-none-with-length-var`.
 - Wrong token used: `var(--background)` where `var(--muted)` would have read better; mixing token families.
 - Dark mode visually broken: tokens that look fine in light fail at AAA contrast in dark, or vice versa.
 
@@ -68,7 +68,7 @@ Scoring: 0 = desktop-only, 1 = major issues, 2 = partial, 3 = good with minor is
 Run the deterministic detector against the surface or component:
 
 ```bash
-npx seven detect <path>
+node .claude/skills/seven/scripts/run-seven.mjs check --file <path>
 ```
 
 Then check the report against the Seven rule set:
@@ -79,15 +79,17 @@ Then check the report against the Seven rule set:
 | `hardcoded-color-not-token`    | Hex, rgb, hsl, OKLCH literal where a token exists                       |
 | `missing-color-type-hint`      | Tailwind v4 arbitrary color value missing the `color:` hint             |
 | `missing-length-type-hint`     | Tailwind v4 arbitrary length value missing the `length:` hint           |
-| `leading-none-with-length-var` | `leading-none` combined with `text-[length:var(--*)]`                   |
+| `leading-none-with-length-var` | `leading-none` combined with a typed length-variable text utility       |
 | `fuchsia-in-ui-chrome`         | Fuchsia color on UI chrome (allowed on `data-role="chart"` and `<svg>`) |
 | `pt-pt-vocab`                  | European Portuguese vocabulary in pt-BR surfaces                        |
 | `pure-black-or-white`          | `#000`, `#fff`, `rgb(0,0,0)`, `rgb(255,255,255)` in consumer code       |
 
-Deep detector rules also include `missing-tactile-press`, `radius-mixed-scales`, `pill-on-button`, `forbidden-em-dash`, `gradient-text-decorative`, `side-stripe-border`, `non-lucide-icon`, and `emoji-in-chrome`.
+Deep detector rules also include `missing-tactile-press`, `radius-mixed-scales`, `pill-on-button`, `forbidden-em-dash`, `gradient-text-decorative`, `side-stripe-border`, `non-lucide-icon`, `emoji-in-chrome`, `sidebar-topbar-shell`, and `sidebar-rail-behavior`.
 
 Scoring: 0 = five or more findings, 1 = three or four findings, 2 = one or two findings, 3 = clean detector pass, 4 = clean detector pass plus no additional manual issues evident in review.
 
+When a trusted development page is available, add rendered evidence with `node .claude/skills/seven/scripts/run-seven.mjs check <url>`. URL checks require the optional Puppeteer dependency and a compatible Chrome binary. If the package manager blocked Puppeteer's browser install script, report that activation requirement instead of pretending the rendered audit ran. Static file checks and the local pre-commit gate remain available without a browser.
+
 ## Report shape
 
 For each dimension, write:

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

@@ -0,0 +1,34 @@
+# Bolder — stronger hierarchy, same Seven
+
+Increase the conviction of one named target without redesigning its neighbors or adding a visual language the installed Seven release does not own.
+
+## Diagnose first
+
+Identify why the target reads weak:
+
+- competing primary actions;
+- every element using the same text role, surface, or density;
+- the target using a weaker variant than its job requires;
+- insufficient contrast between section, content, and supporting metadata;
+- the strongest Seven composition already used elsewhere but omitted here.
+
+State what must remain unchanged. If the scope is ambiguous, ask before editing.
+
+## Amplify with existing authority
+
+- Promote one element through an existing component variant, Text role, semantic token, or spatial role.
+- Reduce surrounding competition instead of making everything louder.
+- Use mint primary only for the true primary action or selected state; do not spread brand fill across unrelated surfaces.
+- Strengthen structure with grouping, alignment, scale, weight, and deliberate whitespace before adding decoration.
+- Preserve copy claims, interactions, accessible names, and state behavior.
+
+Never add a new color, font, shadow, radius, illustration style, variant, or arbitrary scale value. If the current Seven contract cannot express the needed hierarchy, stop and report the precise design-system gap.
+
+## Verification
+
+- Everything outside the agreed target is byte-for-byte or visually unchanged.
+- The primary job is recognizable in five seconds and keyboard order remains logical.
+- The target is unmistakably Seven, not a new visual identity.
+- `node .claude/skills/seven/scripts/run-seven.mjs check --file` passes for every changed UI file.
+
+Finish with `polish` only when the user asks for the broader final pass.

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

@@ -1,24 +1,31 @@
-# Brand register (Phase 2 stub)
+# Brand register
 
-Loaded when the surface is `brand`: marketing pages, campaign surfaces, long-form content, public-facing landing pages.
+Use for public-facing ETUS/Seven marketing, launch, campaign, and storytelling surfaces. The installed Seven release remains the visual authority; this register changes composition and emphasis, not tokens or component contracts.
 
-## Phase 1 status
+## Bar
 
-Phase 1 of Seven ships with the brand register as a stub. The Seven Design System itself is a product register: app UI, admin, dashboards, internal tools. Brand surfaces in Phase 1 fall back to the shared design laws in `SKILL.md` and the domain references (`typography`, `color-and-contrast`, `spatial-design`, `motion-design`, `ux-writing`).
+The surface should feel recognizably ETUS before the logo is read: direct, technically confident, energetic through mint/lime contrast, and disciplined enough that the product remains credible. Avoid the generic AI-marketing formula of eyebrow chip, oversized slogan, radial glow, gradient text, three equal feature cards, and repeated centered sections.
 
-If the user explicitly requests brand work and `BRAND.md` selects a brand name other than `etus`, Phase 2 will load the matching `reference/brands/<name>.md` here. Phase 2 also adds dedicated brand-register design laws (color strategy, visual direction probes, type display, scene-sentence for theme).
+## Composition
 
-## Bar (Phase 2 target)
+- Build a specific narrative: problem, concrete evidence, product mechanism, proof, action.
+- Use asymmetry or editorial pacing only when it improves the story and responsive reading order.
+- One focal visual idea is enough. Repeat a structural motif deliberately instead of adding unrelated decoration per section.
+- Use real product UI, data, customer evidence, or authored imagery. Do not ship placeholder browser mockups, abstract orb gradients, or icon-tile stacks as proof.
+- Keep calls to action scarce and hierarchical. One primary action per decision region.
 
-Distinctiveness. A brand surface should be recognizably ETUS at a glance, not "a SaaS landing page".
+## Seven identity
 
-## Defaults expected in Phase 2
+- Mint and lime are the brand pair. Use semantic Seven token roles; never hardcode the swatches or create campaign-local ramps.
+- Inter remains the typeface. Use the shipped display/heading roles where they exist; a campaign does not justify a new font.
+- Product screenshots and embedded controls retain product component styling. Do not repaint Seven UI to match a hero effect.
+- Motion may author one focal moment, but it obeys Seven tokens, reduced motion, performance budgets, and no bounce/looping-chrome rules.
+- Generated or third-party assets require provenance, appropriate license, alt text, responsive sizes, and explicit user approval before being added.
 
-- Wider type display lane (Inter Display weights, optical sizes).
-- Maximalist color strategy options (`Committed`, `Full palette`, `Drenched`) instead of the product default `Restrained`.
-- Editorial spacing rhythm (varied, intentional, breathing room).
-- Section-level scene sentences forcing dark vs light per surface, not per project.
+## Copy
 
-## Until Phase 2
+Lead with concrete outcomes and evidence. Avoid vague superlatives, aphoristic sentence fragments, marketing buzzwords, theater phrases, and unsupported claims. Public copy may be more expressive than product chrome but remains Brazilian Portuguese unless product context says otherwise.
 
-Apply the shared design laws and the domain references. Surface to the user that brand-register depth lands in Phase 2 of the port; do not invent Phase 2 features in Phase 1 brand work.
+## Verification
+
+Critique the narrative and rendered composition separately from the deterministic scan. Test mobile reading order, real content, dark/light behavior where supported, reduced motion, asset loading, SEO semantics, and conversion actions. Any needed visual primitive missing from Seven is a design-system proposal, not a local override.

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

@@ -6,7 +6,7 @@ Improve UX copy in Seven surfaces. Brazilian Portuguese, sentence case, no trail
 
 Clarify rewrites chrome copy: button text, labels, empty states, validation errors, toast messages, menu items, navigation, table column headers, breadcrumbs, tabs, badges, tooltips, dialog titles and descriptions.
 
-Clarify does not rewrite body prose, long-form content, or marketing copy. Those belong to the brand register (Phase 2).
+Clarify does not rewrite body prose, long-form content, or marketing copy unless the user explicitly includes them. Public-facing copy must also load the brand register.
 
 ## Rewrite rules
 
@@ -64,7 +64,7 @@ Sentence case across every chrome surface. Capitalize only the first word and pr
 3. Verify the rewrites against the detector's `pt-pt-vocab` rule:
 
    ```bash
-   npx seven detect <path>
+   node .claude/skills/seven/scripts/run-seven.mjs check --file <path>
    ```
 
 4. Write the rewrites as a diff or table; do not commit until the user confirms.

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

@@ -0,0 +1,31 @@
+# Colorize — semantic color, not a new palette
+
+Improve hierarchy and meaning with the semantic roles already shipped in the installed Seven release. Read [color-and-contrast.md](color-and-contrast.md) first.
+
+## Audit roles
+
+Map the target's current uses to:
+
+- canvas, surface, elevated surface, and muted regions;
+- primary/secondary foreground and border;
+- action, focus, selection, and active navigation;
+- destructive, warning, success, and information states;
+- chart-only series colors.
+
+Identify where grayscale obscures state, color has no meaning, status relies on color alone, or raw literals bypass Seven.
+
+## Apply
+
+- Use only known Seven CSS variables and declared component variants.
+- Reserve mint primary for the true action/selection hierarchy and lime for the existing secondary brand role.
+- Use semantic status tokens only for their meaning; do not use warning as decoration or destructive to manufacture urgency.
+- Pair color with text, icon, pattern, or accessible state where meaning would otherwise be color-only.
+- Keep body contrast at 4.5:1 and non-text/focus indicators at 3:1 in every supported theme.
+- Treat fuchsia as chart-only and keep chart color out of chrome.
+- Validate dark mode through computed values rather than copying a light-mode token into a local override.
+
+Never create a project palette, hardcode a Seven swatch, redefine a token, introduce a gradient, or use raw Tailwind palette utilities. If a semantic role is absent, report a Seven token gap.
+
+## Verify
+
+Run checks, inspect computed light/dark values, simulate common color-vision deficiencies where status is dense, and confirm all meaning remains available without color. Report which semantic roles changed and why.

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

@@ -0,0 +1,53 @@
+# Critique — visual and product judgment
+
+Critique a rendered Seven surface, prioritize what materially weakens it, and persist the result for later work. Critique reports by default; it does not edit unless the user separately authorizes a fix scope.
+
+## Keep two evidence lanes independent
+
+Do not let a lint finding predetermine the visual judgment.
+
+### Lane A — rendered assessment
+
+Inspect the real target at representative desktop and mobile widths, plus dark mode when supported. Use real product content when available. Record evidence for:
+
+- task clarity and primary-action hierarchy;
+- information architecture and reading order;
+- composition, density, alignment, rhythm, and use of space;
+- typography, semantic color, component/variant choice, and Seven identity;
+- interaction feedback, focus, keyboard path, and state continuity;
+- loading, empty, error, success, disabled, permissions, long copy, and large data;
+- responsive reflow, overflow, clipping, and touch affordances;
+- whether the surface feels specific to the product rather than generically generated.
+
+### Lane B — mechanical evidence
+
+Run `node .claude/skills/seven/scripts/run-seven.mjs check --file <target>` or `node .claude/skills/seven/scripts/run-seven.mjs check <url>` and relevant tests. Record rule IDs, files, lines, browser errors, and reproducible steps. A clean scan is a floor, not a visual endorsement.
+
+Only after both lanes are complete should you synthesize them.
+
+If the evidence supports multiple genuinely different corrections and the user asks to compare them, read [visual-probes.md](visual-probes.md). Keep critique reporting-only until a direction and edit scope are explicitly accepted.
+
+## Prioritization
+
+- **P0:** blocks the primary job, creates data loss/security risk, or makes the surface inaccessible.
+- **P1:** materially harms comprehension, completion, responsive use, or Seven consistency.
+- **P2:** meaningful quality or maintainability issue with a usable workaround.
+- **P3:** optional refinement; do not let it displace P0–P2 work.
+
+For each finding include: priority, concise title, evidence, affected user/job, Seven component/token/rule involved, root cause, recommended direction, and verification criterion. Separate facts from judgment.
+
+Score 0–100 only after findings are written: task clarity 25, hierarchy/composition 20, component/token fidelity 20, states/accessibility 20, responsiveness/performance 15. The score summarizes evidence; it never replaces it.
+
+## Persistence
+
+Persist the critique through:
+
+```bash
+node .claude/skills/seven/scripts/critique-storage.mjs write --target <target> --input <review.json>
+```
+
+The stored JSON must include `schemaVersion`, `createdAt`, `target`, `surface`, `release`, `score`, priority summary, evidence lanes, findings, and verification. The script also writes a readable Markdown sibling under `.seven/reviews/`. Never store screenshots or secrets there by default.
+
+## Completion
+
+Lead with the highest-priority findings, then the score and strengths worth preserving. Link the persisted review. Offer a scoped `polish` pass; do not begin it automatically.

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

@@ -0,0 +1,30 @@
+# Delight — useful product-specific detail
+
+Add a restrained moment that improves confidence, comprehension, recovery, or a sense of progress. Delight is not decoration and never outranks the primary job.
+
+## Find an earned moment
+
+Look for one of these:
+
+- a successful high-effort action that deserves clear acknowledgment;
+- a first-use moment where a concrete example removes uncertainty;
+- a transition whose continuity is currently confusing;
+- a dense workflow where a smart default or preview saves effort;
+- domain-specific microcopy or data formatting that makes the product feel attentive;
+- an empty state that can directly start the next action.
+
+State the user benefit in one sentence. If it is only “looks more fun,” stop.
+
+## Implement within Seven
+
+- Prefer better timing, copy, preview, progressive disclosure, saved context, or one purposeful microinteraction.
+- Use existing Seven components, icons, semantic tokens, and motion rules.
+- Keep feedback interruptible and non-blocking. Success must not make expert users wait.
+- Respect reduced motion, sound/autoplay preferences, and assistive technology announcements.
+- Make the detail work with real product data and adverse states, not only a demo value.
+
+No confetti, emoji chrome, random praise, hover gimmick, mascot, sound, glow, decorative loop, or generated illustration unless the product context explicitly earns it and the user approves the added asset/behavior.
+
+## Verify
+
+The detail should shorten a decision, clarify an outcome, or strengthen trust. Test repeat use, reduced motion, keyboard/screen reader behavior, and failure paths. Remove it if repetition turns it into friction.

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

@@ -0,0 +1,30 @@
+# Distill — remove until the job is clear
+
+Simplify a Seven surface by removing unnecessary decisions, duplication, and chrome while preserving the user's essential job and safe recovery paths.
+
+## Establish the irreducible job
+
+From product and surface context, write one sentence: “This surface helps [user] do [job] by [critical action].” Inventory every visible element and classify it as:
+
+- required to understand or complete the job;
+- required for safety, accessibility, trust, or recovery;
+- useful but secondary;
+- duplicated, premature, decorative, or unrelated.
+
+Do not treat “not primary” as permission to delete. Confirm analytics, permissions, legal text, and expert workflows before removing them.
+
+## Distillation order
+
+1. Remove exact duplicate labels, status, and actions.
+2. Merge redundant grouping; replace nested cards with hierarchy.
+3. Move secondary detail behind an existing disclosure pattern when discoverability remains adequate.
+4. Reduce choices by defining one primary action and clear defaults.
+5. Shorten copy with `clarify` rules.
+6. Remove decorative effects and motion that carry no state or relationship.
+7. Delete code, props, styles, and tests made unreachable by the approved removal.
+
+Do not create a vague “More” menu as a landfill, hide frequent actions, or erase empty/error/recovery states. Simplicity that forces more navigation or memory is not simpler.
+
+## Verify
+
+Compare task completion steps before and after, keyboard order, screen-reader names, mobile layout, and all state variants. Run focused tests and Seven checks. Report what was removed, what was retained for safety, and any product decision still requiring user approval.

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

@@ -0,0 +1,9 @@
+# Doctor
+
+Run `node .claude/skills/seven/scripts/run-seven.mjs doctor` to diagnose the consumer installation. Treat its checks as evidence, not a request to rewrite unrelated files.
+
+Inspect the exact release lock and hashes, generated policy, project config, React/Tailwind/tailwind-merge compatibility, package scripts, provider-native skill payloads, hook manifests, product/surface context freshness, exceptions, baseline, and forbidden `.github` artifacts attributable to Seven.
+
+`node .claude/skills/seven/scripts/run-seven.mjs add` refuses before any component write or dependency installation when initialization is incomplete or this release contract has drifted. Its `--force`, `--overwrite`, `--install`, and `--dry-run` flags never bypass that preflight. Diagnose first, repair release-owned artifacts with `node .claude/skills/seven/scripts/run-seven.mjs update` after review, then retry `add`.
+
+`node .claude/skills/seven/scripts/run-seven.mjs doctor --quick` is the pre-edit health check. The full doctor is the handoff check. Never repair malformed third-party JSON or overwrite modified Seven-owned files without explicit `--force` authorization.

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

@@ -0,0 +1,36 @@
+# Document — record Seven usage
+
+Document how an existing product surface consumes the exact installed Seven release. The output is descriptive and operational. It must never become a second visual authority.
+
+## Read first
+
+- `.seven/release.lock.json`, `.seven/project.yml`, `PRODUCT.md`, and the matched surface brief;
+- `node .claude/skills/seven/scripts/run-seven.mjs list` / `node .claude/skills/seven/scripts/run-seven.mjs info` for every referenced component;
+- representative source, tests, stories, and rendered states;
+- active exceptions and baseline entries.
+
+## Output contract
+
+Unless the user supplies a path, write under `docs/seven/`. Include:
+
+1. Exact Seven CLI/skill/registry versions and registry digest.
+2. Surface purpose, users, primary job, and critical states, linked back to the owning context files.
+3. Component inventory: Seven component, source import, declared variant, role in the surface, and relevant composition.
+4. Token roles actually used. Describe semantic roles, not raw values.
+5. Responsive and keyboard behavior.
+6. Loading, empty, error, success, disabled, permission, and long-content behavior.
+7. Known deviations: rule ID, file, owner, issue, expiry, and whether it is an exception or migration baseline.
+8. Verification commands and the date they last passed.
+
+Every example must compile against the current component API and pass `node .claude/skills/seven/scripts/run-seven.mjs check --file`. Delete stale examples rather than preserving history inside the canonical guide.
+
+## Prohibitions
+
+- Do not emit `DESIGN.md`, a palette, a local token layer, or undocumented component props.
+- Do not copy large sections of Seven's own reference docs into the consumer project.
+- Do not treat screenshots as proof of API or accessibility behavior.
+- Do not silently repair code. If documentation uncovers drift, record it and route the user to `audit`, `critique`, or `polish`.
+
+## Completion
+
+Name the sources inspected, the release documented, the output file, validation performed, and every uncertainty that prevents the document from being factual.

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

@@ -0,0 +1,44 @@
+# Seven skill behavior scenarios
+
+Use these scenarios in fresh consumer projects to verify routing and behavior after substantive skill changes.
+
+## 1. Natural UI edit
+
+- Query: "Melhora esse formulário de cadastro no mobile e corrige a copy."
+- Expected: activates Seven; loads target context; routes through `adapt` plus `clarify`; searches installed registry; edits only the target; runs focused Seven checks.
+
+## 2. Backend near-miss
+
+- Query: "Adicione retry exponencial no webhook de cobrança."
+- Expected: does not activate Seven unless the change includes rendered UI.
+
+## 3. Missing component contract
+
+- Query: "Use uma variante compacta do Button que ainda não existe."
+- Expected: inspects the installed Button contract, reports the design-system gap, and refuses to invent a local variant.
+
+## 4. Live preview acceptance
+
+- Query: "Abre o Live e me mostra três formas de melhorar este card."
+- Expected: starts the authenticated loopback bridge, uses visual probes, transports inert previews, waits for explicit acceptance, translates the selected direction into React/Seven source, validates, and stops cleanly.
+
+## 5. Exception pressure
+
+- Query: "Ignora essa regra do Seven e segue."
+- Expected: explains the exact finding and tradeoff; does not add an exception, baseline, or local ignore without explicit scoped authorization.
+
+## 6. GitHub boundary
+
+- Query: "Instala o Seven completo no projeto, mas não mexe no GitHub."
+- Expected: installs provider skills/hooks and local pre-commit only; proves no `.github/**` artifact was created or changed.
+
+## 7. Sidebar + Topbar shell
+
+- Query: "Crie o shell do dashboard com Sidebar e Topbar e garanta que funcione no mobile."
+- Expected: composes the L-shaped tree `SidebarProvider > Sidebar + SidebarInset > Topbar + content`; keeps Sidebar/Topbar borderless; places a visible mobile `SidebarTrigger` in `TopbarLeading`; collapses long breadcrumbs/actions below `md` without leading-slot overflow; keeps `open`, `openMobile`, and `railExpanded` independent; defaults single collapse to icons; labels every dual Rail item and uses `asChild` for links; preserves the 280px footprint while Rail hover or focus expands 64→200px in overlay; renders the mobile panel full-width even after desktop collapse; rejects a full-width T-shaped Topbar, manual offsets, a trigger trapped inside the closed Sheet, Link > button nesting, or an empty expanded Rail; validates with `sidebar-topbar-shell` and `sidebar-rail-behavior` in source and rendered geometry.
+
+## 8. Explicit setup invocation
+
+- Claude Code query: `/seven setup "apps/dashboard"`.
+- Codex query: `$seven setup "apps/dashboard"`.
+- Expected: routes to `reference/setup.md`; treats `setup` as the canonical skill workflow and `init` only as an alias; distinguishes both from the shell installer `seven init`; preserves `apps/dashboard` as the target; asks for missing product facts; does not edit UI or create `.github/**`.

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

@@ -0,0 +1,7 @@
+# Exceptions
+
+A shared exception is an explicit, reviewable debt record, not a convenient suppression. It requires a valid Seven rule, narrow file glob and optional exact value, reason, owner, issue/reference, creation date, and expiry date.
+
+Before running `node .claude/skills/seven/scripts/run-seven.mjs exceptions add`, show the proposed record and obtain explicit user authorization. Never silently renew an expired exception or broaden its file glob. Local hook ignores are not shared exceptions.
+
+Run `node .claude/skills/seven/scripts/run-seven.mjs exceptions validate` and `node .claude/skills/seven/scripts/run-seven.mjs doctor` after changes. Expired or malformed exceptions are findings and do not suppress the underlying violation.

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

@@ -0,0 +1,42 @@
+# Extract — reusable Seven compositions
+
+Extract genuinely repeated product UI into a reusable composition without cloning or weakening Seven primitives.
+
+## Decide whether extraction is earned
+
+Find at least two real call sites and compare:
+
+- shared user job and semantics;
+- shared component structure and state transitions;
+- variation that belongs in data/slots versus variation that would require a visual prop;
+- accessibility behavior and responsive behavior;
+- whether the registry already contains a component or block that solves it.
+
+Do not extract merely because markup looks similar. Similar cards with different jobs are not necessarily one abstraction. Do not create an abstraction for one call site.
+
+## Classification
+
+- **Seven primitive already exists:** replace the local implementation; do not extract.
+- **Project composition:** compose installed Seven components and keep it in the project's composition/feature layer.
+- **Candidate Seven block:** repeated across products, stable data contract, no product-specific business dependency. Document the proposal in the Seven repository; do not pretend the consumer-local version is canonical.
+- **Missing primitive/variant/token:** stop and surface a design-system gap. Never hide it behind a local visual prop.
+
+## Extraction contract
+
+1. Preserve public behavior and accessible names before moving code.
+2. Define a minimal domain-shaped data contract. Prefer slots only for meaningful composition points.
+3. Reuse declared Seven variants exactly; no `className` tunnel that permits callers to replace the visual system.
+4. Keep routing, fetching, mutations, and business state in the feature caller unless the composition owns that behavior by definition.
+5. Add tests that prove why the shared behavior matters across at least two call-site variants, including an adverse state.
+6. Migrate call sites one at a time and verify rendered parity plus `node .claude/skills/seven/scripts/run-seven.mjs check`.
+
+## Refuse
+
+- Boolean-prop matrices that encode unrelated layouts.
+- A “generic card” wrapper around every card.
+- Local forks of Button, Input, Dialog, Select, Table, or other Seven primitives.
+- New colors, radii, spacing values, animations, or undocumented variants.
+
+## Completion
+
+Report the call sites unified, why one abstraction is valid, the retained variation points, component contracts used, tests added, and whether anything should be proposed upstream to Seven.