From ea05f7a9089e4ebe5ed322880c6dee1367e9d505 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 20:58:25 +0000
Subject: [PATCH] Docs: install from PyPI, with badges and upgrade steps

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8Qs752onkG5wP4feFsWjQ
---
 README.md               | 12 ++++++++++--
 docs/getting-started.md | 28 +++++++++++++++++++++++++---
 docs/index.md           |  2 +-
 zensical.toml           |  4 ++++
 4 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 9a6fd3c..d92c052 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,12 @@
 
 The dictionary and toolkit for the **grid script**: how humans write down what Ross 128 b sends, in InterImm's *The Contact Era*.
 
-**Docs:** https://interimm.github.io/glyph-cli/
+[![PyPI](https://img.shields.io/pypi/v/glyph-cli)](https://pypi.org/project/glyph-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/glyph-cli)](https://pypi.org/project/glyph-cli/)
+[![CI](https://github.com/InterImm/glyph-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/InterImm/glyph-cli/actions/workflows/ci.yml)
+[![Docs](https://github.com/InterImm/glyph-cli/actions/workflows/docs.yml/badge.svg)](https://interimm.github.io/glyph-cli/)
+
+**Docs:** https://interimm.github.io/glyph-cli/ · **PyPI:** https://pypi.org/project/glyph-cli/
 
 ```sh
 uvx --from glyph-cli glyph show BODY.OTHER STAR.TIME COUNT.137
@@ -19,11 +24,14 @@ uvx --from glyph-cli glyph show BODY.OTHER STAR.TIME COUNT.137
 
 ## Install
 
+`glyph` is on [PyPI](https://pypi.org/project/glyph-cli/) as `glyph-cli`:
+
 ```sh
 uv tool install glyph-cli    # or: pipx install glyph-cli, or: pip install glyph-cli
+glyph --version
 ```
 
-Python 3.10 or newer, no other dependencies.
+Upgrade with `uv tool upgrade glyph-cli` (or `pipx upgrade glyph-cli`, `pip install -U glyph-cli`). Python 3.10 or newer, no other dependencies.
 
 ## Use
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a5b808e..b25dbaa 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -2,7 +2,7 @@
 
 ## Install
 
-`glyph` needs Python 3.10 or newer and has no other dependencies.
+`glyph` is published on [PyPI](https://pypi.org/project/glyph-cli/) as **`glyph-cli`** (the command it installs is `glyph`). It needs Python 3.10 or newer and has no other dependencies.
 
 === "uv"
 
@@ -22,14 +22,36 @@
     pip install glyph-cli
     ```
 
-The latest code on `main` installs with `uv tool install git+https://github.com/InterImm/glyph-cli`.
-
 Check it works:
 
 ```sh
 glyph --version
 ```
 
+To get a newer release later:
+
+=== "uv"
+
+    ```sh
+    uv tool upgrade glyph-cli
+    ```
+
+=== "pipx"
+
+    ```sh
+    pipx upgrade glyph-cli
+    ```
+
+=== "pip"
+
+    ```sh
+    pip install -U glyph-cli
+    ```
+
+!!! tip "Unreleased changes"
+    PyPI has the latest release. To try what is on `main` before it is released, install from GitHub instead:
+    `uv tool install git+https://github.com/InterImm/glyph-cli`.
+
 ## Look at the parts
 
 Everything is built from 16 parts, each a 3×3 shape.
diff --git a/docs/index.md b/docs/index.md
index fe6bd1c..5aa0832 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,7 +25,7 @@ uvx --from glyph-cli glyph show BODY.OTHER STAR.TIME COUNT.137
   COUNT.137: 137
 ```
 
-Then follow [Getting started](getting-started.md).
+`uvx` fetches [`glyph-cli` from PyPI](https://pypi.org/project/glyph-cli/) and runs it. To keep the `glyph` command, install it with `uv tool install glyph-cli` (or `pipx install glyph-cli`, or `pip install glyph-cli`), then follow [Getting started](getting-started.md).
 
 ## What it does
 
diff --git a/zensical.toml b/zensical.toml
index 6dfec46..cd2a0e3 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -54,6 +54,10 @@ toggle.name = "Switch to dark mode"
 icon = "fontawesome/brands/github"
 link = "https://github.com/InterImm/glyph-cli"
 
+[[project.extra.social]]
+icon = "fontawesome/brands/python"
+link = "https://pypi.org/project/glyph-cli/"
+
 [project.markdown_extensions]
 admonition = {}
 attr_list = {}