diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4049ca..c7a0c61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,18 @@ All notable changes to Wirehouse are listed here. The format follows
## [Unreleased]
### Changed
+- **A README for the public launch** (2026-10-18)
+ - Summary: The README opens with the new demo, a "Why Wirehouse" section of what the tool guarantees
+ (evidence for each connection, one offline file, any agent or none, safe to share), a comparison
+ with hand-drawn and Mermaid diagrams, and a gallery of eight features; the safety section says what
+ happens when you scan a repository you did not write.
+ - Why: the README is the first thing a visitor sees, and it explained what Wirehouse draws more than
+ why that is worth having.
+- **Demo pictures of the 0.3.0 viewer** (2026-10-18)
+ - Summary: `docs/assets` has a new animated demo and MP4, nine screenshots and a share card of the
+ 0.3.0 viewer on the demo map, plus `one-map-two-readers.png` (`wirehouse export` next to the
+ warehouse). They are rendered frame by frame on a virtual clock, so motion is smooth without a GPU.
+ - Why: every picture still showed the 0.2.0 viewer.
- **The improvement log records Pass 2** (2026-10-18)
- Summary: IMPROVEMENT_LOG.md has a Pass 2 entry: areas covered, findings by severity, the menu, what
was done with its measured effect, what was deferred and the next pass's focus.
@@ -18,6 +30,12 @@ All notable changes to Wirehouse are listed here. The format follows
- Why: the published demo was drawn by the 0.2.0 viewer, without the Checks panel, change review or
any of the Pass 1 and Pass 2 fixes, and its enrichment could not be reproduced.
+### Fixed
+- **README images show on PyPI** (2026-10-18)
+ - Summary: Images and links in the README use absolute GitHub URLs.
+ - Why: PyPI renders the README as the project description but cannot resolve paths inside the
+ repository, so every picture was broken there.
+
## [0.3.0] - 2026-10-18
### Added
diff --git a/README.md b/README.md
index 0742e82..c38a108 100644
--- a/README.md
+++ b/README.md
@@ -1,75 +1,110 @@
-
-
+
+
- Wirehouse turns a repository into a 3D warehouse you can walk around: services are shipping
- containers, databases are silos, auth is a security gate, and every pipe is a real connection
- found in the code. Trace where a request goes, take a guided tour, and share it all as
- one offline HTML file. Built for your agents.
+ See how your codebase really fits together, and prove it.
+ Wirehouse maps a repository from its code and turns it into a 3D warehouse you can walk:
+ services are shipping containers, databases are silos, auth is a security gate, and every pipe is
+ a connection found in the code, with the file and line that prove it. Trace where a request goes,
+ take a guided tour, and share it all as one offline HTML file.
-
+
+
+## Why Wirehouse
+
+Architecture diagrams go stale the day they are drawn, and reading a new codebase file by file tells
+you *what* is there but not *how it fits together*. Wirehouse rebuilds the map from the code every
+time, and holds it to one rule: **nothing is drawn that the code does not show.**
+
+- **A map you can check.** Every connection found in the code carries the file and line it was found
+ at, linked to your code host at the exact commit that was scanned. What an agent adds must cite real code or it
+ is left out, inferred links say so, and a **Checks** panel lists anything that was dropped and why.
+- **Current in seconds, not a drawing to maintain.** Re-run it after a change; descriptions are
+ cached by a hash of the code, so only what changed is described again. `--against` shows exactly
+ which blocks, connections and files a change touched.
+- **One file, nothing to host.** The page is a single offline HTML file with everything inlined:
+ no server, no account, no telemetry, no network loads. Email it, attach it to a pull request, or
+ publish it on GitHub Pages.
+- **Answers real questions.** *What does this service reach?* Trace it, with hop counts.
+ *How does a request get to the database?* Walk the route stop by stop. *Where do I start?* Take
+ the tour, then go find things with quests.
+- **Your agent, or no agent.** The `/wirehouse` skill uses the open `SKILL.md` format and works with
+ Claude Code, Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot and any agent that reads files. Without
+ one, the CLI still draws the full map with rule-based descriptions.
+- **Safe to share.** Real `.env` files are never read, credential-looking text is cut from every
+ output, and `--share` removes your local paths before you publish.
-## Why
-
-Architecture diagrams go stale the day they are drawn, and reading a new codebase file by file
-tells you *what* is there but not *how it fits together*. Wirehouse builds the map from the code
-every time, and makes exploring it feel like walking a well-run warehouse instead of reading a
-wall of boxes and arrows:
+
+
+
+ The same map as text for your agent or your pull request (wirehouse export), and as a place to walk.
+
-- **New teammate?** Take the guided tour, then go find things on your own with quests.
-- **Reviewing a change?** Trace what a service reaches before you touch it.
-- **Explaining the system?** Walk the route from the user to the database and share the link.
+### How it compares
-Everything you see comes from evidence: each pipe lists the file and line it was found in, and
-anything your agent adds has to cite real code or it is left out.
+| | Hand-drawn diagram | Mermaid in the docs | Wirehouse |
+|---|:---:|:---:|:---:|
+| Built from the code | no | no | **yes** |
+| File and line behind each connection | no | no | **yes** |
+| Stays current without redrawing | no | no | **yes** |
+| Follows env vars, compose, Terraform and CI, not just imports | by hand | by hand | **yes** |
+| Shows what a change touched | no | in the diff | **yes** (`--against`) |
+| Guided tours and traces for newcomers | no | no | **yes** |
+| Text for a README or pull request | no | yes | **yes** (`wirehouse export`) |
## What you can do
-
Trace everything a block leads to, or everything that leads to it, with hop counts. File precise.
-
Walk a route from A to B, hop by hop, with the code behind each step.
+
Trace everything a block leads to, or everything that leads to it, with hop counts. File precise.
+
Walk a route from A to B, hop by hop, with the code behind each step.
+
+
+
Guided tours and quests written by your agent from the real code, stop by stop with file and line.
+
Walk into any block. Folders are crates, files sit on racks with aisle signs, connections leave through wall ports.
-
Walk into any block. Folders are crates, files sit on racks, connections leave through wall ports.
-
Guided tours and quests written by your agent from the real code, with your progress kept in the browser.
+
Database rooms with columns, keys and a schema diagram.
+
Floor plan in 2D for a quick overview, fully keyboard accessible.
-
Database rooms with columns, keys and a schema diagram.
-
Floor plan in 2D for a quick overview, fully keyboard accessible.
+
The Clipboard: a first-shift checklist, tours, quests and what you have inspected so far.
+
Night and day shift lighting; the page adapts its resolution to keep slower laptops responsive.