github.com/KeeForge/KeeForge (link)

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

AGENTS.md

---
name: publish-app-store-version
description: Prepare and publish an already-built KeeForge version — iOS, macOS, or both — through the App Store Connect website. Use when the user asks to create or finish an App Store version, publish an uploaded build, prepare an App Review submission, stage everything before the final submit, or operate App Store Connect after the release/tag/CI workflow is complete. Covers build processing, export compliance, localized release notes, reviewer information and test

---
name: keeforge-github-issues
description: >
  Create, edit, comment on, close, reopen, classify, or change project fields for issues in
  KeeForge/KeeForge. Use whenever an action will mutate a KeeForge GitHub issue. Do not use for
  read-only issue searches or reviews that will not change GitHub state.
---

# KeeForge GitHub Issues

Apply this workflow before every GitHub issue mutation, including mutations requested as part of
another workflow. Keep the mutation within the user's authorized scope.

##

---
name: spec-creator
description: >
  Turn a feature request into implementation-ready spec files for a coding agent.
  Use whenever the user wants to plan, scope, or write a spec for a feature about
  to be built: "write a spec for X", "plan feature Y", "how should we build Z",
  "draft an implementation plan". Produces a parent epic plus one file per
  independently-buildable slice. Prefer this skill when the audience is a coding
  agent, not an exec. Auto-applies the KeeForge overlay when the repo look

---
name: release
description: >
  Run the KeeForge three-channel release process: cut a release/{major}.{minor} branch, build
  iOS, Mac App Store, and direct-download Mac candidates from one immutable RC, soak the exact
  artifacts, and ship the exact accepted builds. Bumps versions and the globally monotonic repo
  build in project.yml, updates CHANGELOG.md and the What's New sheet, runs both local KDBX
  compatibility gates plus the local Mac smoke, and pushes rc/{version}-b{repoBuild} tags so Xcode
  C

# Cloud Views

Cloud provider file browsing and the manual WebDAV connect form.

## Screen Map

- `WebDAVConnectView.swift` owns the manual WebDAV connect sheet (server address, username, password with `PasswordInputRow`, advanced unencrypted-HTTP opt-in, inline error, Connect/Cancel), backed by `WebDAVConnectViewModel`. Its nested sheet sizes itself to the form, so nothing is clipped today, but the `Form` still takes `macGroupedForm()` for the sheet rule above; each field takes `macFormFieldStyle()`, and t

# AutoFillExtension

This target provides password, passkey, one-time-code, and new-credential save/generate fulfillment through `AuthenticationServices`.

## Main Files

- `CredentialProviderCoordinator.swift` is the platform-neutral core: request handling (passwords, passkeys, one-time codes, save/generate-password), vault access and unlock orchestration, credential matching, passkey assertion, and the `cleanup()` teardown lifecycle. It must stay free of UIKit/AppKit so both the iOS and macOS shells can h

# Group Views

Post-unlock group navigation, the group editor, and the group icon and move-destination pickers.

## Screen Map

- `GroupListView.swift`, `EntryListView.swift`, `EntryDetailView.swift`, and `SearchView.swift` own post-unlock navigation, entry/group creation and deletion affordances, expired-entry list/detail warnings, enabled expiration timestamps, detail presentation, and the global read-only + unsaved-change surfaces shown while a database is open. On macOS the sidebar column cannot host pu

# SearchAndTags Views

Search results and the tag browser.

## Screen Map

- `TagListView.swift` and `TagEntriesView.swift` own the tag browser. `TagListView.swift` also declares `TagDestination` — the `Hashable` navigation value both stack shells register (`UUID` already means "group" and `KPEntry` "entry") — and `TagAccessibility`, the shared per-tag identifier-suffix normalizer. Entry points: the root-only "Tags" row in `GroupListView.swift` (`group-list.tags-row`, in-file `TagBrowserRow`, visible ev

# Security Services

This folder holds device-security integrations and secret-handling helpers outside the core models.

## Main Files

- `BiometricService.swift` wraps LocalAuthentication flows used by the app and AutoFill.
- `KeychainService.swift` stores composite keys with biometric access control, shared with the extension via the keychain access group (see the invariant below).
- `PasskeyCrypto.swift` handles passkey-related crypto helpers used by the extension flow: PEM key handling and assertion si

# App Support Services

This folder holds app-scoped helpers that support UI behavior and secondary product surfaces.

## Main Files

- `SettingsService.swift` decides what is local-only versus App Group-shared with the extension. It also owns `MacLockPolicy` and documents how the iOS lock-on-background default maps to the macOS screen-lock/sleep/screensaver/session-resign triggers.
- `MacLockMonitor.swift` (KeeForgeMac target only) observes the system notifications that make up the macOS auto-lock guarante

# Entry Views

Entry detail, editing, history, attachments, icon selection, and the shared row-action state.

## Screen Map

- `PendingRowActions.swift` is the single home for the row-action state the three shells share: `PendingEntryDeletion`, `PendingGroupDeletion`, `PendingDeletion` (with `confirmationAlert(viewModel:)`), and `PendingMove`. `GroupListView.swift`, `EntryListView.swift`, and the macOS `../../App/RegularDatabaseWorkspaceView.swift` all build their delete confirmations and move sheets from i

# DatabaseList Views

Database picking, creation, per-database settings, master-key changes, and export to Files.

## Screen Map

- `DatabaseListView.swift` takes `isSidebarColumn` from its host — the split view's sidebar column passes `true`, the compact full-screen root leaves it `false` — and styles its list from it: `.sidebar` in a column, `.insetGrouped` full screen. It is passed in rather than read from `horizontalSizeClass`, which a sidebar column reports as compact however wide the window is. Th

# Components Views

Reusable controls shared across the feature folders.

## Screen Map

- `FaviconView.swift` renders an entry's icon: a custom `Meta/CustomIcons` image, a cached/fetched favicon, or the standard-icon glyph fallback. The fallback's colour is keyed to `backgroundProminence` — accent normally, white when it sits on a selected row's accent fill, which is the one case `.tint` would otherwise render accent-on-accent.
- `PasswordInputRow.swift` owns editable password entry controls shared by ma

# Models Folder

This folder holds the data and logic that the rest of the app depends on. It is the most security-sensitive part of the repo.

## High-Risk Core

The canonical high-risk file list (kept in sync with `AGENTS.md`): `KDBXParser.swift`, `KDBX3Parser.swift`, `KDBXWriter.swift`, `KDBXXMLSerializer.swift`, `KDBXCrypto.swift`, `KDBXOuterCipher.swift`, `OpaqueXMLNodes.swift`, `DatabaseDraft.swift`, `EntryEdit.swift`, `Entry.swift`, `Group.swift`, `EncryptedValue.swift`, `TOTPGenerator.swift`.

- `KD

# Extensions Folder

Use this folder for small app-specific extensions and conformances that are shared across multiple views or models but do not justify their own feature folder.

## Current Files

- `NavigationConformances.swift` keeps navigation state workable with the app's model types.
- `PlatformCompat.swift` is the shared iOS/macOS compatibility shim for the macOS port: `PlatformImage` (`UIImage`/`NSImage`) + `Image(platformImage:)`, `PlatformTextContentType`, UIKit semantic color names on `NSColor`

# KeeForge Unit Tests

Use this folder to find the smallest test slice that proves a change. Prefer unit tests over UI tests unless the behavior is truly UI-driven.

## Running Tests

```bash
xcodebuild test -project KeeForge.xcodeproj -scheme KeeForge \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -only-testing:KeeForgeTests/DatabaseViewModelTests -quiet
```

- Run only the classes touched by the change.
- `-only-testing:` takes test **class** names; the map below lists files, and the two

# GitHub CI And Templates

GitHub Actions workflows, issue/PR templates, funding config, and repo assets. Actions is one leg of CI; Xcode Cloud and a local release gate cover the rest.

## Workflows

- `workflows/pr-tests.yml` — required PR gate (jobs `unit-tests` and `macos-unit-tests`, both required status checks alongside DCO on `main` and `release/**`). Runs on every PR regardless of base branch, so stacked PRs (which target the branch below them) get the same gate: `iPhone 17 Pro, OS=latest`, `-only-

# App Folder

This folder owns app startup, scene transitions, and the adaptive root shell that connects the database list to one active database session.

## Main Files

- `KeeForgeApp.swift` creates the shared `DatabaseListViewModel`, owns the optional active `DatabaseViewModel`, chooses the compact vs regular-width root layout, and wires global scene-phase behavior. One `#if DEBUG` launch-argument hook (developer tooling, no Release effect): in `rootView`, `-autofill-store-inspector` replaces the normal 

# Persistence Services

This folder owns database references, cached copies, file access, and local-save infrastructure.

## Main Files

- `AppGroupContainer.swift` is the single resolution point for App Group storage: the container directory (`AppGroupContainer.url`) and the shared `UserDefaults` suite (`AppGroupContainer.defaults`). Every reader and writer of shared storage — this folder, `../AppSupport/SettingsService.swift`, `../AppSupport/FaviconService.swift`, `../AutoFill/AutoFillDiagnostics.swift`

# Test Support

Shared test infrastructure: fixtures, fakes, spies, and assertion helpers. Nothing here declares a test class — suites live one level up in `../`.

## Helpers

- `TestDatabaseSupport.swift` builds fixture URLs, supports fixture subdirectories, reads non-database fixture bytes (`fixtureData(named:extension:bundle:)`, for key files), and creates bookmark-backed `DatabaseReference` values for tests.
- `FakeCredentialIdentityStore.swift` is the lock-guarded in-memory `CredentialIdentityStorePr

# Cloud Services

This folder owns provider abstractions plus the cloud-backed open/save pipeline.

## Main Files

- `CloudSyncModels.swift` describes cloud provider files and sync metadata used by the database list and sync coordinator. Optimistic concurrency uses a single opaque `rev` field; the provider-specific mapping (Dropbox rev, OneDrive cTag/eTag, WebDAV ETag → `rev`) happens in the this folder providers.
- `CloudProvider.swift` and `CloudProviderRegistry.swift` define the provider boundary the r

# AGENTS.md

Entry point for coding agents working on KeeForge. This file is intentionally brief; most useful guidance now lives in folder-local docs next to the code.

## High level guidance

- Do not preserve backward compatibility unless required by the existing install base. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
- Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.

# ViewModels Folder

Observable app state lives here. Keep business rules here and keep views thin.

## Main View Models

- `DatabaseListViewModel.swift` owns the database list screen: add/remove/reorder, quick launch, nicknames, read-only toggles, key-file association, cloud database selection, row-status derivation, pending-upload counts/conflicts, and manual "push pending changes". `setAutoFillEnabled` invokes its `autoFillEnabledRefreshHandler` (the refresh bridge `../Views/README.md` references) so an 

# Unlock Views

Unlocking a single database: password and key-file entry, biometric affordances.

## Screen Map

- `UnlockView.swift` owns password/key-file entry and biometric affordances for one database. Its header padlock: `isSealed` starts shut, and `sealShutIfArrivingFromLock` replays open-to-shut only when `DatabaseViewModel.didManuallyLock` says the user pressed Lock (cleared on open in `../../App/KeeForgeApp.swift`); regular shells only — compact returns to the database list on lock and gets its 

# TOTP Views

TOTP enrollment: QR scanning and the incoming-URL destination picker.

## Screen Map

- `TOTPQRScannerSheet.swift` (whole file `#if os(iOS)`; VisionKit's `DataScannerViewController` does not exist on macOS, where the scan affordance is hidden) is the TOTP enrollment camera sheet: a `DataScannerViewController` representable restricted to QR symbology. Scanning starts from a deferred main-actor task with one retry (`startScanning()` fails before the scanner is on screen), a still-failing start s

# KeeForge macOS UI Tests

Smoke suite for the native macOS app (target `KeeForgeMacUITests`, scheme `KeeForgeMac`). Methodology and fixture guidance live in `../KeeForgeUITests/README.md`; this suite reuses the same fixtures and accessibility identifiers — preserve them in both places. `MacUITestCase` mirrors the iOS target's fixture-injection launch environment but uses clicks, `typeKey` keyboard shortcuts, and right-click context menus instead of taps/swipes.

## Test Classes

- `MacSmokeUITests` — u

# Settings Views

App settings, release education, support surfaces, and DEBUG-only developer tooling.

## Screen Map

- `SettingsView.swift`, `AcknowledgmentsView.swift`, and `TipJarView.swift` own secondary settings and support surfaces. `SettingsView.swift` contains the in-file sub-screens `SecuritySettingsView`, `AutoFillSettingsView`, `DisplaySettingsView`, `AboutSettingsView`, `AboutSectionContent`, `MacSecuritySettingsTab`, and `MacDisplaySettingsTab`; identifiers: `settings.tab.{security,autofill,di

# AutoFill Services

This folder holds extension-facing helpers shared between the main app and the AutoFill target.

## Main Files

- `AutoFillSaveCoordinator.swift` stages and saves new credentials, refreshes shared caches, and queues deferred cloud uploads when needed.
- `CredentialMatcher.swift` matches KeePass entries to web domains and usernames for AutoFill suggestions.
- `CredentialIdentityStoreManager.swift` mirrors unlocked entries into the system credential identity store. It also owns `Credentia