keepassgo/AGENTS.md

# Product Requirements

These instructions apply to all future work in this repository.

## Product Intent

- Build the product under the user-facing name `KeePassGO`.
- Build a real password manager product in Go.
- Keep Windows and Linux as first-class desktop targets.
- Keep Android as a future target, but do not distort the desktop product to chase Android prematurely.
- Preserve compatibility with KeePass/KDBX so the app can coexist with KeePass2Android.
- Use maintained upstream libraries for KDBX parsing, crypto, and other behavioral requirements when a maintained library is a good fit.

## Skills

- Use the installed Go skills whenever they materially apply to the current slice of work.
- The available Go skills for this repository are:
  `go-code-review`,
  `go-concurrency`,
  `go-context`,
  `go-control-flow`,
  `go-data-structures`,
  `go-declarations`,
  `go-defensive`,
  `go-documentation`,
  `go-error-handling`,
  `go-functional-options`,
  `go-functions`,
  `go-generics`,
  `go-interfaces`,
  `go-linting`,
  `go-logging`,
  `go-naming`,
  `go-packages`,
  `go-performance`,
  `go-style-core`,
  `go-testing`.
- In particular:
  use `go-testing` for test-first slices and behavior tests,
  `go-packages` for package boundaries and dependency layout,
  `go-linting` for `golangci-lint`,
  `go-code-review` when reviewing risky changes,
  `go-interfaces` for seams and test doubles,
  `go-error-handling` for error contracts,
  `go-concurrency` and `go-context` for concurrent or cancellable flows,
  and the remaining skills whenever their topic is directly implicated by the work.

## Required Feature Parity Targets

These are the KeePass 2.57.1 capabilities that this product should explicitly target, subject to platform constraints.

- Database lifecycle:
  create, open, edit, save, save-as, and lock/unlock KDBX databases.
- Master key support:
  master password, key file, and composite master key support.
- KDBX compatibility:
  preserve interoperability with KeePass/KeePass2Android-compatible databases.
- Database security settings:
  support the major KeePass-style encryption and KDF configuration choices that are represented in KDBX databases.
- Groups and paths:
  nested groups, entry paths, and path-aware navigation.
- Entry fields:
  title, username, password, URL, notes, tags, and custom string fields.
- Search:
  current-group listing, global search, and search results with visible path context.
- Entry data transfer:
  copy username, copy password, copy URL, and password reveal/hide controls.
- Password generation:
  strong password generation with configurable rules and reusable profiles.
- Entry history and recycle semantics:
  support entry history and deletion/recovery behavior compatible with KeePass expectations.
- Attachments:
  store and retrieve file attachments in entries.
- Templates:
  support entry templates or an equivalent reusable-entry mechanism.
- Programmatic integration:
  provide a secure gRPC API for trusted clients such as browser extensions and local automation.
- Desktop automation:
  either provide a desktop login automation mechanism comparable in purpose to KeePass auto-type, or document why the secure gRPC integration surface supersedes it.
- Import/export:
  KDBX import/export is mandatory; additional import/export formats are desirable but secondary.
- WebDAV workflow:
  direct remote-file workflows must exist and be treated as a first-class product feature.
- Accessibility and keyboard use:
  keyboard-first operation, high-DPI support, and screen-reader-conscious design.

These features are product requirements, not “nice to have” ideas.

## UX Direction

- Desktop and phone layouts may differ significantly.
- Desktop should optimize for information density and low-friction navigation.
- Phone should optimize for low tap count, not purity of mobile patterns.
- The stacked phone layout is the current preferred phone direction.
- Do not reintroduce the abandoned phone flow mode unless explicitly requested.

## Architecture

- Separate domain logic from Gio UI code.
- UI state should not be the source of truth for vault structure or search behavior.
- Domain packages must be test-driven where practical.
- Prefer behavior-oriented tests that describe expected product behavior rather than implementation details.
- Provide a secure gRPC API as a first-class programmatic surface, not as a thin wrapper around UI state.
- Design browser-extension and automation integrations against the gRPC API, not against ad hoc local protocols.

## Delivery Discipline

- Do not treat this product as complete until the stated requirements in this file are actually satisfied.
- Do not stop at a “good checkpoint” or “meaningful tranche” when required product capabilities are still missing.
- Continue iterating in test-first slices:
  add or extend behavior tests,
  implement the minimum code to satisfy them,
  verify with `go test ./...` and relevant lint checks,
  and commit each completed behavior.
- Only stop before the requirements are satisfied if the work is genuinely blocked by a missing decision, missing external dependency, or a hard technical constraint that cannot be resolved within the repo.
- If blocked, state the blocker concretely and stop only at that point.

## Persistence and Sync

- Plan for direct KDBX support.
- Plan for direct WebDAV-based workflows.
- Avoid adding npm-based or browser-stack dependencies.

## Tooling

- Keep `golangci-lint` passing.
- Keep `go test ./...` passing.
- Track `gogio` as a Go tool and keep a reproducible `make apk` path for Android packaging.
- When running tests or other automated validation that may touch persisted UI state, set `KEEPASSGO_STATE_DIR` to an isolated temporary directory so recent-vault history and other local state do not pollute the user’s real config.
- Prefer commands shaped like `KEEPASSGO_STATE_DIR=\"$(mktemp -d)\" go test ./...` for ad hoc local validation unless a test already manages its own isolated state directory.
- Do not commit generated binaries.