diff --git a/README.md b/README.md
index c90555e..5e84f16 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
-# writ
+<div align="center">
 
-[![CI](https://github.com/Laaaaksh/writ/actions/workflows/ci.yml/badge.svg)](https://github.com/Laaaaksh/writ/actions/workflows/ci.yml)
+<img src="docs/assets/writ-banner.svg" alt="writ" width="640">
+
+**writ** — why read the whole diff when only the drift matters?
 
 Today an agent writes code, opens a PR, and a human reads a large diff to decide whether to
 merge. That does not scale: the diff is too big to read and arrives stripped of the context
@@ -16,6 +18,23 @@ green verification, merges with no human at all.
 A writ that declares its scope as the whole repository makes drift meaningless, so writ
 refuses to accept one - at intake and again before any status or merge decision.
 
+[![Star this repo](https://img.shields.io/github/stars/Laaaaksh/writ?style=for-the-badge&logo=github&label=star%20this%20repo&color=yellow)](https://github.com/Laaaaksh/writ/stargazers)
+[![Built for agent workflows](https://img.shields.io/badge/built_for-agent_workflows-8957e5?style=for-the-badge&logo=githubactions&logoColor=white)](#the-loop-propose---approve---implement---attest---merge)
+
+[![CI](https://github.com/Laaaaksh/writ/actions/workflows/ci.yml/badge.svg)](https://github.com/Laaaaksh/writ/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Laaaaksh/writ/actions/workflows/codeql.yml/badge.svg)](https://github.com/Laaaaksh/writ/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/Laaaaksh/writ?color=green&display_name=tag)](https://github.com/Laaaaksh/writ/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-purple.svg)](LICENSE)
+[![Go](https://img.shields.io/badge/go-1.26+-00ADD8?logo=go&logoColor=white)](go.mod)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%E2%80%A2%20Linux-lightgrey)](#install)
+[![Homebrew](https://img.shields.io/badge/brew-laaaaksh%2Fwrit-orange?logo=homebrew)](#install)
+
+**[Install](#install) • [The loop](#the-loop-propose---approve---implement---attest---merge) • [Completions](#shell-completions) • [Exit codes](#exit-codes) • [Contributing](CONTRIBUTING.md) • [License](LICENSE)**
+
+**[Code of conduct](CODE_OF_CONDUCT.md) • [Contributing](CONTRIBUTING.md) • [License](LICENSE) • [Security](SECURITY.md)**
+
+</div>
+
 ## Install
 
 ```
@@ -141,3 +160,13 @@ For scripting and agents, `writ` signals its decision on the process exit code:
 Output stays script-friendly: ANSI color appears only when stdout is a terminal,
 and setting `NO_COLOR` (to any non-empty value) turns it off even then, so piped
 or captured output is always plain text.
+
+## Star this repo
+
+If `writ` makes reviewing agent PRs tractable, [leave a star](https://github.com/Laaaaksh/writ/stargazers) - it helps other people find it.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=Laaaaksh/writ&type=Date)](https://star-history.com/#Laaaaksh/writ&Date)
+
+## License
+
+MIT - see [LICENSE](LICENSE).
diff --git a/docs/assets/writ-banner.svg b/docs/assets/writ-banner.svg
new file mode 100644
index 0000000..0ca46a2
--- /dev/null
+++ b/docs/assets/writ-banner.svg
@@ -0,0 +1,105 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="668" height="300" viewBox="0 0 668 300" shape-rendering="crispEdges" role="img" aria-label="writ">
+<rect width="668" height="300" rx="10" fill="#0d1117" stroke="#30363d" stroke-width="2"/>
+<rect width="668" height="44" rx="10" fill="#161b22"/>
+<rect y="42" width="668" height="2" fill="#30363d"/>
+<circle cx="22" cy="22" r="6" fill="#ff5f57"/>
+<circle cx="46" cy="22" r="6" fill="#febc2e"/>
+<circle cx="70" cy="22" r="6" fill="#28c840"/>
+<text x="334" y="26" text-anchor="middle" font-family="menlo, monospace" font-size="13" fill="#8b949e">writ — zsh — 80×24</text>
+<rect x="68" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="80" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="92" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="104" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="116" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="128" y="100" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="112" width="12" height="12" fill="#e6edf3"/>
+<rect x="140" y="112" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="124" width="12" height="12" fill="#e6edf3"/>
+<rect x="80" y="124" width="12" height="12" fill="#6e7681"/>
+<rect x="92" y="124" width="12" height="12" fill="#6e7681"/>
+<rect x="104" y="124" width="12" height="12" fill="#6e7681"/>
+<rect x="116" y="124" width="12" height="12" fill="#6e7681"/>
+<rect x="140" y="124" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="136" width="12" height="12" fill="#e6edf3"/>
+<rect x="140" y="136" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="148" width="12" height="12" fill="#e6edf3"/>
+<rect x="80" y="148" width="12" height="12" fill="#6e7681"/>
+<rect x="92" y="148" width="12" height="12" fill="#6e7681"/>
+<rect x="104" y="148" width="12" height="12" fill="#6e7681"/>
+<rect x="116" y="148" width="12" height="12" fill="#6e7681"/>
+<rect x="140" y="148" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="160" width="12" height="12" fill="#e6edf3"/>
+<rect x="140" y="160" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="172" width="12" height="12" fill="#e6edf3"/>
+<rect x="80" y="172" width="12" height="12" fill="#6e7681"/>
+<rect x="92" y="172" width="12" height="12" fill="#6e7681"/>
+<rect x="104" y="172" width="12" height="12" fill="#6e7681"/>
+<rect x="116" y="172" width="12" height="12" fill="#6e7681"/>
+<rect x="140" y="172" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="184" width="12" height="12" fill="#e6edf3"/>
+<rect x="140" y="184" width="12" height="12" fill="#e6edf3"/>
+<rect x="56" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="68" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="80" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="92" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="104" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="116" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="128" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="140" y="196" width="12" height="12" fill="#e6edf3"/>
+<rect x="104" y="208" width="12" height="12" fill="#f85149"/>
+<rect x="116" y="208" width="12" height="12" fill="#f85149"/>
+<rect x="128" y="208" width="12" height="12" fill="#f85149"/>
+<rect x="92" y="220" width="12" height="12" fill="#f85149"/>
+<rect x="104" y="220" width="12" height="12" fill="#f85149"/>
+<rect x="116" y="220" width="12" height="12" fill="#f85149"/>
+<rect x="128" y="220" width="12" height="12" fill="#f85149"/>
+<rect x="92" y="232" width="12" height="12" fill="#f85149"/>
+<rect x="104" y="232" width="12" height="12" fill="#f85149"/>
+<rect x="116" y="232" width="12" height="12" fill="#f85149"/>
+<rect x="284" y="118" width="12" height="12" fill="#ff7b72"/>
+<rect x="332" y="118" width="12" height="12" fill="#ff7b72"/>
+<rect x="284" y="130" width="12" height="12" fill="#ff7b72"/>
+<rect x="332" y="130" width="12" height="12" fill="#ff7b72"/>
+<rect x="284" y="142" width="12" height="12" fill="#ff7b72"/>
+<rect x="308" y="142" width="12" height="12" fill="#ff7b72"/>
+<rect x="332" y="142" width="12" height="12" fill="#ff7b72"/>
+<rect x="284" y="154" width="12" height="12" fill="#ff7b72"/>
+<rect x="308" y="154" width="12" height="12" fill="#ff7b72"/>
+<rect x="332" y="154" width="12" height="12" fill="#ff7b72"/>
+<rect x="296" y="166" width="12" height="12" fill="#ff7b72"/>
+<rect x="320" y="166" width="12" height="12" fill="#ff7b72"/>
+<rect x="356" y="118" width="12" height="12" fill="#e3b341"/>
+<rect x="368" y="118" width="12" height="12" fill="#e3b341"/>
+<rect x="380" y="118" width="12" height="12" fill="#e3b341"/>
+<rect x="392" y="118" width="12" height="12" fill="#e3b341"/>
+<rect x="356" y="130" width="12" height="12" fill="#e3b341"/>
+<rect x="404" y="130" width="12" height="12" fill="#e3b341"/>
+<rect x="356" y="142" width="12" height="12" fill="#e3b341"/>
+<rect x="368" y="142" width="12" height="12" fill="#e3b341"/>
+<rect x="380" y="142" width="12" height="12" fill="#e3b341"/>
+<rect x="392" y="142" width="12" height="12" fill="#e3b341"/>
+<rect x="356" y="154" width="12" height="12" fill="#e3b341"/>
+<rect x="392" y="154" width="12" height="12" fill="#e3b341"/>
+<rect x="356" y="166" width="12" height="12" fill="#e3b341"/>
+<rect x="404" y="166" width="12" height="12" fill="#e3b341"/>
+<rect x="428" y="118" width="12" height="12" fill="#56d364"/>
+<rect x="440" y="118" width="12" height="12" fill="#56d364"/>
+<rect x="452" y="118" width="12" height="12" fill="#56d364"/>
+<rect x="440" y="130" width="12" height="12" fill="#56d364"/>
+<rect x="440" y="142" width="12" height="12" fill="#56d364"/>
+<rect x="440" y="154" width="12" height="12" fill="#56d364"/>
+<rect x="428" y="166" width="12" height="12" fill="#56d364"/>
+<rect x="440" y="166" width="12" height="12" fill="#56d364"/>
+<rect x="452" y="166" width="12" height="12" fill="#56d364"/>
+<rect x="476" y="118" width="12" height="12" fill="#58a6ff"/>
+<rect x="488" y="118" width="12" height="12" fill="#58a6ff"/>
+<rect x="500" y="118" width="12" height="12" fill="#58a6ff"/>
+<rect x="512" y="118" width="12" height="12" fill="#58a6ff"/>
+<rect x="524" y="118" width="12" height="12" fill="#58a6ff"/>
+<rect x="500" y="130" width="12" height="12" fill="#58a6ff"/>
+<rect x="500" y="142" width="12" height="12" fill="#58a6ff"/>
+<rect x="500" y="154" width="12" height="12" fill="#58a6ff"/>
+<rect x="500" y="166" width="12" height="12" fill="#58a6ff"/>
+<text x="284" y="210" font-family="menlo, monospace" font-size="22" fill="#56d364">❯ writ propose</text>
+<rect x="456" y="192" width="12" height="22" fill="#56d364"/>
+</svg>