🚀 TheHowlingWhispers Platform — Full Development Plan
Living roadmap for TheHowlingWhispers — a live multi-user AI chat platform on 159.195.194.180, powered by BYOK provider routing, room-based social features, OC / character management, and a membership model.
Status: v4.3.1 — Reroll cascade fix. `POST /api/rooms/:roomId/messages/:msgId/reroll` no longer keys its DELETE off `created_at` (which broke when the reroll's bot insert used `datetime('now')` and the surrounding chat history used `new Date().toISOString()` — string compare treated `'T' (0x54) > ' ' (0x20)` so older ISO messages got swept). The cascade now keys off the primary key (`id`) and filters `role = 'assistant'`, so it only removes the rerolled row and any subsequent bot rows. All message inserts normalised to `new Date().toISOString()` (reroll, branch system note, wakeup alarm). 6 historical SQLite-format rows in `data/srh.db` migrated to ISO via `scratch/migrate-msg-timestamps.js`. Soulforge + The Forge (4.3.0) and Codex AI assistant (4.2.0) ship alongside. Aether v1.0.10 unchanged.
Roadmap Completion Progress
0% Complete
Done: 0
In Progress: 0
Pending: 0
📆 Project Phases
Phase 1
Foundation & QoL
LIVE
Phase 2
API Keys & Provider Router
LIVE
Phase 2.5
Controls & Memory Systems (Lorebook/Dual-Brain/Realism)
LIVE
Phase 2.6
Immersive Alerting & Alarm Systems
WIP
Phase 3a
Social Features
WIP
Phase 3b
OC System
UPCOMING
Phase 4
Production Polish
UPCOMING
Architecture Overview
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Browser SPA │────▶│ Express API │────▶│ SQLite DB │
│ (chat + rooms) │ │ (server.js) │ │ (data/srh.db) │
└─────────────────┘ └───────┬──────────┘ └──────────────────┘
│
┌──────▼──────────┐ ┌──────────────────┐
│ AI Router │──▶ │ Lore Files │
│ (lib/ai- │ │ (/lore/ static) │
│ router.js) │ └──────────────────┘
└─────────────────┘
Data Model
| Table | Purpose |
|---|---|
| users | Accounts — username, password hash, role (member/admin), protected flag, allowed_master, timestamps |
| sessions | Auth tokens — user_id, token, created_at (persists across restarts) |
| api_keys | Per-user API keys — provider, encrypted key, label (Phase 2) |
| rooms | Chat rooms — name, owner, system prompt, private flag, provider, model, timestamps |
| room_members | Membership — user, room, role (owner/member), joined_at |
| messages | Chat history — room, user, role, content, timestamp, deleted flag |
| relationships | Per-room relationship scores — user, room, score, updated_at |
| invites | Pending room invitations — from, to, room, status (Phase 3a) |
| bug_reports | Bug tracking — title, description, status, reporter, room (Phase 4) |
Phased Implementation
Phase 1 — Foundation DONE
Database · Auth · Rooms · Admin · Chat rebuild
- Replace JSON files with SQLite (better-sqlite3) — WAL mode, 6 tables, indexed, foreign keys
- User sign-up / login with httpOnly session cookies (persist across restarts)
- Dashboard page — login/register tabs, room list, create room form, discover public rooms
- Room-based chat UI — per-room SSE, paginated history, custom system prompts
- Per-room relationship scoring — AI-judged sentiment, 0–100 scale, floor at 0
- Admin system — role column, /admin panel with stats, room/user management, slash commands
- JSON data migration — auto-import old chat history, relationships, stats on first boot
- Version detector + changelog modal — auto-syncs version badge from server
- Cookie consent bar + telemetry endpoint
Phase 1.5 — QoL & Lore Mirror DONE
Message actions · Privacy · Account protection
- Message actions — Delete, Edit, Reroll, Branch (with SSE live updates)
- Private rooms — exclude from discover, only visible to members
- Protected users — immune to role changes / deletion, defaults on for all new accounts
- Permanent admin accounts (Eirvargr + Cipher)
- Stale test rooms & users cleaned up
- Lore integration — serve full Arrax Universe lore at /lore/ as static files
- Characters reference page at /characters — 5 character cards with profile links + dev todo
Phase 2 — User-owned API Keys & Provider Router DONE
Multi-provider · Key management · Model switching · Key Rotation & Whitelist
- Settings page — add/manage API keys per provider (encrypted securely via AES-256-GCM in DB)
- AI Router — unified dispatch to NovelAI, OpenAI, Claude, Gemini, OpenRouter, Ollama
- Room provider setting — owner picks which provider/model powers the room
- Master key whitelist — allow admins to authorize specific users to use the server's master key
Phase 2.5 — Experience Controls & Memory Systems DONE
Realism slider · Dynamic memory slots · Key-triggered Lorebook
- Realism slider (per room) — 5 level from Casual to Void. Injects ECHO-LOCK strictness, C-01 autonomy, negative veto lists, and dynamic persona-filtered relationship overrides.
- Dual-Brain Memory Consolidator — run memory summarization/consolidation using Gemini or local Ollama instances NEW
- Key-triggered Lorebook — scan messages for keywords to dynamically inject relevant lore details (saves active memory) NEW
- Lore-aware system prompts — auto-inject character bio details recursively from the lore mirror into AI context
- Relationship XP Progression Refinements — added +1 XP interaction baseline for steady progression, and default score set to 50 NEW
Phase 2.6 — Immersive Alerting & Alarm Systems WIP
Update warnings · Offline Alarms · Sync engine · Web Push API
- Immersive Update Warnings — bot describes feeling mental Void updates, custom themed action buttons NEW
- Bot Wakeup Alarm — schedule wakeup events that trigger the bot to generate and push wakeup messages using the Web Push API (works when browser is closed) NEW
- Plan Synchronization Engine — automatic local-to-VPS plans caching and offline-state fallbacks NEW
- Robust Client Reply Recovery — fallback rendering of reply on POST response if SSE drops NEW
- Alarm Customization Options — OS-level chime notifications, relationship-adjusted wakeup tones, snooze command handlers NEW
Phase 3a — Social Features WIP
Invites · Permissions · Room discovery
- Private room flag — already live (excluded from discover, visible to members)
- Message actions — Delete, Edit, Reroll, Branch with SSE live updates
- Game Over Room Kick/Ban — 24-hour room ban when relationship drops to 0, history deletion, and interactive cheat reset NEW
- Full visibility tiers — Public, Unlisted (invite-only), Private (owner only)
- Invite system — send by username, accept/reject from notification panel
- Room roles & permissions — Owner, Admin, Member (kick, transfer, edit settings)
Phase 3b — Soulforge & The Forge (Creator Toolbox) DONE
Soulforge rename · The Forge launcher hub · 7 tool cards · deprecated legacy editor
- Character Database Migration — moved hardcoded bots.json data to SQLite `characters` table
- Global UI Redesign — implemented Velvet Console design system across all pages
- Workshop UI Layout — built the draft workspace and shard library frontend (preserved at /legacy-editor.html)
- Soulforge rename (4.3.0) — the (beta) Character Creator grew up. URL /character-creator-beta.html → /soulforge.html; old URL serves a meta-refresh + JS redirect stub. Page title, in-page h1 prefix, Codex greeting, side-nav link, and Lobby button all swap `(beta)` for `Soulforge`. Design doc moved to /soulforge-design.html. All features (9 sections, 36-field payload, Codex AI assistant, live age-gate, auto-save, edit mode) are unchanged.
- The Forge launcher hub (4.3.0) — the Workshop was renamed The Forge and repurposed as a creator toolbox. Same URL (/workshop.html), new layout. 7 tool cards modeled on The Lobby: Soulforge (live), Fragments Workshop (planned), ST PNG / JSON Card Import (planned), Lorebook Editor (future), Worldbuilder / Scenario Builder (future), Sprite / Avatar Pack (future), Voice Preset Library (future). Disabled cards show a roadmap-status toast; live cards deep-link straight to the tool.
- Legacy editor preserved (4.3.0) — the original power-user character editor (shard list, draft workspace, live preview compile, Lyra wizard, drag-and-drop import, archetype presets) is preserved at /legacy-editor.html. The Forge shows it in an `Archived` section with a dashed border and a `Deprecated` pill. New users start with Soulforge; power users who want the macro-resolver preview pane or the meta-contact import can still get to the old editor.
- The Fragments Workshop — modular brain shards for Persona/Identity, World lore, and System behavior rules. Card on The Forge. PLANNED · 3b.1
- SillyTavern PNG Card Import — drag-and-drop character card upload with PNG metadata chunk extractor. Card on The Forge. PLANNED · 3b.1
- W++ Format Parser — natively parse and integrate W++ format trait templates into the system prompt pipeline. Lives inside the Import tool.
- JSON Meta-Contact Import — support for importing external character definitions from JSON files (e.g., meta-contact.json). Already half-implemented in the legacy editor's drag-and-drop zone — fold into the new Import tool.
- Dynamic Macro Resolver — support for
{{char}},{{user}}, and weighted choices{{random::Common@1::Rare@0.1}}in prompts. Platform-wide helper, will surface in every tool. - Draft Workspace Auto-save — rolling rollback snapshots and automatic background saving for active personas/shards. Already live in Soulforge (4.0.0) — extend to Fragments in 3b.1.
- ECHO-LOCK / anti-godmoding — pre-filter user messages for reality-altering claims. Cross-cutting, ships in 3b.1.
Phase 3.8 — Immersive Roleplay Mode & AI Agents PENDING
Roleplay HUD · Expression Sprites · Weather overlays · Pipeline
- AI Agent Pipeline — decouple backend orchestration into sequential plugins (Sentiment, Expression, Lorebook, Summary) NEW
- Roleplay HUD Widgets — toolbar meters for location, weather, in-universe time, inventory, and character lists NEW
- Dynamic Expression Sprites — character avatars that change emotions (neutral, happy, blush, angry) based on LLM output analysis or action text NEW
- Ambient Particle Overlays — CSS overlays displaying rain, snow, or fog particles matching the HUD weather NEW
Phase 4 — Production Polish PENDING
Rate limiting · Mobile · EU compliance · Backups · Membership
- Rate limiting — per-user, per-endpoint limits
- Mobile responsive — touch support, collapsible sidebar, full-width input
- EU DSA report button — report on every message, reason selection, admin queue
- Bug reports — modal with auto-included browser/page info, admin board
- Daily backups + deployment docs — SQLite backup automation, self-hosting guide
- Free tier message caps — hourly limit for free accounts, unlimited for paid
- Membership payment integration — finalize pricing, Stripe/PayPal processor
Phase 5 — Collective Intelligence & Multiplayer Roleplay ON THE TABLE
Group chats · Multi-bot logic · Shared memory pool · Relationship webs
- Multi-Bot Rooms — allow inviting multiple OCs/bots to the same chat room NEW
- Bot-to-Bot Interactions — trigger handlers allowing bots to respond to each other based on context NEW
- Shared Room Memory — central memory pool so bots can reference active environmental events collectively NEW
- Group Relationship Web — matrix tracking relationship levels between user-bot and bot-bot combinations NEW
Phase 6 — Multi-Modal Immersion ON THE TABLE
TTS voice · Dynamic scene art · Ambience audio
- TTS Voice Synthesis — stream voice output (ElevenLabs or local AllTalk TTS integration) matching bot profiles NEW
- Dynamic Scene Generators — generate background art (SDXL/Flux) dynamically when location context changes NEW
- Spatial Soundscapes — play subtle, procedural ambient loop tracks mapped to weather/location tags NEW
Phase 7 — Autonomous Background Agency ON THE TABLE
Auto-chat loops · Diaries · Dynamic clock / weather loops
- Autonomous Room Ticking — background bot triggers to simulate rooms evolving while offline NEW
- Character Diaries — OCs write private reflection journals on user relationships, unlocked at high trust NEW
- Dynamic Clock Cycles — server time/date shifts dynamically influencing bot mood, energy, and dialogue templates NEW
Phase X — Sovereign Nodes & Decentralized Tech ON THE TABLE
WebGPU · P2P local syncing · Offline execution bundles
- WebGPU Local Inference — load and run small models directly in-browser via WebGPU (WebLLM) for zero-latency, keyless chatting NEW
- P2P Room Syncing — sync chat histories and custom characters directly user-to-user via WebRTC without server logs NEW
- Offline Desktop Builds — export whole profile, rooms, and frontend assets to an Electron/Tauri standalone client NEW
🌍 Phase 4.0.0 — Design Documents
Two extensive design documents cover the planned 4.0.0 features. Each is a self-contained design page with a quick-navigation table of contents, chaptered sections, appendices, and worked examples.
Decision Log
| Decision | Resolution |
|---|---|
| Auth scope | Username + password only. No email. CLI password reset only: node scratch/reset-password.js <username> <new-password>. No in-app reset flow. |
| Self-hosted or public | Private group for now. Public instance possible later. |
| Primary providers | NAI (GLM-4-6) primary, Gemini 2.5 Flash fallback. Phase 2 adds more. |
| Hosting | Local machine (PM2-managed). VPS deployment docs in Phase 4. |
| Character default | Peony is default per-room. System prompt fully customizable. |
| Platform name | Pending — evaluating lore candidates (Moonflower, Whisper, Shadow Creek, etc.) |
| Max tokens | 800 for all roles — no rank discrimination. |
| Relationship system | 0–100 scale, floor at 0, AI-judged sentiment with auto +1 fallback. |
| Real-time | Per-room SSE (not global). Users only receive events for rooms they're in. |
| Message actions | Room owner/admin for delete/edit/reroll. Branch available to all members. |
This plan is a living document. Phases and scope shift based on priorities. Last updated for v4.3.1 (Jun 27, 2026) — Reroll cascade fix. `POST /api/rooms/:roomId/messages/:msgId/reroll` no longer keys its DELETE off `created_at` (string compare bug when bot insert format changed from ISO to `datetime('now')`); cascade now keys off the primary key and filters `role = 'assistant'`. All message inserts normalised to `new Date().toISOString()`. 6 historical SQLite-format rows in `data/srh.db` migrated to ISO. Soulforge + The Forge (4.3.0) and Codex AI assistant (4.2.0) ship alongside. Aether v1.0.11 (Jun 29, 2026): stat → XP coupling removed per report id 10 — body stats are now RP cues only, fed to prompt-injection + character_mood. 51-test self-test suite in `lib/aether/test.js`; 8-test XP-invariance regression in `scratch/test-aether-decoupling.js`. No main-app version bump.
Long-term direction (2.0-level, not committed): the cross-pack integration could eventually flip
Long-term direction (2.0-level, not committed): the cross-pack integration could eventually flip
user_stats ownership — move the table from Aether's schema to Mirror's (since Mirror is "the user's" and the data represents the user's body). Aether would then read it as a foreign input for `character_mood` derivation. This would align with Mirror v1.3.0 (persona ↔ body attachment) and the existing pattern where Aether consumes Mirror (not the other way around). Not for any 1.0.x patch — a 2.0 design doc.