@iodes/releasekit 0.1.3 → 0.1.5

package/kit/references/format.md

@@ -1,6 +1,6 @@
 # Content contract
 
-Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases. New projects default to English originals (`sourceLocale: en-US`, `locales: [en-US]`). The agent suggests the user's current language as an optional translation and accepts additional languages; selected translations are added after the source in the release's `locales`.
+Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases. New projects default to English originals (`sourceLocale: en-US`, `locales: [en-US]`). On first use, the agent asks about optional translations only when language choices remain unresolved, then saves the selected source and translations in `releasekit/config.yaml` before preparation. Each new release copies the current project `sourceLocale`, `locales`, and visual policy. Later drafts use those configured languages without asking again, including a single-language choice. Previous releases' language selections do not override config. Explicit release-only language changes are saved in the affected `release.yaml`, preserving project defaults and other releases.
 
 Optional `history.start` in the project config records first-use setup: `ref` is the original commit/tag label, `sha` is its immutable commit, `past` is `summary`, `history`, or `skip`, and `version` is the baseline release ID for summary/history or null for skip. `releasekit start` saves this once before any release exists. It creates no content. Existing configs without this field retain the explicit-range workflow. See [first-use setup](adoption.md).
 
@@ -14,6 +14,16 @@ Within one release:
 | `prompts/<id>.<theme>.md` | Generation requests for pending generated variants; supplied images have no generation request |
 | `assets/` | Selected raster files with content-derived names |
 
+`visuals.accent` makes a project color available for generated images; it does not require that color in every image. In the shared scene's `composition`, record no accent or the exact colored element and its supported state, action, or information meaning. Keep that assignment in `preserve`; neutral scenes remain neutral in both themes.
+
+Each `(version, note.id, variant)` has one selected image. Importing replaces the selected slot and then removes unused managed images belonging to this note, including obsolete shared or themed imports. Files referenced by any visual variant or scene in the project are retained, as are other notes' files and source originals outside the note's managed assets. Reimporting identical content reuses its file. Keep existing variant entries until the replacement import succeeds.
+
+Importing `--theme shared` replaces the note's dark/light entries with one shared entry. Importing `--theme dark` or `light` replaces a shared entry and keeps compatible themed entries. Optional `--source generated|provided` updates `scene.source` in the same save as the imported selection; omission preserves the current source. Shared imports require supplied media, and supplied-only subjects still reject generated media. The CLI validates the file before saving, so decoding or metadata-save failure preserves the previous source and selections. A missing configured counterpart stays pending after the first themed import and blocks finalization. See [image transitions](theme-pairing.md#switch-between-shared-and-themed-images).
+
+`releasekit note remove <version> <id>` is available only for drafts. It removes the ordered metadata entry, `notes/<id>/` with all locale files, `visuals/<id>.yaml`, `prompts/<id>.<variant>.md`, and unused managed raster imports associated with the note, including older variants. Managed imports use `assets/<id>.<variant>.<12-character-hash>.(png|jpg|webp)` names. Files still referenced by any remaining visual are retained; manually named assets and external source originals are preserved. References to the note's text, brief, or prompts must be resolved before removal. The CLI reports removed paths and retained assets. A failed metadata save restores the removed files; any subsequent cleanup failure is reported with the recovery directory rather than as a successful cleanup.
+
+Adding a note creates the release's saved locale files and clears `emptyReason`. Notes are image-enabled by default; `--no-image` records an explicit text-only choice. The agent keeps this default for all notes rather than selecting an illustrated subset. Removing the last note does not invent an empty-release reason: the draft needs another note or a factual `emptyReason` before finalization. Ready releases must be reopened before either operation.
+
 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 or the baseline snapshot for a summary; finalization fingerprints the metadata, note text, and visual briefs. Ready content can be validated and exported without Git history.
 
 Optional `initialContent` in a baseline release snapshots the selected `summary` or `history` mode. Either mode requires `source.fromRef: null`, `source.fromSha: null`, and `previous: null`. A summary describes the product at `source.toSha`; its evidence may reference only that SHA or tracked paths in that snapshot. History mode analyzes the full history through that SHA with normal range evidence. This distinction is preserved in the content fingerprint but excluded from consumer JSON. An absent field keeps the existing range semantics, including full history when `fromSha` is null; loading old files adds no defaults or changes to their fingerprints.
@@ -22,12 +32,18 @@ The next release begins after the baseline SHA and links to its version with `pr
 
 Notes are ordered by their entries in `release.yaml`. Note IDs are unique within a version and shared across locales. Their consumer identity is the pair `(version, note.id)`; never deduplicate different releases by note ID or title alone.
 
+A grouped minor-change note uses the same contract: one note ID, category `fix` or `improvement`, a localized summary title, and an unordered Markdown list in the body. Its metadata carries the evidence paths or commits covering all bullets. Bullets have no separate note records or images; the group uses the normal image and translation policy and exports as one note with its list in `bodyMarkdown`. See [grouping guidance](writing.md#group-minor-changes) for selection and titles.
+
+Optional `releasekit/common-images/minor-fixes/` and `releasekit/common-images/minor-improvements/` hold reviewed project originals under [the common-image convention](common-images.md). Each contains a `visual.yaml` source record, a `policy.yaml` copy of the original visual policy, and its selected raster files. Common asset paths are relative to that source directory; the agent imports their files into each release and keeps selected release asset paths local. The CLI does not automatically discover these source records, and the existing release and bundle schemas stay the same.
+
 Frontmatter fields are `title`, `alt`, and `sourceHash`. The source locale normally uses `sourceHash: null`. Translation marking records a fingerprint of the source title, alt text, and body. An image-free note can use empty alt text. An image-enabled note requires a complete visual brief and its active image assets before finalization. Its scaffold leaves `archetype` and `source` unselected; the authoring agent chooses both from the note and product evidence.
 
 `scene.source` is `generated` or `provided`. Legacy briefs may omit it: `object-detail` and `editorial-scene` use supplied media; other categories default to generated graphics. Those two supplied-only categories reject an explicit `generated` choice. For generated media, `variants` contains the configured dark/light pair or single theme. Supplied media can contain just `shared`, or distinct dark/light entries following project policy. Do not mix shared and themed entries. The shared slot retains native dimensions and bytes, does not depend on presentation palettes, and exports as one asset with `fallbackTheme: shared`. Missing supplied inputs remain pending. See [media sources](media-sources.md).
 
 The `releasekit-finalize` skill reviews the release and runs `releasekit finalize`. This CLI command 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.
+The generated JSON schemas shipped with the package are the structural source of truth. `releasekit export --out <directory>` produces one `release-notes.<locale>.json` per locale saved in the current release, with shared relative image assets in `assets/`. `--locale <locale>` selects one language and keeps the same filename pattern. Each JSON file uses the existing bundle schema and includes only display fields, configured image variants, its 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.
+
+Only `--out` is required. Without `--current`, export selects the unique release that no other saved release names as `previous`, regardless of version spelling, date, or directory order. No releases or cyclic links prevent automatic selection; multiple endpoints require `--current`. A draft endpoint must be finalized before export. Without `--limit`, export uses project `history.limit` (initially 3), following `previous` links. The locales saved in the current release determine the default language set, independently of later project configuration changes. Every selected release must contain each requested locale; missing or stale translations fail the whole export before creating output. The command result contains a `files` array of JSON paths, a `releases` count of version groups, and an `assets` count of image files copied once across locales.
 
 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

@@ -1,6 +1,6 @@
 # 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.
+Choose a truthful source for each note's image before composition and rendering: a supported generated explanation or approved supplied media. When a real capture or approved artwork is required but unavailable, request it and keep the image pending. Follow [image coverage](theme-pairing.md#coverage-and-repeat-runs); omit images only for the user's explicit text-only choices.
 
 | Source | Appropriate use | Agent action |
 | --- | --- | --- |
@@ -13,6 +13,8 @@ Use `provided` for another category whenever a real capture explains it better.
 
 For a map, distinguish an illustrative spatial explanation from an actual place, computed route, or coverage claim. Exact geography and routing need an approved map capture or verified source. Request a supplied image when that evidence is missing. Generated fictional geography is suitable only when explicitly identified as illustrative; visual plausibility does not establish geographic accuracy.
 
+Grouped minor notes should first follow [common-image reuse](common-images.md). An already generated and reviewed original can be imported again with its generated source and matching theme policy; it does not need another generation or a change to `provided` merely because it is reused.
+
 ## Missing input
 
 `releasekit image plan <version>` returns `action: provide` with `promptFile: null` when supplied media is needed. The instruction identifies the subject and import slot. Reuse available approved project files first. Otherwise ask the user for the specific capture, photograph, or content image. Continue independent copy and translation work while the asset is pending. Do not treat a missing capture as permission to synthesize its content.
@@ -27,8 +29,8 @@ A native photo, content image, or screenshot often has one authentic appearance.
 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.
+This requires `source: provided`; pass `--source provided` with the import to change the source and selected image together. 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.
+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. The CLI switches between shared and themed selections during import; keep the previous entries until it succeeds. See [image transitions](theme-pairing.md#switch-between-shared-and-themed-images). 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

@@ -10,9 +10,19 @@ This generation policy does not require inventing a second appearance for suppli
 
 Policy is captured in each release when it is prepared. Editing the project default affects new releases. To apply the current project policy to an existing draft, run `releasekit image plan <version> --sync-config`. Previously selected files are retained; themes disabled by the new policy are not exported. Ready releases must be reopened before their policy changes.
 
+## Coverage and repeat runs
+
+The default image scope is every note in the saved release, including grouped minor fixes and improvements. A grouped note has one visual brief and the configured image variants; its bullets do not become separate notes or image requests. Use [common images](common-images.md) to reuse the appropriate original across releases before planning new generation. Review the current `release.yaml` each time so newly added notes are included. A plain `releasekit-image` invocation uses this full scope without asking the user to pick important notes. Honor an explicitly limited request and the user's explicit text-only choices. If earlier agent prioritization disabled a note's image without such a choice, restore `image: true` and create or complete its visual brief in place, preserving its text, translations, and existing assets. Do not recreate the note. Missing supplied media stays pending instead of making the note text-only.
+
+Before planning, complete missing or unfinished briefs for the image-enabled notes. Preserve existing scene specifications and the release's captured theme policy when they have not been changed by the user's request. Import compatible common originals first, then run `releasekit image plan <version>` from the current saved state and handle the remaining requests across all notes. Respect `action: generate` versus `action: provide` and the configured dark/light or shared variants.
+
+On repeat runs, generate or import only missing images and missing required variants. Reuse existing valid imports and their completed reviews; do not regenerate an accepted image merely because the skill was invoked again. This includes a run after the user adds notes: complete those notes' missing images while retaining earlier ones. If everything is already current, generate nothing and provide the image-review and finalization guidance.
+
+An existing image reported as stale or invalid is unresolved, even though its file exists. Name the affected note and the reason, preserve the current selection, and offer a targeted correction; a missing-images request alone does not authorize replacing it. An explicit request to edit, regenerate, or replace an image applies to that target even when the plan considers it current; follow [replacement handling](#replace-or-regenerate-an-image). Keep other accepted images intact and check affected theme counterparts when the scene changes. Do not claim complete coverage or recommend finalization while required assets remain unresolved.
+
 ## One scene, two presentation treatments
 
-Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change presentation surfaces, neutral values, lighting, shadows, and necessary edge separation. Preserve meaningful status colors and natural photographic or material colors.
+Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change presentation surfaces, neutral values, lighting, shadows, and necessary edge separation. Preserve meaningful status colors and natural photographic or material colors. Lock the absence of accent for a neutral scene; when accent is justified, keep it on the same meaningful elements in both variants. A theme change does not introduce an accent.
 
 | Role | Dark treatment | Light treatment |
 | --- | --- | --- |
@@ -21,7 +31,7 @@ Both outputs share the same scene brief. Lock subject identity, geometry, object
 | 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 |
+| Optional interaction or status color | Preserve assignment and semantic hue, or keep absent | Preserve assignment and semantic hue, or keep absent |
 | Photo or product material | Preserve authentic appearance | Preserve authentic appearance |
 
 Do not invert pixels or shift brightness globally. A black lens remains a black lens on a light canvas. A warning remains the same warning color. If the underlying application has only one authentic UI theme, retain that UI and adapt the surrounding presentation rather than claiming an unsupported application theme.
@@ -29,13 +39,40 @@ Do not invert pixels or shift brightness globally. A black lens remains a black
 ## 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.
+2. Read the current image plan and the project's requested themes. Reuse existing current assets and import any suitable [common originals](common-images.md), then refresh the plan. The following rendering steps apply to `action: generate`; handle `action: provide` through the supplied-image workflow.
 3. Generate one requested variant using its prompt. Select and inspect the result.
 4. Import it. Re-run the image plan; a valid approved counterpart is now offered as a composition reference for the other theme.
 5. When the available tool supports image references or edits, use the counterpart for a constrained theme edit. Otherwise repeat the exact scene contract and inspect for layout drift. Never claim pixel-identical geometry from independent stochastic generations.
 6. Compare the pair. Both files should have the same pixel dimensions. Verify pose, crop, UI state, values, and semantic colors by sight, then import the selected counterpart.
 
-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.
+Use one file per theme, not a split canvas or a two-panel comparison image. Keep the current selection until a reviewed replacement is imported into the same slot. Do not restart the entire release when one small defect can be corrected locally.
+
+## Replace or regenerate an image
+
+Treat replacement and regeneration as an edit to the existing release, note ID, and affected theme. Reopen a ready release as a draft before editing it. Reuse its scene brief and current assets as needed for the requested correction. A request to regenerate an image still needs work even if the unchanged asset is reported as current by the plan; report the requested replacement as pending until it has been generated, reviewed, and imported.
+
+Keep the existing variant metadata while preparing the candidate, then run `releasekit image import <version> <note> --theme <theme> --file <selected-file>` for the same slot. Import validates the candidate and saves the new selection before removing unused managed images for this note, including older imports and obsolete shared/themed files. Reimporting identical bytes reuses the same file. Other selected variants, notes, releases, declared image references, and original source files outside the note's managed assets are preserved. If decoding or saving fails, the previous source and selection remain intact; report the replacement as pending.
+
+Keep temporary generation candidates outside the release's `assets/` directory and remove task-created discarded candidates when the replacement is complete. Do not add a new note or clear the old variant entry to make a replacement request. A replacement that remains one shared supplied image stays in the `shared` slot. Use [the transition flow](#switch-between-shared-and-themed-images) when the requested replacement changes between shared and themed usage.
+
+### Switch between shared and themed images
+
+Keep the current variant entries while preparing and reviewing the replacement. Import with the requested target `--theme`; the CLI replaces incompatible shared or themed entries automatically and cleans unused managed images after saving. When the requested media source also changes, pass `--source provided` or `--source generated` so that source and selection are saved together. Do not pre-clear variants or separately change `scene.source` merely to perform this transition.
+
+For example, replace generated dark/light illustrations with one approved capture:
+
+```sh
+releasekit image import 1.4.0 queue-action --theme shared --source provided --file ./approved-capture.png
+```
+
+To replace that shared image with distinct approved theme captures:
+
+```sh
+releasekit image import 1.4.0 queue-action --theme dark --file ./approved-dark.png
+releasekit image import 1.4.0 queue-action --theme light --file ./approved-light.png
+```
+
+The source remains supplied when `--source` is omitted. For a requested generated explanation instead, use `--source generated` on the first themed import; supplied-only subjects still require real media. Use only the release's configured themes. The first themed import replaces the shared selection, while any required counterpart remains pending until imported. Never synthesize or duplicate a supplied counterpart or describe a partial pair as complete. A source or scene change can also make an existing themed counterpart stale; review and refresh that affected image before finalization.
 
 ## External generation handoff
 

package/kit/references/visual-language.md

@@ -10,7 +10,7 @@ Select the simplest useful archetype in [composition-recipes.md](composition-rec
 
 Choose [generated or supplied media](media-sources.md) before rendering. Generate restrained flat explanations; use actual captures, photographs, or approved artwork when the appearance itself is the subject. Physical details and content previews require supplied images. A missing source stays pending; a fictional written scene is not a replacement for an actual product or content capture.
 
-For each note, derive the scene from that feature independently. Describe the relevant state and relationships: a control's state, two capabilities' association, a physical assembly, spatial connections, data proportions, or the announced content. Record supported facts and limits in `context`; write concrete correctness constraints in `composition`, `preserve`, and `avoid`. Those constraints are local to the note. A worked example supplies a reasoning pattern, not a layout to apply to other features. The agent chooses the representation and reviews its meaning; the CLI compiles the chosen brief and validates files.
+For each standalone note, derive the scene from that feature independently. Grouped minor notes follow [common-image reuse](common-images.md), keeping one generic scene per kind across releases and languages instead of deriving a new scene from each bullet list. Describe the relevant state and relationships: a control's state, two capabilities' association, a physical assembly, spatial connections, data proportions, or the announced content. Record supported facts and limits in `context`; write concrete correctness constraints in `composition`, `preserve`, and `avoid`. Those constraints are local to the note. A worked example supplies a reasoning pattern, not a layout to apply to other features. The agent chooses the representation and reviews its meaning; the CLI compiles the chosen brief and validates files.
 
 ## Composition grammar
 
@@ -31,15 +31,21 @@ Separate the canvas, base surface, raised surface, primary symbol, secondary det
 
 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.
+For icons, use a compact flat rounded-square tile with a neutral monochrome filled glyph and clear negative space. A typical tile occupies 20–24% of the canvas width, with the glyph around 50–65% of the tile width. Keep broad margins, uniform background fills, and related corner radii. Use color only when the feature gives it a functional meaning. Do not default to a colored badge, physical object, or modeled icon.
 
 Flat icons and symbol pairs have no perspective, extrusion, material texture, gradients, lighting, or shadows. Simplified interfaces may use restrained layer separation where it explains the actual control hierarchy. Preserve shading already present in supplied media. Do not add sculpted objects, decorative 3D, studio lighting, glass, glow, or bevels to generated release illustrations.
 
 ## Color has a job
 
-Use the project accent for the changed control, selected item, active route, or direct interaction cue. Do not color every surface. Preserve established meanings such as warnings, completed states, traffic or map semantics, and authentic content colors between themes.
+Start with a fully neutral composition. Establish the focal point through placement, scale, shape, spacing, and value contrast. An image can be complete without any accent, and a release can contain many entirely neutral images. A new feature, an important capability, or the main subject does not by itself represent an active or selected state.
 
-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.
+Treat the project accent as an available color, not an instruction to use it. Add it only when a specific supported state, action, or information distinction needs color to explain the change: for example, an enabled switch, a selected item, a revealed action, or an active route. Even an interaction can remain neutral when its geometry and value contrast already make it clear. Keep the colored area confined to that meaningful element; leave unrelated glyphs, tiles, and supporting surfaces neutral.
+
+In the shared scene's `composition`, explicitly state either that no accent is used or which element uses it and what it communicates. Preserve that assignment, including the absence of accent, in both themes. Do not invent a selection, badge, status dot, or secondary marker to justify color. For `icon-tile`, ordinary capability and maintenance symbols stay neutral. For `symbol-pair`, a simple association uses the same neutral treatment for both symbols.
+
+Preserve established meanings such as warnings, completed states, traffic or map semantics, chart categories, and authentic content colors between themes. These colors belong to supported information; a generic improvement or security note is not itself a success or protection status.
+
+Functional color remains available for colorful features. A supplied capture of a creative tool can retain its colorful output. A spatial view can require several functional colors. Actual content artwork retains its original appearance. The color should belong to the feature, rather than decorate a routine release card.
 
 ## Language independence
 
@@ -68,6 +74,6 @@ Make the brief concrete enough that another model can render the same scene. “
 
 ## Review the actual output
 
-Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. Attractive styling and theme similarity do not establish factual or structural correctness.
+Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. For each accent, identify the supported meaning that would become less clear without it; if there is none, remove it. Review the release images together for repeated decorative accents. Do not give every note one colored point or enforce a fixed quota of colored images. Attractive styling and theme similarity do not establish factual or structural correctness.
 
-For a pair, compare both outputs side by side using [theme-pairing.md](theme-pairing.md). Automated checks establish file integrity, dimensions, configured variants, and scene freshness; they do not prove visual correspondence or truthfulness. Correct a specific defect with a targeted edit instead of randomly regenerating every asset. Preserve accepted files and import the newly selected version.
+For a pair, compare both outputs side by side using [theme-pairing.md](theme-pairing.md). Automated checks establish file integrity, dimensions, configured variants, and scene freshness; they do not prove visual correspondence or truthfulness. Correct a specific defect with a targeted edit instead of randomly regenerating every asset. Preserve unrelated accepted assets. Import a reviewed replacement into the same note and theme slot so unused older managed files are removed; keep the previous selection until that import succeeds.

package/kit/references/workflow.md

@@ -4,19 +4,30 @@ Use the installed `releasekit` CLI, or the repository's compiled CLI when develo
 
 ## Create or continue
 
-The normal skill flow is `releasekit-draft` (source and selected translations), `releasekit-image` (required assets), then `releasekit-finalize` (review, validation, and local confirmation). Translation-only edits also belong to `releasekit-draft`. Skip image work for a text-only release; export follows finalization only when requested.
+The normal skill flow is `releasekit-draft` (source and selected translations), `releasekit-image` (required assets), then `releasekit-finalize` (review, validation, and local confirmation). Translation-only edits also belong to `releasekit-draft`. Skip image work for a release the user explicitly chose to keep text-only; export follows finalization only when requested.
 
-1. Read `releasekit/config.yaml` and any existing `release.yaml`. [Choose languages](#choose-languages) with the user before preparing or writing the draft. Honor the theme policy and product context.
+1. Read `releasekit/config.yaml` and any existing `release.yaml`. [Resolve languages](#choose-languages) from current project settings for a new draft or the saved selection for an existing draft. Ask only when a first-use choice or requested language change remains unresolved. Save the first-use selection in project config before preparation. Honor the theme policy and product context.
 2. For a new release, [resolve the version and Git boundaries from the repository](#resolve-release-scope-from-the-repository). Reuse explicit choices and saved boundaries, inspect the relevant release line, and supply the CLI arguments yourself. Briefly state the selected scope and continue when the evidence is clear. For first-use requests with unresolved earlier-history scope, follow [the adoption guide](adoption.md) to summarize, analyze, or skip the period through the baseline.
 3. Run `releasekit prepare`. It creates only `release.yaml`, including the pinned comparison start and end SHAs. Inspect the pinned Git evidence as described below: baseline summaries read the snapshot; other drafts read history, changed paths, and relevant diffs. Do not save a full patch or a separate changed-file index.
-4. Save the selected `sourceLocale` and `locales` in this release before adding notes with `releasekit note add <version> <id>`. Fill the source Markdown and attach evidence paths or commit SHAs to `release.yaml`, using snapshot evidence for a baseline summary. A note can be text-only with `--no-image` when that is the intended editorial choice.
+4. Save the selected `sourceLocale` and `locales` in this release. Use [Group minor changes](writing.md#group-minor-changes) to select standalone notes and separate minor-fix and minor-improvement groups before adding notes with `releasekit note add <version> <id>`. Give each group the corresponding `--category fix` or `--category improvement`; its bullet items do not get separate notes. Fill the source Markdown and attach evidence paths or commit SHAs to `release.yaml`, using snapshot evidence for a baseline summary. Keep every note image-enabled by default; use `--no-image` only for the user's explicit text-only choice, never to select just the important notes.
 5. As part of `releasekit-draft`, [translate the selected locales](#translate-selected-locales) and mark reviewed translations current. Finish the source and selected translations before recommending image work, unless the user explicitly limited the draft scope.
-6. Use `releasekit-image` to choose generated or supplied media and complete each required visual brief. Run `releasekit image plan`, then handle each request by its action: generate configured variants for `generate`, or find/request an approved capture/image for `provide`. Review and import selected files, using one shared supplied asset when appropriate. Preserve accepted images and manual edits.
+6. Use `releasekit-image` to cover all current drafted notes, including later additions, under [the coverage policy](theme-pairing.md#coverage-and-repeat-runs). For minor groups, [reuse common originals](common-images.md) before generating new images. Choose generated or supplied media and complete each missing visual brief, reusing existing valid images on repeat runs. Run `releasekit image plan`, then handle each request by its action: generate configured variants for `generate`, or find/request an approved capture/image for `provide`. Review and import selected files, using one shared supplied asset when appropriate. Preserve unrelated accepted images and manual edits. For a replacement or regeneration, import into the same note with the intended theme; follow [image transitions](theme-pairing.md#switch-between-shared-and-themed-images) when changing shared/themed usage. Unused managed files are removed after the new selection is saved.
 7. Use `releasekit-finalize` to review factual and visual accuracy, run `releasekit validate <version>`, resolve errors and review warnings, then run `releasekit finalize <version>`. Confirm `status: ready` and a recorded content fingerprint. Review is part of finalization; a validation report alone does not complete this step.
-8. If requested, export the current version and recent history to a new output directory. Pass `--locale <locale>` explicitly, using the requested output language or the confirmed source language when none was specified; the CLI default comes from the project config. A finalized release is a complete local result even without an export. Finalization does not tag, commit, push, deploy, or publish anything.
+8. If requested, run `releasekit export --out <directory>` to export recent history to a new output directory. Omit `--current` to use the unique release with no successor in the saved `previous` links; pass an explicitly requested version or resolve multiple release endpoints with `--current <version>`. Omit `--limit` to use project `history.limit` (initially 3). Omit `--locale` to export all locales saved in the current release as separate `release-notes.<locale>.json` files sharing one `assets/` directory; pass it only when the user requests a specific output language. Every selected version must contain those locales. A finalized release is a complete local result even without an export. Finalization does not tag, commit, push, deploy, or publish anything.
 
 For an existing draft, read and edit the existing content. `prepare` never overwrites a release. Do not recreate a folder as a shortcut for refreshing one note. Reopen a ready release by setting `status: draft` and `contentHash: null`, then make the targeted change and finalize again.
 
+## Revise draft notes
+
+Use the user's requested feature or wording to identify the affected notes in the saved release. Keep its pinned Git boundaries and other releases unchanged. The user can ask for copy changes, exclude a feature, or include a feature that the draft missed without invoking a skill manually.
+
+- For wording changes, edit the existing source and refresh affected translations. If only part of a note is excluded, revise that note and its visual brief as needed.
+- To consolidate minor notes, follow [the grouping guidance](writing.md#group-minor-changes). Reuse the release's existing group or add one with `--category fix` or `--category improvement`. Save the supported content, manual edits, and combined evidence in the group, and preserve coverage in every selected locale before removing the superseded notes with the CLI as described below. Refresh affected translations and fingerprints, and review the group's visual brief and alt text if its scope changed. A change only to the minor bullet list preserves the generic common scene and current images; follow [common-image reuse](common-images.md). Leave unrelated notes and other releases intact.
+- To include an omitted feature, verify it against the pinned evidence. For a minor change, reuse its group or create one with the appropriate `--category fix` or `--category improvement`. For a change that warrants individual attention, extend a related standalone note or run `releasekit note add <version> <id>`. Write or update the affected source, selected translations, and evidence. New notes are image-enabled by default; use `--no-image` only when the user explicitly asks for text-only content. Keep required images pending so the next `releasekit-image` run picks up the new note. Explain a requested feature outside the saved scope instead of silently expanding the Git range.
+- To exclude an entire note, run `releasekit note remove <version> <id>`. Let the CLI remove its metadata entry, complete note folder, visual brief, generated prompts, and unused managed images. Removing only the `release.yaml` entry leaves files behind. The command preserves assets referenced by remaining visuals, including other releases, and source originals outside managed assets; report any retained shared assets. If another scene references the note's text, brief, or prompts, resolve that dependency before removal.
+
+After additions or removals, validate the release and report outstanding copy, translation, or image work. The CLI clears a previous `emptyReason` when adding a note. Removing the last note leaves an editable empty draft; add another note or write a factual `emptyReason` before finalization. Do not invent a reason to hide an unfinished draft. A failed metadata save restores removed files or rolls back newly added note files.
+
 ## Resolve release scope from the repository
 
 Treat versions, tags, commit SHAs, and CLI arguments as repository discovery work. Missing flags in the user's request are not by themselves a reason to open the question UI. Read the request, saved releases, applicable history-start settings, local tags, and release metadata before deciding that scope is missing.
@@ -32,17 +43,17 @@ Ask only when inspection leaves materially different scopes, such as competing p
 
 ## Choose languages
 
-Use English (`en-US`) as the default original language for new releases. Honor an explicitly chosen source language or intentional project setting, and preserve an existing release's saved source and language selection. Do not treat an older generated Korean-original/English-translation default as a confirmed preference. The user's conversation language suggests a translation target; it does not change the original language.
+For every new draft, use the current `sourceLocale` and complete ordered `locales` list from `releasekit/config.yaml`. Once the project has saved releases, proceed without a language picker, alternative language suggestions, or confirmation, including when config selects only one language. Previous releases supply history boundaries; their language lists do not override current project settings. The conversation language does not change configured languages. For an existing draft, reuse its saved selection unless the user explicitly requests a change.
 
-When translation languages have not been chosen, ask one concise question in the user's language using the [native question UI](#ask-with-the-native-question-ui) when available. State the original language as English by default and ask which additional translations, if any, to include. Suggest the user's current language first, using an explicit language preference when available and otherwise the current conversation. Do not detect or persist translation languages from the CLI host's operating-system locale.
+Only on first use with no saved releases, honor explicit language choices and intentional project settings first. If translations remain unchosen, ask one concise question in the user's language using the [native question UI](#ask-with-the-native-question-ui) when available. Use English (`en-US`) as the default original and ask which additional translations, if any, to include. Suggest the user's current language first, using an explicit language preference when available and otherwise the current conversation; it does not change the original language. Do not detect or persist translation languages from the CLI host's operating-system locale.
 
-For a Korean-speaking user, recommend English original with Korean translation, and offer English only as an alternative. Explicitly invite the user to enter additional languages, for example Korean, Japanese, and German together, using the tool's built-in free-text input. Accept language names or locale codes and keep that input available; do not duplicate a built-in Other option or assume multi-select support. Each option should describe a complete translation set. If the user's language is the same as the source, recommend the source alone and invite other translations without proposing a duplicate; regional variants require an explicit request. If the current language cannot be inferred, ask for optional translation languages without inventing a recommendation.
+For that first-use question with a Korean-speaking user and the default English source, recommend English original with Korean translation, and offer English only as an alternative. Explicitly invite the user to enter additional languages, for example Korean, Japanese, and German together, using the tool's built-in free-text input. Accept language names or locale codes and keep that input available; do not duplicate a built-in Other option or assume multi-select support. Each option should describe a complete translation set. If the user's language is the same as the source, recommend the source alone and invite other translations without proposing a duplicate; regional variants require an explicit request. If the current language cannot be inferred, ask for optional translation languages without inventing a recommendation.
 
-Reuse choices already specified for this release, including an explicit request to use configured languages or no translations. A language list supplied in answer to the translation question adds translation targets while retaining the source; do not ask which is the original merely because several languages were entered. An explicit request to write only in one language sets that source with no translations, and an explicit source-language change takes precedence over the English default. Ask only for an unresolved choice. While a necessary translation answer is pending, follow [the answer-waiting procedure](#wait-for-the-users-answer) before preparing the release, scaffolding notes, or writing copy; independent Git inspection may continue. A preselected option or an unanswered prompt does not confirm translations.
+An explicit language-change request takes precedence over the configured or saved selection. Reuse choices already specified for this release, including an explicit request to use configured languages or no translations. A language list supplied in answer to the translation question adds translation targets while retaining the source; do not ask which is the original merely because several languages were entered. An explicit request to write only in one language sets that source with no translations, and an explicit source-language change takes precedence over the English default. Ask only for an unresolved choice. While a necessary translation answer is pending, follow [the answer-waiting procedure](#wait-for-the-users-answer) before preparing the release, scaffolding notes, or writing copy; independent Git inspection may continue. A preselected option or an unanswered prompt does not confirm translations.
 
-Use locale codes such as `en-US`, `ko-KR`, and `ja-JP` in the files. New project configuration starts with `sourceLocale: en-US` and `locales: [en-US]`; translation suggestions are not enabled until selected. Set `sourceLocale` to the original language and `locales` to the unique list containing that source first plus all selected translations. A single-language release has only its source in `locales`. `prepare` copies project defaults, so update `releasekit/releases/<version>/release.yaml` with the confirmed selection immediately afterward and before `note add`. Change `releasekit/config.yaml` only when the user asks to change future project defaults.
+Use locale codes such as `en-US`, `ko-KR`, and `ja-JP` in the files. New project configuration starts with `sourceLocale: en-US` and `locales: [en-US]`; translation suggestions are not enabled until selected. Save the first-use choice directly in `releasekit/config.yaml`: set `sourceLocale` to the original language and `locales` to the unique list containing that source first plus all selected translations. A single-language choice saves only its source in `locales`. Preserve unrelated config fields. This choice establishes project defaults without another confirmation; write it before `prepare`, which copies the current project languages into `releasekit/releases/<version>/release.yaml`. If the first draft already exists, save the choice in both config and that draft before `note add`. Later new drafts follow current config automatically, including after a requested project language change. Save an explicitly release-only override in the affected `release.yaml` before scaffolding notes, preserving project defaults.
 
-For an existing draft, apply a changed selection in place. Create missing `notes/<id>/<locale>.md` files for each existing note using the [content contract](format.md), preserving existing copy and files for deselected languages. If the source language changes, review the new source and all selected translations, then mark reviewed translations against the new source. Keep the change scoped to this release.
+For an existing draft, apply a changed selection in place. Create missing `notes/<id>/<locale>.md` files for each existing note using the [content contract](format.md), preserving existing copy and files for deselected languages. If the source language changes, review the new source and all selected translations, then mark reviewed translations against the new source. Keep the change scoped to this release unless the user also requests a project language change.
 
 ## Translate selected locales
 
@@ -56,9 +67,11 @@ Review each affected translation against the current source, then run `releaseki
 
 Apply this guidance throughout all three ReleaseKit skills, including questions within a step and choices about what to do next. Read the request, conversation, saved release, and relevant evidence before asking. Reuse established choices and resolve routine editorial or implementation details with judgment. Ask when missing information or a user preference materially affects the result and cannot be resolved from that context. Resolve technical parameters such as Git ranges through [repository inspection](#resolve-release-scope-from-the-repository); the picker is for consequential user choices. Draft language selection follows [Choose languages](#choose-languages).
 
+Keep at most one unanswered question request in the conversation across all skills, releases, and question tools. Before every question-tool call, check for a pending request, including one opened before this skill began. If any question in it remains unanswered, do not call `request_user_input`, `request_user_input_async`, or another question tool, even for a different topic. Keep newly discovered questions queued in conversation context until the current request is resolved. Do not replace, refresh, or expand an open picker by issuing another request, and never run question calls in parallel.
+
 For a decision needed before proceeding, prefer a native question tool that waits for the answer when exposed and permitted. In Codex, use `request_user_input` only when its mode restrictions and tool instructions allow the question. Otherwise, `request_user_input_async` requires the explicit [answer-waiting procedure](#wait-for-the-users-answer). In another agent, use its available equivalent. If no supported question tool can preserve that wait, ask in chat and yield for a reply. Follow the tool's current schema; do not change modes or install anything solely to display a picker.
 
-Bundle related missing decisions into as few short questions as practical, within the tool's limits. Use the user's language and identify the affected release or notes. When there are meaningful alternatives, offer a few distinct, actionable choices and put the recommended one first, explaining its effect briefly. Keep built-in free-text input available; do not duplicate a built-in Other option or assume multi-select support. For open-ended text such as a path or terminology, use the tool's free-text question when supported instead of inventing arbitrary choices.
+When no request is pending, bundle related missing decisions into one tool call within its question limit. Queue any remaining decisions for later calls, after this request is resolved. Use the user's language and identify the affected release or notes. When there are meaningful alternatives, offer a few distinct, actionable choices and put the recommended one first, explaining its effect briefly. Keep built-in free-text input available; do not duplicate a built-in Other option or assume multi-select support. For open-ended text such as a path or terminology, use the tool's free-text question when supported instead of inventing arbitrary choices.
 
 Use structured questions for text decisions and existing file paths. Request uploads, screenshots, or photographs through the conversation's supported attachment flow, not through a text-only question tool. Reuse suitable approved files already available before requesting new input.
 
@@ -68,7 +81,7 @@ Questions should address an actual unresolved decision, for example:
 
 | Skill | Ask when needed | Reuse or decide without another question |
 | --- | --- | --- |
-| `releasekit-draft` | Unchosen translation languages, unresolved translation scope or product terminology, a conflicting source-language request, earlier-history treatment for first use, or materially different release scopes that repository inspection cannot resolve. | Established language choices and terminology, current translations, saved boundaries, and versions or Git ranges resolved from release metadata, tags, and ancestry. |
+| `releasekit-draft` | Unchosen first-use translation languages, an ambiguous requested language change, unresolved translation scope or product terminology, earlier-history treatment for first use, or materially different release scopes that repository inspection cannot resolve. | Current project languages for new drafts, saved selections for existing drafts, including a single-language choice; intentional first-use language settings; established terminology, current translations, saved boundaries, and versions or Git ranges resolved from release metadata, tags, and ancestry. |
 | `releasekit-image` | Ambiguous target notes or a meaningful choice among suitable approved reference images. | Captured theme policy, selected assets, and media-source requirements. Required supplied media must stay supplied; do not offer generation as an alternative. |
 | `releasekit-finalize` | Ambiguous target release or requested export choices that neither the request nor established settings resolves. | Requested fixes and local finalization, completed review when content is unchanged, valid export defaults, and already requested export. |
 
@@ -80,13 +93,13 @@ A successful question-tool return may only acknowledge that the question was dis
 
 After an asynchronous question:
 
-1. Continue only authorized work that does not depend on the unanswered choice. Keep dependent preparation, settings writes, copy, image work, finalization, export, or the proposed next step pending as applicable.
+1. Retain the pending request identifier when supplied, its unanswered questions, and queued questions in conversation context. Continue only authorized work that does not depend on the unanswered choice; discovering another missing decision queues it without opening a new picker or asking a competing question in chat. Keep dependent preparation, settings writes, copy, image work, finalization, export, or the proposed next step pending as applicable.
 2. When no independent work remains, use an input-aware wait tool, such as `clock.sleep` when exposed, in calls of at most 60 seconds. Check for a submitted reply after each wait and keep waiting if none arrived. An elapsed wait is not permission to choose a default. Do not simulate waiting with shell sleeps, dummy commands, or unrelated tool calls.
-3. Keep the question open while waiting. Do not send a final response just to say that you are waiting or announce completion while its answer is pending; ending the turn can clear the unanswered picker. A skill transition does not resolve the pending decision or allow dependent work to proceed. A short progress update belongs in commentary and must not claim a selection.
+3. Keep the question open while waiting. Do not send a final response just to say that you are waiting or announce completion while its answer is pending; ending the turn can clear the unanswered picker. A skill transition or resumed context must retain the pending request and queue; neither allows a new picker or dependent work to proceed. A short progress update belongs in commentary and must not claim a selection.
 
-Check that an input-aware wait is available before opening a nonblocking picker. If it is unavailable, ask the question in chat and yield for the user's reply. If an opened picker is cleared without an answer or can no longer be kept open, preserve the unresolved decision, state that no answer was received, and ask it once in chat instead. Do not duplicate a still-open usable picker or treat the fallback as an answer.
+Check that an input-aware wait is available before opening a nonblocking picker. If it is unavailable, ask the question in chat and yield for the user's reply. If the environment confirms an opened picker was cleared without an answer or cannot remain open, preserve its unresolved questions, state that no answer was received, and ask only those questions once in chat instead. Keep that fallback pending before asking queued questions. Lack of a reply or visibility alone does not establish that a picker closed; continue waiting when its state is uncertain. Do not duplicate a still-open usable picker or treat a cleanup notification or fallback as an answer.
 
-After a submitted answer, apply that choice and resume the work it unblocks. Keep any other unanswered decisions pending, and reuse resolved choices across skill transitions. An explicit stop or deferral pauses the affected work without selecting an option. Continue already requested work that needs no new choice without introducing another confirmation.
+After a submitted answer, apply that choice and resume the work it unblocks. A partial reply leaves the other questions in that request pending. Only after every question in the current request is answered or explicitly stopped, deferred, or delegated to the agent may another request be opened. Recheck queued questions against the new answers and completed work, discard those already resolved or no longer needed, and ask only the remaining necessary questions. Reuse resolved choices across skill transitions. An explicit stop or deferral pauses the affected work without selecting an option. Continue already requested work that needs no new choice without introducing another confirmation.
 
 ## Continue to the next step
 
@@ -98,17 +111,30 @@ Choose the next action from the actual state, with priority for useful work that
 | --- | --- |
 | Source copy or evidence is incomplete, or the user wants revisions | Continue `releasekit-draft` for the affected notes, including selected translations. |
 | Selected translations are missing or stale | Continue `releasekit-draft` for the affected languages and notes using [Translate selected locales](#translate-selected-locales). |
-| Source and translations are complete; required briefs or assets remain | Recommend `releasekit-image` to complete the briefs and handle the assets. Run image planning after the briefs are valid. |
+| Source and translations are complete; required briefs or images are missing | Recommend `releasekit-image` to fill missing images across all current notes under [the coverage policy](theme-pairing.md#coverage-and-repeat-runs). Reuse valid images from previous runs. |
+| Existing images are stale or invalid | Identify the affected notes and offer a targeted image correction or replacement. Preserve their selections until replacements succeed. |
 | A supplied image or generation tool is unavailable | Name the exact missing input and keep assets pending. Offer unfinished draft or translation work only when it can usefully proceed. |
 | Copy, translations, and required images are complete; the release is a draft | Recommend `releasekit-finalize` to review, resolve validation findings, and mark the release ready in one step. Reuse completed review when content is unchanged. |
 | The release is ready and a requested export remains | Continue with the selected locale, version window, and a new output directory; collect only missing export choices. |
 | The release is ready and no export was requested, or the requested export is delivered | Deliver the result links and finish. |
 
-Resolve validation failures before finalization or export. Skip image work for text-only notes and translation work for a single-language release or current translations. An intentionally empty release with a factual `emptyReason` can proceed directly to `releasekit-finalize`. Do not recommend completed work again merely to follow a fixed sequence.
+Resolve validation failures before finalization or export. Skip image work for notes the user explicitly chose to keep text-only and translation work for a single-language release or current translations. An intentionally empty release with a factual `emptyReason` can proceed directly to `releasekit-finalize`. Do not recommend completed work again merely to follow a fixed sequence.
+
+Continue steps already included in the user's request in the same conversation, using the corresponding installed skill or its shared references and CLI. Announce the next action without asking for another confirmation. If the release still needs work beyond the completed request, first check for any pending question request. Queue the next-step choice while one remains pending; a completed stage does not allow another picker. Otherwise, use the [native question UI](#ask-with-the-native-question-ui) to offer the recommended next action first, one useful alternative when available, and a choice to finish the current stage. At the end of a completed drafting step, use [Finish drafting](#complete-drafting-and-invite-revisions); for other stages or incomplete drafting, use Stop for now. Keep choices concise and describe the work in ordinary language so the user does not need to know a skill name or CLI command. Preserve free-text input for another direction, then follow [the answer-waiting procedure](#wait-for-the-users-answer). Keep the picker open until the user answers; an unanswered or preselected option does not start additional work.
+
+Carry out the selected step without making the user invoke another skill manually. Reuse the release version, pinned range, language choices, and accepted assets. After that step completes or encounters a blocker, return to this state check and recommend the next useful action. Honor an explicit request to stop, pause, or do only the current step without follow-up questions. Do not open any new question request while an earlier request is still pending, even if it concerns another step or release. Once the release is finalized and any requested export is delivered, finish with the result links; publishing is not an automatic next stage.
+
+### Complete drafting and invite revisions
+
+Once the requested source-copy and translation work is complete, label the stage-completion choice **Finish drafting** (in Korean, **초안 작성 완료**). Its description should explain that the draft is saved and the user can ask the agent for revisions after reading it. Avoid labels such as "finish in draft status" or "초안 상태로 마무리", which suggest permanently ending the release work. Keep incomplete copy or translations visible; do not offer this completion choice while requested drafting work remains.
+
+When the user selects this choice, or the requested drafting-only work is complete, report what was drafted, link the written notes and translations, and state any deferred translations, pending images, or finalization work. Invite the user to request changes in the same conversation, for example, "Rewrite this feature description," "Leave this feature out of the release notes," or "Add the feature that was missed." Explain that the agent will revise the saved draft and refresh affected translations. The user does not need to edit files or invoke a skill manually. Keep the release in draft status and finish this response without opening another next-step picker or starting image work or finalization. Resume the saved release when the user requests revisions or a later stage.
+
+### Review images and continue
 
-Continue steps already included in the user's request in the same conversation, using the corresponding installed skill or its shared references and CLI. Announce the next action without asking for another confirmation. If the release still needs work beyond the completed request, use the [native question UI](#ask-with-the-native-question-ui) to offer the recommended next action first, one useful alternative when available, and a Stop for now choice. Keep choices concise and describe the work in ordinary language so the user does not need to know a skill name or CLI command. Preserve free-text input for another direction, then follow [the answer-waiting procedure](#wait-for-the-users-answer). Keep the picker open until the user answers; an unanswered or preselected option does not start additional work.
+After completing image work, show previews or useful links to the accepted images and report coverage against the release's current notes and theme policy. Invite the user to ask the agent to revise an image or replace it with another approved image, for example, "Simplify the queue feature image" or "Replace this feature image with this screenshot." The agent handles the existing note and affected image slots; the user does not need to edit files or invoke another skill manually.
 
-Carry out the selected step without making the user invoke another skill manually. Reuse the release version, pinned range, language choices, and accepted assets. After that step completes or encounters a blocker, return to this state check and recommend the next useful action. Honor an explicit request to stop, pause, or do only the current step without follow-up questions. Do not repeat a question while the same input is still pending. Once the release is finalized and any requested export is delivered, finish with the result links; publishing is not an automatic next stage.
+When required images, copy, and translations are complete, explain that the user can ask for `releasekit-finalize` to review and confirm this release if no image changes are needed. When offering next steps, use **Finalize release** as the recommended action and **Request image changes or replacement** as the useful alternative, retaining the option to stop for now. Continue finalization without another confirmation when it was already requested. For an image-only request, deliver the images with this guidance and keep the release as a draft. If a repeat run finds no missing images, reuse the same guidance without generating new ones. Name any missing, stale, or invalid assets and their next action before offering completion; unresolved images still block finalization.
 
 ## Inspect the pinned changes
 

package/kit/references/writing.md

@@ -1,31 +1,123 @@
 # Writing product release notes
 
-Write for the person using the product, using its actual terminology and the configured language. Prefer a concrete capability title and a short paragraph about what changed. Add a second paragraph for the action path, requirements, or a material limitation when supported by evidence. More detail is appropriate for a genuinely complex change; concision is not a reason to remove necessary operating instructions.
+Write for the person using the product, using its actual terminology and the configured language. Use a concise title naming the capability, action, or changed result, followed by body copy explaining what the user can do or what now happens. A clear description can be complete on its own. Add usage guidance only when readers need it to understand or use this specific change.
 
-Group commits into user-visible changes. Let the final diff and target revision establish what shipped. A merged commit can have been reverted; a feature can have been renamed; internal maintenance can have no useful user-facing announcement. Do not translate each commit subject into a separate card.
+Group commits into user-visible changes. Let the final diff and target revision establish what shipped. A merged commit can have been reverted; a feature can have been renamed; internal maintenance can have no useful user-facing announcement. Do not translate each commit subject into a separate card. Decide which changes warrant standalone notes and which belong in [minor-change groups](#group-minor-changes) before scaffolding notes.
 
 For a first-use product introduction (`initialContent: summary`), describe the product and useful capabilities present at the pinned baseline. Read supporting snapshot files without reconstructing the historical commit sequence. Avoid “new,” “now available,” or “initial launch” unless that timing is established by the user or product evidence. Use [the adoption guide](adoption.md) for the selected scope and evidence rules.
 
 Keep source evidence with each note. Do not invent performance percentages, privacy claims, security guarantees, supported platforms, eligibility, enabled-by-default behavior, or menu locations. If evidence is incomplete, explain the uncertainty to the author and keep the affected statement out of finalized copy until resolved.
 
-Avoid hype, congratulations, “we are excited,” vague “various enhancements,” engineering implementation details with no user consequence, and repeated starts that make every note sound the same. Use active statements about the product's behavior. A small fix can be one precise sentence.
+Avoid hype, congratulations, “we are excited,” vague “various enhancements,” engineering implementation details with no user consequence, and repeated starts that make every note sound the same. Use active statements about the product's behavior. A small fix can be one precise bullet in a grouped note.
+
+## Group minor changes
+
+Choose note size by user impact. Keep major new capabilities, meaningful workflow changes, and fixes with substantial consequences as standalone notes. Group small user-visible corrections and incremental conveniences, including small additions to existing features, instead of giving every change its own title and note. Patch size, commit count, and a `feature` or `fix` label do not determine importance: a short fix that prevents data loss or restores a core workflow can warrant a standalone note. Omit internal maintenance with no useful user-facing consequence, and respect the author's explicit inclusion, exclusion, or emphasis.
+
+Within each release, collect minor changes into these separate notes using the existing categories. Use natural equivalents in other selected locales.
+
+| Kind | Category | Korean title | English title |
+| --- | --- | --- | --- |
+| Minor bug fixes | `fix` | 사소한 오류 수정 | Minor Fixes |
+| Minor improvements and conveniences | `improvement` | 사소한 기능 향상 | Minor Improvements |
+
+Reuse an existing group; otherwise create one note per nonempty kind, normally after the standalone notes. A group may contain only one bullet; do not promote it to a standalone note or invent more items just to fill the group. Omit empty groups. Grouping stays within the release's pinned scope, even when another version has the same group title or note ID. A baseline introduction still follows the snapshot rules above and does not invent a history of minor changes.
+
+Start the body directly with an unordered Markdown list. Write one short, concrete change per `-` bullet, without an introductory paragraph, per-item titles, or nested explanations. Combine commits that produce the same outcome. Different product areas can share a minor group; each bullet retains its own meaning. State what changed instead of a vague assurance that bugs were fixed. Add a usage path or condition only when essential under [the body guidance](#body-copy). Include each change once, either in a standalone note or in a minor group.
+
+Attach the relevant paths or commits for every bullet to the group note's evidence metadata. Preserve the same grouping, bullet coverage, and order across locales. When consolidating an existing draft, move its supported content, manual edits, and evidence before removing superseded notes; follow [Revise draft notes](workflow.md#revise-draft-notes). A group is one note with the normal image policy; its bullets are not separate notes or image requests. Use [a reusable common image](common-images.md) for each kind, keeping its generic scene independent of the release's text and bullet list.
+
+These fictional examples assume that all listed changes are established and minor in their product context:
+
+Title: 사소한 오류 수정
+
+- 긴 항목 이름이 도구 설명에서 잘리던 문제를 수정했습니다.
+- 설정 설명의 오탈자를 수정했습니다.
+
+Title: 사소한 기능 향상
+
+- 최근 사용한 정렬 방식을 기억합니다.
+- 대기열 목록에 항목 수를 표시합니다.
+
+## Body copy
+
+For a standalone note, lead with the concrete capability or changed behavior. For an action, say what the user can do and how when the gesture or control is central. For automatic behavior, say when it happens and what the product does. For an improvement, identify the aspect that changed; for a fix, name the affected action or condition and the corrected problem. An opening that only says a feature was added, updated, or improved gives the reader too little information.
+
+Usually stop once the changed behavior is clear. Menu paths, setup steps, and usage conditions are optional context, not a checklist for every note. Include them only when their omission would leave a non-obvious feature difficult to find or use, or materially misrepresent its availability or behavior. Automatic improvements, bug fixes, and changes to familiar controls generally need no separate usage instructions. Omit obvious navigation, routine prerequisites, and conditions already clear from the copy. Keep any necessary details concise and grounded in product evidence. Benefits and reassuring statements about unchanged behavior also need evidence and a reason to be included.
+
+Let the content determine length. One sentence can fully explain a small change. Add paragraphs only when there is more useful information to convey; use bullets when several related changes, choices, or necessary steps are easier to scan. Keep standalone notes focused on a coherent user task. Collect remaining minor changes using [the grouping guidance](#group-minor-changes), preserving their specifics in the bullets. Do not pad a short note with a repeated title, a stock closing sentence, unrelated maintenance, or future work presented as shipped functionality.
+
+## Newly supported capabilities
+
+When the pinned before-and-after evidence shows that an action was unsupported before this release and is supported at the target revision, prefer “이제 ~할 수 있습니다.” in Korean or a natural equivalent such as “You can now …” in English when first-time availability is the main news. A direct action or behavior statement can be clearer when the interaction itself is the news. State the newly possible action; include a condition only when it materially limits the claim and is not already clear from the wording. If support was added only for a format, platform, or mode, name that scope instead of implying the whole feature is new. A `feature` category or the current implementation alone does not establish prior lack of support.
+
+Use this construction selectively where the transition matters most. Read the notes together in release order for each locale, and avoid repeating “이제,” “~할 수 있습니다,” or “You can now” in consecutive openings or throughout the release. When several notes qualify, prioritize this opening where it best highlights a newly possible action; vary other openings with the action or automatic result itself, or direct statements such as “~을 지원합니다,” preserving the meaning and scope. Describe what the product does instead of cycling through generic added, supported, and improved formulas. Merely replacing “이제” with “새롭게” or “드디어” does not resolve a repetitive sentence pattern. Use editorial judgment rather than a fixed count or quota.
+
+Describe improvements to existing support, performance changes, and bug fixes directly without implying first-time support. If earlier support is uncertain, describe only the verified behavior without claiming it is newly available. The first-use introduction evidence rule above still applies. These fictional examples assume the change in the left column is established:
+
+| Established change | Suitable Korean body wording |
+| --- | --- |
+| Batch renaming was unsupported and is now supported | 이제 여러 파일의 이름을 한 번에 변경할 수 있습니다. |
+| A new right-swipe gesture adds a saved item to the queue | 저장한 항목을 오른쪽으로 스와이프하면 대기열에 추가됩니다. |
+| SVG export was added, and a nearby note already uses the same opening | SVG 형식 내보내기를 지원합니다. |
+| Existing batch renaming became faster | 여러 파일의 이름을 변경할 때 처리 속도를 개선했습니다. |
+| An existing save action could crash | 저장 중 앱이 종료되던 문제를 수정했습니다. |
+
+## Titles
+
+These rules apply to standalone notes. Grouped minor notes use [the summary headings above](#group-minor-changes), with each specific change stated in a bullet.
+
+Name the capability, action, or changed result the reader should notice. Keep the product's established terminology and the scope that makes the change recognizable, such as a gesture, affected interaction, mode, or condition. The title helps the reader identify the change; the body explains its behavior and use.
+
+A major new capability can use its feature name alone when that name clearly communicates what is being introduced. An addition within an existing feature needs its added scope in the title, but a concrete action such as `스와이프로 대기열 추가` already names that scope. It does not need an extra availability label. A `feature` category alone does not establish that the whole capability is new. For a first-use product introduction, feature names can describe the baseline capabilities without claiming a change or launch.
+
+For improvements, fixes, and other changes to existing functionality, retain the actual change. Use a specific outcome such as `더 빠른 파일 검색`, or an affected area with a meaningful qualifier such as `대화 삭제 동작 개선` or `저장 중 앱 종료 문제 수정`. An outcome can already express the improvement; a bare area such as `대화 삭제` does not explain an interaction improvement. Choose the most specific wording established by the evidence.
+
+Keep titles as compact, natural phrases, including concise action phrases. English action titles such as `Add to Queue with a Swipe` are valid; Korean can use `스와이프로 대기열 추가` without a sentence-like `~하기` ending. When needed, put complete instructions, menu paths, and longer explanations in the body. Established operation names such as `되돌리기` are valid; do not mechanically strip endings or enforce a fixed character limit.
+
+Use words such as `지원`, `추가`, `개선`, `수정`, `업데이트`, and their locale equivalents only when they contribute meaning. Remove a redundant announcement suffix when the action or result is already clear: `스와이프로 대기열 추가 지원` becomes `스와이프로 대기열 추가`. Keep `추가` here because adding to the queue is the user action. Keep compatibility wording when it distinguishes support for an existing tool from introducing that tool, as in `화면 읽기 프로그램 지원`. Neither appending nor deleting the same suffix from every title is an editorial rule.
+
+These fictional examples assume the change in the first column is established:
+
+| Established change | Too vague or padded | Suitable title |
+| --- | --- | --- |
+| A swipe gesture was added for queueing saved items | 스와이프로 대기열 추가 지원 | 스와이프로 대기열 추가 |
+| Existing conversation deletion interaction was improved | 대화 삭제 | 대화 삭제 동작 개선 |
+| An existing save action could crash | 저장 | 저장 중 앱 종료 문제 수정 |
+| Existing batch renaming became faster | Batch renaming improvements | Faster batch renaming |
+| Batch deletion was added to existing conversation deletion | 대화 일괄 삭제 기능 지원 | 대화 일괄 삭제 |
+| The default notification time changed | 알림 | 기본 알림 시간 변경 |
+| Compatibility with screen readers was added | 화면 읽기 프로그램 | 화면 읽기 프로그램 지원 |
+| Autosave was introduced as a major new capability | Save your changes automatically while you work | Autosave |
+
+During drafting and final review, read each standalone title alone to check that the capability or actual change is identifiable. Remove redundant announcement wording, and restore missing change meaning for improvements and fixes. Then read the title and body together: the opening should add concrete behavior, with every claim and qualifier grounded in the pinned evidence.
 
 ## Examples from a fictional product
 
-Title: Add items to the queue
+These standalone examples assume the described changes are established by product evidence and warrant individual attention. Similar changes with minor impact belong in the groups above.
+
+Title: Add to Queue with a Swipe
+
+Swipe a saved item to the right to add it to the queue.
+
+Title: 스와이프로 대기열 추가
+
+저장한 항목을 오른쪽으로 스와이프하면 대기열에 추가됩니다.
+
+Title: 대화 삭제 동작 개선
 
-You can now add a saved item to the queue by swiping its row to the right. The item keeps its existing position in your saved list.
+대화를 삭제한 뒤에도 목록의 스크롤 위치가 유지되어, 보던 위치에서 계속 탐색할 수 있습니다.
 
-Title: 대기열에 항목 추가
+Title: 저장 중 앱 종료 문제 수정
 
-이제 저장한 항목을 오른쪽으로 스와이프해 대기열에 추가할 수 있습니다. 저장 목록에서 항목의 위치는 그대로 유지됩니다.
+파일 이름에 특수 문자가 포함된 경우 저장 중 앱이 종료되던 문제를 수정했습니다.
 
-Only use that second sentence if the behavior is established by the product evidence. An example is not permission to add a similar claim to another product.
+The action example uses a direct instruction or result; a newly available action can also use the opening described above when that transition matters. The improvement example explains the observable behavior, and the fix identifies the triggering condition. Do not infer these fictional details for a real product. Add setup, requirements, or limitations only when established and needed to understand or use that specific change; a complete one-sentence note needs no filler.
 
 ## Translation
 
 Selected translations are part of `releasekit-draft`. Use that skill for translation-only additions or refreshes as well; follow [the translation workflow](workflow.md#translate-selected-locales) for language scope and source fingerprints.
 
-Use the same note ID in every configured locale. Translate user meaning, not word order. Keep product names supplied by the user, supported menu paths, requirements, and numbers consistent. Raster illustrations are shared; localize their alt text separately. Alt text describes the feature-bearing visual rather than the style or color palette.
+Use the same note ID in every configured locale. For grouped minor notes, translate the group title and every bullet while preserving their order and meaning; do not split translated bullets into separate notes. Translate user meaning, not word order. Preserve whether an action is newly supported or an existing capability changed, and apply the new-capability and repetition guidance across each locale rather than copying every opening mechanically. Keep translated titles concise while preserving the source capability, action, or changed result. Apply the title guidance in every locale: retain meaningful improvement, fix, and compatibility distinctions, but do not add `지원` or another announcement suffix simply because the capability is new. Translate a short English action title into a natural local title instead of forcing identical grammar or suffixes. Preserve the body's concrete behavior and any action paths or conditions it includes, without mechanically copying its opening pattern or adding usage guidance to fill a recurring template. Keep product names supplied by the user, supported menu paths, requirements, and numbers consistent. Raster illustrations are shared; localize their alt text separately. Alt text describes the feature-bearing visual rather than the style or color palette.
 
 After reviewing a translation against the current source, use `releasekit translation mark <version> <note> --locale <locale>`. This records a source fingerprint; it does not prove translation quality. If the original title, alt text, or body changes, review and refresh affected translations before marking them current again.