RadDad87 · RadDad87 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/PROJECT_BRIEF.md b/PROJECT_BRIEF.md
@@ -0,0 +1,62 @@
+# Z3R4H Project Brief
+
+## Product
+Z3R4H is a custom-branded offline survival AI interface built on Open WebUI and powered by local GGUF models through llama.cpp.
+
+## Goal
+Create a Windows-first, fully offline survival AI product that looks polished, launches simply, and uses custom Z3R4H modes and prompts.
+
+## Core Rules
+- Fully offline operation for v1
+- No cloud APIs
+- No OpenAI API dependency in product runtime
+- No telemetry
+- No login requirement for v1
+- No unnecessary frameworks or overengineering
+- Keep implementation simple, stable, and portable
+- Preserve Open WebUI where useful, but remove generic/cloud-first assumptions
+- Brand name must appear as Z3R4H
+- Interface language should emphasize:
+  - Offline Survival AI
+  - Local processing
+  - Knowledge when the grid falls
+
+## UI Direction
+- Dark tactical / premium theme
+- Custom Z3R4H branding
+- Remove generic assistant wording
+- Replace generic model language with Z3R4H mode language where appropriate
+
+## Z3R4H Modes
+- General Advisor
+- Medical Reference
+- Engineering & Repair
+- Navigation & Terrain
+- Low Power Mode
+
+## Prompt Architecture
+Each mode should eventually load:
+- core_system.txt
+- one mode-specific prompt
+- failure_behavior.txt
+
+## Runtime Architecture
+User
+→ Z3R4H-branded Open WebUI
+→ local llama.cpp server
+→ local GGUF model
+
+## Priority Order
+1. Reliable Windows launcher
+2. Open WebUI connected to local llama.cpp
+3. Z3R4H branding pass
+4. Z3R4H modes
+5. Prompt loading system
+6. Packaging and documentation
+
+## Constraints
+- Windows-first
+- Offline-first
+- Localhost-only for inference
+- No unrelated refactors
+- Keep edits narrowly scoped to the current task
diff --git a/README.md b/README.md
@@ -237,3 +237,106 @@ If you have any questions, suggestions, or need assistance, please open an issue
 ---
 
 Created by [Timothy Jaeryang Baek](https://github.com/tjbck) - Let's make Open WebUI even more amazing together! 💪
+
+## Z3R4H Windows Local Launcher (offline/localhost)
+
+For Z3R4H local development on Windows (no Docker), use `launch_z3r4h.bat` at the repo root.
+
+- Starts local `llama.cpp` server
+- Starts Open WebUI with local OpenAI-compatible backend settings
+- Waits for both services to become reachable
+- Opens Open WebUI in the default browser
+- Logs to `z3r4h_launcher.log`
+
+The launcher enforces localhost-only endpoints and uses verified Open WebUI environment variables from this codebase:
+- `ENABLE_OPENAI_API=True`
+- `OPENAI_API_BASE_URLS=http://127.0.0.1:<LLAMA_PORT>/v1`
+- `OPENAI_API_KEYS=` (empty)
+
+For Z3R4H offline/local startup, the launcher also applies:
+- `OFFLINE_MODE=True`
+- `WEBUI_AUTH=False`
+- `ENABLE_LOGIN_FORM=False`
+- `ENABLE_SIGNUP=False`
+- `ENABLE_COMMUNITY_SHARING=False`
+- `ENABLE_WEB_SEARCH=False`
+
+This reduces cloud-first/community surfaces in the Z3R4H launcher path while preserving local chat usage.
+
+Edit top variables in `launch_z3r4h.bat` before first run:
+- `LLAMA_SERVER_EXE`
+- `MODEL_PATH`
+- `LLAMA_HOST`
+- `LLAMA_PORT`
+- `OPEN_WEBUI_START_CMD`
+- `OPEN_WEBUI_URL`
+- `LOG_FILE`
+
+### Portable Package Layout (Windows)
+
+```text
+Z3R4H/
+├─ launch_z3r4h.bat
+├─ models/
+│  └─ model.gguf
+├─ runtime/
+│  └─ llama.cpp/
+│     └─ llama-server.exe
+└─ z3r4h_launcher.log   (created at runtime)
+```
+
+Launcher defaults are now relative to `%~dp0` (the launcher directory), so the package can be moved without editing absolute paths.
+
+Open WebUI startup options:
+- **External CLI mode (default):** `open-webui serve` (requires `open-webui` in PATH)
+- **Bundled runtime mode (optional):** point `OPEN_WEBUI_START_CMD` to a bundled executable path under `runtime/`
+
+Required at runtime:
+- `launch_z3r4h.bat`
+- `runtime/llama.cpp/llama-server.exe` (or equivalent configured path)
+- `models/<your-model>.gguf`
+- Local port availability for llama.cpp + Open WebUI
+- Write access for `z3r4h_launcher.log`
+
+### Z3R4H Windows-Local Verification Checklist
+
+1. Set launcher variables in `launch_z3r4h.bat` (`LLAMA_SERVER_EXE`, `MODEL_PATH`, ports/URL).
+2. Run `launch_z3r4h.bat`.
+3. Confirm launcher log shows:
+   - llama.cpp started and ready
+   - Open WebUI started and ready
+4. Confirm browser opens the configured local URL.
+5. Confirm Z3R4H Mode selector is visible in chat.
+6. Send one local prompt and verify a response is returned.
+7. Confirm offline-hardening behavior in launcher path:
+   - no login prompt
+   - community sharing disabled
+   - web search disabled
+
+### Troubleshooting (Windows Local)
+
+- **Missing llama.cpp executable/model:** verify `LLAMA_SERVER_EXE` and `MODEL_PATH`.
+- **Startup timeout:** check `z3r4h_launcher.log`, then verify port availability and local endpoint values.
+- **Open WebUI command not found:** ensure `open-webui` is installed and available in PATH.
+
+
+### Clean-Environment Launch Review (Windows)
+
+Use `Z3R4H_CLEAN_ENV_CHECKLIST.md` for a clean-machine launch/readiness pass focused on:
+- preflight requirements
+- startup validation
+- offline-hardening validation
+- hidden assumptions and launch blockers
+
+### Task 11 Validation Focus (Windows Local)
+
+For Task 11, treat this as a **validation-only** pass (no behavior changes by default):
+- run the execution-ready clean-machine flow in `Z3R4H_CLEAN_ENV_CHECKLIST.md`
+- rank blockers as P0/P1/P2 for launch-readiness decisions
+- record hidden assumptions with concrete repro evidence
+
+Highest-risk items to validate first:
+- default external `open-webui` PATH dependency
+- PowerShell readiness-probe assumptions
+- local port conflicts (11434/8080)
+- packaged model path/filename mismatch
diff --git a/TASKS.md b/TASKS.md
@@ -0,0 +1,85 @@
+# Z3R4H Tasks
+
+## Task 1 — Windows Launcher
+Create a Windows launcher that:
+- starts the local llama.cpp server
+- waits for initialization
+- opens the UI in the default browser
+- shows clear logs/errors
+- stays minimal and offline-only
+
+## Task 2 — Connect Open WebUI to local llama.cpp
+Configure Open WebUI so it works cleanly with a local llama.cpp server and local models.
+
+## Task 3 — Rebrand Open WebUI as Z3R4H
+Update visible branding:
+- Z3R4H name
+- offline survival positioning
+- remove generic cloud AI wording
+- dark tactical/premium visual identity
+
+## Task 4 — Add Z3R4H modes
+Implement visible mode choices:
+- General Advisor
+- Medical Reference
+- Engineering & Repair
+- Navigation & Terrain
+- Low Power Mode
+
+## Task 5 — Prompt system
+Implement or prepare a prompt-loading structure using:
+- core_system.txt
+- mode-specific prompt files
+- failure_behavior.txt
+
+## Task 6 — Offline hardening
+Remove or disable:
+- cloud dependencies
+- telemetry
+- login requirements for v1
+- unnecessary external integrations
+
+## Task 7 — Packaging and docs
+Prepare:
+- final folder structure
+- run instructions
+- troubleshooting notes
+- offline usage notes
+
+## Completed (Tasks 1–5)
+- Task 1 — Windows Launcher: completed in `ca715c0b` (initial launcher and local startup flow)
+- Task 2 — Local llama.cpp connection: completed in `ca715c0b` (local OpenAI-compatible routing setup)
+- Task 3 — Z3R4H rebrand pass: completed in `5b381011`
+- Task 4 — Z3R4H mode selector UI: completed in `6c0ed902`
+- Task 5 — Prompt stack binding by mode: completed in `76d6bb8a`
+
+## Completed (Task 7)
+- Added concise Windows-local run, verification, and troubleshooting guidance in `README.md`.
+- Updated progress tracking summary for packaging/readiness status in `Z3R4H_PROGRESS_SUMMARY.md`.
+
+
+## Completed (Task 9)
+- Added `Z3R4H_CLEAN_ENV_CHECKLIST.md` for clean Windows launch validation.
+- Added focused pointers in `README.md` and summary status in `Z3R4H_PROGRESS_SUMMARY.md`.
+
+## Completed (Task 10)
+- Documented portable Windows package layout and runtime requirements in `README.md`.
+- Updated launcher defaults to `%~dp0`-relative paths for portability.
+
+
+## Completed (Task 11)
+- Converted clean-environment checklist into an execution-ready Windows clean-machine validation flow.
+- Added highest-risk blocker candidates and P0/P1/P2 prioritization rules.
+- Added blocker register fields for triage evidence and release-gate decisions.
+- Kept scope documentation/review-only with no product/backend behavior changes.
+
+## Deferred (Beyond Task 11)
+- Installer generation/signing
+- CI/release automation
+- Bundled Open WebUI runtime build/distribution workflow
+
+
+## Completed (Task 8, Revised)
+- Confirmed local mode-to-model routing resolves only against runtime `model.id` values.
+- Kept routing deterministic with explicit fallback order: mode-mapped -> selected -> first-available -> none.
+- Preserved existing prompt-stack behavior (no change to prompt composition).
diff --git a/Z3R4H_CLEAN_ENV_CHECKLIST.md b/Z3R4H_CLEAN_ENV_CHECKLIST.md
@@ -0,0 +1,119 @@
+# Z3R4H Clean-Environment Validation Checklist (Windows Local)
+
+## Scope
+This checklist validates launch readiness on a clean Windows machine for the current Z3R4H build, without changing product behavior.
+
+## 1) Machine Baseline
+- Windows user profile is fresh or has no prior Open WebUI local config.
+- Terminal used: Command Prompt or PowerShell.
+- Local firewall/AV policies noted before test.
+
+## 2) Preflight Requirements
+- `launch_z3r4h.bat` exists at repo root.
+- `LLAMA_SERVER_EXE` path is valid.
+- `MODEL_PATH` path is valid.
+- Determine startup mode before launch:
+  - External CLI mode: `open-webui` command resolves in PATH.
+  - Bundled runtime mode: `OPEN_WEBUI_START_CMD` points to packaged executable.
+- Local ports configured for llama.cpp and Open WebUI are available.
+
+## 2b) Portable Layout Preflight
+- Confirm package root contains expected folders (`models/`, `runtime/llama.cpp/`).
+- Confirm launcher defaults resolve correctly from `%~dp0` after moving package to a new directory.
+- Confirm whether current build uses:
+  - external `open-webui` CLI in PATH, or
+  - bundled Open WebUI runtime command.
+
+## 3) Launcher Configuration Validation
+- Confirm top variables in `launch_z3r4h.bat`:
+  - `LLAMA_SERVER_EXE`
+  - `MODEL_PATH`
+  - `LLAMA_HOST`
+  - `LLAMA_PORT`
+  - `OPEN_WEBUI_START_CMD`
+  - `OPEN_WEBUI_URL`
+  - `LOG_FILE`
+- Confirm localhost-only settings remain unchanged.
+- Confirm offline/local hardening defaults are active.
+
+## 4) Startup Validation
+1. Run `launch_z3r4h.bat`.
+2. Verify llama.cpp server process starts.
+3. Verify Open WebUI process starts.
+4. Verify readiness polling completes for both services.
+5. Verify browser opens the local UI URL.
+6. Verify `z3r4h_launcher.log` contains startup sequence and no fatal errors.
+
+## 5) UI/Runtime Validation
+- Z3R4H branding appears in UI surfaces.
+- Z3R4H mode selector is visible.
+- One chat request returns a local response.
+- Mode-to-model routing works; fallback warning appears if mapped model is missing.
+
+## 6) Offline-Hardening Validation
+- No login prompt in launcher path.
+- Community sharing surfaces disabled.
+- Web search features disabled.
+- No cloud endpoint configuration required for baseline chat.
+
+## 7) Negative/Failure Path Checks
+- Missing `LLAMA_SERVER_EXE` -> clear error in console/log.
+- Missing `MODEL_PATH` -> clear error in console/log.
+- `open-webui` missing in PATH -> clear error in console/log.
+- Port conflict -> timeout + likely conflict guidance.
+
+## 8) Hidden Assumptions Audit
+- Hardcoded/default local paths may not match machine.
+- PATH inheritance for spawned shell may differ by setup.
+- PowerShell availability is assumed for readiness probes.
+- Localhost binding and firewall behavior can block readiness checks.
+- Runtime model list may not include mode-mapped IDs on first run.
+- localStorage state (`z3r4h_mode`, `z3r4h_mode_model_map`) may be absent/corrupt on fresh profiles.
+
+## 9) Blocker Log Template
+For each blocker, capture:
+- Severity
+- Repro steps
+- Expected vs actual result
+- Log snippet path/time
+- Candidate fix (if known)
+
+
+## 10) Task 11 Execution Flow (Clean Machine, Windows)
+1. Capture baseline: Windows version, shell (CMD/PowerShell), AV/firewall posture.
+2. Verify portable layout from launcher directory (`%~dp0`) after moving package folder.
+3. Run preflight gates: startup mode, paths, model artifact, ports, and PowerShell readiness-probe capability.
+4. Execute cold launch (`launch_z3r4h.bat`) and capture first-failure stage if unsuccessful.
+5. Validate readiness endpoints and browser open behavior; confirm startup sequence in `z3r4h_launcher.log`.
+6. Execute UI/runtime smoke checks: mode selector present + one successful local response.
+7. Execute negative-path checks: missing binary/model, missing PATH command, and port conflicts.
+8. Record blockers into ranked register and assign release-gate status (P0/P1/P2).
+
+## 11) Highest-Risk Blockers (Packaging Readiness)
+- **P0 candidate:** Default startup mode depends on `open-webui` in PATH (clean-machine failure risk).
+- **P0/P1 candidate:** Readiness probes depend on PowerShell `Invoke-WebRequest` behavior/policy.
+- **P1 candidate:** Port conflicts on `11434` (llama.cpp) or `8080` (Open WebUI) appear as startup timeout.
+- **P1 candidate:** Default model path/file (`models\model.gguf`) may not match packaged artifact name.
+- **P1/P2 candidate:** Fresh-profile localStorage state for mode routing may be absent/corrupt.
+
+## 12) Blocker Prioritization Rules
+- **P0:** Prevents clean-machine launch in the intended default package flow.
+- **P1:** Launch possible, but core local usability/hardening expectation fails.
+- **P2:** Non-blocking friction or documentation clarity issue with workaround.
+
+## 13) Blocker Register (Task 11)
+Capture each finding with:
+- ID
+- Severity (P0/P1/P2)
+- Stage (preflight/startup/runtime)
+- Repro reliability (always/intermittent)
+- Expected vs actual
+- Evidence (`z3r4h_launcher.log` timestamp + console symptom)
+- Proposed next action (doc-only, launcher change, packaging change)
+- Owner and status
+
+## 14) Deferred Beyond Task 11
+- Installer generation/signing
+- CI/release automation
+- Bundled Open WebUI runtime build/distribution workflow
+- Product/backend behavior changes unless a verified P0 requires escalation