Shoot layout¶

Every file krites writes into a shoot directory, what it holds, and which command writes it.

The shoot directory is your own folder¶

A shoot is your folder of frames. krites does not create a workspace elsewhere and does not copy anything into one. It adds a .krites/ sidecar beside your files, and — only when you export — an export/ directory.

~/Pictures/smith-wedding/
├── IMG_2043.CR2            ← your originals, never modified
├── IMG_2043.xmp            ← only if you ran `krites xmp write`
├── .krites/                ← everything krites decides
└── export/                 ← only if you ran `krites export`

The `.krites/` sidecar¶

Path	Holds	Written by
`shoot.yaml`	The manifest: shoot name, source path, creation time, frame list	`ingest`
`verdicts.yaml`	Per frame: verdict, reasons, whether you overrode it, star rating, burst cluster, the machine's own proposal, decision time	`cull`, `verdict`
`analysis.yaml`	The regenerable signal cache — sharpness, exposure, eye/smile/facing, perceptual hashes, face boxes, frame dimensions	`cull`
`develop.yaml`	The shoot's develop config: the look catalog and the straighten/crop settings	`develop` and the studio
`exports.yaml`	Append-only ledger of each export run: when, which frames, which verdict set, `--max-dim` and `--quality`	`export`
`edits/<frame>.yaml`	One frame's reversible edits: straighten angle, crop rectangle, look reference, removal list	`straighten`, `crop`, `develop`, `remove`
`removals/<frame>/<n>.png`	The materialised inpaint patch for one object removal	`remove`
`reviews/<frame>.md`	The rendered AI critique	`review`
`reviews/<frame>.yaml`	The structured review record — scores, labels, provider provenance	`review`
`previews/…`	The preview cache, keyed by frame, size, render mode and edit state	the studio
`jobs/<jobId>.yaml`	A crash breadcrumb for a running background job, deleted the moment it ends	the studio

Directories are created 0750 and files 0600.

Which of these you can safely delete¶

File	Safe to delete?
`analysis.yaml`	Yes — regenerable. The next cull re-decodes and re-measures
`previews/`	Yes — regenerable, and nothing else prunes it
`jobs/`	Yes — only affects whether an interrupted job is reported
`verdicts.yaml`	Loses every verdict and rating; the frames themselves are fine
`edits/`	Loses every straighten, crop and look
`develop.yaml`	Loses the shoot's look catalog
`removals/`	No — each patch is the only copy of a generative fill
`shoot.yaml`	No — without the manifest the folder is no longer a shoot
`exports.yaml`	Loses the delivery history; exports themselves are unaffected

The removal patches deserve the emphasis. Unlike the preview cache they are not regenerable: each one is the sole copy of a generative fill, and the edit record only points at it. Losing one loses that removal, recoverable only by re-running krites remove against the model — which will not reproduce the same fill.

`export/`¶

krites export renders into <shoot>/export/. It is the only directory outside .krites/ that krites writes, and the only place new pixels are ever produced.

A frame with no edits and no resize is copied verbatim — original bytes, original metadata, no re-encode. Anything else is decoded, baked and re-encoded: PNG for a .png source, JPEG otherwise.

A RAW frame always renders, because the deliverable is a JPEG from its embedded preview rather than a copied RAW container. The .jpg is appended rather than swapped, so IMG_2043.ARW exports as IMG_2043.ARW.jpg. That looks odd but is deliberate: swapping the extension would collide a RAW+JPEG pair (IMG_2043.ARW and IMG_2043.JPG) onto one output file.

The one file krites puts in your own folder¶

krites xmp write writes <frame-base>.xmp beside the original — in your folder, not in .krites/. It writes only the .xmp companion and never the image.

Two consequences worth knowing:

No reset removes them. krites reset only touches .krites/ and export/. Deleting stale sidecars is a manual step.
A RAW+JPEG pair collides. The extension is stripped, not appended, so IMG_2043.ARW and IMG_2043.JPG both map to IMG_2043.xmp. When both are in the shoot, one verdict overwrites the other, and which one wins is not deterministic. Shoot RAW-only, or JPEG-only, if you rely on sidecars.

Which files each command touches¶

Command	Writes	Deletes	Touches an original?
`ingest`	`.krites/shoot.yaml`	—	No
`cull`	`verdicts.yaml`, `analysis.yaml`	—	No
`verdict`	`verdicts.yaml`	—	No
`straighten`	`edits/<frame>.yaml`	that file, if the record becomes empty	No
`crop`	`edits/<frame>.yaml`	that file, if the record becomes empty	No
`develop`	`edits/<frame>.yaml`	that file, if the record becomes empty	No
`remove`	`removals/<frame>/<n>.png` and `edits/<frame>.yaml`	—	No
`review`	`reviews/<frame>.md`, `reviews/<frame>.yaml`	—	No
`xmp write`	`<frame-base>.xmp` beside the original	—	No — only the `.xmp` companion
`export`	`export/<frame>`, appends to `exports.yaml`	—	No
`reset frame`	rewrites `verdicts.yaml`	`edits/<frame>.yaml`, `removals/<frame>/`	No
`reset shoot`	rewrites or deletes `verdicts.yaml`	see `reset shoot`	No
`reset exports`	—	the whole `export/` directory	No

What ingest does and does not do¶

krites ingest registers. It does not copy, move, rename or link anything; it reads the directory listing, records the frame names in the manifest, and creates the sidecar.

Behaviour	Detail
Accepted extensions	`.jpg`, `.jpeg`, `.png`, `.arw`, `.cr2`, `.nef`, `.dng` — matched case-insensitively
Unrecognised files	Silently skipped. No error, no warning, no line in the report
Subdirectories	Not scanned. Ingest is non-recursive; only files directly in the folder are registered
A folder with no supported frames	Fails with `no supported frames (…) in "…"`
Re-ingesting an existing shoot	Rewrites `shoot.yaml` with a fresh manifest and a new creation timestamp. Verdicts and edits are untouched; there is no "already a shoot" guard

Because unrecognised files and subdirectories are skipped without comment, a card dump with frames in DCIM/100CANON/ registers zero frames and fails rather than finding them.