---
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.*
