Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Complete Daily-Use App

This page defines the release-readiness target for Lapis Notes as a complete, daily-usable notes app. It exists to keep the next implementation phase focused on the core loop instead of expanding platform or feature surface area.

Release Goal

Lapis Notes is ready for a complete daily-use release when a user can rely on the app for local-first note taking across the approved browser/PWA and Electron hosts without losing notes, layout, settings, or the ability to recover from common failures.

Core User Journey

The release target is the end-to-end loop below.

  1. Open an existing vault or create a new vault.
  2. Create, edit, rename, and delete Markdown notes.
  3. Preserve or edit frontmatter safely.
  4. Link notes together and navigate those links.
  5. Search note content and basic metadata.
  6. Create a notebook and run simple explicit cells.
  7. Enable or disable first-party and compatible plugins.
  8. Quit or reload the app and reopen without unexpected data or layout loss.
  9. Recover from common startup, plugin, layout, metadata, search, or notebook failures.

In Scope

Must Have

  • Browser or PWA local vault usage.
  • Electron folder-backed vault usage.
  • Markdown note creation, editing, rename, and deletion.
  • Safe frontmatter preservation or editing.
  • Note linking and link navigation.
  • Safe link behavior during note rename.
  • Basic metadata indexing.
  • Basic full-text search.
  • Notebook creation with explicit cell execution.
  • Clear notebook output persistence or output lifecycle semantics.
  • Plugin enable or disable controls.
  • Safe Mode or equivalent recovery path for bad plugins or layout state.
  • Browser-local export or backup flow.
  • Restart or reload without losing notes, layout, settings, or required generated state semantics.

Should Have

  • Visible diagnostics when startup recovery or rebuild flows are used.
  • Journey-based automation that covers the complete daily-use path.
  • Documentation that distinguishes canonical vault data from generated app state.
  • Clear host-specific validation instructions for browser/PWA and Electron.

Explicitly Deferred

  • Advanced graph optimization.
  • Map or calendar views.
  • Complex TaskNotes parity beyond the current daily-use milestone.
  • LLM or reranker integrations.
  • Full VS Code extension parity.
  • Advanced plugin isolation beyond the current trusted and fallback tiers.
  • Advanced collaborative sync.

Reliability Checks

  • Startup succeeds for the browser/PWA host and the Electron host.
  • Vault contents remain canonical when metadata, search, or notebook generated state is missing or rebuilt.
  • A failed plugin or broken layout does not trap the user outside recovery.
  • Rename, delete, search, and notebook flows remain understandable after restart or reload.
  • Export, import, or reveal-vault flows expose where the user’s canonical data lives.

Required Test Coverage

  • Root pnpm check:all remains the default post-change validation path for every code change.
  • Root pnpm test:smoke remains the pre-commit gate for changes that can affect the running workspace or desktop app; unrelated script, docs-site, roadmap, and spec-only work should stop at the relevant check:all path.
  • At least one journey-based automated test covers the complete user loop from vault open or creation through restart.
  • Focused tests cover plugin failure recovery, layout-restore failure recovery, and generated-state rebuild paths when those behaviors change.

Required Documentation

  • The spec documents the complete daily-use release target on this page.
  • Recovery flows document what is canonical user data and what is rebuildable generated state.
  • This checklist links to File System, Metadata, and Search, Workspace App, and Notebook Plugin for the browser-local import/export, desktop reveal-folder, generated-state rebuild, and notebook output-clearing flows that support this milestone.
  • Testing docs point at the journey coverage and smoke gate.
  • Roadmap and agent guidance point back to this milestone before expanding scope.

Required Recovery Flows

  • Start with community plugins disabled.
  • Start with layout restore disabled.
  • Rebuild metadata generated state without deleting notes.
  • Rebuild search generated state without deleting notes.
  • Clear notebook generated outputs without deleting notebook source.
  • Disable notebook execution temporarily for recovery.
  • Import, reveal, or export canonical vault data from supported hosts.
  • Surface the last startup failure reason when practical.

Known Blockers and Tracked Work

The current release-critical implementation sequence is:

  1. Issue 77: Define a complete daily-use app release milestone and acceptance checklist
  2. Issue 82: Clean up milestones and agent workflow guardrails
  3. Issue 78: Add Safe Mode and recovery flows for startup, plugin, layout, metadata, and search failures
  4. Issue 80: Harden data export, import, backup, and generated-state rebuild flows
  5. Issue 79: Polish Notebook v0 into a reliable, understandable feature
  6. Issue 81: Add journey-based e2e and smoke tests for the complete daily-use path
  7. Issue 90: Add explorer copy path, native file actions, and Lapis app URLs
  8. Issue 91: Replace plugin list diagnostics with VS Code-style Features panel
  9. Issue 95: Restore metadata cache from database or portable backup

New release-critical work should either fit this milestone directly or become a deferred follow-up issue instead of widening the current release.

Release Gate

Do not tag a complete daily-use release until all items below are true.

  • The core user journey works on the approved browser/PWA and Electron hosts.
  • Recovery flows exist for startup, plugin, layout, metadata, search, and notebook failure cases within the scoped release target.
  • Data-safety flows explain and protect canonical vault files.
  • Notebook execution behavior is explicit, understandable, and survives restart with clear semantics.
  • Journey automation and smoke coverage pass on the supported validation path.
  • Deferred work remains outside the milestone unless its acceptance criteria are promoted explicitly.

Scope Control Rule

Stop adding platform surface area until the daily-use loop is reliable, recoverable, and test-covered.