Assets

Assets are images, documents, and other files stored with your workspace. Notes address them through the logical ../assets/ namespace. In a cloud workspace, the filename and bytes are encrypted on your device before upload; the server stores opaque names and encrypted data, not a plaintext assets/ directory.

Opening the Assets Filer

Open Assets from the image icon in the toolbar or run Open Assets Manager from the command palette. The command has no default shortcut; you can assign one in Settings → Shortcuts.

The filer is a floating, non-modal panel. The editor behind it stays visible and usable, so you can keep the filer open while writing.

• Drag the header to move the floating panel.

• Choose Dock right to park it as a full-height right-hand pane. Choose Float panel to detach it again.

• Use the close X to dismiss it. Clicking outside and pressing Escape do not close the panel.

• Escape backs out of the top-most filer state instead: Select mode, the details drawer, the folder-tree drawer, then a normal selection.

While floating, drag the grip in the panel's bottom-right corner, or any of its edges, to resize it. The size you leave it at is remembered and restored the next time you open the filer, including across sessions. (Docked mode tracks the window's full height instead and is not resized this way.)

Its contents reflow from the panel's width: the Details column becomes a bottom drawer, then the folder tree becomes an overlay drawer, once the panel gets narrow enough. The chevron tabs on the tree/content and content/details seams hide or restore those panes.

Browsing Files and Folders

The folder tree shows the complete Assets hierarchy. Select Assets at its root, choose a tree row, or use the breadcrumb above the file area to navigate. In the file area, folders appear before files. Double-click a folder tile to open it.

Use the header controls to switch between thumbnails and a compact list, filter to images or other files, and adjust thumbnail size when the panel is wide enough to show that control.

Creating and Changing Folders

Choose New folder in the header, or right-click empty space and choose New folder. Type the name and press Enter.

Folders can be renamed, moved, downloaded as ZIP files, or deleted from their context menus. You can also create a nested folder with New folder inside. Folder names are POSIX-style relative path segments; the filer prevents empty, . / .., reserved, and overlong paths.

Details and Preview

The Details pane always explains the current context:

• One file — preview, kind, size, modified time, folder, copyable workspace path, and file actions. For an image, choose Enlarge for the lightbox; use the previous/next controls or arrow keys to move through images in the folder.

• Several selected items — selection count, total file size, thumbnail fan, and batch actions.

• Nothing selected — current-folder path, file/subfolder counts, total size, and a selection hint.

Clicking an item only updates Details. It never opens a file unexpectedly. Images can be inserted into the active note with Insert into note.

Converting Text Assets to Notes

Markdown and plain-text assets (.md, .mdx, and .txt) offer two actions in Details:

• Copy as note N creates the next free numbered note and keeps the asset.

• Move as note N creates that note and removes the source asset after the note write succeeds.

N is calculated from the current Inbox, so the next empty slot advances after each conversion. Binary and non-text assets never show these actions.

Selecting More Than One Item

Desktop pointer users can drag a marquee from empty space, use Shift for a range, or use Cmd / Ctrl to toggle items. These are accelerators; every selection workflow is also available on touch:

1. Choose Select in the header.

2. Tap file and folder checkboxes to toggle them.

3. Use Select all, Clear, or Done in the selection bar.

Checkboxes also appear on hover and stay visible on touch-only devices. A solid accent edge means selected; a dashed accent edge means keyboard focus. A selected item keeps the solid edge when focused.

Context Menus

Right-click with a mouse or long-press for about half a second on touch. Moving your finger before the long-press completes cancels it.

• File or image — open/details, preview or insert for images, download, rename, move, copy a Markdown reference, and delete. Desktop-local assets can additionally open in the default app or copy their absolute path.

• Folder — open, create a nested folder, rename, move, download as ZIP, and delete.

• Selection — download one ZIP, download the selected files separately, move, or delete the selection.

• Empty space — new folder, upload, select all, refresh, and view mode.

Context menus are temporary surfaces. Escape closes only the menu and leaves the filer open.

Uploading Assets

Choose Upload in the filer header or drag files into the current folder. Uploads run as a batch with per-file progress and failure reporting. The target is the folder shown in the breadcrumb.

You can also add files from the editor:

• Drag or paste an image to save it and insert ![](../assets/filename.png).

• Use Attach file… for images and other file types; non-images use normal Markdown link syntax.

Every entry point enforces the same 25 MiB plaintext limit per file. If a name already exists, the new file is deduplicated (report.pdf, report-1.pdf, report-2.pdf, …).

The canonical image set is png, jpg, jpeg, gif, webp, svg, bmp, ico, and avif. TIFF files can still be stored, but the backend classifies them as generic files rather than thumbnail images.

Downloading Assets

Choose Download for one file. For a multi-selection, either download the selected files separately or create one ZIP. A folder ZIP keeps nested paths and explicit empty folders. Native multi-file downloads never overwrite files that already exist in the chosen folder; conflicting items are left untouched and reported so you can choose another destination.

ZIP creation happens on your device because asset contents are end-to-end encrypted. The desktop app streams archive chunks to a native save destination, keeping memory bounded. The web fallback builds a browser download and refuses an archive whose uncompressed estimate exceeds 500 MiB. Separate web downloads may produce more than one browser download prompt.

Storage Usage and Quota

Account-wide storage usage appears at the bottom of the folder tree. When the tree is hidden or becomes an overlay drawer, a compact strip takes over at the bottom of the panel, including while the filer is docked.

Finite plans show the tier, used storage, quota, and a progress gauge. The gauge changes to a warning color at 80% and a danger color at 100%. Developer accounts show unlimited storage without a quota gauge. Choose Upgrade storage to add capacity through the app's subscription flow.

If existing usage is above a finite quota, the filer displays Storage is over quota — uploads and new embeds are paused; delete files or upgrade. This is a soft lock: browsing, previewing, downloading, renaming, moving, and deleting existing assets remain available so you can recover space.

Local coding agents

The official MCP integration exposes exactly five narrow asset tools:

Use a workspace-bound PAT with assets:read and assets:write. Asset keys are derived as non-extractable keys in the local MCP process; the Worker receives only opaque encrypted path tokens and encrypted envelopes. Binary bytes and base64 never appear in model-visible MCP text or structured results.

Uploads accept only regular, non-symlink local files and enforce the same 25 MiB plaintext limit as the filer. Check get_asset_usage before material uploads; quota/soft lock can reject creation. Downloads exclusively create a new local path and never overwrite an existing destination.

After a committed agent upload or folder creation, an open filer receives only the content-free { type: "assets-changed" } wake-up and refetches its listing and usage. The event does not reveal which asset changed and is not an ordered or replayable asset feed.

Asset References in Markdown

Use standard Markdown with a path relative to the note directory:

![screenshot](../assets/design/screenshots/home.png)
[brief](../assets/client/brief.pdf)

The preview resolves ../assets/ references through the asset bridge and decrypts the bytes on the client. External http:// and https:// URLs pass through unchanged.

Moving a document or renaming/moving an asset does not update these references automatically. Review affected Markdown manually after an interactive filer operation.

Backend Bridge Contract

Renderer code uses one path-aware bridge.assets contract on the Tauri, mock, REST, and web-workspace adapters:

The plaintext contract is intentional: UI and Markdown code never handle wire tokens or encryption keys. The shared workspace core performs cloud crypto, while the sync server stores only deterministic opaque name tokens and encrypted bytes.