From f412ca0241e77ab737c72909af0d3df2909a7d27 Mon Sep 17 00:00:00 2001 From: Titus Date: Sun, 22 Nov 2026 02:34:03 +0100 Subject: [PATCH] AGENTS.md: a standing text for a builder What the repository is, the gates in the order CI runs them, how a change reaches main, which files are generated or load-bearing and what to run instead of editing them, where to stop and ask, and what a finished pull request says. Read cold by an agent with no other context before it went in. Co-Authored-By: Claude Fable 5.2 --- AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3afb664 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,64 @@ +# Working in this repository + +## What this repository is + +The source of the OnlyWorlds documentation site, https://onlyworlds.github.io, built with Astro Starlight. A push to `main` builds the site and deploys it to GitHub Pages through `.github/workflows/pages.yml`, so a merge is a release. The pages are Markdown in `src/content/docs/`; how the parts fit is in `README.md`. + +## Set up and run the gates + +CI uses Node 22 and Python 3.12. Every command here runs from the repository root in a POSIX shell (Git Bash on Windows) and needs the network. Work in a full clone, not a shallow one, and `git fetch origin` first. Set up once, then run the gates before you call a change done: + +```bash +npm ci +pip install pyyaml +node scripts/gen_sdk_ref.mjs --check # the TypeScript reference matches the pinned SDK +node scripts/gen_errors.mjs --check # the errors table and contract floor rows match the snapshot +npm run check # npm run build, then npm run verify +node scripts/verify-commit-words.mjs origin/main..HEAD # your commit messages +``` + +`npm run check` is the main local gate; it ends with `mutants-run: PASS`. The build runs the two generators without `--check`, so it rewrites the generated parts of two tracked files when they are behind: if `git status` shows a file you did not mean to change, do not commit it; say so in your pull request. Run `npm run verify` alone only right after a build: on a build older than any source file it answers `CANNOT SEE` with exit 2, which is not a pass. Run one build at a time. + +`main` requires two checks: `build` (in `.github/workflows/ci.yml`: install, then `npm run build` and `npm run verify`) and `check` (in `.github/workflows/generated.yml`: the two `--check` commands above). A pull request also runs `commits` (`.github/workflows/commits.yml`, the commit-message check), which is not required but must be green. + +The `build` job also runs report-only steps against the live API, the MCP server, schema-dist and PyPI. They print a warning and never fail the job; you do not need to run them. Two of them, as CI runs them: + +```bash +git clone --depth 1 https://github.com/OnlyWorlds/schema-dist ../schema-dist-clone +python scripts/gen_elements.py --dist ../schema-dist-clone --check # exit 1 means pages in git are behind; report only +pip install onlyworlds mypy +python scripts/verify-examples-py.py # without mypy it prints BLIND and exits 2: not a pass +``` + +Exit codes across `scripts/`: 0 pass, 1 a finding (FAIL or STALE), 2 BLIND or CANNOT SEE (the check could not read its source; never a pass). `npm run verify` also compares several snapshots with the live API document and prints `STALE` without failing; mention any `STALE` line in your pull request. + +## How a change reaches main + +Make a branch, open a pull request, and wait for the required checks to go green. `main` refuses a direct push; the rule has no bypass. Never push to `main`. Never create or push a tag: the deploy tags itself, and a tag is how a rollback is run. Never edit a file under `.github/workflows/`. Never change a version number, a dependency pin in `package.json`, the dated headings of `src/content/docs/docs/changelog.md`, or the version and changelog lines at the end of `public/assets/ow_llm_guide.txt`, unless the job says so. + +## What must not be hand-edited + +- `dist/`: build output, not committed. +- `src/content/docs/docs/development/typescript.md` below its `generated:sdk-reference` marker: written by `node scripts/gen_sdk_ref.mjs` from the pinned `@onlyworlds/sdk`. +- `src/content/docs/api/errors/index.mdx` between its `generated:error-codes` markers, and the `floor` rows of `contract/urls.tsv`: written by `node scripts/gen_errors.mjs` from `contract/error-codes.json`. +- `src/content/docs/docs/schema/element_categories/*.md` below their `generated:fields` marker, and `contract/folder-example.json`: written by `python scripts/gen_elements.py --dist `. Every deploy regenerates them from a published tag of schema-dist; leave them alone unless the job is about them. The field descriptions are the standard's own text: a change to one belongs in https://github.com/OnlyWorlds/OnlyWorlds. +- `contract/*.json` snapshots. Each is refreshed by its script, never by hand: `error-codes.json` (`node scripts/gen_errors.mjs --refresh`), `callers.json`, `signin.json`, `time.json`, `write.json`, `draught.json`, `proposals.json` (`node scripts/gen_.mjs --refresh`), `mcp.json`, `cors.json`, `toolkit.json`, `shapes.json`, `limits.json`, `sd-counts.json` (`node scripts/verify-.mjs --refresh`). `palettes.json`, `public.json` and `practice.json` are read from the server's private code and cannot be refreshed from a clone: stop and ask. +- `contract/urls.tsv` and `contract/old-urls.tsv`: every address the site serves is load-bearing. Never remove a row, move a listed page, or turn one into a redirect stub. `README.md` ("Old URLs are part of the contract") explains the row kinds. +- `package-lock.json`: changes only with a dependency change, which is a stop-and-ask. + +## Words + +Everything here is public, the commit messages included. `scripts/verify-public-words.mjs` (in `npm run verify`) reads the built site in `dist/` for words public text may not carry, its list in `scripts/public-words.mjs`; it does not read root files such as this one. `node scripts/verify-commit-words.mjs origin/main..HEAD` holds your commit messages to the same list; it needs full history, and on a shallow clone it exits 2. A commit message says what the change does and why. It names no private repository, person or internal ticket. The terms the pages use are in `SWEEP.md` ("The terms"). + +## Where to stop and ask + +Stop, do not guess, when the job would need any of these: a change to a file in the list above; a new dependency; a change to public behaviour the job did not name, such as a page's address or what a sample does; a failing gate you cannot explain, one that also fails on `origin/main` included (it is not yours to fix); two readings of the job that give different changes. Write the question as one comment on your pull request (with no pull request yet, in a file `ASK.md` at the root of your branch). Ask one question, push your branch as it stands, then end your turn. + +## What a finished job looks like + +The pull request's description says: + +- what changed, and why; +- each gate you ran, with its last line of output; +- what you did not run, and why; +- a list headed "Looked wrong, left alone": anything outside the job that seemed wrong.