@iodes/releasekit 0.1.3 → 0.1.4

package/README.md

@@ -69,8 +69,18 @@ AI:  Found v1.4.0 and its preceding release tag v1.3.0 on this line.
      Created releasekit/releases/1.4.0/
      ✓ Pinned v1.3.0 → v1.4.0 and collected change evidence
      ✓ Wrote English originals with Korean and Japanese translations
-     Next: use releasekit-image for the images required by these notes.
-     Choose: Prepare images (recommended), Review copy, or Stop for now.
+     Next: use releasekit-image to prepare images for all drafted notes.
+     Choose: Prepare images (recommended), Request copy changes,
+     or Finish drafting — save the draft and ask for revisions later.
+
+You: Finish drafting.
+AI:  Drafting 1.4.0 is complete. Review releasekit/releases/1.4.0/.
+     Ask me here to rewrite a feature description, leave a feature out,
+     or add a feature that was missed. I'll update the draft and its
+     affected translations. Images and finalization remain pending.
+
+You: Rewrite the queue feature description to explain when to use it.
+AI:  Updated that feature description and its Korean and Japanese translations.
 
 You: Prepare images.
 AI:  ✓ Generated dark/light explanations from shared scene briefs
@@ -81,15 +91,17 @@ AI:  ✓ Generated dark/light explanations from shared scene briefs
 
 You: Use ./approved-capture.png for the product-detail note.
 AI:  ✓ Reviewed and imported it once for both viewer themes
-     Next: use releasekit-finalize to check and confirm 1.4.0.
+     Images for all current notes are ready to review.
+     Ask me to revise any feature image or replace it with another image.
+     If no image changes are needed, use releasekit-finalize to confirm 1.4.0.
 
 You: Use releasekit-finalize for 1.4.0, then export up to three releases
      in English to ./release-output.
 AI:  ✓ Validated notes, translations, and images
      ✓ Marked release 1.4.0 ready
      Exported release-output/
-     ├── release-notes.json   ← Notes grouped by release
-     └── assets/             ← Theme variants and shared supplied images
+     ├── release-notes.en-US.json ← English notes grouped by release
+     └── assets/                  ← Theme variants and shared supplied images
 ```
 
 The agent resolves the version and Git range from your request, saved releases, repository tags, and release metadata. It reports a clear scope and proceeds without a tag-selection or confirmation step. If inspection leaves materially different scopes, it asks which work to cover in ordinary language. You can still supply explicit refs to select a particular interval.
@@ -135,9 +147,9 @@ Git range → Draft source + translations → Images → Finalize → Optional e
 | `releasekit-image` | Plan, generate or request, review, and import required images. |
 | `releasekit-finalize` | Review copy, evidence, translations, and images; validate and mark the release ready; export when requested. |
 
-All three skills use the agent's native question picker when clarification is needed and the tool is available, with free-text input for another answer; otherwise they ask in chat. This covers language choices, image references, translation scope or terminology, and unresolved finalization/export choices. Existing decisions are reused, and routine technical parameters are resolved through repository inspection. Required CLI flags do not become a questionnaire. Once a question is asked, dependent work waits for your submitted answer; a default selection, elapsed time, or a closed picker does not count as a choice. The agent keeps an asynchronous picker open while waiting, or asks in chat if the environment cannot support that wait. Image uploads are requested through the conversation's attachment flow.
+All three skills use the agent's native question picker when clarification is needed and the tool is available, with free-text input for another answer; otherwise they ask in chat. This covers language choices, image references, translation scope or terminology, and unresolved finalization/export choices. Existing decisions are reused, and routine technical parameters are resolved through repository inspection. Required CLI flags do not become a questionnaire. Once a question is asked, dependent work waits for your submitted answer; a default selection, elapsed time, or a closed picker does not count as a choice. Only one question request may remain unanswered in the conversation: newly discovered questions and next-step choices wait in a queue, even across skills or releases. A partial answer keeps the remaining questions pending. The agent keeps an asynchronous picker open while waiting, or asks in chat if the environment cannot support that wait. Image uploads are requested through the conversation's attachment flow.
 
-After each stage, the agent reports what is complete and recommends the next useful task based on the release's current state. Choose a suggested action or describe another direction to continue in the same conversation; you can also stop for now. If you already requested the remaining work, the agent continues without asking again. When source and translations are complete, the next step is images; when required images are complete, it is finalization. Text-only releases go directly to finalization. Completed steps are skipped, and missing images or translations stay visible until resolved.
+After each stage, the agent reports what is complete and recommends the next useful task based on the release's current state. Choose a suggested action or describe another direction to continue in the same conversation. After drafting is complete, **Finish drafting** saves the draft for you to read and request changes from the agent. The handoff includes links and examples of revision requests; the agent edits the same draft and refreshes affected translations when you ask. At other stages, you can stop for now. If you already requested the remaining work, the agent continues without asking again. When source and translations are complete, the next step is images; when required images are complete, it is finalization. Text-only releases go directly to finalization. Completed steps are skipped, and missing images or translations stay visible until resolved.
 
 The agent handles editorial work, media selection, and image generation where appropriate. The CLI handles files, evidence, validation, and export. Finalization includes review and marks local content ready with a content fingerprint. Export is optional; committing, publishing, and displaying it remain separate steps.
 
@@ -171,17 +183,21 @@ releasekit image import 1.4.0 queue-action --theme light --file ./selected-light
 # Review facts, copy, translations, and selected images, then finalize.
 releasekit validate 1.4.0
 releasekit finalize 1.4.0
+
 # Export when requested.
-releasekit export --current 1.4.0 --limit 3 --locale en-US --out ./release-output
+releasekit export --out ./release-output
 ```
 
 - Preparing creates only `release.yaml` with pinned Git boundaries. The agent reads commit history and relevant file diffs from Git as needed.
 - Use `--from-root` for an explicitly requested full-history first release.
 - `--to` defaults to the pinned SHA when preparing a saved baseline, and to `HEAD` otherwise; `--previous` can supply the comparison start.
 - Edit existing drafts in place. `prepare` never overwrites them.
-- Use `note add --no-image` for an intentionally text-only note.
+- Notes include images by default. Use `note add --no-image` only for an explicit text-only choice. Adding a note clears any previous `emptyReason`.
+- Use `releasekit note remove <version> <id>` to exclude a draft note. It removes the note folder, translations, visual brief, prompts, and unused managed images, including older imports. Images referenced by remaining visuals and source originals are preserved. The result lists removed paths and retained shared assets. Removing the last note leaves the draft pending until you add notes or supply a factual `emptyReason`.
 - Add `--json` for structured results or `--cwd` to select a project directory.
-- Export to a new directory; an existing destination is never overwritten.
+- Only `--out` is required for export. Omit `--current` to select the release with no successor in the saved `previous` links; multiple release lines require an explicit `--current`. The selected release must be ready. Omit `--limit` to use `history.limit` from `releasekit/config.yaml` (initially 3).
+- Omit `--locale` to export every locale saved in the current release as `release-notes.<locale>.json`, such as `release-notes.en-US.json` and `release-notes.ko-KR.json`. Add `--locale en-US` for only the English file. All files share the same `assets/` directory. Each selected version must contain the requested locales; missing or stale translations stop the export before output is created.
+- Export to a new directory; an existing destination is never overwritten. The command result lists generated JSON paths in `files`, the number of version groups in `releases`, and the number of shared image files in `assets`.
 
 See the [agent workflow](kit/references/workflow.md) for ancestry rules and continuing existing releases.
 
@@ -198,6 +214,10 @@ Codex and Cursor share `.agents/skills` to avoid duplicate discovery. Claude Cod
 
 ## Image themes
 
+Image work covers **every drafted note** by default, including small fixes and improvements. Only an explicit text-only choice omits a note's image. Calling `releasekit-image` again fills missing images, including those for notes added later, and reuses existing valid images. Existing images that need corrections stay pending until the affected revision or replacement is requested.
+
+After generation, review the images and ask the agent to revise anything you dislike or replace it with another approved image. When no image changes are needed and the content is complete, ask for `releasekit-finalize` to confirm the release.
+
 **Generated graphics default to dark and light.** Paired variants share one scene brief, preserving geometry, feature meaning, and semantic colors while presentation surfaces adapt. Images are shared across locales.
 
 Choose `scene.source` in each note's visual brief before planning:
@@ -217,6 +237,8 @@ visuals:
 
 `releasekit image plan <version>` reports pending and reusable assets, with separate `generationRequests` and `providedRequests` counts. It reuses current imports and never calls a model API. Single-theme exports contain one real asset and an explicit fallback.
 
+To replace or regenerate an image, import the reviewed result with the same release version and note ID and the intended `--theme`. Import automatically switches shared/themed usage and removes the note's unused managed images after saving, including older imports. Files still referenced by visuals and source originals outside the note's managed assets are preserved. Keep existing variant entries until the replacement is imported. Use `--source provided` when replacing generated illustrations with a supplied image, or `--source generated` for the reverse change when the subject permits it; source and selection are saved together. See [image transitions](kit/references/theme-pairing.md#switch-between-shared-and-themed-images).
+
 Requests with `action: generate` include a prompt for the agent or an external tool. Requests with `action: provide` have `promptFile: null` and identify the needed source. Missing supplied media stays pending and blocks finalization; the agent can continue independent writing and translation work.
 
 <details>
@@ -233,7 +255,7 @@ releasekit image import 1.4.0 product-detail --theme shared --file ./approved-ca
 
 The CLI keeps the original bytes, dimensions, and colors. One `shared` asset serves both viewer themes without generating or duplicating another file.
 
-If genuine dark/light captures exist, import them with `--theme dark` and `--theme light` instead. A note must use either `shared` or themed entries; remove the previous variant entries when switching. A missing configured capture remains a supplied-image request.
+If genuine dark/light captures exist, import them with `--theme dark` and `--theme light` instead. The CLI replaces the previous shared/themed selection during import; keep its metadata in place until the new file is successfully registered. A missing configured capture remains a supplied-image request.
 
 Follow the current image plan even if older prompt files remain. See the [supplied-media example](examples/provided-media/README.md) and [media source guide](kit/references/media-sources.md) for pending inputs and older briefs.
 

package/dist/assets.d.ts

@@ -0,0 +1,10 @@
+import { type AssetVariant, type Visual } from './model.js';
+import { Project } from './project.js';
+export declare function fileKey(file: string): Promise<string>;
+export declare function visualFileReferences(project: Project, version: string, file: string, selected?: Visual): Promise<Set<string>>;
+export declare function retainedImageFiles(project: Project, replacement: {
+    version: string;
+    noteId: string;
+    visual: Visual | null;
+}): Promise<Set<string>>;
+export declare function managedAssetFiles(project: Project, version: string, noteId?: string, variant?: AssetVariant): Promise<string[]>;

package/dist/assets.js

@@ -0,0 +1,61 @@
+import * as fs from 'node:fs/promises';
+import { visualSchema } from './model.js';
+import { Project } from './project.js';
+import { exists, identifier, readYaml, within } from './files.js';
+// References remain readable while a draft's scene brief is unfinished.
+const imageReferencesSchema = visualSchema.pick({ variants: true }).extend({
+    scene: visualSchema.shape.scene.pick({ references: true }).strip(),
+}).strip();
+export async function fileKey(file) {
+    const resolved = await exists(file) ? await fs.realpath(file) : file;
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+export async function visualFileReferences(project, version, file, selected) {
+    const visual = selected ?? await readYaml(file, imageReferencesSchema);
+    const references = new Set();
+    for (const asset of Object.values(visual.variants)) {
+        if (asset)
+            references.add(await fileKey(await project.releaseFile(version, asset.file)));
+    }
+    for (const reference of visual.scene.references)
+        references.add(await fileKey(await within(project.root, reference)));
+    return references;
+}
+export async function retainedImageFiles(project, replacement) {
+    const retained = new Set();
+    for (const version of await project.versions()) {
+        const directory = await project.releaseFile(version, 'visuals');
+        if (!(await exists(directory)))
+            continue;
+        for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+            if (entry.isDirectory() || !entry.name.endsWith('.yaml'))
+                continue;
+            const replacing = version === replacement.version && entry.name === `${replacement.noteId}.yaml`;
+            if (replacing && replacement.visual === null)
+                continue;
+            const file = await project.releaseFile(version, `visuals/${entry.name}`);
+            for (const reference of await visualFileReferences(project, version, file, replacing ? replacement.visual : undefined)) {
+                retained.add(reference);
+            }
+        }
+    }
+    return retained;
+}
+export async function managedAssetFiles(project, version, noteId, variant) {
+    if (noteId !== undefined)
+        identifier(noteId);
+    const directory = await project.releaseFile(version, 'assets');
+    if (!(await exists(directory)))
+        return [];
+    const prefix = noteId === undefined ? '' : `${noteId}.${variant ? `${variant}.` : ''}`;
+    const suffix = noteId === undefined
+        ? /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}\.(dark|light|shared)\.[a-f0-9]{12}\.(png|jpg|webp)$/
+        : variant ? /^[a-f0-9]{12}\.(png|jpg|webp)$/ : /^(dark|light|shared)\.[a-f0-9]{12}\.(png|jpg|webp)$/;
+    const files = [];
+    for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.startsWith(prefix) && suffix.test(entry.name.slice(prefix.length))) {
+            files.push(await project.releaseFile(version, `assets/${entry.name}`));
+        }
+    }
+    return files.sort();
+}

package/dist/cli.js

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
 import { Project, prepare, startProject } from './project.js';
 import { initProject, installSkills } from './install.js';
-import { addNote, markTranslation, syncImagePolicy } from './content.js';
+import { addNote, removeNote, markTranslation, syncImagePolicy } from './content.js';
 import { planImages, importImage } from './images.js';
 import { validate, finalize } from './validate.js';
 import { exportBundle } from './export.js';
@@ -50,6 +50,8 @@ note.command('add <version> <id>').description('Scaffold a note and its locale f
     await addNote(project(), version, id, noteMetaSchema.shape.category.parse(options.category), options.image);
     emit({ version, note: id, status: 'draft' });
 });
+note.command('remove <version> <id>').description('Remove a draft note, its locale files, prompts, and unused managed images')
+    .action(async (version, id) => emit(await removeNote(project(), version, id)));
 const images = program.command('image').description('Plan themed illustrations and register selected files');
 images.command('plan <version>').description('Plan generation or supplied-image requests without calling a model')
     .option('--sync-config', 'apply current project image settings to this draft')
@@ -59,10 +61,11 @@ images.command('plan <version>').description('Plan generation or supplied-image
         await syncImagePolicy(instance, version);
     emit(await planImages(instance, version));
 });
-images.command('import <version> <note>').description('Import a selected raster variant')
-    .addOption(new Option('--theme <theme>', 'variant to register; shared is for supplied images').choices(['dark', 'light', 'shared']).makeOptionMandatory())
+images.command('import <version> <note>').description('Import or replace an image, switch shared/themed usage, and remove unused note images')
+    .addOption(new Option('--theme <theme>', 'variant to register; shared replaces themed entries and a theme replaces shared').choices(['dark', 'light', 'shared']).makeOptionMandatory())
+    .addOption(new Option('--source <source>', 'save the media source with this import; otherwise keep the current source').choices(['generated', 'provided']))
     .requiredOption('--file <file>', 'selected local PNG, JPEG, or WebP')
-    .action(async (version, id, options) => emit(await importImage(project(), version, id, assetVariant.parse(options.theme), path.resolve(program.opts().cwd, options.file))));
+    .action(async (version, id, options) => emit(await importImage(project(), version, id, assetVariant.parse(options.theme), path.resolve(program.opts().cwd, options.file), { source: options.source })));
 const translation = program.command('translation').description('Track source freshness for reviewed translations');
 translation.command('mark <version> <note>').description('Mark an already reviewed translation current')
     .requiredOption('--locale <locale>', 'translation language code')
@@ -79,9 +82,9 @@ program.command('validate [version]').description('Validate one release or all r
 program.command('finalize <version>').description('Validate and mark local release content ready')
     .action(async (version) => emit(await finalize(project(), version)));
 program.command('export').description('Export recent version groups and selected image variants')
-    .requiredOption('--current <version>', 'current release version')
-    .option('--limit <count>', 'number of version groups, including current', value => Number(value))
-    .option('--locale <locale>', 'output language, defaults to the project source language')
+    .option('--current <version>', 'current release version, defaults to the release with no successor')
+    .option('--limit <count>', 'number of version groups, including current, defaults to project history.limit (initially 3)', value => Number(value))
+    .option('--locale <locale>', 'output language, defaults to all locales saved in the current release')
     .requiredOption('--out <directory>', 'new output directory')
     .action(async (options) => emit(await exportBundle(project(), options.current, { ...options, out: path.resolve(program.opts().cwd, options.out) })));
 async function main() {

package/dist/content.d.ts

@@ -1,6 +1,13 @@
 import { type NoteMeta } from './model.js';
 import { Project } from './project.js';
 export declare function addNote(project: Project, version: string, id: string, category: NoteMeta['category'], image: boolean): Promise<void>;
+export declare function removeNote(project: Project, version: string, id: string): Promise<{
+    version: string;
+    note: string;
+    status: "draft" | "ready";
+    removedPaths: string[];
+    retainedAssets: string[];
+}>;
 export declare function markTranslation(project: Project, version: string, id: string, language: string): Promise<string>;
 export declare function syncImagePolicy(project: Project, version: string): Promise<void>;
 export declare function readVisual(project: Project, version: string, id: string): Promise<{

package/dist/content.js

@@ -1,28 +1,119 @@
 import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileKey, managedAssetFiles, retainedImageFiles, visualFileReferences } from './assets.js';
 import { locale, noteMetaSchema, visualSchema, imageSource } from './model.js';
 import { identifier, writeYaml, writeNote, readNote, noteHash, exists, readYaml } from './files.js';
 import { Project, editable } from './project.js';
+async function notePaths(project, version, id) {
+    return Promise.all([
+        `notes/${id}`, `visuals/${id}.yaml`,
+        ...['dark', 'light', 'shared'].map(variant => `prompts/${id}.${variant}.md`),
+    ].map(relative => project.releaseFile(version, relative)));
+}
 export async function addNote(project, version, id, category, image) {
     const release = await project.release(version);
     editable(release);
     identifier(id);
-    if (release.notes.some(note => note.id === id) || await exists(await project.releaseFile(version, `notes/${id}`))) {
-        throw new Error(`Note ${id} already exists; its content was preserved.`);
+    const paths = await notePaths(project, version, id);
+    if (release.notes.some(note => note.id === id) || (await Promise.all(paths.map(exists))).some(Boolean)) {
+        throw new Error(`Note ${id} already exists or has leftover files; its content was preserved.`);
     }
     const note = noteMetaSchema.parse({ id, category, commits: [], paths: [], image });
-    for (const language of release.locales) {
-        await writeNote(await project.releaseFile(version, `notes/${id}/${language}.md`), { title: '', alt: '', sourceHash: null, body: '' });
+    const directory = paths[0], visualFile = paths[1];
+    await fs.mkdir(path.dirname(directory), { recursive: true });
+    await fs.mkdir(directory);
+    let createdVisual = false;
+    try {
+        for (const language of release.locales) {
+            await writeNote(await project.releaseFile(version, `notes/${id}/${language}.md`), { title: '', alt: '', sourceHash: null, body: '' });
+        }
+        if (image) {
+            await writeYaml(visualFile, {
+                schemaVersion: 1,
+                scene: { archetype: '', source: '', subject: '', message: '', focus: '', composition: '', context: '', elements: [], preserve: [], avoid: [], text: [], references: [] },
+                variants: {},
+            });
+            createdVisual = true;
+        }
+        release.notes.push(note);
+        release.emptyReason = null;
+        release.contentHash = null;
+        await project.save(release);
     }
-    if (image) {
-        await writeYaml(await project.releaseFile(version, `visuals/${id}.yaml`), {
-            schemaVersion: 1,
-            scene: { archetype: '', source: '', subject: '', message: '', focus: '', composition: '', context: '', elements: [], preserve: [], avoid: [], text: [], references: [] },
-            variants: {},
-        });
+    catch (error) {
+        if (createdVisual)
+            await fs.unlink(visualFile);
+        await fs.rm(await project.releaseFile(version, `notes/${id}`), { recursive: true, force: true });
+        throw error;
     }
-    release.notes.push(note);
-    release.contentHash = null;
-    await project.save(release);
+}
+export async function removeNote(project, version, id) {
+    const release = await project.release(version);
+    editable(release);
+    identifier(id);
+    if (!release.notes.some(note => note.id === id))
+        throw new Error(`Unknown note: ${id}`);
+    const paths = await notePaths(project, version, id);
+    const directory = await project.releaseDir(version);
+    const visualFile = paths[1];
+    const references = await exists(visualFile) ? await visualFileReferences(project, version, visualFile) : new Set();
+    const retained = await retainedImageFiles(project, { version, noteId: id, visual: null });
+    const owned = new Set(await managedAssetFiles(project, version, id));
+    const retainedAssets = [];
+    for (const file of await managedAssetFiles(project, version)) {
+        const key = await fileKey(file);
+        if (!owned.has(file) && !references.has(key))
+            continue;
+        if (retained.has(key))
+            retainedAssets.push(file);
+        else
+            paths.push(file);
+    }
+    const targets = [];
+    for (const file of paths) {
+        if (!(await exists(file)))
+            continue;
+        const key = await fileKey(file);
+        if ([...retained].some(reference => reference === key || reference.startsWith(`${key}${path.sep}`))) {
+            throw new Error(`Note files are referenced by another visual; update those references before removing ${id}: ${file}`);
+        }
+        targets.push(file);
+    }
+    // Hold files inside this release until its metadata is saved, so a failed save can restore them.
+    const holding = await fs.mkdtemp(await project.releaseFile(version, `.remove-${id}-`));
+    const checkedHolding = await project.releaseFile(version, path.basename(holding));
+    const moved = [];
+    try {
+        for (const [index, original] of targets.entries()) {
+            const temporary = path.join(checkedHolding, String(index));
+            await fs.rename(original, temporary);
+            moved.push({ original, temporary });
+        }
+        await project.save({ ...release, notes: release.notes.filter(note => note.id !== id), contentHash: null });
+    }
+    catch (error) {
+        const failures = [];
+        for (const entry of moved.reverse()) {
+            try {
+                await fs.rename(entry.temporary, entry.original);
+            }
+            catch (restoreError) {
+                failures.push(restoreError);
+            }
+        }
+        if (failures.length)
+            throw new AggregateError([error, ...failures], `Note removal failed; recovery files remain in ${checkedHolding}`);
+        await fs.rmdir(checkedHolding);
+        throw error;
+    }
+    try {
+        await fs.rm(await project.releaseFile(version, path.basename(checkedHolding)), { recursive: true, force: true });
+    }
+    catch (error) {
+        throw new Error(`Note ${id} was removed, but file cleanup is incomplete in ${checkedHolding}`, { cause: error });
+    }
+    const relative = (file) => path.relative(directory, file).split(path.sep).join('/');
+    return { version, note: id, status: release.status, removedPaths: targets.map(relative), retainedAssets: retainedAssets.map(relative) };
 }
 export async function markTranslation(project, version, id, language) {
     const release = await project.release(version);

package/dist/export.d.ts

@@ -1,10 +1,10 @@
 import { Project } from './project.js';
-export declare function exportBundle(project: Project, current: string, options: {
+export declare function exportBundle(project: Project, current: string | undefined, options: {
     limit?: number;
     locale?: string;
     out: string;
 }): Promise<{
-    file: string;
+    files: string[];
     releases: number;
     assets: number;
 }>;

package/dist/export.js

@@ -7,38 +7,47 @@ import { exists, readNote, write } from './files.js';
 import { readVisual } from './content.js';
 export async function exportBundle(project, current, options) {
     const config = await project.config();
-    const language = locale.parse(options.locale ?? config.sourceLocale);
-    const history = await project.history(current, options.limit ?? config.history.limit);
-    const bundle = { schemaVersion: 1, currentVersion: current, locale: language, releases: [] };
-    const copies = [];
+    const version = current ?? await project.latestVersion();
+    const history = await project.history(version, options.limit ?? config.history.limit);
+    const languages = options.locale === undefined ? history[0].locales : [locale.parse(options.locale)];
     for (const release of history) {
         if (release.status !== 'ready')
             throw new Error(`Release ${release.version} is still a draft.`);
-        if (!release.locales.includes(language))
-            throw new Error(`Release ${release.version} has no ${language} locale.`);
+        for (const language of languages) {
+            if (!release.locales.includes(language))
+                throw new Error(`Release ${release.version} has no ${language} locale.`);
+        }
         const checked = await validate(project, release.version);
         if (!checked.valid)
             throw new Error(checked.errors.join('\n'));
-        const entry = { version: release.version, releasedAt: release.releasedAt, previous: release.previous, notes: [] };
-        for (const note of release.notes) {
-            const text = await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`));
-            const exported = { id: note.id, category: note.category, title: text.title, bodyMarkdown: text.body, image: null };
-            if (note.image) {
-                const visual = await readVisual(project, release.version, note.id);
-                const variants = activeVariants(visual, release.visuals);
-                exported.image = { alt: text.alt, fallbackTheme: variants[0], variants: {} };
-                for (const variant of variants) {
-                    const asset = visual.variants[variant];
-                    const relative = `assets/${release.version}/${path.posix.basename(asset.file)}`;
-                    exported.image.variants[variant] = { src: relative, width: asset.width, height: asset.height };
-                    copies.push({ src: await project.releaseFile(release.version, asset.file), relative });
+    }
+    const bundles = [];
+    const copies = new Map();
+    for (const language of languages) {
+        const bundle = { schemaVersion: 1, currentVersion: version, locale: language, releases: [] };
+        for (const release of history) {
+            const entry = { version: release.version, releasedAt: release.releasedAt, previous: release.previous, notes: [] };
+            for (const note of release.notes) {
+                const text = await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`));
+                const exported = { id: note.id, category: note.category, title: text.title, bodyMarkdown: text.body, image: null };
+                if (note.image) {
+                    const visual = await readVisual(project, release.version, note.id);
+                    const variants = activeVariants(visual, release.visuals);
+                    exported.image = { alt: text.alt, fallbackTheme: variants[0], variants: {} };
+                    for (const variant of variants) {
+                        const asset = visual.variants[variant];
+                        const relative = `assets/${release.version}/${path.posix.basename(asset.file)}`;
+                        exported.image.variants[variant] = { src: relative, width: asset.width, height: asset.height };
+                        copies.set(relative, await project.releaseFile(release.version, asset.file));
+                    }
                 }
+                entry.notes.push(exported);
             }
-            entry.notes.push(exported);
+            bundle.releases.push(entry);
         }
-        bundle.releases.push(entry);
+        bundleSchema.parse(bundle);
+        bundles.push(bundle);
     }
-    bundleSchema.parse(bundle);
     const destination = path.resolve(options.out);
     const contentRoot = await project.content('releases');
     const relativeToContent = path.relative(contentRoot, destination);
@@ -50,9 +59,14 @@ export async function exportBundle(project, current, options) {
     }
     if (await exists(destination))
         throw new Error('The export destination already exists. Choose a new output directory.');
-    // No filesystem output is created until every selected release has passed validation.
-    for (const copy of copies)
-        await write(path.join(destination, copy.relative), await fs.readFile(copy.src));
-    await write(path.join(destination, 'release-notes.json'), JSON.stringify(bundle, null, 2) + '\n');
-    return { file: path.join(destination, 'release-notes.json'), releases: bundle.releases.length, assets: copies.length };
+    // No filesystem output is created until every selected release and locale has passed validation.
+    for (const [relative, src] of copies)
+        await write(path.join(destination, relative), await fs.readFile(src));
+    const files = [];
+    for (const bundle of bundles) {
+        const file = path.join(destination, `release-notes.${bundle.locale}.json`);
+        await write(file, JSON.stringify(bundle, null, 2) + '\n');
+        files.push(file);
+    }
+    return { files, releases: history.length, assets: copies.size };
 }

package/dist/images.d.ts

@@ -31,7 +31,10 @@ export declare function planImages(project: Project, version: string): Promise<{
     providedRequests: number;
     costNote: string;
 }>;
-export declare function importImage(project: Project, version: string, noteId: string, variant: AssetVariant, source: string): Promise<{
+export interface ImportImageOptions {
+    source?: 'generated' | 'provided';
+}
+export declare function importImage(project: Project, version: string, noteId: string, variant: AssetVariant, source: string, options?: ImportImageOptions): Promise<{
     file: string;
     sha256: string;
     sceneHash: string;

package/dist/images.js

@@ -1,11 +1,12 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import sharp from 'sharp';
-import { themes, assetVariant, imageSource, activeVariants } from './model.js';
+import { themes, assetVariant, sceneSchema, imageSource, activeVariants } from './model.js';
 import { Project, editable } from './project.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { digest, identifier, exists, write, writeYaml } from './files.js';
 import { imagePrompt, sceneHash } from './prompts.js';
+import { fileKey, managedAssetFiles, retainedImageFiles } from './assets.js';
 export async function inspectImage(bytes) {
     const image = sharp(bytes, { limitInputPixels: 16_777_216, failOn: 'warning' });
     const metadata = await image.metadata();
@@ -74,7 +75,19 @@ export async function planImages(project, version) {
         costNote: 'Counts describe required output assets, not provider prices or a guarantee of one tool call per asset. No image service was called.',
     };
 }
-export async function importImage(project, version, noteId, variant, source) {
+async function obsoleteNoteImages(project, version, noteId, selected) {
+    const candidates = await managedAssetFiles(project, version, noteId);
+    if (!candidates.length)
+        return [];
+    const retained = await retainedImageFiles(project, { version, noteId, visual: selected });
+    const obsolete = [];
+    for (const file of candidates) {
+        if (!retained.has(await fileKey(file)))
+            obsolete.push(file);
+    }
+    return obsolete;
+}
+export async function importImage(project, version, noteId, variant, source, options = {}) {
     const release = await project.release(version);
     editable(release);
     identifier(noteId);
@@ -82,34 +95,44 @@ export async function importImage(project, version, noteId, variant, source) {
     if (!release.notes.some(n => n.id === noteId && n.image))
         throw new Error(`No image-enabled note named ${noteId}.`);
     const visual = await readVisual(project, version, noteId);
+    if (options.source !== undefined)
+        visual.scene.source = sceneSchema.shape.source.parse(options.source);
     const provided = imageSource(visual.scene) === 'provided';
     if (variant === 'shared') {
         if (!provided)
-            throw new Error('Only supplied images can use a shared asset.');
-        if (visual.variants.dark || visual.variants.light)
-            throw new Error('Remove the themed variant entries before switching to one shared supplied image.');
+            throw new Error('Only supplied images can use a shared asset. Use --source provided when importing a supplied replacement.');
+        visual.variants = {};
     }
     else {
         if (!themes(release.visuals).includes(variant))
             throw new Error(`Theme ${variant} is not enabled for this release. Update the project setting and sync the draft first.`);
-        if (visual.variants.shared)
-            throw new Error('Remove the shared variant entry before switching to distinct supplied theme variants.');
+        delete visual.variants.shared;
     }
     const bytes = await fs.readFile(path.resolve(project.root, source));
     const inspected = await inspectImage(bytes);
     const file = `assets/${noteId}.${variant}.${inspected.sha256.slice(0, 12)}.${inspected.extension}`;
     const destination = await project.releaseFile(version, file);
-    if (await exists(destination)) {
-        if (digest(await fs.readFile(destination)) !== inspected.sha256)
-            throw new Error('The asset destination has conflicting content.');
-    }
-    else
-        await write(destination, bytes);
+    const destinationExists = await exists(destination);
+    if (destinationExists && digest(await fs.readFile(destination)) !== inspected.sha256)
+        throw new Error('The asset destination has conflicting content.');
     visual.variants[variant] = {
         file, sha256: inspected.sha256, sceneHash: sceneHash(visual.scene, release.visuals, variant),
         width: inspected.width, height: inspected.height,
     };
-    await writeYaml(await project.releaseFile(version, `visuals/${noteId}.yaml`), visual);
+    // Resolve cleanup before writing, and remove old files only after the selection is saved.
+    const obsolete = await obsoleteNoteImages(project, version, noteId, visual);
+    if (!destinationExists)
+        await write(destination, bytes);
+    try {
+        await writeYaml(await project.releaseFile(version, `visuals/${noteId}.yaml`), visual);
+    }
+    catch (error) {
+        if (!destinationExists)
+            await fs.unlink(destination);
+        throw error;
+    }
+    for (const oldFile of obsolete)
+        await fs.rm(oldFile, { force: true });
     return visual.variants[variant];
 }
 export async function validateImages(project, version, noteId, visual, errors, warnings) {

package/dist/project.d.ts

@@ -10,6 +10,7 @@ export declare class Project {
     release(version: string): Promise<Release>;
     save(release: Release): Promise<void>;
     versions(): Promise<string[]>;
+    latestVersion(): Promise<string>;
     history(version: string, limit: number): Promise<Release[]>;
 }
 export declare function editable(release: Release): void;

package/dist/project.js

@@ -37,6 +37,19 @@ export class Project {
         const entries = await fs.readdir(folder, { withFileTypes: true });
         return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
     }
+    async latestVersion() {
+        const versions = await this.versions();
+        if (!versions.length)
+            throw new Error('No releases to export. Prepare and finalize a release first.');
+        const releases = await Promise.all(versions.map(version => this.release(version)));
+        const predecessors = new Set(releases.map(release => release.previous));
+        const latest = releases.filter(release => !predecessors.has(release.version));
+        if (!latest.length)
+            throw new Error('No latest release found: previous-release links contain a cycle.');
+        if (latest.length > 1)
+            throw new Error(`Multiple latest releases found: ${latest.map(release => release.version).join(', ')}. Specify --current <version>.`);
+        return latest[0].version;
+    }
     async history(version, limit) {
         if (!Number.isInteger(limit) || limit < 1 || limit > 100)
             throw new Error('History limit must be an integer from 1 to 100.');

package/kit/references/format.md

@@ -14,6 +14,14 @@ 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 |
 
+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.
@@ -28,6 +36,8 @@ Frontmatter fields are `title`, `alt`, and `sourceHash`. The source locale norma
 
 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 |
 | --- | --- | --- |
@@ -27,8 +27,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,6 +10,16 @@ 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 smaller fixes and improvements. Review the current `release.yaml` each time so newly added notes are included. A plain `releasekit-image` invocation uses this full scope without asking the user to pick important notes. Honor an explicitly limited request and the user's explicit text-only choices. If earlier agent prioritization disabled a note's image without such a choice, restore `image: true` and create or complete its visual brief in place, preserving its text, translations, and existing assets. Do not recreate the note. Missing supplied media stays pending instead of making the note text-only.
+
+Before planning, complete missing or unfinished briefs for the image-enabled notes. Preserve existing scene specifications and the release's captured theme policy when they have not been changed by the user's request. Run `releasekit image plan <version>` from the current saved state, then handle the missing requests across all notes. Respect `action: generate` versus `action: provide` and the configured dark/light or shared variants.
+
+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.
@@ -35,7 +45,34 @@ Do not invert pixels or shift brightness globally. A black lens remains a black
 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

@@ -70,4 +70,4 @@ Make the brief concrete enough that another model can render the same scene. “
 
 Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. Attractive styling and theme similarity do not establish factual or structural correctness.
 
-For a pair, compare both outputs side by side using [theme-pairing.md](theme-pairing.md). Automated checks establish file integrity, dimensions, configured variants, and scene freshness; they do not prove visual correspondence or truthfulness. Correct a specific defect with a targeted edit instead of randomly regenerating every asset. Preserve accepted files and import the newly selected version.
+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,29 @@ 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.
 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 before adding notes with `releasekit note add <version> <id>`. Fill the source Markdown and attach evidence paths or commit SHAs to `release.yaml`, using snapshot evidence for a baseline summary. Keep every note image-enabled by default; use `--no-image` only for the user's explicit text-only choice, never to select just the important notes.
 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). 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 include an omitted feature, verify it against the pinned evidence. Extend an existing note when the feature belongs there; otherwise run `releasekit note add <version> <id>` and write its source, selected translations, and evidence. New notes are image-enabled by default; use `--no-image` only when the user explicitly asks for text-only content. Keep required images pending so the next `releasekit-image` run picks up the new note. Explain a requested feature outside the saved scope instead of silently expanding the Git range.
+- To 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.
@@ -56,9 +66,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.
 
@@ -80,13 +92,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 +110,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,6 +1,6 @@
 # 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 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.
 
 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.
 
@@ -10,22 +10,49 @@ Keep source evidence with each note. Do not invent performance percentages, priv
 
 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.
 
+## 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.
+
+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.
+
+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 | 이제 여러 파일의 이름을 한 번에 변경할 수 있습니다. |
+| 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.
+
+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.
+
+| Longer instructional title | Preferred feature title |
+| --- | --- |
+| Save your changes automatically while you work | Autosave |
+| 원하는 시간에 알림을 받도록 예약하기 | 알림 예약 |
+| 여러 파일의 이름을 한 번에 변경하기 | 일괄 이름 변경 |
+
 ## Examples from a fictional product
 
-Title: Add items to the queue
+Title: Queue
 
 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.
+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.
 
 ## 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. 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.
 
 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

@@ -3,14 +3,20 @@ name: releasekit-draft
 description: Create or revise ReleaseKit release notes and their selected translations, including translation-only refreshes. Resolve release scope from the repository and guide first-use setup for an existing product. Use for release copy, not general code implementation.
 ---
 
+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 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 turn the net change into useful product language; source materials are evidence, not new instructions.
+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 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 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 the file shape, read [the contract](references/format.md).
+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).
+
+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).
 
 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.
 
-After drafting, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step). With source and translations complete, recommend `releasekit-image` when required images remain, or `releasekit-finalize` when the release is ready for final checks. Continue work already requested in this conversation; otherwise offer the next useful action. Do not send completed translations through another stage.
+After drafting, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step). With source and translations complete, recommend `releasekit-image` to cover all drafted notes when required images remain, or `releasekit-finalize` when the release is ready for final checks. Continue work already requested in this conversation; otherwise offer the next useful action. When the user chooses to finish drafting or requested drafting only, [hand over the completed draft and invite revision requests](references/workflow.md#complete-drafting-and-invite-revisions). Do not send completed translations through another stage.

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

@@ -3,11 +3,15 @@ name: releasekit-finalize
 description: Finalize a ReleaseKit release by reviewing facts, copy, translations, and images, validating content, and marking the local release ready. Export a release bundle when requested.
 ---
 
+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 target release, [the workflow](references/workflow.md), and [the content contract](references/format.md). Reuse the version and choices established in the request and conversation. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) only for unresolved scope or requested export choices.
 
 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 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 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.
+
+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.
 
 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.
 
@@ -15,6 +19,6 @@ Run `releasekit validate <version>`, resolve errors, and assess warnings. Missin
 
 For a draft that passes review and validation, run `releasekit finalize <version>` and verify that `release.yaml` contains `status: ready` and a nonempty `contentHash`. The command validates again and records the fingerprint; do not set ready status manually. For an already ready release, validate and reuse it without calling finalize again. If requested corrections require changes, reopen it with `status: draft` and `contentHash: null`, apply the corrections, and finalize again.
 
-If export was requested, run `releasekit export --current <version> --locale <locale> --limit <count> --out <directory>` with the requested or established choices, using [the workflow](references/workflow.md) for defaults. Preserve individual release boundaries and configured fallback themes. A successful finalization is a complete local result even when no export was requested. Finalization does not commit, tag, push, deploy, or publish.
+If export was requested, run `releasekit export --out <directory>`, using [the workflow](references/workflow.md) for defaults. Add `--current`, `--limit`, or `--locale` only for requested overrides or to resolve multiple release endpoints. With no language override, export all locales saved in the current release to separate JSON files that share image assets. Preserve individual release boundaries and configured fallback themes. A successful finalization is a complete local result even when no export was requested. Finalization does not commit, tag, push, deploy, or publish.
 
 When finalized, report the version and link to its release file, adding bundle links only for a completed requested export. If blocked, state the remaining work and the actual saved status. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) without introducing a separate review stage.

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

@@ -3,15 +3,19 @@ name: releasekit-image
 description: Create, revise, or import ReleaseKit release illustrations with consistent composition and project-configured dark and light variants. Use for visual release-note assets and generation prompts, not general UI implementation or arbitrary image work.
 ---
 
-Read the release's captured visual policy and the affected note. 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.
+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).
 
-When a user decision is needed during image work, such as an ambiguous target note 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.
+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.
+
+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.
 
-Complete one shared scene brief before generating. 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.
+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.
+
+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.
 
-Run `releasekit image plan <version>`. 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.
+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).
 
 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.
 
@@ -19,4 +23,4 @@ Inspect selected images at full resolution and small-card size. First compare th
 
 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.
 
-When required images, source copy, and translations are complete, recommend `releasekit-finalize` to review and mark this release ready. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) to continue already requested work or offer that action. If images remain blocked, identify the missing input and keep them pending.
+After image work, follow [Review images and continue](references/workflow.md#review-images-and-continue): show the accepted images, invite the user to ask the agent for changes or a replacement, and explain that `releasekit-finalize` confirms the release when no image changes are needed and the content is complete. Reuse this handoff when a repeat run finds no missing images. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) to continue already requested finalization or offer it as the recommended action. If assets remain missing, stale, or otherwise invalid, identify the affected notes and keep that work pending.

package/package.json

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