theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/expo-react-native-default.md

@@ -0,0 +1,73 @@
+# Expo React Native Default Scaffold Playbook
+
+Use this playbook for cross-platform mobile requests unless the prompt explicitly requires native-only Android or iOS work.
+
+## Goal
+
+Create a simple Expo + React Native + TypeScript baseline that:
+
+- boots cleanly for local development
+- exposes one honest runtime wrapper
+- exposes one portable broad test command
+- installs the baseline mobile test layer
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- `./run_app.sh` may exist as a helper for host-side convenience, but it does not replace the required Docker baseline
+
+## Safe default stack
+
+- Expo
+- React Native
+- TypeScript
+- Jest
+- React Native Testing Library
+
+## Bootstrap rule
+
+- use the current official Expo TypeScript bootstrap path unless the prompt or existing repo clearly dictates another mobile starter
+- adapt the generated project only enough to make runtime, tests, and README honest
+
+## Required scripts
+
+- `docker compose up --build`
+- `./run_tests.sh`
+- `./run_app.sh` when useful for local Expo convenience
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real component or state test
+- one real Jest invocation in `./run_tests.sh`
+- one real Docker-backed runtime/build path behind `docker compose up --build`
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- host-side helper command: `./run_app.sh` when present
+- whether the current baseline is Expo/local-device focused
+- any platform-proof limits that still exist at scaffold time
+
+## Common pitfalls
+
+- pretending scaffold already proves real device flow quality
+- skipping RN test setup until later
+- hiding mock/local-only data defaults
+- letting runtime depend on undocumented global host state
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- baseline RN tests exist
+- README is honest about the current mobile proof boundary

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

@@ -0,0 +1,134 @@
+# FastAPI Default Scaffold Playbook
+
+Use this playbook when the request explicitly asks for a FastAPI baseline or when the backend family has already been narrowed to FastAPI.
+
+## Goal
+
+Create a FastAPI-only baseline that:
+
+- follows the official or best-known FastAPI bootstrap path honestly
+- keeps dependency versions pinned
+- uses a safe default database pattern with real persistence
+- makes `docker compose up --build` the primary runtime command
+- makes `./run_tests.sh` the portable broad verification command
+- stops at baseline infrastructure instead of product features
+
+## Bootstrap rule
+
+- FastAPI does not provide an official full-project generator for this baseline shape
+- use the official docs pattern: create the Python environment, install pinned FastAPI dependencies, write the app module, and run `uvicorn app.main:app --host 0.0.0.0 --port 8000`
+- do not invent extra framework layers or boilerplate generators just to make the tree look bigger
+
+Reusable bootstrap commands:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## Safe pinned defaults
+
+- Python `3.12.11`
+- FastAPI `0.122.0`
+- Uvicorn `0.38.0`
+- SQLAlchemy `2.0.44`
+- Pydantic `2.12.3`
+- pytest `8.4.2`
+- httpx `0.28.1`
+- Docker image: `python:3.12.11-slim-bookworm`
+
+## Database pattern
+
+- default to SQLite for the baseline because it keeps the local runtime secret-free and easy to verify
+- place the SQLite file in a Docker-managed volume, not in the repo
+- generate the runtime config file at container startup instead of committing `.env`
+- keep `./init_db.sh` as the single database bootstrap entrypoint
+- use SQLAlchemy with one shared engine and per-request sessions
+
+## Required runtime contract
+
+- runtime: `docker compose up --build`
+- tests: `./run_tests.sh`
+- DB bootstrap: `./init_db.sh`
+- all three commands must be real
+
+## Minimum API floor
+
+At baseline, include all of the following:
+
+- `GET /health` proving API boot and database connectivity
+- `POST /items` creating a persisted record
+- `GET /items` returning persisted records
+- at least two real tests hitting those routes
+
+## Compose pattern
+
+- one `app` service
+- one optional `test` service behind the `test` profile
+- expose only the API port to `127.0.0.1`
+- prefer Docker-assigned random host ports to avoid collisions
+- include an app healthcheck
+- store generated config and DB state in named volumes
+
+## README requirements
+
+`README.md` must state:
+
+- that this is baseline only
+- the exact pinned stack
+- the exact runtime command
+- the exact test command
+- the exact DB bootstrap command
+- that no `.env` file is used
+- what is intentionally excluded
+
+## Experimental verification for this lab
+
+Commands run in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/fastapi-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:32778/health"
+curl -fsS -X POST "http://127.0.0.1:32778/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+curl -fsS "http://127.0.0.1:32778/items"
+docker compose down --volumes --remove-orphans
+python3 -c 'import subprocess, sys, time; cmd=["docker","compose","up","--build"]; proc=subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True); seen=False; start=time.time();
+while True:
+    line=proc.stdout.readline()
+    if line:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+        if "Application startup complete." in line or "Uvicorn running on" in line:
+            seen=True
+            break
+    elif proc.poll() is not None:
+        break
+    elif time.time()-start>120:
+        break
+if not seen:
+    proc.terminate(); proc.wait(timeout=20); sys.exit(1)
+subprocess.run(["docker","compose","stop","app"], check=True)
+rc=proc.wait(timeout=60)
+sys.exit(rc if rc is not None else 1)'
+docker compose down --volumes --remove-orphans
+./run_tests.sh
+```
+
+Observed result:
+
+- detached startup reached healthy state on `127.0.0.1:32778`
+- `GET /health`, `POST /items`, and `GET /items` all returned successful real API responses
+- attached `docker compose up --build` reached `Application startup complete.` before controlled shutdown
+- `./run_tests.sh` finished with `2 passed in 0.53s` and printed `FastAPI smoke check passed at http://127.0.0.1:32779`
+
+## Expected caveats
+
+- upgrade from schema creation to migrations only when the prompt starts requiring schema evolution
+- switch to a network database only when the prompt actually needs multi-service or production-shaped DB behavior
+- keep the config-file pattern even if the DB backend changes

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

@@ -0,0 +1,160 @@
+# Frontend Baseline Scaffold Playbook
+
+Use this when the request is for a plain frontend category scaffold and the prompt does not already force a framework-specific server/runtime model.
+
+## Decision summary
+
+- **chosen default:** React + Vite + TypeScript
+- **why:** safest official SPA bootstrap to verify quickly with Docker, minimal real frontend tests, and low baseline complexity
+- **verified runtime:** `docker compose up --build`
+- **verified broad test path:** `./run_tests.sh`
+
+## Official bootstrap matrix
+
+| Stack | Official/bootstrap path | Good fit | Why not the default prototype here |
+| --- | --- | --- | --- |
+| React + Vite | `npm create vite@latest frontend-baseline -- --template react-ts` | Fast typed SPA baseline; easy Docker + Vitest path | Chosen default |
+| Vue + Vite | `npm create vue@latest` | Strong official starter; excellent when prompt explicitly says Vue | Slightly more prompt/config surface for a category-open default |
+| Angular | `ng new <project-name>` | Best when Angular conventions are required | Heavier install/build/test footprint than needed for a generic baseline scaffold |
+
+## Evidence basis for the matrix
+
+- React docs currently recommend a framework for production-scale React apps, but React's own from-scratch guidance points to build tools such as Vite when a lighter client-only app is appropriate.
+- Vite docs provide the official `npm create vite@latest` bootstrap and list `react-ts` / `vue-ts` templates.
+- Vue docs provide `npm create vue@latest` as the official SPA bootstrap path.
+- Angular docs provide `ng new` after Angular CLI installation as the official local bootstrap path.
+
+For a **category-level frontend baseline**, the safest prototype is the one with the lowest runtime/test burden while still using an official starter. That is React + Vite here.
+
+## Chosen default stack and version pins
+
+Verified prototype pins:
+
+- Node image: `node:22.21.1-alpine3.22`
+- React: `19.2.4`
+- React DOM: `19.2.4`
+- Vite: `8.0.4`
+- `@vitejs/plugin-react`: `6.0.1`
+- TypeScript: `6.0.2`
+- Vitest: `4.1.4`
+- `@testing-library/react`: `16.3.2`
+- `@testing-library/jest-dom`: `6.9.1`
+- `@testing-library/user-event`: `14.6.1`
+- `jsdom`: `29.0.2`
+
+Compatibility pins used in this verified lab:
+
+- `@rolldown/binding-darwin-arm64@1.0.0-rc.12` as an **optional** dependency for current macOS arm64 + npm optional-binding behavior
+- `@emnapi/core@1.9.2`
+- `@emnapi/runtime@1.9.2`
+
+## Safe defaults
+
+- no `.env` file required
+- no secrets committed
+- no pre-seeded runtime exports required
+- baseline-only UI, not a feature-complete app
+- Docker host port bound to `127.0.0.1` with a random host port to reduce local collisions
+- healthcheck required before test smoke step proceeds
+
+## Docker / Compose pattern
+
+Recommended baseline pattern:
+
+1. **multi-stage Dockerfile**
+   - shared `npm ci` base
+   - `development` target runs `vite` on `0.0.0.0:5173`
+   - `verify` target runs `npm run verify`
+2. **Compose services**
+   - `web` service for `docker compose up --build`
+   - `test` service behind a `test` profile for containerized verification
+3. **port strategy**
+   - expose only the app port
+   - prefer `127.0.0.1::5173` so parallel local worktrees do not collide
+4. **health strategy**
+   - wait for `wget http://127.0.0.1:5173` healthcheck before curl smoke tests
+
+## Testing baseline
+
+Minimum real testing floor for this playbook:
+
+- Vitest component tests
+- React Testing Library rendering assertions
+- one small interaction test (`Show verification commands` toggle)
+- one containerized smoke check that confirms the app shell is served through Compose
+- one containerized broad path that runs lint + unit tests + production build
+
+Suggested scripts:
+
+- `npm run test`
+- `npm run verify`
+- `./run_tests.sh`
+
+`./run_tests.sh` should:
+
+1. build Docker images
+2. start `web`
+3. wait for health
+4. `curl` the served HTML shell
+5. run the `test` profile container
+6. tear down cleanly
+
+## README requirements
+
+The scaffold `README.md` should explicitly state:
+
+- that this is a **baseline scaffold**
+- chosen stack and why it was picked
+- `docker compose up --build`
+- `./run_tests.sh`
+- any optional local iteration commands
+- what is included now vs intentionally deferred
+- no `.env` / no secrets policy
+- main files worth reusing later
+
+## Verification commands actually run in the verified prototype
+
+User-facing commands verified:
+
+```bash
+npm create vite@latest frontend-baseline -- --template react-ts
+npm install
+npm run verify
+docker pull node:22.21.1-alpine3.22
+docker compose up --build
+./run_tests.sh
+```
+
+Supporting commands used during verification:
+
+```bash
+docker compose port web 5173
+curl -fsS http://127.0.0.1:<mapped-port>
+docker compose down --remove-orphans
+```
+
+Observed verification results in the prototype lab:
+
+- local `npm run verify`: passed
+- containerized `./run_tests.sh`: passed
+- runtime `docker compose up --build`: passed and served the app shell
+
+## Known caveats
+
+- The curl smoke check validates the served HTML shell, not hydrated browser DOM behavior. Keep Vitest component tests for actual UI assertions.
+- Current Vite 8 / Rolldown behavior on macOS arm64 under npm may need the optional native binding and `emnapi` compatibility pins noted above.
+- Angular remains a documented alternative, not the verified prototype, because its baseline cost is higher for category-level scaffolding.
+- Vue + Vite remains the preferred fallback when the prompt explicitly requires Vue.
+
+## What to reuse later
+
+Reuse these parts directly for later frontend prompts:
+
+- the React + Vite official bootstrap path
+- the multi-stage Dockerfile pattern
+- random localhost host-port mapping
+- healthcheck + curl smoke test flow
+- `./run_tests.sh` as the canonical broad-path wrapper
+- the README honesty checklist
+
+Do **not** treat this playbook as a signal to pre-add routing, auth, API clients, or E2E browsers unless the prompt explicitly needs them.

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

@@ -0,0 +1,134 @@
+# Frontend Scaffold Family Matrix
+
+Use this as the family-level reference for turning CSV stack labels and prompt cues into a concrete frontend scaffold choice.
+
+This is intentionally about **frontend families**, not prompt-specific apps.
+
+## Interpretation rules
+
+1. Existing repo reality and explicit prompt framework names beat generic labels.
+2. `modern_frontend_framework` and `html_css_js` are **intake labels**, not real scaffold families.
+3. `server-rendered HTML` is a **delivery mode**, not enough by itself; resolve it to a concrete root such as HTMX, Thymeleaf, or Livewire.
+4. Prefer the lightest official/bootstrap path that still supports the shared Docker contract and minimal real tests.
+
+## Prepared frontend family matrix
+
+| Family | Support tier | Official/bootstrap init path | Safe default direction | Choose this when | Backend composition | Docker composition | Minimal real testing baseline | Required wrapper/runtime/test expectations |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **React + Vite + TypeScript** | **First-line default** | `npm create vite@latest <app> -- --template react-ts` | Node 22 LTS; React 19; Vite 8; strict TypeScript; Tailwind CSS by default; prefer `shadcn/ui`; fallback to Material UI or Ant Design when `shadcn/ui` is not the right fit; Vitest + Testing Library | Prompt says React, prompt only says `modern_frontend_framework`, or we need the safest generic SPA baseline | Best with decoupled REST/JSON backends across Node/Python/Java/Go/PHP; also fine for pure frontend/no-backend work | Fullstack: separate frontend build/edge service plus internal backend. Pure frontend: single web container is fine | 1 component render test, 1 interaction/state test, production build smoke, container smoke of served shell | Must provide `docker compose up --build`, `./run_tests.sh`, `npm run test`, and `npm run build` |
+| **Vue + Vite + TypeScript** | **First-line when Vue is explicit; experimentally verified** | `npm create vue@latest` | Node 22 LTS; Vue 3; Vite 8; TypeScript on; Composition API + `<script setup>`; Tailwind CSS by default; prefer a stable `shadcn`-style Vue port when it is well-documented for the chosen stack, otherwise default to Ant Design Vue; add Router/Pinia only when the prompt needs them; Vitest baseline | Prompt says Vue, existing repo is Vue, or prompt body clearly describes a Vue app but stack label is generic | Same decoupled API pairing pattern as React + Vite | Same SPA pattern as React: dedicated frontend service when fullstack, static edge publish when appropriate | 1 component test, 1 state/interaction test, production build smoke, container smoke | Must provide `docker compose up --build`, `./run_tests.sh`, `npm run test`, and `npm run build`; see `vue-vite-default.md` |
+| **Angular** | **Prepared and experimentally verified, but not generic default** | Install Angular CLI, then `ng new <app>` | Current Angular stable CLI/workspace; standalone components; strict mode; active/maintenance Node LTS; SSR off unless explicitly required; Tailwind CSS by default when styling is open; Angular Material as the default documented component system | Prompt explicitly says Angular or org conventions clearly require Angular | Best with decoupled REST/JSON backends; avoid as the category-open default because scaffold/build/test footprint is heavier | Same SPA pattern as React/Vue: separate frontend build/runtime surface in fullstack work | 1 generated component or page test, 1 routing/smoke assertion, production build smoke | Must provide `docker compose up --build`, `./run_tests.sh`, `ng test --watch=false` (or equivalent non-watch test target), and `ng build`; see `angular-default.md` |
+| **HTMX + server-rendered templates** | **First-line `html_css_js` default** | No standalone app generator. Start from the backend family's official scaffold, then add htmx via vendored asset or `npm install htmx.org@2` if an asset pipeline exists | htmx 2.x; return HTML fragments instead of JSON by default; progressive enhancement first; keep JS light and local | Prompt is form-heavy/workflow-heavy, partial-page updates are enough, backend should own validation/state, or prompt only says `html_css_js` | Best with backend-rendered templates in Python, Go, PHP, Java, Ruby, etc. | Usually no separate JS frontend container. Publish one app-facing backend service; optional thin reverse proxy only if it adds real value | 1 full-page route/template test, 1 partial/fragment swap response test, 1 HTTP smoke through container | Must provide `docker compose up --build`, `./run_tests.sh`, backend-native tests, and an HTTP/page smoke. No separate frontend test runner is required unless extra JS is added |
+| **Thymeleaf / Spring server-rendered HTML** | **Prepared backend-coupled family** | Spring Initializr with `web,thymeleaf` (optionally devtools), or equivalent `spring init` flow | Java 21 LTS; current Spring Boot 3.x stable; Thymeleaf starter; server-rendered pages first; add HTMX only if the prompt needs richer partial updates | Backend is Spring Boot / Java and the UI should stay template-first instead of becoming a separate SPA | Same Spring app owns routes, views, validation, and any JSON endpoints | Single Spring app-facing service is acceptable; DB stays internal; thin reverse proxy optional, not required | 1 controller/view test, 1 rendered-page assertion, build/test smoke via Maven or Gradle | Must provide `docker compose up --build`, `./run_tests.sh`, and `./mvnw test` or `./gradlew test`, plus HTTP smoke |
+| **Livewire / Laravel server-driven UI** | **Prepared backend-coupled family when warranted; experimentally verified** | `laravel new <app>` (or `composer create-project laravel/laravel <app>`), then `composer require livewire/livewire`; `php artisan livewire:layout` when needed | Current stable Laravel + Livewire 4; Blade layouts; keep Livewire/Alpine bundled the Laravel way; use Laravel Vite defaults instead of inventing a separate SPA | Backend is Laravel/PHP and prompt wants reactive forms/tables/workflows without splitting into a separate JS frontend | Same Laravel app owns routes, auth, validation, rendering, and Livewire updates | No separate frontend container required. Use one Laravel app-facing service or the normal nginx+php-fpm pair as a single app surface | 1 page/feature test, 1 Livewire component test, asset/build smoke when Vite assets exist | Must provide `docker compose up --build`, `./run_tests.sh`, `php artisan test`, and `npm run build` when Laravel assets are part of the scaffold; see `livewire-default.md` |
+
+## Cross-family defaults
+
+### Shared Docker contract
+
+All web families above inherit the same baseline contract from the existing scaffold playbooks:
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- only one app-facing service should be host-published by default
+- healthchecks must drive readiness
+- no checked-in `.env` dependency for the baseline itself
+
+The main family split is:
+
+- **SPA families** (React/Vue/Angular): usually a separate frontend build/runtime surface
+- **server-driven families** (HTMX/Thymeleaf/Livewire): frontend usually lives inside the backend app surface
+
+### Shared UI defaults
+
+- for web UI-bearing scaffolds, default to Tailwind CSS when the ecosystem supports it cleanly
+- prefer `shadcn/ui` or an equivalent well-documented port only where it is truly supported by the chosen ecosystem
+- otherwise prefer a mainstream documented component library appropriate to that stack rather than a niche or weakly documented UI kit
+
+### Wrapper expectations
+
+- Every family needs an honest `README.md` that states scaffold scope and the real runtime/test commands.
+- Every family needs at least one **real static test layer** plus one **runtime smoke proof**.
+- For SPA families, the static test layer is normally frontend unit/component tests.
+- For server-driven families, the static test layer is normally backend-native page/component/controller tests.
+
+## Placeholder/label vs real family
+
+### Treat these as placeholders / intake labels
+
+- `modern_frontend_framework`
+- `html_css_js`
+- `server-rendered HTML`
+- generic phrases like “modern SPA”, “admin dashboard”, or “frontend UI”
+
+These labels are not enough to choose tooling on their own. They must resolve to a real family.
+
+### Treat these as real frontend families
+
+- React + Vite
+- Vue + Vite
+- Angular
+- HTMX
+- Thymeleaf
+- Livewire
+
+### Treat these as prompt-explicit exceptions, not current default prep targets
+
+The CSV-derived prompt bodies also mention concrete ecosystems such as Svelte, jQuery/Layui, Templ, Yew, Leptos, and Dioxus. Those are real frameworks in their own ecosystems, but they should not become the default family-prep set here unless the prompt or repo explicitly requires them.
+
+## Default resolution rules for the CSV labels
+
+### When the prompt says only `modern_frontend_framework`
+
+Recommended default:
+
+- **React + Vite + TypeScript**
+
+Why:
+
+- it already matches the verified `frontend-baseline.md` direction
+- it has the cleanest official bootstrap path for a category-open SPA scaffold
+- it has the lowest generic runtime/test burden while still supporting a strong component-test baseline
+
+Use Vue + Vite instead only when the prompt body or repo explicitly signals Vue.
+Use Angular only when the prompt or repo explicitly signals Angular.
+
+## Verified concrete playbooks
+
+- `frontend-baseline.md` — verified open-ended React/Vite default
+- `vue-vite-default.md` — experimentally verified Vue/Vite baseline
+- `angular-default.md` — experimentally verified Angular baseline
+- `livewire-default.md` — experimentally verified Livewire baseline
+
+## Playwright rule
+
+- do not assume Playwright belongs in every frontend scaffold
+- include Playwright only when the prompt explicitly requires it or when the concrete family playbook has experimentally verified it
+- if a family playbook includes Playwright, the documented commands must have been run successfully on that family baseline
+- until that is true, keep Playwright out of the scaffold default and rely on lighter real test layers plus Docker smoke
+
+### When the prompt says only `html_css_js`
+
+Recommended default:
+
+- **HTMX + server-rendered templates**
+
+Why:
+
+- it is the most portable concrete resolution of the generic `html_css_js` label
+- it keeps validation, auth, and state transitions on the backend where many of these prompts already place them
+- it supports real partial-page interactivity without forcing a full SPA runtime
+
+Refinements:
+
+- if the backend is Spring Boot, prefer **Thymeleaf** as the concrete root
+- if the backend is Laravel and the prompt wants richer server-driven interactivity, prefer **Livewire**
+- if the prompt explicitly forbids JS enhancement, fall back to plain server-rendered templates without HTMX
+
+## Practical family selection order
+
+1. explicit framework in prompt or repo
+2. backend-coupled frontend family if the backend strongly implies one (`Thymeleaf` for Spring, `Livewire` for Laravel)
+3. `modern_frontend_framework` -> React + Vite default
+4. `html_css_js` -> HTMX + server-rendered templates default
+5. only expand beyond this matrix when the prompt explicitly names a different ecosystem

package/assets/slopmachine/scaffold-playbooks/generic-unknown-tech-guide.md

@@ -0,0 +1,136 @@
+# Generic Unknown-Tech Scaffold Guide
+
+Use this guide when a prompt names a technology, framework, or stack family that does not yet have a concrete verified playbook.
+
+## Goal
+
+Produce a safe, honest scaffold by following a repeatable search-and-selection method instead of improvising from memory.
+
+This guide is for:
+
+- frameworks we have not explicitly studied yet
+- niche stacks not yet represented in the family matrices
+- new versions or ecosystem variants that sit near, but not inside, an existing playbook
+
+## Core rule
+
+Do not invent a custom scaffold when an official or clearly de facto standard bootstrap path exists.
+
+Use the official or most widely maintained bootstrap/init path first, then adapt it only enough to satisfy the shared Docker contract and scaffold acceptance contract.
+
+## Search order
+
+When the stack is not yet covered directly:
+
+1. read `docker-shared-contract.md`
+2. resolve the nearest platform family and runtime expectations from the family matrices
+3. check Context7 for the framework/package if available
+4. if Context7 is insufficient, use targeted web research for:
+   - official docs
+   - official CLI/bootstrap command
+   - current stable version guidance
+   - official testing setup guidance
+   - official Docker or deployment guidance if published
+5. prefer official docs over blogs unless the official docs are clearly incomplete
+6. if several credible bootstrap paths exist, choose the one with:
+   - strongest official support
+   - least custom wiring
+   - easiest honest Docker baseline
+   - easiest minimal real test setup
+   - best current maintenance posture
+
+## What to extract from docs
+
+Before generating the scaffold, identify and write down:
+
+- official bootstrap/init command
+- current stable major version family to target
+- required runtime toolchain versions
+- official package manager path
+- official testing path
+- any official build/preview commands
+- any known Linux or Docker caveats
+- whether the stack expects server-rendered, SPA, mobile, desktop, or native runtime semantics
+
+## Default selection rules
+
+- follow the prompt and existing repo first
+- if the prompt names only a language or placeholder, resolve it through the family matrices first
+- if the stack is truly unknown after that, choose the nearest established family and then substitute the official bootstrap path for the new stack
+- do not silently downgrade to a different ecosystem just because it is easier
+
+## UI defaults
+
+For web UI-bearing scaffolds, unless the prompt or existing repo clearly dictates otherwise:
+
+- default CSS system: Tailwind CSS when the ecosystem supports it cleanly
+- React-family component default: `shadcn/ui`
+- Vue-family component default: a well-known `shadcn`-style Vue port when it is stable and well documented for the chosen stack; otherwise a mainstream library such as Ant Design Vue
+- Angular-family component default: Angular Material
+- server-rendered HTML family default: Tailwind CSS plus server-rendered component partials; do not force a SPA component library into a backend-owned HTML scaffold
+
+If the existing project already uses another UI system, preserve and extend that system instead of forcing these defaults.
+
+## Playwright rule
+
+- do not add Playwright to the scaffold by default just because a frontend exists
+- add Playwright only when one of these is true:
+  - the prompt explicitly requires it
+  - the selected concrete family playbook has experimentally verified it
+  - the owner intentionally chooses to absorb the extra setup cost at scaffold time
+- if Playwright is included, it must actually run in the verified scaffold; do not list it in docs or package scripts as decorative future intent
+- if Playwright is not included, keep the baseline honest and rely on unit/component/route tests plus Docker smoke until a later verification phase or later feature work justifies it
+
+## Database default rules
+
+If the prompt requires persistence and no explicit database is named:
+
+- use the database-module matrix to choose the default
+- keep database setup behind `./init_db.sh`
+- keep secrets/config out of `.env`
+- use generated runtime config in ignored paths or Docker-managed state
+
+## Docker contract application
+
+Every unknown-tech scaffold must still satisfy:
+
+- `docker compose up --build` is real and meaningful
+- containerized `./run_tests.sh` is real and meaningful
+- healthchecks/readiness are present when appropriate
+- no `.env` dependency
+- no placeholder secret literals in tracked files
+- honest README with exact runtime/test commands and proof boundary
+
+## Minimal real test floor
+
+At scaffold time, require at least:
+
+- one or more real tests for core baseline logic or rendering
+- one real build/runtime verification path in `./run_tests.sh`
+- one real smoke-level proof behind `docker compose up --build`
+
+Do not accept a scaffold that is mostly generator output with empty tests.
+
+## Documentation floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- exact Docker command
+- exact broad test command
+- main module layout
+- key toolchain/runtime assumptions
+- honesty boundaries for what the Linux/Docker baseline does and does not prove
+
+## Output for a new stack
+
+When you finish scaffolding an unknown-tech stack, capture:
+
+- the exact official bootstrap command used
+- the chosen pinned versions
+- the Docker strategy used
+- the test strategy used
+- exact commands that passed
+- whether the playbook is now experimentally verified or still only specified
+
+Then turn that into a new concrete family playbook if the stack looks likely to recur.