@iodes/releasekit 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 SO, HYEONSEOP
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 SO, HYEONSEOP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,292 @@
-# ReleaseKit
-
-Git-based visual release notes, written with your coding agent and stored with your product.
-
-ReleaseKit provides a deterministic CLI, portable agent skills, an original visual language, and versioned content files. Your agent writes the copy and uses its available image tools. The CLI prepares Git evidence, compiles image prompts, validates artifacts, and exports JSON with local assets.
-
-## Project image policy
-
-Dark **and** light illustrations are recommended by default. Choose one theme when generation cost matters more than providing a dedicated variant for both viewer themes:
-
-```yaml
-# releasekit/config.yaml
-visuals:
-  themes: both # both | dark | light
-```
-
-This edits one field in the complete generated config; keep the other visual settings. You can also select the policy at setup with `releasekit init --themes light`.
-
-One scene brief drives both variants. Object positions, scale, crop, interaction state, and semantic colors stay consistent while presentation surfaces and lighting adapt. Single-theme exports contain one real asset and an explicit fallback, without inventing a second variant. Images are shared across locales.
-
-`releasekit image plan <version>` reports pending and reusable asset counts before any image generation. It never calls a model API. Previously imported current assets are reused. If image generation is unavailable, the prompts remain available for an external tool.
-
-## Local setup
-
-Requires Git and Node.js 22.12 or later. Node.js 24 is recommended for development.
-
-```sh
-npm install
-npm run build
-npm pack
-npm install -g ./iodes-releasekit-0.1.0.tgz
-```
-
-The package can be built and installed locally; no public registry publication is required. In the product's Git repository:
-
-```sh
-releasekit init --tools codex,claude,cursor --themes both
-```
-
-Codex and Cursor share a single project skill tree to avoid duplicate discovery. Claude Code receives its project skill tree. Installation prints invocation hints. `releasekit update` refreshes owned files, preserves user edits, and reports conflicts.
-
-## Agent workflow
-
-Ask your agent to use `releasekit-draft` to create notes between two tags or commits. Include the desired release version. For example:
-
-> Prepare release 1.4.0 from v1.3.0 to v1.4.0. Write Korean and English notes, create the configured image variants, and export the latest three releases.
-
-The installed skills are `releasekit-draft`, `releasekit-image`, `releasekit-translate`, and `releasekit-review`. They use the CLI rather than implementing Git parsing or asset bookkeeping again.
-
-```sh
-releasekit prepare 1.4.0 --from v1.3.0 --to v1.4.0 --previous 1.3.0
-releasekit note add 1.4.0 queue-action
-# Fill the note files, evidence references, and shared visual brief.
-releasekit image plan 1.4.0
-# Generate externally or through the agent's image tool, then select the files.
-releasekit image import 1.4.0 queue-action --theme dark --file ./selected-dark.png
-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
-releasekit validate 1.4.0
-releasekit finalize 1.4.0
-releasekit export --current 1.4.0 --limit 3 --locale ko-KR --out ./release-output
-```
-
-Use `--from-root` for an explicitly requested full-history first release. `--to` defaults to `HEAD`, and `--previous` can supply the default comparison start. Existing drafts are edited in place; `prepare` does not overwrite them. `--json` provides structured results, and `--cwd` selects a project working directory.
-
-There is no built-in model API, viewer, hosted database, automatic Git commit, or publishing step.
-
-## Visual guidance
-
-The built-in guidance goes beyond a style adjective. It includes eight composition recipes, feature-to-image selection, a scene contract, semantic palette roles, theme-pair invariants, text rules, cost-aware reuse, external generation handoff, and visual acceptance checks.
-
-For each note, the agent derives the visual message from its evidence, selects the appropriate archetype, and writes feature-specific relationships and correctness constraints. The CLI combines that scene with common presentation rules, only the selected recipe, and the requested theme. Review first checks what the image claims, then visual clarity, then theme correspondence. Worked examples do not set the layout for other notes.
-
-- [Visual language](kit/references/visual-language.md)
-- [Composition recipes](kit/references/composition-recipes.md)
-- [Theme pairs and cost](kit/references/theme-pairing.md)
-- [Writing and translation](kit/references/writing.md)
-- [Original dark/light example and three-version bundles](examples/README.md)
-
-All shipped guidance uses independent, brand-neutral descriptions. Product-specific imagery should depict the user's actual feature. Reference-company identities, attributed style labels, copied artwork, and unrelated product silhouettes do not belong in briefs or generated output.
-
-## Version and file contract
-
-Each release stores its own changes and an explicit `previous` release link. Export follows that chain, keeping the current version and the configured number of preceding versions in separate groups. The default count is three including current. Version strings are not sorted to infer ancestry, and similar notes in separate versions are retained.
-
-Content uses YAML metadata, Markdown locale files, image briefs and prompts, and local raster assets. Git boundaries are pinned to immutable commits. Notes carry evidence, and translations carry source fingerprints. A ready release has a content fingerprint so later edits are detected.
-
-Project visual defaults are captured when a release is prepared. To apply changed project settings to an existing draft:
-
-```sh
-releasekit image plan 1.4.0 --sync-config
-```
-
-This preserves selected files and schedules only the newly required or stale variants. Ready content must first be reopened with `status: draft` and `contentHash: null`.
-
-See [the file contract](kit/references/format.md) and the generated [JSON schemas](schemas). Export contains display data and relative assets, excluding Git evidence, prompts, and private source paths. Consumers select `image.variants[theme]` or `image.variants[image.fallbackTheme]` and safely render `bodyMarkdown`.
-
-## Development checks
-
-```sh
-npm run check
-npm test
-npm run build
-npm pack --dry-run
-```
-
-Tests cover pinned Git ranges, reverted changes, branched release history, theme scheduling, asset integrity, single-theme fallback, stale translations, finalized content edits, installation conflicts, and command-line behavior. CI runs on Windows and Linux with Node.js 22 and 24.
-
-MIT licensed.
+<div align="center">
+
+<h1>ReleaseKit</h1>
+
+<p><strong>Turn Git changes into visual release notes.</strong></p>
+<p>Written with your coding agent. Versioned with your product.</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/@iodes/releasekit"><img src="https://img.shields.io/npm/v/@iodes/releasekit?color=4678ED" alt="npm version"></a>
+  <a href="https://github.com/iodes/ReleaseKit/actions/workflows/check.yml"><img src="https://github.com/iodes/ReleaseKit/actions/workflows/check.yml/badge.svg" alt="Check workflow status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-4678ED" alt="License: MIT"></a>
+</p>
+
+<p>
+  <a href="#quick-start">Quick start</a> &middot;
+  <a href="#workflow">Workflow</a> &middot;
+  <a href="examples/README.md">Examples</a> &middot;
+  <a href="#documentation">Documentation</a>
+</p>
+
+</div>
+
+ReleaseKit pairs a deterministic CLI with portable agent skills. Your agent writes the notes and selects or creates images; the CLI collects Git evidence, prepares image requests, validates content, and exports JSON with local assets.
+
+| Dark | Light |
+| :---: | :---: |
+| ![A blue queue action revealed behind a list row on a charcoal canvas](examples/queue-action/dark.png) | ![The same queue action and list geometry on a light canvas](examples/queue-action/light.png) |
+
+*One scene brief, two theme variants. Fictional feature illustrations. [Browse the composition gallery →](examples/README.md#composition-gallery)*
+
+## Why ReleaseKit?
+
+- **Grounded in Git.** Draft from tags or commits, pin the evidence, and keep each release's changes together.
+- **Works with your agent.** Use portable skills for Codex, Claude Code, and Cursor, plus the image tools already available to you.
+- **Visuals for your feature.** Generate flat explanations in dark and light, or reuse an approved screenshot, photo, or content image across both viewer themes.
+- **Content you own.** Keep Markdown, translations, and images in your repository. Export JSON and local assets for your product to display.
+
+## Quick start
+
+Requires **Git** and **Node.js 22.12+**.
+
+### 1. Install
+
+```sh
+npm install -g @iodes/releasekit
+```
+
+### 2. Set up your product
+
+Run inside your product's Git repository:
+
+```sh
+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.
+
+### 3. Ask your agent
+
+Start with the installed `releasekit-draft` skill. Example conversation with 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.
+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.
+
+You: Use ./approved-capture.png for the product-detail note.
+AI:  ✓ Reviewed and imported it once for both viewer themes
+
+You: Review and finalize 1.4.0, then export up to three releases
+     in English to ./release-output.
+AI:  ✓ Validated notes, translations, and images
+     ✓ Marked release 1.4.0 ready
+     Exported release-output/
+     ├── release-notes.json   ← Notes grouped by release
+     └── assets/             ← Theme variants and shared supplied images
+```
+
+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.
+
+## Workflow
+
+```text
+Git range → Release draft → Notes + images + translations → Validate → 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. |
+
+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.
+
+<details>
+<summary><strong>Step-by-step CLI workflow</strong></summary>
+
+Replace the sample version, Git refs, and note ID with your own. If release `1.3.0` already exists in ReleaseKit, add `--previous 1.3.0` to link its history.
+
+```sh
+releasekit prepare 1.4.0 --from v1.3.0 --to v1.4.0
+releasekit note add 1.4.0 queue-action
+
+# Fill the notes, evidence references, and visual brief.
+# Choose an archetype and set scene.source to generated for this example.
+releasekit image plan 1.4.0
+
+# Generate and review the dark image with your agent or an external tool.
+releasekit image import 1.4.0 queue-action --theme dark --file ./selected-dark.png
+
+# Plan again to use the accepted dark image as a composition reference.
+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
+releasekit validate 1.4.0
+releasekit finalize 1.4.0
+releasekit export --current 1.4.0 --limit 3 --locale ko-KR --out ./release-output
+```
+
+- Use `--from-root` for an explicitly requested full-history first release.
+- `--to` defaults to `HEAD`; `--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.
+- Export to a new directory; an existing destination is never overwritten.
+
+See the [agent workflow](kit/references/workflow.md) for ancestry rules and continuing existing releases.
+
+</details>
+
+<details>
+<summary><strong>Updating installed skills</strong></summary>
+
+After installing a newer package version, run `releasekit update` in your product repository. It refreshes managed files, preserves user edits, and reports conflicts.
+
+Codex and Cursor share `.agents/skills` to avoid duplicate discovery. Claude Code uses `.claude/skills`.
+
+</details>
+
+## Image themes
+
+**Generated graphics default to dark and light.** Paired variants share one scene brief, preserving geometry, feature meaning, and semantic colors while presentation surfaces adapt. Images are shared across locales.
+
+Choose `scene.source` in each note's visual brief before planning:
+
+| Source | Use for | Theme handling |
+| --- | --- | --- |
+| `generated` | Flat glyphs, interface explanations, diagrams, and data graphics supported by the feature. | Separate images for the configured dark/light themes. |
+| `provided` | Approved screenshots, photographs, or content artwork. Required for `object-detail` and `editorial-scene`. | One unchanged `shared` asset, or distinct genuine theme captures. |
+
+Choose a single theme during setup with `--themes dark` or `--themes light`, or edit this field in the generated configuration while keeping the other visual settings:
+
+```yaml
+# releasekit/config.yaml
+visuals:
+  themes: both # both | dark | light
+```
+
+`releasekit image plan <version>` reports pending and reusable assets, with separate `generationRequests` and `providedRequests` counts. It reuses current imports and never calls a model API. Single-theme exports contain one real asset and an explicit fallback.
+
+Requests with `action: generate` include a prompt for the agent or an external tool. Requests with `action: provide` have `promptFile: null` and identify the needed source. Missing supplied media stays pending and blocks finalization; the agent can continue independent writing and translation work.
+
+<details>
+<summary><strong>Importing one supplied image for both themes</strong></summary>
+
+Complete the note's visual brief with `scene.source: provided`. This example uses the note ID `product-detail`:
+
+```sh
+releasekit image plan 1.4.0
+
+# Once an approved capture or photo is available, inspect it and import.
+releasekit image import 1.4.0 product-detail --theme shared --file ./approved-capture.png
+```
+
+The CLI keeps the original bytes, dimensions, and colors. One `shared` asset serves both viewer themes without generating or duplicating another file.
+
+If genuine dark/light captures exist, import them with `--theme dark` and `--theme light` instead. A note must use either `shared` or themed entries; remove the previous variant entries when switching. A missing configured capture remains a supplied-image request.
+
+Follow the current image plan even if older prompt files remain. See the [supplied-media example](examples/provided-media/README.md) and [media source guide](kit/references/media-sources.md) for pending inputs and older briefs.
+
+</details>
+
+<details>
+<summary><strong>Applying changed settings to an existing draft</strong></summary>
+
+Releases capture the project's visual settings when prepared. To apply updated defaults:
+
+```sh
+releasekit image plan 1.4.0 --sync-config
+```
+
+This preserves selected files and schedules only newly required or stale variants. Reopen ready content first by setting `status: draft` and `contentHash: null` in its `release.yaml`.
+
+</details>
+
+## Content and export
+
+Everything lives alongside your product:
+
+```text
+releasekit/
+├── config.yaml
+└── 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
+```
+
+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`.
+
+`fallbackTheme` can be `dark`, `light`, or `shared`. A shared-image export contains one `image.variants.shared` entry with `fallbackTheme: shared`; the same consumer lookup displays it in either viewer theme. Preserve the supplied image's original appearance when displaying it.
+
+Translations track source fingerprints, and finalized releases record content fingerprints to detect later edits. See the [file contract](kit/references/format.md) and [JSON schemas](schemas) for the full structure.
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Agent workflow](kit/references/workflow.md) | Git boundaries, drafts, review, 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. |
+| [Composition recipes](kit/references/composition-recipes.md) | Eight presentation categories matched to the feature and its source. |
+| [Theme pairs and cost](kit/references/theme-pairing.md) | Shared geometry, single-theme policies, and reuse. |
+| [File contract](kit/references/format.md) · [JSON schemas](schemas) | Authoring files and the public export format. |
+| [Worked examples](examples/README.md) | Paired illustrations, supplied-image workflow, independent briefs, and three-release bundles. |
+
+Visual guidance uses independent, brand-neutral descriptions. Each illustration should communicate the actual feature through its own scene. Worked examples demonstrate the process; each note gets its own composition.
+
+The built-in guidance covers source selection, a scene contract, semantic palette roles, theme-pair invariants, text rules, cost-aware reuse, and visual acceptance checks. Generated icons are compact flat monochrome glyphs. Physical details and content previews use supplied images rather than invented 3D objects or decorative scenes.
+
+## Development
+
+Use **Node.js 24** for development. From a local checkout:
+
+```sh
+npm ci
+npm run check
+npm test
+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.
+
+<details>
+<summary><strong>Install from a local checkout</strong></summary>
+
+```sh
+npm pack
+npm install -g ./iodes-releasekit-0.1.0.tgz
+```
+
+Use the tarball filename printed by `npm pack` if the package version differs. Packing builds the package automatically.
+
+</details>
+
+<details>
+<summary><strong>Publishing this package</strong></summary>
+
+The [Publish workflow](.github/workflows/publish.yml) runs manually on a `release/x.y.z` branch. The branch selects the major/minor release line and starting patch; all three components must be numeric with no leading zeros.
+
+Once the workflow exists on the default and release branches, open **Actions → Publish → Run workflow** and select the release branch. It pins the selected commit and calculates the next available patch from both Git tags and npm versions. For `release/0.1.0`, publishing starts at `0.1.0` if unused, then advances past the highest existing patch to `0.1.1`, `0.1.2`, and so on. A newer major/minor line blocks older lines, and registry errors stop the workflow.
+
+The runner restores dependencies and updates the package and lockfile with `npm version --no-git-tag-version`; no version-bump commit is needed. The CLI reads that package version for `--version`. After checks, tests, build, and package preview pass, the workflow creates a new tag and publishes through the npm trusted publisher configured for `publish.yml`.
+
+Existing tags are never moved. Every run calculates a fresh version, even for the same commit. If an earlier attempt already created a tag or published a package, rerunning advances to the next patch. Tag pushes do not start publishing.
+
+</details>
+
+## License
+
+[MIT](LICENSE) © 2026 SO, HYEONSEOP.

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
 import { Project, prepare } from './project.js';
 import { initProject, installSkills } from './install.js';
@@ -7,9 +8,10 @@ import { addNote, markTranslation, syncImagePolicy } from './content.js';
 import { planImages, importImage } from './images.js';
 import { validate, finalize } from './validate.js';
 import { exportBundle } from './export.js';
-import { configSchema, noteMetaSchema, theme } from './model.js';
+import { configSchema, noteMetaSchema, assetVariant } from './model.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
-program.name('releasekit').description('Git-based visual release content and agent skills').version('0.1.0')
+program.name('releasekit').description('Git-based visual release content and agent skills').version(version)
     .option('--cwd <directory>', 'project working directory', process.cwd())
     .option('--json', 'print machine-readable results');
 const project = () => Project.find(path.resolve(program.opts().cwd));
@@ -44,7 +46,7 @@ note.command('add <version> <id>').description('Scaffold a note and its locale f
     emit({ version, note: id, status: 'draft' });
 });
 const images = program.command('image').description('Plan themed illustrations and register selected files');
-images.command('plan <version>').description('Write pending prompts and report asset counts without calling a model')
+images.command('plan <version>').description('Plan generation or supplied-image requests without calling a model')
     .option('--sync-config', 'apply current project image settings to this draft')
     .action(async (version, options) => {
     const instance = project();
@@ -53,9 +55,9 @@ images.command('plan <version>').description('Write pending prompts and report a
     emit(await planImages(instance, version));
 });
 images.command('import <version> <note>').description('Import a selected raster variant')
-    .addOption(new Option('--theme <theme>', 'variant to register').choices(['dark', 'light']).makeOptionMandatory())
+    .addOption(new Option('--theme <theme>', 'variant to register; shared is for supplied images').choices(['dark', 'light', 'shared']).makeOptionMandatory())
     .requiredOption('--file <file>', 'selected local PNG, JPEG, or WebP')
-    .action(async (version, id, options) => emit(await importImage(project(), version, id, theme.parse(options.theme), path.resolve(program.opts().cwd, options.file))));
+    .action(async (version, id, options) => emit(await importImage(project(), version, id, assetVariant.parse(options.theme), path.resolve(program.opts().cwd, options.file))));
 const translation = program.command('translation').description('Track source freshness for reviewed translations');
 translation.command('mark <version> <note>').description('Mark an already reviewed translation current')
     .requiredOption('--locale <locale>', 'translation language code')

package/dist/content.d.ts

@@ -7,6 +7,7 @@ export declare function readVisual(project: Project, version: string, id: string
     schemaVersion: 1;
     scene: {
         archetype: "data-view" | "device-view" | "editorial-scene" | "icon-tile" | "object-detail" | "spatial-view" | "symbol-pair" | "ui-detail";
+        source?: "generated" | "provided" | undefined;
         subject: string;
         message: string;
         focus: string;
@@ -33,6 +34,13 @@ export declare function readVisual(project: Project, version: string, id: string
             width: number;
             height: number;
         } | undefined;
+        shared?: {
+            file: string;
+            sha256: string;
+            sceneHash: string;
+            width: number;
+            height: number;
+        } | undefined;
     };
 }>;
 export declare function checkReferenceFiles(project: Project, references: string[]): Promise<void>;

package/dist/content.js

@@ -1,5 +1,5 @@
 import * as fs from 'node:fs/promises';
-import { locale, noteMetaSchema, visualSchema } from './model.js';
+import { locale, noteMetaSchema, visualSchema, imageSource } from './model.js';
 import { identifier, writeYaml, writeNote, readNote, noteHash, exists, readYaml } from './files.js';
 import { Project, editable } from './project.js';
 export async function addNote(project, version, id, category, image) {
@@ -16,7 +16,7 @@ export async function addNote(project, version, id, category, image) {
     if (image) {
         await writeYaml(await project.releaseFile(version, `visuals/${id}.yaml`), {
             schemaVersion: 1,
-            scene: { archetype: '', subject: '', message: '', focus: '', composition: '', context: '', elements: [], preserve: [], avoid: [], text: [], references: [] },
+            scene: { archetype: '', source: '', subject: '', message: '', focus: '', composition: '', context: '', elements: [], preserve: [], avoid: [], text: [], references: [] },
             variants: {},
         });
     }
@@ -52,7 +52,9 @@ export async function syncImagePolicy(project, version) {
     await project.save(release);
 }
 export async function readVisual(project, version, id) {
-    return readYaml(await project.releaseFile(version, `visuals/${identifier(id)}.yaml`), visualSchema);
+    const visual = await readYaml(await project.releaseFile(version, `visuals/${identifier(id)}.yaml`), visualSchema);
+    imageSource(visual.scene);
+    return visual;
 }
 export async function checkReferenceFiles(project, references) {
     const { within } = await import('./files.js');

package/dist/export.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { Project } from './project.js';
-import { bundleSchema, themes, locale } from './model.js';
+import { bundleSchema, activeVariants, locale } from './model.js';
 import { validate } from './validate.js';
 import { exists, readNote, write } from './files.js';
 import { readVisual } from './content.js';
@@ -25,8 +25,9 @@ export async function exportBundle(project, current, options) {
             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);
-                exported.image = { alt: text.alt, fallbackTheme: themes(release.visuals)[0], variants: {} };
-                for (const variant of themes(release.visuals)) {
+                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 };

package/dist/images.d.ts

@@ -1,4 +1,4 @@
-import { type Theme, type Visual } from './model.js';
+import { type AssetVariant, type Visual } from './model.js';
 import { Project } from './project.js';
 export declare function inspectImage(bytes: Buffer): Promise<{
     width: number;
@@ -6,13 +6,20 @@ export declare function inspectImage(bytes: Buffer): Promise<{
     extension: string;
     sha256: string;
 }>;
-export interface ImageRequest {
+export type ImageRequest = {
     note: string;
-    theme: Theme;
+    theme: AssetVariant;
     reason: 'missing' | 'stale';
+} & ({
+    action: 'generate';
     promptFile: string;
     compositionReference: string | null;
-}
+} | {
+    action: 'provide';
+    promptFile: null;
+    compositionReference: null;
+    instruction: string;
+});
 export declare function planImages(project: Project, version: string): Promise<{
     version: string;
     configuredThemes: ("dark" | "light")[];
@@ -20,9 +27,11 @@ export declare function planImages(project: Project, version: string): Promise<{
     readyAssets: number;
     pendingAssets: number;
     requests: ImageRequest[];
+    generationRequests: number;
+    providedRequests: number;
     costNote: string;
 }>;
-export declare function importImage(project: Project, version: string, noteId: string, variant: Theme, source: string): Promise<{
+export declare function importImage(project: Project, version: string, noteId: string, variant: AssetVariant, source: string): Promise<{
     file: string;
     sha256: string;
     sceneHash: string;