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

package/.trae-cn/skills/seven/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: seven
 description: "Use for every UI task in a project governed by the Seven Design System: creating or editing React 19 components, pages, flows, layouts, styles, UX copy, responsive behavior, accessibility, visual critique, performance, hardening, documentation, reusable compositions, browser iteration, or final polish. Requires Seven context before edits, reuse of installed Seven components and declared variants, @etus/tokens-only visual values, pt-BR product voice, and deterministic Seven validation. Routes the complete Seven workflow catalog plus doctor, hooks, pins, and exceptions. Do not trigger for backend-only or infrastructure-only work."
-version: 0.1.0-beta.4
-argument-hint: "[intent] [target]"
+version: 0.1.0-beta.5
+argument-hint: "[setup|workflow] [target]"
 user-invocable: true
 license: Apache-2.0
 ---
@@ -11,24 +11,34 @@ license: Apache-2.0
 
 Builds production interfaces that stay inside the installed Seven release. This is not a visual inspiration prompt: Seven components, variants, tokens, interaction behavior, accessibility rules, and pt-BR voice are hard product constraints.
 
+## Invocation contract
+
+Interpret explicit invocations as `/seven <intent> [target]`: the first token selects a workflow and the remaining text scopes it. `setup` is the canonical skill workflow for capturing product, app, and surface context; `init` is retained only as a backward-compatible alias. The CLI subcommand `seven init` is different: it installs the Seven release and consumer governance.
+
+
+
+With no intent, use the no-argument router below. If the first token is not a known intent, show the valid workflows and ask for a choice; never silently substitute a different workflow.
+
+Always execute the project-pinned CLI as `node .trae-cn/skills/seven/scripts/run-seven.mjs ...`. The runner resolves the local `@etus/seven` package without depending on npm, pnpm, Yarn, Bun, `npx`, or a global binary.
+
 ## Mandatory loop for every UI task
 
 Before reading broadly or editing any UI file:
 
 1. Identify the exact target file, application, and surface.
-2. Load the consumer context once, in full:
+2. Load the resolved consumer context once:
 
    ```bash
    node .trae-cn/skills/seven/scripts/load-context.mjs --target path/to/target
    ```
 
-3. Read the returned `PRODUCT.md`, matched `.seven/project.yml` integration, release lock, and surface brief. If product context is missing or placeholder, ask the user directly for the missing product decision before editing UI. Do not invent users, workflow, tone, or product priorities.
+3. Read the returned `PRODUCT.md`, matched `.seven/project.yml` integration, compact release summary, and surface brief. The returned `artifactDigest` plus `artifactSummary` are sufficient when doctor is healthy; do not open the raw release lock or its per-file hashes unless doctor reports release drift or the active intent is `doctor`. If product context is missing or placeholder, ask the user directly for the missing product decision before editing UI. Do not invent users, workflow, tone, or product priorities.
    If the result contains `update.notify: true`, finish the requested work first and then mention the exact update command once. Never update the pinned Seven release implicitly.
-4. Run `seven doctor --quick --target path/to/target`. If the Seven release, provider artifacts, or policy is inconsistent, surface that drift before producing UI.
-5. Search the installed Seven registry before creating a primitive: `seven list <need>` and `seven info <component>`. Import or install the existing component. Do not rebuild it with raw HTML.
+4. Run `node .trae-cn/skills/seven/scripts/run-seven.mjs doctor --quick --target path/to/target`. If the Seven release, provider artifacts, or policy is inconsistent, surface that drift before producing UI.
+5. Search the installed Seven registry before creating a primitive: `node .trae-cn/skills/seven/scripts/run-seven.mjs list <need>` and `node .trae-cn/skills/seven/scripts/run-seven.mjs info <component>`. Import or install the existing component. Do not rebuild it with raw HTML.
 6. Inspect the selected component's public props and variants. If a required variant is absent, stop and surface a design-system gap. Seven allows no variants in code that do not exist in the shipped component contract.
 7. Make the smallest scoped change that satisfies the product job and all Seven rules.
-8. Run `seven check --file path/to/changed-file` for each UI file changed. Resolve errors and warnings. Advisory findings are design review input, not permission to silently redesign adjacent surfaces.
+8. Run `node .trae-cn/skills/seven/scripts/run-seven.mjs check --file path/to/changed-file` for each UI file changed. Resolve errors and warnings. Advisory findings are design review input, not permission to silently redesign adjacent surfaces.
 
 Never create or edit `.github/**` as part of this workflow. Seven governance is local to the consumer project; GitHub CI is outside this skill's scope.
 
@@ -110,9 +120,9 @@ See [reference/motion-design.md](reference/motion-design.md).
 
 ## Exceptions and baselines
 
-Do not add, broaden, renew, or suppress an exception on your own. Explain the exact rule, file/value, tradeoff, owner, issue, and expiry; then obtain explicit user authorization before running `seven exceptions add` or replacing a baseline.
+Do not add, broaden, renew, or suppress an exception on your own. Explain the exact rule, file/value, tradeoff, owner, issue, and expiry; then obtain explicit user authorization before running `node .trae-cn/skills/seven/scripts/run-seven.mjs exceptions add` or replacing a baseline.
 
-Local hook ignores only reduce machine-local agent noise. They do not change the shared `seven check` result. A migration baseline can shrink but must never grow implicitly.
+Local hook ignores only reduce machine-local agent noise. They do not change the shared `run-seven.mjs check` result. A migration baseline can shrink but must never grow implicitly.
 
 ## Intent routing
 
@@ -120,7 +130,8 @@ When invoked without an intent, read [reference/routing.md](reference/routing.md
 
 | Intent                               | Required reference                                 | Outcome                                                                                                       |
 | ------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `/seven init`       | [reference/init.md](reference/init.md)             | Capture product/app/surface context required by every later workflow                                          |
+| `/seven setup`      | [reference/setup.md](reference/setup.md)           | Capture product/app/surface context required by every later workflow                                          |
+| `/seven init`       | [reference/init.md](reference/init.md)             | Backward-compatible alias for the canonical `setup` skill workflow                                            |
 | `/seven shape`      | [reference/shape.md](reference/shape.md)           | Resolve product job, information architecture, component choices, states, and responsive behavior before code |
 | `/seven document`   | [reference/document.md](reference/document.md)     | Document how the project uses its exact Seven release without creating a competing visual authority           |
 | `/seven extract`    | [reference/extract.md](reference/extract.md)       | Extract repeated compositions while preserving Seven primitives, tokens, and public contracts                 |
@@ -131,7 +142,7 @@ When invoked without an intent, read [reference/routing.md](reference/routing.md
 | `/seven quieter`    | [reference/quieter.md](reference/quieter.md)       | Reduce visual noise without erasing hierarchy or Seven identity                                               |
 | `/seven distill`    | [reference/distill.md](reference/distill.md)       | Remove unnecessary UI, states, and decisions while preserving the core job                                    |
 | `/seven harden`     | [reference/harden.md](reference/harden.md)         | Complete accessibility, error, loading, empty, content-stress, and recovery behavior                          |
-| `/seven onboard`    | [reference/onboard.md](reference/onboard.md)       | Design first-run, setup, empty, and activation experiences; context capture belongs to `init`                 |
+| `/seven onboard`    | [reference/onboard.md](reference/onboard.md)       | Design first-run, setup, empty, and activation experiences; context capture belongs to the skill `setup`      |
 | `/seven animate`    | [reference/animate.md](reference/animate.md)       | Add only motion that explains feedback, state, or spatial continuity using Seven motion tokens                |
 | `/seven colorize`   | [reference/colorize.md](reference/colorize.md)     | Improve semantic color hierarchy using the installed Seven token roles only                                   |
 | `/seven typeset`    | [reference/typeset.md](reference/typeset.md)       | Refine typography with Seven Text roles, Inter, JetBrains Mono, measure, and content stress                   |
@@ -146,9 +157,9 @@ When invoked without an intent, read [reference/routing.md](reference/routing.md
 | `/seven hooks`      | [reference/hooks.md](reference/hooks.md)           | Inspect or manage local consumer agent hooks and machine-local noise controls                                 |
 | `/seven exceptions` | [reference/exceptions.md](reference/exceptions.md) | Manage explicit, owned, expiring shared waivers                                                               |
 
-When an intent is invoked, read its reference completely before acting. `audit` reports; it does not silently fix. `polish` may edit only the agreed target.
+When an intent is invoked, read its reference completely before acting. `setup` is canonical and `init` must delegate to it. `audit` reports; it does not silently fix. `polish` may edit only the agreed target.
 
-Use `seven pin <workflow>` to install a provider-native standalone shortcut and `seven unpin <workflow>` to remove only Seven-owned shortcuts. Pins never change policy and never create `.github/**`.
+Use `node .trae-cn/skills/seven/scripts/run-seven.mjs pin <workflow>` to install a provider-native standalone shortcut and `node .trae-cn/skills/seven/scripts/run-seven.mjs unpin <workflow>` to remove only Seven-owned shortcuts. Pins never change policy and never create `.github/**`.
 
 ## Completion evidence
 
@@ -157,7 +168,7 @@ A UI task is complete only when the response names:
 - the product/surface context used;
 - the existing Seven components and declared variants chosen;
 - the changed UI files;
-- the exact `seven check` scope and result;
+- the exact `run-seven.mjs check` scope and result;
 - any unresolved warning, advisory, missing contract, or user-authorized exception.
 
 Do not claim strict Seven compliance from visual resemblance, compilation alone, or a downloaded skill alone.

package/.trae-cn/skills/seven/reference/audit.md

@@ -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
-seven check --file <path>
+node .trae-cn/skills/seven/scripts/run-seven.mjs check --file <path>
 ```
 
 Then check the report against the Seven rule set:
@@ -88,7 +88,7 @@ Deep detector rules also include `missing-tactile-press`, `radius-mixed-scales`,
 
 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 `seven 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.
+When a trusted development page is available, add rendered evidence with `node .trae-cn/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
 

package/.trae-cn/skills/seven/reference/bolder.md

@@ -29,6 +29,6 @@ Never add a new color, font, shadow, radius, illustration style, variant, or arb
 - 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.
-- `seven check --file` passes for every changed UI file.
+- `node .trae-cn/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/.trae-cn/skills/seven/reference/clarify.md

@@ -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
-   seven check --file <path>
+   node .trae-cn/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/.trae-cn/skills/seven/reference/critique.md

@@ -21,7 +21,7 @@ Inspect the real target at representative desktop and mobile widths, plus dark m
 
 ### Lane B — mechanical evidence
 
-Run `seven check --file <target>` or `seven 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.
+Run `node .trae-cn/skills/seven/scripts/run-seven.mjs check --file <target>` or `node .trae-cn/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.
 

package/.trae-cn/skills/seven/reference/doctor.md

@@ -1,7 +1,9 @@
 # Doctor
 
-Run `seven doctor` to diagnose the consumer installation. Treat its checks as evidence, not a request to rewrite unrelated files.
+Run `node .trae-cn/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.
 
-`seven 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.
+`node .trae-cn/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 .trae-cn/skills/seven/scripts/run-seven.mjs update` after review, then retry `add`.
+
+`node .trae-cn/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/.trae-cn/skills/seven/reference/document.md

@@ -5,7 +5,7 @@ Document how an existing product surface consumes the exact installed Seven rele
 ## Read first
 
 - `.seven/release.lock.json`, `.seven/project.yml`, `PRODUCT.md`, and the matched surface brief;
-- `seven list` / `seven info` for every referenced component;
+- `node .trae-cn/skills/seven/scripts/run-seven.mjs list` / `node .trae-cn/skills/seven/scripts/run-seven.mjs info` for every referenced component;
 - representative source, tests, stories, and rendered states;
 - active exceptions and baseline entries.
 
@@ -22,7 +22,7 @@ Unless the user supplies a path, write under `docs/seven/`. Include:
 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 `seven check --file`. Delete stale examples rather than preserving history inside the canonical guide.
+Every example must compile against the current component API and pass `node .trae-cn/skills/seven/scripts/run-seven.mjs check --file`. Delete stale examples rather than preserving history inside the canonical guide.
 
 ## Prohibitions
 

package/.trae-cn/skills/seven/reference/evaluations.md

@@ -36,3 +36,9 @@ Use these scenarios in fresh consumer projects to verify routing and behavior af
 
 - 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/.trae-cn/skills/seven/reference/exceptions.md

@@ -2,6 +2,6 @@
 
 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 `seven 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.
+Before running `node .trae-cn/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 `seven exceptions validate` and `seven doctor` after changes. Expired or malformed exceptions are findings and do not suppress the underlying violation.
+Run `node .trae-cn/skills/seven/scripts/run-seven.mjs exceptions validate` and `node .trae-cn/skills/seven/scripts/run-seven.mjs doctor` after changes. Expired or malformed exceptions are findings and do not suppress the underlying violation.

package/.trae-cn/skills/seven/reference/extract.md

@@ -28,7 +28,7 @@ Do not extract merely because markup looks similar. Similar cards with different
 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 `seven check`.
+6. Migrate call sites one at a time and verify rendered parity plus `node .trae-cn/skills/seven/scripts/run-seven.mjs check`.
 
 ## Refuse
 

package/.trae-cn/skills/seven/reference/harden.md

@@ -31,6 +31,6 @@ Use the matched surface brief as the contract. Ask when a business outcome is un
 
 ## 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 `seven check`, unit/integration tests, and rendered browser validation for the target.
+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 .trae-cn/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/.trae-cn/skills/seven/reference/hooks.md

@@ -2,10 +2,10 @@
 
 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 `seven check --all` result remains blocking after either loop guard. Advisories are surfaced without blocking.
+`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 .trae-cn/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 `seven hooks status|on|off`. Machine-local `ignore-file` and `ignore-rule` controls affect hook noise only, never the shared `seven check` result. Never edit `.github/**` to enable Seven hooks.
+Use `node .trae-cn/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 .trae-cn/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 `seven doctor` information item as an activation checklist, not as proof that the host's private setting was changed.
+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 .trae-cn/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/.trae-cn/skills/seven/reference/init.md

@@ -1,38 +1,5 @@
-# Init — capture UI context
+# Init — compatibility alias
 
-Capture the facts later Seven workflows need. This is the skill-level setup workflow; the CLI command `seven init` installs Seven, while context is written with `seven onboard` for backward compatibility.
+`init` is retained for projects and prompts created before `setup` became the canonical skill workflow.
 
-## 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 `seven doctor --quick`. If Seven is not installed, instruct the user to install the exact desired `@etus/seven` release and run CLI `seven init`.
-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
-   seven onboard --name "..." --users "..." --job "..." --workflows "..." \
-     --voice "..." --accessibility "..." --constraints "..." --owner "..."
-   seven 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.
+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/.trae-cn/skills/seven/reference/live.md

@@ -1,16 +1,16 @@
 # 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 `seven check`.
+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 `seven doctor --quick --target <source>`.
+1. Load the normal Seven context and run `node .trae-cn/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
-   seven extension path
+   node .trae-cn/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.
@@ -20,7 +20,7 @@ Run an interactive Seven session against a rendered React 19 surface. The browse
 Start the loopback bridge in a persistent/background terminal:
 
 ```bash
-seven live start --url http://127.0.0.1:5173/route --target src/path/Surface.tsx
+node .trae-cn/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.
@@ -32,7 +32,7 @@ The bridge binds to `127.0.0.1`, validates extension/local origins, restricts pa
 Keep a one-shot foreground poll active whenever the user can interact with the Live panel:
 
 ```bash
-seven live poll
+node .trae-cn/skills/seven/scripts/run-seven.mjs live poll
 ```
 
 Dispatch the returned event, reply, then poll again immediately.
@@ -62,8 +62,8 @@ The event contains the action, optional prompt, target selector, bounded outer H
 ```
 
 ```bash
-seven live reply --id <event-id> --file .seven/live/reply-<event-id>.json
-seven live poll
+node .trae-cn/skills/seven/scripts/run-seven.mjs live reply --id <event-id> --file .seven/live/reply-<event-id>.json
+node .trae-cn/skills/seven/scripts/run-seven.mjs live poll
 ```
 
 Preview CSS is disposable evidence. Do not copy it mechanically into the source.
@@ -78,7 +78,7 @@ Acceptance identifies the chosen direction and current preview evidence. It auth
 
 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 `seven check --file <changed-file>`.
+3. Run focused tests and `node .trae-cn/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.
 
@@ -93,14 +93,14 @@ The extension restores the original DOM snapshot. Reply `done`; make no source e
 The append-only journal and session metadata live under ignored `.seven/live/` state:
 
 ```bash
-seven live status
-seven live start --resume --url <same-url> --target <same-target>
+node .trae-cn/skills/seven/scripts/run-seven.mjs live status
+node .trae-cn/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
-seven live stop
+node .trae-cn/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/.trae-cn/skills/seven/reference/polish.md

@@ -19,7 +19,7 @@ Every polish finding falls into one of three buckets. Name the bucket in your fi
 1. **Run the detector first**:
 
    ```bash
-   seven check --file <path>
+   node .trae-cn/skills/seven/scripts/run-seven.mjs check --file <path>
    ```
 
    The deterministic findings cover token drift and identity-level violations. Address them before manual review.

package/.trae-cn/skills/seven/reference/routing.md

@@ -13,7 +13,7 @@ Use this workflow when Seven is invoked without an intent. Do not dump a generic
 
 Route by current evidence:
 
-- Missing or placeholder product context: lead with `/seven init`.
+- 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`.

package/.trae-cn/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 .trae-cn/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 .trae-cn/skills/seven/scripts/run-seven.mjs onboard --name "..." --users "..." --job "..." --workflows "..." \
+     --voice "..." --accessibility "..." --constraints "..." --owner "..."
+   node .trae-cn/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/.trae-cn/skills/seven/reference/typeset.md

@@ -7,7 +7,7 @@ Refine hierarchy, readability, and delivery using the installed Seven Text compo
 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 `seven check --file <target>` and inspect arbitrary/dynamic styles the detector cannot resolve.
+2. Mechanical scan: run `node .trae-cn/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.
 

package/.trae-cn/skills/seven/scripts/context-signals.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { argValue, loadContext } from './load-context.mjs'
 
 const UI_EXTENSIONS = new Set(['.css', '.html', '.js', '.jsx', '.less', '.mdx', '.scss', '.ts', '.tsx'])
+const scriptsDirectory = path.dirname(fileURLToPath(import.meta.url))
 
 function gitNames(root, args) {
   const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' })
@@ -80,7 +81,7 @@ export async function collectContextSignals(start = process.cwd(), { target = st
     live: {
       session: fs.existsSync(path.join(context.projectRoot, '.seven', 'live', 'session.json')),
       journal: fs.existsSync(path.join(context.projectRoot, '.seven', 'live', 'journal.ndjson')),
-      extensionPathCommand: 'seven extension path',
+      extensionPathCommand: `node ${JSON.stringify(path.join(scriptsDirectory, 'run-seven.mjs'))} extension path`,
     },
   }
 }

package/.trae-cn/skills/seven/scripts/load-context.mjs

@@ -74,11 +74,29 @@ export async function loadContext(start = process.cwd(), { target = start } = {}
   return loaded.runtimeError ? fallback(root, target, loaded.runtimeError) : loaded
 }
 
+export function contextForAgent(context) {
+  const artifacts = context.release?.artifacts
+  if (!artifacts || typeof artifacts !== 'object') return context
+  const { artifacts: _artifacts, ...release } = context.release
+  const entries = Object.values(artifacts)
+  return {
+    ...context,
+    release: {
+      ...release,
+      artifactSummary: {
+        total: entries.length,
+        managed: entries.filter((entry) => entry?.kind === 'managed').length,
+        scaffold: entries.filter((entry) => entry?.kind === 'scaffold').length,
+      },
+    },
+  }
+}
+
 export async function main(argv = process.argv) {
   const target = argValue('--target', argv) || process.env.SEVEN_TARGET || process.cwd()
   const context = await loadContext(target, { target })
   const update = await checkForUpdate(context.release?.sevenVersion || null)
-  process.stdout.write(`${JSON.stringify({ ...context, update }, null, 2)}\n`)
+  process.stdout.write(`${JSON.stringify({ ...contextForAgent(context), update }, null, 2)}\n`)
 }
 
 function isCliEntry() {

package/.trae-cn/skills/seven/scripts/run-seven.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — package-manager-independent Seven CLI runner.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+import { findRoot } from './load-context.mjs'
+
+export function resolveSevenCli(start = process.cwd()) {
+  const root = findRoot(start)
+  const require = createRequire(path.join(root, 'package.json'))
+  const manifestPath = require.resolve('@etus/seven/package.json')
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.seven
+  if (!bin) throw new Error(`@etus/seven at ${manifestPath} does not declare the seven binary`)
+  return {
+    binPath: path.resolve(path.dirname(manifestPath), bin),
+    root,
+  }
+}
+
+export function runSeven(argv = process.argv.slice(2), start = process.cwd()) {
+  if (argv.length === 0) throw new Error('usage: run-seven.mjs <seven-command> [arguments]')
+  const { binPath, root } = resolveSevenCli(start)
+  const result = spawnSync(process.execPath, [binPath, ...argv], {
+    cwd: root,
+    env: process.env,
+    stdio: 'inherit',
+  })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function isCliEntry() {
+  if (!process.argv[1]) return false
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1])
+  } catch {
+    return false
+  }
+}
+
+if (isCliEntry()) process.exitCode = runSeven()