Files
Incido/Incido Development Plan.txt
T
Incido Developer a39c52cf89
dev / Build debug APK (push) Successful in 1m7s
release / Build & attach release APK (push) Failing after 28s
feat(trash): v0.3.7.0 — Trash / soft delete + release docs backfill
- Deleting a note now soft-deletes it (trashed flag on NoteEntity,
  additive schema, auto-migrated); trashed notes are hidden from Home,
  Favorites, Untagged, tag views, and ordinary search.
- New Trash drawer entry lists soft-deleted notes; each Trash card's
  overflow menu exposes Restore and Delete permanently.
- NoteFilter gains a Trash case; repository gains moveToTrash /
  restoreFromTrash / deletePermanently; backups round-trip the
  trashed state.
- Version bump (lockstep): versionCode 30->31, versionName
  0.3.6.3->0.3.7.0, SettingsViewModel.APP_VERSION, README intro +
  changelog, ReleaseNotes.kt 5-most-recent window.
- Development Plan §10: fix the merged 0.3.4.0/0.3.3.8 table row and
  backfill the missing 0.3.6.2/0.3.6.3 rows; add the 0.3.7.0 row.
- README changelog: backfill the missing 0.3.6.2 row; promote the
  Unreleased Trash row to 0.3.7.0.
2026-08-20 11:52:43 +12:00

533 lines
52 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Incido — Development Plan
## 0. Project Overview
**Name:** Incido (Latin, pronounced "een-chi-do" — *incido* = "I cut into / I inscribe")
**Mission:** A privacy-first, on-device note-taking application. All data stays on the user's device by default. Built to be free, offline-capable, and never lock user content behind a vendor.
**Target Audience:** Privacy-conscious users, anyone wanting a Google Keep alternative without cloud dependency, users who want to avoid paid subscriptions for basic note-taking.
**v0.1 Scope (this plan):** Android-only proof-of-concept / Minimum Viable Product. Demonstrates the core architecture, data layer, and UI shell. Sets the technical foundation for all future features without requiring rewrites.
**Tagline (suggested):** *Your notes. Your device. Your terms.*
---
## 1. Licensing
### 1.1 License: GPL-3.0
- Anyone may use, modify, and redistribute the code.
- Modifications that are **distributed** (sold, published, or otherwise conveyed to others) must also be released under GPL-3.0 (copyleft).
- Internal / private modifications are not required to be published — only **distributed** versions trigger the source-sharing obligation.
- Full license text: https://www.gnu.org/licenses/gpl-3.0.en.html
- A `LICENSE` file containing the full GPL-3.0 text must be committed to the repository root.
- A `NOTICE` file should credit contributors and reference the license.
### 1.2 Commercial Flavor — Future Feature
A separate commercial build under a proprietary license, intended for users/organizations who want the commercial sync service, premium support, or integration features. Not in v0.1 scope.
---
## 2. Repository & Project Setup
### 2.1 Hosting
- **Host:** Self-hosted Gitea
- **Visibility:** Public (for FOSS community contribution)
- **Repository name suggestion:** `incido`
### 2.2 Package & Identity
- **Application ID:** `org.incido.app`
- **Display name:** Incido
- **License file:** `LICENSE` (GPL-3.0)
- **Notice file:** `NOTICE`
### 2.3 Local Toolchain Requirements
The following must be installed on the development machine before any build will succeed:
| Tool | Version (recommended) | Purpose |
|------|----------------------|---------|
| JDK | 17 (LTS) | Kotlin/Java compilation |
| Android Studio | Ladybug (2024.2.1) or newer | IDE, SDK management, device deployment |
| Android SDK Platform | API 35 | Compile target |
| Android SDK Build-Tools | 35.0.0 | Build pipeline |
| Android SDK Platform-Tools | Latest | `adb` for device install |
| Kotlin | 2.0.21+ | Language (bundled with Android Studio) |
| Gradle | 8.10+ | Build system (wrapper handles this) |
For a non-developer: Android Studio bundles JDK, Kotlin, Gradle, and the SDK. **Install Android Studio first; everything else follows.**
### 2.4 SDK Levels
- `minSdk = 26` (Android 8.0 Oreo — covers ~95% of active devices)
- `targetSdk = 35` (Android 15)
- `compileSdk = 35`
---
## 3. Architecture & Technology Choices
### 3.1 Language & UI Framework
- **Kotlin** 2.0.21+ as the primary language
- **Jetpack Compose** as the UI framework (Android-recommended; maps cleanly to Compose Multiplatform for future ports)
- **Kotlin Multiplatform (KMP)** with the UI in the **shared module** from day one. This is the core future-proofing decision: when iOS/Desktop ports come later, no UI rewrite is needed.
### 3.2 Build System
- **Gradle 8.10+** with **Kotlin DSL** (`.kts` build files)
- **Version catalog** (`gradle/libs.versions.toml`) — a single source of truth for all library versions. Critical for AI-assisted workflows to avoid version drift.
### 3.3 Module Structure (Multi-Module)
The project is split into the following Gradle modules:
```
incido/
├── app/ # Android application module (entry point, manifest, MainActivity)
├── composeApp/ # KMP shared module — UI lives here from day 1
│ └── src/
│ ├── commonMain/ # Shared Kotlin + Compose UI (works on Android, iOS, Desktop)
│ └── androidMain/ # Android-specific glue (Activity host, resources)
├── core/
│ ├── data/ # KMP shared module — ObjectBox wrapper, repository, models
│ └── domain/ # KMP shared module — use cases, business logic interfaces
├── gradle/
│ └── libs.versions.toml # Version catalog (single source of truth)
└── settings.gradle.kts
```
**Why this structure:**
- `core/data` and `core/domain` are pure Kotlin and reusable on iOS/Desktop later.
- `composeApp` is the KMP UI module that all platforms consume.
- `app` is just the Android wrapper (manifest, MainActivity, app icon).
- Adding iOS later = create `iosApp/` module pointing at `composeApp`. Adding Desktop = add `desktopMain` source set.
### 3.4 Data Layer
- **ObjectBox** for persistence
- Supports KMP shared modules
- Native blob support for images/audio (future-proofing media storage)
- Built-in encryption support (for future feature)
- Vector search capability (future-proofing semantic search)
- **Data model for v0.1:** Single `NoteEntity` with fields:
- `id: Long` (ObjectBox-managed)
- `content: String` (the note text)
- `createdAt: Long` (epoch millis)
- `updatedAt: Long` (epoch millis)
- **Repository pattern:** `NoteRepository` interface in `core/domain`, ObjectBox-backed implementation in `core/data`. ViewModels consume the interface, not the implementation.
### 3.5 State Management
- **ViewModel + StateFlow** (standard Jetpack pattern)
- Each screen has a single ViewModel exposing immutable UI state as a `StateFlow<UiState>`
- No third-party state management library in v0.1 (Redux/MVI/Compose-Runtime can come later if needed)
### 3.6 Navigation
- **Navigation Compose** (`androidx.navigation:navigation-compose`)
- Two screens in v0.1:
1. `NoteListScreen` — shows all notes as cards
2. `NoteEditorScreen` — add/edit a single note
---
## 4. v0.1 Feature Specification
### 4.1 Functional Requirements
| ID | Requirement | Acceptance Criteria |
|----|-------------|---------------------|
| F1 | **List of currently saved notes** | On app launch (and at all times when on the home screen), the user sees a scrollable list of all notes currently stored in the database. Each note is represented as a card showing a preview of its content and its last-updated timestamp. |
| F2 | Create a new note | Tapping "+" opens an empty editor; saving adds the note to the list and database. |
| F3 | Edit an existing note | Tapping a note card opens the editor pre-filled with its content; saving updates the note in place and reflects the change on the list. |
| F4 | Delete a note | A delete action on a note card (or in the editor) moves the note to the Trash filter. Notes in Trash are excluded from Home, Favorites, Untagged, tag, and ordinary search views; deleting a note from Trash destroys it permanently. |
| F5 | Data persists across restarts | Notes created in one session are visible in the list after force-closing and reopening the app. |
| F6 | Empty state | When the list is empty (no notes saved), show a friendly empty-state message instead of an empty list. |
| F7 | List refreshes automatically | The list of saved notes updates immediately after creating, editing, or deleting a note — no manual reload required. |
### 4.2 Non-Functional Requirements
| ID | Requirement |
|----|-------------|
| N1 | App launches in under 2 seconds on a mid-range device |
| N2 | No network permission required (offline-first) |
| N3 | No analytics, telemetry, or third-party trackers |
| N4 | Single APK, no dynamic feature modules |
| N5 | Dark mode follows system setting (light/dark theming scaffolded for future customization) |
### 4.3 Out of Scope for v0.1 (deferred to future features)
All features listed in §6.
---
## 5. UI/UX Skeleton
### 5.1 Screen 1 — Note List (Home)
- **Purpose:** Display the list of currently saved notes.
- **Top bar:** App title "Incido"
- **Body:**
- If empty: centered text "No notes yet. Tap + to start."
- If populated: vertical scroll of `NoteCard` items, newest first
- **Floating Action Button (FAB):** "+" icon, bottom-right, navigates to editor for a new note
- **`NoteCard` design:**
- Displays the note content (first ~3 lines, truncated)
- Shows relative timestamp ("2 min ago", "Yesterday", etc.)
- Whole card is tappable → opens editor for that note
- Long-press or swipe reveals move-to-Trash action; Trash cards expose Restore and permanent Delete
### 5.2 Screen 2 — Note Editor
- **Top bar:** Back arrow + Save action
- **Body:** Single multi-line `TextField` filling the screen, auto-focused
- **Behavior:**
- Back arrow without save = discard (no confirmation in v0.1; v0.2 should confirm if content changed)
- Save action persists and returns to the list; the updated/created note is visible immediately on the list
- Delete button (only when editing existing note) at bottom or in top bar overflow; it moves the note to Trash
### 5.3 Theming
- **Material 3** (Material You) design system
- **Dynamic color** on Android 12+ (system-derived accent)
- **Light/Dark mode** automatic via system setting
- Brand-neutral palette in v0.1 (custom theming in future)
---
## 6. Future Features (Backlog)
This list is the canonical backlog. Items can be promoted into future versions as the project matures.
### 6.1 Keep Parity
- Checklists / to-do items within notes
- Grocery list with running price total — one product per line, no checkboxes. The price is parsed from the trailing numeric token (e.g. `milk 3.50` → $3.50); a line without a parsable price is ignored until one is added. The editor renders a sticky running total at the top of the note, updated live as prices are added/edited while shopping.
- Color-coded notes and labels
- Pinning notes to top
- Archive (vs. delete) with archive view
- Full-text search across note content
- Tag / hashtag system
- Search by tag or content
- Share-into: receive text/images from other apps
- Image attachments from camera and gallery
- Audio attachments / voice notes
> **Trash status:** Soft-delete, Trash filtering, Restore, and permanent
> deletion are implemented in the current Android app. There is no
> automatic purge window yet; a note is destroyed immediately when it is
> permanently deleted from Trash.
### 6.2 On-Device Machine Learning
- **OCR (Optical Character Recognition):**
- Extract text from images attached to notes
- Handwriting recognition
- Document scanning with perspective correction
- Table extraction
- **Speech-to-Text:**
- Transcription of audio note attachments
- Live dictation while composing notes
- Translation
- Speaker diarization
- **Search index:** automatically index extracted OCR text for full-text search
- ML inference runs entirely on-device (ML Kit, Gemini Nano, or Whisper-tiny)
### 6.3 Cross-Platform Ports
- **iOS** — via Compose Multiplatform (UI already shared)
- **Linux** — Compose Multiplatform Desktop (JVM)
- **Windows** — Compose Multiplatform Desktop (JVM)
- **macOS** — Compose Multiplatform Desktop (JVM)
- Each platform shares `core/data`, `core/domain`, and `composeApp`
### 6.4 Security & Privacy
- ObjectBox database encryption (AES-256 at rest)
- App-lock with PIN
- App-lock with biometric (fingerprint / face)
- Auto-lock timeout
- Encrypted exports
- Secure clipboard handling
### 6.5 Sync & Cloud (Optional, Future)
- Self-hosted sync server (open source, user-runs)
- E2E-encrypted sync protocol
- Multi-device sync
- Optional premium/hosted sync service (Commercial flavor)
### 6.6 Commercial Flavor
- Separate proprietary build under commercial license
- Bundled sync service subscription
- Premium support tier
- Integration APIs for enterprise
### 6.7 Quality of Life
- Markdown rendering and editing
- Import from Google Keep, Evernote, plain text, Markdown files
- Export to plain text, Markdown, PDF, HTML
- Custom themes and color schemes
- Note linking / wiki-style cross-references
- Folders / notebooks in addition to tags
- Versioning / note history
- Undo/redo
### 6.8 Developer / Community
- Continuous Integration via Gitea Actions
- Automated APK builds on commit
- Translation infrastructure (Weblate or Crowdin)
- Contribution guidelines (`CONTRIBUTING.md`)
- Issue and PR templates
- Documentation site (public)
- Release/signing infrastructure for Play Store distribution
---
## 7. Build & Verification Plan for v0.1
### 7.1 "Done" Definition for v0.1
v0.1 is considered complete when **all** of the following are true:
1. `./gradlew assembleDebug` succeeds on a clean clone of the repository
2. The generated APK installs on a real Android device via Android Studio's Run button
3. Manual test pass on a real device:
- App launch shows the list of currently saved notes (empty state on first run)
- Create 3 notes with different content → all 3 are visible on the list
- Edit one note → change appears on its card on the list
- Delete one note → it disappears from the list
- Force-stop the app, reopen → all remaining notes still appear on the list
4. `README.md` contains:
- Project description
- Build instructions
- Install/run instructions
- License notice
5. `LICENSE` (GPL-3.0) is committed
6. `NOTICE` is committed
### 7.2 Manual Smoke Test Script (run before tagging v0.1)
```
[ ] Launch app — see empty state message ("No notes yet. Tap + to start.")
[ ] Tap FAB — editor opens, cursor in text field
[ ] Type "Test note 1" — tap save — returns to list, "Test note 1" card visible
[ ] Repeat for "Test note 2" and "Test note 3"
[ ] Confirm all 3 notes visible on the list, newest at top
[ ] Tap "Test note 2" card — editor opens with existing content
[ ] Change to "Test note 2 (edited)" — tap save
[ ] Confirm updated text appears on the card on the list
[ ] Long-press "Test note 3" — move-to-Trash option appears
[ ] Confirm move — note disappears from the list and appears in Trash
[ ] Restore from Trash — note returns to the list; delete permanently from Trash — note is destroyed
[ ] Force-stop app from system settings
[ ] Reopen app — "Test note 1" and "Test note 2 (edited)" both visible on the list
[ ] Pass — v0.1 verified
```
---
## 8. Development Workflow (for AI-Assisted Building)
Because the developer is not a coder, the following workflow is recommended:
### 8.1 Iteration Loop
1. **State the task in plain English** to the AI coding assistant (e.g., "create the NoteEditorScreen Composable with a single TextField and a save button").
2. **AI writes code** into the appropriate module/file.
3. **AI reports what files were created/modified.**
4. **Developer reviews the diff** in Android Studio or VS Code.
5. **Build via Android Studio** (green Run button) or terminal `./gradlew assembleDebug`.
6. **Install on real device** (Android Studio handles this).
7. **Manual smoke test.**
8. **Commit to Gitea** with a meaningful message.
### 8.2 Recommended Commit Cadence
- Commit after each working milestone (e.g., "scaffold multi-module project", "implement NoteRepository", "build NoteListScreen").
- Use Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`.
### 8.3 Where AI Helpers Should Place Code
A short reference for AI assistants:
| What you're building | Where it goes |
|----------------------|---------------|
| Activity / Application class | `app/src/main/kotlin/...` |
| Composables (UI screens) | `composeApp/src/commonMain/kotlin/...` |
| ViewModels | `composeApp/src/commonMain/kotlin/.../viewmodel/` |
| ObjectBox entities | `core/data/src/commonMain/kotlin/.../entity/` |
| Repositories | `core/data/src/commonMain/kotlin/.../repository/` |
| Use cases | `core/domain/src/commonMain/kotlin/.../usecase/` |
| Android-specific resources | `app/src/main/res/` |
| Dependencies | `gradle/libs.versions.toml` (never hardcode versions elsewhere) |
---
## 9. Risks & Open Questions
### 9.1 Known Risks
- **ObjectBox KMP setup is non-trivial** — first-time KMP+ObjectBox configuration may require debugging. Allow extra time for initial build configuration.
- **Compose Multiplatform is mature but Android-first** — minor adjustments may be needed when iOS/Desktop ports happen. Not a v0.1 concern.
- **GPL-3.0 is strict** — some potential contributors or downstream users may prefer MIT/Apache (especially those who want to build a proprietary network service without publishing source). This is an intentional choice; document clearly in README.
### 9.2 Open Questions (to resolve during v0.1 development)
- App icon design — placeholder for v0.1; designed icon in v0.2.
- Splash screen design — Android 12+ splash API; minimal in v0.1.
- ObjectBox license — verify ObjectBox's own license terms are compatible with GPL-3.0 distribution.
- Play Store distribution — not in v0.1; F-Droid distribution should be evaluated for FOSS flavor.
---
## 10. Document History
> **Version scheme (from v0.3.0.0 onwards):** `MAJOR.MINOR.MAINTENANCE.EMERGENCY` —
> e.g. `0.3.0.0`. `MAJOR.MINOR.MAINTENANCE` are normal release numbers;
> `EMERGENCY` is non-zero only for hotfixes shipped out-of-band.
> `versionCode` is a monotonic int and always +1 per release.
> The build refuses to compile if `versionName` doesn't match this shape.
| Version | Date | Notes |
|---------|------|-------|
| 0.3.7.0 | 2026-08-20 | **Feature release — Trash / soft delete.** Deleting a note (long-press card → ⋮ menu → Delete, or the editor's delete action) now soft-deletes it instead of destroying it: the note is flagged as trashed and hidden from Home, Favorites, Untagged, tag views, and ordinary search. A new **Trash** entry in the nav drawer lists only soft-deleted notes; each Trash card's overflow menu exposes **Restore** (returns the note to its previous views) and **Delete permanently** (destroys the row + attachments for good). `NoteEntity` gains a `trashed` flag (additive schema, auto-migrated); `NoteFilter` gains a `Trash` case; the repository gains `moveToTrash` / `restoreFromTrash` / `deletePermanently`; the drawer, list, and editor ViewModels + screens wire the new actions. Backups round-trip the trashed state. No automatic purge window yet — permanent deletion is immediate (see §6.1 "Trash status" note). versionCode 30→31, versionName "0.3.6.3"→"0.3.7.0", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.6.3 | 2026-08-20 | **Emergency hotfix — actionable missing-keystore failure.** On a fresh clone, `./gradlew assembleRelease` previously died late inside `packageRelease` with the cryptic `SigningConfig "release" is missing required property "storeFile"`. It now fails with a clear `GradleException` quoting the exact `keytool` command from `keystore/README.md` to generate `keystore/release.jks`, implemented as a `validateReleaseKeystore` task whose existence check runs in `doFirst` (so `assembleDebug` still works without a keystore). CI unaffected — `.gitea/workflows/release.yml` mints the dev keystore on release runners before `assembleRelease`. No app/Compose code changes. versionCode 29→30, versionName "0.3.6.2"→"0.3.6.3", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.6.2 | 2026-08-19 | **CI / release-pipeline tag.** v0.3.6.2 is a re-tag of the v0.3.6.1 commit used to exercise the Gitea Actions release workflow (minting the dev keystore on the release runner and attaching the version-stamped debug + release APKs to the Gitea release). No app code or version-string changes landed under this tag — the tagged commit still reads versionName "0.3.6.1" / versionCode 28. |
| 0.3.6.1 | 2026-08-19 | **Emergency hotfix** — two UX bugs in the v0.3.6.0 New/Edit screen. **1. Top-bar title crowded the action buttons.** `NoteEditorScreen` used `CenterAlignedTopAppBar`, but with six actions on the right (camera, attach, tag, favourite, save, more) the visually-centred title ended up pressed against the action cluster — users read it as "the title is on the right". Fix: swap the top bar for `TopAppBar` (Material 3's left-aligned variant) so "New"/"Edit" sits flush right of the back arrow on the left and the action cluster keeps the right edge. Import swap; no behavioural change for the actions or title text. **2. Colour chooser was not equally spaced.** The picker `Row` had `padding(vertical = 4.dp)` (4dp above + 4dp below), but the `OutlinedTextField` below it has an intrinsic top inset (~16dp) inside its border, so the perceived gap from the picker to the first line of the note dwarfed the gap from the title bar's bottom to the picker's top — to the user, "the picker is jammed up against the title bar". Fix: remove the row's `vertical = 4.dp` and bracket it with two explicit `Spacer(Modifier.height(12.dp))` siblings (one before the row, one after) so the picker sits 12dp from the title bar AND 12dp from the field's top border. The asymmetric `OutlinedTextField` internal padding is now matched on both sides of the picker, giving visually equal breathing room up and down. versionCode 27→28, versionName "0.3.6.0"→"0.3.6.1", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.6.0 | 2026-08-19 | **Maintenance release** — share-into titles + encryption-key recovery. **1. Share webpages into Incido with a subject line.** `Intent.EXTRA_SUBJECT` from an inbound `ACTION_SEND` is now routed through `NoteEditorViewModel.initialSharedSubject` and prepended to the new note's content as a first line ("Page title") above the shared body/URL (already supported since v0.3.1.0). Browsers fill `EXTRA_SUBJECT` with the page title when the user shares a URL, so the resulting note reads naturally as a bookmark without ever leaving the device — fully offline, no `INTERNET` permission. **2. Export / Import encryption key.** New rows in Settings → Security expose the underlying AES-256 wrapping key as a passphrase-protected `.inckey` envelope (PBKDF2 200k iters + AES-GCM): "Export encryption key" writes the wrapped blob to a user-chosen SAF uri, "Import encryption key" reads it back, validates the passphrase, and atomically replaces the active key — with a clear warning dialog listing the consequences ("your existing encrypted notes will become unverifiable"). The 32-byte raw key never appears on screen or in logs; only the wrapped envelope crosses the SAF boundary. versionCode 26→27, versionName "0.3.5.1"→"0.3.6.0", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.5.1 | 2026-08-17 | **Emergency hotfix** — two UX bugs in v0.3.5.0. **1. "Encrypted" badge silently failed to appear on the first enable.** Audit found `EncryptionVerifier.checkNow()` early-returned with `if (_checking.value) return` whenever a verify-all was in flight. The startup pass launched from `AppContainer.init` could still be running when the user toggled Encrypt-at-rest in Settings; the post-migration re-check then silently dropped, the startup pass eventually wrote its stale (pre-encryption, empty verified-id) result back to the StateFlow, and the cards never earned the badge until the second toggle or a relaunch let a fresh check actually run. Fix: drop the `_checking` skip-guard and replace it with a `kotlinx.coroutines.sync.Mutex` that serializes checks in invocation order. Every `checkNow()` call now takes its turn and the last call's result wins, so the post-migration check always produces the fresh verified-id set; the startup pass is cheap (no encrypted rows yet → all skips) so user-triggered checks after a real migration only wait milliseconds. **2. "Encrypted" badge UX on note cards.** v0.3.5.0 rendered the indicator as a centred `Row` with a lock icon + "Encrypted" label at the card's bottom edge. Replace with a bare 14 dp `Lock` `Icon` sitting immediately to the LEFT of the timestamp inside the card's existing bottom Row — the row already uses `Alignment.CenterVertically`, so the icon is vertically centred with the date/time and lives in the same left-anchored position on every card regardless of card content (tag row, body preview, checklist summary). The icon keeps the existing `contentDescription = "Encrypted"`. versionCode 25→26, versionName "0.3.5.0"→"0.3.5.1", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.5.0 | 2026-08-17 | **Maintenance release** — real at-rest encryption, verified "Encrypted" badge, and screenshot blocking. **1. Real field-level encryption ("Encrypt in place" now works).** Audit of the v0.3.2.0 toggle found it was cosmetic: `ObjectBoxStore.init()` ignored the key (`@Suppress("UNUSED_PARAMETER")`), `AppContainer` always passed `encryptionKey = null`, and the OSS ObjectBox 4.0.3 `BoxStoreBuilder` exposes no encryption API at all (verified against the local artifact — page-level encryption is ObjectBox Sync/Pro only). Fix: application-layer field encryption. `NoteEntity` gains `cipherVersion` (0=plain, 1=AES-256-GCM) + `contentBlob`; `NoteAttachmentEntity` gains the same pair for `bytesBlob` — additive schema, auto-migrated. New `FieldCipher` abstraction in `:core:data` with `AesGcmFieldCipher` in `:composeApp` (fresh random 12-byte nonce per blob; GCM tag = integrity proof), keyed by the existing Keystore-wrapped 32-byte key from `ObjectBoxKeyProvider`. The repository consults a shared `CipherHolder` on every read/write (encrypt-on-write, decrypt-on-read, in-memory content search while encrypted); `NoteCryptoService` sweeps all rows in place with progress. Toggling encryption ON installs the cipher and encrypts every plaintext note + attachment row live (no restart); toggling OFF decrypts everything first, then removes the cipher and deletes the key; disabling Security entirely also runs the decrypt sweep so no data is orphaned. AES-256-GCM is the correct PQ-era choice for data at rest (NIST: Grover halves effective security → ~128-bit residual; no public-key crypto in this path). **2. Verified "Encrypted" badge on cards.** New `EncryptionVerifier` runs on every app open (and after each migration): full trial-decrypt of every `cipherVersion = 1` note row; the GCM auth tag passing is the proof of integrity. Only notes in the resulting verified-id set get a bottom-centre "Encrypted" label (with lock icon) on their card — never derived from the settings flag alone; rows that fail verification are reported and excluded. **3. Block screenshots toggle (default ON).** New `UserSettings.blockScreenshots` (DataStore-backed, defaults true); `MainActivity` applies/clears `FLAG_SECURE` from a startup snapshot + live settings-flow collection, blocking screenshots, screen recording, and app-switcher previews; Settings → Security gains the "Block screenshots" switch. Settings copy for encryption updated (no longer claims a restart is required). versionCode 24→25, versionName "0.3.4.0"→"0.3.5.0", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.4.0 | 2026-08-17 | **Maintenance release** — three changes. **1. Attachment indicator on note cards** — a paperclip icon (`Icons.Filled.AttachFile`) now appears on the right edge of every card whose note carries at least one attachment (any type — image, PDF, audio…). It is a non-interactive `Icon` (24 dp, `contentDescription = "Has attachments"`) aligned `Alignment.CenterEnd` with `padding(end = 16.dp)` so its glyph centre sits at 28 dp from the right edge — the same vertical column as the ⋮ overflow `IconButton` (top) and the favourite star (bottom), exactly halfway between them (both neighbours centre their 24 dp glyphs at 28 dp: 4 dp padding + 24 dp inside a 48 dp `IconButton`). Bare `Icon` rather than `IconButton` so it never intercepts the whole-card tap that opens the editor. **2. Light-theme readability over image thumbnails** — the card's 0.45-alpha black scrim always renders the background dark, but the overlay content kept the theme-driven colours, so in Light mode dark text sat on a dark photo (all but invisible). Fix: when a thumbnail is present every overlay switches to a forced light palette regardless of theme — title pure white; body preview, checklist summary, timestamp, ⋮ icon, unfilled star, paperclip and "+N" tag overflow white @ 85 %; hashtag chips white; favourited star a light amber (`#FFD54F`) so "favourited" stays distinguishable; the Card's `contentColor` is also set to white. Plain (no-thumbnail) cards are untouched and keep their existing tinted/surface colours. `HashtagRow` now takes caller-supplied `tagColor` / `overflowColor` params. **3. Auto-Lock = Immediate + file-picker hotfix** — with Auto-Lock set to "Immediately", attaching a file (paperclip → SAF picker), taking a photo (camera), opening an attachment in the system viewer, or exporting/importing a backup locked the app the moment the external activity returned: the picker backgrounds the Activity (`ON_STOP`), the return fires `ON_RESUME`, and the 0 ms timeout always re-locks. The lock gate then tore down the `NavHost` from composition, destroying the editor's `NavBackStackEntry` ViewModelStore — so the unsaved note vanished and the picker result never landed. Fix: `SecurityManager` gains an in-flight flag (`externalActivityInFlight`, `@Volatile`) set by a new `beginExternalActivity()` and consumed exactly once by `onAppForegrounded()`, which skips the re-lock check and clears `backgroundedAt` when the flag is set. Call sites: `NoteEditorScreen` (file picker launch, camera launch after permission grant, system-viewer `ACTION_VIEW` — `securityManager` threaded through `AttachmentStrip`/`AttachmentThumbnail`), `SettingsScreen` (backup export + import SAF launchers), with `IncidoApp` threading `resolvedSecurity` to both screens. Genuine background/foreground cycles still lock as configured; cold launch is unaffected (fresh process ⇒ flag always false). versionCode 23→24, versionName "0.3.3.8"→"0.3.4.0", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.8 | 2026-08-17 | **Emergency hotfix** — the designed `incido.png` artwork (glass shield + fountain-pen nib) replaces the v0.1 placeholder launcher icon. The 2048×2048 source is downscaled (LANCZOS) into density-correct raster buckets: `mipmap-{mdpi…xxxhdpi}/ic_launcher.png` (48/72/96/144/192 px square) plus anti-aliased circular `ic_launcher_round.png` in the same buckets, and `drawable-{mdpi…xxxhdpi}/ic_launcher_foreground.png` (108/162/216/324/432 px) feeding the `mipmap-anydpi-v26` adaptive icons (`ic_launcher.xml` / `ic_launcher_round.xml`), whose stale `<monochrome>` placeholder reference is dropped and whose `ic_launcher_background` colour is re-tinted from `#6650A4` to the artwork's edge navy `#010435` so parallax exposure is seamless. The obsolete placeholder vector `drawable/ic_launcher_foreground.xml` is deleted; manifest `android:icon` / `android:roundIcon` references are unchanged. versionCode 22→23, versionName "0.3.3.7"→"0.3.3.8", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.7 | 2026-08-17 | **Emergency hotfix** — when Biometric is the active lock method, the lock screen's "Authenticate" button required an extra tap before the fingerprint / face reader would start. Fix: `PinEntryScreen` now auto-launches the `BiometricPrompt` as soon as the lock screen composes in biometric-only mode (`settings.isBiometricLockActive`), via a one-shot `LaunchedEffect(biometricOnly)` guarded by an `autoLaunched` flag (so a cancelled prompt cannot re-trigger). Success → `onUnlocked()`; cancel/error → the lock screen stays with an error message and the "Authenticate" button remains as the manual-retry path. The failure message in biometric-only mode no longer mentions a PIN ("Authentication failed. Tap Authenticate to try again."). PIN mode is untouched — `biometricOnly` is false there, so the auto-launch effect never runs and the PIN field keeps its auto-focus. versionCode 21→22, versionName "0.3.3.6"→"0.3.3.7", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.6 | 2026-08-17 | **Emergency hotfix** — the fixed card height shipped in v0.3.3.5 (`168.dp`) proved too tall on real devices. Fix: `CARD_HEIGHT_DP` in `NoteListScreen.kt` reduced by ~15% to `143.dp` (~15% taller than the pre-0.3.3.5 wrap-content typical of ~124.dp). Everything else from v0.3.3.5 is unchanged — cards remain a single fixed height, the timestamp stays pinned to the card's bottom edge via the weighted spacer, the hashtag row is still hidden when empty, and the colour stripe still spans the full card height. versionCode 20→21, versionName "0.3.3.5"→"0.3.3.6", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.5 | 2026-08-17 | **Emergency hotfix** — the note cards on the main page used wrap-content height, so card heights varied depending on whether the note carried a body preview, hashtag row, or checklist summary (and untagged notes rendered visibly shorter than tagged ones). Fix: every `NoteCard` now has a fixed height of `168.dp` (~35% taller than the previous typical wrap-content height of ~124.dp for a title + 2-line body preview), applied via `Modifier.height(CARD_HEIGHT_DP)` on the Card. A `Spacer(Modifier.weight(1f))` inside the content column pins the timestamp row to the bottom of the fixed-height card so the layout stays consistent regardless of content; the hashtag row is still hidden entirely when the note has no tags. The left colour stripe now spans the full card height (`fillMaxHeight().width(14.dp)`) instead of the hardcoded `size(width = 14.dp, height = 110.dp)`. Thumbnail background + scrim, dog-ear, ⋮ overflow button, favourite-star overlay, and long-press menu are unaffected (all corner-anchored). versionCode 19→20, versionName "0.3.3.4"→"0.3.3.5", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.4 | 2026-08-17 | **Emergency hotfix** — the favourite star on note cards was rendered inside the title row and overlapped the ⋮ overflow `IconButton` anchored to the card's top-right corner. Fix: the star is removed from the title row (the title now spans the full width) and re-added as an overlay aligned to `Alignment.BottomEnd` with `padding(end = 4.dp, bottom = 4.dp)` — the same `end = 4.dp` offset the `TopEnd` overflow button uses — so the two controls sit in the same vertical column and no longer collide. The star keeps its existing toggle behaviour and tinting (filled + primary when favourited, outline + onSurfaceVariant otherwise). versionCode 18→19, versionName "0.3.3.3"→"0.3.3.4", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.3 | 2026-08-17 | **Emergency hotfix** — importing an encrypted backup crashed the app without any errors. Root cause: the passphrase `CharArray` was wiped immediately after the preview decrypt step (`EncryptedBackupCodec.decrypt` zeroes the array it consumes, and `SettingsScreen` then nulled its cached copy), so the confirm dialog's Import button called `viewModel.import(uri, null)`; `BackupManager.import()` threw `IllegalArgumentException("Encrypted backup requires a passphrase")` inside an unguarded `scope.launch { }` and the app crashed. Fix: the screen now retains a copy of the passphrase for the import step (`pendingImportPassphrase = chars.copyOf()` on dialog confirm), hands `import()` a fresh copy (`retained?.copyOf()`), and wipes the retained array in a `finally` block; the preview / import coroutines are wrapped in try/catch so any failure (wrong passphrase re-decrypt, truncated envelope, I/O error, malformed JSON) surfaces a snackbar ("Import failed. Check the file and passphrase." / "Could not read backup file.") instead of crashing; the confirm dialog's `onDismissRequest` now also wipes the retained passphrase. `BackupManager.preview()` additionally catches `IllegalArgumentException` (truncated envelope failing the `require(...)` size checks) and `GeneralSecurityException` so corrupt encrypted files return `null` cleanly. versionCode 17→18, versionName "0.3.3.2"→"0.3.3.3", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.2 | 2026-08-17 | **Emergency hotfix** for two lock-screen regressions in v0.3.3.x: **White-on-white lock screen in dark mode** — `PinEntryScreen` rendered a bare `Column` with no background of its own, so under the dark theme it was transparent and the permanently-light Activity window background showed through, making the heading and PIN field invisible. The screen is now wrapped in a themed `Surface(color = MaterialTheme.colorScheme.background)` (with matching `contentColor`) so it always paints its own theme-aware background in both light and dark modes. **Biometric unlock hangs** — `SecurityManager.authenticateWithBiometric` busy-waited on the main thread (`while (!done) {}`) while the BiometricPrompt callbacks were posted to the main executor; the callbacks could never run because the main thread never became free, so the app never unlocked (ANR-like hang). Authentication is now fully asynchronous: the method takes an `onResult(Boolean)` callback, the prompt's success/error callbacks run on the main executor and flip `onUnlocked()` or surface a failure via the existing error text. The prompt's `DEVICE_CREDENTIAL` authenticator remains as a fallback so biometric-only users can still unlock with the device PIN/pattern. versionCode 16→17, versionName "0.3.3.1"→"0.3.3.2", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.1 | 2026-08-17 | **Emergency hotfix** for three UX blockers in v0.3.3.0: **Encrypt Notes at rest gating** — the toggle is now greyed out (not just visually, but with `enabled = false` on the Switch) until `securityEnabled && (pinEnabled || useBiometric)`. The subtitle also explains the requirement so the user understands why. **Enable Security without a PIN** — the `setSecurityEnabled(true)` branch used to force the flag back to `false` and surface "Choose PIN or Biometric first to enable security." which created a chicken-and-egg with the PIN toggle being greyed while security was off. The VM now just flips the master switch on; the PIN / Biometric / Encrypt sub-toggles were already gated to require Security on, so the user can pick one in any order. **Import passphrase dialog** — selecting an encrypted backup now opens `PassphraseDialog(mode = IMPORT)`: single field, no Generate / Copy trailing icons, no Confirm field, no password-policy check (an existing passphrase may predate a tightened policy). The Confirm-password validation, confirm-mismatch message, and Policy failure list are all EXPORT-only. Wrong passphrase still surfaces "Incorrect passphrase." via snackbar (handled by `BackupManager.preview()`). versionCode 15→16, versionName "0.3.3.0"→"0.3.3.1", SettingsViewModel.APP_VERSION bumped in lockstep. |
| 0.3.3.0 | 2026-08-17 | **Lock mode as a single choice** — the security section now exposes two mutually-exclusive toggles, PIN and Biometric, that grey each other out. Either one alone is enough to lock the app; enabling Biometric no longer requires setting a PIN first. A new "Reset PIN" row appears when PIN is the active mode (verify current → new → confirm) and the lock screen renders only the biometric button when no Incido PIN is configured. **Encrypted import passphrase prompt** — selecting an encrypted backup file now opens the passphrase dialog first, runs the preview with the supplied passphrase, and surfaces "Incorrect passphrase." via snackbar on mismatch (previously the import silently no-op'd). **Press-and-hold note card menu** — the inline delete button is gone; long-press a card (or tap the ⋮ button in the top-right) to open a DropdownMenu with a Delete entry, ready to host additional actions like Share later. |
| 0.1.0.0 | 2026-08-14 | Initial plan drafted via interview |
| 0.1.1.0 | 2026-08-14 | F1 explicit "list of currently saved notes" requirement + F7 auto-refresh + clarified UI section + editor IME fix (contentWindowInsets + adjustResize) + title/body on cards |
| 0.2.0.0 | 2026-08-14 | Polish + first Keep-parity features. Discard-confirm dialog; release signing config (dev keystore). Favorites (renamed from Pinned Notes), full-text search, 6 colour-coded notes, inline GFM checklists (open/done counts). ObjectBox KMP migration deferred to v0.5 (tracked). |
| 0.2.0.1 | 2026-08-14 | Hotfix: search-active flag folded into uiState so the search icon actually opens the field. |
| 0.3.2.0 | 2026-08-15 | **Settings screen** added under "Untagged" in the nav drawer with four sections: Appearance (System / Light / Dark theme + dynamic color), Security (master toggle + sub-toggles for at-rest encryption, PIN lock, fingerprint / face unlock, auto-lock timeout), Backup & Restore (export / import with plain-JSON or passphrase-encrypted modes), About (version + release notes dialog). **At-rest encryption** — the ObjectBox store is now opened with a 32-byte AES-256 key wrapped by the Android Keystore; toggling the switch generates / deletes the key and surfaces a "Re-encrypting notes…" dialog. **PIN lock + biometric** — the app shows a lock screen on cold launch and after the auto-lock timeout; a 4–6 digit PIN is hashed with PBKDF2-HMAC-SHA256 (100k iters) and verified via constant-time compare, with optional biometric (fingerprint / face) as a faster unlock. **Backup / Import / Export** — JSON codec with Base64 attachment bytes; encrypted variant uses AES-256-GCM + PBKDF2(passphrase, 200k iters) with a "Generate" button + clipboard "Copy". Passphrase policy: 12–32 chars, at least one digit, at least one special. **Release notes dialog** — tap the version on the About card to see the 5 most recent versions, newest first, in a scrollable list. Adds `USE_BIOMETRIC` + `USE_FINGERPRINT` permissions (still no INTERNET, still fully offline). |
| 0.3.0.0 | 2026-08-14 | Hashtags (separate entity + cross-ref, 5-tag cap, autocomplete, persistent chips on editor, search() also matches tag names) + bolder colour accent (14 dp gradient stripe + tinted card background + corner chip) + nav drawer (Home / Favorites / Untagged + recent tags) + centred app-bar title + new version scheme adopted (validator in app/build.gradle.kts). |
| 0.3.0.1 | 2026-08-14 | Urgent UI polish: editor hashtag row moved to the bottom (and hidden when empty), `+ add` chip removed (use `#` icon in top bar), colour picker centred horizontally, list-card dog-ear colour accent replaces the small circle chip, list cards show a hashtag row (with `+N` abbreviation when capped). |
| 0.3.0.2 | 2026-08-14 | Hotfix: dropped the redundant leading `#` from the AddTagSheet placeholder (was `#tag-name`, now `hashtag-name` — the leading `#` icon in the field already signals the format). |
| 0.3.0.3 | 2026-08-14 | Hotfix: `NoteRepositoryImpl.hashtagUsageSnapshot()` batched note/tag lookups (one `Box.get` per distinct noteId and tagId, not per xref) and the manual `trySend(snapshot())` in `observeHashtagsByRecentUse()` dropped — the ObjectBox observer's first fire is now the sole source. Result: the drawer's Recent Tags list fills in well under a second on real data instead of taking minutes. |
| 0.3.0.4 | 2026-08-14 | Hotfix: `observeHashtagsByRecentUse()` now subscribes to **all three** boxes (noteBox, tagBox, xrefBox) — adding a brand-new hashtag only touches `tagBox` + `xrefBox`, so the previous single-`noteBox` subscription missed those updates and the drawer's Recent Tags list only refreshed when something also touched `noteBox` (e.g. toggling the favourite star). This was a step toward the real fix but didn't fully address the underlying race (see v0.3.0.5). |
| 0.3.0.5 | 2026-08-15 | Hotfix: `NoteEditorViewModel.save()` still did upsert + per-tag `addHashtag` in three separate writes, so the drawer's `hashtagUsageSnapshot()` could read a transient empty `xrefBox` between the `tagBox.put` and the `xrefBox.put` and leave `emptyList()` stuck in the StateFlow (toggling the favourite star worked around it because `setFavorite` re-touches `noteBox`). New `NoteRepository.saveNoteWithHashtags()` wraps upsert + hashtag reconciliation in a single ObjectBox transaction via `boxStore.callInTx { ... }`, so the per-box observers fire **once** at commit time with the final state. New hashtags now appear in the drawer's Recent Tags list the moment a note is saved — no workaround required. |
| 0.3.1.0 | 2026-08-15 | **Context-aware search** — on the Favorites and Untagged pages, the search icon is now visible and a typed query intersects with the active filter (search only favourites on Favorites, only untagged notes on Untagged). On Home, search spans everything. **Photo / File attachments** — the editor now has Camera (camera icon) and Attach File (paperclip icon) buttons. Photos are captured via `MediaStore.ACTION_IMAGE_CAPTURE` (with a transient `FileProvider` outbox; bytes live in the database, the temp file is deleted) and files via `ACTION_OPEN_DOCUMENT`. Attachments are stored as `ByteArray` columns inside ObjectBox — no filesystem paths to manage. Each note's attachments show up as a thumbnail strip in the editor with a ✕ in the top-right corner to remove. Tapping a thumbnail opens a full-screen viewer with pinch-to-zoom + pan (`Modifier.transformable`) and a close button. **Card thumbnails** — notes with image attachments show the first image as a (alpha-blended, scrimmed) background on the list card. **Share-into** — the app accepts `ACTION_SEND` (text + image) and `ACTION_SEND_MULTIPLE` (multiple images) from other apps. Inbound bytes are copied into a process-singleton `SharedIntentBuffer` and pre-filled into a new-note editor. Adds the `CAMERA` permission — still no `INTERNET`, still fully offline. |
| 0.3.1.2 | 2026-08-15 | Hotfix for three issues found in v0.3.1.1 testing: **card thumbnails are actually visible now** — the v0.3.1.1 layout had the thumbnail Image as a sibling of the Card, so the Card's opaque `containerColor` was drawn on top and the image was completely hidden; the architecture is restructured so the Image + dark scrim live INSIDE the Card, and `containerColor = Color.Transparent` when a thumbnail is present (plain notes still get the existing tinted/surface background). **Camera photos honour EXIF orientation** — new `NoteRepositoryImpl.normalizeImageOrientation(bytes)` runs at storage time inside `addAttachment` (guarded `if (mimeType.startsWith("image/"))`); reads EXIF `Orientation`, rotates the bitmap, re-encodes as JPEG quality 92, and stores the corrected bytes so every render path (editor thumbnail, card thumbnail, full-screen viewer) sees the photo the right way up. **Non-image attachments open in the system viewer** — `AttachmentThumbnail.onClick` now branches on `isImage`: image taps still go to the in-app full-screen viewer; non-image taps write the bytes to a `cacheDir` temp file, get a `FileProvider` URI, and launch `Intent.ACTION_VIEW` with `FLAG_GRANT_READ_URI_PERMISSION` (the previous unconditional viewer path silently failed for PDFs/MP3s/etc. with a stuck "Loading…"). `file_paths.xml` already exposes `cacheDir` via `<cache-path>`, so no manifest change was needed. Attaching arbitrary file types from the paperclip icon was already shipped in v0.3.1.1 (the `*/*` intent filters) — no code change here, just called out so it's clear what was already in place. |
| 0.3.1.1 | 2026-08-15 | Hotfix for five issues found in v0.3.1.0 testing: persisted image attachments now render a thumbnail in the editor strip (previously fell through to the file-type placeholder because bytes weren't loaded) — `AttachmentThumbnail` lazy-loads bytes from the DB via `produceState` + `repository.getAttachmentBytes()`. Card thumbnails are more visible — alpha bumped 0.45 → 0.70 and the dark scrim dropped 0.18 → 0.08; also `clipToBounds()` so the image can't bleed past the card's rounded corners. Share-into from webpages now opens a fresh editor — `MainActivity.handleShareIntent()` stashes the share text synchronously before launching the async image-byte I/O, so the Compose tree's `LaunchedEffect(Unit)` always finds a payload on first composition. Share menu now offers Incido for any file type (PDF, MP3, video, archives) — added `<data android:mimeType="*/*" />` to both `ACTION_SEND` and `ACTION_SEND_MULTIPLE` intent filters. Editor top-bar title shortened to "Edit" / "New" so it fits on one line with the new icon row. |
---
## 11. Release Build Procedure (every release)
This is the canonical procedure for shipping a new Incido release. The
two deliverables are version-stamped APKs at the repository root:
- `incido-<versionName>-debug.apk` — for development / testing.
- `incido-<versionName>.apk` — signed with the dev keystore, for sharing.
A small Gradle task called `copyReleaseApks` (registered in
`app/build.gradle.kts`) does the stamping automatically — once
`versionName` is bumped, the filenames follow.
### 11.1 Bump the version (three places, in lockstep)
1. **`app/build.gradle.kts`** — in `android.defaultConfig`:
- `versionName = "<NEW_VERSION>"` (e.g. `0.3.6.0` — must match
`MAJOR.MINOR.MAINTENANCE.EMERGENCY`; the in-file regex validator
fails the build otherwise).
- `versionCode = <NEW_VERSION_CODE>` (monotonic int, +1 from the
previous release).
2. **`composeApp/src/main/kotlin/org/incido/compose/ui/settings/SettingsViewModel.kt`**
— `const val APP_VERSION = "<NEW_VERSION>"` so the About card in
Settings displays the new version and the in-app release-notes
dialog recognises it.
3. **`README.md`** — bump the intro paragraph and "Current release"
line, and add a new row at the top of the Changelog table (the table
is the user-facing changelog — §10 keeps the historical release
notes).
### 11.2 Build both APKs (and stamp them)
From the repository root:
```bash
./gradlew clean assembleDebug assembleRelease
```
This is a single command that does everything:
1. `clean` wipes the previous `app/build/`.
2. `assembleDebug` builds the debug APK at
`app/build/outputs/apk/debug/app-debug.apk`.
3. `assembleRelease` builds the signed release APK at
`app/build/outputs/apk/release/app-release.apk`.
4. `copyReleaseApks` (registered as a `finalizedBy` of `assembleRelease`)
copies both files to the repo root with the version-stamped names:
- `./incido-<versionName>-debug.apk`
- `./incido-<versionName>.apk`
The release APK is signed by `signingConfigs.release`, which points at
the dev keystore at `keystore/release.jks` (alias `incido`, store and
key password both `incido_dev_keystore`). **Never ship this keystore to
an external store** — see `keystore/README.md` for instructions on
generating a production keystore before Play Store / F-Droid
distribution.
#### Why a copy task and not `outputFileName` mutation?
We tried the obvious `applicationVariants.outputs.all { output ->
output.outputFileName = ... }` pattern first, but AGP 8.7.2's Kotlin
DSL trips over two quirks:
1. The legacy `applicationVariants.outputs.all { ... }` lambda
resolution clashes with Kotlin's `Iterable<T>.all(predicate: (T) ->
Boolean)` — Kotlin picks the predicate form and the assignment
fails to type-check (even with an explicit `Action<BaseVariantOutput>`
wrapper and `@Suppress("DEPRECATION")`).
2. The modern `androidComponents.onVariants { ... }` API doesn't
expose `outputFileName` as a settable property on its outputs.
A `tasks.register("copyReleaseApks") { ... }` is one Gradle idiomatic
way out: the APKs land where AGP's defaults want them, and the copy
task just renames-and-drops at the repo root with `versionName` baked
in. The `.gitignore` rule for `incido-*.apk` means these files never
accidentally land in a commit.
### 11.3 Verify
```bash
ls -la incido-<versionName>-debug.apk incido-<versionName>.apk
```
Expected:
- Both files exist at the repo root with the correct names.
- Debug APK is roughly 25–35 MB.
- Release APK is roughly 20–25 MB (smaller because R8 will eventually
minify once `isMinifyEnabled = true` is flipped on; for now both
builds are unminified).
Smoke-test the debug APK on a real device before sharing the release:
```bash
adb install -r incido-<versionName>-debug.apk
```
### 11.4 One-liner for the next release
```bash
# (after bumping versionName/versionCode/APP_VERSION/README per §11.1)
./gradlew clean assembleDebug assembleRelease && \
ls -la incido-$(grep '^versionName' app/build.gradle.kts | head -1 | awk -F'"' '{print $2}')-*.apk
```
(The `ls` extracts the version from `app/build.gradle.kts` so you don't
have to type it — `./gradlew assembleRelease` has already deposited
both stamped APKs at the repo root by the time you reach it.)
---
## Appendix A — Key Library Versions (for the version catalog)
These versions are current as of plan drafting. The AI assistant should verify and pin them in `gradle/libs.versions.toml` at project scaffold time:
| Library | Version | Purpose |
|---------|---------|---------|
| Kotlin | 2.0.21 | Language |
| Compose Multiplatform | 1.7.0 | Cross-platform UI |
| Jetpack Compose BOM | 2024.10.00 | Android UI |
| AndroidX Lifecycle | 2.8.7 | ViewModels, lifecycle |
| AndroidX Navigation Compose | 2.8.4 | Screen navigation |
| AndroidX Activity Compose | 1.9.3 | Activity integration |
| ObjectBox | 4.0.3 | Database |
| Coroutines | 1.9.0 | Async |
(AIs: confirm latest stable versions before scaffolding.)