# The Shape Between - `template_storybook`

`template_storybook` is a full-page illustrated storybook exemplar. It renders
every story page as a complete visual scene, then overlays text either directly
on the art or inside a translucent reading box. The bundled story follows
Tessa, a child tetrahedron raised in a family of cubes, and Ciro, a child cube
raised in a tetrahedral family, as their mirrored homes meet through a large
yin-yang-like symbol, a tetrahedron stabilizing the inside of a cube, shadow
projection, a tensegrity lantern, and a vector garden. Its subtitle is
`A geometric fable of belonging, bracing, and reciprocal form`.

## When to use this template

Use this template when you need **full-page illustrated PDF storytelling**:
picture-book pages, symbolic scenes, character-generation methods, page-level
orchestrators, and deterministic raster art assembled into a print-ready PDF.
Choose it when the artifact is the designed book itself rather than a standard
research manuscript.

## What it produces

- `output/figures/storybook_pages/*.png` - one full-page illustration per cover
  or story page
- `output/figures/storybook_contact_sheet.png` - deterministic visual inspection sheet
- `output/pdf/the-shape-between.pdf` - the primary fourteen-page storybook PDF
- `output/data/storybook_manifest.json` - validated cast, page alt text, and render paths
- `output/reports/storybook_summary.md` - compact render summary

## Publication and rendering

<!-- PUBLISHING-STATUS:START (generated by infrastructure.publishing.status_report) -->
**The Shape Between: A Full-Page Illustrated Storybook Template** · v0.1.0 · MIT · Daniel Ari Friedman

Concept DOI: [10.5281/zenodo.21176000](https://doi.org/10.5281/zenodo.21176000) | Version DOI: [10.5281/zenodo.21176001](https://zenodo.org/records/21176001) | Repository: [docxology/template_storybook](https://github.com/docxology/template_storybook)

Publishing surface — 20 platforms, 8 published:

| Platform | Tier | Status | Reference | Credentials |
| --- | --- | --- | --- | --- |
| zenodo | first-class | ✅ published | [10.5281/zenodo.21176000](https://doi.org/10.5281/zenodo.21176000) | `ZENODO_API_TOKEN` |
| github | first-class | ✅ published | [https://github.com/docxology/template_storybook/releases/tag/v0.1.0](https://github.com/docxology/template_storybook/releases/tag/v0.1.0) | `GITHUB_TOKEN` |
| arxiv | first-class | ⚪ available | — | — |
| pypi | first-class | ✅ published | [https://test.pypi.org/project/template-storybook/0.1.0/](https://test.pypi.org/project/template-storybook/0.1.0/) | `PYPI_TOKEN`, `TESTPYPI_TOKEN` |
| ipfs_pinata | first-class | ✅ published | [https://gateway.pinata.cloud/ipfs/QmPcB1mTMZQb541ZsmwDwc6rQgSTLR4BGYefdTLsj1s5Qy](https://gateway.pinata.cloud/ipfs/QmPcB1mTMZQb541ZsmwDwc6rQgSTLR4BGYefdTLsj1s5Qy) | `PINATA_JWT` |
| ipfs_web3storage | first-class | ⚪ available | — | `WEB3_STORAGE_TOKEN` |
| software_heritage | first-class | ✅ published | [https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/docxology/template_storybook/](https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/docxology/template_storybook/) | — |
| github_pages | first-class | ⚪ available | [docxology/template_storybook](https://github.com/docxology/template_storybook) | `GITHUB_TOKEN` |
| cloudflare_pages | first-class | ⚪ available | — | `CLOUDFLARE_API_TOKEN` |
| netlify | first-class | ✅ published | [https://6a47fd2233010f4eb138cdcd--tranquil-kleicha-0c9203.netlify.app](https://6a47fd2233010f4eb138cdcd--tranquil-kleicha-0c9203.netlify.app) | `NETLIFY_AUTH_TOKEN` |
| huggingface_hub | first-class | ✅ published | [https://huggingface.co/datasets/ActiveInference/template_storybook](https://huggingface.co/datasets/ActiveInference/template_storybook) | `HUGGINGFACE_TOKEN`, `HF_TOKEN` |
| osf | first-class | ✅ published | [https://osf.io/xbajh/](https://osf.io/xbajh/) | `OSF_TOKEN` |
| amazon_kdp | documented | 🟡 planned | — | `AMAZON_KDP_EMAIL`, `AMAZON_KDP_PASSWORD` |
| google_play_books | documented | 🟡 planned | — | `GOOGLE_PLAY_BOOKS_SERVICE_ACCOUNT_JSON` |
| gumroad | documented | 🟡 planned | — | `GUMROAD_ACCESS_TOKEN` |
| leanpub | documented | 🟡 planned | — | `LEANPUB_API_KEY` |
| lulu | documented | 🟡 planned | — | `LULU_CLIENT_KEY`, `LULU_CLIENT_SECRET` |
| draft2digital | documented | 🟡 planned | — | `DRAFT2DIGITAL_API_TOKEN` |
| stripe | documented | 🟡 planned | — | `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY` |
| ingramspark | documented | 🟡 planned | — | `INGRAMSPARK_CLIENT_ID`, `INGRAMSPARK_CLIENT_SECRET` |

_Keywords: storybook, illustration, procedural graphics, reportlab, reproducible publishing._

_Status legend: ✅ published (durable identifier recorded in `config.yaml`) · 🔵 reserved (identifier reserved but not yet registered by final publication) · ⚪ available (adapter implemented and locally verifiable) · 🟡 planned. This block is generated — edit `manuscript/config.yaml`, then regenerate with `uv run python -m infrastructure.publishing.status_report --project <path> --write`._
<!-- PUBLISHING-STATUS:END -->

The canonical renderer is [docxology/template](https://github.com/docxology/template)
with `--project templates/template_storybook`.

To regenerate this exemplar from the public monorepo:

```bash
git clone https://github.com/docxology/template
cd template
uv sync
uv run python scripts/pipeline/stage_02_analysis.py --project templates/template_storybook
uv run python scripts/pipeline/stage_03_render.py --project templates/template_storybook
uv run python scripts/pipeline/stage_04_validate.py --project templates/template_storybook
uv run python scripts/pipeline/stage_05_copy.py --project templates/template_storybook
```

## Quick start

From the repository root:

```bash
uv run python scripts/pipeline/stage_02_analysis.py --project templates/template_storybook
open projects/templates/template_storybook/output/pdf/the-shape-between.pdf
```

Render through the manuscript pipeline as well:

```bash
uv run python scripts/pipeline/stage_03_render.py --project templates/template_storybook
```

## How it works

```text
content/story.yaml
        |
        v
src/storybook/
  models.py        frozen dataclasses shared across the package: Character, PageSpec, StorybookSpec, RenderResult
  characters.py    cast generation and shape-family validation
  story.py         YAML loader and manifest metadata
  illustration.py  procedural full-page scenes
  text_layout.py   deterministic typography, wrapping, and text overlays
  rendering.py     PNG page rendering and ReportLab PDF assembly
        |
        v
scripts/10_render_cover.py
scripts/20_render_page_01.py ... scripts/32_render_page_13.py
scripts/90_build_storybook_pdf.py
```

The page scripts are intentionally thin so forks can add, remove, or reorder
pages without moving rendering behavior out of `src/`.

Configuration entry points are `content/story.yaml` for story data and
`manuscript/config.yaml` / `manuscript/config.yaml.example` for repository
pipeline metadata, render formats, and the Stage-02 script list.

## Tests

```bash
uv run pytest projects/templates/template_storybook/tests/ \
  --cov=projects/templates/template_storybook/src --cov-fail-under=90
```

The suite uses the real YAML content and renders real PNG/PDF artifacts.