zinegen 0.1.0__tar.gz

zinegen-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "longfin",
+  "description": "Plugins by longfin",
+  "owner": { "name": "Swen Mun", "url": "https://github.com/longfin" },
+  "plugins": [
+    {
+      "name": "zinegen",
+      "source": "./",
+      "description": "Typeset a photobook or zine from a Lightroom album into a print-ready PDF/X (skill + MCP server)",
+      "category": "productivity"
+    }
+  ]
+}

zinegen-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "zinegen",
+  "displayName": "zinegen",
+  "version": "0.1.0",
+  "description": "Typeset a photobook or zine from a Lightroom album into a print-ready PDF/X (skill + MCP server)",
+  "author": { "name": "Swen Mun", "url": "https://github.com/longfin" },
+  "homepage": "https://github.com/longfin/zinegen#readme",
+  "repository": "https://github.com/longfin/zinegen",
+  "license": "MIT",
+  "keywords": ["lightroom", "photobook", "zine", "pdf/x", "prepress", "typesetting", "mcp"]
+}

zinegen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: System libraries (pango for WeasyPrint, ghostscript for proofs, fonts)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libpango-1.0-0 libpangoft2-1.0-0 ghostscript fontconfig fonts-dejavu-core fonts-nanum
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv && uv pip install -e ".[dev]" ruff
+      - run: .venv/bin/ruff check .
+      - run: .venv/bin/python -m pytest -q
+      - name: Package builds and ships its data files
+        run: |
+          uv build
+          unzip -l dist/*.whl | grep -E "schema/book.schema.json|templates/book.html.j2|templates/sRGB2014.icc"

zinegen-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing, no token stored anywhere
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv publish

zinegen-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.zinegen-cache/
+books/
+*.pdf
+*.png
+!docs/**/*.png
+.DS_Store

zinegen-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "zinegen": {
+      "command": "zinegen",
+      "args": ["mcp"]
+    }
+  }
+}

zinegen-0.1.0/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository (Claude Code, Codex and others).
+
+## What this project is
+
+`zinegen` turns a Lightroom (cloud) album into a print-ready PDF/X. The agent is the typesetter: it edits
+`books/<name>/book.yaml`, renders, looks at the spread proofs, and iterates. The human curates photos in
+Lightroom and reviews proofs. See `README.md` for the pipeline and `skills/zinegen/SKILL.md` for the
+typesetting workflow and taste rules.
+
+## Layout
+
+```
+src/zinegen/
+  lr/compat.py   Lightroom helpers missing from lr-mcp (album order, captions, cached renditions)
+  presets.py     trim presets, binding rules, spine width
+  spec.py        book.yaml loading, JSON Schema validation, skeleton drafting
+  schema/        book.schema.json (book.yaml format, version 1)
+  issues.py      issue codes shared by report.json and check.json
+  layout.py      page geometry in mm, dpi/gutter report
+  render.py      HTML -> WeasyPrint PDF/X, pikepdf post-processing
+  color.py       ICC conversion (Pillow + LittleCMS), gamut check
+  proof.py       Ghostscript page PNGs -> spread PNGs
+  check.py       structural PDF/X self-check
+  cli.py         `zinegen` subcommands
+  server.py      MCP server (`zinegen mcp`), tools prefixed `zg_`
+  templates/     book.html.j2, fallback sRGB2014.icc
+skills/zinegen/  agent skill
+docs/            research, probe results, design (Korean)
+probe/           reproducible experiments (not part of the package)
+examples/        annotated book.example.yaml
+books/           your books (git-ignored: they reference a private catalog)
+tests/           pytest (no network)
+```
+
+## Setup and commands
+
+```bash
+uv venv && . .venv/bin/activate && uv pip install -e ".[dev]"
+zinegen doctor                      # pango, ghostscript, ICC profiles, Lightroom sign-in
+python -m pytest -q                 # unit tests (spec, layout, presets)
+zinegen build books/<name>          # end-to-end on a real album (needs Lightroom sign-in); books/ is git-ignored
+```
+
+macOS: WeasyPrint needs `brew install pango`; `render.py` sets `DYLD_FALLBACK_LIBRARY_PATH` to the Homebrew
+lib dir automatically. Ghostscript (`gs`) is required for proofs.
+
+## Rules
+
+- **Frozen formats** (see `docs/03-schemas.md`): `book.yaml` (`version: 1`, `schema/book.schema.json`),
+  `photos.json`, `out/report.json`, `out/check.json`. Add fields freely; renaming or removing one, or changing
+  a meaning, bumps that format's version and needs a migration note in the doc. New issue codes go in `issues.py`.
+
+- **`book.yaml` is the only editable artefact of a book.** Never patch `out/interior.pdf` or `interior.html`.
+  If the renderer cannot express something, extend `layout.py`/`spec.py` and add a template.
+- **Keep geometry explicit.** All image placement is computed in `layout.py` in millimetres so that dpi and
+  gutter crossing can be reported. Do not move placement into CSS (`object-fit` etc.).
+- **PDF/X invariants** (checked by `check.py`): an output intent with an embedded profile, TrimBox and BleedBox
+  on every page, CMYK/Gray images only for X-1a, ICC-tagged RGB for X-4, no transparency on X-1a, all fonts
+  embedded. Any change to `render.py` or the template must keep `zinegen check` green on both standards.
+- **Never recompress a source JPEG twice.** X-1a converts P3 -> CMYK once (cached in `cache/cmyk/`); X-4 embeds
+  the original bytes. Keep `optimize_images=False` and the DCT passthrough.
+- **Lightroom access is read-only** and goes through `lr_mcp.client`. Do not add write calls. Do not print or
+  commit anything from `~/.config/lr-mcp/` (tokens, client secret).
+- **ICC profiles and Apple/Adobe fonts are not redistributable.** Only `sRGB2014.icc` (from WeasyPrint) is bundled.
+  Resolve press profiles at run time (`color.find_profile`) and prefer OFL fonts (Nanum, Noto, Pretendard) as defaults.
+- Functions that lr-mcp may adopt later live in `lr/compat.py` and must stay importable with only `lr_mcp.client`
+  as a dependency, so they can be upstreamed unchanged (lr-mcp issues #9, #10, #11).
+- Tests must not touch the network. `tests/test_render.py` renders synthetic JPEGs through the real pipeline
+  (PDF/X-4 with an RGB output intent); anything that needs Lightroom or a CMYK profile is a manual `build` run.
+- **One version, three places.** `pyproject.toml`, `.claude-plugin/plugin.json` and `metadata.version` in
+  `skills/zinegen/SKILL.md` must agree (`tests/test_release.py` checks). To release: bump all three, date the
+  CHANGELOG entry, commit, `git tag vX.Y.Z && git push --tags`, then `uv build` and `gh release create vX.Y.Z dist/*`. Publishing the GitHub release triggers
+  `publish.yml`, which uploads to PyPI through trusted publishing (no token in the repo or on any machine).
+  The repo root is both the plugin and a one-entry marketplace (`.claude-plugin/marketplace.json`, `.mcp.json`);
+  `claude plugin validate .` must pass.
+- Lint with `ruff check .` (config in pyproject); CI runs ruff, pytest and a wheel build on Ubuntu.
+- Commit messages: short imperative subject, body explaining why. Do not commit `books/*/cache`, `out`, `proof`,
+  PDFs or PNGs (see `.gitignore`).
+
+## When typesetting a book (not developing the tool)
+
+Load the skill in `skills/zinegen/SKILL.md` and follow it. In short: pick the album, draft with `zg_init_book`,
+edit `book.yaml`, `zg_fetch` → `zg_render` → `zg_proof`, critique every spread, iterate two or three times,
+finish with `zg_check` green and report warnings (low dpi, gutter crossing, padded pages) to the user.
+
+## Open work
+
+- Cover PDF (spine from `zinegen spine`, wrap-around layout, separate PDF/X).
+- Local review GUI: spread viewer with comments the agent can read; no editing.
+- Upstream `lr/compat.py` to lr-mcp.
+- Real preflight comparison (Acrobat Pro / callas) and fixes for anything it flags.

zinegen-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-11-08
+
+First public version.
+
+- `book.yaml` spec (format version 1, JSON Schema) with trim presets, four bindings and nine page templates.
+- Lightroom album import through lr-mcp: album order, captions, cropped size, cached full-size renditions.
+- PDF/X-1a (CMYK via LittleCMS) and PDF/X-4 (ICC-tagged RGB passthrough) output with WeasyPrint.
+- Spread proofs (Ghostscript) and a structural PDF/X self-check (pikepdf) with coded issues.
+- CLI, MCP server (`zg_*` tools) and an agent skill for Claude Code / Codex.
+- Installable as a Claude Code plugin (`/plugin install zinegen --marketplace longfin/zinegen`) and through
+  `npx skills add longfin/zinegen`.

zinegen-0.1.0/LICENSE

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

zinegen-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: zinegen
+Version: 0.1.0
+Summary: Agent-driven photobook typesetting: Lightroom album -> print-ready PDF/X
+Project-URL: Homepage, https://github.com/longfin/zinegen
+Project-URL: Issues, https://github.com/longfin/zinegen/issues
+Project-URL: Changelog, https://github.com/longfin/zinegen/blob/main/CHANGELOG.md
+Author: Swen Mun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,lightroom,mcp,pdf/x,photobook,prepress,weasyprint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Printing
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: lr-mcp>=0.2
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pikepdf>=9
+Requires-Dist: pillow>=11
+Requires-Dist: pyyaml>=6
+Requires-Dist: weasyprint>=66
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zinegen
+
+[![ci](https://github.com/longfin/zinegen/actions/workflows/ci.yml/badge.svg)](https://github.com/longfin/zinegen/actions/workflows/ci.yml)
+
+Agent-driven photobook typesetting: a Lightroom (cloud) album goes in, a print-ready **PDF/X** comes out.
+One Python package provides a CLI, an MCP server and an agent skill, so Claude Code, Codex or any other
+MCP-capable agent can act as the typesetter while you curate in Lightroom and review proofs.
+
+No Adobe desktop app is required. Photos come from the Lightroom Partner API through
+[lr-mcp](https://github.com/longfin/lr-mcp) as full-size JPEG renditions (Display P3, quality 92, 4:4:4),
+which is enough for offset printing; see `docs/01-probe-results.md` for the measurements.
+
+```
+Lightroom album ──fetch──▶ cache/<asset>.jpg ──┐
+book.yaml (edited by the agent / you) ─────────┴──render──▶ out/interior.pdf  (PDF/X-1a or PDF/X-4)
+                                                           ──proof───▶ proof/spread-NN.png
+                                                           ──check───▶ out/check.json
+```
+
+## What it does
+
+- `book.yaml` is the single source of truth: trim size (presets or custom mm), bleed, binding, margins, fonts,
+  output standard, ICC profile and the page sequence with one of nine templates per page
+  (`title`, `blank`, `text`, `colophon`, `full-bleed`, `margin`, `pair`, `spread-full`, `spread-margin`).
+- Page geometry is computed in millimetres, not left to CSS: every image placement reports its effective dpi
+  and whether it crosses the gutter. Spreads are forced to start on a left-hand page; the page count is padded
+  to the binding's multiple.
+- **PDF/X-1a** (offset, 국내 인쇄소): images are converted to CMYK with LittleCMS (perceptual intent, black point
+  compensation) and embedded without a second JPEG generation; text and rules are DeviceCMYK.
+- **PDF/X-4** (POD, Blurb-style services): the original P3 JPEGs are embedded losslessly and tagged with their ICC
+  profile; the output intent is still a CMYK press profile.
+- Proof PNGs are composed as spreads so an agent can look at them (`zg_proof` returns images over MCP).
+- A structural self-check (output intent, trim/bleed boxes, colour spaces, transparency, font embedding,
+  resolution) runs with pikepdf. It is not a replacement for Acrobat/callas preflight.
+
+**New here?** Follow [docs/getting-started.md](docs/getting-started.md): it takes a Claude Code or Codex
+subscriber from zero to a first PDF, and the agent can run it for you.
+
+## Install
+
+```bash
+brew install pango ghostscript            # WeasyPrint runtime, proof rendering (macOS; apt equivalents on Linux)
+uv tool install lr-mcp && lr-mcp doctor   # Lightroom credentials and sign-in: follow the lr-mcp README
+uv tool install zinegen                   # from PyPI; for development: git clone, uv venv && uv pip install -e ".[dev]"
+zinegen doctor
+```
+
+CMYK ICC profiles cannot be redistributed, so zinegen looks for the usual ones on the machine
+(Adobe installs, ColorSync) and otherwise takes a path in `output.icc`. ISO Coated v2 / PSO Coated v3
+can be downloaded free from [ECI](https://www.eci.org/).
+
+## Register with an agent
+
+`zinegen` must be on `PATH` first (`uv tool install`, above). Then pick one:
+
+```bash
+# Claude Code: plugin install adds the skill and registers the `zinegen` MCP server in one step
+/plugin install zinegen --marketplace longfin/zinegen
+
+# Any agent that reads SKILL.md folders (Claude Code, Codex, Cursor, ...): skill only
+npx skills add longfin/zinegen
+codex mcp add zinegen -- "$(which zinegen)" mcp          # Codex still needs the MCP server registered
+```
+
+Without either tool, clone the repo and copy `skills/zinegen` into `~/.claude/skills/` or `~/.codex/skills/` and register the server
+with `claude mcp add zinegen -s user -- "$(which zinegen)" mcp`.
+
+Both agents also need the `lightroom` MCP server from lr-mcp for browsing and rating photos.
+
+## Usage
+
+```bash
+zinegen albums autumn                                   # find the album id
+zinegen init --album <album id> --dir books/autumn       # draft book.yaml + photos.json
+$EDITOR books/autumn/book.yaml                           # sequence, templates, captions
+zinegen build books/autumn                               # fetch + render + proof + check
+zinegen spine --pages 48 --caliper 110                   # spine width from page count and paper caliper (µm)
+zinegen presets                                          # trim presets and binding rules
+```
+
+A complete annotated spec is in [`examples/book.example.yaml`](examples/book.example.yaml).
+
+MCP tools: `zg_spec_help`, `zg_list_albums`, `zg_album_photos`, `zg_init_book`, `zg_fetch`, `zg_render`,
+`zg_proof`, `zg_check`, `zg_spine`.
+
+## Book directory
+
+```
+books/<name>/
+  book.yaml      the spec (the only thing to edit)
+  photos.json    photo metadata from Lightroom
+  cache/         renditions, index.json, cmyk/ conversions   (ignored by git)
+  out/           interior.pdf, interior.html, report.json, check.json
+  proof/         page-NNN.png, spread-NN.png
+```
+
+## Docs
+
+- `docs/getting-started.md` — zero-to-first-book guide for Claude Code / Codex users
+- `AGENTS.md` — how an agent should work in this repo and with the tool
+- `docs/00-research.md` — initial research (Korean)
+- `docs/01-probe-results.md` — measured rendition quality and WeasyPrint PDF/X results (Korean)
+- `docs/02-design.md` — design notes (Korean)
+- `skills/zinegen/SKILL.md` — the agent skill
+
+## Status
+
+Alpha (0.1.0). Interior PDF for a single album, A5 perfect binding verified end to end against a real album;
+the PDF/X output passes the built-in structural check but has not yet been through Acrobat/callas preflight.
+Not yet: cover PDF with spine, review GUI, upstreaming the Lightroom helpers to lr-mcp (issues #9–#11 there).
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. Third-party material and external tools are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+This project is not affiliated with, endorsed by, or sponsored by Adobe. Adobe, Lightroom and InDesign are
+either registered trademarks or trademarks of Adobe in the United States and/or other countries.

zinegen-0.1.0/README.md

@@ -0,0 +1,118 @@
+# zinegen
+
+[![ci](https://github.com/longfin/zinegen/actions/workflows/ci.yml/badge.svg)](https://github.com/longfin/zinegen/actions/workflows/ci.yml)
+
+Agent-driven photobook typesetting: a Lightroom (cloud) album goes in, a print-ready **PDF/X** comes out.
+One Python package provides a CLI, an MCP server and an agent skill, so Claude Code, Codex or any other
+MCP-capable agent can act as the typesetter while you curate in Lightroom and review proofs.
+
+No Adobe desktop app is required. Photos come from the Lightroom Partner API through
+[lr-mcp](https://github.com/longfin/lr-mcp) as full-size JPEG renditions (Display P3, quality 92, 4:4:4),
+which is enough for offset printing; see `docs/01-probe-results.md` for the measurements.
+
+```
+Lightroom album ──fetch──▶ cache/<asset>.jpg ──┐
+book.yaml (edited by the agent / you) ─────────┴──render──▶ out/interior.pdf  (PDF/X-1a or PDF/X-4)
+                                                           ──proof───▶ proof/spread-NN.png
+                                                           ──check───▶ out/check.json
+```
+
+## What it does
+
+- `book.yaml` is the single source of truth: trim size (presets or custom mm), bleed, binding, margins, fonts,
+  output standard, ICC profile and the page sequence with one of nine templates per page
+  (`title`, `blank`, `text`, `colophon`, `full-bleed`, `margin`, `pair`, `spread-full`, `spread-margin`).
+- Page geometry is computed in millimetres, not left to CSS: every image placement reports its effective dpi
+  and whether it crosses the gutter. Spreads are forced to start on a left-hand page; the page count is padded
+  to the binding's multiple.
+- **PDF/X-1a** (offset, 국내 인쇄소): images are converted to CMYK with LittleCMS (perceptual intent, black point
+  compensation) and embedded without a second JPEG generation; text and rules are DeviceCMYK.
+- **PDF/X-4** (POD, Blurb-style services): the original P3 JPEGs are embedded losslessly and tagged with their ICC
+  profile; the output intent is still a CMYK press profile.
+- Proof PNGs are composed as spreads so an agent can look at them (`zg_proof` returns images over MCP).
+- A structural self-check (output intent, trim/bleed boxes, colour spaces, transparency, font embedding,
+  resolution) runs with pikepdf. It is not a replacement for Acrobat/callas preflight.
+
+**New here?** Follow [docs/getting-started.md](docs/getting-started.md): it takes a Claude Code or Codex
+subscriber from zero to a first PDF, and the agent can run it for you.
+
+## Install
+
+```bash
+brew install pango ghostscript            # WeasyPrint runtime, proof rendering (macOS; apt equivalents on Linux)
+uv tool install lr-mcp && lr-mcp doctor   # Lightroom credentials and sign-in: follow the lr-mcp README
+uv tool install zinegen                   # from PyPI; for development: git clone, uv venv && uv pip install -e ".[dev]"
+zinegen doctor
+```
+
+CMYK ICC profiles cannot be redistributed, so zinegen looks for the usual ones on the machine
+(Adobe installs, ColorSync) and otherwise takes a path in `output.icc`. ISO Coated v2 / PSO Coated v3
+can be downloaded free from [ECI](https://www.eci.org/).
+
+## Register with an agent
+
+`zinegen` must be on `PATH` first (`uv tool install`, above). Then pick one:
+
+```bash
+# Claude Code: plugin install adds the skill and registers the `zinegen` MCP server in one step
+/plugin install zinegen --marketplace longfin/zinegen
+
+# Any agent that reads SKILL.md folders (Claude Code, Codex, Cursor, ...): skill only
+npx skills add longfin/zinegen
+codex mcp add zinegen -- "$(which zinegen)" mcp          # Codex still needs the MCP server registered
+```
+
+Without either tool, clone the repo and copy `skills/zinegen` into `~/.claude/skills/` or `~/.codex/skills/` and register the server
+with `claude mcp add zinegen -s user -- "$(which zinegen)" mcp`.
+
+Both agents also need the `lightroom` MCP server from lr-mcp for browsing and rating photos.
+
+## Usage
+
+```bash
+zinegen albums autumn                                   # find the album id
+zinegen init --album <album id> --dir books/autumn       # draft book.yaml + photos.json
+$EDITOR books/autumn/book.yaml                           # sequence, templates, captions
+zinegen build books/autumn                               # fetch + render + proof + check
+zinegen spine --pages 48 --caliper 110                   # spine width from page count and paper caliper (µm)
+zinegen presets                                          # trim presets and binding rules
+```
+
+A complete annotated spec is in [`examples/book.example.yaml`](examples/book.example.yaml).
+
+MCP tools: `zg_spec_help`, `zg_list_albums`, `zg_album_photos`, `zg_init_book`, `zg_fetch`, `zg_render`,
+`zg_proof`, `zg_check`, `zg_spine`.
+
+## Book directory
+
+```
+books/<name>/
+  book.yaml      the spec (the only thing to edit)
+  photos.json    photo metadata from Lightroom
+  cache/         renditions, index.json, cmyk/ conversions   (ignored by git)
+  out/           interior.pdf, interior.html, report.json, check.json
+  proof/         page-NNN.png, spread-NN.png
+```
+
+## Docs
+
+- `docs/getting-started.md` — zero-to-first-book guide for Claude Code / Codex users
+- `AGENTS.md` — how an agent should work in this repo and with the tool
+- `docs/00-research.md` — initial research (Korean)
+- `docs/01-probe-results.md` — measured rendition quality and WeasyPrint PDF/X results (Korean)
+- `docs/02-design.md` — design notes (Korean)
+- `skills/zinegen/SKILL.md` — the agent skill
+
+## Status
+
+Alpha (0.1.0). Interior PDF for a single album, A5 perfect binding verified end to end against a real album;
+the PDF/X output passes the built-in structural check but has not yet been through Acrobat/callas preflight.
+Not yet: cover PDF with spine, review GUI, upstreaming the Lightroom helpers to lr-mcp (issues #9–#11 there).
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. Third-party material and external tools are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+This project is not affiliated with, endorsed by, or sponsored by Adobe. Adobe, Lightroom and InDesign are
+either registered trademarks or trademarks of Adobe in the United States and/or other countries.

zinegen-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+## Bundled
+
+**`src/zinegen/templates/sRGB2014.icc`** — Copyright International Color Consortium, 2015.
+Obtained from the WeasyPrint distribution (BSD-3-Clause), which bundles the ICC's reference sRGB profile.
+The ICC makes this profile available under its standard terms: it may be copied, distributed, embedded, made,
+used and sold without restriction; altered versions must have the original identification and copyright
+information removed and must not be misrepresented as the original profile. zinegen ships it unaltered and
+uses it only as a fallback RGB tag for untagged images and as an RGB output intent in tests.
+
+## Not bundled, resolved on the user's machine
+
+- **CMYK press profiles** (Japan Color 2001 Coated, Coated FOGRA39, U.S. Web Coated (SWOP) and others) are
+  looked up in Adobe/ColorSync/`/usr/share/color/icc` directories or taken from `output.icc`. They are never
+  copied into this repository or the package; their own licenses apply. ECI profiles (eci.org) are a free
+  alternative.
+- **Fonts** are resolved through fontconfig and subset-embedded into the PDF. Default families (Nanum, Noto)
+  are SIL Open Font License fonts that permit embedding. If you configure a proprietary font in `fonts:`,
+  make sure its license allows embedding in documents.
+- **Ghostscript** (AGPL-3.0) is invoked as a separate `gs` process for proof images only; it is not linked or
+  redistributed. Anyone who bundles Ghostscript together with zinegen (containers, installers) takes on the
+  AGPL obligations for that bundle.
+- **Pango / Cairo / GLib** (LGPL-2.1+) are loaded by WeasyPrint as shared libraries.
+
+## Python dependencies
+
+| Package | License |
+|---|---|
+| lr-mcp | MIT |
+| mcp | MIT |
+| WeasyPrint, pydyf, tinycss2, Jinja2 | BSD-3-Clause |
+| pikepdf | MPL-2.0 |
+| Pillow (with LittleCMS) | MIT-CMU (LittleCMS: MIT) |
+| jsonschema, PyYAML, fonttools | MIT |

zinegen-0.1.0/docs/00-research.md

@@ -0,0 +1,67 @@
+# zinegen 사전 조사 (2026-11-08)
+
+lr-mcp로 가져온 Lightroom 앨범을 바탕으로, AI 에이전트가 조판하고 출판용(인쇄 입고 가능) PDF를 만드는 앱의 사전 조사 메모.
+
+## 1. lr-mcp가 지금 주는 것 / 못 주는 것
+
+소스: github.com/longfin/lr-mcp `src/lr_mcp/server.py`, `client.py` (2026-11-08 기준 main)
+
+제공:
+- 앨범 목록/검색, 앨범 내 사진 필터(날짜, 시간대, 별점, 플래그, 카메라/렌즈/조리개/ISO/파일명)
+- 사진 요약: id, 파일명, 촬영시각, 별점, 플래그, 카메라, 렌즈, 노출값, 원본 픽셀 크기(`importSource.originalWidth/Height`)
+- 현상 설정 요약(XMP develop의 주요 crs:* 키, `HasCrop`, `CropAngle` 포함)
+- 렌디션 JPEG: thumbnail2x / 640 / 1280 / 2048 / 2560 / fullsize. 2560·fullsize는 `X-Generate-Renditions`로 생성 요청 후 2초 간격 폴링(최대 60초)
+- 프로젝트 앨범 생성/추가/삭제(서버가 만든 앨범만)
+
+미제공(확장 후보):
+- 앨범의 사용자 정렬 순서(custom order). 현재 `lr_list_photos`는 촬영시각 순으로 정렬
+- 제목/캡션(xmp dc:title, dc:description), 키워드, 색 라벨, GPS/위치
+- 크롭 적용 후 실제 가로세로비(원본 크기만 노출. 렌디션 JPEG 픽셀 크기를 직접 읽어야 함)
+- 원본(RAW/마스터) 다운로드. Partner API에 원본 다운로드 엔드포인트가 없다는 Adobe 측 답변(2024-07)이 커뮤니티에 인용됨. PUT /master(업로드)만 존재
+- 렌디션 색공간/ICC. 문서에서 확인 못 함. 실측 필요(exiftool로 ICC 확인)
+
+운영 제약:
+- 생성된 2560/fullsize 렌디션은 1일 후 자동 삭제 → 로컬 캐시 필수
+- 2560/fullsize는 "basic API access에서는 불가"라는 문구가 검색 결과에 인용됨(lr-mcp는 이미 사용 중이므로 현재 자격으로 되는지 확인)
+- 크레덴셜당 베타 사용자 25명 제한 → 타인에게 배포하는 제품이면 Adobe 심사 필요
+
+## 2. 인쇄 입고 사양(일반)
+
+- 재단 여백(도련) 사방 3mm. A4 완성 210×297 → 작업 216×303mm
+- 이미지 300dpi(최종 인쇄 크기 기준)
+- 국내 인쇄소 대부분 CMYK 요구. RGB 입고 시 색 변환은 인쇄소가 임의로 함
+- PDF/X-1a: CMYK/별색만, 투명도 불가. PDF/X-4: ICC 태그된 RGB·투명도 허용. 해외 POD(Blurb 등)와 디지털 인쇄는 X-4 또는 일반 PDF 수용이 많음
+- 무선제본 책등 = (총 페이지 ÷ 2) × 종이 1장 두께(mm). 평량(g)이 아닌 두께(㎛)가 필요. 인쇄소/제지사 자료 필요
+- 표지는 보통 내지와 별도 PDF(펼침: 뒷표지+책등+앞표지+도련)
+- 검증: PDF/X 프리플라이트는 Acrobat Pro 또는 callas pdfToolbox. veraPDF는 PDF/A·UA만
+
+해상도 환산(300dpi):
+| 렌디션 | 긴 변 최대 인쇄 길이 |
+|---|---|
+| 2048px | 173mm |
+| 2560px | 217mm (A5 세로 216mm 도련 포함 딱 맞음) |
+| 24MP 6000px | 508mm (A4 펼침 426mm 가능) |
+| 12MP 4000px | 339mm (A4 펼침은 240dpi) |
+
+## 3. 렌더링 엔진 후보 (PDF/X 지원 관점)
+
+| 엔진 | PDF/X | 이미지 RGB→CMYK | 도련/재단선 | 비고 |
+|---|---|---|---|---|
+| Typst | 없음(PDF/A, PDF/UA만) | 없음 | 수동 | 빠름, 텍스트 DSL이라 에이전트 친화적. PDF/X는 Ghostscript 후처리 필요 |
+| WeasyPrint | pdf/x-1a, x-3, x-4, x-5g + output intent | 불명확 | @page bleed/marks | Python(lr-mcp와 동일). "유효성 보장 안 함" 명시 |
+| Prince | X-1a/X-3/X-4 공식, 오류 보고 | 자동 변환, 이미지 ICC 존중 | @page bleed/marks | 상용. 가장 확실 |
+| Chromium/Paged.js | 없음 | 없음 | Paged.js로 marks/bleed | 미리보기용으로는 최적(HTML 그대로 GUI) |
+| 직접 생성(pikepdf/pdf-lib) | 직접 구현 | Pillow+LittleCMS | 직접 | 자유도 최대, 공수 최대 |
+| InDesign(설치됨, MCP 있음) | 네이티브 | 네이티브 | 네이티브 | Adobe 라이선스 의존 |
+| Ghostscript 후처리 | -dPDFX + PDFX_def.ps | -sColorConversionStrategy=CMYK | - | 버전별 동작 차이·버그 보고 있음 |
+
+로컬 확인: gs 10.05, ImageMagick 7.1, exiftool, uv, node 24, InDesign 2026, Lightroom(Classic 포함) 설치됨.
+
+## 4. 아키텍처 초안(에이전트 중심)
+
+1. 수집: lr-mcp로 선별 → 로컬 캐시(렌디션 + 메타 JSON)
+2. 북 스펙(선언적 파일, git 친화): 판형/도련/그리드/서체/시퀀스/스프레드별 템플릿/이미지 배치(초점·크롭)/캡션
+3. 결정적 렌더러: 스펙 → PDF(인쇄용) + 저해상 PNG 프루프(스프레드 단위)
+4. 에이전트 루프: 프루프 이미지를 보고 비평 → 스펙 수정 → 재렌더
+5. GUI: 스프레드 뷰어 + 코멘트/승인만. 편집 기능 없음(또는 최소)
+6. 출고: 내지 PDF/X + 표지 PDF/X + 프리플라이트 리포트

zinegen-0.1.0/docs/01-probe-results.md

@@ -0,0 +1,58 @@
+# 실측 결과: Lightroom 렌디션 JPEG 적합성과 WeasyPrint PDF/X (2026-11-08)
+
+## 1. Lightroom Partner API 렌디션 실측
+
+대상: Ricoh GR IV DNG(25MP) 2장, 앨범 "20261107 단풍을찌것습니다", lr-mcp `lr_download_photos`로 수신.
+
+| 항목 | fullsize | 2560 | 2048 |
+|---|---|---|---|
+| 픽셀 | 6192×4128 (원본 동일) | 2560×1706 | 2048×1365 |
+| 용량 | 5.0MB | 0.8MB | 0.6MB |
+| 비트 | 8bit | 8bit | 8bit |
+| ICC | Display P3 임베드 | Display P3 | Display P3 |
+| JPEG 품질 | 92 | 92 | 92 |
+| 크로마 서브샘플링 | 없음(4:4:4) | 없음 | 없음 |
+| 해상도 태그 | 300dpi | - | - |
+| 생성 엔진 | Adobe Imagecore (Linux) | | |
+| 메타데이터 | 제목/캡션/저작자 없음. EXIF 대부분 제거 | | |
+
+판정: 출판 입고용으로 충분하다.
+- 8bit/채널은 인쇄 RIP 입력의 업계 표준. 16bit 이점은 추가 보정 여지뿐이며, 보정은 Lightroom에서 끝내고 다시 받으면 된다.
+- 품질 92 + 4:4:4는 시각적으로 무손실 수준. 재압축만 피하면 된다.
+- Display P3는 sRGB보다 넓어 코티드 CMYK 색역 대부분을 담는다. 변환 시 임베드 ICC를 LittleCMS가 그대로 사용했다.
+- 단점: 캡션·제목 메타데이터 없음(API로 따로 받아야 함), 출력 샤프닝 제어 불가, 생성 렌디션 1일 후 만료.
+
+## 2. CMYK 변환 실측 (Pillow + LittleCMS)
+
+Display P3 → 각 프로파일, 지각적 의도 + 흑점 보정. 풀해상도 변환 0.5초.
+
+| 목적 프로파일 | 색역 밖 픽셀(상대색도 기준, 1/8 축소 샘플) |
+|---|---|
+| Japan Color 2001 Coated | 약 28% |
+| Coated FOGRA39 | 약 25% |
+| US Web Coated SWOP | 약 31% |
+
+이 사진은 채도 +28, 포지티브 필름 프로파일의 단풍 사진이라 색역 밖 비율이 높다. JPEG 문제가 아니라 CMYK 색역의 한계이므로 소프트프루프(CMYK→sRGB 시뮬레이션)를 에이전트가 만들어 보여주고 Lightroom에서 조정하는 루프가 필요하다.
+
+산출 CMYK JPEG(품질 95, 4:4:4): 약 22MB/장. CMYK TIFF LZW: 85~92MB/장.
+
+## 3. WeasyPrint PDF/X 실측
+
+환경: WeasyPrint 최신(uv), macOS에서 `brew install pango` 필요, `DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`.
+입력: A5(148×210) 2페이지 HTML, `@page { bleed: 3mm; marks: crop cross }`, `@color-profile --press { src: url(JapanColor2001Coated.icc); components: c,m,y,k }`, `output_intent="--press"`, CMYK JPEG 전면 배치 + 한글 캡션.
+
+| 검사 항목 | PDF/X-1a | PDF/X-4 |
+|---|---|---|
+| PDF 버전 | 1.4 | 1.6 |
+| OutputIntent GTS_PDFX + DestOutputProfile | ✓ Japan Color 2001 Coated | ✓ |
+| GTS_PDFXVersion | PDF/X-1a:2003 (Info + XMP) | PDF/X-4 (XMP) |
+| TrimBox / BleedBox | 419.5×595.3pt / +8.5pt(3mm) | 동일 |
+| 이미지 | DCTDecode, DeviceCMYK, 6192×4128 재압축 없음 | 동일 |
+| 서체 | Apple SD Gothic Neo 서브셋 임베드 | 동일 |
+| 투명도/ExtGState alpha | 없음 | 없음 |
+| 텍스트·괘선 색 | device-cmyk → DeviceCMYK 연산자 | 동일 |
+| 재단선 | 렌더 확인됨 | 동일 |
+
+주의: 미사용 `/Lab`, `/ICCBased` ColorSpace 리소스가 페이지 리소스에 남는다. 엄격한 X-1a 프리플라이트에서 걸릴 수 있으니 pikepdf 후처리로 제거하거나 Acrobat 프리플라이트로 확인 필요. 공식 PDF/X 검증 도구(Acrobat Pro Preflight, callas)로의 최종 검증은 아직 안 했다.
+
+재현: `probe/cmyk_probe.py`, `probe/page.html`.