RIPDPI: Instructions file for Codex

AGENTS.md -- RIPDPI

Project

RIPDPI is an offline-first Android network-path diagnostics and performance toolkit. Jetpack Compose provides the UI, Android services own VPN/proxy lifecycles, and repository-owned Rust modules implement the native data plane, diagnostics, relays, tunnels, and JNI adapters.

Product principle

The standard is Linear's website or Apple Notes: a simple purpose, a simple architecture, a simple design, and a simple implementation.

Three people open every screen and every module: the user (UX), the developer who reads the code (DX), and the agent that edits it next (AX). A change must serve all three. A change that helps one by taking from another is not finished. "Simple" never means "broken": existing behavior, contracts, and gates stay intact.

• UX: cut taglines, helper text, and secondary labels. Remove any label that only explains the layout. If a screen needs a caption to make sense, the screen is broken: fix the layout, then delete the caption. Text that carries content, state, errors, consequences, or required disclosures stays; DESIGN.md defines the boundary.
• DX: one name and one owner for each concept, no layer that only forwards calls, and code that a new reader can follow without a guide.
• AX: one source of truth for each fact, so an agent finds it with one search and does not edit a copy that disagrees.
• Removing UI text is a full change: delete the string from every locale in the same commit, keep the element's accessible name, and expect Roborazzi baseline changes, which need approval under golden-bless-discipline.md.

Source of truth

• At task start and when you switch checkouts, run just checkout-doctor to discover the actual checkout root, branch, Git directories, worktree problems, and Rust-skill submodule state. Use its current paths instead of remembered checkout names. It is read-only; exit 1 means inspect the reported issue before proceeding. For a Git directory without a justfile, invoke scripts/checkout_doctor.py from an available checkout with the directory as its argument (--json lists every worktree).
• To locate guidance for a build, runtime, contract, UI, testing, release, or harness task, use the task-based documentation index.
• For cross-module or architecture work, start at docs/architecture/ARCHITECTURE.md and follow its links (NATIVE_RUST.md, JNI_CONTRACT.md, CONFIG_CONTRACTS.md, DIAGNOSTICS_ARCHITECTURE.md, FEATURE_EXTENSION_GUIDE.md) as the change requires.
• Derive protocol and relay claims from current Kotlin/Rust registries, schemas, tests, and crate existence. Old plans, README prose, and rollout notes are not authoritative when code disagrees.
• Native build properties come from gradle.properties; dependency versions come from gradle/libs.versions.toml; Rust membership and dependencies come from native/rust/Cargo.toml and cargo metadata --locked.
• Generated artifacts and reports are regenerated through their owning task or script, never hand-edited.