<div align="center">

# Tell Proof

### The independent design layer for Cursor and agent harnesses.

**Agents write code. Tell proves the UI - then helps you ship design that looks intentional, not AI-default.**

[Specimens](#specimens) · [Why Tell](#why-tell) · [Demo](#demo) · [Features](#features) · [Quick Start](#quick-start) · [Cursor MCP](#cursor-mcp) · [Platform Compatibility](#platform-compatibility) · [Architecture](#architecture) · [Deploy](#deploy)

[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](./LICENSE)
[![Built for Cursor](https://img.shields.io/badge/built%20for-Cursor-black.svg)](https://cursor.com)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg)](https://www.typescriptlang.org/)
[![Next.js 14](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)
[![MCP](https://img.shields.io/badge/MCP-stdio-black.svg)](https://modelcontextprotocol.io/)

<br/>

[![Tell Proof product demo: capture the generic fixture, name tells, drag the before/after seam, art-direct with voice, draft a Cursor patch, then Studio and specimens](./docs/media/tell-proof-demo-poster.webp)](./docs/media/tell-proof-demo.mp4)

<p><a href="./docs/media/tell-proof-demo.mp4">Watch the product demo</a> · ~47s · captioned walkthrough of capture → named tells → seam → voice → draft fix, then Studio and specimens</p>

</div>

---

## Specimens

Tell ships **17 engine offerings** plus Crease and Baseline matchday specimens under [`/showcase`](./apps/web/src/app/showcase). These recaptured stills show current progress: Crease and Baseline matchday, Tiller's session helm, Roundspool's care pathway, Ember Gate's path atlas, and the first-five marketing folds after the Lattice Z-stroke and pipeline-rail fixes.

Each offering appears **once**. We do not stack a fold still and a craft reel of the same page. GitHub shows the reel as that fold's first frame, which made every template look repeated.

| Specimens gallery | Crease · cricket | Baseline · tennis |
|:---:|:---:|:---:|
| [![Tell Specimens featured tour](./docs/media/showcase/01-showcase-featured.webp)](./docs/media/tell-proof-demo.mp4) | ![Crease fold](./docs/media/showcase/crease-fold.webp) | ![Baseline fold](./docs/media/showcase/baseline-fold.webp) |
| 19 offerings · hover reels on `/showcase` | Live score spine | Nested sets / games / points |

| Agent harness · Tiller | Care pathway · Roundspool | Lantern path · Ember Gate |
|:---:|:---:|:---:|
| ![Tiller fold](./docs/media/showcase/harness-fold.webp) | ![Care pathway fold](./docs/media/showcase/clinic-fold.webp) | ![Ember Gate fold](./docs/media/showcase/lantern-fold.webp) |
| Turn tape + permit plate | Stage rail + care plate | Path atlas, not a broken diagram |

| SaaS · Northstar | Operator console · Queueboard | Trust narrative · Lattice |
|:---:|:---:|:---:|
| ![Northstar fold](./docs/media/showcase/saas-fold.webp) | ![Queueboard fold](./docs/media/showcase/dashboard-fold.webp) | ![Lattice fold](./docs/media/showcase/corporate-fold.webp) |
| Pipeline board, no title-rail reprint | Priority rail + queue console | Posture grid without a Z-stroke |

| Filmstrip | Press atelier · Forme Desk | Field guide |
|:---:|:---:|:---:|
| ![Tell Specimens filmstrip](./docs/media/showcase/02-showcase-gallery.webp) | ![Press fold](./docs/media/showcase/press-fold.webp) | ![Herbarium fold](./docs/media/showcase/herbarium-fold.webp) |
| Distinct cells - Crease then Baseline | Imposition sheet + densitometer | Glassine tray |

The poster links the full demo video. Craft reels play on [`/showcase`](./apps/web/src/app/showcase) on hover; this README keeps stills only so GitHub does not reprint the same fold twice.

```bash
pnpm capture:readme-showcase   # one fold still per offering
pnpm capture:readme-steps      # docs/media/step-{capture,detect,art-direct,repair,prove}.webp
pnpm media:webp
```

---

## Why Tell

Coding agents inside Cursor (and other harnesses) are extraordinary at shipping working software. They are much weaker at **visual authorship**. Ask an agent to "make it prettier" and you usually get the same defaults again: system fonts, violet accents, shadow-on-every-card, emoji chrome, monotone radius, mushy gray hierarchy.

That is not a failure of effort. It is a structural gap:

| What the harness optimizes | What production UI actually needs |
|---|---|
| Compiling code that runs | A composition users trust in the first viewport |
| Local file edits that "look better" | Measured contrast, token rhythm, and state coverage |
| The same model judging its own output | An independent visual proof loop |
| Prompt-only taste / one universal layout kit | Kind-specific craft + detectors that cannot be waved away |

**Tell is the missing design runtime for agent-built software.** It sits beside Cursor as an independent critic and craft engine:

1. **Observe** - Playwright captures the rendered page users actually see.
2. **Name** - Fourteen deterministic detectors call out genericness and drift with evidence.
3. **Direct** - Voice/text art-direction becomes concrete action items and a reconciled after-state.
4. **Repair** - Source-ranked diffs land as reviewable patches - never silent auto-apply.
5. **Prove** - Disposable checkouts recapture before/after so the harness can trust the fix.
6. **Author** - Tell Studio turns product features into premium, lean-distinct layouts via a skill graph - so Cursor is not inventing another generic SaaS template from scratch.

The authoring agent proposes. Tell measures, critiques, redesigns, and verifies. Humans stay in control.

### Why this is a higher bar than "generate a pretty page"

> **Design process and quality:** see the [DesignProof redesign plan](https://linear.app/bimlabz/document/designproof-redesign-plan-concept-first-step-by-step-design-7f1f65ec2bc3). It proposes concept-first, staged and reviewed generation instead of today's one-pass `tell_design_from_features`, plus its own review for motion between art direction and refinement (not a separate stage), performance budgets, explicit colour themes and a swap test. It also makes keep / rework / drop calls on the templates, so the specimens below are work in progress, not finished. Proposed, waiting on Ashish's decision in [BIM-203](https://linear.app/bimlabz/issue/BIM-203/decide-designproof-redesign-plan-concept-first-step-by-step-and-the); nothing below is built yet.

| Prompt-only / generic kit | Tell |
|---|---|
| One layout grammar restyled per product | **Nineteen offerings** with distinct fold grammar (press sheet, ledger, lattice, path atlas, session helm, …) |
| Taste lives only in the model's prior | **Deterministic detectors + critique bands** - scores and evidence, not vibes |
| Nav crop as "proof" of craft | **Craft reels** that scroll to plate / spread / imprint beats |
| Filler tiers and lorem sections | **Feature-derived** pricing, proof, and instruments from the brief you typed |
| "Looks better" with no receipt | **Contrast floor, token rhythm, state coverage** reported on the after-state |
| Agent grades its own homework | **Independent capture → diagnose → reconcile → proof** loop beside Cursor |

### How harnesses (especially Cursor) get better

| Harness pain | Tell response |
|---|---|
| Agent grades its own homework | Independent browser capture + scored findings |
| "Make it nice" loops regenerate sameness | Named tells + direction presets with measurable deltas |
| Patches look fine in chat, break in the browser | Disposable proof: apply → HMR → recapture → compare |
| No designer on the team | Studio skill graph + MCP tools inside Agent chat |
| Demo tomorrow, UI still generic | Capture → seam → voice → draft fix → apply in Cursor |

---

## Demo

**[Watch the ~47s MP4](./docs/media/tell-proof-demo.mp4)** - captioned, no narrator. It is the product loop, not a dashboard tour. The bland landing in the capture is [`fixtures/generic-app`](./fixtures/generic-app) (demo input, not Tell).

| Beat | On screen |
|---|---|
| Setup | Paste `http://127.0.0.1:3001` - shipped in a weekend with AI, looks familiar |
| Capture + diagnose | Live capture, then 14 findings (`SystemFontTell`, drift, generic) |
| Taste | Click a named tell; evidence on the rendered page, not a vibe check |
| Before / after | Drag the seam - captured purple vs reconciled editorial, contrast floor held |
| Voice + Cursor | "Warmer, more editorial, less shadow" → draft fix → Send to Cursor |
| Studio + specimens | Feature brief → Northstar landing; Crease / filmstrip close |
| Dogfood | Tell runs on itself: zero tells |

The stills below are the same Report UI, frozen, if you cannot play the video.

### 1. Capture

![Capture: live URL composer with the fixture filled in](./docs/media/step-capture.webp)

Paste a live URL (or GitHub repo, or the offline fixture). Tell records screenshots, computed styles, CSS variables, and state probes.

### 2. Detect

![Detect: named findings, 14 total, 8 generic and 6 drift](./docs/media/step-detect.webp)

Fourteen deterministic detectors name issues like `SystemFontTell`, radius monotony, shadow overuse, token misuse, and spacing chaos - with evidence on the rendered page.

### 3. Art-Direct

![Art-Direct: voice and text direction with Editorial selected](./docs/media/step-art-direct.webp)

Type or speak a direction ("warmer, more editorial, less shadow"). Tell maps it to a preset and concrete action items.

### 4. Repair

![Repair: tell-overrides.css patch with Copy patch and Send to Cursor](./docs/media/step-repair.webp)

Source-aware diffs update the files responsible for the problem. Copy the patch or send it to Cursor. `tell_apply` never writes files for you.

### 5. Prove

![Prove: captured vs reconciled seam with genericness 73 to 1](./docs/media/step-prove.webp)

Apply the candidate in a disposable checkout, recapture, and measure improvement (contrast, rhythm, spacing, state coverage) before anything lands.

Studio authoring sits on the same engine: generate a premium preview from a feature brief after the critic loop.

Regenerate the video and stills locally (web on `:3000`, fixture on `:3001`):

```bash
pnpm record:readme-demo    # docs/media/tell-proof-demo.mp4 + poster
pnpm capture:readme-showcase
pnpm capture:readme-steps
```

---

## Features

| Capability | What ships today |
|---|---|
| **Rendered capture** | Playwright opens the route and records screenshot evidence, DOM summary, computed styles, CSS variables, contrast samples, and interactive-state probes. |
| **14 deterministic detectors** | 8 genericness tells and 6 consistency-drift detectors catch system fonts, gradient crutches, shadow overuse, radius monotony, gray mush, token bypasses, spacing chaos, state gaps, focus inconsistency, and more. |
| **Taste engine** | Findings become plain-English verdicts: `generic`, `drift`, `intentional`, or `uncertain`, with confidence and rationale. Gemini can enrich judgment; deterministic fallback keeps the flow usable without keys. |
| **Voice and text art-direction** | Say or type directions like "warmer, more editorial, less shadow". Tell maps intent to a preset and concrete action items before model refinement. |
| **Before/after reveal** | The captured page is compared against a deterministic reconciliation that preserves content while improving hierarchy, contrast, depth, radius, and focus treatment. |
| **Tell Studio + design skills** | Feature brief → site-kind routing → tokens → sections → `previewHtml`. Lean codes (`minimal-clean`, `conversion-sharp`, `system-crafted`, `refined-story`) keep layouts distinctive without designer folklore. |
| **Source-grounded redesign diffs** | When a repo is available, Tell ranks real TSX/JSX/CSS files by rendered evidence and drafts a unified diff instead of guessing from a screenshot. |
| **Visual worktree proof** | Candidate patches run inside a disposable checkout. Tell applies, waits for HMR, recaptures, compares score/focus/structure, and auto-reverts failed attempts. |
| **GitHub setup runner** | Paste `github.com/owner/repo`; local Tell clones it, reads `README` and `package.json`, installs dependencies, starts the dev server, and captures the reachable URL. |
| **Multi-page scanning** | Routes discovered from the snapshot can be scanned individually, exposing drift that only appears on pricing, docs, onboarding, or secondary pages. |
| **Cursor MCP** | Eleven `tell_*` tools expose the same engine inside Cursor Agent chat. Catalog matches `@tell/schema` `MCP_TOOL_NAMES`. |
| **Scenario matrix** | Live Playwright capture across route × viewport × theme × interaction × auth (`storageState`), with CI smoke against the fixture and a Tell Report panel. |

Tell is not a replacement for functional, responsive, accessibility, or security testing. It is a focused visual evidence and craft layer - the piece most agent harnesses still skip.

---

## How It Works

```mermaid
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"]
    features["Product features brief"] --> studio["Tell Studio skill graph"]
    studio --> preview["Premium preview HTML"]
    preview --> cursor
```

**Deterministic-first:** capture, fingerprinting, detector output, baseline reconciliation, Studio routing/tokens/sections, 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+**.

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

Open [http://localhost:3000](http://localhost:3000) for Tell Report, or [http://localhost:3000/studio](http://localhost:3000/studio) for Tell Studio. The report starts with a demo capture target and falls back to the committed offline report if live capture cannot run.

To use the seeded sample app in a second terminal:

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

Useful checks:

```bash
pnpm test
pnpm typecheck
pnpm capture:fixture
pnpm diagnose:fixture
pnpm e2e:studio
pnpm record:readme-demo    # README hero MP4
pnpm capture:readme-showcase
```

---

## Cursor MCP

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

```text
Run tell_diagnose on http://localhost:3001 and draft an editorial redesign.
Design a dashboard from these features with tell_design_from_features.
```

```bash
tell mcp install cursor --project   # upsert .cursor/mcp.json
tell mcp platforms                  # compatibility table
tell mcp print-config               # all agent snippets + deeplink
```

| Tool | Purpose |
|---|---|
| `tell_capture` | Capture screenshot and computed-style evidence for a URL. |
| `tell_diagnose` | Return the full Tell report, findings, verdicts, and score. |
| `tell_redesign` | Draft a redesign proposal for a finding or whole report. |
| `tell_apply` | Return patch text and instructions; it never writes files for you. |
| `tell_capture_matrix` | Live Playwright scenario matrix (route × viewport × theme × interaction × auth). |
| `tell_proof_verify` | Apply a patch, recapture the URL, and return pass/review/fail with measured deltas. |
| `tell_proof_revert` | Revert the last proof patch in the workspace. |
| `tell_design_from_features` | Generate a premium layout from a product brief (Studio skill graph). |
| `tell_voice` | Parse a voice/text transcript into a direction plan. |
| `tell_install_info` | Return MCP install snippets, deeplink, and platform catalog. |
| `tell_resolve_intent` | Route a free-text request to diagnose, redesign, or Studio authoring. |

Catalog must stay at **eleven** tools. `tell_apply` returns patch text only.

> **Planned, not built: staged design tools.** Today `tell_design_from_features` builds a whole site design in one call. The [DesignProof redesign plan](https://linear.app/bimlabz/document/designproof-redesign-plan-concept-first-step-by-step-design-7f1f65ec2bc3) proposes replacing it with one MCP (Model Context Protocol) tool for each of the eight reviewed design stages (brief, concepts, mood board, art direction, imagery, one key screen, section by section, and refinement), plus a review tool. Motion has its own review, after art direction and before refinement, through that same review tool. A stage can't run until the one before it is approved, and rejecting a stage reruns only that stage. Under the plan the catalog would go from 11 to 19 tools, and a colour `theme` setting would replace colour picked from the product name. None of this exists yet. It's waiting for Ashish's decision in Linear issue [BIM-203](https://linear.app/bimlabz/issue/BIM-203/decide-designproof-redesign-plan-concept-first-step-by-step-and-the). Until then the eleven tools listed here are the real catalog.

---

## Platform Compatibility

Tell ships as **a CLI and an MCP server** that mainstream coding agents consume natively. Once the monorepo is installed, a single `tell mcp install <platform>` wires the MCP server into that agent's config - same tools from inside any host.

| Coding agent / platform | Status | One-line MCP install |
|---|:---:|---|
| Cursor | Supported | `tell mcp install cursor --project` |
| Claude Code | Supported | `tell mcp install claude` |
| Codex CLI | Supported | `tell mcp install codex --project` |
| Grok Build | Supported | `tell mcp install grok --project` |
| OpenCode | Supported | `tell mcp install opencode --project` |
| VS Code + GitHub Copilot | Supported | `tell mcp install vscode --project` |
| Windsurf | Supported | `tell mcp install windsurf --user` |
| Zed | Supported | `tell mcp install zed --project` |
| Cline (VS Code) | Supported | `tell mcp install cline --user` |
| Kiro | Supported | `tell mcp install kiro --project` |
| Kimi Code | Supported | `tell mcp install kimi --project` |
| Qwen Code | Supported | `tell mcp install qwen --project` |
| Pi Agent | Supported | `tell mcp install pi --user` |
| Trae | Supported | `tell mcp install trae --user` |
| Antigravity | Supported | `tell mcp install antigravity --user` |
| Hermes Agent | Supported | `tell mcp install hermes --user` |
| OpenClaw | Supported | `tell mcp install openclaw --user` |
| Muse Code | Snippet | `tell mcp install muse --print` |
| Z Code | Snippet | `tell mcp install zcode --print` |

```bash
tell mcp platforms                          # markdown table
tell mcp install <platform> --print         # dry-run snippet
tell mcp print-config                       # all agent snippets + Cursor deeplink
tell install-info --markdown                # catalog + snippets
```

Tell does **not** spawn third-party coding agents as subprocesses. Compatibility means MCP install into the agent you already use.

---

## Architecture

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

```text
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/design-skills/# Feature → route → tokens → sections → preview HTML
├── packages/mcp/          # Cursor MCP stdio server
├── fixtures/              # Generic input app and committed report artifacts
└── docs/                  # Product, deployment, and design notes
```

Key API routes:

| Route | Responsibility |
|---|---|
| `POST /api/diagnose` | Capture and diagnose a URL, using a remote capture backend when configured. |
| `POST /api/redesign` | Produce a source-aware redesign proposal with deterministic fallback. |
| `POST /api/voice` | Convert transcript/text into direction presets and action items. |
| `POST /api/design` | Tell Studio - generate or redesign from a feature brief. |
| `POST /api/setup/start` | Local-only GitHub clone/install/run/capture workflow. |
| `POST /api/proof/apply` | Apply a candidate patch in the disposable checkout and verify it. |
| `POST /api/proof/verify` | Hosted proof sandbox - compare two reports on Vercel, or apply+recapture on the capture backend. |
| `POST /api/proof/matrix` | Live scenario-matrix capture (+ optional self-compare). |
| `POST /api/proof/revert` | Revert the proof checkout. |
| `POST /api/reports/share` | Persist a Tell report (Neon → Blob → disk) and return a shareable `/report/[id]` link. |
| `GET /api/reports/[id]` | Load a previously shared report JSON. |
| `GET /api/health/capture` | Check Playwright capture readiness. |

---

## Deploy

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

| Layer | Platform | Role |
|---|---|---|
| UI | Vercel | Fast Next.js app, report, reveal, voice direction, Studio, redesign draft |
| Capture | Vultr, Render, or Docker host | Playwright + Chromium for live URL diagnosis |
| MCP | Local Cursor | Stdio tools for editor-native diagnosis and patch handoff |

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](./docs/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](./docs/DEPLOY.md)
- [Vultr capture backend](./docs/DEPLOY-VULTR.md)

---

## Contributing

Contributions are welcome. The highest-leverage additions are new detectors, stronger Studio skills, better evidence views, and tighter source mapping for harness workflows.

```bash
pnpm typecheck && pnpm test
```

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

---

## License

Released under the [MIT License](./LICENSE).