Omniscio

Vault mobile, sync and internals — phones, crash recovery and the command surface

Using the vault away from the desktop and under the hood — the mobile experience, what happens after a crash, what is deliberately not built yet, the command surface an agent or script calls, how the vault is put together, and what it promises about your notes.

On this page

What it is

This page covers the vault on a phone, recovering it after a crash, the features deliberately left out, the command surface underneath it, and the two statements worth reading before trusting it with anything important: how it is built and what it promises about your data.

Where to find it

On mobile the vault appears through the app's mobile layout — see "Mobile UX" below for how to get your notes onto a phone. Everything else here is behind the scenes — read from a checkout rather than from a screen.

How it behaves

Mobile UX

On a narrow, touch viewport (useIsMobile() — ≤767px + touch; the web-access companion and small windows) the Vault panel swaps its desktop chrome for a purpose-built mobile layout (the "Writer focus" direction). Desktop is unchanged — every surface is gated behind isMobile.

Getting your notes onto a phone. Notes reach the phone through Mobile Access: turn it on in Settings → Remote Access (the pane headed "Mobile Access"), pair the phone, and open the address it gives you — pick the Vault from the project drawer and you get the same notes as on your desktop. The notes themselves live on your computer, so it has to be on with Omniscio running and the vault folder reachable; the phone holds only a cached copy of what it is showing.

  • Minimal header (KmsMobileHeader) replaces Omniscio's generic project breadcrumb (suppressed for the KMS project via shouldShowMobileBreadcrumb): ☰ Open notes · note title · ⋯ More.
  • Notes drawer (KmsNotesDrawer) — ☰ slides the file tree (FileTreePanel, unchanged) in over the editor with a backdrop scrim; tapping a note opens it and auto-closes the drawer (KmsView watches activeTabId).
  • Swipeable tabs — on mobile TabBar drops the measured-overflow +N dropdown and becomes one horizontally-scrollable momentum row, so every open note is reachable by swipe.
  • Action sheet (KmsActionSheet) — ⋯ (or the quick bar's "Aa More") slides up a bottom sheet holding every editor control: a Format grid built from the same TOOLBAR_GROUPS catalog the desktop toolbar renders (a completeness test pins it, so nothing can be unreachable on mobile), plus a View section (Outline & panels · Find · Source view · Bookmark) wired to the same hooks the desktop View/Bookmark groups use.
  • Quick-format bar (KmsQuickFormatBar) — a slim bottom strip shown only while the editor has focus, with two regions: a horizontally-scrolling icon row (MOBILE_QUICKBAR_COMMAND_IDS: Bold · Italic · Bullet · Numbered · Undo · Redo) and an always-visible pinned cluster (MOBILE_QUICKBAR_PINNED_COMMAND_IDS: Decrease indent · Increase indent) held outside the scroll region, beside the pinned "Aa More" button. Pinning the indent pair (2026-06-15) fixes a reported "I don't see any indent buttons on my phone": they used to be the last two of eight scrolling icons, parked just past the (hidden-scrollbar) right edge — invisible with no cue to swipe. undo/redo now trail the scrolling row (still one tap away under "Aa" if they scroll off). Decrease / Increase indent are the only way to change a list item's nesting on mobile — there's no Tab key — and they reuse the exact indentListItem / outdentListItem helpers the desktop Tab / Shift+Tab keys call (contract I8), greying out when the caret isn't inside a list. The bar subscribes to the editor's transactions (guarding isDestroyed) so the undo/redo + indent enable-state stays live without risking the torn-down-editor crash; link, headings, and the rest stay one tap away in the action sheet.
  • Multi-column blocks become a one-per-screen carousel — a :::columns block (2–5 side-by-side columns on desktop) can't fit on a phone, so at ≤767px each column fills the full pane width and the block scrolls sideways with scroll-snap, showing exactly one column per screen (swipe to the next; the page itself never scrolls sideways). To make this overridable without an !important hack, ColumnBlock.renderHTML emits the per-block track widths as a --kms-column-tracks custom property — so the stylesheet (not an inline grid-template-columns) owns the layout, and the mobile media query can collapse display: grid → display: flex (.column-item { flex: 0 0 100% }); desktop stays a byte-for-byte grid. Snap is proximity (not mandatory) so it never yanks the scroll or traps the caret while editing. (Revises the 2026-06-11 "12rem side-by-side scroll" — at 12rem the visible column sat ~190px and the next was cut off mid-content.) Pinned in kms-editor-styling-contract.md (content-fits-the-pane) + kms-editor-css-contract.test.ts.

File-list actions on a touch screen. Every file-tree row ends in a ⋯ button (shown on touch screens only) that opens the row's actions as a bottom sheet — Rename, Move to…, Copy link, Publish page…, Hide, Delete, only the ones that row offers. Move to… opens the folder picker, which MobileKmsPanel hosts on the Files screen (see "Moving a note" in KMS). Tree rows use the shared 44px touch target on touch screens.

The desktop formatting toolbar and the status bar are hidden on mobile (the sheet + quick bar replace them). All tap targets are ≥44px; shared class strings live in features/kms/styles.ts as KMS_MOBILE_*. Bookmark add/remove is shared with the desktop button via the useBookmarkToggle hook. Because these surfaces float over the note text (not the app gradient like the desktop panes), they share the KMS_MOBILE_PANEL_SURFACE opaque floor (.kms-mobile-panel-surface in globals.css) instead of a translucent --panel-bg + blur — otherwise the text bleeds through on mobile, where backdrop-filter is unreliable (contract I13).

AI sessions on mobile (2026-06-09). The KMS sub-sidebar previously hard-returned only <FileTreePanel /> on mobile (if (isMobile) return <FileTreePanel />), so a phone user could browse notes but never reach the vault's AI sessions. KmsSubSidebar's isMobile branch now renders MobileKmsPanel — the same Files | Sessions toggle desktop has, via the shared KmsViewTabStrip (one toggle component for both surfaces). Files is the notes tree (the unchanged default tab); Sessions is the vault's agent sessions through the shared SessionHostSidebar, so the session sort, rename/pause/archive context menu, and status dots are all inherited (no hand-rolled rows). Tapping a session — or + New, which launches into the list rather than auto-jumping (mirroring SMS, since the session-host factory's onSpawn is fire-and-forget) — drills the mobile nav into session-detail; that detail slot yields the SessionPanel chat instead of the KmsView editor when the active integration's registry shouldYieldToSessionChat predicate returns true. KMS's predicate reuses the same pickKmsMainPane decision (Sessions view + a session), which Dashboard resolves once into the generic integrationYieldsToSessionChat boolean both shared layouts consume — so desktop and mobile agree and the gate stays a no-op for every non-yielding virtual project. The invariant is pinned in session-host-contract.md (KMS consumer section), ai-coaching-mobile-layout-contract.md, + MobileKmsPanel.test.tsx.

Crash recovery

If Omniscio crashes (OS kill, power loss, renderer process death) while you have unsaved edits, those edits are recoverable on the next launch. A debounced draft save writes the editor's pending content to a nothari_note_drafts SQLite table while any note has unsaved changes — it fires after about 2 seconds of idle, stretching up to 15 seconds for very large notes. On relaunch, if a draft's timestamp is newer than the on-disk note's updatedAt, a persistent toast appears: "Recovered unsaved edits for [note names]" with Restore all / Review… actions. Restoring a draft whose note has an open tab loads the body back into the editor, marks it dirty and lets autosave persist it; with no open tab it writes the recovered body straight to disk. Discarding happens in the Review… dialog — per note, or Discard all — and asks for confirmation because it is permanent. Drafts older than 7 days are auto-pruned. A successful autosave clears the matching draft immediately, so drafts only persist across a crash — they never accumulate during normal use. See kms-crash-recovery-contract.md.

What the Vault does not include

The Vault is a notes tool, not a project manager: no tasks panel, no recurring tasks, no calendar. There is also no wizard for moving notes out of the older standalone KMS desktop app — the Obsidian importer is the one migration path. And you work in one vault folder at a time: several folders can stay registered (see the safety contract below), but only one is live on the Vault screen.

Two things older copies of this page listed as deferred are shipped: web clipping — see KMS Web Clipper — and hybrid semantic search with Smart Connections (kms-part-3.md). Templates ship too: with no note open, the empty editor area lists ready-made starting points under Start from a template.

Live updates on web and mobile are note-changed only, and catch up on reconnect. The web bridge forwards kms:note-changed to a paired phone (it is in the bridge's push allow-list), and the phone reconciles its cached copy of an open note from the kms store's own listener, so a note edited on the desktop updates on the phone even while the phone is on the Files list with no editor on screen. A phone that lost its connection missed those pushes, so on every reconnect it re-checks each open note: a clean open note is re-read, a clean cached one is dropped, and a note with unsaved edits is left alone.

IPC channels + the HTTP CLI surface

KMS has two distinct surfaces, easy to conflate:

  • IPC channels (kms:*, listed below) are the renderer↔main contract the in-app editor uses. They are not reachable by a spawned agent or an external script — they need the Electron preload bridge, not HTTP. (Earlier drafts of this page wrongly called these an "agent CLI surface"; they are not.)
  • HTTP CLI control-server routes (/kms/*) are the agent-reachable surface on 127.0.0.1:19519. They reuse the same db queries + write service as the IPC handlers, so the two cannot drift. It began on 2026-06-08 as a curated read + safe-capture subset and reached full parity with the in-app Vault on 2026-06-25.

HTTP CLI control-server routes (agent-reachable)

About 72 routes, all gated by nothariEnabled except the two vault-setup routes (GET /kms/vault/validate and POST /kms/vault/default-folder), which answer while the Vault is off on purpose — you check and create a folder before turning the Vault on. When the gate applies and the Vault is off they return 403 with code: "KMS_FEATURE_DISABLED" (released-but-off, not 404). They come in three tiers:

  • Reads — apply immediately. GET /kms/vaults, /kms/vault/health, /kms/vault/validate, /kms/notes, /kms/notes/:id, /kms/notes/:id/backlinks, /kms/notes/:id/smart-connections, /kms/notes/:id/versions, /kms/notes/:id/summary, /kms/search, /kms/search/titles, /kms/search/unified, /kms/semantic-search, /kms/tags, /kms/notes-by-tag, /kms/inventory, /kms/hidden, /kms/trash, /kms/bookmarks, /kms/tabs, /kms/images, /kms/images/:sha, /kms/images/search, /kms/images/orphaned, /kms/images/:sha/refs, /kms/project-context, /kms/aggregation/status|history|settings, /kms/summary/spend-today, /kms/summary/bulk-seed/status, /kms/obsidian-import/vaults.
  • Reversible writes — apply immediately. POST /kms/notes (create), PUT /kms/notes/:id (edit), POST /kms/notes/:id/rename, /kms/notes/:id/move, /kms/notes/:id/hide, /kms/notes/:id/unhide, /kms/notes/:id/open, /kms/notes/:id/touch-opened, /kms/notes/:id/versions/:versionId/restore, /kms/trash/restore, tag rename, tags / bookmarks / tabs edits, unpinning and reordering project-context notes, /kms/images/import, /kms/images/:sha/replace, /kms/images/:sha/metadata, /kms/clip, /kms/unfurl/tweet-screenshot, /kms/quick-note, /kms/obsidian-import.
  • Approval-gated — they wait for your click. Deletes (DELETE /kms/notes/:id — to the trash — DELETE /kms/images/:sha, DELETE /kms/tags/:tag), POST /kms/project-context (pinning a note as project context), the paid AI work (POST /kms/notes/:id/summary/generate, /kms/summary/bulk-seed, /kms/images/analyze, /kms/aggregation/run), and POST /kms/pages/publish. Each one enqueues an approval card in your inbox and applies nothing until you approve it.

/kms/images/:sha/replace counts as reversible because it KEEPS the picture it replaced: the old file stays on disk as an unreferenced asset (waiting for the approval-gated orphan cleanup), so restoring the note's earlier version brings the picture back. Erasing image bytes is DELETE /kms/images/:sha only.

Vault is resolved: explicit vaultId → the configured vault → the single registered vault → otherwise 409. Invariants: kms-cli-routes-contract.md. Full route reference + curl examples: the omniscio-control skill's kms.md spoke.

IPC channels — read (renderer↔main; Phase 1)

  • kms:vault-list — returns { vaults: KmsVault[], activeVaultId } summarizing every registered vault plus the configured vault's id.
  • kms:note-read — input { noteId } or { vaultId, relativePath } → returns { note: KmsNote } | null. Populates body with the note's Markdown. A note larger than 5 MB comes back as a truncated copy — the first ~5 MB followed by a […note truncated by KMS — exceeds 5 MB body cap…] line — never the whole file, and the Vault refuses to save that copy back, so read or edit a note that big in another editor. A file that is already larger than 25 MB when the Vault scans it is skipped and never appears; a note that grows past 25 MB after it was indexed keeps its last indexed copy and stays listed.
  • kms:search — input { query, limit?, vaultId? } → returns { hits: KmsSearchHit[] } ranked by FTS5 bm25() (lower = stronger match). snippet is the FTS5 snippet() output with <mark> tags.
  • kms:health — returns KmsHealthSnapshot summarizing per-vault index state (root exists, root is symlink, health enum ok | pending | error, last index timestamp, last error string).
  • A bug report carries a path-free slice of that snapshot as its vault field (collectVaultDiagnostics in src/main/services/bug/vault-diagnostics.ts), so a "my notes are gone" report says whether the folder is reachable and what the index thinks, instead of leaving support to rebuild it from raw log lines. Per vault it sends rootExists, rootIsSymlink, health, lastIndexedAt, lastError and noteCount — never rootPath and never rootName, because a folder name is personal content. It is null while the Vault is off, it is clamped to 50 vaults and 2000 characters of lastError, and it is raced against its own 1.5 s deadline: the probe stats a user-chosen path, so an unreachable network share must degrade THIS FIELD to null rather than blow the whole bundle's deadline and leave the report with no diagnostics at all.
  • kms:note-list — input { vaultId, limit? } → returns { notes: KmsNote[], indexReady: boolean }, where indexReady reports whether the folder has finished its first index and limit caps how many rows it reads. The renderer's file tree consumer.

IPC channels — write (renderer↔main; Phase 2)

  • kms:note-create — input { vaultId, relativePath, initialBody?, origin? } (origin is button | template | link and only drives feature tracking) → returns { note: KmsNote }. Creates a new .md file under the vault root through the same tmp-file-then-rename atomic write every write path uses, with an optional initial body (initialBody, 5 MB cap). A path that is already taken is not rejected: pickAvailableNoteRelativePath renames the note to name 2.md, name 3.md, … and creates it there, so read note.relativePath from the result instead of assuming the path you sent. A path that resolves outside the folder is refused.
  • kms:note-write — input { vaultId, relativePath, body, expectedUpdatedAt? } → returns { bytesWritten, updatedAt, conflict?, currentUpdatedAt? }, where conflict: true is a refusal and always arrives beside currentUpdatedAt. The autosave path: the renderer's kms-store debounces calls at 500 ms and sends the note's cached baseline updatedAt as expectedUpdatedAt. That token is the safety: a note whose updatedAt no longer matches it is answered { bytesWritten: 0, conflict: true, currentUpdatedAt } and nothing is written, and a call carrying no expectedUpdatedAt is answered the same way rather than blind-writing. A write to a path with no note row throws. The 5 MB body cap is checked before the per-note lock is taken, and a refused save after the file was edited outside the app also comes back as a conflict.
  • kms:note-rename — input { vaultId, oldRelativePath, newRelativePath } → returns { note }, the renamed KmsNote with its new relativePath and title, plus staleBackLinks?: string[] naming any back-link notes that could not be rewritten. A rename the service refuses (source missing, target already on disk or already indexed, identical names) comes back as { success: false, error, code? } instead of a data payload. Renames the file and updates the nothari_notes row, then updates every link in the vault that pointed at the note: the full path ([[notes/old]]), the plain name the editor's own link picker writes ([[Old Name]], in any letter case, with or without .md), a #heading or |Alias on either form, ! embeds, and relative Markdown links ([text](../notes/old.md)). A plain name that another note also holds is updated only where the stored link pointed at the renamed note. Each rewritten note is saved through the normal note write path, so it gains a version-history entry, and a note that cannot be written is reported back as a stale back-link rather than failing the rename.
  • kms:note-move — input { vaultId, oldRelativePath, newParentDir } → returns { note: KmsNote }. Relocates the note FILE into a new parent folder (newParentDir: '' = vault root) and rewrites every [[wiki-link]] back-reference the same way rename does. Unlike rename the input is a destination FOLDER, not a full path, and there is no ordering / beforePath parameter — the file-tree drag-and-drop sends exactly this shape (so a dropped note relocates folders only, never reorders).
  • kms:note-soft-delete — input { vaultId, relativePath } → returns { trashEntryName: string | null }, null when neither the file nor a note row existed so there was nothing to move. Moves the file into <vaultRoot>/.trash/ as <stamp>__<vault-relative path>, where <stamp> is the ISO timestamp with : and . turned into - and every / in the path becomes __ — a notes/old.md note becomes 2026-11-13T04-05-06-789Z__notes__old.md — and a name already taken in the trash gains a __<N>__ collision suffix (…T04-05-06-789Z__2__notes__old.md). It also writes a <entry>.versions.json sidecar holding the original relativePath and the note's version history, then removes the nothari_notes row. The vault root file watcher and the indexer both ignore .trash/ so the move doesn't ping-pong back through the indexer.

Tabs (new in Phase 2 — nothari_tabs table, v194)

The renderer mirrors its open-tabs strip into a small table so relaunches restore the user's last working set. All four routes gate on nothariEnabled and respect the standard is_deleted = 0 soft-delete contract.

  • kms:tab-list — input { vaultId } → returns { tabs: KmsTab[] } sorted by display_order (0-based, left-to-right slot in the strip).
  • kms:tab-upsert — input is the full tab row { id, vaultId, notePath, isPinned, displayOrder, openedAt, lastActiveAt } → returns { success: true } only, with no tab payload. Idempotent — opening an already-open note bumps last_active_at and re-uses the row.
  • kms:tab-delete — input { id } → returns { success: true }. Soft-deletes the row (is_deleted = 1). The row is a tombstone with a time limit: the periodic retention tick hard-deletes every closed tab that has been idle for 30 days (purgeSoftDeletedTabsOffThread, queries-kms-tabs-retention.ts), so the table cannot grow by one permanent row per note ever opened. A tab that is still open is never touched, and a tab closed inside the window is still revivable by its own id when it is re-upserted.
  • kms:tab-reorder — input { orderedIds } → returns { success: true }. Bulk reassigns display_order to match the array, in a single transaction.

Pinning a tab (desktop). Pinned tabs sort first as a block and stay visible when the strip overflows, and the set survives a relaunch (is_pinned above). The on-ramp is a right-click context menu on any tab — Pin tab / Unpin tab plus Close tab. (Before 2026-06-20 the only pin affordance was an inline unpin glyph that rendered solely on already-pinned tabs, so a fresh tab could never be pinned from the UI — the backend shipped in Phase 2 but sat dormant for want of this entry point.) The menu reuses the shared EditorContextMenu (portal + viewport-clamp + Esc / outside-click + keyboard nav) the file tree and editor body already use. The mobile strip omits it — right-click / long-press there is reserved for the Phase-9 multi-select gesture, so its <Tab/> rows render without the handler.

Tab keys and note history (2026-11-18). The Vault's tab strip answers Ctrl+W (close the tab you are on), Ctrl+Tab and Ctrl+Shift+Tab (next / previous tab, wrapping at the ends), and the two chevron buttons at the left of the strip step Back and Forward through the notes you have visited (Alt+ArrowLeft / Alt+ArrowRight; Cmd+Option+Arrow on a Mac, so Option+Arrow keeps moving the caret by word). All five are ordinary Vault keybindings — they appear under Settings → Keyboard shortcuts → Vault → Panel commands, can be rebound, and are listed in the Vault command palette. In the pop-out Vault window the close key closes the tab, never the window; it closes the window only when no tab is open. Each tab also keeps its own undo history, cursor and scroll position: switching away and back restores all three, unless the note changed on disk while you were away, in which case the editor reloads from the file.

Push events

  • kms:note-changed — fires when the file watcher OR a write-side handler updates a note. Payload: { vaultId, noteId, relativePath, op: 'added' | 'updated' | 'removed' }. The kms store's own module-level listener handles it on every surface, desktop and phone; the channel is in the web bridge's push allow-list, not in the lint test's DESKTOP_ONLY_CHANNELS exemptions.

How it works

Backend

Data lives in six tables. Phase 1 added five (migration v193): nothari_vaults (one row per vault root), nothari_notes (one row per .md file), nothari_tags (denormalized (note_id, tag) for #hashtag lookups), nothari_links (denormalized [[wiki-link]] occurrences with target_title and best-effort resolved_note_id), and nothari_notes_fts (FTS5 external-content virtual table indexed on title + body). Phase 2 adds the sixth (migration v194): nothari_tabs (id, vault_id, note_path, is_pinned, display_order, opened_at, last_active_at, is_deleted, with FK CASCADE on vault_id so unregistering a vault sweeps the tabs).

Frontend (new in Phase 2)

The KMS panel's view is small; the heavy lifting is in three lazy-loaded children:

Layout (post-2026-05-21 rework): KMS no longer renders its own three-pane grid. The file tree is registered as the integration's sidebarComponent so it mounts in Omniscio's native Pane 2 slot via the standard RoutedSubSidebar — same shape as Tools, Skills, Alarms, AI Coaching. On desktop the sub-sidebar toggles between Files (the tree) and Sessions — the Sessions view lists the vault's AI sessions, each rendered with the shared SidebarSessionRow so a KMS session carries the SAME controls as a main-sidebar session: middle-click to archive, the right-click context menu (archive / snooze / pause / move), the hover ⋯ menu, status dots, and Ctrl+Z / Undo (it reuses the shared useCloseSession hook; single-select, no drag-reorder). The panel body is a single editor column. The right-pane panel stack (Outline / Backlinks / Smart Connections / Tags / Bookmarks / Hidden / History / Trash) is a slide-out drawer (KmsRightPaneDrawer.tsx) toggled by the PanelRight button in the editor toolbar's View group; open state persists via appSettings.nothariRightPaneOpen (default false). The drawer mounts INSIDE the editor body region — below the toolbar + tab bar — so it never covers the header (its toggle stays clickable while open). Since 2026-11-16 it is a solid floating card (inset from the edges, rounded) rather than glass, and while it is open on desktop the editor body takes right padding so the note slides left instead of being covered. It animates in/out via transition-transform + translate-x (200ms, reduced-motion aware, mirroring the mobile KmsNotesDrawer) and lazy-mounts its panels on first open (a never-opened drawer fires no per-note IPC). Because its toggle lives in the note-only toolbar, the drawer is reachable only while a note is open. (Before the 2026-06-09 rework it mounted/unmounted instantly at top-0, covering the toolbar.) Prior to the rework KMS shipped with panelOwnsLayout: true and an in-panel left column, which duplicated DOM rows whenever a sidebar entry was registered for the same integration; the rework removes the in-panel column and adds the registry entry simultaneously, so the two changes can't drift apart.

  • ./editor (KmsEditor.tsx) — the TipTap-based markdown editor. React.lazy()'d behind the panel so the ~150 KB gzipped TipTap + StarterKit + Markdown + 17 custom extensions bundle never enters the entry chunk when KMS is disabled.
  • ./toolbar/EditorToolbar — lazy too, for the same TipTap-dep reason. Renders the collapsed single-row layout described above (Bold · Italic · Heading▾ · Bullet · Link · ⋯ More). Subscribes to selection / transaction updates via useEditorState with a destroyed-editor guard (ed && !ed.isDestroyed) so the selector never dereferences a torn-down editor; every button additionally short-circuits its onClick on editor === null || editor.isDestroyed. The shared dropdown primitive lives at ./toolbar/ToolbarMenu.tsx.
  • ./context-menu/EditorContextMenu, ./popovers/LinkPopover, ./popovers/ImagePopover — lazy, each opens-on-demand only.

The 18 custom TipTap extensions cover behavior the upstream StarterKit doesn't (column blocks, hidden blocks, task blocks, vault-relative image rendering, wiki-link suggestion, undo grouping, block inserter, search highlight, URL paste handler, link normalizer, block escape, markdown shortcuts, no-join ordered list, ordered-list numbering continuation, slash command, keyboard shortcuts, tables with GFM roundtrip, frontmatter passthrough via the Markdown extension).

Editor state lives in the Zustand store. The store owns: the open tabs (mirrored to nothari_tabs via the kms:tab-* IPC channels), the active tab, the in-flight autosave timer (500ms debounce per tab), the dirty bit per tab, and the cached body for each open note. On kms:note-changed from the watcher, the store invalidates the affected note's cache and (if it's the active tab) re-reads it into the editor — but only if the local dirty bit is false, so a concurrent external edit can't clobber in-progress user typing.

The find/replace overlay hooks into the editor via the SearchHighlight extension; the source view toggle swaps the TipTap surface for a raw textarea while preserving the round-trip through the markdown serializer.

The status bar is one of the few KMS files statically imported by KmsView. It uses @tiptap/react's useEditorState for word / char count, which would normally pull @tiptap/react into the entry chunk — but @tiptap/react is already in the entry chunk via the type-only import type { Editor } from '@tiptap/core' shared across the panel, so the static import is layout-stable without a bundle regression. (The heavy bits — StarterKit, @tiptap/markdown, and all 17 extensions — stay in the editor chunk; the lazy-load test only asserts those tokens, not @tiptap/react identifiers.)

Privacy + safety contract

  • Omniscio writes only inside a folder the Vault has registered. Every write-side handler resolves the caller-supplied path through resolveInsideVaultForWrite(), which rejects .. traversal, absolute paths and any lexical escape, then re-checks containment against the real path of the nearest existing ancestor — so a write that would land outside the folder through a symlinked folder is refused, while a symlink that stays inside is followed. The system-directory and symlinked-root refusals are a separate gate: isSystemPath() (Windows: C:/Windows, C:/Program Files; POSIX: /etc, /sys, /proc) runs only from validateVaultRoot(), which also refuses a folder that is itself a symlink. A folder you picked before stays registered when you switch to another, and agents address any registered folder by id — so an agent can still read and write notes in a folder you moved away from, even though your Vault screen shows only the current one.
  • Soft-delete is non-destructive, but it is not permanent — the trash is swept. kms:note-soft-delete moves the file into <vaultRoot>/.trash/ as <stamp>__<vault-relative path> — every / in the path becomes __, so a notes/old.md note becomes <stamp>__notes__old.md, and a name already taken in the trash gains a __<N>__ collision suffix — rather than unlinking, so a deleted note's body is recoverable by hand and, from inside Omniscio, from the Trash panel in the Vault, which lists what is in there and restores one — and by agents (GET /kms/trash, POST /kms/trash/restore — body { vaultId, trashEntryName }, where trashEntryName is an entryName from the list, not the note's path) without restoring from external backup. A restore puts the file back at its own path, or under a free name when that path is taken again, and re-indexes it; the note's tags and its saved versions come back with it, but its bookmark and any project-context pin do not, because the delete dropped them. That recovery window is time-limited: the periodic retention tick runs pruneKmsTrashOlderThan() (trash-retention.ts), which deletes every regular file sitting directly inside a vault's .trash once it has sat there for 30 days — or your Settings → Data & Security → Data Retention (days) value, whichever is longer — counted from the day you deleted it. The window never drops below 30 days, whatever that setting says, and it starts at the delete rather than at the note's last edit. Past that window the sweep removes the trashed note file and its version sidecar — the <entry>.versions.json snapshot of that note's earlier versions, which sits in .trash right beside it. .trash is excluded from the indexer and from the backup mirror, so neither file is re-indexed or backed up again. That is all the sweep removes. Copies of what the note held live outside .trash and are not removed with it: images the note embedded stay in the vault's assets/ folder together with the text the AI read from them; an unsaved-edit draft stays in the crash-recovery drafts store; automatic backups taken before the delete still hold the note as it was; a workflow note trigger's run log keeps the body it captured until the retention sweep reaps old runs. The agent-write log entries for the note are removed when the note is deleted. No delete control in the app clears those yet, so copy anything you want to keep out of .trash before the window closes. The sweep only ever touches regular files directly inside .trash (never a subdirectory, never a live note). The sweep runs for every folder the Vault has ever used, including folders you have since switched away from, and it keeps running while the Vault is turned off. If another program (for example Obsidian with its "Move to Obsidian trash" option) keeps its own .trash folder in the same place, files it put there are cleared too once they are past that same window (never less than 30 days) from their last edit. Operator kill switch: AMC_DISABLE_KMS_TRASH_PURGE=1.
  • A rename or move done outside the app keeps the note. Rename or move a note in Explorer, Obsidian or a sync tool while Omniscio runs and the Vault recognises it by its content: the note keeps its version history, bookmark, project pins, hidden flag and open tab. A removal waits up to 2 seconds for its matching new file. A note deleted outside the app, or missing when the Vault starts, is remembered for 30 days in the app database, so if the same file comes back at the same path (an undo, a sync tool re-creating it) its history and extras come back too. A file that comes back at the same path with different text within about ten minutes gets the history but not the hidden flag; one that comes back later with different text is a new note. A copy with the same text at a NEW path only counts as the old note within those ten minutes, so a new note made later from the same template starts clean. Permanently deleting a note in the app also clears this record.
  • Bookmarks, pins and hidden notes travel with the folder. The Vault keeps a small hidden file, .kms/extras.json, inside your vault folder listing which notes are bookmarked, pinned to a project, or hidden. It is updated every few minutes and never slows down or blocks a save. When another computer opens the same folder (a copy, or a synced folder) for the first time, it picks those up once. Version history is not in the file and stays on each computer. Obsidian and the Vault itself ignore the .kms folder. Two identical notes are never confused for each other. Rules: an-outside-rename-keeps-the-note in the watcher contract and an-outside-rename-keeps-the-history in the version-history contract.
  • External edits don't clobber in-progress typing. The watcher's kms:note-changed push triggers a re-read of the active tab only when the local dirty bit is false. If the user is mid-edit, the external change is recorded in the DB but the editor body stays untouched AND that note's autosave is frozen: no write goes out, the typed text stays in memory with the dirty bit set, and a warning toast offers Keep my version / Load the outside version. Nothing is written until the user chooses — including by the next keystroke, which is what used to make the conflict a silent overwrite. Pinned by the KMS self-write echo contract I5. See also How to use it, step 11.
  • Omniscio's own saves don't masquerade as "another window". The vault watcher fires kms:note-changed for every on-disk .md change — including Omniscio's own autosave / summary / image writes. Main fingerprints the bytes of each in-app write (/src/main/services/kms/self-write-tracker.ts); the watcher's re-index of an echo whose on-disk bytes still match that fingerprint refreshes tags/links/title but does NOT advance the note's optimistic-concurrency version token (updated_at) — which otherwise produced a false "This note changed in another window" conflict. Because it matches on CONTENT, it recognizes EVERY echo of a rapid autosave burst (fast typing, or a note open in the KMS pop-out as well as the main window), not just the first. A genuine external / second-window / mobile edit (different bytes) still bumps the token, so real conflicts are still detected. Invariants in kms-self-write-echo-contract.md.
  • 5 MB body cap. A note bigger than 5 MB opens in the editor as a truncated copy that ends with a "note truncated" line, and the Vault refuses to save it back ("This note is too large to edit here") — so the file on disk is never replaced by the head. Open a note that big in another editor to change it. A file already over 25 MB when the Vault scans it is never indexed and never appears; a note that grows past 25 MB after it was indexed keeps its last indexed copy and stays listed.
  • 1000-link cap per note prevents pathological notes from exploding the nothari_links index (unchanged from Phase 1).
  • No LLM spend in Phase 2 — no embedding model loads, no Haiku calls, no MCP server registration. Q5 carve-out (log every LLM call when added) only applies once a future phase wires an LLM caller.

The vault itself, the editor, appearance and search, images and links and AI, windows and sharing each have their own page. Importing a whole existing vault has its own page, KMS Obsidian Import Wizard.

Last verified 2026-11-13