From 19605d0862b874e4ac49b73743123793a3dca195 Mon Sep 17 00:00:00 2001 From: codewithwan Date: Fri, 17 Jul 2026 00:36:46 +0700 Subject: [PATCH] docs: make every page tell the same story MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The front door changed and six pages didn't follow. Two of them contradicted themselves on the same screen: npm and PyPI shipped package descriptions saying 'walks your GitHub contribution year' above READMEs still saying 'a personality layer any CLI can embed'. I wrote the first half yesterday and left the second. usage/README opened with 'What is awan *for*?' and answered with the old pitch. It's the embed examples — it says that now, and points at the profile for what most people came for. crates/awan/README keeps 'personality layer any CLI can embed'. That crate *is* the embed API; it's the one page where the old sentence was never wrong. docs/PROFILE.md was orphaned — nothing linked it, and it still described the core as 'the personality-layer CLI'. It's design notes, so it now says so at the top, points users at profile/ and the editor instead, and profile/ links back to it for anyone changing the thing. And one real bug: profile/README still told readers to run gifsicle with --lossy=80. We dropped that flag because it ghosted the 14px contribution squares for a 6% saving. Anyone following the docs was damaging their own GIF. --- README.md | 28 +++++++++++++++------------- docs/PROFILE.md | 12 ++++++++---- packages/npm/README.md | 11 ++++------- packages/pypi/README.md | 10 ++++------ profile/README.md | 8 +++++++- usage/README.md | 12 +++++++----- 6 files changed, 45 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 5117905..de6397a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ A tiny pixel character that walks your GitHub contribution year.

- awan walking a contribution year on a GitHub profile + awan walking a real contribution year, then reacting to it

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. -

- awan telling a profile's story, with that profile's real numbers -

- -

- - 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 — yours would be, nightly. - -

- **[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. --- +

+ awan introducing awan, with this repo's own live numbers +

+ +

+ + 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. + +

+ +--- + Heritage: the engine began as `idl pet` (Go) inside the [IDCloud](https://idcloud.app) CLI; awan is its standalone, embeddable second life. diff --git a/docs/PROFILE.md b/docs/PROFILE.md index b2de7fb..7a2d543 100644 --- a/docs/PROFILE.md +++ b/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 diff --git a/packages/npm/README.md b/packages/npm/README.md index da65640..78a86b7 100644 --- a/packages/npm/README.md +++ b/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. diff --git a/packages/pypi/README.md b/packages/pypi/README.md index f504c26..d364d78 100644 --- a/packages/pypi/README.md +++ b/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 diff --git a/profile/README.md b/profile/README.md index 2d0e068..b0219d8 100644 --- a/profile/README.md +++ b/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). diff --git a/usage/README.md b/usage/README.md index e944953..b146884 100644 --- a/usage/README.md +++ b/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