AGENTS.md

1# PhotoPrism Core Import & Index Guidelines
2 
3**Last Updated:** April 9, 2026
4 
5## Import & Index Behavior
6 
7- `ImportWorker` may skip a file when an identical file already exists. Use unique copies or assert DB rows only after ensuring the destination is not a duplicate.
8- Keep `SamplesPath()`, `ImportPath()`, and `OriginalsPath()` consistent when testing related files so `RelatedFiles` and `AllowExt` behave correctly.
9- `IndexOptions*` helpers now require a `*config.Config`; pass the active config, or `config.NewMinimalTestConfig(t.TempDir())` in unit tests, so face, label, and NSFW scheduling matches the current run.
10- Vision scheduling is controlled by `VisionSchedule`, `VisionFilter`, and the `Run` property in `vision.yml`. Use helpers such as `vision.FilterModels` and `entity.Photo.ShouldGenerateLabels` or `ShouldGenerateCaption` before loading media.
11- Folder albums use path-first lookup and update via `album_path` to avoid slug collisions for emoji child paths; re-indexing may repair stale collision titles while preserving user-custom titles.
12- Reuse `entity.FindLabels(...)`, `entity.FindLabelIDs(...)`, and `entity.LabelSlugs(...)` for label lookup so homophone-aware exact-name matching stays aligned across entity and search packages.
13 
14## File I/O Overwrite Policy
15 
16- Default to safety: callers must not overwrite non-empty destination files unless they opt in with `force=true`.
17- Replacing an empty destination file is allowed without `force=true`.
18- Open overwriting destinations with `O_WRONLY|O_CREATE|O_TRUNC` so stale trailing bytes cannot survive; use `O_EXCL` when the caller must detect collisions.
19- App-level overwrite helpers live in `internal/photoprism/mediafile.go`; reusable helpers live in `pkg/fs/copy.go` and `pkg/fs/move.go`.
20- Set `force=true` only for explicit replace flows or admin tools with confirmed overwrite, not for import or index flows that touch Originals.
21 
22## Tests
23 
24- In `internal/photoprism` tests, rely on `photoprism.Config()` for runtime-accurate behavior; only build a new config if you replace it with `photoprism.SetConfig`.
25 
26