diff --git a/AGENTS.md b/AGENTS.md index 5a408e2..0f4a258 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,9 @@ authorization. - Avoid unnecessary dependencies, network requests, and background services. - Never assume a development environment is safe for production operations. - Do not silently change configuration, permissions, or system state. +- The current public release line is v0.3.2. Verify source, tag, and package + metadata independently because the CLI/package version may lag the release + tag. ## 2. Wallet and Blockchain Safety @@ -60,10 +63,15 @@ as sensitive and potentially privileged. - Never print, commit, or transmit RPC authentication secrets. - Do not bypass the application's RPC allowlist. - Do not introduce unrestricted RPC execution interfaces. -- Keep the dashboard bound to `127.0.0.1`. -- Do not change dashboard binding to `0.0.0.0`, public IP addresses, or - unrestricted IPv6 interfaces. -- Use SSH tunneling for authorized remote dashboard access. +- Keep the dashboard bound to `127.0.0.1` by default. +- Optional LAN mode may add exactly one explicitly assigned private IPv4 + address. Wildcard, public, multicast, loopback, link-local, and IPv6 + bindings are not supported. +- Use `token_required` LAN authentication by default. `trusted_lan` is an + explicit operator choice and does not make read-only data private from other + reachable LAN clients. +- Never bind the dashboard to `0.0.0.0` or an unrestricted IPv6 interface. +- Prefer SSH tunneling for authorized remote dashboard access. - Do not add external telemetry or outbound transmission of node data without explicit approval and a security review. @@ -81,7 +89,8 @@ The project includes: - Node and staking intelligence processing. - Local data storage and read-only views. - Command-line utilities. -- A localhost-only dashboard. +- A dashboard that is localhost-only by default, with validated optional + single-address LAN mode. - Automated tests and installation documentation. Agents must verify actual module paths and interfaces from the repository before @@ -94,19 +103,24 @@ Do not invent APIs, configuration keys, commands, or database schemas. When helping users install GhostNode Tools: 1. Verify the operating system and Python version. -2. Follow the repository's current `INSTALL.md`. +2. Follow the repository's current `docs/INSTALLATION.md` and `INSTALL.md`. 3. Use an isolated Python virtual environment. 4. Prefer pinned dependencies and hash verification. 5. Keep application files separate from Ghost Core wallet data. 6. Never ask users to upload wallet files or RPC credentials. 7. Explain security implications before recommending configuration changes. -8. Use localhost-only dashboard access. +8. Use localhost-only dashboard access unless an explicitly reviewed, + authenticated LAN mode is required. 9. Verify installation using documented diagnostics. 10. Explain how to stop or uninstall the application without affecting Ghost Core. -The v0.1.0 release was validated against Debian 12 and Python 3.11. Agents -must not assume that other environments have been tested. +The v0.3.2 release documentation targets Debian 12 or supported Ubuntu with +Python 3.11. Agents must not assume that other environments have been tested. + +The public v0.3.2 tag may still expose the older `0.3.1` Python package/CLI +version string. Report this metadata limitation instead of silently changing +version claims or release contents. Do not automatically install packages, change firewall rules, create services, or modify system configuration without appropriate user authorization. @@ -115,7 +129,8 @@ or modify system configuration without appropriate user authorization. Before making changes: -- Inspect `README.md`, `INSTALL.md`, and relevant source files. +- Inspect `README.md`, `docs/INSTALLATION.md`, `INSTALL.md`, and relevant source + files. - Check the current Git branch and working tree. - Identify whether the environment contains production services or real wallet data. @@ -162,6 +177,11 @@ Prefer mocked RPC responses, synthetic fixtures, and temporary databases. Before publishing changes, run the applicable test suite and release validation checks. +For reward-related changes, include tests for exact atomic values, Ghost PoS +identification, 101-confirmation maturity, idempotency, reorg handling, and +the rule that PARTIAL, UNKNOWN, UNVERIFIED, or ORPHANED data cannot increase +confirmed income. + ## 8. Data and Privacy Node information and staking statistics may reveal operational or financial @@ -180,6 +200,10 @@ Agents must: The public donation address in the README is intentionally published. Its presence does not authorize access to the owner's wallet. +The private Donations observer and dashboard wrapper are deployment-local +extensions. They must remain outside public source exports, release archives, +and pull requests. + ## 9. Documentation Standards All public-facing project materials must use clear English. @@ -199,6 +223,10 @@ capabilities, and future plans. Do not present proposed features as available functionality. +Document the distinction between wallet-owned staking rewards and network-wide +block reward components. With `txindex` disabled, unavailable network-wide +components must remain NULL/UNKNOWN rather than being inferred. + ## 10. Release and GitHub Operations Agents must not independently: @@ -248,7 +276,23 @@ Never treat a request for diagnostics as permission to make production changes. For high-risk or irreversible operations, explain the impact and recovery procedure before proceeding. -## 12. Agent Communication +When production changes are explicitly authorized, preserve the current +runtime, private configuration, SQLite database, locks, logs, backups, and +private Donations integration separately from public application source. Back +up affected files and database state before a cutover, verify one collector +instance, and keep a tested rollback path. Documentation-only changes do not +require a service restart. + +## 12. Current Operational Boundaries + +- The public application is read-only with respect to Ghost Core and wallets; + it does not create, unlock, encrypt, restore, or transact with wallets. +- Collector writes are limited to the configured local SQLite intelligence + database and must preserve atomicity, idempotency, and reorg handling. +- Production-only services or wrappers must never be inferred from the public + checkout; inspect their effective systemd unit and private configuration. + +## 13. Agent Communication Agents should communicate clearly and distinguish: