@iodes/releasekit 0.1.3 → 0.1.5

package/README.md

@@ -53,11 +53,11 @@ Run inside your product's Git repository:
 releasekit init --tools codex,claude,cursor --themes both
 ```
 
-Choose the tools you use: `codex`, `claude`, `cursor`, or a comma-separated list. New projects use English (`en-US`) as the original language, with no translations enabled until selected. Edit `releasekit/config.yaml` to set your product name, intentional language overrides, and visual settings. Setup prints the skill invocation hints for each tool.
+Choose the tools you use: `codex`, `claude`, `cursor`, or a comma-separated list. New projects use English (`en-US`) as the original language, with no translations enabled until selected. Edit `releasekit/config.yaml` to set your product name, language defaults for new drafts, and visual settings. Setup prints the skill invocation hints for each tool.
 
 ### 3. Ask your agent
 
-Start with the installed `releasekit-draft` skill. Example conversation with a Korean-speaking user, shown here in English, and an image tool available:
+Start with the installed `releasekit-draft` skill. Example first-use conversation with a Korean-speaking user, shown here in English, and an image tool available:
 
 ```text
 You: Use releasekit-draft to draft 1.4.0.
@@ -65,12 +65,23 @@ AI:  I'll use English for the original notes. Add Korean, your current
      language, as a translation (recommended), or use English only?
      You can also enter additional languages together.
 You: Korean and Japanese translations.
-AI:  Found v1.4.0 and its preceding release tag v1.3.0 on this line.
+AI:  Saved these language defaults in releasekit/config.yaml.
+     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,20 +92,22 @@ 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.
 
-The draft skill defaults the original language to English and suggests the user's current language for optional translation. Its question accepts additional language names or locale codes through free-text input, as well as an English-only choice. An English-speaking user is not offered a duplicate English translation. Explicit source choices and existing release selections are reused. The selection is saved for that release; future project defaults change only when requested. The draft includes the source and those selected translations. Use the same draft skill later to add a language or refresh translations.
+Language selection is a first-use decision. When it is still unresolved, the draft skill defaults the original to English, suggests the user's current language for optional translation, and accepts additional language names or locale codes as well as an English-only choice. Explicit choices and intentional project settings are reused. The first selection is saved in `releasekit/config.yaml` before preparing the draft, without a separate confirmation. Each new draft uses the current config's original language and complete translation set without asking again, even when previous releases used different languages. Existing drafts keep their saved selection. The draft includes the source and all selected translations; use the same skill to request a language change or refresh translations. Changing project defaults affects future drafts while earlier releases remain unchanged.
 
 Invoke the skill with `$releasekit-draft` in Codex, `/releasekit-draft` in Claude Code, or the skill picker in Cursor. The agent runs the CLI, generates flat explanations, and requests approved source images when the actual product or content must be shown.
 
@@ -135,21 +148,21 @@ 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.
 
 <details>
 <summary><strong>Step-by-step CLI workflow</strong></summary>
 
-Replace the sample version, Git refs, and note ID with your own. If release `1.3.0` already exists in ReleaseKit, add `--previous 1.3.0` to link its history.
+Replace the sample version, Git refs, and note ID with your own. Save first-use language choices in `releasekit/config.yaml` before preparation. If release `1.3.0` already exists in ReleaseKit, add `--previous 1.3.0` to link its history.
 
 ```sh
 releasekit prepare 1.4.0 --from v1.3.0 --to v1.4.0
-# Save selected languages in release.yaml before adding notes.
-# This example uses sourceLocale: en-US and locales: [en-US, ko-KR].
+# prepare copied sourceLocale and locales from the current config.yaml.
+# This example has sourceLocale: en-US and locales: [en-US, ko-KR].
 releasekit note add 1.4.0 queue-action
 
 # Write the source and selected translations, then attach evidence.
@@ -171,17 +184,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.
+- Preparing creates only `release.yaml` with pinned Git boundaries. Its `sourceLocale` and `locales` always come from current project configuration. 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 +215,12 @@ Codex and Cursor share `.agents/skills` to avoid duplicate discovery. Claude Cod
 
 ## Image themes
 
+Image work covers **every drafted note** by default, including grouped minor fixes and improvements. A group uses one visual brief and the configured image variants; individual bullets do not require separate images. 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.
+
+**Minor Fixes and Minor Improvements reuse common originals across releases.** The image skill first checks `releasekit/common-images/minor-fixes/` or `releasekit/common-images/minor-improvements/`, importing reviewed compatible images and creating only missing originals or themes. Each release keeps its own copies, so changes to the common design do not rewrite earlier releases. Bullet edits and translations do not require new pictures. The directories are created when reviewed originals become available; see [common images](kit/references/common-images.md).
+
+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 +240,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 +258,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.
 
@@ -268,6 +293,8 @@ releasekit/
         └── assets/            # Selected raster images
 ```
 
+Major capabilities and changes that warrant individual attention get standalone notes. Small user-visible corrections and conveniences are collected into separate **Minor Fixes** and **Minor Improvements** notes, each with a short bullet list, normally after the main notes in that release. Every bullet retains its supporting evidence and selected translations. See [note grouping](kit/references/writing.md#group-minor-changes).
+
 Releases store the comparison start and end SHAs in `release.yaml`, with relevant paths or commits attached to individual notes. They do not save a full patch or a separate changed-file index. Draft validation reads the pinned Git range, or the baseline snapshot for a product introduction; finalized releases can be validated and exported without Git history.
 
 Export follows explicit `previous` links, keeping each version's notes in a separate group. The default limit is **three releases, including the current one**. Similar notes in different versions remain separate.
@@ -289,12 +316,13 @@ Translations track source fingerprints, and finalized releases record content fi
 | [Choosing generated or supplied media](kit/references/media-sources.md) | Source selection, pending captures, and shared assets. |
 | [Composition recipes](kit/references/composition-recipes.md) | Eight presentation categories matched to the feature and its source. |
 | [Theme pairs and cost](kit/references/theme-pairing.md) | Shared geometry, single-theme policies, and reuse. |
+| [Common images](kit/references/common-images.md) | Reusing minor-group originals across releases, missing themes, and preserved release copies. |
 | [File contract](kit/references/format.md) · [JSON schemas](schemas) | Authoring files and the public export format. |
 | [Worked examples](examples/README.md) | Paired illustrations, supplied-image workflow, independent briefs, and three-release bundles. |
 
-Visual guidance uses independent, brand-neutral descriptions. Each illustration should communicate the actual feature through its own scene. Worked examples demonstrate the process; each note gets its own composition.
+Visual guidance uses independent, brand-neutral descriptions. Each illustration should communicate the actual feature through its own scene. Worked examples demonstrate the process; standalone notes get their own composition, while minor groups reuse their common scene.
 
-The built-in guidance covers source selection, a scene contract, semantic palette roles, theme-pair invariants, text rules, cost-aware reuse, and visual acceptance checks. Generated icons are compact flat monochrome glyphs. Physical details and content previews use supplied images rather than invented 3D objects or decorative scenes.
+The built-in guidance covers source selection, a scene contract, semantic palette roles, theme-pair invariants, text rules, cost-aware reuse, and visual acceptance checks. Generated icons are compact flat neutral monochrome glyphs. Emphasis starts with composition and value contrast; the project accent is optional and reserved for a specific state, action, or information distinction that needs color. Entirely neutral images are complete outputs. Physical details and content previews use supplied images rather than invented 3D objects or decorative scenes.
 
 ## Development
 

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;