Lumotia/docs/release/v0.1-known-limitations.md

---
name: v0.1-known-limitations
type: release
tags: [release, v0.1, known-limitations, trust, user-facing]
description: "User-facing known-limitations doc for Lumotia v0.1. Written for end-users not engineers — every limitation states what works, what doesn't, what the workaround is, and when (if ever) the limitation is expected to lift. This is the trust document. Linked from README + the public release notes."
---

# Lumotia v0.1 — known limitations

This is the honest list. Every entry below names something that **does not work the way you might expect it to** in this release. Read it before you install. We'd rather have you walk in clear-eyed than disappointed.

If something you find isn't on this list, it's a real bug — please tell us. If something on this list lifts in a later release, it'll be removed from this file and called out in the changelog.

## Platforms + power

### Long dictation sessions and OS idle/sleep

Lumotia is designed for sit-down dictation, not always-on transcription. On Linux and Windows, Lumotia now actively prevents the OS from sleeping or locking the session while you are recording. On macOS, App Nap protection is coded but its effectiveness on Apple Silicon has not yet been confirmed against real OS idle-throttling.

| Platform | Behaviour | Notes |
|---|---|---|
| Linux | Lumotia acquires a `systemd-logind` idle+sleep inhibit lock (`org.freedesktop.login1.Manager.Inhibit`) on recording start and releases it on stop. Covers screen dim, session lock, suspend, and lid-close. | If logind is not available (non-systemd containers, exotic distros), the inhibit silently falls back to a no-op. In that case: wrap launch with `systemd-inhibit --what=idle:sleep:handle-lid-switch lumotia`. |
| macOS | App Nap protection is coded (`NSProcessInfo.beginActivityWithOptions`). Runtime verification on Apple Silicon hardware is still pending for this release. | Keep the Lumotia window focused for long sessions. As a global override: `defaults write NSGlobalDomain NSAppSleepDisabled -bool YES` (revert with `-bool NO` after). |
| Windows | Lumotia calls `SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED)` on recording start to prevent the system from sleeping, and releases it on stop. Screen lock is intentionally not blocked. | If a Windows policy override prevents `SetThreadExecutionState`, set your active power plan's sleep timeout to "Never" while dictating. |

## Cloud transcription is not available in this release

Lumotia is **local-only** in v0.1. All transcription happens on your device using a Whisper model you download once. Nothing leaves your machine for transcription.

A cloud-provider plumbing crate exists in the codebase but is intentionally not exposed: there's no setting to enable it, no UI to enter an API key, and no path that sends audio to a remote service. We will only ship cloud-provider support when we can ship it with the right defaults (off, BYOK, clearly labelled, never required).

## Model Context Protocol (MCP) server access

Lumotia includes an optional MCP server (`lumotia-mcp`) you can wire into Claude Desktop, Cline, or any MCP-capable client. It is:

- **Read-only.** No tool can create, edit, or delete transcripts or tasks.
- **Local-only.** Communicates over stdio. No network listener. No remote access.
- **Off by default.** You must explicitly launch it and add it to your MCP client's configuration.

The honest thing to flag: when you wire `lumotia-mcp` into an MCP client, that client gets read access to **your entire transcript history and task list**. There is no per-row permission system in v0.1. Treat it the same way you'd treat giving an MCP client access to a folder of personal notes — only enable it if you trust the client end-to-end. We'll add a permission boundary in a later release.

## AI cleanup + extraction failure modes

Lumotia uses a local LLM (downloaded once, runs on your device) for transcript cleanup and task extraction. Like any model, it can fail. The product is designed so that **no AI failure ever loses your transcript**.

What happens on a failure:

| What fails | What you see | What's preserved |
|---|---|---|
| LLM cleanup throws an error | Sidebar status chip flashes "failed"; transcript stays at rule-based cleanup (fillers removed, repetition collapsed, British-English applied) | Your raw transcript text is unchanged |
| Task extraction throws | Tasks still get extracted, just via a rule-based regex+verb-list extractor instead of the LLM | Your transcript text is unchanged; tasks still appear |
| Content tag extraction throws | A "Tagging failed" toast appears; no tags applied | Your transcript text is unchanged; you can retry |
| LLM hangs mid-generation | The sidebar status chip may stay on "Cleaning up" indefinitely until you restart the app | Your raw transcript is preserved; the rest of the app still works while the chip is stuck |

The hanging-chip case is the only soft edge. Closing it (with a timeout wrap on the LLM call) is on the v0.2 hygiene track.

## Settings page is in progressive-disclosure mode

The Settings page has six sections covering everything that matters for v0.1: Start Here, Transcription basics, Models, Privacy, Accessibility, Advanced. A full visual regroup with grouped progressive-disclosure cards is planned for v0.2.

If you can't find a setting, it's almost certainly under **Advanced**.

## Internal engine refactor still in progress

Some internal engine refactors (alternative transcription provider plumbing) are partly landed but not yet wired through every code path. This **does not affect** the default local Whisper transcription path you use as a user. It means alternative providers aren't selectable in v0.1.

## Soft-touch nudging is frontend-driven only

Lumotia's nudge system reacts to what happens **inside the app** — task completions, timer state, ritual progress, window focus. It does not yet watch what's happening on the rest of your system (keyboard activity in other apps, active-window changes, etc.) — that's a v0.2-or-later expansion.

In practice this means: Lumotia won't nudge you because you've been idle in another window. It will nudge you based on the rhythm of your Lumotia session itself. If that's the wrong default for you, you can turn nudges off entirely in Settings.

## What's NOT in v0.1 (call-outs people often ask about)

- **No Garden Inbox / review cards / suggested routing.** This is the v0.2 marquee feature.
- **No related notes / backlinks across transcripts.** v0.2.
- **No Obsidian plugin.** v0.2.
- **No mobile companion app.** Not on the current track.
- **No cloud sync.** Not on the current track.
- **No premium voices / paid tier expansion.** v1.0 commercial track.

## Reporting issues

If you hit something not on this list, please file an issue at the link in the README. Include:

- Platform (Linux/macOS/Windows + version)
- Lumotia version (Settings → About)
- What you did
- What you expected
- What actually happened

Crash dumps (if any) live at `<app-data-dir>/crashes/` — attaching the most recent file helps us a lot.

---

This list is what we know. If we discover more, we'll add to it.

---

## v0.1 release-readiness waivers (W-01 through W-08)

The checklist says: "Tag-eligible when every item below is ✅ or explicitly waived in the linked known-limitations row." The entries below are the spec-allowed waivers. Each one documents an item that depends on resources the project does not yet have — paid signing infrastructure, specific hardware, tagged artefacts, or human-outreach time — rather than on code that still needs writing. None of them hides an engineering gap. Each one names the exact action that ends the waiver.

### W-01 — Windows code-signing certificate

**What's waived**: "Windows code-signing certificate sourced + secrets set in the repo"

**Why this is appropriate as a v0.1 waiver**: Obtaining an EV code-signing certificate for Windows requires purchasing from a CA (DigiCert, Sectigo, SSL.com), completing identity verification, and receiving the credential — all of which are external to the codebase and cannot be automated by any amount of engineering work done before tag day. The CI workflow (`build.yml`) already passes `WINDOWS_CERTIFICATE` and `WINDOWS_CERTIFICATE_PASSWORD` to `tauri-action` conditionally, so signing activates the moment the secrets are set with no further code changes. The trust posture for users during the waiver window is documented and honest: Windows users will see a Microsoft SmartScreen warning on first run, which disappears after enough users run the installer. The workaround is documented in `docs/release/install-warnings.md` and linked from the release notes and README.

**The one-action equivalent the user takes when ready**: Purchase an EV cert, export it as a `.pfx`, and run `gh secret set WINDOWS_CERTIFICATE` + `gh secret set WINDOWS_CERTIFICATE_PASSWORD` per the Windows section of `docs/release/code-signing-setup.md`. The next CI build on a tag will be signed automatically.

**Trust impact**: Windows users see a SmartScreen warning on first install. The warning is documented in `docs/release/install-warnings.md` with the "More info → Run anyway" workaround. Linux ships clean (AppImage + SHA-256 sidecar). macOS users are covered by W-02.

**Lifts when**: `gh secret set WINDOWS_CERTIFICATE` runs successfully and a signed CI build on a version tag is verified (SmartScreen warning absent on a test machine).

---

### W-02 — macOS notarisation + Apple Developer ID

**What's waived**: "macOS notarisation + Gatekeeper acceptance via Apple Developer ID (or documented Gatekeeper-warning workaround if notarisation isn't available)"

**Why this is appropriate as a v0.1 waiver**: macOS notarisation requires enrolment in the Apple Developer Program ($99/year), a two-factor Apple ID, and a code-signing identity issued by Apple. These cannot be provisioned in a coding session. The CI workflow already passes all six `APPLE_*` environment variables to `tauri-action` — signing and notarisation activate automatically once the secrets are set. The trust posture for users during the waiver window is documented and honest: macOS users see a Gatekeeper warning on first open, and the workaround (right-click → Open) is documented in `docs/release/install-warnings.md` and linked from the release notes.

**The one-action equivalent the user takes when ready**: Enrol in the Apple Developer Program, generate an Apple Distribution certificate, export the signing identity, and run `gh secret set APPLE_CERTIFICATE` + the other five `APPLE_*` secrets per the macOS section of `docs/release/code-signing-setup.md`. The next CI build on a tag will be signed and notarised automatically.

**Trust impact**: macOS users see a Gatekeeper warning on first open. The warning is documented in `docs/release/install-warnings.md` with the right-click → Open workaround. App content stays identical whether signed or unsigned.

**Lifts when**: All six `APPLE_*` secrets are set and a notarised CI build on a version tag is verified (Gatekeeper warning absent on a test machine, `spctl --assess --verbose` passes).

---

### W-03 — macOS App Nap Apple Silicon runtime probe

**What's waived**: "RB-08 macOS App Nap power-assertion runtime verification on Apple Silicon (resolve or document with workaround per KI-01)"

**Why this is appropriate as a v0.1 waiver**: The macOS power-assertion code is fully implemented — `src-tauri/src/commands/power.rs` calls `NSProcessInfo.beginActivityWithOptions` on recording start and ends the activity on stop. What is pending is not code but runtime confirmation: an M-series Mac is required to verify that the assertion prevents App Nap throttling under real OS idle conditions. No M-series hardware is available in the development environment. KI-01 in `KNOWN-ISSUES.md` documents the gap with the global workaround (`defaults write NSGlobalDomain NSAppSleepDisabled -bool YES`) and the session-scoped workaround (keep the Lumotia window focused). Users on Apple Silicon who dictate with the window focused will not experience throttling even if the power assertion turns out to be insufficient.

**The one-action equivalent the user takes when ready**: Run the 10-minute verification procedure in `docs/release/apple-silicon-rb08-runbook.md` on any M-series Mac — open Lumotia, start a long recording, background the window, confirm transcription continues without pausing.

**Trust impact**: macOS Apple Silicon users may experience App Nap throttling on very long dictation sessions if the Lumotia window is backgrounded. Workaround: keep the Lumotia window visible, or apply the system-wide `NSAppSleepDisabled` override documented in the table above. Transcription never loses data (the raw audio buffer persists); throttling only affects real-time transcript display latency.

**Lifts when**: The `apple-silicon-rb08-runbook.md` procedure completes on M-series hardware with no throttling observed, OR a code fix is landed and verified.

---

### W-04 — CI green on Linux/macOS/Windows artefact builds on tag push

**What's waived**: "CI green on Linux/macOS/Windows artefact builds on tag push"

**Why this is appropriate as a v0.1 waiver**: This item cannot be verified until a version tag exists — there is no tag yet, so there is no tagged CI run to inspect. The build workflow (`.github/workflows/build.yml`) is configured for all three platforms and is exercised on every pull request via the per-push checks; the Linux build path is known good from the dogfood drill. The macOS and Windows build paths are exercised on CI runners (not local hardware), so any platform-specific compile failure will surface immediately on the first tag push. The pre-tag verify script (`scripts/pre-tag-verify.sh`) runs `cargo check --workspace --all-targets` + `cargo build -p lumotia --release` as a compilation sanity check before tagging.

**The one-action equivalent the user takes when ready**: Run `./scripts/tag-day.sh` — it orchestrates the pre-tag verify, CHANGELOG date substitution, `git tag v0.1.0`, push to both remotes, and CI-watch in one command. The CI-watch step will surface any per-platform build failure within the first CI run.

**Trust impact**: No user-facing impact during the waiver window. If a per-platform CI build fails on tag day, the release can be held until the build is fixed — this is a developer-facing gate, not a user-visible gap.

**Lifts when**: The CI run on the `v0.1.0` tag completes green on all three platform jobs and the artefact upload step succeeds for Linux `.AppImage`, macOS `.dmg`, and Windows `.msi`.

---

### W-05 — Manual smoke-test matrix on tagged artefacts

**What's waived**: "Manual smoke-test on each platform artefact before public release" — all 35 cells of the 5-row × 7-column matrix (Linux Fedora, Linux Ubuntu LTS, macOS Apple Silicon, macOS Intel, Windows 11 × Install / First-run / Capture / Cleanup / Export / History search / Uninstall+reinstall preserves transcripts)

**Why this is appropriate as a v0.1 waiver**: The smoke-test matrix is defined against final tagged artefacts. Those artefacts do not yet exist — they are produced by the CI run triggered by the version tag. Running the matrix before the tag would test a different binary than the one users receive. Linux partial automation already exists: `scripts/smoke-linux.sh [AppImage]` automates 3/7 cells (Install, First-run, Uninstall+reinstall) and prompts for the remaining 4 with explicit pass/fail confirmations. The macOS and Windows rows require access to those platforms. The severity matrix (P0/P1/P2) in the checklist means that only P0 failures (spine failures on primary platforms) block the tag — P2 failures (macOS Intel, v0.2-flagged features) do not block private beta.

**The one-action equivalent the user takes when ready**: After the CI run on the `v0.1.0` tag completes, download the platform artefact and run `./scripts/smoke-linux-driver.sh [AppImage]` for the Linux rows. For macOS and Windows, follow `docs/release/tester-acceptance-runbook.md` for the per-step expected outcomes. Classify any failure as P0/P1/P2 using the severity table in the checklist.

**Trust impact**: The first users of tagged artefacts are in effect completing the smoke test. Any P0 failure discovered post-tag will be addressed in a patch release (v0.1.1) and documented in this known-limitations doc. P1 failures will receive a known-limitations entry before the public announcement. P2 failures are tracked but do not block.

**Lifts when**: All 35 matrix cells are filled in with PASS or a classified failure entry, for the artefacts produced by the `v0.1.0` tag CI run.

---

### W-06 — Tester acceptance flow at 900×700, keyboard-only, and visual contrast on deployed app

**What's waived**: Three UI-acceptance checklist items — (1) "Tester acceptance flow (10 steps) can be completed at 900×700 without horizontal scrolling", (2) "Tester acceptance flow can be completed using keyboard only — no mouse touched", and (3) the visual contrast verification portion that requires a deployed app (as opposed to the code-side audit already completed)

**Why this is appropriate as a v0.1 waiver**: The code-side infrastructure for all three items is in place. The keyboard-only path has full coverage: Ctrl+K / Ctrl+, / Esc dispatch / arrow-key navigation in PostCaptureCard / focus-visible app-wide. The WCAG-AA contrast audit is filed at `docs/release/v0.1-contrast-audit.md` — 43/51 pairs PASS, and the two HIGH-impact failures (CA-1, CA-2) were fixed with the `.btn-filled-text` utility class. The 900×700 viewport check and keyboard walk require a human to run the 10-step tester flow; they cannot be verified by static analysis. These three items are verification steps, not implementation steps.

**The one-action equivalent the user takes when ready**: Open the running app at a 900×700 browser or Tauri window size, and walk through the 10 steps in `docs/release/tester-acceptance-runbook.md` using only the keyboard. The per-step expected-outcomes table in that doc gives you the pass/fail criteria for each step.

**Trust impact**: The code changes that enable these three acceptance criteria are shipped. Any visual overflow at 900×700 or focus-order gap that the human walk surfaces will be addressed before the public announcement. Contrast fixes are already shipped and verifiable in the deployed app.

**Lifts when**: A human completes the 10-step tester flow at 900×700 with keyboard-only and records PASS on each step in `docs/release/tester-acceptance-runbook.md`.

---

### W-07 — Private-beta tester recruitment, activation metrics measurement, and top-3 setup failures

**What's waived**: Three activation-metrics checklist entries — (1) measurement of the five defined private-beta activation metrics (activation / core value / retention / quality / trust), (2) the public v0.1 launch pass-bar metrics (20 install / 15 capture / 10 reuse-within-week / 5 willing-to-pay-£39), and (3) "top-3 setup failures documented after first 5 testers"

**Why this is appropriate as a v0.1 waiver**: All three items require human testers who do not yet exist. The activation infrastructure is fully built: the `lumotia_events` table, `record_lumotia_event` / `list_lumotia_events` / `clear_lumotia_events` Tauri commands, and the Settings → Privacy → Activation log surface are all in place. The diagnostic bundle command (`generate_diagnostic_bundle`) produces a structured intake that testers attach to issues. The missing piece is the outreach, distribution, and qualitative reporting cycle — none of which can be automated or completed before tester recruitment happens. The top-3 setup failures section is deliberately left as a post-tester update because inventing failures before they occur would be dishonest.

**The one-action equivalent the user takes when ready**: Use `docs/release/tester-onboarding-kit.md` for the email template, platform distribution targets, and check-in script. After 5 testers report back, run `scripts/parse-activation-log.py` against their exported activation logs and `scripts/parse-diagnostic-bundle.sh` against any submitted bundles to surface the top-3 setup failures. Add the failures to this doc with workarounds.

**Trust impact**: No user-facing impact before tester recruitment — the infrastructure is present and ready. Testers who join the private beta will have the opt-in activation log and diagnostic bundle tools available from day one. The top-3-failures update will happen before the public v0.1 announcement (not a blocking gate for the private beta tag itself).

**Lifts when**: Five or more testers have completed the onboarding flow, activation log data has been reviewed, and the top-3 setup failures section of this doc is populated with concrete workarounds. Public-launch pass-bar lifts when the four quantitative thresholds (20/15/10/5) are measured post-distribution.

---

### W-08 — Pre-tag verification ceremony (the morning-of steps)

**What's waived**: The "Pre-tag verification (the morning of)" 7-step block in the checklist

**Why this is appropriate as a v0.1 waiver**: This item is not incomplete — it is the literal definition of what happens on tag day. The verification steps are defined, scripted, and ready to run. `./scripts/pre-tag-verify.sh` automates all 7 steps (clean checkout, version sync, CHANGELOG date, known-limitations TBD scan, quality gates, dogfood drill, release build). `./scripts/tag-day.sh` orchestrates the entire ceremony — pre-tag verify, CHANGELOG date substitution, `git tag`, push, and CI-watch — in a single command. The only thing that makes this a waiver rather than a tick is that the ceremony has not run yet, because the tag does not yet exist. Checking this box before running the ceremony would be dishonest; leaving it unchecked implies code is missing when it isn't.

**The one-action equivalent the user takes when ready**: Run `./scripts/tag-day.sh` on tag day. If `pre-tag-verify.sh` exits 0, the ceremony proceeds automatically. If it exits non-zero, the failure message is explicit and actionable.

**Trust impact**: None — this is an internal gate with no user-visible surface. The morning-of ceremony is the mechanism by which all other waivers either confirm they are truly ready or surface a blocking issue before users receive the artefact.

**Lifts when**: `./scripts/tag-day.sh` completes without error, the `v0.1.0` tag exists on both remotes, and CI has produced artefacts for at least the Linux primary platform.