agent: lumotia — release-doc set + two pre-release audits (MCP + LLM failure)
Operationalises the ChatGPT/Jake roadmap-synthesis pass into four
release-boundary documents at docs/release/. Synthesis call:
v0.1 = stable local capture product
v0.2 = Garden Inbox / review cards
v1.0 = PKM-complete + commercial track
Two factual audits ran first per Jake's explicit instruction — release
hardening only, no architecture refactors, no Garden Inbox work:
AUDIT 1 — MCP surface
=====================
Verdict: PASSES the v0.1 trust posture.
- Read-only by design (`//! No writes — Lumotia's Tauri app remains the only writer`)
- Stdio-only transport (newline-delimited JSON-RPC 2.0); no TCP/Unix
listener, no bind, no network exposure
- Database opened via `lumotia_storage::init_readonly` — structurally
enforced, not just convention
- 4 tools, all SELECT-only: list_transcripts, get_transcript,
search_transcripts, list_tasks
- Zero matches for INSERT/UPDATE/DELETE/fs::write/fs::remove/
create_dir/spawn_blocking in the crate
- Separate binary (`crates/mcp/src/main.rs`) — not part of the running
Tauri app; user must explicitly launch and wire into client config
- Honest nuance flagged in known-limitations: a wired client gets read
access to the entire transcript history + task list — no per-row
permission boundary in v0.1
AUDIT 2 — LLM failure surface
=============================
Verdict: data-loss path PASSES; UX-wedge path PARTIAL (documented).
- post_process_segments (file + live pipeline): tracing::warn! on Err,
segments stay at rule-based output. Raw transcript preserved.
- cleanup_transcript_text_cmd (DictationPage): frontend try/catch
returns raw text unchanged on Err. Raw transcript preserved.
- extract_tasks_from_transcript_cmd (DictationPage): frontend falls
back to rule-based extractTasks (regex + verb list) on Err.
- extract_content_tags_cmd (HistoryPage): per-row try/catch; toast on
failure; transcript untouched.
- Hung llama.cpp: no tokio::time::timeout on the spawn_blocking call.
Raw transcript preserved; rest of app functional; LLM status chip
stays on "Cleaning up" until restart. Soft edge — documented in
known-limitations as v0.2 hygiene candidate. Not implemented per
"release hardening only" instruction.
THE FOUR DOCS
=============
docs/release/v0.1-checklist.md
- 10-step tester acceptance test (install → capture → cleanup →
task → MicroSteps → timer → history search)
- Must-ship list per surface (product, onboarding, artefacts, docs,
quality gates, trust+security, release-blockers, smoke-test
matrix)
- Activation metrics for private beta (3 min to first capture, 3
captures in 24h, 7-day return, etc.) + v0.1 public launch
(20 install, 15 first-capture, 10 return, 5 pay-£39)
- Pre-tag verification sequence
- Explicit out-of-scope list (Garden Inbox, Phases B-E/G/I/J, etc.)
docs/release/v0.1-known-limitations.md
- User-facing rewrite, not engineer-speak
- Power assertions per platform (Linux idle / macOS App Nap / Windows
sleep) with practical workarounds
- MCP read-only/local-only posture with the
"all transcripts visible to your wired client" honest nuance
- AI cleanup/extraction failure table — what fails, what you see,
what's preserved
- Settings page progressive-disclosure status
- Internal engine refactor (orchestrator dormant) framed for users
- Explicit "what's NOT in v0.1" call-outs
- Reporting issues + crash-dump location
docs/release/v0.2-garden-roadmap.md
- Headline: "review cards for turning messy dictations into notes,
tasks, topics and links" — tangible, not PKM-overloaded
- Garden Inbox scope (raw / cleaned / suggested title-type-folder-
project / extracted tasks / suggested tags / possible links /
confidence / Accept-Edit-Park-Archive)
- Engine architecture Phases B-E pairing
- Explicit "NOT in v0.2" list (no graph, no canvas, no PKM marketing,
no cloud provider, no premium voices)
- Open decisions for v0.2 scope freeze deferred until v0.1 ships +
20 testers run
docs/release/how-lumotia-is-built.md
- Public-facing trust page; honest disclosure that AI-assisted
human-directed, then evidence
- The real silent-data-loss bug the drill caught (Phase A.7 fix
ff8dda0) framed as proof the process works
- Phase B atomiser audit: 9 surgical fixes including the FIFO hang,
LlmEngine unload race, purge-vs-restore SELECT-then-DELETE race
- Supply-chain pre-flight (npm audit signatures + --ignore-scripts +
pinned dev deps + pinned rust toolchain)
- MCP read-only audit + LLM failure audit cross-referenced
- Anti-patterns explicitly avoided (no telemetry exfiltration, no
silent AI dependency, no "audit log later", etc.)
- Calibrated to "AI use is survivable; sloppy undisclosed untested
AI use is not" — RPCS3 framing cited
Verification:
- cargo fmt --check: clean (no Rust changed)
- All four docs are user-readable, not commit-log-derivative
- Cross-references resolve (every internal path quoted exists)
This commit is contained in:
118
docs/release/how-lumotia-is-built.md
Normal file
118
docs/release/how-lumotia-is-built.md
Normal file
@@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
name: how-lumotia-is-built
|
||||||
|
type: release
|
||||||
|
tags: [release, trust, ai-assisted, process, audit, public]
|
||||||
|
description: "Public-facing trust page. Honest disclosure that Lumotia is AI-assisted human-directed software, paired with the evidence that justifies trusting it anyway: dogfood drill, atomiser audit, supply-chain pre-flight, pinned toolchain, real-data-loss bug caught and fixed. Linked from README and from the v0.1 release notes. Calibrated to the framing 'AI use is survivable; sloppy undisclosed untested AI use is not'."
|
||||||
|
---
|
||||||
|
|
||||||
|
# How Lumotia is built
|
||||||
|
|
||||||
|
Lumotia is an **AI-assisted, human-directed** project.
|
||||||
|
|
||||||
|
A single developer (Jake Sames at CORBEL) defines the product, decides the constraints, sets the privacy model, writes the tests that matter, and ships only through a repeatable quality gate. AI coding tools are used during implementation. Every release is dogfood-tested. Every release ships a known-limitations document. Every release has an audit trail in the git log.
|
||||||
|
|
||||||
|
This page exists because shipping a productivity app built this way without saying so is the wrong shape. Software you trust on your private thoughts deserves a clear answer to the question **"how was this built and how do I know it's not slop?"**
|
||||||
|
|
||||||
|
## The honest disclosure
|
||||||
|
|
||||||
|
The implementation is written with the help of AI tools — primarily Claude (Anthropic). The product direction, scope, design constraints, security boundaries, and quality gates are all human-decided.
|
||||||
|
|
||||||
|
What this means in practice:
|
||||||
|
|
||||||
|
- **A human chose every feature.** No feature in Lumotia exists because an AI suggested it. The product spec and roadmap are in `docs/brief/` and `docs/roadmap/` and predate most of the implementation work.
|
||||||
|
- **A human runs every release.** There is no agent that auto-ships. Builds go out after manual sign-off against the checklist in `docs/release/v0.1-checklist.md`.
|
||||||
|
- **AI does not have credentials.** No AI tool has access to signing keys, licence-server keys, or any production secret. Those live in `.env` files that are never read by the agent loop.
|
||||||
|
- **AI does not bypass review.** Every change goes through clippy, fmt, the workspace test suite, and (for non-trivial work) a second-model cross-review via Codex.
|
||||||
|
|
||||||
|
This is the same shape as the [RPCS3 emulator team's recent stance](https://www.gamesradar.com/games/stop-submitting-ai-slop-code-ps3-emulator-rpcs3-shuts-down-vibe-coders-tells-them-to-learn-how-to-debug-code-and-leave-behind-something-useful-to-humanity-when-youre-gone/) on AI-assisted contributions: disclose use, explain testing/review, ship something that earns its place. AI use is survivable. Sloppy, undisclosed, untested AI use is not.
|
||||||
|
|
||||||
|
## The trust evidence
|
||||||
|
|
||||||
|
Talk is cheap. The evidence is in the repository.
|
||||||
|
|
||||||
|
### A real bug that should have shipped — and didn't
|
||||||
|
|
||||||
|
On 2026/05/14, a dogfood drill against the real built binary (not unit tests) caught a startup-order race condition that would have **silently orphaned every Magnotia user's data** when they upgraded to Lumotia. The migration was running too late in the startup sequence; `init_tracing` and the WebView context were creating the destination directories before the migration could rename the source. Result: a fresh empty Lumotia install next to the legacy Magnotia data, no error, no warning, no recovery path.
|
||||||
|
|
||||||
|
The unit tests all passed. The integration tests all passed. The release would have shipped. The dogfood drill caught it.
|
||||||
|
|
||||||
|
Fix landed in commit `ff8dda0`. Drill probe added to prevent regression. The drill is at `scripts/dogfood-rebrand-drill.sh` and is part of the v0.1 release checklist.
|
||||||
|
|
||||||
|
### An adversarial code audit
|
||||||
|
|
||||||
|
Phase B of the pre-release dogfood pass examined the 15 most-load-bearing recent commits (race conditions, lifecycle, trust-boundary, time bombs, observability) and asked: **what could go wrong here that the original tests don't catch?**
|
||||||
|
|
||||||
|
Outcome: 9 surgical fixes shipped, 5 documented passes. Examples:
|
||||||
|
|
||||||
|
- A `copy_dir_recursive` fall-through that would `std::fs::copy` a FIFO — opening a FIFO for read with no writer blocks forever. A stale debug FIFO in a user's `~/.magnotia/` tree could have silently hung first launch. Hardened to surface an error rather than hang.
|
||||||
|
- An `LlmEngine::unload()` race that didn't consult the `loading` flag — a concurrent unload mid-load could see the engine "succeed at unload" while the in-flight load then installed a model behind it. Both directions now respect the flag.
|
||||||
|
- A `migrate_legacy_setting_keys` flow where `restore_transcript` between a SELECT-then-DELETE could cause `purge_deleted_transcripts` to hard-delete a live row's audio. Refactored to a single atomic `DELETE … RETURNING audio_path`.
|
||||||
|
|
||||||
|
Full audit trail: `docs/superpowers/plans/2026-05-14-phase-b-dogfood-plan.md`.
|
||||||
|
|
||||||
|
### A supply-chain pre-flight
|
||||||
|
|
||||||
|
Lumotia's frontend uses npm packages. The npm ecosystem has been hit by self-replicating worms (Shai-Hulud, mini-Shai-Hulud) that compromise legitimate packages via postinstall scripts and credential-stealing.
|
||||||
|
|
||||||
|
The defence-in-depth in place:
|
||||||
|
|
||||||
|
- The dev launcher (`run.sh`) runs `npm audit signatures` before starting Vite whenever `package-lock.json` has changed since the last successful audit. Mismatch = launch refused.
|
||||||
|
- Install discipline documented in the README is `npm ci --ignore-scripts` — blocks the postinstall vector.
|
||||||
|
- All dev dependencies are version-pinned exactly (no `^` or `~` ranges).
|
||||||
|
- The Rust toolchain is pinned to `rust-toolchain.toml` so every contributor and CI runner runs the same `rustc` / `clippy` / `rustfmt`.
|
||||||
|
|
||||||
|
When we cross-referenced our 192-package dependency tree against the published mini-Shai-Hulud affected-package list, the tree came back clean. This is preventive, not remedial.
|
||||||
|
|
||||||
|
### A read-only Model Context Protocol surface
|
||||||
|
|
||||||
|
Lumotia ships an optional MCP server (`lumotia-mcp`) so you can connect Claude Desktop, Cline, or any MCP-compatible client to your local transcript history. It is:
|
||||||
|
|
||||||
|
- **Read-only.** No write tools. No delete tools. Confirmed by direct codebase audit on 2026/05/14: zero `INSERT` / `UPDATE` / `DELETE` / `fs::write` / `fs::remove` in the crate.
|
||||||
|
- **Stdio-only.** No network listener. No TCP socket. No Unix socket. The server only reads stdin and writes stdout.
|
||||||
|
- **Structurally enforced.** The database connection uses `init_readonly`, which opens SQLite with `read_only=true` — even a bug in the server can't write to your data.
|
||||||
|
- **A separate binary.** The MCP server doesn't run inside the Tauri app. You have to explicitly launch it and wire it into your MCP client's config. It is not exposed when you just open Lumotia.
|
||||||
|
|
||||||
|
Honest nuance: when you wire `lumotia-mcp` into a client, that client gets read access to your **entire** transcript history and task list. There's no per-row permission boundary in v0.1. Treat it like you'd treat giving a tool access to a folder of personal notes.
|
||||||
|
|
||||||
|
### LLM failure cannot lose your data
|
||||||
|
|
||||||
|
Lumotia uses a local LLM (downloaded once, runs on your device) for transcript cleanup and task extraction. Models can fail. The architecture is designed so **no AI failure ever loses your transcript**.
|
||||||
|
|
||||||
|
Verified failure paths (audit on 2026/05/14):
|
||||||
|
|
||||||
|
- LLM cleanup error → rule-based cleanup output preserved; status chip flashes "failed"; raw transcript unchanged.
|
||||||
|
- Task extraction error → rule-based regex extractor takes over; tasks still extracted.
|
||||||
|
- Tag extraction error → toast surfaces; transcript untouched; you can retry.
|
||||||
|
- LLM hang → raw transcript preserved; rest of the app remains functional; LLM status chip may stay on "Cleaning up" until you restart. This is the only soft edge and is documented in `v0.1-known-limitations.md`.
|
||||||
|
|
||||||
|
### Every quality gate is automated
|
||||||
|
|
||||||
|
`cargo test --workspace` (400+ Rust tests). `cargo fmt --check`. `cargo clippy --workspace --all-targets -- -D warnings`. `npm run test` (vitest). `npm run check` (svelte-check). The dogfood drill. All run before tag. All visible in CI.
|
||||||
|
|
||||||
|
## What this page is NOT
|
||||||
|
|
||||||
|
This is not a claim that Lumotia is bug-free. No software is. Lumotia is a young product written by one person; it will have bugs and it will have rough edges.
|
||||||
|
|
||||||
|
What this page is: a commitment to **disclosure, evidence, and audit-trail**. If you find a bug, file it. If you find something the known-limitations document missed, tell us — we'll add it. If you want to inspect the code, the licence is AGPL-3.0-or-later and the repository is public.
|
||||||
|
|
||||||
|
## Anti-patterns this project deliberately avoids
|
||||||
|
|
||||||
|
The list is short and specific. Each entry is a concrete failure mode this project has chosen to design around, not a vague pledge.
|
||||||
|
|
||||||
|
- **No AI-assisted feature ships without dogfood-running it on the real binary.** Unit-test-only verification is insufficient — see the migration race-condition story above.
|
||||||
|
- **No release ships with an empty known-limitations document.** A v0.1 with no known limitations is a v0.1 with known limitations its authors haven't been honest about.
|
||||||
|
- **No telemetry exfiltration.** Anonymous local-only event counts are used for activation metrics during private beta and only when the user opts in. Nothing leaves the machine. No analytics service. No phone-home.
|
||||||
|
- **No silent AI dependency.** If a feature requires the LLM to be loaded, it tells you so. If the LLM fails, the failure is visible. The product still works without an LLM at the cost of plainer output.
|
||||||
|
- **No "we'll add an audit log later".** The audit log is the git history. Every release is reachable from a tagged commit; every commit has a message that explains what changed and why.
|
||||||
|
|
||||||
|
## Closing
|
||||||
|
|
||||||
|
You're trusting Lumotia with private dictations. Voice notes you wouldn't email anyone. Working-thought captures you'd never put on Twitter. The bar for that kind of software is higher than for a meme generator.
|
||||||
|
|
||||||
|
This page is the answer to "did you take that seriously?" Yes. Here's the evidence. Read the commits. Read the test suite. Read the known limitations. Decide for yourself.
|
||||||
|
|
||||||
|
If the answer is no — that's fine, don't install it. If the answer is yes — welcome. And tell us what we missed.
|
||||||
|
|
||||||
|
—
|
||||||
|
|
||||||
|
*Last updated: 2026/05/14, against the v0.1 ship checklist. Audit trail in `docs/superpowers/plans/2026-05-14-phase-b-dogfood-plan.md` and the commits cited above.*
|
||||||
159
docs/release/v0.1-checklist.md
Normal file
159
docs/release/v0.1-checklist.md
Normal file
@@ -0,0 +1,159 @@
|
|||||||
|
---
|
||||||
|
name: v0.1-checklist
|
||||||
|
type: release
|
||||||
|
tags: [release, v0.1, checklist, tester-acceptance, activation-metrics]
|
||||||
|
description: "Source of truth for 'are we allowed to ship v0.1?'. The must-ship list, the 10-step tester acceptance test, the activation metrics for private beta + v0.1, signing/notarisation status, and the per-platform smoke-test matrix. Updated whenever an item lands."
|
||||||
|
---
|
||||||
|
|
||||||
|
# Lumotia v0.1 release checklist
|
||||||
|
|
||||||
|
**Locked scope:** v0.1 ships the stable local capture product. Garden Inbox is v0.2. Cloud providers stay dormant. OEM verification stays v0.2+. See `docs/release/v0.2-garden-roadmap.md` for what comes next.
|
||||||
|
|
||||||
|
**Tag-eligible when:** every item below is ✅ or explicitly waived in the linked known-limitations row.
|
||||||
|
|
||||||
|
## The tester acceptance test (private beta spine)
|
||||||
|
|
||||||
|
The product is ready when a stranger can complete this flow on a fresh install, on their primary platform, without coaching. Time it: if it takes more than ten minutes including the model download, the onboarding needs more work.
|
||||||
|
|
||||||
|
1. Install Lumotia from the artefact for their platform.
|
||||||
|
2. Open the app. First-run onboarding starts automatically.
|
||||||
|
3. Grant microphone permission via the OS prompt the onboarding surfaces.
|
||||||
|
4. Pick or download a speech model (sensible default suggested).
|
||||||
|
5. Test recording (a short pre-supplied prompt the onboarding asks them to read).
|
||||||
|
6. See the live transcript appear.
|
||||||
|
7. Stop dictation. See the cleaned transcript.
|
||||||
|
8. Extract one task from the transcript.
|
||||||
|
9. Break the task into MicroSteps and start a 5-minute timer on the first one.
|
||||||
|
10. Find the dictation again in History via search.
|
||||||
|
|
||||||
|
Every step has a green path. Every step has a clearly-named failure mode in the known-limitations doc. No step depends on a feature that's marked v0.2 or later.
|
||||||
|
|
||||||
|
## Must-ship
|
||||||
|
|
||||||
|
### Product surface (already shipped, verify via Phase A/B/C dogfood passes)
|
||||||
|
|
||||||
|
- [ ] Phases 1–8 functional on Linux primary, parity-tested on macOS + Windows
|
||||||
|
- [ ] Phase 9a — native OS save-dialog Markdown export (single + bulk + collision-suffixing)
|
||||||
|
- [ ] Phase 9b — LLM content tags with manualTags promote-on-click
|
||||||
|
- [ ] Phase 9d — sparkline + badge a11y + `prefers-reduced-motion` respect
|
||||||
|
- [ ] Phase 9c — Settings sanity pass: Start Here / transcription basics / model picker / privacy / accessibility / advanced (full 7-group regroup deferred to v0.2)
|
||||||
|
|
||||||
|
### First-run onboarding (engine architecture Phase F — promoted to v0.1 must-ship)
|
||||||
|
|
||||||
|
- [ ] Onboarding steps wired in `src/lib/pages/FirstRunPage.svelte`: permissions → model check/download → test recording → cleaned transcript surfaced → "you're ready" → main UI
|
||||||
|
- [ ] First-run gate routes anyone with no onboarding-event record through this flow
|
||||||
|
- [ ] `onboarding_events` SQLite table (`completed_at`, `skipped`, `version`) + migration
|
||||||
|
- [ ] Onboarding Tauri commands
|
||||||
|
- [ ] Skip-onboarding path for users who already have transcripts on disk (post-rebrand migration)
|
||||||
|
- [ ] Time-to-first-capture measurable from the onboarding events (raw signal for activation metrics)
|
||||||
|
|
||||||
|
### Release artefacts + trust path
|
||||||
|
|
||||||
|
- [ ] Three-way version sync: `Cargo.toml` workspace + `src-tauri/Cargo.toml` + `package.json` + `tauri.conf.json` all on `0.1.0`
|
||||||
|
- [ ] `CHANGELOG.md` seeded with Phase 1–8 outcomes in end-user voice (not commit-log style)
|
||||||
|
- [ ] Release notes drafted in plain language (one page max, no jargon)
|
||||||
|
- [ ] Windows code-signing certificate sourced + signing wired into `tauri build`
|
||||||
|
- [ ] macOS notarisation + Gatekeeper acceptance via Apple Developer ID (or documented Gatekeeper-warning workaround if notarisation isn't available)
|
||||||
|
- [ ] Linux AppImage SHA-256 checksum published alongside artefact + GPG signature optional
|
||||||
|
- [ ] "What warning you may see on first install" documented per platform (SmartScreen / Gatekeeper)
|
||||||
|
- [ ] CI green on Linux/macOS/Windows artefact builds on tag push
|
||||||
|
- [ ] Manual smoke-test on each platform artefact before public release (see matrix below)
|
||||||
|
|
||||||
|
### Documentation surface
|
||||||
|
|
||||||
|
- [ ] `docs/release/v0.1-known-limitations.md` complete + user-readable
|
||||||
|
- [ ] `docs/release/how-lumotia-is-built.md` complete + linked from README
|
||||||
|
- [ ] Privacy + AI-use disclosure page (what stays local, what optionally reaches the network, what NEVER leaves the machine)
|
||||||
|
- [ ] README updated for v0.1 launch: install paths per platform, first-run expectations, where to file issues
|
||||||
|
|
||||||
|
### Quality gates carried forward from Phase A + B
|
||||||
|
|
||||||
|
- [ ] `cargo test --workspace` — green
|
||||||
|
- [ ] `cargo fmt --check` — clean
|
||||||
|
- [ ] `cargo clippy --workspace --all-targets -- -D warnings` — clean
|
||||||
|
- [ ] `npm run test` — green
|
||||||
|
- [ ] `npm run check` — 0 errors / 0 warnings
|
||||||
|
- [ ] `scripts/dogfood-rebrand-drill.sh` — 8/8 probes pass (carry from Phase A)
|
||||||
|
- [ ] Rust toolchain still pinned to `rust-toolchain.toml`
|
||||||
|
- [ ] npm dev deps still exact-pinned
|
||||||
|
|
||||||
|
### Trust + security boundary verified
|
||||||
|
|
||||||
|
- [ ] MCP surface read-only / stdio-only / no write tools confirmed (see Audit 1 in `docs/release/how-lumotia-is-built.md`)
|
||||||
|
- [ ] LLM failure paths preserve raw transcript / extract tasks via fallback / never block export (see Audit 2 in `docs/release/how-lumotia-is-built.md`)
|
||||||
|
- [ ] `lumotia-cloud-providers` crate compiles but has no UI exposure (KI-04)
|
||||||
|
- [ ] `npm audit signatures` runs in `run.sh` and on CI before any tag
|
||||||
|
|
||||||
|
### Release-blocker resolution
|
||||||
|
|
||||||
|
- [ ] **RB-08** macOS App Nap power-assertion runtime verification on Apple Silicon (resolve or document with workaround per `KI-01`)
|
||||||
|
- [ ] Decision recorded per platform-power-assertion item: KI-02 Linux idle inhibit, KI-03 Windows sleep prevention — fix-if-tiny vs document-as-known-limitation (see known-limitations doc)
|
||||||
|
|
||||||
|
### Smoke-test matrix (executed against final tagged artefacts)
|
||||||
|
|
||||||
|
| Platform | Install | First-run | Capture | Cleanup | Export | History search | Uninstall + reinstall preserves transcripts |
|
||||||
|
|---|---|---|---|---|---|---|---|
|
||||||
|
| Linux (AppImage on Fedora) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||||||
|
| Linux (AppImage on Ubuntu LTS) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||||||
|
| macOS (Apple Silicon, .dmg) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||||||
|
| macOS (Intel, .dmg) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||||||
|
| Windows (.msi on Win 11) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||||||
|
|
||||||
|
A single ❌ in any cell is a tag-blocker.
|
||||||
|
|
||||||
|
## Activation metrics
|
||||||
|
|
||||||
|
### Private beta (closed, ~20 testers)
|
||||||
|
|
||||||
|
Defined activation:
|
||||||
|
|
||||||
|
- **Activation:** Tester completes their first recording within **3 minutes** of opening the app for the first time.
|
||||||
|
- **Core value:** Tester creates **3 useful captures** in the first 24 hours.
|
||||||
|
- **Retention:** Tester returns within **7 days** and uses history / search / review.
|
||||||
|
- **Quality:** Tester accepts or edits at least **one extracted task**.
|
||||||
|
- **Trust:** Tester can articulate **what stays local** if asked.
|
||||||
|
|
||||||
|
Capture mechanism: opt-in anonymous local-only telemetry (`onboarding_events` table + a tiny `lumotia_events` table for first-capture / first-export / first-search events). No exfiltration. The tester reads these themselves and reports back qualitatively.
|
||||||
|
|
||||||
|
### Public v0.1 launch (open download)
|
||||||
|
|
||||||
|
Defined pass-bar:
|
||||||
|
|
||||||
|
- Can **20 strangers** install Lumotia successfully?
|
||||||
|
- Can **15 of them** complete first capture?
|
||||||
|
- Can **10 of them** use it twice within a week?
|
||||||
|
- Can **5 of them** say they would pay **£39** for a Founding Licence?
|
||||||
|
|
||||||
|
If we don't hit these numbers, the answer is iteration on first-run + clarity-of-pitch, not feature additions.
|
||||||
|
|
||||||
|
## Out of scope for v0.1 (explicit non-goals)
|
||||||
|
|
||||||
|
To stop ourselves second-guessing under release pressure, these are pinned **not in v0.1**. Reopening any of them moves the ship date.
|
||||||
|
|
||||||
|
- Garden Inbox / review cards / suggested routing → **v0.2**
|
||||||
|
- Engine Phase B filter-chain refactor → **v0.2**
|
||||||
|
- Engine Phase C vocabulary crate → **v0.2**
|
||||||
|
- Engine Phase D model warmup coordinator → **v0.2**
|
||||||
|
- Engine Phase E dictionary quick-add → **v0.2**
|
||||||
|
- Engine Phase G OpenAI Whisper API provider → **v0.2 at earliest, with BYOK / off-by-default / never-required / clearly-labelled framing**
|
||||||
|
- Engine Phase I OEM verification → **v1.0 commercial track**
|
||||||
|
- Engine Phase J full degraded-mode indicator → **v0.2** (data-loss path closed in v0.1 per Audit 2; the UI-wedge case is documented in known-limitations)
|
||||||
|
- Full SettingsPage 7-group regroup → **v0.2**
|
||||||
|
- Rust-side OS-activity watcher for nudges → **v0.2 if ever**
|
||||||
|
- Obsidian plugin → **v0.2 ecosystem play**
|
||||||
|
- Mobile companion → not on any current track
|
||||||
|
- Cloud sync → not on any current track
|
||||||
|
|
||||||
|
## Pre-tag verification (the morning of)
|
||||||
|
|
||||||
|
In order, before `git tag v0.1.0`:
|
||||||
|
|
||||||
|
1. Re-run all quality gates fresh on a clean checkout.
|
||||||
|
2. Re-run `scripts/dogfood-rebrand-drill.sh` against a freshly-built binary.
|
||||||
|
3. Re-execute the 10-step tester acceptance flow personally on Linux.
|
||||||
|
4. Confirm the smoke-test matrix is fully green for the platforms we're announcing.
|
||||||
|
5. Confirm known-limitations doc has no item marked "TBD" or "pending decision".
|
||||||
|
6. Confirm `CHANGELOG.md` + release notes are user-readable, not commit-log dumps.
|
||||||
|
7. Tag, push to both remotes, watch CI complete the per-platform builds, smoke-test one artefact per platform from the CI output.
|
||||||
|
|
||||||
|
If any step fails, the day's ship is off. Reopen, fix, repeat.
|
||||||
98
docs/release/v0.1-known-limitations.md
Normal file
98
docs/release/v0.1-known-limitations.md
Normal file
@@ -0,0 +1,98 @@
|
|||||||
|
---
|
||||||
|
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 may be throttled by the OS
|
||||||
|
|
||||||
|
Lumotia is designed for sit-down dictation, not always-on transcription. Long sessions (10+ minutes) work fine on every platform, but the OS itself may decide to slow Lumotia down if it thinks the app is idle.
|
||||||
|
|
||||||
|
| Platform | Behaviour | Workaround |
|
||||||
|
|---|---|---|
|
||||||
|
| Linux | The compositor's idle hooks may dim the screen, lock the session, or suspend after the OS-level inactivity timeout. Lumotia does not currently inhibit those. | Wrap launch with `systemd-inhibit --what=idle:sleep:handle-lid-switch lumotia` if you need a long uninterrupted session. Or raise your screen-lock timeout in system settings. |
|
||||||
|
| macOS | App Nap may pause Lumotia after the window loses focus. We've coded the protection but the runtime verification on Apple Silicon hardware is still in progress 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 | Sleep prevention is not yet wired. Long sessions can be paused by your power plan's sleep timer. | Set your active power plan's sleep timeout to "Never" while dictating. |
|
||||||
|
|
||||||
|
Closing this gap is on the path to v0.2 if a real user reports a session-loss; otherwise it stays known.
|
||||||
|
|
||||||
|
## 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.
|
||||||
116
docs/release/v0.2-garden-roadmap.md
Normal file
116
docs/release/v0.2-garden-roadmap.md
Normal file
@@ -0,0 +1,116 @@
|
|||||||
|
---
|
||||||
|
name: v0.2-garden-roadmap
|
||||||
|
type: roadmap
|
||||||
|
tags: [release, v0.2, garden-inbox, review-cards, pkm-bridge, captured-not-implemented]
|
||||||
|
description: "v0.2 roadmap. The second act of Lumotia: review cards for turning messy dictations into notes, tasks, topics and links. Distinct from v0.1 which ships the stable local capture product. Sources: outputs/lumotia/2026-05-14-roadmap-update.md (Garden Inbox direction signal) + docs/roadmap/2026-04-23-magnotia-feature-complete-roadmap.md (engine architecture phases B–G)."
|
||||||
|
---
|
||||||
|
|
||||||
|
# Lumotia v0.2 — the Garden release
|
||||||
|
|
||||||
|
**Status:** roadmap, not specced. Each item below needs its own design pass before implementation begins. This doc fixes the **scope boundary** for v0.2 so v0.1 can ship without scope-creep negotiation, and so v0.2 doesn't expand into a full PKM build.
|
||||||
|
|
||||||
|
**v0.1 ships:** stable local capture product (transcription, cleanup, tasks, MicroSteps, timer, history, export).
|
||||||
|
**v0.2 ships:** the review-card layer that turns messy dictations into notes you can find, link, and act on.
|
||||||
|
**v1.0:** PKM-complete + commercial track (see roadmap notes).
|
||||||
|
|
||||||
|
## The headline
|
||||||
|
|
||||||
|
> **Lumotia v0.2 — review cards for turning messy dictations into notes, tasks, topics and links.**
|
||||||
|
|
||||||
|
Not "voice-first PKM". Not "AI second brain". A specific, tangible thing: a review-card flow.
|
||||||
|
|
||||||
|
## What v0.2 includes
|
||||||
|
|
||||||
|
### Garden Inbox / review cards (the marquee)
|
||||||
|
|
||||||
|
Each new capture surfaces as a review card. The card shows:
|
||||||
|
|
||||||
|
- Raw transcript (always preserved, can collapse)
|
||||||
|
- Cleaned note (LLM cleanup output, editable)
|
||||||
|
- Suggested title (LLM, editable)
|
||||||
|
- Suggested type (Note / Task / Idea / Journal / Meeting — closed set, configurable later)
|
||||||
|
- Suggested folder / project / area / person / topic (LLM-suggested from a user-defined ontology, editable)
|
||||||
|
- Extracted tasks (already shipped in v0.1, surfaced inline)
|
||||||
|
- Suggested LLM tags (already shipped in v0.1, promote-to-manual on click)
|
||||||
|
- Possible links to existing transcripts (similarity-based, deferred from "related notes" item below if needed)
|
||||||
|
- Confidence score per suggestion (so the user knows when to second-guess)
|
||||||
|
- Action: **Accept / Edit / Park / Archive**
|
||||||
|
|
||||||
|
The card is the bridge. Accept routes the capture into the ontology with all suggestions applied. Edit lets the user fix anything. Park sends it back to inbox for later. Archive removes it without routing.
|
||||||
|
|
||||||
|
### Suggested routing (extends v0.1 LLM content tags)
|
||||||
|
|
||||||
|
The shipped `extract_content_tags_cmd` returns `topic:*` and `intent:*`. v0.2 extends this to **folder / project / person / area** suggestions drawn from a user-defined ontology stored in SQLite. Users seed the ontology themselves; Lumotia learns from accept/edit signals (reusing the existing feedback loop from Phase 2).
|
||||||
|
|
||||||
|
### Related notes / backlinks
|
||||||
|
|
||||||
|
For an accepted capture, surface "transcripts that look similar" via local embedding similarity. No graph view. No canvas. Just: "you mentioned this topic in 3 other captures — here they are." Click navigates to the linked transcript in History.
|
||||||
|
|
||||||
|
This is **not** a full backlink graph in v0.2. It's a "you've talked about this before" surface.
|
||||||
|
|
||||||
|
### People / project / topic detection
|
||||||
|
|
||||||
|
Reuses the LLM suggestion pipeline from routing. Surfaces detected entities in the review card so the user can confirm or correct. Detected entities update the ontology (with explicit user consent on first surface).
|
||||||
|
|
||||||
|
### Obsidian-ready Markdown export
|
||||||
|
|
||||||
|
v0.1 already ships Markdown export with frontmatter union (auto + manual + LLM tags). v0.2 hardens this for Obsidian compatibility specifically:
|
||||||
|
|
||||||
|
- `[[wiki-link]]` syntax in the body for detected entity references
|
||||||
|
- Frontmatter fields Obsidian's Dataview plugin can query
|
||||||
|
- Vault-folder-aware export (pick a vault root, mirror the user's folder structure)
|
||||||
|
- Optional: an Obsidian plugin (later sub-item, may slip to v0.3)
|
||||||
|
|
||||||
|
### Engine architecture work landing alongside v0.2
|
||||||
|
|
||||||
|
These were ROADMAPPED items in the engine architecture spec that pair naturally with the Garden release:
|
||||||
|
|
||||||
|
- **Phase B — Filter chain refactor** (`Filter` trait, stage 1/2/3 cleanup pipeline) — needed for vocabulary work below
|
||||||
|
- **Phase C — Vocabulary crate** (`crates/vocabulary`, FTS5 + regex cache, `vocabulary_proposals` table, edit-diff `extract_corrections`) — user dictionary
|
||||||
|
- **Phase D — Model warmup coordinator** (warmup state machine, synthetic audio, `EngineStatusPill.svelte`) — perceived speed improvement
|
||||||
|
- **Phase E — Dictionary quick-add** (`Ctrl+Alt+D` panel, settings vocabulary section)
|
||||||
|
|
||||||
|
These four engine phases are not strictly required for the review-card UX but they unlock a noticeably better v0.2 experience.
|
||||||
|
|
||||||
|
## What v0.2 does NOT include
|
||||||
|
|
||||||
|
To stop v0.2 from sprawling, these are pinned **out**:
|
||||||
|
|
||||||
|
- **No graph view.** Backlinks surface as a list, not a force-directed graph.
|
||||||
|
- **No canvas.** No spatial / freeform layout.
|
||||||
|
- **No multi-user / sync.** Still single-device.
|
||||||
|
- **No mobile companion.** Still desktop-only.
|
||||||
|
- **No full PKM "second brain" marketing pitch.** Lumotia is a voice-first gardener with a review-card flow. We are not Obsidian.
|
||||||
|
- **No cloud transcription provider.** Engine Phase G stays out by default; if it lands in v0.2 it's BYOK + off-by-default + clearly labelled + never required.
|
||||||
|
- **No premium voices / paid expansion.** Still single £39 Founding tier on the licensing side (see `project_lumotia_licensing_strategy` memory).
|
||||||
|
- **No commercial / OEM track.** Engine Phase I stays v1.0.
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
- `outputs/lumotia/2026-05-14-roadmap-update.md` — Garden Inbox direction signal distilled from three 2026/05/14 captures (Wispr Flow / Superwhisper / AudioPen / Granola landscape + "voice-first gardener" positioning)
|
||||||
|
- `docs/roadmap/2026-04-23-magnotia-feature-complete-roadmap.md` — Phase 1–10 plan + post-v0.1 ideas section
|
||||||
|
- `outputs/lumotia/2026-05-10-engine-architecture-spec.md` — engine architecture Phases A–J
|
||||||
|
- `project_lumotia_licensing_strategy` memory — locked pricing / dual-licence / OEM exception
|
||||||
|
|
||||||
|
## Open decisions for v0.2 scope freeze
|
||||||
|
|
||||||
|
These will be decided when v0.1 ships, not before:
|
||||||
|
|
||||||
|
1. **Ontology bootstrapping** — do users define their ontology by hand, or does Lumotia seed it from the first 10 captures?
|
||||||
|
2. **Confidence-score surfacing** — numeric (0.0–1.0), banded (high/medium/low), or implicit (only show suggestions above threshold)?
|
||||||
|
3. **Park vs Archive semantics** — Park goes back to inbox for later, Archive removes from inbox but keeps in History? Or another shape?
|
||||||
|
4. **Obsidian plugin scope** — full plugin with two-way sync, or one-way export only?
|
||||||
|
|
||||||
|
None of these block v0.1.
|
||||||
|
|
||||||
|
## How v0.2 lifts out of v0.1
|
||||||
|
|
||||||
|
The path:
|
||||||
|
|
||||||
|
1. v0.1 ships and gets 20+ testers
|
||||||
|
2. Watch what testers actually do with their captures (what they accept, edit, retry, abandon)
|
||||||
|
3. Lock the review-card scope based on tester behaviour, not on this doc's speculation
|
||||||
|
4. Ship v0.2 incrementally: Garden Inbox first, suggested routing second, related notes third
|
||||||
|
5. Each sub-feature gets its own design pass before code is written
|
||||||
|
|
||||||
|
The shape above is the boundary, not the spec.
|
||||||
Reference in New Issue
Block a user