Agent Guidelines

Getting started

This repository uses Yarn 4 (Berry) in classic node_modules mode (Plug'n'Play is disabled). Install dependencies with yarn install --immutable.
A postinstallDev script runs Beemo with the @niieani/scaffold configuration to materialize local config files after install. If you ever need to regenerate those scaffolds manually, run yarn postinstallDev.
The primary verification flow matches the CI workflow in .github/workflows/ci-cd.yml: run yarn build followed by yarn test when practical. The yarn test command runs formatting, type-checking, linting, and unit tests.
Use the existing formatting and linting tools instead of manual formatting. Prettier and ESLint configurations are already provided. Make sure to run yarn format before committing changes.

To run tests, or run any command that requires the internet, you must execute the task with {with_escalated_permissions: true}.

The following outputs are generated by scripts and must not be edited manually:
- src/bpeRanks/**/*.js — generated from the .tiktoken files in data/ via yarn codegen:bpe (src/codegen/generateJsBpe.ts).
- src/model/**/*.ts — generated from the encodings in src/encoding/ via yarn codegen:models (src/codegen/generateByModel.ts).
- src/modelsChatEnabled.gen.ts — generated from src/models.ts via yarn codegen:chat-enabled (src/codegen/generateChatEnabled.ts).
Generated files now contain a header comment describing the owning script and the command to regenerate them. Always modify the source templates or data (e.g. files under src/codegen/, src/encoding/, or data/) and rerun the corresponding script instead of editing generated outputs directly.

TypeScript source lives under src/. Common entry points are src/main.ts and the modules in src/encoding/.
Tests are written with Vitest (yarn test:code). Snapshot files reside next to their test files inside src/__snapshots__.
Keep the repository compatible with both ESM and CommonJS builds; avoid introducing Node-specific globals without appropriate guards.

Include clear descriptions of functional changes and reference any relevant commands run locally.
When adding new scripts or codegen steps, update this file if they produce additional generated artifacts.