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.
- Use the installed `android-emulator-debug` skill for Android emulator lifecycle, `adb`, screenshots, and log capture work.
- Use the repo-local `keepassgo-apk-test` skill for KeePassGO-specific APK build and emulator test runs.
- 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.
- Keep the product feeling like the same application on desktop, Android phone,
  and Android tablet.
- Platform adaptation is allowed for layout and spacing, not for changing the
  user's mental model of the workflow.
- Use the same action names, the same primary next steps, and the same workflow
  order across platforms unless there is a hard platform constraint.
- Treat workflow prominence and reachability as product behavior, not visual
  polish. A feature is not parity-complete if it technically exists but is
  harder to discover or reach on one platform.
- Prefer shared workflow decisions with platform-specific presentation, rather
  than platform-specific workflow branches.
- Make all test strings `Heist Movie` themed. Use characters, crews, casinos,
  vaults, and locations from heist movies so test fixtures stay obviously fake
  and consistent with the product theme.

## 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.
- For cross-platform UI work, behavior tests must cover workflow parity, not
  just feature or label parity.
- For lifecycle, open, unlock, sync, and other primary flows, tests should
  assert the same conceptual next step across desktop, phone, and tablet
  layouts.
- When Android or phone UX is part of the slice, verify real reachability on an
  emulator or device for the exact flow being changed. Do not count “the same
  buttons exist somewhere on screen” as sufficient validation.
- 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.
- Keep the Android build requirements aligned with the known working setup:
  `ANDROID_SDK_ROOT=/opt/android-sdk`,
  local `ANDROID_NDK_ROOT=/opt/android-ndk`,
  CI `ANDROID_NDK_ROOT=/opt/android-sdk/ndk`,
  local `JAVA_HOME=/usr/lib/jvm/java-25-openjdk`,
  CI `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64`.
- Remember the known Android runtime regression:
  `gioui.org v0.9.0` produced a black screen on the `KeepassGoAPI35` emulator, while `gioui.org v0.8.0` rendered correctly. Treat Gio upgrades on Android as regression-sensitive and verify them on-device or in the emulator.
- When validating an APK in the emulator, prefer the known KeePassGO setup:
  AVD `KeepassGoAPI35`,
  package `org.julianfamily.keepassgo`,
  activity `org.gioui.GioActivity`.
- Do not run emulator/manual APK tests against the user’s real persisted app state.
  Use an isolated `KEEPASSGO_STATE_DIR` for host-side validation, and when emulator testing requires seeded vault data, use sanitized test/demo vaults rather than the user’s real vault files whenever possible.
- 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 assume the agent can decrypt SOPS-encrypted secrets in this repository.
- If work requires plaintext from a SOPS-encrypted secret, stop and ask the user to decrypt it or otherwise provide the needed plaintext.
- Do not commit generated binaries.