# 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](docs/SPEC.md) and [CONTEXT.md](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](PLANS.md), following [IMPLEMENTATION.md](docs/IMPLEMENTATION.md). Execute numbered milestones sequentially through implementation, independent review, repair, and acceptance with evidence.
- Read the relevant ADRs: [explicit restart](docs/adr/0001-explicit-restart.md), [client secrets](docs/adr/0002-client-secret-storage.md), [server configuration authority](docs/adr/0003-server-config-authority.md).
- 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](docs/PROJECT_LAYOUT.md) |
| Dependencies, Cargo features, build/runtime requirements  | [DEPENDENCIES.md](docs/DEPENDENCIES.md)     |
| Rust, persistence, secrets, archives, terminal behavior   | [DEVELOPMENT.md](docs/DEVELOPMENT.md)       |
| Tests, acceptance evidence, Alpine containers, systemd VM | [TESTING.md](docs/TESTING.md)               |
| Codex model configuration and custom roles                | [CODEX.md](docs/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:

```sh
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.