> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootroute.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Code style, commits, changelog maintenance, and the release process.

## Language and style

* **English only** — code, comments, commits, docs.
* **Framework code** (everything outside `Gatherer/`) is structured with `---@` annotations and `volvox.*` namespacing — match it.
* **Gatherer core files** are predominantly globals, mixed indentation, and terse names (`scan`, `avoid`, `Fishi`, `Spore`). Copy the indentation character and block style of the nearest enclosing function in the same file. Do not reformat existing lines.
* New Gatherer-internal helpers are named `Gatherer<Thing>`.

## Commits

Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) with a scope:

```
feat(gatherer): add underground node retry TTL
refactor(framework): resolve file API through ResolveApiFunction
docs: document the state machine
```

## Changelog

`CHANGELOG.md` follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). Add an entry only for a **user-facing change** — anything users can see or experience.

This includes changes to bot behavior, reliability, performance, UI or visible text, settings or defaults, user-facing logs, public commands or APIs, installation, compatibility, security, and public documentation that materially changes how users install, configure, or use LootRoute.

Do not add entries for internal refactors, tests, tooling, repository housekeeping, or agent/development-process guidance unless they have an observable user effect. For mixed changes, describe the user impact rather than implementation details.

Entries stay under `## [Unreleased]` until a release is explicitly cut, using the standard categories: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.

Every released version uses the heading `## [X.Y.Z] — Release Name - YYYY-MM-DD`. Choose a short, unique gathering pun tied to the release's standout theme.

## Releases

Releases are cut with `scripts/changelog-release.sh`:

<Steps>
  <Step title="Determine the bump level">
    Scan `[Unreleased]` entries: any `BREAKING:` / `[breaking]` → **major**; else any `### Added` entries → **minor**; else → **patch**. An explicitly requested level or version wins.
  </Step>

  <Step title="Choose a release name">
    Pick a short, unique gathering pun tied to the release's standout theme.
  </Step>

  <Step title="Run the script">
    ```sh theme={null}
    scripts/changelog-release.sh [level-or-version] [YYYY-MM-DD] "Release Name"
    ```

    For example:

    ```sh theme={null}
    scripts/changelog-release.sh auto 2026-08-01 "Mulch Ado About Nothing"
    ```

    The script requires a nonblank, single-line name. Maintainers are responsible for following the short, unique gathering-pun convention.
  </Step>

  <Step title="Confirm">
    Verify the version, release name, and date in the canonical `## [X.Y.Z] — Release Name - YYYY-MM-DD` heading in `CHANGELOG.md` before committing.
  </Step>
</Steps>

## Verification checklist

Since there is no runtime harness, every change must:

1. Pass the [static tooling](/development/tooling): `selene . && stylua --check . && biome check .`
2. Not break the load order (`loadorder.json`) — a file may only reference symbols defined by files above it.
3. Preserve `volvox.*` contracts.
4. For logic changes: identify the specific in-game trigger (bot state, object type, or user action) and the observable outcome (log message, state transition) that confirms the change works.