docs: cosmic green banner, branded diagram suite & README restructure

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to PyFly
+
+Thanks for your interest in improving PyFly — the official Python implementation of the
+[Firefly Framework](https://github.com/fireflyframework). This guide covers everything you
+need to make a change and open a pull request.
+
+## Ground rules
+
+- **Be respectful and constructive.** Assume good intent.
+- **Keep changes focused.** One logical change per pull request; small PRs review faster.
+- **Add tests for new behaviour** and a note in `CHANGELOG.md` under the next version.
+- By contributing, you agree your work is licensed under **Apache-2.0** (see [`LICENSE`](LICENSE)).
+
+## Development setup
+
+PyFly targets **Python 3.12+** and uses [uv](https://github.com/astral-sh/uv) (pip also works).
+
+```bash
+git clone https://github.com/fireflyframework/fireflyframework-pyfly.git
+cd fireflyframework-pyfly
+
+# Install all extras + dev tooling
+uv sync --all-extras --group dev
+# (or: python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[full]")
+```
+
+## The quality gates (what CI runs)
+
+Every pull request must pass the same gates CI enforces. Run them locally first:
+
+```bash
+uv run ruff format .        # format
+uv run ruff check .         # lint
+uv run mypy src             # type-check (strict)
+uv run pytest               # tests
+```
+
+- **Formatting & linting:** [Ruff](https://docs.astral.sh/ruff/).
+- **Typing:** [mypy](https://mypy-lang.org/) in **strict** mode — every public surface is fully annotated. If it compiles, it's consistent.
+- **Tests:** [pytest](https://docs.pytest.org/). Add tests next to the code they cover under `tests/`, and prefer fast, isolated unit tests; integration tests that need real infrastructure (Postgres, Kafka, Redis, …) live behind the Docker Compose stack (`docker-compose.yml`).
+
+## Making a change
+
+1. **Branch from `main`:** `git switch -c feat/short-description` (or `fix/…`, `docs/…`).
+2. Make your change with tests.
+3. Run the quality gates above until green.
+4. Add a `CHANGELOG.md` entry under the next version heading (we use [Keep a Changelog](https://keepachangelog.com/)).
+5. **Commit** with a clear, imperative message (Conventional-Commits style is welcome: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`).
+6. **Open a pull request** against `main` describing the what and the why.
+
+## Versioning & releases
+
+PyFly uses **Calendar Versioning** ([CalVer](https://calver.org/)) — `YY.MM.PATCH` — to stay
+aligned with the rest of the Firefly Framework family (Java, .NET, Go, Rust). Releases are
+published via [GitHub Releases](https://github.com/fireflyframework/fireflyframework-pyfly/releases)
+(PyFly is **not** published to PyPI). Maintainers cut releases; you don't need to bump the
+version in your PR — just add the changelog entry.
+
+## Documentation & the book
+
+- Framework docs live under [`docs/`](docs/README.md) — keep them in sync with code changes.
+- The project-driven book, *PyFly by Example*, lives under [`book/`](book/); its figures and
+  cover are generated (see [`assets/README.md`](assets/README.md) for the shared brand system).
+
+## Questions
+
+Open a [discussion or issue](https://github.com/fireflyframework/fireflyframework-pyfly/issues).
+Thank you for contributing! 🐍✨

assets/README.md

@@ -0,0 +1,60 @@
+# PyFly brand assets
+
+The visual identity used across the README and the book. **PyFly is the green
+firefly of the [Firefly Framework](https://github.com/fireflyframework) family** —
+the same firefly-in-the-dark language as the Java / .NET / Rust siblings, recolored
+to Python green (the logo's green-yellow sparkles *are* the family's fireflies).
+
+## Assets
+
+| File | What it is |
+|------|------------|
+| [`pyfly-logo.png`](pyfly-logo.png) | The master logo — the green Python snake on a leaf-wing + the `pyFly` wordmark (RGBA, 1648×748). Source of brand truth. |
+| [`banner.svg`](banner.svg) | README hero banner (1280×320). Dark cosmic sky, green fireflies + light trails, the **actual snake** (cropped from the logo, embedded) and a **Maven Pro** `pyFly` wordmark vectorized to paths. |
+| [`architecture.svg`](architecture.svg) | "Architecture at a glance" — front door → five layers → async core. |
+| [`hexagonal.svg`](hexagonal.svg) | Ports & adapters: an application core, Protocol ports, swappable adapters. |
+| [`auto-configuration.svg`](auto-configuration.svg) | Entry-point discovery → conditional guards → bind / fall back / skip. |
+| [`request-lifecycle.svg`](request-lifecycle.svg) | An HTTP request flowing through filters → controller → service → port → adapter → DB. |
+| [`distributed-patterns.svg`](distributed-patterns.svg) | A saga DAG with reverse-order compensation + Saga / Workflow / TCC cards. |
+| [`ecosystem.svg`](ecosystem.svg) | The Firefly family constellation (Java · .NET · **PyFly** · Rust · Go · Angular · GenAI). |
+
+## Design system
+
+- **Typeface:** [Maven Pro](https://fonts.google.com/specimen/Maven+Pro) for the
+  wordmark (also the book's typeface). System sans / `ui-monospace` for diagram text.
+- **Green palette:** lime `#7ed321` · primary `#4cbb2f` · `#43b02a` / `#3a9e23` ·
+  mid `#2c8a1c` · deep `#1f5e16` · body text `#33402e` · muted `#7c876f` ·
+  card stroke `#dfe7d4` · panel `#f4f9ee`. Firefly glow `#9bd24a → #c2e85f → #dff58a`.
+- **Banner sky:** `#07110b → #0a1410 → #0c1a0f` with a green radial ambient.
+- **Motifs:** firefly motes, a green title rule, deep-green numbered badges,
+  monospace module lists, and brand icons ([Simple Icons](https://simpleicons.org/)).
+- **GitHub-safe:** every SVG is self-contained — no `<script>`, no external
+  resource references, no web fonts (the wordmark is vector paths); diagrams use
+  opaque light cards so they read in both light and dark mode.
+
+## Regenerating
+
+Everything is generated by one self-contained script:
+
+```bash
+# needs fontTools + Pillow (the book virtualenv has both); Maven Pro is fetched & cached
+book/.venv/bin/python assets/tools/build_brand_assets.py
+```
+
+It crops the snake from `pyfly-logo.png`, vectorizes the Maven Pro wordmark,
+draws the six diagrams from the shared kit (measured text → guaranteed fit, plus an
+automatic overlap check that prints `WARNINGS: none`), and writes all seven SVGs.
+The brand icons are vendored in [`tools/icons.py`](tools/icons.py) so the build is
+network-free except for the one-time Maven Pro download.
+
+### Previewing / verifying
+
+SVGs render faithfully (exactly as GitHub shows them) with resvg:
+
+```bash
+npx -y @resvg/resvg-js-cli assets/banner.svg /tmp/banner.png   # exact-size PNG
+```
+
+The book cover (`book/art/cover.svg`) shares this identity and is produced by
+[`book/build/gen_cover.py`](../book/build/gen_cover.py), which vectorizes the same
+Maven Pro wordmark.