symfonia-ai-tools 1.7.1 → 1.9.0

package/README.md

@@ -19,21 +19,33 @@ symfonia-ai-tools
 
 The configurator guides you through:
 1. Language selection (Polish / English)
-2. Project type, description, tech stack
-3. Instruction & skill packs (checkboxes)
-4. AI tools to configure (checkboxes)
-5. Skills to install (checkboxes — base + from selected packs)
-6. Paths, commands, CI pipeline, JIRA prefix
-7. MCP servers (checkboxes + tokens)
-8. CLI installation (checkboxes)
+2. **Install scope** — choose what to install
+3. Project type, description, tech stack *(full setup only)*
+4. Instruction & skill packs (checkboxes)
+5. AI tools to configure (checkboxes)
+6. Skills to install (checkboxes — base + from selected packs)
+7. Paths, commands, CI pipeline, JIRA prefix *(full setup only)*
+8. MCP servers (checkboxes + tokens)
+9. CLI installation (checkboxes) *(full setup only)*
 
 The entire configurator uses arrow-key navigation — no typing numbers.
 
-Finally, it automatically runs GSD:
+Finally (full setup only), it automatically runs GSD:
 - **New project** → `/gsd-new-project`
 - **Existing project** → `/gsd-map-codebase` → `/gsd-new-project`
 
-### Installation modes (existing project)
+### Install scopes
+
+| Scope | What it installs | Use case |
+|-------|-----------------|----------|
+| **Full setup** | Everything — files, skills, MCP, CLI, GSD bootstrap | First-time setup or full reinstall |
+| **Skills only** | Selected skills → `.ai/skills/` + mirrors | Add new skills to existing project |
+| **MCP only** | MCP server configuration | Add/update MCP servers |
+| **Skills + MCP** | Skills and MCP servers | Add skills and MCP in one go |
+
+Slim scopes (skills only, MCP only, skills + MCP) skip project metadata, commands, CI, JIRA, and CLI installation — they only ask for what's needed.
+
+### Installation modes (existing project, full setup)
 
 | Mode | Description |
 |------|-------------|
@@ -73,6 +85,7 @@ Instead of choosing a single stack, you pick any combination of instruction & sk
 | **Vitest** | 1 instruction | Yes |
 | **Storybook** | 1 instruction | No |
 | **Laravel + PHP** | 4 instructions, 7 skills | No |
+| **Python FastAPI** | 4 instructions, 7 skills | No |
 | **Playwright E2E** | 1 instruction, 3 skills | No |
 | **Docker** | 1 instruction | No |
 
@@ -155,6 +168,15 @@ When AI opens/edits a file matching `applyTo`, it automatically loads those inst
 | `api-resource.instructions.md` | `**/*Resource*.php, **/*Request*.php` | Resources with whenLoaded(), Form Requests, Policies |
 | `testing.instructions.md` | `**/*Test*.php, **/tests/**` | PHPUnit, data providers, factories, Laravel fakes |
 
+### Python FastAPI (4 instructions)
+
+| Instruction | applyTo | What it teaches AI |
+|-------------|---------|-------------------|
+| `api-schema.instructions.md` | `**/schemas.py, **/*schema*.py, **/*request*.py, **/*response*.py` | Pydantic v2 schemas, StrEnum status fields, `PaginatedResponse[T]`, frozen request models, `ErrorResponse` |
+| `module.instructions.md` | `**/modules/**/router.py, **/modules/**/dependencies.py, **/modules/**/domain/**, **/modules/**/infrastructure/**` | Module structure, FastAPI router pattern, SQLAlchemy 2.0 ORM models, `lifespan=` setup, DI wiring |
+| `service-repository.instructions.md` | `**/domain/services.py, **/infrastructure/repositories/**, **/domain/entities.py, **/domain/value_objects.py` | CQRS repos, domain entities, EventPublisher pattern, layer isolation rules |
+| `testing.instructions.md` | `**/tests/**, **/*test*.py, **/conftest.py` | pytest-asyncio conftest, `async_sessionmaker`, rollback pattern, `AsyncClient` |
+
 ### Playwright (1 instruction)
 
 | Instruction | applyTo | What it teaches AI |
@@ -267,6 +289,18 @@ All skills have the `smf-` prefix (Symfonia). The configurator lets you choose w
 | `smf-testing-unit` | Unit tests | Isolated tests without DB, PHPUnit mocks, data providers |
 | `smf-testing-manual` | Manual HTTP tests | JetBrains HTTP Client — `.http` files for interactive API testing |
 
+### Python FastAPI skills (7 skills)
+
+| Skill | Purpose | When to use |
+|-------|---------|-------------|
+| `smf-new-module` | New module from scratch | router → schemas → ORM model → CQRS repos → service → migration → tests |
+| `smf-new-endpoint` | New endpoint in existing module | request schema → route → service method → response schema → tests |
+| `smf-migration` | Alembic migration | autogenerate → review → upgrade → verify; async env.py setup |
+| `smf-background-task` | Celery background task | task def (sync) → `SyncSessionLocal` → dispatch from router → beat schedule → tests |
+| `smf-testing-integration` | Integration tests (HTTP) | `AsyncClient` → real DB via rollback conftest → router assertions |
+| `smf-testing-unit` | Unit tests (service) | mock repos → service logic → no DB needed |
+| `smf-testing-manual` | Manual HTTP tests | JetBrains HTTP Client `.http` files for interactive API testing |
+
 ### Playwright skills (3 skills)
 
 | Skill | Purpose | When to use |
@@ -524,6 +558,7 @@ templates/
     ├── vitest/                  # 1 instr.
     ├── storybook/               # 1 instr.
     ├── laravel/                 # 4 instr. · 7 skills
+    ├── python-fastapi/          # 4 instr. · 7 skills
     ├── playwright/              # 1 instr. · 3 skills
     └── docker/                  # 1 instr.
 ```

package/lib/i18n.mjs

@@ -32,6 +32,15 @@ const translations = {
     'q.quit_hint': 'Wpisz',
     'q.quit_hint2': 'aby przerwac w dowolnym momencie.',
 
+    // questions.mjs — install scope
+    'q.section.scope': 'Zakres instalacji',
+    'q.scope.select': 'Co chcesz zainstalowac?',
+    'q.scope.full': 'Pelny setup',
+    'q.scope.full_hint': '(pliki, skille, MCP, CLI)',
+    'q.scope.skills_only': 'Tylko skille',
+    'q.scope.mcp_only': 'Tylko serwery MCP',
+    'q.scope.skills_mcp': 'Skille + MCP',
+
     // questions.mjs — project
     'q.section.project': 'Projekt',
     'q.project_type': 'Typ projektu:',
@@ -143,12 +152,16 @@ const translations = {
     'i.mode.overwrite': 'nadpisz wszystko',
     'i.mode.skip': 'tylko nowe pliki',
     'i.mode.mcp': 'tylko MCP',
+    'i.mode.skills': 'tylko skille',
+    'i.mode.skills_mcp': 'skille + MCP',
     'i.dir': 'Katalog:',
     'i.mode_label': 'Tryb:',
     'i.step.base': 'Szablony bazowe',
     'i.step.pack': 'Pakiet',
     'i.step.guidelines': 'Skladanie',
     'i.step.mirror': 'Mirror',
+    'i.step.skills': 'Kopiowanie skilli',
+    'i.step.skills_mirror': 'Mirror skilli',
     'i.step.mcp': 'Konfiguracja MCP',
     'i.step.cli': 'Instalacja CLI',
 
@@ -170,6 +183,8 @@ const translations = {
 
     // installer.mjs — next steps
     'i.done.mcp': 'Konfiguracja MCP zakonczona!',
+    'i.done.skills': 'Instalacja skilli zakonczona!',
+    'i.done.skills_mcp': 'Instalacja skilli i MCP zakonczona!',
     'i.done.install': 'Instalacja zakonczona!',
     'i.done.check_mcp': 'Sprawdz MCP:',
     'i.done.install_gsd': 'Zainstaluj GSD',
@@ -213,6 +228,15 @@ const translations = {
     'q.quit_hint': 'Type',
     'q.quit_hint2': 'to abort at any time.',
 
+    // questions.mjs — install scope
+    'q.section.scope': 'Installation scope',
+    'q.scope.select': 'What do you want to install?',
+    'q.scope.full': 'Full setup',
+    'q.scope.full_hint': '(files, skills, MCP, CLI)',
+    'q.scope.skills_only': 'Skills only',
+    'q.scope.mcp_only': 'MCP servers only',
+    'q.scope.skills_mcp': 'Skills + MCP',
+
     // questions.mjs — project
     'q.section.project': 'Project',
     'q.project_type': 'Project type:',
@@ -324,12 +348,16 @@ const translations = {
     'i.mode.overwrite': 'overwrite all',
     'i.mode.skip': 'new files only',
     'i.mode.mcp': 'MCP only',
+    'i.mode.skills': 'skills only',
+    'i.mode.skills_mcp': 'skills + MCP',
     'i.dir': 'Directory:',
     'i.mode_label': 'Mode:',
     'i.step.base': 'Base templates',
     'i.step.pack': 'Pack',
     'i.step.guidelines': 'Assembling',
     'i.step.mirror': 'Mirror',
+    'i.step.skills': 'Copying skills',
+    'i.step.skills_mirror': 'Mirroring skills',
     'i.step.mcp': 'MCP configuration',
     'i.step.cli': 'CLI installation',
 
@@ -351,6 +379,8 @@ const translations = {
 
     // installer.mjs — next steps
     'i.done.mcp': 'MCP configuration complete!',
+    'i.done.skills': 'Skills installation complete!',
+    'i.done.skills_mcp': 'Skills & MCP installation complete!',
     'i.done.install': 'Installation complete!',
     'i.done.check_mcp': 'Check MCP:',
     'i.done.install_gsd': 'Install GSD',

package/lib/installer.mjs

@@ -116,6 +116,12 @@ export async function install(packageRoot, answers) {
   const templatesDir = join(packageRoot, 'templates');
   const mode = answers.installMode || 'fresh';
 
+  // Handle slim install scopes (skills-only, mcp-only, skills+mcp)
+  const installScope = answers.installScope || 'full';
+  if (installScope !== 'full') {
+    return await installSlim(targetDir, templatesDir, answers, installScope);
+  }
+
   const modeLabel = mode === 'fresh' ? boldGreen(t('i.mode.fresh'))
     : mode === 'overwrite' ? boldYellow(t('i.mode.overwrite'))
     : mode === 'skip-existing' ? boldCyan(t('i.mode.skip'))
@@ -183,6 +189,100 @@ export async function install(packageRoot, answers) {
   }
 }
 
+// ─── Slim install (skills-only, mcp-only, skills+mcp) ───
+
+async function installSlim(targetDir, templatesDir, answers, scope) {
+  const needsSkills = scope !== 'mcp-only';
+  const needsMcp = scope !== 'skills-only';
+  const needsMirror = needsSkills && (answers.toolCopilot || answers.toolClaude);
+
+  const totalSteps = (needsSkills ? 1 : 0) + (needsMirror ? 1 : 0) + (needsMcp ? 1 : 0);
+  let currentStep = 0;
+
+  const modeLabel = scope === 'skills-only' ? boldCyan(t('i.mode.skills'))
+    : scope === 'mcp-only' ? boldCyan(t('i.mode.mcp'))
+    : boldCyan(t('i.mode.skills_mcp'));
+
+  section(t('i.section.install'));
+  console.log(info(`${t('i.dir')} ${bold(targetDir)}`));
+  console.log(info(`${t('i.mode_label')} ${modeLabel}`));
+  console.log('');
+
+  if (needsSkills) {
+    step(++currentStep, totalSteps, t('i.step.skills'));
+    await installSkills(templatesDir, targetDir, answers);
+
+    if (needsMirror) {
+      step(++currentStep, totalSteps, t('i.step.skills_mirror'));
+      const aiSkillsDir = join(targetDir, '.ai', 'skills');
+      if (answers.toolCopilot) {
+        await mirrorDir(aiSkillsDir, join(targetDir, '.github', 'skills'), targetDir, 'overwrite');
+      }
+      if (answers.toolClaude) {
+        await mirrorDir(aiSkillsDir, join(targetDir, '.claude', 'skills'), targetDir, 'overwrite');
+      }
+    }
+  }
+
+  if (needsMcp) {
+    step(++currentStep, totalSteps, t('i.step.mcp'));
+    await generateMcpConfig(targetDir, answers);
+  }
+
+  console.log('');
+  const doneKey = scope === 'skills-only' ? 'i.done.skills'
+    : scope === 'mcp-only' ? 'i.done.mcp'
+    : 'i.done.skills_mcp';
+  box([boldGreen(`  ${t(doneKey)}`)], boldGreen);
+  console.log('');
+
+  if (needsMcp && answers.toolClaude) {
+    console.log(info(`${t('i.done.check_mcp')} ${cyan('claude mcp list')}`));
+  }
+}
+
+async function installSkills(templatesDir, targetDir, answers) {
+  const selectedSkills = answers.selectedSkills || [];
+  if (selectedSkills.length === 0) {
+    console.log(`  ${dim(t('q.skills.none'))}`);
+    return;
+  }
+
+  const aiSkillsDir = join(targetDir, '.ai', 'skills');
+  await mkdir(aiSkillsDir, { recursive: true });
+
+  // Base skills
+  const baseSkillsDir = join(templatesDir, 'base', '_ai', 'skills');
+  try {
+    const entries = await readdir(baseSkillsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory() && selectedSkills.includes(e.name)) {
+        const dest = join(aiSkillsDir, e.name);
+        await mkdir(dest, { recursive: true });
+        await copyTemplateDir(join(baseSkillsDir, e.name), dest, answers, 'overwrite');
+      }
+    }
+  } catch { /* no base skills */ }
+
+  // Pack skills
+  const allPacks = await loadPacks(join(templatesDir, 'packs'));
+  for (const packId of (answers.packs || [])) {
+    const pack = allPacks[packId];
+    if (!pack) continue;
+    const packSkillsDir = join(pack._dir, '_ai', 'skills');
+    try {
+      const entries = await readdir(packSkillsDir, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.isDirectory() && selectedSkills.includes(e.name)) {
+          const dest = join(aiSkillsDir, e.name);
+          await mkdir(dest, { recursive: true });
+          await copyTemplateDir(join(packSkillsDir, e.name), dest, answers, 'overwrite');
+        }
+      }
+    } catch { /* no pack skills */ }
+  }
+}
+
 // ─── Guidelines assembly ───
 
 async function assembleGuidelines(templatesDir, targetDir, answers, selectedPacks, allPacks, mode) {

package/lib/questions.mjs

@@ -80,6 +80,25 @@ export async function askQuestions(packsDir) {
     console.log('');
     console.log(`  ${dim(t('q.quit_hint'))} ${yellow('"q"')} ${dim(t('q.quit_hint2'))}`);
 
+    // --- Install scope ---
+    section(t('q.section.scope'));
+    answers.installScope = await askChoice(t('q.scope.select'), [
+      'full',
+      'skills-only',
+      'mcp-only',
+      'skills+mcp',
+    ], [
+      `${boldGreen(t('q.scope.full'))} ${dim(t('q.scope.full_hint'))}`,
+      `${boldCyan(t('q.scope.skills_only'))}`,
+      `${boldCyan(t('q.scope.mcp_only'))}`,
+      `${boldCyan(t('q.scope.skills_mcp'))}`,
+    ]);
+
+    // Slim flows — early return
+    if (answers.installScope !== 'full') {
+      return await askSlimFlow(answers, packsDir);
+    }
+
     // --- Project type ---
     section(t('q.section.project'));
 
@@ -156,9 +175,10 @@ export async function askQuestions(packsDir) {
 
     const hasVue = answers.packs.includes('vue3');
     const hasLaravel = answers.packs.includes('laravel');
-    answers.testCommand = await ask(t('q.cmd.test'), hasVue ? 'npm run test' : hasLaravel ? 'php artisan test' : 'npm test');
-    answers.buildCommand = await ask(t('q.cmd.build'), hasVue ? 'npm run build' : hasLaravel ? 'composer build' : 'npm run build');
-    answers.lintCommand = await ask(t('q.cmd.lint'), hasVue ? 'npm run lint' : hasLaravel ? 'php artisan pint' : 'npm run lint');
+    const hasPythonFastapi = answers.packs.includes('python-fastapi');
+    answers.testCommand = await ask(t('q.cmd.test'), hasVue ? 'npm run test' : hasLaravel ? 'php artisan test' : hasPythonFastapi ? 'pytest' : 'npm test');
+    answers.buildCommand = await ask(t('q.cmd.build'), hasVue ? 'npm run build' : hasLaravel ? 'composer build' : hasPythonFastapi ? 'docker build .' : 'npm run build');
+    answers.lintCommand = await ask(t('q.cmd.lint'), hasVue ? 'npm run lint' : hasLaravel ? 'php artisan pint' : hasPythonFastapi ? 'ruff check . && mypy .' : 'npm run lint');
 
     // --- CI ---
     section(t('q.section.ci'));
@@ -493,3 +513,88 @@ function printSummary(answers, allPacks) {
     tableRow(t('q.summary.gsd'), cyan(gsdSteps.join(dim(' → '))));
   }
 }
+
+// ─── Slim flow (skills-only, mcp-only, skills+mcp) ───
+
+async function askSlimFlow(answers, packsDir) {
+  const scope = answers.installScope;
+  const needsSkills = scope !== 'mcp-only';
+  const needsMcp = scope !== 'skills-only';
+
+  // --- Target directory ---
+  answers.targetDir = await ask(t('q.target_dir'), '.');
+  answers.installMode = 'overwrite';
+
+  // --- Tool selection ---
+  await askToolSelection(answers);
+
+  // --- Skills flow ---
+  let allPacks = {};
+  if (needsSkills) {
+    allPacks = await loadPacks(packsDir);
+    await askPackSelection(answers, allPacks);
+    const baseSkillsDir = join(packsDir, '..', 'base', '_ai', 'skills');
+    await askSkillSelection(answers, allPacks, baseSkillsDir);
+    await askPackPlaceholders(answers, allPacks);
+    checkCliDeps(answers.selectedSkills || []);
+  } else {
+    answers.packs = [];
+    answers.selectedSkills = [];
+  }
+
+  // --- MCP flow ---
+  if (needsMcp) {
+    const requiredMcps = collectRequiredMcps(answers.selectedSkills || []);
+    await askMcpServers(answers, requiredMcps);
+  } else {
+    answers.mcpJira = false;
+    answers.mcpBitbucket = false;
+    answers.mcpFigma = false;
+    answers.mcpGrafana = false;
+    answers.mcpContext7 = false;
+  }
+
+  // --- Defaults for unused fields ---
+  answers.installClaudeCli = false;
+  answers.installGsd = false;
+
+  // --- Summary ---
+  printSlimSummary(answers, allPacks);
+
+  const proceed = await askYN(`\n  ${t('q.summary.continue')}`, true);
+  if (!proceed) throw new Error('USER_ABORT');
+
+  return answers;
+}
+
+function printSlimSummary(answers, allPacks) {
+  section(t('q.section.summary'));
+
+  tableRow(t('q.summary.dir'), answers.targetDir);
+
+  const tools = [];
+  if (answers.toolClaude) tools.push('Claude');
+  if (answers.toolCopilot) tools.push('Copilot');
+  if (answers.toolCursor) tools.push('Cursor');
+  if (answers.toolGemini) tools.push('Gemini');
+  if (answers.toolJunie) tools.push('Junie');
+  tableRow(t('q.summary.tools'), tools.length > 0 ? cyan(tools.join(dim(' · '))) : dim(t('q.summary.none')));
+
+  if (answers.installScope !== 'mcp-only') {
+    const packNames = (answers.packs || []).map(id => allPacks[id]?.name || id);
+    tableRow(t('q.summary.packs'), packNames.length > 0 ? cyan(packNames.join(dim(' · '))) : dim(t('q.summary.none')));
+
+    const skills = answers.selectedSkills || [];
+    tableRow(t('q.summary.skills'), skills.length > 0 ? cyan(skills.join(dim(' · '))) : dim(t('q.summary.none')));
+  }
+
+  if (answers.installScope !== 'skills-only') {
+    const mcps = [];
+    if (answers.mcpJira) mcps.push('Jira');
+    if (answers.mcpBitbucket) mcps.push('Bitbucket');
+    if (answers.mcpFigma) mcps.push('Figma');
+    if (answers.mcpGrafana) mcps.push('Grafana');
+    if (answers.mcpContext7) mcps.push('Context7');
+    tableRow(t('q.summary.mcp'), mcps.length > 0 ? cyan(mcps.join(dim(' · '))) : dim(t('q.summary.none')));
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symfonia-ai-tools",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "AI tooling setup for your project - Claude Code, GitHub Copilot, Cursor, Gemini, Junie, GSD",
   "type": "module",
   "bin": {

package/templates/packs/python-fastapi/_ai/instructions/api-schema.instructions.md

@@ -0,0 +1,177 @@
+---
+applyTo: "**/schemas.py,**/*schema*.py,**/*request*.py,**/*response*.py"
+---
+
+# API Schemas, Request & Response Models — Instructions
+
+## Pydantic v2 Schemas
+
+Never return ORM models directly from endpoints. All input/output passes through Pydantic schemas.
+
+```python
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FeatureResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    name: str
+    description: str | None
+    status: FeatureStatus          # use the StrEnum — not bare `str`
+    created_at: datetime
+
+    # Nested relations — use None default (loaded on demand)
+    author: UserResponse | None = None
+    category: CategoryResponse | None = None
+```
+
+### Request Schemas (Input Validation)
+
+Request schemas are **read-only once validated** — add `frozen=True` to catch accidental mutation:
+
+```python
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from uuid import UUID
+
+
+class StoreFeatureRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(min_length=2, max_length=255)
+    description: str | None = Field(default=None, max_length=5000)
+    category_id: UUID | None = None
+    status: FeatureStatus
+    tags: list[str] = Field(default_factory=list)
+
+    @field_validator("tags")
+    @classmethod
+    def validate_tags(cls, v: list[str]) -> list[str]:
+        if any(len(tag) > 50 for tag in v):
+            raise ValueError("Each tag must be at most 50 characters")
+        return v
+
+
+class UpdateFeatureRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str | None = Field(default=None, min_length=2, max_length=255)
+    description: str | None = None
+    status: FeatureStatus | None = None
+```
+
+### List / Index Request with Filtering and Sorting
+
+```python
+from __future__ import annotations
+
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+class IndexFeatureRequest(BaseModel):
+    page: int = Field(default=1, ge=1)
+    limit: int = Field(default=20, ge=1, le=100)
+    status: FeatureStatus | None = None
+    sort_by: Literal["created_at", "name", "status"] = "created_at"
+    sort_dir: Literal["asc", "desc"] = "desc"
+```
+
+### Paginated Collection Response
+
+`PaginatedResponse` and `PaginationMeta` are **shared types** — define them once in `app/core/schemas.py`, never per-module:
+
+```python
+# app/core/schemas.py
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class PaginationMeta(BaseModel):
+    total: int
+    per_page: int
+    current_page: int
+    last_page: int
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    data: list[T]
+    meta: PaginationMeta
+```
+
+Import from `app.core.schemas` in every module that needs it.
+
+## Error Responses
+
+Standardize the error body shape. Define `ErrorResponse` in `app/core/schemas.py`:
+
+```python
+# app/core/schemas.py
+class ErrorResponse(BaseModel):
+    code: str           # machine-readable code: "FEATURE_NOT_FOUND"
+    message: str        # human-readable description
+    field: str | None = None  # which field caused the error (optional)
+```
+
+Raise via `HTTPException` — the exception handler converts it:
+
+```python
+from fastapi import HTTPException, status
+
+# In service (expected domain errors):
+raise HTTPException(
+    status_code=status.HTTP_404_NOT_FOUND,
+    detail={"code": "FEATURE_NOT_FOUND", "message": "Feature not found"},
+)
+```
+
+Register a handler in `app/main.py` to enforce consistent shape:
+
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    if isinstance(exc.detail, dict):
+        body = exc.detail
+    else:
+        body = {"code": "HTTP_ERROR", "message": str(exc.detail)}
+    return JSONResponse(status_code=exc.status_code, content=body)
+```
+
+## Enums
+
+```python
+from enum import StrEnum
+
+
+class FeatureStatus(StrEnum):
+    DRAFT = "draft"
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+```
+
+Use `StrEnum` (Python 3.11+) — auto-serializes to string in JSON.
+
+## Rules
+
+- `from_attributes=True` on every response schema that reads from ORM
+- Never expose internal IDs as integers — use UUID
+- Use `Field(...)` for constraints, not just annotations
+- `StrEnum` for all enums — clean JSON serialization, use in both request and response schemas
+- Nested relations are always `| None = None` — populate only when loaded
+- `frozen=True` on all request/input schemas — prevents accidental mutation after validation
+- `PaginatedResponse[T]` and `PaginationMeta` live in `app/core/schemas.py` — import, never redefine
+- `ErrorResponse` body has `code` (machine) and `message` (human) — register a global exception handler