@damiangilgonzalez/harness 1.3.7

package/skills/diseno-landing/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: diseno-landing
+description: "Complete system for building high-conversion landing pages: intake questions, page structure, layout choice, conversion copy, SEO, plus strict visual rules for typography, spacing, radii, backgrounds, hero, icons, and motion. Use whenever building, editing, styling, reviewing, or writing copy for ANY landing page, marketing site, web UI, page section, component, or prototype, even if the user does not mention design, conversion, tokens, or a design system. Always consult it before choosing sections, headlines, CTAs, fonts, text sizes, spacing values, radii, background colors, icons, or transitions."
+tags: ["landing-page", "conversion", "design-system", "copywriting"]
+profiles: [ui, full]
+---
+
+# Diseno de landing page
+
+Una landing no es una home. Una home sirve a varias intenciones. Una landing gana una sola:
+
+**una oferta → una audiencia → una accion principal.**
+
+Esta skill tiene dos mitades. La **Parte A** decide que dice la pagina y como se estructura. La **Parte B** es el sistema visual innegociable. Recorre la A antes de tocar la B.
+
+## Alcance
+
+Aplica a todo trabajo de UI web: landings, webs de marketing, componentes, dashboards, prototipos y revisiones de diseno. Cuando una regla de aqui choque con el defecto de un framework, gana este fichero. Cuando el prompt explicito del usuario choque con una regla, gana el usuario.
+
+---
+
+# PARTE A — Estrategia y estructura
+
+## A1. Recopilacion inicial
+
+Reune esto antes de disenar o escribir. Pregunta solo lo que falte, y en un unico bloque en vez de pregunta a pregunta.
+
+**Proposito**
+- Cual es LA accion principal? (prueba, demo, compra, lista de espera, descarga)
+- Cual es la oferta, que reciben exactamente?
+- Que cuenta como conversion? (clic, alta, compra)
+
+**Audiencia y contexto**
+- Quien es el cliente ideal?
+- Que problema intenta resolver?
+- Las tres objeciones principales, es decir por que hoy no convierte
+- Fuente de trafico: anuncios, buscador, redes, email
+- Que sabe ya el visitante cuando aterriza?
+
+**Prueba y assets**
+- Puntos de prueba: logos, testimonios, cifras, casos de exito
+- Capturas, video de demo, GIFs de producto
+- Garantias, condiciones de devolucion y de cancelacion
+
+**Restricciones**
+- Voz de marca: cercana o profesional
+- Direccion de diseno: editorial minimal, 3D jugueton, UI de cristal
+- Prioridad movil?
+
+Si el usuario no puede responder, haz una suposicion razonable, declarala en una linea y sigue. No pares la construccion.
+
+## A2. Estructura de la pagina
+
+**Sobre el pliegue (obligatorio)**
+1. Titular: resultado mas audiencia
+2. Subtitular: aclara el como y anade concrecion
+3. CTA principal: verbo claro mas lo que consiguen
+4. Una senal de prueba: tira de logos, cifra o testimonio corto
+5. Visual del hero: captura del producto, video o una ilustracion fuerte
+
+**Cuerpo de la pagina (el argumento)**
+6. De problema a solucion, una seccion
+7. Beneficios, de tres a cinco, orientados a resultado
+8. Como funciona, tres pasos
+9. Prueba social, testimonios o un caso de exito
+
+**Fondo (gestion de objeciones)**
+10. FAQ, de seis a doce preguntas
+11. Reversion del riesgo: prueba, cancela cuando quieras, garantia
+12. CTA final, identico al de arriba
+
+Incluye en algun punto del cuerpo la seccion obligatoria de revelado del lema (B11), tipicamente justo despues del hero o despues de los beneficios.
+
+## A3. Eleccion de layout
+
+Elige uno y di por que.
+
+| Tipo | Usar cuando |
+|---|---|
+| **A. Hero clasico mas secciones** | El producto se entiende con una captura en el hero. El mas comun. |
+| **B. Historia larga** | Hay que educar y vencer escepticismo. |
+| **C. Pagina minima de conversion** | Trafico de alta intencion (email a usuarios conocidos), u oferta corta tipo descarga o lista de espera. |
+| **D. Pagina de comparacion** | La intencion de busqueda incluye alternativas ("X frente a Y", "el mejor para"). |
+
+## A4. Reglas de conversion
+
+**Ajusta el mensaje a la fuente.** Si el trafico viene de anuncios, refleja el titular del anuncio en el hero y manten la misma promesa y el mismo tono visual.
+
+**Haz obvio el siguiente paso.** Un unico CTA principal. Nunca pongas CTAs que compitan sobre el pliegue.
+
+**Escribe primero el beneficio.** Las funcionalidades son lo que hace. Los beneficios son lo que eso significa para el usuario.
+
+**Se concreto.**
+- Mal: "Ahorra tiempo y optimiza"
+- Bien: "Reduce tu informe semanal de 4 horas a 15 minutos"
+
+**Reduce el riesgo.** Elige al menos uno: prueba gratis, plan gratuito, sin tarjeta, cancela cuando quieras, devolucion del dinero.
+
+**Trata las objeciones como una seccion, no como una nota al pie.** Sube la FAQ en ofertas de mucha friccion. Pon la prueba justo al lado de la afirmacion que sostiene.
+
+## A5. Redaccion
+
+**Formulas de titular**
+- "{Resultado} sin {dolor}"
+- "El {categoria} para {audiencia}"
+- "Entrega {resultado} en {tiempo}"
+
+**Subtitular.** Una o dos frases. Aclara que es y para quien.
+
+**CTA.** Verbo mas lo que consiguen. Nunca "Saber mas" ni "Enviar". Usa "Empezar prueba gratis", "Reservar una demo", "Descargar la guia".
+
+**Vinetas de beneficio.** Beneficio en negrita y luego la prueba o el detalle. Ejemplo: **Iteracion mas rapida** — genera tres variantes de layout en un clic.
+
+## A6. Orden de construccion
+
+Trabaja seccion a seccion, en este orden: hero, beneficios, como funciona, prueba, FAQ, CTA final.
+
+Nunca reconstruyas la pagina entera en cada iteracion. Seccion a seccion mantiene el control y hace revisables los diffs.
+
+## A7. SEO y AEO
+
+**No indexar** paginas de campana solo para anuncios ni ofertas muy acotadas en el tiempo. Usa `noindex` o mantenlas en una ruta no indexada.
+
+**Si indexar** ofertas perennes y paginas donde la intencion de busqueda coincide con la promesa. Anade titulo y meta descripcion claros, enlaces internos desde la home y las paginas de producto, y la FAQ en formato llano de pregunta y respuesta para AEO. Anade schema de FAQ si procede.
+
+## A8. Errores tipicos
+
+- Demasiados CTAs sobre el pliegue
+- Propuesta de valor vaga: "optimiza", "agiliza"
+- Una lista larga de funcionalidades sin resultados
+- La prueba enterrada al final
+- Layout movil que rompe la legibilidad
+- Ningun siguiente paso claro
+
+---
+
+# PARTE B — Sistema visual
+
+Todo valor visual debe resolverse por estas reglas en vez de inventarse sobre la marcha.
+
+## B1. Tipografia
+
+### Fuentes
+
+**Usa:** Geist, Manrope, Geist Mono, Poppins.
+
+**Nunca uses:** Inter, Roboto, Arial, Open Sans, Helvetica.
+
+**Nunca uses cursivas** en ningun punto de la interfaz.
+
+**Una tipografia por sitio.** No emparejes dos fuentes salvo que el prompt lo pida explicitamente. Geist Mono se permite junto a la principal solo para codigo, datos o UI numerica donde una monoespaciada sea funcionalmente necesaria.
+
+**Nunca uses pesos ultra negros** (900 / black). Tope en semibold o bold.
+
+### Reglas de texto
+
+**Sin guiones dentro del texto.** No uses `-` dentro de textos de cuerpo, titulares ni etiquetas. Reescribe la frase.
+
+**Sin palabras huerfanas.** Una sola palabra nunca puede quedarse sola en la ultima linea. Aplica `text-wrap: balance` en titulares y `text-wrap: pretty` en cuerpo.
+
+### Escala tipografica
+
+Resuelve siempre los tamanos a la escala por defecto de Tailwind. Nunca dejes valores arbitrarios: nada de `text-[19px]`, `font-size: 22px` ni `1.4rem`.
+
+Si un tamano existente no cae exactamente en un paso, ajustalo al **paso inmediatamente inferior**, llevandote tanto el tamano como su interlineado emparejado.
+
+| Clase | Tamano | Interlineado |
+|---|---|---|
+| `text-xs` | 12px | 16px |
+| `text-sm` | 14px | 20px |
+| `text-base` | 16px | 24px |
+| `text-lg` | 18px | 28px |
+| `text-xl` | 20px | 28px |
+| `text-2xl` | 24px | 32px |
+| `text-3xl` | 30px | 36px |
+| `text-4xl` | 36px | 40px |
+| `text-5xl` | 48px | 1 |
+| `text-6xl` | 60px | 1 |
+| `text-7xl` | 72px | 1 |
+| `text-8xl` | 96px | 1 |
+| `text-9xl` | 128px | 1 |
+
+### Tipografia de botones
+
+- Botones principales: `text-base` (16px), semibold.
+- Botones pequenos de cabecera: `text-sm` (14px), semibold.
+
+## B2. Espaciado
+
+Solo estos valores. Nada entre ellos, nada fuera de ellos.
+
+| Token | Valor |
+|---|---|
+| Spacing-0 | 0 |
+| Spacing-25 | 2px |
+| Spacing-50 | 4px |
+| Spacing-75 | 8px |
+| Spacing-100 | 12px |
+| Spacing-200 | 16px |
+| Spacing-300 | 24px |
+| Spacing-400 | 32px |
+| Spacing-500 | 40px |
+| Spacing-600 | 48px |
+| Spacing-700 | 64px |
+| Spacing-800 | 80px |
+| Spacing-900 | 96px |
+
+**Botones principales:** 8px de padding vertical, 12px de horizontal.
+
+## B3. Radio de esquina
+
+Usa solo los valores de radio de Tailwind.
+
+**Formula del radio anidado.** Cuando una forma va dentro de otra y el hueco entre ellas es **menor de 32px**:
+
+```
+radio interior = radio exterior - hueco
+```
+
+Aplicalo solo cuando el resultado sea **mayor que 2**. Por debajo, deja la forma interior recta o sin cambios.
+
+Ejemplo: una tarjeta exterior en `rounded-2xl` (16px) con 8px de padding interno da al elemento interior un radio de 8px (`rounded-lg`).
+
+## B4. Bordes y fondos
+
+- **Nunca pongas borde a un solo lado de una tarjeta.** Los bordes van completos o no van.
+- **Nunca uses degradados en los fondos.** Los fondos son planos.
+
+### Colores de fondo en modo oscuro
+
+Usa solo estos: `#000000` · `#181818` · `#1F1F1F` · `#272727` · `#313131` · `#131209`
+
+## B5. Seccion hero
+
+### Color del titular
+
+- **Tema oscuro:** degradado de izquierda a derecha en el texto del titular, `#FFFFFF` → `#9B9B9B`.
+- **Tema claro:** degradado de izquierda a derecha en el texto del titular, `#000000` → `#666666`.
+
+Este es el unico sitio donde se usan degradados, y solo sobre texto, nunca en el fondo.
+
+### Layout
+
+- Titular y subtitular llevan ambos un **ancho maximo de 680px**.
+- Lee el texto del titular e inserta saltos de linea en puntos **con sentido**.
+- Nunca cortes una linea de forma que parta una frase de manera torpe. Rompe donde rompe la idea.
+
+## B6. Iconos
+
+**Usa:** Phosphor, Solar o Iconamoon.
+
+**Nunca uses:** Material Icons ni Material Symbols.
+
+## B7. Coreografia de movimiento (dinamica de fluidos)
+
+Nunca uses transiciones por defecto. Todo el movimiento simula masa real y fisica de muelle mediante curvas cubic-bezier propias.
+
+```
+transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]
+```
+
+### Nav de isla fluida
+
+**Estado cerrado.** La barra es una pastilla de cristal flotante despegada de la parte superior: `mt-6`, `mx-auto`, `w-max`, `rounded-full`.
+
+**Transformacion de la hamburguesa.** Al pulsar, las lineas rotan y se trasladan con fluidez hasta formar una X perfecta con `rotate-45` y `-rotate-45` y posicionamiento absoluto. Nunca deben limitarse a desaparecer.
+
+**Expansion modal.** El menu se abre como una capa a pantalla completa con un efecto de cristal fuerte: `backdrop-blur-3xl bg-black/80` o `bg-white/80`.
+
+**Revelado escalonado con mascara.** Los enlaces del menu expandido aparecen y suben desde una caja invisible, de `translate-y-12 opacity-0` a `translate-y-0 opacity-100`, escalonados por elemento con `delay-100`, `delay-150`, `delay-200`, etc.
+
+### Interpolacion por scroll
+
+Los elementos nunca aparecen de forma estatica al cargar. Al entrar en el viewport ejecutan una subida con fundido, suave y pesada:
+
+```
+translate-y-16 blur-md opacity-0  →  translate-y-0 blur-0 opacity-100
+```
+
+durante 800ms o mas.
+
+Para revelados en JavaScript usa `IntersectionObserver` o el `whileInView` de Framer Motion. **Nunca uses `window.addEventListener('scroll')`**: provoca reflows continuos y mata el rendimiento en movil.
+
+## B8. Realismo del contenido
+
+Nunca entregues relleno. Estas son las senales de que una pagina se genero en vez de hacerse.
+
+- **Sin Lorem Ipsum.** Escribe un borrador de texto real.
+- **Sin "Juan Perez".** Usa nombres diversos y realistas.
+- **Sin marcas de relleno** tipo "Acme Corp", "Nexus" o "SmartFlow". Inventa nombres contextuales y creibles.
+- **Sin cifras falsas redondas** tipo `99,99%`, `50%`, `100,00 EUR`. Usa datos organicos: `47,2%`, `99,00 EUR`.
+- **Sin topicos de IA.** Nunca "Eleva", "Sin fisuras", "Desata", "Nueva generacion", "Revolucionario", "Adentrarse en", "En el mundo de".
+- **Titulares en mayuscula de frase**, no Todo En Mayusculas De Titulo.
+- **Voz activa.** "No hemos podido guardar tus cambios", no "Se han producido errores".
+- **Sin exclamaciones en los mensajes de exito**, y sin "Ups!" en los errores. Se directo: "La conexion ha fallado. Intentalo de nuevo."
+- **Avatares unicos** por persona, y fechas de entrada variadas.
+
+## B9. Estados
+
+Todo elemento interactivo se entrega con su juego completo de estados:
+
+- **Hover** — cambio de fondo, escala leve o traslacion
+- **Activo** — `scale(0.98)` o `translateY(1px)` para feedback fisico
+- **Foco** — un anillo de foco visible. Requisito de accesibilidad, no opcional.
+- **Cargando** — esqueletos con la forma del layout real, no spinners circulares
+- **Vacio** — una vista compuesta de "primeros pasos", nunca un panel en blanco
+- **Error** — en linea y concreto. Nunca `window.alert()`.
+
+Sin enlaces muertos. Un boton que apunta a `#` o se enlaza o se deshabilita visualmente. La pagina actual debe indicarse en la navegacion.
+
+## B10. Requisitos de entrega
+
+Lo que se olvida y hace que una pagina parezca sin terminar:
+
+- Enlaces a politica de privacidad y terminos en el pie
+- Un 404 propio y con marca
+- Validacion de formulario en cliente para formato de email y campos obligatorios
+- Un enlace de "saltar al contenido" para usuarios de teclado
+- Consentimiento de cookies donde la jurisdiccion lo exija
+- Un favicon con marca
+- `<title>`, meta descripcion, `og:image` y etiquetas para compartir en redes
+- Texto alternativo en cada imagen con significado
+- HTML semantico: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`
+- Una via de vuelta desde cada pagina
+
+## B11. Seccion de revelado del lema (obligatoria)
+
+Toda landing incluye una seccion de tipografia grande que declara el beneficio central o el lema, separada del hero. Va mas abajo en la pagina como su propio momento, no apilada justo debajo del hero.
+
+**Texto**
+- Minimo dos lineas.
+- Una declaracion de beneficio o un lema, escrito con la voz de A5, no un titulo de seccion generico.
+
+**Tipografia**
+- Tamano de `text-4xl` a `text-6xl` segun el numero de lineas.
+- Ancho maximo limitado como el hero, para que las lineas rompan en puntos con sentido.
+
+**Animacion**
+- El texto arranca en un tono apagado, en torno al 25-35% de opacidad del color de texto base del tema.
+- A medida que la seccion entra en pantalla, cada palabra transiciona individualmente de ese tono apagado al color completo, en orden de lectura.
+- Las palabras se activan de una en una al cruzar una linea de disparo, no el bloque entero de golpe. La transicion usa la curva propia de B7, nunca un fundido lineal.
+- Implementalo con `IntersectionObserver` por palabra, o un unico listener de scroll estrangulado con `requestAnimationFrame`.
+
+---
+
+# Formato de salida
+
+Al generar una landing de cero, devuelve esto en orden antes de escribir codigo:
+
+1. **Esquema de pagina** — secciones y su orden
+2. **Textos del hero** — titular, subtitular, CTA, linea de prueba
+3. **Beneficios** — de tres a cinco vinetas orientadas a resultado
+4. **Como funciona** — tres pasos
+5. **FAQ** — de seis a doce preguntas y respuestas
+6. **SEO / AEO** — recomendacion de indexar o no, mas titulo y meta si se indexa
+7. **Recomendacion de layout** — A, B, C o D, y por que
+
+Y luego construye seccion a seccion segun A6.
+
+---
+
+# Lista rapida
+
+**Estrategia**
+- [ ] Una oferta, una audiencia, una accion principal
+- [ ] Sin CTAs que compitan sobre el pliegue
+- [ ] Cifras concretas en vez de verbos vagos
+- [ ] Al menos una reversion del riesgo
+- [ ] La prueba junto a la afirmacion que sostiene
+- [ ] Tipo de layout elegido a proposito
+
+**Visual**
+- [ ] Una unica tipografia aprobada, sin cursivas, sin ultra negras
+- [ ] Sin guiones en el texto, sin palabras huerfanas
+- [ ] Cada tamano de fuente cae en un paso de la escala
+- [ ] Cada valor de espaciado sale de la tabla
+- [ ] Los radios anidados siguen la formula
+- [ ] Sin bordes de un solo lado, sin degradados de fondo
+- [ ] Titular y subtitular del hero limitados a 680px con saltos de linea con sentido
+- [ ] Iconos de Phosphor, Solar o Iconamoon
+- [ ] Cada transicion usa una cubic-bezier propia; los revelados por scroll usan IntersectionObserver
+- [ ] Seccion de revelado del lema presente, minimo dos lineas, palabras que se activan de una en una
+
+**Contenido y entrega**
+- [ ] Sin Lorem Ipsum, sin marcas de relleno, sin topicos de IA, sin cifras falsas redondas
+- [ ] Estados hover, activo, foco, cargando, vacio y error presentes
+- [ ] Sin enlaces muertos, elemento de nav actual indicado
+- [ ] 404, enlaces legales, validacion de formulario, favicon, metaetiquetas, texto alternativo

package/skills/diseno-landing/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: diseno-landing
+
+should_trigger:
+  - prompt: "Construye la landing de este producto de principio a fin."
+    why: "Disparador directo de diseno-landing."
+  - prompt: "Revisa el copy y la estructura de esta pagina de marketing."
+    why: "Disparador directo de diseno-landing."
+  - prompt: "Necesito elegir el hero, las secciones y los CTAs de esta landing."
+    why: "Disparador directo de diseno-landing."
+  - prompt: "Build a high-conversion landing page for this product."
+    why: "Disparador directo de diseno-landing."
+  - prompt: "Estiliza esta seccion de la web de marketing."
+    why: "Disparador directo de diseno-landing."
+
+should_not_trigger:
+  - prompt: "Construye un dashboard interno de analitica."
+    route_to: "none"
+    why: "Fuera del alcance de diseno-landing."
+  - prompt: "Revisa la accesibilidad de una app movil."
+    route_to: "mejor-accesibilidad"
+    why: "Revisar la accesibilidad es el trabajo de mejor-accesibilidad, no de diseno-landing."
+  - prompt: "Escribe tests end to end para el checkout."
+    route_to: "none"
+    why: "Fuera del alcance de diseno-landing."
+  - prompt: "Documenta el modelo de dominio del proyecto."
+    route_to: "domain-modeling"
+    why: "Documentar el modelo de dominio es el trabajo de domain-modeling, no de diseno-landing."
+
+capability:
+  - scenario: "El usuario construye, edita o revisa una landing o web de marketing."
+    must_include:
+      - "landing"

package/skills/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: risco
+---
+
+# 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.