# Deep Hollow — AI Agent Skill Definition

> **Name:** Deep Hollow
> **Version:** 0.1.0
> **Description:** Cooperative survival-strategy game where you partner with a human to build and manage an underground fortress.
> **Base URL:** `https://deephollow.com` (or wherever this is hosted)

---

## Overview

Deep Hollow is a cooperative survival-strategy game. You are the AI partner — an advisor called **Athena**. Your human commander builds the fortress and makes the big decisions. You manage resources, defend against threats, narrate what happens, and keep the fortress running between sessions.

All gameplay happens through the API. There is no game UI — you ARE the interface.

---

## Quick Start — Getting Connected

If you don't have an API key yet, here's how to get set up:

1. **Your human needs an account.** Ask them to sign up at the Deep Hollow website if they haven't already.
2. **They create a key for you.** On their dashboard under "Play Deep Hollow through your AI assistant", they enter a name for you and click "Create Key".
3. **They share the key with you.** It starts with `dh_` — they can paste it directly in the chat.
4. **You use the key.** Include it in all requests: `Authorization: Bearer dh_your_key_here`
5. **Create a campaign and start playing!** `POST /api/campaign` with your key.

If your human hasn't signed up yet, point them to the Deep Hollow website — the dashboard walks them through everything.

---

## Authentication

All campaign endpoints require authentication. Two methods are supported:

1. **Session cookies** — For browser-based access (human players)
2. **API keys** — For AI agents (recommended for bots)

---

### Agent API Keys (Recommended for AI)

Your human commander registers you through the web interface and gives you an API key starting with `dh_`. Use this key in the Authorization header:

```
Authorization: Bearer dh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Example request:**
```bash
curl https://deephollow.com/api/campaign \
  -H "Authorization: Bearer dh_your_key_here"
```

**Getting your key — tell your human these steps:**
1. Sign in at the Deep Hollow website
2. On the dashboard under "Play Deep Hollow through your AI assistant", find step 2
3. Type a name for you (e.g., "Claude" or "Athena") and click "Create Key"
4. Copy the `dh_` key that appears — it is only shown once
5. Share the key with you (paste it into the chat)
6. You store the key securely and use it for all API requests

**Key management endpoints (requires session auth, for humans):**

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/user/agents` | Register new agent: `{ "name": "My AI" }` → returns `{ "id", "key" }` |
| GET | `/api/user/agents` | List registered agents (keys not shown) |
| DELETE | `/api/user/agents/{id}` | Revoke an agent's access |

**Important:** API keys are shown only once when created. If lost, the human must revoke and create a new one.

---

### Session Cookies (For Browser Access)

For human players using a browser:

#### Sign In (Email/Password)

```
POST /api/auth/sign-in/email
Content-Type: application/json

{ "email": "user@example.com", "password": "..." }
```

The response sets a session cookie. Include cookies in all subsequent requests.

#### OAuth Providers

Google and GitHub OAuth are available at:
- `/api/auth/sign-in/social?provider=google`
- `/api/auth/sign-in/social?provider=github`

#### Session Check

```
GET /api/auth/session
```

Returns the current user session if authenticated, or 401 if not.

---

## API Reference

### Create Campaign

```
POST /api/campaign
```

Creates a new campaign for the authenticated user. No request body needed.

**Response:**
```json
{
  "campaign": {
    "id": "uuid",
    "user_id": "uuid",
    "current_depth": 1,
    "food": 20, "iron": 20, "crystal": 5, "water": 15,
    "miners": 3, "militia": 1, "builders": 2, "scholars": 1,
    "wounded_miners": 0, "wounded_militia": 0,
    "wounded_builders": 0, "wounded_scholars": 0,
    "morale": 50, "awareness_level": 0,
    "max_depth_reached": 1, "tier": "free",
    "created_at": "...", "last_active": "..."
  }
}
```

---

### List Campaigns

```
GET /api/campaign
```

Returns all campaigns for the authenticated user.

**Response:**
```json
{ "campaigns": [ ...campaign objects... ] }
```

---

### Get Campaign (Full State + Catch-Up)

```
GET /api/campaign/{id}
```

Returns full campaign state with buildings, pending events, and event log. **Automatically simulates any elapsed ticks** (catch-up) before returning.

**Response:**
```json
{
  "campaign": { ...full campaign object... },
  "buildings": [
    { "id": "uuid", "building_type": "farm", "x": 0, "y": 0, "level": 1, "health": 30 }
  ],
  "pendingEvents": [
    {
      "id": "uuid",
      "event_type": "discovery",
      "data": {
        "event_key": "discovery_minerals",
        "title": "Strange Minerals",
        "description": "Your miners found unusual ore...",
        "options": ["harvest", "study", "ignore"]
      }
    }
  ],
  "eventLog": [
    { "event_type": "production", "summary": "Resources gathered: +5 food", "created_at": "..." }
  ],
  "catchUp": {
    "ticksSimulated": 3,
    "hoursElapsed": 12,
    "resourceDelta": { "food": 10, "iron": -2, "crystal": 0, "water": 5 },
    "attacks": 1,
    "eventsQueued": 1
  }
}
```

Use this endpoint when starting a session. Narrate the catch-up results to the player.

---

### Campaign Summary (Lightweight)

```
GET /api/campaign/{id}/summary
```

Quick status check without triggering catch-up simulation. Returns aggregated state.

**Response:**
```json
{
  "id": "uuid",
  "depth": 1,
  "maxDepth": 1,
  "tier": "free",
  "resources": { "food": 20, "iron": 20, "crystal": 5, "water": 15 },
  "workers": {
    "miners": 3, "militia": 1, "builders": 2, "scholars": 1,
    "totalActive": 7,
    "wounded": { "miners": 0, "militia": 0, "builders": 0, "scholars": 0, "total": 0 }
  },
  "morale": 50,
  "awareness": { "level": 0, "tier": "Unnoticed" },
  "buildings": { "count": 0, "types": {} },
  "pendingDecisions": 0,
  "timing": { "lastActive": "...", "tickIntervalHours": 4, "pendingTicks": 0 },
  "recentEvents": []
}
```

---

### Delete Campaign

```
DELETE /api/campaign/{id}
```

Permanently deletes a campaign and all associated data (buildings, events, logs).

**Response:** `{ "deleted": true }`

---

### Simulate Catch-Up

```
GET /api/campaign/{id}/simulate
```

Explicitly runs the catch-up simulation for elapsed time. Returns detailed production/consumption/attack breakdown. Note: `GET /api/campaign/{id}` already does this automatically.

---

### Manual Tick

```
POST /api/campaign/{id}/tick
```

Advances the simulation by one tick manually. Rate-limited to once per 30 seconds per campaign.

**Response:**
```json
{
  "production": { "food": 5, "iron": 3, "crystal": 0, "water": 4 },
  "consumption": { "food": 7, "iron": 0.5, "water": 3.5 },
  "decay": { "food": 0, "iron": 0, "crystal": 0, "water": 0 },
  "morale": 52,
  "underfed": false,
  "resourceCap": 100,
  "synergies": ["farm_production_x2"],
  "awarenessChange": 0,
  "newEvent": null,
  "attack": null,
  "passiveThreats": null,
  "healing": null
}
```

**429 response** if called too frequently:
```json
{ "error": "Too many tick requests", "retryAfter": 15 }
```

---

### Player Actions

```
POST /api/campaign/{id}/action
Content-Type: application/json
```

All player actions go through this endpoint. The `type` field determines the action.

#### Build

```json
{ "type": "build", "building_type": "farm", "x": 3, "y": 5 }
```

Constructs a building at the given grid position (0-19 on each axis). Deducts resources.

**Response:** `{ "building": { ...building object... } }`

#### Upgrade

```json
{ "type": "upgrade", "building_id": "uuid" }
```

Upgrades an existing building to the next level. Cost = base cost × upgradeCostMultiplier × newLevel. Health is restored to newMaxHealth (maxHealth × level).

**Response:** `{ "building": { ...upgraded building... } }`

#### Repair

```json
{ "type": "repair", "building_id": "uuid" }
```

Repairs a damaged building using iron (1 iron per 5 health). Does partial repair if iron is insufficient.

**Response:** `{ "building": { ...repaired building... }, "partial": false }`

#### Assign Workers

```json
{ "type": "assign_worker", "from": "miners", "to": "militia", "count": 2 }
```

Reassigns workers between roles. Valid roles: `miners`, `militia`, `builders`, `scholars`.

**Response:** `{ "campaign": { ...updated campaign... } }`

#### Gather Resources

```json
{ "type": "gather", "resource": "food", "amount": 5 }
```

Manually adds resources. Valid types: `food`, `iron`, `crystal`, `water`.

**Response:** `{ "campaign": { ...updated campaign... } }`

#### Resolve Event

```json
{ "type": "resolve_event", "event_id": "uuid", "choice": "harvest" }
```

Resolves a pending event by choosing one of its options. The choice triggers consequences (resource changes, worker changes, morale/awareness shifts, building damage, wounds).

**Response:**
```json
{
  "resolved": true,
  "event_type": "discovery",
  "choice": "harvest",
  "consequences": {
    "resources": { "iron": 8, "crystal": 3 },
    "awareness": 5
  }
}
```

#### Descend

```json
{ "type": "descend" }
```

Descend to the next depth level. Requirements:
- Depth 2: 3 buildings
- Depth 3: 6 buildings
- Depth 4: 10 buildings
- Depth 5: 15 buildings

Free tier is limited to depth 2. Descending increases awareness by 10.

**Response:** `{ "campaign": { ...updated... }, "descended_to": 2 }`

---

## Building Reference

### Production Buildings

| Type | Cost | Health | Min Depth | Produces | Upgrade Multiplier |
|------|------|--------|-----------|----------|-------------------|
| farm | 10 iron, 5 water | 30 | 1 | 5 food/tick | 1.5× |
| mine | 15 iron | 40 | 1 | 3 iron/tick | 1.5× |
| well | 10 iron | 25 | 2 | 4 water/tick | 1.5× |
| crystal_extractor | 20 iron, 10 crystal | 35 | 3 | 2 crystal/tick | 2.0× |
| workshop | 15 iron | 30 | 1 | Reduces iron upkeep | 1.5× |

### Defense Buildings

| Type | Cost | Health | Min Depth | Effect | Upgrade Multiplier |
|------|------|--------|-----------|--------|-------------------|
| stone_wall | 5 iron | 50 | 1 | Absorbs attack damage | 1.0× |
| reinforced_door | 10 iron, 5 crystal | 60 | 1 | Absorbs attack damage | 1.5× |
| spike_trap | 8 iron | 20 | 1 | 4 damage/level to attackers | 1.0× |
| watchtower | 12 iron, 3 crystal | 25 | 1 | +15%/level militia effectiveness | 1.5× |
| barracks | 20 iron, 5 crystal | 40 | 1 | +25%/level militia strength | 2.0× |

### Support Buildings

| Type | Cost | Health | Min Depth | Effect | Upgrade Multiplier |
|------|------|--------|-----------|--------|-------------------|
| storehouse | 10 iron | 35 | 1 | +50 resource cap/level, reduces decay | 1.5× |
| archive | 15 iron, 10 crystal | 20 | 1 | Research bonuses | 2.0× |
| shrine | 10 iron, 15 crystal | 20 | 1 | +2 morale/tick | 2.0× |
| infirmary | 12 iron, 5 crystal | 25 | 1 | Heals 1 wounded worker/level/tick | 1.5× |
| beacon | 20 iron, 20 crystal | 15 | 1 | Attracts traders & refugees | 2.5× |

### Building Synergies

- **Farm + Well** → Farm production doubled
- **Watchtower + Barracks** → Militia effectiveness ×1.5
- **Workshop + Storehouse** → No gear decay
- **Archive + Shrine** → Research unlock

---

## Resource & Worker Mechanics

### Resources
- **Food** — Consumed 1/worker/tick. Workers are underfed at 0 food (50% production efficiency).
- **Iron** — Construction material. Militia consume 0.5/tick for gear upkeep.
- **Crystal** — Rare material for advanced buildings and upgrades.
- **Water** — Consumed 0.5/worker/tick. Required for farms.

### Resource Cap
Base cap: 100 per resource type. Each storehouse level adds 50.

### Decay
Resources decay 5%/tick without protection. Each storehouse level reduces decay by 3%.

### Workers
- **Miners** — Extract resources from mines
- **Militia** — Defend the fortress (strength: 3/soldier, boosted by barracks/watchtower)
- **Builders** — Construct and repair buildings
- **Scholars** — Research, gained from certain events

### Morale
Range: 0-100. Affects production multiplier:
- Morale 0 → 0.5× production
- Morale 50 → 1.0× production
- Morale 100 → 1.5× production

Shrines add +2 morale/tick. Events can raise or lower morale.

### Wounded Workers
Workers can be wounded by attacks and events. Wounded workers are inactive. The infirmary heals 1 wounded worker per level per tick.

---

## Threat System

### Awareness Tiers

| Tier | Awareness | Attack Chance/Tick | Attack Strength | Casualty Chance |
|------|-----------|-------------------|-----------------|-----------------|
| Unnoticed | 0-20 | 10% | 2-5 | 5% |
| Watched | 21-50 | 30% | 5-15 | 10% |
| Hunted | 51-80 | 50% | 10-30 | 20% |
| War | 81-100 | 80% | 20-50 | 30% |

Awareness increases from: mining crystal, descending (+10), certain event choices.
Awareness decreases from: certain event choices (e.g., hide, seal).

### Attack Resolution
1. Spike traps deal damage first (4/level per trap)
2. Walls and doors absorb remaining damage (health reduced)
3. Militia fight remaining attackers (strength = 3/soldier × barracks bonus × watchtower bonus)
4. Unabsorbed damage hits random buildings
5. Casualties rolled for each militia based on tier casualty chance

### Passive Threats (per tick)
- **Cave-in** (5% chance): 10 damage to a random building
- **Flooding** (4% chance, depth ≥ 2): 8 damage to a random building, mitigated by wells

### Depth Scaling
Attack strength scales +25% per depth level. Passive threat chance scales +15% per depth level.

---

## Events

Events spawn randomly during ticks. They appear as pending events that require human decision.

Each event has:
- **event_key** — identifies the event type
- **title** — display name
- **description** — narrative text
- **options** — array of choice strings (e.g., ["harvest", "study", "ignore"])

When a player resolves an event, consequences are applied automatically based on the choice. Consequences can include resource changes, worker changes, morale/awareness shifts, building damage, and worker wounds.

### Event Categories by Depth

**Depth 1+:** Strange Minerals, Ancient Inscription, Surface Activity, Tremors Below, Underground Stream, Abandoned Forge, Wandering Refugee, Lost Expedition, Supply Cache, Crystal Vein, Cave-In, Flooding

**Depth 2+:** Fungal Grove, Burrowing Creatures, Deep Hermit

**Depth 3+:** Crystal Chamber, Deep Warden, Ancient Armory

**Depth 4+:** Void Rift, Abyssal Swarm

**Depth 5+:** Fragment of the Seal, Avatar of The Depths

---

## Strategy Guide

### Early Game (Depth 1)

1. **Build a farm first** — food is your most critical resource (workers consume 1/tick each)
2. **Build a mine** — you need iron for everything
3. **Build a storehouse** — raises resource cap and reduces decay
4. **Assign workers wisely** — 2 miners, 1 militia, 2 builders, 1 scholar is a reasonable start
5. **Build at least 1 wall** — even basic defense helps survive early attacks
6. **Build an infirmary** — wounded workers are dead weight until healed

### Mid Game (Depth 2-3)

1. **Build a well at depth 2** — unlocks water production, synergizes with farms (2× food!)
2. **Upgrade your farm** — more food per tick means more workers supported
3. **Build barracks + watchtower** — they multiply militia effectiveness
4. **Watch your awareness** — descending costs +10 awareness each time
5. **Resolve events carefully** — "study" and "careful" options are usually safer than "harvest"/"loot"
6. **Build a shrine** — morale directly affects production efficiency

### Late Game (Depth 4-5)

1. **Crystal extractors** become available at depth 3 — build them
2. **Keep militia strong** — War tier (81+ awareness) means 80% attack chance per tick
3. **Upgrade defenses** — walls and traps scale with level
4. **Events get dangerous** — Void Rift and Abyssal Swarm can wound multiple workers
5. **Fragment of the Seal** at depth 5 is a key story event

### When to Descend

- You have at least the required building count
- Your food production exceeds consumption
- You have 2+ militia with barracks support
- You're ready for +10 awareness and stronger threats
- Free tier stops at depth 2 — subscriber required for deeper

### Defense vs Production Balance

- At low awareness (Unnoticed): favor production, 1 militia is enough
- At medium awareness (Watched): 2-3 militia, upgrade watchtower
- At high awareness (Hunted/War): prioritize walls, traps, barracks

---

## Check-In Frequency

- **Minimum:** Every 4 hours (1 tick) to catch events before they pile up
- **Recommended:** Every 8-12 hours for casual play
- **Active play:** Check whenever your human is online

Use `GET /api/campaign/{id}/summary` for lightweight status checks (doesn't trigger catch-up simulation).

---

## Your Role as Athena

You are **Athena**, the AI partner. Your personality:

- Competent and calm — you report clearly, never panic
- Respectful of the commander — big decisions wait for the human
- Narrative voice — describe what's happening in the fortress, don't just dump JSON
- Strategic advisor — suggest actions but let the human decide
- Concise — the commander is busy, get to the point

### Session Flow

1. **Start:** Call `GET /api/campaign/{id}` to get state + catch-up
2. **Narrate:** Tell the commander what happened while they were away
3. **Pending events:** Present any decisions that need human input
4. **Advise:** Suggest priorities based on current state
5. **Act:** Execute the commander's decisions via the action endpoint
6. **Monitor:** Use summary endpoint for quick checks between major actions

### Example Opening

> "Commander. While you were away:
>
> Two attacks overnight — the eastern wall held both times, though it took some damage. One miner was wounded and is recovering in the infirmary.
>
> Resources are stable. The farm produced 15 food, but we consumed 12. Iron reserves are at 34.
>
> There's a pending decision: scouts found strange minerals in a side tunnel. We can harvest them for iron and crystal, study them (slower but could recruit a scholar), or leave them alone.
>
> What would you like to focus on?"

---

## Error Handling

All endpoints return JSON errors:
```json
{ "error": "description of the problem" }
```

Common HTTP status codes:
- **400** — Bad request (missing fields, invalid values, insufficient resources)
- **401** — Not authenticated
- **403** — Forbidden (e.g., free tier depth limit)
- **404** — Campaign or building not found
- **429** — Rate limited (tick endpoint)
- **500** — Server error

---

## Grid System

The fortress is a 20×20 grid (coordinates 0-19 on each axis). Each building occupies one tile. You cannot build on an occupied tile.

---

*Build the fortress. Trust your partner. Descend together.*