tevra-design-kit 0.0.0-stage → 1.0.0

package/dist/packages/workflow-engine/src/index.js

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import { transitionPlan } from '../../core/src/workflow.js';
+import { validate } from '../../design-context/src/validation.js';
+import { loadContext } from '../../design-context/src/index.js';
+import { readJSON, redact, withLock, writeJSON } from '../../filesystem/src/index.js';
+export async function runWorkflow(root, path, adapters) {
+    return withLock(root, '.tevra/runner.lock', async () => {
+        let plan = validate('plan.schema.json', await readJSON(root, path));
+        const revision = (await loadContext(root)).revision;
+        if (plan.contextRevision !== revision)
+            throw new Error('Workflow context revision is stale');
+        if (plan.approvalRequired && !plan.approvedBy)
+            throw new Error('Human approval required before executing this high-impact workflow');
+        if (plan.steps.length > plan.budget.maxSteps || new Set(plan.steps.map(step => step.skill)).size !== plan.steps.length)
+            throw new Error('Invalid workflow step budget or duplicate skills');
+        for (const [index, step] of plan.steps.entries())
+            for (const dependency of step.dependsOn)
+                if (!plan.steps.slice(0, index).some(candidate => candidate.skill === dependency))
+                    throw new Error(`Dependency must precede ${step.skill}: ${dependency}`);
+        for (const step of [...plan.steps]) {
+            if (step.status === 'passed' || step.status === 'skipped')
+                continue;
+            if (step.status === 'running')
+                throw new Error(`Stage already running: ${step.skill}; inspect its previous attempt before recovery`);
+            if (step.dependsOn.some(dependency => plan.steps.find(candidate => candidate.skill === dependency)?.status !== 'passed'))
+                continue;
+            while (step.attempts < plan.budget.maxRefinements + 1) {
+                plan = await transitionPlan(root, path, step.skill, 'running', [], revision);
+                const started = plan.steps.find(candidate => candidate.skill === step.skill);
+                if (!started)
+                    throw new Error('Workflow stage disappeared');
+                step.attempts = started.attempts;
+                const artifact = `.tevra/workflow-runs/${randomUUID()}.json`;
+                let result;
+                try {
+                    const adapter = adapters[step.skill];
+                    result = adapter ? await adapter() : { status: 'blocked', evidence: [], message: 'This skill requires the coding agent to execute its instructions and submit validation evidence; no supported automatic agent adapter is configured.' };
+                }
+                catch (error) {
+                    result = { status: 'blocked', evidence: [], message: redact(error instanceof Error ? error.message : String(error)) };
+                }
+                await writeJSON(root, artifact, { skill: step.skill, contextRevision: revision, ...result });
+                plan = await transitionPlan(root, path, step.skill, result.status, [artifact, ...result.evidence], revision);
+                if (result.status !== 'failed')
+                    break;
+            }
+        }
+        return { status: plan.steps.some(step => step.status === 'failed') ? 'failed' : plan.steps.every(step => step.status === 'passed') ? 'passed' : 'blocked', plan };
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/workflow-engine/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/workflow-engine/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAItF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,QAAsC;IAClG,OAAO,QAAQ,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,IAAI,EAAE;QACrD,IAAI,IAAI,GAAG,QAAQ,CAAO,kBAAkB,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAG,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpD,IAAI,IAAI,CAAC,eAAe,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC7F,IAAI,IAAI,CAAC,gBAAgB,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACrI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAC5L,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;YAAE,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,UAAU,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC,CAAC;QACtP,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;gBAAE,SAAS;YACpE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,KAAK,gDAAgD,CAAC,CAAC;YACrI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,UAAU,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC;gBAAE,SAAS;YACnI,OAAO,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;gBACtD,IAAI,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;gBAC7E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC7E,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;gBAC5D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;gBACjC,MAAM,QAAQ,GAAG,wBAAwB,UAAU,EAAE,OAAO,CAAC;gBAC7D,IAAI,MAAmB,CAAC;gBACxB,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACrC,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,sJAAsJ,EAAE,CAAC;gBAC5O,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBACxH,CAAC;gBACD,MAAM,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;gBAC7F,IAAI,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC7G,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ;oBAAE,MAAM;YACxC,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACpK,CAAC,CAAC,CAAC;AACL,CAAC"}

package/docs/agents.md

@@ -0,0 +1,36 @@
+# Supported agents
+
+Tevra skills follow the open [Agent Skills format](https://agentskills.io/specification), so the same folders work across agents. Only the install location differs.
+
+| Agent | Install | Skills folder | How skills activate | Notes |
+| --- | --- | --- | --- | --- |
+| Claude Code | Plugin (recommended) | managed by Claude Code | Description match or `/tevra:<skill>` | Namespaced, so no clash with project skills. [Details](../adapters/claude-code/CLAUDE.md) |
+| Claude Code | `--agents claude` | `.claude/skills/` | Description match or `/<skill>` | Refuses to overwrite a same-named skill |
+| Codex | `--agents codex` | `.agents/skills/` | Native selector or `$<skill>` | [Details](../adapters/codex/AGENTS.md) |
+| Cursor | `--agents cursor` | `.cursor/skills/` | `/` in Agent chat | [Details](../adapters/cursor/README.md) |
+| Kiro | `--agents kiro` | `.kiro/skills/` | Description match or `/<skill>` | Custom agents need `skill://.kiro/skills/**/SKILL.md` in `resources`. [Details](../adapters/kiro/README.md) |
+| Gemini CLI | `--agents gemini` | `.gemini/skills/` | Description match, with confirmation | Also reads `.agents/skills`. [Details](../adapters/gemini-cli/README.md) |
+| GitHub Copilot | `--agents copilot` | `.github/skills/` | Agent mode, Copilot CLI, cloud agent | Also reads `.claude/skills` and `.agents/skills`. [Details](../adapters/github-copilot/README.md) |
+| OpenCode | `--agents opencode` | `.opencode/skills/` | Loaded on relevance | Also reads `.claude/skills`; `.opencode/skills` wins. [Details](../adapters/opencode/README.md) |
+| Windsurf / Devin Desktop | `--agents windsurf` | `.windsurf/skills/` | Description match or `@<skill>` | Devin Desktop prefers `.devin/skills/` but still reads this path. [Details](../adapters/windsurf/README.md) |
+
+## Avoid duplicate skills
+
+Some agents read more than one folder. Installing Tevra into two folders that the same agent reads shows every skill twice. Pick one per agent:
+
+- Gemini CLI: `gemini` **or** `codex`
+- GitHub Copilot: `copilot`, `claude` **or** `codex`
+- OpenCode: `opencode` (or rely on `claude`)
+
+## Installing for several agents
+
+```sh
+tevra-design init --yes --agents codex,cursor,kiro
+tevra-design skills install --agents opencode --dry-run   # preview without writing
+```
+
+Each skill folder is self-contained and carries its own references. The installer checks every destination first and aborts the whole install if any file differs from the bundled copy, so local edits are never lost.
+
+## Verifying activation
+
+A successful copy does not prove an agent loaded the skill. Agent trust settings, managed policies and versions can affect loading. After installing, open a new agent session and ask for a small task (for example "check the accessibility of the login page") or list skills in the agent's UI.

package/docs/architecture.md

@@ -0,0 +1,86 @@
+# Architecture
+
+Tevra is two things in one repository:
+
+1. **Twelve Agent Skills** (`skills/<name>/SKILL.md` plus focused references). They are plain Markdown that any agent supporting the [Agent Skills format](https://agentskills.io/specification) can load. They work without the CLI.
+2. **A TypeScript CLI** (`packages/*`) that plans workflows and produces verifiable evidence. It never invokes an LLM; the coding agent does the design and implementation work.
+
+```
+            ┌──────────────┐   reads    ┌──────────────────────┐
+  you ────▶ │ coding agent │ ─────────▶ │ skills/*/SKILL.md    │
+            └──────┬───────┘            └──────────────────────┘
+                   │ runs
+                   ▼
+            ┌──────────────┐  writes   ┌──────────────────────────────┐
+            │ tevra-design │ ────────▶ │ .tevra/  config, context,    │
+            └──────────────┘           │ memory, plans, screenshots,  │
+                                       │ diffs, reports               │
+                                       └──────────────────────────────┘
+```
+
+## Packages
+
+Dependencies flow one way: `cli` → feature engines (`workflow-engine` → `core` → `registry`, plus `visual-testing`, `quality-engine`, `performance-qa`, `design-memory`) → `design-context` → `contracts` and `filesystem`. No engine imports the CLI. Runtime and type-only imports follow the same direction, and cycles are not allowed.
+
+| Package | Responsibility |
+| --- | --- |
+| `contracts` | Shared types and enums (skill names, plans, handoffs, checks) |
+| `filesystem` | The only write path: project-root boundary, traversal and symlink rejection, atomic writes, locks, secret redaction |
+| `design-context` | Versioned context schema, explicit migration, optimistic revisions, token foundation and export |
+| `design-memory` | Inspectable project decisions with revisioned updates and confirmed reset |
+| `registry` | Skill metadata validation, capability ownership, dependency and conflict resolution |
+| `core` | Skill discovery, installation, request routing, BM25 search, workflow state and handoffs |
+| `workflow-engine` | Executes the QA stages of a plan with retry budgets |
+| `visual-testing` | Playwright capture, axe, runtime errors, overflow and target heuristics, PNG comparison |
+| `performance-qa` | Lighthouse subprocess and budget checks |
+| `quality-engine` | Weighted scoring, blockers and JSON/Markdown/HTML reports |
+| `cli` | Strict argument parsing, setup and command dispatch |
+
+## Skills and capability ownership
+
+`registry/skills.json` describes each skill (capabilities, dependencies, conflicts, frameworks, platforms, supported agents, inputs, outputs) without loading its instructions. Each capability has exactly one owner, so two skills never do the same job in one plan:
+
+| Capability | Owner | Evidence it produces |
+| --- | --- | --- |
+| UX research | design-research | Cited recommendations with confidence |
+| Visual direction | design-direction | Approved rationale and design controls |
+| Tokens | design-system | Schema-valid tokens and exports |
+| Implementation | ui-builder | Working code, build and behavior checks |
+| Redesign | ui-redesign | Invariant table and before/after evidence |
+| Responsive | responsive-design | Screenshots and overflow findings |
+| Motion | interaction-motion | Interaction and reduced-motion evidence |
+| Visual regression | visual-review | PNG diffs and rubric findings |
+| Accessibility | accessibility-qa | axe results plus manual checklist |
+| Browser testing | browser-testing | Assertions, console and network errors |
+| Performance | performance-qa | Lighthouse lab artifacts |
+| Code review | frontend-review | File and line findings |
+
+Selection is deterministic: filter by framework, platform and agent; use an explicit override or the highest priority (ties broken by ID); expand dependencies in topological order; reject conflicts visibly. Third parties can add skills through a registry extension file without changing core code.
+
+## Workflow model
+
+`workflow plan` routes a request to a skill chain and records steps, dependencies, mode, step/time/refinement budgets, the context revision and whether human approval is required. Stages move through `pending → running → passed | failed | blocked | skipped`.
+
+- Design and implementation stages are completed by the coding agent with an evidence file.
+- `workflow run` executes Tevra's own QA stages. A missing browser, app or integration produces `blocked`, never a pass.
+- Failed stages retry up to the plan's refinement budget; blocked stages are not retried automatically.
+- Stale context, concurrent runs, unapproved high-impact work and invalid dependency order fail before anything executes.
+
+## Evidence and quality gates
+
+Capture output is partitioned by route, state, viewport and capture kind, and is identified by hashes of the screenshots, manifest and settings. Comparisons and reports refuse mismatched or stale inputs. Evidence is labeled by kind (deterministic, heuristic, AI, human) and the report keeps them apart. Critical failures and missing required checks block PASS even when the weighted score is high.
+
+## Context and multi-agent handoff
+
+The design context (`.tevra/design-context.json`, format version 2.0) holds project identity, brand, approved direction, tokens, responsive requirements, known regressions and provenance. Older context formats migrate explicitly and non-destructively. Updates require the current revision; approved decisions are immutable.
+
+Handoffs (`schemas/handoff.schema.json`) carry the task ID, objective, artifacts, context revision, owner, exclusive file claims, constraints, acceptance criteria, evidence, status and error. Tevra rejects stale revisions and overlapping file ownership so agents working in parallel do not overwrite each other.
+
+## Design decisions
+
+1. **Local first.** All state lives in the project's `.tevra/` folder. Tevra never commits, uploads or calls a model endpoint.
+2. **No simulated success.** A missing browser or tool is an error, not a skipped pass.
+3. **Validate at boundaries.** External JSON and YAML go through strict JSON Schemas (Ajv); internals use TypeScript types.
+4. **Small dependency set.** Ajv, YAML, Playwright, axe-core, pngjs, pixelmatch and Lighthouse. Tokens export as portable CSS variables and a CSS-first Tailwind adapter.
+5. **Self-contained skills.** Each skill folder ships its own narrowly chosen references and installs independently.
+6. **Humans own approvals.** Baselines, transformative redesigns and shared-system changes need an explicit recorded decision.

package/docs/configuration.md

@@ -0,0 +1,109 @@
+# Configuration
+
+`tevra-design init` creates `.tevra/config.json`. To start from a reviewed file instead, place a `tevra.config.json` in the project root before running `init`. The file is validated against [`schemas/config.schema.json`](../schemas/config.schema.json); unknown fields are rejected.
+
+## Minimal example
+
+```json
+{
+  "version": 1,
+  "baseURL": "http://localhost:3000",
+  "permittedOrigins": ["http://localhost:3000"],
+  "viewports": [
+    { "name": "mobile", "width": 390, "height": 844 },
+    { "name": "desktop", "width": 1440, "height": 900 }
+  ],
+  "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]"],
+          "waitFor": "#email-error"
+        }
+      ]
+    }
+  ],
+  "browser": {},
+  "timeoutMs": 15000,
+  "thresholds": { "diffRatio": 0.01, "pixelSensitivity": 0.1, "minScore": 75 },
+  "weights": {
+    "hierarchy": 15, "typography": 10, "layout": 15, "consistency": 10,
+    "responsive": 15, "accessibility": 15, "interaction": 0, "functional": 10, "performance": 10
+  },
+  "requiredChecks": ["visual-diff", "axe", "overflow", "functional-tests"],
+  "maxRefinements": 2
+}
+```
+
+## Fields
+
+| Field | Meaning |
+| --- | --- |
+| `baseURL` | Where the app runs. No credentials, query string or fragment |
+| `permittedOrigins` | Exact HTTP(S) origins the browser may load. Requests to anything else are blocked; add asset or API origins explicitly |
+| `viewports` | Named width × height profiles. Defaults: 390×844, 768×1024, 1280×800, 1440×900. Add intermediate or landscape sizes your product needs |
+| `routes[].states` | Named page conditions to capture. Names use lowercase letters, digits and hyphens |
+| `states[].actions` | Steps to reach the state (see below) |
+| `states[].masks` | CSS/Playwright selectors hidden in screenshots. Each must match at least one element or capture fails |
+| `states[].waitFor` | Selector that must be visible before capture |
+| `readySelector` | Optional marker awaited before any action, useful for client-side hydration |
+| `colorScheme` | `light` (default), `dark` or `no-preference` |
+| `reducedMotion` | `reduce` (default, for repeatable captures) or `no-preference` |
+| `browser` | `channel` (for example `chrome`, `msedge`) or `executablePath` |
+| `timeoutMs` | Upper bound for browser waits |
+| `thresholds.diffRatio` | Fraction of changed pixels allowed before a diff fails (0–1) |
+| `thresholds.pixelSensitivity` | Color difference that counts as "changed" (0–1) |
+| `thresholds.minScore` | Minimum rubric score (0–100). `0` disables the subjective-score requirement; required checks still apply |
+| `weights` | Rubric weights, totalling 100 |
+| `requiredChecks` | Check IDs that must pass for delivery |
+| `maxRefinements` | Default retry budget for new plans |
+
+### Actions
+
+Actions use a closed vocabulary; arbitrary scripts are not supported.
+
+| `type` | Uses | Effect |
+| --- | --- | --- |
+| `click` | `selector` | Clicks the element |
+| `fill` | `selector`, `value` | Types into a field |
+| `press` | `selector`, `value` | Presses a key on the element |
+| `check` | `selector` | Checks a checkbox or radio |
+| `expect-visible` / `expect-hidden` | `selector` | Asserts visibility |
+| `expect-text` | `selector`, `value` | Asserts the element contains text |
+| `expect-checked` | `selector` | Asserts a checked state |
+
+Selectors are Playwright locators, so `button:has-text('Save')` works. `test browser` requires at least one `expect-*` assertion in every state; a click that does not throw is not evidence that the feature works.
+
+## Privacy
+
+- Never put real passwords, tokens or customer data in `value`. Use sample data.
+- Mask anything private that can appear on screen (names, emails, ID numbers, plate numbers). Text redaction in reports cannot detect arbitrary personal data inside images.
+- Reports redact URL query strings and common secret patterns.
+- The kit's browser starts without cookies or storage, so pages behind a login redirect to your sign-in page. Test those pages with an agent that uses an already signed-in browser, or point Tevra at a test environment with public routes.
+
+## Design controls
+
+Visual direction is described with three integers from 1 to 10, stored in the design context:
+
+| Control | Context field | Low values | High values |
+| --- | --- | --- | --- |
+| Variance | `design.variance` | Familiar composition | Experimental composition with explicit usability checks |
+| Motion intensity | `design.motionIntensity` | State feedback only | Rich transitions with a documented task benefit and reduced-motion equivalent |
+| Visual density | `design.visualDensity` | Reading-oriented | Dense comparison views |
+
+Defaults are 5, 3 and 5. Controls never override accessibility, approved brand rules or project constraints.
+
+## Extending Tevra
+
+- **Research catalog:** add records to `references/ux-patterns/catalog.json` with a stable ID, source, license and confidence, plus a relevance test.
+- **Third-party skills:** describe them in a registry extension file that follows `schemas/skill-registry.schema.json` and pass it with `--registry extension.json` to `skills list|inspect|validate|graph`. Extensions are metadata; they cannot register commands or executables.
+- **Framework guidance:** add a focused file under `references/frameworks/` and link it from the skill that needs it, rather than loading every framework for every task.

package/docs/contributing.md

@@ -0,0 +1,75 @@
+# Contributing
+
+## Setup
+
+```sh
+pnpm install
+pnpm build
+pnpm exec playwright install chromium
+```
+
+## Checks
+
+```sh
+pnpm typecheck
+pnpm test                    # unit + integration
+pnpm test:structure          # axe on the built example apps
+pnpm test:examples           # acceptance-app model tests
+pnpm test:legacy             # Python context validator
+pnpm skills:check            # skill metadata and links
+pnpm test:e2e                # real browser: screenshots, diffs, axe, task flows
+node --import tsx --test tests/unit/router.test.ts   # a single file
+```
+
+`test:e2e` builds first and needs a machine that allows starting Chromium and local servers. Build the examples before `test:structure` and `test:e2e`:
+
+```sh
+pnpm --filter @tevra/example-nextjs build
+pnpm --filter @tevra/example-sveltekit build
+pnpm --filter @tevra/acceptance-app build
+```
+
+CI (`.github/workflows/ci.yml`) runs all of the above on every push and pull request.
+
+## Measuring skill impact
+
+`evals/` holds cases for `claude plugin eval`. Each run compares Claude with and without the plugin on the same prompt and reports the score delta.
+
+```sh
+claude plugin eval . --runs 3 --no-publish --max-cost-usd 5
+```
+
+Add a case when you change a skill's behavior: a realistic `prompt.md` and `graders/*.md` that describe observable outcomes. Results go to `evals/results/` (gitignored). Single runs are noisy; report deltas only from several runs.
+
+## Demo images
+
+`docs/assets/` and `.claude-plugin/icon.png` are rendered from a real run, never mocked. Reproduce the before/after run from the README ("See it in action"), then:
+
+```sh
+pnpm demo:assets
+```
+
+## Editing skills
+
+- `skills/` is the only source of truth. `.claude/` and `.cursor/` in this repository are local installs and are gitignored; refresh them with `tevra-design skills install`.
+- Start every `description` with what the skill does, then a "Use when…" sentence with the words people actually type. Agents choose skills from that line.
+- Keep `SKILL.md` short. Put conditional detail in `references/` and link it.
+- Keep `registry/skills.json` in sync with skill names and descriptions.
+- Run `pnpm skills:check` after every change.
+
+## Code
+
+- Dependencies point one way (see [architecture](architecture.md)). No cycles, including type-only imports.
+- Validate external input with a schema in `schemas/`. Keep internal types strict.
+- Write all files through `packages/filesystem`; never write outside the project root.
+- Production modules stay under about 300 logical lines; split only at a real ownership boundary.
+- Add a test for every changed behavior.
+- Write all repository content in English. Vietnamese keywords in `packages/core/src/router.ts` and `references/ux-patterns/catalog.json` are intentional search terms.
+
+## Before a release
+
+- Bump `version` in `package.json`, `packages/*/package.json`, `examples/*/package.json`, `.claude-plugin/plugin.json`, `registry/skills.json` and the skill frontmatter together, and add a [changelog](../CHANGELOG.md) entry.
+- Check the npm contents with `npm pack --dry-run`, then publish with `npm publish`.
+- Run every check above, plus `pnpm audit` and `pnpm licenses list`.
+- Install the plugin and each adapter in a fresh project and confirm the skills load.
+- Report any check you could not run as unverified, not as passing.

package/docs/security.md

@@ -0,0 +1,42 @@
+# Security
+
+Tevra treats everything it reads as data, never as instructions: external references, screenshots, project configuration and skill catalogs. It configures no model endpoint, no upload client and no arbitrary shell command.
+
+## Boundaries
+
+| Boundary | Protection | Covered by |
+| --- | --- | --- |
+| Project paths | Relative paths only; traversal, absolute paths and symlinked ancestors are rejected | `tests/integration/project.test.ts` |
+| Concurrent writes | Exclusive locks, atomic replacement, expected revisions | Context, memory and workflow tests |
+| Agent ownership | Canonical file claims, stale-revision checks, overlapping owners rejected | Router and handoff tests |
+| Skill installation | Every destination is preflighted and rechecked; changed files are never overwritten | Adapter integration tests |
+| Browser executable | Channels from a closed list; a custom path needs `--allow-custom-browser` | Custom executable regression test |
+| Browser network | Only configured origins load; requests and WebSockets are intercepted; fresh context; downloads and service workers blocked | E2E browser tests |
+| Browser actions | Closed vocabulary (`click`, `fill`, `press`, `check`, `expect-*`); no scripts in config | Config schema |
+| Lighthouse | Subprocess with an argument array, no shell; network access only with `--allow-network` | Performance unit tests |
+| PNG input | Header and dimension budget checked before decoding | Invalid and oversized PNG tests |
+| Evidence integrity | Hashes for screenshots, manifests and settings; failed captures and stale comparisons are rejected | CLI pipeline tests |
+| Reports and memory | Secret patterns and URL queries redacted; secret-like memory entries rejected; Markdown escaped | Quality and memory tests |
+| Human decisions | Approved history protected; resets, constraint changes and baselines need explicit flags | Context, memory and workflow tests |
+
+## Limits to be aware of
+
+- File locks coordinate cooperating tools. They do not protect against an administrator or a hostile process running as the same user.
+- `workflow approve --by NAME` records a decision. It is not identity verification.
+- Redaction finds common secret formats in text. It cannot detect arbitrary personal data, and never inside screenshots. Mask private regions before capture.
+- Lighthouse may load every resource origin a page requests once `--allow-network` is given. Only audit apps whose third-party requests you have reviewed.
+- Automated browser checks do not certify screen-reader behavior, native apps or full WCAG conformance.
+
+## Before a release
+
+```sh
+pnpm audit
+pnpm licenses list
+pnpm test && pnpm test:structure && pnpm test:e2e
+```
+
+Run these on a machine that allows browser launch and local servers.
+
+## Reporting a vulnerability
+
+Do not open a public issue. Contact the Tevra maintainers privately with steps to reproduce and the affected version.

package/docs/usage.md

@@ -0,0 +1,142 @@
+# Usage
+
+Tevra has two halves that work together:
+
+- **Skills** are instructions your coding agent reads and follows. You use them by asking the agent for something.
+- **The `tevra-design` CLI** plans work and produces evidence: screenshots, pixel diffs, axe results, Lighthouse metrics and quality reports. It never calls an LLM.
+
+Every command accepts `--root <project>`; other paths are relative to that project. Run `tevra-design help` for the full list.
+
+**Exit codes:** `0` success, `1` a check or quality gate failed (or a workflow is blocked), `2` invalid input or environment error. Read the JSON output as well as the exit code.
+
+## Working with skills
+
+Ask for the outcome in plain language; the agent picks the matching skill from its description. You can also name one directly (`/tevra:ui-redesign` with the Claude Code plugin, `/ui-redesign` with a project install).
+
+| You want to… | Skill chain the router suggests |
+| --- | --- |
+| Build a new screen | research → direction → system → builder → responsive → visual review → accessibility |
+| Improve an existing component | redesign → builder → visual review |
+| Turn a screenshot into code | direction → builder → responsive → visual review → accessibility |
+| Fix one concern (motion, responsive, accessibility, performance, tests, review) | that skill alone, plus the builder when code changes |
+
+Preview the chain before starting:
+
+```sh
+tevra-design workflow plan "Improve this pricing card" --mode quick
+```
+
+| Mode | Behavior |
+| --- | --- |
+| `quick` | Drops general research and secondary steps; no retries |
+| `standard` | Default chain with a refinement budget |
+| `full` | Adds accessibility and QA stages (frontend review, browser testing, performance) |
+
+Plans record steps, dependencies, step/time/refinement budgets and the context revision. Work that changes shared tokens or brand, or a transformative redesign, is marked `approvalRequired` and waits for a human.
+
+## Research and design data
+
+```sh
+tevra-design analyze                                        # detected framework, styling, design-system files, agent instructions
+tevra-design search "form error validation mobile" --category ux --limit 5
+tevra-design tokens generate --new-system --brand '#175a44' # only when the project has no tokens yet
+tevra-design tokens export                                  # JSON, tokens.css and CSS-first Tailwind under .tevra/exports
+```
+
+`search` ranks a small local catalog by lexical relevance (BM25). Results carry source, confidence and license; a high score means "matches the words", not "is true". It cannot tell what is currently trending.
+
+`tokens generate` refuses to run when tokens already exist. Exports never modify your application theme; you choose what to import.
+
+## Checking a running app
+
+Start the app first, then configure its origin, routes and states in `.tevra/config.json` (see [configuration](configuration.md)).
+
+```sh
+tevra-design doctor --launch                              # browser can start
+tevra-design capture --kind baseline --approve-baseline   # after a human approves the current screens
+tevra-design capture                                      # current screenshots for every route/state/viewport
+tevra-design compare                                      # pixel diff against the baseline
+tevra-design a11y                                         # fresh capture with axe results
+tevra-design report                                       # .tevra/reports/quality.{json,md,html}
+```
+
+Shortcuts that bundle these steps:
+
+```sh
+tevra-design test browser          # requires explicit assertions in every state
+tevra-design test visual           # capture + compare + report
+tevra-design test accessibility
+tevra-design test performance --allow-network --lcp-ms 2500 --cls 0.1 --tbt-ms 200
+tevra-design review                # capture → compare → report
+```
+
+What each capture records:
+
+- Screenshots per route, state and viewport, with dynamic regions masked
+- axe violations and incomplete rules (WCAG 2.0–2.2 A/AA tags)
+- Console errors, failed requests and HTTP errors as separate findings
+- Overflow and touch-target heuristics
+- The browser version, context revision and a hash of the capture settings
+
+Comparison fails when the configuration, screenshot set, browser version or context revision does not match the baseline. Reports refuse stale comparisons or failed captures.
+
+**Baselines are protected.** They are created only with `--approve-baseline` and never overwritten by `compare`. To replace one, archive the baseline folder yourself after review, then capture again.
+
+**Performance** runs Lighthouse in a separate browser. `--allow-network` is required because the page may load third-party resources; review those origins first. Results are lab metrics (LCP, CLS, TBT) and do not represent real-user data such as INP.
+
+## Adding your own evidence
+
+Agents and humans can add checks that automation cannot make, such as a keyboard walkthrough, a screen-reader pass or a design judgment:
+
+```sh
+tevra-design report --checks review-checks.json
+```
+
+Checks follow `schemas/checks.schema.json`. Each check names its evidence kind (`deterministic`, `heuristic`, `ai` or `human`) and points to an existing local file as evidence. Add a passing `functional-tests` check only after actually running the behavior tests. The report keeps the four evidence kinds separate.
+
+The default rubric scores eight categories (hierarchy, typography, layout, consistency, responsive, accessibility, functional, performance). A category without evidence stays unscored. A critical failure or a missing required check blocks PASS regardless of the total.
+
+## Executing a workflow
+
+```sh
+tevra-design workflow plan "Build a dashboard" --mode full
+tevra-design workflow start  .tevra/plans/PLAN.json --skill design-research
+tevra-design workflow complete .tevra/plans/PLAN.json --skill design-research --evidence design-research.md
+tevra-design workflow run    .tevra/plans/PLAN.json        # runs the local QA stages
+tevra-design workflow status .tevra/plans/PLAN.json
+tevra-design workflow approve .tevra/plans/PLAN.json --by "Product owner" --yes
+```
+
+The coding agent carries out design and implementation stages, then marks them complete with an evidence file. `workflow run` executes the stages Tevra can run itself (browser, visual, accessibility, performance). Stages missing an app, browser or integration are reported `blocked`, never passed. Failed stages retry up to the plan's refinement budget. `approve` records a named human decision; it is not authentication.
+
+## Shared context and memory
+
+```sh
+tevra-design context show
+tevra-design context validate
+tevra-design context update candidate.json --revision 3 [--approve-constraints]
+tevra-design context migrate old-context.json --out .tevra/migrated-context.json
+tevra-design memory list
+tevra-design memory update entry.json --revision 2
+tevra-design memory reset --yes
+tevra-design handoff validate handoff.json
+tevra-design handoff save handoff.json
+```
+
+- **Context** (`.tevra/design-context.json`) holds brand, approved direction, tokens, responsive requirements, known regressions and provenance. Updates must quote the current revision. Approved decisions cannot be replaced by ordinary updates; append a superseding decision. Changing constraints needs `--approve-constraints`.
+- **Memory** (`.tevra/memory.json`) is plain, inspectable JSON for decisions such as directions, rejected options and conventions. Entries that look like secrets are rejected. Reset needs `--yes`.
+- **Handoffs** let several agents share work safely: each declares the files it owns, and Tevra rejects stale context revisions or overlapping file claims.
+
+Nothing under `.tevra/` is committed or uploaded by Tevra.
+
+## Examples
+
+The repository includes runnable apps to try every command against:
+
+| Example | What it shows | Start |
+| --- | --- | --- |
+| `examples/nextjs-dashboard` | Task app: add, validate, complete, remove, empty state | `pnpm --filter @tevra/example-nextjs build && pnpm --filter @tevra/example-nextjs start` (port 4173) |
+| `examples/sveltekit-workspace` | The same app in SvelteKit | `pnpm --filter @tevra/example-sveltekit build && pnpm --filter @tevra/example-sveltekit start` (port 4174) |
+| `examples/acceptance-app` | Analytics filters, pricing calculator and dialog, form validation, before/after redesign | see its [README](../examples/acceptance-app/README.md) |
+
+Each example has a reviewed `tevra.config.json`. Point the CLI at it with `--root`, for example `tevra-design capture --root examples/nextjs-dashboard`.

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "tevra-design-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Portable design agent skills and evidence-based local quality tools",
+  "type": "module",
+  "license": "MIT",
+  "author": "Tevra",
+  "homepage": "https://github.com/tevra-si/design-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tevra-si/design-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tevra-si/design-kit/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "ai-agents",
+    "design-system",
+    "accessibility",
+    "axe",
+    "visual-regression",
+    "playwright",
+    "lighthouse",
+    "frontend",
+    "qa"
+  ],
+  "bin": {
+    "tevra-design": "dist/packages/cli/src/index.js"
+  },
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
+  "packageManager": "pnpm@11.1.3",
+  "files": [
+    "dist/packages",
+    "SKILL.md",
+    "skills",
+    "references",
+    "schemas",
+    "adapters",
+    "templates",
+    "rubrics",
+    "LICENSE",
+    "PROVENANCE.md",
+    "THIRD_PARTY_NOTICES.md",
+    "docs",
+    "registry",
+    "!docs/assets"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test tests/unit/*.test.ts tests/integration/*.test.ts",
+    "test:e2e": "pnpm build && node --test dist/tests/e2e/*.test.js",
+    "test:legacy": "python3 -m unittest discover -s tests -p 'test_*.py' -v",
+    "test:structure": "node --import tsx --test tests/structure/*.test.ts",
+    "skills:check": "node --import tsx packages/cli/src/index.ts skills check",
+    "tevra-design": "node dist/packages/cli/src/index.js",
+    "prepack": "pnpm build",
+    "test:examples": "node --test tests/examples/*.test.mjs",
+    "demo:assets": "node scripts/render-demo-assets.mjs"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "axe-core": "4.11.0",
+    "pixelmatch": "8.0.0",
+    "playwright": "1.63.0",
+    "pngjs": "7.0.0",
+    "yaml": "2.8.1",
+    "lighthouse": "13.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "@types/pngjs": "6.0.5",
+    "@types/jsdom": "^27.0.0",
+    "jsdom": "30.1.2",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}