docs: rewrite README and add MIT license

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tai Sakuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,58 +1,76 @@
 # improved-octo-fortnight
 
-A reference implementation of a documentation workflow using [zensical](https://zensical.org/) and GitHub Pages.
+[![GitHub Release][release-badge]][release-url]
+[![GitHub Pages][pages-badge]][pages-url]
 
-- [latest](https://taisakuma.github.io/improved-octo-fortnight/latest/)
-- [dev](https://taisakuma.github.io/improved-octo-fortnight/dev/)
+[![Deploy dev docs][dev-badge]][dev-url]
+[![Deploy release docs][release-docs-badge]][release-docs-url]
+[![Deploy docs preview][preview-badge]][preview-url]
+
+[release-badge]: https://img.shields.io/github/v/release/TaiSakuma/improved-octo-fortnight
+[release-url]: https://github.com/TaiSakuma/improved-octo-fortnight/releases/latest
+[pages-badge]: https://img.shields.io/website?url=https://taisakuma.github.io/improved-octo-fortnight/
+[pages-url]: https://taisakuma.github.io/improved-octo-fortnight/
+[dev-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-dev.yml/badge.svg
+[dev-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-dev.yml
+[release-docs-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-release.yml/badge.svg
+[release-docs-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-release.yml
+[preview-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml/badge.svg
+[preview-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml
+
+A reference implementation of documentation workflows.
+
+📚 [Demo site](https://taisakuma.github.io/improved-octo-fortnight/)
 
 ## Features
 
-- **Versioned docs** -- Release docs at `/<version>/`, dev docs at `/dev/`, and a `/latest/` alias
-- **PR previews** -- Every PR gets a preview deployment at `/pr/<number>/` with an automatic comment linking to it
-- **PR cleanup** -- Preview deployments are removed when PRs are closed
-- **Version index** -- An auto-generated root `index.html` lists all available versions
-- **Deploy verification** -- The preview URL is polled before posting the PR comment; a note is added if the site isn't ready yet
-- **Custom domain support** -- Works with both default GitHub Pages URLs and custom domains
-- **API reference** -- Auto-generated from Python docstrings using [mkdocstrings](https://mkdocstrings.github.io/). Add `:::` directives in Markdown to render any module (see `docs/api.md` for an example)
+### Content
 
-## How it works
+- Built with [zensical](https://zensical.org/)
+- API reference auto-generated using [mkdocstrings](https://mkdocstrings.github.io/)
 
-Documentation is built with [zensical](https://zensical.org/) and deployed by pushing subdirectories to a `gh-pages` branch. Four workflows handle the different deployment scenarios:
+This repo documents a Python package. The setup should work for other languages with minor modifications.
 
-| Workflow              | Trigger                          | Deploys to                                |
-| --------------------- | -------------------------------- | ----------------------------------------- |
-| `docs-dev.yml`        | Push to `main`                   | `/dev/`                                   |
-| `docs-release.yml`    | Release (via changelog workflow) | `/<version>/` + `/latest/` + `index.html` |
-| `docs-pr-preview.yml` | PR opened/updated (incl. forks)  | `/pr/<number>/`                           |
-| `docs-pr-cleanup.yml` | PR closed                        | removes `/pr/<number>/`                   |
+### Deployment
 
-The `gh-pages` branch has the following structure:
+- Deployed to [GitHub Pages](https://pages.github.com/) via [GitHub
+  Actions](https://github.com/features/actions)
+- Separate docs for each release and development branch
+- Docs preview for each PR
 
-```
-gh-pages
-├── .nojekyll
+## GitHub Pages structure
+
+The deployed site is structured as follows:
+
+```text
+/
 ├── index.html          # auto-generated version index
 ├── latest/             # copy of the latest release
 ├── dev/                # built from main
-├── 0.2.1/              # release versions
-├── 0.2.0/
+├── 2.0.0/              # release versions
+├── 1.1.0/
+├── 1.0.0/
 └── pr/
     ├── 14/             # PR preview
     └── 13/
 ```
 
-Shared logic is extracted into two composite actions:
+## GitHub Actions workflows
+
+These workflows build, deploy, and clean up the documentation:
 
-- **`.github/actions/build-docs`** -- Overrides `site_url` for the target subdirectory, builds the site, and stages the output
-- **`.github/actions/deploy-to-gh-pages`** -- Checks out (or creates) the `gh-pages` branch and pushes the built site to a target subdirectory
+| Workflow                | Trigger           | Deploys to                              |
+| ----------------------- | ----------------- | --------------------------------------- |
+| [`docs-dev.yml`]        | Push to `main`    | `/dev/`, `index.html`                   |
+| [`docs-release.yml`]    | Release           | `/<version>/`, `/latest/`, `index.html` |
+| [`docs-pr-preview.yml`] | PR opened/updated | `/pr/<number>/`                         |
+| [`docs-pr-cleanup.yml`] | PR closed         | removes `/pr/<number>/`                 |
 
-A Python script (`.github/actions/build-docs/override_site_url.py`) uses [tomlkit](https://github.com/sdispater/tomlkit) to modify `site_url` in `zensical.toml` so that navigation and search work correctly in each subdirectory.
+[`docs-dev.yml`]: .github/workflows/docs-dev.yml
+[`docs-release.yml`]: .github/workflows/docs-release.yml
+[`docs-pr-preview.yml`]: .github/workflows/docs-pr-preview.yml
+[`docs-pr-cleanup.yml`]: .github/workflows/docs-pr-cleanup.yml
 
-## Setup
+The workflows require the GitHub settings
 
-1. Install [uv](https://docs.astral.sh/uv/)
-2. Build docs locally:
-   ```
-   uv run --group docs zensical serve
-   ```
-3. Set GitHub Pages source to **Deploy from a branch** > `gh-pages` (root `/`)
+- `Settings` > `Pages` > `Source` > `Deploy from a branch` > `gh-pages` (root `/`)