@iodes/releasekit 0.1.0 → 0.1.1

package/dist/images.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import sharp from 'sharp';
-import { themes, theme } from './model.js';
+import { themes, assetVariant, imageSource, activeVariants } from './model.js';
 import { Project, editable } from './project.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { digest, identifier, exists, write, writeYaml } from './files.js';
@@ -27,10 +27,11 @@ export async function planImages(project, version) {
     let ready = 0;
     for (const note of release.notes.filter(n => n.image)) {
         const visual = await readVisual(project, version, note.id);
+        const source = imageSource(visual.scene);
         const pair = visual.variants;
         const invalidPair = release.visuals.themes === 'both' && pair.dark && pair.light &&
             (pair.dark.sha256 === pair.light.sha256 || pair.dark.width !== pair.light.width || pair.dark.height !== pair.light.height);
-        for (const variant of themes(release.visuals)) {
+        for (const variant of activeVariants(visual, release.visuals)) {
             const expected = sceneHash(visual.scene, release.visuals, variant);
             const asset = visual.variants[variant];
             const file = asset && await project.releaseFile(version, asset.file);
@@ -41,6 +42,16 @@ export async function planImages(project, version) {
                 continue;
             }
             editable(release);
+            if (source === 'provided') {
+                requests.push({
+                    note: note.id, theme: variant, reason: present ? 'stale' : 'missing', action: 'provide',
+                    promptFile: null, compositionReference: null,
+                    instruction: `Use an existing approved image or ask for a capture, photograph, or content asset for "${visual.scene.subject}". Import the selected file with --theme ${variant}. Do not synthesize a replacement.`,
+                });
+                continue;
+            }
+            if (variant === 'shared')
+                throw new Error('Generated images require a dark or light variant.');
             await checkReferenceFiles(project, visual.scene.references);
             const promptFile = await project.releaseFile(version, `prompts/${note.id}.${variant}.md`);
             await write(promptFile, imagePrompt(visual.scene, release.visuals, variant));
@@ -52,12 +63,14 @@ export async function planImages(project, version) {
                 if (await exists(reference) && digest(await fs.readFile(reference)) === other.sha256)
                     compositionReference = reference;
             }
-            requests.push({ note: note.id, theme: variant, reason: present ? 'stale' : 'missing', promptFile, compositionReference });
+            requests.push({ note: note.id, theme: variant, reason: present ? 'stale' : 'missing', action: 'generate', promptFile, compositionReference });
         }
     }
     return {
         version, configuredThemes: themes(release.visuals), requestedAssets: ready + requests.length,
         readyAssets: ready, pendingAssets: requests.length, requests,
+        generationRequests: requests.filter(request => request.action === 'generate').length,
+        providedRequests: requests.filter(request => request.action === 'provide').length,
         costNote: 'Counts describe required output assets, not provider prices or a guarantee of one tool call per asset. No image service was called.',
     };
 }
@@ -65,12 +78,23 @@ export async function importImage(project, version, noteId, variant, source) {
     const release = await project.release(version);
     editable(release);
     identifier(noteId);
-    theme.parse(variant);
+    assetVariant.parse(variant);
     if (!release.notes.some(n => n.id === noteId && n.image))
         throw new Error(`No image-enabled note named ${noteId}.`);
-    if (!themes(release.visuals).includes(variant))
-        throw new Error(`Theme ${variant} is not enabled for this release. Update the project setting and sync the draft first.`);
     const visual = await readVisual(project, version, noteId);
+    const provided = imageSource(visual.scene) === 'provided';
+    if (variant === 'shared') {
+        if (!provided)
+            throw new Error('Only supplied images can use a shared asset.');
+        if (visual.variants.dark || visual.variants.light)
+            throw new Error('Remove the themed variant entries before switching to one shared supplied image.');
+    }
+    else {
+        if (!themes(release.visuals).includes(variant))
+            throw new Error(`Theme ${variant} is not enabled for this release. Update the project setting and sync the draft first.`);
+        if (visual.variants.shared)
+            throw new Error('Remove the shared variant entry before switching to distinct supplied theme variants.');
+    }
     const bytes = await fs.readFile(path.resolve(project.root, source));
     const inspected = await inspectImage(bytes);
     const file = `assets/${noteId}.${variant}.${inspected.sha256.slice(0, 12)}.${inspected.extension}`;
@@ -90,7 +114,7 @@ export async function importImage(project, version, noteId, variant, source) {
 }
 export async function validateImages(project, version, noteId, visual, errors, warnings) {
     const release = await project.release(version);
-    for (const variant of themes(release.visuals)) {
+    for (const variant of activeVariants(visual, release.visuals)) {
         const expected = sceneHash(visual.scene, release.visuals, variant);
         const asset = visual.variants[variant];
         if (!asset) {
@@ -105,7 +129,7 @@ export async function validateImages(project, version, noteId, visual, errors, w
                 errors.push(`${noteId}: ${variant} asset changed after import; import the selected file again.`);
             }
             const requestedRatio = release.visuals.width / release.visuals.height;
-            if (Math.abs(actual.width / actual.height / requestedRatio - 1) > 0.05) {
+            if (imageSource(visual.scene) === 'generated' && Math.abs(actual.width / actual.height / requestedRatio - 1) > 0.05) {
                 warnings.push(`${noteId}: ${variant} aspect ratio differs from the project target; review its framing.`);
             }
         }

package/dist/model.d.ts

@@ -7,6 +7,12 @@ export declare const theme: z.ZodEnum<{
     light: "light";
 }>;
 export type Theme = z.infer<typeof theme>;
+export declare const assetVariant: z.ZodEnum<{
+    dark: "dark";
+    light: "light";
+    shared: "shared";
+}>;
+export type AssetVariant = z.infer<typeof assetVariant>;
 export declare const paletteSchema: z.ZodObject<{
     canvas: z.ZodString;
     surface: z.ZodString;
@@ -193,6 +199,10 @@ export declare const sceneSchema: z.ZodObject<{
         "symbol-pair": "symbol-pair";
         "ui-detail": "ui-detail";
     }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        generated: "generated";
+        provided: "provided";
+    }>>;
     subject: z.ZodString;
     message: z.ZodString;
     focus: z.ZodString;
@@ -225,6 +235,10 @@ export declare const visualSchema: z.ZodObject<{
             "symbol-pair": "symbol-pair";
             "ui-detail": "ui-detail";
         }>;
+        source: z.ZodOptional<z.ZodEnum<{
+            generated: "generated";
+            provided: "provided";
+        }>>;
         subject: z.ZodString;
         message: z.ZodString;
         focus: z.ZodString;
@@ -251,6 +265,13 @@ export declare const visualSchema: z.ZodObject<{
             width: z.ZodNumber;
             height: z.ZodNumber;
         }, z.core.$strict>>;
+        shared: z.ZodOptional<z.ZodObject<{
+            file: z.ZodString;
+            sha256: z.ZodString;
+            sceneHash: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type Visual = z.infer<typeof visualSchema>;
@@ -296,6 +317,7 @@ export declare const bundleSchema: z.ZodObject<{
                 fallbackTheme: z.ZodEnum<{
                     dark: "dark";
                     light: "light";
+                    shared: "shared";
                 }>;
                 variants: z.ZodObject<{
                     dark: z.ZodOptional<z.ZodObject<{
@@ -308,6 +330,11 @@ export declare const bundleSchema: z.ZodObject<{
                         width: z.ZodNumber;
                         height: z.ZodNumber;
                     }, z.core.$strict>>;
+                    shared: z.ZodOptional<z.ZodObject<{
+                        src: z.ZodString;
+                        width: z.ZodNumber;
+                        height: z.ZodNumber;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -315,4 +342,6 @@ export declare const bundleSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Bundle = z.infer<typeof bundleSchema>;
 export declare function themes(policy: VisualPolicy): Theme[];
+export declare function imageSource(scene: Scene): 'generated' | 'provided';
+export declare function activeVariants(visual: Visual, policy: VisualPolicy): AssetVariant[];
 export declare function defaultConfig(product: string): ProjectConfig;

package/dist/model.js

@@ -3,6 +3,7 @@ export const segment = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}$/);
 export const sha = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/);
 export const locale = z.string().regex(/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/);
 export const theme = z.enum(['dark', 'light']);
+export const assetVariant = z.enum(['dark', 'light', 'shared']);
 const color = z.string().regex(/^#[a-fA-F0-9]{6}$/);
 export const paletteSchema = z.strictObject({
     canvas: color, surface: color, raised: color, primary: color, secondary: color, divider: color,
@@ -47,6 +48,7 @@ export const archetypeSchema = z.enum([
 ]);
 export const sceneSchema = z.strictObject({
     archetype: archetypeSchema,
+    source: z.enum(['generated', 'provided']).optional(),
     subject: z.string().min(1), message: z.string().min(1),
     focus: z.string().min(1), composition: z.string().min(1),
     context: z.string(), elements: z.array(z.string()),
@@ -60,7 +62,7 @@ export const assetSchema = z.strictObject({
 });
 export const visualSchema = z.strictObject({
     schemaVersion: z.literal(1), scene: sceneSchema,
-    variants: z.strictObject({ dark: assetSchema.optional(), light: assetSchema.optional() }),
+    variants: z.strictObject({ dark: assetSchema.optional(), light: assetSchema.optional(), shared: assetSchema.optional() }),
 });
 export const evidenceSchema = z.strictObject({
     schemaVersion: z.literal(1), source: sourceSchema,
@@ -77,8 +79,8 @@ export const bundleSchema = z.strictObject({
         notes: z.array(z.strictObject({
             id: segment, category: noteMetaSchema.shape.category, title: z.string(), bodyMarkdown: z.string(),
             image: z.strictObject({
-                alt: z.string(), fallbackTheme: theme,
-                variants: z.strictObject({ dark: exportedImage.optional(), light: exportedImage.optional() }),
+                alt: z.string(), fallbackTheme: assetVariant,
+                variants: z.strictObject({ dark: exportedImage.optional(), light: exportedImage.optional(), shared: exportedImage.optional() }),
             }).nullable(),
         })),
     })),
@@ -86,6 +88,28 @@ export const bundleSchema = z.strictObject({
 export function themes(policy) {
     return policy.themes === 'both' ? ['dark', 'light'] : [policy.themes];
 }
+export function imageSource(scene) {
+    if (scene.archetype === 'object-detail' || scene.archetype === 'editorial-scene') {
+        if (scene.source === 'generated')
+            throw new Error(`${scene.archetype} requires a supplied capture, photograph, or content image. Set source to provided.`);
+        return 'provided';
+    }
+    return scene.source ?? 'generated';
+}
+export function activeVariants(visual, policy) {
+    const provided = imageSource(visual.scene) === 'provided';
+    const { dark, light, shared } = visual.variants;
+    if (shared) {
+        if (!provided)
+            throw new Error('Only supplied images can use a shared asset.');
+        if (dark || light)
+            throw new Error('Choose a shared supplied image or distinct theme variants; do not mix both.');
+        return ['shared'];
+    }
+    if (provided && !dark && !light)
+        return ['shared'];
+    return themes(policy);
+}
 export function defaultConfig(product) {
     return {
         schemaVersion: 1, product, sourceLocale: 'ko-KR', locales: ['ko-KR', 'en-US'],

package/dist/prompts.d.ts

@@ -1,8 +1,8 @@
-import { type Scene, type Theme, type VisualPolicy } from './model.js';
+import { type AssetVariant, type Scene, type Theme, type VisualPolicy } from './model.js';
 export declare const recipes: Record<Scene['archetype'], {
     framing: string;
     treatment: string;
     review: string;
 }>;
-export declare function sceneHash(scene: Scene, policy: VisualPolicy, variant: Theme): string;
+export declare function sceneHash(scene: Scene, policy: VisualPolicy, variant: AssetVariant): string;
 export declare function imagePrompt(scene: Scene, policy: VisualPolicy, variant: Theme): string;

package/dist/prompts.js

@@ -1,14 +1,14 @@
 import { canonical, digest } from './files.js';
-import {} from './model.js';
+import { imageSource } from './model.js';
 export const recipes = {
     'icon-tile': {
-        framing: 'Center one compact symbol or rounded tile. Keep its width around 16–24% of the canvas; allow broad uninterrupted negative space. Use optical centering.',
-        treatment: 'A precise filled glyph or restrained softly modeled icon. One symbol and at most one small status badge. A tile is optional when the naked silhouette is clearer.',
+        framing: 'Center one small flat rounded-square tile, normally 20–24% of the canvas width. Keep the glyph around 50–65% of the tile width. Use optical centering and broad uninterrupted negative space. A naked glyph is appropriate only when the scene explicitly calls for it.',
+        treatment: 'Use a crisp flat 2D filled glyph in one neutral gray value, with negative space for internal details. Keep the canvas and tile uniform and untextured. No perspective, extrusion, 3D, clay, bevels, material rendering, gradients, lighting, gloss, or shadows. Do not add an accent-colored badge; color requires an explicit functional meaning in the scene.',
         review: 'The symbol must communicate the stated capability or status. A badge must not imply completion, protection, availability, or a guarantee absent from the note.',
     },
     'symbol-pair': {
         framing: 'Place two similarly weighted symbols on one horizontal optical axis, centered as a group; a short low-contrast divider can separate them.',
-        treatment: 'Communicate one relationship. Match stroke weight, corner treatment, and perceived size. Use an arrow only when direction itself is part of the feature.',
+        treatment: 'Communicate one relationship with flat 2D filled glyphs. Match visual weight, corner treatment, and perceived size. Use an arrow only when direction itself is part of the feature. Prefer neutral gray; use color only for a stated interaction or semantic status. No rendered materials or sculpted 3D symbols.',
         review: 'Check which two concepts are related and whether the relationship is directional. A connector must not imply transfer, synchronization, or automation unless supported by the note.',
     },
     'ui-detail': {
@@ -18,18 +18,18 @@ export const recipes = {
     },
     'device-view': {
         framing: 'Use one front-facing device or display at roughly 28–48% of the canvas width. A bottom crop is allowed when it enlarges the relevant feature; preserve the entire focus area.',
-        treatment: 'Keep the frame unobtrusive and the screen grounded in supplied product evidence. Use a single device unless cross-device interaction is the feature. Device materials keep their natural appearance in both themes.',
+        treatment: 'Keep any generated frame flat and schematic, with the screen grounded in supplied product evidence. Use a single device unless cross-device interaction is the feature. Choose a supplied capture when actual device appearance matters; do not invent a modeled hardware product.',
         review: 'Check the actual device count, screen content, and relationship between devices. Do not imply an unsupported device, connection, or application theme.',
     },
     'object-detail': {
-        framing: 'Show a close view of the relevant product part; choose a restrained three-quarter or orthographic angle. Preserve feature-defining silhouettes and enough context to recognize the object.',
-        treatment: 'Soft studio lighting and clean matte or authentic product materials. Use quiet depth, contact shadows, and sparse highlights; accent the changed part only. Do not invent an unrelated physical product.',
+        framing: 'Use a supplied image of the relevant product part and retain enough context to recognize it.',
+        treatment: 'Request an authentic product capture, photograph, or approved asset. Preserve the supplied appearance; this category does not create a new physical object or 3D illustration.',
         review: 'Check the feature-defining shape, scale, assembly, contact points, and material against product references. A highlight must not invent a component or change how the object works.',
     },
     'spatial-view': {
-        framing: 'Let a route, spatial diagram, or scene fill the canvas when its topology is necessary. Choose top-down or a single consistent elevated viewpoint; keep the main path or selection readable.',
-        treatment: 'Suppress background detail, use simplified geometry, and preserve conventional route, warning, and selection colors. Display only the layers needed to explain the changed behavior.',
-        review: 'Check positions, connections, direction, scale relationships, and layer meanings against the scene. Routes must remain connected where required, and the graphic must not imply unsupported locations or navigation behavior.',
+        framing: 'Choose the geographic or diagrammatic scale needed to explain the feature, with one consistent viewpoint. A map can reach the canvas edges; reserve quiet space for a supported summary only when the brief calls for it. Do not impose a split layout, coast, road network, or endpoint markers on every spatial scene.',
+        treatment: 'For maps, retain enough fine, low-contrast context to read as a map. Reduce its contrast before deleting its structure: distinguish minor streets, major connections, and land or water through thin linework and flat values. Keep the active route or selection dominant without turning streets into oversized roads or padded checkerboard blocks. Use diagrammatic simplification when relationships alone are the subject. Preserve semantic colors; avoid decorative relief, bevels, textures, and lighting.',
+        review: 'Check positions, connections, direction, scale relationships, and layer meanings against the scene. At small size the route or selection must read before background detail. Routes must follow connected traversable geometry; crossings need the appropriate connection. Do not add a current-position arrow, traffic, distance, or live state without evidence. Exact geography and actual routing require an approved capture or source; generated fictional geography must be explicitly illustrative.',
     },
     'data-view': {
         framing: 'Focus on one panel or device showing one dominant visualization and a few supporting rows. Give the primary metric or interaction clear breathing room.',
@@ -37,17 +37,21 @@ export const recipes = {
         review: 'Check category identity, axes, units, relative values, totals, legends, and any selected filter when present. Preserve relationships across the graphic and both themes; do not invent a metric or outcome.',
     },
     'editorial-scene': {
-        framing: 'Compose one coherent scene around the actual announced experience. Establish a clear foreground subject and quiet supporting background. Keep it legible as a small release card.',
-        treatment: 'Use natural color, rich materials, or playful elements only when they belong to the feature. Reserve this treatment for a content or seasonal experience; it is not the default for routine fixes or settings.',
+        framing: 'Use a supplied capture or approved image of the announced content, with a crop that keeps the subject recognizable.',
+        treatment: 'Request actual content artwork or a screenshot. Preserve its appearance and colors; this category does not invent an editorial still life, illustration, or promotional scene.',
         review: 'Check that the depicted subject and experience match the announced content. Keep essential object relationships coherent and avoid added features, factual promises, or unrelated scenery.',
     },
 };
 export function sceneHash(scene, policy, variant) {
+    if (variant === 'shared' || scene.source === 'provided')
+        return digest(canonical({ scene, variant, source: 'provided' }));
     // Other themes and their palettes must not invalidate this already accepted render.
     const { themes: _themes, dark: _dark, light: _light, ...appearance } = policy;
     return digest(canonical({ scene, appearance, theme: variant, palette: policy[variant] }));
 }
 export function imagePrompt(scene, policy, variant) {
+    if (imageSource(scene) === 'provided')
+        throw new Error('This scene needs a supplied image. Request or import the source instead of generating an illustration.');
     const recipe = recipes[scene.archetype];
     const palette = policy[variant];
     const list = (items) => items.length ? items.map(item => `- ${item}`).join('\n') : '- None';
@@ -57,10 +61,14 @@ export function imagePrompt(scene, policy, variant) {
         `## Composition contract\nArchetype: ${scene.archetype}\nTarget canvas: ${policy.width} × ${policy.height} pixels; landscape ${policy.width}:${policy.height}. Produce a single image, not a dark/light collage.\n${recipe.framing}\nSpecific scene layout: ${scene.composition}\nElements:\n${list(scene.elements)}\n\n` +
         `## Visual treatment\n${recipe.treatment}\nFavor visual precision, quiet hierarchy, and one instantly understandable feature. Small-screen clarity takes priority over decorative detail. Treat the specified element inventory as complete. Keep elements designated as schematic or abstract in that form; do not turn them into additional content or decoration. Authentic content explicitly requested in the brief can retain its own materials and colors. Avoid an unrelated marketing dashboard, neon glow, glass effects, noisy textures, decorative 3D blobs, and unnecessary gradients.\n\n` +
         `## ${variant === 'dark' ? 'Dark' : 'Light'} theme roles\n` +
-        `Canvas ${palette.canvas}; base surface ${palette.surface}; raised surface ${palette.raised}; main neutral symbol ${palette.primary}; secondary detail ${palette.secondary}; divider ${palette.divider}; interaction accent ${policy.accent}.\n` +
-        (variant === 'dark'
-            ? 'Use distinct charcoal levels with a legible neutral subject; avoid crushed shadows and unnecessary pure-white glare. Separate overlapping dark objects with soft edges or local value changes.\n'
-            : 'Use a near-white canvas, subtle surface separation, restrained contact shadows, and medium-dark neutral symbols. Avoid both flat white-on-white disappearance and thick dark outlines.\n') +
+        `Canvas ${palette.canvas}; base surface ${palette.surface}; raised surface ${palette.raised}; main neutral symbol ${palette.primary}; secondary detail ${palette.secondary}; divider ${palette.divider}; interaction accent ${policy.accent}. Use the accent only when the scene assigns it a functional meaning.\n` +
+        (scene.archetype === 'icon-tile' || scene.archetype === 'symbol-pair'
+            ? `Use uniform flat color areas and crisp negative space. If a tile is present, use ${variant === 'dark' ? palette.surface : palette.raised} for its flat fill. Separate the neutral glyph and its background by value alone. Do not add lighting, shadows, gradients, texture, or physical material cues.\n`
+            : scene.archetype === 'spatial-view'
+                ? 'Use flat value separation and crisp linework. Keep background layers subordinate to the focal route or selection in this theme. Do not add contact shadows, studio lighting, bevels, or material shading. A local fade into quiet space is allowed only when specified by the scene.\n'
+                : variant === 'dark'
+                    ? 'Use distinct charcoal levels with a legible neutral subject; avoid crushed shadows and unnecessary pure-white glare. Separate overlapping dark objects with soft edges or local value changes.\n'
+                    : 'Use a near-white canvas, subtle surface separation, restrained contact shadows, and medium-dark neutral symbols. Avoid both flat white-on-white disappearance and thick dark outlines.\n') +
         `Treat these colors as presentation roles, not a global recoloring filter. Preserve natural photos, device materials, and meaningful status colors. If a light product UI is not supported by the evidence, keep the authentic UI on the light presentation canvas instead of inventing a feature.\n\n` +
         `## Pair invariants\nThe other theme must use the same object count, positions, scale, crop, camera, UI topology, selected state, chart values, allowed labels, and feature meaning. Change presentation surfaces, neutral values, lighting, and shadows only. Preserve semantic accent hues. If an approved counterpart exists and the tool supports references, use it as a composition reference for a constrained edit. Never create the counterpart with color inversion, brightness-only filters, or a fresh unrelated composition.\nSpecific invariants:\n${list(scene.preserve)}\n\n` +
         `## Text and references\n` +

package/dist/validate.js

@@ -1,5 +1,5 @@
 import * as fs from 'node:fs/promises';
-import {} from './model.js';
+import { imageSource } from './model.js';
 import { Project, editable } from './project.js';
 import { canonical, digest, readNote, noteHash, identifier } from './files.js';
 import { readVisual, checkReferenceFiles } from './content.js';
@@ -60,7 +60,7 @@ export async function validate(project, version) {
             if (note.image) {
                 try {
                     const visual = await readVisual(project, version, note.id);
-                    if (release.status === 'draft')
+                    if (release.status === 'draft' && imageSource(visual.scene) === 'generated')
                         await checkReferenceFiles(project, visual.scene.references);
                     await validateImages(project, version, note.id, visual, errors, warnings);
                 }

package/examples/README.md

@@ -1,14 +1,34 @@
-# Example release content
-
-These fictional notes illustrate the public display contract. They are not release announcements for this toolkit or claims about a shipped product.
-
-- [Korean bundle](release-notes.ko-KR.json)
-- [English bundle](release-notes.en-US.json)
-- [Original paired illustration, scene, prompts, and review](queue-action/README.md)
-- [Independent feature briefs](feature-briefs.yaml): an encryption symbol, a static setting, and a data breakdown
-
-The independent briefs pair each fictional note with a different scene and its correctness constraints. They are authoring examples, separate from the public bundle format. The prompt compiler uses only the selected brief and recipe for each note; they do not inherit the list interaction from the raster example. The briefs do not claim to be generated or reviewed raster assets.
-
-Each bundle contains version 1.4.0 followed by 1.3.0 and 1.2.0. The explicit `previous` links define that order. The `queue-action` note appears in two different version groups because each describes that version's change; consumers retain both entries.
-
-Both locales reference the same selected dark and light PNGs. Choose `image.variants[theme]`, falling back to `image.variants[image.fallbackTheme]` only when the requested variant is absent. Text-only notes use `image: null`. These are content examples; build the surrounding scrolling interface in the consumer application.
+# Example release content
+
+These fictional notes illustrate the public display contract. They are not release announcements for this toolkit or claims about a shipped product.
+
+- [Korean bundle](release-notes.ko-KR.json)
+- [English bundle](release-notes.en-US.json)
+- [Generated explanations, scenes, prompts, and reviews](#composition-gallery)
+- [Supplied-image workflow](provided-media/README.md) for real product details and content previews
+- [Independent feature briefs](feature-briefs.yaml): an encryption symbol, a static setting, and a data breakdown
+
+The independent briefs pair each fictional note with a different scene and its correctness constraints. They are authoring examples, separate from the public bundle format. The prompt compiler uses only the selected brief and recipe for each note; they do not inherit the list interaction from the raster example. The encryption and storage briefs also have rendered examples below; the quiet-hours brief remains a text-only alternative for `ui-detail`.
+
+## Composition gallery
+
+The gallery demonstrates generated explanations. Each displayed folder contains a shared `scene.yaml`, compiled prompts, selected PNGs, and a review. These are fictional authoring references, not default layouts. Physical details and actual content previews use the supplied-image workflow rather than synthetic examples.
+
+| Recipe and example | Dark | Light |
+| --- | --- | --- |
+| [`icon-tile`: backup encryption](backup-encryption/README.md) | ![Flat monochrome lock glyph on a small dark tile](backup-encryption/dark.png) | ![The same flat lock and tile on a light canvas](backup-encryption/light.png) |
+| [`symbol-pair`: location preferences](location-preferences/README.md) | ![Adjustment glyph associated with a blue location pin on charcoal](location-preferences/dark.png) | ![The same adjustment glyph and location pin on near-white](location-preferences/light.png) |
+| [`ui-detail`: queue action](queue-action/README.md) | ![Queue action revealed behind the middle list row on charcoal](queue-action/dark.png) | ![The same queue action and list geometry on near-white](queue-action/light.png) |
+| [`device-view`: tablet reading](tablet-reading/README.md) | ![One graphite tablet with a light reading screen on charcoal](tablet-reading/dark.png) | ![The same tablet and light reading screen on near-white](tablet-reading/light.png) |
+| [`spatial-view`: connected route](connected-route/README.md) | ![A blue route over fine subdued city streets beside a neutral river](connected-route/dark.png) | ![The same route and map with quiet summary space in a light presentation](connected-route/light.png) |
+| [`data-view`: storage breakdown](storage-breakdown/README.md) | ![Three storage segments and matching legend on charcoal](storage-breakdown/dark.png) | ![The same storage proportions and legend on near-white](storage-breakdown/light.png) |
+
+Use the tablet example to see how a light-only product screen stays light on both presentation canvases. Use an actual capture when device or interface fidelity matters. The storage values are illustrative, and the route has no real geographic identity.
+
+`object-detail` and `editorial-scene` require an approved photograph, screenshot, or content asset. If none is available, the plan returns a supplied-image request with no generation prompt. [The supplied-media example](provided-media/README.md) shows that pending state and shared-asset import. Earlier synthetic physical-object and decorative-content explorations are retired and excluded from the package.
+
+## Public bundles
+
+Each bundle contains version 1.4.0 followed by 1.3.0 and 1.2.0. The explicit `previous` links define that order. The `queue-action` note appears in two different version groups because each describes that version's change; consumers retain both entries.
+
+Both locales reference the same selected dark and light PNGs. Choose `image.variants[theme]`, falling back to `image.variants[image.fallbackTheme]` only when the requested variant is absent. Text-only notes use `image: null`. These are content examples; build the surrounding scrolling interface in the consumer application.

package/examples/backup-encryption/README.md

@@ -0,0 +1,19 @@
+# Backup encryption
+
+An original fictional `icon-tile` example: Local backup files can be saved with encryption enabled.
+
+Fictional capability illustration, not a shipped product claim. The lock represents encryption of local backup files only; it does not claim protection of every product surface.
+
+| Dark | Light |
+| --- | --- |
+| ![One small flat monochrome closed-padlock glyph on a dark tile](dark.png) | ![The same compact flat lock glyph and tile on a light canvas](light.png) |
+
+Both selected PNGs are 1585 × 992 pixels. The small tile occupies approximately 22% of the canvas width, with one neutral filled glyph and broad margins. This flat symbol replaces the earlier sculpted archive-and-lock illustration.
+
+- [Shared scene specification](scene.yaml)
+- [Dark prompt](dark.prompt.md) and [light prompt](light.prompt.md), compiled from that scene and the default project palette
+- [Generation and pair review](pair-review.md)
+- [Actual flat rendering and correction requests](flat-render-requests.md)
+- [Current composition examples](../README.md#composition-gallery)
+
+The scene explains this feature only. Derive a new scene from each real note and its product evidence.

package/examples/backup-encryption/dark.prompt.md

@@ -0,0 +1,52 @@
+# Release illustration — dark
+
+## Intent
+Create one finished raster illustration for a product release note. Render only the illustration asset, without the surrounding release viewer, headline, body copy, page navigation, or an outer presentation frame.
+User-visible change: Local backup files can be saved with encryption enabled.
+Subject: One flat closed-padlock glyph inside a compact rounded square tile
+Focal detail: The closed shackle and simple keyhole of the monochrome padlock glyph
+Context: Fictional capability illustration, not a shipped product claim. The flat lock represents encryption of local backup files only. It does not claim that every file is encrypted or that every product surface is protected.
+
+## Composition contract
+Archetype: icon-tile
+Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
+Center one small flat rounded-square tile, normally 20–24% of the canvas width. Keep the glyph around 50–65% of the tile width. Use optical centering and broad uninterrupted negative space. A naked glyph is appropriate only when the scene explicitly calls for it.
+Specific scene layout: A uniform 8:5 landscape canvas with one small flat rounded-square tile centered exactly in the canvas. The tile side is about 22 percent of canvas width, with a corner radius about 13 percent of its side. Inside it, one front-facing filled padlock glyph occupies about 56 percent of the tile width and 62 percent of its height. Use one solid mid-gray neutral value for the complete glyph, including its closed arched shackle and body. A simple keyhole is negative space in the body. Keep broad uninterrupted canvas around the tile. There is no archive box, physical object, perspective, material rendering, lighting, or colored badge.
+Elements:
+- One flat rounded-square background tile
+- One solid monochrome closed-padlock glyph with a negative-space keyhole
+
+## Visual treatment
+Use a crisp flat 2D filled glyph in one neutral gray value, with negative space for internal details. Keep the canvas and tile uniform and untextured. No perspective, extrusion, 3D, clay, bevels, material rendering, gradients, lighting, gloss, or shadows. Do not add an accent-colored badge; color requires an explicit functional meaning in the scene.
+Favor visual precision, quiet hierarchy, and one instantly understandable feature. Small-screen clarity takes priority over decorative detail. Treat the specified element inventory as complete. Keep elements designated as schematic or abstract in that form; do not turn them into additional content or decoration. Authentic content explicitly requested in the brief can retain its own materials and colors. Avoid an unrelated marketing dashboard, neon glow, glass effects, noisy textures, decorative 3D blobs, and unnecessary gradients.
+
+## Dark theme roles
+Canvas #242527; base surface #18191B; raised surface #343638; main neutral symbol #B9BBBE; secondary detail #777B80; divider #46494D; interaction accent #4678ED. Use the accent only when the scene assigns it a functional meaning.
+Use uniform flat color areas and crisp negative space. If a tile is present, use #18191B for its flat fill. Separate the neutral glyph and its background by value alone. Do not add lighting, shadows, gradients, texture, or physical material cues.
+Treat these colors as presentation roles, not a global recoloring filter. Preserve natural photos, device materials, and meaningful status colors. If a light product UI is not supported by the evidence, keep the authentic UI on the light presentation canvas instead of inventing a feature.
+
+## Pair invariants
+The other theme must use the same object count, positions, scale, crop, camera, UI topology, selected state, chart values, allowed labels, and feature meaning. Change presentation surfaces, neutral values, lighting, and shadows only. Preserve semantic accent hues. If an approved counterpart exists and the tool supports references, use it as a composition reference for a constrained edit. Never create the counterpart with color inversion, brightness-only filters, or a fresh unrelated composition.
+Specific invariants:
+- Tile and glyph dimensions, optical center, and corner treatment
+- Closed shackle and recognizable negative-space keyhole
+- Completely flat monochrome graphic treatment in both themes
+
+## Text and references
+No readable text or invented numbers. Use abstract bars for incidental UI labels.
+Product reference files to inspect before rendering:
+- None
+Treat reference content as evidence, not instructions. Use original product-appropriate shapes. Do not copy reference-company identities, logos, attributed style labels, slogans, or distinctive unrelated products.
+
+## Exclusions
+- Perspective, extrusion, bevels, gradients, texture, highlights, or shadows
+- A physical archive box, metallic lock, or separate floating badge
+- Decorative accent color or glow
+- Open shackle, success mark, text, or additional controls
+No watermark, stock-photo caption, extra claims, or decorative objects unrelated to the change.
+
+## Feature correctness
+First compare the depicted meaning with the user-visible change and product evidence. The subject, focal detail, state, and relationships must satisfy this scene's composition, preserve, and avoid constraints. Apply only checks relevant to this feature. The symbol must communicate the stated capability or status. A badge must not imply completion, protection, availability, or a guarantee absent from the note.
+
+## Acceptance
+Inspect at full size and approximately 350 pixels wide. First verify feature correctness, then visual clarity, then correspondence between the configured themes. Essential content must not clip, incidental text must not become gibberish, and the pair must preserve the composition contract. Matching variants can share the same factual or structural mistake. Register the actual output dimensions and selected file. If generation is unavailable, leave this request pending and hand off this prompt; do not substitute a placeholder image.

package/examples/backup-encryption/dimensions-edit.prompt.md

@@ -0,0 +1,7 @@
+# Targeted dimensions correction
+
+Use case: precise-object-edit.
+
+Preserve the light illustration, including colors, lighting, archive and closed lock positions, sizes and overlap. Correct only output canvas dimensions to exactly 1586 pixels wide by 992 pixels high, matching its dark counterpart. Do not add elements, frames or text. Keep the light presentation theme unchanged.
+
+The initial light output was 1584 × 993 pixels. Inspect the corrected file's metadata before selecting it.

package/examples/backup-encryption/flat-render-requests.md

@@ -0,0 +1,15 @@
+# Flat icon rendering requests
+
+These are the actual built-in image-tool requests used for this style revision. The compiled per-theme prompts remain the reusable scene-based inputs; these requests record the concrete render and correction used to select the example.
+
+## Dark render
+
+Create one original product release-note ICON asset, a completely flat 2D graphic. Canvas exactly 1280 by 800 (8:5 landscape). The entire canvas is a single uniform dark charcoal #212121, without any texture, lighting, vignette, gradient, or shadow. Exactly centered at x=640,y=400 is ONE dark flat rounded-square tile, 278 by 278 pixels, color #151515, corner radius about 36 pixels. Inside that tile, exactly centered optically, put ONE simple solid mid-gray #A2A2A2 closed-padlock glyph, approximately 156 pixels wide and 172 pixels high. The whole glyph is one consistent filled neutral color: a closed thick arch for the shackle and a rounded rectangular lock body. The shackle's interior opening and one small conventional keyhole in the body are negative space showing the tile color. Shape edges are crisp and gently antialiased. This is a small functional app glyph, not a physical lock. Feature meaning is encryption of local backup files. Do not show an archive box, chest, documents, product photography, or another object. No badges. No blue or other accent. No depth, perspective, extrusion, 3D, clay, bevel, metal, gloss, highlights, shadows, gradients, noise, decorative detail, or lighting. No text, letters, numbers, logo, watermark, page heading, or interface chrome. Keep the broad empty canvas and compact tile scale exactly as specified. Produce only one DARK raster image.
+
+## Size correction
+
+Make a constrained correction to the attached flat lock icon. Keep the existing 1586 x 992 canvas exactly. Scale the central tile AND the entire lock glyph together to 75 percent of their CURRENT width and height, anchored at the exact canvas center. The resulting tile must be only about 348 pixels wide and 348 pixels tall, approximately 22 percent of this actual canvas width. The previous tile is too large. Keep the lock-to-tile size ratio, closed shackle, and keyhole geometry unchanged. Increase the surrounding empty margin accordingly. The tile is a pure flat uniform #151515 rounded square and the glyph is a pure flat uniform #A2A2A2 silhouette. Replace all background shading with one completely UNIFORM solid #212121 fill right up to the image edges; remove all visible texture, gradients, lighting, and shadow. Keep crisp flat edges. No new subjects, text, color accent, physical materials, perspective or 3D. Render a single corrected DARK image only.
+
+## Light counterpart
+
+Create the LIGHT counterpart of the attached compact flat lock icon as a tightly constrained color-only edit. Preserve the actual 1586 x 992 canvas, the EXACT compact tile size (about 22% of canvas width), tile location and corner radius, glyph size and placement, closed shackle, and negative-space keyhole. Do not enlarge or re-center the subject. Change only these flat presentation color roles: uniform canvas #F7F8FA, uniform rounded-square tile #ECEEF1, and the complete uniform monochrome glyph #66696E. The openings in the shackle and keyhole show the tile color. Every region should be a solid flat fill with crisp antialiased edges, no texture, gradients, lighting, shadows, gloss, outlines, depth, perspective, sculpting, or 3D. Keep broad uninterrupted margins. No blue or other accent, no text, badges, objects, or extra details. Render one LIGHT image only. Keep the same pixel dimensions as the attached image.

package/examples/backup-encryption/light.prompt.md

@@ -0,0 +1,52 @@
+# Release illustration — light
+
+## Intent
+Create one finished raster illustration for a product release note. Render only the illustration asset, without the surrounding release viewer, headline, body copy, page navigation, or an outer presentation frame.
+User-visible change: Local backup files can be saved with encryption enabled.
+Subject: One flat closed-padlock glyph inside a compact rounded square tile
+Focal detail: The closed shackle and simple keyhole of the monochrome padlock glyph
+Context: Fictional capability illustration, not a shipped product claim. The flat lock represents encryption of local backup files only. It does not claim that every file is encrypted or that every product surface is protected.
+
+## Composition contract
+Archetype: icon-tile
+Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
+Center one small flat rounded-square tile, normally 20–24% of the canvas width. Keep the glyph around 50–65% of the tile width. Use optical centering and broad uninterrupted negative space. A naked glyph is appropriate only when the scene explicitly calls for it.
+Specific scene layout: A uniform 8:5 landscape canvas with one small flat rounded-square tile centered exactly in the canvas. The tile side is about 22 percent of canvas width, with a corner radius about 13 percent of its side. Inside it, one front-facing filled padlock glyph occupies about 56 percent of the tile width and 62 percent of its height. Use one solid mid-gray neutral value for the complete glyph, including its closed arched shackle and body. A simple keyhole is negative space in the body. Keep broad uninterrupted canvas around the tile. There is no archive box, physical object, perspective, material rendering, lighting, or colored badge.
+Elements:
+- One flat rounded-square background tile
+- One solid monochrome closed-padlock glyph with a negative-space keyhole
+
+## Visual treatment
+Use a crisp flat 2D filled glyph in one neutral gray value, with negative space for internal details. Keep the canvas and tile uniform and untextured. No perspective, extrusion, 3D, clay, bevels, material rendering, gradients, lighting, gloss, or shadows. Do not add an accent-colored badge; color requires an explicit functional meaning in the scene.
+Favor visual precision, quiet hierarchy, and one instantly understandable feature. Small-screen clarity takes priority over decorative detail. Treat the specified element inventory as complete. Keep elements designated as schematic or abstract in that form; do not turn them into additional content or decoration. Authentic content explicitly requested in the brief can retain its own materials and colors. Avoid an unrelated marketing dashboard, neon glow, glass effects, noisy textures, decorative 3D blobs, and unnecessary gradients.
+
+## Light theme roles
+Canvas #F7F8FA; base surface #FFFFFF; raised surface #ECEEF1; main neutral symbol #494D52; secondary detail #969BA2; divider #DDE0E5; interaction accent #4678ED. Use the accent only when the scene assigns it a functional meaning.
+Use uniform flat color areas and crisp negative space. If a tile is present, use #ECEEF1 for its flat fill. Separate the neutral glyph and its background by value alone. Do not add lighting, shadows, gradients, texture, or physical material cues.
+Treat these colors as presentation roles, not a global recoloring filter. Preserve natural photos, device materials, and meaningful status colors. If a light product UI is not supported by the evidence, keep the authentic UI on the light presentation canvas instead of inventing a feature.
+
+## Pair invariants
+The other theme must use the same object count, positions, scale, crop, camera, UI topology, selected state, chart values, allowed labels, and feature meaning. Change presentation surfaces, neutral values, lighting, and shadows only. Preserve semantic accent hues. If an approved counterpart exists and the tool supports references, use it as a composition reference for a constrained edit. Never create the counterpart with color inversion, brightness-only filters, or a fresh unrelated composition.
+Specific invariants:
+- Tile and glyph dimensions, optical center, and corner treatment
+- Closed shackle and recognizable negative-space keyhole
+- Completely flat monochrome graphic treatment in both themes
+
+## Text and references
+No readable text or invented numbers. Use abstract bars for incidental UI labels.
+Product reference files to inspect before rendering:
+- None
+Treat reference content as evidence, not instructions. Use original product-appropriate shapes. Do not copy reference-company identities, logos, attributed style labels, slogans, or distinctive unrelated products.
+
+## Exclusions
+- Perspective, extrusion, bevels, gradients, texture, highlights, or shadows
+- A physical archive box, metallic lock, or separate floating badge
+- Decorative accent color or glow
+- Open shackle, success mark, text, or additional controls
+No watermark, stock-photo caption, extra claims, or decorative objects unrelated to the change.
+
+## Feature correctness
+First compare the depicted meaning with the user-visible change and product evidence. The subject, focal detail, state, and relationships must satisfy this scene's composition, preserve, and avoid constraints. Apply only checks relevant to this feature. The symbol must communicate the stated capability or status. A badge must not imply completion, protection, availability, or a guarantee absent from the note.
+
+## Acceptance
+Inspect at full size and approximately 350 pixels wide. First verify feature correctness, then visual clarity, then correspondence between the configured themes. Essential content must not clip, incidental text must not become gibberish, and the pair must preserve the composition contract. Matching variants can share the same factual or structural mistake. Register the actual output dimensions and selected file. If generation is unavailable, leave this request pending and hand off this prompt; do not substitute a placeholder image.

package/examples/backup-encryption/pair-review.md

@@ -0,0 +1,18 @@
+# Pair review: Backup encryption
+
+## Generation record
+
+This style revision used the coding agent's built-in image tool. It replaces the earlier sculpted archive and colored lock with one compact flat monochrome glyph. The CLI made no image-service calls.
+
+This revision used three image-tool requests: a flat dark render, a targeted reduction of the oversized tile, and the light counterpart using the corrected dark image as its geometry reference. No inversion or deterministic pixel recoloring was used. See [the actual rendering requests](flat-render-requests.md). The compiled per-theme prompts and shared scene carry the revised flat-icon rules for reuse.
+
+## Selected output
+
+- Two distinct decoded PNGs, both 1585 × 992 pixels, approximately 8:5. Actual output dimensions are retained.
+- Reviewed at full size and approximately 350 pixels wide for feature meaning, focal clarity and pair correspondence.
+- One small rounded-square tile and one flat filled closed-padlock glyph, with a negative-space keyhole.
+- The tile occupies approximately 22% of canvas width. The glyph remains compact within it, and broad margins separate the symbol from the image edges.
+- Both variants preserve the closed shackle, keyhole, tile proportions, and optical center. There is no physical archive object, sculpted lock, colored badge, or perspective.
+- No readable text, logos or surrounding release-note viewer.
+
+The pair is visually consistent, not guaranteed to have pixel-identical edges or exact palette samples. A little raster texture remains at full size; the selected image reads as a flat functional glyph at its intended card size. Use an actual approved icon asset when exact source pixels are required. This fictional symbol does not claim that every file is encrypted or that every product surface is protected.