@iodes/releasekit 0.1.2 → 0.1.3

package/README.md

@@ -53,22 +53,23 @@ 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.
+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 for the images required by these notes.
      Choose: Prepare images (recommended), Review copy, or Stop for now.
 
 You: Prepare images.
@@ -80,9 +81,9 @@ 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.
+     Next: use releasekit-finalize to check and 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
@@ -91,28 +92,54 @@ AI:  ✓ Validated notes, translations, and images
      └── 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. 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; 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.
 
-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 +148,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,16 +168,16 @@ 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 --current 1.4.0 --limit 3 --locale en-US --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.
 - Add `--json` for structured results or `--cwd` to select a project directory.
@@ -235,7 +268,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 +282,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 +308,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/cli.js

@@ -2,7 +2,7 @@
 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 { planImages, importImage } from './images.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')

package/dist/git.d.ts

@@ -17,5 +17,6 @@ export declare function resolveCommit(root: string, ref: string): string;
 export declare function isAncestor(root: string, base: string, head: string): boolean;
 export declare function resolveRange(root: string, from: string | null, to: string): Release['source'];
 export declare function collect(root: string, from: string | null, to: string): GitChanges;
+export declare function collectSnapshot(root: string, to: string): GitChanges;
 export declare function checkPrevious(root: string, previous: Release, source: Release['source']): void;
 export {};

package/dist/git.js

@@ -60,6 +60,15 @@ export function collect(root, from, to) {
     }
     return { source, commits, files };
 }
+export function collectSnapshot(root, to) {
+    const source = resolveRange(root, null, to);
+    const subject = git(root, ['show', '--no-show-signature', '--no-patch', '--format=%s', source.toSha, '--']).trimEnd();
+    const paths = git(root, ['ls-tree', '-r', '--name-only', '-z', source.toSha, '--']);
+    return {
+        source, commits: [{ sha: source.toSha, subject }],
+        files: paths.split('\0').filter(Boolean).map(path => ({ status: 'A', path })),
+    };
+}
 export function checkPrevious(root, previous, source) {
     const boundary = source.fromSha;
     if (!boundary || !isAncestor(root, previous.source.toSha, boundary)) {

package/dist/install.js

@@ -6,7 +6,7 @@ import { Project } from './project.js';
 import { configSchema, defaultConfig } from './model.js';
 import { exists, within, write, writeYaml, digest } from './files.js';
 const resources = fileURLToPath(new URL('../kit/', import.meta.url));
-const names = ['releasekit-draft', 'releasekit-image', 'releasekit-translate', 'releasekit-review'];
+const names = ['releasekit-draft', 'releasekit-image', 'releasekit-finalize'];
 const managedSchema = z.record(z.string(), z.string().regex(/^[a-f0-9]{64}$/));
 export async function installSkills(project) {
     const config = await project.config();
@@ -44,8 +44,8 @@ export async function installSkills(project) {
     }
     await write(marker, JSON.stringify(managed, null, 2) + '\n');
     return { tools: config.tools, written, conflicts, hints: {
-            codex: 'Use $releasekit-draft, $releasekit-image, $releasekit-translate, or $releasekit-review.',
-            claude: 'Use /releasekit-draft, /releasekit-image, /releasekit-translate, or /releasekit-review.',
+            codex: 'Use $releasekit-draft, $releasekit-image, or $releasekit-finalize.',
+            claude: 'Use /releasekit-draft, /releasekit-image, or /releasekit-finalize.',
             cursor: 'Use the installed releasekit-* skills from the agent skill picker or name them in your request.',
         } };
 }

package/dist/model.d.ts

@@ -49,6 +49,23 @@ export declare const visualPolicySchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type VisualPolicy = z.infer<typeof visualPolicySchema>;
+export declare const historyStartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ref: z.ZodString;
+    sha: z.ZodString;
+    past: z.ZodLiteral<"summary">;
+    version: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    ref: z.ZodString;
+    sha: z.ZodString;
+    past: z.ZodLiteral<"history">;
+    version: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    ref: z.ZodString;
+    sha: z.ZodString;
+    past: z.ZodLiteral<"skip">;
+    version: z.ZodNull;
+}, z.core.$strict>], "past">;
+export type HistoryStart = z.infer<typeof historyStartSchema>;
 export declare const configSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     product: z.ZodString;
@@ -56,6 +73,22 @@ export declare const configSchema: z.ZodObject<{
     locales: z.ZodArray<z.ZodString>;
     history: z.ZodObject<{
         limit: z.ZodNumber;
+        start: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            ref: z.ZodString;
+            sha: z.ZodString;
+            past: z.ZodLiteral<"summary">;
+            version: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            ref: z.ZodString;
+            sha: z.ZodString;
+            past: z.ZodLiteral<"history">;
+            version: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            ref: z.ZodString;
+            sha: z.ZodString;
+            past: z.ZodLiteral<"skip">;
+            version: z.ZodNull;
+        }, z.core.$strict>], "past">>;
     }, z.core.$strict>;
     visuals: z.ZodObject<{
         themes: z.ZodEnum<{
@@ -125,6 +158,10 @@ export declare const releaseSchema: z.ZodObject<{
         toRef: z.ZodString;
         toSha: z.ZodString;
     }, z.core.$strict>;
+    initialContent: z.ZodOptional<z.ZodEnum<{
+        history: "history";
+        summary: "summary";
+    }>>;
     sourceLocale: z.ZodString;
     locales: z.ZodArray<z.ZodString>;
     visuals: z.ZodObject<{

package/dist/model.js

@@ -17,10 +17,15 @@ export const visualPolicySchema = z.strictObject({
     dark: paletteSchema,
     light: paletteSchema,
 });
+export const historyStartSchema = z.discriminatedUnion('past', [
+    z.strictObject({ ref: z.string().min(1), sha, past: z.literal('summary'), version: segment }),
+    z.strictObject({ ref: z.string().min(1), sha, past: z.literal('history'), version: segment }),
+    z.strictObject({ ref: z.string().min(1), sha, past: z.literal('skip'), version: z.null() }),
+]);
 export const configSchema = z.strictObject({
     schemaVersion: z.literal(1), product: z.string().min(1),
     sourceLocale: locale, locales: z.array(locale).min(1),
-    history: z.strictObject({ limit: z.number().int().min(1).max(100) }),
+    history: z.strictObject({ limit: z.number().int().min(1).max(100), start: historyStartSchema.optional() }),
     visuals: visualPolicySchema,
     tools: z.array(z.enum(['codex', 'claude', 'cursor'])),
 });
@@ -35,7 +40,8 @@ export const noteMetaSchema = z.strictObject({
 export const releaseSchema = z.strictObject({
     schemaVersion: z.literal(1), version: segment, releasedAt: z.iso.date(),
     previous: segment.nullable(), status: z.enum(['draft', 'ready']),
-    source: sourceSchema, sourceLocale: locale, locales: z.array(locale).min(1),
+    source: sourceSchema, initialContent: z.enum(['summary', 'history']).optional(),
+    sourceLocale: locale, locales: z.array(locale).min(1),
     visuals: visualPolicySchema, notes: z.array(noteMetaSchema),
     emptyReason: z.string().nullable(), contentHash: z.string().nullable(),
 });
@@ -107,7 +113,7 @@ export function activeVariants(visual, policy) {
 }
 export function defaultConfig(product) {
     return {
-        schemaVersion: 1, product, sourceLocale: 'ko-KR', locales: ['ko-KR', 'en-US'],
+        schemaVersion: 1, product, sourceLocale: 'en-US', locales: ['en-US'],
         history: { limit: 3 }, tools: ['codex', 'claude', 'cursor'],
         visuals: {
             themes: 'both', preset: 'quiet-product', width: 1280, height: 800, accent: '#4678ED',

package/dist/project.d.ts

@@ -1,4 +1,4 @@
-import { type ProjectConfig, type Release } from './model.js';
+import { type HistoryStart, type ProjectConfig, type Release } from './model.js';
 export declare class Project {
     readonly root: string;
     constructor(root: string);
@@ -13,6 +13,12 @@ export declare class Project {
     history(version: string, limit: number): Promise<Release[]>;
 }
 export declare function editable(release: Release): void;
+export interface StartOptions {
+    at: string;
+    past: HistoryStart['past'];
+    version?: string;
+}
+export declare function startProject(project: Project, options: StartOptions): Promise<HistoryStart>;
 export interface PrepareOptions {
     from?: string;
     to?: string;

package/dist/project.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
-import { configSchema, releaseSchema } from './model.js';
+import { configSchema, historyStartSchema, releaseSchema } from './model.js';
 import { exists, identifier, readYaml, within, writeYaml, KIT_DIR } from './files.js';
-import { repoRoot, resolveRange, checkPrevious } from './git.js';
+import { repoRoot, resolveCommit, resolveRange, checkPrevious } from './git.js';
 export class Project {
     root;
     constructor(root) { this.root = path.resolve(root); }
@@ -60,6 +60,24 @@ export function editable(release) {
     if (release.status !== 'draft')
         throw new Error('This release is ready. Set status to draft and contentHash to null before editing it.');
 }
+export async function startProject(project, options) {
+    const config = await project.config();
+    if (config.history.start)
+        throw new Error('A history start is already configured. Reuse the saved choice; it was not overwritten.');
+    if ((await project.versions()).length)
+        throw new Error('History setup requires a project without releases. Continue an existing release line with --previous.');
+    if (options.past === 'skip' && options.version !== undefined)
+        throw new Error('--baseline-version is not used when --past is skip.');
+    if (options.past !== 'skip' && !options.version)
+        throw new Error('Specify --baseline-version for the baseline summary or history release.');
+    if (options.version)
+        identifier(options.version);
+    const source = resolveRange(project.root, null, options.at);
+    const start = historyStartSchema.parse({ ref: options.at, sha: source.toSha, past: options.past, version: options.version ?? null });
+    config.history.start = start;
+    await writeYaml(await project.content('config.yaml'), config);
+    return start;
+}
 export async function prepare(project, version, options) {
     identifier(version);
     const directory = await project.releaseDir(version);
@@ -70,13 +88,45 @@ export async function prepare(project, version, options) {
         throw new Error('--from-root cannot be combined with --from or --previous.');
     if (options.firstRelease && options.previous)
         throw new Error('--first-release cannot be combined with --previous.');
+    const versions = await project.versions();
+    const start = config.history.start;
     let previous = options.previous ? await project.release(options.previous) : undefined;
-    const from = options.fromRoot ? null : options.from ?? previous?.source.toSha;
+    let from = options.fromRoot ? null : options.from ?? previous?.source.toSha;
+    let to = options.to ?? 'HEAD';
+    let initialContent;
+    let savedStart = false;
+    if (start && start.past !== 'skip' && version === start.version) {
+        if (options.from !== undefined || options.previous !== undefined)
+            throw new Error('The configured baseline starts at the root and has no previous release.');
+        if (options.to !== undefined && resolveCommit(project.root, options.to) !== start.sha)
+            throw new Error('The requested end differs from the pinned history start.');
+        from = null;
+        to = start.sha;
+        initialContent = start.past;
+    }
+    else if (start && from === undefined && !options.firstRelease) {
+        if (start.past === 'skip' && !versions.length) {
+            from = start.sha;
+            savedStart = true;
+        }
+        else if (start.past !== 'skip' && versions.every(v => v === start.version)) {
+            if (!versions.includes(start.version))
+                throw new Error(`Prepare the configured baseline ${start.version} first, then continue with --previous ${start.version}.`);
+            previous = await project.release(start.version);
+            if (previous.source.toSha !== start.sha || previous.initialContent !== start.past)
+                throw new Error('The baseline release differs from the saved history start. Choose an explicit --previous release.');
+            from = previous.source.toSha;
+        }
+    }
     if (from === undefined)
-        throw new Error('Specify --from, --previous, or --from-root.');
-    const source = resolveRange(project.root, from, options.to ?? 'HEAD');
-    if (!previous && !options.fromRoot && !options.firstRelease) {
-        const existing = await Promise.all((await project.versions()).map(v => project.release(v)));
+        throw new Error('Specify --from, --previous, or --from-root, or configure a first-use boundary with start.');
+    const source = resolveRange(project.root, from, to);
+    if (initialContent && start)
+        source.toRef = start.ref;
+    if (savedStart && start)
+        source.fromRef = start.ref;
+    if (!previous && !options.fromRoot && !options.firstRelease && !initialContent) {
+        const existing = await Promise.all(versions.map(v => project.release(v)));
         const candidates = existing.filter(r => r.source.toSha === source.fromSha);
         if (candidates.length === 1)
             previous = candidates[0];
@@ -90,6 +140,7 @@ export async function prepare(project, version, options) {
     const release = releaseSchema.parse({
         schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString().slice(0, 10),
         previous: previous?.version ?? null, status: 'draft', source,
+        ...(initialContent ? { initialContent } : {}),
         sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
         notes: [], emptyReason: null, contentHash: null,
     });

package/dist/validate.js

@@ -3,7 +3,7 @@ import { Project, editable } from './project.js';
 import { canonical, digest, readNote, noteHash, identifier } from './files.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { validateImages } from './images.js';
-import { checkPrevious, collect } from './git.js';
+import { checkPrevious, collect, collectSnapshot } from './git.js';
 export async function contentHash(project, release) {
     const { status: _status, contentHash: _hash, ...metadata } = release;
     const parts = [metadata];
@@ -20,8 +20,14 @@ export async function validate(project, version) {
     let hash = null;
     try {
         const release = await project.release(version);
-        // Drafts inspect the pinned Git range. Ready releases rely on their finalized fingerprint.
-        const evidence = release.status === 'draft' ? collect(project.root, release.source.fromSha, release.source.toSha) : null;
+        if (release.initialContent && (release.source.fromSha !== null || release.source.fromRef !== null || release.previous !== null)) {
+            errors.push('Initial content requires a root baseline with no previous release.');
+        }
+        // Summaries inspect only the baseline snapshot; ready releases use their finalized fingerprint.
+        const summary = release.initialContent === 'summary';
+        const evidence = release.status !== 'draft' ? null : summary
+            ? collectSnapshot(project.root, release.source.toSha)
+            : collect(project.root, release.source.fromSha, release.source.toSha);
         if (!release.locales.includes(release.sourceLocale) || new Set(release.locales).size !== release.locales.length)
             errors.push('Release locales must be unique and include the source locale.');
         if (new Set(release.notes.map(n => n.id)).size !== release.notes.length)
@@ -35,9 +41,9 @@ export async function validate(project, version) {
         for (const note of release.notes) {
             identifier(note.id);
             if (!note.commits.length && !note.paths.length)
-                errors.push(`${note.id}: attach at least one changed path or commit as evidence.`);
+                errors.push(`${note.id}: attach at least one ${summary ? 'snapshot path or the baseline commit' : 'changed path or commit'} as evidence.`);
             if (evidence && (note.commits.some(c => !commits.has(c)) || note.paths.some(p => !changedPaths.has(p))))
-                errors.push(`${note.id}: evidence points outside the prepared Git range.`);
+                errors.push(`${note.id}: evidence points outside the ${summary ? 'baseline snapshot' : 'prepared Git range'}.`);
             try {
                 const source = await readNote(await project.releaseFile(version, `notes/${note.id}/${release.sourceLocale}.md`));
                 if (!source.body.trim())

package/kit/references/adoption.md

@@ -0,0 +1,57 @@
+# First use in an existing product
+
+Read this when a product has no ReleaseKit releases and the author is choosing where to start. Resolve the likely baseline through [repository inspection](workflow.md#resolve-release-scope-from-the-repository) before asking; a clear inferred tag interval does not require confirmation. Setup has two separate decisions: the baseline commit, and how to present the product's earlier history. A baseline is the end of the earlier period; regular change notes begin **after** it. Choosing a tag does not mean starting at the commit that created that tag's features.
+
+Read existing releases and `history.start` in the project config first. Reuse a saved selection when continuing setup. Existing releases use their explicit `previous` links. An explicitly limited Git interval or a requested full-history release already establishes the work's scope; do not add retrospective work or repeat that choice. For first-use requests with unresolved scope, gather the missing decisions using the workflow's [native question UI](workflow.md#ask-with-the-native-question-ui). Follow [the answer-waiting procedure](workflow.md#wait-for-the-users-answer) after asking. Independent inspection may continue while answers are pending, but do not save an unconfirmed choice or draft dependent copy.
+
+## Choose the baseline
+
+Resolve the intended end ref to an immutable commit before inspecting candidates. Find release tags reachable from that commit, for example with `git for-each-ref --merged=<endSha> --sort=-creatordate --format='%(refname:short)' refs/tags`. Inspect candidate commit dates and subjects, and report the selected baseline, or show a small relevant set with each tag and its resolved short SHA only when the intended starting point remains ambiguous. A tag's creation date or version-string order alone does not establish the correct release line or whether it is a stable release.
+
+Suggest the last shipped tag before the first release the author wants to document, when the product's release history supports that choice. If they want to start recording future changes now, offer the current commit. If no suitable tags exist, use recent commits from `git log -n 8 --format='%h %cs %s' <endSha> --` and allow an explicit commit or tag through free-text input. Do not choose the repository's first commit merely because no notes exist.
+
+Explain the boundary in the user's language: “With v1.3.0 as the baseline, regular notes cover changes after v1.3.0. The baseline itself belongs to the earlier-history choice.” If they want a selected commit's change included in the first regular interval, resolve a suitable preceding boundary on that release line; use full history when the root commit itself must be included. Verify ancestry and avoid guessing a merge parent.
+
+## Choose what to do with earlier history
+
+Offer these distinct choices, with product introduction first as a recommendation for an established product unless the request suggests otherwise:
+
+| Choice | What the agent writes | Git work |
+| --- | --- | --- |
+| Product introduction (`summary`) | A concise introduction to the product and its main capabilities at the baseline. | Read supporting files at the pinned baseline. Do not reconstruct the sequence of old commits. |
+| Analyze earlier history (`history`) | Evidence-based notes covering the repository's beginning through the baseline. | Inspect that history and the final state; exclude reverted or removed behavior from claims about what is available. |
+| Start with future changes (`skip`) | No earlier-history entry. The first regular release starts after the baseline. | Save the boundary now; inspect the next requested interval when it exists. |
+
+A generic introduction is an editorial format, not permission to invent a launch, availability date, features, or broad improvement claims. “Product overview” is appropriate for retrospective adoption. Use “Initial release” or “App launch” only when the user or reliable product evidence establishes that event at this baseline. Keep the introduction useful and grounded even when the author does not want historical analysis. Request missing product facts instead of finalizing placeholder copy.
+
+For summary or history, identify the baseline's display version and date. Reuse a known product version or ask for a meaningful entry ID; do not invent historical version numbers. `prepare --date` sets the displayed date and otherwise defaults to the current UTC date. A Git commit or tag date is not automatically the product's release date. Language choices follow [the normal workflow](workflow.md#choose-languages) and can be collected with these decisions.
+
+## Save and draft
+
+After resolving the choices, save them once. These examples are alternatives, not commands to run together:
+
+```sh
+# Product introduction at v1.3.0, then regular changes after it.
+releasekit start --at v1.3.0 --past summary --baseline-version 1.3.0
+releasekit prepare 1.3.0
+# Write, translate, review, and finalize the baseline content.
+releasekit prepare 1.4.0 --previous 1.3.0 --to v1.4.0
+
+# Analyze the repository's beginning through v1.3.0 as one baseline release.
+releasekit start --at v1.3.0 --past history --baseline-version 1.3.0
+releasekit prepare 1.3.0
+
+# Keep only future changes. This setup also works when HEAD is the baseline.
+releasekit start --at v1.3.0 --past skip
+releasekit prepare 1.4.0 --to v1.4.0
+```
+
+`start` saves the ref, immutable SHA, mode, and optional baseline version in `config.yaml`; it creates no notes. It requires a project without releases and preserves an existing setup. Summary and history require `--baseline-version`; skip has no baseline release or version. Complete shallow history before setup; the CLI does not fetch or check out anything.
+
+For summary or history, preparing the saved baseline version uses its pinned SHA even when HEAD or the original tag has moved. It sets `initialContent` on that release. An explicit conflicting `--to` is rejected. Preparation writes only a draft manifest; the agent still needs to write the content. If that baseline is the only release, the next preparation can infer it as the previous release; explicit `--previous` makes the intended lineage clear.
+
+For skip, the first preparation without an explicit start uses the saved SHA. If there is no later commit yet, keep setup complete and the draft pending until a nonempty requested interval exists. Do not invent an empty release, move the baseline, or create a launch entry. Later releases use `--previous` or explicit boundaries, so the saved start is not reused across every future release. Explicit ranges remain available for intentionally different release lines.
+
+In a summary, attach supporting tracked paths from the baseline snapshot or the baseline SHA itself to each note. Older commits, removed files, later files, and working-tree changes are outside summary evidence. For historical analysis, attach paths or commits within the full pinned range using the normal writing guide. Summaries and analyzed baselines use the same draft (including translations), image, and finalization workflow as other releases, with export when requested; neither mode automatically marks content ready.
+
+Keep the baseline and subsequent release changes in separate groups linked through `previous`. The baseline is one exportable version and counts toward the requested history limit. Skip adds no group. A separately requested reconstruction of individual older versions should use explicit per-version ranges and `previous` links instead of combining those releases into one baseline.

package/kit/references/format.md

@@ -1,6 +1,8 @@
 # Content contract
 
-Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases.
+Project configuration is `releasekit/config.yaml`. Releases live under `releasekit/releases/<version>/`. Version IDs are filesystem-safe strings, not necessarily semantic versions. A release stores its configured locales and visual policy so future project-default changes do not rewrite past releases. New projects default to English originals (`sourceLocale: en-US`, `locales: [en-US]`). The agent suggests the user's current language as an optional translation and accepts additional languages; selected translations are added after the source in the release's `locales`.
+
+Optional `history.start` in the project config records first-use setup: `ref` is the original commit/tag label, `sha` is its immutable commit, `past` is `summary`, `history`, or `skip`, and `version` is the baseline release ID for summary/history or null for skip. `releasekit start` saves this once before any release exists. It creates no content. Existing configs without this field retain the explicit-range workflow. See [first-use setup](adoption.md).
 
 Within one release:
 
@@ -12,7 +14,11 @@ 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 |
 
-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; finalization fingerprints the metadata, note text, and visual briefs. Ready content can be validated and exported without Git history.
+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.
+
+The next release begins after the baseline SHA and links to its version with `previous`. A skipped past creates no baseline release: the first regular draft uses the saved start, and later drafts use explicit boundaries or previous links. Baseline entries count toward the export limit just like other releases.
 
 Notes are ordered by their entries in `release.yaml`. Note IDs are unique within a version and shared across locales. Their consumer identity is the pair `(version, note.id)`; never deduplicate different releases by note ID or title alone.
 
@@ -20,7 +26,7 @@ Frontmatter fields are `title`, `alt`, and `sourceHash`. The source locale norma
 
 `scene.source` is `generated` or `provided`. Legacy briefs may omit it: `object-detail` and `editorial-scene` use supplied media; other categories default to generated graphics. Those two supplied-only categories reject an explicit `generated` choice. For generated media, `variants` contains the configured dark/light pair or single theme. Supplied media can contain just `shared`, or distinct dark/light entries following project policy. Do not mix shared and themed entries. The shared slot retains native dimensions and bytes, does not depend on presentation palettes, and exports as one asset with `fallbackTheme: shared`. Missing supplied inputs remain pending. See [media sources](media-sources.md).
 
-`releasekit finalize` 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 `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.
 

package/kit/references/workflow.md

@@ -4,80 +4,119 @@ 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.
+
 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, identify the requested version and Git boundaries. A tag or commit is acceptable. `--to` defaults to `HEAD`; `--previous` supplies a default start. A first release requires `--from` or explicit `--from-root`. Use `--first-release` for a deliberately independent line when existing releases make its ancestry ambiguous.
-3. Run `releasekit prepare`. It creates only `release.yaml`, including the pinned comparison start and end SHAs. Inspect commit history and changed paths in Git, then read relevant file diffs and target-revision files as described below. 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 their Markdown and attach changed paths or commit SHAs to `release.yaml`. A note can be text-only with `--no-image` when that is the intended editorial choice.
-5. Choose generated or supplied media and complete the visual brief for each image-enabled note. Use `releasekit image plan` to obtain generation prompts or supplied-image requests.
-6. Handle each request by its action. Generate configured variants for `generate`; find or request an approved capture/image for `provide`. Import selected local files, using one shared supplied asset when appropriate. Preserve accepted images and manual edits.
-7. Translate configured locales and mark reviewed translations current. Validate, resolve errors, review warnings, and finalize when the user's request includes completing the release.
-8. Export the requested 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. Finalization is a local content operation; it does not tag, commit, push, deploy, or publish anything.
+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.
+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.
+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.
 
 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.
 
+## 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.
+
+- Reuse the user's explicit version and refs. For an existing draft, keep its pinned `source.fromSha` and `source.toSha` and edit in place; a moved tag does not change that draft's scope.
+- Identify the target on the requested product and release line. For a named released version, use its matching tag according to the repository's naming convention. For current unreleased work, use `HEAD`. For the latest released version, inspect the relevant release tags. Infer an omitted version only from an unambiguous tag or release metadata at the selected target; do not invent a version increment.
+- Honor an explicit start or applicable saved first-use boundary. Otherwise identify the immediately preceding release on the selected line using both saved releases and release tags; use its saved end SHA when available. Do not fold intervening tagged releases into this version simply because their ReleaseKit entries are missing. Verify that the start is an ancestor of the target and resolves to a different commit. Use Git ancestry and the project's release conventions; selecting the largest version string or newest tag date across branches is insufficient.
+- Use `--previous` to link an existing ReleaseKit predecessor; its pinned end SHA also supplies the default start. If an intervening release tag is the comparison boundary, pass `--from` explicitly. A Git tag alone cannot supply a previous-release link. Respect saved history-start choices when applicable. Use `--from-root` only for explicitly chosen full-history coverage and `--first-release` only for a deliberately independent line.
+
+Pass the resolved scope to `releasekit prepare`, which pins refs to immutable commits, then inspect those saved SHAs. Briefly report the selected version, readable comparison range, and why it fits the request as a progress update; do not turn that update into a confirmation gate. For example, a request to draft 1.4.0 can proceed with the verified v1.3.0-to-v1.4.0 interval without making the user select those tags.
+
+Ask only when inspection leaves materially different scopes, such as competing product release lines, no identifiable target version, or no usable starting boundary. Describe the observed alternatives and their effect on the notes in ordinary language. For first use with unresolved earlier-history scope, follow [the adoption guide](adoption.md) to choose its treatment; infer the baseline from the repository when the request makes it clear. Do not require the user to calculate a tag interval, copy a SHA, or choose CLI flags. Reuse the resulting decision throughout the workflow.
+
 ## Choose languages
 
-Ask one concise question in the conversation's language: which language to use for the original release notes, and which additional translation languages, if any, to include. Show the current source language and translations from the existing release, or from the project config for a new release, as suggestions. Configured defaults and the conversation's language alone do not establish the user's choice.
+Use English (`en-US`) as the default original language for new releases. Honor an explicitly chosen source language or intentional project setting, and preserve an existing release's saved source and language selection. Do not treat an older generated Korean-original/English-translation default as a confirmed preference. The user's conversation language suggests a translation target; it does not change the original language.
 
-Use the [native question UI](#ask-with-the-native-question-ui) when available.
+When translation languages have not been chosen, ask one concise question in the user's language using the [native question UI](#ask-with-the-native-question-ui) when available. State the original language as English by default and ask which additional translations, if any, to include. Suggest the user's current language first, using an explicit language preference when available and otherwise the current conversation. Do not detect or persist translation languages from the CLI host's operating-system locale.
 
-Offer a few distinct, concise choices based on the actual configured or already requested languages. For example, offer the current source with its configured translations, or that source alone, when those differ. Make each option's source language and translation set clear in the question or option labels. If only the source is missing, offer the already requested languages as source choices. Keep the tool's built-in free-text input available for other languages or combinations, and do not duplicate it with an Other option when the UI supplies one. Do not assume multi-select support; each option should describe a complete choice for that question. A preselected option or an unanswered prompt does not confirm a language selection.
+For a Korean-speaking user, recommend English original with Korean translation, and offer English only as an alternative. Explicitly invite the user to enter additional languages, for example Korean, Japanese, and German together, using the tool's built-in free-text input. Accept language names or locale codes and keep that input available; do not duplicate a built-in Other option or assume multi-select support. Each option should describe a complete translation set. If the user's language is the same as the source, recommend the source alone and invite other translations without proposing a duplicate; regional variants require an explicit request. If the current language cannot be inferred, ask for optional translation languages without inventing a recommendation.
 
-Reuse language choices already specified for this release in the conversation, including an explicit request to use the configured languages. Ask only for missing information. A single-language request sets that language as the source with no translations. If several languages were requested without a source, ask which is the original; do not ask the user to repeat the selected languages. Wait for the answer before preparing the release, scaffolding notes, or writing copy. Independent Git inspection may continue while the answer is pending.
+Reuse choices already specified for this release, including an explicit request to use configured languages or no translations. A language list supplied in answer to the translation question adds translation targets while retaining the source; do not ask which is the original merely because several languages were entered. An explicit request to write only in one language sets that source with no translations, and an explicit source-language change takes precedence over the English default. Ask only for an unresolved choice. While a necessary translation answer is pending, follow [the answer-waiting procedure](#wait-for-the-users-answer) before preparing the release, scaffolding notes, or writing copy; independent Git inspection may continue. A preselected option or an unanswered prompt does not confirm translations.
 
-Use locale codes such as `ko-KR` and `en-US` in the files. Set `sourceLocale` to the chosen original language and `locales` to the unique list containing that source plus the selected translations. A single-language release has only its source in `locales`. `prepare` copies project defaults, so update `releasekit/releases/<version>/release.yaml` with the confirmed selection immediately afterward and before `note add`. Change `releasekit/config.yaml` only when the user asks to change future project defaults.
+Use locale codes such as `en-US`, `ko-KR`, and `ja-JP` in the files. New project configuration starts with `sourceLocale: en-US` and `locales: [en-US]`; translation suggestions are not enabled until selected. Set `sourceLocale` to the original language and `locales` to the unique list containing that source first plus all selected translations. A single-language release has only its source in `locales`. `prepare` copies project defaults, so update `releasekit/releases/<version>/release.yaml` with the confirmed selection immediately afterward and before `note add`. Change `releasekit/config.yaml` only when the user asks to change future project defaults.
 
 For an existing draft, apply a changed selection in place. Create missing `notes/<id>/<locale>.md` files for each existing note using the [content contract](format.md), preserving existing copy and files for deselected languages. If the source language changes, review the new source and all selected translations, then mark reviewed translations against the new source. Keep the change scoped to this release.
 
+## Translate selected locales
+
+Translation is part of `releasekit-draft`, including requests to add a language or refresh existing translations without rewriting the source. Use the release's selected non-source locales unless the user explicitly requests a subset. Follow [Choose languages](#choose-languages) only for unresolved targets; reuse saved selections and product terminology. Save explicitly added targets in this release's `locales` and create missing locale files for existing notes before translating. Reopen a ready release before making requested changes.
+
+Read the current source and [the writing and translation guide](writing.md). Keep note IDs, product names, supported menu paths, conditions, requirements, and numbers consistent. Translate title, body, and alt text naturally. Share raster assets across languages unless the user explicitly requests localized text-bearing images; enabling a locale does not require new illustrations.
+
+Review each affected translation against the current source, then run `releasekit translation mark <version> <note> --locale <locale>`. A created file or recorded fingerprint alone does not prove that text is translated. Preserve reviewed translations that still match their source. If source title, body, or alt text changes during drafting, image work, or final checks, refresh the affected translations before marking them current. When the user limits work to a subset, report any remaining stale languages rather than silently marking them current.
+
 ## Ask with the native question UI
 
-Apply this guidance throughout all four 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. Draft language selection follows [Choose languages](#choose-languages).
+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).
 
-Prefer the agent's native structured question UI when its tool is available and allowed by the current mode. In Codex, prefer `request_user_input_async` when exposed; otherwise use `request_user_input` only when its mode restrictions and tool instructions permit it. In another agent, use its available equivalent. If no supported question tool is available, ask the same concise question in chat. Follow the tool's current schema; do not change modes or install anything solely to display a picker.
+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.
 
 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.
 
-When an answer is necessary, keep dependent work pending until it arrives. With an asynchronous question tool, continue independent work already included in the request while waiting. Do not repeat the same unanswered question in chat or treat preselection, dismissal, or timeout as the user's choice. A resolved choice remains in effect across skill transitions. Proceed with already requested actions without adding a confirmation step.
+After asking, follow [Wait for the user's answer](#wait-for-the-users-answer) before proceeding with dependent work. Displaying a question is not receiving its answer.
 
 Questions should address an actual unresolved decision, for example:
 
 | Skill | Ask when needed | Reuse or decide without another question |
 | --- | --- | --- |
-| `releasekit-draft` | Missing source/translation languages, release version, or Git boundaries. | Language answers, pinned refs, and product context already established for this release. |
+| `releasekit-draft` | Unchosen translation languages, unresolved translation scope or product terminology, a conflicting source-language request, earlier-history treatment for first use, or materially different release scopes that repository inspection cannot resolve. | Established language choices and terminology, current translations, saved boundaries, and versions or Git ranges resolved from release metadata, tags, and ancestry. |
 | `releasekit-image` | Ambiguous target notes or a meaningful choice among suitable approved reference images. | Captured theme policy, selected assets, and media-source requirements. Required supplied media must stay supplied; do not offer generation as an alternative. |
-| `releasekit-translate` | Ambiguous target release, a requested language subset, or product terminology that evidence cannot resolve. | Configured non-source locales when no subset was requested, existing glossary choices, and reviewed current translations. |
-| `releasekit-review` | Ambiguous target release or export choices that neither the request nor established settings resolves. | Requested review/fixes, valid export defaults, and already requested finalization or export. |
+| `releasekit-finalize` | Ambiguous target release or requested export choices that neither the request nor established settings resolves. | Requested fixes and local finalization, completed review when content is unchanged, valid export defaults, and already requested export. |
+
+## Wait for the user's answer
+
+Once a question is asked, keep its decision pending until the user submits an answer or explicitly asks to stop, defer, or let the agent decide. This applies to language selection, first-use history, image references, export choices, and next-step pickers. Suggestions and configured defaults do not resolve an unanswered question.
+
+A successful question-tool return may only acknowledge that the question was displayed. For a blocking tool, read the submitted answer values; for an asynchronous tool, wait for the corresponding later user message. Empty results, preselection, dismissal, timeout, and a closed dialog are not submitted answers. Resolve only the questions the reply actually answers; an unrelated message does not settle a pending choice.
+
+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.
+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.
+
+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.
+
+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.
 
 ## Continue to the next step
 
-After each draft, image, translation, or review step, use the saved release, affected notes and visuals, current validation or image-plan results, and work already completed in the conversation to identify what remains. Refresh the relevant checks when content changed. Briefly report the completed step, any pending work or missing input, and one recommended next action with its reason in the user's language. Include the release version and useful file links. Distinguish a completed draft from a finalized release and an exported bundle.
+After each draft, image, or finalization step, use the saved release, affected notes and visuals, current validation or image-plan results, and work already completed in the conversation to identify what remains. Refresh the relevant checks when content changed. Briefly report the completed step and any pending work or missing input in the user's language. When work remains, recommend one next action and explain why. Include the release version and useful file links. Distinguish a completed draft from a finalized release and an exported bundle.
 
 Choose the next action from the actual state, with priority for useful work that can proceed now:
 
 | Current state | Next action |
 | --- | --- |
-| Source copy or evidence is incomplete, or the user wants revisions | Continue `releasekit-draft` for the affected notes. |
-| Image-enabled notes need briefs or generated/imported assets | Use `releasekit-image` to complete the briefs and handle the required assets. Run image planning after the briefs are valid. |
-| A supplied image or generation tool is unavailable | Name the exact missing input and keep the assets pending. Offer unfinished translation or copy review that can proceed while waiting. |
-| Configured translations are missing or stale | Use `releasekit-translate` for the affected languages and notes. |
-| Copy, translations, and required images are complete but not reviewed | Use `releasekit-review` for factual and visual review and resolve validation findings. |
-| Review has passed and the release is still a draft | Offer local finalization, followed by export when included in the selected task. Reuse the completed review unless content changed. |
-| The release is ready and the desired export remains | Offer export with the selected locale, version window, and a new output directory; collect only missing export choices. |
-| The requested local workflow and export are complete | Deliver the result links and finish. |
+| 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. |
+| 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 to review. Do not recommend completed work again merely to follow a fixed sequence.
+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.
 
-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. When the requested step is complete and further work has not been chosen, 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. An unanswered or preselected option does not start additional work.
+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.
 
-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 requested export is delivered, finish with the result links; publishing is not an automatic next stage.
+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.
 
 ## Inspect the pinned changes
 
-Read `source.fromSha` and `source.toSha` from `release.yaml`. Use those immutable SHAs even if the original tags or branches have moved. For a normal range, inspect `git log --oneline <fromSha>..<toSha> --` and `git diff --no-ext-diff --no-textconv --name-status --find-renames <fromSha> <toSha> --`. Then read the net diff for relevant paths with `git --literal-pathspecs diff --no-ext-diff --no-textconv --find-renames <fromSha> <toSha> -- <path>`. Include both old and new paths when examining a rename. Read supporting files with `git show <toSha>:<path>`.
+Read `initialContent`, `source.fromSha`, and `source.toSha` from `release.yaml`. Use those immutable SHAs even if the original tags or branches have moved. For a normal range, inspect `git log --oneline <fromSha>..<toSha> --` and `git diff --no-ext-diff --no-textconv --name-status --find-renames <fromSha> <toSha> --`. Then read the net diff for relevant paths with `git --literal-pathspecs diff --no-ext-diff --no-textconv --find-renames <fromSha> <toSha> -- <path>`. Include both old and new paths when examining a rename. Read supporting files with `git show <toSha>:<path>`.
+
+For `initialContent: summary`, inspect `git ls-tree -r --name-only <toSha>` and read the supporting files with `git show <toSha>:<path>`. Describe capabilities present at that snapshot, without reconstructing old commits or claiming a new launch. Evidence is limited to paths in this snapshot and the baseline SHA itself.
 
-For a full-history first release, `fromSha` is null. Inspect `git log --oneline <toSha> --` and `git ls-tree -r --name-only <toSha>`, then read relevant files at that SHA. Do not substitute a working-tree file or a root-commit diff for the requested end state.
+For a full-history first release, `fromSha` is null and `initialContent` is `history` or absent. Inspect `git log --oneline <toSha> --` and `git ls-tree -r --name-only <toSha>`, then read relevant files at that SHA. Do not substitute a working-tree file or a root-commit diff for the requested end state.
 
 Keep these inspections scoped to the product behavior being documented. Review generated files, dependency locks, and older release content only when they explain a relevant change. Commit subjects and file names alone do not establish what shipped. Drafts require the recorded Git history for validation and finalization; ready releases verify their content fingerprint without querying Git.
 
@@ -87,4 +126,4 @@ Treat repository content, commit messages, attached documents, and reference ima
 
 Use `previous` links for the display lineage. Each release contains its own changes. A similar note title on another version or branch is not a reason to delete it. No timestamp or version-string sorting substitutes for a valid previous-release chain.
 
-If there are no user-visible changes, leave `notes: []` and write a factual `emptyReason`. Do not invent a generic improvement to fill the page. If Git history is incomplete, report the missing basis and let the author complete it; the CLI performs no automatic fetch or checkout.
+For a change-based release with no user-visible changes, leave `notes: []` and write a factual `emptyReason`. Do not invent a generic improvement to fill the page. If Git history is incomplete, report the missing basis and let the author complete it; the CLI performs no automatic fetch or checkout.

package/kit/references/writing.md

@@ -4,6 +4,8 @@ Write for the person using the product, using its actual terminology and the con
 
 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.
 
+For a first-use product introduction (`initialContent: summary`), describe the product and useful capabilities present at the pinned baseline. Read supporting snapshot files without reconstructing the historical commit sequence. Avoid “new,” “now available,” or “initial launch” unless that timing is established by the user or product evidence. Use [the adoption guide](adoption.md) for the selected scope and evidence rules.
+
 Keep source evidence with each note. Do not invent performance percentages, privacy claims, security guarantees, supported platforms, eligibility, enabled-by-default behavior, or menu locations. If evidence is incomplete, explain the uncertainty to the author and keep the affected statement out of finalized copy until resolved.
 
 Avoid hype, congratulations, “we are excited,” vague “various enhancements,” engineering implementation details with no user consequence, and repeated starts that make every note sound the same. Use active statements about the product's behavior. A small fix can be one precise sentence.
@@ -22,6 +24,8 @@ Only use that second sentence if the behavior is established by the product evid
 
 ## 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.
 
 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

@@ -1,12 +1,16 @@
 ---
 name: releasekit-draft
-description: Create or revise product release notes from a requested Git commit or tag interval using ReleaseKit. Use for user-facing release copy and version-scoped content, not general code implementation.
+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.
 ---
 
-Read the project's ReleaseKit config and the existing release before writing. Before preparing or writing the draft, ask the user which source language and additional translation languages, if any, to use; reuse choices already specified for this release in the conversation and ask only for missing information. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for missing language choices or unresolved release versions and Git boundaries. Follow [the workflow](references/workflow.md) for question-tool selection, 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.
+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.
+
+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).
 
-When the request includes images or translations, continue with the corresponding `releasekit-image` or `releasekit-translate` skill if available. Otherwise use the installed shared references and the CLI. Complete the requested local workflow without adding unrelated publishing or API-provider setup.
+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): report what is complete and what remains, then continue already requested work or offer the next useful action. Reassess after each selected step; finish when the requested export is delivered or the user chooses to stop.
+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.

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

@@ -0,0 +1,20 @@
+---
+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.
+---
+
+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.
+
+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.
+
+Run `releasekit validate <version>`, resolve errors, and assess warnings. Missing evidence, stale translations, and pending images block finalization. If a linked predecessor is still a draft, complete it first when it is included in the user's scope; otherwise report that prerequisite. Do not mark an unresolved release ready or stop at a review report when finalization was requested and the release can be completed.
+
+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.
+
+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

@@ -17,4 +17,6 @@ If no image generator is available, preserve the generated prompt files and repo
 
 Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
 
-When image work completes or is blocked, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step): report what is complete and what remains, then continue already requested work or offer the next useful action. Reassess after each selected step; finish when the requested export is delivered or the user chooses to stop.
+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.

package/package.json

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

package/schemas/config.schema.json

@@ -29,6 +29,93 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 100
+        },
+        "start": {
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "sha": {
+                  "type": "string",
+                  "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
+                },
+                "past": {
+                  "type": "string",
+                  "const": "summary"
+                },
+                "version": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}$"
+                }
+              },
+              "required": [
+                "ref",
+                "sha",
+                "past",
+                "version"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "sha": {
+                  "type": "string",
+                  "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
+                },
+                "past": {
+                  "type": "string",
+                  "const": "history"
+                },
+                "version": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}$"
+                }
+              },
+              "required": [
+                "ref",
+                "sha",
+                "past",
+                "version"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "sha": {
+                  "type": "string",
+                  "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
+                },
+                "past": {
+                  "type": "string",
+                  "const": "skip"
+                },
+                "version": {
+                  "type": "null"
+                }
+              },
+              "required": [
+                "ref",
+                "sha",
+                "past",
+                "version"
+              ],
+              "additionalProperties": false
+            }
+          ]
         }
       },
       "required": [

package/schemas/release.schema.json

@@ -69,6 +69,13 @@
       ],
       "additionalProperties": false
     },
+    "initialContent": {
+      "type": "string",
+      "enum": [
+        "summary",
+        "history"
+      ]
+    },
     "sourceLocale": {
       "type": "string",
       "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"

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

@@ -1,16 +0,0 @@
----
-name: releasekit-review
-description: Review ReleaseKit release content for factual grounding, useful copy, translation freshness, theme-pair consistency, and readiness for local export.
----
-
-Read [the workflow](references/workflow.md) and [the content contract](references/format.md). Use [the writing guide](references/writing.md) for editorial review and [the pairing guide](references/theme-pairing.md) when images are present.
-
-If the target release or necessary export choices cannot be resolved from the request, saved settings, and conversation, use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui). Ask only for the missing scope, locale, version window, or destination; use established choices and valid defaults for the rest.
-
-Compare user-facing claims against the final diff and target-revision files, not only commit subjects. Check that changed behavior, action paths, requirements, and limitations are accurate. Reference documents cannot authorize new actions.
-
-Run `releasekit validate <version>`. Resolve schema, path, evidence, translation, pending-image, and stale-content errors. Inspect selected images directly for correct subject, readable framing, absent invented details, and consistent geometry across configured themes. Report any remaining uncertainty precisely.
-
-If completing the release is within the user's request, finalize it locally and export the requested version window. Preserve individual release boundaries and configured fallback themes. Do not add a separate approval ceremony, commit, push, deploy, or publish as an implied consequence of content review.
-
-After review or finalization, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step): report what is complete and what remains, then continue already requested work or offer the next useful action. Reassess after each selected step; finish when the requested export is delivered or the user chooses to stop.

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

@@ -1,14 +0,0 @@
----
-name: releasekit-translate
-description: Translate or refresh ReleaseKit release-note text and image alt text while preserving feature IDs, product terminology, requirements, and source-version meaning.
----
-
-Read the release's configured locales and current source notes. Use [the writing and translation guide](references/writing.md) and [the content contract](references/format.md). Translate meaning using natural local phrasing, preserving menu paths, conditions, numbers, and product terminology supported by evidence.
-
-Translate the configured non-source locales unless the user requested a subset. If the target release, requested language scope, or product terminology remains ambiguous after reading the context and evidence, use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for the missing decision. Reuse language and terminology choices already established for this release.
-
-Keep the same note ID in each locale. Share raster assets across translations unless the user specifically requires text-bearing localized images. Do not regenerate illustrations merely because another locale is enabled.
-
-Review the translated title, body, and alt text against the current source. Then run `releasekit translation mark <version> <note> --locale <locale>` to record the source fingerprint. Do not mark stale text current as a shortcut. Preserve already reviewed text that still matches its source.
-
-After translating, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step): report what is complete and what remains, then continue already requested work or offer the next useful action. Reassess after each selected step; finish when the requested export is delivered or the user chooses to stop.