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 contains a Rust package with startup, settings validation, a pure client domain model, a byte-preserving WireGuard configuration editor, encrypted vault and read-only import APIs, saved-file persistence with recovery, backups, Commit, and previewed restore. The management interface and VPN runtime operations are not implemented yet. Do not report planned modules, 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

Use the pinned Rust toolchain and environment checks in ENVIRONMENT.md. System-packaged tools do not automatically honor rust-toolchain.toml.

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.