create-agentic-app 1.1.57 → 1.1.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-app",
-  "version": "1.1.57",
+  "version": "1.1.59",
   "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
   "type": "module",
   "bin": {

package/template/.agents/skills/checkpoint/SKILL.md

@@ -10,7 +10,7 @@ description: >
 
 # Checkpoint Commit
 
-Create a comprehensive checkpoint commit that captures all current changes with a detailed, well-structured commit message.
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
 
 ## Instructions
 
@@ -23,7 +23,17 @@ Run these commands to understand the full picture:
 3. `git diff --cached` — see already-staged changes
 4. `git log -5 --oneline` — understand this repo's commit message style
 
-### Step 2: Stage Everything
+### Step 2: Quality Checks
+
+Run all three checks. If any fail, fix the issues before proceeding — do not skip or ignore failures.
+
+1. `npm run lint` — fix any lint errors
+2. `npm run type-check` — fix any type errors (if the script doesn't exist, try `npx tsc --noEmit`)
+3. `npm run build` — fix any build errors
+
+Iterate until all three pass cleanly. Only then move to the next step.
+
+### Step 3: Stage Everything
 
 Stage all changes — tracked modifications, deletions, and new untracked files:
 
@@ -31,20 +41,16 @@ Stage all changes — tracked modifications, deletions, and new untracked files:
 git add -A
 ```
 
-### Step 3: Craft the Commit Message
+### Step 4: Craft the Commit Message
 
 Write a commit message following the project's existing conventions (observed from `git log`). Structure:
 
 - **First line**: clear, concise summary in imperative mood (50-72 chars)
   - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
-- **Body** (separated by blank line): detailed description including:
-  - What changes were made (key modifications)
-  - Why these changes were made (purpose/motivation)
-  - Important technical details or decisions
-  - Breaking changes or migration notes if applicable
+- **Body** (separated by blank line): a short TL;DR of the changes — 1-3 sentences max. No bullet lists, no file-by-file breakdowns, no lengthy explanations.
 - **Footer**: co-author attribution
 
-### Step 4: Commit
+### Step 5: Commit
 
 Create the commit using a heredoc for proper formatting:
 
@@ -52,14 +58,14 @@ Create the commit using a heredoc for proper formatting:
 git commit -m "$(cat <<'EOF'
 {first line}
 
-{body}
+{tldr}
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 EOF
 )"
 ```
 
-### Step 5: Report
+### Step 6: Report
 
 Display:
 - The commit hash and message summary
@@ -70,6 +76,7 @@ Display:
 
 - Stage and commit everything — do not skip files unless they are clearly sensitive (`.env`, credentials)
 - If the repo has no git history, run `git init` first
-- Make the commit message descriptive enough that someone reading `git log` understands what was accomplished
+- All quality checks (lint, type-check, build) MUST pass before committing — fix issues, don't skip them
+- Keep the commit body short — a TL;DR, not an essay
 - Follow the project's existing commit conventions (check the log first)
 - Do not push — only commit locally

package/template/.agents/skills/ship-it/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ship-it
+description: >
+  Push the current branch to GitHub and create a pull request. Use this skill when the user says
+  "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review",
+  "get this reviewed", or wants to push their work and open a PR. Also use when the user says
+  "/ship-it". This skill handles prerequisites, branching, pushing, and PR creation — it does not
+  commit or run quality checks (use checkpoint for that first).
+---
+
+# Ship It
+
+Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
+
+This skill complements `checkpoint`. Use `checkpoint` to commit locally (with quality gates), then `ship-it` to get the code to GitHub for review.
+
+## Instructions
+
+### Step 0: Prerequisites
+
+Verify tooling before doing anything else.
+
+1. **GitHub CLI installed?**
+   ```bash
+   gh --version
+   ```
+   If the command fails (not found):
+   - Detect the platform and attempt to install:
+     - **Windows:** `winget install --id GitHub.cli`
+     - **macOS:** `brew install gh`
+     - **Linux (Debian/Ubuntu):** follow the official apt instructions
+   - If auto-install fails, tell the user what to install and stop.
+
+2. **GitHub CLI authenticated?**
+   ```bash
+   gh auth status
+   ```
+   If not authenticated, tell the user:
+   ```
+   GitHub CLI is not logged in. Please run this in the prompt:
+     ! gh auth login
+   Then re-run /ship-it.
+   ```
+   Stop here — do not proceed until auth is confirmed.
+
+3. **Git remote exists?**
+   ```bash
+   git remote -v
+   ```
+   If no remote named `origin` exists, stop and tell the user:
+   ```
+   No git remote found. Add one with:
+     git remote add origin https://github.com/{user}/{repo}.git
+   ```
+
+### Step 1: Detect the Environment
+
+Run these commands to understand the current state:
+
+1. `git branch --show-current` — get the current branch name
+2. Detect the default branch:
+   ```bash
+   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+   ```
+3. `git status --porcelain` — check for uncommitted changes
+
+If there are uncommitted changes, stop and tell the user:
+```
+You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.
+```
+
+Store the default branch name for use throughout the remaining steps.
+
+### Step 2: Check for Unpushed Commits
+
+Determine if there are commits that haven't been pushed yet.
+
+**If on a feature branch with a remote tracking branch:**
+```bash
+git log @{upstream}..HEAD --oneline
+```
+
+**If on a feature branch with no remote tracking branch, or on the default branch:**
+```bash
+git log origin/{default_branch}..HEAD --oneline
+```
+
+If there are **no unpushed commits**, stop and tell the user:
+```
+Nothing to ship — all commits are already pushed.
+```
+
+Save the list of unpushed commit messages for use in later steps.
+
+### Step 3: Handle Branching
+
+**If already on a feature branch** (not the default branch):
+- Stay on it. No branching needed.
+- Skip to Step 4.
+
+**If on the default branch:**
+- Generate a branch name from the unpushed commit messages:
+  - Read the commit subjects
+  - Derive a kebab-case branch name with a conventional prefix: `feat/`, `fix/`, `refactor/`, `chore/`, `docs/` based on the commit content
+  - Keep it short (3-5 words max after the prefix), e.g., `feat/add-user-auth`, `fix/login-redirect-loop`
+  - Strip special characters, lowercase everything
+- Create and switch to the new branch:
+  ```bash
+  git checkout -b {branch_name}
+  ```
+- Tell the user: `Created branch {branch_name}`
+
+### Step 4: Push to Origin
+
+```bash
+git push -u origin {branch_name}
+```
+
+If the branch already has a remote tracking branch, a regular `git push` is fine.
+
+### Step 5: Check for Existing PR
+
+Before creating a new PR, check if one already exists for this branch:
+
+```bash
+gh pr view --json number,url,title,state 2>/dev/null
+```
+
+If a PR already exists and is **open**:
+- Do NOT create a new one
+- Skip to Step 7 and report the existing PR with a note that new commits were pushed.
+
+If no PR exists (or it is closed/merged), proceed to Step 6.
+
+### Step 6: Create the Pull Request
+
+Generate the PR title and body from the unpushed commits:
+
+- **Title**: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
+- **Body**: TL;DR of the changes in 2-4 bullet points max.
+
+```bash
+gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{2-4 bullet points}
+
+---
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 7: Report
+
+Display the result clearly:
+
+```
+Shipped to GitHub:
+  Branch: {branch_name}
+  PR: #{number} — {title}
+  URL: {url}
+```
+
+## Important
+
+- Do NOT run lint, type-check, or build — that is checkpoint's job
+- Do NOT commit anything — only push existing commits and create a PR
+- If the user has uncommitted changes, tell them to run /checkpoint first
+- Keep the PR body short — a TL;DR, not an essay
+- Always check for an existing open PR before creating a new one to avoid duplicates
+- Detect the default branch dynamically — do not hardcode `main` or `master`
+- When creating a branch from the default branch, use conventional prefixes (`feat/`, `fix/`, etc.) with kebab-case names
+- Never run destructive git operations (no `--force`, no `reset --hard`)
+- If `gh` is not installed or authenticated, help the user get set up before proceeding

package/template/.claude/skills/checkpoint/SKILL.md

@@ -10,7 +10,7 @@ description: >
 
 # Checkpoint Commit
 
-Create a comprehensive checkpoint commit that captures all current changes with a detailed, well-structured commit message.
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
 
 ## Instructions
 
@@ -23,7 +23,17 @@ Run these commands to understand the full picture:
 3. `git diff --cached` — see already-staged changes
 4. `git log -5 --oneline` — understand this repo's commit message style
 
-### Step 2: Stage Everything
+### Step 2: Quality Checks
+
+Run all three checks. If any fail, fix the issues before proceeding — do not skip or ignore failures.
+
+1. `npm run lint` — fix any lint errors
+2. `npm run type-check` — fix any type errors (if the script doesn't exist, try `npx tsc --noEmit`)
+3. `npm run build` — fix any build errors
+
+Iterate until all three pass cleanly. Only then move to the next step.
+
+### Step 3: Stage Everything
 
 Stage all changes — tracked modifications, deletions, and new untracked files:
 
@@ -31,20 +41,16 @@ Stage all changes — tracked modifications, deletions, and new untracked files:
 git add -A
 ```
 
-### Step 3: Craft the Commit Message
+### Step 4: Craft the Commit Message
 
 Write a commit message following the project's existing conventions (observed from `git log`). Structure:
 
 - **First line**: clear, concise summary in imperative mood (50-72 chars)
   - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
-- **Body** (separated by blank line): detailed description including:
-  - What changes were made (key modifications)
-  - Why these changes were made (purpose/motivation)
-  - Important technical details or decisions
-  - Breaking changes or migration notes if applicable
+- **Body** (separated by blank line): a short TL;DR of the changes — 1-3 sentences max. No bullet lists, no file-by-file breakdowns, no lengthy explanations.
 - **Footer**: co-author attribution
 
-### Step 4: Commit
+### Step 5: Commit
 
 Create the commit using a heredoc for proper formatting:
 
@@ -52,14 +58,14 @@ Create the commit using a heredoc for proper formatting:
 git commit -m "$(cat <<'EOF'
 {first line}
 
-{body}
+{tldr}
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 EOF
 )"
 ```
 
-### Step 5: Report
+### Step 6: Report
 
 Display:
 - The commit hash and message summary
@@ -70,6 +76,7 @@ Display:
 
 - Stage and commit everything — do not skip files unless they are clearly sensitive (`.env`, credentials)
 - If the repo has no git history, run `git init` first
-- Make the commit message descriptive enough that someone reading `git log` understands what was accomplished
+- All quality checks (lint, type-check, build) MUST pass before committing — fix issues, don't skip them
+- Keep the commit body short — a TL;DR, not an essay
 - Follow the project's existing commit conventions (check the log first)
 - Do not push — only commit locally

package/template/.claude/skills/ship-it/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ship-it
+description: >
+  Push the current branch to GitHub and create a pull request. Use this skill when the user says
+  "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review",
+  "get this reviewed", or wants to push their work and open a PR. Also use when the user says
+  "/ship-it". This skill handles prerequisites, branching, pushing, and PR creation — it does not
+  commit or run quality checks (use checkpoint for that first).
+---
+
+# Ship It
+
+Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
+
+This skill complements `checkpoint`. Use `checkpoint` to commit locally (with quality gates), then `ship-it` to get the code to GitHub for review.
+
+## Instructions
+
+### Step 0: Prerequisites
+
+Verify tooling before doing anything else.
+
+1. **GitHub CLI installed?**
+   ```bash
+   gh --version
+   ```
+   If the command fails (not found):
+   - Detect the platform and attempt to install:
+     - **Windows:** `winget install --id GitHub.cli`
+     - **macOS:** `brew install gh`
+     - **Linux (Debian/Ubuntu):** follow the official apt instructions
+   - If auto-install fails, tell the user what to install and stop.
+
+2. **GitHub CLI authenticated?**
+   ```bash
+   gh auth status
+   ```
+   If not authenticated, tell the user:
+   ```
+   GitHub CLI is not logged in. Please run this in the prompt:
+     ! gh auth login
+   Then re-run /ship-it.
+   ```
+   Stop here — do not proceed until auth is confirmed.
+
+3. **Git remote exists?**
+   ```bash
+   git remote -v
+   ```
+   If no remote named `origin` exists, stop and tell the user:
+   ```
+   No git remote found. Add one with:
+     git remote add origin https://github.com/{user}/{repo}.git
+   ```
+
+### Step 1: Detect the Environment
+
+Run these commands to understand the current state:
+
+1. `git branch --show-current` — get the current branch name
+2. Detect the default branch:
+   ```bash
+   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+   ```
+3. `git status --porcelain` — check for uncommitted changes
+
+If there are uncommitted changes, stop and tell the user:
+```
+You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.
+```
+
+Store the default branch name for use throughout the remaining steps.
+
+### Step 2: Check for Unpushed Commits
+
+Determine if there are commits that haven't been pushed yet.
+
+**If on a feature branch with a remote tracking branch:**
+```bash
+git log @{upstream}..HEAD --oneline
+```
+
+**If on a feature branch with no remote tracking branch, or on the default branch:**
+```bash
+git log origin/{default_branch}..HEAD --oneline
+```
+
+If there are **no unpushed commits**, stop and tell the user:
+```
+Nothing to ship — all commits are already pushed.
+```
+
+Save the list of unpushed commit messages for use in later steps.
+
+### Step 3: Handle Branching
+
+**If already on a feature branch** (not the default branch):
+- Stay on it. No branching needed.
+- Skip to Step 4.
+
+**If on the default branch:**
+- Generate a branch name from the unpushed commit messages:
+  - Read the commit subjects
+  - Derive a kebab-case branch name with a conventional prefix: `feat/`, `fix/`, `refactor/`, `chore/`, `docs/` based on the commit content
+  - Keep it short (3-5 words max after the prefix), e.g., `feat/add-user-auth`, `fix/login-redirect-loop`
+  - Strip special characters, lowercase everything
+- Create and switch to the new branch:
+  ```bash
+  git checkout -b {branch_name}
+  ```
+- Tell the user: `Created branch {branch_name}`
+
+### Step 4: Push to Origin
+
+```bash
+git push -u origin {branch_name}
+```
+
+If the branch already has a remote tracking branch, a regular `git push` is fine.
+
+### Step 5: Check for Existing PR
+
+Before creating a new PR, check if one already exists for this branch:
+
+```bash
+gh pr view --json number,url,title,state 2>/dev/null
+```
+
+If a PR already exists and is **open**:
+- Do NOT create a new one
+- Skip to Step 7 and report the existing PR with a note that new commits were pushed.
+
+If no PR exists (or it is closed/merged), proceed to Step 6.
+
+### Step 6: Create the Pull Request
+
+Generate the PR title and body from the unpushed commits:
+
+- **Title**: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
+- **Body**: TL;DR of the changes in 2-4 bullet points max.
+
+```bash
+gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{2-4 bullet points}
+
+---
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 7: Report
+
+Display the result clearly:
+
+```
+Shipped to GitHub:
+  Branch: {branch_name}
+  PR: #{number} — {title}
+  URL: {url}
+```
+
+## Important
+
+- Do NOT run lint, type-check, or build — that is checkpoint's job
+- Do NOT commit anything — only push existing commits and create a PR
+- If the user has uncommitted changes, tell them to run /checkpoint first
+- Keep the PR body short — a TL;DR, not an essay
+- Always check for an existing open PR before creating a new one to avoid duplicates
+- Detect the default branch dynamically — do not hardcode `main` or `master`
+- When creating a branch from the default branch, use conventional prefixes (`feat/`, `fix/`, etc.) with kebab-case names
+- Never run destructive git operations (no `--force`, no `reset --hard`)
+- If `gh` is not installed or authenticated, help the user get set up before proceeding

package/template/AGENTS.md

@@ -1,87 +1,36 @@
-## Planning mode
+# CRITICAL RULES - MUST FOLLOW
 
-Never make assumptions about what the user wants. Always ask clarifying questions before proceeding.
+## RESPONSES
 
-# MANDATORY: Feature Planning & Implementation Workflow
+- Keep responses concise and to the point - unless the user asks otherwise
 
-**This workflow is non-negotiable for any non-trivial feature or multi-step change.** Do not implement multi-task features directly in a single session. Do not write a monolithic plan and start coding from it. The workflow below exists because implementation plans that live in a single file are either too large for a context window or too shallow for independent execution — both lead to poor results.
+## PLANNING MODE
 
-### The workflow has three stages. Execute them in order, every time.
+- Always ask clarifying questions
+- Never assume design, tech stack or features
+- Use deep-dive sub-agents to assist with research
+- Use deep-dive sub-agents to review the different aspects of your plan before presenting to the user
 
-**Stage 1 — Plan.** Discuss the feature with the user. Ask clarifying questions. Understand requirements, technical constraints, and acceptance criteria. This happens naturally in planning mode.
+## CHANGE / EDIT MODE
 
-**Stage 2 — Create the spec.** Once planning is complete, invoke the `create-spec` skill. This converts the planning conversation into a structured `specs/{feature}/` folder with:
-- Self-contained task files (one per task, in a `tasks/` subfolder)
-- A README with a dependency graph and parallel execution waves
-- Requirements and manual action items
+- Never implement features yourself when possible - use sub-agents!
+- Identify changes from the plan that can be implemented in parallel, and use sub-agents to implement the features efficiently
+- When using sub-agents to implement features, act as a coordinator only
+- Use the best model for the task - premium models for complex tasks (like coding) and mid-tier models for simpler tasks, like documentation
+- After completing features (large or small), always run commands like lint, type check and next build to check code quality
 
-Do not skip this step. Do not proceed to implementation without a spec folder. The spec is what enables parallel agent execution — without it, you're back to single-threaded implementation.
+## DATABASE SCHEMA CHANGES
 
-**Stage 3 — Implement via orchestration.** Once the spec folder exists and the user approves it, invoke the `implement-feature` skill. This orchestrates parallel coder agents wave-by-wave:
-- Each task is dispatched to its own coder agent
-- Tasks within a wave run in parallel
-- A code review gate runs between waves
-- Issues from review are dispatched back to coder agents
-- The cycle repeats until everything passes
+- Whenever you make changes to the database schema, ALWAYS run the drizzle generate and migrate commands
+- NEVER run drizzle push!
 
-The main agent (you) does NOT write code during Stage 3. You orchestrate. Coder subagents implement. The code-review agent verifies. You manage progress and commit completed waves.
+## TESTING
 
-### When does this workflow apply?
+- Use any testing tools, libraries available to the project for testing your changes
+- Never assume your changes simply work, always test!
+- If the project does not have any testing tools, scripts, MCP tools, skills, etc. available for testing, ask the user whether testing should be skipped.
 
-- Any feature with 2+ tasks or files to change
-- Any work that came out of a planning conversation
-- Any time the user says "implement", "build", "create this feature", or similar after discussing what to build
+## UI DESIGN
 
-### When does it NOT apply?
-
-- Single-file bug fixes or trivial changes
-- Quick config edits or one-line patches
-- Tasks the user explicitly asks to do inline ("just fix this here")
-
-If in doubt, ask the user: "This looks like it could benefit from a spec — should I create one, or would you prefer I implement it directly?"
-
----
-
-# Project Agent Instructions
-
-## Skills
-
-This repo ships agent skills under `.claude/skills` (mirrored at `.agents/skills`). **Read and follow the relevant skill** when your task matches its domain—skills encode stack conventions and patterns for this project.
-
-Use **`find-skills`** when you are unsure whether a skill exists for a task or want to discover installable skills from registries.
-
-## Pre-flight (non-trivial tasks)
-
-1. Map the work to skills using the routing table below.
-2. Open and follow matching skills before writing substantial code or making architectural decisions.
-
-If you start down the wrong path, stop, invoke the right skill, and continue from there.
-
-## Task → skill routing
-
-| If you are about to… | Invoke first |
-| --- | --- |
-| Plan a feature, create a spec, break work into tasks | `create-spec` |
-| Implement a planned feature, execute a spec | `implement-feature` |
-| Create a checkpoint commit | `checkpoint` |
-| Review a pull request | `review-pr` |
-| Touch Next.js App Router, routing, RSC, data fetching, deployment | `nextjs` |
-| Touch shadcn/ui components or registries | `shadcn` |
-| Touch Better Auth configuration or auth flows | `better-auth-best-practices` |
-| Optimize or review React / Next.js performance | `vercel-react-best-practices` |
-| Build, modify, or review an MCP server | `mcp-builder` |
-| Build or review a frontend design / UI | `frontend-design`, `web-design-guidelines` |
-| Automate browser testing (Playwright) | `playwright-cli` |
-| Create or refine project agent skills | `skill-creator` |
-| Look for a skill or extend capabilities | `find-skills` |
-
-Stack skills compose: invoking `nextjs` does not excuse skipping `shadcn` or `better-auth-best-practices` when those layers are involved.
-
-## Hard rules
-
-1. **Never touch the Next.js / shadcn / Better Auth / MCP layers without reading their corresponding skill** for this repo. They are mandatory references, not optional browsing.
-2. **Before claiming work is done, fixed, or passing**, run the project’s verification commands (see workspace rules: lint and typecheck scripts) and only assert success when the output supports it.
-
-## If no skill matches
-
-Fall back to sound engineering judgment. State explicitly: _"I checked the skills list and none applied because …"_ so the user can correct a missed skill.
+- Always follow the UI design system when creating or reviewing components or pages.
+- Design System: @DESIGN.md

package/template/DESIGN.md

@@ -0,0 +1,451 @@
+# Design System
+
+This document defines the visual design system for the project. All new components and pages **must** follow these tokens, patterns, and conventions.
+
+---
+
+## Stack
+
+- **Framework:** Next.js (App Router) + React + TypeScript
+- **Styling:** Tailwind CSS v4 (CSS-first config via `@theme inline` in `globals.css` — no `tailwind.config.ts`)
+- **Components:** shadcn/ui (new-york style, neutral base)
+- **Icons:** Lucide React
+- **Fonts:** Geist (sans) + Geist Mono (mono) via `next/font/google`
+- **Dark mode:** next-themes (class-based, system default)
+- **Utilities:** `cn()` from `@/lib/utils` (clsx + tailwind-merge)
+
+---
+
+## Colors
+
+All values use the **oklch** color space. Colors are defined as CSS custom properties in `globals.css` and bridged to Tailwind via `@theme inline`.
+
+### Semantic Tokens
+
+| Token | Light | Dark | Usage |
+|---|---|---|---|
+| `background` | `oklch(1 0 0)` | `oklch(0.141 0.005 285.823)` | Page background |
+| `foreground` | `oklch(0.141 0.005 285.823)` | `oklch(0.985 0 0)` | Primary text |
+| `primary` | `oklch(0.21 0.034 270)` | `oklch(0.92 0.02 270)` | Buttons, links, accents |
+| `primary-foreground` | `oklch(0.985 0 0)` | `oklch(0.21 0.006 285.885)` | Text on primary |
+| `secondary` | `oklch(0.967 0.001 286.375)` | `oklch(0.274 0.006 286.033)` | Secondary buttons, subtle bg |
+| `secondary-foreground` | `oklch(0.21 0.006 285.885)` | `oklch(0.985 0 0)` | Text on secondary |
+| `muted` | `oklch(0.967 0.001 286.375)` | `oklch(0.274 0.006 286.033)` | Subdued backgrounds |
+| `muted-foreground` | `oklch(0.552 0.016 285.938)` | `oklch(0.705 0.015 286.067)` | Subdued text, placeholders |
+| `accent` | `oklch(0.96 0.012 270)` | `oklch(0.28 0.018 270)` | Hover backgrounds, highlights |
+| `accent-foreground` | `oklch(0.21 0.006 285.885)` | `oklch(0.985 0 0)` | Text on accent |
+| `destructive` | `oklch(0.577 0.245 27.325)` | `oklch(0.704 0.191 22.216)` | Error states, delete actions |
+| `card` | `oklch(1 0 0)` | `oklch(0.21 0.006 285.885)` | Card backgrounds |
+| `card-foreground` | `oklch(0.141 0.005 285.823)` | `oklch(0.985 0 0)` | Card text |
+| `popover` | `oklch(1 0 0)` | `oklch(0.21 0.006 285.885)` | Popover/dropdown bg |
+| `popover-foreground` | `oklch(0.141 0.005 285.823)` | `oklch(0.985 0 0)` | Popover/dropdown text |
+| `border` | `oklch(0.92 0.004 286.32)` | `oklch(1 0 0 / 10%)` | Borders, dividers |
+| `input` | `oklch(0.92 0.004 286.32)` | `oklch(1 0 0 / 15%)` | Input borders |
+| `ring` | `oklch(0.705 0.06 270)` | `oklch(0.552 0.05 270)` | Focus rings |
+
+### Chart Colors
+
+| Token | Light | Dark |
+|---|---|---|
+| `chart-1` | `oklch(0.646 0.222 41.116)` | `oklch(0.488 0.243 264.376)` |
+| `chart-2` | `oklch(0.6 0.118 184.704)` | `oklch(0.696 0.17 162.48)` |
+| `chart-3` | `oklch(0.398 0.07 227.392)` | `oklch(0.769 0.188 70.08)` |
+| `chart-4` | `oklch(0.828 0.189 84.429)` | `oklch(0.627 0.265 303.9)` |
+| `chart-5` | `oklch(0.769 0.188 70.08)` | `oklch(0.645 0.246 16.439)` |
+
+### Sidebar Colors
+
+| Token | Light | Dark |
+|---|---|---|
+| `sidebar` | `oklch(0.985 0 0)` | `oklch(0.21 0.006 285.885)` |
+| `sidebar-foreground` | `oklch(0.141 0.005 285.823)` | `oklch(0.985 0 0)` |
+| `sidebar-primary` | `oklch(0.21 0.006 285.885)` | `oklch(0.488 0.243 264.376)` |
+| `sidebar-primary-foreground` | `oklch(0.985 0 0)` | `oklch(0.985 0 0)` |
+| `sidebar-accent` | `oklch(0.967 0.001 286.375)` | `oklch(0.274 0.006 286.033)` |
+| `sidebar-accent-foreground` | `oklch(0.21 0.006 285.885)` | `oklch(0.985 0 0)` |
+| `sidebar-border` | `oklch(0.92 0.004 286.32)` | `oklch(1 0 0 / 10%)` |
+| `sidebar-ring` | `oklch(0.705 0.015 286.067)` | `oklch(0.552 0.016 285.938)` |
+
+### Ad-hoc Status Colors
+
+Use these Tailwind utilities for status indicators — they are not part of the token system but are used consistently:
+
+- **Success:** `text-green-600` / `dark:text-green-400`, `bg-green-500`
+- **Error:** `text-red-600`, `text-destructive`
+
+---
+
+## Typography
+
+### Font Families
+
+| Token | Font | Usage |
+|---|---|---|
+| `--font-geist-sans` | Geist | All UI text (applied to body) |
+| `--font-geist-mono` | Geist Mono | Code, monospace content |
+
+Body has `font-feature-settings: "rlig" 1, "calt" 1` and `antialiased` enabled.
+
+### Type Scale
+
+| Class | Size | Usage |
+|---|---|---|
+| `text-xs` | 12px | Timestamps, shortcuts, helper text, code |
+| `text-sm` | 14px | Descriptions, labels, body copy, card descriptions |
+| `text-base` | 16px | Base text, inputs (mobile) |
+| `text-lg` | 18px | Dialog titles, sub-headings |
+| `text-xl` | 20px | Section titles, header logo |
+| `text-2xl` | 24px | Page titles, card titles |
+| `text-3xl` | 30px | Dashboard/profile headings |
+| `text-4xl` | 36px | Large display text |
+| `text-5xl` | 48px | Hero title |
+
+### Font Weights
+
+| Class | Weight | Usage |
+|---|---|---|
+| `font-medium` | 500 | Buttons, labels, nav items |
+| `font-semibold` | 600 | Card titles, section headings, badges, dialog titles |
+| `font-bold` | 700 | Page titles, hero heading |
+
+### Line Heights & Tracking
+
+| Class | Usage |
+|---|---|
+| `leading-none` | Labels, card titles |
+| `leading-5` | Code blocks |
+| `leading-6` | List items |
+| `leading-7` | Paragraphs (markdown) |
+| `tracking-tight` | Hero/display text |
+| `tracking-widest` | Keyboard shortcuts |
+
+---
+
+## Spacing
+
+### Container Pattern
+
+```
+container mx-auto px-4
+```
+
+Responsive overrides where needed:
+- Header: `px-3 sm:px-4`
+- Footer: `px-4 sm:px-6 lg:px-8`
+
+### Max Widths
+
+| Class | Value | Usage |
+|---|---|---|
+| `max-w-sm` | 24rem | Auth forms |
+| `max-w-md` | 28rem | Login/register cards, error pages |
+| `max-w-lg` | 32rem | Dialog content (sm+) |
+| `max-w-2xl` | 42rem | Large dialogs |
+| `max-w-3xl` | 48rem | Embeds, protected state |
+| `max-w-4xl` | 56rem | Main content pages |
+
+### Vertical Spacing (space-y)
+
+| Class | Usage |
+|---|---|
+| `space-y-1` | Tight lists, inline stacks |
+| `space-y-1.5` | Card header |
+| `space-y-2` | Form field groups, small stacks |
+| `space-y-3` | Footer stacks |
+| `space-y-4` | Form sections, dialog content |
+| `space-y-6` | Card content sections |
+| `space-y-8` | Page-level sections |
+
+### Padding
+
+| Class | Usage |
+|---|---|
+| `p-1` | Dropdown content, icon buttons |
+| `p-2` | Code blocks, muted backgrounds |
+| `p-3` | Chat bubbles, inputs |
+| `p-4` | Grid items, action buttons, list items |
+| `p-6` | Cards, dialog content |
+
+### Page Vertical Padding
+
+| Class | Usage |
+|---|---|
+| `py-3 sm:py-4` | Header |
+| `py-4 sm:py-6` | Footer |
+| `py-8` | Standard content pages |
+| `py-12` | Home page, dashboard |
+| `py-16` | Error/not-found pages |
+
+---
+
+## Border Radius
+
+| Token | Value | Class |
+|---|---|---|
+| `--radius` | `0.625rem` (10px) | Base |
+| `--radius-sm` | `calc(--radius - 4px)` = 6px | `rounded-sm` |
+| `--radius-md` | `calc(--radius - 2px)` = 8px | `rounded-md` |
+| `--radius-lg` | `var(--radius)` = 10px | `rounded-lg` |
+| `--radius-xl` | `calc(--radius + 4px)` = 14px | `rounded-xl` |
+| — | 9999px | `rounded-full` |
+
+**Usage:**
+- `rounded-md` — Buttons, inputs, textarea, code blocks, dropdowns
+- `rounded-lg` — Cards, dialogs, feature cards, chat bubbles
+- `rounded-xl` — Hero logo container
+- `rounded-full` — Badges, avatars
+
+---
+
+## Shadows
+
+| Class | Usage |
+|---|---|
+| `shadow-xs` | Inputs, textarea, secondary/outline buttons |
+| `shadow-sm` | Card base |
+| `shadow-md` | Card hover, dropdown content |
+| `shadow-lg` | Dialogs, dropdown sub-content |
+
+No custom shadow definitions — all Tailwind defaults.
+
+---
+
+## Animations
+
+### Custom Keyframes
+
+| Name | Effect | Duration | Easing |
+|---|---|---|---|
+| `fade-in` | Opacity 0 → 1 | 0.3s | ease-out |
+| `fade-up` | Opacity 0 → 1 + translateY(8px → 0) | 0.4s | ease-out |
+| `scale-in` | Opacity 0 → 1 + scale(0.97 → 1) | 0.2s | ease-out |
+
+Use via: `animate-fade-in`, `animate-fade-up`, `animate-scale-in`
+
+### tw-animate-css Animations
+
+Used on dialogs and dropdowns:
+- `animate-in` / `animate-out`
+- `fade-in-0` / `fade-out-0`
+- `zoom-in-95` / `zoom-out-95`
+- `slide-in-from-{top|bottom|left|right}-2`
+
+### Transition Classes
+
+| Class | Usage |
+|---|---|
+| `transition-colors` | Links, hover color changes |
+| `transition-opacity` | Avatar hover, reveal-on-hover |
+| `transition-all duration-200` | Card interactive hover, buttons |
+| `transition-[color,box-shadow]` | Input/textarea focus |
+
+### Utility Classes
+
+```css
+.card-interactive {
+  @apply transition-all duration-200 ease-out;
+}
+.card-interactive:hover {
+  @apply shadow-md -translate-y-0.5;
+}
+```
+
+```css
+.auth-bg {
+  background-image: radial-gradient(
+    circle at 50% 0%,
+    var(--accent) 0%,
+    transparent 50%
+  );
+}
+```
+
+---
+
+## Layout
+
+### Root Structure
+
+```
+<body class="antialiased min-h-screen flex flex-col">
+  <SiteHeader />
+  <main id="main-content" class="flex-1">{children}</main>
+  <SiteFooter />
+  <Toaster />
+</body>
+```
+
+### Page Layout Patterns
+
+**Auth pages:**
+```
+flex min-h-[calc(100vh-4rem)] items-center justify-center p-4
+  → Card w-full max-w-md
+```
+
+**Standard content pages:**
+```
+container mx-auto px-4 py-8
+  → max-w-4xl mx-auto
+```
+
+**Error/not-found pages:**
+```
+container mx-auto px-4 py-16
+  → max-w-md mx-auto text-center
+```
+
+### Grid Patterns
+
+| Pattern | Usage |
+|---|---|
+| `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6` | Feature cards (4-col) |
+| `grid grid-cols-1 md:grid-cols-2 gap-6` | Dashboard cards |
+| `grid grid-cols-1 md:grid-cols-2 gap-4` | Profile info |
+| `grid grid-cols-1 md:grid-cols-3 gap-4` | Quick actions |
+
+### Responsive Breakpoints
+
+Standard Tailwind breakpoints:
+- `sm:` (640px) — Padding adjustments, text alignment, button sizing
+- `md:` (768px) — Grid column changes (→ 2 col), input font size
+- `lg:` (1024px) — Grid column changes (→ 4 col), wide padding
+
+---
+
+## Icons
+
+**Library:** Lucide React
+
+### Sizing Convention
+
+| Size | Classes | Usage |
+|---|---|---|
+| XS | `h-3 w-3` | Inline badge icons |
+| SM | `h-3.5 w-3.5` | Copy buttons |
+| Default | `h-4 w-4` or `size-4` | Standard UI icons |
+| MD | `h-5 w-5` | Header logo icon |
+| LG | `h-7 w-7` | Hero logo icon |
+| XL | `h-16 w-16` | Error/empty state illustrations |
+
+### Commonly Used Icons
+
+`Bot`, `User`, `Lock`, `Shield`, `Mail`, `Calendar`, `Copy`, `Check`, `Loader2`, `LogOut`, `Sun`, `Moon`, `Github`, `ArrowLeft`, `RefreshCw`, `AlertCircle`, `FileQuestion`, `Database`, `Palette`, `Video`
+
+---
+
+## Components (shadcn/ui)
+
+All components live in `src/components/ui/`. They use `data-slot` attributes, accept `className` for overrides via `cn()`, and follow either `React.forwardRef` or functional component patterns.
+
+### Button
+
+6 variants, 4 sizes (CVA-based):
+
+| Variant | Usage |
+|---|---|
+| `default` | Primary actions |
+| `secondary` | Secondary actions |
+| `outline` | Tertiary actions |
+| `ghost` | Subtle/icon actions |
+| `destructive` | Delete/danger actions |
+| `link` | Inline text links |
+
+| Size | Height | Padding |
+|---|---|---|
+| `sm` | h-8 | px-3 |
+| `default` | h-9 | px-4 |
+| `lg` | h-10 | px-6 |
+| `icon` | size-9 | — |
+
+### Card
+
+6 sub-components: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
+
+Base: `rounded-lg border bg-card text-card-foreground shadow-sm`
+
+### Input / Textarea
+
+- Height: `h-9` (input), `min-h-16` (textarea)
+- Border: `border bg-transparent rounded-md shadow-xs`
+- Focus: `focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]`
+- Validation: `aria-invalid:border-destructive aria-invalid:ring-destructive/20`
+- Responsive font: `text-base md:text-sm`
+
+### Badge
+
+4 variants: `default`, `secondary`, `destructive`, `outline`
+
+Base: `rounded-full border px-2.5 py-0.5 text-xs font-semibold`
+
+### Dialog
+
+Radix-based with overlay (`bg-black/50`), fade + zoom animations, optional close button.
+
+### DropdownMenu
+
+Radix-based. Content: `rounded-md border p-1 shadow-md min-w-[8rem]`. Items support a `destructive` variant.
+
+### Spinner
+
+Sizes: `sm` (h-4 w-4), `md` (h-6 w-6), `lg` (h-8 w-8). Uses `Loader2` with `animate-spin`.
+
+### Toast (Sonner)
+
+Custom icons per state (success, info, warning, error, loading). Themed via CSS variable overrides.
+
+---
+
+## Focus & Interaction States
+
+### Focus Ring (Global)
+
+```css
+outline-2 outline-offset-2 outline-ring/70
+```
+
+Component-level override:
+```
+focus-visible:ring-ring/50 focus-visible:ring-[3px]
+```
+
+### Disabled
+
+```
+disabled:pointer-events-none disabled:opacity-50
+```
+
+### Interactive Card Hover
+
+```
+transition-all duration-200 ease-out
+hover:shadow-md hover:-translate-y-0.5
+```
+
+---
+
+## Dark Mode
+
+- **Method:** Class-based via `next-themes` with `attribute="class"` and `disableTransitionOnChange`
+- **Default:** System preference
+- **Toggle:** 3-way dropdown — Light / Dark / System
+- All semantic color tokens swap automatically via `.dark` CSS selector
+- Use `dark:` prefix for component-specific overrides (e.g., `dark:bg-input/30`)
+
+---
+
+## Branding
+
+### Logo Text
+
+```
+bg-gradient-to-r from-primary to-primary/70 bg-clip-text text-transparent
+```
+
+### Logo Icon Container
+
+```
+w-8 h-8 rounded-lg bg-primary/10 flex items-center justify-center
+```
+
+Hero variant: `w-12 h-12 rounded-xl`