@decantr/cli 1.1.1 → 1.3.0

package/dist/{heal-4DWU7BJS.js → heal-ZG5VJZ5J.js}

@@ -1,5 +1,3 @@
-import "./chunk-3RG5ZIWI.js";
-
 // src/commands/heal.ts
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";

package/dist/index.js

@@ -1,3 +1,2 @@
-import "./chunk-LXOY447U.js";
+import "./chunk-2F6Q5S5W.js";
 import "./chunk-CT5XHG6I.js";
-import "./chunk-3RG5ZIWI.js";

package/dist/{upgrade-3YL3NFOG.js → upgrade-ZSLT32KN.js}

@@ -1,7 +1,6 @@
 import {
   RegistryClient
 } from "./chunk-CT5XHG6I.js";
-import "./chunk-3RG5ZIWI.js";
 
 // src/commands/upgrade.ts
 import { readFileSync, existsSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Decantr CLI — search the registry, validate essence files, and access design intelligence from the terminal",
   "license": "MIT",
   "repository": {
@@ -22,13 +22,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@decantr/essence-spec": "1.0.0-beta.6",
+    "@decantr/registry": "1.0.0-beta.6"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@decantr/essence-spec": "workspace:*",
-    "@decantr/registry": "workspace:*"
   }
-}
+}

package/src/bundled/blueprints/default.json

@@ -6,7 +6,7 @@
   "name": "Decantr Default",
   "description": "Minimal starter blueprint for offline scaffolding. Visit decantr.ai/registry for more options.",
   "tags": ["starter", "minimal", "offline"],
-  "compose": ["starter"],
+  "compose": [],
   "theme": {
     "style": "default",
     "mode": "system",

package/src/bundled/themes/default.json

@@ -44,5 +44,14 @@
     }
   },
   "modes": ["light", "dark", "system"],
-  "shapes": ["rounded", "sharp", "pill"]
+  "shapes": ["rounded", "sharp", "pill"],
+  "typography_hints": {
+    "scale": "modular",
+    "heading_weight": 600,
+    "body_weight": 400
+  },
+  "motion_hints": {
+    "preference": "subtle",
+    "reduce_motion_default": true
+  }
 }

package/src/templates/DECANTR.md.template

@@ -6,65 +6,48 @@ This project uses **Decantr** for design intelligence. Read this file before gen
 
 ## What is Decantr?
 
-Decantr is a design intelligence layer that sits between you (the AI code generator) and the code you produce. It provides:
-
-- **Structured schemas** — The `decantr.essence.json` file is the source of truth for this project's design
-- **Reusable building blocks** — Patterns, archetypes, blueprints, and themes from the registry
-- **Drift prevention** — Guard rules that validate your code against the spec
-- **Design methodology** — The 7-stage Design Pipeline
+Decantr is a design intelligence layer that sits between you (the AI code generator) and the code you produce. It provides structured schemas, guard rules, and a two-layer model (DNA + Blueprint) that ensures consistent, production-quality output.
 
 **Decantr does NOT generate code.** You generate the code. Decantr ensures it remains coherent and consistent.
 
-### Why Drift Matters
+---
 
-Design drift is the gradual divergence between intended design and actual implementation. It happens when:
+## Two-Layer Model
 
-- Themes are switched "just this once" without updating the spec
-- New pages are added without declaring them in the structure
-- Layout order is changed because "it looks better this way"
-- Spacing values are tweaked ad-hoc instead of following the density profile
+### DNA (Design Axioms)
 
-Drift compounds. Small violations accumulate into a codebase where every page looks different, spacing is inconsistent, and the original design intent is lost. Decantr prevents this by making the design spec explicit and enforced.
+DNA defines the foundational design rules. **DNA violations are errors** -- they must never happen without updating the essence first.
 
----
+DNA axioms include: Theme (style, mode, recipe, shape), Spacing (density, content gap), Typography (scale, weights), Color (palette, accent count), Radius (philosophy, base), Elevation (system, levels), Motion (preference, reduce-motion), Accessibility (WCAG level, focus-visible), and Personality traits.
 
-## The Design Pipeline
+### Blueprint (Structural Layout)
 
-Every design decision follows these seven stages:
+Blueprint defines sections, pages, routes, features, and pattern layouts. **Blueprint deviations are warnings** -- they should be corrected but do not block generation.
 
-| Stage | Name | What Happens |
-|-------|------|--------------|
-| 1 | **Intent** | User describes what they want to build |
-| 2 | **Interpret** | Parse intent into structured form |
-| 3 | **Decompose** | Split into theme, structure, features |
-| 4 | **Specify** | Write `decantr.essence.json` |
-| 5 | **Compose** | Resolve layouts from patterns and recipes |
-| 6 | **Generate** | You generate code from the composition |
-| 7 | **Guard** | Validate every change against the spec |
-
-The essence file captures stages 1-5. Your code generation is stage 6. The guard rules enforce stage 7.
+Blueprint includes: Sections (grouped by archetype with role, shell, and scoped features), Page definitions with layouts and pattern references, Routes (URL mapping), and Features (resolved from archetype union + blueprint overrides).
 
 ---
 
 ## Guard Rules
 
-The guard system enforces five rules. **These are non-negotiable.**
-
-| # | Rule | What It Checks | Severity |
-|---|------|----------------|----------|
-| 1 | **Style** | Code uses theme specified in essence | Error |
-| 2 | **Structure** | Page exists in essence structure | Error |
-| 3 | **Layout** | Pattern order matches essence layout | Error (strict only) |
-| 4 | **Recipe** | Decorations match essence recipe | Error |
-| 5 | **Density** | Spacing follows density profile | Warning (strict only) |
+| # | Rule | Layer | What It Checks |
+|---|------|-------|----------------|
+| 1 | Style | DNA (error) | Code uses the theme specified in DNA |
+| 2 | Recipe | DNA (error) | Decorations match the DNA recipe |
+| 3 | Density | DNA (error) | Spacing follows the density profile |
+| 4 | Accessibility | DNA (error) | Code meets the WCAG level |
+| 5 | Theme-mode | DNA (error) | Theme/mode combination is valid |
+| 6 | Structure | Blueprint (warn) | Pages exist in the blueprint sections |
+| 7 | Layout | Blueprint (warn) | Pattern order matches the layout spec |
+| 8 | Pattern existence | Blueprint (warn) | Patterns referenced exist in the registry |
 
 ### Enforcement Tiers
 
-| Tier | When Used | Rules Enforced |
-|------|-----------|----------------|
-| **Creative** | New project scaffolding | Advisory only |
-| **Guided** | Adding pages or features | Rules 1, 2, 4 |
-| **Strict** | Modifying existing code | All 5 rules |
+| Tier | When Used | DNA Rules | Blueprint Rules |
+|------|-----------|-----------|-----------------|
+| **Creative** | New project scaffolding | Off | Off |
+| **Guided** | Adding pages or features | Error | Off |
+| **Strict** | Modifying existing code | Error | Warn |
 
 This project uses **{{GUARD_MODE}}** mode.
 
@@ -73,461 +56,50 @@ This project uses **{{GUARD_MODE}}** mode.
 When a user request would violate guard rules:
 
 ```
-1. STOP   — Do not proceed with code that violates guard rules
-2. EXPLAIN — Tell the user which rule would be violated and why
-3. OFFER  — Ask if they want to update the essence
-4. WAIT   — Only proceed after the essence is updated
+1. STOP   -- Do not proceed with code that violates DNA rules
+2. EXPLAIN -- Tell the user which rule would be violated and why
+3. OFFER  -- Suggest using decantr_update_essence to update the spec
+4. WAIT   -- Only proceed after the essence is updated
 ```
 
 **Never make "just this once" exceptions.** If the user insists, update the essence first.
 
----
-
-## This Project
-
-{{PROJECT_SUMMARY}}
-
-### Essence Overview
-
-```json
-{
-  "theme": "{{THEME_STYLE}}",
-  "mode": "{{THEME_MODE}}",
-  "guard": "{{GUARD_MODE}}",
-  "target": "{{TARGET}}"
-}
-```
-
-### Theme Quick Reference
-
-{{THEME_QUICK_REFERENCE}}
-
-**To fetch complete theme and recipe specs:**
-```bash
-npx @decantr/cli get theme {{THEME_STYLE}}
-npx @decantr/cli get recipe {{THEME_RECIPE}}
-```
-
-{{ACCESSIBILITY_SECTION}}
-
-{{SEO_SECTION}}
-
-### Pages
-
-{{PAGES_TABLE}}
+### MCP Tools for Drift Management
 
-### Patterns in Use
-
-{{PATTERNS_LIST}}
+- `decantr_check_drift` -- Check if planned changes violate rules
+- `decantr_accept_drift` -- Accept a detected drift as intentional
+- `decantr_update_essence` -- Update the essence spec to match desired changes
 
 ---
 
-## Before Writing Code
-
-**Always check these before generating UI code:**
-
-### Quick Commands
-
-```bash
-# Get full theme spec (colors, palette, modes)
-npx @decantr/cli get theme {{THEME_STYLE}}
-
-# Get recipe decorators and effects
-npx @decantr/cli get recipe {{THEME_RECIPE}}
-
-# Get pattern structure and presets
-npx @decantr/cli get pattern <pattern-name>
-
-# Search for patterns
-npx @decantr/cli search <query>
-```
+## How To Use This Project
 
-### With MCP Tools (If Available)
+### Source of truth
 
-> Note: MCP tools require the `@decantr/mcp-server` to be configured. If these tools are not available, use the CLI commands above.
-
-1. `decantr_read_essence` — Load the current essence
-2. `decantr_check_drift` — Verify your planned changes won't violate rules
-3. `decantr_resolve_pattern` — Get pattern details before implementing
-4. `decantr_suggest_patterns` — Find appropriate patterns for new sections
-
-### Without MCP Tools or CLI
-
-1. Read `decantr.essence.json` in the project root
-2. Verify the page you're editing exists in `structure[]`
-3. Check the page's `layout[]` for required pattern order
-4. Follow the `theme.style` and `theme.recipe` specifications
-5. Use spacing tokens from `density.content_gap`
-
-### Checklist
-
-Before writing any UI code:
-
-- [ ] Is this page in the essence structure?
-- [ ] Am I using the correct theme ({{THEME_STYLE}})?
-- [ ] Am I following the correct mode ({{THEME_MODE}})?
-- [ ] Does my pattern order match the layout spec?
-- [ ] Am I using the correct spacing tokens?
-
-If any answer is "no" — **STOP and ask the user to update the essence.**
-
----
+`decantr.essence.json` is the structural spec. Tools and guards read this.
 
-## After Writing Code
-
-### Self-Check
-
-After generating code, verify:
-
-1. **Theme consistency** — All colors, typography, and effects match the theme
-2. **Pattern structure** — Components follow the pattern's layout spec
-3. **Spacing consistency** — Gap values use tokens, not arbitrary pixels
-4. **Page declaration** — The page exists in the essence structure
-
-### Drift Validation
-
-Run validation to check for violations:
-
-```bash
-npx @decantr/cli validate
-```
-
-Or use the MCP tool:
-
-```
-decantr_check_drift(page_id="{{page}}", theme_used="{{theme}}")
-```
-
----
-
-## Pattern Quality Rules
-
-When implementing patterns, follow these rules:
-
-### 1. One Elevation
-
-Each pattern section should have a single visual elevation level. Don't nest cards within cards or create competing visual hierarchies.
-
-```
-// Good: Single elevation
-<section class="pattern-section">
-  <h2>Title</h2>
-  <div class="content">...</div>
-</section>
-
-// Bad: Nested elevations
-<Card>
-  <Card>...</Card>
-</Card>
-```
-
-### 2. Containment Decision
-
-Decide upfront whether a pattern is:
-- **Contained** — Has visible boundaries (card, panel)
-- **Inline** — Flows with content, no boundaries
-
-Don't mix containment within a pattern.
-
-### 3. Component Consistency
-
-Use the same component variants throughout a pattern. If buttons are `primary` style in one place, they should be `primary` everywhere in that pattern.
-
----
-
-## CSS Implementation
-
-This project uses **@decantr/css** for layout atoms and the generated CSS files for theme tokens and recipe decorators.
-
-### Setup
-
-```javascript
-// 1. Import the atoms runtime
-import { css } from '@decantr/css';
-
-// 2. Import generated CSS files (created by decantr init)
-import './styles/tokens.css';      // Theme tokens (--d-primary, --d-surface, etc.)
-import './styles/decorators.css';  // Recipe decorators ({{THEME_RECIPE}}-card, etc.)
-```
-
-### HTML Setup
-
-Your `index.html` MUST have theme and mode attributes:
-
-```html
-<!DOCTYPE html>
-<html lang="en" data-theme="{{THEME_STYLE}}" data-mode="{{THEME_MODE}}">
-  <head>
-    <meta name="color-scheme" content="{{THEME_MODE}}">
-    ...
-  </head>
-</html>
-```
+### Initial scaffolding
 
-**Why this matters:**
-- `data-theme` enables theme switching via JS without reloading CSS
-- `data-mode` enables light/dark toggle
-- `color-scheme` tells the browser to style native controls (scrollbars, inputs) correctly
+Read `.decantr/context/scaffold.md` for the full app overview, topology, and route map.
 
-### Using Atoms
+### Working on a section
 
-The `css()` function processes atom strings and injects CSS at runtime:
+Read `.decantr/context/section-{name}.md` for that section's complete context. Each section file contains guard rules, theme tokens, decorator classes, pattern specs with code examples, zone context, and routes. **Everything you need is in that one file.**
 
-```jsx
-// Layout atoms
-<div className={css('_flex _col _gap4 _p4')}>
-  <h1 className={css('_heading1')}>Title</h1>
-  <p className={css('_textsm _fgmuted')}>Description</p>
-</div>
+### Validation
 
-// Responsive prefixes (mobile-first)
-<div className={css('_gc1 _sm:gc2 _lg:gc4')}>
-  {/* 1 col -> 2 cols at 640px -> 4 cols at 1024px */}
-</div>
+Run `decantr check` to validate code against the spec.
 
-// Pseudo-class prefixes
-<button className={css('_bgprimary _h:bgprimary/80')}>
-  Hover me
-</button>
-```
-
-### Common Atoms
-
-| Category | Atoms | Description |
-|----------|-------|-------------|
-| Display | `_flex`, `_grid`, `_block`, `_none` | Display types |
-| Flexbox | `_col`, `_row`, `_wrap`, `_flex1` | Flex direction/behavior |
-| Alignment | `_aic`, `_jcc`, `_jcsb` | Align/justify content |
-| Spacing | `_gap{n}`, `_p{n}`, `_m{n}`, `_px{n}` | Gap, padding, margin |
-| Sizing | `_wfull`, `_hfull`, `_w{n}`, `_h{n}` | Width, height |
-| Typography | `_textsm`, `_textlg`, `_heading1`-`_heading6` | Font sizes |
-| Colors | `_bgprimary`, `_bgsurface`, `_fgmuted` | Background, foreground |
-
-### CSS Architecture
-
-The CSS is organized into two parts:
-
-1. **Atoms (@decantr/css)** - Layout utilities injected at runtime into `@layer d.atoms`
-2. **Generated CSS files** - Theme tokens and recipe decorators created during scaffold
-
-```
-src/styles/
-  tokens.css      # :root { --d-primary: #...; --d-surface: #...; }
-  decorators.css  # .{{THEME_RECIPE}}-card { ... }
-```
-
-### Variable Naming Convention
-
-| Prefix | Purpose | Example |
-|--------|---------|---------|
-| `--d-` | Core Decantr tokens | `--d-primary`, `--d-bg` |
-| `--d-gap-{n}` | Spacing tokens | `--d-gap-4`, `--d-gap-8` |
-| `--d-radius` | Border radius | `--d-radius`, `--d-radius-lg` |
-
-### Theme Switching (JavaScript)
-
-```javascript
-// Switch theme
-document.documentElement.dataset.theme = 'newTheme';
-
-// Switch mode
-document.documentElement.dataset.mode = 'light';
-document.querySelector('meta[name="color-scheme"]').content = 'light';
-```
-
-### Get Full Theme/Recipe Specs
+### Quick Commands
 
 ```bash
-npx @decantr/cli get theme {{THEME_STYLE}}   # See seed colors, palette
-npx @decantr/cli get recipe {{THEME_RECIPE}} # See decorators, effects
-```
-
----
-
-## Spatial Guidelines
-
-### Personality to Density Mapping
-
-| Personality | Suggested Density | Content Gap |
-|-------------|-------------------|-------------|
-| professional | comfortable | `_gap4` |
-| playful | spacious | `_gap6` |
-| premium | spacious | `_gap8` |
-| minimal | compact | `_gap2` |
-| bold | comfortable | `_gap4` |
-
-This project uses: **{{PERSONALITY}}** personality with **{{DENSITY}}** density.
-
-### The 50% Rule
-
-Pattern content should occupy roughly 50% of its container width on desktop. This creates breathing room and prevents wall-of-text layouts.
-
-### Spacing Tokens
-
-Use these tokens instead of arbitrary pixel values:
-
-| Token | Value | Use Case |
-|-------|-------|----------|
-| `_gap1` | 4px | Tight spacing within components |
-| `_gap2` | 8px | Compact layouts |
-| `_gap3` | 12px | Default inline spacing |
-| `_gap4` | 16px | Comfortable content gap |
-| `_gap6` | 24px | Section spacing |
-| `_gap8` | 32px | Major section breaks |
-| `_gap12` | 48px | Page section spacing |
-
----
-
-## Shells (Page Layouts)
-
-A shell is the page-level layout container. This project uses **{{DEFAULT_SHELL}}** as the default shell.
-
-### Available Shells
-
-| Shell | Description | Use Case |
-|-------|-------------|----------|
-| `sidebar-main` | Collapsible sidebar + main content | Dashboards, admin panels |
-| `top-nav-main` | Horizontal nav + full-width content | Marketing, content sites |
-| `centered` | Centered card on background | Auth flows, focused tasks |
-| `full-bleed` | No persistent nav, scroll-driven | Landing pages, portfolios |
-| `minimal-header` | Slim header + centered content | Checkout, wizards |
-| `sidebar-aside` | Three columns (nav + main + aside) | IDE-style, email clients |
-
-### Shell Structure
-
-```
-{{SHELL_STRUCTURE}}
+decantr status          # Project health
+decantr check           # Detect drift violations
+decantr get pattern X   # Fetch a pattern spec from registry
+decantr get recipe X    # Fetch recipe decorators
+decantr search <query>  # Search the registry
 ```
 
 ---
 
-## Task-Specific Context
-
-For detailed instructions based on what you're doing, see:
-
-| Task | Context File |
-|------|--------------|
-| Scaffolding new pages | `.decantr/context/task-scaffold.md` |
-| Adding pages/features | `.decantr/context/task-add-page.md` |
-| Modifying existing code | `.decantr/context/task-modify.md` |
-
-These files contain tier-specific rules and checklists.
-
----
-
-## Quick Reference
-
-### Essence Schema (Simplified)
-
-```json
-{
-  "version": "2.0.0",
-  "theme": {
-    "style": "theme-id",
-    "mode": "dark | light | auto",
-    "recipe": "recipe-id",
-    "shape": "pill | rounded | sharp"
-  },
-  "personality": ["trait1", "trait2"],
-  "structure": [
-    {
-      "id": "page-id",
-      "shell": "shell-id",
-      "layout": ["pattern-1", "pattern-2"]
-    }
-  ],
-  "features": ["auth", "search"],
-  "guard": {
-    "enforce_style": true,
-    "enforce_recipe": true,
-    "mode": "strict | guided | creative"
-  },
-  "density": {
-    "level": "compact | comfortable | spacious",
-    "content_gap": "_gap4"
-  },
-  "target": "react | vue | svelte | html"
-}
-```
-
-### Common Violations
-
-| Violation | Fix |
-|-----------|-----|
-| "Page not in structure" | Add page to `structure[]` in essence |
-| "Theme mismatch" | Use the theme from `theme.style` |
-| "Pattern order wrong" | Reorder to match `layout[]` |
-| "Unknown recipe" | Use recipe from `theme.recipe` |
-| "Spacing inconsistent" | Use tokens from `density.content_gap` |
-
-### Troubleshooting
-
-**"I need to add a new page"**
-1. Update `structure[]` in essence with the new page
-2. Specify the shell and layout patterns
-3. Then generate the code
-
-**"I want to change the theme"**
-1. Update `theme.style` in essence
-2. Update `theme.recipe` if needed
-3. Regenerate affected components
-
-**"The guard is blocking me"**
-1. Check which rule is being violated
-2. Update the essence to reflect the desired change
-3. Then proceed with code generation
-
-**"I don't know which pattern to use"**
-1. Use `decantr_suggest_patterns` with a description
-2. Or check the patterns in `.decantr/cache/patterns/`
-3. Or search the registry with `npx @decantr/cli search <query>`
-
----
-
-## Registry Content
-
-This project has access to the following content:
-
-### Patterns
-{{AVAILABLE_PATTERNS}}
-
-### Themes
-{{AVAILABLE_THEMES}}
-
-### Shells
-{{AVAILABLE_SHELLS}}
-
----
-
-## Updating the Essence
-
-When the user wants to change the design spec:
-
-1. Read the current `decantr.essence.json`
-2. Make the requested changes
-3. Validate with `npx @decantr/cli validate`
-4. Write the updated file
-5. Regenerate `DECANTR.md` if structure changed significantly
-
-Or use the MCP tool:
-
-```
-decantr_update_essence(operation="add_page", payload={...})
-```
-
----
-
-## Summary
-
-1. **Read the essence** before generating code
-2. **Check guard rules** before proceeding
-3. **Never violate** — update the essence instead
-4. **Use patterns** from the layout spec
-5. **Follow the theme** exactly
-6. **Validate after** generating code
-
-The essence is the source of truth. When in doubt, consult it.
-
----
-
-*Generated by Decantr CLI v{{VERSION}}*
+{{CSS_APPROACH}}

package/src/templates/essence-summary.md.template

@@ -35,8 +35,8 @@ Auto-generated summary of `decantr.essence.json`.
 | Property | Value |
 |----------|-------|
 | Mode | {{GUARD_MODE}} |
-| Enforce Style | {{ENFORCE_STYLE}} |
-| Enforce Recipe | {{ENFORCE_RECIPE}} |
+| DNA Enforcement | {{DNA_ENFORCEMENT}} |
+| Blueprint Enforcement | {{BLUEPRINT_ENFORCEMENT}} |
 
 ## Density