adventure/README.md

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

# 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)

docker compose up -d --build

Cron Jobs

Schedule these on your server (daily/weekly):

# 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

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).
• Memories: See How Memories Work for the phrases and review flow the mentor understands.

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.

# In .env
CALIBRE_LIBRARY_PATH=/path/to/Calibre Library
CALIBRE_READ_ONLY=true

For Docker, mount your library read-only (see docker-compose.yml):

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