Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 55 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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:

Expand Down
Loading