# Repository instructions

## Architecture boundary

`crates/storage` owns all password-store behavior and all objects stored in or
derived from a password-store repository. This includes filesystem layout,
`.gpg-id` handling, GPG-compatible encryption and key handling, Git,
synchronization, conflict handling, entry parsing, password generation, OTP,
QR payloads, server/application identities, HTTPS Git credentials, and
secure-secret-storage orchestration. Git remotes are HTTPS-only; reject other
schemes before entering the Git transport.

The CLI, Ratatui, Iced, Swift, SwiftUI, AutoFill, and watchOS code may collect
input, invoke the Rust API, and present Rust-provided state. They must not
duplicate storage rules, derive domain state from display strings, or directly
read or mutate a password-store repository.

Application code must not launch external processes. Do not invoke `pass`,
`git`, `gpg`, shell commands, or helper executables. Use pure Rust libraries.
Use FFI only where an operating-system API has no feasible Rust interface,
such as Apple authentication and secure-storage APIs; keep domain decisions in
`crates/storage`.

Keep project crates free of `unsafe` Rust. Isolate any unavoidable future FFI
implementation in the smallest platform-specific module and document its
safety contract.

## Compatibility

Compatibility means the upstream `pass` repository format and observable
behavior, including `pass-otp`; IronStorage must not introduce a competing
on-disk format. Prove new behavior with fixtures usable by both upstream tools
and `crates/storage` without executing those tools at application runtime.

## Required checks

Run these from the repository root before committing:

```sh
cargo fmt --all -- --check
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

For Apple project changes, also run `xcodegen generate` from `apple/` and build
the affected simulator targets.