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.