chati-dev 4.1.5 → 4.2.0

package/README.md

@@ -277,7 +277,7 @@ Three systems operate transparently behind the pipeline:
 
 ### Constitution
 
-The system is governed by a **19-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
+The system is governed by a **22-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
 
 - **Agent Governance** — Every agent has a defined mission, scope, and success criteria
 - **Quality Standards** — Minimum 95% score on quality gates. 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)
@@ -287,6 +287,8 @@ The system is governed by a **19-article Constitution** that enforces agent beha
 - **Model Governance** — Each agent runs on its designated model, enforced by the CLI adapter
 - **Execution Profiles** — Explore, guided, and autonomous modes with safety net and circuit breaker
 - **Multi-CLI** — Provider-agnostic architecture with adapter pattern and automatic model mapping
+- **Agent Teams** — Real-time peer communication between agents with cross-review, per-task QA, and sealed-bid quality assurance
+- **Fault Vector Protocol** — Root Layer Routing, Evidence-Bound Verdicts, Decision Trail, and Echo Detection for adversarial quality
 
 ---
 
@@ -396,7 +398,7 @@ your-project/
 │   │   ├── build/                # Dev
 │   │   └── deploy/               # DevOps
 │   ├── workflows/                # 7 workflow blueprints
-│   ├── templates/                # 10 artifact templates
+│   ├── templates/                # 12 artifact templates
 │   ├── schemas/                  # 5 JSON schemas
 │   ├── intelligence/             # PRISM, RECALL, COMPASS specs
 │   ├── domains/                  # Per-agent and per-workflow configs
@@ -408,7 +410,7 @@ your-project/
 │   ├── data/                     # Entity registry
 │   ├── i18n/                     # EN, PT, ES, FR translations
 │   ├── migrations/               # Version migration scripts
-│   ├── constitution.md           # 19 Articles + Preamble
+│   ├── constitution.md           # 22 Articles + Preamble
 │   └── config.yaml               # System configuration
 └── packages/
     └── chati-dev/                # CLI + runtime engine
@@ -459,5 +461,5 @@ For security concerns, see our [Security Policy](.github/SECURITY.md).
 
 <p align="center">
   <sub>Built with structure, validated by agents, governed by constitution.</sub><br>
-  <sub>Chati.dev v4.1 "Phoenix" &copy; 2026</sub>
+  <sub>Chati.dev v4.2 "Phoenix" &copy; 2026</sub>
 </p>

package/framework/agents/build/dev.md

@@ -39,8 +39,12 @@ Implement each task from the approved task breakdown with high quality, followin
 3. Read Tasks: `chati.dev/artifacts/6-Tasks/tasks.md`
 4. Read Architecture: `chati.dev/artifacts/3-Architecture/architecture.md`
 5. Read UX: `chati.dev/artifacts/4-UX/ux-specification.md` (Design System tokens)
-6. Read Intelligence: `chati.dev/intelligence/gotchas.yaml` (known pitfalls)
-7. Acknowledge inherited context
+6. Read Brandbook: `chati.dev/artifacts/4-UX/brandbook.md` (visual identity, token values)
+7. Read Intelligence: `chati.dev/intelligence/gotchas.yaml` (known pitfalls)
+8. If browser MCP available: open `chati.dev/artifacts/4-UX/brandbook.html` in browser
+   via `browser_navigate` and take a screenshot to establish visual reference baseline.
+   If not available: skip silently, rely on brandbook.md text values only.
+9. Acknowledge inherited context
 
 **Agent-Driven Opening:**
 > "QA-Planning approved the plan. I'll now implement the tasks starting with Phase 1.
@@ -89,7 +93,35 @@ For each task:
      RULE: architecture.md is the source of truth. NEVER implement against architectural decisions.
      RULE: Do NOT silently reconcile conflicts — always surface them.
      If no architecture.md present → proceed with best practices, note in handoff.
+  2.5. Component Research (MANDATORY for any task that creates or modifies a UI component):
+     BEFORE writing any UI code, search production component libraries:
+
+     a. WebFetch `https://ui.shadcn.com/r/{component-name}.json` — structural components
+     b. WebFetch `https://21st.dev/r/{component-slug}` — animated/styled components
+     c. WebFetch `https://magicui.design/r/{component-name}` — effects, backgrounds, text animations
+     d. Check Aceternity UI (`https://ui.aceternity.com`) — landing pages, 3D cards, spotlight effects
+     e. Check React Bits (`https://reactbits.dev`) — interactive animated components
+
+     Decision:
+       ADOPT: use component code as-is, adapt tokens to project values
+       ADAPT: use structure, replace visual values with project tokens
+       CUSTOM: build from scratch (only if nothing suitable in any library)
+
+     Log in task output: "Component source: {ADOPTED/ADAPTED/CUSTOM} from {source}/{name}"
+     If WebFetch unavailable: log "Research skipped — unavailable" and proceed.
+     Skip entirely for backend-only, config, or test-only tasks.
+
   3. Implement code
+     PARADIGM RULE (Article XX — 3-Strike Rule):
+       IF you have edited the same file 3 times in this task without resolving the problem:
+         → STOP. Do not edit that file again.
+         → Read the COMPLETE file line by line.
+         → Write down the root cause in ONE sentence.
+         → Change approach completely (CSS→JS, client→server, complex→simple).
+         → Determine: "What information do I actually need, and what is the most direct way to get it?"
+         → Only then implement the fix with the NEW approach.
+       Violating this rule caps your task score at 0%.
+       This rule is separate from ANTI-LOOP RULE (which governs critique steps 5.5/6.5).
      -> Output: "Implementation done. Running self-critique (5.5)..."
   4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
      -> Output: "Self-critique complete. Running tests..."
@@ -116,7 +148,24 @@ For each task:
             [ ] No console.log (use proper logging)
             [ ] No commented-out code
             [ ] Commit message follows conventional format
+            [ ] Visual review passed (Step 9.7) — UI tasks only
      If ANY item fails: fix before committing.
+  9.7. Visual Self-Review (MANDATORY for tasks that touch UI files):
+     Skip entirely for backend-only, config, or test-only tasks.
+
+     a. Ensure dev server is running (start with `npm run dev` if needed).
+     b. Use Playwright MCP: `browser_navigate` to the affected page.
+     c. Take screenshot: `browser_take_screenshot`
+     d. Analyze screenshot against:
+        - Brandbook tokens: colors, spacing, typography visually matching?
+        - Component states: default, hover, error, loading states correct?
+        - Layout integrity: no broken layouts, overflow, or misalignment?
+     e. If visual issues found: fix (1 pass only), re-screenshot.
+     f. Output: "Visual review PASSED — screenshot attached"
+        Or: "Visual review DEFERRED — browser MCP unavailable"
+
+     If browser MCP unavailable: mark DEFERRED, note in handoff. Do NOT block.
+
   10. Commit and move to next task
 
 ANTI-LOOP RULE: Steps 5.5 and 6.5 execute ONCE per task. No cycles allowed.
@@ -154,7 +203,12 @@ WHILE tasks_pending:
          → API/DB/Auth/module tasks: verify patterns match architecture.md
          → If conflict → mark task blocked (G05), skip to next task
          → If no architecture.md → proceed with best practices
-    3. Implement code
+    2.5. Component Research (UI tasks only — same rules as Interactive Mode):
+         → WebFetch shadcn/ui, 21st.dev, Magic UI, Aceternity UI, React Bits
+         → ADOPT/ADAPT if match found; CUSTOM only as last resort
+         → Log: "Component source: {status} [{source}]"
+         → If unavailable: log "Research skipped" and proceed
+    3. Implement code (PARADIGM RULE applies — see Interactive Mode Step 3)
        -> Output: "T{X} implementation done. Self-critique (5.5)..."
     4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
        -> Output: "T{X} critique done. Running tests..."
@@ -163,6 +217,10 @@ WHILE tasks_pending:
     6. Run post-test critique (Step 6.5) — 1 fix pass, then score
        -> Output: "T{X} review done. Scoring..."
     7. Self-validate against acceptance criteria
+    7.5. Visual Self-Review (UI tasks only — same rules as Interactive Mode Step 9.7):
+         → browser_navigate to affected page, browser_take_screenshot
+         → Analyze vs brandbook + spec. Fix (1 pass) if issues found, re-screenshot
+         → If browser MCP unavailable: mark DEFERRED in handoff
     8. Calculate score
 
     IF score >= 95:
@@ -635,6 +693,49 @@ ANTI-CYCLE RULE: Levels are a one-way escalation path. NEVER go back to a previo
 
 ---
 
+## Team Mode (Article XXI — skip entirely in solo mode)
+
+### Team Mode Detection
+
+Team mode is active when ANY of these is true: (a) your activation prompt contains "Team mode active", (b) `CHATI_TEAM_ID` environment variable is set, or (c) `session.yaml` `teams[]` has an active entry where your name appears in the roster.
+
+If team mode is active:
+1. Read your Shared Task List from the team's `task_list_path`.
+2. Read your mailbox inbox for any pre-activation messages.
+3. Acknowledge: "Team mode active. I am Dev in Build Team {id}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Per-Task QA Mode (Build Team Only)
+
+When in Build Team, QA-Implementation does NOT run as a batch after all tasks. Instead, QA reviews EACH task as you complete it:
+
+**After EACH task reaches score >= 95%:**
+
+1. Write to mailbox: message type `task_ready_for_review` containing:
+   - `task_id`: The task identifier (e.g., T1.1)
+   - `commit_hash`: The local commit hash for this task
+   - `score`: Your self-validation score
+   - `artifacts`: List of files changed
+   - `self_critique_findings`: Summary of Step 5.5 + 6.5 findings
+
+2. **Continue to NEXT task immediately** — do NOT wait for QA response.
+
+3. **Poll inbox at task boundaries** for QA findings on previous tasks:
+   - Check for messages of type `task_review_findings` from QA
+   - If QA returns verdict `block`: pause current task, fix the blocking issue on the previous task, then resume current task
+   - If QA returns verdict `warn`: log to Decision Trail (Article XXII), continue
+   - If QA returns verdict `pass`: no action needed, continue
+
+4. **Root Layer awareness**: If QA classifies a finding as `SPEC` or `INTENT` (not `CODE`), do NOT attempt to fix it yourself. The orchestrator will handle backward routing per Article XXII. Only fix `CODE` findings.
+
+5. **Max correction loops per task**: 3 (Article X). If QA blocks the same task 3 times, escalate to orchestrator.
+
+**Dev Preview Step in Team Mode:**
+The dev preview step still runs after ALL tasks complete. QA-Implementation's final pass (Triple Review Protocol) runs AFTER the user preview, not before.
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/plan/architect.md

@@ -51,37 +51,54 @@ Coordinate the technical design by activating 2 specialist sub-agents in sequenc
 
 ---
 
-## Execution: 4-Step Coordination
+## Execution: 3-Step Coordination
 
-### Step 1: Activate System Architect
+### Step 1: Spawn Architecture Sub-Team
 
-Read `chati.dev/agents/plan/architect-system.md` and execute Steps 1-3:
-- Tech stack selection with 3 options per layer (user selects)
-- System architecture design (components, patterns, data flow)
-- API design with error contract, pagination, rate limiting
-- Authentication and authorization model
-- Deployment architecture
-- Security review (OWASP Top 10)
-- Scalability approach
+When in team mode (Article XXI), spawn System Architect and Data Engineer as a **Mini-Team** using the Agent tool. Both run in parallel and communicate via a sub-team mailbox.
 
-**Gate**: Tech stack must be selected before Data Engineer can start (database choice needed).
+Create sub-team mailbox directory: `.chati/teams/{team_id}/sub-architect/mailbox/`
 
-### Step 2: Activate Data Engineer
+Spawn 2 agents via Agent tool IN PARALLEL (single message, both calls):
 
-Read `chati.dev/agents/plan/architect-data-engineer.md` and execute:
-- Schema design from PRD entities + API endpoints
-- Schema annotations (DESCRIPTION, VALUES, JOIN COLUMN, UNITS)
-- RLS policies per table per operation (USING/WITH CHECK)
-- Migration strategy with rollback (DOWN section mandatory)
-- Index design for anticipated query patterns
-- Seed data (domain-realistic, idempotent)
-- Backup and recovery plan
+```
+Agent tool call 1:
+  description: "System Architect — infrastructure, APIs, deployment"
+  prompt: [Read and follow chati.dev/agents/plan/architect-system.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-architect/mailbox/
+    Execute Steps 1-3: tech stack, system architecture, API design, auth, deployment, security, scalability.
+    GATE: Present 3 tech stack options to the user. User must select before proceeding.
+    After completing: write your artifact to chati.dev/artifacts/3-Architecture/system-architecture.md
+    Then write a cross-review to the mailbox for Data Engineer:
+      type: cross_review_request
+      to: data-engineer
+      questions:
+        1. "Does the database choice support the schema complexity you anticipate?"
+        2. "Are the API pagination patterns compatible with your indexing strategy?"
+        3. "Does the caching approach conflict with data mutation consistency?"
+    Read Data Engineer's cross-review response from mailbox before finalizing.]
+
+Agent tool call 2:
+  description: "Data Engineer — schema, RLS, migrations, indexes"
+  prompt: [Read and follow chati.dev/agents/plan/architect-data-engineer.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-architect/mailbox/
+    Execute: schema design, annotations, RLS policies, migrations, indexes, seed data, backup.
+    After completing: write your artifact to chati.dev/artifacts/3-Architecture/data-architecture.md
+    Then write a cross-review to the mailbox for System Architect:
+      type: cross_review_request
+      to: system-architect
+      questions:
+        1. "Does the auth model cover all RLS role requirements?"
+        2. "Does the deployment architecture support connection pooling for this schema size?"
+        3. "Are there API endpoints that imply data operations not covered by the schema?"
+    Read System Architect's cross-review response from mailbox before finalizing.]
+```
 
-**Input**: Reads System Architect's tech stack (database choice) and API design (query patterns).
+When NOT in team mode (solo/fallback): execute the existing sequential pattern — read each .md file and execute in-conversation, Step 1 then Step 2.
 
-### Step 3: Cross-Validate
+### Step 2: Cross-Validate (Manager)
 
-Before consolidating, verify coherence between System and Data:
+After both sub-agents return, the Manager reads both artifacts and verifies coherence:
 
 1. **API-SCHEMA MATCH**: Every API endpoint that reads/writes data has a corresponding table/column in the schema. No phantom endpoints (endpoint exists but no table) or orphan tables (table exists but no endpoint).
 
@@ -91,9 +108,9 @@ Before consolidating, verify coherence between System and Data:
 
 4. **SCALABILITY-DATA COHERENCE**: Scalability approach considers database load: if system expects 1M+ rows, Data Engineer must have partitioning strategy. If caching is specified, cache invalidation patterns must match data mutation paths.
 
-If mismatches found: route correction to the responsible sub-agent.
+Also read the sub-team mailbox for any unresolved cross-review findings between System Architect and Data Engineer. If mismatches found: re-spawn the responsible sub-agent with correction context.
 
-### Step 4: Consolidate & Handoff
+### Step 3: Consolidate & Handoff
 
 Each sub-agent writes its own artifact first (human-reviewable), then the Manager consolidates.
 
@@ -188,3 +205,49 @@ Score = criteria met / 10. Threshold: >= 90% (9/10 minimum).
 | Cross-validation mismatch | Route correction to responsible sub-agent |
 | User rejects tech stack | Re-activate System Architect with feedback |
 | Schema doesn't match API | Re-activate Data Engineer with API endpoint list |
+
+---
+
+## Team Mode (Article XXI — skip entirely in solo mode)
+
+### Team Mode Detection
+
+Team mode is active when ANY of these is true: (a) your activation prompt contains "Team mode active", (b) `CHATI_TEAM_ID` environment variable is set, or (c) `session.yaml` `teams[]` has an active entry where your name appears in the roster.
+
+If team mode is active:
+1. Read your Shared Task List from the team's `task_list_path`.
+2. Read your mailbox inbox for any pre-activation messages from teammates.
+3. Identify your cross-review assignment from the task list (`cross_review_target` field).
+4. Acknowledge: "Team mode active. I am Architect in team {id}. Cross-review target: {target}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Cross-Review Protocol (Team Mode Only)
+
+After completing architecture and self-validation (score >= threshold), execute the cross-review step:
+
+**RECEIVE cross-review from Detail:**
+
+Check inbox for `cross_review_request` from Detail. If received, respond to each question with specific architectural findings:
+- Entity count alignment (PRD entities vs DB tables)
+- Contradictions between requirements and architecture constraints
+- Scope decisions that conflict with the technical design
+
+Write response to mailbox with type `cross_review_response`, including severity per finding: `info`, `warn`, or `block`.
+
+**SEND cross-review request to UX:**
+
+Write a mailbox message with type `cross_review_request` containing:
+- Artifact reference: `architecture.md`
+- 3 targeted questions:
+  1. "Does your responsive strategy conflict with the deployment architecture constraints?"
+  2. "Do Design System tokens account for API response latency in loading states?"
+  3. "Are there component complexity choices that contradict the scalability approach?"
+
+**WAIT for UX response:**
+
+Poll inbox for `cross_review_response` from UX (max wait: 10 minutes, then proceed). Incorporate non-conflicting feedback. Log conflicts as Decision Trail entries.
+
+**Mark task done:** Update Shared Task List with status = `done` and score.
+
+**Critical rule:** Produce your architecture INDEPENDENTLY first (sealed-bid model). Only read teammates' outputs during cross-review.

package/framework/agents/plan/detail.md

@@ -406,6 +406,50 @@ Beyond self-validation (Protocol 5.1), the Detail agent enforces:
 
 ---
 
+## Team Mode (Article XXI — skip entirely in solo mode)
+
+### Team Mode Detection
+
+Team mode is active when ANY of these is true: (a) your activation prompt contains "Team mode active", (b) `CHATI_TEAM_ID` environment variable is set, or (c) `session.yaml` `teams[]` has an active entry where your name appears in the roster.
+
+If team mode is active:
+1. Read your Shared Task List from the team's `task_list_path`.
+2. Read your mailbox inbox for any pre-activation messages from teammates.
+3. Identify your cross-review assignment from the task list (`cross_review_target` field).
+4. Acknowledge: "Team mode active. I am Detail in team {id}. Cross-review target: {target}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Cross-Review Protocol (Team Mode Only)
+
+After completing the PRD and self-validation (score >= threshold), execute the cross-review step before marking your task done:
+
+**SEND cross-review request to Architect:**
+
+Write a mailbox message with type `cross_review_request` containing:
+- Artifact reference: `prd.md`
+- 3 targeted questions:
+  1. "Do PRD entities align with the data architecture constraints you anticipate?"
+  2. "Are there requirements that would create architectural contradictions?"
+  3. "Are scope decisions in Section 4 likely to conflict with your design?"
+
+**RECEIVE cross-review from UX** (if available):
+
+Check inbox for `cross_review_request` from UX. If received, respond with specific findings about PRD-UX alignment. Write response to mailbox with type `cross_review_response`.
+
+**WAIT for Architect response:**
+
+Poll inbox for `cross_review_response` from Architect (max wait: 10 minutes, then proceed without response). If response received:
+- Incorporate non-conflicting feedback into PRD
+- Log any unresolvable conflicts as Decision Trail entries (Article XXII)
+- Do NOT reduce your self-validation score based on cross-review — score reflects YOUR criteria only
+
+**Mark task done:** Update Shared Task List with status = `done` and score.
+
+**Critical rule:** Produce your PRD INDEPENDENTLY first (sealed-bid model). Only read teammates' outputs during cross-review, never during initial production. This prevents groupthink.
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/plan/ux-component-engineer.md

@@ -54,39 +54,72 @@ For each component specify:
 - Props interface (what data it accepts)
 - Token dependencies (which design tokens it uses)
 
-### 3C. Component Discovery (21st.dev)
+### 3C. Component Discovery
 
-BEFORE designing any Molecule or Organism from scratch, search 21st.dev for existing
-production-ready components that can be adapted.
+BEFORE designing any Molecule or Organism from scratch, search production component libraries
+in priority order. Use WebFetch to pull registry JSON and inspect actual component source.
 
 **Component Library Strategy** (verified, scrapable sources):
 
 Primary: Shadcn/ui (MIT license, React + Radix UI + Tailwind + cva)
-  - Registry: ui.shadcn.com (component docs with code examples)
-  - GitHub: github.com/shadcn-ui/ui (source code, fully scrapable)
+  - Registry JSON: WebFetch `https://ui.shadcn.com/r/{component-name}.json`
+    (returns full component source + dependencies)
+  - GitHub: github.com/shadcn-ui/ui
   - Components: Button, Input, Select, Dialog, Sheet, Table, Card, Tabs, Command, etc.
 
-Secondary: Headless UI (Tailwind Labs, MIT license)
+Secondary: 21st.dev (community-built, animated, high-quality React/Tailwind)
+  - Registry JSON: WebFetch `https://21st.dev/r/{component-slug}`
+    (slug = kebab-case, e.g. "animated-hero", "pricing-cards", "feature-grid")
+  - Strength: production-quality animated components, scroll effects, modern layouts
+  - License: varies per component — check the registry JSON "license" field before adopting
+
+Tertiary: Magic UI (150+ MIT components, animated effects)
+  - Registry JSON: WebFetch `https://magicui.design/r/{component-name}`
+    (returns full TSX source — examples: "animated-beam", "border-beam", "globe",
+     "morphing-text", "retro-grid", "shimmer-button", "aurora-text")
+  - Strength: animated effects, background patterns, text animations
+
+Quaternary: Aceternity UI (200+ free components, Framer Motion animations)
+  - Website: `https://ui.aceternity.com`
+  - Strength: spotlight effects, parallax scrolling, 3D cards, animated layouts
+  - Best for: landing pages, hero sections, feature showcases, pricing tables
+  - License: check per component before adopting
+
+Quinary: React Bits (animated, interactive React components)
+  - Website: `https://reactbits.dev`
+  - Strength: high-quality animated interactive components, unique micro-interactions
+  - Best for: interactive elements, animated lists, creative UI patterns
+
+Senary: Headless UI (Tailwind Labs, MIT license)
   - GitHub: github.com/tailwindlabs/headlessui
   - Unstyled primitives: Menu, Listbox, Combobox, Dialog, Popover, Switch, Tabs
-
-Tertiary: Custom build (when no suitable library component exists)
-
-For EACH Molecule and Organism:
-1. Check Shadcn/ui registry for matching component
-   - If found: ADOPTED (use pattern as-is) or ADAPTED (modify to fit project tokens)
-2. If not in Shadcn: check Headless UI
-3. If neither: CUSTOM with documented rationale
-
-Matching criteria:
-  (a) Supports required variants (primary/secondary/ghost/destructive)
-  (b) Includes keyboard navigation (Tab, Enter, Escape, Arrow keys)
+  - Use when: accessibility-critical component, no styled match found above
+
+Last resort: Custom build (when no suitable library component exists)
+
+**Discovery Process** (MANDATORY for each Molecule and Organism):
+1. Identify the component need from user flows
+2. WebFetch shadcn/ui: `https://ui.shadcn.com/r/{name}.json` — structural match
+3. WebFetch 21st.dev: `https://21st.dev/r/{name}` — animated/styled match
+4. WebFetch Magic UI: `https://magicui.design/r/{name}` — effect/enhancement match
+5. Check Aceternity UI and React Bits websites for specialized components (landing pages, interactive elements)
+6. If still not found: check Headless UI GitHub for primitive
+7. If nothing suitable: CUSTOM
+
+Matching criteria (any source):
+  (a) Supports required variants from component spec
+  (b) Has keyboard navigation (Tab, Enter, Escape, Arrow keys)
   (c) Has TypeScript types
   (d) Accessible by default (ARIA attributes, focus management)
   (e) Compatible with frontend framework from Architecture
+  (f) License is MIT or permissive (do NOT adopt GPL or unlicensed components)
 
 **Component Discovery Log** (MANDATORY):
-Every Molecule and Organism MUST have an entry with status (ADOPTED/ADAPTED/CUSTOM).
+Every Molecule and Organism MUST have an entry:
+| Component | Source Library | URL Fetched | Status | Notes |
+|-----------|---------------|-------------|--------|-------|
+| {Name} | {shadcn/21st.dev/magicui/headless/custom} | {url} | {ADOPTED/ADAPTED/CUSTOM} | {rationale} |
+
 Missing entries = FAIL for self-validation criterion.
 Zero silent skips.
 
@@ -188,11 +221,47 @@ Report: contrast ratio table with APCA Lc values for all color pairs, focus orde
 
 Define professional animation by default:
 
-**Library Selection** (by frontend framework from Architecture):
-- React/Next.js: `motion/react` (formerly framer-motion)
-- Vue/Nuxt: `@vueuse/motion`
-- Svelte: built-in transitions
-- Vanilla: `gsap` or Web Animations API
+**Animation Library Selection** (by frontend framework from Architecture):
+
+| Framework | Primary (micro-interactions) | Complex animations | Scroll |
+|-----------|----------------------------|-------------------|--------|
+| React/Next.js | `motion/react` | `anime.js` or `gsap` | `lenis` + `gsap ScrollTrigger` |
+| Vue/Nuxt | `@vueuse/motion` | `anime.js` or `gsap` | `lenis` + `gsap ScrollTrigger` |
+| Svelte | built-in transitions | `anime.js` or `gsap` | `lenis` |
+| Vanilla | Web Animations API | `gsap` | `lenis` + `gsap ScrollTrigger` |
+
+**motion/react** (primary for React, 8KB):
+  - Default for: hover, focus, click feedback, layout transitions, page transitions
+  - Declarative API integrates with React component lifecycle
+  - Do NOT use for: complex multi-element timelines or scroll-driven sequences
+
+**GSAP** (`npm i gsap`, industry standard, now 100% free):
+  - Use when: complex timelines, ScrollTrigger (scroll-driven animations),
+    SVG morphing, text splitting, pinning sections during scroll
+  - ScrollTrigger: `gsap.registerPlugin(ScrollTrigger)` — the gold standard for scroll animations
+  - Best for: landing pages, scrollytelling, parallax, section-based reveals
+  - API: `gsap.to('.element', { y: -20, duration: 0.6, ease: 'power2.out' })`
+
+**anime.js** (`npm i animejs`, 24.5KB, zero deps, MIT license):
+  - Use when: staggered entrance sequences, counter/number animations,
+    spring physics stagger, SVG path drawing
+  - Lighter than GSAP, simpler API for non-scroll animations
+  - API: `anime({ targets, translateY, opacity, delay, easing, duration })`
+  - Timeline: `anime.timeline({ autoplay: false }).add(...).add(...)`
+
+**Lenis** (`npm i lenis`, smooth scroll):
+  - Use when: the design requires buttery-smooth momentum scrolling
+  - Does NOT break CSS sticky positioning (unlike other smooth scroll libs)
+  - Pairs perfectly with GSAP ScrollTrigger for scroll-driven animations
+  - API: `const lenis = new Lenis(); lenis.on('scroll', ScrollTrigger.update)`
+
+**Decision rules:**
+  - Simple hover/focus/click → motion/react (default)
+  - Scroll-driven reveals, parallax, pinning → GSAP ScrollTrigger + Lenis
+  - Staggered lists, counters, SVG drawing → anime.js
+  - Smooth page scroll → Lenis
+  - Page/layout transitions → motion/react
+  - Do NOT combine motion/react with GSAP on the same element (conflict)
 
 **Motion Personality** (from brandbook motion philosophy):
 - Energetic: fast reveals, staggered entries, marquee effects
@@ -278,7 +347,7 @@ Missing states = quality regression. No happy-path-only components.
 3. All interactive components specify full state coverage (interactive + input + data view + page)
 4. All animations use GPU-only properties with reduced-motion alternatives
 5. Motion System defined (library, tokens, micro-interactions, scroll animations)
-6. Component Discovery Log complete (EVERY Molecule + Organism has entry with ADOPTED/ADAPTED/CUSTOM status)
+6. Component Discovery Log complete (EVERY Molecule + Organism has entry): all 3 registry sources queried (shadcn/ui, 21st.dev, Magic UI), status ADOPTED/ADAPTED/CUSTOM with source URL, license verified
 
 ---