Where Your Data Lives

nitpin is local-first: everything you capture is plain files on your machine, YAML and PNGs you can read, diff, and version like anything else. No backend, no cloud copy. Screenshots, notes, and repo paths never leave your device.

A project store

A project is a folder:

.nitpin/                        (or a folder under ~/.nitpin/projects/)
  project.yaml                  the project's identity and settings
  issues/
    001_pay-button-misaligned/
      issue.md                  the issue — your notes, statuses, provenance
      clean.png                 the capture, untouched
      annotated.png             the capture with badges drawn (when marks exist)
      img-1.png                 any images you pasted into notes or comments
      comments.yaml             the discussion thread (when there is one)
  locks/                        transient agent claims (never committed)
  clusters.yaml                 the triage grouping (committed only if you share it)

Screenshot pixels are never embedded in text files; images sit beside the issue as ordinary PNGs. An in-repo store is meant to be committed — issues travel with the code, and git sync automates the chore. Claims and other transient state are ignored by git automatically.

The user store

Machine-wide data lives in ~/.nitpin/:

~/.nitpin/
  config.yaml            machine-wide preferences (default project path, task models, …)
  projects.yaml          the list of known projects
  active-project.yaml    which project captures land in
  projects/              "in nitpin" project stores

Set NITPIN_HOME to relocate all of it.

How a repo finds its project

Tools and agents resolve the project for a directory in this order:

1. a .nitpin/ store in the directory (or an ancestor),
2. a nitpin.yaml pointer written by nitpin link or nitpin init --path,
3. otherwise, the app’s active project.

Portability & backup

Because a store is just files: back it up by backing up the folder, move it by moving the folder, share it through git. Deleting a project from the Cockpit moves its store to the Trash — nothing is ever destroyed silently.