From aee7bc4536febb3e13c9194a9805ae0a1ec780d6 Mon Sep 17 00:00:00 2001
From: Andrew Griess <BeardedDragon757@gmail.com>
Date: Wed, 15 Jul 2026 11:08:19 -0500
Subject: [PATCH] Define product image standards

---
 docs/image-guidelines.md | 146 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 docs/image-guidelines.md

diff --git a/docs/image-guidelines.md b/docs/image-guidelines.md
new file mode 100644
index 0000000..9b11ebd
--- /dev/null
+++ b/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.