create-xani-agentic-app 1.0.0

package/template/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/template/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/template/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/template/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/template/scripts/setup.ts

@@ -0,0 +1,277 @@
+#!/usr/bin/env npx tsx
+/**
+ * Interactive setup wizard for the Xani Agentic Starter Kit.
+ * Run with: npx tsx scripts/setup.ts
+ */
+
+import { existsSync, copyFileSync, readFileSync } from "fs";
+import { createInterface } from "readline";
+import { execSync } from "child_process";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT_DIR = join(__dirname, "..");
+const ENV_EXAMPLE = join(ROOT_DIR, "env.example");
+const ENV_FILE = join(ROOT_DIR, ".env");
+
+// ANSI colors
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+function log(message: string, color?: keyof typeof colors) {
+  const colorCode = color ? colors[color] : "";
+  console.log(`${colorCode}${message}${colors.reset}`);
+}
+
+function header(message: string) {
+  console.log();
+  log(`${"=".repeat(60)}`, "cyan");
+  log(`  ${message}`, "bright");
+  log(`${"=".repeat(60)}`, "cyan");
+  console.log();
+}
+
+function success(message: string) {
+  log(`✓ ${message}`, "green");
+}
+
+function warn(message: string) {
+  log(`⚠ ${message}`, "yellow");
+}
+
+function error(message: string) {
+  log(`✗ ${message}`, "red");
+}
+
+function info(message: string) {
+  log(`  ${message}`, "dim");
+}
+
+async function prompt(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${colors.cyan}? ${colors.reset}${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function confirm(question: string): Promise<boolean> {
+  const answer = await prompt(`${question} (y/n)`);
+  return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+}
+
+function checkNodeVersion(): boolean {
+  const requiredMajor = 20;
+  const currentVersion = process.version;
+  const currentMajor = parseInt(currentVersion.slice(1).split(".")[0] || "0", 10);
+
+  if (currentMajor >= requiredMajor) {
+    success(`Node.js ${currentVersion} detected (requires v${requiredMajor}+)`);
+    return true;
+  } else {
+    error(`Node.js ${currentVersion} detected, but v${requiredMajor}+ is required`);
+    info("Please upgrade Node.js: https://nodejs.org/");
+    return false;
+  }
+}
+
+function copyEnvFile(): boolean {
+  if (existsSync(ENV_FILE)) {
+    warn(".env file already exists");
+    return true;
+  }
+
+  if (!existsSync(ENV_EXAMPLE)) {
+    error("env.example file not found");
+    return false;
+  }
+
+  try {
+    copyFileSync(ENV_EXAMPLE, ENV_FILE);
+    success("Created .env file from env.example");
+    return true;
+  } catch (err) {
+    error(`Failed to create .env file: ${err}`);
+    return false;
+  }
+}
+
+interface EnvStatus {
+  configured: string[];
+  missing: string[];
+  optional: string[];
+}
+
+function checkEnvVariables(): EnvStatus {
+  const required = ["POSTGRES_URL", "BETTER_AUTH_SECRET"];
+  const optional = [
+    "GOOGLE_CLIENT_ID",
+    "GOOGLE_CLIENT_SECRET",
+    "OPENROUTER_API_KEY",
+    "OPENROUTER_MODEL",
+    "BLOB_READ_WRITE_TOKEN",
+    "NEXT_PUBLIC_APP_URL",
+  ];
+
+  const status: EnvStatus = {
+    configured: [],
+    missing: [],
+    optional: [],
+  };
+
+  // Read .env file if it exists
+  let envContent = "";
+  if (existsSync(ENV_FILE)) {
+    envContent = readFileSync(ENV_FILE, "utf-8");
+  }
+
+  // Parse env file (simple key=value parsing)
+  const envVars: Record<string, string> = {};
+  envContent.split("\n").forEach((line) => {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith("#")) {
+      const [key, ...valueParts] = trimmed.split("=");
+      if (key) {
+        envVars[key] = valueParts.join("=");
+      }
+    }
+  });
+
+  // Check required variables
+  for (const key of required) {
+    const value = envVars[key];
+    if (value && value.length > 0 && !value.startsWith("your-")) {
+      status.configured.push(key);
+    } else {
+      status.missing.push(key);
+    }
+  }
+
+  // Check optional variables
+  for (const key of optional) {
+    const value = envVars[key];
+    if (value && value.length > 0 && !value.startsWith("your-")) {
+      status.configured.push(key);
+    } else {
+      status.optional.push(key);
+    }
+  }
+
+  return status;
+}
+
+async function runDatabaseMigration(): Promise<boolean> {
+  log("\nRunning database migration...", "cyan");
+
+  try {
+    execSync("pnpm db:migrate", {
+      cwd: ROOT_DIR,
+      stdio: "inherit",
+    });
+    success("Database migration completed");
+    return true;
+  } catch {
+    error("Database migration failed");
+    info("Make sure your database is running and POSTGRES_URL is correct");
+    return false;
+  }
+}
+
+function printNextSteps(envStatus: EnvStatus) {
+  header("Next Steps");
+
+  const steps: string[] = [];
+
+  if (envStatus.missing.length > 0) {
+    steps.push(`Configure required env vars in .env: ${envStatus.missing.join(", ")}`);
+  }
+
+  if (envStatus.optional.includes("GOOGLE_CLIENT_ID")) {
+    steps.push("Set up Google OAuth at https://console.cloud.google.com/");
+  }
+
+  if (envStatus.optional.includes("OPENROUTER_API_KEY")) {
+    steps.push("Get an OpenRouter API key at https://openrouter.ai/settings/keys");
+  }
+
+  steps.push("Start the development server: pnpm dev");
+  steps.push("Open http://localhost:3000 in your browser");
+
+  steps.forEach((step, index) => {
+    log(`${index + 1}. ${step}`);
+  });
+
+  console.log();
+  log("Documentation:", "bright");
+  info("- README.md - Project overview and setup");
+  info("- CLAUDE.md - AI assistant guidelines");
+  info("- docs/ - Technical documentation");
+  console.log();
+}
+
+async function main() {
+  header("Xani Agentic Starter Kit - Setup Wizard");
+
+  // Step 1: Check Node version
+  log("Checking Node.js version...", "cyan");
+  if (!checkNodeVersion()) {
+    process.exit(1);
+  }
+
+  // Step 2: Create .env file
+  console.log();
+  log("Setting up environment...", "cyan");
+  copyEnvFile();
+
+  // Step 3: Check environment variables
+  console.log();
+  log("Checking environment variables...", "cyan");
+  const envStatus = checkEnvVariables();
+
+  if (envStatus.configured.length > 0) {
+    success(`Configured: ${envStatus.configured.join(", ")}`);
+  }
+  if (envStatus.missing.length > 0) {
+    warn(`Missing (required): ${envStatus.missing.join(", ")}`);
+  }
+  if (envStatus.optional.length > 0) {
+    info(`Optional (not set): ${envStatus.optional.join(", ")}`);
+  }
+
+  // Step 4: Offer to run database migration
+  if (envStatus.missing.length === 0) {
+    console.log();
+    const shouldMigrate = await confirm("Would you like to run database migrations now?");
+    if (shouldMigrate) {
+      await runDatabaseMigration();
+    }
+  } else {
+    console.log();
+    warn("Skipping database migration - please configure required env vars first");
+  }
+
+  // Step 5: Print next steps
+  printNextSteps(envStatus);
+
+  log("Setup complete!", "green");
+}
+
+main().catch((err) => {
+  error(`Setup failed: ${err}`);
+  process.exit(1);
+});

package/template/skills-lock.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "skills": {
+    "ai-sdk": {
+      "source": "vercel/ai",
+      "sourceType": "github",
+      "skillPath": "skills/use-ai-sdk/SKILL.md",
+      "computedHash": "2249889eb47ef0f61c4dba4cf2afe01c1c8dd793bb4c24230347c1ab909bb7dd"
+    },
+    "better-auth-best-practices": {
+      "source": "better-auth/skills",
+      "sourceType": "github",
+      "computedHash": "9ab075b5061be2a5f299c10505667345cc1ec76e8de4120901cfd586643e776f"
+    },
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "computedHash": "9e1c8b3103f92fa8092568a44fe64858de7c5c9dc65ce4bea8f168080e889cfd"
+    },
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "516bd2154eb843a8240e43d5b285229129853114ad7075a5e141e1c08e408c84"
+    },
+    "mcp-builder": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "f08cbdec74dba480ec5217363446dae154b7576b8c3d9b4cb17aff234f15973b"
+    },
+    "nextjs": {
+      "source": "vercel-labs/vercel-plugin",
+      "sourceType": "github",
+      "computedHash": "044a0bc722b018b636c9bd23f3dd4e4410fd8b0815d79b1fa1ba3fa7dc5f4d88"
+    },
+    "playwright-cli": {
+      "source": "microsoft/playwright-cli",
+      "sourceType": "github",
+      "computedHash": "675811a7e7f958e6544f9c6bc53993c85fe39e72c5820a60d9d46bd169eddc32"
+    },
+    "shadcn": {
+      "source": "shadcn/ui",
+      "sourceType": "github",
+      "computedHash": "642a177bee320618caa49f5106cadb4e7594c606e867f61ba7b56d19cf745cd5"
+    },
+    "skill-creator": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "57f470f512f45bdac598e302bc72fd62bf2b649fc7fad032efe97720149cde4d"
+    },
+    "vercel-react-best-practices": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "257b84bf218a7d3b2cba56e929b7e933cf71cb89f2e24ab601759c599d1c23f2"
+    },
+    "web-design-guidelines": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "f3bc47f890f42a44db1007ab390709ec368e4b8c089baee6b0007182236ac474"
+    }
+  }
+}

package/template/specs/ui-polish-responsive/README.md

@@ -0,0 +1,59 @@
+# UI Polish & Responsive Improvements
+
+## Overview
+
+Improve the visual quality, component consistency, and responsive behavior of the boilerplate UI across all pages. This includes refreshing the color palette with a subtle blue accent, replacing bare HTML elements with shadcn components, adding hover/transition effects via a reusable utility class, and introducing `sm:` breakpoints throughout for better tablet/mobile scaling. All custom styling goes in globals.css — no inline or custom CSS on components.
+
+## Quick Links
+
+- [Requirements](./requirements.md) — full requirements and acceptance criteria
+- [Action Required](./action-required.md) — manual steps needing human action
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    task-01-globals-css["01: globals.css Foundation"]
+    task-02-layout["02: Layout Sticky Footer"]
+    task-03-site-header["03: Site Header Responsive"]
+    task-04-site-footer["04: Site Footer Responsive"]
+    task-05-home-page["05: Home Page Overhaul"]
+    task-06-dashboard["06: Dashboard Page"]
+    task-07-chat-page["07: Chat Page"]
+    task-08-profile-page["08: Profile Page"]
+    task-09-auth-pages["09: Auth Pages"]
+    task-10-setup-checklist["10: Setup Checklist"]
+    task-11-starter-prompt-modal["11: Starter Prompt Modal"]
+    task-01-globals-css --> task-05-home-page
+    task-01-globals-css --> task-06-dashboard
+    task-01-globals-css --> task-07-chat-page
+    task-01-globals-css --> task-08-profile-page
+    task-01-globals-css --> task-09-auth-pages
+    task-01-globals-css --> task-10-setup-checklist
+    task-01-globals-css --> task-11-starter-prompt-modal
+    task-02-layout --> task-09-auth-pages
+```
+
+## Waves
+
+| Wave | Tasks | Description |
+|------|-------|-------------|
+| 1 | task-01, task-02, task-03, task-04 | Foundation: globals.css enhancements, layout flex structure, header/footer responsive |
+| 2 | task-05, task-06, task-07, task-08, task-09, task-10, task-11 | All pages: Card adoption, responsive breakpoints, component swaps |
+
+## Task Status
+
+### Wave 1
+- [x] [task-01-globals-css](./tasks/task-01-globals-css.md) — globals.css color palette, animations, and utility classes
+- [x] [task-02-layout](./tasks/task-02-layout.md) — Root layout sticky footer with flex column
+- [x] [task-03-site-header](./tasks/task-03-site-header.md) — Header responsive padding and sizing
+- [x] [task-04-site-footer](./tasks/task-04-site-footer.md) — Footer responsive padding
+
+### Wave 2
+- [ ] [task-05-home-page](./tasks/task-05-home-page.md) — Home page Card adoption + responsive typography
+- [ ] [task-06-dashboard](./tasks/task-06-dashboard.md) — Dashboard Card adoption + responsive grid
+- [ ] [task-07-chat-page](./tasks/task-07-chat-page.md) — Chat Input swap + sticky form + responsive
+- [ ] [task-08-profile-page](./tasks/task-08-profile-page.md) — Profile responsive stacking + grid fixes
+- [ ] [task-09-auth-pages](./tasks/task-09-auth-pages.md) — Auth pages animation, shadow, and background
+- [ ] [task-10-setup-checklist](./tasks/task-10-setup-checklist.md) — Setup checklist Card adoption
+- [ ] [task-11-starter-prompt-modal](./tasks/task-11-starter-prompt-modal.md) — Textarea swap + responsive buttons

package/template/specs/ui-polish-responsive/action-required.md

@@ -0,0 +1,3 @@
+# Action Required: UI Polish & Responsive Improvements
+
+No manual steps required for this feature. All tasks can be implemented automatically.

package/template/specs/ui-polish-responsive/requirements.md

@@ -0,0 +1,53 @@
+# Requirements: UI Polish & Responsive Improvements
+
+## Summary
+
+The boilerplate UI is functional but visually flat — bare `<div>` elements instead of shadcn Cards, a monotone neutral-gray palette, no hover/transition effects, and minimal responsive breakpoints (most pages only use `md:`). The goal is to meaningfully improve visual quality, component consistency, and responsive behavior across all pages and components.
+
+All changes must use Tailwind utilities and shadcn standards. Custom styling (animations, utilities, color tokens) goes in `globals.css`. No custom inline styles or CSS-in-JS on individual components. The result should look like a polished, high-quality default that can be customized by users of the boilerplate.
+
+## Goals
+
+- Refresh the color palette with a subtle cool blue accent (shift primary/ring/accent from flat gray to hue 270)
+- Replace all bare `<div>` cards with shadcn Card components for consistency
+- Replace native `<input>`, `<button>`, and `<textarea>` elements with their shadcn equivalents
+- Add hover/transition effects to interactive cards via a reusable `card-interactive` utility
+- Introduce `sm:` breakpoints throughout for proper tablet/mobile scaling
+- Add entrance animations to auth pages
+- Fix the sticky footer layout so it works on short-content pages
+- Ensure all pages scale well from 320px to 1536px+ viewports
+
+## Non-Goals
+
+- No hamburger/mobile menu for the header — the current content (avatar + theme toggle) is minimal enough
+- No new shadcn component installations — all needed components are already installed
+- No changes to business logic, API routes, or authentication flows
+- No new pages or routes
+- No changes to the Geist font choice
+- No Storybook or component documentation
+
+## Acceptance Criteria
+
+- [ ] All pages render correctly in both light and dark modes
+- [ ] No horizontal scroll on any page at 320px viewport width
+- [ ] Feature cards, dashboard cards, and next steps cards use shadcn Card components
+- [ ] Chat input uses shadcn Input, not a native `<input>`
+- [ ] Footer sticks to the bottom on short-content pages (auth pages)
+- [ ] Primary color has a visible cool-blue tint (not flat gray)
+- [ ] Cards have hover lift effect with shadow transition
+- [ ] All grids have `sm:` breakpoints for tablet-size viewports
+- [ ] `pnpm lint` and `pnpm typecheck` pass with no errors
+
+## Assumptions
+
+- Tailwind CSS v4 is in use (confirmed: `@import "tailwindcss"` syntax, `@theme inline` block)
+- `tw-animate-css` is installed in dependencies but currently unused (confirmed in package.json)
+- The ThemeProvider from next-themes renders children directly without a wrapping `<div>` (confirmed by reading the component)
+- All shadcn components needed (Card, Input, Button, Textarea, Badge, Avatar, Dialog) are already installed
+
+## Technical Constraints
+
+- All custom CSS (animations, utilities, color tokens) must go in `src/app/globals.css`
+- Component files should only use Tailwind utility classes and shadcn components — no `style={{}}` props
+- Must maintain both light and dark mode support via the existing OKLch CSS variable system
+- Must not break existing functionality (auth flows, chat, diagnostics)

package/template/specs/ui-polish-responsive/tasks/task-01-globals-css.md

@@ -0,0 +1,144 @@
+# Task 01: globals.css Foundation
+
+## Status
+
+complete
+
+## Wave
+
+1
+
+## Description
+
+Update `globals.css` to establish the visual foundation for the entire UI improvement. This includes importing the unused `tw-animate-css` package, refreshing the color palette with a subtle blue accent, adding custom keyframe animations, expanding the base layer with better defaults, and defining reusable utility classes. All subsequent tasks depend on the utilities and color tokens defined here.
+
+## Dependencies
+
+**Depends on:** None (Wave 1)
+**Blocks:** task-05-home-page.md, task-06-dashboard.md, task-07-chat-page.md, task-08-profile-page.md, task-09-auth-pages.md, task-10-setup-checklist.md, task-11-starter-prompt-modal.md
+
+**Context from dependencies:** N/A — this is the foundation task.
+
+## Files to Modify
+
+- `src/app/globals.css` — Add tw-animate-css import, update color tokens, add animations, expand base layer, add utility classes
+
+## Technical Details
+
+### Implementation Steps
+
+1. **Add tw-animate-css import** — The package `tw-animate-css@1.4.0` is already installed (in package.json) but never imported. Add the import right after the tailwindcss import:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+```
+
+2. **Add animation tokens to `@theme inline`** — Add these at the end of the existing `@theme inline` block (after the `--radius-xl` line):
+
+```css
+--animate-fade-in: fade-in 0.3s ease-out;
+--animate-fade-up: fade-up 0.4s ease-out;
+--animate-scale-in: scale-in 0.2s ease-out;
+```
+
+3. **Update light mode color tokens in `:root`** — Change these 3 values (leave all other tokens unchanged):
+
+```css
+/* CHANGE these 3 lines: */
+--primary: oklch(0.21 0.034 270);          /* was oklch(0.21 0.006 285.885) */
+--ring: oklch(0.705 0.06 270);              /* was oklch(0.705 0.015 286.067) */
+--accent: oklch(0.96 0.012 270);            /* was oklch(0.967 0.001 286.375) */
+```
+
+4. **Update dark mode color tokens in `.dark`** — Change these 3 values (leave all other tokens unchanged):
+
+```css
+/* CHANGE these 3 lines: */
+--primary: oklch(0.92 0.02 270);            /* was oklch(0.92 0.004 286.32) */
+--ring: oklch(0.552 0.05 270);              /* was oklch(0.552 0.016 285.938) */
+--accent: oklch(0.28 0.018 270);            /* was oklch(0.274 0.006 286.033) */
+```
+
+5. **Add keyframe definitions** — Add these right before the `@layer base` block:
+
+```css
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes scale-in {
+  from { opacity: 0; transform: scale(0.97); }
+  to { opacity: 1; transform: scale(1); }
+}
+```
+
+6. **Expand the `@layer base` block** — Replace the existing `@layer base` block with:
+
+```css
+@layer base {
+  * {
+    @apply border-border;
+  }
+  html {
+    scroll-behavior: smooth;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
+  :focus-visible {
+    @apply outline-2 outline-offset-2 outline-ring;
+  }
+}
+```
+
+7. **Add utility classes** — Add a new `@layer utilities` block after the `@layer base` block:
+
+```css
+@layer utilities {
+  .card-interactive {
+    @apply transition-all duration-200 ease-out;
+  }
+  .card-interactive:hover {
+    @apply shadow-md -translate-y-0.5;
+  }
+  .auth-bg {
+    background-image: radial-gradient(
+      circle at 50% 0%,
+      var(--accent) 0%,
+      transparent 50%
+    );
+  }
+}
+```
+
+### Final file structure (order of sections)
+
+1. `@import "tailwindcss";`
+2. `@import "tw-animate-css";`
+3. `@theme inline { ... }` (with animation tokens added at end)
+4. `:root { ... }` (with 3 updated color values)
+5. `.dark { ... }` (with 3 updated color values)
+6. `@keyframes` definitions (3 keyframes)
+7. `@layer base { ... }` (expanded)
+8. `@layer utilities { ... }` (new)
+
+## Acceptance Criteria
+
+- [ ] `tw-animate-css` is imported and animation utilities like `animate-fade-up` are available
+- [ ] `:root` has `--primary: oklch(0.21 0.034 270)`, `--ring: oklch(0.705 0.06 270)`, `--accent: oklch(0.96 0.012 270)`
+- [ ] `.dark` has `--primary: oklch(0.92 0.02 270)`, `--ring: oklch(0.552 0.05 270)`, `--accent: oklch(0.28 0.018 270)`
+- [ ] Three keyframe animations (`fade-in`, `fade-up`, `scale-in`) are defined
+- [ ] `@theme inline` includes `--animate-fade-in`, `--animate-fade-up`, `--animate-scale-in`
+- [ ] `.card-interactive` utility class is defined with hover shadow and translate
+- [ ] `.auth-bg` utility class is defined with radial gradient
+- [ ] `html` has `scroll-behavior: smooth`
+- [ ] `:focus-visible` has global outline styling
+- [ ] All other existing color tokens remain unchanged

package/template/specs/ui-polish-responsive/tasks/task-02-layout.md

@@ -0,0 +1,66 @@
+# Task 02: Layout Sticky Footer
+
+## Status
+
+complete
+
+## Wave
+
+1
+
+## Description
+
+Update the root layout to use a flex column structure that pushes the footer to the bottom of the viewport on short-content pages. Currently, pages like login/register have minimal content and the footer floats up, leaving blank space below. Adding `min-h-screen flex flex-col` to the body and `flex-1` to the main element creates a proper sticky footer layout.
+
+## Dependencies
+
+**Depends on:** None (Wave 1)
+**Blocks:** task-09-auth-pages.md (auth pages rely on the flex-1 main for proper vertical centering)
+
+**Context from dependencies:** N/A — this is a foundation task.
+
+## Files to Modify
+
+- `src/app/layout.tsx` — Add flex classes to body and main elements
+
+## Technical Details
+
+### Implementation Steps
+
+1. **Add flex layout classes to the `<body>` element** (line 92). The current className is:
+
+```tsx
+className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+```
+
+Change it to:
+
+```tsx
+className={`${geistSans.variable} ${geistMono.variable} antialiased min-h-screen flex flex-col`}
+```
+
+2. **Add `flex-1` to the `<main>` element** (line 101). The current element is:
+
+```tsx
+<main id="main-content">{children}</main>
+```
+
+Change it to:
+
+```tsx
+<main id="main-content" className="flex-1">{children}</main>
+```
+
+### Why this works
+
+The ThemeProvider component (`src/components/theme-provider.tsx`) is a pass-through wrapper around `next-themes` ThemeProvider — it renders children directly without adding a wrapping `<div>`. So the flex column chain from `<body>` flows directly through to `<SiteHeader>`, `<main>`, and `<SiteFooter>`.
+
+The `min-h-screen` ensures the body fills at least the full viewport. `flex flex-col` creates a vertical flex container. `flex-1` on `<main>` makes it expand to fill all available space, pushing `<SiteFooter>` to the bottom.
+
+## Acceptance Criteria
+
+- [ ] `<body>` has classes `min-h-screen flex flex-col` in addition to existing font variable classes
+- [ ] `<main>` has `className="flex-1"` 
+- [ ] On short-content pages (e.g. `/login`), the footer sits at the bottom of the viewport
+- [ ] On long-content pages (e.g. `/profile`), the footer sits below the content as usual
+- [ ] No visual regressions on any page