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

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

@@ -0,0 +1,43 @@
+# Typography
+
+Inter is the only sans face in Seven. JetBrains Mono is the only mono face. Every other typeface decision routes back to one of these two.
+
+## Hard rules
+
+- **Inter for everything sans-serif.** UI chrome, body, headings, display, numeric tabular figures. Use Inter's variable axes for weight (400 / 500 / 600 / 700) and width (`wdth` axis only if Figma uses it; Seven currently does not).
+- **JetBrains Mono for code and keyboard glyphs.** Never DM Mono, never IBM Plex Mono, never the system mono fallback as a primary choice.
+- **Reflex-reject in Seven**: Space Grotesk, Geist, DM Mono, Inter Tight, Inter Display. They appear in legacy Figma exploration on `Text/Display`, `Text/Heading`, `Dashboard/Dash-01-W`, `Timeline/StatusTitle`, `Feature-item`. They never shipped. Substitute Inter at the same size and surface the swap so the user knows.
+- **Sentence case across every chrome surface.** Headings, labels, button text, menu items, table column headers, breadcrumbs, tabs. Acronyms (KPI, OTP, OIDC, OAuth) stay uppercase.
+- **No trailing periods** on buttons, labels, breadcrumbs, captions, badge text, or short status messages. Periods belong in body prose, not in chrome.
+
+## Scale
+
+Seven's scale lives in `@etus/tokens`:
+
+- Body / `--text-base`: 16 px, line-height 1.5, Inter 400.
+- Caption / `--text-sm`: 14 px, line-height 1.4.
+- Label / `--text-xs`: 12 px, line-height 1.3 (uppercase only for monospaced data-table column headers).
+- Headings / `--text-lg` through `--text-4xl`: walk the Figma `Text/Heading` ramp. Hierarchy via scale plus weight contrast, not via color.
+
+Use the `<Text>` component variant API in `@etus/ui` rather than ad-hoc arbitrary classes. `<Text variant="h2">` is correct; `<h2 className="text-2xl font-semibold">` is drift.
+
+## Line-height and the Tailwind v4 trap
+
+The combination `leading-none` plus `text-[length:var(--something)]` zeroes line-height in Tailwind v4 (Lightning CSS interprets the arbitrary value before applying `leading-none`'s `1`). Two safe paths:
+
+- Use `leading-tight`, `leading-snug`, or a literal `leading-[1.1]`. They survive the Lightning CSS pass.
+- Inline `style={{ fontSize, lineHeight }}` for any case where the variable approach falters.
+
+## Numeric figures
+
+Inter ships tabular figures via the `tnum` feature. Apply `font-feature-settings: 'tnum' 1` to tables, data grids, KPI cards, and any column where digits need to line up vertically. The `<DataTable>` component does this for cells by default; manual KPI displays still need it.
+
+## Display surfaces
+
+Display typography (hero headings and marketing pages) follows the brand register in [brand.md](brand.md), not product chrome. Do not import display treatment into application UI.
+
+## Refusals
+
+- "Use Space Grotesk for the H1" — Inter is the only sans face. Substitute Inter Bold at the same size and surface the swap.
+- "Add letter spacing to the labels" — Seven labels use Inter at default tracking. Letter-spacing belongs to Display only, defined by the brand layer.
+- "Use the system font as a fallback" — Inter is loaded via `next/font` or equivalent. The system fallback is for SSR flash mitigation, never the primary stack.

package/.agents/skills/seven/reference/ux-writing.md

@@ -0,0 +1,47 @@
+# UX writing
+
+Seven's product chrome speaks Brazilian Portuguese. Developer-facing docs and code identifiers stay in English. The voice is direct, decisive, and concrete.
+
+## Hard rules
+
+- **Pt-BR for chrome.** Buttons, labels, menu items, navigation, table headers, breadcrumbs, tabs, status messages, empty states, toast text, error messages.
+- **No European Portuguese vocabulary.** The detector ships a `pt-pt-vocab` rule that catches `ficheiro`, `telemóvel`, `ecrã`, `tu` (as a pronoun, not in code), and other catalogued pairs. Use the pt-BR equivalents.
+- **Sentence case** across every chrome surface. Capitalize the first word and proper nouns; everything else lowercase. Acronyms stay uppercase.
+- **No trailing periods** on buttons, labels, captions, badges, breadcrumbs, table column headers, menu items, tabs. Periods belong in body prose, never in chrome.
+- **Imperative leads** for action buttons and menu items: `Procurar`, `Adicionar conta`, `Exportar relatório`, `Excluir item`. Avoid `Clique para`, `Você pode`, `Aqui você`.
+
+## Voice
+
+Direct, decisive, brazilian. Three qualities to hold:
+
+- **Direct.** No `clique aqui`, no `aprenda mais sobre`. The label says what the action does.
+- **Decisive.** No `talvez`, `poderia`, `seria possível`. If the system is suggesting an action, it commits to the suggestion. If it does not know, it asks.
+- **Concrete.** A token name beats an adjective. `Salvo às 14:32` beats `Alterações salvas com sucesso`. The user already knows it was successful, the timestamp tells them when.
+
+## Microcopy patterns
+
+| Surface             | Pattern                                | Example                                            |
+| ------------------- | -------------------------------------- | -------------------------------------------------- |
+| Primary button      | Verb + object, imperative              | `Adicionar conta`, `Salvar alterações`             |
+| Secondary button    | Verb only when context obvious         | `Cancelar`, `Voltar`                               |
+| Destructive button  | Verb + object, no hedging              | `Excluir conta`                                    |
+| Toast (success)     | Past tense, short                      | `Conta criada`                                     |
+| Toast (error)       | What broke + what to do                | `Não foi possível salvar. Tente novamente.`        |
+| Empty state         | What is missing + how to fix           | `Nenhuma conta. Adicione a primeira para começar.` |
+| Input placeholder   | Hint, not instruction                  | `nome@email.com`, not `Digite o seu email`         |
+| Validation error    | What is wrong, inline, below the field | `Email obrigatório`                                |
+| Menu item           | Verb in imperative                     | `Duplicar`, `Renomear`, `Arquivar`                 |
+| Table column header | Noun, sentence case                    | `Nome`, `Última atividade`, `Status`               |
+
+## Numbers and dates
+
+- Numbers use the Brazilian convention: comma for decimals, period for thousands. `1.234,56` not `1,234.56`.
+- Dates default to `dd/mm/yyyy` in chrome surfaces. ISO `yyyy-mm-dd` in data tables and developer-facing logs.
+- Currency: `R$ 1.234,56` with non-breaking space.
+- Relative time for recent events (`há 2 minutos`, `há 1 hora`), absolute date once it crosses 24 hours (`12/03/2026`).
+
+## Refusals
+
+- "Use European Portuguese to match the parent company brand" — Pt-BR is non-negotiable for Seven chrome. Surface this to the user; if there is a legitimate need for pt-PT, it is a brand-layer decision documented separately.
+- "Add a period to the button text for consistency with paragraphs" — Chrome and prose follow different rules. Buttons do not get periods.
+- "Make all the labels uppercase for emphasis" — Sentence case is non-negotiable. Use weight or size for emphasis, not uppercase.

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

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

package/.agents/skills/seven/scripts/context-signals.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+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'])
+
+function gitNames(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+  if (result.status !== 0) return []
+  return result.stdout.split('\n').map((item) => item.trim()).filter(Boolean)
+}
+
+function changedUiFiles(root) {
+  const names = new Set([
+    ...gitNames(root, ['diff', '--name-only', '--diff-filter=ACMR']),
+    ...gitNames(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']),
+    ...gitNames(root, ['ls-files', '--others', '--exclude-standard']),
+  ])
+  return [...names].filter((name) => UI_EXTENSIONS.has(path.extname(name).toLowerCase())).sort()
+}
+
+function latestReview(root) {
+  const directory = path.join(root, '.seven', 'reviews')
+  let names = []
+  try {
+    names = fs.readdirSync(directory).filter((name) => name.endsWith('.json'))
+  } catch {
+    return null
+  }
+  const candidates = names.map((name) => {
+    const filePath = path.join(directory, name)
+    try {
+      return { filePath, mtime: fs.statSync(filePath).mtimeMs, payload: JSON.parse(fs.readFileSync(filePath, 'utf8')) }
+    } catch {
+      return null
+    }
+  }).filter(Boolean).sort((left, right) => right.mtime - left.mtime)
+  if (!candidates[0]) return null
+  return {
+    path: path.relative(root, candidates[0].filePath).split(path.sep).join('/'),
+    createdAt: candidates[0].payload.createdAt || null,
+    score: candidates[0].payload.score ?? null,
+    p0: candidates[0].payload.summary?.p0 ?? 0,
+    p1: candidates[0].payload.summary?.p1 ?? 0,
+    target: candidates[0].payload.target || null,
+  }
+}
+
+function scanTargets(context, changed) {
+  if (changed.length > 0) return { via: 'git-changes', targets: changed.slice(0, 40) }
+  const roots = Array.isArray(context.project?.sourceRoots) ? context.project.sourceRoots : ['src']
+  const existing = roots.filter((entry) => fs.existsSync(path.join(context.projectRoot, entry)))
+  return { via: 'source-roots', targets: existing.slice(0, 8) }
+}
+
+export async function collectContextSignals(start = process.cwd(), { target = start } = {}) {
+  const context = await loadContext(start, { target })
+  const changed = changedUiFiles(context.projectRoot)
+  return {
+    schemaVersion: 1,
+    projectRoot: context.projectRoot,
+    target: path.resolve(target),
+    setup: {
+      hasProduct: context.hasProduct,
+      productPlaceholder: context.productPlaceholder,
+      hasRelease: Boolean(context.release),
+      register: context.register,
+      app: context.app?.id || null,
+      surface: context.surface?.id || null,
+    },
+    git: { changedFiles: changed },
+    critique: { latest: latestReview(context.projectRoot) },
+    scan: scanTargets(context, changed),
+    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',
+    },
+  }
+}
+
+export async function main(argv = process.argv) {
+  const target = argValue('--target', argv) || process.env.SEVEN_TARGET || process.cwd()
+  const signals = await collectContextSignals(target, { target })
+  process.stdout.write(`${JSON.stringify(signals, null, 2)}\n`)
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) await main()

package/.agents/skills/seven/scripts/critique-storage.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { argValue, findRoot, loadContext } from './load-context.mjs'
+
+const PRIORITIES = new Set(['P0', 'P1', 'P2', 'P3'])
+const SENSITIVE_KEY = /(?:authorization|cookie|password|secret|token|api[-_]?key|session[-_]?id)/i
+
+function slug(value) {
+  return String(value || 'review')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60) || 'review'
+}
+
+function assertNoSensitiveKeys(value, trail = []) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoSensitiveKeys(entry, [...trail, String(index)]))
+    return
+  }
+  if (!value || typeof value !== 'object') return
+  for (const [key, entry] of Object.entries(value)) {
+    if (SENSITIVE_KEY.test(key)) throw new Error(`critique input contains a forbidden sensitive field: ${[...trail, key].join('.')}`)
+    assertNoSensitiveKeys(entry, [...trail, key])
+  }
+}
+
+function validateReview(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('critique input must be a JSON object')
+  if (!Number.isFinite(input.score) || input.score < 0 || input.score > 100) throw new Error('critique score must be between 0 and 100')
+  if (!Array.isArray(input.findings)) throw new Error('critique findings must be an array')
+  for (const [index, finding] of input.findings.entries()) {
+    if (!finding || typeof finding !== 'object') throw new Error(`finding ${index + 1} must be an object`)
+    if (!PRIORITIES.has(finding.priority)) throw new Error(`finding ${index + 1} has invalid priority`)
+    for (const field of ['title', 'evidence', 'recommendation']) {
+      if (typeof finding[field] !== 'string' || !finding[field].trim()) throw new Error(`finding ${index + 1} requires ${field}`)
+    }
+  }
+  assertNoSensitiveKeys(input)
+}
+
+function readInput(inputPath) {
+  const text = inputPath === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(inputPath), 'utf8')
+  if (Buffer.byteLength(text) > 1_000_000) throw new Error('critique input exceeds 1 MB')
+  return JSON.parse(text)
+}
+
+function counts(findings) {
+  const summary = { p0: 0, p1: 0, p2: 0, p3: 0 }
+  for (const finding of findings) summary[finding.priority.toLowerCase()]++
+  return summary
+}
+
+function markdown(review) {
+  const lines = [
+    `# Seven critique — ${review.target}`,
+    '',
+    `- Created: ${review.createdAt}`,
+    `- Seven release: ${review.release?.sevenVersion || 'unknown'}`,
+    `- Surface: ${review.surface || 'unresolved'}`,
+    `- Score: ${review.score}/100`,
+    `- Priorities: P0 ${review.summary.p0}, P1 ${review.summary.p1}, P2 ${review.summary.p2}, P3 ${review.summary.p3}`,
+    '',
+  ]
+  if (review.strengths?.length) {
+    lines.push('## Strengths to preserve', '')
+    for (const strength of review.strengths) lines.push(`- ${strength}`)
+    lines.push('')
+  }
+  lines.push('## Findings', '')
+  if (review.findings.length === 0) lines.push('No active findings.', '')
+  for (const finding of review.findings) {
+    lines.push(`### ${finding.priority} — ${finding.title}`, '')
+    lines.push(`**Evidence:** ${finding.evidence}`, '')
+    if (finding.impact) lines.push(`**Impact:** ${finding.impact}`, '')
+    if (finding.rootCause) lines.push(`**Root cause:** ${finding.rootCause}`, '')
+    lines.push(`**Direction:** ${finding.recommendation}`, '')
+    if (finding.verification) lines.push(`**Verify:** ${finding.verification}`, '')
+  }
+  if (review.verification) lines.push('## Verification evidence', '', review.verification, '')
+  lines.push('This review is evidence, not a visual authority. The installed Seven release remains canonical.', '')
+  return lines.join('\n')
+}
+
+function atomicWrite(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  const temporary = `${filePath}.tmp-${process.pid}-${Date.now()}`
+  fs.writeFileSync(temporary, content)
+  fs.renameSync(temporary, filePath)
+}
+
+export async function writeReview(start, target, input) {
+  validateReview(input)
+  const root = findRoot(start)
+  const context = await loadContext(root, { target })
+  let resolvedTarget = target
+  if (!/^https?:\/\//i.test(target)) {
+    const absolute = path.resolve(root, target)
+    const relative = path.relative(root, absolute)
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('critique target escapes the Seven project root')
+    resolvedTarget = relative.split(path.sep).join('/') || '.'
+  }
+  const createdAt = new Date().toISOString()
+  const review = {
+    schemaVersion: 1,
+    createdAt,
+    target: resolvedTarget,
+    surface: context.surface?.id || null,
+    release: context.release ? {
+      sevenVersion: context.release.sevenVersion,
+      skillVersion: context.release.skillVersion,
+      registrySha256: context.release.registrySha256,
+    } : null,
+    score: input.score,
+    summary: counts(input.findings),
+    renderedEvidence: input.renderedEvidence || null,
+    mechanicalEvidence: input.mechanicalEvidence || null,
+    strengths: Array.isArray(input.strengths) ? input.strengths : [],
+    findings: input.findings,
+    verification: input.verification || null,
+  }
+  const stamp = createdAt.replace(/[:.]/g, '-').replace(/-000Z$/, 'Z')
+  const base = path.join(root, '.seven', 'reviews', `${stamp}-${slug(context.surface?.id || resolvedTarget)}`)
+  atomicWrite(`${base}.json`, `${JSON.stringify(review, null, 2)}\n`)
+  atomicWrite(`${base}.md`, markdown(review))
+  return {
+    review,
+    json: path.relative(root, `${base}.json`).split(path.sep).join('/'),
+    markdown: path.relative(root, `${base}.md`).split(path.sep).join('/'),
+  }
+}
+
+export async function main(argv = process.argv) {
+  const action = argv[2]
+  if (action !== 'write') throw new Error('usage: critique-storage.mjs write --target <target> --input <review.json|->')
+  const target = argValue('--target', argv)
+  const inputPath = argValue('--input', argv)
+  if (!target || !inputPath) throw new Error('write requires --target and --input')
+  const result = await writeReview(process.cwd(), target, readInput(inputPath))
+  process.stdout.write(`${JSON.stringify({ json: result.json, markdown: result.markdown, summary: result.review.summary }, null, 2)}\n`)
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = 1
+  })
+}

package/.agents/skills/seven/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven consumer context adapter.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { checkForUpdate } from './update-check.mjs'
+
+export function argValue(name, argv = process.argv) {
+  const direct = argv.find((arg) => arg.startsWith(`${name}=`))
+  if (direct) return direct.slice(name.length + 1)
+  const index = argv.indexOf(name)
+  return index >= 0 ? argv[index + 1] : null
+}
+
+export function findRoot(start) {
+  let current = path.resolve(start)
+  try {
+    if (fs.statSync(current).isFile()) current = path.dirname(current)
+  } catch {}
+  const fallbackRoot = current
+  while (true) {
+    if (fs.existsSync(path.join(current, '.seven', 'project.yml'))) return current
+    if (fs.existsSync(path.join(current, 'seven.json'))) return current
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return fallbackRoot
+}
+
+export async function loadFromInstalledRuntime(root, target) {
+  try {
+    const require = createRequire(path.join(root, 'package.json'))
+    const manifest = require.resolve('@etus/seven/package.json')
+    const moduleUrl = pathToFileURL(path.join(path.dirname(manifest), 'lib', 'context.mjs')).href
+    const runtime = await import(moduleUrl)
+    return runtime.loadConsumerContext(root, { target })
+  } catch (error) {
+    return { runtimeError: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export function fallback(root, target, runtimeError) {
+  const productPath = path.join(root, 'PRODUCT.md')
+  const product = fs.existsSync(productPath) ? fs.readFileSync(productPath, 'utf8') : null
+  let release = null
+  try {
+    release = JSON.parse(fs.readFileSync(path.join(root, '.seven', 'release.lock.json'), 'utf8'))
+  } catch {}
+  return {
+    schemaVersion: 1,
+    projectRoot: root,
+    target: path.resolve(target),
+    hasProduct: Boolean(product),
+    product,
+    productPath: product ? 'PRODUCT.md' : null,
+    productPlaceholder: !product || product.trim().length < 200 || /\b(?:TODO|TBD|placeholder)\b/i.test(product),
+    register: null,
+    project: null,
+    release,
+    surface: null,
+    runtimeAvailable: false,
+    runtimeError,
+  }
+}
+
+export async function loadContext(start = process.cwd(), { target = start } = {}) {
+  const root = findRoot(start)
+  const loaded = await loadFromInstalledRuntime(root, target)
+  return loaded.runtimeError ? fallback(root, target, loaded.runtimeError) : loaded
+}
+
+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`)
+}
+
+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()) await main()

package/.agents/skills/seven/scripts/update-check.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const WEEK_MS = 7 * DAY_MS
+
+function cachePath(env = process.env) {
+  return env.SEVEN_UPDATE_CACHE || path.join(os.homedir(), '.seven', 'update-check.json')
+}
+
+function readCache(env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath(env), 'utf8'))
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeCache(cache, env) {
+  try {
+    const destination = cachePath(env)
+    fs.mkdirSync(path.dirname(destination), { recursive: true })
+    fs.writeFileSync(destination, `${JSON.stringify(cache, null, 2)}\n`)
+  } catch {
+    // Update discovery is best-effort and must never block the UI workflow.
+  }
+}
+
+function semverParts(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
+  if (!match) return null
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function compareIdentifier(left, right) {
+  const leftNumber = /^\d+$/.test(left) ? Number(left) : null
+  const rightNumber = /^\d+$/.test(right) ? Number(right) : null
+  if (leftNumber != null && rightNumber != null) return Math.sign(leftNumber - rightNumber)
+  if (leftNumber != null) return -1
+  if (rightNumber != null) return 1
+  return left.localeCompare(right)
+}
+
+export function compareSemver(left, right) {
+  const a = semverParts(left)
+  const b = semverParts(right)
+  if (!a || !b) return 0
+  for (let index = 0; index < 3; index++) {
+    if (a.core[index] !== b.core[index]) return Math.sign(a.core[index] - b.core[index])
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1
+  if (b.prerelease.length === 0 && a.prerelease.length > 0) return -1
+  for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+    if (a.prerelease[index] == null) return -1
+    if (b.prerelease[index] == null) return 1
+    const compared = compareIdentifier(a.prerelease[index], b.prerelease[index])
+    if (compared !== 0) return compared
+  }
+  return 0
+}
+
+async function fetchLatest(env) {
+  const registry = (env.SEVEN_UPDATE_REGISTRY || 'https://registry.npmjs.org').replace(/\/$/, '')
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 1500)
+  try {
+    const response = await fetch(`${registry}/%40etus%2Fseven/latest`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    })
+    if (!response.ok) return null
+    const payload = await response.json()
+    return typeof payload?.version === 'string' ? payload.version : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function checkForUpdate(currentVersion, { env = process.env, now = Date.now() } = {}) {
+  if (!currentVersion || env.SEVEN_NO_UPDATE_CHECK) return null
+  const cache = readCache(env)
+  const fresh = typeof cache.checkedAt === 'number' && now - cache.checkedAt < DAY_MS
+  let latestVersion = fresh ? cache.latestVersion : await fetchLatest(env)
+  if (!latestVersion) latestVersion = cache.latestVersion || null
+  if (!fresh && latestVersion) {
+    cache.checkedAt = now
+    cache.latestVersion = latestVersion
+  }
+  if (!latestVersion) return null
+
+  const available = compareSemver(latestVersion, currentVersion) > 0
+  const notify = available && (
+    cache.notifiedVersion !== latestVersion ||
+    typeof cache.notifiedAt !== 'number' ||
+    now - cache.notifiedAt >= WEEK_MS
+  )
+  if (notify) {
+    cache.notifiedVersion = latestVersion
+    cache.notifiedAt = now
+  }
+  writeCache(cache, env)
+  return {
+    package: '@etus/seven',
+    currentVersion,
+    latestVersion,
+    available,
+    notify,
+    command: `pnpm add -D @etus/seven@${latestVersion} && pnpm exec seven update`,
+  }
+}

package/.claude/agents/seven-asset-producer.md

@@ -0,0 +1,40 @@
+---
+name: seven-asset-producer
+description: Produces or prepares approved UI imagery and reusable visual assets without redesigning the direction or baking Seven chrome into raster files.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: inherit
+effort: medium
+maxTurns: 12
+---
+
+# Seven Asset Producer
+
+You prepare production assets from an approved brief or reference. You do not choose a new visual direction and you do not edit application implementation code.
+
+## Input contract
+
+Require the reference or brief, output directory, visual role, target dimensions/aspect ratio, transparency needs, allowed generation/editing tool, provenance/license constraints, and an avoid list. Missing source or output directory blocks work; choose conservative format/compression defaults for other omissions and report them.
+
+## Classify every requested visual
+
+- `produce`: requires approved image generation, editing, cleanup, cutout, or reconstruction.
+- `direct`: an existing licensed, sufficiently large source needs only crop, naming, or compression.
+- `semantic`: must remain HTML, Seven components, CSS, Lucide/SVG, canvas, or chart code.
+
+Controls, UI copy, navigation, charts, data widgets, cards, app frames, logos/wordmarks with vector sources, icons available in Lucide, and full interface screenshots are semantic by default. Do not rasterize them to imitate a mock.
+
+## Production rules
+
+1. Preserve the approved subject, composition, camera, silhouette, material, palette role, and lighting. Do not add objects or “improve” the concept.
+2. Keep radius, border, shadow, perspective, captions, responsive crop, and layout in code when the implementation can own them.
+3. Remove baked UI text, buttons, labels, mock chrome, watermarks, letterboxing, and empty padding unless explicitly intrinsic to the asset.
+4. Prefer WebP for opaque photographic/texture assets, PNG for true-alpha cutouts, and SVG only for authored vector work. Produce at target density, normally 2× display size.
+5. Use a harness-native image generation/editing capability when available and explicitly authorized. Never request, read, log, or store a consumer API key. If no approved capability exists, return `blocked`; do not invent an HTTP fallback.
+6. Keep sources/references in a sibling review directory and shipping outputs alone in the production directory.
+7. Record provenance, license, generation/edit history, prompt when applicable, dimensions, format, alt-text recommendation, and QA result.
+
+## QA and output
+
+Compare every output to the approved reference at actual display crop. Reject unwanted text/chrome, low resolution, wrong perspective, haloed transparency, visual drift, or missing provenance. Return a manifest grouped by `produce`, `direct`, and `semantic`, followed by `execution_order`, `blockers`, and `assumptions`. `qa_status` is `accepted`, `needs_parent_review`, or `blocked`.
+
+Do not modify application code, the approved reference, Seven tokens, or component contracts.

package/.claude/agents/seven-finish-reviewer.md

@@ -0,0 +1,36 @@
+---
+name: seven-finish-reviewer
+description: Reviews a supposedly finished Seven UI with fresh attention against product context, the exact release contract, rendered evidence, and completion criteria; never edits.
+tools: Read, Bash, Glob, Grep
+model: inherit
+effort: high
+maxTurns: 12
+---
+
+# Seven Finish Reviewer
+
+You are an independent final reviewer. You do not edit files. The parent agent owns fixes.
+
+## Input contract
+
+Expect the original request and confirmed decisions, target/source paths, `PRODUCT.md`, matched surface brief, release lock, component/variant inventory, changed-file list, latest Seven check output, tests, and rendered screenshots or a running URL at relevant viewports. If a material input is absent, name it rather than guessing.
+
+## Review order
+
+1. **Context and scope:** the implementation satisfies the stated product job without unrelated redesign; required context exists and no consumer `DESIGN.md` overrides Seven.
+2. **Release contract:** every primitive, variant, token, icon, and motion value belongs to the exact installed Seven release. Missing contracts are surfaced, not locally invented.
+3. **Rendered task:** primary action, reading order, density, alignment, responsive behavior, content extremes, and product specificity hold at the required viewports/themes.
+4. **States and access:** loading, empty, error, success, disabled, permissions, keyboard, focus, accessible names, contrast, zoom, and reduced motion are complete.
+5. **Truth and persistence:** no invented claims or fake production data; generated assets are labeled/provenanced; the latest critique and documentation reflect the actual target where required.
+6. **Evidence:** focused tests and `seven check` cover every changed UI file. Do not rerun a redundant detector pass unless the supplied result is stale or missing.
+
+## Output contract
+
+Return exactly four sections:
+
+- `contract`: pass/fail with exact release/component/context discrepancies;
+- `rendered`: the strongest unresolved rendered/state issue, or `reached`;
+- `material_fixes`: at most eight ordered one-line fixes, each tied to evidence and a verification criterion;
+- `keep`: one line naming what must not be diluted while fixing.
+
+No praise, no vague score, no edits, and no summary prose outside those sections.