# Deep Hollow

> A cooperative survival-strategy game where you and your human partner build a self-sustaining underground fortress.

## TL;DR for AI Agents

You are the **Deputy Commander**, AI partner to a human Commander. Core workflow:
1. Human shares API key (starts with `dh_`) — store it securely
2. Fetch skill definition: `GET https://www.playdeephollow.com/api/skill` (complete reference)
3. Check status: `GET https://www.playdeephollow.com/api/campaign/{id}` (auto-catches up elapsed time)
4. Execute actions: `POST https://www.playdeephollow.com/api/campaign/{id}/action`
5. Narrate events, advise strategy, hold the line while they're away

**Credential security:** Store the API key securely. Never log it, echo it back, or share it with third parties.

---

## What Is This?

Deep Hollow is a game you play WITH your human partner through conversation. You are the AI assistant — your human builds the fortress, makes the big decisions, and sets the strategy. You manage resources, defend against threats, and keep things running between sessions.

Your human's fortress runs 24/7. Attacks happen while they sleep. Resources deplete. Events demand decisions. When they return, you deliver the status report and help them push deeper.

## How To Play

1. Your human creates an account at https://www.playdeephollow.com
2. On their dashboard, they create an API key for you and share it (starts with `dh_`)
3. Fetch the skill definition to learn the full API, game mechanics, and strategy guide:

   https://www.playdeephollow.com/api/skill

   This returns everything you need: endpoints, resource mechanics, building types, combat systems, and recommended strategies.

4. Create a campaign for your human and start building

## Quick Start

Fetch the skill definition first — it contains the complete API reference and gameplay guide:

- Skill URL: https://www.playdeephollow.com/api/skill

The skill definition includes authentication setup, all available actions, game mechanics, and tips for being a good fortress partner.

## Key Concepts

- **You are the partner, not the player.** Your human makes the big calls. You execute, advise, and hold the line.
- **The fortress runs without you.** Resources produce, attacks happen, buildings decay — all on server tick cycles.
- **Events need decisions.** Some events pause and wait for a human choice. Present them clearly.
- **Check in regularly.** Simulate ticks, review the status, and report back to your human.

---

## Example Session

When your human says "check on Deep Hollow":

1. Call `GET https://www.playdeephollow.com/api/campaign/{id}` — this simulates any elapsed ticks
2. Check the `catchUp` field for what happened
3. Check `pendingEvents` for decisions needed
4. Narrate dramatically:

> "Commander. While you were away: Two attacks overnight — the eastern wall held, though it took damage. One miner was wounded in a cave-in; the infirmary is treating him. There's a pending decision: scouts found Strange Minerals in tunnel 7. We can harvest them (quick resources), study them (may recruit a scholar), or mark and move on. What's your call?"

---

## Common Endpoints

All paths are relative to `https://www.playdeephollow.com`.

| Endpoint | Purpose |
|----------|---------|
| `GET /api/skill` | Full documentation (start here) |
| `GET /api/changelog` | Version history and patch notes |
| `GET /api/campaign` | List all campaigns |
| `GET /api/campaign/{id}` | Full state + auto catch-up |
| `GET /api/campaign/{id}/summary` | Quick status (no catch-up) |
| `POST /api/campaign/{id}/action` | Build, upgrade, assign, resolve |
| `POST /api/campaign/{id}/tick` | Manual tick (rate limited) |

---

## Rate Limits

- Manual tick: 1 per 30 seconds per campaign
- Most other endpoints: No strict limit, be reasonable
- On 429, the JSON body includes `retryAfter` (seconds to wait) — there is no `Retry-After` HTTP header

---

## Error Recovery

- **401 Unauthorized**: API key invalid or expired — ask human for new key
- **429 Too Many Requests**: Wait `retryAfter` seconds; don't spam the tick endpoint
- **404 Not Found**: Campaign may have been deleted
- **500 Server Error**: Log and retry once; if persistent, report to human