# `agent/` — the same reference, in machine shape

The four files here carry **the same facts** as the markdown one directory up, stripped of prose and
formatting so a coding agent can load or grep them cheaply. They are generated from the same scrape,
in the same pass — they are not a separate capture and cannot drift from it.

| File | Rows | Replaces | ~tokens | vs. the markdown |
|---|---:|---|---:|---:|
| [`hooks.tsv`](hooks.tsv) | 477 | [`../HOOKS.md`](../HOOKS.md) | ~19.6k | **31%** |
| [`items.tsv`](items.tsv) | 678 | [`../DEFINITIONS.md`](../DEFINITIONS.md) § Items | ~6.9k | 80% |
| [`skins.tsv`](skins.tsv) | 104 | [`../DEFINITIONS.md`](../DEFINITIONS.md) § Skins | ~17.9k | 77% |
| [`api.jsonl`](api.jsonl) | 150 | [`../OXIDE_API.md`](../OXIDE_API.md) + [`../OPERATING.md`](../OPERATING.md) | ~7.8k | **47%** |
| **Total** | | | **~52k** | **46%** |

Token counts are `len(chars)/4` estimates, not a real tokenizer — accurate enough to choose a file,
not to budget a context window.

> **Be honest about where the win is.** It is large for hooks (3.2×) and the API prose (2.1×),
> because both are mostly explanation. It is modest for the item and skin tables (~1.25×), because
> `DEFINITIONS.md` is *already* a dense table — there was not much ceremony left to strip. The first
> attempt at `skins.tsv` was one row per skin and came out **11% larger** than the markdown it was
> meant to replace; grouping it one row per item is what made it a saving at all.

---

## Which file to reach for

- **"Which hook fires when X happens?"** → `hooks.tsv`. It is the whole catalogue; grep the
  description column.
- **"What exactly does this hook give me, and what may I return?"** → `hooks.tsv` answers both in
  the `signatures` and `returns` columns. Only go to `../HOOKS.md` for the worked example body.
- **"How do I do <Oxide thing> in a plugin?"** → `api.jsonl`, grep `section` or `code`. It is every
  code example uMod publishes, addressed by page and heading.
- **"What is this item's id / short name?"** → `items.tsv`.
- **"What skins exist for this item?"** → `skins.tsv`, one grep, one line.

Read the markdown instead when you want the *reasoning* — the return-contract rules, the callouts,
the cautions. Those are deliberately not in here.

---

## Formats

All files are UTF-8 with LF endings and a header line. TSV fields are **tab-separated with no
quoting and no escaping** — tabs and newlines are stripped from values at generation time, so a
naive `split('\t')` is always correct.

### `hooks.tsv`

```
name  category  universal  returns  signatures  description
```

- **`category`** — one of the 20 uMod subcategories (`Server`, `Player`, `Entity`, …).
- **`universal`** — `1` for the 34 uMod *universal* (Covalence) hooks, which fire identically on
  every game uMod supports; empty for Rust-specific ones. This is the portable/non-portable split.
- **`returns`** — the return contract, normalised to one of five codes:

  | Code | uMod's wording | What to declare |
  |---|---|---|
  | `none` | *No return behavior* | `void`. Nothing you return is read. |
  | `nonnull` | *Returning a non-null value overrides default behavior* | `object`. `null` proceeds; anything else cancels. |
  | `bool` | *Returning true or false overrides default behavior* | `object`. `null` abstains — `false` is **not** abstaining. |
  | `data` | *Returning a string will kick…*, and similar | The value is consumed as data, not just as a veto. |
  | `?` | upstream states no return behaviour at all | 3 hooks. Not a guess — genuinely absent. |

- **`signatures`** — every declaration uMod publishes for the hook, joined by ` ;; `. Twelve hooks
  have more than one (overloads); the rest have exactly one. Extracted by matching the hook's own
  name, so no body line is ever mistaken for a signature.
- **`description`** — the descriptive bullets, joined by `; `, with the return-behaviour bullet
  moved into `returns`.

### `items.tsv`

```
shortname  item_id  display_name
```

Sorted by short name. **`shortname` is the only key safe to persist** — see
[`../DEFINITIONS.md`](../DEFINITIONS.md) § Which key to use.

### `skins.tsv`

```
item_shortname  skins (id=name;id=name;...)
```

**One row per item, not per skin** — 104 rows covering 2,590 skins. A `;` inside a skin name is
replaced with `,` so the field splits cleanly.

### `api.jsonl`

One JSON object per line, one object per code example uMod publishes:

```json
{"page":"api/timers","section":"Single timer","lang":"csharp","code":"timer.Once(1f, () =>\n{\n    Puts(\"Hello world!\");\n});"}
```

- **`page`** — the uMod path, e.g. `api/permissions`. Prefix with `https://umod.org/documentation/`
  for the source.
- **`section`** — the nearest heading above the example.
- **`lang`** — `csharp`, `json` or `text`.

This is the *examples only*. The prose that explains them is in `../OXIDE_API.md` and
`../OPERATING.md`, which is exactly the trade that makes it 47% of the size.

---

## Regenerating

These are build outputs, not hand-edited files. Re-capture and regenerate together —
[`../README.md`](../README.md) § Provenance and refreshing has the procedure. **Never edit a file
here by hand:** it will be silently overwritten on the next capture, and it would put the machine
copy out of step with the markdown, which is the one thing this directory promises cannot happen.