chore(deps): update agp to v9.3.1

Reviewed-on: https://codeberg.org/jlmakiola/calendula/pulls/130

.forgejo/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something doesn't work the way it should
+title: ""
+labels:
+  - bug
+---
+
+### What happened
+
+
+### What you expected
+
+
+### Steps to reproduce
+1.
+2.
+3.
+
+### Environment
+- Calendula version: <!-- Settings → bottom of the screen -->
+- Android version:
+- Device:
+- Installed from: <!-- official F-Droid / the self-hosted repo / built from source -->
+- Affected calendar: <!-- Google, CalDAV (DAVx5, Nextcloud, …), on-device/local,
+                         subscribed/WebCal, birthdays — provider behaviour differs
+                         a lot per account type, so this often points straight at
+                         the cause -->
+- Time zone: <!-- only if the problem involves dates or all-day events -->
+

.forgejo/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,18 @@
+# Kept enabled so anything that doesn't fit the four templates still has a way
+# in (the `ToDo` label exists for exactly those).
+blank_issues_enabled: true
+
+contact_links:
+  - name: Translate Calendula
+    url: https://weblate.dev.jeanlucmakiola.de/engage/calendula/
+    about: >-
+      Translations are managed on Weblate, not here — it owns every values-*
+      file, so a hand-edited translation gets overwritten on the next sync.
+      No coding needed: pick or request a language and translate in the browser.
+
+  - name: Contributing guide
+    url: https://codeberg.org/jlmakiola/calendula/src/branch/main/CONTRIBUTING.md
+    about: >-
+      Before opening a pull request: the issue-first workflow, which release
+      branch to target, how to build (there's a submodule), and the
+      architectural rules a change is reviewed against.

.forgejo/ISSUE_TEMPLATE/crash_report.md

@@ -0,0 +1,27 @@
+---
+name: Crash report
+about: Report a crash. Calendula can capture this for you (Settings → Report a problem, or the prompt after a crash) — it copies the report to your clipboard and prefills this form.
+title: "Crash: "
+labels:
+  - bug
+  - crash
+  - priority/high
+---
+
+<!--
+Thanks for reporting a crash in Calendula!
+
+If the app prefilled this for you, the crash report is already below — just add
+what you were doing and submit. Otherwise, paste the report from your clipboard
+into the code block. The report contains only app/Android/device versions and the
+stack trace — no personal data or calendar content.
+-->
+
+### What happened
+
+
+### Crash report
+
+```
+(paste the crash report here)
+```

.forgejo/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ""
+labels:
+  - feat
+---
+
+### What would you like Calendula to do?
+
+
+### Why — what problem does it solve?
+
+
+### Anything else
+<!-- mockups, examples from other apps, alternatives you considered -->

.forgejo/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,19 @@
+---
+name: Question
+about: Ask how something works or get help using Calendula
+title: ""
+labels:
+  - question
+---
+
+### Your question
+
+
+### What you've tried
+<!-- so far, if anything -->
+
+
+### Context
+- Calendula version: <!-- Settings → bottom of the screen -->
+- Android version:
+- Device:

.forgejo/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+<!--
+Thanks for contributing to Calendula!
+
+Please skim CONTRIBUTING.md if you haven't:
+https://codeberg.org/jlmakiola/calendula/src/branch/main/CONTRIBUTING.md
+
+Two things it's easy to get wrong:
+  • Features need a discussed issue first — an undiscussed feature PR may be
+    closed unmerged even when the code is good.
+  • Target the release branch for your issue's milestone (milestone 2.18.0 →
+    release/v2.18.0), not main. If you targeted main, just say so below and it
+    will be retargeted.
+-->
+
+### What this changes
+
+
+### Why
+
+<!-- Closes #123 — link the issue this implements or fixes. -->
+
+
+### How it was tested
+
+<!--
+Which of these ran green, and anything you exercised by hand. On-device notes
+are especially useful for UI changes.
+
+  ./gradlew lint test assembleDebug
+  python3 scripts/check_translations.py
+-->
+
+
+### Checklist
+
+- [ ] There's an issue for this, and (for a feature) it got a go-ahead
+- [ ] Targeting the release branch for that issue's milestone — or `main`, noted above
+- [ ] `./gradlew lint test assembleDebug` passes locally
+- [ ] No `values-*/strings.xml` touched (Weblate owns those; new English strings in `values/` are fine)
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`, if the change is user-visible
+- [ ] No planning or design documents committed

.forgejo/workflows/ci.yaml

@@ -0,0 +1,169 @@
+name: CI
+
+# One gate per pull request. Branch pushes no longer trigger CI on their own,
+# so a change is built once on its PR (covering feature -> release/* and
+# release/* -> main) instead of once per push and again on the merge to main.
+# The merge itself is handled by release.yaml, which only does heavy work when
+# the merge actually cuts a release.
+on:
+  pull_request:
+
+# Cancel superseded runs for the same PR.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Single job named `ci` so the required "CI" status check is always reported,
+  # even for docs-only PRs: those just skip the Android build and the job still
+  # succeeds (fast green check) instead of being filtered out and leaving the
+  # required check pending forever.
+  ci:
+    runs-on: docker
+    env:
+      ANDROID_HOME: /opt/android-sdk
+      ANDROID_SDK_ROOT: /opt/android-sdk
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history so the base..HEAD diff below has a merge-base.
+          fetch-depth: 0
+          submodules: recursive
+
+      # Cheap, always-on guard: the release build must stay reproducible for the
+      # official F-Droid repo (no AGP VCS-info embedding). Runs regardless of
+      # change scope so a regression can't slip through on a "docs-only" PR.
+      - name: Reproducible-release invariant
+        run: bash scripts/check_reproducible_release.sh
+
+      # Decide whether anything that affects the app build changed. Docs, store
+      # metadata, licence texts and forge housekeeping don't, so those PRs skip
+      # the SDK + Gradle work below but still report a green `ci`.
+      - name: Classify change scope
+        id: scope
+        env:
+          # Deliberately a skip-list, not a build-list: a path nobody thought
+          # about defaults to building. Only paths the Gradle build provably
+          # never reads belong here — note that the workflows themselves, the
+          # `.gitmodules` submodule pointer and `scripts/` are *not* in it.
+          SKIP_RE: '(\.md$|^docs/|^fastlane/|^fdroid-metadata/|^licenses/|^\.planning/|^\.(forgejo|gitea)/ISSUE_TEMPLATE/|^\.editorconfig$|^\.gitattributes$|^\.gitignore$|^renovate\.json5$|^LICENSE$)'
+        run: |
+          set -e
+          BASE="${{ github.base_ref }}"
+          # Normally the bare branch name; tolerate a full ref, which would
+          # otherwise make the merge-base lookup fail and quietly degrade this
+          # guard into "always build".
+          BASE="${BASE#refs/heads/}"
+          if [ -z "$BASE" ]; then
+            echo "No base branch on this event — running the full build to be safe."
+            echo "code=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # Full (not --depth=1) base fetch so the merge-base is present even when
+          # the PR branch forked several commits back; a shallow tip has no merge
+          # base with a divergent branch and `git diff base...HEAD` aborts.
+          git fetch --no-tags origin "$BASE"
+          MB=$(git merge-base "origin/$BASE" HEAD 2>/dev/null || true)
+          if [ -z "$MB" ]; then
+            # No common ancestor available — don't risk skipping the build.
+            echo "No merge base with origin/$BASE — running the full build to be safe."
+            echo "code=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          CHANGED=$(git diff --name-only "$MB" HEAD)
+          echo "Changed files:"; echo "$CHANGED"
+          RELEVANT=$(echo "$CHANGED" | grep -vE "$SKIP_RE" || true)
+          if [ -n "$RELEVANT" ]; then
+            # Naming them makes "why did my docs PR build for four minutes?"
+            # answerable from the log alone.
+            echo "Build-relevant changes:"; echo "$RELEVANT"
+            echo "code=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Docs/metadata-only change — skipping the Android build."
+            echo "code=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Java
+        if: steps.scope.outputs.code == 'true'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+
+      # Fully qualified on purpose. Codeberg resolves bare `uses:` refs against
+      # data.forgejo.org, Forgejo's own action mirror — actions/checkout,
+      # setup-java and cache all exist there, but android-actions/setup-android
+      # does not, and the job dies with "repository not found". Gitea's instance
+      # defaults to GitHub, which is why this never surfaced before the split.
+      - name: Setup Android SDK
+        if: steps.scope.outputs.code == 'true'
+        uses: https://github.com/android-actions/setup-android@v3
+        with:
+          # Default ("tools platform-tools") drags in the Android Emulator
+          # (~300 MB) which the build never uses.
+          packages: ''
+
+      - name: Setup Android SDK cache
+        if: steps.scope.outputs.code == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /opt/android-sdk
+          key: ${{ runner.os }}-android-sdk-37-36.0.0
+
+      - name: Install Android SDK packages
+        if: steps.scope.outputs.code == 'true'
+        run: |
+          yes | sdkmanager --licenses >/dev/null || true
+          sdkmanager \
+            "platform-tools" \
+            "platforms;android-37.0" \
+            "build-tools;36.0.0"
+
+      - name: Setup Gradle cache
+        if: steps.scope.outputs.code == 'true'
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', 'gradle/libs.versions.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Grant execute permission for gradlew
+        if: steps.scope.outputs.code == 'true'
+        run: chmod +x ./gradlew
+
+      # No --no-daemon: the daemon lives only as long as this job container
+      # and lets the following steps skip JVM startup + reconfiguration.
+      - name: Lint (debug variant only)
+        if: steps.scope.outputs.code == 'true'
+        run: ./gradlew lintDebug
+
+      - name: Unit tests
+        if: steps.scope.outputs.code == 'true'
+        run: ./gradlew testDebugUnitTest
+
+      - name: Assemble debug APK
+        if: steps.scope.outputs.code == 'true'
+        run: ./gradlew assembleDebug
+
+      - name: Trivy filesystem scan
+        if: steps.scope.outputs.code == 'true'
+        run: |
+          set -e
+          SUDO=""
+          if command -v sudo >/dev/null 2>&1; then
+            SUDO="sudo"
+          fi
+          if command -v apt-get >/dev/null 2>&1; then
+            $SUDO apt-get update
+            $SUDO apt-get install -y wget apt-transport-https gnupg lsb-release
+            wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | $SUDO tee /usr/share/keyrings/trivy.gpg > /dev/null
+            echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | $SUDO tee /etc/apt/sources.list.d/trivy.list
+            $SUDO apt-get update
+            $SUDO apt-get install -y trivy
+          fi
+          trivy filesystem --severity HIGH,CRITICAL --exit-code 0 .
+        continue-on-error: true

.forgejo/workflows/translations.yaml

@@ -0,0 +1,39 @@
+name: Translations
+
+# Fast, SDK-free parity check for translation resources, so Weblate PRs (which
+# only touch values-*/strings.xml) get quick feedback without the full Android
+# build. The deeper checks still run in CI via lintDebug (ExtraTranslation).
+#
+# Runs on every PR (no path filter) so the required "Translations / check"
+# status is always reported — like the `ci` job. A path-filtered workflow is
+# skipped on unrelated PRs and never posts its status, which leaves that
+# required check pending forever and blocks the merge of any code-only PR into a
+# release/* branch. The check itself is cheap and simply passes when the
+# committed translations are consistent, so always running it costs nothing.
+on:
+  pull_request:
+
+concurrency:
+  group: translations-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Ensure python3
+        run: |
+          if ! command -v python3 >/dev/null 2>&1; then
+            if command -v apt-get >/dev/null 2>&1; then
+              apt-get update && apt-get install -y python3
+            elif command -v apk >/dev/null 2>&1; then
+              apk add --no-cache python3
+            fi
+          fi
+          python3 --version
+
+      - name: Check translation parity
+        run: python3 scripts/check_translations.py

.gitea/workflows/ci.yaml

@@ -1,93 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches:
-      - '**'
-    tags-ignore:
-      - '**'
-
-# Cancel superseded runs on the same branch.
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  ci:
-    runs-on: docker
-    env:
-      ANDROID_HOME: /opt/android-sdk
-      ANDROID_SDK_ROOT: /opt/android-sdk
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Java
-        uses: actions/setup-java@v4
-        with:
-          distribution: 'zulu'
-          java-version: '17'
-
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v3
-        with:
-          # Default ("tools platform-tools") drags in the Android Emulator
-          # (~300 MB) which the build never uses.
-          packages: ''
-
-      - name: Setup Android SDK cache
-        uses: actions/cache@v4
-        with:
-          path: /opt/android-sdk
-          key: ${{ runner.os }}-android-sdk-37-36.0.0
-
-      - name: Install Android SDK packages
-        run: |
-          yes | sdkmanager --licenses >/dev/null || true
-          sdkmanager \
-            "platform-tools" \
-            "platforms;android-37.0" \
-            "build-tools;36.0.0"
-
-      - name: Setup Gradle cache
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.gradle/caches
-            ~/.gradle/wrapper
-          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', 'gradle/libs.versions.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-
-      - name: Grant execute permission for gradlew
-        run: chmod +x ./gradlew
-
-      # No --no-daemon: the daemon lives only as long as this job container
-      # and lets the following steps skip JVM startup + reconfiguration.
-      - name: Lint (debug variant only)
-        run: ./gradlew lintDebug
-
-      - name: Unit tests
-        run: ./gradlew testDebugUnitTest
-
-      - name: Assemble debug APK
-        run: ./gradlew assembleDebug
-
-      - name: Trivy filesystem scan
-        if: github.ref == 'refs/heads/main'
-        run: |
-          set -e
-          SUDO=""
-          if command -v sudo >/dev/null 2>&1; then
-            SUDO="sudo"
-          fi
-          if command -v apt-get >/dev/null 2>&1; then
-            $SUDO apt-get update
-            $SUDO apt-get install -y wget apt-transport-https gnupg lsb-release
-            wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | $SUDO tee /usr/share/keyrings/trivy.gpg > /dev/null
-            echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | $SUDO tee /etc/apt/sources.list.d/trivy.list
-            $SUDO apt-get update
-            $SUDO apt-get install -y trivy
-          fi
-          trivy filesystem --severity HIGH,CRITICAL --exit-code 0 .
-        continue-on-error: true

.gitea/workflows/release.yaml

@@ -1,78 +1,128 @@
-name: Build and Release to F-Droid
+name: Release — F-Droid repo + Gitea/Codeberg release + Play
 
+# A release is cut by merging a release branch into main with a bumped
+# versionName (see docs/RELEASING.md). This workflow reads that versionName and,
+# if no matching tag exists yet, runs tests, builds + signs the APK, publishes
+# it to the F-Droid repo, creates the vX.Y.Z tag + Gitea release, and mirrors
+# that release to Codeberg with the signed APK + a SHA-256 checksum as a
+# direct-download channel — the tag is an output of the pipeline, not its
+# trigger. Ordinary merges (no version bump) fall through `detect` and do
+# nothing.
+#
+# A trailing `play` job then uploads the App Bundle to Google Play. It is last
+# and separate because Play is the only channel that can reject a good build for
+# reasons the pipeline can't see, and that must not endanger a release which has
+# already shipped to F-Droid and Codeberg. It skips cleanly until the
+# PLAY_SERVICE_ACCOUNT_JSON secret exists.
+#
+# A manual workflow_dispatch (from a branch) runs the re-sign-only recovery
+# path: it re-signs the existing F-Droid index with the repo key and re-uploads,
+# without building an APK or creating a release. Used for key rotation / repo
+# recovery.
 on:
   push:
-    tags:
-      - '*'
+    branches: [main]
   workflow_dispatch:
 
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
-  ci:
+  # Cheap gate: resolve the version from the committed build.gradle and decide
+  # whether this push actually cuts a new release (no tag for it yet). Keeps the
+  # heavy job from running on every merge to main.
+  detect:
+    # Gitea only. The workflow directory split already keeps this file invisible
+    # to Codeberg — Forgejo's lookup is first-match-wins, and .forgejo/workflows
+    # exists — but that only holds while .forgejo/ is non-empty. Move the last
+    # file out of it and Codeberg would fall back to .gitea/workflows and start
+    # running the release pipeline on the contributor-facing runner, with no
+    # secrets. repository_owner differs between the two forges regardless of
+    # URL, proxy or instance rename, so this closes it permanently.
+    if: github.repository_owner == 'makiolaj'
     runs-on: docker
-    env:
-      ANDROID_HOME: /opt/android-sdk
-      ANDROID_SDK_ROOT: /opt/android-sdk
+    outputs:
+      is_release: ${{ steps.v.outputs.is_release }}
+      version: ${{ steps.v.outputs.version }}
+      version_code: ${{ steps.v.outputs.version_code }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-
-      - name: Setup Java
-        uses: actions/setup-java@v4
         with:
-          distribution: 'zulu'
-          java-version: '17'
+          submodules: recursive
 
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v3
-        with:
-          packages: ''
-
-      - name: Setup Android SDK cache
-        uses: actions/cache@v4
-        with:
-          path: /opt/android-sdk
-          key: ${{ runner.os }}-android-sdk-37-36.0.0
-
-      - name: Install Android SDK packages
+      - name: Resolve version and whether it is a new release
+        id: v
+        env:
+          # Tags are read from Codeberg, which is canonical — deliberately NOT
+          # from the Gitea API this workflow runs on. The Codeberg -> Gitea sync
+          # is a push mirror, i.e. `git push --mirror`, which deletes refs the
+          # source does not have. A tag minted here on Gitea is therefore wiped
+          # by the next sync (Codeberg does not have it yet) and only reappears
+          # once the tag push at the end of this workflow propagates back.
+          # Asking Gitea inside that window would report "no tag" for a release
+          # that already shipped, and cut it a second time.
+          # Public repo, so this read needs no token.
+          TAG_API: https://codeberg.org/api/v1/repos/jlmakiola/calendula
         run: |
-          yes | sdkmanager --licenses >/dev/null || true
-          sdkmanager \
-            "platform-tools" \
-            "platforms;android-37.0" \
-            "build-tools;36.0.0"
+          set -e
+          VERSION=$(grep -oP 'versionName\s*=\s*"\K[^"]+' app/build.gradle.kts)
+          if [ -z "$VERSION" ]; then echo "No versionName in app/build.gradle.kts" >&2; exit 1; fi
+          MAJOR=$(echo "$VERSION" | cut -d. -f1); MINOR=$(echo "$VERSION" | cut -d. -f2); PATCH=$(echo "$VERSION" | cut -d. -f3)
+          MAJOR=${MAJOR:-0}; MINOR=${MINOR:-0}; PATCH=${PATCH:-0}
+          VERSION_CODE=$(( MAJOR * 10000 + MINOR * 100 + PATCH ))
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "version_code=$VERSION_CODE" >> "$GITHUB_OUTPUT"
+          echo "Resolved version $VERSION (code $VERSION_CODE)"
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "Manual dispatch — re-sign path, not a release."
+            echo "is_release=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # A tag for this version already existing means the release shipped on
+          # an earlier push; do nothing. Absent => this merge cuts the release.
+          #
+          # Anything other than a clean 200/404 is treated as fatal rather than
+          # as "no tag". A Codeberg outage or a network blip would otherwise
+          # read as absent and re-cut a release that has already shipped —
+          # republishing to F-Droid and Play. Failing here is recoverable; a
+          # duplicate release is not.
+          STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$TAG_API/git/refs/tags/v$VERSION" || echo 000)
+          case "$STATUS" in
+            200)
+              echo "Tag v$VERSION already exists on Codeberg — nothing to release."
+              echo "is_release=false" >> "$GITHUB_OUTPUT"
+              ;;
+            404)
+              echo "No tag for v$VERSION on Codeberg yet — cutting the release."
+              echo "is_release=true" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "Codeberg tag lookup for v$VERSION returned HTTP $STATUS." >&2
+              echo "Refusing to guess: treating this as 'no tag' could re-cut a shipped release." >&2
+              exit 1
+              ;;
+          esac
 
-      - name: Setup Gradle cache
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.gradle/caches
-            ~/.gradle/wrapper
-          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', 'gradle/libs.versions.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-
-      - name: Grant execute permission for gradlew
-        run: chmod +x ./gradlew
-
-      # Lint already enforced on every push to main via ci.yaml.
-      # Release sanity only re-runs tests + a debug build to catch
-      # any tag-resolved drift (e.g. version code substitution issues).
-
-      - name: Unit tests
-        run: ./gradlew testDebugUnitTest
-
-      - name: Assemble debug APK (sanity)
-        run: ./gradlew assembleDebug
-
-  build-and-deploy:
-    needs: ci
+  # Releases: build + sign + publish, then mint the tag and Gitea release.
+  # Also runs on manual dispatch, where it skips the build and just re-signs and
+  # re-uploads the existing index (recovery path).
+  release:
+    needs: detect
+    if: needs.detect.outputs.is_release == 'true' || github.event_name == 'workflow_dispatch'
     runs-on: docker
     env:
       ANDROID_HOME: /opt/android-sdk
       ANDROID_SDK_ROOT: /opt/android-sdk
+      VERSION: ${{ needs.detect.outputs.version }}
+      VERSION_CODE: ${{ needs.detect.outputs.version_code }}
+      IS_RELEASE: ${{ needs.detect.outputs.is_release }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - name: Setup Java
         uses: actions/setup-java@v4
@@ -121,22 +171,26 @@ jobs:
             $SUDO apk add --no-cache jq
           fi
 
-      - name: Set version from git tag
+      - name: Grant execute permission for gradlew
+        run: chmod +x ./gradlew
+
+      # The committed versionName is the source of truth. Pin versionCode to the
+      # value derived from it so the published APK's code is always
+      # MAJOR*10000 + MINOR*100 + PATCH even if the committed code was forgotten.
+      - name: Pin versionCode to versionName
+        if: env.IS_RELEASE == 'true'
         run: |
           set -e
-          RAW_TAG="${GITHUB_REF_NAME:-${GITHUB_REF##*/}}"
-          VERSION="${RAW_TAG#v}"
-          MAJOR=$(echo "$VERSION" | cut -d. -f1)
-          MINOR=$(echo "$VERSION" | cut -d. -f2)
-          PATCH=$(echo "$VERSION" | cut -d. -f3)
-          MAJOR=${MAJOR:-0}; MINOR=${MINOR:-0}; PATCH=${PATCH:-0}
-          VERSION_CODE=$(( MAJOR * 10000 + MINOR * 100 + PATCH ))
-          echo "Version: $VERSION, VersionCode: $VERSION_CODE"
-          sed -i "s/versionName = \".*\"/versionName = \"$VERSION\"/" app/build.gradle.kts
           sed -i "s/versionCode = .*/versionCode = $VERSION_CODE/" app/build.gradle.kts
           grep -E 'versionName|versionCode' app/build.gradle.kts
 
+      # Test the exact commit being shipped (only on a real release).
+      - name: Unit tests
+        if: env.IS_RELEASE == 'true'
+        run: ./gradlew testDebugUnitTest
+
       - name: Setup Android Keystore
+        if: env.IS_RELEASE == 'true'
         env:
           KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
           KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
@@ -151,10 +205,8 @@ jobs:
           storeFile=upload-keystore.jks
           EOF
 
-      - name: Grant execute permission for gradlew
-        run: chmod +x ./gradlew
-
       - name: Build release APK
+        if: env.IS_RELEASE == 'true'
         run: ./gradlew assembleRelease
 
       - name: Setup F-Droid Server Tools
@@ -165,50 +217,81 @@ jobs:
           $SUDO apt-get install -y sshpass python3-pip
           pip3 install --break-system-packages --upgrade fdroidserver
 
-      - name: Initialize or fetch F-Droid Repository
+      - name: Fetch existing F-Droid repo from Hetzner
         env:
           HOST: ${{ secrets.HETZNER_HOST }}
           USER: ${{ secrets.HETZNER_USER }}
           PASS: ${{ secrets.HETZNER_PASS }}
         run: |
+          set -euo pipefail
+          SSH_OPTS="-o StrictHostKeyChecking=no -o ConnectTimeout=20"
           mkdir -p fdroid
-          sshpass -p "$PASS" sftp -o StrictHostKeyChecking=no "$USER@$HOST" <<'SFTP'
-          -mkdir dev
-          -mkdir dev/fdroid
-          -mkdir dev/fdroid/repo
-          SFTP
-          sshpass -p "$PASS" scp -o StrictHostKeyChecking=no -r "$USER@$HOST:dev/fdroid/." fdroid/ || (cd fdroid && fdroid init)
+          # Pull only the published repo/ (all apps' APKs), any per-app
+          # metadata, and the repo icon — enough to rebuild the index without
+          # dropping the other apps. The signing key is deliberately NOT pulled
+          # from the box; it comes from CI secrets in the next step so it never
+          # has to live in the web-served tree.
+          sshpass -p "$PASS" scp $SSH_OPTS -r "$USER@$HOST:dev/fdroid/repo" fdroid/ 2>/dev/null || true
+          sshpass -p "$PASS" scp $SSH_OPTS -r "$USER@$HOST:dev/fdroid/metadata" fdroid/ 2>/dev/null || true
+          sshpass -p "$PASS" scp $SSH_OPTS "$USER@$HOST:dev/fdroid/icon.png" fdroid/ 2>/dev/null || true
+          mkdir -p fdroid/repo fdroid/metadata
 
-      - name: Ensure F-Droid repo signing key and icon
+      - name: Restore F-Droid signing key and config from secrets
+        env:
+          FDROID_KEYSTORE_BASE64: ${{ secrets.FDROID_KEYSTORE_BASE64 }}
+          FDROID_CONFIG_BASE64: ${{ secrets.FDROID_CONFIG_BASE64 }}
         run: |
-          cd fdroid
-          mkdir -p repo/icons
-          if [ ! -f keystore.p12 ]; then
-            fdroid update --create-key
+          set -euo pipefail
+          # Fail loudly if the repo key is not configured. NEVER auto-generate
+          # one: a fresh key changes the repo fingerprint and breaks every
+          # user's pinned repo.
+          if [ -z "${FDROID_KEYSTORE_BASE64:-}" ] || [ -z "${FDROID_CONFIG_BASE64:-}" ]; then
+            echo "ERROR: FDROID_KEYSTORE_BASE64 / FDROID_CONFIG_BASE64 secrets are not set." >&2
+            echo "Refusing to continue — will not auto-generate a new repo key." >&2
+            exit 1
           fi
+          echo "$FDROID_KEYSTORE_BASE64" | base64 --decode > fdroid/keystore.p12
+          echo "$FDROID_CONFIG_BASE64"   | base64 --decode > fdroid/config.yml
+          test -s fdroid/keystore.p12
+          test -s fdroid/config.yml
+          mkdir -p fdroid/repo/icons
 
       - name: Copy new APK to repo
+        if: env.IS_RELEASE == 'true'
         run: |
           set -e
           mkdir -p fdroid/repo
-          REF_NAME="${GITHUB_REF_NAME:-${GITHUB_REF##*/}}"
-          SAFE_REF_NAME="$(echo "$REF_NAME" | tr '/ ' '__' | tr -cd '[:alnum:]_.-')"
-          if [ -z "$SAFE_REF_NAME" ]; then
-            SAFE_REF_NAME="${GITHUB_SHA:-manual}"
-          fi
-          cp app/build/outputs/apk/release/app-release.apk "fdroid/repo/calendula_${SAFE_REF_NAME}.apk"
+          cp app/build/outputs/apk/release/app-release.apk "fdroid/repo/calendula_v${VERSION}.apk"
 
-      - name: Copy metadata to F-Droid repo
+      # Per-version "What's New": ensure this version's changelog exists in the
+      # fastlane tree. The committed hand-written summary (kept under Play's
+      # 500-char cap) is used as-is; only if it is missing does the script fall
+      # back to CHANGELOG.md, so the self-hosted repo never depends on the
+      # commit having happened. The transform below then carries it across.
+      - name: Ensure this version's changelog is in the fastlane tree
+        if: env.IS_RELEASE == 'true'
+        run: bash scripts/sync_changelog_to_fastlane.sh
+
+      - name: Build F-Droid metadata from fastlane (single source of truth)
         run: |
           mkdir -p fdroid/metadata
-          cp -r fdroid-metadata/* fdroid/metadata/
+          # App-level control file (Categories/License/links) for the self-hosted
+          # repo's `fdroid update`.
+          cp fdroid-metadata/de.jeanlucmakiola.calendula.yml fdroid/metadata/
+          # Localized text + graphics + per-version changelogs come from the SAME
+          # fastlane tree the official F-Droid repo harvests from source,
+          # transformed into the F-Droid repo "localized" layout. One source of
+          # truth, both channels.
+          bash scripts/fastlane_to_fdroid_localized.sh \
+            fastlane/metadata/android \
+            fdroid/metadata/de.jeanlucmakiola.calendula
 
       - name: Generate F-Droid Index
         run: |
           cd fdroid
           fdroid update -c
 
-      - name: Upload Repo to Hetzner
+      - name: Upload repo/ to Hetzner
         env:
           HOST: ${{ secrets.HETZNER_HOST }}
           USER: ${{ secrets.HETZNER_USER }}
@@ -219,6 +302,354 @@ jobs:
           sshpass -p "$PASS" sftp $SSH_OPTS "$USER@$HOST" <<'SFTP'
           -mkdir dev
           -mkdir dev/fdroid
-          -mkdir dev/fdroid/repo
           SFTP
-          sshpass -p "$PASS" scp $SSH_OPTS -r fdroid/. "$USER@$HOST:dev/fdroid/"
+          # Publish the signed repo/ plus metadata/ (descriptions, screenshots,
+          # per-version changelogs) so changelog history survives across
+          # releases. keystore.p12 and config.yml are NEVER uploaded.
+          sshpass -p "$PASS" scp $SSH_OPTS -r fdroid/repo fdroid/metadata "$USER@$HOST:dev/fdroid/"
+
+      # The APK is published and the index re-signed — now record the release.
+      # Creating it with target_commitish makes Gitea create the vX.Y.Z tag at
+      # this commit, so the tag only ever marks a fully-shipped release (and a
+      # failure before here leaves no tag, so re-running the workflow retries).
+      - name: Create tag + Gitea release
+        if: env.IS_RELEASE == 'true'
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          SHA: ${{ github.sha }}
+        run: |
+          set -e
+          TAG="v$VERSION"
+          # Notes = this version's CHANGELOG section.
+          awk -v ver="$VERSION" '
+            $0 ~ "^## \\[" ver "\\]" { flag = 1; next }
+            /^## \[/ { flag = 0 }
+            flag' CHANGELOG.md > release-notes.md
+          sed -i -e '/./,$!d' release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "_No changelog entry for ${VERSION} — see CHANGELOG.md._" > release-notes.md
+          fi
+          python3 - "$TAG" "$SHA" <<'PY' > payload.json
+          import json, sys
+          print(json.dumps({
+              "tag_name": sys.argv[1],
+              "target_commitish": sys.argv[2],
+              "name": sys.argv[1],
+              "body": open("release-notes.md").read(),
+              "draft": False,
+              "prerelease": False,
+          }))
+          PY
+          # Upsert (re-run safe): PATCH if a release for the tag already exists,
+          # else POST a new one (which also creates the tag at target_commitish).
+          curl -s -H "Authorization: token $TOKEN" "$API/releases/tags/$TAG" > existing.json
+          ID=$(jq -r '.id // empty' existing.json 2>/dev/null || true)
+          if [ -n "$ID" ]; then
+            CODE=$(curl -s -o response.json -w '%{http_code}' -X PATCH \
+              -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+              -d @payload.json "$API/releases/$ID")
+            OK=200
+          else
+            CODE=$(curl -s -o response.json -w '%{http_code}' -X POST \
+              -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+              -d @payload.json "$API/releases")
+            OK=201
+          fi
+          cat response.json
+          if [ "$CODE" != "$OK" ]; then
+            echo "Release upsert failed with HTTP $CODE (expected $OK)" >&2
+            exit 1
+          fi
+          echo "Created/updated release $TAG at $SHA"
+
+      # Archive the R8 mapping so user crash stacktraces stay deobfuscatable.
+      # Attached to the release (it's not an APK, so it fits the no-binaries
+      # rule). Best-effort: never fail a release over it.
+      - name: Attach R8 mapping to Gitea release
+        if: env.IS_RELEASE == 'true'
+        continue-on-error: true
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+        run: |
+          set -e
+          MAP="app/build/outputs/mapping/release/mapping.txt"
+          if [ ! -f "$MAP" ]; then echo "No mapping.txt (R8 off?) — skipping."; exit 0; fi
+          TAG="v$VERSION"
+          ASSET="mapping-${VERSION}.txt.gz"
+          gzip -c "$MAP" > "/tmp/$ASSET"
+          ID=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/tags/$TAG" | jq -r '.id // empty')
+          if [ -z "$ID" ]; then echo "Could not resolve release id — skipping."; exit 0; fi
+          # Replace any prior asset of the same name (re-run safe).
+          OLD=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/$ID/assets" \
+            | jq -r --arg n "$ASSET" '.[] | select(.name==$n) | .id')
+          [ -n "$OLD" ] && curl -s -X DELETE -H "Authorization: token $TOKEN" "$API/releases/$ID/assets/$OLD" >/dev/null || true
+          curl -s -X POST -H "Authorization: token $TOKEN" \
+            -F "attachment=@/tmp/$ASSET" \
+            "$API/releases/$ID/assets?name=$ASSET" -o /dev/null -w "asset upload HTTP %{http_code}\n"
+
+      # Mirror the release to the Codeberg mirror as a direct-download channel
+      # for users who don't want F-Droid. Gitea already push-mirrors branches +
+      # tags to Codeberg, but releases aren't git objects so they don't sync —
+      # we create the release there over the API and attach the signed APK plus
+      # a SHA-256 checksum. The APK is identical to the F-Droid one (same app
+      # key), so this adds no trust surface. Best-effort: a Codeberg outage
+      # (it 504s under load) must never fail an already-published F-Droid
+      # release. Needs the CODEBERG_RELEASE_TOKEN secret; skips cleanly if unset.
+      - name: Publish release to Codeberg
+        if: env.IS_RELEASE == 'true'
+        continue-on-error: true
+        env:
+          TOKEN: ${{ secrets.CODEBERG_RELEASE_TOKEN }}
+          API: https://codeberg.org/api/v1/repos/jlmakiola/calendula
+          SHA: ${{ github.sha }}
+        run: |
+          set -e
+          if [ -z "${TOKEN:-}" ]; then
+            echo "CODEBERG_RELEASE_TOKEN not set — skipping Codeberg publish."
+            exit 0
+          fi
+          TAG="v$VERSION"
+          APK="app/build/outputs/apk/release/app-release.apk"
+          if [ ! -f "$APK" ]; then echo "No release APK found — skipping." >&2; exit 1; fi
+          ASSET_APK="calendula_v${VERSION}.apk"
+          ASSET_SUM="${ASSET_APK}.sha256"
+          cp "$APK" "/tmp/$ASSET_APK"
+          ( cd /tmp && sha256sum "$ASSET_APK" > "$ASSET_SUM" )
+
+          # Release notes: reuse the section extracted for the Gitea release,
+          # fall back to the CHANGELOG entry if that step's file is gone.
+          if [ ! -s release-notes.md ]; then
+            awk -v ver="$VERSION" '
+              $0 ~ "^## \\[" ver "\\]" { flag = 1; next }
+              /^## \[/ { flag = 0 }
+              flag' CHANGELOG.md > release-notes.md
+            sed -i -e '/./,$!d' release-notes.md
+          fi
+          [ -s release-notes.md ] || echo "_See CHANGELOG.md for ${VERSION}._" > release-notes.md
+          # The pipeline creates the tag via the Gitea API, which the push mirror
+          # (sync_on_commit only fires on real git pushes) doesn't propagate
+          # promptly — so a release POST that carries a target_commitish can
+          # outrun the mirror and 500 on a commit/tag Codeberg hasn't received.
+          # Push the tag straight to Codeberg so it's guaranteed present, then
+          # attach the release to that existing tag with NO target_commitish
+          # (which is what triggered the 500).
+          git tag -f "$TAG" "$SHA"
+          git push -f "https://jlmakiola:${TOKEN}@codeberg.org/jlmakiola/calendula.git" \
+            "refs/tags/$TAG"
+          python3 - "$TAG" <<'PY' > cb-payload.json
+          import json, sys
+          print(json.dumps({
+              "tag_name": sys.argv[1],
+              "name": sys.argv[1],
+              "body": open("release-notes.md").read(),
+              "draft": False,
+              "prerelease": False,
+          }))
+          PY
+          # Create (or update) the release. Codeberg 500s on a POST/GET against a
+          # tag it has only just received — the release request outruns the
+          # indexing of the ref we pushed a moment ago — so a single attempt kept
+          # failing and skipping the mirror even though the very same call
+          # succeeds seconds later. Retry with backoff, and PATCH in place if a
+          # release already exists (re-run safe). A 5xx body still exits curl 0,
+          # so the loop, not `set -e`, controls the flow.
+          ID=""
+          for attempt in 1 2 3 4 5 6; do
+            EXIST=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/tags/$TAG" | jq -r '.id // empty' 2>/dev/null || true)
+            if [ -n "$EXIST" ]; then
+              curl -s -o /dev/null -w "release PATCH HTTP %{http_code}\n" -X PATCH \
+                -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+                -d @cb-payload.json "$API/releases/$EXIST"
+              ID="$EXIST"; break
+            fi
+            CODE=$(curl -s -o cb-response.json -w "%{http_code}" -X POST \
+              -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+              -d @cb-payload.json "$API/releases")
+            echo "release POST attempt $attempt HTTP $CODE"
+            ID=$(jq -r '.id // empty' cb-response.json 2>/dev/null || true)
+            [ -n "$ID" ] && break
+            sleep $((attempt * 10))
+          done
+          if [ -z "$ID" ]; then echo "Could not resolve Codeberg release id after retries." >&2; exit 1; fi
+
+          # Attach APK + checksum, replacing any prior asset of the same name.
+          for A in "$ASSET_APK" "$ASSET_SUM"; do
+            OLD=$(curl -s -H "Authorization: token $TOKEN" "$API/releases/$ID/assets" \
+              | jq -r --arg n "$A" '.[] | select(.name==$n) | .id')
+            [ -n "$OLD" ] && curl -s -X DELETE -H "Authorization: token $TOKEN" "$API/releases/$ID/assets/$OLD" >/dev/null || true
+            curl -s -X POST -H "Authorization: token $TOKEN" \
+              -F "attachment=@/tmp/$A" \
+              "$API/releases/$ID/assets?name=$A" -o /dev/null -w "asset $A HTTP %{http_code}\n"
+          done
+          echo "Published $TAG to Codeberg."
+
+      # Play takes an App Bundle, not the APK, so it is a second artifact from
+      # the same source and the same signing config — not a repackage of the
+      # APK. The release key signs it, but Play only ever treats that key as the
+      # *upload* key: Play App Signing re-signs with Google's own key before
+      # delivery. A Play install and an F-Droid install therefore carry
+      # different signatures and cannot update each other. That divergence is a
+      # deliberate, documented choice (docs/RELEASING.md), not an accident.
+      #
+      # Built LAST and `continue-on-error`, both deliberately: everything above
+      # has already shipped by this point, and nothing Play-related may put that
+      # at risk. Sitting mid-job without continue-on-error, this block took the
+      # whole 2.17.0 release down with it — no F-Droid publish, no tag, no
+      # Codeberg mirror — over an artifact upload. A failure here now costs the
+      # Play upload and nothing else.
+      #
+      # Nothing here touches the F-Droid path: the AAB is never copied into the
+      # repo, never attached to a release, and its build cannot change the APK
+      # published above.
+      #
+      # AGP embeds the R8 mapping in the bundle's BUNDLE-METADATA, so Play gets
+      # deobfuscated stacktraces without a separate mapping upload.
+      - name: Build release AAB
+        if: env.IS_RELEASE == 'true'
+        continue-on-error: true
+        run: ./gradlew bundleRelease
+
+      # NOT actions/upload-artifact@v4: it runs @actions/artifact v2, which
+      # refuses to start whenever GITHUB_SERVER_URL is not github.com — it reads
+      # any other forge as an unsupported GHES instance and fails before it ever
+      # talks to the server (go-gitea/gitea#36024). Gitea 1.25 serves the v4
+      # artifact API fine; only the client-side check is wrong. This fork is that
+      # client with the check removed. Pinned to a commit, not the v4 branch: a
+      # third-party action in the signing pipeline must not change under us.
+      - name: Hand the AAB to the Play job
+        if: env.IS_RELEASE == 'true'
+        continue-on-error: true
+        uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 # v4
+        with:
+          name: release-aab-${{ needs.detect.outputs.version }}
+          path: app/build/outputs/bundle/release/app-release.aab
+          if-no-files-found: error
+          retention-days: 14
+
+  # Google Play channel.
+  #
+  # A separate job, on purpose, running only AFTER the F-Droid publish and both
+  # forge releases have completed. Play is the one channel that can reject a
+  # perfectly good build for reasons outside the pipeline (listing rules, policy
+  # review, API outage, a track that needs manual promotion). Isolating it means
+  # such a rejection surfaces as one red job next to a release that already
+  # shipped everywhere else, instead of failing the workflow that publishes it.
+  #
+  # Not a `container:` job even though a fastlane image exists: act_runner does
+  # not provide node inside custom job containers, so JavaScript actions
+  # (checkout, download-artifact) can't run there. The Renovate job gets away
+  # with a container because its only step is a shell command. Ruby is installed
+  # the same way sshpass, jq and fdroidserver are in the job above.
+  play:
+    needs: [detect, release]
+    # workflow_dispatch is the F-Droid re-sign recovery path — it must never
+    # touch Play, so gate on a real release only.
+    if: needs.detect.outputs.is_release == 'true'
+    runs-on: docker
+    env:
+      VERSION: ${{ needs.detect.outputs.version }}
+      VERSION_CODE: ${{ needs.detect.outputs.version_code }}
+      # Where the bundle lands. `internal` by default so a release reaches
+      # testers rather than the public, and promotion to production stays a
+      # deliberate human action in the Play Console — the same posture as
+      # holding UI releases for on-device review. Override with the PLAY_TRACK
+      # repo variable once the flow is trusted.
+      PLAY_TRACK: ${{ vars.PLAY_TRACK || 'internal' }}
+      PLAY_RELEASE_STATUS: ${{ vars.PLAY_RELEASE_STATUS || 'completed' }}
+      # Set PLAY_DRY_RUN=true to validate the edit against the API and discard
+      # it instead of committing — used to rehearse the first upload.
+      PLAY_DRY_RUN: ${{ vars.PLAY_DRY_RUN || 'false' }}
+      BUNDLE_PATH: vendor/bundle
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Skip cleanly (not fatally) when Play isn't configured yet, so the rest
+      # of the release pipeline keeps working during setup — same contract as
+      # the Codeberg mirror step.
+      - name: Write the Play service-account key
+        id: key
+        env:
+          PLAY_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
+        run: |
+          set -euo pipefail
+          if [ -z "${PLAY_SERVICE_ACCOUNT_JSON:-}" ]; then
+            echo "PLAY_SERVICE_ACCOUNT_JSON not set — skipping the Play upload."
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          printf '%s' "$PLAY_SERVICE_ACCOUNT_JSON" > play-service-account.json
+          # Fail here, with a clear message, rather than inside fastlane: a
+          # mangled multi-line secret is the likeliest setup mistake.
+          python3 -c "import json,sys; d=json.load(open('play-service-account.json')); sys.exit(0 if d.get('type')=='service_account' else 1)" \
+            || { echo "PLAY_SERVICE_ACCOUNT_JSON is not a valid service-account JSON." >&2; exit 1; }
+          echo "configured=true" >> "$GITHUB_OUTPUT"
+
+      # Same GHES-detection problem as the upload side, same fix — see the
+      # handoff step in the release job.
+      - name: Download the AAB
+        if: steps.key.outputs.configured == 'true'
+        uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7 # v4
+        with:
+          name: release-aab-${{ needs.detect.outputs.version }}
+          path: dist
+
+      - name: Install Ruby
+        if: steps.key.outputs.configured == 'true'
+        run: |
+          set -euo pipefail
+          SUDO=""
+          if command -v sudo >/dev/null 2>&1; then SUDO="sudo"; fi
+          $SUDO apt-get update
+          # ruby-dev + build-essential: several of fastlane's dependencies build
+          # native extensions.
+          $SUDO apt-get install -y ruby-full ruby-dev build-essential
+          ruby -v
+
+      # Only the first release pays the full gem build; afterwards this restores.
+      - name: Cache bundled gems
+        if: steps.key.outputs.configured == 'true'
+        uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-gems-${{ hashFiles('Gemfile') }}
+          restore-keys: |
+            ${{ runner.os }}-gems-
+
+      - name: Install fastlane
+        if: steps.key.outputs.configured == 'true'
+        run: |
+          set -euo pipefail
+          gem install bundler --no-document
+          bundle config set --local path vendor/bundle
+          bundle install --jobs 4
+          bundle exec fastlane --version
+
+      - name: Upload to Play
+        if: steps.key.outputs.configured == 'true'
+        env:
+          SUPPLY_JSON_KEY: play-service-account.json
+          # supply is chatty on a TTY-less runner otherwise.
+          FASTLANE_SKIP_UPDATE_CHECK: '1'
+          FASTLANE_HIDE_CHANGELOG: '1'
+        run: |
+          set -euo pipefail
+          AAB="$GITHUB_WORKSPACE/dist/app-release.aab"
+          # Absolute, because a lane body runs from fastlane/, not the
+          # workspace root — a relative path resolves against the wrong
+          # directory there and 2.17.1 died on exactly that.
+          test -f "$AAB" || { echo "No AAB at $AAB — the artifact handoff failed." >&2; ls -la dist || true; exit 1; }
+          bundle exec fastlane deploy \
+            aab:"$AAB" \
+            track:"$PLAY_TRACK" \
+            release_status:"$PLAY_RELEASE_STATUS" \
+            dry_run:"$PLAY_DRY_RUN"
+          echo "Uploaded $VERSION (code $VERSION_CODE) to the '$PLAY_TRACK' track."
+
+      # The workspace is reused between runs on a self-hosted runner, so the
+      # credential must not outlive the job.
+      - name: Shred the service-account key
+        if: always()
+        run: shred -u play-service-account.json 2>/dev/null || rm -f play-service-account.json

.gitea/workflows/renovate.yml

@@ -0,0 +1,58 @@
+name: Renovate
+
+on:
+  # Weekly sweep. Mondays 05:00 UTC — this cron owns the cadence; the repo's
+  # renovate.json5 deliberately has no internal schedule (avoids double-gating).
+  schedule:
+    - cron: '0 5 * * 1'
+  # Manual run for an on-demand sweep from the Actions tab.
+  workflow_dispatch:
+
+# Never let two Renovate runs touch the repo at once.
+concurrency:
+  group: renovate
+  cancel-in-progress: false
+
+jobs:
+  renovate:
+    runs-on: docker
+    # Run the Renovate image *as* the job container and invoke the `renovate`
+    # binary directly. The renovatebot/github-action wrapper is a thin Node
+    # action that shells out to `docker run …` — it needs a Docker CLI + socket
+    # inside the job, which the Gitea runner's plain node container has not, so
+    # it died on "Unable to locate executable file: docker". Running the image
+    # directly drops the docker-in-docker requirement entirely.
+    # Full tag pinned; Renovate's github-actions manager keeps it bumped.
+    container:
+      image: ghcr.io/renovatebot/renovate:43.232.0
+    steps:
+      - name: Run Renovate
+        run: renovate
+        env:
+          # Renovate targets Codeberg (canonical) while still RUNNING on the
+          # Gitea runner. Moving the job to Codeberg would put a repo-write
+          # token on the contributor-facing runner, which is exactly what the
+          # .forgejo/ vs .gitea/ split exists to prevent — so the token stays
+          # where the other secrets live and only the API calls cross over.
+          #
+          # Platform is `forgejo`, not `gitea`: Codeberg runs Forgejo, and the
+          # pinned image ships a distinct forgejo platform module.
+          RENOVATE_PLATFORM: forgejo
+          RENOVATE_ENDPOINT: https://codeberg.org/api/v1
+          # Codeberg bot-account token (Gitea secret). Needs repo read/write +
+          # PR scope on jlmakiola/calendula.
+          RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
+          # Scope to this repo only — no org-wide autodiscovery.
+          RENOVATE_AUTODISCOVER: 'false'
+          RENOVATE_REPOSITORIES: '["jlmakiola/calendula"]'
+          # Commits/PRs authored as the bot, not a real maintainer. This address
+          # must be a verified email on the Codeberg bot account, otherwise the
+          # commits show up unattributed there.
+          RENOVATE_GIT_AUTHOR: 'Renovate Bot <renovate@jeanlucmakiola.de>'
+          # Read-only github.com PAT (no scopes needed). Unaffected by the forge
+          # move — nearly every dependency is *released* on GitHub, and without
+          # this,
+          # changelog/release-note lookups hit the 60/h anonymous rate limit
+          # and PRs arrive with an empty "Release Notes" section.
+          RENOVATE_GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
+          LOG_LEVEL: info

.gitignore

@@ -40,6 +40,7 @@ captures/
 # Keystore files
 *.jks
 *.keystore
+*.p12
 /key.properties
 
 # Google Services (e.g. APIs or Firebase)
@@ -49,9 +50,27 @@ google-services.json
 .DS_Store
 Thumbs.db
 
+# Editor swap/backup files
+*.swp
+*.swo
+*~
+
 # F-Droid local artifacts (the pipeline generates them in CI)
-fdroid/repo/
-fdroid/keystore.p12
+/fdroid/
 
 # KSP
 .ksp/
+
+# Google Play Developer API service-account key. Reconstructed in CI from the
+# PLAY_SERVICE_ACCOUNT_JSON secret and shredded afterwards — never committed.
+/play-service-account.json
+
+# fastlane (Play uploader only — see fastlane/Fastfile)
+/fastlane/report.xml
+/fastlane/README.md
+/vendor/bundle/
+/.bundle/
+Gemfile.lock
+
+# Claude Code
+/CLAUDE.md

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "floret-kit"]
+	path = floret-kit
+	url = https://codeberg.org/jlmakiola/floret-kit.git

.planning/PROJECT.md

@@ -2,11 +2,12 @@
 
 ## What This Is
 
-A modern Material 3 Expressive Android calendar app, read-only V1. Lives
-entirely on top of Android's `CalendarContract` — any calendar synced to the
-device (CalDAV via DAVx5, Google, local, WebCal, …) shows up automatically.
-The differentiator is visual: real Material 3 Expressive design that no
-existing FOSS calendar app delivers.
+A modern Material 3 Expressive Android calendar app. Lives entirely on top
+of Android's `CalendarContract` — any calendar synced to the device (CalDAV
+via DAVx5, Google, local, WebCal, …) shows up automatically; creating,
+editing, and deleting writes straight back, and reminders are delivered by
+the app itself (Etar model). The differentiator is visual: real Material 3
+Expressive design that no existing FOSS calendar app delivers.
 
 ## Core Value
 
@@ -15,8 +16,11 @@ re-inventing the calendar sync stack — leave that to DAVx5 and the system.
 
 ## Current Milestone
 
-**v0.1 — Foundation & CI:** Buildable Android project scaffold with theme,
-icon, i18n, Hilt, DataStore, green CI.
+Milestones 1 (read, v1.0) and 2 (write support, v1.1–v2.0.0 incl. reminder
+delivery) are **complete** — v2.0.0 shipped 2026-06-11. Everything since is
+tracked as issues and milestones on Codeberg:
+<https://codeberg.org/jlmakiola/calendula/milestones>. A milestone maps to its
+`release/vX.Y.Z` branch.
 
 ## Stack
 
@@ -24,11 +28,26 @@ Kotlin 2.3.21 (paired with KSP 2.3.9 — Kotlin 2.4.0 has no KSP release
 yet, do not upgrade until one ships). Jetpack Compose + Material 3
 Expressive 1.5.0-alpha21 (alpha is intentional — Expressive APIs only
 live in the 1.5 alpha line). Hilt 2.59.2, DataStore. Gradle Kotlin DSL
-with Version Catalog. AGP 9.1.1, Gradle 9.5.1. JVM target 17.
+with Version Catalog. AGP 9.2.1, Gradle 9.5.1. JVM target 17 (exactly — AGP
+requires it).
 
-Read-only V1, write support V2.
+The shared Material 3 Expressive kit, **floret-kit**, is a git submodule wired
+in as a Gradle composite build, so it compiles from source rather than resolving
+as a dependency.
 
-Android-only (minSdk 29, targetSdk 36). No iOS.
+## Constraints
+
+- **Platform:** Android-only, Android 10+ (minSdk 29), targetSdk 36. No iOS.
+- **Offline-first:** all data lives in `CalendarContract` — no app database, no
+  sync stack. No `INTERNET` permission; any feature needing one is an explicit
+  product decision first.
+- **Privacy:** zero telemetry, zero analytics.
+- **i18n:** German + English from day one; further languages come from community
+  translators via the self-hosted Weblate, which owns every `values-*` file.
+- **Tests + CI from day one**, JVM-first.
+- **Reproducible release builds**, so the official F-Droid repo can verify the
+  published binary against a from-source rebuild.
+- **Licence:** MIT.
 
 ## Naming
 
@@ -38,5 +57,9 @@ shows a stylized "1" on a slate squircle.
 
 ## Source
 
-Hosted on self-hosted Gitea, released through self-hosted F-Droid repo on
-Hetzner. Same infrastructure as `HouseHoldKeaper`.
+**Codeberg (`jlmakiola/calendula`) is canonical** — git, issues, PRs, tags and
+releases, plus contributor CI. The self-hosted Gitea instance is build
+infrastructure only: it holds the signing key, runs the release pipeline, and
+publishes the self-hosted F-Droid repo on Hetzner. Codeberg push-mirrors `main`
+and tags to Gitea, where a bumped `versionName` triggers the release. Also
+published to the official F-Droid repo. See `docs/RELEASING.md`.

.planning/REQUIREMENTS.md

@@ -1,49 +0,0 @@
-# Calendula — Requirements
-
-See full design spec: `docs/superpowers/specs/2026-06-08-calendar-app-design.md`
-
-## V1 Scope (Variant "B")
-
-### Validated (shipped)
-- Foundation & CI infrastructure — v0.1.0 (2026-06-08)
-
-### Active (V1)
-
-- [x] Foundation & CI infrastructure
-- [x] Data Layer over `CalendarContract`
-- [x] Permission flow (`READ_CALENDAR`)
-- [ ] Month view (S1)
-- [ ] Week view (S2)
-- [ ] Day view (S3)
-- [ ] Event Detail Sheet (S4)
-- [ ] Multi-Calendar Filter (M3)
-- [x] Today button (M2) — shipped v0.5; Jump-to-Date **cut from scope**
-- [ ] View-Switcher (M1)
-- [ ] Settings screen (M4)
-- [ ] Empty / no-permission / no-calendars states
-- [ ] German + English localization
-- [ ] Loading/Failure/Success states per screen (architectural pattern)
-
-### Out of Scope (V2+)
-
-- Event create / edit / delete (V2)
-- Home-screen widget
-- Full-text search
-- Quick-add
-- ~~Custom notifications/reminders (system already handles these)~~ —
-  **reversed:** Calendula targets sole-calendar-app users, so no other app
-  posts reminder notifications. We post them ourselves (Etar model). Planned
-  for v1.4 — see `ROADMAP.md`.
-- Tablet/foldable-specific layouts
-- iOS support (Android-only by design)
-
-## Constraints
-
-- **Tech stack:** Kotlin + Jetpack Compose + Material 3 Expressive, Hilt, DataStore
-- **Tech stack pin:** Hilt 2.59.2 + KSP 2.3.9; Kotlin 2.3.21 (KSP for Kotlin 2.4.0 not released yet). Material 3 pinned to `1.5.0-alpha21` (Expressive APIs only exist in alpha). Re-evaluate when KSP/Material3 stable land.
-- **Platform:** Android 10+ (API 29 minimum), Android 16 (API 36) target
-- **Offline-first:** all data lives in `CalendarContract`; no app-side network
-- **Privacy:** zero telemetry, no analytics
-- **i18n:** German + English from day one
-- **Tests + CI from day one**
-- **License:** MIT

.planning/ROADMAP.md

@@ -1,103 +0,0 @@
-# Calendula — Roadmap
-
-## v0.x — Pre-Release
-
-| Version | Milestone | Status |
-|---|---|---|
-| v0.1 | Foundation & CI | complete |
-| v0.2 | Data Layer & Permission Flow | complete |
-| v0.3 | Month + Week + Day views, view switcher | complete |
-| v0.4 | Event Detail (S4) + humanized recurrence | complete |
-| v0.5 | Calendar filter (M3) + Settings (M4) | complete |
-| v0.6 | Full event read — surface every readable field | complete |
-| v1.0 | First public release — polish pass, F-Droid | complete |
-
-Delivery ran ahead of the original table: Day view (S3) shipped in v0.3 and
-Event Detail (S4) in v0.4, so the Filter/Settings milestone became v0.5.
-
-Jump-to-date (the date-picker half of M2) was **cut from scope** and will not
-ship. The "Today" half of M2 already shipped in v0.5 (drawer entry).
-
-## v0.6 — Full event read
-
-Round out the read-only model so a detail view shows everything the system
-actually stores, before write support starts. Scope = `CalendarContract`
-columns we don't yet read/display:
-
-- **Reminders** (`VALARM`) — read `CalendarContract.Reminders`, list lead times
-- **Status** — Confirmed / Tentative / Cancelled (cancelled shown struck-through)
-- **Availability** (`TRANSP`) — Free / Busy chip
-- **Attendee extras** — role (required / optional / organizer) + the user's own
-  `SELF_ATTENDEE_STATUS`
-- **Timezone** (`EVENT_TIMEZONE`) — shown only when it differs from the device zone
-- **URL** — ~~tappable link card~~ **cut**: `CalendarContract` exposes no
-  `Events.URL` column (only `CUSTOM_APP_URI`, an originating-app deep-link).
-  URLs are instead surfaced by linkifying the description text
-- **Access level / class** (private / confidential) — small chip (optional, trivial)
-
-All of the above shipped in v0.6.0 (2026-06-11).
-
-Deliberately out of v0.6:
-- Recurrence exception / modified-occurrence badges — `Instances` already
-  resolves correct per-occurrence times for display; this only matters for
-  editing, so it folds into v2
-- `CATEGORIES`, `ATTACH` — not reliably exposed by `CalendarContract`
-  (provider limitation, not our choice)
-
-## v1.0 — First Public Release — shipped 2026-06-11
-
-All V1 features shipped, polished, on F-Droid. Read-only calendar. Cut directly
-after v0.6 (full event read) plus the onboarding-screen polish pass.
-
-### Polish backlog (pre-1.0)
-- ~~Redesign the initial grant-access (permission) screen~~ — **done**
-  (Material 3 Expressive onboarding, shipped in v0.6.0 / v1.0.0)
-
-## v2.0 — Write Support (in progress)
-
-Delivered in four releasable slices (plan:
-`docs/superpowers/plans/2026-06-11-03-write-support.md`). The V1 spec is a
-guide here, not a contract — scope per slice is decided as we go.
-
-| Version | Milestone | Status |
-|---|---|---|
-| v1.1 | Write foundation — `WRITE_CALENDAR`, read-only-calendar detection, delete (series + single occurrence) | complete (shipped 2026-06-11) |
-| v1.2 | Create event — form, FAB, last-used-calendar preselect | complete (shipped 2026-06-11) |
-| v1.2.1 | Form polish after on-device review — card design system, optional fields + settings defaults, OptionCard dialogs, expressive motion | complete (shipped 2026-06-11) |
-| v1.3 | Edit event — shared form, scoped recurring writes (this / following / all), recurrence picker | complete (shipped 2026-06-11) |
-| v1.4 | Reminder notifications — see below | planned |
-| v2.0 | Quick-add, occurrence edit, conflict dialog, polish, release | planned |
-
-## v1.4 — Reminder Notifications
-
-**Essential**, not nice-to-have: Calendula targets users for whom it is their
-*only* calendar app, so reminder delivery can't be delegated to Google/OEM
-Calendar. The calendar provider schedules reminders and broadcasts
-`android.intent.action.EVENT_REMINDER`, but it does **not** post the visible
-notification — a calendar app must. We become that app (the Etar model).
-
-Scope:
-- Manifest-registered `BroadcastReceiver` for `EVENT_REMINDER`
-  (data scheme `content://com.android.calendar`) — wakes us at reminder time,
-  no foreground service.
-- Read `CalendarContract.CalendarAlerts` / `Reminders`, filter to
-  `METHOD_ALERT` / `METHOD_DEFAULT` (skip `METHOD_EMAIL`); post on a dedicated
-  notification channel; tap opens event detail.
-- `POST_NOTIFICATIONS` runtime permission (API 33+) — requested in onboarding.
-- Onboarding step: (a) request `POST_NOTIFICATIONS`, (b) in-app reminders
-  toggle, **default ON**, with copy warning that a second calendar app with
-  notifications on will cause duplicate reminders. Mirrored into Settings
-  (reversible).
-
-Deliberately deferred (add only if needed):
-- Snooze / dismiss notification actions (Etar has them)
-- Battery-optimization exemption prompt for delivery reliability
-
-## v3.0 — Power-User Features
-
-- Home-screen widget
-- Full-text search
-- Tablet / foldable layouts
-- Optional: ICS file import (drag-and-drop)
-
-Order is indicative — community feedback after V1 may re-prioritize.

.planning/STATE.md

@@ -1,71 +0,0 @@
-# Calendula — Current State
-
-*Last updated: 2026-06-11*
-
-## Status
-
-**Milestone:** v2.0 — Write support (milestone 2, in progress)
-**Phase:** v1.3.0 (edit event) shipped 2026-06-11 after four on-device
-review rounds (BYDAY toggles, scoped recurring writes, scope-at-save flip,
-stale-instances split bugfix). Milestone 2 runs in four slices
-(`docs/superpowers/plans/2026-06-11-03-write-support.md`); v2.0 (quick-add,
-conflict dialog, polish) is the remaining slice, v1.4 (reminder
-notifications) comes first.
-
-## Progress
-
-- [x] Design spec written and committed (`docs/superpowers/specs/2026-06-08-calendar-app-design.md`)
-- [x] V1 design decisions resolved (App name "Calendula", icon, seed color)
-- [x] Plan 01 written and executed — foundation lands (theme, icon, i18n, Hilt, DataStore, CI green)
-- [x] Plan 02 written and executed — data layer + permission flow + debug screen
-- [x] Month view (S1) — 6-week grid, event dots, today marker, swipe nav, three states (replaces debug screen)
-- [x] Week view (S2) — time schedule with overlap-resolved lanes, all-day strip, swipe nav, three states
-- [x] Day view (S3) — single-column slice reusing the week layout
-- [x] View-switcher (M1) wired — cycles Month ↔ Week ↔ Day
-- [x] Event-detail screen (S4) — full-screen, humanized recurrence
-- [x] Filter sheet (M3) — per-calendar visibility, grouped by account, persisted, applied centrally in the repository
-- [x] Settings (M4) — appearance (theme, dynamic colour, week start), language (per-app locales), about
-- [~] Jump-to-date (M2) — **cut from scope**; "Today" half shipped in v0.5, date-picker dropped
-- [x] Full event read (v0.6) — reminders, status, availability, access level,
-  attendee role + self-response, foreign timezone, and linkified description
-  URLs in the detail view; new domain enums + mapper unit tests. (A dedicated
-  URL field was cut — no `CalendarContract` column backs it.)
-
-- [x] v1.1 write foundation — `WRITE_CALENDAR` (onboarding asks READ+WRITE,
-  only READ gates; contextual upgrade for v1.0 installs), read-only-calendar
-  detection (`CALENDAR_ACCESS_LEVEL` → `canModifyContents`, actions hidden for
-  WebCal/birthday calendars), delete from the detail screen (recurring:
-  "only this event" via cancelled exception / "all events in the series"),
-  repository + mapper tests
-
-- [x] v1.2 create event — full-screen `EventEditScreen` (title, all-day,
-  M3 date/time pickers with duration-preserving start moves, writable-only
-  calendar picker preselecting the last-used calendar, location, description),
-  "+" FAB on all three views prefilled with the visible day, `insertEvent`
-  with provider-correct all-day normalisation (UTC midnights, exclusive end),
-  domain/mapper/repository tests
-
-- [x] v1.3 edit event (shipped 2026-06-11) — `EventEditScreen` reused for
-  edit (detail-screen Edit action, `canModify`-gated, contextual WRITE
-  upgrade), dirty-checked partial `update` on the Events row (recurring:
-  series DTSTART moves by the user's delta, DURATION instead of DTEND),
-  reminder diff by minutes (kept rows keep their method), simple recurrence
-  picker (FREQ/INTERVAL/UNTIL/COUNT; complex RRULEs preserved verbatim and
-  shown humanized), `EventFormField.Recurrence` incl. settings default,
-  recurrence also available on create; domain/mapper/repository tests.
-  Review round 1: weekly BYDAY day-toggles in the custom picker ("every week
-  on Mon+Fri"). Review rounds 2–4: occurrence edit pulled forward from v2.0
-  and made three-way like delete ("this" = exception row via
-  `CONTENT_EXCEPTION_URI`, "this and following" = series split, "all" =
-  series update); delete equally three-way (truncation via RRULE UNTIL);
-  the edit-scope question moved to save time (Google model) — dirty
-  recurring saves park in `SaveUiState.AwaitingScope`, a changed rule drops
-  the "only this event" option
-
-## Next
-
-1. v1.4 — reminder notifications (essential for sole-app use): `EVENT_REMINDER`
-   receiver + notification channel, `POST_NOTIFICATIONS`, onboarding step with
-   default-on toggle + duplicate-reminder warning (Etar model)
-2. v2.0 — quick-add sheet, conflict dialog, polish pass, milestone release
-3. Monitor the F-Droid build/publish for v1.1.0 – v1.3.0

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to Calendula
+
+Calendula is a Material 3 Expressive calendar app that lives strictly on top of
+Android's `CalendarContract` — no app database, no sync stack, no network access.
+That constraint shapes most review comments, so
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) is worth skimming before you write
+code. This file is the practical how.
+
+**[Codeberg](https://codeberg.org/jlmakiola/calendula) is the canonical home** —
+issues, pull requests, releases. The self-hosted Gitea instance referenced in the
+release docs is build infrastructure only; there is nothing to contribute there.
+Be decent to the people you meet in the tracker.
+
+## Start with an issue
+
+| You want to | Do this |
+|---|---|
+| Add a feature | **Open an issue first** and wait for a go-ahead |
+| Fix a bug | Open an issue, then a pull request |
+| Fix a typo, a comment, or docs | Just open the pull request |
+| Add or fix a translation | **Don't** — [use Weblate](#translations) |
+
+Features get an opinion before they get code: whether Calendula should do a
+thing at all is the one decision a patch can't make. A feature PR that arrives
+without a discussed issue may be closed unmerged even when the code is good —
+please don't spend a weekend on one first.
+
+Bugs are more straightforward, but still start with an issue: it's what carries
+the milestone and gives the changelog something to link.
+
+Issue templates cover bug, crash, feature and question. For a crash, let the app
+do the work — **Settings → Report a problem**, or the prompt shown after a crash,
+captures the stack trace and prefills the form. The report contains app, Android
+and device versions plus the trace; no calendar content, no personal data.
+
+## Which branch to target
+
+Calendula releases by merging a version bump into `main`, so `main` is a release
+trigger rather than a staging area. Work is assembled on release branches first.
+
+Once your issue has a milestone, that milestone names your branch:
+
+| Milestone | Target branch |
+|---|---|
+| `2.18.0` | `release/v2.18.0` |
+
+Every milestone has a matching branch. If it's somehow missing, target `main` and
+mention it in the PR — it will be retargeted. Don't pick an older release branch:
+they're kept after shipping, so the newest one isn't necessarily yours.
+
+## Translations
+
+**Never edit a `values-*/strings.xml` file in a pull request** — German included.
+Translations are owned by a self-hosted Weblate that writes to this repository
+directly, and a hand-edit is overwritten on the next sync.
+
+→ **[Translate Calendula on Weblate](https://weblate.dev.jeanlucmakiola.de/engage/calendula/)**
+
+Adding a *new* English string to `values/strings.xml` is normal PR work; Weblate
+picks it up and offers it to translators. Partial translations are expected and
+fine — missing keys are informational. Stale and orphaned keys are not, so run
+
+```sh
+python3 scripts/check_translations.py
+```
+
+before pushing. It reports those more clearly than lint's `MissingTranslation`
+does.
+
+## Build & test
+
+```sh
+git clone --recurse-submodules https://codeberg.org/jlmakiola/calendula.git
+```
+
+The `floret-kit` submodule is a composite build compiled from source. An
+existing clone needs `git submodule update --init --recursive`, or nothing
+resolves.
+
+- **JDK 17** — not newer; the Android Gradle Plugin requires exactly 17. Set
+  `JAVA_HOME` if your default differs.
+- **Android SDK** — platform 37 (`compileSdk`) and build-tools 36.0.0, located
+  via `ANDROID_HOME` or a gitignored `local.properties` with `sdk.dir`. If you
+  go the `local.properties` route the included build needs its own copy at
+  `floret-kit/local.properties`; `ANDROID_HOME` covers both at once and is the
+  easier path.
+
+The Gradle wrapper is checked in, so no system Gradle is needed.
+
+```sh
+./gradlew lint test assembleDebug     # roughly what CI runs
+```
+
+A single test class, or a pattern:
+
+```sh
+./gradlew testDebugUnitTest --tests "de.jeanlucmakiola.calendula.domain.SimpleRecurrenceTest"
+./gradlew testDebugUnitTest --tests "*SimpleRecurrence*"
+```
+
+CI reports one `CI` check per pull request: `lintDebug`, `testDebugUnitTest`,
+`assembleDebug`, and a Trivy scan. Pull requests touching only docs, F-Droid
+metadata or the licence skip the Android build and go green quickly. More detail
+in [`docs/BUILDING.md`](docs/BUILDING.md).
+
+## The rules
+
+These are the ones that turn into review comments.
+
+1. **No network.** Calendula holds no `INTERNET` permission, and that's a
+   feature rather than an oversight. Anything that would need one is a product
+   decision before it's a patch — the crash reporter deliberately opens a
+   prefilled web issue instead of posting anything itself.
+2. **The provider is the only database.** No Room, no cache, no local mirror of
+   events. `CalendarContract` is the single source of truth, which is also why
+   externally synced changes work for free.
+3. **Don't patch UI state after a write.** A `ContentObserver` re-queries and
+   views recompose from fresh provider state. Hand-patching a list after saving
+   appears to work, then quietly diverges from what the provider actually stored.
+4. **`domain/` has no Android imports.** Models, validation, recurrence
+   rendering, conflict snapshots and the `.ics` codec stay pure Kotlin so they
+   remain JVM-testable.
+5. **Tests run on the JVM.** JUnit 5 + Truth + Turbine. The seams exist for you:
+   fake the data source (`FakeCalendarDataSource`), and feed mappers plain maps
+   through `ColumnReader` instead of cursors. Instrumented tests are a last
+   resort, not a default.
+6. **Read before touching the subtle pipelines.** Recurring writes (UNTIL vs
+   DURATION, exception URIs, series splits), save-conflict detection and reminder
+   delivery (post-before-mark) follow provider-driven rules that are documented
+   in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and are not guessable from
+   the code alone.
+7. **Don't break reproducible builds.** `vcsInfo`, `dependenciesInfo` and the AGP
+   metadata block are disabled on purpose so the official F-Droid repo can verify
+   our binary against a from-source rebuild.
+   `scripts/check_reproducible_release.sh` runs on every pull request, including
+   docs-only ones.
+
+## UI conventions
+
+Material 3 Expressive throughout, built from the system's own tokens and
+components — colour-scheme tokens rather than hardcoded colours, `ListItem` for
+settings rows.
+
+**Selection pickers are full-screen.** Every browse-style "choose one" surface
+uses floret-kit's `FullScreenPicker` / `OptionPicker`; one that needs a commit or
+extra action passes it through the picker's `actions` slot. The exception is the
+recurring-scope chooser (*this / this and following / all*), which stays a
+compact dialog — a two- or three-option decision reads better as a popup than as
+a nearly empty screen. `AlertDialog` is for plain confirmations only, and radio-
+or text-list dialogs aren't used at all.
+
+Shared UI machinery lives in the `floret-kit` submodule and has
+[its own contributing guide](https://codeberg.org/jlmakiola/floret-kit/src/branch/main/CONTRIBUTING.md);
+changing it means a pull request against that repository plus a submodule bump
+here.
+
+## Commits & pull requests
+
+Conventional commits, scoped to the area you touched:
+
+```
+fix(calendars): keep an event's own calendar when it is switched off
+feat(month): pull-to-expand the split view (#38)
+docs(architecture): record what the second review pass changed
+```
+
+Types in use: `feat` `fix` `docs` `refactor` `style` `chore` `ci` `build`
+`revert`. Reference the issue in the subject or the body. Keep commits small —
+small commits revert cleanly, which matters more here than a tidy history.
+
+If your change is user-visible, add an entry under `## [Unreleased]` in
+[`CHANGELOG.md`](CHANGELOG.md). Match the surrounding voice: entries describe
+what changed *for the person using the app*, and why, not what changed in the
+code. Link the issue and add its reference at the bottom of the file. It may get
+reworded when the release is cut, so don't agonise over it.
+
+Please don't commit planning or design documents. Code, tests, architecture notes
+and the changelog land; the reasoning belongs in the commit message and the
+issue.
+
+## Licence
+
+Calendula is [MIT](LICENSE). By contributing you agree your changes ship under
+the same licence.

Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# fastlane is used ONLY to upload the release bundle to Google Play
+# (see fastlane/Fastfile). It is not part of the build or the signing path, so
+# it never runs on a PR — only in release.yaml's `play` job.
+#
+# Pinned exactly; Renovate's bundler manager keeps it bumped. No Gemfile.lock is
+# committed on purpose: this resolves an uploader's transitive deps, not the
+# app's, and none of it affects the reproducible release build.
+gem "fastlane", "2.237.0"

README.md

@@ -1,43 +1,194 @@
-# Calendula
+<div align="center">
 
-A modern Material 3 Expressive calendar app for Android.
+<img src="fastlane/metadata/android/en-US/images/icon.png" width="112" alt="Calendula icon">
 
-Calendula is named after the flower of the same name, whose name comes from
-the Latin *kalendae* — the first day of the month — the same root as the
-word "calendar". Calendula reads from Android's built-in `CalendarContract`,
-so any calendar source synced to your device (CalDAV via DAVx5, Google,
-local, WebCal subscriptions, ...) is shown.
+<h1>Calendula</h1>
 
-## Features (V1)
+<p><strong>A modern Material 3 Expressive calendar for Android.</strong><br>
+Reads, writes, and reminds — on top of the system calendar, with zero network access.</p>
 
-- Month, Week, and Day views
-- Read-only event details (write support comes in V2)
-- Multi-calendar visibility toggle
-- Material You Dynamic Color (Android 12+)
-- Light/Dark theme follows system
-- German + English UI
+<p>
+<a href="https://codeberg.org/jlmakiola/calendula/actions"><img src="https://codeberg.org/jlmakiola/calendula/actions/workflows/ci.yaml/badge.svg?branch=main" alt="CI"></a>
+<img src="https://img.shields.io/badge/Android-10%2B-3DDC84?logo=android&logoColor=white" alt="Android 10+">
+<img src="https://img.shields.io/badge/Kotlin-Compose-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin + Compose">
+<img src="https://img.shields.io/badge/Material%203-Expressive-4285F4" alt="Material 3 Expressive">
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
+</p>
 
-## Building
+<p>
+<a href="https://f-droid.org/packages/de.jeanlucmakiola.calendula/"><img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" alt="Get it on F-Droid" height="56"></a>
+&nbsp;
+<a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/calendula"><img src="https://github.com/ImranR98/Obtainium/blob/main/assets/graphics/badge_obtainium.png?raw=true" alt="Get it on Obtainium" height="56"></a>
+&nbsp;
+<a href="https://ko-fi.com/jeanlucmakiola"><img src="https://storage.ko-fi.com/cdn/brandasset/v2/support_me_on_kofi_badge_beige.png" alt="Support me on Ko-fi" height="56"></a>
+</p>
 
-Requires Android SDK 36 and JDK 17. The Gradle wrapper is checked in, so no host Gradle install is needed:
+<p>
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/01-week.png" width="16%" alt="Week view">&nbsp;
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/02-month.png" width="16%" alt="Month view">&nbsp;
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/03-day.png" width="16%" alt="Day view">&nbsp;
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/04-detail.png" width="16%" alt="Event detail">&nbsp;
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/05-agenda.png" width="16%" alt="Agenda view">&nbsp;
+<img src="fastlane/metadata/android/en-US/images/phoneScreenshots/06-onboarding.png" width="16%" alt="Reminder onboarding">
+</p>
 
-```bash
-# Build debug APK
-./gradlew assembleDebug
+</div>
 
-# Run unit tests
-./gradlew test
+Calendula is named after the flower whose name — like the word *calendar* —
+comes from the Latin *kalendae*, the first day of the month. It lives
+entirely on top of Android's `CalendarContract`: any calendar synced to your
+device (CalDAV via DAVx5, Google, local, WebCal subscriptions, …) simply
+appears, and everything you create or edit syncs back the same way. No own
+database, no sync stack reinvented.
 
-# Run lint
-./gradlew lint
-```
+## ✨ Features
 
-If your default JDK is something other than 17, set `JAVA_HOME` explicitly:
+**Calendar**
 
-```bash
-JAVA_HOME=/path/to/jdk-17 ./gradlew assembleDebug
-```
+- Month, week, and day views with a one-tap view switcher
+- Full event details — attendees and their responses, reminders, recurrence
+  (humanized), availability, visibility, foreign time zones
+- Per-calendar visibility toggle, grouped by account
 
-## License
+**Editing**
+
+- Create, edit, and delete events — including recurring events with scoped
+  writes: *only this event*, *this and all following*, or *the whole series*
+- Recurrence picker with one-tap presets and custom rules (interval, weekday
+  toggles, end conditions); rules it can't express are preserved verbatim
+- Conflict-safe saves: if an event changed elsewhere while you were editing,
+  Calendula asks instead of silently overwriting
+- Read-only calendars (WebCal, birthdays) are detected and respected
+
+**Reminders**
+
+- Event reminders delivered by Calendula itself as notifications —
+  essential when it's your only calendar app, since Android delegates
+  reminder delivery to calendar apps
+- Tap a reminder to land on the event
+
+**Design & privacy**
+
+- Real Material 3 Expressive throughout — dynamic color (Android 12+),
+  expressive motion and shapes, light/dark theme
+- English and German UI plus community translations (Spanish, French, Italian,
+  Polish, and more in progress), per-app language setting — and [open to more
+  languages](#-translations)
+- **Zero telemetry, zero analytics, no internet permission** — your data
+  never leaves the device
+
+## 📦 Install
+
+Pick whichever channel you already use — they all install the same app:
+
+| Channel | Updates | Notes |
+| --- | --- | --- |
+| [Official F-Droid](#f-droid-recommended) | On F-Droid's build schedule | Recommended; no extra setup |
+| [Self-hosted F-Droid repo](#self-hosted-f-droid-repo-fastest-updates) | Minutes after a release | Fastest; needs the repo added once |
+| [Codeberg release / Obtainium](#codeberg-release--obtainium) | Per release | Plain APK download, or automated by Obtainium |
+| [Google Play](#google-play-coming-soon) | — | Coming soon |
+| [Build from source](#build-from-source) | Whenever you build | Full control |
+
+### F-Droid (recommended)
+
+Calendula is on the **official [F-Droid](https://f-droid.org) repository** —
+just search for **Calendula** in any F-Droid client, or
+[install it from f-droid.org](https://f-droid.org/packages/de.jeanlucmakiola.calendula/).
+
+F-Droid rebuilds from source on its own schedule, so a new version usually
+shows up there a few days after release.
+
+### Self-hosted F-Droid repo (fastest updates)
+
+Every release is built, signed, and published to a self-hosted F-Droid
+repository as part of the release pipeline, so it lands there first. Add it once
+and your F-Droid client handles updates from then on:
+
+1. In your F-Droid client, open *Settings → Repositories → Add* (or open the
+   link below on your phone):
+
+   ```
+   https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo?fingerprint=C2C0640402BF458FC0ED957AF0B37AA4C14022E72F89CE90B5965B458CF73425
+   ```
+
+   <sub>Repo: `https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo` ·
+   fingerprint (SHA-256):
+   `C2C0 6404 02BF 458F C0ED 957A F0B3 7AA4 C140 22E7 2F89 CE90 B596 5B45 8CF7 3425`</sub>
+
+2. Refresh, search for **Calendula**, install.
+
+### Codeberg release / Obtainium
+
+If you'd rather not use F-Droid at all, every release is also published on
+**[Codeberg](https://codeberg.org/jlmakiola/calendula/releases)** with the
+signed APK (`calendula_vX.Y.Z.apk`) and a `.sha256` checksum attached — download
+and install it directly.
+
+For automatic updates from that channel, use
+**[Obtainium](https://github.com/ImranR98/Obtainium)** — on the phone,
+**[add Calendula in one tap](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/calendula)**,
+or do it by hand: *Add App* → paste `https://codeberg.org/jlmakiola/calendula`
+→ *Add*. Either way, Obtainium tracks the releases and prompts you when a new
+one appears.
+
+### Google Play (coming soon)
+
+Calendula is on its way to Google Play as an additional channel. It isn't live
+yet — this section gets a link once it is. Play builds will be signed with
+Google's key rather than mine, so switching between Play and any other channel
+will require an uninstall.
+
+> **Testers wanted.** Play requires a round of closed testing before the app can
+> go public, and I'm still looking for testers. If you'd like to help, email
+> **[business@jeanlucmakiola.de](mailto:business@jeanlucmakiola.de)** with the
+> Google account address you want to use — that address is what I need to add you
+> to the closed test.
+
+### Build from source
+
+The build is a plain Gradle build with no proprietary dependencies — see
+**[docs/BUILDING.md](docs/BUILDING.md)** (note the `floret-kit` submodule).
+
+<sub>Official F-Droid, the self-hosted repo, and the Codeberg releases all share
+the same signing key, so you can switch freely between them without
+reinstalling.</sub>
+
+## 📚 Documentation
+
+- **[Contributing](CONTRIBUTING.md)** — how to report, propose, and patch
+- **[Building from source](docs/BUILDING.md)** — requirements and Gradle tasks
+- **[Architecture](docs/ARCHITECTURE.md)** — the layered design and key pipelines
+- **[Milestones](https://codeberg.org/jlmakiola/calendula/milestones)** — what's shipped and what's next
+
+## 🤝 Contributing
+
+Bug reports, ideas, and patches are all welcome on
+**[Codeberg](https://codeberg.org/jlmakiola/calendula/issues)**.
+
+The short version: **start with an issue.** Features get a yes-or-no before they
+get code, and both features and bugs are assigned a milestone whose
+`release/vX.Y.Z` branch your pull request then targets. Typo and docs fixes can
+skip straight to a pull request. Translations don't go through pull requests at
+all — [Weblate owns them](#-translations).
+
+Read **[CONTRIBUTING.md](CONTRIBUTING.md)** before writing code: it covers the
+workflow, the build (note the `floret-kit` submodule), and the architectural
+rules a change is reviewed against.
+
+## 🌍 Translations
+
+Calendula ships in English and German, with community translations in Arabic,
+Chinese, French, Italian, Polish, Portuguese, Russian, and Spanish at varying
+degrees of completeness — partial is fine, untranslated strings simply fall back
+to English. You're warmly invited to add or finish your language. Translations
+are managed on a self-hosted **Weblate**:
+
+**→ [Help translate Calendula](https://weblate.dev.jeanlucmakiola.de/engage/calendula/)**
+
+No coding needed — register on the Weblate server, pick (or request) a language,
+and translate the strings in your browser. You can also reach this link in the
+app from the top of **Settings → App language**.
+
+## 📜 License
 
 [MIT](LICENSE) — Jean-Luc Makiola, 2026

app/build.gradle.kts

@@ -23,8 +23,13 @@ android {
         applicationId = "de.jeanlucmakiola.calendula"
         minSdk = 29
         targetSdk = 36
-        versionCode = 11
-        versionName = "1.3.0"
+        // These committed values ARE the source of truth for a release: merging
+        // a bumped versionName into main triggers .gitea/workflows/release.yaml,
+        // which builds this version and then creates the matching vX.Y.Z tag +
+        // release itself (versionCode is pinned to MAJOR*10000 + MINOR*100 +
+        // PATCH from versionName, e.g. 2.7.2 -> 20702). See docs/RELEASING.md.
+        versionCode = 21800
+        versionName = "2.18.0"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
@@ -42,6 +47,11 @@ android {
 
     buildTypes {
         release {
+            // Keep release builds reproducible for F-Droid: don't let AGP embed
+            // build-environment git metadata (META-INF/version-control-info.textproto),
+            // whose `revision`/path content varies by build machine and is the only
+            // thing that otherwise differs from a clean from-source rebuild.
+            vcsInfo { include = false }
             isMinifyEnabled = true
             isShrinkResources = true
             proguardFiles(
@@ -56,6 +66,21 @@ android {
             applicationIdSuffix = ".debug"
             isMinifyEnabled = false
         }
+        // A locally-installable twin of `release`: same R8 shrinking + obfuscation
+        // and resource shrinking, but debug-signed and given its own applicationId
+        // suffix so it installs alongside both the production app (signed with the
+        // real key) and the debug build. Used to smoke-test a release candidate on
+        // a real device before tagging — R8-only breakage and first-run/permission
+        // states don't surface in the unminified debug build, nor on a device that
+        // already holds the permission. Never published. See docs/RELEASING.md.
+        create("releaseTest") {
+            initWith(getByName("release"))
+            applicationIdSuffix = ".releasetest"
+            signingConfig = signingConfigs.getByName("debug")
+            isMinifyEnabled = true
+            isShrinkResources = true
+            matchingFallbacks += "release"
+        }
     }
 
     compileOptions {
@@ -65,6 +90,18 @@ android {
 
     buildFeatures {
         compose = true
+        // BuildConfig.DEBUG gates the in-app debug ribbon (see DebugRibbon).
+        buildConfig = true
+    }
+
+    // Don't embed AGP's dependency-metadata block in the APK signing block. It's
+    // a Play-oriented blob, and F-Droid's reproducible-build scanner rejects any
+    // "extra signing block" — so leaving it in blocks publishing to the official
+    // repo. It lives in the signing block, not the zip entries, so disabling it
+    // doesn't change the build output (reproducibility is unaffected).
+    dependenciesInfo {
+        includeInApk = false
+        includeInBundle = false
     }
 
     packaging {
@@ -73,6 +110,18 @@ android {
         }
     }
 
+    lint {
+        // Community translations are expected to be partial — a missing string
+        // falls back to the English base at runtime — so don't fail the build on
+        // it. Likewise a translated <plurals> may not fill every CLDR quantity
+        // form its locale defines (e.g. Arabic needs "zero"); the missing form
+        // falls back to "other" at runtime, so MissingQuantity is informational
+        // too. Stale/extra keys (ExtraTranslation) stay fatal; scripts/
+        // check_translations.py guards the same invariants with clearer,
+        // translator-facing messages.
+        informational += listOf("MissingTranslation", "MissingQuantity")
+    }
+
     testOptions {
         unitTests {
             all { it.useJUnitPlatform() }
@@ -108,7 +157,19 @@ dependencies {
 
     implementation(libs.androidx.datastore.preferences)
 
+    implementation(libs.androidx.work.runtime.ktx)
+    implementation(libs.androidx.documentfile)
+
+    implementation(libs.androidx.glance.appwidget)
+    implementation(libs.androidx.glance.material3)
+
     implementation(libs.kotlinx.datetime)
+    implementation("de.jeanlucmakiola.floret:core-time")
+    implementation("de.jeanlucmakiola.floret:core-locale")
+    implementation("de.jeanlucmakiola.floret:core-crash")
+    implementation("de.jeanlucmakiola.floret:core-reminders")
+    implementation("de.jeanlucmakiola.floret:identity")
+    implementation("de.jeanlucmakiola.floret:components")
     implementation(libs.kotlinx.coroutines.core)
 
     debugImplementation(libs.androidx.ui.tooling)

app/proguard-rules.pro

@@ -4,3 +4,49 @@
 
 # Compose Compiler may keep its own; defaults are fine
 -dontwarn org.jetbrains.annotations.**
+
+# Room database implementations (pulled in transitively via
+# androidx.glance:glance-appwidget → androidx.work → androidx.room).
+# The widgets rely on Glance, whose WorkManager backend stores state in a Room
+# database. Under R8 full mode (AGP 9 default) the generated *_Impl subclasses
+# of RoomDatabase lose their usable no-arg constructor / are marked abstract,
+# so Room's reflective instantiation throws InstantiationException and the app
+# crashes at startup with "Failed to create an instance of ...WorkDatabase".
+# Keep the generated Room database implementations fully intact.
+-keep class * extends androidx.room.RoomDatabase { *; }
+-dontwarn androidx.room.paging.**
+
+# Glance runs an @Composable's `actionRunCallback<T>()` by persisting the
+# callback's fully-qualified class name into the click PendingIntent, then
+# reflectively instantiating it (Class.forName(name).newInstance()) when the tap
+# fires. Under R8 full mode (AGP 9 default) these ActionCallback classes — only
+# ever referenced reflectively — get renamed or have their no-arg constructor
+# stripped, so the lookup fails silently and the tap does nothing. In the month
+# and agenda widgets that broke every run-callback control (the prev/next/today
+# month arrows and the agenda refresh) in release builds while actionStartActivity
+# taps, which ride a PendingIntent and need no reflection, kept working. Keep
+# every ActionCallback's name and constructor intact.
+-keep class * implements androidx.glance.appwidget.action.ActionCallback { <init>(...); }
+
+# WorkManager instantiates an InputMerger reflectively (Class.newInstance) from
+# the fully-qualified class name persisted in the WorkSpec, so the class must
+# keep both its name and a no-arg constructor. Glance renders every widget
+# through a WorkManager worker (androidx.glance.session.SessionWorker) whose
+# default merger is androidx.work.OverwritingInputMerger. Under R8 full mode
+# (AGP 9 default) that unused no-arg constructor was stripped, so WorkManager
+# threw "OverwritingInputMerger has no zero argument constructor", the
+# SessionWorker never ran, and widgets were stuck on their loading layout
+# (a blank spinner) in release builds. Keep every InputMerger's name + ctor.
+-keep class * extends androidx.work.InputMerger { <init>(...); }
+
+# Glance identifies a widget by its GlanceAppWidget subclass's *canonical name*:
+# GlanceAppWidgetManager persists a providerName -> receivers map under that
+# string, and `updateAll` looks the widget's app-widget ids up through it. Under
+# R8 full mode (AGP 9 default) MonthWidget and AgendaWidget — same supertype,
+# same overrides, no distinguishing members — were horizontally merged into one
+# class, so both receivers registered under the *same* provider name and
+# `AgendaWidget().updateAll()` resolved the month widget's id too, redrawing a
+# placed month widget as the agenda one on the next data change (#89). Keeping
+# the real names also survives app updates, which would otherwise renumber the
+# obfuscated name and orphan the stored mapping.
+-keep class * extends androidx.glance.appwidget.GlanceAppWidget

app/src/androidTest/java/de/jeanlucmakiola/calendula/data/calendar/CalendarRepositorySmokeTest.kt

@@ -9,6 +9,7 @@ import androidx.test.platform.app.InstrumentationRegistry
 import androidx.test.rule.GrantPermissionRule
 import com.google.common.truth.Truth.assertThat
 import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.runBlocking
@@ -31,7 +32,12 @@ class CalendarRepositorySmokeTest {
         val store: DataStore<Preferences> = PreferenceDataStoreFactory.create(
             produceFile = { context.cacheDir.resolve("smoke_test_prefs.preferences_pb") },
         )
-        return CalendarRepositoryImpl(dataSource, CalendarPrefs(store), Dispatchers.IO)
+        return CalendarRepositoryImpl(
+            dataSource,
+            CalendarPrefs(store),
+            SettingsPrefs(store),
+            Dispatchers.IO,
+        )
     }
 
     @Test

app/src/debug/res/values/colors.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Debug-only launcher-icon background. Production is slate (#5C6B7A); the
+    debug build paints the adaptive-icon background burnt orange instead, so the
+    debug icon reads at a glance as "not the real app" on the home screen. The
+    off-white foreground mark contrasts on both. See drawable/ic_launcher_background.
+-->
+<resources>
+    <color name="ic_launcher_background">#FFB23B00</color>
+</resources>

app/src/debug/res/values/strings.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Debug-build resource overrides. Merged on top of src/main for the `debug`
+    build type only (release/releaseTest keep the production values), so the
+    debug app is unmistakable on the launcher: its own label, alongside the
+    real app thanks to the `.debug` applicationId suffix.
+-->
+<resources>
+    <string name="app_name">Calendula Debug</string>
+</resources>

app/src/main/AndroidManifest.xml

@@ -4,14 +4,64 @@
 
     <uses-permission android:name="android.permission.READ_CALENDAR" />
     <uses-permission android:name="android.permission.WRITE_CALENDAR" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!--
+      Optional and feature-gated: only the "Contact special dates" feature reads
+      contacts, and only after the user enables it and grants this at runtime
+      (never requested at startup). Everything stays offline — birthdays and
+      other contact dates are mirrored one-way into local calendars; contacts
+      are never written and nothing leaves the device (the app has no INTERNET
+      permission). See docs/design/contact-special-dates.md.
+    -->
+    <uses-permission android:name="android.permission.READ_CONTACTS" />
+    <!--
+      Lets the "Reliable delivery" setting open the direct system dialog to
+      exempt Calendula from battery optimisation (so reminder broadcasts aren't
+      delayed by Doze). Used only to launch that dialog; falls back to the
+      battery-optimisation list if the OS declines the direct intent.
+    -->
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
+    <!--
+      Re-fire a snoozed reminder at an exact time (the calendar provider won't —
+      its alert is already fired). USE_EXACT_ALARM is auto-granted to calendar
+      apps on API 33+; SCHEDULE_EXACT_ALARM covers API 31–32 (user-revocable,
+      with an inexact fallback if withheld). F-Droid-clean: no Play allowlisting.
+    -->
+    <uses-permission
+        android:name="android.permission.SCHEDULE_EXACT_ALARM"
+        android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+
+    <!--
+      A reboot clears every pending alarm, including the one holding the next
+      reminder. Now that the app schedules that alarm itself (#75) rather than
+      leaning on the provider's, it has to hear about the reboot to re-arm it —
+      otherwise reminders simply stop after a restart.
+    -->
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+    <!-- Package visibility (Android 11+): without this, getLaunchIntentForPackage
+         returns null and the calendar manager's per-account "manage" button can't
+         open the source sync app (DAVx5, ICSx5, Google Calendar, …). The LAUNCHER
+         intent makes launchable apps visible so we can launch whichever app owns a
+         calendar account's authenticator. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.MAIN" />
+            <category android:name="android.intent.category.LAUNCHER" />
+        </intent>
+    </queries>
 
     <application
         android:name=".CalendulaApp"
         android:allowBackup="true"
+        android:enableOnBackInvokedCallback="true"
         android:dataExtractionRules="@xml/data_extraction_rules"
         android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:localeConfig="@xml/locales_config"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:supportsRtl="true"
         android:theme="@style/Theme.Calendula"
@@ -19,12 +69,298 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTop"
             android:windowSoftInputMode="adjustResize">
+            <!-- The MAIN/LAUNCHER entry (the launcher icon + its label) lives on
+                 the two <activity-alias> below, so the app name can be switched at
+                 runtime (issue #44). MainActivity keeps every other filter. -->
+
+            <!-- Be selectable as the system calendar app. Android has no API for
+                 an app to make itself the default, so registering the filters
+                 launchers and the OS use is what lets the user pick Calendula
+                 from the system chooser when a date action fires (issue #9).
+                 APP_CALENDAR is the "open the calendar app" action; the VIEW
+                 filters below catch a tapped date. -->
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.APP_CALENDAR" />
+            </intent-filter>
+            <!-- A launcher/clock date tap fires ACTION_VIEW on the provider's
+                 time Uri (content://com.android.calendar/time/<epochMillis>);
+                 some surfaces use the time/epoch mime type. We open the day view
+                 on that date (MainActivity.calendarTimeDateOrNull). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data
+                    android:scheme="content"
+                    android:host="com.android.calendar"
+                    android:pathPrefix="/time" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="time/epoch" />
+            </intent-filter>
+
+            <!-- Open a .ics/.vcs file (file manager / email attachment / browser).
+                 The three MIME types cover the common labels the same calendar
+                 data arrives under: iCalendar 2.0 (text/calendar), the older
+                 vCalendar 1.0 / .vcs (text/x-vcalendar), and application/ics some
+                 mail apps emit — Android cross-products the scheme and mimeType
+                 tags, so each MIME is accepted on both schemes (matches Etar). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="content" />
+                <data android:scheme="file" />
+                <data android:mimeType="text/calendar" />
+                <data android:mimeType="text/x-vcalendar" />
+                <data android:mimeType="application/ics" />
+            </intent-filter>
+            <!-- Same .ics/.vcs data arriving mislabelled as a generic download —
+                 application/octet-stream — the way many mail clients, browsers and
+                 file managers hand off attachments. Matched by file extension, so
+                 this stays a separate filter: a pathPattern here must not narrow
+                 the MIME-typed VIEW filter above (that one has no path and must
+                 keep matching regardless of name). The import handler ignores the
+                 MIME type, so a let-through octet-stream .ics imports normally.
+                 Best-effort: pathPattern is reliable for file:// (and content://
+                 whose path carries the filename); content:// URIs that expose no
+                 name still fall back to the MIME-typed filter above. -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="content" />
+                <data android:scheme="file" />
+                <data android:host="*" />
+                <data android:mimeType="application/octet-stream" />
+                <data android:pathPattern=".*\\.ics" />
+                <data android:pathPattern=".*\\.vcs" />
+            </intent-filter>
+
+            <!-- Receive a .ics/.vcs shared from another app (same MIME set). -->
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="text/calendar" />
+                <data android:mimeType="text/x-vcalendar" />
+                <data android:mimeType="application/ics" />
+            </intent-filter>
+
+            <!-- Let another app or widget (e.g. the Todo Agenda widget) launch us
+                 to create a new event, the way the AOSP calendar accepts it:
+                 ACTION_INSERT on the events *dir* mime type, carrying the new
+                 event's fields as CalendarContract extras
+                 (MainActivity.insertFormOrNull, issue #30). ACTION_EDIT on the
+                 dir mime is AOSP's "edit a new event" — i.e. create — so it maps
+                 to the same prefilled create form. (The far more common *item*-
+                 typed INSERT — the form the Android docs' example and apps like
+                 DB Navigator use — is the item filter below, issue #74.) -->
+            <intent-filter>
+                <action android:name="android.intent.action.INSERT" />
+                <action android:name="android.intent.action.EDIT" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="vnd.android.cursor.dir/event" />
+            </intent-filter>
+
+            <!-- Create or edit an event another app/assistant/widget points at,
+                 addressed by the provider's *item* MIME type. Three actions share
+                 this filter, told apart at runtime by the intent's data:
+
+                 • ACTION_INSERT — create. This is the form the Android docs'
+                   "insert an event" example and many apps use
+                   (setType("vnd.android.cursor.item/event")), e.g. DB Navigator's
+                   "Save to calendar". The dir-typed filter above alone missed it,
+                   so Calendula never showed in the chooser — and, when it was the
+                   only calendar app, the intent resolved to nothing (issue #74).
+                 • ACTION_INSERT_OR_EDIT — the third "add to calendar" action AOSP
+                   and Google Calendar register; a create, or an edit when it
+                   carries an event id.
+                 • ACTION_EDIT — edit the existing event at
+                   content://com.android.calendar/events/<id> (an id-less EDIT is a
+                   create). Opens the occurrence in the edit form, not the
+                   read-only detail — that's the VIEW filter above.
+
+                 Create fields ride as CalendarContract extras; an edit's
+                 occurrence times ride as EXTRA_EVENT_BEGIN_TIME /
+                 EXTRA_EVENT_END_TIME when supplied (MainActivity.insertFormOrNull
+                 / editEventKeyOrNull). -->
+            <intent-filter>
+                <action android:name="android.intent.action.INSERT" />
+                <action android:name="android.intent.action.INSERT_OR_EDIT" />
+                <action android:name="android.intent.action.EDIT" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="vnd.android.cursor.item/event" />
+            </intent-filter>
+
+            <!-- Open an existing event another app/widget points at (e.g. tapping
+                 an event in the Todo Agenda widget): ACTION_VIEW on
+                 content://com.android.calendar/events/<id>, the way AOSP fires it.
+                 Matched by the provider's item MIME type, not the path — a
+                 content: VIEW intent carries the resolved type
+                 (vnd.android.cursor.item/event) and a path-only filter wouldn't
+                 match it. The occurrence's times ride as EXTRA_EVENT_BEGIN_TIME /
+                 EXTRA_EVENT_END_TIME when the launcher supplies them
+                 (MainActivity.viewEventKeyOrNull, issue #48). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:mimeType="vnd.android.cursor.item/event" />
+            </intent-filter>
+
+        </activity>
+
+        <!-- Launcher entry for MainActivity, split into two aliases so the app's
+             launcher name can be switched at runtime between "Calendula" and
+             "Calendar" (issue #44). Exactly one is enabled at a time; the app
+             flips them via PackageManager.setComponentEnabledSetting
+             (LauncherNameManager). The shortcuts meta-data lives here, not on
+             MainActivity, because static shortcuts are published by whichever
+             component owns the MAIN/LAUNCHER filter. -->
+        <activity-alias
+            android:name=".DefaultNameAlias"
+            android:enabled="true"
+            android:exported="true"
+            android:icon="@mipmap/ic_launcher"
+            android:label="@string/app_name"
+            android:roundIcon="@mipmap/ic_launcher_round"
+            android:targetActivity=".MainActivity">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
-        </activity>
+            <meta-data
+                android:name="android.app.shortcuts"
+                android:resource="@xml/shortcuts" />
+        </activity-alias>
+        <activity-alias
+            android:name=".CalendarNameAlias"
+            android:enabled="false"
+            android:exported="true"
+            android:icon="@mipmap/ic_launcher"
+            android:label="@string/app_name_calendar_alias"
+            android:roundIcon="@mipmap/ic_launcher_round"
+            android:targetActivity=".MainActivity">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+            <meta-data
+                android:name="android.app.shortcuts"
+                android:resource="@xml/shortcuts" />
+        </activity-alias>
+
+        <!-- Standalone surface for a captured crash report. MainActivity routes
+             here on a startup crash-loop, so it stays clear of the app's Hilt
+             graph and Compose content. Not exported: launched only by us. -->
+        <activity
+            android:name=".ui.crash.CrashReportActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:launchMode="singleTask" />
+
+        <!-- Quick Settings tile: a one-tap "New event" shortcut in the QS panel.
+             Exported with BIND_QUICK_SETTINGS_TILE so only the system QS host can
+             bind it; the action mirrors the launcher "New event" shortcut. -->
+        <service
+            android:name=".qs.NewEventTileService"
+            android:exported="true"
+            android:icon="@drawable/ic_qs_new_event"
+            android:label="@string/qs_tile_new_event_label"
+            android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
+            <intent-filter>
+                <action android:name="android.service.quicksettings.action.QS_TILE" />
+            </intent-filter>
+        </service>
+
+        <!-- Reminder delivery is the app's own (#75): it plans the alarms from
+             Instances + Reminders instead of waiting for the provider's
+             EVENT_REMINDER broadcast, which OEM-modified providers demonstrably
+             retarget or never send. This receiver takes our scan alarm plus
+             every outside event that invalidates it — boot and package-replace
+             wipe pending alarms, and a clock or timezone change moves every
+             reminder relative to the one that is armed.
+             Exported: the system broadcasts arrive from outside the app. -->
+        <receiver
+            android:name=".data.reminders.ReminderScheduleReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+                <action android:name="android.intent.action.TIME_SET" />
+                <action android:name="android.intent.action.TIMEZONE_CHANGED" />
+            </intent-filter>
+        </receiver>
+
+        <!-- Snooze / dismiss actions on a reminder notification, plus the snooze
+             re-show alarm. Not exported: only our own notification buttons and
+             AlarmManager PendingIntents target it. -->
+        <receiver
+            android:name=".data.reminders.ReminderActionReceiver"
+            android:exported="false" />
+
+        <!-- Home-screen widgets (Glance). Exported: the launcher/host binds them. -->
+        <receiver
+            android:name=".widget.agenda.AgendaWidgetReceiver"
+            android:label="@string/widget_agenda_label"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+            </intent-filter>
+            <meta-data
+                android:name="android.appwidget.provider"
+                android:resource="@xml/appwidget_info_agenda" />
+        </receiver>
+
+        <receiver
+            android:name=".widget.month.MonthWidgetReceiver"
+            android:label="@string/widget_month_label"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+            </intent-filter>
+            <meta-data
+                android:name="android.appwidget.provider"
+                android:resource="@xml/appwidget_info_month" />
+        </receiver>
+
+        <!-- Keeps both widgets fresh: the calendar provider broadcasts
+             PROVIDER_CHANGED on any data change (our writes and external sync),
+             and the system broadcasts the date/time ones at midnight / clock
+             changes so "today" highlighting rolls over. -->
+        <receiver
+            android:name=".widget.WidgetUpdateReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.PROVIDER_CHANGED" />
+                <data
+                    android:host="com.android.calendar"
+                    android:scheme="content" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.DATE_CHANGED" />
+                <action android:name="android.intent.action.TIME_SET" />
+                <action android:name="android.intent.action.TIMEZONE_CHANGED" />
+            </intent-filter>
+        </receiver>
+
+        <!-- Hands .ics files we stage in the cache to other apps via a content
+             Uri (single-event share). Authority tracks applicationId so the
+             debug suffix doesn't break getUriForFile. -->
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
 
         <!-- Persists the per-app language (M4) on API < 33, where the platform
              per-app-languages API is unavailable. On 33+ this is a no-op. -->

app/src/main/java/de/jeanlucmakiola/calendula/CalendulaApp.kt

@@ -1,11 +1,110 @@
 package de.jeanlucmakiola.calendula
 
 import android.app.Application
+import dagger.hilt.android.EntryPointAccessors
 import dagger.hilt.android.HiltAndroidApp
+import de.jeanlucmakiola.calendula.data.backup.BackupScheduler
+import de.jeanlucmakiola.calendula.data.calendar.CalendarVisibilityReconciler
+import de.jeanlucmakiola.calendula.data.backup.BackupWorker
+import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesScheduler
+import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesSyncWorker
+import de.jeanlucmakiola.calendula.data.reminders.ReminderMaintenanceScheduler
+import de.jeanlucmakiola.calendula.data.reminders.ReminderMaintenanceWorker
+import de.jeanlucmakiola.floret.crash.CrashConfig
+import de.jeanlucmakiola.floret.crash.CrashReporter
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
 
 /**
  * Application entry point. Registered as android:name=".CalendulaApp"
  * in AndroidManifest.xml. Hilt initializes its component graph here.
  */
 @HiltAndroidApp
-class CalendulaApp : Application()
+class CalendulaApp : Application() {
+
+    override fun onCreate() {
+        super.onCreate()
+        // Install first thing so startup crashes are captured too (privacy-
+        // respecting, on-device; the user submits the report by hand). The
+        // capture/loop-detection/report machinery lives in floret-kit's
+        // core-crash; only the app label + issue-tracker URLs are app-specific.
+        CrashReporter.install(
+            this,
+            CrashConfig(
+                appLabel = getString(R.string.app_name),
+                newIssueUrl = getString(R.string.report_issue_url),
+                chooseIssueUrl = getString(R.string.report_issue_choose_url),
+                issueTitle = getString(R.string.crash_report_issue_title),
+            ),
+        )
+        reconcileAutoBackup()
+        reconcileSpecialDates()
+        reconcileCalendarVisibility()
+        startReminderDelivery()
+    }
+
+    /**
+     * Bring reminder delivery up with the process (#75): a scan re-arms whatever
+     * the system dropped and posts what a missed alarm still owes, then the
+     * provider watch keeps edits re-planned. The daily worker is the backstop.
+     */
+    private fun startReminderDelivery() {
+        val deps = EntryPointAccessors.fromApplication(
+            this, ReminderMaintenanceWorker.Deps::class.java,
+        )
+        val scanner = deps.reminderScanner()
+        scanner.startWatchingProvider()
+        scanner.scanInBackground()
+        ReminderMaintenanceScheduler.apply(this)
+    }
+
+    /**
+     * Flush any calendar switch-off not yet written to `Calendars.VISIBLE`,
+     * including the set inherited from the retired app-local model (#75). A
+     * no-op in the steady state; `RootScreen` re-runs it after a later grant.
+     */
+    private fun reconcileCalendarVisibility() {
+        val deps = EntryPointAccessors.fromApplication(
+            this, CalendarVisibilityReconciler.Deps::class.java,
+        )
+        CoroutineScope(SupervisorJob() + Dispatchers.Default).launch {
+            deps.calendarVisibilityReconciler().run()
+        }
+    }
+
+    /**
+     * Bring the scheduled auto-backup work back in line with the saved settings
+     * on every launch — re-arms it after a reinstall and, crucially, cancels any
+     * orphaned work once backup has been turned off.
+     */
+    private fun reconcileAutoBackup() {
+        val deps = EntryPointAccessors.fromApplication(this, BackupWorker.Deps::class.java)
+        CoroutineScope(SupervisorJob() + Dispatchers.Default).launch {
+            val prefs = deps.settingsPrefs()
+            BackupScheduler.apply(
+                context = this@CalendulaApp,
+                enabled = prefs.autoBackupEnabled.first(),
+                intervalMinutes = prefs.autoBackupIntervalMinutes.first(),
+                hasFolder = prefs.autoBackupFolderUri.first() != null,
+            )
+        }
+    }
+
+    /**
+     * Re-arm (or cancel) the daily special-dates reconcile from the saved
+     * settings, like [reconcileAutoBackup]. The on-open refresh is RootScreen's
+     * ON_RESUME trigger, so no immediate run is needed here.
+     */
+    private fun reconcileSpecialDates() {
+        val deps = EntryPointAccessors.fromApplication(this, SpecialDatesSyncWorker.Deps::class.java)
+        CoroutineScope(SupervisorJob() + Dispatchers.Default).launch {
+            SpecialDatesScheduler.apply(
+                context = this@CalendulaApp,
+                enabled = deps.settingsPrefs().specialDatesEnabled.first(),
+            )
+        }
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/MainActivity.kt

@@ -1,26 +1,124 @@
 package de.jeanlucmakiola.calendula
 
+import android.content.Context
+import android.content.Intent
+import android.content.res.Configuration
+import android.net.Uri
 import android.os.Bundle
-import androidx.activity.ComponentActivity
+import android.provider.CalendarContract
+import androidx.activity.SystemBarStyle
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
+import androidx.appcompat.app.AppCompatActivity
 import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.core.content.IntentCompat
+import androidx.core.net.toUri
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import dagger.hilt.android.AndroidEntryPoint
 import de.jeanlucmakiola.calendula.data.prefs.ThemeMode
+import de.jeanlucmakiola.calendula.data.prefs.is24Hour
+import de.jeanlucmakiola.calendula.domain.EventForm
+import de.jeanlucmakiola.calendula.domain.buildInsertEventForm
 import de.jeanlucmakiola.calendula.ui.RootScreen
+import de.jeanlucmakiola.calendula.ui.common.LocalShowHourLines
+import de.jeanlucmakiola.calendula.ui.common.LocalTimelineZoom
+import de.jeanlucmakiola.calendula.ui.common.rememberTimelineZoom
+import de.jeanlucmakiola.calendula.ui.common.LocalSoftenColors
+import de.jeanlucmakiola.calendula.ui.common.LocalUse24HourFormat
+import de.jeanlucmakiola.calendula.ui.WidgetNavRequest
+import de.jeanlucmakiola.calendula.ui.common.CalendarView
+import de.jeanlucmakiola.calendula.ui.detail.EventDetailViewModel.Companion.NO_OCCURRENCE_TIME
+import de.jeanlucmakiola.calendula.ui.edit.ImportSource
+import de.jeanlucmakiola.floret.components.DebugRibbon
+import de.jeanlucmakiola.calendula.ui.crash.CrashReportActivity
+import de.jeanlucmakiola.calendula.domain.FontRole
 import de.jeanlucmakiola.calendula.ui.settings.SettingsViewModel
+import de.jeanlucmakiola.floret.crash.CrashReportDialog
+import de.jeanlucmakiola.floret.crash.CrashReporter
+import de.jeanlucmakiola.floret.crash.submitCrashReport
 import de.jeanlucmakiola.calendula.ui.theme.CalendulaTheme
+import de.jeanlucmakiola.calendula.ui.theme.calendulaTypography
+import de.jeanlucmakiola.calendula.ui.theme.resolveFontFamily
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Clock
+import kotlin.time.Instant
+
+/** A prefilled create form from an external launch, with the source it came from. */
+private data class InsertRequest(val form: EventForm, val source: ImportSource)
 
 @AndroidEntryPoint
-class MainActivity : ComponentActivity() {
+class MainActivity : AppCompatActivity() {
+
+    // Which of light/dark the system bars are drawn for. The styles installed
+    // in onCreate read this field live, so androidx's config-change replay
+    // picks up the in-app override instead of the night resource qualifier.
+    private var systemBarsDark = false
+
+    // The occurrence a reminder notification was tapped for (eventId, begin,
+    // end — the detail screen's key shape). singleTop + onNewIntent route a
+    // tap into the running activity; CalendarHost consumes and clears it.
+    private var requestedDetailKey by mutableStateOf<LongArray?>(null)
+
+    // A navigation a home-screen widget asked for (open a date / start a
+    // create). Consumed once by CalendarHost, same pattern as the detail key.
+    private var requestedNav by mutableStateOf<WidgetNavRequest?>(null)
+
+    // An .ics file opened/shared into the app (ACTION_VIEW/SEND). Consumed once
+    // by CalendarHost's import flow.
+    private var requestedImportUri by mutableStateOf<Uri?>(null)
+
+    // A prefilled new-event form from an external ACTION_INSERT launch (another
+    // app/widget asking us to create an event, issue #30). Consumed once by
+    // CalendarHost, which opens it in the create form for review.
+    private var requestedInsert by mutableStateOf<InsertRequest?>(null)
+
+    // An external "edit this event" (ACTION_EDIT on content://.../events/<id>):
+    // opens the occurrence in the edit form. Same occurrence-key shape as the
+    // detail channel; consumed once by CalendarHost.
+    private var requestedEditKey by mutableStateOf<LongArray?>(null)
+
+    // A captured crash report awaiting the user's decision, surfaced as a dialog
+    // over the calendar on the next launch (the single-crash path). A startup
+    // crash-loop is handled out of band, before setContent — see below.
+    private var pendingCrashReport by mutableStateOf<String?>(null)
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
-        enableEdgeToEdge()
+
+        // If the app keeps crashing as it starts, the main UI can't be trusted
+        // to come up — route to the standalone report screen instead of
+        // re-entering the crashing graph.
+        if (CrashReporter.isCrashLoop(this)) {
+            startActivity(
+                Intent(this, CrashReportActivity::class.java)
+                    .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK),
+            )
+            finish()
+            return
+        }
+
+        systemBarsDark = resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK ==
+            Configuration.UI_MODE_NIGHT_YES
+        applyEdgeToEdge()
+        requestedDetailKey = intent.detailKeyOrNull() ?: intent.viewEventKeyOrNull()
+        requestedNav = intent.navRequestOrNull()
+        requestedImportUri = intent.importUriOrNull()
+        requestedInsert = intent.insertRequestOrNull()
+        requestedEditKey = intent.editEventKeyOrNull()
+        if (CrashReporter.shouldPrompt(this)) pendingCrashReport = CrashReporter.pendingReport(this)
         setContent {
             // One activity-scoped SettingsViewModel drives both the theme here
             // and the Settings screen, so a theme change applies app-wide at once.
@@ -31,12 +129,384 @@ class MainActivity : ComponentActivity() {
                 ThemeMode.LIGHT -> false
                 ThemeMode.DARK -> true
             }
+            // onCreate can only see the night resource qualifier, not the in-app
+            // override — re-apply from the resolved theme so the bar icons follow
+            // the app's light/dark choice.
+            DisposableEffect(darkTheme) {
+                systemBarsDark = darkTheme
+                applyEdgeToEdge()
+                onDispose {}
+            }
+            // The app-wide clock convention: the time-format preference resolved
+            // against the device's 24-hour system setting, provided once here so
+            // every time label reads it via LocalUse24HourFormat.
+            val context = LocalContext.current
+            val use24Hour = remember(settings.timeFormat, context) {
+                settings.timeFormat.is24Hour(android.text.format.DateFormat.is24HourFormat(context))
+            }
+            // The user's custom-font choice, resolved to a Material typography
+            // (issue #19). Recomputed only when a token — or the custom-font
+            // re-import stamp AppFontSettings carries, so replacing the file
+            // behind an active "custom" token still refreshes — changes;
+            // "system for both" returns the default scale untouched.
+            // The timeline scale plus the pinch in flight over it (#56). Held
+            // here, above the calendar views, so a zoom survives paging between
+            // weeks and switching between the week and day view.
+            val timelineZoom = rememberTimelineZoom(
+                stored = settings.timelineScale,
+                onPersist = settingsViewModel::setTimelineScale,
+            )
+            val fonts by settingsViewModel.fontState.collectAsStateWithLifecycle()
+            val typography = remember(fonts, context) {
+                calendulaTypography(
+                    brand = resolveFontFamily(fonts.brand, FontRole.BRAND, context),
+                    plain = resolveFontFamily(fonts.plain, FontRole.PLAIN, context),
+                )
+            }
             CalendulaTheme(
                 darkTheme = darkTheme,
                 dynamicColor = settings.dynamicColor,
+                typography = typography,
             ) {
-                RootScreen(modifier = Modifier.fillMaxSize())
+                Box(modifier = Modifier.fillMaxSize()) {
+                    CompositionLocalProvider(
+                        LocalUse24HourFormat provides use24Hour,
+                        LocalShowHourLines provides settings.showHourLines,
+                        LocalTimelineZoom provides timelineZoom,
+                        LocalSoftenColors provides settings.softenColors,
+                    ) {
+                        RootScreen(
+                            modifier = Modifier.fillMaxSize(),
+                            requestedDetailKey = requestedDetailKey,
+                            onDetailKeyConsumed = { requestedDetailKey = null },
+                            widgetNavRequest = requestedNav,
+                            onWidgetNavConsumed = { requestedNav = null },
+                            requestedImportUri = requestedImportUri,
+                            onImportConsumed = { requestedImportUri = null },
+                            requestedInsertForm = requestedInsert?.form,
+                            requestedInsertSource = requestedInsert?.source ?: ImportSource.Insert,
+                            onInsertConsumed = { requestedInsert = null },
+                            requestedEditKey = requestedEditKey,
+                            onEditKeyConsumed = { requestedEditKey = null },
+                        )
                     }
+                    // A persistent corner marker so a debug build is never
+                    // mistaken for the production app; compiled out of release.
+                    if (BuildConfig.DEBUG) DebugRibbon()
+                }
+                pendingCrashReport?.let { report ->
+                    CrashReportDialog(
+                        report = report,
+                        onSend = {
+                            submitCrashReport(this@MainActivity, report)
+                            CrashReporter.clearReport(this@MainActivity)
+                            pendingCrashReport = null
+                        },
+                        onDismiss = {
+                            // Keep the report (Settings can still reach it); just
+                            // stop it popping on every launch.
+                            CrashReporter.dismissPrompt(this@MainActivity)
+                            pendingCrashReport = null
+                        },
+                    )
+                }
+            }
+        }
+    }
+
+    /**
+     * Applies the transparent edge-to-edge bars for the current [systemBarsDark].
+     * Both scrims are transparent because API 29+ enforces its own contrast and
+     * ignores them anyway.
+     */
+    private fun applyEdgeToEdge() {
+        val transparent = android.graphics.Color.TRANSPARENT
+        enableEdgeToEdge(
+            statusBarStyle = SystemBarStyle.auto(transparent, transparent) { systemBarsDark },
+            navigationBarStyle = SystemBarStyle.auto(transparent, transparent) { systemBarsDark },
+        )
+    }
+
+    override fun onResume() {
+        super.onResume()
+        // Reaching a running UI means startup succeeded; reset the loop trail.
+        CrashReporter.markHealthy(this)
+    }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        (intent.detailKeyOrNull() ?: intent.viewEventKeyOrNull())?.let { requestedDetailKey = it }
+        intent.navRequestOrNull()?.let { requestedNav = it }
+        intent.importUriOrNull()?.let { requestedImportUri = it }
+        intent.insertRequestOrNull()?.let { requestedInsert = it }
+        intent.editEventKeyOrNull()?.let { requestedEditKey = it }
+    }
+
+    /**
+     * The `.ics` Uri an external app asked us to open (file manager `ACTION_VIEW`)
+     * or share into us (`ACTION_SEND`). Restricted to content/file schemes so the
+     * app's own `calendula://` deep-links never match.
+     */
+    private fun Intent.importUriOrNull(): Uri? {
+        val uri = when (action) {
+            Intent.ACTION_VIEW -> data
+            Intent.ACTION_SEND -> IntentCompat.getParcelableExtra(this, Intent.EXTRA_STREAM, Uri::class.java)
+            else -> null
+        } ?: return null
+        // The calendar "view time" Uri (a date tap) is also ACTION_VIEW/content;
+        // it's a navigation, not a file to import, so [navRequestOrNull] owns it.
+        if (uri.host == CALENDAR_PROVIDER_HOST) return null
+        return uri.takeIf { it.scheme == "content" || it.scheme == "file" }
+    }
+
+    /**
+     * A prefilled new-event form from an external launch asking us to create an
+     * event — another app or widget (e.g. Todo Agenda) firing `ACTION_INSERT`
+     * (issue #30), or `ACTION_EDIT` with no concrete event id (AOSP's "edit a new
+     * event", i.e. create). The new event's fields ride as CalendarContract
+     * extras; anything omitted falls back to the in-app "new event" defaults in
+     * [buildInsertEventForm]. An intent that names no end time leaves the length
+     * to the default-duration setting ([ImportSource.InsertOpenEnded], #54).
+     */
+    private fun Intent.insertRequestOrNull(): InsertRequest? {
+        // ACTION_EDIT / ACTION_INSERT_OR_EDIT on an existing event route to the
+        // edit form instead ([editEventKeyOrNull]); an id-less one is a create,
+        // as is any plain ACTION_INSERT.
+        val isCreate = action == Intent.ACTION_INSERT ||
+            ((action == Intent.ACTION_EDIT || action == Intent.ACTION_INSERT_OR_EDIT) &&
+                editEventKeyOrNull() == null)
+        if (!isCreate) return null
+        val beginMillis = longExtraOrNull(CalendarContract.EXTRA_EVENT_BEGIN_TIME)
+        val endMillis = longExtraOrNull(CalendarContract.EXTRA_EVENT_END_TIME)
+        val form = buildInsertEventForm(
+            beginMillis = beginMillis,
+            endMillis = endMillis,
+            isAllDay = getBooleanExtra(CalendarContract.EXTRA_EVENT_ALL_DAY, false),
+            title = getStringExtra(CalendarContract.Events.TITLE),
+            description = getStringExtra(CalendarContract.Events.DESCRIPTION),
+            location = getStringExtra(CalendarContract.Events.EVENT_LOCATION),
+            rrule = getStringExtra(CalendarContract.Events.RRULE),
+            zone = TimeZone.currentSystemDefault(),
+            now = Clock.System.now(),
+        )
+        // An end the intent didn't name — or one [buildInsertEventForm] drops for
+        // landing before the start — leaves the length to the setting.
+        val namesEnd = beginMillis != null && endMillis != null && endMillis >= beginMillis
+        return InsertRequest(form, if (namesEnd) ImportSource.Insert else ImportSource.InsertOpenEnded)
+    }
+
+    /** A Long extra's value, or null when the extra is absent. */
+    private fun Intent.longExtraOrNull(key: String): Long? =
+        if (hasExtra(key)) getLongExtra(key, 0L) else null
+
+    /**
+     * The date a launcher/clock date tap points at, parsed from the AOSP calendar
+     * "view time" intent: ACTION_VIEW on `content://com.android.calendar/time/
+     * <epochMillis>`. Null for any other intent. The matching manifest filter is
+     * what lets users pick Calendula from the system calendar chooser (issue #9).
+     */
+    private fun Intent.calendarTimeDateOrNull(): LocalDate? {
+        if (action != Intent.ACTION_VIEW) return null
+        val uri = data ?: return null
+        if (uri.host != CALENDAR_PROVIDER_HOST) return null
+        val segments = uri.pathSegments
+        if (segments.firstOrNull() != "time") return null
+        val millis = segments.getOrNull(1)?.toLongOrNull() ?: return null
+        return Instant.fromEpochMilliseconds(millis)
+            .toLocalDateTime(TimeZone.currentSystemDefault()).date
+    }
+
+    private fun Intent.navRequestOrNull(): WidgetNavRequest? {
+        // An external date tap (launcher/clock) has no widget source, so it opens
+        // the day view rooted over the default home view (OpenDate source = null).
+        calendarTimeDateOrNull()?.let { return WidgetNavRequest.OpenDate(it.toString(), source = null) }
+        // A widget header tap: open a top-level view with no date drill-in. The
+        // empty string carried by [openViewIntent] means "the default home view".
+        if (hasExtra(EXTRA_OPEN_VIEW)) {
+            val name = getStringExtra(EXTRA_OPEN_VIEW).orEmpty()
+            return WidgetNavRequest.OpenView(CalendarView.entries.firstOrNull { it.name == name })
+        }
+        val source = sourceViewOrNull()
+        val eventId = getLongExtra(EXTRA_EVENT_ID, -1L)
+        return when {
+            // Launcher long-press "New event" shortcut. Static shortcut intents
+            // can't carry typed extras, so the action alone signals create-on-today.
+            action == ACTION_NEW_EVENT -> WidgetNavRequest.Create(null)
+            getBooleanExtra(EXTRA_CREATE, false) ->
+                WidgetNavRequest.Create(getStringExtra(EXTRA_DATE_ISO))
+            // A widget event tap carries both the occurrence and its source view;
+            // reminders (no source) fall through to [detailKeyOrNull] instead.
+            source != null && eventId != -1L -> WidgetNavRequest.OpenEvent(
+                eventId = eventId,
+                beginMillis = getLongExtra(EXTRA_BEGIN_MILLIS, 0L),
+                endMillis = getLongExtra(EXTRA_END_MILLIS, 0L),
+                source = source,
+            )
+            source != null && getStringExtra(EXTRA_DATE_ISO) != null ->
+                WidgetNavRequest.OpenDate(getStringExtra(EXTRA_DATE_ISO)!!, source)
+            else -> null
+        }
+    }
+
+    /** The view the launching widget represents, if any (see [EXTRA_SOURCE_VIEW]). */
+    private fun Intent.sourceViewOrNull(): CalendarView? =
+        getStringExtra(EXTRA_SOURCE_VIEW)
+            ?.let { name -> CalendarView.entries.firstOrNull { it.name == name } }
+
+    private fun Intent.detailKeyOrNull(): LongArray? {
+        // A widget event tap (source present) is routed through [navRequestOrNull]
+        // so it can also set the base view; only sourceless reminder taps land here.
+        if (sourceViewOrNull() != null) return null
+        val eventId = getLongExtra(EXTRA_EVENT_ID, -1L)
+        if (eventId == -1L) return null
+        return longArrayOf(
+            eventId,
+            getLongExtra(EXTRA_BEGIN_MILLIS, 0L),
+            getLongExtra(EXTRA_END_MILLIS, 0L),
+        )
+    }
+
+    /**
+     * The detail key for an external "open this event" — ACTION_VIEW on
+     * `content://com.android.calendar/events/<id>`, the way AOSP fires it (e.g.
+     * tapping an existing event in the Todo Agenda widget, issue #48). Reuses the
+     * same occurrence-key channel as reminder taps. The launcher passes the
+     * occurrence's times as `EXTRA_EVENT_BEGIN_TIME` / `EXTRA_EVENT_END_TIME` when
+     * it has them; a bare URI omits them, so we carry [NO_OCCURRENCE_TIME] and
+     * [EventDetailViewModel] falls back to the event row's own DTSTART/DTEND
+     * rather than rendering at the epoch.
+     */
+    private fun Intent.viewEventKeyOrNull(): LongArray? {
+        if (action != Intent.ACTION_VIEW) return null
+        val uri = data ?: return null
+        if (uri.host != CALENDAR_PROVIDER_HOST) return null
+        val segments = uri.pathSegments
+        if (segments.firstOrNull() != "events") return null
+        val eventId = segments.getOrNull(1)?.toLongOrNull() ?: return null
+        return longArrayOf(
+            eventId,
+            longExtraOrNull(CalendarContract.EXTRA_EVENT_BEGIN_TIME) ?: NO_OCCURRENCE_TIME,
+            longExtraOrNull(CalendarContract.EXTRA_EVENT_END_TIME) ?: NO_OCCURRENCE_TIME,
+        )
+    }
+
+    /**
+     * The occurrence key for an external "edit this event" — `ACTION_EDIT` on
+     * `content://com.android.calendar/events/<id>`, the way AOSP fires it (e.g.
+     * an assistant, task app, or widget that wants to open the event for editing
+     * rather than viewing). Opens it in the edit form. Reuses the same
+     * occurrence-key channel as reminder/view taps; the caller passes the
+     * occurrence's times as `EXTRA_EVENT_BEGIN_TIME` / `EXTRA_EVENT_END_TIME`
+     * when it has them, otherwise we carry [NO_OCCURRENCE_TIME] and
+     * [EventEditViewModel.openForEdit] falls back to the event row's own
+     * DTSTART/DTEND. An id-less `ACTION_EDIT` — or `ACTION_INSERT_OR_EDIT`, which
+     * some apps fire — is a create instead ([insertFormOrNull]).
+     */
+    private fun Intent.editEventKeyOrNull(): LongArray? {
+        if (action != Intent.ACTION_EDIT && action != Intent.ACTION_INSERT_OR_EDIT) return null
+        val uri = data ?: return null
+        if (uri.host != CALENDAR_PROVIDER_HOST) return null
+        val segments = uri.pathSegments
+        if (segments.firstOrNull() != "events") return null
+        val eventId = segments.getOrNull(1)?.toLongOrNull() ?: return null
+        return longArrayOf(
+            eventId,
+            longExtraOrNull(CalendarContract.EXTRA_EVENT_BEGIN_TIME) ?: NO_OCCURRENCE_TIME,
+            longExtraOrNull(CalendarContract.EXTRA_EVENT_END_TIME) ?: NO_OCCURRENCE_TIME,
+        )
+    }
+
+    companion object {
+        // The calendar provider's authority/host. A date tap arrives as
+        // ACTION_VIEW on content://com.android.calendar/time/<epochMillis>.
+        private const val CALENDAR_PROVIDER_HOST = "com.android.calendar"
+
+        private const val EXTRA_EVENT_ID = "de.jeanlucmakiola.calendula.extra.EVENT_ID"
+        private const val EXTRA_BEGIN_MILLIS = "de.jeanlucmakiola.calendula.extra.BEGIN"
+        private const val EXTRA_END_MILLIS = "de.jeanlucmakiola.calendula.extra.END"
+        private const val EXTRA_DATE_ISO = "de.jeanlucmakiola.calendula.extra.DATE_ISO"
+        private const val EXTRA_CREATE = "de.jeanlucmakiola.calendula.extra.CREATE"
+
+        // A widget header tap asking to open a top-level view (no date drill-in).
+        // Its value is the target [CalendarView] name, or "" for the default view.
+        private const val EXTRA_OPEN_VIEW = "de.jeanlucmakiola.calendula.extra.OPEN_VIEW"
+
+        // The [CalendarView] (by name) of the widget a launch came from. Roots the
+        // in-app back stack in that view; absent for non-widget launches (reminders).
+        private const val EXTRA_SOURCE_VIEW = "de.jeanlucmakiola.calendula.extra.SOURCE_VIEW"
+
+        // Fired by the launcher long-press "New event" shortcut (res/xml/
+        // shortcuts.xml hardcodes this string — keep the two in sync).
+        const val ACTION_NEW_EVENT = "de.jeanlucmakiola.calendula.action.NEW_EVENT"
+
+        /**
+         * Intent opening the detail screen of one occurrence (reminder
+         * notifications). The synthetic data URI keys the intent so
+         * PendingIntents for different occurrences never collapse into one.
+         */
+        fun eventDetailIntent(
+            context: Context,
+            eventId: Long,
+            beginMillis: Long,
+            endMillis: Long,
+        ): Intent = Intent(context, MainActivity::class.java).apply {
+            data = "calendula://event/$eventId/$beginMillis".toUri()
+            putExtra(EXTRA_EVENT_ID, eventId)
+            putExtra(EXTRA_BEGIN_MILLIS, beginMillis)
+            putExtra(EXTRA_END_MILLIS, endMillis)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+
+        /**
+         * Open the day view anchored on [date], drilled in over the launching
+         * widget's [source] view (home-screen widgets). Backing out of the day
+         * returns to [source], then to the default home view.
+         */
+        fun openDateIntent(context: Context, date: LocalDate, source: CalendarView): Intent =
+            Intent(context, MainActivity::class.java).apply {
+                data = "calendula://date/$date".toUri()
+                putExtra(EXTRA_DATE_ISO, date.toString())
+                putExtra(EXTRA_SOURCE_VIEW, source.name)
+                addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+            }
+
+        /**
+         * Open one occurrence's detail from a widget event tap, rooting the back
+         * stack in the widget's [source] view. Same occurrence-key shape as
+         * [eventDetailIntent]; the [source] extra is what distinguishes a widget
+         * tap (sets the base view) from a reminder tap (leaves it untouched).
+         */
+        fun openEventIntent(
+            context: Context,
+            eventId: Long,
+            beginMillis: Long,
+            endMillis: Long,
+            source: CalendarView,
+        ): Intent = eventDetailIntent(context, eventId, beginMillis, endMillis).apply {
+            putExtra(EXTRA_SOURCE_VIEW, source.name)
+        }
+
+        /** Open the create-event form prefilled for [date] (home-screen widgets). */
+        fun openCreateIntent(context: Context, date: LocalDate): Intent =
+            Intent(context, MainActivity::class.java).apply {
+                data = "calendula://create/$date".toUri()
+                putExtra(EXTRA_CREATE, true)
+                putExtra(EXTRA_DATE_ISO, date.toString())
+                addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+            }
+
+        /**
+         * Open the app on a top-level [view] with no date drill-in — a widget
+         * header tap. A null [view] opens the user's default home view (the agenda
+         * widget's "Upcoming" title); a concrete view roots there over the default
+         * home (the month widget's month/year title → [CalendarView.Month]). The
+         * per-view data URI keeps distinct headers' PendingIntents from collapsing.
+         */
+        fun openViewIntent(context: Context, view: CalendarView?): Intent =
+            Intent(context, MainActivity::class.java).apply {
+                data = "calendula://view/${view?.name ?: "default"}".toUri()
+                putExtra(EXTRA_OPEN_VIEW, view?.name ?: "")
+                addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
             }
     }
 }

app/src/main/java/de/jeanlucmakiola/calendula/data/appname/LauncherNameManager.kt

@@ -0,0 +1,109 @@
+package de.jeanlucmakiola.calendula.data.appname
+
+import android.content.ComponentName
+import android.content.Context
+import android.content.pm.PackageManager
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/** The launcher label the app shows for itself (issue #44). */
+enum class LauncherName { CALENDULA, CALENDAR }
+
+/** The two launcher aliases declared in the manifest. */
+enum class LauncherAlias { DEFAULT, CALENDAR }
+
+/** One component-enable change in a [aliasWritePlan]. */
+data class AliasStateChange(val alias: LauncherAlias, val enabled: Boolean)
+
+/**
+ * Interpret the `CalendarNameAlias` component-enabled state as a [LauncherName].
+ * Only [PackageManager.COMPONENT_ENABLED_STATE_ENABLED] means the "Calendar"
+ * name is active; `DEFAULT` (never toggled) and `DISABLED` both resolve to the
+ * manifest default, "Calendula".
+ */
+fun launcherNameFor(calendarAliasState: Int): LauncherName =
+    if (calendarAliasState == PackageManager.COMPONENT_ENABLED_STATE_ENABLED) {
+        LauncherName.CALENDAR
+    } else {
+        LauncherName.CALENDULA
+    }
+
+/**
+ * The ordered enable/disable steps to switch the launcher name to [target].
+ * Always **enables the target alias first, then disables the other** — the two
+ * `setComponentEnabledSetting` calls are not atomic, and this ordering means the
+ * only transient the launcher can observe is a harmless two-entry state, never a
+ * zero-entry one (which would briefly drop the app from the launcher).
+ */
+fun aliasWritePlan(target: LauncherName): List<AliasStateChange> = when (target) {
+    LauncherName.CALENDAR -> listOf(
+        AliasStateChange(LauncherAlias.CALENDAR, enabled = true),
+        AliasStateChange(LauncherAlias.DEFAULT, enabled = false),
+    )
+    LauncherName.CALENDULA -> listOf(
+        AliasStateChange(LauncherAlias.DEFAULT, enabled = true),
+        AliasStateChange(LauncherAlias.CALENDAR, enabled = false),
+    )
+}
+
+/**
+ * Switches the app's launcher label between "Calendula" and "Calendar" by
+ * enabling/disabling the two `<activity-alias>` components (issue #44). The
+ * component-enabled state is the single source of truth — there is no persisted
+ * preference — so [current] reads it straight from [PackageManager] and the two
+ * always agree.
+ *
+ * The decision logic lives in the pure [launcherNameFor] / [aliasWritePlan]
+ * functions above (JVM-tested); this class is only the thin framework seam.
+ */
+@Singleton
+class LauncherNameManager @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+    private val packageManager: PackageManager get() = context.packageManager
+
+    // The class portion is namespace-qualified (suffix-free), the package portion
+    // is the applicationId (which carries the .debug / .releasetest suffix). The
+    // manifest's ".CalendarNameAlias" resolves its class against the namespace, so
+    // the real component is <namespace>.CalendarNameAlias registered under the
+    // suffixed applicationId. Do NOT use ComponentName(context, ".CalendarNameAlias")
+    // — its leading-dot form prepends the applicationId to the class too, producing
+    // "<appId>.CalendarNameAlias" and failing on every debug / releaseTest build.
+    private fun component(alias: LauncherAlias): ComponentName {
+        val simpleName = when (alias) {
+            LauncherAlias.DEFAULT -> "DefaultNameAlias"
+            LauncherAlias.CALENDAR -> "CalendarNameAlias"
+        }
+        return ComponentName(context.packageName, "$NAMESPACE.$simpleName")
+    }
+
+    /** The launcher name currently in effect. */
+    fun current(): LauncherName =
+        launcherNameFor(packageManager.getComponentEnabledSetting(component(LauncherAlias.CALENDAR)))
+
+    /** Switch the launcher name to [name] (no-op cost if already active). */
+    fun set(name: LauncherName) {
+        for (change in aliasWritePlan(name)) {
+            val state = if (change.enabled) {
+                PackageManager.COMPONENT_ENABLED_STATE_ENABLED
+            } else {
+                PackageManager.COMPONENT_ENABLED_STATE_DISABLED
+            }
+            packageManager.setComponentEnabledSetting(
+                component(change.alias),
+                state,
+                PackageManager.DONT_KILL_APP,
+            )
+        }
+    }
+
+    private companion object {
+        /**
+         * The app's namespace (R-class package) — NOT `applicationId`, which
+         * carries the build-type suffix. Kept in sync with `namespace` in
+         * `app/build.gradle.kts`.
+         */
+        const val NAMESPACE = "de.jeanlucmakiola.calendula"
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/backup/AutoBackup.kt

@@ -0,0 +1,176 @@
+package de.jeanlucmakiola.calendula.data.backup
+
+import android.Manifest
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import androidx.core.net.toUri
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.ExistingWorkPolicy
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import dagger.hilt.EntryPoint
+import dagger.hilt.InstallIn
+import dagger.hilt.android.EntryPointAccessors
+import dagger.hilt.components.SingletonComponent
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository
+import de.jeanlucmakiola.calendula.data.ics.IcsExporter
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.domain.ics.IcsWriter
+import kotlinx.coroutines.flow.first
+import java.util.concurrent.TimeUnit
+import kotlin.time.Clock
+
+/**
+ * Schedules and runs the automatic periodic `.ics` backup of local calendars
+ * (issue #8). One-way export only — it mirrors the manual "Back up" into a
+ * user-chosen folder on an interval; it is not a sync. Stays INTERNET-free:
+ * everything is local provider reads + a local file write.
+ */
+object BackupScheduler {
+
+    private const val WORK_NAME = "auto-backup"
+    private const val WORK_NAME_NOW = "auto-backup-now"
+
+    /**
+     * Reconcile the scheduled work with the current settings: enqueue a unique
+     * periodic request when backup is on and a folder is set, otherwise cancel
+     * it. WorkManager persists the request across reboots on its own.
+     *
+     * The first run is delayed by one interval so it never overlaps an immediate
+     * [runNow] (two simultaneous writes would race and leave a "(1)" duplicate).
+     */
+    fun apply(context: Context, enabled: Boolean, intervalMinutes: Long, hasFolder: Boolean) {
+        val workManager = WorkManager.getInstance(context)
+        if (!enabled || !hasFolder) {
+            workManager.cancelUniqueWork(WORK_NAME)
+            // Also cancel any pending immediate run — otherwise a failing run-now
+            // keeps retrying after the user has turned backup off.
+            workManager.cancelUniqueWork(WORK_NAME_NOW)
+            return
+        }
+        // WorkManager's own floor is 15 min; the UI floors the user choice at 30.
+        val interval = intervalMinutes.coerceAtLeast(15L)
+        val request = PeriodicWorkRequestBuilder<BackupWorker>(interval, TimeUnit.MINUTES)
+            .setInitialDelay(interval, TimeUnit.MINUTES)
+            .build()
+        workManager.enqueueUniquePeriodicWork(
+            WORK_NAME,
+            ExistingPeriodicWorkPolicy.UPDATE,
+            request,
+        )
+    }
+
+    /**
+     * Run one export immediately (e.g. right after enabling or changing the
+     * folder) for instant feedback. Unique + REPLACE so rapid taps coalesce into
+     * a single run rather than racing each other.
+     */
+    fun runNow(context: Context) {
+        WorkManager.getInstance(context).enqueueUniqueWork(
+            WORK_NAME_NOW,
+            ExistingWorkPolicy.REPLACE,
+            OneTimeWorkRequestBuilder<BackupWorker>().build(),
+        )
+    }
+}
+
+/**
+ * Exports the local calendars to `calendula-backup.ics` in the configured folder,
+ * overwriting the previous file. Pulls its collaborators through a Hilt
+ * [EntryPoint] so it works under WorkManager's default (no-arg) worker factory —
+ * no custom factory / Application wiring needed. Records the outcome for the
+ * settings status line, and notifies after repeated failures.
+ */
+class BackupWorker(
+    appContext: Context,
+    params: WorkerParameters,
+) : CoroutineWorker(appContext, params) {
+
+    @EntryPoint
+    @InstallIn(SingletonComponent::class)
+    interface Deps {
+        fun settingsPrefs(): SettingsPrefs
+        fun repository(): CalendarRepository
+        fun exporter(): IcsExporter
+    }
+
+    override suspend fun doWork(): Result {
+        val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java)
+        val prefs = deps.settingsPrefs()
+        // Respect the toggle even for already-queued work: if backup was turned
+        // off, no-op (and don't retry) so a lingering run can't revive itself.
+        if (!prefs.autoBackupEnabled.first()) return Result.success()
+        val folder = prefs.autoBackupFolderUri.first()
+            ?: return Result.failure() // nothing to write to — leave scheduling to settings
+        val now = System.currentTimeMillis()
+        return try {
+            val events = deps.repository().exportEvents()
+            val content = IcsWriter().writeCalendar(events, Clock.System.now())
+            deps.exporter().writeToFolder(folder.toUri(), BACKUP_FILE_NAME, content)
+            prefs.recordAutoBackupRun(success = true, atMillis = now)
+            Result.success()
+        } catch (e: Exception) {
+            prefs.recordAutoBackupRun(success = false, atMillis = now)
+            if (prefs.autoBackupStatus.first().consecutiveFailures >= FAILURE_NOTIFY_THRESHOLD) {
+                notifyFailure(applicationContext)
+            }
+            Log.w(TAG, "Automatic backup failed", e)
+            Result.retry()
+        }
+    }
+
+    private fun notifyFailure(context: Context) {
+        val canPost = Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+            ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) ==
+            PackageManager.PERMISSION_GRANTED
+        if (!canPost) return
+        val manager = NotificationManagerCompat.from(context)
+        manager.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_ID,
+                context.getString(R.string.backup_channel_name),
+                NotificationManager.IMPORTANCE_LOW,
+            ).apply { description = context.getString(R.string.backup_channel_description) },
+        )
+        val launch = context.packageManager.getLaunchIntentForPackage(context.packageName)
+        val tap = launch?.let {
+            PendingIntent.getActivity(
+                context, 0, it,
+                PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+            )
+        }
+        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(R.drawable.ic_notification)
+            .setContentTitle(context.getString(R.string.backup_failed_title))
+            .setContentText(context.getString(R.string.backup_failed_text))
+            .setCategory(NotificationCompat.CATEGORY_ERROR)
+            .setAutoCancel(true)
+            .apply { tap?.let(::setContentIntent) }
+            .build()
+        try {
+            manager.notify(NOTIFICATION_ID, notification)
+        } catch (e: SecurityException) {
+            Log.w(TAG, "Could not post backup-failure notification", e)
+        }
+    }
+
+    companion object {
+        const val BACKUP_FILE_NAME = "calendula-backup.ics"
+        private const val FAILURE_NOTIFY_THRESHOLD = 2
+        private const val CHANNEL_ID = "backup"
+        private const val NOTIFICATION_ID = 2
+        private const val TAG = "BackupWorker"
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/AllDayReminderEncoding.kt

@@ -0,0 +1,84 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+import de.jeanlucmakiola.calendula.domain.reminders.allDayLeadDays
+import java.time.LocalDate
+import java.time.LocalTime
+import java.time.ZoneId
+import java.time.ZoneOffset
+
+/**
+ * Translates an all-day reminder between the **semantic** lead time the UI
+ * speaks (whole days before the event — "1 day before") and the **raw**
+ * `CalendarContract.Reminders.MINUTES` offset the provider stores.
+ *
+ * Calendula schedules no alarms itself: the provider fires a reminder at
+ * `DTSTART − MINUTES` (the Etar model). An all-day event's DTSTART is **UTC
+ * midnight** (see [EventWriteTimes]), so a raw `MINUTES = 1440` ("1 day") lands
+ * on UTC-midnight of the previous day — 02:00 local in CEST, not the morning.
+ *
+ * To fire at a chosen wall-clock time we encode that time *into* the offset:
+ * `MINUTES = UTC-midnight(startDate) − (localInstant of [timeOfDayMinutes] on the
+ * day [semanticMinutes] before)`. The single fixed offset can only be tuned for
+ * the event's own date, so a recurring all-day series or a post-creation
+ * timezone change drifts the fire time by the offset delta (±1h across DST) —
+ * an inherent limit of the provider model, shared by Etar.
+ */
+private const val MINUTES_PER_DAY = 1_440
+private const val MILLIS_PER_MINUTE = 60_000L
+
+/**
+ * Raw provider `MINUTES` for an all-day reminder set [semanticMinutes] before the
+ * event (a whole-day multiple; sub-day remainders are dropped), so it fires at
+ * [timeOfDayMinutes] (minutes from local midnight) in [zone]. The result may be
+ * **negative** — e.g. "at time of event" at 09:00 CEST encodes to −420, meaning
+ * the provider fires *after* DTSTART; this is valid and must not be clamped.
+ * A negative [semanticMinutes] is the "provider default" sentinel and passes
+ * through unchanged.
+ */
+internal fun toProviderAllDayMinutes(
+    semanticMinutes: Int,
+    startDate: LocalDate,
+    zone: ZoneId,
+    timeOfDayMinutes: Int,
+): Int {
+    if (semanticMinutes < 0) return semanticMinutes
+    val utcMidnight = startDate.atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli()
+    val fire = startDate.minusDays((semanticMinutes / MINUTES_PER_DAY).toLong())
+        .atTime(LocalTime.of(timeOfDayMinutes / 60, timeOfDayMinutes % 60))
+        .atZone(zone).toInstant().toEpochMilli()
+    return ((utcMidnight - fire) / MILLIS_PER_MINUTE).toInt()
+}
+
+/**
+ * The next date on or after [today] carrying [month]/[day] — the date to sample
+ * a yearly all-day reminder's UTC offset at. A managed birthday's DTSTART is an
+ * ancient anchor (1972 for year-less dates), a year whose timezone rules
+ * (pre-DST offsets) differ from today's; sampling the offset there skews every
+ * modern occurrence by hours. Sampling at the upcoming occurrence makes the
+ * stored offset correct for it and its neighbours (only ±1h DST drift remains,
+ * the inherent limit). Feb-29 skips forward to the next leap year.
+ */
+internal fun nextYearlyOccurrence(month: Int, day: Int, today: LocalDate): LocalDate {
+    var year = today.year
+    // A Feb-29 date is valid only every ~4 years; 8 tries always reaches one.
+    repeat(8) {
+        val candidate = runCatching { LocalDate.of(year, month, day) }.getOrNull()
+        if (candidate != null && !candidate.isBefore(today)) return candidate
+        year++
+    }
+    // Unreachable for real month/day inputs; fall back to the raw anchor.
+    return LocalDate.of(today.year, month, day)
+}
+
+/**
+ * Recover the semantic whole-day lead time from a raw all-day reminder
+ * [rawMinutes] — the inverse of [toProviderAllDayMinutes], for the form and the
+ * detail screen. Delegates to [allDayLeadDays], so the day displayed is the day
+ * the reminder actually fires on.
+ */
+internal fun fromProviderAllDayMinutes(
+    rawMinutes: Int,
+    startDate: LocalDate,
+    zone: ZoneId,
+    timeOfDayMinutes: Int,
+): Int = allDayLeadDays(rawMinutes, startDate, zone, timeOfDayMinutes).toInt() * MINUTES_PER_DAY

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/CalendarColorPalette.kt

@@ -0,0 +1,22 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+/**
+ * Google-Calendar-style palette; ARGB ints for a raw `CALENDAR_COLOR` /
+ * `EVENT_COLOR`. The named entries exist for callers that need one specific
+ * hue (the managed special-dates calendars), so they can't drift from the
+ * swatches offered in the colour picker.
+ */
+object CalendarColorPalette {
+    val Red = 0xFFD50000.toInt()
+    val Orange = 0xFFE67C00.toInt()
+    val Amber = 0xFFF6BF26.toInt()
+    val Green = 0xFF33B679.toInt()
+    val DarkGreen = 0xFF0B8043.toInt()
+    val Blue = 0xFF039BE5.toInt()
+    val Indigo = 0xFF3F51B5.toInt()
+    val Purple = 0xFF8E24AA.toInt()
+    val Graphite = 0xFF616161.toInt()
+
+    /** The full palette, in swatch-row order. */
+    val all: List<Int> = listOf(Red, Orange, Amber, Green, DarkGreen, Blue, Indigo, Purple, Graphite)
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/CalendarMapper.kt

@@ -3,14 +3,36 @@ package de.jeanlucmakiola.calendula.data.calendar
 import android.provider.CalendarContract
 import de.jeanlucmakiola.calendula.domain.CalendarSource
 
-internal fun ColumnReader.toCalendarSource(): CalendarSource = CalendarSource(
+internal fun ColumnReader.toCalendarSource(): CalendarSource {
+    val accountType = getString(CalendarProjection.IDX_ACCOUNT_TYPE).orEmpty()
+    val isLocal = accountType == CalendarContract.ACCOUNT_TYPE_LOCAL
+    return CalendarSource(
         id = getLong(CalendarProjection.IDX_ID),
         displayName = getString(CalendarProjection.IDX_DISPLAY_NAME)
             ?: Fallbacks.UNNAMED_CALENDAR,
         accountName = getString(CalendarProjection.IDX_ACCOUNT_NAME).orEmpty(),
-    accountType = getString(CalendarProjection.IDX_ACCOUNT_TYPE).orEmpty(),
+        accountType = accountType,
         color = getInt(CalendarProjection.IDX_COLOR),
         isVisibleInSystem = getInt(CalendarProjection.IDX_VISIBLE) != 0,
         canModifyContents = getInt(CalendarProjection.IDX_ACCESS_LEVEL) >=
             CalendarContract.Calendars.CAL_ACCESS_CONTRIBUTOR,
-)
+        isLocal = isLocal,
+        // CAL_SYNC1 holds the sync token for synced rows, so only treat it as a
+        // user description on the local calendars the app owns.
+        description = if (isLocal) {
+            getString(CalendarProjection.IDX_DESCRIPTION)?.takeIf { it.isNotBlank() }
+        } else {
+            null
+        },
+        // A special-dates mirror calendar, recognised by its durable CAL_SYNC2
+        // marker (only meaningful on the local calendars the app owns). This is
+        // the source of truth for the editor lock — independent of any stored
+        // preference that a backup restore could have wiped.
+        isManaged = isLocal &&
+            getString(CalendarProjection.IDX_MANAGED_MARKER)
+                ?.startsWith(CalendarProjection.MANAGED_MARKER_PREFIX) == true,
+        // NULL is treated as syncing — the harmless default.
+        syncsEvents = isNull(CalendarProjection.IDX_SYNC_EVENTS) ||
+            getInt(CalendarProjection.IDX_SYNC_EVENTS) != 0,
+    )
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/CalendarRepository.kt

@@ -1,9 +1,13 @@
 package de.jeanlucmakiola.calendula.data.calendar
 
 import de.jeanlucmakiola.calendula.domain.CalendarSource
+import de.jeanlucmakiola.calendula.domain.EventColorOption
 import de.jeanlucmakiola.calendula.domain.EventDetail
 import de.jeanlucmakiola.calendula.domain.EventForm
 import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.ics.IcsEvent
+import de.jeanlucmakiola.calendula.domain.ics.IcsImportSummary
+import de.jeanlucmakiola.calendula.domain.ics.ParsedIcsEvent
 import kotlinx.coroutines.flow.Flow
 import kotlin.time.Instant
 
@@ -12,6 +16,52 @@ interface CalendarRepository {
     fun instances(range: ClosedRange<Instant>): Flow<List<EventInstance>>
     suspend fun eventDetail(eventId: Long): EventDetail
 
+    /**
+     * Events whose title, description or location contains [query], with hidden
+     * calendars removed and newest first. Empty when [query] is blank. Searches
+     * the whole history/future (see [CalendarDataSource.searchEvents]).
+     */
+    suspend fun searchEvents(query: String): List<EventInstance>
+
+    /**
+     * The event-colour palette a calendar's account publishes; empty when it
+     * exposes none (see [CalendarDataSource.eventColorPalette]).
+     */
+    suspend fun eventColorPalette(calendarId: Long): List<EventColorOption>
+
+    /** Create a device-only (LOCAL) calendar the app owns; returns its id. */
+    suspend fun createLocalCalendar(displayName: String, color: Int, description: String?): Long
+
+    /** Update name, color and description of a local calendar the app owns. */
+    suspend fun updateCalendar(id: Long, displayName: String, color: Int, description: String?)
+
+    /** Permanently delete a local calendar the app owns, with all its events. */
+    suspend fun deleteCalendar(id: Long)
+
+    /**
+     * Show or hide [ids] device-wide (`Calendars.VISIBLE`), which also gates
+     * their reminders — see [CalendarDataSource.setCalendarVisible]. Written one
+     * at a time, in order; a failure part-way leaves the earlier writes standing.
+     *
+     * Without `WRITE_CALENDAR` the choice is kept app-side instead (see
+     * [de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs.pendingDisabledCalendarIds]).
+     */
+    suspend fun setCalendarsVisible(ids: Collection<Long>, visible: Boolean)
+
+    /**
+     * Every event of the writable local calendars, ready to serialise into a
+     * whole-calendar `.ics` backup (see [CalendarDataSource.exportableEvents]).
+     * [calendarIds] narrows the export to a chosen subset; `null` exports all.
+     */
+    suspend fun exportEvents(calendarIds: Set<Long>? = null): List<IcsEvent>
+
+    /**
+     * Bulk-import parsed `.ics` [events] into [targetCalendarId]. Events whose
+     * UID already exists in the target are skipped (idempotent restore); the
+     * rest are inserted. See [CalendarDataSource.insertImportedEvent].
+     */
+    suspend fun importEvents(targetCalendarId: Long, events: List<ParsedIcsEvent>): IcsImportSummary
+
     /** Create a new event from a validated form; returns the new `Events._ID`. */
     suspend fun createEvent(form: EventForm): Long
 
@@ -21,6 +71,20 @@ interface CalendarRepository {
      */
     suspend fun updateEvent(eventId: Long, original: EventForm, updated: EventForm)
 
+    /**
+     * Move an event (recurring: the whole series, with its exceptions) to
+     * [targetCalendarId] and apply the [original]→[updated] field edits; returns
+     * the new event's `Events._ID`. Copy+delete under the hood
+     * (see [CalendarDataSource.moveEvent]) — `CALENDAR_ID` can't be updated in
+     * place.
+     */
+    suspend fun moveEvent(
+        eventId: Long,
+        targetCalendarId: Long,
+        original: EventForm,
+        updated: EventForm,
+    ): Long
+
     /**
      * Change a single occurrence of a recurring event (exception row with the
      * form's values); returns the exception's `Events._ID`.

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/CalendarRepositoryImpl.kt

@@ -1,19 +1,32 @@
 package de.jeanlucmakiola.calendula.data.calendar
 
+import de.jeanlucmakiola.floret.time.toEpochMillis
 import de.jeanlucmakiola.calendula.data.di.IoDispatcher
 import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
 import de.jeanlucmakiola.calendula.domain.CalendarSource
+import de.jeanlucmakiola.calendula.domain.EventColorOption
 import de.jeanlucmakiola.calendula.domain.EventDetail
 import de.jeanlucmakiola.calendula.domain.EventForm
 import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.ics.IcsImportSummary
+import de.jeanlucmakiola.calendula.domain.ics.ParsedIcsEvent
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.drop
+import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.flowOn
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.merge
 import kotlinx.coroutines.flow.onStart
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
+import java.util.concurrent.atomic.AtomicLong
 import kotlin.time.Instant
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -27,51 +40,199 @@ import javax.inject.Singleton
 class CalendarRepositoryImpl @Inject constructor(
     private val dataSource: CalendarDataSource,
     private val prefs: CalendarPrefs,
+    private val settingsPrefs: SettingsPrefs,
     @IoDispatcher private val io: CoroutineDispatcher,
 ) : CalendarRepository {
 
+    /** The configured wall-clock fire time for all-day reminders, read per write. */
+    private suspend fun allDayReminderTimeMinutes(): Int =
+        settingsPrefs.allDayReminderTimeMinutes.first()
+
     private val ticks = MutableSharedFlow<Unit>(
         replay = 0,
         extraBufferCapacity = 1,
     )
 
+    /**
+     * Bumped on every provider notification, so one tick's calendar read can be
+     * shared by everything that needs it (see [calendarsSnapshot]).
+     */
+    private val generation = AtomicLong(0L)
+
     init {
-        dataSource.registerChangeListener { ticks.tryEmit(Unit) }
+        dataSource.registerChangeListener {
+            generation.incrementAndGet()
+            ticks.tryEmit(Unit)
+        }
     }
 
+    /**
+     * Re-query signal for everything filtered by visibility: the provider's own
+     * notifications, plus every change to the pending switch-off set.
+     */
+    private fun visibilityTicks(): Flow<Unit> = merge(
+        ticks.onStart { emit(Unit) },
+        // drop(1): the current value is already covered by the tick above.
+        prefs.pendingDisabledCalendarIds.drop(1).map {},
+    )
+
+    // A switch-off not yet written to the provider is folded into the flag
+    // itself, so every consumer reads one visibility (#75). The reconciler goes
+    // to the data source directly — it needs the provider's own answer.
     override fun calendars(): Flow<List<CalendarSource>> =
-        ticks
-            .onStart { emit(Unit) }
-            .reQuery { dataSource.calendars() }
+        visibilityTicks().reQuery {
+            val calendars = calendarsSnapshot()
+            val pendingDisabled = prefs.pendingDisabledCalendarIds.first()
+            if (pendingDisabled.isEmpty()) calendars
+            else calendars.map {
+                if (it.id in pendingDisabled) it.copy(isVisibleInSystem = false) else it
+            }
+        }
+            .distinctUntilChanged()
             .flowOn(io)
 
-    // Instances are filtered by the app-side hidden-calendar set (M3): an event
-    // is dropped whenever the user has hidden its calendar. Re-runs when the
-    // provider ticks *or* the hidden set changes — toggling a calendar in the
-    // filter sheet updates every view immediately. [calendars] stays unfiltered
-    // so the filter sheet can list and re-enable hidden calendars.
+    // Instances are filtered by the system's VISIBLE flag ∪ the switch-offs
+    // still waiting to be written to it ∪ the app-side hidden set from the
+    // filter sheet. [calendars] stays unfiltered so those screens can list and
+    // re-enable invisible calendars.
     override fun instances(range: ClosedRange<Instant>): Flow<List<EventInstance>> =
         combine(
-            ticks
-                .onStart { emit(Unit) }
-                .reQuery {
-                    dataSource.instances(
+            visibilityTicks().reQuery {
+                // All three reads in one pass, so a list of instances is never
+                // filtered against a visibility snapshot from another tick.
+                QueriedInstances(
+                    instances = dataSource.instances(
                         beginMillis = range.start.toEpochMillis(),
                         endMillis = range.endInclusive.toEpochMillis(),
+                    ),
+                    switchedOffCalendarIds = invisibleCalendarIds() +
+                        prefs.pendingDisabledCalendarIds.first(),
                 )
             },
             prefs.hiddenCalendarIds,
-        ) { instances, hidden ->
-            if (hidden.isEmpty()) instances
-            else instances.filterNot { it.calendarId in hidden }
-        }.flowOn(io)
+        ) { queried, hidden ->
+            val excluded = hidden + queried.switchedOffCalendarIds
+            if (excluded.isEmpty()) queried.instances
+            else queried.instances.filterNot { it.calendarId in excluded }
+        }
+            // Any DataStore edit re-emits the hidden set even when unchanged;
+            // collapse those so views don't re-render for them.
+            .distinctUntilChanged()
+            .flowOn(io)
+
+    /** One instances query plus the visibility it must be filtered against. */
+    private data class QueriedInstances(
+        val instances: List<EventInstance>,
+        val switchedOffCalendarIds: Set<Long>,
+    )
+
+    /** Calendars switched off at system level — hidden, and never reminded about. */
+    private suspend fun invisibleCalendarIds(): Set<Long> = calendarsSnapshot()
+        .filterNot { it.isVisibleInSystem }
+        .mapTo(mutableSetOf()) { it.id }
+
+    private val calendarsLock = Mutex()
+    private var cachedGeneration = -1L
+    private var cachedPending: Set<Long>? = null
+    private var cachedCalendars: List<CalendarSource> = emptyList()
+
+    /**
+     * The calendar list for the current tick, queried once and shared, so every
+     * open view doesn't pay for its own `Calendars` query and all of them see
+     * one snapshot.
+     *
+     * An empty result is never cached — that is what a read without the calendar
+     * permission returns, and the grant itself doesn't notify the provider. The
+     * pending switch-off set keys the cache alongside the tick, because an id
+     * leaves it before the invalidating observer is dispatched.
+     */
+    private suspend fun calendarsSnapshot(): List<CalendarSource> = calendarsLock.withLock {
+        val current = generation.get()
+        val pending = prefs.pendingDisabledCalendarIds.first()
+        if (current != cachedGeneration || pending != cachedPending || cachedCalendars.isEmpty()) {
+            cachedCalendars = dataSource.calendars()
+            cachedGeneration = current
+            cachedPending = pending
+        }
+        cachedCalendars
+    }
 
     override suspend fun eventDetail(eventId: Long): EventDetail = withContext(io) {
-        dataSource.eventDetail(eventId) ?: throw NoSuchEventException(eventId)
+        dataSource.eventDetail(eventId, allDayReminderTimeMinutes())
+            ?: throw NoSuchEventException(eventId)
+    }
+
+    override suspend fun searchEvents(query: String): List<EventInstance> = withContext(io) {
+        if (query.isBlank()) return@withContext emptyList()
+        val excluded = prefs.hiddenCalendarIds.first() +
+            prefs.pendingDisabledCalendarIds.first() +
+            invisibleCalendarIds()
+        dataSource.searchEvents(query)
+            .let { if (excluded.isEmpty()) it else it.filterNot { e -> e.calendarId in excluded } }
+    }
+
+    override suspend fun eventColorPalette(calendarId: Long): List<EventColorOption> =
+        withContext(io) { dataSource.eventColorPalette(calendarId) }
+
+    override suspend fun createLocalCalendar(
+        displayName: String,
+        color: Int,
+        description: String?,
+    ): Long = withContext(io) {
+        dataSource.createLocalCalendar(displayName, color, description)
+    }
+
+    override suspend fun updateCalendar(
+        id: Long,
+        displayName: String,
+        color: Int,
+        description: String?,
+    ) = withContext(io) { dataSource.updateCalendar(id, displayName, color, description) }
+
+    override suspend fun deleteCalendar(id: Long) =
+        withContext(io) { dataSource.deleteCalendar(id) }
+
+    override suspend fun setCalendarsVisible(ids: Collection<Long>, visible: Boolean) =
+        withContext(io) {
+            if (dataSource.canWriteCalendars()) {
+                ids.forEach { dataSource.setCalendarVisible(it, visible) }
+                // Nothing of ours is left waiting for the provider once the
+                // write lands (and switching one back on retires its entry).
+                prefs.removePendingDisabledCalendarIds(ids)
+            } else if (visible) {
+                prefs.removePendingDisabledCalendarIds(ids)
+            } else {
+                // Read-only permission: the switch still works, app-side, and
+                // the reconciler flushes it if WRITE_CALENDAR ever arrives.
+                prefs.addPendingDisabledCalendarIds(ids)
+            }
+        }
+
+    override suspend fun exportEvents(calendarIds: Set<Long>?) =
+        withContext(io) { dataSource.exportableEvents(calendarIds) }
+
+    override suspend fun importEvents(
+        targetCalendarId: Long,
+        events: List<ParsedIcsEvent>,
+    ): IcsImportSummary = withContext(io) {
+        val existing = dataSource.existingUids(targetCalendarId)
+        var imported = 0
+        var skipped = 0
+        for (event in events) {
+            // A known UID means the event is already in this calendar — skip,
+            // keeping a restore idempotent (no overwrite this pass).
+            if (event.uid != null && event.uid in existing) {
+                skipped++
+            } else {
+                dataSource.insertImportedEvent(event, targetCalendarId)
+                imported++
+            }
+        }
+        IcsImportSummary(imported = imported, skippedDuplicate = skipped)
     }
 
     override suspend fun createEvent(form: EventForm): Long = withContext(io) {
-        dataSource.insertEvent(form)
+        dataSource.insertEvent(form, allDayReminderTimeMinutes())
     }
 
     override suspend fun updateEvent(
@@ -79,19 +240,30 @@ class CalendarRepositoryImpl @Inject constructor(
         original: EventForm,
         updated: EventForm,
     ) = withContext(io) {
-        dataSource.updateEvent(eventId, original, updated)
+        dataSource.updateEvent(eventId, original, updated, allDayReminderTimeMinutes())
     }
 
     override suspend fun deleteEvent(eventId: Long) = withContext(io) {
         dataSource.deleteEvent(eventId)
     }
 
+    override suspend fun moveEvent(
+        eventId: Long,
+        targetCalendarId: Long,
+        original: EventForm,
+        updated: EventForm,
+    ): Long = withContext(io) {
+        dataSource.moveEvent(
+            eventId, targetCalendarId, original, updated, allDayReminderTimeMinutes(),
+        )
+    }
+
     override suspend fun updateOccurrence(
         eventId: Long,
         beginMillis: Long,
         form: EventForm,
     ): Long = withContext(io) {
-        dataSource.updateOccurrence(eventId, beginMillis, form)
+        dataSource.updateOccurrence(eventId, beginMillis, form, allDayReminderTimeMinutes())
     }
 
     override suspend fun updateEventFromOccurrence(
@@ -100,7 +272,9 @@ class CalendarRepositoryImpl @Inject constructor(
         original: EventForm,
         updated: EventForm,
     ): Long = withContext(io) {
-        dataSource.updateEventFromOccurrence(eventId, beginMillis, original, updated)
+        dataSource.updateEventFromOccurrence(
+            eventId, beginMillis, original, updated, allDayReminderTimeMinutes(),
+        )
     }
 
     override suspend fun deleteOccurrence(eventId: Long, beginMillis: Long) = withContext(io) {

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/CalendarVisibilityReconciler.kt

@@ -0,0 +1,113 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.util.Log
+import androidx.core.content.ContextCompat
+import dagger.hilt.EntryPoint
+import dagger.hilt.InstallIn
+import dagger.hilt.android.qualifiers.ApplicationContext
+import dagger.hilt.components.SingletonComponent
+import de.jeanlucmakiola.calendula.data.di.IoDispatcher
+import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
+import de.jeanlucmakiola.calendula.domain.calendarVisibilityPlan
+import de.jeanlucmakiola.calendula.domain.hasSystemHiddenCalendars
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.withContext
+import kotlin.coroutines.cancellation.CancellationException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Keeps [CalendarPrefs.pendingDisabledCalendarIds] and the system's
+ * `Calendars.VISIBLE` in step (#75): the fold-in of the retired app-local
+ * visibility model, and the standing drain for switch-offs made without
+ * `WRITE_CALENDAR`.
+ *
+ * Runs on every launch and on every calendar-permission grant; a no-op once the
+ * pending set is empty and the notice is settled. Only ever hides (see
+ * [calendarVisibilityPlan]); on an upgraded install the first run that sees a
+ * system-hidden calendar arms the one-time explanatory notice.
+ */
+@Singleton
+class CalendarVisibilityReconciler @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val dataSource: CalendarDataSource,
+    private val prefs: CalendarPrefs,
+    @IoDispatcher private val io: CoroutineDispatcher,
+) {
+
+    suspend fun run() = withContext(io) {
+        // The DataStore reads sit inside the guard too: this runs in a bare
+        // application-scope coroutine, so an IOException from a damaged
+        // preferences file would take the process down on every launch.
+        try {
+            // Settled ahead of the permission gate, so an update installed
+            // before the first grant can't later look like an upgrade.
+            if (!isUpgradeInstall()) settleNoticeOnce(pending = false)
+            if (!hasPermission(Manifest.permission.READ_CALENDAR)) return@withContext
+            val pending = prefs.pendingDisabledCalendarIds.first()
+            val noticeSettled = prefs.visibilityNoticePending.first() != null
+            if (pending.isEmpty() && noticeSettled) return@withContext
+            val calendars = dataSource.calendars()
+            // Empty means "couldn't read" (null cursor), not "no calendars".
+            // Both decisions below are one-way, so leave them to the next run.
+            if (calendars.isEmpty()) return@withContext
+            settleNoticeOnce(hasSystemHiddenCalendars(calendars, pending))
+            if (pending.isEmpty() || !hasPermission(Manifest.permission.WRITE_CALENDAR)) {
+                return@withContext
+            }
+            val plan = calendarVisibilityPlan(calendars, pending)
+            prefs.removePendingDisabledCalendarIds(plan.settled)
+            // One calendar per write: the provider skips its reminder-alarm
+            // reschedule for anything but a single-id update (see
+            // [CalendarDataSource.setCalendarVisible]).
+            for (id in plan.hide) {
+                dataSource.setCalendarVisible(id, false)
+                prefs.removePendingDisabledCalendarIds(setOf(id))
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Log.w(TAG, "Calendar visibility reconcile failed; will retry", e)
+        }
+    }
+
+    /**
+     * Settle the one-time notice: [pending] arms it, false retires it unshown.
+     * Answered once and stored either way, so it can't resurface later.
+     */
+    private suspend fun settleNoticeOnce(pending: Boolean) {
+        if (prefs.visibilityNoticePending.first() != null) return
+        prefs.setVisibilityNoticePending(pending)
+    }
+
+    /**
+     * Whether this install has ever run an earlier version. The notice explains
+     * a behaviour change, so a first install has nothing to announce.
+     */
+    private fun isUpgradeInstall(): Boolean = try {
+        @Suppress("DEPRECATION")
+        val info = context.packageManager.getPackageInfo(context.packageName, 0)
+        info.lastUpdateTime > info.firstInstallTime
+    } catch (e: PackageManager.NameNotFoundException) {
+        Log.w(TAG, "Own package info unavailable; treating as a fresh install", e)
+        false
+    }
+
+    private fun hasPermission(permission: String): Boolean =
+        ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
+
+    /** Lets non-injectable entry points (the Application) reach the reconciler. */
+    @EntryPoint
+    @InstallIn(SingletonComponent::class)
+    interface Deps {
+        fun calendarVisibilityReconciler(): CalendarVisibilityReconciler
+    }
+
+    private companion object {
+        const val TAG = "CalendarVisibility"
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/EventDetailMapper.kt

@@ -1,5 +1,6 @@
 package de.jeanlucmakiola.calendula.data.calendar
 
+import de.jeanlucmakiola.floret.time.toKotlinInstantFromEpochMillis
 import android.provider.CalendarContract
 import android.util.Log
 import de.jeanlucmakiola.calendula.domain.AccessLevel
@@ -13,46 +14,63 @@ import de.jeanlucmakiola.calendula.domain.EventInstance
 import de.jeanlucmakiola.calendula.domain.EventStatus
 import de.jeanlucmakiola.calendula.domain.Reminder
 import de.jeanlucmakiola.calendula.domain.ReminderMethod
+import de.jeanlucmakiola.calendula.domain.ics.parseRfc2445DurationMillis
+import java.time.Instant
+import java.time.ZoneId
+import java.time.ZoneOffset
 
 private const val TAG = "EventDetailMapper"
 
 internal fun ColumnReader.toEventDetailCore(
     attendees: List<Attendee>,
     reminders: List<Reminder>,
+    allDayReminderTimeMinutes: Int,
 ): EventDetail? {
+    // DTSTART is epoch millis in UTC, so a series anchored before 1970 (common
+    // for yearly birthdays/anniversaries synced over CalDAV) is legitimately
+    // negative — only an *absent* DTSTART marks a malformed row worth dropping.
+    // Dropping negatives made every occurrence of such a series un-openable
+    // (the detail loads the ancient series-master DTSTART), see issue #34.
+    if (isNull(EventDetailProjection.IDX_DTSTART)) {
+        Log.w(TAG, "Dropping event with missing dtstart")
+        return null
+    }
     val begin = getLong(EventDetailProjection.IDX_DTSTART)
 
-    if (begin < 0L) {
-        Log.w(TAG, "Dropping event with negative dtstart=$begin")
-        return null
-    }
-
     // Recurring events store DURATION instead of DTEND, so the series row's
-    // DTEND is null. Keep the event (end == begin); callers that opened a
-    // specific occurrence supply the real per-occurrence times from
-    // CalendarContract.Instances. Only a present-but-backwards DTEND is malformed.
+    // DTEND is null — derive the length from DURATION (as SearchMapper and
+    // IcsExportMapper do). Callers that opened a specific occurrence overwrite
+    // both times with the per-occurrence values from CalendarContract.Instances;
+    // a caller that names no occurrence (a bare content://.../events/<id> VIEW
+    // intent, issue #48) keeps this row's own times, so the length has to be
+    // right here or the series renders zero-length. A present-but-backwards
+    // DTEND is malformed, but dropping the row would make the event un-openable
+    // — the same trap as the pre-1970 DTSTART bug above (issue #34): it would
+    // surface as the generic error screen with no way to open the event and fix
+    // it. Clamp to a zero-length event instead (matching SearchMapper).
     val end = if (isNull(EventDetailProjection.IDX_DTEND)) {
-        begin
+        begin + parseRfc2445DurationMillis(getString(EventDetailProjection.IDX_DURATION))
     } else {
-        val rawEnd = getLong(EventDetailProjection.IDX_DTEND)
-        if (rawEnd < begin) {
-            Log.w(TAG, "Dropping event with dtend=$rawEnd < dtstart=$begin")
-            return null
-        }
-        rawEnd
+        getLong(EventDetailProjection.IDX_DTEND).coerceAtLeast(begin)
     }
 
     // Kept raw (no untitled fallback): the detail screen substitutes its own
     // localized placeholder, and the edit form must prefill the true value.
     val title = getString(EventDetailProjection.IDX_TITLE).orEmpty()
 
-    val color = if (isNull(EventDetailProjection.IDX_EVENT_COLOR)) {
-        getInt(EventDetailProjection.IDX_CALENDAR_COLOR)
+    // The event's own colour (null = inherits the calendar's) is kept apart
+    // from the resolved display colour: the edit form needs to tell the two
+    // cases apart, while the instance carries the calendar fallback for display.
+    val eventColor = if (isNull(EventDetailProjection.IDX_EVENT_COLOR)) {
+        null
     } else {
         getInt(EventDetailProjection.IDX_EVENT_COLOR)
     }
+    val eventColorKey = getString(EventDetailProjection.IDX_EVENT_COLOR_KEY)
+    val color = eventColor ?: getInt(EventDetailProjection.IDX_CALENDAR_COLOR)
 
     val eventId = getLong(EventDetailProjection.IDX_EVENT_ID)
+    val isAllDay = getInt(EventDetailProjection.IDX_ALL_DAY) != 0
     val instance = EventInstance(
         instanceId = eventId,
         eventId = eventId,
@@ -60,11 +78,29 @@ internal fun ColumnReader.toEventDetailCore(
         title = title,
         start = begin.toKotlinInstantFromEpochMillis(),
         end = end.toKotlinInstantFromEpochMillis(),
-        isAllDay = getInt(EventDetailProjection.IDX_ALL_DAY) != 0,
+        isAllDay = isAllDay,
         color = color,
         location = getString(EventDetailProjection.IDX_LOCATION),
     )
 
+    // All-day reminders are stored as a wall-clock-shifted offset (see
+    // AllDayReminderEncoding); decode back to the whole-day lead time the form
+    // and detail screen speak. DTSTART is UTC midnight for all-day events, so the
+    // event's date is its UTC date.
+    val displayReminders = if (isAllDay) {
+        val startDate = Instant.ofEpochMilli(begin).atZone(ZoneOffset.UTC).toLocalDate()
+        val zone = ZoneId.systemDefault()
+        reminders.map {
+            it.copy(
+                minutes = fromProviderAllDayMinutes(
+                    it.minutes, startDate, zone, allDayReminderTimeMinutes,
+                ),
+            )
+        }
+    } else {
+        reminders
+    }
+
     // STATUS shares its 0 value with STATUS_TENTATIVE, so a missing column must
     // be distinguished from a present 0 — an absent status means "just confirmed".
     val status = if (isNull(EventDetailProjection.IDX_STATUS)) {
@@ -79,7 +115,7 @@ internal fun ColumnReader.toEventDetailCore(
         organizer = getString(EventDetailProjection.IDX_ORGANIZER),
         attendees = attendees,
         rrule = getString(EventDetailProjection.IDX_RRULE),
-        reminders = reminders,
+        reminders = displayReminders,
         status = status,
         // BUSY and DEFAULT are both 0, so a null column folds into the same
         // default these mappers already return — no isNull guard needed.
@@ -87,6 +123,8 @@ internal fun ColumnReader.toEventDetailCore(
         accessLevel = mapAccessLevel(getInt(EventDetailProjection.IDX_ACCESS_LEVEL)),
         eventTimezone = getString(EventDetailProjection.IDX_EVENT_TIMEZONE),
         selfStatus = mapAttendeeStatus(getInt(EventDetailProjection.IDX_SELF_ATTENDEE_STATUS)),
+        eventColor = eventColor,
+        eventColorKey = eventColorKey,
     )
 }
 

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/EventWriteMapper.kt

@@ -6,9 +6,11 @@ import de.jeanlucmakiola.calendula.domain.Availability
 import de.jeanlucmakiola.calendula.domain.EventForm
 import kotlinx.datetime.toJavaLocalDate
 import kotlinx.datetime.toJavaLocalDateTime
+import java.time.Duration
 import java.time.Instant
 import java.time.ZoneId
 import java.time.ZoneOffset
+import java.time.LocalDateTime as JavaLocalDateTime
 
 /** Provider-ready DTSTART / DTEND / EVENT_TIMEZONE for an event write. */
 internal data class EventWriteTimes(
@@ -20,7 +22,11 @@ internal data class EventWriteTimes(
 /**
  * All-day events live at UTC midnights with an exclusive DTEND (the
  * CalendarContract convention — a one-day event ends at the next midnight);
- * timed events resolve their wall-clock values in [zone].
+ * timed events resolve their wall-clock values in the form's own
+ * [EventForm.timezone], falling back to [zone] (the device) when it doesn't pin
+ * one. Passing the device zone is therefore still correct for an unpinned form —
+ * but it no longer overrides a pinned event's zone, which is what used to
+ * silently re-anchor a foreign-zone event to the device on any time edit.
  */
 internal fun EventForm.toWriteTimes(zone: ZoneId): EventWriteTimes = if (isAllDay) {
     EventWriteTimes(
@@ -31,22 +37,92 @@ internal fun EventForm.toWriteTimes(zone: ZoneId): EventWriteTimes = if (isAllDa
         timezone = "UTC",
     )
 } else {
+    val writeZone = writeZone(zone)
     EventWriteTimes(
-        dtStartMillis = start.toJavaLocalDateTime().atZone(zone).toInstant().toEpochMilli(),
-        dtEndMillis = end.toJavaLocalDateTime().atZone(zone).toInstant().toEpochMilli(),
-        timezone = zone.id,
+        dtStartMillis = start.toJavaLocalDateTime().atZone(writeZone).toInstant().toEpochMilli(),
+        dtEndMillis = end.toJavaLocalDateTime().atZone(writeZone).toInstant().toEpochMilli(),
+        timezone = writeZone.id,
     )
 }
 
+/**
+ * The zone this form's DTSTART is expressed in: UTC for an all-day event (the
+ * provider's date anchor), otherwise the form's own pinned zone, falling back to
+ * [deviceZone] when it doesn't pin one or pins something the tz database can't
+ * parse.
+ */
+private fun EventForm.writeZone(deviceZone: ZoneId): ZoneId = if (isAllDay) {
+    ZoneOffset.UTC
+} else {
+    timezone?.let { runCatching { ZoneId.of(it) }.getOrNull() } ?: deviceZone
+}
+
+/**
+ * The form's start as a bare wall-clock value — what the user sees on the form,
+ * stripped of any zone. All-day events use their date's midnight rather than
+ * [EventForm.start]'s placeholder time-of-day, which exists only so switching the
+ * event back to timed has something to show.
+ */
+private fun EventForm.anchorLocal(): JavaLocalDateTime = if (isAllDay) {
+    start.date.toJavaLocalDate().atStartOfDay()
+} else {
+    start.toJavaLocalDateTime()
+}
+
 /**
  * RFC 2445 duration for a recurring event's row (the provider requires
  * DURATION instead of DTEND when an RRULE is set): whole days for all-day
  * events, seconds otherwise.
  */
-internal fun EventWriteTimes.toRfc2445Duration(isAllDay: Boolean): String = if (isAllDay) {
-    "P${(dtEndMillis - dtStartMillis) / MILLIS_PER_DAY}D"
+internal fun EventWriteTimes.toRfc2445Duration(isAllDay: Boolean): String =
+    rfc2445Duration(dtEndMillis - dtStartMillis, isAllDay)
+
+/**
+ * RFC 2445 duration for a [spanMillis]-long event: whole days for all-day
+ * events (the provider's convention), seconds otherwise. Shared by the write
+ * paths that need a DURATION but start from a raw millisecond span (the series
+ * copy and exception replay of a calendar move) rather than [EventWriteTimes].
+ */
+internal fun rfc2445Duration(spanMillis: Long, isAllDay: Boolean): String = if (isAllDay) {
+    "P${spanMillis / MILLIS_PER_DAY}D"
 } else {
-    "P${(dtEndMillis - dtStartMillis) / 1_000L}S"
+    "P${spanMillis / 1_000L}S"
+}
+
+/**
+ * Column values for a brand-new Events row: identity, times (the provider's
+ * invariant — recurring rows carry RRULE+DURATION and no DTEND, one-off rows
+ * carry DTEND), availability/access level and trimmed optional text. Shared by
+ * the user-event and managed-event insert paths, which differ only in the
+ * [uid] they stamp; colour and attendees are user-event concerns the caller
+ * layers on top.
+ */
+internal fun buildEventInsertValues(
+    form: EventForm,
+    uid: String,
+    times: EventWriteTimes,
+): Map<String, Any?> = buildMap {
+    put(
+        CalendarContract.Events.CALENDAR_ID,
+        requireNotNull(form.calendarId) { "EventForm.calendarId is required" },
+    )
+    put(CalendarContract.Events.UID_2445, uid)
+    put(CalendarContract.Events.TITLE, form.title.trim())
+    put(CalendarContract.Events.ALL_DAY, if (form.isAllDay) 1 else 0)
+    put(CalendarContract.Events.DTSTART, times.dtStartMillis)
+    if (form.rrule == null) {
+        put(CalendarContract.Events.DTEND, times.dtEndMillis)
+    } else {
+        put(CalendarContract.Events.RRULE, form.rrule)
+        put(CalendarContract.Events.DURATION, times.toRfc2445Duration(form.isAllDay))
+    }
+    put(CalendarContract.Events.EVENT_TIMEZONE, times.timezone)
+    put(CalendarContract.Events.AVAILABILITY, form.availability.toProviderValue())
+    put(CalendarContract.Events.ACCESS_LEVEL, form.accessLevel.toProviderValue())
+    form.location.trim().takeIf { it.isNotEmpty() }
+        ?.let { put(CalendarContract.Events.EVENT_LOCATION, it) }
+    form.description.trim().takeIf { it.isNotEmpty() }
+        ?.let { put(CalendarContract.Events.DESCRIPTION, it) }
 }
 
 /**
@@ -59,10 +135,12 @@ internal fun EventWriteTimes.toRfc2445Duration(isAllDay: Boolean): String = if (
  * Time fields travel together (the provider validates them as a unit):
  * - unchanged times, all-day flag and rrule → no time columns at all;
  * - non-recurring result → DTSTART/DTEND, DURATION and RRULE cleared;
- * - recurring result → the *series* DTSTART moves by the same delta the user
- *   applied to the displayed occurrence ([seriesDtStartMillis] is the row's
- *   current DTSTART), DURATION replaces DTEND, RRULE is written. This keeps
- *   past occurrences intact when someone edits a later occurrence's time.
+ * - recurring result → the *series* DTSTART moves by the same **wall-clock**
+ *   shift the user applied to the displayed occurrence and is re-resolved in the
+ *   event's zone ([seriesDtStartMillis] is the row's current DTSTART), DURATION
+ *   replaces DTEND, RRULE is written. This keeps past occurrences intact when
+ *   someone edits a later occurrence's time, and keeps the anchor's time-of-day
+ *   stable across a DST boundary or a zone change between the two.
  */
 internal fun buildEventUpdateValues(
     original: EventForm,
@@ -85,11 +163,18 @@ internal fun buildEventUpdateValues(
     if (updated.accessLevel != original.accessLevel) {
         put(CalendarContract.Events.ACCESS_LEVEL, updated.accessLevel.toProviderValue())
     }
+    if (updated.colorKey != original.colorKey || updated.color != original.color) {
+        putAll(eventColorColumns(updated.colorKey, updated.color))
+    }
 
+    // A zone change counts as a time change even when the wall-clock is
+    // untouched: the same 09:00 in another zone is a different instant, so
+    // DTSTART has to move with it.
     val timesChanged = updated.start != original.start ||
         updated.end != original.end ||
         updated.isAllDay != original.isAllDay ||
-        updated.rrule != original.rrule
+        updated.rrule != original.rrule ||
+        updated.timezone != original.timezone
     if (!timesChanged) return@buildMap
 
     val newTimes = updated.toWriteTimes(zone)
@@ -101,8 +186,23 @@ internal fun buildEventUpdateValues(
         put(CalendarContract.Events.RRULE, null)
         put(CalendarContract.Events.DURATION, null)
     } else {
-        val startDelta = newTimes.dtStartMillis - original.toWriteTimes(zone).dtStartMillis
-        put(CalendarContract.Events.DTSTART, seriesDtStartMillis + startDelta)
+        // Move the series anchor by the *wall-clock* shift the user applied to the
+        // displayed occurrence, then re-resolve it in the event's (possibly new)
+        // zone — never by a millisecond delta. An instant delta silently bakes in
+        // the offset that happened to apply on the edited occurrence's date, which
+        // is a different offset from the series anchor's whenever a DST boundary
+        // sits between them, or whenever the zone itself changed. Working in wall
+        // clock keeps "09:00" meaning 09:00 at both ends.
+        val seriesLocal = Instant.ofEpochMilli(seriesDtStartMillis)
+            .atZone(original.writeZone(zone)).toLocalDateTime()
+        val wallClockShift = Duration.between(original.anchorLocal(), updated.anchorLocal())
+        val shifted = seriesLocal.plus(wallClockShift)
+        // An all-day series anchor must sit on a UTC midnight. A pure day move
+        // already lands there (both ends are midnights), but *switching* a
+        // recurring event to all-day shifts by a time-of-day too, so snap.
+        val newSeriesLocal = if (updated.isAllDay) shifted.toLocalDate().atStartOfDay() else shifted
+        val newSeriesStart = newSeriesLocal.atZone(updated.writeZone(zone))
+        put(CalendarContract.Events.DTSTART, newSeriesStart.toInstant().toEpochMilli())
         put(CalendarContract.Events.DTEND, null)
         put(CalendarContract.Events.RRULE, updated.rrule)
         put(CalendarContract.Events.DURATION, newTimes.toRfc2445Duration(updated.isAllDay))
@@ -115,8 +215,14 @@ internal fun buildEventUpdateValues(
  * provider clone the series row and apply these on top. Unlike the series
  * update there is no dirty check — the exception is a fresh row, so every
  * form-backed column is written (empty optionals as explicit NULLs, since the
- * clone starts from the parent's values). An exception is a single event:
- * DTEND, never RRULE/DURATION.
+ * clone starts from the parent's values).
+ *
+ * The occurrence's length travels as DURATION, never DTEND: the provider
+ * rejects DTEND on an exception outright (`CalendarProvider2`:
+ * "Exceptions can't overwrite dtend") and derives the instance end from
+ * DTSTART + DURATION itself, clearing the inherited RRULE in the process. This
+ * matches how AOSP Calendar/Etar write exceptions; sending DTEND is what made
+ * "only this event" fail on-device (Codeberg #16).
  */
 internal fun buildOccurrenceExceptionValues(
     form: EventForm,
@@ -128,12 +234,243 @@ internal fun buildOccurrenceExceptionValues(
     put(CalendarContract.Events.TITLE, form.title.trim())
     put(CalendarContract.Events.ALL_DAY, if (form.isAllDay) 1 else 0)
     put(CalendarContract.Events.DTSTART, times.dtStartMillis)
-    put(CalendarContract.Events.DTEND, times.dtEndMillis)
+    put(CalendarContract.Events.DURATION, times.toRfc2445Duration(form.isAllDay))
     put(CalendarContract.Events.EVENT_TIMEZONE, times.timezone)
     put(CalendarContract.Events.AVAILABILITY, form.availability.toProviderValue())
     put(CalendarContract.Events.ACCESS_LEVEL, form.accessLevel.toProviderValue())
     put(CalendarContract.Events.EVENT_LOCATION, form.location.trim().ifEmpty { null })
     put(CalendarContract.Events.DESCRIPTION, form.description.trim().ifEmpty { null })
+    putAll(eventColorColumns(form.colorKey, form.color))
+}
+
+/**
+ * Raw provider snapshot of a master/one-off Events row, enough to re-insert it
+ * verbatim on another calendar (a calendar move is copy+delete — `CALENDAR_ID`
+ * is sync-adapter-owned and can't be updated in place). Recurring rows carry
+ * [rrule]/[duration] (and any [rdate]/[exdate]) with a null [dtEndMillis];
+ * one-off rows carry [dtEndMillis]. Colour is deliberately absent: a raw
+ * `EVENT_COLOR` or account-scoped `EVENT_COLOR_KEY` may be invalid on the target
+ * account, so the moved copy inherits the target calendar's colour instead.
+ */
+internal data class MasterEventSnapshot(
+    val title: String,
+    val isAllDay: Boolean,
+    val dtStartMillis: Long,
+    val dtEndMillis: Long?,
+    val duration: String?,
+    val rrule: String?,
+    val rdate: String?,
+    val exdate: String?,
+    val timezone: String?,
+    val availability: Int,
+    val accessLevel: Int,
+    val status: Int?,
+    val location: String?,
+    val description: String?,
+)
+
+/**
+ * Column values re-creating [snapshot] as a fresh Events row on
+ * [targetCalendarId], keeping its [uid] so `.ics` backup dedup and sync identity
+ * survive the move. Preserves the recurrence skeleton (DTSTART/RRULE/DURATION,
+ * RDATE/EXDATE) so the series' generated instances — and therefore the
+ * ORIGINAL_INSTANCE_TIME of every copied exception — line up unchanged. The
+ * caller layers the user's field edits on top with a normal series update.
+ */
+internal fun buildMovedMasterValues(
+    snapshot: MasterEventSnapshot,
+    targetCalendarId: Long,
+    uid: String,
+): Map<String, Any?> = buildMap {
+    put(CalendarContract.Events.CALENDAR_ID, targetCalendarId)
+    put(CalendarContract.Events.UID_2445, uid)
+    put(CalendarContract.Events.TITLE, snapshot.title)
+    put(CalendarContract.Events.ALL_DAY, if (snapshot.isAllDay) 1 else 0)
+    put(CalendarContract.Events.DTSTART, snapshot.dtStartMillis)
+    put(CalendarContract.Events.EVENT_TIMEZONE, snapshot.timezone ?: "UTC")
+    if (snapshot.rrule != null) {
+        put(CalendarContract.Events.RRULE, snapshot.rrule)
+        snapshot.rdate?.takeIf { it.isNotBlank() }?.let { put(CalendarContract.Events.RDATE, it) }
+        snapshot.exdate?.takeIf { it.isNotBlank() }?.let { put(CalendarContract.Events.EXDATE, it) }
+        put(CalendarContract.Events.DURATION, snapshot.movedDuration())
+    } else {
+        snapshot.dtEndMillis?.let { put(CalendarContract.Events.DTEND, it) }
+    }
+    put(CalendarContract.Events.AVAILABILITY, snapshot.availability)
+    put(CalendarContract.Events.ACCESS_LEVEL, snapshot.accessLevel)
+    snapshot.status?.let { put(CalendarContract.Events.STATUS, it) }
+    put(CalendarContract.Events.EVENT_LOCATION, snapshot.location?.ifEmpty { null })
+    put(CalendarContract.Events.DESCRIPTION, snapshot.description?.ifEmpty { null })
+}
+
+/** The recurring copy's DURATION: its own if present, else derived from DTEND. */
+private fun MasterEventSnapshot.movedDuration(): String = duration?.takeIf { it.isNotBlank() }
+    ?: rfc2445Duration((dtEndMillis ?: dtStartMillis) - dtStartMillis, isAllDay)
+
+/**
+ * Raw provider snapshot of one exception row of a recurring series (a modified
+ * or cancelled occurrence, `ORIGINAL_ID` = the series). [originalInstanceMillis]
+ * ties it to the occurrence it overrides; a [isCancelled] row only needs that.
+ */
+internal data class ExceptionRowSnapshot(
+    val exceptionEventId: Long,
+    val originalInstanceMillis: Long,
+    val isCancelled: Boolean,
+    val status: Int?,
+    val title: String,
+    val isAllDay: Boolean,
+    val dtStartMillis: Long,
+    val dtEndMillis: Long?,
+    val duration: String?,
+    val timezone: String?,
+    val availability: Int,
+    val accessLevel: Int,
+    val location: String?,
+    val description: String?,
+)
+
+/**
+ * Column values replaying a *modified* occurrence [snapshot] against the moved
+ * series via `CONTENT_EXCEPTION_URI`. Like [buildOccurrenceExceptionValues] the
+ * length travels as DURATION (the provider rejects DTEND on an exception). A
+ * cancelled occurrence is written separately (ORIGINAL_INSTANCE_TIME +
+ * STATUS_CANCELED) — this builder is only for the modified case.
+ */
+internal fun buildCopiedExceptionValues(snapshot: ExceptionRowSnapshot): Map<String, Any?> =
+    buildMap {
+        put(CalendarContract.Events.ORIGINAL_INSTANCE_TIME, snapshot.originalInstanceMillis)
+        put(CalendarContract.Events.TITLE, snapshot.title)
+        put(CalendarContract.Events.ALL_DAY, if (snapshot.isAllDay) 1 else 0)
+        put(CalendarContract.Events.DTSTART, snapshot.dtStartMillis)
+        put(
+            CalendarContract.Events.DURATION,
+            snapshot.duration?.takeIf { it.isNotBlank() }
+                ?: rfc2445Duration(
+                    (snapshot.dtEndMillis ?: snapshot.dtStartMillis) - snapshot.dtStartMillis,
+                    snapshot.isAllDay,
+                ),
+        )
+        put(CalendarContract.Events.EVENT_TIMEZONE, snapshot.timezone ?: "UTC")
+        put(CalendarContract.Events.AVAILABILITY, snapshot.availability)
+        put(CalendarContract.Events.ACCESS_LEVEL, snapshot.accessLevel)
+        put(CalendarContract.Events.EVENT_LOCATION, snapshot.location?.ifEmpty { null })
+        put(CalendarContract.Events.DESCRIPTION, snapshot.description?.ifEmpty { null })
+        snapshot.status?.let { put(CalendarContract.Events.STATUS, it) }
+    }
+
+/**
+ * Column values for a *cancelled*-occurrence exception row ("delete only this
+ * event"): inserting them at `Events.CONTENT_EXCEPTION_URI/<id>` makes the
+ * provider clone the series row and cancel exactly this one instance.
+ *
+ * As with [buildOccurrenceExceptionValues], the occurrence must be anchored with
+ * DTSTART + DURATION so the provider derives a single instance and clears the
+ * inherited RRULE. A STATUS-only cancel skips that: the clone keeps the RRULE, so
+ * the *whole series* is cancelled and every other occurrence disappears
+ * (Codeberg #47). The occurrence's length/zone come straight from the series row
+ * — cancelling never changes them.
+ */
+internal fun buildOccurrenceCancelValues(
+    originalInstanceMillis: Long,
+    dtStartMillis: Long,
+    duration: String?,
+    timezone: String?,
+    allDay: Int,
+): Map<String, Any?> = buildMap {
+    put(CalendarContract.Events.ORIGINAL_INSTANCE_TIME, originalInstanceMillis)
+    put(CalendarContract.Events.DTSTART, dtStartMillis)
+    put(CalendarContract.Events.DURATION, duration)
+    put(CalendarContract.Events.EVENT_TIMEZONE, timezone)
+    put(CalendarContract.Events.ALL_DAY, allDay)
+    put(CalendarContract.Events.STATUS, CalendarContract.Events.STATUS_CANCELED)
+}
+
+/**
+ * The master-row columns that drop the occurrence at [occurrenceMillis] from a
+ * series by adding it to `EXDATE` — the path for events that have **no
+ * `_sync_id`** (a local calendar, or a synced event not yet pushed).
+ *
+ * A cancelled exception row (see [buildOccurrenceCancelValues]) only attaches to
+ * its parent through `ORIGINAL_SYNC_ID`. Without a `_sync_id` the link never
+ * forms, and the provider's expansion of the *parent* collapses — every other
+ * occurrence disappears (Codeberg #47, reproduced on a local calendar). EXDATE
+ * needs no link, and is the canonical iCalendar way to drop an occurrence, so a
+ * sync adapter carries it upstream unchanged if the calendar later syncs.
+ *
+ * The whole time/recurrence set is rewritten alongside it on purpose. The
+ * provider does **not** treat an EXDATE-only update as a recurrence change: it
+ * leaves the expanded `Instances` rows untouched, so the occurrence stays visible
+ * (and, symmetrically, un-excluding one leaves it hidden). Writing DTSTART with
+ * it forces the re-expansion — but DTSTART *alone* makes the provider recompute
+ * `lastDate` as if the event were a single instance, collapsing the series to its
+ * first occurrence. Passing DTSTART + DURATION + RRULE + zone together is what
+ * re-expands it correctly. All observed on a Pixel; see the #47 notes.
+ *
+ * EXDATE is a comma-separated list, so an existing one is appended to (a repeat
+ * of the same occurrence is folded away). All-day series take the `VALUE=DATE`
+ * form (`yyyyMMdd`), timed ones the UTC date-time form (`yyyyMMddTHHmmssZ`).
+ */
+internal fun buildOccurrenceExdateValues(
+    existingExdate: String?,
+    occurrenceMillis: Long,
+    dtStartMillis: Long,
+    rrule: String?,
+    duration: String?,
+    timezone: String?,
+    allDay: Int,
+): Map<String, Any?> {
+    val stamp = formatExdateStamp(occurrenceMillis, isAllDay = allDay != 0)
+    val existing = existingExdate?.split(',')
+        ?.map { it.trim() }
+        ?.filter { it.isNotEmpty() }
+        .orEmpty()
+    val merged = (existing + stamp).distinct().joinToString(",")
+    return mapOf(
+        CalendarContract.Events.EXDATE to merged,
+        CalendarContract.Events.DTSTART to dtStartMillis,
+        CalendarContract.Events.RRULE to rrule,
+        CalendarContract.Events.DURATION to duration,
+        CalendarContract.Events.EVENT_TIMEZONE to timezone,
+        CalendarContract.Events.ALL_DAY to allDay,
+    )
+}
+
+/**
+ * One EXDATE entry for the occurrence starting at [occurrenceMillis]. Both forms
+ * are UTC: the provider stores an all-day DTSTART at UTC midnight, so its date
+ * reads off the UTC calendar day.
+ */
+private fun formatExdateStamp(occurrenceMillis: Long, isAllDay: Boolean): String {
+    val utc = Instant.ofEpochMilli(occurrenceMillis).atZone(ZoneOffset.UTC)
+    return if (isAllDay) {
+        "%04d%02d%02d".format(utc.year, utc.monthValue, utc.dayOfMonth)
+    } else {
+        "%04d%02d%02dT%02d%02d%02dZ".format(
+            utc.year, utc.monthValue, utc.dayOfMonth,
+            utc.hour, utc.minute, utc.second,
+        )
+    }
+}
+
+/**
+ * The `EVENT_COLOR` / `EVENT_COLOR_KEY` columns for a colour selection. A
+ * [colorKey] writes the key alone (the provider derives `EVENT_COLOR` from the
+ * account's palette, so the colour round-trips through sync); a raw [color]
+ * writes `EVENT_COLOR` and clears any key; "no colour" clears both so the event
+ * falls back to its calendar's colour. The two are never written together —
+ * the provider rejects a raw colour on a calendar that publishes a palette,
+ * which is exactly why palette calendars only ever go through the key.
+ */
+internal fun eventColorColumns(colorKey: String?, color: Int?): Map<String, Any?> = when {
+    colorKey != null -> mapOf(CalendarContract.Events.EVENT_COLOR_KEY to colorKey)
+    color != null -> mapOf(
+        CalendarContract.Events.EVENT_COLOR_KEY to null,
+        CalendarContract.Events.EVENT_COLOR to color,
+    )
+    else -> mapOf(
+        CalendarContract.Events.EVENT_COLOR_KEY to null,
+        CalendarContract.Events.EVENT_COLOR to null,
+    )
 }
 
 /**

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/IcsExportMapper.kt

@@ -0,0 +1,55 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+import de.jeanlucmakiola.floret.time.toKotlinInstantFromEpochMillis
+import de.jeanlucmakiola.calendula.domain.EventStatus
+import de.jeanlucmakiola.calendula.domain.ics.IcsEvent
+import de.jeanlucmakiola.calendula.domain.ics.deriveIcsUid
+import de.jeanlucmakiola.calendula.domain.ics.parseRfc2445DurationMillis
+
+/**
+ * Map one Events row (read through [EventExportProjection]) into an [IcsEvent]
+ * for backup. [reminderMinutes] are the row's raw provider reminder offsets and
+ * [calendarName] the display name of its calendar (emitted as
+ * `X-CALENDULA-CALENDAR`). Pure given a [ColumnReader] — JVM-tested with
+ * MapColumnReader.
+ */
+internal fun ColumnReader.toIcsEvent(
+    reminderMinutes: List<Int>,
+    calendarName: String?,
+): IcsEvent {
+    val eventId = getLong(EventExportProjection.IDX_ID)
+    val dtStart = getLong(EventExportProjection.IDX_DTSTART)
+    val rrule = getString(EventExportProjection.IDX_RRULE)?.takeIf { it.isNotBlank() }
+
+    // Recurring rows store DURATION instead of DTEND; reconstruct the end from it
+    // so the writer can render DTEND. A missing/blank both means a zero-length event.
+    val end = when {
+        !isNull(EventExportProjection.IDX_DTEND) -> getLong(EventExportProjection.IDX_DTEND)
+        else -> dtStart + parseRfc2445DurationMillis(getString(EventExportProjection.IDX_DURATION))
+    }
+
+    // STATUS shares value 0 with TENTATIVE, so an absent column must read as Confirmed.
+    val status = if (isNull(EventExportProjection.IDX_STATUS)) {
+        EventStatus.Confirmed
+    } else {
+        mapEventStatus(getInt(EventExportProjection.IDX_STATUS))
+    }
+
+    return IcsEvent(
+        uid = deriveIcsUid(getString(EventExportProjection.IDX_UID), eventId, dtStart),
+        summary = getString(EventExportProjection.IDX_TITLE).orEmpty(),
+        start = dtStart.toKotlinInstantFromEpochMillis(),
+        end = end.toKotlinInstantFromEpochMillis(),
+        isAllDay = getInt(EventExportProjection.IDX_ALL_DAY) != 0,
+        zoneId = getString(EventExportProjection.IDX_EVENT_TIMEZONE)?.takeIf { it.isNotBlank() }
+            ?: "UTC",
+        recurrenceRule = rrule,
+        location = getString(EventExportProjection.IDX_LOCATION),
+        description = getString(EventExportProjection.IDX_DESCRIPTION),
+        reminderMinutes = reminderMinutes,
+        status = status,
+        availability = mapAvailability(getInt(EventExportProjection.IDX_AVAILABILITY)),
+        calendarName = calendarName,
+    )
+}
+

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/InstanceMapper.kt

@@ -1,5 +1,6 @@
 package de.jeanlucmakiola.calendula.data.calendar
 
+import de.jeanlucmakiola.floret.time.toKotlinInstantFromEpochMillis
 import android.util.Log
 import de.jeanlucmakiola.calendula.domain.EventInstance
 

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/ManagedCalendar.kt

@@ -0,0 +1,24 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+
+/**
+ * One of the app's special-dates calendars, discovered by the marker stamped in
+ * its `CAL_SYNC2` column — so the mirror can re-adopt its calendars even if the
+ * stored ids in preferences were lost (e.g. an app-data wipe).
+ */
+data class ManagedCalendarRow(val id: Long, val type: SpecialDateType)
+
+/**
+ * A managed event as read back for the sync diff. [uid] is the deterministic
+ * `Events.UID_2445` (`contact-<type>:<lookupKey>@calendula`) the mirror keys on;
+ * [title], [dtStartMillis] and [rrule] are the managed columns compared against
+ * the desired state to decide whether a targeted update is needed.
+ */
+data class ManagedEventRow(
+    val eventId: Long,
+    val uid: String,
+    val title: String,
+    val dtStartMillis: Long,
+    val rrule: String?,
+)

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/Projections.kt

@@ -11,8 +11,23 @@ internal object CalendarProjection {
         CalendarContract.Calendars.CALENDAR_COLOR,
         CalendarContract.Calendars.VISIBLE,
         CalendarContract.Calendars.CALENDAR_ACCESS_LEVEL,
+        // CalendarContract has no description column; for the local calendars we
+        // own we stash one in CAL_SYNC1 (synced rows put their sync token here,
+        // so the mapper only reads it for local calendars).
+        DESCRIPTION_COLUMN,
+        // The special-dates marker (CAL_SYNC2) — the durable identity the app
+        // uses to recognise its own managed calendars, independent of any
+        // stored preference id (which a backup restore / data wipe can lose).
+        MANAGED_MARKER_COLUMN,
+        CalendarContract.Calendars.SYNC_EVENTS,
     )
 
+    const val DESCRIPTION_COLUMN: String = CalendarContract.Calendars.CAL_SYNC1
+    const val MANAGED_MARKER_COLUMN: String = CalendarContract.Calendars.CAL_SYNC2
+
+    /** Namespace prefix of every managed-calendar [MANAGED_MARKER_COLUMN] value. */
+    const val MANAGED_MARKER_PREFIX = "calendula.specialdates"
+
     const val IDX_ID = 0
     const val IDX_DISPLAY_NAME = 1
     const val IDX_ACCOUNT_NAME = 2
@@ -20,6 +35,9 @@ internal object CalendarProjection {
     const val IDX_COLOR = 4
     const val IDX_VISIBLE = 5
     const val IDX_ACCESS_LEVEL = 6
+    const val IDX_DESCRIPTION = 7
+    const val IDX_MANAGED_MARKER = 8
+    const val IDX_SYNC_EVENTS = 9
 }
 
 internal object InstanceProjection {
@@ -67,6 +85,10 @@ internal object EventDetailProjection {
         CalendarContract.Events.ACCESS_LEVEL,
         CalendarContract.Events.EVENT_TIMEZONE,
         CalendarContract.Events.SELF_ATTENDEE_STATUS,
+        CalendarContract.Events.EVENT_COLOR_KEY,
+        // Recurring rows carry DURATION instead of DTEND; the detail screen
+        // needs it to render a series opened without a named occurrence.
+        CalendarContract.Events.DURATION,
     )
 
     const val IDX_EVENT_ID = 0
@@ -86,6 +108,168 @@ internal object EventDetailProjection {
     const val IDX_ACCESS_LEVEL = 14
     const val IDX_EVENT_TIMEZONE = 15
     const val IDX_SELF_ATTENDEE_STATUS = 16
+    const val IDX_EVENT_COLOR_KEY = 17
+    const val IDX_DURATION = 18
+}
+
+/**
+ * Master/one-off Events rows for a whole-calendar backup. Unlike
+ * [EventDetailProjection] this reads `UID_2445` (to keep a row's identity across
+ * backups) and `DURATION` (recurring rows carry it instead of DTEND). Modified-
+ * occurrence and cancelled-exception rows are filtered out by the query
+ * (`ORIGINAL_ID IS NULL`), so RECURRENCE-ID overrides and EXDATEs aren't
+ * exported yet — a documented v1 limit (import skips them too).
+ */
+internal object EventExportProjection {
+    val COLUMNS: Array<String> = arrayOf(
+        CalendarContract.Events._ID,
+        CalendarContract.Events.UID_2445,
+        CalendarContract.Events.TITLE,
+        CalendarContract.Events.DTSTART,
+        CalendarContract.Events.DTEND,
+        CalendarContract.Events.DURATION,
+        CalendarContract.Events.ALL_DAY,
+        CalendarContract.Events.EVENT_TIMEZONE,
+        CalendarContract.Events.RRULE,
+        CalendarContract.Events.EVENT_LOCATION,
+        CalendarContract.Events.DESCRIPTION,
+        CalendarContract.Events.STATUS,
+        CalendarContract.Events.AVAILABILITY,
+        CalendarContract.Events.CALENDAR_ID,
+    )
+
+    const val IDX_ID = 0
+    const val IDX_UID = 1
+    const val IDX_TITLE = 2
+    const val IDX_DTSTART = 3
+    const val IDX_DTEND = 4
+    const val IDX_DURATION = 5
+    const val IDX_ALL_DAY = 6
+    const val IDX_EVENT_TIMEZONE = 7
+    const val IDX_RRULE = 8
+    const val IDX_LOCATION = 9
+    const val IDX_DESCRIPTION = 10
+    const val IDX_STATUS = 11
+    const val IDX_AVAILABILITY = 12
+    const val IDX_CALENDAR_ID = 13
+}
+
+/**
+ * Master/one-off Events rows matched by a full-text search. Like
+ * [EventExportProjection] it reads the Events table directly (so the search is
+ * unbounded in time), carrying DURATION for recurring rows that have no DTEND.
+ * Colour folds the calendar fallback like [InstanceProjection].
+ */
+internal object SearchProjection {
+    val COLUMNS: Array<String> = arrayOf(
+        CalendarContract.Events._ID,
+        CalendarContract.Events.CALENDAR_ID,
+        CalendarContract.Events.TITLE,
+        CalendarContract.Events.DTSTART,
+        CalendarContract.Events.DTEND,
+        CalendarContract.Events.DURATION,
+        CalendarContract.Events.ALL_DAY,
+        CalendarContract.Events.EVENT_COLOR,
+        CalendarContract.Events.CALENDAR_COLOR,
+        CalendarContract.Events.EVENT_LOCATION,
+        // Recurrence markers: a non-empty RRULE or RDATE means the result should
+        // display its nearest occurrence, not the series-start DTSTART.
+        CalendarContract.Events.RRULE,
+        CalendarContract.Events.RDATE,
+    )
+
+    const val IDX_ID = 0
+    const val IDX_CALENDAR_ID = 1
+    const val IDX_TITLE = 2
+    const val IDX_DTSTART = 3
+    const val IDX_DTEND = 4
+    const val IDX_DURATION = 5
+    const val IDX_ALL_DAY = 6
+    const val IDX_EVENT_COLOR = 7
+    const val IDX_CALENDAR_COLOR = 8
+    const val IDX_LOCATION = 9
+    const val IDX_RRULE = 10
+    const val IDX_RDATE = 11
+}
+
+/**
+ * The master/one-off Events row of an event about to be moved to another
+ * calendar, read for a verbatim re-insert (see [MasterEventSnapshot]). Carries
+ * the full recurrence skeleton (RRULE/DURATION, RDATE/EXDATE) so the moved copy
+ * generates the same instances, and `UID_2445` so identity survives the move.
+ */
+internal object MoveMasterProjection {
+    val COLUMNS: Array<String> = arrayOf(
+        CalendarContract.Events.UID_2445,
+        CalendarContract.Events.TITLE,
+        CalendarContract.Events.DTSTART,
+        CalendarContract.Events.DTEND,
+        CalendarContract.Events.DURATION,
+        CalendarContract.Events.RRULE,
+        CalendarContract.Events.RDATE,
+        CalendarContract.Events.EXDATE,
+        CalendarContract.Events.EVENT_TIMEZONE,
+        CalendarContract.Events.ALL_DAY,
+        CalendarContract.Events.AVAILABILITY,
+        CalendarContract.Events.ACCESS_LEVEL,
+        CalendarContract.Events.STATUS,
+        CalendarContract.Events.EVENT_LOCATION,
+        CalendarContract.Events.DESCRIPTION,
+    )
+
+    const val IDX_UID = 0
+    const val IDX_TITLE = 1
+    const val IDX_DTSTART = 2
+    const val IDX_DTEND = 3
+    const val IDX_DURATION = 4
+    const val IDX_RRULE = 5
+    const val IDX_RDATE = 6
+    const val IDX_EXDATE = 7
+    const val IDX_EVENT_TIMEZONE = 8
+    const val IDX_ALL_DAY = 9
+    const val IDX_AVAILABILITY = 10
+    const val IDX_ACCESS_LEVEL = 11
+    const val IDX_STATUS = 12
+    const val IDX_LOCATION = 13
+    const val IDX_DESCRIPTION = 14
+}
+
+/**
+ * The exception rows of a recurring series (`ORIGINAL_ID` = the series), read to
+ * replay them against a moved copy (see [ExceptionRowSnapshot]). Both modified
+ * occurrences and cancellations (`STATUS_CANCELED`) are read; the query filters
+ * `DELETED = 0` so provider tombstones aren't replayed.
+ */
+internal object ExceptionProjection {
+    val COLUMNS: Array<String> = arrayOf(
+        CalendarContract.Events._ID,
+        CalendarContract.Events.ORIGINAL_INSTANCE_TIME,
+        CalendarContract.Events.STATUS,
+        CalendarContract.Events.TITLE,
+        CalendarContract.Events.ALL_DAY,
+        CalendarContract.Events.DTSTART,
+        CalendarContract.Events.DTEND,
+        CalendarContract.Events.DURATION,
+        CalendarContract.Events.EVENT_TIMEZONE,
+        CalendarContract.Events.AVAILABILITY,
+        CalendarContract.Events.ACCESS_LEVEL,
+        CalendarContract.Events.EVENT_LOCATION,
+        CalendarContract.Events.DESCRIPTION,
+    )
+
+    const val IDX_ID = 0
+    const val IDX_ORIGINAL_INSTANCE_TIME = 1
+    const val IDX_STATUS = 2
+    const val IDX_TITLE = 3
+    const val IDX_ALL_DAY = 4
+    const val IDX_DTSTART = 5
+    const val IDX_DTEND = 6
+    const val IDX_DURATION = 7
+    const val IDX_EVENT_TIMEZONE = 8
+    const val IDX_AVAILABILITY = 9
+    const val IDX_ACCESS_LEVEL = 10
+    const val IDX_LOCATION = 11
+    const val IDX_DESCRIPTION = 12
 }
 
 internal object AttendeeProjection {

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/SearchMapper.kt

@@ -0,0 +1,44 @@
+package de.jeanlucmakiola.calendula.data.calendar
+
+import de.jeanlucmakiola.floret.time.toKotlinInstantFromEpochMillis
+import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.ics.parseRfc2445DurationMillis
+
+/**
+ * Map an Events-table row (a search hit) to an [EventInstance]. Unlike the
+ * Instances query this reads the series master, so there is no instance id (the
+ * event id stands in as the list key) and recurring rows carry DURATION instead
+ * of DTEND — reconstruct the end the same way the `.ics` export does.
+ */
+internal fun ColumnReader.toSearchResult(): EventInstance? {
+    // A pre-1970 series anchor is a legitimately negative epoch-millis DTSTART
+    // (see EventDetailMapper / issue #34); drop only a genuinely absent one, so
+    // long-running birthdays/anniversaries still surface in search.
+    if (isNull(SearchProjection.IDX_DTSTART)) return null
+    val dtStart = getLong(SearchProjection.IDX_DTSTART)
+    val end = when {
+        !isNull(SearchProjection.IDX_DTEND) -> getLong(SearchProjection.IDX_DTEND)
+        else -> dtStart + parseRfc2445DurationMillis(getString(SearchProjection.IDX_DURATION))
+    }.coerceAtLeast(dtStart)
+
+    val rawTitle = getString(SearchProjection.IDX_TITLE)
+    val title = if (rawTitle.isNullOrEmpty()) Fallbacks.UNTITLED_EVENT else rawTitle
+    val color = if (isNull(SearchProjection.IDX_EVENT_COLOR)) {
+        getInt(SearchProjection.IDX_CALENDAR_COLOR)
+    } else {
+        getInt(SearchProjection.IDX_EVENT_COLOR)
+    }
+    val eventId = getLong(SearchProjection.IDX_ID)
+
+    return EventInstance(
+        instanceId = eventId,
+        eventId = eventId,
+        calendarId = getLong(SearchProjection.IDX_CALENDAR_ID),
+        title = title,
+        start = dtStart.toKotlinInstantFromEpochMillis(),
+        end = end.toKotlinInstantFromEpochMillis(),
+        isAllDay = getInt(SearchProjection.IDX_ALL_DAY) != 0,
+        color = color,
+        location = getString(SearchProjection.IDX_LOCATION),
+    )
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/calendar/TimeBridge.kt

@@ -1,7 +0,0 @@
-package de.jeanlucmakiola.calendula.data.calendar
-
-import kotlin.time.Instant
-
-fun Long.toKotlinInstantFromEpochMillis(): Instant = Instant.fromEpochMilliseconds(this)
-
-fun Instant.toEpochMillis(): Long = toEpochMilliseconds()

app/src/main/java/de/jeanlucmakiola/calendula/data/contacts/AndroidSpecialDatesCalendarSpec.kt

@@ -0,0 +1,42 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.content.Context
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.calendar.CalendarColorPalette
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Resolves the localized calendar names/templates and per-type colours the
+ * mirror creates its calendars with. The colours are picked from the shared
+ * palette so managed calendars look native alongside user calendars.
+ */
+@Singleton
+class AndroidSpecialDatesCalendarSpec @Inject constructor(
+    @ApplicationContext private val context: Context,
+) : SpecialDatesCalendarSpec {
+
+    override fun displayName(type: SpecialDateType): String = context.getString(
+        when (type) {
+            SpecialDateType.Birthday -> R.string.special_dates_calendar_birthday
+            SpecialDateType.Anniversary -> R.string.special_dates_calendar_anniversary
+            SpecialDateType.Custom -> R.string.special_dates_calendar_custom
+        },
+    )
+
+    override fun defaultTitleTemplate(type: SpecialDateType): String = context.getString(
+        when (type) {
+            SpecialDateType.Birthday -> R.string.special_dates_default_title_birthday
+            SpecialDateType.Anniversary -> R.string.special_dates_default_title_anniversary
+            SpecialDateType.Custom -> R.string.special_dates_default_title_custom
+        },
+    )
+
+    override fun color(type: SpecialDateType): Int = when (type) {
+        SpecialDateType.Birthday -> CalendarColorPalette.Purple
+        SpecialDateType.Anniversary -> CalendarColorPalette.Red
+        SpecialDateType.Custom -> CalendarColorPalette.Blue
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/contacts/ContactSpecialDatesDataSource.kt

@@ -0,0 +1,105 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.provider.ContactsContract
+import android.provider.ContactsContract.CommonDataKinds.Event
+import android.util.Log
+import androidx.core.content.ContextCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.domain.contacts.ContactSpecialDate
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import de.jeanlucmakiola.calendula.domain.contacts.managedUid
+import de.jeanlucmakiola.calendula.domain.contacts.parseContactEventDate
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Reads the dated `Event` rows (birthdays, anniversaries, custom dates) of the
+ * device's contacts. Read-only and offline — the one-way source for the
+ * special-dates mirror. Requires `READ_CONTACTS`; returns an empty list when
+ * the permission is absent so the sync can degrade to a stalled state rather
+ * than crash.
+ */
+interface ContactSpecialDatesDataSource {
+    fun hasPermission(): Boolean
+
+    /** All usable contact special-dates, deduplicated per contact and type. */
+    fun readSpecialDates(): List<ContactSpecialDate>
+}
+
+/** Whether `READ_CONTACTS` is granted — the gate for every contacts read. */
+fun Context.hasContactsPermission(): Boolean =
+    ContextCompat.checkSelfPermission(this, Manifest.permission.READ_CONTACTS) ==
+        PackageManager.PERMISSION_GRANTED
+
+/** Map a `ContactsContract` event `TYPE` to our calendar bucket. */
+internal fun specialDateTypeForRawEventType(type: Int): SpecialDateType = when (type) {
+    Event.TYPE_BIRTHDAY -> SpecialDateType.Birthday
+    Event.TYPE_ANNIVERSARY -> SpecialDateType.Anniversary
+    else -> SpecialDateType.Custom
+}
+
+@Singleton
+class AndroidContactSpecialDatesDataSource @Inject constructor(
+    @ApplicationContext private val context: Context,
+) : ContactSpecialDatesDataSource {
+
+    override fun hasPermission(): Boolean = context.hasContactsPermission()
+
+    override fun readSpecialDates(): List<ContactSpecialDate> {
+        if (!hasPermission()) return emptyList()
+        val resolver = context.contentResolver
+        // A contact can carry the same date more than once (multiple raw contacts
+        // under one aggregate); dedup on the mirror's reconciliation key so exact
+        // duplicates collapse while genuinely distinct dates (two custom events on
+        // one contact) are all kept. Ordered by Data._ID so which of two truly
+        // conflicting rows wins is stable across syncs (no event ping-pong).
+        val seen = HashSet<String>()
+        val result = ArrayList<ContactSpecialDate>()
+        runCatching {
+            resolver.query(
+                ContactsContract.Data.CONTENT_URI,
+                PROJECTION,
+                "${ContactsContract.Data.MIMETYPE} = ?",
+                arrayOf(Event.CONTENT_ITEM_TYPE),
+                "${ContactsContract.Data._ID} ASC",
+            )?.use { c ->
+                val idxDate = c.getColumnIndexOrThrow(Event.START_DATE)
+                val idxType = c.getColumnIndexOrThrow(Event.TYPE)
+                val idxLabel = c.getColumnIndexOrThrow(Event.LABEL)
+                val idxLookup = c.getColumnIndexOrThrow(ContactsContract.Data.LOOKUP_KEY)
+                val idxName = c.getColumnIndexOrThrow(ContactsContract.Data.DISPLAY_NAME_PRIMARY)
+                while (c.moveToNext()) {
+                    val lookup = c.getString(idxLookup)?.takeIf { it.isNotEmpty() } ?: continue
+                    val parts = parseContactEventDate(c.getString(idxDate)) ?: continue
+                    val type = specialDateTypeForRawEventType(c.getInt(idxType))
+                    val date = ContactSpecialDate(
+                        lookupKey = lookup,
+                        displayName = c.getString(idxName)?.trim().orEmpty(),
+                        type = type,
+                        month = parts.month,
+                        day = parts.day,
+                        year = parts.year,
+                        label = c.getString(idxLabel)?.takeIf { it.isNotBlank() },
+                    )
+                    if (seen.add(date.managedUid())) result += date
+                }
+            }
+        }.onFailure { Log.w(TAG, "Reading contact special-dates failed", it) }
+        return result
+    }
+
+    private companion object {
+        const val TAG = "ContactSpecialDates"
+
+        val PROJECTION = arrayOf(
+            ContactsContract.Data.LOOKUP_KEY,
+            ContactsContract.Data.DISPLAY_NAME_PRIMARY,
+            Event.START_DATE,
+            Event.TYPE,
+            Event.LABEL,
+        )
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/contacts/SpecialDatesScheduler.kt

@@ -0,0 +1,135 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.content.Context
+import android.util.Log
+import androidx.work.CoroutineWorker
+import androidx.work.Data
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.ExistingWorkPolicy
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import dagger.hilt.EntryPoint
+import dagger.hilt.InstallIn
+import dagger.hilt.android.EntryPointAccessors
+import dagger.hilt.components.SingletonComponent
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.data.prefs.SpecialDatesStalledReason
+import kotlinx.coroutines.flow.first
+import java.util.concurrent.TimeUnit
+
+/**
+ * Schedules the contact special-dates mirror. Birthdays change rarely, so this
+ * is deliberately cheap: a **daily** periodic reconcile, plus an immediate run
+ * on enable / "Sync now" and a debounced one when the app is foregrounded. No
+ * ContentObserver — it would need the process alive and buys almost nothing for
+ * once-a-year events. Everything stays offline (local contacts → local calendar).
+ */
+object SpecialDatesScheduler {
+
+    private const val WORK_NAME = "special-dates-sync"
+    private const val WORK_NAME_NOW = "special-dates-sync-now"
+    private const val WORK_NAME_FOREGROUND = "special-dates-sync-foreground"
+    private const val KEY_FOREGROUND = "foreground"
+
+    /** Enqueue (or cancel) the daily periodic reconcile to match [enabled]. */
+    fun apply(context: Context, enabled: Boolean) {
+        val workManager = WorkManager.getInstance(context)
+        if (!enabled) {
+            workManager.cancelUniqueWork(WORK_NAME)
+            workManager.cancelUniqueWork(WORK_NAME_NOW)
+            workManager.cancelUniqueWork(WORK_NAME_FOREGROUND)
+            return
+        }
+        val request = PeriodicWorkRequestBuilder<SpecialDatesSyncWorker>(1, TimeUnit.DAYS)
+            // Delay the first periodic run so it never overlaps an immediate run.
+            .setInitialDelay(1, TimeUnit.DAYS)
+            .build()
+        workManager.enqueueUniquePeriodicWork(WORK_NAME, ExistingPeriodicWorkPolicy.UPDATE, request)
+    }
+
+    /**
+     * Run one reconcile immediately. [foreground] runs (the app resuming) are
+     * debounced inside the worker and use their own work name, so a frequent
+     * foreground resync can never REPLACE — and swallow — a pending enable /
+     * "Sync now" run, which always syncs. The engine serializes the two if they
+     * overlap.
+     */
+    fun runNow(context: Context, foreground: Boolean = false) {
+        val request = OneTimeWorkRequestBuilder<SpecialDatesSyncWorker>()
+            .setInputData(Data.Builder().putBoolean(KEY_FOREGROUND, foreground).build())
+            .build()
+        val name = if (foreground) WORK_NAME_FOREGROUND else WORK_NAME_NOW
+        WorkManager.getInstance(context)
+            .enqueueUniqueWork(name, ExistingWorkPolicy.REPLACE, request)
+    }
+
+    internal const val INPUT_FOREGROUND = KEY_FOREGROUND
+}
+
+/**
+ * Runs the [SpecialDatesSyncEngine]. Pulls its collaborators through a Hilt
+ * [EntryPoint] so it works under WorkManager's default worker factory. Records
+ * the run for the settings status line; a missing permission parks the feature
+ * in a stalled state (surfaced in settings) rather than retrying forever.
+ */
+class SpecialDatesSyncWorker(
+    appContext: Context,
+    params: WorkerParameters,
+) : CoroutineWorker(appContext, params) {
+
+    @EntryPoint
+    @InstallIn(SingletonComponent::class)
+    interface Deps {
+        fun settingsPrefs(): SettingsPrefs
+        fun syncEngine(): SpecialDatesSyncEngine
+    }
+
+    override suspend fun doWork(): Result {
+        val deps = EntryPointAccessors.fromApplication(applicationContext, Deps::class.java)
+        val prefs = deps.settingsPrefs()
+
+        val now = System.currentTimeMillis()
+        // A foreground resume can fire often — skip if we synced recently.
+        val foreground = inputData.getBoolean(SpecialDatesScheduler.INPUT_FOREGROUND, false)
+        if (foreground && now - prefs.specialDatesLastForegroundSync.first() < FOREGROUND_DEBOUNCE_MILLIS) {
+            return Result.success()
+        }
+
+        return try {
+            when (val result = deps.syncEngine().sync()) {
+                // The engine re-checks the toggle, so already-queued work never
+                // revives a disabled feature; don't record a run either.
+                SpecialDatesSyncResult.Disabled -> return Result.success()
+                else -> {
+                    val stalled = if (result == SpecialDatesSyncResult.PermissionMissing) {
+                        SpecialDatesStalledReason.PermissionRevoked
+                    } else {
+                        null
+                    }
+                    prefs.recordSpecialDatesRun(now, stalled)
+                }
+            }
+            if (foreground) prefs.setSpecialDatesLastForegroundSync(now)
+            Result.success()
+        } catch (e: SecurityException) {
+            // A revoked calendar/contacts permission won't fix itself on retry —
+            // park the feature in a stalled state (surfaced in settings) instead
+            // of retrying with backoff forever.
+            Log.w(TAG, "Special-dates sync lacks a required permission", e)
+            prefs.recordSpecialDatesRun(now, SpecialDatesStalledReason.PermissionRevoked)
+            Result.success()
+        } catch (e: Exception) {
+            Log.w(TAG, "Special-dates sync failed", e)
+            Result.retry()
+        }
+    }
+
+    companion object {
+        private const val TAG = "SpecialDatesSync"
+
+        /** Skip a foreground-triggered sync if one ran within this window (4h). */
+        private const val FOREGROUND_DEBOUNCE_MILLIS = 4L * 60 * 60 * 1000
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/contacts/SpecialDatesSyncEngine.kt

@@ -0,0 +1,304 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.provider.CalendarContract
+import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
+import de.jeanlucmakiola.calendula.data.calendar.ManagedEventRow
+import de.jeanlucmakiola.calendula.data.calendar.toWriteTimes
+import de.jeanlucmakiola.floret.reminders.ReminderOverride
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.domain.Availability
+import de.jeanlucmakiola.calendula.domain.EventForm
+import de.jeanlucmakiola.calendula.domain.RecurrenceFreq
+import de.jeanlucmakiola.calendula.domain.SimpleRecurrence
+import de.jeanlucmakiola.calendula.domain.contacts.ContactSpecialDate
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import de.jeanlucmakiola.calendula.domain.contacts.anchorDate
+import de.jeanlucmakiola.calendula.domain.contacts.managedUid
+import de.jeanlucmakiola.calendula.domain.contacts.renderSpecialDateTitle
+import de.jeanlucmakiola.calendula.domain.toRRule
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.LocalTime
+import java.time.ZoneId
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/** Outcome of one mirror reconcile, reported back so the worker can record status. */
+enum class SpecialDatesSyncResult { Success, Disabled, PermissionMissing }
+
+/**
+ * Localized, per-type presentation the engine needs but can't derive purely
+ * (calendar display name, colour, and the default title template). Kept behind
+ * an interface so the engine's diff stays unit-testable without Android
+ * resources.
+ */
+interface SpecialDatesCalendarSpec {
+    fun displayName(type: SpecialDateType): String
+    fun color(type: SpecialDateType): Int
+    fun defaultTitleTemplate(type: SpecialDateType): String
+}
+
+/**
+ * The stored title template for [type], falling back to the localized default
+ * when blank/absent — the one resolution rule shared by the sync (what gets
+ * written) and the settings editor (what gets shown).
+ */
+fun SpecialDatesCalendarSpec.resolveTitleTemplate(
+    type: SpecialDateType,
+    stored: Map<SpecialDateType, String>,
+): String = stored[type]?.takeIf { it.isNotBlank() } ?: defaultTitleTemplate(type)
+
+/**
+ * Mirrors contact birthdays/anniversaries/custom dates into local calendars,
+ * one per type. Every reconcile is an idempotent diff keyed on the deterministic
+ * `UID_2445` ([managedEventUid]): new contacts are inserted (seeding user-owned
+ * fields once), changed contacts get a *targeted* managed-column update, and
+ * removed contacts are deleted — so a user's own edits (reminders, location,
+ * notes) are never clobbered. See docs/design/contact-special-dates.md.
+ */
+@Singleton
+class SpecialDatesSyncEngine @Inject constructor(
+    private val contacts: ContactSpecialDatesDataSource,
+    private val calendars: CalendarDataSource,
+    private val prefs: SettingsPrefs,
+    private val spec: SpecialDatesCalendarSpec,
+) {
+
+    // Serializes calendar-lifecycle work: two overlapping syncs (the daily job
+    // racing a "Sync now"/foreground run) would each see no managed calendar and
+    // both create one; a teardown racing an in-flight sync would delete calendars
+    // the sync then recreates. Holding this for the whole of sync()/teardown()
+    // makes those check-then-act sequences atomic, and — because sync() re-reads
+    // the enabled flag inside the lock — a teardown always wins the race.
+    private val lifecycleMutex = Mutex()
+
+    /**
+     * Reconcile every enabled type against the device's contacts. Returns why it
+     * stopped early (disabled / permission gone) or [SpecialDatesSyncResult.Success].
+     */
+    suspend fun sync(): SpecialDatesSyncResult = lifecycleMutex.withLock {
+        if (!prefs.specialDatesEnabled.first()) return SpecialDatesSyncResult.Disabled
+        if (!contacts.hasPermission()) return SpecialDatesSyncResult.PermissionMissing
+
+        val enabledTypes = prefs.specialDatesTypes.first()
+        val calendarByType = reconcileCalendars(enabledTypes)
+
+        val desiredByType = contacts.readSpecialDates().groupBy { it.type }
+        val reminderCtx = readReminderContext()
+        val templates = prefs.specialDatesTitleTemplates.first()
+        val showYear = prefs.specialDatesShowYear.first()
+
+        calendarByType.forEach { (type, calendarId) ->
+            val template = spec.resolveTitleTemplate(type, templates)
+            syncType(
+                calendarId = calendarId,
+                type = type,
+                contactsOfType = desiredByType[type].orEmpty(),
+                template = template,
+                showYear = showYear,
+                reminderCtx = reminderCtx,
+            )
+        }
+        SpecialDatesSyncResult.Success
+    }
+
+    /**
+     * Set the reminder default for a type's managed calendar and apply it to
+     * **all** its existing events too (not just future ones) — for managed
+     * calendars the reminder is a calendar-level setting. Persists the per-calendar
+     * all-day override so new events keep matching. No-op if the calendar for
+     * [type] doesn't exist yet.
+     */
+    suspend fun applyReminders(type: SpecialDateType, override: ReminderOverride) {
+        val calendarId = prefs.specialDatesCalendars.first()[type] ?: return
+        prefs.setCalendarAllDayReminderOverride(calendarId, override)
+        val minutes = when (override) {
+            ReminderOverride.Inherit -> prefs.defaultAllDayReminderMinutes.first()
+            ReminderOverride.None -> emptyList()
+            is ReminderOverride.Minutes -> override.minutes
+        }
+        calendars.applyManagedCalendarReminders(
+            calendarId = calendarId,
+            allDayReminderTimeMinutes = prefs.allDayReminderTimeMinutes.first(),
+            minutes = minutes,
+        )
+    }
+
+    /** Delete every managed calendar and forget its id — used when the feature is turned off. */
+    suspend fun teardown() = lifecycleMutex.withLock {
+        calendars.findManagedCalendars().forEach { calendars.deleteCalendar(it.id) }
+        SpecialDateType.entries.forEach { prefs.setSpecialDatesCalendarId(it, null) }
+    }
+
+    /**
+     * Ensure each enabled type has exactly one managed calendar (adopting an
+     * existing one, or the stored id if it still exists, else creating one) and
+     * that disabled types have none. Returns the calendar id per enabled type.
+     */
+    private suspend fun reconcileCalendars(enabledTypes: Set<SpecialDateType>): Map<SpecialDateType, Long> {
+        val foundByType = calendars.findManagedCalendars()
+            .groupBy({ it.type }, { it.id })
+            .mapValues { it.value.first() }
+        val stored = prefs.specialDatesCalendars.first()
+        val result = LinkedHashMap<SpecialDateType, Long>()
+        for (type in SpecialDateType.entries) {
+            // A stored id counts only if the calendar still exists (the user may
+            // have deleted it in system settings); otherwise adopt a found one.
+            val existingId = stored[type]?.takeIf { id -> foundByType.containsValue(id) }
+                ?: foundByType[type]
+            if (type in enabledTypes) {
+                val id = existingId ?: createCalendar(type)
+                if (stored[type] != id) prefs.setSpecialDatesCalendarId(type, id)
+                result[type] = id
+            } else {
+                if (existingId != null) calendars.deleteCalendar(existingId)
+                if (stored.containsKey(type)) prefs.setSpecialDatesCalendarId(type, null)
+            }
+        }
+        return result
+    }
+
+    private suspend fun createCalendar(type: SpecialDateType): Long {
+        // reconcileCalendars persists the id — the single place ids are recorded.
+        val id = calendars.createManagedCalendar(spec.displayName(type), spec.color(type), type)
+        // Seed a useful all-day reminder default (on the day + a week before), so
+        // birthdays get lead time out of the box. Per-calendar, user-adjustable —
+        // only set when the user hasn't already configured this calendar.
+        if (!prefs.perCalendarAllDayReminderOverride.first().containsKey(id)) {
+            prefs.setCalendarAllDayReminderOverride(
+                id,
+                ReminderOverride.Minutes(DEFAULT_REMINDER_MINUTES),
+            )
+        }
+        return id
+    }
+
+    private suspend fun syncType(
+        calendarId: Long,
+        type: SpecialDateType,
+        contactsOfType: List<ContactSpecialDate>,
+        template: String,
+        showYear: Boolean,
+        reminderCtx: ReminderContext,
+    ) {
+        val built = contactsOfType.map { sd ->
+            buildManagedEvent(calendarId, type, sd, template, showYear, reminderCtx)
+        }
+        val diff = diffManagedEvents(built.map { it.desired }, calendars.queryManagedEvents(calendarId))
+        val formByUid = built.associate { it.desired.uid to it.form }
+        diff.insertUids.forEach { uid ->
+            calendars.insertManagedEvent(formByUid.getValue(uid), uid, reminderCtx.allDayTimeMinutes)
+        }
+        diff.updates.forEach { calendars.updateManagedFields(it.eventId, it.columns) }
+        diff.deleteEventIds.forEach { calendars.deleteEvent(it) }
+    }
+
+    private fun buildManagedEvent(
+        calendarId: Long,
+        type: SpecialDateType,
+        sd: ContactSpecialDate,
+        template: String,
+        showYear: Boolean,
+        reminderCtx: ReminderContext,
+    ): BuiltManagedEvent {
+        val anchor = sd.anchorDate()
+        val start = LocalDateTime(anchor, LocalTime(0, 0))
+        // The source year is static and correct on every occurrence (unlike age).
+        val year = if (showYear) sd.year else null
+        val title = renderSpecialDateTitle(template, sd.displayName, year)
+        val form = EventForm(
+            calendarId = calendarId,
+            title = title,
+            isAllDay = true,
+            start = start,
+            end = start,
+            reminders = reminderCtx.resolveAllDay(calendarId),
+            availability = Availability.Free,
+            rrule = YEARLY_RRULE,
+        )
+        val dtStartMillis = form.toWriteTimes(ZoneId.systemDefault()).dtStartMillis
+        return BuiltManagedEvent(
+            desired = ManagedEventDesired(
+                uid = sd.managedUid(),
+                title = title,
+                dtStartMillis = dtStartMillis,
+                rrule = YEARLY_RRULE,
+            ),
+            form = form,
+        )
+    }
+
+    // Managed events are always all-day, so only the all-day defaults apply.
+    private suspend fun readReminderContext(): ReminderContext = ReminderContext(
+        allDayGlobal = prefs.defaultAllDayReminderMinutes.first(),
+        allDayOverrides = prefs.perCalendarAllDayReminderOverride.first(),
+        allDayTimeMinutes = prefs.allDayReminderTimeMinutes.first(),
+    )
+
+    private data class ReminderContext(
+        val allDayGlobal: List<Int>,
+        val allDayOverrides: Map<Long, List<Int>>,
+        val allDayTimeMinutes: Int,
+    ) {
+        /** Same semantics as `resolveDefaultReminder`: present-empty = explicit none. */
+        fun resolveAllDay(calendarId: Long): List<Int> =
+            allDayOverrides[calendarId] ?: allDayGlobal
+    }
+
+    private data class BuiltManagedEvent(val desired: ManagedEventDesired, val form: EventForm)
+
+    private companion object {
+        /** "On the day" (0) + one week before (7 days), as all-day lead minutes. */
+        val DEFAULT_REMINDER_MINUTES = listOf(0, 7 * 24 * 60)
+        val YEARLY_RRULE = SimpleRecurrence(freq = RecurrenceFreq.Yearly).toRRule()
+    }
+}
+
+/** The managed columns of a desired event, compared against the existing row. */
+internal data class ManagedEventDesired(
+    val uid: String,
+    val title: String,
+    val dtStartMillis: Long,
+    val rrule: String?,
+)
+
+internal data class ManagedFieldUpdate(val eventId: Long, val columns: Map<String, Any?>)
+
+internal data class ManagedDiff(
+    val insertUids: List<String>,
+    val updates: List<ManagedFieldUpdate>,
+    val deleteEventIds: List<Long>,
+)
+
+/**
+ * The idempotent diff at the heart of the mirror, keyed on `UID_2445`:
+ * desired-not-existing → insert, existing-not-desired → delete, and for events
+ * in both only the *changed* managed columns (title/dtstart/rrule) are emitted —
+ * so a re-run with no contact changes produces nothing, and a managed update
+ * never touches user-owned columns or reminder rows. Pure, so it's unit-tested.
+ */
+internal fun diffManagedEvents(
+    desired: List<ManagedEventDesired>,
+    existing: List<ManagedEventRow>,
+): ManagedDiff {
+    val desiredByUid = desired.associateBy { it.uid }
+    val existingByUid = existing.associateBy { it.uid }
+    val insertUids = desired.filter { it.uid !in existingByUid }.map { it.uid }
+    val deleteEventIds = existing.filter { it.uid !in desiredByUid }.map { it.eventId }
+    val updates = buildList {
+        for (d in desired) {
+            val row = existingByUid[d.uid] ?: continue
+            val columns = buildMap<String, Any?> {
+                if (row.title != d.title) put(CalendarContract.Events.TITLE, d.title)
+                if (row.dtStartMillis != d.dtStartMillis) {
+                    put(CalendarContract.Events.DTSTART, d.dtStartMillis)
+                }
+                if (row.rrule != d.rrule) put(CalendarContract.Events.RRULE, d.rrule)
+            }
+            if (columns.isNotEmpty()) add(ManagedFieldUpdate(row.eventId, columns))
+        }
+    }
+    return ManagedDiff(insertUids, updates, deleteEventIds)
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/di/DataModule.kt

@@ -14,6 +14,12 @@ import de.jeanlucmakiola.calendula.data.calendar.AndroidCalendarDataSource
 import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
 import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository
 import de.jeanlucmakiola.calendula.data.calendar.CalendarRepositoryImpl
+import de.jeanlucmakiola.calendula.data.contacts.AndroidContactSpecialDatesDataSource
+import de.jeanlucmakiola.calendula.data.contacts.AndroidSpecialDatesCalendarSpec
+import de.jeanlucmakiola.calendula.data.contacts.ContactSpecialDatesDataSource
+import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesCalendarSpec
+import de.jeanlucmakiola.calendula.data.reminders.ProviderReminderInstanceSource
+import de.jeanlucmakiola.calendula.data.reminders.ReminderInstanceSource
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.Dispatchers
 import javax.inject.Singleton
@@ -37,6 +43,24 @@ abstract class DataBindModule {
     abstract fun bindCalendarRepository(
         impl: CalendarRepositoryImpl,
     ): CalendarRepository
+
+    @Binds
+    @Singleton
+    abstract fun bindReminderInstanceSource(
+        impl: ProviderReminderInstanceSource,
+    ): ReminderInstanceSource
+
+    @Binds
+    @Singleton
+    abstract fun bindContactSpecialDatesDataSource(
+        impl: AndroidContactSpecialDatesDataSource,
+    ): ContactSpecialDatesDataSource
+
+    @Binds
+    @Singleton
+    abstract fun bindSpecialDatesCalendarSpec(
+        impl: AndroidSpecialDatesCalendarSpec,
+    ): SpecialDatesCalendarSpec
 }
 
 @Module

app/src/main/java/de/jeanlucmakiola/calendula/data/fonts/CustomFontStore.kt

@@ -0,0 +1,57 @@
+package de.jeanlucmakiola.calendula.data.fonts
+
+import android.content.Context
+import android.net.Uri
+import de.jeanlucmakiola.calendula.domain.FontRole
+import java.io.File
+import java.util.Locale
+import android.graphics.fonts.Font as PlatformFont
+
+/**
+ * Storage for user-loaded custom fonts (issue #19). A font a user picks via the
+ * system file picker is copied into the app's private storage — one file per
+ * [FontRole] — so the selection survives even if the original is later moved or
+ * deleted, and never leaves the app. The chosen file is validated as a real font
+ * before it replaces the previous one, so a bad pick can't wedge the app-wide
+ * typography.
+ */
+object CustomFontStore {
+
+    private fun dir(context: Context): File = File(context.filesDir, "fonts")
+
+    /** The stored font file for [role] (may not exist yet). */
+    fun file(context: Context, role: FontRole): File =
+        File(dir(context), "${role.name.lowercase(Locale.ROOT)}.ttf")
+
+    fun exists(context: Context, role: FontRole): Boolean =
+        file(context, role).let { it.exists() && it.length() > 0 }
+
+    /**
+     * Copy [uri] into per-role storage, first validating that it parses as a
+     * font. Returns true on success; on any failure the previous file is left
+     * untouched and false is returned (the caller keeps the old selection).
+     */
+    fun import(context: Context, role: FontRole, uri: Uri): Boolean {
+        val target = file(context, role)
+        target.parentFile?.mkdirs()
+        val tmp = File(target.parentFile, "${role.name.lowercase(Locale.ROOT)}.tmp")
+        return try {
+            context.contentResolver.openInputStream(uri)?.use { input ->
+                tmp.outputStream().use { output -> input.copyTo(output) }
+            } ?: return false
+            // Font.Builder throws IOException for anything that isn't a valid
+            // font file (API 29+, which is our minSdk) — a cheap, reliable check.
+            PlatformFont.Builder(tmp).build()
+            if (target.exists() && !target.delete()) return false
+            tmp.renameTo(target)
+        } catch (_: Exception) {
+            tmp.delete()
+            false
+        }
+    }
+
+    /** Forget the custom font for [role] (used when switching away from it). */
+    fun clear(context: Context, role: FontRole) {
+        file(context, role).delete()
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/ics/IcsExporter.kt

@@ -0,0 +1,78 @@
+package de.jeanlucmakiola.calendula.data.ics
+
+import android.content.Context
+import android.net.Uri
+import androidx.core.content.FileProvider
+import androidx.documentfile.provider.DocumentFile
+import dagger.hilt.android.qualifiers.ApplicationContext
+import java.io.File
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The Android IO edge of `.ics` export: writes a serialised calendar to a
+ * SAF document (whole-calendar backup) or stages it in a cache file behind a
+ * `FileProvider` content Uri (single-event share). The serialisation itself is
+ * the pure `domain.ics.IcsWriter`; this class only moves bytes.
+ */
+@Singleton
+class IcsExporter @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+
+    /** Write [content] to the SAF document at [uri] as UTF-8. Throws on failure. */
+    fun writeDocument(uri: Uri, content: String) {
+        context.contentResolver.openOutputStream(uri)?.use { out ->
+            out.write(content.toByteArray(Charsets.UTF_8))
+            // Only the scheme — the full Uri can embed the user's chosen filename.
+        } ?: throw IOException("Could not open output stream for export (scheme=${uri.scheme})")
+    }
+
+    /**
+     * Write [content] to [fileName] inside the persisted SAF tree [folder],
+     * overwriting it if it already exists (the automatic-backup destination).
+     * Requires a persisted write grant on [folder]. Throws on failure.
+     */
+    fun writeToFolder(folder: Uri, fileName: String, content: String) {
+        val dir = DocumentFile.fromTreeUri(context, folder)
+            ?: throw IOException("Backup folder is not accessible")
+        if (!dir.exists() || !dir.canWrite()) {
+            throw IOException("Backup folder is missing or not writable")
+        }
+        // Reuse the canonical file if present and clean up any "name (1).ics"
+        // duplicates SAF may have created if two runs ever raced — so we always
+        // converge on a single overwritten file.
+        val base = fileName.substringBeforeLast('.')
+        val ext = fileName.substringAfterLast('.', "")
+        var target: DocumentFile? = null
+        for (child in dir.listFiles()) {
+            val name = child.name ?: continue
+            when {
+                name == fileName -> target = child
+                name.startsWith("$base (") && name.endsWith(".$ext") -> child.delete()
+            }
+        }
+        val file = target
+            ?: dir.createFile(MIME_CALENDAR, fileName)
+            ?: throw IOException("Could not create backup file in the chosen folder")
+        writeDocument(file.uri, content)
+    }
+
+    /**
+     * Stage [content] in a private cache file and return a shareable content
+     * Uri for an `ACTION_SEND`. [fileName] is the suggested `.ics` name shown to
+     * the receiving app. The authority mirrors the manifest's `FileProvider`.
+     */
+    fun stageShareFile(fileName: String, content: String): Uri {
+        val dir = File(context.cacheDir, SHARE_DIR).apply { mkdirs() }
+        val file = File(dir, fileName)
+        file.writeText(content, Charsets.UTF_8)
+        return FileProvider.getUriForFile(context, "${context.packageName}.fileprovider", file)
+    }
+
+    private companion object {
+        const val SHARE_DIR = "shared_ics"
+        const val MIME_CALENDAR = "text/calendar"
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/ics/IcsImporter.kt

@@ -0,0 +1,21 @@
+package de.jeanlucmakiola.calendula.data.ics
+
+import android.content.Context
+import android.net.Uri
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Android IO edge of `.ics` import: reads the text of a received/opened
+ * document [Uri]. Parsing is the pure `domain.ics.IcsParser`; this class only
+ * pulls bytes off the ContentResolver. Returns null on any read failure.
+ */
+@Singleton
+class IcsImporter @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+    fun readText(uri: Uri): String? = runCatching {
+        context.contentResolver.openInputStream(uri)?.use { it.readBytes().toString(Charsets.UTF_8) }
+    }.getOrNull()
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/CalendarPrefs.kt

@@ -1,18 +1,25 @@
 package de.jeanlucmakiola.calendula.data.prefs
 
 import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.MutablePreferences
 import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.booleanPreferencesKey
 import androidx.datastore.preferences.core.edit
 import androidx.datastore.preferences.core.longPreferencesKey
 import androidx.datastore.preferences.core.stringPreferencesKey
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.map
 import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * App-side preference for "calendars the user has hidden in this app",
- * separate from the system's per-calendar VISIBLE flag.
+ * App-side calendar preferences. [hiddenCalendarIds] is the drawer's filter
+ * sheet — a purely in-app declutter that deliberately does *not* suppress
+ * reminders. Switching a calendar off entirely is the system's
+ * `Calendars.VISIBLE` flag, written straight to the provider (#75);
+ * [pendingDisabledCalendarIds] only holds those switch-offs the app has not been
+ * allowed to write yet.
  *
  * Persisted as a comma-separated string of Long ids; non-numeric tokens are
  * silently dropped (defensive — see CalendarPrefsTest).
@@ -22,21 +29,56 @@ class CalendarPrefs @Inject constructor(
     private val store: DataStore<Preferences>,
 ) {
 
-    val hiddenCalendarIds: Flow<Set<Long>> = store.data.map { prefs ->
-        prefs[HIDDEN_IDS_KEY].orEmpty()
-            .split(',')
-            .mapNotNull { it.trim().toLongOrNull() }
-            .toSet()
-    }
+    // Both id sets are deduped: the store is shared with SettingsPrefs, so any
+    // unrelated write would otherwise re-emit an identical set.
+    val hiddenCalendarIds: Flow<Set<Long>> = store.data
+        .map { prefs -> prefs[HIDDEN_IDS_KEY].parseIds() }
+        .distinctUntilChanged()
 
     suspend fun setHiddenCalendarIds(ids: Set<Long>) {
+        store.edit { prefs -> prefs.writeIds(HIDDEN_IDS_KEY, ids) }
+    }
+
+    /**
+     * Switch-offs the provider does not know about yet, because writing
+     * `Calendars.VISIBLE` needs `WRITE_CALENDAR` (#75). Also inherits the
+     * retired app-local model's set, from the same key.
+     *
+     * Honoured as a display and reminder filter while non-empty, but not a
+     * second visibility model: `CalendarVisibilityReconciler` drains it entry by
+     * entry as soon as the app may write, and nothing adds to it while it may.
+     */
+    val pendingDisabledCalendarIds: Flow<Set<Long>> = store.data
+        .map { prefs -> prefs[DISABLED_IDS_KEY].parseIds() }
+        .distinctUntilChanged()
+
+    suspend fun addPendingDisabledCalendarIds(ids: Collection<Long>) =
+        editPendingDisabled { it + ids }
+
+    /**
+     * Drop [ids] from the pending set, one at a time as the reconciler flushes
+     * them, so a run that fails part-way never re-applies what already landed.
+     */
+    suspend fun removePendingDisabledCalendarIds(ids: Collection<Long>) =
+        editPendingDisabled { it - ids.toSet() }
+
+    private suspend fun editPendingDisabled(transform: (Set<Long>) -> Set<Long>) {
         store.edit { prefs ->
-            if (ids.isEmpty()) {
-                prefs.remove(HIDDEN_IDS_KEY)
-            } else {
-                prefs[HIDDEN_IDS_KEY] = ids.sorted().joinToString(",")
+            prefs.writeIds(DISABLED_IDS_KEY, transform(prefs[DISABLED_IDS_KEY].parseIds()))
         }
     }
+
+    /**
+     * Whether the one-time "visibility follows this device" notice is still
+     * owed. Null until the reconciler has evaluated it (which needs the calendar
+     * permission), false once it has been shown or was never needed.
+     */
+    val visibilityNoticePending: Flow<Boolean?> = store.data.map { prefs ->
+        prefs[VISIBILITY_NOTICE_KEY]
+    }
+
+    suspend fun setVisibilityNoticePending(pending: Boolean) {
+        store.edit { prefs -> prefs[VISIBILITY_NOTICE_KEY] = pending }
     }
 
     /**
@@ -53,6 +95,17 @@ class CalendarPrefs @Inject constructor(
 
     companion object {
         internal val HIDDEN_IDS_KEY = stringPreferencesKey("hidden_calendar_ids")
+        internal val DISABLED_IDS_KEY = stringPreferencesKey("disabled_calendar_ids")
+        internal val VISIBILITY_NOTICE_KEY = booleanPreferencesKey("visibility_notice_pending")
         internal val LAST_USED_CALENDAR_KEY = longPreferencesKey("last_used_calendar_id")
     }
 }
+
+private fun String?.parseIds(): Set<Long> = orEmpty()
+    .split(',')
+    .mapNotNull { it.trim().toLongOrNull() }
+    .toSet()
+
+private fun MutablePreferences.writeIds(key: Preferences.Key<String>, ids: Set<Long>) {
+    if (ids.isEmpty()) remove(key) else set(key, ids.sorted().joinToString(","))
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/ReminderStatePrefs.kt

@@ -0,0 +1,36 @@
+package de.jeanlucmakiola.calendula.data.prefs
+
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.longPreferencesKey
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.map
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * How far reminder delivery has got — the one number replacing the provider's
+ * `CalendarAlerts.STATE` (#75). A scan posts the reminders falling after this
+ * watermark and up to now, then moves it to now, so a scan running twice cannot
+ * post twice while a late one still catches up.
+ *
+ * Unset means "never scanned", not zero: the first scan after an install would
+ * otherwise treat every reminder since the epoch as overdue.
+ */
+@Singleton
+class ReminderStatePrefs @Inject constructor(
+    private val store: DataStore<Preferences>,
+) {
+
+    /** The watermark, or `null` before the first scan has ever run. */
+    suspend fun lastScanMillis(): Long? = store.data.map { it[LAST_SCAN_KEY] }.first()
+
+    suspend fun setLastScanMillis(millis: Long) {
+        store.edit { prefs -> prefs[LAST_SCAN_KEY] = millis }
+    }
+
+    private companion object {
+        val LAST_SCAN_KEY = longPreferencesKey("reminder_last_scan_millis")
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderActionReceiver.kt

@@ -0,0 +1,144 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import androidx.core.net.toUri
+import dagger.hilt.android.AndroidEntryPoint
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * Handles the "Snooze" and "Dismiss" actions on a reminder notification, plus
+ * the internal re-show when a snooze elapses. All three are app-internal
+ * intents (notification action buttons and our own [ReminderSnoozeScheduler]
+ * alarm), so the receiver is not exported.
+ *
+ * - **Dismiss** just cancels the notification — the scan's watermark has moved
+ *   past this reminder, so nothing re-posts it.
+ * - **Snooze** cancels the notification and schedules an exact alarm to re-show
+ *   it after the user's snooze delay.
+ * - **Show** (the alarm) re-posts the same notification, so the user can snooze
+ *   or dismiss it again — unless the calendar was switched off during the
+ *   snooze, which [ReminderNotifier.post] catches — this alarm is its own
+ *   trigger, outside the ordinary scan.
+ */
+@AndroidEntryPoint
+class ReminderActionReceiver : BroadcastReceiver() {
+
+    @Inject lateinit var notifier: ReminderNotifier
+    @Inject lateinit var scheduler: ReminderSnoozeScheduler
+    @Inject lateinit var settingsPrefs: SettingsPrefs
+
+    override fun onReceive(context: Context, intent: Intent) {
+        val alert = alertFrom(intent) ?: return
+        when (intent.action) {
+            ACTION_DISMISS -> notifier.cancel(alert)
+
+            ACTION_SNOOZE -> {
+                // Cancel now so the notification doesn't linger until the alarm;
+                // the snooze delay read is the only async work.
+                notifier.cancel(alert)
+                val pendingResult = goAsync()
+                CoroutineScope(SupervisorJob() + Dispatchers.IO).launch {
+                    try {
+                        val minutes = settingsPrefs.snoozeMinutes.first()
+                        val triggerAt = System.currentTimeMillis() + minutes * 60_000L
+                        scheduler.schedule(alert, triggerAt)
+                    } finally {
+                        pendingResult.finish()
+                    }
+                }
+            }
+
+            ACTION_SHOW -> {
+                val pendingResult = goAsync()
+                CoroutineScope(SupervisorJob() + Dispatchers.IO).launch {
+                    try {
+                        if (settingsPrefs.remindersEnabled.first() && notifier.canPost()) {
+                            notifier.post(alert)
+                        }
+                    } finally {
+                        pendingResult.finish()
+                    }
+                }
+            }
+        }
+    }
+
+    companion object {
+        const val ACTION_SNOOZE = "de.jeanlucmakiola.calendula.reminders.SNOOZE"
+        const val ACTION_DISMISS = "de.jeanlucmakiola.calendula.reminders.DISMISS"
+        const val ACTION_SHOW = "de.jeanlucmakiola.calendula.reminders.SHOW"
+
+        /**
+         * Not handled here — the notification body opens the detail screen
+         * directly. It only claims a slot in [requestCode] so that intent stays
+         * distinct from the three this receiver does handle.
+         */
+        const val ACTION_OPEN = "de.jeanlucmakiola.calendula.reminders.OPEN"
+
+        private const val EXTRA_ALERT_KEY = "alert_key"
+        private const val EXTRA_EVENT_ID = "event_id"
+        private const val EXTRA_CALENDAR_ID = "calendar_id"
+        private const val EXTRA_BEGIN = "begin"
+        private const val EXTRA_END = "end"
+        private const val EXTRA_TITLE = "title"
+        private const val EXTRA_LOCATION = "location"
+        private const val EXTRA_ALL_DAY = "all_day"
+
+        /**
+         * An explicit intent to this receiver carrying [alert] as extras. The
+         * data URI duplicates no information but is what keeps two reminders'
+         * `PendingIntent`s apart — `filterEquals` never compares extras.
+         */
+        fun intent(context: Context, action: String, alert: ReminderAlert): Intent =
+            Intent(context, ReminderActionReceiver::class.java).apply {
+                this.action = action
+                data = "calendula://reminder/${alert.key}".toUri()
+                putExtra(EXTRA_ALERT_KEY, alert.key)
+                putExtra(EXTRA_EVENT_ID, alert.eventId)
+                putExtra(EXTRA_CALENDAR_ID, alert.calendarId)
+                putExtra(EXTRA_BEGIN, alert.beginMillis)
+                putExtra(EXTRA_END, alert.endMillis)
+                putExtra(EXTRA_TITLE, alert.title)
+                putExtra(EXTRA_LOCATION, alert.location)
+                putExtra(EXTRA_ALL_DAY, alert.isAllDay)
+            }
+
+        /**
+         * A stable request code per (alert, action), so one notification's
+         * PendingIntents stay distinct. The shift keeps the action slot intact;
+         * the top bits it drops are separated by [intent]'s per-reminder URI.
+         */
+        fun requestCode(alert: ReminderAlert, action: String): Int {
+            val actionOffset = when (action) {
+                ACTION_SNOOZE -> 1
+                ACTION_DISMISS -> 2
+                ACTION_SHOW -> 3
+                ACTION_OPEN -> 4
+                else -> 0
+            }
+            return (alert.key.toInt() shl 3) + actionOffset
+        }
+
+        private fun alertFrom(intent: Intent): ReminderAlert? {
+            if (!intent.hasExtra(EXTRA_ALERT_KEY)) return null
+            return ReminderAlert(
+                key = intent.getLongExtra(EXTRA_ALERT_KEY, 0L),
+                eventId = intent.getLongExtra(EXTRA_EVENT_ID, 0L),
+                calendarId = intent.getLongExtra(EXTRA_CALENDAR_ID, 0L),
+                beginMillis = intent.getLongExtra(EXTRA_BEGIN, 0L),
+                endMillis = intent.getLongExtra(EXTRA_END, 0L),
+                title = intent.getStringExtra(EXTRA_TITLE).orEmpty(),
+                location = intent.getStringExtra(EXTRA_LOCATION),
+                isAllDay = intent.getBooleanExtra(EXTRA_ALL_DAY, false),
+            )
+        }
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderAlarms.kt

@@ -0,0 +1,64 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.app.AlarmManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import androidx.core.content.getSystemService
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * True on API < 31 (no restriction), and on 31+ when the exact-alarm capability
+ * is held — auto-granted via `USE_EXACT_ALARM` on API 33+ (Calendula is a
+ * calendar app), user-revocable on 31–32.
+ */
+internal fun AlarmManager.canScheduleExactCompat(): Boolean =
+    Build.VERSION.SDK_INT < Build.VERSION_CODES.S || canScheduleExactAlarms()
+
+/**
+ * Holds the app's own wake-up for the next reminder (#75). Exactly one alarm
+ * exists at a time, for the earliest reminder ahead; every firing re-scans and
+ * re-arms. Exact, with an inexact allow-while-idle fallback where the OS
+ * withholds the capability (API 31–32 with the permission revoked).
+ */
+@Singleton
+class ReminderAlarmScheduler @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+
+    fun scheduleScan(triggerAtMillis: Long) {
+        val alarmManager = context.getSystemService<AlarmManager>() ?: return
+        val pendingIntent = scanPendingIntent(PendingIntent.FLAG_UPDATE_CURRENT)
+        if (alarmManager.canScheduleExactCompat()) {
+            alarmManager.setExactAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP, triggerAtMillis, pendingIntent,
+            )
+        } else {
+            alarmManager.setAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP, triggerAtMillis, pendingIntent,
+            )
+        }
+    }
+
+    /** Drop the pending wake-up — reminders are off, or there is nothing to wait for. */
+    fun cancelScan() {
+        val alarmManager = context.getSystemService<AlarmManager>() ?: return
+        alarmManager.cancel(scanPendingIntent(PendingIntent.FLAG_UPDATE_CURRENT))
+    }
+
+    private fun scanPendingIntent(flags: Int): PendingIntent = PendingIntent.getBroadcast(
+        context,
+        SCAN_REQUEST_CODE,
+        Intent(context, ReminderScheduleReceiver::class.java)
+            .setAction(ReminderScheduleReceiver.ACTION_SCAN),
+        flags or PendingIntent.FLAG_IMMUTABLE,
+    )
+
+    private companion object {
+        // Fixed: there is only ever one scan alarm, and re-arming must replace it.
+        const val SCAN_REQUEST_CODE = 0x5CA1
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderAlert.kt

@@ -0,0 +1,32 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import de.jeanlucmakiola.calendula.domain.reminders.PlannedReminder
+
+/**
+ * One reminder as the notification layer needs it: what to show, and the stable
+ * [key] identifying it across a reboot, a re-scan and a reinstall. Derived from
+ * the reminder itself (see [PlannedReminder.key]) — in-house delivery has no
+ * `CalendarAlerts` row to take an id from (#75).
+ */
+data class ReminderAlert(
+    val key: Long,
+    val eventId: Long,
+    val calendarId: Long,
+    val beginMillis: Long,
+    val endMillis: Long,
+    /** Raw event title; may be blank — the notifier substitutes "(no title)". */
+    val title: String,
+    val location: String?,
+    val isAllDay: Boolean,
+)
+
+fun PlannedReminder.toAlert(): ReminderAlert = ReminderAlert(
+    key = key,
+    eventId = instance.eventId,
+    calendarId = instance.calendarId,
+    beginMillis = instance.beginMillis,
+    endMillis = instance.endMillis,
+    title = instance.title,
+    location = instance.location,
+    isAllDay = instance.isAllDay,
+)

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderInstanceSource.kt

@@ -0,0 +1,121 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.content.Context
+import android.content.ContentUris
+import android.provider.CalendarContract
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.domain.reminders.ReminderEventInstance
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The read side of in-house reminder delivery: occurrences and their reminder
+ * offsets, read from `Instances` and `Reminders` rather than `CalendarAlerts`,
+ * which cannot be assumed to be written (#75).
+ *
+ * An interface so [ReminderScanner] can be exercised on the JVM.
+ */
+interface ReminderInstanceSource {
+
+    /** Occurrences overlapping `[fromMillis, toMillis]`, of switched-on calendars. */
+    fun occurrences(fromMillis: Long, toMillis: Long): List<ReminderEventInstance>
+
+    /** `METHOD_ALERT` reminder offsets per event id, for the given events. */
+    fun reminderMinutes(eventIds: Collection<Long>): Map<Long, List<Int>>
+
+    /**
+     * The largest `METHOD_ALERT` offset anywhere in the table, so the query
+     * window can be stretched to cover it and a long-lead reminder is planned
+     * before it comes due rather than firing late.
+     */
+    fun longestReminderMinutes(): Int
+}
+
+@Singleton
+class ProviderReminderInstanceSource @Inject constructor(
+    @ApplicationContext private val context: Context,
+) : ReminderInstanceSource {
+
+    override fun occurrences(fromMillis: Long, toMillis: Long): List<ReminderEventInstance> {
+        val uri = CalendarContract.Instances.CONTENT_URI.buildUpon().apply {
+            ContentUris.appendId(this, fromMillis)
+            ContentUris.appendId(this, toMillis)
+        }.build()
+        // `visible` is the flag the app's one visibility model writes (#75).
+        // The status clause mirrors CalendarDataSource.instances: NULL means
+        // "normal", so a bare `!= CANCELED` would drop every ordinary event.
+        val selection = "${CalendarContract.Calendars.VISIBLE} = 1 AND " +
+            "(${CalendarContract.Instances.STATUS} IS NULL OR " +
+            "${CalendarContract.Instances.STATUS} != ${CalendarContract.Events.STATUS_CANCELED})"
+        return context.contentResolver.query(
+            uri, OCCURRENCE_PROJECTION, selection, null, null,
+        )?.use { c ->
+            buildList {
+                while (c.moveToNext()) {
+                    add(
+                        ReminderEventInstance(
+                            eventId = c.getLong(0),
+                            calendarId = c.getLong(1),
+                            beginMillis = c.getLong(2),
+                            endMillis = if (c.isNull(3)) 0L else c.getLong(3),
+                            title = c.getString(4).orEmpty(),
+                            location = c.getString(5)?.takeIf { it.isNotBlank() },
+                            isAllDay = c.getInt(6) == 1,
+                        ),
+                    )
+                }
+            }
+        } ?: emptyList()
+    }
+
+    override fun reminderMinutes(eventIds: Collection<Long>): Map<Long, List<Int>> {
+        if (eventIds.isEmpty()) return emptyMap()
+        val out = mutableMapOf<Long, MutableList<Int>>()
+        // Batched: the ids go into the selection literally, and an unbounded
+        // `IN (...)` would grow the SQL past what SQLite takes.
+        eventIds.distinct().chunked(EVENT_ID_BATCH).forEach { batch ->
+            context.contentResolver.query(
+                CalendarContract.Reminders.CONTENT_URI,
+                REMINDER_PROJECTION,
+                "${CalendarContract.Reminders.METHOD} = " +
+                    "${CalendarContract.Reminders.METHOD_ALERT} AND " +
+                    "${CalendarContract.Reminders.EVENT_ID} IN (${batch.joinToString(",")})",
+                null,
+                null,
+            )?.use { c ->
+                while (c.moveToNext()) {
+                    out.getOrPut(c.getLong(0)) { mutableListOf() } += c.getInt(1)
+                }
+            }
+        }
+        return out
+    }
+
+    override fun longestReminderMinutes(): Int = context.contentResolver.query(
+        CalendarContract.Reminders.CONTENT_URI,
+        arrayOf(CalendarContract.Reminders.MINUTES),
+        "${CalendarContract.Reminders.METHOD} = ${CalendarContract.Reminders.METHOD_ALERT}",
+        null,
+        // One row is enough: the provider passes the sort order to SQLite.
+        "${CalendarContract.Reminders.MINUTES} DESC",
+    )?.use { c -> if (c.moveToFirst()) c.getInt(0) else 0 } ?: 0
+
+    private companion object {
+        const val EVENT_ID_BATCH = 50
+
+        val OCCURRENCE_PROJECTION = arrayOf(
+            CalendarContract.Instances.EVENT_ID,
+            CalendarContract.Instances.CALENDAR_ID,
+            CalendarContract.Instances.BEGIN,
+            CalendarContract.Instances.END,
+            CalendarContract.Instances.TITLE,
+            CalendarContract.Instances.EVENT_LOCATION,
+            CalendarContract.Instances.ALL_DAY,
+        )
+
+        val REMINDER_PROJECTION = arrayOf(
+            CalendarContract.Reminders.EVENT_ID,
+            CalendarContract.Reminders.MINUTES,
+        )
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderMaintenanceWorker.kt

@@ -0,0 +1,62 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.content.Context
+import android.util.Log
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import dagger.hilt.EntryPoint
+import dagger.hilt.InstallIn
+import dagger.hilt.android.EntryPointAccessors
+import dagger.hilt.components.SingletonComponent
+import java.util.concurrent.TimeUnit
+
+/**
+ * The backstop under the alarm: a daily scan that runs whether or not the alarm
+ * survived. Finds nothing to do in the steady state; it exists for the device
+ * that quietly drops the alarm without a reboot to announce it (#75).
+ */
+object ReminderMaintenanceScheduler {
+
+    private const val WORK_NAME = "reminder-scan-maintenance"
+
+    /** Enqueue the daily backstop; idempotent, so every launch may call it. */
+    fun apply(context: Context) {
+        val request = PeriodicWorkRequestBuilder<ReminderMaintenanceWorker>(1, TimeUnit.DAYS)
+            // The launch scan covers now; let the first periodic run wait.
+            .setInitialDelay(1, TimeUnit.DAYS)
+            .build()
+        WorkManager.getInstance(context)
+            .enqueueUniquePeriodicWork(WORK_NAME, ExistingPeriodicWorkPolicy.UPDATE, request)
+    }
+}
+
+class ReminderMaintenanceWorker(
+    appContext: Context,
+    params: WorkerParameters,
+) : CoroutineWorker(appContext, params) {
+
+    @EntryPoint
+    @InstallIn(SingletonComponent::class)
+    interface Deps {
+        fun reminderScanner(): ReminderScanner
+    }
+
+    override suspend fun doWork(): Result = try {
+        EntryPointAccessors.fromApplication(applicationContext, Deps::class.java)
+            .reminderScanner()
+            .scan()
+        Result.success()
+    } catch (e: Exception) {
+        // The scan swallows its own failures, so anything reaching here is the
+        // entry point itself — a retry will not mend it.
+        Log.w(TAG, "Reminder maintenance scan failed", e)
+        Result.success()
+    }
+
+    private companion object {
+        const val TAG = "ReminderMaintenance"
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderNotifier.kt

@@ -0,0 +1,171 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.Manifest
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.MainActivity
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
+import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.data.prefs.is24Hour
+import de.jeanlucmakiola.calendula.data.prefs.resolveFirstDay
+import kotlinx.coroutines.flow.first
+import kotlinx.datetime.isoDayNumber
+import java.time.DayOfWeek
+import java.time.Instant
+import java.time.ZoneId
+import java.util.Locale
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Posts one notification per due reminder on a dedicated channel. Tapping opens
+ * the event's detail screen.
+ *
+ * The tag is the reminder's stable key, so a scan that posts the same reminder
+ * again — a catch-up pass overlapping the alarm that already fired — replaces
+ * its notification silently ([NotificationCompat.Builder.setOnlyAlertOnce])
+ * instead of stacking a second one.
+ */
+@Singleton
+class ReminderNotifier @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val settingsPrefs: SettingsPrefs,
+    private val calendarPrefs: CalendarPrefs,
+    private val calendarDataSource: CalendarDataSource,
+) {
+
+    /** False when the user declined `POST_NOTIFICATIONS` or muted the app. */
+    fun canPost(): Boolean {
+        val granted = Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+            ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) ==
+            PackageManager.PERMISSION_GRANTED
+        return granted && NotificationManagerCompat.from(context).areNotificationsEnabled()
+    }
+
+    /**
+     * The single choke point for "this calendar is switched off", covering the
+     * two paths that reach [post] around the scan's own filter: a snooze armed
+     * before the switch-off, and a read-only install whose switch lives in
+     * [CalendarPrefs].
+     */
+    private suspend fun isSilenced(calendarId: Long): Boolean =
+        calendarId in calendarPrefs.pendingDisabledCalendarIds.first() ||
+            calendarDataSource.isCalendarVisible(calendarId) == false
+
+    /**
+     * Post [alert], unless its calendar is switched off. Returns whether the
+     * notification was put up, which the snooze re-show path uses to tell a
+     * silenced reminder from a delivered one.
+     */
+    suspend fun post(alert: ReminderAlert): Boolean {
+        if (isSilenced(alert.calendarId)) return false
+        ensureChannel()
+        val title = alert.title.ifBlank { context.getString(R.string.event_untitled) }
+        val is24Hour = settingsPrefs.timeFormat.first()
+            .is24Hour(android.text.format.DateFormat.is24HourFormat(context))
+        val zone = ZoneId.systemDefault()
+        val locale = Locale.getDefault()
+        // resolveFirstDay yields a kotlinx.datetime day; bridge it to java.time by
+        // its shared ISO number (1..7) for the date math in reminderTimeText.
+        val firstDayOfWeek = DayOfWeek.of(settingsPrefs.weekStart.first().resolveFirstDay(locale).isoDayNumber)
+        val time = reminderTimeText(
+            beginMillis = alert.beginMillis,
+            endMillis = alert.endMillis,
+            isAllDay = alert.isAllDay,
+            zone = zone,
+            locale = locale,
+            is24Hour = is24Hour,
+            today = Instant.now().atZone(zone).toLocalDate(),
+            firstDayOfWeek = firstDayOfWeek,
+            tomorrowLabel = context.getString(R.string.reminder_day_tomorrow),
+            yesterdayLabel = context.getString(R.string.reminder_day_yesterday),
+        )
+        val text = listOfNotNull(time, alert.location).joinToString(" · ")
+        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(R.drawable.ic_notification)
+            .setContentTitle(title)
+            .setContentText(text)
+            .setWhen(alert.beginMillis)
+            .setShowWhen(false)
+            .setCategory(NotificationCompat.CATEGORY_EVENT)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .setAutoCancel(true)
+            .setOnlyAlertOnce(true)
+            .setContentIntent(detailIntent(alert))
+            .addAction(
+                R.drawable.ic_notification_snooze,
+                context.getString(R.string.reminder_action_snooze),
+                actionIntent(alert, ReminderActionReceiver.ACTION_SNOOZE),
+            )
+            .addAction(
+                R.drawable.ic_notification_dismiss,
+                context.getString(R.string.reminder_action_dismiss),
+                actionIntent(alert, ReminderActionReceiver.ACTION_DISMISS),
+            )
+            .build()
+        try {
+            NotificationManagerCompat.from(context)
+                .notify(alert.key.toString(), NOTIFICATION_ID, notification)
+        } catch (e: SecurityException) {
+            // POST_NOTIFICATIONS was revoked between canPost() and here.
+            Log.w(TAG, "Could not post reminder for event ${alert.eventId}", e)
+        }
+        // Handled either way — a retry hits the same revoked permission.
+        return true
+    }
+
+    /** Remove a posted reminder (snooze re-shows it later; dismiss is final). */
+    fun cancel(alert: ReminderAlert) {
+        NotificationManagerCompat.from(context).cancel(alert.key.toString(), NOTIFICATION_ID)
+    }
+
+    private fun actionIntent(alert: ReminderAlert, action: String): PendingIntent =
+        PendingIntent.getBroadcast(
+            context,
+            ReminderActionReceiver.requestCode(alert, action),
+            ReminderActionReceiver.intent(context, action, alert),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+    private fun detailIntent(alert: ReminderAlert): PendingIntent = PendingIntent.getActivity(
+        context,
+        // Shares the per-(alert, action) request-code scheme with the buttons.
+        /* requestCode = */ ReminderActionReceiver.requestCode(
+            alert, ReminderActionReceiver.ACTION_OPEN,
+        ),
+        MainActivity.eventDetailIntent(context, alert.eventId, alert.beginMillis, alert.endMillis),
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+
+    /** Channel creation is idempotent; re-running refreshes the localized name. */
+    private fun ensureChannel() {
+        val channel = NotificationChannel(
+            CHANNEL_ID,
+            context.getString(R.string.reminder_channel_name),
+            NotificationManager.IMPORTANCE_HIGH,
+        ).apply {
+            description = context.getString(R.string.reminder_channel_description)
+        }
+        NotificationManagerCompat.from(context).createNotificationChannel(channel)
+    }
+
+    private companion object {
+        const val TAG = "ReminderNotifier"
+        const val CHANNEL_ID = "reminders"
+
+        // One id, distinct tags: the tag (alert id) already keys the
+        // notification, so a fixed id keeps cancellation/replacement simple.
+        const val NOTIFICATION_ID = 1
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderScanner.kt

@@ -0,0 +1,158 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.util.Log
+import androidx.core.content.ContextCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
+import de.jeanlucmakiola.calendula.data.di.IoDispatcher
+import de.jeanlucmakiola.calendula.data.prefs.ReminderStatePrefs
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.domain.reminders.planReminders
+import de.jeanlucmakiola.calendula.domain.reminders.reminderQueryHorizon
+import de.jeanlucmakiola.calendula.domain.reminders.reminderWatermark
+import de.jeanlucmakiola.calendula.domain.reminders.scheduleReminders
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.debounce
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.launchIn
+import kotlinx.coroutines.flow.onEach
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import java.time.ZoneId
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * One pass of in-house reminder delivery: read what is planned, post what has
+ * come due, and arm the next wake-up. Every trigger runs the same [scan], and
+ * re-running is always safe — the watermark in [ReminderStatePrefs] decides what
+ * is owed, not the trigger.
+ */
+@Singleton
+class ReminderScanner @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val source: ReminderInstanceSource,
+    private val calendarDataSource: CalendarDataSource,
+    private val notifier: ReminderNotifier,
+    private val alarms: ReminderAlarmScheduler,
+    private val state: ReminderStatePrefs,
+    private val settingsPrefs: SettingsPrefs,
+    @IoDispatcher private val io: kotlinx.coroutines.CoroutineDispatcher,
+) {
+
+    // Triggers overlap freely (an alarm during a burst of edits); serialize so
+    // two passes can't both read the same watermark and post the same reminder.
+    private val scanLock = Mutex()
+
+    private val scope = CoroutineScope(SupervisorJob() + io)
+    private val providerChanges = MutableSharedFlow<Unit>(
+        replay = 0, extraBufferCapacity = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST,
+    )
+    private var watching = false
+
+    suspend fun scan() = withContext(io) {
+        scanLock.withLock {
+            try {
+                runScan()
+            } catch (e: SecurityException) {
+                // Permission revoked mid-flight; the next grant re-scans.
+                Log.w(TAG, "Reminder scan lacks the calendar permission", e)
+            } catch (e: Exception) {
+                Log.w(TAG, "Reminder scan failed", e)
+            }
+        }
+    }
+
+    private suspend fun runScan() {
+        val now = System.currentTimeMillis()
+        if (!hasReadCalendar()) return
+
+        if (!settingsPrefs.remindersEnabled.first()) {
+            // Reminders off: drop the wake-up, but keep the watermark moving
+            // so switching them back on doesn't replay the backlog.
+            alarms.cancelScan()
+            state.setLastScanMillis(now)
+            return
+        }
+
+        val lookahead = reminderQueryHorizon(LOOKAHEAD_MILLIS, source.longestReminderMinutes())
+        // Reach into the past too: an all-day "at time of event" encodes to a
+        // negative offset, and a catch-up pass needs the occurrences it missed.
+        val occurrences = source.occurrences(now - PAST_WINDOW_MILLIS, now + lookahead)
+        val planned = planReminders(
+            instances = occurrences,
+            minutesByEvent = source.reminderMinutes(occurrences.map { it.eventId }),
+            zone = ZoneId.systemDefault(),
+            allDayTimeMinutes = settingsPrefs.allDayReminderTimeMinutes.first(),
+        )
+
+        val schedule = scheduleReminders(
+            planned = planned,
+            lastFiredMillis = reminderWatermark(state.lastScanMillis(), now),
+            nowMillis = now,
+            horizonMillis = now + MAX_ALARM_INTERVAL_MILLIS,
+        )
+
+        if (notifier.canPost()) {
+            schedule.due.forEach { notifier.post(it.toAlert()) }
+        }
+        // Advance even when nothing could be posted, so muting notifications
+        // doesn't build a backlog.
+        state.setLastScanMillis(now)
+        alarms.scheduleScan(schedule.nextAlarmMillis)
+    }
+
+    private fun hasReadCalendar(): Boolean = ContextCompat.checkSelfPermission(
+        context, Manifest.permission.READ_CALENDAR,
+    ) == PackageManager.PERMISSION_GRANTED
+
+    /**
+     * Re-scan when the provider changes, so a saved or deleted event re-arms the
+     * alarm at once. Debounced, since a single save lands as several
+     * notifications. Process-lifetime only; other triggers cover the rest.
+     */
+    fun startWatchingProvider() {
+        if (watching) return
+        watching = true
+        providerChanges
+            .debounce(PROVIDER_CHANGE_DEBOUNCE_MILLIS)
+            .onEach { scan() }
+            .launchIn(scope)
+        calendarDataSource.registerChangeListener { providerChanges.tryEmit(Unit) }
+    }
+
+    /** Fire-and-forget scan for callers that are not in a coroutine already. */
+    fun scanInBackground() {
+        scope.launch(start = CoroutineStart.DEFAULT) { scan() }
+    }
+
+    private companion object {
+        const val TAG = "ReminderScanner"
+
+        /**
+         * How far ahead occurrences are read. Stretched further by the longest
+         * reminder offset in the table, so this is only the floor.
+         */
+        const val LOOKAHEAD_MILLIS = 7L * 24 * 60 * 60 * 1000
+
+        /** How far back to look for occurrences that may still owe a reminder. */
+        const val PAST_WINDOW_MILLIS = 24L * 60 * 60 * 1000
+
+        /**
+         * Never wait longer than a day for the next pass: it rolls the lookahead
+         * window forward and re-arms an alarm the system may have dropped.
+         */
+        const val MAX_ALARM_INTERVAL_MILLIS = 24L * 60 * 60 * 1000
+
+        const val PROVIDER_CHANGE_DEBOUNCE_MILLIS = 2_000L
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderScheduleReceiver.kt

@@ -0,0 +1,53 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import dagger.hilt.android.AndroidEntryPoint
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * Every out-of-process reason to re-run a reminder scan: our own [ACTION_SCAN]
+ * alarm, boot and package-replaced (both wipe pending alarms), and time or
+ * timezone changes (both move reminders relative to the armed alarm). All do the
+ * same thing, since [ReminderScanner.scan] is idempotent.
+ *
+ * Exported for the system broadcasts; an early scan triggered by another app is
+ * harmless.
+ */
+@AndroidEntryPoint
+class ReminderScheduleReceiver : BroadcastReceiver() {
+
+    @Inject lateinit var scanner: ReminderScanner
+
+    override fun onReceive(context: Context, intent: Intent) {
+        // Checked despite every action doing the same thing: the receiver is
+        // exported and the broadcasts it takes are protected, so any other
+        // action did not come from where it claims to.
+        if (intent.action !in HANDLED_ACTIONS) return
+        val pendingResult = goAsync()
+        CoroutineScope(SupervisorJob() + Dispatchers.IO).launch {
+            try {
+                scanner.scan()
+            } finally {
+                pendingResult.finish()
+            }
+        }
+    }
+
+    companion object {
+        const val ACTION_SCAN = "de.jeanlucmakiola.calendula.reminders.SCAN"
+
+        private val HANDLED_ACTIONS = setOf(
+            ACTION_SCAN,
+            Intent.ACTION_BOOT_COMPLETED,
+            Intent.ACTION_MY_PACKAGE_REPLACED,
+            Intent.ACTION_TIME_CHANGED,
+            Intent.ACTION_TIMEZONE_CHANGED,
+        )
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderSnoozeScheduler.kt

@@ -0,0 +1,54 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import android.app.AlarmManager
+import android.app.PendingIntent
+import android.content.Context
+import android.os.Build
+import androidx.core.content.getSystemService
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Schedules a one-off exact alarm that re-shows a snoozed reminder. Separate
+ * from [ReminderAlarmScheduler]'s single moving scan alarm: a snooze is pinned
+ * to one reminder and has to outlive the watermark moving past it, so it carries
+ * the reminder in its own intent.
+ *
+ * Falls back to an inexact allow-while-idle alarm where the OS withholds the
+ * exact-alarm capability (API 31–32 with the permission revoked).
+ */
+@Singleton
+class ReminderSnoozeScheduler @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+
+    fun schedule(alert: ReminderAlert, triggerAtMillis: Long) {
+        val alarmManager = context.getSystemService<AlarmManager>() ?: return
+        val pendingIntent = PendingIntent.getBroadcast(
+            context,
+            ReminderActionReceiver.requestCode(alert, ReminderActionReceiver.ACTION_SHOW),
+            ReminderActionReceiver.intent(context, ReminderActionReceiver.ACTION_SHOW, alert),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+        if (canScheduleExact(alarmManager)) {
+            alarmManager.setExactAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP, triggerAtMillis, pendingIntent,
+            )
+        } else {
+            // Exact alarms revoked (API 31–32); an inexact wake is the best
+            // available without nagging for SCHEDULE_EXACT_ALARM.
+            alarmManager.setAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP, triggerAtMillis, pendingIntent,
+            )
+        }
+    }
+
+    /**
+     * True on API < 31 (no restriction), and on 31+ when the exact-alarm
+     * capability is held — auto-granted via `USE_EXACT_ALARM` on API 33+
+     * (Calendula is a calendar app), user-revocable on 31–32.
+     */
+    private fun canScheduleExact(alarmManager: AlarmManager): Boolean =
+        Build.VERSION.SDK_INT < Build.VERSION_CODES.S || alarmManager.canScheduleExactAlarms()
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/reminders/ReminderTimeText.kt

@@ -0,0 +1,130 @@
+package de.jeanlucmakiola.calendula.data.reminders
+
+import de.jeanlucmakiola.calendula.ui.common.timeOfDayFormatter
+import java.time.DayOfWeek
+import java.time.Instant
+import java.time.LocalDate
+import java.time.ZoneId
+import java.time.ZoneOffset
+import java.time.format.DateTimeFormatter
+import java.time.format.FormatStyle
+import java.time.format.TextStyle
+import java.time.temporal.ChronoUnit
+import java.util.Locale
+
+/**
+ * The one line of time context in a reminder notification. Pure so it can be
+ * JVM-tested.
+ *
+ * Timed events that fall on a day other than [today] are prefixed with that
+ * day, so a reminder fired ahead of time no longer reads as if the event were
+ * today (issue #46). The prefix prefers natural language and stays short:
+ *
+ * - today:                "09:30 – 10:00"                 (no prefix)
+ * - tomorrow / yesterday: "Tomorrow, 09:30 – 10:00"       ([tomorrowLabel] / [yesterdayLabel])
+ * - elsewhere this week:  "Thu, 09:30 – 10:00"            (localized short weekday)
+ * - further out:          "16 Jul, 09:30 – 10:00"         (medium date — a weekday
+ *                                                          alone would be ambiguous)
+ * - timed, crossing days: "11 Jun, 23:30 – 12 Jun, 00:30" (medium date + short time,
+ *                                                          already unambiguous)
+ * - all-day, one day:     "11 Jun 2026"
+ * - all-day, multi-day:   "11 Jun 2026 – 12 Jun 2026"
+ *
+ * All-day instances already carry an explicit date, so they never gain a
+ * relative prefix. They store UTC midnights with an exclusive end, so they are
+ * read in UTC and the end day is the last *covered* day.
+ */
+fun reminderTimeText(
+    beginMillis: Long,
+    endMillis: Long,
+    isAllDay: Boolean,
+    zone: ZoneId,
+    locale: Locale,
+    is24Hour: Boolean,
+    today: LocalDate,
+    firstDayOfWeek: DayOfWeek,
+    tomorrowLabel: String,
+    yesterdayLabel: String,
+): String {
+    if (isAllDay) {
+        val dateFormat = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(locale)
+        // (atZone().toLocalDate() instead of LocalDate.ofInstant — API 34+)
+        val firstDay = Instant.ofEpochMilli(beginMillis).atZone(ZoneOffset.UTC).toLocalDate()
+        val lastDay = Instant.ofEpochMilli(endMillis).atZone(ZoneOffset.UTC).toLocalDate()
+            .minusDays(1)
+            .coerceAtLeast(firstDay)
+        return if (lastDay == firstDay) {
+            dateFormat.format(firstDay)
+        } else {
+            dateFormat.format(firstDay) + RANGE + dateFormat.format(lastDay)
+        }
+    }
+
+    val timeFormat = timeOfDayFormatter(is24Hour, locale)
+    val dateFormat = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(locale)
+    val begin = Instant.ofEpochMilli(beginMillis).atZone(zone)
+    val end = Instant.ofEpochMilli(endMillis).atZone(zone)
+    return if (begin.toLocalDate() == end.toLocalDate()) {
+        val range = timeFormat.format(begin) + RANGE + timeFormat.format(end)
+        val prefix = relativeDayPrefix(
+            day = begin.toLocalDate(),
+            today = today,
+            firstDayOfWeek = firstDayOfWeek,
+            locale = locale,
+            dateFormat = dateFormat,
+            tomorrowLabel = tomorrowLabel,
+            yesterdayLabel = yesterdayLabel,
+        )
+        if (prefix == null) range else "$prefix, $range"
+    } else {
+        // Cross-day: medium date + the chosen short time, joined per side. Built
+        // from the two formatters (not ofLocalizedDateTime) so the 12/24h choice
+        // applies to the time portion too. The explicit dates already say which
+        // day, so no relative prefix is layered on top.
+        val dateTime = { z: java.time.ZonedDateTime -> "${dateFormat.format(z)}, ${timeFormat.format(z)}" }
+        dateTime(begin) + RANGE + dateTime(end)
+    }
+}
+
+/**
+ * A short label for [day] relative to [today], or `null` when it *is* today (the
+ * common case, which needs no prefix). Weekday names are used only within the
+ * current week — a "next Wednesday" would be indistinguishable from this one, so
+ * anything past this week falls back to the exact date.
+ */
+private fun relativeDayPrefix(
+    day: LocalDate,
+    today: LocalDate,
+    firstDayOfWeek: DayOfWeek,
+    locale: Locale,
+    dateFormat: DateTimeFormatter,
+    tomorrowLabel: String,
+    yesterdayLabel: String,
+): String? = when (ChronoUnit.DAYS.between(today, day)) {
+    0L -> null
+    1L -> tomorrowLabel
+    -1L -> yesterdayLabel
+    else -> if (isSameWeek(day, today, firstDayOfWeek)) {
+        day.dayOfWeek.getDisplayName(TextStyle.SHORT, locale)
+    } else {
+        dateFormat.format(day)
+    }
+}
+
+/**
+ * True when [day] and [today] share the same week. The week boundary honours the
+ * user's *week starts on* setting (already resolved to a concrete [firstDayOfWeek],
+ * with [firstDayOfWeek] falling back to the locale default upstream).
+ */
+private fun isSameWeek(day: LocalDate, today: LocalDate, firstDayOfWeek: DayOfWeek): Boolean {
+    val startOfWeek = today.previousOrSame(firstDayOfWeek)
+    return !day.isBefore(startOfWeek) && day.isBefore(startOfWeek.plusWeeks(1))
+}
+
+/** The most recent [target] on or before this date (this date itself when it matches). */
+private fun LocalDate.previousOrSame(target: DayOfWeek): LocalDate {
+    val backtrack = (dayOfWeek.value - target.value + 7) % 7
+    return minusDays(backtrack.toLong())
+}
+
+private const val RANGE = " – "

app/src/main/java/de/jeanlucmakiola/calendula/domain/CalendarRowState.kt

@@ -0,0 +1,60 @@
+package de.jeanlucmakiola.calendula.domain
+
+/**
+ * The ways a calendar can behave unlike a plain, writable one — each a reason it
+ * is missing from the event and import pickers (#76).
+ */
+enum class CalendarStateLabel {
+    /**
+     * A special-dates mirror the app fills from contacts. Writable and visible,
+     * yet no event target: anything authored here is deleted by the next sync.
+     */
+    MANAGED,
+
+    /** Contents can't be modified: a WebCal subscription, a read-only share. */
+    READ_ONLY,
+
+    /** The account holds the events, but this device isn't syncing them down. */
+    NOT_SYNCED,
+}
+
+/**
+ * Whether the account keeps this calendar's events off the device
+ * (`Calendars.SYNC_EVENTS = 0`) — empty by construction. Device-local calendars
+ * are excluded: nothing syncs them by definition, and one from another app can
+ * hold real events at `sync_events = 0`.
+ */
+val CalendarSource.isNotSynced: Boolean
+    get() = !syncsEvents && !isLocal
+
+/**
+ * Whether a visibility switch on this calendar can change anything the user
+ * would see — it can't for a non-syncing one, with no events on the device.
+ */
+val CalendarSource.hasVisibilitySwitch: Boolean
+    get() = !isNotSynced
+
+/**
+ * Whether this calendar can be offered as a target for a new or imported event.
+ * The one predicate behind both pickers, so the states [CalendarStateLabel]
+ * names on a manager row are exactly the states that keep a calendar out of them
+ * (#76). An event already living in an excluded calendar keeps it; the editor
+ * adds that calendar back to its picker.
+ */
+val CalendarSource.isEventTarget: Boolean
+    get() = canModifyContents && isVisibleInSystem && !isManaged && !isNotSynced
+
+/** Every state worth naming on this calendar's row, in reading order. */
+fun CalendarSource.stateLabels(): List<CalendarStateLabel> = buildList {
+    if (isManaged) add(CalendarStateLabel.MANAGED)
+    if (!canModifyContents) add(CalendarStateLabel.READ_ONLY)
+    if (isNotSynced) add(CalendarStateLabel.NOT_SYNCED)
+}
+
+/**
+ * Calendar-manager order within one group: the ones you can actually act on
+ * first, the non-syncing ones after them. Stable otherwise, so the provider's
+ * display-name ordering survives.
+ */
+fun List<CalendarSource>.orderedForManager(): List<CalendarSource> =
+    sortedBy { it.isNotSynced }

app/src/main/java/de/jeanlucmakiola/calendula/domain/CalendarVisibilityPlan.kt

@@ -0,0 +1,48 @@
+package de.jeanlucmakiola.calendula.domain
+
+/**
+ * The `Calendars.VISIBLE` writes that flush the app's pending "switched off"
+ * set into the provider, plus the ids that need no write at all.
+ */
+data class CalendarVisibilityPlan(
+    val hide: Set<Long> = emptySet(),
+    val settled: Set<Long> = emptySet(),
+) {
+    val isEmpty: Boolean get() = hide.isEmpty() && settled.isEmpty()
+}
+
+/**
+ * Reconcile [pendingDisabledIds] — switch-offs the app could not write, plus
+ * what the retired app-local visibility model left behind (#75) — against the
+ * calendars actually on the device.
+ *
+ * Only ever *hides*: switching a system-hidden calendar back on would un-hide it
+ * in every other calendar app too. Calendula follows the flag and explains
+ * itself once (see [hasSystemHiddenCalendars]).
+ *
+ * [CalendarVisibilityPlan.settled] carries the ids needing no write — already
+ * hidden, or gone from the device.
+ */
+fun calendarVisibilityPlan(
+    calendars: List<CalendarSource>,
+    pendingDisabledIds: Set<Long>,
+): CalendarVisibilityPlan {
+    val byId = calendars.associateBy { it.id }
+    val hide = mutableSetOf<Long>()
+    val settled = mutableSetOf<Long>()
+    for (id in pendingDisabledIds) {
+        val calendar = byId[id]
+        // Gone from the device, or already invisible — nothing to write.
+        if (calendar != null && calendar.isVisibleInSystem) hide += id else settled += id
+    }
+    return CalendarVisibilityPlan(hide = hide, settled = settled)
+}
+
+/**
+ * Whether any calendar is switched off at system level without Calendula having
+ * asked for it — the condition the one-time notice explains.
+ */
+fun hasSystemHiddenCalendars(
+    calendars: List<CalendarSource>,
+    pendingDisabledIds: Set<Long>,
+): Boolean = calendars.any { !it.isVisibleInSystem && it.id !in pendingDisabledIds }

app/src/main/java/de/jeanlucmakiola/calendula/domain/EventColorPalette.kt

@@ -0,0 +1,112 @@
+package de.jeanlucmakiola.calendula.domain
+
+import de.jeanlucmakiola.calendula.domain.color.Oklch
+import de.jeanlucmakiola.calendula.domain.color.eventTone
+import de.jeanlucmakiola.calendula.domain.color.oklchOf
+
+/**
+ * Curates an account's published event palette for the colour picker.
+ *
+ * Sync adapters differ wildly in what they publish: Google exposes a
+ * hand-picked two-dozen set, while CalDAV adapters (DAVx5) dump all ~147 CSS3
+ * named colours — including exact-value aliases (aqua/cyan, the gray/grey
+ * spelling pairs) and dozens of visually indistinguishable whites and grays
+ * (#22).
+ *
+ * Crucially, curation runs against the colour the picker actually *paints*, not
+ * the raw provider value — and it gets that colour from the same [eventTone]
+ * the picker calls, rather than from a copy of its shaping kept in step by hand.
+ * Because a harmonised container pins lightness, the raw palette's lightness
+ * axis is invisible on screen: two raw colours that look different — a navy and
+ * a mid blue — paint as one swatch, and every neutral (black, the grays, white)
+ * paints as the same grey. Judging distinctness in raw space, as before, left
+ * near-identical painted swatches and stranded the neutrals as a run of
+ * look-alike tints at the end of the grid.
+ *
+ * Three steps, all in painted space:
+ *  1. Collapse swatches that paint identically to one (alphabetically-first key
+ *     wins, deterministically) — this folds aliases, dark/light shades of a
+ *     hue, and all the neutrals together.
+ *  2. Oversized palettes (> [CURATION_TRIGGER_SIZE]) drop the neutral-origin
+ *     swatches — with lightness pinned, a grey source paints as plain grey, so
+ *     "has no hue left" is simply zero chroma — and are then thinned to visually
+ *     distinct colours: most vivid first, a colour is kept only when at least
+ *     [MIN_DISTANCE] away in Oklab from every colour already kept. Small
+ *     palettes are already curated by their adapter and pass through whole.
+ *  3. The survivors are ordered like a rainbow — continuously by painted hue —
+ *     with the wheel cut at its single widest empty gap so the one unavoidable
+ *     seam lands in dead space and no hue family is torn across both ends.
+ *
+ * Every surviving option keeps its provider [EventColorOption.key], so a pick
+ * still round-trips through sync.
+ */
+fun List<EventColorOption>.curatedForPicker(): List<EventColorOption> {
+    val painted = sortedBy { it.key }
+        .distinctBy { paintedArgb(it.argb) }
+        .map { it to oklchOf(paintedArgb(it.argb)) }
+    val kept = if (painted.size <= CURATION_TRIGGER_SIZE) {
+        painted
+    } else {
+        thin(painted.filter { (_, painted) -> painted.chroma > 0f })
+    }
+    return orderAroundWheel(kept).map { (option, _) -> option }
+}
+
+/**
+ * Orders swatches continuously around the (painted) hue wheel, then cuts the
+ * circle at its widest angular gap so the single seam lands in empty space
+ * instead of mid-family. Saturation breaks ties, vivid first.
+ */
+private fun orderAroundWheel(
+    swatches: List<Pair<EventColorOption, Oklch>>,
+): List<Pair<EventColorOption, Oklch>> {
+    if (swatches.size < 2) return swatches
+    val byHue = swatches.sortedWith(
+        compareBy({ (_, painted) -> painted.hue }, { (_, painted) -> -painted.chroma }),
+    )
+    // Split the wheel after the largest empty arc between neighbouring hues;
+    // the default is the wrap gap (last hue back round to the first), i.e. the
+    // familiar 0→360 order, and we only rotate away from it for a wider void.
+    var cutAfter = byHue.lastIndex
+    var widestGap = 360f - byHue.last().second.hue + byHue.first().second.hue
+    for (i in 0 until byHue.lastIndex) {
+        val gap = byHue[i + 1].second.hue - byHue[i].second.hue
+        if (gap > widestGap) {
+            widestGap = gap
+            cutAfter = i
+        }
+    }
+    return byHue.subList(cutAfter + 1, byHue.size) + byHue.subList(0, cutAfter + 1)
+}
+
+/** Greedy max-distance filter: vivid colours stake out clusters first. */
+private fun thin(
+    swatches: List<Pair<EventColorOption, Oklch>>,
+): List<Pair<EventColorOption, Oklch>> {
+    val byVividness = swatches
+        .sortedWith(
+            compareByDescending<Pair<EventColorOption, Oklch>> { it.second.chroma }
+                .thenBy { it.first.key },
+        )
+    val kept = mutableListOf<Pair<EventColorOption, Oklch>>()
+    for (candidate in byVividness) {
+        if (kept.none { it.second.distanceTo(candidate.second) < MIN_DISTANCE }) kept += candidate
+    }
+    return kept
+}
+
+/** The colour the picker paints for [argb]; the light theme stands in as the
+ *  reference, since a harmonised container differs only in lightness by theme
+ *  and curation compares hue and chroma. */
+private fun paintedArgb(argb: Int): Int =
+    eventTone(argb, dark = false, harmonise = true).container
+
+/** Palettes at most this big skip the thinning (Google's ~26 pass through). */
+private const val CURATION_TRIGGER_SIZE = 36
+
+/**
+ * Minimum Oklab distance between surviving painted swatches. Painted colours all
+ * share one lightness, so this is really a hue/chroma separation — far enough
+ * apart that two swatches never read as the same colour in the grid.
+ */
+private const val MIN_DISTANCE = 0.025f

app/src/main/java/de/jeanlucmakiola/calendula/domain/EventForm.kt

@@ -4,13 +4,14 @@ import kotlinx.datetime.LocalDate
 import kotlinx.datetime.LocalDateTime
 import kotlinx.datetime.LocalTime
 import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toInstant
 import kotlinx.datetime.toLocalDateTime
 import kotlin.time.Instant
 
 /**
  * User input for creating an event (and, from v1.3, editing one). Times are
- * wall-clock values in the device zone; the data layer translates them to
- * provider millis (all-day events normalise to UTC midnights there).
+ * wall-clock values in [timezone]; the data layer translates them to provider
+ * millis (all-day events normalise to UTC midnights there).
  */
 data class EventForm(
     val calendarId: Long?,
@@ -18,6 +19,23 @@ data class EventForm(
     val isAllDay: Boolean = false,
     val start: LocalDateTime,
     val end: LocalDateTime,
+    /**
+     * The zone [start]/[end] are wall-clock values in, or null to follow the
+     * device — null is not "no zone", it is "whichever zone the device is in
+     * when this is saved", which is what an event authored and lived in one
+     * place wants. The data layer resolves it at write time and always stamps a
+     * concrete `EVENT_TIMEZONE`.
+     *
+     * A non-null value pins the event to a zone regardless of where the device
+     * is, so it keeps tracking that zone's offset across DST. [toEditForm] only
+     * sets it when the stored zone differs from the device's, so merely opening
+     * a local event never reveals the field — and re-opening a pinned one in
+     * another zone round-trips it rather than silently re-anchoring it.
+     *
+     * Always null for all-day events: those are date-anchored, not zone-anchored
+     * (see [EventFormField.Timezone] and the data layer's UTC-midnight rule).
+     */
+    val timezone: String? = null,
     val location: String = "",
     val description: String = "",
     /** Reminder lead times in minutes before the start, deduplicated. */
@@ -30,19 +48,61 @@ data class EventForm(
      * those are kept verbatim until the user picks something else.
      */
     val rrule: String? = null,
+    /**
+     * The event's own colour, or null to inherit the calendar's colour.
+     * [colorKey] is a `Colors.COLOR_KEY` from the calendar account's published
+     * event palette (Google, some CalDAV) — written as `EVENT_COLOR_KEY` so it
+     * round-trips through sync. When it is null but [color] is set, [color] is
+     * a raw ARGB written as `EVENT_COLOR` (local calendars, or synced ones the
+     * user opted into despite no palette). [color] mirrors the key's swatch when
+     * [colorKey] is set, so the picker can highlight it.
+     */
+    val colorKey: String? = null,
+    val color: Int? = null,
+    /**
+     * Guests the user has added/kept on the event. Calendula only writes these
+     * `Attendees` rows — it has no INTERNET and never sends an invitation
+     * itself; whether a guest is notified is decided downstream by the
+     * calendar's backend (local: no one; CalDAV/Google: the server/account).
+     * Read-only rows the form doesn't model (the organizer, resources) are
+     * preserved by the data layer, not carried here.
+     */
+    val attendees: List<EventAttendee> = emptyList(),
+)
+
+/**
+ * One editable guest: the user controls the [email] (the identity we dedup and
+ * write on), an optional display [name], and whether they're [optional] rather
+ * than required. Response status and the organizer/resource distinction are not
+ * user-editable, so they aren't modelled here.
+ */
+data class EventAttendee(
+    val email: String,
+    val name: String = "",
+    val optional: Boolean = false,
 )
 
 /**
  * The form's optional sections. Which ones show by default is a user setting;
- * the rest unfold behind a "more fields" button.
+ * the rest unfold behind a "more fields" button. Declaration order is the order
+ * they're offered in, so a new constant goes where it belongs on the form, not
+ * at the end.
  */
 enum class EventFormField {
     Location,
     Description,
+    /**
+     * Pins the event's wall-clock times to a zone. Offered right after the time
+     * fields it qualifies, and suppressed entirely for all-day events, whose
+     * dates are deliberately zone-free.
+     */
+    Timezone,
     Reminders,
     Recurrence,
     Availability,
     Visibility,
+    Color,
+    Attendees,
 }
 
 enum class EventFormProblem {
@@ -66,8 +126,25 @@ enum class EventFormProblem {
  * All-day provider times are UTC midnights with an exclusive end; the form
  * shows the last covered day and keeps placeholder wall-clock times in case
  * the user switches the event to timed.
+ *
+ * A timed event stored in a zone other than [zone] is prefilled *in its own
+ * zone* and keeps it pinned, so the wall-clock the form shows is the one the
+ * event means ("the New York 09:00 call") and a later save re-anchors it to the
+ * same zone rather than the device's.
  */
 fun EventDetail.toEditForm(beginMillis: Long, endMillis: Long, zone: TimeZone): EventForm {
+    // All-day events are date-anchored and carry a nominal "UTC" that is an
+    // anchor, not a location, so they never pin a zone.
+    val pinnedZone = if (instance.isAllDay) {
+        null
+    } else {
+        eventTimezone
+            ?.takeIf { it != zone.id }
+            // An unparseable id (a malformed sync row) can't be honoured or
+            // shown; fall back to the device zone rather than failing the open.
+            ?.takeIf { runCatching { TimeZone.of(it) }.isSuccess }
+    }
+    val formZone = pinnedZone?.let { TimeZone.of(it) } ?: zone
     val (start, end) = if (instance.isAllDay) {
         val startDate = Instant.fromEpochMilliseconds(beginMillis)
             .toLocalDateTime(TimeZone.UTC).date
@@ -76,8 +153,8 @@ fun EventDetail.toEditForm(beginMillis: Long, endMillis: Long, zone: TimeZone):
         val endDate = maxOf(startDate, LocalDate.fromEpochDays(endExclusive.toEpochDays() - 1))
         LocalDateTime(startDate, LocalTime(9, 0)) to LocalDateTime(endDate, LocalTime(10, 0))
     } else {
-        Instant.fromEpochMilliseconds(beginMillis).toLocalDateTime(zone) to
-            Instant.fromEpochMilliseconds(endMillis).toLocalDateTime(zone)
+        Instant.fromEpochMilliseconds(beginMillis).toLocalDateTime(formZone) to
+            Instant.fromEpochMilliseconds(endMillis).toLocalDateTime(formZone)
     }
     return EventForm(
         calendarId = instance.calendarId,
@@ -85,13 +162,79 @@ fun EventDetail.toEditForm(beginMillis: Long, endMillis: Long, zone: TimeZone):
         isAllDay = instance.isAllDay,
         start = start,
         end = end,
+        timezone = pinnedZone,
         location = instance.location.orEmpty(),
         description = description.orEmpty(),
         reminders = reminders.map { it.minutes }.distinct().sorted(),
         availability = availability,
         accessLevel = accessLevel,
         rrule = rrule?.removePrefix("RRULE:")?.takeIf { it.isNotBlank() },
+        // The provider fills EVENT_COLOR from the key, so [color] is the
+        // swatch either way; a null colour means the event inherits its
+        // calendar's colour.
+        colorKey = eventColorKey,
+        color = eventColor,
+        // Only editable guests ride in the form: drop the organizer and
+        // resource rows (not user-editable) and any without an email (we key
+        // edits and dedup on the address). The data layer preserves the rows we
+        // don't carry here, so they're never clobbered on save.
+        attendees = attendees
+            .filter {
+                it.relationship != AttendeeRelationship.Organizer &&
+                    it.type != AttendeeType.Resource
+            }
+            .mapNotNull { a ->
+                a.email?.takeIf { it.isNotBlank() }?.let { email ->
+                    EventAttendee(
+                        email = email,
+                        name = a.name,
+                        optional = a.type == AttendeeType.Optional,
                     )
+                }
+            },
+    )
+}
+
+/**
+ * What the edit form saw when it loaded — compared against a fresh read at
+ * save time to detect external changes (sync, another device) that landed
+ * while the form was open. The raw row times ride along because
+ * [toEditForm] derives the form's times from the *tapped occurrence*, so
+ * re-deriving with the same occurrence would mask an externally moved
+ * event. Guests are covered (the form writes editable attendees), so an
+ * external attendee change now also trips the conflict check. Still not
+ * covered: status, the user's own response, reminder methods, the
+ * organizer/resource rows, and a recurring event's duration.
+ */
+data class EditSnapshot(
+    val form: EventForm,
+    /** The raw Events-row times (for recurring events: the series anchor). */
+    val rowStart: Instant,
+    val rowEnd: Instant,
+)
+
+fun EventDetail.toEditSnapshot(beginMillis: Long, endMillis: Long, zone: TimeZone): EditSnapshot =
+    EditSnapshot(
+        form = toEditForm(beginMillis, endMillis, zone),
+        rowStart = instance.start,
+        rowEnd = instance.end,
+    )
+
+/**
+ * The form's times as they land in [target] — what a pinned event's wall-clock
+ * actually means where the user is standing. Null when there's nothing to
+ * disambiguate: an unpinned event (already in [target]), one pinned to [target]
+ * itself, an all-day event (no zone), or an unparseable pinned zone.
+ *
+ * The form edits a pinned event in its own zone, so this is what lets the UI
+ * show the other side of the pair rather than making the user do the arithmetic.
+ */
+fun EventForm.timesIn(target: TimeZone): Pair<LocalDateTime, LocalDateTime>? {
+    if (isAllDay) return null
+    val pinned = timezone?.let { runCatching { TimeZone.of(it) }.getOrNull() } ?: return null
+    if (pinned.id == target.id) return null
+    return start.toInstant(pinned).toLocalDateTime(target) to
+        end.toInstant(pinned).toLocalDateTime(target)
 }
 
 /**
@@ -102,10 +245,13 @@ fun EventDetail.toEditForm(beginMillis: Long, endMillis: Long, zone: TimeZone):
 fun EventForm.populatedFields(): Set<EventFormField> = buildSet {
     if (location.isNotBlank()) add(EventFormField.Location)
     if (description.isNotBlank()) add(EventFormField.Description)
+    if (timezone != null) add(EventFormField.Timezone)
     if (reminders.isNotEmpty()) add(EventFormField.Reminders)
     if (rrule != null) add(EventFormField.Recurrence)
     if (availability != Availability.Busy) add(EventFormField.Availability)
     if (accessLevel != AccessLevel.Default) add(EventFormField.Visibility)
+    if (colorKey != null || color != null) add(EventFormField.Color)
+    if (attendees.isNotEmpty()) add(EventFormField.Attendees)
 }
 
 fun EventForm.problems(): Set<EventFormProblem> = buildSet {

app/src/main/java/de/jeanlucmakiola/calendula/domain/FontRole.kt

@@ -0,0 +1,8 @@
+package de.jeanlucmakiola.calendula.domain
+
+/**
+ * The two Material 3 typeface roles a user can set independently (issue #19):
+ * [BRAND] drives the display/headline styles (expression), [PLAIN] the
+ * title/body/label styles (readability). Each defaults to the system typeface.
+ */
+enum class FontRole { BRAND, PLAIN }

app/src/main/java/de/jeanlucmakiola/calendula/domain/InsertEventForm.kt

@@ -0,0 +1,78 @@
+package de.jeanlucmakiola.calendula.domain
+
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.LocalTime
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toInstant
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Duration.Companion.hours
+import kotlin.time.Instant
+
+/**
+ * Build a prefilled [EventForm] from an `ACTION_INSERT` intent's extras (issue
+ * #30). External apps and widgets (e.g. the Todo Agenda widget) launch the
+ * calendar this way to create a new event, passing the fields as
+ * [android.provider.CalendarContract] extras. Any field the intent omits falls
+ * back to the same defaults the in-app "new event" uses — a timed start at the
+ * next full hour, and a placeholder hour for a missing end that the form then
+ * stretches to the default-duration setting (the intent is opened as
+ * `ImportSource.InsertOpenEnded`, #54). [EventForm.calendarId] is left null so
+ * it resolves to the last-used / first-writable calendar, exactly like the
+ * `.ics` single-event and plain new-event paths.
+ *
+ * Pure (no Android types) so it is unit-testable; the intent parsing that reads
+ * the extras lives in `MainActivity.insertFormOrNull`.
+ */
+fun buildInsertEventForm(
+    beginMillis: Long?,
+    endMillis: Long?,
+    isAllDay: Boolean,
+    title: String?,
+    description: String?,
+    location: String?,
+    rrule: String?,
+    zone: TimeZone,
+    now: Instant,
+): EventForm {
+    val (start, end) = if (isAllDay) {
+        // All-day provider times are UTC midnights with an exclusive end; show
+        // the last covered day and keep placeholder wall-clock times in case the
+        // user switches the event to timed (mirrors EventDetail.toEditForm).
+        val startDate = beginMillis
+            ?.let { Instant.fromEpochMilliseconds(it).toLocalDateTime(TimeZone.UTC).date }
+            ?: now.toLocalDateTime(zone).date
+        val endDate = endMillis
+            ?.let { Instant.fromEpochMilliseconds(it).toLocalDateTime(TimeZone.UTC).date }
+            ?.let { exclusive -> maxOf(startDate, LocalDate.fromEpochDays(exclusive.toEpochDays() - 1)) }
+            ?: startDate
+        LocalDateTime(startDate, LocalTime(9, 0)) to LocalDateTime(endDate, LocalTime(10, 0))
+    } else {
+        val startTime = beginMillis
+            ?.let { Instant.fromEpochMilliseconds(it).toLocalDateTime(zone) }
+            ?: nextFullHour(now, zone)
+        val endTime = endMillis
+            ?.let { Instant.fromEpochMilliseconds(it).toLocalDateTime(zone) }
+            ?.takeIf { it >= startTime }
+            ?: (startTime.toInstant(zone) + 1.hours).toLocalDateTime(zone)
+        startTime to endTime
+    }
+    return EventForm(
+        calendarId = null,
+        title = title.orEmpty(),
+        isAllDay = isAllDay,
+        start = start,
+        end = end,
+        location = location.orEmpty(),
+        description = description.orEmpty(),
+        // Bare RRULE value (Events.RRULE convention); tolerate a leading "RRULE:"
+        // some callers include.
+        rrule = rrule?.removePrefix("RRULE:")?.takeIf { it.isNotBlank() },
+    )
+}
+
+private fun nextFullHour(now: Instant, zone: TimeZone): LocalDateTime {
+    val hourMillis = 3_600_000L
+    val rounded = (now.toEpochMilliseconds() / hourMillis + 1) * hourMillis
+    return Instant.fromEpochMilliseconds(rounded).toLocalDateTime(zone)
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/Models.kt

@@ -1,5 +1,9 @@
 package de.jeanlucmakiola.calendula.domain
 
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Duration.Companion.milliseconds
 import kotlin.time.Instant
 
 data class CalendarSource(
@@ -8,6 +12,11 @@ data class CalendarSource(
     val accountName: String,
     val accountType: String,
     val color: Int,
+    /**
+     * The system's `Calendars.VISIBLE` flag — the single visibility model,
+     * deciding both what Calendula shows and whether this calendar plans
+     * reminders (#75). The drawer's filter sheet is a separate in-app declutter.
+     */
     val isVisibleInSystem: Boolean,
     /**
      * Whether events in this calendar can be created/edited/deleted
@@ -15,6 +24,32 @@ data class CalendarSource(
      * subscriptions, birthday calendars and other read-only sources.
      */
     val canModifyContents: Boolean = false,
+    /**
+     * A device-only calendar the app itself owns (`ACCOUNT_TYPE_LOCAL`): it has
+     * no sync backend, so the app can rename / recolor / delete it. Synced
+     * calendars (Google, DAVx5, …) are managed in their own source app instead.
+     */
+    val isLocal: Boolean = false,
+    /**
+     * Free-text note for a local calendar (stored in `CAL_SYNC1`, which the app
+     * owns for its own calendars). Always null for synced calendars.
+     */
+    val description: String? = null,
+    /**
+     * A special-dates mirror calendar the app manages (birthdays/anniversaries
+     * from contacts). Its events' title/date/recurrence are owned by the sync,
+     * so it's hidden from the new-event calendar picker and its events lock those
+     * fields in the editor. Recognised by a durable provider marker, so it holds
+     * even after a backup restore clears the app's stored ids.
+     */
+    val isManaged: Boolean = false,
+    /**
+     * Whether the provider keeps this calendar's events on the device
+     * (`Calendars.SYNC_EVENTS`), independent of [isVisibleInSystem]. Says
+     * nothing about device-local calendars, which can hold events with it off.
+     * Read for the "not synced" row label (#76).
+     */
+    val syncsEvents: Boolean = true,
 )
 
 data class EventInstance(
@@ -29,6 +64,39 @@ data class EventInstance(
     val location: String?,
 )
 
+/**
+ * Whether this event has finished relative to [now] — its end is at or before
+ * the current instant. An in-progress event (already started but not yet ended)
+ * is *not* considered ended. All-day events end at the exclusive next-midnight,
+ * so they only count as ended once their day is fully over.
+ */
+fun EventInstance.hasEnded(now: Instant): Boolean = end <= now
+
+/**
+ * The zone this event's calendar dates live in: the device [zone] for timed
+ * events, UTC for all-day ones, whose midnights would otherwise shift day
+ * boundaries (#65, #82). Every surface naming an all-day date goes through here.
+ */
+fun EventInstance.dateZone(zone: TimeZone): TimeZone =
+    if (isAllDay) TimeZone.UTC else zone
+
+/** The first calendar day this event occupies. */
+fun EventInstance.spanFirstDay(zone: TimeZone): LocalDate =
+    start.toLocalDateTime(dateZone(zone)).date
+
+/**
+ * The last calendar day this event occupies. An event ending exactly at midnight
+ * does not reach into that day, so resolve just before [EventInstance.end].
+ */
+fun EventInstance.spanLastDay(zone: TimeZone): LocalDate {
+    val lastInstant = if (end > start) end - 1.milliseconds else start
+    return lastInstant.toLocalDateTime(dateZone(zone)).date
+}
+
+/** Whether this event occupies more than one calendar day in [zone]. */
+fun EventInstance.spansMultipleDays(zone: TimeZone): Boolean =
+    spanFirstDay(zone) != spanLastDay(zone)
+
 data class EventDetail(
     val instance: EventInstance,
     val description: String?,
@@ -47,8 +115,25 @@ data class EventDetail(
     val eventTimezone: String? = null,
     /** This device user's own response (`Events.SELF_ATTENDEE_STATUS`). */
     val selfStatus: AttendeeStatus = AttendeeStatus.Unknown,
+    /**
+     * The event's own raw colour (`Events.EVENT_COLOR`), null when the event
+     * inherits its calendar's colour. Unlike [EventInstance.color] (which
+     * already folds in the calendar fallback for display) this stays null so
+     * the edit form can tell "has own colour" from "inherits".
+     */
+    val eventColor: Int? = null,
+    /** The event's `Events.EVENT_COLOR_KEY` (a calendar-palette key), or null. */
+    val eventColorKey: String? = null,
 )
 
+/**
+ * One selectable event colour published by a calendar's account
+ * (`CalendarContract.Colors`, `TYPE_EVENT`): [key] is the account-scoped
+ * `COLOR_KEY` written as `EVENT_COLOR_KEY` (so the colour survives sync),
+ * [argb] is the swatch it renders as.
+ */
+data class EventColorOption(val key: String, val argb: Int)
+
 data class Attendee(
     val name: String,
     val email: String?,

app/src/main/java/de/jeanlucmakiola/calendula/domain/RecurrenceOccurrences.kt

@@ -0,0 +1,106 @@
+package de.jeanlucmakiola.calendula.domain
+
+import kotlinx.datetime.DateTimeUnit
+import kotlinx.datetime.DayOfWeek
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.isoDayNumber
+import kotlinx.datetime.minus
+import kotlinx.datetime.number
+import kotlinx.datetime.plus
+
+/**
+ * The first [limit] dates a [SimpleRecurrence] fires on, starting at [start]
+ * (DTSTART), for previewing a rule as dates instead of as words. A preview only,
+ * kept to the shapes the picker can build; the provider stays the authority.
+ *
+ * Mirrors RFC 5545: [start] is always the first occurrence (§3.8.5.3), even when
+ * the rule's own picks miss it; a monthly or yearly rule *skips* a period the
+ * start day doesn't exist in rather than clamping; a weekly rule repeats in
+ * blocks of `interval` weeks beginning on Monday (the default WKST, since
+ * [toRRule] never writes one); [RecurrenceEnd.Count] counts real occurrences and
+ * [RecurrenceEnd.Until] is inclusive.
+ *
+ * Returns fewer than [limit] dates when the series ends first, and an empty list
+ * only when the rule yields nothing at all (an UNTIL before [start]).
+ */
+fun SimpleRecurrence.upcomingOccurrences(start: LocalDate, limit: Int): List<LocalDate> {
+    if (limit <= 0) return emptyList()
+    val until = (end as? RecurrenceEnd.Until)?.date
+    val maxCount = (end as? RecurrenceEnd.Count)?.times ?: Int.MAX_VALUE
+    val wanted = minOf(limit, maxCount)
+    if (wanted <= 0) return emptyList()
+    if (until != null && start > until) return emptyList()
+
+    // DTSTART is in the recurrence set whatever the rule picks, so seed with it
+    // and let the walk skip anything landing on or before it.
+    val result = mutableListOf(start)
+    var period = 0
+    // Periods can yield nothing (a skipped 31st), so the cap counts periods
+    // examined rather than dates found.
+    while (result.size < wanted && period < MAX_PERIODS) {
+        for (date in occurrencesInPeriod(period, start)) {
+            if (date <= start) continue
+            if (until != null && date > until) return result
+            result += date
+            if (result.size == wanted) return result
+        }
+        period++
+    }
+    return result
+}
+
+/** The dates this rule's [period]-th repetition yields (empty when skipped). */
+private fun SimpleRecurrence.occurrencesInPeriod(period: Int, start: LocalDate): List<LocalDate> =
+    when (freq) {
+        RecurrenceFreq.Daily -> listOf(start.plus(period * interval, DateTimeUnit.DAY))
+        RecurrenceFreq.Weekly -> weeklyOccurrences(period, start)
+        RecurrenceFreq.Monthly -> {
+            val month = start.plus(period * interval, DateTimeUnit.MONTH)
+            // plus() clamps into the shorter month, but the rule skips such a
+            // period — so a clamped date means "not this month".
+            listOfNotNull(dateOrNull(month.year, month.month.number, start.day))
+        }
+        RecurrenceFreq.Yearly ->
+            listOfNotNull(dateOrNull(start.year + period * interval, start.month.number, start.day))
+    }
+
+/**
+ * One weekly block: every picked weekday inside the week that begins
+ * `period * interval` weeks after the start's own week, in weekday order. With
+ * no picks the rule simply repeats the start's weekday.
+ */
+private fun SimpleRecurrence.weeklyOccurrences(period: Int, start: LocalDate): List<LocalDate> {
+    if (byDays.isEmpty()) return listOf(start.plus(period * interval, DateTimeUnit.WEEK))
+    val daysIntoWeek = (start.dayOfWeek.isoDayNumber - DayOfWeek.MONDAY.isoDayNumber + DAYS_PER_WEEK) %
+        DAYS_PER_WEEK
+    val weekStart = start
+        .minus(daysIntoWeek, DateTimeUnit.DAY)
+        .plus(period * interval, DateTimeUnit.WEEK)
+    return byDays.sortedBy { it.isoDayNumber }.map { day ->
+        weekStart.plus(
+            (day.isoDayNumber - DayOfWeek.MONDAY.isoDayNumber + DAYS_PER_WEEK) % DAYS_PER_WEEK,
+            DateTimeUnit.DAY,
+        )
+    }
+}
+
+/**
+ * Whether a run of [occurrences] starting at [start] leaves its starting year,
+ * i.e. whether showing them without a year would be ambiguous — a yearly rule
+ * would otherwise read as the same date repeated.
+ */
+fun occurrencesSpanYears(occurrences: List<LocalDate>, start: LocalDate): Boolean =
+    occurrences.any { it.year != start.year } || occurrences.map { it.year }.distinct().size > 1
+
+/** [LocalDate] for a day-of-month that may not exist in that month; null if it doesn't. */
+private fun dateOrNull(year: Int, month: Int, day: Int): LocalDate? =
+    runCatching { LocalDate(year, month, day) }.getOrNull()
+
+private const val DAYS_PER_WEEK = 7
+
+/**
+ * How many repetitions to examine before giving up: generous enough for the
+ * sparsest rule the picker can build, bounded so a rule whose occurrences all
+ * fall outside its own UNTIL can't spin.
+ */
+private const val MAX_PERIODS = 2_000

app/src/main/java/de/jeanlucmakiola/calendula/domain/TimeZoneCatalog.kt

@@ -0,0 +1,225 @@
+package de.jeanlucmakiola.calendula.domain
+
+import java.text.Normalizer
+import java.time.Instant
+import java.time.ZoneId
+import java.time.format.TextStyle
+import java.util.Locale
+
+/**
+ * One selectable zone, resolved for display at a given instant. [id] is the IANA
+ * id we store in `EVENT_TIMEZONE` and show as the primary label (via [label]);
+ * [shortName] its abbreviation ("CET", "WET", "UTC", or a "GMT+05:30" fallback);
+ * [offsetMinutes] its offset. Both the abbreviation and the offset shift with
+ * DST, so they're only meaningful next to the moment they were resolved for.
+ *
+ * [displayName] is the long localized name ("Central European Time"). It's kept
+ * for search only — matching on it lets someone type "pacific" — and is *not*
+ * displayed: spelled out next to the id it made the field too wide to fit.
+ */
+data class TimeZoneOption(
+    val id: String,
+    val displayName: String,
+    val shortName: String,
+    val offsetMinutes: Int,
+) {
+    /** The id as the primary label, underscores undone ("America/New York"). */
+    val label: String get() = id.replace('_', ' ')
+
+    /** The trailing segment of the id ("Europe/Berlin" -> "Berlin"), underscores undone. */
+    val city: String get() = id.substringAfterLast('/').replace('_', ' ')
+
+    /** The leading segment ("Europe/Berlin" -> "Europe"); empty for bare ids like "UTC". */
+    val region: String get() = id.substringBeforeLast('/', missingDelimiterValue = "")
+
+    /**
+     * The four fields [filterTimeZones] matches on, normalized once here rather
+     * than per query. Normalizing is not cheap — NFD decomposition plus a combining-
+     * mark strip — and a search re-examines every option on every keystroke, so
+     * doing it at construction turns ~2400 normalizations per character into a few
+     * hundred plain `startsWith`/`contains` calls.
+     *
+     * Declared in the class body, so it stays out of `equals`/`hashCode`/`copy`:
+     * it is derived state, and two options with the same id are the same option.
+     */
+    internal val searchKeys: TimeZoneSearchKeys = TimeZoneSearchKeys(
+        city = city.normalizeForSearch(),
+        id = id.normalizeForSearch(),
+        displayName = displayName.normalizeForSearch(),
+        shortName = shortName.normalizeForSearch(),
+    )
+}
+
+/** Pre-normalized match targets for one [TimeZoneOption]. */
+internal data class TimeZoneSearchKeys(
+    val city: String,
+    val id: String,
+    val displayName: String,
+    val shortName: String,
+)
+
+private fun optionFor(
+    zone: ZoneId,
+    locale: Locale,
+    at: Instant,
+    regionOf: (String) -> String?,
+): TimeZoneOption = TimeZoneOption(
+    id = zone.id,
+    displayName = zone.getDisplayName(TextStyle.FULL, locale),
+    shortName = resolveAbbreviation(zone.id, zone.rules.isDaylightSavings(at), locale, regionOf),
+    offsetMinutes = zone.rules.getOffset(at).totalSeconds / 60,
+)
+
+/**
+ * The zone abbreviation ("EDT", "CEST"), DST-correct at the resolved instant, or
+ * a "GMT+05:30" form when no name exists.
+ *
+ * Two things make this fiddlier than it looks. First, it goes through
+ * java.util.TimeZone, NOT java.time's "zzz" formatter: on Android the latter has
+ * no short specific-zone names and degrades every zone to a "GMT-4" form (it
+ * agrees with java.util only on desktop, which is why desktop can't catch it).
+ * Second, ICU only surfaces the short name *commonly used in the display
+ * locale's region* — a German-region English phone (en-DE) is shown "CEST" but
+ * not "EDT", and an en-US phone the reverse. So ask in the display *language*
+ * but the *zone's* region ("America/New_York" in en-US, "Europe/Berlin" in
+ * en-DE) via [regionOf]. That covers almost everything; where a region still
+ * yields no name (Athens in en-GR) the plain device locale sometimes does, so
+ * try that next; failing both, the caller shows the offset.
+ *
+ * [regionOf] maps an IANA id to an ISO 3166 region and is injected because it
+ * needs `android.icu`, which this pure-JVM module can't import. The default
+ * (no region) leaves only the device-locale path — which is all a JVM test has
+ * anyway, and enough there since desktop ICU isn't region-gated the same way.
+ */
+private fun resolveAbbreviation(
+    id: String,
+    dst: Boolean,
+    locale: Locale,
+    regionOf: (String) -> String?,
+): String {
+    fun shortIn(loc: Locale): String =
+        java.util.TimeZone.getTimeZone(id).getDisplayName(dst, java.util.TimeZone.SHORT, loc)
+    val regional = regionOf(id)
+        ?.takeIf { it.length == 2 }
+        ?.let { shortIn(Locale(locale.language, it)) }
+    if (regional != null && !regional.looksLikeOffset()) return regional
+    // Either no region, or the region has no name for this zone: the device
+    // locale is the next-best shot, and the offset the last resort.
+    return shortIn(locale)
+}
+
+/** True for the offset-style names ICU returns when a zone has no abbreviation. */
+private fun String.looksLikeOffset(): Boolean = this == "UTC" || startsWith("GMT")
+
+/**
+ * Every zone the JVM knows, resolved at [at]. [regionOf] (see
+ * [resolveAbbreviation]) supplies the zone's region for the abbreviation.
+ *
+ * This is ~600 entries, each costing a localized display name plus up to two ICU
+ * short-name lookups, so it is **not** cheap enough for the main thread — build
+ * it off-thread once and filter the result with [filterTimeZones] rather than
+ * rebuilding per keystroke.
+ *
+ * Bare three-letter ids ("EST", "CST6CDT") and the legacy SystemV tree are
+ * dropped: they're aliases the tz database keeps for compatibility, they'd
+ * double up the real zones in the list, and none of them is what a user means
+ * when they pick a place.
+ */
+fun timeZoneOptions(
+    locale: Locale = Locale.getDefault(),
+    at: Instant = Instant.now(),
+    regionOf: (String) -> String? = { null },
+): List<TimeZoneOption> = ZoneId.getAvailableZoneIds()
+    .asSequence()
+    .filter { it.contains('/') && !it.startsWith("SystemV/") }
+    .map { optionFor(ZoneId.of(it), locale, at, regionOf) }
+    .sortedWith(compareBy({ it.region }, { it.city }))
+    .toList()
+
+/**
+ * Resolve a single [id] the same way [timeZoneOptions] would, or null if the tz
+ * database doesn't know it — for labelling one known zone without paying to
+ * build the whole catalogue.
+ */
+fun timeZoneOptionOf(
+    id: String,
+    locale: Locale = Locale.getDefault(),
+    at: Instant = Instant.now(),
+    regionOf: (String) -> String? = { null },
+): TimeZoneOption? {
+    val zone = runCatching { ZoneId.of(id) }.getOrNull() ?: return null
+    return optionFor(zone, locale, at, regionOf)
+}
+
+/**
+ * The short descriptor shown beneath the id, e.g. "CET · GMT+01:00". "UTC" reads
+ * fine alone; any other offset-shaped name is normalised to our own GMT form so
+ * the offset isn't stated twice in ICU's spelling and ours.
+ */
+fun zoneDescriptor(option: TimeZoneOption): String {
+    val abbrev = option.shortName
+    return when {
+        abbrev == "UTC" -> "UTC"
+        abbrev.startsWith("GMT") -> formatGmtOffset(option.offsetMinutes)
+        else -> "$abbrev · ${formatGmtOffset(option.offsetMinutes)}"
+    }
+}
+
+/**
+ * [options] matching [query], best matches first; a blank query returns the list
+ * unchanged. Matching is accent- and case-insensitive and treats underscores as
+ * spaces, so "sao paulo" finds "America/Sao_Paulo".
+ *
+ * Ranking puts a city that *starts with* the query above one that merely
+ * contains it — typing "col" should reach Colombo before Turks_and_Caicos —
+ * and the id is matched ahead of the localized name so a user who knows the
+ * IANA id gets it first. An exact abbreviation hit ("CEST") ranks just under a
+ * city prefix, so typing an abbreviation surfaces every zone that shows it
+ * (all the CEST zones together); the abbreviation is the one resolved for the
+ * display region, i.e. what the row actually shows.
+ */
+fun filterTimeZones(options: List<TimeZoneOption>, query: String): List<TimeZoneOption> {
+    val needle = query.normalizeForSearch()
+    if (needle.isEmpty()) return options
+    return options
+        .mapNotNull { option ->
+            val keys = option.searchKeys
+            val rank = when {
+                keys.city.startsWith(needle) -> 0
+                keys.shortName == needle -> 1
+                keys.displayName.startsWith(needle) -> 2
+                keys.shortName.startsWith(needle) -> 3
+                keys.city.contains(needle) -> 4
+                keys.id.contains(needle) -> 5
+                keys.displayName.contains(needle) -> 6
+                else -> return@mapNotNull null
+            }
+            rank to option
+        }
+        .sortedWith(compareBy({ it.first }, { it.second.city }))
+        .map { it.second }
+}
+
+/** Unicode combining marks — what NFD decomposition leaves an accent as. */
+private val COMBINING_MARKS = Regex("\\p{Mn}+")
+
+/**
+ * Lowercased, accent-stripped, underscores and slashes flattened to spaces, so
+ * a query types the way a place is spoken rather than the way the tz database
+ * spells it.
+ */
+private fun String.normalizeForSearch(): String =
+    Normalizer.normalize(this, Normalizer.Form.NFD)
+        .replace(COMBINING_MARKS, "")
+        .replace('_', ' ')
+        .replace('/', ' ')
+        .lowercase(Locale.ROOT)
+        .trim()
+
+/** "GMT+02:00" / "GMT-05:30" / "GMT" — the offset as shown next to a zone. */
+fun formatGmtOffset(offsetMinutes: Int): String {
+    if (offsetMinutes == 0) return "GMT"
+    val sign = if (offsetMinutes < 0) '-' else '+'
+    val abs = kotlin.math.abs(offsetMinutes)
+    return "GMT%c%02d:%02d".format(sign, abs / 60, abs % 60)
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/color/EventTone.kt

@@ -0,0 +1,124 @@
+package de.jeanlucmakiola.calendula.domain.color
+
+/**
+ * The colours one calendar's identity resolves to in one theme.
+ *
+ * The app paints a calendar's colour in two structurally different places, and
+ * they want opposite things:
+ *
+ *  - a **[container]** sits behind text (week and day blocks, month bars, widget
+ *    rows, picker swatches), so it has to contrast with its own ink;
+ *  - an **[accent]** is a mark on an ordinary app surface (day dots, agenda and
+ *    search stripes, calendar icon tints, the detail header), so it has to
+ *    contrast with the *surface* instead.
+ *
+ * Painting both from one colour is what made this hard to get right: deep enough
+ * to carry white text is too dark to see as a dot on a dark surface, and light
+ * enough to show up there is too pale to carry white text. Splitting them lets
+ * each be pinned to the lightness its job needs, while hue and chroma — the parts
+ * that actually say *which calendar this is* — stay shared, so the two roles
+ * still read as the same colour.
+ */
+data class EventTone(
+    val container: Int,
+    val onContainer: Int,
+    val accent: Int,
+)
+
+/**
+ * Resolve [rawArgb] for the current theme.
+ *
+ * With [harmonise] on, hue and chroma are kept and lightness is re-pinned per
+ * role, which is what makes the ink predictable: every container lands at the
+ * same perceptual lightness, so one ink colour serves every hue at ≥ 6:1. With
+ * it off the provider's colour is painted verbatim — the sync source's own look,
+ * as DAVx5/CalDAV users expect — and the ink is then chosen per colour, since
+ * nothing constrains what the provider sends.
+ */
+fun eventTone(rawArgb: Int, dark: Boolean, harmonise: Boolean): EventTone {
+    val opaque = rawArgb or 0xFF000000.toInt()
+    val raw = oklchOf(opaque)
+    if (!harmonise) {
+        return EventTone(
+            container = opaque,
+            onContainer = inkFor(raw.lightness),
+            accent = opaque,
+        )
+    }
+    // A near-grey source has no hue worth keeping, so it stays grey rather than
+    // being pushed to an arbitrary one; everything else is held inside a band
+    // that keeps calendars apart without going neon.
+    val chroma = if (raw.chroma < GREY_CHROMA) 0f else raw.chroma.coerceIn(MIN_CHROMA, MAX_CHROMA)
+    // Two poles rather than one. Forcing every hue deep is what turned the warm,
+    // naturally light ones muddy — a dark orange is brown and a dark yellow is
+    // olive, which is a fact about those hues, not a tuning miss. So a colour is
+    // sent to whichever pole it already sits nearer: most land deep and carry
+    // white ink, while genuinely light sources (yellows, creams, pale tints)
+    // stay light and carry dark ink, keeping the character that made them
+    // recognisable. Either way the colour is pulled clear of the middle, where
+    // neither ink reads well — which was the original fault.
+    val staysLight = raw.lightness >= LIGHT_POLE_THRESHOLD
+    val containerLightness = when {
+        staysLight && dark -> LIGHT_CONTAINER_LIGHTNESS_DARK
+        staysLight -> LIGHT_CONTAINER_LIGHTNESS_LIGHT
+        dark -> CONTAINER_LIGHTNESS_DARK
+        else -> CONTAINER_LIGHTNESS_LIGHT
+    }
+    // The accent takes no pole: it is a mark on the app's surface, so it has to
+    // contrast with that surface whichever way its container went.
+    val accentLightness = if (dark) ACCENT_LIGHTNESS_DARK else ACCENT_LIGHTNESS_LIGHT
+    return EventTone(
+        container = Oklch(containerLightness, chroma, raw.hue).toArgb(),
+        onContainer = inkFor(containerLightness),
+        accent = Oklch(accentLightness, chroma, raw.hue).toArgb(),
+    )
+}
+
+/**
+ * White or black ink for a background of the given perceptual [lightness].
+ *
+ * Derived rather than hardcoded so it stays right for raw provider colours,
+ * where lightness is whatever the sync source sent. For harmonised containers it
+ * is constant by construction — that is the point of pinning the lightness.
+ */
+fun inkFor(lightness: Float): Int =
+    if (lightness < INK_FLIP_LIGHTNESS) 0xFFFFFFFF.toInt() else 0xFF000000.toInt()
+
+/**
+ * Lightness at which white ink overtakes black. Sits above the midpoint because
+ * lightness is perceptual: a colour has to be distinctly light before black wins.
+ */
+const val INK_FLIP_LIGHTNESS = 0.62f
+
+/**
+ * Raw lightness at or above which a colour keeps its light character instead of
+ * being pushed deep. Set high enough that oranges and warm reds still go deep —
+ * a burnt orange reads as orange, where a dark yellow does not read as yellow —
+ * so only the genuinely pale sources take the light pole.
+ */
+const val LIGHT_POLE_THRESHOLD = 0.72f
+
+/** Container lightness: deep enough that white ink clears 5.5:1 on every hue. */
+const val CONTAINER_LIGHTNESS_LIGHT = 0.45f
+
+/** Same in dark mode, a shade lighter so a block separates from the surface. */
+const val CONTAINER_LIGHTNESS_DARK = 0.48f
+
+/** Light-pole container: pale enough that dark ink clears 11:1 on every hue. */
+const val LIGHT_CONTAINER_LIGHTNESS_LIGHT = 0.88f
+
+/** Same in dark mode, held down a little so a pale block doesn't glare. */
+const val LIGHT_CONTAINER_LIGHTNESS_DARK = 0.84f
+
+/** Accent lightness: dark enough to read as a mark on a pale surface. */
+const val ACCENT_LIGHTNESS_LIGHT = 0.55f
+
+/** Same against a dark surface, where the mark has to be the light one. */
+const val ACCENT_LIGHTNESS_DARK = 0.78f
+
+/** Below this chroma a colour counts as grey and keeps no hue. */
+const val GREY_CHROMA = 0.02f
+
+/** Chroma band for harmonised colours: distinct, but never electric. */
+const val MIN_CHROMA = 0.07f
+const val MAX_CHROMA = 0.16f

app/src/main/java/de/jeanlucmakiola/calendula/domain/color/Oklch.kt

@@ -0,0 +1,119 @@
+package de.jeanlucmakiola.calendula.domain.color
+
+import kotlin.math.atan2
+import kotlin.math.cbrt
+import kotlin.math.cos
+import kotlin.math.hypot
+import kotlin.math.pow
+import kotlin.math.sin
+import kotlin.math.sqrt
+
+/**
+ * A colour in Oklch — Oklab's cylindrical form: perceptual [lightness], [chroma]
+ * (colourfulness) and [hue] in degrees.
+ *
+ * The point of using it over HSV is that its lightness axis matches what the eye
+ * calls brightness. HSV's "value" does not: at a single pinned value the hues
+ * spread across relative luminance 0.10 (indigo) to 0.45 (yellow), which is why
+ * pinning value produced fills that needed different ink per hue. Pin Oklch
+ * lightness instead and every hue lands at the same apparent brightness, so one
+ * ink serves all of them.
+ *
+ * [lightness] runs 0 (black) to 1 (white); [chroma] is 0 (grey) to about 0.32 at
+ * the sRGB limit.
+ */
+data class Oklch(val lightness: Float, val chroma: Float, val hue: Float) {
+
+    /**
+     * Perceptual distance to [other] — plain Euclidean in Oklab, which is what
+     * Oklab is built for (unlike CIE Lab, where CIE76 is known to misjudge
+     * saturated blues).
+     */
+    fun distanceTo(other: Oklch): Float {
+        val (a1, b1) = chroma * cosDeg(hue) to chroma * sinDeg(hue)
+        val (a2, b2) = other.chroma * cosDeg(other.hue) to other.chroma * sinDeg(other.hue)
+        val dl = (lightness - other.lightness).toDouble()
+        return sqrt(dl * dl + (a1 - a2).pow(2) + (b1 - b2).pow(2)).toFloat()
+    }
+}
+
+/** Read [argb]'s opaque colour as Oklch. */
+fun oklchOf(argb: Int): Oklch {
+    val r = toLinear(((argb shr 16) and 0xFF) / 255.0)
+    val g = toLinear(((argb shr 8) and 0xFF) / 255.0)
+    val b = toLinear((argb and 0xFF) / 255.0)
+
+    val l = cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+    val m = cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+    val s = cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+
+    val lightness = 0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s
+    val aAxis = 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s
+    val bAxis = 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s
+
+    val hue = (Math.toDegrees(atan2(bAxis, aAxis)) + 360.0) % 360.0
+    return Oklch(lightness.toFloat(), hypot(aAxis, bAxis).toFloat(), hue.toFloat())
+}
+
+/**
+ * The opaque sRGB colour for this Oklch, gamut-mapped: most of the Oklch cylinder
+ * falls outside sRGB, so a colour that does not fit keeps its lightness and hue
+ * and gives up chroma until it does. Holding lightness is what matters here —
+ * it's the axis the contrast guarantees rest on.
+ */
+fun Oklch.toArgb(): Int {
+    val fitted = if (inSrgb(lightness, chroma, hue)) {
+        chroma
+    } else {
+        var low = 0f
+        var high = chroma
+        repeat(GAMUT_STEPS) {
+            val mid = (low + high) / 2f
+            if (inSrgb(lightness, mid, hue)) low = mid else high = mid
+        }
+        low
+    }
+    val (r, g, b) = linearSrgbOf(lightness, fitted, hue)
+    return 0xFF shl 24 or
+        (channel(r) shl 16) or
+        (channel(g) shl 8) or
+        channel(b)
+}
+
+private fun linearSrgbOf(lightness: Float, chroma: Float, hue: Float): Triple<Double, Double, Double> {
+    val a = chroma * cosDeg(hue)
+    val b = chroma * sinDeg(hue)
+    val l = (lightness + 0.3963377774 * a + 0.2158037573 * b).pow(3)
+    val m = (lightness - 0.1055613458 * a - 0.0638541728 * b).pow(3)
+    val s = (lightness - 0.0894841775 * a - 1.2914855480 * b).pow(3)
+    return Triple(
+        4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+    )
+}
+
+private fun inSrgb(lightness: Float, chroma: Float, hue: Float): Boolean {
+    val (r, g, b) = linearSrgbOf(lightness, chroma, hue)
+    return r in -GAMUT_EPSILON..(1.0 + GAMUT_EPSILON) &&
+        g in -GAMUT_EPSILON..(1.0 + GAMUT_EPSILON) &&
+        b in -GAMUT_EPSILON..(1.0 + GAMUT_EPSILON)
+}
+
+private fun channel(linear: Double): Int =
+    (toSrgb(linear.coerceIn(0.0, 1.0)) * 255.0).toInt().coerceIn(0, 255)
+
+private fun toLinear(c: Double): Double =
+    if (c <= 0.04045) c / 12.92 else ((c + 0.055) / 1.055).pow(2.4)
+
+private fun toSrgb(c: Double): Double =
+    if (c <= 0.0031308) 12.92 * c else 1.055 * c.pow(1.0 / 2.4) - 0.055
+
+private fun cosDeg(deg: Float) = cos(Math.toRadians(deg.toDouble()))
+private fun sinDeg(deg: Float) = sin(Math.toRadians(deg.toDouble()))
+
+/** Bisection steps when pulling an out-of-gamut colour back into sRGB. */
+private const val GAMUT_STEPS = 24
+
+/** Slack for the gamut test, so rounding at the boundary doesn't reject a fit. */
+private const val GAMUT_EPSILON = 1e-4

app/src/main/java/de/jeanlucmakiola/calendula/domain/contacts/ContactSpecialDate.kt

@@ -0,0 +1,122 @@
+package de.jeanlucmakiola.calendula.domain.contacts
+
+import java.time.LocalDate
+
+/**
+ * The kinds of contact "special date" Calendula mirrors into local calendars.
+ * Each kind gets its own local calendar, so it inherits per-calendar colour,
+ * visibility and reminder defaults for free. See
+ * docs/design/contact-special-dates.md.
+ */
+enum class SpecialDateType {
+    Birthday,
+    Anniversary,
+
+    /** Everything else — a contact "Event" that is neither birthday nor anniversary. */
+    Custom,
+}
+
+/**
+ * One dated event read from a device contact (a `ContactsContract` `Event`
+ * row). The [lookupKey] is the stable contact identity used to reconcile the
+ * mirror without duplicating; [year] is null when the contact stored the date
+ * without one (`--MM-dd`), in which case age can't be shown.
+ */
+data class ContactSpecialDate(
+    val lookupKey: String,
+    val displayName: String,
+    val type: SpecialDateType,
+    val month: Int,
+    val day: Int,
+    val year: Int?,
+    /** The contact's custom label for a [SpecialDateType.Custom] date, if any. */
+    val label: String? = null,
+)
+
+/** The parsed month/day (+ optional year) of a contact date. */
+data class ContactDateParts(val year: Int?, val month: Int, val day: Int)
+
+/**
+ * A fixed leap year to validate and anchor year-less dates against, so that a
+ * `--02-29` birthday is representable (and, once anchored, only recurs in leap
+ * years — matching how the calendar provider expands a yearly Feb-29 series).
+ */
+const val YEARLESS_ANCHOR_YEAR = 1972
+
+/**
+ * Parse a `ContactsContract.CommonDataKinds.Event.START_DATE` value into its
+ * calendar parts, or null if it isn't a usable date. Handles the three shapes
+ * seen in the wild:
+ * - full `yyyy-MM-dd` (year known),
+ * - year-less `--MM-dd` (year null),
+ * - compact `yyyyMMdd`.
+ *
+ * A date that names an impossible day (e.g. `1999-02-29`) is rejected. Pure, so
+ * it's unit-tested without a device.
+ */
+fun parseContactEventDate(raw: String?): ContactDateParts? {
+    val s = raw?.trim().orEmpty()
+    if (s.isEmpty()) return null
+
+    // Year-less: "--MM-dd" or "--MMdd".
+    if (s.startsWith("--")) {
+        val (m, d) = parseMonthDay(s.substring(2)) ?: return null
+        return validated(null, m, d)
+    }
+
+    if (s.contains('-')) {
+        val parts = s.split('-').filter { it.isNotEmpty() }
+        return when (parts.size) {
+            // "yyyy-MM-dd" — but a leading '-' would have dropped the empty
+            // first part, so require the first token to look like a year.
+            3 -> if (s.startsWith('-')) null else validated(
+                year = parts[0].toIntOrNull() ?: return null,
+                month = parts[1].toIntOrNull() ?: return null,
+                day = parts[2].toIntOrNull() ?: return null,
+            )
+            // Year-less "MM-dd" without the "--" prefix.
+            2 -> validated(
+                year = null,
+                month = parts[0].toIntOrNull() ?: return null,
+                day = parts[1].toIntOrNull() ?: return null,
+            )
+            else -> null
+        }
+    }
+
+    // Compact "yyyyMMdd".
+    if (s.length == 8 && s.all { it.isDigit() }) {
+        return validated(
+            year = s.substring(0, 4).toInt(),
+            month = s.substring(4, 6).toInt(),
+            day = s.substring(6, 8).toInt(),
+        )
+    }
+
+    return null
+}
+
+/** "MM-dd" or compact "MMdd". */
+private fun parseMonthDay(rest: String): Pair<Int, Int>? {
+    if (rest.contains('-')) {
+        val p = rest.split('-').filter { it.isNotEmpty() }
+        if (p.size != 2) return null
+        return (p[0].toIntOrNull() ?: return null) to (p[1].toIntOrNull() ?: return null)
+    }
+    if (rest.length == 4 && rest.all { it.isDigit() }) {
+        return rest.substring(0, 2).toInt() to rest.substring(2, 4).toInt()
+    }
+    return null
+}
+
+/**
+ * Confirm month/day form a real calendar date (validated against the actual
+ * year when known, otherwise the leap anchor so `02-29` survives).
+ */
+private fun validated(year: Int?, month: Int, day: Int): ContactDateParts? {
+    if (month !in 1..12 || day !in 1..31) return null
+    val checkYear = year ?: YEARLESS_ANCHOR_YEAR
+    return runCatching { LocalDate.of(checkYear, month, day) }
+        .map { ContactDateParts(year, month, day) }
+        .getOrNull()
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/contacts/SpecialDateFormatting.kt

@@ -0,0 +1,65 @@
+package de.jeanlucmakiola.calendula.domain.contacts
+
+import kotlinx.datetime.LocalDate
+
+/**
+ * Prefix of every managed-event `UID_2445`. Distinguishes mirror events from
+ * user-created ones (which carry a random `<uuid>@calendula` UID), so the sync
+ * only ever reconciles — and never deletes — events it actually owns.
+ */
+const val MANAGED_UID_PREFIX = "contact-"
+
+/**
+ * The deterministic `Events.UID_2445` that ties a mirrored event to its source
+ * contact date. Stable across syncs (the reconciliation key), namespaced by
+ * type so the same contact's birthday and anniversary never collide, and — when
+ * a [discriminator] is given — by it too, so two Custom dates on one contact
+ * (e.g. "Wedding" and "Graduation") get distinct events instead of clobbering
+ * each other.
+ */
+fun managedEventUid(type: SpecialDateType, lookupKey: String, discriminator: String? = null): String {
+    val disc = discriminator?.takeIf { it.isNotBlank() }?.let { ":$it" }.orEmpty()
+    return "$MANAGED_UID_PREFIX${type.name.lowercase()}:$lookupKey$disc@calendula"
+}
+
+/**
+ * The reconciliation key for this date's mirrored event. Birthdays/anniversaries
+ * are one-per-contact, so they key on the contact alone; a [SpecialDateType.Custom]
+ * date adds a discriminator (its label, else its month-day) so distinct custom
+ * dates on one contact don't collapse into a single event.
+ */
+fun ContactSpecialDate.managedUid(): String =
+    managedEventUid(type, lookupKey, customDiscriminator())
+
+private fun ContactSpecialDate.customDiscriminator(): String? =
+    if (type == SpecialDateType.Custom) {
+        label?.trim()?.lowercase()?.ifBlank { null } ?: "%02d-%02d".format(month, day)
+    } else {
+        null
+    }
+
+/**
+ * The all-day date the recurring `FREQ=YEARLY` series is anchored at: the real
+ * date when the year is known (so age can be derived), otherwise the month/day
+ * on a fixed leap anchor year so a `--02-29` date stays representable and the
+ * anchor never drifts between syncs.
+ */
+fun ContactSpecialDate.anchorDate(): LocalDate =
+    LocalDate(year ?: YEARLESS_ANCHOR_YEAR, month, day)
+
+/**
+ * Render a title [template] for a contact, substituting `{name}` and `{year}`
+ * (the source year — a birthday's birth year or an anniversary's start year;
+ * empty when [year] is null). Unlike an age, the year is static and correct on
+ * every occurrence of the yearly event. Collapses the whitespace an empty
+ * `{year}` may leave behind, so "{name}'s birthday ({year})" degrades cleanly to
+ * "Jane's birthday" when no year is known.
+ */
+fun renderSpecialDateTitle(template: String, name: String, year: Int?): String =
+    template
+        .replace("{name}", name)
+        .replace("{year}", year?.toString().orEmpty())
+        // Drop an empty "()" left by an unresolved {year}, then tidy spacing.
+        .replace(Regex("""\(\s*\)"""), "")
+        .replace(Regex("""\s+"""), " ")
+        .trim()

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/EventDetailIcs.kt

@@ -0,0 +1,29 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+import de.jeanlucmakiola.calendula.domain.EventDetail
+
+/**
+ * Build the [IcsEvent] for sharing a single event. We export the event the user
+ * is looking at as a **one-off** VEVENT (no RRULE): the detail screen shows one
+ * occurrence, so "share this event" should hand off exactly that instance, not
+ * a whole series anchored to a possibly-different DTSTART. Reminders are the
+ * already-decoded semantic lead times the detail screen holds.
+ */
+fun EventDetail.toShareIcsEvent(): IcsEvent {
+    val startMillis = instance.start.toEpochMilliseconds()
+    return IcsEvent(
+        uid = deriveIcsUid(existingUid = null, eventId = instance.eventId, dtStartMillis = startMillis),
+        summary = instance.title,
+        start = instance.start,
+        end = instance.end,
+        isAllDay = instance.isAllDay,
+        zoneId = eventTimezone?.takeIf { it.isNotBlank() } ?: "UTC",
+        recurrenceRule = null,
+        location = instance.location,
+        description = description,
+        reminderMinutes = reminders.map { it.minutes },
+        status = status,
+        availability = availability,
+        calendarName = null,
+    )
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/IcsDuration.kt

@@ -0,0 +1,40 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+// Android's calendar provider (and Calendula's own writes) use the non-standard
+// single-unit forms P<n>S / P<n>D / P<n>W — seconds without the RFC-required
+// leading T. Matched first; anything else falls through to the general grammar.
+private val DURATION_SINGLE_UNIT = Regex("""([+-]?)P(\d+)([WDS])""")
+private val DURATION_GENERAL =
+    Regex("""([+-]?)P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?""")
+
+/**
+ * Milliseconds of a DURATION (`P1D`, `P3600S`, `PT1H30M`, `-PT15M`, `P1W`, …),
+ * sign-aware. Calendula writes `P<days>D` / `P<seconds>S`, but the parser also
+ * accepts the general RFC 5545 grammar so backup `DURATION` rows and foreign
+ * `VALARM` triggers round-trip. Unparseable input is treated as zero.
+ */
+fun parseRfc2445DurationMillis(duration: String?): Long {
+    if (duration.isNullOrBlank()) return 0L
+    val s = duration.trim()
+
+    DURATION_SINGLE_UNIT.matchEntire(s)?.let { m ->
+        val unitSeconds = when (m.groupValues[3]) {
+            "W" -> 7L * 24 * 60 * 60
+            "D" -> 24L * 60 * 60
+            else -> 1L // S
+        }
+        return m.signum() * m.groupValues[2].toLong() * unitSeconds * 1_000L
+    }
+
+    val m = DURATION_GENERAL.matchEntire(s) ?: return 0L
+    val weeks = m.groupValues[2].toLongOrNull() ?: 0L
+    val days = m.groupValues[3].toLongOrNull() ?: 0L
+    val hours = m.groupValues[4].toLongOrNull() ?: 0L
+    val minutes = m.groupValues[5].toLongOrNull() ?: 0L
+    val seconds = m.groupValues[6].toLongOrNull() ?: 0L
+    val totalSeconds = ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60 + seconds)
+    return m.signum() * totalSeconds * 1_000L
+}
+
+/** Sign carried by group 1 (`-` → -1, otherwise +1) of a duration match. */
+private fun MatchResult.signum(): Long = if (groupValues[1] == "-") -1L else 1L

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/IcsEvent.kt

@@ -0,0 +1,43 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+import de.jeanlucmakiola.calendula.domain.Availability
+import de.jeanlucmakiola.calendula.domain.EventStatus
+import kotlin.time.Instant
+
+/**
+ * A single event ready to be serialised to a `VEVENT`, decoupled from the
+ * provider so [IcsWriter] stays pure-Kotlin and JVM-testable. [start]/[end] are
+ * absolute instants; [isAllDay] and [recurrenceRule] decide how they are
+ * rendered (see [IcsWriter]'s timezone rule).
+ */
+data class IcsEvent(
+    /** RFC 5545 UID — globally stable across exports (see [deriveIcsUid]). */
+    val uid: String,
+    val summary: String,
+    val start: Instant,
+    /** Exclusive end (for all-day: the next-day midnight, as the provider stores it). */
+    val end: Instant,
+    val isAllDay: Boolean,
+    /** IANA zone id (`Events.EVENT_TIMEZONE`); only used for recurring timed events. */
+    val zoneId: String,
+    /** Bare RRULE value (no `RRULE:` prefix), or null for a one-off event. */
+    val recurrenceRule: String? = null,
+    val location: String? = null,
+    val description: String? = null,
+    /** Reminder lead times in minutes before start (raw provider offsets). */
+    val reminderMinutes: List<Int> = emptyList(),
+    val status: EventStatus = EventStatus.Confirmed,
+    val availability: Availability = Availability.Busy,
+    /** Source calendar name, emitted as `X-CALENDULA-CALENDAR` so a combined backup can fan back out. */
+    val calendarName: String? = null,
+)
+
+/**
+ * The UID to export for a provider event. A row that already carries a UID
+ * (`Events.UID_2445`) keeps it; otherwise we synthesise a **stable** one from
+ * the event id and its DTSTART so the same legacy event yields the same UID
+ * across repeated backups — which keeps a later restore from duplicating it.
+ */
+fun deriveIcsUid(existingUid: String?, eventId: Long, dtStartMillis: Long): String =
+    existingUid?.trim()?.takeIf { it.isNotEmpty() }
+        ?: "$eventId-$dtStartMillis@calendula"

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/IcsParser.kt

@@ -0,0 +1,259 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+import de.jeanlucmakiola.calendula.domain.Availability
+import de.jeanlucmakiola.calendula.domain.EventStatus
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.LocalTime
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.atStartOfDayIn
+import kotlinx.datetime.toInstant
+import kotlin.time.Instant
+
+/**
+ * A `VEVENT` parsed from an `.ics` file — the read-side mirror of [IcsEvent],
+ * but [uid] is nullable (an incoming event may carry none; the insert layer
+ * then assigns one). Times are absolute instants; [isAllDay]/[zoneId] mirror
+ * how the writer encoded them.
+ */
+data class ParsedIcsEvent(
+    val uid: String?,
+    val summary: String,
+    val start: Instant,
+    val end: Instant,
+    val isAllDay: Boolean,
+    val zoneId: String,
+    val recurrenceRule: String? = null,
+    val location: String? = null,
+    val description: String? = null,
+    val reminderMinutes: List<Int> = emptyList(),
+    val status: EventStatus = EventStatus.Confirmed,
+    val availability: Availability = Availability.Busy,
+    val calendarName: String? = null,
+)
+
+/** Things the parser dropped rather than failing — surfaced in the import report. */
+enum class IcsParseWarning {
+    /** A `RECURRENCE-ID` override occurrence (not modelled; only masters import). */
+    ModifiedOccurrenceSkipped,
+
+    /** A `VEVENT` with no parseable `DTSTART`. */
+    EventWithoutStartSkipped,
+
+    /** `ATTENDEE` rows were present; Calendula doesn't import attendees. */
+    AttendeesIgnored,
+
+    /** A `TZID` couldn't be resolved against the device tz database (used local zone). */
+    UnknownTimezone,
+}
+
+data class IcsParseResult(
+    val events: List<ParsedIcsEvent>,
+    val warnings: Set<IcsParseWarning>,
+)
+
+/** Outcome of a bulk `.ics` import into one calendar. */
+data class IcsImportSummary(val imported: Int, val skippedDuplicate: Int)
+
+/**
+ * Hand-rolled RFC 5545 reader, the inverse of [IcsWriter]. Pure and
+ * JVM-testable. Liberal-in/strict-out: unknown properties are ignored, a single
+ * malformed `VEVENT` is skipped (not fatal), and unsupported constructs
+ * (`RECURRENCE-ID`, attendees, unresolved `TZID`) are reported as [warnings]
+ * rather than silently dropped. `VTIMEZONE` blocks are skipped — a `TZID` is
+ * resolved against the OS tz database instead ([deviceZone] is the fallback).
+ */
+class IcsParser(private val deviceZone: TimeZone = TimeZone.currentSystemDefault()) {
+
+    fun parse(text: String): IcsParseResult {
+        val lines = unfoldLines(text)
+        val events = mutableListOf<ParsedIcsEvent>()
+        val warnings = mutableSetOf<IcsParseWarning>()
+        var calendarName: String? = null
+
+        var i = 0
+        while (i < lines.size) {
+            val line = parseContentLine(lines[i])
+            if (line == null) { i++; continue }
+            when {
+                line.isBegin("VEVENT") -> {
+                    val end = indexOfEnd(lines, i + 1, "VEVENT")
+                    parseVevent(lines.subList(i + 1, end), calendarName, warnings)
+                        ?.let(events::add)
+                    i = end + 1
+                }
+                line.isBegin("VTIMEZONE") -> {
+                    // Skipped wholesale; TZIDs resolve against the OS tz database.
+                    i = indexOfEnd(lines, i + 1, "VTIMEZONE") + 1
+                }
+                line.name == "X-WR-CALNAME" -> {
+                    calendarName = unescapeText(line.value).trim().ifEmpty { null }
+                    i++
+                }
+                else -> i++
+            }
+        }
+        return IcsParseResult(events, warnings)
+    }
+
+    private fun parseVevent(
+        body: List<String>,
+        fileCalendarName: String?,
+        warnings: MutableSet<IcsParseWarning>,
+    ): ParsedIcsEvent? {
+        var uid: String? = null
+        var summary = ""
+        var dtStart: IcsDateTime? = null
+        var dtEnd: IcsDateTime? = null
+        var duration: String? = null
+        var rrule: String? = null
+        var location: String? = null
+        var description: String? = null
+        var status = EventStatus.Confirmed
+        var availability = Availability.Busy
+        var calendarName = fileCalendarName
+        val reminders = mutableListOf<Int>()
+        var skipAsOverride = false
+
+        var i = 0
+        while (i < body.size) {
+            val line = parseContentLine(body[i])
+            if (line == null) { i++; continue }
+            when (line.name) {
+                "BEGIN" -> if (line.value.trim().equals("VALARM", true)) {
+                    val end = indexOfEnd(body, i + 1, "VALARM")
+                    parseAlarmMinutes(body.subList(i + 1, end))?.let(reminders::add)
+                    i = end + 1
+                    continue
+                }
+                "UID" -> uid = line.value.trim().ifEmpty { null }
+                "SUMMARY" -> summary = unescapeText(line.value)
+                "DTSTART" -> dtStart = parseIcsDateTime(line, warnings)
+                "DTEND" -> dtEnd = parseIcsDateTime(line, warnings)
+                "DURATION" -> duration = line.value.trim()
+                "RRULE" -> rrule = line.value.trim().ifEmpty { null }
+                "LOCATION" -> location = unescapeText(line.value).ifEmpty { null }
+                "DESCRIPTION" -> description = unescapeText(line.value).ifEmpty { null }
+                "STATUS" -> status = mapIcsStatus(line.value)
+                "TRANSP" -> availability =
+                    if (line.value.trim().equals("TRANSPARENT", true)) Availability.Free
+                    else Availability.Busy
+                "RECURRENCE-ID" -> skipAsOverride = true
+                "ATTENDEE" -> warnings.add(IcsParseWarning.AttendeesIgnored)
+                "X-CALENDULA-CALENDAR" ->
+                    calendarName = unescapeText(line.value).trim().ifEmpty { calendarName }
+            }
+            i++
+        }
+
+        if (skipAsOverride) {
+            warnings.add(IcsParseWarning.ModifiedOccurrenceSkipped)
+            return null
+        }
+        val start = dtStart ?: run {
+            warnings.add(IcsParseWarning.EventWithoutStartSkipped)
+            return null
+        }
+        val end = dtEnd
+            ?: duration?.let {
+                start.copy(
+                    instant = Instant.fromEpochMilliseconds(
+                        start.instant.toEpochMilliseconds() + parseRfc2445DurationMillis(it),
+                    ),
+                )
+            }
+            ?: start
+        return ParsedIcsEvent(
+            uid = uid,
+            summary = summary,
+            start = start.instant,
+            end = end.instant,
+            isAllDay = start.isAllDay,
+            zoneId = start.zoneId,
+            recurrenceRule = rrule,
+            location = location,
+            description = description,
+            reminderMinutes = reminders.distinct(),
+            status = status,
+            availability = availability,
+            calendarName = calendarName,
+        )
+    }
+
+    /** A VALARM's lead time in minutes before start, or null if not a usable relative trigger. */
+    private fun parseAlarmMinutes(body: List<String>): Int? {
+        val trigger = body.asSequence()
+            .mapNotNull { parseContentLine(it) }
+            .firstOrNull { it.name == "TRIGGER" }
+            ?: return null
+        // Absolute (DATE-TIME) triggers can't be expressed as a lead time.
+        if (trigger.params["VALUE"].equals("DATE-TIME", true)) return null
+        val millis = parseRfc2445DurationMillis(trigger.value)
+        // Negative = before start (the normal case) → positive lead minutes.
+        return (-millis / 60_000L).toInt().coerceAtLeast(0)
+    }
+
+    private fun parseIcsDateTime(line: IcsContentLine, warnings: MutableSet<IcsParseWarning>): IcsDateTime? {
+        val raw = line.value.trim()
+        val isDate = line.params["VALUE"].equals("DATE", true) ||
+            (raw.length == 8 && !raw.contains('T'))
+        if (isDate) {
+            val date = parseBasicDate(raw) ?: return null
+            return IcsDateTime(date.atStartOfDayIn(TimeZone.UTC), isAllDay = true, zoneId = "UTC")
+        }
+        val isUtc = raw.endsWith("Z")
+        val ldt = parseBasicDateTime(raw.removeSuffix("Z")) ?: return null
+        if (isUtc) return IcsDateTime(ldt.toInstant(TimeZone.UTC), isAllDay = false, zoneId = "UTC")
+
+        val tzid = line.params["TZID"]
+        val resolved = tzid?.let { id -> runCatching { TimeZone.of(id) }.getOrNull()?.let { id to it } }
+        if (tzid != null && resolved == null) warnings.add(IcsParseWarning.UnknownTimezone)
+        val (zoneId, zone) = resolved ?: (deviceZone.id to deviceZone)
+        return IcsDateTime(ldt.toInstant(zone), isAllDay = false, zoneId = zoneId)
+    }
+
+    private data class IcsDateTime(val instant: Instant, val isAllDay: Boolean, val zoneId: String)
+
+    private companion object {
+        fun IcsContentLine.isBegin(component: String) =
+            name == "BEGIN" && value.trim().equals(component, true)
+
+        /** Index of the matching `END:<component>` at/after [from], or list end. */
+        fun indexOfEnd(lines: List<String>, from: Int, component: String): Int {
+            var i = from
+            while (i < lines.size) {
+                val line = parseContentLine(lines[i])
+                if (line != null && line.name == "END" &&
+                    line.value.trim().equals(component, true)
+                ) {
+                    return i
+                }
+                i++
+            }
+            return lines.size
+        }
+
+        fun mapIcsStatus(value: String): EventStatus = when (value.trim().uppercase()) {
+            "TENTATIVE" -> EventStatus.Tentative
+            "CANCELLED" -> EventStatus.Cancelled
+            else -> EventStatus.Confirmed
+        }
+
+        fun parseBasicDate(s: String): LocalDate? = runCatching {
+            LocalDate(s.substring(0, 4).toInt(), s.substring(4, 6).toInt(), s.substring(6, 8).toInt())
+        }.getOrNull()
+
+        fun parseBasicDateTime(s: String): LocalDateTime? = runCatching {
+            val date = LocalDate(
+                s.substring(0, 4).toInt(), s.substring(4, 6).toInt(), s.substring(6, 8).toInt(),
+            )
+            // Format is YYYYMMDD 'T' HHMMSS; seconds optional.
+            val time = LocalTime(
+                s.substring(9, 11).toInt(),
+                s.substring(11, 13).toInt(),
+                if (s.length >= 15) s.substring(13, 15).toInt() else 0,
+            )
+            LocalDateTime(date, time)
+        }.getOrNull()
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/IcsText.kt

@@ -0,0 +1,155 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+/**
+ * Low-level RFC 5545 text mechanics, kept separate from [IcsWriter] so the
+ * escaping and folding rules can be tested in isolation. Pure Kotlin — no
+ * Android, no time handling.
+ */
+
+/** iCalendar mandates CRLF line breaks, not the platform separator. */
+const val ICS_CRLF: String = "\r\n"
+
+/** RFC 5545 §3.1: content lines SHOULD be folded at 75 octets (excluding the break). */
+private const val MAX_OCTETS = 75
+
+/**
+ * Escape a TEXT value (SUMMARY, DESCRIPTION, LOCATION, …) per RFC 5545 §3.3.11:
+ * backslash, semicolon and comma are escaped, newlines become the literal `\n`.
+ * Backslash is handled first so it doesn't double-escape the others' markers.
+ */
+fun escapeText(value: String): String = buildString(value.length) {
+    for (ch in value) {
+        when (ch) {
+            '\\' -> append("\\\\")
+            ';' -> append("\\;")
+            ',' -> append("\\,")
+            '\n' -> append("\\n")
+            '\r' -> Unit // CR is dropped; a lone CRLF in source text folds to one \n
+            else -> append(ch)
+        }
+    }
+}
+
+/**
+ * Fold a single content line to ≤75 octets per physical line, inserting
+ * `CRLF + space` between segments (the space is part of the 75-octet budget of
+ * the continuation line, so its content caps at 74). Folding counts UTF-8
+ * octets, never splitting a multi-byte character across a boundary.
+ */
+fun foldLine(line: String): String {
+    if (line.toByteArray(Charsets.UTF_8).size <= MAX_OCTETS) return line
+    val out = StringBuilder()
+    var octetsThisLine = 0
+    var first = true
+    var i = 0
+    while (i < line.length) {
+        val cp = line.codePointAt(i)
+        val width = Character.charCount(cp)
+        val piece = line.substring(i, i + width)
+        val pieceOctets = piece.toByteArray(Charsets.UTF_8).size
+        // Continuation lines spend one octet on the leading space.
+        val budget = if (first) MAX_OCTETS else MAX_OCTETS - 1
+        if (octetsThisLine + pieceOctets > budget) {
+            out.append(ICS_CRLF).append(' ')
+            octetsThisLine = 0
+            first = false
+        }
+        out.append(piece)
+        octetsThisLine += pieceOctets
+        i += width
+    }
+    return out.toString()
+}
+
+/**
+ * Reverse of [escapeText]: turn `\n`/`\N` into newlines and unescape `\\`, `\;`,
+ * `\,`. A backslash before any other character is dropped, keeping the
+ * character (lenient — foreign files escape liberally).
+ */
+fun unescapeText(value: String): String = buildString(value.length) {
+    var i = 0
+    while (i < value.length) {
+        val c = value[i]
+        if (c == '\\' && i + 1 < value.length) {
+            when (val next = value[i + 1]) {
+                'n', 'N' -> append('\n')
+                else -> append(next) // \\, \;, \, and any other escaped char
+            }
+            i += 2
+        } else {
+            append(c)
+            i++
+        }
+    }
+}
+
+/**
+ * Reverse of [foldLine] across a whole document: split into physical lines on
+ * CRLF/LF/CR, then re-join any line that begins with a single space or tab onto
+ * the previous one (RFC 5545 unfolding). Returns the logical content lines.
+ */
+fun unfoldLines(text: String): List<String> {
+    val out = mutableListOf<String>()
+    for (physical in text.split("\r\n", "\n", "\r")) {
+        if (physical.isEmpty()) continue
+        val isContinuation = physical[0] == ' ' || physical[0] == '\t'
+        if (isContinuation && out.isNotEmpty()) {
+            out[out.lastIndex] = out.last() + physical.substring(1)
+        } else {
+            out.add(physical)
+        }
+    }
+    return out
+}
+
+/**
+ * One unfolded content line split into its property name, parameters and value:
+ * `SUMMARY;LANGUAGE=en:Lunch` → name `SUMMARY`, params `{LANGUAGE=en}`, value
+ * `Lunch`. The value is everything after the first colon that isn't inside a
+ * quoted parameter; param keys are upper-cased, quoted param values unquoted.
+ * Returns null for a line with no colon.
+ */
+data class IcsContentLine(val name: String, val params: Map<String, String>, val value: String)
+
+fun parseContentLine(line: String): IcsContentLine? {
+    var inQuote = false
+    var colon = -1
+    for (i in line.indices) {
+        when (line[i]) {
+            '"' -> inQuote = !inQuote
+            ':' -> if (!inQuote) { colon = i; break }
+        }
+    }
+    if (colon < 0) return null
+    val head = splitUnquoted(line.substring(0, colon), ';')
+    val name = head.firstOrNull()?.trim()?.uppercase().orEmpty()
+    if (name.isEmpty()) return null
+    val params = buildMap {
+        for (part in head.drop(1)) {
+            val eq = part.indexOf('=')
+            if (eq > 0) {
+                put(
+                    part.substring(0, eq).trim().uppercase(),
+                    part.substring(eq + 1).trim().removeSurrounding("\""),
+                )
+            }
+        }
+    }
+    return IcsContentLine(name, params, line.substring(colon + 1))
+}
+
+/** Split on [delimiter] except where it falls inside a double-quoted run. */
+private fun splitUnquoted(text: String, delimiter: Char): List<String> {
+    val parts = mutableListOf<String>()
+    val current = StringBuilder()
+    var inQuote = false
+    for (c in text) {
+        when {
+            c == '"' -> { inQuote = !inQuote; current.append(c) }
+            c == delimiter && !inQuote -> { parts.add(current.toString()); current.clear() }
+            else -> current.append(c)
+        }
+    }
+    parts.add(current.toString())
+    return parts
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/IcsWriter.kt

@@ -0,0 +1,124 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+import de.jeanlucmakiola.calendula.domain.Availability
+import de.jeanlucmakiola.calendula.domain.EventStatus
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.number
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Instant
+
+/** Default `PRODID` advertising the writer that produced the file. */
+const val ICS_PROD_ID: String = "-//Jean-Luc Makiola//Calendula//EN"
+
+/**
+ * Hand-rolled RFC 5545 serialiser for the subset Calendula models. No iCal
+ * library: we stay on `kotlinx-datetime` and own the output, exactly as
+ * `domain/Recurrence.kt` owns RRULE. Pure and JVM-testable — the caller
+ * supplies [dtStamp] (the export moment) so the writer never reads a clock.
+ *
+ * Timezone rule (see plan 05, decision 1):
+ *  - all-day      → `VALUE=DATE`, no zone;
+ *  - timed one-off → UTC instant with a `Z` suffix (an instant is an instant);
+ *  - timed recurring → `TZID`-labelled local wall time, so the series stays
+ *    anchored to wall-clock across DST. No `VTIMEZONE` block is emitted; import
+ *    resolves the `TZID` against the OS tz database.
+ */
+class IcsWriter(private val prodId: String = ICS_PROD_ID) {
+
+    fun writeCalendar(events: List<IcsEvent>, dtStamp: Instant): String {
+        val lines = buildList {
+            add("BEGIN:VCALENDAR")
+            add("VERSION:2.0")
+            add("PRODID:$prodId")
+            add("CALSCALE:GREGORIAN")
+            events.forEach { appendEvent(it, dtStamp) }
+            add("END:VCALENDAR")
+        }
+        return lines.joinToString(ICS_CRLF, postfix = ICS_CRLF) { foldLine(it) }
+    }
+
+    private fun MutableList<String>.appendEvent(event: IcsEvent, dtStamp: Instant) {
+        add("BEGIN:VEVENT")
+        add("UID:${event.uid}")
+        add("DTSTAMP:${utcStamp(dtStamp)}")
+        add("SUMMARY:${escapeText(event.summary)}")
+        appendTimes(event)
+        event.recurrenceRule?.takeIf { it.isNotBlank() }
+            ?.let { add("RRULE:${it.removePrefix("RRULE:")}") }
+        event.location?.takeIf { it.isNotBlank() }
+            ?.let { add("LOCATION:${escapeText(it)}") }
+        event.description?.takeIf { it.isNotBlank() }
+            ?.let { add("DESCRIPTION:${escapeText(it)}") }
+        add("STATUS:${statusValue(event.status)}")
+        add("TRANSP:${transpValue(event.availability)}")
+        event.calendarName?.takeIf { it.isNotBlank() }
+            ?.let { add("X-CALENDULA-CALENDAR:${escapeText(it)}") }
+        event.reminderMinutes.filter { it >= 0 }.distinct().forEach { minutes ->
+            appendAlarm(minutes, event.summary)
+        }
+        add("END:VEVENT")
+    }
+
+    private fun MutableList<String>.appendTimes(event: IcsEvent) = when {
+        event.isAllDay -> {
+            add("DTSTART;VALUE=DATE:${utcDate(event.start)}")
+            add("DTEND;VALUE=DATE:${utcDate(event.end)}")
+        }
+        // Recurring: anchor to wall-clock in the event's own zone.
+        event.recurrenceRule?.isNotBlank() == true -> {
+            val zone = runCatching { TimeZone.of(event.zoneId) }.getOrNull()
+            if (zone != null) {
+                add("DTSTART;TZID=${event.zoneId}:${localStamp(event.start, zone)}")
+                add("DTEND;TZID=${event.zoneId}:${localStamp(event.end, zone)}")
+            } else {
+                // Unknown zone id → fall back to plain UTC instants.
+                add("DTSTART:${utcStamp(event.start)}")
+                add("DTEND:${utcStamp(event.end)}")
+            }
+        }
+        else -> {
+            add("DTSTART:${utcStamp(event.start)}")
+            add("DTEND:${utcStamp(event.end)}")
+        }
+    }
+
+    private fun MutableList<String>.appendAlarm(minutes: Int, summary: String) {
+        add("BEGIN:VALARM")
+        add("ACTION:DISPLAY")
+        add("DESCRIPTION:${escapeText(summary.ifBlank { "Reminder" })}")
+        add("TRIGGER:${triggerValue(minutes)}")
+        add("END:VALARM")
+    }
+
+    private companion object {
+        fun statusValue(status: EventStatus): String = when (status) {
+            EventStatus.Confirmed -> "CONFIRMED"
+            EventStatus.Tentative -> "TENTATIVE"
+            EventStatus.Cancelled -> "CANCELLED"
+        }
+
+        // iCal TRANSP is binary; only an explicitly free event is TRANSPARENT.
+        fun transpValue(availability: Availability): String =
+            if (availability == Availability.Free) "TRANSPARENT" else "OPAQUE"
+
+        // A lead time of 0 fires at start (PT0M); anything positive is "before".
+        fun triggerValue(minutes: Int): String =
+            if (minutes <= 0) "PT0M" else "-PT${minutes}M"
+
+        fun utcStamp(instant: Instant): String =
+            basic(instant.toLocalDateTime(TimeZone.UTC)) + "Z"
+
+        fun localStamp(instant: Instant, zone: TimeZone): String =
+            basic(instant.toLocalDateTime(zone))
+
+        fun utcDate(instant: Instant): String {
+            val dt = instant.toLocalDateTime(TimeZone.UTC)
+            return "%04d%02d%02d".format(dt.year, dt.month.number, dt.day)
+        }
+
+        fun basic(dt: LocalDateTime): String = "%04d%02d%02dT%02d%02d%02d".format(
+            dt.year, dt.month.number, dt.day, dt.hour, dt.minute, dt.second,
+        )
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/ics/ParsedIcsForm.kt

@@ -0,0 +1,38 @@
+package de.jeanlucmakiola.calendula.domain.ics
+
+import de.jeanlucmakiola.calendula.domain.EventForm
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.LocalTime
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+
+/**
+ * Prefill the create form from a single parsed `.ics` event (the "open one
+ * event" path). [calendarId] is left null so the form preselects the last-used
+ * calendar, exactly like a fresh create — the user confirms the target and
+ * reviews everything before saving. Mirrors `EventDetail.toEditForm`'s all-day
+ * handling (provider all-day times are UTC midnights with an exclusive end).
+ */
+fun ParsedIcsEvent.toEventForm(zone: TimeZone): EventForm {
+    val (start, end) = if (isAllDay) {
+        val startDate = this.start.toLocalDateTime(TimeZone.UTC).date
+        val endExclusive = this.end.toLocalDateTime(TimeZone.UTC).date
+        val endDate = maxOf(startDate, LocalDate.fromEpochDays(endExclusive.toEpochDays() - 1))
+        LocalDateTime(startDate, LocalTime(9, 0)) to LocalDateTime(endDate, LocalTime(10, 0))
+    } else {
+        this.start.toLocalDateTime(zone) to this.end.toLocalDateTime(zone)
+    }
+    return EventForm(
+        calendarId = null,
+        title = summary,
+        isAllDay = isAllDay,
+        start = start,
+        end = end,
+        location = location.orEmpty(),
+        description = description.orEmpty(),
+        reminders = reminderMinutes.distinct().sorted(),
+        availability = availability,
+        rrule = recurrenceRule?.removePrefix("RRULE:")?.takeIf { it.isNotBlank() },
+    )
+}

app/src/main/java/de/jeanlucmakiola/calendula/domain/reminders/ReminderPlan.kt

@@ -0,0 +1,191 @@
+package de.jeanlucmakiola.calendula.domain.reminders
+
+import java.time.Instant
+import java.time.LocalDate
+import java.time.LocalTime
+import java.time.ZoneId
+import java.time.ZoneOffset
+import java.time.temporal.ChronoUnit
+
+/**
+ * Pure decision layer of in-house reminder delivery (#75): instances and reminder
+ * offsets in, fire instants out. No provider, no clock. See docs/ARCHITECTURE.md.
+ */
+
+/** An occurrence that reminders can hang off, flattened out of `Instances`. */
+data class ReminderEventInstance(
+    val eventId: Long,
+    val calendarId: Long,
+    val beginMillis: Long,
+    val endMillis: Long,
+    val title: String,
+    val location: String?,
+    val isAllDay: Boolean,
+)
+
+/**
+ * One occurrence paired with one of its reminder offsets, and the instant that
+ * pairing has to fire at.
+ */
+data class PlannedReminder(
+    val instance: ReminderEventInstance,
+    val minutes: Int,
+    val alarmMillis: Long,
+) {
+    /**
+     * Stable identity, keying the notification tag and the snooze/dismiss
+     * `PendingIntent`s. Survives reboot, re-scan and reinstall.
+     */
+    val key: Long = key(instance.eventId, instance.beginMillis, minutes)
+
+    private companion object {
+        fun key(eventId: Long, beginMillis: Long, minutes: Int): Long {
+            var h = eventId * 1_000_003L
+            h = (h xor beginMillis) * 31L
+            return h + minutes
+        }
+    }
+}
+
+/** What one scan concluded: post these now, and wake up again at [nextAlarmMillis]. */
+data class ReminderSchedule(
+    val due: List<PlannedReminder>,
+    val nextAlarmMillis: Long,
+)
+
+private const val MILLIS_PER_MINUTE = 60_000L
+private const val MINUTES_PER_DAY = 1_440
+
+/**
+ * Pair every instance with each of its event's reminder offsets.
+ *
+ * Timed occurrences fire at `begin − minutes`. All-day ones read the offset only
+ * for *which day* it means ([allDayLeadDays]) and take the hour from
+ * [allDayTimeMinutes], recomposed against each occurrence's own date in [zone].
+ * Duplicate offsets in [minutesByEvent] collapse.
+ */
+fun planReminders(
+    instances: List<ReminderEventInstance>,
+    minutesByEvent: Map<Long, List<Int>>,
+    zone: ZoneId,
+    allDayTimeMinutes: Int,
+): List<PlannedReminder> = instances.flatMap { instance ->
+    minutesByEvent[instance.eventId].orEmpty().distinct().map { minutes ->
+        PlannedReminder(
+            instance = instance,
+            minutes = minutes,
+            alarmMillis = if (instance.isAllDay) {
+                allDayAlarmMillis(instance.beginMillis, minutes, zone, allDayTimeMinutes)
+            } else {
+                instance.beginMillis - minutes * MILLIS_PER_MINUTE
+            },
+        )
+    }
+}
+
+/** UTC midnight of an all-day occurrence, as the calendar date it stands for. */
+private fun allDayDate(beginMillis: Long): LocalDate =
+    Instant.ofEpochMilli(beginMillis).atZone(ZoneOffset.UTC).toLocalDate()
+
+/**
+ * How many whole days before its occurrence a raw all-day offset means.
+ *
+ * Our own rows fold the wanted hour into the offset, so the local date of the
+ * encoded instant is the answer. A plain multiple of 1440 is a foreign bare lead
+ * time and taken at face value instead — unless the instant lands on the hour the
+ * setting names (within [NAMED_HOUR_TOLERANCE_MINUTES], for DST drift), where the
+ * encodings collide and the tie goes to our own reading.
+ *
+ * Also used by
+ * [de.jeanlucmakiola.calendula.data.calendar.fromProviderAllDayMinutes] for
+ * display, so screen and notification agree.
+ */
+internal fun allDayLeadDays(
+    rawMinutes: Int,
+    startDate: LocalDate,
+    zone: ZoneId,
+    allDayTimeMinutes: Int,
+): Long {
+    val utcMidnight = startDate.atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli()
+    val encoded = Instant.ofEpochMilli(utcMidnight - rawMinutes * MILLIS_PER_MINUTE).atZone(zone)
+    val minutesFromNamedHour = encoded.toLocalTime().let {
+        val delta = (it.hour * 60 + it.minute - allDayTimeMinutes).mod(MINUTES_PER_DAY)
+        minOf(delta, MINUTES_PER_DAY - delta)
+    }
+    if (rawMinutes % MINUTES_PER_DAY == 0 && minutesFromNamedHour > NAMED_HOUR_TOLERANCE_MINUTES) {
+        return (rawMinutes / MINUTES_PER_DAY).toLong()
+    }
+    return ChronoUnit.DAYS.between(encoded.toLocalDate(), startDate)
+}
+
+/** DST drift a row written in the other phase carries, rounded up past Lord Howe's half hour. */
+private const val NAMED_HOUR_TOLERANCE_MINUTES = 90
+
+private fun allDayAlarmMillis(
+    beginMillis: Long,
+    rawMinutes: Int,
+    zone: ZoneId,
+    allDayTimeMinutes: Int,
+): Long = allDayDate(beginMillis)
+    .minusDays(allDayLeadDays(rawMinutes, allDayDate(beginMillis), zone, allDayTimeMinutes))
+    .atTime(LocalTime.of(allDayTimeMinutes / 60, allDayTimeMinutes % 60))
+    .atZone(zone)
+    .toInstant()
+    .toEpochMilli()
+
+/**
+ * Split [planned] into what is due now and when to wake up next.
+ *
+ * Due means the fire instant falls in `(lastFiredMillis, nowMillis]`, so a scan
+ * running twice cannot post twice while a late one still catches up. Reminders
+ * whose event has ended are dropped ([isStillRelevant]). [nextAlarmMillis] is
+ * capped at [horizonMillis] so the lookahead window keeps rolling forward.
+ */
+fun scheduleReminders(
+    planned: List<PlannedReminder>,
+    lastFiredMillis: Long,
+    nowMillis: Long,
+    horizonMillis: Long,
+): ReminderSchedule {
+    val due = planned
+        .filter { it.alarmMillis in (lastFiredMillis + 1)..nowMillis }
+        .filter { it.instance.isStillRelevant(nowMillis) }
+        .distinctBy { it.key }
+        .sortedWith(compareBy({ it.instance.beginMillis }, { it.key }))
+    val nextPending = planned
+        .filter { it.alarmMillis > nowMillis }
+        .minOfOrNull { it.alarmMillis }
+    return ReminderSchedule(
+        due = due,
+        nextAlarmMillis = minOf(nextPending ?: horizonMillis, horizonMillis),
+    )
+}
+
+/**
+ * Still worth showing while the occurrence has not ended. Falls back to the
+ * begin time when the end is unknown (0L).
+ */
+fun ReminderEventInstance.isStillRelevant(nowMillis: Long): Boolean =
+    (endMillis.takeIf { it > 0L } ?: beginMillis) >= nowMillis
+
+/**
+ * The watermark a scan at [nowMillis] should measure against. A first-ever scan
+ * claims the present rather than replaying everything since the epoch; a
+ * watermark in the future (clock moved back) is clamped so it can't silence
+ * every reminder until real time catches up.
+ */
+fun reminderWatermark(lastScanMillis: Long?, nowMillis: Long): Long =
+    lastScanMillis?.coerceAtMost(nowMillis) ?: nowMillis
+
+/**
+ * How far ahead instances must be queried: the plain lookahead plus the longest
+ * reminder offset, so a "two weeks before" is planned before it comes due. The
+ * stretch is capped at [MAX_REMINDER_LEAD_MILLIS] — `maxReminderMinutes` is the
+ * largest row in the whole provider, and a nonsense one would otherwise make
+ * every scan expand every series over years.
+ */
+fun reminderQueryHorizon(lookaheadMillis: Long, maxReminderMinutes: Int): Long =
+    lookaheadMillis + (maxReminderMinutes * MILLIS_PER_MINUTE).coerceIn(0L, MAX_REMINDER_LEAD_MILLIS)
+
+/** Longest reminder offset a scan stretches its query window for — one year. */
+const val MAX_REMINDER_LEAD_MILLIS = 365L * 24 * 60 * 60 * 1000

app/src/main/java/de/jeanlucmakiola/calendula/qs/NewEventTileService.kt

@@ -0,0 +1,43 @@
+package de.jeanlucmakiola.calendula.qs
+
+import android.app.PendingIntent
+import android.os.Build
+import android.service.quicksettings.TileService
+import de.jeanlucmakiola.calendula.MainActivity
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Clock
+
+/**
+ * Quick Settings tile: tapping it opens the create-event form on today — the
+ * same action as the launcher "New event" shortcut and the agenda widget's "+".
+ * A stateless action tile, so there is no on/off state to keep in sync.
+ */
+class NewEventTileService : TileService() {
+
+    // The pre-34 branch intentionally uses the deprecated Intent overload: it is
+    // the only form available below UpsideDownCake, and is reached only there.
+    @Suppress("DEPRECATION", "StartActivityAndCollapseDeprecated")
+    override fun onClick() {
+        super.onClick()
+        val today = Clock.System.now()
+            .toLocalDateTime(TimeZone.currentSystemDefault()).date
+        val intent = MainActivity.openCreateIntent(this, today)
+        // Launch only once the device is unlocked: creating an event behind the
+        // keyguard makes no sense, and the shade can't start an activity over a
+        // locked screen anyway.
+        unlockAndRun {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                val pending = PendingIntent.getActivity(
+                    this,
+                    0,
+                    intent,
+                    PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+                )
+                startActivityAndCollapse(pending)
+            } else {
+                startActivityAndCollapse(intent)
+            }
+        }
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/CalendarHost.kt

@@ -1,5 +1,7 @@
 package de.jeanlucmakiola.calendula.ui
 
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.AnimatedContent
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
@@ -8,38 +10,100 @@ import androidx.compose.animation.slideOutHorizontally
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.listSaver
 import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import de.jeanlucmakiola.calendula.domain.EventForm
 import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.ui.agenda.AgendaScreen
+import de.jeanlucmakiola.calendula.ui.calendars.BackupScreen
+import de.jeanlucmakiola.calendula.ui.calendars.CalendarsScreen
+import de.jeanlucmakiola.floret.identity.fadeThrough
 import de.jeanlucmakiola.calendula.ui.common.CalendarView
+import de.jeanlucmakiola.calendula.ui.common.drillToDay
 import de.jeanlucmakiola.calendula.ui.common.rememberCalendarSlideSpec
+import de.jeanlucmakiola.calendula.ui.common.selectView
+import de.jeanlucmakiola.calendula.ui.common.viewBaseStack
 import de.jeanlucmakiola.calendula.ui.day.DayScreen
 import de.jeanlucmakiola.calendula.ui.detail.EventDetailScreen
 import de.jeanlucmakiola.calendula.ui.edit.EventEditScreen
+import de.jeanlucmakiola.calendula.ui.edit.ImportSource
+import de.jeanlucmakiola.calendula.ui.imports.ImportScreen
 import de.jeanlucmakiola.calendula.ui.month.MonthScreen
+import de.jeanlucmakiola.calendula.ui.search.SearchScreen
 import de.jeanlucmakiola.calendula.ui.settings.SettingsScreen
 import de.jeanlucmakiola.calendula.ui.week.WeekScreen
 import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Clock
 
 /**
- * Holds the active top-level view (spec M1) and swaps between the calendar
+ * Holds the top-level view back stack (spec M1) and swaps between the calendar
  * screens. Each screen owns its own ViewModel and date anchor; the view-switcher
  * pill in their top bars writes back here via [onSelectView].
+ *
+ * The stack's bottom is the user's [CalendarHostViewModel.defaultView] home view.
+ * A lateral switch (pill / drawer) builds a visit history so back retraces it
+ * (see [selectView]); a widget launch resets the stack to its own view; a date
+ * tap drills the day view on top. Pressing back pops one level, and the
+ * base-level [BackHandler] hands off to the system to exit once only the home
+ * view remains. So back from a widget-opened screen returns to that widget's
+ * view, then home; and back through pill switches walks the views in reverse.
+ *
+ * [requestedDetailKey] is an externally requested occurrence (a tapped
+ * reminder notification routed through MainActivity): it opens the detail
+ * overlay exactly like an event tap and is cleared via [onDetailKeyConsumed]
+ * so a later recomposition can't re-open it. (A widget event tap instead arrives
+ * as [WidgetNavRequest.OpenEvent], which also roots the back stack in the
+ * widget's view.)
  */
 @Composable
-fun CalendarHost(modifier: Modifier = Modifier) {
-    var view by rememberSaveable { mutableStateOf(CalendarView.Week) }
-    val onSelectView: (CalendarView) -> Unit = { view = it }
+fun CalendarHost(
+    modifier: Modifier = Modifier,
+    requestedDetailKey: LongArray? = null,
+    onDetailKeyConsumed: () -> Unit = {},
+    widgetNavRequest: WidgetNavRequest? = null,
+    onWidgetNavConsumed: () -> Unit = {},
+    requestedImportUri: android.net.Uri? = null,
+    onImportConsumed: () -> Unit = {},
+    requestedInsertForm: EventForm? = null,
+    requestedInsertSource: ImportSource = ImportSource.Insert,
+    onInsertConsumed: () -> Unit = {},
+    requestedEditKey: LongArray? = null,
+    onEditKeyConsumed: () -> Unit = {},
+    viewModel: CalendarHostViewModel = hiltViewModel(),
+) {
+    // Wait for the persisted default view before seeding the stack, so the app
+    // opens straight on the user's choice instead of flashing a placeholder and
+    // correcting it. Brief blank first frame, matching the onboarding gate above.
+    val defaultView = viewModel.defaultView.collectAsStateWithLifecycle().value ?: return
+
+    // View customisation (#24): the quick-switch cycle and drawer order. Both have
+    // sensible non-empty initial values, so they're ready before the first frame.
+    val quickSwitchViews = viewModel.quickSwitchViews.collectAsStateWithLifecycle().value
+    val drawerViewOrder = viewModel.drawerViewOrder.collectAsStateWithLifecycle().value
+    // Whether the jump-to-today control sits in each view's top bar or the FAB (#60).
+    val todayInToolbar = viewModel.todayButtonInToolbar.collectAsStateWithLifecycle().value
+
+    var viewStack by rememberSaveable(stateSaver = viewStackSaver) {
+        mutableStateOf(listOf(defaultView))
+    }
+    val view = viewStack.last()
+    val onSelectView: (CalendarView) -> Unit = { viewStack = viewStack.selectView(it) }
 
     // Tapping a day in the month grid opens the day view anchored to that date.
     var pendingDayIso by rememberSaveable { mutableStateOf<String?>(null) }
     val onOpenDay: (LocalDate) -> Unit = { date ->
         pendingDayIso = date.toString()
-        view = CalendarView.Day
+        viewStack = viewStack.drillToDay()
     }
 
     // The event-detail screen (S4) is a full-screen destination hoisted here so
@@ -61,19 +125,48 @@ fun CalendarHost(modifier: Modifier = Modifier) {
         detailKey = key
     }
 
+    // A tapped reminder notification asks for a specific occurrence.
+    LaunchedEffect(requestedDetailKey) {
+        if (requestedDetailKey != null) {
+            heldKey = requestedDetailKey
+            detailKey = requestedDetailKey
+            onDetailKeyConsumed()
+        }
+    }
+
     // Settings (M4) is hoisted here so it overlays whichever calendar view is
     // active and survives view switches. (The calendar filter now lives inline
     // in the navigation drawer, so no overlay state is needed for it.)
     var showSettings by rememberSaveable { mutableStateOf(false) }
     val onOpenSettings = { showSettings = true }
 
+    // Full-text search — its own overlay, opened from each calendar screen's
+    // top bar. Sits below the detail/edit overlays so tapping a result reveals
+    // the detail on top and backing out returns to the results.
+    var showSearch by rememberSaveable { mutableStateOf(false) }
+    val onOpenSearch = { showSearch = true }
+
+    // Calendar manager (reached from Settings) — its own overlay so it slides
+    // over Settings and survives view switches.
+    var showCalendars by rememberSaveable { mutableStateOf(false) }
+
+    // Backup & restore (#69) — hoisted like the manager, being driven by the
+    // calendar list rather than by preferences. Reached from both.
+    var showBackup by rememberSaveable { mutableStateOf(false) }
+
     // Event form (v1.2 create) — same held-key pattern as the detail screen:
     // [heldCreateIso] keeps the prefill date alive through the slide-out.
+    // [createStartMinutes] is the tapped slot's start (minutes from midnight)
+    // when the form is opened from a day/week grid tap; null from the FAB.
     var createDateIso by rememberSaveable { mutableStateOf<String?>(null) }
     var heldCreateIso by remember { mutableStateOf<String?>(null) }
-    val onCreateEvent: (LocalDate) -> Unit = { date ->
+    var createStartMinutes by rememberSaveable { mutableStateOf<Int?>(null) }
+    var heldCreateMinutes by remember { mutableStateOf<Int?>(null) }
+    val onCreateEvent: (LocalDate, Int?) -> Unit = { date, startMinutes ->
         heldCreateIso = date.toString()
         createDateIso = date.toString()
+        heldCreateMinutes = startMinutes
+        createStartMinutes = startMinutes
     }
 
     // Edit form (v1.3) — reuses the detail screen's occurrence key; for
@@ -85,31 +178,206 @@ fun CalendarHost(modifier: Modifier = Modifier) {
     var editKey by rememberSaveable { mutableStateOf<LongArray?>(null) }
     var heldEditKey by remember { mutableStateOf<LongArray?>(null) }
 
+    // An opened/received .ics file. [ImportScreen] parses it and either opens
+    // the prefilled create form (one event → [importForm]) or its own bulk
+    // picker (many). A plain conditional overlay (no slide) — it's transient.
+    var importUri by remember { mutableStateOf<android.net.Uri?>(null) }
+    var importForm by remember { mutableStateOf<EventForm?>(null) }
+    // Which channel filled [importForm]: an .ics file (prompt to apply the default
+    // reminder) or an ACTION_INSERT intent (apply it automatically) — #49.
+    var importFormSource by remember { mutableStateOf(ImportSource.File) }
+    // A restore (in-app "Restore from .ics" button) always runs the full import
+    // flow — picker + summary — even for a single-event file, because the intent
+    // is "restore a backup", not "add this one event". An externally opened .ics
+    // keeps routing a single event straight into the prefilled create form.
+    var importForceMany by remember { mutableStateOf(false) }
+    LaunchedEffect(requestedImportUri) {
+        if (requestedImportUri != null) {
+            importUri = requestedImportUri
+            importForceMany = false
+            onImportConsumed()
+        }
+    }
+    // An external ACTION_INSERT launch (another app/widget creating an event,
+    // issue #30) arrives already prefilled — open it in the same create form the
+    // single-event .ics path uses. [importForm] is the topmost overlay, so it
+    // reveals on top of whatever was open without extra dismissal.
+    LaunchedEffect(requestedInsertForm) {
+        if (requestedInsertForm != null) {
+            importFormSource = requestedInsertSource
+            importForm = requestedInsertForm
+            onInsertConsumed()
+        }
+    }
+
+    // Close every overlay that can sit over the calendar, so an externally
+    // requested destination (a widget/shortcut/QS-tile launch) is revealed on
+    // top instead of underneath whatever the user had open.
+    fun dismissCoveringOverlays() {
+        showSettings = false
+        showCalendars = false
+        showBackup = false
+        detailKey = null
+        editKey = null
+        importUri = null
+        importForm = null
+    }
+
+    // An external "edit this event" (ACTION_EDIT, e.g. an assistant/task app or
+    // widget) opens the occurrence straight in the edit form. Drop any covering
+    // overlay first — the edit overlay sits below Settings/import in the Box, so
+    // without this it would open hidden underneath them. Same held-key pattern as
+    // a detail-screen "Edit" tap; a saved edit just returns to the calendar.
+    LaunchedEffect(requestedEditKey) {
+        if (requestedEditKey != null) {
+            dismissCoveringOverlays()
+            heldEditKey = requestedEditKey
+            editKey = requestedEditKey
+            onEditKeyConsumed()
+        }
+    }
+
+    // A home-screen widget launch asks to open a date (→ day view), open an
+    // event's detail, or start a create. Handled once and cleared, mirroring
+    // [requestedDetailKey]. Date/event opens root the stack in the widget's own
+    // view so backing out returns there (then home), not to the default.
+    LaunchedEffect(widgetNavRequest) {
+        when (val req = widgetNavRequest) {
+            is WidgetNavRequest.OpenDate -> {
+                // Drill the day view in over the widget's view: drop any overlay
+                // that would cover it, so the open doesn't land under Settings/form.
+                dismissCoveringOverlays()
+                createDateIso = null
+                pendingDayIso = req.dateIso
+                // No widget source (an external date tap) roots over the default
+                // home view, so backing out of the day returns home then exits.
+                viewStack = viewBaseStack(defaultView, req.source ?: defaultView).drillToDay()
+                onWidgetNavConsumed()
+            }
+            is WidgetNavRequest.OpenEvent -> {
+                // Root the stack in the widget's view, then open the occurrence
+                // detail over it (same key shape as a tapped event / reminder).
+                dismissCoveringOverlays()
+                createDateIso = null
+                viewStack = viewBaseStack(defaultView, req.source)
+                val key = longArrayOf(req.eventId, req.beginMillis, req.endMillis)
+                heldKey = key
+                detailKey = key
+                onWidgetNavConsumed()
+            }
+            is WidgetNavRequest.OpenView -> {
+                // A widget header tap: land on a top-level view with no date
+                // drill-in. Reveal it by dropping any covering overlay, then root
+                // the stack on the target (null → the default home) over the
+                // default home — so backing out returns to the default, then exits.
+                dismissCoveringOverlays()
+                createDateIso = null
+                pendingDayIso = null
+                viewStack = viewBaseStack(defaultView, req.view ?: defaultView)
+                onWidgetNavConsumed()
+            }
+            is WidgetNavRequest.Create -> {
+                // External "new event" entries (QS tile / launcher shortcut /
+                // widget) must land on top of whatever is open — the form overlay
+                // sits below Settings/calendars in the Box, so without this it
+                // would open hidden underneath them.
+                dismissCoveringOverlays()
+                val iso = req.dateIso ?: Clock.System.now()
+                    .toLocalDateTime(TimeZone.currentSystemDefault()).date.toString()
+                heldCreateIso = iso
+                createDateIso = iso
+                heldCreateMinutes = null
+                createStartMinutes = null
+                onWidgetNavConsumed()
+            }
+            null -> {}
+        }
+    }
+
     val slideSpec = rememberCalendarSlideSpec()
 
+    // Base-level back: pop the view stack while no overlay covers it (each overlay
+    // owns its own BackHandler and takes precedence). Disabled at the home view,
+    // so back there falls through to the system and exits the app.
+    val anyOverlayVisible = showSearch || detailKey != null || createDateIso != null ||
+        editKey != null || showSettings || showCalendars || showBackup ||
+        importUri != null || importForm != null
+    BackHandler(enabled = !anyOverlayVisible && viewStack.size > 1) {
+        viewStack = viewStack.dropLast(1)
+    }
+
     Box(modifier = modifier.fillMaxSize()) {
-        when (view) {
+        // Switching between the peer views (month/week/day/agenda) is lateral
+        // navigation, so it fades through rather than sliding — paging *within* a
+        // view keeps the directional slide. AnimatedContent keyed on the view type.
+        val viewSwitch = fadeThrough()
+        AnimatedContent(
+            targetState = view,
+            transitionSpec = { viewSwitch },
+            label = "view-switch",
+        ) { currentView ->
+            when (currentView) {
                 CalendarView.Week -> WeekScreen(
-                selectedView = view,
-                onSelectView = onSelectView,
-                onEventClick = onEventClick,
-                onOpenSettings = onOpenSettings,
-                onCreateEvent = onCreateEvent,
-            )
-            CalendarView.Day -> DayScreen(
-                selectedView = view,
-                onSelectView = onSelectView,
-                onEventClick = onEventClick,
-                onOpenSettings = onOpenSettings,
-                onCreateEvent = onCreateEvent,
-                initialDateIso = pendingDayIso,
-            )
-            CalendarView.Month -> MonthScreen(
-                selectedView = view,
+                    selectedView = currentView,
                     onSelectView = onSelectView,
                     onOpenDay = onOpenDay,
+                    onEventClick = onEventClick,
                     onOpenSettings = onOpenSettings,
+                    onOpenSearch = onOpenSearch,
                     onCreateEvent = onCreateEvent,
+                    quickSwitchViews = quickSwitchViews,
+                    drawerViewOrder = drawerViewOrder,
+                    todayInToolbar = todayInToolbar,
+                )
+                CalendarView.Day -> DayScreen(
+                    selectedView = currentView,
+                    onSelectView = onSelectView,
+                    onEventClick = onEventClick,
+                    onOpenSettings = onOpenSettings,
+                    onOpenSearch = onOpenSearch,
+                    onCreateEvent = onCreateEvent,
+                    initialDateIso = pendingDayIso,
+                    quickSwitchViews = quickSwitchViews,
+                    drawerViewOrder = drawerViewOrder,
+                    todayInToolbar = todayInToolbar,
+                )
+                CalendarView.Month -> MonthScreen(
+                    selectedView = currentView,
+                    onSelectView = onSelectView,
+                    onOpenDay = onOpenDay,
+                    onEventClick = onEventClick,
+                    onOpenSettings = onOpenSettings,
+                    onOpenSearch = onOpenSearch,
+                    onCreateEvent = onCreateEvent,
+                    quickSwitchViews = quickSwitchViews,
+                    drawerViewOrder = drawerViewOrder,
+                    todayInToolbar = todayInToolbar,
+                )
+                CalendarView.Agenda -> AgendaScreen(
+                    selectedView = currentView,
+                    onSelectView = onSelectView,
+                    onOpenDay = onOpenDay,
+                    onEventClick = onEventClick,
+                    onOpenSettings = onOpenSettings,
+                    onOpenSearch = onOpenSearch,
+                    onCreateEvent = onCreateEvent,
+                    quickSwitchViews = quickSwitchViews,
+                    drawerViewOrder = drawerViewOrder,
+                    todayInToolbar = todayInToolbar,
+                )
+            }
+        }
+
+        // Search overlay — below detail/edit in the Box so a tapped result's
+        // detail screen draws on top, and closing it returns to the results.
+        AnimatedVisibility(
+            visible = showSearch,
+            enter = slideInHorizontally(slideSpec) { it } + fadeIn(),
+            exit = slideOutHorizontally(slideSpec) { it } + fadeOut(),
+        ) {
+            SearchScreen(
+                onBack = { showSearch = false },
+                onEventClick = onEventClick,
             )
         }
 
@@ -130,6 +398,14 @@ fun CalendarHost(modifier: Modifier = Modifier) {
                         heldEditKey = key
                         editKey = key
                     },
+                    onDuplicate = { form ->
+                        // Reuse the prefilled-create overlay: a duplicate is a
+                        // fresh event, so it applies the default reminder like an
+                        // in-app new event (#52).
+                        importFormSource = ImportSource.Insert
+                        importForm = form
+                        detailKey = null
+                    },
                 )
             }
         }
@@ -143,8 +419,10 @@ fun CalendarHost(modifier: Modifier = Modifier) {
             (createDateIso ?: heldCreateIso)?.let { iso ->
                 EventEditScreen(
                     initialDateIso = iso,
+                    initialStartMinutes = createStartMinutes ?: heldCreateMinutes,
                     onClose = { createDateIso = null },
                     onSaved = { createDateIso = null },
+                    onManageCalendars = { showCalendars = true },
                 )
             }
         }
@@ -164,6 +442,7 @@ fun CalendarHost(modifier: Modifier = Modifier) {
                         editKey = null
                         detailKey = null
                     },
+                    onManageCalendars = { showCalendars = true },
                 )
             }
         }
@@ -174,7 +453,76 @@ fun CalendarHost(modifier: Modifier = Modifier) {
             enter = slideInHorizontally(slideSpec) { it } + fadeIn(),
             exit = slideOutHorizontally(slideSpec) { it } + fadeOut(),
         ) {
-            SettingsScreen(onBack = { showSettings = false })
+            SettingsScreen(
+                onBack = { showSettings = false },
+                onManageCalendars = { showCalendars = true },
+                onOpenBackup = { showBackup = true },
+            )
+        }
+
+        // Import flow for an opened/received .ics file. A single event routes
+        // into the create form (prefilled, for review); many open the picker.
+        importUri?.let { uri ->
+            ImportScreen(
+                uri = uri,
+                forceMany = importForceMany,
+                onClose = { importUri = null },
+                onManageCalendars = { showCalendars = true },
+                onOpenSingle = { form ->
+                    importUri = null
+                    importFormSource = ImportSource.File
+                    importForm = form
+                },
+            )
+        }
+        importForm?.let { form ->
+            EventEditScreen(
+                initialDateIso = null,
+                initialForm = form,
+                initialFormSource = importFormSource,
+                onClose = { importForm = null },
+                onSaved = { importForm = null },
+                onManageCalendars = { showCalendars = true },
+            )
+        }
+
+        // Declared last so it covers every overlay that can open it: Settings,
+        // both event forms, and the .ics import picker (#76).
+        AnimatedVisibility(
+            visible = showCalendars,
+            enter = slideInHorizontally(slideSpec) { it } + fadeIn(),
+            exit = slideOutHorizontally(slideSpec) { it } + fadeOut(),
+        ) {
+            CalendarsScreen(
+                onBack = { showCalendars = false },
+                onOpenBackup = { showBackup = true },
+            )
+        }
+
+        // Backup & restore — over the manager, since the manager links into it.
+        AnimatedVisibility(
+            visible = showBackup,
+            enter = slideInHorizontally(slideSpec) { it } + fadeIn(),
+            exit = slideOutHorizontally(slideSpec) { it } + fadeOut(),
+        ) {
+            BackupScreen(
+                onBack = { showBackup = false },
+                // Restore runs the normal .ics import, and both this screen and
+                // the manager that can have opened it are declared above the
+                // import overlays — so both have to step aside.
+                onImport = {
+                    importUri = it
+                    importForceMany = true
+                    showBackup = false
+                    showCalendars = false
+                },
+            )
         }
     }
 }
+
+/** Persists the view back stack across config change / process death by ordinal. */
+private val viewStackSaver = listSaver<List<CalendarView>, Int>(
+    save = { stack -> stack.map(CalendarView::ordinal) },
+    restore = { ordinals -> ordinals.map { CalendarView.entries[it] } },
+)

app/src/main/java/de/jeanlucmakiola/calendula/ui/CalendarHostViewModel.kt

@@ -0,0 +1,56 @@
+package de.jeanlucmakiola.calendula.ui
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import dagger.hilt.android.lifecycle.HiltViewModel
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.ui.common.CalendarView
+import de.jeanlucmakiola.calendula.ui.common.IMPLEMENTED_VIEWS
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+import javax.inject.Inject
+
+/**
+ * Supplies [CalendarHost] with the user's default startup view (M1). Held as a
+ * nullable [StateFlow] so the host can wait for DataStore's first emission before
+ * seeding its view back stack — rendering nothing for that first frame rather
+ * than flashing the old hard-coded Week view and then correcting it.
+ */
+@HiltViewModel
+class CalendarHostViewModel @Inject constructor(
+    prefs: SettingsPrefs,
+) : ViewModel() {
+
+    val defaultView: StateFlow<CalendarView?> = prefs.defaultView.stateIn(
+        scope = viewModelScope,
+        started = SharingStarted.WhileSubscribed(5_000L),
+        initialValue = null,
+    )
+
+    /** Views the top-bar quick-switch pill cycles through, in the user's order (#24). */
+    val quickSwitchViews: StateFlow<List<CalendarView>> = prefs.quickSwitchConfig
+        .map { it.cycle }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = IMPLEMENTED_VIEWS,
+        )
+
+    /** Order of the views in the navigation drawer (#24); every view always shown. */
+    val drawerViewOrder: StateFlow<List<CalendarView>> = prefs.drawerViewOrder
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = IMPLEMENTED_VIEWS,
+        )
+
+    /** Whether each view's jump-to-today control lives in the top bar, not the FAB (#60). */
+    val todayButtonInToolbar: StateFlow<Boolean> = prefs.todayButtonInToolbar
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = false,
+        )
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/RootScreen.kt

@@ -2,22 +2,49 @@ package de.jeanlucmakiola.calendula.ui
 
 import android.Manifest
 import android.content.pm.PackageManager
+import androidx.compose.animation.Crossfade
+import androidx.compose.material3.ExperimentalMaterial3ExpressiveApi
+import androidx.compose.material3.MaterialTheme
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.runtime.getValue
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
+import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.LocalLifecycleOwner
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.core.content.ContextCompat
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleEventObserver
+import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesScheduler
+import de.jeanlucmakiola.calendula.data.contacts.hasContactsPermission
+import de.jeanlucmakiola.calendula.ui.calendars.CalendarVisibilityNoticeDialog
+import de.jeanlucmakiola.calendula.ui.calendars.CalendarVisibilityNoticeViewModel
 import de.jeanlucmakiola.calendula.ui.permission.PermissionScreen
+import de.jeanlucmakiola.calendula.ui.permission.ReminderOnboardingScreen
+import de.jeanlucmakiola.calendula.ui.permission.ReminderOnboardingViewModel
 
+@OptIn(ExperimentalMaterial3ExpressiveApi::class)
 @Composable
-fun RootScreen(modifier: Modifier = Modifier) {
+fun RootScreen(
+    modifier: Modifier = Modifier,
+    requestedDetailKey: LongArray? = null,
+    onDetailKeyConsumed: () -> Unit = {},
+    widgetNavRequest: WidgetNavRequest? = null,
+    onWidgetNavConsumed: () -> Unit = {},
+    requestedImportUri: android.net.Uri? = null,
+    onImportConsumed: () -> Unit = {},
+    requestedInsertForm: de.jeanlucmakiola.calendula.domain.EventForm? = null,
+    requestedInsertSource: de.jeanlucmakiola.calendula.ui.edit.ImportSource =
+        de.jeanlucmakiola.calendula.ui.edit.ImportSource.Insert,
+    onInsertConsumed: () -> Unit = {},
+    requestedEditKey: LongArray? = null,
+    onEditKeyConsumed: () -> Unit = {},
+) {
     val context = LocalContext.current
     var hasPermission by remember {
         mutableStateOf(
@@ -26,6 +53,10 @@ fun RootScreen(modifier: Modifier = Modifier) {
         )
     }
 
+    // A launch scan already covers the app coming up with the permission, so
+    // only a grant made during this session owes a re-scan.
+    val grantedAtLaunch = remember { hasPermission }
+
     val lifecycle = LocalLifecycleOwner.current.lifecycle
     DisposableEffect(lifecycle) {
         val obs = LifecycleEventObserver { _, event ->
@@ -33,18 +64,70 @@ fun RootScreen(modifier: Modifier = Modifier) {
                 hasPermission = ContextCompat.checkSelfPermission(
                     context, Manifest.permission.READ_CALENDAR
                 ) == PackageManager.PERMISSION_GRANTED
+                // Refresh the contact special-dates mirror on foreground (the
+                // worker is debounced and no-ops when the feature is off). Gated
+                // on the permission so users without the opt-in never enqueue it.
+                if (context.hasContactsPermission()) {
+                    SpecialDatesScheduler.runNow(context, foreground = true)
+                }
             }
         }
         lifecycle.addObserver(obs)
         onDispose { lifecycle.removeObserver(obs) }
     }
 
-    if (hasPermission) {
-        CalendarHost(modifier = modifier)
+    // Cross-fade the one-time onboarding gates so granting permission / finishing
+    // onboarding eases into the next screen instead of snapping. A fade carries no
+    // spatial motion, so it stays appropriate under "remove animations" too.
+    val gateSpec = MaterialTheme.motionScheme.fastEffectsSpec<Float>()
+    Crossfade(targetState = hasPermission, animationSpec = gateSpec, label = "permissionGate") { granted ->
+        if (granted) {
+            // Second onboarding gate (v1.4, one-time): reminder notifications.
+            // Null until DataStore's first emission — render nothing for that
+            // frame instead of flashing the wrong screen.
+            val reminderOnboarding: ReminderOnboardingViewModel = hiltViewModel()
+            val onboardingDone by reminderOnboarding.onboardingDone.collectAsStateWithLifecycle()
+            // One-time explainer for the switch to the device's own calendar
+            // visibility (#75), armed by the reconciler.
+            val visibilityNotice: CalendarVisibilityNoticeViewModel = hiltViewModel()
+            val noticePending by visibilityNotice.pending.collectAsStateWithLifecycle()
+            // Runs on entry however the permission was granted, including via
+            // Android's app-settings screen (caught by the ON_RESUME above).
+            LaunchedEffect(Unit) {
+                visibilityNotice.reconcile()
+                if (!grantedAtLaunch) reminderOnboarding.rearmAfterGrant()
+            }
+            if (onboardingDone == true && noticePending) {
+                CalendarVisibilityNoticeDialog(onDismiss = visibilityNotice::dismiss)
+            }
+            Crossfade(targetState = onboardingDone, animationSpec = gateSpec, label = "onboardingGate") { done ->
+                when (done) {
+                    true -> CalendarHost(
+                        modifier = modifier,
+                        requestedDetailKey = requestedDetailKey,
+                        onDetailKeyConsumed = onDetailKeyConsumed,
+                        widgetNavRequest = widgetNavRequest,
+                        onWidgetNavConsumed = onWidgetNavConsumed,
+                        requestedImportUri = requestedImportUri,
+                        onImportConsumed = onImportConsumed,
+                        requestedInsertForm = requestedInsertForm,
+                        requestedInsertSource = requestedInsertSource,
+                        onInsertConsumed = onInsertConsumed,
+                        requestedEditKey = requestedEditKey,
+                        onEditKeyConsumed = onEditKeyConsumed,
+                    )
+                    false -> ReminderOnboardingScreen(
+                        onFinished = reminderOnboarding::finish,
+                        modifier = modifier,
+                    )
+                    null -> {}
+                }
+            }
         } else {
             PermissionScreen(
                 onGranted = { hasPermission = true },
                 modifier = modifier,
             )
         }
+    }
 }

app/src/main/java/de/jeanlucmakiola/calendula/ui/WidgetNavRequest.kt

@@ -0,0 +1,43 @@
+package de.jeanlucmakiola.calendula.ui
+
+import de.jeanlucmakiola.calendula.ui.common.CalendarView
+
+/**
+ * A navigation a home-screen widget asked the app to perform when launched.
+ * Parsed from the launch intent in MainActivity and consumed once by
+ * [CalendarHost]. Every request carries the [source] view of the widget it came
+ * from (the agenda widget → [CalendarView.Agenda], the month widget →
+ * [CalendarView.Month]) so the in-app back stack roots itself in that view:
+ * backing out of the opened date/event returns to the widget's own view, not the
+ * default home. (Reminder notifications are not widgets — they keep the separate
+ * detail-key channel and leave the base view untouched.)
+ */
+sealed interface WidgetNavRequest {
+    /**
+     * Open the day view anchored on [dateIso] (an ISO `yyyy-MM-dd` date), over
+     * [source]. A null [source] means the request came from outside the app (a
+     * launcher/clock date tap, issue #9) rather than a widget, so it roots over
+     * the default home view instead of a widget's view.
+     */
+    data class OpenDate(val dateIso: String, val source: CalendarView?) : WidgetNavRequest
+
+    /** Open one occurrence's detail (an agenda-widget event tap), over [source]. */
+    data class OpenEvent(
+        val eventId: Long,
+        val beginMillis: Long,
+        val endMillis: Long,
+        val source: CalendarView,
+    ) : WidgetNavRequest
+
+    /** Open the create-event form prefilled for [dateIso] (today when null). */
+    data class Create(val dateIso: String?) : WidgetNavRequest
+
+    /**
+     * Open the app rooted on a top-level [view] with no date drill-in — a widget
+     * header tap. A null [view] means "the user's default home view" (the agenda
+     * widget's "Upcoming" title, issue #20); a concrete view roots there over the
+     * default home (the month widget's month/year title → [CalendarView.Month],
+     * issue #18), so backing out returns to the default view, then exits.
+     */
+    data class OpenView(val view: CalendarView?) : WidgetNavRequest
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaRange.kt

@@ -0,0 +1,123 @@
+package de.jeanlucmakiola.calendula.ui.agenda
+
+import de.jeanlucmakiola.floret.locale.localizedDateFormatter
+import kotlinx.datetime.DayOfWeek
+import kotlinx.datetime.LocalDate
+import java.time.YearMonth
+import java.util.Locale
+
+/**
+ * How far ahead the agenda (screen or widget) shows events, starting at today.
+ *
+ * Two flavours:
+ * - **Rolling** windows of a fixed length: [Day] (today), [Week] (7 days),
+ *   [Month] (30 days), [Custom] (1–365 days). These never degenerate.
+ * - **Calendar-aligned** windows that end at a period boundary: [ThisWeek] runs
+ *   through the end of the current week (respecting the week-start preference —
+ *   a Monday start means "everything before next Monday"); [ThisMonth] runs
+ *   through the last day of the current month. These shrink as the period ends.
+ */
+sealed interface AgendaRange {
+    data object Day : AgendaRange
+    data object Week : AgendaRange
+    data object Month : AgendaRange
+    data object ThisWeek : AgendaRange
+    data object ThisMonth : AgendaRange
+    data class Custom(val days: Int) : AgendaRange
+
+    companion object {
+        /** Allowed bounds for a [Custom] day count. */
+        const val MIN_CUSTOM_DAYS = 1
+        const val MAX_CUSTOM_DAYS = 365
+    }
+}
+
+private const val DAYS_PER_WEEK = 7
+
+/**
+ * Inclusive number of days the window spans, starting at (and including)
+ * [anchor]. The calendar-aligned ranges depend on the anchor day and, for
+ * [AgendaRange.ThisWeek], the [weekStart] preference.
+ */
+fun AgendaRange.dayCount(anchor: LocalDate, weekStart: DayOfWeek): Int = when (this) {
+    AgendaRange.Day -> 1
+    AgendaRange.Week -> DAYS_PER_WEEK
+    AgendaRange.Month -> 30
+    AgendaRange.ThisWeek -> {
+        // Days elapsed since the week's first day (0 when today *is* the start),
+        // so the window is the rest of the week through the day before it repeats.
+        val sinceWeekStart = ((anchor.dayOfWeek.ordinal - weekStart.ordinal) + DAYS_PER_WEEK) % DAYS_PER_WEEK
+        DAYS_PER_WEEK - sinceWeekStart
+    }
+    AgendaRange.ThisMonth -> {
+        val daysInMonth = YearMonth.of(anchor.year, anchor.month.ordinal + 1).lengthOfMonth()
+        daysInMonth - anchor.day + 1
+    }
+    is AgendaRange.Custom -> days.coerceIn(AgendaRange.MIN_CUSTOM_DAYS, AgendaRange.MAX_CUSTOM_DAYS)
+}
+
+/** Stored representation: a fixed token, or `CUSTOM:<days>`. */
+fun AgendaRange.storageValue(): String = when (this) {
+    AgendaRange.Day -> "DAY"
+    AgendaRange.Week -> "WEEK"
+    AgendaRange.Month -> "MONTH"
+    AgendaRange.ThisWeek -> "THIS_WEEK"
+    AgendaRange.ThisMonth -> "THIS_MONTH"
+    is AgendaRange.Custom -> "$CUSTOM_PREFIX$days"
+}
+
+/** Parse a stored value; unknown/garbage falls back to [default]. */
+fun parseAgendaRange(stored: String?, default: AgendaRange): AgendaRange = when {
+    stored == "DAY" -> AgendaRange.Day
+    stored == "WEEK" -> AgendaRange.Week
+    stored == "MONTH" -> AgendaRange.Month
+    stored == "THIS_WEEK" -> AgendaRange.ThisWeek
+    stored == "THIS_MONTH" -> AgendaRange.ThisMonth
+    stored != null && stored.startsWith(CUSTOM_PREFIX) -> {
+        val days = stored.removePrefix(CUSTOM_PREFIX).toIntOrNull()
+        if (days != null) {
+            AgendaRange.Custom(days.coerceIn(AgendaRange.MIN_CUSTOM_DAYS, AgendaRange.MAX_CUSTOM_DAYS))
+        } else {
+            default
+        }
+    }
+    else -> default
+}
+
+/**
+ * The concrete span the range covers, starting at [start] through [end]
+ * (inclusive), for a human-readable header. Both ends use the same day-month
+ * order so a span never mixes "15 Jul" with "Aug 13, 2026":
+ * - [AgendaRange.Day] → a single date ("27 Jun 2026")
+ * - [AgendaRange.ThisMonth] → month and year ("June 2026")
+ * - everything else → "start – end" ("27 Jun – 3 Jul 2026"), with the start's
+ *   year shown too only when it differs from the end's.
+ *
+ * [monthAsSpan] puts [AgendaRange.ThisMonth] on the "start – end" form as well.
+ * The agenda's own header browses the whole month, so the month name is right
+ * there; the range picker previews the window an option opens *today*, which for
+ * "This month" is only the rest of it.
+ */
+fun agendaRangeWindowSummary(
+    range: AgendaRange,
+    start: LocalDate,
+    end: LocalDate,
+    locale: Locale,
+    monthAsSpan: Boolean = false,
+): String {
+    val javaStart = java.time.LocalDate.of(start.year, start.month.ordinal + 1, start.day)
+    val javaEnd = java.time.LocalDate.of(end.year, end.month.ordinal + 1, end.day)
+    val dayMonth = localizedDateFormatter(locale, "dMMM")
+    val dayMonthYear = localizedDateFormatter(locale, "dMMMy")
+    return when {
+        range == AgendaRange.Day -> dayMonthYear.format(javaStart)
+        range == AgendaRange.ThisMonth && !monthAsSpan ->
+            localizedDateFormatter(locale, "LLLLy").format(javaStart)
+        else -> {
+            val startFmt = if (start.year == end.year) dayMonth else dayMonthYear
+            "${startFmt.format(javaStart)} – ${dayMonthYear.format(javaEnd)}"
+        }
+    }
+}
+
+private const val CUSTOM_PREFIX = "CUSTOM:"

app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaRows.kt

@@ -0,0 +1,207 @@
+package de.jeanlucmakiola.calendula.ui.agenda
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Coffee
+import androidx.compose.material3.Card
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.alpha
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.ui.common.EventDimAlpha
+import de.jeanlucmakiola.calendula.ui.common.LocalSoftenColors
+import de.jeanlucmakiola.calendula.ui.common.LocalUse24HourFormat
+import de.jeanlucmakiola.calendula.ui.common.eventAccent
+import de.jeanlucmakiola.calendula.ui.common.eventFill
+import de.jeanlucmakiola.calendula.ui.common.formatTimeOfDay
+import de.jeanlucmakiola.floret.components.GroupedRow
+import de.jeanlucmakiola.floret.components.Position
+import de.jeanlucmakiola.floret.locale.currentLocale
+import de.jeanlucmakiola.floret.locale.localizedDateFormatter
+import kotlinx.datetime.DateTimeUnit
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.plus
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Instant
+import java.util.Locale
+
+// The agenda's row vocabulary, split out of AgendaScreen so the month view's
+// split style can list a day with exactly the same visual language instead of
+// growing a parallel set of event rows.
+
+@Composable
+internal fun AgendaDayHeader(
+    date: LocalDate,
+    today: LocalDate,
+    onOpenDay: (LocalDate) -> Unit,
+) {
+    Surface(
+        color = MaterialTheme.colorScheme.surface,
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable { onOpenDay(date) },
+    ) {
+        Text(
+            text = agendaDayLabel(date, today),
+            style = MaterialTheme.typography.titleSmall,
+            color = if (date == today) {
+                MaterialTheme.colorScheme.primary
+            } else {
+                MaterialTheme.colorScheme.onSurfaceVariant
+            },
+            modifier = Modifier.padding(start = 28.dp, end = 28.dp, top = 16.dp, bottom = 8.dp),
+        )
+    }
+}
+
+/**
+ * A card standing in for a day with no events — the same coffee-cup motif as the
+ * agenda's full-screen empty state, boxed into a card so the day keeps a visible slot
+ * rather than a bare header. Used for an anchored, event-less today (#35) and for
+ * an empty selected day in the month view's split style.
+ */
+@Composable
+internal fun AgendaEmptyDayRow(text: String, onClick: () -> Unit) {
+    Card(
+        // Match a single event row's resting corner radius (floret groupedShape).
+        shape = RoundedCornerShape(22.dp),
+        modifier = Modifier
+            .fillMaxWidth()
+            .padding(horizontal = 16.dp, vertical = 4.dp)
+            .clickable(onClick = onClick),
+    ) {
+        Column(
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(vertical = 18.dp, horizontal = 16.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+        ) {
+            Icon(
+                imageVector = Icons.Filled.Coffee,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.size(36.dp),
+            )
+            Spacer(Modifier.height(8.dp))
+            Text(
+                text = text,
+                style = MaterialTheme.typography.bodyLarge,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                textAlign = TextAlign.Center,
+            )
+        }
+    }
+}
+
+@Composable
+internal fun AgendaEventRow(
+    event: EventInstance,
+    day: LocalDate,
+    zone: TimeZone,
+    position: Position,
+    dimmed: Boolean,
+    modifier: Modifier = Modifier,
+    onClick: () -> Unit,
+) {
+    val dark = isSystemInDarkTheme()
+    val soften = LocalSoftenColors.current
+    val title = event.title.ifBlank { stringResource(R.string.event_untitled) }
+    GroupedRow(
+        modifier = if (dimmed) modifier.alpha(EventDimAlpha) else modifier,
+        title = title,
+        summary = agendaTimeSummary(event, day, zone),
+        position = position,
+        minHeight = 64.dp,
+        leading = {
+            Box(
+                modifier = Modifier
+                    .size(width = 6.dp, height = 36.dp)
+                    .clip(RoundedCornerShape(3.dp))
+                    .background(eventAccent(event.color, dark, soften)),
+            )
+        },
+        onClick = onClick,
+    )
+}
+
+/** "Today · Wed, 17. Jun 2026" — relative word for today/tomorrow, else the date. */
+@Composable
+internal fun agendaDayLabel(date: LocalDate, today: LocalDate): String {
+    val relative = when (date) {
+        today -> stringResource(R.string.agenda_header_today)
+        today.plus(1, DateTimeUnit.DAY) -> stringResource(R.string.agenda_header_tomorrow)
+        else -> null
+    }
+    val formatted = formatAgendaDate(date)
+    return if (relative != null) "$relative · $formatted" else formatted
+}
+
+/**
+ * Time line under the title: "09:00 – 10:00 · Location", "All day", etc.
+ *
+ * A multi-day event shows only the part relevant to [day], spelled out so each
+ * day reads on its own: its first day names the start ("Starts 14:00"), its last
+ * day the end ("Ends 10:00"), and any whole day in between reads as "All day".
+ * An all-day multi-day event is simply "All day" on every day it covers.
+ */
+@Composable
+internal fun agendaTimeSummary(event: EventInstance, day: LocalDate, zone: TimeZone): String {
+    val is24Hour = LocalUse24HourFormat.current
+    val locale = currentLocale()
+
+    val time = when (val label = agendaTimeLabel(event, day, zone)) {
+        AgendaTimeLabel.AllDay -> stringResource(R.string.event_detail_all_day)
+        is AgendaTimeLabel.Starts -> stringResource(
+            R.string.agenda_span_starts,
+            formatTime(label.start, zone, is24Hour, locale),
+        )
+        is AgendaTimeLabel.Ends -> stringResource(
+            R.string.agenda_span_ends,
+            formatTime(label.end, zone, is24Hour, locale),
+        )
+        is AgendaTimeLabel.Range -> "${formatTime(label.start, zone, is24Hour, locale)} – " +
+            formatTime(label.end, zone, is24Hour, locale)
+    }
+
+    val location = event.location?.takeIf { it.isNotBlank() }
+    return if (location != null) "$time · $location" else time
+}
+
+private fun formatTime(
+    instant: Instant,
+    zone: TimeZone,
+    is24Hour: Boolean,
+    locale: Locale,
+): String {
+    val t = instant.toLocalDateTime(zone).time
+    return formatTimeOfDay(t.hour, t.minute, is24Hour, locale)
+}
+
+private fun formatAgendaDate(date: LocalDate): String {
+    val locale = Locale.getDefault()
+    val java = java.time.LocalDate.of(date.year, date.month.ordinal + 1, date.day)
+    // Weekday + date in the locale's own field order (e.g. "Wed, Jun 17, 2026"
+    // vs "Mi., 17. Juni 2026") rather than a hardcoded day-month-year layout.
+    return localizedDateFormatter(locale, "EEEdMMMy").format(java)
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaScreen.kt

@@ -0,0 +1,453 @@
+package de.jeanlucmakiola.calendula.ui.agenda
+
+import androidx.compose.foundation.ExperimentalFoundationApi
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Coffee
+import androidx.compose.material.icons.filled.Menu
+import androidx.compose.material.icons.filled.Search
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.DrawerValue
+import androidx.compose.material3.FilledTonalButton
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalNavigationDrawer
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.TopAppBarDefaults
+import androidx.compose.material3.TopAppBarScrollBehavior
+import androidx.compose.material3.rememberDrawerState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.input.nestedscroll.nestedScroll
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.prefs.PastEventDisplay
+import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.hasEnded
+import de.jeanlucmakiola.calendula.ui.common.AgendaRangePicker
+import de.jeanlucmakiola.calendula.ui.common.agendaRangeLabel
+import de.jeanlucmakiola.floret.identity.animateItemMotion
+import de.jeanlucmakiola.calendula.ui.common.CalendarDrawer
+import de.jeanlucmakiola.calendula.ui.common.CalendarFabColumn
+import de.jeanlucmakiola.calendula.ui.common.TodayAction
+import de.jeanlucmakiola.calendula.ui.common.CalendarFailure
+import de.jeanlucmakiola.calendula.ui.common.CalendarView
+import de.jeanlucmakiola.calendula.ui.common.IMPLEMENTED_VIEWS
+import de.jeanlucmakiola.calendula.ui.common.ViewSwitcherPill
+import de.jeanlucmakiola.calendula.ui.common.next
+import de.jeanlucmakiola.floret.components.positionOf
+import de.jeanlucmakiola.calendula.ui.common.rememberCurrentMinute
+import de.jeanlucmakiola.floret.locale.currentLocale
+import kotlinx.coroutines.launch
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlin.time.Instant
+
+// No file-level zone constant here on purpose: it would be fixed for the process
+// lifetime and drift from the zone AgendaViewModel groups in after a device
+// time-zone change. The zone travels on AgendaUiState.Success instead.
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun AgendaScreen(
+    selectedView: CalendarView,
+    onSelectView: (CalendarView) -> Unit,
+    onOpenDay: (LocalDate) -> Unit,
+    onEventClick: (EventInstance) -> Unit,
+    onOpenSettings: () -> Unit,
+    onOpenSearch: () -> Unit,
+    onCreateEvent: (LocalDate, Int?) -> Unit,
+    quickSwitchViews: List<CalendarView> = IMPLEMENTED_VIEWS,
+    drawerViewOrder: List<CalendarView> = IMPLEMENTED_VIEWS,
+    todayInToolbar: Boolean = false,
+    modifier: Modifier = Modifier,
+    viewModel: AgendaViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val anchor by viewModel.anchor.collectAsStateWithLifecycle()
+    val pastDisplay by viewModel.pastEventDisplay.collectAsStateWithLifecycle()
+    val showToday by viewModel.showToday.collectAsStateWithLifecycle()
+    val weekStart by viewModel.weekStart.collectAsStateWithLifecycle()
+
+    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
+    val drawerState = rememberDrawerState(DrawerValue.Closed)
+    val scope = rememberCoroutineScope()
+    var showRangePicker by remember { mutableStateOf(false) }
+
+    val isOnToday = when (val s = state) {
+        is AgendaUiState.Success -> s.anchor == s.today
+        else -> true
+    }
+    val successState = state as? AgendaUiState.Success
+
+    ModalNavigationDrawer(
+        drawerState = drawerState,
+        drawerContent = {
+            CalendarDrawer(
+                currentView = selectedView,
+                currentDate = anchor,
+                drawerState = drawerState,
+                viewOrder = drawerViewOrder,
+                onSelectView = { view ->
+                    onSelectView(view)
+                    scope.launch { drawerState.close() }
+                },
+                onJumpToDate = { target ->
+                    viewModel.goToDate(target)
+                    scope.launch { drawerState.close() }
+                },
+                onSettings = {
+                    onOpenSettings()
+                    scope.launch { drawerState.close() }
+                },
+            )
+        },
+    ) {
+        Scaffold(
+            modifier = modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
+            topBar = {
+                AgendaTopBar(
+                    selectedView = selectedView,
+                    onCycleView = { onSelectView(selectedView.next(quickSwitchViews)) },
+                    onOpenDrawer = { scope.launch { drawerState.open() } },
+                    onOpenSearch = onOpenSearch,
+                    showTodayButton = todayInToolbar,
+                    onToday = viewModel::goToToday,
+                    scrollBehavior = scrollBehavior,
+                )
+            },
+            floatingActionButton = {
+                CalendarFabColumn(
+                    todayVisible = !isOnToday && !todayInToolbar,
+                    todayText = stringResource(R.string.agenda_today_action),
+                    onToday = viewModel::goToToday,
+                    onCreate = { onCreateEvent(anchor, null) },
+                )
+            },
+        ) { innerPadding ->
+            Column(
+                modifier = Modifier
+                    .fillMaxSize()
+                    .padding(innerPadding),
+            ) {
+                // One bar at the top: the "showing …" header on the left and the
+                // session range switcher on the right (one settings toggle).
+                successState?.takeIf { it.showRangeBar }?.let { s ->
+                    Row(
+                        verticalAlignment = Alignment.CenterVertically,
+                        // end aligns the selector's right edge with the top-bar view
+                        // switcher (its 8.dp margin + the app bar's 4.dp inset).
+                        modifier = Modifier
+                            .fillMaxWidth()
+                            .padding(start = 28.dp, end = 12.dp, top = 8.dp, bottom = 8.dp),
+                    ) {
+                        AgendaRangeBanner(
+                            range = s.range,
+                            start = s.anchor,
+                            end = s.rangeEnd,
+                            modifier = Modifier.weight(1f),
+                        )
+                        AgendaRangePill(
+                            range = s.range,
+                            isOverride = s.rangeIsOverride,
+                            onClick = { showRangePicker = true },
+                        )
+                    }
+                }
+                AgendaContent(
+                    state = state,
+                    pastDisplay = pastDisplay,
+                    showToday = showToday,
+                    onRetry = viewModel::goToToday,
+                    onEventClick = onEventClick,
+                    onOpenDay = onOpenDay,
+                    modifier = Modifier
+                        .weight(1f)
+                        .fillMaxWidth(),
+                )
+            }
+        }
+    }
+
+    if (showRangePicker) {
+        AgendaRangePicker(
+            title = stringResource(R.string.settings_agenda_range),
+            description = stringResource(R.string.agenda_range_override_hint),
+            selected = successState?.range ?: AgendaRange.Month,
+            weekStart = weekStart,
+            onSelect = viewModel::setRangeOverride,
+            onDismiss = { showRangePicker = false },
+        )
+    }
+}
+
+/**
+ * The agenda's current range, tapped to open the range picker as a session-only
+ * override. Shares the top-bar view switcher's button shape so the two read as a
+ * family, but stays low-emphasis — a subtle neutral surface tint rather than the
+ * switcher's secondary container, so it doesn't compete. Fills with the primary
+ * container only while an override is active, to make that temporary state clear.
+ */
+@Composable
+private fun AgendaRangePill(
+    range: AgendaRange,
+    isOverride: Boolean,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    FilledTonalButton(
+        onClick = onClick,
+        shape = MaterialTheme.shapes.large,
+        colors = ButtonDefaults.filledTonalButtonColors(
+            containerColor = if (isOverride) {
+                MaterialTheme.colorScheme.primaryContainer
+            } else {
+                MaterialTheme.colorScheme.surfaceContainerHigh
+            },
+            contentColor = if (isOverride) {
+                MaterialTheme.colorScheme.onPrimaryContainer
+            } else {
+                MaterialTheme.colorScheme.onSurfaceVariant
+            },
+        ),
+        modifier = modifier,
+    ) {
+        Text(
+            text = agendaRangeLabel(range),
+            style = MaterialTheme.typography.labelLarge,
+        )
+    }
+}
+
+/**
+ * A header naming the concrete window currently shown under a "showing …" label,
+ * e.g. "27 Jun 2026" / "27 Jun – 3 Jul 2026" / "June 2026". The range's name
+ * lives on the selector button beside it, so it isn't repeated here.
+ */
+@Composable
+private fun AgendaRangeBanner(
+    range: AgendaRange,
+    start: LocalDate,
+    end: LocalDate,
+    modifier: Modifier = Modifier,
+) {
+    val locale = currentLocale()
+    val window = agendaRangeWindowSummary(range, start, end, locale)
+    Column(modifier = modifier) {
+        Text(
+            text = stringResource(R.string.agenda_range_showing_label),
+            style = MaterialTheme.typography.labelMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+        // Just the concrete dates — the range's name ("Next 30 days") already
+        // sits on the selector button to the right, so repeating it here is noise.
+        Text(
+            text = window,
+            style = MaterialTheme.typography.titleMedium,
+            color = MaterialTheme.colorScheme.onSurface,
+        )
+    }
+}
+
+@Composable
+private fun AgendaContent(
+    state: AgendaUiState,
+    pastDisplay: PastEventDisplay,
+    showToday: Boolean,
+    onRetry: () -> Unit,
+    onEventClick: (EventInstance) -> Unit,
+    onOpenDay: (LocalDate) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    when (state) {
+        AgendaUiState.Loading -> Box(modifier)
+        is AgendaUiState.Failure -> Box(modifier) {
+            CalendarFailure(reason = state.reason, onRetry = onRetry)
+        }
+        is AgendaUiState.Success -> {
+            val now by rememberCurrentMinute()
+            // Hiding drops finished events — and any day they leave empty; dimming
+            // keeps them but fades the row. Recomputed each minute so events fall
+            // away (or fade) as they end while the screen stays open.
+            val filtered = if (pastDisplay == PastEventDisplay.HIDE) {
+                state.days.mapNotNull { day ->
+                    val remaining = day.events.filterNot { it.hasEnded(now) }
+                    if (remaining.isEmpty()) null else day.copy(events = remaining)
+                }
+            } else {
+                state.days
+            }
+            // Anchor today with a "nothing left today" placeholder — but only when
+            // the window actually starts on today; a jumped-to date has no today in
+            // it, so anchoring there would be misleading (#35).
+            val days = anchorTodayIfMissing(
+                days = filtered,
+                today = state.today,
+                enabled = showToday && state.anchor == state.today,
+            )
+            if (days.isEmpty()) {
+                AgendaEmpty(modifier)
+            } else {
+                AgendaList(
+                    days = days,
+                    today = state.today,
+                    zone = state.zone,
+                    dimPast = pastDisplay == PastEventDisplay.DIM,
+                    now = now,
+                    onEventClick = onEventClick,
+                    onOpenDay = onOpenDay,
+                    modifier = modifier,
+                )
+            }
+        }
+    }
+}
+
+@OptIn(ExperimentalFoundationApi::class)
+@Composable
+private fun AgendaList(
+    days: List<AgendaDay>,
+    today: LocalDate,
+    zone: TimeZone,
+    dimPast: Boolean,
+    now: Instant,
+    onEventClick: (EventInstance) -> Unit,
+    onOpenDay: (LocalDate) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    LazyColumn(
+        modifier = modifier,
+        // Bottom inset clears the FAB stack so the last row stays tappable.
+        contentPadding = PaddingValues(top = 8.dp, bottom = 96.dp),
+    ) {
+        days.forEach { day ->
+            stickyHeader(key = "header-${day.date}") {
+                AgendaDayHeader(date = day.date, today = today, onOpenDay = onOpenDay)
+            }
+            if (day.events.isEmpty()) {
+                // An anchored, event-less today (#35) — "nothing left today".
+                item(key = "placeholder-${day.date}") {
+                    AgendaEmptyDayRow(
+                        text = stringResource(R.string.agenda_no_more_today),
+                        onClick = { onOpenDay(day.date) },
+                    )
+                }
+            } else {
+                itemsIndexed(
+                    items = day.events,
+                    // Scope the key by day: a multi-day event appears under every
+                    // day it spans, so its instanceId alone is not unique across
+                    // the list (LazyColumn requires unique keys).
+                    key = { _, event -> "${day.date}-${event.instanceId}" },
+                ) { index, event ->
+                    AgendaEventRow(
+                        event = event,
+                        day = day.date,
+                        zone = zone,
+                        position = positionOf(index, day.events.size),
+                        dimmed = dimPast && event.hasEnded(now),
+                        modifier = animateItemMotion(),
+                        onClick = { onEventClick(event) },
+                    )
+                }
+            }
+            item(key = "gap-${day.date}") { Spacer(Modifier.height(8.dp)) }
+        }
+    }
+}
+
+@Composable
+private fun AgendaEmpty(modifier: Modifier = Modifier) {
+    Column(
+        modifier = modifier.padding(32.dp),
+        verticalArrangement = Arrangement.Center,
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        Icon(
+            imageVector = Icons.Filled.Coffee,
+            contentDescription = null,
+            tint = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.size(48.dp),
+        )
+        Spacer(Modifier.height(16.dp))
+        Text(
+            text = stringResource(R.string.agenda_empty_title),
+            style = MaterialTheme.typography.titleMedium,
+            textAlign = TextAlign.Center,
+        )
+    }
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun AgendaTopBar(
+    selectedView: CalendarView,
+    onCycleView: () -> Unit,
+    onOpenDrawer: () -> Unit,
+    onOpenSearch: () -> Unit,
+    showTodayButton: Boolean,
+    onToday: () -> Unit,
+    scrollBehavior: TopAppBarScrollBehavior,
+) {
+    TopAppBar(
+        title = {
+            Text(
+                text = stringResource(R.string.view_agenda),
+                style = MaterialTheme.typography.titleLarge,
+            )
+        },
+        navigationIcon = {
+            IconButton(onClick = onOpenDrawer) {
+                Icon(
+                    imageVector = Icons.Default.Menu,
+                    contentDescription = stringResource(R.string.month_open_menu),
+                )
+            }
+        },
+        actions = {
+            TodayAction(show = showTodayButton, onToday = onToday)
+            IconButton(onClick = onOpenSearch) {
+                Icon(
+                    imageVector = Icons.Default.Search,
+                    contentDescription = stringResource(R.string.search_action),
+                )
+            }
+            ViewSwitcherPill(
+                current = selectedView,
+                onCycle = onCycleView,
+                modifier = Modifier.padding(end = 8.dp),
+            )
+        },
+        colors = TopAppBarDefaults.topAppBarColors(
+            containerColor = MaterialTheme.colorScheme.surface,
+            scrolledContainerColor = MaterialTheme.colorScheme.surfaceContainer,
+        ),
+        scrollBehavior = scrollBehavior,
+    )
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaUiState.kt

@@ -0,0 +1,144 @@
+package de.jeanlucmakiola.calendula.ui.agenda
+
+import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.FailureReason
+import de.jeanlucmakiola.calendula.domain.spanFirstDay
+import de.jeanlucmakiola.calendula.domain.spanLastDay
+import kotlinx.datetime.DateTimeUnit
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.plus
+import kotlin.time.Instant
+
+/**
+ * What an agenda row's time line should convey for an event on a given day —
+ * the part of a multi-day span that [day] falls in. Pure and shared so the
+ * agenda screen and the agenda widget label multi-day events identically; each
+ * surface only formats the instants into its own locale/24h string.
+ */
+sealed interface AgendaTimeLabel {
+    /** An all-day event, or a whole in-between day of a multi-day span. */
+    data object AllDay : AgendaTimeLabel
+    /** The first day of a multi-day timed event: when it begins. */
+    data class Starts(val start: Instant) : AgendaTimeLabel
+    /** The last day of a multi-day timed event: when it ends. */
+    data class Ends(val end: Instant) : AgendaTimeLabel
+    /** A single-day timed event: its start–end range. */
+    data class Range(val start: Instant, val end: Instant) : AgendaTimeLabel
+}
+
+/** The [AgendaTimeLabel] for [event] as it appears on [day], resolved in [zone]. */
+fun agendaTimeLabel(event: EventInstance, day: LocalDate, zone: TimeZone): AgendaTimeLabel {
+    if (event.isAllDay) return AgendaTimeLabel.AllDay
+    val firstDay = event.spanFirstDay(zone)
+    val lastDay = event.spanLastDay(zone)
+    return when {
+        firstDay == lastDay -> AgendaTimeLabel.Range(event.start, event.end)
+        day <= firstDay -> AgendaTimeLabel.Starts(event.start)
+        day >= lastDay -> AgendaTimeLabel.Ends(event.end)
+        else -> AgendaTimeLabel.AllDay // a full in-between day
+    }
+}
+
+/** One calendar day with at least one event, for the agenda list. */
+data class AgendaDay(
+    val date: LocalDate,
+    /** Events on this day, all-day first then ascending by start time. */
+    val events: List<EventInstance>,
+)
+
+/**
+ * Group flat [instances] into forward-looking [AgendaDay]s (only days that
+ * actually carry events). A multi-day event surfaces on *every* day it spans,
+ * not just its first — clamped to [[anchor], [windowEnd]] so an event that began
+ * before the window (ongoing) still lists from the anchor day, and one running
+ * past the window stops at the last visible day. Within a day, all-day events
+ * sort first, then ascending by start time, then title.
+ *
+ * Shared by the Agenda screen and the agenda home-screen widget so both group
+ * and order identically.
+ */
+fun groupAgendaDays(
+    anchor: LocalDate,
+    windowEnd: LocalDate,
+    instances: List<EventInstance>,
+    zone: TimeZone,
+): List<AgendaDay> {
+    val byDay = sortedMapOf<LocalDate, MutableList<EventInstance>>()
+    for (instance in instances) {
+        val firstDay = instance.spanFirstDay(zone).coerceAtLeast(anchor)
+        val lastDay = instance.spanLastDay(zone).coerceAtMost(windowEnd)
+        // Skip instances that don't actually occupy any day in [[anchor], [windowEnd]].
+        // The provider returns an event whenever its instant span overlaps the query
+        // window, but all-day events live at UTC midnights with an exclusive end: east
+        // of UTC that end dips just past local midnight, so *yesterday's* all-day event
+        // overlaps today's window start and comes back even though its true last day
+        // (resolved in UTC) is before the anchor. Clamping it up to the anchor would
+        // surface it under "today" (issue #65); drop it instead. The symmetric case —
+        // a next-day all-day event overlapping the window's last instant — drops too.
+        if (lastDay < firstDay) continue
+        var day = firstDay
+        while (day <= lastDay) {
+            byDay.getOrPut(day) { mutableListOf() }.add(instance)
+            day = day.plus(1, DateTimeUnit.DAY)
+        }
+    }
+    return byDay.map { (date, dayEvents) ->
+        AgendaDay(
+            date = date,
+            events = dayEvents.sortedWith(
+                compareByDescending<EventInstance> { it.isAllDay }
+                    .thenBy { it.start }
+                    .thenBy { it.title },
+            ),
+        )
+    }
+}
+
+/**
+ * Ensure [today] surfaces as the first agenda day even when it carries no
+ * (remaining) events, by prepending an empty-event [AgendaDay] the agenda widget
+ * renders as a "nothing left today" placeholder. A no-op unless [enabled], and
+ * when today already has its own day in [days]. Keeps today anchored at the top
+ * so a glance tells today's events apart from a future day's (issue #35).
+ */
+fun anchorTodayIfMissing(
+    days: List<AgendaDay>,
+    today: LocalDate,
+    enabled: Boolean,
+): List<AgendaDay> =
+    if (enabled && days.none { it.date == today }) {
+        listOf(AgendaDay(today, emptyList())) + days
+    } else {
+        days
+    }
+
+/**
+ * State for the Agenda view: a flat, forward-looking list of upcoming events
+ * grouped by day (only days that actually have events appear).
+ */
+sealed interface AgendaUiState {
+    data object Loading : AgendaUiState
+    data class Failure(val reason: FailureReason) : AgendaUiState
+    data class Success(
+        /** First day of the loaded window (today, or a jumped-to date). */
+        val anchor: LocalDate,
+        val today: LocalDate,
+        val days: List<AgendaDay>,
+        /** The range currently in effect — the saved default or a session override. */
+        val range: AgendaRange,
+        /** True when [range] is a temporary in-view override of the saved default. */
+        val rangeIsOverride: Boolean,
+        /** Last day the current [range] covers (inclusive), for the range header. */
+        val rangeEnd: LocalDate,
+        /** Whether to show the top range bar — header + switcher (toggle, on by default). */
+        val showRangeBar: Boolean,
+        /**
+         * The zone [days] were grouped in. Carried in the state rather than
+         * re-read by the screen so labelling and grouping cannot disagree: an
+         * event's "Starts …/Ends …/All day" line is only correct relative to the
+         * same zone that decided which day it was filed under.
+         */
+        val zone: TimeZone,
+    ) : AgendaUiState
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaViewModel.kt

@@ -0,0 +1,186 @@
+package de.jeanlucmakiola.calendula.ui.agenda
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import dagger.hilt.android.lifecycle.HiltViewModel
+import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository
+import de.jeanlucmakiola.calendula.data.di.IoDispatcher
+import de.jeanlucmakiola.calendula.data.prefs.PastEventDisplay
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.data.prefs.firstDayOfWeek
+import de.jeanlucmakiola.calendula.domain.CalendarSource
+import de.jeanlucmakiola.calendula.domain.EventInstance
+import de.jeanlucmakiola.calendula.domain.FailureReason
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.catch
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.flatMapLatest
+import kotlinx.coroutines.flow.flowOn
+import kotlinx.coroutines.flow.stateIn
+import kotlinx.datetime.DateTimeUnit
+import kotlinx.datetime.DayOfWeek
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.atStartOfDayIn
+import kotlinx.datetime.atTime
+import kotlinx.datetime.plus
+import kotlinx.datetime.toInstant
+import kotlinx.datetime.toLocalDateTime
+import kotlin.time.Clock
+import kotlin.time.Instant
+import javax.inject.Inject
+
+@OptIn(ExperimentalCoroutinesApi::class)
+@HiltViewModel
+class AgendaViewModel @Inject constructor(
+    private val repository: CalendarRepository,
+    settingsPrefs: SettingsPrefs,
+    @IoDispatcher private val io: CoroutineDispatcher,
+) : ViewModel() {
+
+    // The saved agenda range plus the range-bar visibility toggle.
+    private val agendaSettings = combine(
+        settingsPrefs.agendaScreenRange,
+        settingsPrefs.agendaShowRangeBar,
+    ) { range, showBar -> AgendaSettings(range, showBar) }
+
+    /**
+     * First day of the week, for the calendar-aligned "this week" range. Public
+     * because the range picker resolves each option to real dates, which needs
+     * the same week start the window is built from.
+     */
+    val weekStart: StateFlow<DayOfWeek> = settingsPrefs.firstDayOfWeek(viewModelScope)
+
+    /**
+     * How to treat events that already ended today (show / dim / hide). A display
+     * concern only, so it rides alongside the data state rather than re-querying;
+     * the screen combines it with a per-minute "now" to fade or drop past rows.
+     */
+    val pastEventDisplay: StateFlow<PastEventDisplay> = settingsPrefs.pastEventDisplay
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = PastEventDisplay.SHOW,
+        )
+
+    /**
+     * Whether to keep today anchored at the top with a "nothing left today"
+     * placeholder even once it has no remaining events (#35). A display concern
+     * applied in the composition (after past-event filtering), so it rides
+     * alongside the data state like [pastEventDisplay] rather than re-querying.
+     */
+    val showToday: StateFlow<Boolean> = settingsPrefs.agendaShowToday
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = true,
+        )
+
+    private val zone = TimeZone.currentSystemDefault()
+
+    private val todayDate: LocalDate
+        get() = Clock.System.now().toLocalDateTime(zone).date
+
+    private val _anchor = MutableStateFlow(todayDate)
+    val anchor: StateFlow<LocalDate> = _anchor
+
+    // A transient, in-view override of the saved agenda range. Held in memory
+    // (not persisted), so it survives view switches and rotation within the
+    // session but resets to the saved default when the app is relaunched.
+    private val _rangeOverride = MutableStateFlow<AgendaRange?>(null)
+
+    val state: StateFlow<AgendaUiState> =
+        combine(_anchor, agendaSettings, _rangeOverride, weekStart) { anchor, settings, override, weekStart ->
+            AgendaParams(
+                anchor = anchor,
+                range = override ?: settings.range,
+                rangeIsOverride = override != null && override != settings.range,
+                weekStart = weekStart,
+                showRangeBar = settings.showBar,
+            )
+        }
+        .flatMapLatest { params ->
+            val window = agendaRange(
+                params.anchor,
+                params.range.dayCount(params.anchor, params.weekStart) - 1,
+                zone,
+            )
+            combine(
+                repository.calendars(),
+                repository.instances(window),
+            ) { calendars, instances ->
+                buildState(params, calendars, instances)
+            }
+        }
+        .catch { emit(AgendaUiState.Failure(FailureReason.ProviderUnavailable)) }
+        .flowOn(io)
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = AgendaUiState.Loading,
+        )
+
+    fun goToToday() {
+        _anchor.value = todayDate
+    }
+
+    /** Jump the agenda window to start on a specific date (drawer jump-to-date). */
+    fun goToDate(date: LocalDate) {
+        _anchor.value = date
+    }
+
+    /** Temporarily override the agenda range for this session (the bottom-left pill). */
+    fun setRangeOverride(range: AgendaRange) {
+        _rangeOverride.value = range
+    }
+
+    private data class AgendaSettings(
+        val range: AgendaRange,
+        val showBar: Boolean,
+    )
+
+    private data class AgendaParams(
+        val anchor: LocalDate,
+        val range: AgendaRange,
+        val rangeIsOverride: Boolean,
+        val weekStart: DayOfWeek,
+        val showRangeBar: Boolean,
+    )
+
+    private fun buildState(
+        params: AgendaParams,
+        calendars: List<CalendarSource>,
+        instances: List<EventInstance>,
+    ): AgendaUiState {
+        if (calendars.isEmpty()) {
+            return AgendaUiState.Failure(FailureReason.NoCalendarsConfigured)
+        }
+        val anchor = params.anchor
+        val rangeEnd = anchor.plus(
+            params.range.dayCount(anchor, params.weekStart) - 1,
+            DateTimeUnit.DAY,
+        )
+        val days = groupAgendaDays(anchor, rangeEnd, instances, zone)
+        return AgendaUiState.Success(
+            anchor = anchor,
+            today = todayDate,
+            days = days,
+            range = params.range,
+            rangeIsOverride = params.rangeIsOverride,
+            rangeEnd = rangeEnd,
+            showRangeBar = params.showRangeBar,
+            zone = zone,
+        )
+    }
+}
+
+/** Inclusive instant range from the start of [anchor] through [days] days ahead. */
+internal fun agendaRange(anchor: LocalDate, days: Int, zone: TimeZone): ClosedRange<Instant> {
+    val from = anchor.atStartOfDayIn(zone)
+    val to = anchor.plus(days, DateTimeUnit.DAY).atTime(23, 59, 59).toInstant(zone)
+    return from..to
+}

app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt

@@ -0,0 +1,373 @@
+package de.jeanlucmakiola.calendula.ui.calendars
+
+import android.net.Uri
+import android.text.format.DateUtils
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.FileDownload
+import androidx.compose.material.icons.filled.FileUpload
+import androidx.compose.material.icons.filled.Schedule
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.Checkbox
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.SnackbarHost
+import androidx.compose.material3.SnackbarHostState
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.listSaver
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.pluralStringResource
+import androidx.compose.ui.res.stringArrayResource
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.unit.dp
+import androidx.core.net.toUri
+import androidx.documentfile.provider.DocumentFile
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.prefs.BackupStatus
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.domain.CalendarSource
+import de.jeanlucmakiola.calendula.domain.isEventTarget
+import de.jeanlucmakiola.calendula.ui.common.CalendarColorChip
+import de.jeanlucmakiola.calendula.ui.common.LeadingAvatar
+import de.jeanlucmakiola.floret.components.CollapsingScaffold
+import de.jeanlucmakiola.floret.components.DialogAmountField
+import de.jeanlucmakiola.floret.components.DialogUnitDropdown
+import de.jeanlucmakiola.floret.components.FullScreenPicker
+import de.jeanlucmakiola.floret.components.GroupedRow
+import de.jeanlucmakiola.floret.components.Position
+import de.jeanlucmakiola.floret.components.positionOf
+import java.time.LocalDate
+
+// SAF mime filter for the restore picker. Source apps hand `.ics` files out
+// under several mimes, so accept the common set.
+private val RESTORE_MIME_TYPES = arrayOf(
+    "text/calendar",
+    "application/octet-stream",
+    "text/plain",
+)
+
+/**
+ * Backup & restore (#69): `.ics` export and restore for local calendars, with
+ * optional automatic backup. Shares [CalendarsViewModel] with the manager.
+ *
+ * A full-screen destination hoisted in `CalendarHost`; [onBack] pops it,
+ * [onImport] hands a picked file to the app's normal .ics import flow.
+ */
+@Composable
+fun BackupScreen(
+    onBack: () -> Unit,
+    onImport: (Uri) -> Unit,
+    viewModel: CalendarsViewModel = hiltViewModel(),
+) {
+    val calendars by viewModel.calendars.collectAsStateWithLifecycle()
+    val backupResult by viewModel.backupResult.collectAsStateWithLifecycle()
+    val autoBackup by viewModel.autoBackup.collectAsStateWithLifecycle()
+
+    val context = LocalContext.current
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    // Export covers local calendars only; managed special-dates mirrors are
+    // rebuilt from contacts. Restore can target anything the import picker offers.
+    val exportable = calendars.filter { it.isLocal && it.canModifyContents && !it.isManaged }
+    val canImport = calendars.any { it.isEventTarget }
+
+    // Exports everything eligible (null); the per-calendar selector owns its
+    // own launcher.
+    val createBackup = rememberLauncherForActivityResult(
+        contract = ActivityResultContracts.CreateDocument("text/calendar"),
+    ) { uri -> uri?.let { viewModel.exportBackup(it, null) } }
+    var showExportPicker by rememberSaveable { mutableStateOf(false) }
+
+    // Restore runs the picked file through the normal .ics import flow.
+    val openBackup = rememberLauncherForActivityResult(
+        contract = ActivityResultContracts.OpenDocument(),
+    ) { uri -> uri?.let(onImport) }
+
+    // The VM persists the write grant so background runs can keep writing.
+    val pickFolder = rememberLauncherForActivityResult(
+        contract = ActivityResultContracts.OpenDocumentTree(),
+    ) { uri -> uri?.let(viewModel::setAutoBackupFolder) }
+    var showInterval by remember { mutableStateOf(false) }
+
+    val backupFailedText = stringResource(R.string.calendars_backup_failed)
+    LaunchedEffect(backupResult) {
+        when (val r = backupResult) {
+            is BackupResult.Success -> {
+                snackbarHostState.showSnackbar(
+                    context.resources.getQuantityString(
+                        R.plurals.calendars_backup_done, r.eventCount, r.eventCount,
+                    ),
+                )
+                viewModel.consumeBackupResult()
+            }
+            BackupResult.Failure -> {
+                snackbarHostState.showSnackbar(backupFailedText)
+                viewModel.consumeBackupResult()
+            }
+            null -> Unit
+        }
+    }
+
+    CollapsingScaffold(
+        title = stringResource(R.string.settings_section_backup),
+        onBack = onBack,
+        snackbarHost = { SnackbarHost(snackbarHostState) },
+        predictiveBack = true,
+    ) {
+        HintText(stringResource(R.string.calendars_backup_hint))
+
+        if (exportable.isNotEmpty()) {
+            GroupedRow(
+                title = stringResource(R.string.calendars_backup_action),
+                position = Position.Top,
+                leading = { LeadingAvatar(Icons.Default.FileDownload) },
+                onClick = {
+                    // A single exportable calendar skips the selector.
+                    if (exportable.size == 1) {
+                        runCatching { createBackup.launch("calendula-backup-${LocalDate.now()}.ics") }
+                    } else {
+                        showExportPicker = true
+                    }
+                },
+            )
+            GroupedRow(
+                title = stringResource(R.string.calendars_restore_action),
+                summary = stringResource(R.string.calendars_restore_hint),
+                position = Position.Middle,
+                leading = { LeadingAvatar(Icons.Default.FileUpload) },
+                onClick = { runCatching { openBackup.launch(RESTORE_MIME_TYPES) } },
+            )
+            GroupedRow(
+                title = stringResource(R.string.calendars_auto_backup),
+                summary = stringResource(R.string.calendars_auto_backup_hint),
+                position = if (autoBackup.enabled) Position.Middle else Position.Bottom,
+                leading = { LeadingAvatar(Icons.Default.Schedule) },
+                trailing = {
+                    Switch(checked = autoBackup.enabled, onCheckedChange = viewModel::setAutoBackupEnabled)
+                },
+                onClick = { viewModel.setAutoBackupEnabled(!autoBackup.enabled) },
+            )
+            if (autoBackup.enabled) {
+                GroupedRow(
+                    title = stringResource(R.string.calendars_auto_backup_folder),
+                    summary = rememberFolderName(autoBackup.folderUri)
+                        ?: stringResource(R.string.calendars_auto_backup_folder_unset),
+                    position = Position.Middle,
+                    onClick = { runCatching { pickFolder.launch(null) } },
+                )
+                GroupedRow(
+                    title = stringResource(R.string.calendars_auto_backup_interval),
+                    summary = backupIntervalLabel(autoBackup.intervalMinutes),
+                    position = Position.Bottom,
+                    onClick = { showInterval = true },
+                )
+                HintText(backupStatusText(autoBackup.status))
+            }
+        } else if (canImport) {
+            // Nothing to back up, but restore is still possible — don't hide
+            // it behind export eligibility.
+            SectionHeader(stringResource(R.string.calendars_restore_header))
+            HintText(stringResource(R.string.calendars_restore_hint))
+            GroupedRow(
+                title = stringResource(R.string.calendars_restore_action),
+                position = Position.Alone,
+                leading = { LeadingAvatar(Icons.Default.FileUpload) },
+                onClick = { runCatching { openBackup.launch(RESTORE_MIME_TYPES) } },
+            )
+        }
+    }
+
+    if (showExportPicker) {
+        ExportCalendarPicker(
+            calendars = exportable,
+            onExport = viewModel::exportBackup,
+            onDismiss = { showExportPicker = false },
+        )
+    }
+    if (showInterval) {
+        BackupIntervalDialog(
+            currentMinutes = autoBackup.intervalMinutes,
+            onConfirm = viewModel::setAutoBackupIntervalMinutes,
+            onDismiss = { showInterval = false },
+        )
+    }
+}
+
+/**
+ * Choose which local calendars to include in a one-time `.ics` export. Defaults
+ * to all selected; the Export action opens the SAF save dialog and hands back
+ * the picked file with the chosen calendar ids.
+ */
+@Composable
+private fun ExportCalendarPicker(
+    calendars: List<CalendarSource>,
+    onExport: (Uri, Set<Long>?) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    // Deliberately not keyed on [calendars]: that list is observer-driven, so
+    // keying it would reset the user's de-selections on every provider re-emit.
+    var selected by rememberSaveable(
+        stateSaver = listSaver(
+            save = { it.toList() },
+            restore = { it.toSet() },
+        ),
+    ) {
+        mutableStateOf(calendars.map { it.id }.toSet())
+    }
+    val createBackup = rememberLauncherForActivityResult(
+        contract = ActivityResultContracts.CreateDocument("text/calendar"),
+    ) { uri ->
+        if (uri != null) {
+            onExport(uri, selected)
+            onDismiss()
+        }
+    }
+
+    FullScreenPicker(
+        title = stringResource(R.string.calendars_export_title),
+        onDismiss = onDismiss,
+    ) {
+        HintText(stringResource(R.string.calendars_export_hint))
+        calendars.forEachIndexed { index, calendar ->
+            val isSelected = calendar.id in selected
+            GroupedRow(
+                title = calendar.displayName,
+                summary = calendar.description,
+                position = positionOf(index, calendars.size),
+                leading = { CalendarColorChip(calendar.color) },
+                trailing = {
+                    Checkbox(
+                        checked = isSelected,
+                        onCheckedChange = { checked ->
+                            selected = if (checked) selected + calendar.id else selected - calendar.id
+                        },
+                    )
+                },
+                onClick = {
+                    selected = if (isSelected) selected - calendar.id else selected + calendar.id
+                },
+            )
+        }
+        Button(
+            onClick = {
+                runCatching { createBackup.launch("calendula-backup-${LocalDate.now()}.ics") }
+            },
+            enabled = selected.isNotEmpty(),
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 16.dp, vertical = 16.dp),
+        ) {
+            Text(stringResource(R.string.calendars_export_action))
+        }
+    }
+}
+
+/** Readable name of the persisted backup folder, resolved from its tree Uri. */
+@Composable
+private fun rememberFolderName(uriString: String?): String? {
+    val context = LocalContext.current
+    return remember(uriString) {
+        uriString?.let {
+            runCatching { DocumentFile.fromTreeUri(context, it.toUri())?.name }.getOrNull()
+        }
+    }
+}
+
+/** "Every 30 minutes" / "Every 2 hours" / "Every day" — the interval in its largest whole unit. */
+@Composable
+private fun backupIntervalLabel(minutes: Long): String {
+    val duration = when {
+        minutes % MINUTES_PER_WEEK == 0L ->
+            pluralStringResource(R.plurals.duration_weeks, (minutes / MINUTES_PER_WEEK).toInt(), (minutes / MINUTES_PER_WEEK).toInt())
+        minutes % MINUTES_PER_DAY == 0L ->
+            pluralStringResource(R.plurals.duration_days, (minutes / MINUTES_PER_DAY).toInt(), (minutes / MINUTES_PER_DAY).toInt())
+        minutes % 60L == 0L ->
+            pluralStringResource(R.plurals.duration_hours, (minutes / 60L).toInt(), (minutes / 60L).toInt())
+        else ->
+            pluralStringResource(R.plurals.duration_minutes, minutes.toInt(), minutes.toInt())
+    }
+    return stringResource(R.string.calendars_auto_backup_every, duration)
+}
+
+/** "Last backup: 5 minutes ago" / "… failed" / "No automatic backup yet". */
+@Composable
+private fun backupStatusText(status: BackupStatus): String {
+    if (status.lastRun == 0L) return stringResource(R.string.calendars_auto_backup_status_never)
+    val relative = DateUtils.getRelativeTimeSpanString(
+        status.lastRun, System.currentTimeMillis(), DateUtils.MINUTE_IN_MILLIS,
+    ).toString()
+    return if (status.lastSuccess) {
+        stringResource(R.string.calendars_auto_backup_status_ok, relative)
+    } else {
+        stringResource(R.string.calendars_auto_backup_status_failed, relative)
+    }
+}
+
+/** Amount + unit picker for the backup interval (floored at 30 minutes). */
+@Composable
+private fun BackupIntervalDialog(
+    currentMinutes: Long,
+    onConfirm: (Long) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    // Pick the largest unit the current value divides into.
+    val unitMinutes = remember { listOf(1L, 60L, MINUTES_PER_DAY, MINUTES_PER_WEEK) }
+    val units = stringArrayResource(R.array.backup_interval_units).toList()
+    val initialUnit = unitMinutes.indexOfLast { currentMinutes % it == 0L }.coerceAtLeast(0)
+    var amount by rememberSaveable { mutableStateOf((currentMinutes / unitMinutes[initialUnit]).toString()) }
+    var unitIndex by rememberSaveable { mutableStateOf(initialUnit) }
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text(stringResource(R.string.calendars_auto_backup_interval)) },
+        text = {
+            Column {
+                Row(verticalAlignment = Alignment.CenterVertically) {
+                    DialogAmountField(value = amount, onValueChange = { amount = it }, placeholder = "1")
+                    Spacer(Modifier.width(12.dp))
+                    DialogUnitDropdown(label = units[unitIndex], entries = units) { unitIndex = it }
+                }
+                Spacer(Modifier.height(8.dp))
+                Text(
+                    text = stringResource(R.string.calendars_auto_backup_interval_min),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(onClick = {
+                val value = amount.toLongOrNull()?.coerceAtLeast(1L) ?: 1L
+                onConfirm((value * unitMinutes[unitIndex]).coerceAtLeast(SettingsPrefs.MIN_BACKUP_INTERVAL))
+                onDismiss()
+            }) { Text(stringResource(R.string.reminder_custom_set)) }
+        },
+        dismissButton = {
+            TextButton(onClick = onDismiss) { Text(stringResource(R.string.dialog_cancel)) }
+        },
+    )
+}
+
+private const val MINUTES_PER_DAY = 1_440L
+private const val MINUTES_PER_WEEK = 10_080L

app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarVisibilityNotice.kt

@@ -0,0 +1,71 @@
+package de.jeanlucmakiola.calendula.ui.calendars
+
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.VisibilityOff
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.res.stringResource
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import dagger.hilt.android.lifecycle.HiltViewModel
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.data.calendar.CalendarVisibilityReconciler
+import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * The one-time notice that Calendula now follows the device's per-calendar
+ * visibility (#75), armed by `CalendarVisibilityReconciler`. The app does not
+ * switch those calendars back on — that would un-hide them everywhere else too.
+ */
+@HiltViewModel
+class CalendarVisibilityNoticeViewModel @Inject constructor(
+    private val prefs: CalendarPrefs,
+    private val reconciler: CalendarVisibilityReconciler,
+) : ViewModel() {
+
+    /**
+     * Reconcile whenever the app comes up with the calendar permission held,
+     * rather than off one grant route: a permission granted on Android's
+     * app-settings screen never reaches the permission screen's callback.
+     */
+    fun reconcile() {
+        viewModelScope.launch { reconciler.run() }
+    }
+
+    val pending: StateFlow<Boolean> = prefs.visibilityNoticePending
+        .map { it == true }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000L),
+            initialValue = false,
+        )
+
+    fun dismiss() {
+        viewModelScope.launch { prefs.setVisibilityNoticePending(false) }
+    }
+}
+
+/** Plain informational dialog — one acknowledgement, nothing to decide. */
+@Composable
+fun CalendarVisibilityNoticeDialog(onDismiss: () -> Unit) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        icon = { Icon(Icons.Default.VisibilityOff, contentDescription = null) },
+        title = { Text(stringResource(R.string.calendars_visibility_notice_title)) },
+        text = { Text(stringResource(R.string.calendars_visibility_notice_message)) },
+        confirmButton = {
+            TextButton(onClick = onDismiss) {
+                Text(stringResource(R.string.dialog_ok))
+            }
+        },
+    )
+}