akbasic/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this
repository.

## Read MAINTENANCE.md first

**[`MAINTENANCE.md`](MAINTENANCE.md) is the authoritative document for changing this project**,
and it is written for whoever has to do the changing — human or agent. It carries what used to
live in this file: the project goals, the Go reference implementation and its architecture, the
dependency versions and their ABI rules, the four ways an embedded build collides, the
`libakerror` error convention, the coordinated error-code range map, the test lists, the
documentation-example harness, and the style and commit rules.

There is one copy of all of that, on purpose. Anything you would have added here, add there
instead — the maintainer needs it as much as you do, and a second copy is a second thing to
keep true.

`akbasic` is a C rewrite of the Go BASIC interpreter in `deps/basicinterpret`, written in the
idiom of the `ak*` C libraries it builds on, and meant to end up embedded in `libakgl` as a
scripting engine for game authors.

| Read | For |
|---|---|
| [`MAINTENANCE.md`](MAINTENANCE.md) | Everything above. Start here |
| [the issue tracker](https://source.starfort.tech/andrew/akbasic/issues) | **Outstanding defects and gaps.** Labelled by kind and blast radius; `status::grooming` means the scope is not settled yet |
| [`TODO.md`](TODO.md) | The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on |
| [`README.md`](README.md) | What the project is and why, for somebody who has not seen it |
| [`docs/`](docs/README.md) | The language itself: eighteen chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/` |
| `deps/libakerror/AGENTS.md` | The `ATTEMPT`/`CLEANUP`/`PROCESS`/`HANDLE`/`FINISH` protocol, authoritatively |
| `deps/libakerror/UPGRADING.md` | 1.0.0's status registry. Required before writing an error code |
| `deps/<library>/AGENTS.md` | Per-repo rules. Read the relevant one **before editing a submodule** |

Before doing anything else in a fresh clone:

```sh
git submodule update --init --recursive
```

## Rules that are on you rather than on a test

Most of the conventions in `MAINTENANCE.md` are enforced by something — a sorted-table test, a
`WILL_FAIL` list, a Doxygen gate, a byte-compared corpus. These are not, so they are worth
repeating where you will see them:

- **Add tests in the same commit as the behaviour change**, and assert the *correct* contract
  even where the code is currently wrong. A known-failing test goes in
  `AKBASIC_KNOWN_FAILING_TESTS` with an open issue; it does not get pinned to the buggy
  behaviour, because that turns the eventual fix into a test failure.
- **Never work around a missing dependency capability here.** Open an issue in that
  repository's tracker on <https://source.starfort.tech> — what the BASIC verb requires, what
  the entry point should look like, what tests would cover it. `MAINTENANCE.md` explains why,
  and names the four gaps this closed upstream. **Recording it here instead is not filing it**:
  two `akgl_ui` gaps sat in `TODO.md` for a release because changing a submodule is that
  repository's decision — which is true of changing it and not of reporting it.
- **Never edit generated output** — `build/` trees, the generated `akerror.h`, `akgl.pc`,
  `include/akgl/SDL_GameControllerDB.h`. Change the template or the generator script.
- **Do not reformat code you are not otherwise changing.** Several files mix tabs and spaces
  and there is no repo-wide formatter; style conversions get their own commit.
- **Do not edit `tests/reference/`.** Those expectations came from the Go implementation and
  are never edited to suit this interpreter. A deliberate divergence goes in
  `tests/reference/README.md`'s divergence table and `docs/13-differences.md`.
- **Open an issue for outstanding work; do not add it to `TODO.md`.**
  <https://source.starfort.tech/andrew/akbasic/issues>, or `tea issues create --repo
  andrew/akbasic`. Name the file and line, the functional consequence, and what closing it would
  touch. Publishing a problem you cannot fix yet is a contribution — and **when you learn
  something about an open issue, say so in the issue**, including that it is worse than
  recorded, already fixed, or resting on a premise that has expired.
- **Add yourself — program, model and version — as a commit co-author.** `libakgl`'s
  `AGENTS.md` requires it and this repository follows the same rule.