Imported from cristianoliveira/pxp (internal/annotationio/AGENTS.md). Install upstream with npx skills add cristianoliveira/pxp --skill annotationio. Copyright stays with the author.

Purpose

internal/annotationio owns the JSON and filesystem adapter for annotation documents.

Boundaries

It translates the wire DTO into the annotation domain and persists validated documents. It does not own coordinate rules, image comparison, or command policy.

Connections

• Annotations: provides the domain document that this adapter validates and serializes.
• Artifact persistence: provides parent-directory creation and file creation.
• Command orchestration: consumes loaded documents at the comparison boundary.

Landmarks

• internal/annotationio/annotationio.go:Load: decodes, rejects trailing JSON, and validates an annotation document.
• internal/annotationio/annotationio.go:Write: serializes an annotation document to JSON.

Boundary flows

• Information flow: internal/annotationio/annotationio.go:Load -> internal/annotations/annotations.go:Document.Intersections via internal/commands/command.go:NewCommand; value: annotations.Document.

Placement

Keep wire-format translation and file access here. Put annotation invariants in annotations and generic filesystem creation in artifact.