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.