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.

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.
• 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.