blacksmith-cli 0.1.7 → 0.1.9

package/dist/index.js

@@ -858,19 +858,23 @@ function banner() {
   console.log(chalk.dim("  Welcome to Blacksmith \u2014 forge fullstack apps with one command."));
   console.log();
 }
-function printNextSteps(projectName, backendPort = 8e3, frontendPort = 5173) {
+function printNextSteps(projectName, projectType = "fullstack", backendPort, frontendPort) {
   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(`  ${chalk.cyan("blacksmith dev")}        ${chalk.dim("# Start development server" + (projectType === "fullstack" ? "s" : ""))}`);
   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/`));
+  if (backendPort !== void 0) {
+    console.log(chalk.dim(`  Django:   http://localhost:${backendPort}`));
+    console.log(chalk.dim(`  Swagger:  http://localhost:${backendPort}/api/docs/`));
+    console.log(chalk.dim(`  ReDoc:    http://localhost:${backendPort}/api/redoc/`));
+  }
+  if (frontendPort !== void 0) {
+    console.log(chalk.dim(`  React:    http://localhost:${frontendPort}`));
+  }
   log.blank();
 }
 
@@ -1018,13 +1022,33 @@ function findProjectRoot(startDir) {
     'Not inside a Blacksmith project. Run "blacksmith init <name>" to create one, or navigate to an existing Blacksmith project.'
   );
 }
+function getProjectType(projectRoot) {
+  const config = loadConfig(projectRoot);
+  return config.type || "fullstack";
+}
+function hasBackend(projectRoot) {
+  const type = getProjectType(projectRoot);
+  return type === "fullstack" || type === "backend";
+}
+function hasFrontend(projectRoot) {
+  const type = getProjectType(projectRoot);
+  return type === "fullstack" || type === "frontend";
+}
 function getBackendDir(projectRoot) {
   const root = projectRoot || findProjectRoot();
-  return path3.join(root, "backend");
+  const type = getProjectType(root);
+  if (type === "frontend") {
+    throw new Error("This is a frontend-only project. There is no backend directory.");
+  }
+  return type === "backend" ? root : path3.join(root, "backend");
 }
 function getFrontendDir(projectRoot) {
   const root = projectRoot || findProjectRoot();
-  return path3.join(root, "frontend");
+  const type = getProjectType(root);
+  if (type === "backend") {
+    throw new Error("This is a backend-only project. There is no frontend directory.");
+  }
+  return type === "frontend" ? root : path3.join(root, "frontend");
 }
 function loadConfig(projectRoot) {
   const root = projectRoot || findProjectRoot();
@@ -1052,11 +1076,12 @@ var coreRulesSkill = {
 - **Typography**: Use \`Heading\` and \`Text\` \u2014 NEVER raw \`<h1>\`\u2013\`<h6>\`, \`<p>\`, or \`<span>\` with text classes
 - **Separators**: Use \`Divider\` \u2014 NEVER \`<hr>\`
 - **Everything else**: \`Button\`, \`Card\`, \`Badge\`, \`Input\`, \`Table\`, \`Modal\`, \`Alert\`, \`Skeleton\`, \`Stat\`, etc.
+- **Exceptions**: Semantic HTML landmarks (\`<main>\`, \`<section>\`, \`<nav>\`, \`<header>\`, \`<footer>\`, \`<article>\`, \`<aside>\`) are acceptable for page structure. \`<form>\` is acceptable with React Hook Form. \`<Link>\` from react-router-dom for navigation
 - See the \`chakra-ui-react\` skill for the full 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
+- Pages import components, call hooks, and compose JSX \u2014 they should not contain business logic or large JSX blocks
+- Break every page into child components in a \`components/\` folder. Aim for clarity, not a strict line count
 - See the \`page-structure\` skill for the full pattern with examples
 
 ### 3. Components Render, Hooks Think
@@ -1071,14 +1096,34 @@ var coreRulesSkill = {
 - 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
+### 5. API Hooks vs UI Hooks \u2014 Two Different Places
+- **API hooks** (data fetching) \u2192 \`src/api/hooks/<resource>/\` \u2014 queries, mutations, cache invalidation. Import as: \`import { usePosts } from '@/api/hooks/posts'\`
+- **UI hooks** (page logic) \u2192 \`pages/<page>/hooks/\` or \`features/<feature>/hooks/\` \u2014 form state, pagination, filtering, debouncing
+- Never put API data fetching in page-level hooks. Never put UI-only logic in \`src/api/hooks/\`
+- See the \`react-query\` skill for API hook conventions
+
+### 6. Use Generated API Client Code
+- Always check \`src/api/generated/\` first before writing any API calls \u2014 use the generated types, query options, mutations, and query keys
+- Only write manual API client code when no generated code exists for the endpoint (e.g. the endpoint hasn't been synced yet)
+- **In fullstack projects:** after creating or modifying any backend endpoint (views, serializers, URLs), run \`blacksmith sync\` from the project root to regenerate the frontend API client before writing frontend code that consumes it
+
+### 7. Prioritize Modularization and Code Reuse
+- **Always reuse before writing** \u2014 before creating a new function, search the codebase for an existing one that does the same thing or can be extended
+- **Extract reusable logic to utils** \u2014 if a function can be useful outside the file it lives in, move it to a \`utils/\` folder. This applies to both frontend and backend
+  - Frontend: page/feature-scoped \u2192 \`<page>/utils/\`; app-wide \u2192 \`src/shared/utils/\`
+  - Backend: app-scoped \u2192 \`apps/<app>/utils.py\` (or \`utils/\` package); project-wide \u2192 \`utils/\` at the backend root
+- **No inline helper functions** \u2014 standalone functions sitting in component files, view files, or serializer files should be extracted to utils
+- **No duplicated logic** \u2014 if the same logic appears in two places, extract it into a shared utility immediately
+- See the \`frontend-modularization\` and \`backend-modularization\` skills for full conventions
+
+### 8. 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/             # Page-local hooks (UI logic, not API hooks)
+\u2514\u2500\u2500 hooks/             # Page-local hooks (UI logic only, not API hooks)
 \`\`\`
 - See the \`page-structure\` skill for full conventions
 `;
@@ -1094,49 +1139,80 @@ var projectOverviewSkill = {
   render(ctx) {
     return `# ${ctx.projectName}
 
-A fullstack web application built with **Django** (backend) and **React** (frontend), scaffolded by **Blacksmith CLI**.
+A web application scaffolded by **Blacksmith CLI**. Check \`blacksmith.config.json\` at the project root for the project type (\`fullstack\`, \`backend\`, or \`frontend\`) and configuration.
 
 ## Project Structure
 
+The structure depends on the project type configured in \`blacksmith.config.json\`:
+
+**Fullstack** (\`type: "fullstack"\`) \u2014 Django backend + React frontend in subdirectories:
 \`\`\`
 ${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 utils/            # Shared backend utilities
 \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 api/          # API client and hooks
 \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
+\u2502   \u2502   \u251C\u2500\u2500 router/       # React Router setup
+\u2502   \u2502   \u2514\u2500\u2500 shared/       # Shared components, hooks, utils
+\u2502   \u2514\u2500\u2500 package.json
 \u251C\u2500\u2500 blacksmith.config.json
-\u2514\u2500\u2500 CLAUDE.md             # This file
+\u2514\u2500\u2500 CLAUDE.md
+\`\`\`
+
+**Backend-only** (\`type: "backend"\`) \u2014 Django project at root:
+\`\`\`
+${ctx.projectName}/
+\u251C\u2500\u2500 apps/
+\u251C\u2500\u2500 config/
+\u251C\u2500\u2500 utils/
+\u251C\u2500\u2500 manage.py
+\u251C\u2500\u2500 venv/
+\u2514\u2500\u2500 blacksmith.config.json
+\`\`\`
+
+**Frontend-only** (\`type: "frontend"\`) \u2014 React project at root:
+\`\`\`
+${ctx.projectName}/
+\u251C\u2500\u2500 src/
+\u2502   \u251C\u2500\u2500 api/
+\u2502   \u251C\u2500\u2500 pages/
+\u2502   \u251C\u2500\u2500 router/
+\u2502   \u2514\u2500\u2500 shared/
+\u251C\u2500\u2500 package.json
+\u2514\u2500\u2500 blacksmith.config.json
 \`\`\`
 
 ## 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
+| Command | Fullstack | Backend | Frontend |
+|---|---|---|---|
+| \`blacksmith dev\` | Django + Vite + sync | Django only | Vite only |
+| \`blacksmith sync\` | Regenerate frontend types | N/A | N/A |
+| \`blacksmith make:resource <Name>\` | Both ends | Backend only | Frontend only |
+| \`blacksmith build\` | Both | collectstatic | Vite build |
+| \`blacksmith eject\` | Remove Blacksmith | Remove Blacksmith | Remove Blacksmith |
 
 ## 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/\`
+**Fullstack:**
+1. Define models, serializers, and viewsets in the backend
+2. Run \`blacksmith sync\` to generate TypeScript types and API client
+3. Build frontend features using the generated hooks and types
+
+**Backend-only:**
+1. Define models, serializers, and viewsets
+2. Run migrations and test endpoints
+
+**Frontend-only:**
+1. Build pages and components
+2. Create API hooks in \`src/api/hooks/\` for data fetching
 `;
   }
 };
@@ -1179,6 +1255,11 @@ var djangoSkill = {
 - 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
 
+### Sync After Backend Changes (Fullstack Projects)
+> **RULE: After creating or modifying any endpoint (views, serializers, URLs, or model fields that affect the API), run \`blacksmith sync\` from the project root before writing frontend code that uses the endpoint.**
+>
+> This regenerates the TypeScript types, query options, mutations, and Zod schemas in \`frontend/src/api/generated/\`. Without syncing, the frontend will be working against stale or missing type definitions.
+
 ### URLs
 - Each app has its own \`urls.py\` with a \`DefaultRouter\`
 - Register viewsets on the router: \`router.register('resources', ResourceViewSet)\`
@@ -2069,6 +2150,179 @@ def internal_health_check(self, request):
   }
 };
 
+// src/skills/backend-modularization.ts
+init_esm_shims();
+var backendModularizationSkill = {
+  id: "backend-modularization",
+  name: "Backend Modularization",
+  description: "When and how to promote Django modules (models, serializers, views, tests, admin) from single files to packages with per-class files.",
+  render(_ctx) {
+    return `## Backend Modularization
+
+> **RULE: When a Django module contains more than one class, promote it from a single file to a package (folder) with one class per file and re-export everything from \`__init__.py\`.**
+
+This applies to \`models.py\`, \`serializers.py\`, \`views.py\`, \`admin.py\`, and \`tests.py\`.
+
+### Single-Class Module \u2014 Keep as a File
+
+When an app has only one model, one serializer, etc., a single file is fine:
+
+\`\`\`
+apps/posts/
+\u251C\u2500\u2500 __init__.py
+\u251C\u2500\u2500 models.py           # one model: Post
+\u251C\u2500\u2500 serializers.py      # one serializer: PostSerializer
+\u251C\u2500\u2500 views.py            # one viewset: PostViewSet
+\u251C\u2500\u2500 urls.py
+\u251C\u2500\u2500 admin.py
+\u2514\u2500\u2500 tests.py
+\`\`\`
+
+### Multi-Class Module \u2014 Promote to a Package
+
+When a second class is added, convert the file to a package:
+
+\`\`\`
+apps/posts/
+\u251C\u2500\u2500 __init__.py
+\u251C\u2500\u2500 models/
+\u2502   \u251C\u2500\u2500 __init__.py     # from .post import *  /  from .comment import *
+\u2502   \u251C\u2500\u2500 post.py         # class Post(models.Model)
+\u2502   \u2514\u2500\u2500 comment.py      # class Comment(models.Model)
+\u251C\u2500\u2500 serializers/
+\u2502   \u251C\u2500\u2500 __init__.py     # from .post_serializer import *  /  from .comment_serializer import *
+\u2502   \u251C\u2500\u2500 post_serializer.py
+\u2502   \u2514\u2500\u2500 comment_serializer.py
+\u251C\u2500\u2500 views/
+\u2502   \u251C\u2500\u2500 __init__.py     # from .post_views import *  /  from .comment_views import *
+\u2502   \u251C\u2500\u2500 post_views.py
+\u2502   \u2514\u2500\u2500 comment_views.py
+\u251C\u2500\u2500 admin/
+\u2502   \u251C\u2500\u2500 __init__.py     # from .post_admin import *  /  from .comment_admin import *
+\u2502   \u251C\u2500\u2500 post_admin.py
+\u2502   \u2514\u2500\u2500 comment_admin.py
+\u251C\u2500\u2500 tests/
+\u2502   \u251C\u2500\u2500 __init__.py
+\u2502   \u251C\u2500\u2500 test_post.py
+\u2502   \u2514\u2500\u2500 test_comment.py
+\u251C\u2500\u2500 urls.py
+\u2514\u2500\u2500 ...
+\`\`\`
+
+### The \`__init__.py\` Contract
+
+Every package \`__init__.py\` re-exports all public names so that imports from outside the app remain unchanged:
+
+\`\`\`python
+# models/__init__.py
+from .post import *
+from .comment import *
+\`\`\`
+
+This means the rest of the codebase continues to use:
+\`\`\`python
+from apps.posts.models import Post, Comment
+from apps.posts.serializers import PostSerializer, CommentSerializer
+from apps.posts.views import PostViewSet, CommentViewSet
+\`\`\`
+
+No import paths change when you promote a file to a package \u2014 that is the whole point.
+
+### File Naming Conventions
+
+| Module | Single file | Package file names |
+|---|---|---|
+| Models | \`models.py\` | \`models/<model_name>.py\` (e.g. \`post.py\`, \`comment.py\`) |
+| Serializers | \`serializers.py\` | \`serializers/<model_name>_serializer.py\` |
+| Views | \`views.py\` | \`views/<model_name>_views.py\` |
+| Admin | \`admin.py\` | \`admin/<model_name>_admin.py\` |
+| Tests | \`tests.py\` | \`tests/test_<model_name>.py\` |
+
+### Using \`__all__\` in Each File
+
+Define \`__all__\` in each file to make the \`from .module import *\` explicit:
+
+\`\`\`python
+# models/post.py
+from django.db import models
+
+__all__ = ['Post']
+
+class Post(models.Model):
+    title = models.CharField(max_length=255)
+    content = models.TextField()
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.title
+\`\`\`
+
+\`\`\`python
+# serializers/post_serializer.py
+from rest_framework import serializers
+from apps.posts.models import Post
+
+__all__ = ['PostSerializer']
+
+class PostSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Post
+        fields = '__all__'
+\`\`\`
+
+### When to Promote
+
+- **Do promote** when a module contains 2 or more classes (models, serializers, viewsets, admin classes)
+- **Don't promote** \`urls.py\` \u2014 URL configuration is typically one file regardless of size, since routers naturally aggregate
+- **Don't promote** a module just because it is long \u2014 if it has one class with many methods, keep it as a file; length alone is not a reason
+- **Don't promote preemptively** \u2014 start with a single file and convert when the second class arrives
+
+### Migration Considerations
+
+When promoting \`models.py\` to a \`models/\` package, Django migrations continue to work as long as the import path in \`__init__.py\` is correct. Existing migrations reference the app label, not the file path, so no migration changes are needed.
+
+### Utility Functions
+
+> **RULE: Reuse before writing. If a function can be used outside the file it lives in, it belongs in utils.**
+
+- **App-scoped utilities** \u2192 \`apps/<app>/utils.py\` (or \`utils/\` package if multiple files)
+- **Project-wide utilities** \u2192 \`utils/\` at the backend root (e.g. \`utils/formatting.py\`, \`utils/permissions.py\`)
+
+Before writing any helper function, search the codebase for an existing one. If the same logic exists in two places, extract it into a shared utility immediately.
+
+\`\`\`python
+# BAD \u2014 helper function sitting in views.py
+def parse_date_range(request):
+    ...
+
+class ReportViewSet(ModelViewSet):
+    def get_queryset(self):
+        start, end = parse_date_range(self.request)
+        ...
+
+# GOOD \u2014 extracted to utils
+# apps/reports/utils.py
+def parse_date_range(request):
+    ...
+
+# apps/reports/views.py
+from apps.reports.utils import parse_date_range
+\`\`\`
+
+\`utils.py\` follows the same promotion rule \u2014 when it has multiple unrelated groups of functions, promote it to a \`utils/\` package with focused files (\`utils/dates.py\`, \`utils/formatting.py\`, etc.) and re-export from \`__init__.py\`.
+
+### Summary
+
+1. **One class per file** when a module is promoted to a package
+2. **\`__init__.py\` re-exports everything** \u2014 external imports never change
+3. **Use \`__all__\`** in each file to be explicit about exports
+4. **Promote at 2+ classes** \u2014 not preemptively, not based on line count alone
+5. **\`urls.py\` stays a file** \u2014 it does not get promoted
+6. **Extract reusable functions to utils** \u2014 search before writing, no duplicated logic
+`;
+  }
+};
+
 // src/skills/react.ts
 init_esm_shims();
 var reactSkill = {
@@ -2298,9 +2552,14 @@ if (errorMessage) {
 
 ### Creating Resource Hook Files
 
-When building hooks for a resource, create two files:
+> **RULE: All API hooks live in \`src/api/hooks/<resource>/\` \u2014 never in page-level \`hooks/\` folders.**
+> Page-level \`hooks/\` are for UI logic only (form state, filters, pagination). API data access is centralized in \`src/api/hooks/\`.
+
+When building hooks for a resource, create a folder under \`src/api/hooks/\` with these files:
 
-**\`use-<resources>.ts\`** \u2014 List query hook:
+**\`src/api/hooks/<resource>/index.ts\`** \u2014 Re-exports all hooks from the folder.
+
+**\`src/api/hooks/<resource>/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'
@@ -2330,7 +2589,7 @@ export function usePosts(params: UsePostsParams = {}) {
 }
 \`\`\`
 
-**\`use-<resource>-mutations.ts\`** \u2014 Create/update/delete hooks:
+**\`src/api/hooks/<resource>/use-<resource>-mutations.ts\`** \u2014 Create/update/delete hooks:
 \`\`\`tsx
 import { useApiMutation } from '@/shared/hooks/use-api-mutation'
 import {
@@ -2371,7 +2630,7 @@ export function useDeletePost() {
 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
+4. **Always prefer generated API client code** \u2014 use the generated options, mutations, types, and query keys from \`@/api/generated/\`. Check \`@/api/generated/@tanstack/react-query.gen\` for available query options and mutations before writing anything manually. Only write a manual \`queryFn\` as a last resort when no generated code exists for the endpoint (e.g. the backend endpoint hasn't been synced yet)
 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\`
@@ -3157,62 +3416,108 @@ var chakraUiAuthSkill = {
     return `## Custom Auth System \u2014 Authentication Context & Hooks
 
 > **RULE: Use the local AuthProvider and useAuth hook for all auth functionality.**
-> Auth components (LoginForm, RegisterForm, etc.) are custom implementations in \`frontend/src/features/auth/\`.
+> Auth components and pages are custom implementations in \`src/features/auth/\`.
+
+### Imports
 
 \`\`\`tsx
-import { AuthProvider } from '@/features/auth/context'
 import { useAuth } from '@/features/auth/hooks/use-auth'
-import type { User, AuthState } from '@/features/auth/types'
+import type { User } from '@/features/auth/types'
 \`\`\`
 
-### Context & Provider
+### useAuth() Hook
 
-- \`AuthProvider\` \u2014 Context provider wrapping the app. Manages auth state, token storage, and session lifecycle.
-  - Place at the app root, inside \`ChakraProvider\`.
-  - Props: \`config?: { adapter?: AuthAdapter }\`
+Returns auth state and actions. Use this everywhere \u2014 never manage auth state manually.
 
-### Types
+\`\`\`tsx
+const { user, isAuthenticated, loading, error, signInWithEmail, signOut } = useAuth()
+\`\`\`
 
+| Field | Type | Description |
+|-------|------|-------------|
+| \`user\` | \`User \\| null\` | Current authenticated user |
+| \`isAuthenticated\` | \`boolean\` | Whether the user is logged in |
+| \`loading\` | \`boolean\` | Auth state is being resolved |
+| \`error\` | \`string \\| null\` | Last auth error message |
+| \`signInWithEmail\` | \`(email, password) => Promise\` | Log in |
+| \`signUpWithEmail\` | \`(email, password, displayName?) => Promise\` | Register |
+| \`signOut\` | \`() => Promise\` | Log out |
+| \`sendPasswordResetEmail\` | \`(email) => Promise\` | Request password reset |
+| \`confirmPasswordReset\` | \`(code, newPassword) => Promise\` | Set new password |
+
+### Usage Examples
+
+**Conditionally render based on auth:**
 \`\`\`tsx
-interface User {
-  id: string
-  email: string
-  displayName?: string
-  avatar?: string
+import { useAuth } from '@/features/auth/hooks/use-auth'
+
+function UserGreeting() {
+  const { user, isAuthenticated } = useAuth()
+
+  if (!isAuthenticated) return <Text>Please log in.</Text>
+  return <Text>Welcome, {user?.email}</Text>
 }
+\`\`\`
 
-interface AuthState {
-  user: User | null
-  loading: boolean
-  error: string | null
-  isAuthenticated: boolean
+**Protected action:**
+\`\`\`tsx
+function LogoutButton() {
+  const { signOut } = useAuth()
+
+  return <Button onClick={signOut} variant="ghost">Sign out</Button>
 }
 \`\`\`
 
-### Hooks
+**Login form integration:**
+\`\`\`tsx
+import { useAuth } from '@/features/auth/hooks/use-auth'
 
-- \`useAuth()\` \u2014 Hook for auth state and actions
-  - Returns: \`user\`, \`loading\`, \`error\`, \`isAuthenticated\`, \`signInWithEmail(email, password)\`, \`signUpWithEmail(email, password, displayName?)\`, \`signOut()\`, \`sendPasswordResetEmail(email)\`, \`confirmPasswordReset(code, newPassword)\`
+function useLoginForm() {
+  const { signInWithEmail, error } = useAuth()
+  const navigate = useNavigate()
 
-### Auth Pages
+  const onSubmit = async (data: { email: string; password: string }) => {
+    await signInWithEmail(data.email, data.password)
+    navigate(Path.Dashboard)
+  }
 
-Auth pages are custom implementations in \`frontend/src/features/auth/pages/\`:
+  return { onSubmit, error }
+}
+\`\`\`
 
-- \`LoginPage\` \u2014 Login form with email/password, validation, and navigation links
-- \`RegisterPage\` \u2014 Registration form with email, password, and display name
-- \`ForgotPasswordPage\` \u2014 Password reset email request
-- \`ResetPasswordPage\` \u2014 Set new password form
+### Auth Provider Setup
 
-Each auth page uses Chakra UI form components (\`FormControl\`, \`FormLabel\`, \`Input\`, \`Button\`, etc.) with React Hook Form + Zod validation.
+\`AuthProvider\` wraps the app (inside \`ChakraProvider\`) and manages token storage and session lifecycle:
 
-### Adapter
+\`\`\`tsx
+// app.tsx
+import { AuthProvider } from '@/features/auth/context'
 
-- \`AuthAdapter\` \u2014 Interface for custom auth backends (Django JWT adapter in \`frontend/src/features/auth/adapter.ts\`)
+function App() {
+  return (
+    <ChakraProvider>
+      <AuthProvider>
+        <RouterProvider router={router} />
+      </AuthProvider>
+    </ChakraProvider>
+  )
+}
+\`\`\`
+
+### Auth Pages
+
+Pre-built pages in \`src/features/auth/pages/\`:
+- \`LoginPage\` \u2014 email/password login with validation
+- \`RegisterPage\` \u2014 registration with email, password, display name
+- \`ForgotPasswordPage\` \u2014 password reset email request
+- \`ResetPasswordPage\` \u2014 set new password form
+
+All use Chakra UI form components with React Hook Form + Zod validation.
 
 ### Rules
-- NEVER manage auth state manually. Use \`useAuth()\` hook.
-- Auth pages live in \`frontend/src/features/auth/pages/\` and use Chakra UI components.
-- Use the \`Path\` enum for auth route paths (\`Path.Login\`, \`Path.Register\`, etc.).
+- NEVER manage auth state manually \u2014 always use \`useAuth()\`
+- Use the \`Path\` enum for auth route paths (\`Path.Login\`, \`Path.Register\`, etc.)
+- Auth adapter (Django JWT) lives in \`src/features/auth/adapter.ts\`
 `;
   }
 };
@@ -3222,20 +3527,16 @@ init_esm_shims();
 var blacksmithHooksSkill = {
   id: "blacksmith-hooks",
   name: "Custom Hooks & Chakra UI Hooks",
-  description: "Custom React hooks (local implementations) and Chakra UI built-in hooks for state, UI, layout, and responsiveness.",
+  description: "Custom React hooks (scaffolded implementations) and Chakra UI built-in hooks for state, UI, layout, and responsiveness.",
   render(_ctx) {
     return `## Custom Hooks & Chakra UI Hooks
 
-A combination of local custom hooks and Chakra UI built-in hooks for common UI patterns.
-
-> **RULE: Use Chakra UI hooks when available, and local custom hooks for additional utilities.**
-> Before creating a new hook, check if one already exists below.
+> **RULE: Use Chakra UI hooks when available, and project custom hooks for additional utilities.**
+> Before creating a new hook, check if one already exists in \`src/shared/hooks/\` or in Chakra UI.
 
 ### Chakra UI Built-in Hooks
 
-\`\`\`tsx
-import { useColorMode, useDisclosure, useBreakpointValue, useMediaQuery, useToast } from '@chakra-ui/react'
-\`\`\`
+These are always available from \`@chakra-ui/react\`:
 
 | Hook | Description |
 |------|-------------|
@@ -3248,42 +3549,20 @@ import { useColorMode, useDisclosure, useBreakpointValue, useMediaQuery, useToas
 | \`useClipboard\` | Copy text to clipboard with status feedback |
 | \`useBoolean\` | Boolean state with \`on\`, \`off\`, \`toggle\` actions |
 | \`useOutsideClick\` | Detect clicks outside a ref element |
-| \`useControllable\` | Controlled/uncontrolled component pattern helper |
 | \`useMergeRefs\` | Merge multiple refs into one |
 | \`useTheme\` | Access the current Chakra UI theme object |
 
-### Custom Local Hooks
+### Scaffolded Project Hooks
 
-These are implemented locally in the project (e.g., in \`frontend/src/shared/hooks/\`):
+These hooks are scaffolded by Blacksmith and live in \`src/shared/hooks/\`. Check the directory to see which ones are available in your project:
 
-\`\`\`tsx
-import { useDebounce } from '@/shared/hooks/use-debounce'
-import { useLocalStorage } from '@/shared/hooks/use-local-storage'
-\`\`\`
+| Hook | File | Description |
+|------|------|-------------|
+| \`useDebounce\` | \`use-debounce.ts\` | Debounce a value with configurable delay |
+| \`useApiQuery\` | \`use-api-query.ts\` | Wrapper around \`useQuery\` with DRF error parsing and smart retry |
+| \`useApiMutation\` | \`use-api-mutation.ts\` | Wrapper around \`useMutation\` with DRF error parsing and cache invalidation |
 
-| Hook | Description |
-|------|-------------|
-| \`useDebounce\` | Debounce a value with configurable delay |
-| \`useDebouncedCallback\` | Debounce a callback function |
-| \`useLocalStorage\` | Persist state to localStorage with JSON serialization |
-| \`useSessionStorage\` | Persist state to sessionStorage with JSON serialization |
-| \`usePrevious\` | Track the previous value of a variable |
-| \`useInterval\` | setInterval wrapper with pause support |
-| \`useTimeout\` | setTimeout wrapper with manual clear |
-| \`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 |
-| \`useScrollPosition\` | Track window scroll position |
-| \`useScrollLock\` | Lock/unlock body scroll |
-| \`useOnline\` | Track network connectivity |
-| \`useWindowSize\` | Track window dimensions |
-| \`usePageVisibility\` | Detect page visibility state |
-| \`useIsMounted\` | Check if component is currently mounted |
-| \`useIsFirstRender\` | Check if this is the first render |
-| \`useUpdateEffect\` | useEffect that skips the initial render |
-| \`useIntersectionObserver\` | Observe element intersection with viewport |
-| \`useInfiniteScroll\` | Infinite scroll with threshold detection |
+> **Note:** Additional hooks (e.g. \`useLocalStorage\`, \`usePrevious\`, \`useInterval\`) can be created as needed in \`src/shared/hooks/\`. Always check if one exists before writing a new one.
 
 ### Common Patterns
 
@@ -3311,58 +3590,28 @@ function MyComponent() {
 }
 \`\`\`
 
-**Debounced search (custom hook):**
+**Debounced search:**
 \`\`\`tsx
 import { useDebounce } from '@/shared/hooks/use-debounce'
 import { Input } from '@chakra-ui/react'
 
-function SearchPage({ items }) {
+function SearchBar({ onSearch }: { onSearch: (q: string) => void }) {
   const [query, setQuery] = useState('')
   const debouncedQuery = useDebounce(query, 300)
-  // Use debouncedQuery for API calls or filtering
 
-  return (
-    <Input
-      value={query}
-      onChange={(e) => setQuery(e.target.value)}
-      placeholder="Search..."
-    />
-  )
+  useEffect(() => { onSearch(debouncedQuery) }, [debouncedQuery, onSearch])
+
+  return <Input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />
 }
 \`\`\`
 
-**Responsive layout with Chakra hook:**
+**Responsive layout:**
 \`\`\`tsx
 import { useBreakpointValue } from '@chakra-ui/react'
 
 function Layout({ children }) {
   const columns = useBreakpointValue({ base: 1, md: 2, lg: 3 })
-  const isMobile = useBreakpointValue({ base: true, md: false })
-
-  return isMobile ? <MobileLayout>{children}</MobileLayout> : <DesktopLayout>{children}</DesktopLayout>
-}
-\`\`\`
-
-**Color mode toggle:**
-\`\`\`tsx
-import { useColorMode, useColorModeValue, IconButton } from '@chakra-ui/react'
-import { Sun, Moon } from 'lucide-react'
-
-function ColorModeToggle() {
-  const { colorMode, toggleColorMode } = useColorMode()
-  const icon = colorMode === 'light' ? <Moon size={16} /> : <Sun size={16} />
-
-  return <IconButton aria-label="Toggle color mode" icon={icon} onClick={toggleColorMode} variant="ghost" />
-}
-\`\`\`
-
-**Persisted state with local storage:**
-\`\`\`tsx
-import { useLocalStorage } from '@/shared/hooks/use-local-storage'
-
-function Editor() {
-  const [saved, setSaved] = useLocalStorage('draft', '')
-  // saved persists across page refreshes
+  return <SimpleGrid columns={columns} spacing={6}>{children}</SimpleGrid>
 }
 \`\`\`
 `;
@@ -3385,12 +3634,12 @@ Blacksmith is the CLI that scaffolded and manages this project. It lives outside
 | 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 dev\` | Start development server(s) |
+| \`blacksmith sync\` | Regenerate frontend API client from Django OpenAPI schema (fullstack only) |
+| \`blacksmith make:resource <Name>\` | Scaffold a resource (backend, frontend, or both depending on project type) |
+| \`blacksmith build\` | Production build |
 | \`blacksmith eject\` | Remove Blacksmith dependency, keep a clean project |
-| \`blacksmith setup:ai\` | Generate CLAUDE.md with AI development skills |
+| \`blacksmith setup:ai\` | Generate/regenerate CLAUDE.md with AI development skills |
 | \`blacksmith skills\` | List all available AI development skills |
 
 ### Configuration
@@ -3401,47 +3650,46 @@ Project settings are stored in \`blacksmith.config.json\` at the project root:
 {
   "name": "my-app",
   "version": "0.1.0",
+  "type": "fullstack",
   "backend": { "port": 8000 },
   "frontend": { "port": 5173 }
 }
 \`\`\`
 
-- **Ports** are read by \`blacksmith dev\` and \`blacksmith sync\` \u2014 change them here, not in code
+- **\`type\`** \u2014 \`"fullstack"\`, \`"backend"\`, or \`"frontend"\`. Determines which commands and steps are available
+- **\`backend\`** \u2014 present for fullstack and backend projects. Absent for frontend-only
+- **\`frontend\`** \u2014 present for fullstack and frontend projects. Absent for backend-only
+- **Ports** are read by \`blacksmith dev\` \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)
+Depends on project type:
+- **Fullstack**: Runs three concurrent processes \u2014 Django, Vite, and an OpenAPI file watcher (auto-syncs types on \`.py\` changes)
+- **Backend**: Runs Django only
+- **Frontend**: Runs Vite only
 
-All three are managed by \`concurrently\` and stop together on Ctrl+C.
+All processes are managed by \`concurrently\` and stop together on Ctrl+C.
 
 ### How \`blacksmith make:resource\` Works
 
-Given a PascalCase name (e.g. \`BlogPost\`), it generates:
+Given a PascalCase name (e.g. \`BlogPost\`), it scaffolds based on project type:
 
-**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
+**Backend (fullstack and backend projects):**
+- \`apps/blog_posts/\` \u2014 model, serializer, viewset, urls, admin, tests
 - 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\`
+**Frontend (fullstack and frontend projects):**
+- \`src/api/hooks/blog-posts/\` \u2014 query and mutation hooks
+- \`src/pages/blog-posts/\` \u2014 list and detail pages
+- Registers route path in \`src/router/paths.ts\` and routes in \`src/router/routes.tsx\`
 
-Then runs \`blacksmith sync\` to generate the TypeScript API client.
+**Fullstack only:** Also runs \`blacksmith sync\` to generate the TypeScript API client.
 
-### How \`blacksmith sync\` Works
+### How \`blacksmith sync\` Works (Fullstack Only)
 
-1. Fetches the OpenAPI schema from \`http://localhost:<backend-port>/api/schema/\`
+1. Generates the OpenAPI schema offline using \`manage.py spectacular\`
 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
 
@@ -3454,11 +3702,12 @@ Then runs \`blacksmith sync\` to generate the TypeScript API client.
 blacksmith init
 
 # Skip prompts with flags
-blacksmith init my-app -b 9000 -f 3000 --ai
+blacksmith init my-app --type fullstack -b 9000 -f 3000 --ai
 \`\`\`
 
 | Flag | Description |
 |---|---|
+| \`--type <type>\` | Project type: fullstack, backend, or frontend (default: fullstack) |
 | \`-b, --backend-port <port>\` | Django port (default: 8000) |
 | \`-f, --frontend-port <port>\` | Vite port (default: 5173) |
 | \`--ai\` | Generate CLAUDE.md with project skills |
@@ -3472,252 +3721,91 @@ init_esm_shims();
 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 Chakra UI design language.",
+  description: "Design principles, spacing, typography, color, layout patterns, and interaction guidelines aligned with the Chakra UI design language.",
   render(_ctx) {
     return `## UI/UX Design System \u2014 Modern Flat Design
 
 > **Design philosophy: Clean, flat, content-first.**
-> Chakra UI follows a clean design language similar to 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.
+> Follow a design language similar to Linear, Vercel, and Stripe \u2014 minimal chrome, generous whitespace, subtle depth, and purposeful motion.
 
 ### 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.
+1. **Flat over skeuomorphic** \u2014 No gradients on surfaces, no heavy drop shadows, no bevels. Solid colors, subtle borders, and \`shadow="sm"\` / \`shadow="md"\` only where elevation is meaningful (cards, dropdowns, modals)
+2. **Content over decoration** \u2014 UI presents content, not decoration. 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. When in doubt, add more space
+4. **Consistency over creativity** \u2014 Every page should feel like part of the same app. Same spacing, same patterns, same interactions
+5. **Progressive disclosure** \u2014 Show only what's needed. Use tabs, dialogs, and drill-down navigation to manage complexity
 
-### Spacing System
+### Spacing
 
-Use Chakra UI's spacing scale consistently. Chakra uses a numeric spacing scale (1 = 4px, 2 = 8px, etc.).
+Use Chakra UI's numeric spacing scale consistently (1 = 4px):
 
-| 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) |
+| Scale | Use for |
+|-------|---------|
+| \`1\`\u2013\`2\` | Icon-to-text gaps, tight badge padding |
+| \`3\`\u2013\`4\` | Inner component padding, gap between related items |
+| \`5\`\u2013\`6\` | Card padding, section inner spacing |
+| \`8\` | Gap between sections within a page |
+| \`10\`\u2013\`12\` | Gap between major page sections |
 
-**Rules:**
-- Use \`spacing\` (via \`VStack\`, \`HStack\`, \`SimpleGrid\`) for spacing between siblings \u2014 not margin on individual items
-- Use \`VStack spacing={...}\` for vertical rhythm within a section
-- Page content padding: use \`Container\` which handles responsive horizontal padding
-- Card body padding: \`p={6}\` standard, \`p={4}\` for compact cards
-- Never mix spacing approaches in the same context \u2014 pick spacing OR margin, not both
+- Use \`VStack spacing={...}\` / \`HStack spacing={...}\` for sibling spacing \u2014 not margin on individual items
+- Page content: use \`Container\` for responsive horizontal padding
+- Card body: \`p={6}\` standard, \`p={4}\` for compact cards
 
 ### Typography
 
-Use \`Heading\` and \`Text\` components from \`@chakra-ui/react\`. Do NOT style raw HTML headings.
-
-**Hierarchy:**
 | Level | Component | Use for |
 |-------|-----------|---------|
-| Page title | \`<Heading as="h1" size="2xl">\` | One per page. The main heading. |
-| Section title | \`<Heading as="h2" size="xl">\` | Major sections within a page |
+| Page title | \`<Heading as="h1" size="2xl">\` | One per page |
+| Section title | \`<Heading as="h2" size="xl">\` | Major sections |
 | Sub-section | \`<Heading as="h3" size="lg">\` | Groups within a section |
 | Card title | \`<Heading as="h4" size="md">\` | Card headings |
 | Body | \`<Text>\` | Paragraphs, descriptions |
-| Caption/label | \`<Text fontSize="sm" color="gray.500">\` | Secondary info, metadata, timestamps |
-| Overline | \`<Text fontSize="xs" fontWeight="medium" textTransform="uppercase" letterSpacing="wide">\` | Category labels, section overlines |
+| Caption | \`<Text fontSize="sm" color="gray.500">\` | Metadata, timestamps |
 
-**Rules:**
-- One \`h1\` per page \u2014 it's the page title
-- Headings should never skip levels (h1 -> h3 without h2)
-- Body text: \`fontSize="sm"\` (14px) for dense UIs (tables, sidebars), \`fontSize="md"\` (16px) for reading content
-- Max reading width: \`maxW="prose"\` (~65ch) for long-form text. Never let paragraphs stretch full-width
-- Use \`color="gray.500"\` or theme-aware \`useColorModeValue('gray.600', 'gray.400')\` for secondary text
-- Font weight: \`fontWeight="medium"\` (500) for labels, \`fontWeight="semibold"\` (600) for headings, \`fontWeight="bold"\` (700) sparingly
+- One \`h1\` per page. Never skip heading levels
+- Max reading width: \`maxW="prose"\` for long-form text
+- Use \`useColorModeValue('gray.600', 'gray.400')\` for secondary text
 
 ### Color
 
-Use Chakra UI's theme-aware color tokens, never hardcoded colors.
+Use Chakra UI theme tokens \u2014 never hardcoded hex/rgb values:
 
-**Semantic palette (via colorScheme and theme tokens):**
-| Token | Usage |
-|-------|-------|
-| \`blue\` (colorScheme) | Primary actions (buttons, links, active states) |
-| \`gray\` (colorScheme) | Secondary actions, subtle backgrounds |
-| \`red\` (colorScheme) | Delete, error, danger states |
-| \`green\` (colorScheme) | Success states |
+| colorScheme | Usage |
+|-------------|-------|
+| \`blue\` | Primary actions, active states |
+| \`gray\` | Secondary actions, subtle backgrounds |
+| \`red\` | Delete, error, danger |
+| \`green\` | Success states |
 | \`yellow\` / \`orange\` | Warning states |
 
-**Rules:**
-- Use \`useColorModeValue()\` for any colors that need to adapt between light and dark mode
-- Status colors: use \`Badge\` with \`colorScheme\` (\`green\`, \`red\`, \`blue\`, \`gray\`) \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 maxW="container.xl">
-    <VStack spacing={8} align="stretch">
-      {/* Page header */}
-      <Flex align="center" justify="space-between">
-        <VStack spacing={1} align="start">
-          <Heading as="h1" size="2xl">Page Title</Heading>
-          <Text color="gray.500">Brief description of this page</Text>
-        </VStack>
-        <Button colorScheme="blue">Primary Action</Button>
-      </Flex>
-
-      {/* Page content sections */}
-      <VStack spacing={6} align="stretch">
-        {/* ... */}
-      </VStack>
-    </VStack>
-  </Container>
-</Box>
-\`\`\`
-
-**Card-based content:**
-\`\`\`tsx
-<SimpleGrid columns={{ base: 1, md: 2, lg: 3 }} spacing={6}>
-  {items.map((item) => (
-    <Card key={item.id}>
-      <CardHeader>
-        <Heading size="md">{item.title}</Heading>
-        <Text fontSize="sm" color="gray.500">{item.description}</Text>
-      </CardHeader>
-      <CardBody>
-        {/* Content */}
-      </CardBody>
-    </Card>
-  ))}
-</SimpleGrid>
-\`\`\`
-
-**Sidebar + main content:**
-\`\`\`tsx
-<Flex minH="100vh">
-  <Box as="aside" w="250px">{/* Nav items */}</Box>
-  <Box as="main" flex={1}>
-    <Container maxW="container.xl">{/* Page content */}</Container>
-  </Box>
-</Flex>
-\`\`\`
-
-**Section with centered content (landing pages):**
-\`\`\`tsx
-<Box as="section" py={{ base: 16, sm: 20 }}>
-  <Container maxW="container.xl">
-    <VStack spacing={4} align="center" textAlign="center">
-      <Heading as="h2" size="xl">Section Title</Heading>
-      <Text color="gray.500" maxW="2xl">
-        A concise description that explains the value proposition.
-      </Text>
-    </VStack>
-    <SimpleGrid columns={{ base: 1, md: 3 }} spacing={8} mt={12}>
-      {/* Feature cards or content */}
-    </SimpleGrid>
-  </Container>
-</Box>
-\`\`\`
-
-### Component Patterns
-
-**Empty states:**
-\`\`\`tsx
-// GOOD \u2014 uses a well-structured empty state with Chakra components
-<VStack spacing={4} align="center" py={12} textAlign="center">
-  <Icon as={Inbox} boxSize={12} color="gray.400" />
-  <Heading size="md">No messages yet</Heading>
-  <Text color="gray.500">Messages from your team will appear here.</Text>
-  <Button colorScheme="blue">Send a message</Button>
-</VStack>
-
-// BAD \u2014 hand-rolled empty state with raw HTML
-<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 Chakra Stat component
-<SimpleGrid columns={{ base: 1, sm: 2, lg: 4 }} spacing={4}>
-  <Stat>
-    <StatLabel>Total Users</StatLabel>
-    <StatNumber>2,847</StatNumber>
-    <StatHelpText><StatArrow type="increase" />12%</StatHelpText>
-  </Stat>
-  <Stat>
-    <StatLabel>Revenue</StatLabel>
-    <StatNumber>$48,290</StatNumber>
-    <StatHelpText><StatArrow type="increase" />8%</StatHelpText>
-  </Stat>
-</SimpleGrid>
-\`\`\`
-
-**Loading states:**
-\`\`\`tsx
-// GOOD \u2014 Skeleton matches the layout structure
-<VStack spacing={4} align="stretch">
-  <Skeleton h="32px" w="200px" />
-  <SkeletonText noOfLines={2} />
-  <SimpleGrid columns={3} spacing={4}>
-    {Array.from({ length: 3 }).map((_, i) => (
-      <Skeleton key={i} h="128px" />
-    ))}
-  </SimpleGrid>
-</VStack>
-
-// 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
+- Use \`useColorModeValue()\` for any color that must adapt between light and dark mode
+- Maximum 2\u20133 colors visible at once. Colorful UIs feel noisy
+- Status indicators: use \`Badge\` with \`colorScheme\` \u2014 don't hand-roll colored pills
 
-> **CRITICAL: Every screen, component, and custom style MUST look correct in both light and dark mode. No exceptions.**
+### Dark Mode
 
-Chakra UI supports color mode via \`useColorMode()\` and \`useColorModeValue()\`. All built-in components automatically adapt.
+> **Every screen and component MUST render correctly in both light and dark mode.**
 
-**Rules:**
-- Use \`useColorModeValue()\` for any custom colors that need to differ between modes
-- NEVER hardcode colors that only work in one mode. Use theme tokens or \`useColorModeValue()\`.
-- NEVER use \`bg="white"\` or \`bg="black"\`. Use \`bg={useColorModeValue('white', 'gray.800')}\` or Chakra semantic tokens.
-- All Chakra UI components automatically adapt to color mode \u2014 leverage this.
+- Use \`useColorModeValue()\` for any custom colors
+- NEVER hardcode \`bg="white"\` or \`bg="black"\`. Use \`bg={useColorModeValue('white', 'gray.800')}\`
+- All Chakra UI components automatically adapt \u2014 leverage this
 
 ### Interactions & Feedback
 
-- **Hover states**: Subtle background change \u2014 Chakra components handle this automatically
-- **Focus**: Chakra components include accessible focus rings by default
-- **Loading feedback**: Show \`Spinner\` on buttons via \`isLoading\` prop. 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
+- **Loading**: \`Skeleton\` for content areas, \`isLoading\` prop on buttons. Never leave the user without feedback
+- **Success/error**: \`useToast()\` for transient confirmations, \`Alert\` for persistent messages. Never \`window.alert()\`
+- **Destructive actions**: Always use \`AlertDialog\` for delete/remove. Never delete on single click
+- **Touch targets**: Minimum 44x44px for interactive elements on mobile
 
 ### Responsive Design
 
-- **Mobile-first**: Chakra's responsive props use mobile-first breakpoints
-- **Breakpoints**: \`sm\` (480px), \`md\` (768px), \`lg\` (992px), \`xl\` (1280px), \`2xl\` (1536px)
-- **Responsive props**: \`columns={{ base: 1, md: 2, lg: 3 }}\` \u2014 single column on mobile, expand on larger screens
-- **Hide/show**: Use Chakra's \`Show\` and \`Hide\` components or \`display={{ base: 'none', md: 'block' }}\`
-- **Touch targets**: Minimum 44x44px for interactive elements on mobile. Use \`Button size="lg"\` and adequate padding
-- **Stack direction**: Use \`Stack direction={{ base: 'column', md: 'row' }}\` for responsive stacking
-- **Container**: Always wrap page content in \`<Container>\` \u2014 it handles responsive horizontal padding
+- **Mobile-first**: Chakra responsive props use mobile-first breakpoints (\`base\`, \`sm\`, \`md\`, \`lg\`, \`xl\`)
+- **Responsive props**: \`columns={{ base: 1, md: 2, lg: 3 }}\`
+- **Stack direction**: \`Stack direction={{ base: 'column', md: 'row' }}\` for responsive stacking
+- Always wrap page content in \`<Container>\` for responsive horizontal padding
 
-### Anti-Patterns \u2014 NEVER Do These
-
-| Anti-pattern | What to do instead |
-|---|---|
-| Raw \`<div>\` with flex/grid classes | Use \`Flex\`, \`VStack\`, \`HStack\`, \`SimpleGrid\` |
-| Raw \`<h1>\`-\`<h6>\` tags | Use \`Heading\` with \`as\` and \`size\` props |
-| Raw \`<p>\` tags | Use \`Text\` |
-| Heavy box shadows | Use Chakra's built-in shadow prop: \`shadow="sm"\`, \`shadow="md"\` |
-| Gradient backgrounds on surfaces | Use solid backgrounds |
-| Custom scrollbar CSS hacks | Use Chakra's styling system |
-| Animated entrances (fade-in, slide-up) | Content should appear instantly. Only animate user-triggered changes |
-| Using \`<br />\` for spacing | Use \`VStack spacing={...}\` or Chakra spacing props |
-| Inline styles (\`style={{ ... }}\`) | Use Chakra style props (\`p\`, \`m\`, \`bg\`, \`color\`, etc.) |
-| Hardcoded color values | Use theme tokens and \`useColorModeValue()\` |
+For the full component reference, see the \`chakra-ui-react\` skill.
 `;
   }
 };
@@ -4152,6 +4240,178 @@ class OrderService:
   }
 };
 
+// src/skills/frontend-modularization.ts
+init_esm_shims();
+var frontendModularizationSkill = {
+  id: "frontend-modularization",
+  name: "Frontend Modularization",
+  description: "Component file structure, one-component-per-file rule, folder-based components, utility extraction, and barrel exports.",
+  render(_ctx) {
+    return `## Frontend Modularization
+
+> **RULE: One component per file. Extract non-component functions to utils. Promote complex components to folders with barrel exports.**
+
+### One Component Per File
+
+Every \`.tsx\` file exports exactly one React component. No sibling components, no inline helpers that render JSX.
+
+\`\`\`tsx
+// BAD \u2014 two components in one file
+export function UserCard({ user }: Props) { ... }
+export function UserCardSkeleton() { ... }
+
+// GOOD \u2014 separate files
+// user-card.tsx
+export function UserCard({ user }: Props) { ... }
+
+// user-card-skeleton.tsx
+export function UserCardSkeleton() { ... }
+\`\`\`
+
+Small, tightly-coupled sub-components (e.g. a skeleton for a card) still get their own file \u2014 co-locate them in the same directory.
+
+### Utility Functions Live in Utils
+
+> **RULE: Reuse before writing. Before creating any helper function, search the codebase for an existing one. If a function can be used outside the file it lives in, it belongs in utils.**
+
+Functions that are not components or hooks do not belong in component files. Extract them:
+
+- **Page/feature-scoped utilities** \u2192 \`utils/\` folder next to the component
+- **App-wide utilities** \u2192 \`src/shared/utils/\`
+
+If the same logic exists in two places, extract it into a shared utility immediately \u2014 never duplicate.
+
+\`\`\`tsx
+// BAD \u2014 helper function sitting in the component file
+function formatCurrency(amount: number) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
+}
+
+export function PriceTag({ amount }: { amount: number }) {
+  return <Text>{formatCurrency(amount)}</Text>
+}
+
+// GOOD \u2014 utility extracted
+// utils/format.ts
+export function formatCurrency(amount: number) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
+}
+
+// price-tag.tsx
+import { formatCurrency } from '../utils/format'
+
+export function PriceTag({ amount }: { amount: number }) {
+  return <Text>{formatCurrency(amount)}</Text>
+}
+\`\`\`
+
+**Exception:** Tiny, one-line helpers used only in that file (e.g. a local type guard) can stay inline. If it grows beyond a few lines or is used elsewhere, extract it.
+
+### Simple Components \u2014 Single File
+
+A component that is self-contained and has no children components stays as a single file:
+
+\`\`\`
+components/
+\u251C\u2500\u2500 user-avatar.tsx
+\u251C\u2500\u2500 status-badge.tsx
+\u2514\u2500\u2500 empty-state.tsx
+\`\`\`
+
+### Complex Components \u2014 Folder with Barrel Export
+
+When a component grows to have its own child components or hooks, promote it to a folder:
+
+\`\`\`
+components/
+\u2514\u2500\u2500 data-table/
+    \u251C\u2500\u2500 index.ts                    # Barrel \u2014 re-exports the main component
+    \u251C\u2500\u2500 data-table.tsx              # Main component (the orchestrator)
+    \u251C\u2500\u2500 components/
+    \u2502   \u251C\u2500\u2500 table-header.tsx        # Child component
+    \u2502   \u251C\u2500\u2500 table-row.tsx           # Child component
+    \u2502   \u251C\u2500\u2500 table-pagination.tsx    # Child component
+    \u2502   \u2514\u2500\u2500 table-empty-state.tsx   # Child component
+    \u251C\u2500\u2500 hooks/
+    \u2502   \u251C\u2500\u2500 use-table-sorting.ts    # Sorting logic
+    \u2502   \u2514\u2500\u2500 use-table-filters.ts    # Filter logic
+    \u2514\u2500\u2500 utils/
+        \u2514\u2500\u2500 column-helpers.ts       # Non-component, non-hook helpers
+\`\`\`
+
+**\`index.ts\`** \u2014 barrel export for the main component:
+\`\`\`ts
+export { DataTable } from './data-table'
+export type { DataTableProps } from './data-table'
+\`\`\`
+
+Consumers import from the folder, not the internal file:
+\`\`\`tsx
+// GOOD
+import { DataTable } from '@/shared/components/data-table'
+
+// BAD \u2014 reaching into internal structure
+import { DataTable } from '@/shared/components/data-table/data-table'
+\`\`\`
+
+### When to Promote a File to a Folder
+
+Promote a single-file component to a folder when any of these apply:
+
+1. It has **child components** \u2014 sections of JSX that are large enough to extract
+2. It has **custom hooks** \u2014 local logic that warrants its own file
+3. It has **utility functions** \u2014 helpers that should live in \`utils/\`
+4. It exceeds **~150 lines** \u2014 a sign it needs decomposition
+
+### Folder Structure Rules
+
+| What | Where |
+|---|---|
+| Child components only used by the parent | \`<component>/components/\` |
+| UI logic hooks for the component | \`<component>/hooks/\` |
+| Non-component, non-hook helpers | \`<component>/utils/\` |
+| Main component | \`<component>/<component>.tsx\` |
+| Public API | \`<component>/index.ts\` (barrel) |
+
+### Barrel Export Rules
+
+- The \`index.ts\` only re-exports the main component and its public types
+- Child components in \`components/\` are private \u2014 they are **not** re-exported
+- If a child component needs to be used elsewhere, move it up to the parent \`components/\` directory or to \`shared/components/\`
+
+\`\`\`ts
+// GOOD \u2014 index.ts re-exports only the public API
+export { DataTable } from './data-table'
+export type { DataTableProps, Column } from './data-table'
+
+// BAD \u2014 leaking internal child components
+export { DataTable } from './data-table'
+export { TableHeader } from './components/table-header'
+export { TableRow } from './components/table-row'
+\`\`\`
+
+### Where Components Live
+
+| Scope | Location |
+|---|---|
+| Used across the entire app | \`src/shared/components/\` |
+| Used only within a feature | \`src/features/<feature>/components/\` |
+| Used only within a page | \`src/pages/<page>/components/\` |
+| Used only within a parent component | \`<parent>/components/\` |
+
+### Summary
+
+1. **One component per file** \u2014 always
+2. **Non-component functions go in \`utils/\`** \u2014 never loose functions in component files
+3. **Reuse before writing** \u2014 search the codebase for existing utils before creating new ones; no duplicated logic
+4. **Simple component = single file** \u2014 no folder overhead for leaf components
+5. **Complex component = folder** with \`components/\`, \`hooks/\`, \`utils/\` subdirectories and an \`index.ts\` barrel
+6. **Barrel exports are the public API** \u2014 consumers import from the folder, never reach into internals
+7. **Scope determines location** \u2014 shared, feature, page, or parent component level
+`;
+  }
+};
+
 // src/skills/frontend-testing.ts
 init_esm_shims();
 var frontendTestingSkill = {
@@ -4224,12 +4484,47 @@ router/
 - Use \`.spec.ts\` for pure logic tests (hooks, utilities, no JSX)
 - Name matches the source file: \`customer-card.tsx\` \u2192 \`customer-card.spec.tsx\`
 
-### Always Use \`renderWithProviders\`
+### Test Rendering Setup
 
-> **RULE: Never import \`render\` from \`@testing-library/react\` directly. Always use \`renderWithProviders\` from \`@/__tests__/test-utils\`.**
+> **RULE: Never import \`render\` from \`@testing-library/react\` directly. Create a \`renderWithProviders\` helper in \`src/__tests__/test-utils.tsx\` that wraps components with all app providers.**
 
-\`renderWithProviders\` wraps components with all app providers (ChakraProvider, QueryClientProvider, MemoryRouter) so tests match the real app environment.
+Create \`src/__tests__/test-utils.tsx\` if it doesn't exist:
 
+\`\`\`tsx
+// src/__tests__/test-utils.tsx
+import { render, type RenderOptions } from '@testing-library/react'
+import { ChakraProvider } from '@chakra-ui/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { MemoryRouter } from 'react-router-dom'
+import userEvent from '@testing-library/user-event'
+
+interface ProviderOptions extends Omit<RenderOptions, 'wrapper'> {
+  routerEntries?: string[]
+  queryClient?: QueryClient
+}
+
+export function renderWithProviders(ui: React.ReactElement, options: ProviderOptions = {}) {
+  const { routerEntries = ['/'], queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }), ...renderOptions } = options
+  const user = userEvent.setup()
+
+  const result = render(ui, {
+    wrapper: ({ children }) => (
+      <ChakraProvider>
+        <QueryClientProvider client={queryClient}>
+          <MemoryRouter initialEntries={routerEntries}>{children}</MemoryRouter>
+        </QueryClientProvider>
+      </ChakraProvider>
+    ),
+    ...renderOptions,
+  })
+
+  return { ...result, user }
+}
+
+export { screen, waitFor, within } from '@testing-library/react'
+\`\`\`
+
+**Usage:**
 \`\`\`tsx
 import { screen } from '@/__tests__/test-utils'
 import { renderWithProviders } from '@/__tests__/test-utils'
@@ -4243,14 +4538,6 @@ describe('MyComponent', () => {
 })
 \`\`\`
 
-**Options:**
-\`\`\`tsx
-renderWithProviders(<MyComponent />, {
-  routerEntries: ['/customers/1'],  // Set initial route
-  queryClient: customQueryClient,   // Custom query client
-})
-\`\`\`
-
 **User interactions:**
 \`\`\`tsx
 const { user } = renderWithProviders(<MyComponent />)
@@ -4341,7 +4628,7 @@ vi.mock('react-router-dom', async () => {
 
 ### Test Structure
 \`\`\`tsx
-import { screen, waitFor } from '@/__tests__/test-utils'
+import { screen } from '@/__tests__/test-utils'
 import { renderWithProviders } from '@/__tests__/test-utils'
 
 // Mocks at the top, before imports of modules that use them
@@ -4507,9 +4794,10 @@ var aiGuidelinesSkill = {
     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
+1. Use \`blacksmith make:resource <Name>\` for new CRUD resources \u2014 it scaffolds the appropriate files based on project type
+2. **Fullstack projects:** After any backend API change (new endpoint, changed schema, new field), run \`blacksmith sync\` from the project root to regenerate the frontend API client and types
+3. Never manually edit files in \`src/api/generated/\` \u2014 they are overwritten on every sync
+4. Before writing any new function, search the codebase for an existing one that does the same thing
 
 ### Code Style
 - **Backend**: Follow PEP 8. Use Django and DRF conventions. Docstrings on models, serializers, and non-obvious view methods
@@ -4517,57 +4805,64 @@ var aiGuidelinesSkill = {
 - Use existing patterns in the codebase as reference before inventing new ones
 
 ### Frontend Architecture (Mandatory)
-- **Use \`@chakra-ui/react\` for ALL UI** \u2014 \`VStack\`, \`HStack\`, \`Flex\`, \`SimpleGrid\` for layout; \`Heading\`, \`Text\` for text; \`Card\`, \`Button\`, \`Badge\`, etc. for all elements. Never use raw HTML (\`<div>\`, \`<h1>\`, \`<p>\`, \`<button>\`) when a Chakra 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
+- **Use \`@chakra-ui/react\` for ALL UI** \u2014 \`VStack\`, \`HStack\`, \`Flex\`, \`SimpleGrid\` for layout; \`Heading\`, \`Text\` for text; \`Card\`, \`Button\`, \`Badge\`, etc. for all elements. Never use raw HTML (\`<div>\`, \`<h1>\`, \`<p>\`, \`<button>\`) when a Chakra UI component exists. Semantic landmarks (\`<main>\`, \`<section>\`, \`<nav>\`, etc.) are the only exception
+- **Pages are thin orchestrators** \u2014 compose child components from \`components/\`, extract logic into \`hooks/\`. Aim for clarity over strict line counts
+- **Use the \`Path\` enum** \u2014 all route paths come from \`src/router/paths.ts\`. Never hardcode path strings
+- **One component per file** \u2014 promote complex components to folders with barrel exports (see \`frontend-modularization\` skill)
 
 ### 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\`
+- Check \`blacksmith.config.json\` for configured ports and project type
 - Start everything: \`blacksmith dev\`
+- API docs (fullstack/backend): \`http://localhost:<backend-port>/api/docs/\` (Swagger) or \`/api/redoc/\`
+- Python venv: \`venv/\` in the backend directory \u2014 always use \`./venv/bin/python\` or \`./venv/bin/pip\`
 
 ### Checklist Before Finishing a Task
-1. Backend tests pass: \`cd backend && ./venv/bin/python manage.py test\`
-2. Frontend tests pass: \`cd frontend && npm test\`
-3. Frontend builds: \`cd frontend && npm run build\`
-4. API types are in sync: \`blacksmith sync\`
+1. Backend tests pass (if project has backend): \`./venv/bin/python manage.py test\` in the backend directory
+2. Frontend tests pass (if project has frontend): \`npm test\` in the frontend directory
+3. Frontend builds (if project has frontend): \`npm run build\` in the frontend directory
+4. API types are in sync (fullstack only): \`blacksmith sync\`
 5. No lint errors in modified files
 6. All UI uses \`@chakra-ui/react\` components \u2014 no raw \`<div>\` for layout, no raw \`<h1>\`-\`<h6>\` for text
 7. Pages are modular \u2014 page file is a thin orchestrator, sections are in \`components/\`, logic in \`hooks/\`
 8. Logic is in hooks \u2014 no \`useApiQuery\`, \`useApiMutation\`, \`useEffect\`, or multi-\`useState\` in component bodies
 9. No hardcoded route paths \u2014 all paths use the \`Path\` enum from \`@/router/paths\`
-10. New routes have a corresponding \`Path\` enum entry
-11. **Tests are co-located** \u2014 every new or modified page, component, or hook has a corresponding \`.spec.tsx\` / \`.spec.ts\` in a \`__tests__/\` folder next to the source file (see the \`frontend-testing\` skill)
+10. No duplicated logic \u2014 reusable functions are extracted to \`utils/\`
+11. Tests are co-located \u2014 every new or modified page, component, or hook has a corresponding \`.spec.tsx\` / \`.spec.ts\` in a \`__tests__/\` folder next to the source file
 `;
   }
 };
 
 // src/commands/ai-setup.ts
-async function setupAiDev({ projectDir, projectName, includeChakraUiSkill }) {
+async function setupAiDev({ projectDir, projectName, includeChakraUiSkill, projectType = "fullstack" }) {
   const aiSpinner = spinner("Setting up AI development environment...");
+  const needsBackend = projectType === "fullstack" || projectType === "backend";
+  const needsFrontend = projectType === "fullstack" || projectType === "frontend";
   try {
     const skills = [
       coreRulesSkill,
-      projectOverviewSkill,
-      djangoSkill,
-      djangoRestAdvancedSkill,
-      apiDocumentationSkill,
-      reactSkill,
-      reactQuerySkill,
-      pageStructureSkill
+      projectOverviewSkill
     ];
-    if (includeChakraUiSkill) {
-      skills.push(chakraUiReactSkill);
-      skills.push(chakraUiFormsSkill);
-      skills.push(chakraUiAuthSkill);
-      skills.push(blacksmithHooksSkill);
-      skills.push(uiDesignSkill);
+    if (needsBackend) {
+      skills.push(djangoSkill);
+      skills.push(djangoRestAdvancedSkill);
+      skills.push(apiDocumentationSkill);
+      skills.push(backendModularizationSkill);
+    }
+    if (needsFrontend) {
+      skills.push(reactSkill);
+      skills.push(reactQuerySkill);
+      skills.push(pageStructureSkill);
+      skills.push(frontendModularizationSkill);
+      if (includeChakraUiSkill) {
+        skills.push(chakraUiReactSkill);
+        skills.push(chakraUiFormsSkill);
+        skills.push(chakraUiAuthSkill);
+        skills.push(blacksmithHooksSkill);
+        skills.push(uiDesignSkill);
+      }
+      skills.push(frontendTestingSkill);
     }
     skills.push(blacksmithCliSkill);
-    skills.push(frontendTestingSkill);
     skills.push(programmingParadigmsSkill);
     skills.push(cleanCodeSkill);
     skills.push(aiGuidelinesSkill);
@@ -4632,6 +4927,7 @@ function parsePort(value, label) {
   return port;
 }
 var THEME_PRESETS = ["default", "blue", "green", "violet", "red", "neutral"];
+var PROJECT_TYPES = ["fullstack", "backend", "frontend"];
 async function init(name, options) {
   if (!name) {
     name = await promptText("Project name");
@@ -4640,203 +4936,226 @@ async function init(name, options) {
       process.exit(1);
     }
   }
-  if (!options.backendPort) {
+  let projectType;
+  if (options.type && PROJECT_TYPES.includes(options.type)) {
+    projectType = options.type;
+  } else if (options.type) {
+    log.error(`Invalid project type: "${options.type}". Must be one of: fullstack, backend, frontend`);
+    process.exit(1);
+  } else {
+    projectType = await promptSelect("Project type", PROJECT_TYPES, "fullstack");
+  }
+  const needsBackend = projectType === "fullstack" || projectType === "backend";
+  const needsFrontend = projectType === "fullstack" || projectType === "frontend";
+  if (needsBackend && !options.backendPort) {
     options.backendPort = await promptText("Backend port", "8000");
   }
-  if (!options.frontendPort) {
+  if (needsFrontend && !options.frontendPort) {
     options.frontendPort = await promptText("Frontend port", "5173");
   }
-  if (!options.themeColor) {
+  if (needsFrontend && !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 backendPort = needsBackend ? parsePort(options.backendPort || "8000", "backend") : void 0;
+  const frontendPort = needsFrontend ? parsePort(options.frontendPort || "5173", "frontend") : void 0;
+  const themePreset = needsFrontend && options.themeColor && THEME_PRESETS.includes(options.themeColor) ? options.themeColor : "default";
+  const configDisplay = { "Project": name, "Type": projectType };
+  if (needsBackend) configDisplay["Backend"] = `Django on :${backendPort}`;
+  if (needsFrontend) configDisplay["Frontend"] = `React on :${frontendPort}`;
+  if (needsFrontend) configDisplay["Theme"] = themePreset;
+  configDisplay["AI support"] = options.ai ? "Yes" : "No";
+  printConfig(configDisplay);
   const projectDir = path5.resolve(process.cwd(), name);
-  const backendDir = path5.join(projectDir, "backend");
-  const frontendDir = path5.join(projectDir, "frontend");
+  const backendDir = needsBackend ? projectType === "backend" ? projectDir : path5.join(projectDir, "backend") : null;
+  const frontendDir = needsFrontend ? projectType === "frontend" ? projectDir : path5.join(projectDir, "frontend") : null;
   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 (needsBackend) {
+    const hasPython = await commandExists("python3");
+    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);
+  if (needsFrontend) {
+    const hasNode = await commandExists("node");
+    const hasNpm = await commandExists("npm");
+    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 prereqs = [
+    needsBackend ? "Python 3" : null,
+    needsFrontend ? "Node.js, npm" : null
+  ].filter(Boolean).join(", ");
+  checkSpinner.succeed(`Prerequisites OK (${prereqs})`);
   const context = {
     projectName: name,
-    backendPort,
-    frontendPort,
+    backendPort: backendPort || 8e3,
+    frontendPort: frontendPort || 5173,
     themePreset
   };
   fs4.mkdirSync(projectDir, { recursive: true });
+  const configObj = {
+    name,
+    version: "0.1.0",
+    type: projectType
+  };
+  if (needsBackend) configObj.backend = { port: backendPort };
+  if (needsFrontend) configObj.frontend = { port: frontendPort };
   fs4.writeFileSync(
     path5.join(projectDir, "blacksmith.config.json"),
-    JSON.stringify(
-      {
-        name,
-        version: "0.1.0",
-        backend: { port: backendPort },
-        frontend: { port: frontendPort }
-      },
-      null,
-      2
-    )
+    JSON.stringify(configObj, null, 2)
   );
-  const backendSpinner = spinner("Generating Django backend...");
-  try {
-    renderDirectory(
-      path5.join(templatesDir, "backend"),
-      backendDir,
-      context
-    );
-    fs4.copyFileSync(
-      path5.join(backendDir, ".env.example"),
-      path5.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(
-      path5.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);
+  if (backendDir) {
+    const backendSpinner = spinner("Generating Django backend...");
+    try {
+      renderDirectory(
+        path5.join(templatesDir, "backend"),
+        backendDir,
+        context
+      );
+      fs4.copyFileSync(
+        path5.join(backendDir, ".env.example"),
+        path5.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 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));
+  if (frontendDir) {
+    const frontendSpinner = spinner("Generating React frontend...");
     try {
-      await exec(process.execPath, [path5.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)');
+      renderDirectory(
+        path5.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);
+    }
+  }
+  if (backendDir && frontendDir) {
+    const syncSpinner = spinner("Running initial OpenAPI sync...");
     try {
-      if (djangoProcess.pid) {
-        process.kill(-djangoProcess.pid);
+      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, [path5.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)');
     }
-  } catch {
-    syncSpinner.warn('OpenAPI sync skipped (run "blacksmith sync" after starting Django)');
-  }
-  const generatedDir = path5.join(frontendDir, "src", "api", "generated");
-  const stubFile = path5.join(generatedDir, "client.gen.ts");
-  if (!fs4.existsSync(stubFile)) {
-    if (!fs4.existsSync(generatedDir)) {
-      fs4.mkdirSync(generatedDir, { recursive: true });
+    const generatedDir = path5.join(frontendDir, "src", "api", "generated");
+    const stubFile = path5.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"
+      );
     }
-    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,
-      includeChakraUiSkill: options.chakraUiSkill !== false
+      includeChakraUiSkill: options.chakraUiSkill !== false,
+      projectType
     });
   }
-  printNextSteps(name, backendPort, frontendPort);
+  printNextSteps(name, projectType, backendPort, frontendPort);
 }
 
 // src/commands/dev.ts
@@ -4871,82 +5190,96 @@ async function dev() {
     process.exit(1);
   }
   const config = loadConfig(root);
-  const backendDir = getBackendDir(root);
-  const frontendDir = getFrontendDir(root);
+  const projectHasBackend = hasBackend(root);
+  const projectHasFrontend = hasFrontend(root);
   let backendPort;
   let frontendPort;
   try {
-    ;
-    [backendPort, frontendPort] = await Promise.all([
-      findAvailablePort(config.backend.port),
-      findAvailablePort(config.frontend.port)
-    ]);
+    if (projectHasBackend && config.backend) {
+      backendPort = await findAvailablePort(config.backend.port);
+      if (backendPort !== config.backend.port) {
+        log.step(`Backend port ${config.backend.port} in use, using ${backendPort}`);
+      }
+    }
+    if (projectHasFrontend && config.frontend) {
+      frontendPort = await findAvailablePort(config.frontend.port);
+      if (frontendPort !== config.frontend.port) {
+        log.step(`Frontend port ${config.frontend.port} in use, using ${frontendPort}`);
+      }
+    }
   } 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}`);
+  log.info("Starting development server" + (projectHasBackend && projectHasFrontend ? "s" : "") + "...");
+  log.blank();
+  if (projectHasBackend && backendPort) {
+    log.step(`Django      \u2192 http://localhost:${backendPort}`);
+    log.step(`Swagger     \u2192 http://localhost:${backendPort}/api/docs/`);
   }
-  if (frontendPort !== config.frontend.port) {
-    log.step(`Frontend port ${config.frontend.port} in use, using ${frontendPort}`);
+  if (projectHasFrontend && frontendPort) {
+    log.step(`Vite        \u2192 http://localhost:${frontendPort}`);
+  }
+  if (projectHasBackend && projectHasFrontend) {
+    log.step("OpenAPI sync \u2192 watching backend .py files");
   }
-  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} ${path6.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 processes = [];
+  if (projectHasBackend && backendPort) {
+    const backendDir = getBackendDir(root);
+    processes.push({
+      command: `./venv/bin/python manage.py runserver 0.0.0.0:${backendPort}`,
+      name: "django",
+      cwd: backendDir,
+      prefixColor: "green"
+    });
+  }
+  if (projectHasFrontend && frontendPort) {
+    const frontendDir = getFrontendDir(root);
+    processes.push({
+      command: "npm run dev",
+      name: "vite",
+      cwd: frontendDir,
+      prefixColor: "blue"
+    });
+  }
+  if (projectHasBackend && projectHasFrontend) {
+    const backendDir = getBackendDir(root);
+    const frontendDir = getFrontendDir(root);
+    const syncCmd = `${process.execPath} ${path6.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("");
+    processes.push({
+      command: `node -e '${watcherCode}'`,
+      name: "sync",
+      cwd: frontendDir,
+      prefixColor: "yellow"
+    });
+  }
+  const { result } = concurrently(processes, {
+    prefix: "name",
+    killOthers: ["failure"],
+    restartTries: 3
+  });
   const shutdown = () => {
     log.blank();
-    log.info("Development servers stopped.");
+    log.info("Development server" + (processes.length > 1 ? "s" : "") + " stopped.");
     process.exit(0);
   };
   process.on("SIGINT", shutdown);
@@ -4969,6 +5302,12 @@ async function sync() {
     log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
     process.exit(1);
   }
+  const projectType = getProjectType(root);
+  if (projectType !== "fullstack") {
+    log.error('The "sync" command is only available for fullstack projects.');
+    log.step("It generates frontend TypeScript types from the Django API schema.");
+    process.exit(1);
+  }
   const backendDir = getBackendDir(root);
   const frontendDir = getFrontendDir(root);
   const s = spinner("Syncing OpenAPI schema to frontend...");
@@ -5042,150 +5381,168 @@ async function makeResource(name) {
     process.exit(1);
   }
   const names = generateNames(name);
-  const backendDir = getBackendDir(root);
-  const frontendDir = getFrontendDir(root);
   const templatesDir = getTemplatesDir();
-  const backendAppDir = path8.join(backendDir, "apps", names.snakes);
-  if (fs6.existsSync(backendAppDir)) {
-    log.error(`Backend app "${names.snakes}" already exists.`);
-    process.exit(1);
-  }
-  const frontendPageDir = path8.join(frontendDir, "src", "pages", names.kebabs);
-  if (fs6.existsSync(frontendPageDir)) {
-    log.error(`Frontend page "${names.kebabs}" already exists.`);
-    process.exit(1);
-  }
+  const projectHasBackend = hasBackend(root);
+  const projectHasFrontend = hasFrontend(root);
   const context = { ...names, projectName: name };
-  const backendSpinner = spinner(`Creating backend app: apps/${names.snakes}/`);
-  try {
-    renderDirectory(
-      path8.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 = path8.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 = path8.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);
+  if (projectHasBackend) {
+    const backendDir = getBackendDir(root);
+    const backendAppDir = path8.join(backendDir, "apps", names.snakes);
+    if (fs6.existsSync(backendAppDir)) {
+      log.error(`Backend app "${names.snakes}" already exists.`);
+      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);
+  if (projectHasFrontend) {
+    const frontendDir = getFrontendDir(root);
+    const frontendPageDir = path8.join(frontendDir, "src", "pages", names.kebabs);
+    if (fs6.existsSync(frontendPageDir)) {
+      log.error(`Frontend page "${names.kebabs}" already exists.`);
+      process.exit(1);
+    }
   }
-  const syncSpinner = spinner("Syncing OpenAPI schema...");
-  try {
-    const schemaPath = path8.join(frontendDir, "_schema.yml");
-    await execPython(["manage.py", "spectacular", "--file", schemaPath], backendDir, true);
-    const configPath = path8.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");
+  if (projectHasBackend) {
+    const backendDir = getBackendDir(root);
+    const backendAppDir = path8.join(backendDir, "apps", names.snakes);
+    const backendSpinner = spinner(`Creating backend app: apps/${names.snakes}/`);
     try {
-      await exec(process.execPath, [path8.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);
+      renderDirectory(
+        path8.join(templatesDir, "resource", "backend"),
+        backendAppDir,
+        context
+      );
+      backendSpinner.succeed(`Created 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 = path8.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 = path8.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);
     }
-    syncSpinner.succeed("Frontend types and hooks regenerated");
-  } catch {
-    syncSpinner.warn('Could not sync OpenAPI. Run "blacksmith sync" manually.');
-  }
-  const apiHooksDir = path8.join(frontendDir, "src", "api", "hooks", names.kebabs);
-  const apiHooksSpinner = spinner(`Creating API hooks: api/hooks/${names.kebabs}/`);
-  try {
-    renderDirectory(
-      path8.join(templatesDir, "resource", "api-hooks"),
-      apiHooksDir,
-      context
-    );
-    apiHooksSpinner.succeed(`Created frontend/src/api/hooks/${names.kebabs}/`);
-  } catch (error) {
-    apiHooksSpinner.fail("Failed to create API hooks");
-    log.error(error.message);
-    process.exit(1);
-  }
-  const frontendSpinner = spinner(`Creating frontend page: pages/${names.kebabs}/`);
-  try {
-    renderDirectory(
-      path8.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 = path8.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");
+  if (projectHasBackend && projectHasFrontend) {
+    const backendDir = getBackendDir(root);
+    const frontendDir = getFrontendDir(root);
+    const syncSpinner = spinner("Syncing OpenAPI schema...");
+    try {
+      const schemaPath = path8.join(frontendDir, "_schema.yml");
+      await execPython(["manage.py", "spectacular", "--file", schemaPath], backendDir, true);
+      const configPath = path8.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, [path8.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 routeSpinner = spinner("Registering frontend routes...");
-  try {
-    const routesPath = path8.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");
+  if (projectHasFrontend) {
+    const frontendDir = getFrontendDir(root);
+    const apiHooksDir = path8.join(frontendDir, "src", "api", "hooks", names.kebabs);
+    const apiHooksSpinner = spinner(`Creating API hooks: api/hooks/${names.kebabs}/`);
+    try {
+      renderDirectory(
+        path8.join(templatesDir, "resource", "api-hooks"),
+        apiHooksDir,
+        context
+      );
+      apiHooksSpinner.succeed(`Created src/api/hooks/${names.kebabs}/`);
+    } catch (error) {
+      apiHooksSpinner.fail("Failed to create API hooks");
+      log.error(error.message);
+      process.exit(1);
+    }
+    const frontendPageDir = path8.join(frontendDir, "src", "pages", names.kebabs);
+    const frontendSpinner = spinner(`Creating frontend page: pages/${names.kebabs}/`);
+    try {
+      renderDirectory(
+        path8.join(templatesDir, "resource", "pages"),
+        frontendPageDir,
+        context
+      );
+      frontendSpinner.succeed(`Created 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 = path8.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 src/router/paths.ts");
+    }
+    const routeSpinner = spinner("Registering frontend routes...");
+    try {
+      const routesPath = path8.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 src/router/routes.tsx");
+    }
   }
   log.blank();
   log.success(`Resource "${names.Name}" created successfully!`);
@@ -5202,35 +5559,41 @@ async function build() {
     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 projectHasBackend = hasBackend(root);
+  const projectHasFrontend = hasFrontend(root);
+  if (projectHasFrontend) {
+    const frontendDir = getFrontendDir(root);
+    const frontendSpinner = spinner("Building frontend...");
+    try {
+      await exec("npm", ["run", "build"], { cwd: frontendDir, silent: true });
+      frontendSpinner.succeed("Frontend built \u2192 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);
+  if (projectHasBackend) {
+    const backendDir = getBackendDir(root);
+    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");
+  if (projectHasFrontend) log.step("Frontend assets: dist/");
+  if (projectHasBackend) log.step("Backend ready for deployment");
   log.blank();
 }
 
@@ -5246,20 +5609,34 @@ async function eject() {
     log.error("Not inside a Blacksmith project.");
     process.exit(1);
   }
+  const config = loadConfig(root);
+  const projectType = config.type || "fullstack";
   const configPath = path9.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.");
+  if (projectType === "fullstack") {
+    log.step("Your project is now a standard Django + React project.");
+  } else if (projectType === "backend") {
+    log.step("Your project is now a standard Django project.");
+  } else {
+    log.step("Your project is now a standard 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");
+  if (projectType === "fullstack") {
+    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");
+  } else if (projectType === "backend") {
+    log.step("Start:    ./venv/bin/python manage.py runserver");
+  } else {
+    log.step("Start:    npm run dev");
+  }
   log.blank();
 }
 
@@ -5271,7 +5648,9 @@ var allSkills = [
   djangoSkill,
   djangoRestAdvancedSkill,
   apiDocumentationSkill,
+  backendModularizationSkill,
   reactSkill,
+  frontendModularizationSkill,
   chakraUiReactSkill,
   chakraUiFormsSkill,
   chakraUiAuthSkill,
@@ -5293,7 +5672,8 @@ async function setupSkills(options) {
   await setupAiDev({
     projectDir: root,
     projectName: config.name,
-    includeChakraUiSkill: options.chakraUiSkill !== false
+    includeChakraUiSkill: options.chakraUiSkill !== false,
+    projectType: getProjectType(root)
   });
   log.blank();
   log.success("AI skills generated:");
@@ -5657,6 +6037,10 @@ async function backend(args) {
     log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
     process.exit(1);
   }
+  if (!hasBackend(root)) {
+    log.error('This is a frontend-only project. The "backend" command is not available.');
+    process.exit(1);
+  }
   if (args.length === 0) {
     log.error("Please provide a Django management command.");
     log.step("Usage: blacksmith backend <command> [args...]");
@@ -5681,6 +6065,10 @@ async function frontend(args) {
     log.error('Not inside a Blacksmith project. Run "blacksmith init <name>" first.');
     process.exit(1);
   }
+  if (!hasFrontend(root)) {
+    log.error('This is a backend-only project. The "frontend" command is not available.');
+    process.exit(1);
+  }
   if (args.length === 0) {
     log.error("Please provide an npm command.");
     log.step("Usage: blacksmith frontend <command> [args...]");
@@ -5700,7 +6088,7 @@ 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-chakra-ui-skill", "Disable Chakra 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("init").argument("[name]", "Project name").option("--type <type>", "Project type: fullstack, backend, or frontend (default: fullstack)").option("--ai", "Set up AI development skills and documentation (CLAUDE.md)").option("--no-chakra-ui-skill", "Disable Chakra 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);