# silverbaths

> silverbaths grades photos, camera raws (ARW, CR3, CR2, NEF, RAF, RW2, ORF, DNG), and videos with declarative TOML film looks and subject-aware crops. Written in Rust, it ships as a CLI (`silverbaths`), a Python package (`import silverbaths`), a Model Context Protocol server (`silverbaths mcp`), and a browser WebAssembly build. Everything is built from six primitives (`open`, `measure`, `resolve`, `render`, `encode`, `catalog`) over a single deterministic data type, the recipe.

When stdout is not a terminal (or with `--format json`), the CLI emits newline-delimited JSON (NDJSON) events and structured error objects with stable `code` and actionable `hint` fields. Agents should follow the loop: `open` -> `measure` -> `render` (or `sheet`) -> visually inspect -> adjust recipe -> `encode`.

## Documentation

- [README](README.md): Overview, before/after showcase, installation across CLI/Python/MCP/browser, six primitives summary, and benchmarks.
- [Documentation Index](docs/index.md): Map of all documentation pages, the six primitives, and supported media formats.
- [Quickstart](docs/quickstart.md): Install silverbaths and run your first contact sheet, measurement, photo grade, camera raw grade, and video grade.
- [CLI Reference](docs/cli.md): Every command (`grade`, `render`, `resolve`, `measure`, `run`, `sheet`, `looks`, `ops`, `schema`, `lut`, `skills`, `mcp`), flag, exit code, and real JSON output examples.
- [Python Reference](docs/python.md): Python bindings (`Source` primitives, immutable `Photo` builder, batch `grade`, `preview`, `inspect`, `lut`, NumPy conversion, and `SilverbathsError`).
- [MCP Server Reference](docs/mcp.md): Model Context Protocol server setup for Claude Code, Codex, Cursor, and Claude Desktop, tool schemas, source cache behavior, and a multi-turn agent session trace.
- [Recipes, Crops, and Plans](docs/recipes.md): Recipe schema (`schema = 2`), crop specifications (`RATIO`, `RATIO@smart`, `RATIO@L,T,R,B`), `resolve` idempotence, `grain_unit` resolution independence, `.recipe.json` sidecars, and `plan.toml` batch plans.
- [Looks Catalog and Authoring Guide](docs/looks.md): All 24 built-in CC0 film looks, complete reference for all 25 pixel and spatial operations, pipeline op ordering, and how to write and validate custom `.toml` looks.
- [Video Grading](docs/video.md): Video pipeline via `ffmpeg`, multi-frame auto-exposure calibration, cached grain texture bank, codecs (`hevc`, `h264`, `prores`), Sony S-Log3 `log_decode`, and `.cube` 3D LUT export.
- [Guide for AI Agents](docs/agents.md): How coding agents should use silverbaths: installing skills (`silverbaths skills`), the `measure -> render -> look -> adjust -> encode` loop, error codes, and example prompts.
- [FAQ](docs/faq.md): Frequently asked questions on raw development vs Lightroom, RAW+JPEG deduplication, EXIF/ICC handling, LUT limitations, and licensing.

## Design and Showcase

- [Primitives Design](docs/design/primitives.md): Architectural notes on the six primitives and why recipes are data.
- [Showcase Commands and Sources](docs/showcase/SHOWCASE.md): Exact commands, crop coordinates, and CC0 attributions for every showcase before/after image and video.
- [Contributor Guide for Coding Agents](AGENTS.md): Repository layout, build/test commands, and architectural invariants for agents modifying silverbaths.
- [Grade Photos Skill](skills/grade-photos/SKILL.md): Agent skill instructions for grading photos and camera raws with the `silverbaths` CLI.