# AGENTS

## Repo Purpose (verified)
- This repo is an automation utility for VMess preferred-domain rotation: fetch API candidates, pick one domain, write runtime artifacts, then let Sub-Store/V2Ray consume them.
- Main entrypoint is `scripts/domain_updater.py`; optional post-processor for VMess links is `scripts/update_vmess_links.py`.
- Scheduled runtime entrypoint is `scripts/run_update_and_commit.sh` (runs updater, then commits only when domain changed).

## High-value Files
- `config.json`: active runtime config (single source for runtime settings).
- `runtime/current_domain.json` and `runtime/current_domain.txt`: outputs consumed by Sub-Store/operator scripts.
- `substore/operator_template.js`: Sub-Store script-operation template using `$substore.http.get` and `scriptResourceCache`.
- `systemd/vmess-domain-rotator.service` and `systemd/vmess-domain-rotator.timer`: deployment templates (must customize user/path).

## Commands You Should Actually Use
- Syntax check after Python edits:
  - `python3 -m py_compile scripts/domain_updater.py`
  - `python3 -m py_compile scripts/update_vmess_links.py`
- Manual refresh run:
  - `python3 scripts/domain_updater.py --config config.json`
- Manual refresh + conditional git commit:
  - `bash scripts/run_update_and_commit.sh config.json`
- Update VMess links (`add` field) from selected domain:
  - `python3 scripts/update_vmess_links.py --input <in> --output <out> --domain-file runtime/current_domain.txt`
- Debian one-shot deploy/remove:
  - `sudo bash scripts/install_debian.sh`
  - `sudo bash scripts/uninstall_debian.sh`
- Local output smoke test endpoint:
  - `python3 -m http.server 8080 --directory runtime`

## Behavior/Gotchas That Are Easy To Miss
- For vps789 Top20, keep API ranking order (`scoring.use_api_order=true`) and keep only domains (filter IPv4 via `domain_filter.exclude_regex`).
- `healthcheck.enabled` may be intentionally `false` in vps789 mode; do not re-enable unless you want local TLS checks to override API ranking behavior.
- `domain_updater.py` fallback behavior depends on persisted `runtime/state.json` (`last_good_domain`). Do not delete this file in normal operation.
- `run_update_and_commit.sh` commits only when `runtime/current_domain.txt` changed before/after update.
- Sub-Store script preview may show no change if `NODE_NAME_REGEX` in `substore/operator_template.js` does not match node names, or if cached output is reused.
- In Sub-Store operators here, use `$substore.http.get(...)` (not plain `fetch`) for compatibility.

## Deployment Notes (systemd templates)
- Template service assumes:
  - Working dir: `/opt/vmess-domain-rotator`
  - User: `vmessrotator`
- Template timer interval is `12h` by default.
- Before enabling timer, adjust `User`, `WorkingDirectory`, and `ExecStart` in `systemd/vmess-domain-rotator.service` to match the real host.
- Enable flow: copy unit files to `/etc/systemd/system/` -> `systemctl daemon-reload` -> `systemctl enable --now vmess-domain-rotator.timer`.

## Editing Constraints For This Repo
- Keep secrets out of source snapshots/backups: avoid placing tokens in tracked/shared files.
- `runtime/` is operational output; avoid treating it as source-of-truth code.