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

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

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

package/.gemini/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/.gemini/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/.gemini/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/.gemini/skills/seven/scripts/context-signals.mjs

@@ -0,0 +1,95 @@
+#!/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'])
+const scriptsDirectory = path.dirname(fileURLToPath(import.meta.url))
+
+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: `node ${JSON.stringify(path.join(scriptsDirectory, 'run-seven.mjs'))} 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/.gemini/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/.gemini/skills/seven/scripts/load-context.mjs

@@ -0,0 +1,111 @@
+#!/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 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({ ...contextForAgent(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/.gemini/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()