docs / your-files

Your files.

Your notes are plain markdown files in a folder on your disk, called the vault. That folder is the whole of your data. Paperkites keeps an index of it, and rebuilds that index from the files every time it starts.

The vault

The vault is ~/notes unless you choose another folder.

Command	Does
`:vault`	shows which folder Paperkites is using
`:vault ~/somewhere/else`	points Paperkites at another folder

Switching copies and moves nothing. The old folder stays exactly where it was, and you can switch back. In :settings, under Vault, you can show the folder in Finder.

What's in the folder

~/notes/
  Welcome.md
  Reading list.md
  2026-09-24.md
  Pics/
    photo.png
  attachments/
    01J8Z….age
  fragments/
  people/
    dasha.md
  .trash/

Where	What
`<Title>.md`	a note, named after its title. Renaming the note renames the file.
`fragments/`	one file per fragment
`people/`	person notes, named after their username (see People)
`attachments/`	images pasted or dropped into notes; a locked note's are encrypted, as `.age` files
`.trash/`	notes you've deleted; never indexed, so never in lists or search

Images can live anywhere in the vault; a note refers to them by path, such as ![alt](Pics/photo.png).

Front matter

A note can start with a block of front matter between two --- lines. Paperkites leaves it alone, apart from three lines:

---
created: 2026-09-24T08:15:00Z
id: 01J8Z3K4QW7T9V2N5M6B1C0D8E
pinned: true
---

Key	What Paperkites does with it
`created`	when the note was made; shown in the gutter
`id`	the note's identity, a ULID. A rename keeps it.
`pinned`	added when you pin a note and taken out when you unpin it, so the file comes back byte for byte

A locked note also has lock: password, and below its title its text is encrypted (see Locked notes). Person notes also use type, username and aliases. Anything else you put in front matter stays as you wrote it.

Pinning

Pinning keeps a note at the top of the lists. :pin and :unpin work in a note, and x works on a row in any list. :pinned lists everything pinned. On disk, pinning is just the pinned: true line above.

Editing outside Paperkites

Anything that works on files works on your notes: git, grep, sync tools, any editor. Paperkites watches the folder while it runs, so a file added, edited, renamed or deleted elsewhere shows up within a moment.

If that note is open in Paperkites:

With nothing unsaved, it takes the new text.
With unsaved edits, it asks you to choose:

Command	Does
`:reload`	take the file's version
`:w`	write your version over it

Working with other tools

Git: cd ~/notes && git init, and commit whenever you like.
grep: grep -ri "soil" ~/notes searches the same text / does.
Any editor: open a note in vim or VS Code, change it, and Paperkites picks it up.
Sync: keep the folder in anything that syncs folders, and point Paperkites at it with :vault. See Coming soon.

The trash

:delete (or :rm) in a note moves it to .trash/ in your vault. Nothing is deleted for good until you say so.

Command	Does
`:trash`	lists trashed notes
`⏎` on a trashed note	puts it back where it lived
`:trash empty`	deletes everything in the trash for good

The trash is also in :settings, under Vault. It's an ordinary folder; its name starts with a dot, so some file browsers hide it.

Settings and themes live elsewhere

Your settings are kept on this device, in the app's data folder, outside the vault. Theme files live in ~/.kites/themes/. See Settings and Themes.