tevra-design-kit 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tevra Design Kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROVENANCE.md

@@ -0,0 +1,18 @@
+# Provenance
+
+Tevra Design Kit's TypeScript code and skill instructions are original work, licensed under the MIT [LICENSE](LICENSE). Third-party projects listed below were used as references only.
+
+| Source | License | How it is used |
+| --- | --- | --- |
+| [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | MIT, © 2026 Leonxlnx | Conceptual reference for art direction and the screenshot review loop. No code, prompts or assets copied |
+| [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | MIT, © 2024 Next Level Builder | Reference for search and domain organization. Three short UX records adapted with attribution |
+| Web Quality Skills (Addy Osmani) | MIT, © 2026 Addy Osmani | Inspiration only for performance guidance. Nothing redistributed |
+| Vercel React guidance | Declared MIT | Inspiration only. No rule files redistributed |
+
+The three adapted records in `references/ux-patterns/catalog.json` have IDs starting with `upstream-` and carry their source URL, confidence and license. The full upstream MIT notice is at `references/ux-patterns/UPSTREAM-LICENSE.txt`. All other catalog records are Tevra guidance labeled `inferred`; they are not user-research data.
+
+Inspected revisions, license status and known limitations for every source are recorded in `registry/sources.json`.
+
+No upstream fonts, images, icons, logos, screenshots, full catalogs or scripts are included. A link to an asset is not permission to copy it; review each new asset separately.
+
+Third-party names and brands belong to their respective owners.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# Tevra Design Kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Design and frontend QA skills for coding agents, with a CLI that proves the work.**
+
+Tevra gives your coding agent twelve focused skills for researching, building, redesigning and reviewing user interfaces, and a local CLI that turns "looks good to me" into evidence: real screenshots, pixel diffs, accessibility results, performance metrics and a quality report that blocks delivery when something critical fails.
+
+Works with **Claude Code, Codex, Cursor, Kiro, Gemini CLI, GitHub Copilot, OpenCode and Windsurf**.
+
+[![CI](https://github.com/tevra-si/design-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/tevra-si/design-kit/actions/workflows/ci.yml) ![version 1.0.0](https://img.shields.io/badge/version-1.0.0-175a44) ![license MIT](https://img.shields.io/badge/license-MIT-blue) ![node](https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2026-339933)
+
+![A real Tevra run: approved baseline, the changed pricing section, the pixel diff and the checks that blocked delivery](docs/assets/hero.png)
+
+---
+
+- [Why Tevra](#why-tevra)
+- [See it in action](#see-it-in-action)
+- [The skills](#the-skills)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configure a project](#configure-a-project)
+- [Quick tour](#quick-tour)
+- [Update and uninstall](#update-and-uninstall)
+- [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
+
+## Why Tevra
+
+- **Respects your design system.** Every skill inspects and reuses the project's tokens and components first. Tevra never introduces a parallel system.
+- **Evidence over opinion.** Checks produce files you can open: screenshots, diffs, axe output, Lighthouse JSON. A missing tool is reported as an error, never as a pass.
+- **Humans stay in charge.** Baselines, transformative redesigns and brand changes need an explicit, recorded approval.
+- **Local and private.** Everything lives in the project's `.tevra/` folder. Nothing is uploaded, committed or sent to a model by the CLI.
+- **Agent-agnostic.** Plain Markdown skills in the open Agent Skills format, installable into eight agents.
+
+## See it in action
+
+The image above is a real run on the bundled [acceptance app](examples/acceptance-app/README.md): a pricing redesign captured across 3 states × 4 viewports. Every behavior, axe, console, network, overflow and touch-target check passed, yet delivery is blocked because 3–7% of pixels changed and nobody has approved the new look. Reproduce it yourself:
+
+```sh
+pnpm --filter @tevra/acceptance-app build:before && pnpm --filter @tevra/acceptance-app start   # terminal 1
+tevra-design init --root examples/acceptance-app --yes --skip-skills                            # terminal 2
+tevra-design capture --root examples/acceptance-app --kind baseline --approve-baseline
+pnpm --filter @tevra/acceptance-app build                                                       # apply the redesign
+tevra-design capture --root examples/acceptance-app
+tevra-design compare --root examples/acceptance-app
+tevra-design report  --root examples/acceptance-app                                             # FAIL: visual-diff
+```
+
+Every finding links to its evidence in the HTML report:
+
+<img src="docs/assets/report.png" alt="Tevra HTML quality report listing passed checks and the failed visual diff with links to evidence" width="720">
+
+## The skills
+
+| Skill | Use it when |
+| --- | --- |
+| `design-research` | The brief, users or problem are unclear and need evidence first |
+| `design-direction` | Starting substantial new UI or a redesign, or turning a screenshot into a direction |
+| `design-system` | Creating or extending tokens, themes, dark mode or component variants |
+| `ui-builder` | Building or changing a real screen, component, route or form |
+| `ui-redesign` | Improving an existing screen without breaking its behavior |
+| `responsive-design` | Fixing mobile/tablet layouts, overflow, breakpoints or safe areas |
+| `interaction-motion` | Adding feedback, transitions, loading states or reduced-motion behavior |
+| `visual-review` | Comparing screenshots, approving baselines or scoring visual quality |
+| `accessibility-qa` | Checking WCAG, keyboard and focus, labels and contrast |
+| `browser-testing` | Writing or running end-to-end tests of real user flows |
+| `performance-qa` | A page feels slow, or you need Lighthouse, LCP, CLS or TBT |
+| `frontend-review` | Reviewing frontend code or a diff before merge |
+
+Agents pick skills automatically from your request. Bigger requests chain several skills. For example, "build a new dashboard" runs research → direction → system → builder → responsive → visual review → accessibility.
+
+## Requirements
+
+| Needed for | Requirement |
+| --- | --- |
+| CLI | Node `^22.22.2`, `^24.15.0` or `>=26`, and pnpm 11 |
+| Screenshots, axe, Lighthouse | A Chromium-based browser Playwright can launch |
+| Claude Code plugin | Claude Code with plugin support (`claude plugin --help` lists the commands) |
+
+## Installation
+
+Choose **A** for skills in Claude Code, **B** for the CLI and any other agent. Most teams use both.
+
+### A. Claude Code plugin
+
+```sh
+claude plugin marketplace add tevra-si/design-kit
+claude plugin install tevra@tevra
+```
+
+Or inside a session: `/plugin marketplace add tevra-si/design-kit`, then `/plugin install tevra@tevra`.
+
+Open a **new** session (skills load at startup) and type `/tevra` to see them. Skills are namespaced as `tevra:<skill>`, such as `/tevra:ui-builder`, so they never collide with a project skill of the same name.
+
+### B. CLI and skills for any agent
+
+**1. Install the CLI**
+
+```sh
+git clone https://github.com/tevra-si/design-kit.git
+cd design-kit
+pnpm install
+pnpm build
+npm link                                # adds `tevra-design` to your PATH
+pnpm exec playwright install chromium   # browser for screenshots and axe
+tevra-design help
+```
+
+After `git pull`, run `pnpm build` again; the linked command uses your clone.
+
+**2. Add Tevra to a project**
+
+```sh
+cd /path/to/your-project
+tevra-design init --yes --agents claude,cursor
+```
+
+| `--agents` | Installs into |
+| --- | --- |
+| `claude` | `.claude/skills/` |
+| `codex` | `.agents/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `kiro` | `.kiro/skills/` |
+| `gemini` | `.gemini/skills/` |
+| `copilot` | `.github/skills/` |
+| `opencode` | `.opencode/skills/` |
+| `windsurf` | `.windsurf/skills/` |
+
+Use one folder per agent: Gemini CLI also reads `.agents/skills`, and Copilot also reads `.claude/skills` and `.agents/skills`. Installing twice shows every skill twice. See [supported agents](docs/agents.md) for details.
+
+`init` also creates `.tevra/` with the project config, design context and memory. Add `.tevra/` to your `.gitignore`.
+
+Useful variations:
+
+```sh
+tevra-design init                                       # interactive
+tevra-design skills install --agents codex --dry-run    # preview only
+tevra-design init --yes --skip-skills                   # config and context only
+```
+
+The installer never overwrites a file you changed; on any conflict it stops without writing anything.
+
+**3. Restart your agent** in the project so it loads the skills.
+
+## Configure a project
+
+Start your app, then tell Tevra where it runs and which screens matter in `.tevra/config.json`:
+
+```json
+{
+  "baseURL": "http://localhost:3000",
+  "permittedOrigins": ["http://localhost:3000"],
+  "routes": [
+    {
+      "name": "checkout",
+      "path": "/checkout",
+      "states": [
+        { "name": "default", "actions": [], "masks": [] },
+        {
+          "name": "invalid-email",
+          "actions": [
+            { "type": "fill", "selector": "#email", "value": "not-an-email" },
+            { "type": "click", "selector": "button[type=submit]" },
+            { "type": "expect-visible", "selector": "#email-error" }
+          ],
+          "masks": ["[data-testid=order-number]"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Keep the other fields `init` generated (viewports, thresholds, weights). Only `permittedOrigins` may be loaded. `masks` hide private or changing content in screenshots. Never put real credentials or customer data in actions. Full reference: [configuration](docs/configuration.md).
+
+> **Pages behind a login.** The CLI's browser starts signed out. Check those pages by asking your agent to use an already signed-in browser, and keep the CLI for public pages, test environments and CI.
+
+## Quick tour
+
+**Ask your agent:**
+
+```
+The pricing table overflows on mobile, fix it
+/tevra:accessibility-qa check the signup form
+Review this diff before I merge
+```
+
+**Plan and research:**
+
+```sh
+tevra-design workflow plan "Improve pricing card" --mode quick
+tevra-design search "form error validation" --limit 5
+tevra-design analyze
+```
+
+**Verify a running app:**
+
+```sh
+tevra-design doctor --launch                              # browser starts
+tevra-design capture --kind baseline --approve-baseline   # after a human approves the screens
+tevra-design capture && tevra-design compare              # what changed?
+tevra-design a11y                                         # axe on every route, state and viewport
+tevra-design test performance --allow-network             # Lighthouse lab metrics
+tevra-design report                                       # .tevra/reports/quality.{md,json,html}
+```
+
+Exit codes: `0` passed, `1` a check failed, `2` input or environment error. See [usage](docs/usage.md) for workflows, evidence, context and memory.
+
+## Update and uninstall
+
+| | Update | Uninstall |
+| --- | --- | --- |
+| Plugin | `claude plugin marketplace update tevra` then `claude plugin update tevra@tevra` | `claude plugin uninstall tevra@tevra` and `claude plugin marketplace remove tevra` |
+| CLI | `git pull && pnpm install && pnpm build` in your clone | `npm unlink -g tevra-design-kit` |
+| Project skills | Move the old Tevra skill folders aside, then `tevra-design skills install --agents <agent>` | Delete the Tevra skill folders and, if unwanted, `.tevra/` |
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| A skill like `/ui-builder` does not appear | The skills are in another agent's folder, or the session started before the install. Use the plugin, or `--agents claude`, then open a new session |
+| `Installation conflict; preserve local file` | A skill with the same name already exists (for example `design-system`). Use the plugin, or move the existing folder aside |
+| `Marketplace file not found` | Pull the latest `main`; the repository root must contain `.claude-plugin/marketplace.json` |
+| `Unknown agent` | Use one of `codex, claude, cursor, kiro, gemini, copilot, opencode, windsurf` |
+| `doctor` fails or the browser cannot launch | Run `pnpm exec playwright install chromium` in the design-kit clone. Some sandboxes block browsers or local servers; Tevra reports the error instead of faking results |
+| Screenshots show the sign-in page | The route needs a login; see [Configure a project](#configure-a-project) |
+| Capture refuses a URL | Add its origin to `permittedOrigins` |
+| `Mask matches no elements` | Every mask selector must exist on the page; fix or remove it |
+| `Write lock unavailable` | Another Tevra command is running, or one crashed. Remove the stale `.tevra/*.lock` file |
+| Plugin install mentions packages not installed | Expected: the plugin ships skills only; the CLI comes from step B |
+
+## Known limitations
+
+- Automated checks are evidence, not certification. axe and heuristics cannot confirm screen-reader behavior or full WCAG conformance; skills list the manual checks still required.
+- Lighthouse results are lab metrics and do not represent real-user data such as INP.
+- Browser checks cover web pages. Native React Native/Expo apps need device testing.
+- The research catalog is small and local; it cannot report current trends.
+
+## Documentation
+
+| Guide | Contents |
+| --- | --- |
+| [Usage](docs/usage.md) | Skills, workflows, capture, reports, context, memory, examples |
+| [Configuration](docs/configuration.md) | Every config field, actions, privacy, design controls, extensions |
+| [Supported agents](docs/agents.md) | Per-agent install paths and activation |
+| [Architecture](docs/architecture.md) | Packages, capability ownership, workflow and evidence model |
+| [Security](docs/security.md) | Boundaries, protections and limits |
+| [Contributing](docs/contributing.md) | Development setup, checks and release steps |
+| [Changelog](CHANGELOG.md) | Release history |
+
+## License
+
+MIT. See [LICENSE](LICENSE), [PROVENANCE](PROVENANCE.md) and [third-party notices](THIRD_PARTY_NOTICES.md).

package/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: tevra-design
+description: Route product design and frontend work to focused Tevra skills, manage shared decisions and deliver evidence-based visual and accessibility review.
+license: MIT
+---
+
+# Tevra Design Orchestrator
+
+Inspect the active project instructions and design system. Use the smallest workflow that completes the request. `tevra-design analyze` inventories likely sources; `tevra-design plan "<request>" --mode quick|standard|full` creates a local plan with explicit budgets. The CLI does not invoke an AI agent.
+
+- New interface: research → direction → system → builder → responsive → visual review → accessibility.
+- Existing component: redesign → builder → visual review; add accessibility when interaction changes.
+- Screenshot: direction with visible evidence/assumptions → builder → responsive → visual review.
+- Focused motion, responsive or accessibility task: invoke the relevant independent skill.
+
+Read only each selected skill's `SKILL.md` and needed references. Use project-scoped context revisions and transparent memory. Preserve user-approved decisions and public contracts. Use handoffs with exclusive file ownership for future agent dispatch. Record human approval for shared system migrations and transformative changes.
+
+Run available behavior and browser checks; do not fabricate a PASS when a tool is missing. Critical functionality/accessibility failures and failed required tests block delivery. Refine only within the configured retry/time budget. Report outputs, executed checks, evidence and unresolved blockers.
+
+Use `skills list|inspect|validate|graph` for metadata discovery. `workflow run` executes supported local QA stages; design and coding stages need the coding agent and an evidence file to complete. Unsupported integrations are reported as blocked. See `docs/usage.md` for commands.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+## Adapted content
+
+Three guidance records in `references/ux-patterns/catalog.json` (IDs starting with `upstream-`) are adapted from [UI/UX Pro Max `ux-guidelines.csv`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/src/ui-ux-pro-max/data/ux-guidelines.csv), MIT, Copyright (c) 2024 Next Level Builder. The complete notice is bundled at `references/ux-patterns/UPSTREAM-LICENSE.txt`. Wording is shortened; non-universal guidance is kept as advice.
+
+Taste Skill (MIT, Copyright (c) 2026 Leonxlnx) and Web Quality Skills (MIT, Copyright (c) 2026 Addy Osmani) are conceptual references only; no code, text or assets are redistributed.
+
+## Runtime dependencies
+
+| Package | License |
+| --- | --- |
+| Ajv | MIT |
+| YAML | ISC |
+| Playwright | Apache-2.0 (its NOTICE credits Microsoft Corporation and Puppeteer-derived code) |
+| axe-core | MPL-2.0 |
+| Lighthouse | Apache-2.0 |
+| pngjs | MIT |
+| pixelmatch | ISC |
+
+Build, test and example dependencies keep their own notices under `node_modules`. `pnpm-lock.yaml` pins exact transitive versions. No proprietary service or model is required, and no dependency source is modified.
+
+Run `pnpm licenses list` and `pnpm audit` before each release.

package/adapters/claude-code/CLAUDE.md

@@ -0,0 +1,14 @@
+# Tevra with Claude Code
+
+**Recommended:** install the plugin once per machine. Skills are namespaced as `tevra:<skill>`, so they never collide with project skills such as an existing `design-system`.
+
+```sh
+claude plugin marketplace add tevra-si/design-kit
+claude plugin install tevra@tevra
+```
+
+**Per project:** `tevra-design init --yes --agents claude --root <project>` copies skills into `.claude/skills/<name>/SKILL.md`, unnamespaced. The installer refuses to overwrite a same-named skill.
+
+Start a new session after installing; skills load at startup. Invoke them through natural-language requests or `/tevra:<skill>` (plugin) or `/<skill>` (project install). Follow the project's own CLAUDE.md and design system first. Do not replace that file with this note.
+
+Source: https://code.claude.com/docs/en/skills . Managed policy may affect loading.

package/adapters/codex/AGENTS.md

@@ -0,0 +1,5 @@
+# Tevra with Codex
+
+Install using `tevra-design init --yes --agents codex --root <project>`. Native project skills live in `.agents/skills/<name>/SKILL.md`; focused references are copied with each skill. Invoke from the native selector or `$skill-name` where supported. Prioritize project instructions and the current design system.
+
+Source: https://learn.chatgpt.com/docs/build-skills . A managed workspace can protect .agents; report that permission error, use a permitted installation environment and never claim discovery without host evidence. Do not overwrite unrelated AGENTS.md instructions.

package/adapters/cursor/README.md

@@ -0,0 +1,5 @@
+# Tevra with Cursor
+
+Install using `tevra-design init --yes --agents cursor --root <project>`. Project skills live in `.cursor/skills/<name>/SKILL.md` with their focused references. Cursor also documents compatibility paths, but Tevra uses its native project directory to avoid assuming identical agent behavior. Select a skill through `/` in Agent chat where supported.
+
+Source: https://cursor.com/docs/skills . Remote/global sync and managed trust differ from local discovery. Installer tests establish file layout, not host activation.

package/adapters/gemini-cli/README.md

@@ -0,0 +1,5 @@
+# Tevra with Gemini CLI
+
+Install using `tevra-design init --yes --agents gemini --root <project>`. Workspace skills live in `.gemini/skills/<name>/SKILL.md`. Gemini CLI also reads `.agents/skills`, so install either `gemini` or `codex` for a project, not both, to avoid duplicate skill names. Gemini asks for confirmation before activating a matching skill; check with `/skills list`. Keep always-on conventions in GEMINI.md.
+
+Source: https://geminicli.com/docs/cli/skills/ . Installer tests establish file layout, not host activation.

package/adapters/github-copilot/README.md

@@ -0,0 +1,5 @@
+# Tevra with GitHub Copilot
+
+Install using `tevra-design init --yes --agents copilot --root <project>`. Repository skills live in `.github/skills/<name>/SKILL.md` and apply to Copilot agent mode in VS Code, Copilot CLI and the cloud agent. Copilot also reads `.claude/skills` and `.agents/skills`; install only one of `copilot`, `claude` or `codex` when a project uses Copilot to avoid duplicate skill names. Keep repository instructions in `.github/copilot-instructions.md`.
+
+Source: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/create-skills . Installer tests establish file layout, not host activation.

package/adapters/kiro/README.md

@@ -0,0 +1,5 @@
+# Tevra with Kiro
+
+Install using `tevra-design init --yes --agents kiro --root <project>`. Workspace skills live in `.kiro/skills/<name>/SKILL.md` with their focused references. Kiro activates a skill when the request matches its description, or through `/skill-name`. Custom Kiro agents load skills only when their `resources` include `skill://.kiro/skills/**/SKILL.md`. Keep project steering files in `.kiro/steering/`; this adapter does not replace them.
+
+Source: https://kiro.dev/docs/skills/ . Workspace skills override global `~/.kiro/skills` of the same name. Installer tests establish file layout, not host activation.

package/adapters/opencode/README.md

@@ -0,0 +1,5 @@
+# Tevra with OpenCode
+
+Install using `tevra-design init --yes --agents opencode --root <project>`. Project skills live in `.opencode/skills/<name>/SKILL.md`; relative reference links resolve from each skill folder. OpenCode also loads `.claude/skills`; when both exist, `.opencode/skills` wins for the same name, so installing both `claude` and `opencode` is safe but redundant.
+
+Source: https://opencode.ai/docs/skills/ . Installer tests establish file layout, not host activation.

package/adapters/windsurf/README.md

@@ -0,0 +1,5 @@
+# Tevra with Windsurf
+
+Install using `tevra-design init --yes --agents windsurf --root <project>`. Skills install to `.windsurf/skills/<name>/SKILL.md`, which Cascade reads in both older Windsurf releases and current Devin Desktop (whose primary workspace path is `.devin/skills/`). Cascade activates a skill from its description or an `@skill-name` mention. Keep project rules in `.windsurf/rules/`.
+
+Source: https://docs.windsurf.com/windsurf/cascade/skills . The product is changing; verify the path against the installed version. Installer tests establish file layout, not host activation.

package/dist/packages/cli/src/arguments.d.ts

@@ -0,0 +1,9 @@
+export interface Arguments {
+    command: string;
+    positional: string[];
+    flags: Record<string, string | boolean | undefined>;
+}
+export declare function parseCLI(argv: string[]): Arguments;
+export declare function flag(args: Arguments, name: string, fallback?: string): string;
+export declare function numeric(args: Arguments, name: string, fallback?: number): number;
+export declare function inputPath(args: Arguments): string;

package/dist/packages/cli/src/arguments.js

@@ -0,0 +1,58 @@
+import { parseArgs } from 'node:util';
+const boolean = { type: 'boolean' };
+const string = { type: 'string' };
+const specs = {
+    init: { agents: string, yes: boolean, 'skip-skills': boolean }, doctor: { launch: boolean, 'allow-custom-browser': boolean }, analyze: {},
+    'skills list': { registry: string }, 'skills inspect': { registry: string }, 'skills validate': { registry: string }, 'skills graph': { registry: string }, 'skills check': {}, 'skills install': { agents: string, 'dry-run': boolean },
+    validate: {}, 'context show': {}, 'context validate': {}, 'context migrate': { out: string, owner: string }, 'context update': { revision: string, 'approve-constraints': boolean },
+    'memory inspect': {}, 'memory list': {}, 'memory update': { revision: string }, 'memory reset': { yes: boolean },
+    'workflow plan': { registry: string, mode: string, 'max-steps': string, 'max-minutes': string, 'max-refinements': string, out: string },
+    'workflow run': { 'allow-network': boolean, 'allow-custom-browser': boolean },
+    plan: { registry: string, mode: string, 'max-steps': string, 'max-minutes': string, 'max-refinements': string, out: string },
+    'workflow status': {}, 'workflow start': { skill: string }, 'workflow complete': { skill: string, evidence: string }, 'workflow fail': { skill: string, evidence: string }, 'workflow approve': { by: string, yes: boolean },
+    'handoff validate': {}, 'handoff save': {}, search: { category: string, limit: string },
+    'tokens generate': { 'new-system': boolean, brand: string }, 'tokens export': {},
+    'test performance': { 'allow-network': boolean, 'allow-custom-browser': boolean, 'lcp-ms': string, cls: string, 'tbt-ms': string },
+    'test browser': { 'allow-custom-browser': boolean }, 'test visual': { 'allow-custom-browser': boolean }, 'test accessibility': { 'allow-custom-browser': boolean },
+    capture: { kind: string, 'approve-baseline': boolean, 'allow-custom-browser': boolean }, compare: {}, a11y: { 'allow-custom-browser': boolean },
+    report: { checks: string, out: string }, review: { checks: string, out: string, 'allow-custom-browser': boolean }, help: {}
+};
+export function parseCLI(argv) {
+    const words = [...argv];
+    let command = words.shift() ?? 'help';
+    if (command === '--help' || command === '-h')
+        command = 'help';
+    if (['skills', 'context', 'memory', 'workflow', 'handoff', 'tokens', 'test'].includes(command))
+        command += ` ${words.shift() ?? ''}`;
+    const specification = specs[command];
+    if (!specification)
+        throw new Error(`Unknown command: ${command}. Use tevra-design help.`);
+    const result = parseArgs({ args: words, options: { ...specification, root: string, help: boolean }, allowPositionals: true, strict: true });
+    if (!result.values.help && command !== 'help') {
+        const single = ['skills inspect', 'workflow run', 'context migrate', 'context update', 'memory update', 'workflow status', 'workflow start', 'workflow complete', 'workflow fail', 'workflow approve', 'handoff validate', 'handoff save'];
+        const count = result.positionals.length;
+        if (single.includes(command) ? count !== 1 : ['plan', 'workflow plan', 'search'].includes(command) ? count < 1 : command === 'validate' ? count > 1 : count !== 0)
+            throw new Error(`Unexpected positional arguments for ${command}`);
+    }
+    return { command: result.values.help ? 'help' : command, positional: result.positionals, flags: result.values };
+}
+export function flag(args, name, fallback) {
+    const value = args.flags[name];
+    if (typeof value === 'string')
+        return value;
+    if (fallback !== undefined)
+        return fallback;
+    throw new Error(`--${name} is required`);
+}
+export function numeric(args, name, fallback) {
+    const value = Number(flag(args, name, fallback?.toString()));
+    if (!Number.isFinite(value))
+        throw new Error(`--${name} must be a finite number`);
+    return value;
+}
+export function inputPath(args) {
+    if (args.positional.length !== 1 || !args.positional[0])
+        throw new Error('Expected exactly one project-relative input file');
+    return args.positional[0];
+}
+//# sourceMappingURL=arguments.js.map

package/dist/packages/cli/src/arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arguments.js","sourceRoot":"","sources":["../../../../packages/cli/src/arguments.ts"],"names":[],"mappings":"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"}

package/dist/packages/cli/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): Promise<number>;

package/dist/packages/cli/src/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, realpathSync } from 'node:fs';
+import { auditPerformance } from '../../performance-qa/src/index.js';
+import { loadConfig } from '../../core/src/config.js';
+import { loadContext } from '../../design-context/src/index.js';
+import { loadRegistry, registryGraph, validateBundledProvenance } from '../../registry/src/index.js';
+import { safePath } from '../../filesystem/src/index.js';
+import { discoverSkills } from '../../core/src/skills.js';
+import { installSkills } from '../../core/src/install.js';
+import { searchPatterns } from '../../core/src/search.js';
+import { projectRoot, redact } from '../../filesystem/src/index.js';
+import { kitRoot } from '../../filesystem/src/resources.js';
+import { parseCLI, flag, numeric } from './arguments.js';
+import { agents, projectCommand } from './project-commands.js';
+import { runCommand } from './run-command.js';
+import { workflowCommand } from './workflow-commands.js';
+import { visualCommand } from './visual-commands.js';
+const help = `Tevra Design Kit — local agent skills and evidence tools
+
+tevra-design init [--yes --agents codex,claude,cursor,kiro,gemini,copilot,opencode,windsurf | --skip-skills]
+tevra-design doctor [--launch]
+tevra-design analyze
+tevra-design skills list|check|validate|graph [--registry extension.json]
+tevra-design skills inspect <name> [--registry extension.json]
+tevra-design skills install --agents codex,claude,cursor,kiro,gemini,copilot,opencode,windsurf [--dry-run]
+tevra-design validate [design-context.json]
+tevra-design context show|validate
+tevra-design context migrate <legacy.json> [--out .tevra/migrated-context.json --owner name]
+tevra-design context update <candidate.json> --revision N [--approve-constraints]
+tevra-design memory list|inspect|reset [--yes]
+tevra-design memory update <entry.json> --revision N
+tevra-design search "query" [--category ux --limit 5]
+tevra-design plan "request" [--mode quick|standard|full --max-steps 12 --max-minutes 60 --max-refinements 2]
+tevra-design workflow plan "request" [--mode quick|standard|full]
+tevra-design workflow run <plan.json> [--allow-network]
+tevra-design workflow status <plan.json>
+tevra-design workflow start|complete|fail <plan.json> --skill name [--evidence file1,file2]
+tevra-design workflow approve <plan.json> --by human-name --yes
+tevra-design handoff validate|save <handoff.json>
+tevra-design tokens generate --new-system [--brand '#175a44']
+tevra-design tokens export
+tevra-design capture [--kind current|baseline --approve-baseline]
+tevra-design compare
+tevra-design test browser|visual|accessibility [--allow-custom-browser]
+tevra-design test performance --allow-network [--lcp-ms 2500 --cls 0.1 --tbt-ms 200]
+tevra-design a11y
+tevra-design report|review [--checks checks.json --out .tevra/reports/quality.md]
+
+Every command accepts --root <project-directory>. Paths are project-relative.
+Custom executable paths require --allow-custom-browser on doctor/capture/a11y/review.
+Exit: 0 success, 1 quality/check failure, 2 input/environment error.
+The CLI executes local QA adapters; your coding agent executes design/implementation instructions.
+`;
+export async function run(argv) {
+    try {
+        const args = parseCLI(argv);
+        if (args.command === 'help') {
+            process.stdout.write(help);
+            return 0;
+        }
+        const root = await projectRoot(flag(args, 'root', process.cwd()));
+        let result;
+        if (['skills list', 'skills inspect', 'skills validate', 'skills graph'].includes(args.command)) {
+            const extension = typeof args.flags.registry === 'string' ? [await safePath(root, args.flags.registry)] : [];
+            const registry = await loadRegistry(extension);
+            if (args.command === 'skills inspect') {
+                const name = args.positional[0];
+                const entry = registry.skills.find(skill => skill.name === name || skill.id === name);
+                if (!entry)
+                    throw new Error(`Unknown skill: ${name}`);
+                result = entry;
+            }
+            else if (args.command === 'skills graph')
+                result = { format: 'mermaid', graph: registryGraph(registry) };
+            else if (args.command === 'skills validate') {
+                await validateBundledProvenance(registry);
+                const canonical = await discoverSkills(resolve(kitRoot(), 'skills'));
+                for (const skill of canonical)
+                    if (!registry.skills.some(entry => entry.name === skill.name))
+                        throw new Error(`Unregistered skill ${skill.name}`);
+                result = { valid: true, count: registry.skills.length };
+            }
+            else
+                result = registry.skills;
+        }
+        else if (args.command === 'skills check')
+            result = await discoverSkills(resolve(kitRoot(), 'skills'));
+        else if (args.command === 'skills install')
+            result = await installSkills(root, agents(flag(args, 'agents', 'codex')), args.flags['dry-run'] === true);
+        else if (args.command === 'search')
+            result = await searchPatterns(args.positional.join(' '), typeof args.flags.category === 'string' ? args.flags.category : undefined, numeric(args, 'limit', 5));
+        else if (args.command === 'test performance') {
+            const outcome = await auditPerformance(root, await loadConfig(root), (await loadContext(root)).revision, {
+                allowNetwork: args.flags['allow-network'] === true, allowCustomBrowser: args.flags['allow-custom-browser'] === true,
+                budgets: { lcpMs: numeric(args, 'lcp-ms', 2500), cls: numeric(args, 'cls', 0.1), tbtMs: numeric(args, 'tbt-ms', 200) }
+            });
+            process.stdout.write(`${redact(JSON.stringify(outcome, null, 2))}\n`);
+            return outcome.checks.some(check => check.status === 'failed') ? 1 : 0;
+        }
+        else if (['test browser', 'test visual', 'test accessibility'].includes(args.command)) {
+            const command = args.command === 'test visual' ? 'review' : args.command === 'test browser' ? 'browser' : 'a11y';
+            const outcome = await visualCommand({ ...args, command }, root);
+            process.stdout.write(`${redact(JSON.stringify(outcome.result, null, 2))}\n`);
+            return outcome.failed ? 1 : 0;
+        }
+        else if (['capture', 'compare', 'a11y', 'report', 'review'].includes(args.command)) {
+            const outcome = await visualCommand(args, root);
+            process.stdout.write(`${redact(JSON.stringify(outcome.result, null, 2))}\n`);
+            return outcome.failed ? 1 : 0;
+        }
+        else if (args.command === 'workflow run') {
+            const outcome = await runCommand(args, root);
+            process.stdout.write(`${redact(JSON.stringify(outcome, null, 2))}\n`);
+            return typeof outcome === 'object' && outcome !== null && 'status' in outcome && outcome.status === 'passed' ? 0 : 1;
+        }
+        else if (args.command === 'plan' || args.command.startsWith('workflow ') || args.command.startsWith('handoff '))
+            result = await workflowCommand(args, root);
+        else
+            result = await projectCommand(args, root);
+        process.stdout.write(`${redact(JSON.stringify(result, null, 2))}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${redact(error instanceof Error ? error.message : String(error))}\n`);
+        return 2;
+    }
+}
+if (process.argv[1] && existsSync(process.argv[1]) && fileURLToPath(import.meta.url) === realpathSync(process.argv[1]))
+    process.exitCode = await run(process.argv.slice(2));
+//# sourceMappingURL=index.js.map