image-reference-preflight/README.md

A Preflight Manifest and Validator for Image References in Design Repositories

The problem: images arrive faster than their records do

Anyone maintaining a repository of visual assets for a product launch, a storyboard, or a set of social graphics knows the pattern. A folder fills up with PNGs and JPEGs pulled from stock libraries, internal renders, screenshots, and AI-assisted drafts. Weeks later, nobody can say with confidence where a given file came from, whether it was AI-generated, whether it used a reference photo of a real object, or whether the alt text was ever written. This is not a hypothetical concern for teams that need to disclose AI involvement or track licensing terms before an asset goes into a public deck or a client review.

The fix does not require heavy tooling. A small JSON manifest checked into the repository alongside the assets, plus a validator script that runs in CI, closes most of the gap.

A manifest that carries the facts, not just the files

The manifest should be boring and explicit. Each entry names the file, its expected pixel dimensions, a content hash, where it came from, whether it used an object reference, and whether alt text and disclosure fields are filled in.

{
 "assets": [
 {
 "file": "campaign/hero-01.png",
 "width": 1600,
 "height": 900,
 "sha256": "a1b2c3d4e5f6...",
 "sourceLabel": "internal-render",
 "objectReferenceRole": "none",
 "aiAssisted": false,
 "altText": "Wide banner showing a stylized product on a gradient background",
 "disclosure": "none-required"
 },
 {
 "file": "campaign/mockup-03.png",
 "width": 2048,
 "height": 1365,
 "sha256": "9f8e7d6c5b4a...",
 "sourceLabel": "ai-draft",
 "objectReferenceRole": "product-shape-reference",
 "aiAssisted": true,
 "altText": "Early concept mockup of a beverage can on a wooden table",
 "disclosure": "ai-assisted-draft"
 }
 ]
}

The objectReferenceRole field matters when a workflow uses a reference image to guide shape, pose, or layout rather than generating from a text prompt alone. Labeling it as none, product-shape-reference, pose-reference, or similar keeps later reviewers from guessing whether a real photographed object informed the output.

A validator that checks what the manifest promises

A short Node script can run in a pre-commit hook or CI job to confirm the manifest matches the files on disk.

const fs = require('fs');
const crypto = require('crypto');
const path = require('path');
const sizeOf = require('image-size');

function sha256(filePath) {
 const buffer = fs.readFileSync(filePath);
 return crypto.createHash('sha256').update(buffer).digest('hex');
}

function validateManifest(manifestPath, baseDir) {
 const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
 const errors = [];

 for (const asset of manifest.assets) {
 const filePath = path.join(baseDir, asset.file);
 if (!fs.existsSync(filePath)) {
 errors.push(`Missing file: ${asset.file}`);
 continue;
 }
 const dims = sizeOf(filePath);
 if (dims.width !== asset.width || dims.height !== asset.height) {
 errors.push(`Dimension mismatch for ${asset.file}`);
 }
 const hash = sha256(filePath);
 if (hash !== asset.sha256) {
 errors.push(`Hash mismatch for ${asset.file}`);
 }
 if (!asset.sourceLabel) errors.push(`Missing sourceLabel for ${asset.file}`);
 if (!asset.altText || asset.altText.trim().length === 0) {
 errors.push(`Missing altText for ${asset.file}`);
 }
 if (asset.aiAssisted && asset.disclosure === 'none-required') {
 errors.push(`AI-assisted asset needs disclosure: ${asset.file}`);
 }
 }

 return errors;
}

const errors = validateManifest('manifest.json', './');
if (errors.length) {
 console.error(errors.join('\n'));
 process.exit(1);
}
console.log('Manifest validation passed.');

This is intentionally minimal. It confirms files exist, dimensions and hashes match, and required text fields are not empty. Teams can extend it to check aspect ratio tolerances, enforce naming conventions, or cross-reference license files.

Where an upstream drafting tool fits

Many of the entries in a manifest like this originate outside the repository entirely, from whatever tool a designer used to sketch an early concept. If a contributor used a third-party AI drafting tool to produce a rough mockup before refining it in-house, the sourceLabel and aiAssisted fields are the place to record that honestly rather than after the fact. One example of such a tool is Nano Banana 2 Lite, an independent third-party site for AI image generation and editing that supports prompt-based creation and object-reference workflows for things like advertising concepts and storyboards. It is not a Google or DeepMind product, and nothing about its credit structure, output limits, or generation speed should be assumed from its name; anyone evaluating it for a workflow should check its current terms directly rather than relying on secondhand claims.

Limitations worth stating plainly

A manifest and validator like this only catch what they are told to check. They cannot verify that a sourceLabel is truthful, only that the field is present. They cannot detect subtle edits made after the hash was recorded unless the hash is recomputed on every commit. And they say nothing about copyright or licensing terms for reference images pulled from outside sources, which still needs separate tracking. Treat this as a floor for provenance hygiene, not a substitute for an actual review process before assets ship to a client or a public campaign.