C2 · Authoring & knowledge UX

Capabilities

System view — simplified

C2 is the app users actually touch: a markdown editor, a filterable note list with sidebar navigation, an inspector for metadata, and a kanban board — all client chrome around a thin server-action layer. Standalone (with AI, SaaS, and agents turned off) it is a complete offline Obsidian-style workspace: browse a vault by bucket/type/folder/tag, edit notes with versioned autosave and conflict snapshots, capture quickly with Cmd+Shift+N, keep a daily note, and drag projects across a board. Its only hard dependency is the C1 storage interface; AI menu items degrade to error toasts if /api/ai/* is unreachable. Every filter, search, and list state lives in the URL, so the server re-renders the tree — there is no client-side state store for navigation.

System view — detailed

Data flow — simplified

The autosave loop is the load-bearing runtime path of the whole platform: markdown comes out of storage, becomes BlockNote blocks, and every keystroke re-serialises it back to markdown, restarting a 1500 ms debounce timer. When the timer fires, saveNoteAction writes through the storage abstraction with an optimistic-concurrency token; a raced write is never rejected — the previous body is parked as a conflict-snapshot version and the editor shows a review banner. The save also revalidates the RSC tree and schedules a semantic re-embed without blocking the user.

Data flow — detailed

Open-and-edit-note autosave loop, including the markdown round-trip, both debounce values, the OCC divergence, and the local-vs-SaaS post-save divergence:

Quick capture → hard navigation (why the app deliberately abandons soft routing here):

Works separately / works together

Standalone

With every other cluster disabled except C1 storage, C2 is a complete offline markdown workspace: vault picker and sample-vault onboarding, sidebar navigation over buckets/types/folders/tags, URL-driven filtering and 250 ms-debounced search, the full BlockNote editing loop with versioned autosave and conflict snapshots, the inspector, quick capture, daily notes, the projects kanban, rebindable keybindings, and FOUC-free theming. AI features degrade gracefully (fetch failures surface as toasts); SaaS-only chrome (realtime watcher, share dialog, hamburger nav) simply never mounts.

Composed

• → C1 storage: every UI mutation goes through getStorage() (lib/storage) so LocalAdapter and SupabaseAdapter serve identical components — ADR-0004, called out at app/(saas)/(app)/w/[workspace]/n/[...path]/page.tsx:25-30. The /api/events SSE feed (FS watcher via lib/watch/events-bus) drives VaultEventsBridge refreshes.
• → C3 semantic search: saveNoteAction fire-and-forgets scheduleEmbed from lib/ai/auto-embed-queue (app/_actions/notes.ts:96-105); deleteNoteAction cancels pending embeds via cancelEmbed (notes.ts:225-245).
• → C4 AI platform: slash-menu items POST /api/ai/draft and /api/ai/summarize; the transform menu POSTs /api/ai/transform (blocknote-editor.tsx:371-404, ai-transform-menu.tsx:64-104).
• → C6 versioning: the History card links Compare to /v/diff/<path>?a&b (local) or /w/<slug>/diff (SaaS, parameterised diffRouteBase, properties-panel.tsx:56); conflict snapshots created by the storage adapter surface in this card via the hash deep-link.
• ↔ C7 SaaS collaboration: SaaS note page adds RealtimeNoteWatcher (Supabase postgres_changes) and ShareLinkDialog (mounted when the editor toolbar receives workspaceId, note-editor.tsx:27-31); both note pages mount CommentsThread with section anchors from lib/storage/helpers/section-diff.
• → C5 agent surface: SetupExternalToolsDialog writes MCP configs (~/.claude/mcp.json, ~/.cursor/mcp.json, ~/.codex/config.toml, ~/.gemini/settings.json, ~/.openclaw/openclaw.json) pointing at bin/eli-mcp.mjs; storage.todayNote() is shared with the MCP daily tool (lib/mcp/tools/daily.ts:54).
• ← C8 capture/templates: clipper drops and template-created notes appear live via the SSE bridge without a manual re-scan.
• ↔ C9 platform ops: /api/cron/trash-prune reuses emptyTrashAction({olderThanDays}) (notes.ts:254-287); project status changes participate in git auto-commit via the standard updateNote path (app/_actions/projects.ts:12-16); e2e disables SSE via ELI_DISABLE_LIVE_EVENTS=1 / window.__ELI_DISABLE_EVENTS__.
• → Export: inspector download hits /api/export/note/[id]; the palette’s “Export vault as zip” hits /api/export/vault.
• → Config: keybinding overrides and the vault registry both live in ~/.eli/config.json via lib/config; the root layout re-reads it on every render in local mode (app/layout.tsx:59-67).

Load-bearing details

• Editor selection is server-side and env-gated: ELI_LEGACY_EDITOR=1 forces the textarea everywhere, ELI_MOBILE_EDITOR=raw gives BlockNote-on-desktop/textarea-on-mobile, default is BlockNote everywhere (components/editor/note-editor-root.tsx:33-35; env.ts:56,72). Env vars never reach the client bundle.
• The markdown round-trip is explicitly lossy by design: tryParseMarkdownToBlocks on load, blocksToMarkdownLossy on save; adversarial parse failures fall back to one paragraph block containing the raw markdown so no body is ever lost (blocknote-editor.tsx:91-102,135).
• Saves are last-writer-wins-with-snapshot, not reject-on-conflict: a stale expectedVersionId still commits, and the previous head’s body is parked as an auto-conflict-snapshot version whose id rides back in SaveState.snapshotVersionId (app/_actions/notes.ts:35-47,76-89; conflict-banner.tsx:7-31).
• Both debounce constants matter: autosave is 1500 ms (SAVE_DEBOUNCE_MS, note-editor.tsx:34, blocknote-editor.tsx:52), list search is 250 ms (note-list-search.tsx:9), SSE-driven refresh is 500 ms (vault-events-bridge.tsx:7).
• Wikilink autocomplete inserts plain text [[Title]] — resolution and backlink extraction happen at save/index time in the storage layer, never in the editor (blocknote-editor.tsx:405-417).
• Editor identity key is `${note.id}:${note.versionId}` so any external version change remounts the editor with fresh content (app/(local)/v/n/[...path]/page.tsx:102; SaaS page :152).
• Palette and NewNoteDialog use window.location.assign instead of router.push because soft navigation races the layout revalidation triggered by revalidatePath('/v','layout') (command-palette.tsx:131-140; new-note-dialog.tsx:55-60).
• Keybinding handler stacks give modal behaviour for free: last-registered handler wins per action, unmount pops the stack, returning false chains downward (components/keybinding-provider.tsx:63-100). The rebind recorder wins over the global provider by listening in the capture phase (keybinding-recorder.tsx:89). mergeKeybindingOverrides silently drops overrides for unknown action ids, so stale ~/.eli/config.json entries can never break the table (lib/keybindings/overrides.ts:19-34).
• Frontmatter is partitioned by underscore prefix: _-prefixed keys are system fields (read-only System card, preserved on property edits, used for _pinned and _child_count); everything else is user-editable and fully replaced by updateFrontmatterAction (lib/storage/helpers/frontmatter.ts:92-102; notes.ts:354-360).
• Trash is soft-delete by default; emptyTrashAction’s olderThanDays uses updatedAt as the trashed-at proxy and powers both the manual button and the daily cron (notes.ts:225-287). The inspector’s delete confirm reveals the local trash location .eli/trash/ (properties-panel.tsx:146-155).
• Mobile tap-target compliance is a single Tailwind selector: [&>button]:max-sm:min-h-11 gives every toolbar button a 44 px minimum below 640 px (note-editor.tsx:216; blocknote-editor.tsx:318); MobileNav rows use h-11 (mobile-nav.tsx:64).
• SaaS self-save suppression is globalThis.__ELI_LOCAL_VERSIONS__ — a Set of version ids capped at 32 with oldest-first eviction, stamped by markVersionAsLocal after each save; the realtime watcher never auto-replaces the buffer, only offers a Refresh toast (realtime/note-watcher.tsx:34-56,92-108).
• Theme boots without FOUC via an inline <head> script that stamps the class before first paint from localStorage key eli-theme (lib/theme/constants.ts:12; theme-script.tsx:18-32); cross-tab sync rides the storage event (theme-provider.tsx:70-78). Browser chrome follows via the viewport themeColor pair #fafafa/#0a0a0a (app/layout.tsx:45-47).
• Design tokens live in app/globals.css (Tailwind v4): dark mode is class-based, @custom-variant dark (&:is(.dark *)) — no prefers-color-scheme media query in CSS, so the ThemeScript/provider .dark class is the single switch (globals.css:5). @theme inline maps shadcn/sidebar/chart oklch variables to utilities; the palette is zero-chroma grayscale except --destructive and dark-mode --sidebar-primary (blue oklch(0.488 0.243 264.376)), and the entire radius scale derives from one --radius: 0.625rem token (sm 0.6x → 4xl 2.6x). cn() in lib/utils.ts is exactly twMerge(clsx(...)).
• Two cross-cutting guards sit in @layer base (globals.css:119-160): body{overflow-x:hidden} is the P6-MOBILE no-horizontal-scroll guard (wide content must opt into its own overflow-x-auto), and a P6-A11Y focus-visible safety net draws a 2px var(--ring) outline on raw interactive elements — the :not([data-slot]) predicate excludes shadcn primitives that already ship their own focus ring, avoiding double indicators.

Gaps and partially wired

• toggle-sidebar (Mod+\) is registered but dead: it appears in the registry, help overlay, and rebind table, but no component ever mounts a handler for it — the working sidebar shortcut is the shadcn built-in Mod+B ad-hoc listener (lib/keybindings/registry.ts:43; components/ui/sidebar.tsx:33,97-110). Verified: toggle-sidebar occurs nowhere outside registry/help/table.
• No chord support: matchAction is single-combo only; the palette’s g t next to “Go to today” is a display-only CommandShortcut label (command-palette.tsx:187; lib/keybindings/registry.ts:70-84).
• BlockNote ignores dark mode: BlockNoteView is pinned to theme="light" regardless of app theme (blocknote-editor.tsx:364); the textarea editor inherits app theming correctly.
• SaaS backlink links are wrong-mode: PropertiesPanel backlink hrefs are hardcoded to the local /v/n/ prefix even when rendered inside /w/<slug>/n/..., so SaaS backlink clicks navigate to a local-mode route (properties-panel.tsx:241); contrast diffRouteBase which IS parameterised (:56).
• SaaS favorites stubbed: the SaaS note page hardcodes favorite state to false pending a user_favorites table (app/(saas)/(app)/w/[workspace]/n/[...path]/page.tsx:88-89,135).
• Keybinding overrides are local-only: the SaaS root layout deliberately skips the ~/.eli/config.json read (“per-user keybindings in saas would be a future profiles-row column”, app/layout.tsx:54-67); /keybindings returns notFound in SaaS (app/(local)/keybindings/page.tsx:21).
• No rebind uniqueness validation: assigning the same combo to two actions is silently resolved by handler precedence, not flagged as an error.
• No SaaS daily note: /v/today is local-only; no /w/<slug>/today route exists.
• Daily-note day boundary is UTC: todayNote() computes the date as new Date().toISOString().slice(0,10) (lib/storage/local/writes.ts:483), so “Today” rolls over at UTC midnight — an evening user in the Americas gets tomorrow’s note.
• No SaaS command palette: the palette mounts in the local vault header; SaaS reaches notes via top-bar links instead.
• Trash age proxy: emptyTrashAction({olderThanDays}) measures against updatedAt rather than a real trashed-at timestamp (notes.ts:254-287), so a note edited just before trashing ages faster than expected.
• Undebounced hook exposed: a public useVaultEvents hook exists alongside the debounced bridge (hooks/use-vault-events.ts:17-40) but nothing else consumes it yet.