@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/mcp_ping_server.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Minimal self-contained MCP stdio server (raw JSON-RPC 2.0, zero dependencies).
+
+Ships in the caddis agy plugin to prove the MCP wiring end-to-end without pulling in the `mcp`
+package or any retired server (junai-mcp is gone). Exposes ONE tool, `caddis_ping`, which returns
+the marker `CADDIS-MCP-OK`. Transport: newline-delimited JSON-RPC on stdin/stdout (MCP stdio).
+"""
+import json
+import sys
+
+
+def _send(msg: dict) -> None:
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> None:
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        mid = req.get("id")
+        method = req.get("method")
+        if method == "initialize":
+            _send({"jsonrpc": "2.0", "id": mid, "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "caddis", "version": "0.1.0"},
+            }})
+        elif method == "tools/list":
+            _send({"jsonrpc": "2.0", "id": mid, "result": {"tools": [{
+                "name": "caddis_ping",
+                "description": "Health-check tool — returns a caddis marker so MCP wiring can be verified.",
+                "inputSchema": {"type": "object", "properties": {}},
+            }]}})
+        elif method == "tools/call":
+            name = (req.get("params") or {}).get("name")
+            if name == "caddis_ping":
+                _send({"jsonrpc": "2.0", "id": mid, "result": {
+                    "content": [{"type": "text", "text": "CADDIS-MCP-OK"}]
+                }})
+            else:
+                _send({"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"unknown tool: {name}"}})
+        elif method and method.startswith("notifications/"):
+            pass  # notifications get no response
+        elif mid is not None:
+            _send({"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"method not found: {method}"}})
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "caddis",
+  "version": "1.3.39",
+  "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
+}

package/bundles/antigravity-plugin/session_end_agy.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""caddis `session_end` hook for agy (Antigravity) — Stop event.
+
+Ports claude-harness/hooks/session_end.py to agy's contract. On Stop, appends ONE session-end record to
+the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`, or `.claudster/` if the repo still lives
+there). Self-contained (the agy bundle does not ship claudster_config.py), stdlib-only, and fully defensive:
+a Stop hook must never fail the turn, and must not print a non-JSON line to stdout (agy parses Stop-hook
+stdout as a `{"decision":…}` object — a stray string trips its "unsupported hook decision" path). So this
+does a pure side effect and prints NOTHING.
+
+agy Stop stdin (camelCase protojson):
+  {"executionNum":N, "terminationReason":"model_stop|max_steps_exceeded|error", "error":"",
+   "fullyIdle":true, "conversationId":"…", "workspacePaths":["…"], "transcriptPath":"…", "modelName":"…"}
+"""
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+
+def _artifact_root(root: str) -> str:
+    """Write where the repo lives: prefer .caddis, keep .claudster if that's what the repo has."""
+    for name in (".caddis", ".claudster"):
+        path = os.path.join(str(root), name)
+        if os.path.isdir(path):
+            return path
+    return os.path.join(str(root), ".caddis")
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        data = {}
+    try:
+        workspaces = data.get("workspacePaths") or []
+        workspace = workspaces[0] if workspaces else os.getcwd()
+        art = _artifact_root(workspace)
+        os.makedirs(art, exist_ok=True)
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "event": "session_end",
+            "agent": "agy",
+            "conversationId": data.get("conversationId"),
+            "executionNum": data.get("executionNum"),
+            "terminationReason": data.get("terminationReason"),
+            "model": data.get("modelName"),
+        }
+        with open(os.path.join(art, "usage-log.jsonl"), "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record) + "\n")
+    except Exception:
+        pass  # never fail the turn
+    # No stdout: agy interprets a Stop hook's stdout as a decision object.
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin/skills/_registry.md

@@ -0,0 +1,115 @@
+# Skills Registry
+
+> Bundle skill inventory generated from `SKILL.md` frontmatter for the shipped subset.
+> Load a skill by reading its `SKILL.md`.
+
+---
+
+## Skills by Category
+
+### Coding
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Api Design | `api-design/` | REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation. |
+| Backend Development | `backend-development/` | Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture. |
+| Code Review | `code-review/` | Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits. |
+| Codebase Audit | `codebase-audit/` | Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents. |
+| Cross Review | `cross-review/` | Cross-vendor code review of the current diff — a second-vendor model (DeepSeek/GLM/any OpenAI-compatible endpoint) reviews your changes to catch bugs a same-vendor reviewer misses |
+| Error Handling | `error-handling/` | Error handling patterns for Python and TypeScript applications. Use when designing error hierarchies, implementing retry logic, building error boundaries, or establishing logging strategies. Covers custom exceptions, result types, circuit breakers, and user-facing error messages. |
+| Fastapi Dev | `fastapi-dev/` | Build FastAPI backends with standard patterns, error handling, and testing |
+| Javascript Typescript | `javascript-typescript/` | JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects. |
+| Python Development | `python/` | Modern Python development with Python 3.12+, Django, FastAPI, async patterns, and production best practices. Use for Python projects, APIs, data processing, or automation scripts. |
+| Refactoring | `refactoring/` | Safely refactor code while maintaining behavior. Use when improving code structure, reducing duplication, extracting functions, or modernizing legacy code. |
+| Security Review | `security-review/` | Security review workflow — OWASP, code scanning, cloud infrastructure |
+| Sql | `sql/` | Write high-quality, optimized SQL with best practices for performance, NULL handling, security, and readability. Database-agnostic patterns with dialect-specific notes. |
+
+### Data
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Database Design | `database-design/` | Database schema design, optimization, and migration patterns for PostgreSQL, MySQL, and NoSQL databases. Use for designing schemas, writing migrations, or optimizing queries. |
+| Db Diagram | `db-diagram/` | Turn a SQL artifact — a stored procedure, view, query, .sql file, or table name — into a diagram that explains it to a human. Use when the user says "diagram this query/proc/view/schema", "explain this SQL visually", "draw the ER diagram", "show me the data flow of this stored proc", "/mermaid-db", or "/excalidraw-db". Produces Mermaid (default, git-diffable) or Excalidraw (for design reviews). Read-only — never touches the database. |
+
+### Devops
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
+| Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
+| Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
+| Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
+| Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
+
+### Docs
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
+| Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
+| Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
+
+### Frontend
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Css Architecture | `css-architecture/` | CSS architecture, design token strategy, Tailwind conventions, CSS Modules, container queries, dark mode, responsive patterns, and animation architecture. Use for design token naming, CSS custom properties, Tailwind config, container queries, dark mode implementation, fluid typography, or CSS animation decisions. Complements frontend-design (what to achieve) with how to implement it. |
+| Frontend Design | `frontend-design/` | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics while strictly adhering to the user's technical standards. |
+| Mockup | `mockup/` | Create framework-aware UI mockups with feasibility checks. Prevents wasted effort by validating that proposed designs work within the target framework's constraints. |
+| React Best Practices | `react-best-practices/` | Modern React development guidelines covering hooks, component patterns, state management, performance optimization, and TypeScript integration. |
+| React Dev | `react-dev/` | This skill should be used when building React components with TypeScript, typing hooks, handling events, or when React TypeScript, React 19, Server Components are mentioned. Covers type-safe patterns for React 18-19 including generic components, proper event typing, and routing integration (TanStack Router, React Router). |
+| Ui Review | `ui-review/` | Review UI implementations against design requirements, accessibility standards (WCAG 2.2 AA), and brand guidelines. Use when reviewing designs or validating UI before release. |
+| Warm Editorial Ui | `warm-editorial-ui/` | Apply the "Warm Editorial Refinement" design system — a sophisticated, executive-grade aesthetic with warm cream surfaces (light mode) and warm charcoal surfaces (dark mode), Bahnschrift + Plus Jakarta Sans typography, generous rounded corners, multi-layer shadows, and a warm neutral palette. Supports both light and dark themes via CSS custom properties and the `.dark` class. Use this skill whenever the user wants to build an app, dashboard, component, or web UI using the abc-project visual style. Trigger on phrases like "use our design system", "apply our template", "make it look like abc-project", "use the warm editorial style", "use our brand template", "add dark mode", or any request to build a new tool/app/dashboard for XYZ Brand or similar contexts. This is the canonical design template for all new frontend builds. |
+
+### General
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Add Rules | `add-rules/` | Create canonical rules for ANY folder — write <folder>/AGENTS.md (from the folder template) + a <folder>/CLAUDE.md @import shim. For folders the stack-map generator doesn't cover. |
+| Digress | `digress/` | Park the current workstream on the stack and switch to a new task — without losing the original |
+| Excalidraw Db | `excalidraw-db/` | Turn a SQL artifact into an Excalidraw diagram for a design review / ARB pack / slide — higher-level, drag-the-boxes format |
+| Feature Plan | `feature-plan/` | Create a phased, TDD-structured implementation plan that acts as the durable spine for multi-session work |
+| Handoff | `handoff/` | End-of-session handoff — capture exact state so the next session resumes with zero re-discovery |
+| Implement | `implement/` | Headless plan executor — implement an approved plan phase-by-phase on the current feature branch, TDD-first, committing per phase |
+| Kb | `kb/` | Rebuild the KB index (.caddis/kb/DOC-MAP.md) — create it if missing, index un-indexed notes, report dangling links |
+| Mermaid Db | `mermaid-db/` | Turn a SQL artifact (proc, view, query, .sql file, or table name) into a Mermaid diagram that explains it — git-diffable, saved as .md |
+| Migrate Dir | `migrate-dir/` | Rename this repo's legacy `.claudster/` artifact dir to `.caddis/` — dry-run first, `git mv` to keep history, merges a straggler dir, rewrites live refs. Opt-in, never automatic. |
+| Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
+| Resume | `resume/` | Pop the most recently parked workstream off the stack and resume it at its exact resume point |
+| Ship | `ship/` | Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only) |
+| Ship Merge | `ship-merge/` | Merge an already-green, already-reviewed PR behind an explicit deploy-confirm, monitor the deploy, validate prod, then clean up the branch — only on green. |
+| Ship Pr | `ship-pr/` | Open a reviewed PR for the current feature branch — rebase-safe push, PR create/update, monitor CI, STOP at green. Never merges, never deploys (that's /ship-merge). |
+| Tdd | `tdd/` | Run a strict red-green-refactor TDD cycle for a unit of behavior |
+| Ui Brief | `ui-brief/` | Design-first UI brief — lock the aesthetic before writing any code |
+| Usage Review | `usage-review/` | Review local caddis usage over a window, surface prioritised recommendations, and apply config changes in one step |
+| Use Model | `use-model/` | Explain (or apply) the model lanes — claude / claude-glm / cross-review — key resolution, and how to add a provider |
+| Version | `version/` | Report the installed caddis version |
+
+### Media
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Draw Io | `draw-io/` | draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage. |
+| Mermaid Diagrams | `mermaid-diagrams/` | Create software diagrams using Mermaid text-based syntax. Use for class diagrams (domain modeling, OOP design), sequence diagrams (API flows, interactions), flowcharts (processes, algorithms, user journeys), ERD (database schemas), C4 architecture diagrams, state diagrams, git graphs, gantt charts, and data visualization. |
+| Particle Art | `particle-art/` | Generate animated particle art React/Next.js components — zero dependencies, spring physics, CSS-variable theming, DPR-correct canvas, mouse interaction. Use when the user wants animated hero art, a living logo, a branded initial or monogram, a constellation background, or any "particles that form a shape". Triggers on "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse". Covers — text/initials → spring-node letter; preset patterns (constellation, helix, spiral, DNA, hex-grid, wave, infinity); custom SVG paths; custom polygon points; Unicode halftone stipple; Gaussian dot field with sparks; SVG circuit traces; hybrid combos. Outputs a complete, self-contained, copy-paste-ready React component. Prefer this over p5.js (zero-dep, React-native, TypeScript), tsParticles (richer spring physics, CSS-var theming), Three.js (lightweight, no WebGL). |
+
+### Testing
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Playwright | `playwright/` | Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows, check links, automate any browser task. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing. |
+| Tdd Workflow | `tdd-workflow/` | Test-Driven Development workflow — red-green-refactor cycle |
+| Test Strategy | `test-strategy/` | Test planning and strategy for projects of any size. Use when defining what to test, choosing test types, setting coverage goals, building test pyramids, or planning quality gates. Produces TEST-STRATEGY.md with prioritized test plan. Routes to Tester agent for execution. |
+| Webapp Testing | `webapp-testing/` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. |
+
+### Workflow
+
+| Skill | Path | When to Use |
+|-------|------|-------------|
+| Best Practices | `best-practices/` | >- |
+| Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
+| Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |
+| Golden Plan | `golden-plan/` | USE THIS SKILL whenever a user asks for a comprehensive implementation plan, a full-stack build plan, a UI+backend plan, or says 'create a plan for building X' where X spans multiple phases or systems. Also activate when the user says 'plan this project', 'I need a detailed plan', 'build plan', 'implementation plan', or attaches a mockup/wireframe and asks how to build it. Produces a zero-ambiguity, evidence-gated plan with self-contained per-phase prompts, exhaustive data binding tables, per-phase validation checklists, and a global quality gate. Evidence-gated: before writing phases, verify required artefacts (mockup, data sample, API contract, scaffold inventory); if any BLOCKER is missing, ask for it and wait before proceeding. Dual-mode: generic by default, junai-pipeline only when explicitly requested. Agent-agnostic - any agent with read/search/edit tools can use this skill. |
+| Preflight | `preflight/` | Plan-vs-codebase validation — verifies API contracts, type names, field accuracy, dependencies, and paths before implementation begins |
+| Setup Project Ai | `setup-project-ai/` | Install or refresh the agent-agnostic dev harness in this project (AGENTS.md-canonical rules hierarchy + CLAUDE.md @import shims, subagents, commands, settings) |
+| Skill Creator | `skill-creator/` | Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. |

package/bundles/antigravity-plugin/skills/add-rules/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: add-rules
+description: Create canonical rules for ANY folder — write <folder>/AGENTS.md (from the folder template) + a <folder>/CLAUDE.md @import shim. For folders the stack-map generator doesn't cover.
+---
+
+# /add-rules — add canonical rules to a folder
+
+Create a rules file for a folder the deterministic generator doesn't cover (stack-map only writes
+`src/`, `frontend/`, `tests/`). `AGENTS.md` is the **canonical** rules file; `CLAUDE.md` is a thin
+`@AGENTS.md` import shim beside it. This command writes both.
+
+Context / args: **$ARGUMENTS** — the first token is the target `<folder>` (repo-relative); the rest is
+an optional one-line purpose.
+
+## Steps
+
+1. **Parse args.** `<folder>` = first token; `[purpose]` = the remainder (may be empty). If `<folder>`
+   is missing, ask which folder and stop. Resolve `<folder>` relative to the repo root; if it doesn't
+   exist, say so and stop (create the folder first, or fix the path).
+
+2. **Refuse to clobber.** If `<folder>/AGENTS.md` already exists, STOP — do **not** overwrite it. Point
+   the user at the `knowledge-transfer` / `claude-md-curator` agents for *updating* existing rules (they
+   target ANY existing `AGENTS.md`). This command only *creates* new folder rules.
+
+3. **Seed from the folder.** Read a representative sample of `<folder>`'s contents (a few files, the
+   most-imported modules, any local README) to learn the real conventions, layering, naming, test
+   pattern, and non-obvious gotchas. Combine that with `[purpose]`. Do not invent rules the code
+   doesn't support; prefer a short honest file over a padded one.
+
+4. **Write `<folder>/AGENTS.md`** from the folder template `claude-md/folder-agents.md.tmpl` (resolve
+   `<harness-root>` the same way `/setup-project-ai` does: `${CLAUDE_PLUGIN_ROOT}/claude-md/…` for a
+   plugin install, else the `claude-harness/claude-md/…` checkout path). Fill `{{FOLDER}}` and
+   `{{FOLDER_PURPOSE}}`, then replace the `<…>` section stubs (Conventions, Gotchas / non-obvious,
+   Adding functionality) with what you learned in Step 3. Keep it lean (the ~80-line budget applies).
+
+5. **Write `<folder>/CLAUDE.md`** as the exact 2-line shim (nothing more — never put rules here):
+   ```
+   # Folder conventions — canonical in AGENTS.md (imported below; Claude Code inlines it)
+   @AGENTS.md
+   ```
+
+6. **Report + remind.** Show the two files written. Remind that ongoing updates flow through the
+   `knowledge-transfer` (end-of-session capture) and `claude-md-curator` (periodic prune) agents — they
+   match ANY existing `AGENTS.md`, so no per-folder upkeep command is needed. Codex and Antigravity
+   (`agy`) read the `AGENTS.md` directly; Claude Code inlines it via the `CLAUDE.md` shim.

package/bundles/antigravity-plugin/skills/api-design/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: api-design
+description: REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation.
+---
+
+# API Design Skill
+
+Design APIs that are consistent, discoverable, and hard to misuse. Conventions over configuration.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Designing new API endpoints or a full API surface
+- "What should this endpoint look like?"
+- Planning API versioning or migration
+- Reviewing API contracts for consistency
+- Building an API spec or OpenAPI document
+
+## 2. REST Resource Naming
+
+### URL Convention
+
+```
+# Resources are nouns, plural, lowercase, kebab-case
+GET    /api/v1/customers                  # List
+GET    /api/v1/customers/{id}             # Get one
+POST   /api/v1/customers                  # Create
+PUT    /api/v1/customers/{id}             # Full update
+PATCH  /api/v1/customers/{id}             # Partial update
+DELETE /api/v1/customers/{id}             # Delete
+
+# Nested resources for strong ownership
+GET    /api/v1/customers/{id}/orders      # Customer's orders
+POST   /api/v1/customers/{id}/orders      # Create order for customer
+
+# Actions (when CRUD doesn't fit) — verb suffix
+POST   /api/v1/orders/{id}/cancel         # Action on resource
+POST   /api/v1/reports/generate           # Trigger async operation
+```
+
+### Naming Rules
+
+| Rule | Good | Bad |
+|------|------|-----|
+| Plural nouns | `/customers` | `/customer`, `/getCustomers` |
+| Kebab-case | `/order-items` | `/orderItems`, `/order_items` |
+| No verbs in path | `/customers` (POST = create) | `/createCustomer` |
+| Consistent nesting depth | Max 2 levels: `/customers/{id}/orders` | `/customers/{id}/orders/{id}/items/{id}/details` |
+| No trailing slash | `/customers` | `/customers/` |
+
+## 3. Request & Response Envelope
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "request_id": "req_abc123",
+    "timestamp": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+### List Response (with pagination)
+
+```json
+{
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "per_page": 25,
+    "total": 142,
+    "total_pages": 6
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Invalid email format" },
+      { "field": "age", "message": "Must be at least 18" }
+    ]
+  }
+}
+```
+
+## 4. HTTP Status Codes
+
+Use the right code. Clients depend on these for control flow.
+
+| Code | When to Use |
+|------|-------------|
+| `200 OK` | Successful GET, PUT, PATCH |
+| `201 Created` | Successful POST that creates a resource |
+| `204 No Content` | Successful DELETE |
+| `400 Bad Request` | Malformed request body or parameters |
+| `401 Unauthorized` | Missing or invalid authentication |
+| `403 Forbidden` | Authenticated but not authorized |
+| `404 Not Found` | Resource doesn't exist |
+| `409 Conflict` | Duplicate resource, version conflict |
+| `422 Unprocessable Entity` | Valid syntax but semantic validation failed |
+| `429 Too Many Requests` | Rate limit exceeded (include `Retry-After` header) |
+| `500 Internal Server Error` | Unhandled server error |
+
+## 5. Pagination
+
+### Offset-based (simple, good for most cases)
+
+```
+GET /api/v1/customers?page=2&per_page=25
+```
+
+### Cursor-based (better for real-time data, large datasets)
+
+```
+GET /api/v1/events?cursor=eyJpZCI6MTAwfQ&limit=25
+```
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| Offset | Simple, supports jumping to page N | Skips/duplicates on mutations, slow at high offsets |
+| Cursor | Consistent with mutations, performant | No "jump to page 5", harder to implement |
+
+**Rule:** Use offset for admin/dashboard UIs. Use cursor for feeds, events, and public APIs.
+
+## 6. Filtering, Sorting, and Search
+
+```
+# Filtering — field-level with operators
+GET /api/v1/orders?status=open&created_after=2025-01-01
+
+# Sorting — field with direction prefix
+GET /api/v1/orders?sort=-created_at        # descending
+GET /api/v1/orders?sort=status,created_at   # multi-field
+
+# Search — dedicated parameter
+GET /api/v1/customers?q=acme+corp
+
+# Field selection — sparse fieldsets
+GET /api/v1/customers?fields=id,name,email
+```
+
+## 7. Versioning
+
+### URL Path versioning (recommended)
+
+```
+/api/v1/customers
+/api/v2/customers
+```
+
+### Version lifecycle
+
+| Phase | Duration | Behaviour |
+|-------|----------|-----------|
+| **Current** | Indefinite | Actively maintained |
+| **Deprecated** | 6-12 months | Returns `Deprecation` header, still works |
+| **Sunset** | After deprecation | Returns `410 Gone` |
+
+```python
+# FastAPI deprecation header
+@app.get("/api/v1/old-endpoint", deprecated=True)
+async def old_endpoint(response: Response):
+    response.headers["Deprecation"] = "true"
+    response.headers["Sunset"] = "2026-06-01"
+    response.headers["Link"] = '</api/v2/new-endpoint>; rel="successor-version"'
+    return {"data": ...}
+```
+
+## 8. Authentication & Security
+
+- Use `Authorization: Bearer <token>` for API auth
+- Never put tokens in URL query parameters (they appear in logs)
+- Return `401` for missing/invalid auth, `403` for insufficient permissions
+- Include `X-Request-Id` header for tracing
+- Rate limit all public endpoints
+
+## 9. FastAPI Implementation Pattern
+
+```python
+from fastapi import APIRouter, Depends, Query, HTTPException, status
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/api/v1/customers", tags=["customers"])
+
+class CustomerCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=200)
+    email: str = Field(..., pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
+
+class CustomerResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+class PaginatedResponse(BaseModel):
+    data: list[CustomerResponse]
+    pagination: dict
+
+@router.get("", response_model=PaginatedResponse)
+async def list_customers(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(25, ge=1, le=100),
+):
+    ...
+
+@router.post("", response_model=CustomerResponse, status_code=status.HTTP_201_CREATED)
+async def create_customer(body: CustomerCreate):
+    ...
+
+@router.get("/{customer_id}", response_model=CustomerResponse)
+async def get_customer(customer_id: str):
+    customer = await repo.find(customer_id)
+    if not customer:
+        raise HTTPException(status_code=404, detail="Customer not found")
+    return customer
+```
+
+## 10. API Design Checklist
+
+Before shipping an API endpoint:
+
+- [ ] Resource names are plural nouns in kebab-case
+- [ ] Correct HTTP methods (GET reads, POST creates, etc.)
+- [ ] Correct status codes (201 for create, 204 for delete)
+- [ ] Request body validated with Pydantic/Zod
+- [ ] Error responses use consistent envelope with error code
+- [ ] Pagination implemented for list endpoints
+- [ ] Authentication required (unless intentionally public)
+- [ ] Rate limiting configured
+- [ ] OpenAPI spec generated and reviewed
+- [ ] No sensitive data in URLs or logs
+
+## 11. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Verbs in URLs | `/getUser`, `/deleteOrder` | Use HTTP methods + nouns |
+| Inconsistent pluralisation | `/user` vs `/orders` | Always plural |
+| Returning 200 for errors | Client can't distinguish success/failure | Use proper status codes |
+| Nested resources > 2 levels | Hard to discover, fragile URLs | Flatten with query params |
+| No pagination on lists | Unbounded response size, OOM | Always paginate |
+| Exposing internal IDs/schemas | Coupling clients to implementation | Use public-facing schemas |