Add a documentation site, and reduce the README to a landing page

[Korijn]

The README had grown to hold everything there is to know about keycmd, which made the one thing a landing page is for — seeing what this is and getting a first command to run — the hardest thing to find in it.

This moves the prose into an mkdocs-material site under docs/, arranged the way a command line tool is used rather than the way a library is read: no API reference and no mkdocstrings, and a reference section that is flags, environment variables, files and exit status instead.

Home                index.md
Getting Started     installation · quick-start
Guide               running-commands · configuration · keyring-backends · wsl · troubleshooting
Examples            openai · azure-artifacts
Reference           cli · configuration
Development         contributing · testing

Where each README section went

README	Now lives in
About, Quickstart	index.md, getting-started/
Installation, pyenv, up- and downgrading	getting-started/installation.md
WSL installation	guide/wsl.md, which covers the install and the boundary in one place
Usage	guide/running-commands.md, reference/cli.md
Configuration (locations, fields, format strings, aliases)	guide/configuration.md, reference/configuration.md
OpenAI example, Advanced example	examples/
Debugging configuration	guide/troubleshooting.md
Note on keyring backends, startup time	guide/keyring-backends.md
Development, Testing, Testing WSL	development/

Beyond re-homing, troubleshooting gained a "common problems" section keyed on the error strings keycmd actually prints (MISSING credential ..., MISSING alias key ..., no backend, the unquoted $SECRET mistake), and the platform and shell variants use tabs rather than stacked headings. The screenshots move to docs/assets/ so that docs/ is the site root.

The README is now roughly seventy lines: badges, a paragraph of pitch, install and config and run, five bullets on why, and a table of links into the site. Its CI badge pointed at clinicalgraphics/keycmd and now points here.

Supporting changes

• .github/workflows/docs.yml builds with --strict on pull requests, so a broken link or a page missing from the nav fails before it lands, and deploys to GitHub Pages on push to master.
• A docs dependency group, a Documentation project URL, site in .gitignore, and the docs commands and conventions in CLAUDE.md.
• The hint keycmd prints inside a distribution with no keyring daemon said "the README explains how to reach the windows credential manager". The README no longer does, so it prints the WSL page's URL instead.

Before merging

GitHub Pages has to be set to build from GitHub Actions in the repository settings, or the deploy job fails on its first run. The site URL is assumed to be korijn.github.io/keycmd, which is baked into mkdocs.yml, the README links and that error hint.

Verification

mkdocs build --strict clean, ruff check/ruff format --check clean, ty check --error-on-warning clean, and 156 passed / 16 skipped — the skips being the OS keyring and WSL tests this container cannot provide for.

---

Generated by Claude Code