initial

README.md

@@ -0,0 +1,122 @@
+# AdventureOS
+
+A self-hosted personal companion for building consistency, learning, discipline, and growth — styled as a nostalgic personal operating system and adventure game.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 22+
+- PostgreSQL running on `localhost:5432`
+- Docker & Docker Compose (for the app and Ollama)
+
+### Development
+
+```bash
+# Start Ollama
+docker compose up ollama -d
+
+# Copy environment
+cp .env.example .env
+
+# Create the PostgreSQL role/database if needed
+sudo -u postgres psql -c "CREATE ROLE adventureos WITH LOGIN PASSWORD 'adventureos';"
+sudo -u postgres createdb -O adventureos adventureos
+
+# Install dependencies
+npm install
+
+# Run migrations and seed
+npm run db:generate
+npm run db:migrate
+npm run db:seed
+
+# Start dev server
+npm run dev
+```
+
+Open http://localhost:3060 — default password: `adventure` (set `AUTH_PASSWORD` in `.env`).
+
+### Production (Docker)
+
+```bash
+docker compose up -d --build
+```
+
+### Cron Jobs
+
+Schedule these on your server (daily/weekly):
+
+```bash
+# Materialize today's adventure (midnight)
+curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=materialize"
+
+# Generate daily quests (6am)
+curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-quests"
+
+# Generate weekly explorations (Monday 6am)
+curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-explorations"
+
+# Generate weekly review (Sunday 6pm)
+curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-weekly-review"
+
+# Prune action history older than 90 days (weekly)
+curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=prune-actions"
+```
+
+### Ollama Models
+
+```bash
+docker compose exec ollama ollama pull llama3.2:3b
+docker compose exec ollama ollama pull llama3.1:8b
+```
+
+### Themes, Undo & AI Settings
+
+- **Themes:** Settings → Appearance — 11 nostalgia themes with live preview. Default for new installs: `minimal-dark`. Legacy `xp` maps to `windows-xp-light`.
+- **Undo:** After adventure/reading actions, use the toast Undo button or Settings → Action History.
+- **AI:** Settings → AI Configuration, AI Templates, System Prompts, AI Health. Provider keys stay in `.env` only (`OPENAI_API_KEY`, `LLAMACPP_API_KEY`).
+
+Run tests: `npm run test`
+
+After upgrading, run migrations: `npm run db:migrate`
+
+### Calibre Library (optional)
+
+Connect a live Calibre library for the Library Wing — metadata is read read-only from `metadata.db`; reading progress is stored in Postgres.
+
+```bash
+# In .env
+CALIBRE_LIBRARY_PATH=/path/to/Calibre Library
+CALIBRE_READ_ONLY=true
+```
+
+For Docker, mount your library read-only (see `docker-compose.yml`):
+
+```yaml
+volumes:
+  - /path/to/Calibre Library:/calibre-library:ro
+environment:
+  CALIBRE_LIBRARY_PATH: /calibre-library
+```
+
+If Calibre is open and locks the database, the Library page shows a friendly retry message. Without Calibre configured, manual book entry still works.
+
+## Project Structure
+
+```
+nostalgia/
+├── apps/web/          # Next.js 15 application
+├── packages/db/       # Drizzle schema + migrations
+├── packages/shared/   # XP formulas, scores, types
+├── docker-compose.yml
+├── scripts/backup.sh
+└── docs/
+```
+
+## Philosophy
+
+- Consistency over productivity
+- No guilt, no streak destruction
+- The user *is* the character
+- Local AI on your server — data never leaves your infrastructure