# Vault-Hier Development Guidelines

## Build & Test Commands
- Build & run: `cargo build && cargo run`
- Run server: `cargo run server`
- Run tests: `cargo test` (or `cargo test -- --nocapture` for verbose output)
- Run single test: `cargo test test_name -- --nocapture`
- Docker test: `./test_docker.sh` (includes vault initialization)
- Local test: `./test_local.sh` (sets up local vault)
- Lint: `cargo clippy -- -D warnings`
- Format: `cargo fmt --all`

## CLI Commands
- Start server: `cargo run server [--vault-addr URL] [--api-port PORT]`
- Login: `cargo run login --username USER --password PASS [--api-url URL]`
- Upload document: `cargo run upload --name NAME --file PATH [--api-url URL]`
- Sign document: `cargo run sign --document-id ID --username USER --token TOKEN [--api-url URL]`
- Verify document: `cargo run verify --document-id ID [--api-url URL]`
- List documents: `cargo run list [--api-url URL]`
- Get document details: `cargo run get --document-id ID [--api-url URL]`

## Code Style Guidelines
- **Formatting**: Follow rustfmt conventions (run `cargo fmt` before committing)
- **Imports**: Group by crate (stdlib → external → internal)
- **Error Handling**: Use `anyhow` with descriptive messages; propagate with `?` or `thiserror` for actionable errors
- **Naming**: Snake case for functions/variables, CamelCase for types
- **Async**: Use Tokio for async runtime with structured task management
- **Logging**: Use `tracing` macros for structured logging (`info!`, `debug!`, `error!`, `warn!`, `trace!`)
- **Documentation**: Document public APIs with doc comments (`///`)

## Architecture Notes
- Modular design with separate services (document, vault, API)
- Hierarchical signing with department validation
- JWT-based authentication using Vault transit backend