@iodes/releasekit 0.1.4 → 0.1.6

package/examples/queue-action/dark.prompt.md

@@ -11,23 +11,31 @@ Context: A fictional productivity interface used to demonstrate the illustration
 Archetype: ui-detail
 Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
 Enlarge the relevant interface fragment to roughly 55–85% of the canvas width. Keep the focal control inside a 6% safe margin. Supporting interface context may be deliberately cropped.
-Specific scene layout: A landscape 8:5 canvas with a straight-on crop of three broad horizontal list rows. Define a fixed list left boundary L at 17 percent of canvas width. The first and third resting row backgrounds start at L. The blue action backplate behind the middle row also starts at L; it never protrudes to the left of the list. Its exposed width D is about 13 percent of canvas width. Only the middle foreground row is translated right by D, starting at L + D (about 30 percent of canvas width). Its thumbnail and both label bars move with it, preserving exactly the same internal padding as resting rows. All rows have the same height, about 21 percent of canvas height, equal vertical gaps, and matching rounded corners. The row tops sit at about 14, 38, and 62 percent of canvas height. Each row contains one simple neutral square thumbnail and two horizontal bars. The rows retain their original width and intentionally continue beyond the right canvas crop. Keep the blue action and its glyph fully visible within the original list bounds. No phone or outer application frame.
+Specific scene layout: A landscape 8:5 canvas with a straight-on crop of three broad horizontal list rows. Define a fixed list left boundary L at 17 percent of canvas width. The first and third resting row backgrounds start at L. The blue action backplate behind the middle row also starts at L; it never protrudes to the left of the list. Its exposed width D is about 13 percent of canvas width. Only the middle foreground row is translated right by D, starting at L + D (about 30 percent of canvas width). Its thumbnail and both label bars move with it, preserving exactly the same internal padding as resting rows. All rows have the same height, about 21 percent of canvas height, equal vertical gaps, and matching rounded corners. The row tops sit at about 14, 38, and 62 percent of canvas height. Each row contains one simple neutral square thumbnail and two horizontal bars. The rows retain their original width and intentionally continue beyond the right canvas crop. Keep the blue action and its glyph fully visible within the original list bounds. Use canvas for the background, surface for every row, raised for every abstract thumbnail, and secondary for both incidental bars in every row. Use the project accent only for the exposed action; its reversed queue glyph uses the light surface value for legibility. Keep each assigned fill uniform, with no new gray tones or shadows. No phone or outer application frame.
 Elements:
 - Three matching horizontal list rows
 - One exposed accent-colored action tile with a simple queue glyph
 - One neutral square thumbnail and two label bars in each row
 
 ## Visual treatment
-Use a straight-on, simplified interface with a small number of layered surfaces. Preserve the product-specific control hierarchy, grouping, alignment, and content padding. Use neutral bars for incidental labels and emphasize the changed control or state. Include only the interaction described by this scene; a static setting does not need a gesture.
-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.
+Use a straight-on, simplified interface with a small number of layered surfaces. Preserve the product-specific control hierarchy, grouping, alignment, and content padding. Use neutral bars for incidental labels. Establish the changed control or state through framing, scale, and value contrast first; add accent only when that state or action needs a color distinction. Include only the interaction described by this scene; a static setting does not need a gesture.
+Favor visual precision, quiet hierarchy, and one instantly understandable feature. Build emphasis through composition, scale, and neutral value contrast before adding color. No accent is the default, and a fully neutral image is a finished result. Being new, important, or the focal subject does not itself justify color. 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.
+| Role | Color | Assignment |
+| --- | --- | --- |
+| canvas | #242527 | Uniform illustration background |
+| surface | #18191B | Base interface panels and resting rows |
+| raised | #343638 | Quiet icon tiles, inset areas, and abstract thumbnail fills |
+| primary | #B9BBBE | Main neutral glyphs and feature-defining marks |
+| secondary | #777B80 | Incidental label bars and supporting schematic details |
+| divider | #46494D | Thin separators and necessary surface boundaries |
+Use these configured roles consistently across the scene and release. Assign schematic elements to roles in the composition; repeated elements with the same role use the same fill. Keep flat areas uniform. Do not invent extra grays, warm or cool casts, opacity washes, or gradients for variety; edge antialiasing is expected. Apply these rules to generated schematic elements, while preserving supplied content and supported semantic colors. Optional project accent: #4678ED; this is available, not required. Use it only on the exact element whose supported state, action, or data meaning the scene says needs color. Otherwise use no accent. Keep unrelated glyphs, tiles, and supporting surfaces neutral; do not invent a colored state, badge, or marker to use the palette.
 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.
 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.
+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 whether accent is absent or present, its assigned elements, and its semantic hues. A neutral scene stays neutral in both themes. 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:
 - Exact row count, positions, dimensions, spacing, and crop
 - Shared left boundary of the two resting rows and the blue action backplate
@@ -55,4 +63,4 @@ No watermark, stock-photo caption, extra claims, or decorative objects unrelated
 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. Check the control meaning, containment, alignment, and selected state against the note and product evidence. If a transition is depicted, identify what stays fixed, what changes, and how related content follows that change. Use the actual interaction model specified in the scene.
 
 ## 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.
+Inspect at full size and approximately 350 pixels wide. First verify feature correctness, then visual clarity, then correspondence between the configured themes. Check neutral fills against their configured roles and compare their visual weight with other images in the release, especially in the light theme. File validation does not establish color consistency. Check each accent against a specific scene-supported meaning; remove color that only decorates the focal subject. 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/queue-action/light-palette-edit.prompt.md

@@ -0,0 +1,20 @@
+# Light palette edit request
+
+This is the actual built-in image-tool prompt for the light-palette revision. The edit target is the earlier `light.png`; the selected output is `light-soft.png`. The existing dark variant is retained. The compiled per-theme prompts remain the reusable inputs from the shared scene and project policy.
+
+Use case: precise-object-edit. Input image 1 is the existing LIGHT queue-interaction illustration and is the edit target. Keep the input canvas exactly 1586 by 992 pixels. Preserve every current row position, dimension, rounded corner, crop, thumbnail position, label-bar length and padding. The first and third rows and the middle blue action backplate retain one identical left boundary; only the middle foreground row is offset to the right by the exposed action width. Change only presentation fills according to the fixed neutral roles below. The entire background is #F8F8F8. Every row foreground is #FFFFFF. All three abstract thumbnail squares are #ECECEC. Every incidental label bar, both long and short in all rows, is the SAME uniform light supporting gray #B8B8B8; do not alternate arbitrary shades. Keep the one purposeful action backplate #4678ED and its existing queue glyph in the contrasting light surface color #FFFFFF. Preserve the exact queue glyph and its geometry. Remove invented shadows, material gradients, cloudy texture, and blue casts from the neutral surfaces; keep flat precise fills. Do not sharpen the image by making neutral bars charcoal or adding heavy outlines. Do not add new elements, text, symbols, watermarks, photographic thumbnail content, or UI. Produce one LIGHT raster image only, never a collage.
+
+Use this compiled palette guidance for the neutral role assignments:
+| Role | Color | Assignment |
+| --- | --- | --- |
+| canvas | #F8F8F8 | Uniform illustration background |
+| surface | #FFFFFF | Base interface panels and resting rows |
+| raised | #ECECEC | Quiet icon tiles, inset areas, and abstract thumbnail fills |
+| primary | #999999 | Main neutral glyphs and feature-defining marks |
+| secondary | #B8B8B8 | Incidental label bars and supporting schematic details |
+| divider | #D9D9D9 | Thin separators and necessary surface boundaries |
+Use these configured roles consistently across the scene and release. Assign schematic elements to roles in the composition; repeated elements with the same role use the same fill. Keep flat areas uniform. Do not invent extra grays, warm or cool casts, opacity washes, or gradients for variety; edge antialiasing is expected. Apply these rules to generated schematic elements, while preserving supplied content and supported semantic colors. Optional project accent: #4678ED; this is available, not required. Use it only on the exact element whose supported state, action, or data meaning the scene says needs color. Otherwise use no accent. Keep unrelated glyphs, tiles, and supporting surfaces neutral; do not invent a colored state, badge, or marker to use the palette.
+Keep a soft light presentation using the configured palette: primary glyphs use #999999; incidental label bars use the lighter secondary role #B8B8B8. Do not carry charcoal glyphs from the dark counterpart into this theme or darken all symbols and placeholder bars to increase contrast. Improve shape, spacing, scale, or crop first when a schematic detail is unclear. Respect explicit project palette overrides.
+Use the configured near-white canvas and light surfaces. Separate panels with the divider role only where needed. Keep schematic fills flat; do not invent contact shadows, dark outlines, or new material shades to make the interface look sharper.
+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.
+

package/examples/queue-action/light.prompt.md

@@ -11,23 +11,32 @@ Context: A fictional productivity interface used to demonstrate the illustration
 Archetype: ui-detail
 Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
 Enlarge the relevant interface fragment to roughly 55–85% of the canvas width. Keep the focal control inside a 6% safe margin. Supporting interface context may be deliberately cropped.
-Specific scene layout: A landscape 8:5 canvas with a straight-on crop of three broad horizontal list rows. Define a fixed list left boundary L at 17 percent of canvas width. The first and third resting row backgrounds start at L. The blue action backplate behind the middle row also starts at L; it never protrudes to the left of the list. Its exposed width D is about 13 percent of canvas width. Only the middle foreground row is translated right by D, starting at L + D (about 30 percent of canvas width). Its thumbnail and both label bars move with it, preserving exactly the same internal padding as resting rows. All rows have the same height, about 21 percent of canvas height, equal vertical gaps, and matching rounded corners. The row tops sit at about 14, 38, and 62 percent of canvas height. Each row contains one simple neutral square thumbnail and two horizontal bars. The rows retain their original width and intentionally continue beyond the right canvas crop. Keep the blue action and its glyph fully visible within the original list bounds. No phone or outer application frame.
+Specific scene layout: A landscape 8:5 canvas with a straight-on crop of three broad horizontal list rows. Define a fixed list left boundary L at 17 percent of canvas width. The first and third resting row backgrounds start at L. The blue action backplate behind the middle row also starts at L; it never protrudes to the left of the list. Its exposed width D is about 13 percent of canvas width. Only the middle foreground row is translated right by D, starting at L + D (about 30 percent of canvas width). Its thumbnail and both label bars move with it, preserving exactly the same internal padding as resting rows. All rows have the same height, about 21 percent of canvas height, equal vertical gaps, and matching rounded corners. The row tops sit at about 14, 38, and 62 percent of canvas height. Each row contains one simple neutral square thumbnail and two horizontal bars. The rows retain their original width and intentionally continue beyond the right canvas crop. Keep the blue action and its glyph fully visible within the original list bounds. Use canvas for the background, surface for every row, raised for every abstract thumbnail, and secondary for both incidental bars in every row. Use the project accent only for the exposed action; its reversed queue glyph uses the light surface value for legibility. Keep each assigned fill uniform, with no new gray tones or shadows. No phone or outer application frame.
 Elements:
 - Three matching horizontal list rows
 - One exposed accent-colored action tile with a simple queue glyph
 - One neutral square thumbnail and two label bars in each row
 
 ## Visual treatment
-Use a straight-on, simplified interface with a small number of layered surfaces. Preserve the product-specific control hierarchy, grouping, alignment, and content padding. Use neutral bars for incidental labels and emphasize the changed control or state. Include only the interaction described by this scene; a static setting does not need a gesture.
-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.
+Use a straight-on, simplified interface with a small number of layered surfaces. Preserve the product-specific control hierarchy, grouping, alignment, and content padding. Use neutral bars for incidental labels. Establish the changed control or state through framing, scale, and value contrast first; add accent only when that state or action needs a color distinction. Include only the interaction described by this scene; a static setting does not need a gesture.
+Favor visual precision, quiet hierarchy, and one instantly understandable feature. Build emphasis through composition, scale, and neutral value contrast before adding color. No accent is the default, and a fully neutral image is a finished result. Being new, important, or the focal subject does not itself justify color. 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 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.
+| Role | Color | Assignment |
+| --- | --- | --- |
+| canvas | #F8F8F8 | Uniform illustration background |
+| surface | #FFFFFF | Base interface panels and resting rows |
+| raised | #ECECEC | Quiet icon tiles, inset areas, and abstract thumbnail fills |
+| primary | #999999 | Main neutral glyphs and feature-defining marks |
+| secondary | #B8B8B8 | Incidental label bars and supporting schematic details |
+| divider | #D9D9D9 | Thin separators and necessary surface boundaries |
+Use these configured roles consistently across the scene and release. Assign schematic elements to roles in the composition; repeated elements with the same role use the same fill. Keep flat areas uniform. Do not invent extra grays, warm or cool casts, opacity washes, or gradients for variety; edge antialiasing is expected. Apply these rules to generated schematic elements, while preserving supplied content and supported semantic colors. Optional project accent: #4678ED; this is available, not required. Use it only on the exact element whose supported state, action, or data meaning the scene says needs color. Otherwise use no accent. Keep unrelated glyphs, tiles, and supporting surfaces neutral; do not invent a colored state, badge, or marker to use the palette.
+Keep a soft light presentation using the configured palette: primary glyphs use #999999; incidental label bars use the lighter secondary role #B8B8B8. Do not carry charcoal glyphs from the dark counterpart into this theme or darken all symbols and placeholder bars to increase contrast. Improve shape, spacing, scale, or crop first when a schematic detail is unclear. Respect explicit project palette overrides.
+Use the configured near-white canvas and light surfaces. Separate panels with the divider role only where needed. Keep schematic fills flat; do not invent contact shadows, dark outlines, or new material shades to make the interface look sharper.
 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.
+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 whether accent is absent or present, its assigned elements, and its semantic hues. A neutral scene stays neutral in both themes. 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:
 - Exact row count, positions, dimensions, spacing, and crop
 - Shared left boundary of the two resting rows and the blue action backplate
@@ -55,4 +64,4 @@ No watermark, stock-photo caption, extra claims, or decorative objects unrelated
 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. Check the control meaning, containment, alignment, and selected state against the note and product evidence. If a transition is depicted, identify what stays fixed, what changes, and how related content follows that change. Use the actual interaction model specified in the scene.
 
 ## 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.
+Inspect at full size and approximately 350 pixels wide. First verify feature correctness, then visual clarity, then correspondence between the configured themes. Check neutral fills against their configured roles and compare their visual weight with other images in the release, especially in the light theme. File validation does not establish color consistency. Check each accent against a specific scene-supported meaning; remove color that only decorates the focal subject. 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/queue-action/pair-review.md

@@ -9,17 +9,18 @@ This is an original fictional interface illustration generated with the coding a
 3. Create the light variant as a constrained edit of the accepted dark image, using the compiled light prompt. Preserve the canvas, row count, row geometry, middle-row offset, action glyph, neutral thumbnails, and bar lengths. Adapt only presentation surfaces, neutral values, and shadows while preserving the blue interaction accent.
 4. Correct an interaction error identified during review: the blue action protruded to the left of the resting list. Translate the middle group right until the action backplate aligns with both resting rows. This leaves only the foreground row displaced relative to the list. The [alignment edit prompt](alignment-edit.prompt.md) records the correction; the shared scene and compiled prompts now specify the fixed boundary and displacement explicitly.
 5. Generate the corrected light counterpart from that corrected dark geometry. Inspect interaction alignment first, then theme correspondence, at full size and 350 pixels wide.
+6. Revise the light palette with [this constrained edit](light-palette-edit.prompt.md). Assign every incidental bar to `secondary: #B8B8B8`, thumbnails to `raised: #ECECEC`, rows to `surface: #FFFFFF`, and the background to `canvas: #F8F8F8`. Keep the blue action and the existing interaction geometry. Select `light-soft.png` after full-size and 350-pixel review alongside the earlier version; spot-check its fills against the intended roles.
 
 The initial review checked theme correspondence but missed the incorrect list boundary. Two visually similar variants can share the same interaction mistake. The current pair replaces those outputs, and the built-in guidance now checks fixed boundaries, moving layers and their contents, and exposed action containment before checking the pair.
 
-This example has used five image-tool requests in total, including its two revision rounds. Two required assets do not guarantee only two billable generations. The CLI itself made no image-service requests.
+This example has used six image-tool requests in total, including the light-palette revision. Two required assets do not guarantee only two billable generations. The CLI itself made no image-service requests.
 
 ## Selected output
 
 | Check | Result |
 | --- | --- |
 | Actual dimensions | Both 1586 × 992 pixels, approximately 8:5 |
-| Encoding | Two distinct, fully decoded PNG files |
+| Encoding | Two distinct, fully decoded PNG files: `dark.png` and `light-soft.png` |
 | Subject | Three list rows with one action revealed behind the middle row |
 | Fixed alignment | The first row, blue action backplate, and third row share a left boundary at approximately 17% of canvas width |
 | Foreground displacement | Only the middle foreground and its contents start farther right, around 30% of canvas width; the exposed action fills the intervening space |
@@ -30,4 +31,4 @@ This example has used five image-tool requests in total, including its two revis
 | Full-size inspection | The deliberate right-edge row crop preserves the fully visible action tile |
 | 350-pixel-wide inspection | The aligned list edge, revealed action, rightward foreground offset, and three-row structure remain clear |
 
-The pair is visually consistent, not guaranteed to have pixel-identical edges. The light variant uses subtle shadows and surface separation; the dark variant keeps subdued layered surfaces. Review an actual product's imagery in its intended viewer before acceptance.
+The pair is visually consistent, not guaranteed to have pixel-identical edges. The light revision uses a consistent neutral hierarchy and quieter surface separation; the dark variant retains its accepted layered treatment. Raster fills remain approximate rather than exact palette swatches. Review an actual product's imagery in its intended viewer before acceptance.

package/examples/queue-action/scene.yaml

@@ -15,7 +15,11 @@ composition: >-
   height. Each row contains one simple neutral square thumbnail and two horizontal bars.
   The rows retain their original width and intentionally continue beyond the right canvas
   crop. Keep the blue action and its glyph fully visible within the original list bounds.
-  No phone or outer application frame.
+  Use canvas for the background, surface for every row, raised for every abstract
+  thumbnail, and secondary for both incidental bars in every row. Use the project
+  accent only for the exposed action; its reversed queue glyph uses the light
+  surface value for legibility. Keep each assigned fill uniform, with no new gray
+  tones or shadows. No phone or outer application frame.
 context: >-
   A fictional productivity interface used to demonstrate the illustration recipe.
   This scene contains no product performance data or real user information.

package/kit/references/common-images.md

@@ -0,0 +1,56 @@
+# Common images for minor changes
+
+Grouped minor changes reuse project-level originals across releases. Use this guide during `releasekit-image`, before generating a new illustration. Standalone features keep their own visual meaning, and explicit custom-image or text-only choices take precedence.
+
+| Common kind | Use for |
+| --- | --- |
+| `minor-fixes` | The grouped minor bug-fix note |
+| `minor-improvements` | The grouped minor improvement and convenience note |
+
+Select the kind from the note's editorial role under [Group minor changes](writing.md#group-minor-changes). A translated title, note ID, or `fix`/`improvement` category alone does not identify a minor group. Keep existing note IDs; do not add unsupported fields to release or visual metadata.
+
+## Store reviewed originals
+
+Store originals in `releasekit/common-images/<kind>/`, outside individual releases. Create a kind's directory when its first reviewed original is available. Each directory contains:
+
+- `visual.yaml`: the existing visual format (`schemaVersion`, `scene`, `variants`). Copy asset hashes, dimensions, and scene fingerprints from successful CLI imports. Here, each asset's `file` is relative to this common directory.
+- `policy.yaml`: the captured `release.yaml` `visuals` value used for the originals.
+- The selected raster files, named by variant and content, such as `dark.<hash>.png`. Use the actual format and hash suffix returned by import.
+
+These files are agent-maintained source records. The CLI does not discover or select common images automatically. Publish only reviewed files with matching metadata; an absent theme remains missing. A directory, prompt, or unfinished image is not a reusable original.
+
+Use a stable, generic scene for the kind, normally a compact neutral monochrome filled glyph on a quiet flat tile with broad margins. Generic fixes and improvements use no accent by default. Do not color the glyph or add a colored badge simply to announce maintenance; the note category is not a selected, active, or successful state. Keep release versions, titles, languages, bullet counts, individual fixes, and release-specific evidence out of the scene. The common scene must not depend on files belonging to its originating release. Do not imply a particular feature, a security guarantee, or that every possible bug is fixed. The note's text and evidence still describe that release's actual changes.
+
+## Reuse before generation
+
+1. Preserve the note's existing valid selections, including custom images and copies of an earlier common design. A newer common original does not replace them on a repeat run. Complete a partial illustration under its existing scene; a common counterpart is suitable only when it matches that scene and the selected image.
+2. For a new, unillustrated, or partially illustrated minor group, inspect its common `visual.yaml`, `policy.yaml`, and requested files. Verify the kind, published review status, file hashes, and actual dimensions against the record. Reuse prior visual review when the originals and their intended role are unchanged.
+3. For a new or unillustrated group without an explicit custom brief, adopt the common `scene`, keeping it independent of the current bullet list. Check compatibility with the release's captured policy. For generated originals, the common scene must match the target brief, and the requested canvas dimensions, preset, accent, and requested theme's palette must match the source policy. Enabling another theme or changing only the other palette does not invalidate a compatible original. Preserve `source: generated` for generated artwork; do not relabel it as supplied to bypass these checks. A genuine approved supplied image keeps `source: provided` and may use `shared` under the normal supplied-image rules.
+4. Import each compatible requested original with `releasekit image import`, using the file named by the common record. Do not copy the common `variants` paths into a release, use links to another release's assets, or point selected assets outside the release directory.
+5. Run `releasekit image plan <version>` after imports. Compatible imports are now ready; continue only with missing or unresolved assets. A generated source does not mean that an existing reviewed file must be generated again. Do not run image generation from an older plan after satisfying its request by import.
+
+The import command uses the current note's actual ID, which may differ from the common kind:
+
+```sh
+releasekit image import <version> <note> --theme <theme> --file releasekit/common-images/<kind>/<file>
+```
+
+Use only the release's configured themes. Reuse both members of an existing pair when both are required, or only the configured member for a single-theme release. A supplied `shared` original serves either theme without manufacturing a pair. Cross-release reuse and the `shared` theme slot are separate concepts.
+
+## Create only missing originals
+
+If no reviewed original exists for a needed kind or theme, first check already approved project images, including earlier minor-group illustrations. Promote a suitable generic image and its scene and policy to the common store when its meaning and appearance match. Do not use an unrelated earlier feature image solely because its category matches.
+
+If no suitable generated original is available, establish the generic scene once and follow the normal [generation sequence](theme-pairing.md#generation-sequence) for the missing configured themes. Keep an existing scene stable while completing its pair. Import a reviewed first variant into the current note so the planner can offer it as the composition reference for the counterpart. For a supplied scene, find or request the missing genuine input under [the supplied-image rules](media-sources.md#missing-input); do not generate its replacement.
+
+To publish an original, first import it successfully under the same scene and policy that will be saved in the common record. Copy the selected bytes unchanged into the common directory and record the matching metadata and captured policy. Preserve already reviewed compatible variants. A continuation of a custom or earlier design must not overwrite a different common design. If only one theme is complete, publish only that entry and keep the other pending. A later run reuses the completed theme and creates only the missing counterpart. Do not invert, duplicate, or freshly redraw an existing variant to satisfy a new release.
+
+When generation is unavailable or an original fails integrity or compatibility checks, keep the affected work pending. Do not silently regenerate an existing design, claim that it is ready, or substitute a placeholder. An appearance change already requested by the user follows the replacement procedure below without another confirmation.
+
+## Preserve release snapshots
+
+Import copies the original into the current release's managed assets and records its own hashes. Keep that scene and those selected files in the release. A bullet addition, wording change, or translation update alone is not a reason to rewrite the common scene, reimport current images, or generate another picture. Update text and localized alt text only where their meaning requires it. A change that no longer belongs to the minor group needs its own appropriate note and illustration.
+
+For an explicitly requested common-design change, prepare and review the replacement before updating the common source records. Keep the prior published originals until the replacement set is ready, and do not mix incompatible scenes or policies in one record. New or unillustrated notes then use the new original. Existing releases and already accepted draft images retain their saved copies unless their replacement was also requested; use the normal [replacement workflow](theme-pairing.md#replace-or-regenerate-an-image) for those notes.
+
+Common files are originals outside release asset cleanup. Removing a note must not remove them. Export continues to copy each release's selected snapshots into that release's asset directory in the bundle. This avoids repeated generation while keeping older releases independent of later changes to the common store; it does not deduplicate physical files across releases.

package/kit/references/composition-recipes.md

@@ -6,8 +6,8 @@ The rules below are conditional on the selected subject. Choose the [media sourc
 
 | Archetype | Use when | Starting composition | Common failure |
 | --- | --- | --- | --- |
-| `icon-tile` | A capability or status is recognizable through one symbol | Flat tile about 20–24% of canvas width; monochrome filled glyph about 50–65% of tile width | A sculpted 3D object, colored decorative badge, or oversized glyph |
-| `symbol-pair` | Two capabilities are connected | Two equally weighted symbols, a short subtle divider, broad empty space | Unequal weights or an arrow implying a direction that does not exist |
+| `icon-tile` | A capability or status is recognizable through one symbol | Flat tile about 20–24% of canvas width; neutral monochrome filled glyph about 50–65% of tile width | A sculpted 3D object, colored decorative badge, or oversized glyph |
+| `symbol-pair` | Two capabilities are connected | Two equally weighted neutral symbols, a short subtle divider, broad empty space | Coloring one symbol merely for emphasis, unequal weights, or an unsupported direction |
 | `ui-detail` | A specific interaction or setting changed | One enlarged fragment occupying about 55–85% of width | A complete invented dashboard with the useful control too small |
 | `device-view` | The device or cross-device context matters | One unobtrusive front-facing display, around 28–48% of width | Decorative device mockups unrelated to the workflow |
 | `object-detail` | A real physical part explains the feature | Supplied photograph or capture, with a useful crop | Inventing a physical product or generating a 3D substitute |
@@ -46,7 +46,7 @@ Message: a saved item can be added to a queue with one swipe.
 
 Choose `ui-detail`. Three broad horizontal list rows extend slightly past the right crop. Define the resting list left boundary as `L` and the exposed action width as `D`. The top and bottom row backgrounds and the middle row's action backplate all start at `L`. For this rightward swipe, only the middle foreground row starts at `L + D`; its thumbnail and label bars move with it and retain their original padding. The action occupies the space revealed inside the original row bounds. Its left edge must not protrude outside the resting list. Do not shift the entire list or compress the active row to make room.
 
-Represent incidental text as two or three neutral bars with consistent padding. Keep the action icon recognizable and the entire interaction inside the safe margin. This is a horizontal reveal gesture, not a vertical reorder drag: the rows keep their order and vertical positions. One interaction, one accent, no floating hand, arrow trail, extra feature, or surrounding app navigation.
+Represent incidental text as two or three neutral bars with consistent padding. Assign these bars to `secondary`, base rows to `surface`, and abstract thumbnails to `raised`. Keep repeated roles consistent; vary tone only for a hierarchy supported by the scene. Keep the action icon recognizable and the entire interaction inside the safe margin. This is a horizontal reveal gesture, not a vertical reorder drag: the rows keep their order and vertical positions. Keep one interaction. The exposed action may use accent if color helps distinguish it; neutral value contrast is also valid. Do not add a floating hand, arrow trail, extra feature, or surrounding app navigation.
 
 Before pairing, check that the resting rows and action backplate share a left boundary, the foreground displacement equals the revealed action width, and its contents moved as one unit. For the theme pair, lock row dimensions, offset, action width, bars, crop, and selected state. Change only canvas and surface roles, neutral label values, and local shadows. A second view that selects another row is a failed pair. Two matching images can still share the same interaction error, so correspondence alone is insufficient.
 

package/kit/references/format.md

@@ -1,6 +1,6 @@
 # Content contract
 
-Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases. New projects default to English originals (`sourceLocale: en-US`, `locales: [en-US]`). The agent suggests the user's current language as an optional translation and accepts additional languages; selected translations are added after the source in the release's `locales`.
+Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases. New projects default to English originals (`sourceLocale: en-US`, `locales: [en-US]`). On first use, the agent asks about optional translations only when language choices remain unresolved, then saves the selected source and translations in `releasekit/config.yaml` before preparation. Each new release copies the current project `sourceLocale`, `locales`, and visual policy. Later drafts use those configured languages without asking again, including a single-language choice. Previous releases' language selections do not override config. Explicit release-only language changes are saved in the affected `release.yaml`, preserving project defaults and other releases.
 
 Optional `history.start` in the project config records first-use setup: `ref` is the original commit/tag label, `sha` is its immutable commit, `past` is `summary`, `history`, or `skip`, and `version` is the baseline release ID for summary/history or null for skip. `releasekit start` saves this once before any release exists. It creates no content. Existing configs without this field retain the explicit-range workflow. See [first-use setup](adoption.md).
 
@@ -14,6 +14,10 @@ Within one release:
 | `prompts/<id>.<theme>.md` | Generation requests for pending generated variants; supplied images have no generation request |
 | `assets/` | Selected raster files with content-derived names |
 
+`visuals.dark` and `visuals.light` assign six neutral roles: `canvas` for the background, `surface` for base panels, `raised` for tiles and abstract thumbnails, `primary` for main glyphs, `secondary` for incidental bars and detail, and `divider` for thin boundaries. See the [role table](visual-language.md#assign-neutral-colors-by-role). Values are fixed per role within the captured theme policy; do not derive a separate palette for each note. Updating the toolkit does not overwrite existing project colors or release snapshots. To adopt new defaults in an existing project, edit `releasekit/config.yaml`; use `image plan --sync-config` to apply that project policy to a draft.
+
+`visuals.accent` makes a project color available for generated images; it does not require that color in every image. In the shared scene's `composition`, record no accent or the exact colored element and its supported state, action, or information meaning. Keep that assignment in `preserve`; neutral scenes remain neutral in both themes.
+
 Each `(version, note.id, variant)` has one selected image. Importing replaces the selected slot and then removes unused managed images belonging to this note, including obsolete shared or themed imports. Files referenced by any visual variant or scene in the project are retained, as are other notes' files and source originals outside the note's managed assets. Reimporting identical content reuses its file. Keep existing variant entries until the replacement import succeeds.
 
 Importing `--theme shared` replaces the note's dark/light entries with one shared entry. Importing `--theme dark` or `light` replaces a shared entry and keeps compatible themed entries. Optional `--source generated|provided` updates `scene.source` in the same save as the imported selection; omission preserves the current source. Shared imports require supplied media, and supplied-only subjects still reject generated media. The CLI validates the file before saving, so decoding or metadata-save failure preserves the previous source and selections. A missing configured counterpart stays pending after the first themed import and blocks finalization. See [image transitions](theme-pairing.md#switch-between-shared-and-themed-images).
@@ -30,6 +34,10 @@ The next release begins after the baseline SHA and links to its version with `pr
 
 Notes are ordered by their entries in `release.yaml`. Note IDs are unique within a version and shared across locales. Their consumer identity is the pair `(version, note.id)`; never deduplicate different releases by note ID or title alone.
 
+A grouped minor-change note uses the same contract: one note ID, category `fix` or `improvement`, a localized summary title, and an unordered Markdown list in the body. Its metadata carries the evidence paths or commits covering all bullets. Bullets have no separate note records or images; the group uses the normal image and translation policy and exports as one note with its list in `bodyMarkdown`. See [grouping guidance](writing.md#group-minor-changes) for selection and titles.
+
+Optional `releasekit/common-images/minor-fixes/` and `releasekit/common-images/minor-improvements/` hold reviewed project originals under [the common-image convention](common-images.md). Each contains a `visual.yaml` source record, a `policy.yaml` copy of the original visual policy, and its selected raster files. Common asset paths are relative to that source directory; the agent imports their files into each release and keeps selected release asset paths local. The CLI does not automatically discover these source records, and the existing release and bundle schemas stay the same.
+
 Frontmatter fields are `title`, `alt`, and `sourceHash`. The source locale normally uses `sourceHash: null`. Translation marking records a fingerprint of the source title, alt text, and body. An image-free note can use empty alt text. An image-enabled note requires a complete visual brief and its active image assets before finalization. Its scaffold leaves `archetype` and `source` unselected; the authoring agent chooses both from the note and product evidence.
 
 `scene.source` is `generated` or `provided`. Legacy briefs may omit it: `object-detail` and `editorial-scene` use supplied media; other categories default to generated graphics. Those two supplied-only categories reject an explicit `generated` choice. For generated media, `variants` contains the configured dark/light pair or single theme. Supplied media can contain just `shared`, or distinct dark/light entries following project policy. Do not mix shared and themed entries. The shared slot retains native dimensions and bytes, does not depend on presentation palettes, and exports as one asset with `fallbackTheme: shared`. Missing supplied inputs remain pending. See [media sources](media-sources.md).

package/kit/references/media-sources.md

@@ -13,6 +13,8 @@ Use `provided` for another category whenever a real capture explains it better.
 
 For a map, distinguish an illustrative spatial explanation from an actual place, computed route, or coverage claim. Exact geography and routing need an approved map capture or verified source. Request a supplied image when that evidence is missing. Generated fictional geography is suitable only when explicitly identified as illustrative; visual plausibility does not establish geographic accuracy.
 
+Grouped minor notes should first follow [common-image reuse](common-images.md). An already generated and reviewed original can be imported again with its generated source and matching theme policy; it does not need another generation or a change to `provided` merely because it is reused.
+
 ## Missing input
 
 `releasekit image plan <version>` returns `action: provide` with `promptFile: null` when supplied media is needed. The instruction identifies the subject and import slot. Reuse available approved project files first. Otherwise ask the user for the specific capture, photograph, or content image. Continue independent copy and translation work while the asset is pending. Do not treat a missing capture as permission to synthesize its content.

package/kit/references/theme-pairing.md

@@ -10,11 +10,13 @@ This generation policy does not require inventing a second appearance for suppli
 
 Policy is captured in each release when it is prepared. Editing the project default affects new releases. To apply the current project policy to an existing draft, run `releasekit image plan <version> --sync-config`. Previously selected files are retained; themes disabled by the new policy are not exported. Ready releases must be reopened before their policy changes.
 
+For a requested palette correction, change the relevant saved theme roles at the requested project or release scope before generating replacements. A project change belongs in `releasekit/config.yaml`; sync that policy into the target draft with `releasekit image plan <version> --sync-config`. A release-only change belongs in that draft's captured visual policy. Do not work around a saved dark glyph value by adding a one-off lighter color to a prompt. Regenerate and review the affected requested variants; preserve unchanged accepted counterparts. Palette changes are authoring policy changes, not a global filter over supplied images.
+
 ## Coverage and repeat runs
 
-The default image scope is every note in the saved release, including smaller fixes and improvements. Review the current `release.yaml` each time so newly added notes are included. A plain `releasekit-image` invocation uses this full scope without asking the user to pick important notes. Honor an explicitly limited request and the user's explicit text-only choices. If earlier agent prioritization disabled a note's image without such a choice, restore `image: true` and create or complete its visual brief in place, preserving its text, translations, and existing assets. Do not recreate the note. Missing supplied media stays pending instead of making the note text-only.
+The default image scope is every note in the saved release, including grouped minor fixes and improvements. A grouped note has one visual brief and the configured image variants; its bullets do not become separate notes or image requests. Use [common images](common-images.md) to reuse the appropriate original across releases before planning new generation. Review the current `release.yaml` each time so newly added notes are included. A plain `releasekit-image` invocation uses this full scope without asking the user to pick important notes. Honor an explicitly limited request and the user's explicit text-only choices. If earlier agent prioritization disabled a note's image without such a choice, restore `image: true` and create or complete its visual brief in place, preserving its text, translations, and existing assets. Do not recreate the note. Missing supplied media stays pending instead of making the note text-only.
 
-Before planning, complete missing or unfinished briefs for the image-enabled notes. Preserve existing scene specifications and the release's captured theme policy when they have not been changed by the user's request. Run `releasekit image plan <version>` from the current saved state, then handle the missing requests across all notes. Respect `action: generate` versus `action: provide` and the configured dark/light or shared variants.
+Before planning, complete missing or unfinished briefs for the image-enabled notes. Preserve existing scene specifications and the release's captured theme policy when they have not been changed by the user's request. Import compatible common originals first, then run `releasekit image plan <version>` from the current saved state and handle the remaining requests across all notes. Respect `action: generate` versus `action: provide` and the configured dark/light or shared variants.
 
 On repeat runs, generate or import only missing images and missing required variants. Reuse existing valid imports and their completed reviews; do not regenerate an accepted image merely because the skill was invoked again. This includes a run after the user adds notes: complete those notes' missing images while retaining earlier ones. If everything is already current, generate nothing and provide the image-review and finalization guidance.
 
@@ -22,28 +24,28 @@ An existing image reported as stale or invalid is unresolved, even though its fi
 
 ## One scene, two presentation treatments
 
-Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change presentation surfaces, neutral values, lighting, shadows, and necessary edge separation. Preserve meaningful status colors and natural photographic or material colors.
+Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change presentation surfaces, neutral values, lighting, shadows, and necessary edge separation. Preserve meaningful status colors and natural photographic or material colors. Lock the absence of accent for a neutral scene; when accent is justified, keep it on the same meaningful elements in both variants. A theme change does not introduce an accent.
 
 | Role | Dark treatment | Light treatment |
 | --- | --- | --- |
 | Canvas | Quiet charcoal | Quiet near-white |
 | Interface surface | Separate adjacent dark values | Separate white and pale-gray values |
-| Primary neutral symbol | Legible mid-light neutral | Legible mid-dark neutral |
-| Secondary detail | Subdued, still distinguishable | Subdued, still distinguishable |
-| Contact shadow | Soft, with enough local separation | Light, restrained, never muddy |
-| Interaction or status color | Preserve semantic hue | Preserve semantic hue |
+| Primary neutral symbol | Legible mid-light neutral | Medium gray from `primary`, without default charcoal fills |
+| Secondary detail | Subdued, still distinguishable | Lighter `secondary` for incidental bars and supporting detail |
+| Surface separation | Preserve only feature-relevant layers | Use surface roles and thin dividers; do not invent shadows |
+| Optional interaction or status color | Preserve assignment and semantic hue, or keep absent | Preserve assignment and semantic hue, or keep absent |
 | Photo or product material | Preserve authentic appearance | Preserve authentic appearance |
 
 Do not invert pixels or shift brightness globally. A black lens remains a black lens on a light canvas. A warning remains the same warning color. If the underlying application has only one authentic UI theme, retain that UI and adapt the surrounding presentation rather than claiming an unsupported application theme.
 
 ## Generation sequence
 
-1. Complete the shared brief and inspect its product references.
-2. Read the image plan and the project's requested themes. Reuse existing current assets. The following rendering steps apply to `action: generate`; handle `action: provide` through the supplied-image workflow.
+1. Complete the shared brief and inspect its product references. Map schematic groups to the [neutral color roles](visual-language.md#assign-neutral-colors-by-role); preserve those assignments across themes while using each theme's saved values.
+2. Read the current image plan and the project's requested themes. Reuse existing current assets and import any suitable [common originals](common-images.md), then refresh the plan. The following rendering steps apply to `action: generate`; handle `action: provide` through the supplied-image workflow.
 3. Generate one requested variant using its prompt. Select and inspect the result.
 4. Import it. Re-run the image plan; a valid approved counterpart is now offered as a composition reference for the other theme.
 5. When the available tool supports image references or edits, use the counterpart for a constrained theme edit. Otherwise repeat the exact scene contract and inspect for layout drift. Never claim pixel-identical geometry from independent stochastic generations.
-6. Compare the pair. Both files should have the same pixel dimensions. Verify pose, crop, UI state, values, and semantic colors by sight, then import the selected counterpart.
+6. Compare the pair and the other accepted images in the same theme. Check equivalent glyphs, label bars, and surfaces against the same configured color roles, without making light images as dark or contrast-heavy as dark-theme subjects. Both files should have the same pixel dimensions. Verify pose, crop, UI state, values, and semantic colors by sight, then import the selected counterpart.
 
 Use one file per theme, not a split canvas or a two-panel comparison image. Keep the current selection until a reviewed replacement is imported into the same slot. Do not restart the entire release when one small defect can be corrected locally.
 

package/kit/references/visual-language.md

@@ -10,7 +10,7 @@ Select the simplest useful archetype in [composition-recipes.md](composition-rec
 
 Choose [generated or supplied media](media-sources.md) before rendering. Generate restrained flat explanations; use actual captures, photographs, or approved artwork when the appearance itself is the subject. Physical details and content previews require supplied images. A missing source stays pending; a fictional written scene is not a replacement for an actual product or content capture.
 
-For each note, derive the scene from that feature independently. Describe the relevant state and relationships: a control's state, two capabilities' association, a physical assembly, spatial connections, data proportions, or the announced content. Record supported facts and limits in `context`; write concrete correctness constraints in `composition`, `preserve`, and `avoid`. Those constraints are local to the note. A worked example supplies a reasoning pattern, not a layout to apply to other features. The agent chooses the representation and reviews its meaning; the CLI compiles the chosen brief and validates files.
+For each standalone note, derive the scene from that feature independently. Grouped minor notes follow [common-image reuse](common-images.md), keeping one generic scene per kind across releases and languages instead of deriving a new scene from each bullet list. Describe the relevant state and relationships: a control's state, two capabilities' association, a physical assembly, spatial connections, data proportions, or the announced content. Record supported facts and limits in `context`; write concrete correctness constraints in `composition`, `preserve`, and `avoid`. Those constraints are local to the note. A worked example supplies a reasoning pattern, not a layout to apply to other features. The agent chooses the representation and reviews its meaning; the CLI compiles the chosen brief and validates files.
 
 ## Composition grammar
 
@@ -29,17 +29,42 @@ For each note, derive the scene from that feature independently. Describe the re
 
 Separate the canvas, base surface, raised surface, primary symbol, secondary detail, and divider. These are semantic roles, not a global color filter. The project defines their dark and light values.
 
-On dark backgrounds, distinguish charcoal layers and use mid-light neutral symbols. Do not crush a dark object into the canvas or turn every small glyph pure white. On light backgrounds, use near-white space, subtle gray separation, and darker neutral symbols. A dark device or natural photo may stay dark in a light presentation.
+On dark backgrounds, distinguish charcoal layers and use mid-light neutral symbols. Do not crush a dark object into the canvas or turn every small glyph pure white. On light backgrounds, use near-white space, subtle gray separation, and medium-gray symbols with lighter supporting details. Do not use charcoal glyphs or dark placeholder bars by default. A dark device or natural photo may stay dark in a light presentation.
 
-For icons, use a compact flat rounded-square tile with a monochrome filled glyph and clear negative space. A typical tile occupies 20–24% of the canvas width, with the glyph around 50–65% of the tile width. Keep broad margins, uniform background fills, and related corner radii. Use color only when the feature gives it a functional meaning. Do not default to a colored badge, physical object, or modeled icon.
+For icons, use a compact flat rounded-square tile with a neutral monochrome filled glyph and clear negative space. A typical tile occupies 20–24% of the canvas width, with the glyph around 50–65% of the tile width. Keep broad margins, uniform background fills, and related corner radii. Use color only when the feature gives it a functional meaning. Do not default to a colored badge, physical object, or modeled icon.
 
 Flat icons and symbol pairs have no perspective, extrusion, material texture, gradients, lighting, or shadows. Simplified interfaces may use restrained layer separation where it explains the actual control hierarchy. Preserve shading already present in supplied media. Do not add sculpted objects, decorative 3D, studio lighting, glass, glow, or bevels to generated release illustrations.
 
+## Assign neutral colors by role
+
+Use the release's captured palette as the source of truth. The default light palette deliberately uses a narrow neutral hierarchy:
+
+| Role | Default light value | Assignment |
+| --- | --- | --- |
+| `canvas` | `#F8F8F8` | Uniform background |
+| `surface` | `#FFFFFF` | Base panels and resting rows |
+| `raised` | `#ECECEC` | Quiet tiles, inset areas, and abstract thumbnails |
+| `primary` | `#999999` | Main glyphs and feature-defining marks |
+| `secondary` | `#B8B8B8` | Incidental label bars and supporting detail |
+| `divider` | `#D9D9D9` | Thin separators and necessary boundaries |
+
+Map visible schematic groups to these roles in `composition`; do not choose a fresh gray for each object or each image. Equivalent label bars share `secondary`; a second tone needs an actual hierarchy in the feature. Use the configured values, including explicit project overrides, instead of copying hex values from a worked example. Keep uniform flat fills without arbitrary warm or cool casts, opacity washes, gradients, or invented shading. Antialiased edges can contain intermediate pixels.
+
+Light illustrations explain shapes and relationships without the contrast of a text document. If something is unclear at card size, improve silhouette, spacing, stroke width, scale, or crop first. Do not globally darken glyphs and placeholder bars or introduce shadows to make every element sharper. Preserve authentic dark hardware, supplied UI, content colors, and justified semantic colors; the neutral role map applies to generated schematic elements.
+
+Review same-role objects across the release's light images together, not only each dark/light pair. A successful decode and matching dimensions do not validate the palette or visual weight.
+
 ## Color has a job
 
-Use the project accent for the changed control, selected item, active route, or direct interaction cue. Do not color every surface. Preserve established meanings such as warnings, completed states, traffic or map semantics, and authentic content colors between themes.
+Start with a fully neutral composition. Establish the focal point through placement, scale, shape, spacing, and value contrast. An image can be complete without any accent, and a release can contain many entirely neutral images. A new feature, an important capability, or the main subject does not by itself represent an active or selected state.
+
+Treat the project accent as an available color, not an instruction to use it. Add it only when a specific supported state, action, or information distinction needs color to explain the change: for example, an enabled switch, a selected item, a revealed action, or an active route. Even an interaction can remain neutral when its geometry and value contrast already make it clear. Keep the colored area confined to that meaningful element; leave unrelated glyphs, tiles, and supporting surfaces neutral.
+
+In the shared scene's `composition`, explicitly state either that no accent is used or which element uses it and what it communicates. Preserve that assignment, including the absence of accent, in both themes. Do not invent a selection, badge, status dot, or secondary marker to justify color. For `icon-tile`, ordinary capability and maintenance symbols stay neutral. For `symbol-pair`, a simple association uses the same neutral treatment for both symbols.
+
+Preserve established meanings such as warnings, completed states, traffic or map semantics, chart categories, and authentic content colors between themes. These colors belong to supported information; a generic improvement or security note is not itself a success or protection status.
 
-Limited color is a default for interface explanation, not a prohibition on colorful features. A supplied capture of a creative tool can retain its colorful output. A spatial view can require several functional colors. Actual content artwork retains its original appearance. The color should belong to the feature, rather than decorate a routine release card.
+Functional color remains available for colorful features. A supplied capture of a creative tool can retain its colorful output. A spatial view can require several functional colors. Actual content artwork retains its original appearance. The color should belong to the feature, rather than decorate a routine release card.
 
 ## Language independence
 
@@ -68,6 +93,6 @@ Make the brief concrete enough that another model can render the same scene. “
 
 ## Review the actual output
 
-Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. Attractive styling and theme similarity do not establish factual or structural correctness.
+Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. For each accent, identify the supported meaning that would become less clear without it; if there is none, remove it. Review the release images together for repeated decorative accents. Do not give every note one colored point or enforce a fixed quota of colored images. Attractive styling and theme similarity do not establish factual or structural correctness.
 
 For a pair, compare both outputs side by side using [theme-pairing.md](theme-pairing.md). Automated checks establish file integrity, dimensions, configured variants, and scene freshness; they do not prove visual correspondence or truthfulness. Correct a specific defect with a targeted edit instead of randomly regenerating every asset. Preserve unrelated accepted assets. Import a reviewed replacement into the same note and theme slot so unused older managed files are removed; keep the previous selection until that import succeeds.

package/kit/references/workflow.md

@@ -6,12 +6,12 @@ Use the installed `releasekit` CLI, or the repository's compiled CLI when develo
 
 The normal skill flow is `releasekit-draft` (source and selected translations), `releasekit-image` (required assets), then `releasekit-finalize` (review, validation, and local confirmation). Translation-only edits also belong to `releasekit-draft`. Skip image work for a release the user explicitly chose to keep text-only; export follows finalization only when requested.
 
-1. Read `releasekit/config.yaml` and any existing `release.yaml`. [Choose languages](#choose-languages) with the user before preparing or writing the draft. Honor the theme policy and product context.
+1. Read `releasekit/config.yaml` and any existing `release.yaml`. [Resolve languages](#choose-languages) from current project settings for a new draft or the saved selection for an existing draft. Ask only when a first-use choice or requested language change remains unresolved. Save the first-use selection in project config before preparation. Honor the theme policy and product context.
 2. For a new release, [resolve the version and Git boundaries from the repository](#resolve-release-scope-from-the-repository). Reuse explicit choices and saved boundaries, inspect the relevant release line, and supply the CLI arguments yourself. Briefly state the selected scope and continue when the evidence is clear. For first-use requests with unresolved earlier-history scope, follow [the adoption guide](adoption.md) to summarize, analyze, or skip the period through the baseline.
 3. Run `releasekit prepare`. It creates only `release.yaml`, including the pinned comparison start and end SHAs. Inspect the pinned Git evidence as described below: baseline summaries read the snapshot; other drafts read history, changed paths, and relevant diffs. Do not save a full patch or a separate changed-file index.
-4. Save the selected `sourceLocale` and `locales` in this release before adding notes with `releasekit note add <version> <id>`. Fill the source Markdown and attach evidence paths or commit SHAs to `release.yaml`, using snapshot evidence for a baseline summary. Keep every note image-enabled by default; use `--no-image` only for the user's explicit text-only choice, never to select just the important notes.
+4. Save the selected `sourceLocale` and `locales` in this release. Use [Group minor changes](writing.md#group-minor-changes) to select standalone notes and separate minor-fix and minor-improvement groups before adding notes with `releasekit note add <version> <id>`. Give each group the corresponding `--category fix` or `--category improvement`; its bullet items do not get separate notes. Fill the source Markdown and attach evidence paths or commit SHAs to `release.yaml`, using snapshot evidence for a baseline summary. Keep every note image-enabled by default; use `--no-image` only for the user's explicit text-only choice, never to select just the important notes.
 5. As part of `releasekit-draft`, [translate the selected locales](#translate-selected-locales) and mark reviewed translations current. Finish the source and selected translations before recommending image work, unless the user explicitly limited the draft scope.
-6. Use `releasekit-image` to cover all current drafted notes, including later additions, under [the coverage policy](theme-pairing.md#coverage-and-repeat-runs). Choose generated or supplied media and complete each missing visual brief, reusing existing valid images on repeat runs. Run `releasekit image plan`, then handle each request by its action: generate configured variants for `generate`, or find/request an approved capture/image for `provide`. Review and import selected files, using one shared supplied asset when appropriate. Preserve unrelated accepted images and manual edits. For a replacement or regeneration, import into the same note with the intended theme; follow [image transitions](theme-pairing.md#switch-between-shared-and-themed-images) when changing shared/themed usage. Unused managed files are removed after the new selection is saved.
+6. Use `releasekit-image` to cover all current drafted notes, including later additions, under [the coverage policy](theme-pairing.md#coverage-and-repeat-runs). For minor groups, [reuse common originals](common-images.md) before generating new images. Choose generated or supplied media and complete each missing visual brief, reusing existing valid images on repeat runs. Run `releasekit image plan`, then handle each request by its action: generate configured variants for `generate`, or find/request an approved capture/image for `provide`. Review and import selected files, using one shared supplied asset when appropriate. Preserve unrelated accepted images and manual edits. For a replacement or regeneration, import into the same note with the intended theme; follow [image transitions](theme-pairing.md#switch-between-shared-and-themed-images) when changing shared/themed usage. Unused managed files are removed after the new selection is saved.
 7. Use `releasekit-finalize` to review factual and visual accuracy, run `releasekit validate <version>`, resolve errors and review warnings, then run `releasekit finalize <version>`. Confirm `status: ready` and a recorded content fingerprint. Review is part of finalization; a validation report alone does not complete this step.
 8. If requested, run `releasekit export --out <directory>` to export recent history to a new output directory. Omit `--current` to use the unique release with no successor in the saved `previous` links; pass an explicitly requested version or resolve multiple release endpoints with `--current <version>`. Omit `--limit` to use project `history.limit` (initially 3). Omit `--locale` to export all locales saved in the current release as separate `release-notes.<locale>.json` files sharing one `assets/` directory; pass it only when the user requests a specific output language. Every selected version must contain those locales. A finalized release is a complete local result even without an export. Finalization does not tag, commit, push, deploy, or publish anything.
 
@@ -22,7 +22,8 @@ For an existing draft, read and edit the existing content. `prepare` never overw
 Use the user's requested feature or wording to identify the affected notes in the saved release. Keep its pinned Git boundaries and other releases unchanged. The user can ask for copy changes, exclude a feature, or include a feature that the draft missed without invoking a skill manually.
 
 - For wording changes, edit the existing source and refresh affected translations. If only part of a note is excluded, revise that note and its visual brief as needed.
-- To include an omitted feature, verify it against the pinned evidence. Extend an existing note when the feature belongs there; otherwise run `releasekit note add <version> <id>` and write its source, selected translations, and evidence. New notes are image-enabled by default; use `--no-image` only when the user explicitly asks for text-only content. Keep required images pending so the next `releasekit-image` run picks up the new note. Explain a requested feature outside the saved scope instead of silently expanding the Git range.
+- To consolidate minor notes, follow [the grouping guidance](writing.md#group-minor-changes). Reuse the release's existing group or add one with `--category fix` or `--category improvement`. Save the supported content, manual edits, and combined evidence in the group, and preserve coverage in every selected locale before removing the superseded notes with the CLI as described below. Refresh affected translations and fingerprints, and review the group's visual brief and alt text if its scope changed. A change only to the minor bullet list preserves the generic common scene and current images; follow [common-image reuse](common-images.md). Leave unrelated notes and other releases intact.
+- To include an omitted feature, verify it against the pinned evidence. For a minor change, reuse its group or create one with the appropriate `--category fix` or `--category improvement`. For a change that warrants individual attention, extend a related standalone note or run `releasekit note add <version> <id>`. Write or update the affected source, selected translations, and evidence. New notes are image-enabled by default; use `--no-image` only when the user explicitly asks for text-only content. Keep required images pending so the next `releasekit-image` run picks up the new note. Explain a requested feature outside the saved scope instead of silently expanding the Git range.
 - To exclude an entire note, run `releasekit note remove <version> <id>`. Let the CLI remove its metadata entry, complete note folder, visual brief, generated prompts, and unused managed images. Removing only the `release.yaml` entry leaves files behind. The command preserves assets referenced by remaining visuals, including other releases, and source originals outside managed assets; report any retained shared assets. If another scene references the note's text, brief, or prompts, resolve that dependency before removal.
 
 After additions or removals, validate the release and report outstanding copy, translation, or image work. The CLI clears a previous `emptyReason` when adding a note. Removing the last note leaves an editable empty draft; add another note or write a factual `emptyReason` before finalization. Do not invent a reason to hide an unfinished draft. A failed metadata save restores removed files or rolls back newly added note files.
@@ -42,17 +43,17 @@ Ask only when inspection leaves materially different scopes, such as competing p
 
 ## Choose languages
 
-Use English (`en-US`) as the default original language for new releases. Honor an explicitly chosen source language or intentional project setting, and preserve an existing release's saved source and language selection. Do not treat an older generated Korean-original/English-translation default as a confirmed preference. The user's conversation language suggests a translation target; it does not change the original language.
+For every new draft, use the current `sourceLocale` and complete ordered `locales` list from `releasekit/config.yaml`. Once the project has saved releases, proceed without a language picker, alternative language suggestions, or confirmation, including when config selects only one language. Previous releases supply history boundaries; their language lists do not override current project settings. The conversation language does not change configured languages. For an existing draft, reuse its saved selection unless the user explicitly requests a change.
 
-When translation languages have not been chosen, ask one concise question in the user's language using the [native question UI](#ask-with-the-native-question-ui) when available. State the original language as English by default and ask which additional translations, if any, to include. Suggest the user's current language first, using an explicit language preference when available and otherwise the current conversation. Do not detect or persist translation languages from the CLI host's operating-system locale.
+Only on first use with no saved releases, honor explicit language choices and intentional project settings first. If translations remain unchosen, ask one concise question in the user's language using the [native question UI](#ask-with-the-native-question-ui) when available. Use English (`en-US`) as the default original and ask which additional translations, if any, to include. Suggest the user's current language first, using an explicit language preference when available and otherwise the current conversation; it does not change the original language. Do not detect or persist translation languages from the CLI host's operating-system locale.
 
-For a Korean-speaking user, recommend English original with Korean translation, and offer English only as an alternative. Explicitly invite the user to enter additional languages, for example Korean, Japanese, and German together, using the tool's built-in free-text input. Accept language names or locale codes and keep that input available; do not duplicate a built-in Other option or assume multi-select support. Each option should describe a complete translation set. If the user's language is the same as the source, recommend the source alone and invite other translations without proposing a duplicate; regional variants require an explicit request. If the current language cannot be inferred, ask for optional translation languages without inventing a recommendation.
+For that first-use question with a Korean-speaking user and the default English source, recommend English original with Korean translation, and offer English only as an alternative. Explicitly invite the user to enter additional languages, for example Korean, Japanese, and German together, using the tool's built-in free-text input. Accept language names or locale codes and keep that input available; do not duplicate a built-in Other option or assume multi-select support. Each option should describe a complete translation set. If the user's language is the same as the source, recommend the source alone and invite other translations without proposing a duplicate; regional variants require an explicit request. If the current language cannot be inferred, ask for optional translation languages without inventing a recommendation.
 
-Reuse choices already specified for this release, including an explicit request to use configured languages or no translations. A language list supplied in answer to the translation question adds translation targets while retaining the source; do not ask which is the original merely because several languages were entered. An explicit request to write only in one language sets that source with no translations, and an explicit source-language change takes precedence over the English default. Ask only for an unresolved choice. While a necessary translation answer is pending, follow [the answer-waiting procedure](#wait-for-the-users-answer) before preparing the release, scaffolding notes, or writing copy; independent Git inspection may continue. A preselected option or an unanswered prompt does not confirm translations.
+An explicit language-change request takes precedence over the configured or saved selection. Reuse choices already specified for this release, including an explicit request to use configured languages or no translations. A language list supplied in answer to the translation question adds translation targets while retaining the source; do not ask which is the original merely because several languages were entered. An explicit request to write only in one language sets that source with no translations, and an explicit source-language change takes precedence over the English default. Ask only for an unresolved choice. While a necessary translation answer is pending, follow [the answer-waiting procedure](#wait-for-the-users-answer) before preparing the release, scaffolding notes, or writing copy; independent Git inspection may continue. A preselected option or an unanswered prompt does not confirm translations.
 
-Use locale codes such as `en-US`, `ko-KR`, and `ja-JP` in the files. New project configuration starts with `sourceLocale: en-US` and `locales: [en-US]`; translation suggestions are not enabled until selected. Set `sourceLocale` to the original language and `locales` to the unique list containing that source first plus all selected translations. A single-language release has only its source in `locales`. `prepare` copies project defaults, so update `releasekit/releases/<version>/release.yaml` with the confirmed selection immediately afterward and before `note add`. Change `releasekit/config.yaml` only when the user asks to change future project defaults.
+Use locale codes such as `en-US`, `ko-KR`, and `ja-JP` in the files. New project configuration starts with `sourceLocale: en-US` and `locales: [en-US]`; translation suggestions are not enabled until selected. Save the first-use choice directly in `releasekit/config.yaml`: set `sourceLocale` to the original language and `locales` to the unique list containing that source first plus all selected translations. A single-language choice saves only its source in `locales`. Preserve unrelated config fields. This choice establishes project defaults without another confirmation; write it before `prepare`, which copies the current project languages into `releasekit/releases/<version>/release.yaml`. If the first draft already exists, save the choice in both config and that draft before `note add`. Later new drafts follow current config automatically, including after a requested project language change. Save an explicitly release-only override in the affected `release.yaml` before scaffolding notes, preserving project defaults.
 
-For an existing draft, apply a changed selection in place. Create missing `notes/<id>/<locale>.md` files for each existing note using the [content contract](format.md), preserving existing copy and files for deselected languages. If the source language changes, review the new source and all selected translations, then mark reviewed translations against the new source. Keep the change scoped to this release.
+For an existing draft, apply a changed selection in place. Create missing `notes/<id>/<locale>.md` files for each existing note using the [content contract](format.md), preserving existing copy and files for deselected languages. If the source language changes, review the new source and all selected translations, then mark reviewed translations against the new source. Keep the change scoped to this release unless the user also requests a project language change.
 
 ## Translate selected locales
 
@@ -80,7 +81,7 @@ Questions should address an actual unresolved decision, for example:
 
 | Skill | Ask when needed | Reuse or decide without another question |
 | --- | --- | --- |
-| `releasekit-draft` | Unchosen translation languages, unresolved translation scope or product terminology, a conflicting source-language request, earlier-history treatment for first use, or materially different release scopes that repository inspection cannot resolve. | Established language choices and terminology, current translations, saved boundaries, and versions or Git ranges resolved from release metadata, tags, and ancestry. |
+| `releasekit-draft` | Unchosen first-use translation languages, an ambiguous requested language change, unresolved translation scope or product terminology, earlier-history treatment for first use, or materially different release scopes that repository inspection cannot resolve. | Current project languages for new drafts, saved selections for existing drafts, including a single-language choice; intentional first-use language settings; established terminology, current translations, saved boundaries, and versions or Git ranges resolved from release metadata, tags, and ancestry. |
 | `releasekit-image` | Ambiguous target notes or a meaningful choice among suitable approved reference images. | Captured theme policy, selected assets, and media-source requirements. Required supplied media must stay supplied; do not offer generation as an alternative. |
 | `releasekit-finalize` | Ambiguous target release or requested export choices that neither the request nor established settings resolves. | Requested fixes and local finalization, completed review when content is unchanged, valid export defaults, and already requested export. |