theslopmachine 0.6.2 → 0.7.1

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

@@ -0,0 +1,265 @@
+# Laravel Livewire Default Scaffold Playbook
+
+Use this playbook when the prompt explicitly asks for a Laravel Livewire baseline and does not need product-specific feature work.
+
+This playbook follows the shared Docker contract in:
+
+- `/Users/yohannesakd/code/eaglepoint/demonstration/slopmachine-0.3/assets/slopmachine/scaffold-playbooks/docker-shared-contract.md`
+
+## Goal
+
+Ship a concrete Laravel Livewire baseline that is:
+
+- bootstrapped from the official Laravel path
+- upgraded with a real Livewire package install
+- Docker-first
+- Tailwind-preferred without pretending a richer design system exists
+- safe by default
+- wired to a real database path without `.env`
+- verified with real Livewire page/component tests inside containers
+- limited to baseline infrastructure only
+
+Verified lab:
+
+- `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline`
+
+## Official bootstrap path
+
+Use the official Composer create-project flow, then install Livewire in the created app:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab:/workspace" -w /workspace composer:2.8 create-project --prefer-dist laravel/laravel="^12.0" livewire-baseline
+
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app composer:2.8 require livewire/livewire
+```
+
+Observed bootstrap result for the verified lab:
+
+- `laravel/laravel v12.12.2`
+- `laravel/framework v12.56.0`
+- `livewire/livewire v4.2.4`
+- `phpunit/phpunit v11.5.55`
+
+## Safe pinned defaults
+
+- Docker runtime image: `php:8.4-cli-bookworm`
+- Node asset build image: `node:22-bookworm-slim`
+- Composer image: `composer:2.8`
+- Laravel skeleton: `laravel/laravel v12.12.2`
+- lockfile-pinned Livewire package: `livewire/livewire v4.2.4`
+- lockfile-pinned test runner: `phpunit/phpunit v11.5.55`
+- database default: SQLite file in a Docker-managed volume
+- frontend styling default: Tailwind via Vite build during image creation
+
+The lockfiles are the real dependency pins. Keep them committed.
+
+## No-`.env` rule
+
+- do not commit `.env`
+- do not require users to create `.env` before startup
+- point Laravel at a committed empty environment stub instead of `.env`
+- load runtime app/database values from a generated runtime config file in a Docker-managed volume
+
+Verified lab pattern:
+
+- `bootstrap/runtime-environment.stub` is the environment file Laravel loads
+- `bootstrap/runtime-config.php` loads JSON from `APP_CONFIG_PATH`
+- `scripts/bootstrap_runtime.sh` generates the JSON config and SQLite path
+
+## Livewire baseline pattern
+
+- use a full-page Livewire component as the baseline surface
+- use `Route::livewire('/', App\Livewire\ShoppingListPage::class)` for the root page
+- provide a real layout with `@vite`, `@livewireStyles`, and `@livewireScripts`
+- keep the UI honest: Tailwind-styled baseline only, not a product-grade feature set
+- back the component with one real persistence path so Livewire behavior and DB wiring are both proven
+
+Verified lab surface:
+
+- `GET /health`
+- `GET /`
+
+Verified lab component flow:
+
+- add an item from the full-page Livewire form
+- persist it into SQLite
+- rerender the saved list
+
+## Runtime contract
+
+Required commands:
+
+- `docker compose up --build`
+- `./run_tests.sh`
+
+Both commands are real in the verified lab.
+
+## Docker / Compose pattern
+
+- use `compose.yaml`
+- one app service published to loopback only with a random host port
+- one tester service behind a `test` profile
+- named volume for runtime state
+- healthcheck against `/health`
+- same application image for runtime and tests
+- multi-stage Dockerfile: Composer dependency stage, Node/Tailwind asset stage, PHP runtime stage
+
+Verified lab details:
+
+- detached verification host bind: `127.0.0.1:32800->8000`
+- interactive verification host bind: `127.0.0.1:32801->8000`
+
+## Tailwind stance
+
+- Tailwind is preferred and used here
+- build Tailwind assets ahead of runtime with Vite
+- do not pretend there is a live Vite dev-server contract when the Docker baseline serves built assets from `public/build`
+
+Verified lab files:
+
+- `resources/css/app.css`
+- `resources/views/layouts/app.blade.php`
+- `resources/views/livewire/shopping-list-page.blade.php`
+
+## Testing baseline
+
+Minimum real Livewire/Laravel test floor:
+
+- one unit test that proves runtime config defaults select SQLite without `.env`
+- one feature test for health/database readiness
+- one page-render test that proves the root Livewire page responds and includes Livewire markup
+- one Livewire component test that mutates state, saves data, and proves persistence
+- containerized `./run_tests.sh` that performs HTTP smoke checks plus `php artisan test`
+
+Verified lab test files:
+
+- `tests/Unit/RuntimeConfigTest.php`
+- `tests/Feature/LivewireBaselineTest.php`
+- `tests/Feature/ShoppingListPageTest.php`
+
+Verified lab test result:
+
+- `4 passed (13 assertions)`
+
+## README requirements
+
+The README must honestly state:
+
+- this is a baseline, not a feature app
+- exact stack and pins used
+- exact runtime command: `docker compose up --build`
+- exact broad test command: `./run_tests.sh`
+- no `.env` requirement
+- safe database/config pattern
+- Tailwind/Vite build boundary
+- what is intentionally excluded
+- exact verification commands and observed results
+
+## Commands actually run for the verified lab
+
+All commands below were executed in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline` unless otherwise noted.
+
+Bootstrap and dependency commands:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab:/workspace" -w /workspace composer:2.8 create-project --prefer-dist laravel/laravel="^12.0" livewire-baseline
+
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app composer:2.8 require livewire/livewire
+
+docker run --rm -u "$(id -u):$(id -g)" -e npm_config_cache=/app/.npm-cache -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app node:22-bookworm-slim npm install
+```
+
+Verification commands:
+
+```bash
+docker compose config
+
+docker compose up --build -d
+
+docker compose ps
+
+docker compose port app 8000
+
+curl -fsS "http://127.0.0.1:32800/health"
+
+python3 - <<'PY'
+from urllib.request import urlopen
+html = urlopen('http://127.0.0.1:32800/', timeout=10).read().decode()
+print('title=', 'Livewire baseline' in html)
+print('snapshot=', 'wire:snapshot' in html)
+print('saved_items=', 'Saved items' in html)
+PY
+
+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/livewire-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+last_error = None
+try:
+    deadline = time.time() + 240
+    while time.time() < deadline:
+        try:
+            port_line = subprocess.check_output(["docker", "compose", "port", "app", "8000"], cwd=cwd, text=True).strip()
+            if not port_line:
+                raise RuntimeError("port not published yet")
+            port = port_line.rsplit(":", 1)[-1]
+            with urlopen(f"http://127.0.0.1:{port}/health", timeout=3) as response:
+                health_body = response.read().decode()
+            root_html = urlopen(f"http://127.0.0.1:{port}/", timeout=3).read().decode()
+            if 'Livewire baseline' in root_html and 'wire:snapshot' in root_html:
+                print(f"interactive docker compose up --build reached /health and / on port {port}")
+                print(health_body)
+                break
+            raise RuntimeError("root page missing Livewire markers")
+        except Exception as exc:
+            last_error = exc
+            time.sleep(2)
+    else:
+        raise RuntimeError(f"interactive compose never became ready: {last_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", "--volumes", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+## Observed results
+
+- `docker compose config` resolved cleanly
+- `docker compose up --build -d` started the app and `docker compose port app 8000` returned `127.0.0.1:32800`
+- `docker compose ps` reported `Up ... (healthy)`
+- `curl -fsS "http://127.0.0.1:32800/health"` returned `{"status":"ok","database":"ready"}`
+- the root page marker script printed `title= True`, `snapshot= True`, and `saved_items= True`
+- `./run_tests.sh` passed and ended with `4 passed (13 assertions)`
+- the interactive `docker compose up --build` path reached both `/health` and `/` successfully and printed `interactive docker compose up --build reached /health and / on port 32801`
+
+## Acceptance checklist
+
+Baseline is acceptable when:
+
+- official Laravel bootstrap path is used
+- Livewire is installed for real and pinned by lockfile
+- Tailwind is used honestly as the default styling layer
+- runtime does not rely on `.env`
+- database defaults are safe and real
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- minimal real Livewire page/component tests are present and passing
+- README is honest about included versus excluded scope
+- the lab stops at baseline infrastructure
+
+## Experimental verification status
+
+Yes. This playbook is based on an experimentally verified lab, not a hypothetical template.

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

@@ -0,0 +1,130 @@
+# Overlay / Module Matrix for Scaffold Composition
+
+Use this after selecting the scaffold root playbook. The root establishes the primary runtime and honest baseline contract; overlays add predictable non-root capabilities that recur across many prompts.
+
+## Core rule
+
+- **scaffold root:** the minimum stack needed to boot, run, test, and explain the chosen platform honestly
+- **overlay module:** a repeatable capability that is common enough to standardize but not universal enough to force into every root
+- **later prompt-specific development:** product/domain behavior, provider-specific integrations, and feature depth that depends on the actual app brief
+
+## Root vs overlay vs later work
+
+| Concern | Put in scaffold root when | Put in overlay when | Defer to later prompt-specific work when |
+| --- | --- | --- | --- |
+| Runtime/framework | it defines how the app starts and is built | almost never | never |
+| Minimal testing | one real test path is required for honesty | extra test layers are requested or predictably valuable | the test only exists for a future feature |
+| Config/secrets | the app cannot start safely without it | advanced secret/auth/policy layers are needed | provider-specific secret rotation or cloud policy details are unknown |
+| Logging/validation | tiny baseline wiring is obviously required by the stack | structured, reusable cross-cutting policy is needed | domain-specific rules and business validations are not known yet |
+| UI system | only a tiny shell/layout needed to prove the frontend runs | reusable design system, theme, component primitives, or form layer are wanted | product-specific screens and workflows are not yet defined |
+| Database | a minimal persistence path is required to prove the backend honestly | network DB, ORM, migrations, cache, or multi-service persistence is needed | schema-heavy product models are not yet known |
+| Jobs/search/export/reporting | rarely | when the prompt already implies platform support for them | when reports, indexes, or jobs depend on product logic not yet defined |
+
+## Overlay matrix
+
+| Overlay family | Typical module contents | Apply to | Keep out of root by default because |
+| --- | --- | --- | --- |
+| Testing overlays | browser E2E harness, API integration test container, contract-test wiring, visual regression setup | frontend, backend, fullstack, mobile, desktop | roots only need one honest baseline test path; deeper test stacks are optional cost |
+| Auth / security / config overlays | session/JWT wiring, user model stub, RBAC shell, CORS/CSRF/rate-limit policy, secret-file/config loader, secure cookie defaults | backend, fullstack, frontend shells with protected routes | many scaffolds do not need auth yet, and provider choice is often prompt-specific |
+| Logging / validation overlays | structured logger, request IDs, error envelope, schema validation, input parsing, shared DTO/schema package | backend, fullstack, API-heavy frontend | baseline roots can survive with light defaults; standardized policy is reusable but not universal |
+| UI system overlays | design tokens, theme switch, component primitives, layout shell, form helpers, icon setup, toast/notification shell | frontend, fullstack, desktop, some mobile | not every scaffold needs a reusable design system on day one |
+| Database overlays | Postgres/MySQL service, ORM module, migrations tool, seed path, DB admin helper, cache/Redis sidecar when persistence model requires it | backend, fullstack | some roots only need a very small default persistence story; network DB choice should stay modular |
+| Queue / job / scheduler overlays | worker service, queue broker, retry policy, cron/scheduler entrypoint, job health metrics | backend, fullstack | background processing is expensive to add and often unused in simple scaffolds |
+| Search / export / reporting overlays | search engine service stub, export pipeline shell, report generation worker, storage/export directory contract | backend, fullstack, admin-heavy frontend/fullstack | these usually depend on real domain models, so only scaffold them when the prompt already signals the need |
+
+## Reusable overlay guidance by category
+
+### Testing overlays
+
+- keep **one real baseline test path in the root**
+- add overlays for:
+  - browser E2E
+  - API integration/container tests
+  - contract testing
+  - visual regression or snapshot systems
+- do **not** pre-add heavyweight E2E browsers to every root
+
+### Auth / security / config overlays
+
+- keep **safe config loading and no-secret defaults in the root**
+- use overlays for:
+  - local auth stub or session/JWT baseline
+  - RBAC/permission shell
+  - hardened API security middleware
+  - provider-ready secret/config abstraction
+- defer:
+  - OAuth provider specifics
+  - enterprise SSO details
+  - tenant-specific policy logic
+
+### Logging / validation overlays
+
+- root may include very light logging/validation when the framework already exposes it naturally
+- overlay should standardize:
+  - structured logs
+  - correlation/request IDs
+  - shared validation schemas
+  - normalized error responses
+- defer domain validation rules that depend on real business entities
+
+### UI system overlays
+
+- root should only prove the frontend can render and be tested
+- overlay is the right place for:
+  - theme tokens
+  - reusable components
+  - navigation shell
+  - form system
+  - notification primitives
+- defer product screens, dashboards, and specialized flows
+
+### Database overlays
+
+- **yes, database modules belong in this matrix** when they are a reusable composition choice beyond the minimal root persistence story
+- keep in root:
+  - only the smallest honest persistence needed for the selected backend/fullstack scaffold
+- use overlay for:
+  - network DB service selection
+  - ORM/migrations package
+  - seed/reset helpers
+  - caching sidecars closely tied to persistence shape
+- defer schema-rich domain modeling and app-specific query logic
+
+### Queue / job / scheduler overlays
+
+- add only when the prompt already implies async work, scheduled work, ingestion, notifications, or heavy exports
+- overlay should own:
+  - separate worker runtime
+  - queue/broker service
+  - retry/dead-letter defaults
+  - scheduler entrypoint
+- defer actual business jobs until features are defined
+
+### Search / export / reporting overlays
+
+- include at scaffold time only when these are clearly part of the platform ask, such as admin/reporting systems, catalog/search products, or export-heavy back offices
+- overlay may establish:
+  - search service wiring
+  - export job shell
+  - report generation/storage contracts
+- defer report definitions, search ranking rules, and domain-specific exports
+
+## Composition examples
+
+| Composition | When it fits | Notes |
+| --- | --- | --- |
+| frontend root + UI system overlay + testing overlay | product asks for a polished web UI but feature scope is still open | keep domain pages out; ship reusable shell and stronger frontend verification |
+| backend root + database overlay + logging/validation overlay | API scaffold needs production-shaped persistence and cross-cutting API quality | root proves API baseline; overlays add Postgres/ORM/migrations plus structured request handling |
+| frontend root + backend root + database overlay + auth overlay | fullstack app with real accounts and persistent data | roots define separate runtime surfaces; overlays add shared auth and stronger persistence |
+| frontend root + backend root + database overlay + queue overlay + reporting overlay | admin/back-office or workflow app with async exports/reports | only do this when the prompt already signals jobs/reports early |
+| mobile/desktop root + backend root + auth overlay + logging/validation overlay | client app depends on API-backed identity and reusable service policy | keep platform runtime separate; centralize auth/API policy in overlays |
+
+## Decision shortcuts
+
+- if the item is required for **every** app of that root family to start honestly, keep it in the root
+- if the item is **common but optional** across many apps, make it an overlay
+- if the item depends on domain nouns, product workflows, or provider selection not yet in evidence, defer it to later development
+
+## Practical stop rule
+
+After root selection, layer only the overlays already justified by the prompt or clearly implied platform category. Stop before product-specific implementation begins.

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

@@ -0,0 +1,79 @@
+# Platform Family Scaffold Matrix
+
+Use this matrix to choose a real scaffold family for Android, iOS, and desktop requests.
+Do **not** collapse these into one generic `mobile` or `desktop` bucket: the bootstrap path, Linux-proof boundary, and wrapper-script meaning differ too much across families.
+
+## Family selection rule
+
+1. follow the prompt and existing repo first
+2. choose a concrete family, not a generic platform bucket
+3. apply that family's official/bootstrap path and proof boundary honestly
+4. keep `docker compose up --build` and `./run_tests.sh` real for every family
+5. treat `./run_app.sh` as an optional helper only
+
+## Current defaults vs backlog
+
+- **current default families**
+  - `android-java-views`
+  - `ios-expo-react-native`
+  - `desktop-electron-vite`
+- **current opt-in families when the prompt or repo clearly requires them**
+  - `android-kotlin-views`
+  - `ios-native-swift` → see [`ios-native-swift.md`](./ios-native-swift.md)
+- **current non-default families with a concrete playbook**
+  - `android-kotlin-compose` → see [`android-kotlin-compose.md`](./android-kotlin-compose.md)
+  - `ios-native-objective-c` → see [`ios-native-objective-c.md`](./ios-native-objective-c.md)
+- **future / non-default backlog families**
+  - none
+
+## Android families
+
+| Family | Use when | Official/bootstrap/init path | Safe default versions/config direction | What `docker compose up --build` means | What `./run_tests.sh` means | `./run_app.sh` helpful? | Honest Linux proof | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `android-java-views` | prompt says native Android and does not require Kotlin or Compose | official Android Studio phone/tablet **Empty Views Activity** in **Java**; for automation, commit the equivalent Gradle/AGP skeleton rather than pretending there is a stable non-interactive official CLI | AGP `8.5.x`, Gradle `8.7`, Java `17`, `compileSdk = 34`, `targetSdk = 34`, `minSdk = 29`, XML Views | containerized Gradle build path that at least lints and assembles a debug APK or equivalent artifact; no emulator claims | containerized lint + assemble + JVM/Robolectric tests + schema verification when Room exists | **yes**; useful to normalize `JAVA_HOME` / `ANDROID_HOME`, build a debug APK, and optionally install via `adb` when available | a real APK/debug artifact is produced and JVM tests pass on Linux; no device/emulator proof claimed | **current default, experimentally verified** |
+| `android-kotlin-views` | prompt or repo explicitly requires Kotlin but not Compose | official Android Studio **Empty Views Activity** in **Kotlin** | same Android baseline as Java Views, but pin one AGP-compatible Kotlin plugin version and keep XML Views unless prompt says otherwise | same containerized assemble/lint artifact path as Java Views | same broad path as Java Views, but using Kotlin sources | **yes**; same value as Java family | Kotlin Android app assembles on Linux and passes JVM/Robolectric proof without pretending emulator coverage | **current opt-in** |
+| `android-kotlin-compose` | prompt explicitly requires Compose or existing repo already uses Compose | official Android Studio **Empty Activity** / Compose-first app template in **Kotlin** | keep AGP `8.5.x`, Gradle `8.7`, Java `17`, SDK levels aligned with other Android families; pin one AGP-compatible Kotlin version and one tested stable Compose BOM; keep Material 3 defaults | containerized Compose-capable build path that assembles the app and emits the artifact; do not pretend `docker compose` proves interactive device UX | lint + assemble + JVM/unit coverage that is honest on Linux; only include instrumentation/device checks when a real device/emulator path exists outside the portable baseline | **yes**; useful for local build/install convenience | Compose code now assembles on Linux, `docker compose up --build` reaches artifact-serving healthy state, and containerized lint/JVM tests pass; still no emulator/device proof | **current opt-in, experimentally verified** |
+
+## iOS families
+
+| Family | Use when | Official/bootstrap/init path | Safe default versions/config direction | What `docker compose up --build` means | What `./run_tests.sh` means | `./run_app.sh` helpful? | Honest Linux proof | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `ios-expo-react-native` | work is iOS-targeted but running from Linux, and the prompt does not require a native-only iOS codebase | `npx create-expo-app@latest <app> --template blank-typescript` | Expo-managed workflow, TypeScript, current stable Expo SDK, Jest, React Native Testing Library; keep native modules minimal until a real native requirement exists | containerized Expo-oriented baseline such as dependency install plus Expo dev-server startup and/or `expo export --platform ios`; this proves shared RN wiring, not native iOS runtime | `tsc --noEmit`, `jest --runInBand`, and `expo export --platform ios` or equivalent portable iOS build-shape checks | **yes**; useful to wrap `npx expo start` and print the closest device-adjacent flow | shared JS/TS code, tests, and iOS-targeted Expo export pass on Linux; no Xcode, CocoaPods, simulator, signing, or archive proof claimed | **current default on Linux** |
+| `ios-native-swift` | prompt explicitly requires native Swift iOS or repo already is a native Swift iOS app | official Xcode **App** template in **Swift**; UIKit vs SwiftUI follows prompt/repo; detailed rules live in [`ios-native-swift.md`](./ios-native-swift.md) | treat Xcode/iOS SDK selection as a macOS checkpoint; on Linux, only portable SwiftPM/shared-module defaults may be pinned and tested honestly | on Linux, this means a real **partial-proof** container path: portable SwiftPM build/test when such modules exist, plus static repo-shape validation; it must **not** claim `.app`, simulator, or archive proof | portable Swift package tests, build/lint when available, and static validation only; if there are no portable modules, the script must say native proof requires macOS/Xcode rather than faking success | **usually no** on Linux; only add it if it cleanly hands off to a documented macOS/Xcode flow | shared SwiftPM modules and static Xcode-shape validation are experimentally verified on Linux; the actual iOS app target remains unproven until a real macOS/Xcode checkpoint | **current opt-in, experimentally verified partial-proof** |
+| `ios-native-objective-c` | prompt explicitly requires native Objective-C iOS or repo already is Objective-C | official Xcode **App** template in **Objective-C**; detailed Linux-boundary rules live in [`ios-native-objective-c.md`](./ios-native-objective-c.md) | same macOS/Xcode dependency as native Swift; do not invent a Linux-first default beyond portable shared modules if they exist | on Linux, this means a real verification/support container for static checks and any portable modules only; never pretend it builds or runs the native iOS app | static validation plus any portable shared-module tests only; if there are no portable modules, keep this as a real static gate rather than fake native success | **usually no** on Linux; only add it when it is an honest macOS/Xcode handoff helper | static Xcode-project validation is experimentally verified on Linux; native iOS app proof is still blocked on macOS/Xcode | **current explicit opt-in, experimentally verified partial-proof** |
+
+### iOS honesty boundary
+
+For native Swift and Objective-C families, Linux is a **partial-proof** environment only.
+Honest proof on Linux does **not** include Xcode build success, CocoaPods integration quality, simulator behavior, signing, archives, or App Store readiness.
+
+## Desktop families
+
+| Family | Use when | Official/bootstrap/init path | Safe default versions/config direction | What `docker compose up --build` means | What `./run_tests.sh` means | `./run_app.sh` helpful? | Honest Linux proof | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `desktop-electron-vite` | prompt says desktop app and does not require another desktop shell | `npm create @quick-start/electron@latest <app> -- --template vanilla-ts`, then harden/pin the generated baseline | Electron + Vite + TypeScript, repo-tested pinned versions, `contextIsolation` on, no unnecessary `nodeIntegration`, explicit preload bridge, Linux packaging kept to `electron-builder --linux dir` at scaffold time | containerized build/package/smoke gate: install deps, build renderer/main, create unpacked Linux output, and run one headless smoke under Xvfb/Playwright or equivalent | unit/renderer/main tests plus the headless Electron smoke/build check | **yes**; useful for host-side launch convenience | an unpacked Linux Electron build launches a real window process headlessly and passes smoke/build checks | **current default, experimentally verified** |
+| `desktop-tauri` | prompt explicitly requires Tauri, Rust footprint, or existing repo already uses Tauri | official Tauri bootstrap such as `npm create tauri-app@latest <app>` | Tauri `2.x`, Rust stable, TS frontend by default, Linux WebView/runtime dependencies documented explicitly; do not default to Tauri when prompt is open | containerized Rust + frontend build path that emits a Linux binary/bundle when dependencies permit; keep claims limited to what the container actually proves | `cargo test` plus frontend tests and static checks such as clippy/typecheck as appropriate | **yes** when host Rust/WebView deps are present | Linux now proves a Tauri build/bundle/startup baseline honestly through Docker, but this remains an explicit opt-in family rather than the generic default | **current non-default, experimentally verified** |
+
+## Wrapper meaning by family
+
+- `docker compose up --build`
+  - always means a **real** containerized baseline path
+  - for Android: build/lint/test/artifact proof without pretending emulator runtime
+  - for Expo iOS on Linux: shared-code/runtime-export proof without pretending Xcode proof
+  - for native iOS families: only partial Linux proof; for Swift, follow [`ios-native-swift.md`](./ios-native-swift.md) and do not choose it as a default; for Objective-C, follow [`ios-native-objective-c.md`](./ios-native-objective-c.md) and keep it explicit opt-in only
+  - for desktop: build/package/headless-smoke proof rather than pretending a container is the final end-user desktop runtime
+- `./run_tests.sh`
+  - always means the broad portable verification path
+  - should be the command an owner can run on a clean Linux machine with Docker
+  - must never silently downgrade into `NO-SOURCE`, placeholder, or documentation-only success
+- `./run_app.sh`
+  - useful for Android, Expo, Electron, and often Tauri
+  - usually **not** useful for native iOS-on-Linux families unless it is explicitly a macOS/Xcode handoff helper
+  - never replaces the Docker baseline contract
+
+## Decision summary
+
+- when the prompt says **Android**, split into `android-java-views`, `android-kotlin-views`, or `android-kotlin-compose` instead of one generic native-mobile bucket
+- when the prompt says **iOS on Linux**, default to `ios-expo-react-native`; only choose native Swift or Objective-C families when the prompt explicitly requires them and the proof boundary is documented honestly; both native families now have experimentally verified partial-proof Linux baselines
+- when the prompt says **desktop**, default to `desktop-electron-vite`; treat Tauri as explicit opt-in, and currently only partial-lab-state rather than fully verified
+- if a family cannot produce honest Linux proof for the requested baseline, keep it out of the default path and label it backlog or exception-driven

package/assets/slopmachine/scaffold-playbooks/selection-matrix.md

@@ -0,0 +1,72 @@
+# Scaffold Playbook Selection Matrix
+
+Use this as owner-side reference when composing the scaffold request.
+
+## Selection order
+
+1. follow the original prompt and existing repo first
+2. read `docker-shared-contract.md`
+3. if the stack is not directly covered, read `generic-unknown-tech-guide.md`
+4. choose the primary platform family using `platform-family-matrix.md`
+5. choose the frontend family using `frontend-family-matrix.md` when a frontend surface exists
+6. choose the backend family and database module using `backend-family-matrix.md` and `database-module-matrix.md` when a backend surface exists
+7. choose the matching concrete scaffold playbook for the selected family default
+8. add any scaffold-time overlays from `overlay-module-matrix.md`
+9. choose the framework bootstrap path that best matches the prompt
+10. restate the relevant directives in the developer prompt instead of passing external file paths
+
+## Shared references
+
+- shared Docker contract:
+  - `docker-shared-contract.md`
+- generic fallback guide:
+  - `generic-unknown-tech-guide.md`
+- family matrices:
+  - `frontend-family-matrix.md`
+  - `backend-family-matrix.md`
+  - `database-module-matrix.md`
+  - `platform-family-matrix.md`
+  - `overlay-module-matrix.md`
+
+## Primary playbooks
+
+- open-ended web product with no narrower family already selected:
+  - `web-default.md`
+  - for explicit frontend families, prefer `frontend-baseline.md`, `vue-vite-default.md`, or `angular-default.md` as appropriate
+  - for explicit backend families, prefer `backend-baseline.md`, `fastapi-default.md`, `spring-boot-default.md`, `django-default.md`, `laravel-default.md`, or `go-chi-default.md` as appropriate
+  - for explicit Laravel server-driven UI work, prefer `livewire-default.md`
+- native Android request:
+  - `android-native-java.md` (current experimentally verified default)
+  - `android-kotlin-views.md` when the prompt explicitly requires Kotlin + Views
+  - `android-kotlin-compose.md` when the prompt explicitly requires Compose; now experimentally verified
+  - if the prompt explicitly requires Kotlin or Compose, keep the Android runtime/test contract but adapt the language/UI defaults accordingly
+- cross-platform mobile request with no native-only requirement:
+  - `expo-react-native-default.md`
+- desktop app request:
+  - `electron-vite-default.md` (current experimentally verified default)
+  - `tauri-default.md` only when the prompt explicitly requires Tauri; experimentally verified but still explicit opt-in only
+- iOS-targeted work on Linux:
+  - `ios-linux-portable.md`
+  - if the prompt explicitly requires native Swift, use `ios-native-swift.md` (experimentally verified partial-proof baseline)
+  - if the prompt explicitly requires native Objective-C, use `ios-native-objective-c.md` (experimentally verified partial-proof baseline)
+
+## Framework bootstrap guidance
+
+- when the prompt explicitly names a framework with a strong official starter, use that framework's official or best-known bootstrap path and then apply the matching playbook contract
+- examples:
+  - Next.js, Nuxt, Laravel, Rails, Django, Expo, Electron
+- when the prompt names only a language or only a placeholder label, resolve that through the corresponding family matrix before picking a bootstrap command
+- when the prompt leaves the framework open, use the safest package default for that platform family rather than inventing a custom starter
+
+## Runtime contract reminders
+
+- web always requires working `docker compose up --build`
+- web always requires containerized `./run_tests.sh`
+- Android, mobile, iOS, and desktop projects also require working `docker compose up --build` plus containerized `./run_tests.sh`
+- for non-web app platforms, the Docker runtime command may start a meaningful build, artifact, preview, or support environment rather than pretending to be native runtime proof
+- `./run_app.sh` may still exist for non-web local convenience, but it does not replace the Docker-based baseline contract
+
+## Scaffold stop rule
+
+Stop scaffold once the baseline stack, required technologies, runtime contract, wrapper scripts, minimal real tests, and honest README are in place.
+Do not start prompt-specific feature implementation during scaffold unless the runtime baseline genuinely depends on it.