Define product image standards

docs/image-guidelines.md

@@ -0,0 +1,146 @@
+# Product Image Guidelines
+
+## Purpose
+
+Product images help users identify ammunition products while browsing, scanning, or importing catalog records.
+
+Images are optional. RoundCount must continue working when an image is missing or unavailable.
+
+## Supported Formats
+
+Preferred:
+
+- WebP
+
+Accepted:
+
+- JPEG
+- PNG
+
+Not accepted:
+
+- GIF
+- SVG
+- TIFF
+- BMP
+- Renamed or executable files
+
+## File Naming
+
+Store images using:
+
+    images/<manufacturer>/<product-identifier>.<extension>
+
+Use the UPC as the filename when available:
+
+    images/winchester/020892201989.webp
+
+When no UPC exists, use a normalized manufacturer SKU:
+
+    images/lake-city/lc-m193-55gr.webp
+
+Naming requirements:
+
+- Lowercase manufacturer directories
+- Lowercase filenames
+- Hyphens instead of spaces
+- Letters, numbers, hyphens, and periods only
+
+## Image Size
+
+Recommended dimensions:
+
+    800 x 800 pixels
+
+Maximum dimensions:
+
+    1600 x 1600 pixels
+
+Recommended maximum size:
+
+    500 KB
+
+Absolute maximum size:
+
+    1 MB
+
+Images should be resized and compressed before being committed.
+
+## Image Content
+
+Preferred images should:
+
+- Clearly show the product packaging
+- Have a plain or uncluttered background
+- Be properly oriented
+- Be sharp and well lit
+- Show identifying product information when possible
+
+Do not include:
+
+- Personal information
+- People
+- Receipts
+- Shipping labels
+- Storage locations
+- Personal inventory markings
+- Unrelated objects
+- Contributor-added watermarks
+
+## Catalog Record Reference
+
+Catalog records should contain a repository-relative path:
+
+    "image": {
+      "path": "images/federal/029465063924.webp",
+      "sha256": null
+    }
+
+Do not place the complete Gitea URL in each product record.
+
+RoundCount should construct the download URL from its configured catalog repository address.
+
+## SHA-256 Checksums
+
+Generate a checksum with:
+
+    sha256sum images/federal/029465063924.webp
+
+The resulting 64-character value may be stored in the product record.
+
+Checksums allow RoundCount to verify that the downloaded image is complete and unchanged.
+
+## Missing Images
+
+When no product image is available, use:
+
+    "image": null
+
+RoundCount should display its built-in placeholder image.
+
+Do not store separate copies of the placeholder for every product.
+
+## Image Validation
+
+The catalog validation tool should eventually verify:
+
+- The referenced image exists
+- The extension is supported
+- The file is a valid image
+- Dimensions are within limits
+- File size is within limits
+- SHA-256 matches when provided
+- The path remains inside the images directory
+
+## Copyright and Sources
+
+Only add images that may legally be stored and redistributed.
+
+Preferred sources:
+
+1. Original contributor photograph
+2. Manufacturer-provided media
+3. Distributor media with redistribution permission
+4. Properly licensed third-party media
+
+Image source information should be documented when appropriate.