Merge pull request #7 from RadDad87/codex/propose-plan-for-windows-launcher-implementation-9ldchg

Z3R4H: Windows offline launcher, wrapper scaffold, geo services, UI rebrand & prompt stack

Author: RadDad87

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

README.md

@@ -237,3 +237,267 @@ 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` (default package expectation: `runtime/llama.cpp/llama-server.exe` and `models/model.gguf`).
+- **Open WebUI startup mode issue:**
+  - `OPEN_WEBUI_START_MODE=external` requires `open-webui` in PATH
+  - `OPEN_WEBUI_START_MODE=bundled` requires valid `OPEN_WEBUI_BUNDLED_EXE`
+- **Port conflict before startup:** launcher now fails fast if `LLAMA_PORT` or WebUI port is already listening.
+- **Readiness probe unavailable/blocked:** verify PowerShell policy or curl availability on Windows.
+- **Startup timeout:** check `z3r4h_launcher.log`, then verify firewall and localhost reachability.
+
+
+### 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
+
+
+### Task 12 Blocker-Fix Focus (Windows Local)
+
+Task 12 hardens clean-machine startup by improving launcher preflight clarity and failure diagnostics only (no product/backend feature expansion):
+- explicit Open WebUI startup-mode branching (external vs bundled)
+- readiness-probe fallback diagnostics
+- model-path contract clarity
+- fail-fast local port conflict checks
+
+
+### Task 13 Release-Candidate Checklist (Windows Portable Package)
+
+Use this RC gate before any installer/wrapper work:
+1. Scope and intent confirmed (documentation/readiness-only gate).
+2. Package manifest complete (launcher/runtime/model artifacts present).
+3. Runtime prerequisites confirmed on clean Windows machine.
+4. Preflight checks pass (startup mode, paths, ports, log write access).
+5. Cold launch validation passes (llama + Open WebUI ready).
+6. Operator smoke checks pass (UI opens, one local response).
+7. No unresolved P0/P1 blockers in checklist blocker register.
+8. Evidence captured and signoff recorded.
+
+
+### Task 14 Validation Execution Support (Windows Local)
+
+For clean-machine RC execution, run validation in this exact order:
+1. Session header capture (operator/date/machine/build).
+2. Package manifest verification.
+3. Runtime prerequisite verification.
+4. Launcher preflight checks (mode/paths/ports/log write).
+5. Cold launch execution and readiness confirmation.
+6. Operator smoke check (UI opens + one local prompt/response).
+7. Blocker classification (P0/P1/P2) and disposition.
+8. RC signoff decision with evidence pack attached.
+
+Use `Z3R4H_CLEAN_ENV_CHECKLIST.md` as the source of truth for pass/fail recording.
+
+
+### Task 15 RC Run Result Capture (Windows Local)
+
+After executing validation, record outcomes using the Task 15 run-result template in `Z3R4H_CLEAN_ENV_CHECKLIST.md`:
+- per-step pass/fail/blocked status
+- evidence references per step
+- blocker rollup (P0/P1/P2)
+- final release recommendation (`GO`, `GO-WITH-RISK`, `NO-GO`)
+
+
+### Task 16 v1 Shipping Format Decision (Windows)
+
+Compared options for v1:
+1. Portable BAT-launched package (current baseline)
+2. Wrapped desktop `.exe` / shell approach (intended v1 target)
+
+**v1 Recommendation:** Ship with the wrapped desktop `.exe` / shell approach as the primary operator entry point.
+
+Rationale for .exe-first:
+- improves operator-first launch experience by reducing manual launcher handling
+- provides a clearer product-like entry path for v1 distribution
+- reduces perceived complexity for first-time Windows operators
+
+BAT path role during transition:
+- retain BAT launch flow as controlled fallback while exe-first gates are validated
+- do not position BAT as primary v1 operator experience
+
+Exe-first gating conditions before release decision:
+- repeated RC runs show no unresolved P0 launch blockers in exe-first flow
+- failure diagnostics remain operator-visible and supportable
+- portability expectations are preserved for packaged runtime/model assets
+- support burden is acceptable versus BAT baseline in pilot validation
+
+
+### Task 17 .exe Wrapper Implementation Plan (v1 Path)
+
+Task 17 defines the implementation plan only (no wrapper code yet):
+- wrapper technology options and recommendation
+- runtime startup orchestration sequence
+- diagnostics/logging expectations
+- BAT launcher fallback/support role
+
+v1 intended entrypoint remains `.exe` / shell wrapper, with BAT preserved as fallback/support.
+
+
+### Task 18 Concrete .exe Wrapper Implementation Plan (Build-Ready)
+
+Task 18 adds the build-ready implementation plan for the `.exe` wrapper path (planning only, no code):
+- recommended wrapper technology
+- concrete wrapper project layout
+- startup orchestration and readiness sequence
+- logging/error-handling model
+- BAT fallback/support path expectations
+
+For v1, `.exe` remains the intended primary entrypoint; BAT remains fallback/support only.
+
+
+### Task 19 Minimal Wrapper Scaffold (Implemented)
+
+Added initial native C#/.NET wrapper scaffold under `wrapper/` for `.exe`-first v1 path:
+- project structure and entrypoint
+- config/path resolution scaffold
+- orchestration/readiness/logging stubs
+- BAT fallback hook scaffold
+
+No full runtime orchestration, installer, or build automation was implemented in this task.
+
+
+### Task 20 First Working Wrapper Milestone
+
+The wrapper now provides a first working milestone for `.exe`-first path by delivering:
+- config/path validation
+- structured logging and error categories
+- structured exit codes
+- BAT fallback invocation path (`auto`/`always`/`never`)
+
+Full runtime orchestration/readiness/browser launch remain intentionally deferred.
+
+
+### Task 21 First Live Llama Orchestration Milestone
+
+Wrapper now performs first live orchestration by launching llama and validating llama readiness.
+This milestone still does **not** start Open WebUI or launch a browser.
+BAT fallback remains the support/recovery path.
+
+
+### Task 22 Open WebUI + Dual-Service Readiness Milestone
+
+Wrapper now supports dual-service startup readiness:
+1) launch/validate llama
+2) launch/validate Open WebUI
+
+This milestone still excludes browser launch and advanced supervision.
+
+
+### Task 23 Browser Launch on Dual-Service Readiness
+
+Wrapper now opens the configured local Open WebUI URL in the default browser
+only after both llama and Open WebUI readiness checks pass.
+
+Fallback behavior remains unchanged for earlier startup failures (`auto` / `always` / `never`).
+Browser-launch-only failures are returned as structured wrapper outcomes.
+
+
+### Task 24 Wrapper-First RC Validation Execution Support
+
+RC validation workflow now explicitly treats the wrapper entrypoint as the
+primary clean-machine validation path for `.exe`-first shipping.
+
+Validation guidance now records:
+- wrapper stage-by-stage outcomes (config, llama, webui, browser-launch)
+- wrapper exit code + terminal stage
+- BAT fallback evidence only when wrapper failure triggers support handoff
+
+
+### Task 25 Package-Root Resolution Blocker Fix
+
+Wrapper default package-root detection was corrected for published RC layout so it no longer collapses to `C:\\`.
+Resolved runtime and fallback paths are now anchored to the detected package root and logged at startup.