From a5c59eceb096649edc6ebb409c6a89c718d80c6a Mon Sep 17 00:00:00 2001 From: Kris Bennett <13557788+kbennett2000@users.noreply.github.com> Date: Sun, 21 Jun 2026 19:11:32 -0600 Subject: [PATCH] =?UTF-8?q?docs(repo):=20shine=20the=20front=20door=20?= =?UTF-8?q?=E2=80=94=20retro=20banner=20+=20zero-assumptions=20README=20(C?= =?UTF-8?q?ycle=2013)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the repo's front door welcoming to a zero-assumptions audience (including non-technical, nostalgia-driven visitors who may never have heard of Microsoft Agent). Docs/README/asset only — no code change; CI stays green. - assets/banner.svg: original retro Win9x-window banner (teal desktop, raised silver chrome, navy gradient title bar, generic speech balloon). Ships NO Microsoft/L&H imagery, no character pixels (IP rule holds). Drawn sparkles (not font glyphs) + own opaque background → crisp and light/dark-safe on GitHub. - README.md: full rewrite to the parked Vision & docs spec's voice + layout — plain-language "What is this?" + MS Agent history, "Try it in 60 seconds" (docker compose up mash), tiered onboarding (browser voice main path; authentic TruVoice an opt-in upgrade), honest "what you supply", developer pointer, credits. Nostalgia is deletable seasoning (hook + tagline + one aside). Minimal honest badges (no dead npm/CI). Later docs pages signposted at their canonical paths. - docs/cycles/cycle-13-repo-shine.md: the cycle (build-now/signpost table) + the paste-ready GitHub description + topics + social-preview PNG export steps. - docs/decisions/0025-repo-front-door.md: ADR for the front-door approach. Out of scope (signposted only): docs/ explainer + install + dev pages, the Playwright GIF/screenshot pipeline + gallery, community files, hosted demo deploy. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 208 +++++++++++++++++++++++-- assets/banner.svg | 78 ++++++++++ docs/cycles/cycle-13-repo-shine.md | 110 +++++++++++++ docs/decisions/0025-repo-front-door.md | 40 +++++ 4 files changed, 420 insertions(+), 16 deletions(-) create mode 100644 assets/banner.svg create mode 100644 docs/cycles/cycle-13-repo-shine.md create mode 100644 docs/decisions/0025-repo-front-door.md diff --git a/README.md b/README.md index fae7a17..20b3a3a 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,206 @@ -# vivify + +![vivify — Microsoft Agent characters, alive again in your browser](assets/banner.svg) -**Bring Microsoft Agent characters back to life in the browser — faithfully.** +![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg) +![Runs in your browser](https://img.shields.io/badge/runs%20in-your%20browser-008080) +![Status: feature-complete, pre-release](https://img.shields.io/badge/status-feature--complete-success) -Genie, Merlin, Peedy, Robby, Clippy, and any `.acs` character ever made: parsed, rendered, animated, and (optionally) speaking in their original TruVoice voice with real lip-sync. A framework-agnostic engine plus tooling, so you can drop a character into anything. +**Bring those animated characters from late-90s Windows back to life — right in your web browser.** -> 🚧 **Status: early development.** See `docs/roadmap.md`. +> _Before "Agent" had anything to do with AI… there were Genie, Merlin, and Clippy._ -## Packages -- `@vivify/core` — the engine (load / show / play / speak / moveTo / gestureAt / stop). Framework-agnostic. -- `@vivify/acs` — `.acs` parser + `acs2bundle` CLI. Runs in Node and the browser. -- `@vivify/voice-truvoice` — authentic-voice provider (talks to the voice server). -- `services/voice-server` — Dockerized Wine + SAPI4 + TruVoice → `{ audio, mouthTimeline }`. -- `apps/mash` — the MASH-style playground (demo + integration example). +--- + +## ▶ See it move + +There's no hosted click-to-try demo yet _(coming soon)_. But you can run the playground on your own +machine in about a minute — see **[Try it in 60 seconds](#-try-it-in-60-seconds)** below. It's a little +sandbox where you load a character, click its animations, and type to make it talk. + +> 🎬 _An animated preview (a character actually moving and talking) is on the way — it's generated from the +> live demo, which arrives in a later step._ + +--- + +## What is this? + +Back in the late 1990s, Microsoft made a thing called **Microsoft Agent**: little animated cartoon +helpers that lived on your Windows desktop. They walked around your screen, waved, talked out loud in a +synthesized voice, and showed a speech bubble with their words. The cast included **Genie** (a blue +genie), **Merlin** (a wizard), **Peedy** (a parrot), **Robby** (a robot), and the infamous **Clippy** (the +paperclip from Microsoft Office). + +Microsoft retired the technology in Windows 7, and it quietly disappeared. + +**vivify brings it back — faithfully — and runs it in a web browser.** It reads the original character +files, draws and animates the characters exactly as they were, shows their classic speech balloon, and can +even speak in their original voice. No old version of Windows required. Nothing to install on your +computer to just _look_ at it. + +> 💾 **Remember when…** software came on a stack of floppy disks, "downloading" meant going to make a +> sandwich, and a tiny cartoon would pop up to "help" you write a letter? Yeah. This brings _that_ back. + +#### A couple of words, in plain English + +- **`.acs` file** — the single file that holds one character: all its pictures, animations, and sounds. + (Microsoft's format. You supply your own — more on that below.) _A full glossary is coming in + [`docs/glossary.md`](docs/glossary.md)._ +- **Lip-sync** — the character's mouth moving in time with the words it speaks. + +--- + +## The cast + +The original four — **Genie, Merlin, Peedy, Robby** — plus Office favorites like **Clippy** and **Rover**, +and any other character anyone ever made. If it's a `.acs` file, vivify aims to run it. + +> 🖼️ _A picture gallery of the characters is coming once the demo-capture step lands._ + +--- + +## 🚀 Try it in 60 seconds + +The quickest way to see a character on your screen today. You'll need two free tools and one character +file. + +**1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/).** It's a free app that +runs the playground for you, so you don't have to set anything else up. _(Saw a scary-looking technical +message during install? Totally normal — just follow Docker's own prompts.)_ + +**2. Get this project and start the playground.** In a terminal, from this project's folder: + +```bash +docker compose up mash +``` + +Then open **http://localhost:8090** in your browser. That's the playground. _(The `mash` part means "just +the visual playground, no voice setup needed" — the authentic voice is a separate, optional upgrade you can +add later.)_ + +**3. Load a character.** The playground ships with **no** characters (those belong to their owners — see +[What you supply](#what-you-supply)). Grab a free classic one from the community archive linked in +[`docs/legal-and-assets.md`](docs/legal-and-assets.md), then drag the `.acs` file onto the playground. + +**That's it — it's alive!** Click any animation in the list to play it. Type a sentence and the character +shows its speech balloon. 🎉 + +> Want to hear the character's _real_ voice, not just see the balloon? That's the optional upgrade in +> [Want the real voice?](#want-the-real-voice) below. + +--- + +## Install & full guides + +Running the playground above is the fast path. When you're ready to set things up properly on your own +computer — including the authentic voice — there's a friendly, step-by-step guide for each operating +system: + +- 🪟 **Windows** → [`docs/install/windows.md`](docs/install/windows.md) _(coming soon)_ +- 🍎 **macOS** → [`docs/install/mac.md`](docs/install/mac.md) _(coming soon)_ +- 🐧 **Linux** → [`docs/install/linux.md`](docs/install/linux.md) _(coming soon)_ + +New to all of this? Start with the gentle overview: [`docs/getting-started.md`](docs/getting-started.md) +_(coming soon)_. + +--- + +## Want the real voice? + +Seeing the character is one thing. Hearing it speak in its **original synthesized voice**, with its mouth +moving to match, is the magic. + +That voice came from old Windows speech software that can't run in a browser directly, so vivify runs it in +a small background helper. It's a more involved, opt-in setup — completely separate from the quick +playground above — and there's a dedicated, hand-held walkthrough for it: + +➡️ **[The authentic voice — what it is and how to set it up](docs/voice/overview.md)** _(coming soon)_ + +> Don't need the original voice? The playground still talks using your browser's built-in voice, so you +> never hit a dead end. + +--- + +## For developers + +vivify isn't just a demo — it's a **framework-agnostic engine** you can drop into your own site or app +(React, Vue, Svelte, or plain JavaScript). The API mirrors the classic Agent control: `show`, `play`, +`speak`, `moveTo`, `gestureAt`, `stop`, with an action queue. -## Quick start (target API — not yet implemented) ```ts import { createAgent } from "@vivify/core"; -const genie = await createAgent("/agents/genie.acs"); // raw .acs or a prebuilt bundle +// Load a character from a raw .acs file's bytes (or pass a prebuilt bundle: { manifestUrl }). +const acs = await fetch("/agents/genie.acs").then((r) => r.arrayBuffer()); +const genie = await createAgent(acs); + await genie.show(); await genie.play("Greet"); -await genie.speak("You rubbed the lamp?"); +await genie.speak("You rubbed the lamp?"); // browser voice by default; authentic voice is opt-in ``` -## Authenticity & assets -The engine is MIT-licensed and ships **no** Microsoft/L&H binaries or character files. To get the authentic voice and the characters, you supply the original components yourself — see **[`docs/legal-and-assets.md`](docs/legal-and-assets.md)**. +By default, speech uses the browser's built-in voice — so this works with **nothing else installed**. The +authentic voice is a clearly-labeled upgrade. + +**The packages** (this is a pnpm monorepo): + +- **`@vivify/core`** — the engine: load / show / play / speak / moveTo / gestureAt / stop. No framework + dependency. +- **`@vivify/acs`** — the `.acs` parser + `acs2bundle` CLI. Runs in Node _and_ the browser. +- **`@vivify/voice-truvoice`** — the authentic-voice provider (talks to the voice server). +- **`services/voice-server`** — the Dockerized voice helper. +- **`apps/mash`** — the playground demo you ran above. + +Full developer docs are on the way: [`docs/developers/overview.md`](docs/developers/overview.md) and a +copy-paste [`docs/developers/quickstart.md`](docs/developers/quickstart.md) _(coming soon)_. The +architecture is documented today in [`docs/architecture.md`](docs/architecture.md), and the build plan in +[`docs/roadmap.md`](docs/roadmap.md). + +--- + +## What you supply + +vivify is free and open-source, and it ships **no** Microsoft files and **no** characters. To keep things +clean and legal, _you_ bring two things yourself: + +1. **Character files (`.acs`).** These are Microsoft's (and the community's) creations. You download the + ones you want from the community archive — vivify never redistributes them. +2. **The speech software** — only if you want the authentic voice. It's old, free Microsoft/L&H speech + software that you install into the voice helper. + +It's all explained, with exactly where to get each piece, in +**[`docs/legal-and-assets.md`](docs/legal-and-assets.md)** (and a friendlier consumer guide is coming in +[`docs/voice/sourcing-components.md`](docs/voice/sourcing-components.md)). + +> In short: the _engine_ is ours and open. The _characters and voices_ are their owners', and you supply +> your own copies. + +--- + +## More help + +- ❓ **FAQ** — "Is this legal?", "Why is there no sound?", "Which characters work?" → + [`docs/faq.md`](docs/faq.md) _(coming soon)_ +- 🛠️ **Troubleshooting** — common hiccups, per platform → [`docs/troubleshooting.md`](docs/troubleshooting.md) + _(coming soon)_ +- 📖 **Glossary** — every technical term, in plain English → [`docs/glossary.md`](docs/glossary.md) + _(coming soon)_ + +--- + +## Credits + +vivify stands on a lot of shoulders, gratefully: the original **Microsoft Agent** team who made these +characters; **DoubleAgent** (Cinnamon Software) and **Lebeau's MSAgent Decompiler** as references for the +`.acs` format; **clippy.js** for proving the characters could live again in a browser; **TETYYS/SAPI4** for +charting the path to the authentic voice; and **TMAFE** for keeping the character archive alive all these +years. A fuller credits page is coming in [`docs/credits.md`](docs/credits.md). + +--- ## License -MIT © Kris Bennett. The Microsoft Agent characters, the SAPI4/TruVoice engine, and related assets are the property of their respective owners and are **not** distributed by this project. + +MIT © Kris Bennett. + +vivify is **not** affiliated with or endorsed by Microsoft. The Microsoft Agent characters, the +SAPI4/TruVoice speech engine, and related assets are the property of their respective owners and are **not** +distributed by this project. diff --git a/assets/banner.svg b/assets/banner.svg new file mode 100644 index 0000000..811e773 --- /dev/null +++ b/assets/banner.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + vivify.exe + + + + vivify + + Microsoft Agent characters, alive again — right in your browser. + + + + + + + + + + + + + + diff --git a/docs/cycles/cycle-13-repo-shine.md b/docs/cycles/cycle-13-repo-shine.md new file mode 100644 index 0000000..9b1ac3b --- /dev/null +++ b/docs/cycles/cycle-13-repo-shine.md @@ -0,0 +1,110 @@ +# Cycle 13 — repo shine (banner + README + GitHub metadata) + +## Goal +The build is feature-complete (authentic TruVoice voice, dense lip-sync, pose stacking, Docker, disk TTS +cache), but the repo's front door is still a terse dev blurb. Make it **shine for a zero-assumptions +audience** — including non-technical, nostalgia-driven visitors who may never have heard "Microsoft +Agent." **Docs/README/asset only — no code change; CI stays green.** + +Voice/structure follow the parked **Vision & docs spec** (the project's north star, kept out of the repo). +Its non-negotiables govern this cycle: + +- **Assume nothing**; **simple, then simpler**; **when in doubt, more hand-holding**. +- **Nostalgia is seasoning, never the spine.** Every wink is _deletable_ without losing any instruction, + and lives only in set-off asides (the `💾 Remember when…` callout), the tagline, and the top hook. +- **Tiered onboarding**, always in this order: _see it → run it yourself (browser voice) → authentic + TruVoice (opt-in upgrade)_. The Wine/Docker voice path is **never** on the main road. +- Second person, present tense, encouraging. + +## Reconciliation: spec sequencing vs reality +The spec was written for a 12-cycle plan where docs/demo assets landed in its "Cycle 4/7." Reality: we're +feature-complete at Cycle 12, but there is **no hosted demo URL, no GIF/screenshot pipeline (Playwright is +a later cycle), npm is unpublished, and the `docs/` explainer pages don't exist yet.** So this cycle keeps +the spec's section **order + voice** and splits each into **build-now** vs **signpost-as-coming** — no +faked badges, no dead demo button, no invented screenshots. + +| README section (spec order) | This cycle | +| ----------------------------- | --------------------------------------------------------------------- | +| Banner | **now** — `assets/banner.svg` | +| Badges | **now, minimal** — license · runs-in-browser · status (no npm/CI) | +| One-liner + nostalgia hook | **now** | +| Live demo (hero CTA) | **adapted** — run MASH locally; hosted demo marked _coming_ | +| Animated GIF | **signpost** — _coming_ (Playwright capture is a later cycle) | +| "What is this?" + MS history | **now** — the heart of the zero-assumptions ask | +| Character gallery | **now (text list)** — thumbnails _coming_ | +| Try it in 60 seconds | **now** — `docker compose up mash` → upload `.acs` → play/talk | +| Install (3 platform pages) | **signpost** — `docs/install/{windows,mac,linux}.md` _coming_ | +| Want the real voice? | **signpost** — `docs/voice/overview.md` _coming_ | +| For developers | **now + signpost** — inline API snippet + `docs/developers/*` _coming_| +| FAQ / Troubleshooting / Glossary | **signpost** — _coming_ | +| What you supply (IP) | **now** — friendly, links existing `docs/legal-and-assets.md` | +| Credits | **now** — gracious acknowledgments; `docs/credits.md` _coming_ | +| License | **now** — MIT + not-affiliated / no-MS·L&H-IP line | + +Every _coming_ link points at the spec's **canonical** intended path, so the later docs cycles drop pages +into place with no link churn. + +## Deliverable 1 — banner (`assets/banner.svg`) +Original artwork evoking a late-90s desktop window: teal desktop backdrop, raised silver chrome with a +navy→blue gradient title bar (`vivify.exe`), min/max/close buttons, a large `vivify` wordmark + plain-text +tagline, and a generic speech balloon with a talking `•••` and sparkles. + +- **Format SVG** — crisp at any size; carries its **own opaque background** so it's legible on GitHub light + _and_ dark themes. +- **IP rule holds** — no Microsoft/Genie/Clippy imagery, no character pixels, no lamp (too Genie-adjacent); + only period UI furniture + typography + a generic chat bubble. +- **Font-robust** — decorative sparkles are **drawn shapes**, not Unicode glyphs, so nothing depends on the + viewer's installed fonts except the plain-Latin wordmark/tagline. Validated as well-formed XML. + +### Social-preview PNG (operator step) +The spec wants a **1280×640 PNG** for GitHub's social preview. No SVG rasterizer (`rsvg-convert`, +`inkscape`, ImageMagick, `sharp`, `cairosvg`) is available in the dev sandbox, and a docs-only cycle won't +add a dependency — so this is a quick operator step. Pick whichever tool you have: + +```bash +# one of: +rsvg-convert -w 1280 -h 640 assets/banner.svg -o assets/banner-social.png +inkscape assets/banner.svg --export-type=png -w 1280 -h 640 -o assets/banner-social.png +npx --yes svgexport assets/banner.svg assets/banner-social.png 1280:640 +``` + +Then set it in **GitHub → Settings → General → Social preview**. (The banner is 1280×320; exporting at +1280×640 letterboxes it with the teal background, which is fine.) + +## Deliverable 2 — README (`README.md`) +Full rewrite to the table above, in the spec's voice. Discipline applied: short sentences; jargon (`.acs`, +lip-sync) defined inline with a _coming_ glossary link; nostalgia confined to the hook, the tagline, and a +single `💾 Remember when…` aside — all deletable without touching an instruction. + +## Deliverable 3 — GitHub metadata (paste-ready — operator applies) +I can't set repo settings, so apply these by hand. + +**Description** (Settings → General, or the ⚙ by "About"): + +> Bring Microsoft Agent characters — Genie, Merlin, Clippy & friends — back to life in any browser. A +> faithful, framework-agnostic revival of the late-90s desktop assistant, voice and all. + +**Topics** (the "About" gear → Topics; ≤20): + +``` +microsoft-agent msagent clippy genie nostalgia retrocomputing 90s +typescript javascript browser text-to-speech tts sapi4 truvoice +lip-sync animation acs agent-character vintage-computing web-speech +``` + +**Homepage**: leave blank until a live demo is deployed. +**Social preview**: upload `assets/banner-social.png` (see Deliverable 1). + +## What is verified where +- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green — no code + touched; prettier covers the new/edited Markdown; the banner is valid XML. +- **Operator (eyeball + GitHub):** the README renders with the banner crisp on both light and dark themes; + every `docs/...` link either resolves to an existing file (`legal-and-assets.md`, `architecture.md`, + `roadmap.md`) or is clearly marked _coming_; the description + topics are pasted into GitHub; optionally + the social-preview PNG is exported and uploaded. + +## Non-goals (later cycles — signposted only) +The `docs/` explainer pages (getting-started, install/\*, characters, voice/\*, developers/\*, faq, +troubleshooting, glossary, credits); the Playwright screenshot/GIF pipeline + gallery thumbnails; community +files (CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / issue templates); the hosted live-demo deploy. No +code / `@vivify/core` / browser change. See ADR-0025 for the front-door approach. diff --git a/docs/decisions/0025-repo-front-door.md b/docs/decisions/0025-repo-front-door.md new file mode 100644 index 0000000..a0f51e4 --- /dev/null +++ b/docs/decisions/0025-repo-front-door.md @@ -0,0 +1,40 @@ +# ADR-0025: Repo front door — adopt the parked Vision & docs spec as the binding voice/structure authority, ship only what's real, signpost the rest at canonical paths, no polish-theater +Status: Accepted · Date: 2026-06-21 + +## Context +The build is feature-complete (Cycle 12: authentic TruVoice voice, dense lip-sync, pose stacking, Docker, disk TTS cache), but the repo's front door was still a terse dev blurb — useless to the audience we actually want: a zero-assumptions visitor, including non-technical, nostalgia-driven people who may never have heard "Microsoft Agent." + +A **Vision & docs spec** exists as the project's north star for all documentation and presentation — its voice rules (assume nothing; simpler-then-simpler; nostalgia is seasoning, never the spine; tiered onboarding; second person, present tense), its README section order, and its canonical `docs/` page layout. By choice, **that spec is not committed to the repo**; it is pasted in when a docs cycle needs it. + +The spec was written for a 12-cycle plan where docs/demo assets landed in its "Cycle 4/7." Reality diverges: we're feature-complete at Cycle 12, but there is **no hosted demo URL, no GIF/screenshot pipeline (Playwright is a later cycle), npm is unpublished, and the `docs/` explainer pages don't exist yet.** Cycle 13 (`docs/cycles/cycle-13-repo-shine.md`) implements the spec's README layout + voice + a banner for this audience — **docs/asset only, no code change** — and reconciles the spec's sequencing with that reality. + +## Decision + +**1. Adopt the parked Vision & docs spec as the binding voice/structure authority, even though it's not in the repo.** +The spec is the single north star for all doc work: this cycle and every later docs cycle (getting-started, install pages, voice pages, developer docs, FAQ/glossary/credits) reads in its voice and follows its section order and canonical page paths. It lives outside the repo by choice and is pasted in when needed. WHY: one authority for voice and structure prevents every docs cycle from re-litigating tone and layout; keeping it out of the repo is a deliberate call, so this ADR records that the authority is binding regardless of where the document physically sits. + +**2. Split the spec's README layout into build-now vs signpost-as-coming (reconcile spec sequencing with reality).** +The repo is past the spec's assumed sequencing, so the cycle keeps the spec's section **order + voice** and splits each section into **build-now** (banner, minimal badges, one-liner + hook, "what is this?", text character list, "try it in 60 seconds," inline developer snippet, "what you supply," credits, license) vs **signpost-as-coming** (GIF, install pages, voice overview, developer docs, FAQ/troubleshooting/glossary). Every _coming_ link points at the spec's **canonical** intended path (e.g. `docs/install/{windows,mac,linux}.md`, `docs/voice/overview.md`, `docs/developers/*`, `docs/glossary.md`). WHY: building only what's real now and linking the rest at the canonical paths means later cycles drop pages into place with **zero link churn**, and it avoids faked or dead content. + +**3. No faked badges, no dead demo button, no invented screenshots.** +Badges are minimal and honest: license (MIT), runs-in-browser, status (feature-complete, pre-release) — npm and CI badges are **omitted** because npm is unpublished and a CI badge would be dead. The hero CTA ("See it move") points to running MASH **locally** (`docker compose up mash` → `http://localhost:8090`) because there is no hosted demo; the animated GIF and the character gallery are **signposted as coming** (the Playwright capture pipeline is a later cycle). WHY: honesty over polish-theater — a dead button or a fake screenshot erodes trust with the exact zero-assumptions newcomer we're courting. + +**4. Tiered onboarding with the Wine/Docker authentic-voice path always OFF the main road.** +The README order is _see it → run it yourself (browser voice, nothing to install beyond Docker) → authentic TruVoice (opt-in upgrade)_. The quick playground is the main path; the authentic L&H/SAPI4 voice is a clearly-labeled upgrade on its own (coming) `docs/voice/overview.md` page, never inline on the main road. WHY: spec tension #1 — the involved Wine/Docker voice setup must never scare off a casual visitor, so its complexity is quarantined behind an explicit opt-in. + +**5. Nostalgia is deletable seasoning.** +Winks live only in the top hook, the tagline, and set-off `💾 Remember when…` asides; the instructional spine reads clean for someone who has never heard of Microsoft Agent — every wink is deletable without losing an instruction. WHY: spec tension #2 / hard rule — the front door must teach a true newcomer, with nostalgia as a bonus for those who get it, never a prerequisite. + +**6. Banner: original SVG artwork, no MS/L&H IP, font-robust, theme-safe; social-preview PNG is an operator step.** +`assets/banner.svg` evokes a late-90s desktop window — teal desktop, raised silver chrome, navy→blue gradient title bar (`vivify.exe`), min/max/close buttons, a `vivify` wordmark + plain-text tagline, and a generic speech balloon with a talking `•••` — using **only period UI furniture + typography**: no character pixels, no Genie lamp, no Microsoft/L&H imagery. Decorative sparkles are **drawn shapes** (a path `#spark`), not Unicode glyphs, so the art doesn't depend on the viewer's installed fonts (only the plain-Latin wordmark/tagline do). The SVG carries its **own opaque teal background**, so it stays legible on GitHub light _and_ dark themes. The 1280×640 social-preview PNG export is **deferred to the operator** because no SVG rasterizer is available in the sandbox and a docs-only cycle won't add a dependency. WHY: keeps the IP gate (ADR-0006 / `docs/legal-and-assets.md`), guarantees crisp rendering everywhere regardless of viewer fonts or theme, and avoids pulling in tooling for one image. + +## Consequences +- **The README ships what's real and signposts the rest at canonical paths.** Later docs cycles drop pages in with no link churn; the front door never shows a dead button, a faked badge, or an invented screenshot. The authentic-voice complexity stays off the main road, and nostalgia stays deletable — so a true newcomer can follow the spine. +- **This sets the voice precedent for all later docs cycles.** Every subsequent page (getting-started, install/\*, voice/\*, developers/\*, faq/glossary/credits) is written to the same parked spec's voice and structure recorded here; this ADR is the standing reference for why those pages read the way they do and live where they do. +- **Verification boundary (CI vs operator).** CI proves `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stay green with **no code touched** (prettier covers the new/edited Markdown) and that the banner is valid, well-formed XML. The **operator** verifies what CI cannot: the README renders with the banner crisp on **both** light and dark themes, every `docs/...` link either resolves to an existing file (`legal-and-assets.md`, `architecture.md`, `roadmap.md`) or is clearly marked _coming_, the GitHub description + topics are pasted in, and — optionally — the 1280×640 social-preview PNG is exported (`rsvg-convert` / `inkscape` / `svgexport`) and uploaded under Settings → Social preview. +- **No third-party IP.** The banner is original artwork built from generic period UI furniture and typography only — no character pixels, no MS/L&H imagery. No `.acs` files, engine binaries, or Wine prefix are committed. The repo's IP posture (ADR-0006) is preserved unchanged. + +## Related +- ADR-0006 — MIT license, zero bundled third-party IP; the IP gate the banner is built to respect. +- `docs/cycles/cycle-13-repo-shine.md` — the cycle this ADR records, including the build-now/signpost table, the paste-ready GitHub description/topics, and the operator verification steps. +- `docs/legal-and-assets.md` — the existing "what you supply" guide the README links for characters and the speech software.