wireguard-admin/AGENTS.md

Agent Instructions

Start here

These instructions apply to the entire repository. Keep documentation, code comments, and identifiers in English; use the user's language in conversation.

The project currently contains design/configuration documents, not an implemented Rust application. Update this statement when scaffolding is created. Do not report planned code, tests, or commands as already working.

• Read SPEC.md and CONTEXT.md before implementing behavior. The approved specification is the product contract; do not change it to make tests pass.
• For milestone execution, read and maintain PLANS.md, following IMPLEMENTATION.md. Execute numbered milestones sequentially through implementation, independent review, repair, and acceptance with evidence.
• Read the relevant ADRs: explicit restart, client secrets, server configuration authority.
• Read task-specific supporting documents below before editing that area. Their requirements remain applicable; moving them out of this file does not make them optional.
• Preserve unrelated user changes. Resolve specific requirement conflicts before implementing affected behavior; continue independent work. Do not reopen settled decisions or seek approval for routine implementation choices.

Non-negotiable behavior

• Native Rust TUI, root management, one existing WireGuard interface, configurable systemd service. No production experimentation, remote management, server bootstrap, concurrent edit reconciliation, or automatic restart rollback.
• Public keys identify clients; aliases may repeat. The server configuration is authoritative. Modify only client [Peer] sections and managed metadata blocks; preserve all other settings and administrator comments byte-for-byte. Do not fully reserialize through a generic INI writer.
• Commit saves files/vault only. Restore also changes saved state only. Neither may reload, sync, restart, or mutate the running VPN. Keep draft, saved, and applied states distinct.
• Restart is explicit. Require successful systemd job completion and interface/client verification before marking applied or releasing deleted-client addresses.
• Complete a backup before every Commit, restore, and restart; backup failure stops the operation before protected mutations. Restore is a previewed, confirmed full replacement without a vault password or implicit restart.
• Preserve original imported files. Report anomalies rather than repairing them silently. New clients get IPv4/IPv6 and full-tunnel routes; preserve existing client parameters and IPv4-only clients.
• Settings are executable-relative; default working data is Backup/data, archives Backup/archives. Never substitute working-directory or system-wide defaults.
• Encrypt new secrets without a password using the vault public key. Protect the separate vault secret key with a password. Reissue requires a password per client; retained plaintext files must not bypass it. First delivery follows Commit and supports retry after file failure within the creation session.
• Never expose secrets through logs, errors, Debug, or snapshots. Explicit file/QR delivery is the disclosure path. Use synthetic fixtures only; keep real keys/configs/output and working backups out of version control.

Development rules and reference map

When working on	Read first
Module layout and boundaries	PROJECT_LAYOUT.md
Dependencies, Cargo features, build/runtime requirements	DEPENDENCIES.md
Rust, persistence, secrets, archives, terminal behavior	DEVELOPMENT.md
Tests, acceptance evidence, Alpine containers, systemd VM	TESTING.md
Codex model configuration and custom roles	CODEX.md

• Start with one Cargo package, thin main.rs, and testable library modules. Separate domain/application logic from filesystem, cryptography, WireGuard, systemd, and TUI adapters. Create modules as needed, not as empty scaffolding.
• Dependencies outside the approved list require comparison of alternatives and explicit user agreement before changing manifests/lockfiles. Approved crates may be added when needed without asking again. Apply the rule to runtime, build, and development dependencies.
• Select compatible versions/minimal features using official documentation; retain Cargo.lock and avoid unrelated upgrades. Use established cryptography, not custom primitives.
• Use typed errors/Result; avoid panics for recoverable input/I/O failures. Validate boundary inputs, escape terminal control text, and keep errors secret-free. Bound external operations; never execute configuration text through a shell.
• Create secret files/private directories with 0600/0700, including temporary files. Handle partial writes honestly; validate archive destinations and reject traversal/link escapes.
• Keep TUI input/rendering responsive, restore the terminal on errors/exit, mask passwords, and identify destructive targets unambiguously. Cancel preserves drafts; never silently commit on exit. Help/version require neither root nor vault access.

Agents and acceptance

Coordinator: GPT-6-Sol / medium. Implementation, independent review, repairs, and optional exploration: GPT-6-Luna / high, using the configured implementer, reviewer, repairer, and explorer roles. Configure actual models through the harness; do not impersonate or silently substitute them.

The coordinator owns task boundaries, PLANS.md updates, and acceptance. Default to one writer; parallel writes require disjoint ownership. Use a separate reviewer from the implementer, repair actionable findings, and verify integrated results before advancing. Do not create Git commits, publish, or deploy merely because a milestone is accepted.

Build/test without root by default. Never read production private keys, modify production configuration, restart host services, or use the live VPN for testing. Alpine Testcontainers suites are opt-in and isolated; actual systemd/D-Bus acceptance requires a disposable VM. Unavailable prerequisites mean incomplete validation, not success.

After Rust scaffolding exists, run focused behavioral checks and these completion gates for Rust changes:

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo build --locked --release

Do not assume all feature combinations are supported. Documentation-only edits require link/consistency checks, not an application rebuild. Report what changed, actual checks/results, and remaining limitations; distinguish fixture, Alpine, and VM evidence. Maintain the plan before handoff and never claim a milestone complete with unmet acceptance criteria.