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.

When auto-distill is enabled, pi-napkin installs and maintains a single contiguous block in your vault’s .gitignore file. This block covers the ephemeral state that auto-distill generates (worktree session forks, Obsidian workspace caches) as well as common secrets that would otherwise be swept into the initial git add . commit on a vault that happens to sit alongside development work. The block is delimited by exact sentinel comment lines so pi-napkin can precisely locate and update its own content without ever touching anything you’ve written outside the markers.

​
What the block looks like

# BEGIN NAPKIN-DISTILL MANAGED
# napkin-distill ephemeral state
.napkin/distill/

# Obsidian workspace-local state
.obsidian/workspace*.json
.obsidian/cache
.obsidian/.trash/

# Local tmp/cache
search-cache.json
.DS_Store

# Common secrets — belt-and-braces for vaults that end up alongside dev
# work. Auto-distill commits 'git add .' on first run; these patterns
# keep credentials out of the initial commit even if a user's vault
# happens to contain them.
.env
.env.local
.env.*.local
*.pem
*.key
id_rsa
id_ecdsa
id_ed25519
secrets.json
.aws/credentials
# END NAPKIN-DISTILL MANAGED

​
The rules

Inside the markers — pi-napkin’s territory. pi-napkin owns every line between # BEGIN NAPKIN-DISTILL MANAGED and # END NAPKIN-DISTILL MANAGED. If you edit lines inside the block by hand, they will be reset to the canonical content on the next session start. The health check detects any drift and rewrites the bracketed region in place. Outside the markers — your territory. Everything in .gitignore that lives outside the markers belongs to you. pi-napkin never adds, removes, or reorders any of your custom entries. The only exception is a one-time migration cleanup (see below): if orphaned lines that exactly match canonical block content exist outside the markers (a residue from the pre-v0.3.1 line-by-line format), they are removed and the block is installed. Lines that do not match canonical content are never touched, regardless of where they appear.
Add your custom gitignore entries anywhere outside the markers and pi-napkin will leave them alone permanently. A common pattern is to put project-specific entries before the block and global personal entries after it, but any arrangement works.

​
When is the block installed?

The block is installed on the first session start in a vault where distill.enabled: true is set. If the vault is not yet a git repo, pi-napkin runs git init first, then installs the block as part of the initial commit. On every subsequent session start, the health check confirms the block matches canonical content. If drift is detected — content changed, markers reordered, or canonical lines leaked outside the block — the block is automatically recovered in place before any distill spawns.

​
Recovery behaviors

FindingWhat happenedWhat pi-napkin does
installedMarkers absent; no orphan lines in file.Appends the block to the end of .gitignore.
migrated from line-by-lineMarkers absent but v0.3.0 orphan canonical lines found in the file, OR markers present with orphan canonical lines outside them.Removes the orphan lines from user territory and installs or preserves the block.
resetMarkers present; content inside drifted from canonical; no orphan lines outside.Rewrites the bracketed region in place; lines outside the markers are untouched.
reset and migrated from line-by-lineMarkers present; content inside drifted from canonical; AND orphan canonical lines found outside the markers.Rewrites the bracketed region in place AND removes the orphan lines from user territory in the same pass.
Malformed markersMultiple BEGIN markers, a BEGIN with no matching END, or END appearing before BEGIN.Emits a loud error notification; leaves .gitignore completely untouched. Resolve the markers manually before distill can proceed.
The sentinel pattern — # BEGIN NAPKIN-DISTILL MANAGED / # END NAPKIN-DISTILL MANAGED — is the same Ansible-style blockinfile convention used by Ansible, Homebrew, and oh-my-zsh. If you’ve used any of those tools, the boundary between managed and unmanaged content will look immediately familiar. The exact suffix NAPKIN-DISTILL MANAGED is required so the markers don’t collide with any unrelated # BEGIN ... comments already in your file.

Build docs developers (and LLMs) love

Get started for freeTalk to us