# PROJECT MANDATE: PROC-GENERATOR (Mundane Realms)

## 1. THE STACK & INFRASTRUCTURE
* **Frontend Engine:** Vite + React + Tailwind CSS + Lucide React. (Strictly Single Page Application. No Next.js routing or SSR).
* **Backend/Generator Engine:** Node.js (utilizing worker threads or batch processes for heavy procedural generation).
* **Database & Auth:** Supabase (PostgreSQL).
* **Internal Port:** The Vite development server strictly binds to `127.0.0.1:17000`.
* **External Routing:** The project is accessed via `http://mundanerealms.local`. 
* **Proxy Mandate:** Traffic is routed through an Apache Reverse Proxy (`/etc/apache2/sites-enabled/001-proc-gen.conf`). The proxy handles port 80 and WebSocket upgrades for Vite's Hot Module Replacement (HMR). Do NOT attempt to bind Vite to port 80.

## 2. CRITICAL SERVER MANAGEMENT (The `./pm` Wrapper)
**NEVER** start the server using raw `npm run dev` or `vite` commands. The project is strictly managed by the Project Manager (`./pm`) bash script located in the root directory.
* `./pm start` : Daemonizes the Vite server in the background and binds it safely.
* `./pm stop` : Hunts down and kills any rogue processes on Port 17000.
* `./pm restart` : Executes a clean stop and start.
* `./pm status` : Verifies the heartbeat of the server.
* **Silent Sudo:** The `./pm` script and `./bin/silent-sudo` utilize a password file located at `/home/drew/Documents/proc-generator/.sudo_pass` to execute privileged commands non-interactively.

## 3. FILE STRUCTURE & LOCATIONS
The project is a monorepo configured via npm workspaces.
* **Root Directory:** `/home/drew/Documents/proc-generator`
* **`/client`:** The Vite + React frontend application.
* **`/server`:** The Node.js + Socket.io backend.
* **`/world-builder`:** The standalone Node.js incremental generation script.
* **`/shared`:** Shared Types, Constants, and Event Interfaces.
* **`/wiki_master_docs`:** The source of truth for World Specifications, Functional Blueprints, and Technical Architecture.
* **`/bin`:** Contains utility scripts like `silent-sudo`.
* **Database Migrations:** Located at `/server/src/db/migrations/`.
* **Apache Config:** The active configuration is located at `/etc/apache2/sites-enabled/001-proc-gen.conf`. Legacy configurations have been moved to `/etc/apache2/legacy-backup/`.

## 4. THE CORE / PLUGIN ARCHITECTURE
* **The Core:** The central nervous system. It handles state, database I/O, and the orchestration of the generator. It does not contain specific lore, items, or map data.
* **The Plugins:** Procedural generation is modular. Terrain, NPCs, Loot, and Lore are built as isolated "Plugins" that the Core calls upon. You can swap, remove, or upgrade a generator plugin without touching the Core logic.

## 5. STRICT CODING STANDARDS
1.  **Anti-Monolith Rule:** Do NOT put everything into one big file. Break logic down into the smallest logical components. If a file exceeds 200 lines, it is likely doing too much and must be split.
2.  **Relational Data Structures:** Data must be normalized and relational. Avoid massive, deeply nested JSON objects. Use ID references (e.g., `locationId: "loc_123"`) to link entities together, treating the data structures like a relational database (PostgreSQL style) even if held in memory.
3.  **Explicit Multi-threading:** For heavy generation tasks, do not block the main Node Event Loop. Utilize Node's `worker_threads` to offload mathematical generation (like hex grids or massive tables) to separate CPU cores.
4.  **No Ghost Assets:** Ensure all required UI assets (images, icons) are actually present in the `/public` directory before referencing them in the code.
5.  **Silent Output Mandate:** Silence all file-write previews. When creating or updating files, use silent redirection (e.g., cat <<'EOF' > file) and do not echo the file contents to the terminal. Only output a single success confirmation line.


## 6. PRODUCTION INFRASTRUCTURE (DEDICATED HOST)
* **Production IP:** `158.69.121.203`
* **Host OS:** Ubuntu 24.04.4 LTS
* **SSH Alias:** `mundanerealms-live`
* **SSH Key:** `~/.ssh/mundanerealms_ed25519`
* **Deployment Path:** `/var/www/mundane-realms`
* **Remote User:** `mundanerealms`
* **Infrastructure Stack:** Apache2 (Reverse Proxy), Node.js (v20), PM2, Git.
* **Firewall Rules:** OpenSSH and 'Apache Full' allowed via UFW.

## 7. REMOTE EXECUTION MANDATES (Prevention of stdin Collisions)
When executing remote commands via SSH that require both **`sudo`** and **multi-line text input** (like heredocs `<<EOF`):
1.  **NEVER** pipe both the password and the data stream simultaneously into the same command.
2.  **MANDATE:** Use the **Temporary File Migration** pattern:
    *   Write the configuration/text to a temporary file in the user's home directory (e.g., `~/temp.conf`).
    *   Execute a separate, single-line `sudo` command to move or process that file (e.g., `echo 'pass' | sudo -S mv ~/temp.conf /etc/apache2/`).
3.  **RATIONALE:** This prevents "Terminal Input Traffic Jams" where the server incorrectly reads the data stream as the password, triggering security lockouts.

## 8. SOURCE CONTROL & WORKFLOW
* **GitHub Repository:** `https://github.com/materialplane/mundane-realms`
* **Clone URL (SSH):** `git@github.com:materialplane/mundane-realms.git`
* **The CLI Execution Cycle:**
    1. **Local Update**: AI makes changes to the local codebase and restarts the local server wrapper (`pm2 restart all`) to verify stability.
    2. **Dev Push**: AI pushes the changes to the `dev` branch on GitHub.
    3. **Stop & Wait**: AI **MUST STOP** after pushing to `dev`. 
    4. **Manual Promotion**: The AI shall only merge to `main` and deploy to the production server when explicitly directed by the Lead Developer.
* **Branch Strategy:**
    * `main`: Production-ready, stable code. Merged from `dev` and deployed to the dedicated host.
    * `dev`: Primary development branch. All CLI work and feature implementation occurs here.
    * `dev-backup`: Daily/Session snapshot of the `dev` branch for recovery.