cockatrice-custom-tokens/AGENTS.md

2.9 KiB

Repository instructions

Purpose and layout

  • Maintain custom Cockatrice sets and artwork with the eventual goal of automatic installation and updates.

  • Edit sets/<SET_CODE>/set.toml metadata, topic files such as command_zones.toml, and images in its artwork/ directory. Declare [set] once per set; use [[tokens.alternatives]] for additional artwork of the same token. TOML is the authoritative editable source; never hand-maintain XML in sets/. scripts/generate_xml.py generates XML under dist/sets/. Preserve stable token IDs, imported UUIDs, and published XML filenames when updating content. Archives are historical snapshots, not a second source to maintain.

  • Building requires Python 3.11+ (tomllib) and Pillow from requirements-build.lock. Activate .venv before building/testing; the client installer remains 3.8+.

  • Render reminder text from [tokens.render] with scripts/render_cards.py. Keep blank templates in templates/, bundled fonts and licenses in assets/fonts/, and rendered images only under dist/. Reject overflow instead of clipping text. Cite official rules and record the reviewed date for rules reminders.

  • Build ZIPs using python3 scripts/build.py; do not hand-edit ZIPs or commit generated dist/ contents.

  • Keep deploy.sh and deploy.ps1 as non-mutating mocks until real deployment is explicitly requested. Keep their behavior consistent.

  • Maintain the real client installer in scripts/install.py; install.sh and its checksum manifest are generated by scripts/publish.py prepare. Preserve the interactive path checks, staged validation, explicit destination logging, and rollback behavior. Run python3 -m unittest discover -s tests -v after changes.

  • Update README.md when layout or supported behavior changes. Distinguish working features from planned installation and updates.

  • config/servatrice/ is for manual configuration safekeeping only. Never wire it into CI deployment, token publication, or the client installer. Keep credentials out of Git; preserve private originals separately. Do not migrate a server database or replace its container without a verified backup and upgrade plan.

Validation and commits

  • Run python3 scripts/build.py, python3 scripts/generate_xml.py --check, and python3 -m unittest discover -s tests -v after source or packaging changes. Check Bash syntax and run the preview after changing deploy.sh. Validate deploy.ps1 using PowerShell when available, and report when unavailable.
  • You shall make a Git commit for every completed modification or user request that changes this repository. Group edits for one request into a coherent commit with a descriptive message after appropriate validation.
  • Commit only files belonging to the request and preserve unrelated user changes. Do not amend or rewrite existing commits unless requested.
  • If a commit cannot be created, report the blocker rather than claiming success.