@iodes/releasekit 0.1.2 → 0.1.4

package/README.md

@@ -53,23 +53,34 @@ 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. Then edit `releasekit/config.yaml` to set your product name, source language, locales, 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, intentional language overrides, 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 an image tool available:
+Start with the installed `releasekit-draft` skill. Example 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 from v1.3.0 to v1.4.0.
-AI:  Which language should the original notes use, and which
-     translations would you like? Current settings: Korean original,
-     English translation. A single language is also fine.
-You: Korean original and English translation.
-AI:  Created releasekit/releases/1.4.0/
-     ✓ Pinned the Git range and collected change evidence
-     ✓ Wrote release notes in ko-KR and en-US
-     Next: prepare the images required by these notes.
-     Choose: Prepare images (recommended), Review copy, or Stop for now.
+You: Use releasekit-draft to draft 1.4.0.
+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.
+     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 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
@@ -80,39 +91,67 @@ 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: review and finalize 1.4.0, then export the release bundle.
+     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: Review and finalize 1.4.0, then export up to three releases
+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 draft skill asks for the original language and optional translations before preparing or writing notes. Choices already supplied in the conversation are reused. The selection is saved for that release; future project defaults change only when requested.
+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.
 
 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.
 
+## Adopting ReleaseKit later
+
+You can start after your product has already shipped. Ask the draft skill to set a starting point; it finds a relevant release tag or commit from the repository and asks how to handle the earlier period when that choice is unresolved. Regular notes begin **after** the selected baseline commit.
+
+| Earlier history | Result |
+| --- | --- |
+| **Product introduction** (recommended for an established product) | A concise overview of capabilities at the baseline, grounded in that snapshot without reconstructing every old commit. |
+| **Analyze history** | Notes based on the repository's beginning through the baseline. |
+| **Skip** | No earlier entry; start recording subsequent changes. |
+
+An introduction does not assume that adopting ReleaseKit was the product's launch. Version, date, and product claims should reflect the actual product. The agent reuses choices already made in the conversation or saved setup.
+
+For example, introduce the product at `v1.3.0`, then record changes from there:
+
+```sh
+releasekit start --at v1.3.0 --past summary --baseline-version 1.3.0
+releasekit prepare 1.3.0
+# Ask the agent to write, review, and finalize the baseline introduction.
+releasekit prepare 1.4.0 --previous 1.3.0 --to v1.4.0
+```
+
+Use `--past history` to analyze earlier commits instead. With `--past skip`, omit `--baseline-version`; the first regular `prepare` uses the saved boundary. You can save `HEAD` as the start now and prepare the first draft when later commits exist. Setup pins the SHA, so moving a tag or adding commits cannot shift the boundary.
+
+`start` saves the choice and creates no notes. Summary/history baselines become ordinary draft releases when prepared and follow the same draft (including translations), image, and finalization workflow. They count as one release in exported history; skipping creates no extra group. Existing releases keep their current workflow. See the [first-use guide](kit/references/adoption.md).
+
 ## Workflow
 
 ```text
-Git range → Release draft → Notes + images + translations → Validate → Export
+Git range → Draft source + translations → Images → Finalize → Optional export
 ```
 
 | Skill | Purpose |
 | --- | --- |
-| `releasekit-draft` | Create or revise notes from a Git range. |
-| `releasekit-image` | Plan, generate or request, review, and import images. |
-| `releasekit-translate` | Translate notes and track source freshness. |
-| `releasekit-review` | Review content, evidence, images, and release readiness. |
+| `releasekit-draft` | Choose a first-use baseline, write and revise source notes and selected translations, or refresh translations alone. |
+| `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 four 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 review/export choices. Existing decisions are reused, so a clear request proceeds without extra questions. 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. 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. Finalizing a release marks local content ready; committing, publishing, and displaying it remain separate steps.
+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>
@@ -121,9 +160,15 @@ Replace the sample version, Git refs, and note ID with your own. If release `1.3
 
 ```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].
 releasekit note add 1.4.0 queue-action
 
-# Fill the notes, evidence references, and visual brief.
+# Write the source and selected translations, then attach evidence.
+# Review each translation before marking it current.
+releasekit translation mark 1.4.0 queue-action --locale ko-KR
+
+# Complete the visual brief for image work.
 # Choose an archetype and set scene.source to generated for this example.
 releasekit image plan 1.4.0
 
@@ -135,20 +180,24 @@ releasekit image plan 1.4.0
 # Generate and review the matching light image, then import it.
 releasekit image import 1.4.0 queue-action --theme light --file ./selected-light.png
 
-# Review the completed translation before marking it current.
-releasekit translation mark 1.4.0 queue-action --locale en-US
+# Review facts, copy, translations, and selected images, then finalize.
 releasekit validate 1.4.0
 releasekit finalize 1.4.0
-releasekit export --current 1.4.0 --limit 3 --locale ko-KR --out ./release-output
+
+# Export when requested.
+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 `HEAD`; `--previous` can supply the comparison start.
+- `--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.
 
@@ -165,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:
@@ -184,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>
@@ -200,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.
 
@@ -235,7 +290,7 @@ releasekit/
         └── assets/            # Selected raster images
 ```
 
-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; finalized releases can be validated and exported without Git history.
+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.
 
@@ -249,7 +304,8 @@ Translations track source fingerprints, and finalized releases record content fi
 
 | Guide | What it covers |
 | --- | --- |
-| [Agent workflow](kit/references/workflow.md) | Git boundaries, drafts, review, and export. |
+| [First use in an existing product](kit/references/adoption.md) | Starting points, product introductions, historical analysis, and skipped history. |
+| [Agent workflow](kit/references/workflow.md) | Git boundaries, drafts and translations, images, finalization, and export. |
 | [Writing and translation](kit/references/writing.md) | Product copy, evidence, and locale freshness. |
 | [Visual language](kit/references/visual-language.md) | Composition, hierarchy, materials, and acceptance checks. |
 | [Choosing generated or supplied media](kit/references/media-sources.md) | Source selection, pending captures, and shared assets. |
@@ -274,7 +330,7 @@ npm run build
 npm pack --dry-run
 ```
 
-CI runs on Windows and Linux with Node.js 22 and 24. Tests cover Git ranges, release history, image integrity, theme policies, supplied media and shared assets, translation freshness, finalization, installation conflicts, and CLI behavior.
+CI runs on Windows and Linux with Node.js 22 and 24. Tests cover first-use setup, snapshot summaries, Git ranges, release history, image integrity, theme policies, supplied media and shared assets, translation freshness, finalization, installation conflicts, and CLI behavior.
 
 <details>
 <summary><strong>Install from a local checkout</strong></summary>

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

@@ -2,9 +2,9 @@
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
-import { Project, prepare } from './project.js';
+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';
@@ -29,9 +29,14 @@ program.command('init').description('Initialize content and install project skil
 program.command('update').description('Refresh managed skills while preserving user edits')
     .action(async () => { const result = await installSkills(project()); emit(result); if (result.conflicts.length)
     process.exitCode = 1; });
+program.command('start').description('Save the first-use Git boundary and treatment of earlier history')
+    .requiredOption('--at <ref>', 'baseline commit or tag; subsequent notes begin after this commit')
+    .addOption(new Option('--past <mode>', 'summarize the baseline, analyze history, or skip earlier notes').choices(['summary', 'history', 'skip']).makeOptionMandatory())
+    .option('--baseline-version <version>', 'baseline release ID, required for summary or history')
+    .action(async (options) => emit(await startProject(project(), { at: options.at, past: options.past, version: options.baselineVersion })));
 program.command('prepare <version>').description('Create a draft from pinned Git commits')
     .option('--from <ref>', 'comparison start commit or tag')
-    .option('--to <ref>', 'comparison end commit or tag', 'HEAD')
+    .option('--to <ref>', 'comparison end commit or tag, defaults to the saved baseline or HEAD')
     .option('--previous <version>', 'explicit previous release')
     .option('--from-root', 'explicitly include the whole history')
     .option('--first-release', 'start an independent release line')
@@ -45,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')
@@ -54,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')
@@ -74,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;
 }>;