lightcraft git:20261104.a5ac27dA

Immutable. This exact content never changes and is served at /api/v1/blob/be6e4c1d042b9b24.

---
name: lightcraft
description: >-
  LightCraft is a native photo library and non-destructive raw developer — an open-source, clean-room
  reimplementation of Adobe Lightroom Classic — written in pure Rust (macOS app at
  /Applications/LightCraft.app, plus a separate `lightcraft-cli` and a WebAssembly web build). Trigger
  this skill whenever the user mentions LightCraft, `.lcpreset`, `.lcprint`, a LightCraft library folder
  (`catalog.snap` / `catalog.log`), `lightcraft-cli`, or LightCraft's control/MCP server; asks what it
  can import, develop or export (RAW: DNG/CR2/CR3/ARW/NEF/RAF/RW2/ORF/PEF/SRW/MRW/SR2; export:
  JPEG/PNG/TIFF/WebP/AVIF/JPEG XL/PSD/DNG/original); asks about its menus or keyboard shortcuts; wants
  to automate, script, batch-render or agent-drive it (CLI `run`/`render`/`snapshot`/`merge`/`calibrate`/
  `denoise-serve`, JSON-lines control channel on 127.0.0.1, MCP tools, `print.*`/`slideshow.*`
  commands); wants to prepare inputs, migrate a Lightroom Classic catalog, repair a library folder, fit
  camera colour profiles from raws, or use a lensfun lens database; wants exports, XMP sidecars or camera
  colour verified; or troubleshoots it. Trigger even when the app is not named but the job is
  photo-library or raw-development work — "cull this shoot", "develop this RAW", "apply a preset and
  export JPEGs", "import my Lightroom catalog", "why won't this CR3 open" — and prefer this skill over
  generic Lightroom advice, because LightCraft's formats and gaps differ from Adobe's in ways that matter.
---

**Audit basis.** Refreshed 2026-11-04 against tag **v0.18.0**, commit **`32d569ad5d19a6b55cf8d5c077127faa0f44a83b`** — `git rev-parse HEAD` in the pinned checkout confirms, and the installed `/Applications/LightCraft.app` matches (its binary prints `lightcraft 0.18.0`). The previous release this skill described was v0.17.0 (`5a09d07`).

**v0.17.0 → v0.18.0 delta.** 13 files changed; the command set is unchanged (274 ids). A correctness-only wave: histogram percentile when the target truncates to 0, shutter-fraction validation, case-insensitive date search, `LIGHTCRAFT_GPU_LIMITS` overflow, settings merging with `linkMargins`, and Cmd/Ctrl-click taking a photo out of a survey (`crates/ui-egui`).

**Verify against your installed version** — the ArtCraft Launcher auto-updates, so a newer build may differ; every count quoted here was re-measured at this tag, and code paths that moved were re-cited. The measurement method for each count is in `evidence.md`.

v0.16.0 → v0.18.0 adds **4 commands, zero removed** (multiline non-test extract 375 → 379): **`keyword.setShortcut`, `keyword.shortcut`, `keyword.toggleShortcut`** (keyword keyboard shortcuts) and **`photo.clearLabel`**. The MCP tool set, CLI subcommands (10), control methods, the 9 bundled camera profiles and the 122+10 develop sliders are unchanged (the MCP/control/CLI diffs are doc-strings, an invalid-Unicode argument guard in the CLI, and an internal async `Later` reply in the control server). The wave is a giant **"Integration r3" batch of 178 reviewed PRs** plus an **accessibility pass** (the grid's date header, sliders, icon buttons and dialogs carry accessible names/roles; panels and bars are landmarks and toolbars; the Detail photo is named by file name). Highlights: **Auto Import waits for an import that starts during its listing** (#3409); **Develop exports from a source at least twice the output size** (#3281); **a person's page finds look-alikes in seconds, not minutes** (#3286); the **home folder and Local's built-in places can't be renamed or moved** (#3276); the **remembered crop ratio's box shows on an untouched photo** (#3235); TIFF LZW is documented as usually larger and slower than zip (default stays zip); and a hardening wave rejects EXIF offsets beyond 18 hours (#3242), signed ports in `Url::parse`, signed numbers in Content-Range, and malformed Content-Length.

## Overview

LightCraft is a photo **library** plus a non-destructive **raw developer** — an open-source, clean-room reimplementation of Adobe Lightroom Classic 15.5 / Lightroom 9.6 (`ROADMAP.md:3`, `docs/target-app-parity.md`), written from scratch in pure Rust with no Adobe assets (`README.md`, `AGENTS.md`). Its surfaces are the desktop app (`apps/lightcraft`, eframe + wgpu + native macOS menus, migrated to egui 0.37 with the shared `craft-ui` docking in this release), `lightcraft-cli` (headless render, batch commands, MCP server, headless UI snapshots), and a WebAssembly build of the same UI (`apps/lightcraft-web`).

**Maturity: alpha.** At this tag the generated parity summary reports **83.5% of 543 in-scope rows** (P0 98.3%, P1 94.4%, P2 56.7%, `docs/parity-checklist.md:58`), while `ROADMAP.md:15` and `docs/target-app-parity.md:15` still print **81.6% of 532** — they lag the generated block. The project's readiness estimate is unchanged at **~61%** overall, **~51%** for a mainstream working photographer and **~65%** for an essentials user; beta is an estimated ~340–600 agent-hours away (`ROADMAP.md:3-22`). The gap is quality and coverage — camera colour, render fidelity, some raw variants, AI models — not missing buttons. Source: GitHub `storytold/lightcraft`, MIT OR Apache-2.0 (`Cargo.toml`).

v0.16.0 is a **large community-integration release (~250 merged PRs) with no command-registry change**: the engine still registers **375 command specs**, `UI_COMMANDS` is still **191 + 18 language commands = 209** (584 total), so every count below carried over from v0.15.0. What is new: **hold Space over a tool to pan and click-zoom**; **Alt/Option-drag previews for clipping and sharpening**; **AHD demosaic blends its candidates where noise alone would pick one**; compressed RAF decode is 13–17 % faster; Canon CR3/CR2 preview colour space comes from the maker note and a Canon maker-note lens is read when `LensModel` is missing; **embedded lens corrections for Sony ILCE-6700 and Fujifilm X-S20**, plus lens profiles for compact cameras with built-in lenses; Fujifilm X-Trans III bodies get Kelvin from the RAF's own neutral pair; the per-file camera-colour fit now runs on the vignetting-corrected sensor; **MCP `render`/`screenshot` PNGs go through a private temp folder**; CLI hardening (`--script` accepts a UTF-8 BOM, `render --set` refuses inf/NaN, non-object script parameters are rejected, a script stops after a failed import); a person's People page finds look-alikes in seconds instead of minutes; GPU kernels build on parallel threads and device OOM falls back without stopping the GPU; and a library path or `catalog.snap` given at launch opens that library instead of being ignored.

## Capabilities (verified)

### Library, catalog and views — implemented

- **The library is a folder, not a document.** `catalog.snap` (JSON snapshot) + `catalog.log` (append-only JSON-lines op log: `seq`, CRC-32, fsynced; a torn final record is repaired; a mid-log is preserved as `catalog.log.damaged-<seq>`), plus `presets.json`, `view.json`, `prefs.json`, `thumbs/` and `Originals/` for copy-imported photos (`crates/engine/src/library.rs:1-22`; `crates/catalog/src/journal.rs:1-40`). Default: `LightCraft Library` under the user's `Pictures` folder; `LIGHTCRAFT_LIBRARY` overrides (`crates/engine/src/library.rs:63-70`).
- **Crash-safe and single-writer.** Every top-level command that changes the catalog persists its ops (fsynced) before replying; a failed write keeps the change in memory, reports `unsaved` and retries. One process per library: `catalog.lock` refuses a second writer with "This library is already open in …" (`crates/catalog/src/lock.rs:86`; `crates/ui-egui/src/control.rs` `ui.inspect`). On Windows a hard link to an original now counts as that original.
- **Library model.** Albums in folders, smart albums (rule trees incl. File Path rules; "in the last…" date rules refresh when the session clock crosses a minute), stacks/auto-stack, virtual copies, versions and history, ratings/flags/colour labels + configurable label sets, filter bar with **Enable Filters** (`⌘L`, `library.toggleFilters` sets a filter aside and brings it back), fielded search (including people named on faces), sort, Photo Grid / Square Grid / People, filmstrip, Compare and Survey culling with synced zoom, **Reference view** (⇧R, `photo.setReference`), **Local** folder browsing without import (edits go to XMP sidecars; "Add to My Photos" adopts the photo), Recently Deleted, missing-file relink (matches a library made on Windows by file name), **hold view** (`library.holdView`) and **Assisted Culling** (classical focus score, clipping, burst grouping; no expression/eye detection) (`crates/engine/src/cmd/organize.rs`, `crates/engine/src/cmd/library.rs`, `crates/engine/src/cmd/filters.rs`, `crates/engine/src/cmd/query.rs`, `crates/engine/src/cmd/browse.rs`, `crates/engine/src/cmd/cull.rs`; `docs/parity-checklist.md` rows `LRC-LIB-REFVIEW`, `LR-LIB-CULL`).
- **Choosing a library at launch.** Settings ▸ General ▸ **At launch**: *Open the last library* or *Ask me*; with *Ask me* (or Alt/Option held as the window appears) a window lists recent libraries with name, folder, last-opened time and a background existence check. `app.recentLibraries` returns `{path, name, exists, checking, open, lastOpened}` and `{remove: path}`/`{clear: true}`; `app.newLibrary` makes and opens one (`crates/ui-egui/src/dialogs/settings/libraries.rs` — moved from `panels/settings.rs` in v0.16.0; `docs/control-protocol.md` "Choosing the library at launch").
- **Workspace.** Detail view with Edit / Info / Keywords / History panels, full-screen preview (`F`), Lights Out (`⇧L`), second window (`⌘F11`), Before/After (`Y`, `⇧Y`, `⌥Y`), soft proofing (`S`; partial — see limitations), info overlay (`⌘I`) and View Options (`⌘J`), a loupe layout-image overlay, multi-select Info panel (`view.infoSelectedPhotos` shows the values the selection shares and marks mixed fields), and dockable/splittable panels via `ui.dock` / `ui.dock.reset` — **side panels now dock in columns on craft-ui's shared docking** (`crates/ui-egui/src/menus.rs`; `docs/control-protocol.md` "Methods").
- **Long-running tasks** (imports, exports, merges, downloads, preview builds, the face scan) live in one activity stack, visible to agents as `activity.list` / `activity.cancel`; quitting asks first (`crates/engine/src/cmd/activity.rs`; `docs/background-tasks.md:1-10`; `ui.inspect` → `quitPrompt`).
- **Previews and proxies.** `library.buildPreviews|cancelPreviews|previewProgress` build the disk thumbnail cache; `photo.smartPreview` plus `library.smartPreviews|smartPreviewsLocation` build/relocate smart previews that keep working when originals are offline (`crates/engine/src/cmd/previews.rs`; `docs/camera-preview-colour.md` "smart previews").
- **Faces and focus points.** XMP face names, editable face boxes and the People view work with no model; detection (YuNet) and recognition (SFace/AuraFace) are opt-in model installs run by LightCraft's own pure-Rust CPU interpreter (`crates/engine/src/cmd/face_models.rs`, `crates/engine/src/cmd/face_detect.rs`, `crates/engine/src/cmd/face_recognize.rs`; `docs/faces.md:1-24`). `photo.inspect` carries `meta.focus`; View ▸ Focus Point (⌥F), zoom-to-focus and a background `photo.readFocusPoints` sweep — only Sony `ILCE-1` (α1) and `ILCE-7SM3` (A7S III) at this tag (`docs/focus-points.md:36,66-67`; `crates/engine/src/focus_scan.rs`).

### Import and raw decoding — implemented, with coverage limits

- **Importable extensions are one list of 39** in `crates/engine/src/import/files.rs` (`EXTENSIONS`): `jpg jpeg png tif tiff webp dng cr2 cr3 nef nrw arw sr2 srf raf orf rw2 rwl raw pef srw psd psb jxl gif bmp heic heif avif iiq crw mrw x3f kdc mos erf 3fr fff mef`. Support is decided by **extension** (`is_supported`), then the decoder may still refuse. Modes: **Add** (reference in place), **Copy** (into `Originals/` or a destination, with date/month/flat/folder-template filing and rename templates), **Move** (copy, verify, then remove the source and its sidecars); duplicates are detected by path and by content; copy imports can convert raws to DNG (`crates/engine/src/import.rs`; `crates/engine/src/cmd/library.rs`).
- **Raw decoded from sensor data** (`docs/raw-parity.md`; `crates/raw/src/lib.rs`): DNG (uncompressed, LJ92, lossy/Smart Preview, LinearRaw, Deflate, DNG 1.7 JPEG XL tiles, Apple ProRAW, row/column interleave), CR2, CR3 (lossless CRX Bayer + version 0x100/0x200 C-RAW; R5 Mark II), ARW (uncompressed, cRAW/ARW2, lossless L/M/S, A900 packed, ARW6 Compressed/HQ on the ILCE-7RM6), NEF (uncompressed, lossless/lossy, lossy-after-split, table-less 34713 strips as packed 12/14-bit), RAF (uncompressed and lossless/lossy compressed, Bayer + X-Trans), RW2/RWL/Panasonic RAW (formats 2/4/5/6/7/8 incl. tiled high-resolution format 8), PEF, ORF (uncompressed incl. 12.8 bpp), SRW (uncompressed), ERF, MEF, Minolta MRW, 3FR/FFF, Kodak DCS520C TIFF, and Sony SR2. Hostile-file memory bounds were hardened across the raw decoders in this release.
- **Per-model coverage is measured, not implied.** Of Adobe's 1,446 listed models: **551 verified** from sensor data (38%), 656 decoder-path-unverified, **202 preview-only**, **37 unsupported** (`docs/raw/coverage.tsv` sums re-checked at this tag; the headline table in `docs/raw-parity.md:20-21` still says 201/38). Use-weighted: **~94% of photographers' cameras fully decode, ~85% on a verified body** (`docs/raw-parity.md:23-24`).
- **Anything it cannot decode falls back to the embedded camera JPEG** and is flagged `previewOnly`; the app rechecks those photos in the background on version change, and headless callers use `library.recheckPreviewOnly` (`crates/engine/src/cmd/recheck.rs`; `docs/mcp.md`). Sparse header + embedded-JPEG reads avoid pulling sensor data over a network share (56.5 MB → 5.9 MB on the test share; `docs/raw-preview-reads.md:1-13`).
- **HEIC/HEIF decode** exists behind the `heif` build feature; it is off by default for HEVC-patent reasons and **on in official packaging** (`crates/codecs/Cargo.toml` still claims releases don't ship it — `packaging/macos/package.sh:65` passes `--features lightcraft/heif`, and the installed 0.15.0 binary contains `lightcraft_heif::decode|probe|decode_thumbnail`). The heic-rs path is hardened against hostile HEIF containers. AVIF is import-listed but never decodes (export only).
- **Lightroom Classic catalog import** (`library.inspectLightroom` / `library.importLightroom`, File ▸ Import Lightroom Catalog…): reads `.lrcat` directly (read-only pure-Rust SQLite incl. committed WAL; 16 GiB / 16,777,216-page cap), one-way and approximate, imports ratings/flags/labels/keywords/collections/virtual copies/mapped develop settings. The app first asks whether the catalog **merges into the open library or goes into a new library** — `file.importLightroom {into?: "open"|"new", name?, location?}` makes that choice headlessly, and Settings ▸ General can turn the question off (`crates/ui-egui/src/lightroom_destination.rs:1-30`; `docs/lightroom-catalog-import.md:87`). Also `folder.scanChanges` / `folder.synchronize` and `library.autoImport` / `library.autoImportScan` (`crates/engine/src/cmd/sync.rs`, `crates/engine/src/cmd/library.rs`).

### Develop, masks and merge — implemented

- **122 named develop sliders** in one spec table plus **10 indexed specs** (8 Point Color + 2 Red Eye), addressed as `pointColor.<i>.<control>` / `redEye.<control>`; 16 sections: Light, Curve, Color, Mixer, BwMix, Grading, Effects, Vignette, Grain, Detail, Optics, Geometry, Profile, Calibration, PointColor, RedEye (`crates/develop/src/controls.rs`; count it with `lightcraft-cli controls --json`).
- **22 built-in develop profiles** (looks, `crates/engine/src/presets.rs:476` `PROFILES`) — Color, Neutral, Vivid, Landscape, Portrait, Monochrome plus film/cinema/muted/B&W families — a profile *browser* with recent profiles; the profile is separate from the raw camera profile below.
- The pipeline is scene-referred linear Rec.2020 32-bit float with OkLCh-based colour and a filmic shoulder for raw, pass-through for untouched JPEGs (`README.md`). **Process versions V1 (frozen) and V2 (current)** make re-renders deterministic; `develop.updateProcess` moves photos forward (`docs/process-versions.md`; `crates/develop/src/settings.rs`).
- `develop.set` / `develop.adjust` / `develop.auto` / `develop.wb` / `develop.wbPick` / `develop.matchExposure` / `develop.copy|paste|sync|autoSync` / `develop.merge` / `develop.reset*` / `develop.beginInteraction|endInteraction`; white balance is Kelvin on raws with colour matrices or measured presets, relative (6500 = as shot) elsewhere (`crates/engine/src/cmd/develop.rs`; `docs/control-protocol.md` "White balance").
- **Masking**: brush, linear/radial gradients, luminance range, colour range, Subject / Sky / Background heuristics, plus Object and Describe via an optional SAM 3 model; Add/Subtract/Intersect, invert, and **17 local sliders + a colour overlay + Amount** per mask. Straight agent brush strokes: `mask.brushStroke {connect: true}` (`crates/develop/src/settings.rs:829-852`; `crates/engine/src/cmd/masks.rs`; `docs/ai-masks.md`).
- **Crop, geometry and repair**: crop/straighten/rotate/flip with aspect ratios that stay portrait after rotation, **aspect lock** (`crop.lockAspect`, `A`), auto-straighten (refuses turns > 10° and needs ≥ 3 agreeing lines), Upright Auto/Level/Vertical/Full/Guided, Constrain Crop; Heal/Clone spots with auto source, non-generative Fill (PatchMatch), editable pins, Visualize Spots, Red Eye and Pet Eye (`crates/engine/src/cmd/develop.rs`; `crates/inpaint/src/lib.rs:1-22`).
- **Photo Merge**: HDR (auto-align, deghost incl. moving lights, deterministic order, bracket batching), Panorama (spherical/cylindrical/perspective, boundary warp, auto crop, Lanczos-3 resampling; hard maxima 512 MP / 65,000 px; default output at the photos' own resolution unless `maxMegapixels` caps it), HDR Panorama → DNG; commands `merge.hdr|panorama|hdrPanorama|hdrBatch`; CLI `merge hdr|panorama|hdr-panorama|hdr-batch` (`docs/merge.md:20-31`; `crates/merge/src/pano/mod.rs:34-57`; `crates/merge/src/flow.rs`, `crates/merge/src/refine.rs`). Full-size exports got faster in this release (fewer copies and serial passes).
- **GPU**: the develop pipeline as wgpu compute kernels on Metal/Vulkan/DX12, checked against the CPU pipeline to within 1/255; CPU fallback on device limits or errors (`README.md`; `docs/gpu-pipeline.md`). **AI Denoise** is a per-photo switch, Bayer RAW only, with **no weights bundled** (user-installed ONNX + `denoise-model.json`), results cached under `<library>/denoise/`; `lightcraft-cli denoise-serve` serves tiles to other machines over a LAN/VPN with token auth (`docs/denoise.md:1-40`).

### Presets, colour and lens data — implemented

- **41 built-in presets** with an Amount slider 0–200%; copy/paste/sync of chosen settings groups; `.lcpreset` is LightCraft's own preset file. Import also accepts XMP presets, legacy `.lrtemplate`, Luminar `.lmp`/`.mplumpack`, `.zip` bundles, `.cube` LUT profiles and local-adjustment effect presets (`.lrtemplate`, `.xmp`, `.lceffect`) (`crates/engine/src/presets.rs`; `crates/engine/src/cmd/preset_files.rs`, `crates/engine/src/cmd/lut_profiles.rs`, `crates/engine/src/cmd/mask_effect_files.rs`).
- **Camera colour** starts from DNG matrices, guarded per-file fits to the camera JPEG, **9 bundled profiles** (Sony ILCA-99M2, ILCE-7CR, ILCE-7M4, **ILCE-7RM5 (α7R V — new this release)**; Fujifilm X-H2S, X-T4; Nikon Z 6II, Z 8, D5300 — `crates/engine/src/camera_profiles.rs:27` `BUNDLED`, 9 entries; `assets/camera-profiles/`), **52 spectral matrices** (`crates/raw/src/spectral_table.rs`, 52 `Camera` entries), or a neutral fallback. `lightcraft-cli calibrate` fits per-camera profiles from a user's own raws (Sony ARW, Nikon NEF, Fujifilm RAF). Measured ΔE against the camera JPEG is 2.9–10 (`docs/gaps.md:18`).
- **Lens corrections**: embedded DNG opcodes, Panasonic/Leica RW2/RWL distortion, Nikon Z 6II / Z 8 / Z f distortion, Sony ILCE-7RM4A / ILCE-7CR / ILCE-7RM6 / **ILCE-6700 (new in v0.16.0)** distortion, and **Fujifilm distortion + vignetting for 59 validated bodies — X-S20 added in v0.16.0, plus lens profiles for compact cameras with a built-in lens**; all go through Optics ▸ Enable Lens Corrections (`crates/raw/src/vendor/`; `docs/*-lens-corrections.md`). For everything else, a **user-supplied lensfun XML database** via `LIGHTCRAFT_LENSFUN_DIR` adds distortion/TCA/vignetting; no database is bundled, Adobe `.lcp` is never used, matching is automatic, and fisheye is not corrected (`crates/lensdb/src/lib.rs:1-14`; `crates/engine/src/lens_profiles.rs`; `docs/lens-profiles.md`).

### Export and output modules — implemented

- **10 export formats** (`ExportFormat`, `crates/engine/src/export/options.rs:5`): `jpeg png tiff psd webp avif jxl original dng rendereddng`. `psd` is a **flat** PSD (8/16-bit, no layers); `original` copies the file plus an XMP sidecar carrying the edits; `dng` writes a raw photo as DNG with edits embedded; `rendereddng` bakes the render into a linear 16-bit float DNG.
- **Validated export options** (`ExportOptions`, `crates/engine/src/export.rs`, parsed by `from_params`): `quality 1-100`, `bitDepth 8|10|16|32` per format, `colorSpace srgb|displayP3|adobeRgb|proPhoto|rec2020` with embedded ICC, `metadata all|allExceptCamera|copyright|none`, `removeLocation` (an `original` export is refused when a PSD/PSB embeds GPS it cannot strip), `sharpen none|screen|matte|glossy` + amount, `tiffCompression`, `dngCompression`, `conflict unique|overwrite|skip`, resize by `longEdge|shortEdge|width|height|megapixels|percent` with `dontEnlarge`, `fit dimensions|widthHeight`, `ppi`, `limitKb` (JPEG, incl. HDR gain-map JPEG), text/image `watermark` (vertical, rotation, nine anchors, image orientation honoured), `hdr` with `hdrTransfer pq|hlg`, `jxlLossless|jxlEffort|jxlProgressive`, `destinationMode: "sameAsOriginal"`, and macOS-only `addToPhotos` + `photosAlbum`.
- **File-naming and folder templates** share one token set — `{name} {num} {seq} {seq:N} {date} {date:%Y%m%d} {folder} {camera} {lens} {iso} {rating} {title} {creator} {ext}`; unknown tokens stay as typed, illegal characters become `-`, collisions get a suffix (`crates/engine/src/rename.rs`; `photo.renameTokens` lists them).
- **Contact Sheet PDF**: A4/Letter, rows/columns, captions, 150 dpi sRGB; limits 1,000 photos / 100 pages / 256 MiB; atomic replace; command `export.contactSheet` (`crates/engine/src/contact_sheet.rs:87-92`).
- **Print module** as `print.*` commands (`print.get/set/reset`, `print.cell.*`, `print.layout.*`, `print.exportPdf`, `print.template.list|save|apply|delete|export|import`): Single Image, Contact Sheet, Picture Package (Auto Layout), Custom Package; zoom-to-fill / rotate-to-fit; borders/strokes; A3–A5, Letter/Legal/Tabloid, 4×6/5×7/8×10/13×19, Japanese photo/postcard sizes or custom; margins; guides/rulers; saved templates **as `.lcprint` files**; printer/paper ICC + intent + black-point compensation; 8/16-bit colour-managed PDF; Page Options (page numbers, page info, crop marks) on Single Image and Contact Sheet (`crates/engine/src/cmd/print.rs:385-401`; `crates/engine/src/print/template.rs:34` `FILE_EXT = "lcprint"`; `crates/engine/src/print_pdf.rs`).
- **Slideshow**: playback (fades, random order, repeat, prepared previews), layouts, overlays (identity plate, rating stars, text tokens, export watermark), intro/ending title screens, built-in + user templates with import/export, and background export to PDF (page per slide), numbered JPEG sequence, or **AV1 video in MP4/WebM (no audio, at most 2 hours)**; commands `slideshow.*`, progress via `activity.list`, `slideshow.exportStatus` (`crates/engine/src/cmd/slideshow.rs`; `crates/engine/src/slideshow_export.rs:40-42`; `docs/slideshow.md`).
- **Apple Photos (macOS only)**: `app.export {addToPhotos: true, photosAlbum}` or `export.addToPhotos {paths}`; the first run triggers a macOS Automation permission prompt (`docs/apple-photos.md`).

### Interchange — implemented

- **XMP sidecars** read/write, manual (`⌘S`, `photo.saveMetadataToFile`) or automatic (`library.xmpPreferences {autoWrite, naming: stem|full}`); LightCraft's fields plus the full develop state as `lc:settings` under `http://ns.lightcraft.app/lc/1.0/` (`crates/meta/src/xmp.rs:18`); owned properties are replaced, capture time/GPS only when LightCraft has a value, **foreign namespaces kept byte for byte** (including when they use `lc:`/`xmp:` prefixes), an existing sidecar is merged into, writes are atomic, failed writes retry and `library.retrySidecars` forces them (`docs/xmp-interop.md`; `crates/engine/src/cmd/xmp.rs`).
- Reading Adobe `crs:` develop settings is **approximate** and reports per-photo warnings; Lightroom radial masks apply inside the circle as Lightroom does (`docs/xmp-interop.md`).
- **PSD/PSB metadata**: imports embedded EXIF (resource 1058) and XMP (resource 1060) image resources, so capture dates, GPS and descriptive fields survive; PSD edit copies keep their capture date (`crates/meta/src/psd.rs:1-20`).
- GPX track logs, offline reverse geocoding (GeoNames towns ≥15k; `metadata.reverseGeocode {maxDistance}`), keyword lists with keyword sets (nine keywords per set, `⌥1–⌥9`; next/previous set `⌥0`/`⌥⇧0`), XMP face names (face boxes are catalog-only and never written to XMP), and capture-time edits (`photo.setCaptureTime`) (`crates/engine/src/cmd/geocode.rs`, `crates/engine/src/cmd/keywords.rs`, `crates/engine/src/cmd/manage.rs`).
- macOS edit-in: **Edit in PhotoCraft / Edit in Other Editor** renders `<name>-Edit.tif` (16-bit Adobe RGB by default; flat `.psd` or 8-bit optional), stacks it on the original and opens it; at most 50 photos per call (`crates/engine/src/cmd/convert.rs`).

### Automation surface — implemented (the strongest part of the app)

- **Everything is a command.** At this tag: **375 engine command specs** (counted from the `cmd!` literals in `crates/engine/src/cmd/*.rs`, re-counted unchanged at v0.16.0 and wired by 39 `specs()` sites in `crates/engine/src/cmd.rs`) and **191 UI commands** in `UI_COMMANDS` (`crates/ui-egui/src/menus/ui_commands.rs`) plus **18 language commands**, i.e. **209 UI entries**, so a running app's `engine.commands` reports **584** commands. `engine.commands` returns id, label, menu path, shortcut, parameter doc and current enablement; UI, CLI, control channel and MCP all dispatch by id.
- **MCP server**: `lightcraft-cli mcp [--demo | --library DIR | FILES…]` headless, or `lightcraft-cli mcp --connect 127.0.0.1:7980` to drive the live app. Hand-written JSON-RPC over stdio, protocol `2025-06-18` (older revisions accepted), 7 resources (`lightcraft://document`, `//commands`, `//library`, `//photos`, `//photo/active`, `//develop/active`, `//controls`). Helpers: **17 headless / 28 connected** (`crates/mcp/src/tools.rs:78` `helper_tools`: 17 always-on tools + 11 UI-only when a desktop app is attached): `command_list/run/batch`, `doc_inspect`, `render_preview`, `import`, `query_photos`, `select_photos`, `list_controls`, `get_develop`, `set_develop`, `apply_preset`, `crop`, `render_photo`, `export` (plus the documented legacy `list_commands` / `run_command`); connect mode adds `ui_inspect`, `ui_screenshot`, `screenshot`, `inspect_ui`, `set_ui`, `list_widgets`, `click`, `press_key`, `type_text`, `clipboard`, `pointer_gesture`. One generated `cmd_*` tool per reported command, so `tools/list` totals **392** tools headless (17 helpers + 380 engine commands) and **612** connected (28 helpers + 584 commands); `--compact` lists helpers only (`crates/mcp/src/tools.rs`; `crates/mcp/src/server.rs`; `docs/mcp.md`).
- **Control channel**: `lightcraft --control 7980` (or `LIGHTCRAFT_CONTROL_PORT`) serves JSON-lines on `127.0.0.1:PORT`, **loopback only, no authentication**, at most 16 connections, 4 MiB line cap. Requests are answered on the UI thread with a 60 s timeout; a request that has not started and draws no frame for 5 s is failed and never retried; an idle connection closes after 5 minutes; a malformed line closes the connection (`apps/lightcraft/src/control_server.rs:24-77`; `docs/control-protocol.md:1-40`). Same dispatch surface as the previous skill (**24 arms exposing 29 callable method names**, list at `crates/ui-egui/src/control.rs`): `engine.execute` (aliases `ui.menu.invoke`, `command`), `engine.commands`, `ui.menu.list/tree`, `ui.inspect`, `ui.widgets`, `ui.clickWidget|dragWidget|hoverWidget`, raw `ui.move|click|drag`, image-coordinate `ui.pointer`, `ui.key`, `ui.text`, `ui.clipboard`, `ui.scroll`, `ui.zoom` (pinch), `ui.set`, `ui.dialog.confirm|cancel`, `ui.resize`, `ui.zoomFactor`, `ui.screenshot`, `ui.render`, `ui.dropFiles` (drag-and-drop imports, with `hover` for the drop card), `app.quit`.
- **CLI subcommands** (`apps/lightcraft-cli/src/main.rs` USAGE + dispatch): `run`, `mcp`, `render`, `snapshot`, `merge`, `synth-merge`, `denoise-serve`, `commands`, `controls`, `calibrate`. `run` takes `--demo|--library DIR|--connect [ADDR]`, repeatable `--import`, `--script FILE|-`, `--keep-going`; `render` takes `--set control=value`, `--settings look.json|.lcpreset|.xmp`, `--preset ID`, `--size`, `--quality`, and any export option via `--opt KEY=VALUE`; `merge` writes `<first>-HDR.dng` / `-Pano.dng` / `-HDR-Pano.dng` next to the first file (`--preview OUT.png` writes only a preview); `commands` lists ids sorted for readable families.
- **Headless UI snapshots** need no window and no GPU: `lightcraft-cli snapshot --demo --script tour.jsonl -o out.png --size 1600x1000 --scale 2` runs the full egui UI on the CPU. In a running app use `ui.screenshot {"path": …, "headless": true}`; windowed capture falls back to headless after 2 s. In snapshot scripts `ui.settle {timeoutMs}` waits for renders (`docs/control-protocol.md` "Headless rendering").
- **Update check (new this release)**: a startup update prompt modal with self-update, delegated to the shared `craft-update` crate (`apps/lightcraft`, `Cargo.toml` craft-update pin).
- **Web build automation**: the browser build exposes `await globalThis.lightcraft.command("<id>", "<json params>")` returning JSON text; params must be a JSON object (a typo such as `{ids: [3]}` is refused instead of running the command on the selection) (`apps/lightcraft-web/index.html:39-40`; `apps/lightcraft-web/src/automation.rs:1-20`).

### Platform — implemented

- Native **macOS / Windows / Linux** (deb, rpm, AppImage, Flatpak, tarball; riscv64 tarball), a **FreeBSD** tarball, and a **WebAssembly build of the same UI** (WebGL2 via eframe's glow backend) with a persistent browser library in OPFS/IndexedDB; WebGPU and Safari/Firefox testing are in progress; JXL export is native-only and merges have no file access in the browser (`docs/web.md`; `README.md` Downloads). Windows installs per-user by default now (MSI for your account, no administrator prompt).
- **18 interface languages** in code: English, Simplified/Traditional Chinese, Japanese, Brazilian Portuguese, Spanish, German, Russian, French, Ukrainian, Polish, Czech, Italian, Georgian, Swedish, Finnish, Indonesian, Vietnamese (`crates/ui-egui/src/i18n.rs`; one `LANGUAGE_COMMANDS` entry each). Coverage is partial and lower-layer errors stay English; no RTL or complex-script shaping.
- Display colour management: macOS screen profile, Linux colord, or a chosen ICC file via Settings ▸ Display / `app.displayProfile`; Windows WCS is not implemented (`docs/display-profiles.md`). Portable mode (`portable.txt` beside the executable) and isolated automation profiles via `LIGHTCRAFT_CONFIG_DIR` (`apps/lightcraft/src/main.rs:793-815`).
- **Tests in CI**: Linux x64 runs `cargo xtask ci` on every push/PR (`.github/workflows/ci.yml`), FreeBSD runs a nightly build/package check; macOS/Windows package but do not run the suite (`docs/gaps.md:26`).

## Known limitations and not-implemented

Read this before assigning work. Each item is the project's own admission or a code path that is absent.

**Raw and colour**

- **Camera colour is estimated, not measured.** Raws start from a per-file fit to the camera JPEG (run on the vignetting-corrected sensor since v0.16.0), the **9** bundled profiles, 52 spectral matrices, or a neutral fallback; measured ΔE against the camera JPEG is 2.9–10 (`docs/gaps.md:18`). The old "5 bundled profiles" doc bug is fixed in the docs at this tag.
- **No bundled lens database.** Only in-file data plus the opt-in lensfun XML database; Adobe's 3,635 profiles are never used — deliberately. lensfun matching is automatic (no manual picker), raws only, no fisheye, and not validated against real photos (`docs/gaps.md:25`; `docs/lens-profiles.md:40-45`).
- **Preview-only raws**: compressed Olympus/OM ORF (58 of 78 models in the generated table), Nikon High-Efficiency (HE / HE★) NEF, several CRX variants (vertical-tile C-RAW, partial subband, multi-tile 0x200, adaptive low-frequency gains), compressed Samsung SRW, and the long tail IIQ / Hasselblad-compressed / X3F / CRW / GPR / DCR (`docs/gaps.md:19,23-24,37`; `docs/raw/coverage.tsv`). All 110 public CC0 CR3s decode; 26 CR3 bodies are verified, but some variants have no public sample (`docs/cr3.md`).
- **AVIF cannot be imported** (no permissive pure-Rust AV1 decoder); AVIF is export-only. `.HIF` HEIC stills are not CR3; HEIC 4:2:2/4:4:4 frames are refused (`crates/engine/src/import/files.rs`; `docs/file-format-parity.md`).
- **PSD/PSB import is the merged composite only** — no layers or layer styles; LightCraft writes flat PSDs (`crates/codecs/src/psd.rs:1-5`).
- **Render fidelity is unmeasured**: tone, highlights, texture/clarity/dehaze, noise reduction and sharpening are tuned by eye, so edits imported from Lightroom will not look identical (`docs/gaps.md:20`).

**AI and enhancement**

- **AI masks**: Subject, Sky, Background (and the model's People/Landscape kinds) are classical heuristics, not models; only **Object** and **Describe** use SAM 3, and the 3.4 GB model is **not bundled**. The built-in download-mirror list is empty, so the in-app download needs a user-configured `LIGHTCRAFT_SAM3_MIRRORS` or a manually installed model folder (`docs/ai-masks.md`; `docs/gaps.md:22`).
- **AI Denoise ships no weights**: user-installed ONNX + `denoise-model.json`; Bayer RAW only, no X-Trans, and it does not run on merged linear DNGs. The optional RawNIND weights are GPL-3.0 and gated behind a release policy (`docs/denoise.md:14-24`; `docs/gaps.md:28`).
- **Absent: Super Resolution, Raw Details, content-aware/generative remove, reflections and distraction removal** (`docs/gaps.md:28-29`).

**Output and interchange**

- **Print** lacks identity plate / watermark / photo-info overlays (beyond Page Options), Cut Guides, Auto Layout for *Custom* Package, printer-driver Page Setup, direct printer output and JPEG output; it produces a colour-managed PDF (`docs/gaps.md:32`).
- **HDR display (EDR / Windows HDR) is not implemented**: HDR editing, the headroom limit and SDR rendition work, but you edit blind on an HDR monitor (`docs/gaps.md:31`).
- **Slideshow** has playback, layouts, overlays, titles, templates and PDF/JPEG/AV1 export, but no music and no dedicated module editor (`docs/gaps.md:33`).
- **Lightroom catalog migration is one-way and approximate**; unsupported Adobe profiles/AI settings are archived (`docs/lightroom-catalog-import.md`; `docs/gaps.md:30`).
- **No custom ICC output profile**, and **Render to DNG** exists only as the export format `rendereddng`, not as a catalog command (`docs/file-format-parity.md`; `docs/gaps.md:42`).

**Do not assign**

- Video (playback, trim, edits, export): a `Video` media kind exists in the catalog model, but the importer's extension list is stills-only and there is no playback or editing path (`crates/catalog/src/model.rs`; `crates/engine/src/import/files.rs`; `docs/gaps.md:35`).
- Map view, Book module, publish services, tethered capture, Lightroom plug-ins / SDK; no HDR display (map/book `docs/gaps.md:33`, tethered `:34`, plug-ins `:36`, HDR display `:31`).
- **No document file format.** There is no "save as" for an edited photo: the library folder is the unit of persistence and edits live in the catalog and/or an XMP sidecar. The macOS bundle declares **no** `CFBundleDocumentTypes` (`/Applications/LightCraft.app/Contents/Info.plist`; `crates/engine/src/library.rs:1-22`).

**Platform, quality and docs**

- Per-model verification is thin: 551 of 1,446 Adobe models verified (38%), ~85% of photographers on a verified body (`docs/gaps.md:27`). macOS/Windows/Linux package but do not run the test suite. Windows/Linux GPU paths are only partly proven (`docs/gaps.md:44`).
- Localization is partial; lower-layer errors stay English; no RTL or complex-script shaping (`docs/localization-parity.md`). Accessibility is partial: AccessKit tree audited, but brush/red-eye keyboard access and a real screen-reader session remain (`docs/gaps.md:39`).
- **Docs that disagree with code (trust the code):** `docs/raw-parity.md` headline 201 preview / 38 unsupported vs the generated `docs/raw/coverage.tsv` 202 / 37; ROADMAP 81.6%/532 vs checklist summary 83.5%/543; `docs/file-format-parity.md` still marks PSD write ⬜ while export implements it; `crates/codecs/Cargo.toml` says releases don't ship the `heif` feature while `packaging/macos/package.sh:65` passes it and the installed binary decodes HEIC; `docs/gaps.md:38` names Vietnamese as absent although it ships in `crates/ui-egui/src/i18n.rs`.

## How to operate

**Launch (macOS).** `open -a /Applications/LightCraft.app` for the GUI, or the binary directly when you need flags: `/Applications/LightCraft.app/Contents/MacOS/LightCraft`. Real flags, parsed in `apps/lightcraft/src/main.rs` (HELP at `:793`):

```
lightcraft [OPTIONS] [FILES/FOLDERS…]      # positional paths are imported at launch
  --library DIR    open (or create) this library (env LIGHTCRAFT_LIBRARY; default: last library opened,
                   else ~/Pictures/LightCraft Library; Settings ▸ General ▸ At launch: Ask me shows a list)
  --no-demo        don't seed a new library with the procedural demo photos
  --memory         throwaway in-memory session (alias --demo); writes nothing
  --control PORT   serve the JSON-lines control channel on 127.0.0.1:PORT
  --version, --help
```

Useful environment: `LIGHTCRAFT_LIBRARY`, `LIGHTCRAFT_CONTROL_PORT`, `LIGHTCRAFT_CONFIG_DIR` (isolated settings/logs/model profile), `LIGHTCRAFT_LANGUAGE=de|ja|zh-hans|…`, `LIGHTCRAFT_GPU_BACKEND=dx12|vulkan|metal|auto|off`, `LIGHTCRAFT_GPU=0`, `LIGHTCRAFT_LOG=info|debug` / `RUST_LOG`, `LIGHTCRAFT_MEMORY_MB`, `LIGHTCRAFT_NO_PREFS`, `LIGHTCRAFT_NO_NATIVE_MENU`, `LIGHTCRAFT_SAM3_DIR|_MIRRORS|_TOKEN|_REMOTE`, `LIGHTCRAFT_LENSFUN_DIR`, `LIGHTCRAFT_CAMERA_PROFILES`, `LIGHTCRAFT_DENOISE_MODELS|_URL|_TOKEN`, `LIGHTCRAFT_HDR_DISPLAY=0`, `LIGHTCRAFT_FPS=1` (start with the frame-rate overlay on), `LIGHTCRAFT_PROFILE=1` (`apps/lightcraft/src/main.rs:806-815`; other env vars in `crates/engine` and `crates/segment`). Logs go to the settings folder's `logs/lightcraft.log`, rotated on each start.

**The CLI is a separate download on macOS.** The `.app` contains only the desktop app; there is no `lightcraft-cli` inside it and none on a stock `PATH`. Get `lightcraft-cli-<ver>-macos-universal.zip` from the release assets or build it with `cargo build --release -p lightcraft-cli`. Use the CLI and the app from the same release (`docs/mcp.md` "From an installed release").

**Window/document model.** One process = one open library; a main window (grid or Detail) plus an optional second window (`⌘F11`). There are no per-photo documents and no tabs. Switching libraries is File ▸ Open Library… (`app.openLibrary`, `⌘O`) or File ▸ New Library… (`app.newLibrary`); if a library cannot be opened, the app starts an empty session and asks (`ui.inspect` → `libraryProblem`). Pointing Open Library at a Lightroom catalog folder offers the importer instead (`docs/control-protocol.md`; `crates/ui-egui/src/panels/library_problem.rs`).

**Keyboard (verified in the command registry and `crates/ui-egui/src/shortcuts.rs` — do not invent others).** Views: `G` grid, `D` detail, `N` survey, `⇧C` compare, `⇧R` reference, `F` full-screen preview, `⇧L` Lights Out, `⇧F` filter bar, `/` filmstrip, `F6`/`F7`/`F8` filmstrip/left/right panel, `\` Filter Bar in grids (Show Original in Detail). **v0.16.0 additions: holding Space over any tool pans (click-zoom as usual); Alt/Option-drag shows a live clipping or sharpening preview; keyword painting is the `tool.keywordPainter {keyword?}` command (no default shortcut — assign one with `app.setShortcut`); Clear Color Label can carry a user shortcut.** Panels/tools: `E` Edit, `C` Crop & Rotate, `M` Masking, `H` Remove, `I` Info, `K` Keywords, `⌘K` Add Keywords, `⇧P` Presets, `⇧V` Versions, `B`/`L`/`R`/`W` brush/linear/radial/WB picker, `A` aspect lock (crop) / Visualize Spots, `S` soft proof (in grids `S` toggles the stack), `Shift+S` stack set-top. View aids: `Z` zoom, `J` clipping, `Shift+O` crop overlay, `⇧H` tool overlay, `⌘J` View Options, `⌘I` info overlay, `⌥F` focus point, `Y`/`⇧Y`/`⌥Y` before/after. Rating: `0`–`5`, `6`–`9` labels, `P` pick, `X` reject, `U` unflag, `` ` `` cycle flag, `[`/`]` step rating, `⌘↑`/`⌘↓` flag up/down, `⇧0-9/P/X/U` apply-and-advance. Keywords: `⌥1`–`⌥9` apply a set member, `⌥0`/`⌥⇧0` next/previous set. Misc: `Enter` open/done, `Esc` back, `⌘Z` undo, `⌘L` Enable Filters, `⌘⌥⇧C`/`⌘⌥⇧V` copy/paste metadata, `⌘⇧I` import, `⌘⇧E` Edit in PhotoCraft, `⌘⌥E` Edit in Other Editor, `⌘P` print, `⌘⌥↵` slideshow. **All keys are user-remappable** (`app.setShortcut`); `⌘,` and `⌘Q` are reserved (`crates/ui-egui/src/shortcuts.rs:17`; `docs/library-shortcuts.md`).

**Open / save / export.** Import with File ▸ Import Photos… (`⌘⇧I`, `file.addPhotos`), Import from Folder… (`file.addFolder`), or by passing paths on the command line; files dropped on the window go through the import review (`ui.dropFiles` reproduces that headlessly). There is nothing to "save": each command persists. `⌘S` (`photo.saveMetadataToFile`, Photo ▸ Save Metadata to File) writes sidecars; automatic sidecar writing is File ▸ Automatically Write Changes into XMP (`library.toggleAutoWriteXmp`), both driving `library.xmpPreferences`. Export with File ▸ Export… (`dialog.export`), Photo ▸ Edit In (`⌘⇧E` / `⌘⌥E`), File ▸ Contact Sheet PDF…, File ▸ Print… (`⌘P`; its dialog is titled "Print to PDF…" and writes a colour-managed PDF), View ▸ Export Slideshow…, or the equivalent commands. The photo export itself is always `app.export` with the options above (`crates/engine/src/export.rs`; `crates/engine/src/cmd/xmp.rs`).

**Drive it — the three supported routes**

1. One-shot CLI (best for batch work, no session state):
   ```sh
   lightcraft-cli run --import ./shoot develop.set control=light.exposure value=0.7 \
       develop.auto app.export dir=out longEdge=2048 colorSpace=displayP3
   lightcraft-cli run --library ./lib library.select ids=[3] develop.get
   lightcraft-cli run --demo --script steps.jsonl --keep-going    # JSON lines; stdin works too
   lightcraft-cli run --connect 127.0.0.1:7980 ui.set view=detail ui.screenshot path=ui.png
   lightcraft-cli render in.dng -o out.jpg --set light.exposure=0.5 --size 2048 --quality 92
   lightcraft-cli merge hdr-batch ./brackets                      # every bracket set in the folder
   ```
   One JSON line per command (`{command, ok, result|error, ms}`); non-zero exit on failure; a bare word starts the next command, `key=value` values parse as JSON when they can (`docs/mcp.md` "One-shot commands").
2. Control channel (best for interacting with a live UI or an external controller):
   ```json
   {"id":1,"method":"engine.execute","params":{"command":"develop.set","params":{"values":{"light.highlights":-45}}}}
   {"id":2,"method":"ui.dropFiles","params":{"paths":["./shoot"]}}
   ```
   Discover identifiers with `engine.commands`, `develop.controls`, `ui.widgets`; never hard-code translated labels or widget positions. Group slider bursts in `develop.beginInteraction` / `develop.endInteraction` (one undo step). On macOS `ui.key` injects egui events and does **not** synthesize Cocoa menu accelerators; use `ui.menu.invoke` with the command id when testing menu shortcuts (`docs/control-protocol.md` "Methods").
3. MCP (`lightcraft-cli mcp`): helpers plus `command_list` / `command_run` / `command_batch` / `doc_inspect` / `render_preview`, 7 resources, and one generated tool per command unless `--compact`. In connect mode the UI tools are added; in headless mode they return an error explaining how to start the app (`docs/mcp.md`).

**Look at the result.** Any UI work must be verified visually: `lightcraft-cli snapshot --demo --script tour.jsonl -o out.png` or `{"method":"ui.screenshot","params":{"path":"a.png","headless":true}}`. Before capturing, poll `ui.inspect` until the expected `loupe.photo` is active, `loupe.source` is `render` or `cached`, `loupe.pending` is false and the render queues are empty — or `loupe.failed` is set (`docs/control-protocol.md` "Before capturing a finished Detail view").

## Working with an AI agent

**Legitimate agent work**

- Pre-generate or convert inputs into supported formats before touching the library. There is no ingest conversion step for unsupported files: an unsupported raw/AVIF stays unsupported unless you convert it externally. HEIC works only in a build with the `heif` feature (official macOS packaging has it) (`crates/engine/src/import/files.rs`; `crates/codecs/Cargo.toml`).
- Batch develop and export through `lightcraft-cli run --import …`, or against a persistent library with `--library DIR` so ratings and edits survive between calls (`docs/mcp.md`).
- Batch-render one image with a settings JSON: `lightcraft-cli render in.dng -o out.jpg --settings look.json` (a partial develop-settings object, or a single-preset `.lcpreset`/XMP file) plus `--set control=value` and `--opt` for export options (`apps/lightcraft-cli/src/main.rs` USAGE).
- Inspect and repair library files: `catalog.snap` and `catalog.log` are documented, CRC-checked JSON; the loader already handles torn appends and damaged records. Back the folder up before editing anything by hand (`crates/catalog/src/journal.rs:1-40`).
- Verify exports by reading the returned `{path, width, height, bytes, sidecars}` and then the file itself; the encoder is pure (bytes in, bytes out) so it is testable without a window (`crates/engine/src/export.rs:1-5`).
- Read XMP sidecars to understand another tool's edits; LightCraft preserves foreign namespaces. Do not expect LightCraft to write face regions to XMP (`docs/xmp-interop.md`).
- Rebuild camera colour profiles from a user's own raws with `lightcraft-cli calibrate`; enable lens corrections from the user's own lensfun database by setting `LIGHTCRAFT_LENSFUN_DIR` before launch (`apps/lightcraft-cli/src/main.rs` USAGE; `crates/engine/src/lens_profiles.rs`).
- Drive output modules as commands: `export.contactSheet`, the `print.*` family (including `.lcprint` template import/export), `slideshow.*` and `export.addToPhotos`, with `activity.list` progress (`crates/engine/src/cmd/export.rs`, `crates/engine/src/cmd/print.rs`, `crates/engine/src/cmd/slideshow.rs`; `crates/engine/src/cmd/activity.rs`).
- Choose where a Lightroom catalog goes before importing: `file.importLightroom {into: "open"|"new"}` (UI command) or run `library.importLightroom` after opening the target library (`crates/ui-egui/src/lightroom_destination.rs:1-30`).
- Query and edit through MCP or the control channel using **command ids and control ids** from the registry, not translated labels; use `ui.inspect`/`ui.widgets` and automation ids for UI state (`docs/control-protocol.md`; `docs/mcp.md`).
- Install/point at optional models only with the user's consent: SAM 3 (Hugging Face gated; 3.4 GB) and denoise ONNX weights; face models are separate (`docs/ai-masks.md`; `docs/denoise.md`; `docs/faces.md`).

**Do not**

- Do not launch the GUI and drive it with OS-level synthetic input (osascript/System Events, cliclick): it goes to whatever window is frontmost. Use the control channel, `lightcraft-cli snapshot`, or MCP connect mode (repo `AGENTS.md`: "Never send OS-level synthetic input").
- Do not assume the CLI exists — on macOS it is a separate download, not inside the `.app` (`docs/mcp.md` "From an installed release").
- Do not assume a library can be opened by two programs at once (`catalog.lock`); use `--connect` instead (`crates/catalog/src/lock.rs:86`).
- Do not assume Adobe assets or formats work: `.dcp`, `.lcp`, Lightroom plug-ins, `.lrlibrary`. `.lrtemplate` is import-only; `.dcp`/`.lcp` are deliberately unsupported (`docs/file-format-parity.md`).
- Do not promise AI subject/sky masks, AI denoise, face recognition or super resolution out of the box — they need optional models, and the default SAM mirror list is empty (`docs/ai-masks.md`; `docs/denoise.md`; `docs/gaps.md:28-29`).
- Do not promise that a raw will develop from sensor data; check the format list above and expect preview-only for compressed ORF, HE Nikon NEF, some CR3 variants and compressed SRW (`docs/raw-parity.md`).
- Do not treat a returned command result as proof of a correct image. Nothing here validates the pixels (`docs/gaps.md:20`).
- Do not overwrite a catalogued original or its XMP sidecar: MCP `export`/`render_photo`/`screenshot` refuse such a `path`; use a new output folder (`docs/mcp.md` export helper).

## Verification protocol

LightCraft is alpha; its library is crash-safe but its output is not self-checking. For every non-trivial task:

1. **Throwaway round-trip first.** Make a scratch library (`--library` pointed at a fresh folder, or `lightcraft-cli run --demo`), import one file, change one slider, export, then reopen the export in LightCraft or any other viewer and confirm dimensions and pixels. Only then run the real batch. Use `--memory` when you only want to experiment — it writes nothing (`apps/lightcraft/src/main.rs:793-815`).
2. **Never trust a silent export.** `app.export` reports per-file `{path, width, height, bytes, sidecars}` and can report `gpuFallback`; a size/resolution mismatch or a zero-byte file is the failure you would otherwise miss. `format: "original"` also writes an XMP sidecar — check for it before assuming the folder is unchanged (`crates/engine/src/export.rs`; `docs/mcp.md` export helper).
3. **Check the render, not just the command.** `ok: true` means the command ran. Poll `ui.inspect` for `loupe.pending == false` (or `loupe.failed` for the reason) and take a screenshot/PNG before declaring success (`docs/control-protocol.md` "Before capturing a finished Detail view").
4. **Version and back up per session.** Copy the whole library folder before a bulk operation; the catalog is an append-only log, so a copied folder is a complete restore point. On the desktop there is **no in-app backup command** — `file.backupLibrary` / `file.restoreLibrary` are wired only where the platform supplies a backup service (the web build); on desktop the command returns "the library is a folder; back it up with your other files". Keep the app and CLI from the same release.
5. **Update between projects, never mid-project.** Re-run step 1 after any update — the launcher auto-updates, and a new build can change rendering; process versions exist for exactly that reason (`docs/process-versions.md`).
6. **Know your single-writer rule.** Any `--library` headless run fails while the desktop app holds that library. Reserve it in your plan, or drive the open app with `--connect` (`docs/mcp.md:20`; `crates/catalog/src/lock.rs:86`).
7. **Treat the control port as a local privilege.** It has no authentication and can run any command; only enable it for a task that needs it, on loopback (`docs/control-protocol.md:39`).

## Sources & evidence

- Repo: https://github.com/storytold/lightcraft — inspected tag **v0.16.0**, commit **`cdf00cc84bf87f544d6dbc40e3bc0456641661a9`** (shallow clone at the tag; `git rev-parse HEAD`), release dated 2026-10-31; inspection date **2026-11-01**. Target: Lightroom Classic 15.5 / Lightroom 9.6 (`ROADMAP.md:3`). License MIT OR Apache-2.0.
- Installed `/Applications/LightCraft.app`: `CFBundleShortVersionString` 0.15.0, binary `--version` prints `lightcraft 0.15.0`, bundle id `ai.storyteller.lightcraft` — **the installed bundle is the previous release; it lags this skill's pin.** The bundle has no `CFBundleDocumentTypes`. The 0.15.0 binary contains `lightcraft_heif::decode|probe|decode_thumbnail` (HEIC enabled in the official build). **Verify against your installed version.**
- Key code files read for this skill: `README.md`, `ROADMAP.md`, `Cargo.toml`, `apps/lightcraft/src/main.rs`, `apps/lightcraft/src/control_server.rs`, `apps/lightcraft-cli/src/main.rs`, `crates/engine/src/{library,import,import/files,camera_profiles,rename,contact_sheet,presets,export,export/options}.rs`, `crates/engine/src/cmd.rs` (specs() wiring) and `crates/engine/src/cmd/{library,develop,masks,keywords,print,export,slideshow,merge,sync,xmp,convert,previews,activity,cull,browse,query,organize,recheck}.rs`, `crates/develop/src/{controls,settings}.rs`, `crates/catalog/src/{journal,lock,model}.rs`, `crates/raw/src/{lib,spectral_table}.rs`, `crates/raw/src/vendor/`, `crates/mcp/src/{tools,server}.rs`, `crates/lensdb/src/lib.rs`, `crates/codecs/src/{psd,sniff}.rs`, `crates/codecs/Cargo.toml`, `crates/meta/src/{psd,xmp}.rs`, `crates/merge/src/`, `crates/inpaint/src/lib.rs`, `crates/ui-egui/src/{menus,menus/ui_commands,shortcuts,i18n,control,lightroom_destination,frame_rate}.rs`, `crates/ui-egui/src/dialogs/settings/` (libraries.rs; was `panels/settings.rs`), `packaging/macos/Info.plist.in`, `packaging/macos/package.sh`, `assets/camera-profiles/`, `.github/workflows/{ci,freebsd}.yml`.
- Docs read for this skill: `docs/{target-app-parity,raw-parity,file-format-parity,gaps,control-protocol,mcp,merge,slideshow,denoise,ai-masks,faces,focus-points,xmp-interop,process-versions,lens-profiles,camera-preview-colour,web,localization,localization-parity,background-tasks,raw-preview-reads,lightroom-catalog-import,display-profiles,apple-photos,library-shortcuts,parity-checklist,cr3}.md`, `docs/raw/coverage.tsv`, `docs/user/` trees.
- Counts were measured from source at this tag (not from README/docs or the previous skill): 375 engine command specs (39 `specs()` wiring sites in `cmd.rs`), 191 `UI_COMMANDS` + 18 language commands = 209 UI entries (584 total), 17/28 MCP helper tools, 7 MCP resources, 392/612 `tools/list` entries, 24 control arms / 29 method names (set unchanged), 10 CLI subcommands, 39 import extensions, 10 export formats, 122 + 10 develop controls, 41 presets, 22 develop profiles, 9 camera profiles, 52 spectral matrices, 18 languages, 1,446 Adobe raw models (551/656/202/37 — unchanged).
- Shared libraries `storytold/craft-libs` (read-only reference): `craft-docpath`, `craft-ui` and `craft-window` pinned to rev `92d392cff132eaf53e13afff77f38b5c11b73aa0`; **`craft-update` moved to rev `04aa1703b32d299e54f78fcde4182f2b393a9116`** (`Cargo.toml`); LightCraft's own formats are documented in this repo, so nothing outside it was needed.
- Evidence tiers: **implemented** (the code path exists and is reachable from UI/CLI/command), **partial/stub** (exists but visibly incomplete — what is missing is stated), **not implemented** (absent or explicitly out of scope).

**Uncertain / not verified in this pass**

- Runtime GUI behaviour, menus and dialogs were not launched: every GUI claim comes from the command registry, the control-protocol document, the parity checklist and the packaging metadata. The installed binary was inspected read-only (`--version`, `Info.plist`).
- The exact visual/colour fidelity of renders is not compared against Lightroom; the project itself says it is unmeasured (`docs/gaps.md:20`).
- HEIC availability depends on the build: official packaging passes `--features heif` and the installed binary has the symbols; a source build without the feature does not decode HEIC/HEIF.
- MCP tool totals are derived statically from `helper_tools` and the measured command counts, not captured from a running `tools/list`.
- Whether a specific raw variant decodes can only be settled file-by-file; the per-model table (`docs/raw/coverage.tsv`) is evidence, not a guarantee for every body that writes the container.
- Where project docs disagree with code at this tag, code was followed and the drift is listed above.