blacksmith-cli 0.1.1

package/dist/index.js

@@ -0,0 +1,4404 @@
+// src/index.ts
+import { Command } from "commander";
+
+// src/utils/logger.ts
+import chalk from "chalk";
+import ora from "ora";
+import { createInterface } from "readline";
+var log = {
+  info: (msg) => console.log(chalk.blue("\u2139"), msg),
+  success: (msg) => console.log(chalk.green("\u2713"), msg),
+  warn: (msg) => console.log(chalk.yellow("\u26A0"), msg),
+  error: (msg) => console.log(chalk.red("\u2717"), msg),
+  step: (msg) => console.log(chalk.cyan("\u2192"), msg),
+  blank: () => console.log()
+};
+function promptText(label, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const def = defaultValue ? chalk.dim(` (${defaultValue})`) : "";
+  const question = `  ${chalk.cyan("?")} ${chalk.bold(label)}${def}${chalk.dim(":")} `;
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+function promptYesNo(label, defaultValue = false) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const hint = defaultValue ? chalk.dim(" (Y/n)") : chalk.dim(" (y/N)");
+  const question = `  ${chalk.cyan("?")} ${chalk.bold(label)}${hint}${chalk.dim(":")} `;
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const val = answer.trim().toLowerCase();
+      if (!val) return resolve(defaultValue);
+      resolve(["y", "yes"].includes(val));
+    });
+  });
+}
+function promptSelect(label, options, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const optionList = options.map((opt, i) => `${chalk.dim(`  ${i + 1}.`)} ${opt}`).join("\n");
+  const def = defaultValue ? chalk.dim(` (${defaultValue})`) : "";
+  const question = `  ${chalk.cyan("?")} ${chalk.bold(label)}${def}
+${optionList}
+  ${chalk.dim("Choice:")} `;
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      if (!trimmed && defaultValue) return resolve(defaultValue);
+      const index = parseInt(trimmed, 10);
+      if (index >= 1 && index <= options.length) return resolve(options[index - 1]);
+      const match = options.find((opt) => opt.toLowerCase() === trimmed.toLowerCase());
+      resolve(match || defaultValue || options[0]);
+    });
+  });
+}
+function printConfig(config) {
+  const bar = chalk.dim("\u2502");
+  console.log();
+  console.log(`  ${chalk.dim("\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510")}`);
+  console.log(`  ${bar}  ${chalk.bold.white("Configuration")}${" ".repeat(23)}${bar}`);
+  console.log(`  ${chalk.dim("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524")}`);
+  for (const [key, value] of Object.entries(config)) {
+    const padded = `${chalk.dim(key + ":")} ${chalk.white(value)}`;
+    const rawLen = `${key}: ${value}`.length;
+    const padding = " ".repeat(Math.max(1, 36 - rawLen));
+    console.log(`  ${bar}  ${padded}${padding}${bar}`);
+  }
+  console.log(`  ${chalk.dim("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518")}`);
+  console.log();
+}
+function spinner(text) {
+  return ora({ text, color: "cyan" }).start();
+}
+function banner() {
+  const logo = [
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557      \u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557  \u2588\u2588\u2557",
+    "  \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551 \u2588\u2588\u2554\u255D",
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2554\u255D ",
+    "  \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2588\u2588\u2557 ",
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2557",
+    "  \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D",
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557  \u2588\u2588\u2557",
+    "  \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u2588\u2588\u2551  \u2588\u2588\u2551",
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2554\u2588\u2588\u2588\u2588\u2554\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551",
+    "  \u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2554\u255D\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551",
+    "  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551 \u255A\u2550\u255D \u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551  \u2588\u2588\u2551",
+    "  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D     \u255A\u2550\u255D\u255A\u2550\u255D   \u255A\u2550\u255D   \u255A\u2550\u255D  \u255A\u2550\u255D"
+  ];
+  console.log();
+  for (const line of logo) {
+    console.log(chalk.cyan(line));
+  }
+  console.log();
+  console.log(chalk.dim("  Welcome to Blacksmith \u2014 forge fullstack apps with one command."));
+  console.log();
+}
+function printNextSteps(projectName, backendPort = 8e3, frontendPort = 5173) {
+  log.blank();
+  log.success("Project created successfully!");
+  log.blank();
+  console.log(chalk.bold("  Next steps:"));
+  console.log();
+  console.log(`  ${chalk.cyan("cd")} ${projectName}`);
+  console.log(`  ${chalk.cyan("blacksmith dev")}        ${chalk.dim("# Start development servers")}`);
+  console.log();
+  console.log(chalk.dim(`  Django:   http://localhost:${backendPort}`));
+  console.log(chalk.dim(`  React:    http://localhost:${frontendPort}`));
+  console.log(chalk.dim(`  Swagger:  http://localhost:${backendPort}/api/docs/`));
+  console.log(chalk.dim(`  ReDoc:    http://localhost:${backendPort}/api/redoc/`));
+  log.blank();
+}
+
+// src/commands/init.ts
+import path4 from "path";
+import fs4 from "fs";
+import { spawn } from "child_process";
+
+// src/utils/template.ts
+import fs from "fs";
+import path from "path";
+import Handlebars from "handlebars";
+Handlebars.registerHelper("eq", (a, b) => a === b);
+Handlebars.registerHelper("ne", (a, b) => a !== b);
+Handlebars.registerHelper("upper", (str) => str?.toUpperCase());
+Handlebars.registerHelper("lower", (str) => str?.toLowerCase());
+function renderTemplate(templateStr, context) {
+  let safeStr = templateStr.replace(/\{(\s*)(?=\{\{[^{])/g, "BLACKSMITH_OB$1").replace(/([^}]\}\})(\s*)\}/g, "$1$2BLACKSMITH_CB");
+  const template = Handlebars.compile(safeStr, { noEscape: true });
+  const rendered = template(context);
+  return rendered.replace(/BLACKSMITH_OB/g, "{").replace(/BLACKSMITH_CB/g, "}");
+}
+function renderTemplateFile(templatePath, context) {
+  const templateStr = fs.readFileSync(templatePath, "utf-8");
+  return renderTemplate(templateStr, context);
+}
+function renderToFile(templatePath, destPath, context) {
+  const rendered = renderTemplateFile(templatePath, context);
+  const destDir = path.dirname(destPath);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  fs.writeFileSync(destPath, rendered, "utf-8");
+}
+function renderDirectory(srcDir, destDir, context) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Template directory not found: ${srcDir}`);
+  }
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const renderedName = renderTemplate(entry.name, context);
+    const srcPath = path.join(srcDir, entry.name);
+    if (entry.isDirectory()) {
+      const destSubDir = path.join(destDir, renderedName);
+      renderDirectory(srcPath, destSubDir, context);
+    } else if (entry.name.endsWith(".hbs")) {
+      const outputName = renderedName.replace(/\.hbs$/, "");
+      const destPath = path.join(destDir, outputName);
+      renderToFile(srcPath, destPath, context);
+    } else {
+      const destPath = path.join(destDir, renderedName);
+      const destDirPath = path.dirname(destPath);
+      if (!fs.existsSync(destDirPath)) {
+        fs.mkdirSync(destDirPath, { recursive: true });
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function appendAfterMarker(filePath, marker, content) {
+  const fileContent = fs.readFileSync(filePath, "utf-8");
+  const lines = fileContent.split("\n");
+  const markerIndex = lines.findIndex((line) => line.includes(marker));
+  if (markerIndex === -1) {
+    throw new Error(`Marker "${marker}" not found in ${filePath}`);
+  }
+  lines.splice(markerIndex + 1, 0, content);
+  fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
+}
+function insertBeforeMarker(filePath, marker, content) {
+  const fileContent = fs.readFileSync(filePath, "utf-8");
+  const lines = fileContent.split("\n");
+  const markerIndex = lines.findIndex((line) => line.includes(marker));
+  if (markerIndex === -1) {
+    throw new Error(`Marker "${marker}" not found in ${filePath}`);
+  }
+  lines.splice(markerIndex, 0, content);
+  fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
+}
+
+// src/utils/exec.ts
+import { execa } from "execa";
+async function exec(command, args, options = {}) {
+  const { cwd, silent = false, env } = options;
+  try {
+    const result = await execa(command, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: silent ? "pipe" : "inherit"
+    });
+    return result;
+  } catch (error) {
+    if (!silent) {
+      log.error(`Command failed: ${command} ${args.join(" ")}`);
+      if (error.stderr) {
+        log.error(error.stderr);
+      }
+    }
+    throw error;
+  }
+}
+async function commandExists(command) {
+  try {
+    await execa("which", [command], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function execPython(args, cwd, silent = false) {
+  const venvPython = `${cwd}/venv/bin/python`;
+  return exec(venvPython, args, { cwd, silent });
+}
+async function execPip(args, cwd, silent = false) {
+  const venvPip = `${cwd}/venv/bin/pip`;
+  return exec(venvPip, args, { cwd, silent });
+}
+
+// src/utils/paths.ts
+import path2 from "path";
+import fs2 from "fs";
+import { fileURLToPath } from "url";
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path2.dirname(__filename2);
+function getTemplatesDir() {
+  const devPath = path2.resolve(__dirname2, "..", "templates");
+  const prodPath = path2.resolve(__dirname2, "..", "src", "templates");
+  if (fs2.existsSync(devPath)) return devPath;
+  if (fs2.existsSync(prodPath)) return prodPath;
+  throw new Error("Templates directory not found. Make sure the CLI is properly installed.");
+}
+function findProjectRoot(startDir) {
+  let dir = startDir || process.cwd();
+  while (dir !== path2.dirname(dir)) {
+    if (fs2.existsSync(path2.join(dir, "blacksmith.config.json"))) {
+      return dir;
+    }
+    dir = path2.dirname(dir);
+  }
+  throw new Error(
+    'Not inside a Blacksmith project. Run "blacksmith init <name>" to create one, or navigate to an existing Blacksmith project.'
+  );
+}
+function getBackendDir(projectRoot) {
+  const root = projectRoot || findProjectRoot();
+  return path2.join(root, "backend");
+}
+function getFrontendDir(projectRoot) {
+  const root = projectRoot || findProjectRoot();
+  return path2.join(root, "frontend");
+}
+function loadConfig(projectRoot) {
+  const root = projectRoot || findProjectRoot();
+  const configPath = path2.join(root, "blacksmith.config.json");
+  return JSON.parse(fs2.readFileSync(configPath, "utf-8"));
+}
+
+// src/commands/ai-setup.ts
+import path3 from "path";
+import fs3 from "fs";
+
+// src/skills/core-rules.ts
+var coreRulesSkill = {
+  id: "core-rules",
+  // No `name` → content is inlined directly into CLAUDE.md, not a separate file
+  render(_ctx) {
+    return `## Critical Rules
+
+> **These rules are mandatory. Violating them produces broken, inconsistent code.**
+
+### 1. Use \`@blacksmith-ui/react\` for ALL UI
+- **Layout**: Use \`Stack\`, \`Flex\`, \`Grid\`, \`Box\`, \`Container\` \u2014 NEVER \`<div className="flex ...">\` or \`<div className="grid ...">\`
+- **Typography**: Use \`Typography\` and \`Text\` \u2014 NEVER raw \`<h1>\`\u2013\`<h6>\`, \`<p>\`, or \`<span>\` with text classes
+- **Separators**: Use \`Divider\` \u2014 NEVER \`<hr>\` or \`<Separator>\`
+- **Everything else**: \`Button\`, \`Card\`, \`Badge\`, \`Input\`, \`Table\`, \`Dialog\`, \`Alert\`, \`Skeleton\`, \`EmptyState\`, \`StatCard\`, etc.
+- See the \`blacksmith-ui-react\` skill for the full 60+ component list
+
+### 2. Pages Are Thin Orchestrators
+- A page file should be ~20-30 lines: import components, call hooks, compose JSX
+- Break every page into child components in a \`components/\` folder
+- See the \`page-structure\` skill for the full pattern with examples
+
+### 3. Components Render, Hooks Think
+- Extract ALL logic into hooks in a \`hooks/\` folder \u2014 API calls, mutations, form setup, filtering, pagination, debouncing, computed state
+- Components should contain only JSX composition, prop passing, and simple event handler wiring
+- The only \`useState\` acceptable inline in a component is a simple UI toggle (e.g. modal open/close)
+- If a component has more than one \`useState\`, one \`useEffect\`, or any \`useApiQuery\`/\`useApiMutation\` \u2014 extract to a hook
+
+### 4. Use the \`Path\` Enum \u2014 Never Hardcode Paths
+- All route paths are in \`src/router/paths.ts\` as a \`Path\` enum
+- Use \`Path.Login\`, \`Path.Dashboard\`, etc. in \`navigate()\`, \`<Link to={}>\`, and route definitions
+- When adding a new page, add its path to the enum before \`// blacksmith:path\`
+- Use \`buildPath(Path.ResetPassword, { token })\` for dynamic segments
+
+### 5. Follow the Page/Feature Folder Structure
+\`\`\`
+pages/<page>/
+\u251C\u2500\u2500 <page>.tsx         # Thin orchestrator (default export)
+\u251C\u2500\u2500 routes.tsx         # RouteObject[] using Path enum
+\u251C\u2500\u2500 index.ts           # Re-exports public API
+\u251C\u2500\u2500 components/        # Child components
+\u2514\u2500\u2500 hooks/             # Data hooks
+\`\`\`
+- See the \`page-structure\` skill for full conventions
+`;
+  }
+};
+
+// src/skills/project-overview.ts
+var projectOverviewSkill = {
+  id: "project-overview",
+  name: "Project Overview",
+  description: "Overview of the project structure, commands, and development workflow.",
+  render(ctx) {
+    return `# ${ctx.projectName}
+
+A fullstack web application built with **Django** (backend) and **React** (frontend), scaffolded by **Blacksmith CLI**.
+
+## Project Structure
+
+\`\`\`
+${ctx.projectName}/
+\u251C\u2500\u2500 backend/              # Django project
+\u2502   \u251C\u2500\u2500 apps/             # Django apps (one per resource)
+\u2502   \u2502   \u2514\u2500\u2500 users/        # Built-in user app
+\u2502   \u251C\u2500\u2500 config/           # Django settings, urls, wsgi/asgi
+\u2502   \u2502   \u2514\u2500\u2500 settings/     # Split settings (base, development, production)
+\u2502   \u251C\u2500\u2500 manage.py
+\u2502   \u251C\u2500\u2500 requirements.txt
+\u2502   \u2514\u2500\u2500 venv/             # Python virtual environment
+\u251C\u2500\u2500 frontend/             # React + Vite project
+\u2502   \u251C\u2500\u2500 src/
+\u2502   \u2502   \u251C\u2500\u2500 api/          # API client (auto-generated from OpenAPI)
+\u2502   \u2502   \u251C\u2500\u2500 features/     # Feature modules (auth, etc.)
+\u2502   \u2502   \u251C\u2500\u2500 pages/        # Top-level pages
+\u2502   \u2502   \u251C\u2500\u2500 router/       # React Router setup with guards
+\u2502   \u2502   \u251C\u2500\u2500 shared/       # Shared components and hooks
+\u2502   \u2502   \u2514\u2500\u2500 styles/       # Global styles (Tailwind)
+\u2502   \u251C\u2500\u2500 package.json
+\u2502   \u2514\u2500\u2500 tailwind.config.js
+\u251C\u2500\u2500 blacksmith.config.json
+\u2514\u2500\u2500 CLAUDE.md             # This file
+\`\`\`
+
+## Commands
+
+- \`blacksmith dev\` \u2014 Start Django + Vite + OpenAPI sync in parallel
+- \`blacksmith sync\` \u2014 Regenerate frontend API types from Django OpenAPI schema
+- \`blacksmith make:resource <Name>\` \u2014 Scaffold a full resource (model, serializer, viewset, hooks, pages)
+- \`blacksmith build\` \u2014 Production build (frontend + collectstatic)
+- \`blacksmith eject\` \u2014 Remove Blacksmith, keep a clean Django + React project
+
+## Development Workflow
+
+1. Define models in \`backend/apps/<app>/models.py\`
+2. Create serializers in \`backend/apps/<app>/serializers.py\`
+3. Add viewsets in \`backend/apps/<app>/views.py\` and register URLs in \`backend/apps/<app>/urls.py\`
+4. Run \`blacksmith sync\` to generate TypeScript types and API client
+5. Build frontend features using generated hooks in \`frontend/src/features/\`
+`;
+  }
+};
+
+// src/skills/django.ts
+var djangoSkill = {
+  id: "django",
+  name: "Django Backend Conventions",
+  description: "Models, serializers, views, URLs, settings, migrations, and testing patterns for the Django backend.",
+  render(_ctx) {
+    return `## Django Backend Conventions
+
+### Models
+- Models live in \`backend/apps/<app>/models.py\`
+- Use Django's ORM. Inherit from \`models.Model\`
+- Use \`TimeStampedModel\` pattern: add \`created_at\` and \`updated_at\` fields with \`auto_now_add\` and \`auto_now\`
+- Register models in \`backend/apps/<app>/admin.py\` for Django admin
+- Use descriptive \`verbose_name\` and \`verbose_name_plural\` in \`Meta\`
+- Define \`__str__\` on every model for readable admin and debugging output
+- Use \`related_name\` on all ForeignKey and ManyToManyField declarations
+- Prefer \`TextField\` over \`CharField\` when there is no strict max length requirement
+
+### Serializers
+- Use Django REST Framework serializers in \`backend/apps/<app>/serializers.py\`
+- Prefer \`ModelSerializer\` for standard CRUD operations
+- Use \`serializers.Serializer\` for custom input/output that does not map to a model
+- Add per-field validation via \`validate_<field>(self, value)\` methods
+- Add cross-field validation via \`validate(self, attrs)\`
+- Use \`SerializerMethodField\` for computed read-only fields
+- Nest related serializers for read endpoints; use PrimaryKeyRelatedField for write endpoints
+- Keep serializers thin \u2014 move business logic to model methods or service functions
+
+### Views
+- Use DRF \`ModelViewSet\` for standard CRUD endpoints
+- Use \`@action(detail=True|False)\` decorator for custom non-CRUD endpoints
+- Apply permissions with \`permission_classes\` at the class or action level
+- Use \`@extend_schema\` from \`drf-spectacular\` to document every endpoint \u2014 this powers the OpenAPI sync that generates frontend types
+- Use \`filterset_fields\`, \`search_fields\`, and \`ordering_fields\` for queryable list endpoints
+- Override \`get_queryset()\` to scope data to the current user when needed
+- Override \`perform_create()\` to inject \`request.user\` or other context into the serializer save
+
+### URLs
+- Each app has its own \`urls.py\` with a \`DefaultRouter\`
+- Register viewsets on the router: \`router.register('resources', ResourceViewSet)\`
+- App URLs are included in \`backend/config/urls.py\` under \`/api/\`
+- URL pattern: \`/api/<resource>/\` (list/create), \`/api/<resource>/<id>/\` (retrieve/update/delete)
+
+### Settings
+- Split settings: \`base.py\` (shared), \`development.py\` (local dev), \`production.py\` (deployment)
+- Environment variables loaded from \`.env\` via \`django-environ\`
+- Database: SQLite in development, configurable in production via \`DATABASE_URL\`
+- \`INSTALLED_APPS\` is declared in \`base.py\` \u2014 add new apps there
+- CORS, allowed hosts, and debug flags are environment-specific
+
+### Migrations
+- Run \`./venv/bin/python manage.py makemigrations <app>\` after model changes
+- Run \`./venv/bin/python manage.py migrate\` to apply
+- Never edit auto-generated migration files unless resolving a conflict
+- Use \`RunPython\` in data migrations for one-time data transformations
+
+### Testing
+- Tests live in \`backend/apps/<app>/tests.py\` (or a \`tests/\` package for larger apps)
+- Use \`APITestCase\` from DRF for API endpoint tests
+- Use \`APIClient\` with \`force_authenticate(user)\` for authenticated requests
+- Test both success and error paths (400, 401, 403, 404)
+- Run all tests: \`cd backend && ./venv/bin/python manage.py test\`
+- Run a single app: \`cd backend && ./venv/bin/python manage.py test apps.<app>\`
+
+### Adding a New App Manually
+1. Create the app directory under \`backend/apps/\` with \`__init__.py\`, \`models.py\`, \`views.py\`, \`serializers.py\`, \`urls.py\`, \`admin.py\`, \`tests.py\`
+2. Add \`'apps.<app>'\` to \`INSTALLED_APPS\` in \`backend/config/settings/base.py\`
+3. Include URLs in \`backend/config/urls.py\`: \`path('api/<app>/', include('apps.<app>.urls'))\`
+4. Run \`makemigrations\` and \`migrate\`
+5. Run \`blacksmith sync\` to update frontend types
+
+### Common Patterns
+- **Soft delete**: Add an \`is_active\` BooleanField and override \`get_queryset()\` to filter
+- **Pagination**: Configured globally in \`REST_FRAMEWORK\` settings \u2014 default is \`PageNumberPagination\`
+- **Permissions**: Use \`IsAuthenticated\` as default; create custom permissions in \`permissions.py\`
+- **Signals**: Use sparingly; prefer explicit calls in serializer/view logic
+- **Management commands**: Place in \`backend/apps/<app>/management/commands/\` for CLI tasks
+`;
+  }
+};
+
+// src/skills/django-rest-advanced.ts
+var djangoRestAdvancedSkill = {
+  id: "django-rest-advanced",
+  name: "Advanced Django REST Framework",
+  description: "Senior-level DRF patterns: service layer, query optimization, custom permissions, filters, caching, and testing.",
+  render(_ctx) {
+    return `## Advanced Django REST Framework \u2014 Senior-Level Patterns
+
+> **RULE: Follow these patterns for production-grade, scalable, and maintainable DRF APIs.**
+> These build on top of the base Django conventions. Apply them when building non-trivial features.
+
+### Architecture: Service Layer Pattern
+
+Keep views and serializers thin. Extract business logic into service modules.
+
+\`\`\`
+backend/apps/<app>/
+\u251C\u2500\u2500 models.py          # Data + model-level methods only
+\u251C\u2500\u2500 serializers.py     # Validation + representation only
+\u251C\u2500\u2500 views.py           # HTTP glue + permissions only
+\u251C\u2500\u2500 services.py        # Business logic lives here
+\u251C\u2500\u2500 selectors.py       # Complex read queries
+\u251C\u2500\u2500 permissions.py     # Custom permission classes
+\u251C\u2500\u2500 filters.py         # Custom filter backends
+\u251C\u2500\u2500 signals.py         # Signal handlers (use sparingly)
+\u251C\u2500\u2500 tasks.py           # Celery/background tasks
+\u2514\u2500\u2500 tests/
+    \u251C\u2500\u2500 test_views.py
+    \u251C\u2500\u2500 test_services.py
+    \u2514\u2500\u2500 test_selectors.py
+\`\`\`
+
+\`\`\`python
+# services.py \u2014 Business logic
+from django.db import transaction
+
+class OrderService:
+    @staticmethod
+    @transaction.atomic
+    def place_order(*, user, items, shipping_address):
+        """Place an order with inventory validation and payment."""
+        order = Order.objects.create(user=user, shipping_address=shipping_address)
+        for item in items:
+            if item['product'].stock < item['quantity']:
+                raise ValidationError(f"Insufficient stock for {item['product'].name}")
+            OrderItem.objects.create(order=order, **item)
+            item['product'].stock -= item['quantity']
+            item['product'].save(update_fields=['stock'])
+        PaymentService.charge(user=user, amount=order.total)
+        return order
+\`\`\`
+
+\`\`\`python
+# selectors.py \u2014 Complex read queries
+from django.db.models import Q, Count, Prefetch
+
+class OrderSelector:
+    @staticmethod
+    def list_for_user(*, user, status=None, search=None):
+        qs = (
+            Order.objects
+            .filter(user=user)
+            .select_related('user', 'shipping_address')
+            .prefetch_related(
+                Prefetch('items', queryset=OrderItem.objects.select_related('product'))
+            )
+            .annotate(item_count=Count('items'))
+        )
+        if status:
+            qs = qs.filter(status=status)
+        if search:
+            qs = qs.filter(Q(id__icontains=search) | Q(items__product__name__icontains=search))
+        return qs.distinct().order_by('-created_at')
+\`\`\`
+
+### Serializers: Advanced Patterns
+
+**Separate read and write serializers:**
+\`\`\`python
+class OrderListSerializer(serializers.ModelSerializer):
+    """Lightweight serializer for list endpoints."""
+    item_count = serializers.IntegerField(read_only=True)
+    user = UserMinimalSerializer(read_only=True)
+
+    class Meta:
+        model = Order
+        fields = ['id', 'status', 'total', 'item_count', 'user', 'created_at']
+
+
+class OrderDetailSerializer(serializers.ModelSerializer):
+    """Full serializer for retrieve endpoints."""
+    items = OrderItemSerializer(many=True, read_only=True)
+    user = UserSerializer(read_only=True)
+    shipping_address = AddressSerializer(read_only=True)
+
+    class Meta:
+        model = Order
+        fields = ['id', 'status', 'total', 'items', 'user', 'shipping_address', 'created_at', 'updated_at']
+
+
+class OrderCreateSerializer(serializers.Serializer):
+    """Write serializer \u2014 validates input, delegates to service."""
+    items = OrderItemInputSerializer(many=True)
+    shipping_address_id = serializers.PrimaryKeyRelatedField(queryset=Address.objects.all())
+
+    def create(self, validated_data):
+        return OrderService.place_order(
+            user=self.context['request'].user,
+            items=validated_data['items'],
+            shipping_address=validated_data['shipping_address_id'],
+        )
+\`\`\`
+
+**Writable nested serializers:**
+\`\`\`python
+class ProjectSerializer(serializers.ModelSerializer):
+    tags = TagSerializer(many=True, required=False)
+
+    class Meta:
+        model = Project
+        fields = ['id', 'name', 'description', 'tags']
+
+    def create(self, validated_data):
+        tags_data = validated_data.pop('tags', [])
+        project = Project.objects.create(**validated_data)
+        for tag_data in tags_data:
+            tag, _ = Tag.objects.get_or_create(**tag_data)
+            project.tags.add(tag)
+        return project
+
+    def update(self, instance, validated_data):
+        tags_data = validated_data.pop('tags', None)
+        instance = super().update(instance, validated_data)
+        if tags_data is not None:
+            instance.tags.clear()
+            for tag_data in tags_data:
+                tag, _ = Tag.objects.get_or_create(**tag_data)
+                instance.tags.add(tag)
+        return instance
+\`\`\`
+
+**Dynamic field serializers:**
+\`\`\`python
+class DynamicFieldsSerializer(serializers.ModelSerializer):
+    """Pass ?fields=id,name,email to limit response fields."""
+    def __init__(self, *args, **kwargs):
+        fields = kwargs.pop('fields', None)
+        super().__init__(*args, **kwargs)
+        if fields is not None:
+            allowed = set(fields)
+            for field_name in set(self.fields) - allowed:
+                self.fields.pop(field_name)
+\`\`\`
+
+### ViewSets: Advanced Patterns
+
+**Use \`get_serializer_class()\` for action-specific serializers:**
+\`\`\`python
+class OrderViewSet(ModelViewSet):
+    permission_classes = [IsAuthenticated]
+    filterset_class = OrderFilterSet
+    search_fields = ['items__product__name']
+    ordering_fields = ['created_at', 'total']
+    ordering = ['-created_at']
+
+    def get_queryset(self):
+        return OrderSelector.list_for_user(user=self.request.user)
+
+    def get_serializer_class(self):
+        if self.action == 'list':
+            return OrderListSerializer
+        if self.action == 'retrieve':
+            return OrderDetailSerializer
+        if self.action in ('create',):
+            return OrderCreateSerializer
+        return OrderUpdateSerializer
+
+    def perform_create(self, serializer):
+        serializer.save()  # Service called inside serializer.create()
+
+    @extend_schema(request=None, responses={200: OrderDetailSerializer})
+    @action(detail=True, methods=['post'])
+    def cancel(self, request, pk=None):
+        order = self.get_object()
+        OrderService.cancel_order(order=order, user=request.user)
+        return Response(OrderDetailSerializer(order).data)
+\`\`\`
+
+**Bulk operations:**
+\`\`\`python
+class BulkActionSerializer(serializers.Serializer):
+    ids = serializers.ListField(child=serializers.IntegerField(), min_length=1, max_length=100)
+    action = serializers.ChoiceField(choices=['archive', 'delete', 'export'])
+
+@extend_schema(request=BulkActionSerializer, responses={200: None})
+@action(detail=False, methods=['post'])
+def bulk_action(self, request):
+    serializer = BulkActionSerializer(data=request.data)
+    serializer.is_valid(raise_exception=True)
+    qs = self.get_queryset().filter(id__in=serializer.validated_data['ids'])
+    action = serializer.validated_data['action']
+    if action == 'archive':
+        qs.update(status='archived')
+    elif action == 'delete':
+        qs.delete()
+    return Response(status=status.HTTP_200_OK)
+\`\`\`
+
+### QuerySet Optimization
+
+**ALWAYS optimize queries. N+1 queries are unacceptable.**
+
+\`\`\`python
+# BAD \u2014 N+1 queries
+orders = Order.objects.all()
+for order in orders:
+    print(order.user.email)        # 1 query per order
+    for item in order.items.all(): # 1 query per order
+        print(item.product.name)   # 1 query per item
+
+# GOOD \u2014 3 queries total
+orders = (
+    Order.objects
+    .select_related('user')
+    .prefetch_related(
+        Prefetch('items', queryset=OrderItem.objects.select_related('product'))
+    )
+)
+\`\`\`
+
+**Use \`only()\` / \`defer()\` for large tables:**
+\`\`\`python
+# Only load fields you need for list views
+Product.objects.only('id', 'name', 'price', 'thumbnail').filter(is_active=True)
+\`\`\`
+
+**Use \`Subquery\` and \`OuterRef\` for correlated queries:**
+\`\`\`python
+from django.db.models import Subquery, OuterRef
+
+latest_comment = Comment.objects.filter(
+    post=OuterRef('pk')
+).order_by('-created_at')
+
+posts = Post.objects.annotate(
+    latest_comment_text=Subquery(latest_comment.values('text')[:1])
+)
+\`\`\`
+
+### Custom Permissions
+
+\`\`\`python
+# permissions.py
+from rest_framework.permissions import BasePermission
+
+class IsOwner(BasePermission):
+    """Object-level permission: only the owner can modify."""
+    def has_object_permission(self, request, view, obj):
+        return obj.user == request.user
+
+
+class IsAdminOrReadOnly(BasePermission):
+    def has_permission(self, request, view):
+        if request.method in ('GET', 'HEAD', 'OPTIONS'):
+            return True
+        return request.user and request.user.is_staff
+
+
+class HasRole(BasePermission):
+    """Usage: permission_classes = [HasRole('manager')]"""
+    def __init__(self, role):
+        self.role = role
+
+    def has_permission(self, request, view):
+        return hasattr(request.user, 'role') and request.user.role == self.role
+\`\`\`
+
+**Combine permissions per action:**
+\`\`\`python
+class ProjectViewSet(ModelViewSet):
+    def get_permissions(self):
+        if self.action in ('update', 'partial_update', 'destroy'):
+            return [IsAuthenticated(), IsOwner()]
+        if self.action == 'create':
+            return [IsAuthenticated()]
+        return [AllowAny()]
+\`\`\`
+
+### Custom Filters with django-filter
+
+\`\`\`python
+# filters.py
+import django_filters
+from .models import Order
+
+class OrderFilterSet(django_filters.FilterSet):
+    min_total = django_filters.NumberFilter(field_name='total', lookup_expr='gte')
+    max_total = django_filters.NumberFilter(field_name='total', lookup_expr='lte')
+    created_after = django_filters.DateFilter(field_name='created_at', lookup_expr='gte')
+    created_before = django_filters.DateFilter(field_name='created_at', lookup_expr='lte')
+    status = django_filters.MultipleChoiceFilter(choices=Order.STATUS_CHOICES)
+
+    class Meta:
+        model = Order
+        fields = ['status', 'min_total', 'max_total', 'created_after', 'created_before']
+\`\`\`
+
+### Pagination: Cursor-Based for Large Datasets
+
+\`\`\`python
+# pagination.py
+from rest_framework.pagination import CursorPagination
+
+class TimelinePagination(CursorPagination):
+    page_size = 50
+    ordering = '-created_at'
+    cursor_query_param = 'cursor'
+\`\`\`
+
+Use in viewset: \`pagination_class = TimelinePagination\`
+
+### Throttling
+
+\`\`\`python
+# In settings
+REST_FRAMEWORK = {
+    'DEFAULT_THROTTLE_CLASSES': ['rest_framework.throttling.ScopedRateThrottle'],
+    'DEFAULT_THROTTLE_RATES': {
+        'auth': '5/min',
+        'uploads': '20/hour',
+        'burst': '60/min',
+    },
+}
+
+# In view
+class LoginView(APIView):
+    throttle_scope = 'auth'
+\`\`\`
+
+### Caching
+
+\`\`\`python
+from django.views.decorators.cache import cache_page
+from django.utils.decorators import method_decorator
+
+class ProductViewSet(ModelViewSet):
+    @method_decorator(cache_page(60 * 15))  # 15 min cache
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+\`\`\`
+
+**Conditional caching with ETags:**
+\`\`\`python
+from rest_framework_condition import condition
+from hashlib import md5
+
+def product_etag(request, pk=None):
+    product = Product.objects.only('updated_at').get(pk=pk)
+    return md5(str(product.updated_at).encode()).hexdigest()
+
+class ProductViewSet(ModelViewSet):
+    @condition(etag_func=product_etag)
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+\`\`\`
+
+### Error Handling
+
+\`\`\`python
+# exceptions.py
+from rest_framework.views import exception_handler
+from rest_framework.response import Response
+
+def custom_exception_handler(exc, context):
+    response = exception_handler(exc, context)
+    if response is not None:
+        response.data = {
+            'error': {
+                'code': response.status_code,
+                'message': response.data.get('detail', response.data),
+            }
+        }
+    return response
+\`\`\`
+
+Register in settings: \`'EXCEPTION_HANDLER': 'config.exceptions.custom_exception_handler'\`
+
+### Versioning
+
+\`\`\`python
+# settings
+REST_FRAMEWORK = {
+    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
+    'ALLOWED_VERSIONS': ['v1', 'v2'],
+    'DEFAULT_VERSION': 'v1',
+}
+
+# urls.py
+urlpatterns = [
+    path('api/<version>/', include('apps.core.urls')),
+]
+
+# views.py \u2014 Version-specific behavior
+class UserViewSet(ModelViewSet):
+    def get_serializer_class(self):
+        if self.request.version == 'v2':
+            return UserV2Serializer
+        return UserV1Serializer
+\`\`\`
+
+### Signals \u2014 Use Responsibly
+
+\`\`\`python
+# signals.py \u2014 Only for cross-cutting concerns (audit logs, cache invalidation)
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+@receiver(post_save, sender=Order)
+def notify_on_order_placed(sender, instance, created, **kwargs):
+    if created:
+        NotificationService.send_order_confirmation(order=instance)
+\`\`\`
+
+Register in \`apps.py\`:
+\`\`\`python
+class OrdersConfig(AppConfig):
+    def ready(self):
+        import apps.orders.signals  # noqa: F401
+\`\`\`
+
+> **Prefer explicit service calls over signals for business logic.** Signals make flow hard to trace.
+
+### Testing: Senior-Level Patterns
+
+\`\`\`python
+import factory
+from rest_framework.test import APITestCase, APIClient
+
+# factories.py \u2014 Use factory_boy for test data
+class UserFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = User
+    email = factory.Sequence(lambda n: f'user{n}@example.com')
+    password = factory.PostGenerationMethodCall('set_password', 'testpass123')
+
+
+class OrderFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Order
+    user = factory.SubFactory(UserFactory)
+    status = 'pending'
+
+
+# test_views.py
+class OrderViewSetTest(APITestCase):
+    def setUp(self):
+        self.user = UserFactory()
+        self.client = APIClient()
+        self.client.force_authenticate(self.user)
+
+    def test_list_returns_only_own_orders(self):
+        OrderFactory.create_batch(3, user=self.user)
+        OrderFactory.create_batch(2)  # Other user's orders
+        response = self.client.get('/api/orders/')
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.data['results']), 3)
+
+    def test_create_validates_stock(self):
+        product = ProductFactory(stock=0)
+        response = self.client.post('/api/orders/', {
+            'items': [{'product_id': product.id, 'quantity': 1}],
+            'shipping_address_id': AddressFactory(user=self.user).id,
+        }, format='json')
+        self.assertEqual(response.status_code, 400)
+
+    def test_cancel_forbidden_for_non_owner(self):
+        order = OrderFactory()  # Different user
+        response = self.client.post(f'/api/orders/{order.id}/cancel/')
+        self.assertEqual(response.status_code, 403)
+\`\`\`
+
+**Test query count to prevent N+1 regressions:**
+\`\`\`python
+from django.test.utils import override_settings
+
+def test_list_query_count(self):
+    OrderFactory.create_batch(10, user=self.user)
+    with self.assertNumQueries(3):  # 1 count + 1 orders + 1 prefetch items
+        self.client.get('/api/orders/')
+\`\`\`
+
+### API Documentation with drf-spectacular
+
+\`\`\`python
+from drf_spectacular.utils import extend_schema, extend_schema_view, OpenApiParameter, OpenApiExample
+
+@extend_schema_view(
+    list=extend_schema(
+        summary="List orders",
+        parameters=[
+            OpenApiParameter('status', str, description='Filter by status'),
+            OpenApiParameter('search', str, description='Search by product name'),
+        ],
+    ),
+    create=extend_schema(summary="Place a new order"),
+    cancel=extend_schema(summary="Cancel an order", responses={200: OrderDetailSerializer}),
+)
+class OrderViewSet(ModelViewSet):
+    ...
+\`\`\`
+
+### Key Principles
+
+1. **Fat services, thin views** \u2014 Views handle HTTP; services handle logic
+2. **Optimize every queryset** \u2014 Use \`select_related\`, \`prefetch_related\`, \`only\`, \`annotate\`
+3. **Separate read/write serializers** \u2014 List views are lightweight, detail views are rich, write views validate input
+4. **Test behavior, not implementation** \u2014 Test API contracts, permissions, and edge cases
+5. **Use \`transaction.atomic\`** \u2014 Wrap multi-step mutations to prevent partial writes
+6. **Document with \`extend_schema\`** \u2014 Every endpoint needs OpenAPI docs for frontend type generation
+7. **Scope querysets to user** \u2014 Never return data the user shouldn't see
+8. **Use cursor pagination for large datasets** \u2014 Offset pagination degrades at scale
+9. **Throttle sensitive endpoints** \u2014 Auth, uploads, and expensive operations
+10. **Version your API** \u2014 Plan for breaking changes from the start
+`;
+  }
+};
+
+// src/skills/api-documentation.ts
+var apiDocumentationSkill = {
+  id: "api-documentation",
+  name: "API Documentation",
+  description: "drf-spectacular OpenAPI/Swagger documentation conventions for all API endpoints.",
+  render(_ctx) {
+    return `## API Documentation \u2014 drf-spectacular (OpenAPI / Swagger)
+
+> **RULE: Every API endpoint MUST be documented with \`@extend_schema\` from \`drf-spectacular\`.**
+> Undocumented endpoints break the frontend type generation pipeline (\`blacksmith sync\`).
+> The OpenAPI schema powers auto-generated TypeScript types \u2014 accurate docs = accurate frontend types.
+
+### Setup
+
+drf-spectacular is already configured in \`backend/config/settings/base.py\`:
+
+\`\`\`python
+INSTALLED_APPS = [
+    ...
+    'drf_spectacular',
+]
+
+REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+}
+
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'API',
+    'DESCRIPTION': 'API documentation',
+    'VERSION': '1.0.0',
+    'SERVE_INCLUDE_SCHEMA': False,
+}
+\`\`\`
+
+Docs URLs in \`backend/config/urls.py\`:
+\`\`\`python
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
+
+urlpatterns = [
+    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
+    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
+]
+\`\`\`
+
+### Decorating ViewSets \u2014 MANDATORY
+
+**Use \`@extend_schema_view\` on every ViewSet:**
+\`\`\`python
+from drf_spectacular.utils import extend_schema, extend_schema_view, OpenApiParameter, OpenApiExample, OpenApiResponse
+
+@extend_schema_view(
+    list=extend_schema(
+        summary="List projects",
+        description="Returns paginated list of projects for the authenticated user.",
+        parameters=[
+            OpenApiParameter('status', str, enum=['active', 'archived'], description='Filter by status'),
+            OpenApiParameter('search', str, description='Search by name or description'),
+            OpenApiParameter('ordering', str, description='Sort field (prefix with - for desc)', enum=['created_at', '-created_at', 'name', '-name']),
+        ],
+        responses={200: ProjectListSerializer},
+    ),
+    retrieve=extend_schema(
+        summary="Get project details",
+        responses={200: ProjectDetailSerializer},
+    ),
+    create=extend_schema(
+        summary="Create a project",
+        request=ProjectCreateSerializer,
+        responses={201: ProjectDetailSerializer},
+        examples=[
+            OpenApiExample(
+                'Create project',
+                value={'name': 'My Project', 'description': 'A new project'},
+                request_only=True,
+            ),
+        ],
+    ),
+    update=extend_schema(
+        summary="Update a project",
+        request=ProjectUpdateSerializer,
+        responses={200: ProjectDetailSerializer},
+    ),
+    partial_update=extend_schema(
+        summary="Partially update a project",
+        request=ProjectUpdateSerializer,
+        responses={200: ProjectDetailSerializer},
+    ),
+    destroy=extend_schema(
+        summary="Delete a project",
+        responses={204: None},
+    ),
+)
+class ProjectViewSet(ModelViewSet):
+    ...
+\`\`\`
+
+**Custom actions MUST also be decorated:**
+\`\`\`python
+@extend_schema(
+    summary="Archive a project",
+    request=None,
+    responses={200: ProjectDetailSerializer},
+)
+@action(detail=True, methods=['post'])
+def archive(self, request, pk=None):
+    project = self.get_object()
+    ProjectService.archive(project=project)
+    return Response(ProjectDetailSerializer(project).data)
+
+
+@extend_schema(
+    summary="Bulk delete projects",
+    request=BulkDeleteSerializer,
+    responses={204: None},
+)
+@action(detail=False, methods=['post'])
+def bulk_delete(self, request):
+    ...
+\`\`\`
+
+### Decorating APIViews
+
+\`\`\`python
+class DashboardStatsView(APIView):
+    @extend_schema(
+        summary="Get dashboard statistics",
+        responses={200: DashboardStatsSerializer},
+    )
+    def get(self, request):
+        stats = DashboardSelector.get_stats(user=request.user)
+        return Response(DashboardStatsSerializer(stats).data)
+\`\`\`
+
+### Serializer Documentation
+
+**Use \`help_text\` on serializer fields \u2014 these become field descriptions in the schema:**
+\`\`\`python
+class ProjectCreateSerializer(serializers.Serializer):
+    name = serializers.CharField(max_length=255, help_text="The project name. Must be unique per user.")
+    description = serializers.CharField(required=False, help_text="Optional project description.")
+    status = serializers.ChoiceField(
+        choices=['active', 'archived'],
+        default='active',
+        help_text="Initial project status.",
+    )
+    tags = serializers.ListField(
+        child=serializers.CharField(),
+        required=False,
+        help_text="List of tag names to attach.",
+    )
+\`\`\`
+
+**Use \`@extend_schema_serializer\` for serializer-level docs:**
+\`\`\`python
+from drf_spectacular.utils import extend_schema_serializer, OpenApiExample
+
+@extend_schema_serializer(
+    examples=[
+        OpenApiExample(
+            'Project response',
+            value={
+                'id': 1,
+                'name': 'My Project',
+                'status': 'active',
+                'created_at': '2025-01-15T10:30:00Z',
+            },
+            response_only=True,
+        ),
+    ]
+)
+class ProjectDetailSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Project
+        fields = ['id', 'name', 'description', 'status', 'created_at', 'updated_at']
+\`\`\`
+
+### Response Types
+
+**Explicitly declare all possible response codes:**
+\`\`\`python
+@extend_schema(
+    summary="Place an order",
+    request=OrderCreateSerializer,
+    responses={
+        201: OrderDetailSerializer,
+        400: OpenApiResponse(description="Validation error (insufficient stock, invalid address, etc.)"),
+        401: OpenApiResponse(description="Authentication required"),
+        403: OpenApiResponse(description="Insufficient permissions"),
+    },
+)
+def create(self, request, *args, **kwargs):
+    ...
+\`\`\`
+
+### Enum and Choice Fields
+
+**Use \`@extend_schema_field\` for custom field types:**
+\`\`\`python
+from drf_spectacular.utils import extend_schema_field
+from drf_spectacular.types import OpenApiTypes
+
+@extend_schema_field(OpenApiTypes.STR)
+class ColorField(serializers.Field):
+    ...
+\`\`\`
+
+### Polymorphic / Union Responses
+
+\`\`\`python
+from drf_spectacular.utils import PolymorphicProxySerializer
+
+@extend_schema(
+    responses=PolymorphicProxySerializer(
+        component_name='Notification',
+        serializers={
+            'email': EmailNotificationSerializer,
+            'sms': SmsNotificationSerializer,
+            'push': PushNotificationSerializer,
+        },
+        resource_type_field_name='type',
+    )
+)
+def list(self, request):
+    ...
+\`\`\`
+
+### Pagination in Schema
+
+drf-spectacular auto-wraps list responses with pagination. If using custom pagination:
+\`\`\`python
+from drf_spectacular.utils import extend_schema
+
+@extend_schema(
+    summary="List items",
+    responses=ItemSerializer(many=True),  # Pagination wrapper is auto-applied
+)
+def list(self, request, *args, **kwargs):
+    ...
+\`\`\`
+
+### Tags for Grouping
+
+**Group endpoints by feature using tags:**
+\`\`\`python
+@extend_schema_view(
+    list=extend_schema(tags=['Orders']),
+    create=extend_schema(tags=['Orders']),
+    retrieve=extend_schema(tags=['Orders']),
+)
+class OrderViewSet(ModelViewSet):
+    ...
+\`\`\`
+
+Or set a default tag via \`SPECTACULAR_SETTINGS\`:
+\`\`\`python
+SPECTACULAR_SETTINGS = {
+    'TAGS': [
+        {'name': 'Auth', 'description': 'Authentication endpoints'},
+        {'name': 'Orders', 'description': 'Order management'},
+        {'name': 'Products', 'description': 'Product catalog'},
+    ],
+}
+\`\`\`
+
+### Authentication in Schema
+
+\`\`\`python
+SPECTACULAR_SETTINGS = {
+    'SECURITY': [{'jwtAuth': []}],
+    'APPEND_COMPONENTS': {
+        'securitySchemes': {
+            'jwtAuth': {
+                'type': 'http',
+                'scheme': 'bearer',
+                'bearerFormat': 'JWT',
+            }
+        }
+    },
+}
+\`\`\`
+
+### Excluding Endpoints
+
+\`\`\`python
+@extend_schema(exclude=True)
+@action(detail=False, methods=['get'])
+def internal_health_check(self, request):
+    ...
+\`\`\`
+
+### Generating and Validating the Schema
+
+\`\`\`bash
+# Generate schema file
+./venv/bin/python manage.py spectacular --file schema.yml
+
+# Validate schema for errors
+./venv/bin/python manage.py spectacular --validate
+\`\`\`
+
+> **Always run \`--validate\` after adding new endpoints.** Fix any warnings before committing.
+
+### Rules
+
+1. **Every ViewSet** must have \`@extend_schema_view\` with summaries for all actions
+2. **Every custom \`@action\`** must have its own \`@extend_schema\` decorator
+3. **Every serializer field** that isn't self-explanatory must have \`help_text\`
+4. **Request and response serializers** must be explicitly declared \u2014 do not rely on auto-detection for non-trivial endpoints
+5. **All error responses** (400, 401, 403, 404) should be documented with \`OpenApiResponse\`
+6. **Run \`manage.py spectacular --validate\`** before committing to catch schema issues early
+7. **Use examples** (\`OpenApiExample\`) for complex request/response bodies
+8. **Group endpoints with tags** to keep Swagger UI organized
+`;
+  }
+};
+
+// src/skills/react.ts
+var reactSkill = {
+  id: "react",
+  name: "React Frontend Conventions",
+  description: "Tech stack, project structure, state management, component patterns, styling, and testing for the React frontend.",
+  render(_ctx) {
+    return `## React Frontend Conventions
+
+### Tech Stack
+- React 19 + TypeScript (strict mode)
+- Vite for bundling and dev server
+- TanStack React Query for server state management
+- React Router v7 for client-side routing
+- React Hook Form + Zod for forms and validation
+- Tailwind CSS for styling
+- \`@hey-api/openapi-ts\` for auto-generating API client from Django's OpenAPI schema
+- \`lucide-react\` for icons
+
+### API Layer
+- Auto-generated client in \`frontend/src/api/generated/\` \u2014 **never edit these files manually**
+- Custom API configuration (base URL, interceptors, auth headers) in \`frontend/src/api/client.ts\`
+- Query client setup and default options in \`frontend/src/api/query-client.ts\`
+- After any backend API change, run \`blacksmith sync\` to regenerate the client
+
+### Project Structure
+- See the \`page-structure\` skill for page folders, feature modules, routing, and route composition conventions
+- Shared, cross-feature code lives in \`frontend/src/shared/\`
+
+### State Management
+- **Server state**: TanStack React Query \u2014 see the \`react-query\` skill for full conventions on \`useApiQuery\` and \`useApiMutation\`
+- **Form state**: React Hook Form \u2014 manages form values, validation, submission
+- **Local UI state**: React \`useState\` / \`useReducer\` for component-scoped state
+- Avoid global state libraries unless there is a clear cross-cutting concern not covered by React Query
+
+### Component Patterns
+- Use functional components with named exports (not default exports for components)
+- Co-locate component, hook, and type in the same feature directory
+- Keep components focused \u2014 extract sub-components when a file exceeds ~150 lines
+- Use custom hooks to encapsulate data fetching and mutation logic
+- Prefer composition over prop drilling \u2014 use context for deeply shared state
+- **Pages must be thin orchestrators** \u2014 break into child components in \`components/\`, extract logic into \`hooks/\`. See the \`page-structure\` skill for the full pattern
+
+### UI Components
+- **All UI must use \`@blacksmith-ui/react\` components** \u2014 see the \`blacksmith-ui-react\` skill for the full component list
+- Use \`Stack\`, \`Flex\`, \`Grid\`, \`Box\` for layout \u2014 never raw \`<div>\` with flex/grid classes
+- Use \`Typography\` and \`Text\` for headings and text \u2014 never raw \`<h1>\`\u2013\`<h6>\` or \`<p>\`
+- Use \`Divider\` instead of \`<Separator>\` or \`<hr>\`
+- Use \`StatCard\`, \`EmptyState\`, \`Skeleton\` instead of building custom equivalents
+
+### Route Paths
+- All route paths live in the \`Path\` enum at \`src/router/paths.ts\` \u2014 **never hardcode path strings**
+- Use \`Path\` in route definitions, \`navigate()\`, and \`<Link to={}>\`
+- Use \`buildPath()\` for dynamic segments \u2014 see the \`page-structure\` skill for details
+
+### Styling
+- Use Tailwind CSS utility classes for all styling
+- Use the \`cn()\` helper (from \`clsx\` + \`tailwind-merge\`) for conditional and merged classes
+- Theming via HSL CSS variables defined in \`frontend/src/styles/globals.css\`
+- Dark mode is supported via the \`class\` strategy on \`<html>\`
+- Use responsive prefixes (\`sm:\`, \`md:\`, \`lg:\`) for responsive layouts
+- Avoid inline \`style\` attributes \u2014 use Tailwind classes instead
+
+### Path Aliases
+- \`@/\` maps to \`frontend/src/\`
+- Always use the alias for imports: \`import { useAuth } from '@/features/auth'\`
+- Never use relative paths that go up more than one level (\`../../\`)
+
+### Error Handling
+- Use React Error Boundary (\`frontend/src/router/error-boundary.tsx\`) for render errors
+- API errors are handled by \`useApiQuery\` / \`useApiMutation\` \u2014 see the \`react-query\` skill for error display patterns
+- Display user-facing errors using the project's feedback components (Alert, Toast)
+
+### Testing
+- Run all tests: \`cd frontend && npm test\`
+- Run a specific test: \`cd frontend && npm test -- --grep "test name"\`
+- Test files live alongside the code they test (\`component.test.tsx\`)
+`;
+  }
+};
+
+// src/skills/react-query.ts
+var reactQuerySkill = {
+  id: "react-query",
+  name: "TanStack React Query",
+  description: "API data fetching conventions using useApiQuery and useApiMutation wrappers.",
+  render(_ctx) {
+    return `## TanStack React Query \u2014 API Data Fetching
+
+> **RULE: Always use \`useApiQuery\` and \`useApiMutation\` instead of raw \`useQuery\` / \`useMutation\`.**
+> These wrappers live in \`@/shared/hooks/\` and handle DRF error parsing, smart retry, and cache invalidation automatically.
+
+### Queries \u2014 \`useApiQuery\`
+
+Import: \`import { useApiQuery } from '@/shared/hooks/use-api-query'\`
+
+Wraps \`useQuery\` with:
+- **Smart retry** \u2014 skips 400, 401, 403, 404, 405, 409, 422 (retries others up to 2 times)
+- **Parsed errors** \u2014 \`errorMessage\` (string) and \`apiError\` (structured) derived from \`result.error\`
+
+\`\`\`tsx
+// Basic list query using generated options
+import { postsListOptions } from '@/api/generated/@tanstack/react-query.gen'
+
+const { data, isLoading, errorMessage } = useApiQuery({
+  ...postsListOptions({ query: { page: 1 } }),
+})
+
+// With select to transform data
+const { data, errorMessage } = useApiQuery({
+  ...postsListOptions({ query: { page: 1 } }),
+  select: (data: any) => ({
+    posts: data.results ?? [],
+    total: data.count ?? 0,
+  }),
+})
+
+// Detail query
+import { postsRetrieveOptions } from '@/api/generated/@tanstack/react-query.gen'
+
+const { data: post, isLoading, errorMessage } = useApiQuery({
+  ...postsRetrieveOptions({ path: { id: Number(id) } }),
+})
+
+// Conditional query (skip until id is available)
+const { data } = useApiQuery({
+  ...postsRetrieveOptions({ path: { id: Number(id) } }),
+  enabled: !!id,
+})
+\`\`\`
+
+**Return type extends \`UseQueryResult\` with:**
+| Field | Type | Description |
+|-------|------|-------------|
+| \`errorMessage\` | \`string \\| null\` | Human-readable error message |
+| \`apiError\` | \`ApiError \\| null\` | Structured error with \`status\`, \`message\`, \`fieldErrors\` |
+
+### Mutations \u2014 \`useApiMutation\`
+
+Import: \`import { useApiMutation } from '@/shared/hooks/use-api-mutation'\`
+
+Wraps \`useMutation\` with:
+- **DRF error parsing** \u2014 \`fieldErrors\`, \`errorMessage\`, \`apiError\` derived from \`mutation.error\` (no local state)
+- **Cache invalidation** \u2014 pass \`invalidateKeys\` to auto-invalidate queries on success
+
+\`\`\`tsx
+// Create mutation with cache invalidation
+import {
+  postsCreateMutation,
+  postsListQueryKey,
+} from '@/api/generated/@tanstack/react-query.gen'
+
+const createPost = useApiMutation({
+  ...postsCreateMutation(),
+  invalidateKeys: [postsListQueryKey()],
+})
+
+// Trigger the mutation
+createPost.mutate({ body: { title: 'Hello', content: '...' } })
+
+// Update mutation \u2014 invalidate both list and detail caches
+import {
+  postsUpdateMutation,
+  postsRetrieveQueryKey,
+} from '@/api/generated/@tanstack/react-query.gen'
+
+const updatePost = useApiMutation({
+  ...postsUpdateMutation(),
+  invalidateKeys: [
+    postsListQueryKey(),
+    postsRetrieveQueryKey({ path: { id } }),
+  ],
+})
+
+// Delete with async/await
+const deletePost = useApiMutation({
+  ...postsDestroyMutation(),
+  invalidateKeys: [postsListQueryKey()],
+})
+
+const handleDelete = async () => {
+  await deletePost.mutateAsync({ path: { id: Number(id) } })
+  navigate('/posts')
+}
+\`\`\`
+
+**Return type extends \`UseMutationResult\` with:**
+| Field | Type | Description |
+|-------|------|-------------|
+| \`fieldErrors\` | \`Record<string, string[]>\` | Per-field validation errors from DRF |
+| \`errorMessage\` | \`string \\| null\` | General error message |
+| \`apiError\` | \`ApiError \\| null\` | Full structured error |
+
+### Error Display Patterns
+
+\`\`\`tsx
+// General error banner
+{mutation.errorMessage && (
+  <Alert variant="destructive">
+    <AlertDescription>{mutation.errorMessage}</AlertDescription>
+  </Alert>
+)}
+
+// Inline field errors in forms
+const getFieldError = (field: string): string | undefined => {
+  // Client-side (react-hook-form) errors take priority
+  const clientError = form.formState.errors[field]?.message
+  if (clientError) return clientError
+  // Fall back to server-side field errors
+  return mutation.fieldErrors[field]?.[0]
+}
+
+// Query error on a page
+const { data, isLoading, errorMessage } = useApiQuery({ ... })
+
+if (errorMessage) {
+  return (
+    <Alert variant="destructive">
+      <AlertDescription>{errorMessage}</AlertDescription>
+    </Alert>
+  )
+}
+\`\`\`
+
+### Creating Resource Hook Files
+
+When building hooks for a resource, create two files:
+
+**\`use-<resources>.ts\`** \u2014 List query hook:
+\`\`\`tsx
+import { useApiQuery } from '@/shared/hooks/use-api-query'
+import { postsListOptions } from '@/api/generated/@tanstack/react-query.gen'
+
+interface UsePostsParams {
+  page?: number
+  search?: string
+  ordering?: string
+}
+
+export function usePosts(params: UsePostsParams = {}) {
+  return useApiQuery({
+    ...postsListOptions({
+      query: {
+        page: params.page ?? 1,
+        search: params.search,
+        ordering: params.ordering ?? '-created_at',
+      },
+    }),
+    select: (data: any) => ({
+      posts: data.results ?? [],
+      total: data.count ?? 0,
+      hasNext: !!data.next,
+      hasPrev: !!data.previous,
+    }),
+  })
+}
+\`\`\`
+
+**\`use-<resource>-mutations.ts\`** \u2014 Create/update/delete hooks:
+\`\`\`tsx
+import { useApiMutation } from '@/shared/hooks/use-api-mutation'
+import {
+  postsCreateMutation,
+  postsUpdateMutation,
+  postsDestroyMutation,
+  postsListQueryKey,
+  postsRetrieveQueryKey,
+} from '@/api/generated/@tanstack/react-query.gen'
+
+export function useCreatePost() {
+  return useApiMutation({
+    ...postsCreateMutation(),
+    invalidateKeys: [postsListQueryKey()],
+  })
+}
+
+export function useUpdatePost(id: number) {
+  return useApiMutation({
+    ...postsUpdateMutation(),
+    invalidateKeys: [
+      postsListQueryKey(),
+      postsRetrieveQueryKey({ path: { id } }),
+    ],
+  })
+}
+
+export function useDeletePost() {
+  return useApiMutation({
+    ...postsDestroyMutation(),
+    invalidateKeys: [postsListQueryKey()],
+  })
+}
+\`\`\`
+
+### Key Rules
+
+1. **Never use raw \`useQuery\` or \`useMutation\`** \u2014 always go through \`useApiQuery\` / \`useApiMutation\`
+2. **Never manage API error state with \`useState\`** \u2014 error state is derived from TanStack Query's \`error\` field
+3. **Always pass \`invalidateKeys\`** on mutations that modify data \u2014 ensures the UI stays in sync
+4. **Use generated options/mutations** from \`@/api/generated/@tanstack/react-query.gen\` \u2014 never write \`queryFn\` manually
+5. **Use \`select\`** to reshape API responses at the hook level, not in components
+6. **Use \`enabled\`** for conditional queries (e.g. waiting for an ID from URL params)
+7. **Spread generated options first** (\`...postsListOptions()\`), then add overrides \u2014 this preserves the generated \`queryKey\` and \`queryFn\`
+`;
+  }
+};
+
+// src/skills/page-structure.ts
+var pageStructureSkill = {
+  id: "page-structure",
+  name: "Page & Route Structure",
+  description: "Page folders, feature modules, routing conventions, and route composition patterns.",
+  render(_ctx) {
+    return `## Page & Route Structure
+
+> **RULE: Every page and feature owns its own \`routes.tsx\`. The central router only composes them \u2014 never import page components directly into \`routes.tsx\`.**
+
+### Standalone Pages (\`src/pages/\`)
+
+Each page gets its own folder:
+
+\`\`\`
+pages/<page>/
+\u251C\u2500\u2500 <page>.tsx         # Page component (default export)
+\u251C\u2500\u2500 routes.tsx         # Exports RouteObject[] for this page
+\u251C\u2500\u2500 index.ts           # Re-exports public members (routes)
+\u251C\u2500\u2500 components/        # Components private to this page (optional)
+\u2514\u2500\u2500 hooks/             # Hooks private to this page (optional)
+\`\`\`
+
+**\`routes.tsx\`** \u2014 defines the route config using the \`Path\` enum:
+\`\`\`tsx
+import type { RouteObject } from 'react-router-dom'
+import { Path } from '@/router/paths'
+import SettingsPage from './settings'
+
+export const settingsRoutes: RouteObject[] = [
+  { path: Path.Settings, element: <SettingsPage /> },
+]
+\`\`\`
+
+**\`index.ts\`** \u2014 re-exports only public members:
+\`\`\`ts
+export { settingsRoutes } from './routes'
+\`\`\`
+
+### Feature Pages (\`src/features/\`)
+
+Features that have pages include a \`routes.tsx\` at the feature root:
+
+\`\`\`
+features/<feature>/
+\u251C\u2500\u2500 components/        # UI components scoped to this feature
+\u251C\u2500\u2500 hooks/             # Custom hooks (queries, mutations, logic)
+\u251C\u2500\u2500 pages/             # Page components (default exports)
+\u251C\u2500\u2500 routes.tsx         # RouteObject[] for all pages in this feature
+\u2514\u2500\u2500 index.ts           # Re-exports routes + public API
+\`\`\`
+
+**\`routes.tsx\`** \u2014 groups related routes using the \`Path\` enum:
+\`\`\`tsx
+import { Outlet, type RouteObject } from 'react-router-dom'
+import { Path } from '@/router/paths'
+import PostsPage from './pages/posts-page'
+import PostDetailPage from './pages/post-detail-page'
+
+export const postsRoutes: RouteObject[] = [
+  {
+    path: Path.Posts,
+    element: <Outlet />,
+    children: [
+      { index: true, element: <PostsPage /> },
+      { path: ':id', element: <PostDetailPage /> },
+    ],
+  },
+]
+\`\`\`
+
+**\`index.ts\`** \u2014 exports routes first:
+\`\`\`ts
+export { postsRoutes } from './routes'
+export { usePosts } from './hooks/use-posts'
+export { useCreatePost, useUpdatePost, useDeletePost } from './hooks/use-post-mutations'
+\`\`\`
+
+### Route Paths (\`src/router/paths.ts\`)
+
+All route paths are defined in a central \`Path\` enum \u2014 **never use hardcoded path strings**:
+
+\`\`\`ts
+export enum Path {
+  Home = '/',
+  Login = '/login',
+  Register = '/register',
+  ForgotPassword = '/forgot-password',
+  ResetPassword = '/reset-password/:token',
+  Dashboard = '/dashboard',
+  // blacksmith:path
+}
+\`\`\`
+
+Use \`Path\` everywhere \u2014 in route definitions, \`navigate()\`, \`<Link to={}\`\`, etc.:
+\`\`\`tsx
+import { Path } from '@/router/paths'
+
+// In routes
+{ path: Path.Dashboard, element: <DashboardPage /> }
+
+// In navigation
+navigate(Path.Login)
+<Link to={Path.Home}>Home</Link>
+\`\`\`
+
+For dynamic paths, use the \`buildPath\` helper:
+\`\`\`ts
+import { Path, buildPath } from '@/router/paths'
+
+buildPath(Path.ResetPassword, { token: 'abc123' })
+// => '/reset-password/abc123'
+\`\`\`
+
+The \`Path\` enum is re-exported from \`@/router\` along with \`buildPath\`.
+
+### Central Router (\`src/router/routes.tsx\`)
+
+The central router imports and spreads route arrays \u2014 it never imports page components directly:
+
+\`\`\`tsx
+import { homeRoutes } from '@/pages/home'
+import { dashboardRoutes } from '@/pages/dashboard'
+import { authRoutes } from '@/features/auth'
+import { postsRoutes } from '@/features/posts'
+// blacksmith:import
+
+const publicRoutes: RouteObject[] = [
+  ...homeRoutes,
+]
+
+const privateRoutes: RouteObject[] = [
+  ...dashboardRoutes,
+  ...postsRoutes,
+  // blacksmith:routes
+]
+\`\`\`
+
+### Auto-Registration
+
+\`blacksmith make:resource\` automatically registers routes using marker comments:
+- \`// blacksmith:path\` \u2014 new \`Path\` enum entry is inserted above this marker in \`paths.ts\`
+- \`// blacksmith:import\` \u2014 new import line is inserted above this marker in \`routes.tsx\`
+- \`// blacksmith:routes\` \u2014 new spread line is inserted above this marker in \`routes.tsx\`
+
+Never remove these markers. They must stay in the \`Path\` enum, \`privateRoutes\` array, and import block.
+
+### When to Use Pages vs Features
+
+| Use \`pages/<page>/\` | Use \`features/<feature>/\` |
+|---|---|
+| Standalone pages (home, dashboard, settings) | CRUD resources with multiple pages |
+| No shared hooks or components | Has hooks, components, and pages that belong together |
+| Single route | Multiple related routes (list + detail + edit) |
+
+### Component Decomposition
+
+> **RULE: Pages are orchestrators, not monoliths. Break every page into small, focused child components stored in \`components/\`.**
+
+A page component should read data (via hooks), pass it down as props, and compose child components. It should contain minimal JSX itself.
+
+\`\`\`
+pages/dashboard/
+\u251C\u2500\u2500 dashboard.tsx              # Page: composes children, calls hooks
+\u251C\u2500\u2500 components/
+\u2502   \u251C\u2500\u2500 stats-cards.tsx        # Renders the stats grid
+\u2502   \u251C\u2500\u2500 recent-activity.tsx    # Renders activity feed
+\u2502   \u2514\u2500\u2500 quick-actions.tsx      # Renders action buttons
+\u251C\u2500\u2500 hooks/
+\u2502   \u2514\u2500\u2500 use-dashboard-data.ts  # All data fetching for this page
+\u251C\u2500\u2500 routes.tsx
+\u2514\u2500\u2500 index.ts
+\`\`\`
+
+\`\`\`tsx
+// dashboard.tsx \u2014 thin orchestrator using @blacksmith-ui/react layout
+import { Stack, Grid, Divider } from '@blacksmith-ui/react'
+import { StatsCards } from './components/stats-cards'
+import { RecentActivity } from './components/recent-activity'
+import { QuickActions } from './components/quick-actions'
+import { useDashboardData } from './hooks/use-dashboard-data'
+
+export default function DashboardPage() {
+  const { stats, activity, isLoading } = useDashboardData()
+
+  return (
+    <Stack gap={6}>
+      <StatsCards stats={stats} isLoading={isLoading} />
+      <Divider />
+      <Grid columns={{ base: 1, lg: 3 }} gap={6}>
+        <RecentActivity items={activity} isLoading={isLoading} className="lg:col-span-2" />
+        <QuickActions />
+      </Grid>
+    </Stack>
+  )
+}
+\`\`\`
+
+**When to extract a child component:**
+- A section of JSX exceeds ~30 lines
+- A block has its own loading/error state
+- A block is logically independent (e.g. a table, a form, a sidebar)
+- A block could be reused on another page (move to \`shared/\` or the feature's \`components/\`)
+
+**When NOT to extract:**
+- A few lines of simple, static markup (headings, wrappers)
+- Extracting would just move props through another layer with no clarity gain
+
+### Separating Logic into Hooks
+
+> **RULE: Components render. Hooks think. Never mix data fetching, transformations, or complex state logic into component bodies.**
+
+Extract logic into hooks in the \`hooks/\` folder co-located with the page or feature:
+
+\`\`\`tsx
+// BAD \u2014 logic mixed into the component
+export default function OrdersPage() {
+  const [page, setPage] = useState(1)
+  const [search, setSearch] = useState('')
+  const debouncedSearch = useDebounce(search, 300)
+  const { data, isLoading } = useApiQuery({
+    ...ordersListOptions({ query: { page, search: debouncedSearch } }),
+    select: (d: any) => ({ orders: d.results ?? [], total: d.count ?? 0 }),
+  })
+
+  const deleteOrder = useApiMutation({
+    ...ordersDestroyMutation(),
+    invalidateKeys: [ordersListQueryKey()],
+  })
+
+  return ( /* 200 lines of JSX using all of the above */ )
+}
+\`\`\`
+
+\`\`\`tsx
+// GOOD \u2014 logic in a hook, component just renders
+// hooks/use-orders-page.ts
+export function useOrdersPage() {
+  const [page, setPage] = useState(1)
+  const [search, setSearch] = useState('')
+  const debouncedSearch = useDebounce(search, 300)
+
+  const { data, isLoading, errorMessage } = useOrders({
+    page,
+    search: debouncedSearch,
+  })
+
+  const deleteOrder = useDeleteOrder()
+
+  return { orders: data?.orders ?? [], total: data?.total ?? 0, isLoading, errorMessage, page, setPage, search, setSearch, deleteOrder }
+}
+
+// orders-page.tsx
+import { Stack } from '@blacksmith-ui/react'
+import { useOrdersPage } from './hooks/use-orders-page'
+import { OrdersTable } from './components/orders-table'
+import { OrdersToolbar } from './components/orders-toolbar'
+
+export default function OrdersPage() {
+  const { orders, total, isLoading, page, setPage, search, setSearch, deleteOrder } = useOrdersPage()
+
+  return (
+    <Stack gap={4}>
+      <OrdersToolbar search={search} onSearchChange={setSearch} />
+      <OrdersTable orders={orders} isLoading={isLoading} onDelete={(id) => deleteOrder.mutate({ path: { id } })} />
+    </Stack>
+  )
+}
+\`\`\`
+
+**What goes into a hook:**
+- API queries and mutations
+- Derived/computed state
+- Debouncing, pagination, filtering logic
+- Form setup (\`useForm\`, schema, submit handler)
+- Any \`useEffect\` or \`useState\` beyond a simple UI toggle
+
+**What stays in the component:**
+- Simple UI toggles (\`useState\` for a modal open/close is fine inline)
+- JSX composition and prop passing
+- Event handler wiring (calling \`hook.mutate()\`, \`navigate()\`, etc.)
+
+### Key Rules
+
+1. **Every page/feature owns its routes** \u2014 the route config lives next to the page, not in the central router
+2. **Use the \`Path\` enum for all route paths** \u2014 never hardcode path strings; import \`Path\` from \`@/router/paths\`
+3. **\`index.ts\` is the public API** \u2014 only export what other modules need (routes, hooks, components)
+4. **Page components use default exports** \u2014 this is the one exception to the named-export convention
+5. **Routes use named exports** \u2014 \`export const settingsRoutes\` not \`export default\`
+6. **Private components/hooks stay in the page folder** \u2014 if only one page uses it, co-locate it there
+7. **Never import across page folders** \u2014 if something is shared, move it to \`shared/\` or a feature
+8. **Keep marker comments intact** \u2014 \`// blacksmith:path\`, \`// blacksmith:import\`, and \`// blacksmith:routes\` are required for auto-registration
+9. **Pages are orchestrators** \u2014 break pages into child components in \`components/\`, extract logic into hooks in \`hooks/\`
+10. **Components render, hooks think** \u2014 never put data fetching, transformations, or complex state directly in component bodies
+`;
+  }
+};
+
+// src/skills/blacksmith-ui-react.ts
+var blacksmithUiReactSkill = {
+  id: "blacksmith-ui-react",
+  name: "@blacksmith-ui/react",
+  description: "Core UI component library \u2014 60+ components for layout, typography, inputs, data display, overlays, feedback, media, and navigation.",
+  render(_ctx) {
+    return `## @blacksmith-ui/react \u2014 Core UI Components (60+)
+
+> **CRITICAL RULE: Every UI element MUST be built using \`@blacksmith-ui/react\` components \u2014 including layout and typography.**
+> Do NOT use raw HTML elements when a Blacksmith-UI component exists for that purpose.
+> This includes layout: use \`Flex\`, \`Stack\`, \`Grid\`, \`Box\`, \`Container\` instead of \`<div>\` with flex/grid classes.
+> This includes typography: use \`Text\` and \`Typography\` instead of raw \`<h1>\`\u2013\`<h6>\`, \`<p>\`, \`<span>\`.
+
+### Layout
+
+| Component | Use instead of | Description |
+|-----------|---------------|-------------|
+| \`Box\` | \`<div>\` | Base layout primitive with style props |
+| \`Flex\` | \`<div className="flex ...">\` | Flexbox container with style props (\`direction\`, \`align\`, \`justify\`, \`gap\`, \`wrap\`) |
+| \`Grid\` | \`<div className="grid ...">\` | CSS Grid container (\`columns\`, \`rows\`, \`gap\`) |
+| \`Stack\` | \`<div className="flex flex-col gap-...">\` | Vertical/horizontal stack (\`direction\`, \`gap\`) |
+| \`Container\` | \`<div className="max-w-7xl mx-auto px-...">\` | Max-width centered container |
+| \`Divider\` | \`<hr>\` or border hacks | Visual separator (horizontal/vertical) |
+| \`AspectRatio\` | padding-bottom trick | Maintain aspect ratio for content |
+| \`Resizable\` | custom resize logic | Resizable panel groups |
+| \`ScrollArea\` | \`overflow-auto\` divs | Custom scrollbar container |
+
+### Typography
+
+| Component | Use instead of | Description |
+|-----------|---------------|-------------|
+| \`Text\` | \`<p>\`, \`<span>\` | Text display with style props (\`size\`, \`weight\`, \`color\`, \`align\`) |
+| \`Typography\` | \`<h1>\`\u2013\`<h6>\`, \`<p>\` | Semantic heading/paragraph elements (\`variant\`: h1\u2013h6, p, lead, muted, etc.) |
+| \`Label\` | \`<label>\` | Form label with accessibility support |
+
+### Cards & Containers
+
+- \`Card\`, \`CardHeader\`, \`CardTitle\`, \`CardDescription\`, \`CardContent\`, \`CardFooter\` \u2014 Use instead of styled \`<div>\` containers
+- \`StatCard\` \u2014 Use for metric/stat display (value, label, trend)
+- \`EmptyState\` \u2014 Use for empty content placeholders instead of custom empty divs
+
+### Actions
+
+- \`Button\` \u2014 Use instead of \`<button>\` or \`<a>\` styled as buttons
+  - Variants: \`default\`, \`secondary\`, \`destructive\`, \`outline\`, \`ghost\`, \`link\`
+  - Sizes: \`sm\`, \`default\`, \`lg\`, \`icon\`
+- \`Toggle\`, \`ToggleGroup\` \u2014 Use for toggle buttons
+- \`DropdownMenu\`, \`DropdownMenuTrigger\`, \`DropdownMenuContent\`, \`DropdownMenuItem\`, \`DropdownMenuSeparator\`, \`DropdownMenuLabel\` \u2014 Use for action menus
+- \`ContextMenu\` \u2014 Use for right-click menus
+- \`Menubar\` \u2014 Use for application menu bars
+- \`AlertDialog\`, \`AlertDialogTrigger\`, \`AlertDialogContent\`, \`AlertDialogAction\`, \`AlertDialogCancel\` \u2014 Use for destructive action confirmations
+
+### Data Entry
+
+- \`Input\` \u2014 Use instead of \`<input>\`
+- \`SearchInput\` \u2014 Use for search fields (has built-in search icon)
+- \`Textarea\` \u2014 Use instead of \`<textarea>\`
+- \`NumberInput\` \u2014 Use for numeric inputs with increment/decrement
+- \`Select\`, \`SelectTrigger\`, \`SelectContent\`, \`SelectItem\`, \`SelectValue\` \u2014 Use instead of \`<select>\`
+- \`Checkbox\` \u2014 Use instead of \`<input type="checkbox">\`
+- \`RadioGroup\`, \`RadioGroupItem\` \u2014 Use instead of \`<input type="radio">\`
+- \`Switch\` \u2014 Use for toggle switches
+- \`Slider\` \u2014 Use for single range inputs
+- \`RangeSlider\` \u2014 Use for dual-handle range selection
+- \`DatePicker\` \u2014 Use for date selection with calendar popup
+- \`PinInput\` / \`InputOTP\` \u2014 Use for PIN/OTP code entry
+- \`ColorPicker\` \u2014 Use for color selection
+- \`FileUpload\` \u2014 Use for file upload with drag & drop
+- \`TagInput\` \u2014 Use for tag/chip input with add/remove
+- \`Rating\` \u2014 Use for star/icon rating selection
+- \`Label\` \u2014 Use instead of \`<label>\`
+
+### Data Display
+
+- \`Table\`, \`TableHeader\`, \`TableBody\`, \`TableRow\`, \`TableHead\`, \`TableCell\` \u2014 Use instead of \`<table>\` elements
+- \`DataTable\` \u2014 Use for feature-rich tables with sorting, filtering, and pagination
+- \`Badge\` \u2014 Use for status indicators, tags, counts (variants: \`default\`, \`secondary\`, \`destructive\`, \`outline\`)
+- \`Avatar\`, \`AvatarImage\`, \`AvatarFallback\` \u2014 Use for user profile images
+- \`Tooltip\`, \`TooltipTrigger\`, \`TooltipContent\`, \`TooltipProvider\` \u2014 Use for hover hints
+- \`HoverCard\` \u2014 Use for rich hover content
+- \`Calendar\` \u2014 Use for full calendar display
+- \`Chart\` \u2014 Use for data visualization (powered by Recharts)
+- \`Timeline\` \u2014 Use for chronological event display
+- \`Tree\` \u2014 Use for hierarchical tree views
+- \`List\` \u2014 Use for structured list display instead of \`<ul>\`/\`<ol>\`
+- \`Skeleton\` \u2014 Use for loading placeholders
+- \`Spinner\` \u2014 Use for loading indicators
+- \`Progress\` \u2014 Use for progress bars
+- \`Pagination\`, \`PaginationContent\`, \`PaginationItem\`, \`PaginationLink\`, \`PaginationNext\`, \`PaginationPrevious\` \u2014 Use for paginated lists
+
+### Tabs & Accordion
+
+- \`Tabs\`, \`TabsList\`, \`TabsTrigger\`, \`TabsContent\` \u2014 Use for tabbed interfaces
+- \`Accordion\`, \`AccordionItem\`, \`AccordionTrigger\`, \`AccordionContent\` \u2014 Use for collapsible sections
+
+### Overlays
+
+- \`Dialog\`, \`DialogTrigger\`, \`DialogContent\`, \`DialogHeader\`, \`DialogTitle\`, \`DialogDescription\`, \`DialogFooter\` \u2014 Use for modals
+- \`AlertDialog\` \u2014 Use for confirmation dialogs
+- \`Drawer\` / \`Sheet\`, \`SheetTrigger\`, \`SheetContent\`, \`SheetHeader\`, \`SheetTitle\`, \`SheetDescription\` \u2014 Use for slide-out panels
+- \`Popover\` \u2014 Use for floating content panels
+- \`CommandPalette\` \u2014 Use for searchable command menus (cmdk-based)
+
+### Navigation
+
+- \`Breadcrumb\`, \`BreadcrumbList\`, \`BreadcrumbItem\`, \`BreadcrumbLink\`, \`BreadcrumbSeparator\` \u2014 Use for breadcrumb trails
+- \`NavigationMenu\`, \`NavigationMenuList\`, \`NavigationMenuItem\`, \`NavigationMenuTrigger\`, \`NavigationMenuContent\` \u2014 Use for site navigation
+- \`Sidebar\` \u2014 Use for app sidebars
+- \`Dock\` \u2014 Use for macOS-style dock navigation
+- \`BackToTop\` \u2014 Use for scroll-to-top buttons
+
+### Feedback
+
+- \`Alert\`, \`AlertTitle\`, \`AlertDescription\` \u2014 Use for inline messages/warnings
+- \`AlertBanner\` \u2014 Use for full-width alert banners
+- \`Toast\` / \`Toaster\` / \`useToast\` \u2014 Use for transient notifications
+- \`SonnerToaster\` \u2014 Sonner-based toast notifications
+
+### Media
+
+- \`Image\` \u2014 Use instead of \`<img>\` for optimized image display
+- \`VideoPlayer\` \u2014 Use for video playback
+- \`CodeBlock\` \u2014 Use for syntax-highlighted code (Shiki-powered)
+- \`Carousel\` \u2014 Use for image/content carousels
+- \`Lightbox\` \u2014 Use for full-screen media viewers
+
+### Specialized
+
+- \`Stepper\` / \`Wizard\` \u2014 Use for multi-step workflows
+- \`NotificationCenter\` / \`useNotificationCenter\` \u2014 Use for notification management
+- \`SpotlightTour\` \u2014 Use for guided feature tours
+
+### Utilities & Hooks
+
+- \`cn()\` \u2014 Merge class names (clsx + tailwind-merge)
+- \`useToast()\` \u2014 Programmatic toast notifications
+- \`useMobile()\` \u2014 Responsive breakpoint detection
+- \`useDarkMode()\` \u2014 Dark mode toggle. Returns \`{ isDark, toggle }\`
+
+---
+
+### Component-First Rules
+
+1. **Layout**: NEVER use \`<div className="flex ...">\` or \`<div className="grid ...">\`. Use \`<Flex>\`, \`<Grid>\`, \`<Stack>\`, \`<Box>\` from \`@blacksmith-ui/react\`.
+2. **Centering/max-width**: NEVER use \`<div className="max-w-7xl mx-auto px-...">\`. Use \`<Container>\`.
+3. **Typography**: NEVER use raw \`<h1>\`\u2013\`<h6>\` or \`<p>\` with Tailwind text classes. Use \`<Typography variant="h2">\` or \`<Text>\`.
+4. **Separators**: NEVER use \`<hr>\` or border hacks. Use \`<Divider>\`.
+5. **Images**: NEVER use raw \`<img>\`. Use \`<Image>\` from \`@blacksmith-ui/react\` (use \`Avatar\` for profile pictures).
+6. **Lists**: NEVER use \`<ul>\`/\`<ol>\` for structured display lists. Use \`<List>\` from \`@blacksmith-ui/react\`. Plain \`<ul>\`/\`<ol>\` is only acceptable for simple inline content lists.
+7. **Buttons**: NEVER use \`<button>\` or \`<a>\` styled as a button. Use \`<Button>\`.
+8. **Inputs**: NEVER use \`<input>\`, \`<textarea>\`, \`<select>\` directly. Use the Blacksmith-UI equivalents.
+9. **Cards**: NEVER use a styled \`<div>\` as a card. Use \`Card\` + sub-components.
+10. **Tables**: NEVER use raw \`<table>\` HTML. Use \`Table\` or \`DataTable\`.
+11. **Loading**: NEVER use custom \`animate-pulse\` divs. Use \`Skeleton\` or \`Spinner\`.
+12. **Modals**: NEVER build custom modals. Use \`Dialog\`, \`AlertDialog\`, \`Drawer\`, or \`Sheet\`.
+13. **Feedback**: NEVER use plain styled text for errors/warnings. Use \`Alert\` or \`useToast\`.
+14. **Empty states**: NEVER build custom empty-state UIs. Use \`EmptyState\`.
+15. **Metrics**: NEVER build custom stat/metric cards. Use \`StatCard\`.
+
+### When Raw HTML IS Acceptable
+
+- \`<main>\`, \`<section>\`, \`<header>\`, \`<footer>\`, \`<nav>\`, \`<article>\`, \`<aside>\` \u2014 semantic HTML landmarks for page structure (but use \`Flex\`/\`Stack\`/\`Grid\` inside them for layout)
+- \`<Link>\` from react-router-dom \u2014 for page navigation (use \`<Button asChild><Link>...</Link></Button>\` if it needs button styling)
+- Icon components from \`lucide-react\`
+- \`<form>\` element when used with React Hook Form (but use \`@blacksmith-ui/forms\` components inside)
+
+### Design Tokens & Theming
+
+- \`ThemeProvider\` \u2014 Wrap app to apply preset or custom theme
+- Built-in presets: \`default\`, \`blue\`, \`green\`, \`violet\`, \`red\`, \`neutral\`
+- All components use HSL CSS variables (\`--background\`, \`--foreground\`, \`--primary\`, etc.)
+- Dark mode: \`.dark\` class strategy on \`<html>\`, or \`<ThemeProvider mode="dark">\`
+- Border radius: controlled by \`--radius\` CSS variable
+- Extend with \`className\` prop + \`cn()\` utility for custom styles
+- Global styles: \`@import '@blacksmith-ui/react/styles.css'\` in app entry
+
+### Example: HowItWorks Section (Correct Way)
+
+\`\`\`tsx
+import { Container, Stack, Flex, Grid, Text, Typography, Image } from '@blacksmith-ui/react'
+import { howItWorksSteps } from '../data'
+
+export function HowItWorks() {
+  return (
+    <Box as="section" className="py-16 sm:py-20">
+      <Container>
+        <Stack gap={3} align="center" className="mb-12">
+          <Typography variant="h2">How It Works</Typography>
+          <Text color="muted">Book your stay in three simple steps</Text>
+        </Stack>
+
+        <Grid columns={{ base: 1, md: 3 }} gap={8} className="max-w-4xl mx-auto">
+          {howItWorksSteps.map((item) => (
+            <Stack key={item.step} align="center" gap={4}>
+              <Box className="relative">
+                <Flex align="center" justify="center" className="h-16 w-16 rounded-full bg-primary text-primary-foreground shadow-lg shadow-primary/30">
+                  <item.icon className="h-7 w-7" />
+                </Flex>
+                <Flex align="center" justify="center" className="absolute -top-1 -right-1 h-6 w-6 rounded-full bg-background border-2 border-primary">
+                  <Text size="xs" weight="bold" color="primary">{item.step}</Text>
+                </Flex>
+              </Box>
+              <Stack gap={2} align="center">
+                <Text size="lg" weight="bold">{item.title}</Text>
+                <Text size="sm" color="muted" align="center" className="max-w-xs">
+                  {item.description}
+                </Text>
+              </Stack>
+            </Stack>
+          ))}
+        </Grid>
+      </Container>
+    </Box>
+  )
+}
+\`\`\`
+
+### Example: Resource List Page (Correct Way)
+
+\`\`\`tsx
+import {
+  Stack, Flex,
+  Card, CardHeader, CardTitle, CardContent,
+  Button, Badge, Skeleton,
+  Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+  AlertDialog, AlertDialogTrigger, AlertDialogContent,
+  AlertDialogAction, AlertDialogCancel,
+} from '@blacksmith-ui/react'
+import { MoreHorizontal, Plus, Trash2, Edit } from 'lucide-react'
+import { Link } from 'react-router-dom'
+
+function ResourceListPage({ resources, isLoading, onDelete }) {
+  if (isLoading) {
+    return (
+      <Card>
+        <CardContent className="p-6">
+          <Stack gap={4}>
+            {Array.from({ length: 5 }).map((_, i) => (
+              <Skeleton key={i} className="h-12 w-full" />
+            ))}
+          </Stack>
+        </CardContent>
+      </Card>
+    )
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <Flex align="center" justify="between">
+          <CardTitle>Resources</CardTitle>
+          <Button asChild>
+            <Link to="/resources/new"><Plus className="mr-2 h-4 w-4" /> Create</Link>
+          </Button>
+        </Flex>
+      </CardHeader>
+      <CardContent>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Title</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead className="w-12" />
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {resources.map((r) => (
+              <TableRow key={r.id}>
+                <TableCell>{r.title}</TableCell>
+                <TableCell><Badge variant="outline">{r.status}</Badge></TableCell>
+                <TableCell>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <Button variant="ghost" size="icon">
+                        <MoreHorizontal className="h-4 w-4" />
+                      </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent>
+                      <DropdownMenuItem asChild>
+                        <Link to={\`/resources/\${r.id}/edit\`}>
+                          <Edit className="mr-2 h-4 w-4" /> Edit
+                        </Link>
+                      </DropdownMenuItem>
+                      <AlertDialog>
+                        <AlertDialogTrigger asChild>
+                          <DropdownMenuItem onSelect={(e) => e.preventDefault()}>
+                            <Trash2 className="mr-2 h-4 w-4" /> Delete
+                          </DropdownMenuItem>
+                        </AlertDialogTrigger>
+                        <AlertDialogContent>
+                          <AlertDialogAction onClick={() => onDelete(r.id)}>
+                            Delete
+                          </AlertDialogAction>
+                          <AlertDialogCancel>Cancel</AlertDialogCancel>
+                        </AlertDialogContent>
+                      </AlertDialog>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </CardContent>
+    </Card>
+  )
+}
+\`\`\`
+`;
+  }
+};
+
+// src/skills/blacksmith-ui-forms.ts
+var blacksmithUiFormsSkill = {
+  id: "blacksmith-ui-forms",
+  name: "@blacksmith-ui/forms",
+  description: "Form components using React Hook Form + Zod for validation and submission.",
+  render(_ctx) {
+    return `## @blacksmith-ui/forms \u2014 Form Components (React Hook Form + Zod)
+
+> **RULE: ALWAYS use these for forms.** Do NOT build forms with raw \`<form>\`, \`<input>\`, \`<label>\`, or manual error display.
+
+\`\`\`tsx
+import { Form, FormField, FormInput, FormTextarea, FormSelect } from '@blacksmith-ui/forms'
+\`\`\`
+
+### Components
+
+- \`Form\` \u2014 Wraps the entire form. Props: \`form\` (useForm instance), \`onSubmit\`
+- \`FormField\` \u2014 Wraps each field. Props: \`name\`, \`label\`, \`description?\`
+- \`FormInput\` \u2014 Text input within FormField. Props: \`type\`, \`placeholder\`
+- \`FormTextarea\` \u2014 Textarea within FormField. Props: \`rows\`, \`placeholder\`
+- \`FormSelect\` \u2014 Select within FormField. Props: \`options\`, \`placeholder\`
+- \`FormCheckbox\` \u2014 Checkbox within FormField
+- \`FormSwitch\` \u2014 Toggle switch within FormField
+- \`FormRadioGroup\` \u2014 Radio group within FormField. Props: \`options\`
+- \`FormDatePicker\` \u2014 Date picker within FormField
+- \`FormError\` \u2014 Displays field-level validation error (auto-handled by FormField)
+- \`FormDescription\` \u2014 Displays helper text below a field
+
+### Rules
+- NEVER use raw \`<form>\` with manual \`<label>\` and error \`<p>\` tags. Always use \`Form\` + \`FormField\`.
+- NEVER use \`<input>\`, \`<textarea>\`, \`<select>\` inside forms. Use \`FormInput\`, \`FormTextarea\`, \`FormSelect\`.
+
+### Form Pattern \u2014 ALWAYS follow this:
+\`\`\`tsx
+import { Form, FormField, FormInput, FormTextarea, FormSelect } from '@blacksmith-ui/forms'
+import { Button } from '@blacksmith-ui/react'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+
+const schema = z.object({
+  title: z.string().min(1, 'Title is required'),
+  description: z.string().optional(),
+  status: z.enum(['draft', 'published']),
+})
+
+type FormData = z.infer<typeof schema>
+
+function ResourceForm({ defaultValues, onSubmit, isSubmitting }: Props) {
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: { title: '', description: '', status: 'draft', ...defaultValues },
+  })
+
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <FormField name="title" label="Title">
+        <FormInput placeholder="Enter title" />
+      </FormField>
+      <FormField name="description" label="Description">
+        <FormTextarea rows={4} placeholder="Enter description" />
+      </FormField>
+      <FormField name="status" label="Status">
+        <FormSelect options={[
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+        ]} />
+      </FormField>
+      <Button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Saving...' : 'Save'}
+      </Button>
+    </Form>
+  )
+}
+\`\`\`
+
+### Example: Detail Page with Edit Dialog
+\`\`\`tsx
+import {
+  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter,
+  Button, Badge, Separator,
+  Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogFooter,
+  Alert, AlertTitle, AlertDescription,
+} from '@blacksmith-ui/react'
+import { Form, FormField, FormInput, FormTextarea } from '@blacksmith-ui/forms'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { Edit, ArrowLeft } from 'lucide-react'
+import { Link } from 'react-router-dom'
+
+const editSchema = z.object({
+  title: z.string().min(1, 'Required'),
+  description: z.string().optional(),
+})
+
+function ResourceDetailPage({ resource, onUpdate, error }) {
+  const form = useForm({
+    resolver: zodResolver(editSchema),
+    defaultValues: { title: resource.title, description: resource.description },
+  })
+
+  return (
+    <Card>
+      <CardHeader>
+        <div className="flex items-center justify-between">
+          <div>
+            <CardTitle>{resource.title}</CardTitle>
+            <CardDescription>Created {new Date(resource.created_at).toLocaleDateString()}</CardDescription>
+          </div>
+          <div className="flex gap-2">
+            <Button variant="outline" asChild>
+              <Link to="/resources"><ArrowLeft className="mr-2 h-4 w-4" /> Back</Link>
+            </Button>
+            <Dialog>
+              <DialogTrigger asChild>
+                <Button><Edit className="mr-2 h-4 w-4" /> Edit</Button>
+              </DialogTrigger>
+              <DialogContent>
+                <DialogHeader>
+                  <DialogTitle>Edit Resource</DialogTitle>
+                </DialogHeader>
+                <Form form={form} onSubmit={onUpdate}>
+                  <FormField name="title" label="Title">
+                    <FormInput />
+                  </FormField>
+                  <FormField name="description" label="Description">
+                    <FormTextarea rows={4} />
+                  </FormField>
+                  <DialogFooter>
+                    <Button type="submit">Save Changes</Button>
+                  </DialogFooter>
+                </Form>
+              </DialogContent>
+            </Dialog>
+          </div>
+        </div>
+      </CardHeader>
+      <Separator />
+      <CardContent className="pt-6">
+        {error && (
+          <Alert variant="destructive" className="mb-4">
+            <AlertTitle>Error</AlertTitle>
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
+        )}
+        <p>{resource.description || 'No description provided.'}</p>
+      </CardContent>
+      <CardFooter>
+        <Badge>{resource.status}</Badge>
+      </CardFooter>
+    </Card>
+  )
+}
+\`\`\`
+`;
+  }
+};
+
+// src/skills/blacksmith-ui-auth.ts
+var blacksmithUiAuthSkill = {
+  id: "blacksmith-ui-auth",
+  name: "@blacksmith-ui/auth",
+  description: "Authentication UI components and hooks for login, registration, and password reset.",
+  render(_ctx) {
+    return `## @blacksmith-ui/auth \u2014 Authentication UI
+
+> **RULE: ALWAYS use these for auth pages.** Do NOT build custom login/register forms.
+
+\`\`\`tsx
+import { AuthProvider, LoginForm, RegisterForm, useAuth } from '@blacksmith-ui/auth'
+\`\`\`
+
+### Components
+
+- \`AuthProvider\` \u2014 Context provider wrapping the app. Props: \`config: { adapter, socialProviders? }\`
+- \`LoginForm\` \u2014 Complete login form with email/password fields, validation, and links
+  - Props: \`onSubmit: (data: { email, password }) => void\`, \`onRegisterClick\`, \`onForgotPasswordClick\`, \`error\`, \`loading\`
+- \`RegisterForm\` \u2014 Registration form with email, password, and display name
+  - Props: \`onSubmit: (data: { email, password, displayName }) => void\`, \`onLoginClick\`, \`error\`, \`loading\`
+- \`ForgotPasswordForm\` \u2014 Password reset email request
+  - Props: \`onSubmit: (data: { email }) => void\`, \`onLoginClick\`, \`error\`, \`loading\`
+- \`ResetPasswordForm\` \u2014 Set new password form
+  - Props: \`onSubmit: (data: { password, code }) => void\`, \`code\`, \`onLoginClick\`, \`error\`, \`loading\`
+
+### Hooks
+
+- \`useAuth\` \u2014 Hook for auth state and actions
+  - Returns: \`user\`, \`loading\`, \`error\`, \`signInWithEmail(email, password)\`, \`signUpWithEmail(email, password, displayName?)\`, \`signOut()\`, \`sendPasswordResetEmail(email)\`, \`confirmPasswordReset(code, newPassword)\`, \`socialProviders\`
+
+### Adapter
+
+- \`AuthAdapter\` \u2014 Interface for custom auth backends (Django JWT adapter already configured in \`frontend/src/features/auth/adapter.ts\`)
+
+### Rules
+- NEVER build custom login/register forms. Use \`LoginForm\`, \`RegisterForm\`, etc. from \`@blacksmith-ui/auth\`.
+- NEVER manage auth state manually. Use \`useAuth\` hook.
+`;
+  }
+};
+
+// src/skills/blacksmith-hooks.ts
+var blacksmithHooksSkill = {
+  id: "blacksmith-hooks",
+  name: "@blacksmith-ui/hooks",
+  description: "74 production-ready React hooks for state, DOM, timers, async, browser APIs, and layout.",
+  render(_ctx) {
+    return `## @blacksmith-ui/hooks \u2014 React Hooks Library
+
+A collection of 74 production-ready React hooks. SSR-safe, fully typed, zero dependencies, tree-shakeable.
+
+> **RULE: Use \`@blacksmith-ui/hooks\` instead of writing custom hooks when one exists for that purpose.**
+> Before creating a new hook, check if one already exists below.
+
+\`\`\`tsx
+import { useToggle, useLocalStorage, useDebounce, useClickOutside } from '@blacksmith-ui/hooks'
+\`\`\`
+
+### State & Data
+
+| Hook | Description |
+|------|-------------|
+| \`useToggle\` | Boolean state with \`toggle\`, \`on\`, \`off\` actions |
+| \`useDisclosure\` | Open/close/toggle state for modals, drawers, etc. |
+| \`useCounter\` | Numeric counter with optional min/max clamping |
+| \`useList\` | Array state with push, remove, update, insert, filter, clear |
+| \`useMap\` | Map state with set, remove, clear helpers |
+| \`useSet\` | Set state with add, remove, toggle, has, clear helpers |
+| \`useHistoryState\` | State with undo/redo history |
+| \`useDefault\` | State that falls back to a default when set to null/undefined |
+| \`useQueue\` | FIFO queue data structure |
+| \`useStack\` | LIFO stack data structure |
+| \`useLocalStorage\` | Persist state to localStorage with JSON serialization |
+| \`useSessionStorage\` | Persist state to sessionStorage with JSON serialization |
+| \`useUncontrolled\` | Controlled/uncontrolled component pattern helper |
+
+### Values & Memoization
+
+| Hook | Description |
+|------|-------------|
+| \`useDebounce\` | Debounce a value with configurable delay |
+| \`useDebouncedCallback\` | Debounce a callback function |
+| \`useThrottle\` | Throttle a value with configurable interval |
+| \`useThrottledCallback\` | Throttle a callback function |
+| \`usePrevious\` | Track the previous value of a variable |
+| \`useLatest\` | Ref that always points to the latest value |
+| \`useConst\` | Compute a value once and return it on every render |
+| \`useSyncedRef\` | Keep a ref synchronized with the latest value |
+
+### DOM & Browser
+
+| Hook | Description |
+|------|-------------|
+| \`useClickOutside\` | Detect clicks outside a ref element |
+| \`useEventListener\` | Attach event listeners to window or elements |
+| \`useElementSize\` | Track element width/height via ResizeObserver |
+| \`useHover\` | Track mouse hover state |
+| \`useKeyPress\` | Listen for a specific key press |
+| \`useKeyCombo\` | Listen for key + modifier combinations |
+| \`useLongPress\` | Detect long press gestures |
+| \`useFullscreen\` | Manage the Fullscreen API |
+| \`useTextSelection\` | Track currently selected text |
+| \`useFocusWithin\` | Track whether focus is inside a container |
+| \`useFocusTrap\` | Trap Tab/Shift+Tab focus within a container |
+| \`useBoundingClientRect\` | Track element bounding rect via ResizeObserver |
+| \`useSwipe\` | Detect touch swipe direction |
+| \`useDrag\` | Track mouse drag with position and delta |
+| \`useElementVisibility\` | Check if an element is in the viewport |
+| \`useScrollPosition\` | Track window scroll position |
+| \`useScrollLock\` | Lock/unlock body scroll |
+| \`useMutationObserver\` | Observe DOM mutations |
+| \`useIntersectionObserver\` | Observe element intersection with viewport |
+
+### Timers & Lifecycle
+
+| Hook | Description |
+|------|-------------|
+| \`useInterval\` | setInterval wrapper with pause support |
+| \`useTimeout\` | setTimeout wrapper with manual clear |
+| \`useCountdown\` | Countdown timer with start/pause/reset |
+| \`useStopwatch\` | Stopwatch with lap support |
+| \`useIdleTimer\` | Detect user idle time |
+| \`useUpdateEffect\` | useEffect that skips the initial render |
+| \`useIsomorphicLayoutEffect\` | SSR-safe useLayoutEffect |
+| \`useIsMounted\` | Check if component is currently mounted |
+| \`useIsFirstRender\` | Check if this is the first render |
+
+### Async & Network
+
+| Hook | Description |
+|------|-------------|
+| \`useFetch\` | Declarative data fetching with loading/error states (use for external URLs; use TanStack Query for API calls) |
+| \`useAsync\` | Execute async functions with status tracking |
+| \`useScript\` | Dynamically load external scripts |
+| \`useWebSocket\` | WebSocket connection with auto-reconnect |
+| \`useSSE\` | Server-Sent Events (EventSource) wrapper |
+| \`usePolling\` | Poll an async function at a fixed interval |
+| \`useAbortController\` | Manage AbortController lifecycle |
+| \`useRetry\` | Retry async operations with exponential backoff |
+| \`useSearch\` | Filter arrays with debounced search |
+
+### Browser APIs
+
+| Hook | Description |
+|------|-------------|
+| \`useMediaQuery\` | Reactive CSS media query matching |
+| \`useColorScheme\` | Detect system color scheme preference |
+| \`useCopyToClipboard\` | Copy text to clipboard with status feedback |
+| \`useOnline\` | Track network connectivity |
+| \`useWindowSize\` | Track window dimensions |
+| \`usePageVisibility\` | Detect page visibility state |
+| \`usePageLeave\` | Detect when the user leaves the page |
+| \`useFavicon\` | Dynamically change the favicon |
+| \`useReducedMotion\` | Respect prefers-reduced-motion |
+| \`useBreakpoint\` | Responsive breakpoint detection |
+| \`useIsClient\` | SSR-safe client-side detection |
+
+### Layout & UI
+
+| Hook | Description |
+|------|-------------|
+| \`useStickyHeader\` | Detect when header should be sticky |
+| \`useVirtualList\` | Virtualized list rendering for large datasets |
+| \`useInfiniteScroll\` | Infinite scroll with threshold detection |
+| \`useCollapse\` | Collapse/expand animation with prop getters |
+| \`useSteps\` | Multi-step flow navigation |
+
+### Common Patterns
+
+**Modal with click-outside dismiss:**
+\`\`\`tsx
+import { useDisclosure, useClickOutside } from '@blacksmith-ui/hooks'
+
+function MyComponent() {
+  const [opened, { open, close }] = useDisclosure(false)
+  const ref = useClickOutside<HTMLDivElement>(close)
+
+  return (
+    <>
+      <Button onClick={open}>Open</Button>
+      {opened && <div ref={ref}>Modal content</div>}
+    </>
+  )
+}
+\`\`\`
+
+**Debounced search:**
+\`\`\`tsx
+import { useDebounce, useSearch } from '@blacksmith-ui/hooks'
+
+function SearchPage({ items }) {
+  const [query, setQuery] = useState('')
+  const debouncedQuery = useDebounce(query, 300)
+  const results = useSearch(items, debouncedQuery, ['title', 'description'])
+
+  return (
+    <>
+      <Input value={query} onChange={(e) => setQuery(e.target.value)} />
+      {results.map(item => <div key={item.id}>{item.title}</div>)}
+    </>
+  )
+}
+\`\`\`
+
+**Persisted state with undo:**
+\`\`\`tsx
+import { useLocalStorage, useHistoryState } from '@blacksmith-ui/hooks'
+
+function Editor() {
+  const [saved, setSaved] = useLocalStorage('draft', '')
+  const [content, { set, undo, redo, canUndo, canRedo }] = useHistoryState(saved)
+
+  const handleSave = () => setSaved(content)
+}
+\`\`\`
+
+**Responsive layout:**
+\`\`\`tsx
+import { useBreakpoint, useWindowSize } from '@blacksmith-ui/hooks'
+
+function Layout({ children }) {
+  const breakpoint = useBreakpoint({ sm: 640, md: 768, lg: 1024 })
+  const isMobile = breakpoint === 'sm'
+
+  return isMobile ? <MobileLayout>{children}</MobileLayout> : <DesktopLayout>{children}</DesktopLayout>
+}
+\`\`\`
+`;
+  }
+};
+
+// src/skills/blacksmith-cli.ts
+var blacksmithCliSkill = {
+  id: "blacksmith-cli",
+  name: "Blacksmith CLI",
+  description: "CLI commands, configuration, and workflows for project scaffolding and management.",
+  render(_ctx) {
+    return `## Blacksmith CLI
+
+Blacksmith is the CLI that scaffolded and manages this project. It lives outside the project directory as a globally installed npm package.
+
+### Commands Reference
+
+| Command | Description |
+|---|---|
+| \`blacksmith init [name]\` | Create a new project (interactive prompts if no flags) |
+| \`blacksmith dev\` | Start Django + Vite + OpenAPI watcher in parallel |
+| \`blacksmith sync\` | Regenerate frontend API client from Django OpenAPI schema |
+| \`blacksmith make:resource <Name>\` | Scaffold a full CRUD resource across backend and frontend |
+| \`blacksmith build\` | Production build (Vite build + Django collectstatic) |
+| \`blacksmith eject\` | Remove Blacksmith dependency, keep a clean project |
+| \`blacksmith setup:ai\` | Generate CLAUDE.md with AI development skills |
+| \`blacksmith skills\` | List all available AI development skills |
+
+### Configuration
+
+Project settings are stored in \`blacksmith.config.json\` at the project root:
+
+\`\`\`json
+{
+  "name": "my-app",
+  "version": "0.1.0",
+  "backend": { "port": 8000 },
+  "frontend": { "port": 5173 }
+}
+\`\`\`
+
+- **Ports** are read by \`blacksmith dev\` and \`blacksmith sync\` \u2014 change them here, not in code
+- The CLI finds the project root by walking up directories looking for this file
+
+### How \`blacksmith dev\` Works
+
+Runs three concurrent processes:
+1. **Django** \u2014 \`./venv/bin/python manage.py runserver 0.0.0.0:<backend-port>\`
+2. **Vite** \u2014 \`npm run dev\` in the frontend directory
+3. **OpenAPI watcher** \u2014 watches \`.py\` files in backend, runs \`npx openapi-ts\` on changes (2s debounce)
+
+All three are managed by \`concurrently\` and stop together on Ctrl+C.
+
+### How \`blacksmith make:resource\` Works
+
+Given a PascalCase name (e.g. \`BlogPost\`), it generates:
+
+**Backend:**
+- \`backend/apps/blog_posts/models.py\` \u2014 Django model with timestamps
+- \`backend/apps/blog_posts/serializers.py\` \u2014 DRF ModelSerializer
+- \`backend/apps/blog_posts/views.py\` \u2014 DRF ModelViewSet with drf-spectacular schemas
+- \`backend/apps/blog_posts/urls.py\` \u2014 DefaultRouter registration
+- \`backend/apps/blog_posts/admin.py\` \u2014 Admin registration
+- Wires the app into \`INSTALLED_APPS\` and \`config/urls.py\`
+- Runs \`makemigrations\` and \`migrate\`
+
+**Frontend:**
+- \`frontend/src/features/blog-posts/\` \u2014 Feature module with hooks and components
+- \`frontend/src/pages/blog-posts/\` \u2014 List and detail pages
+- Registers route path in \`frontend/src/router/paths.ts\` (\`Path\` enum)
+- Registers routes in \`frontend/src/router/routes.tsx\`
+
+Then runs \`blacksmith sync\` to generate the TypeScript API client.
+
+### How \`blacksmith sync\` Works
+
+1. Fetches the OpenAPI schema from \`http://localhost:<backend-port>/api/schema/\`
+2. Runs \`openapi-ts\` to generate TypeScript types, Zod schemas, SDK functions, and TanStack Query hooks
+3. Output goes to \`frontend/src/api/generated/\` \u2014 never edit these files manually
+
+### Init Flags
+
+\`blacksmith init\` supports both interactive prompts and CLI flags:
+
+\`\`\`bash
+# Fully interactive
+blacksmith init
+
+# Skip prompts with flags
+blacksmith init my-app -b 9000 -f 3000 --ai
+\`\`\`
+
+| Flag | Description |
+|---|---|
+| \`-b, --backend-port <port>\` | Django port (default: 8000) |
+| \`-f, --frontend-port <port>\` | Vite port (default: 5173) |
+| \`--ai\` | Generate CLAUDE.md with project skills |
+| \`--no-blacksmith-ui-skill\` | Exclude blacksmith-ui skill from CLAUDE.md |
+`;
+  }
+};
+
+// src/skills/ui-design.ts
+var uiDesignSkill = {
+  id: "ui-design",
+  name: "UI/UX Design System",
+  description: "Modern flat design principles, spacing, typography, color, layout patterns, and interaction guidelines aligned with the BlacksmithUI design language.",
+  render(_ctx) {
+    return `## UI/UX Design System \u2014 Modern Flat Design
+
+> **Design philosophy: Clean, flat, content-first.**
+> BlacksmithUI follows the same design language as Anthropic, Apple, Linear, Vercel, and OpenAI \u2014 minimal chrome, generous whitespace, subtle depth, and purposeful motion. Every UI you build must conform to this standard.
+
+### Core Principles
+
+1. **Flat over skeuomorphic** \u2014 No gradients on surfaces, no heavy drop shadows, no bevels. Use solid colors, subtle borders, and minimal \`shadow-sm\` / \`shadow-md\` only where elevation is meaningful (cards, dropdowns, modals).
+2. **Content over decoration** \u2014 UI exists to present content, not to look busy. Remove any element that doesn't serve the user. If a section looks empty, the content is the problem \u2014 not the lack of decorative elements.
+3. **Whitespace is a feature** \u2014 Generous padding and margins create hierarchy and breathing room. Cramped UIs feel cheap. When in doubt, add more space.
+4. **Consistency over creativity** \u2014 Every page should feel like part of the same app. Use the same spacing scale, the same component patterns, the same interaction behaviors everywhere.
+5. **Progressive disclosure** \u2014 Show only what's needed at each level. Use expandable sections, tabs, dialogs, and drill-down navigation to manage complexity. Don't overwhelm with everything at once.
+
+### Spacing System
+
+Use Tailwind's spacing scale consistently. Do NOT use arbitrary values (\`p-[13px]\`) \u2014 stick to the system.
+
+| Scale | Value | Use for |
+|-------|-------|---------|
+| \`1\`\u2013\`2\` | 4\u20138px | Inline gaps, icon-to-text spacing, tight badge padding |
+| \`3\`\u2013\`4\` | 12\u201316px | Inner component padding, gap between related items |
+| \`5\`\u2013\`6\` | 20\u201324px | Card padding, section inner spacing |
+| \`8\` | 32px | Gap between sections within a page |
+| \`10\`\u2013\`12\` | 40\u201348px | Gap between major page sections |
+| \`16\`\u2013\`20\` | 64\u201380px | Page-level vertical padding (hero, landing sections) |
+
+**Rules:**
+- Use \`gap\` (via \`Flex\`, \`Stack\`, \`Grid\`) for spacing between siblings \u2014 not margin on individual items
+- Use \`Stack gap={...}\` for vertical rhythm within a section
+- Page content padding: \`px-4 sm:px-6 lg:px-8\` (use \`Container\` which handles this)
+- Card body padding: \`p-6\` standard, \`p-4\` for compact cards
+- Never mix spacing approaches in the same context \u2014 pick gap OR margin, not both
+
+### Typography
+
+Use \`Typography\` and \`Text\` components from \`@blacksmith-ui/react\`. Do NOT style raw HTML headings.
+
+**Hierarchy:**
+| Level | Component | Use for |
+|-------|-----------|---------|
+| Page title | \`<Typography variant="h1">\` | One per page. The main heading. |
+| Section title | \`<Typography variant="h2">\` | Major sections within a page |
+| Sub-section | \`<Typography variant="h3">\` | Groups within a section |
+| Card title | \`<Typography variant="h4">\` or \`CardTitle\` | Card headings |
+| Body | \`<Text>\` | Paragraphs, descriptions |
+| Caption/label | \`<Text size="sm" color="muted">\` | Secondary info, metadata, timestamps |
+| Overline | \`<Text size="xs" weight="medium" className="uppercase tracking-wide">\` | Category labels, section overlines |
+
+**Rules:**
+- One \`h1\` per page \u2014 it's the page title
+- Headings should never skip levels (h1 \u2192 h3 without h2)
+- Body text: \`text-sm\` (14px) for dense UIs (tables, sidebars), \`text-base\` (16px) for reading content
+- Line height: use Tailwind defaults (\`leading-relaxed\` for body copy, \`leading-tight\` for headings)
+- Max reading width: \`max-w-prose\` (~65ch) for long-form text. Never let paragraphs stretch full-width
+- Use \`text-muted-foreground\` for secondary text, never gray hardcoded values
+- Font weight: \`font-medium\` (500) for labels and emphasis, \`font-semibold\` (600) for headings, \`font-bold\` (700) sparingly
+
+### Color
+
+Use design tokens (CSS variables), never hardcoded colors.
+
+**Semantic palette:**
+| Token | Usage |
+|-------|-------|
+| \`primary\` | Primary actions (buttons, links, active states) |
+| \`secondary\` | Secondary actions, subtle backgrounds |
+| \`destructive\` | Delete, error, danger states |
+| \`muted\` | Backgrounds for subtle sections, disabled states |
+| \`accent\` | Highlights, hover states, focus rings |
+| \`foreground\` | Primary text |
+| \`muted-foreground\` | Secondary/helper text |
+| \`border\` | Borders, dividers |
+| \`card\` | Card backgrounds |
+| \`background\` | Page background |
+
+**Rules:**
+- NEVER use Tailwind color literals (\`text-gray-500\`, \`bg-blue-600\`, \`border-slate-200\`, \`bg-white\`, \`bg-black\`). Always use semantic tokens (\`text-muted-foreground\`, \`bg-primary\`, \`border-border\`, \`bg-background\`). This is non-negotiable \u2014 hardcoded colors break dark mode.
+- Status colors: use \`Badge\` variants (\`default\`, \`secondary\`, \`destructive\`, \`outline\`) \u2014 don't hand-roll colored pills.
+- Maximum 2\u20133 colors visible at any time (primary + foreground + muted). Colorful UIs feel noisy.
+- Every UI must render correctly in both light and dark mode. See the Dark Mode section below for the full rules.
+
+### Layout Patterns
+
+**Page layout:**
+\`\`\`tsx
+<Box as="main">
+  <Container>
+    <Stack gap={8}>
+      {/* Page header */}
+      <Flex align="center" justify="between">
+        <Stack gap={1}>
+          <Typography variant="h1">Page Title</Typography>
+          <Text color="muted">Brief description of this page</Text>
+        </Stack>
+        <Button>Primary Action</Button>
+      </Flex>
+
+      {/* Page content sections */}
+      <Stack gap={6}>
+        {/* ... */}
+      </Stack>
+    </Stack>
+  </Container>
+</Box>
+\`\`\`
+
+**Card-based content:**
+\`\`\`tsx
+<Grid columns={{ base: 1, md: 2, lg: 3 }} gap={6}>
+  {items.map((item) => (
+    <Card key={item.id}>
+      <CardHeader>
+        <CardTitle>{item.title}</CardTitle>
+        <CardDescription>{item.description}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        {/* Content */}
+      </CardContent>
+    </Card>
+  ))}
+</Grid>
+\`\`\`
+
+**Sidebar + main content:**
+\`\`\`tsx
+<Flex className="min-h-screen">
+  <Sidebar>{/* Nav items */}</Sidebar>
+  <Box as="main" className="flex-1">
+    <Container>{/* Page content */}</Container>
+  </Box>
+</Flex>
+\`\`\`
+
+**Section with centered content (landing pages):**
+\`\`\`tsx
+<Box as="section" className="py-16 sm:py-20">
+  <Container>
+    <Stack gap={4} align="center" className="text-center">
+      <Typography variant="h2">Section Title</Typography>
+      <Text color="muted" className="max-w-2xl">
+        A concise description that explains the value proposition.
+      </Text>
+    </Stack>
+    <Grid columns={{ base: 1, md: 3 }} gap={8} className="mt-12">
+      {/* Feature cards or content */}
+    </Grid>
+  </Container>
+</Box>
+\`\`\`
+
+### Component Patterns
+
+**Empty states:**
+\`\`\`tsx
+// GOOD \u2014 uses EmptyState component
+<EmptyState
+  icon={Inbox}
+  title="No messages yet"
+  description="Messages from your team will appear here."
+  action={<Button>Send a message</Button>}
+/>
+
+// BAD \u2014 hand-rolled empty state
+<div className="flex flex-col items-center justify-center py-12 text-center">
+  <Inbox className="h-12 w-12 text-gray-400 mb-4" />
+  <h3 className="text-lg font-medium">No messages yet</h3>
+  <p className="text-gray-500 mt-1">Messages from your team will appear here.</p>
+</div>
+\`\`\`
+
+**Stats/metrics:**
+\`\`\`tsx
+// GOOD \u2014 uses StatCard
+<Grid columns={{ base: 1, sm: 2, lg: 4 }} gap={4}>
+  <StatCard label="Total Users" value="2,847" trend="+12%" />
+  <StatCard label="Revenue" value="$48,290" trend="+8%" />
+</Grid>
+
+// BAD \u2014 hand-rolled stat cards
+<div className="grid grid-cols-4 gap-4">
+  <div className="bg-white rounded-lg p-6 shadow">
+    <p className="text-sm text-gray-500">Total Users</p>
+    <p className="text-2xl font-bold">2,847</p>
+  </div>
+</div>
+\`\`\`
+
+**Loading states:**
+\`\`\`tsx
+// GOOD \u2014 Skeleton matches the layout structure
+<Stack gap={4}>
+  <Skeleton className="h-8 w-48" />       {/* Title */}
+  <Skeleton className="h-4 w-96" />       {/* Description */}
+  <Grid columns={3} gap={4}>
+    {Array.from({ length: 3 }).map((_, i) => (
+      <Skeleton key={i} className="h-32" />
+    ))}
+  </Grid>
+</Stack>
+
+// BAD \u2014 generic spinner with no layout hint
+<div className="flex justify-center py-12">
+  <div className="animate-spin h-8 w-8 border-2 border-blue-500 rounded-full" />
+</div>
+\`\`\`
+
+### Dark Mode & Light Mode
+
+> **CRITICAL: Every screen, component, and custom style MUST look correct in both light and dark mode. No exceptions.**
+
+BlacksmithUI uses the \`.dark\` class strategy on \`<html>\`. All semantic CSS variables automatically switch between light and dark values. Your job is to never break this.
+
+**Rules:**
+- NEVER hardcode colors. \`text-gray-500\`, \`bg-white\`, \`bg-slate-900\`, \`border-gray-200\` \u2014 all of these break in one mode or the other. Use semantic tokens: \`text-muted-foreground\`, \`bg-background\`, \`bg-card\`, \`border-border\`.
+- NEVER use \`bg-white\` or \`bg-black\`. Use \`bg-background\` (page), \`bg-card\` (elevated surfaces), \`bg-muted\` (subtle sections).
+- NEVER use \`text-black\` or \`text-white\`. Use \`text-foreground\` (primary text), \`text-muted-foreground\` (secondary), \`text-primary-foreground\` (text on primary-colored backgrounds).
+- NEVER use hardcoded shadows like \`shadow-[0_2px_8px_rgba(0,0,0,0.1)]\`. Use Tailwind shadow utilities (\`shadow-sm\`, \`shadow-md\`) which respect the theme.
+- NEVER use opacity-based overlays with hardcoded colors (\`bg-black/50\`). Use \`bg-background/80\` or let overlay components (\`Dialog\`, \`Sheet\`) handle it.
+- SVG fills and strokes: use \`currentColor\` or \`fill-foreground\` / \`stroke-border\` \u2014 never \`fill-black\` or \`stroke-gray-300\`.
+- Image assets: if you use decorative images or illustrations, ensure they work on both backgrounds or use \`dark:hidden\` / \`hidden dark:block\` to swap variants.
+
+**Safe color tokens (always use these):**
+| Need | Light mode maps to | Dark mode maps to | Use |
+|------|----|----|-----|
+| Page background | white/light gray | near-black | \`bg-background\` |
+| Card/surface | white | dark gray | \`bg-card\` |
+| Subtle background | light gray | darker gray | \`bg-muted\` |
+| Primary text | near-black | near-white | \`text-foreground\` |
+| Secondary text | medium gray | lighter gray | \`text-muted-foreground\` |
+| Borders | light gray | dark gray | \`border-border\` |
+| Input borders | light gray | dark gray | \`border-input\` |
+| Focus ring | brand color | brand color | \`ring-ring\` |
+| Primary action | brand color | brand color | \`bg-primary text-primary-foreground\` |
+| Destructive | red | red | \`bg-destructive text-destructive-foreground\` |
+
+**Testing checklist (mental model):**
+Before considering any UI complete, verify these in your head:
+1. Does every text element use \`foreground\`, \`muted-foreground\`, or \`*-foreground\` tokens?
+2. Does every background use \`background\`, \`card\`, \`muted\`, or \`primary\`/\`secondary\`/\`accent\` tokens?
+3. Does every border use \`border\`, \`input\`, or \`ring\` tokens?
+4. Are there ANY hex values, rgb values, or Tailwind color names (gray, slate, blue, etc.) in the code? If yes, replace them.
+5. Do hover/focus/active states also use semantic tokens? (\`hover:bg-muted\` not \`hover:bg-gray-100\`)
+
+### Interactions & Feedback
+
+- **Hover states**: Subtle background change (\`hover:bg-muted\`) \u2014 not color shifts or scale transforms
+- **Focus**: Use focus-visible ring (\`focus-visible:ring-2 ring-ring\`). BlacksmithUI components handle this automatically
+- **Transitions**: \`transition-colors duration-150\` for color changes. No bounces, no springs, no dramatic animations
+- **Click feedback**: Use \`active:scale-[0.98]\` only on buttons and interactive cards, never on text or static elements
+- **Loading feedback**: Show \`Spinner\` on buttons during async actions. Use \`Skeleton\` for content areas. Never leave the user without feedback during loading
+- **Success/error feedback**: Use \`useToast()\` for transient confirmations. Use \`Alert\` for persistent messages. Never use \`window.alert()\`
+- **Confirmation before destructive actions**: Always use \`AlertDialog\` for delete/remove actions. Never delete on single click
+
+### Responsive Design
+
+- **Mobile-first**: Write base styles for mobile, add \`sm:\`/\`md:\`/\`lg:\` for larger screens
+- **Breakpoints**: \`sm\` (640px), \`md\` (768px), \`lg\` (1024px), \`xl\` (1280px)
+- **Grid collapse**: \`Grid columns={{ base: 1, md: 2, lg: 3 }}\` \u2014 single column on mobile, expand on larger screens
+- **Hide/show**: Use \`hidden md:block\` / \`md:hidden\` to toggle elements across breakpoints
+- **Touch targets**: Minimum 44\xD744px for interactive elements on mobile. Use \`Button size="lg"\` and adequate padding
+- **Stack on mobile, row on desktop**: Use \`Flex direction={{ base: 'column', md: 'row' }}\` or \`Stack\` that switches direction
+- **Container**: Always wrap page content in \`<Container>\` \u2014 it handles responsive horizontal padding
+
+### Anti-Patterns \u2014 NEVER Do These
+
+| Anti-pattern | What to do instead |
+|---|---|
+| Hardcoded colors (\`text-gray-500\`, \`bg-blue-600\`) | Use semantic tokens (\`text-muted-foreground\`, \`bg-primary\`) |
+| Heavy box shadows (\`shadow-xl\`, \`shadow-2xl\`) | Use \`shadow-sm\` on cards, \`shadow-md\` on elevated overlays only |
+| Rounded pill shapes (\`rounded-full\`) on cards/containers | Use \`rounded-lg\` or \`rounded-md\` (controlled by \`--radius\`) |
+| Gradient backgrounds on surfaces | Use solid \`bg-card\` or \`bg-background\` |
+| Decorative borders (\`border-l-4 border-blue-500\`) | Use \`Divider\` or \`border-border\` |
+| Custom scrollbars with CSS hacks | Use \`ScrollArea\` |
+| Animated entrances (fade-in, slide-up on mount) | Content should appear instantly. Only animate user-triggered changes |
+| Centering with \`absolute inset-0 flex items-center\` | Use \`Flex align="center" justify="center"\` |
+| Using \`<br />\` for spacing | Use \`Stack gap={...}\` or margin utilities |
+| Multiple font sizes in close proximity | Keep nearby text within 1\u20132 size steps |
+| Dense walls of text | Break into sections with headings, cards, or spacing |
+| Colored backgrounds on every section | Use \`bg-background\` as default, \`bg-muted\` sparingly for contrast |
+| Over-using badges/tags on everything | Badges are for status and categories, not decoration |
+| Inline styles (\`style={{ ... }}\`) | Use Tailwind classes via \`className\` |
+| \`bg-white\` / \`bg-black\` / \`bg-slate-*\` | Use \`bg-background\`, \`bg-card\`, \`bg-muted\` |
+| \`text-black\` / \`text-white\` / \`text-gray-*\` | Use \`text-foreground\`, \`text-muted-foreground\` |
+| \`border-gray-*\` / \`border-slate-*\` | Use \`border-border\`, \`border-input\` |
+| Hex/rgb values in className or style | Use CSS variable tokens exclusively |
+| UI that only looks right in light mode | Always verify both modes \u2014 use semantic tokens throughout |
+`;
+  }
+};
+
+// src/skills/programming-paradigms.ts
+var programmingParadigmsSkill = {
+  id: "programming-paradigms",
+  name: "Programming Paradigms",
+  description: "Functional programming for React frontend development, OOP + functional patterns for Django backend development.",
+  render(_ctx) {
+    return `## Programming Paradigms
+
+> **Frontend (React/TypeScript): Functional programming.** Pure functions, immutability, composition, declarative UI.
+> **Backend (Django/Python): OOP with functional touches.** Classes for structure, pure functions for logic, no mutation where avoidable.
+
+---
+
+## Frontend \u2014 Functional Programming
+
+React is a functional framework. Write it functionally. No classes, no imperative mutation, no object-oriented patterns.
+
+### Core Rules
+
+1. **Functions, not classes** \u2014 Every component is a function. Every hook is a function. Every utility is a function. Never use \`class\` in frontend code.
+2. **Pure by default** \u2014 A component given the same props should render the same output. A utility given the same arguments should return the same result. Side effects belong in hooks (\`useEffect\`, \`useMutation\`), never in render logic.
+3. **Immutable data** \u2014 Never mutate state, props, or variables. Always return new values.
+4. **Declarative over imperative** \u2014 Describe *what* to render, not *how* to render it. Use \`map\`, \`filter\`, ternaries, and composition \u2014 not \`for\` loops, \`if/else\` chains, or DOM manipulation.
+5. **Composition over inheritance** \u2014 Build complex behavior by composing small functions and components, not by extending base classes.
+
+### Immutability
+
+\`\`\`tsx
+// BAD \u2014 mutation
+const handleAdd = (item) => {
+  items.push(item)                    // mutates array
+  setItems(items)                     // React won't re-render (same reference)
+}
+
+user.name = 'New Name'                // mutates object
+setUser(user)
+
+// GOOD \u2014 immutable updates
+const handleAdd = (item) => {
+  setItems((prev) => [...prev, item])
+}
+
+setUser((prev) => ({ ...prev, name: 'New Name' }))
+
+// GOOD \u2014 immutable array operations
+const removeItem = (id) => setItems((prev) => prev.filter((i) => i.id !== id))
+const updateItem = (id, data) => setItems((prev) =>
+  prev.map((i) => (i.id === id ? { ...i, ...data } : i))
+)
+\`\`\`
+
+### Pure Functions & Composition
+
+\`\`\`tsx
+// BAD \u2014 impure, relies on external state
+let taxRate = 0.1
+const calculateTotal = (price) => price * (1 + taxRate)
+
+// GOOD \u2014 pure, all inputs explicit
+const calculateTotal = (price: number, taxRate: number) => price * (1 + taxRate)
+
+// GOOD \u2014 compose small functions
+const formatCurrency = (amount: number) => \`$\${amount.toFixed(2)}\`
+const calculateTax = (price: number, rate: number) => price * rate
+const formatPriceWithTax = (price: number, rate: number) =>
+  formatCurrency(price + calculateTax(price, rate))
+\`\`\`
+
+### Declarative UI Patterns
+
+\`\`\`tsx
+// BAD \u2014 imperative rendering
+function UserList({ users }) {
+  const items = []
+  for (let i = 0; i < users.length; i++) {
+    if (users[i].isActive) {
+      items.push(<UserCard key={users[i].id} user={users[i]} />)
+    }
+  }
+  return <div>{items}</div>
+}
+
+// GOOD \u2014 declarative rendering
+function UserList({ users }) {
+  return (
+    <Stack gap={4}>
+      {users
+        .filter((user) => user.isActive)
+        .map((user) => <UserCard key={user.id} user={user} />)
+      }
+    </Stack>
+  )
+}
+
+// BAD \u2014 imperative conditional
+function Status({ isOnline }) {
+  let badge
+  if (isOnline) {
+    badge = <Badge>Online</Badge>
+  } else {
+    badge = <Badge variant="secondary">Offline</Badge>
+  }
+  return badge
+}
+
+// GOOD \u2014 declarative conditional
+function Status({ isOnline }) {
+  return isOnline
+    ? <Badge>Online</Badge>
+    : <Badge variant="secondary">Offline</Badge>
+}
+\`\`\`
+
+### Hooks as Functional Composition
+
+\`\`\`tsx
+// BAD \u2014 logic in component body
+function OrdersPage() {
+  const [page, setPage] = useState(1)
+  const [search, setSearch] = useState('')
+  const debounced = useDebounce(search, 300)
+  const { data } = useApiQuery(ordersListOptions({ query: { page, search: debounced } }))
+  const deleteOrder = useApiMutation(ordersDestroyMutation())
+
+  // ... 20 lines of derived state and handlers
+
+  return ( /* JSX */ )
+}
+
+// GOOD \u2014 compose hooks, component just renders
+function OrdersPage() {
+  const { orders, pagination, search, deleteOrder } = useOrdersPage()
+
+  return (
+    <Stack gap={4}>
+      <OrdersToolbar search={search} />
+      <OrdersTable orders={orders} onDelete={deleteOrder} />
+      <Pagination {...pagination} />
+    </Stack>
+  )
+}
+
+// The hook composes smaller hooks
+function useOrdersPage() {
+  const search = useSearchFilter()
+  const pagination = usePagination()
+  const { data } = useOrders({ page: pagination.page, search: search.debounced })
+  const deleteOrder = useDeleteOrder()
+
+  return {
+    orders: data?.results ?? [],
+    pagination: { ...pagination, total: data?.count ?? 0 },
+    search,
+    deleteOrder: (id: number) => deleteOrder.mutate({ path: { id } }),
+  }
+}
+\`\`\`
+
+### Data Transformation \u2014 Functional Style
+
+\`\`\`tsx
+// BAD \u2014 imperative transformation
+function getActiveUserNames(users) {
+  const result = []
+  for (const user of users) {
+    if (user.isActive) {
+      result.push(user.name.toUpperCase())
+    }
+  }
+  return result
+}
+
+// GOOD \u2014 functional pipeline
+const getActiveUserNames = (users: User[]) =>
+  users
+    .filter((u) => u.isActive)
+    .map((u) => u.name.toUpperCase())
+
+// GOOD \u2014 derive state without mutation
+const sortedItems = useMemo(
+  () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+)
+
+const groupedByStatus = useMemo(
+  () => items.reduce<Record<string, Item[]>>((acc, item) => ({
+    ...acc,
+    [item.status]: [...(acc[item.status] ?? []), item],
+  }), {}),
+  [items]
+)
+\`\`\`
+
+### What to Avoid in Frontend Code
+
+| Anti-pattern | Functional alternative |
+|---|---|
+| \`class MyComponent extends React.Component\` | \`function MyComponent()\` |
+| \`this.state\`, \`this.setState\` | \`useState\`, \`useReducer\` |
+| \`array.push()\`, \`object.key = value\` | Spread: \`[...arr, item]\`, \`{ ...obj, key: value }\` |
+| \`for\` / \`while\` loops in render | \`.map()\`, \`.filter()\`, \`.reduce()\` |
+| \`let\` for derived values | \`const\` + \`useMemo\` or inline computation |
+| Mutable ref for state (\`useRef\` to track values) | \`useState\` or \`useReducer\` |
+| HOCs (\`withAuth\`, \`withTheme\`) | Custom hooks (\`useAuth\`, \`useTheme\`) |
+| Render props for logic sharing | Custom hooks |
+| \`if/else\` chains for rendering | Ternaries, \`&&\`, early returns, lookup objects |
+| Singleton services / global mutable state | Context + hooks, React Query for server state |
+
+---
+
+## Backend \u2014 OOP with Functional Patterns
+
+Django is object-oriented by design. Lean into it for structure (models, views, serializers, services), but use functional patterns for pure logic and data transformations.
+
+### OOP for Structure
+
+**Models** \u2014 Encapsulate data and behavior together:
+\`\`\`python
+class Order(TimeStampedModel):
+    user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='orders')
+    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='pending')
+    total = models.DecimalField(max_digits=10, decimal_places=2, default=0)
+
+    class Meta:
+        ordering = ['-created_at']
+
+    def __str__(self):
+        return f"Order #{self.pk} \u2014 {self.user}"
+
+    @property
+    def is_cancellable(self):
+        return self.status in ('pending', 'confirmed')
+
+    def recalculate_total(self):
+        self.total = self.items.aggregate(
+            total=Sum(F('quantity') * F('unit_price'))
+        )['total'] or 0
+        self.save(update_fields=['total'])
+\`\`\`
+
+**Services** \u2014 Classes for complex business operations with multiple related methods:
+\`\`\`python
+class OrderService:
+    @staticmethod
+    @transaction.atomic
+    def place_order(*, user, items, shipping_address):
+        order = Order.objects.create(user=user, shipping_address=shipping_address)
+        for item_data in items:
+            OrderItem.objects.create(order=order, **item_data)
+        order.recalculate_total()
+        NotificationService.send_order_confirmation(order=order)
+        return order
+
+    @staticmethod
+    @transaction.atomic
+    def cancel_order(*, order, user):
+        if not order.is_cancellable:
+            raise ValidationError("Order cannot be cancelled in its current state.")
+        if order.user != user:
+            raise PermissionDenied("You can only cancel your own orders.")
+        order.status = 'cancelled'
+        order.save(update_fields=['status'])
+        InventoryService.restore_stock(order=order)
+        return order
+\`\`\`
+
+**ViewSets** \u2014 Inherit, extend, override:
+\`\`\`python
+class OrderViewSet(ModelViewSet):
+    permission_classes = [IsAuthenticated]
+
+    def get_queryset(self):
+        return OrderSelector.list_for_user(user=self.request.user)
+
+    def get_serializer_class(self):
+        return {
+            'list': OrderListSerializer,
+            'retrieve': OrderDetailSerializer,
+            'create': OrderCreateSerializer,
+        }.get(self.action, OrderUpdateSerializer)
+
+    def perform_create(self, serializer):
+        serializer.save()
+\`\`\`
+
+**Custom permissions, filters, pagination** \u2014 All class-based, inheriting from DRF base classes:
+\`\`\`python
+class IsOwner(BasePermission):
+    def has_object_permission(self, request, view, obj):
+        return obj.user == request.user
+
+class OrderFilterSet(django_filters.FilterSet):
+    class Meta:
+        model = Order
+        fields = ['status', 'created_at']
+\`\`\`
+
+### Functional Patterns in Python
+
+Use functional style for pure logic, data transformation, and utilities \u2014 anywhere you don't need state or inheritance.
+
+**Selectors** \u2014 Pure query builders (can be functions or static methods):
+\`\`\`python
+# selectors.py \u2014 pure functions that build querysets
+def get_active_orders(*, user, status=None):
+    qs = (
+        Order.objects
+        .filter(user=user, is_active=True)
+        .select_related('user')
+        .prefetch_related('items__product')
+    )
+    if status:
+        qs = qs.filter(status=status)
+    return qs.order_by('-created_at')
+
+def get_order_summary(*, user):
+    return (
+        Order.objects
+        .filter(user=user)
+        .values('status')
+        .annotate(count=Count('id'), total=Sum('total'))
+    )
+\`\`\`
+
+**Data transformations** \u2014 Use comprehensions, \`map\`, pure functions:
+\`\`\`python
+# BAD \u2014 imperative mutation
+def format_export_data(orders):
+    result = []
+    for order in orders:
+        row = {}
+        row['id'] = order.id
+        row['total'] = str(order.total)
+        row['items'] = ', '.join([i.product.name for i in order.items.all()])
+        result.append(row)
+    return result
+
+# GOOD \u2014 functional transformation
+def format_export_data(orders):
+    return [
+        {
+            'id': order.id,
+            'total': str(order.total),
+            'items': ', '.join(i.product.name for i in order.items.all()),
+        }
+        for order in orders
+    ]
+\`\`\`
+
+**Utility functions** \u2014 Pure, no side effects:
+\`\`\`python
+# utils.py \u2014 all pure functions
+def calculate_discount(price: Decimal, percentage: int) -> Decimal:
+    return price * (Decimal(percentage) / 100)
+
+def slugify_unique(name: str, existing_slugs: set[str]) -> str:
+    base = slugify(name)
+    slug = base
+    counter = 1
+    while slug in existing_slugs:
+        slug = f"{base}-{counter}"
+        counter += 1
+    return slug
+
+def paginate_list(items: list, page: int, page_size: int = 20) -> list:
+    start = (page - 1) * page_size
+    return items[start:start + page_size]
+\`\`\`
+
+**Decorators** \u2014 Functional composition for cross-cutting concerns:
+\`\`\`python
+import functools
+import logging
+
+logger = logging.getLogger(__name__)
+
+def log_service_call(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        logger.info(f"Calling {func.__name__} with kwargs={kwargs}")
+        result = func(*args, **kwargs)
+        logger.info(f"{func.__name__} completed successfully")
+        return result
+    return wrapper
+
+# Usage
+class OrderService:
+    @staticmethod
+    @log_service_call
+    @transaction.atomic
+    def place_order(*, user, items, shipping_address):
+        ...
+\`\`\`
+
+### When to Use What
+
+| Pattern | Use OOP (class) | Use Functional (function) |
+|---------|-----------------|---------------------------|
+| **Models** | Always \u2014 Django models are classes | Model methods can be property-style pure computations |
+| **Views** | Always \u2014 ViewSets, APIViews | \u2014 |
+| **Serializers** | Always \u2014 DRF serializers are classes | \u2014 |
+| **Services** | Business logic with multiple related operations | Single-purpose operations can be standalone functions |
+| **Selectors** | Either \u2014 class with static methods or module-level functions | Preferred \u2014 pure functions that return querysets |
+| **Permissions** | Always \u2014 DRF permissions are class-based | \u2014 |
+| **Filters** | Always \u2014 django-filter uses classes | \u2014 |
+| **Utilities** | Never \u2014 don't wrap utilities in classes | Always \u2014 pure functions |
+| **Data transforms** | Never | Always \u2014 comprehensions, map, pure functions |
+| **Validators** | DRF validator classes for reusable validation | Simple validation functions for one-off checks |
+| **Signals** | Receiver functions (decorated functions) | \u2014 |
+| **Tests** | Test classes inheriting APITestCase | Individual test functions with pytest are also fine |
+
+### Backend Anti-Patterns
+
+| Anti-pattern | Correct approach |
+|---|---|
+| God class with 20+ methods | Split into focused Service + Selector + utils |
+| Utility class with only static methods | Use module-level functions instead |
+| Mixin soup (\`class View(A, B, C, D, E)\`) | Compose with max 1-2 mixins, prefer explicit overrides |
+| Business logic in views | Move to services |
+| Business logic in serializers | Serializers validate, services execute |
+| Mutable default arguments (\`def f(items=[])\`) | Use \`None\` default: \`def f(items=None)\` \u2192 \`items = items or []\` |
+| Nested \`for\` loops for data building | List/dict comprehensions |
+| Raw SQL for simple queries | Django ORM with \`annotate\`, \`Subquery\`, \`F\` expressions |
+| Global mutable state | Pass dependencies explicitly, use Django settings for config |
+| Deep inheritance chains | Prefer composition, keep inheritance to 1-2 levels |
+`;
+  }
+};
+
+// src/skills/clean-code.ts
+var cleanCodeSkill = {
+  id: "clean-code",
+  name: "Clean Code Principles",
+  description: "Naming, functions, components, file organization, conditionals, error handling, and DRY guidelines.",
+  render(_ctx) {
+    return `## Clean Code Principles
+
+Write code that is easy to read, easy to change, and easy to delete. Treat clarity as a feature.
+
+### Naming
+- Names should reveal intent. A reader should understand what a variable, function, or class does without reading its implementation
+- Booleans: prefix with \`is\`, \`has\`, \`can\`, \`should\` \u2014 e.g. \`isLoading\`, \`hasPermission\`, \`canEdit\`
+- Functions: use verb phrases that describe the action \u2014 e.g. \`fetchUsers\`, \`createOrder\`, \`validateEmail\`
+- Event handlers: prefix with \`handle\` in components, \`on\` in props \u2014 e.g. \`handleSubmit\`, \`onSubmit\`
+- Collections: use plural nouns \u2014 e.g. \`users\`, \`orderItems\`, not \`userList\` or \`data\`
+- Avoid abbreviations. \`transaction\` not \`txn\`, \`button\` not \`btn\`, \`message\` not \`msg\`
+- Avoid generic names like \`data\`, \`info\`, \`item\`, \`result\`, \`value\` unless the scope is trivially small (e.g. a one-line callback)
+
+### Functions
+- A function should do one thing. If you can describe what it does with "and", split it
+- Keep functions short \u2014 aim for under 20 lines. If a function is longer, look for sections you can extract
+- Prefer early returns to reduce nesting. Guard clauses at the top, happy path at the bottom
+- Limit parameters to 3. Beyond that, pass an options object
+- Pure functions are easier to test, reason about, and reuse. Prefer them where possible
+- Don't use flags (boolean parameters) to make a function do two different things \u2014 write two functions instead
+
+### Components (React-specific)
+- One component per file. The file name should match the component name
+- Keep components under 100 lines of JSX. Extract sub-components when they grow beyond this
+- Separate data logic (hooks) from presentation (components). A component should mostly be JSX, not logic
+- **Page components are orchestrators** \u2014 they should be ~20-30 lines, composing child components from \`components/\` and calling hooks from \`hooks/\`. Never build a 200-line page monolith
+- Props interfaces should be explicit and narrow \u2014 accept only what the component needs, not entire objects
+- Avoid prop drilling beyond 2 levels \u2014 use context or restructure the component tree
+- Destructure props in the function signature for clarity
+- Use \`@blacksmith-ui/react\` layout components (\`Stack\`, \`Flex\`, \`Grid\`) \u2014 never raw \`<div>\` with flex/grid classes
+
+### File Organization
+- Keep files short. If a file exceeds 200 lines, it is likely doing too much \u2014 split it
+- Group by feature, not by type. \`features/orders/\` is better than \`components/\`, \`hooks/\`, \`utils/\` at the top level
+- Co-locate related code. A component's hook, types, and test should live next to it
+- One export per file for components and hooks. Use \`index.ts\` barrel files only at the feature boundary
+
+### Conditionals & Logic
+- Prefer positive conditionals: \`if (isValid)\` over \`if (!isInvalid)\`
+- Extract complex conditions into well-named variables or functions:
+  \`\`\`ts
+  // Bad
+  if (user.role === 'admin' && user.isActive && !user.isSuspended) { ... }
+
+  // Good
+  const canAccessAdminPanel = user.role === 'admin' && user.isActive && !user.isSuspended
+  if (canAccessAdminPanel) { ... }
+  \`\`\`
+- Avoid deeply nested if/else trees. Use early returns, guard clauses, or lookup objects
+- Prefer \`switch\` or object maps over long \`if/else if\` chains:
+  \`\`\`ts
+  // Bad
+  if (status === 'active') return 'green'
+  else if (status === 'pending') return 'yellow'
+  else if (status === 'inactive') return 'gray'
+
+  // Good
+  const statusColor = { active: 'green', pending: 'yellow', inactive: 'gray' }
+  return statusColor[status]
+  \`\`\`
+
+### Error Handling
+- Handle errors at the right level \u2014 close to where they occur and where you can do something meaningful
+- Provide useful error messages that help the developer (or user) understand what went wrong and what to do
+- Don't swallow errors silently. If you catch, log or handle. Never write empty \`catch {}\` blocks
+- Use typed errors. In Python, raise specific exceptions. In TypeScript, return discriminated unions or throw typed errors
+
+### Comments
+- Don't comment what the code does \u2014 make the code readable enough to not need it
+- Do comment why \u2014 explain business decisions, workarounds, non-obvious constraints
+- Delete commented-out code. Version control remembers it
+- TODOs are acceptable but should include context: \`// TODO(auth): rate-limit login attempts after v1 launch\`
+
+### DRY Without Overengineering
+- Don't repeat the same logic in multiple places \u2014 extract it once you see the third occurrence
+- But don't over-abstract. Two similar blocks of code are fine if they serve different purposes and are likely to diverge
+- Premature abstraction is worse than duplication. Wait for patterns to emerge before creating shared utilities
+- Helper functions should be genuinely reusable. A "helper" called from one place is just indirection
+
+### Python-Specific (Django)
+- Use \`f-strings\` for string formatting, not \`.format()\` or \`%\`
+- Use list/dict/set comprehensions when they are clearer than loops \u2014 but don't nest them
+- Use \`dataclasses\` or typed dicts for structured data outside of Django models
+- Keep view methods thin \u2014 push business logic into model methods, serializer validation, or service functions
+- Use \`get_object_or_404\` instead of manual \`try/except DoesNotExist\`
+
+### TypeScript-Specific (React)
+- Use strict TypeScript. Don't use \`any\` \u2014 use \`unknown\` and narrow, or define a proper type
+- Define interfaces for component props, API responses, and form schemas
+- Use \`const\` by default. Only use \`let\` when reassignment is necessary. Never use \`var\`
+- Prefer \`map\`, \`filter\`, \`reduce\` over imperative loops for data transformation
+- Use optional chaining (\`?.\`) and nullish coalescing (\`??\`) instead of manual null checks
+- Keep type definitions close to where they are used. Don't create a global \`types.ts\` file
+`;
+  }
+};
+
+// src/skills/ai-guidelines.ts
+var aiGuidelinesSkill = {
+  id: "ai-guidelines",
+  name: "AI Development Guidelines",
+  description: "Guidelines for developing the project using AI, including when to use code generation, code style, environment setup, and a checklist before finishing tasks.",
+  render(_ctx) {
+    return `## AI Development Guidelines
+
+### When Adding Features
+1. Use \`blacksmith make:resource <Name>\` for new CRUD resources \u2014 it scaffolds model, serializer, viewset, URLs, hooks, components, and pages across both backend and frontend
+2. After any backend API change (new endpoint, changed schema, new field), run \`blacksmith sync\` to regenerate the frontend API client and types
+3. Never manually edit files in \`frontend/src/api/generated/\` \u2014 they are overwritten on every sync
+
+### Code Style
+- **Backend**: Follow PEP 8. Use Django and DRF conventions. Docstrings on models, serializers, and non-obvious view methods
+- **Frontend**: TypeScript strict mode. Functional components. Named exports (not default, except for page components used in routes). Descriptive variable names
+- Use existing patterns in the codebase as reference before inventing new ones
+
+### Frontend Architecture (Mandatory)
+- **Use \`@blacksmith-ui/react\` for ALL UI** \u2014 \`Stack\`, \`Flex\`, \`Grid\` for layout; \`Typography\`, \`Text\` for text; \`Card\`, \`Button\`, \`Badge\`, etc. for all elements. Never use raw HTML (\`<div>\`, \`<h1>\`, \`<p>\`, \`<button>\`) when a Blacksmith-UI component exists
+- **Pages are thin orchestrators** \u2014 compose child components from \`components/\`, extract logic into \`hooks/\`. A page file should be ~20-30 lines, not a monolith
+- **Use the \`Path\` enum** \u2014 all route paths come from \`src/router/paths.ts\`. Never hardcode path strings like \`'/login'\` or \`'/dashboard'\`
+- **Add new paths to the enum** \u2014 when creating a new page, add its path to the \`Path\` enum before the \`// blacksmith:path\` marker
+
+### Environment
+- Backend: \`http://localhost:8000\`
+- Frontend: \`http://localhost:5173\`
+- API docs: \`http://localhost:8000/api/docs/\` (Swagger UI) or \`/api/redoc/\` (ReDoc)
+- Python venv: \`backend/venv/\` \u2014 always use \`./venv/bin/python\` or \`./venv/bin/pip\`
+- Start everything: \`blacksmith dev\`
+
+### Checklist Before Finishing a Task
+1. Backend tests pass: \`cd backend && ./venv/bin/python manage.py test\`
+2. Frontend builds: \`cd frontend && npm run build\`
+3. API types are in sync: \`blacksmith sync\`
+4. No lint errors in modified files
+5. All UI uses \`@blacksmith-ui/react\` components \u2014 no raw \`<div>\` for layout, no raw \`<h1>\`-\`<h6>\` for text
+6. Pages are modular \u2014 page file is a thin orchestrator, sections are in \`components/\`, logic in \`hooks/\`
+7. Logic is in hooks \u2014 no \`useApiQuery\`, \`useApiMutation\`, \`useEffect\`, or multi-\`useState\` in component bodies
+8. No hardcoded route paths \u2014 all paths use the \`Path\` enum from \`@/router/paths\`
+9. New routes have a corresponding \`Path\` enum entry
+`;
+  }
+};
+
+// src/commands/ai-setup.ts
+async function setupAiDev({ projectDir, projectName, includeBlacksmithUiSkill }) {
+  const aiSpinner = spinner("Setting up AI development environment...");
+  try {
+    const skills = [
+      coreRulesSkill,
+      projectOverviewSkill,
+      djangoSkill,
+      djangoRestAdvancedSkill,
+      apiDocumentationSkill,
+      reactSkill,
+      reactQuerySkill,
+      pageStructureSkill
+    ];
+    if (includeBlacksmithUiSkill) {
+      skills.push(blacksmithUiReactSkill);
+      skills.push(blacksmithUiFormsSkill);
+      skills.push(blacksmithUiAuthSkill);
+      skills.push(blacksmithHooksSkill);
+      skills.push(uiDesignSkill);
+    }
+    skills.push(blacksmithCliSkill);
+    skills.push(programmingParadigmsSkill);
+    skills.push(cleanCodeSkill);
+    skills.push(aiGuidelinesSkill);
+    const ctx = { projectName };
+    const inlineSkills = skills.filter((s) => !s.name);
+    const fileSkills = skills.filter((s) => s.name);
+    const skillsDir = path3.join(projectDir, ".claude", "skills");
+    if (fs3.existsSync(skillsDir)) {
+      for (const entry of fs3.readdirSync(skillsDir)) {
+        const entryPath = path3.join(skillsDir, entry);
+        const stat = fs3.statSync(entryPath);
+        if (stat.isDirectory()) {
+          fs3.rmSync(entryPath, { recursive: true });
+        } else if (entry.endsWith(".md")) {
+          fs3.unlinkSync(entryPath);
+        }
+      }
+    }
+    fs3.mkdirSync(skillsDir, { recursive: true });
+    for (const skill of fileSkills) {
+      const skillDir = path3.join(skillsDir, skill.id);
+      fs3.mkdirSync(skillDir, { recursive: true });
+      const frontmatter = `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+`;
+      const content = skill.render(ctx).trim();
+      fs3.writeFileSync(path3.join(skillDir, "SKILL.md"), frontmatter + content + "\n", "utf-8");
+    }
+    const inlineContent = inlineSkills.map((s) => s.render(ctx)).join("\n");
+    const skillsList = fileSkills.map((s) => `- \`.claude/skills/${s.id}/SKILL.md\` \u2014 ${s.name}`).join("\n");
+    const claudeMd = [
+      inlineContent.trim(),
+      "",
+      "## AI Skills",
+      "",
+      "Detailed skills and conventions are in `.claude/skills/`:",
+      "",
+      skillsList,
+      "",
+      "These files are auto-loaded by Claude Code. Run `blacksmith setup:ai` to regenerate.",
+      ""
+    ].join("\n");
+    fs3.writeFileSync(path3.join(projectDir, "CLAUDE.md"), claudeMd, "utf-8");
+    const skillNames = skills.filter((s) => s.id !== "project-overview" && s.id !== "ai-guidelines").map((s) => s.id).join(" + ");
+    aiSpinner.succeed(`AI dev environment ready (${skillNames} skills)`);
+  } catch (error) {
+    aiSpinner.fail("Failed to set up AI development environment");
+    log.error(error.message);
+  }
+}
+
+// src/commands/init.ts
+function parsePort(value, label) {
+  const port = parseInt(value, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    log.error(`Invalid ${label} port: ${value}`);
+    process.exit(1);
+  }
+  return port;
+}
+var THEME_PRESETS = ["default", "blue", "green", "violet", "red", "neutral"];
+async function init(name, options) {
+  if (!name) {
+    name = await promptText("Project name");
+    if (!name) {
+      log.error("Project name is required.");
+      process.exit(1);
+    }
+  }
+  if (!options.backendPort) {
+    options.backendPort = await promptText("Backend port", "8000");
+  }
+  if (!options.frontendPort) {
+    options.frontendPort = await promptText("Frontend port", "5173");
+  }
+  if (!options.themeColor) {
+    options.themeColor = await promptSelect("Theme preset", THEME_PRESETS, "default");
+  }
+  if (options.ai === void 0) {
+    options.ai = await promptYesNo("Set up AI coding support");
+  }
+  const backendPort = parsePort(options.backendPort, "backend");
+  const frontendPort = parsePort(options.frontendPort, "frontend");
+  const themePreset = THEME_PRESETS.includes(options.themeColor) ? options.themeColor : "default";
+  printConfig({
+    "Project": name,
+    "Backend": `Django on :${backendPort}`,
+    "Frontend": `React on :${frontendPort}`,
+    "Theme": themePreset,
+    "AI support": options.ai ? "Yes" : "No"
+  });
+  const projectDir = path4.resolve(process.cwd(), name);
+  const backendDir = path4.join(projectDir, "backend");
+  const frontendDir = path4.join(projectDir, "frontend");
+  const templatesDir = getTemplatesDir();
+  if (fs4.existsSync(projectDir)) {
+    log.error(`Directory "${name}" already exists.`);
+    process.exit(1);
+  }
+  const checkSpinner = spinner("Checking prerequisites...");
+  const hasPython = await commandExists("python3");
+  const hasNode = await commandExists("node");
+  const hasNpm = await commandExists("npm");
+  if (!hasPython) {
+    checkSpinner.fail("Python 3 is required but not found. Install it from https://python.org");
+    process.exit(1);
+  }
+  if (!hasNode || !hasNpm) {
+    checkSpinner.fail("Node.js and npm are required but not found. Install from https://nodejs.org");
+    process.exit(1);
+  }
+  checkSpinner.succeed("Prerequisites OK (Python 3, Node.js, npm)");
+  const context = {
+    projectName: name,
+    backendPort,
+    frontendPort,
+    themePreset
+  };
+  fs4.mkdirSync(projectDir, { recursive: true });
+  fs4.writeFileSync(
+    path4.join(projectDir, "blacksmith.config.json"),
+    JSON.stringify(
+      {
+        name,
+        version: "0.1.0",
+        backend: { port: backendPort },
+        frontend: { port: frontendPort }
+      },
+      null,
+      2
+    )
+  );
+  const backendSpinner = spinner("Generating Django backend...");
+  try {
+    renderDirectory(
+      path4.join(templatesDir, "backend"),
+      backendDir,
+      context
+    );
+    fs4.copyFileSync(
+      path4.join(backendDir, ".env.example"),
+      path4.join(backendDir, ".env")
+    );
+    backendSpinner.succeed("Django backend generated");
+  } catch (error) {
+    backendSpinner.fail("Failed to generate backend");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const venvSpinner = spinner("Creating Python virtual environment...");
+  try {
+    await exec("python3", ["-m", "venv", "venv"], { cwd: backendDir, silent: true });
+    venvSpinner.succeed("Virtual environment created");
+  } catch (error) {
+    venvSpinner.fail("Failed to create virtual environment");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const pipSpinner = spinner("Installing Python dependencies...");
+  try {
+    await execPip(
+      ["install", "-r", "requirements.txt"],
+      backendDir,
+      true
+    );
+    pipSpinner.succeed("Python dependencies installed");
+  } catch (error) {
+    pipSpinner.fail("Failed to install Python dependencies");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const migrateSpinner = spinner("Running initial migrations...");
+  try {
+    await execPython(["manage.py", "makemigrations", "users"], backendDir, true);
+    await execPython(["manage.py", "migrate"], backendDir, true);
+    migrateSpinner.succeed("Database migrated");
+  } catch (error) {
+    migrateSpinner.fail("Failed to run migrations");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const frontendSpinner = spinner("Generating React frontend...");
+  try {
+    renderDirectory(
+      path4.join(templatesDir, "frontend"),
+      frontendDir,
+      context
+    );
+    frontendSpinner.succeed("React frontend generated");
+  } catch (error) {
+    frontendSpinner.fail("Failed to generate frontend");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const npmSpinner = spinner("Installing Node.js dependencies...");
+  try {
+    await exec("npm", ["install"], { cwd: frontendDir, silent: true });
+    npmSpinner.succeed("Node.js dependencies installed");
+  } catch (error) {
+    npmSpinner.fail("Failed to install Node.js dependencies");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const syncSpinner = spinner("Running initial OpenAPI sync...");
+  try {
+    const djangoProcess = spawn(
+      "./venv/bin/python",
+      ["manage.py", "runserver", `0.0.0.0:${backendPort}`, "--noreload"],
+      {
+        cwd: backendDir,
+        stdio: "ignore",
+        detached: true
+      }
+    );
+    djangoProcess.unref();
+    await new Promise((resolve) => setTimeout(resolve, 4e3));
+    try {
+      await exec(process.execPath, [path4.join(frontendDir, "node_modules", ".bin", "openapi-ts")], { cwd: frontendDir, silent: true });
+      syncSpinner.succeed("OpenAPI types synced");
+    } catch {
+      syncSpinner.warn('OpenAPI sync skipped (run "blacksmith sync" after starting Django)');
+    }
+    try {
+      if (djangoProcess.pid) {
+        process.kill(-djangoProcess.pid);
+      }
+    } catch {
+    }
+  } catch {
+    syncSpinner.warn('OpenAPI sync skipped (run "blacksmith sync" after starting Django)');
+  }
+  const generatedDir = path4.join(frontendDir, "src", "api", "generated");
+  const stubFile = path4.join(generatedDir, "client.gen.ts");
+  if (!fs4.existsSync(stubFile)) {
+    if (!fs4.existsSync(generatedDir)) {
+      fs4.mkdirSync(generatedDir, { recursive: true });
+    }
+    fs4.writeFileSync(
+      stubFile,
+      [
+        "/**",
+        " * Auto-generated API Client",
+        " *",
+        " * This is a stub file that allows the app to boot before",
+        " * the first OpenAPI sync. Run `blacksmith sync` or `blacksmith dev`",
+        " * to generate the real client from your Django API schema.",
+        " *",
+        " * Generated by Blacksmith. This file will be overwritten by openapi-ts.",
+        " */",
+        "",
+        "import { createClient } from '@hey-api/client-fetch'",
+        "",
+        "export const client = createClient()",
+        ""
+      ].join("\n"),
+      "utf-8"
+    );
+  }
+  if (options.ai) {
+    await setupAiDev({
+      projectDir,
+      projectName: name,
+      includeBlacksmithUiSkill: options.blacksmithUiSkill !== false
+    });
+  }
+  printNextSteps(name, backendPort, frontendPort);
+}
+
+// src/commands/dev.ts
+import net from "net";
+import concurrently from "concurrently";
+import path5 from "path";
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port);
+  });
+}
+async function findAvailablePort(startPort) {
+  let port = startPort;
+  while (port < startPort + 100) {
+    if (await isPortAvailable(port)) return port;
+    port++;
+  }
+  throw new Error(`No available port found in range ${startPort}-${port - 1}`);
+}
+async function dev() {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const config = loadConfig(root);
+  const backendDir = getBackendDir(root);
+  const frontendDir = getFrontendDir(root);
+  let backendPort;
+  let frontendPort;
+  try {
+    ;
+    [backendPort, frontendPort] = await Promise.all([
+      findAvailablePort(config.backend.port),
+      findAvailablePort(config.frontend.port)
+    ]);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+  if (backendPort !== config.backend.port) {
+    log.step(`Backend port ${config.backend.port} in use, using ${backendPort}`);
+  }
+  if (frontendPort !== config.frontend.port) {
+    log.step(`Frontend port ${config.frontend.port} in use, using ${frontendPort}`);
+  }
+  log.info("Starting development servers...");
+  log.blank();
+  log.step(`Django      \u2192 http://localhost:${backendPort}`);
+  log.step(`Vite        \u2192 http://localhost:${frontendPort}`);
+  log.step(`Swagger     \u2192 http://localhost:${backendPort}/api/docs/`);
+  log.step("OpenAPI sync \u2192 watching backend .py files");
+  log.blank();
+  const syncCmd = `${process.execPath} ${path5.join(frontendDir, "node_modules", ".bin", "openapi-ts")}`;
+  const watcherCode = [
+    `const{watch}=require("fs"),{exec}=require("child_process");`,
+    `let t=null,s=false;`,
+    `watch(${JSON.stringify(backendDir)},{recursive:true},(e,f)=>{`,
+    `if(!f||!f.endsWith(".py"))return;`,
+    `if(f.startsWith("venv/")||f.includes("__pycache__")||f.includes("/migrations/"))return;`,
+    `if(t)clearTimeout(t);`,
+    `t=setTimeout(()=>{`,
+    `if(s)return;s=true;`,
+    `console.log("Backend change detected \u2014 syncing OpenAPI types...");`,
+    `exec(${JSON.stringify(syncCmd)},{cwd:${JSON.stringify(frontendDir)}},(err,o,se)=>{`,
+    `s=false;`,
+    `if(err)console.error("Sync failed:",se||err.message);`,
+    `else console.log("OpenAPI types synced");`,
+    `})`,
+    `},2000)});`,
+    `console.log("Watching for .py changes...");`
+  ].join("");
+  const { result } = concurrently(
+    [
+      {
+        command: `./venv/bin/python manage.py runserver 0.0.0.0:${backendPort}`,
+        name: "django",
+        cwd: backendDir,
+        prefixColor: "green"
+      },
+      {
+        command: "npm run dev",
+        name: "vite",
+        cwd: frontendDir,
+        prefixColor: "blue"
+      },
+      {
+        command: `node -e '${watcherCode}'`,
+        name: "sync",
+        cwd: frontendDir,
+        prefixColor: "yellow"
+      }
+    ],
+    {
+      prefix: "name",
+      killOthers: ["failure"],
+      restartTries: 3
+    }
+  );
+  const shutdown = () => {
+    log.blank();
+    log.info("Development servers stopped.");
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  try {
+    await result;
+  } catch {
+  }
+}
+
+// src/commands/sync.ts
+import path6 from "path";
+import fs5 from "fs";
+async function sync() {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const backendDir = getBackendDir(root);
+  const frontendDir = getFrontendDir(root);
+  const s = spinner("Syncing OpenAPI schema to frontend...");
+  try {
+    const schemaPath = path6.join(frontendDir, "_schema.yml");
+    await execPython(["manage.py", "spectacular", "--file", schemaPath], backendDir, true);
+    const configPath = path6.join(frontendDir, "openapi-ts.config.ts");
+    const configBackup = fs5.readFileSync(configPath, "utf-8");
+    const configWithFile = configBackup.replace(
+      /path:\s*['"]http[^'"]+['"]/,
+      `path: './_schema.yml'`
+    );
+    fs5.writeFileSync(configPath, configWithFile, "utf-8");
+    try {
+      await exec(process.execPath, [path6.join(frontendDir, "node_modules", ".bin", "openapi-ts")], {
+        cwd: frontendDir,
+        silent: true
+      });
+    } finally {
+      fs5.writeFileSync(configPath, configBackup, "utf-8");
+      if (fs5.existsSync(schemaPath)) fs5.unlinkSync(schemaPath);
+    }
+    s.succeed("Frontend types, schemas, and hooks synced from OpenAPI spec");
+    log.blank();
+    log.step("Generated files in frontend/src/api/generated/:");
+    log.step("  types.gen.ts            \u2192 TypeScript interfaces");
+    log.step("  zod.gen.ts              \u2192 Zod validation schemas");
+    log.step("  sdk.gen.ts              \u2192 API client functions");
+    log.step("  @tanstack/react-query.gen.ts \u2192 TanStack Query hooks");
+    log.blank();
+  } catch (error) {
+    s.fail("Failed to sync OpenAPI schema");
+    log.error(error.message || error);
+    process.exit(1);
+  }
+}
+
+// src/commands/make-resource.ts
+import path7 from "path";
+import fs6 from "fs";
+
+// src/utils/names.ts
+import { pascalCase, snakeCase, kebabCase, camelCase } from "change-case";
+import pluralize from "pluralize";
+function generateNames(input) {
+  const singular = pascalCase(input);
+  const plural = pluralize(singular);
+  return {
+    Name: singular,
+    Names: plural,
+    name: camelCase(singular),
+    names: camelCase(plural),
+    snake: snakeCase(singular),
+    snakes: snakeCase(plural),
+    kebab: kebabCase(singular),
+    kebabs: kebabCase(plural),
+    UPPER: snakeCase(singular).toUpperCase(),
+    UPPERS: snakeCase(plural).toUpperCase()
+  };
+}
+
+// src/commands/make-resource.ts
+async function makeResource(name) {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const names = generateNames(name);
+  const backendDir = getBackendDir(root);
+  const frontendDir = getFrontendDir(root);
+  const templatesDir = getTemplatesDir();
+  const backendAppDir = path7.join(backendDir, "apps", names.snakes);
+  if (fs6.existsSync(backendAppDir)) {
+    log.error(`Backend app "${names.snakes}" already exists.`);
+    process.exit(1);
+  }
+  const frontendPageDir = path7.join(frontendDir, "src", "pages", names.kebabs);
+  if (fs6.existsSync(frontendPageDir)) {
+    log.error(`Frontend page "${names.kebabs}" already exists.`);
+    process.exit(1);
+  }
+  const context = { ...names, projectName: name };
+  const backendSpinner = spinner(`Creating backend app: apps/${names.snakes}/`);
+  try {
+    renderDirectory(
+      path7.join(templatesDir, "resource", "backend"),
+      backendAppDir,
+      context
+    );
+    backendSpinner.succeed(`Created backend/apps/${names.snakes}/`);
+  } catch (error) {
+    backendSpinner.fail("Failed to create backend app");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const registerSpinner = spinner("Registering app in Django settings...");
+  try {
+    const settingsPath = path7.join(backendDir, "config", "settings", "base.py");
+    appendAfterMarker(
+      settingsPath,
+      "# blacksmith:apps",
+      `    'apps.${names.snakes}',`
+    );
+    registerSpinner.succeed("Registered in INSTALLED_APPS");
+  } catch (error) {
+    registerSpinner.fail("Failed to register app in settings");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const urlSpinner = spinner("Registering API URLs...");
+  try {
+    const urlsPath = path7.join(backendDir, "config", "urls.py");
+    insertBeforeMarker(
+      urlsPath,
+      "# blacksmith:urls",
+      `    path('api/${names.snakes}/', include('apps.${names.snakes}.urls')),`
+    );
+    urlSpinner.succeed("Registered API URLs");
+  } catch (error) {
+    urlSpinner.fail("Failed to register URLs");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const migrateSpinner = spinner("Running migrations...");
+  try {
+    await execPython(["manage.py", "makemigrations", names.snakes], backendDir, true);
+    await execPython(["manage.py", "migrate"], backendDir, true);
+    migrateSpinner.succeed("Migrations complete");
+  } catch (error) {
+    migrateSpinner.fail("Migration failed");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const syncSpinner = spinner("Syncing OpenAPI schema...");
+  try {
+    const schemaPath = path7.join(frontendDir, "_schema.yml");
+    await execPython(["manage.py", "spectacular", "--file", schemaPath], backendDir, true);
+    const configPath = path7.join(frontendDir, "openapi-ts.config.ts");
+    const configBackup = fs6.readFileSync(configPath, "utf-8");
+    const configWithFile = configBackup.replace(
+      /path:\s*['"]http[^'"]+['"]/,
+      `path: './_schema.yml'`
+    );
+    fs6.writeFileSync(configPath, configWithFile, "utf-8");
+    try {
+      await exec(process.execPath, [path7.join(frontendDir, "node_modules", ".bin", "openapi-ts")], {
+        cwd: frontendDir,
+        silent: true
+      });
+    } finally {
+      fs6.writeFileSync(configPath, configBackup, "utf-8");
+      if (fs6.existsSync(schemaPath)) fs6.unlinkSync(schemaPath);
+    }
+    syncSpinner.succeed("Frontend types and hooks regenerated");
+  } catch {
+    syncSpinner.warn('Could not sync OpenAPI. Run "blacksmith sync" manually.');
+  }
+  const frontendSpinner = spinner(`Creating frontend page: pages/${names.kebabs}/`);
+  try {
+    renderDirectory(
+      path7.join(templatesDir, "resource", "pages"),
+      frontendPageDir,
+      context
+    );
+    frontendSpinner.succeed(`Created frontend/src/pages/${names.kebabs}/`);
+  } catch (error) {
+    frontendSpinner.fail("Failed to create frontend page");
+    log.error(error.message);
+    process.exit(1);
+  }
+  const pathSpinner = spinner("Registering route path...");
+  try {
+    const pathsFile = path7.join(frontendDir, "src", "router", "paths.ts");
+    insertBeforeMarker(
+      pathsFile,
+      "// blacksmith:path",
+      `  ${names.Names} = '/${names.kebabs}',`
+    );
+    pathSpinner.succeed("Registered route path");
+  } catch {
+    pathSpinner.warn("Could not auto-register path. Add it manually to frontend/src/router/paths.ts");
+  }
+  const routeSpinner = spinner("Registering frontend routes...");
+  try {
+    const routesPath = path7.join(frontendDir, "src", "router", "routes.tsx");
+    insertBeforeMarker(
+      routesPath,
+      "// blacksmith:import",
+      `import { ${names.names}Routes } from '@/pages/${names.kebabs}'`
+    );
+    insertBeforeMarker(
+      routesPath,
+      "// blacksmith:routes",
+      `  ...${names.names}Routes,`
+    );
+    routeSpinner.succeed("Registered frontend routes");
+  } catch {
+    routeSpinner.warn("Could not auto-register routes. Add them manually to frontend/src/router/routes.tsx");
+  }
+  log.blank();
+  log.success(`Resource "${names.Name}" created successfully!`);
+  log.blank();
+}
+
+// src/commands/build.ts
+async function build() {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const backendDir = getBackendDir(root);
+  const frontendDir = getFrontendDir(root);
+  const frontendSpinner = spinner("Building frontend...");
+  try {
+    await exec("npm", ["run", "build"], { cwd: frontendDir, silent: true });
+    frontendSpinner.succeed("Frontend built \u2192 frontend/dist/");
+  } catch (error) {
+    frontendSpinner.fail("Frontend build failed");
+    log.error(error.message || error);
+    process.exit(1);
+  }
+  const backendSpinner = spinner("Collecting static files...");
+  try {
+    await execPython(
+      ["manage.py", "collectstatic", "--noinput"],
+      backendDir,
+      true
+    );
+    backendSpinner.succeed("Static files collected");
+  } catch (error) {
+    backendSpinner.fail("Failed to collect static files");
+    log.error(error.message || error);
+    process.exit(1);
+  }
+  log.blank();
+  log.success("Production build complete!");
+  log.blank();
+  log.step("Frontend assets: frontend/dist/");
+  log.step("Backend ready for deployment");
+  log.blank();
+}
+
+// src/commands/eject.ts
+import fs7 from "fs";
+import path8 from "path";
+async function eject() {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error("Not inside a Blacksmith project.");
+    process.exit(1);
+  }
+  const configPath = path8.join(root, "blacksmith.config.json");
+  if (fs7.existsSync(configPath)) {
+    fs7.unlinkSync(configPath);
+  }
+  log.success("Blacksmith has been ejected.");
+  log.blank();
+  log.step("Your project is now a standard Django + React project.");
+  log.step("All generated code remains in place and is fully owned by you.");
+  log.step("The blacksmith CLI commands will no longer work in this directory.");
+  log.blank();
+  log.info("To continue development without Blacksmith:");
+  log.step("Backend:  cd backend && ./venv/bin/python manage.py runserver");
+  log.step("Frontend: cd frontend && npm run dev");
+  log.step("Codegen:  cd frontend && npx openapi-ts");
+  log.blank();
+}
+
+// src/commands/skills.ts
+import fs8 from "fs";
+var allSkills = [
+  projectOverviewSkill,
+  djangoSkill,
+  djangoRestAdvancedSkill,
+  apiDocumentationSkill,
+  reactSkill,
+  blacksmithUiReactSkill,
+  blacksmithUiFormsSkill,
+  blacksmithUiAuthSkill,
+  blacksmithHooksSkill,
+  blacksmithCliSkill,
+  cleanCodeSkill,
+  aiGuidelinesSkill
+];
+async function setupSkills(options) {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const config = loadConfig(root);
+  await setupAiDev({
+    projectDir: root,
+    projectName: config.name,
+    includeBlacksmithUiSkill: options.blacksmithUiSkill !== false
+  });
+  log.blank();
+  log.success("AI skills generated:");
+  log.step("  CLAUDE.md                  \u2192 project overview + guidelines");
+  log.step("  .claude/skills/*/SKILL.md  \u2192 detailed skill files");
+}
+function listSkills() {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  const hasClaude = fs8.existsSync(`${root}/CLAUDE.md`);
+  const hasSkillsDir = fs8.existsSync(`${root}/.claude/skills`);
+  const inlineSkills = allSkills.filter((s) => !s.name);
+  const fileSkills = allSkills.filter((s) => s.name);
+  log.info("Inline skills (in CLAUDE.md):");
+  for (const skill of inlineSkills) {
+    log.step(`  ${skill.id}`);
+  }
+  log.blank();
+  log.info("File-based skills (in .claude/skills/):");
+  for (const skill of fileSkills) {
+    const exists = hasSkillsDir && fs8.existsSync(`${root}/.claude/skills/${skill.id}/SKILL.md`);
+    const status = exists ? "\u2713" : "\u2717";
+    log.step(`  ${status} ${skill.id}/SKILL.md \u2014 ${skill.name}`);
+  }
+  log.blank();
+  if (hasClaude && hasSkillsDir) {
+    log.success('AI skills are set up. Run "blacksmith setup:ai" to regenerate.');
+  } else {
+    log.info('Run "blacksmith setup:ai" to generate AI skills.');
+  }
+}
+
+// src/commands/backend.ts
+async function backend(args) {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  if (args.length === 0) {
+    log.error("Please provide a Django management command.");
+    log.step("Usage: blacksmith backend <command> [args...]");
+    log.step("Example: blacksmith backend createsuperuser");
+    process.exit(1);
+  }
+  const backendDir = getBackendDir(root);
+  try {
+    await execPython(["manage.py", ...args], backendDir);
+  } catch {
+    process.exit(1);
+  }
+}
+
+// src/commands/frontend.ts
+async function frontend(args) {
+  let root;
+  try {
+    root = findProjectRoot();
+  } catch {
+    log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
+    process.exit(1);
+  }
+  if (args.length === 0) {
+    log.error("Please provide an npm command.");
+    log.step("Usage: blacksmith frontend <command> [args...]");
+    log.step("Example: blacksmith frontend install axios");
+    process.exit(1);
+  }
+  const frontendDir = getFrontendDir(root);
+  try {
+    await exec("npm", args, { cwd: frontendDir });
+  } catch {
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("blacksmith").description("Fullstack Django + React framework").version("0.1.0").hook("preAction", () => {
+  banner();
+});
+program.command("init").argument("[name]", "Project name").option("--ai", "Set up AI development skills and documentation (CLAUDE.md)").option("--no-blacksmith-ui-skill", "Disable blacksmith-ui skill when using --ai").option("-b, --backend-port <port>", "Django backend port (default: 8000)").option("-f, --frontend-port <port>", "Vite frontend port (default: 5173)").option("-t, --theme-color <color>", "Theme color (zinc, slate, blue, green, orange, red, violet)").description("Create a new Blacksmith project").action(init);
+program.command("dev").description("Start development servers (Django + Vite + OpenAPI sync)").action(dev);
+program.command("sync").description("Sync OpenAPI schema to frontend types, schemas, and hooks").action(sync);
+program.command("make:resource").argument("<name>", "Resource name (PascalCase, e.g. BlogPost)").description("Create a new resource (model, serializer, viewset, hooks, pages)").action(makeResource);
+program.command("build").description("Build both frontend and backend for production").action(build);
+program.command("eject").description("Remove Blacksmith, keep a clean Django + React project").action(eject);
+program.command("setup:ai").description("Generate CLAUDE.md with AI development skills for the project").option("--no-blacksmith-ui-skill", "Exclude blacksmith-ui skill").action(setupSkills);
+program.command("skills").description("List all available AI development skills").action(listSkills);
+program.command("backend").argument("[args...]", "Django management command and arguments").description("Run a Django management command (e.g. blacksmith backend createsuperuser)").allowUnknownOption().action(backend);
+program.command("frontend").argument("[args...]", "npm command and arguments").description("Run an npm command in the frontend (e.g. blacksmith frontend install axios)").allowUnknownOption().action(frontend);
+program.parse();
+//# sourceMappingURL=index.js.map