@iodes/releasekit 0.1.1 → 0.1.3

package/README.md

@@ -53,29 +53,37 @@ 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.
-     Write Korean and English notes.
-AI:  Created releasekit/releases/1.4.0/
-     ✓ Pinned the Git range and collected change evidence
-     ✓ Wrote release notes in ko-KR and en-US
-
-You: Add images for the 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.
 AI:  ✓ Generated dark/light explanations from shared scene briefs
      ✓ Reviewed and imported both variants for each generated graphic
      The product-detail image is pending; I need an approved capture
-     or photo. Translation work can continue while it is pending.
+     or photo. Next: provide that image, or review the completed copy
+     while it is pending.
 
 You: Use ./approved-capture.png for the product-detail note.
 AI:  ✓ Reviewed and imported it once for both viewer themes
+     Next: use releasekit-finalize to check and confirm 1.4.0.
 
-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
@@ -84,22 +92,54 @@ AI:  ✓ Validated notes, translations, and images
      └── assets/             ← Theme variants and shared supplied images
 ```
 
+The agent resolves the version and Git range from your request, saved releases, repository tags, and release metadata. It reports a clear scope and proceeds without a tag-selection or confirmation step. If inspection leaves materially different scopes, it asks which work to cover in ordinary language. You can still supply explicit refs to select a particular interval.
+
+The draft skill defaults the original language to English and suggests the user's current language for optional translation. Its question accepts additional language names or locale codes through free-text input, as well as an English-only choice. An English-speaking user is not offered a duplicate English translation. Explicit source choices and existing release selections are reused. The selection is saved for that release; future project defaults change only when requested. The draft includes the source and those selected translations. Use the same draft skill later to add a language or refresh translations.
+
 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. |
 
-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.
+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. When source and translations are complete, the next step is images; when required images are complete, it is finalization. Text-only releases go directly to finalization. Completed steps are skipped, and missing images or translations stay visible until resolved.
+
+The agent handles editorial work, media selection, and image generation where appropriate. The CLI handles files, evidence, validation, and export. Finalization includes review and marks local content ready with a content fingerprint. Export is optional; committing, publishing, and displaying it remain separate steps.
 
 <details>
 <summary><strong>Step-by-step CLI workflow</strong></summary>
@@ -108,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
 
@@ -122,15 +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.
@@ -215,14 +262,14 @@ releasekit/
 └── releases/
     └── 1.4.0/
         ├── release.yaml       # Metadata, note order, previous release
-        ├── evidence.json      # Pinned Git evidence
-        ├── changes.patch      # Net change for this release
         ├── notes/             # Markdown for each locale
         ├── visuals/           # Scene briefs, media sources, and variants
         ├── prompts/           # Prompts for pending generated variants
         └── 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, 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.
 
 The bundle contains display data and relative assets. Git evidence, prompts, and private source paths stay out of the export. Consumers safely render `bodyMarkdown` and select `image.variants[theme]`, falling back to `image.variants[image.fallbackTheme]` when needed. Text-only notes have `image: null`.
@@ -235,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. |
@@ -260,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

@@ -1,10 +1,22 @@
-import { type Evidence, type Release } from './model.js';
+import type { Release } from './model.js';
+interface GitChanges {
+    source: Release['source'];
+    commits: Array<{
+        sha: string;
+        subject: string;
+    }>;
+    files: Array<{
+        status: string;
+        path: string;
+        oldPath?: string;
+    }>;
+}
 export declare function git(cwd: string, args: string[], input?: string): string;
 export declare function repoRoot(cwd: string): string;
 export declare function resolveCommit(root: string, ref: string): string;
 export declare function isAncestor(root: string, base: string, head: string): boolean;
-export declare function collect(root: string, from: string | null, to: string): {
-    evidence: Evidence;
-    patch: string;
-};
-export declare function checkPrevious(root: string, previous: Release, evidence: Evidence): void;
+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

@@ -1,5 +1,4 @@
 import { spawnSync } from 'node:child_process';
-import { evidenceSchema } from './model.js';
 export function git(cwd, args, input) {
     const result = spawnSync('git', args, {
         cwd, input, encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024,
@@ -27,7 +26,7 @@ export function isAncestor(root, base, head) {
         return false;
     throw new Error(`Cannot establish Git ancestry: ${result.stderr || result.error?.message}`);
 }
-export function collect(root, from, to) {
+export function resolveRange(root, from, to) {
     if (git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true') {
         throw new Error('Complete the shallow Git history before preparing a release; no fetch was performed.');
     }
@@ -38,6 +37,11 @@ export function collect(root, from, to) {
     if (fromSha && !isAncestor(root, fromSha, toSha)) {
         throw new Error('The start commit is not an ancestor of the end commit. Choose an explicit range on this release line.');
     }
+    return { fromRef: from, fromSha, toRef: to, toSha };
+}
+export function collect(root, from, to) {
+    const source = resolveRange(root, from, to);
+    const { fromSha, toSha } = source;
     const base = fromSha ?? git(root, ['hash-object', '-t', 'tree', '--stdin'], '').trim();
     const log = git(root, ['log', '--no-show-signature', '--format=%H%x00%s', fromSha ? `${fromSha}..${toSha}` : toSha, '--']);
     const commits = log.trimEnd() ? log.trimEnd().split('\n').map(line => {
@@ -54,14 +58,19 @@ export function collect(root, from, to) {
         else
             files.push({ status, path: first });
     }
-    const patch = git(root, ['diff', '--no-ext-diff', '--no-textconv', '--find-renames', base, toSha, '--']);
+    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 {
-        evidence: evidenceSchema.parse({ schemaVersion: 1, source: { fromRef: from, fromSha, toRef: to, toSha }, commits, files }),
-        patch,
+        source, commits: [{ sha: source.toSha, subject }],
+        files: paths.split('\0').filter(Boolean).map(path => ({ status: 'A', path })),
     };
 }
-export function checkPrevious(root, previous, evidence) {
-    const boundary = evidence.source.fromSha;
+export function checkPrevious(root, previous, source) {
+    const boundary = source.fromSha;
     if (!boundary || !isAncestor(root, previous.source.toSha, boundary)) {
         throw new Error('The previous release is not an ancestor of this comparison start. Choose the correct previous release.');
     }

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<{
@@ -275,25 +312,6 @@ export declare const visualSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type Visual = z.infer<typeof visualSchema>;
-export declare const evidenceSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    source: z.ZodObject<{
-        fromRef: z.ZodNullable<z.ZodString>;
-        fromSha: z.ZodNullable<z.ZodString>;
-        toRef: z.ZodString;
-        toSha: z.ZodString;
-    }, z.core.$strict>;
-    commits: z.ZodArray<z.ZodObject<{
-        sha: z.ZodString;
-        subject: z.ZodString;
-    }, z.core.$strict>>;
-    files: z.ZodArray<z.ZodObject<{
-        status: z.ZodString;
-        path: z.ZodString;
-        oldPath: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type Evidence = z.infer<typeof evidenceSchema>;
 export declare const bundleSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     currentVersion: z.ZodString;

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(),
 });
@@ -64,11 +70,6 @@ export const visualSchema = z.strictObject({
     schemaVersion: z.literal(1), scene: sceneSchema,
     variants: z.strictObject({ dark: assetSchema.optional(), light: assetSchema.optional(), shared: assetSchema.optional() }),
 });
-export const evidenceSchema = z.strictObject({
-    schemaVersion: z.literal(1), source: sourceSchema,
-    commits: z.array(z.strictObject({ sha, subject: z.string() })),
-    files: z.array(z.strictObject({ status: z.string(), path: z.string(), oldPath: z.string().optional() })),
-});
 const exportedImage = z.strictObject({
     src: z.string(), width: z.number().int().positive(), height: z.number().int().positive(),
 });
@@ -112,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, type Evidence } from './model.js';
+import { type HistoryStart, type ProjectConfig, type Release } from './model.js';
 export declare class Project {
     readonly root: string;
     constructor(root: string);
@@ -10,10 +10,15 @@ export declare class Project {
     release(version: string): Promise<Release>;
     save(release: Release): Promise<void>;
     versions(): Promise<string[]>;
-    evidence(version: string): Promise<Evidence>;
     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, evidenceSchema } from './model.js';
-import { exists, identifier, readYaml, within, writeYaml, write, KIT_DIR } from './files.js';
-import { repoRoot, collect, checkPrevious } from './git.js';
+import { configSchema, historyStartSchema, releaseSchema } from './model.js';
+import { exists, identifier, readYaml, within, writeYaml, KIT_DIR } from './files.js';
+import { repoRoot, resolveCommit, resolveRange, checkPrevious } from './git.js';
 export class Project {
     root;
     constructor(root) { this.root = path.resolve(root); }
@@ -37,9 +37,6 @@ export class Project {
         const entries = await fs.readdir(folder, { withFileTypes: true });
         return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
     }
-    async evidence(version) {
-        return evidenceSchema.parse(JSON.parse(await fs.readFile(await this.releaseFile(version, 'evidence.json'), 'utf8')));
-    }
     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.');
@@ -63,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);
@@ -73,31 +88,62 @@ 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 { evidence, patch } = collect(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)));
-        const candidates = existing.filter(r => r.source.toSha === evidence.source.fromSha);
+        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];
         else if (existing.length)
             throw new Error('Previous release is ambiguous. Specify --previous, or --first-release for an independent release line.');
     }
     if (previous) {
-        checkPrevious(project.root, previous, evidence);
+        checkPrevious(project.root, previous, source);
         await project.history(previous.version, 1);
     }
     const release = releaseSchema.parse({
         schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString().slice(0, 10),
-        previous: previous?.version ?? null, status: 'draft', source: evidence.source,
+        previous: previous?.version ?? null, status: 'draft', source,
+        ...(initialContent ? { initialContent } : {}),
         sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
         notes: [], emptyReason: null, contentHash: null,
     });
     await project.save(release);
-    await write(await project.releaseFile(version, 'evidence.json'), JSON.stringify(evidence, null, 2) + '\n');
-    await write(await project.releaseFile(version, 'changes.patch'), patch);
     return release;
 }

package/dist/schema-export.js

@@ -1,10 +1,17 @@
 import * as fs from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { configSchema, releaseSchema, visualSchema, noteTextSchema, evidenceSchema, bundleSchema } from './model.js';
+import { configSchema, releaseSchema, visualSchema, noteTextSchema, bundleSchema } from './model.js';
 const directory = fileURLToPath(new URL('../schemas/', import.meta.url));
 await fs.mkdir(directory, { recursive: true });
-for (const [name, schema] of Object.entries({ config: configSchema, release: releaseSchema, visual: visualSchema, note: noteTextSchema, evidence: evidenceSchema, bundle: bundleSchema })) {
+const schemas = { config: configSchema, release: releaseSchema, visual: visualSchema, note: noteTextSchema, bundle: bundleSchema };
+for (const [name, schema] of Object.entries(schemas)) {
     const json = { ...z.toJSONSchema(schema), $id: `urn:releasekit:${name}:1` };
     await fs.writeFile(`${directory}/${name}.schema.json`, JSON.stringify(json, null, 2) + '\n');
 }
+// Keep the generated directory aligned with the schemas the package exports.
+const outputs = new Set(Object.keys(schemas).map(name => `${name}.schema.json`));
+for (const file of await fs.readdir(directory)) {
+    if (file.endsWith('.schema.json') && !outputs.has(file))
+        await fs.unlink(`${directory}/${file}`);
+}