# Decantr Scaffolding Flow

## Complete Init Flow (Top-Down)

```
┌─────────────────────────────────────────────────────────────────────┐
│                        decantr init                                 │
│                     (CLI Entry Point)                               │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    PROJECT DETECTION                                │
│  Scans working directory for:                                       │
│  • Framework (react, vue, svelte, next, etc.)                       │
│  • Package manager (npm, pnpm, yarn)                                │
│  • TypeScript presence                                              │
│  • Tailwind presence                                                │
│  • Existing decantr.essence.json                                    │
│  • Existing AI rule files (CLAUDE.md, .cursorrules, AGENTS.md, etc.)│
│  • Ambient doctrine docs (.claude/, docs/, CI, schema, design system)│
│  • Workspace/app roots (pnpm workspaces, turbo, nx, apps/*)         │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│              WORKFLOW POLICY RESOLUTION                             │
│                                                                     │
│  Resolve once, before registry reads, adapter work, or file writes: │
│                                                                     │
│  workflowMode:                                                      │
│    greenfield-scaffold | greenfield-contract-only                   │
│    brownfield-attach  | hybrid-compose                              │
│                                                                     │
│  adoptionMode: contract-only | style-bridge | decantr-css           │
│  contentSource: none | official | custom | cache                    │
│  assistantBridge: none | preview | apply                            │
│  projectScope: single-app | workspace-app                           │
│                                                                     │
│  --existing is a compatibility alias for brownfield-attach.         │
│  --accept-proposal / --merge-proposal / --replace-essence control   │
│  deterministic brownfield proposal acceptance.                      │
│  --project=<path> pins appRoot when a workspace has multiple apps.  │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   WORKFLOW ROUTING                                  │
│                                                                     │
│  greenfield-scaffold      → adapter bootstrap + optional registry   │
│  greenfield-contract-only → local contract/context files only       │
│  brownfield-attach        → inventory → proposal → acceptance        │
│  hybrid-compose           → mutate existing essence/context         │
│                                                                     │
│  Offline contract-only exits without hosted registry access.        │
│  Offline registry-backed flows require cache/custom/content dir.    │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   BLUEPRINT / CONTENT SELECTION                     │
│                                                                     │
│  Two-phase interactive flow:                                        │
│                                                                     │
│  Phase A: runSimplifiedInit()                                       │
│  ┌────────────────────────────┐                                     │
│  │  "What blueprint?"         │                                     │
│  │  1. Default (recommended)  │──→ Phase B: runInteractivePrompts() │
│  │  2. Search registry...     │──→ Select from results, use defaults│
│  └────────────────────────────┘                                     │
│                                                                     │
│  Phase B (only if "Default" selected):                              │
│    Theme, mode, shape, target, guard, density, shell prompts        │
│                                                                     │
│  --yes / --blueprint <id>:  Skip prompts, use defaults/flags        │
│  --offline (contract-only): scaffoldMinimal() → exit early           │
│  --offline + --blueprint:    Normal flow using local content only    │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  CONTENT RESOLUTION                                 │
│                                                                     │
│  Single items: Custom → API → Cache                                 │
│  Lists:        API → Cache → merge Custom on top                    │
│  cmdGet:       API → Cache → Bundled (packages/cli/src/bundled/)    │
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │  1. BLUEPRINT │    │  2. THEMES   │    │  3. RECIPE   │          │
│  │              │    │              │    │              │          │
│  │  compose[]   │    │  seed        │    │  treatment_  │          │
│  │  theme{}     │    │  palette     │    │    overrides │          │
│  │  personality │    │  tokens      │    │  decorators  │          │
│  │  features    │    │  typography_ │    │  spatial_    │          │
│  │  overrides   │    │    hints     │    │    hints     │          │
│  └──────┬───────┘    │  motion_     │    │  radius_     │          │
│         │            │    hints     │    │    hints     │          │
│         │            │  cvd_support │    │  animation   │          │
│         │            └──────┬───────┘    │  shell prefs │          │
│         │                   │            │  visual_     │          │
│         │                   │            │    effects   │          │
│         │                   │            └──────┬───────┘          │
│         ▼                   │                   │                  │
│  ┌──────────────────┐       │                   │                  │
│  │  4. ARCHETYPES   │       │                   │                  │
│  │  (ALL compose[]) │       │                   │                  │
│  │                  │       │                   │                  │
│  │  compose[0]:     │       │                   │                  │
│  │   Primary        │       │                   │                  │
│  │   No prefix      │       │                   │                  │
│  │   Sets shell     │       │                   │                  │
│  │                  │       │                   │                  │
│  │  compose[1+]:    │       │                   │                  │
│  │   Prefixed pages │       │                   │                  │
│  │   shell_override │       │                   │                  │
│  │                  │       │                   │                  │
│  │  Each provides:  │       │                   │                  │
│  │   pages[]        │       │                   │                  │
│  │   features[]     │       │                   │                  │
│  │   shells{}       │       │                   │                  │
│  └──────┬───────────┘       │                   │                  │
│         │                   │                   │                  │
└─────────┼───────────────────┼───────────────────┼──────────────────┘
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                 BROWNFIELD PROPOSAL PATH                            │
│                                                                     │
│  decantr analyze writes:                                            │
│    .decantr/analysis.json                                           │
│    .decantr/init-seed.json                                          │
│    .decantr/ambient-context.json                                    │
│    .decantr/doctrine-map.json                                       │
│    .decantr/observed-essence.proposal.json                          │
│    .decantr/brownfield-report.md                                    │
│                                                                     │
│  doctrine-map ranks security/data, architecture, design-system,      │
│  workflow/CI, feature/business, assistant-specific, and stale        │
│  sources before the proposal is accepted.                           │
│  Observed routes are grouped into semantic product domains such as   │
│  auth, RBAC, billing, reporting, facilities, settings, and public.   │
│  Route/style scanners cover mixed Next App/Pages Router, React       │
│  Router, Angular, SvelteKit, Vue, Nuxt, Bootstrap, MUI, and Chakra.  │
│                                                                     │
│  decantr init --existing --accept-proposal writes the proposal       │
│  only when no essence exists. Existing essences require              │
│  --merge-proposal or the explicit destructive --replace-essence.     │
│                                                                     │
│  Brownfield contract-only uses existing-app authority: no Decantr    │
│  theme default, no CSS runtime, no rule-file mutation, no registry   │
│  content unless explicitly requested.                               │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│     composeArchetypes() + resolvePatternAlias() + buildEssenceV4()  │
│                                                                     │
│  INPUTS:                                                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
│  │ Archetypes  │  │ Theme Hints │  │Recipe Hints │                │
│  │ (composed)  │  │             │  │             │                │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                │
│         │                │                │                        │
│         ▼                ▼                ▼                        │
│  ┌─────────────────────────────────────────────────────────┐       │
│  │                                                         │       │
│  │              decantr.essence.json (v4)                   │       │
│  │                                                         │       │
│  │  ┌─────────────────────────────────────────────────┐    │       │
│  │  │  DNA (Guarded — design axioms)                  │    │       │
│  │  │                                                 │    │       │
│  │  │  theme ◄──────── Blueprint.theme                │    │       │
│  │  │    id, mode, shape                              │    │       │
│  │  │                                                 │    │       │
│  │  │  typography ◄──── Theme.typography_hints         │    │       │
│  │  │    scale, heading_weight, body_weight           │    │       │
│  │  │                                                 │    │       │
│  │  │  spacing ◄─────── Options.density               │    │       │
│  │  │    base_unit, scale, density, content_gap       │    │       │
│  │  │                                                 │    │       │
│  │  │  radius ◄──────── Theme.radius_hints             │    │       │
│  │  │    philosophy, base                             │    │       │
│  │  │                                                 │    │       │
│  │  │  motion ◄──────── Theme.motion_hints            │    │       │
│  │  │    preference, duration_scale, reduce_motion    │    │       │
│  │  │                                                 │    │       │
│  │  │  color ◄───────── Options/Defaults              │    │       │
│  │  │  elevation ◄───── Defaults                      │    │       │
│  │  │  accessibility ◄─ Options (wcag_level: AA)      │    │       │
│  │  │  personality ◄─── Blueprint/Options             │    │       │
│  │  └─────────────────────────────────────────────────┘    │       │
│  │                                                         │       │
│  │  ┌─────────────────────────────────────────────────┐    │       │
│  │  │  BLUEPRINT (Tracked — evolves with the app)     │    │       │
│  │  │                                                 │    │       │
│  │  │  shell ◄───────── Primary archetype[0].shell    │    │       │
│  │  │                                                 │    │       │
│  │  │  sections[] ◄───── Composed from archetype topology │ │       │
│  │  │    ┌─────────────────────────────────────────┐  │    │       │
│  │  │    │ Primary pages (no prefix):              │  │    │       │
│  │  │    │   home      → [hero, features, cta]     │  │    │       │
│  │  │    │   pricing   → [pricing-table]           │  │    │       │
│  │  │    │                                         │  │    │       │
│  │  │    │ chat-* pages (prefixed):                │  │    │       │
│  │  │    │   chat-main → [chat-header, thread]     │  │    │       │
│  │  │    │   chat-settings → [form-sections]       │  │    │       │
│  │  │    │     shell_override: sidebar-main        │  │    │       │
│  │  │    └─────────────────────────────────────────┘  │    │       │
│  │  │                                                 │    │       │
│  │  │  features[] ◄──── Merged + deduplicated         │    │       │
│  │  └─────────────────────────────────────────────────┘    │       │
│  │                                                         │       │
│  │  ┌─────────────────────────────────────────────────┐    │       │
│  │  │  META                                           │    │       │
│  │  │  archetype, target, platform, guard             │    │       │
│  │  │                                                 │    │       │
│  │  │  guard.dna_enforcement: error|warn|off          │    │       │
│  │  │  guard.blueprint_enforcement: warn|off          │    │       │
│  │  └─────────────────────────────────────────────────┘    │       │
│  │                                                         │       │
│  └─────────────────────────────────────────────────────────┘       │
│                                                                     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    FILE GENERATION                                  │
│                                                                     │
│  decantr.essence.json ◄── Essence v4 (DNA + Blueprint + Meta)       │
│                                                                     │
│  DECANTR.md ◄──────────── Template + theme/pages/guard data         │
│                            (AI assistant instructions)              │
│                                                                     │
│  src/styles/tokens.css ◄── Theme seed + palette → CSS variables     │
│    :root        { --d-primary, --d-bg, --d-text, ... }              │
│    @media (prefers-color-scheme: light) { ... }          (if auto)   │
│                                                                     │
│  src/styles/treatments.css ◄── Visual treatments → CSS rules         │
│    .d-interactive { hover, focus, active states; ... }              │
│    .d-surface     { container surfaces, elevation; ... }            │
│    .d-data        { table, list, grid styling; ... }                │
│    .d-control     { form input focus, error states; ... }           │
│    .d-section     { section rhythm and spacing; ... }               │
│    .d-annotation  { badge, tag, status indicators; ... }            │
│                                                                     │
│  src/styles/decorators.css ◄── Recipe decorators → CSS rules        │
│    .d-glass  { backdrop-filter: blur(8px); ... }                    │
│    .d-card   { border: 1px solid var(--d-border); ... }             │
│                                                                     │
│  CSS files are adoption-mode gated:                                 │
│    contract-only → no Decantr CSS files or @decantr/css guidance    │
│    style-bridge  → bridge tokens/files, no @decantr/css requirement │
│    decantr-css   → full tokens/treatments/decorators guidance       │
│                                                                     │
│  .decantr/project.json ◄── Detection results + init metadata        │
│  .decantr/context/*.md ◄── compiled packs + task and section context │
│  .gitignore            ◄── Adds .decantr/cache/ if not present      │
│                                                                     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    POST-SCAFFOLD                                    │
│                                                                     │
│  1. Validate essence against the v4 schema                          │
│  2. Display file creation summary                                   │
│  3. Generate curated prompt (copy to AI assistant)                  │
│  4. Optionally preview/apply assistant rule bridge                  │
└─────────────────────────────────────────────────────────────────────┘


═══════════════════════════════════════════════════════════════════════
                     RUNTIME FLOW (after init)
═══════════════════════════════════════════════════════════════════════


┌─────────────────────────────────────────────────────────────────────┐
│                    GUARD EVALUATION                                 │
│          (MCP tools, CLI validate, Vite plugin)                     │
│                                                                     │
│  evaluateGuard(essence, context) → GuardViolation[]                 │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  DNA Rules (enforce design axioms)                          │    │
│  │                                                             │    │
│  │  Rule 1: Style    — code theme matches dna.theme.id           │    │
│  │  Rule 2: Density  — spacing matches dna.spacing.content_gap │    │
│  │  Rule 3: A11y     — meets dna.accessibility.wcag_level      │    │
│  │  Rule 4: Mode     — theme/mode combo is compatible          │    │
│  │                                                             │    │
│  │  Severity: controlled by meta.guard.dna_enforcement         │    │
│  │    'error' → violations are errors                          │    │
│  │    'warn'  → violations downgraded to warnings              │    │
│  │    'off'   → violations suppressed entirely                 │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Blueprint Rules (track structural evolution)               │    │
│  │                                                             │    │
│  │  Rule 6: Page exists — code pages in blueprint.pages        │    │
│  │  Rule 7: Layout      — pattern order matches (strict only)  │    │
│  │  Rule 8: Patterns    — referenced patterns exist in registry│    │
│  │                                                             │    │
│  │  Severity: controlled by meta.guard.blueprint_enforcement   │    │
│  │    'warn'  → violations are warnings (default)              │    │
│  │    'off'   → violations suppressed entirely                 │    │
│  │                                                             │    │
│  │  autoFixable: true (can be resolved via decantr_accept_drift)│   │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  Guard Modes: creative (skip all) | guided (1,2,4,5,6,8) |         │
│               strict (all rules including 3 + 7)                   │
└─────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────┐
│                  DATA SOURCE CASCADE                                │
│           (Priority order for DNA field derivation)                 │
│                                                                     │
│  ┌───────────────────────────────────────────────────────┐          │
│  │                                                       │          │
│  │   DNA Field        Source Priority                    │          │
│  │   ─────────        ───────────────                    │          │
│  │                                                       │          │
│  │   theme.*          Blueprint.theme                    │          │
│  │                                                       │          │
│  │   typography.*     Theme.typography_hints > Defaults   │          │
│  │                                                       │          │
│  │   spacing.*        Options.density > Defaults          │          │
│  │                                                       │          │
│  │   radius.*         Recipe.radius_hints > Theme.shape   │          │
│  │                    > Defaults                         │          │
│  │                                                       │          │
│  │   motion.*         Recipe.animation > Theme.motion_    │          │
│  │                    hints > Defaults                   │          │
│  │                                                       │          │
│  │   color.*          Defaults (semantic, 1 accent)       │          │
│  │                                                       │          │
│  │   elevation.*      Defaults (layered, 3 levels)        │          │
│  │                                                       │          │
│  │   accessibility.*  User choice > AA default            │          │
│  │                                                       │          │
│  │   personality      Blueprint > Options > [professional]│          │
│  │                                                       │          │
│  └───────────────────────────────────────────────────────┘          │
│                                                                     │
│  After init, the essence file IS the source of truth.               │
│  The cascade only matters at scaffold time.                         │
└─────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────┐
│                CONTENT REGISTRY PIPELINE                            │
│                                                                     │
│  decantr-content repo (JSON files)                                  │
│       │                                                             │
│       │  push to main                                               │
│       ▼                                                             │
│  GitHub Actions: validate.js → sync-to-registry.js                  │
│       │                                                             │
│       │  POST /v1/admin/sync (X-Admin-Key)                          │
│       ▼                                                             │
│  Supabase DB (namespace=@official, status=published)                │
│       │                                                             │
│       ├──→ API serves: GET /v1/{type}/@official/{slug}              │
│       │       │                                                     │
│       │       ├──→ CLI fetches (Custom → API → Cache)               │
│       │       └──→ MCP server fetches (RegistryAPIClient)           │
│       │                                                             │
│       └──→ Community publishes: POST /v1/content                    │
│               │                                                     │
│               └──→ Moderation queue (untrusted users)               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```
