The hero didn't show the thing, and six pages hadn't heard

README.md

@@ -8,7 +8,7 @@
 A tiny pixel character that walks your GitHub contribution year.
 
 <p align="center">
-  <img src="assets/banner.gif" alt="awan walking a contribution year on a GitHub profile" width="700">
+  <img src="assets/profile-sample.gif" alt="awan walking a real contribution year, then reacting to it" width="700">
 </p>
 
 He reads your real numbers, brags when the month went well, and goes to sleep
@@ -34,18 +34,6 @@ host, no account, no token.
 Three files in the repo named after you. No secrets to set up: the token GitHub
 Actions already gives you reads everything he needs.
 
-<p align="center">
-  <img src="assets/profile-sample.gif" alt="awan telling a profile's story, with that profile's real numbers" width="700">
-</p>
-
-<p align="center">
-  <sub>
-    A real profile, not a mock-up: the streak, the readout and the contribution
-    year are all live numbers a workflow fetched. It's a still preview, so it
-    isn't refreshed — <a href="profile">yours would be</a>, nightly.
-  </sub>
-</p>
-
 **[Build it in the browser →](https://codewithwan.github.io/awan/)** Arrange the
 beats, watch it play, download the folder. The preview runs the real engine
 compiled to wasm, so the frames you see are the frames CI draws — and you can
@@ -242,5 +230,19 @@ MIT OR Apache-2.0, at your option.
 
 ---
 
+<p align="center">
+  <img src="assets/banner.gif" alt="awan introducing awan, with this repo's own live numbers" width="700">
+</p>
+
+<p align="center">
+  <sub>
+    And that one is awan describing awan — same engine, same workflow, this
+    repo's own stars and version, redrawn every night. If it ever breaks, you'll
+    see it here first.
+  </sub>
+</p>
+
+---
+
 Heritage: the engine began as `idl pet` (Go) inside the
 [IDCloud](https://idcloud.app) CLI; awan is its standalone, embeddable second life.

docs/PROFILE.md

@@ -1,9 +1,13 @@
-# awan profile generator (design)
+# awan profile generator — design notes
+
+> **Using it?** You want [`profile/`](../profile) for the format and
+> [the editor](https://codewithwan.github.io/awan/) for the fast way. This file
+> is why it's built the way it is, for anyone changing it.
 
 A **seamless looping animation** generated from one JSON file, for a GitHub
-profile README. Users edit `awan.json`, add one workflow, and a GitHub Action
-regenerates the GIF on every push. This is a **separate, opt-in** layer — the
-core personality-layer CLI is untouched.
+profile README. The reader edits `awan.json`, calls one reusable workflow, and
+an Action redraws the GIF nightly. It's a **separate, opt-in** layer — the core
+engine and CLI are untouched by it.
 
 ## Separation
 

packages/npm/README.md

@@ -1,13 +1,10 @@
 # awan
 
-A tiny living character for your terminal — and a **personality layer** any
-CLI can embed. This package ships the `awan` binary to Node projects.
+A tiny pixel character that walks your GitHub contribution year.
 
-```sh
-npx @codewithwan/awan demo               # try it, no install
-npm i -g @codewithwan/awan && awan demo  # or install the command
-npm i @codewithwan/awan                  # or use it from your project
-```
+**[Build yours →](https://codewithwan.github.io/awan/)** · [source](https://github.com/codewithwan/awan)
+
+He also lives in your terminal — that's what this package installs.
 
 On install it downloads the prebuilt binary for your platform from the
 project's GitHub Releases. No Rust toolchain required.

packages/pypi/README.md

@@ -1,12 +1,10 @@
 # awan-cli
 
-A tiny living character for your terminal — and a **personality layer** any CLI
-can embed. This package ships the `awan` command (and a Python API) to PyPI.
+A tiny pixel character that walks your GitHub contribution year.
 
-```sh
-pip install awan-cli
-awan demo
-```
+**[Build yours →](https://codewithwan.github.io/awan/)** · [source](https://github.com/codewithwan/awan)
+
+He also lives in your terminal — that's what this package installs.
 
 On first run it downloads the prebuilt binary for your platform from the
 project's GitHub Releases and caches it under `~/.cache/awan`. No Rust

profile/README.md

@@ -210,4 +210,10 @@ fresh without you touching anything.
 - **Lyrics are yours** — put a couple of lines of your own favourite song in
   `lyrics`. The sample ships original placeholder lines.
 - The GIF is a few MB raw; shrink it with
-  `gifsicle -O3 --lossy=80 --colors 64 assets/awan.gif -o assets/awan.gif`.
+  `gifsicle -O3 --colors 64 assets/awan.gif -o assets/awan.gif`. No `--lossy`:
+  it bought about 6% and ghosted the 14px contribution squares.
+
+---
+
+Why it's built this way — the seam, the CI/binary split, the config's shape:
+[**docs/PROFILE.md**](../docs/PROFILE.md).

usage/README.md

@@ -1,9 +1,11 @@
-# Usage examples
+# Using awan from your code
 
-What is awan *for*? It's a **personality layer** for command-line tools — drop a
-little character into the moments your program already has (a long task running,
-a job finishing, a prompt redrawing) so the terminal feels alive instead of
-silent.
+awan is **a binary plus a text protocol**, not a library you link. Anything that
+can spawn a process and write a line can embed it — no SDK.
+
+These are the embed examples. The character most people meet is the one on a
+[profile README](https://codewithwan.github.io/awan/); this is the same engine,
+called from your own tool.
 
 Each folder is a **self-contained, runnable example** for one language, showing
 the same use case: *keep a companion on screen while a slow task runs, then