@thedesignagent/mcp 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @thedesignagent/mcp
 
-MCP server for [TheDesignAgent](https://thedesignagent.ai): UX and visual judgment for UI that coding agents build.
+MCP server and CLI for [TheDesignAgent](https://thedesignagent.ai): UX and visual judgment for UI that coding agents build.
 
 Your agent gets a build brief before it builds a screen, and a scored review after: does the screen serve the user's job, does it follow UX heuristics, does it match your design system. Reviews use a real screenshot when the page is running.
 
@@ -32,6 +32,14 @@ Use the hosted server if you only need briefs and UX reviews. Use this package w
 
 Get an API key (it starts with `tda_`) at [thedesignagent.ai/dashboard/api-keys](https://thedesignagent.ai/dashboard/api-keys).
 
+You can put the key in each client's config as shown below, or save it once for every client and the CLI:
+
+```
+npx -y --package=@thedesignagent/mcp thedesignagent login
+```
+
+That writes `~/.thedesignagent/credentials`, readable only by you. `THEDESIGNAGENT_API_KEY` still wins when it's set, so you can then leave the `env` lines out of the configs below.
+
 ### Claude Code (recommended: the plugin)
 
 The plugin includes this server, plus skills that teach the agent the brief → build → review loop and `/tda:brief` and `/tda:review` commands:
@@ -105,6 +113,134 @@ The package has two commands, so pass `--package` and name `thedesignagent-mcp`
 
 After the first successful `Discover`, write `{ "project_id": "<id>" }` to `.thedesignagent` and commit it, so every agent on the repo shares the same project context.
 
+## Command line and CI
+
+The same package has a `thedesignagent` command for terminals, headless agent runs and CI. `npx thedesignagent` runs it with no install.
+
+```
+npx thedesignagent check http://localhost:3000/checkout --threshold 7
+npx thedesignagent check app/checkout/page.tsx --checks ux
+npx thedesignagent brief "Build the forecast approval queue"
+```
+
+| Command | What it does |
+| --- | --- |
+| `check [url\|file]` | With no target, checks every page listed in `.thedesignagent` (below). Otherwise scores a page from a screenshot (`visual`) or a source file (`ux`). On a URL, `--checks visual,ux --code <file>` runs both (the UX review reads the page's source). `--task` says what the screen is for. |
+| `brief "<task>"` | Writes a build brief to `.thedesignagent-brief.md` (`--out -` prints it). Point any agent at it from AGENTS.md or CLAUDE.md. |
+| `login [key]` | Saves your API key. Reads it from stdin when piped. |
+
+`check` options: `--threshold <n>` exits 1 when a check's overall score is below `n`; `--json` prints the full result (scores, findings, recommendations, screenshot path) for scripts and agents.
+
+Exit codes: `0` ok, `1` below threshold, `2` error (key, network, usage), `3` the page redirected to a login screen (no review ran, nothing charged).
+
+Both commands find the project from `.thedesignagent` in the repo, or `--project <id>`, or `THEDESIGNAGENT_PROJECT_ID`. Commit `.thedesignagent`: CI clones often use a different remote URL than your machine, so the fallback (a hash of the remote URL) can point at a different project. A project's first brief needs a project model, which your coding agent builds on its first `Discover` call; after that the CLI's briefs work anywhere.
+
+### Checking a set of pages
+
+List the pages to check in `.thedesignagent`, and `check` with no target checks them all:
+
+```json
+{
+  "project_id": "proj_...",
+  "check": {
+    "base_url": "http://localhost:3000",
+    "threshold": 7,
+    "pages": [
+      { "path": "/checkout", "task": "Pay for the items in the cart" },
+      { "path": "/orders", "code": "app/orders/page.tsx", "checks": ["visual", "ux"], "threshold": 7.5 }
+    ]
+  }
+}
+```
+
+```
+npx thedesignagent check
+npx thedesignagent check --base-url https://my-app-git-feature.vercel.app
+```
+
+`--base-url` (or `THEDESIGNAGENT_BASE_URL`) points the same pages at a preview deploy. A page's own `threshold` overrides the shared one, and `--threshold` overrides both. `code` paths are relative to the repo root. The run exits 1 if any page is below its threshold, and 3 if a page redirected to login.
+
+### Only the pages a branch changed
+
+`check --changed` diffs the branch against `origin/main` (in GitHub Actions, the pull request's base branch; `--base <ref>` to choose) and checks the Next.js App Router pages it touched. A changed file counts toward the nearest `page.tsx` above it, so editing `app/orders/_components/table.tsx` re-checks `/orders`. Route groups like `(shop)` are handled. Dynamic routes (`[id]`) have no URL to visit, so list a concrete page for them in `.thedesignagent` (with `code` pointing at the page file) and it's checked when that file changes.
+
+```
+npx thedesignagent check --changed --base-url https://my-app-git-feature.vercel.app --threshold 7
+```
+
+### Headless agent runs
+
+Ask the agent to run the check and fix what it finds:
+
+```
+claude -p "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+codex exec "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+grok -p "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+```
+
+Or have the agent write the brief first: `npx thedesignagent brief "Build the checkout page" && claude -p "Read .thedesignagent-brief.md, then build the checkout page."`
+
+### GitHub Actions
+
+Fail a build when a page scores below 7. Add your key as the repository secret `THEDESIGNAGENT_API_KEY`. GitHub's Ubuntu runners include Chrome.
+
+```yaml
+name: Design check
+on: pull_request
+
+jobs:
+  design-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - run: npm start &
+      - run: npx -y wait-on -t 120000 http://localhost:3000/checkout
+      - run: npx -y thedesignagent check http://localhost:3000/checkout --threshold 7
+        env:
+          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}
+```
+
+#### On pull requests: changed pages only, with a PR comment
+
+Check only the pages the pull request touched and post the scores as one comment, updated on every push:
+
+```yaml
+name: Design check
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  design-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - run: npm start &
+      - run: npx -y wait-on -t 120000 http://localhost:3000
+      - run: npx -y thedesignagent check --changed --base-url http://localhost:3000 --threshold 7 --pr-comment
+        env:
+          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+`fetch-depth: 0` lets `--changed` diff against the base branch. The comment lists each page's scores against the threshold, with the top findings and fixes folded under each. If commenting fails (for example without `pull-requests: write`), the check still runs and still sets the exit code.
+
+The score table and the critical and high findings appear on the run's summary page. For pages behind login, set `THEDESIGNAGENT_AUTH_SEED` to an AuthSeed object, `{ "cookies": [...] }` (the format `thedesignagent-auth` saves under `~/.thedesignagent/auth/`), ideally for a test account.
+
 ## Screenshots
 
 `Visual` screenshots `render_url` with your local Chrome, Edge, Brave or Chromium. If it can't find one, set `CHROME_PATH` to the browser binary.
@@ -139,7 +275,9 @@ Check what's saved with `thedesignagent-auth status <url>`.
 
 | Variable | Required | Purpose |
 | --- | --- | --- |
-| `THEDESIGNAGENT_API_KEY` | Yes | Your `tda_` API key |
+| `THEDESIGNAGENT_API_KEY` | Yes, unless you ran `thedesignagent login` | Your `tda_` API key |
+| `THEDESIGNAGENT_PROJECT_ID` | No | Project for the CLI when there's no `.thedesignagent` file |
+| `THEDESIGNAGENT_AUTH_SEED` | No | Session cookies as JSON, for screenshots behind login in CI |
 | `CHROME_PATH` | No | Browser binary for screenshots, if it isn't found automatically |
 | `ANTHROPIC_API_KEY` | No | Enables a fallback review through Claude when TheDesignAgent's API is unreachable |
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,771 @@
+#!/usr/bin/env node
+/**
+ * thedesignagent: TheDesignAgent from a terminal, a headless agent run or CI.
+ *
+ *   check <url|file>   Score a page (screenshot) or a source file. Exit 1 below --threshold.
+ *   brief "<task>"     Write a build brief to .thedesignagent-brief.md for any agent to read.
+ *   login [key]        Save your tda_ API key to ~/.thedesignagent/credentials.
+ *
+ * Exit codes: 0 ok · 1 below threshold · 2 error · 3 page is behind login (nothing charged).
+ */
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline';
+import { captureScreenshot } from './screenshot.js';
+import { loadStoredAuth } from './auth-store.js';
+import { loadApiKey, looksLikeApiKey, saveApiKey, MISSING_KEY_HELP } from './credentials.js';
+const API_BASE = process.env.THEDESIGNAGENT_API_BASE ?? 'https://bxqifcmkydlsgwgcpqda.supabase.co/functions/v1';
+const EDGE_TIMEOUT_MS = 280_000;
+const MAX_ARTIFACT_CHARS = 60_000;
+const BRIEF_FILE = '.thedesignagent-brief.md';
+const EXIT = { ok: 0, belowThreshold: 1, error: 2, authRequired: 3 };
+const USAGE = `Usage: thedesignagent <command> [options]
+
+Commands:
+  check [url|file]    Score a page or a source file; with no target, every page in .thedesignagent
+  brief "<task>"      Write a build brief for the screen you're about to build
+  login [key]         Save your API key (or pipe it on stdin)
+
+check options:
+  --task <text>       What the screen is for (default: a generic review)
+  --checks <list>     visual, ux or visual,ux (default: visual for a URL, ux for a file)
+  --code <file>       Source of the page; needed for --checks ux on a URL
+  --threshold <n>     Exit 1 if a check's overall score is below n (0-10)
+  --base-url <url>    With no target: where the configured pages live (e.g. a preview deploy)
+  --changed           Check only the pages this branch changed (Next.js app/ routes)
+  --pr-comment        In GitHub Actions: post the results as one PR comment, updated on every run
+  --base <ref>        Branch to diff against with --changed (default: origin/main, or the PR base in GitHub Actions)
+  --json              Print the result as JSON
+
+brief options:
+  --out <file>        Where to write the brief (default: ${BRIEF_FILE}; "-" for stdout)
+  --project-model <file>  Project model JSON, for a project's first brief
+  --json              Print the raw result as JSON
+
+Both use the project_id in .thedesignagent, or --project <id>, or THEDESIGNAGENT_PROJECT_ID.
+
+Exit codes: 0 ok, 1 below threshold, 2 error, 3 page is behind login (nothing charged).`;
+// ---- Small helpers --------------------------------------------------------
+class CliError extends Error {
+    code;
+    constructor(message, code = EXIT.error) {
+        super(message);
+        this.code = code;
+    }
+}
+function version() {
+    try {
+        return createRequire(import.meta.url)('../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function requireKey() {
+    const { key } = loadApiKey();
+    if (!key)
+        throw new CliError(MISSING_KEY_HELP);
+    return key;
+}
+function gitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+let cachedConfig;
+// .thedesignagent in the working directory or the repo root.
+function loadConfig() {
+    if (cachedConfig !== undefined)
+        return cachedConfig;
+    cachedConfig = null;
+    for (const dir of [process.cwd(), gitRoot()]) {
+        if (!dir)
+            continue;
+        const file = join(dir, '.thedesignagent');
+        if (!existsSync(file) || !statSync(file).isFile())
+            continue;
+        try {
+            cachedConfig = { config: JSON.parse(readFileSync(file, 'utf-8')), dir };
+        }
+        catch {
+            throw new CliError(`${file} is not valid JSON. Expected { "project_id": "proj_..." }.`);
+        }
+        break;
+    }
+    return cachedConfig;
+}
+function resolveProject(flag) {
+    const explicit = flag ?? process.env.THEDESIGNAGENT_PROJECT_ID;
+    if (explicit)
+        return { project_id: explicit };
+    const id = loadConfig()?.config.project_id;
+    if (id)
+        return { project_id: id };
+    // Same recipe as the agent skills. CI clones often use a different remote
+    // URL (https vs ssh), which hashes differently, so commit .thedesignagent.
+    try {
+        const remote = execSync('git remote get-url origin', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (remote)
+            return { repo_hash: createHash('sha256').update(remote).digest('hex') };
+    }
+    catch { /* not a git repo */ }
+    throw new CliError('No project found. Run this in a repo with a .thedesignagent file, or pass --project <id>.');
+}
+async function callEdge(path, body) {
+    let response;
+    try {
+        response = await fetch(`${API_BASE}/${path}`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${requireKey()}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(EDGE_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        if (e instanceof CliError)
+            throw e;
+        throw new CliError(`Couldn't reach TheDesignAgent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (response.ok)
+        return await response.json();
+    let err = {};
+    try {
+        err = await response.json();
+    }
+    catch { /* non-JSON error body */ }
+    const message = err.message ?? `HTTP ${response.status}`;
+    if (response.status === 401 || response.status === 403) {
+        throw new CliError(`Authentication failed: ${message}\nCheck your API key (THEDESIGNAGENT_API_KEY or "thedesignagent login").`);
+    }
+    if (response.status === 402)
+        throw new CliError(message);
+    if (response.status === 429)
+        throw new CliError(`Rate limit reached: ${message}`);
+    throw new CliError(`${path} failed (${response.status}): ${message}${err.detail ? `\nDetail: ${err.detail}` : ''}`);
+}
+function isUrl(target) {
+    return /^https?:\/\//i.test(target);
+}
+function readArtifact(path) {
+    const abs = resolve(path);
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        throw new CliError(`File not found: ${path}`);
+    const text = readFileSync(abs, 'utf-8');
+    return text.length > MAX_ARTIFACT_CHARS ? text.slice(0, MAX_ARTIFACT_CHARS) + '\n/* truncated */' : text;
+}
+function parseChecks(raw, target) {
+    if (!raw)
+        return isUrl(target) ? ['visual'] : ['ux'];
+    const names = raw.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    for (const n of names) {
+        if (n !== 'visual' && n !== 'ux')
+            throw new CliError(`Unknown check "${n}". Use visual, ux or visual,ux.`);
+    }
+    return [...new Set(names)];
+}
+function parseThreshold(raw) {
+    if (raw === undefined)
+        return null;
+    if (raw.trim() === '')
+        throw new CliError('--threshold is empty. Pass a number from 0 to 10.');
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0 || n > 10)
+        throw new CliError(`--threshold must be a number from 0 to 10, got "${raw}".`);
+    return n;
+}
+function envAuthSeed() {
+    const raw = process.env.THEDESIGNAGENT_AUTH_SEED;
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError('THEDESIGNAGENT_AUTH_SEED is not valid JSON.');
+    }
+}
+function defaultTask(target) {
+    return isUrl(target) ? `Review the page at ${new URL(target).pathname}` : `Review the UI in ${target}`;
+}
+function validateSpec(spec) {
+    if (isUrl(spec.target) && spec.checks.includes('ux') && !spec.code) {
+        throw new CliError(`The ux check reviews source code, not a screenshot. Pass the page's source with --code <file> (or "code" in .thedesignagent), or use --checks visual. (${spec.target})`);
+    }
+}
+async function checkPage(spec, identity, json) {
+    const url = isUrl(spec.target) ? spec.target : undefined;
+    const artifact = url
+        ? (spec.code ? readArtifact(spec.code) : `The rendered page at ${url}. Judge it from the screenshot.`)
+        : readArtifact(spec.target);
+    let screenshot;
+    if (url && spec.checks.includes('visual')) {
+        status(json, `Screenshotting ${url}…`);
+        const seed = envAuthSeed() ?? loadStoredAuth(url) ?? undefined;
+        const shot = await captureScreenshot(url, seed).catch((e) => {
+            throw new CliError(`Screenshot failed: ${e instanceof Error ? e.message : String(e)}`);
+        });
+        if (shot.authRequired) {
+            return {
+                result: { target: spec.target, screenshot: null, authRequired: true, finalUrl: shot.finalUrl, outcomes: [] },
+                identity,
+            };
+        }
+        screenshot = { base64: shot.base64, localPath: shot.localPath };
+    }
+    const outcomes = [];
+    let callIdentity = identity;
+    for (const check of spec.checks) {
+        status(json, `Running ${check} review${url ? ` of ${url}` : ''}…`);
+        const result = check === 'visual'
+            ? await callEdge('visual', {
+                task: spec.task, artifact, ...callIdentity,
+                ...(screenshot && { screenshot: screenshot.base64 }),
+                ...(url && { render_url: url }),
+            })
+            : await callEdge('ux', { task: spec.task, artifact, ...callIdentity });
+        // Later calls use the project the first one resolved, so an unknown id
+        // or a repo_hash doesn't create a second project.
+        if (result.project_id)
+            callIdentity = { project_id: result.project_id };
+        const score = (check === 'visual' ? result.visual_score : result.ux_score) ?? NaN;
+        outcomes.push({
+            check,
+            score,
+            passed: spec.threshold === null ? null : score >= spec.threshold,
+            summary: result.summary,
+            scores: result.scores ?? {},
+            findings: result.findings ?? [],
+            recommendations: result.recommendations ?? [],
+            degradations: result.degradations ?? [],
+        });
+    }
+    return {
+        result: { target: spec.target, screenshot: screenshot?.localPath ?? null, authRequired: false, outcomes },
+        identity: callIdentity,
+    };
+}
+function loginHelp(r) {
+    return [
+        `${r.target} redirected to a login page (${r.finalUrl}). No review ran and nothing was charged.`,
+        'Save a session first:',
+        `  npx -y --package=@thedesignagent/mcp thedesignagent-auth capture ${r.target}`,
+        'In CI, set THEDESIGNAGENT_AUTH_SEED to an AuthSeed object ({ "cookies": [...] }), or check a preview with protection bypass.',
+    ].join('\n');
+}
+// Pages from .thedesignagent: { "check": { "base_url", "threshold", "pages": [...] } }.
+function configuredSpecs(opts, thresholdFlag) {
+    const loaded = loadConfig();
+    const cfg = loaded?.config.check;
+    if (!cfg?.pages?.length) {
+        throw new CliError([
+            'Nothing to check. Pass a URL or file, or list pages in .thedesignagent:',
+            '  { "project_id": "proj_...", "check": { "base_url": "http://localhost:3000", "threshold": 7,',
+            '    "pages": [ { "path": "/checkout", "task": "Pay for the cart" } ] } }',
+        ].join('\n'));
+    }
+    const base = opts['base-url'] ?? process.env.THEDESIGNAGENT_BASE_URL ?? cfg.base_url;
+    const flagChecks = opts.checks ? parseChecks(opts.checks, 'http://x') : undefined;
+    return cfg.pages.map((page, i) => {
+        if (!page?.path)
+            throw new CliError(`.thedesignagent check.pages[${i}] needs a "path".`);
+        const isAbsolute = isUrl(page.path);
+        if (!isAbsolute && !base) {
+            throw new CliError(`No base URL for "${page.path}". Set check.base_url in .thedesignagent, or pass --base-url.`);
+        }
+        const target = isAbsolute ? page.path : new URL(page.path, base).href;
+        const configThreshold = page.threshold ?? cfg.threshold;
+        return {
+            target,
+            task: page.task ?? defaultTask(target),
+            code: page.code && loaded ? resolve(loaded.dir, page.code) : undefined,
+            checks: flagChecks ?? page.checks ?? ['visual'],
+            threshold: thresholdFlag ?? (typeof configThreshold === 'number' ? configThreshold : null),
+        };
+    });
+}
+// ---- --changed: map a branch's changed files to the routes they render ----
+const PAGE_FILE = /^page\.(tsx|jsx|ts|js|mdx)$/;
+function changedFiles(base) {
+    const ref = base
+        ?? (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'origin/main');
+    try {
+        return execSync(`git diff --name-only --diff-filter=d ${JSON.stringify(ref)}...HEAD`, { stdio: ['ignore', 'pipe', 'pipe'] })
+            .toString().split('\n').map(l => l.trim()).filter(Boolean);
+    }
+    catch {
+        throw new CliError(`Couldn't diff against ${ref}. Fetch it first (in CI: actions/checkout with fetch-depth: 0), or pass --base <ref>.`);
+    }
+}
+// Next.js App Router: app/(group)/orders/page.tsx -> /orders. Dynamic
+// segments ([id]) have no URL to visit, so they're skipped unless
+// .thedesignagent lists a concrete page for them.
+function routeForAppDir(segments) {
+    const parts = [];
+    for (const seg of segments) {
+        if (seg.startsWith('(') && seg.endsWith(')'))
+            continue;
+        if (seg.startsWith('@') || seg.startsWith('_'))
+            return null;
+        if (seg.startsWith('['))
+            return null;
+        parts.push(seg);
+    }
+    return '/' + parts.join('/');
+}
+// For each changed file, the nearest enclosing App Router page: a change to
+// app/orders/_components/table.tsx re-checks /orders.
+function pagesForChangedFiles(root, files) {
+    const found = new Map();
+    for (const file of files) {
+        if (!/\.(tsx|jsx|ts|js|mdx|css|scss)$/.test(file))
+            continue;
+        const parts = file.split('/');
+        const appIdx = parts.findIndex((p, i) => p === 'app' && (i === 0 || (i === 1 && parts[0] === 'src')));
+        if (appIdx === -1)
+            continue;
+        for (let end = parts.length - 1; end > appIdx; end--) {
+            const dir = parts.slice(0, end);
+            const page = ['tsx', 'jsx', 'ts', 'js', 'mdx'].map(ext => [...dir, `page.${ext}`].join('/'))
+                .find(candidate => existsSync(join(root, candidate)));
+            if (!page)
+                continue;
+            const route = routeForAppDir(dir.slice(appIdx + 1));
+            if (route && !found.has(route))
+                found.set(route, { route, pageFile: page });
+            break;
+        }
+    }
+    return [...found.values()];
+}
+function changedSpecs(opts, thresholdFlag) {
+    const root = gitRoot();
+    if (!root)
+        throw new CliError('--changed needs a git repository.');
+    const files = changedFiles(opts.base);
+    const loaded = loadConfig();
+    const cfg = loaded?.config.check;
+    const base = opts['base-url'] ?? process.env.THEDESIGNAGENT_BASE_URL ?? cfg?.base_url;
+    if (!base)
+        throw new CliError('No base URL. Pass --base-url, set THEDESIGNAGENT_BASE_URL, or set check.base_url in .thedesignagent.');
+    const flagChecks = opts.checks ? parseChecks(opts.checks, 'http://x') : undefined;
+    const changed = new Set(files);
+    const specs = new Map();
+    const add = (route, page, pageFile) => {
+        const target = isUrl(route) ? route : new URL(route, base).href;
+        if (specs.has(target))
+            return;
+        const t = page?.threshold ?? cfg?.threshold;
+        specs.set(target, {
+            target,
+            task: page?.task ?? defaultTask(target),
+            code: page?.code && loaded ? resolve(loaded.dir, page.code) : pageFile ? join(root, pageFile) : undefined,
+            checks: flagChecks ?? page?.checks ?? ['visual'],
+            threshold: thresholdFlag ?? (typeof t === 'number' ? t : null),
+        });
+    };
+    // Listed pages whose source changed, then routes found from the diff
+    // (using the listed page's task and threshold when the route matches).
+    for (const page of cfg?.pages ?? []) {
+        if (page.code && changed.has(page.code.replace(/^\.\//, '')))
+            add(page.path, page, undefined);
+    }
+    for (const { route, pageFile } of pagesForChangedFiles(root, files)) {
+        add(route, cfg?.pages?.find(p => p.path === route), pageFile);
+    }
+    return [...specs.values()];
+}
+async function runCheck(target, opts) {
+    const thresholdFlag = parseThreshold(opts.threshold);
+    if (target && opts.changed)
+        throw new CliError('Pass a target or --changed, not both.');
+    const specs = opts.changed
+        ? changedSpecs(opts, thresholdFlag)
+        : target
+            ? [{
+                    target,
+                    task: opts.task ?? defaultTask(target),
+                    code: opts.code,
+                    checks: parseChecks(opts.checks, target),
+                    threshold: thresholdFlag,
+                }]
+            : configuredSpecs(opts, thresholdFlag);
+    specs.forEach(validateSpec);
+    if (!specs.length) {
+        if (opts['pr-comment'])
+            await postPrComment(`${COMMENT_MARKER}\n### TheDesignAgent design check: no UI pages changed`, opts.pr);
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, passed: true, project_id: null, pages: [] }, null, 2));
+        else
+            console.log('No changed UI pages to check.');
+        return EXIT.ok;
+    }
+    let identity = resolveProject(opts.project);
+    requireKey();
+    const results = [];
+    for (const spec of specs) {
+        const { result, identity: next } = await checkPage(spec, identity, opts.json);
+        identity = next;
+        results.push(result);
+    }
+    const failed = results.some(r => r.outcomes.some(o => o.passed === false));
+    const loginBlocked = results.filter(r => r.authRequired);
+    const anyThreshold = specs.some(s => s.threshold !== null);
+    const passed = anyThreshold ? !failed && loginBlocked.length === 0 : null;
+    if (opts.json) {
+        const pageJson = (r, spec) => ({
+            target: r.target,
+            threshold: spec.threshold,
+            screenshot: r.screenshot,
+            ...(r.authRequired && { error: 'auth_required', message: loginHelp(r), final_url: r.finalUrl }),
+            checks: r.outcomes,
+        });
+        const body = target
+            // One target keeps the flat shape.
+            ? { ok: !results[0].authRequired, passed, project_id: identity.project_id ?? null, ...pageJson(results[0], specs[0]) }
+            : { ok: loginBlocked.length === 0, passed, project_id: identity.project_id ?? null, pages: results.map((r, i) => pageJson(r, specs[i])) };
+        console.log(JSON.stringify(body, null, 2));
+    }
+    else {
+        results.forEach((r, i) => {
+            if (r.authRequired)
+                console.error(loginHelp(r));
+            else
+                console.log(formatCheck(r.target, r.outcomes, specs[i].threshold, r.screenshot ?? undefined));
+            if (i < results.length - 1)
+                console.log('');
+        });
+    }
+    results.forEach((r, i) => { if (!r.authRequired)
+        writeStepSummary(r.target, r.outcomes, specs[i].threshold); });
+    if (opts['pr-comment'])
+        await postPrComment(prCommentBody(results, specs), opts.pr);
+    if (failed)
+        return EXIT.belowThreshold;
+    if (loginBlocked.length)
+        return EXIT.authRequired;
+    return EXIT.ok;
+}
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'];
+const severityRank = (s) => { const i = SEVERITY_ORDER.indexOf(s); return i === -1 ? SEVERITY_ORDER.length : i; };
+function fmt(n) {
+    return n === null || n === undefined || Number.isNaN(n) ? 'n/a' : n.toFixed(1);
+}
+function verdict(o, threshold) {
+    if (o.passed === null)
+        return '';
+    return o.passed ? `  pass (threshold ${threshold})` : `  FAIL (threshold ${threshold})`;
+}
+function formatCheck(target, outcomes, threshold, shotPath) {
+    const lines = [`TheDesignAgent · ${target}`, ''];
+    for (const o of outcomes) {
+        lines.push(`${o.check} ${fmt(o.score)}/10${verdict(o, threshold)}`);
+        lines.push('  ' + Object.entries(o.scores).map(([k, v]) => `${k} ${fmt(v)}`).join(' · '));
+        if (o.degradations.length)
+            lines.push(`  degraded: ${o.degradations.join(', ')}`);
+        lines.push('', `  ${o.summary}`, '');
+        const top = [...o.findings]
+            .sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+            .slice(0, 5);
+        for (const f of top) {
+            const loc = f.location ? ` (${f.location})` : '';
+            lines.push(`  [${f.severity}] ${f.dimension ?? f.track ?? 'general'}: ${f.description}${loc}`);
+        }
+        if (o.recommendations.length) {
+            lines.push('', '  Fix first:');
+            for (const r of o.recommendations.slice(0, 3))
+                lines.push(`  - ${r.change}`);
+        }
+        lines.push('');
+    }
+    if (shotPath)
+        lines.push(`Screenshot: ${shotPath}`);
+    return lines.join('\n').trimEnd();
+}
+// GitHub Actions shows this file on the run's summary page.
+function writeStepSummary(target, outcomes, threshold) {
+    const path = process.env.GITHUB_STEP_SUMMARY;
+    if (!path)
+        return;
+    const rows = outcomes.map(o => {
+        const result = o.passed === null ? '' : o.passed ? 'pass' : 'fail';
+        return `| ${o.check} | ${fmt(o.score)} | ${result} |`;
+    });
+    const findings = outcomes.flatMap(o => o.findings
+        .filter(f => f.severity === 'critical' || f.severity === 'high')
+        .map(f => `- **${o.check} · ${f.severity}**: ${f.description}`));
+    const md = [
+        `### TheDesignAgent: ${target}`,
+        '',
+        `| Check | Score | ${threshold === null ? '' : `Threshold ${threshold}`} |`,
+        '| --- | --- | --- |',
+        ...rows,
+        '',
+        ...(findings.length ? ['**Critical and high findings**', '', ...findings, ''] : []),
+    ].join('\n');
+    try {
+        appendFileSync(path, md + '\n');
+    }
+    catch { /* summary is best-effort */ }
+}
+// ---- --pr-comment: one comment per pull request, updated on every run ----
+const COMMENT_MARKER = '<!-- thedesignagent-check -->';
+function prCommentBody(results, specs) {
+    const failed = results.some(r => r.outcomes.some(o => o.passed === false));
+    const blocked = results.filter(r => r.authRequired);
+    const headline = failed
+        ? '❌ Below threshold'
+        : blocked.length ? `⚠️ ${blocked.length} page${blocked.length > 1 ? 's' : ''} couldn't be checked (login)`
+            : specs.some(s => s.threshold !== null) ? '✅ Passed' : 'Scores';
+    const pagePath = (target) => { try {
+        return new URL(target).pathname;
+    }
+    catch {
+        return target;
+    } };
+    const rows = [];
+    results.forEach((r, i) => {
+        if (r.authRequired) {
+            rows.push(`| \`${pagePath(r.target)}\` | | | ${specs[i].threshold ?? ''} | login required |`);
+            return;
+        }
+        for (const o of r.outcomes) {
+            const result = o.passed === null ? '' : o.passed ? 'pass' : '**fail**';
+            rows.push(`| \`${pagePath(r.target)}\` | ${o.check} | ${fmt(o.score)} | ${specs[i].threshold ?? ''} | ${result} |`);
+        }
+    });
+    const details = [];
+    for (const r of results) {
+        for (const o of r.outcomes) {
+            const top = [...o.findings].sort((a, b) => severityRank(a.severity) - severityRank(b.severity)).slice(0, 5);
+            if (!top.length && !o.recommendations.length)
+                continue;
+            details.push(`<details><summary><code>${pagePath(r.target)}</code> · ${o.check} ${fmt(o.score)}</summary>`, '', o.summary, '', ...top.map(f => `- **${f.severity}** ${f.dimension ?? f.track ?? 'general'}: ${f.description}${f.location ? ` (${f.location})` : ''}`), ...(o.recommendations.length ? ['', '**Fix first**', ...o.recommendations.slice(0, 3).map(rc => `- ${rc.change}`)] : []), '', '</details>');
+        }
+    }
+    return [
+        COMMENT_MARKER,
+        `### TheDesignAgent design check: ${headline}`,
+        '',
+        '| Page | Check | Score | Threshold | Result |',
+        '| --- | --- | --- | --- | --- |',
+        ...rows,
+        '',
+        ...details,
+    ].join('\n');
+}
+function pullRequestNumber(flag) {
+    if (flag)
+        return Number(flag) || null;
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (!eventPath || !existsSync(eventPath))
+        return null;
+    try {
+        const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+        return event.pull_request?.number ?? event.number ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Best-effort: a failed comment never changes the check's exit code.
+async function postPrComment(body, prFlag) {
+    const token = process.env.GITHUB_TOKEN;
+    const repo = process.env.GITHUB_REPOSITORY;
+    const pr = pullRequestNumber(prFlag);
+    if (!token || !repo || !pr) {
+        console.error('--pr-comment: skipped. It needs GITHUB_TOKEN, GITHUB_REPOSITORY and a pull_request event (or --pr <number>).');
+        return;
+    }
+    const api = process.env.GITHUB_API_URL ?? 'https://api.github.com';
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+    };
+    try {
+        let existing = null;
+        for (let page = 1; page <= 10 && existing === null; page++) {
+            const res = await fetch(`${api}/repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`, { headers });
+            if (!res.ok)
+                throw new Error(`listing comments: HTTP ${res.status}`);
+            const comments = await res.json();
+            existing = comments.find(c => c.body?.startsWith(COMMENT_MARKER))?.id ?? null;
+            if (comments.length < 100)
+                break;
+        }
+        const res = existing
+            ? await fetch(`${api}/repos/${repo}/issues/comments/${existing}`, { method: 'PATCH', headers, body: JSON.stringify({ body }) })
+            : await fetch(`${api}/repos/${repo}/issues/${pr}/comments`, { method: 'POST', headers, body: JSON.stringify({ body }) });
+        if (!res.ok)
+            throw new Error(`${existing ? 'updating' : 'posting'} comment: HTTP ${res.status}`);
+    }
+    catch (e) {
+        const hint = String(e).includes('403') ? ' Give the job "permissions: pull-requests: write".' : '';
+        console.error(`--pr-comment: couldn't comment on PR #${pr}: ${e instanceof Error ? e.message : String(e)}.${hint}`);
+    }
+}
+function status(json, msg) {
+    // Progress goes to stderr so --json stdout stays parseable.
+    if (!json && process.stderr.isTTY)
+        console.error(msg);
+}
+async function runBrief(task, opts) {
+    const identity = resolveProject(opts.project);
+    let projectModel;
+    if (opts.projectModel) {
+        try {
+            projectModel = JSON.parse(readFileSync(resolve(opts.projectModel), 'utf-8'));
+        }
+        catch (e) {
+            throw new CliError(`Couldn't read --project-model: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    status(opts.json, 'Getting a build brief…');
+    const result = await callEdge('discovery', {
+        task, ...identity, ...(projectModel && { projectModel }),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result.status === 'ok' ? EXIT.ok : EXIT.error;
+    }
+    if (result.status !== 'ok') {
+        const why = result.status === 'needs_setup'
+            ? 'This project has no stored model yet.'
+            : 'The stored project model is out of date with your schema.';
+        console.error([
+            why,
+            'Run one brief from your coding agent (it scans the repo and builds the model),',
+            'or build the model yourself and pass it with --project-model <file>. The extraction task:',
+            '',
+            result.extraction_task ?? '(none returned)',
+        ].join('\n'));
+        return EXIT.error;
+    }
+    const md = [
+        `# Build brief: ${task}`,
+        '',
+        `Project ${result.project_id}${result.active_job ? ` · active job: ${result.active_job}` : ''}`,
+        `Generated by TheDesignAgent ${new Date().toISOString().slice(0, 10)}. Follow it while building this screen.`,
+        '',
+        result.brief ?? '',
+        '',
+    ].join('\n');
+    const out = opts.out ?? BRIEF_FILE;
+    if (out === '-') {
+        process.stdout.write(md);
+    }
+    else {
+        writeFileSync(resolve(out), md);
+        console.log(`Wrote ${out}. Point your agent at it, e.g. add "Read ${out} before building UI." to AGENTS.md or CLAUDE.md.`);
+    }
+    if (!identity.project_id && result.project_id) {
+        console.error(`Tip: save { "project_id": "${result.project_id}" } to .thedesignagent and commit it, so CI and every agent share this project.`);
+    }
+    return EXIT.ok;
+}
+// ---- login ----------------------------------------------------------------
+async function readKeyInteractively() {
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks).toString('utf-8').trim();
+    }
+    console.error('Get a key at https://thedesignagent.ai/dashboard/api-keys');
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    // Hide what's typed: the key is a secret and terminals get recorded.
+    const rlOut = rl;
+    let prompted = false;
+    rlOut._writeToOutput = (s) => {
+        if (!prompted) {
+            rlOut.output.write(s);
+            prompted = true;
+        }
+    };
+    rl.on('SIGINT', () => {
+        rl.close();
+        process.stderr.write('\n');
+        process.exit(130);
+    });
+    const key = await new Promise(res => rl.question('Paste your API key: ', res));
+    rl.close();
+    process.stderr.write('\n');
+    return key.trim();
+}
+async function runLogin(keyArg) {
+    const key = (keyArg ?? await readKeyInteractively()).trim();
+    if (!looksLikeApiKey(key)) {
+        throw new CliError('That doesn\'t look like a TheDesignAgent key. Keys start with tda_.');
+    }
+    const path = saveApiKey(key);
+    console.log(`Saved to ${path} (readable only by you).`);
+    if (process.env.THEDESIGNAGENT_API_KEY) {
+        console.error('Note: THEDESIGNAGENT_API_KEY is set in this shell and takes precedence over the saved key.');
+    }
+    return EXIT.ok;
+}
+// ---- main -----------------------------------------------------------------
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            task: { type: 'string' },
+            checks: { type: 'string' },
+            code: { type: 'string' },
+            threshold: { type: 'string' },
+            json: { type: 'boolean' },
+            project: { type: 'string' },
+            'base-url': { type: 'string' },
+            changed: { type: 'boolean' },
+            'pr-comment': { type: 'boolean' },
+            pr: { type: 'string' },
+            base: { type: 'string' },
+            out: { type: 'string' },
+            'project-model': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    if (values.version) {
+        console.log(version());
+        return EXIT.ok;
+    }
+    const [command, ...rest] = positionals;
+    if (values.help || !command) {
+        console.log(USAGE);
+        return command || values.help ? EXIT.ok : EXIT.error;
+    }
+    switch (command) {
+        case 'check':
+            if (rest.length > 1)
+                throw new CliError('Usage: thedesignagent check [url|file] [--threshold n] [--json]');
+            return runCheck(rest[0], values);
+        case 'brief':
+            if (!rest.length)
+                throw new CliError('Usage: thedesignagent brief "<what you are about to build>"');
+            return runBrief(rest.join(' '), { ...values, projectModel: values['project-model'] });
+        case 'login':
+            return runLogin(rest[0]);
+        default:
+            throw new CliError(`Unknown command "${command}".\n\n${USAGE}`);
+    }
+}
+// Set exitCode rather than calling process.exit(): on macOS, stdout to a pipe
+// is async, and exiting early truncates large --json output.
+const wantsJson = process.argv.includes('--json');
+main().then(code => { process.exitCode = code; }, (e) => {
+    // parseArgs throws TypeError with a readable message for bad flags.
+    const message = e instanceof Error ? e.message : String(e);
+    if (wantsJson)
+        console.log(JSON.stringify({ ok: false, error: 'error', message }, null, 2));
+    console.error(message);
+    process.exitCode = e instanceof CliError ? e.code : EXIT.error;
+});

package/dist/credentials.d.ts

@@ -0,0 +1,8 @@
+export declare const CREDENTIALS_PATH: string;
+export declare function looksLikeApiKey(key: string): boolean;
+export declare function loadApiKey(): {
+    key?: string;
+    source: 'env' | 'file' | 'none';
+};
+export declare function saveApiKey(key: string): string;
+export declare const MISSING_KEY_HELP: string;

package/dist/credentials.js

@@ -0,0 +1,44 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// One key file for every client: MCP hosts with no standard way to prompt for
+// a key (Agent Plugins, Cursor, Copilot) and the CLI both read it. The env var
+// still wins, so CI and existing MCP configs behave as before.
+export const CREDENTIALS_PATH = join(homedir(), '.thedesignagent', 'credentials');
+export function looksLikeApiKey(key) {
+    return /^tda_[A-Za-z0-9_-]{8,}$/.test(key);
+}
+export function loadApiKey() {
+    const fromEnv = process.env.THEDESIGNAGENT_API_KEY?.trim();
+    if (fromEnv)
+        return { key: fromEnv, source: 'env' };
+    try {
+        if (!existsSync(CREDENTIALS_PATH))
+            return { source: 'none' };
+        const parsed = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf-8'));
+        if (typeof parsed.api_key === 'string' && parsed.api_key.trim()) {
+            return { key: parsed.api_key.trim(), source: 'file' };
+        }
+    }
+    catch {
+        // Unreadable or malformed: treat as missing; `login` rewrites it.
+    }
+    return { source: 'none' };
+}
+export function saveApiKey(key) {
+    const dir = dirname(CREDENTIALS_PATH);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Write a fresh 0600 file and rename it over the old one, so the key is
+    // never briefly readable through an existing file's looser mode.
+    const tmp = `${CREDENTIALS_PATH}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ api_key: key }, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, CREDENTIALS_PATH);
+    return CREDENTIALS_PATH;
+}
+export const MISSING_KEY_HELP = [
+    'No TheDesignAgent API key found.',
+    'Get one at https://thedesignagent.ai/dashboard/api-keys, then either:',
+    '  - run: npx -y --package=@thedesignagent/mcp thedesignagent login',
+    '  - or set the THEDESIGNAGENT_API_KEY environment variable.',
+].join('\n');

package/dist/index.js

@@ -28,7 +28,10 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { captureScreenshot } from './screenshot.js';
 import { loadStoredAuth } from './auth-store.js';
-const API_KEY = process.env.THEDESIGNAGENT_API_KEY;
+import { loadApiKey, MISSING_KEY_HELP } from './credentials.js';
+// Read per call: a key saved with `thedesignagent login` after the server
+// started still takes effect without a restart.
+const apiKey = () => loadApiKey().key;
 const API_BASE = process.env.THEDESIGNAGENT_API_BASE ?? 'https://bxqifcmkydlsgwgcpqda.supabase.co/functions/v1';
 // Discover/Ux route through the hosted gateway so mcp_call_logs telemetry
 // captures local-stdio calls too. Visual stays direct because it needs local
@@ -41,7 +44,7 @@ async function callGatewayTool(name, args) {
         response = await fetch(`${GATEWAY_BASE}/mcp`, {
             method: 'POST',
             headers: {
-                Authorization: `Bearer ${API_KEY}`,
+                Authorization: `Bearer ${apiKey()}`,
                 'Content-Type': 'application/json',
                 'Accept': 'application/json',
             },
@@ -341,9 +344,9 @@ function formatDiscoveryResult(result) {
 }
 // ---- Tool handlers --------------------------------------------------------
 async function handleUxCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set. Add it to your MCP server config.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             isError: true,
         };
     }
@@ -421,9 +424,9 @@ async function handleUxCall(args) {
     }
 }
 async function handleVisualCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             isError: true,
         };
     }
@@ -439,7 +442,7 @@ async function handleVisualCall(args) {
     try {
         const response = await fetch(`${API_BASE}/visual`, {
             method: 'POST',
-            headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+            headers: { Authorization: `Bearer ${apiKey()}`, 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 task: args.task,
                 artifact: args.artifact,
@@ -465,7 +468,7 @@ async function handleVisualCall(args) {
         const err = await response.json();
         if (response.status === 401 || response.status === 403) {
             return {
-                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your THEDESIGNAGENT_API_KEY.` }],
+                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your API key (THEDESIGNAGENT_API_KEY or "thedesignagent login").` }],
                 isError: true,
             };
         }
@@ -492,9 +495,9 @@ async function handleVisualCall(args) {
     }
 }
 async function handleDiscoverCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             isError: true,
         };
     }
@@ -534,7 +537,7 @@ const evalInputSchema = {
     repo_hash: z.string().optional().describe('SHA256 of git remote origin URL (fallback if no .thedesignagent)'),
     codebase_context: z.string().optional().describe('Optional surrounding code context'),
 };
-const server = new McpServer({ name: 'TheDesignAgent', version: '0.3.1' });
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.4.0' });
 server.registerTool('Discover', {
     description: `Get a build brief calibrated to your project, persona, and the specific screen you're building.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.3.1",
-  "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
+  "version": "0.4.0",
+  "description": "MCP server and CLI for TheDesignAgent \u2014 UX and visual judgment layer for agent-generated UI",
   "license": "MIT",
   "type": "module",
   "homepage": "https://thedesignagent.ai",
@@ -14,11 +14,14 @@
     "design-system",
     "claude-code",
     "codex",
-    "ai-agents"
+    "ai-agents",
+    "cli",
+    "ci"
   ],
   "bin": {
     "thedesignagent-mcp": "dist/index.js",
-    "thedesignagent-auth": "dist/auth-capture.js"
+    "thedesignagent-auth": "dist/auth-capture.js",
+    "thedesignagent": "dist/cli.js"
   },
   "files": [
     "dist"