Tell Proof

Independent visual proof for AI-built interfaces.

Tell Proof captures the UI that users actually see, names the visual tells that make it feel generic or inconsistent, drafts a source-grounded repair, and verifies the result in a disposable checkout before anything touches your app.

Demo · Why Tell · Features · Quick Start · Cursor MCP · Architecture · Deploy

Demo

• Live app: tell-five.vercel.app

• Default scan target: superlearnai.com

• Offline fallback: fixtures/reports/tell-report.json, so the product still opens with a complete report when live capture is unavailable.

• Showcase GIF: docs/media/tell-superlearnai-demo.gif, generated from the current UI flow.

Tell can scan a public URL directly, or locally clone a GitHub repository, install dependencies, boot the app on a free port, and capture localhost automatically.

Related MCP server: VibeServe

Why Tell

AI agents can generate working interfaces quickly. The harder question is whether the result has taste: a distinctive hierarchy, consistent tokens, reachable states, readable contrast, and a visual language that does not collapse into the same gradient-card-template everyone else ships.

Tell Proof is the independent reviewer for that moment. It does not ask the authoring agent to grade its own output. It opens the page in a real browser, measures the rendered surface, identifies specific genericness and drift patterns, and turns the critique into a reviewable direction.

The authoring agent proposes. Tell measures, critiques, repairs, and verifies.

Features

Tell is not a replacement for functional, responsive, accessibility, or security testing. It is a focused visual evidence layer for one rendered route at a time.

How It Works

flowchart LR
    url["Public URL or local app"] --> capture["Browser capture"]
    capture --> fingerprint["Design fingerprint"]
    fingerprint --> detectors["Genericness + drift detectors"]
    detectors --> taste["Taste verdicts"]
    taste --> report["Tell Report"]
    report --> direction["Voice/text art-direction"]
    direction --> diff["Source-grounded diff"]
    diff --> proof["Disposable proof checkout"]
    proof --> recapture["Recapture + measured comparison"]
    recapture --> cursor["Review and apply in Cursor"]

Deterministic-first: capture, fingerprinting, detector output, baseline reconciliation, and score comparison do not depend on a model. Models are only used where judgment or drafting benefits from language.

Human-reviewed by design: Tell can prepare a patch and prove it in isolation, but the final change still lands through the developer's normal review workflow.

Quick Start

You need Node 20+ and pnpm 9+.

git clone <your-repo-url> tell
cd tell
pnpm install
pnpm dev

Open http://localhost:3000. The app starts with SuperlearnAI as the capture target and falls back to the committed report if live capture cannot run.

To use the seeded sample app in a second terminal:

pnpm dev:fixture   # http://localhost:3001

Useful checks:

pnpm test
pnpm typecheck
pnpm capture:fixture
pnpm diagnose:fixture
pnpm verify:directions   # screenshot all 6 reconcile directions (requires Playwright)

Optional environment variables live in .env.example:

GEMINI_API_KEY=            # richer taste and voice parsing
CURSOR_API_KEY=            # Cursor-SDK-backed redesign drafts
CURSOR_MODEL=composer-2.5
CURSOR_AGENT_TIMEOUT_MS=75000
TELL_CAPTURE_API_URL=      # remote Playwright backend for hosted UI

Cursor MCP

Tell registers as a local MCP server via .cursor/mcp.json. Open this repo in Cursor and ask Agent chat to run the tools directly.

Run tell_diagnose on http://localhost:3001 and draft an editorial redesign.

Architecture

Tell is a pnpm monorepo with one shared engine behind both the web app and MCP server.

tell/
├── apps/web/           # Next.js product UI and API routes
├── packages/schema/    # Zod contracts shared across every boundary
├── packages/core/      # Capture, fingerprint, detectors, diagnosis
├── packages/taste/     # Verdicts, direction presets, voice/text parsing
├── packages/redesign/  # Reconciliation, source patches, proof measures
├── packages/mcp/       # Cursor MCP stdio server
├── fixtures/           # Generic input app and committed report artifacts
└── docs/               # Product, deployment, and design notes

Key API routes:

Deploy

The most reliable production shape is a hosted UI plus a separate Playwright capture backend.

Set TELL_CAPTURE_API_URL on the Vercel app to point at the capture backend. GitHub clone-and-run is local-only and should stay disabled on public hosts with TELL_DISABLE_REPO_SETUP=1.

For durable share links on Vercel, set DATABASE_URL from a Neon project (preferred) or link a Blob store (see DEPLOY.md). For PR preview diagnosis CI, set the GitHub repo variable TELL_PREVIEW_URL to your stable Vercel URL.

Deployment guides:

• Hybrid and single-platform deploy

• Vultr capture backend

Product Status

Shipped:

• Deterministic capture, fingerprinting, and 14 detectors

• Taste verdicts with safe fallback

• Tell Report with before/after reveal

• Voice/text art-direction

• Cursor MCP tools

• Public URL capture with offline report fallback

• Local GitHub repo setup runner

• Source-grounded redesign proposals

• Contrast-grounded reconciliation

• Multi-page route discovery and per-page scans

• Disposable visual proof loop for candidate patches

Next:

• Broader live-site captures in the open corpus (optional expansion)

• Scenario matrix: route × viewport × theme × interaction state (see docs/06_TELL_PROOF.md)

Shipped in Phase 4:

• Open taxonomy / benchmark asset (fixtures/corpus/taxonomy.json + README)

• Additional corpus captures: editorial-calm (0 tells), fintech-dense (dense drift)

• PR proof-compare workflow (.github/workflows/pr-proof-compare.yml) + pnpm proof:compare

• Cursor after-edit hook reminds agents to run proof-verify on UI changes

• Consolidated remaining-work plan: root PLAN.md (archived duplicate plans under docs/archive/)

Shipped in Phase 3:

• Multi-viewport capture matrix (desktop + tablet + mobile) with viewport strip in the report

• Hosted proof verify API (POST /api/proof/verify) — compare mode on Vercel, patch mode on capture backend

• Detector golden corpus manifest (fixtures/corpus/manifest.json) with regression test

• Cursor rule for auto proof-verify (.cursor/rules/tell-proof-verify.mdc)

• Cursor Cloud environment setup docs in AGENTS.md

Shipped in Phase 2:

• Shareable report links (/api/reports/share, /report/[id]) with Neon Postgres preferred, Blob fallback

• State probe thumbnails on capture (default / hover / focus clips)

• DESIGN.md drift detector (DesignSystemDrift) with automatic load in diagnose pipeline

• Tell Proof verify Cursor skill (.cursor/skills/tell-proof-verify)

• Dogfood typography consolidation on Tell web UI

Shipped in Phase 1:

• Full 14-detector golden fixture corpus

• tell_proof_verify and tell_proof_revert MCP tools

• PR preview diagnosis workflow (.github/workflows/pr-diagnose.yml)

• Dogfood script (pnpm dogfood:web) — Tell UI reports zero generic tells and zero drift

Contributing

Contributions are welcome. The highest-leverage additions are new detectors, better evidence views, and stronger source mapping.

pnpm typecheck && pnpm test

The sample app under fixtures/generic-app/ is intentionally bland input data, not the product itself. See CONTRIBUTIONS.md for the attribution breakdown.

License

Released under the MIT License.