Skip to the document

Vaults

A vault is a folder. That's the whole idea: everything it needs, documents, blocks, themes, is a file inside it, so the folder can live in Drive, Dropbox, OneDrive or a git repository and Plicine works the same way in all of them.

Layout

A full vault looks like this:

my-vault/
  .vault/
    vault.json         title, theme, default page size, aliases
    blocks/            *.block files
      blocks.lock      resolved block ids, versions and hashes
    themes/            *.theme files
  assets/              images and logos
  AGENTS.md            the agent primer, only when agentsMd is on
  INDEX.md             optional: the vault's own page
  doc-one.md
  doc-two.md
  proposals/           any folder of markdown is just a folder of documents

Everything that configures the vault, rather than its content, lives under .vault/: the config file, the installed blocks and themes, and the lock file that remembers how they resolved. .vault/vault.json is optional. If it's missing, Plicine uses sensible defaults (theme default, page A4, no aliases) and only complains if a .vault/vault.json is present but doesn't parse. See vault.json and frontmatter for every field it accepts.

Documents live at the vault root, in whatever folders you like, alongside .vault/ and assets/. Listing documents skips assets/ and every dot folder, .vault/ included. A folder called docs gets no special treatment: it shows up in the sidebar like proposals/ or any other folder.

INDEX.md

An INDEX.md is the page of the folder it's in (matched case-insensitively, so index.md works too, though INDEX.md is the convention). Clicking the folder in the sidebar opens it, and it isn't listed among the folder's documents. Every folder has one as far as the app is concerned. A folder without the file opens as a blank page, and the file is only written, as INDEX.md in that folder, the first time something is put on the page, so looking into folders never creates anything. When the page has no title in its frontmatter and no # heading, it takes the folder's name.

The vault is a folder too, and the same rule covers it. The INDEX.md at the vault root is the vault's own page: the vault's name at the top of the sidebar opens it, it has no row among the documents, it's blank and unwritten until something is put on it, and with no title of its own it takes the vault's title (title in .vault/vault.json, or the folder's name). Opening a vault without a specific document in the URL loads it, falling back to the first document while the file doesn't exist, and export-site writes it as the site's front page. One thing a folder's INDEX.md does that the vault's doesn't: its frontmatter isn't a layer of values for the documents below it, because values in .vault/vault.json already is (vault.json and frontmatter).

README.md isn't treated specially anywhere; a vault doesn't need one, and if it has one, it's just an ordinary document sorted by title like any other.

What Plicine writes into a vault, and what it never writes

Plicine's app and CLI generate exactly two files inside a vault. .vault/blocks/blocks.lock is written only when block resolution actually changes (see How blocks work). AGENTS.md at the vault root is written only when you turn agentsMd on, and, like the lock, only when its content would actually differ; it's described under AGENTS.md below. Editing a setting through the app writes .vault/vault.json too, but that's your configuration rather than generated output, and only when you ask for the change. Everything else the tools generate, compiled block bundles, the render cache used for PDF export, and each person's approval decisions, lives outside the vault entirely, in the app's own data folder:

  • ~/Library/Application Support/plicine on macOS
  • %APPDATA%\plicine on Windows
  • or wherever PLICINE_DATA_DIR points, which keeps a CI run's data apart from your own

This is deliberate, not an oversight. A vault is usually sitting inside a synced folder, and sync clients like Dropbox and OneDrive don't read .gitignore or any other ignore file, they sync whatever is there. If Plicine wrote compiled code or per-machine caches into the vault, those files would sync to every other person's computer too, causing needless churn and, worse, conflicted copies of files nobody asked to share. Keeping generated output out of the vault also means an up-to-date vault stays untouched by simply opening it: nothing changes on disk unless resolution genuinely drifts.

blocks.lock

blocks.lock records exactly which block, version and file hash each name in the vault resolved to, the last time resolution ran. It's a plain JSON file at .vault/blocks/blocks.lock and syncs like any other file. Plicine rewrites it only when resolution has genuinely changed, never on every open, so an up-to-date vault stays untouched. The format, and how the lock affects which block actually runs, is covered in How blocks work.

AGENTS.md

AGENTS.md at the vault root holds the primer Plicine gives an agent: the document syntax, every block the vault can use with its props, how block code is drawn and what the sandbox rules out, the commands worth running and the files not to edit by hand. It's there so an agent working from a terminal, with Plicine closed, starts with the same picture the agent palette gives one running inside the app.

It's off until you turn it on, because it's a generated file in a folder other people sync. Turn it on with Write AGENTS.md in the palette's agent menu, or with plicine agents-md <vault> --write; either one sets agentsMd in .vault/vault.json and writes the file. While it's on, Plicine rewrites it whenever the vault's documents, blocks, themes or configuration change, and only when the content would actually differ, so an unchanged vault stays untouched.

Two things follow from it being generated rather than written. The file carries a marker comment on its first line, and Plicine only ever overwrites or removes a file that has it, so an AGENTS.md you wrote yourself is left alone and reported rather than replaced. And the vault root's AGENTS.md isn't listed as a document: it doesn't appear in the sidebar, [[links]] don't resolve to it, and the watcher gives it a kind of its own so Plicine's own write never looks like a document changing.

Library and community folders

Two more folders live in the app's data folder rather than in any single vault: a library folder for blocks and themes you or your organisation install once and want available everywhere, and a community folder for ones you got from somewhere else and want to keep apart from your own. plicine install some-block.block copies into the library by default, or into community with --community. Both are searched when resolving a name that isn't satisfied by the vault's own .vault/blocks/ or .vault/themes/ folder, so a block installed into your library is available to every vault you open on that machine without copying it into each one. See How blocks work for where library and community sit in the resolution order, and The app data folder for the full layout of the app data folder.