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.
• Treat the vault model as local-first across all platforms: every usable vault is a local KDBX file first, and remote sync attaches to that local vault rather than replacing it as the primary object.
• Keep the remote-sync model standardized across desktop, Android phone, and Android tablet: shared remote configuration belongs in the vault, cross-platform workflow stays the same, and only Android's initial KDBX share/import transport may differ.
• Do not persist remote credentials in plaintext app-local state. Keep only non-secret binding metadata outside the vault.
• When working on remote-sync behavior, preserve the local cache / local-first design: opening or creating the local vault is the main workflow, and remote setup, remote settings, and remote use attach to that vault.

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.
• Keep remote configuration and synchronization local-first: the app should maintain a live local KDBX cache even when using a remote store, so remote outage does not eliminate vault access.
• Prefer vault-backed remote setup and lookup over ad hoc local credential storage.
• On Android, use system picker/share mechanisms for local vault import/export rather than raw path entry when a user is selecting or sharing a vault file.

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.
• For the Arch package, treat packaging/archlinux/keepassgo-git/PKGBUILD.tmpl as the source of truth and regenerate PKGBUILD from the template before building.
• 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.