@iodes/releasekit 0.1.6 → 0.2.0

package/dist/install.d.ts

@@ -1,23 +1,40 @@
 import { Project } from './project.js';
 import { type ProjectConfig } from './model.js';
-export declare function installSkills(project: Project): Promise<{
+export declare function installSkills(project: Project, tools?: ProjectConfig['tools']): Promise<{
     tools: ("claude" | "codex" | "cursor")[];
     written: string[];
     conflicts: string[];
+    unchanged: string[];
     hints: {
         codex: string;
         claude: string;
         cursor: string;
     };
 }>;
-export declare function initProject(project: Project, options: {
+export declare function updateProject(project: Project): Promise<{
+    tools: ("claude" | "codex" | "cursor")[];
+    written: string[];
+    conflicts: string[];
+    unchanged: string[];
+    hints: {
+        codex: string;
+        claude: string;
+        cursor: string;
+    };
+}>;
+export declare function formatUpdate(result: Awaited<ReturnType<typeof installSkills>>): string;
+export interface InitOptions {
     product?: string;
     tools?: ProjectConfig['tools'];
     themes?: ProjectConfig['visuals']['themes'];
-}): Promise<{
+    sourceLocale?: string;
+    locales?: string[];
+}
+export declare function initProject(project: Project, options: InitOptions): Promise<{
     tools: ("claude" | "codex" | "cursor")[];
     written: string[];
     conflicts: string[];
+    unchanged: string[];
     hints: {
         codex: string;
         claude: string;

package/dist/install.js

@@ -8,13 +8,14 @@ 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-finalize'];
 const managedSchema = z.record(z.string(), z.string().regex(/^[a-f0-9]{64}$/));
-export async function installSkills(project) {
+export async function installSkills(project, tools) {
     const config = await project.config();
+    const selected = tools ?? config.tools;
     const marker = await project.content('managed-skills.json');
     const managed = await exists(marker) ? managedSchema.parse(JSON.parse(await fs.readFile(marker, 'utf8'))) : {};
-    const roots = new Set(config.tools.map(tool => tool === 'claude' ? '.claude/skills' : '.agents/skills'));
+    const roots = new Set(selected.map(tool => tool === 'claude' ? '.claude/skills' : '.agents/skills'));
     const references = (await fs.readdir(path.join(resources, 'references'))).filter(file => file.endsWith('.md')).sort();
-    const written = [], conflicts = [];
+    const written = [], conflicts = [], unchanged = [];
     for (const root of roots) {
         for (const name of names) {
             const sourceFiles = [
@@ -29,6 +30,7 @@ export async function installSkills(project) {
                     const actual = digest(await fs.readFile(destination));
                     if (actual === expected) {
                         managed[item.destination] = expected;
+                        unchanged.push(item.destination);
                         continue;
                     }
                     if (actual !== managed[item.destination]) {
@@ -43,12 +45,26 @@ export async function installSkills(project) {
         }
     }
     await write(marker, JSON.stringify(managed, null, 2) + '\n');
-    return { tools: config.tools, written, conflicts, hints: {
+    return { tools: selected, written, conflicts, unchanged, hints: {
             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.',
         } };
 }
+export async function updateProject(project) {
+    return installSkills(project, ['codex', 'claude', 'cursor']);
+}
+export function formatUpdate(result) {
+    const lines = [result.conflicts.length ? 'Update needs attention.' : result.tools.length ? 'Skills are up to date.' : 'No agent tools selected.',
+        `  Updated: ${result.written.length} files`, `  Already current: ${result.unchanged.length} files`, `  Modified files preserved: ${result.conflicts.length}`];
+    if (result.conflicts.length) {
+        lines.push('', ...result.conflicts.map(file => `  ! ${file}`), 'Compare these files with the installed package templates and merge the changes you want to keep.');
+    }
+    if (result.tools.length)
+        lines.push('', ...result.tools.map(tool => `  ${tool}: ${result.hints[tool]}`));
+    lines.push('', 'Next: releasekit status');
+    return lines.join('\n');
+}
 export async function initProject(project, options) {
     const file = await project.content('config.yaml');
     if (await exists(file))
@@ -58,6 +74,13 @@ export async function initProject(project, options) {
         config.tools = [...new Set(options.tools)];
     if (options.themes)
         config.visuals.themes = options.themes;
-    await writeYaml(file, configSchema.parse(config));
+    if (options.sourceLocale !== undefined)
+        config.sourceLocale = options.sourceLocale;
+    config.locales = options.locales ?? [config.sourceLocale];
+    configSchema.parse(config);
+    if (!config.locales.includes(config.sourceLocale) || new Set(config.locales).size !== config.locales.length) {
+        throw new Error('Project locales must be unique and include the source locale.');
+    }
+    await writeYaml(file, config);
     return { config: file, ...await installSkills(project) };
 }

package/dist/model.d.ts

@@ -1,5 +1,16 @@
 import { z } from 'zod';
 export declare const segment: z.ZodString;
+export declare const channelName: z.ZodString;
+export declare const channelRefSchema: z.ZodObject<{
+    channel: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strict>;
+export type ReleaseRef = {
+    version: string;
+    channel?: string;
+};
+export type ReleaseId = string | ReleaseRef;
+export declare const releasedAtSchema: z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>;
 export declare const sha: z.ZodString;
 export declare const locale: z.ZodString;
 export declare const theme: z.ZodEnum<{
@@ -66,13 +77,33 @@ export declare const historyStartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     version: z.ZodNull;
 }, z.core.$strict>], "past">;
 export type HistoryStart = z.infer<typeof historyStartSchema>;
+export declare const channelsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    include: z.ZodArray<z.ZodString>;
+    history: z.ZodOptional<z.ZodObject<{
+        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>>;
+}, z.core.$strict>>;
 export declare const configSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     product: z.ZodString;
     sourceLocale: z.ZodString;
     locales: z.ZodArray<z.ZodString>;
-    history: z.ZodObject<{
-        limit: z.ZodNumber;
+    history: z.ZodOptional<z.ZodObject<{
         start: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             ref: z.ZodString;
             sha: z.ZodString;
@@ -89,7 +120,28 @@ export declare const configSchema: z.ZodObject<{
             past: z.ZodLiteral<"skip">;
             version: z.ZodNull;
         }, z.core.$strict>], "past">>;
-    }, z.core.$strict>;
+    }, z.core.$strict>>;
+    channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        include: z.ZodArray<z.ZodString>;
+        history: z.ZodOptional<z.ZodObject<{
+            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>>;
+    }, z.core.$strict>>]>>;
     visuals: z.ZodObject<{
         themes: z.ZodEnum<{
             both: "both";
@@ -146,8 +198,12 @@ export type NoteMeta = z.infer<typeof noteMetaSchema>;
 export declare const releaseSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     version: z.ZodString;
-    releasedAt: z.ZodISODate;
-    previous: z.ZodNullable<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    releasedAt: z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>;
+    previous: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        channel: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>]>>;
     status: z.ZodEnum<{
         draft: "draft";
         ready: "ready";
@@ -316,10 +372,16 @@ export declare const bundleSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     currentVersion: z.ZodString;
     locale: z.ZodString;
+    viewChannel: z.ZodOptional<z.ZodString>;
+    currentChannel: z.ZodOptional<z.ZodString>;
     releases: z.ZodArray<z.ZodObject<{
         version: z.ZodString;
-        releasedAt: z.ZodISODate;
-        previous: z.ZodNullable<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        releasedAt: z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>;
+        previous: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            channel: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>]>>;
         notes: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             category: z.ZodEnum<{

package/dist/model.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 export const segment = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}$/);
+export const channelName = z.string().regex(/^(?!(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$)[a-z][a-z0-9-]{0,62}$/);
+export const channelRefSchema = z.strictObject({ channel: channelName, version: segment });
+export const releasedAtSchema = z.union([z.iso.date(), z.iso.datetime({ offset: true }).regex(/T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/)]);
 export const sha = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/);
 export const locale = z.string().regex(/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/);
 export const theme = z.enum(['dark', 'light']);
@@ -7,10 +10,10 @@ export const assetVariant = z.enum(['dark', 'light', 'shared']);
 const color = z.string().regex(/^#[a-fA-F0-9]{6}$/);
 export const paletteSchema = z.strictObject({
     canvas: color.describe('Uniform illustration background.'),
-    surface: color.describe('Base interface panels and resting rows.'),
-    raised: color.describe('Quiet icon tiles, inset areas, and abstract thumbnail fills.'),
-    primary: color.describe('Main neutral glyphs and feature-defining marks; mid-gray in the default light theme.'),
-    secondary: color.describe('Incidental label bars and supporting schematic details.'),
+    surface: color.describe('Base or recessed interface panels.'),
+    raised: color.describe('Foreground panels, controls, and quiet tile fills.'),
+    primary: color.describe('Main neutral glyphs, focal controls, and feature-defining marks; mid-gray in the default light theme.'),
+    secondary: color.describe('Supporting glyphs, incidental label bars, and abstract content.'),
     divider: color.describe('Thin separators and necessary surface boundaries.'),
 });
 export const visualPolicySchema = z.strictObject({
@@ -27,10 +30,25 @@ export const historyStartSchema = z.discriminatedUnion('past', [
     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() }),
 ]);
+const historySettings = z.strictObject({ start: historyStartSchema.optional() });
+export const channelsSchema = z.record(channelName, z.strictObject({
+    include: z.array(channelName).min(1), history: historySettings.optional(),
+})).superRefine((channels, ctx) => {
+    if (!Object.keys(channels).length)
+        ctx.addIssue({ code: 'custom', message: 'Use channels: false to disable channels.' });
+    for (const [name, settings] of Object.entries(channels)) {
+        if (new Set(settings.include).size !== settings.include.length)
+            ctx.addIssue({ code: 'custom', path: [name, 'include'], message: 'Included channels must be unique.' });
+        for (const included of settings.include)
+            if (!Object.hasOwn(channels, included))
+                ctx.addIssue({ code: 'custom', path: [name, 'include'], message: `Unknown included channel: ${included}` });
+    }
+});
 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), start: historyStartSchema.optional() }),
+    history: historySettings.optional(),
+    channels: z.union([z.literal(false), channelsSchema]).optional(),
     visuals: visualPolicySchema,
     tools: z.array(z.enum(['codex', 'claude', 'cursor'])),
 });
@@ -43,12 +61,16 @@ export const noteMetaSchema = z.strictObject({
     commits: z.array(sha), paths: z.array(z.string()), image: z.boolean(),
 });
 export const releaseSchema = z.strictObject({
-    schemaVersion: z.literal(1), version: segment, releasedAt: z.iso.date(),
-    previous: segment.nullable(), status: z.enum(['draft', 'ready']),
+    schemaVersion: z.literal(1), version: segment, channel: channelName.optional(), releasedAt: releasedAtSchema,
+    previous: z.union([segment, channelRefSchema]).nullable(), status: z.enum(['draft', 'ready']),
     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(),
+}).superRefine((release, ctx) => {
+    if (release.previous !== null && (release.channel === undefined ? typeof release.previous !== 'string' : typeof release.previous === 'string')) {
+        ctx.addIssue({ code: 'custom', path: ['previous'], message: 'Channel releases require a channel/version predecessor; unchanneled releases require a version string.' });
+    }
 });
 export const noteTextSchema = z.strictObject({
     title: z.string().min(1), alt: z.string(), sourceHash: z.string().nullable(),
@@ -80,8 +102,9 @@ const exportedImage = z.strictObject({
 });
 export const bundleSchema = z.strictObject({
     schemaVersion: z.literal(1), currentVersion: segment, locale,
+    viewChannel: channelName.optional(), currentChannel: channelName.optional(),
     releases: z.array(z.strictObject({
-        version: segment, releasedAt: z.iso.date(), previous: segment.nullable(),
+        version: segment, channel: channelName.optional(), releasedAt: releasedAtSchema, previous: z.union([segment, channelRefSchema]).nullable(),
         notes: z.array(z.strictObject({
             id: segment, category: noteMetaSchema.shape.category, title: z.string(), bodyMarkdown: z.string(),
             image: z.strictObject({
@@ -119,7 +142,7 @@ export function activeVariants(visual, policy) {
 export function defaultConfig(product) {
     return {
         schemaVersion: 1, product, sourceLocale: 'en-US', locales: ['en-US'],
-        history: { limit: 3 }, tools: ['codex', 'claude', 'cursor'],
+        tools: ['codex', 'claude', 'cursor'],
         visuals: {
             themes: 'both', preset: 'quiet-product', width: 1280, height: 800, accent: '#4678ED',
             dark: { canvas: '#242527', surface: '#18191B', raised: '#343638', primary: '#B9BBBE', secondary: '#777B80', divider: '#46494D' },

package/dist/move.d.ts

@@ -0,0 +1,24 @@
+import { Project } from './project.js';
+import { type ReleaseRef } from './model.js';
+export interface MoveOptions {
+    fromChannel?: string;
+    toChannel?: string;
+    toUnchanneled?: boolean;
+    after?: string;
+    atStart?: boolean;
+    dryRun?: boolean;
+}
+export declare function moveReleases(project: Project, versions: string[], options: MoveOptions): Promise<{
+    dryRun: boolean;
+    moved: {
+        from: ReleaseRef;
+        to: ReleaseRef;
+        status: "draft" | "ready";
+    }[];
+    updatedReleases: ReleaseRef[];
+    updatedFiles: string[];
+    paths: {
+        from: string;
+        to: string;
+    }[];
+}>;

package/dist/move.js

@@ -0,0 +1,292 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { stringify } from 'yaml';
+import { Project, linearHistory } from './project.js';
+import { visualSchema } from './model.js';
+import { ref, refKey, parseRef, link } from './refs.js';
+import { canonical, digest, exists, parseYaml, readNote, within, write } from './files.js';
+import { validate } from './validate.js';
+import { imagePrompt, sceneHash } from './prompts.js';
+const inside = (root, file) => {
+    const relative = path.relative(root, file);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+};
+function yamlBytes(value, original) {
+    const text = stringify(value, { lineWidth: 100 });
+    return Buffer.from(original.includes(Buffer.from('\r\n')) ? text.replace(/\n/g, '\r\n') : text);
+}
+function historySettings(config, channel) {
+    if (channel === undefined)
+        return config.history ??= {};
+    if (!config.channels || !config.channels[channel])
+        throw new Error(`Unknown channel: ${channel}`);
+    return config.channels[channel].history ??= {};
+}
+export async function moveReleases(project, versions, options) {
+    if ((options.toChannel !== undefined) === !!options.toUnchanneled)
+        throw new Error('Specify exactly one of --to-channel or --to-unchanneled.');
+    if (!versions.length || new Set(versions).size !== versions.length)
+        throw new Error('Choose one or more unique release versions.');
+    if (options.after !== undefined && options.atStart)
+        throw new Error('--after and --at-start cannot be combined.');
+    if (options.fromChannel !== undefined)
+        await project.requireChannel(options.fromChannel);
+    if (options.toChannel !== undefined)
+        await project.requireChannel(options.toChannel);
+    const destinationChannel = options.toChannel;
+    if (options.fromChannel === destinationChannel)
+        throw new Error('The source and destination are the same.');
+    const crossing = (options.fromChannel === undefined) !== (destinationChannel === undefined);
+    if (!crossing && (options.after !== undefined || options.atStart))
+        throw new Error('Channel-to-channel moves preserve position; insertion options only apply when crossing histories.');
+    const config = await project.config();
+    const updatedConfig = structuredClone(config);
+    const all = await Promise.all((await project.allRefs()).map(r => project.release(r)));
+    const entries = all.map(r => ({ before: r, after: structuredClone(r) }));
+    const byOldKey = new Map(entries.map(e => [refKey(e.before), e]));
+    const selected = versions.map(version => {
+        const identity = ref({ channel: options.fromChannel, version });
+        const entry = byOldKey.get(refKey(identity));
+        if (!entry)
+            throw new Error(`Missing release: ${refKey(identity)}`);
+        return entry;
+    });
+    const selectedKeys = new Set(selected.map(e => refKey(e.before)));
+    const channelChain = linearHistory(all.filter(r => r.channel !== undefined));
+    // Existing unchanneled projects may have multiple lines; a crossing move requires one unambiguous line.
+    const singleChain = crossing ? linearHistory(all.filter(r => r.channel === undefined)) : [];
+    const sourceChain = options.fromChannel === undefined ? singleChain : channelChain;
+    const ordered = sourceChain.filter(r => selectedKeys.has(refKey(r))).reverse();
+    const relocations = [];
+    for (const entry of selected) {
+        const destination = ref({ version: entry.before.version, channel: destinationChannel });
+        const from = await project.releaseDir(entry.before);
+        const to = await project.releaseDir(destination);
+        if (entries.some(e => refKey(e.before).toLowerCase() === refKey(destination).toLowerCase()))
+            throw new Error(`Destination already exists: ${refKey(destination)}`);
+        if (await exists(to))
+            throw new Error(`Destination already exists: ${refKey(destination)}`);
+        for (const other of entries) {
+            if (other === entry)
+                continue;
+            const directory = await project.releaseDir(other.before);
+            if (inside(from, directory) || inside(directory, from) || inside(to, directory) || inside(directory, to)) {
+                throw new Error('Release directories overlap; resolve the directory collision before moving.');
+            }
+        }
+        for (const prior of relocations)
+            if (inside(prior.to, to) || inside(to, prior.to))
+                throw new Error('Move destinations overlap.');
+        delete entry.after.channel;
+        Object.assign(entry.after, destination);
+        relocations.push({ from, realFrom: await fs.realpath(from), to, identity: ref(entry.before), destination });
+    }
+    const relink = (chain) => {
+        // chain is oldest first and refers to original identities.
+        for (const [index, old] of chain.entries()) {
+            byOldKey.get(refKey(old)).after.previous = link(index ? byOldKey.get(refKey(chain[index - 1])).after : undefined);
+        }
+    };
+    if (!crossing) {
+        relink([...channelChain].reverse());
+    }
+    else {
+        const targetChain = [...(destinationChannel === undefined ? singleChain : channelChain)].reverse();
+        let insertion = targetChain.length;
+        if (options.atStart)
+            insertion = 0;
+        if (options.after !== undefined) {
+            const after = parseRef(options.after);
+            const index = targetChain.findIndex(r => refKey(r) === refKey(after));
+            if (index < 0)
+                throw new Error(`Insertion point is not in the target history: ${options.after}`);
+            insertion = index + 1;
+        }
+        targetChain.splice(insertion, 0, ...ordered);
+        relink([...sourceChain].reverse().filter(r => !selectedKeys.has(refKey(r))));
+        relink(targetChain);
+    }
+    linearHistory(entries.filter(e => e.after.channel !== undefined).map(e => e.after));
+    if (crossing)
+        linearHistory(entries.filter(e => e.after.channel === undefined).map(e => e.after));
+    const sourceSettings = options.fromChannel === undefined ? config.history : (config.channels ? config.channels[options.fromChannel]?.history : undefined);
+    if (sourceSettings?.start && sourceSettings.start.past !== 'skip' && versions.includes(sourceSettings.start.version)) {
+        const targetSettings = historySettings(updatedConfig, destinationChannel);
+        if (targetSettings.start)
+            throw new Error('The destination already has a history start; resolve the settings conflict first.');
+        targetSettings.start = structuredClone(sourceSettings.start);
+        delete historySettings(updatedConfig, options.fromChannel).start;
+    }
+    const relocated = (file) => {
+        const relocation = relocations.find(r => inside(r.from, file));
+        return relocation ? path.join(relocation.to, path.relative(relocation.from, file)) : file;
+    };
+    const originals = new Map();
+    const writes = new Map();
+    const setWrite = async (file, contents) => {
+        const original = await fs.readFile(file);
+        if (!original.equals(contents)) {
+            originals.set(file, original);
+            writes.set(file, contents);
+        }
+    };
+    const visuals = new Map();
+    const affected = new Set(entries.filter(e => canonical(e.before) !== canonical(e.after)));
+    for (const entry of entries) {
+        const directory = await project.releaseFile(entry.before, 'visuals');
+        if (!(await exists(directory)))
+            continue;
+        for (const fileName of await fs.readdir(directory)) {
+            if (!fileName.endsWith('.yaml'))
+                continue;
+            const file = await project.releaseFile(entry.before, `visuals/${fileName}`);
+            const original = await fs.readFile(file);
+            const raw = parseYaml(original.toString());
+            const references = raw?.scene?.references;
+            if (!Array.isArray(references) || !references.every(r => typeof r === 'string'))
+                throw new Error(`Invalid visual references: ${file}`);
+            const replacements = [];
+            for (const reference of references) {
+                const absolute = await within(project.root, reference);
+                const real = await exists(absolute) ? await fs.realpath(absolute) : absolute;
+                const relocation = relocations.find(r => inside(r.realFrom, real));
+                const next = relocation ? path.join(relocation.to, path.relative(relocation.realFrom, real)) : relocated(absolute);
+                replacements.push(next === absolute ? reference : path.relative(project.root, next).split(path.sep).join('/'));
+            }
+            if (canonical(references) === canonical(replacements))
+                continue;
+            const oldVisual = visualSchema.safeParse(raw);
+            raw.scene.references = replacements;
+            const parsed = visualSchema.safeParse(raw);
+            if (oldVisual.success && parsed.success) {
+                for (const variant of ['dark', 'light', 'shared']) {
+                    const asset = raw.variants?.[variant];
+                    if (asset && asset.sceneHash === sceneHash(oldVisual.data.scene, entry.before.visuals, variant)) {
+                        asset.sceneHash = sceneHash(parsed.data.scene, entry.after.visuals, variant);
+                    }
+                }
+                for (const theme of ['dark', 'light']) {
+                    const prompt = await project.releaseFile(entry.before, `prompts/${fileName.slice(0, -5)}.${theme}.md`);
+                    if (await exists(prompt) && parsed.data.scene.source !== 'provided' && !['object-detail', 'editorial-scene'].includes(parsed.data.scene.archetype)) {
+                        const bytes = await fs.readFile(prompt);
+                        let generated = imagePrompt(parsed.data.scene, entry.after.visuals, theme);
+                        if (bytes.includes(Buffer.from('\r\n')))
+                            generated = generated.replace(/\n/g, '\r\n');
+                        await setWrite(prompt, Buffer.from(generated));
+                    }
+                }
+            }
+            visuals.set(file, raw);
+            await setWrite(file, yamlBytes(raw, original));
+            affected.add(entry);
+        }
+    }
+    for (const entry of affected) {
+        if (entry.before.status === 'ready') {
+            const checked = await validate(project, entry.before);
+            if (!checked.valid)
+                throw new Error(`Cannot move changed ready content ${refKey(entry.before)}: ${checked.errors.join('\n')}`);
+            const { status: _status, contentHash: _hash, ...metadata } = entry.after;
+            const parts = [metadata];
+            for (const note of entry.after.notes) {
+                for (const locale of entry.after.locales)
+                    parts.push(await readNote(await project.releaseFile(entry.before, `notes/${note.id}/${locale}.md`)));
+                if (note.image) {
+                    const file = await project.releaseFile(entry.before, `visuals/${note.id}.yaml`);
+                    parts.push(visualSchema.parse(visuals.get(file) ?? parseYaml(await fs.readFile(file, 'utf8'))));
+                }
+            }
+            entry.after.contentHash = digest(canonical(parts));
+        }
+        else {
+            entry.after.contentHash = null;
+        }
+        const file = await project.releaseFile(entry.before, 'release.yaml');
+        await setWrite(file, yamlBytes(entry.after, await fs.readFile(file)));
+    }
+    if (canonical(config) !== canonical(updatedConfig)) {
+        const file = await project.content('config.yaml');
+        await setWrite(file, yamlBytes(updatedConfig, await fs.readFile(file)));
+    }
+    const result = {
+        dryRun: !!options.dryRun,
+        moved: selected.map(e => ({ from: ref(e.before), to: ref(e.after), status: e.after.status })),
+        updatedReleases: [...affected].map(e => ref(e.after)),
+        updatedFiles: [...writes.keys()].map(file => path.relative(project.root, relocated(file)).split(path.sep).join('/')),
+        paths: relocations.map(r => ({ from: r.from, to: r.to })),
+    };
+    if (options.dryRun)
+        return result;
+    // Detect edits made during preflight before any mutation.
+    for (const [file, original] of originals)
+        if (!(await fs.readFile(file)).equals(original))
+            throw new Error(`File changed during move preparation: ${file}`);
+    const holding = await fs.mkdtemp(await project.content('.move-'));
+    const locations = relocations.map(r => r.from);
+    const written = [];
+    const createdParents = [];
+    const recoveryFiles = [];
+    const clearHolding = async () => {
+        for (const file of recoveryFiles)
+            await fs.rm(file, { force: true });
+        await fs.rmdir(holding);
+    };
+    try {
+        // Durable originals and path mapping remain available if rollback itself fails.
+        const backups = [];
+        for (const [file, original] of originals) {
+            const backup = path.join(holding, `original-${backups.length}`);
+            recoveryFiles.push(backup);
+            await fs.writeFile(backup, original, { flag: 'wx' });
+            backups.push({ from: file, to: relocated(file), backup });
+        }
+        const manifest = path.join(holding, 'recovery.json');
+        recoveryFiles.push(manifest);
+        await fs.writeFile(manifest, JSON.stringify({ backups, relocations: relocations.map((r, index) => ({ from: r.from, to: r.to, holding: path.join(holding, String(index)) })) }, null, 2), { flag: 'wx' });
+        for (const [index, relocation] of relocations.entries()) {
+            const temporary = path.join(holding, String(index));
+            await fs.rename(relocation.from, temporary);
+            locations[index] = temporary;
+        }
+        for (const [index, relocation] of relocations.entries()) {
+            const parent = path.dirname(relocation.to);
+            if (!(await exists(parent))) {
+                await fs.mkdir(parent, { recursive: true });
+                createdParents.push(parent);
+            }
+            if (await exists(relocation.to))
+                throw new Error(`Destination appeared during move: ${relocation.to}`);
+            await fs.rename(locations[index], relocation.to);
+            locations[index] = relocation.to;
+        }
+        for (const [file, contents] of writes) {
+            // Include the attempted file so even an error after replacement is recoverable.
+            written.push(file);
+            await write(relocated(file), contents);
+        }
+    }
+    catch (error) {
+        try {
+            for (const file of written.reverse())
+                await fs.writeFile(relocated(file), originals.get(file));
+            for (let index = relocations.length - 1; index >= 0; index--) {
+                if (locations[index] !== relocations[index].from)
+                    await fs.rename(locations[index], relocations[index].from);
+            }
+            for (const directory of createdParents.reverse())
+                await fs.rmdir(directory);
+            await clearHolding();
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `Move failed and rollback needs recovery. Preserved holding directory: ${holding}`);
+        }
+        throw error;
+    }
+    await clearHolding();
+    // Only remove now-empty channel containers. Never recursively remove a source path.
+    for (const directory of new Set(relocations.filter(r => r.identity.channel !== undefined).map(r => path.dirname(r.from)))) {
+        if (await exists(directory) && !(await fs.readdir(directory)).length)
+            await fs.rmdir(directory);
+    }
+    return result;
+}