picturesq 0.0.1__tar.gz

picturesq-0.0.1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,20 @@
+name: Bug
+description: Something produces wrong output or crashes
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened vs expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Repro (command, config, camera/RAW type)
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment (`picturesq doctor --json`)

picturesq-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

picturesq-0.0.1/.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,32 @@
+name: Task
+description: A small (30–60 min) unit of work with clear acceptance criteria
+labels: ["task"]
+body:
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Why this task exists; links to the project plan section / ADR.
+    validations:
+      required: true
+  - type: textarea
+    id: ac
+    attributes:
+      label: Acceptance criteria
+      description: Checklist of observable outcomes.
+      value: |
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: test
+    attributes:
+      label: Test plan
+      description: How it is verified (unit test, golden image, contact sheet review, …).
+    validations:
+      required: true
+  - type: textarea
+    id: learn
+    attributes:
+      label: Learning note
+      description: Concept(s) involved, for docs/learning-log.md (optional).

picturesq-0.0.1/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+<!-- What and why. Closes #… -->
+
+## Test plan
+<!-- Commands run, tests added, contact sheet reviewed, … -->
+
+## Learning note
+<!-- New concept? Add an entry to docs/learning-log.md -->
+
+## Checklist
+- [ ] Tests added/updated (maths needs tests)
+- [ ] No new runtime dependency (or approved in the issue)
+- [ ] Docs/ADR updated if a decision changed

picturesq-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest

picturesq-0.0.1/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

picturesq-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+# Publishes to PyPI on version tags (trusted publishing; no API token).
+# The `pypi` environment only accepts `v*` tags. Bump `version` in pyproject.toml to match the tag.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv publish --trusted-publishing always

picturesq-0.0.1/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.benchmarks/
+.coverage
+htmlcov/
+
+# picturesq run artefacts (never commit outputs or caches)
+.picturesq/
+exports/
+
+# RAW and large image files: reference RAWs stay local
+reference/raw/
+reference/samples/
+*.DNG
+*.dng
+*.CR2
+*.CR3
+*.NEF
+*.ARW
+*.RAF
+*.RW2
+*.ORF
+*.tif
+*.tiff
+# Golden test images are small PNGs and ARE committed (tests/golden/)
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local agent settings
+.claude/settings.local.json

picturesq-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: [--maxkb=1024]

picturesq-0.0.1/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md — picturesq
+
+Instructions for coding agents (Claude Code, Codex, …) working on this repo.
+**Read this first, then `docs/project-plan.md` and `docs/glossary.md`. Don't re-explore the whole repo each session.**
+
+## What we're building
+`picturesq`: a CLI that turns a folder of RAW photos into consistently graded exports.
+Pipeline stages: **decode** (rawpy → scene-linear) → **normalise** (adaptive, per photo) → **grade** (look + adjustments + AgX display transform) → **export** (outputs, sRGB JPEG).
+The local web UI (`picturesq ui`) is the only way humans edit config. Agents edit the YAML or use the CLI.
+
+- Scope, decisions, milestones: `docs/project-plan.md`
+- Decision rationale: `docs/decisions/` (ADRs; add one when you make a significant decision)
+- Vocabulary (binding): `docs/glossary.md`
+- Concepts: `docs/learning-log.md`
+- Current milestone and tasks: [project board](https://github.com/users/eddiemg10/projects/1) / GitHub issues (the only tracker)
+
+## Hard rules
+- **Vocabulary:** use only glossary terms in code, CLI, config, docs, issues and UI text. British spelling everywhere (`colour`, `normalise`, `grey`), identifiers included. New term? Add it to the glossary in the same PR.
+- **Never modify originals.** Outputs go to `<dir>/.picturesq/`, `<dir>/exports/`, or `--out`.
+- **Precision:** float32 scene-linear internally (linear Rec.2020 primaries); 16-bit for intermediates on disk; 8-bit only at final export. Exposure/WB maths in linear only.
+- **Config over constants:** tunable values live in config models (`picturesq.config`), not inline in code.
+- **Pure image operations:** `f(image: float32 HxWx3, params) -> image`, with no IO inside `colour/`, `normalise/`, `grade/`.
+- **Memory:** never hold more than the needed full-res arrays; prefer in-place numpy (`out=`); interactive paths use proxies only.
+- **Reproducible:** same originals + config + version = same output. Seed anything random (grain).
+- **Dependencies:** ask before adding a runtime dependency (the list is in project plan §12).
+- **Tests:** maths is not merged without tests. Every PR states how it was tested.
+- **Small steps:** one issue per PR; propose a plan before large changes.
+- **Be honest about limits:** if something is a guess about the camera, a colour space or a LUT, say so and ask.
+
+## Working with the user (teaching protocol)
+The user is an experienced engineer but **new to image science**. Don't explain general programming. For each milestone:
+1. A short concept primer (2–4 concepts, plain language, one concrete example each).
+2. State trade-offs when choosing a library, colour space or algorithm.
+3. Show, don't just tell: small visual/numeric demos (before/after, histograms).
+4. Flag classic gotchas (wrong input space, 8-bit clipping, exposure in gamma space, …).
+5. Append to `docs/learning-log.md` (concept, one paragraph, why it mattered in code).
+6. Occasionally one quick understanding check at the end of a milestone; don't quiz constantly.
+
+## Commands
+```bash
+uv sync                      # install env
+uv run pytest                # tests
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run picturesq --help
+```
+
+## Repo map
+```
+src/picturesq/
+  cli/ config/ colour/ decode/ normalise/ grade/ export/ pipeline/ preview/ ui/
+tests/unit  tests/integration  tests/golden
+reference/   # reference set shot list + CC0 samples manifest (RAWs are git-ignored)
+scripts/     # dev utilities (fetch samples, compare, update goldens)
+skills/      # Claude skill shipped for end users' agents
+```
+
+## Git / PR conventions
+- Branch from `main`: `feat/…`, `fix/…`, `docs/…`, `chore/…`. Squash-merge via PR; `main` is protected and CI must be green.
+- PR title in conventional-commit style; body: summary, linked issue, test plan, learning note (if any).
+- Update `AGENTS.md` / the project plan / glossary / ADRs when decisions change.
+- The repo is **public**: never commit personal photos, absolute home paths or secrets.

picturesq-0.0.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

picturesq-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddie MG
+
+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.

picturesq-0.0.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: picturesq
+Version: 0.0.1
+Summary: Turn a folder of RAW photos into consistently graded exports, driven by looks and YAML.
+Project-URL: Homepage, https://github.com/eddiemg10/picturesq
+Project-URL: Repository, https://github.com/eddiemg10/picturesq
+Project-URL: Issues, https://github.com/eddiemg10/picturesq/issues
+Project-URL: Roadmap, https://github.com/users/eddiemg10/projects/1
+Author: Eddie MG
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# picturesq
+
+Turn a folder of RAW photos into consistently graded exports. No photo editor needed.
+
+```bash
+picturesq run ./lisbon    # decode → normalise → grade → export
+picturesq ui ./lisbon     # choose looks and set their intensity in a tiny local web UI
+```
+
+**Status:** pre-alpha (M0, setup). Plan: [`docs/project-plan.md`](https://github.com/eddiemg10/picturesq/blob/main/docs/project-plan.md) · Roadmap: [project board](https://github.com/users/eddiemg10/projects/1).
+
+- Any camera LibRaw supports; built and tested on DJI Osmo Pocket 4 DNGs
+- Runs on an 8 GB, CPU-only laptop (Linux/WSL2, Windows)
+- Looks in four categories (B/W · Cold · Warm · Cinematic), each with adjustable intensity
+- Config is YAML, written by the web UI and editable by coding agents
+
+## Development
+```bash
+uv sync
+uv run pytest
+```
+See [`AGENTS.md`](https://github.com/eddiemg10/picturesq/blob/main/AGENTS.md) for conventions and [`docs/glossary.md`](https://github.com/eddiemg10/picturesq/blob/main/docs/glossary.md) for vocabulary.
+
+## Releasing
+Releases are manual for now and triggered by a `v*` tag. Pushing the tag runs the [`Release`](https://github.com/eddiemg10/picturesq/blob/main/.github/workflows/release.yml) workflow, which builds with `uv build` and publishes to PyPI via trusted publishing (no API token).
+
+1. Set `version` in `pyproject.toml` (e.g. `0.0.1`) and merge it to `main` via PR.
+2. Tag the merge commit and push the tag:
+   ```bash
+   git tag v0.0.1
+   git push origin v0.0.1
+   ```
+3. Check the workflow run succeeded and the new version appears on PyPI.
+
+The tag must match `version` in `pyproject.toml`. The `pypi` environment only accepts `v*` tags.

picturesq-0.0.1/README.md

@@ -0,0 +1,35 @@
+# picturesq
+
+Turn a folder of RAW photos into consistently graded exports. No photo editor needed.
+
+```bash
+picturesq run ./lisbon    # decode → normalise → grade → export
+picturesq ui ./lisbon     # choose looks and set their intensity in a tiny local web UI
+```
+
+**Status:** pre-alpha (M0, setup). Plan: [`docs/project-plan.md`](https://github.com/eddiemg10/picturesq/blob/main/docs/project-plan.md) · Roadmap: [project board](https://github.com/users/eddiemg10/projects/1).
+
+- Any camera LibRaw supports; built and tested on DJI Osmo Pocket 4 DNGs
+- Runs on an 8 GB, CPU-only laptop (Linux/WSL2, Windows)
+- Looks in four categories (B/W · Cold · Warm · Cinematic), each with adjustable intensity
+- Config is YAML, written by the web UI and editable by coding agents
+
+## Development
+```bash
+uv sync
+uv run pytest
+```
+See [`AGENTS.md`](https://github.com/eddiemg10/picturesq/blob/main/AGENTS.md) for conventions and [`docs/glossary.md`](https://github.com/eddiemg10/picturesq/blob/main/docs/glossary.md) for vocabulary.
+
+## Releasing
+Releases are manual for now and triggered by a `v*` tag. Pushing the tag runs the [`Release`](https://github.com/eddiemg10/picturesq/blob/main/.github/workflows/release.yml) workflow, which builds with `uv build` and publishes to PyPI via trusted publishing (no API token).
+
+1. Set `version` in `pyproject.toml` (e.g. `0.0.1`) and merge it to `main` via PR.
+2. Tag the merge commit and push the tag:
+   ```bash
+   git tag v0.0.1
+   git push origin v0.0.1
+   ```
+3. Check the workflow run succeeded and the new version appears on PyPI.
+
+The tag must match `version` in `pyproject.toml`. The `pypi` environment only accepts `v*` tags.

picturesq-0.0.1/docs/decisions/0001-rawpy-decoder-no-darktable.md

@@ -0,0 +1,15 @@
+# ADR-0001: rawpy as the only decoder; no darktable dependency
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+The decode stage turns RAW originals into scene-linear images. Options: wrap darktable-cli or RawTherapee-cli (mature, excellent quality), or decode with rawpy (LibRaw) and own the rest of the pipeline.
+
+## Decision
+Use rawpy (LibRaw) as the only decoder. darktable is not a dependency. It is used only by hand during development, as a quality yardstick.
+
+## Consequences
+- + A pip-only install (~50 MB); works on Linux and Windows; 1000+ cameras.
+- + Everything after decode is our numpy code, so YAML maps directly to parameters and proxies render in milliseconds.
+- − darktable's XMP/styles store module params as versioned binary blobs, which can't be generated from YAML. Its per-render process startup also prevents live previews. Avoiding it removes both problems.
+- − Denoise and highlight reconstruction are now our responsibility. Chroma NR is in v1; luma NR gets re-evaluated in M2 on night shots.

picturesq-0.0.1/docs/decisions/0002-no-camera-conversion-lut.md

@@ -0,0 +1,14 @@
+# ADR-0002: No camera conversion LUT; use DNG colour matrices
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+The original brief assumed a "camera conversion LUT" stage. The DJI Osmo Pocket 4 shoots DNG stills; DJI's official LUTs convert **D-Log video** (log-encoded, wide gamut) to Rec.709.
+
+## Decision
+No camera LUT for stills. The DNG's embedded ColorMatrix/ForwardMatrix (applied by LibRaw) maps sensor RGB to a standard space. Proprietary RAWs use LibRaw's built-in per-camera matrices.
+
+## Consequences
+- + Removes the biggest risk in the brief (LUT input-space mismatch).
+- + Works for every LibRaw camera with no per-camera assets.
+- − Users who want "the DJI look" get it from a look, not a vendor LUT. A D-Log encode path could be added later if DJI publishes the D-Log M curve.

picturesq-0.0.1/docs/decisions/0003-agx-display-transform.md

@@ -0,0 +1,14 @@
+# ADR-0003: AgX-style display transform as the neutral base
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+Scene-linear data has a far larger range than a display. A display transform (tone mapping) compresses it, and its quality defines how highlights, skies and saturated colours look. Naive per-channel curves cause hue skews (blue skies to cyan, orange to yellow).
+
+## Decision
+Implement an AgX-style transform (inset primaries → log encode → sigmoid → outset), from the published maths, as the default neutral rendering. Parameters live in config.
+
+## Consequences
+- + Film-like highlight roll-off, natural path to white, good base for every look.
+- − We must implement and test it ourselves. Reference implementations (Blender, darktable, AgXc) go through a licence check before any code is ported. Default: implement from the maths.
+- Alternative kept in reserve: OpenDRT.

picturesq-0.0.1/docs/decisions/0004-yaml-machine-owned.md

@@ -0,0 +1,16 @@
+# ADR-0004: YAML config is machine-owned; web UI is the human editor
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+Config must be portable, reproducible and editable by coding agents. The user does not want to hand-edit YAML.
+
+## Decision
+- Pydantic models are the source of truth; YAML is their serialisation; `picturesq schema` exports JSON Schema.
+- Humans edit through the UI (`picturesq ui`); agents edit the file or use CLI commands.
+- Writes are atomic (temp file + rename); the UI watches the file and reloads on external change.
+- Comments in YAML are not preserved (nobody hand-writes them).
+
+## Consequences
+- + Simple serializer; strict validation; agents get a schema.
+- − Every user-tunable setting needs a UI control before humans can change it, so the UI scope must be managed.

picturesq-0.0.1/docs/decisions/0005-web-ui-no-build.md

@@ -0,0 +1,15 @@
+# ADR-0005: No-build web UI with Python-rendered proxies
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+We need a colour-accurate visual loop: photo × look grid and live controls, on an 8 GB CPU-only laptop, shipped via pip.
+
+## Decision
+- Starlette + uvicorn server, htmx + small vanilla JS, no Node build. Assets ship in the wheel.
+- On each control change, Python renders an ~800–1200 px proxy (target < 150 ms). There is one implementation of the image maths.
+- Terminal previews (sixel/kitty) are view-only and point to the UI.
+
+## Consequences
+- + Trivial install; previews are guaranteed to match exports (same code).
+- − Not "buttery" like GPU editors. A WebGL path (with parity tests) is the documented upgrade if latency disappoints.

picturesq-0.0.1/docs/decisions/0006-glossary-and-public-repo.md

@@ -0,0 +1,19 @@
+# ADR-0006: Binding glossary, British spelling, public repo
+
+**Status:** Accepted · 2026-10-11
+
+## Context
+Early docs mixed vocabulary (develop/decode, strength/intensity/amount, recipe/look, profile for three different things) and spelling (colour vs `color`). The repo was planned to stay private until v0.1.
+
+## Decision
+- `docs/glossary.md` is binding for code, CLI, config, docs, issues and UI text.
+- British spelling everywhere, identifiers included (`colour`, `normalise`, `grey`).
+- Pipeline stages: **decode → normalise → grade → export**. A **look** is the thing applied in the grade stage; **intensity** is its strength; **adjustments** are the universal controls; **outputs** are export targets; "profile" means only ICC profile.
+- Packages mirror the stages (`decode/`, `normalise/`, `grade/`, `export/`) around a shared `colour/` core. This also removes `picturesq.io`, which shadowed the stdlib name.
+- The repo is public from day one (MIT), with `main` protected.
+
+## Consequences
+- + One word per concept; agents and contributors can't drift.
+- + Free branch protection and required checks on a public repo.
+- − British spelling is unusual for a Python CLI, and contributors need the glossary rule spelled out (AGENTS.md does this).
+- − Public repo: personal RAWs must never be committed (git-ignored; goldens from CC0 samples only).

picturesq-0.0.1/docs/decisions/README.md

@@ -0,0 +1,13 @@
+# Architecture Decision Records
+
+Short records of significant decisions. Format: Context → Decision → Consequences.
+New ADRs get the next number; superseded ones are marked, not deleted.
+
+| ADR | Title | Status |
+|---|---|---|
+| [0001](0001-rawpy-decoder-no-darktable.md) | rawpy as the only decoder; no darktable dependency | Accepted |
+| [0002](0002-no-camera-conversion-lut.md) | No camera conversion LUT; use DNG colour matrices | Accepted |
+| [0003](0003-agx-display-transform.md) | AgX-style display transform as the neutral base | Accepted |
+| [0004](0004-yaml-machine-owned.md) | YAML config is machine-owned; web UI is the human editor | Accepted |
+| [0005](0005-web-ui-no-build.md) | No-build web UI (Starlette + htmx) with Python-rendered proxies | Accepted |
+| [0006](0006-glossary-and-public-repo.md) | Binding glossary, British spelling, public repo | Accepted |

picturesq-0.0.1/docs/glossary.md

@@ -0,0 +1,71 @@
+# Glossary
+
+**The single source of vocabulary for picturesq.** Code, CLI, config keys, docs, issues and UI labels use these words and only these words. If you need a new term, add it here in the same PR.
+
+## Language rules
+- **British spelling everywhere**: *colour, normalise, grey, behaviour, licence* (noun) / *license* (verb). This applies to identifiers too: `colour/`, `normalise()`, `grey_point`.
+  Exceptions: third-party APIs we call (`rawpy ... output_color`), CSS properties, and quoted product names.
+- Config keys and identifiers are `snake_case`; CLI flags are `--kebab-case`.
+- Prefer the industry term when one exists (sources: ACES/OpenColorIO, darktable, Lightroom, Capture One).
+
+## Things
+| Term | Meaning | Not to be called |
+|---|---|---|
+| **project** | A folder of RAW files plus its `picturesq.yaml`. The unit every command works on. | trip, batch, session, album |
+| **photo** | One input RAW file and everything derived from it. Used in the UI, CLI output and config (`photos:`). | image (in user-facing text), shot, frame, picture |
+| **image** | An in-memory pixel array (code only): `image: NDArray[float32]` of shape H×W×3. | photo (in code) |
+| **original** | The RAW file on disk. Never written. | source, input file |
+| **proxy** | A small cached scene-linear version of a photo (2048 px, float16) used for all interactive work. | thumbnail, preview (that's the rendered result) |
+| **preview** | A display-ready render of a proxy, shown in the terminal or UI. | proxy, thumbnail |
+| **contact sheet** | A grid of previews (photos × looks, or photos only). | gallery, mosaic |
+| **look** | A named, reusable creative grade, e.g. *cold/nordic*. Defined by a **look file**. | style, preset, filter, recipe, profile |
+| **look file** | YAML defining a look: metadata, **parameters**, and a list of **operations**, which may include a `lut` operation referencing a `.cube`. | recipe |
+| **category** | A grouping of looks: `bw`, `cold`, `warm`, `cinematic`. | family, collection, group |
+| **look library** | All available looks: built-in + user-installed. | catalogue, pack |
+| **LUT** | A 3D lookup table file (`.cube`). Always used *through* a look file that declares its **input space**. | filter, profile |
+| **operation (op)** | One step inside a look file, e.g. `contrast`, `split_tone`, `lut`. | module, node, tool, effect |
+| **parameter** | A named, adjustable value a look exposes to the UI (e.g. *shadow tint*). | knob, setting, control |
+| **intensity** | How strongly a look applies: 0 % = neutral render, 100 % = as designed, up to 150 %. The only word for this. | strength, amount, opacity, mix |
+| **amount** | The magnitude parameter *inside* an operation (`contrast.amount`). Never used for looks. | strength |
+| **adjustments** | The fixed set of global controls available for every look: exposure, warmth, tint, contrast, saturation, vibrance. | tweaks, fine-tune layer, basics |
+| **override** | A per-photo value that replaces the project default (look, intensity, normalisation values). | exception, manual edit |
+| **output** | A named export target in config, e.g. `web`, `archive` (size, quality, sharpening). | export profile, preset, recipe |
+| **ICC profile** | The colour profile embedded in an exported file. The only use of "profile". | — |
+| **stats** | Per-photo measurements (luminance percentiles, clipping, …), stored as JSON. | metrics, analysis |
+| **flag** | A per-photo warning raised by a stage (e.g. `exposure_clamped`, `wb_disagreement`). | warning, alert, issue |
+| **outlier** | A photo whose stats fall outside configured ranges; one kind of flag. | — |
+| **reference set** | The user's local Pocket 4 RAWs (scenarios R01–R10) used for acceptance. | test images |
+| **samples** | CC0 RAWs from raw.pixls.us used in CI. | fixtures (fixture = pytest) |
+| **golden** | A stored expected output used by a regression test. | snapshot (that's for text/JSON) |
+
+## Pipeline
+| Term | Meaning | Not to be called |
+|---|---|---|
+| **pipeline** | The full chain: decode → normalise → grade → export. | workflow, process |
+| **stage** | One of the four pipeline steps below. | phase (that's project management), step |
+| **decode** | Stage 1: original → scene-linear image in the working space (rawpy/LibRaw), plus proxy. | develop, import, convert, ingest |
+| **normalise** | Stage 2: adaptive per-photo correction to a common baseline (exposure, WB check, chroma NR). | auto, correct, balance |
+| **grade** | Stage 3: apply the photo's look + adjustments, then the display transform. The *act*; a look is the *thing*. | style, edit, look (as a verb) |
+| **export** | Stage 4: encode, resize and write each enabled output with sidecar. | render, save |
+| **render** | Producing pixels from a proxy or original through stages 2–3 (used by preview and export). | process |
+
+## Colour science
+| Term | Meaning |
+|---|---|
+| **scene-linear** | Pixel values proportional to light in the scene. All maths before the display transform happens here. |
+| **working space** | The colour space of scene-linear images inside picturesq: linear Rec.2020 primaries, float32. |
+| **display transform** | Maps scene-linear to display range with highlight roll-off. Ours is AgX-style. (OCIO: *view transform*; ACES: *output transform*.) |
+| **display-referred** | Values after the display transform (0–1, encoded for a screen). LUT operations usually run here. |
+| **input space** | The colour space + transfer curve a LUT expects as input (e.g. `srgb`, `rec709`). |
+| **transfer function** | The curve between linear and encoded values (sRGB curve, log). "Gamma" only in explanations. |
+| **key** | Overall brightness character of a scene: `low_key`, `normal`, `high_key`. |
+| **EV / stop** | A doubling or halving of light. `exposure_ev: +1` = ×2 in scene-linear. |
+| **white balance (WB)** | Per-channel gains making neutral objects neutral; **as-shot** = camera's recorded values. |
+| **chroma NR / luma NR** | Noise reduction on colour / brightness detail. |
+
+## Project management
+| Term | Meaning |
+|---|---|
+| **milestone** | M0–M5 (and later). "Phase" is used only in the original brief. |
+| **task** | One GitHub issue, 30–60 min, with acceptance criteria and a test plan. |
+| **ADR** | Architecture decision record in `docs/decisions/`. |

picturesq-0.0.1/docs/learning-log.md

@@ -0,0 +1,30 @@
+# Learning log
+
+Short entries: **concept**, a one-paragraph explanation, and **why it mattered in the code**.
+Agents append here as phases introduce new concepts.
+
+---
+
+## 2026-10-11 · RAW files and decoding
+A RAW file is not an image. It holds one brightness number per sensor pixel, where each pixel sits under a red, green or blue filter in a checkerboard (Bayer mosaic), plus metadata on how to interpret them. A **decoder** subtracts the sensor's black level, scales to the white level, **demosaics** (estimates the two missing colours per pixel from neighbours), applies white-balance multipliers, and converts the camera's colour primaries to a standard space using a **colour matrix**. The result is a linear RGB image.
+**Why it mattered:** this is the only camera-specific step. After decoding, everything is camera-agnostic, which is why picturesq supports any LibRaw camera (ADR-0001).
+
+## 2026-10-11 · D-Log LUTs don't apply to DNG
+DJI's "conversion LUTs" turn D-Log *video* into normal-looking Rec.709. D-Log is a log curve plus a wide gamut that the camera bakes into video files. A DNG still is linear sensor data with no log encoding. Applying a D-Log LUT to it means feeding the LUT inputs it was never designed for, and the colours and contrast come out wrong. A LUT only gives correct results when the input is in exactly the colour space and transfer curve it was built for.
+**Why it mattered:** we dropped the camera-LUT stage entirely (ADR-0002), and every user `.cube` file must declare its input space.
+
+## 2026-10-11 · Linear vs display encoding
+In **scene-linear** data, a value is proportional to light: double the light, double the number. Displays and JPEGs use a **non-linear encoding** (sRGB "gamma"), which spends more code values on shadows because human vision is more sensitive there. Maths that mimics physics (exposure, white balance, blending light) must happen in linear. Doing it on gamma-encoded values distorts contrast and colour, a classic mistake.
+**Why it mattered:** the whole pipeline works in float32 linear and converts to sRGB only at export.
+
+## 2026-10-11 · Display transforms (tone mapping)
+A sunny scene can span 15+ stops; a screen shows about 6–8. A **display transform** compresses scene-linear values into the 0–1 display range: it decides how highlights roll off, how contrast feels, and how bright saturated colours fade toward white. Naive per-channel curves skew hues (skies turn cyan, sunsets yellow). AgX and OpenDRT are open designs that avoid this.
+**Why it mattered:** AgX is our neutral base (ADR-0003); every look builds on it.
+
+## 2026-10-11 · The memory maths of a 33 MP photo
+7680 × 4320 ≈ 33 M pixels. As float32 RGB that's 33M × 3 × 4 bytes ≈ **400 MB per array**. A numpy expression like `a * b + c` allocates temporaries, so a naive chain can peak at 1–2 GB per image. On an 8 GB laptop, memory, not CPU, limits how many photos run in parallel. Per-pixel ops on a 1000 px proxy (~0.5 MP) are ~60× cheaper, which is why interactive previews always use proxies.
+**Why it mattered:** proxy-first design, in-place ops, memory-capped worker pool, and memory budget tests (project plan §5).
+
+## 2026-10-11 · Proxies
+A **proxy** is a small (2048 px long edge), cached, **scene-linear** float16 copy of a photo; the term comes from video editing. It has ~14× fewer pixels than a 33 MP original, so operations take milliseconds. It's scene-linear rather than a JPEG thumbnail, so normalise and grade behave exactly as they will on the original: what you preview is what you export. Float16 halves storage versus float32 while still holding values above 1.0 (bright skies), which 8-bit can't. The cache key hashes the original, the decode config and the version, so a proxy is never stale. A **preview** is the display-ready render *of* a proxy.
+**Why it mattered:** every interactive feature (contact sheets, the UI, normalise stats) uses proxies; only export touches originals. This is what makes an 8 GB, CPU-only laptop enough.