FrilVault

FrilVault is a local-first developer knowledge layer that attaches persistent notes to source code without modifying the source file.

Features

• Add notes to source lines and symbols
• View notes directly inside VS Code with expandable CodeLens viewers above code anchors
• Edit and delete notes from the editor
• Navigate between code and notes
• Search notes across the current workspace
• Store all note data locally as JSON
• Keep note data in the selected Local or Shared vault

Environment Manager

The FrilVault Environments view uses the native VS Code Tree View, Quick Pick, and Input Box APIs to manage encrypted environment profiles through the existing flvt CLI. It shows profile readiness and manifest metadata without displaying environment values. Secret values are entered through a masked Input Box and sent to the CLI over stdin; they are not placed in command arguments or extension logs.

The displayed scope follows the Vault mode: Local is shown as this-machine and Shared as project-shared. This describes profile availability; values are injected only into a child started with Run with Environment Profile.

Project dotenv files are listed as discovered sources only. They are never read or imported automatically. Select Import Dotenv File to explicitly copy the parsed values into an encrypted profile; the source file is preserved.

Run with Environment Profile launches the selected child through flvt env run, so the environment is injected only into that child process and the extension does not decrypt or persist values itself.

Note Viewer

Notes View

The FrilVault Notes tree keeps the workspace overview visible while you move between editors. It groups files by folder and shows note counts. When the active file has notes, an additional Active file section shows its line, resolved symbol, and unresolved symbol groups. The section is omitted when the active file has no notes. An empty workspace shows one actionable empty state.

The overview is reused during presentation-only redraws and same-context background refreshes. A loading row is shown for the initial overview load; revalidation keeps the usable snapshot visible. Switching workspace or Vault does not display the previous context's notes. File and folder collapse state is retained across unchanged refreshes.

CodeLens and Markdown Hover

FrilVault uses CodeLens controls and a line decoration to present notes at code anchors without modifying source files. Each anchored group has compact +, disclosure, tag, and − controls. The disclosure expands a short preview made from the first non-empty logical line of each note at that anchor; it does not flatten the rest of the Markdown body. The preview is shortened when needed. The default state is expanded and can be changed with frilvault.noteViewer.defaultState. Explicit disclosure choices are retained per note and document.

+ adds a note or opens the existing note for that anchor. − asks which note to delete when several notes share the anchor, then requires confirmation. Line and Symbol anchors remain distinct even when they resolve to the same displayed line. The source document is never edited by these controls.

Hovering over an anchored line or a resolved Symbol declaration name shows the full note Markdown and tags. Markdown paragraphs, lists, links, and fenced code remain readable in the Hover. Unresolved Symbols are not assigned a guessed CodeLens location; they remain available in the Notes view and other note navigation paths.

Editing and Recovery

The note editor opens beside the source editor and autosaves after the delay configured by frilvault.inlineEditor.autoSaveDebounceMs (900 ms by default). The editor's Close action flushes pending changes before it closes; if saving fails, the editor stays open with an error. Changes received by the extension are also copied to VS Code workspace state so they can be recovered if the webview is closed while a save is in flight. On reopen, a recovered draft is restored when its saved base is still current; if the persisted note has changed, FrilVault presents a conflict instead of silently overwriting it. Because webview input is asynchronous, a keystroke not yet delivered and recorded by the extension is not guaranteed after a forced VS Code shutdown.

Viewer Differences

Configuration

Note: The legacy after-line inline preview settings (frilvault.inlineNotes.* and frilvault.inlineLineNotes.*) were removed. The plain-text preview helpers remain only where they are reused by supported hover/sidebar presentation paths.

Commands

The viewer also exposes frilvault.noteViewer.toggle and frilvault.noteViewer.actions through its CodeLens rows; these commands receive stable note IDs from the provider.

Add / Edit Note shortcut

Use FrilVault: Add / Edit Note from the Command Palette or the existing + controls. The default shortcut is ⌘K, ⌘N on macOS and Ctrl+K, Ctrl+N on Windows/Linux (press the two combinations in sequence). Remap frilvault.addOrEditNote in VS Code Keyboard Shortcuts.

The shortcut runs only when a trusted, enabled workspace's source editor has text focus. It excludes files inside the selected Vault, terminals, search inputs, note inputs, and unrelated webviews. If no eligible source file or initialized Vault is available, the command explains the required action; invoking it never initializes storage.

On a code line with a symbol, choose Line or Symbol using the keyboard. Blank lines and files without a symbol provider use Line directly. Escape cancels without creating a note. A Line identity is the existing exact one-based line and column; a Symbol identity is name, kind and signature, with its line hint used only for location. These two anchor kinds can have notes on the same displayed line. Repeating the action for an existing identity edits its note. Existing duplicates remain available through a separate, stable chooser showing previews and note IDs. A specific note's Edit control opens that exact note directly. The original workspace, Vault and anchor remain the save target when focus or configuration changes.

The current note editor is reused for the Edit action. Compatibility IDs frilvault.addNote and frilvault.editNote dispatch through the same action.

The shortcut uses VS Code's familiar K chord prefix and avoids an Alt-based binding that can interfere with text entry on some layouts. The default Git extension also uses K/N for Unstage Selected Ranges in git documents; this binding is scoped to file documents. User bindings and other extensions can still conflict. See VS Code's default shortcuts and Keyboard Shortcuts editor when choosing a remapping.

Search syntax

Search Notes searches while you type and keeps the source editor layout unchanged. Plain text searches note content and symbol names. Add filters to narrow the same query:

parser cache
tag:todo
file:src/parser.rs
symbol:parse_config
tag:todo parser
file:src/core tag:architecture

Select a result to open the source file and reveal its line or symbol anchor. Results are labeled as FrilVault notes and unresolved symbol anchors are shown as metadata rather than source diagnostics.

Requirements

FrilVault ships with a bundled flvt CLI inside each platform-specific VSIX.

Supported packaged targets:

• darwin-arm64
• darwin-x64
• linux-x64
• win32-x64

frilvault.cliPath is now an advanced override for custom builds.

When frilvault.vaultPath is empty, the extension asks Core through flvt for the selected vault. A new Local vault in a Git checkout lives under that checkout's Git metadata directory; a new Shared vault uses project-root .vault/. Non-Git Local projects keep project-root .vault/. Existing workspace-root .vault/ data stays in place with its stored mode, and if it coexists with another valid vault the extension asks you to choose a path.

Local/Shared selects the storage policy. frilvault.vaultPath or CLI --vault PATH selects only the storage location; an explicit path does not infer a mode. The extension passes it to each CLI operation. Opening a project, activating the extension, and refreshing views do not create a vault. Select Enable and then an initialization option to create one.

Install

You can install FrilVault in either of these ways:

1. Visual Studio Marketplace
2. GitHub Release VSIX

Marketplace users do not choose a platform manually. The Marketplace serves the matching package for the current operating system and CPU architecture.

If you install from GitHub Release, download the matching VSIX and use Extensions: Install from VSIX... in VS Code.

Release And Publish

Release automation is split into two stages:

1. release.yml builds platform-specific VSIX files and attaches them to a published GitHub Release.
2. publish.yml is run manually when you want to publish those VSIX files to the Visual Studio Marketplace.

publish.yml uses VSCE_PAT and publishes the existing Release assets to the single Marketplace listing.

Getting Started

1. Install the FrilVault extension.
2. Open a project in VS Code.
3. Open FrilVault Notes in the Explorer and select Enable.
4. Choose Initialize Local Vault or Initialize Shared Vault when prompted.
5. Choose FrilVault: Add / Edit Note from the Command Palette, use its keyboard shortcut, or select the + CodeLens control at a source anchor.
6. Enter a note in the inline editor.

Commands

Data Storage

FrilVault stores project data locally under the selected vault. A new Local vault in a Git checkout is stored in that checkout's Git metadata at frilvault/vaults/<workspace-key>/. The checkout root uses root; each other workspace path gets its own collision-free encoded directory. A new Shared vault is stored in the project-root .vault/. Non-Git Local projects keep the .vault/ layout. An existing project-root .vault/ remains in place and is never moved based on its mode. An explicit path can select an external vault for either mode.

The Shared vault's project-root layout is:

.vault/

No cloud account is required.

Known Limitations

• FrilVault targets one workspace root at a time, so multi-root workspace support is limited
• CodeLens previews flatten whitespace and shorten long content; hover and Open Note provide the complete content
• This is an early preview release

Roadmap

• Improve multi-root workspace behavior
• Expand editor UX for symbol-anchored notes

Privacy

FrilVault does not upload source code or note content to an external service.

Issues

Report bugs and feature requests through the GitHub issue tracker:

https://github.com/FrilLab/frilvault/issues

License

MIT