@iodes/releasekit 0.1.0 → 0.1.1

package/examples/storage-breakdown/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: A category breakdown shows how saved files use storage.
+Subject: A storage breakdown with three categories
+Focal detail: One stacked bar and its matching category legend
+Context: Fictional view illustration. The proportions 20, 30, and 50 percent are explicitly illustrative and are not measurements or a claim of improved storage efficiency.
+
+## Composition contract
+Archetype: data-view
+Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
+Focus on one panel or device showing one dominant visualization and a few supporting rows. Give the primary metric or interaction clear breathing room.
+Specific scene layout: A single panel occupies about 68 percent of an 8:5 canvas width. One horizontal stacked bar contains three contiguous segments with lengths in the ratio 2:3:5. Below it, three equally spaced legend items appear in the same order as the segments. Each legend item has one matching swatch and an abstract label bar. The first two categories use distinguishable neutral values; the largest category uses the accent. Omit literal numbers, axes, trend lines, and unrelated controls.
+Elements:
+- One panel
+- One stacked bar containing exactly three contiguous segments
+- Three matching legend swatches with abstract label bars
+
+## Visual treatment
+Use sparse neutral chart scaffolding and one purposeful accent. Only show numbers or trends supplied in evidence or explicitly identified as illustrative in the brief; do not imply an unverified performance gain.
+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 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.
+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:
+- Three segment lengths in the ratio 2:3:5, accounting for the complete bar
+- Left-to-right category order and one-to-one legend correspondence
+- Accent assigned to the same largest category 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
+- Invented performance improvement or additional metrics
+- Gaps, overlap, or proportions that disagree with the legend
+- Category color changes between the bar and its legend
+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. 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.
+
+## 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/storage-breakdown/pair-review.md

@@ -0,0 +1,18 @@
+# Pair review: Storage breakdown
+
+## Generation record
+
+Generated with the coding agent's built-in image tool. The CLI made no image-service calls. The dark asset was generated from dark.prompt.md; the light asset was created as a constrained edit of the selected dark image using light.prompt.md and an instruction to preserve input dimensions and composition. No color inversion was used.
+
+Two image-tool requests: dark generation and light counterpart.
+
+## Selected output
+
+- Two distinct decoded PNGs, both 1586 × 992 pixels, approximately 8:5. Original output dimensions are retained.
+- Reviewed at full size and approximately 350 pixels wide for feature meaning, focal clarity and pair correspondence.
+- Exactly three contiguous segments and three corresponding legend swatches remain in the same order.
+- The bar depicts approximately 20/30/50 proportions with the blue category largest; raster boundaries are not exact numerical data.
+- The first two swatches use distinguishable neutrals, matching their segments in each theme. No literal metric or improvement claim is shown.
+- 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. Presentation lighting and surface shading can differ. This fictional image is an authoring reference; review real product imagery against its own evidence before acceptance.

package/examples/storage-breakdown/scene.yaml

@@ -0,0 +1,28 @@
+archetype: data-view
+subject: A storage breakdown with three categories
+message: A category breakdown shows how saved files use storage.
+focus: One stacked bar and its matching category legend
+composition: A single panel occupies about 68 percent of an 8:5 canvas width.
+  One horizontal stacked bar contains three contiguous segments with lengths in
+  the ratio 2:3:5. Below it, three equally spaced legend items appear in the
+  same order as the segments. Each legend item has one matching swatch and an
+  abstract label bar. The first two categories use distinguishable neutral
+  values; the largest category uses the accent. Omit literal numbers, axes,
+  trend lines, and unrelated controls.
+context: Fictional view illustration. The proportions 20, 30, and 50 percent are
+  explicitly illustrative and are not measurements or a claim of improved
+  storage efficiency.
+elements:
+  - One panel
+  - One stacked bar containing exactly three contiguous segments
+  - Three matching legend swatches with abstract label bars
+preserve:
+  - Three segment lengths in the ratio 2:3:5, accounting for the complete bar
+  - Left-to-right category order and one-to-one legend correspondence
+  - Accent assigned to the same largest category in both themes
+avoid:
+  - Invented performance improvement or additional metrics
+  - Gaps, overlap, or proportions that disagree with the legend
+  - Category color changes between the bar and its legend
+text: []
+references: []

package/examples/tablet-reading/README.md

@@ -0,0 +1,18 @@
+# Tablet reading
+
+An original fictional `device-view` example: A tablet reading view keeps a saved article in one spacious column.
+
+Original fictional example. The written scene is the complete product specification for this example, not evidence of a shipped product.
+
+| Dark | Light |
+| --- | --- |
+| ![A single tablet displaying a focused reading layout, dark presentation](dark.png) | ![A single tablet displaying a focused reading layout, light presentation](light.png) |
+
+Both selected PNGs are 1586 × 992 pixels.
+
+- [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)
+- [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/tablet-reading/content-edit.prompt.md

@@ -0,0 +1,7 @@
+# Targeted content correction
+
+Use case: precise-object-edit.
+
+Change only the rectangular article image area inside the tablet screen: remove the mountains and circle and fill that exact existing rectangle with one uniform muted blue. No pictorial content. Preserve all tablet geometry, screen, six body bars, header bar, canvas, framing, lighting and every other pixel relationship. Keep the dark presentation theme. Output one image at exactly the input dimensions.
+
+Use the corrected dark output as the composition reference for the light prompt.

package/examples/tablet-reading/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: A tablet reading view keeps a saved article in one spacious column.
+Subject: A single tablet displaying a focused reading layout
+Focal detail: One generous single-column article layout on a tablet screen
+Context: Original fictional example. The written scene is the complete product specification for this example, not evidence of a shipped product.
+
+## Composition contract
+Archetype: device-view
+Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
+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.
+Specific scene layout: One front-facing portrait tablet centered on the canvas, occupying 34 percent of canvas width and 84 percent of canvas height. Thin matte graphite hardware bezel, modest rounded corners, no logo, camera ornament or stand. Screen is always near-white in BOTH themes: the fictional reader supports only a light reading surface. Inside the screen one short dark heading bar, one muted blue rectangular abstract article image, and six neutral body bars in one column with generous equal side padding. The first five body bars are equally long and the last is shorter. No other controls. Natural subtle contact shadow below device.
+Elements:
+- One matte graphite portrait tablet
+- One near-white single-column screen
+- One heading bar, one muted blue image rectangle, six body bars
+
+## Visual 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.
+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 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.
+Specific invariants:
+- Hardware material and light screen in both presentation themes
+- One device, exact screen layout, six body bars and their lengths
+- Straight-on camera, centered position and crop
+
+## 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
+- Second device or connection cues
+- Invented dark reading UI
+- Readable article text, numbers, logos or extra 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. Check the actual device count, screen content, and relationship between devices. Do not imply an unsupported device, connection, or application theme.
+
+## 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/tablet-reading/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: A tablet reading view keeps a saved article in one spacious column.
+Subject: A single tablet displaying a focused reading layout
+Focal detail: One generous single-column article layout on a tablet screen
+Context: Original fictional example. The written scene is the complete product specification for this example, not evidence of a shipped product.
+
+## Composition contract
+Archetype: device-view
+Target canvas: 1280 × 800 pixels; landscape 1280:800. Produce a single image, not a dark/light collage.
+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.
+Specific scene layout: One front-facing portrait tablet centered on the canvas, occupying 34 percent of canvas width and 84 percent of canvas height. Thin matte graphite hardware bezel, modest rounded corners, no logo, camera ornament or stand. Screen is always near-white in BOTH themes: the fictional reader supports only a light reading surface. Inside the screen one short dark heading bar, one muted blue rectangular abstract article image, and six neutral body bars in one column with generous equal side padding. The first five body bars are equally long and the last is shorter. No other controls. Natural subtle contact shadow below device.
+Elements:
+- One matte graphite portrait tablet
+- One near-white single-column screen
+- One heading bar, one muted blue image rectangle, six body bars
+
+## Visual 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.
+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 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.
+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:
+- Hardware material and light screen in both presentation themes
+- One device, exact screen layout, six body bars and their lengths
+- Straight-on camera, centered position and crop
+
+## 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
+- Second device or connection cues
+- Invented dark reading UI
+- Readable article text, numbers, logos or extra 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. Check the actual device count, screen content, and relationship between devices. Do not imply an unsupported device, connection, or application theme.
+
+## 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/tablet-reading/pair-review.md

@@ -0,0 +1,18 @@
+# Pair review: Tablet reading
+
+## Generation record
+
+Generated with the coding agent's built-in image tool. The CLI made no image-service calls. The dark asset was generated from dark.prompt.md; the light asset was created as a constrained edit of the selected dark image using light.prompt.md and an instruction to preserve input dimensions and composition. No color inversion was used.
+
+Three image-tool requests: initial dark, targeted content correction, and light counterpart.
+
+## Selected output
+
+- Two distinct decoded PNGs, both 1586 × 992 pixels, approximately 8:5. Original output dimensions are retained.
+- Reviewed at full size and approximately 350 pixels wide for feature meaning, focal clarity and pair correspondence.
+- One front-facing graphite tablet retains its near-white reading screen in both presentation themes.
+- One heading, one flat muted-blue rectangle and six body bars remain in one column; the sixth bar is shorter.
+- The initial dark output added a landscape inside the abstract image rectangle. A targeted edit removed that content before creating the light counterpart; see content-edit.prompt.md.
+- 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. Presentation lighting and surface shading can differ. This fictional image is an authoring reference; review real product imagery against its own evidence before acceptance.

package/examples/tablet-reading/scene.yaml

@@ -0,0 +1,29 @@
+archetype: device-view
+subject: A single tablet displaying a focused reading layout
+message: A tablet reading view keeps a saved article in one spacious column.
+focus: One generous single-column article layout on a tablet screen
+composition: "One front-facing portrait tablet centered on the canvas, occupying
+  34 percent of canvas width and 84 percent of canvas height. Thin matte
+  graphite hardware bezel, modest rounded corners, no logo, camera ornament or
+  stand. Screen is always near-white in BOTH themes: the fictional reader
+  supports only a light reading surface. Inside the screen one short dark
+  heading bar, one muted blue rectangular abstract article image, and six
+  neutral body bars in one column with generous equal side padding. The first
+  five body bars are equally long and the last is shorter. No other controls.
+  Natural subtle contact shadow below device."
+context: Original fictional example. The written scene is the complete product
+  specification for this example, not evidence of a shipped product.
+elements:
+  - One matte graphite portrait tablet
+  - One near-white single-column screen
+  - One heading bar, one muted blue image rectangle, six body bars
+preserve:
+  - Hardware material and light screen in both presentation themes
+  - One device, exact screen layout, six body bars and their lengths
+  - Straight-on camera, centered position and crop
+avoid:
+  - Second device or connection cues
+  - Invented dark reading UI
+  - Readable article text, numbers, logos or extra controls
+text: []
+references: []

package/kit/references/composition-recipes.md

@@ -1,73 +1,89 @@
-# Composition recipes
-
-Choose an archetype from the feature's explanatory need. Numeric occupancy ranges below are starting points, not replacements for the scene brief.
-
-The rules below are conditional on the selected subject. Choose a new scene for each release note. A worked brief demonstrates one feature's constraints; its objects, coordinates, gestures, or data relationships must not become defaults for unrelated notes.
-
-| Archetype | Use when | Starting composition | Common failure |
-| --- | --- | --- | --- |
-| `icon-tile` | A capability or status is recognizable through one symbol | Symbol or tile about 16–24% of canvas width, optically centered | An enormous generic icon or empty decorative symbolism |
-| `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 |
-| `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 | Close crop with one consistent camera and quiet depth | An invented product silhouette or excessive glossy modeling |
-| `spatial-view` | Topology, route, location, or layout is the subject | Top-down or elevated scene, often filling the frame | Competing map layers, unreadable lines, impossible spatial relationships |
-| `data-view` | A new view of information is the feature | One dominant chart or metric panel plus sparse support | Fake improvement numbers or decorative chart noise |
-| `editorial-scene` | The announced content or experience is the subject | One coherent scene with feature-appropriate materials and color | A marketing banner for an ordinary fix |
-
-## Decision sequence
-
-1. Does the reader need to understand where or how to act? Prefer `ui-detail`; use `device-view` only when device context carries meaning.
-2. Is spatial topology or a real physical part essential? Choose `spatial-view` or `object-detail`.
-3. Is the new information display itself the change? Choose `data-view`.
-4. Is this an experience whose content is inherently visual? Choose `editorial-scene`.
-5. Otherwise, use `icon-tile` for one concept or `symbol-pair` for one relationship.
-
-## Correctness checks by subject
-
-Select only the relevant checks and make them concrete in the note's `composition`, `preserve`, and `avoid` fields before generating.
-
-| Archetype | Check against the release note and product evidence |
-| --- | --- |
-| `icon-tile` | The symbol conveys the announced capability or status without suggesting an unsupported guarantee |
-| `symbol-pair` | The association and any direction are accurate; no invented transfer, synchronization, or automation |
-| `ui-detail` | Control meaning, hierarchy, containment, alignment, and state are correct; any transition identifies fixed and changing elements |
-| `device-view` | Device identity, count, screen content, and cross-device relationships match the feature |
-| `object-detail` | Shape, scale, assembly, contact points, and materials preserve the physical feature |
-| `spatial-view` | Positions, connections, direction, and layer meanings form a consistent spatial model |
-| `data-view` | Categories, values, proportions, units, legends, and selected filters agree wherever present |
-| `editorial-scene` | The depicted experience matches the announced content without added capabilities or unrelated subjects |
-
-Review correctness before visual polish and theme correspondence. If a detail is unsupported, reduce specificity to a justified abstraction or resolve it before rendering. A successful theme pair can still repeat the same incorrect feature depiction.
-
-## Worked brief: list interaction
-
-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.
-
-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.
-
-## Worked brief: a saved-location preference
-
-Message: a setting can be saved for a selected location.
-
-Choose `symbol-pair` if the association itself is sufficient: a simple adjustment glyph and a location pin, balanced around a narrow neutral divider. Choose `ui-detail` if users need to discover the new menu action. Do not add a device just to fill the empty space. A location pin is a metaphor; it must not imply geofencing or automatic behavior absent from the evidence.
-
-## Worked brief: activity information
-
-Message: users can see an activity breakdown in a new panel.
-
-Choose `data-view`. One panel contains a dominant simple chart and two supporting rows. If actual values are not available, omit literal numbers and avoid a rising curve that implies a performance gain. Make the new view, not an invented result, the focus. Use a selected segment or one active filter to establish hierarchy if that interaction is supported.
-
-## Worked brief: a focused object
-
-Message: a new control is available on an existing physical interface.
-
-Choose `object-detail` only with product evidence. Crop closely enough to make the control recognizable, retain surrounding context, and use one soft highlight or local accent. Lock the actual geometry. Do not introduce a generic vehicle, appliance, robot, or headset into an unrelated software product.
-
-## Exceptions with a reason
-
-A genuine content preview can be photographic or colorful. A real icon may include gradients. A broad spatial view may reach every edge. An editorial introduction may use a different aspect ratio chosen in project settings. These exceptions follow the subject; they do not replace the quiet presentation language for other notes.
+# Composition recipes
+
+Choose an archetype from the feature's explanatory need. Numeric occupancy ranges below are starting points, not replacements for the scene brief.
+
+The rules below are conditional on the selected subject. Choose the [media source](media-sources.md) first. These are eight presentation categories; physical details and content previews require supplied media. A worked brief demonstrates one feature's constraints; its objects, coordinates, gestures, or data relationships must not become defaults for unrelated notes.
+
+| 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 |
+| `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 |
+| `spatial-view` | Topology, route, location, or layout is the subject | One appropriate scale and viewpoint; fine subdued context around a clear route or selection | An oversized toy street grid, competing map layers, or impossible spatial relationships |
+| `data-view` | A new view of information is the feature | One dominant chart or metric panel plus sparse support | Fake improvement numbers or decorative chart noise |
+| `editorial-scene` | The announced content or experience is the subject | Supplied content artwork or screenshot, with original colors | Inventing a still life or decorative illustration |
+
+## Decision sequence
+
+1. Does the reader need to understand where or how to act? Prefer `ui-detail`; use `device-view` only when device context carries meaning.
+2. Is spatial topology essential? Choose `spatial-view`. Is a real physical part essential? Choose `object-detail` and request or reuse its image.
+3. Is the new information display itself the change? Choose `data-view`.
+4. Is the actual announced content the subject? Choose `editorial-scene` and request or reuse its artwork or capture.
+5. Otherwise, use `icon-tile` for one concept or `symbol-pair` for one relationship.
+
+## Correctness checks by subject
+
+Select only the relevant checks and make them concrete in the note's `composition`, `preserve`, and `avoid` fields before generating.
+
+| Archetype | Check against the release note and product evidence |
+| --- | --- |
+| `icon-tile` | The symbol conveys the announced capability or status without suggesting an unsupported guarantee |
+| `symbol-pair` | The association and any direction are accurate; no invented transfer, synchronization, or automation |
+| `ui-detail` | Control meaning, hierarchy, containment, alignment, and state are correct; any transition identifies fixed and changing elements |
+| `device-view` | Device identity, count, screen content, and cross-device relationships match the feature |
+| `object-detail` | Shape, scale, assembly, contact points, and materials preserve the physical feature |
+| `spatial-view` | Positions, connections, direction, and layer meanings form a consistent spatial model; the focal layer reads first at small size |
+| `data-view` | Categories, values, proportions, units, legends, and selected filters agree wherever present |
+| `editorial-scene` | The depicted experience matches the announced content without added capabilities or unrelated subjects |
+
+Review correctness before visual polish and theme correspondence. If a detail is unsupported, reduce specificity to a justified abstraction or resolve it before rendering. A successful theme pair can still repeat the same incorrect feature depiction.
+
+## Worked brief: list interaction
+
+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.
+
+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.
+
+## Worked brief: a saved-location preference
+
+Message: a setting can be saved for a selected location.
+
+Choose `symbol-pair` if the association itself is sufficient: a simple adjustment glyph and a location pin, balanced around a narrow neutral divider. Choose `ui-detail` if users need to discover the new menu action. Do not add a device just to fill the empty space. A location pin is a metaphor; it must not imply geofencing or automatic behavior absent from the evidence.
+
+## Worked brief: activity information
+
+Message: users can see an activity breakdown in a new panel.
+
+Choose `data-view`. One panel contains a dominant simple chart and two supporting rows. If actual values are not available, omit literal numbers and avoid a rising curve that implies a performance gain. Make the new view, not an invented result, the focus. Use a selected segment or one active filter to establish hierarchy if that interaction is supported.
+
+## Map hierarchy within spatial views
+
+Choose the level of abstraction from the feature. A relationship diagram can be sparse; a map preview usually needs recognizable cartographic context. Simplify a map by reducing the contrast of minor detail before removing its structure. Use thin, connected local streets, a slightly stronger major network, and quiet flat land or water values. Avoid replacing a regional map with a few broad roads, lane dashes, padded blocks, or a raised checkerboard.
+
+Make the route or selected area the first read at roughly 350 pixels wide. Supporting detail may merge into a quiet texture at that size, while the focal path and its meaningful endpoints remain legible. Give the active path a clear stroke hierarchy without making it a glowing cable. Keep geographic context planar; do not add bevels, modeled terrain, grain, or studio lighting for polish.
+
+Choose the crop and amount of negative space from the feature. A supported summary can occupy a quiet area beside a map, with a local fade that suppresses background detail behind it. A full-frame map or a focused spatial diagram can be more appropriate for other notes. Do not require a left summary, a right map, a water body, or any particular route shape across this archetype.
+
+Marker shapes carry meaning. Saved waypoints, a current-position arrow, a destination pin, traffic, and a route alternative are different states; include only the ones established by the note. A route follows traversable connections, with a bridge or other supported connection wherever needed. For an actual location, path, or coverage claim, request an approved map capture or verified source instead of inventing geography. A fictional gallery scene must state that its geography is illustrative.
+
+## Worked brief: a saved route preview
+
+Message: the route preview connects two selected saved waypoints. Choose `spatial-view`. For this fictional example, use an original irregular city network with many fine, quiet streets and one continuous blue path. Place a compact abstract summary beside the map when that summary is part of the chosen scene. Use neutral endpoints rather than introducing an unsupported live-navigation state. The map's detail supports recognition; its route supplies the meaning.
+
+Before pairing, check continuity, endpoint attachment, meaningful scale, and route priority at mobile size. Preserve the land boundary, primary street structure, route bends, endpoint positions, summary alignment, crop, and semantic route color between themes. If exact real-world geography matters, switch to supplied media. These are feature-derived checks; they do not prescribe this example's layout for every spatial note.
+
+## Worked brief: a focused object
+
+Message: a new control is available on an existing physical interface.
+
+Choose `object-detail` with `source: provided`. Request a photograph or capture of the actual control if an approved image is not already available. Use a crop that preserves surrounding context and the real geometry. Do not synthesize a product from a written fictional specification or introduce an unrelated appliance, robot, or headset. This note stays pending until an appropriate image is supplied.
+
+## Exceptions with a reason
+
+A supplied content preview can retain its authentic photography, artwork, materials, and colors. A broad spatial view may reach every edge when its relationships require it. Original supplied media can retain its aspect ratio. These are source-preservation choices, not permission to invent a decorative illustration or physical rendering.

package/kit/references/format.md

@@ -1,24 +1,26 @@
-# 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.
-
-Within one release:
-
-| File | Purpose |
-| --- | --- |
-| `release.yaml` | Version, status, explicit previous link, pinned Git range, policy snapshot, ordered note metadata |
-| `evidence.json` and `changes.patch` | Commit/path evidence and the net change at the requested end revision |
-| `notes/<id>/<locale>.md` | Title, alt text, source fingerprint, and Markdown body |
-| `visuals/<id>.yaml` | Shared scene specification and imported variant metadata |
-| `prompts/<id>.<theme>.md` | Reproducible generation requests for pending variants |
-| `assets/` | Selected raster files with content-derived names |
-
-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.
-
-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 every configured theme before finalization. Its scaffold leaves `archetype` unselected; the authoring agent chooses the representation from the note and product evidence before planning images.
-
-`releasekit finalize` checks references and content, then records `status: ready` and a content fingerprint. A later edit invalidates that fingerprint. Reopen the draft before changing content; publishing is a separate user-controlled workflow.
-
-The generated JSON schemas shipped with the package are the structural source of truth. `releasekit export` produces `release-notes.json` plus relative image assets. It includes only display fields, configured image variants, the chosen locale, and explicit version groups. Source patches, prompts, internal paths, and Git evidence are not included. Consumers should safely render `bodyMarkdown` and use image `variants[theme]` or `variants[fallbackTheme]` without recoloring the raster.
-
-An export destination must not already exist. This avoids overwriting content or mixing assets from separate builds. Validation completes before the destination is created.
+# 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.
+
+Within one release:
+
+| File | Purpose |
+| --- | --- |
+| `release.yaml` | Version, status, explicit previous link, pinned Git range, policy snapshot, ordered note metadata |
+| `evidence.json` and `changes.patch` | Commit/path evidence and the net change at the requested end revision |
+| `notes/<id>/<locale>.md` | Title, alt text, source fingerprint, and Markdown body |
+| `visuals/<id>.yaml` | Scene, image source choice, and imported variant metadata |
+| `prompts/<id>.<theme>.md` | Generation requests for pending generated variants; supplied images have no generation request |
+| `assets/` | Selected raster files with content-derived names |
+
+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.
+
+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).
+
+`releasekit finalize` checks references and content, then records `status: ready` and a content fingerprint. A later edit invalidates that fingerprint. Reopen the draft before changing content; publishing is a separate user-controlled workflow.
+
+The generated JSON schemas shipped with the package are the structural source of truth. `releasekit export` produces `release-notes.json` plus relative image assets. It includes only display fields, configured image variants, the chosen locale, and explicit version groups. Source patches, prompts, internal paths, and Git evidence are not included. Consumers should safely render `bodyMarkdown` and use image `variants[theme]` or `variants[fallbackTheme]` without recoloring the raster.
+
+An export destination must not already exist. This avoids overwriting content or mixing assets from separate builds. Validation completes before the destination is created.

package/kit/references/media-sources.md

@@ -0,0 +1,34 @@
+# Choosing the image source
+
+A release note needs a truthful explanation of the feature. It does not need an invented illustration for every subject. Choose the source before composition and rendering.
+
+| Source | Appropriate use | Agent action |
+| --- | --- | --- |
+| `generated` | Flat functional glyphs, simplified interface fragments, schematic relationships, maps, or data graphics supported by the brief | Build the scene and use the configured image generator |
+| `provided` | Actual product appearance, physical details, content artwork, photos, exact interfaces, or a user's selected image | Find an approved existing asset or request the relevant capture/image, inspect it, and import it |
+
+Set `scene.source` in the note's visual YAML. `object-detail` and `editorial-scene` require `provided`; explicitly choosing `generated` for either is rejected. For older briefs without this field, those two categories default to supplied media and the others to generated graphics. The categories describe presentation, not eight styles that must all be invented.
+
+Use `provided` for another category whenever a real capture explains it better. Do not invent a device's appearance, fabricate actual product content, or turn a capability icon into a sculpted object. Decorative illustration and 3D still-life generation are outside this kit's release-note language.
+
+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.
+
+## 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.
+
+The plan reports `generationRequests` and `providedRequests` separately. Always use the current plan; old prompt files are historical artifacts, not authorization to generate a newly supplied-only scene. Finalization remains blocked until the selected source is imported and validated.
+
+## One image shared by both viewer themes
+
+A native photo, content image, or screenshot often has one authentic appearance. Import it once:
+
+```sh
+releasekit image import 1.4.0 product-detail --theme shared --file ./approved-capture.png
+```
+
+This requires `source: provided`. The CLI copies the selected bytes unchanged. `variants.shared` stores one asset; the public bundle exports one file with `fallbackTheme: shared`. The normal consumer lookup, `variants[theme] ?? variants[fallbackTheme]`, displays that file in either viewer theme. A shared slot is not a fabricated pair and does not require a second generation or duplicate file. Its original dimensions and colors are retained.
+
+If the product actually supplies distinct dark/light captures, import those with `--theme dark` and `--theme light`. Once one themed capture is imported, the plan requests the remaining configured capture. Choose shared or distinct themed entries, not both in the same note; remove the previous variant entries deliberately when switching. A missing theme is never generated as a substitute for an authentic capture.
+
+Inspect the content and crop before import. Keep the original source while preparing any user-authorized crop or presentation adjustment. Theme changes must not alter product content. File validation checks bytes and metadata; the agent's review establishes whether the selected media is the appropriate approved source.