docs(humans): ship the MD explainer as a PDF with the images baked in

The HTML references screenshots relatively, so it only renders inside a
checkout -- mailing the file on its own gives broken images. The PDF is one
self-contained file, which is what actually gets sent to Ozlem.

- tools/humans_to_pdf.py: renders .humans/*.html via headless Chrome (or
  Edge), so the output is what the browser shows. HTML stays the source.
- @media print block on the page: the wide tables and the pipeline diagram
  scroll on screen but would be cut off at the paper edge; this reflows
  them and keeps figures, callouts and table rows off page breaks.
  Verified at A4 content width -- 6 pages, both screenshots embedded.
- *.pdf -> LFS. Each regeneration is a whole new ~2 MB blob, and unlike
  png/jpg there are no PDFs tracked raw yet, so there is no history to
  rewrite by adding it now.

Also corrects working-files.md: it claimed .gitattributes does not LFS-track
.blend, which was true when written and is no longer -- .blend/.zprj/.obj/
.npy/.npz have since been added. The note now covers what is actually still
excluded (png/jpg, deliberately) and why that makes QA renders scratch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-07 09:31:37 -07:00
parent 3ba86b2ea8
commit 4bbd1a1732
6 changed files with 157 additions and 9 deletions
+19 -5
View File
@@ -1,7 +1,7 @@
# .humans/ — pages written for people, not agents
Self-contained HTML pages explaining how parts of this repo work, for reading in
a browser. Same convention as `ariki-game/.humans/`.
Explainers about how parts of this repo work. Same convention as
`ariki-game/.humans/`: an HTML page per topic, read in a browser.
The operating detail lives in `.claude/skills/` and `.agents/` and is written for
whoever is driving the tools. These pages are the **explanation** — what we built,
@@ -10,7 +10,21 @@ skill/wiki is the source of truth.
| page | about |
|---|---|
| `marvelous-designer.html` | How we author Ariki's garments as real sewn cloth in Marvelous Designer — the process, what's been made, the traps, what's still unsolved. Written for Özlem and Jeremy. |
| `marvelous-designer` | How we author Ariki's garments as real sewn cloth in Marvelous Designer — the process, what's been made, the traps, what's still unsolved. Written for Özlem and Jeremy. |
Images are referenced relatively (`../tools/tailor/screenshots/…`), so open these
from inside the repo rather than copying the file out on its own.
## HTML is the source; the PDF is what you send
The HTML references screenshots relatively (`../tools/tailor/screenshots/…`), so it
only renders from inside a checkout — mail someone the `.html` on its own and they
get broken images. The **PDF has the images baked in** and travels as one file.
Edit the HTML, then regenerate:
```
python tools/humans_to_pdf.py --all # or a single page
```
That drives headless Chrome, so what you get is exactly what the browser shows.
Each page carries an `@media print` block controlling the paper layout — without it
the wide tables and the pipeline diagram, which merely scroll on screen, get cut
off at the page edge. Commit the HTML and the PDF together so they don't drift.