coding-os 0.3.2__py3-none-any.whl

templates/django/scaffold/docs/engineering/backend-rules.md

@@ -0,0 +1,133 @@
+<!-- domain:ALL | layer:policy | ssot:true | updated:2026-03-16 -->
+# Backend Engineering Rules
+
+Purpose: Canonical backend implementation policy for Django, DRF, Celery, PostgreSQL, and Redis work.
+Read when: The task changes backend models, services, serializers, endpoints, auth, payments, downloads, or backend ops behavior.
+Skip when: The task is frontend-only, docs-only, or pure content work.
+Read next: `../architecture/00-index.md` and the matching domain architecture doc.
+
+> Nav: [Docs Index](../00-index.md) | [CodeStyle](../../CodeStyle.md) | [Architecture](../architecture/00-index.md)
+
+## Core Rules
+
+- Schema changes happen through Django migrations only.
+- Read operations use selectors in `apps/*/selectors/`. Never query ORM directly in views.
+- Write operations use services in `apps/*/services/`. Views delegate, never mutate.
+- Views are thin: parse request, call selector/service, return serialized response.
+- Use integer cents for all monetary values.
+- Payment and fulfillment flows must be idempotent.
+- Long-running or retryable work goes through Celery tasks.
+
+## Migration Rules
+
+- Every migration must be reversible (`RunPython` requires `reverse_code`; `RunSQL` requires `reverse_sql`).
+- Separate schema migrations from data migrations.
+- Review generated SQL before production: `python manage.py sqlmigrate <app> <number>`.
+- Test rollback locally: `migrate <app> <previous>` then re-apply.
+- Migration-producing changes: agent creates files, **user runs `make migrate`**.
+- **Add field with default:** `AddField(null=True)` → `RunPython(backfill)` → `AlterField(null=False)`.
+- **Rename field:** `AddField(new_name)` → `RunPython(copy_data)` → `RemoveField(old_name)`.
+- **Remove field:** stop reading/writing in code → deploy → `RemoveField` in next deploy.
+- For large tables (>1M rows), test migration timing on staging before production.
+- `django-pg-zero-downtime-migrations` prevents table locks; do not add manual `LOCK TABLE`.
+- Never combine schema and data changes in the same migration file.
+
+## Validation and Contracts
+
+- Validate request payloads with DRF serializers.
+- Validate cross-entity business rules in services.
+- Use explicit error codes and the standard DRF exception wrapper from the common app.
+- Keep API routes under `/api/v1/` unless versioning policy says otherwise.
+
+## Security Baseline
+
+- Use Django permissions and DRF permission classes; keep access-control language aligned with the current backend stack.
+- Resolve client IPs through `django-ipware`, not `REMOTE_ADDR`.
+- Keep JWT/session cookies `httpOnly`, `secure` in production, and `SameSite=Strict`.
+- Validate uploaded files by content, not extension alone.
+- Never expose internal stack traces or provider secrets in API responses.
+
+## Error Handling Policy
+
+- **Fail-closed default:** if verification/validation cannot complete, reject the operation. Never log-and-allow.
+- Use typed exceptions from `apps/<domain>/exceptions.py`, inheriting `rest_framework.exceptions.APIException`.
+- Never raise bare `ValueError` or `Exception` from service layer code.
+- Never expose `str(exc)`, database column names, or third-party service details in API responses.
+- Error responses must match the standard envelope in `docs/api-contracts/error-format.md`.
+- The custom exception handler in `apps/common/exception_handler.py` formats all DRF exceptions automatically — use typed exceptions and it works.
+- **Never manually build error envelopes** — do not write `return Response({"error_code": ..., "message": ...})`. Raise a typed exception instead; the handler produces the envelope.
+- Every `except` block must either re-raise, raise a typed exception, or reject the operation. No silent `pass` or `return None`.
+- Log internal error details at WARNING/ERROR level for debugging — generic message to client.
+
+## Observability and Operations
+
+- Log security-relevant events such as login failures, payment mutations, permission changes, and download denials.
+- Capture 5xx failures through the analytics/error pipeline defined in architecture docs.
+- Record architectural tradeoffs in the task file and `changes.log`, not in shadow logging files outside the task system.
+- Use `.env` plus environment-specific Django settings modules for backend configuration.
+
+## 8) System Health Diagnostics
+
+The `systemhealth` Django management command validates the entire backend:
+
+```bash
+python manage.py systemhealth              # Full report (5 categories)
+python manage.py systemhealth --json       # JSON output for CI
+python manage.py systemhealth --category=security  # Single category
+```
+
+**Categories checked:**
+
+- ENV VARIABLES: Stripe, Email, Turnstile, Storage, OAuth, PostHog
+- CONNECTIONS: PostgreSQL (with latency), Redis (with latency)
+- QUEUE & SCHEDULER: Celery broker, workers, beat, queue depth, failed tasks
+- SECURITY: DEBUG, SECRET_KEY, HTTPS, CORS, CSRF, cookies
+- MIGRATIONS: pending migration detection
+
+**Makefile targets:**
+
+- `make diagnose-backend` — run systemhealth in Docker
+- `make diagnose-frontend` — validate frontend env vars + API reachability
+- `make diagnose` — both combined
+- `make ci-gate` — full pipeline including diagnostics
+
+**When to run diagnostics:**
+
+- After cloning the repo (verify env setup)
+- During task verification (ensure services are healthy)
+- Before deploy (part of `make ci-gate`)
+- When debugging connection issues
+
+## Required Security Review
+
+Perform an explicit security review when the task touches: auth/sessions, payments/webhooks, file upload/download, HTML rendering/UGC, admin/privileged actions, redirects, CAPTCHA, rate limiting, or permission boundaries.
+
+## Comments
+
+- Comment **why**, not **what**. If the code is self-evident, no comment is needed.
+- Use `Ref:` to trace decisions back to architecture docs (e.g. `# Ref: architecture/04a-auth-security.md`).
+- Use `TODO: TASK-###` with a task number. Bare TODOs without a task reference are not allowed.
+- Comment non-obvious ordering constraints, security rationale, and business rules.
+- Do not add docstrings that restate the function name or arguments.
+
+## Testing Standards
+
+- **Infrastructure tests are mandatory**: `tests/test_infrastructure.py` must include `call_command("check", "--fail-level", "ERROR")` (catches admin field errors before they crash `runserver`) and `call_command("makemigrations", "--check", "--dry-run")` (catches missing migrations).
+- For seeded data (permissions, feature flags, site settings): always use `get_or_create()` in tests, never `create()`, to avoid IntegrityError conflicts with data migrations.
+- Every app must include: `tests/conftest.py` (shared fixtures), `tests/factories.py` (factory_boy factories), `tests/test_selectors.py`, `tests/test_api.py` (integration), `tests/test_contract.py` (schema assertions).
+- Use `factory_boy` for test data. Avoid raw `Model.objects.create()` except in legacy fixtures.
+- Factories live in `apps/<app>/tests/factories.py`; use `factory.Faker` for realistic values.
+- Avoid hardcoded magic values — use factories with explicit overrides only for the fields under test.
+- Verify N+1 prevention with `django_assert_num_queries` for selectors using `select_related`/`prefetch_related`; document expected query count in a comment.
+- Define expected field sets as module-level constants; contract tests verify API response keys match exactly.
+- Update contract field sets whenever a serializer changes.
+- Target: 80%+ line coverage per app. Measure with `pytest --cov=apps/<app>`.
+
+## Edge Case Testing
+
+- Test null/None/empty inputs for every public service function and selector.
+- Test boundary values (0, max allowed, max+1, negative for unsigned fields).
+- Test error paths: what happens when the DB is down, Redis unavailable, Stripe returns 500?
+- Test concurrent mutations for payment/order flows (idempotency verification).
+- Never write a test that asserts "does not crash" — assert the correct behavior (correct error type, correct status code, correct state).
+- Name edge-case tests descriptively: `test_create_order_when_cart_empty_returns_400`.

templates/django/scaffold/docs/engineering/glossary.md

@@ -0,0 +1,51 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:2026-03-13 -->
+# Project Glossary
+
+Purpose: Canonical project terminology — use when a term is ambiguous in context.
+Read when: A term in architecture, playbooks, or PRD is unclear or ambiguous.
+Skip when: Terminology is obvious from context.
+Read next: The specific architecture domain or playbook clarifying the term.
+
+
+> Purpose: Domain language dictionary. Use these terms consistently across all docs.
+> Nav: [Docs Index](../00-index.md) | [Code Style](../../CodeStyle.md)
+
+## Business Domain
+
+- **Entitlement** → a user's right to download a purchased product. Created after successful payment. Stored in `downloads.Entitlement` model.
+- **Fulfillment** → the process of creating Order, OrderItems, and Entitlements after payment succeeds. Triggered by webhook, executed in `OrderService.fulfill_order()`.
+- **Guest checkout** → purchase without an account. Uses email for order association. Guest can later register and link orders via `AccountLinkingService`.
+- **Price snapshot** → the `price_at_purchase` field on OrderItem. Preserves the price at time of purchase, independent of future price changes.
+- **Digital product** → a downloadable file (template, design, script, tool). No physical shipping.
+
+## Technical Domain
+
+- **BaseModel** → abstract Django model providing `id` (UUID), `created_at`, `updated_at`. All models inherit from it.
+- **Bounded context** → a DDD concept. Each Django app (`accounts`, `catalog`, `commerce`, etc.) is a bounded context with its own models and services.
+- **PaymentPort** → abstract interface (`apps/payments/ports.py`) defining `create_payment_intent()`, `verify_webhook()`, `refund()`. Adapters implement it for each provider.
+- **Service layer** → business logic lives in `apps/*/services/`, never in views or serializers. Services are the only place that orchestrates multi-model operations.
+- **Selector (query layer)** → pattern for database queries. Complex queries go in `apps/*/selectors/`, not in views or services directly.
+
+## Infrastructure
+
+- **ISR (Incremental Static Regeneration)** → Next.js feature. Pages are statically generated and revalidated at intervals (30 min for blog, 30 min for products).
+- **Celery task** → async background job. Used for: email sending, analytics events, file processing. Never for synchronous request-response.
+- **Health check** → `GET /ht/` endpoint. Checks DB, Redis, Celery, S3. Used by Docker, Nginx, and monitoring.
+
+## Payment
+
+- **PaymentIntent** → Stripe object representing a payment attempt. Created by backend, confirmed by frontend via Payment Element.
+- **client_secret** → Stripe token passed to frontend to render Payment Element. Never store or log.
+- **Idempotency** → webhook handler checks `StripeEvent.stripe_id` before processing. Duplicate webhooks are safely ignored.
+- **SAQ-A** → PCI compliance level. Applies when card data never touches our servers (Stripe Payment Element handles it).
+
+## Abbreviations
+
+- DRF → Django REST Framework
+- DDD → Domain-Driven Design
+- SSOT → Single Source of Truth
+- UFS → Universal File Standard (our doc header format)
+- REF → Reference shortcode (see `foundation-map.md`)
+- PRD → Product Requirements Document
+- MVP → Minimum Viable Product (V1 launch scope)
+- LCP → Largest Contentful Paint (Core Web Vital)

templates/django/scaffold/docs/engineering/logging-standards.md

@@ -0,0 +1,107 @@
+<!-- domain:ALL | layer:policy | ssot:true | updated:2026-03-14 -->
+# Logging Standards
+
+Purpose: Structured logging format, log levels, and PII exclusion rules for all backend services.
+Read when: Adding logging to any backend code or configuring log infrastructure.
+Skip when: Frontend-only changes.
+Read next: `backend-rules.md` for general backend engineering rules.
+
+> Nav: [Docs Index](../00-index.md) | [Code Style](../../CodeStyle.md)
+
+---
+
+## Format
+
+- **Production**: JSON via `python-json-logger` (already configured in `production.py`)
+- **Development**: Standard text format for readability
+- **Fields per log entry**: timestamp, level, logger_name, message, request_id (if available), user_id (if authenticated)
+
+---
+
+## Log Levels by Event Type
+
+| Level | When to Use | Examples |
+|:------|:------------|:--------|
+| DEBUG | Development-only detailed traces | SQL queries, template rendering, cache hits |
+| INFO | Normal business operations | User registered, order created, email sent, download completed |
+| WARNING | Recoverable issues that need attention | Rate limit hit, soft email bounce, deprecated API usage |
+| ERROR | Failed operations that need investigation | Payment failed, webhook processing error, file validation failure |
+| CRITICAL | System-level failures | Database connection lost, Redis unreachable, Celery worker crash |
+
+---
+
+## Error Logging Patterns
+
+- Log the full exception context (`exc_info=True`) at ERROR level for unexpected failures.
+- Log expected business errors (validation, permission denied) at WARNING level without stack trace.
+- **No PII in any `logger.*` call** — never pass `user.email`, full name, phone, or raw IP to any log level. Use `user.id` (UUID) only. For debugging that requires email context, use masked form (`j***@example.com`).
+- Include request context (endpoint, method, user UUID) in error logs for traceability.
+
+---
+
+## Security Event Logging
+
+These events MUST be logged at INFO or WARNING level for audit:
+
+- Login success/failure (WARNING for failures)
+- Password reset request
+- Account creation
+- Permission denied (403)
+- Rate limit exceeded (429)
+- CAPTCHA validation failure
+- Download access denied
+- Admin actions (create/update/delete)
+
+---
+
+## PII Exclusion Rules (CRITICAL)
+
+**NEVER log:**
+
+- Passwords (raw or hashed)
+- Full credit card numbers (Stripe handles payment — we never see them)
+- JWT tokens or refresh tokens
+- API keys or secrets
+- Full email addresses in ERROR/CRITICAL logs (use `j***@example.com` masking)
+- IP addresses in logs retained > 90 days (anonymize for compliance)
+
+**OK to log:**
+
+- User IDs (UUIDs)
+- Order IDs
+- Product IDs
+- Event types
+- Status codes
+- Masked emails in INFO logs (first char + *** + domain)
+
+---
+
+## Django LOGGING Configuration
+
+```python
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "json": {
+            "()": "pythonjsonlogger.json.JsonFormatter",
+            "format": "%(asctime)s %(levelname)s %(name)s %(message)s",
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "json",
+        },
+    },
+    "loggers": {
+        "apps": {"level": "INFO", "handlers": ["console"], "propagate": False},
+        "django.security": {"level": "WARNING", "handlers": ["console"], "propagate": False},
+        "celery": {"level": "INFO", "handlers": ["console"], "propagate": False},
+    },
+    "root": {"level": "WARNING", "handlers": ["console"]},
+}
+```
+
+---
+[Docs Index](../00-index.md)

templates/django/scaffold/docs/engineering/naming-conventions.md

@@ -0,0 +1,68 @@
+<!-- domain:ALL | layer:policy | ssot:true | updated:2026-03-13 -->
+# Naming Conventions & Project Structure
+
+Purpose: Canonical naming and placement policy for the actual ExampleApp monorepo.
+Read when: Deciding where files belong, how they should be named, or how route/API names should look.
+Skip when: The task already targets an existing file and no placement/naming decision is needed.
+Read next: `../architecture/03-project-structure.md` or the relevant engineering rules file.
+
+> Nav: [Docs Index](../00-index.md) | [CodeStyle](../../CodeStyle.md) | [Architecture](../architecture/00-index.md)
+
+## Monorepo Anchors
+
+- `src/frontend/` → Next.js application
+- `src/backend/` → Django application
+- `src/shared/` → shared contracts/constants
+- `docs/` → SSOT docs
+- `infrastructure/` → deploy, nginx, and operational scripts
+
+## Frontend Placement
+
+- Routes live in `src/frontend/app/`
+- Shared UI primitives live in `src/frontend/components/ui/`
+- Shared page sections live in `src/frontend/components/sections/`
+- Feature-specific composite components live in domain folders such as `src/frontend/components/admin/`
+- Message files live in `src/frontend/messages/`
+- Route metadata and AI-discovery files follow Next.js conventions or `src/frontend/public/` where appropriate
+
+## Backend Placement
+
+- Django apps live in `src/backend/apps/`
+- App-local business logic lives in `src/backend/apps/<domain>/services/`
+- App-local tests live in `src/backend/apps/<domain>/tests/`
+- Cross-app integration tests live in `src/backend/tests/`
+- Settings live in `src/backend/config/settings/`
+
+## Naming Rules
+
+- Directories and non-class files → `kebab-case` for frontend, `snake_case` for backend Python modules
+- React components, serializers, models, viewsets → `PascalCase`
+- Functions and variables → `camelCase` in TypeScript, `snake_case` in Python
+- Booleans → `is*`, `has*`, `can*`
+- Django apps → `snake_case` singular names such as `accounts`, `catalog`, `admin_dashboard`
+- URL paths → `kebab-case`
+- API base path → `/api/v1/`
+- Exception classes → `DomainActionError` pattern (e.g., `CartEmptyError`, `PaymentFailedError`, `EntitlementRevokedError`)
+- Error codes → SCREAMING_SNAKE_CASE matching `docs/api-contracts/error-format.md` (e.g., `CART_EMPTY`, `PAYMENT_FAILED`)
+- Validation functions → `validate_*` prefix (e.g., `validate_upload`, `validate_coupon_code`)
+- Edge case tests → `test_<action>_when_<condition>_<expected>` (e.g., `test_create_order_when_cart_empty_returns_400`)
+
+## Route Naming
+
+- Frontend admin application routes use `/admin/*`
+- Django admin stays at `/back-office/`
+- Public product routes use slugs, not IDs, where the route contract already defines slugs
+
+## Task and Doc Naming
+
+- Task files → `TASK-###-slug.md`
+- ADRs → `ADR-###-slug.md`
+- Index files → `00-index.md`
+- Historical governance docs → `YYYY-MM-topic.md`
+
+## Import Order
+
+1. React / Next.js
+2. Third-party packages
+3. Internal modules
+4. Types

templates/django/scaffold/docs/engineering/secrets-rotation-runbook.md

@@ -0,0 +1,142 @@
+<!-- domain:INFRA | layer:reference | ssot:true | updated:2026-03-29 -->
+# Secrets Rotation Runbook
+
+Purpose: Step-by-step procedures for rotating all production secrets with zero downtime.
+Read when: A secret has been exposed, a rotation schedule triggers, or onboarding a new team member to ops procedures.
+Skip when: No secrets need rotation and no exposure has occurred.
+Read next: `../architecture/04a-auth-security.md` for auth architecture details.
+
+> Nav: [Docs Index](../00-index.md) | [Backend Rules](./backend-rules.md)
+
+---
+
+## Django SECRET_KEY
+
+**Automated rotation available.** Django 4.1+ supports `SECRET_KEY_FALLBACKS` for zero-downtime key rotation.
+
+### Automated (recommended)
+
+```bash
+make rotate-secret-key
+# or with custom .env path:
+bash infrastructure/scripts/rotate-secrets.sh --env-file src/backend/.env
+```
+
+The script:
+1. Generates a new 50-character random key
+2. Moves the current key to `DJANGO_SECRET_KEY_FALLBACKS`
+3. Sets the new key as `DJANGO_SECRET_KEY`
+4. Creates a timestamped backup of `.env`
+
+### Post-rotation
+
+1. Deploy the application (existing sessions remain valid via fallback)
+2. After 7+ days with no session errors: remove the old key from `DJANGO_SECRET_KEY_FALLBACKS`
+3. Monitor Django logs for `Signature verification failed` warnings
+
+### Manual (if script unavailable)
+
+1. Generate: `python3 -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"`
+2. Set `DJANGO_SECRET_KEY=<new_key>` in `.env`
+3. Set `DJANGO_SECRET_KEY_FALLBACKS=<old_key>` in `.env` (comma-separated if multiple)
+4. Deploy
+5. After 7 days, remove old key from `DJANGO_SECRET_KEY_FALLBACKS`
+
+---
+
+## Stripe API Keys
+
+Stripe keys support a 24-hour grace period where both old and new keys work.
+
+### Steps
+
+1. Go to Stripe Dashboard -> Developers -> API keys
+2. Click "Roll key" on the secret key (`sk_live_...`)
+3. Stripe provides the new key immediately; old key works for 24 hours
+4. Validate the new key:
+   ```bash
+   make rotate-secret WHICH=stripe
+   ```
+5. Update `STRIPE_LIVE_SECRET_KEY` (or `STRIPE_TEST_SECRET_KEY`) in `.env`
+6. Deploy within 24 hours
+7. Verify webhook signatures still work (webhook signing secret is separate)
+
+### Webhook signing secret
+
+1. Go to Stripe Dashboard -> Developers -> Webhooks -> your endpoint
+2. Click "Reveal" on signing secret, then "Roll secret"
+3. Update `STRIPE_WEBHOOK_SECRET` in `.env`
+4. Deploy immediately (no grace period for webhook secrets)
+
+---
+
+## Postmark API Token
+
+Postmark invalidates the old token immediately on regeneration. Schedule maintenance window.
+
+### Steps
+
+1. Go to Postmark -> Servers -> your server -> API Tokens
+2. Click "Regenerate" (old token invalidated instantly)
+3. Update `POSTMARK_SERVER_TOKEN` in `.env`
+4. Deploy immediately
+5. Verify email delivery by checking Postmark activity log
+
+### Risk mitigation
+
+- Schedule during low-traffic hours
+- Have the new token ready to paste before regenerating
+- Deploy within 2-3 minutes of regeneration
+
+---
+
+## Sentry DSN
+
+Sentry DSN rotation is rarely needed. The DSN contains only the project ID and public key (no secret material). Rotate only if the DSN was accidentally exposed in client-side code alongside private data.
+
+### Steps
+
+1. Go to Sentry -> Settings -> Projects -> your project -> Client Keys
+2. Click "Generate new key" (creates a new DSN; old remains active)
+3. Update `SENTRY_DSN` in `.env`
+4. Deploy
+5. After confirming new DSN works: disable the old key in Sentry
+
+---
+
+## PostHog API Key
+
+PostHog project API keys are public by design (used in client-side analytics). Rotation is only needed if the project itself needs to change.
+
+### Steps
+
+1. Go to PostHog -> Settings -> Project -> API Key
+2. Regenerate the project API key
+3. Update `NEXT_PUBLIC_POSTHOG_KEY` in frontend `.env`
+4. Rebuild and deploy the frontend
+5. Old events may still arrive on the old key until all clients refresh
+
+---
+
+## Cloudflare Turnstile
+
+### Steps
+
+1. Go to Cloudflare Dashboard -> Turnstile -> your site
+2. Click "Rotate secret key" (both keys valid for 24 hours)
+3. Update `TURNSTILE_SECRET_KEY` in backend `.env`
+4. Deploy backend within 24 hours
+5. Site key (`NEXT_PUBLIC_TURNSTILE_SITE_KEY`) does not change during rotation
+
+---
+
+## Rotation Schedule
+
+Recommended rotation cadence:
+
+- **Django SECRET_KEY**: every 90 days or on suspected exposure
+- **Stripe keys**: every 90 days or on suspected exposure
+- **Postmark token**: only on suspected exposure (no grace period makes routine rotation risky)
+- **Sentry DSN**: only on suspected exposure
+- **PostHog key**: only if project change needed
+- **Turnstile secret**: every 90 days or on suspected exposure

templates/django/scaffold/docs/playbooks/backend-api.md

@@ -0,0 +1,119 @@
+<!-- domain:ALL | layer:playbook | ssot:true | updated:2026-03-17 -->
+# Backend API Playbook
+
+Purpose: Execute Django/DRF work using architecture, schema, and service-layer SSOT without scanning unrelated docs.
+Read when: The task touches backend apps, models, services, serializers, auth, payments, downloads, or admin APIs.
+Skip when: The task is frontend-only, docs-only, or pure content work.
+Read next: `docs/architecture/00-index.md`, then the relevant domain architecture doc.
+
+> Nav: [Docs Index](../00-index.md) | [Architecture Index](../architecture/00-index.md)
+
+## Task-to-File Mapping
+
+Use this to select the exact architecture doc(s). If a task spans multiple domains, read the architecture doc for **each** domain — do not limit to one.
+
+- Auth / login / registration / JWT → `architecture/04a-auth-security.md`
+- Rate limiting / throttling / abuse protection → `architecture/04a-auth-security.md` + `architecture/04b-web-security.md`
+- CSP / CORS / XSS / web security → `architecture/04b-web-security.md`
+- File downloads / signed URLs → `architecture/04c-download-security.md`
+- Payment / Stripe / checkout flow → `architecture/08-payment-architecture.md`
+- Email / notifications / MJML → `architecture/07-email-notifications.md`
+- Analytics / PostHog / events → `architecture/09-analytics-posthog.md`
+- Blog / i18n / content backend → `architecture/10-blog-content-i18n.md`
+- Testing / pytest / factories → `architecture/05-testing-strategy.md`
+- Docker / infra / deployment → `architecture/06a-infrastructure.md` + `06b-docker-services.md`
+- Identity / RBAC / roles / permissions → `PRD/12-schema-erd.md`
+- New model / schema change → `architecture/03a-monorepo-layout.md` + `PRD/09-data-model-apis.md`
+- Tech stack / dependency question → `architecture/02a-core-dependencies.md`
+
+## Read Selection Guide
+
+> Complete lookup: AGENTS.md § Dimension Type Registry (auto-loaded). This section adds domain-specific detail for Orient phase.
+
+The Classify phase generates a Read List. Use this mapping to select files — do NOT read all entries. Read only what matches your task's dimensions and unknowns.
+
+### By Dimension Type
+
+| If task involves... | Read these files |
+| --- | --- |
+| Schema / model changes | `PRD/12-schema-erd.md` + `PRD/12c-indexing-strategy.md` |
+| Business logic | `PRD/08-functional-requirements.md` |
+| API contract shape | `api-contracts/{domain}.md` + `PRD/09-data-model-apis.md` |
+| Auth / security | `architecture/04a-auth-security.md` + `security-review.md` |
+| Payments | `architecture/08-payment-architecture.md` |
+| Scheduled tasks / expiry | `architecture/06c-scheduled-tasks.md` |
+| Frontend page context | `pages-content-spec/{page}.md` |
+| Error handling patterns | `engineering/backend-rules.md` § Error Handling Policy |
+| Testing patterns | `engineering/backend-rules.md` § Edge Case Testing |
+
+### Always Read (for any backend task)
+
+1. The exact architecture doc(s) from the Task-to-File Mapping above
+2. `docs/engineering/backend-rules.md`
+
+### Read Only If Relevant
+
+- `docs/prd/12-schema-erd.md` — only if models/columns are touched
+- `docs/prd/08-functional-requirements.md` — only if business logic involved
+- `docs/playbooks/security-review.md` — only if the change is security-sensitive
+- `docs/pages-content-spec/{page}.md` — only if the API serves a specific frontend page
+
+## Execution Rules
+
+- Business logic lives in `src/backend/apps/*/services/`.
+- Schema names come from `PRD/12-schema-erd.md`; never invent model or field names.
+- Monetary values stay in integer cents.
+- Webhooks and payment truth come from provider webhooks, not client callbacks.
+- Use `/api/v1/` routes and keep API changes version-safe.
+- When existing code is found (Orient phase — repo search step), read existing serializers, tests, and factories in the same app to identify spec-vs-implementation gaps before writing new code.
+- If task involves error handling or validation: also read `backend-rules.md` § Error Handling Policy
+- If task involves testing: also read `backend-rules.md` § Edge Case Testing
+
+## Verification
+
+**Required** (enforced by `enforce-verify.sh` domain-aware hook):
+1. `make lint-backend` — ruff + mypy
+2. `make test-backend` — pytest (1178+ tests)
+3. Both must show PASS in `.claude/.last-verify.json` within 30 min
+
+**Additional**: if migrations created, agent prepares files but user runs `make migrate`. See AGENTS.md § Verification Matrix for full domain mapping.
+
+## MVP Task Sequencing
+
+Backend tasks are grouped by dependency order. Complete earlier groups before later ones:
+
+1. **Foundation** (TASK-043, 044) → project structure, base models, settings
+2. **Identity & Auth** (TASK-045–048) → user model, JWT, OAuth, email verification
+3. **Catalog & Products** (TASK-049–051) → product model, categories, search
+4. **Commerce & Cart** (TASK-052–054) → cart, checkout flow, order model
+5. **Payments & Fulfillment** (TASK-055–057) → Stripe integration, webhooks, entitlements
+6. **Downloads & Delivery** (TASK-058–059) → signed URLs, download tracking
+7. **Content & Blog** (TASK-060–061) → blog backend, content API
+8. **Notifications** (TASK-062–063) → email templates, notification service
+9. **Reviews & Engagement** (TASK-064–065) → review system, favorites
+10. **Analytics** (TASK-066–067) → PostHog events, tracking
+11. **Admin Dashboard** (TASK-068–069) → admin APIs, dashboard data
+12. **SEO & Technical** (TASK-070–071) → backend-owned sitemap, structured data
+13. **Security & QA** (TASK-072–074) → security hardening, penetration testing
+14. **Deployment** (TASK-075–077) → staging, production, monitoring
+
+## Migration Workflow
+
+Agent creates migration files; user runs `make migrate`. For safety rules, multi-step patterns, and rollback procedures, see `docs/engineering/backend-rules.md` § Migration Rules.
+
+## SSOT Transition — Docs to Code
+
+Design docs are read-once blueprints. After implementation, code is the living truth:
+
+- Table schema → `models.py` (not `docs/prd/12a`, `12b`)
+- Indexes → `models.py Meta.indexes` (not `docs/prd/12c`)
+- API endpoints → `drf-spectacular` at `/api/v1/schema/` (not `docs/api-contracts/`)
+- Business logic → `services.py` (not `docs/architecture/`)
+
+Do NOT update design docs after implementation — code is SSOT. Live API docs: `/api/v1/docs/` (Swagger UI).
+
+## Stop and Escalate If
+
+- architecture docs conflict with schema docs
+- the endpoint contract is missing from PRD/architecture — **do not infer endpoints from page specs alone; log a blocker via `cos task-move TASK-NNN --to blocked`**
+- the change requires undocumented security behavior or provider semantics

templates/django/scaffold/src/backend/config/settings.py

@@ -0,0 +1,31 @@
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-insecure-change-me")
+DEBUG = os.environ.get("DJANGO_DEBUG", "true").lower() == "true"
+ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "*").split(",")
+
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "rest_framework",
+]
+
+MIDDLEWARE = [
+    "django.middleware.common.CommonMiddleware",
+]
+
+ROOT_URLCONF = "config.urls"
+WSGI_APPLICATION = "config.wsgi.application"
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": BASE_DIR / "db.sqlite3",
+    }
+}
+
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+USE_TZ = True

templates/django/scaffold/src/backend/config/urls.py

@@ -0,0 +1,11 @@
+from django.http import JsonResponse
+from django.urls import path
+
+
+def health(_request):
+    return JsonResponse({"status": "ok"})
+
+
+urlpatterns = [
+    path("health/", health, name="health"),
+]