decantr

# Decantr

**AI Frontend Governance for production codebases touched by AI agents.**

Decantr is the governance layer between product intent and AI-edited frontend code. It gives coding assistants three things they don't have on their own: typed contracts, route-scoped context, and machine-actionable evidence, so UI changes stay coherent instead of drifting prompt by prompt. Decantr 3.9 calls this **Governed Change Proof**: one source-grounded adoption truth, one bounded task capsule, and one fail-closed governance delta around each change. The model still writes the code; Decantr defines the contract, context, authority, and verification loop around it.

> AI generates the interface. Decantr proves, with local evidence, whether the outcome stayed aligned.

## Pick your path

| Path | Use when | Start with |
| --- | --- | --- |
| **[Brownfield adoption](docs/reference/workflow-model.md#brownfield-adoption)**  ⭐ | Attaching Decantr to an existing Angular/React/Vue/etc. project | `decantr scan` -> `decantr adopt --yes` |
| **[Hybrid operating layer](docs/reference/workflow-model.md#hybrid-operating-layer)** | An attached app wants selected Decantr or project-owned UI law, without source takeover | `decantr codify`, `decantr doctor`, `decantr task` |
| **[Greenfield content contract](#greenfield-content-contracts)** | New project, official content-corpus composition as governance context | `decantr new my-app --blueprint=<id> --workflow=greenfield` |
| **Greenfield contract-only** | New project or repo that wants Decantr governance but no blueprint/runtime takeover | `decantr init --workflow=greenfield --adoption=contract-only` |

---

## Greenfield Content Contracts

### 1. Scaffold from a blueprint

```bash
npx @decantr/cli new my-app --blueprint=esports-hq
cd my-app
```

A blueprint is official corpus content: theme, sections, pages, layouts, voice, and personality that compile into Decantr contracts and execution packs. It is reference material for governance, not a public marketplace or runtime takeover. Try `esports-hq`, `agent-studio`, or `carbon-ai-portal`, or run `decantr list blueprints --blueprint-set featured` to browse the curated set.

> **Adapter availability.** Greenfield defaults to contract-only governance. The legacy `@decantr/css` runnable adapters (`react-vite`, `next-app`, `vanilla-vite`, `vue-vite`, `sveltekit`, `angular`, and `solid-vite`) remain available only when explicitly requested with `--adoption=decantr-css`. Other targets initialize through `generic-web` contract-only mode.

### 2. What just got generated

```
my-app/
├── decantr.essence.json     # the durable contract: theme, sections, routes, features
├── DECANTR.md               # methodology primer your AI assistant reads first
├── .decantr/context/
│   ├── scaffold.md          # full app overview: topology, voice, personality
│   └── section-*.md         # per-section spec: shell, patterns, spacing
└── .decantr/graph/
    ├── graph.snapshot.json  # typed Contract graph with route/source provenance
    └── contract-capsule.json # compact agent cache and source handles
```

Decantr produces the contract and governance context. Your AI assistant produces the implementation through the project's selected runtime and styling system. Decantr CSS files are generated only by the explicit legacy `--adoption=decantr-css` path.

### 3. Hand it to your AI assistant

Open the project in Claude Code, Cursor, Windsurf, or any AI-aware editor. For Cursor, run `decantr connect cursor` once from the opened workspace; in monorepos use `decantr connect cursor --project apps/web`. It writes `.cursor/mcp.json` and `.cursor/rules/decantr.mdc`, preserving existing MCP servers, so Cursor Agent knows to call Decantr task context before route edits. Other assistants can read `DECANTR.md` first for the methodology, then load section context files on demand. Optional assistant bridges are workflow-specific: contract-only Greenfield rules cite Essence, narrative context, and the Contract capsule; corpus-backed Greenfield/Hybrid rules cite execution packs; Brownfield rules cite observed analysis and doctrine artifacts. For route-level work, run `decantr task <route> "<intent>"` before editing. In 3.9 that compatibility response is built from `TaskCapsuleV1`: the discovered implementation file is the required rank-one read target, authority and changed-file impact are explicit, official guidance carries content identity and digest provenance, and the compact canonical payload is bounded to 12,000 UTF-8 bytes / 4,000 deterministic estimated tokens. Task activation emits structured remediation and exits nonzero when the typed graph is missing, stale, or, for Angular Brownfield, not proven from the selected production bootstrap.

### 4. Make your first change and verify

```bash
# Edit decantr.essence.json — add a section, swap the theme, etc.
decantr refresh   # regenerate context files from the updated essence
decantr graph     # generate the typed Contract graph, source index, and contract capsule
decantr verify    # run the canonical local reliability gate
decantr verify --evidence
decantr studio    # open the local-only health dashboard
```

`refresh` keeps the generated context files in sync with the essence. `graph` writes `.decantr/graph/graph.snapshot.json`, `.decantr/graph/snapshots/<snapshot-id>.json`, `graph.manifest.json`, `graph.diff.json`, and `contract-capsule.json` for typed agent context and replayable local history. `verify` is the day-to-day reliability gate over Project Health, Brownfield checks, health baselines, and optional evidence; health findings include stable diagnostic codes, typed repair IDs, component reuse drift such as `COMP001`, behavior-obligation drift such as `A11Y010`, and accepted style bridge drift such as `TOKEN010`. For an adopted Brownfield app with a saved baseline, inherited findings remain visible but only new findings determine the `verify --ci` or `decantr ci` exit code. When a graph snapshot exists, findings also include graph anchors back to the contract node they came from. `--evidence` writes the privacy-redacted Evidence Bundle that AI agents and CI can use for repair context. `decantr studio` gives the same signal in a small localhost dashboard, and `decantr studio --workspace` expands that view across many Decantr projects in a monorepo.

> Starting from a different point? See the full [workflow model](docs/reference/workflow-model.md).

---

## The model

Decantr separates design governance into two layers:

- **DNA** — durable visual and system axioms: theme, spacing, motion, accessibility, personality.
- **Blueprint** — product topology: sections, page routes, shells, layouts, features.

That split matters because not every change should be treated the same way. A theme swap or accessibility regression is different from adding an auxiliary section or reshaping a route map. Decantr lets governance be strict where it should be strict (DNA, errors by default) and flexible where it should be flexible (Blueprint, warnings only).

Canonical shapes live in the [published schemas](https://decantr.ai/schemas/); the command-level flow is in the [workflow model](docs/reference/workflow-model.md).

## Surfaces

| Surface | What it does |
| --- | --- |
| CLI | Guides users through workflow commands (`setup`, `adopt`, `doctor`, `task`, `verify`, `resolve`, `ci`, `codify`, `connect cursor`), projects `AdoptionTruthV1`, builds bounded `TaskCapsuleV1` task context, keeps v2 reports as the default, offers explicit CI v3 governed-change proof, and opens read-only Studio locally |
| MCP server | Exposes exactly eight Decantr tools for contracts, bounded task context, graph reads, compatibility content-corpus reads, verification, repair, and explicit contract writes; it does not add a ninth content tool in 3.x |
| Content API | Fly-hosted helper for official corpus search, schemas, intelligence summaries, showcase metadata, and execution-pack compilation |
| Verifier | Canonical owner of `AdoptionTruthV1`, `TaskCapsuleV1`, and `GovernanceDeltaV1`, plus shared discovery, audit, critique, Project Health, Evidence Bundle, stable finding identity, graph anchors, and report schemas |
| Showcase apps | Audited benchmark corpus and verification targets for Decantr-generated scaffolds |

Decantr 3.7 introduced the shared Brownfield discovery substrate that 3.9 composes into `AdoptionTruthV1` across verifier, CLI, MCP, opt-in CI v3, and Studio. `scan`, `setup`, `workspace list`, `adopt`, `doctor`, `task`, `verify`, `ci`, and MCP project/task/evidence reads use the same selected app scope, workspace package-manager evidence, framework, language, route signals, taskable routes, component inventory confidence, styling authority, assistant rules, provenance, and limitations. Route discovery reads formal TanStack source routes instead of generated route trees, resolves nested React Router object routes and lazy implementation files, recognizes Vue Router object routes, and labels pathname-only fallbacks as medium confidence. Angular uses a framework authority adapter: it starts at the selected `angular.json`/`project.json` build entry, follows the TypeScript import graph to `provideRouter` or `RouterModule.forRoot`, resolves nested/lazy routes, excludes test and fixture source, separates structural route scopes from rendered pages, inventories `@Component` classes, and derives styling from selected-app build/runtime evidence rather than an installed Tailwind package alone. Authority, completeness, taskability, and confidence are separate axes; a high aggregate score cannot make unproven routes governable. App scans also inherit repository-level assistant rules such as a root `AGENTS.md`. This is especially important in mixed monorepos: a React/Vite app beside an Angular app should scan as React/TypeScript/pnpm when `--project apps/web` targets the React app, not as the repository root or sibling framework. `scan --json` remains `s