@iodes/releasekit 0.1.4 → 0.1.6

package/kit/references/writing.md

@@ -1,58 +1,123 @@
 # Writing product release notes
 
-Write for the person using the product, using its actual terminology and the configured language. Use a short feature name as the 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. State the newly possible action and its conditions. 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.
+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 direct statements such as “~을 지원합니다” or “~ 기능을 추가했습니다,” preserving the meaning and scope. Merely replacing “이제” with “새롭게” or “드디어” does not resolve a repetitive sentence pattern. Use editorial judgment rather than a fixed count or quota.
+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
 
-Name the feature, setting, or product area with a compact noun phrase, preferably using the product's established label. Keep only the qualifiers needed to identify the change or distinguish it from another note. Put usage instructions, benefits, requirements, and longer explanations in the body.
+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.
 
-Avoid turning titles into instructions, full sentences, or a restatement of the opening paragraph. In Korean, prefer feature names over sentence-like `~하기` constructions; in English, prefer names over imperative or how-to phrases. Use the shortest natural wording that preserves the feature's identity. Established operation names such as `되돌리기` are valid; do not mechanically strip endings or enforce a fixed character limit.
+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.
 
-| Longer instructional title | Preferred feature title |
-| --- | --- |
-| Save your changes automatically while you work | Autosave |
-| 원하는 시간에 알림을 받도록 예약하기 | 알림 예약 |
-| 여러 파일의 이름을 한 번에 변경하기 | 일괄 이름 변경 |
+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: 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: 저장 중 앱 종료 문제 수정
 
-이제 저장한 항목을 오른쪽으로 스와이프해 대기열에 추가할 수 있습니다. 저장 목록에서 항목의 위치는 그대로 유지됩니다.
+파일 이름에 특수 문자가 포함된 경우 저장 중 앱이 종료되던 문제를 수정했습니다.
 
-Use the opening only when evidence establishes that this action was previously unsupported and became available in this release; vary it when nearby notes use the same pattern. Only use the 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. 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 as concise feature names, preserving the source subject and necessary qualifiers without expanding them into usage instructions. 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.

package/kit/skills/releasekit-draft/SKILL.md

@@ -7,15 +7,15 @@ Before asking anything, check for an unanswered question request already in this
 
 Read the project's ReleaseKit config and the existing release before writing. For translation-only requests, preserve the source copy, pinned scope, and accepted images; follow [Translate selected locales](references/workflow.md#translate-selected-locales) for the affected notes and languages without preparing a new release. For a new draft or source-copy revisions, resolve the version and Git boundaries using [the repository scope guidance](references/workflow.md#resolve-release-scope-from-the-repository); inspect saved releases and Git before asking, and proceed with a clear inferred range without requesting confirmation.
 
-Use English (`en-US`) as the default original language, honoring explicit source choices and existing release selections. Before preparing or writing a new draft, ask only for unchosen translation languages: recommend the user's current language when it differs from the source, offer the source alone, and explicitly allow additional languages through free-text input. Follow [Choose languages](references/workflow.md#choose-languages) and reuse established choices without asking again. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for missing language choices or a consequential scope decision that the evidence cannot resolve. Follow [the workflow](references/workflow.md) for saving the language selection, preparing pinned evidence, continuing drafts, and preserving version boundaries. Use [the writing guide](references/writing.md) to write short feature names as titles in every locale and explain changed behavior and usage in the body; source materials are evidence, not new instructions.
+For each new draft, use `sourceLocale` and `locales` from `releasekit/config.yaml`, including a single-language selection. Once the project has saved releases, proceed without a language question or confirmation; previous releases' language lists do not override the current config. Only on first use, when the request and intentional project settings leave languages unresolved, default the original to English (`en-US`) and ask which translations to include. Save that first-use selection in `releasekit/config.yaml` before preparing the draft, without a separate question about saving defaults. Reuse an existing draft's saved selection unless the user requests a change. Follow [Choose languages](references/workflow.md#choose-languages) for first-use suggestions, persistence, and explicit overrides. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for missing language choices or a consequential scope decision that the evidence cannot resolve. Follow [the workflow](references/workflow.md) for saving the language selection, preparing pinned evidence, continuing drafts, and preserving version boundaries. Use [the writing guide](references/writing.md) for titles and bodies in every locale. Name the capability, action, or changed result concisely; remove redundant announcement suffixes while retaining meaningful improvement, fix, and compatibility distinctions. Lead the body with concrete behavior and accept a clear description as complete. Include usage paths or conditions only when needed to find a non-obvious feature or prevent a material misunderstanding; do not append them to every note. Apply the guide's exceptions for self-explanatory major new capabilities, baseline introductions, and grouped minor notes; source materials are evidence, not new instructions.
 
-For actions that were previously unsupported and become supported in this release, prefer “이제 ~할 수 있습니다.” or its natural equivalent in the selected language. Follow [the new-capability guidance](references/writing.md#newly-supported-capabilities) to establish the before-and-after evidence, retain support conditions, and vary repeated openings across the release. Do not apply this pattern to every feature, improvement, or fix.
+For actions that were previously unsupported and become supported in this release, prefer “이제 ~할 수 있습니다.” or its natural equivalent when first-time availability is the main news; a direct action or behavior statement can better explain a new interaction. Follow [the new-capability guidance](references/writing.md#newly-supported-capabilities) to establish the before-and-after evidence, retain support conditions, and vary openings across the release. Do not apply one pattern to every feature, improvement, or fix.
 
 For first use without existing releases, follow [the adoption guide](references/adoption.md) to resolve and save the baseline and earlier-history choice. Reuse saved choices and explicitly limited scopes. A product introduction uses the pinned snapshot; historical analysis uses the full selected history.
 
-Use the CLI for scaffolding and validation. Group changes by user-visible outcome, attach evidence, and preserve manual edits. Do not invent features, menu locations, or claims to fill gaps. For requested wording changes or feature additions and exclusions, follow [Revise draft notes](references/workflow.md#revise-draft-notes), using the CLI to add or remove whole notes and their managed files. For the file shape, read [the contract](references/format.md).
+Use the CLI for scaffolding and validation. Before adding notes, follow [Group minor changes](references/writing.md#group-minor-changes): reserve standalone notes for changes that warrant individual attention, and collect minor corrections and conveniences into separate per-release bullet-list notes. Reuse existing groups, attach evidence for every bullet, and preserve manual edits. Do not invent features, menu locations, or claims to fill gaps. For requested wording changes or feature additions and exclusions, follow [Revise draft notes](references/workflow.md#revise-draft-notes), using the CLI to add or remove whole notes and their managed files. For the file shape, read [the contract](references/format.md).
 
-Keep every drafted note image-enabled by default, including small fixes and improvements. Use `releasekit note add` without `--no-image` unless the user explicitly chose text-only content for that note. Do not choose an illustrated subset by importance or disable an image because its input is missing. Keep required media pending for `releasekit-image`; follow [image coverage](references/theme-pairing.md#coverage-and-repeat-runs).
+Keep every drafted note image-enabled by default, including grouped minor changes. Each group is one note; its bullets do not require separate notes or images. Use `releasekit note add` without `--no-image` unless the user explicitly chose text-only content for that note. Do not choose an illustrated subset by importance or disable an image because its input is missing. Keep required media pending for `releasekit-image`; follow [image coverage](references/theme-pairing.md#coverage-and-repeat-runs).
 
 Drafting includes the source and every selected translation unless the user explicitly limits the language scope. Follow [Translate selected locales](references/workflow.md#translate-selected-locales) to write or refresh title, body, and alt text, then record the source fingerprints only after reviewing each translation. Preserve translations that are already current. A locale file scaffold alone is not a completed translation.
 

package/kit/skills/releasekit-finalize/SKILL.md

@@ -9,9 +9,11 @@ Read the target release, [the workflow](references/workflow.md), and [the conten
 
 Invoking this skill to finalize a release includes review, corrections within the requested scope, validation, and local finalization. Complete those actions without a separate confirmation step. If the user explicitly asks only for an assessment, report the findings and leave the release status unchanged.
 
-Compare claims against the pinned final diff and target-revision files. For `initialContent: summary`, use the baseline snapshot and [the adoption guide](references/adoption.md); do not require a reconstruction of old commits or assume an initial launch. Use [the writing guide](references/writing.md) to check concise feature titles in every locale, changed behavior, action paths, requirements, and limitations. Refresh affected translations after source edits using [Translate selected locales](references/workflow.md#translate-selected-locales). Preserve current translations and manual edits.
+Compare claims against the pinned final diff and target-revision files. For `initialContent: summary`, use the baseline snapshot and [the adoption guide](references/adoption.md); do not require a reconstruction of old commits or assume an initial launch. Use [the writing guide](references/writing.md) to review copy in every locale. Check that a standalone title names a capability, action, or changed result and its body explains concrete behavior. For grouped minor notes, keep the summary heading and check the concrete changes in the bullets. Accept a clear description without usage instructions. Missing paths, setup steps, or conditions are not completeness defects by themselves; include them only when their omission makes the change difficult to find or use, or materially misleading. Remove redundant announcement suffixes without erasing meaningful improvement, fix, or compatibility distinctions; apply [the title guidance](references/writing.md#titles) before shortening a title to a feature name. Remove body filler and vary the structure where the content calls for it. Refresh affected translations after source edits using [Translate selected locales](references/workflow.md#translate-selected-locales). Preserve current translations and manual edits.
 
-Apply [the new-capability guidance](references/writing.md#newly-supported-capabilities) to prefer “이제 ~할 수 있습니다.” or a natural locale equivalent where evidence establishes newly supported actions. Remove unsupported first-time claims from improvements and fixes, and read the notes together in release order for each locale to vary repetitive openings while preserving the change and its conditions.
+Review the note breakdown using [Group minor changes](references/writing.md#group-minor-changes). Within the requested editing scope, consolidate minor standalone notes into the appropriate per-release fix or improvement group, reusing an existing group when available and keeping significant changes separate. Follow [Revise draft notes](references/workflow.md#revise-draft-notes) to preserve evidence, manual edits, and translations before removing superseded notes. Check every bullet against the pinned evidence and remove duplicates without losing distinct changes or crossing version boundaries.
+
+Apply [the new-capability guidance](references/writing.md#newly-supported-capabilities) to prefer “이제 ~할 수 있습니다.” or a natural locale equivalent when evidence establishes a newly supported action and first-time availability is the main news. Keep direct action or behavior openings when they explain the change clearly. Remove unsupported first-time claims from improvements and fixes, and read the notes together in release order for each locale to vary repetitive openings while preserving the change and its conditions.
 
 Inspect selected images for correct subject, readable framing, absent invented details, and consistent geometry across configured themes using [the pairing guide](references/theme-pairing.md). Reuse a completed visual review when the note, brief, and assets are unchanged. The CLI verifies files and metadata; it cannot judge whether the image depicts the feature accurately. Keep missing or unsuitable assets pending and use `releasekit-image` for the needed correction.
 

package/kit/skills/releasekit-image/SKILL.md

@@ -5,21 +5,23 @@ description: Create, revise, or import ReleaseKit release illustrations with con
 
 Before asking anything, check for an unanswered question request already in this conversation. Keep that request pending across skill transitions and queue every new question until it is resolved; follow [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui).
 
-Read the saved release's complete current note list and captured visual policy on every invocation. Default to covering every drafted note, including notes added since earlier image work; honor only the user's explicit text-only choices or explicitly limited request. Follow [coverage and repeat runs](references/theme-pairing.md#coverage-and-repeat-runs) to reuse accepted images and fill missing ones. First choose the [media source](references/media-sources.md), then read [the visual language](references/visual-language.md) and applicable [composition recipe](references/composition-recipes.md). Use [the pairing guide](references/theme-pairing.md) for configured themes, cost-aware reuse, and importing images. Consult [the file contract](references/format.md) when editing a brief.
+Read the saved release's complete current note list and captured visual policy on every invocation. Default to covering every drafted note, including notes added since earlier image work; honor only the user's explicit text-only choices or explicitly limited request. Follow [coverage and repeat runs](references/theme-pairing.md#coverage-and-repeat-runs) to reuse accepted images and fill missing ones. For grouped minor fixes and improvements, follow [common images](references/common-images.md) first: reuse reviewed project originals before generating anything, and create only missing originals or themes. Choose the [media source](references/media-sources.md), then read [the visual language](references/visual-language.md) and applicable [composition recipe](references/composition-recipes.md). Use [the pairing guide](references/theme-pairing.md) for configured themes, cost-aware reuse, and importing images. Consult [the file contract](references/format.md) when editing a brief.
 
 When a user decision is needed during image work, such as an ambiguous target for a requested revision or a meaningful choice among suitable approved references, use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui). Reuse the captured theme policy and existing asset choices. Ask for missing image attachments through the conversation's supported attachment flow; a text-only picker can collect an existing file path.
 
-Derive one visual message from the release note and its Git/product evidence. Choose an archetype and `source`; the scaffold leaves both unselected. Generate flat explanatory graphics when an abstraction is sufficient. `object-detail` and `editorial-scene` require supplied media, and any other type can use an actual capture when fidelity matters. Search existing approved assets or use the user's capture; if absent, ask for the specific image and keep it pending. Do not invent a physical product, content artwork, or decorative 3D scene. Examples illustrate individual features, not default layouts.
+For standalone notes, derive one visual message from the release note and its Git/product evidence. Minor groups use the common kind's generic scene, independent of their current bullet list. Choose an archetype and `source`; the scaffold leaves both unselected. Generate flat explanatory graphics when an abstraction is sufficient. `object-detail` and `editorial-scene` require supplied media, and any other type can use an actual capture when fidelity matters. Search existing approved assets or use the user's capture; if absent, ask for the specific image and keep it pending. Do not invent a physical product, content artwork, or decorative 3D scene. Examples illustrate individual features, not default layouts.
 
-Complete each missing or unfinished scene brief before planning the release. Preserve the briefs of unchanged accepted images. Each note has one shared scene brief for its configured variants. Encode product facts and uncertainties in `context`, the relevant state and relationships in `composition`, and the feature-specific correctness constraints in `preserve` and `avoid`. Keep reference identities and attributed style names out of prompts and assets. Inspect product references as evidence. Do not invent a concrete UI or physical design to fill missing evidence; use a supported abstraction or leave the unresolved detail in the brief.
+Start each generated scene in neutral values and establish its focal point through composition, scale, and contrast. Map visible schematic groups to the captured palette roles in `composition`, using the [neutral role assignments](references/visual-language.md#assign-neutral-colors-by-role). Light glyphs use `primary`; incidental bars use the lighter `secondary`. Do not introduce new gray tones, tint, opacity, gradients, or shading per image. Improve geometry and spacing before darkening the palette for clarity, and preserve explicit project color overrides. In `composition`, record either no accent or the exact element and supported meaning that needs color. The configured accent is optional; a newly announced capability or a simple relationship between symbols does not justify coloring an icon. Keep generic capability and minor-group icons neutral. Preserve meaningful status, map, chart, and supplied-content colors.
 
-Run `releasekit image plan <version>` on every invocation. For a normal first or repeat run, fill missing assets under [the coverage policy](references/theme-pairing.md#coverage-and-repeat-runs); a repeat invocation alone does not request regeneration of existing images. Handle requests by `action`: `generate` has a generation prompt; `provide` needs an existing or user-supplied image and has no generation prompt. Respect the latest plan even if older prompt files remain in the release. For generated variants, review and import the first before planning its counterpart. For supplied media, use `--theme shared` for one unchanged source or import distinct genuine theme captures. Keep native appearance and meaning; do not invert, duplicate, or synthesize a missing supplied counterpart.
+Complete each missing or unfinished scene brief before planning the release. Preserve the briefs of unchanged accepted images. Each note has one shared scene brief for its configured variants. Keep common minor-group scenes independent of release-specific text and evidence. For standalone scenes, encode product facts and uncertainties in `context`, the relevant state and relationships in `composition`, and the feature-specific correctness constraints in `preserve` and `avoid`. Keep reference identities and attributed style names out of prompts and assets. Inspect product references as evidence. Do not invent a concrete UI or physical design to fill missing evidence; use a supported abstraction or leave the unresolved detail in the brief.
 
-For an image replacement or regeneration request, reuse the existing release and note ID. Keep the current variant metadata until the replacement is reviewed, then run `releasekit image import` with the intended `--theme`. The CLI replaces the selection, switches between shared and themed usage when needed, and removes unused managed images for that note. If the media source changes, include `--source provided` or `--source generated` to save it together with the new selection. Do not pre-clear variants or separately change the source just to switch modes. Do not create another note, release, or permanent candidate asset to represent a revision. Keep failed or unavailable replacements pending; preserve unrelated accepted assets and supplied originals. Follow [replacement handling](references/theme-pairing.md#replace-or-regenerate-an-image), including [shared/themed transitions](references/theme-pairing.md#switch-between-shared-and-themed-images).
+Run `releasekit image plan <version>` on every invocation after importing any reusable common originals. For a normal first or repeat run, fill missing assets under [the coverage policy](references/theme-pairing.md#coverage-and-repeat-runs); a repeat invocation alone does not request regeneration of existing images. Handle requests by `action`: `generate` has a generation prompt; `provide` needs an existing or user-supplied image and has no generation prompt. Respect the latest plan even if older prompt files remain in the release. An existing reviewed common file can satisfy a generated-image request through import; rerun the plan before generating anything that is still missing. For generated variants, review and import the first before planning its counterpart. For supplied media, use `--theme shared` for one unchanged source or import distinct genuine theme captures. Keep native appearance and meaning; do not invert, duplicate, or synthesize a missing supplied counterpart.
+
+For an image replacement or regeneration request, reuse the existing release and note ID. Keep the current variant metadata until the replacement is reviewed, then run `releasekit image import` with the intended `--theme`. The CLI replaces the selection, switches between shared and themed usage when needed, and removes unused managed images for that note. If the media source changes, include `--source provided` or `--source generated` to save it together with the new selection. Do not pre-clear variants or separately change the source just to switch modes. Do not create another note or release to represent a revision. Keep discarded candidates temporary; publish a reviewed common original only through [the common-image workflow](references/common-images.md#preserve-release-snapshots). Keep failed or unavailable replacements pending; preserve unrelated accepted assets and supplied originals. Follow [replacement handling](references/theme-pairing.md#replace-or-regenerate-an-image), including [shared/themed transitions](references/theme-pairing.md#switch-between-shared-and-themed-images).
 
 If no image generator is available, preserve the generated prompt files and report the pending assets. Continue independent editorial work. Do not silently call a paid API, install a provider, or replace requested raster illustrations with placeholders. Import user-supplied PNG, JPEG, or WebP files when they become available.
 
-Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
+Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence, including whether accent is absent or stays confined to its justified elements. Review the release images together for repeated decorative accents; do not assign one colored point to every note or impose a fixed color quota. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
 
 If the accepted image requires an alt-text correction, update the source and affected translations using [Translate selected locales](references/workflow.md#translate-selected-locales), reviewing them before recording new source fingerprints.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iodes/releasekit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Git-based visual release notes and portable agent skills",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -157,27 +157,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base interface panels and resting rows."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Quiet icon tiles, inset areas, and abstract thumbnail fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Incidental label bars and supporting schematic details."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [
@@ -195,27 +201,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base interface panels and resting rows."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Quiet icon tiles, inset areas, and abstract thumbnail fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Incidental label bars and supporting schematic details."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [

package/schemas/release.schema.json

@@ -122,27 +122,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base interface panels and resting rows."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Quiet icon tiles, inset areas, and abstract thumbnail fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Incidental label bars and supporting schematic details."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [
@@ -160,27 +166,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base interface panels and resting rows."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Quiet icon tiles, inset areas, and abstract thumbnail fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Incidental label bars and supporting schematic details."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [