Apply rsfly identity throughout books and documentation

.github/workflows/ci.yml

@@ -30,7 +30,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: ${{ env.RUST_TOOLCHAIN }}
+          # Pin lint diagnostics; build and tests continue to target stable Rust.
+          toolchain: "1.96.0"
           components: rustfmt, clippy
       - uses: Swatinem/rust-cache@v2
       - name: System libraries (librdkafka native build + TLS/SASL)
@@ -139,10 +140,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: WeasyPrint system libraries
-        run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 libffi-dev
+        run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 libffi-dev poppler-utils
       - name: book toolchain (venv)
         run: |
           python3 -m venv docs/book/.venv
-          docs/book/.venv/bin/pip install --quiet weasyprint markdown pygments pyyaml
-      - name: build PDF + EPUB
-        run: docs/book/build-book.sh
+          docs/book/.venv/bin/pip install --quiet -r docs/book/requirements.txt
+      - name: cover integration tests
+        run: docs/book/build-book.sh --test
+      - name: build English and Spanish PDF + EPUB
+        env:
+          BOOK_OUTPUT_DIR: ${{ runner.temp }}/rust-book-editions
+        run: |
+          docs/book/build-book.sh
+          BOOK_CONFIG=book-es.yaml docs/book/build-book.sh

README.md

@@ -1,8 +1,11 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="Firefly Framework for Rust" width="100%">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/banner-dark.svg">
+    <img src="assets/brand/banner-light.svg" alt="rsfly — Firefly for Rust" width="100%">
+  </picture>
 </p>
 
-<h1 align="center">Firefly Framework for Rust</h1>
+<h1 align="center">rsfly — Firefly for Rust</h1>
 
 <p align="center">
   <b>Spring Boot for Rust</b> — a production-grade platform for building
@@ -28,17 +31,22 @@
   <a href="CHANGELOG.md">Changelog</a>
 </p>
 
-> **Read the book — [Firefly Framework for Rust](docs/book/)** — the canonical,
+> **Read the book — [rsfly by example](docs/book/)** — the canonical,
 > best-in-class guide: a punchy [Quickstart](docs/book/src/02-quickstart.md)
 > (zero to a running reactive endpoint in minutes), the keystone
 > [Reactive Model](docs/book/src/05-reactive-model.md) chapter (`Mono`/`Flux`),
 > the new [Declarative Services with Macros](docs/book/src/21-declarative-macros.md)
 > chapter, and full chapters on configuration, persistence, DDD, CQRS, EDA, event
 > sourcing, sagas, HTTP clients, security, observability, testing, and
 > production. Build it locally with `mdbook build docs/book` and open
-> `docs/book/book/index.html`, or read the offline editions:
-> [`docs/book/dist/firefly-rust-by-example.pdf`](docs/book/dist/firefly-rust-by-example.pdf)
-> and [`.epub`](docs/book/dist/firefly-rust-by-example.epub).
+> `docs/book/book/index.html`, or download the redesigned offline editions:
+> English [PDF](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example.pdf)
+> · [EPUB](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example.epub).
+> Español [PDF](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example-es.pdf)
+> · [EPUB](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example-es.epub).
+
+**rsfly** is the product name. Existing `firefly` / `firefly-*` crate names,
+imports, APIs and repository links remain unchanged.
 
 > **Two headline wins.** (1) A **Spring-Boot-for-Rust
 > developer experience**: add the one [`firefly`](crates/firefly/README.md)

docs/book/BUILDING.md

@@ -0,0 +1,88 @@
+# Building the branded book editions
+
+Both editions use the collection title **rsfly by example**. The English subtitle
+is “Composing typed services with Tokio, Axum and SQLx”; the Spanish subtitle is
+“Servicios tipados con Tokio, Axum y SQLx”. The product name is rsfly; existing
+crate names, imports, technical examples and repository URLs remain unchanged.
+
+The English and Spanish editions share the original chapters and technical examples.
+Each edition has a localized front and back cover from the Firefly Framework Brand
+Kit, `11-Books/rust/`. The cover source of truth is that kit; this repository stores
+the exported artwork used to build the books. `art/brand-assets.json` records the
+imported files and their SHA-256 digests.
+
+The PDF uses outlined SVG artwork at the existing 7.5 × 9.25 inch trim size.
+CairoSVG renders the two cover pages as vectors, preserving translucent gradients;
+they replace the reserved cover pages without changing interior pagination. Cover
+pages have no running header or page number. The EPUB uses the corresponding PNG
+artwork for reader compatibility, with a front-cover image declaration, localized
+alternative text and separate front/back documents at the beginning/end of its
+reading order. The back cover is not a table-of-contents chapter.
+
+## Toolchain
+
+Create an isolated Python 3.12 environment under `docs/book/.venv` and install
+`docs/book/requirements.txt`. The requirements pin the renderer and its Python
+dependencies, including the PDF inspection library used by the tests. WeasyPrint
+also needs Pango/Cairo/GObject: on macOS use the Homebrew libraries; on Linux the
+CI workflow lists the system packages. Poppler supplies `pdftoppm` for
+rendered gradient regression tests. `build-book.sh` configures the macOS loader
+path. Pandoc, LaTeX and mdBook are not part of the PDF/EPUB build.
+
+```sh
+python3.12 -m venv docs/book/.venv
+docs/book/.venv/bin/pip install -r docs/book/requirements.txt
+docs/book/build-book.sh --test
+BOOK_OUTPUT_DIR=/absolute/path/to/book-editions docs/book/build-book.sh
+BOOK_CONFIG=book-es.yaml BOOK_OUTPUT_DIR=/absolute/path/to/book-editions docs/book/build-book.sh
+```
+
+The output directory contains `firefly-rust-by-example.{pdf,epub}` and
+`firefly-rust-by-example-es.{pdf,epub}`. Use `BOOK_OUTPUT_DIR` for a new edition:
+the default `docs/book/dist/` contains tracked historical release artifacts and
+must not be replaced incidentally. `--pdf` and `--epub` select one format.
+
+The existing body typography uses system-font fallbacks; the outlined cover SVGs
+do not depend on locally installed cover fonts. Inspect both complete PDFs after
+building on the selected release host, including front/back pages, chapter
+openings, page boundaries and the English/Spanish accented characters. Also open
+each EPUB in a reader and check its cover, final page and navigation.
+
+## Updating cover artwork
+
+Copy the approved `cover`, `cover-es`, `back-cover` and `back-cover-es` SVG/PNG
+pairs from the canonical kit into `docs/book/art/`, then refresh the provenance
+digests. `book.yaml` and `book-es.yaml` select each edition's artwork, title labels
+and alternative text. The build fails if a configured cover asset is missing.
+`gen_openers.py` regenerates chapter openers only and does not own the cover files.
+
+## Book-only publication
+
+Book publication is separate from the framework version. The existing release
+workflow is triggered by `v*.*.*` tags and publishes the historical committed
+distribution; it is not the publisher for this design edition. A reviewed
+`books-2026.10.08` release can attach the four newly built artifacts with
+`latest=false`, preserving framework tags, package versions and existing assets.
+Include the exact source commit, artwork provenance and artifact SHA-256 digests
+in its release notes. No book build command publishes or uploads files.
+
+## Interior identity and diagram sources
+
+The approved rsfly gradient-y lockups in `art/rsfly-light.svg` and
+`art/rsfly-dark.svg` come from Brand Kit `12-Frameworks/rust/`.
+`build/brand.py` embeds their existing outlines; it never redraws the mark.
+Chapter openers and part dividers use this same identity. Diagram footers reserve
+space below the existing drawing, leaving technical coordinates and labels intact.
+The inline figures in the English and Spanish manuscripts are maintained in the
+manuscripts; `build/gen_diagrams.py` owns the standalone diagram previews.
+
+`theme/tokens.css` uses the kit's charcoal, paper, amber, gold, ink and neutral
+colors. Success, warning and failure indicators retain distinct accessible
+semantic treatments. Syntax highlighting keeps its language-token distinctions.
+Root README and book landing headers use the matching canonical family assets
+from `assets/brand/`; technical identifiers and example code remain unchanged.
+
+For PDF interiors, the renderer uses the canonical PNG version of each small
+rsfly lockup to preserve the approved alpha gradient. Source SVG diagrams and
+EPUB interiors retain the original vector lockups. This avoids WeasyPrint
+flattening that gradient without changing the technical drawings.

docs/book/README.md

@@ -0,0 +1,16 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="../../assets/brand/logo-dark.svg">
+    <img src="../../assets/brand/logo-light.svg" alt="rsfly — Firefly for Rust" width="280">
+  </picture>
+</p>
+
+# rsfly by example
+
+Composing typed services with Tokio, Axum and SQLx.
+
+Read the [English manuscript](src/SUMMARY.md) or [Spanish manuscript](src-es/SUMMARY.md).
+The book connects application composition, HTTP, domain modeling, persistence and distributed work through one running service.
+
+See [Building the book](BUILDING.md) for the PDF/EPUB editions and artwork provenance.
+Existing `firefly` crate names, APIs and technical examples are unchanged.