@etus/seven

@etus/seven is the single consumer-facing Seven CLI. It installs Seven components as source and installs the local governance layer that keeps human- and agent-authored UI inside the exact Seven release selected by the project.

pnpm add -D @etus/seven@<exact-version>
pnpm exec seven init --install
pnpm exec seven onboard \
  --name "Operações ETUS" \
  --users "Analistas internos" \
  --job "Resolver exceções operacionais" \
  --workflows "Revisar, decidir e acompanhar" \
  --voice "Português brasileiro direto e profissional" \
  --accessibility "WCAG AA e operação completa por teclado" \
  --constraints "Sem paleta ou variantes locais" \
  --owner "[email protected]"
pnpm exec seven add button card --install
pnpm exec seven doctor
pnpm exec seven check --all

Requirements are checked before the first write: React 19, Tailwind CSS 4, and, when already declared, tailwind-merge@^3.4.0. The foundation installs clsx, class-variance-authority, lucide-react, tw-animate-css (the overlay enter/exit utilities seven.css imports), and the exact compatible tailwind-merge range.

Copied components are React Server Components-ready: interactive files carry "use client" in the registry source, so they work when imported from a Next.js App Router Server Component; presentational files ship without the directive and stay server-renderable. In Vite SPAs the directive is inert.

What seven init installs

| Consumer artifact | Purpose | | ------------------------------------------------- | -------------------------------------------------------------------------- | | seven.json, src/seven.css, src/lib/utils.ts | Versioned Seven foundation and source-copy configuration | | .seven/release.lock.json | Exact CLI, skill, registry, provider, and artifact integrity record | | .seven/policy.json | Generated deterministic severity policy for this release | | .seven/project.yml | Source roots, apps, surfaces, validation excludes, profile, and providers | | PRODUCT.md | Product users, job, workflows, voice, accessibility needs, and constraints | | .seven/surfaces/*.md | Optional target-specific behavior/state briefs | | Provider skill trees | Native Seven skill for each selected agent host | | Provider agent definitions | Asset producer, finish reviewer, and manual-edit applier where supported | | Provider hook manifests | Semantically merged local hooks where the host exposes a compatible API | | Resolved local Git pre-commit hook | Deterministic staged-file enforcement, preserving existing hook behavior | | .seven/runtime/hook.mjs | Tiny adapter into the exact installed @etus/seven runtime | | .seven/exceptions.yml | Shared, owned, expiring exceptions | | .seven/state.local.json | Git-ignored machine-local hook state, cache, and noise controls | | .seven/reviews/ | Persisted critique evidence | | .seven/live/ | Git-ignored Live session journal and reply payloads |

The published @etus/seven-skill dependency also carries Seven UI Guardian, the unpacked Manifest V3 extension used for rendered-page findings and reversible Seven Live previews. It is intentionally not copied into the consumer repository.

Seven creates and manages no .github/** artifact. It does not install a workflow, required check, CODEOWNERS rule, or GitHub webhook. Governance is entirely inside each consumer project. --no-hooks is deliberately unsupported because the local agent feedback loop is part of the installed contract.

Codex project hooks are subject to Codex's project trust and hook-hash review. Run /hooks after installation or after a hook definition changes, review the commands, and trust the current project definition.

Some hosts require a one-time action outside npm, which seven init and seven doctor report as informational activation notes:

• Codex requires reviewing and trusting the project hook in /hooks; a changed hook hash can require approval again.

These host permissions cannot be bypassed safely by a package installer. They do not weaken the provider-independent local Git pre-commit gate.

Commands

Components and registry

• seven init [--providers <list|all>] [--profile etus-strict] [--install] installs the foundation and consumer governance transactionally. Without --providers, it first selects supported harness directories already present in the project, otherwise infers the user's installed harnesses, and finally falls back to claude,codex. Detection is read-only and every artifact is still written only inside the consumer project. The two supported and tested hosts are Claude Code (claude) and Codex (codex); --providers all is shorthand for both.
• Shared templates and scripted bootstraps should always pass an explicit provider list (or all) so the committed provider set does not depend on the first developer's machine. The selected set is persisted in .seven/release.lock.json; normal seven update reuses that lock instead of detecting again.
• seven add <component...> [--install] first proves that seven init completed and that the consumer still matches the exact release lock. Only then does it resolve registry dependencies and copy source without overwriting consumer changes unless --overwrite is explicit.
• seven list [query] searches the bundled registry.
• seven info <component> returns dependencies, files, and declared CVA variant sets from the exact registry.

The bundled registry is the release authority. seven init and governed seven add reject --registry; upgrade or downgrade @etus/seven to choose a different registry. This prevents components from one version being checked against policy and variant metadata from another.

The add preflight runs before registry resolution, component writes, or --install. It rejects missing/partial initialization; CLI, skill, or registry version drift; incomplete or altered managed artifacts; a mismatched project profile/provider/scan scope; weakened provider hooks or local pre-commit; divergent package commands/dependency pins; and broken local-state isolation. The refusal is read-only and points to seven doctor plus seven update. --force, --overwrite, --install, and --dry-run cannot bypass it; --force belongs on the reviewed seven update repair when an owned file really must be reconciled. Consumer-authored scaffold content may be customized, but initialized scaffold files must remain present.

Context and health

• seven onboard writes complete product context from explicit flags or an interactive prompt.
• seven onboard --app <id> --target <app-root> adds target-aware app context in a monorepo.
• seven onboard --surface <id> --target <file-or-glob> [--app <id>] adds a surface brief and mapping.
• seven context --target <path> prints the resolved project, app, product, release, and surface context an agent receives.
• seven doctor [--quick] [--target <path>] validates versions, registry/artifact hashes, package requirements, provider-native skills and agents, semantic hook presence, local pre-commit, Live state isolation, the packaged extension, pinned workflows, exceptions, context freshness, monorepo app roots, the consumer-only boundary, and the global stylesheet wiring (@import "tailwindcss" in full first, the Seven stylesheet after it in the same file, tw-animate-css imported by the foundation and declared in package.json).

Deterministic validation

• seven check --all scans configured source roots.
• seven check --changed scans modified and untracked UI files.
• seven check --staged scans staged UI files.
• seven check --file <path> scans one or more comma-separated files.
• seven check <url> renders a live page with Puppeteer and adds runtime evidence such as script errors, broken images, failed reveal content, overflow, clipping, occlusion, heading rhythm, edge-flush cards, and computed Seven token drift.

URL checks require the optional Puppeteer package and a compatible Chrome binary. If the package manager blocks dependency install scripts, approve Puppeteer's browser installation or configure a compatible local Chrome before running the URL check. File checks and the local pre-commit gate do not depend on a browser runtime.

• seven detect ... is an alias for the governed seven check path.

Exit code 0 means no active blocking finding, 2 means policy findings, and 1 means a configuration or usage failure. The default strict profile blocks both errors and warnings. The scanner is deterministic; an LLM is never a hard gate.

Hooks

The installed agent hooks fail open on parser, dependency, and runtime failures and always exit zero. Valid blocking findings use the provider's structured JSON protocol rather than a process failure. Claude Code and Codex receive compatible native hooks; every selected host receives the skill, and every Git worktree receives the deterministic local pre-commit gate.

• PreToolUse resolves the target app/surface and injects each distinct product/release context once per session, reloading when the agent crosses into another app or surface.
• PostToolUse scans the changed UI file with the immediate rule tier and deduplicates findings by content/signature.
• Stop runs the full rule set across UI files touched in the session. Errors and warnings return decision: "block" so the agent continues the task. A Claude Code re-entry marked stop_hook_active: true exits silently because the prior response already surfaced the findings; hosts without that contract retain a three-attempt cap for an unchanged finding set. Advisories remain non-blocking, and seven check --all stays authoritative.

Commands: seven hooks status|on|off|log, seven hooks ignore-file <glob>, seven hooks ignore-rule <id>, and seven hooks clear-ignores. Hook ignores are machine-local and never change seven check results.

Workflows, critique evidence, and shortcuts

The skill routes 22 UI workflows: adapt, animate, audit, bolder, clarify, colorize, critique, delight, distill, document, extract, harden, layout, live, onboard, optimize, overdrive, polish, quieter, setup, shape, and typeset. init remains a backward-compatible alias for the canonical setup skill workflow and is distinct from the shell installer seven init. Invoke /seven setup [target] in Claude Code or $seven setup [target] in Codex. No-argument routing uses local context signals to recommend the smallest relevant next workflow. Critique results can be persisted under .seven/reviews/.

Agent workflows execute CLI subcommands through their installed run-seven.mjs helper. It resolves the exact local @etus/seven binary without requiring a global install or assuming npm, pnpm, Yarn, or Bun.

seven pin <workflow> creates a provider-native standalone shortcut in every selected host; seven unpin <workflow> removes only the Seven-owned shortcut. Pins are retained through updates and checked by seven doctor.

Browser extension and Seven Live

seven extension path
seven live start --url http://127.0.0.1:5173/route --target src/path/Surface.tsx
seven live poll
seven live reply --id <event-id> --file .seven/live/reply-<event-id>.json
seven live status
seven live stop

The first command prints the published unpacked extension directory. Browser security requires a one-time user-approved load from chrome://extensions; npm cannot silently activate an extension. Live binds only to 127.0.0.1, uses a random ephemeral bearer token, accepts events only from the declared page origin, journals unanswered work for recovery, and transports inert HTML/CSS previews only. Accepted directions still become code through a reviewed React/Seven source edit followed by focused validation.

Exceptions and migration baseline

Shared exceptions require one known rule, a narrow file glob, reason, owner, issue, and future expiry:

seven exceptions add raw-interactive-element \
  --file src/legacy/Confirm.tsx \
  --reason "Migração delimitada" \
  --owner design-platform \
  --issue DS-123 \
  --expires 2026-12-31
seven exceptions validate

An exception should be added only after explicit user approval. A baseline is for an existing migration, records exact finding signatures, and can shrink but cannot grow:

seven baseline create --reason "Migração inicial" --owner design-platform --issue DS-200
seven baseline update --reason "Dívida reduzida" --owner design-platform --issue DS-200

Update and uninstall

• seven update updates only release-owned governance artifacts from the exact currently installed package. Drift aborts before writes; --force first backs up the divergent file.
• seven update --providers codex also removes obsolete provider-owned skill files and only the Seven handlers from provider settings.
• seven uninstall removes unchanged release-owned governance artifacts, only scripts/dependencies Seven originally added, and only Seven hook handlers. Customized files are preserved with a reduced ownership lock.
• seven uninstall --force removes the remaining owned files after explicit review.

Copied UI component source remains consumer-owned. Preview a component refresh with seven add button --diff --dry-run, then use --overwrite only when you intend to reconcile that source with git.

Safety model

• All paths are resolved against an explicit Seven project root and traversal is rejected.
• The install preflights package compatibility, provider availability, JSON/YAML parsing, managed drift, and hook merges before writing.
• Component and governance writes are transactional and roll back earlier files if a later write fails.
• Existing non-Seven hook groups and package data are preserved through semantic merges.
• Generated, dependency, provider-skill, runtime, build, and sensitive paths are excluded from UI scans.
• The lock records SHA-256 per artifact plus a whole-set digest and bundled registry digest.
• Every seven add validates that lock, its canonical managed-artifact set, provider hooks, package wiring, project scan scope, and local pre-commit before the first possible mutation.
• Provider-native artifacts are shipped for the two supported hosts (Claude Code and Codex); an unsupported provider fails instead of receiving a generic fallback.
• The browser extension is validated during install and doctor, but activation always requires explicit browser consent.
• Seven Live accepts only authenticated loopback traffic and stores its journal under ignored .seven/live/.

Package mode

The CLI source-copy channel is primary. Consumers that prefer package imports can use @etus/ui, @etus/tokens, or @etus/seven-react, while still installing @etus/seven as a development dependency for governance. See React consumption.