@iodes/releasekit 0.1.0 → 0.1.2

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,27 @@
-# 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 |
+| `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 |
+
+Preparation writes only `release.yaml`: `source` records the immutable Git boundaries, and each note later records its relevant commits or paths. No full patch or separate changed-file index is stored. Draft validation checks note references against the pinned Git range; finalization fingerprints the metadata, note text, and visual briefs. Ready content can be validated and exported without Git history.
+
+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.

package/kit/references/theme-pairing.md

@@ -1,53 +1,55 @@
-# Theme pairs and generation cost
-
-## Project policy
-
-`visuals.themes` in `releasekit/config.yaml` accepts `both`, `dark`, or `light`. The recommended default is `both`. Single-theme projects request only that variant. Image count depends on image-enabled notes and missing or stale variants; it does not multiply by the number of translations.
-
-`releasekit image plan <version>` writes pending prompt files and reports requested, ready, and pending asset counts. It never calls an image service. These counts are work units, not currency estimates or a guarantee about provider billing. Editing a provider's existing image can still cost money. Do not advertise automatic theme conversion as a free second generation.
-
-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.
-
-## 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.
-
-| 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 |
-| 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.
-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.
-
-Use one file per theme, not a split canvas or a two-panel comparison image. Keep previously accepted files while iterating. Do not restart the entire release when one small defect can be corrected locally.
-
-## External generation handoff
-
-If the agent has no image generator, preserve the prompt files and list the pending assets. The user can generate them with another tool and return the files. Import each with:
-
-```sh
-releasekit image import 1.4.0 queue-action --theme dark --file ./selected-dark.png
-releasekit image import 1.4.0 queue-action --theme light --file ./selected-light.png
-```
-
-Only configured themes are required. A missing theme in a two-theme project remains pending and blocks finalization. Do not create SVG stand-ins, placeholders, automatic inversion, or a duplicate of the existing file to satisfy validation.
-
-## Consumer behavior
-
-Exported image data includes `variants` and `fallbackTheme`. A consumer selects the requested theme if present, otherwise the explicitly exported fallback. A single-theme project therefore uses one file in both viewer themes by choice; the bundle does not pretend a second asset exists. Consumers should not invert or recolor raster assets.
-
-The file validator checks format, actual decoding, dimensions, content digest, scene freshness, and configured themes. It rejects identical files masquerading as a pair. The image review checks composition and meaning; a hash cannot establish either.
+# Theme pairs and generation cost
+
+## Project policy
+
+`visuals.themes` in `releasekit/config.yaml` accepts `both`, `dark`, or `light`. The recommended default is `both`. Single-theme projects request only that variant. Image count depends on image-enabled notes and missing or stale variants; it does not multiply by the number of translations.
+
+This generation policy does not require inventing a second appearance for supplied media. A capture or approved content image can use one `shared` asset in either viewer theme. See [media sources](media-sources.md) for supplied-image requests and importing one source or distinct genuine theme captures.
+
+`releasekit image plan <version>` writes pending prompt files and reports requested, ready, and pending asset counts. It never calls an image service. These counts are work units, not currency estimates or a guarantee about provider billing. Editing a provider's existing image can still cost money. Do not advertise automatic theme conversion as a free second generation.
+
+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.
+
+## 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.
+
+| 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 |
+| 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.
+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.
+
+Use one file per theme, not a split canvas or a two-panel comparison image. Keep previously accepted files while iterating. Do not restart the entire release when one small defect can be corrected locally.
+
+## External generation handoff
+
+If the agent has no image generator, preserve the prompt files and list the pending assets. The user can generate them with another tool and return the files. Import each with:
+
+```sh
+releasekit image import 1.4.0 queue-action --theme dark --file ./selected-dark.png
+releasekit image import 1.4.0 queue-action --theme light --file ./selected-light.png
+```
+
+For generated illustrations, only configured themes are required. A missing theme in a two-theme project remains pending and blocks finalization. Supplied media can instead use one genuine shared source. Do not create placeholders, automatic inversion, or duplicate files to satisfy validation.
+
+## Consumer behavior
+
+Exported image data includes `variants` and `fallbackTheme`. A consumer selects the requested theme if present, otherwise the explicitly exported fallback. The fallback can be `dark`, `light`, or `shared`. A supplied shared asset therefore appears once as `variants.shared`, with `fallbackTheme: shared`; the bundle does not pretend a second asset exists. Consumers should not invert or recolor raster assets.
+
+The file validator checks format, actual decoding, dimensions, content digest, scene freshness, and configured themes. It rejects identical files masquerading as a pair. The image review checks composition and meaning; a hash cannot establish either.

package/kit/references/visual-language.md

@@ -1,69 +1,73 @@
-# Quiet product illustration
-
-This is an original, brand-neutral visual language for product release notes. Its purpose is recognition: a reader should understand which capability changed before reading the paragraph. Translate external references into abstract design decisions. Keep reference-company names, reference-site URLs, attributed styles, recognizable unrelated products, and copied artwork out of briefs and generated assets.
-
-## Start with the change, then choose the picture
-
-Read the end-state diff and the product context. Write a one-sentence visual message: what the user can now do, what changed, and which visible detail proves it. Separate established product facts from an illustrative metaphor. Do not turn an internal refactor into a new feature, or invent a control path, metric, security guarantee, or device to make an image more interesting.
-
-Select the simplest useful archetype in [composition-recipes.md](composition-recipes.md). A release can mix archetypes while sharing the same canvas treatment and restraint. A UI workflow deserves a UI fragment; a generic shield cannot explain a new selection interaction. Conversely, a routine status notice rarely needs a complete application dashboard.
-
-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.
-
-## Composition grammar
-
-- Use a landscape canvas, normally 1280 × 800 (8:5). This is an illustration asset, not a screenshot of the release-note viewer. Keep the heading, release number, paragraph, back navigation, and outer page chrome outside the image.
-- Keep one focal idea. Let the archetype determine subject size: compact symbols need substantial empty space; UI fragments and spatial views can occupy most of the frame. Do not apply a single occupancy rule to every asset.
-- Center compact subjects optically. For an interaction, center the changed control or the gesture's result rather than a large irrelevant panel.
-- Keep essential content about 6% away from edges. A deliberate bottom crop of a device or side crop of a list can increase readability; accidental clipped icons, labels, and action targets cannot.
-- Reduce irrelevant UI labels to neutral bars of varied length. Keep alignment, padding, hierarchy, groupings, and interaction topology recognizable. Avoid uniform skeleton placeholders that obscure the actual action.
-- Preserve the relationships that make this feature correct. Specify containment and selected state for controls, fixed and changing parts for transitions, assembly and contact for objects, connections for spatial views, and quantitative relationships for charts. Apply only relationships relevant to the actual subject.
-- Treat the scene's visible-element inventory as complete. Keep schematic elements abstract; do not invent additional content or decoration. Include authentic photographic or detailed content when the brief calls for it.
-- An authentic photo, product material, map layer, or content preview can keep natural detail and color. Most surrounding interface scaffolding should remain quiet.
-- Use one viewpoint. UI crops are normally straight-on; spatial relationships can use an orthographic or elevated camera; a physical detail can use a restrained three-quarter angle.
-
-## Value, depth, and materials
-
-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.
-
-Prefer filled silhouettes and consistent medium-weight strokes that survive reduction. A symbol may sit on a rounded tile, stand alone, or carry one small status badge. Keep corner radii and line weights related across a release.
-
-Use soft contact shadows where they explain separation. Restrained gradient modeling can clarify a lens, button, material, or native application icon. Avoid decorative glass, broad atmospheric gradients, cinematic glow, heavy bevels, and glossy objects that have no relationship to the feature.
-
-## 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.
-
-Limited color is a default for interface explanation, not a prohibition on colorful features. A newly announced creative tool can show colorful output. A spatial view can require several functional colors. A content or seasonal experience can support a full scene. The color should belong to the feature, rather than decorate a routine release card.
-
-## Language independence
-
-Keep illustrations reusable across locales. Put release copy in Markdown and alt text in each locale. Omit readable text and numbers by default. If a short label or numeric value is indispensable, include it verbatim in the brief's `text` list and trace it to evidence or an explicitly illustrative example. Do not let the model fabricate microcopy, timestamps, status-bar details, or statistics.
-
-The generator may use neutral bars in place of labels, but it must preserve the hierarchy and shape of the real workflow. If exact UI fidelity matters, use a supplied product capture as evidence and describe the specific simplification to make. Do not fabricate a light product UI merely because the output canvas is light.
-
-## Scene brief contract
-
-Each image-enabled note has one shared scene in `visuals/<note>.yaml`:
-
-- `archetype`: the selected recipe.
-- `subject`: the actual feature or its justified visual metaphor.
-- `message`: the user-visible change, in one sentence.
-- `focus`: the exact part a reader should notice first.
-- `composition`: explicit placement, scale, crop, camera, and surrounding context.
-- `context`: product facts and any limits on what the image can claim.
-- `elements`: a short inventory of visible objects or UI groups.
-- `preserve`: invariants shared by theme variants and revisions.
-- `avoid`: exclusions specific to this scene.
-- `text`: the only literal labels permitted in the raster; normally empty.
-- `references`: portable project-relative files to inspect before generation.
-
-Make the brief concrete enough that another model can render the same scene. “Clean, modern, minimal” alone is not a useful composition specification. State the subject's anchors, grouping, relationships, and any allowed change in state, as well as the safe margin. A chart may need fixed category proportions; a device detail may need a preserved attachment point; a setting may need one enabled control with its associated fields. Read only the worked brief relevant to the current feature.
-
-## 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.
-
-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 accepted files and import the newly selected version.
+# Quiet product illustration
+
+This is an original, brand-neutral visual language for product release notes. Its purpose is recognition: a reader should understand which capability changed before reading the paragraph. Translate external references into abstract design decisions. Keep reference-company names, reference-site URLs, attributed styles, recognizable unrelated products, and copied artwork out of briefs and generated assets.
+
+## Start with the change, then choose the picture
+
+Read the end-state diff and the product context. Write a one-sentence visual message: what the user can now do, what changed, and which visible detail proves it. Separate established product facts from an illustrative metaphor. Do not turn an internal refactor into a new feature, or invent a control path, metric, security guarantee, or device to make an image more interesting.
+
+Select the simplest useful archetype in [composition-recipes.md](composition-recipes.md). A release can mix archetypes while sharing the same canvas treatment and restraint. A UI workflow deserves a UI fragment; a generic shield cannot explain a new selection interaction. Conversely, a routine status notice rarely needs a complete application dashboard.
+
+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.
+
+## Composition grammar
+
+- Use a landscape canvas, normally 1280 × 800 (8:5). This is an illustration asset, not a screenshot of the release-note viewer. Keep the heading, release number, paragraph, back navigation, and outer page chrome outside the image.
+- Keep one focal idea. Let the archetype determine subject size: compact symbols need substantial empty space; UI fragments and spatial views can occupy most of the frame. Do not apply a single occupancy rule to every asset.
+- Center compact subjects optically. For an interaction, center the changed control or the gesture's result rather than a large irrelevant panel.
+- Keep essential content about 6% away from edges. A deliberate bottom crop of a device or side crop of a list can increase readability; accidental clipped icons, labels, and action targets cannot.
+- Reduce irrelevant UI labels to neutral bars of varied length. Keep alignment, padding, hierarchy, groupings, and interaction topology recognizable. Avoid uniform skeleton placeholders that obscure the actual action.
+- Preserve the relationships that make this feature correct. Specify containment and selected state for controls, fixed and changing parts for transitions, assembly and contact for objects, connections for spatial views, and quantitative relationships for charts. Apply only relationships relevant to the actual subject.
+- Treat the scene's visible-element inventory as complete. Keep schematic elements abstract; do not invent additional content or decoration. Include authentic photographic or detailed content when the brief calls for it.
+- An authentic photo, product material, map layer, or content preview can keep natural detail and color. Most surrounding interface scaffolding should remain quiet.
+- Quiet does not always mean sparse. A map may retain many fine streets at low contrast so its subject still reads as geography; establish hierarchy through value and line weight before removing useful structure. Use the selected recipe's scale and density, not a universal icon-like simplification.
+- Use one viewpoint. UI crops are normally straight-on; spatial relationships can use an orthographic or elevated camera; a physical detail can use a restrained three-quarter angle.
+
+## Value, depth, and materials
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+## Language independence
+
+Keep illustrations reusable across locales. Put release copy in Markdown and alt text in each locale. Omit readable text and numbers by default. If a short label or numeric value is indispensable, include it verbatim in the brief's `text` list and trace it to evidence or an explicitly illustrative example. Do not let the model fabricate microcopy, timestamps, status-bar details, or statistics.
+
+The generator may use neutral bars in place of labels, but it must preserve the hierarchy and shape of the real workflow. If exact UI fidelity matters, use a supplied product capture as evidence and describe the specific simplification to make. Do not fabricate a light product UI merely because the output canvas is light.
+
+## Scene brief contract
+
+Each image-enabled note has one shared scene in `visuals/<note>.yaml`:
+
+- `archetype`: the selected recipe.
+- `source`: `generated` for a flat explanation or `provided` for an existing capture/image; physical details and content previews require `provided`.
+- `subject`: the actual feature or its justified visual metaphor.
+- `message`: the user-visible change, in one sentence.
+- `focus`: the exact part a reader should notice first.
+- `composition`: explicit placement, scale, crop, camera, and surrounding context.
+- `context`: product facts and any limits on what the image can claim.
+- `elements`: a short inventory of visible objects or UI groups.
+- `preserve`: invariants shared by theme variants and revisions.
+- `avoid`: exclusions specific to this scene.
+- `text`: the only literal labels permitted in the raster; normally empty.
+- `references`: portable project-relative files to inspect before generation.
+
+Make the brief concrete enough that another model can render the same scene. “Clean, modern, minimal” alone is not a useful composition specification. State the subject's anchors, grouping, relationships, and any allowed change in state, as well as the safe margin. A chart may need fixed category proportions; a device detail may need a preserved attachment point; a setting may need one enabled control with its associated fields. Read only the worked brief relevant to the current feature.
+
+## 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.
+
+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 accepted files and import the newly selected version.