# 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:3000 — default password: `adventure` (set `AUTH_PASSWORD` in `.env`).

Docker production serves the app at http://localhost:3060.

### 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`).
- **Memories:** See [How Memories Work](docs/MEMORIES.md) 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.

```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