photocli/AGENT.md

AGENT.md

• Project: photoscli, macOS Apple Photos exporter, Go + cgo + Objective-C PhotoKit bridge.
• Release binary target: Apple Silicon only (darwin/arm64). Make this explicit in docs/assets.
• Module: gitea.k3s.k0.nu/tools/photocli.
• Run tests with -tags=test; tests use the C stub bridge, not real PhotoKit.
• Required before any release: go test -tags=test -race -count=1 -coverprofile=coverage.out ./... must show 100% for all packages, then make pipeline, then make package.
• Never release below 100% coverage.
• Release assets must include: binary, USERGUIDE.md, and photoscli-<version>-macos-arm64.zip.
• Release page must use clear notes from RELEASE_NOTES.md; CHANGELOG.md must be updated too.
• Keep README concise; put practical user workflows in USERGUIDE.md.
• Manifest backends: JSONL default, SQLite optional via modernc.org/sqlite.
• Preserve manifest compatibility and migration behavior.
• XMP sidecars are opt-in via --sidecar xmp; default must remain none.
• Reverse geocoding is opt-in via --reverse-geocode, uses MapKit on macOS 26+, and must fail safely on older macOS without failing export.
• Do not claim Photos people/animal/object labels are exported unless Vision/Core ML analysis is explicitly implemented.
• Roadmap: keep 0.8.x focused on making XMP sidecars as rich, standard-compatible, and complete as possible from public PhotoKit metadata.
• Roadmap: use 0.9.0 through 0.9.5 for checksums, deep verification, manifest repair, cleanup, doctor, and backup-integrity hardening.
• Roadmap: start Vision/Core ML analysis only after 0.9.5; keep it opt-in and label it as photoscli-generated analysis, not Apple Photos metadata.
• Do not commit generated artifacts from bin/ or coverage files.