@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/digitalocean/scripts/verify.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# verify.sh — offline structural lint for DigitalOcean App Platform app specs.
+#
+# Read-only. Finds candidate app specs and checks they are parseable YAML with the
+# required App Platform top-level keys. Inline-secret literals are WARNINGS, not failures.
+# Exits 0 on a clean/empty target (no spec found is fine — nothing to lint).
+# Exits non-zero only when a found spec is unparseable YAML or missing required keys.
+#
+# Usage:
+#   scripts/verify.sh [path-to-spec-or-dir]   # default: current directory
+set -euo pipefail
+
+target="${1:-.}"
+fail=0
+checked=0
+
+# --- find candidate specs ----------------------------------------------------
+candidates=()
+if [ -f "$target" ]; then
+  candidates+=("$target")
+elif [ -d "$target" ]; then
+  while IFS= read -r f; do candidates+=("$f"); done < <(
+    {
+      [ -f "$target/.do/app.yaml" ] && printf '%s\n' "$target/.do/app.yaml"
+      find "$target" -type f \
+        \( -iname '*app*spec*.yml' -o -iname '*app*spec*.yaml' -o -path '*/.do/app.yaml' -o -path '*/.do/app.yml' \) \
+        2>/dev/null
+    } | sort -u
+  )
+else
+  echo "verify: target not found: $target" >&2
+  exit 0   # nothing to lint -> clean
+fi
+
+if [ "${#candidates[@]}" -eq 0 ]; then
+  echo "verify: no App Platform app spec found under '$target' — nothing to lint."
+  exit 0
+fi
+
+# --- pick a YAML parser -------------------------------------------------------
+yaml_ok() {  # $1=file -> 0 if parseable
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$1" <<'PY' 2>/dev/null
+import sys, yaml
+yaml.safe_load(open(sys.argv[1]))
+PY
+    return $?
+  elif command -v yq >/dev/null 2>&1; then
+    yq eval '.' "$1" >/dev/null 2>&1
+    return $?
+  fi
+  return 2  # no parser
+}
+
+have_key() {  # $1=file $2=key -> 0 if top-level key present (best-effort grep)
+  grep -Eq "^[[:space:]]*${2}:" "$1"
+}
+
+parser_warned=0
+
+for spec in "${candidates[@]}"; do
+  checked=$((checked + 1))
+  echo "verify: checking $spec"
+
+  yaml_ok "$spec"
+  rc=$?
+  if [ "$rc" -eq 2 ]; then
+    if [ "$parser_warned" -eq 0 ]; then
+      echo "  WARN: no python3/yq found — skipping YAML parse, doing key + secret grep only"
+      parser_warned=1
+    fi
+  elif [ "$rc" -ne 0 ]; then
+    echo "  FAIL: not parseable YAML"
+    fail=1
+    continue
+  fi
+
+  # required: name
+  if ! have_key "$spec" name; then
+    echo "  FAIL: missing required top-level key 'name'"
+    fail=1
+  fi
+
+  # required: at least one component type
+  if ! grep -Eq "^[[:space:]]*(services|static_sites|workers|jobs|functions):" "$spec"; then
+    echo "  FAIL: needs at least one of services|static_sites|workers|jobs|functions"
+    fail=1
+  fi
+
+  # warn: inline secret literals not behind a SECRET-typed env
+  if grep -Eqi 'dop_v1_[a-f0-9]|(password|secret|api[_-]?key|token)[[:space:]]*[:=][[:space:]]*["'\'']?[A-Za-z0-9/_+-]{12,}' "$spec"; then
+    echo "  WARN: a token/secret-looking literal appears inline — use 'type: SECRET' or \${...} injection"
+  fi
+done
+
+# --- optional doctl hint ------------------------------------------------------
+if command -v doctl >/dev/null 2>&1; then
+  echo "verify: doctl detected — for an authoritative check run: doctl apps spec validate <spec>"
+fi
+
+echo "verify: checked $checked spec(s)."
+exit "$fail"

package/skills/shared/django/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: django
+description: "Use when building, reviewing, securing, testing or shipping a Django app — models, migrations, QuerySets/managers, FBV/CBV views, forms, the admin, settings split, and Django REST Framework (serializers, ModelViewSet, permissions). NOT async FastAPI/Pydantic services (that is `fastapi`), NOT Postgres schema/index work (that is `postgresdb`)."
+tags: [python, django, orm, drf, backend, web]
+recommends: [postgresdb, secure-coding, deployment, testing-py, api-design]
+origin: ai-hub
+---
+
+# Django web applications
+
+The single authoritative skill for building, reviewing, securing, testing and shipping a
+**Django** app — the batteries-included, ORM-first, request/response Python framework.
+
+Mental model: **a Django project is apps composed of fat-but-thin-enough models (domain +
+query logic on the model/manager), views that orchestrate (FBV/CBV/DRF) and never own SQL,
+an admin/forms layer, and a settings module split by environment.** The ORM, migrations,
+auth, admin, CSP and the test runner are all first-party. Reach for the framework before you
+add a dependency.
+
+## Pinned stack (2026-06)
+
+- **Django 5.2 LTS** — the production default. Released 2025-04-02, security fixes until
+  ~April 2028, supports Python 3.10–3.14. New in 5.2: all models auto-imported in `shell`,
+  `CompositePrimaryKey`, `BoundField` customization.
+- **Django 6.0** — released 2025-12-03 (non-LTS, ~8 months until 6.1). Choose it only when you
+  want the new built-in **Tasks framework** (background jobs without Celery) or **native CSP**
+  (`ContentSecurityPolicyMiddleware`, `SECURE_CSP`) and can take the shorter support window.
+  Drops Python 3.10/3.11; supports 3.12–3.14.
+- **Django REST Framework 3.17.1** (2026-03-24) — adds Django 6.0 + Python 3.14 support.
+- Python 3.12+, `pytest-django`, `factory_boy`. ruff/uv and type-hint policy live in `python`.
+
+**Version rule:** default to 5.2 LTS. Pick 6.0 only for a concrete Tasks/CSP need, and say so.
+
+## Route elsewhere
+
+| Situation | Route to |
+|---|---|
+| Async service, `fastapi`/`pydantic`/uvicorn, async SQLAlchemy | `fastapi` |
+| Postgres schema design, EXPLAIN ANALYZE, indexing strategy, RLS, pooling | `postgresdb` |
+| Cross-stack OWASP/STRIDE threat modeling | `secure-coding` |
+| Container/Compose/CI, gunicorn prod tuning, collectstatic pipeline | `deployment` |
+| REST contract design (cursor vs offset, status codes, versioning) | `api-design` |
+| ruff/uv/general type hints, packaging | `python` |
+
+## Project shape
+
+Split settings by environment; never ship one `settings.py` toggled by `DEBUG`.
+
+```text
+src/
+  manage.py
+  config/
+    settings/
+      base.py      # shared; reads secrets from os.environ
+      dev.py       # from base import *; DEBUG=True; local hosts
+      prod.py      # from base import *; DEBUG=False; SECURE_*; CSP
+  catalog/         # an app = a bounded domain
+    models.py  managers.py  views.py  serializers.py  urls.py  admin.py
+    migrations/
+    tests/
+```
+
+- Read secrets with `os.environ["SECRET_KEY"]` (or `django-environ`). **Never** commit a
+  literal `SECRET_KEY` — a leaked key forges sessions and signed tokens.
+- Select env via `DJANGO_SETTINGS_MODULE=config.settings.prod`, not an `if DEBUG` branch.
+- One app = one domain. Resist a single `core` app that accretes everything.
+
+## Models
+
+Put domain and query logic on the model and its manager. The view stays thin.
+
+```python
+# managers.py
+from django.db import models
+
+class ArticleQuerySet(models.QuerySet):
+    def published(self):
+        return self.filter(status=Article.Status.PUBLISHED)
+
+    def for_reader(self):  # composes; reused everywhere, tested once
+        return self.published().select_related("author")
+
+# models.py
+class Article(models.Model):
+    class Status(models.TextChoices):
+        DRAFT = "draft", "Draft"
+        PUBLISHED = "published", "Published"
+
+    tenant = models.ForeignKey("Tenant", on_delete=models.CASCADE)
+    slug = models.SlugField()
+    author = models.ForeignKey("Author", on_delete=models.PROTECT)
+    status = models.CharField(max_length=16, choices=Status.choices, default=Status.DRAFT)
+    published_at = models.DateTimeField(null=True, blank=True)
+
+    objects = ArticleQuerySet.as_manager()
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(fields=["tenant", "slug"], name="uniq_tenant_slug"),
+            models.CheckConstraint(
+                check=models.Q(status="draft") | models.Q(published_at__isnull=False),
+                name="published_needs_date",
+            ),
+        ]
+        indexes = [models.Index(fields=["tenant", "status"])]
+```
+
+- **Constraints live in the DB, not just Python.** A `UniqueConstraint`/`CheckConstraint` is
+  enforced under concurrency; a `clean()` check is not. Validate-in-Python-only is a foot-gun.
+- `on_delete` is mandatory and load-bearing: `CASCADE` deletes children, `PROTECT` blocks the
+  delete, `SET_NULL` orphans. Choosing wrong silently destroys data — pick deliberately.
+- Multi-column PK (5.2+): `pk = models.CompositePrimaryKey("tenant_id", "id")`.
+- Bad→Good for business logic:
+
+```python
+# Bad: logic in the view — untested, unreusable, duplicated across endpoints
+def publish(request, pk):
+    a = Article.objects.get(pk=pk)
+    a.status = "published"; a.published_at = timezone.now(); a.save()
+
+# Good: a method on the model — one place, testable, reused by view/admin/command
+class Article(models.Model):
+    def publish(self):
+        self.status = self.Status.PUBLISHED
+        self.published_at = timezone.now()
+        self.save(update_fields=["status", "published_at"])
+```
+
+## QuerySet performance
+
+The N+1 is the single most common Django defect: one query for the list, then one more per row.
+
+```python
+# Bad: 1 + N queries — each .author touches the DB inside the loop
+for a in Article.objects.all():
+    print(a.author.name)
+
+# Good: 2 queries total (FK -> JOIN; reverse/M2M -> second query)
+for a in Article.objects.select_related("author").prefetch_related("tags"):
+    print(a.author.name, [t.name for t in a.tags.all()])
+```
+
+| You are following | Use | Cost |
+|---|---|---|
+| Forward `ForeignKey` / `OneToOne` | `select_related(...)` | SQL JOIN, 1 query |
+| Reverse FK, `ManyToMany` | `prefetch_related(...)` | 2nd query, joined in Python |
+| Prefetch that itself needs filter/order | `Prefetch("x", queryset=...)` | controlled 2nd query |
+
+- Need existence, not rows? `qs.exists()`, never `len(qs)` or `if qs.count()`.
+- Need a few columns of a wide row? `.only("id", "slug")` / `.defer("body")`.
+- Computed totals belong in the DB: `annotate(...)` / `aggregate(...)`, not a Python loop.
+- Many inserts: `bulk_create(objs)` — one round-trip, not N `.save()` calls.
+- Never `Model.objects.all()` then slice/filter in Python; push it into the QuerySet.
+
+Deeper recipes (`assertNumQueries`, `Prefetch`, `.explain()`, ORM indexing) →
+[references/orm-performance.md](references/orm-performance.md).
+
+## Views & URLs
+
+Keep views thin: validate input, call a model/manager method, return a response. No SQL.
+
+| Need | Use |
+|---|---|
+| One bespoke action, custom flow | function-based view (FBV) |
+| Standard list/detail/create/update/delete on a model | generic CBV (`ListView`, `DetailView`, …) |
+| JSON API consumed by a client/SPA | drop to DRF (do **not** hand-roll `JsonResponse` CRUD) |
+
+For the DRF surface — serializers, `ModelViewSet`, routers, permissions, throttling,
+pagination, filtering, nested-serializer N+1, versioning — see
+[references/drf.md](references/drf.md). The thin-view rule still holds: a fat serializer that
+walks relations per row is just an N+1 wearing a tie.
+
+## Migrations
+
+```bash
+python manage.py makemigrations catalog   # generate from model diff
+python manage.py migrate                   # apply
+python manage.py makemigrations --check    # CI gate: fail if a model drifts from migrations
+```
+
+- **Never edit a migration that has been applied anywhere.** Add a new one. Editing rewrites
+  history and breaks every environment that already ran it.
+- Data backfills go through `migrations.RunPython(forward, reverse)` with a reverse, not a
+  one-off script. Use the historical model from `apps.get_model(...)`, not the imported class.
+- Schema changes on a live table that you cannot afford to lock are expand-and-contract; the
+  Postgres-side mechanics (lock modes, batching) live in `postgresdb`.
+
+## Security
+
+Set these in `prod.py`. Then prove it: `python manage.py check --deploy` must come back clean.
+
+| Setting | Value | Why |
+|---|---|---|
+| `DEBUG` | `False` | `True` leaks settings + a stack-trace shell to the world |
+| `ALLOWED_HOSTS` | explicit domains | `['*']` enables Host-header attacks |
+| `SECRET_KEY` | from `os.environ` | a literal in source forges signed cookies/tokens |
+| `SECURE_SSL_REDIRECT` | `True` | force HTTPS |
+| `SECURE_HSTS_SECONDS` | `31536000` (+ include-subdomains, preload) | the `check --deploy` warning you saw is this being 0 |
+| `SESSION_COOKIE_SECURE` / `CSRF_COOKIE_SECURE` | `True` | stop cookie leak over HTTP |
+| `SECURE_CSP` (Django 6.0) | a real policy + nonce | native CSP; pre-6.0 use `django-csp` |
+
+- CSRF protection is on by default — keep `CsrfViewMiddleware`; do not blanket-exempt views.
+- The ORM parameterizes queries. Only `.raw()`, `.extra()` and `cursor.execute()` with an
+  f-string/`%`-built string reopen SQL injection. Pass params, never interpolate.
+
+Full `SECURE_*` checklist, CSP nonce/report-only, upload/SSRF, ORM-injection →
+[references/security.md](references/security.md).
+
+## Testing
+
+```python
+import pytest
+from rest_framework.test import APIClient
+
+@pytest.mark.django_db
+def test_owner_only(article, owner):
+    client = APIClient()
+    assert client.get(f"/api/articles/{article.pk}/").status_code == 403  # anon
+    client.force_authenticate(owner)
+    assert client.get(f"/api/articles/{article.pk}/").status_code == 200
+```
+
+- `pytest-django` + `@pytest.mark.django_db`; run with `--reuse-db` to skip rebuilds locally.
+- `TestCase` wraps each test in a rolled-back transaction (fast). Use `TransactionTestCase`
+  only when you test `on_commit` hooks or real commit behavior.
+- Lock in N+1 fixes with `assertNumQueries(2)` — it fails the build when a relation regresses.
+- Build instances with `factory_boy`, not 30 lines of `Model.objects.create(...)`.
+
+Setup, fixtures, transactional DB, coverage → [references/testing.md](references/testing.md).
+
+## Background work
+
+| Need | Use |
+|---|---|
+| New project on Django 6.0, simple enqueue-and-forget jobs | the built-in **Tasks framework** |
+| Pre-6.0, or you need schedules/retries/fan-out/result backends/workers at scale | **Celery** |
+
+Either way: enqueue from the model/service layer, never block the request thread.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Business logic in the view | untested, duplicated across endpoints | method on the model/manager |
+| f-string SQL into `.raw()`/`.extra()`/`cursor.execute` | SQL injection | parameterized queries |
+| Looping rows touching `.author` | N+1 queries | `select_related`/`prefetch_related` |
+| `DEBUG=True` in prod | leaks settings + stack traces | `DEBUG=False` in `prod.py` |
+| `SECRET_KEY` literal in source | forged sessions/tokens | `os.environ` |
+| Validation only in `clean()` | races under concurrency | DB `UniqueConstraint`/`CheckConstraint` |
+| `Model.objects.all()` in a template loop | one query per iteration | prefetch in the view |
+| `ModelViewSet` with no `permission_classes` | endpoint open to the world | explicit permission class |
+| Fat serializer walking relations | N+1 per response | prefetch + `assertNumQueries` |
+| Editing an applied migration | breaks every env that ran it | new migration |
+| `len(qs)` / `qs.count()` to test existence | full fetch/COUNT | `qs.exists()` |
+| Swallowing `Model.DoesNotExist` silently | hidden bugs | `get_object_or_404` or handle explicitly |
+
+## Verify
+
+`scripts/verify.sh [TARGET]` greps tracked Django source for high-signal foot-guns:
+FAIL on a literal `SECRET_KEY`, `ALLOWED_HOSTS = ['*']`, or f-string SQL in
+`.raw()`/`.extra()`/`cursor.execute`; WARN on `DEBUG = True` outside a dev settings file and
+a `ModelViewSet`/`APIView` with no `permission_classes`. Read-only, exit 0 on a clean or empty
+target. It is a lint, not a substitute for `manage.py check --deploy` or the test suite.

package/skills/shared/django/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `django` skill
+
+`cases.yaml` is a trigger/routing and capability rubric, not an automated test harness. Run it
+by reading each prompt and checking the skill behaves: every `should_trigger` prompt should make
+the `django` skill fire (including the non-obvious template-N+1 case and the Spanish phrasings),
+and every `should_not_trigger` prompt should route to the named sibling (`fastapi`, `postgresdb`,
+`secure-coding`, `api-design`) instead. For the `capability` case, draft the answer and confirm it
+hits every line in `must_include` — model with FK + Meta, explicit `ModelSerializer`, `ModelViewSet`
+with `permission_classes`, owner-scoped `get_queryset` with `select_related`, router registration,
+`perform_create` setting the owner, the `APIClient.force_authenticate` 403/200 test, and the
+migration step. A miss on any line means the skill body or references need tightening.

package/skills/shared/django/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: django
+
+should_trigger:
+  - prompt: "Add a `published` filter and fix the N+1 in this Django ListView."
+    why: Core Django — QuerySet filtering plus select_related/prefetch_related on a CBV.
+  - prompt: "Build a DRF ModelViewSet for Orders with owner-only permission and wire it into a router."
+    why: Django REST Framework surface — serializer, viewset, router, object-level permission.
+  - prompt: "This template loops over `books` and queries `book.author` on each iteration and the page is slow."
+    why: Non-obvious — no word 'Django', but it is the classic ORM N+1 inside a template loop.
+  - prompt: "Revisa este modelo y añade un UniqueConstraint en (tenant, slug)."
+    why: Spanish/Catalan phrasing for a Django model Meta constraint change.
+  - prompt: "Why does `python manage.py check --deploy` warn about SECURE_HSTS_SECONDS?"
+    why: Django-specific security/settings question; the warning is the default 0 value.
+  - prompt: "El queryset hace N+1 al renderizar el feed; ¿cómo lo arreglo con prefetch?"
+    why: Spanish, non-obvious ORM performance phrasing pointing straight at prefetch_related.
+  - prompt: "Convert this fat publish() logic out of the view onto the model and add a data migration."
+    why: Fat-model rule plus RunPython migration — both squarely Django implementation.
+
+should_not_trigger:
+  - prompt: "Build an async FastAPI endpoint with Pydantic models and async SQLAlchemy."
+    route_to: fastapi
+    why: Async-first service importing fastapi/pydantic; no manage.py/INSTALLED_APPS.
+  - prompt: "Write the EXPLAIN ANALYZE for this slow query and add the right Postgres index."
+    route_to: postgresdb
+    why: DB-side query plan and indexing strategy, ORM-agnostic.
+  - prompt: "Do a STRIDE threat model of our payment flow."
+    route_to: secure-coding
+    why: Cross-stack threat modeling, not Django middleware/CSP knobs.
+  - prompt: "Should this REST API use cursor or offset pagination, and what status code for a partial update?"
+    route_to: api-design
+    why: REST contract design; the DRF wiring would be django, the contract choice is api-design.
+
+capability:
+  - scenario: >
+      Create a Django app `catalog` with a `Product` model (name, price, owner FK to the user),
+      a DRF ModelSerializer and ModelViewSet exposing it read/write to the owner only, wired into
+      a DefaultRouter, plus a pytest-django test asserting an anonymous user gets 403 and the
+      owner gets 200. Include the migration step.
+    must_include:
+      - "Product model with an owner ForeignKey and a Meta (constraint or index)"
+      - "ModelSerializer with an explicit fields list and owner as read-only"
+      - "ModelViewSet with permission_classes (IsAuthenticated + object-level IsOwner)"
+      - "get_queryset scoped to request.user and using select_related to avoid N+1"
+      - "DefaultRouter registration of the viewset"
+      - "perform_create sets owner=self.request.user (not from request data)"
+      - "pytest-django test using APIClient.force_authenticate, asserting 403 anon and 200 owner"
+      - "makemigrations/migrate step for the new model"

package/skills/shared/django/references/drf.md

@@ -0,0 +1,109 @@
+# Django REST Framework (DRF 3.17.x)
+
+DRF turns models into a JSON API. The layering mirrors core Django: **serializer = form/marshal,
+viewset = view, router = URLconf**. Keep business logic on the model; the serializer validates
+and shapes, the viewset orchestrates.
+
+## Serializers
+
+Prefer `ModelSerializer` — it derives fields and validators from the model.
+
+```python
+from rest_framework import serializers
+from catalog.models import Product
+
+class ProductSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Product
+        fields = ["id", "name", "price", "owner"]
+        read_only_fields = ["owner"]  # set server-side, never trust the client
+
+    def validate_price(self, value):
+        if value < 0:
+            raise serializers.ValidationError("price must be non-negative")
+        return value
+```
+
+- Use an explicit `fields` list. `fields = "__all__"` leaks new columns the moment a model grows.
+- Server-owned fields (`owner`, `tenant`, timestamps) are `read_only`; set them in
+  `perform_create`, not from request data.
+- A plain `serializers.Serializer` is for non-model payloads (search params, RPC-style bodies).
+
+## ViewSets + routers
+
+```python
+from rest_framework import viewsets, permissions
+from rest_framework.routers import DefaultRouter
+
+class IsOwner(permissions.BasePermission):
+    def has_object_permission(self, request, view, obj):
+        return obj.owner_id == request.user.id
+
+class ProductViewSet(viewsets.ModelViewSet):
+    serializer_class = ProductSerializer
+    permission_classes = [permissions.IsAuthenticated, IsOwner]
+
+    def get_queryset(self):
+        # scope to the caller AND prefetch — the viewset is where N+1 is born
+        return Product.objects.filter(owner=self.request.user).select_related("owner")
+
+    def perform_create(self, serializer):
+        serializer.save(owner=self.request.user)
+
+router = DefaultRouter()
+router.register("products", ProductViewSet, basename="product")
+urlpatterns = router.urls
+```
+
+- **Every viewset declares `permission_classes`.** A `ModelViewSet` with none is a fully open
+  CRUD endpoint. Set a project default in `DEFAULT_PERMISSION_CLASSES` and override per view.
+- `IsAuthenticated` gates the request; object-level checks live in `has_object_permission`.
+- `get_queryset` filters by tenant/owner *and* prefetches. A serializer that walks a relation
+  with no prefetch is an N+1 per row — assert query counts in tests.
+
+## Pagination, throttling, filtering
+
+```python
+# settings: DRF defaults
+REST_FRAMEWORK = {
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.CursorPagination",
+    "PAGE_SIZE": 50,
+    "DEFAULT_THROTTLE_CLASSES": ["rest_framework.throttling.ScopedRateThrottle"],
+    "DEFAULT_THROTTLE_RATES": {"login": "5/min", "default": "1000/day"},
+    "DEFAULT_FILTER_BACKENDS": ["rest_framework.filters.SearchFilter",
+                                "rest_framework.filters.OrderingFilter"],
+}
+```
+
+```python
+class ProductViewSet(viewsets.ModelViewSet):
+    search_fields = ["name"]
+    ordering_fields = ["price", "name"]
+    throttle_scope = "default"
+```
+
+- Pagination is not optional: an unpaginated list endpoint returns the whole table.
+- Throttle auth/login and write endpoints. `ScopedRateThrottle` lets you rate-limit per view.
+- *Whether* the contract should use cursor vs offset, what status codes to return, and how to
+  version is `api-design`; this file is the DRF wiring of whatever contract you chose.
+
+## Nested serializers without N+1
+
+```python
+class OrderSerializer(serializers.ModelSerializer):
+    items = ItemSerializer(many=True, read_only=True)
+    class Meta:
+        model = Order
+        fields = ["id", "items"]
+
+# viewset queryset MUST prefetch the nested relation
+Order.objects.prefetch_related("items")
+```
+
+A nested serializer with no matching `prefetch_related` issues one query per parent row. The
+fix is always in `get_queryset`, never in the serializer.
+
+## Versioning & schema
+
+- Version via `URLPathVersioning` (`/api/v1/...`) — explicit and cache-friendly.
+- Generate an OpenAPI schema with `drf-spectacular`; do not hand-write API docs.

package/skills/shared/django/references/orm-performance.md

@@ -0,0 +1,91 @@
+# ORM performance recipes
+
+The ORM is fast when you tell it what to fetch. Almost every slow Django page is an N+1 or a
+fetch of columns/rows you never use.
+
+## select_related vs prefetch_related vs Prefetch
+
+```python
+# Forward FK / OneToOne -> SQL JOIN, one query
+Article.objects.select_related("author", "author__profile")
+
+# Reverse FK / ManyToMany -> a second query, joined in Python
+Author.objects.prefetch_related("articles", "tags")
+
+# Prefetch that needs its own filter/order/select_related
+from django.db.models import Prefetch
+Author.objects.prefetch_related(
+    Prefetch("articles",
+             queryset=Article.objects.published().select_related("category"))
+)
+```
+
+- `select_related` only follows single-valued relations (FK, O2O). Use it for the JOIN.
+- `prefetch_related` handles multi-valued relations and runs a separate `IN (...)` query.
+- `Prefetch` is the escape hatch when the related set needs filtering, ordering, or its own
+  `select_related` — otherwise you re-introduce an N+1 inside the prefetch.
+
+## Proving query counts
+
+```python
+from django.test import TestCase
+
+class FeedQueryCount(TestCase):
+    def test_feed(self):
+        with self.assertNumQueries(2):
+            [a.author.name for a in Article.objects.select_related("author")]
+```
+
+In a shell, eyeball SQL with `django.db.connection.queries` (needs `DEBUG=True`) or wrap a block
+in `CaptureQueriesContext`.
+
+## Fetch less
+
+```python
+Article.objects.only("id", "slug", "title")     # SELECT just these columns
+Article.objects.defer("body")                    # everything except the heavy one
+Article.objects.values("id", "slug")             # dicts, no model instances
+Article.objects.values_list("id", flat=True)     # a flat list of ids
+```
+
+- `.exists()` for existence; `.count()` only when you truly need the integer.
+- Never `list(Model.objects.all())` then filter/slice in Python — push it into the QuerySet.
+
+## Aggregate in the DB, not in Python
+
+```python
+from django.db.models import Count, Sum, Q
+
+Author.objects.annotate(
+    published=Count("articles", filter=Q(articles__status="published"))
+)
+Order.objects.aggregate(total=Sum("amount"))
+```
+
+A Python loop summing `.amount` over a queryset is one row fetched per iteration plus the math;
+`annotate`/`aggregate` does it in a single SQL pass.
+
+## Bulk writes
+
+```python
+Article.objects.bulk_create(objs, batch_size=500)            # one round-trip
+Article.objects.bulk_update(objs, ["status"], batch_size=500)
+Article.objects.filter(status="draft").update(status="published")  # set-based, no Python loop
+```
+
+`.update()` is a single UPDATE and skips `save()`/signals — use it for set-based changes, and a
+loop of `.save()` only when you need per-row signals/`save()` logic.
+
+## Indexing through the ORM
+
+```python
+class Meta:
+    indexes = [
+        models.Index(fields=["tenant", "status"]),
+        models.Index(fields=["-published_at"], name="article_recent"),
+    ]
+```
+
+Add the index where your hot `filter`/`order_by` actually hits. *Which* index, and reading
+`EXPLAIN ANALYZE`, is `postgresdb`; here you just express it. Inspect a query plan from the ORM
+with `qs.explain()`.