Files

Jake c5460a169c 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)

2026-05-14 21:49:54 +01:00

9.0 KiB

Raw Blame History

name, type, tags, description

name

type

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.

Install Lumotia from the artefact for their platform.
Open the app. First-run onboarding starts automatically.
Grant microphone permission via the OS prompt the onboarding surfaces.
Pick or download a speech model (sensible default suggested).
Test recording (a short pre-supplied prompt the onboarding asks them to read).
See the live transcript appear.
Stop dictation. See the cleaned transcript.
Extract one task from the transcript.
Break the task into MicroSteps and start a 5-minute timer on the first one.
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:

Re-run all quality gates fresh on a clean checkout.
Re-run scripts/dogfood-rebrand-drill.sh against a freshly-built binary.
Re-execute the 10-step tester acceptance flow personally on Linux.
Confirm the smoke-test matrix is fully green for the platforms we're announcing.
Confirm known-limitations doc has no item marked "TBD" or "pending decision".
Confirm CHANGELOG.md + release notes are user-readable, not commit-log dumps.
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.

9.0 KiB Raw Blame History Unescape Escape