Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-napkin/llms.txt

Use this file to discover all available pages before exploring further.

Auto-distill uses git worktrees to isolate each distill subprocess from concurrent vault writes. Worktree-based concurrency requires the subdir vault layout so that napkin can resolve the vault from inside the worktree: on a subdir-layout vault, the branch tracks .napkin/config.json, so every checked-out worktree has the .napkin/ subdirectory napkin needs to find the vault. On a legacy embedded vault, the branch has no .napkin/ subdir at all — the worktree ends up empty and napkin’s findVault falls back to the global config, routing distill writes to your real vault and silently bypassing the isolation guarantee.

​
What Is the Legacy Embedded Layout?

The legacy layout has the napkin config file (config.json) at the vault root with no .napkin/ subdirectory. In this layout, configPath === contentPath — the config directory and the note root are the same directory. Vaults created by older versions of napkin use this shape: 
my-vault/
  config.json      ← config at vault root, no .napkin/ subdir
  NAPKIN.md
  notes/
  daily/

​
What Is the Subdir Layout?

The subdir layout moves the config into a .napkin/ subdirectory. The config.json includes "vault": { "root": ".." } to tell napkin that the note root is one level up from the config. This is what napkin init creates by default in modern versions: 
my-vault/
  .napkin/
    config.json    ← config here, with "vault": { "root": ".." }
  NAPKIN.md
  notes/
  daily/

​
Migration Steps

1

cd into the vault directory

Change into the vault directory — the one where config.json and your notes currently live side by side.
cd ~/my-vault
2

Create the .napkin subdirectory

mkdir .napkin
3

Move config.json into .napkin/

mv config.json .napkin/config.json
4

Add vault.root to .napkin/config.json

Open .napkin/config.json in your editor and add "vault": { "root": ".." } at the top level. This is the key field that marks the file as a subdir-layout config and tells napkin where to find the note root.
{
  "distill": { "enabled": true }
}
5

Reload pi

If you have an active pi session, run /quit and restart it. pi-napkin reads the vault config at session start; it won’t pick up the new layout until the session restarts.
# In pi:
/quit

# Then relaunch:
pi
6

Verify the migration

Confirm that napkin now sees the subdir layout:
napkin vault --json | jq -r .path
The path field should point at <vault>/.napkin/ — that is the new configPath. If it still shows the vault root, double-check that vault.root was added correctly and that the file was saved.
Manual /distill still works on legacy embedded vaults — only auto-distill (interval + shutdown) requires the subdir layout. If you need to delay migration, you can continue using /distill manually while working on the migration. Just be aware that distill.enabled: true in a legacy layout vault will produce a migration notification at session start and auto-distill will be disabled for that session.

​
Migration from PR #11 (v0.1.x → v0.2.x)

pi-napkin v0.1.x shipped an LLM-backed git merge driver registered as .napkin-distill-merge. PR #12 (v0.2.x) removed the driver entirely — the distill agent now resolves its own merge conflicts as part of the distill task, so no external driver is needed. Vaults set up with v0.2+ never have the driver installed. If your vault was created or used with v0.1.x, it may contain inert fragments of the old driver configuration. These are harmless to leave in place (git silently falls back to its built-in merge driver when the script is gone), but cleaner to remove: 
# In each vault that ran v0.1.x distill:
git config --local --remove-section merge.napkin-distill-merge 2>/dev/null || true
Then open .gitattributes and remove the following line if it is present: 
*.md merge=napkin-distill-merge
Leaving the .gitattributes rule in place after removing the driver script is harmless — git falls back to its built-in merge driver when the named driver script cannot be found. The rule becomes inert rather than causing errors. Manual cleanup is recommended for hygiene, but there is no urgency if you prefer to defer it.

Build docs developers (and LLMs) love

Get started for freeTalk to us