theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/angular-default.md

@@ -0,0 +1,181 @@
+# Angular Default Scaffold Playbook
+
+Use this playbook when the prompt explicitly wants Angular rather than a category-open frontend choice.
+
+## Goal
+
+Create a simple Angular baseline that:
+
+- uses the official Angular CLI bootstrap path
+- pins the working defaults exactly
+- keeps `docker compose up --build` as the runtime contract
+- keeps `./run_tests.sh` as the broad containerized verification path
+- includes minimal real Angular tests without pretending the app is product-complete
+
+Verified lab: `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/angular-baseline`
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+
+## Official bootstrap path
+
+Angular docs define the local project bootstrap as `ng new [project-name] [options]`.
+The experimentally verified non-interactive baseline here used:
+
+```bash
+npx -y @angular/cli@21.2.7 new angular-baseline --defaults --package-manager npm --skip-git --routing false --style css --ssr false --test-runner vitest
+```
+
+Why this shape:
+
+- official CLI path
+- no SSR, routing, or extra product surface at scaffold time
+- standalone app defaults preserved
+- Angular 21 docs show `vitest` as the default test runner for new projects
+
+## Evidence basis for the defaults
+
+- Angular CLI docs: `ng new` is the official command to create a workspace and initial application.
+- Angular CLI docs: `test-runner` defaults to `vitest` for new projects.
+- Angular version compatibility docs: Angular 21 supports Node `^20.19.0 || ^22.12.0 || ^24.0.0`.
+
+## Safe pinned defaults used in the verified lab
+
+- bootstrap generator: `@angular/cli@21.2.7`
+- Docker base image: `node:24.13.0-alpine3.22`
+- Angular packages: `21.2.8`
+- `@angular/build`: `21.2.7`
+- `@angular/compiler-cli`: `21.2.8`
+- `typescript`: `5.9.3`
+- `vitest`: `4.1.4`
+- `rxjs`: `7.8.2`
+- `tslib`: `2.8.1`
+- `jsdom`: `28.1.0`
+
+Pin exact versions in `package.json` after generation so reruns are deterministic.
+
+## Docker / Compose pattern
+
+Recommended light baseline pattern:
+
+1. **single pinned Node base image** for both runtime and verification
+2. **development target** runs `ng serve --host 0.0.0.0 --port 4200`
+3. **verify target** runs `npm run verify`
+4. **Compose services**
+   - `web` for `docker compose up --build`
+   - `test` behind a `test` profile for disposable verification
+5. **port strategy**
+   - expose only the Angular app port
+   - prefer `127.0.0.1::4200` so local worktrees do not collide
+6. **health strategy**
+   - use a localhost HTTP healthcheck against `/`
+
+This keeps the baseline convergent without adding SSR, nginx, or browser automation.
+
+## Testing baseline
+
+Minimum real testing floor for this playbook:
+
+- Angular unit tests generated from the official starter
+- at least one rendered-content assertion
+- at least one real user interaction assertion (for example, toggling a panel)
+- `npm run verify` that runs tests and production build
+- `./run_tests.sh` that smoke-checks the live app and runs the verify container
+
+Suggested scripts:
+
+- `npm run test:ci`
+- `npm run build`
+- `npm run verify`
+- `./run_tests.sh`
+
+## README floor
+
+`README.md` must already state:
+
+- that this is a baseline scaffold only
+- exact official bootstrap command used
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- exact pinned versions that materially matter
+- what is intentionally included now
+- what is intentionally deferred
+- no `.env` / no secrets policy
+
+## Exact commands actually run in the verified lab
+
+```bash
+npx -y @angular/cli@21.2.7 new angular-baseline --defaults --package-manager npm --skip-git --routing false --style css --ssr false --test-runner vitest
+npm install
+npm run verify
+docker compose up -d --build
+docker compose ps
+docker compose port web 4200
+curl -fsS http://127.0.0.1:<mapped-port>
+docker compose down --remove-orphans
+./run_tests.sh
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/angular-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 240
+    while time.time() < deadline:
+        try:
+            output = subprocess.check_output(["docker", "compose", "port", "web", "4200"], cwd=cwd, text=True).strip()
+            if output:
+                port = output.rsplit(":", 1)[1]
+                with urlopen(f"http://127.0.0.1:{port}", timeout=2) as response:
+                    if response.status == 200:
+                        print(f"Angular baseline reached while docker compose up --build was active at http://127.0.0.1:{port}")
+                        break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"Angular baseline never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+## Observed results from the verified lab
+
+- `npm run verify`: passed
+- `docker compose up --build`: reached a live Angular page before controlled shutdown
+- `curl -fsS http://127.0.0.1:<mapped-port>`: returned the HTML shell containing `<title>Angular Baseline Lab</title>`
+- `./run_tests.sh`: passed and printed `Smoke check passed at http://127.0.0.1:<mapped-port>`
+
+## Common pitfalls
+
+- keeping caret ranges instead of exact pins after generation
+- letting Angular's generated README overstate scope
+- skipping containerized smoke proof and only running local tests
+- adding routing, SSR, API clients, or auth before the baseline is verified
+- checking in `.env` even though the scaffold does not need it
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- minimal real Angular tests exist
+- package and Docker defaults are pinned safely
+- README is honest
+- no `.env` is required or committed
+- the result is experimentally verified, not just theoretically scaffolded

package/assets/slopmachine/scaffold-playbooks/backend-baseline.md

@@ -0,0 +1,142 @@
+# Backend Baseline Scaffold Playbook
+
+Use this playbook when the request is for a category-level backend/API scaffold and the prompt does not already force a different backend family.
+
+## Goal
+
+Create a simple backend baseline that:
+
+- uses an official or safest-known bootstrap path for the selected backend family
+- keeps the runtime contract honest and Docker-first
+- includes a real database dependency and a safe config path
+- exposes one portable broad test command
+- stops at baseline infrastructure instead of product-specific features
+
+## Runtime contract
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- required database bootstrap command when a DB exists: `./init_db.sh`
+- all three commands must be real and working
+
+## Selection matrix for major backend families
+
+| Family | Official / bootstrap path | Strengths | Risks for baseline category work | Decision |
+| --- | --- | --- | --- | --- |
+| Node | `nest new backend-baseline --package-manager npm` | strongest official CLI, batteries included, built-in test scaffolding | heavier config/ORM wiring once safe config and DB state are enforced | good fallback when prompt explicitly asks for Nest or Node enterprise conventions |
+| Python | `python3 -m venv .venv` + pinned install; if available, prefer `uv init backend-baseline` first | fastest API + DB prototype, smallest surface to keep honest, easy Docker/test story | no single dominant framework generator, so some app structure is still hand-wired | **chosen default** |
+| Java | Spring Initializr / `start.spring.io` bootstrap | strongest official generator, production-shaped defaults, rich ecosystem | slower build/test loops, more boilerplate for a neutral category baseline | use when prompt explicitly asks for Spring or JVM enterprise patterns |
+| Go | `go mod init backend-baseline` plus Gin/Chi setup | fast builds, simple container runtime, small deploy footprint | fewer built-in baseline opinions for validation/config/test ergonomics | use when prompt explicitly wants Go or minimal static binaries |
+| PHP | `composer create-project laravel/laravel backend-baseline` or `laravel new backend-baseline` | strong official starter, batteries included, mature testing story | heavier than needed for neutral category baseline; requires PHP/Composer toolchain | use when prompt explicitly asks for Laravel/PHP |
+
+## Chosen default stack and version pins
+
+Prototype and default recommendation:
+
+- Python `3.12`
+- FastAPI `0.122.0`
+- Uvicorn `0.38.0`
+- SQLAlchemy `2.0.44`
+- SQLite `3` via Python stdlib driver
+- pytest `8.4.2`
+- httpx `0.28.1`
+
+Why this default won:
+
+- fastest verified path to a real API + real DB baseline
+- Docker and test setup stay readable instead of framework-heavy
+- works well as a category-level default when the prompt does not already lock the backend family
+
+## Bootstrap rule
+
+- use the official or best-known bootstrap command for the requested backend family when one exists
+- if the prompt leaves the backend family open, default to the Python/FastAPI baseline above
+- after bootstrap, adapt only enough to make Docker runtime, DB wiring, config, and README honest
+
+## Database wiring pattern
+
+- always route the app through one explicit runtime config path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- generate the runtime config file at container startup instead of committing `.env` files
+- for the default prototype, point the app at a SQLite file inside a Docker-managed volume so no DB credentials are needed
+- provide `./init_db.sh` as the single project-standard database setup entrypoint
+- `./init_db.sh` should create the baseline schema or migrations already known at scaffold time
+- when the prompt requires a network DB later, keep the same config-file contract and swap only the database URL and service wiring
+
+## Safe secret/config defaults
+
+- no `.env` dependency
+- no committed secrets
+- runtime secret values generated into Docker-managed volumes or mounted secret files
+- app config should be able to load secrets from file paths rather than only raw environment variables
+- Docker startup must work without user-side exports
+
+## Docker / Compose pattern
+
+- one app service
+- one database strategy: either an embedded DB file for the default fast baseline or a separate DB service when the prompt requires it
+- one test service behind a `test` profile when practical
+- app exposed on `127.0.0.1` only, preferably with a random host port
+- healthchecks on app and database
+- named volumes for runtime-generated config/state instead of committed files
+
+## Testing baseline
+
+At scaffold, include at least:
+
+- one health or smoke endpoint
+- one CRUD-ish endpoint with real persistence
+- containerized `./run_tests.sh`
+- pytest, Jest, JUnit, Go test, or framework-equivalent tests that hit real routes and prove DB wiring
+
+For the chosen Python baseline, the minimum real test floor is:
+
+- `GET /health` proves API boot + DB connectivity
+- `POST /items` then `GET /items` proves real persistence
+- `./run_tests.sh` performs both smoke `curl` checks and containerized pytest execution
+
+## README requirements
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- chosen stack and version pins
+- required runtime command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- database bootstrap command: `./init_db.sh`
+- how config is generated safely without `.env`
+- what is intentionally excluded from the baseline
+
+## Verification commands actually run for this prototype
+
+Commands run in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/backend-baseline`:
+
+```bash
+docker compose build
+docker compose up --build -d
+docker compose ps
+docker compose port app 8000
+curl -fsS "http://127.0.0.1:32771/health"
+curl -fsS -X POST "http://127.0.0.1:32771/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+curl -fsS "http://127.0.0.1:32771/items"
+docker compose down --volumes --remove-orphans
+./run_tests.sh
+```
+
+Observed result:
+
+- app reached healthy state on `127.0.0.1:32771`
+- `./run_tests.sh` finished with `2 passed in 0.49s`
+
+## Known caveats
+
+- this baseline uses schema creation via `./init_db.sh`; upgrade to a migrations tool when the prompt starts evolving the schema over time
+- the verified prototype uses SQLite for speed and zero-secret local startup; switch to a network database when the prompt needs external services, concurrent writers, or production-shaped infra
+- the default stack choice is category-level guidance, not a rule; use the prompt-specific family when it is explicit
+
+## What to reuse later
+
+- Docker-first runtime contract
+- `./run_tests.sh` wrapper pattern
+- `./init_db.sh` as the single DB bootstrap entrypoint
+- config-file-plus-secret-file wiring instead of `.env`
+- health endpoint + one persistence-backed route as the minimum real backend proof

package/assets/slopmachine/scaffold-playbooks/backend-family-matrix.md

@@ -0,0 +1,80 @@
+# Backend Scaffold Family Matrix
+
+Use this matrix after `backend-baseline.md` when the prompt or existing repo indicates a backend/API scaffold and the backend family still needs to be normalized.
+
+## Selection defaults
+
+Follow the original prompt and existing repo first. When the prompt is language-level only, use these defaults:
+
+| Prompt signal | Default family | Why this is the safe default |
+| --- | --- | --- |
+| Node.js | Nest + Fastify | strongest batteries-included Node backend starter, clear module structure, good DB/test story |
+| Python | FastAPI | current playbook default; fastest honest API + DB baseline with low scaffold cost |
+| Java | Spring Boot | strongest official bootstrap and production-shaped defaults |
+| Go | Go + Chi | smallest reliable HTTP surface, easy Docker/runtime wiring, low framework lock-in |
+| PHP | Laravel | strongest official starter, migrations/testing already standardized |
+| `not_specified` | Python + FastAPI | current category-open backend default from `backend-baseline.md` |
+
+If the repo already uses Express, Flask, Django, Gin, or another supported family, keep the repo family unless the prompt explicitly requests migration.
+
+## Shared contract for every backend family
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- required DB bootstrap command when persistence exists: `./init_db.sh`
+- do not depend on a checked-in `.env`
+- generate runtime config into a mounted runtime path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- keep database services internal-only in Compose; publish host ports only when the prompt truly needs direct host access
+- include a real health endpoint plus at least one persistence-backed route or module test
+- wire healthchecks so app startup waits on database readiness when a database service exists
+
+## Supported backend family matrix
+
+| Family | Likely scaffold root / bootstrap command | Safe default direction | Right choice when | Baseline API / test structure expectation | Database composition + shared Docker contract |
+| --- | --- | --- | --- | --- | --- |
+| **Nest + Fastify** (default Node family) | `npx @nestjs/cli@latest new <app-name> --package-manager npm` then `npm install @nestjs/platform-fastify` | Node `22 LTS`, TypeScript `5.x`, Nest `11.x`, Fastify `5.x`; keep Nest CLI layout and switch the HTTP adapter to Fastify | prompt says Node.js only, Nest, modular enterprise API, decorators/DI, or team-scale backend conventions | `src/main.ts`, root module, per-feature `module/controller/service`, unit `*.spec.ts`, e2e `test/*.e2e-spec.ts`, `/health` plus one persistence route | compose with SQLite for smallest local baseline or PostgreSQL for network DB; use Prisma/TypeORM/Drizzle only when chosen explicitly or already present; `./init_db.sh` owns migrations; app stays internal and waits on DB health |
+| **Express + TypeScript** | `npx express-generator@latest <app-name> --no-view` then add TypeScript + test wiring | Node `22 LTS`, Express `5.x`, TypeScript `5.x`; keep the stack thin and explicit | prompt explicitly says Express, webhook/middleware-heavy service, or minimal Node API without Nest ceremony | `src/server.ts` or `src/app.ts`, route modules, service/repository split where needed, `tests/integration/*.test.ts` with Supertest, `/health` plus one persistence route | same Docker contract as Nest; prefer PostgreSQL for service DB, SQLite for smallest local baseline, MongoDB only when the prompt explicitly wants a document store |
+| **FastAPI** (default Python family; experimentally verified) | `uv init <app-name>` then add FastAPI dependencies; fallback `python3 -m venv .venv && pip install fastapi uvicorn[standard] sqlalchemy pytest httpx` | Python `3.12`, FastAPI `0.122.x`, Uvicorn `0.38.x`, SQLAlchemy `2.0.x`, pytest `8.4.x`, httpx `0.28.x` | prompt says Python only, API-first service, typed request/response models, fast neutral backend scaffold | `app/main.py`, router package, config/settings module, DB/session module, `tests/test_health.py` and persistence tests using pytest | default local DB is SQLite in a Docker-managed volume; default network DB is PostgreSQL; keep `APP_CONFIG_PATH` contract, run migrations or schema bootstrap through `./init_db.sh`, and gate app on DB readiness when a DB service exists; see `fastapi-default.md` |
+| **Flask** | `python3 -m venv .venv && pip install Flask SQLAlchemy pytest` | Python `3.12`, Flask `3.1.x`, SQLAlchemy `2.0.x`, pytest `8.4.x`; prefer app-factory structure | prompt explicitly says Flask, simple service/webhook, or very small Python backend without FastAPI/Django weight | `app/__init__.py` app factory, blueprints, DB/extensions module, `tests/` with pytest and Flask test client or httpx, `/health` plus one persistence route | SQLite is acceptable for the minimal baseline; PostgreSQL is the default service DB when a network database is needed; use Alembic or a small idempotent bootstrap in `./init_db.sh` |
+| **Django** (experimentally verified) | `python3 -m pip install "Django>=5.2,<5.3" && django-admin startproject <app-name> . && python manage.py startapp api` | Python `3.12`, Django `5.2.x`; add Django REST Framework only when the scaffold is clearly JSON-API-first | prompt says Django, admin-heavy backend, server-rendered platform, or batteries-included Python monolith | project package + one or more apps, `urls.py`, models, migrations, `tests.py` or `tests/`, `/health` or equivalent readiness view, framework test runner or pytest-django | SQLite is acceptable only for tiny/local baselines; PostgreSQL is the default network DB; use Django migrations via `./init_db.sh`; Compose app should wait on DB health before migrations/start; see `django-default.md` |
+| **Spring Boot** (default Java family; experimentally verified) | `curl -G "https://start.spring.io/starter.tgz" --data-urlencode "type=maven-project" --data-urlencode "language=java" --data-urlencode "javaVersion=21" --data-urlencode "dependencies=web,data-jpa,validation,actuator,testcontainers" --data-urlencode "baseDir=<app-name>" | tar -xz` | Java `21 LTS`, Spring Boot `3.5.x`, Maven wrapper by default, Actuator on, Validation on; prefer explicit config properties and a single app module at scaffold time | prompt says Java only, Spring, JVM enterprise conventions, strong validation/config needs, or production-shaped service baseline | `src/main/java/...` with controller/service/repository split, `src/test/java/...`, `@SpringBootTest` and slice tests, `/actuator/health` plus one persistence-backed API | PostgreSQL is the default network DB; MySQL only when explicit or existing-repo driven; use Flyway or Liquibase for SQL migrations, run through `./init_db.sh`, and keep the DB service internal with healthchecks; see `spring-boot-default.md` |
+| **Go + Chi** (default Go family; experimentally verified) | `go mod init <module-path> && go get github.com/go-chi/chi/v5` | Go `1.24.x`, Chi `5.x`; stay close to `net/http`, `database/sql`, and small explicit packages | prompt says Go only, wants a low-magic service, small binary, or direct control over middleware and DB access | `cmd/server/main.go`, `internal/http`, `internal/store`, `internal/config`, `*_test.go` using `httptest`, `/health` plus one persistence route | SQLite is the local default; PostgreSQL is the default network DB using `pgx` or driver-equivalent; keep migration/bootstrap in `./init_db.sh`; no separate DB host port unless explicitly requested; see `go-chi-default.md` |
+| **Go + Gin** | `go mod init <module-path> && go get github.com/gin-gonic/gin` | Go `1.24.x`, Gin `1.11.x`; use only when the request benefits from higher-level JSON binding/middleware helpers | prompt explicitly says Gin or wants faster handler ergonomics than Chi/stdlib | same structure as Chi, but handlers and middleware hang off Gin router groups; tests still use `httptest` and `go test ./...` | same DB and Docker contract as Chi; do not make MongoDB or Redis the default just because Gin is chosen |
+| **Laravel** (default PHP family; experimentally verified) | `composer create-project laravel/laravel <app-name>` or `laravel new <app-name>` | PHP `8.3+`, Laravel `12.x`; keep built-in config/migration/test structure and queue/cache stubs off unless requested | prompt says PHP only, Laravel, admin/back-office style app, or batteries-included MVC/API backend | `routes/api.php`, controllers, models, migrations, `tests/Feature`, `tests/Unit`, `/up` or `/health` readiness route, real DB-backed feature test | MySQL is the conventional default service DB for PHP-only asks; PostgreSQL is also supported when the repo or prompt wants it; SQLite is fine for tiny local/test baselines; Eloquent migrations run through `./init_db.sh`; DB stays on an internal Compose network; see `laravel-default.md` |
+
+## Practical family guidance
+
+- **Prefer Nest + Fastify over Express** when the prompt only says Node.js and does not push for minimalism.
+- **Prefer FastAPI over Flask or Django** when the prompt only says Python and the task is an API/backend scaffold.
+- **Prefer Django over FastAPI** only when the prompt implies Django conventions, admin-heavy behavior, or server-rendered/backend-monolith shape.
+- **Prefer Chi over Gin** when the prompt only says Go and does not need extra framework ergonomics.
+- **Prefer Laravel over custom PHP wiring** for every PHP-only baseline unless an existing repo already chose a different PHP framework.
+
+## Verified concrete playbooks
+
+- `backend-baseline.md` — verified category-open backend baseline
+- `fastapi-default.md` — experimentally verified FastAPI baseline
+- `spring-boot-default.md` — experimentally verified Spring Boot baseline
+- `django-default.md` — experimentally verified Django baseline
+- `laravel-default.md` — experimentally verified Laravel baseline
+- `go-chi-default.md` — experimentally verified Go + Chi baseline
+
+## Placeholder handling
+
+- `backend_family=not_specified` means **choose from the language default table above**, not “invent a new framework.”
+- `backend_language=not_specified` and no existing repo evidence means **Python + FastAPI**.
+- `backend_family=not_specified` with an existing repo means **keep the existing repo family**.
+- `database=not_specified` should not remove persistence entirely; pair the chosen backend family with the default database module from `database-module-matrix.md`.
+
+## Family-by-family default DB pairing summary
+
+| Family | Local / smallest honest DB default | Network / service DB default |
+| --- | --- | --- |
+| Nest + Fastify | SQLite | PostgreSQL |
+| Express + TypeScript | SQLite | PostgreSQL |
+| FastAPI | SQLite | PostgreSQL |
+| Flask | SQLite | PostgreSQL |
+| Django | SQLite only for tiny local baseline | PostgreSQL |
+| Spring Boot | SQLite only if the prompt truly keeps things local and tiny | PostgreSQL |
+| Go + Chi / Gin | SQLite | PostgreSQL |
+| Laravel | SQLite for tiny local/test baseline | MySQL |

package/assets/slopmachine/scaffold-playbooks/database-module-matrix.md

@@ -0,0 +1,80 @@
+# Database Module Matrix
+
+Use this after selecting the backend family. This matrix defines the standard database wiring modules we should compose into backend and fullstack scaffolds.
+
+## Shared database wiring contract
+
+- if the scaffold has persistence, it gets a real `./init_db.sh`
+- app runtime reads one generated config path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- no checked-in `.env`
+- no committed secrets or baked database credentials
+- database services stay internal-only in Compose unless the prompt explicitly requires host access
+- healthchecks are mandatory for every database service container
+- `./run_tests.sh` must prove both app readiness and real database access
+
+At the config level, normalize on a small shared shape even when each framework maps it into native config objects:
+
+```json
+{
+  "database": {
+    "driver": "postgresql|mysql|sqlite|mongodb",
+    "url": "...",
+    "host": "db",
+    "port": 5432,
+    "name": "app",
+    "user": "app",
+    "password_file": "/run/secrets/db_password"
+  }
+}
+```
+
+## Database selection defaults
+
+| Prompt / selector state | Default database module | Why |
+| --- | --- | --- |
+| `database=postgresql` | PostgreSQL | neutral service-container SQL default across most backend families |
+| `database=mysql` | MySQL | explicit MySQL ask, existing MySQL estate, or conventional Laravel/MySQL pairing |
+| `database=sqlite` | SQLite | smallest honest local persistence path with no credentials |
+| `database=mongodb` | MongoDB | explicit document-store or flexible-schema requirement |
+| `database=not_specified` | SQLite for the smallest honest baseline | baseline should still prove persistence without forcing a network DB |
+
+When the prompt or repo clearly requires a **service-container relational DB** but leaves the engine open, prefer **PostgreSQL** except for conventional PHP/Laravel defaults where MySQL is still reasonable.
+
+## Database module matrix
+
+| Module | Safe baseline direction | Use it when | Secret / config handling model | Migration / init expectations | Docker composition expectations | State location default |
+| --- | --- | --- | --- | --- | --- | --- |
+| **PostgreSQL** | PostgreSQL `17.x`, internal service name `db`, healthcheck via `pg_isready` | prompt wants a real service DB, relational integrity, concurrent writers, or production-shaped SQL infrastructure | app reads one generated DSN or config object; local disposable credentials may live in Compose only when the DB is internal-only and clearly documented as throwaway; otherwise mount secret files | `./init_db.sh` waits for healthy DB then runs family-native migrations (Alembic, Django migrations, Flyway/Liquibase, Prisma/TypeORM/Drizzle, Eloquent, goose, etc.); idempotent seed/bootstrap is allowed | `db` service on the internal bridge network, `expose: 5432`, named volume for data, readiness-gated `depends_on`, no host port by default | **service container state** with a named Docker volume |
+| **MySQL** | MySQL `8.4 LTS`, internal service name `db`, healthcheck via `mysqladmin ping` | prompt explicitly wants MySQL/MariaDB-family behavior, existing repo already uses it, or Laravel/PHP conventions dominate | same config-file contract as PostgreSQL; never commit credentials; local-only disposable credentials are acceptable only for isolated internal Compose use | `./init_db.sh` runs framework-native migrations after healthcheck; schema/bootstrap stays idempotent; avoid raw hand-edited SQL dumps as the primary scaffold contract | `db` service on internal network, `expose: 3306`, named volume, readiness-gated startup, no host port unless explicitly requested | **service container state** with a named Docker volume |
+| **SQLite** | SQLite `3` via language/runtime driver, DB file under a mounted runtime path such as `/runtime/data/app.sqlite` | prompt leaves DB open, the scaffold only needs the smallest honest persistence layer, or the backend family is still in category-open baseline mode | no DB credentials; keep the file path in generated runtime config; never commit live `.sqlite` state into the repo | `./init_db.sh` creates the file path, runs schema creation or migrations against that file, and can safely recreate it for tests; once schema evolution becomes real, switch to the family's migration tool instead of ad hoc SQL | **no separate DB service**; the app service mounts a named volume for DB state; app health should still prove it can open/query the file | **local app-mounted state** in a named Docker volume by default; use a gitignored host bind mount only if the prompt explicitly needs inspectable local files |
+| **MongoDB** | MongoDB `8.x`, internal service name `db`, healthcheck via `mongosh --eval 'db.adminCommand({ ping: 1 })'` | prompt explicitly wants a document store, event/log style documents, flexible schema, or an existing Mongo repo | same generated config-file contract; use URI plus optional secret-file paths; local disposable users are acceptable only for internal-only Compose bootstrap | `./init_db.sh` should create users/databases as needed, apply indexes/validators, and seed any baseline documents idempotently; think “indexes + validators + bootstrap” rather than SQL migrations | `db` service on internal network, `expose: 27017`, named volume, healthcheck, readiness-gated startup; no host port by default | **service container state** with a named Docker volume |
+
+## Host-volume local state vs service-container state
+
+| Database module | Default state model | When to use host-volume local state instead |
+| --- | --- | --- |
+| PostgreSQL | service-container named volume | almost never at scaffold time; only when the prompt explicitly needs inspectable raw database files on the host |
+| MySQL | service-container named volume | almost never at scaffold time; same rule as PostgreSQL |
+| SQLite | app-mounted named volume | when the prompt explicitly wants a visible local file for manual inspection or offline tooling; keep the bind mount gitignored |
+| MongoDB | service-container named volume | almost never at scaffold time |
+
+## Family-to-database pairing defaults
+
+| Backend family | Smallest honest default when DB is open | Default network/service DB | Notes |
+| --- | --- | --- | --- |
+| Nest + Fastify | SQLite | PostgreSQL | MongoDB only when the prompt explicitly wants a document model |
+| Express + TypeScript | SQLite | PostgreSQL | MySQL is fine when the repo already uses it; not the neutral default |
+| FastAPI | SQLite | PostgreSQL | this is the current category-open backend default pairing |
+| Flask | SQLite | PostgreSQL | stay lightweight unless the prompt proves a larger service DB is needed |
+| Django | SQLite for tiny local scaffolds only | PostgreSQL | keep Django migrations first-class; use DRF only when the API surface warrants it |
+| Spring Boot | SQLite only for rare tiny local baselines | PostgreSQL | MySQL is acceptable for explicit compatibility; PostgreSQL remains the neutral default |
+| Go + Chi / Gin | SQLite | PostgreSQL | use MongoDB only for explicit document-store prompts |
+| Laravel | SQLite for tiny local/test baselines | MySQL | PostgreSQL is still acceptable when the repo or prompt asks for it |
+
+## Placeholder handling
+
+- `database=not_specified` means **choose the smallest honest DB module for the selected backend family**, not “skip the database.”
+- if both backend family and database are open, default to **FastAPI + SQLite** per the current backend baseline direction.
+- if the prompt explicitly implies a multi-user or production-shaped service DB but does not name an engine, default to **PostgreSQL**.
+- if the prompt says PHP only and leaves the DB open, default to **Laravel + MySQL** unless the repo already standardized on PostgreSQL.
+- `not_specified` never means “commit secrets later”; keep the config-file + secret-file contract from day one.

package/assets/slopmachine/scaffold-playbooks/django-default.md

@@ -0,0 +1,166 @@
+# Django Default Scaffold Playbook
+
+Use this playbook when the request explicitly wants Django or when a backend baseline should prefer Django's official project/app bootstrap path over lighter Python microframeworks.
+
+Verified lab: `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/django-baseline`
+
+## Goal
+
+Create a Django baseline that:
+
+- uses Django's official bootstrap path
+- keeps defaults pinned and conservative
+- wires the backend to a safe default database pattern without `.env`
+- ships a real `docker compose up --build` path
+- ships a real containerized `./run_tests.sh`
+- includes minimal real Django tests
+- keeps the README honest about included versus excluded scope
+- stops at baseline infrastructure instead of product-specific features
+
+## Runtime contract
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- required database bootstrap command: `./init_db.sh`
+- all three commands must be real and working
+
+## Official/bootstrap path
+
+Per Django's documented admin commands, the baseline should start from:
+
+```bash
+django-admin startproject config .
+python manage.py startapp core
+```
+
+Those commands preserve the standard Django project shape while keeping the app split explicit.
+
+## Chosen default stack and version pins
+
+- Python `3.12`
+- Django `5.2.6`
+- Gunicorn `23.0.0`
+- SQLite `3` via Django's built-in SQLite backend
+
+Why this default won:
+
+- Django provides the official project generator, ORM, migrations, and test runner in one maintained stack
+- SQLite keeps the baseline fast, reproducible, and secret-free while still proving real persistence
+- Gunicorn provides a safer container runtime than `runserver` while keeping the app bootstrap simple
+
+## Safe database/config pattern
+
+- always route runtime configuration through one explicit config file path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- generate that config file at startup with a small bootstrap script instead of committing `.env`
+- generate `SECRET_KEY` into a Docker-managed runtime file under `/runtime/state`
+- default the database to a SQLite file under `/runtime/db/django-baseline.sqlite3` in a named volume
+- provide `./init_db.sh` as the single database bootstrap entrypoint and make it run `python manage.py migrate --noinput`
+
+## Docker / Compose pattern
+
+- one `app` service
+- one disposable `test` service behind a `test` profile
+- host exposure loopback-bound only via `127.0.0.1::8000`
+- named volumes for runtime config, generated secret state, and SQLite data
+- app healthcheck must hit `/health` inside the container and the endpoint must perform a real DB query
+
+## Minimal baseline behavior
+
+At scaffold time, include at least:
+
+- `GET /health` proves app boot + DB connectivity
+- `POST /items` and `GET /items` prove ORM-backed persistence
+- one migration for the minimal model
+- `python manage.py test` wired into `./run_tests.sh`
+
+Minimum real Django tests:
+
+- one test for `GET /health`
+- one test for `POST /items` then `GET /items`
+
+## README requirements
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- chosen stack and pinned versions
+- required runtime command: `docker compose up --build`
+- required test command: `./run_tests.sh`
+- database bootstrap command: `./init_db.sh`
+- how runtime config and `SECRET_KEY` are generated safely without `.env`
+- what is intentionally excluded from the baseline
+
+## Verification commands actually run for this prototype
+
+Commands run in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/django-baseline`:
+
+```bash
+docker compose build
+docker compose up --build -d
+docker compose ps
+docker compose port app 8000
+curl -fsS "http://127.0.0.1:32781/health"
+curl -fsS -X POST "http://127.0.0.1:32781/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+curl -fsS "http://127.0.0.1:32781/items"
+docker compose down --volumes --remove-orphans
+./run_tests.sh
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/django-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 180
+    while time.time() < deadline:
+        try:
+            port_output = subprocess.check_output(["docker", "compose", "port", "app", "8000"], cwd=cwd, text=True).strip()
+            if port_output:
+                host = port_output.split(":")[-1]
+                with urlopen(f"http://127.0.0.1:{host}/health", timeout=2) as response:
+                    body = response.read().decode("utf-8")
+                    if response.status == 200 and '"status": "ok"' in body and '"database": "ok"' in body:
+                        print(f"docker compose up --build reached healthy /health on http://127.0.0.1:{host}/health")
+                        break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"django baseline never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "-v", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+Observed results:
+
+- `docker compose ps` reported the app `Up ... (healthy)` and `docker compose port app 8000` returned `127.0.0.1:32781`
+- `GET /health` returned `{"status": "ok", "database": "ok", "app_name": "django-baseline-lab", "environment": "development"}`
+- `POST /items` returned `{"id": 1, "name": "manual-smoke-item", "created_at": "2026-04-14T21:27:33.090Z"}`
+- `GET /items` returned `[{"id": 1, "name": "manual-smoke-item", "created_at": "2026-04-14T21:27:33.090Z"}]`
+- `./run_tests.sh` reported `Ran 2 tests in 0.005s`, `OK`, and `Django smoke check passed at http://127.0.0.1:32794`
+- the interactive `docker compose up --build` path reached a healthy `/health` endpoint and printed `docker compose up --build reached healthy /health on http://127.0.0.1:32796/health`
+
+## Known caveats
+
+- this baseline uses direct Django migrations for the initial schema; introduce more advanced migration workflows only when the prompt grows beyond a baseline lab
+- SQLite is the safe default for local baseline work, not a production recommendation for concurrent high-write deployments
+- admin/auth are present only as framework defaults; they are not configured as finished product features
+
+## What to reuse later
+
+- Django official bootstrap shape
+- config-file-plus-secret-file runtime pattern instead of `.env`
+- Docker-first runtime contract
+- `./run_tests.sh` wrapper pattern
+- `./init_db.sh` as the single DB bootstrap entrypoint
+- health endpoint + one persistence-backed route as the minimum real backend proof