Two additions from Luca's published essays on note-taking:
- 'Knowledge has a purpose' section: notes exist to get things done,
not for abstract future use. Without purpose, the system collapses.
- Evergreen notes concept: atomic, timeless, reusable units of thought.
The most valuable layer of a mature vault.
- Organize phase clarified: weekly cadence, deleting >50% of captures
is normal and healthy, not a failure.
Complete rewrite structured around three pillars:
1. The problem (architectural + methodological)
2. The method (ontology, capture/organize, convention over configuration)
3. The foundation (local files, Git, AI-native architecture)
Key improvement: the document now explains *why* tool and method together
is the differentiating insight — not just a list of features and principles.
Includes the three-stage product trajectory and updated design principles.
Current state section condensed; full roadmap moved to ROADMAP.md.
VISION.md:
- New section 'The two-phase knowledge workflow: capture and organize'
- Explains capture (fast, frictionless, everywhere) vs organize (deliberate,
periodic) as fundamentally different activities
- Defines Inbox: a smart filter showing notes with no outgoing relationships
- Inbox Zero as the goal; connecting a note removes it automatically
- Replaces 'All Notes' as the primary navigation section
ROADMAP.md:
- New strategic direction #4: Inbox and capture pipeline
- Covers inbox UI, capture integrations (Chrome ext, iPhone, Readwise, voice)
- Add 'Product trajectory' section: 3 stages from personal PKM → indie
knowledge workers → small teams, with rationale for why the same
foundational model (local files + Git) enables all three stages
- Note that the knowledge ontology (Projects/Responsibilities/Procedures/
Notes/People/Events) maps equally well to personal and organizational use
- Describe workspace feature as the seed for future team access control
- Update design principles: add convention over configuration, semantic
properties, filesystem as source of truth; expand AI-native principle
to include AI-readability via shared conventions
Remove hardcoded /Users/luca/Laputa/ paths from resolveNewNote,
resolveNewType, and resolveDailyNote. All three now accept a vaultPath
parameter and build paths relative to the active vault. Added vaultPath
to NoteActionsConfig so the hook passes it through to all callers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- ARCHITECTURE.md: new Design Principles section covering filesystem as
source of truth, convention over configuration, no hardcoded exceptions,
AI-first knowledge graph, and three-representation model
- ABSTRACTIONS.md: design philosophy intro + semantic field names table
documenting all conventional frontmatter fields and their UI behavior
Convention over configuration principle explicitly noted as serving
AI-readability: shared conventions make vaults navigable by AI agents
without bespoke per-vault instructions.
contextRef (useRef) was initialized at mount time and synced via useEffect,
which runs after paint. If contextPrompt was empty at mount (tab content
not yet loaded), sendMessage could read stale/empty context during the
window between paint and effect. Removing the ref and reading contextPrompt
directly in the useCallback closure eliminates the race entirely.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When viewing a Type note (e.g. "Project"), the Properties panel now shows
an Instances section listing all notes of that type, sorted by modified_at
descending. Trashed instances are excluded, archived instances are dimmed.
Display capped at 50 with count badge for large collections.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The frontmatter field for entity type is now 'type:' (not 'Is A:').
The Rust parser accepts both via serde alias, but all documentation,
examples, and new code should use 'type:'.
Updated: ABSTRACTIONS.md, ARCHITECTURE.md, PROJECT-SPEC.md, GETTING-STARTED.md
Three root causes identified and fixed:
1. JS semantics bug: `activeNoteContent ?? allContent[path]` used nullish
coalescing (`??`) which does NOT fall through on empty string ''. When
handleEditorChange temporarily overwrites tab.content with frontmatter-
only content during async content swaps, activeNoteContent becomes ''
and the fallback to allContent never triggers. Fix: change `??` to `||`.
2. Defence-in-depth: when body is still empty after fallback (Tauri mode
where allContent is {}), but wordCount > 0, the body field now includes
an explicit get_note instruction instead of being empty. This is more
reliable than the preamble instruction that Claude may skip.
3. Rust strip_frontmatter used `rest.find("---")` which matches `---`
anywhere in text (including inside frontmatter values like `title:
foo---bar`). Fixed to use `rest.find("\n---")` for line-boundary
matching. This ensures accurate wordCount for the fallback heuristic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Flush unsaved editor content to disk before any trash or archive
operation (both single-note and bulk) so body edits are never silently
dropped when only frontmatter is updated.
- Add flushEditorContent utility that checks pending content ref, then
falls back to comparing tab content with last-saved state
- Add onBeforeAction callback to useEntryActions, called before
handleTrashNote and handleArchiveNote
- Wire flushBeforeAction in App.tsx using refs for stable closures
- Add error handling in useBulkActions so one failed save doesn't
block remaining notes
- Extract findOrCreateType helper to reduce useEntryActions complexity
- Export persistContent from useSaveNote for reuse
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The frontend writes 'archived: true' (lowercase) via handleUpdateFrontmatter,
but the Rust parser only recognized 'Archived' (titlecase). This caused all
notes archived from within Laputa to be read back as not archived — they
continued appearing in the sidebar and note list after restart.
Fix: add alias = "archived" to the serde attribute, matching the pattern
already used for 'trashed'/'Trashed'.
Regression tests added for both lowercase and titlecase variants.
The body field in buildContextSnapshot was passing the full raw file
content (including YAML frontmatter delimiters) instead of just the
body text. When handleEditorChange reconstructed tab content with empty
blocksToMarkdownLossy output, the body became frontmatter-only — causing
the AI to report "has frontmatter but no body content."
Three changes:
1. Strip frontmatter from body using splitFrontmatter before setting the
body field (frontmatter is already a separate parsed field)
2. Add wordCount to the context snapshot so the AI can detect when body
is stale vs genuinely empty
3. Instruct the AI to call get_note MCP tool when body is empty but
wordCount > 0, providing a safety net for any content staleness
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- .claude-pid: Claude Code runtime PID file, not repo content
- .laputa-index.json: generated search index, must not be committed
- *.key / *.key.pub: blanket guard against future signing key commits
Previous keypair was accidentally committed to git history.
New keypair generated, GitHub Secrets updated, pubkey rotated in tauri.conf.json.
Old key is now invalid for signing — any releases must use the new key.
handleContentChange now syncs content to tab state on every editor
change (not just on Cmd+S save). This ensures the AI panel's context
snapshot always contains the current editor body, fixing the bug where
the AI reported empty note bodies for unsaved edits.
Root cause: pendingContentRef buffered content for save but never
updated notes.tabs[].content, so activeTab?.content (used by the AI
context builder) always reflected the last-saved disk content.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Root cause: CSS zoom on document.documentElement caused stale CodeMirror
measurements. Two issues:
1. Race condition: zoom was applied in useEffect (parent), but CodeMirror
was created in useEffect (child) — child effects run first, so CM
measured at zoom=1 before zoom was actually applied.
2. No re-measure on zoom change: CSS zoom changes don't trigger
ResizeObserver on descendant elements, so CodeMirror never updated
its cached scaleX/scaleY, line heights, or character widths.
Fix:
- Apply zoom synchronously during useState init (before child effects)
- Dispatch 'laputa-zoom-change' event when zoom changes
- Listen for this event in useCodeMirror and call view.requestMeasure()
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
In Tauri mode, allContent is {} (empty) until a note is explicitly
saved. The previous mergeTabContent fix enriched allContent with tab
content, but the indirection was fragile. This fix passes the active
tab's content directly to buildContextSnapshot as activeNoteContent,
which takes priority over allContent[path]. This ensures the AI always
receives the note body regardless of allContent state.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Each CLI invocation is a fresh subprocess — --resume depends on session
persistence that doesn't reliably work with -p mode. Switch to prompt-
embedded history: prior exchanges are formatted into each request using
formatMessageWithHistory + trimHistory (already existed as dead code).
- Remove sessionIdRef and --resume session tracking
- Always send system prompt (each request is stateless)
- Split sendMessage into doSend(text, history) to handle retry correctly
- Retry now passes correct history (excludes the retried exchange)
- Tests verify history accumulation, clear, retry, and system prompt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
allContent is empty ({}) in Tauri mode because loadVaultData never
populates it — note content only enters allContent on explicit save.
mergeTabContent() enriches allContent with open tab content so the AI
context snapshot always includes the active note's body.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
detectFileOperation silently failed when tool input was undefined (timing
issues with NDJSON event ordering). Added onVaultChanged callback as fallback:
when Write/Edit/Bash tools complete but specific file can't be determined,
vault.reloadVault() is triggered. Also added safety net in onDone handler.
Threaded onVaultChanged through AiPanel → EditorRightPanel → Editor → App.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Root cause: buildContextSnapshot (the system prompt used when a note is
active — the common case) did NOT instruct the AI to use [[wikilinks]].
Only buildAgentSystemPrompt (the fallback when no context) had it.
So the AI almost never produced clickable wikilinks.
Fix: Add the [[Note Title]] wikilink instruction to
buildContextSnapshot's preamble.
The click handler chain was already correct (verified with new
integration tests): MarkdownContent → AiMessage → AiPanel →
notes.handleNavigateWikilink → findWikilinkTarget → handleSelectNote.
Tests added:
- Unit: buildContextSnapshot includes wikilink instruction
- Integration: clicking wikilinks in AiPanel calls onOpenNote
- Playwright: wikilink renders, click opens note in tab
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The previous approach embedded conversation history as formatted text
in the prompt (<conversation_history> tags). The claude CLI's -p flag
treats this as a single user turn, losing turn boundaries — so the
model had no real multi-turn context.
Switch to using --resume with the session_id returned by the CLI's
init event. This lets the CLI manage conversation state natively:
- First message starts a new session (with system prompt)
- Subsequent messages resume via --resume (no system prompt needed)
- Clear and retry reset the session_id for a fresh start
Extract makeStreamCallbacks() to keep useAIChat complexity below
CodeScene threshold.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "Repair Vault" to command palette (Cmd+K → "Repair Vault")
- Add "Repair Vault" to macOS Vault menu bar
- Wire repair_vault Tauri command through App → useAppCommands → registry
- Add menu event handler for vault-repair
- Update MCP get_vault_context to include configFiles.agents content
- Add repair_vault mock handler for browser testing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The command was gated on `mcpStatus !== 'checking'` which meant it was
hidden during the initial async status check. Changed enabled to always
be true so users can find and run the command immediately on app start.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The "Install MCP Server" command was only enabled when status was
"not_installed", preventing users from re-registering when MCP got
removed or broken. Now the command is always available:
- Shows "Install MCP Server" when not installed
- Shows "Restore MCP Server" when already installed
- Added restore/fix/repair keywords for discoverability
- Context-aware toast: "installed" vs "restored"
- Menu bar label updated to "Restore MCP Server"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Structural changes (sidebar visibility, label, order, template, icon/color)
now auto-create missing Type entries and call onFrontmatterPersisted to
refresh git status, so changes appear in git diff without user intervention.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Previously called 'qmd update' and 'qmd embed' without arguments, which
updated all global qmd collections. If any other collection had a broken
path, the entire indexing would fail.
Now passes the vault name explicitly:
qmd update <vault_name>
qmd embed -c <vault_name>
This makes reindex independent of other qmd collections on the system.
AiPanel.handleNavigateWikilink was double-resolving: it resolved the
wikilink target to an entry path, then passed the path to onOpenNote
which is notes.handleNavigateWikilink (expects a title-based target).
The path didn't match any entry's title, so navigation silently failed.
Fix: pass the wikilink target string directly to onOpenNote, letting
the parent's handleNavigateWikilink do the resolution.
Also enhanced the Playwright smoke test to verify click → tab opens.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The ai-notes-visibility-fix smoke test imports 'ws' (WebSocketServer)
but it wasn't listed as a dev dependency.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Updated all three docs to reflect significant features added since they were last written:
- AI agent panel (Claude CLI subprocess with tool execution + NDJSON streaming)
- Vault cache system (git-based incremental caching in cache.rs)
- Theme system (vault-based themes, useThemeManager, ThemePropertyEditor)
- Search & indexing (qmd integration, keyword/semantic/hybrid modes)
- Pulse view (git activity feed with pagination)
- GitHub OAuth (device flow, vault clone/create)
- Vault management (multi-vault, vault config, onboarding, WelcomeScreen)
- Raw editor mode (CodeMirror 6 alternative)
- Command palette (Cmd+K registry)
- Auto-sync & conflict resolution
Also added mandatory docs-update rule to CLAUDE.md: docs/ files must be
updated in the same commit as significant feature changes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Root causes:
- toolInputMapRef in useAiAgent was overwritten by tool_progress events
(which arrive with input=undefined AFTER the assistant message set
the full input), causing detectFileOperation to receive undefined
and skip file creation detection entirely.
- MCP open_note only broadcast open_tab without vault_changed, so
the note list didn't refresh when Claude Code called open_note.
- detectFileOperation only handled Write/Edit but not Bash commands
that create .md files via redirects.
Fixes:
- Preserve accumulated input in toolInputMapRef (input ?? prev?.input)
- MCP open_note now broadcasts vault_changed before open_tab
- detectFileOperation now detects Bash redirect patterns (>, >>, tee)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The AI chat was using both --resume (CLI session resumption) AND formatted
conversation history in the prompt simultaneously. This dual-context approach
confused the model — it saw the conversation twice (from session + from prompt
markup), leading to "I don't have context" responses on follow-ups.
Fix: remove --resume entirely from chat mode. Each CLI call is now independent,
with full conversation history formatted into the prompt via
<conversation_history> markup. trimHistory handles graceful truncation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add highlight_editor and refresh_vault tools to the MCP stdio server
so Claude Code can visually highlight UI elements and trigger vault
rescans. Also fix outdated test.js imports after the ai-agent-full-shell
simplification removed write operations from vault.js.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update mock agent response to include [[wikilinks]] for testing.
Add smoke test verifying wikilinks render as clickable elements
with correct text, attributes, and styling.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- System prompts instruct AI to use [[Note Title]] wikilink syntax
- preprocessWikilinks converts [[Target]] to markdown links
- Custom urlTransform allows wikilink:// scheme through sanitizer
- Click handler resolves target via findEntryByTarget and opens note
- Styled as colored chips matching primary accent
- Works in both AiPanel (agent) and AIChatPanel (legacy chat)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "Reindex Vault" command to command palette and menu bar
- Show "Indexed Xm ago" in status bar when idle, clickable to reindex
- After git pull with updates, auto-trigger incremental reindex
- Add lastIndexedTime state to useIndexing, populated from backend metadata
- Add triggerFullReindex to useIndexing (retryIndexing is now an alias)
- Add onSyncUpdated callback to useAutoSync
- Extract formatIndexedElapsed to utils/indexingHelpers.ts
- Tests: 20 new unit tests across 5 files, 2 Playwright smoke tests
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
