The vault

Vaults and files

A vault is a plain folder. That single fact does most of the work in this chapter: because a vault is only files, everything Clew does to it is inspectable, everything it adds is deletable, and every other tool you own — git, grep, Obsidian, a text editor from 1991 — keeps working on the same notes at the same time. What follows is the full account: what Clew writes where, how it shares a vault with other apps, how windows map to vaults, what the file explorer can do, and the two places Clew deliberately goes beyond Obsidian — external edits handled without data loss, and real symbolic-link support.

A vault is a folder

Any folder of .md or .jmd files is a vault; so is an empty folder you intend to fill. Notes are Markdown files, canvases are JSON files, attachments are ordinary images and PDFs sitting wherever you put them. There is no database, no manifest, and no import step — opening a vault means pointing Clew at the folder, nothing more. Subfolders structure the vault however you like, and the explorer shows them as a tree, folders first, then files, each sorted alphabetically (Obsidian's default order). Files and folders whose names begin with a dot are hidden, and a few directories are ignored outright wherever Clew walks the vault: .obsidian, .clew, .git, node_modules, and .trash.

What Clew adds on disk: .clew/

Clew keeps every piece of its own state in a single subfolder of the vault, .clew/, created when the vault is first opened. Everything in it falls into three kinds: caches Clew can rebuild from your notes at any time, small settings files recording choices you made, and history/ — past versions of your notes, kept as a safety net. Your current writing lives only in the vault itself: deleting the whole folder loses no present content, only convenience and that safety net (your window layout, bookmarks, and per-vault settings go back to defaults, and the first re-render after deletion is a little slower while the caches rebuild).

Living with Obsidian

Obsidian compatibility is a hard constraint in Clew's design, not an aspiration. Notes stay .md; wikilinks resolve the way Obsidian resolves them; canvases are standard JSON Canvas files. Most importantly for this chapter, Clew treats .obsidian/ as foreign territory: it never writes there, never reads your Obsidian configuration, and keeps everything of its own in .clew/. The two state folders sit side by side without contact.

One window, one vault

Clew's window model is strict and worth internalizing: one window shows exactly one vault, and the same vault is never open in two windows. When you open a vault — from the welcome screen, the File → Open Vault… dialog (⌘⇧O), or the recent-vaults list — Clew first looks for a window that already shows it and focuses that instead of opening a duplicate. If the window you asked from has no vault yet (a fresh welcome window), the vault opens right there; otherwise you get a new window. File → New Window (⌘⇧N) opens an empty window ready to take a vault.

Every window that is open when you quit is restored at the next launch, one window per vault. Closing a vault's window by hand removes that vault from the restore set. To work in two vaults at once, open them both — each gets its own window, its own explorer, its own search index, and its own layout, completely independent of the other.

The file explorer

The explorer is the Files tool in the left sidebar. Clicking a note opens it — in a new tab by default, though a note that is already open in the pane focuses its existing tab rather than multiplying. ⌘-clicking inverts the default for one click, and Settings → Appearance → Explorer click opens files flips the default itself if you prefer Obsidian's replace-in-place behaviour. Clicking an image, PDF, audio, or video file opens a viewer tab (see Attachments and files), and clicking a .canvas file opens the canvas.

Right-clicking brings up the file operations. On a file: open in a new tab, in the current tab, or to the right in a split. On anything: new note, new folder, rename, reveal in Finder (or your platform's file manager), and delete — deletions go to the system Trash, not into the void, so a slip is recoverable the usual way.

Moving is dragging: drop a note or folder onto another folder to move it there, or onto the empty background of the tree to move it to the vault root.

Clicking a folder's disclosure triangle opens or closes it, and Clew remembers which folders you closed. The state is saved with the rest of the window's layout, in the vault's own .clew/workspace.json, so a vault you reopen — tomorrow, or after a restart — greets you with the same tree you left rather than everything expanded. A vault opened for the first time starts fully expanded, and folders you create later start open. Rename or move a closed folder and its state follows it, along with any closed folders inside it.

Renames rewrite links

Renaming or moving a note is safe for the rest of the vault, because Clew rewrites every [[wikilink]] that pointed at it — across all notes, in the same pass as the rename. The rewrite respects how each link was written: a link by bare name ([[Project Notes]]) is updated only when the note's name actually changed, since a pure move between folders keeps bare names valid; a link written with a path gets the new path. Renaming a folder does the same for every note inside it. Canvas files are included: a canvas's file nodes reference vault paths, and those references are rewritten too — for renamed files of any type, not only notes.

Edits from other apps

Clew watches the vault continuously. Create, delete, or move a file in Finder, in a terminal, in Obsidian, or via a sync service, and the explorer updates by itself; edit a note's content elsewhere and any open editor or preview of it reloads in place. This is what makes the simultaneous-Obsidian arrangement above workable, and it is equally what makes a synced vault (Dropbox, iCloud Drive, Syncthing) behave sensibly on the receiving machine.

Every save, on every platform, lands as a whole file. Clew writes the new text to a hidden temporary beside the note — .Thesis.md.clew-tmp for Thesis.md — flushes it to disk, and only then renames it over the original, so a crash or a sync pass in mid-write leaves either the old note or the new one, never a truncated half. The temporary exists for milliseconds and is invisible to the explorer and to Clew's own watcher; if a crash ever strands one, the next save of that note sweeps it up. A sync client's activity log is the only place you are likely to notice them.

The interesting case is a genuine conflict: the file changed on disk while you have unsaved local edits to it. Clew refuses to guess. A banner appears over the editor, auto-save pauses so your typing cannot clobber the disk version behind your back, and you choose: Keep my version (your buffer wins and is saved over the disk change) or Load disk version (your unsaved edits are discarded in favour of the file). Nothing is overwritten silently in either direction. The same banner protects canvases.

Symbolic links

Symlinked files and folders inside a vault are first-class citizens. A linked note appears in the explorer, is indexed for links, backlinks, search, and the quick switcher, renders in reading mode, and saves through the link to the real file — even when the target lives entirely outside the vault folder. A linked folder brings its whole subtree in the same way. The file watcher follows links too, so an external edit to a linked file reloads like any other. The degenerate cases are handled rather than feared: link cycles are detected and each real directory is walked exactly once, and dangling links are skipped quietly.

This is a deliberate design point, not an accident of implementation. It means a vault can weave in material that lives elsewhere on your disk — a folder of shared bibliography files, a project directory maintained by another tool, one note that belongs to two vaults at once — while the vault itself remains a clean, syncable folder. In-vault links pointing outside the vault are allowed by design.

Telling Clew to leave a folder alone

A vault is whatever folder you point Clew at, and folders collect things that are not notes: a presentation library, a build directory, a font pack, a decade of archived material you never open. Two lists in the vault's own options file say what to do about them, and they mean different things:

{
  "unindexed": ["**/libs"],
  "hidden": ["Archive/2019", "**/build"]
}

You can write them there by hand, or fill them in at Settings → This vault, one pattern per line. Either way they take effect at once: the explorer, the watcher and the index are all rebuilt under the new rules without reopening the vault.

The patterns are relative to the vault root, and the dialect is deliberately small: a plain path means that folder (or file) and everything under it; * matches within a single folder name; ** matches any number of folders including none, so **/node_modules catches one at the top just as well as one buried five deep. A line that is empty, absolute, or climbs out of the vault with .. is ignored rather than obeyed.

And if those library folders are symlinks to one shared copy — a common arrangement for presentation frameworks — there is a second thing to know. Clew follows symlinks, which Obsidian does not, and counts a tree once no matter how many links lead to it. So excluding one route to a shared folder excludes nothing at all: the walk simply reaches the same files through another link, and the total does not move. Exclude every route — which is what one ** line does.

Very large vaults, and what Clew watches

Clew watches the files in a vault so the explorer, previews and backlinks keep up with changes made anywhere — by you, by another app, by a sync client. Watching a file costs the operating system a small handle, and every window watches its own vault, so the cost is shared and finite. Clew therefore watches up to a few thousand files at a time across all open vaults, and when a vault would take it past that it stops adding and tells you so:

Watching 8,000 files in this vault; 12,445+ more are not
watched (from econ-and-id/libs/fontawesome6/svgs/thin/desktop.svg).
Changes there will not refresh on their own.

Nothing is hidden when this happens: the files are still listed, still opened, still searched and still indexed. The only thing lost is the automatic refresh, so a file changed by another program in the unwatched part may show its old contents until you reopen it.

Which files go unwatched is not left to chance. Clew decides the order before it starts watching, and it spends the budget like this:

1. Every note first. All your .md and .jmd files, however deep they sit and whatever else is in the vault. In practice this means a vault's notes are always watched: tens of thousands of them fit inside the limit on their own.
2. Then the documents Clew edits — canvases, .base files, .bib bibliographies, PDFs, office documents, drawings. A change to one of these always has a tab or a render waiting for it, and there are never many.
3. Then everything else, nearest first — breadth first, so files beside your notes are reached before files buried deep in a vendored library.

That last rule is why attachments look after themselves without being a category: a vault's own images and media sit beside or just below its notes, while a downloaded framework is five or six folders down. The measurement that produced this policy: in one real course vault — ten presentation folders, each symlinked to the same 41,000-file library — watching in plain directory order reached six of the vault's eighty-one notes before the budget was gone, all of it spent inside a font icon set. Ordering it this way watches all eighty-one, and all 288 of its documents.

Anything you do in Clew is always reflected at once, whatever the limit says: a note or folder you create, rename or delete updates the file explorer immediately, because Clew knows it made the change rather than waiting to be told about it.

If you see that message, the folder causing it is usually not note material at all, and the message names a file inside it — which tells you what to put in hidden or unindexed. node_modules, .git and .obsidian are skipped already; anything else you can exclude in a line, move out of the vault, or link to from a note rather than keep inside it. A vault of ordinary notes — even tens of thousands of them — never meets this limit.

Recent vaults, and opening another

Clew keeps a list of the last ten vaults you opened. File → Open Recent Vault lists them (with a Clear Recent Vaults entry at the bottom), and a vaultless welcome window shows the same list as one-click entries. Opening a recent vault follows the window rules above: an already-open vault focuses its window; anything else fills the current vaultless window or opens a new one.

Reference

See also

• Attachments and files — pasting images, the attachment folder, and the built-in viewers.
• Links and embeds — the wikilink syntax the rename machinery preserves.
• Navigation, tabs and splits — the workspace those explorer clicks open into.
• Panels — the explorer's siblings in the sidebars.
• Settings and hotkeys — including the per-vault settings stored in vault-settings.json.