ark-stronghold-protocol/AGENTS.md

AGENTS.md

Entry point for AI coding assistants (Codex, Claude Code, Cursor, Copilot …) working on this repository. It only indexes the existing documents and their hard rules; when this file and a linked document disagree, the document wins. Human contributors: CONTRIBUTING.md is the same material in full.

What this is

A non-commercial fan remake of Arknights「卫戍协议：盟约」 that runs in the browser: a Node.js server (economy, rounds, rooms) and a deterministic battle sim shared by the server and the browser. It aims to be faithful to the official mode.

Read first

1. docs/ARCHITECTURE.md — the code map: where things live, data flow, golden results, import boundaries, where common changes start.
2. docs/DESIGN.md — the index of the rules: current rules in docs/design/, each release's revisions and their evidence in docs/history/.
3. The reference for the part you touch: docs/SIM.md (battle engine API, hooks, test harness), docs/META.md (match flow, shop, protocol), docs/DATA.md (generated data), docs/I18N.md (interface strings), server/sim/content/kits/README.md (operator kits).

Hard rules

• Official first. Rules come from the official data tables (.cache/gamedata/excel/ after setup) and PRTS. A detail no source settles is implemented the simplest way and marked [ASSUMED] in the code and the PR. Deliberate deviations from the official mode are the maintainer's decision only.
• Determinism. server/sim/ is plain ESM that runs in Node and in browsers: no Node APIs, no Math.random, no clocks, and no engine-approximated Math functions (use server/sim/detmath.js; ESLint and test/sim/detmath.test.js enforce it).
• Golden results. A refactor must not change test/golden/*.json. An intended gameplay change runs npm run golden:update in the same commit, and the commit / PR names every moved scenario and why (test/golden/README.md).
• Generated data. Never hand-edit data/*.json: change tools/build-data.mjs and regenerate.
• No game art in git. public/assets/ is ignored; never commit extracted or downloaded game files.
• Interface strings go through t('…'), with entries in every pack under public/i18n/ (node tools/i18n.mjs check --all --strict).
• Docs follow the code. A rule change updates docs/design/, the current docs/history/ file and the reference docs; run node --test test/docs-consistency.test.js test/docs-paths.test.js.
• Commits and PRs: one topic per PR; a one-line message of what changed (Chinese or English) with the issue number; no attribution trailers (Co-Authored-By:, Generated with …). The PR description states what, why, the sources, the [ASSUMED] points, the tests you ran (paste the summary lines) and the golden moves. No ads, payments or other monetisation — the project stays non-commercial.

Verify

Run the tests of what you touched first, then everything before opening the PR:

node --test test/<area>/<file>.test.js      # targeted
npm run ci                                  # the CI checks locally (tools/ci.mjs): node --test, smoke, lint, imports, types
npm run golden                              # golden results

Browser suites are off by default and need Chrome: SP_E2E=1 (UI), SP_REAL_E2E=1 (real match, needs assets), RENDER_E2E=1, SIM_E2E=1 — see CONTRIBUTING.md §2. Battle tests are easiest with the helpers described in docs/SIM.md (the test harness section) and the patterns in test/content/op_siege.test.js.