@iodes/releasekit 0.1.2 → 0.1.4

package/dist/export.js

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

package/dist/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/images.d.ts

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

package/dist/images.js

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

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