# OSRS Codex

**One source of truth for everything that can be botted in OSRS.**

Every bot-able activity — alching, mining, slayer, bosses, trading — is
described here **once**, in a strict client-agnostic YAML structure:
requirements, execution order (state machine), the exact action sequence,
economics, best-in-class setup, and anti-ban notes.

AI agents building scripts do **not** re-learn the game. They read a codex
entry and *translate* it into the target client API
(DreamBot / Microbot / Storm / RuneLite plugins / …). The game knowledge
lives in this repo; the client glue lives in whatever script is being
written.

```
client-agnostic                client-specific (NOT in this repo)
+----------------+             +-------------------+
| codex entry    |  translate  | DreamBot Java     |
| (YAML, strict) |  ---------> | Microbot JS       |
| actions: verbs |             | RuneLite plugin   |
+----------------+             +-------------------+
```

## Layout

```
codex/<domain>/<entry-id>.yaml   # one entry per activity
  economy/       trading, alching, flipping
  training/      skill grinds (magic, mining, woodcutting, ...)
  combat/        bosses
  combat-slayers/
  quests/        quest entries (referenced by requires_quest)
  transport/     teleport/teleport-reach recipes (shared by many entries)
  meta/          account rotation, world hopping, break scheduling
docs/schema.md         # the entry contract (read this first)
docs/action-grammar.md # the universal verb vocabulary
docs/data-sources.md   # where every fact must come from + how to verify
schemas/entry.schema.json
tools/validate.py      # the gate: python3 tools/validate.py (must exit 0)
```

## The rules (short version)

1. **One entry = one activity.** State machine + action list, both mandatory.
2. **Every fact carries a source.** Wiki-cited or `researched <date>`
   (a TODO: follow-up issue must land the proper citation). Live prices
   are re-verified against `prices.runescape.wiki` on every bump.
3. **Best-in-class setup is mandatory** (`best_practice`). Top-operator
   execution: staff of fire for alchemy, noted items, shortest routes.
   Translators adopt it by default; deviating requires `improvised: true`.
4. **Anti-ban is first-class.** Every action declares delay bounds and
   movement style; entries carry `risk.ban_level` + notes.
5. **The gate must pass** before a PR merges: `python3 tools/validate.py`.
6. **Never mix in client knowledge.** No DreamBot/Microbot/Storm API names
   in entries. Translations live in script repos, referencing the entry id.

## Entry lifecycle

`draft` → `verified` (all facts sourced, prices re-checked, validator
clean) → `stale` (facts > 30d old or prices moved materially). Stale
entries are skipped by translators unless explicitly allowed.

## Contributing

This repo is **issue-driven**: all content is specified in Gitea issues
(acceptance criteria + source URLs + expected output path), implemented in
branches, and gated by `tools/validate.py` in CI. No direct pushes.