# Project Instructions
## Code Changes
- Add concise comments at important rules, invariants, protocol details, and non-obvious decisions. Do not add comments that merely restate the code.
- Do not overuse tuples. When a tuple has several fields or its values have distinct meanings, use a named `struct` instead. Small tuples are acceptable for simple, obvious pairs.
- Keep the project skill synchronized with the implementation. The skill at `.agents/skills/rust-codebase-navigation/SKILL.md` is developed from this project, so update it in the same change whenever commands, flags, workflows, or supported behavior change.
## Development and Verification
- Use `cargo run -- ...` for development and CLI verification. Do not run a stale binary directly from `target/debug`.
- Before finishing a change, run:
```powershell
cargo clippy
cargo fmt
```
## CLI Output and Usability
- Treat `--help` output as part of the public interface. Every command and option must have a clear description, required/optional indication, default value, accepted values, and at least one practical example when the usage is not self-evident.
- Help text must explain project-specific conventions that affect input, such as workspace-relative paths, 1-based line and column numbers, daemon prerequisites, ports, output modes, and the meaning of an empty result.
- Error output must identify what failed, the relevant file/command/endpoint or input when available, and the likely cause. When the user can take a corrective action, include the exact next command or a concrete remediation step.
- Do not replace actionable errors with generic messages such as `operation failed` or `invalid input`. Preserve useful underlying error context while keeping the final message readable.
- Status, progress, and confirmation messages must state the operation and its result clearly. Distinguish successful completion, initialization/in-progress state, warnings, and failure; do not make the user infer state from silence.
- Human-readable output and JSON output are separate interfaces. Human mode may include explanatory labels and next steps; `--json` mode must write valid, stable, machine-readable JSON to stdout without log noise, decorative text, or mixed output.
- Use `null` or an explicitly documented empty collection for a valid query with no result. Reserve errors and non-zero exit codes for failed operations, invalid input, unavailable dependencies, or unavailable services.
- Add or update tests for user-facing help, error, and output behavior when changing CLI commands, flags, response formats, or workflow requirements. Keep the README and project skill synchronized with those changes.