diff --git a/.env.example b/.env.example index 501c78f..c693ccd 100644 --- a/.env.example +++ b/.env.example @@ -1,34 +1,46 @@ -# StarPunk Configuration Template -# Copy this file to .env and fill in your values -# DO NOT commit .env to version control +# StarPunk configuration template (v2.10.1) +# +# Copy to .env and fill in your values. DO NOT commit .env. +# Every variable here is read by starpunk/config.py. Uncommented lines are +# the ones you normally set; commented lines show the built-in default and +# only need uncommenting to change it. Real environment variables take +# precedence over .env. # ============================================================================= -# SITE CONFIGURATION +# SITE # ============================================================================= -# Public URL where your site is hosted (no trailing slash) +# Public URL of the site (a trailing slash is added if missing) +# (default: http://localhost:5000) SITE_URL=http://localhost:5000 - -# Your site name (appears in RSS feed and page titles) +# Site name: page titles and feeds (default: StarPunk) SITE_NAME=My StarPunk Site - -# Your name (appears as author in RSS feed) +# Author name; must be non-empty but is not currently displayed: pages use +# the h-card discovered at ADMIN_ME (default: Unknown) SITE_AUTHOR=Your Name - -# Site description (appears in RSS feed) +# Feed description (default: A minimal IndieWeb CMS) SITE_DESCRIPTION=My personal IndieWeb site # ============================================================================= # AUTHENTICATION # ============================================================================= -# Your identity URL (REQUIRED) -# Your personal website. Used as the author h-card source and as the "me" -# value in Micropub tokens. It should link to this site's IndieAuth metadata -# (see docs/decisions/ADR-064) so Micropub apps can find StarPunk. +# Your identity URL (REQUIRED unless DEV_MODE=true). Used as the author h-card +# source and as the "me" of Micropub tokens. It should link to this site's +# IndieAuth metadata so Micropub apps can find StarPunk (ADR-064). ADMIN_ME=https://your-website.com -# Admin login via OpenID Connect (REQUIRED in production) +# Session secret (REQUIRED: the app refuses to start without it) +# Generate with: python3 -c "import secrets; print(secrets.token_hex(32))" +SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET + +# Flask secret key (default: SESSION_SECRET) +# FLASK_SECRET_KEY= + +# Admin session lifetime in days (default: 30) +# SESSION_LIFETIME=30 + +# Admin login via OpenID Connect (all four REQUIRED unless DEV_MODE=true) # Register StarPunk as a confidential client with your provider (e.g. Pocket ID) # using the callback URL: /auth/callback OIDC_ISSUER=https://id.example.com @@ -37,118 +49,168 @@ OIDC_CLIENT_SECRET= # The provider's subject ("sub") of the one account allowed to log in. # Pocket ID: the user's ID shown in the admin user list. OIDC_ADMIN_SUB= -# Name shown on the login button (default: "single sign-on") +# Name shown on the login button (default: single sign-on) OIDC_PROVIDER_NAME=Pocket ID -# Session secret key (REQUIRED - GENERATE A RANDOM VALUE) -# Generate with: python3 -c "import secrets; print(secrets.token_hex(32))" -SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET - -# Session lifetime in days (default: 30) -SESSION_LIFETIME=30 - -# Lifetime of Micropub access tokens StarPunk issues, in days (default: 90) -INDIEAUTH_TOKEN_LIFETIME_DAYS=90 +# Lifetime of the Micropub access tokens StarPunk's IndieAuth server issues, +# in days (default: 90) +# INDIEAUTH_TOKEN_LIFETIME_DAYS=90 # ============================================================================= -# CROSSPOSTING (optional, v2.1.0) +# DATA STORAGE (the container image sets /data, /data/notes, /data/starpunk.db) # ============================================================================= -# GoToSocial or Mastodon account to copy new notes to. Create an app token -# with scopes: write:statuses write:media -GOTOSOCIAL_URL= -GOTOSOCIAL_ACCESS_TOKEN= -# Name shown in the editor and Micropub apps (default: GoToSocial) -GOTOSOCIAL_NAME=GoToSocial -# public, unlisted, private (default: public) -GOTOSOCIAL_VISIBILITY=public - -# Threads account (v2.6.0). A long-lived user token with threads_basic, -# threads_content_publish and threads_delete; StarPunk refreshes it daily and -# keeps the current one in DATA_PATH/threads_token.json. -# How to get one: docs/design/v2.6.0/2026-10-31-threads-crossposting.md -THREADS_ACCESS_TOKEN= -# Your Threads username (for the Micropub syndicate-to uid) -THREADS_USERNAME= - -# ============================================================================= -# DATA STORAGE -# ============================================================================= - -# Base data directory (relative to project root) +# Base data directory: notes (DATA_PATH/notes), media, logs, +# threads_token.json (default: ./data) DATA_PATH=./data - -# Notes directory (where markdown files are stored) +# Created at startup; note files are always written under DATA_PATH/notes, +# so keep this equal to that (default: ./data/notes) NOTES_PATH=./data/notes - -# SQLite database path +# SQLite database (default: ./data/starpunk.db) DATABASE_PATH=./data/starpunk.db # ============================================================================= -# FLASK CONFIGURATION +# FLASK / LOGGING # ============================================================================= -# Environment: development or production +# development or production (default: development) FLASK_ENV=development - -# Debug mode: 1 (on) or 0 (off) -# NEVER use debug mode in production +# 1 = debug on, 0 = off (default: 1). Set 0 in production. FLASK_DEBUG=1 - -# Flask secret key (falls back to SESSION_SECRET if not set) -FLASK_SECRET_KEY= +# DEBUG, INFO, WARNING, ERROR or CRITICAL (default: INFO) +LOG_LEVEL=INFO +# Overrides the version shown in the footer and /health (default: the +# package version, starpunk.__version__). Normally leave unset. +# VERSION= # ============================================================================= -# RSS FEED CONFIGURATION +# DEVELOPMENT LOGIN (never in production) # ============================================================================= -# Maximum number of items in RSS feed (default: 50) -FEED_MAX_ITEMS=50 - -# Feed cache duration in seconds (default: 300 = 5 minutes) -FEED_CACHE_SECONDS=300 +# DEV_MODE=true adds /dev/login, which logs you in as DEV_ADMIN_ME without +# OIDC, and makes ADMIN_ME and OIDC_* optional (default: false) +# DEV_MODE=false +# Identity used by /dev/login (required when DEV_MODE=true) +# DEV_ADMIN_ME=http://localhost:5000/ # ============================================================================= -# CONTAINER CONFIGURATION +# REVERSE PROXY # ============================================================================= -# Environment: development or production -ENVIRONMENT=production - -# Number of Gunicorn workers (default: 4) -# Recommendation: (2 x CPU cores) + 1 -WORKERS=4 - -# Worker timeout in seconds (default: 30) -WORKER_TIMEOUT=30 - -# Max requests per worker before restart (prevents memory leaks) -MAX_REQUESTS=1000 - # Behind a reverse proxy (Caddy, nginx): take the client address from # X-Forwarded-For. Without it every visitor shares the proxy's address, so one # busy client can rate-limit everyone on /webmention and /websub. # Only enable when the proxy sets X-Forwarded-For itself (Caddy does). -TRUSTED_PROXY=true +# (default: false) +TRUSTED_PROXY=false + +# ============================================================================= +# FEEDS +# ============================================================================= + +# Items per feed (default: 50) +# FEED_MAX_ITEMS=50 +# Feed cache lifetime in seconds; changes to notes clear it (default: 300) +# FEED_CACHE_SECONDS=300 +# FEED_CACHE_ENABLED=true +# Cached feed variants kept (default: 50) +# FEED_CACHE_MAX_SIZE=50 + +# ============================================================================= +# WEBMENTION +# ============================================================================= + +# Receive webmentions at /webmention (default: true) +# WEBMENTION_ENABLED=true +# Background worker that verifies received webmentions and sends outgoing +# ones (default: true) +# WEBMENTION_WORKER_ENABLED=true +# Seconds between queue checks (default: 10) and after an error (default: 60) +# WEBMENTION_POLL_INTERVAL=10 +# WEBMENTION_ERROR_BACKOFF=60 +# Items per worker pass (default: 5) +# WEBMENTION_BATCH_SIZE=5 +# Show verified mentions without moderation (default: true) +# WEBMENTION_AUTO_APPROVE=true +# Rate limits on /webmention: requests per window per client IP (default: 60) +# and per source domain (default: 10); window in seconds (default: 60) +# WEBMENTION_RATE_LIMIT_ENABLED=true +# WEBMENTION_RATE_LIMIT_IP=60 +# WEBMENTION_RATE_LIMIT_DOMAIN=10 +# WEBMENTION_RATE_LIMIT_WINDOW=60 # ============================================================================= # WEBSUB (v2.10.0) # ============================================================================= # Built-in hub at /websub for this site's feeds. Set WEBSUB_HUB_URL to use -# another hub instead (StarPunk then pings it on changes). +# another hub instead (StarPunk then pings it on changes). (default: true) WEBSUB_ENABLED=true # WEBSUB_HUB_URL=https://hub.example.com/ +# Subscriptions in total, pending included (default: 1000) # WEBSUB_MAX_SUBSCRIPTIONS=1000 -# Per callback server (resolved address) +# Per callback server (resolved address) (default: 25) # WEBSUB_MAX_PER_HOST=25 +# Seconds between hub worker passes (default: 5) +# WEBSUB_POLL_INTERVAL=5 # ============================================================================= -# DEVELOPMENT OPTIONS +# CROSSPOSTING / POSSE (optional; a target is enabled when its credentials +# are set) # ============================================================================= -# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL -LOG_LEVEL=INFO +# GoToSocial or any Mastodon-API server (v2.1.0, ADR-065). Create an app +# token with scopes: write:statuses write:media, plus read:search +# write:favourites for native likes and boosts (v2.5.0) +GOTOSOCIAL_URL= +GOTOSOCIAL_ACCESS_TOKEN= +# Name shown in the editor and Micropub apps (default: GoToSocial) +# GOTOSOCIAL_NAME=GoToSocial +# public, unlisted or private (default: public) +# GOTOSOCIAL_VISIBILITY=public +# Server limits (defaults: 5000 characters, 4 images) +# GOTOSOCIAL_MAX_CHARS=5000 +# GOTOSOCIAL_MAX_MEDIA=4 -# Enable SQL query logging (development only) -SQL_ECHO=0 +# Bluesky (v2.2.0, ADR-066). Use an app password, not your account password. +BLUESKY_HANDLE= +BLUESKY_APP_PASSWORD= +# PDS / entryway (default: https://bsky.social) +# BLUESKY_SERVICE=https://bsky.social +# BLUESKY_NAME=Bluesky +# BLUESKY_MAX_CHARS=300 + +# Threads (v2.6.0, ADR-069). A long-lived user token with threads_basic, +# threads_content_publish and threads_delete; StarPunk refreshes it daily and +# keeps the current one in DATA_PATH/threads_token.json. +# How to get one: docs/design/v2.6.0/2026-10-31-threads-crossposting.md +THREADS_ACCESS_TOKEN= +# Your Threads username (for the Micropub syndicate-to uid) +THREADS_USERNAME= +# THREADS_NAME=Threads +# THREADS_MAX_CHARS=500 +# THREADS_MAX_MEDIA=4 + +# Seconds between syndication worker passes (default: 10) +# SYNDICATION_POLL_INTERVAL=10 + +# ============================================================================= +# MONITORING +# ============================================================================= + +# Metrics shown on /admin/metrics-dashboard (default: true) +# METRICS_ENABLED=true +# Queries slower than this many seconds are logged (default: 1.0) +# METRICS_SLOW_QUERY_THRESHOLD=1.0 +# Fraction of operations recorded, 0.0-1.0 (default: 1.0) +# METRICS_SAMPLING_RATE=1.0 +# METRICS_BUFFER_SIZE=1000 +# Seconds between memory samples (default: 30) +# METRICS_MEMORY_INTERVAL=30 + +# Keep uploads that fail processing in DATA_PATH/debug for diagnosis +# (default: false); cleaned up by age (default: 7 days) and total size +# (default: 100 MB) +# DEBUG_SAVE_FAILED_UPLOADS=false +# DEBUG_FILE_MAX_AGE_DAYS=7 +# DEBUG_FILE_MAX_SIZE_MB=100 diff --git a/CLAUDE.md b/CLAUDE.md index 0db3af0..61d2c33 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,11 @@ This file contains operational instructions for Claude agents working on this pr - We use **uv** for Python virtual environment management - All Python commands must be run with `uv run` prefix -- Example: `uv run pytest`, `uv run flask run` +- Example: `uv run pytest`, `uv run flask --app app.py run --debug` +- There is no `pyproject.toml`: create the environment with `uv venv --python 3.11 && uv pip install -r requirements-dev.txt` +- Tests need `SESSION_SECRET` set: `SESSION_SECRET=test uv run pytest`. The full suite takes about 6 minutes, 5 of them in `tests/test_migration_race_condition.py`; add `--ignore=tests/test_migration_race_condition.py` while iterating, but run everything before a release +- Local login without OIDC: `DEV_MODE=true` and `DEV_ADMIN_ME` in `.env`, then `/dev/login` +- Setup details: `docs/standards/development-setup.md` ## Agent Protocol (All Agents) @@ -42,12 +46,18 @@ When invoking the agent-developer, always remind it to: 4. **Version number management** - Increment version numbers according to `docs/standards/versioning-strategy.md` - - Update version in `starpunk/__init__.py` + - Update version in `starpunk/__init__.py` (both `__version__` and `__version_info__`) 5. **Follow git protocol** - Adhere to git branching strategy in `docs/standards/git-branching-strategy.md` - - Create feature branches for non-trivial changes - - Write clear commit messages + - Create feature branches for non-trivial changes, in their own git worktree (`/vX.Y.Z-description`, prefixes `feat/`, `fix/`, `ci/`, `docs/`) + - Write clear commit messages (`feat: ... (vX.Y.Z)`) + +## Release Process + +Follow "Release process" in `docs/standards/git-branching-strategy.md`. In short: work in a worktree on a `feat/`/`fix/` branch → bump `__version__` and `__version_info__` → `CHANGELOG.md` entry → design note in `docs/design/vX.Y.Z/` (or ADR amendment) → full test suite → commit → `git merge --no-ff` into `main` ("Merge branch '' for vX.Y.Z release") → annotated tag `vX.Y.Z` → push `main` and the tag. CI (`.gitea/workflows/build-container.yml`) runs the tests and publishes the image; production is then updated from the separate Ansible deployment repository. Back up the database before deploying a release with a migration. + +Merging to `main`, tagging, pushing and deploying happen only when the project owner asks for a release. ## Documentation diff --git a/README.md b/README.md index 412eff5..152450c 100644 --- a/README.md +++ b/README.md @@ -1,207 +1,116 @@ # StarPunk -A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication. - -**Current Version**: 1.2.0 - -## Versioning - -StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/): -- Version format: `MAJOR.MINOR.PATCH` -- Current: `1.2.0` (stable release) -- Check version: `python -c "from starpunk import __version__; print(__version__)"` -- See changes: [CHANGELOG.md](CHANGELOG.md) -- Versioning strategy: [docs/standards/versioning-strategy.md](docs/standards/versioning-strategy.md) - -## Philosophy +A minimal, self-hosted, single-user IndieWeb site for publishing notes. +Flask, SQLite and markdown files; one container. "Every line of code must justify its existence. When in doubt, leave it out." -StarPunk is designed for a single user who wants to: -- Publish short notes to their personal website -- Own their content (notes stored as portable markdown files) -- Syndicate via RSS -- Support IndieWeb standards (Micropub, IndieAuth) -- Run on minimal resources +The current version is in [`starpunk/__init__.py`](starpunk/__init__.py); +what changed in each release is in [CHANGELOG.md](CHANGELOG.md). ## Features -- **File-based storage**: Notes are markdown files, owned by you -- **OIDC admin login**: Sign in through your identity provider (e.g. Pocket ID) -- **Built-in IndieAuth server**: Approve Micropub apps without a separate auth service -- **Micropub support**: Full W3C Micropub specification compliance -- **Media attachments**: Upload and display images with your notes -- **Microformats2**: Full h-entry, h-card, and h-feed markup for IndieWeb compatibility -- **Author discovery**: Automatic profile discovery from your IndieWeb identity -- **RSS, ATOM, JSON Feed**: Multiple syndication formats with Media RSS support -- **Custom slugs**: Control your note permalinks -- **No database lock-in**: SQLite for metadata, files for content -- **Self-hostable**: Run on your own server -- **Minimal dependencies**: Core dependencies, no build tools +**Publishing** +- Notes in markdown, stored as plain files with metadata in SQLite +- Admin editor with drafts, custom slugs, tags and photo uploads + (resized variants, HEIC/MPO converted to JPEG, captions) +- Post types: notes, titled posts, replies, likes, reposts and bookmarks +- Full-text search (SQLite FTS5) and tag pages -## Requirements +**IndieWeb** +- [Micropub](https://www.w3.org/TR/micropub/): create, update, delete and + undelete; media endpoint; `q=config`, `source`, `syndicate-to`, `category` +- Built-in [IndieAuth](https://indieauth.spec.indieweb.org/) server for + Micropub apps (consent screen, tokens, revocation, Connected Apps page) +- Admin login through any OpenID Connect provider (e.g. Pocket ID) +- [Webmention](https://www.w3.org/TR/webmention/): receiving (verified, + moderated, rate-limited) and sending; replies, likes and reposts shown on + each note +- [WebSub](https://www.w3.org/TR/websub/) with a built-in hub, so readers get + new posts within seconds +- [Microformats2](https://microformats.org/wiki/h-entry): h-entry, h-feed and + an h-card discovered from your own site -- Python 3.11 or higher -- 500MB disk space -- Linux, macOS, or Windows with WSL2 +**Syndication** +- Feeds: RSS 2.0 (with Media RSS), Atom 1.0, JSON Feed 1.1, content + negotiation at `/feed`, OPML export; tag pages and the likes page are + h-feeds readers can follow +- POSSE crossposting to GoToSocial/Mastodon, Bluesky and Threads, with + `u-syndication` links back; edits and deletes follow, native likes and + boosts where the target supports them -## Quick Start +**Operations** +- Migrations applied automatically at startup +- `/health` endpoint, admin metrics dashboard, structured logs +- Fetches of user-supplied URLs are limited to public addresses, size and + time + +## Quick start + +### Container ```bash -# Clone repository -git clone https://github.com/YOUR_USERNAME/starpunk.git -cd starpunk - -# Install uv (package manager) -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Create virtual environment -uv venv .venv --python 3.11 - -# Install dependencies -uv pip install -r requirements.txt - -# Configure -cp .env.example .env -# Edit .env and set ADMIN_ME, SESSION_SECRET and the OIDC_* values - -# Initialize database -mkdir -p data/notes -.venv/bin/python -c "from starpunk.database import init_db; init_db()" -# Note: Database also auto-initializes on first run if not present - -# Run development server -.venv/bin/flask --app app.py run --debug - -# Visit http://localhost:5000 +git clone https://git.thesatelliteoflove.com/phil/StarPunk.git && cd StarPunk +cp .env.example .env # set SITE_URL, ADMIN_ME, SESSION_SECRET, OIDC_* +docker build -t starpunk -f Containerfile . +docker run -d --name starpunk -p 127.0.0.1:8000:8000 --env-file .env \ + -e FLASK_ENV=production -e FLASK_DEBUG=0 \ + -v ./starpunk-data:/data starpunk ``` +The container runs as UID 1000, so the data directory must be writable by +it. Release images are published by CI as +`git.thesatelliteoflove.com/phil/starpunk:vX.Y.Z`. Put a reverse proxy +with HTTPS in front (see `Caddyfile.example` or `nginx.conf.example`) and +set `TRUSTED_PROXY=true`. Register `/auth/callback` as the +redirect URI with your OIDC provider. Details: +[docs/architecture/deployment.md](docs/architecture/deployment.md). + +### Local development + +```bash +uv venv --python 3.11 +uv pip install -r requirements-dev.txt +cp .env.example .env # set SESSION_SECRET; add DEV_MODE=true and DEV_ADMIN_ME +uv run flask --app app.py run --debug # http://localhost:5000 +SESSION_SECRET=test uv run pytest # tests (about 6 minutes) +``` + +With `DEV_MODE=true`, `/dev/login` logs you in without OIDC. Never enable +it on a public server. Full guide: +[docs/standards/development-setup.md](docs/standards/development-setup.md). + ## Configuration -All configuration is in the `.env` file. Required settings: +All settings are environment variables (or a `.env` file), each listed with +its default in [`.env.example`](.env.example). Required in production: +`SESSION_SECRET`, `SITE_URL`, `ADMIN_ME`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, +`OIDC_CLIENT_SECRET` and `OIDC_ADMIN_SUB`. Crossposting is enabled by +setting a target's credentials. -- `ADMIN_ME` - Your IndieWeb identity URL (e.g., https://yoursite.com) -- `SESSION_SECRET` - Random secret key (generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`) -- `SITE_URL` - Public URL of your site -- `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` - OIDC client for admin login (callback: `/auth/callback`) -- `OIDC_ADMIN_SUB` - Subject ID of the one account allowed to log in +## Data and backups -See `.env.example` for all options. +Everything lives in the data directory (`/data` in the container): the +SQLite database, note files in `notes/`, uploaded media and logs. Back it +up regularly, and always before upgrading to a release with a migration. -## Project Structure +## Documentation -``` -starpunk/ -├── app.py # Application entry point -├── starpunk/ # Application code -├── data/ # Your notes and database (gitignored) -│ ├── notes/ # Markdown files -│ └── starpunk.db # SQLite database -├── static/ # CSS and JavaScript -├── templates/ # HTML templates -└── tests/ # Test suite -``` - -## Usage - -### Publishing Notes - -**Via Web Interface**: -1. Navigate to `/admin` -2. Login with your IndieWeb identity -3. Create notes in markdown - -**Via Micropub Client**: -1. Configure client with your site URL -2. Sign in with your OIDC provider -3. Publish from any Micropub-compatible app - -### Backing Up Your Data - -Your notes are stored as plain markdown files in `data/notes/`. Back up this directory: - -```bash -# Simple backup -tar -czf backup.tar.gz data/ - -# Or use rsync -rsync -av data/ /backup/starpunk/ -``` - -## Development - -See [docs/standards/development-setup.md](docs/standards/development-setup.md) for detailed setup. - -```bash -# Install dev dependencies -uv pip install -r requirements-dev.txt - -# Run tests -.venv/bin/pytest - -# Format code -.venv/bin/black starpunk/ tests/ - -# Lint -.venv/bin/flake8 starpunk/ tests/ -``` - -## Architecture - -StarPunk uses a hybrid storage approach: -- **Notes content**: Markdown files (portable, human-readable) -- **Metadata**: SQLite database (fast queries) - -This gives you both portability AND performance. - -See [docs/architecture/](docs/architecture/) for complete documentation. - -## IndieWeb Compliance - -StarPunk implements: -- [Micropub](https://micropub.spec.indieweb.org/) - Publishing API -- [IndieAuth](https://www.w3.org/TR/indieauth/) - Authentication -- [Microformats2](http://microformats.org/) - h-entry, h-card, h-feed markup -- [RSS 2.0](https://www.rssboard.org/rss-specification) with Media RSS extensions -- [ATOM 1.0](https://validator.w3.org/feed/docs/atom.html) - Syndication format -- [JSON Feed 1.1](https://jsonfeed.org/version/1.1) - Modern feed format - -## Deployment - -### Production Setup - -```bash -# Install gunicorn -uv pip install gunicorn - -# Run with gunicorn -.venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app - -# Configure nginx/Caddy for HTTPS -# Set up systemd for process management -# Enable regular backups of data/ directory -``` - -See [docs/standards/deployment-standards.md](docs/standards/deployment-standards.md) for details. +| Topic | Where | +|---|---| +| How the docs are organized | [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) | +| System overview | [docs/architecture/overview.md](docs/architecture/overview.md) | +| Technology stack | [docs/architecture/technology-stack.md](docs/architecture/technology-stack.md) | +| Database and migrations | [docs/architecture/database.md](docs/architecture/database.md) | +| Deployment | [docs/architecture/deployment.md](docs/architecture/deployment.md) | +| Authentication (OIDC, IndieAuth) | [docs/architecture/simplified-auth-architecture.md](docs/architecture/simplified-auth-architecture.md) | +| IndieWeb protocols | [docs/architecture/indieweb-protocols.md](docs/architecture/indieweb-protocols.md) | +| Feeds and crossposting | [docs/architecture/syndication-architecture.md](docs/architecture/syndication-architecture.md) | +| Decisions (ADRs) | [docs/decisions/INDEX.md](docs/decisions/INDEX.md) | +| Per-release designs and reports | [docs/design/](docs/design/) | +| Backlog | [docs/projectplan/BACKLOG.md](docs/projectplan/BACKLOG.md) | +| Development standards and release process | [docs/standards/INDEX.md](docs/standards/INDEX.md) | ## License -MIT License - see LICENSE file - -## Credits - -Built with: -- [Flask](https://flask.palletsprojects.com/) - Web framework -- [python-markdown](https://python-markdown.github.io/) - Markdown processing -- [feedgen](https://feedgen.kiesow.be/) - RSS generation -- [httpx](https://www.python-httpx.org/) - HTTP client - -## Contributing - -This is a personal project optimized for single-user use. If you want additional features, consider forking! - -## Support - -- Documentation: [docs/](docs/) -- Issues: GitHub Issues -- IndieWeb: [indieweb.org](https://indieweb.org/) +MIT, see [LICENSE](LICENSE). diff --git a/docs/architecture/INDEX.md b/docs/architecture/INDEX.md index 7049f41..cd02ffb 100644 --- a/docs/architecture/INDEX.md +++ b/docs/architecture/INDEX.md @@ -1,82 +1,40 @@ # Architecture Documentation Index -This directory contains architectural documentation, system design overviews, component diagrams, and architectural patterns for StarPunk CMS. +This directory describes the **current** design of StarPunk (v2.10.1). Per +[../DOCUMENTATION.md](../DOCUMENTATION.md) it is updated at the end of each +release. Decisions and their history are in [../decisions/](../decisions/); +per-release designs and reports are in [../design/](../design/). -## Core Architecture +## Documents -### System Overview -- **[overview.md](overview.md)** - Complete system architecture and design principles -- **[technology-stack.md](technology-stack.md)** - Current technology stack and dependencies -- **[technology-stack-legacy.md](technology-stack-legacy.md)** - Historical technology decisions +| Document | Description | +|----------|-------------| +| [overview.md](overview.md) | System overview: purpose, request flow, modules and routes, background workers, storage, auth model, URL surface, caching, security posture | +| [technology-stack.md](technology-stack.md) | Current runtime, Python dependencies, standards implemented, testing and CI | +| [database.md](database.md) | SQLite schema after migrations 001–017, migration runner and its lock, connection pool | +| [deployment.md](deployment.md) | Container image stages, CI workflow, release process, `/data` layout, reverse proxy, all environment variables | +| [simplified-auth-architecture.md](simplified-auth-architecture.md) | Admin login via OpenID Connect and the built-in IndieAuth server that issues Micropub tokens (ADR-064) | +| [indieweb-protocols.md](indieweb-protocols.md) | How Micropub, IndieAuth, Webmention, microformats2, WebSub and the feeds are implemented, with compliance status and known gaps | +| [syndication-architecture.md](syndication-architecture.md) | Crossposting (POSSE) to GoToSocial, Bluesky and Threads: syndications table, worker, reconcile rules | +| [technology-stack-legacy.md](technology-stack-legacy.md) | Historical: the original v0.x technology choices (IndieLogin era); not current | -### Feature-Specific Architecture +## Where to start -#### IndieAuth & Authentication -- **[indieauth-assessment.md](indieauth-assessment.md)** - Assessment of IndieAuth implementation -- **[indieauth-client-diagnosis.md](indieauth-client-diagnosis.md)** - IndieAuth client diagnostic analysis -- **[indieauth-endpoint-discovery.md](indieauth-endpoint-discovery.md)** - Endpoint discovery architecture -- **[indieauth-identity-page.md](indieauth-identity-page.md)** - Identity page architecture -- **[indieauth-questions-answered.md](indieauth-questions-answered.md)** - Architectural Q&A for IndieAuth -- **[indieauth-removal-architectural-review.md](indieauth-removal-architectural-review.md)** - Review of custom IndieAuth removal -- **[indieauth-removal-implementation-guide.md](indieauth-removal-implementation-guide.md)** - Implementation guide for removal -- **[indieauth-removal-phases.md](indieauth-removal-phases.md)** - Phased removal approach -- **[indieauth-removal-plan.md](indieauth-removal-plan.md)** - Overall removal plan -- **[indieauth-token-verification-diagnosis.md](indieauth-token-verification-diagnosis.md)** - Token verification diagnostic analysis -- **[simplified-auth-architecture.md](simplified-auth-architecture.md)** - Simplified authentication architecture -- **[endpoint-discovery-answers.md](endpoint-discovery-answers.md)** - Endpoint discovery implementation Q&A +- **New to the code**: overview.md, then technology-stack.md. +- **Changing the schema**: database.md (migrations must be safe inside one + transaction). +- **Releasing or operating the site**: deployment.md. +- **Working on auth, Micropub, Webmention or WebSub**: + simplified-auth-architecture.md and indieweb-protocols.md, plus the ADRs + they link to. -#### Database & Migrations -- **[database-migration-architecture.md](database-migration-architecture.md)** - Database migration system architecture -- **[migration-fix-quick-reference.md](migration-fix-quick-reference.md)** - Quick reference for migration fixes -- **[migration-race-condition-answers.md](migration-race-condition-answers.md)** - Race condition resolution Q&A +## Related documentation -#### Syndication -- **[syndication-architecture.md](syndication-architecture.md)** - RSS feed and syndication architecture - -## Version-Specific Architecture - -### v1.0.0 -- **[v1.0.0-release-validation.md](v1.0.0-release-validation.md)** - Release validation architecture - -### v1.1.0 -- **[v1.1.0-feature-architecture.md](v1.1.0-feature-architecture.md)** - Feature architecture for v1.1.0 -- **[v1.1.0-implementation-decisions.md](v1.1.0-implementation-decisions.md)** - Implementation decisions -- **[v1.1.0-search-ui-validation.md](v1.1.0-search-ui-validation.md)** - Search UI validation -- **[v1.1.0-validation-report.md](v1.1.0-validation-report.md)** - Overall validation report - -### v1.1.1 -- **[v1.1.1-architecture-overview.md](v1.1.1-architecture-overview.md)** - Architecture overview for v1.1.1 - -## Phase Documentation -- **[phase1-completion-guide.md](phase1-completion-guide.md)** - Phase 1 completion guide -- **[phase-5-validation-report.md](phase-5-validation-report.md)** - Phase 5 validation report - -## Review Documentation -- **[review-v1.0.0-rc.5.md](review-v1.0.0-rc.5.md)** - Architectural review of v1.0.0-rc.5 - -## How to Use This Documentation - -### For New Developers -1. Start with **overview.md** to understand the system -2. Review **technology-stack.md** for current technologies -3. Read feature-specific architecture docs relevant to your work - -### For Architects -1. Review version-specific architecture for historical context -2. Consult feature-specific docs when making changes -3. Update relevant docs when architecture changes - -### For Contributors -1. Read **overview.md** for system understanding -2. Consult specific architecture docs for areas you're working on -3. Follow patterns documented in architecture files - -## Related Documentation -- **[../decisions/](../decisions/)** - Architectural Decision Records (ADRs) -- **[../design/](../design/)** - Detailed design documents -- **[../standards/](../standards/)** - Coding standards and conventions +- [../decisions/](../decisions/): Architectural Decision Records (ADRs) +- [../design/](../design/): designs, questions and reports per version +- [../standards/](../standards/): coding, testing and versioning standards +- [../projectplan/](../projectplan/): backlog and release plans --- -**Last Updated**: 2025-11-25 -**Maintained By**: Documentation Manager Agent +**Last Updated**: 2026-11-03 (v2.10.1) diff --git a/docs/architecture/database.md b/docs/architecture/database.md new file mode 100644 index 0000000..ecf2639 --- /dev/null +++ b/docs/architecture/database.md @@ -0,0 +1,235 @@ +# Database Architecture + +**Version**: 2.10.1 (2026-11-03) +**Status**: Current. Verified against a database created by `create_app()` +with migrations 001–017. + +StarPunk uses one SQLite file, `starpunk.db` under `DATA_PATH` (`/data` in +the container), in WAL mode. Note *content* is not in the database: it lives +in Markdown files (`notes/YYYY/MM/.md`) and the `notes` table points to +them. See [overview.md](overview.md) for how the rest of the system uses it. + +## How the schema is built + +On every start, `init_db()` (`starpunk/database/init.py`) does two things: + +1. Runs `INITIAL_SCHEMA_SQL` (`starpunk/database/schema.py`). This is the + frozen v1.0.0 baseline, written with `CREATE … IF NOT EXISTS`: `notes`, + `sessions`, `tokens`, `authorization_codes`, `auth_state` and their + indexes. It must not be changed; every later change is a migration. +2. Runs `run_migrations()` (`starpunk/migrations.py`) over the SQL files in + `migrations/`, in file-name order. + +### Migration runner + +- Applied migrations are recorded in `schema_migrations` + (`migration_name`, `applied_at`). +- **Locking**: all four gunicorn processes run `create_app()` at the same + time. Each opens a direct (unpooled) connection with a 30-second busy + timeout and runs `BEGIN IMMEDIATE`, which takes SQLite's write lock. The + whole run (creating `schema_migrations`, checking what is pending, applying + every pending migration and recording it) happens in that one transaction + and is committed at the end, so a migration is applied once and atomically. + Statements are executed one by one with `conn.execute()` (split with + `sqlite3.complete_statement`, so trigger bodies stay whole), never with + `executescript()`, which would commit and drop the lock part-way (the cause + of the v2.8.0 deploy failure fixed in v2.8.1). +- A process that finds the database locked retries with exponential backoff + (up to 10 attempts, 120 seconds in total), then finds everything already + applied and returns. +- A failing migration rolls the whole run back and raises `MigrationError`, + which stops the app from starting. +- **Fresh databases**: when `schema_migrations` is empty, the runner checks + each of the early migrations (001–003) against the actual schema and only + records those whose effect is already present; migration 002 is reduced to + creating its indexes. All later migrations run normally. + +Background: [ADR-031](../decisions/ADR-031-database-migration-system-redesign.md), +[ADR-032](../decisions/ADR-032-initial-schema-sql-implementation.md), +[ADR-033](../decisions/ADR-033-database-migration-redesign.md), +[ADR-037](../decisions/ADR-037-migration-race-condition-fix.md), +[ADR-041](../decisions/ADR-041-database-migration-conflict-resolution.md). + +### Migrations + +| File | Version | Change | +|------|---------|--------| +| `001_add_code_verifier_to_auth_state.sql` | 0.8 | `auth_state.code_verifier` (removed again by 003) | +| `002_secure_tokens_and_authorization_codes.sql` | 1.0.0-rc | Hashed `tokens` and `authorization_codes` (dropped by 004) | +| `003_remove_code_verifier_from_auth_state.sql` | 1.0 | Drops `auth_state.code_verifier` | +| `004_drop_token_tables.sql` | 1.0 | Drops `tokens` and `authorization_codes` | +| `005_add_fts5_search.sql` | 1.1 | `notes_fts` (FTS5) and the `notes_fts_delete` trigger | +| `006_add_author_profile.sql` | 1.2 | `author_profile` (h-card cache) | +| `007_add_media_support.sql` | 1.2 | `media`, `note_media` | +| `008_add_tags.sql` | 1.3 | `tags`, `note_tags` | +| `009_add_media_variants.sql` | 1.4 | `media_variants` | +| `010_add_webmentions.sql` | 1.6 | `notes.in_reply_to`, `webmentions`, `webmention_queue`, `reply_contexts` | +| `011_oidc_login_and_indieauth_server.sql` | 2.0 | `oidc_login_state`, `indieauth_codes`, `indieauth_tokens` | +| `012_add_syndications.sql` | 2.1 | `syndications` | +| `013_add_likes_reposts.sql` | 2.5 | `notes.like_of`, `notes.repost_of` | +| `014_webmention_source_details.sql` | 2.8 | `webmentions.source_post_url`, `webmentions.source_published` | +| `015_bookmarks_and_content_format.sql` | 2.9 | `notes.bookmark_of`, `notes.content_format` | +| `016_websub.sql` | 2.10.0 | `websub_subscriptions`, `websub_intents`, `websub_deliveries`, `site_state` | +| `017_websub_hardening.sql` | 2.10.1 | `websub_intents.request_id`, `requested_topic`, `callback_ip`; `websub_subscriptions.callback_ip` | + +New migrations are numbered `NNN_description.sql`, must be safe to run inside +one transaction, and should use `IF NOT EXISTS` where SQLite allows it. + +## Tables + +### Content + +**`notes`**: one row per note; the content is in the file at `file_path`. + +| Column | Purpose | +|--------|---------| +| `id`, `slug` (unique), `file_path` (unique) | Identity and location of the Markdown file (relative to `DATA_PATH`) | +| `published` | 0 = draft, 1 = public | +| `created_at`, `updated_at` | Timestamps (UTC) | +| `deleted_at` | Set on soft delete (file moved to `.trash/`); cleared by undelete | +| `content_hash` | SHA-256 of the file content | +| `in_reply_to`, `like_of`, `repost_of`, `bookmark_of` | URL the note responds to; set for replies, likes, reposts, bookmarks | +| `content_format` | `'html'` when a Micropub client sent HTML (so `q=source` returns HTML); NULL means Markdown | + +Indexes on `created_at DESC`, `published`, `slug`, `deleted_at`, `like_of`. + +**`notes_fts`**: FTS5 virtual table (`slug` unindexed, `title`, `content`; +`porter unicode61` tokenizer), with its shadow tables `notes_fts_config`, +`_content`, `_data`, `_docsize`, `_idx`. Rows use the note `id` as `rowid`. +Inserts and updates are done by `starpunk/search.py` (the database cannot +read note files); the trigger `notes_fts_delete` removes the row when a note +row is deleted. The index is rebuilt at start-up if it is empty. + +**`tags`** (`name` normalised and unique, `display_name` as written) and +**`note_tags`** (`note_id`, `tag_id`, unique pair, cascading deletes). + +**`media`**: an uploaded image: original `filename`, `stored_filename` +(UUID), `path` (`YYYY/MM/.` under `media/`), `mime_type`, `size`, +`width`, `height`, `uploaded_at`. + +**`media_variants`**: resized copies per image (`variant_type` one of +`thumb`, `small`, `medium`, `large`, `original`; `path`, dimensions, size); +unique per (`media_id`, `variant_type`), deleted with the image. + +**`note_media`**: attaches media to notes with `display_order` and +`caption` (alt text); unique per (`note_id`, `media_id`). + +### Authentication + +**`sessions`**: admin sessions. `session_token_hash` (SHA-256 of the cookie +value), `me`, `created_at`, `expires_at`, `last_used_at`, `user_agent`, +`ip_address`. + +**`oidc_login_state`**: one row per OIDC login in progress: `state` +(primary key), `nonce`, `code_verifier` (PKCE), `next_url`, `expires_at`. +Consumed once on callback. + +**`indieauth_codes`**: authorization codes issued to Micropub clients: +`code_hash`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, +`expires_at`, `used_at` (single use). + +**`indieauth_tokens`**: access tokens: `token_hash`, `client_id`, `scope`, +`created_at`, `expires_at`, `last_used_at`, `revoked_at`. Listed and revoked +in `/admin/tokens`. + +**Legacy tables, unused**: `auth_state` (v1 IndieLogin login state), `tokens` +and `authorization_codes` (v1 token tables). No code reads or writes them. +Migration 004 drops `tokens` and `authorization_codes`, but +`INITIAL_SCHEMA_SQL` recreates them (empty) on the next start, so a running +database normally contains them. They are harmless; v2 auth uses the tables +above. + +### IndieWeb interactions + +**`webmentions`**: received webmentions, one per (`source_url`, +`target_url`). + +| Column | Purpose | +|--------|---------| +| `target_note_id` | The note mentioned (SET NULL if the note is deleted) | +| `mention_type` | `reply`, `like`, `repost`, `bookmark`, `mention` | +| `author_name`, `author_url`, `author_photo`, `content_snippet` | From the source's mf2 (content sanitised) | +| `source_post_url`, `source_published` | The source entry's own `u-url` and `dt-published` | +| `validation_status` | `pending`, `valid`, `invalid`, `error` (set by the worker) | +| `moderation_status` | `pending`, `approved`, `hidden`, `deleted` (auto-approved when `WEBMENTION_AUTO_APPROVE`) | +| `validation_error`, `validated_at`, `received_at`, `updated_at` | Bookkeeping | + +**`webmention_queue`**: outgoing webmentions, one per (`source_url`, +`target_url`): `source_note_id`, discovered `endpoint_url`, `status` +(`pending`, `sending`, `sent`, `failed`, `no_endpoint`), `retry_count`, +`next_retry_at`, `last_error`, `started_at`, `sent_at`. + +**`reply_contexts`**: cache of the posts that replies (and other responses) +point to: `url` (unique), `title`, `content_snippet`, `published_at`, author +fields, `site_name`, `fetch_status` (`pending`, `fetched`, `error`), +`fetch_error`, `fetched_at`. + +**`author_profile`**: cache of the owner's h-card discovered from `ADMIN_ME`: +`me`, `name`, `photo`, `url`, `note`, `rel_me_links` (JSON), `discovered_at`, +`cached_until` (24 hours). + +### Crossposting + +**`syndications`**: one row per (`note_id`, `target`), where `target` is a +configured target id (GoToSocial, Bluesky, Threads). `enabled` says whether +the note should be on that target; `remote_id` and `remote_url` identify the +remote post. `state` (`pending`, `synced`, `failed`), `version` (bumped on +every note change, so an edit made during a send is not lost), `attempts`, +`last_error`, `next_attempt_at` and `claimed_until` (a 5-minute lease that +lets any gunicorn process take the row exclusively) drive the worker. See +[syndication-architecture.md](syndication-architecture.md). + +### WebSub + +**`websub_subscriptions`**: verified subscriptions to this site's topics: +`topic`, `callback` (unique pair), `secret`, `lease_seconds`, `expires_at`, +`verified_at`, `last_success_at`, `last_error`, `callback_ip` (the address +the callback resolved to, for per-address limits). + +**`websub_intents`**: subscribe and unsubscribe requests waiting for +verification of intent: `topic`, `callback` (unique pair), `mode`, `secret`, +`lease_seconds`, `attempts`, `next_attempt_at`, `request_id` (so verifying an +older request cannot consume a newer one), `requested_topic` (the topic as +sent, echoed in verification), `callback_ip`. + +**`websub_deliveries`**: content waiting to be pushed: one row per +subscription (built-in hub) or one per topic with `subscription_id` NULL (a +publish ping to an external hub); partial unique indexes keep at most one +pending row of each kind. `attempts`, `next_attempt_at`, `last_error`. + +**`site_state`**: key/value pairs. `content_version` is bumped whenever a +public note changes; every gunicorn process compares it to decide whether +its cached feed data is stale. + +### Bookkeeping + +**`schema_migrations`**: applied migrations (see above). + +## Connections + +- **Request connections**: `starpunk/database/pool.py`. `init_pool()` creates + one `ConnectionPool` per process (up to 5 idle connections, 10-second busy + timeout; `DB_POOL_SIZE` and `DB_TIMEOUT` can be set only through the + `create_app()` config dict). Connections use `sqlite3.Row` rows, + `check_same_thread=False` and `PRAGMA journal_mode=WAL`, and are wrapped + in `MonitoredConnection` for query timing when metrics are on. `get_db()` + stores one connection in `flask.g` per request or app context; on teardown + it goes back to the pool, rolled back first if a transaction was left + open. +- **Direct connections**: the migration runner, the FTS start-up check, the + webmention worker and sender, reply-context fetching and search helpers + open their own `sqlite3.connect(db_path)` connections. +- WAL mode lets readers carry on while one writer writes. The four gunicorn + processes and the worker threads share the one file; writes are short, so + contention is low. + +## Backups + +The application does not back itself up. A consistent copy needs the +database (use SQLite's online backup, e.g. `sqlite3 starpunk.db ".backup …"`, +because of WAL) together with `notes/` and `media/`; see +[deployment.md](deployment.md). + +--- + +**Last Updated**: 2026-11-03 (v2.10.1) diff --git a/docs/architecture/deployment.md b/docs/architecture/deployment.md new file mode 100644 index 0000000..1bd1efa --- /dev/null +++ b/docs/architecture/deployment.md @@ -0,0 +1,269 @@ +# Deployment Architecture + +**Version**: 2.10.1 (2026-11-03) +**Status**: Current + +How StarPunk is built, configured and run in production. The production site +is a single container behind Caddy on one host, managed with Ansible. This +document stays generic: hostnames, credentials and inventory live in the +deployment repository, not here. + +## Overview + +``` + git tag vX.Y.Z ──► Gitea Actions ──► test stage (pytest) ──► runtime image + │ push :vX.Y.Z, :latest + ▼ + Gitea container registry + │ pull (tag set in Ansible) + ▼ + Internet ──► Caddy (TLS, headers, X-Forwarded-For) ──► container :8000 (gunicorn × 4) + │ + /data volume (host) +``` + +## Container image (`Containerfile`) + +A multi-stage build on `python:3.11-slim`; it works with Podman and Docker. + +| Stage | Purpose | +|-------|---------| +| `builder` | Copies `uv` from `ghcr.io/astral-sh/uv`, creates `/opt/venv` and installs `requirements.txt` into it | +| `test` | Copies the venv, adds `pytest` and `pytest-mock`, copies the source and runs `python -m pytest -q -p no:cacheprovider tests` with test values for `SESSION_SECRET`, `SITE_URL` and `ADMIN_ME`. The stage only builds if the tests pass. | +| runtime (last, the default target) | Creates user `starpunk` (UID/GID 1000) and `/data/notes`, copies the venv and the application to `/app`, sets `DATA_PATH=/data`, `NOTES_PATH=/data/notes`, `DATABASE_PATH=/data/starpunk.db`, runs as `starpunk`, exposes port 8000 | + +The runtime image's command is gunicorn: + +``` +gunicorn --bind 0.0.0.0:8000 --workers 4 --worker-class sync + --worker-tmp-dir /dev/shm --max-requests 1000 --max-requests-jitter 50 + --timeout 30 --graceful-timeout 30 + --access-logfile - --error-logfile - --log-level info app:app +``` + +Each of the four worker processes builds its own Flask app, so each runs +migrations (only one applies them, see [database.md](database.md)) and starts +its own background threads (see [overview.md](overview.md#background-workers)). +Workers are recycled after about 1000 requests; a recycled process starts +new threads, and the file locks pass to another process if the holder exits. + +**Health check**: the image's `HEALTHCHECK` runs every 30 seconds (3-second +timeout, 10-second start period, 3 retries) and calls +`http://localhost:8000/health` with httpx. `/health` returns +`{"status": "ok", "version": …}` plus webmention-worker statistics, without +authentication. + +## CI/CD (`.gitea/workflows/build-container.yml`) + +- **Triggers**: pushing a tag matching `vX.Y.Z`, or a manual run. +- **Runner**: a Gitea Actions runner with no Docker daemon. Images are built + by a rootless BuildKit daemon reached over its socket + (`docker buildx create --driver remote`). +- **Steps**: + 1. Log in to the Gitea container registry with the repository secret + `REGISTRY_TOKEN` (a token with only the `write:package` scope; the + automatic Actions token is refused by the registry). + 2. `docker buildx build --target test`: runs the test suite. A failure + stops the workflow before anything is pushed. + 3. Build the runtime image and push it tagged with the git tag + (e.g. `v2.10.1`) and `latest`. The image name is the repository path in + lower case. + 4. Remove the builder and log out, even after a failure. + +There is no CI on branches or pull requests; run the tests locally before +merging (see [technology-stack.md](technology-stack.md#testing)). + +## Release process + +1. Finish the change on a branch, including the version bump in + `starpunk/__init__.py` (`__version__`, `__version_info__`) and a + `CHANGELOG.md` entry. +2. Merge to `main`. +3. Tag the merge commit `vX.Y.Z` and push the tag. CI tests, builds and + pushes the image. +4. In the Ansible-managed deployment, change the StarPunk image tag to the new + version and apply it. The container is recreated from the new image; new + migrations run automatically at start-up. +5. Check `/health` reports the new version. + +Rolling back means deploying the previous tag. Migrations are not reversed +automatically, so a release with a migration needs a database backup first +if a rollback might be needed. + +## Runtime layout + +### Data volume (`/data`) + +A host directory is mounted at `/data`, owned by UID 1000. Everything +persistent is there; the image itself holds no state. + +| Path | Contents | +|------|----------| +| `starpunk.db` (+ `-wal`, `-shm`) | SQLite database in WAL mode | +| `notes/YYYY/MM/.md` | Note content | +| `.trash/YYYY/MM/` | Soft-deleted note files (restorable with Micropub undelete) | +| `media/YYYY/MM/` | Uploaded images and their variants; `media/.tmp/` while processing | +| `logs/starpunk.log` | Application log, rotated at 10 MB, 10 files kept | +| `webmention-worker.lock`, `websub-worker.lock` | `flock` files choosing the process that runs each worker | +| `threads_token.json` (+ `.lock`) | Current Threads access token, refreshed daily (only with Threads configured) | +| `debug/` | Failed uploads, only with `DEBUG_SAVE_FAILED_UPLOADS=true`; cleaned up after `DEBUG_FILE_MAX_AGE_DAYS` | + +The application does not make backups. A backup must include the database +(copied with SQLite's online backup because of WAL), `notes/` and `media/`. +Backups are handled by the deployment, outside the container. + +### Reverse proxy + +Caddy terminates TLS and proxies to the container's port 8000. Publish that +port only where the proxy can reach it (for example on the host's loopback +interface, as `compose.yaml` does), never publicly. Caddy adds security headers +(HSTS, CSP, X-Frame-Options, Referrer-Policy and so on; see +`Caddyfile.example`, and `nginx.conf.example` for nginx) and sets +`X-Forwarded-For`. + +Set `TRUSTED_PROXY=true` behind the proxy. With it, StarPunk takes the client +address from the first entry of `X-Forwarded-For`, which the webmention and +WebSub rate limits need; without it, every client appears as the proxy's +address and shares one limit. Do not set it if the container port can be +reached without the proxy, because the header could then be forged. + +`SITE_URL` must be the public `https://` URL: it is used for absolute links, +feed and WebSub topic URLs, the IndieAuth issuer and redirect URIs, and to +decide whether the session cookie is `Secure`. + +## Configuration + +Configuration is read from environment variables (and a `.env` file if +present) by `starpunk/config.py` at start-up. In production the variables +come from the Ansible-managed environment, with secrets from its vault. +`.env.example` documents them for local use. Booleans are `true`/`false` +unless noted. + +### Required + +| Variable | Default | Notes | +|----------|---------|-------| +| `SESSION_SECRET` | none | Required always. Signs sessions; also Flask's `SECRET_KEY` unless `FLASK_SECRET_KEY` is set | +| `SITE_URL` | `http://localhost:5000` | Public URL; a trailing `/` is added | +| `ADMIN_ME` | none | Owner's identity URL (h-card, Micropub `me`). Required unless `DEV_MODE` | +| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ADMIN_SUB` | empty | Admin login via OIDC. Required unless `DEV_MODE` (or testing) | + +### Site and authentication + +| Variable | Default | Notes | +|----------|---------|-------| +| `SITE_NAME` | `StarPunk` | | +| `SITE_AUTHOR` | `Unknown` | | +| `SITE_DESCRIPTION` | `A minimal IndieWeb CMS` | | +| `SESSION_LIFETIME` | `30` | Days | +| `FLASK_SECRET_KEY` | `SESSION_SECRET` | | +| `OIDC_PROVIDER_NAME` | `single sign-on` | Label on the login button | +| `INDIEAUTH_TOKEN_LIFETIME_DAYS` | `90` | Lifetime of Micropub access tokens | +| `DEV_MODE` | `false` | Enables `/dev/login`; never in production | +| `DEV_ADMIN_ME` | empty | Required when `DEV_MODE=true` | + +`TOKEN_ENDPOINT` and `INDIELOGIN_URL` are v1 settings; if present they are +ignored with a warning. + +### Paths, runtime and logging + +| Variable | Default | Notes | +|----------|---------|-------| +| `DATA_PATH` | `./data` (image: `/data`) | Root of all stored data | +| `DATABASE_PATH` | `./data/starpunk.db` (image: `/data/starpunk.db`) | | +| `NOTES_PATH` | `./data/notes` (image: `/data/notes`) | Created at start-up, but note files are always written to `DATA_PATH/notes` | +| `FLASK_ENV` | `development` | Set `production` in production | +| `FLASK_DEBUG` | `1` | Set `0` in production (the image does not set it) | +| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | +| `VERSION` | package `__version__` | Overrides the reported version; normally unset | + +### Feeds + +| Variable | Default | Notes | +|----------|---------|-------| +| `FEED_MAX_ITEMS` | `50` | Notes per feed | +| `FEED_CACHE_SECONDS` | `300` | Cache TTL and `Cache-Control: max-age` | +| `FEED_CACHE_ENABLED` | `true` | | +| `FEED_CACHE_MAX_SIZE` | `50` | Cached feed documents per process | + +### Webmention + +| Variable | Default | Notes | +|----------|---------|-------| +| `WEBMENTION_ENABLED` | `true` | Endpoint, `Link` header and sending | +| `WEBMENTION_WORKER_ENABLED` | `true` | | +| `WEBMENTION_POLL_INTERVAL` | `10` | Seconds | +| `WEBMENTION_ERROR_BACKOFF` | `60` | Seconds after a worker error | +| `WEBMENTION_BATCH_SIZE` | `5` | Items per pass | +| `WEBMENTION_AUTO_APPROVE` | `true` | Valid webmentions are shown without moderation | +| `WEBMENTION_RATE_LIMIT_ENABLED` | `true` | | +| `WEBMENTION_RATE_LIMIT_IP` | `60` | Requests per window per client IP | +| `WEBMENTION_RATE_LIMIT_DOMAIN` | `10` | Requests per window per source domain | +| `WEBMENTION_RATE_LIMIT_WINDOW` | `60` | Seconds | +| `TRUSTED_PROXY` | `false` | Use `X-Forwarded-For` for the client IP (see above) | + +### WebSub + +| Variable | Default | Notes | +|----------|---------|-------| +| `WEBSUB_ENABLED` | `true` | Discovery links, hub and worker | +| `WEBSUB_HUB_URL` | empty | Use an external hub (StarPunk then sends publish pings) instead of the built-in one | +| `WEBSUB_MAX_SUBSCRIPTIONS` | `1000` | Total subscriptions | +| `WEBSUB_MAX_PER_HOST` | `25` | Subscriptions per callback host | +| `WEBSUB_POLL_INTERVAL` | `5` | Seconds | + +### Crossposting (POSSE) + +A target is enabled when its credentials are set; the syndication worker +starts only if at least one is. + +| Variable | Default | Notes | +|----------|---------|-------| +| `GOTOSOCIAL_URL`, `GOTOSOCIAL_ACCESS_TOKEN` | empty | GoToSocial or any Mastodon-API server | +| `GOTOSOCIAL_NAME` | `GoToSocial` | Label in the UI and `syndicate-to` | +| `GOTOSOCIAL_VISIBILITY` | `public` | | +| `GOTOSOCIAL_MAX_CHARS` | `5000` | | +| `GOTOSOCIAL_MAX_MEDIA` | `4` | | +| `BLUESKY_HANDLE`, `BLUESKY_APP_PASSWORD` | empty | | +| `BLUESKY_SERVICE` | `https://bsky.social` | | +| `BLUESKY_NAME` | `Bluesky` | | +| `BLUESKY_MAX_CHARS` | `300` | | +| `THREADS_ACCESS_TOKEN` | empty | Long-lived token; refreshed automatically into `threads_token.json` | +| `THREADS_USERNAME` | empty | | +| `THREADS_NAME` | `Threads` | | +| `THREADS_MAX_CHARS` | `500` | | +| `THREADS_MAX_MEDIA` | `4` | | +| `SYNDICATION_POLL_INTERVAL` | `10` | Seconds | + +### Metrics and debugging + +| Variable | Default | Notes | +|----------|---------|-------| +| `METRICS_ENABLED` | `true` | HTTP/database metrics and the memory monitor | +| `METRICS_SLOW_QUERY_THRESHOLD` | `1.0` | Seconds | +| `METRICS_SAMPLING_RATE` | `1.0` | | +| `METRICS_BUFFER_SIZE` | `1000` | | +| `METRICS_MEMORY_INTERVAL` | `30` | Seconds | +| `DEBUG_SAVE_FAILED_UPLOADS` | `false` | Keep failed uploads in `debug/` | +| `DEBUG_FILE_MAX_AGE_DAYS` | `7` | | +| `DEBUG_FILE_MAX_SIZE_MB` | `100` | | + +Fixed values: the maximum request body is 50 MB (`MAX_CONTENT_LENGTH`). The +connection pool size and timeout (`DB_POOL_SIZE`, `DB_TIMEOUT`) are not read +from the environment. + +## Running locally + +```bash +uv venv && uv pip install -r requirements-dev.txt +cp .env.example .env # set SESSION_SECRET; DEV_MODE=true and DEV_ADMIN_ME for local login +flask --app app.py run # or: gunicorn app:app +``` + +`compose.yaml` builds and runs the image with `./container-data` mounted at +`/data`; its image tag and `VERSION` values are out of date, so override them +or build with `podman build -t starpunk .`. + +--- + +**Last Updated**: 2026-11-03 (v2.10.1) diff --git a/docs/architecture/indieweb-protocols.md b/docs/architecture/indieweb-protocols.md new file mode 100644 index 0000000..0bb4558 --- /dev/null +++ b/docs/architecture/indieweb-protocols.md @@ -0,0 +1,524 @@ +# IndieWeb and W3C Protocols + +How StarPunk implements each protocol it speaks, as of v2.10.1, with its +compliance status and the gaps that remain. Each section links to the +decision records and review documents behind it. + +| Protocol | Role | Status | Main code | +|---|---|---|---| +| [Micropub](#micropub) | Server (posts and media) | Reviewed against the Recommendation in v2.9.0; deliberate deviations listed | `starpunk/micropub.py`, `starpunk/routes/micropub.py` | +| [IndieAuth](#indieauth) | Authorization server for Micropub clients | Authorization code + PKCE, metadata, revocation | `starpunk/indieauth.py`, `starpunk/routes/indieauth.py` | +| [Webmention](#webmention) | Sender and receiver | Every MUST and SHOULD checked in v2.7.0 and v2.7.2; known limits listed | `starpunk/webmention_*.py`, `starpunk/routes/webmention.py` | +| [Microformats2](#microformats2) | Publisher and consumer | Reviewed in v2.8.0 | `templates/`, `starpunk/mf2_utils.py`, `starpunk/author_discovery.py` | +| [WebSub](#websub) | Publisher and built-in hub (own topics only) | Adversarial review in v2.10.1 | `starpunk/websub.py`, `starpunk/websub_worker.py`, `starpunk/routes/websub.py` | +| [Feeds](#feeds) | RSS 2.0, Atom 1.0, JSON Feed 1.1, OPML 2.0 | Stable | `starpunk/feeds/`, `starpunk/routes/public.py` | + +Crossposting to other networks (POSSE) is covered in +[syndication-architecture.md](syndication-architecture.md). + +## Shared infrastructure: the SSRF-safe fetcher + +Webmention (fetching sources, discovering endpoints, sending), WebSub +(verification and delivery) and Micropub (downloading remote photos) all +make requests to URLs chosen by someone else. They use +`starpunk/webmention_ssrf.py`: + +- `validate_url_for_fetch()`: http(s) only. Every address from + `getaddrinfo` must be public. Private, loopback, link-local, multicast, + reserved, unspecified, CGNAT (`100.64.0.0/10`), `0.0.0.0/8` and + IPv4-mapped forms are blocked. It returns the checked address, preferring + IPv4. `DEV_MODE` allows localhost. +- **DNS pinning** (v2.7.2): each request connects to the checked IP, with + the original host in the `Host` header and as the TLS SNI name. The + certificate is still verified against the real hostname, so a rebinding + DNS server can't send the second lookup elsewhere. +- `safe_get()` follows up to 10 redirects by hand and checks each hop. The + response is capped at 1 MB by default. +- `safe_post()` doesn't follow redirects. +- **Hard deadlines** (v2.10.1): the whole exchange, not each read, is + limited to 10 s. When the deadline passes, the client is closed, so a + server trickling bytes can't hold a worker. +- DNS resolution failures raise `ResolutionError` (a `ValueError`), which + callers can treat as temporary. +- User-Agent: `StarPunk/ Webmention (+)`. + +Workers that drain queues (Webmention, WebSub) run as one daemon thread per +gunicorn process. Each takes a non-blocking `flock` on a lock file in the +data directory, so only one process works the queue at a time and another +takes over if it dies. + +--- + +## Micropub + +Spec: https://www.w3.org/TR/micropub/. Decisions: +[ADR-028](../decisions/ADR-028-micropub-implementation.md), +[ADR-029](../decisions/ADR-029-micropub-indieauth-integration.md), +[ADR-057](../decisions/ADR-057-media-attachment-model.md) (photos), +[ADR-067](../decisions/ADR-067-micropub-update-delete.md) (update/delete), +[ADR-068](../decisions/ADR-068-likes-and-reposts.md) (likes/reposts). +Review: [v2.9.0 Micropub review](../design/v2.9.0/2026-11-03-micropub-review.md). + +### Endpoints and discovery + +| Endpoint | Purpose | +|---|---| +| `GET /micropub?q=...` | Queries | +| `POST /micropub` | Create, update, delete, undelete | +| `POST /micropub/media` (and legacy `POST /media`) | Media endpoint | + +Every page has `` plus the IndieAuth discovery links +(see [IndieAuth](#indieauth)). Authentication, token placement, scopes and +error codes are described in +[simplified-auth-architecture.md §3](simplified-auth-architecture.md#3-token-use-at-the-micropub-and-media-endpoints). + +### Create + +Accepts form-encoded, multipart (with photo files) and JSON bodies. Only +`h=entry` / `type: ["h-entry"]` is accepted; other types get 400. Success is +**201** with `Location` set to the permalink `/note/`. + +| Property / command | Handling | +|---|---| +| `content` | String, or `{"html": ...}` / `{"text": ...}`. Text is preferred. HTML-only content is stored with `content_format = 'html'` (migration 015) and rendered through `render_markdown()` (Markdown, then nh3 allowlist sanitization) | +| `summary` | Used as the text when there is no `content` | +| `name` | Stored as a `# name` heading on the first line (StarPunk has no title column) | +| `category` | Tags (strings only; person tags as h-card objects are ignored) | +| `in-reply-to`, `like-of`, `repost-of`, `bookmark-of` | URL or h-cite. At most one of like/repost/bookmark. Content is optional for these | +| `photo` | URLs, `{"value", "alt"}` objects, or uploaded files; at most 4 (ADR-057), duplicates collapsed. Own `/media/` URLs are looked up; other URLs are downloaded through `safe_get` (20 MB cap). Any photo that can't be resolved means 400 and nothing is created | +| `published` | ISO 8601; converted to naive UTC; invalid gets 400 | +| `post-status` | `published` (default) or `draft`; others get 400 | +| `visibility` | `public`; `private` and `unlisted` are saved as drafts (StarPunk has no private posts); others get 400 | +| `video`, `audio` | 400 (not supported) | +| `location`, `checkin`, others | Ignored (allowed by 3.3.5) | +| `mp-slug` | Custom slug | +| `mp-syndicate-to` | Crosspost targets. **Absent means none** (v2.9.0). See [syndication-architecture.md](syndication-architecture.md#choosing-targets) | + +`mp-*` keys are read as commands from the top level or from inside JSON +`properties`, and are never stored. JSON property values must be arrays; a +bare scalar is wrapped on create. If anything fails after the note is +created, the note is removed and 500 is returned, so the client never +believes a half-made post failed. + +Post types advertised in `q=config`: note, article, photo, reply, like, +repost, bookmark. + +### Update, delete, undelete + +- **Update** (JSON only, `update` scope) targets a `/note/` URL on + this site. + - `replace` works on `content`, `name`, `category`, `in-reply-to`, + `post-status` and `photo`. + - `add` works on `category` and `photo` only. + - `delete` takes a list of property names, or values to remove for + `category` and `photo`. + - Values must be arrays. An update without any operation gets 400. + Unsupported properties get 400. + - Photos are resolved before anything changes. Success is **204**. + - Edits follow crossposts and are re-announced to Webmention targets and + WebSub subscribers. +- **Delete** (`delete` scope) is soft: the note is moved to the trash, its + page returns 410, and `undelete` restores it. Both return **204**. + +### Queries + +| Query | Scope | Result | +|---|---|---| +| `q=config` | any token | `media-endpoint`, `syndicate-to`, `q` list, `post-types` | +| `q=syndicate-to` | any token | `{"syndicate-to": [{"uid", "name"}]}` | +| `q=source&url=...[&properties[]=...]` | create/update/delete/draft | One post as mf2 JSON. Content comes back as `{"html": ...}` if it was authored as HTML. Includes `syndication` URLs and `post-status` | +| `q=source` without `url` | same | `{"items": [...]}`, drafts included, `limit` (default 10, max 50) and `offset` | +| `q=category[&filter=...]` | same | Tags in use, most used first | + +Unknown or missing `q` gets 400. + +### Media endpoint + +`POST /micropub/media`, multipart with one part named `file`, `media` or +`create` scope. It returns **201** with `Location: /media/`. +Images are JPEG, PNG, GIF, WebP or HEIC, up to 50 MB in. They are optimized +and get responsive variants (`starpunk/media.py`, +[ADR-058](../decisions/ADR-058-image-optimization-strategy.md)). Validation +failures get 400. + +### Known deviations and gaps + +- **403 for `insufficient_scope`** (RFC 6750) where the Micropub error table + says 401. Kept on purpose. +- `add` is only supported for `category` and `photo`. `published`, + `syndication` and `location` can't be updated. `mp-syndicate-to` is only + read on create. +- `location` / `checkin` are ignored, and person tags are dropped. +- `video` and `audio` are refused. +- The `access_token` query parameter is still accepted on GET. +- Only notes (`/note/`) can be the target of update/delete/source. + +--- + +## IndieAuth + +StarPunk is its own IndieAuth authorization server for Micropub clients, +issuing tokens for the single identity `ADMIN_ME`. The admin approves +clients on a consent screen protected by OIDC login. Supported: the +authorization code flow with mandatory PKCE S256, `iss` in responses (RFC +9207), the metadata endpoint, a profile-only flow, a token endpoint, RFC +7009 revocation, and legacy token verification (`GET /auth/token`). Client +`redirect_uri`s must be same-origin or published by the client (JSON +metadata or `rel=redirect_uri`). + +Full description, scopes and gaps: +[simplified-auth-architecture.md](simplified-auth-architecture.md). +Decision: [ADR-064](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md). + +Known gaps: `scopes_supported` doesn't list `draft`. There are no +introspection, userinfo or refresh tokens. The client metadata fetch +doesn't use the pinned SSRF fetcher. + +--- + +## Webmention + +Spec: https://www.w3.org/TR/webmention/ (Recommendation, 12 January 2017). +Decision: [ADR-063](../decisions/ADR-063-webmention-implementation.md). +Reviews: [v2.6.9 fixes](../design/v2.6.9/2026-11-03-webmention-processing-fixes.md), +[v2.7.0 compliance](../design/v2.7.0/2026-11-03-webmention-spec-compliance.md), +[v2.7.2 remaining SHOULDs](../design/v2.7.2/2026-11-03-webmention-shoulds.md). + +### Endpoint discovery (advertising) + +With `WEBMENTION_ENABLED` (default true), every HTML response carries +`Link: ; rel="webmention"`, and `base.html` has +``. When it is off, the receiving +route isn't registered at all. + +### Receiving + +`POST /webmention` (`routes/webmention.py`): + +1. Rate limits: 60 requests per minute per client IP and 10 per minute per + source domain (`WEBMENTION_RATE_LIMIT_*`). Over the limit gets 429 with + `Retry-After`. The limiter is in memory, per process. The client IP + comes from `X-Forwarded-For` only when `TRUSTED_PROXY=true`. +2. Form-encoded (JSON also accepted). `source` and `target` are required, + http(s), at most 2048 characters, and different from each other. + Otherwise 400. +3. The target's host and port must be this site's. The fragment is stripped + before storing. The target must be a **published note**: anything else, + including the home page, gets 400 `invalid_target`. +4. The row is upserted into `webmentions` (unique on source + target) as + `pending`, and **202** is returned. A repeat from the same source resets + it to `pending` (an update, 3.2.4). + +Verification is asynchronous (`WebmentionWorker`, poll +`WEBMENTION_POLL_INTERVAL` 10 s, batch of 5): + +- **Fetch** the source with `safe_get` (redirects followed and checked, + 1 MB, 10 s), with an `Accept` header preferring HTML. +- **Exact-match verification** (3.2.2), per media type: + - HTML: every link-bearing attribute (`lxml iterlinks`: `a`/`link` href, + `img`/`video`/`audio` src, ...), resolved against the final URL. + - JSON: any string value. + - Other `text/*`: substring match. + - Any other type: no match. + - Fragments are ignored on both sides. +- **Parse mf2** (HTML only) with mf2py: + - `mf2_utils.responding_entry()` picks the h-entry that responds to the + target. + - `response_type()` classifies it as reply, like, repost, bookmark or + mention. + - `entry_author()` follows the authorship algorithm without extra + fetches: author property, then the parent h-feed's author, then + `rel=author`, then the representative h-card. + - Also stored: a content snippet (e-content or p-summary, sanitized with + nh3, at most 500 characters), the source's `u-url` and `dt-published` + (migration 014). + - The author URL and photo are kept only if they are absolute http(s) + URLs (XSS, 4.1). +- **Outcomes**: + - Valid: `validation_status = 'valid'`. A first-time mention gets + `moderation_status = 'approved'` if `WEBMENTION_AUTO_APPROVE` (default + true), otherwise `pending`. An update keeps the admin's earlier + moderation decision. + - Source returns 4xx (including 410), or no longer links: `invalid`, + which hides it (3.2.4 deletion). + - Network error, timeout or 5xx: a mention that was valid before stays + valid with its old data. A new one becomes `error`. + - A source that is one of the note's own syndicated copies + (`syndications.remote_url`) is `invalid` (v2.8.0). +- **Re-send on display change** (3.1.4, v2.7.2): if what the note shows + for this webmention changed, the note's own outgoing webmentions are + re-queued. That covers a new response, a changed author or snippet, or a + change of shown/hidden. Unchanged re-validations send nothing, so two + sites doing the same don't ping-pong. + +**Moderation and display.** `/admin/webmentions` lists, filters, and +approves, hides or deletes mentions, one at a time or in bulk. Changes that +alter what is shown also re-send the note's webmentions. Note pages show +approved, valid mentions grouped as replies (`u-comment h-cite`), likes, +reposts and bookmarks (facepiles), and mentions. See +[Microformats2](#microformats2). + +### Sending + +Queued by `webmention_sender.queue_webmentions_for_note()` from `notes.py`. +Sending isn't gated by `WEBMENTION_ENABLED`; it runs whenever the worker +does (`WEBMENTION_WORKER_ENABLED`). + +| Event | Targets | +|---|---| +| Publish | Reply / like / repost / bookmark target first, then `` links from the rendered HTML in document order (not inside `
`/``), absolute http(s) only, de-duplicated, at most 10 |
+| Edit (published) | The same, plus every target notified before and links the edit removed (not capped) (3.1.4) |
+| Delete | Every previously notified target is re-queued (3.1.5); for a hard delete the queue rows are detached first so the cascade doesn't remove them |
+| Undelete | Re-queued again |
+| Displayed responses change | Re-queued (see above) |
+
+Re-queuing resets the cached endpoint, so discovery runs again (3.1.4).
+
+**Endpoint discovery** (3.1.2): GET the target with `safe_get` (redirects
+checked). The first `Link` header with a `rel` token `webmention` wins. The
+header is parsed per RFC 8288: several links per header, several headers,
+rel token lists, case-insensitive. Otherwise the first `` or ``
+with `rel~=webmention` and an `href`, in document order. Relative URLs
+resolve against the final URL, an empty `href` means the target itself, and
+the query string is kept.
+
+**Send** (3.1.3): a form-encoded POST through `safe_post`, pinned and with
+no redirects followed (a 301/302 would turn the POST into a GET).
+
+| Result | Outcome |
+|---|---|
+| Any 2xx | `sent` |
+| 429, 5xx, network error | Retried after 1 h, 6 h, 24 h; `failed` after the 4th attempt |
+| Other 3xx/4xx, SSRF-blocked endpoint | `failed` |
+| No endpoint | `no_endpoint` |
+
+**Deleted posts**: `/note/` returns **410 Gone** with a tombstone page
+for soft-deleted notes, and for hard-deleted notes that had sent
+webmentions (3.1.5).
+
+### Security (section 4)
+
+- XSS: author URL and photo must be http(s). Snippets are sanitized with
+  nh3 (and re-sanitized after truncation). The mentions list uses
+  `striptags`.
+- SSRF: all fetches and POSTs go through the pinned fetcher described
+  above, so the endpoint URL is checked before POSTing.
+- DoS: rate limits on receiving, a 1 MB / 10 s cap on fetches, and
+  asynchronous processing.
+
+### Known limits
+
+From the v2.7.0 review, still current:
+
+- Home-page mentions (and mentions of anything that isn't a published note)
+  are refused rather than stored.
+- Discovery ignores HTTP cache headers (5.3). Targets are fetched only when
+  a note is created, edited or deleted.
+- The 410 page is a generic tombstone without microformats.
+- `error` rows (transient failures of a new mention, or unexpected errors)
+  are not retried automatically. They are re-checked only when the sender
+  re-sends.
+- The 202 response has no `Location` status URL.
+
+---
+
+## Microformats2
+
+Specs: microformats2 parsing, h-entry, h-card, h-feed, h-cite,
+representative h-card, authorship, Post Type Discovery. Decisions:
+[ADR-040](../decisions/ADR-040-microformats2-compliance.md),
+[ADR-061](../decisions/ADR-061-author-discovery.md). Review:
+[v2.8.0 microformats2 review](../design/v2.8.0/2026-11-03-microformats2-review.md).
+
+### What pages publish
+
+| Page | Markup |
+|---|---|
+| `/` (home) | `h-feed` with `p-name`, hidden `u-url`, hidden `p-author h-card` (photo, name, URL, note), feed `u-photo`; each note an `h-entry` preview with `u-uid` |
+| `/note/` | `h-entry`: `p-name` only when the note starts with a `# Heading` (so plain notes have no implied name); `u-photo` as direct children above `e-content`; `u-url u-uid` with `dt-published` (RFC 3339 UTC `Z`); `dt-updated`; `p-category` with `rel=tag`; `u-syndication` links; hidden `p-author h-card` |
+| Replies | `u-in-reply-to h-cite` holding the cached reply context (`p-content`, `u-url`) |
+| Likes / reposts / bookmarks | `u-like-of` / `u-repost-of` / `u-bookmark-of` link with "★ Liked" / "🔁 Reposted" / "🔖 Bookmarked" |
+| Received responses | `u-comment h-cite` (replies: `p-author h-card` with `u-url` on an inner link, `u-photo`, `p-name`; `e-content`; `u-url`; `dt-published`), and `u-like`, `u-repost`, `u-bookmark`, `u-mention` h-cites. Faces beyond 8 are `hidden`, not omitted |
+| `/likes`, `/tag/` | `h-feed` with `p-name`, `u-url`, `p-author h-card` |
+
+Post Type Discovery gives note, article, reply, like, repost, bookmark and
+photo correctly.
+
+### Identity links
+
+`base.html` always emits `rel=me` and `rel=author` pointing at the author's
+home page (`author.url`, else `author.me`, else `ADMIN_ME`), even on a fresh
+install (v2.8.0). Further `rel=me` links come from the discovered profile.
+Because the `p-author h-card`'s `u-url` matches the `rel=me` URL, parsers
+treat it as the page's representative h-card. Without a discovered profile
+there is no h-card, only the `rel` links.
+
+### Consuming
+
+- **Author profile** (`author_discovery.py`, ADR-061): on login, StarPunk
+  fetches `ADMIN_ME`, picks its representative h-card with
+  `mf2_utils.representative_hcard()` (uid and url match the page, then
+  url matches a `rel=me`, then a single h-card whose url is the page),
+  parsed with the URL after redirects. It stores name, photo, URL, note and
+  rel-me links, cached for 24 hours. If discovery fails, the stale cache is
+  used.
+- **Webmention sources**: `responding_entry`, `response_type` and
+  `entry_author` (see [Webmention](#webmention)).
+- **Reply context** (`reply_context.py`): title, snippet, author and site
+  name of the post being replied to, liked, reposted or bookmarked, cached
+  in `reply_contexts`.
+
+### Known gaps
+
+From the v2.8.0 review, "Not done":
+
+- The reply-context `h-cite` doesn't carry the cached author h-card, name or
+  published time.
+- Photo alt text falls back to "Image" when a photo-only post has no
+  caption.
+- Person tags (`p-category h-card`) aren't supported.
+- Webmentions received before v2.8.0 keep NULL source details until they
+  are re-validated.
+
+---
+
+## WebSub
+
+Spec: https://www.w3.org/TR/websub/. Decision:
+[ADR-071](../decisions/ADR-071-websub.md), including its v2.10.1
+amendments, which replace the original text where they differ.
+
+### Topics
+
+All absolute URLs under `SITE_URL`:
+
+| Topic | Content type | Updated when |
+|---|---|---|
+| `/` | text/html | A public non-like note changes |
+| `/feed.atom`, `/feed.rss`, `/feed.json` | feed types | A public non-like note changes |
+| `/likes` | text/html | A public like changes |
+| `/tag/` | text/html | A note with that tag (before or after the change) changes |
+
+`/feed.xml` (legacy) advertises `/feed.rss` as its `rel=self`. The
+negotiated `/feed` advertises the topic of the format it served.
+
+### Discovery
+
+Topic responses (200/304) carry `Link: ; rel="hub"` and
+`Link: ; rel="self"`. The same links are embedded: ``
+and `` in HTML heads, a hub `` in Atom, an
+`` in RSS, and `"hubs"` in JSON Feed. All of this
+happens only while `WEBSUB_ENABLED` (default true).
+
+### On change
+
+`websub.note_changed()` runs on create, edit, publish/unpublish, delete and
+undelete, and once photos are attached. If the note is or was public, it:
+
+1. bumps `content_version`, which is in the feed cache key and the ETag, so
+   every process serves fresh feeds at once;
+2. queues one delivery per active subscription for each affected topic.
+   Only the latest content is sent: a newer delivery replaces a waiting one.
+
+Drafts that stay drafts change nothing.
+
+### Hub
+
+`POST /websub`, form-encoded only (case-insensitive check):
+
+- `hub.mode` is `subscribe` or `unsubscribe`.
+- `hub.topic` must be one of the topics above, after decoding unreserved
+  percent-encodings and comparing scheme and host case-insensitively. Tag
+  topics must name an existing tag.
+- `hub.callback` must:
+  - be printable, at most 2,048 characters, and absolute http(s);
+  - not be on this site;
+  - use port 80, 443 or 1024 and up;
+  - pass the SSRF check.
+
+  It is stored with an IDNA host.
+- `hub.secret` must be non-empty and under 200 bytes. `hub.lease_seconds`
+  is clamped to 1 to 30 days (default 10). Both are ignored for
+  unsubscriptions.
+- The hub answers **202**, then verifies later. Errors are 4xx with a
+  plain-text reason.
+
+Limits (429 when hit):
+
+- 30 requests per minute per client IP (per process; needs
+  `TRUSTED_PROXY=true` behind a proxy);
+- at most 200 pending verifications;
+- `WEBSUB_MAX_SUBSCRIPTIONS` (1000) in total;
+- `WEBSUB_MAX_PER_HOST` (25) per callback IP address.
+
+The limits count pending requests too. Renewals are always allowed.
+
+`WebSubWorker` (file lock, poll `WEBSUB_POLL_INTERVAL` 5 s) handles each
+queued item on its own, so one bad item can't stop it:
+
+- **Verification of intent** (5.3): `GET` the callback (existing query
+  kept) with `hub.mode`, the topic exactly as requested, `hub.challenge`
+  and `hub.lease_seconds`. Success is a 2xx whose body equals the challenge.
+  Replies over 4 KB and redirects fail. Network/DNS errors and 5xx are
+  retried after 1, 5 and 15 minutes. A request id per intent (migration
+  017) stops an older verification from consuming a newer request. A
+  subscription row exists only once verified.
+- **Distribution** (7): the topic is rendered inside the app, once per pass,
+  and POSTed with its `Content-Type`, `Link` rel=hub/self, and
+  `X-Hub-Signature: sha256=` when there is a secret.
+  - 2xx: success.
+  - 410: removes the subscription.
+  - Other failures: retried after 1 min, 5 min, 30 min, 2 h and 6 h, then
+    that delivery is dropped. The subscription stays until its lease ends.
+  - A topic that renders 404/410 ends its subscriptions with a
+    `hub.mode=denied` notice.
+- Expired subscriptions are pruned hourly.
+
+Outbound requests use `safe_get` / `safe_post`: pinned, no redirects,
+10 s hard deadline.
+
+**External hub**: with `WEBSUB_HUB_URL` set, StarPunk advertises that hub
+and sends it a `hub.mode=publish` ping per changed topic. Its own `/websub`
+refuses new subscriptions but still accepts unsubscriptions.
+
+The admin dashboard shows subscribers per topic and deliveries being
+retried.
+
+### Known limits
+
+- The hub serves only this site's topics, by design. websub.rocks' hub
+  tests use their own topics, so they can't be run against it.
+- Rate limiting is per process and in memory.
+- Deliveries always carry the full topic content (no diffs). Fat pings
+  aren't sent to external hubs.
+
+---
+
+## Feeds
+
+Decisions: [ADR-014](../decisions/ADR-014-rss-feed-implementation.md),
+[ADR-038](../decisions/ADR-038-syndication-formats.md),
+[ADR-059](../decisions/ADR-059-full-feed-media-standardization.md).
+
+| URL | Format |
+|---|---|
+| `/feed.rss` | RSS 2.0 (with `atom:link rel=self` and Media RSS) |
+| `/feed.xml` | Legacy alias of `/feed.rss` |
+| `/feed.atom` | Atom 1.0 |
+| `/feed.json` | JSON Feed 1.1 |
+| `/feed` | Content negotiation on `Accept` (RSS default; 406 with `X-Available-Formats` if nothing fits; `Vary: Accept`) |
+| `/opml.xml` | OPML 2.0 listing the three feeds |
+
+- Feeds contain the newest `FEED_MAX_ITEMS` (50) published notes, with full
+  HTML content and media. Likes are excluded, as on the home page.
+  Reposts and bookmarks start with a "🔁 Reposted" / "🔖 Bookmarked" line.
+- Feeds are cached for `FEED_CACHE_SECONDS` (300). The cache key and ETag
+  include `content_version`, so any change to a public note invalidates
+  them in every process. `If-None-Match` gets 304.
+- `base.html` advertises the negotiated `/feed` (as RSS) and the OPML file
+  with `rel=alternate`. Atom and JSON Feed are listed in the OPML but have
+  no `` of their own.
+- WebSub hub links are embedded in each feed (see above).
+
+Gaps: there are no per-tag feeds (tag pages are h-feeds and WebSub topics,
+but have no RSS/Atom/JSON equivalent). The `/likes` page has no feed.
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 32b3365..c79b0ac 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -1,1130 +1,338 @@
 # StarPunk Architecture Overview
 
-**Version**: v0.9.5 (2025-11-24)
-**Status**: Pre-V1 Release (Micropub endpoint pending)
+**Version**: 2.10.1 (2026-11-03)
+**Status**: Current. Describes the system as it is in the code today.
 
-## Executive Summary
+## Purpose
 
-StarPunk is a minimal, single-user IndieWeb CMS designed around the principle: "Every line of code must justify its existence." The architecture prioritizes simplicity, standards compliance, and user data ownership through careful technology selection and hybrid data storage.
+StarPunk is a minimal, single-user IndieWeb blog/CMS. One person (the site
+owner) writes short notes, which are published as microformats2-marked HTML
+pages and as RSS, Atom and JSON feeds. The site takes part in the IndieWeb:
+it accepts posts from Micropub clients, issues its own IndieAuth tokens for
+them, sends and receives Webmentions, pushes feed updates with WebSub, and
+crossposts (POSSE) to GoToSocial, Bluesky and Threads.
 
-**Core Architecture**: Flask web application with hybrid file+database storage, server-side rendering, delegated authentication (IndieLogin.com), and containerized deployment.
+Guiding principle: "every line of code must justify its existence". It is a
+single Flask application with server-side rendering, SQLite and plain files.
+There is no JavaScript build step, no external database and no message
+broker. Background work runs in threads inside the web processes.
 
-**Technology Stack**: Python 3.11, Flask, SQLite, Jinja2, Gunicorn, uv package manager
-**Deployment**: Container-based (Podman/Docker) with automated CI/CD (Gitea Actions)
-**Authentication**: IndieAuth via IndieLogin.com with PKCE security
+## Related documents
 
-## System Architecture
+| Topic | Document |
+|-------|----------|
+| Dependencies, runtime, tests, CI | [technology-stack.md](technology-stack.md) |
+| Database schema and migrations | [database.md](database.md) |
+| Build, configuration and production deployment | [deployment.md](deployment.md) |
+| Admin login (OIDC) and the built-in IndieAuth server | [simplified-auth-architecture.md](simplified-auth-architecture.md) |
+| Micropub, IndieAuth, Webmention, microformats2, WebSub, feeds | [indieweb-protocols.md](indieweb-protocols.md) |
+| Crossposting (POSSE) to GoToSocial, Bluesky, Threads | [syndication-architecture.md](syndication-architecture.md) |
 
-### High-Level Components
+Key decisions:
+[ADR-064](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md)
+(OIDC login + built-in IndieAuth server),
+[ADR-063](../decisions/ADR-063-webmention-implementation.md) (Webmention),
+[ADR-065](../decisions/ADR-065-direct-syndication-posse.md),
+[ADR-066](../decisions/ADR-066-bluesky-syndication.md),
+[ADR-069](../decisions/ADR-069-threads-syndication.md) and
+[ADR-070](../decisions/ADR-070-crosspost-links-and-cards.md) (crossposting),
+[ADR-067](../decisions/ADR-067-micropub-update-delete.md) (Micropub update/delete),
+[ADR-068](../decisions/ADR-068-likes-and-reposts.md) (likes and reposts),
+[ADR-071](../decisions/ADR-071-websub.md) (WebSub),
+[ADR-057](../decisions/ADR-057-media-attachment-model.md) and
+[ADR-058](../decisions/ADR-058-image-optimization-strategy.md) (media),
+[ADR-034](../decisions/ADR-034-full-text-search.md) (search),
+[ADR-052](../decisions/ADR-052-configuration-system-architecture.md) (configuration),
+[ADR-053](../decisions/ADR-053-performance-monitoring-strategy.md) and
+[ADR-060](../decisions/ADR-060-production-hotfix-metrics-dashboard.md) (metrics),
+[ADR-054](../decisions/ADR-054-structured-logging-architecture.md) (logging),
+[ADR-055](../decisions/ADR-055-error-handling-philosophy.md) (errors).
+
+## System at a glance
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                         User Browser                         │
-└───────────────┬─────────────────────────────────────────────┘
-                │
-                │ HTTP/HTTPS
-                ↓
-┌─────────────────────────────────────────────────────────────┐
-│                      Flask Application                       │
-│  ┌─────────────────────────────────────────────────────────┤
-│  │ Web Interface (Jinja2 Templates)                         │
-│  │  - Public: Homepage, Note Permalinks                     │
-│  │  - Admin: Dashboard, Note Editor                         │
-│  └──────────────────────────────┬──────────────────────────┘
-│  ┌──────────────────────────────┴──────────────────────────┐
-│  │ API Layer (RESTful + Micropub)                           │
-│  │  - Notes CRUD API                                        │
-│  │  - Micropub Endpoint                                     │
-│  │  - RSS Feed Generator                                    │
-│  │  - Authentication Handlers                               │
-│  └──────────────────────────────┬──────────────────────────┘
-│  ┌──────────────────────────────┴──────────────────────────┐
-│  │ Business Logic                                           │
-│  │  - Note Management (create, read, update, delete)        │
-│  │  - File/Database Sync                                    │
-│  │  - Markdown Rendering                                    │
-│  │  - Slug Generation                                       │
-│  │  - Session Management                                    │
-│  └──────────────────────────────┬──────────────────────────┘
-│  ┌──────────────────────────────┴──────────────────────────┐
-│  │ Data Layer                                               │
-│  │  ┌──────────────────┐    ┌─────────────────────────┐   │
-│  │  │ File Storage     │    │ SQLite Database         │   │
-│  │  │                  │    │                         │   │
-│  │  │ Markdown Files   │    │ - Note Metadata         │   │
-│  │  │ (Pure Content)   │    │ - Sessions              │   │
-│  │  │                  │    │ - Tokens                │   │
-│  │  │ data/notes/      │    │ - Auth State            │   │
-│  │  │   YYYY/MM/       │    │                         │   │
-│  │  │     slug.md      │    │ data/starpunk.db        │   │
-│  │  └──────────────────┘    └─────────────────────────┘   │
-│  └─────────────────────────────────────────────────────────┘
-└─────────────────────────────────────────────────────────────┘
-                │
-                │ HTTPS
-                ↓
-┌─────────────────────────────────────────────────────────────┐
-│               External Services                              │
-│  - IndieLogin.com (Authentication)                           │
-│  - User's Website (Identity Verification)                    │
-│  - Micropub Clients (Publishing)                             │
-└─────────────────────────────────────────────────────────────┘
+                       Internet
+                          │
+                    ┌─────▼─────┐   TLS, security headers,
+                    │   Caddy   │   sets X-Forwarded-For
+                    └─────┬─────┘
+                          │ HTTP :8000
+┌─────────────────────────▼─────────────────────────────────────────┐
+│ Container: gunicorn, 4 sync worker processes                       │
+│                                                                    │
+│ each process = Flask app (create_app) + daemon threads:            │
+│   request handling    routes/* blueprints -> Jinja2 templates      │
+│   webmention worker   works its queues only while holding a lock   │
+│   websub worker       works its queues only while holding a lock   │
+│   syndication worker  claims rows with a lease in SQLite           │
+│   memory monitor      per-process metrics                          │
+└───────────────┬──────────────────────────────┬─────────────────────┘
+                │                              │
+        ┌───────▼────────┐          ┌──────────▼──────────────────┐
+        │ /data volume   │          │ Outbound HTTP               │
+        │ starpunk.db    │          │ OIDC provider, IndieAuth    │
+        │ notes/*.md     │          │ client pages, webmention    │
+        │ media/         │          │ sources/targets, WebSub     │
+        │ logs/, locks   │          │ callbacks, GoToSocial,      │
+        └────────────────┘          │ Bluesky, Threads            │
+                                    └─────────────────────────────┘
 ```
 
-## Core Principles
-
-### 1. Radical Simplicity
-- Total dependencies: 6 direct packages
-- No build tools, no npm, no bundlers
-- Server-side rendering eliminates frontend complexity
-- Single file SQLite database
-- Zero configuration frameworks
-
-### 2. Hybrid Data Architecture
-**Files for Content**: Markdown notes stored as plain text files
-- Maximum portability
-- Human-readable
-- Direct user access
-- Easy backup (copy, rsync, git)
-
-**Database for Metadata**: SQLite stores structured data
-- Fast queries and indexes
-- Referential integrity
-- Efficient filtering and sorting
-- Transaction support
-
-**Sync Strategy**: Files are authoritative for content; database is authoritative for metadata. Both must stay in sync.
-
-### 3. Standards-First Design
-- IndieWeb: Microformats2, IndieAuth, Micropub
-- Web: HTML5, RSS 2.0, HTTP standards
-- Security: OAuth 2.0, HTTPS, secure cookies
-- Data: CommonMark markdown
-
-### 4. API-First Architecture
-All functionality exposed via API, web interface consumes API. This enables:
-- Micropub client support
-- Future client applications
-- Scriptable automation
-- Clean separation of concerns
-
-### 5. Progressive Enhancement
-- Core functionality works without JavaScript
-- JavaScript adds optional enhancements (markdown preview)
-- Server-side rendering for fast initial loads
-- Mobile-responsive from the start
-
-## Component Descriptions
-
-### Web Layer
-
-#### Public Interface
-**Purpose**: Display published notes to the world
-**Technology**: Server-side rendered HTML (Jinja2)
-**Status**: ✅ IMPLEMENTED (v0.5.0)
-
-**Routes** (Implemented):
-- `GET /` - Homepage with recent published notes
-- `GET /note/` - Individual note permalink
-- `GET /feed.xml` - RSS 2.0 feed (v0.6.0)
-- `GET /health` - Health check endpoint (v0.6.0)
-
-**Features**:
-- Microformats2 markup (h-entry, h-card, h-feed) - ⚠️ Not validated
-- Reverse chronological note list
-- Clean, minimal responsive CSS
-- Mobile-responsive
-- No JavaScript required
-
-#### Admin Interface
-**Purpose**: Manage notes (create, edit, publish)
-**Technology**: Server-side rendered HTML (Jinja2)
-**Status**: ✅ IMPLEMENTED (v0.5.2)
-
-**Routes** (Implemented):
-- `GET /auth/login` - Login form (v0.9.2: moved from /admin/login)
-- `POST /auth/login` - Initiate IndieLogin OAuth flow
-- `GET /auth/callback` - Handle IndieLogin callback
-- `POST /auth/logout` - Logout and destroy session
-- `GET /admin` - Dashboard (list of all notes, published + drafts)
-- `GET /admin/new` - Create note form
-- `POST /admin/new` - Create note handler
-- `GET /admin/edit/` - Edit note form
-- `POST /admin/edit/` - Update note handler
-- `POST /admin/delete/` - Delete note handler
-
-**Development Routes** (DEV_MODE only):
-- `GET /dev/login` - Development authentication bypass (v0.5.0)
-
-**Features**:
-- Markdown editor (textarea)
-- No real-time preview (deferred to V2)
-- Publish/draft toggle
-- Protected by session authentication
-- Flash messages for feedback
-- Note: Admin routes changed from `/admin/*` to `/auth/*` for auth in v0.9.2
-
-### API Layer
-
-#### Notes API
-**Purpose**: RESTful CRUD operations for notes
-**Authentication**: Session-based (admin interface)
-**Status**: ❌ NOT IMPLEMENTED (Optional for V1, deferred to V2)
-
-**Planned Routes** (Not Implemented):
-```
-GET    /api/notes           List published notes (JSON)
-POST   /api/notes           Create new note (JSON)
-GET    /api/notes/    Get single note (JSON)
-PUT    /api/notes/    Update note (JSON)
-DELETE /api/notes/    Delete note (JSON)
-```
-
-**Current Workaround**: Admin interface uses HTML forms (POST), not JSON API
-**Note**: Not required for V1, admin interface is fully functional without REST API
-
-#### Micropub Endpoint
-**Purpose**: Accept posts from external Micropub clients (Quill, Indigenous, etc.)
-**Authentication**: IndieAuth bearer tokens
-**Status**: ❌ NOT IMPLEMENTED (Critical blocker for V1)
-
-**Planned Routes** (Not Implemented):
-```
-POST /api/micropub          Create note (h-entry)
-GET  /api/micropub?q=config Query configuration
-GET  /api/micropub?q=source Query note source by URL
-```
-
-**Planned Content Types**:
-- application/json
-- application/x-www-form-urlencoded
-
-**Target Compliance**: Micropub specification
-**Current Status**:
-- Token model exists in database
-- No endpoint implementation
-- No token validation logic
-- Will require IndieAuth token endpoint or external token service
-
-#### RSS Feed
-**Purpose**: Syndicate published notes
-**Technology**: feedgen library
-**Status**: ✅ IMPLEMENTED (v0.6.0)
-
-**Route**: `GET /feed.xml`
-**Format**: Valid RSS 2.0 XML
-**Caching**: 5 minutes server-side (configurable via FEED_CACHE_SECONDS)
-**Features**:
-- Limit to 50 most recent published notes (configurable via FEED_MAX_ITEMS)
-- RFC-822 date formatting (pubDate)
-- CDATA-wrapped HTML content for feed readers
-- Proper GUID for each item (note permalink)
-- Auto-discovery link in HTML templates ()
-- Cache-Control headers for client caching
-- ETag support for conditional requests
-
-### Business Logic Layer
-
-#### Note Management
-**Operations**:
-1. **Create**: Generate slug → write file → insert database record
-2. **Read**: Query database for path → read file → render markdown
-3. **Update**: Write file atomically → update database timestamp
-4. **Delete**: Mark deleted in database → optionally archive file
-
-**Key Components**:
-- Slug generation (URL-safe, unique)
-- Markdown rendering (markdown library)
-- Content hashing (integrity verification)
-- Atomic file operations (prevent corruption)
-
-#### File/Database Sync
-**Strategy**: Write files first, then database
-**Rollback**: If database operation fails, delete/restore file
-**Verification**: Content hash detects external modifications
-**Integrity Check**: Optional scan for orphaned files/records
-
-#### Authentication
-**Admin Auth**: IndieLogin.com OAuth 2.0 flow with PKCE
-**Status**: ✅ IMPLEMENTED (v0.8.0, refined through v0.9.5)
-
-**Flow**:
-1. User enters website URL (their "me" identity)
-2. Generate PKCE code_verifier and code_challenge (SHA-256)
-3. Store state token + code_verifier in database (5 min expiry)
-4. Redirect to indielogin.com/authorize with:
-   - client_id (SITE_URL with trailing slash)
-   - redirect_uri (SITE_URL/auth/callback)
-   - state (CSRF protection)
-   - code_challenge + code_challenge_method (S256)
-5. IndieLogin.com verifies identity via RelMeAuth or email
-6. Callback to /auth/callback with code + state
-7. Verify state token (CSRF check)
-8. POST code + code_verifier to indielogin.com/authorize (NOT /token)
-9. Receive verified "me" URL
-10. Verify "me" matches ADMIN_ME config
-11. Create session with SHA-256 hashed token
-12. Store in HttpOnly, Secure, SameSite=Lax cookie named "starpunk_session"
-
-**Security Features** (v0.8.0-v0.9.5):
-- PKCE prevents authorization code interception
-- State tokens prevent CSRF attacks
-- Session token hashing (SHA-256) before database storage
-- Single-use state tokens with short expiry
-- Automatic trailing slash normalization on SITE_URL (v0.9.1)
-- Uses authorization endpoint (not token endpoint) per IndieAuth spec (v0.9.4)
-- Session cookie renamed to avoid Flask session collision (v0.5.1)
-
-**Development Mode** (v0.5.0):
-- `/dev/login` bypasses IndieLogin for local development
-- Requires DEV_MODE=true and DEV_ADMIN_ME configuration
-- Shows warning in logs
-
-**Micropub Auth**: IndieAuth token verification
-**Status**: ❌ NOT IMPLEMENTED (Required for Micropub)
-
-**Planned Implementation**:
-- Client obtains token via external IndieAuth token endpoint
-- Token sent as Bearer in Authorization header
-- Verify token exists in database and not expired
-- Check scope permissions (create, update, delete)
-- OR: Delegate token verification to external IndieAuth server
-
-### Data Layer
-
-#### File Storage
-**Location**: `data/notes/`
-**Structure**: `YYYY/MM/slug.md`
-**Format**: Pure markdown, no frontmatter
-**Operations**:
-- Atomic writes (temp file → rename)
-- Directory creation (makedirs)
-- Content reading (UTF-8 encoding)
-
-**Example**:
-```
-data/notes/
-├── 2024/
-│   ├── 11/
-│   │   ├── my-first-note.md
-│   │   └── another-note.md
-│   └── 12/
-│       └── december-note.md
-```
-
-#### Database Storage
-**Location**: `data/starpunk.db`
-**Engine**: SQLite3
-**Status**: ✅ IMPLEMENTED with automatic migration system (v0.9.0)
-
-**Tables**:
-- `notes` - Note metadata (slug, file_path, published, created_at, updated_at, deleted_at, content_hash)
-- `sessions` - Admin auth sessions (session_token_hash, me, created_at, expires_at, last_used_at, user_agent, ip_address)
-- `tokens` - Micropub bearer tokens (token, me, client_id, scope, created_at, expires_at) - **Table exists but unused**
-- `auth_state` - CSRF state tokens (state, created_at, expires_at, redirect_uri, code_verifier)
-- `schema_migrations` - Migration tracking (migration_name, applied_at) - **Added v0.9.0**
-
-**Indexes**:
-- `notes.created_at` (DESC) - Fast chronological queries
-- `notes.published` - Fast published note filtering
-- `notes.slug` (UNIQUE) - Fast lookup by slug, uniqueness enforcement
-- `notes.deleted_at` - Fast soft-delete filtering
-- `sessions.session_token_hash` (UNIQUE) - Fast auth checks
-- `sessions.me` - Fast user lookups
-- `auth_state.state` (UNIQUE) - Fast state token validation
-
-**Migration System** (v0.9.0):
-- Automatic schema updates on application startup
-- Migration files in `migrations/` directory (SQL format)
-- Executed in alphanumeric order (001, 002, 003...)
-- Fresh database detection (marks migrations as applied without execution)
-- Legacy database detection (applies pending migrations automatically)
-- Migration tracking in schema_migrations table
-- Fail-safe: Application refuses to start if migrations fail
-
-**Queries**: Direct SQL using Python sqlite3 module (no ORM)
-
-## Data Flow Examples
-
-### Creating a Note (via Admin Interface)
-
-```
-1. User fills out form at /admin/new
-   ↓
-2. POST to /api/notes with markdown content
-   ↓
-3. Verify user session (check session cookie)
-   ↓
-4. Generate unique slug from content or timestamp
-   ↓
-5. Determine file path: data/notes/2024/11/slug.md
-   ↓
-6. Create directories if needed (makedirs)
-   ↓
-7. Write markdown content to file (atomic write)
-   ↓
-8. Calculate SHA-256 hash of content
-   ↓
-9. Begin database transaction
-   ↓
-10. Insert record into notes table:
-    - slug
-    - file_path
-    - published (from form)
-    - created_at (now)
-    - updated_at (now)
-    - content_hash
-   ↓
-11. If database insert fails:
-    - Delete file
-    - Return error to user
-   ↓
-12. If database insert succeeds:
-    - Commit transaction
-    - Return success with note URL
-   ↓
-13. Redirect user to /admin (dashboard)
-```
-
-### Reading a Note (via Public Interface)
-
-```
-1. User visits /note/my-first-note
-   ↓
-2. Extract slug from URL
-   ↓
-3. Query database:
-    SELECT file_path, created_at, published
-    FROM notes
-    WHERE slug = 'my-first-note' AND published = 1
-   ↓
-4. If not found → 404 error
-   ↓
-5. Read markdown content from file:
-    - Open data/notes/2024/11/my-first-note.md
-    - Read UTF-8 content
-   ↓
-6. Render markdown to HTML (markdown.markdown())
-   ↓
-7. Render Jinja2 template with:
-    - content_html (rendered HTML)
-    - created_at (timestamp)
-    - slug (for permalink)
-   ↓
-8. Return HTML with microformats markup
-```
-
-### Publishing via Micropub
-
-```
-1. Micropub client POSTs to /api/micropub
-   Headers: Authorization: Bearer {token}
-   Body: {"type": ["h-entry"], "properties": {"content": ["..."]}}
-   ↓
-2. Extract bearer token from Authorization header
-   ↓
-3. Query database:
-    SELECT me, scope FROM tokens
-    WHERE token = {token} AND expires_at > now()
-   ↓
-4. If token invalid → 401 Unauthorized
-   ↓
-5. Parse Micropub JSON payload
-   ↓
-6. Extract content from properties.content[0]
-   ↓
-7. Create note (same flow as admin interface):
-    - Generate slug
-    - Write file
-    - Insert database record
-   ↓
-8. If successful:
-    - Return 201 Created
-    - Set Location header to note URL
-   ↓
-9. Client receives note URL, displays success
-```
-
-### IndieLogin Authentication Flow (v0.9.5 with PKCE)
-
-```
-1. User visits /auth/login
-   ↓
-2. User enters their website: https://alice.example.com
-   ↓
-3. POST to /auth/login with "me" parameter
-   ↓
-4. Validate URL format (must be https://)
-   ↓
-5. Generate PKCE code_verifier (43 random bytes, base64-url encoded)
-   ↓
-6. Generate code_challenge from code_verifier (SHA256 hash, base64-url encoded)
-   ↓
-7. Generate random state token (CSRF protection)
-   ↓
-8. Store state + code_verifier in auth_state table (5-minute expiry)
-   ↓
-9. Normalize client_id by adding trailing slash if missing (v0.9.1)
-   ↓
-10. Build IndieLogin authorization URL:
-    https://indielogin.com/authorize?
-      me=https://alice.example.com
-      client_id=https://starpunk.example.com/  (note trailing slash)
-      redirect_uri=https://starpunk.example.com/auth/callback
-      state={random_state}
-      code_challenge={code_challenge}
-      code_challenge_method=S256
-   ↓
-11. Redirect user to IndieLogin
-   ↓
-12. IndieLogin verifies user's identity:
-    - Checks rel="me" links on alice.example.com
-    - Or sends email verification
-    - User authenticates via chosen method
-   ↓
-13. IndieLogin redirects back:
-    /auth/callback?code={auth_code}&state={state}
-   ↓
-14. Verify state matches stored value (CSRF check, single-use)
-   ↓
-15. Retrieve code_verifier from database using state
-   ↓
-16. Delete state token (single-use enforcement)
-   ↓
-17. Exchange code for verified identity (v0.9.4: uses /authorize, not /token):
-    POST https://indielogin.com/authorize
-      code={auth_code}
-      client_id=https://starpunk.example.com/
-      redirect_uri=https://starpunk.example.com/auth/callback
-      code_verifier={code_verifier}
-   ↓
-18. IndieLogin returns: {"me": "https://alice.example.com"}
-   ↓
-19. Verify me == ADMIN_ME (config)
-   ↓
-20. If match:
-    - Generate session token (secrets.token_urlsafe(32))
-    - Hash token with SHA-256
-    - Insert into sessions table with hash (not plaintext)
-    - Set cookie "starpunk_session" (HttpOnly, Secure, SameSite=Lax)
-    - Redirect to /admin
-   ↓
-21. If no match:
-    - Return "Unauthorized" error
-    - Log attempt with WARNING level
-```
-
-**Key Security Features**:
-- PKCE prevents code interception attacks (v0.8.0)
-- State tokens prevent CSRF (v0.4.0)
-- Session token hashing prevents token exposure if database compromised (v0.4.0)
-- Single-use state tokens (deleted after verification)
-- Short-lived state tokens (5 minutes)
-- Trailing slash normalization fixes client_id validation (v0.9.1)
-- Correct endpoint usage (/authorize not /token) per IndieAuth spec (v0.9.4)
-
-## Security Architecture
-
-### Authentication Security
-
-#### Session Management
-- **Token Generation**: `secrets.token_urlsafe(32)` (256-bit entropy)
-- **Storage**: SHA-256 hash stored in database (plaintext token NEVER stored)
-- **Cookie Name**: `starpunk_session` (v0.5.1: renamed to avoid Flask session collision)
-- **Cookies**: HttpOnly, Secure, SameSite=Lax
-- **Expiry**: 30 days, extendable on use
-- **Validation**: Every protected route checks session via `@require_auth` decorator
-- **Metadata**: Tracks user_agent and ip_address for audit purposes
-
-#### CSRF Protection
-- **State Tokens**: Random tokens for OAuth flows
-- **Expiry**: 5 minutes (short-lived)
-- **Single-Use**: Deleted after verification
-- **SameSite**: Cookies set to Lax mode
-
-#### Access Control
-- **Admin Routes**: Require valid session
-- **Micropub Routes**: Require valid bearer token
-- **Public Routes**: No authentication needed
-- **Identity Verification**: Only ADMIN_ME can authenticate
-
-### Input Validation
-
-#### User Input
-- **Markdown**: Sanitize to prevent XSS in rendered HTML
-- **URLs**: Validate format and scheme (https://)
-- **Slugs**: Alphanumeric + hyphens only
-- **JSON**: Parse and validate structure
-- **File Paths**: Prevent directory traversal (validate against base path)
-
-#### Micropub Payloads
-- **Content-Type**: Verify matches expected format
-- **Required Fields**: Validate h-entry structure
-- **Size Limits**: Prevent DoS via large payloads
-- **Scope Verification**: Check token has required permissions
-
-### Database Security
-
-#### SQL Injection Prevention
-- **Parameterized Queries**: Always use parameter substitution
-- **No String Interpolation**: Never build SQL with f-strings
-- **Input Sanitization**: Validate before database operations
-
-Example:
-```python
-# GOOD
-cursor.execute("SELECT * FROM notes WHERE slug = ?", (slug,))
-
-# BAD (SQL injection vulnerable)
-cursor.execute(f"SELECT * FROM notes WHERE slug = '{slug}'")
-```
-
-#### Data Integrity
-- **Transactions**: Use for multi-step operations
-- **Constraints**: UNIQUE on slugs, file_paths
-- **Foreign Keys**: Enforce relationships (if applicable)
-- **Content Hashing**: Detect unauthorized file modifications
-
-### Network Security
-
-#### HTTPS
-- **Production Requirement**: TLS 1.2+ required
-- **Reverse Proxy**: Nginx/Caddy handles SSL termination
-- **Certificate Validation**: Verify SSL certs on outbound requests
-- **HSTS**: Set Strict-Transport-Security header
-
-#### Security Headers
-```python
-# Set on all responses
-Content-Security-Policy: default-src 'self'
-X-Frame-Options: DENY
-X-Content-Type-Options: nosniff
-Referrer-Policy: strict-origin-when-cross-origin
-```
-
-#### Rate Limiting
-- **Implementation**: Reverse proxy (nginx/Caddy)
-- **Admin Routes**: Stricter limits
-- **API Routes**: Moderate limits
-- **Public Routes**: Permissive limits
-
-### File System Security
-
-#### Atomic Operations
-```python
-# Write to temp file, then atomic rename
-temp_path = f"{target_path}.tmp"
-with open(temp_path, 'w') as f:
-    f.write(content)
-os.rename(temp_path, target_path)  # Atomic on POSIX
-```
-
-#### Path Validation
-```python
-# Prevent directory traversal
-base_path = os.path.abspath(DATA_PATH)
-requested_path = os.path.abspath(os.path.join(base_path, user_input))
-if not requested_path.startswith(base_path):
-    raise SecurityError("Path traversal detected")
-```
-
-#### File Permissions
-- **Data Directory**: 700 (owner only)
-- **Database File**: 600 (owner read/write)
-- **Note Files**: 600 (owner read/write)
-- **Application User**: Dedicated non-root user
-
-## Performance Considerations
-
-### Response Time Targets
-- **API Responses**: < 100ms (database + file read)
-- **Page Renders**: < 200ms (template rendering)
-- **RSS Feed**: < 300ms (query + file reads + XML generation)
-
-### Optimization Strategies
-
-#### Database
-- **Indexes**: On frequently queried columns (created_at, slug, published)
-- **Connection Pooling**: Single connection (single-user, no contention)
-- **Query Optimization**: SELECT only needed columns
-- **Prepared Statements**: Reuse compiled queries
-
-#### File System
-- **Caching**: Consider caching rendered HTML in memory (optional)
-- **Directory Structure**: Year/Month prevents large directories
-- **Atomic Reads**: Fast sequential reads, no locking needed
-
-#### HTTP
-- **Static Assets**: Cache headers on CSS/JS (1 year)
-- **RSS Feed**: Cache for 5 minutes (Cache-Control)
-- **Compression**: gzip/brotli via reverse proxy
-- **ETags**: For conditional requests
-
-#### Rendering
-- **Template Compilation**: Jinja2 compiles templates automatically
-- **Minimal Templating**: Simple templates render fast
-- **Server-Side**: No client-side rendering overhead
-
-### Resource Usage
-
-#### Memory
-- **Flask Process**: ~50MB base
-- **SQLite**: ~10MB typical working set
-- **Total**: < 100MB under normal load
-
-#### Disk
-- **Application**: ~5MB (code + dependencies)
-- **Database**: ~1MB per 1000 notes
-- **Notes**: ~5KB average per markdown file
-- **Total**: Scales linearly with note count
-
-#### CPU
-- **Idle**: Near zero
-- **Request Handling**: Minimal (no heavy processing)
-- **Markdown Rendering**: Fast (pure Python)
-- **Database Queries**: Indexed, sub-millisecond
-
-## Deployment Architecture
-
-**Current State**: ✅ IMPLEMENTED (v0.6.0 - v0.9.5)
-**Technology**: Container-based with Gunicorn WSGI server
-**CI/CD**: Gitea Actions automated builds (v0.9.5)
-
-### Container Deployment (v0.6.0)
-
-**Containerfile**: Multi-stage build using Python 3.11-slim base
-- Stage 1: Build dependencies with uv package manager
-- Stage 2: Production image with non-root user (starpunk:1000)
-- Final size: ~174MB
-
-**Features**:
-- Health check endpoint: `/health` (validates database and filesystem)
-- Gunicorn WSGI server with 4 workers (configurable)
-- Log rotation (10MB max, 3 files)
-- Resource limits (memory, CPU)
-- SELinux compatibility (volume mount flags)
-- Automatic database initialization on first run
-
-**Container Orchestration**:
-- Podman-compatible (rootless, userns=keep-id)
-- Docker Compose compatible
-- Volume mounts for data persistence (`./data:/app/data`)
-- Port mapping (8080:8000)
-- Environment variables for configuration
-
-**CI/CD Pipeline** (v0.9.5):
-- Gitea Actions workflow (.gitea/workflows/build-container.yml)
-- Automated builds on push to main branch
-- Manual trigger support
-- Container registry push
-- Docker and git dependencies installed
-- Node.js support for GitHub Actions compatibility
-
-### Single-Server Deployment
-
-```
-┌─────────────────────────────────────────────────┐
-│ Internet                                        │
-└────────────────┬────────────────────────────────┘
-                 │
-                 │ Port 443 (HTTPS)
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ Nginx/Caddy (Reverse Proxy)                     │
-│  - SSL/TLS termination                          │
-│  - Static file serving                          │
-│  - Rate limiting                                │
-│  - Compression                                  │
-└────────────────┬────────────────────────────────┘
-                 │
-                 │ Port 8000 (HTTP)
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ Gunicorn (WSGI Server)                          │
-│  - 4 worker processes                           │
-│  - Process management                           │
-│  - Load balancing (round-robin)                 │
-└────────────────┬────────────────────────────────┘
-                 │
-                 │ WSGI
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ Flask Application                               │
-│  - Request handling                             │
-│  - Business logic                               │
-│  - Template rendering                           │
-└────────────────┬────────────────────────────────┘
-                 │
-                 ↓
-┌────────────────────────────┬────────────────────┐
-│ File System                │ SQLite Database    │
-│  data/notes/               │  data/starpunk.db  │
-│    YYYY/MM/slug.md         │                    │
-└────────────────────────────┴────────────────────┘
-```
-
-### Process Management (systemd)
-
-```ini
-[Unit]
-Description=StarPunk CMS
-After=network.target
-
-[Service]
-Type=notify
-User=starpunk
-WorkingDirectory=/opt/starpunk
-Environment="PATH=/opt/starpunk/venv/bin"
-ExecStart=/opt/starpunk/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-### Backup Strategy
-
-#### Automated Daily Backup
-```bash
-#!/bin/bash
-# backup.sh - Run daily via cron
-
-DATE=$(date +%Y%m%d)
-BACKUP_DIR="/backup/starpunk"
-
-# Backup data directory (notes + database)
-rsync -av /opt/starpunk/data/ "$BACKUP_DIR/$DATE/"
-
-# Keep last 30 days
-find "$BACKUP_DIR" -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;
-```
-
-#### Manual Backup
-```bash
-# Simple copy
-cp -r /opt/starpunk/data /backup/starpunk-$(date +%Y%m%d)
-
-# Or with compression
-tar -czf starpunk-backup-$(date +%Y%m%d).tar.gz /opt/starpunk/data
-```
-
-### Restore Process
-
-1. Stop application: `sudo systemctl stop starpunk`
-2. Restore data directory: `rsync -av /backup/starpunk/20241118/ /opt/starpunk/data/`
-3. Fix permissions: `chown -R starpunk:starpunk /opt/starpunk/data`
-4. Start application: `sudo systemctl start starpunk`
-5. Verify: Visit site, check recent notes
-
-## Testing Strategy
-
-### Test Pyramid
-
-```
-           ┌─────────────┐
-          /               \
-         /   Manual Tests  \      Validation, Real Services
-        /─────────────────  \
-       /                     \
-      /  Integration Tests    \   API Flows, Database + Files
-     /───────────────────────  \
-    /                           \
-   /        Unit Tests            \  Functions, Logic, Parsing
-  /───────────────────────────────\
-```
-
-### Unit Tests (pytest)
-**Coverage**: Business logic, utilities, models
-**Examples**:
-- Slug generation and uniqueness
-- Markdown rendering with various inputs
-- Content hash calculation
-- File path validation
-- Token generation and verification
-- Date formatting for RSS
-- Micropub payload parsing
-
-### Integration Tests
-**Coverage**: Component interactions, full flows
-**Examples**:
-- Create note: file write + database insert
-- Read note: database query + file read
-- IndieLogin flow with mocked API
-- Micropub creation with token validation
-- RSS feed generation with multiple notes
-- Session authentication on protected routes
-
-### End-to-End Tests
-**Coverage**: Full user workflows
-**Examples**:
-- Admin login via IndieLogin (mocked)
-- Create note via web interface
-- Publish note via Micropub client (mocked)
-- View note on public site
-- Verify RSS feed includes note
-
-### Validation Tests
-**Coverage**: Standards compliance
-**Tools**:
-- W3C HTML Validator (validate templates)
-- W3C Feed Validator (validate RSS output)
-- IndieWebify.me (verify microformats)
-- Micropub.rocks (test Micropub compliance)
-
-### Manual Tests
-**Coverage**: Real-world usage
-**Examples**:
-- Authenticate with real indielogin.com
-- Publish from actual Micropub client (Quill, Indigenous)
-- Subscribe to feed in actual RSS reader
-- Browser compatibility (Chrome, Firefox, Safari, mobile)
-- Accessibility with screen reader
-
-## Monitoring and Observability
-
-### Logging Strategy
-
-#### Application Logs
-```python
-# Structured logging
-import logging
-
-logger = logging.getLogger(__name__)
-
-# Info: Normal operations
-logger.info("Note created", extra={
-    "slug": slug,
-    "published": published,
-    "user": session.me
-})
-
-# Warning: Recoverable issues
-logger.warning("State token expired", extra={
-    "state": state,
-    "age": age_seconds
-})
-
-# Error: Failed operations
-logger.error("File write failed", extra={
-    "path": file_path,
-    "error": str(e)
-})
-```
-
-#### Log Levels
-- **DEBUG**: Development only (verbose)
-- **INFO**: Normal operations (note creation, auth success)
-- **WARNING**: Unusual but handled (expired tokens, invalid input)
-- **ERROR**: Failed operations (file I/O errors, database errors)
-- **CRITICAL**: System failures (database unreachable)
-
-#### Log Destinations
-- **Development**: Console (stdout)
-- **Production**: File rotation (logrotate) + optional syslog
-
-### Metrics (Optional for V2)
-
-**Simple Metrics** (if desired):
-- Note count (query database)
-- Request count (nginx logs)
-- Error rate (grep application logs)
-- Response times (nginx logs)
-
-**Advanced Metrics** (V2):
-- Prometheus exporter
-- Grafana dashboard
-- Alert on error rate spike
-
-### Health Checks
-
-```python
-@app.route('/health')
-def health_check():
-    """Simple health check for monitoring"""
-    try:
-        # Check database
-        db.execute("SELECT 1").fetchone()
-
-        # Check file system
-        os.path.exists(DATA_PATH)
-
-        return {"status": "ok"}, 200
-    except Exception as e:
-        return {"status": "error", "detail": str(e)}, 500
-```
-
-## Migration and Evolution
-
-### V1 to V2 Migration
-
-#### Database Schema Changes
-```sql
--- Add new column with default
-ALTER TABLE notes ADD COLUMN tags TEXT DEFAULT '';
-
--- Create new table
-CREATE TABLE tags (
-    id INTEGER PRIMARY KEY,
-    name TEXT UNIQUE NOT NULL
-);
-
--- Migration script updates existing notes
-```
-
-#### File Format Evolution
-**V1**: Pure markdown
-**V2** (if needed): Add optional frontmatter
-```markdown
+## Request flow
+
+1. Caddy terminates TLS and proxies to gunicorn on port 8000.
+2. `app.py` builds the app once per worker process with
+   `starpunk.create_app()` (`starpunk/__init__.py`). That function loads and
+   validates configuration, configures logging, cleans up old debug and
+   temporary upload files, creates the schema and runs migrations (under a
+   lock, see [database.md](database.md)), creates the connection pool,
+   installs the HTTP metrics middleware, configures the feed cache and rate
+   limiters, fills the FTS index if it is empty, registers blueprints, error
+   handlers and template helpers, and starts the background threads.
+3. `before_request` assigns a correlation ID (included in every log line) and,
+   if a `starpunk_session` cookie is present, verifies it and sets `g.me`.
+4. The blueprint handler runs. Database access goes through `get_db()`, which
+   hands out a pooled, request-scoped SQLite connection.
+5. `after_request` hooks add `Link: ; rel="webmention"` to HTML
+   responses, WebSub `Link rel=hub` / `rel=self` headers to topic responses,
+   and request metrics with an `X-Request-ID` header.
+6. Errors are rendered by the central handlers in `starpunk/errors.py`
+   (JSON for Micropub, HTML pages from `templates/.html` elsewhere).
+
+Writing a note (admin form or Micropub) goes through `starpunk/notes.py`,
+which writes the Markdown file and the `notes` row together. It then updates
+the FTS index, queues outgoing webmentions, fetches a reply context for
+replies, marks crossposts pending, and tells WebSub what changed (bumping the
+site's `content_version` and queueing deliveries). The HTTP response does not
+wait for outbound network calls; the workers make them later.
+
+## Components
+
+### Application core (`starpunk/`)
+
+| Module | Responsibility |
+|--------|----------------|
+| `__init__.py` | App factory `create_app()`, logging setup, request hooks, `/health`, worker start-up, `__version__` |
+| `config.py` | Reads environment variables (and `.env`) into `app.config`; validates and fails fast |
+| `notes.py` | Note CRUD with file and database kept in sync; soft delete and undelete; triggers follow-up work |
+| `models.py` | `Note` and other data classes; Markdown rendering and HTML sanitising (nh3 allow-list) |
+| `utils.py` | Slugs, note file paths (`notes/YYYY/MM/slug.md`), atomic writes, trash, date formatting, `absolute_url_for` |
+| `slug_utils.py` | Custom slug (`mp-slug`) validation and timestamp fallback slugs |
+| `markdown_ext.py` | Markdown extension that turns bare URLs into links |
+| `media.py` | Image upload and validation (including HEIC), resizing, variants (thumb/small/medium/large), attachment to notes |
+| `tags.py` | Tag normalisation and note–tag links |
+| `search.py` | FTS5 full-text search (falls back to `LIKE` if FTS5 is unavailable); index maintained by application code |
+| `auth.py` | Admin login with OpenID Connect (PKCE, nonce, ID-token checks with PyJWT); sessions; `require_auth` |
+| `indieauth.py` | Built-in IndieAuth authorization server: client discovery, codes, hashed access tokens, scopes |
+| `dev_auth.py` | Development-only login (`DEV_MODE=true`) |
+| `micropub.py` | Micropub create, update, delete, undelete; queries (`q=config`, `source`, `syndicate-to`, `category`); photos |
+| `author_discovery.py` | Fetches and caches the owner's h-card from `ADMIN_ME` (24-hour cache) |
+| `mf2_utils.py` | Helpers for consuming microformats2: representative h-card, responding entry, response type, author |
+| `reply_context.py` | Fetches and caches the post a reply responds to |
+| `webmention_sender.py` | Extracts links from rendered notes and queues outgoing webmentions |
+| `webmention_processor.py` | Validates incoming webmentions: fetch source, parse mf2, classify, sanitise content |
+| `webmention_worker.py` | Background thread working the incoming and outgoing webmention queues |
+| `webmention_queries.py` | Webmention queries for display and moderation |
+| `webmention_ssrf.py` | SSRF-safe fetcher: public-address checks, pinned connections, manual redirects, size and time limits |
+| `websub.py` | WebSub publisher (discovery headers and links, `content_version`, queueing) and hub request handling |
+| `websub_worker.py` | Background thread: verification of intent, content delivery, publish pings to an external hub |
+| `syndication.py` | POSSE clients (Mastodon API/GoToSocial, Bluesky, Threads), reconcile logic, syndication worker |
+| `rate_limiter.py` | In-memory sliding-window rate limiter |
+| `errors.py` | Central error handlers |
+| `feeds/` | `rss.py` (feedgen), `atom.py`, `json_feed.py`, `opml.py`, `negotiation.py` (Accept header), `cache.py` (LRU + TTL feed cache with ETags) |
+| `feed.py` | Backward-compatibility re-export of `feeds.rss` |
+| `monitoring/` | Metrics buffer, HTTP middleware, database timing wrapper, memory monitor, business metrics |
+| `database/` | `schema.py` (`INITIAL_SCHEMA_SQL`), `init.py` (`init_db`), `pool.py` (connection pool) |
+| `migrations.py` | Migration runner for `migrations/NNN_*.sql` |
+
+### Routes (`starpunk/routes/`)
+
+| Blueprint | File | Paths |
+|-----------|------|-------|
+| `public` | `public.py` | `/`, `/note/`, `/tag/`, `/likes`, `/media/`, feeds, `/opml.xml` |
+| `auth` | `auth.py` | `/auth/login` (GET, POST), `/auth/callback`, `/auth/logout` (POST) |
+| `indieauth` | `indieauth.py` | `/.well-known/oauth-authorization-server`, `/auth/authorize` (GET, POST), `/auth/authorize/approve`, `/auth/token` (GET, POST), `/auth/revoke` |
+| `micropub` | `micropub.py` | `/micropub` (GET, POST), `/micropub/media` (POST), `/media` (POST, legacy alias) |
+| `admin` | `admin.py` | `/admin/…` (see below) |
+| `search` | `search.py` | `/search`, `/api/search` |
+| `webmention` | `webmention.py` | `/webmention` (GET, POST); registered only when `WEBMENTION_ENABLED` |
+| `websub` | `websub.py` | `/websub` (GET for information, POST to subscribe/unsubscribe) |
+| `dev_auth` | `dev_auth.py` | `/dev/login`; registered only when `DEV_MODE=true` |
+
+`/health` is defined directly in `create_app()`.
+
+### Templates and static files
+
+Jinja2 templates live in `templates/`: public pages, `admin/`, `partials/`
+(for example `responses.html` for webmentions and `reaction.html` for likes,
+reposts and bookmarks) and one page per HTTP error. `templates/base.html`
+carries the discovery links (`rel=micropub`, `indieauth-metadata`,
+`authorization_endpoint`, `token_endpoint`, `webmention`, `hub`/`self`, `me`,
+feeds). Static assets are one stylesheet (`static/css/style.css`) and one
+script (`static/js/preview.js`, the Markdown preview in the admin editor).
+Everything works without JavaScript.
+
+## Public URL surface
+
+| Path | Purpose |
+|------|---------|
+| `/` | Home page: recent published notes (h-feed); likes are kept off it |
+| `/note/` | Note permalink (h-entry), with approved webmentions and reply context |
+| `/tag/` | Notes with a tag |
+| `/likes` | Likes |
+| `/search`, `/api/search` | Full-text search page and JSON API |
+| `/media/` | Uploaded images and their variants |
+| `/feed` | Feed chosen by the `Accept` header (RSS by default; `Vary: Accept`) |
+| `/feed.rss`, `/feed.atom`, `/feed.json` | RSS 2.0, Atom 1.0, JSON Feed 1.1 |
+| `/feed.xml` | Legacy alias of `/feed.rss` |
+| `/opml.xml` | OPML list of the feeds |
+| `/micropub`, `/micropub/media` | Micropub and media endpoints (Bearer token) |
+| `/webmention` | Webmention receiver (POST answers 202; validated asynchronously) |
+| `/websub` | WebSub hub for this site's own topics |
+| `/.well-known/oauth-authorization-server`, `/auth/authorize`, `/auth/token`, `/auth/revoke` | IndieAuth server |
+| `/auth/login`, `/auth/callback`, `/auth/logout` | Admin login via OIDC |
+| `/admin/` | Dashboard (notes, WebSub subscriber counts) |
+| `/admin/new`, `/admin/edit/`, `/admin/delete/` | Note editor |
+| `/admin/webmentions`, `/admin/webmentions/`, `…/action`, `…/bulk-action` | Webmention moderation |
+| `/admin/tokens`, `/admin/tokens//revoke` | Issued IndieAuth tokens |
+| `/admin/syndication//retry` | Retry a failed crosspost |
+| `/admin/metrics-dashboard`, `/admin/metrics`, `/admin/health` | Monitoring (HTML dashboard, JSON metrics, full diagnostics) |
+| `/health` | Public liveness check (`{"status": "ok", "version": …}`); `?detailed=true` requires login |
+
+## Background workers
+
+Gunicorn runs four worker processes and `create_app()` runs in each, so each
+process starts its own daemon threads. Work that must happen once per site is
+coordinated through the data volume:
+
+| Thread | Started when | Coordination | Work |
+|--------|--------------|--------------|------|
+| Webmention worker (`webmention_worker.py`) | `WEBMENTION_WORKER_ENABLED` and not testing | Non-blocking `fcntl.flock` on `webmention-worker.lock` next to the database. Only the holder works the queues; the others try again each poll interval. The OS releases the lock if the holder dies, and the new holder resets rows stuck in `sending`. | Validates received webmentions; discovers endpoints and sends queued outgoing webmentions, with retries |
+| WebSub worker (`websub_worker.py`) | `WEBSUB_ENABLED` and not testing | Same pattern with `websub-worker.lock` | Verifies subscription intents, delivers topic content (signed with `X-Hub-Signature` when the subscriber gave a secret), retries, expires leases; pings an external hub instead if `WEBSUB_HUB_URL` is set |
+| Syndication worker (`syndication.py`) | At least one crosspost target configured, and not testing | No file lock. Rows in `syndications` are claimed with a 5-minute `claimed_until` lease by an atomic `UPDATE`, so any process may work a row but only one at a time; a `version` column keeps edits made during a send. Threads token refreshes are serialised with a lock file next to `threads_token.json`. | Creates, updates or deletes the remote post for each (note, target) pair; up to 8 attempts |
+| Memory monitor (`monitoring/memory.py`) | `METRICS_ENABLED` and not testing | None (per-process metrics) | Samples process memory every `METRICS_MEMORY_INTERVAL` seconds |
+
+All workers run inside an app context, are daemon threads (they end with the
+process) and sleep for their poll interval when there is nothing to do. Under
+the test suite (`TESTING=True`) none of them start; tests call the processing
+functions directly.
+
+## Data storage
+
+Content is kept in files and everything else in SQLite, both under
+`DATA_PATH` (`/data` in the container):
+
+- **Notes**: Markdown files at `notes/YYYY/MM/.md`, written atomically
+  (temporary file, then rename). The file holds the content; the `notes` row
+  holds slug, path, timestamps, published flag, content hash and response
+  properties (`in_reply_to`, `like_of`, `repost_of`, `bookmark_of`,
+  `content_format`). Deletion is soft: the row gets `deleted_at` and the file
+  moves to `.trash/YYYY/MM/`, so Micropub `undelete` can restore it.
+- **Media**: `media/YYYY/MM/.` plus `_.`
+  variants, staged in `media/.tmp/` while being processed.
+- **Database**: `starpunk.db` (WAL mode): note metadata, tags, media records,
+  sessions, IndieAuth codes and tokens, webmentions and the outgoing queue,
+  syndications, WebSub subscriptions and queues, caches (author h-card, reply
+  contexts), the FTS5 index and `site_state`. See [database.md](database.md).
+- **Other files**: `logs/starpunk.log` (rotating), worker lock files,
+  `threads_token.json`, and `debug/` for failed uploads when
+  `DEBUG_SAVE_FAILED_UPLOADS=true`.
+
+The FTS index is maintained by `notes.py` (SQLite cannot read the note files)
+and rebuilt at start-up if it is empty.
+
+## Authentication model
+
+There is one user, the site owner, identified by the `ADMIN_ME` URL. Details
+are in [simplified-auth-architecture.md](simplified-auth-architecture.md).
+
+- **Admin login** uses OpenID Connect (authorization code with PKCE S256 and a
+  nonce) against a configured provider (Pocket ID in production). Only the
+  subject `OIDC_ADMIN_SUB` may log in. The ID token's signature (via JWKS),
+  issuer, audience and expiry are checked. Pending logins are kept in
+  `oidc_login_state`.
+- **Sessions**: a random token in the `starpunk_session` cookie (HttpOnly,
+  SameSite=Lax, Secure when `SITE_URL` is https), stored as a SHA-256 hash in
+  `sessions` and valid for `SESSION_LIFETIME` days. No passwords are stored.
+- **Micropub tokens**: StarPunk is its own IndieAuth authorization server. A
+  client sends the owner to `/auth/authorize`; the owner (logged in through
+  OIDC) approves; the client exchanges the code at `/auth/token` (PKCE
+  required). Codes and tokens are stored hashed. Tokens last
+  `INDIEAUTH_TOKEN_LIFETIME_DAYS` and can be revoked at `/auth/revoke` or in
+  `/admin/tokens`. Scopes: `create`, `update`, `delete`, `media`, `profile`.
+- **Development**: `DEV_MODE=true` adds `/dev/login`, which logs in as
+  `DEV_ADMIN_ME` without any checks. Never enabled in production; start-up
+  logs a warning when it is on.
+
+## Configuration
+
+All configuration comes from environment variables (optionally a `.env`
+file), read once at start-up by `starpunk/config.py`. Validation fails fast:
+`SESSION_SECRET` is always required; outside `DEV_MODE`, `ADMIN_ME` and the
+four `OIDC_*` settings are required too. Crosspost targets switch on when
+their credentials are set. The full list with defaults is in
+[deployment.md](deployment.md#configuration).
+
+## Caching
+
+- **Feed note list**: per process, refreshed after `FEED_CACHE_SECONDS` or as
+  soon as `site_state.content_version` changes. Every change to a public note
+  bumps that value in the database, so all gunicorn processes notice at once.
+- **Rendered feeds**: `feeds/cache.py`, an in-memory LRU cache with a TTL
+  (`FEED_CACHE_MAX_SIZE`, `FEED_CACHE_SECONDS`), keyed by a checksum of the
+  notes plus `content_version`. Responses carry `ETag` and
+  `Cache-Control: public, max-age=…`; conditional requests get `304`.
+- **Author h-card** (`author_profile`, 24 hours) and **reply contexts**
+  (`reply_contexts`) are cached in the database.
+- The webmention worker caches endpoint discovery results in memory.
+
+## Security posture
+
+- **Outbound requests (SSRF)**: fetches of URLs that come from outside
+  (webmention sources and targets, endpoint discovery, reply contexts, WebSub
+  callbacks, remote Micropub photos, IndieAuth client pages, crosspost link
+  cards) are checked first: every address the host resolves to must be public
+  (private, loopback, link-local, CGNAT, multicast and reserved ranges are
+  refused). The fetcher in `webmention_ssrf.py`, used for webmentions, reply
+  contexts, WebSub and remote Micropub photos, follows redirects by hand and
+  re-checks each hop, connects to the address it checked (no second DNS
+  lookup) and limits response size (1 MB by default) and total time.
+  Crosspost link cards use their own check that also re-checks each redirect.
+  The IndieAuth client-page fetch checks only the initial URL. `DEV_MODE`
+  relaxes the checks for local testing.
+- **HTML sanitising**: rendered notes (Markdown or HTML sent by a Micropub
+  client) and webmention content are cleaned with nh3 allow-lists; search
+  highlighting escapes everything except ``.
+- **Rate limits**: `/webmention` per client IP and per source domain
+  (defaults 60 and 10 per 60 seconds); `/websub` 30 requests per IP per
+  minute, plus limits on subscriptions in total, per callback host and per
+  callback address, and on requests waiting for verification. Request-rate
+  counters are in memory and per process.
+- **Client IP behind a proxy**: with `TRUSTED_PROXY=true` the first address in
+  `X-Forwarded-For` is used as the client IP for rate limiting. Set it only
+  when the app is reachable solely through a proxy that sets that header
+  (Caddy does); without it, every client shares the proxy's address.
+- **Auth**: hashed session and token storage, single-use login state, PKCE
+  for both OIDC and IndieAuth, redirect URIs checked against the client,
+  post-login redirects limited to this site. Admin form POSTs rely on the
+  SameSite=Lax session cookie (there are no per-form CSRF tokens).
+- **Uploads**: request bodies are capped at 50 MB; images are processed by
+  Pillow and stored under random (UUID) names.
+- **Container**: runs as a non-root user. HTTPS and security headers (HSTS,
+  CSP, X-Frame-Options and so on) come from the reverse proxy.
+
+## Observability
+
+- Logs go to stdout and `logs/starpunk.log` (10 MB × 10 files); each line
+  carries the request's correlation ID.
+- Metrics (`monitoring/`): HTTP request timings, database query timings
+  (with a slow-query threshold), memory, pool statistics and business
+  counters, in an in-memory buffer per process, shown at
+  `/admin/metrics-dashboard` and `/admin/metrics`.
+- `/health` reports status, version and webmention-worker statistics;
+  `/health?detailed=true` checks database, filesystem and disk space;
+  `/admin/health` adds metrics, pool statistics and system information.
+
 ---
-tags: indieweb, cms
----
-Note content here
-```
 
-**Backward Compatibility**: Parser checks for frontmatter, falls back to pure markdown.
-
-#### API Versioning
-```
-# V1 (current)
-GET /api/notes
-
-# V2 (future)
-GET /api/v2/notes  # New features
-GET /api/notes     # Still works, returns V1 response
-```
-
-### Data Export/Import
-
-#### Export Formats
-1. **Markdown Bundle**: Zip of all notes (already portable)
-2. **JSON Export**: Notes + metadata
-   ```json
-   {
-     "version": "1.0",
-     "exported_at": "2024-11-18T12:00:00Z",
-     "notes": [
-       {
-         "slug": "my-note",
-         "content": "Note content...",
-         "created_at": "2024-11-01T12:00:00Z",
-         "published": true
-       }
-     ]
-   }
-   ```
-3. **RSS Archive**: Existing feed.xml
-
-#### Import (V2)
-- From JSON export
-- From WordPress XML
-- From markdown directory
-- From other IndieWeb CMSs
-
-## Implementation Status (v0.9.5)
-
-### ✅ Fully Implemented Features
-
-1. **Note Management** (v0.3.0)
-   - Full CRUD operations (create, read, update, delete)
-   - Hybrid file+database storage with sync
-   - Soft and hard delete support
-   - Markdown rendering
-   - Slug generation with uniqueness
-
-2. **Authentication** (v0.8.0)
-   - IndieLogin.com OAuth 2.0 with PKCE
-   - Session management with token hashing
-   - CSRF protection with state tokens
-   - Development mode authentication bypass
-
-3. **Web Interface** (v0.5.2)
-   - Public site: homepage and note permalinks
-   - Admin dashboard with note management
-   - Login/logout flows
-   - Responsive design
-   - Microformats2 markup (h-entry, h-card, h-feed)
-
-4. **RSS Feed** (v0.6.0)
-   - RSS 2.0 compliant feed generation
-   - Auto-discovery links
-   - Server-side caching
-   - ETag support
-
-5. **Container Deployment** (v0.6.0)
-   - Multi-stage Containerfile
-   - Gunicorn WSGI server
-   - Health check endpoint
-   - Volume persistence
-
-6. **CI/CD Pipeline** (v0.9.5)
-   - Gitea Actions workflow
-   - Automated container builds
-   - Registry push
-
-7. **Database Migrations** (v0.9.0)
-   - Automatic migration system
-   - Fresh database detection
-   - Legacy database migration
-   - Migration tracking
-
-8. **Development Tools**
-   - uv package manager for Python
-   - Comprehensive test suite (87% coverage)
-   - Black code formatting
-   - Flake8 linting
-
-### ❌ Not Yet Implemented (Blocking V1)
-
-1. **Micropub Endpoint**
-   - POST /api/micropub for creating notes
-   - GET /api/micropub?q=config
-   - GET /api/micropub?q=source
-   - Token validation
-   - **Status**: Critical blocker for V1 release
-
-2. **IndieAuth Token Endpoint**
-   - Token issuance for Micropub clients
-   - **Alternative**: May use external IndieAuth server
-
-### ⚠️ Partially Implemented
-
-1. **Standards Validation**
-   - HTML5: Markup exists, not validated
-   - Microformats: Markup exists, not validated
-   - RSS: Validated and compliant
-   - Micropub: N/A (not implemented)
-
-2. **REST API** (Optional)
-   - JSON API for notes CRUD
-   - **Status**: Deferred to V2 (admin interface works without it)
-
-## Success Metrics
-
-The architecture is successful if it enables:
-
-1. **Fast Development**: < 1 week to implement V1 - ✅ **ACHIEVED** (~35 hours, 70% complete)
-2. **Easy Deployment**: < 5 minutes to get running - ✅ **ACHIEVED** (containerized)
-3. **Low Maintenance**: Runs for months without intervention - ✅ **ACHIEVED** (automated migrations)
-4. **High Performance**: All responses < 300ms - ✅ **ACHIEVED**
-5. **Data Ownership**: User has direct access to all content - ✅ **ACHIEVED** (file-based storage)
-6. **Standards Compliance**: Passes all validators - ⚠️ **PARTIAL** (RSS yes, others pending)
-7. **Extensibility**: Can add V2 features without rewrite - ✅ **ACHIEVED** (migration system ready)
-
-## References
-
-### Internal Documentation
-- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
-- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
-- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
-- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
-- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
-
-### External Standards
-- [IndieWeb](https://indieweb.org/)
-- [IndieAuth Spec](https://www.w3.org/TR/indieauth/)
-- [Micropub Spec](https://micropub.spec.indieweb.org/)
-- [Microformats2](http://microformats.org/wiki/h-entry)
-- [RSS 2.0](https://www.rssboard.org/rss-specification)
-- [Flask Documentation](https://flask.palletsprojects.com/)
+**Last Updated**: 2026-11-03 (v2.10.1)
diff --git a/docs/architecture/simplified-auth-architecture.md b/docs/architecture/simplified-auth-architecture.md
index 4d06728..0bac38f 100644
--- a/docs/architecture/simplified-auth-architecture.md
+++ b/docs/architecture/simplified-auth-architecture.md
@@ -1,428 +1,342 @@
-# StarPunk Simplified Authentication Architecture
+# Authentication and Authorization Architecture
+
+Current as of v2.10.1. Decision record: [ADR-064](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md),
+which supersedes the "no self-hosted IndieAuth" decisions
+([ADR-050](../decisions/ADR-050-remove-custom-indieauth-server.md),
+[ADR-056](../decisions/ADR-056-no-selfhosted-indieauth.md)) and the external
+token verification of ADR-030 / ADR-036.
+
+> The filename is historical: it described the v1.x "external provider only"
+> design. Other documents link to it, so it is kept.
 
 ## Overview
 
-After removing the custom IndieAuth authorization server, StarPunk becomes a pure Micropub server that relies on external providers for all authentication and authorization.
+StarPunk is a single-user site with two kinds of client and two auth
+mechanisms:
 
-## Architecture Diagrams
+| Who | Mechanism | Credential | Code |
+|---|---|---|---|
+| The site owner in a browser (admin UI, consent screen) | OpenID Connect login against an external provider (e.g. Pocket ID) | `starpunk_session` cookie, backed by a hashed row in `sessions` | `starpunk/auth.py`, `starpunk/routes/auth.py` |
+| Micropub apps (Quill, Indigenous, ...) | StarPunk's own IndieAuth authorization server | Bearer access token, backed by a hashed row in `indieauth_tokens` | `starpunk/indieauth.py`, `starpunk/routes/indieauth.py` |
+
+The two are chained: a Micropub app is approved on a consent screen that
+requires an admin session, so every token ultimately rests on the OIDC
+login. StarPunk stores no passwords.
 
-### Before: Complex Mixed-Mode Architecture
 ```
-┌──────────────────────────────────────────────────────────────┐
-│                     StarPunk Instance                         │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                   Web Interface                         │   │
-│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
-│  │  │ Admin Login │  │ Authorization │  │ Token Issuer │  │   │
-│  │  └─────────────┘  └──────────────┘  └──────────────┘  │   │
-│  └────────────────────────────────────────────────────────┘   │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                    Auth Module                          │   │
-│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │   │
-│  │  │ Sessions │ │   PKCE   │ │  Tokens  │ │   Codes  │ │   │
-│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │   │
-│  └────────────────────────────────────────────────────────┘   │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                     Database                            │   │
-│  │  ┌────────┐ ┌──────────────────┐ ┌─────────────────┐  │   │
-│  │  │ Users  │ │ authorization_codes│ │     tokens     │  │   │
-│  │  └────────┘ └──────────────────┘ └─────────────────┘  │   │
-│  └────────────────────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────────────────┘
+ Browser (owner)                    StarPunk                         OIDC provider
+ ───────────────                    ────────                         ─────────────
+ POST /auth/login ─────────────▶ initiate_login()  ── redirect ──▶  authorize (PKCE, nonce)
+                                                                     owner authenticates
+ GET /auth/callback?code&state ◀────────────────────── redirect ───┘
+                                 handle_callback(): code exchange, ID token checks,
+                                 sub == OIDC_ADMIN_SUB → create_session(ADMIN_ME)
+ ◀── Set-Cookie: starpunk_session
 
-Problems:
-- 500+ lines of security-critical code
-- Dual role: authorization server AND resource server
-- Complex token lifecycle management
-- Database bloat with token storage
-- Maintenance burden for security updates
+ Micropub app                       StarPunk
+ ────────────                       ────────
+ discovers indieauth-metadata / authorization_endpoint / token_endpoint
+ GET /auth/authorize?... ────────▶ validate request → (OIDC login if no session) → consent page
+ owner approves ─────────────────▶ POST /auth/authorize/approve → redirect: code, state, iss
+ POST /auth/token (code, verifier) ▶ access token (hash stored in indieauth_tokens)
+ POST /micropub, /micropub/media ─▶ verify_access_token() + scope check
 ```
 
-### After: Clean Separation of Concerns
-```
-┌──────────────────────────────────────────────────────────────┐
-│                     StarPunk Instance                         │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                   Web Interface                         │   │
-│  │  ┌─────────────┐                    ┌──────────────┐   │   │
-│  │  │ Admin Login │                    │   Micropub   │   │   │
-│  │  └─────────────┘                    └──────────────┘   │   │
-│  └────────────────────────────────────────────────────────┘   │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                    Auth Module                          │   │
-│  │  ┌──────────────┐            ┌──────────────────────┐  │   │
-│  │  │   Sessions   │            │  Token Verification  │  │   │
-│  │  │ (Admin Only) │            │  (External Provider) │  │   │
-│  │  └──────────────┘            └──────────────────────┘  │   │
-│  └────────────────────────────────────────────────────────┘   │
-│                                                                │
-│  ┌────────────────────────────────────────────────────────┐   │
-│  │                     Database                            │   │
-│  │  ┌────────┐ ┌──────────┐ ┌─────────┐                   │   │
-│  │  │ Users  │ │auth_state│ │  posts  │  (No token tables)│   │
-│  │  └────────┘ └──────────┘ └─────────┘                   │   │
-│  └────────────────────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────────────────┘
-                              │
-                              │ API Calls
-                              ▼
-┌──────────────────────────────────────────────────────────────┐
-│              External IndieAuth Providers                     │
-│  ┌─────────────────────┐      ┌─────────────────────────┐    │
-│  │  indieauth.com      │      │ tokens.indieauth.com    │    │
-│  │  (Authorization)    │      │ (Token Verification)    │    │
-│  └─────────────────────┘      └─────────────────────────┘    │
-└──────────────────────────────────────────────────────────────┘
+## 1. Admin login (OIDC)
 
-Benefits:
-- 500+ lines of code removed
-- Clear single responsibility
-- No security burden
-- Minimal database footprint
-- Zero maintenance for auth code
-```
+### Flow
 
-## Authentication Flows
+1. `GET /auth/login` shows `templates/admin/login.html`, or redirects to the
+   dashboard if the session cookie is already valid.
+2. `POST /auth/login` calls `auth.initiate_login(next)`:
+   - Fetches `{OIDC_ISSUER}/.well-known/openid-configuration` (cached for an
+     hour per process). The document's `issuer` must equal `OIDC_ISSUER`, and
+     it must name `authorization_endpoint`, `token_endpoint` and `jwks_uri`.
+   - Generates `state`, `nonce` and a PKCE `code_verifier`, and stores them in
+     `oidc_login_state` with the sanitized `next` URL (same site only) and a
+     10-minute expiry.
+   - Redirects to the provider with `response_type=code`, `scope=openid` and
+     `code_challenge_method=S256`.
+3. `GET /auth/callback`:
+   - A provider `error` parameter, or a missing `code`/`state`, flashes an
+     error and returns to the login page.
+   - The `state` row is fetched and deleted in one step: it is single use and
+     must not have expired.
+   - If the provider sent `iss` (RFC 9207), it must match the issuer.
+   - The code is exchanged at the token endpoint along with the
+     `code_verifier`. StarPunk authenticates as a confidential client (HTTP
+     Basic, `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET`).
+   - The ID token is verified with PyJWT against the provider's JWKS. The
+     checks are: the signature (algorithms from the provider metadata, never
+     `none`), `iss`, `aud` equal to the client id, `exp`, required `iat` and
+     `sub`, a 60 s leeway, and a `nonce` equal to the stored one.
+   - `sub` must equal `OIDC_ADMIN_SUB` (constant-time comparison). Any other
+     account gets "Not authorized as admin".
+   - A session is created for `ADMIN_ME`, the owner's identity URL. It is also
+     the `me` of every issued token. The author h-card is refreshed from
+     `ADMIN_ME` on a best-effort basis that never blocks login (see
+     [ADR-061](../decisions/ADR-061-author-discovery.md)).
 
-### Flow 1: Admin Authentication (Unchanged)
-```
-Admin User                    StarPunk                    IndieLogin.com
-    │                            │                              │
-    ├──── GET /admin/login ───→  │                              │
-    │                            │                              │
-    │ ←── Login Form ───────────  │                              │
-    │                            │                              │
-    ├──── POST /auth/login ───→  │                              │
-    │      (me=admin.com)        │                              │
-    │                            ├──── Redirect ──────────────→ │
-    │                            │    (client_id=starpunk.com)  │
-    │ ←──────────── Authorization Request ─────────────────────  │
-    │                            │                              │
-    ├───────────── Authenticate with IndieLogin ──────────────→ │
-    │                            │                              │
-    │                            │ ←── Callback ────────────────│
-    │                            │    (me=admin.com)           │
-    │                            │                              │
-    │ ←── Session Cookie ───────  │                              │
-    │                            │                              │
-    │      Admin Access           │                              │
-```
+### Sessions
 
-### Flow 2: Micropub Client Authentication (Simplified)
-```
-Micropub Client              StarPunk              External Token Endpoint
-      │                         │                           │
-      ├─── POST /micropub ───→  │                           │
-      │   Bearer: token123      │                           │
-      │                         ├──── GET /token ─────────→ │
-      │                         │   Bearer: token123        │
-      │                         │                           │
-      │                         │ ←── Token Info ──────────│
-      │                         │   {me, scope, client_id}  │
-      │                         │                           │
-      │                         │ [Validate me==ADMIN_ME]   │
-      │                         │ [Check scope includes     │
-      │                         │  "create"]                │
-      │                         │                           │
-      │ ←── 201 Created ────────│                           │
-      │    Location: /post/123  │                           │
-```
+- `create_session(me)` makes a random 32-byte URL-safe token. Only its
+  SHA-256 hash is stored in `sessions`, with `me`, `expires_at`
+  (`SESSION_LIFETIME` days, default 30), the user agent and the IP. Expired
+  sessions and login states are cleaned up each time a session is created.
+- Cookie `starpunk_session`: `HttpOnly`, `SameSite=Lax`, `Secure` when
+  `SITE_URL` is https, `max-age` equal to the session lifetime.
+- `verify_session(token)` looks up the hash, checks expiry and updates
+  `last_used_at`.
+- `@require_auth` protects `/admin/*`. Without a valid session it remembers
+  the URL and redirects to `/auth/login`. It sets `g.user` and `g.me`.
+- A `before_request` hook also resolves the session on public pages that
+  carry the cookie, so the header can show "Admin" instead of "Log in".
+- `POST /auth/logout` deletes the session row and the cookie.
 
-## Component Responsibilities
+### Configuration
 
-### StarPunk Components
+Outside `DEV_MODE`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`,
+`OIDC_ADMIN_SUB` and `ADMIN_ME` are required, and startup fails without them.
+The provider must have `{SITE_URL}/auth/callback` registered as a redirect
+URI.
 
-#### 1. Admin Authentication (`/auth/*`)
-**Responsibility**: Manage admin sessions via IndieLogin.com
-**Does**:
-- Initiate OAuth flow with IndieLogin.com
-- Validate callback and create session
-- Manage session lifecycle
+### Development mode
 
-**Does NOT**:
-- Issue tokens
-- Store passwords
-- Manage user identities
+With `DEV_MODE=true` (and `DEV_ADMIN_ME`), `/dev/login` creates a session
+without OIDC. The blueprint is registered only in dev mode, and its
+`before_request` guard returns 404 if `DEV_MODE` is off. Every page shows a
+warning banner while it is on. Never enable it in production.
 
-#### 2. Micropub Endpoint (`/micropub`)
-**Responsibility**: Accept and process Micropub requests
-**Does**:
-- Extract Bearer tokens from requests
-- Verify tokens with external endpoint
-- Create/update/delete posts
-- Return proper Micropub responses
+## 2. Built-in IndieAuth authorization server
 
-**Does NOT**:
-- Issue tokens
-- Manage authorization codes
-- Store token data
+StarPunk issues tokens for exactly one identity, `ADMIN_ME`. It implements
+the authorization code flow of the current IndieAuth spec
+(https://indieauth.spec.indieweb.org/), with PKCE required.
 
-#### 3. Token Verification Module
-**Responsibility**: Validate tokens with external providers
-**Does**:
-- Call external token endpoint
-- Cache valid tokens (5 min TTL)
-- Validate scope and identity
+### Endpoints
 
-**Does NOT**:
-- Generate tokens
-- Store tokens permanently
-- Manage token lifecycle
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/.well-known/oauth-authorization-server` | Server metadata (the target of `rel=indieauth-metadata`) |
+| GET | `/auth/authorize` | Validate the request; show the consent screen (admin session required) |
+| POST | `/auth/authorize/approve` | Consent decision from the screen |
+| POST | `/auth/authorize` | Profile-only code redemption, returns `{"me": ...}` |
+| POST | `/auth/token` | Exchange a code for an access token; also legacy `action=revoke` |
+| GET | `/auth/token` | Legacy token verification (Bearer token → `me`, `client_id`, `scope`) |
+| POST | `/auth/revoke` | RFC 7009 revocation (always 200) |
 
-### External Provider Responsibilities
+All JSON responses carry `Cache-Control: no-store`. Errors use the OAuth
+form `{"error", "error_description"}`.
 
-#### indieauth.com
-- User authentication
-- Authorization consent
-- Authorization code generation
-- Profile discovery
+### Metadata
 
-#### tokens.indieauth.com
-- Token issuance
-- Token verification
-- Token revocation
-- Scope management
-
-## Configuration
-
-### Required Settings
-```ini
-# Identity of the admin user
-ADMIN_ME=https://your-domain.com
-
-# External token endpoint for verification
-TOKEN_ENDPOINT=https://tokens.indieauth.com/token
-
-# Admin session secret (existing)
-SECRET_KEY=your-secret-key
-```
-
-### HTML Discovery
-```html
-
-
-
-
-```
-
-## Security Model
-
-### Trust Boundaries
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Trusted Zone                              │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │               StarPunk Application                    │   │
-│  │  - Session management                                 │   │
-│  │  - Post creation/management                          │   │
-│  │  - Admin interface                                   │   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                  Token Verification API
-                            │
-┌─────────────────────────────────────────────────────────────┐
-│                  Semi-Trusted Zone                           │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │           External IndieAuth Providers                │   │
-│  │  - Token validation                                   │   │
-│  │  - Identity verification                             │   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                     User Authentication
-                            │
-┌─────────────────────────────────────────────────────────────┐
-│                    Untrusted Zone                            │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │              Micropub Clients                         │   │
-│  │  - Must provide valid Bearer tokens                   │   │
-│  │  - Tokens verified on every request                   │   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Security Benefits of Simplified Architecture
-
-1. **Reduced Attack Surface**
-   - No token generation = no cryptographic mistakes
-   - No token storage = no database leaks
-   - No PKCE = no implementation errors
-
-2. **Specialized Security**
-   - Auth providers focus solely on security
-   - Regular updates from specialized teams
-   - Community-vetted implementations
-
-3. **Clear Boundaries**
-   - StarPunk only verifies, never issues
-   - Single source of truth (external provider)
-   - No confused deputy problems
-
-## Performance Characteristics
-
-### Token Verification Performance
-```
-Without Cache:
-┌──────────┐     200-500ms      ┌─────────────┐
-│ Micropub ├───────────────────→│Token Endpoint│
-└──────────┘                     └─────────────┘
-
-With Cache (95% hit rate):
-┌──────────┐       <1ms          ┌─────────────┐
-│ Micropub ├───────────────────→│ Memory Cache │
-└──────────┘                     └─────────────┘
-```
-
-### Cache Strategy
-```python
-Cache Key: SHA256(token)
-Cache Value: {
-    'me': 'https://user.com',
-    'client_id': 'https://client.com',
-    'scope': 'create update delete',
-    'expires_at': timestamp + 300  # 5 minutes
+```json
+{
+  "issuer": "/",
+  "authorization_endpoint": "/auth/authorize",
+  "token_endpoint": "/auth/token",
+  "revocation_endpoint": "/auth/revoke",
+  "revocation_endpoint_auth_methods_supported": ["none"],
+  "scopes_supported": ["create", "update", "delete", "media", "profile"],
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code"],
+  "code_challenge_methods_supported": ["S256"],
+  "authorization_response_iss_parameter_supported": true
 }
 ```
 
-### Expected Latencies
-- First request: 200-500ms (external API)
-- Cached request: <1ms
-- Admin login: 1-2s (OAuth flow)
-- Post creation: <50ms (after auth)
+StarPunk has no introspection or userinfo endpoint. Only StarPunk itself
+checks its tokens.
 
-## Migration Impact
+### Authorization request validation (`validate_authorization_request`)
 
-### Breaking Changes
-1. **All existing tokens invalid**
-   - Users must re-authenticate
-   - No migration path for tokens
+- `client_id` must be an http(s) URL without a fragment.
+- `redirect_uri` must be present and have no fragment. It must either share
+  the `client_id`'s scheme, host and port, or be published by the client. To
+  check the second case, StarPunk fetches the `client_id` URL (5 s timeout,
+  with an SSRF check on the URL unless `DEV_MODE` is on). It reads
+  `redirect_uris` from a JSON client metadata document, or
+  `rel="redirect_uri"` from the `Link` header and from ``/``
+  elements.
+- Problems with `client_id` or `redirect_uri` are shown to the user on an
+  error page (HTTP 400). They are never redirected, because the redirect
+  target can't be trusted.
+- Other problems are redirected to the client with `error`,
+  `error_description`, `state` and `iss`. These are: a `response_type` other
+  than `code` (`unsupported_response_type`), a missing `state`, a missing
+  `code_challenge`, or a `code_challenge_method` other than `S256`.
+- `scope` is split on spaces. Requested scopes are not filtered against
+  `scopes_supported`.
 
-2. **Endpoint removal**
-   - `/auth/authorization` → 404
-   - `/auth/token` → 404
+### Consent screen
 
-3. **Configuration required**
-   - Must set `ADMIN_ME`
-   - Must configure domain with IndieAuth links
+If `GET /auth/authorize` gets a valid request but there is no admin session,
+StarPunk stores the request URL and redirects to the OIDC login, which
+returns to that URL afterwards. With a session, it renders
+`templates/admin/authorize.html`. The page shows the client id, the identity
+the client will act as, the redirect URI, and one checkbox per requested
+scope (all checked). A request without scopes is described as "only wants to
+confirm your identity".
 
-### Non-Breaking Preserved Functionality
-1. **Admin login unchanged**
-   - Same URL (`/admin/login`)
-   - Same provider (IndieLogin.com)
-   - Sessions preserved
+`POST /auth/authorize/approve` checks the session again and re-validates the
+request from hidden form fields. "Deny" redirects with
+`error=access_denied`. "Approve" grants only the scopes that were both
+requested and left checked, issues a code, and redirects with `code`,
+`state` and `iss`.
 
-2. **Micropub API unchanged**
-   - Same endpoint (`/micropub`)
-   - Same request format
-   - Same response format
+### Codes and tokens
 
-## Comparison with Other Systems
+| | Authorization code | Access token |
+|---|---|---|
+| Table | `indieauth_codes` | `indieauth_tokens` |
+| Value | 32 random bytes, URL-safe | 32 random bytes, URL-safe |
+| Stored as | SHA-256 hash | SHA-256 hash |
+| Lifetime | 10 minutes | `INDIEAUTH_TOKEN_LIFETIME_DAYS` (default 90) |
+| Bound to | `client_id`, `redirect_uri`, `scope`, `code_challenge` | `client_id`, `scope` |
 
-### WordPress + IndieAuth Plugin
-- **Similarity**: External provider for auth
-- **Difference**: WP has user management, we don't
+`redeem_authorization_code` handles redemption for both `POST /auth/token`
+and `POST /auth/authorize`:
 
-### Known IndieWeb Sites
-- **micro.blog**: Custom auth server (complex)
-- **Indigenous**: Client only, uses external auth
-- **StarPunk**: Micropub server only (simple)
+1. `code` and `code_verifier` are required.
+2. An atomic `UPDATE ... SET used_at = now WHERE code_hash = ? AND used_at IS
+   NULL AND expires_at > now` makes the code single-use, even across
+   gunicorn workers.
+3. `client_id` and `redirect_uri` must match the code exactly.
+4. `BASE64URL(SHA256(code_verifier))` must equal the stored challenge
+   (constant-time comparison).
 
-### Architecture Philosophy
-```
-"Do one thing well"
-       │
-       ├── StarPunk: Publish notes
-       ├── IndieAuth.com: Authenticate users
-       └── Tokens.indieauth.com: Manage tokens
+The token endpoint accepts only `grant_type=authorization_code`. It refuses
+a code issued with no scope (`invalid_grant`), because such codes are for
+the profile-only flow at the authorization endpoint. The response is
+`{access_token, token_type: "Bearer", scope, me, expires_in}`. There are no
+refresh tokens: a client re-authorizes when its token expires.
+
+Expired codes are deleted whenever a new code is issued.
+
+### Verification and revocation
+
+- `verify_access_token(token)` hashes the token and accepts it if it is
+  neither revoked nor expired, then updates `last_used_at`. It returns
+  `{me: ADMIN_ME, client_id, scope}`.
+- `check_scope(required, scope)` matches whole words in the space-separated
+  scope string.
+- Revocation sets `revoked_at`. It can happen by token value, through
+  `POST /auth/revoke` or the legacy `POST /auth/token` with `action=revoke`
+  (unknown tokens are ignored, per RFC 7009). It can also happen by id, from
+  the admin page.
+- `/admin/tokens` ("Connected Apps") lists active tokens with their client,
+  scope, dates and last use. Each has a Revoke button.
+
+### Scopes
+
+| Scope | Allows |
+|---|---|
+| `create` | Micropub create (published or draft), media upload, `q=source`, `q=category` |
+| `draft` | Micropub create, always saved as a draft (v2.9.0); `q=source`, `q=category` |
+| `update` | Micropub update; `q=source`, `q=category` |
+| `delete` | Micropub delete and undelete; `q=source`, `q=category` |
+| `media` | Media endpoint uploads |
+| `profile` | Nothing beyond identity (there is no profile or userinfo endpoint) |
+
+`q=config` and `q=syndicate-to` work with any valid token.
+
+## 3. Token use at the Micropub and media endpoints
+
+`routes/micropub.py` handles `GET/POST /micropub` and
+`POST /micropub/media`. The old `POST /media` path is kept for existing
+clients.
+
+### Extracting the token (`micropub.extract_bearer_token`)
+
+- The token comes from `Authorization: Bearer `, with the scheme
+  matched case-insensitively (RFC 7235).
+- Or it comes from `access_token` in the form body (POST) or the query
+  string (GET).
+- A token in both places gets **400 `invalid_request`** (RFC 6750 §2,
+  v2.9.0).
+- No token gets **401 `unauthorized`**, "No access token provided".
+- An unknown, expired or revoked token gets **401 `unauthorized`**,
+  "Invalid or expired access token".
+
+Every 401 carries `WWW-Authenticate: Bearer realm="micropub"`. When a token
+was sent but isn't valid, `error="invalid_token"` is added (RFC 6750 §3,
+v2.9.0).
+
+### Scope rules
+
+| Operation | Required scope | Notes |
+|---|---|---|
+| create | `create` or `draft` | With only `draft`, the post is saved unpublished whatever `post-status` says |
+| update | `update` | |
+| delete / undelete | `delete` | |
+| `q=source`, `q=category` | any of `create`, `update`, `delete`, `draft` | These show drafts and tags (v2.9.0) |
+| `q=config`, `q=syndicate-to` | any valid token | |
+| media upload | `media` or `create` | `create` is accepted for older clients |
+
+A missing scope gets **403 `insufficient_scope`** (RFC 6750). The Micropub
+Recommendation's error table lists 401 for this case. StarPunk keeps 403 on
+purpose (see the [v2.9.0 review](../design/v2.9.0/2026-11-03-micropub-review.md),
+"Kept as is").
+
+Micropub request handling itself is described in
+[indieweb-protocols.md](indieweb-protocols.md#micropub).
+
+## 4. Discovery
+
+`templates/base.html` puts these links on every page, whether or not
+`WEBMENTION_ENABLED` is set (v2.8.0):
+
+```html
+
+
+
+
+
+
 ```
 
-## Future Considerations
+Micropub clients start from the URL the user types, which is normally
+`ADMIN_ME`. If `ADMIN_ME` is the StarPunk site itself, the links above are
+enough. If it is another page, that page must advertise StarPunk's
+`indieauth-metadata` (or `authorization_endpoint` and `token_endpoint`) and
+`micropub` links. Otherwise clients won't find StarPunk
+([ADR-064](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md) §3).
 
-### Potential V2 Enhancements (NOT for V1)
-1. **Multi-user support**
-   - Would require user management
-   - Still use external auth
+## 5. Data (migration 011)
 
-2. **Multiple token endpoints**
-   - Support different providers per user
-   - Endpoint discovery from user domain
+| Table | Purpose | Key columns |
+|---|---|---|
+| `sessions` | Admin browser sessions | `session_token_hash`, `me`, `expires_at`, `last_used_at`, `user_agent`, `ip_address` |
+| `oidc_login_state` | One pending OIDC login | `state` (PK), `nonce`, `code_verifier`, `next_url`, `expires_at` |
+| `indieauth_codes` | Authorization codes | `code_hash`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, `expires_at`, `used_at` |
+| `indieauth_tokens` | Access tokens | `token_hash`, `client_id`, `scope`, `expires_at`, `last_used_at`, `revoked_at` |
 
-3. **Token caching layer**
-   - Redis for distributed caching
-   - Longer TTL with refresh
+The legacy v1 tables `auth_state`, `tokens` and `authorization_codes` are
+not used (see the migration's header comment).
 
-### Explicitly NOT Implementing
-1. **Custom authorization server**
-   - Violates simplicity principle
-   - Maintenance burden
+## 6. Security properties and known gaps
 
-2. **Password authentication**
-   - Not IndieWeb compliant
-   - Security burden
+In place:
 
-3. **JWT validation**
-   - Not part of IndieAuth spec
-   - Unnecessary complexity
+- No secrets at rest: session tokens, codes and access tokens are stored only
+  as SHA-256 hashes.
+- OIDC: PKCE S256, a nonce, single-use expiring state, issuer checks (in the
+  metadata and the RFC 9207 `iss`), full ID-token validation, and a single
+  allowed `sub`.
+- IndieAuth: PKCE S256 required, single-use 10-minute codes bound to the
+  client and redirect URI, `iss` in every authorization response, and
+  untrusted redirect URIs never followed.
+- Post-login redirects are limited to this site.
 
-## Testing Strategy
+Known gaps:
 
-### Unit Tests
-```python
-# Test external verification
-@patch('httpx.get')
-def test_token_verification(mock_get):
-    # Mock successful response
-    mock_get.return_value.status_code = 200
-    mock_get.return_value.json.return_value = {
-        'me': 'https://example.com',
-        'scope': 'create'
-    }
-
-    result = verify_token('test-token')
-    assert result is not None
-```
-
-### Integration Tests
-```python
-# Test with real endpoint (in CI)
-def test_real_token_verification():
-    # Use test token from tokens.indieauth.com
-    token = get_test_token()
-    result = verify_token(token)
-    assert result['me'] == TEST_USER
-```
-
-### Manual Testing
-1. Configure domain with IndieAuth links
-2. Use Quill or Indigenous
-3. Create test post
-4. Verify token caching
-
-## Metrics for Success
-
-### Quantitative Metrics
-- **Code removed**: >500 lines
-- **Database tables removed**: 2
-- **Complexity reduction**: ~40%
-- **Test coverage maintained**: >90%
-- **Performance**: <500ms token verification
-
-### Qualitative Metrics
-- **Clarity**: Clear separation of concerns
-- **Maintainability**: No auth code to maintain
-- **Security**: Specialized providers
-- **Flexibility**: User choice of providers
-- **Simplicity**: Focus on core functionality
-
----
-
-**Document Version**: 1.0
-**Created**: 2025-11-24
-**Author**: StarPunk Architecture Team
-**Purpose**: Document simplified authentication architecture after IndieAuth server removal
\ No newline at end of file
+- Admin forms and the consent form have no CSRF token. They rely on the
+  `SameSite=Lax` session cookie, which cross-site POSTs don't carry.
+- The client metadata fetch checks the `client_id` URL against private
+  addresses, but then makes a plain `httpx.get` that follows redirects.
+  Redirect hops are not re-checked and the connection is not pinned, unlike
+  `webmention_ssrf.safe_get`.
+- `scopes_supported` leaves out `draft`, although Micropub honours it and
+  the consent screen grants it when requested. Unknown scopes are also shown
+  and granted as requested; they just have no effect.
+- No token introspection endpoint and no refresh tokens.
diff --git a/docs/architecture/syndication-architecture.md b/docs/architecture/syndication-architecture.md
index cb61ca4..6c0f17f 100644
--- a/docs/architecture/syndication-architecture.md
+++ b/docs/architecture/syndication-architecture.md
@@ -1,233 +1,255 @@
-# Syndication Architecture
+# Syndication (POSSE) Architecture
 
-## Overview
-StarPunk's syndication architecture provides multiple feed formats for content distribution, ensuring broad compatibility with feed readers and IndieWeb tools while maintaining simplicity.
+Current as of v2.10.1. Code: `starpunk/syndication.py`.
 
-## Current State (v1.1.0)
-```
-┌─────────────┐
-│   Database  │
-│   (Notes)   │
-└──────┬──────┘
-       │
-┌──────▼──────┐
-│  feed.py    │
-│  (RSS 2.0)  │
-└──────┬──────┘
-       │
-┌──────▼──────┐
-│ /feed.xml   │
-│  endpoint   │
-└─────────────┘
-```
+StarPunk publishes on its own site first and then copies each note to other
+networks (POSSE: Publish on your Own Site, Syndicate Elsewhere). Later
+edits, unpublishing and deletes follow the copies.
 
-## Target Architecture (v1.1.2+)
-```
-┌─────────────┐
-│   Database  │
-│   (Notes)   │
-└──────┬──────┘
-       │
-┌──────▼──────────────────┐
-│   Feed Generation Layer  │
-├──────────┬───────────────┤
-│  feed.py │  json_feed.py │
-│  RSS/ATOM│     JSON      │
-└──────────┴───────────────┘
-       │
-┌──────▼──────────────────┐
-│      Feed Endpoints     │
-├─────────┬───────────────┤
-│/feed.xml│  /feed.atom   │
-│  (RSS)  │    (ATOM)     │
-├─────────┼───────────────┤
-│     /feed.json          │
-│    (JSON Feed)          │
-└─────────────────────────┘
-```
+> Feeds (RSS, Atom, JSON Feed, OPML) and WebSub are pull and push
+> distribution of the site itself, not crossposting. They are described in
+> [indieweb-protocols.md](indieweb-protocols.md#feeds). This document
+> covered feeds before v2.1.0.
 
-## Design Principles
+Decisions: [ADR-065](../decisions/ADR-065-direct-syndication-posse.md)
+(GoToSocial, queue model), [ADR-066](../decisions/ADR-066-bluesky-syndication.md)
+(Bluesky), [ADR-068](../decisions/ADR-068-likes-and-reposts.md) (likes and
+reposts), [ADR-069](../decisions/ADR-069-threads-syndication.md) (Threads),
+[ADR-070](../decisions/ADR-070-crosspost-links-and-cards.md) (links and link
+cards), and the [v2.9.0 Micropub review](../design/v2.9.0/2026-11-03-micropub-review.md)
+(bookmarks, `mp-syndicate-to` default).
 
-### 1. Format Independence
-Each syndication format operates independently:
-- No shared state between formats
-- Failures in one don't affect others
-- Can be enabled/disabled individually
+## Targets
 
-### 2. Shared Data Access
-All formats read from the same data source:
-- Single query pattern for notes
-- Consistent ordering (newest first)
-- Same publication status filtering
+A target exists when its credentials are configured. `get_targets()` builds
+the list from config on each call and caches one client object per target
+in the process.
 
-### 3. Library Leverage
-Maximize use of existing libraries:
-- `feedgen` for RSS and ATOM
-- Native Python `json` for JSON Feed
-- No custom XML generation
+| Target id | Client | Enabled by | Micropub `uid` | Text limit | Images | Edits follow? |
+|---|---|---|---|---|---|---|
+| `gotosocial` | `MastodonClient` (any Mastodon-API server) | `GOTOSOCIAL_URL` + `GOTOSOCIAL_ACCESS_TOKEN` | `GOTOSOCIAL_URL/` | `GOTOSOCIAL_MAX_CHARS` (5000) | `GOTOSOCIAL_MAX_MEDIA` (4) | Yes |
+| `bluesky` | `BlueskyClient` (AT Protocol, app password) | `BLUESKY_HANDLE` + `BLUESKY_APP_PASSWORD` (`BLUESKY_SERVICE`, default `https://bsky.social`) | `https://bsky.app/profile/` | `BLUESKY_MAX_CHARS` (300) | 4 | No |
+| `threads` | `ThreadsClient` (Meta Graph API) | `THREADS_ACCESS_TOKEN` (`THREADS_USERNAME` for links) | `https://www.threads.com/@` | `THREADS_MAX_CHARS` (500) | `THREADS_MAX_MEDIA` (4) | No |
 
-## Component Design
+Display names come from `GOTOSOCIAL_NAME`, `BLUESKY_NAME` and
+`THREADS_NAME`. GoToSocial statuses use `GOTOSOCIAL_VISIBILITY` (default
+`public`). The GoToSocial token needs `write:statuses` and `write:media`,
+plus `read:search` and `write:favourites` for likes and boosts.
 
-### Feed Generation Module (`feed.py`)
-**Current Responsibility**: RSS 2.0 generation
-**Future Enhancement**: Add ATOM generation function
+Bluesky and Threads can't edit posts through their APIs. Once a copy exists
+there, edits to the note don't change it, but unpublish and delete still
+remove it.
 
-```python
-# Pseudocode structure
-def generate_rss_feed(notes, config) -> str
-def generate_atom_feed(notes, config) -> str  # New
-```
+## Choosing targets
 
-### JSON Feed Module (`json_feed.py`)
-**New Component**: Dedicated JSON Feed generation
+`select_targets(note_id, target_ids)` records which targets a note goes to.
+Every configured target not in the list is disabled; if it already has a
+copy, that copy is deleted. Targets the note never went to get no row.
 
-```python
-# Pseudocode structure
-def generate_json_feed(notes, config) -> str
-def format_json_item(note) -> dict
-```
+| Origin | Targets |
+|---|---|
+| Admin editor, new note | One checkbox per target, all checked by default |
+| Admin editor, edit | Checkboxes reflect the targets currently enabled; saving applies the selection |
+| Micropub create | Only the targets in `mp-syndicate-to` (form field, `mp-syndicate-to[]`, or inside JSON `properties`). Values may be a target's `uid` (trailing slash ignored) or its id. **No `mp-syndicate-to` means no crossposting** (v2.9.0; before, all targets) |
+| Micropub update / delete | Target selection is unchanged; the change follows existing copies |
 
-### Route Handlers
-Simple pass-through to generation functions:
-```python
-@app.route('/feed.xml')  # Existing
-@app.route('/feed.atom') # New
-@app.route('/feed.json') # New
-```
+Micropub clients learn the targets from `q=syndicate-to` and `q=config`
+(`[{"uid", "name"}]`). Selecting targets for a draft records them; nothing
+is sent until the note is published.
 
-## Data Flow
+## Data: the `syndications` table (migration 012)
 
-1. **Request**: Client requests feed at endpoint
-2. **Query**: Fetch published notes from database
-3. **Transform**: Convert notes to format-specific structure
-4. **Serialize**: Generate final output (XML/JSON)
-5. **Response**: Return with appropriate Content-Type
+One row per (note, target), unique on `(note_id, target)`:
 
-## Microformats2 Architecture
+| Column | Meaning |
+|---|---|
+| `enabled` | Whether the note should have a copy on this target |
+| `remote_id`, `remote_url` | The copy: status id, `at://` URI, Threads media id, or a `favourite:` / `reblog:` marker for native likes and boosts |
+| `state` | `pending`, `synced` or `failed` |
+| `version` | Incremented on every change that needs a reconcile |
+| `attempts`, `last_error`, `next_attempt_at` | Retry bookkeeping |
+| `claimed_until` | Lease held by the worker processing the row |
 
-### Template Layer Enhancement
-Microformats2 operates at the HTML template layer:
+`note_id` deliberately has no foreign key, so the row outlives a hard
+delete and the worker can still remove the copy.
+
+## Change hooks
+
+| Event | Call | Effect |
+|---|---|---|
+| Admin create/edit | `select_targets()` | Rows set to `pending`, version bumped |
+| Micropub create | `select_targets(resolve_targets(mp-syndicate-to))` | After photos are attached |
+| `update_note()` (admin or Micropub, including publish/unpublish) | `note_changed(id)` | Every row of the note set to `pending`, version bumped, attempts reset |
+| Micropub photo changes | `note_changed(id)` | Same |
+| `delete_note()` (soft or hard), `undelete_note()` | `note_changed(id)` | Same |
+| Retry button on the edit page | `retry(id)` | That row set to `pending` now, attempts reset |
+
+## Worker
+
+`SyndicationWorker` is a daemon thread started in every gunicorn process
+when at least one target is configured (not under `TESTING`). It runs
+`process_due()` every `SYNDICATION_POLL_INTERVAL` seconds (default 10), and
+loops again immediately while there is work.
+
+`process_due()`:
+
+1. Calls each client's `maintain()` (the Threads token refresh).
+2. Selects up to 5 rows that are `pending`, due, and not claimed.
+3. Claims each row with an atomic
+   `UPDATE ... SET claimed_until = now + 5 min WHERE state = 'pending' AND
+   (claimed_until IS NULL OR claimed_until < now)`. The other processes skip
+   it. Unlike the Webmention and WebSub workers, there is no file lock: the
+   row claim is the only coordination.
+4. Reconciles the row (below), then records the result.
+
+### Reconcile
 
 ```
-┌──────────────┐
-│  Data Model  │
-│   (Notes)    │
-└──────┬───────┘
-       │
-┌──────▼───────┐
-│  Templates   │
-│  + mf2 markup│
-└──────┬───────┘
-       │
-┌──────▼───────┐
-│  HTML Output │
-│  (Semantic)  │
-└──────────────┘
+note published and row enabled?
+  no  → remote copy exists? delete it            → (None, None)
+  yes → copy exists and target can't edit?        → keep it as is
+        copy exists                                → update (if it's gone remotely: create again)
+        no copy                                    → create
 ```
 
-### Markup Strategy
-- **Progressive Enhancement**: Add classes without changing structure
-- **CSS Independence**: Use mf2-specific classes, not styling classes
-- **Validation First**: Test with parsers during development
+Deleted notes are not found by `get_note()`, so they count as "not
+published".
 
-## Configuration Requirements
+### Versions
 
-### New Configuration Variables
-```ini
-# Author information for h-card
-AUTHOR_NAME = "Site Author"
-AUTHOR_URL = "https://example.com"
-AUTHOR_PHOTO = "/static/avatar.jpg"  # Optional
+The row's `version` is read when the row is picked up. `_finish()` sets
+`state = 'synced'` only if the version is unchanged. If the note was edited
+while the send was in flight, the row stays `pending` and is reconciled
+again with the new content. `_fail()` does the same.
 
-# Feed settings
-FEED_LIMIT = 50
-FEED_FORMATS = "rss,atom,json"  # Comma-separated
-```
+### Retries and idempotency
 
-## Performance Considerations
+- `SyndicationError(permanent=True)` fails the row immediately. This covers
+  HTTP 4xx other than 429, a missing target, images too large for Bluesky,
+  a Threads container in `ERROR`/`EXPIRED`, and Graph API auth/permission
+  errors (codes 10, 190, 200).
+- Other errors retry after `min(30 s × 2^attempts, 6 h)`. After 8 attempts
+  the row becomes `failed`. The error is shown on the edit page with a
+  Retry button.
+- `RemoteGone` (404, or Graph error 100/33) during an update means the copy
+  was deleted remotely, so a new one is created. During a delete it counts as
+  success.
+- Duplicate posts after a lost response are prevented as follows:
+  - GoToSocial: an `Idempotency-Key: starpunk--` header.
+  - Bluesky and Threads: on a retry (`attempts > 0`), the last 25 posts are
+    searched for one containing the permalink (for Threads reposts, the
+    reposted URL). A match is adopted instead of posting again.
+- Threads' publish step sometimes fails transiently ("Fatal"); it is
+  retried unless the error is an auth error.
 
-### Caching Strategy
-- Feed generation is read-heavy, write-light
-- Consider caching generated feeds (5-minute TTL)
-- Invalidate cache on note creation/update
+## Composing posts
 
-### Resource Usage
-- RSS/ATOM: ~O(n) memory for n notes
-- JSON Feed: Similar memory profile
-- Microformats2: No additional server resources
+`Post` carries the note, permalink, tags, the target's character limit,
+media files, and for likes, reposts and bookmarks, the URL they point at and
+its fetched title (from the reply-context cache).
 
-## Security Considerations
+### Text
 
-### Content Sanitization
-- HTML in feeds must be properly escaped
-- CDATA wrapping for RSS/ATOM
-- JSON string encoding for JSON Feed
-- No script injection vectors
+`compose_text()` builds: body, a blank line, the permalink, a blank line,
+the hashtags. If that is too long, the body is cut at a word boundary with
+"…"; the permalink always survives. Hashtags (`#` plus the tag's display
+name without non-word characters) may take at most a third of the limit. A
+bookmark's body starts with `🔖 ` (v2.9.0). A photo-only
+note starts with the permalink.
 
-### Rate Limiting
-- Apply same limits as HTML endpoints
-- Consider aggressive caching for feeds
-- Monitor for feed polling abuse
+| Target | Body format | Links | Hashtags |
+|---|---|---|---|
+| GoToSocial | The note's Markdown, sent with `content_type: text/markdown`; embedded images removed from the text (sent as attachments) | As written | In the text |
+| Bluesky | Plain text from the rendered Markdown | Markdown link text becomes a clickable link facet; bare URLs and `#tags` get link/tag facets (UTF-8 byte offsets) | In the text, as tag facets |
+| Threads | Plain text | Markdown links are written `text (url)`, up to 4 different URLs plus the permalink (Threads allows 5); the length counts non-ASCII characters as UTF-8 bytes | None in the text; the first usable tag becomes the post's `topic_tag` |
 
-## Testing Architecture
+### Link cards (ADR-070)
 
-### Unit Tests
-```
-tests/
-├── test_feed.py          # Enhanced for ATOM
-├── test_json_feed.py     # New test module
-└── test_microformats.py  # Template parsing tests
-```
+- **Bluesky**: if the note has images, they are the embed. Otherwise, if
+  the note links somewhere, StarPunk builds an `app.bsky.embed.external`
+  card for the first link. `page_card()` fetches the page (at most 512 KB,
+  every redirect hop checked against private addresses, 10 s per request,
+  5 redirects) and reads the Open Graph, Twitter or HTML title, description
+  and image. The image (at most 5 MB) is shrunk under 1 MB and uploaded as
+  the thumbnail. If the page can't be fetched, the card has just the URL.
+  A note without links gets a card for its own permalink, built from the
+  note without fetching anything.
+- **Threads**: no explicit `link_attachment` (Meta rejects one for a page
+  it hasn't crawled yet). Threads previews the first link in the text by
+  itself.
+- **GoToSocial**: the server makes its own previews.
 
-### Integration Tests
-- Validate against external validators
-- Test feed reader compatibility
-- Verify IndieWeb tool parsing
+### Media
 
-## Backwards Compatibility
+`_media_files()` collects the note's attached photos first, then images
+embedded in the note text that are in this site's media library (some
+Micropub clients put uploaded photos in the content). It stops at the
+target's image limit. The `large` variant is used when one exists. Alt text
+comes from the caption, or from the embedded image's alt.
 
-### URL Structure
-- `/feed.xml` remains RSS 2.0 (no breaking change)
-- New endpoints are additive only
-- Auto-discovery links updated in templates
+| Target | Handling |
+|---|---|
+| GoToSocial | Uploaded via `POST /api/v2/media` with description; re-uploaded on each edit |
+| Bluesky | `uploadBlob`; images over 1,000,000 bytes are re-encoded as JPEG at decreasing size and quality, and fail permanently if they still don't fit. Aspect ratio is sent |
+| Threads | Meta fetches each image from its public `/media/` URL. Only JPEG and PNG up to 8 MB are used; others are left off. 1 image → `IMAGE` container, 2 or more → `CAROUSEL` of child containers. Alt text up to 1000 characters |
 
-### Database
-- No schema changes required
-- All features use existing Note model
-- No migration needed
+Only notes of kind `note` carry media; likes, reposts and bookmarks don't.
 
-## Future Extensibility
+### Likes, reposts and bookmarks
 
-### Potential Enhancements
-1. Content negotiation on `/feed`
-2. WebSub (PubSubHubbub) support
-3. Custom feed filtering (by tag, date)
-4. Feed pagination for large sites
+| Kind | GoToSocial | Bluesky | Threads |
+|---|---|---|---|
+| Like of a post on that network | Native favourite (`favourite:`) | Native `app.bsky.feed.like` | Not crossposted (the API can't like) |
+| Like of anything else | Not crossposted | Not crossposted | Not crossposted |
+| Repost without comment, of a post on that network | Native boost (`reblog:`) | Native `app.bsky.feed.repost` | Not native: posts `🔁 title` + URL |
+| Repost with comment, of a post on that network | Status: comment, `🔁 title`, URL | Quote post (`app.bsky.embed.record`) | Comment, `🔁 title`, URL |
+| Repost of another page | Status: (comment,) `🔁 title`, URL | Post with an external card for the URL | (Comment,) `🔁 title`, URL |
+| Bookmark | Ordinary status starting `🔖 ` | Ordinary post starting `🔖 ` | Ordinary post starting `🔖 ` |
 
-### Format Support Matrix
-| Format | v1.1.0 | v1.1.2 | v1.2.0 |
-|--------|--------|--------|--------|
-| RSS 2.0 | ✅ | ✅ | ✅ |
-| ATOM | ❌ | ✅ | ✅ |
-| JSON Feed | ❌ | ✅ | ✅ |
-| Microformats2 | Partial | Partial | ✅ |
+"On that network" is decided by the client. GoToSocial resolves the URL
+through `/api/v2/search?resolve=true`. Bluesky matches
+`https://bsky.app/profile//post/` and resolves it to a URI and
+CID. Native likes and boosts have no URL of their own and nothing to edit.
+Deleting the note undoes them (`unfavourite` / `unreblog`, or deleting the
+like or repost record). A like that isn't crossposted is recorded as synced
+with no remote copy.
 
-## Decision Rationale
+## u-syndication
 
-### Why Multiple Formats?
-1. **No Universal Standard**: Different ecosystems prefer different formats
-2. **Low Maintenance**: Feed formats are stable, rarely change
-3. **User Choice**: Let users pick their preferred format
-4. **IndieWeb Philosophy**: Embrace plurality and interoperability
+`templates/note.html` lists every row that has a `remote_url` as "Also on
+", using ``. Micropub
+`q=source` returns the same URLs as the `syndication` property. The
+Webmention worker rejects a webmention whose source is one of the note's
+own copies (e.g. backfed by Bridgy), so a copy is never shown as a response
+to itself (v2.8.0).
 
-### Why This Architecture?
-1. **Simplicity**: Each component has single responsibility
-2. **Testability**: Isolated components are easier to test
-3. **Maintainability**: Changes to one format don't affect others
-4. **Performance**: Can optimize each format independently
+## Client sessions and tokens
 
-## References
-- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
-- [ATOM RFC 4287](https://tools.ietf.org/html/rfc4287)
-- [JSON Feed Specification](https://www.jsonfeed.org/)
-- [Microformats2](https://microformats.org/wiki/microformats2)
\ No newline at end of file
+- **Bluesky**: `createSession` with the app password, then
+  `refreshSession` when the access JWT expires (a 401 or `ExpiredToken`
+  triggers one re-login and retry). The PDS endpoint is taken from the DID
+  document. Calls are serialized per client with a lock.
+- **Threads**: long-lived tokens expire after 60 days. `maintain()` tries a
+  refresh (`refresh_access_token`, `th_refresh_token`) at most once a day.
+  The current token is kept in `DATA_PATH/threads_token.json` (mode 0600,
+  written atomically), together with a SHA-256 "seed" of the configured
+  token. A different `THREADS_ACCESS_TOKEN` in the config therefore
+  replaces the saved one. An exclusive `flock` on `threads_token.lock` makes
+  one gunicorn process refresh while the others pick up its result. A failed
+  refresh is retried an hour later (network error) or the next day (HTTP
+  error, e.g. a token less than a day old). The httpx logger is raised to
+  WARNING because Threads takes the token in the URL, and errors never echo
+  the URL.
+- **GoToSocial**: a static bearer token.
+
+## Known limits
+
+- Bluesky and Threads copies don't follow edits (platform limitation).
+  Unticking and re-ticking a target makes a new copy.
+- Link-card and Threads image fetches check every redirect hop against
+  private addresses but don't pin DNS, and use a per-request rather than an
+  overall time limit. Webmention and WebSub fetching use the stricter
+  `webmention_ssrf` fetcher.
+- No per-target choice for Micropub updates: `mp-syndicate-to` is read only
+  on create.
+- Likes of ordinary web pages, and all likes on Threads, stay on the site.
diff --git a/docs/architecture/technology-stack-legacy.md b/docs/architecture/technology-stack-legacy.md
index f62886c..100562a 100644
--- a/docs/architecture/technology-stack-legacy.md
+++ b/docs/architecture/technology-stack-legacy.md
@@ -1,5 +1,10 @@
 # StarPunk Technology Stack - Quick Reference
 
+> **Historical document.** This describes StarPunk's original v0.x technology
+> choices (for example IndieLogin.com for admin login) and is kept for
+> context only. It does not describe the current system; see
+> [technology-stack.md](technology-stack.md) and [overview.md](overview.md).
+
 ## Project Understanding
 
 StarPunk is a **minimal, single-user IndieWeb CMS** for publishing notes with RSS syndication. The core philosophy is radical simplicity: "Every line of code must justify its existence."
diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md
index bb58207..41b0f42 100644
--- a/docs/architecture/technology-stack.md
+++ b/docs/architecture/technology-stack.md
@@ -1,1082 +1,119 @@
 # StarPunk Technology Stack
 
-## Project Summary
-
-StarPunk is a minimal, single-user IndieWeb CMS for publishing notes with RSS syndication. The project emphasizes radical simplicity, standards compliance, and user data ownership. Every technology choice is driven by the principle: "Every line of code must justify its existence. When in doubt, leave it out."
-
-### Core Requirements
-- Publish IndieWeb-compatible notes (https://indieweb.org/note)
-- IndieAuth authentication using external provider (indielogin.com)
-- Micropub server endpoint for publishing from any client
-- RSS feed generation for syndication
-- File-based note storage for maximum portability
-- SQLite for metadata and structured data
-- Self-hostable single-user system
-- API-first architecture
-- Markdown support
-
-## Complete Technology Stack
-
-### Backend Stack
-
-#### Web Framework: Flask 3.0+
-**Purpose**: HTTP server, routing, templating
-**Justification**:
-- Minimal micro-framework (< 1000 lines core code)
-- Perfect for single-user applications
-- Native support for both JSON APIs and HTML rendering
-- Mature, stable, well-documented (13+ years)
-- Built-in Jinja2 templating for server-side rendering
-- Standard WSGI interface for deployment flexibility
-
-**Alternatives Rejected**:
-- FastAPI: Async complexity unnecessary for single-user CMS
-- Django: Massive framework with ORM, admin, multi-user features we don't need
-- Bottle: Too minimal, smaller ecosystem
-
-**Reference**: ADR-001
-
-#### Python Version: 3.11+
-**Purpose**: Programming language
-**Justification**:
-- User's preferred language
-- Excellent standard library (sqlite3, hashlib, secrets, etc.)
-- Rich ecosystem for web development
-- Strong typing support (type hints)
-- Mature dependency management (pip, venv)
-
-#### Data Persistence: Hybrid File + Database
-
-##### Note Storage: Markdown Files on Disk
-**Purpose**: Store note content
-**Format**: Plain markdown files (.md)
-**Structure**:
-```
-data/notes/
-├── 2024/
-│   ├── 11/
-│   │   ├── my-first-note.md
-│   │   └── another-note.md
-│   └── 12/
-│       └── december-note.md
-└── 2025/
-    └── 01/
-        └── new-year-note.md
-```
-
-**Naming Convention**: `{slug}.md`
-**Organization**: Year/Month subdirectories (`YYYY/MM/`)
-**File Format**: Pure markdown, no frontmatter
-
-**Justification**:
-- Maximum portability (user requirement)
-- Human-readable, editable in any text editor
-- Easy backup (cp, rsync, git)
-- User owns data directly
-- No vendor lock-in
-- Future-proof format
-
-**Reference**: ADR-004
-
-##### Metadata Storage: SQLite
-**Purpose**: Store note metadata, sessions, tokens
-**Database**: `data/starpunk.db`
-
-**Schema**:
-```sql
--- Note metadata (NOT content)
-CREATE TABLE notes (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    slug TEXT UNIQUE NOT NULL,
-    file_path TEXT UNIQUE NOT NULL,
-    published BOOLEAN DEFAULT 0,
-    created_at TIMESTAMP NOT NULL,
-    updated_at TIMESTAMP NOT NULL,
-    content_hash TEXT
-);
-
--- Authentication sessions (IndieLogin)
-CREATE TABLE sessions (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    session_token TEXT UNIQUE NOT NULL,
-    me TEXT NOT NULL,
-    created_at TIMESTAMP NOT NULL,
-    expires_at TIMESTAMP NOT NULL,
-    last_used_at TIMESTAMP
-);
-
--- Micropub access tokens
-CREATE TABLE tokens (
-    token TEXT PRIMARY KEY,
-    me TEXT NOT NULL,
-    client_id TEXT,
-    scope TEXT,
-    created_at TIMESTAMP NOT NULL,
-    expires_at TIMESTAMP
-);
-
--- CSRF state tokens
-CREATE TABLE auth_state (
-    state TEXT PRIMARY KEY,
-    created_at TIMESTAMP NOT NULL,
-    expires_at TIMESTAMP NOT NULL
-);
-```
-
-**Justification**:
-- Single file, perfect for single-user
-- No separate server process
-- Excellent for read-heavy workloads (blog)
-- Fast indexing and querying
-- Built into Python standard library
-- Enables efficient metadata queries without parsing files
-- Atomic transactions for data integrity
-
-**Hybrid Strategy**: Files are authoritative for content; database is authoritative for metadata. This gives us portability AND performance.
-
-**Reference**: ADR-004
-
-#### Core Dependencies
-
-##### markdown (3.5+)
-**Purpose**: Convert markdown to HTML
-**Usage**: Render note content for display and RSS feed
-**Justification**:
-- Pure Python, standard markdown implementation
-- Simple API: `markdown.markdown(text)`
-- Sufficient performance for single-user system
-- More standard than alternatives (mistune)
-
-##### feedgen (1.0+)
-**Purpose**: Generate RSS 2.0 feeds
-**Usage**: Create valid RSS feed from published notes
-**Justification**:
-- High-level API ensures RSS 2.0 compliance
-- Handles date formatting (RFC-822) automatically
-- CDATA wrapping for HTML content
-- Better than manual XML generation (error-prone)
-
-##### httpx (0.27+)
-**Purpose**: HTTP client library
-**Usage**:
-- Communication with indielogin.com API
-- Verify Micropub client metadata
-- Fetch remote URLs for verification
-**Justification**:
-- Modern, clean API
-- Synchronous and async support
-- Better than requests (async capability) and urllib (too low-level)
-- Proper timeout handling
-- SSL verification built-in
-
-##### python-dotenv (1.0+)
-**Purpose**: Environment configuration
-**Usage**: Load settings from `.env` file
-**Justification**:
-- Industry standard for configuration
-- Keeps secrets out of code
-- Simple API: `load_dotenv()`
-- Minimal overhead
-
-##### pytest (8.0+)
-**Purpose**: Testing framework
-**Usage**: Unit and integration tests
-**Justification**:
-- Current Python testing standard
-- Minimal boilerplate
-- Clear assertions
-- Built-in fixtures
-- Better than unittest (verbose) and nose2 (unmaintained)
-
-**Reference**: ADR-002
-
-#### Dependencies Explicitly REJECTED
-
-- **Flask-SQLAlchemy**: ORM abstraction unnecessary, adds complexity
-- **Flask-Login**: Session-based auth, we need token-based for Micropub
-- **Flask-CORS**: Single decorator, don't need full extension (5 lines of code)
-- **Flask-WTF**: Form library overkill for simple note creation
-- **Flask-Limiter**: Rate limiting deferred to V2 or reverse proxy
-
-**Decision**: Use Python standard library and explicit code instead of extensions where possible. Each dependency must justify its existence.
-
-**Reference**: ADR-002
-
-### Frontend Stack
-
-#### Template Engine: Jinja2
-**Purpose**: Server-side HTML rendering
-**Included With**: Flask (no additional dependency)
-**Usage**:
-- Public interface (homepage, note permalinks)
-- Admin interface (dashboard, note editor)
-- Microformats markup (h-entry, h-card)
-
-**Justification**:
-- Zero build process
-- Server-side rendering for better performance
-- Works without JavaScript (progressive enhancement)
-- Easy microformats implementation
-- Familiar syntax
-- Stable and mature
-
-**Reference**: ADR-003
-
-#### CSS: Custom Stylesheet
-**Purpose**: Visual styling
-**Approach**: Single custom CSS file, no framework
-**File**: `static/css/style.css`
-**Size**: ~200 lines for entire site
-
-**Features**:
-- CSS custom properties (variables) for theming
-- Mobile-first responsive design
-- Simple media queries for tablet/desktop
-- Semantic HTML5 + minimal classes
-
-**Justification**:
-- No framework overhead (Bootstrap, Tailwind, etc.)
-- No build tools required
-- Full control over appearance
-- Minimal single theme fits project scope
-- Faster than loading framework CSS
-
-**Example**:
-```css
-:root {
-  --color-text: #333;
-  --color-bg: #fff;
-  --max-width: 42rem;
-  --spacing: 1rem;
-}
-```
-
-**Frameworks Rejected**:
-- Tailwind: Requires build process, utility-first doesn't fit
-- Bootstrap/Bulma: Too many unused features
-- PicoCSS: Good but custom CSS gives more control
-
-**Reference**: ADR-003
-
-#### JavaScript: Minimal Vanilla JS
-**Purpose**: Markdown preview in admin (optional enhancement)
-**Approach**: Single vanilla JavaScript file, no framework
-**File**: `static/js/preview.js`
-**Dependency**: marked.js via CDN (client-side markdown)
-
-**Usage**:
-- Optional real-time markdown preview in note editor
-- Progressive enhancement (works without JS)
-
-**Justification**:
-- Core functionality works without JavaScript
-- Single optional feature doesn't justify framework
-- Vanilla JS sufficient for simple preview
-- Modern browser APIs (fetch, DOM manipulation) are enough
-- No build tools required
-
-**Frameworks Rejected**:
-- React/Vue/Svelte: Massive overkill for one preview feature
-- htmx: Interesting but not needed for V1
-- Alpine.js: Too much for minimal JS needs
-
-**Reference**: ADR-003
-
-#### Build Tools: NONE
-**Decision**: No build process whatsoever
-**Justification**:
-- Server-side rendering eliminates need for bundling
-- Custom CSS served directly
-- Vanilla JS served directly
-- Modern browsers support ES6+ natively
-- Zero npm dependencies
-- Instant development setup
-
-**This means**:
-- No webpack, Vite, Rollup, esbuild
-- No Babel transpilation
-- No PostCSS processing
-- No minification (premature optimization)
-- No asset pipeline
-
-**Reference**: ADR-003
-
-### Authentication Stack
-
-#### Admin Authentication: IndieLogin.com
-**Purpose**: Authenticate the admin user via their personal website
-**Provider**: External service at https://indielogin.com
-**API**: https://indielogin.com/api
-**Protocol**: OAuth 2.0 / IndieAuth
-
-**Flow**:
-1. User enters their website URL
-2. StarPunk redirects to indielogin.com with state token
-3. indielogin.com verifies user's identity (RelMeAuth, email, etc.)
-4. indielogin.com redirects back with authorization code
-5. StarPunk exchanges code for verified identity
-6. StarPunk creates session cookie
-
-**Session Management**:
-- HttpOnly, Secure cookies
-- 30-day expiry
-- Stored in SQLite sessions table
-- CSRF protection via state tokens
-
-**Configuration**:
-```bash
-ADMIN_ME=https://your-website.com  # Only this URL can authenticate
-SESSION_SECRET=random-secret-key
-```
-
-**Justification**:
-- Extremely simple (< 100 lines of code)
-- No authentication code to maintain
-- No password management needed
-- True IndieWeb authentication (user owns identity)
-- Secure by default (delegated to trusted service)
-- Community-maintained, stable service
-
-**Alternatives Rejected**:
-- Self-hosted IndieAuth: Too complex for V1
-- Password auth: Not IndieWeb-compatible, security burden
-- OAuth (GitHub/Google): User doesn't own identity
-
-**Reference**: ADR-005
-
-#### Micropub Authentication: IndieAuth Tokens
-**Purpose**: Authenticate Micropub API clients
-**Protocol**: IndieAuth bearer tokens
-**Flow**: Standard IndieAuth authorization code grant
-**Storage**: Tokens table in SQLite
-
-**Note**: Micropub token endpoint is separate from admin authentication. Users authenticate their Micropub clients (e.g., mobile apps) separately via IndieAuth flow. This will be detailed in a future ADR for Micropub implementation.
-
-### Development Tools
-
-#### Code Quality
-```
-pytest-cov       # Test coverage reporting
-black            # Code formatting (standard: 88 char line length)
-flake8           # Linting
-mypy             # Type checking (optional but recommended)
-```
-
-**Justification**:
-- Automated formatting prevents style debates
-- Linting catches common errors
-- Test coverage ensures quality
-- Type hints improve maintainability
-
-#### Development Workflow
-```bash
-# Setup
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-
-# Run
-flask run
-
-# Test
-pytest
-
-# Format
-black .
-flake8 .
-```
-
-**No additional tools required**: No npm, no build scripts, no containers (optional for deployment).
-
-### Deployment Stack
-
-#### WSGI Server: Gunicorn (Production)
-**Purpose**: Production HTTP server
-**Justification**:
-- Standard Python WSGI server
-- Production-ready
-- Better performance than Flask dev server
-- Simple configuration
-
-**Alternative**: uWSGI (more complex, not needed for single-user)
-
-#### Reverse Proxy: Nginx or Caddy (Recommended)
-**Purpose**: HTTPS termination, static file serving
-**Justification**:
-- Handle SSL/TLS certificates
-- Serve static files efficiently
-- Rate limiting (optional)
-- Proven deployment pattern
-
-#### Process Manager: systemd (Recommended)
-**Purpose**: Keep application running
-**Justification**:
-- Standard on modern Linux
-- Auto-restart on failure
-- Log management
-
-#### Deployment Package: Single Unit
-**Structure**:
-```
-starpunk/
-├── app.py                  # Main application
-├── requirements.txt        # Dependencies
-├── .env.example            # Configuration template
-├── static/                 # CSS, JS
-├── templates/              # Jinja2 templates
-├── data/                   # Notes + SQLite (persistent)
-│   ├── notes/
-│   └── starpunk.db
-└── README.md              # Setup instructions
-```
-
-**Deployment**:
-- Clone repository
-- Create virtual environment
-- Install dependencies
-- Configure .env file
-- Run with Gunicorn + systemd
-- (Optional) Nginx for HTTPS
-
-**Justification**: Single self-contained package, easy to deploy and backup.
-
-## File Organization
-
-### Project Structure
-```
-starpunk/
-├── app.py                       # Main Flask application
-├── requirements.txt             # Python dependencies
-├── .env                         # Environment configuration (gitignored)
-├── .env.example                 # Configuration template
-├── README.md                    # Setup documentation
-├── CLAUDE.MD                    # Project requirements
-│
-├── starpunk/                    # Application package
-│   ├── __init__.py
-│   ├── config.py                # Configuration loading
-│   ├── database.py              # SQLite operations
-│   ├── models.py                # Data models
-│   ├── auth.py                  # Authentication logic
-│   ├── micropub.py              # Micropub endpoint
-│   ├── feed.py                  # RSS generation
-│   └── utils.py                 # Helper functions
-│
-├── static/                      # Static assets
-│   ├── css/
-│   │   └── style.css           # Single stylesheet
-│   └── js/
-│       └── preview.js          # Optional markdown preview
-│
-├── templates/                   # Jinja2 templates
-│   ├── base.html               # Base layout
-│   ├── index.html              # Homepage (note list)
-│   ├── note.html               # Single note
-│   ├── feed.xml                # RSS template
-│   └── admin/
-│       ├── base.html           # Admin layout
-│       ├── login.html          # Login form
-│       ├── dashboard.html      # Admin dashboard
-│       ├── new.html            # Create note
-│       └── edit.html           # Edit note
-│
-├── data/                        # Persistent data (gitignored)
-│   ├── notes/                  # Markdown files
-│   │   └── YYYY/MM/
-│   │       └── slug.md
-│   └── starpunk.db             # SQLite database
-│
-├── tests/                       # Test suite
-│   ├── test_auth.py
-│   ├── test_database.py
-│   ├── test_micropub.py
-│   ├── test_feed.py
-│   └── test_notes.py
-│
-└── docs/                        # Architecture documentation
-    ├── architecture/
-    │   ├── overview.md
-    │   ├── components.md
-    │   ├── data-flow.md
-    │   ├── security.md
-    │   └── technology-stack.md
-    └── decisions/
-        ├── ADR-001-python-web-framework.md
-        ├── ADR-002-flask-extensions.md
-        ├── ADR-003-frontend-technology.md
-        ├── ADR-004-file-based-note-storage.md
-        └── ADR-005-indielogin-authentication.md
-```
-
-## Architecture Patterns
-
-### API-First Design
-**Pattern**: All functionality exposed via API, web interface consumes API
-**Routes**:
-```
-# Public API
-GET  /api/notes              # List published notes
-GET  /api/notes/{slug}       # Get single note
-GET  /feed.xml               # RSS feed
-
-# Admin API (session auth)
-POST   /api/notes            # Create note
-PUT    /api/notes/{id}       # Update note
-DELETE /api/notes/{id}       # Delete note
-
-# Micropub API (token auth)
-POST /api/micropub           # Create via Micropub
-GET  /api/micropub?q=config  # Query config
-
-# Auth API
-GET  /admin/login            # Login form
-POST /admin/login            # Initiate IndieLogin
-GET  /auth/callback          # IndieLogin callback
-POST /admin/logout           # Logout
-```
-
-### Data Flow: File + Database Sync
-
-#### Creating a Note
-```
-User submits note
-  ↓
-Generate slug
-  ↓
-Create file: data/notes/YYYY/MM/{slug}.md
-  ↓
-Calculate content hash
-  ↓
-Insert database record (slug, file_path, hash, timestamps)
-  ↓
-If database insert fails: delete file, return error
-  ↓
-Return success
-```
-
-#### Reading a Note
-```
-Request note by slug
-  ↓
-Query database for file_path
-  ↓
-Read markdown from file
-  ↓
-Render to HTML (if needed)
-  ↓
-Return content + metadata
-```
-
-#### Updating a Note
-```
-User submits changes
-  ↓
-Atomic write: new content to temp file
-  ↓
-Calculate new hash
-  ↓
-Update database (timestamp, hash)
-  ↓
-If database update succeeds: atomic rename temp → actual
-  ↓
-If database update fails: delete temp, return error
-  ↓
-Return success
-```
-
-**Benefits**:
-- Files provide portability
-- Database provides fast queries
-- Content hash detects external changes
-- Atomic operations prevent corruption
-
-**Reference**: ADR-004
-
-### IndieLogin Authentication Flow
-
-```
-┌─────────┐                ┌──────────┐              ┌─────────────┐
-│ User    │                │ StarPunk │              │ IndieLogin  │
-└────┬────┘                └────┬─────┘              └──────┬──────┘
-     │                          │                           │
-     │  1. Click "Login"        │                           │
-     ├─────────────────────────>│                           │
-     │                          │                           │
-     │  2. Enter website URL    │                           │
-     ├─────────────────────────>│                           │
-     │                          │                           │
-     │                     3. Generate state token          │
-     │                          │                           │
-     │  4. Redirect to IndieLogin with:                     │
-     │     - me=user_website                                │
-     │     - client_id=starpunk_url                         │
-     │     - redirect_uri=starpunk/callback                 │
-     │     - state=random_token                             │
-     │                          ├──────────────────────────>│
-     │                          │                           │
-     │                          │    5. Verify user's       │
-     │                          │       identity            │
-     │  <────────────────────────────────────────────────── │
-     │    (User authenticates via                           │
-     │     chosen method)                                   │
-     │  ──────────────────────────────────────────────────> │
-     │                          │                           │
-     │  6. Redirect back with code + state                  │
-     │  <──────────────────────────────────────────────────│
-     ├─────────────────────────>│                           │
-     │                          │                           │
-     │                     7. Verify state                  │
-     │                          │                           │
-     │                     8. POST to IndieLogin:           │
-     │                        - code                        │
-     │                        - client_id                   │
-     │                        - redirect_uri                │
-     │                          ├──────────────────────────>│
-     │                          │                           │
-     │                          │   9. Return verified "me" │
-     │                          │<──────────────────────────│
-     │                          │                           │
-     │                    10. Verify me == ADMIN_ME         │
-     │                          │                           │
-     │                    11. Create session                │
-     │                          │                           │
-     │  12. Set session cookie  │                           │
-     │  <───────────────────────│                           │
-     │                          │                           │
-     │  13. Redirect to admin   │                           │
-     │  <───────────────────────│                           │
-     │                          │                           │
-```
-
-**Security Features**:
-- State token prevents CSRF
-- Session tokens are cryptographically random
-- HttpOnly cookies prevent XSS
-- Only ADMIN_ME URL can authenticate
-- Sessions expire after 30 days
-
-**Reference**: ADR-005
-
-### Progressive Enhancement Pattern
-
-**Principle**: Core functionality works without JavaScript
-
-#### Public Interface
-- **Without JS**: Full functionality (view notes, RSS feed)
-- **With JS**: No difference (no JS used on public pages)
-
-#### Admin Interface
-- **Without JS**:
-  - Create/edit notes via HTML forms
-  - Submit to server, server renders markdown
-  - Full page refresh on submit
-- **With JS**:
-  - Real-time markdown preview
-  - No page refresh for preview
-  - Still submits via form (progressive enhancement)
-
-**Implementation**:
-```html
-
-
- - -
- - - -``` - -**Reference**: ADR-003 - -## Standards Compliance - -### IndieWeb Standards - -#### Microformats2 -**Required Classes**: -- `h-entry`: Mark up notes -- `h-card`: Mark up author information -- `e-content`: Note content -- `dt-published`: Publication timestamp -- `u-url`: Permalink URL - -**Example**: -```html -
-``` - -**Validation**: https://indiewebify.me/ - -#### IndieAuth -**Compliance**: OAuth 2.0 authorization code flow -**Endpoints**: Delegated to indielogin.com -**Token Format**: Bearer tokens -**Validation**: Token introspection - -**Reference**: https://www.w3.org/TR/indieauth/ - -#### Micropub -**Compliance**: Full Micropub spec support -**Content Types**: JSON and form-encoded -**Required Responses**: 201 Created with Location header -**Query Support**: q=config, q=source - -**Validation**: https://micropub.rocks/ - -**Reference**: https://micropub.spec.indieweb.org/ - -### Web Standards - -#### RSS 2.0 -**Compliance**: Valid RSS 2.0 XML -**Required Elements**: title, link, description, pubDate, guid -**Date Format**: RFC-822 -**HTML Content**: CDATA-wrapped - -**Validation**: https://validator.w3.org/feed/ - -#### HTTP -**Status Codes**: Proper use of 200, 201, 400, 401, 404, 500 -**Headers**: Content-Type, Cache-Control, Location -**Methods**: GET, POST, PUT, DELETE -**CORS**: Allow cross-origin for API endpoints - -#### HTML5 -**Compliance**: Valid semantic HTML -**Accessibility**: ARIA labels, alt text, proper heading hierarchy -**Responsive**: Viewport meta tag, mobile-first CSS -**Forms**: Proper labels, validation attributes - -**Validation**: https://validator.w3.org/ - -## Security Architecture - -### Authentication Security -- State tokens for CSRF protection (5-minute expiry) -- Session tokens are cryptographically random (32 bytes) -- HttpOnly cookies prevent XSS theft -- Secure flag requires HTTPS -- SameSite=Lax prevents CSRF -- Single admin user (ADMIN_ME verification) - -### Input Validation -- Validate all user input -- Sanitize markdown (prevent XSS in rendered HTML) -- Validate Micropub payloads against spec -- URL validation for IndieAuth -- File path validation (prevent directory traversal) - -### Database Security -- Parameterized queries (prevent SQL injection) -- Input sanitization before storage -- Hash session tokens before storage -- Content hashing for integrity - -### Network Security -- HTTPS required in production -- SSL certificate verification on httpx requests -- Secure headers (CSP, X-Frame-Options, etc.) -- Rate limiting via reverse proxy (nginx/Caddy) - -### File System Security -- Atomic file operations -- Restricted permissions on data/ directory -- Prevent directory traversal attacks -- Validate file paths before operations - -## Performance Targets - -### Response Times -- API responses: < 100ms -- Page loads: < 200ms -- RSS feed: < 300ms - -### Optimization Strategy -- SQLite indexes on frequently queried columns -- Cache RSS feed (5 minutes) -- Minimal dependencies = fast startup -- Server-side rendering = fast first paint -- Single CSS file = one request -- Optional JS = doesn't block rendering - -### Resource Usage -- Memory: < 100MB for typical workload -- Disk: Minimal (SQLite + markdown files) -- CPU: Minimal (no heavy processing) - -**Scaling**: Designed for single-user, typical load is <10 requests/minute. Over-engineering for scale would violate simplicity principle. - -## Testing Strategy - -### Unit Tests (pytest) -- Database operations (CRUD, queries) -- Slug generation and validation -- Markdown rendering -- File operations (atomic writes) -- Session management -- Token validation -- Content hash calculation - -### Integration Tests -- IndieLogin authentication flow (mocked API) -- Micropub note creation (full flow) -- RSS feed generation (validation) -- API endpoints (request/response) -- File + database sync -- Error handling - -### Manual Tests -- Real IndieLogin authentication -- Micropub client integration (e.g., Quill) -- RSS feed in actual reader -- Browser compatibility -- Mobile responsiveness -- Accessibility (screen readers) - -### Validation Tests -- HTML validation (W3C validator) -- RSS validation (W3C feed validator) -- Microformats validation (indiewebify.me) -- Micropub compliance (micropub.rocks) - -## Risk Assessment - -### Technical Risks - -#### Risk: IndieLogin.com Outage -**Impact**: Cannot authenticate new sessions -**Likelihood**: Low (stable service) -**Mitigation**: -- Sessions last 30 days (brief outages don't lock out user) -- Document manual session creation in database -- V2: Add fallback authentication method - -#### Risk: File/Database Sync Failure -**Impact**: Data inconsistency -**Likelihood**: Low (atomic operations, error handling) -**Mitigation**: -- Write files first, database second -- Transaction rollback on failure -- Integrity check on startup (optional) -- Regular backups - -#### Risk: File System Corruption -**Impact**: Lost notes -**Likelihood**: Very low (standard filesystem operations) -**Mitigation**: -- Atomic file writes -- Regular backups (user responsibility) -- Markdown files are recoverable - -#### Risk: Dependency Vulnerabilities -**Impact**: Security breach -**Likelihood**: Medium (all software has bugs) -**Mitigation**: -- Minimal dependencies (6 direct) -- All dependencies are mature, maintained -- Regular updates -- Security scanning (optional) - -### Operational Risks - -#### Risk: User Misconfiguration -**Impact**: Application doesn't work -**Likelihood**: Medium (manual setup required) -**Mitigation**: -- Clear documentation -- .env.example with all settings -- Validation on startup -- Helpful error messages - -#### Risk: Backup Neglect -**Impact**: Data loss -**Likelihood**: Medium (user responsibility) -**Mitigation**: -- Document backup procedures -- Make backup easy (copy data/ folder) -- Consider automated backup scripts (V2) - -## Migration and Future Considerations - -### V1 to V2 Migration Path -- Add features without breaking existing data -- Markdown files remain compatible -- Database schema migrations (ALTER TABLE) -- Backward compatible API changes - -### Potential V2 Enhancements -- Webmentions support -- Media uploads (photos) -- Additional post types (articles, replies) -- Full-text search (SQLite FTS) -- Automated backups -- Self-hosted IndieAuth option -- Multiple IndieAuth providers -- Draft/scheduled posts -- Tags and categories -- Import/export tools - -### Data Portability Strategy -**Export Formats**: -- Markdown files (already portable) -- JSON export (notes + metadata) -- RSS feed (existing notes) -- HTML archive (static site generator) - -**Import Strategy** (V2): -- From other blogging platforms -- From JSON backup -- From markdown directories - -## Success Criteria - -The technology stack is successful if: - -1. **User can publish notes from any Micropub client** ✓ - - Protocol: Micropub over HTTP - - Auth: IndieAuth tokens - - Format: Stored as markdown files - -2. **Notes appear in RSS readers immediately** ✓ - - Format: Valid RSS 2.0 - - Generator: feedgen library - - Caching: 5 minutes - -3. **System runs on minimal resources** ✓ - - Stack: Flask + SQLite (single process) - - Memory: < 100MB - - Dependencies: 6 direct - -4. **Code is readable and maintainable** ✓ - - Language: Python (user's preference) - - Framework: Flask (minimal, clear) - - Style: black formatting, type hints - -5. **All IndieWeb validators pass** ✓ - - Microformats: Server-side templating makes this easy - - IndieAuth: Delegated to indielogin.com - - Micropub: Spec-compliant implementation - -6. **Setup takes less than 5 minutes** ✓ - - Steps: Clone, venv, pip install, configure .env, run - - No build process - - No complex dependencies - -7. **System runs for months without intervention** ✓ - - Architecture: Stateless application - - Persistence: SQLite (reliable) - - Auth: Long-lived sessions (30 days) - -## Quick Start Guide - -### Development Setup -```bash -# Clone repository -git clone && cd starpunk - -# Create virtual environment -python -m venv venv -source venv/bin/activate # or `venv\Scripts\activate` on Windows - -# Install dependencies -pip install -r requirements.txt - -# Configure -cp .env.example .env -# Edit .env: set SITE_URL, ADMIN_ME, SESSION_SECRET - -# Initialize database -flask db init - -# Run development server -flask run - -# Visit http://localhost:5000 -``` - -### Production Deployment -```bash -# Setup (same as development) -# ... - -# Install production server -pip install gunicorn - -# Run with Gunicorn -gunicorn -w 4 -b 127.0.0.1:8000 app:app - -# Configure nginx/Caddy for HTTPS -# Configure systemd for process management -# Set up regular backups of data/ directory -``` - -### Configuration Reference -```bash -# .env file -SITE_URL=https://starpunk.example.com # Your domain -ADMIN_ME=https://your-website.com # Your IndieWeb identity -SESSION_SECRET=random-secret-key # Generate with: python -c "import secrets; print(secrets.token_hex(32))" -DATA_PATH=./data # Where to store notes and database -``` - -## Summary - -StarPunk's technology stack achieves radical simplicity through careful technology selection: - -- **Backend**: Flask (micro-framework) + SQLite (embedded DB) + Python stdlib -- **Storage**: Markdown files (portability) + SQLite metadata (performance) -- **Frontend**: Jinja2 (SSR) + custom CSS (200 lines) + optional vanilla JS -- **Auth**: IndieLogin.com (external, zero maintenance) -- **Build**: None (zero build tools, zero npm) -- **Deploy**: Single package (Gunicorn + systemd + nginx) - -**Total Direct Dependencies**: 6 (Flask, markdown, feedgen, httpx, python-dotenv, pytest) - -**Lines of Code Estimate**: ~1500 LOC for complete V1 implementation - -**Setup Time**: < 5 minutes from clone to running - -This stack embodies the project philosophy: "Every line of code must justify its existence." Each technology choice prioritizes simplicity, standards compliance, and user data ownership over features and complexity. - -## References - -### Architecture Decision Records -- [ADR-001: Python Web Framework Selection](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md) -- [ADR-002: Flask Extensions and Dependencies](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md) -- [ADR-003: Front-end Technology Stack](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md) -- [ADR-004: File-Based Note Storage Architecture](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md) -- [ADR-005: IndieLogin Authentication Integration](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md) - -### Standards and Specifications -- IndieWeb: https://indieweb.org/ -- IndieAuth Spec: https://www.w3.org/TR/indieauth/ -- Micropub Spec: https://micropub.spec.indieweb.org/ -- Microformats2: http://microformats.org/wiki/h-entry -- RSS 2.0: https://www.rssboard.org/rss-specification -- CommonMark: https://spec.commonmark.org/ - -### Tools and Libraries -- Flask: https://flask.palletsprojects.com/ -- Jinja2: https://jinja.palletsprojects.com/ -- IndieLogin.com: https://indielogin.com/ -- Python Markdown: https://python-markdown.github.io/ -- feedgen: https://feedgen.kiesow.be/ -- httpx: https://www.python-httpx.org/ - -### Validation and Testing -- IndieWebify.me: https://indiewebify.me/ -- Micropub Rocks: https://micropub.rocks/ -- W3C Feed Validator: https://validator.w3.org/feed/ -- W3C HTML Validator: https://validator.w3.org/ +**Version**: 2.10.1 (2026-11-03) +**Status**: Current. The original v0.x stack write-up is kept as +[technology-stack-legacy.md](technology-stack-legacy.md) for history. + +StarPunk deliberately uses few dependencies: a WSGI web framework, SQLite +from the standard library, plain files, server-rendered templates and a +handful of libraries for parsing, images and security. No JavaScript build, +no external database, no task queue. See [overview.md](overview.md) for how +the pieces fit together. + +## Runtime + +| Component | Choice | +|-----------|--------| +| Language | Python 3.11 (`python:3.11-slim` base image) | +| Web framework | Flask 3.0 (Werkzeug, Jinja2, itsdangerous, click come with it) | +| WSGI server | gunicorn 21.2, 4 sync workers (see [deployment.md](deployment.md)) | +| Database | SQLite (standard-library `sqlite3`), WAL mode, FTS5 for search | +| Content storage | Markdown files on disk | +| Background work | `threading` daemon threads; `fcntl.flock` file locks to pick one process | +| Templates | Jinja2, server-side rendered | +| Front end | One hand-written stylesheet; one small vanilla JS file for the editor's Markdown preview | +| Packaging | `uv` creates the virtual environment and installs requirements (locally and in the image) | +| Container | Multi-stage `Containerfile` (Podman/Docker), non-root user | +| Reverse proxy | Caddy in production (examples for Caddy and nginx in the repo) | + +## Python dependencies (`requirements.txt`) + +| Package | Pin | Used for | +|---------|-----|----------| +| Flask | `3.0.*` | Web framework | +| gunicorn | `21.2.*` | Production WSGI server | +| markdown | `3.5.*` | Rendering notes (`extra`, `codehilite`, `nl2br` and a bare-URL linking extension) | +| feedgen | `1.0.*` | RSS 2.0 feed (`starpunk/feeds/rss.py`); Atom and JSON Feed are generated by StarPunk's own code | +| httpx | `0.27.*` | All outbound HTTP: OIDC, IndieAuth client discovery, webmention and WebSub requests (through the SSRF-safe wrapper in `webmention_ssrf.py`), crossposting APIs, health check | +| python-dotenv | `1.0.*` | Loading `.env` | +| beautifulsoup4 | `4.12.*` | HTML parsing: IndieAuth client pages, crosspost text and link cards | +| mf2py | `2.0.*` | Parsing microformats2 (webmention sources, reply contexts, author h-card) | +| pytest | `8.0.*` | Test runner (listed here as well as in the image's test stage) | +| psutil | `5.9.*` | Memory monitor and system metrics | +| Pillow | `10.1.*` | Image validation, resizing and variants | +| pillow-heif | `0.18.*` | HEIC/HEIF uploads (iPhone photos) | +| nh3 | `0.2.*` | HTML sanitising (rendered notes, webmention content) | +| PyJWT[crypto] | `2.10.*` | Verifying OIDC ID tokens (JWKS, RS/ES signatures via `cryptography`) | + +Packages imported directly but installed only as dependencies of the above: +`lxml` (outgoing link extraction, webmention endpoint discovery and source checks; from feedgen) and `python-dateutil` (dates in +reply contexts; from feedgen). `markupsafe` comes with Flask/Jinja2. + +### Development dependencies (`requirements-dev.txt`) + +Includes `requirements.txt`, plus `pytest-cov`, `pytest-mock`, `black`, +`flake8`, `mypy` and `gunicorn`. Coding standards are in +[../standards/](../standards/). + +### Deliberately not used + +No ORM (plain SQL), no Flask extensions (login, WTF, SQLAlchemy, caching), +no Celery/Redis or other broker (worker threads with SQLite queues), no +front-end framework or bundler, no separate search server. + +## Standards implemented + +| Area | Standards | +|------|-----------| +| IndieWeb | Micropub (create, update, delete, undelete, queries, media endpoint), IndieAuth (authorization server with PKCE, metadata endpoint, token revocation), Webmention (send and receive), WebSub (publisher and built-in hub), microformats2 (h-entry, h-feed, h-card markup and parsing), rel=me | +| Login | OpenID Connect authorization code flow with PKCE (provider: Pocket ID) | +| Feeds | RSS 2.0, Atom 1.0, JSON Feed 1.1, OPML 2.0, HTTP content negotiation | +| Crossposting | Mastodon client API (GoToSocial), AT Protocol (Bluesky XRPC), Threads Graph API | + +Protocol details: [indieweb-protocols.md](indieweb-protocols.md), +[simplified-auth-architecture.md](simplified-auth-architecture.md), +[syndication-architecture.md](syndication-architecture.md). + +## Testing + +- **Framework**: pytest with pytest-mock; about 1,250 tests in `tests/` + (`test_*.py` per module or feature, shared fixtures in `tests/conftest.py`, + helpers in `tests/helpers/`). +- **Isolation**: the `app` fixture calls `create_app()` with `TESTING=True` + and a temporary data directory, so every test gets a fresh database (all + migrations applied) and note directory. With `TESTING=True` no background + threads start and the OIDC settings are not required; tests drive worker + functions directly. +- **Network**: outbound HTTP is mocked; `webmention_ssrf.TRANSPORT` accepts an + `httpx.MockTransport` for fetcher tests. +- **Running locally**: + + ```bash + uv venv && uv pip install -r requirements-dev.txt + .venv/bin/python -m pytest + ``` + +- **In CI**: the `test` stage of the `Containerfile` installs the production + requirements plus pytest and pytest-mock and runs the whole suite. The + image is only built and pushed if it passes. Checklist: + [../standards/testing-checklist.md](../standards/testing-checklist.md). + +## CI/CD + +Gitea Actions, one workflow (`.gitea/workflows/build-container.yml`), run on +`vX.Y.Z` tags or by hand: build the `test` stage (runs pytest), then build +and push the runtime image to the Gitea container registry tagged with the +version and `latest`. Builds go to a rootless BuildKit daemon; there is no +Docker daemon on the runner. Production pulls the new tag through the +Ansible-managed deployment. Details: [deployment.md](deployment.md). + +## Versioning + +Semantic versioning; the version is `__version__` in `starpunk/__init__.py` +and every release has a `CHANGELOG.md` entry and a `vX.Y.Z` git tag. See +[../standards/](../standards/) for the versioning and git-branching +standards. + +--- + +**Last Updated**: 2026-11-03 (v2.10.1) diff --git a/docs/decisions/ADR-005-indielogin-authentication.md b/docs/decisions/ADR-005-indielogin-authentication.md index be24ef7..bba3a54 100644 --- a/docs/decisions/ADR-005-indielogin-authentication.md +++ b/docs/decisions/ADR-005-indielogin-authentication.md @@ -1,7 +1,9 @@ # ADR-005: IndieLogin Authentication Integration ## Status -Accepted +Superseded by ADR-064 (was: Accepted) + +> Admin login stopped using IndieLogin.com during v1.x (it discovered the authorization endpoint from `ADMIN_ME`) and has used OIDC since v2.0.0 (ADR-064). (status updated 2026-11-03) ## Context The user has explicitly required external IndieLogin authentication via indielogin.com for V1. This is different from implementing a full IndieAuth server (which CLAUDE.MD mentions). The distinction is important: diff --git a/docs/decisions/ADR-007-slug-generation-algorithm.md b/docs/decisions/ADR-007-slug-generation-algorithm.md index f53d2ad..788d703 100644 --- a/docs/decisions/ADR-007-slug-generation-algorithm.md +++ b/docs/decisions/ADR-007-slug-generation-algorithm.md @@ -1,7 +1,9 @@ # ADR-007: Slug Generation Algorithm ## Status -Accepted +Superseded by ADR-062 (was: Accepted) + +> New notes get timestamp slugs by default since v1.5.0 (ADR-062). (status updated 2026-11-03) ## Context @@ -466,7 +468,7 @@ def update_note_slug(note_id, new_slug): - [IndieWeb Permalink Design](https://indieweb.org/permalink) - [URL Slug Best Practices](https://moz.com/learn/seo/url) - [Python secrets Module](https://docs.python.org/3/library/secrets.html) -- [ADR-004: File-Based Note Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md) +- [ADR-004: File-Based Note Storage](ADR-004-file-based-note-storage.md) ## Acceptance Criteria diff --git a/docs/decisions/ADR-008-versioning-strategy.md b/docs/decisions/ADR-008-versioning-strategy.md index bc27067..7c37737 100644 --- a/docs/decisions/ADR-008-versioning-strategy.md +++ b/docs/decisions/ADR-008-versioning-strategy.md @@ -444,9 +444,9 @@ When ready to release: ### Internal Documentation -- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md) - Complete versioning specification -- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md) - System architecture -- [Development Setup](/home/phil/Projects/starpunk/docs/standards/development-setup.md) - Development workflow +- [Versioning Strategy](../standards/versioning-strategy.md) - Complete versioning specification +- [Architecture Overview](../architecture/overview.md) - System architecture +- [Development Setup](../standards/development-setup.md) - Development workflow --- diff --git a/docs/decisions/ADR-009-git-branching-strategy.md b/docs/decisions/ADR-009-git-branching-strategy.md index 9bffda8..3923667 100644 --- a/docs/decisions/ADR-009-git-branching-strategy.md +++ b/docs/decisions/ADR-009-git-branching-strategy.md @@ -470,10 +470,10 @@ Created comprehensive documentation: ### Internal Documentation -- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md) - Semantic versioning decision -- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md) - Complete versioning spec -- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md) - Complete branching spec -- [Development Setup](/home/phil/Projects/starpunk/docs/standards/development-setup.md) - Development workflow +- [ADR-008: Versioning Strategy](ADR-008-versioning-strategy.md) - Semantic versioning decision +- [Versioning Strategy](../standards/versioning-strategy.md) - Complete versioning spec +- [Git Branching Strategy](../standards/git-branching-strategy.md) - Complete branching spec +- [Development Setup](../standards/development-setup.md) - Development workflow --- diff --git a/docs/decisions/ADR-010-authentication-module-design.md b/docs/decisions/ADR-010-authentication-module-design.md index 58fae3b..abb6e16 100644 --- a/docs/decisions/ADR-010-authentication-module-design.md +++ b/docs/decisions/ADR-010-authentication-module-design.md @@ -3,6 +3,8 @@ ## Status Accepted +> Partly superseded by ADR-064: the IndieLogin login flow was replaced by OIDC. The single `starpunk/auth.py` module and the session design are still in use. (status updated 2026-11-03) + ## Context With the core utilities and notes management complete, StarPunk needs an authentication system for the admin interface. ADR-005 already decided on using IndieLogin.com as the authentication provider. This ADR defines the specific module architecture and implementation approach for the authentication system. @@ -204,7 +206,7 @@ Balance between security and usability: ## References -- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md) +- [ADR-005: IndieLogin Authentication](ADR-005-indielogin-authentication.md) - [IndieAuth Specification](https://www.w3.org/TR/indieauth/) - [OWASP Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) - [Flask Security Best Practices](https://flask.palletsprojects.com/en/3.0.x/security/) diff --git a/docs/decisions/ADR-011-development-authentication-mechanism.md b/docs/decisions/ADR-011-development-authentication-mechanism.md index 8486c60..f2c87c6 100644 --- a/docs/decisions/ADR-011-development-authentication-mechanism.md +++ b/docs/decisions/ADR-011-development-authentication-mechanism.md @@ -507,8 +507,8 @@ Dev auth implementation is successful if: ## References -- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md) -- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md) +- [ADR-005: IndieLogin Authentication](ADR-005-indielogin-authentication.md) +- [ADR-010: Authentication Module Design](ADR-010-authentication-module-design.md) - [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) - [The Twelve-Factor App - Dev/Prod Parity](https://12factor.net/dev-prod-parity) diff --git a/docs/decisions/ADR-012-flaky-test-removal.md b/docs/decisions/ADR-012-flaky-test-removal.md index 9891adc..0566102 100644 --- a/docs/decisions/ADR-012-flaky-test-removal.md +++ b/docs/decisions/ADR-012-flaky-test-removal.md @@ -1,7 +1,7 @@ # ADR-012: Flaky Test Removal and Test Quality Standards ## Status -Proposed +Accepted (implemented in v1.5.0; was: Proposed) ## Context diff --git a/docs/decisions/ADR-014-rss-feed-implementation.md b/docs/decisions/ADR-014-rss-feed-implementation.md index 8371d06..150aad8 100644 --- a/docs/decisions/ADR-014-rss-feed-implementation.md +++ b/docs/decisions/ADR-014-rss-feed-implementation.md @@ -4,6 +4,8 @@ Accepted +> Its deferral of WebSub is superseded by ADR-071 (v2.10.0), and "no feed caching" by the feed cache added in v1.1.2. RSS is now one of three feed formats (ADR-038) and is served at `/feed.rss` (`/feed.xml` still works). (status updated 2026-11-03) + ## Context Phase 5 requires implementing RSS feed generation for syndicating published notes. We need to decide on the implementation approach, feed format, caching strategy, and technical details for generating a standards-compliant RSS feed. @@ -365,8 +367,8 @@ The decision will be validated by: - [Feed Discovery](https://indieweb.org/feed_discovery) ### Internal Documentation -- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md) -- [Phase 5 Design](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md) +- [Architecture Overview](../architecture/overview.md) +- [Phase 5 Design](../design/v1.0.0/phase-5-rss-and-container.md) --- diff --git a/docs/decisions/ADR-015-phase-5-implementation-approach.md b/docs/decisions/ADR-015-phase-5-implementation-approach.md index efd7462..e3f5b8d 100644 --- a/docs/decisions/ADR-015-phase-5-implementation-approach.md +++ b/docs/decisions/ADR-015-phase-5-implementation-approach.md @@ -87,10 +87,10 @@ The developer should: 6. Tag release after merge: `git tag -a v0.6.0 -m "Release 0.6.0: RSS feed and production container"` ## References -- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md) -- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md) -- [Phase 5 Design](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md) -- [Phase 5 Quick Reference](/home/phil/Projects/starpunk/docs/designs/phase-5-quick-reference.md) +- [Versioning Strategy](../standards/versioning-strategy.md) +- [Git Branching Strategy](../standards/git-branching-strategy.md) +- [Phase 5 Design](../design/v1.0.0/phase-5-rss-and-container.md) +- [Phase 5 Quick Reference](../design/v1.0.0/phase-5-quick-reference.md) --- diff --git a/docs/decisions/ADR-016-indieauth-client-discovery.md b/docs/decisions/ADR-016-indieauth-client-discovery.md index 2322d3d..a9b004a 100644 --- a/docs/decisions/ADR-016-indieauth-client-discovery.md +++ b/docs/decisions/ADR-016-indieauth-client-discovery.md @@ -4,6 +4,8 @@ **Superseded by ADR-019** - IndieLogin.com does not use h-app microformats for client discovery. PKCE implementation is the correct solution. +> ADR-019 was itself replaced by ADR-025, and the whole IndieLogin login flow by OIDC in ADR-064. (status updated 2026-11-03) + ## Context StarPunk uses IndieLogin.com as a delegated IndieAuth provider for admin authentication. During the first production deployment to https://starpunk.thesatelliteoflove.com, authentication failed with the error: diff --git a/docs/decisions/ADR-017-oauth-client-metadata-document.md b/docs/decisions/ADR-017-oauth-client-metadata-document.md index 23ff0ac..6e39633 100644 --- a/docs/decisions/ADR-017-oauth-client-metadata-document.md +++ b/docs/decisions/ADR-017-oauth-client-metadata-document.md @@ -4,6 +4,8 @@ **Superseded by ADR-019** - IndieLogin.com does not require OAuth metadata endpoint. PKCE implementation is the correct solution. +> ADR-019 was itself replaced by ADR-025, and the whole IndieLogin login flow by OIDC in ADR-064. (status updated 2026-11-03) + ## Context StarPunk continues to experience "client_id is not registered" errors from IndieLogin.com despite implementing h-app microformats in ADR-016 and making them visible in ADR-006. diff --git a/docs/decisions/ADR-018-indieauth-detailed-logging.md b/docs/decisions/ADR-018-indieauth-detailed-logging.md index 693f323..aadde22 100644 --- a/docs/decisions/ADR-018-indieauth-detailed-logging.md +++ b/docs/decisions/ADR-018-indieauth-detailed-logging.md @@ -2,7 +2,9 @@ ## Status -Accepted +Superseded by ADR-064 (was: Accepted) + +> The IndieAuth login flow whose HTTP traffic this logged was replaced by OIDC in v2.0.0. General logging is described in ADR-054. (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-019-indieauth-correct-implementation.md b/docs/decisions/ADR-019-indieauth-correct-implementation.md index 1cdae6e..bc8aaf9 100644 --- a/docs/decisions/ADR-019-indieauth-correct-implementation.md +++ b/docs/decisions/ADR-019-indieauth-correct-implementation.md @@ -2,7 +2,9 @@ ## Status -Proposed +Superseded by ADR-025 (was: Proposed) + +> ADR-025 is the accepted version of this decision; its login flow was in turn replaced by OIDC (ADR-064). (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-021-indieauth-provider-strategy.md b/docs/decisions/ADR-021-indieauth-provider-strategy.md index 8b01428..f7711fc 100644 --- a/docs/decisions/ADR-021-indieauth-provider-strategy.md +++ b/docs/decisions/ADR-021-indieauth-provider-strategy.md @@ -1,7 +1,7 @@ # ADR-021: IndieAuth Provider Strategy ## Status -Accepted +Superseded by ADR-064 (was: Accepted) ## Context @@ -525,8 +525,8 @@ If there is user demand for a more integrated solution, V2 could add: - [IndieWeb Wiki: authorization-endpoint](https://indieweb.org/authorization-endpoint) - Endpoint details ### Related ADRs -- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md) - Original auth decision -- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md) - Auth module structure +- [ADR-005: IndieLogin Authentication](ADR-005-indielogin-authentication.md) - Original auth decision +- [ADR-010: Authentication Module Design](ADR-010-authentication-module-design.md) - Auth module structure ### Community Examples - [Aaron Parecki's IndieAuth Notes](https://aaronparecki.com/2025/10/08/4/cimd) - Client ID metadata adoption diff --git a/docs/decisions/ADR-022-auth-route-prefix-fix.md b/docs/decisions/ADR-022-auth-route-prefix-fix.md index a99c1e2..d14dc3c 100644 --- a/docs/decisions/ADR-022-auth-route-prefix-fix.md +++ b/docs/decisions/ADR-022-auth-route-prefix-fix.md @@ -1,7 +1,9 @@ # ADR-022: Fix IndieAuth Callback Route Mismatch ## Status -Proposed +Accepted (implemented in v0.9.2; was: Proposed) + +> The `/auth` prefix remains; since v2.0.0 `/auth/callback` is the OIDC callback (ADR-064). (status updated 2026-11-03) ## Context We have discovered a critical routing mismatch in our IndieAuth implementation that causes a 404 error when IndieAuth providers redirect back to our application. diff --git a/docs/decisions/ADR-023-indieauth-client-identification.md b/docs/decisions/ADR-023-indieauth-client-identification.md index 21b0084..ebf1143 100644 --- a/docs/decisions/ADR-023-indieauth-client-identification.md +++ b/docs/decisions/ADR-023-indieauth-client-identification.md @@ -1,7 +1,9 @@ # ADR-023: IndieAuth Client Identification Strategy ## Status -Accepted +Superseded by ADR-064 (was: Accepted) + +> StarPunk is now a registered OIDC client for login and publishes no h-app. (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-024-static-identity-page.md b/docs/decisions/ADR-024-static-identity-page.md index 834d76b..0b86580 100644 --- a/docs/decisions/ADR-024-static-identity-page.md +++ b/docs/decisions/ADR-024-static-identity-page.md @@ -1,7 +1,9 @@ # ADR-024: Static HTML Identity Pages for IndieAuth ## Status -Accepted +Superseded by ADR-064 (was: Accepted) + +> The `ADMIN_ME` page must now advertise StarPunk's own IndieAuth endpoints, not indieauth.com's (ADR-064, decision 3). (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-025-indieauth-pkce-authentication.md b/docs/decisions/ADR-025-indieauth-pkce-authentication.md index 5afab42..87bc486 100644 --- a/docs/decisions/ADR-025-indieauth-pkce-authentication.md +++ b/docs/decisions/ADR-025-indieauth-pkce-authentication.md @@ -2,7 +2,7 @@ ## Status -Accepted +Superseded by ADR-064 (was: Accepted) ## Context diff --git a/docs/decisions/ADR-026-indieauth-token-exchange-compliance.md b/docs/decisions/ADR-026-indieauth-token-exchange-compliance.md index 83dfedf..98f26ab 100644 --- a/docs/decisions/ADR-026-indieauth-token-exchange-compliance.md +++ b/docs/decisions/ADR-026-indieauth-token-exchange-compliance.md @@ -1,7 +1,7 @@ # ADR-026: IndieAuth Token Exchange Compliance ## Status -Accepted +Superseded by ADR-064 (was: Accepted) ## Context StarPunk's IndieAuth implementation is failing to authenticate with certain providers (specifically gondulf.thesatelliteoflove.com) during the token exchange phase. The provider is rejecting our token exchange requests with a "missing grant_type" error. diff --git a/docs/decisions/ADR-027-indieauth-authentication-endpoint-correction.md b/docs/decisions/ADR-027-indieauth-authentication-endpoint-correction.md index 08edada..52db80d 100644 --- a/docs/decisions/ADR-027-indieauth-authentication-endpoint-correction.md +++ b/docs/decisions/ADR-027-indieauth-authentication-endpoint-correction.md @@ -1,7 +1,7 @@ # ADR-027: IndieAuth Authentication Endpoint Correction ## Status -Accepted +Superseded by ADR-064 (was: Accepted) ## Context @@ -178,7 +178,7 @@ Continue current implementation, document incompatibility. - [IndieAuth Specification Section 5.4](https://www.w3.org/TR/indieauth/#authentication-response): Authorization Code Verification for authentication flows - [IndieAuth Specification Section 6.3](https://www.w3.org/TR/indieauth/#token-response): Token Endpoint for authorization flows - [IndieAuth Authentication vs Authorization](https://indieweb.org/IndieAuth#Authentication_vs_Authorization): Community documentation -- [ADR-021: IndieAuth Provider Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-021-indieauth-provider-strategy.md): Related architectural decision +- [ADR-021: IndieAuth Provider Strategy](ADR-021-indieauth-provider-strategy.md): Related architectural decision --- diff --git a/docs/decisions/ADR-028-micropub-implementation.md b/docs/decisions/ADR-028-micropub-implementation.md index ab1e05d..0c78580 100644 --- a/docs/decisions/ADR-028-micropub-implementation.md +++ b/docs/decisions/ADR-028-micropub-implementation.md @@ -2,7 +2,9 @@ ## Status -Proposed +Accepted (implemented in v1.0.0-rc.1; was: Proposed) + +> Its token endpoint was removed by ADR-050; tokens are now issued and verified by StarPunk's own IndieAuth server (ADR-064). Update and delete were added by ADR-067. (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-029-micropub-indieauth-integration.md b/docs/decisions/ADR-029-micropub-indieauth-integration.md index f3e4962..3cb676c 100644 --- a/docs/decisions/ADR-029-micropub-indieauth-integration.md +++ b/docs/decisions/ADR-029-micropub-indieauth-integration.md @@ -1,7 +1,9 @@ # ADR-029: Micropub IndieAuth Integration Strategy ## Status -Accepted +Superseded by ADR-050, then ADR-064 (was: Accepted) + +> The token endpoint designed here was removed in v1.0.0-rc.4 (ADR-050). v2.0.0 added a new built-in IndieAuth server (ADR-064). (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-030-external-token-verification-architecture.md b/docs/decisions/ADR-030-external-token-verification-architecture.md index eba8baf..af07ba0 100644 --- a/docs/decisions/ADR-030-external-token-verification-architecture.md +++ b/docs/decisions/ADR-030-external-token-verification-architecture.md @@ -1,7 +1,7 @@ # ADR-030: External Token Verification Architecture ## Status -Accepted +Superseded by ADR-043, then ADR-064 (was: Accepted) ## Context diff --git a/docs/decisions/ADR-031-database-migration-system-redesign.md b/docs/decisions/ADR-031-database-migration-system-redesign.md index 5e94412..310d6c1 100644 --- a/docs/decisions/ADR-031-database-migration-system-redesign.md +++ b/docs/decisions/ADR-031-database-migration-system-redesign.md @@ -1,7 +1,7 @@ # ADR-031: Database Migration System Redesign ## Status -Proposed +Accepted (implemented through ADR-032 and ADR-033; was: Proposed) ## Context diff --git a/docs/decisions/ADR-033-database-migration-redesign.md b/docs/decisions/ADR-033-database-migration-redesign.md index c26898c..1646a72 100644 --- a/docs/decisions/ADR-033-database-migration-redesign.md +++ b/docs/decisions/ADR-033-database-migration-redesign.md @@ -1,7 +1,7 @@ # ADR-033: Database Migration System Redesign ## Status -Proposed +Accepted (implemented in v1.1.0; was: Proposed) ## Context The current migration system has a critical flaw: duplicate schema definitions exist between SCHEMA_SQL (used for fresh installs) and individual migration files. This violates the DRY principle and creates maintenance burden. When schema changes are made, developers must remember to update both locations, leading to potential inconsistencies. diff --git a/docs/decisions/ADR-034-full-text-search.md b/docs/decisions/ADR-034-full-text-search.md index d130f2a..92fd633 100644 --- a/docs/decisions/ADR-034-full-text-search.md +++ b/docs/decisions/ADR-034-full-text-search.md @@ -1,7 +1,7 @@ # ADR-034: Full-Text Search with SQLite FTS5 ## Status -Proposed +Accepted (implemented in v1.1.0; was: Proposed) ## Context Users need the ability to search through their notes efficiently. Currently, finding specific content requires manually browsing through notes or using external tools. A built-in search capability is essential for any content management system, especially as the number of notes grows. diff --git a/docs/decisions/ADR-035-custom-slugs.md b/docs/decisions/ADR-035-custom-slugs.md index 670a0a1..b5981dd 100644 --- a/docs/decisions/ADR-035-custom-slugs.md +++ b/docs/decisions/ADR-035-custom-slugs.md @@ -1,7 +1,9 @@ # ADR-035: Custom Slugs in Micropub ## Status -Proposed +Accepted (implemented in v1.1.0; was: Proposed) + +> Default slugs later became timestamps (ADR-062); `mp-slug` is still honoured. (status updated 2026-11-03) ## Context Currently, StarPunk auto-generates slugs from note content (first 5 words). While this works well for most cases, users may want to specify custom slugs for: diff --git a/docs/decisions/ADR-036-indieauth-token-verification-method.md b/docs/decisions/ADR-036-indieauth-token-verification-method.md index f74d974..819554c 100644 --- a/docs/decisions/ADR-036-indieauth-token-verification-method.md +++ b/docs/decisions/ADR-036-indieauth-token-verification-method.md @@ -1,7 +1,9 @@ # ADR-036: IndieAuth Token Verification Method Diagnosis ## Status -Accepted +Superseded by ADR-064 (was: Accepted) + +> Micropub tokens are verified locally since v2.0.0. (status updated 2026-11-03) ## Context StarPunk is experiencing HTTP 405 Method Not Allowed errors when verifying tokens with the external IndieAuth provider (gondulf.thesatelliteoflove.com). The user questioned "why are we making GET requests to these endpoints?" diff --git a/docs/decisions/ADR-038-syndication-formats.md b/docs/decisions/ADR-038-syndication-formats.md index 6809340..85dd730 100644 --- a/docs/decisions/ADR-038-syndication-formats.md +++ b/docs/decisions/ADR-038-syndication-formats.md @@ -1,7 +1,7 @@ # ADR-022: Multiple Syndication Format Support ## Status -Proposed +Accepted (implemented in v1.1.2; was: Proposed) ## Context StarPunk currently provides RSS 2.0 feed generation using the feedgen library. The IndieWeb community and modern feed readers increasingly support additional syndication formats: diff --git a/docs/decisions/ADR-040-microformats2-compliance.md b/docs/decisions/ADR-040-microformats2-compliance.md index 1664c9a..d7ea1b5 100644 --- a/docs/decisions/ADR-040-microformats2-compliance.md +++ b/docs/decisions/ADR-040-microformats2-compliance.md @@ -1,7 +1,7 @@ # ADR-023: Strict Microformats2 Compliance ## Status -Proposed +Accepted (implemented in v1.3.0, reviewed in v2.8.0; was: Proposed) ## Context StarPunk currently implements basic microformats2 markup: diff --git a/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md b/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md index 3973a58..c87e579 100644 --- a/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md +++ b/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md @@ -158,7 +158,7 @@ The lesson learned: Release candidates are valuable for discovering not just bug - [Semantic Versioning 2.0.0](https://semver.org/) - [ADR-008: Versioning Strategy](../standards/versioning-strategy.md) - [ADR-021: IndieAuth Provider Strategy](./ADR-021-indieauth-provider-strategy.md) -- [StarPunk Philosophy](../architecture/philosophy.md) +- StarPunk Philosophy (`philosophy.md`, not preserved) --- diff --git a/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md b/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md index b4dcd2c..7dfd9ed 100644 --- a/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md +++ b/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md @@ -1,7 +1,9 @@ # ADR-043-CORRECTED: IndieAuth Endpoint Discovery Architecture ## Status -Accepted (Replaces incorrect understanding in previous ADR-030) +Superseded by ADR-064 (was: Accepted; it replaced ADR-030) + +> Admin login uses OIDC and Micropub tokens are verified locally since v2.0.0; no endpoints are discovered from `ADMIN_ME`. (status updated 2026-11-03) ## Context diff --git a/docs/decisions/ADR-044-endpoint-discovery-implementation.md b/docs/decisions/ADR-044-endpoint-discovery-implementation.md index 7e368c1..b110d2b 100644 --- a/docs/decisions/ADR-044-endpoint-discovery-implementation.md +++ b/docs/decisions/ADR-044-endpoint-discovery-implementation.md @@ -1,7 +1,7 @@ # ADR-031: IndieAuth Endpoint Discovery Implementation Details ## Status -Accepted +Superseded by ADR-064 (was: Accepted) ## Context diff --git a/docs/decisions/ADR-050-remove-custom-indieauth-server.md b/docs/decisions/ADR-050-remove-custom-indieauth-server.md index cde6a91..271cd9c 100644 --- a/docs/decisions/ADR-050-remove-custom-indieauth-server.md +++ b/docs/decisions/ADR-050-remove-custom-indieauth-server.md @@ -1,7 +1,9 @@ # ADR-050: Remove Custom IndieAuth Server ## Status -Proposed +Superseded by ADR-064 (was: Proposed; implemented in v1.0.0-rc.4) + +> v2.0.0 brought back a built-in IndieAuth server for Micropub clients (ADR-064). (status updated 2026-11-03) ## Context @@ -363,7 +365,7 @@ TOKEN_ENDPOINT=https://tokens.indieauth.com/token - [IndieAuth Spec](https://www.w3.org/TR/indieauth/) - [tokens.indieauth.com](https://tokens.indieauth.com/) -- [ADR-021: IndieAuth Provider Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-021-indieauth-provider-strategy.md) +- [ADR-021: IndieAuth Provider Strategy](ADR-021-indieauth-provider-strategy.md) - [Micropub Spec](https://www.w3.org/TR/micropub/) --- diff --git a/docs/decisions/ADR-056-no-selfhosted-indieauth.md b/docs/decisions/ADR-056-no-selfhosted-indieauth.md index 4038ece..b253d63 100644 --- a/docs/decisions/ADR-056-no-selfhosted-indieauth.md +++ b/docs/decisions/ADR-056-no-selfhosted-indieauth.md @@ -1,7 +1,9 @@ # ADR-056: Use External IndieAuth Provider (Never Self-Host) ## Status -**ACCEPTED** - This is a permanent, non-negotiable decision. +Superseded by ADR-064 (was: Accepted, "permanent, non-negotiable") + +> In v2.0.0 the operator moved login to OIDC and StarPunk became its own IndieAuth server for Micropub clients (ADR-064). (status updated 2026-11-03) ## Context StarPunk is a minimal IndieWeb CMS focused on **content creation and syndication**, not identity infrastructure. The project philosophy demands that every line of code must justify its existence. diff --git a/docs/decisions/ADR-059-full-feed-media-standardization.md b/docs/decisions/ADR-059-full-feed-media-standardization.md index 9140085..e19e46b 100644 --- a/docs/decisions/ADR-059-full-feed-media-standardization.md +++ b/docs/decisions/ADR-059-full-feed-media-standardization.md @@ -271,8 +271,8 @@ Make media support pluggable for advanced features. - [Apple Podcast RSS Requirements](https://podcasters.apple.com/support/823-podcast-requirements) - [Podcast Index Namespace](https://github.com/Podcastindex-org/podcast-namespace) - [RSS 2.0 Enclosure Specification](https://www.rssboard.org/rss-specification#ltenclosuregtSubelementOfLtitemgt) -- [ADR-057: Media Attachment Model](/home/phil/Projects/starpunk/docs/decisions/ADR-057-media-attachment-model.md) -- [ADR-058: Image Optimization Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-058-image-optimization-strategy.md) +- [ADR-057: Media Attachment Model](ADR-057-media-attachment-model.md) +- [ADR-058: Image Optimization Strategy](ADR-058-image-optimization-strategy.md) ## Decision This ADR documents the scope of Full Standardization (Option 3) for the project backlog. Implementation should be scheduled for v1.3.0 and v1.4.0 releases according to the phased approach outlined above. diff --git a/docs/decisions/ADR-060-production-hotfix-metrics-dashboard.md b/docs/decisions/ADR-060-production-hotfix-metrics-dashboard.md new file mode 100644 index 0000000..e71dfca --- /dev/null +++ b/docs/decisions/ADR-060-production-hotfix-metrics-dashboard.md @@ -0,0 +1,103 @@ +# ADR-060: Route Adapter for the Metrics Dashboard + +## Status + +Accepted (v1.1.1-rc.2, 2025-11-25) + +> Reconstructed on 2026-11-03 from code, changelog and related documents; +> the original was lost. The original +> (`ADR-060-production-hotfix-metrics-dashboard.md`) was deleted in the +> v1.1.1-rc.2 architectural review as "a bug fix, not an architectural +> decision", and its content was merged into +> `docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md`. Code +> (`starpunk/routes/admin.py`) and CHANGELOG 1.1.1-rc.2 still cite it, so +> this record restores the number. +> +> Not to be confused with the "Option 2 (ADR-060)" for Media RSS mentioned +> in ADR-059: that ADR was planned but never written (see +> `docs/design/v1.2.0/2025-12-10-documentation-audit-v1.2.0.md`). + +## Context + +v1.1.1-rc.1 added a metrics dashboard. In production it returned 500: + +``` +jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'database' +``` + +Two problems were found: + +1. **Route conflict.** The notes dashboard (`/admin/`, endpoint + `admin.dashboard`) and the new metrics dashboard (`/admin/dashboard`) + were easily confused. This was fixed first by moving the metrics + dashboard to `/admin/metrics-dashboard` (the "ADR-022" route-naming fix + cited in the CHANGELOG; see Numbering below). +2. **Data contract mismatch** (the real cause). The template reads + `metrics.database.count` and `.avg/.min/.max`, but + `starpunk.monitoring.get_metrics_stats()` returns + `by_type.database.count` and `avg_duration_ms`, `min_duration_ms`, + `max_duration_ms`. + +Either the monitoring module, the template (and its JavaScript), or the +route could change. + +## Decision + +Adapt the data **in the route handler** (presentation layer) and leave +both the monitoring module's API and the template unchanged. + +- `transform_metrics_for_template()` in `starpunk/routes/admin.py` + flattens `by_type.` to `` for `database`, `http` and + `render`, renames `avg_duration_ms`/`min_duration_ms`/`max_duration_ms` + to `avg`/`min`/`max`, and keeps `total_count`, `max_size` and + `process_id`. Missing types get zero values. +- If collecting metrics fails, the route flashes a warning and renders + the same structure with zeros. +- The monitoring imports are defensive: if `starpunk.monitoring` or the + pool statistics are unavailable, stub functions return an error value + and the dashboard still renders. +- The metrics dashboard lives at `/admin/metrics-dashboard` + (`admin.metrics_dashboard`); `/admin/` (`admin.dashboard`) stays the + notes list, so existing `url_for("admin.dashboard")` redirects are + unaffected. + +## Consequences + +### Positive + +- Minimal, low-risk hotfix: one route changed, no template or monitoring + changes. +- The monitoring module's output stays the same for the JSON endpoint + (`/admin/metrics`) and other consumers. +- The dashboard degrades instead of failing when metrics are missing. + +### Negative + +- Treats the symptom: the template and the monitoring module still + disagree about the data shape, and the adapter must be kept in step + with both (noted in `docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md`). +- Errors loading metrics are shown as zeros, which can hide a problem. + +## Alternatives Considered + +- **Change the monitoring module to return the template's shape**: breaks + its other consumers. +- **Change the template and its JavaScript**: larger change in a hotfix, + with more to test. + +## Numbering + +The CHANGELOG for 1.1.1-rc.2 says "See ADR-022 and ADR-060". The ADR-022 +it meant was `ADR-022-admin-dashboard-route-conflict-hotfix.md`, deleted in +the same review; its number collided with the existing +[ADR-022](ADR-022-auth-route-prefix-fix.md) (IndieAuth callback route) and +it was not restored. Its decision (the route rename) is recorded above. + +## References + +- `starpunk/routes/admin.py`: `transform_metrics_for_template()`, + `metrics_dashboard()` +- `docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md` +- `docs/design/v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md` +- `docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md` +- ADR-053 (performance monitoring) diff --git a/docs/decisions/ADR-063-webmention-implementation.md b/docs/decisions/ADR-063-webmention-implementation.md new file mode 100644 index 0000000..c8dffd4 --- /dev/null +++ b/docs/decisions/ADR-063-webmention-implementation.md @@ -0,0 +1,293 @@ +# ADR-063: Webmention Implementation + +## Status + +Accepted (v1.6.0; revised v2.6.8, v2.6.9, v2.7.0, v2.7.2, v2.8.0, v2.10.1) + +> Reconstructed on 2026-11-03 from code, changelog and related documents; +> the original was lost. The v1.6.0 release was never committed: its code +> was recovered from the production image (`v1.6.0-rc.2`), but its tests, +> this ADR and the `docs/design/v1.6.0/` folder (`background-worker.md`, +> `api-contract.md`, `display-moderation.md`, `rate-limiting.md`) were not +> in the image. This document describes the design as it exists in +> v2.10.1. The numbering of the decisions below is new, except that +> Decision 9 (SSRF protection) keeps the number the code cites. + +## Context + +Webmention (W3C Recommendation, https://www.w3.org/TR/webmention/) is how +IndieWeb sites tell each other that one page links to another. It is what +makes replies, likes and reposts from other sites (and from Mastodon or +Bluesky via Bridgy) show up on a note, and what tells the sites a note +replies to or links to that it exists. + +Both directions involve fetching URLs chosen by someone else, which is +slow, can fail, and can be abused: + +- A receiver must fetch the source page to check that it really links to + the target. Doing that inside the request lets anyone make StarPunk + fetch arbitrary URLs synchronously, and ties up a server process. +- A sender must discover each target's endpoint and POST to it, with + retries when the other site is down. +- Any fetch can be pointed (directly, by redirect or by DNS) at private + addresses on the server's own network (SSRF). +- Content from other sites is shown on our pages (XSS). + +StarPunk is a single-user site on SQLite, run under gunicorn with several +processes, with no job queue or message broker. + +## Decision + +### 1. Endpoint and discovery + +- `POST /webmention` receives webmentions (form-encoded as the spec + requires; JSON is accepted as an extension); + `GET /webmention` returns a short description of the endpoint. +- HTML responses advertise it with a `Link: ; rel="webmention"` + header (added alongside other Link headers, not replacing them) and a + `` in `base.html`. +- `WEBMENTION_ENABLED` (default true) turns the feature off. + +### 2. Receiving is asynchronous + +The endpoint does only cheap, local checks and then answers +**202 Accepted**; verification happens later in the background worker. + +Synchronous checks, each answered with 400 on failure: `source` and +`target` are well-formed http(s) URLs of at most 2048 characters, they +differ, and the target is a **published note** on this site (host compared +case-insensitively and without default ports; `#fragment` dropped). Since +v2.7.0 mentions of the home page or other pages are refused instead of +being stored and never shown. + +The mention is upserted into `webmentions` keyed by `(source_url, +target_url)` with `validation_status = 'pending'`, so a re-sent mention is +re-verified rather than duplicated. + +### 3. Background worker + +One daemon thread (`WebmentionWorker`) handles both incoming verification +and outgoing sending, using two SQLite tables as queues (`webmentions`, +`webmention_queue`). No external queue is introduced. + +- Started by `create_app()` when `WEBMENTION_WORKER_ENABLED` is true (not + in tests). It polls every `WEBMENTION_POLL_INTERVAL` seconds (10), + handles up to `WEBMENTION_BATCH_SIZE` items (5) per pass, and backs off + `WEBMENTION_ERROR_BACKOFF` seconds (60) after an unexpected error. +- Each pass runs inside `app.app_context()` (v2.6.8: without it every + item failed with "Working outside of application context"). The thread + lives for the life of the process; it is not stopped on app-context + teardown (v2.6.8: that stopped it after the first request). +- **Only one process works the queues** (v2.6.9). Every gunicorn process + starts a worker, but a worker only processes after taking a + non-blocking `flock` on `/webmention-worker.lock`. Others retry + each poll, so one takes over if the holder dies. +- On acquiring the lock it resets outgoing items stuck in `sending` for + more than 5 minutes (orphans from a crash). +- `/health?detailed=true` (authenticated) reports the worker's + statistics. + +### 4. Verifying a received webmention + +Per Recommendation 3.2.2 and 3.2.4: + +- The source is fetched with an `Accept` header, following redirects + (Decision 9), and decoded in its declared character set. +- The source must link to the **exact** target URL, by media type: for + HTML any link attribute (resolved against the final URL after + redirects); for JSON any string value; for `text/*` a substring; other + types never match. Fragments are ignored (v2.7.0). +- The source is parsed with mf2py. The responding entry and its author are + found with the authorship algorithm (v2.8.0); the mention type is one of + `reply`, `like`, `repost`, `bookmark` or `mention`. The source's own + `u-url` and `dt-published` are stored (`source_post_url`, + `source_published`, migration 014) so the response links to and is + dated by the original post. +- If the source is gone (410, other 4xx) or no longer links, the mention + is removed from display. If it can't be reached right now (network + error, 5xx, temporary DNS failure), a previously valid mention stays up + (v2.7.0, v2.10.1). +- A webmention from one of the note's own crossposts (e.g. its GoToSocial + copy returned through Bridgy) is ignored (v2.8.0). + +### 5. Moderation and display + +- Valid mentions are approved automatically when `WEBMENTION_AUTO_APPROVE` + is true (the default), otherwise they wait in `pending`. The admin can + approve, hide or delete them at `/admin/webmentions` (single and bulk + actions). +- A re-sent mention keeps its moderation: hidden stays hidden, approved + stays approved (v2.7.0). +- Notes show only mentions that are both `valid` and `approved`, grouped + by type. Replies are marked up as `u-comment h-cite`; likes, reposts, + bookmarks and mentions as `u-like`, `u-repost`, `u-bookmark`, + `u-mention` h-cites, each with the author's h-card (v2.8.0). + +### 6. Sending + +- After a note is created, edited, deleted or restored, links are + extracted from its **rendered HTML**: `` only, excluding links + inside `
` and ``, the `in_reply_to` target first, then
+  document order, at most 10 current links per operation. Each target is
+  queued in `webmention_queue` (unique per source and target).
+- On edit, every target sent to before is notified again, including links
+  the edit removed and an old reply target; on delete and undelete too
+  (Recommendation 3.1.4, 3.1.5; v2.7.0). Re-sends are not capped.
+- When the responses a note displays change (a mention arrives, changes
+  or is removed, or the admin approves, hides or deletes one that was
+  shown), the note's previous webmentions are re-queued, as 3.1.4
+  recommends. An unchanged re-verification sends nothing, so two sites
+  that both do this don't ping-pong (v2.7.2).
+- Endpoint discovery follows 3.1.2: the first `Link` header with a
+  `webmention` rel token (RFC 8288 parsing, several headers, any case),
+  otherwise the first `` or `` in document order; relative URLs
+  resolve against the final URL. The endpoint is discovered afresh every
+  time; there is no cache (v2.7.0).
+- The webmention is a form-encoded POST. Any 2xx is success; redirects
+  are not followed (a redirected POST would become a GET). A target
+  without an endpoint is marked `no_endpoint`.
+- Failures (network errors, 5xx, 429) are retried after 1 h, 6 h and
+  24 h; after the fourth failed attempt the item is `failed`.
+- The User-Agent is `StarPunk/ Webmention (+site)`.
+
+### 7. Deleted notes
+
+A deleted note answers **410 Gone** with a "This post has been deleted"
+page (soft-deleted notes, and hard-deleted notes that sent webmentions),
+so receivers can remove the mention (3.1.5; v2.7.0).
+
+### 8. Content safety (XSS)
+
+- Snippets and reply content are sanitized with nh3, cut at 500
+  characters and sanitized again so no tag is left open (v2.7.0); the
+  admin "Mentions" list shows them with tags stripped.
+- Author URLs and photos are kept only if they are absolute http(s) URLs;
+  otherwise the source URL is used as the author link and no photo is
+  shown (v2.6.9). mf2 values with `alt` are reduced to their URL.
+
+### 9. SSRF protection
+
+All outbound requests for webmentions (source fetches, endpoint discovery
+and the POST) go through `starpunk/webmention_ssrf.py` (Recommendation
+4.2, 4.3, 4.5):
+
+- Only http(s). **Every** address a hostname resolves to (IPv4 and IPv6)
+  must be public: private, loopback, link-local, multicast, reserved,
+  unspecified, carrier-grade NAT (`100.64.0.0/10`), `0.0.0.0/8` and
+  IPv4-mapped forms are blocked.
+- Redirects (at most 10) are followed by hand and **each hop** is checked
+  (v2.7.0).
+- **DNS pinning** (v2.7.2): each request connects to the exact address
+  that passed the check, with the original host in the `Host` header and
+  as TLS SNI, so certificates are still verified against the hostname. A
+  rebinding DNS server can't answer differently the second time. IPv4 is
+  preferred when a host has both.
+- Responses are limited to 1 MB, and each fetch has a total time limit of
+  10 s that a slow, byte-by-byte response can't extend (v2.10.1).
+- `DEV_MODE` allows localhost for local testing.
+
+The same guard is reused for IndieAuth client metadata fetches (ADR-064),
+Micropub remote photos (v2.9.0) and WebSub callbacks and deliveries
+(ADR-071).
+
+### 10. Rate limiting
+
+`POST /webmention` is rate-limited before any other work: by client IP
+(`WEBMENTION_RATE_LIMIT_IP`, 60) and by source domain
+(`WEBMENTION_RATE_LIMIT_DOMAIN`, 10) per `WEBMENTION_RATE_LIMIT_WINDOW`
+(60 s), answering 429 with `Retry-After`. Counters are an in-memory
+sliding-window log (`starpunk/rate_limiter.py`), so they are per server
+process. Behind a reverse proxy, `TRUSTED_PROXY=true` makes the first
+`X-Forwarded-For` address the client IP. `WEBMENTION_RATE_LIMIT_ENABLED`
+turns it off.
+
+`starpunk/rate_limiter.py` and `routes/webmention.py` cite this as
+"ADR-064: Webmention Rate Limiting", a v1.6.0 ADR that was lost with this
+one. The number ADR-064 was later reused for OIDC login
+(ADR-064-oidc-admin-login-and-builtin-indieauth-server.md); the rate-limit
+decision is recorded here instead.
+
+### 11. Data (migrations 010 and 014)
+
+- `notes.in_reply_to`
+- `webmentions`: source, target, target note, type, author name/URL/photo,
+  snippet, `validation_status` (`pending`, `valid`, `invalid`, `error`),
+  `moderation_status` (`pending`, `approved`, `hidden`, `deleted`),
+  timestamps, and (migration 014) `source_post_url`, `source_published`
+- `webmention_queue`: outgoing items with `status` (`pending`, `sending`,
+  `sent`, `failed`, `no_endpoint`), retry count and next retry time
+- `reply_contexts`: cached title, snippet and author of pages notes reply
+  to
+
+## Consequences
+
+### Positive
+
+- Receiving is cheap and can't be used to make StarPunk fetch URLs while
+  the sender waits.
+- No new infrastructure: the queues are SQLite tables and the worker is a
+  thread, as for crossposting and WebSub.
+- Outbound fetching is hardened once and reused by every other feature
+  that fetches user-supplied URLs.
+- Follows every MUST and SHOULD of the Recommendation after v2.7.2.
+
+### Negative
+
+- Mentions appear only after the next worker pass (seconds), not
+  immediately.
+- One worker per site: throughput is limited, which is fine for a
+  personal site.
+- Rate limits are per process and reset on restart.
+- `error` rows (unexpected failures) are not retried automatically.
+- Endpoint discovery ignores HTTP cache headers (spec 5.3); targets are
+  only fetched when a note changes.
+- The 410 page is a generic tombstone without microformats.
+
+## Revisions
+
+- **v2.6.8** — Worker runs inside an app context and is no longer stopped
+  on teardown; before this, no webmention was ever processed
+  (`docs/design/v2.6.8/2026-11-03-webmention-worker-app-context.md`).
+- **v2.6.9** — Author photos with alt text; endpoint discovery crash
+  fixed and discovery errors retried; `flock` so only one process works
+  the queues; http(s)-only author links
+  (`docs/design/v2.6.9/2026-11-03-webmention-processing-fixes.md`).
+- **v2.7.0** — Full review against the Recommendation: published notes
+  only, exact target match, RFC 8288 endpoint discovery, no discovery
+  cache, re-sends on edit/delete/undelete, 410 for deleted notes,
+  per-hop SSRF checks, size and time limits, moderation kept on re-send
+  (`docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md`).
+- **v2.7.2** — DNS pinning; re-send when displayed responses change
+  (`docs/design/v2.7.2/2026-11-03-webmention-shoulds.md`).
+- **v2.8.0** — Authorship algorithm, source URL and published time
+  (migration 014), response microformats, own crossposts ignored
+  (`docs/design/v2.8.0/2026-11-03-microformats2-review.md`).
+- **v2.10.1** — Hard total time limit on fetches; temporary DNS failures
+  treated as transient.
+
+## Alternatives Considered
+
+- **Synchronous verification in the request**: simpler, but slow, ties
+  up a gunicorn process and turns the endpoint into a fetch-anything
+  proxy. The Recommendation allows 202 for exactly this.
+- **External service (webmention.io)**: no code to run, but mentions
+  would live outside the site's database and moderation, against the
+  self-hosted approach.
+- **A job queue (Celery/RQ with Redis)**: new infrastructure for a few
+  jobs a day.
+- **Resolving and validating the host, then letting the HTTP client
+  connect normally**: open to DNS rebinding; replaced by pinning in
+  v2.7.2.
+
+## References
+
+- W3C Webmention: https://www.w3.org/TR/webmention/
+- Code: `starpunk/routes/webmention.py`, `starpunk/webmention_worker.py`,
+  `starpunk/webmention_processor.py`, `starpunk/webmention_sender.py`,
+  `starpunk/webmention_ssrf.py`, `starpunk/webmention_queries.py`,
+  `starpunk/rate_limiter.py`, `migrations/010_add_webmentions.sql`,
+  `migrations/014_webmention_source_details.sql`
+- Tests: `tests/test_webmention_spec.py`, `tests/test_webmention_worker.py`
+- [IndieWeb protocols](../architecture/indieweb-protocols.md)
+- ADR-064 (OIDC login; reuses the SSRF guard), ADR-071 (WebSub; same
+  guard and worker pattern)
diff --git a/docs/decisions/ADR-068-likes-and-reposts.md b/docs/decisions/ADR-068-likes-and-reposts.md
index e0d2c17..ac9ccd0 100644
--- a/docs/decisions/ADR-068-likes-and-reposts.md
+++ b/docs/decisions/ADR-068-likes-and-reposts.md
@@ -4,6 +4,8 @@
 
 Accepted (v2.5.0, 2026-11-01). Bookmarks were considered and declined.
 
+> Bookmarks were later added in v2.9.0 (Micropub `bookmark-of`, migration 015) without a separate ADR. (status updated 2026-11-03)
+
 ## Decision
 
 1. **Storage.** `notes.like_of` / `notes.repost_of` (migration 013). The note's
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index aaafaae..9d98ae6 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -1,139 +1,203 @@
 # Architectural Decision Records (ADRs) Index
 
-This directory contains all Architectural Decision Records for StarPunk CMS. ADRs document significant architectural decisions, their context, rationale, and consequences.
+This directory holds StarPunk's Architectural Decision Records. Each ADR
+records one decision: its context, what was decided, and the consequences.
+Superseded ADRs are kept as history; their Status line names the ADR that
+replaced them.
 
-## ADR Format
+**Total ADR files**: 67 (66 numbers: ADR-001 to ADR-044 and ADR-050 to
+ADR-071, with two files numbered ADR-012). See [Numbering](#numbering).
 
-Each ADR follows this structure:
-- **Title**: ADR-NNN-brief-descriptive-title.md
-- **Status**: Proposed, Accepted, Deprecated, Superseded
-- **Context**: Why we're making this decision
-- **Decision**: What we decided to do
-- **Consequences**: Impact of this decision
+Status values: **Accepted** (in force), **Superseded** (replaced by a later
+ADR), **Deprecated** (withdrawn, nothing replaces it; none at present),
+**Proposed** (not implemented). "Accepted*" means accepted, with later
+changes noted in the ADR's Status section.
 
-## All ADRs (Chronological)
+## Current decisions by area
 
-### Foundation & Technology Stack (ADR-001 to ADR-009)
-- **[ADR-001](ADR-001-python-web-framework.md)** - Python Web Framework Selection
-- **[ADR-002](ADR-002-flask-extensions.md)** - Flask Extensions Strategy
-- **[ADR-003](ADR-003-frontend-technology.md)** - Frontend Technology Stack
-- **[ADR-004](ADR-004-file-based-note-storage.md)** - File-Based Note Storage
-- **[ADR-005](ADR-005-indielogin-authentication.md)** - IndieLogin Authentication
-- **[ADR-006](ADR-006-python-virtual-environment-uv.md)** - Python Virtual Environment with uv
-- **[ADR-007](ADR-007-slug-generation-algorithm.md)** - Slug Generation Algorithm
-- **[ADR-008](ADR-008-versioning-strategy.md)** - Versioning Strategy
-- **[ADR-009](ADR-009-git-branching-strategy.md)** - Git Branching Strategy
+### Foundation and process
 
-### Authentication & Authorization (ADR-010 to ADR-027)
-- **[ADR-010](ADR-010-authentication-module-design.md)** - Authentication Module Design
-- **[ADR-011](ADR-011-development-authentication-mechanism.md)** - Development Authentication Mechanism
-- **[ADR-016](ADR-016-indieauth-client-discovery.md)** - IndieAuth Client Discovery
-- **[ADR-017](ADR-017-oauth-client-metadata-document.md)** - OAuth Client Metadata Document
-- **[ADR-018](ADR-018-indieauth-detailed-logging.md)** - IndieAuth Detailed Logging
-- **[ADR-019](ADR-019-indieauth-correct-implementation.md)** - IndieAuth Correct Implementation
-- **[ADR-021](ADR-021-indieauth-provider-strategy.md)** - IndieAuth Provider Strategy
-- **[ADR-022](ADR-022-auth-route-prefix-fix.md)** - Auth Route Prefix Fix
-- **[ADR-023](ADR-023-indieauth-client-identification.md)** - IndieAuth Client Identification
-- **[ADR-024](ADR-024-static-identity-page.md)** - Static Identity Page
-- **[ADR-025](ADR-025-indieauth-pkce-authentication.md)** - IndieAuth PKCE Authentication
-- **[ADR-026](ADR-026-indieauth-token-exchange-compliance.md)** - IndieAuth Token Exchange Compliance
-- **[ADR-027](ADR-027-indieauth-authentication-endpoint-correction.md)** - IndieAuth Authentication Endpoint Correction
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [001](ADR-001-python-web-framework.md) | Python Web Framework Selection | Accepted | Flask as the web framework. |
+| [002](ADR-002-flask-extensions.md) | Flask Extensions and Dependencies | Accepted | A minimal dependency set; avoid Flask extensions where the standard library will do. |
+| [003](ADR-003-frontend-technology.md) | Front-end Technology Stack | Accepted | Server-rendered Jinja2 templates with minimal client-side code. |
+| [006](ADR-006-python-virtual-environment-uv.md) | Python Virtual Environment Management with uv | Accepted | uv manages the virtual environment and dependencies. |
+| [008](ADR-008-versioning-strategy.md) | Versioning Strategy | Accepted | Semantic Versioning, PEP 440 compatible. |
+| [009](ADR-009-git-branching-strategy.md) | Git Branching Strategy | Accepted | Simplified trunk-based development with feature branches and release tags. |
+| [012](ADR-012-flaky-test-removal.md) | Flaky Test Removal and Test Quality Standards | Accepted | Remove the multiprocessing migration tests and fix brittle assertions (done in v1.5.0). |
+| [015](ADR-015-phase-5-implementation-approach.md) | Phase 5 Implementation Approach | Accepted | Version jump 0.5.1 → 0.6.0 for Phase 5 (historical). |
+| [051](ADR-051-phase1-test-strategy.md) | Phase 1 Test Strategy and Implementation Review | Accepted | Review of the v1.1.1 Phase 1 test approach (historical). |
 
-### Error Handling & Core Features (ADR-012 to ADR-015)
-- **[ADR-012](ADR-012-http-error-handling-policy.md)** - HTTP Error Handling Policy
-- **[ADR-013](ADR-013-expose-deleted-at-in-note-model.md)** - Expose Deleted-At in Note Model
-- **[ADR-014](ADR-014-rss-feed-implementation.md)** - RSS Feed Implementation
-- **[ADR-015](ADR-015-phase-5-implementation-approach.md)** - Phase 5 Implementation Approach
+### Storage and database
 
-### Micropub & API (ADR-028 to ADR-029)
-- **[ADR-028](ADR-028-micropub-implementation.md)** - Micropub Implementation
-- **[ADR-029](ADR-029-micropub-indieauth-integration.md)** - Micropub IndieAuth Integration
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [004](ADR-004-file-based-note-storage.md) | File-Based Note Storage Architecture | Accepted | Note content in Markdown files under `data/notes/YYYY/MM/`, metadata in SQLite. |
+| [013](ADR-013-expose-deleted-at-in-note-model.md) | Expose deleted_at Field in Note Model | Accepted | `deleted_at` on the Note dataclass for soft deletes. |
+| [020](ADR-020-automatic-database-migrations.md) | Automatic Database Migration System | Accepted | Numbered SQL migrations applied at startup and tracked in a table. |
+| [031](ADR-031-database-migration-system-redesign.md) | Database Migration System Redesign | Accepted | Baseline schema first, then migrations, so existing databases upgrade (implemented via ADR-032/033). |
+| [032](ADR-032-initial-schema-sql-implementation.md) | Initial Schema SQL Implementation for Migration System | Accepted | `INITIAL_SCHEMA_SQL` holds the baseline schema. |
+| [033](ADR-033-database-migration-redesign.md) | Database Migration System Redesign | Accepted | Frozen baseline schema; every later change only in migration files (v1.1.0). |
+| [037](ADR-037-migration-race-condition-fix.md) | Database Migration Race Condition Resolution | Accepted | SQLite `BEGIN IMMEDIATE` lock with retries so several gunicorn workers don't migrate at once. |
+| [041](ADR-041-database-migration-conflict-resolution.md) | Database Migration Conflict Resolution | Accepted | Handling a production database that fell into a migration edge case. |
 
-### Database & Migrations (ADR-020, ADR-031 to ADR-037)
-- **[ADR-020](ADR-020-automatic-database-migrations.md)** - Automatic Database Migrations
-- **[ADR-031](ADR-031-database-migration-system-redesign.md)** - Database Migration System Redesign
-- **[ADR-032](ADR-032-initial-schema-sql-implementation.md)** - Initial Schema SQL Implementation
-- **[ADR-033](ADR-033-database-migration-redesign.md)** - Database Migration Redesign
-- **[ADR-037](ADR-037-migration-race-condition-fix.md)** - Migration Race Condition Fix
-- **[ADR-041](ADR-041-database-migration-conflict-resolution.md)** - Database Migration Conflict Resolution
+See also [database architecture](../architecture/database.md).
 
-### Search & Advanced Features (ADR-034 to ADR-036, ADR-038 to ADR-040)
-- **[ADR-034](ADR-034-full-text-search.md)** - Full-Text Search
-- **[ADR-035](ADR-035-custom-slugs.md)** - Custom Slugs
-- **[ADR-036](ADR-036-indieauth-token-verification-method.md)** - IndieAuth Token Verification Method
-- **[ADR-038](ADR-038-syndication-formats.md)** - Syndication Formats (ATOM, JSON Feed)
-- **[ADR-039](ADR-039-micropub-url-construction-fix.md)** - Micropub URL Construction Fix
-- **[ADR-040](ADR-040-microformats2-compliance.md)** - Microformats2 Compliance
+### Notes, slugs, media and search
 
-### Architecture Refinements (ADR-042 to ADR-044)
-- **[ADR-042](ADR-042-versioning-strategy-for-authorization-removal.md)** - Versioning Strategy for Authorization Removal
-- **[ADR-043](ADR-043-CORRECTED-indieauth-endpoint-discovery.md)** - CORRECTED IndieAuth Endpoint Discovery
-- **[ADR-044](ADR-044-endpoint-discovery-implementation.md)** - Endpoint Discovery Implementation Details
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [062](ADR-062-timestamp-based-slug-format.md) | Timestamp-Based Slug Format | Accepted | Default slugs are `YYYYMMDDHHMMSS` timestamps (v1.5.0); replaces ADR-007. |
+| [035](ADR-035-custom-slugs.md) | Custom Slugs in Micropub | Accepted* | Honour `mp-slug`, sanitized, with reserved names protected (v1.1.0). |
+| [034](ADR-034-full-text-search.md) | Full-Text Search with SQLite FTS5 | Accepted | FTS5 search over note content (v1.1.0). |
+| [057](ADR-057-media-attachment-model.md) | Media Attachment Model | Accepted | Social-media-style image attachments: up to 4 per note, ordered, with captions. |
+| [058](ADR-058-image-optimization-strategy.md) | Image Optimization Strategy | Accepted | Upload limits, automatic resizing and size variants. |
 
-### Major Architectural Changes (ADR-050 to ADR-051)
-- **[ADR-050](ADR-050-remove-custom-indieauth-server.md)** - Remove Custom IndieAuth Server
-- **[ADR-051](ADR-051-phase1-test-strategy.md)** - Phase 1 Test Strategy
+### Feeds
 
-### v1.1.1 Quality & Production Readiness (ADR-052 to ADR-055)
-- **[ADR-052](ADR-052-configuration-system-architecture.md)** - Configuration System Architecture
-- **[ADR-053](ADR-053-performance-monitoring-strategy.md)** - Performance Monitoring Strategy
-- **[ADR-054](ADR-054-structured-logging-architecture.md)** - Structured Logging Architecture
-- **[ADR-055](ADR-055-error-handling-philosophy.md)** - Error Handling Philosophy
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [014](ADR-014-rss-feed-implementation.md) | RSS Feed Implementation Strategy | Accepted* | RSS 2.0 feed; its WebSub deferral is superseded by ADR-071. |
+| [038](ADR-038-syndication-formats.md) | Multiple Syndication Format Support | Accepted | RSS, Atom and JSON Feed side by side (v1.1.2). |
+| [071](ADR-071-websub.md) | WebSub publishing with a built-in hub | Accepted | Built-in WebSub hub at `/websub` for StarPunk's own feeds (v2.10.0, amended v2.10.1). |
+| [059](ADR-059-full-feed-media-standardization.md) | Full Feed Media Standardization (Option 3) | Proposed | Full Media RSS, podcasts, video and thumbnails in feeds; not scheduled. |
 
-## ADRs by Topic
+### IndieWeb: microformats, Webmention, Micropub
 
-### Authentication & IndieAuth
-ADR-005, ADR-010, ADR-011, ADR-016, ADR-017, ADR-018, ADR-019, ADR-021, ADR-022, ADR-023, ADR-024, ADR-025, ADR-026, ADR-027, ADR-036, ADR-043, ADR-044, ADR-050
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [040](ADR-040-microformats2-compliance.md) | Strict Microformats2 Compliance | Accepted | Full h-entry, h-card and h-feed markup (v1.3.0, reviewed v2.8.0). |
+| [061](ADR-061-author-discovery.md) | Author Profile Discovery from IndieAuth | Accepted | The author h-card is read from `ADMIN_ME` and cached. |
+| [063](ADR-063-webmention-implementation.md) | Webmention Implementation | Accepted | Async receiving (202) and sending via a background worker, SSRF guard, rate limits, moderation (v1.6.0, revised up to v2.10.1). *Reconstructed.* |
+| [028](ADR-028-micropub-implementation.md) | Micropub Implementation Strategy | Accepted* | `/micropub` endpoint for creating posts (v1.0.0-rc.1); tokens now per ADR-064. |
+| [039](ADR-039-micropub-url-construction-fix.md) | Micropub URL Construction Fix | Accepted | Fix the double slash in returned post URLs. |
+| [067](ADR-067-micropub-update-delete.md) | Micropub update, delete, drafts and replies | Accepted | Micropub update, delete, drafts and replies (v2.4.0). |
+| [068](ADR-068-likes-and-reposts.md) | Likes and reposts | Accepted* | `like-of` and `repost-of` posts (v2.5.0); bookmarks were added later in v2.9.0. |
 
-### Database & Migrations
-ADR-004, ADR-020, ADR-031, ADR-032, ADR-033, ADR-037, ADR-041
+See also [IndieWeb protocols](../architecture/indieweb-protocols.md).
 
-### API & Micropub
-ADR-028, ADR-029, ADR-039
+### Crossposting (POSSE)
 
-### Content & Features
-ADR-007, ADR-013, ADR-014, ADR-034, ADR-035, ADR-038, ADR-040
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [065](ADR-065-direct-syndication-posse.md) | Direct Syndication (POSSE) to GoToSocial | Accepted | Crosspost to GoToSocial/Mastodon-API servers from a background worker (v2.1.0). |
+| [066](ADR-066-bluesky-syndication.md) | Crossposting to Bluesky | Accepted | Bluesky as a second crosspost target (v2.2.0). |
+| [069](ADR-069-threads-syndication.md) | Crossposting to Threads | Accepted | Threads as a third target, with automatic token refresh (v2.6.0). |
+| [070](ADR-070-crosspost-links-and-cards.md) | Links and link cards in crossposts | Accepted | Keep note links in crossposts and build link cards for the linked page (v2.6.3). |
 
-### Development & Operations
-ADR-001, ADR-002, ADR-003, ADR-006, ADR-008, ADR-009, ADR-012, ADR-015, ADR-042, ADR-051, ADR-052, ADR-053, ADR-054, ADR-055
+### Authentication (current)
 
-## Superseded ADRs
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [064](ADR-064-oidc-admin-login-and-builtin-indieauth-server.md) | OIDC Admin Login and Built-in IndieAuth Server | Accepted | Admin login via OIDC; StarPunk issues and verifies Micropub tokens itself (v2.0.0). |
+| [010](ADR-010-authentication-module-design.md) | Authentication Module Design | Accepted* | Single `auth.py` module and server-side sessions; the login flow is now ADR-064. |
+| [011](ADR-011-development-authentication-mechanism.md) | Development Authentication Mechanism | Accepted | `DEV_MODE` login bypass for local development only. |
+| [022](ADR-022-auth-route-prefix-fix.md) | Fix IndieAuth Callback Route Mismatch | Accepted | Auth routes live under `/auth` (v0.9.2). |
 
-These ADRs have been superseded by later decisions:
-- **ADR-030** (old) - Superseded by ADR-043 (CORRECTED IndieAuth Endpoint Discovery)
+### Operations, errors and monitoring
 
-## How to Create a New ADR
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [012](ADR-012-http-error-handling-policy.md) | HTTP Error Handling Policy | Accepted | Correct HTTP status codes (e.g. 404 for missing notes) across routes. |
+| [052](ADR-052-configuration-system-architecture.md) | Configuration System Architecture | Accepted | Environment variables with defaults, loaded in one module. |
+| [053](ADR-053-performance-monitoring-strategy.md) | Performance Monitoring Strategy | Accepted | Built-in, standard-library performance metrics (v1.1.1). |
+| [054](ADR-054-structured-logging-architecture.md) | Structured Logging Architecture | Accepted | Rotating log files with correlation IDs (v1.1.1). |
+| [055](ADR-055-error-handling-philosophy.md) | Error Handling Philosophy | Accepted | Layered handling: graceful degradation, clear user messages, detailed logs. |
+| [060](ADR-060-production-hotfix-metrics-dashboard.md) | Route Adapter for the Metrics Dashboard | Accepted | Adapt monitoring data to the dashboard template in the route (v1.1.1-rc.2). *Reconstructed.* |
+
+See also [deployment](../architecture/deployment.md).
+
+## Superseded decisions
+
+Kept for history. Most concern the IndieLogin.com and external-IndieAuth
+designs of v0.x–v1.6.0, all replaced by ADR-064 in v2.0.0.
+
+| ADR | Title | Status | Summary |
+|---|---|---|---|
+| [005](ADR-005-indielogin-authentication.md) | IndieLogin Authentication Integration | Superseded by 064 | Admin login through indielogin.com. |
+| [007](ADR-007-slug-generation-algorithm.md) | Slug Generation Algorithm | Superseded by 062 | Slugs from the first words of the note. |
+| [016](ADR-016-indieauth-client-discovery.md) | IndieAuth Client Discovery Mechanism | Superseded by 019 | h-app markup for client discovery. |
+| [017](ADR-017-oauth-client-metadata-document.md) | OAuth Client ID Metadata Document Implementation | Superseded by 019 | OAuth client metadata endpoint. |
+| [018](ADR-018-indieauth-detailed-logging.md) | IndieAuth Detailed Logging Strategy | Superseded by 064 | Redacted HTTP logging of the IndieAuth login flow. |
+| [019](ADR-019-indieauth-correct-implementation.md) | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 025 | Draft of the IndieLogin.com PKCE flow. |
+| [021](ADR-021-indieauth-provider-strategy.md) | IndieAuth Provider Strategy | Superseded by 064 | Keep IndieLogin.com for admin login. |
+| [023](ADR-023-indieauth-client-identification.md) | IndieAuth Client Identification Strategy | Superseded by 064 | Visible h-app in the footer. |
+| [024](ADR-024-static-identity-page.md) | Static HTML Identity Pages for IndieAuth | Superseded by 064 | Standalone identity page pointing at indieauth.com. |
+| [025](ADR-025-indieauth-pkce-authentication.md) | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 064 | IndieLogin.com authentication with PKCE. |
+| [026](ADR-026-indieauth-token-exchange-compliance.md) | IndieAuth Token Exchange Compliance | Superseded by 064 | Token exchange parameters for the IndieAuth login. |
+| [027](ADR-027-indieauth-authentication-endpoint-correction.md) | IndieAuth Authentication Endpoint Correction | Superseded by 064 | Use the authentication (not token) endpoint for login. |
+| [029](ADR-029-micropub-indieauth-integration.md) | Micropub IndieAuth Integration Strategy | Superseded by 050, 064 | Built-in token endpoint for Micropub (v1.0.0-rc.1). |
+| [030](ADR-030-external-token-verification-architecture.md) | External Token Verification Architecture | Superseded by 043, 064 | Verify Micropub tokens at a configured external endpoint. |
+| [036](ADR-036-indieauth-token-verification-method.md) | IndieAuth Token Verification Method Diagnosis | Superseded by 064 | How to call the external token endpoint. |
+| [042](ADR-042-versioning-strategy-for-authorization-removal.md) | Versioning Strategy for Authorization Server Removal | Accepted (historical) | Remove the authorization server in 1.0.0-rc.4 rather than in a later release. |
+| [043](ADR-043-CORRECTED-indieauth-endpoint-discovery.md) | IndieAuth Endpoint Discovery Architecture | Superseded by 064 | Discover the token endpoint from `ADMIN_ME` to verify tokens. |
+| [044](ADR-044-endpoint-discovery-implementation.md) | IndieAuth Endpoint Discovery Implementation Details | Superseded by 064 | Implementation details of ADR-043. |
+| [050](ADR-050-remove-custom-indieauth-server.md) | Remove Custom IndieAuth Server | Superseded by 064 | Remove the built-in authorization and token server (done in v1.0.0-rc.4). |
+| [056](ADR-056-no-selfhosted-indieauth.md) | Use External IndieAuth Provider (Never Self-Host) | Superseded by 064 | Never run an IndieAuth server in StarPunk. |
+
+ADR-042 is listed here because it only matters together with ADR-050; it
+was carried out and is not itself superseded.
+
+## Numbering
+
+- **Gap ADR-045 to ADR-049**: never used; no document or code refers to
+  them.
+- **Two ADR-012 files**: `ADR-012-http-error-handling-policy.md` and
+  `ADR-012-flaky-test-removal.md` (added 2025-12-16). Both are cited as
+  plain "ADR-012": `starpunk/routes/admin.py` and early CHANGELOG entries
+  mean the error policy, `tests/test_migration_race_condition.py` means
+  the flaky-test one. Not renumbered, since other documents link to them.
+- **Old numbers in headings**: several files were renumbered without
+  updating their first heading: ADR-037 and ADR-038 say "ADR-022",
+  ADR-040 says "ADR-023", ADR-042 says "ADR-027", ADR-044 says "ADR-031".
+  Older CHANGELOG entries use those old numbers ("ADR-022: Migration Race
+  Condition Fix" is ADR-037; "ADR-031: IndieAuth Endpoint Discovery" is
+  ADR-044). The file name is authoritative.
+- **ADR-060** was deleted in the v1.1.1-rc.2 review and reconstructed on
+  2026-11-03 because code still cites it. ADR-059 also mentions a planned
+  "Option 2 (ADR-060)" for Media RSS that was never written.
+- **ADR-063** was lost with the uncommitted v1.6.0 docs and reconstructed
+  on 2026-11-03.
+- **ADR-064 used twice**: v1.6.0 code (`starpunk/rate_limiter.py`,
+  `starpunk/routes/webmention.py`) cites a lost "ADR-064: Webmention Rate
+  Limiting"; the number was reused in v2.0.0 for OIDC login. The rate-limit
+  decision is recorded in ADR-063, Decision 10.
+
+## How to create a new ADR
+
+1. Use the next number after the highest existing one (currently ADR-072).
+2. Name it `ADR-NNN-brief-descriptive-title.md`.
+3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071):
 
-1. **Find the next sequential number**: Check the highest existing ADR number
-2. **Use the naming format**: `ADR-NNN-brief-descriptive-title.md`
-3. **Follow the template**:
    ```markdown
    # ADR-NNN: Title
 
    ## Status
-   Proposed | Accepted | Deprecated | Superseded
+
+   Accepted (vX.Y.Z, YYYY-MM-DD)
 
    ## Context
-   Why are we making this decision?
 
    ## Decision
-   What have we decided to do?
 
    ## Consequences
-   What are the positive and negative consequences?
 
-   ## Alternatives Considered
-   What other options did we evaluate?
+   ## Alternatives considered
    ```
-4. **Update this index** with the new ADR
 
-## Related Documentation
-- **[../architecture/](../architecture/)** - Architectural overviews and system design
-- **[../design/](../design/)** - Detailed design documents
-- **[../standards/](../standards/)** - Coding standards and conventions
+4. When a decision replaces an earlier one, change the earlier ADR's Status
+   to "Superseded by ADR-NNN" with a one-line note; don't rewrite its body.
+5. Add the ADR to this index.
+
+## Related documentation
+
+- [../architecture/](../architecture/) — current system design
+- [../design/](../design/) — per-version implementation designs
+- [../standards/](../standards/) — coding and documentation standards
+- [../../CHANGELOG.md](../../CHANGELOG.md) — what changed in each release
 
 ---
 
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
-**Total ADRs**: 55
+**Last Updated**: 2026-11-03
+**Total ADR files**: 67
diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md
index 503ee63..72c4b91 100644
--- a/docs/design/INDEX.md
+++ b/docs/design/INDEX.md
@@ -1,128 +1,428 @@
 # Design Documentation Index
 
-This directory contains detailed design documents, feature specifications, and phase implementation plans for StarPunk CMS.
+Implementation designs, developer questions and architect answers,
+implementation reports (`YYYY-MM-DD-description.md`) and reviews, one
+folder per release (see `docs/DOCUMENTATION.md`). Current system design
+is in `../architecture/`; decisions are in `../decisions/` (ADRs).
 
-## Project Structure
-- **[project-structure.md](project-structure.md)** - Overall project structure and organization
-- **[initial-files.md](initial-files.md)** - Initial file structure for the project
+## Notes
 
-## Phase Implementation Plans
+- v1.6.0 (webmentions) was deployed but never committed; its code was
+  recovered from the production image on 2026-10-31 (commit `d3fa5b7`). Its
+  documents and tests were not in the image. The five v1.6.0 documents the
+  code cites were reconstructed from the implementation.
+- Releases from v2.0.1 on that had no folder have a short implementation
+  report reconstructed from the changelog and git history.
+- Documents marked *(reconstructed)* were written on 2026-11-03 after the fact.
+- Every release from v2.0.0 on has a folder. Of the v1 releases, v1.0.1
+  and v1.1.0 have none: their documents are in `v1.1.1/` (and the v1.0.1
+  hotfix plan in `v1.0.0/`).
+- Description = the document's title.
 
-### Phase 1: Foundation
-- **[phase-1.1-core-utilities.md](phase-1.1-core-utilities.md)** - Core utility functions and helpers
-- **[phase-1.1-quick-reference.md](phase-1.1-quick-reference.md)** - Quick reference for Phase 1.1
-- **[phase-1.2-data-models.md](phase-1.2-data-models.md)** - Data models and database schema
-- **[phase-1.2-quick-reference.md](phase-1.2-quick-reference.md)** - Quick reference for Phase 1.2
+## Contents
 
-### Phase 2: Core Features
-- **[phase-2.1-notes-management.md](phase-2.1-notes-management.md)** - Notes CRUD functionality
-- **[phase-2.1-quick-reference.md](phase-2.1-quick-reference.md)** - Quick reference for Phase 2.1
+[v1.0.0](#v100) · [v1.1.1](#v111) · [v1.1.2](#v112) · [v1.2.0](#v120) · [v1.3.0](#v130) · [v1.3.1](#v131) · [v1.4.0](#v140) · [v1.4.1](#v141) · [v1.4.2](#v142) · [v1.5.0](#v150) · [v1.6.0](#v160) · [v2.0.0](#v200) · [v2.0.1](#v201) · [v2.0.2](#v202) · [v2.1.0](#v210) · [v2.2.0](#v220) · [v2.3.0](#v230) · [v2.3.1](#v231) · [v2.3.2](#v232) · [v2.3.3](#v233) · [v2.4.0](#v240) · [v2.5.0](#v250) · [v2.6.0](#v260) · [v2.6.1](#v261) · [v2.6.2](#v262) · [v2.6.3](#v263) · [v2.6.4](#v264) · [v2.6.5](#v265) · [v2.6.6](#v266) · [v2.6.7](#v267) · [v2.6.8](#v268) · [v2.6.9](#v269) · [v2.7.0](#v270) · [v2.7.1](#v271) · [v2.7.2](#v272) · [v2.8.0](#v280) · [v2.8.1](#v281) · [v2.9.0](#v290) · [v2.10.0](#v2100) · [v2.10.1](#v2101) · [hotfix](#hotfix)
 
-### Phase 3: Authentication
-- **[phase-3-authentication.md](phase-3-authentication.md)** - Authentication system design
-- **[phase-3-authentication-implementation.md](phase-3-authentication-implementation.md)** - Implementation details
-- **[indieauth-pkce-authentication.md](indieauth-pkce-authentication.md)** - IndieAuth PKCE authentication design
+## v1.0.0
 
-### Phase 4: Web Interface
-- **[phase-4-web-interface.md](phase-4-web-interface.md)** - Web interface design
-- **[phase-4-quick-reference.md](phase-4-quick-reference.md)** - Quick reference for Phase 4
-- **[phase-4-error-handling-fix.md](phase-4-error-handling-fix.md)** - Error handling improvements
+V1 foundation: phases 1–5 (utilities, models, notes, auth, web UI, RSS, container), Micropub, migrations, IndieAuth fixes and the release candidates.
 
-### Phase 5: RSS & Deployment
-- **[phase-5-rss-and-container.md](phase-5-rss-and-container.md)** - RSS feed and container deployment
-- **[phase-5-executive-summary.md](phase-5-executive-summary.md)** - Executive summary of Phase 5
-- **[phase-5-quick-reference.md](phase-5-quick-reference.md)** - Quick reference for Phase 5
+- [2025-11-18-auth-redirect-loop-fix.md](v1.0.0/2025-11-18-auth-redirect-loop-fix.md) — Auth Redirect Loop Fix - Implementation Report
+- [2025-11-18-quickfix-auth-loop.md](v1.0.0/2025-11-18-quickfix-auth-loop.md) — QUICK FIX: Auth Redirect Loop
+- [2025-11-19-container-implementation-summary.md](v1.0.0/2025-11-19-container-implementation-summary.md) — Phase 5 Containerization - Implementation Complete
+- [2025-11-19-migration-implementation-quick-reference.md](v1.0.0/2025-11-19-migration-implementation-quick-reference.md) — Migration System - Quick Reference Card
+- [2025-11-19-migration-system-implementation-guidance.md](v1.0.0/2025-11-19-migration-system-implementation-guidance.md) — Migration System Implementation Guidance
+- [2025-11-19-migration-system-implementation-report.md](v1.0.0/2025-11-19-migration-system-implementation-report.md) — Migration System Implementation Report
+- [2025-11-19-todo-test-updates.md](v1.0.0/2025-11-19-todo-test-updates.md) — Test Updates Required for ADR-019 Implementation
+- [2025-11-22-auth-route-prefix-fix.md](v1.0.0/2025-11-22-auth-route-prefix-fix.md) — Auth Route Prefix Fix Implementation Report
+- [2025-11-22-authorization-endpoint-fix.md](v1.0.0/2025-11-22-authorization-endpoint-fix.md) — IndieAuth Authentication Endpoint Correction
+- [2025-11-22-grant-type-fix.md](v1.0.0/2025-11-22-grant-type-fix.md) — IndieAuth Token Exchange grant_type Fix
+- [2025-11-24-endpoint-discovery-analysis.md](v1.0.0/2025-11-24-endpoint-discovery-analysis.md) — IndieAuth Endpoint Discovery Implementation Analysis
+- [2025-11-24-indieauth-removal-complete.md](v1.0.0/2025-11-24-indieauth-removal-complete.md) — IndieAuth Server Removal - Complete Implementation Report
+- [2025-11-24-migration-detection-hotfix-rc3.md](v1.0.0/2025-11-24-migration-detection-hotfix-rc3.md) — Migration Detection Hotfix - v1.0.0-rc.3
+- [2025-11-24-migration-fix-v1.0.0-rc.2.md](v1.0.0/2025-11-24-migration-fix-v1.0.0-rc.2.md) — Implementation Report: Migration Fix for v1.0.0-rc.2
+- [2025-11-24-phase1-indieauth-server-removal.md](v1.0.0/2025-11-24-phase1-indieauth-server-removal.md) — Phase 1: IndieAuth Authorization Server Removal - Implementation Report
+- [2025-11-24-v1.0.0-rc.5-implementation.md](v1.0.0/2025-11-24-v1.0.0-rc.5-implementation.md) — v1.0.0-rc.5 Implementation Report
+- [ADR-025-implementation-report.md](v1.0.0/ADR-025-implementation-report.md) — ADR-025 Implementation Report
+- [ADR-025-implementation-summary.md](v1.0.0/ADR-025-implementation-summary.md) — ADR-025 Implementation Summary
+- [ADR-025-versioning-guidance.md](v1.0.0/ADR-025-versioning-guidance.md) — ADR-019 Implementation: Versioning Guidance
+- [ARCHITECT-FINAL-ANALYSIS.md](v1.0.0/ARCHITECT-FINAL-ANALYSIS.md) — Architect Final Analysis - Delete Route 404 Fix
+- [container-deployment.md](v1.0.0/container-deployment.md) — StarPunk Container Deployment Guide
+- [custom-slug-bug-diagnosis.md](v1.0.0/custom-slug-bug-diagnosis.md) — Custom Slug Bug Diagnosis Report
+- [custom-slug-bug-implementation.md](v1.0.0/custom-slug-bug-implementation.md) — Custom Slug Bug Fix - Implementation Report
+- [database-migration-architecture.md](v1.0.0/database-migration-architecture.md) — Database Migration Architecture
+- [database-migration-conflict-diagnosis.md](v1.0.0/database-migration-conflict-diagnosis.md) — Database Migration Conflict Diagnosis Report
+- [delete-nonexistent-note-error-analysis.md](v1.0.0/delete-nonexistent-note-error-analysis.md) — Delete Nonexistent Note Error Analysis
+- [delete-route-404-fix-implementation.md](v1.0.0/delete-route-404-fix-implementation.md) — Delete Route 404 Fix - Implementation Report
+- [delete-route-fix-summary.md](v1.0.0/delete-route-fix-summary.md) — Delete Route Fix - Developer Summary
+- [delete-route-implementation-spec.md](v1.0.0/delete-route-implementation-spec.md) — Delete Route Implementation Specification
+- [dependencies-diagram.md](v1.0.0/dependencies-diagram.md) — StarPunk V1 Dependencies Diagram
+- [endpoint-discovery-answers.md](v1.0.0/endpoint-discovery-answers.md) — IndieAuth Endpoint Discovery: Definitive Implementation Answers
+- [error-handling-rest-vs-web-patterns.md](v1.0.0/error-handling-rest-vs-web-patterns.md) — Architectural Review: Error Handling in Web Routes
+- [feature-scope.md](v1.0.0/feature-scope.md) — StarPunk V1 Feature Scope
+- [fix-hardcoded-endpoints.md](v1.0.0/fix-hardcoded-endpoints.md) — Migration Guide: Fixing Hardcoded IndieAuth Endpoints
+- [identity-domain-validation-2025-11-19.md](v1.0.0/identity-domain-validation-2025-11-19.md) — Identity Domain Validation Report
+- [identity-page-customization-guide.md](v1.0.0/identity-page-customization-guide.md) — IndieAuth Identity Page Customization Guide
+- [identity-page.html](v1.0.0/identity-page.html) — Example IndieAuth identity page (HTML template)
+- [implementation-guide-expose-deleted-at.md](v1.0.0/implementation-guide-expose-deleted-at.md) — Implementation Guide: Expose deleted_at in Note Model
+- [implementation-plan.md](v1.0.0/implementation-plan.md) — StarPunk V1 Implementation Plan
+- [indieauth-assessment.md](v1.0.0/indieauth-assessment.md) — IndieAuth Architecture Assessment
+- [indieauth-client-diagnosis.md](v1.0.0/indieauth-client-diagnosis.md) — IndieAuth Client Registration Issue - Diagnosis Report
+- [indieauth-client-discovery-analysis.md](v1.0.0/indieauth-client-discovery-analysis.md) — IndieAuth Client Discovery Error - Architectural Analysis
+- [indieauth-client-discovery-fix-implementation.md](v1.0.0/indieauth-client-discovery-fix-implementation.md) — IndieAuth Client Discovery Fix - Implementation Report
+- [indieauth-client-discovery-root-cause-analysis.md](v1.0.0/indieauth-client-discovery-root-cause-analysis.md) — IndieAuth Client Discovery Root Cause Analysis
+- [indieauth-detailed-logging-implementation.md](v1.0.0/indieauth-detailed-logging-implementation.md) — IndieAuth Detailed Logging Implementation Report
+- [indieauth-endpoint-discovery-security.md](v1.0.0/indieauth-endpoint-discovery-security.md) — IndieAuth Endpoint Discovery Security Analysis
+- [indieauth-endpoint-discovery.md](v1.0.0/indieauth-endpoint-discovery.md) — IndieAuth Endpoint Discovery Architecture
+- [indieauth-fix-summary.md](v1.0.0/indieauth-fix-summary.md) — IndieAuth Authentication Fix - Quick Summary
+- [indieauth-identity-page.md](v1.0.0/indieauth-identity-page.md) — IndieAuth Identity Page Architecture
+- [indieauth-questions-answered.md](v1.0.0/indieauth-questions-answered.md) — IndieAuth Implementation Questions - Answered
+- [indieauth-removal-analysis.md](v1.0.0/indieauth-removal-analysis.md) — IndieAuth Removal Implementation Analysis
+- [indieauth-removal-architectural-review.md](v1.0.0/indieauth-removal-architectural-review.md) — Architectural Review: IndieAuth Authorization Server Removal
+- [indieauth-removal-implementation-guide.md](v1.0.0/indieauth-removal-implementation-guide.md) — IndieAuth Provider Removal - Implementation Guide
+- [indieauth-removal-phases.md](v1.0.0/indieauth-removal-phases.md) — IndieAuth Removal: Phased Implementation Guide
+- [indieauth-removal-plan.md](v1.0.0/indieauth-removal-plan.md) — IndieAuth Server Removal Plan
+- [indieauth-removal-questions.md](v1.0.0/indieauth-removal-questions.md) — IndieAuth Removal - Questions for Architect
+- [indieauth-spec-url-standardization-2025-11-24.md](v1.0.0/indieauth-spec-url-standardization-2025-11-24.md) — IndieAuth Specification URL Standardization Report
+- [indieauth-token-verification-diagnosis.md](v1.0.0/indieauth-token-verification-diagnosis.md) — IndieAuth Token Verification Diagnosis
+- [initial-files.md](v1.0.0/initial-files.md) — Initial Project Files Design
+- [initial-schema-implementation-guide.md](v1.0.0/initial-schema-implementation-guide.md) — Initial Schema SQL Implementation Guide
+- [initial-schema-quick-reference.md](v1.0.0/initial-schema-quick-reference.md) — INITIAL_SCHEMA_SQL Quick Reference
+- [micropub-401-diagnosis.md](v1.0.0/micropub-401-diagnosis.md) — Micropub 401 Unauthorized Error - Architectural Diagnosis
+- [micropub-endpoint-design.md](v1.0.0/micropub-endpoint-design.md) — Micropub Endpoint Design for StarPunk V1
+- [micropub-phase1-architecture-review.md](v1.0.0/micropub-phase1-architecture-review.md) — Micropub V1 Implementation - Phase 1 Architecture Review
+- [micropub-phase3-architecture-review.md](v1.0.0/micropub-phase3-architecture-review.md) — Micropub Phase 3 Implementation Architecture Review
+- [micropub-v1-implementation-progress.md](v1.0.0/micropub-v1-implementation-progress.md) — Micropub V1 Implementation Progress Report
+- [migration-failure-diagnosis-v1.0.0-rc.1.md](v1.0.0/migration-failure-diagnosis-v1.0.0-rc.1.md) — Migration Failure Diagnosis - v1.0.0-rc.1
+- [migration-fix-quick-reference.md](v1.0.0/migration-fix-quick-reference.md) — Migration Race Condition Fix - Quick Implementation Reference
+- [migration-race-condition-answers.md](v1.0.0/migration-race-condition-answers.md) — Migration Race Condition Fix - Architectural Answers
+- [migration-race-condition-fix-implementation.md](v1.0.0/migration-race-condition-fix-implementation.md) — Migration Race Condition Fix - Implementation Guide
+- [oauth-metadata-implementation-2025-11-19.md](v1.0.0/oauth-metadata-implementation-2025-11-19.md) — OAuth Client ID Metadata Document Implementation Report
+- [phase-1.1-core-utilities.md](v1.0.0/phase-1.1-core-utilities.md) — Phase 1.1: Core Utilities Design
+- [phase-1.1-quick-reference.md](v1.0.0/phase-1.1-quick-reference.md) — Phase 1.1 Quick Reference: Core Utilities
+- [phase-1.2-data-models.md](v1.0.0/phase-1.2-data-models.md) — Phase 1.2: Data Models Design
+- [phase-1.2-quick-reference.md](v1.0.0/phase-1.2-quick-reference.md) — Phase 1.2 Quick Reference: Data Models
+- [phase-2-architectural-review.md](v1.0.0/phase-2-architectural-review.md) — Architectural Review: Phase 2 Implementation
+- [phase-2-implementation-report.md](v1.0.0/phase-2-implementation-report.md) — Phase 2 Implementation Report: Authorization and Token Endpoints
+- [phase-2.1-implementation-20251118.md](v1.0.0/phase-2.1-implementation-20251118.md) — Phase 2.1 Implementation Report: Notes Management
+- [phase-2.1-notes-management.md](v1.0.0/phase-2.1-notes-management.md) — Phase 2.1: Notes Management Design
+- [phase-2.1-quick-reference.md](v1.0.0/phase-2.1-quick-reference.md) — Phase 2.1: Notes Management - Quick Reference
+- [phase-3-authentication-20251118.md](v1.0.0/phase-3-authentication-20251118.md) — Phase 3: Authentication Implementation Report
+- [phase-3-authentication-architectural-review.md](v1.0.0/phase-3-authentication-architectural-review.md) — Phase 3: Authentication Implementation - Architectural Review
+- [phase-3-authentication-implementation.md](v1.0.0/phase-3-authentication-implementation.md) — Phase 3: Authentication Implementation Design
+- [phase-3-authentication.md](v1.0.0/phase-3-authentication.md) — Phase 3: Authentication Design
+- [phase-4-architectural-assessment-20251118.md](v1.0.0/phase-4-architectural-assessment-20251118.md) — Phase 4: Architectural Assessment and Design Report
+- [phase-4-error-handling-fix.md](v1.0.0/phase-4-error-handling-fix.md) — Phase 4: Error Handling Fix - Implementation Guide
+- [phase-4-quick-reference.md](v1.0.0/phase-4-quick-reference.md) — Phase 4: Quick Reference
+- [phase-4-test-fixes.md](v1.0.0/phase-4-test-fixes.md) — Phase 4 Test Fixes Report
+- [phase-4-web-interface.md](v1.0.0/phase-4-web-interface.md) — Phase 4: Web Interface - Implementation Design
+- [phase-5-approval-summary.md](v1.0.0/phase-5-approval-summary.md) — Phase 5 Containerization - Approval Summary
+- [phase-5-container-architectural-review.md](v1.0.0/phase-5-container-architectural-review.md) — Phase 5 Containerization - Architectural Review
+- [phase-5-container-implementation-report.md](v1.0.0/phase-5-container-implementation-report.md) — Phase 5 Container Implementation Report
+- [phase-5-executive-summary.md](v1.0.0/phase-5-executive-summary.md) — Phase 5 Executive Summary
+- [phase-5-pre-implementation-review.md](v1.0.0/phase-5-pre-implementation-review.md) — Phase 5 Pre-Implementation Review
+- [phase-5-quick-reference.md](v1.0.0/phase-5-quick-reference.md) — Phase 5 Quick Reference Guide
+- [phase-5-rss-and-container.md](v1.0.0/phase-5-rss-and-container.md) — Phase 5: RSS Feed & Production Container - Implementation Design
+- [phase-5-rss-implementation-20251119.md](v1.0.0/phase-5-rss-implementation-20251119.md) — Phase 5: RSS Feed Implementation Report
+- [phase-5-validation-report.md](v1.0.0/phase-5-validation-report.md) — Phase 5 RSS Feed Implementation - Architectural Validation Report
+- [phase1-completion-guide.md](v1.0.0/phase1-completion-guide.md) — Phase 1 Completion Guide: Test Cleanup and Commit
+- [project-structure.md](v1.0.0/project-structure.md) — Project Structure Design
+- [quick-reference.md](v1.0.0/quick-reference.md) — StarPunk V1 Quick Reference
+- [review-v1.0.0-rc.5.md](v1.0.0/review-v1.0.0-rc.5.md) — Architectural Review: v1.0.0-rc.5 Implementation
+- [setup-complete-2025-11-18.md](v1.0.0/setup-complete-2025-11-18.md) — StarPunk Project Setup - Complete
+- [test-failure-analysis-deleted-at-attribute.md](v1.0.0/test-failure-analysis-deleted-at-attribute.md) — Test Failure Analysis: Missing `deleted_at` Attribute on Note Model
+- [troubleshooting.md](v1.0.0/troubleshooting.md) — StarPunk Troubleshooting Guide
+- [v0.9.1-implementation-report.md](v1.0.0/v0.9.1-implementation-report.md) — StarPunk v0.9.1 Implementation Report
+- [v1-planning-overview.md](v1.0.0/v1-planning-overview.md) — StarPunk V1 Project Plan
+- [v1.0.0-rc.1-hotfix-instructions.md](v1.0.0/v1.0.0-rc.1-hotfix-instructions.md) — v1.0.0-rc.1 Production Hotfix Instructions
+- [v1.0.0-rc.5-migration-race-condition-implementation.md](v1.0.0/v1.0.0-rc.5-migration-race-condition-implementation.md) — v1.0.0-rc.5 Migration Race Condition Fix - Implementation Report
+- [v1.0.0-release-validation.md](v1.0.0/v1.0.0-release-validation.md) — StarPunk v1.0.0 Release Validation Report
+- [v1.0.1-hotfix-plan.md](v1.0.0/v1.0.1-hotfix-plan.md) — StarPunk v1.0.1 Hotfix Release Plan
 
-## Feature-Specific Design
+## v1.1.1
 
-### Micropub API
-- **[micropub-endpoint-design.md](micropub-endpoint-design.md)** - Micropub endpoint detailed design
+v1.1.0 "SearchLight" (search) and v1.1.1 "Polish" designs and reports; v1.0.1 hotfix.
 
-### Authentication Fixes
-- **[auth-redirect-loop-diagnosis.md](auth-redirect-loop-diagnosis.md)** - Diagnosis of redirect loop issues
-- **[auth-redirect-loop-diagram.md](auth-redirect-loop-diagram.md)** - Visual diagrams of the problem
-- **[auth-redirect-loop-executive-summary.md](auth-redirect-loop-executive-summary.md)** - Executive summary
-- **[auth-redirect-loop-fix-implementation.md](auth-redirect-loop-fix-implementation.md)** - Implementation guide
+- [2025-11-25-hotfix-v1.1.1-rc.2-implementation.md](v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md) — Implementation Report: Hotfix v1.1.1-rc.2 - Admin Dashboard Route Conflict
+- [2025-11-25-v1.0.1-micropub-url-fix.md](v1.1.1/2025-11-25-v1.0.1-micropub-url-fix.md) — v1.0.1 Hotfix Implementation Report
+- [auth-redirect-loop-diagnosis.md](v1.1.1/auth-redirect-loop-diagnosis.md) — Authentication Redirect Loop Diagnosis - Phase 4
+- [auth-redirect-loop-diagram.md](v1.1.1/auth-redirect-loop-diagram.md) — Auth Redirect Loop - Visual Diagram
+- [auth-redirect-loop-executive-summary.md](v1.1.1/auth-redirect-loop-executive-summary.md) — Auth Redirect Loop - Executive Summary
+- [auth-redirect-loop-fix-implementation.md](v1.1.1/auth-redirect-loop-fix-implementation.md) — Implementation Guide: Auth Redirect Loop Fix
+- [hotfix-v1.1.1-rc2-consolidated.md](v1.1.1/hotfix-v1.1.1-rc2-consolidated.md) — Hotfix Design: v1.1.1-rc.2 - Metrics Dashboard Template Data Mismatch
+- [hotfix-v1.1.1-rc2-review.md](v1.1.1/hotfix-v1.1.1-rc2-review.md) — Architectural Review: Hotfix v1.1.1-rc.2
+- [hotfix-v1.1.1-rc2-route-conflict.md](v1.1.1/hotfix-v1.1.1-rc2-route-conflict.md) — Hotfix Design: v1.1.1-rc.2 Route Conflict Resolution
+- [hotfix-validation-script.md](v1.1.1/hotfix-validation-script.md) — Hotfix Validation Script for v1.1.1-rc.2
+- [indieauth-pkce-authentication.md](v1.1.1/indieauth-pkce-authentication.md) — IndieAuth PKCE Authentication - Technical Design
+- [potential-features.md](v1.1.1/potential-features.md) — StarPunk V1.1: Potential Features
+- [priority-work.md](v1.1.1/priority-work.md) — StarPunk v1.1.0: Priority Work Items
+- [syndication-features.md](v1.1.1/syndication-features.md) — Syndication Features Specification
+- [token-security-migration.md](v1.1.1/token-security-migration.md) — Token Security Migration Strategy
+- [upgrade-to-v1.1.1.md](v1.1.1/upgrade-to-v1.1.1.md) — Upgrade Guide: StarPunk v1.1.1 "Polish"
+- [v1.1.0-feature-architecture.md](v1.1.1/v1.1.0-feature-architecture.md) — StarPunk v1.1.0 Feature Architecture
+- [v1.1.0-implementation-decisions.md](v1.1.1/v1.1.0-implementation-decisions.md) — V1.1.0 Implementation Decisions - Architectural Guidance
+- [v1.1.0-implementation-plan.md](v1.1.1/v1.1.0-implementation-plan.md) — StarPunk v1.1.0 Implementation Plan
+- [v1.1.0-implementation-report.md](v1.1.1/v1.1.0-implementation-report.md) — StarPunk v1.1.0 Implementation Report
+- [v1.1.0-release-status.md](v1.1.1/v1.1.0-release-status.md) — StarPunk v1.1.0 "SearchLight" Release Status
+- [v1.1.0-search-ui-validation.md](v1.1.1/v1.1.0-search-ui-validation.md) — StarPunk v1.1.0 Search UI Implementation Review
+- [v1.1.0-validation-report.md](v1.1.1/v1.1.0-validation-report.md) — StarPunk v1.1.0 Implementation Validation & Search UI Design
+- [v1.1.1-architecture-overview.md](v1.1.1/v1.1.1-architecture-overview.md) — v1.1.1 "Polish" Architecture Overview
+- [v1.1.1-final-release-review.md](v1.1.1/v1.1.1-final-release-review.md) — StarPunk v1.1.1 "Polish" - Final Architectural Release Review
+- [v1.1.1-instrumentation-assessment.md](v1.1.1/v1.1.1-instrumentation-assessment.md) — v1.1.1 Performance Monitoring Instrumentation Assessment
+- [v1.1.1-phase1-architectural-review.md](v1.1.1/v1.1.1-phase1-architectural-review.md) — StarPunk v1.1.1 Phase 1 - Architectural Review Report
+- [v1.1.1-phase1-implementation.md](v1.1.1/v1.1.1-phase1-implementation.md) — StarPunk v1.1.1 Phase 1 Implementation Report
+- [v1.1.1-phase2-architectural-review.md](v1.1.1/v1.1.1-phase2-architectural-review.md) — StarPunk v1.1.1 "Polish" - Phase 2 Architectural Review
+- [v1.1.1-phase2-implementation.md](v1.1.1/v1.1.1-phase2-implementation.md) — StarPunk v1.1.1 "Polish" - Phase 2 Implementation Report
+- [v1.1.1-phase3-implementation.md](v1.1.1/v1.1.1-phase3-implementation.md) — StarPunk v1.1.1 "Polish" - Phase 3 Implementation Report
 
-### Database Schema
-- **[initial-schema-implementation-guide.md](initial-schema-implementation-guide.md)** - Schema implementation guide
-- **[initial-schema-quick-reference.md](initial-schema-quick-reference.md)** - Quick reference
+## v1.1.2
 
-### Security
-- **[token-security-migration.md](token-security-migration.md)** - Token security improvements
+v1.1.2 "Syndicate": metrics, ATOM/JSON feeds, feed statistics, OPML.
 
-## Version-Specific Design
+- [2025-11-26-phase2-architect-review.md](v1.1.2/2025-11-26-phase2-architect-review.md) — Architectural Review: StarPunk v1.1.2 Phase 2 "Syndicate" - Feed Formats
+- [2025-11-26-v1.1.2-phase1-review.md](v1.1.2/2025-11-26-v1.1.2-phase1-review.md) — StarPunk v1.1.2 Phase 1 Implementation Review
+- [2025-11-26-v1.1.2-phase2-complete.md](v1.1.2/2025-11-26-v1.1.2-phase2-complete.md) — StarPunk v1.1.2 Phase 2 Feed Formats - Implementation Report (COMPLETE)
+- [2025-11-26-v1.1.2-phase2-feed-formats-partial.md](v1.1.2/2025-11-26-v1.1.2-phase2-feed-formats-partial.md) — StarPunk v1.1.2 Phase 2 Feed Formats - Implementation Report (Partial)
+- [2025-11-27-phase3-architect-review.md](v1.1.2/2025-11-27-phase3-architect-review.md) — StarPunk v1.1.2 Phase 3 - Architectural Review
+- [2025-11-27-v1.1.2-phase3-complete.md](v1.1.2/2025-11-27-v1.1.2-phase3-complete.md) — v1.1.2 Phase 3 Implementation Report - Feed Statistics & OPML
+- [2025-11-28-v1.1.2-rc.1-architect-review.md](v1.1.2/2025-11-28-v1.1.2-rc.1-architect-review.md) — Architect Review: v1.1.2-rc.1 Production Issues
+- [2025-11-28-v1.1.2-rc.1-production-issues.md](v1.1.2/2025-11-28-v1.1.2-rc.1-production-issues.md) — v1.1.2-rc.1 Production Issues Investigation Report
+- [2025-11-28-v1.1.2-rc.2-fixes.md](v1.1.2/2025-11-28-v1.1.2-rc.2-fixes.md) — v1.1.2-rc.2 Production Bug Fixes - Implementation Report
+- [feed-media-handling-options.md](v1.1.2/feed-media-handling-options.md) — Feed Media Handling: Architecture Options Analysis
+- [feed-media-option2-design.md](v1.1.2/feed-media-option2-design.md) — Feed Media Enhancement Design: Option 2 (RSS + Media RSS Extension)
+- [upgrade-to-v1.1.2.md](v1.1.2/upgrade-to-v1.1.2.md) — Upgrade Guide: StarPunk v1.1.2 "Syndicate"
+- [v1.1.2-caption-alttext-update.md](v1.1.2/v1.1.2-caption-alttext-update.md) — Caption Display Update - Alt Text Only (v1.1.2)
+- [v1.1.2-options.md](v1.1.2/v1.1.2-options.md) — StarPunk v1.1.2 Release Plan Options
+- [v1.1.2-phase1-metrics-implementation.md](v1.1.2/v1.1.2-phase1-metrics-implementation.md) — StarPunk v1.1.2 Phase 1: Metrics Instrumentation - Implementation Report
+- [v1.1.2-syndicate-architecture.md](v1.1.2/v1.1.2-syndicate-architecture.md) — StarPunk v1.1.2 "Syndicate" - Architecture Overview
 
-### v1.1.1
-- **[v1.1.1/](v1.1.1/)** - v1.1.1 specific design documents
+## v1.2.0
 
-## Quick Reference Documents
+Custom slugs, author discovery and microformats2, media upload and display.
 
-Quick reference documents provide condensed, actionable information for developers:
-- **phase-1.1-quick-reference.md** - Core utilities quick ref
-- **phase-1.2-quick-reference.md** - Data models quick ref
-- **phase-2.1-quick-reference.md** - Notes management quick ref
-- **phase-4-quick-reference.md** - Web interface quick ref
-- **phase-5-quick-reference.md** - RSS and deployment quick ref
-- **initial-schema-quick-reference.md** - Database schema quick ref
+- [2025-11-28-v1.2.0-design-complete.md](v1.2.0/2025-11-28-v1.2.0-design-complete.md) — v1.2.0 Design Review - Complete
+- [2025-11-28-v1.2.0-media-display-fixes.md](v1.2.0/2025-11-28-v1.2.0-media-display-fixes.md) — Media Display Fixes Implementation Report
+- [2025-11-28-v1.2.0-phase1-custom-slugs.md](v1.2.0/2025-11-28-v1.2.0-phase1-custom-slugs.md) — v1.2.0 Phase 1: Custom Slugs - Implementation Report
+- [2025-11-28-v1.2.0-phase1-review.md](v1.2.0/2025-11-28-v1.2.0-phase1-review.md) — v1.2.0 Phase 1: Custom Slugs - Architectural Review
+- [2025-11-28-v1.2.0-phase2-author-microformats.md](v1.2.0/2025-11-28-v1.2.0-phase2-author-microformats.md) — v1.2.0 Phase 2 Implementation Report: Author Discovery & Microformats2
+- [2025-11-28-v1.2.0-phase2-review.md](v1.2.0/2025-11-28-v1.2.0-phase2-review.md) — v1.2.0 Phase 2 Architectural Review: Author Discovery & Microformats2
+- [2025-11-28-v1.2.0-phase3-media-upload.md](v1.2.0/2025-11-28-v1.2.0-phase3-media-upload.md) — v1.2.0 Phase 3: Media Upload - Implementation Report
+- [2025-11-28-v1.2.0-phase3-review.md](v1.2.0/2025-11-28-v1.2.0-phase3-review.md) — v1.2.0 Phase 3 Architecture Review: Media Upload
+- [2025-12-09-feed-media-implementation.md](v1.2.0/2025-12-09-feed-media-implementation.md) — Feed Media Enhancement Implementation Report
+- [2025-12-09-media-display-validation.md](v1.2.0/2025-12-09-media-display-validation.md) — Media Display Implementation Validation Report
+- [2025-12-09-v1.2.0-release.md](v1.2.0/2025-12-09-v1.2.0-release.md) — v1.2.0 Release Report
+- [2025-12-10-documentation-audit-v1.2.0.md](v1.2.0/2025-12-10-documentation-audit-v1.2.0.md) — Documentation Audit Report - Post v1.2.0 Release
+- [media-display-fixes.md](v1.2.0/media-display-fixes.md) — Media Display Fixes - Architectural Design
+- [v1.2.0-media-css-design.md](v1.2.0/v1.2.0-media-css-design.md) — CSS Design for Media Display (v1.2.0)
+- [v1.X.X-indieweb-options.md](v1.2.0/v1.X.X-indieweb-options.md) — StarPunk v1.X.X IndieWeb-Focused Release Options
+- [v1.X.X-options.md](v1.2.0/v1.X.X-options.md) — StarPunk Next Release Options
 
-## How to Use This Documentation
+## v1.3.0
 
-### For Developers Implementing Features
-1. Start with the relevant **phase** document (e.g., phase-2.1-notes-management.md)
-2. Consult the **quick reference** for that phase
-3. Check **feature-specific design** docs for details
-4. Reference **ADRs** in ../decisions/ for architectural decisions
+Microformats2 compliance and tags.
 
-### For Planning New Features
-1. Review similar **phase documents** for patterns
-2. Check **project-structure.md** for organization guidelines
-3. Create new design doc following existing format
-4. Update this index with the new document
+- [2025-12-10-phase1-implementation.md](v1.3.0/2025-12-10-phase1-implementation.md) — v1.3.0 Phase 1 Implementation Report
+- [2025-12-10-phase2-implementation.md](v1.3.0/2025-12-10-phase2-implementation.md) — v1.3.0 Phase 2: Templates Implementation Report
+- [2025-12-10-phase3-implementation.md](v1.3.0/2025-12-10-phase3-implementation.md) — v1.3.0 Phase 3 Implementation Report
+- [2025-12-10-phase4-implementation.md](v1.3.0/2025-12-10-phase4-implementation.md) — v1.3.0 Phase 4: Validation Implementation Report
+- [microformats-tags-design.md](v1.3.0/microformats-tags-design.md) — v1.3.0 Microformats2 Compliance and Tags Implementation Design
 
-### For Understanding Existing Code
-1. Find the **phase** that implemented the feature
-2. Read the design document for context
-3. Check **ADRs** for decision rationale
-4. Review implementation reports in ../reports/
+## v1.3.1
 
-## Document Types
+Tags in feeds.
 
-### Phase Documents
-Comprehensive plans for each development phase, including:
-- Goals and scope
-- Implementation tasks
-- Dependencies
-- Testing requirements
+- [2025-12-10-feed-tags-implementation.md](v1.3.1/2025-12-10-feed-tags-implementation.md) — Feed Tags Implementation Report
+- [feed-tags-design.md](v1.3.1/feed-tags-design.md) — Feed Tags Implementation Design
 
-### Quick Reference Documents
-Condensed information for rapid development:
-- Key decisions
-- Code patterns
-- Common operations
-- Gotchas and notes
+## v1.4.0
 
-### Feature Design Documents
-Detailed specifications for specific features:
-- Requirements
-- API design
-- Data models
-- UI/UX considerations
+"Media" release: image variants and media pipeline.
 
-### Diagnostic Documents
-Problem analysis and solutions:
-- Issue description
-- Root cause analysis
-- Solution design
-- Implementation plan
+- [2025-12-16-phase4-implementation-report.md](v1.4.0/2025-12-16-phase4-implementation-report.md) — v1.4.0 Phase 4 Implementation Report
+- [2025-12-16-v140-implementation-complete.md](v1.4.0/2025-12-16-v140-implementation-complete.md) — v1.4.0 "Media" Release - Implementation Complete
+- [media-implementation-design.md](v1.4.0/media-implementation-design.md) — v1.4.0 "Media" Release - Implementation Design
+
+## v1.4.1
+
+Media upload logging.
+
+- [2025-12-16-implementation-report.md](v1.4.1/2025-12-16-implementation-report.md) — Implementation Report - v1.4.1 Media Upload Logging
+- [architect-responses.md](v1.4.1/architect-responses.md) — Architect Responses - v1.4.1 Media Upload Logging
+- [developer-questions.md](v1.4.1/developer-questions.md) — Developer Questions - v1.4.1 Media Upload Logging
+- [media-logging-design.md](v1.4.1/media-logging-design.md) — Media Upload Logging Design - v1.4.1
+
+## v1.4.2
+
+HEIC/MPO support and larger dimension limit.
+
+- [2025-12-16-architect-review.md](v1.4.2/2025-12-16-architect-review.md) — Architect Review: v1.4.2 Implementation and End-to-End Media Pipeline
+- [2025-12-16-developer-review.md](v1.4.2/2025-12-16-developer-review.md) — v1.4.2 Developer Review - HEIC/MPO Support and Dimension Limit Increase
+- [2025-12-16-implementation-report.md](v1.4.2/2025-12-16-implementation-report.md) — v1.4.2 Implementation Report - HEIC Image Support
+- [heic-support-design.md](v1.4.2/heic-support-design.md) — HEIC Image Support Design - v1.4.2
+
+## v1.5.0
+
+Timestamp slugs, debug file management, N+1 fix, atomic variants, test coverage.
+
+- [2025-12-16-architect-responses.md](v1.5.0/2025-12-16-architect-responses.md) — Architect Responses - v1.5.0 Developer Questions
+- [2025-12-16-developer-questions.md](v1.5.0/2025-12-16-developer-questions.md) — Developer Review Questions - v1.5.0 Release Plan
+- [2025-12-16-phase-0-implementation-report.md](v1.5.0/2025-12-16-phase-0-implementation-report.md) — Phase 0 Implementation Report - Test Fixes
+- [2025-12-16-phase2-architect-review.md](v1.5.0/2025-12-16-phase2-architect-review.md) — Phase 2 Architect Review: Debug File Management
+- [2025-12-17-indieauth-discovery-fix.md](v1.5.0/2025-12-17-indieauth-discovery-fix.md) — IndieAuth Endpoint Discovery Regression Analysis
+- [2025-12-17-phase-1-implementation-report.md](v1.5.0/2025-12-17-phase-1-implementation-report.md) — Phase 1 Implementation Report: Timestamp-Based Slugs
+- [2025-12-17-phase3-architect-review.md](v1.5.0/2025-12-17-phase3-architect-review.md) — Phase 3 Architect Review: N+1 Query Fix
+- [2025-12-17-phase3-implementation.md](v1.5.0/2025-12-17-phase3-implementation.md) — v1.5.0 Phase 3 Implementation Report
+- [2025-12-17-phase4-architect-review.md](v1.5.0/2025-12-17-phase4-architect-review.md) — Phase 4 Architect Review: Atomic Variant Generation
+- [2025-12-17-phase4-implementation.md](v1.5.0/2025-12-17-phase4-implementation.md) — v1.5.0 Phase 4: Atomic Variant Generation - Implementation Report
+- [2025-12-17-phase5-architect-review.md](v1.5.0/2025-12-17-phase5-architect-review.md) — Phase 5 Architect Review: Test Coverage Expansion (FINAL)
+- [2025-12-17-phase5-implementation.md](v1.5.0/2025-12-17-phase5-implementation.md) — v1.5.0 Phase 5: Test Coverage Expansion - Implementation Report
+- [phase-2-implementation-report.md](v1.5.0/phase-2-implementation-report.md) — v1.5.0 Phase 2 Implementation Report: Debug File Management
+
+## v1.6.0
+
+Webmentions (receive, send, moderate), reply contexts, rate limiting. Original documents lost; reconstructed from the code.
+
+- [api-contract.md](v1.6.0/api-contract.md) — v1.6.0 Design: Webmention API Contract *(reconstructed)*
+- [background-worker.md](v1.6.0/background-worker.md) — v1.6.0 Design: Webmention Background Worker *(reconstructed)*
+- [database-schema.md](v1.6.0/database-schema.md) — v1.6.0 Design: Webmention Database Schema *(reconstructed)*
+- [display-moderation.md](v1.6.0/display-moderation.md) — v1.6.0 Design: Webmention Display and Moderation *(reconstructed)*
+- [rate-limiting.md](v1.6.0/rate-limiting.md) — v1.6.0 Design: Webmention Rate Limiting *(reconstructed)*
+
+## v2.0.0
+
+OIDC admin login and built-in IndieAuth server.
+
+- [2026-10-31-oidc-migration.md](v2.0.0/2026-10-31-oidc-migration.md) — v2.0.0 Implementation Report: OIDC Login and Built-in IndieAuth Server
+
+## v2.0.1
+
+- [2026-10-31-absolute-urls-and-ci-buildkit.md](v2.0.1/2026-10-31-absolute-urls-and-ci-buildkit.md) — Absolute URLs from SITE_URL; CI builds with BuildKit *(reconstructed)*
+
+## v2.0.2
+
+- [2026-10-31-ci-registry-token.md](v2.0.2/2026-10-31-ci-registry-token.md) — CI registry login with REGISTRY_TOKEN *(reconstructed)*
+
+## v2.1.0
+
+- [2026-10-31-gotosocial-crossposting.md](v2.1.0/2026-10-31-gotosocial-crossposting.md) — Crossposting to GoToSocial *(reconstructed)*
+
+## v2.2.0
+
+- [2026-10-31-bluesky-crossposting.md](v2.2.0/2026-10-31-bluesky-crossposting.md) — Crossposting to Bluesky *(reconstructed)*
+
+## v2.3.0
+
+- [2026-10-31-public-page-restyle.md](v2.3.0/2026-10-31-public-page-restyle.md) — Public page restyle *(reconstructed)*
+
+## v2.3.1
+
+- [2026-10-31-login-link-in-header.md](v2.3.1/2026-10-31-login-link-in-header.md) — "Log in" back in the header *(reconstructed)*
+
+## v2.3.2
+
+- [2026-10-31-header-admin-link.md](v2.3.2/2026-10-31-header-admin-link.md) — Header shows "Admin" when logged in *(reconstructed)*
+
+## v2.3.3
+
+- [2026-10-31-micropub-title-and-source-url.md](v2.3.3/2026-10-31-micropub-title-and-source-url.md) — Micropub titles, q=source URL, single title display
+
+## v2.4.0
+
+- [2026-10-31-micropub-update-delete-drafts.md](v2.4.0/2026-10-31-micropub-update-delete-drafts.md) — Micropub update, delete/undelete, drafts, replies *(reconstructed)*
+
+## v2.5.0
+
+- [2026-10-31-likes-and-reposts.md](v2.5.0/2026-10-31-likes-and-reposts.md) — Likes and reposts *(reconstructed)*
+
+## v2.6.0
+
+- [2026-10-31-threads-crossposting.md](v2.6.0/2026-10-31-threads-crossposting.md) — Crossposting to Threads
+
+## v2.6.1
+
+- [2026-10-31-threads-publish-retry.md](v2.6.1/2026-10-31-threads-publish-retry.md) — Retry Threads publish errors *(reconstructed)*
+
+## v2.6.2
+
+- [2026-10-31-threads-link-preview.md](v2.6.2/2026-10-31-threads-link-preview.md) — Let Threads build the link preview *(reconstructed)*
+
+## v2.6.3
+
+- [2026-11-01-crosspost-links-and-cards.md](v2.6.3/2026-11-01-crosspost-links-and-cards.md) — Crosspost cards show the note's own link *(reconstructed)*
+
+## v2.6.4
+
+- [2026-11-01-tag-entry-order.md](v2.6.4/2026-11-01-tag-entry-order.md) — Tags keep the order they were entered in *(reconstructed)*
+
+## v2.6.5
+
+- [2026-11-01-micropub-media-fixes.md](v2.6.5/2026-11-01-micropub-media-fixes.md) — Micropub media fixes
+
+## v2.6.6
+
+- [2026-11-02-crosspost-embedded-images.md](v2.6.6/2026-11-02-crosspost-embedded-images.md) — Crossposts include photos embedded in the text *(reconstructed)*
+
+## v2.6.7
+
+- [2026-11-02-admin-layout-width.md](v2.6.7/2026-11-02-admin-layout-width.md) — Admin pages line up with the header *(reconstructed)*
+
+## v2.6.8
+
+- [2026-11-03-webmention-worker-app-context.md](v2.6.8/2026-11-03-webmention-worker-app-context.md) — Webmention worker app context
+
+## v2.6.9
+
+- [2026-11-03-webmention-processing-fixes.md](v2.6.9/2026-11-03-webmention-processing-fixes.md) — Webmention processing fixes
+
+## v2.7.0
+
+- [2026-11-03-webmention-spec-compliance.md](v2.7.0/2026-11-03-webmention-spec-compliance.md) — Webmention W3C compliance
+
+## v2.7.1
+
+- [2026-11-03-ci-test-stage.md](v2.7.1/2026-11-03-ci-test-stage.md) — Tests run before release images are built *(reconstructed)*
+
+## v2.7.2
+
+- [2026-11-03-webmention-shoulds.md](v2.7.2/2026-11-03-webmention-shoulds.md) — Remaining Webmention SHOULDs
+
+## v2.8.0
+
+- [2026-11-03-microformats2-review.md](v2.8.0/2026-11-03-microformats2-review.md) — Microformats2 review
+
+## v2.8.1
+
+- [2026-11-03-migration-lock.md](v2.8.1/2026-11-03-migration-lock.md) — Migration lock held for the whole run
+
+## v2.9.0
+
+- [2026-11-03-micropub-review.md](v2.9.0/2026-11-03-micropub-review.md) — Micropub review
+
+## v2.10.0
+
+- [2026-11-03-websub-implementation.md](v2.10.0/2026-11-03-websub-implementation.md) — WebSub with a built-in hub (implementation report) *(reconstructed)*
+
+## v2.10.1
+
+- [2026-11-03-websub-hardening.md](v2.10.1/2026-11-03-websub-hardening.md) — WebSub hardening (implementation report) *(reconstructed)*
+
+## hotfix
+
+Not a release folder.
+
+IndieAuth PKCE endpoint discovery hotfix (2025-12-17, between v1.5.0 and v1.6.0; no version of its own).
+
+- [2025-12-17-indieauth-pkce-endpoint-discovery-hotfix-implementation-report.md](hotfix/2025-12-17-indieauth-pkce-endpoint-discovery-hotfix-implementation-report.md) — IndieAuth Endpoint Discovery Hotfix - Implementation Report
+- [2025-12-17-indieauth-pkce-endpoint-discovery-hotfix.md](hotfix/2025-12-17-indieauth-pkce-endpoint-discovery-hotfix.md) — IndieAuth Endpoint Discovery Hotfix
 
 ## Related Documentation
-- **[../architecture/](../architecture/)** - System architecture and overviews
-- **[../decisions/](../decisions/)** - Architectural Decision Records (ADRs)
-- **[../reports/](../reports/)** - Implementation reports
-- **[../standards/](../standards/)** - Coding standards and conventions
+
+- [../architecture/](../architecture/) - Current system architecture
+- [../decisions/](../decisions/) - Architectural Decision Records (ADRs)
+- [../projectplan/](../projectplan/) - Backlog and release plans
+- [../standards/](../standards/) - Coding standards and conventions
+- [../../CHANGELOG.md](../../CHANGELOG.md) - User-facing release notes
 
 ---
 
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
+**Last Updated**: 2026-11-03
diff --git a/docs/design/v1.0.0/container-deployment.md b/docs/design/v1.0.0/container-deployment.md
index f21cf5f..94aad81 100644
--- a/docs/design/v1.0.0/container-deployment.md
+++ b/docs/design/v1.0.0/container-deployment.md
@@ -630,11 +630,11 @@ curl http://localhost:8000/health
 
 ### Documentation
 
-- [Phase 5 Design](../designs/phase-5-rss-and-container.md)
-- [Containerfile](../../Containerfile)
-- [Compose Configuration](../../compose.yaml)
-- [Caddy Example](../../Caddyfile.example)
-- [Nginx Example](../../nginx.conf.example)
+- [Phase 5 Design](phase-5-rss-and-container.md)
+- [Containerfile](../../../Containerfile)
+- [Compose Configuration](../../../compose.yaml)
+- [Caddy Example](../../../Caddyfile.example)
+- [Nginx Example](../../../nginx.conf.example)
 
 ### External Resources
 
diff --git a/docs/design/v1.0.0/implementation-plan.md b/docs/design/v1.0.0/implementation-plan.md
index f4e7239..b9ac36f 100644
--- a/docs/design/v1.0.0/implementation-plan.md
+++ b/docs/design/v1.0.0/implementation-plan.md
@@ -21,12 +21,12 @@ This document provides a comprehensive, dependency-ordered implementation plan f
 |-------|--------|---------|---------------|--------|
 | 1.1 - Core Utilities | ✅ Complete | 0.1.0 | >90% | N/A |
 | 1.2 - Data Models | ✅ Complete | 0.1.0 | >90% | N/A |
-| 2.1 - Notes Management | ✅ Complete | 0.3.0 | 86% (85 tests) | [Phase 2.1 Report](/home/phil/Projects/starpunk/docs/reports/phase-2.1-implementation-20251118.md) |
-| 3.1 - Authentication | ✅ Complete | 0.8.0 | 96% (51 tests) | [Phase 3 Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md) |
+| 2.1 - Notes Management | ✅ Complete | 0.3.0 | 86% (85 tests) | [Phase 2.1 Report](phase-2.1-implementation-20251118.md) |
+| 3.1 - Authentication | ✅ Complete | 0.8.0 | 96% (51 tests) | [Phase 3 Report](phase-3-authentication-20251118.md) |
 | 4.1-4.4 - Web Interface | ✅ Complete | 0.5.2 | 87% (405 tests) | Phase 4 implementation |
 | 5.1-5.2 - RSS Feed | ✅ Complete | 0.6.0 | 96% | ADR-014, ADR-015 |
-| 6 - Micropub | ✅ Complete | 1.0.0 | 95% | [v1.0.0 Release](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md) |
-| V1.1 - Search & Enhancements | ✅ Complete | 1.1.0 | 598 tests | [v1.1.0 Report](/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md) |
+| 6 - Micropub | ✅ Complete | 1.0.0 | 95% | v1.0.0 Release (`v1.0.0-implementation-report.md`, not preserved) |
+| V1.1 - Search & Enhancements | ✅ Complete | 1.1.0 | 598 tests | [v1.1.0 Report](../v1.1.1/v1.1.0-implementation-report.md) |
 
 ### Current Status 🔵
 
@@ -1553,29 +1553,29 @@ Final steps before V1 release.
 ## References
 
 ### Project Documentation
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
-- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
-- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
-- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
-- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
-- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
-- [ADR-007: Slug Generation Algorithm](/home/phil/Projects/starpunk/docs/decisions/ADR-007-slug-generation-algorithm.md)
-- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md)
-- [ADR-009: Git Branching Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-009-git-branching-strategy.md)
-- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md)
-- [ADR-011: Development Authentication Mechanism](/home/phil/Projects/starpunk/docs/decisions/ADR-011-development-authentication-mechanism.md)
-- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
-- [Phase 4 Web Interface Design](/home/phil/Projects/starpunk/docs/design/phase-4-web-interface.md)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
-- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
+- [Architecture Overview](../../architecture/overview.md)
+- [Technology Stack](../../architecture/technology-stack.md)
+- [ADR-001: Python Web Framework](../../decisions/ADR-001-python-web-framework.md)
+- [ADR-002: Flask Extensions](../../decisions/ADR-002-flask-extensions.md)
+- [ADR-003: Frontend Technology](../../decisions/ADR-003-frontend-technology.md)
+- [ADR-004: File-Based Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [ADR-005: IndieLogin Authentication](../../decisions/ADR-005-indielogin-authentication.md)
+- [ADR-006: Python Virtual Environment](../../decisions/ADR-006-python-virtual-environment-uv.md)
+- [ADR-007: Slug Generation Algorithm](../../decisions/ADR-007-slug-generation-algorithm.md)
+- [ADR-008: Versioning Strategy](../../decisions/ADR-008-versioning-strategy.md)
+- [ADR-009: Git Branching Strategy](../../decisions/ADR-009-git-branching-strategy.md)
+- [ADR-010: Authentication Module Design](../../decisions/ADR-010-authentication-module-design.md)
+- [ADR-011: Development Authentication Mechanism](../../decisions/ADR-011-development-authentication-mechanism.md)
+- [Project Structure](project-structure.md)
+- [Phase 4 Web Interface Design](phase-4-web-interface.md)
+- [Python Coding Standards](../../standards/python-coding-standards.md)
+- [Versioning Strategy](../../standards/versioning-strategy.md)
+- [Git Branching Strategy](../../standards/git-branching-strategy.md)
 
 ### Implementation Reports
-- [Phase 2.1 Implementation Report](/home/phil/Projects/starpunk/docs/reports/phase-2.1-implementation-20251118.md)
-- [Phase 3 Authentication Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md)
-- [Phase 4 Architectural Assessment](/home/phil/Projects/starpunk/docs/reports/phase-4-architectural-assessment-20251118.md)
+- [Phase 2.1 Implementation Report](phase-2.1-implementation-20251118.md)
+- [Phase 3 Authentication Report](phase-3-authentication-20251118.md)
+- [Phase 4 Architectural Assessment](phase-4-architectural-assessment-20251118.md)
 
 ### External Standards
 - [Micropub Specification](https://micropub.spec.indieweb.org/)
diff --git a/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md b/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
index d075213..8482d83 100644
--- a/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
+++ b/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
@@ -333,8 +333,8 @@ This allows gradual migration without breaking existing integrations.
 ## References
 
 ### Architect Documentation
-- [ADR-016: IndieAuth Client Discovery Mechanism](/home/phil/Projects/starpunk/docs/decisions/ADR-016-indieauth-client-discovery.md)
-- [IndieAuth Client Discovery Analysis Report](/home/phil/Projects/starpunk/docs/reports/indieauth-client-discovery-analysis.md)
+- [ADR-016: IndieAuth Client Discovery Mechanism](../../decisions/ADR-016-indieauth-client-discovery.md)
+- [IndieAuth Client Discovery Analysis Report](indieauth-client-discovery-analysis.md)
 
 ### IndieWeb Standards
 - [IndieAuth Specification](https://www.w3.org/TR/indieauth/)
@@ -342,9 +342,9 @@ This allows gradual migration without breaking existing integrations.
 - [IndieLogin.com](https://indielogin.com/)
 
 ### Project Documentation
-- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md)
-- [ADR-009: Git Branching Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-009-git-branching-strategy.md)
-- [Phase 3: Authentication Design](/home/phil/Projects/starpunk/docs/design/phase-3-authentication.md)
+- [ADR-008: Versioning Strategy](../../decisions/ADR-008-versioning-strategy.md)
+- [ADR-009: Git Branching Strategy](../../decisions/ADR-009-git-branching-strategy.md)
+- [Phase 3: Authentication Design](phase-3-authentication.md)
 
 ---
 
diff --git a/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md b/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
index d4d9632..c8e62dc 100644
--- a/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
+++ b/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
@@ -376,6 +376,6 @@ The implementation exactly follows the architect's specification in ADR-018, use
 
 ## Related Documentation
 
-- [ADR-018: IndieAuth Detailed Logging Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-018-indieauth-detailed-logging.md)
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
-- [CHANGELOG.md](/home/phil/Projects/starpunk/CHANGELOG.md)
+- [ADR-018: IndieAuth Detailed Logging Strategy](../../decisions/ADR-018-indieauth-detailed-logging.md)
+- [Versioning Strategy](../../standards/versioning-strategy.md)
+- [CHANGELOG.md](../../../CHANGELOG.md)
diff --git a/docs/design/v1.0.0/initial-files.md b/docs/design/v1.0.0/initial-files.md
index 21d60ef..4a5bd48 100644
--- a/docs/design/v1.0.0/initial-files.md
+++ b/docs/design/v1.0.0/initial-files.md
@@ -1009,9 +1009,9 @@ echo "✓ Sensitive files are gitignored"
 
 ## References
 
-- [Project Structure Design](/home/phil/Projects/starpunk/docs/design/project-structure.md)
-- [Development Setup Standards](/home/phil/Projects/starpunk/docs/standards/development-setup.md)
-- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
-- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
+- [Project Structure Design](project-structure.md)
+- [Development Setup Standards](../../standards/development-setup.md)
+- [ADR-002: Flask Extensions](../../decisions/ADR-002-flask-extensions.md)
+- [ADR-006: Python Virtual Environment](../../decisions/ADR-006-python-virtual-environment-uv.md)
 - [Python Packaging Guide](https://packaging.python.org/)
 - [Flask Configuration Handling](https://flask.palletsprojects.com/en/3.0.x/config/)
diff --git a/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md b/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
index a66003e..c746081 100644
--- a/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
+++ b/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
@@ -328,7 +328,7 @@ This client_id is not registered (https://starpunk.thesatelliteoflove.com)
 - [IANA Well-Known URIs](https://www.iana.org/assignments/well-known-uris/)
 
 ### Project
-- [ADR-017: OAuth Client ID Metadata Document Implementation](../decisions/ADR-017-oauth-client-metadata-document.md)
+- [ADR-017: OAuth Client ID Metadata Document Implementation](../../decisions/ADR-017-oauth-client-metadata-document.md)
 - [IndieAuth Fix Summary](indieauth-fix-summary.md)
 - [Root Cause Analysis](indieauth-client-discovery-root-cause-analysis.md)
 
diff --git a/docs/design/v1.0.0/phase-1.1-core-utilities.md b/docs/design/v1.0.0/phase-1.1-core-utilities.md
index a788b1c..1bfbd7c 100644
--- a/docs/design/v1.0.0/phase-1.1-core-utilities.md
+++ b/docs/design/v1.0.0/phase-1.1-core-utilities.md
@@ -1365,9 +1365,9 @@ def extract_title(content: str) -> Optional[str]:
 
 ## References
 
-- [ADR-004: File-Based Note Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
+- [ADR-004: File-Based Note Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [Python Coding Standards](../../standards/python-coding-standards.md)
+- [Project Structure](project-structure.md)
 - [CommonMark Specification](https://spec.commonmark.org/)
 - [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
 - [ISO 8601 Date Format](https://en.wikipedia.org/wiki/ISO_8601)
diff --git a/docs/design/v1.0.0/phase-1.2-data-models.md b/docs/design/v1.0.0/phase-1.2-data-models.md
index 61ee9e3..445c5c0 100644
--- a/docs/design/v1.0.0/phase-1.2-data-models.md
+++ b/docs/design/v1.0.0/phase-1.2-data-models.md
@@ -1900,10 +1900,10 @@ class Webmention:
 
 ## References
 
-- [ADR-004: File-Based Note Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [Database Schema](/home/phil/Projects/starpunk/starpunk/database.py)
-- [Phase 1.1: Core Utilities](/home/phil/Projects/starpunk/docs/design/phase-1.1-core-utilities.md)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
+- [ADR-004: File-Based Note Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [Database Schema](../../../starpunk/monitoring/database.py)
+- [Phase 1.1: Core Utilities](phase-1.1-core-utilities.md)
+- [Python Coding Standards](../../standards/python-coding-standards.md)
 - [Python Dataclasses Documentation](https://docs.python.org/3/library/dataclasses.html)
 - [Python-Markdown Documentation](https://python-markdown.github.io/)
 
diff --git a/docs/design/v1.0.0/phase-2.1-notes-management.md b/docs/design/v1.0.0/phase-2.1-notes-management.md
index d92c8a7..dcfb950 100644
--- a/docs/design/v1.0.0/phase-2.1-notes-management.md
+++ b/docs/design/v1.0.0/phase-2.1-notes-management.md
@@ -2057,14 +2057,14 @@ Phase 2.1 is complete when:
 
 ## References
 
-- [ADR-004: File-Based Note Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [ADR-007: Slug Generation Algorithm](/home/phil/Projects/starpunk/docs/decisions/ADR-007-slug-generation-algorithm.md)
-- [Phase 1.1: Core Utilities](/home/phil/Projects/starpunk/docs/design/phase-1.1-core-utilities.md)
-- [Phase 1.2: Data Models](/home/phil/Projects/starpunk/docs/design/phase-1.2-data-models.md)
-- [Database Schema](/home/phil/Projects/starpunk/starpunk/database.py)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Security Architecture](/home/phil/Projects/starpunk/docs/architecture/security.md)
+- [ADR-004: File-Based Note Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [ADR-007: Slug Generation Algorithm](../../decisions/ADR-007-slug-generation-algorithm.md)
+- [Phase 1.1: Core Utilities](phase-1.1-core-utilities.md)
+- [Phase 1.2: Data Models](phase-1.2-data-models.md)
+- [Database Schema](../../../starpunk/monitoring/database.py)
+- [Python Coding Standards](../../standards/python-coding-standards.md)
+- [Architecture Overview](../../architecture/overview.md)
+- Security Architecture (`security.md`, not preserved)
 
 ---
 
diff --git a/docs/design/v1.0.0/phase-2.1-quick-reference.md b/docs/design/v1.0.0/phase-2.1-quick-reference.md
index fb02b87..3515c59 100644
--- a/docs/design/v1.0.0/phase-2.1-quick-reference.md
+++ b/docs/design/v1.0.0/phase-2.1-quick-reference.md
@@ -607,10 +607,10 @@ After completing Phase 2.1:
 
 ## Help & Resources
 
-- **Full Design Doc**: [phase-2.1-notes-management.md](/home/phil/Projects/starpunk/docs/design/phase-2.1-notes-management.md)
-- **Utilities Design**: [phase-1.1-core-utilities.md](/home/phil/Projects/starpunk/docs/design/phase-1.1-core-utilities.md)
-- **Models Design**: [phase-1.2-data-models.md](/home/phil/Projects/starpunk/docs/design/phase-1.2-data-models.md)
-- **Coding Standards**: [python-coding-standards.md](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- **Implementation Plan**: [implementation-plan.md](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
+- **Full Design Doc**: [phase-2.1-notes-management.md](phase-2.1-notes-management.md)
+- **Utilities Design**: [phase-1.1-core-utilities.md](phase-1.1-core-utilities.md)
+- **Models Design**: [phase-1.2-data-models.md](phase-1.2-data-models.md)
+- **Coding Standards**: [python-coding-standards.md](../../standards/python-coding-standards.md)
+- **Implementation Plan**: [implementation-plan.md](implementation-plan.md)
 
 Remember: "Every line of code must justify its existence. When in doubt, leave it out."
diff --git a/docs/design/v1.0.0/phase-3-authentication-implementation.md b/docs/design/v1.0.0/phase-3-authentication-implementation.md
index 799d99d..5edec98 100644
--- a/docs/design/v1.0.0/phase-3-authentication-implementation.md
+++ b/docs/design/v1.0.0/phase-3-authentication-implementation.md
@@ -532,8 +532,8 @@ After Phase 3 completion:
 
 ## References
 
-- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
-- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md)
+- [ADR-005: IndieLogin Authentication](../../decisions/ADR-005-indielogin-authentication.md)
+- [ADR-010: Authentication Module Design](../../decisions/ADR-010-authentication-module-design.md)
 - [IndieAuth Specification](https://www.w3.org/TR/indieauth/)
 - [IndieLogin API Documentation](https://indielogin.com/api)
 - [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
diff --git a/docs/design/v1.0.0/phase-4-web-interface.md b/docs/design/v1.0.0/phase-4-web-interface.md
index e7a6274..012fb47 100644
--- a/docs/design/v1.0.0/phase-4-web-interface.md
+++ b/docs/design/v1.0.0/phase-4-web-interface.md
@@ -1292,12 +1292,12 @@ Deferred features:
 ## References
 
 ### Internal Documentation
-- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
-- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
-- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md)
-- [ADR-011: Development Authentication Mechanism](/home/phil/Projects/starpunk/docs/decisions/ADR-011-development-authentication-mechanism.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Phase 3 Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md)
+- [ADR-003: Frontend Technology](../../decisions/ADR-003-frontend-technology.md)
+- [ADR-005: IndieLogin Authentication](../../decisions/ADR-005-indielogin-authentication.md)
+- [ADR-010: Authentication Module Design](../../decisions/ADR-010-authentication-module-design.md)
+- [ADR-011: Development Authentication Mechanism](../../decisions/ADR-011-development-authentication-mechanism.md)
+- [Architecture Overview](../../architecture/overview.md)
+- [Phase 3 Report](phase-3-authentication-20251118.md)
 
 ### External Standards
 - [Microformats2 h-entry](http://microformats.org/wiki/h-entry)
diff --git a/docs/design/v1.0.0/phase-5-executive-summary.md b/docs/design/v1.0.0/phase-5-executive-summary.md
index 53053a7..d295461 100644
--- a/docs/design/v1.0.0/phase-5-executive-summary.md
+++ b/docs/design/v1.0.0/phase-5-executive-summary.md
@@ -382,10 +382,10 @@ The codebase is in excellent condition, all prerequisites are met, and comprehen
 ## Quick Access Links
 
 **Primary Documents**:
-- [Full Design Document](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md)
-- [Quick Reference Guide](/home/phil/Projects/starpunk/docs/designs/phase-5-quick-reference.md)
-- [ADR-014: RSS Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-014-rss-feed-implementation.md)
-- [Pre-Implementation Review](/home/phil/Projects/starpunk/docs/reports/phase-5-pre-implementation-review.md)
+- [Full Design Document](phase-5-rss-and-container.md)
+- [Quick Reference Guide](phase-5-quick-reference.md)
+- [ADR-014: RSS Implementation](../../decisions/ADR-014-rss-feed-implementation.md)
+- [Pre-Implementation Review](phase-5-pre-implementation-review.md)
 
 **Standards References**:
 - [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
@@ -393,8 +393,8 @@ The codebase is in excellent condition, all prerequisites are met, and comprehen
 - [Podman Documentation](https://docs.podman.io/)
 
 **Project Standards**:
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
-- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
+- [Versioning Strategy](../../standards/versioning-strategy.md)
+- [Git Branching Strategy](../../standards/git-branching-strategy.md)
 
 ---
 
diff --git a/docs/design/v1.0.0/phase-5-quick-reference.md b/docs/design/v1.0.0/phase-5-quick-reference.md
index 751580a..74fc468 100644
--- a/docs/design/v1.0.0/phase-5-quick-reference.md
+++ b/docs/design/v1.0.0/phase-5-quick-reference.md
@@ -421,10 +421,10 @@ Phase 5 complete when:
 
 ## Reference Documents
 
-- [Phase 5 Full Design](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md)
-- [ADR-014: RSS Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-014-rss-feed-implementation.md)
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
-- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
+- [Phase 5 Full Design](phase-5-rss-and-container.md)
+- [ADR-014: RSS Implementation](../../decisions/ADR-014-rss-feed-implementation.md)
+- [Versioning Strategy](../../standards/versioning-strategy.md)
+- [Git Branching Strategy](../../standards/git-branching-strategy.md)
 
 ---
 
diff --git a/docs/design/v1.0.0/phase-5-rss-and-container.md b/docs/design/v1.0.0/phase-5-rss-and-container.md
index ae031cc..6177248 100644
--- a/docs/design/v1.0.0/phase-5-rss-and-container.md
+++ b/docs/design/v1.0.0/phase-5-rss-and-container.md
@@ -1236,10 +1236,10 @@ Deferred features:
 ## References
 
 ### Internal Documentation
-- [Phase 4: Web Interface](/home/phil/Projects/starpunk/docs/design/phase-4-web-interface.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
+- [Phase 4: Web Interface](phase-4-web-interface.md)
+- [Architecture Overview](../../architecture/overview.md)
+- [ADR-002: Flask Extensions](../../decisions/ADR-002-flask-extensions.md)
+- [Versioning Strategy](../../standards/versioning-strategy.md)
 
 ### External Standards
 - [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
diff --git a/docs/design/v1.0.0/project-structure.md b/docs/design/v1.0.0/project-structure.md
index 9059171..63a087c 100644
--- a/docs/design/v1.0.0/project-structure.md
+++ b/docs/design/v1.0.0/project-structure.md
@@ -337,7 +337,7 @@ tests/
 
 **Purpose**: Architecture, decisions, designs, and standards.
 
-**Organization**: See [Documentation Organization Standard](/home/phil/Projects/starpunk/docs/standards/documentation-organization.md)
+**Organization**: See [Documentation Organization Standard](../../standards/documentation-organization.md)
 
 ```
 docs/
@@ -790,6 +790,6 @@ After creating project structure, verify:
 - [Flask Project Layout](https://flask.palletsprojects.com/en/3.0.x/tutorial/layout/)
 - [Pytest Good Practices](https://docs.pytest.org/en/stable/goodpractices.html)
 - [PEP 8 Package Layout](https://peps.python.org/pep-0008/)
-- [ADR-004: File-Based Note Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
-- [Documentation Organization Standard](/home/phil/Projects/starpunk/docs/standards/documentation-organization.md)
+- [ADR-004: File-Based Note Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [ADR-006: Python Virtual Environment](../../decisions/ADR-006-python-virtual-environment-uv.md)
+- [Documentation Organization Standard](../../standards/documentation-organization.md)
diff --git a/docs/design/v1.0.0/quick-reference.md b/docs/design/v1.0.0/quick-reference.md
index 07bd7c5..ad6b5bd 100644
--- a/docs/design/v1.0.0/quick-reference.md
+++ b/docs/design/v1.0.0/quick-reference.md
@@ -318,8 +318,8 @@ Quick lookup for architectural decisions:
 
 ### Documentation
 - [Full Implementation Plan](implementation-plan.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
+- [Architecture Overview](../../architecture/overview.md)
+- [Technology Stack](../../architecture/technology-stack.md)
 
 ### External Specs
 - [Micropub Spec](https://micropub.spec.indieweb.org/)
diff --git a/docs/design/v1.0.0/v1-planning-overview.md b/docs/design/v1.0.0/v1-planning-overview.md
index 762cb2e..a8eccc4 100644
--- a/docs/design/v1.0.0/v1-planning-overview.md
+++ b/docs/design/v1.0.0/v1-planning-overview.md
@@ -200,18 +200,18 @@ All validators must pass before V1 release.
 ## Reference Documentation
 
 ### Project Documentation
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
-- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
+- [Architecture Overview](../../architecture/overview.md)
+- [Technology Stack](../../architecture/technology-stack.md)
+- [Project Structure](project-structure.md)
+- [Python Coding Standards](../../standards/python-coding-standards.md)
 
 ### Architecture Decision Records (ADRs)
-- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
-- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
-- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
-- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
-- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
-- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
+- [ADR-001: Python Web Framework](../../decisions/ADR-001-python-web-framework.md)
+- [ADR-002: Flask Extensions](../../decisions/ADR-002-flask-extensions.md)
+- [ADR-003: Frontend Technology](../../decisions/ADR-003-frontend-technology.md)
+- [ADR-004: File-Based Storage](../../decisions/ADR-004-file-based-note-storage.md)
+- [ADR-005: IndieLogin Authentication](../../decisions/ADR-005-indielogin-authentication.md)
+- [ADR-006: Python Virtual Environment](../../decisions/ADR-006-python-virtual-environment-uv.md)
 
 ### External Standards
 - [Micropub Specification](https://micropub.spec.indieweb.org/)
diff --git a/docs/design/v1.1.1/potential-features.md b/docs/design/v1.1.1/potential-features.md
index de2bdc1..718c3b2 100644
--- a/docs/design/v1.1.1/potential-features.md
+++ b/docs/design/v1.1.1/potential-features.md
@@ -6,8 +6,8 @@ This document tracks features that were considered for StarPunk V1.0 but have be
 
 **Status**: Planning / Future Consideration
 **Related Documents**:
-- [V1.0 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
+- [V1.0 Implementation Plan](../v1.0.0/implementation-plan.md)
+- [Architecture Overview](../../architecture/overview.md)
 
 ## Feature Categories
 
@@ -424,8 +424,8 @@ When planning V1.1, features should be evaluated using:
 
 ## References
 
-- [V1.0 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
+- [V1.0 Implementation Plan](../v1.0.0/implementation-plan.md)
+- [Architecture Overview](../../architecture/overview.md)
 - [IndieWeb Principles](https://indieweb.org/principles)
 - [Micropub Specification](https://www.w3.org/TR/micropub/)
 - [Webmention Specification](https://www.w3.org/TR/webmention/)
diff --git a/docs/design/v1.1.1/priority-work.md b/docs/design/v1.1.1/priority-work.md
index 11e7504..c511333 100644
--- a/docs/design/v1.1.1/priority-work.md
+++ b/docs/design/v1.1.1/priority-work.md
@@ -208,10 +208,10 @@ Before releasing v1.1.0:
 
 ## References
 
-- [ADR-031: Database Migration System Redesign](/home/phil/Projects/starpunk/docs/decisions/ADR-031-database-migration-system-redesign.md)
-- [ADR-032: Initial Schema SQL Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-032-initial-schema-sql-implementation.md)
-- [v1.1 Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
-- [Migration Implementation Reports](/home/phil/Projects/starpunk/docs/reports/)
+- [ADR-031: Database Migration System Redesign](../../decisions/ADR-031-database-migration-system-redesign.md)
+- [ADR-032: Initial Schema SQL Implementation](../../decisions/ADR-032-initial-schema-sql-implementation.md)
+- [v1.1 Potential Features](potential-features.md)
+- Migration Implementation Reports (`reports`, not preserved)
 
 ---
 
diff --git a/docs/design/v1.1.1/v1.1.1-architecture-overview.md b/docs/design/v1.1.1/v1.1.1-architecture-overview.md
index 03befda..60bb325 100644
--- a/docs/design/v1.1.1/v1.1.1-architecture-overview.md
+++ b/docs/design/v1.1.1/v1.1.1-architecture-overview.md
@@ -368,11 +368,11 @@ Benchmarks
 
 ## Documentation References
 
-- [Configuration System](/home/phil/Projects/starpunk/docs/decisions/ADR-052-configuration-system-architecture.md)
-- [Performance Monitoring](/home/phil/Projects/starpunk/docs/decisions/ADR-053-performance-monitoring-strategy.md)
-- [Structured Logging](/home/phil/Projects/starpunk/docs/decisions/ADR-054-structured-logging-architecture.md)
-- [Error Handling](/home/phil/Projects/starpunk/docs/decisions/ADR-055-error-handling-philosophy.md)
-- [Implementation Guide](/home/phil/Projects/starpunk/docs/design/v1.1.1/implementation-guide.md)
+- [Configuration System](../../decisions/ADR-052-configuration-system-architecture.md)
+- [Performance Monitoring](../../decisions/ADR-053-performance-monitoring-strategy.md)
+- [Structured Logging](../../decisions/ADR-054-structured-logging-architecture.md)
+- [Error Handling](../../decisions/ADR-055-error-handling-philosophy.md)
+- Implementation Guide (`implementation-guide.md`, not preserved)
 
 ---
 
diff --git a/docs/design/v1.4.0/media-implementation-design.md b/docs/design/v1.4.0/media-implementation-design.md
index 78d44a3..fdaafd7 100644
--- a/docs/design/v1.4.0/media-implementation-design.md
+++ b/docs/design/v1.4.0/media-implementation-design.md
@@ -1652,7 +1652,7 @@ This pattern is used in:
 - [W3C Micropub Specification](https://www.w3.org/TR/micropub/)
 - [Media RSS Specification](https://www.rssboard.org/media-rss)
 - [JSON Feed 1.1 Specification](https://jsonfeed.org/version/1.1)
-- [ADR-057: Media Attachment Model](/home/phil/Projects/starpunk/docs/decisions/ADR-057-media-attachment-model.md)
-- [ADR-058: Image Optimization Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-058-image-optimization-strategy.md)
-- [ADR-059: Full Feed Media Standardization](/home/phil/Projects/starpunk/docs/decisions/ADR-059-full-feed-media-standardization.md)
-- [v1.4.0 Release Definition](/home/phil/Projects/starpunk/docs/projectplan/v1.4.0/RELEASE.md)
+- [ADR-057: Media Attachment Model](../../decisions/ADR-057-media-attachment-model.md)
+- [ADR-058: Image Optimization Strategy](../../decisions/ADR-058-image-optimization-strategy.md)
+- [ADR-059: Full Feed Media Standardization](../../decisions/ADR-059-full-feed-media-standardization.md)
+- [v1.4.0 Release Definition](../../projectplan/v1.4.0/RELEASE.md)
diff --git a/docs/design/v1.6.0/api-contract.md b/docs/design/v1.6.0/api-contract.md
new file mode 100644
index 0000000..686367a
--- /dev/null
+++ b/docs/design/v1.6.0/api-contract.md
@@ -0,0 +1,99 @@
+# v1.6.0 Design: Webmention API Contract
+
+> Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG).
+> This describes the code as of v2.10.1 (`starpunk/routes/webmention.py`, `starpunk/webmention_processor.py`, `starpunk/__init__.py`).
+
+Related: ADR-063, [background-worker.md](background-worker.md),
+[rate-limiting.md](rate-limiting.md), W3C Webmention (https://www.w3.org/TR/webmention/).
+
+## Endpoint discovery (what we advertise)
+
+- Every `text/html` response gets `Link: ; rel="webmention"`
+  when `WEBMENTION_ENABLED` (default true). It is added alongside other
+  `Link` headers (v2.7.0; it used to replace them, e.g. the WebSub links).
+- The endpoint URL is relative to the site root.
+
+## `POST /webmention` (receiving)
+
+Blueprint `webmention`, no authentication.
+
+### Request
+
+- `application/x-www-form-urlencoded` (spec) with `source` and `target`.
+- `application/json` with the same keys is accepted as an extension.
+
+### Processing order
+
+1. **Rate limit** (`before_request`, POST only): see
+   [rate-limiting.md](rate-limiting.md). 429 if exceeded.
+2. `source` and `target` present.
+3. Both are http(s) URLs with a host, at most 2,048 characters.
+4. `source != target`.
+5. Target host and effective port equal `SITE_URL`'s (host compared
+   case-insensitively, default ports filled in; v2.7.0).
+6. The fragment is removed from `target` (spec 3.2.1), so `#a` and `#b` are
+   one mention.
+7. Target must be a published note: path `/note/` resolving to a
+   published note. Anything else (home page, tag pages, drafts, unknown
+   slugs) is refused (v2.7.0; before, such mentions were stored but never
+   shown).
+8. UPSERT into `webmentions` on `(source_url, target_url)`: a new row is
+   `pending`/`pending`; an existing row is set back to
+   `validation_status = 'pending'` (an update or removal, spec 3.2.4),
+   keeping its moderation status.
+
+All fetching happens later in the worker (spec 3.2: asynchronous
+verification).
+
+### Responses (JSON)
+
+| Status | Body | When |
+|---|---|---|
+| 202 | `{"status": "accepted", "message": "Webmention queued for verification"}` | Stored |
+| 400 | `{"error": "invalid_request", "error_description": "Missing required parameter: source"}` (or `target`) | Missing parameter |
+| 400 | `invalid_request` / "Source must be a valid URL", "Target must be a valid URL" | Bad URL |
+| 400 | `invalid_request` / "Source and target must be different" | Same URL |
+| 400 | `invalid_target` / "Target URL is not on this site" | Other host |
+| 400 | `invalid_target` / "Target URL does not accept webmentions" | Not a published note |
+| 429 | `rate_limit_exceeded` with `Retry-After` | Rate limited |
+| 500 | `server_error` / "Failed to queue webmention" | Database error |
+
+## `GET /webmention`
+
+Returns `{"name": "Webmention endpoint", "spec": "https://www.w3.org/TR/webmention/"}`.
+Not rate limited.
+
+## Deleted targets
+
+A soft-deleted note's page answers **410 Gone** ("This post has been
+deleted", v2.7.0), so senders can tell the post is gone. New webmentions to
+it are refused (step 7).
+
+## Content sanitisation (stored snippets)
+
+`webmention_processor.sanitize_content()` uses `nh3`:
+
+- Allowed tags: `p, br, strong, em, b, i, a, code, pre, blockquote`.
+- Allowed attributes: `a[href]`; nh3 adds `rel="nofollow noopener"` to links
+  (the original contract listed `a[href, rel]`; `rel` is set by nh3 rather
+  than passed through).
+- Snippets are cut to ~500 characters and sanitised again so a cut never
+  leaves a tag open (v2.7.0).
+- Author URL and photo are stored only if http(s) (v2.6.9); everything is
+  rendered through Jinja autoescaping except the sanitised snippet.
+
+## Extracted fields
+
+`process_webmention()` returns: `mention_type` (`reply`, `like`, `repost`,
+`bookmark`, `mention`), `author_name`, `author_url`, `author_photo`,
+`content_snippet`, `source_post_url`, `source_uid`, `source_published`
+(RFC 3339 UTC). See [background-worker.md](background-worker.md) for how
+each is derived and [database-schema.md](database-schema.md) for storage.
+
+## Sending (our requests to others)
+
+- Endpoint discovery and POST as in [background-worker.md](background-worker.md).
+- Body: `source=&target=`, form-encoded.
+- `User-Agent: StarPunk/ Webmention (+)`.
+- Any 2xx is success; redirects from the endpoint are not followed and
+  count as failure (v2.7.0).
diff --git a/docs/design/v1.6.0/background-worker.md b/docs/design/v1.6.0/background-worker.md
new file mode 100644
index 0000000..10371ca
--- /dev/null
+++ b/docs/design/v1.6.0/background-worker.md
@@ -0,0 +1,196 @@
+# v1.6.0 Design: Webmention Background Worker
+
+> Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG).
+> Also affected by v2.8.0 (source details, authorship, own-crosspost filter) and v2.10.1 (hard time limit on fetches). This describes the code as of v2.10.1.
+
+Related: ADR-063 (Webmention implementation), [api-contract.md](api-contract.md),
+[database-schema.md](database-schema.md), [rate-limiting.md](rate-limiting.md),
+[display-moderation.md](display-moderation.md).
+
+## Purpose
+
+Webmention work that involves fetching remote URLs never happens inside a
+request. `POST /webmention` only stores a row; a background thread validates
+incoming webmentions and sends outgoing ones.
+
+## Modules
+
+| Module | Role |
+|---|---|
+| `starpunk/webmention_worker.py` | `WebmentionWorker` thread: queue loop, validation bookkeeping, endpoint discovery, sending, retries |
+| `starpunk/webmention_processor.py` | Fetch source, verify link, parse mf2, extract type/author/content |
+| `starpunk/webmention_sender.py` | Extract links from a note and queue outgoing webmentions |
+| `starpunk/webmention_ssrf.py` | `safe_get` / `safe_post`: SSRF-checked, address-pinned HTTP |
+| `starpunk/reply_context.py` | Fetch context for reply/like/repost targets (synchronous, see below) |
+
+## Thread lifecycle
+
+- Started in `create_app()` (`starpunk/__init__.py`) when
+  `WEBMENTION_WORKER_ENABLED` is true and `TESTING` is false. Stored as
+  `app.webmention_worker`. Daemon thread named `webmention-worker`, following
+  the `MemoryMonitor` pattern (a `threading.Event` for stop).
+- There is no teardown hook: until v2.6.8 a `teardown_appcontext` handler
+  stopped the worker after the first request.
+- Each poll runs inside `app.app_context()` (v2.6.8), because the SSRF checks
+  read `current_app.config` (`DEV_MODE`).
+- `stop()` sets the event; the loop exits after the current pass.
+
+### One worker across processes (v2.6.9)
+
+Every gunicorn process starts a worker. Only the one holding an exclusive,
+non-blocking `fcntl.flock` on `/webmention-worker.lock` processes the
+queues; the others poll the lock every `poll_interval`. The OS releases the
+lock when the holder dies, so another process takes over.
+
+### Orphan cleanup
+
+When a worker first acquires the lock it resets `webmention_queue` rows stuck
+in `sending` for more than 5 minutes back to `pending` (a previous holder
+crashed mid-send).
+
+## Main loop
+
+```
+while not stopped:
+    if not lock acquired: wait poll_interval; continue
+    with app.app_context():
+        n  = process pending validations (incoming, oldest received first, batch_size)
+        n += process pending sends (outgoing, due rows, oldest first, batch_size)
+    if n == 0: wait poll_interval
+    on unexpected error: log, wait error_backoff
+```
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `WEBMENTION_WORKER_ENABLED` | true | Start the thread |
+| `WEBMENTION_POLL_INTERVAL` | 10 s | Sleep when idle / lock not held |
+| `WEBMENTION_ERROR_BACKOFF` | 60 s | Sleep after a loop error |
+| `WEBMENTION_BATCH_SIZE` | 5 | Rows per queue per pass |
+| `WEBMENTION_AUTO_APPROVE` | true | New valid mentions start `approved` (else `pending`) |
+
+`get_stats()` (running, last_processed, pending_validations, pending_sends)
+is included in the basic (unauthenticated) `/health` response. Note it reports
+the worker of whichever process answers, which may not hold the lock.
+
+## Incoming: validation
+
+For each `webmentions` row with `validation_status = 'pending'`:
+
+1. `process_webmention(source, target, SITE_URL)`:
+   - `fetch_source`: `safe_get` with an `Accept` header preferring HTML,
+     following redirects (each hop checked). 4xx, SSRF block or >1 MB is a
+     `ValidationError`; network error, timeout, 3xx without location or 5xx is
+     a `TransientError`.
+   - `verify_link_presence` (spec 3.2.2): exact target match, fragments
+     ignored. HTML: any link-bearing attribute after resolving relative URLs
+     against the final URL; JSON: any string value; other `text/*`:
+     substring. Fails with "Source does not link to target".
+   - HTML only: `mf2py.parse`, then `mf2_utils.responding_entry` picks the
+     h-entry that responds to the target; `response_type` gives `reply`,
+     `like`, `repost`, `bookmark` or `mention`; `entry_author` applies the
+     authorship algorithm without extra fetches; `extract_content` takes
+     `e-content` (else `p-summary`) as a sanitized snippet of at most ~500
+     characters; `extract_source_details` gives the entry's `u-url`, `u-uid`
+     and `dt-published` (v2.8.0).
+   - Author URL and photo are kept only if they are http(s) URLs (v2.6.9);
+     the author URL falls back to the source, the name to its host.
+2. If the source is one of the target note's own `u-syndication` copies
+   (`syndications.remote_url`, compared normalised), it is rejected (v2.8.0).
+3. Success: the row becomes `valid` with the extracted fields. Moderation:
+   a first-time valid mention gets `approved`/`pending` per
+   `WEBMENTION_AUTO_APPROVE`; a mention that was valid before keeps its
+   moderation status, and `hidden`/`deleted` are never overwritten (v2.7.0).
+4. Failure (`_mark_validation_failed`):
+   - Transient error and the mention was valid before (`validated_at` set,
+     no `validation_error`): restored to `valid` with its old data; nothing
+     disappears because the source was briefly down (v2.7.0).
+   - "does not link", "returned 4xx" or own syndicated copy: `invalid`.
+   - Anything else: `error`. Either way the error text is stored and the
+     mention is no longer displayed (spec 3.2.4 for 410/no link).
+
+### Displayed responses are an update (v2.7.2, spec 3.1.4)
+
+`_validate_webmention` compares `_display_state()` (what the note shows for
+this mention: type, author, photo, snippet; `None` if hidden) before and
+after validation. If it changed, `webmention_sender.note_responses_changed`
+re-queues the target note's previously sent webmentions. A re-validation
+that changes nothing sends nothing, so two sites doing the same don't
+ping-pong.
+
+## Outgoing: queueing
+
+`webmention_sender.queue_webmentions_for_note()` is called by `notes.py`
+after the note is committed, best-effort (failures are logged, never fail the
+note):
+
+- **Create** (published only): the response target first (`in_reply_to`,
+  else `like_of`, `repost_of`, `bookmark_of`), then `` links from the
+  rendered HTML in document order; links inside `
`/`` are skipped
+  (including a top-level `
`, v2.7.0); only absolute http(s) URLs;
+  de-duplicated; at most 10 ("architect's answer to Q1").
+- **Update** ("Phase 6" answers): queued when a note is published or
+  unpublished, or a published note's content or reply target changes. The
+  current targets (capped at 10) plus every target this note was queued for
+  before and every link the edit removed (not capped), so receivers can
+  update or remove the mention (v2.7.0).
+- **Delete / undelete** (spec 3.1.5): `requeue_previous_webmentions` resets
+  all of the note's queue rows to `pending`; on hard delete with
+  `detach=True` the `source_note_id` is cleared so the rows survive the
+  cascade.
+- Rows are UPSERTed on `(source_url, target_url)`; re-queueing resets
+  status, retry count, error and `endpoint_url`.
+
+## Outgoing: sending
+
+For each due `webmention_queue` row (`pending`, `next_retry_at` null or
+past):
+
+1. Mark `sending` with `started_at`.
+2. Discover the endpoint (spec 3.1.2), every time (the v1.6.0 1–24 h
+   discovery cache was removed in v2.7.0): `safe_get` the target; 5xx raises
+   (retry); 4xx, blocked or too large means no endpoint. The first `Link`
+   header with `rel` containing the token `webmention` (case-insensitive,
+   several headers and multi-value rels handled) wins, then the first
+   ``/`` with that rel and an `href`, in document order. Relative
+   URLs resolve against the final URL; an empty `href` is the target itself.
+   No endpoint: status `no_endpoint` (permanent).
+3. POST `source`/`target` form-encoded with `safe_post` (no redirects).
+   2xx: `sent`. 429 or 5xx: retry. Other (3xx, 4xx): `failed`. Network
+   error: retry. SSRF block: `failed`.
+
+### Retries ("architect's answer to Q5")
+
+`retry_count` is incremented after the failed attempt; at 4 the row is
+`failed`. Delays after attempt 1, 2, 3: 1 h, 6 h, 24 h.
+
+## Outbound safety (`webmention_ssrf.py`)
+
+Used for every fetch and send (and since v2.9.0/v2.10.0 by Micropub photo
+fetches and the WebSub hub):
+
+- http(s) only; every address the host resolves to must be public (blocks
+  private, loopback, link-local, multicast, reserved, unspecified, CGNAT,
+  `0.0.0.0/8`, IPv4-mapped forms). `DEV_MODE` allows `localhost`.
+- The connection goes to the checked address; the hostname is sent in
+  `Host` and TLS SNI so certificates are still verified (v2.7.2). IPv4
+  preferred.
+- Redirects followed by hand, each hop checked, at most 10; 1 MB body
+  limit; 10 s total time limit enforced by a watchdog that closes the client
+  (v2.10.1).
+- User-Agent `StarPunk/ Webmention (+SITE_URL)`.
+
+## Reply context
+
+`reply_context.fetch_reply_context()` is not run by the worker: `notes.py`
+calls it synchronously after creating a reply/like/repost/bookmark (or when
+an update sets `in_reply_to`). See [database-schema.md](database-schema.md).
+
+## Known limits
+
+- A DNS failure while fetching a source (`ResolutionError`, a `ValueError`)
+  is treated as a blocked request, i.e. a permanent `error`, not a transient
+  one; the WebSub worker retries DNS failures, the webmention worker does not.
+- Between receipt of a re-sent webmention and its re-validation the row is
+  `pending` and not shown on the note (`get_webmentions_for_note` requires
+  `valid`), although `_display_state` counts it as shown.
+- The worker opens its own `sqlite3` connections (not the request pool).
diff --git a/docs/design/v1.6.0/database-schema.md b/docs/design/v1.6.0/database-schema.md
new file mode 100644
index 0000000..9d727ed
--- /dev/null
+++ b/docs/design/v1.6.0/database-schema.md
@@ -0,0 +1,102 @@
+# v1.6.0 Design: Webmention Database Schema
+
+> Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG).
+> Schema from `migrations/010_add_webmentions.sql` plus `014_webmention_source_details.sql` (v2.8.0). The original document's story numbering is only known for Story 2.4 (reply context), cited in `starpunk/reply_context.py`.
+
+Related: ADR-063, [background-worker.md](background-worker.md),
+[display-moderation.md](display-moderation.md).
+
+## Migration 010 (v1.6.0)
+
+### `notes.in_reply_to TEXT`
+
+URL the note replies to. Later migrations added `like_of`, `repost_of`
+(013, v2.5.0) and `bookmark_of` (015, v2.9.0); `Note.reacts_to` is the first
+of these that is set.
+
+### `webmentions` (received)
+
+| Column | Notes |
+|---|---|
+| `id` | PK |
+| `source_url`, `target_url` | NOT NULL; `UNIQUE(source_url, target_url)`; target stored without fragment (v2.7.0) |
+| `target_note_id` | FK `notes(id)` ON DELETE SET NULL; always set for new rows since v2.7.0 (only notes accept webmentions) |
+| `mention_type` | `reply`, `like`, `repost`, `bookmark`, `mention` (default `mention`) |
+| `author_name`, `author_url`, `author_photo` | From the authorship algorithm; URLs http(s) only |
+| `content_snippet` | Sanitised HTML, ~500 chars max |
+| `validation_status` | `pending` (default), `valid`, `invalid`, `error` |
+| `moderation_status` | `pending` (default), `approved`, `hidden`, `deleted` |
+| `validation_error` | Last error text, NULL when valid |
+| `validated_at` | Last validation attempt; with `validation_error IS NULL` it means "was valid before" |
+| `received_at`, `updated_at` | Timestamps |
+| `source_post_url`, `source_published` | Migration 014 (v2.8.0): the source h-entry's `u-url` and `dt-published` (UTC) |
+
+Indexes: `target_note_id`, `moderation_status`, `validation_status`,
+`received_at DESC`.
+
+Notes:
+- `moderation_status = 'deleted'` is allowed by the CHECK but unused: admin
+  delete removes the row (`DELETE`). Validation never overwrites `hidden` or
+  `deleted`.
+- A row is shown on a note only if `valid` and `approved`.
+
+### `webmention_queue` (sent)
+
+| Column | Notes |
+|---|---|
+| `source_url` | Our note's permalink (built from `SITE_URL`) |
+| `target_url` | `UNIQUE(source_url, target_url)` |
+| `source_note_id` | FK `notes(id)` ON DELETE CASCADE; cleared (`detach`) before a hard delete so the re-sent rows survive |
+| `endpoint_url` | Endpoint found by the current attempt; reset on every re-queue (no cross-attempt cache since v2.7.0) |
+| `status` | `pending`, `sending`, `sent`, `failed`, `no_endpoint` |
+| `retry_count`, `next_retry_at`, `last_error` | Retry schedule 1 h / 6 h / 24 h, failed at 4 |
+| `created_at`, `started_at`, `sent_at` | `started_at` drives orphan cleanup (>5 min in `sending`) |
+
+Indexes: `status`, `next_retry_at`, `source_note_id`.
+
+### `reply_contexts` (cache of what a note responds to)
+
+| Column | Notes |
+|---|---|
+| `url` | UNIQUE; the `in_reply_to` / `like_of` / `repost_of` / `bookmark_of` URL |
+| `title` | h-entry `p-name`, max 200 chars |
+| `content_snippet` | Via `extract_content` |
+| `published_at` | h-entry `dt-published` parsed with dateutil |
+| `author_name`, `author_url`, `author_photo` | Via `extract_author` |
+| `site_name` | First top-level h-card's name |
+| `fetch_status` | `pending`, `fetched`, `error` |
+| `fetch_error`, `fetched_at`, `created_at` | |
+
+## Story 2.4: reply context
+
+`starpunk/reply_context.py`, called synchronously from `notes.create_note`
+(for any response URL) and `notes.update_note` (when `in_reply_to` is set),
+best-effort:
+
+1. If a row for the URL exists, return it (never refreshed).
+2. Fetch with `webmention_processor.fetch_source` (SSRF-safe).
+3. Non-HTML: store an `error` row ("Not HTML content").
+4. Parse mf2; take the first top-level h-entry's name, content and
+   published time, and the author; store as `fetched` (`INSERT OR REPLACE`).
+5. Any failure stores an `error` row; note creation is never affected.
+
+Read side: `webmention_queries.get_reply_context(url)` for the note page
+(`in_reply_to` h-cite), `routes.public.attach_contexts` for likes/reposts
+(title and author lines, v2.5.0) and `syndication._target_title` for
+crosspost text.
+
+### Known defect (found during reconstruction)
+
+Since v2.7.0, `fetch_source()` returns `(content, content_type, final_url)`,
+but `fetch_reply_context()` still unpacks two values. The resulting
+`ValueError` is caught by the generic handler, so every new URL gets an
+`error` row ("Unexpected error: too many values to unpack") and no context.
+Rows fetched before v2.7.0 are unaffected (they are never refreshed).
+Tests replace `fetch_reply_context` with a stub, so this is not covered.
+
+## Later schema touching webmentions
+
+- 012 (v2.1.0) `syndications`: used to reject a note's own crossposts as
+  sources (v2.8.0).
+- 013 / 015: response URL columns on `notes`, which become the first
+  outgoing webmention target.
diff --git a/docs/design/v1.6.0/display-moderation.md b/docs/design/v1.6.0/display-moderation.md
new file mode 100644
index 0000000..0b45f41
--- /dev/null
+++ b/docs/design/v1.6.0/display-moderation.md
@@ -0,0 +1,89 @@
+# v1.6.0 Design: Webmention Display and Moderation
+
+> Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG).
+> Display markup was reworked in v2.8.0 (microformats2 review). Describes `starpunk/webmention_queries.py`, `starpunk/routes/admin.py`, `starpunk/routes/public.py`, `templates/note.html` and `templates/partials/responses.html` as of v2.10.1.
+
+Related: ADR-063, [background-worker.md](background-worker.md),
+[database-schema.md](database-schema.md).
+
+## States
+
+A received webmention has two independent states:
+
+- `validation_status` (set by the worker): `pending`, `valid`, `invalid`, `error`.
+- `moderation_status` (set by the worker on first validation, then by the
+  admin): `pending`, `approved`, `hidden` (`deleted` exists in the schema but
+  deleting removes the row).
+
+A webmention is **shown** only when `valid` AND `approved`.
+`WEBMENTION_AUTO_APPROVE=true` (default) makes a first-time valid mention
+`approved`; with `false` it waits as `pending` for the admin. Re-validation
+of a previously valid mention keeps the admin's decision (v2.7.0).
+
+## Public display
+
+`get_webmentions_for_note(note_id)` returns shown webmentions for a note,
+ordered by type (reply, like, repost, bookmark, mention) then `received_at`
+ascending, grouped into `replies`, `likes`, `reposts`, `bookmarks`,
+`mentions`. `received_at` and `source_published` are parsed to datetimes
+(unparseable `source_published` becomes `None`).
+
+`routes/public.note` loads them only when `WEBMENTION_ENABLED`; errors are
+logged and the page renders without them. The "Webmentions" section is
+rendered only if at least one group is non-empty, with a heading and count
+per group.
+
+Markup (v2.8.0, `partials/responses.html`), each response an `h-cite` in a
+property of the note's `h-entry`:
+
+| Group | Property | Presentation |
+|---|---|---|
+| Replies | `u-comment h-cite` | Author card (name, link, 48px photo), sanitised `e-content` snippet, date link |
+| Likes, reposts, bookmarks | `u-like` / `u-repost` / `u-bookmark` `h-cite` | Facepile of 32px photos (or a coloured initial); faces after the 8th are `hidden` on screen but stay in the markup for parsers, with "+N others" |
+| Mentions | `u-mention h-cite` | Small author card, snippet with tags stripped and truncated to 200 chars |
+
+- The response's link is the source's `u-url` (`source_post_url`) if given,
+  else the webmention source; its date is `source_published`, else
+  `received_at`, in UTC with `Z`.
+- The author `h-card` puts `u-url` on an inner link, so it isn't read as the
+  `h-cite`'s URL.
+- Snippets are stored sanitised (see [api-contract.md](api-contract.md)) and
+  output with `|safe`; all other fields are autoescaped.
+
+## Admin moderation
+
+All routes `@require_auth`, under `/admin`:
+
+| Route | Purpose |
+|---|---|
+| `GET /admin/webmentions?status=&page=` | List, newest received first, 25 per page; filter tabs All / Pending / Approved / Hidden (by `moderation_status`) |
+| `GET /admin/webmentions/` | Detail: source, target (note link), type, author, snippet, validation status and error, timestamps, actions |
+| `POST /admin/webmentions//action` | `action` = `approve` / `hide` / `delete` |
+| `POST /admin/webmentions/bulk-action` | Same actions for `ids` (checkboxes) |
+
+The dashboard shows a badge with the number of `pending` (moderation)
+webmentions.
+
+Query functions: `list_webmentions`, `get_webmention`, `count_webmentions`,
+`update_webmention_status(ids, status)` (only `approved`, `hidden`,
+`pending`), `delete_webmentions(ids)` (hard delete).
+
+### Moderation changes re-send webmentions (v2.7.2, spec 3.1.4)
+
+Before an update or delete, `_visibility_changes()` finds the target notes
+of valid webmentions whose shown/not-shown state changes. After the commit,
+`_notify_responses_changed()` calls
+`webmention_sender.note_responses_changed()`, which re-queues every
+webmention the (published, undeleted) note sent before. Best effort:
+failures are logged.
+
+## Known limits
+
+- The admin list filters and shows only moderation status; validation
+  status and error appear on the detail page. A mention that never
+  validated keeps the default `moderation_status = 'pending'`, so it is
+  listed under Pending and counted in the dashboard badge although there is
+  nothing to approve.
+- A webmention re-sent by its source is `pending` until the worker
+  re-validates it (seconds), and is not shown during that time.
+- Hidden or invalid webmentions are kept indefinitely; there is no pruning.
diff --git a/docs/design/v1.6.0/rate-limiting.md b/docs/design/v1.6.0/rate-limiting.md
new file mode 100644
index 0000000..f6083d7
--- /dev/null
+++ b/docs/design/v1.6.0/rate-limiting.md
@@ -0,0 +1,84 @@
+# v1.6.0 Design: Webmention Rate Limiting
+
+> Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG).
+> The rate limiter itself has not changed since v1.6.0; v2.10.0 reused `RateLimiter` for the WebSub hub. Describes `starpunk/rate_limiter.py` and `starpunk/routes/webmention.py` as of v2.10.1.
+
+Related: ADR-063, [api-contract.md](api-contract.md).
+
+**Note on ADR numbering:** the code cites "ADR-064: Webmention Rate
+Limiting". In this repository ADR-064 is the OIDC admin login decision
+(v2.0.0); the webmention rate-limiting ADR from v1.6.0 was lost with the
+other v1.6.0 documents and its number was reused. This document is the
+surviving description of that decision.
+
+## Goal
+
+Stop `POST /webmention` from being used to fill the database or the
+validation queue (each accepted webmention costs one outbound fetch).
+
+## Algorithm
+
+`RateLimiter(limit, window_seconds)`: sliding-window log, in memory.
+
+- Per key, a list of request timestamps (`time.time()`), guarded by one
+  `threading.Lock`.
+- `is_allowed(key)`: drop timestamps older than the window; if the count is
+  `>= limit` refuse (not recorded); otherwise record and allow.
+- `get_retry_after(key)`: seconds until the oldest timestamp leaves the
+  window, clamped to 1..window.
+- `cleanup(max_idle_seconds=300)`: drop keys with no recent requests.
+- `get_request_count(key)`: current count (tests/logging).
+
+In-memory state was chosen to match the other in-process caches (the
+v1.6.0 code cites the worker's endpoint `_discovery_cache`, removed in
+v2.7.0); no new table, no Redis.
+
+## Webmention limits
+
+Two module-level limiters, created by `init_rate_limiters(app)` in
+`create_app()`:
+
+| Setting | Default | Key |
+|---|---|---|
+| `WEBMENTION_RATE_LIMIT_ENABLED` | true | Off: both limiters are `None`, everything allowed |
+| `WEBMENTION_RATE_LIMIT_IP` | 60 | Client IP |
+| `WEBMENTION_RATE_LIMIT_DOMAIN` | 10 | Host (`netloc`) of the `source` URL |
+| `WEBMENTION_RATE_LIMIT_WINDOW` | 60 s | Both |
+
+`check_rate_limit(ip, source_domain)` checks the IP first, then the source
+domain (if one could be parsed). Only POST is limited, in the webmention
+blueprint's `before_request`, before any validation, reading `source` from
+the form or JSON body.
+
+Client IP (`get_client_ip`): the first `X-Forwarded-For` entry when
+`TRUSTED_PROXY=true`, else `request.remote_addr`. Behind Caddy without
+`TRUSTED_PROXY` every client shares the proxy's address (documented in
+`.env.example` since v2.10.1).
+
+## Response
+
+```
+HTTP/1.1 429
+Retry-After: 
+{"error": "rate_limit_exceeded",
+ "error_description": "Too many requests from your IP. Please retry after N seconds."}
+```
+
+The description carries the computed wait; the `Retry-After` header carries
+the full window.
+
+## Other users
+
+`routes/websub.py` (v2.10.0) has its own `RateLimiter(30, 60)` per client
+IP for subscription requests, calling `cleanup()` every 500 requests.
+
+## Known limits
+
+- Counters are per gunicorn process, so the effective limit is up to
+  limit × processes, and they reset on restart.
+- `cleanup_rate_limiters()` exists but nothing calls it, so the webmention
+  limiters never drop a key (old timestamps are trimmed when the key is
+  checked again, but the key stays); memory grows slowly with distinct
+  client IPs and source domains until the process restarts.
+- Requests refused by the IP limit are not recorded, and a request refused
+  by the domain limit has already been counted against the IP.
diff --git a/docs/design/v2.0.1/2026-10-31-absolute-urls-and-ci-buildkit.md b/docs/design/v2.0.1/2026-10-31-absolute-urls-and-ci-buildkit.md
new file mode 100644
index 0000000..8e5c4c9
--- /dev/null
+++ b/docs/design/v2.0.1/2026-10-31-absolute-urls-and-ci-buildkit.md
@@ -0,0 +1,38 @@
+# v2.0.1: Absolute URLs from SITE_URL; CI builds with BuildKit
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commits `b4e6cf3`, `2d0568d`.
+
+## Summary
+
+Behind Caddy the app is reached over plain HTTP, so
+`url_for(..., _external=True)` produced `http://` links on the https site:
+RSS/OPML ``s and the microformats `u-url`/`u-uid` permalinks that
+IndieWeb parsers treat as canonical. Separately, the container workflow
+had never succeeded.
+
+## Changes
+
+- `starpunk/utils.py`: new `absolute_url_for(endpoint, **values)` =
+  `SITE_URL` (trailing slash stripped) + `url_for(endpoint, **values)`.
+  Registered as a Jinja global in `create_app()`.
+- `templates/base.html`, `index.html`, `note.html`, `tag.html`: absolute
+  URLs use `absolute_url_for()`.
+- `starpunk/indieauth.py`, `starpunk/routes/indieauth.py`: the IndieAuth
+  metadata used its own SITE_URL helper; it now shares `absolute_url_for()`.
+- `.gitea/workflows/build-container.yml`: the runner no longer has a Docker
+  daemon. Build with `docker buildx` against the rootless BuildKit socket
+  (`unix:///run/buildkit/buildkit/buildkitd.sock`, remote driver) and log in
+  to `git.thesatelliteoflove.com` (the old workflow logged in to
+  `gitea:3000`, which did not resolve). Image name is lower-cased.
+
+## Tests
+
+`tests/test_absolute_urls.py`: links in pages and feeds use `SITE_URL`
+even when the request arrives over http.
+
+## Notes
+
+- Any new absolute URL must use `absolute_url_for()`, not `_external=True`
+  (later used for outgoing webmention source URLs, v2.5.0).
+- The registry login still used the automatic Actions token, which the
+  registry refused; fixed in v2.0.2.
diff --git a/docs/design/v2.0.2/2026-10-31-ci-registry-token.md b/docs/design/v2.0.2/2026-10-31-ci-registry-token.md
new file mode 100644
index 0000000..7167ae2
--- /dev/null
+++ b/docs/design/v2.0.2/2026-10-31-ci-registry-token.md
@@ -0,0 +1,25 @@
+# v2.0.2: CI registry login with REGISTRY_TOKEN
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commits `011f7cc`, `94e8c67`.
+
+## Summary
+
+Release images still failed to push: the registry refused the automatic
+Gitea Actions token (run 107: unauthorized). No application changes.
+
+## Changes
+
+- `.gitea/workflows/build-container.yml`: `docker login` uses the
+  repository secret `REGISTRY_TOKEN` (a personal access token with only
+  `write:package`) as `github.repository_owner`, instead of
+  `GITHUB_TOKEN` / `github.actor`.
+- `starpunk/__init__.py`: version 2.0.2.
+
+## Tests
+
+None (CI only). Verified by the release workflow pushing the v2.0.2 image.
+
+## Notes
+
+The `REGISTRY_TOKEN` secret must exist in the repository settings for
+releases to publish.
diff --git a/docs/design/v2.1.0/2026-10-31-gotosocial-crossposting.md b/docs/design/v2.1.0/2026-10-31-gotosocial-crossposting.md
new file mode 100644
index 0000000..e848023
--- /dev/null
+++ b/docs/design/v2.1.0/2026-10-31-gotosocial-crossposting.md
@@ -0,0 +1,52 @@
+# v2.1.0: Crossposting to GoToSocial
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `57b02ad`. Design: ADR-065.
+
+## Summary
+
+Published notes are copied to a GoToSocial (or any Mastodon-API) account;
+edits, unpublishing and deletes follow. Replaces Echofeed for this target.
+Also fixes three `/notes/` (404) links and a nested form.
+
+## Changes
+
+- `migrations/012_add_syndications.sql`: `syndications` table, one row per
+  (note, target), `UNIQUE(note_id, target)`: `enabled`, `remote_id`,
+  `remote_url`, `state` (`pending`/`synced`/`failed`), `version`,
+  `attempts`, `last_error`, `next_attempt_at`, `claimed_until`. `note_id` has no foreign key so a hard-deleted note's remote post
+  can still be deleted.
+- `starpunk/syndication.py` (new):
+  - `MastodonClient`: media upload (large variant, caption as alt text),
+    create/update (`PUT /api/v1/statuses/:id`)/delete status,
+    `Idempotency-Key` on create.
+  - `Target`, `get_targets()`, `resolve_targets()`, `select_targets()`;
+    `note_changed(note_id)` marks a note's rows pending.
+  - `compose_text()`: note Markdown + permalink + tags as hashtags,
+    shortened at a word boundary with the link kept.
+  - `process_due()` / `_claim()` / `_reconcile()` / `_finish()` / `_fail()`:
+    rows claimed atomically (one sender across gunicorn processes),
+    `version` keeps edits made during a send, network/5xx/429 retried with
+    exponential backoff (8 attempts), other 4xx fail at once.
+  - `SyndicationWorker` thread started in `create_app()` when a target is
+    configured.
+- `starpunk/notes.py`: create/update/delete call `syndication.note_changed`.
+- `starpunk/micropub.py`: `mp-syndicate-to` selects targets; `q=syndicate-to`
+  and `q=config` list them; `Location` header uses the real permalink.
+- `starpunk/routes/admin.py`, `templates/admin/new.html`, `edit.html`:
+  per-target checkboxes (on by default for new notes), status, last error
+  and a retry button; delete button moved out of the edit form.
+- `templates/note.html`: synced copies as `u-syndication` links.
+- `starpunk/routes/search.py`: result links `/note/`.
+- Config: `GOTOSOCIAL_URL`, `GOTOSOCIAL_ACCESS_TOKEN` (`.env.example`).
+
+## Tests
+
+`tests/test_syndication.py` (25 tests: composition, target selection,
+claim/retry/version handling, delete and edit follow-up, Micropub
+`mp-syndicate-to`); path fixes in Micropub and search tests.
+
+## Notes
+
+- Existing notes are never backfilled.
+- Echofeed must stop posting to GoToSocial or posts appear twice.
+- A remote post deleted by hand is re-created on the next edit.
diff --git a/docs/design/v2.10.0/2026-11-03-websub-implementation.md b/docs/design/v2.10.0/2026-11-03-websub-implementation.md
new file mode 100644
index 0000000..9b3f81f
--- /dev/null
+++ b/docs/design/v2.10.0/2026-11-03-websub-implementation.md
@@ -0,0 +1,60 @@
+# v2.10.0: WebSub with a built-in hub (implementation report)
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commits `720a1e6` (ADR, proposed), `b520b8b`.
+
+## Design
+
+[ADR-071](../../decisions/ADR-071-websub.md), sections 1–11. This report
+covers where it was implemented and how it was verified; it does not repeat
+the design.
+
+## Changes
+
+- `starpunk/websub.py` (new): topics (`topic_url`, `tag_topic`,
+  `canonical_topic`, `topic_for_request`), discovery (`add_discovery_headers`
+  after-request hook for `Link: rel=hub` / `rel=self`, `template_links` for
+  ``s in HTML, `embed_hub` for Atom/RSS/JSON Feed), change tracking
+  (`note_changed`, `queue_topics`, `get_content_version` /
+  `bump_content_version`), subscription requests
+  (`accept_subscription_request`), signing (`signature`: HMAC-SHA256),
+  `stats` for the dashboard.
+- `starpunk/websub_worker.py` (new): `WebSubWorker`, one per gunicorn
+  process with a file lock so one process works the queues (webmention
+  worker pattern): `verify` (challenge GET), `render_topic` (renders inside
+  the app), `deliver` (signed POST, retries), `prune` (expired leases).
+- `starpunk/routes/websub.py` (new): `POST /websub`, 202 on accept,
+  plain-text 4xx otherwise, per-IP `RateLimiter(30, 60)`.
+- `migrations/016_websub.sql`: `websub_subscriptions`, `websub_intents`,
+  `websub_deliveries` (one per subscription, or per topic for pings to an
+  external hub), and `site_state.content_version`.
+- `starpunk/notes.py`, `starpunk/micropub.py`: create/update/delete call
+  `websub.note_changed` (via `_websub_changed`), which bumps the content
+  version (all processes' feed caches go stale at once) and queues
+  deliveries.
+- `starpunk/webmention_ssrf.py`: `safe_post` takes a raw body and reads
+  only a capped response; used for verification and delivery.
+- `starpunk/feeds/rss.py`: self link `/feed.rss` (was `/feed.xml`).
+- `starpunk/__init__.py`: discovery hook, worker start; the memory monitor's
+  `teardown_appcontext` stop removed (it stopped after the first request).
+- `starpunk/routes/admin.py`, `templates/admin/dashboard.html`: subscribers
+  per topic, failing deliveries.
+- Config: `WEBSUB_ENABLED`, `WEBSUB_HUB_URL`, `WEBSUB_MAX_SUBSCRIPTIONS`,
+  `WEBSUB_MAX_PER_HOST`.
+
+## Tests
+
+`tests/test_websub.py` (23 tests: discovery on every topic and format,
+external hub, request validation, private callbacks, per-host limit,
+verification success/failure, unsubscribe, re-subscribe, signed delivery,
+drafts, tag topics incl. removed tags, delete, 410, retries, expiry, fresh
+feed after posting).
+
+## Verification
+
+Deployed to production; the websub.rocks publisher test passed against the
+live site.
+
+## Notes
+
+An adversarial review after release found worker, time-limit, lease and
+spec 5.1 issues; fixed in v2.10.1 (ADR-071 Amendments).
diff --git a/docs/design/v2.10.1/2026-11-03-websub-hardening.md b/docs/design/v2.10.1/2026-11-03-websub-hardening.md
new file mode 100644
index 0000000..25bd1fb
--- /dev/null
+++ b/docs/design/v2.10.1/2026-11-03-websub-hardening.md
@@ -0,0 +1,53 @@
+# v2.10.1: WebSub hardening (implementation report)
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `b204328`.
+
+## Design
+
+[ADR-071](../../decisions/ADR-071-websub.md), "Amendments (v2.10.1)",
+from an adversarial review of v2.10.0 against the W3C Recommendation.
+
+## Changes
+
+- `starpunk/websub_worker.py`: each intent/delivery handled in its own
+  try block (an error drops a verification or retries a delivery, never
+  stops the worker); failing subscribers kept until lease end; DNS failures
+  (`ResolutionError`) and render errors retried; a topic rendering 404/410
+  sends `hub.mode=denied` and ends its subscriptions; each topic rendered
+  once per pass; verification replies over 4 KB fail.
+- `starpunk/webmention_ssrf.py`: `_Watchdog` closes the client when the
+  whole exchange exceeds the time limit (10 s), for `safe_get` and
+  `safe_post`, so webmention fetching benefits too; `ResolutionError`
+  distinguishes DNS failures.
+- `starpunk/websub.py`: spec 5.1 fixes (unreserved percent-decoding,
+  requested topic echoed, lease/secret ignored on unsubscribe, empty secret
+  refused); callback validation (printable, ≤2,048 chars, not this site,
+  port 80/443/≥1024, IDNA host); limits count pending requests per callback
+  address, at most 200 pending; likes only queue `/likes` and tag pages;
+  unsubscribe works with an external hub.
+- `starpunk/routes/websub.py`: case-insensitive Content-Type check.
+- `migrations/017_websub_hardening.sql`: `request_id`, `requested_topic`,
+  `callback_ip` on intents; `callback_ip` on subscriptions.
+- `starpunk/media.py`: `attach_media_to_note` announces the note
+  (photos are in the first delivery); `starpunk/notes.py`/`micropub.py`
+  skip the early announcement for notes with photos.
+- `starpunk/feeds/cache.py`, `starpunk/routes/public.py`: cache key and
+  weak ETag from format + notes checksum incl. `content_version` (stable
+  across processes); `/feed` sends `Vary: Accept`.
+- `.env.example`: `TRUSTED_PROXY` and the WebSub settings documented.
+
+## Tests
+
+`tests/test_websub_hardening.py` (24 tests, one or more per amendment:
+oversized challenge, bad and IDN callbacks, per-item errors, photo notes,
+slow callback cut off, lease kept, DNS/render retries, denial for gone
+topics, pending-request limits, spec 5.1 cases, request-id race, render
+once per pass, likes, stable ETag, `Vary: Accept`).
+
+## Verification
+
+Deployed to production; the websub.rocks publisher test passed again.
+
+## Notes
+
+Per-client rate limits only work behind Caddy with `TRUSTED_PROXY=true`.
diff --git a/docs/design/v2.2.0/2026-10-31-bluesky-crossposting.md b/docs/design/v2.2.0/2026-10-31-bluesky-crossposting.md
new file mode 100644
index 0000000..94ba776
--- /dev/null
+++ b/docs/design/v2.2.0/2026-10-31-bluesky-crossposting.md
@@ -0,0 +1,40 @@
+# v2.2.0: Crossposting to Bluesky
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `e92c27a`. Design: ADR-066.
+
+## Summary
+
+A second syndication target, `bluesky`, behind the ADR-065 reconcile loop.
+
+## Changes
+
+- `starpunk/syndication.py`:
+  - `Post`: the note as the clients see it (text, permalink, tags, media).
+    Clients share `create` / `update` / `delete` / `can_edit`; the Mastodon
+    client was adapted (`_prepare`).
+  - `BlueskyClient`: `createSession` with an app password against
+    `BLUESKY_SERVICE`, writes to the PDS from the DID document, token
+    refresh with fallback to a new session; `upload_blob`; `_record`
+    builds the post with facets, images (max 4, alt text, aspect ratio) or a
+    link card; `_find_existing` checks recent posts for one linking to the
+    note before a retried create (no doubles).
+  - `plain_text()` (Markdown rendered and stripped), `bluesky_facets()`
+    (link and hashtag facets in UTF-8 byte offsets), `compose_text()` with a
+    hashtag budget (at most a third), 300-character limit; `_fit_image()`
+    re-encodes images over 1 MB as JPEG.
+  - `targets_configured()` so the worker starts for either target.
+- Config: `BLUESKY_HANDLE`, `BLUESKY_APP_PASSWORD`, `BLUESKY_SERVICE`
+  (default `https://bsky.social`).
+
+## Tests
+
+`tests/test_syndication_bluesky.py` (14 tests: facets and byte offsets,
+truncation, image shrinking, session refresh, duplicate check, delete).
+
+## Notes
+
+- Edits don't follow (`can_edit` false): rewriting the record would break
+  likes and replies. Unpublish, untick and delete remove the post.
+- A post deleted by hand on Bluesky is not re-created.
+- `__version_info__` was left at `(2, 1, 0)` from this release until v2.6.0
+  (`__version__` was correct).
diff --git a/docs/design/v2.3.0/2026-10-31-public-page-restyle.md b/docs/design/v2.3.0/2026-10-31-public-page-restyle.md
new file mode 100644
index 0000000..a5e2624
--- /dev/null
+++ b/docs/design/v2.3.0/2026-10-31-public-page-restyle.md
@@ -0,0 +1,39 @@
+# v2.3.0: Public page restyle
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `cc09098`.
+
+## Summary
+
+A styling pass over the public pages, plus three display bugs: note
+metadata styled as the page footer, previews cut through HTML at 300
+characters, and bare URLs not linked.
+
+## Changes
+
+- `templates/base.html`: compact header with `SITE_NAME`, nav, search;
+  page titles from the note text and `SITE_NAME`.
+- `templates/partials/note_preview.html` (new): shared by `index.html` and
+  `tag.html`; short notes in full, titled notes show a summary and
+  "Read more". One-line metadata: date · #tags · Also on ….
+- `templates/note.html`: same metadata line; author h-card kept for
+  parsers but visually hidden.
+- `static/css/style.css`: serif reading font, dark mode via
+  `prefers-color-scheme`, footer pinned to the bottom, metadata no longer
+  inherits `footer` styles.
+- `starpunk/markdown_ext.py` (new): `BareUrlExtension` links bare
+  `http(s)://` URLs (trailing punctuation excluded) and un-nests a link
+  inside a link.
+- `starpunk/models.py`: `BareUrlExtension()` added to
+  `MARKDOWN_EXTENSIONS` (`extra`, `codehilite`, `nl2br`).
+- "Log in" moved from the header to the footer (reverted in v2.3.1).
+
+## Tests
+
+`tests/test_public_style.py` (4 tests: bare URLs linked, a URL used as
+link text not nested, home page shows full notes and `SITE_NAME`, note
+page metadata line); one assertion updated in
+`tests/test_routes_public.py`.
+
+## Notes
+
+The header only knew about logged-in users on `/admin` pages until v2.3.2.
diff --git a/docs/design/v2.3.1/2026-10-31-login-link-in-header.md b/docs/design/v2.3.1/2026-10-31-login-link-in-header.md
new file mode 100644
index 0000000..e02edda
--- /dev/null
+++ b/docs/design/v2.3.1/2026-10-31-login-link-in-header.md
@@ -0,0 +1,23 @@
+# v2.3.1: "Log in" back in the header
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `2616ef5`.
+
+## Summary
+
+v2.3.0 moved "Log in" to the footer, where it was easy to miss.
+
+## Changes
+
+- `templates/base.html`: the header nav shows "Log in"
+  (`auth.login_form`) when `g.me` is not set, "Dashboard" when it is; the
+  footer link is removed.
+
+## Tests
+
+No new test; an existing test in `tests/test_public_style.py` now also
+checks the header has the login link.
+
+## Notes
+
+Public pages never set `g.me`, so the header always showed "Log in" even
+when logged in; fixed in v2.3.2.
diff --git a/docs/design/v2.3.2/2026-10-31-header-admin-link.md b/docs/design/v2.3.2/2026-10-31-header-admin-link.md
new file mode 100644
index 0000000..a914ae4
--- /dev/null
+++ b/docs/design/v2.3.2/2026-10-31-header-admin-link.md
@@ -0,0 +1,26 @@
+# v2.3.2: Header shows "Admin" when logged in
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `c51cf72`.
+
+## Summary
+
+Only `/admin` routes checked the session, so public pages never knew the
+admin was logged in and the header always said "Log in".
+
+## Changes
+
+- `starpunk/__init__.py`, `before_request`: if the request carries a
+  `starpunk_session` cookie, `auth.verify_session()` is called and
+  `g.user` / `g.me` are set. Requests without the cookie don't touch the
+  database; a verification error is treated as logged out.
+- `templates/base.html`: the logged-in link reads "Admin" (was
+  "Dashboard").
+
+## Tests
+
+`tests/test_public_style.py`: with a valid session the header shows
+"Admin" and no "Log in".
+
+## Notes
+
+Every public request with a session cookie now costs a session lookup.
diff --git a/docs/design/v2.4.0/2026-10-31-micropub-update-delete-drafts.md b/docs/design/v2.4.0/2026-10-31-micropub-update-delete-drafts.md
new file mode 100644
index 0000000..41b471d
--- /dev/null
+++ b/docs/design/v2.4.0/2026-10-31-micropub-update-delete-drafts.md
@@ -0,0 +1,45 @@
+# v2.4.0: Micropub update, delete/undelete, drafts, replies
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `0d3a5cd`. Design: ADR-067.
+
+## Summary
+
+The Micropub endpoint could only create published notes. It now supports
+update, soft delete and undelete, drafts, replies, photos in multipart
+requests and from remote URLs, and the `q=source` / `q=category` queries
+editing apps need.
+
+## Changes
+
+- `starpunk/micropub.py` (largely rewritten):
+  - `handle_create`: `post-status` (`extract_post_status`), `in-reply-to`
+    (`extract_in_reply_to`), multipart uploads (`_save_uploads`), remote
+    photos (`_fetch_remote_photo`: public addresses only, 20 MB, max 4;
+    `_public_address`), own media URLs mapped back to media rows
+    (`_media_id_for_url`); unsupported `h=` types rejected (`_check_type`).
+  - `handle_update` (JSON, `update` scope): delete, then replace, then add,
+    for `content`, `name`, `category`, `photo`, `in-reply-to`,
+    `post-status`; other properties 400; success 204.
+  - `handle_delete` (`delete` scope), with `undelete=True` for undelete.
+  - `handle_query`: `q=source` with or without `url` (list incl. drafts,
+    `limit`/`offset`, `properties[]`), via `note_to_mf2`; `q=category`
+    (`_all_categories`, `filter`); `q=config` lists queries and post types.
+  - `_require_scope`; the media endpoint accepts the `media` scope.
+- `starpunk/notes.py`: `undelete_note(slug)` restores a soft-deleted note
+  and its file from `.trash/`; crossposts removed on delete and re-posted
+  on undelete.
+- `starpunk/routes/micropub.py`: dispatch on `action`; the media endpoint
+  is served at both `/micropub/media` (advertised) and `/media`.
+
+## Tests
+
+`tests/test_micropub_v240.py` (23 tests: each update operation, scopes,
+delete/undelete, drafts, replies, multipart and remote photos, queries);
+`tests/test_micropub.py` updated for the new responses.
+
+## Notes
+
+- `published` can be set on create but not changed by update.
+- Remote photo fetching here used its own public-address check; v2.9.0
+  moved it onto the webmention SSRF fetcher (every redirect checked,
+  pinned connection).
diff --git a/docs/design/v2.5.0/2026-10-31-likes-and-reposts.md b/docs/design/v2.5.0/2026-10-31-likes-and-reposts.md
new file mode 100644
index 0000000..73e764d
--- /dev/null
+++ b/docs/design/v2.5.0/2026-10-31-likes-and-reposts.md
@@ -0,0 +1,51 @@
+# v2.5.0: Likes and reposts
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `e8c1b03`. Design: ADR-068.
+
+## Summary
+
+Micropub `like-of` and `repost-of` (optional comment as content), shown on
+the site, sent a webmention, and crossposted natively where the target is
+on that network. Also fixes outgoing webmention source URLs.
+
+## Changes
+
+- `migrations/013_add_likes_reposts.sql`: `notes.like_of`, `notes.repost_of`.
+- `starpunk/models.py`: `Note.kind`, `Note.reacts_to` (the liked/reposted
+  URL), `Note.feed_html` (repost line + comment for feeds).
+- `starpunk/micropub.py`: `extract_url_property()`; a post with both
+  `like-of` and `repost-of` is rejected; content optional for these.
+- `starpunk/notes.py`: stores the new columns; the reacted-to URL is the
+  first outgoing webmention target and gets a reply context; webmention
+  source URLs built with `absolute_url_for()` (fixes `https://site//note/…`).
+- `starpunk/routes/public.py`: likes excluded from the home page; new
+  `/likes` page (`templates/likes.html`, linked in the header);
+  `attach_contexts()` gives each like/repost its cached reply context.
+- `templates/partials/reaction.html` (new): "🔁 Reposted" / like line with
+  the target's title and author, `u-like-of` / `u-repost-of`.
+- `starpunk/feeds/atom.py`, `rss.py`, `json_feed.py`: likes left out,
+  reposts use `feed_html`.
+- `starpunk/syndication.py`:
+  - GoToSocial: `find_status()` resolves fediverse URLs via
+    `/api/v2/search?resolve=true`; native favourite / reblog, stored as
+    `favourite:` / `reblog:` so deletes undo them.
+  - Bluesky: `resolve_post()` recognises `bsky.app/profile//post/`;
+    `_react()` creates like / repost records, a repost with a comment is a
+    quote post (`_record(..., embed=...)`).
+  - Otherwise `compose_repost_text()` posts "🔁 title url" (+ comment),
+    title from `_target_title()` (reply-context cache); likes of ordinary
+    pages are not crossposted.
+
+## Tests
+
+`tests/test_likes_reposts.py` (13 tests: storage and display, feeds,
+webmention to the target with a clean URL, both kinds rejected, native and
+link-post behaviour per target).
+
+## Notes
+
+- The GoToSocial token needs `read:search` and `write:favourites`.
+- Editing a like/repost doesn't change a native favourite/boost.
+- Bookmarks were declined here and added in v2.9.0.
+- The CHANGELOG and ADR-068 date this release 2026-11-01; the commit and
+  tag are dated 2026-10-31.
diff --git a/docs/design/v2.6.1/2026-10-31-threads-publish-retry.md b/docs/design/v2.6.1/2026-10-31-threads-publish-retry.md
new file mode 100644
index 0000000..5f47911
--- /dev/null
+++ b/docs/design/v2.6.1/2026-10-31-threads-publish-retry.md
@@ -0,0 +1,32 @@
+# v2.6.1: Retry Threads publish errors
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `11e09a0`. Design: ADR-069.
+
+## Summary
+
+Meta's `threads_publish` step returned a one-off `HTTP 400 Fatal` for a
+plain text post that published fine on retry; StarPunk treated it as
+permanent.
+
+## Changes
+
+`starpunk/syndication.py` (Threads client):
+
+- Publish-step errors are raised as retryable `SyndicationError`s unless
+  the Graph error code is in `_GRAPH_AUTH = {10, 190, 200}` (bad token or
+  missing permission). The retry's existing-post check prevents a double
+  post.
+- Error messages include the Graph `code`, `error_subcode`,
+  `error_user_title` / `error_user_msg` and `fbtrace_id`; the code is kept on
+  the exception.
+- A 2-second pause before the first container status poll (Meta can report
+  a container ready too early).
+
+## Tests
+
+`tests/test_syndication_threads.py`: `test_publish_fatal_is_retried`.
+
+## Notes
+
+The CHANGELOG dates this release 2026-11-01; the commit and tag are dated
+2026-10-31.
diff --git a/docs/design/v2.6.2/2026-10-31-threads-link-preview.md b/docs/design/v2.6.2/2026-10-31-threads-link-preview.md
new file mode 100644
index 0000000..7db5127
--- /dev/null
+++ b/docs/design/v2.6.2/2026-10-31-threads-link-preview.md
@@ -0,0 +1,29 @@
+# v2.6.2: Let Threads build the link preview
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `fade75f`. Design: ADR-069 (amended in this release).
+
+## Summary
+
+Every new note failed its first Threads crosspost with "Invalid Link
+Attachment" (subcode 4279047) and only went out on the retry a minute
+later: Meta rejects an explicit `link_attachment` for a URL it hasn't
+fetched yet.
+
+## Changes
+
+- `starpunk/syndication.py`: text posts and reposts no longer send
+  `link_attachment`. Tested live with fresh URLs: without it the post
+  publishes first time and Threads still sets `link_attachment_url` from
+  the first link in the text.
+- `docs/decisions/ADR-069-threads-syndication.md` updated accordingly.
+
+## Tests
+
+`tests/test_syndication_threads.py`: assertions changed to expect no
+`link_attachment` in text and repost payloads.
+
+## Notes
+
+The preview shows the first link in the text; v2.6.3 (ADR-070) makes that
+the note's own link when it has one. The CHANGELOG dates this release
+2026-11-01; the commit and tag are dated 2026-10-31.
diff --git a/docs/design/v2.6.3/2026-11-01-crosspost-links-and-cards.md b/docs/design/v2.6.3/2026-11-01-crosspost-links-and-cards.md
new file mode 100644
index 0000000..7b7341f
--- /dev/null
+++ b/docs/design/v2.6.3/2026-11-01-crosspost-links-and-cards.md
@@ -0,0 +1,39 @@
+# v2.6.3: Crosspost cards show the note's own link
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `0fe3411`. Design: ADR-070.
+
+## Summary
+
+When a note links somewhere, the crosspost's preview card shows that page
+instead of the note. Markdown links keep their URL on Bluesky and Threads,
+and Threads stays within Meta's 5-link limit.
+
+## Changes
+
+`starpunk/syndication.py`:
+
+- `note_links()` (with `_note_soup`, `_clean_url`, `_is_web`): the note's
+  own links (Markdown links, ``, bare URLs) in reading order.
+- `plain_text(markdown, links=..., max_urls=...)` / `plain_text_links()`:
+  link modes: Bluesky keeps link text and records anchors; Threads writes
+  "text (url)" and, after 4 distinct links, keeps only the text.
+- `bluesky_facets(text, anchors)`: link-text facets in UTF-8 byte offsets.
+- Bluesky `_link_card()` / `page_card()`: fetch the page's Open Graph,
+  Twitter or HTML title, description and image; image shrunk under 1 MB
+  (`_fit_image`) and uploaded as the thumbnail; an unreachable page still
+  gets a URL-only card. Images in the note still replace the card.
+- `_fetch_public()`: http(s) only, public addresses, checked again at every
+  redirect; 512 KB for pages, 5 MB for images; failures never fail the post.
+
+## Tests
+
+`tests/test_syndication_bluesky.py` (9 new: card choice, unreachable page,
+redirect to a private address not followed, images beat the card, link
+order, link modes, URL budget, anchor facet offsets) and
+`tests/test_syndication_threads.py` (2 new: the Markdown link comes first
+for the preview, at most five links).
+
+## Notes
+
+One or two extra requests to the linked site per Bluesky crosspost.
+Reposts are unchanged (their card is the reposted page).
diff --git a/docs/design/v2.6.4/2026-11-01-tag-entry-order.md b/docs/design/v2.6.4/2026-11-01-tag-entry-order.md
new file mode 100644
index 0000000..08bd878
--- /dev/null
+++ b/docs/design/v2.6.4/2026-11-01-tag-entry-order.md
@@ -0,0 +1,30 @@
+# v2.6.4: Tags keep the order they were entered in
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `4b56f7c`.
+
+## Summary
+
+The first tag is the note's main tag (the Threads topic; Bluesky keeps the
+first tags when space runs out), but crossposts used the alphabetically
+first, and the editor and Micropub reordered tags alphabetically on save.
+
+## Changes
+
+- `starpunk/tags.py`: `add_tags_to_note()` already rewrites `note_tags` in
+  entry order on every save, so `note_tags.id` records the order.
+  `get_note_tags(note_id, entered_order=False)` reads it back when asked;
+  the default stays alphabetical.
+- `entered_order=True` is used by `starpunk/syndication.py` (Threads topic,
+  Bluesky hashtags), `starpunk/routes/admin.py` (editor) and
+  `starpunk/micropub.py` (`q=source`, and updates that add/delete
+  categories).
+- Public pages still list tags alphabetically.
+
+## Tests
+
+`tests/test_tag_order.py` (5 tests: default vs entered order, public page
+alphabetical, editor round trip, Micropub source/update, crossposts).
+
+## Notes
+
+No migration: the order comes from existing row ids.
diff --git a/docs/design/v2.6.6/2026-11-02-crosspost-embedded-images.md b/docs/design/v2.6.6/2026-11-02-crosspost-embedded-images.md
new file mode 100644
index 0000000..41e5e74
--- /dev/null
+++ b/docs/design/v2.6.6/2026-11-02-crosspost-embedded-images.md
@@ -0,0 +1,34 @@
+# v2.6.6: Crossposts include photos embedded in the text
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `39c8259`.
+
+## Summary
+
+Some Micropub clients (OutPost) upload to the media endpoint and then put
+the image in `content` instead of sending `photo`. Those notes have no
+attached media, so crossposts went out without the image.
+
+## Changes
+
+`starpunk/syndication.py`:
+
+- `inline_images(markdown)`: images in the note text, with alt text.
+- `_own_media_path(url)` / `_media_by_path(path)`: keep only images in this
+  site's media library.
+- `_media_files(note_id, limit, content)`: attached media first, then
+  embedded own images, de-duplicated, within each target's photo limit,
+  alt text from the Markdown.
+- `strip_images()`: GoToSocial's text no longer contains the image
+  Markdown.
+
+## Tests
+
+`tests/test_syndication.py` (4 tests: embedded own image attached, text
+around the image kept, image both attached and embedded sent once, other
+sites' images ignored).
+
+## Notes
+
+Images hosted on other sites are still left out of crossposts.
+`__version_info__` was not bumped in v2.6.6 and v2.6.7 (stayed `(2, 6, 4)`;
+`__version__` was correct).
diff --git a/docs/design/v2.6.7/2026-11-02-admin-layout-width.md b/docs/design/v2.6.7/2026-11-02-admin-layout-width.md
new file mode 100644
index 0000000..ace1a05
--- /dev/null
+++ b/docs/design/v2.6.7/2026-11-02-admin-layout-width.md
@@ -0,0 +1,24 @@
+# v2.6.7: Admin pages line up with the header
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `4b2ae4c`.
+
+## Summary
+
+Every page sat in the 40rem reading column, so the admin wrapper's 60rem
+never applied and the notes table ran past the header's right edge.
+
+## Changes
+
+- `templates/base.html`: ``.
+- `templates/admin/base.html`: sets `class="admin-page"`.
+- `static/css/style.css`: `.admin-page { --max-width: 60rem; }` widens the
+  header, menu, content and footer together (replaces
+  `.admin-container { max-width: 60rem }`); `.table-scroll` scrolls tables
+  sideways on narrow screens; `.note-content-preview` wraps
+  (`overflow-wrap: anywhere`, `min-width: 14rem`).
+- `templates/admin/dashboard.html`, `tokens.html`, `webmentions.html`:
+  tables wrapped in `.table-scroll`.
+
+## Tests
+
+None (CSS/templates only); checked visually.
diff --git a/docs/design/v2.7.1/2026-11-03-ci-test-stage.md b/docs/design/v2.7.1/2026-11-03-ci-test-stage.md
new file mode 100644
index 0000000..03eb189
--- /dev/null
+++ b/docs/design/v2.7.1/2026-11-03-ci-test-stage.md
@@ -0,0 +1,25 @@
+# v2.7.1: Tests run before release images are built
+
+> Reconstructed on 2026-11-03 from the changelog and git history. Commit `6a76ee2`.
+
+## Summary
+
+Releases were built and pushed without running the test suite, and eight
+tests had been failing unnoticed.
+
+## Changes
+
+- `Containerfile`: new `test` stage (same `python:3.11-slim` base and venv
+  as production, plus `pytest`, `pytest-mock`; CI-only `SESSION_SECRET`,
+  `SITE_URL`, `ADMIN_ME`), which runs `pytest -q tests`. The runtime stage
+  stays last, so it is still the default target.
+- `.gitea/workflows/build-container.yml`: a "Run tests" step builds
+  `--target test` before the push step; a failing test stops the release.
+- `tests/test_media_upload.py`: validation has returned a PIL `Image`
+  (not bytes) since v1.5.0; tests updated.
+- `tests/test_migration_race_condition.py`: sets `TESTING` so the app
+  skips production configuration checks.
+
+## Tests
+
+The full suite passes in the `test` stage; no new tests.
diff --git a/docs/projectplan/BACKLOG.md b/docs/projectplan/BACKLOG.md
index 1365588..9e28b30 100644
--- a/docs/projectplan/BACKLOG.md
+++ b/docs/projectplan/BACKLOG.md
@@ -1,43 +1,17 @@
 # StarPunk Backlog
 
-**Last Updated**: 2025-12-17
+**Last Updated**: 2026-11-03 (current release: v2.10.1)
 
-## Recently Completed
-
-### v1.5.0 - Quality of Life Improvements (Complete)
-- Timestamp-based default slug generation (ADR-062)
-- Debug file management with automatic cleanup
-- Filename sanitization in debug paths
-- N+1 query fix for feed generation (batch media loading)
-- Atomic variant generation (temp file pattern)
-- MPO format test coverage
-- Test suite cleanup (removed 5 broken tests, fixed brittle assertions)
-
-### v1.4.2 - HEIC/MPO Support and Dimension Limit Increase (Complete)
-- HEIC/HEIF format detection and conversion to JPEG
-- MPO (Multi-Picture Object) format support for iPhone depth photos
-- MAX_DIMENSION increased from 4096 to 12000 pixels
-- Enhanced debug logging for failed uploads
-
-### v1.4.0/v1.4.1 - Media Variants (Complete)
-- Image variant generation (thumb, small, medium, large)
-- Micropub media endpoint
-- Enhanced feed media support with Media RSS
-
-### v1.3.0 - Microformats2 Compliance and Tags (Complete)
-- Tag/Category system with database schema
-- p-category microformats2 markup
-- h-feed required properties (name, author, url)
-- Author h-card with photo and bio
-- u-photo placement outside e-content
-- mf2py validation test suite
+These are the open features and bugs, sorted by priority. Each item was checked against the code
+at v2.10.1. Work that has shipped is listed per release in `vX.Y.Z/RELEASE.md` and in
+`CHANGELOG.md`.
 
 ## Priority Levels
 
 - **Critical** - Items that break existing functionality
-- **High** - Important features or fixes
-- **Medium** - Planned features
-- **Low** - Nice-to-have, deferred indefinitely
+- **High** - Security, data-integrity or correctness bugs; important features
+- **Medium** - Planned features and spec gaps with visible effect
+- **Low** - Nice-to-have, minor spec deviations, deferred ideas
 
 ---
 
@@ -49,144 +23,201 @@
 
 ## High
 
-### POSSE
-- Native syndication to social networks
-- Supported networks:
-  - First iteration:
-    - Mastodon (and compatible services)
-    - Bluesky
-  - Second iteration
-    - TBD
-- Solution should include a configuration UI for setup
+### SQLite foreign keys are not enforced (ON DELETE CASCADE is inert)
+- **Description**: No connection runs `PRAGMA foreign_keys = ON`, so the `ON DELETE CASCADE` clauses in the schema do nothing. When a note is deleted from the admin (a hard delete), its `note_tags`, `note_media`, `syndications` and webmention rows stay behind. `delete_media()` relies on the cascade to remove `media_variants` and `note_media` rows, so those are left orphaned too. Before turning the pragma on, check for existing orphan rows and add a migration that cleans them up. Each cascade also needs tests.
+- **Where**: `starpunk/database/` (connection setup/pool), `starpunk/notes.py` (`delete_note`, hard delete), `starpunk/media.py` (`delete_media`), `migrations/007`–`010`, `016`
+- **Source**: v2.10.x review; confirmed in code (there is no `foreign_keys` pragma anywhere in `starpunk/`)
+
+### No CSRF tokens on admin and consent forms
+- **Description**: Admin forms (create/edit/delete notes, webmention moderation, token revocation) and the IndieAuth consent form rely only on the `SameSite=Lax` session cookie. Lax blocks cross-site POSTs in current browsers, but a per-session CSRF token is the standard defence and covers older clients and same-site subdomains.
+- **Where**: `starpunk/routes/admin.py`, `starpunk/routes/indieauth.py`, `templates/admin/*`
+- **Source**: Documentation refresh 2026-11-03 (architecture review)
+
+### Two outbound fetches don't use the hardened fetcher
+- **Description**: IndieAuth client-metadata discovery (`indieauth.fetch_client_redirect_uris`) checks only the first URL, then uses `httpx.get(follow_redirects=True)`: redirect hops aren't checked and DNS isn't pinned. Crosspost link cards and Threads image fetches (`syndication._fetch_public`) check each hop but don't pin DNS, and their 10 s timeout is per read. Move both to `webmention_ssrf.safe_get`, as Webmention, WebSub and Micropub photo downloads already do.
+- **Where**: `starpunk/indieauth.py`, `starpunk/syndication.py`
+- **Source**: Documentation refresh 2026-11-03
+
+### `FLASK_DEBUG` defaults to on
+- **Description**: `config.py` reads `FLASK_DEBUG` with default `"1"` (and `FLASK_ENV` defaults to development); the runtime image sets neither. Production is safe only because the deployment sets `FLASK_DEBUG=0`. Default to off, or set it in the `Containerfile` runtime stage.
+- **Where**: `starpunk/config.py`, `Containerfile`
+- **Source**: Documentation refresh 2026-11-03 (production verified: DEBUG is False there)
+
+### Rate limiters are per process
+- **Description**: `RateLimiter` keeps its counters in memory, and gunicorn runs 4 workers. The WebSub hub limit of 30/min is therefore really 4×30/min, and the webmention endpoint limit is multiplied the same way. Consider a counter stored in SQLite that all workers share.
+- **Where**: `starpunk/rate_limiter.py`, `starpunk/routes/websub.py`, `starpunk/routes/webmention.py`, `Containerfile` (`--workers 4`)
+- **Source**: ADR-071 (Consequences: rate limiting bounds subscriber-chosen requests); v2.10.1 review
 
 ---
 
 ## Medium
 
-### PKCE Support for IndieAuth
-- **Description**: Implement PKCE (Proof Key for Code Exchange) per RFC 7636 for IndieAuth authentication. Some IndieAuth providers (like indielogin.com) require PKCE. While not required by the W3C IndieAuth spec, it's a security best practice.
-- **Source**: Hotfix 2025-12-17 scoping decision
-- **Approach**:
-  - Add `code_verifier` column to `auth_state` table
-  - Add PKCE helper functions (`_generate_pkce_verifier()`, `_generate_pkce_challenge()`)
-  - Include `code_challenge` and `code_challenge_method=S256` in authorization request
-  - Include `code_verifier` in token exchange request
-- **Reference**: Commit `5e50330` had working PKCE implementation that was removed in `a3bac86`
-- **Priority**: Medium (adds security, enables compatibility with providers that require PKCE)
+### Admin editor cannot clear all tags
+- **Description**: When a note is saved with an empty tag field, the route passes `tags=None`. `update_note` treats that as "unchanged", so the last tags can't be removed from the editor.
+- **Where**: `starpunk/routes/admin.py` (edit POST: `tags=tags if tags else None`), `starpunk/notes.py` (`update_note`)
+- **Source**: Old backlog (v1.3.0 follow-up); still present
 
-### N+1 Query Patterns - Deferred Locations
-- **Description**: N+1 query patterns exist in multiple locations beyond `_get_cached_notes()`. These are lower priority due to lower traffic or single-note contexts.
-- **Deferred Locations**:
-  1. **Admin Edit Page** (`starpunk/routes/admin.py` line 186): Single note context, low impact
-  2. **Tag Archive Pages** (`starpunk/routes/public.py` lines 243-248, 332): Lower traffic than main feed
-  3. **Individual Note View** (`starpunk/routes/public.py` lines 282-289): Single note, negligible
-  4. **Note Model Property** (`starpunk/models.py` lines 380-381): On-demand loading, acceptable
-  5. **Tag Module** (`starpunk/tags.py` line 197): Internal helper, low volume
-- **Source**: Architect Review, v1.5.0 scoping decision
-- **Approach**: Future optimization if performance issues arise. Consider batch loading patterns established in v1.5.0.
-- **Priority**: Deferred to post-v1.5.0
+### Media captions not escaped in RSS HTML
+- **Description**: The RSS description embeds `{caption}` without escaping the caption. A caption containing `"` or `<` breaks the item's HTML.
+- **Where**: `starpunk/feeds/rss.py` (two places, ~lines 136 and 277)
+- **Source**: Old backlog (Architect Review 2.2.10); still present
 
-### Rate Limiting on Upload Endpoints
-- **Description**: No rate limiting exists on media upload endpoints, making them vulnerable to abuse.
-- **Location**: `/admin/new` (admin.py), `/media` (micropub.py)
-- **Source**: Architect Review (Security Assessment)
-- **Approach**: Implement Flask-Limiter or similar rate limiting middleware for upload routes.
+### No rate limiting on upload endpoints
+- **Description**: Media uploads (`/admin/new` and the Micropub media endpoint) have no rate limit. Both require authentication, so the risk comes from a leaked token or session.
+- **Where**: `starpunk/routes/admin.py`, `starpunk/routes/micropub.py`
+- **Source**: Old backlog (Architect Review security assessment); still present
 
-### Tag Enhancements (v1.3.0 Follow-up)
-- Tag pagination on archive pages (when note count exceeds threshold)
-- Tag autocomplete in admin interface
-- Tag-filtered feeds (e.g., `/feed.rss?tag=python`, `/tags/python/feed.rss`)
-- Fix: Empty tag field in admin should remove all tags (currently may leave unchanged)
+### Micropub: more updatable properties
+- **Description**: `add` works only for `category` and `photo`. `published`, `syndication` and `location` can't be updated.
+- **Where**: `starpunk/micropub.py`
+- **Source**: `docs/design/v2.9.0/2026-11-03-micropub-review.md` (Kept as is)
 
-### Tag-Filtered Feeds
-- Filter feeds by tag (e.g., `/feed.rss?tag=python`)
-- Dedicated tag feed URLs (e.g., `/tags/python/feed.rss`)
-- Support all three formats (RSS, Atom, JSON Feed)
-- Cache management for filtered feeds
+### Micropub: `insufficient_scope` returns 403
+- **Description**: StarPunk follows RFC 6750 and returns 403, but the Micropub spec's error table says 401. Choose one: keep 403 and document why, or switch to 401.
+- **Where**: `starpunk/micropub.py`, `starpunk/routes/micropub.py`
+- **Source**: `docs/design/v2.9.0/2026-11-03-micropub-review.md` (Kept as is)
 
-### Webmentions
-- Receive endpoint
-- Send on publish
-- Display received mentions
-- Moderation interface
+### Webmentions with status `error` are never retried
+- **Description**: When a received webmention fails unexpectedly or temporarily, it is stored as `error`. It is never processed again unless the sender sends it again. Add a limited number of retries with backoff.
+- **Where**: `starpunk/webmention_worker.py`
+- **Source**: `docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md` (Known limits)
 
-### Reply Contexts
-- In-reply-to support
-- Like/repost posts
-- Bookmark posts
+### IndieAuth scope handling
+- **Description**: The metadata's `scopes_supported` omits `draft`, though Micropub honours it and the consent screen grants it. Requested scopes aren't filtered, so unknown scopes are granted (and have no effect).
+- **Where**: `starpunk/indieauth.py`, `starpunk/routes/indieauth.py`
+- **Source**: Documentation refresh 2026-11-03
 
-### Media Uploads Enhancements
-- File management interface
-- Thumbnail generation
-- CDN integration (optional)
+### Webmention source DNS failures are permanent
+- **Description**: A DNS failure while fetching a webmention source becomes `ValueError` and marks the mention invalid/error without retry; the WebSub worker now retries `ResolutionError`. Treat it as transient here too.
+- **Where**: `starpunk/webmention_processor.py`, `starpunk/webmention_worker.py`
+- **Source**: v1.6.0 design reconstruction (docs/design/v1.6.0/background-worker.md)
 
-### Photo Posts
-- Instagram-like photo notes
-- Gallery views
-- EXIF data preservation
+### Webmention rate limiter never cleaned up
+- **Description**: `cleanup_rate_limiters()` is never called, so per-IP and per-domain keys accumulate for the life of each process.
+- **Where**: `starpunk/rate_limiter.py`, `starpunk/routes/webmention.py`
+- **Source**: v1.6.0 design reconstruction
 
-### Audio/Podcast Support
-- Podcast RSS with iTunes namespace
-- Audio duration extraction
-- Episode metadata support
-- Apple/Google podcast compatibility
-- See: ADR-059
+### Atom and JSON Feed not linked from pages
+- **Description**: `base.html` advertises only `/feed` (as RSS) and OPML with `rel=alternate`; add `` for `/feed.atom` and `/feed.json` so readers can pick a format.
+- **Where**: `templates/base.html`
+- **Source**: Documentation refresh 2026-11-03
 
-### Video Support
-- Video upload handling
-- Poster image generation
-- Video in Media RSS feeds
-- HTML5 video embedding
+### Housekeeping in the repository
+- **Description**: `compose.yaml` is stale (`image: starpunk:0.6.0`, `VERSION=0.6.0` would override the real version, unused `ENVIRONMENT`); the root `dev_auth.py` duplicates `starpunk/dev_auth.py` and is unused; `LICENSE` says "Copyright (c) 2024 [Your Name]"; `test.ini` contains a private host name; `lxml` and `python-dateutil` are used directly but only installed as dependencies of other packages, while `pytest` is pinned in the production `requirements.txt`.
+- **Where**: `compose.yaml`, `dev_auth.py`, `LICENSE`, `test.ini`, `requirements*.txt`
+- **Source**: Documentation refresh 2026-11-03
+
+### Backfeed responses to crossposts
+- **Description**: Idea: bring likes, boosts and replies to StarPunk's own crossposts back to the note as responses. Two options: poll GoToSocial (the token would need a `read` scope), or rely on Bridgy, which sends webmentions. Since v2.8.0, StarPunk ignores webmentions *from* a note's own crossposts, so that rule would need to change to work with Bridgy.
+- **Where**: `starpunk/syndication.py`, `starpunk/webmention_worker.py`
+- **Source**: v2.8.0 microformats2 review discussion
+
+### Tag-filtered feeds
+- **Description**: Tag pages are h-feeds and WebSub topics, but there are no RSS, Atom or JSON feeds per tag (for example `/tag/python/feed.atom`). Tag pages also have no pagination, and the editor has no tag autocomplete.
+- **Where**: `starpunk/routes/public.py`, `starpunk/feeds/`, `templates/admin/`
+- **Source**: Old backlog (Tag enhancements)
 
 ---
 
 ## Low
 
-### HEIC/MPO Conversion Quality Not Configurable
-- **Description**: HEIC and MPO to JPEG conversion uses hardcoded `quality=95`. Users with different quality/size tradeoff preferences cannot adjust this.
-- **Location**: `starpunk/media.py` line 157
-- **Source**: Developer Review (M3)
-- **Approach**: Add `HEIC_CONVERSION_QUALITY` config variable with 95 as default.
+### Micropub: `location` / `checkin` ignored
+- **Description**: These properties are accepted but dropped, which spec 3.3.5 allows.
+- **Where**: `starpunk/micropub.py`
+- **Source**: `docs/design/v2.9.0/2026-11-03-micropub-review.md`
 
-### MAX_DIMENSION Not Configurable
-- **Description**: `MAX_DIMENSION = 12000` is a hardcoded constant. Cannot adjust limit without code change.
-- **Location**: `starpunk/media.py` line 41
-- **Source**: Developer Review (M4)
-- **Approach**: Make configurable via config variable, keeping 12000 as default.
+### Micropub: video and audio unsupported
+- **Description**: `video` and `audio` are refused with 400 (`UNSUPPORTED_MEDIA`). Supporting them would need upload handling, HTML5 embedding, Media RSS and possibly podcast feeds (see ADR-059).
+- **Where**: `starpunk/micropub.py`, `starpunk/media.py`
+- **Source**: `docs/design/v2.9.0/2026-11-03-micropub-review.md`; old backlog (Audio/Podcast, Video)
 
-### Animated WebP Not Detected
-- **Description**: Animated GIF detection exists but animated WebP is not handled, potentially bypassing animated image size checks.
-- **Location**: `starpunk/media.py` (validate_image function)
-- **Source**: Architect Review (Issue 2.2.2)
-- **Approach**: Add animated WebP detection similar to existing GIF handling.
+### Micropub: GET `access_token` query parameter accepted
+- **Description**: Tokens sent in the URL end up in logs and proxies. Consider refusing them.
+- **Where**: `starpunk/micropub.py` (`extract_bearer_token`)
+- **Source**: `docs/design/v2.9.0/2026-11-03-micropub-review.md`
 
-### Caption Not Escaped in RSS HTML
-- **Description**: In RSS generation, caption is used directly in alt attribute without HTML escaping. Could break markup if caption contains `"` or other special characters.
-- **Location**: `starpunk/feeds/rss.py` line 136
-- **Source**: Architect Review (Issue 2.2.10)
-- **Approach**: Use `html.escape()` for caption when generating HTML content.
+### Person tags (`p-category h-card`) unsupported
+- **Description**: h-card objects in `category` are silently ignored.
+- **Where**: `starpunk/micropub.py`, templates
+- **Source**: `docs/design/v2.8.0/2026-11-03-microformats2-review.md` (Not done)
 
-### Incomplete MPO Documentation
-- **Description**: Code comment says "extract primary image" but doesn't explain the multi-frame nature of MPO files (contain multiple images for 3D or depth maps).
-- **Location**: `starpunk/media.py` lines 163-165
-- **Source**: Developer Review (M5)
-- **Approach**: Enhance inline comment to document that MPO files contain multiple frames and only the primary frame is extracted.
+### Reply-context h-cite lacks author h-card, name and published
+- **Description**: The `u-in-reply-to h-cite` shows the cached author name as plain text. It has no `p-author h-card`, `p-name` or `dt-published`.
+- **Where**: `templates/note.html`, `starpunk/reply_context.py`
+- **Source**: `docs/design/v2.8.0/2026-11-03-microformats2-review.md` (Not done)
 
-### Module Docstring Stale
-- **Description**: Module docstring still states "4096x4096 max dimensions" but MAX_DIMENSION was updated to 12000 in v1.4.2.
-- **Location**: `starpunk/media.py` lines 1-12
-- **Source**: Architect Review (Issue 1.2.1)
-- **Approach**: Update docstring to reflect current 12000px limit.
+### Photo alt falls back to "Image"
+- **Description**: A photo-only post with no caption still gets `alt="Image"`.
+- **Where**: `templates/partials/media.html`
+- **Source**: `docs/design/v2.8.0/2026-11-03-microformats2-review.md` (Not done)
 
-### Flaky Migration Race Condition Tests
-- Improve `test_migration_race_condition.py::TestGraduatedLogging::test_debug_level_for_early_retries`
-- Test expects DEBUG retry messages but passes when migration succeeds without retries
-- May need to mock or force retry conditions for reliable testing
+### Old webmentions lack source details
+- **Description**: Webmentions received before migration 014 keep NULL source details (the original post's URL and published time) until they are re-validated. A one-off re-validation would fill them in.
+- **Where**: `starpunk/webmention_worker.py`, migration 014
+- **Source**: `docs/design/v2.8.0/2026-11-03-microformats2-review.md` (Not done)
 
-### Deferred Indefinitely
-- Static Site Generation - Conflicts with dynamic Micropub
-- Multi-language UI - Low priority for single-user system
-- Advanced Analytics - Privacy concerns, use external tools
-- Comments System - Use Webmentions instead
-- WYSIWYG Editor - Markdown is sufficient
-- Mobile App - Web interface is mobile-friendly
+### Homepage webmentions refused
+- **Description**: Mentions of the home page are refused with 400. They are not stored or shown anywhere.
+- **Where**: `starpunk/routes/webmention.py`
+- **Source**: `docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md` (Known limits)
+
+### Webmention discovery ignores HTTP cache headers
+- **Description**: Endpoint discovery doesn't apply HTTP caching (spec 5.3). Targets are only fetched when a note is created, edited or deleted, so the extra cost is small.
+- **Where**: `starpunk/webmention_sender.py`
+- **Source**: `docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md` (Known limits)
+
+### 410 tombstone page has no microformats
+- **Description**: The "This post has been deleted" page is a generic error page. It could include an `h-entry` with the post's URL and deletion state.
+- **Where**: `templates/410.html`
+- **Source**: `docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md` (Known limits)
+
+### Slow and previously flaky tests
+- **Description**: `tests/test_migration_race_condition.py` takes about 5 minutes. 8 tests were flaky or failing until v2.7.1. Speed them up (mock the waits) or mark them slow so the default test run stays fast.
+- **Where**: `tests/test_migration_race_condition.py`
+- **Source**: v2.7.1 release; ADR-012
+
+### Animated WebP not detected
+- **Description**: Animated GIFs are detected and handled; animated WebP is not.
+- **Where**: `starpunk/media.py`
+- **Source**: Old backlog (Architect Review 2.2.2); still present
+
+### MAX_DIMENSION not configurable
+- **Description**: `MAX_DIMENSION = 12000` is a constant.
+- **Where**: `starpunk/media.py`
+- **Source**: Old backlog (Developer Review M4)
+
+### N+1 queries on secondary pages
+- **Description**: Tag pages and a few single-note views load media one note at a time. Load it in batches if this becomes a problem.
+- **Where**: `starpunk/routes/public.py` (tag page), `starpunk/routes/admin.py`, `starpunk/models.py`, `starpunk/tags.py`
+- **Source**: Old backlog (v1.5.0 scoping)
+
+### Unused settings and legacy tables
+- **Description**: `NOTES_PATH` is read and its folder created, but notes are always written under `DATA_PATH/notes`. `SITE_AUTHOR` is required but shown nowhere. `INITIAL_SCHEMA_SQL` recreates the unused `tokens` and `authorization_codes` tables (dropped by migration 004) on every start, and `auth_state` is unused. Version fallbacks are stale (`author_discovery.py` "1.2.0", `base.html` "0.5.0").
+- **Where**: `starpunk/config.py`, `starpunk/utils.py`, `starpunk/database/schema.py`, `starpunk/author_discovery.py`, `templates/base.html`
+- **Source**: Documentation refresh 2026-11-03 (docs/architecture/database.md, deployment.md)
+
+### Media library and crosspost settings UI
+- **Description**: There is no admin page to browse or delete media, and crosspost targets can only be configured through environment variables.
+- **Where**: `starpunk/routes/admin.py`
+- **Source**: Old backlog (Media enhancements, POSSE configuration UI)
+
+### Deferred indefinitely
+- Static site generation (conflicts with Micropub)
+- Multi-language UI, advanced analytics, WYSIWYG editor, mobile app
+- Comments system (webmentions cover it)
+- CDN integration, gallery views
+
+---
+
+## Done since the last update (2025-12-17)
+
+These items were removed from the backlog because they have shipped:
+
+- POSSE: GoToSocial (v2.1.0), Bluesky (v2.2.0), Threads (v2.6.0)
+- Webmentions: receive, send, display and moderation (v1.6.0); fixed and made spec-compliant in v2.6.8–v2.7.2
+- Reply contexts, replies, likes, reposts and bookmarks (v2.4.0, v2.5.0, v2.9.0)
+- Photo posts without text (v2.6.5); thumbnails and image variants (v1.4.0)
+- PKCE for IndieAuth login: replaced by OIDC admin login with PKCE (v2.0.0, ADR-064)
+- HEIC conversion quality: no longer hardcoded; HEIC images now go through the normal optimisation tiers
+- `media.py` module docstring now says 12000px
+- Fresh feeds and push updates: WebSub (v2.10.0, v2.10.1)
diff --git a/docs/projectplan/INDEX.md b/docs/projectplan/INDEX.md
new file mode 100644
index 0000000..5606570
--- /dev/null
+++ b/docs/projectplan/INDEX.md
@@ -0,0 +1,48 @@
+# Project Plan Index
+
+Future work and per-release plans. See `../DOCUMENTATION.md` (PROJECTPLAN).
+
+## Backlog
+
+- **[BACKLOG.md](BACKLOG.md)** - Open features and bugs by priority (updated for v2.10.1)
+
+## Releases
+
+- **[v1.0.0](v1.0.0/RELEASE.md)** (Released 2025-11-24)
+- **[v1.1.0](v1.1.0/RELEASE.md)** (Released 2025-11-25)
+- **[v1.1.1](v1.1.1/RELEASE.md)** (Released 2025-11-26)
+- **[v1.1.2](v1.1.2/RELEASE.md)** (Released 2025-11-27)
+- **[v1.2.0](v1.2.0/RELEASE.md)** (Released 2025-12-09)
+- **[v1.3.0](v1.3.0/RELEASE.md)** (Complete)
+- **[v1.3.1](v1.3.1/RELEASE.md)** - Feed Categories/Tags Support (Planning)
+- **[v1.4.0](v1.4.0/RELEASE.md)** - Micropub Media Endpoint, Large Image Support, Enhanced Feed Media (Planning)
+- **[v1.5.0](v1.5.0/RELEASE.md)** - Stability, Test Coverage, and Technical Debt Reduction (Approved)
+- **[v2.0.0](v2.0.0/RELEASE.md)** - OIDC admin login and built-in IndieAuth server (Released 2026-10-31)
+- **[v2.0.1](v2.0.1/RELEASE.md)** - Absolute URLs behind HTTPS proxy (Released 2026-10-31)
+- **[v2.0.2](v2.0.2/RELEASE.md)** - CI registry login (Released 2026-10-31)
+- **[v2.1.0](v2.1.0/RELEASE.md)** - Crossposting to GoToSocial (Released 2026-10-31)
+- **[v2.2.0](v2.2.0/RELEASE.md)** - Crossposting to Bluesky (Released 2026-10-31)
+- **[v2.3.0](v2.3.0/RELEASE.md)** - Public page restyle (Released 2026-10-31)
+- **[v2.3.1](v2.3.1/RELEASE.md)** - Log in link (Released 2026-10-31)
+- **[v2.3.2](v2.3.2/RELEASE.md)** - Logged-in state on public pages (Released 2026-10-31)
+- **[v2.3.3](v2.3.3/RELEASE.md)** - Micropub titles and source URLs (Released 2026-10-31)
+- **[v2.4.0](v2.4.0/RELEASE.md)** - Micropub update, delete, drafts and replies (Released 2026-10-31)
+- **[v2.5.0](v2.5.0/RELEASE.md)** - Likes and reposts (Released 2026-11-01)
+- **[v2.6.0](v2.6.0/RELEASE.md)** - Crossposting to Threads (Released 2026-11-01)
+- **[v2.6.1](v2.6.1/RELEASE.md)** - Threads retry fixes (Released 2026-11-01)
+- **[v2.6.2](v2.6.2/RELEASE.md)** - Threads first-post fix (Released 2026-11-01)
+- **[v2.6.3](v2.6.3/RELEASE.md)** - Crosspost link cards (Released 2026-11-01)
+- **[v2.6.4](v2.6.4/RELEASE.md)** - Tag order (Released 2026-11-01)
+- **[v2.6.5](v2.6.5/RELEASE.md)** - Micropub media fixes and photo-only posts (Released 2026-11-01)
+- **[v2.6.6](v2.6.6/RELEASE.md)** - Inline images in crossposts (Released 2026-11-02)
+- **[v2.6.7](v2.6.7/RELEASE.md)** - Admin layout (Released 2026-11-02)
+- **[v2.6.8](v2.6.8/RELEASE.md)** - Webmention worker app context (Released 2026-11-03)
+- **[v2.6.9](v2.6.9/RELEASE.md)** - Webmention processing fixes (Released 2026-11-03)
+- **[v2.7.0](v2.7.0/RELEASE.md)** - Webmention W3C compliance (Released 2026-11-03)
+- **[v2.7.1](v2.7.1/RELEASE.md)** - CI test stage (Released 2026-11-03)
+- **[v2.7.2](v2.7.2/RELEASE.md)** - Remaining Webmention SHOULDs (Released 2026-11-03)
+- **[v2.8.0](v2.8.0/RELEASE.md)** - Microformats2 review (Released 2026-11-03)
+- **[v2.8.1](v2.8.1/RELEASE.md)** - Migration lock (Released 2026-11-03)
+- **[v2.9.0](v2.9.0/RELEASE.md)** - Micropub review (Released 2026-11-03)
+- **[v2.10.0](v2.10.0/RELEASE.md)** - WebSub (Released 2026-11-03)
+- **[v2.10.1](v2.10.1/RELEASE.md)** - WebSub hardening (Released 2026-11-03)
diff --git a/docs/projectplan/v2.0.0/RELEASE.md b/docs/projectplan/v2.0.0/RELEASE.md
new file mode 100644
index 0000000..1bc80bd
--- /dev/null
+++ b/docs/projectplan/v2.0.0/RELEASE.md
@@ -0,0 +1,23 @@
+# StarPunk v2.0.0 Release
+
+**Status**: Released 2026-10-31
+**Focus**: OIDC admin login and built-in IndieAuth server
+
+## Features
+
+- Admin login via OpenID Connect (Pocket ID or any OIDC provider), PKCE + nonce, restricted to `OIDC_ADMIN_SUB` (breaking: new `OIDC_*` settings; `INDIELOGIN_URL`, `TOKEN_ENDPOINT` ignored)
+- Built-in IndieAuth server for Micropub tokens: metadata, consent, token and revocation endpoints (breaking: apps must re-authorize)
+- Connected Apps admin page (`/admin/tokens`) to review and revoke tokens
+- Discovery links on every page; migration 011
+- Removed external IndieAuth endpoint discovery and token verification
+- v1.6.0 webmention source (never committed) recovered from the production image
+
+## Bugs fixed
+
+- None
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.0.0]`)
+- [ADR-064-oidc-admin-login-and-builtin-indieauth-server](../../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md)
+- Design: [docs/design/v2.0.0/](../../design/v2.0.0/)
diff --git a/docs/projectplan/v2.0.1/RELEASE.md b/docs/projectplan/v2.0.1/RELEASE.md
new file mode 100644
index 0000000..e726645
--- /dev/null
+++ b/docs/projectplan/v2.0.1/RELEASE.md
@@ -0,0 +1,18 @@
+# StarPunk v2.0.1 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Absolute URLs behind HTTPS proxy
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Absolute URLs (RSS/OPML links, `u-url`/`u-uid`) said `http://` behind an HTTPS proxy; now built from `SITE_URL`
+- Gitea Actions container builds use rootless BuildKit and the public registry name
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.0.1]`)
+- Design: [docs/design/v2.0.1/](../../design/v2.0.1/)
diff --git a/docs/projectplan/v2.0.2/RELEASE.md b/docs/projectplan/v2.0.2/RELEASE.md
new file mode 100644
index 0000000..3c6c54c
--- /dev/null
+++ b/docs/projectplan/v2.0.2/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.0.2 Release
+
+**Status**: Released 2026-10-31
+**Focus**: CI registry login
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Gitea Actions logs in to the registry with the `REGISTRY_TOKEN` secret (no application changes)
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.0.2]`)
+- Design: [docs/design/v2.0.2/](../../design/v2.0.2/)
diff --git a/docs/projectplan/v2.1.0/RELEASE.md b/docs/projectplan/v2.1.0/RELEASE.md
new file mode 100644
index 0000000..d856469
--- /dev/null
+++ b/docs/projectplan/v2.1.0/RELEASE.md
@@ -0,0 +1,21 @@
+# StarPunk v2.1.0 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Crossposting to GoToSocial
+
+## Features
+
+- Crosspost to GoToSocial / Mastodon-API servers: Markdown with images, alt text, permalink, hashtags; edits, unpublish and delete follow
+- Micropub `syndicate-to`/`config` list the target; editor shows status, errors and retry; `u-syndication` links
+- Migration 012 (`syndications`)
+
+## Bugs fixed
+
+- Micropub `Location` header and search results linked to `/notes/` (404)
+- "Delete Note" on the edit page submitted the edit form
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.1.0]`)
+- [ADR-065-direct-syndication-posse](../../decisions/ADR-065-direct-syndication-posse.md)
+- Design: [docs/design/v2.1.0/](../../design/v2.1.0/)
diff --git a/docs/projectplan/v2.10.0/RELEASE.md b/docs/projectplan/v2.10.0/RELEASE.md
new file mode 100644
index 0000000..51b403c
--- /dev/null
+++ b/docs/projectplan/v2.10.0/RELEASE.md
@@ -0,0 +1,21 @@
+# StarPunk v2.10.0 Release
+
+**Status**: Released 2026-11-03
+**Focus**: WebSub
+
+## Features
+
+- Built-in WebSub hub at `/websub` for the home page, `/feed.atom`, `/feed.rss`, `/feed.json`, `/likes` and tag pages; verified subscriptions, leases, signed full-feed deliveries, retries; `WEBSUB_HUB_URL` / `WEBSUB_ENABLED`
+- Admin dashboard shows WebSub subscribers per feed
+- RSS self link is `/feed.rss` (`/feed.xml` still works)
+
+## Bugs fixed
+
+- Feeds could be up to five minutes stale and were cached per process; changes now refresh feeds everywhere
+- Memory monitor stopped after the first request
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.10.0]`)
+- [ADR-071-websub](../../decisions/ADR-071-websub.md)
+- Design: [docs/design/v2.10.0/](../../design/v2.10.0/)
diff --git a/docs/projectplan/v2.10.1/RELEASE.md b/docs/projectplan/v2.10.1/RELEASE.md
new file mode 100644
index 0000000..6542d05
--- /dev/null
+++ b/docs/projectplan/v2.10.1/RELEASE.md
@@ -0,0 +1,28 @@
+# StarPunk v2.10.1 Release
+
+**Status**: Released 2026-11-03
+**Focus**: WebSub hardening
+
+## Features
+
+- `.env.example` documents `TRUSTED_PROXY` and WebSub settings
+
+## Bugs fixed
+
+- Notes with photos announced before photos were attached; feed cache follows photo/caption changes
+- Failing subscribers kept until lease end (spec 7); DNS/render errors retried; gone feeds end subscriptions with `hub.mode=denied`
+- Verification echoes the requested topic; percent-encoded topics; case-insensitive Content-Type; empty `hub.secret` refused
+- Newer subscription request lost during verification (migration 017); unsubscribe with external hub; stable ETags and `Vary: Accept`; likes don't push home/feeds; IDN callbacks
+
+## Security
+
+- Worker could be stopped for good by a large or malformed callback; each item handled on its own
+- Hard total time limit on hub and webmention requests (slow-loris subscribers)
+- Limits count pending requests per callback address; max 200 pending
+- Callbacks must be printable, reasonable length, off-site and on ports 80/443/1024+
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.10.1]`)
+- [ADR-071-websub](../../decisions/ADR-071-websub.md)
+- Design: [docs/design/v2.10.1/](../../design/v2.10.1/)
diff --git a/docs/projectplan/v2.2.0/RELEASE.md b/docs/projectplan/v2.2.0/RELEASE.md
new file mode 100644
index 0000000..c92f507
--- /dev/null
+++ b/docs/projectplan/v2.2.0/RELEASE.md
@@ -0,0 +1,19 @@
+# StarPunk v2.2.0 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Crossposting to Bluesky
+
+## Features
+
+- Crosspost to Bluesky: plain text with link/hashtag facets, 300-character limit, up to 4 images with alt text, link cards; unpublish/delete remove the post
+- App-password login (`BLUESKY_HANDLE`, `BLUESKY_APP_PASSWORD`, `BLUESKY_SERVICE`)
+
+## Bugs fixed
+
+- None
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.2.0]`)
+- [ADR-066-bluesky-syndication](../../decisions/ADR-066-bluesky-syndication.md)
+- Design: [docs/design/v2.2.0/](../../design/v2.2.0/)
diff --git a/docs/projectplan/v2.3.0/RELEASE.md b/docs/projectplan/v2.3.0/RELEASE.md
new file mode 100644
index 0000000..11ab20f
--- /dev/null
+++ b/docs/projectplan/v2.3.0/RELEASE.md
@@ -0,0 +1,20 @@
+# StarPunk v2.3.0 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Public page restyle
+
+## Features
+
+- Public pages restyled: compact header with `SITE_NAME`, serif reading font, one-line metadata, dark mode, pinned footer
+- Short notes shown in full, titled notes as summary + "Read more"; page titles from note text
+- Bare URLs become links
+
+## Bugs fixed
+
+- Note metadata styled as the page footer
+- Previews cut HTML at 300 characters and could break markup
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.3.0]`)
+- Design: [docs/design/v2.3.0/](../../design/v2.3.0/)
diff --git a/docs/projectplan/v2.3.1/RELEASE.md b/docs/projectplan/v2.3.1/RELEASE.md
new file mode 100644
index 0000000..edb58e4
--- /dev/null
+++ b/docs/projectplan/v2.3.1/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.3.1 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Log in link
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- "Log in" moved back to the header nav
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.3.1]`)
+- Design: [docs/design/v2.3.1/](../../design/v2.3.1/)
diff --git a/docs/projectplan/v2.3.2/RELEASE.md b/docs/projectplan/v2.3.2/RELEASE.md
new file mode 100644
index 0000000..cf6e1c3
--- /dev/null
+++ b/docs/projectplan/v2.3.2/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.3.2 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Logged-in state on public pages
+
+## Features
+
+- Header link reads "Admin" when logged in
+
+## Bugs fixed
+
+- Public pages never detected the admin session, so the header always said "Log in"
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.3.2]`)
+- Design: [docs/design/v2.3.2/](../../design/v2.3.2/)
diff --git a/docs/projectplan/v2.3.3/RELEASE.md b/docs/projectplan/v2.3.3/RELEASE.md
new file mode 100644
index 0000000..460f634
--- /dev/null
+++ b/docs/projectplan/v2.3.3/RELEASE.md
@@ -0,0 +1,19 @@
+# StarPunk v2.3.3 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Micropub titles and source URLs
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Micropub `name` was ignored; now stored as the note's `# Heading`
+- `q=source` returned `/notes/` links and a `name` for every note
+- Titled notes showed their title twice
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.3.3]`)
+- Design: [docs/design/v2.3.3/](../../design/v2.3.3/)
diff --git a/docs/projectplan/v2.4.0/RELEASE.md b/docs/projectplan/v2.4.0/RELEASE.md
new file mode 100644
index 0000000..cf5f7c7
--- /dev/null
+++ b/docs/projectplan/v2.4.0/RELEASE.md
@@ -0,0 +1,22 @@
+# StarPunk v2.4.0 Release
+
+**Status**: Released 2026-10-31
+**Focus**: Micropub update, delete, drafts and replies
+
+## Features
+
+- Micropub `action=update` (replace/add/delete), with edits following crossposts
+- Micropub delete/undelete (soft delete); drafts via `post-status`; replies via `in-reply-to`
+- Multipart photo upload in create; remote photos downloaded (public addresses only, 20 MB cap)
+- `q=source` listing with paging and `properties[]`; `q=category`; `q=config` lists queries and post types; media endpoint accepts `media` scope
+
+## Bugs fixed
+
+- Media endpoint advertised at `/micropub/media` but served at `/media`
+- Unsupported types (e.g. `h=event`) were stored as notes; now rejected
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.4.0]`)
+- [ADR-067-micropub-update-delete](../../decisions/ADR-067-micropub-update-delete.md)
+- Design: [docs/design/v2.4.0/](../../design/v2.4.0/)
diff --git a/docs/projectplan/v2.5.0/RELEASE.md b/docs/projectplan/v2.5.0/RELEASE.md
new file mode 100644
index 0000000..3c2a888
--- /dev/null
+++ b/docs/projectplan/v2.5.0/RELEASE.md
@@ -0,0 +1,21 @@
+# StarPunk v2.5.0 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Likes and reposts
+
+## Features
+
+- Micropub `like-of` / `repost-of` with optional comment; `/likes` page; reposts in the stream and feeds
+- Liked/reposted post's title and author fetched; webmention sent
+- Native favourites/boosts on GoToSocial and likes/reposts/quote posts on Bluesky; undone on delete
+- Migration 013
+
+## Bugs fixed
+
+- Outgoing webmentions used `https://site//note/` (double slash)
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.5.0]`)
+- [ADR-068-likes-and-reposts](../../decisions/ADR-068-likes-and-reposts.md)
+- Design: [docs/design/v2.5.0/](../../design/v2.5.0/)
diff --git a/docs/projectplan/v2.6.0/RELEASE.md b/docs/projectplan/v2.6.0/RELEASE.md
new file mode 100644
index 0000000..cc1d4b6
--- /dev/null
+++ b/docs/projectplan/v2.6.0/RELEASE.md
@@ -0,0 +1,19 @@
+# StarPunk v2.6.0 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Crossposting to Threads
+
+## Features
+
+- Crosspost to Threads (`THREADS_ACCESS_TOKEN`): link previews, image/carousel posts with alt text, first tag as topic, 500-character limit; unpublish/delete remove the post
+- Threads token refreshed daily and persisted in `data/threads_token.json`
+
+## Bugs fixed
+
+- None
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.0]`)
+- [ADR-069-threads-syndication](../../decisions/ADR-069-threads-syndication.md)
+- Design: [docs/design/v2.6.0/](../../design/v2.6.0/)
diff --git a/docs/projectplan/v2.6.1/RELEASE.md b/docs/projectplan/v2.6.1/RELEASE.md
new file mode 100644
index 0000000..b54a54a
--- /dev/null
+++ b/docs/projectplan/v2.6.1/RELEASE.md
@@ -0,0 +1,20 @@
+# StarPunk v2.6.1 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Threads retry fixes
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Threads publish errors (one-off `HTTP 400 Fatal`) are retried without double-posting
+- Threads errors include Meta's code, subcode, message and trace id
+- Short wait before the first readiness check
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.1]`)
+- [ADR-069-threads-syndication](../../decisions/ADR-069-threads-syndication.md)
+- Design: [docs/design/v2.6.1/](../../design/v2.6.1/)
diff --git a/docs/projectplan/v2.6.2/RELEASE.md b/docs/projectplan/v2.6.2/RELEASE.md
new file mode 100644
index 0000000..d545356
--- /dev/null
+++ b/docs/projectplan/v2.6.2/RELEASE.md
@@ -0,0 +1,18 @@
+# StarPunk v2.6.2 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Threads first-post fix
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- New notes failed their first Threads crosspost with "Invalid Link Attachment"; the explicit link preview is no longer sent
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.2]`)
+- [ADR-069-threads-syndication](../../decisions/ADR-069-threads-syndication.md)
+- Design: [docs/design/v2.6.2/](../../design/v2.6.2/)
diff --git a/docs/projectplan/v2.6.3/RELEASE.md b/docs/projectplan/v2.6.3/RELEASE.md
new file mode 100644
index 0000000..dbc2e60
--- /dev/null
+++ b/docs/projectplan/v2.6.3/RELEASE.md
@@ -0,0 +1,19 @@
+# StarPunk v2.6.3 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Crosspost link cards
+
+## Features
+
+- A note's own outbound link gets the crosspost preview card
+
+## Bugs fixed
+
+- Markdown links lost their URL on Bluesky and Threads
+- Notes with more than 5 links failed on Threads
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.3]`)
+- [ADR-070-crosspost-links-and-cards](../../decisions/ADR-070-crosspost-links-and-cards.md)
+- Design: [docs/design/v2.6.3/](../../design/v2.6.3/)
diff --git a/docs/projectplan/v2.6.4/RELEASE.md b/docs/projectplan/v2.6.4/RELEASE.md
new file mode 100644
index 0000000..52b94cd
--- /dev/null
+++ b/docs/projectplan/v2.6.4/RELEASE.md
@@ -0,0 +1,18 @@
+# StarPunk v2.6.4 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Tag order
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Tags keep their entered order; the first tag is the main tag (Threads topic, Bluesky priority)
+- Editor and Micropub `q=source` reordered tags alphabetically on save
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.4]`)
+- Design: [docs/design/v2.6.4/](../../design/v2.6.4/)
diff --git a/docs/projectplan/v2.6.5/RELEASE.md b/docs/projectplan/v2.6.5/RELEASE.md
new file mode 100644
index 0000000..34bb369
--- /dev/null
+++ b/docs/projectplan/v2.6.5/RELEASE.md
@@ -0,0 +1,21 @@
+# StarPunk v2.6.5 Release
+
+**Status**: Released 2026-11-01
+**Focus**: Micropub media fixes and photo-only posts
+
+## Features
+
+- Photo posts no longer need text (Micropub and admin); crossposts start with the link and the page is titled "Photo"
+
+## Bugs fixed
+
+- A Micropub post failing partway stayed published without photos; it is now rolled back
+- "database is locked" for ~10 s after a failed write: pooled connections roll back
+- Duplicate photos in one post are shown once
+- Reply markup: `u-in-reply-to h-cite` on note pages, "↩ In reply to" on the home page
+- Photo alt falls back to the post text instead of "Image"; home entries always have `e-content`
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.5]`)
+- Design: [docs/design/v2.6.5/](../../design/v2.6.5/)
diff --git a/docs/projectplan/v2.6.6/RELEASE.md b/docs/projectplan/v2.6.6/RELEASE.md
new file mode 100644
index 0000000..b6dc2f8
--- /dev/null
+++ b/docs/projectplan/v2.6.6/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.6.6 Release
+
+**Status**: Released 2026-11-02
+**Focus**: Inline images in crossposts
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Images embedded in the post text (from this site's media library) are now crossposted like attached photos, with alt text
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.6]`)
+- Design: [docs/design/v2.6.6/](../../design/v2.6.6/)
diff --git a/docs/projectplan/v2.6.7/RELEASE.md b/docs/projectplan/v2.6.7/RELEASE.md
new file mode 100644
index 0000000..036364d
--- /dev/null
+++ b/docs/projectplan/v2.6.7/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.6.7 Release
+
+**Status**: Released 2026-11-02
+**Focus**: Admin layout
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Admin pages misaligned; now a 60rem frame, wrapping previews, scrolling tables on narrow screens
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.7]`)
+- Design: [docs/design/v2.6.7/](../../design/v2.6.7/)
diff --git a/docs/projectplan/v2.6.8/RELEASE.md b/docs/projectplan/v2.6.8/RELEASE.md
new file mode 100644
index 0000000..b3c8ce3
--- /dev/null
+++ b/docs/projectplan/v2.6.8/RELEASE.md
@@ -0,0 +1,18 @@
+# StarPunk v2.6.8 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Webmention worker app context
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Webmentions were never processed: the worker ran outside the app context; it now runs with the app loaded
+- The worker stopped after the first request; it now runs for the life of the process
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.8]`)
+- Design: [docs/design/v2.6.8/](../../design/v2.6.8/)
diff --git a/docs/projectplan/v2.6.9/RELEASE.md b/docs/projectplan/v2.6.9/RELEASE.md
new file mode 100644
index 0000000..b1a5aaa
--- /dev/null
+++ b/docs/projectplan/v2.6.9/RELEASE.md
@@ -0,0 +1,23 @@
+# StarPunk v2.6.9 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Webmention processing fixes
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Received webmentions failed when the author photo had alt text
+- Outgoing webmentions were never sent (endpoint discovery crashed); network errors are retried
+- Each process ran its own worker; only one process now handles the queues, with takeover
+
+## Security
+
+- `javascript:` author links from webmention senders were rendered; only http(s) URLs are kept
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.6.9]`)
+- Design: [docs/design/v2.6.9/](../../design/v2.6.9/)
diff --git a/docs/projectplan/v2.7.0/RELEASE.md b/docs/projectplan/v2.7.0/RELEASE.md
new file mode 100644
index 0000000..c2b603b
--- /dev/null
+++ b/docs/projectplan/v2.7.0/RELEASE.md
@@ -0,0 +1,25 @@
+# StarPunk v2.7.0 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Webmention W3C compliance
+
+## Features
+
+- Webmentions accepted only for published notes (home/other pages refused with 400)
+- Deleted notes answer 410 Gone
+- Re-sent mentions keep their moderation state
+
+## Bugs fixed
+
+- Sending: endpoint discovery handles multi-word/any-case `rel`, multiple Link headers and document order; no endpoint cache; edits/deletes/restores notify old and removed targets; redirects not counted as success; 429 retried
+- Receiving: exact target link required; relative links resolved; `Accept` header and charset; existing mention kept if the source is unreachable; target host/port/fragment normalised
+- Snippet truncation no longer leaves tags open; Link header merged; code-block links not sent
+
+## Security
+
+- Every redirect checked against private addresses; all resolved addresses must be public (CGNAT, multicast, reserved, IPv4-mapped blocked); total time and 1 MB size limits
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.7.0]`)
+- Design: [docs/design/v2.7.0/](../../design/v2.7.0/)
diff --git a/docs/projectplan/v2.7.1/RELEASE.md b/docs/projectplan/v2.7.1/RELEASE.md
new file mode 100644
index 0000000..3612872
--- /dev/null
+++ b/docs/projectplan/v2.7.1/RELEASE.md
@@ -0,0 +1,17 @@
+# StarPunk v2.7.1 Release
+
+**Status**: Released 2026-11-03
+**Focus**: CI test stage
+
+## Features
+
+- Releases run the full test suite in the Containerfile `test` stage before an image is pushed
+
+## Bugs fixed
+
+- Eight failing tests fixed (image validation expectations; migration test in production mode)
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.7.1]`)
+- Design: [docs/design/v2.7.1/](../../design/v2.7.1/)
diff --git a/docs/projectplan/v2.7.2/RELEASE.md b/docs/projectplan/v2.7.2/RELEASE.md
new file mode 100644
index 0000000..b7097ad
--- /dev/null
+++ b/docs/projectplan/v2.7.2/RELEASE.md
@@ -0,0 +1,21 @@
+# StarPunk v2.7.2 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Remaining Webmention SHOULDs
+
+## Features
+
+- Webmentions re-sent when the responses shown on a note change (spec 3.1.4)
+
+## Bugs fixed
+
+- None
+
+## Security
+
+- DNS pinning: fetches and sends connect to the exact address that passed the private-address check; TLS still verified against the hostname
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.7.2]`)
+- Design: [docs/design/v2.7.2/](../../design/v2.7.2/)
diff --git a/docs/projectplan/v2.8.0/RELEASE.md b/docs/projectplan/v2.8.0/RELEASE.md
new file mode 100644
index 0000000..585bd1f
--- /dev/null
+++ b/docs/projectplan/v2.8.0/RELEASE.md
@@ -0,0 +1,24 @@
+# StarPunk v2.8.0 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Microformats2 review
+
+## Features
+
+- Tag and likes pages have a feed URL and author; note previews have `u-uid`
+
+## Bugs fixed
+
+- Replies marked up as `u-comment h-cite` with author h-card; likes/reposts/bookmarks/mentions as h-cites
+- Responses use the original post's URL and published time (migration 014)
+- Times in UTC with `Z`
+- A note starting with `#hashtag` was treated as a titled article
+- Webmentions from a note's own crossposts ignored
+- Micropub/IndieAuth discovery links vanished when webmentions were off; `rel=me`/`rel=author` always present
+- Representative h-card and authorship algorithm for author discovery
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.8.0]`)
+- [ADR-040-microformats2-compliance](../../decisions/ADR-040-microformats2-compliance.md)
+- Design: [docs/design/v2.8.0/](../../design/v2.8.0/)
diff --git a/docs/projectplan/v2.8.1/RELEASE.md b/docs/projectplan/v2.8.1/RELEASE.md
new file mode 100644
index 0000000..fcb8b06
--- /dev/null
+++ b/docs/projectplan/v2.8.1/RELEASE.md
@@ -0,0 +1,18 @@
+# StarPunk v2.8.1 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Migration lock
+
+## Features
+
+- None
+
+## Bugs fixed
+
+- Concurrent workers could apply the same migration ("duplicate column name") and take the server down; migrations now run entirely inside the lock
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.8.1]`)
+- [ADR-037-migration-race-condition-fix](../../decisions/ADR-037-migration-race-condition-fix.md)
+- Design: [docs/design/v2.8.1/](../../design/v2.8.1/)
diff --git a/docs/projectplan/v2.9.0/RELEASE.md b/docs/projectplan/v2.9.0/RELEASE.md
new file mode 100644
index 0000000..13ea27d
--- /dev/null
+++ b/docs/projectplan/v2.9.0/RELEASE.md
@@ -0,0 +1,28 @@
+# StarPunk v2.9.0 Release
+
+**Status**: Released 2026-11-03
+**Focus**: Micropub review
+
+## Features
+
+- Bookmarks (`bookmark-of`, migration 015)
+- Micropub posts crosspost only to targets the client requests (no `mp-syndicate-to` → none)
+- `visibility` private/unlisted saved as drafts; `draft` scope; summary-only and name-only posts
+
+## Bugs fixed
+
+- `mp-syndicate-to`/`mp-slug` inside `properties` (Quill) were ignored
+- Failed photo fetches now fail the request; remote photos fetched with SSRF protections
+- Single JSON values read character by character; HTML posts returned as `{"html": …}`; `published` stored as UTC
+- Malformed JSON → 400; `video`/`audio` refused; empty updates refused; case-insensitive `Bearer`; `WWW-Authenticate` on 401
+
+## Security
+
+- Rendered note HTML sanitized (scripts, event handlers, iframes, `javascript:` links removed)
+- `q=source`/`q=category` require a posting scope; header + body token refused
+
+## Related documents
+
+- Changelog: [CHANGELOG.md](../../../CHANGELOG.md) (`[2.9.0]`)
+- [ADR-028-micropub-implementation](../../decisions/ADR-028-micropub-implementation.md)
+- Design: [docs/design/v2.9.0/](../../design/v2.9.0/)
diff --git a/docs/standards/INDEX.md b/docs/standards/INDEX.md
index 97fa888..a141f86 100644
--- a/docs/standards/INDEX.md
+++ b/docs/standards/INDEX.md
@@ -1,169 +1,54 @@
-# Standards Documentation Index
+# Standards Index
 
-This directory contains coding standards, conventions, processes, workflows, and best practices for StarPunk CMS development.
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-## Core Standards
+Standards for developing and releasing StarPunk. Folder rules are in
+[../DOCUMENTATION.md](../DOCUMENTATION.md). All standards below were checked
+against the code at v2.10.1.
 
-### Code Quality
-- **[python-coding-standards.md](python-coding-standards.md)** - Python code style, patterns, and best practices
-- **[utility-function-patterns.md](utility-function-patterns.md)** - Patterns for writing utility functions
+## Active standards
 
-### Testing
-- **[testing-checklist.md](testing-checklist.md)** - Comprehensive testing checklist and requirements
+| Standard | Covers |
+|---|---|
+| [development-setup.md](development-setup.md) | uv environment, `.env`, running the app with `DEV_MODE`, running the tests |
+| [testing-checklist.md](testing-checklist.md) | What to test, test conventions, the CI test stage, protocol validation tools |
+| [git-branching-strategy.md](git-branching-strategy.md) | Branches, commits, **the release process** (worktree, `merge --no-ff`, tag, CI, deploy), migrations |
+| [versioning-strategy.md](versioning-strategy.md) | Choosing MAJOR / MINOR / PATCH |
+| [version-implementation-guide.md](version-implementation-guide.md) | Where the version lives, changelog entry and design note format |
+| [python-coding-standards.md](python-coding-standards.md) | Style, naming, and project patterns (config, database, outbound HTTP, errors, routes, workers) |
+| [utility-function-patterns.md](utility-function-patterns.md) | Patterns for small helper functions |
+| [cookie-naming-convention.md](cookie-naming-convention.md) | `starpunk_` cookie prefix and the cookies in use |
+| [documentation-organization.md](documentation-organization.md) | Templates and conventions for docs (folder rules: DOCUMENTATION.md) |
 
-### Development Workflow
-- **[development-setup.md](development-setup.md)** - Development environment setup guide
-- **[git-branching-strategy.md](git-branching-strategy.md)** - Git workflow and branching model
-- **[versioning-strategy.md](versioning-strategy.md)** - Semantic versioning guidelines
-- **[version-implementation-guide.md](version-implementation-guide.md)** - How to implement version changes
+## Where to start
 
-### Conventions
-- **[cookie-naming-convention.md](cookie-naming-convention.md)** - Cookie naming standards
-- **[documentation-organization.md](documentation-organization.md)** - Documentation structure and organization
+- **New to the code**: development-setup → python-coding-standards →
+  testing-checklist.
+- **Making a release**: git-branching-strategy (release process), which
+  links to versioning-strategy and version-implementation-guide.
+- **Writing an ADR or design note**: documentation-organization.
 
-## Standards by Category
+## Key rules in brief
 
-### Python Development
-- **python-coding-standards.md** - Style guide, linting, formatting
-- **utility-function-patterns.md** - Reusable code patterns
+- `uv` for environments, `uv run` for every command.
+- Tests need `SESSION_SECRET`; the full suite takes about 6 minutes, 5 of
+  them in `tests/test_migration_race_condition.py`.
+- Every release: branch in a worktree, bump `__version__` and
+  `__version_info__`, changelog entry, design note (or ADR amendment),
+  `git merge --no-ff`, annotated `vX.Y.Z` tag; CI tests and publishes the
+  image; deploy from the Ansible repository; back up the database first when
+  there is a migration.
+- Formatters and linters are available but not enforced; match the file
+  you are editing.
 
-### Version Control & Release Management
-- **git-branching-strategy.md** - Branch naming, workflow, PRs
-- **versioning-strategy.md** - SemVer guidelines, version bumping
-- **version-implementation-guide.md** - Step-by-step version changes
+## Deprecated standards
 
-### Quality Assurance
-- **testing-checklist.md** - Test coverage requirements, test types
+Standards that no longer apply move to `DEPRECATED/` (none at
+present). Earlier versions of the standards above are in git history.
 
-### Development Environment
-- **development-setup.md** - Local setup, dependencies, tools
+## Related
 
-### Project Organization
-- **documentation-organization.md** - Where to put what docs
-- **cookie-naming-convention.md** - Naming consistency
-
-## How to Use These Standards
-
-### For New Developers
-1. **Start here**: [development-setup.md](development-setup.md)
-2. **Read**: [python-coding-standards.md](python-coding-standards.md)
-3. **Understand**: [git-branching-strategy.md](git-branching-strategy.md)
-4. **Reference**: Other standards as needed
-
-### Before Writing Code
-- [ ] Review [python-coding-standards.md](python-coding-standards.md)
-- [ ] Check [utility-function-patterns.md](utility-function-patterns.md) for reusable patterns
-- [ ] Create feature branch per [git-branching-strategy.md](git-branching-strategy.md)
-
-### Before Committing Code
-- [ ] Run tests per [testing-checklist.md](testing-checklist.md)
-- [ ] Verify code follows [python-coding-standards.md](python-coding-standards.md)
-- [ ] Update version if needed per [versioning-strategy.md](versioning-strategy.md)
-- [ ] Write clear commit message per [git-branching-strategy.md](git-branching-strategy.md)
-
-### Before Creating PR
-- [ ] All tests pass ([testing-checklist.md](testing-checklist.md))
-- [ ] Documentation updated ([documentation-organization.md](documentation-organization.md))
-- [ ] Version bumped if needed ([version-implementation-guide.md](version-implementation-guide.md))
-- [ ] PR follows [git-branching-strategy.md](git-branching-strategy.md)
-
-### When Reviewing Code
-- [ ] Check adherence to [python-coding-standards.md](python-coding-standards.md)
-- [ ] Verify test coverage per [testing-checklist.md](testing-checklist.md)
-- [ ] Confirm naming conventions ([cookie-naming-convention.md](cookie-naming-convention.md))
-- [ ] Validate documentation ([documentation-organization.md](documentation-organization.md))
-
-## Key Principles
-
-### Code Quality
-- **Simplicity First**: "Every line of code must justify its existence"
-- **Explicit Over Implicit**: Clear, readable code over clever tricks
-- **Type Hints Required**: All functions must have type hints
-- **Docstrings Required**: All public functions must have docstrings
-
-### Testing
-- **Test-Driven Development**: Write tests before implementation
-- **Coverage Requirements**: Minimum 80% coverage, aim for 90%+
-- **Test Types**: Unit, integration, and end-to-end tests
-- **No Skipped Tests**: All tests must pass
-
-### Version Control
-- **Feature Branches**: All work happens in feature branches
-- **Atomic Commits**: One logical change per commit
-- **Clear Messages**: Commit messages follow conventional commits format
-- **No Direct Commits to Main**: All changes via pull requests
-
-### Versioning
-- **Semantic Versioning**: MAJOR.MINOR.PATCH format
-- **Version Bumping**: Update version in multiple locations consistently
-- **Changelog Maintenance**: Document all user-facing changes
-- **Tag Releases**: Git tags match version numbers
-
-## Standards Compliance Checklist
-
-Use this checklist for all code contributions:
-
-### Code Standards
-- [ ] Follows Python coding standards
-- [ ] Uses approved utility patterns
-- [ ] Has type hints on all functions
-- [ ] Has docstrings on all public functions
-- [ ] Passes linting (flake8, black)
-
-### Testing Standards
-- [ ] Unit tests written
-- [ ] Integration tests if needed
-- [ ] All tests pass
-- [ ] Coverage meets minimum (80%)
-
-### Git Standards
-- [ ] Feature branch created
-- [ ] Commits are atomic
-- [ ] Commit messages are clear
-- [ ] PR description is complete
-
-### Versioning Standards
-- [ ] Version updated if needed
-- [ ] Changelog updated
-- [ ] Version consistent across files
-- [ ] Git tag created for releases
-
-### Documentation Standards
-- [ ] Code documented
-- [ ] README updated if needed
-- [ ] ADR created if architectural
-- [ ] Implementation report written
-
-## Enforcing Standards
-
-### Automated Enforcement
-- **Pre-commit hooks**: Run linting and formatting
-- **CI/CD pipeline**: Run tests and checks
-- **Code review**: Human verification of standards
-
-### Manual Verification
-- **Checklist review**: Use standards compliance checklist
-- **Peer review**: Other developers verify adherence
-- **Architect review**: For architectural changes
-
-## Updating Standards
-
-Standards are living documents that evolve:
-
-1. **Propose Change**: Create ADR documenting why
-2. **Discuss**: Get team consensus
-3. **Update Standard**: Modify the relevant standard document
-4. **Announce**: Communicate the change to team
-5. **Enforce**: Update CI/CD and tooling
-
-## Related Documentation
-- **[../architecture/](../architecture/)** - System architecture
-- **[../decisions/](../decisions/)** - Architectural Decision Records
-- **[../design/](../design/)** - Feature designs
-- **[../reports/](../reports/)** - Implementation reports
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
-**Total Standards**: 9
+- [../architecture/](../architecture/): current system design
+- [../decisions/](../decisions/): ADRs
+- [../design/](../design/): per-release designs and reports
+- [../projectplan/](../projectplan/): backlog and release plans
diff --git a/docs/standards/cookie-naming-convention.md b/docs/standards/cookie-naming-convention.md
index 45d704d..5b27b98 100644
--- a/docs/standards/cookie-naming-convention.md
+++ b/docs/standards/cookie-naming-convention.md
@@ -1,8 +1,9 @@
 # Cookie Naming Convention
 
-**Status**: ACTIVE
+**Status**: Active
 **Date**: 2025-11-18
-**Version**: 1.0
+**Last Updated**: 2026-11-03 (v2.10.1; cookie list checked against the code)
+**Version**: 1.1
 
 ## Purpose
 
@@ -44,9 +45,19 @@ All StarPunk cookies use the `starpunk_` prefix for clear ownership.
 
 ### Current Cookies
 
-| Cookie Name | Purpose | Security Attributes | Max Age |
-|-------------|---------|---------------------|---------|
-| `starpunk_session` | Authentication session token | HttpOnly, Secure (prod), SameSite=Lax | 30 days |
+| Cookie Name | Set by | Purpose | Security Attributes | Max Age |
+|-------------|--------|---------|---------------------|---------|
+| `starpunk_session` | `/auth/callback` (`starpunk/routes/auth.py`, constant `SESSION_COOKIE`) | Admin session token (the token's hash is stored in the `sessions` table) | HttpOnly, SameSite=Lax, Secure when `SITE_URL` starts with `https://` | `SESSION_LIFETIME` days (default 30) |
+| `starpunk_session` | `/dev/login` (`starpunk/routes/dev_auth.py`, only with `DEV_MODE=true`) | Same cookie, created without authentication | HttpOnly, SameSite=Lax, never Secure | 30 days (fixed) |
+
+`starpunk_session` is read in `starpunk/auth.py` (`require_auth`),
+`starpunk/routes/auth.py`, `starpunk/routes/indieauth.py` (consent screen)
+and `starpunk/__init__.py` (`before_request`, so every page knows whether
+the owner is logged in), and deleted on logout.
+
+Not cookies: the OIDC login state, nonce and PKCE verifier are kept
+server-side in the `oidc_login_state` table, and Micropub clients
+authenticate with bearer tokens (`indieauth_tokens` table), never cookies.
 
 ### Future Cookies
 
@@ -149,7 +160,11 @@ StarPunk and Flask cookies can coexist without conflict:
 - `starpunk_session` - Application authentication
 
 **Flask cookies** (framework-managed):
-- `session` - Flask server-side session (for flash messages)
+- `session` - Flask's signed session cookie (signed with `SECRET_KEY`, which
+  defaults to `SESSION_SECRET`). StarPunk stores flash messages and
+  `session["next"]`, the page to return to after login (set by
+  `require_auth` and the IndieAuth consent screen). Keep it to small,
+  non-secret values: it is signed, not encrypted.
 
 Both are necessary and serve different purposes. Do not interfere with Flask's `session` cookie.
 
@@ -188,7 +203,7 @@ Both are necessary and serve different purposes. Do not interfere with Flask's `
 
 ```python
 def test_auth_cookie_name(client):
-    """Test authentication uses correct cookie name"""
+    """Test authentication uses correct cookie name (app built with DEV_MODE=True)"""
     response = client.post("/dev/login")
 
     # Verify correct cookie name
@@ -202,9 +217,9 @@ def test_auth_cookie_name(client):
 ## References
 
 ### Internal Documentation
-- **Auth Redirect Loop Fix**: `/docs/reports/2025-11-18-auth-redirect-loop-fix.md`
+- **Auth Redirect Loop Fix**: `docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md`
 - **ADR-011**: Development Authentication Mechanism
-- **ADR-005**: IndieLogin Authentication
+- **ADR-064**: OIDC admin login and built-in IndieAuth server (replaced ADR-005, IndieLogin, in v2.0.0)
 
 ### External Standards
 - [RFC 6265 - HTTP State Management Mechanism (Cookies)](https://tools.ietf.org/html/rfc6265)
@@ -213,6 +228,12 @@ def test_auth_cookie_name(client):
 
 ## History
 
+### Version 1.1 (2026-11-03)
+- Cookie table checked against v2.10.1: `starpunk_session` lifetime follows
+  `SESSION_LIFETIME`, Secure follows the `SITE_URL` scheme; dev login cookie
+  listed; Flask `session` contents and server-side OIDC state documented
+- References updated (reports folder no longer exists; ADR-064 replaced ADR-005)
+
 ### Version 1.0 (2025-11-18)
 - Initial version
 - Established `starpunk_` prefix convention
@@ -223,5 +244,5 @@ def test_auth_cookie_name(client):
 ---
 
 **Document Owner**: StarPunk Architecture Team
-**Last Updated**: 2025-11-18
+**Last Updated**: 2026-11-03
 **Status**: Active Standard
diff --git a/docs/standards/development-setup.md b/docs/standards/development-setup.md
index 0f4243a..42f3df3 100644
--- a/docs/standards/development-setup.md
+++ b/docs/standards/development-setup.md
@@ -1,814 +1,154 @@
-# Development Setup Standards
+# Development Setup
 
-## Purpose
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-This document defines the standard development setup procedure for StarPunk. It provides step-by-step instructions for developer agents and humans to create a fully functional development environment from scratch.
+How to set up a local StarPunk environment, run the app and run the tests.
+Each configuration variable is described in [`.env.example`](../../.env.example);
+deployment is in [architecture/deployment.md](../architecture/deployment.md).
 
-## Prerequisites
+## Requirements
 
-### System Requirements
+- Python 3.11 (the container image uses `python:3.11-slim`)
+- [uv](https://docs.astral.sh/uv/) for the virtual environment and packages ([ADR-006](../decisions/ADR-006-python-virtual-environment-uv.md))
+- git
+- Optional: Docker or Podman, to build the image and run the CI test stage locally
 
-- **Operating System**: Linux, macOS, or Windows with WSL2
-- **Python**: 3.11 or higher
-- **Disk Space**: 500MB minimum
-- **Network**: Internet connection for package downloads
+## Environment
 
-### Required Tools
-
-- **Python 3.11+**: System Python installation
-- **uv**: Python package and environment manager
-- **git**: Version control (for cloning repository)
-
-## Installation Steps
-
-### Step 1: Verify Python Installation
+The repository has no `pyproject.toml`; dependencies are in
+`requirements.txt` (runtime) and `requirements-dev.txt` (adds pytest-cov,
+pytest-mock, black, flake8, mypy).
 
 ```bash
-# Check Python version
-python3 --version
-
-# Expected output: Python 3.11.x or higher
-```
-
-**If Python 3.11+ is not installed**:
-
-**Ubuntu/Debian**:
-```bash
-sudo apt update
-sudo apt install python3.11 python3.11-venv
-```
-
-**macOS**:
-```bash
-brew install python@3.11
-```
-
-**Arch Linux**:
-```bash
-sudo pacman -S python
-```
-
----
-
-### Step 2: Install uv
-
-**Linux/macOS (Recommended)**:
-```bash
-# Install via official installer
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Verify installation
-uv --version
-```
-
-**Alternative (via pip)**:
-```bash
-# Install uv using pip
-pip install --user uv
-
-# Verify installation
-uv --version
-```
-
-**Windows**:
-```powershell
-# Using PowerShell
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
-# Verify installation
-uv --version
-```
-
-**Expected Output**: `uv 0.x.x` (any recent version)
-
-See [ADR-006](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md) for full uv standards.
-
----
-
-### Step 3: Clone Repository
-
-```bash
-# Clone the repository
-git clone https://github.com/YOUR_USERNAME/starpunk.git
-cd starpunk
-
-# Verify you're in the correct directory
-pwd
-# Expected: /path/to/starpunk
-
-# List files to confirm
-ls -la
-# Should see: app.py, requirements.txt, starpunk/, etc.
-```
-
-**If starting from scratch without git**:
-Create the project structure manually following [Project Structure Design](/home/phil/Projects/starpunk/docs/design/project-structure.md).
-
----
-
-### Step 4: Create Virtual Environment
-
-```bash
-# Create virtual environment using uv
-uv venv .venv --python 3.11
-
-# Verify creation
-ls -la .venv
-
-# Expected: bin/, lib/, include/, pyvenv.cfg
-```
-
-**Verification**:
-```bash
-# Check Python executable exists
-.venv/bin/python --version
-
-# Expected: Python 3.11.x
-```
-
-**Important**: Virtual environment is created in `.venv/` directory at project root.
-
----
-
-### Step 5: Install Dependencies
-
-```bash
-# Install all production dependencies
-uv pip install -r requirements.txt
-
-# Verify installation
-uv pip list
-
-# Expected output should include:
-# - Flask (3.0.x)
-# - markdown (3.5.x)
-# - feedgen (1.0.x)
-# - httpx (0.27.x)
-# - python-dotenv (1.0.x)
-# - pytest (8.0.x)
-```
-
-**For Development** (optional):
-```bash
-# Install development dependencies
+git clone https://git.thesatelliteoflove.com/phil/StarPunk.git
+cd StarPunk
+uv venv --python 3.11            # creates .venv/ (gitignored)
 uv pip install -r requirements-dev.txt
-
-# Includes: pytest-cov, black, flake8, mypy
 ```
 
-**Troubleshooting**:
-- If installation fails, check internet connection
-- Verify uv is installed correctly: `which uv`
-- Check Python version in venv: `.venv/bin/python --version`
+Run everything through `uv run`, which picks up `.venv/` automatically:
+`uv run pytest`, `uv run flask ...`, `uv run python ...`. Never install into
+the system Python.
 
----
+To add a dependency, add a pinned line (`package==X.Y.*`) with a short
+comment to `requirements.txt`, then `uv pip install -r requirements.txt`.
+The file is maintained by hand; don't overwrite it with `pip freeze`.
 
-### Step 6: Configure Environment
+## Configuration
 
 ```bash
-# Copy environment template
 cp .env.example .env
-
-# Edit .env file with your settings
-nano .env  # or vim, code, etc.
+python3 -c "import secrets; print(secrets.token_hex(32))"   # paste as SESSION_SECRET
 ```
 
-**Required Configuration** (edit `.env`):
+`starpunk/config.py` loads `.env` (python-dotenv; real environment
+variables win) and validates at startup, raising `ValueError` with every
+problem it found. What is required depends on the mode:
+
+| Setting | Production | `DEV_MODE=true` |
+|---|---|---|
+| `SESSION_SECRET` | required | required |
+| `SITE_URL`, `SITE_NAME`, `SITE_AUTHOR` | required (have defaults) | same |
+| `ADMIN_ME` | required | optional |
+| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ADMIN_SUB` | required | optional |
+| `DEV_ADMIN_ME` | unused | required |
+
+`TOKEN_ENDPOINT` and `INDIELOGIN_URL` are no longer read (v2.0.0 replaced
+IndieLogin with OIDC admin login and a built-in IndieAuth server, ADR-064);
+the app logs a warning if they are set.
+
+## Running the app locally
+
+There is no separate database step: `create_app()` creates `DATA_PATH`,
+`NOTES_PATH` and the database, and applies pending migrations
+(`starpunk/migrations.py`) at startup.
+
+For local work, use development login instead of OIDC
+([ADR-011](../decisions/ADR-011-development-authentication-mechanism.md)):
 
 ```bash
-# Site Configuration
-SITE_URL=http://localhost:5000
-SITE_NAME=My StarPunk Site
-SITE_AUTHOR=Your Name
-
-# Admin Authentication
-ADMIN_ME=https://your-website.com
-# ^ Replace with YOUR IndieWeb identity URL
-
-# Session Security
-SESSION_SECRET=GENERATE_RANDOM_SECRET_HERE
-# ^ Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
-
-# Data Paths
-DATA_PATH=./data
-NOTES_PATH=./data/notes
-DATABASE_PATH=./data/starpunk.db
-
-# Flask Configuration
-FLASK_ENV=development
-FLASK_DEBUG=1
+# in .env
+DEV_MODE=true
+DEV_ADMIN_ME=http://localhost:5000/
 ```
 
-**Generate SESSION_SECRET**:
-```bash
-# Generate cryptographically secure secret
-python3 -c "import secrets; print(secrets.token_hex(32))"
-
-# Copy output and paste into .env as SESSION_SECRET value
-```
-
-**Important**:
-- **NEVER commit `.env` file** to git
-- `.env.example` is a template and SHOULD be committed
-- Each developer/deployment has their own `.env`
-
----
-
-### Step 7: Initialize Database
-
 ```bash
-# Create data directory structure
-mkdir -p data/notes
-
-# Initialize database schema
-.venv/bin/python -c "from starpunk.database import init_db; init_db()"
-
-# Verify database created
-ls -la data/
-
-# Expected: starpunk.db file should exist
+uv run flask --app app.py run --debug      # http://localhost:5000
 ```
 
-**Alternative** (if Flask CLI is set up):
-```bash
-# Initialize via Flask CLI
-.venv/bin/flask db init
-```
+`DEV_MODE=true` registers `/dev/login` (otherwise those routes don't exist),
+adds a "Quick Dev Login (No Auth)" button to `/auth/login` and a warning
+banner to every page. It sets the `starpunk_session` cookie for
+`DEV_ADMIN_ME` without any authentication: never enable it on a reachable
+server.
 
-**Verify Database Schema**:
-```bash
-# Check tables exist
-sqlite3 data/starpunk.db ".tables"
+Each app process also starts background threads: the webmention worker,
+the WebSub hub worker, the memory monitor and, when a crossposting target
+is configured, the syndication worker. Turn off what you don't need locally
+with `WEBMENTION_WORKER_ENABLED=false`, `WEBSUB_ENABLED=false` and
+`METRICS_ENABLED=false`. Leave `GOTOSOCIAL_*`, `BLUESKY_*` and `THREADS_*`
+empty unless you mean to post to those accounts.
 
-# Expected output: notes, sessions, tokens, auth_state
-```
-
----
-
-### Step 8: Verify Installation
+Production runs the same app under gunicorn (`gunicorn app:app`, see `CMD`
+in `Containerfile`). To try the image locally:
 
 ```bash
-# Run all verification checks
-.venv/bin/python -c "
-from starpunk.config import load_config
-from starpunk.database import verify_db
-import flask
-print('✓ Flask version:', flask.__version__)
-print('✓ Config loads successfully')
-print('✓ Database schema verified')
-print('✓ Installation complete!')
-"
+docker build -t starpunk:dev -f Containerfile .
+docker run --rm -p 8000:8000 --env-file .env -v ./container-data:/data starpunk:dev
 ```
 
-**Manual Verification Checklist**:
-```bash
-# Check virtual environment
-[ -d ".venv" ] && echo "✓ Virtual environment exists" || echo "✗ Missing .venv"
-
-# Check Python version
-.venv/bin/python --version | grep "3.11" && echo "✓ Python 3.11+" || echo "✗ Wrong Python version"
-
-# Check Flask installed
-.venv/bin/python -c "import flask" && echo "✓ Flask installed" || echo "✗ Flask missing"
-
-# Check .env file exists
-[ -f ".env" ] && echo "✓ .env configured" || echo "✗ Missing .env"
-
-# Check data directory
-[ -d "data/notes" ] && echo "✓ Data directory exists" || echo "✗ Missing data/"
-
-# Check database
-[ -f "data/starpunk.db" ] && echo "✓ Database initialized" || echo "✗ Missing database"
-```
-
----
-
-### Step 9: Run Development Server
+## Running the tests
 
 ```bash
-# Run Flask development server
-.venv/bin/flask --app app.py run --debug
-
-# Alternative: Run directly
-.venv/bin/python app.py
+SESSION_SECRET=test uv run pytest                          # full suite
+SESSION_SECRET=test uv run pytest tests/test_websub.py      # one file
+SESSION_SECRET=test uv run pytest tests/test_micropub.py -k delete -x
 ```
 
-**Expected Output**:
-```
- * Serving Flask app 'app.py'
- * Debug mode: on
-WARNING: This is a development server. Do not use it in a production deployment.
- * Running on http://127.0.0.1:5000
-Press CTRL+C to quit
-```
+- `SESSION_SECRET` must be set (in `.env` or the environment) because
+  `load_config()` checks it before the test overrides are applied. The CI
+  test stage also sets `SITE_URL=http://localhost:5000` and
+  `ADMIN_ME=https://test.example.com`; set them too to reproduce CI exactly.
+- `tests/conftest.py` builds each app with `TESTING=True` and a temporary
+  `DATA_PATH` and database, so tests never touch `./data`. Under
+  `TESTING=True` the background workers and memory monitor don't start and
+  the production OIDC check is skipped.
+- `tests/test_migration_race_condition.py` is slow (about 5 minutes). While
+  iterating, add `--ignore=tests/test_migration_race_condition.py`; run the
+  full suite before releasing.
+- Coverage: `SESSION_SECRET=test uv run pytest --cov=starpunk --cov-report=term-missing`.
+- The CI test stage can be reproduced exactly with
+  `docker build --target test -f Containerfile .` (see
+  [testing-checklist.md](testing-checklist.md)).
 
-**Access Application**:
-- Open browser to: `http://localhost:5000`
-- Should see StarPunk homepage
-- No notes will exist on first run
-
-**Stop Server**:
-- Press `Ctrl+C` in terminal
-
----
-
-### Step 10: Run Tests
+## Useful commands
 
 ```bash
-# Run all tests
-.venv/bin/pytest
+# Version
+uv run python -c "import starpunk; print(starpunk.__version__)"
 
-# Run with coverage report
-.venv/bin/pytest --cov=starpunk tests/
+# Inspect the database
+sqlite3 data/starpunk.db '.tables'
+sqlite3 data/starpunk.db 'SELECT migration_name, applied_at FROM schema_migrations ORDER BY id'
 
-# Run specific test file
-.venv/bin/pytest tests/test_database.py
-
-# Run with verbose output
-.venv/bin/pytest -v
+# Reset local data (deletes notes, media and the database)
+rm -rf data/
 ```
 
-**Expected Output** (once tests are written):
-```
-======================== test session starts =========================
-collected 45 items
-
-tests/test_auth.py ........                                    [ 17%]
-tests/test_database.py .......                                 [ 33%]
-tests/test_feed.py .....                                       [ 44%]
-tests/test_micropub.py ..........                              [ 66%]
-tests/test_notes.py ..........                                 [ 88%]
-tests/test_utils.py .....                                      [100%]
-
-========================= 45 passed in 2.34s =========================
-```
-
----
-
-## Configuration Management
-
-### Environment Variables
-
-All configuration is managed via environment variables loaded from `.env` file.
-
-**Configuration Categories**:
-
-1. **Site Identity**
-   - `SITE_URL` - Public URL of site
-   - `SITE_NAME` - Site title
-   - `SITE_AUTHOR` - Author name
-   - `SITE_DESCRIPTION` - Site description (for RSS)
-
-2. **Authentication**
-   - `ADMIN_ME` - Admin's IndieWeb identity URL
-   - `SESSION_SECRET` - Secret key for session signing
-   - `SESSION_LIFETIME` - Session duration in days (default: 30)
-
-3. **Data Storage**
-   - `DATA_PATH` - Base data directory (default: `./data`)
-   - `NOTES_PATH` - Notes directory (default: `./data/notes`)
-   - `DATABASE_PATH` - SQLite database path (default: `./data/starpunk.db`)
-
-4. **Flask Settings**
-   - `FLASK_ENV` - Environment: `development` or `production`
-   - `FLASK_DEBUG` - Debug mode: `1` (on) or `0` (off)
-   - `FLASK_SECRET_KEY` - Falls back to `SESSION_SECRET`
-
-5. **External Services**
-   - `INDIELOGIN_URL` - IndieLogin service URL (default: `https://indielogin.com`)
-
-### Configuration Loading
-
-Configuration is loaded in this priority order:
-
-1. **Environment variables** (highest priority)
-2. **`.env` file** (loaded via python-dotenv)
-3. **Default values** (in `config.py`)
-
-**Example** (`starpunk/config.py`):
-```python
-import os
-from pathlib import Path
-from dotenv import load_dotenv
-
-# Load .env file
-load_dotenv()
-
-class Config:
-    # Site
-    SITE_URL = os.getenv('SITE_URL', 'http://localhost:5000')
-    SITE_NAME = os.getenv('SITE_NAME', 'StarPunk')
-
-    # Security
-    SECRET_KEY = os.getenv('SESSION_SECRET')
-    if not SECRET_KEY:
-        raise ValueError("SESSION_SECRET must be set in .env")
-
-    # Data paths
-    DATA_PATH = Path(os.getenv('DATA_PATH', './data'))
-    NOTES_PATH = Path(os.getenv('NOTES_PATH', './data/notes'))
-    DATABASE_PATH = Path(os.getenv('DATABASE_PATH', './data/starpunk.db'))
-
-    # Flask
-    DEBUG = os.getenv('FLASK_DEBUG', '1') == '1'
-    ENV = os.getenv('FLASK_ENV', 'development')
-```
-
-### Development vs Production Settings
-
-**Development** (`.env`):
-```bash
-FLASK_ENV=development
-FLASK_DEBUG=1
-SITE_URL=http://localhost:5000
-```
-
-**Production** (`.env`):
-```bash
-FLASK_ENV=production
-FLASK_DEBUG=0
-SITE_URL=https://your-domain.com
-```
-
-**Key Differences**:
-- **Debug mode**: Development has detailed errors, production hides them
-- **URL**: Development uses localhost, production uses actual domain
-- **HTTPS**: Production requires HTTPS, development doesn't
-- **Session cookies**: Production sets `Secure` flag, development doesn't
-
----
-
-## Common Development Tasks
-
-### Starting Development
-
-```bash
-# 1. Activate virtual environment context (via uv)
-cd /path/to/starpunk
-
-# 2. Run development server
-.venv/bin/flask --app app.py run --debug
-
-# Server runs on http://localhost:5000
-```
-
-### Running Tests
-
-```bash
-# All tests
-.venv/bin/pytest
-
-# Specific module
-.venv/bin/pytest tests/test_notes.py
-
-# Specific test
-.venv/bin/pytest tests/test_notes.py::test_create_note
-
-# With coverage
-.venv/bin/pytest --cov=starpunk --cov-report=html tests/
-# Open htmlcov/index.html to view coverage report
-```
-
-### Code Formatting
-
-```bash
-# Format all Python code
-.venv/bin/black starpunk/ tests/
-
-# Check formatting without changing
-.venv/bin/black --check starpunk/ tests/
-
-# Format specific file
-.venv/bin/black starpunk/notes.py
-```
-
-### Linting
-
-```bash
-# Lint all code
-.venv/bin/flake8 starpunk/ tests/
-
-# Lint specific file
-.venv/bin/flake8 starpunk/notes.py
-
-# Type checking (if mypy installed)
-.venv/bin/mypy starpunk/
-```
-
-### Adding Dependencies
-
-```bash
-# 1. Install new package
-uv pip install package-name
-
-# 2. Update requirements.txt
-uv pip freeze | sort > requirements.txt
-
-# 3. Commit updated requirements.txt
-git add requirements.txt
-git commit -m "Add package-name dependency"
-```
-
-### Database Operations
-
-```bash
-# Reset database (WARNING: deletes all data)
-rm data/starpunk.db
-.venv/bin/python -c "from starpunk.database import init_db; init_db()"
-
-# Backup database
-cp data/starpunk.db data/starpunk.db.backup
-
-# Inspect database
-sqlite3 data/starpunk.db
-# SQL> .tables
-# SQL> SELECT * FROM notes;
-# SQL> .quit
-```
-
-### Creating a Note Manually
-
-```bash
-# 1. Create directory for current month
-mkdir -p data/notes/$(date +%Y)/$(date +%m)
-
-# 2. Create markdown file
-cat > data/notes/$(date +%Y)/$(date +%m)/test-note.md << 'EOF'
-This is a test note created manually.
-
-It has **markdown** formatting and `code`.
-EOF
-
-# 3. Add to database
-.venv/bin/python -c "
-from starpunk.notes import scan_and_import_notes
-scan_and_import_notes()
-"
-```
-
----
-
 ## Troubleshooting
 
-### Issue: Virtual Environment Not Found
-
-**Symptom**: `bash: .venv/bin/python: No such file or directory`
-
-**Solution**:
-```bash
-# Check if .venv exists
-ls -la .venv
-
-# If not, create it
-uv venv .venv --python 3.11
-```
-
----
-
-### Issue: Import Errors
-
-**Symptom**: `ModuleNotFoundError: No module named 'flask'`
-
-**Solution**:
-```bash
-# Install dependencies
-uv pip install -r requirements.txt
-
-# Verify Flask is installed
-.venv/bin/python -c "import flask; print(flask.__version__)"
-```
-
----
-
-### Issue: Database Not Found
-
-**Symptom**: `sqlite3.OperationalError: unable to open database file`
-
-**Solution**:
-```bash
-# Create data directory
-mkdir -p data/notes
-
-# Initialize database
-.venv/bin/python -c "from starpunk.database import init_db; init_db()"
-
-# Verify
-ls -la data/starpunk.db
-```
-
----
-
-### Issue: Port Already in Use
-
-**Symptom**: `OSError: [Errno 98] Address already in use`
-
-**Solution**:
-```bash
-# Find process using port 5000
-lsof -i :5000
-
-# Kill the process
-kill -9 
-
-# Or use different port
-.venv/bin/flask run --port 5001
-```
-
----
-
-### Issue: Missing SESSION_SECRET
-
-**Symptom**: `ValueError: SESSION_SECRET must be set in .env`
-
-**Solution**:
-```bash
-# Generate secret
-python3 -c "import secrets; print(secrets.token_hex(32))"
-
-# Add to .env file
-echo "SESSION_SECRET=" >> .env
-```
-
----
-
-### Issue: Permission Denied on data/
-
-**Symptom**: `PermissionError: [Errno 13] Permission denied: 'data/notes'`
-
-**Solution**:
-```bash
-# Fix permissions
-chmod -R 755 data/
-chmod 644 data/starpunk.db  # If exists
-
-# Verify
-ls -la data/
-```
-
----
-
-## Agent-Specific Standards
-
-### For AI Developer Agents
-
-When setting up development environment, agents MUST:
-
-1. **Use absolute paths** in all bash commands
-   ```bash
-   # CORRECT
-   /home/phil/Projects/starpunk/.venv/bin/python
-
-   # WRONG
-   .venv/bin/python
-   ```
-
-2. **Check before creating** virtual environment
-   ```bash
-   if [ ! -d "/home/phil/Projects/starpunk/.venv" ]; then
-     uv venv /home/phil/Projects/starpunk/.venv --python 3.11
-   fi
-   ```
-
-3. **Verify each step** before proceeding
-   ```bash
-   # Example verification
-   [ -f "/home/phil/Projects/starpunk/.env" ] || echo "ERROR: .env missing"
-   ```
-
-4. **Never modify global Python**
-   ```bash
-   # FORBIDDEN
-   pip install flask
-
-   # CORRECT
-   uv pip install flask  # Uses active venv
-   ```
-
-See [ADR-006](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md) for complete agent standards.
-
----
-
-## Security Considerations
-
-### Secrets Management
-
-**DO**:
-- Store all secrets in `.env` file
-- Generate strong random secrets
-- Use different secrets for dev/production
-- Never log secrets
-
-**DON'T**:
-- Commit `.env` to version control
-- Hardcode secrets in code
-- Share secrets via email/chat
-- Reuse secrets across projects
-
-### File Permissions
-
-**Recommended Permissions**:
-```bash
-# Application code
-chmod 644 *.py
-chmod 755 starpunk/
-
-# Data directory
-chmod 755 data/
-chmod 755 data/notes/
-chmod 644 data/starpunk.db
-chmod 644 data/notes/**/*.md
-
-# Configuration
-chmod 600 .env  # Only owner can read
-```
-
-### Development-Only Features
-
-In development mode (FLASK_DEBUG=1):
-- Detailed error pages with stack traces
-- Auto-reload on code changes
-- No HTTPS requirement
-- More verbose logging
-
-**NEVER run production with FLASK_DEBUG=1**
-
----
-
-## Verification Checklist
-
-After completing setup, verify:
-
-- [ ] Python 3.11+ installed
-- [ ] uv installed and working
-- [ ] Virtual environment created in `.venv/`
-- [ ] All dependencies installed
-- [ ] `.env` file configured with SESSION_SECRET
-- [ ] `data/` directory exists and is gitignored
-- [ ] Database initialized with all tables
-- [ ] Development server starts successfully
-- [ ] Can access http://localhost:5000
-- [ ] Tests run successfully
-- [ ] Code formatting works (black)
-- [ ] Linting works (flake8)
-
----
-
-## Quick Reference
-
-### Essential Commands
-
-```bash
-# Start development server
-.venv/bin/flask --app app.py run --debug
-
-# Run tests
-.venv/bin/pytest
-
-# Format code
-.venv/bin/black starpunk/ tests/
-
-# Install dependency
-uv pip install 
-uv pip freeze | sort > requirements.txt
-
-# Database reset
-rm data/starpunk.db
-.venv/bin/python -c "from starpunk.database import init_db; init_db()"
-
-# Generate secret
-python3 -c "import secrets; print(secrets.token_hex(32))"
-```
-
-### File Locations
-
-```
-.venv/              # Virtual environment
-.env                # Configuration (secret, gitignored)
-.env.example        # Configuration template
-requirements.txt    # Production dependencies
-data/               # User data (gitignored)
-starpunk/           # Application code
-tests/              # Test suite
-```
-
----
-
-## Next Steps
-
-After setup is complete:
-
-1. Read [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-2. Review [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
-3. Explore [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-4. Start implementing features following [API Contracts](/home/phil/Projects/starpunk/docs/design/api-contracts.md)
-
----
+| Symptom | Cause |
+|---|---|
+| `SESSION_SECRET must be set in .env file` (also from pytest) | `SESSION_SECRET` missing from `.env` and the environment |
+| `Production mode requires OIDC_ISSUER to be set` | `DEV_MODE` is not `true` and OIDC is not configured |
+| `DEV_MODE=true requires DEV_ADMIN_ME to be set` | set `DEV_ADMIN_ME` |
+| `ModuleNotFoundError` | run through `uv run` after `uv pip install -r requirements-dev.txt` |
+| `/dev/login` returns 404 | `DEV_MODE` is not `true` |
 
 ## References
 
-- [ADR-006: Python Virtual Environment with uv](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
-- [Project Structure Design](/home/phil/Projects/starpunk/docs/design/project-structure.md)
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- [Flask Configuration Handling](https://flask.palletsprojects.com/en/3.0.x/config/)
-- [python-dotenv Documentation](https://pypi.org/project/python-dotenv/)
-- [uv Documentation](https://docs.astral.sh/uv/)
+- [ADR-006: Python virtual environment with uv](../decisions/ADR-006-python-virtual-environment-uv.md)
+- [ADR-011: Development authentication](../decisions/ADR-011-development-authentication-mechanism.md)
+- [ADR-064: OIDC admin login and built-in IndieAuth server](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md)
+- [python-coding-standards.md](python-coding-standards.md), [testing-checklist.md](testing-checklist.md), [git-branching-strategy.md](git-branching-strategy.md)
diff --git a/docs/standards/documentation-organization.md b/docs/standards/documentation-organization.md
index eff1a51..f325fb0 100644
--- a/docs/standards/documentation-organization.md
+++ b/docs/standards/documentation-organization.md
@@ -1,472 +1,98 @@
-# Documentation Organization Standard
+# Documentation Organization
 
-## Purpose
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-This document defines the organization and structure of all StarPunk documentation. It establishes clear guidelines for what types of documents belong where, naming conventions, and when to create each type.
+**[docs/DOCUMENTATION.md](../DOCUMENTATION.md) is authoritative** for what
+goes in which folder and supersedes this document. This standard only adds
+templates and conventions for writing the documents; it does not repeat
+the folder rules. If the two ever disagree, follow DOCUMENTATION.md and fix
+this file.
 
-## Philosophy
-
-Documentation follows the same principle as code: "Every document must justify its existence." Documents should be:
-
-- **Actionable**: Provide clear guidance for implementation
-- **Discoverable**: Easy to find based on purpose
-- **Maintainable**: Updated as decisions evolve
-- **Minimal**: No redundant or unnecessary documentation
-
-## Directory Structure
+## Layout at a glance
 
 ```
 docs/
-├── architecture/          # High-level system design and overviews
-├── decisions/            # Architecture Decision Records (ADRs)
-├── design/               # Detailed technical designs and specifications
-└── standards/            # Coding standards, conventions, and guidelines
+├── DOCUMENTATION.md   folder rules (authoritative)
+├── architecture/      current system design, refreshed each release; INDEX.md
+├── decisions/         ADR-NNN-title.md; INDEX.md
+├── design/            vX.Y.Z/ per release: designs, Q&A, reports, reviews; INDEX.md
+├── projectplan/       BACKLOG.md, vX.Y.Z/RELEASE.md; INDEX.md
+└── standards/         this folder; INDEX.md; DEPRECATED/ for retired standards
 ```
 
-## Document Types
+Outside `docs/`: `README.md` (overview and quick start), `CHANGELOG.md`
+(every release), `.env.example` (every setting), `CLAUDE.md` (agent
+instructions).
 
-### 1. Architecture Documents (`docs/architecture/`)
+## Conventions for every document
 
-**Purpose**: High-level system architecture, component relationships, and technology overviews.
+- Start with a `# Title`, then `**Status**` and `**Last Updated**` lines
+  (date and the release it describes) for documents meant to stay current
+  (architecture, standards).
+- Link with **relative paths** (`../decisions/ADR-064-...md`), never absolute
+  filesystem paths.
+- Say what is true of the code now; history belongs in ADRs, design notes
+  and the changelog. When describing something that changed, name the
+  release ("since v2.8.1").
+- Don't copy content between documents: link to the one place it lives.
+  Settings are documented in `.env.example`, releases in `CHANGELOG.md`,
+  the release process in
+  [git-branching-strategy.md](git-branching-strategy.md).
+- Update the folder's `INDEX.md` when adding, retiring or renaming a
+  document.
 
-**When to Create**:
-- Describing the overall system architecture
-- Documenting major subsystems and their interactions
-- Explaining technology stack choices (overview)
-- Defining deployment architecture
-- Documenting security architecture
-- Creating data flow diagrams
+## Architecture decision records
 
-**Naming Convention**: `{topic}.md`
+File: `docs/decisions/ADR-NNN-short-title.md`, next free number. Create one
+when choosing between technical approaches, adopting a protocol, or
+establishing a pattern. Template (as in ADR-064 to ADR-071):
 
-**Examples**:
-- `overview.md` - System architecture overview
-- `components.md` - Component descriptions and relationships
-- `data-flow.md` - How data moves through the system
-- `security.md` - Security architecture and threat model
-- `deployment.md` - Deployment architecture and strategies
-- `technology-stack.md` - Complete technology stack with rationale
-
-**Characteristics**:
-- Broad scope, high-level view
-- Focus on "what" and "why" at system level
-- Includes diagrams and visual representations
-- Describes component interactions
-- Documents architectural patterns
-- References relevant ADRs
-
-**Template Structure**:
 ```markdown
-# {Topic} Architecture
-
-## Overview
-[High-level description]
-
-## Components
-[Major components and their roles]
-
-## Interactions
-[How components communicate]
-
-## Patterns
-[Architectural patterns employed]
-
-## Diagrams
-[Visual representations]
-
-## References
-[Links to related ADRs and design docs]
-```
-
----
-
-### 2. Architecture Decision Records (`docs/decisions/`)
-
-**Purpose**: Document significant architectural decisions with context, rationale, and alternatives considered.
-
-**When to Create**:
-- Selecting technologies or libraries
-- Choosing between architectural approaches
-- Making trade-offs that affect multiple components
-- Establishing patterns or standards
-- Accepting technical debt
-- Rejecting common alternatives
-
-**Naming Convention**: `ADR-{NNN}-{short-title}.md`
-- NNN = Zero-padded sequential number (001, 002, etc.)
-- short-title = Kebab-case description
-
-**Examples**:
-- `ADR-001-python-web-framework.md`
-- `ADR-002-flask-extensions.md`
-- `ADR-003-frontend-technology.md`
-- `ADR-004-file-based-note-storage.md`
-- `ADR-005-indielogin-authentication.md`
-- `ADR-006-python-virtual-environment-uv.md`
-
-**Characteristics**:
-- Focused on a single decision
-- Documents the decision-making process
-- Includes evaluation criteria
-- Lists alternatives considered with scores
-- Explains trade-offs and consequences
-- Has a status (Proposed, Accepted, Superseded)
-- Immutable once accepted (new ADR to change)
-
-**Required Template**:
-```markdown
-# ADR-{NNN}: {Title}
+# ADR-NNN: Title
 
 ## Status
-{Proposed|Accepted|Superseded by ADR-XXX}
+
+Proposed | Accepted (vX.Y.Z, YYYY-MM-DD) | Superseded by ADR-MMM
 
 ## Context
-What is the issue we're addressing? What are the requirements?
-What constraints do we face?
+The problem, constraints, and relevant spec (with link).
 
 ## Decision
-What have we decided? Be specific and clear.
-
-## Rationale
-Why did we make this decision?
-
-### {Technology/Approach} Score: X/10
-- Simplicity Score: X/10 - [explanation]
-- Fitness Score: X/10 - [explanation]
-- Maintenance Score: X/10 - [explanation]
-- Standards Compliance: Pass/Fail - [explanation]
+What we will do. Numbered subsections for larger designs, citing spec
+sections.
 
 ## Consequences
+What gets better, what gets worse, what to watch.
 
-### Positive
-- [List benefits]
+## Alternatives considered
+Each alternative and why it was not chosen.
 
-### Negative
-- [List drawbacks]
-
-### Mitigation
-- [How we address drawbacks]
-
-## Alternatives Considered
-
-### {Alternative 1} (Rejected/Considered)
-- Simplicity: X/10 - [explanation]
-- Fitness: X/10 - [explanation]
-- Maintenance: X/10 - [explanation]
-- Verdict: [Why rejected]
-
-### {Alternative 2} (Rejected/Considered)
-[Same structure]
-
-## Implementation Notes
-[Any specific guidance for implementing this decision]
-
-## References
-- [Links to specifications, documentation, related ADRs]
+## Amendments (vX.Y.Z, YYYY-MM-DD)
+Later changes to the decision, newest last.
 ```
 
-**Status Values**:
-- **Proposed**: Decision is under consideration
-- **Accepted**: Decision is final and should be implemented
-- **Superseded**: Decision has been replaced (link to new ADR)
+ADRs are not rewritten after acceptance. Change them with an
+**Amendments** section, or supersede them with a new ADR and set the old
+one's status to "Superseded by ADR-MMM".
 
-**Numbering Rules**:
-- Numbers are sequential starting from 001
-- Never reuse or skip numbers
-- Numbers are assigned when ADR is created, not when accepted
-- Numbers provide chronological history
+## Design notes
 
----
-
-### 3. Design Documents (`docs/design/`)
-
-**Purpose**: Detailed technical specifications for implementation, including schemas, APIs, file formats, and component interfaces.
-
-**When to Create**:
-- Defining database schemas
-- Specifying API contracts and endpoints
-- Designing file formats and structures
-- Defining component interfaces
-- Specifying configuration formats
-- Documenting project structure
-- Creating initial setup specifications
-
-**Naming Convention**: `{component-or-feature}.md`
-
-**Examples**:
-- `project-structure.md` - Complete directory and file organization
-- `database-schema.md` - Database tables, columns, indexes, relationships
-- `api-contracts.md` - RESTful API endpoint specifications
-- `micropub-endpoint.md` - Micropub API implementation details
-- `rss-feed-format.md` - RSS feed structure and generation
-- `ui-patterns.md` - User interface patterns and components
-- `component-interfaces.md` - How components communicate
-- `initial-files.md` - Bootstrap files and configurations
-- `authentication-flow.md` - Detailed auth implementation
-
-**Characteristics**:
-- Detailed and specific
-- Implementation-ready specifications
-- Includes code examples, schemas, formats
-- Defines exact file contents when applicable
-- Provides acceptance criteria
-- Focus on "how" at implementation level
-- Should be sufficient for developer to implement
-
-**Template Structure**:
-```markdown
-# {Component/Feature} Design
-
-## Purpose
-[What this component/feature does]
-
-## Overview
-[High-level description]
-
-## Specification
-
-### {Aspect 1}
-[Detailed specification with examples]
-
-### {Aspect 2}
-[Detailed specification with examples]
-
-## Implementation Details
-
-### File Structure
-[If applicable]
-
-### API Endpoints
-[If applicable]
-
-### Database Schema
-[If applicable]
-
-### Configuration
-[If applicable]
-
-## Examples
-[Concrete examples of usage]
-
-## Acceptance Criteria
-[How to verify correct implementation]
-
-## References
-[Related ADRs, standards, specifications]
-```
-
----
-
-### 4. Standards Documents (`docs/standards/`)
-
-**Purpose**: Establish coding conventions, development practices, and guidelines that ensure consistency.
-
-**When to Create**:
-- Defining coding style guidelines
-- Establishing naming conventions
-- Documenting development setup procedures
-- Creating testing standards
-- Defining commit message formats
-- Establishing documentation standards
-- Setting API design principles
-
-**Naming Convention**: `{topic}-standards.md` or `{topic}-setup.md`
-
-**Examples**:
-- `documentation-organization.md` - This document
-- `python-coding-standards.md` - Python style guide
-- `development-setup.md` - Setup procedures
-- `testing-strategy.md` - Testing approach and standards
-- `api-design.md` - API design principles
-- `indieweb-compliance.md` - How to meet IndieWeb specs
-- `commit-conventions.md` - Git commit standards
-
-**Characteristics**:
-- Prescriptive and normative
-- Define consistent practices
-- Include examples of good/bad patterns
-- Focus on "how we work"
-- Living documents (updated as practices evolve)
-- Should include rationale for standards
-
-**Template Structure**:
-```markdown
-# {Topic} Standards
-
-## Purpose
-[Why these standards exist]
-
-## Principles
-[Core principles underlying the standards]
+File: `docs/design/vX.Y.Z/YYYY-MM-DD-topic.md`, one folder per release
+(rules in DOCUMENTATION.md). For format, see
+[version-implementation-guide.md](version-implementation-guide.md#design-note).
 
 ## Standards
 
-### {Standard Category 1}
-[Detailed standard with examples]
+File: `docs/standards/topic.md`. Each standard states what is required, why,
+and how to check it, and is kept true to the code. A standard that no
+longer applies is moved to `docs/standards/DEPRECATED/` with a note at the
+top saying what replaced it, and removed from the active list in
+`standards/INDEX.md`.
 
-**Good Example**:
-```[code/example]
-```
+## Retiring other documents
 
-**Bad Example**:
-```[code/example]
-```
-
-**Rationale**: [Why this is the standard]
-
-### {Standard Category 2}
-[Same structure]
-
-## Enforcement
-[How standards are enforced - tools, reviews, etc.]
-
-## Exceptions
-[When it's acceptable to deviate]
-
-## References
-[Related standards, tools, specifications]
-```
-
----
-
-## Cross-References
-
-Documents should reference each other appropriately:
-
-- **ADRs** → Should be referenced by Architecture, Design, and Standards docs
-- **Architecture** → References ADRs, links to Design docs
-- **Design** → References ADRs, may reference Standards
-- **Standards** → May reference ADRs for rationale
-
-**Reference Format**:
-```markdown
-See [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
-See [Database Schema Design](/home/phil/Projects/starpunk/docs/design/database-schema.md)
-See [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-```
-
-## Document Lifecycle
-
-### Creating Documents
-
-1. **Determine Type**: Which category does this belong in?
-2. **Check for Existing**: Does a similar document already exist?
-3. **Name Appropriately**: Follow naming conventions
-4. **Use Template**: Start from the appropriate template
-5. **Be Specific**: Include actionable details
-6. **Reference Related Docs**: Link to ADRs and other docs
-
-### Updating Documents
-
-**ADRs**: Once accepted, ADRs are immutable. To change a decision:
-- Create a new ADR
-- Reference the old ADR
-- Mark old ADR as "Superseded by ADR-XXX"
-
-**Other Documents**: Living documents that should be updated:
-- Add changelog section if document changes significantly
-- Update references when related docs change
-- Keep in sync with actual implementation
-
-### Deprecating Documents
-
-**Don't Delete**: Mark as deprecated instead
-- Add "DEPRECATED" to title
-- Add note explaining why and what replaced it
-- Keep for historical reference
-
-## Quality Checklist
-
-Before finalizing any document:
-
-- [ ] Is this the right document type for this content?
-- [ ] Is the file in the correct directory?
-- [ ] Does it follow the naming convention?
-- [ ] Does it use the appropriate template?
-- [ ] Is the content actionable and specific?
-- [ ] Are all references correct and complete?
-- [ ] Are there code examples where helpful?
-- [ ] Is the rationale clear?
-- [ ] Can a developer implement from this?
-- [ ] Have I removed unnecessary content?
-
-## Anti-Patterns
-
-**Avoid**:
-- Mixing document types (ADR with design specs)
-- Redundant documentation (saying same thing in multiple places)
-- Vague specifications ("should be fast", "user-friendly")
-- Missing rationale (standards without explaining why)
-- Orphaned documents (not referenced anywhere)
-- Documentation for documentation's sake
-- Copy-pasting without adapting
-
-## Tools and Automation
-
-**Validation**:
-- Check links: Ensure all references point to existing files
-- Naming validation: Verify naming conventions
-- Template compliance: Ensure required sections exist
-
-**Future Enhancements** (V2):
-- Automated ADR numbering
-- Documentation index generator
-- Link checker
-- Template enforcement
-
-## Examples
-
-### When to Create Which Document Type
-
-**Scenario**: Choosing between SQLite and PostgreSQL
-
-→ Create an ADR (`ADR-007-database-engine.md`)
-- This is a technology decision
-- Needs evaluation of alternatives
-- Has long-term architectural impact
-
-**Scenario**: Defining the exact database schema
-
-→ Create a Design doc (`database-schema.md`)
-- This is detailed specification
-- Implementation-ready
-- May evolve as requirements change
-
-**Scenario**: Establishing how to write database migrations
-
-→ Create a Standards doc (`database-migration-standards.md`)
-- This is a practice/process
-- Defines consistent approach
-- Applies to all database changes
-
-**Scenario**: Explaining how authentication, database, and file storage work together
-
-→ Create an Architecture doc or update existing (`architecture/overview.md`)
-- This is system-level interaction
-- Cross-component relationship
-- High-level understanding
-
-## Summary
-
-| Type | Purpose | Location | Mutability | Naming |
-|------|---------|----------|------------|--------|
-| **Architecture** | System-level design | `docs/architecture/` | Living | `{topic}.md` |
-| **ADR** | Decision records | `docs/decisions/` | Immutable | `ADR-{NNN}-{title}.md` |
-| **Design** | Implementation specs | `docs/design/` | Living | `{component}.md` |
-| **Standards** | Coding/process guidelines | `docs/standards/` | Living | `{topic}-standards.md` |
-
-## Principles Summary
-
-1. **One Document Type Per File**: Don't mix ADR with Design specs
-2. **Right Place, Right Name**: Follow conventions strictly
-3. **Actionable Content**: Documentation should enable implementation
-4. **Minimal but Complete**: Every document must justify its existence
-5. **Reference Richly**: Link to related documents
-6. **Update Living Docs**: Keep non-ADR docs current
-7. **Never Delete**: Deprecate instead for historical reference
-
-## References
-
-- Michael Nygard's ADR pattern: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
-- Arc42 documentation: https://arc42.org/
-- Diátaxis documentation framework: https://diataxis.fr/
+- Architecture documents describing a design that no longer exists are
+  either rewritten or renamed with a `-legacy` suffix and a note at the top
+  (e.g. `architecture/technology-stack-legacy.md`).
+- Design notes and ADRs are historical records and stay where they are.
diff --git a/docs/standards/git-branching-strategy.md b/docs/standards/git-branching-strategy.md
index a665225..0c6fb8e 100644
--- a/docs/standards/git-branching-strategy.md
+++ b/docs/standards/git-branching-strategy.md
@@ -1,724 +1,177 @@
-# Git Branching Strategy
+# Git Branching and Release Process
 
-## Overview
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-This document defines the git branching strategy for StarPunk. The strategy balances simplicity with discipline, appropriate for a personal/small-team project while supporting semantic versioning and clean releases.
+How changes reach `main`, how releases are cut, and what happens after a
+tag is pushed. This is the flow used for the v2 releases (see
+`git log --merges`). Which version number to use is in
+[versioning-strategy.md](versioning-strategy.md). The original reasoning is
+in [ADR-009](../decisions/ADR-009-git-branching-strategy.md); where they
+differ, this document describes current practice.
 
-**Philosophy**: Keep it simple. Minimize long-lived branches. Integrate frequently.
+## Principles
 
-## Primary Branch
+- `main` is always releasable and is never rewritten or force-pushed.
+- Each release is built on its own short-lived branch, usually as a single
+  commit, and merged with `--no-ff` so `main` shows one merge per release.
+- Every release is an annotated `vX.Y.Z` tag on `main`. The tag is what
+  triggers CI; CI is what publishes the image.
+- Several agents may work on the repository at once, so each works in its
+  own git worktree, never in the main checkout's working tree.
 
-**Branch**: `main`
+## Branches
 
-**Purpose**: The primary development branch and source of truth
+| Prefix | Use | Example |
+|---|---|---|
+| `feat/` | new behaviour (MINOR) | `feat/v2.10.0-websub` |
+| `fix/` | bug and security fixes (PATCH) | `fix/v2.10.1-websub-hardening` |
+| `ci/` | build and CI changes | `ci/v2.7.1-pytest` |
+| `docs/` | documentation only, no release | `docs/refresh-v2.10.1` |
 
-**Characteristics**:
-- Always contains the latest development code
-- Should be stable and pass all tests
-- Protected from direct commits (use pull requests)
-- Tagged for releases
-- Never rewritten or force-pushed
+Release branches are named `/vX.Y.Z-`, so the
+branch already states the version it will become. (Releases before v2.6.0
+used `feature/`; read old history with that in mind.) There are no long-lived
+`develop`, `release/` or `hotfix/` branches: a production fix is just the
+next PATCH release from `main`.
 
-**Version state**: Development version (0.x.y) until first stable release (1.0.0)
+## Commits
 
-## Branch Types
+Conventional-commit style subject, with the version in parentheses on the
+release commit:
 
-### Feature Branches
-
-**Naming**: `feature/` or ``
-
-**Purpose**: Develop new features or enhancements
-
-**Lifecycle**:
-- Branch from: `main`
-- Merge into: `main`
-- Delete after: Merged or abandoned
-
-**Examples**:
-- `feature/micropub-endpoint`
-- `feature/rss-feed`
-- `indieauth-integration`
-- `note-markdown-support`
-
-**Workflow**:
-```bash
-# Create feature branch
-git checkout -b feature/micropub-endpoint main
-
-# Work on feature
-git add .
-git commit -m "Add micropub endpoint skeleton"
-
-# Keep updated with main
-git fetch origin
-git rebase origin/main
-
-# When ready, create pull request or merge
-git checkout main
-git merge feature/micropub-endpoint
-
-# Delete feature branch
-git branch -d feature/micropub-endpoint
+```
+feat: WebSub with a built-in hub (v2.10.0)
+fix: Hold the migration lock for the whole run (v2.8.1)
+ci: Run the test suite before building release images (v2.7.1)
+docs: ADR-071 WebSub publishing with a built-in hub (proposed)
 ```
 
-### Fix Branches
+Types in use: `feat`, `fix`, `ci`, `docs`, `style`, `refactor`, `test`,
+`chore`. The body explains why, not what. Commits made by an agent end with
+the attribution trailer the agent was given.
 
-**Naming**: `fix/` or `bugfix/`
+An ADR can land on `main` ahead of its implementation (`docs:` commit,
+status "Proposed"), as ADR-071 did before v2.10.0.
 
-**Purpose**: Fix bugs in development code
+## Release process
 
-**Lifecycle**:
-- Branch from: `main`
-- Merge into: `main`
-- Delete after: Merged
-
-**Examples**:
-- `fix/slug-generation-unicode`
-- `bugfix/rss-invalid-xml`
-- `fix/auth-redirect-loop`
-
-**Workflow**: Same as feature branches
-
-### Hotfix Branches
-
-**Naming**: `hotfix/-`
-
-**Purpose**: Critical fixes to production releases (post-1.0.0)
-
-**Lifecycle**:
-- Branch from: Release tag (e.g., `v1.0.0`)
-- Merge into: `main`
-- Tag as new release: `v1.0.1`
-- Delete after: Released
-
-**Examples**:
-- `hotfix/1.0.1-security-path-traversal`
-- `hotfix/1.1.1-rss-encoding`
-
-**Workflow**:
-```bash
-# Create hotfix from release tag
-git checkout -b hotfix/1.0.1-security-fix v1.0.0
-
-# Fix the issue
-git commit -m "Fix security vulnerability"
-
-# Update version
-# Edit starpunk/__init__.py: __version__ = "1.0.1"
-# Update CHANGELOG.md
-
-git commit -m "Bump version to 1.0.1"
-
-# Tag the hotfix
-git tag -a v1.0.1 -m "Hotfix 1.0.1: Security vulnerability fix"
-
-# Merge into main
-git checkout main
-git merge hotfix/1.0.1-security-fix
-
-# Push
-git push origin main v1.0.1
-
-# Delete hotfix branch
-git branch -d hotfix/1.0.1-security-fix
-```
-
-### Release Branches (Optional)
-
-**Naming**: `release/`
-
-**Purpose**: Prepare for release (testing, docs, version bumps)
-
-**Used when**: Release preparation requires multiple commits and testing
-
-**Note**: For V1 (simple project), we likely don't need release branches. We can prepare releases directly on `main` or feature branches.
-
-**If used**:
-```bash
-# Create release branch
-git checkout -b release/1.0.0 main
-
-# Prepare release
-# - Update version numbers
-# - Update CHANGELOG.md
-# - Update documentation
-# - Final testing
-
-git commit -m "Prepare release 1.0.0"
-
-# Tag
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-
-# Merge to main
-git checkout main
-git merge release/1.0.0
-
-# Push
-git push origin main v1.0.0
-
-# Delete release branch
-git branch -d release/1.0.0
-```
-
-## Branch Naming Conventions
-
-### Format
-
-**Preferred**: `/`
-
-**Types**:
-- `feature/` - New features
-- `fix/` - Bug fixes
-- `bugfix/` - Bug fixes (alternative)
-- `hotfix/` - Production hotfixes
-- `docs/` - Documentation only
-- `refactor/` - Code refactoring
-- `test/` - Test additions/changes
-- `chore/` - Maintenance tasks
-
-**Description**:
-- Use lowercase
-- Use hyphens to separate words
-- Be descriptive but concise
-- Reference issue number if applicable
-
-### Examples
-
-**Good**:
-- `feature/micropub-create-action`
-- `fix/rss-pubdate-timezone`
-- `docs/api-documentation`
-- `refactor/note-storage-layer`
-- `test/slug-generation-edge-cases`
-- `chore/update-dependencies`
-
-**Acceptable** (simple description):
-- `micropub-endpoint`
-- `rss-feed`
-- `auth-integration`
-
-**Avoid**:
-- `my-feature` (too vague)
-- `feature/Feature1` (not descriptive)
-- `fix_bug` (use hyphens)
-- `FEATURE-MICROPUB` (use lowercase)
-
-## Workflows
-
-### Development Workflow (Pre-1.0)
-
-**For single developer**:
-
-1. Work directly on `main` for small changes
-2. Use feature branches for larger features
-3. Commit frequently with clear messages
-4. Tag development milestones (e.g., `v0.1.0`)
-
-**For multiple developers**:
-
-1. Always use feature branches
-2. Create pull requests
-3. Review before merging
-4. Delete feature branches after merge
-
-### Feature Development
+### 1. Branch in a worktree
 
 ```bash
-# Start feature
-git checkout -b feature/new-feature main
-
-# Develop
-git add file.py
-git commit -m "Implement core functionality"
-
-# Keep updated
-git fetch origin
-git rebase origin/main
-
-# Finish
-git checkout main
-git merge feature/new-feature
-git push origin main
-git branch -d feature/new-feature
+cd ~/Documents/projects/StarPunk                 # main checkout, on main
+git pull
+git worktree add ../StarPunk-worktrees/v2.10.1 -b fix/v2.10.1-websub-hardening main
+cd ../StarPunk-worktrees/v2.10.1
+uv venv --python 3.11 && uv pip install -r requirements-dev.txt
 ```
 
-### Release Workflow
+### 2. Make the change
 
-**For development releases (0.x.y)**:
+Code, tests and docs together:
+
+- [ ] Code and tests (see [testing-checklist.md](testing-checklist.md))
+- [ ] Schema change? Add the next numbered file in `migrations/` (see
+      [Migrations](#migrations))
+- [ ] New setting? Read it in `starpunk/config.py` and document it in
+      `.env.example`
+- [ ] Architectural decision? New ADR in `docs/decisions/`, or an
+      "Amendments" section on the existing one
+- [ ] Bump the version in `starpunk/__init__.py`: both `__version__` and
+      `__version_info__` ([version-implementation-guide.md](version-implementation-guide.md))
+- [ ] Add a `## [X.Y.Z] - YYYY-MM-DD` entry at the top of `CHANGELOG.md`
+- [ ] Add a design note `docs/design/vX.Y.Z/YYYY-MM-DD-.md` (what
+      changed and why, how it was verified). Small releases fully covered by
+      an ADR amendment and the changelog may skip it
+- [ ] Full test suite passes:
+      `SESSION_SECRET=test uv run pytest`
+
+Commit (usually one commit):
 
 ```bash
-# Ensure on main
-git checkout main
-
-# Update version
-# Edit starpunk/__init__.py
-# Update CHANGELOG.md
-
-# Commit
-git add starpunk/__init__.py CHANGELOG.md
-git commit -m "Bump version to 0.2.0"
-
-# Tag
-git tag -a v0.2.0 -m "Development release 0.2.0: Phase 1.2 complete"
-
-# Push
-git push origin main v0.2.0
+git add -A
+git commit -m "fix: WebSub hardening from the adversarial review (v2.10.1)"
 ```
 
-**For stable releases (1.0.0+)**:
+### 3. Merge, tag, push
+
+From the main checkout:
 
 ```bash
-# Option 1: Direct on main (simple)
-git checkout main
-# Update version, changelog, documentation
-git commit -m "Prepare release 1.0.0"
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-git push origin main v1.0.0
-
-# Option 2: Using release branch (if needed)
-git checkout -b release/1.0.0 main
-# Prepare release
-git commit -m "Prepare release 1.0.0"
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-git checkout main
-git merge release/1.0.0
-git push origin main v1.0.0
-git branch -d release/1.0.0
+cd ~/Documents/projects/StarPunk
+git checkout main && git pull
+git merge --no-ff fix/v2.10.1-websub-hardening \
+    -m "Merge branch 'fix/v2.10.1-websub-hardening' for v2.10.1 release"
+git tag -a v2.10.1 -m "v2.10.1: WebSub hardening"
+git push origin main v2.10.1
 ```
 
-### Hotfix Workflow
+Then remove the worktree and branch:
 
 ```bash
-# Create from release tag
-git checkout -b hotfix/1.0.1-critical-fix v1.0.0
-
-# Fix
-git commit -m "Fix critical bug"
-
-# Version bump
-git commit -m "Bump version to 1.0.1"
-
-# Tag
-git tag -a v1.0.1 -m "Hotfix 1.0.1: Critical bug fix"
-
-# Merge to main
-git checkout main
-git merge hotfix/1.0.1-critical-fix
-
-# Push
-git push origin main v1.0.1
-
-# Clean up
-git branch -d hotfix/1.0.1-critical-fix
+git worktree remove ../StarPunk-worktrees/v2.10.1
+git branch -d fix/v2.10.1-websub-hardening
 ```
 
-## Branch Protection Rules
+Merging to `main`, tagging and pushing are release actions: an agent does
+them only when the project owner has asked for the release.
 
-### Main Branch Protection
+### 4. CI builds the image
 
-**For solo development**:
-- Recommended but not enforced via GitHub
-- Self-discipline: treat `main` as protected
-- Don't force push
-- Don't rewrite history
+Pushing a tag that matches `v[0-9]+.[0-9]+.[0-9]+` runs
+`.gitea/workflows/build-container.yml` on the Gitea runner:
 
-**For team development**:
-- Require pull request reviews
-- Require status checks to pass
-- Prevent force push
-- Prevent deletion
+1. builds the Containerfile `test` stage, which runs the whole pytest
+   suite; a failure stops the workflow and nothing is published;
+2. builds the runtime image and pushes
+   `git.thesatelliteoflove.com/phil/starpunk:vX.Y.Z` and `:latest`.
 
-**GitHub settings** (when ready):
-```
-Settings → Branches → Add branch protection rule
+Pre-release tags such as `v2.0.0-rc.1` don't match the pattern and are not
+built by CI. The workflow can also be started by hand
+(`workflow_dispatch`).
 
-Branch name pattern: main
+If CI fails, fix it on a new branch and release the next PATCH version.
+Don't move or re-push an existing tag.
 
-Protect matching branches:
-☑ Require a pull request before merging
-  ☑ Require approvals (1)
-☑ Require status checks to pass before merging
-  ☑ Require branches to be up to date before merging
-☑ Require conversation resolution before merging
-☑ Do not allow bypassing the above settings
-☐ Allow force pushes (NEVER enable)
-☐ Allow deletions (NEVER enable)
-```
+### 5. Deploy
 
-## Tagging Strategy
+Production is managed from the separate Ansible deployment repository, not
+from this one:
 
-### Tag Format
+1. If the release has a migration, back up the production database first
+   (see [architecture/deployment.md](../architecture/deployment.md)).
+   Migrations run automatically when the new container starts.
+2. In the deployment repository, set `starpunk_version` to the new tag and
+   deploy the `starpunk` service.
+3. Check `/health`, the home page, admin login and the feature that changed.
 
-**Version tags**: `vMAJOR.MINOR.PATCH[-PRERELEASE]`
+## Migrations
 
-**Examples**:
-- `v0.1.0` - Development release
-- `v1.0.0` - First stable release
-- `v1.0.1` - Patch release
-- `v1.1.0` - Minor release
-- `v2.0.0` - Major release
-- `v1.0.0-alpha.1` - Pre-release
+- Files are `migrations/NNN_description.sql`, numbered sequentially.
+  `starpunk/migrations.py` applies the pending ones at startup and records
+  them in `schema_migrations`.
+- Every gunicorn worker runs the migration check at startup; a
+  `BEGIN IMMEDIATE` lock makes one worker apply them while the others wait.
+  Since v2.8.1 the statements run with `conn.execute` inside that
+  transaction. Don't use `executescript()` (it commits and drops the lock)
+  and don't put `BEGIN`/`COMMIT` in migration files.
+- Migrations only move forward; there are no down migrations. The backup
+  is the rollback.
+- Test a new migration against a copy of a database at the previous
+  version.
 
-### Tag Types
+See [ADR-020](../decisions/ADR-020-automatic-database-migrations.md),
+[ADR-037](../decisions/ADR-037-migration-race-condition-fix.md) and
+`docs/design/v2.8.1/2026-11-03-migration-lock.md`.
 
-**Annotated tags** (ALWAYS use for releases):
-```bash
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-```
+## Documentation-only changes
 
-**Why annotated**:
-- Contains tagger, date, message
-- Can include release notes
-- Can be GPG signed
-- Treated as full Git objects
-- Better for releases
-
-**Lightweight tags** (NEVER use for releases):
-```bash
-git tag v1.0.0  # Don't do this for releases
-```
-
-### Tag Messages
-
-**Format**:
-```
-Release MAJOR.MINOR.PATCH: 
-
-[Optional longer description]
-[Release highlights]
-```
-
-**Examples**:
-```bash
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release
-
-Complete IndieWeb CMS implementation with:
-- IndieAuth authentication
-- Micropub publishing endpoint
-- RSS feed generation
-- File-based note storage
-- Markdown support"
-
-git tag -a v1.0.1 -m "Hotfix 1.0.1: Security vulnerability fix"
-
-git tag -a v0.2.0 -m "Development release 0.2.0: Phase 1.2 complete"
-```
-
-### Viewing Tags
-
-```bash
-# List all tags
-git tag
-
-# List tags with messages
-git tag -n
-
-# Show tag details
-git show v1.0.0
-
-# List tags matching pattern
-git tag -l "v1.0.*"
-```
-
-### Pushing Tags
-
-```bash
-# Push specific tag
-git push origin v1.0.0
-
-# Push all tags
-git push origin --tags
-
-# Delete remote tag (if needed)
-git push origin :refs/tags/v1.0.0
-```
-
-## Integration with Semantic Versioning
-
-### Version-to-Branch Mapping
-
-**Development phase (0.x.y)**:
-- Work on `main`
-- Tag development milestones: `v0.1.0`, `v0.2.0`, etc.
-- Breaking changes allowed
-
-**Stable releases (1.x.y)**:
-- Work on `main` or feature branches
-- Tag stable releases: `v1.0.0`, `v1.1.0`, etc.
-- Breaking changes require major version bump
-
-**Major releases (2.0.0+)**:
-- Work on `main` or feature branches
-- Tag major releases: `v2.0.0`, `v3.0.0`, etc.
-- Document breaking changes thoroughly
-
-### Branch-to-Release Flow
-
-```
-feature/micropub → main → v0.1.0 (development)
-feature/rss      → main → v0.2.0 (development)
-feature/auth     → main → v0.3.0 (development)
-                   main → v1.0.0 (stable)
-fix/bug          → main → v1.0.1 (patch)
-feature/new      → main → v1.1.0 (minor)
-feature/breaking → main → v2.0.0 (major)
-```
-
-## Common Scenarios
-
-### Scenario 1: Developing a New Feature
-
-```bash
-# Create feature branch
-git checkout -b feature/micropub-endpoint main
-
-# Develop
-git commit -am "Add micropub create action"
-git commit -am "Add micropub update action"
-
-# Keep updated with main
-git fetch origin
-git rebase origin/main
-
-# Merge when ready
-git checkout main
-git merge feature/micropub-endpoint
-
-# Push and clean up
-git push origin main
-git branch -d feature/micropub-endpoint
-```
-
-### Scenario 2: Releasing a Development Version
-
-```bash
-# Update version
-echo '__version__ = "0.2.0"' > starpunk/__init__.py
-
-# Update changelog
-# Edit CHANGELOG.md
-
-# Commit
-git commit -am "Bump version to 0.2.0"
-
-# Tag
-git tag -a v0.2.0 -m "Development release 0.2.0"
-
-# Push
-git push origin main v0.2.0
-```
-
-### Scenario 3: First Stable Release
-
-```bash
-# Final preparations on main
-git commit -am "Update documentation for 1.0.0"
-
-# Version bump
-echo '__version__ = "1.0.0"' > starpunk/__init__.py
-# Edit CHANGELOG.md
-
-git commit -am "Bump version to 1.0.0"
-
-# Tag
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-
-# Push
-git push origin main v1.0.0
-```
-
-### Scenario 4: Critical Production Bug
-
-```bash
-# Create hotfix from last release
-git checkout -b hotfix/1.0.1-security-fix v1.0.0
-
-# Fix the bug
-git commit -am "Fix security vulnerability"
-
-# Version bump
-echo '__version__ = "1.0.1"' > starpunk/__init__.py
-# Edit CHANGELOG.md
-git commit -am "Bump version to 1.0.1"
-
-# Tag
-git tag -a v1.0.1 -m "Hotfix 1.0.1: Security vulnerability fix"
-
-# Merge to main
-git checkout main
-git merge hotfix/1.0.1-security-fix
-
-# Push
-git push origin main v1.0.1
-
-# Clean up
-git branch -d hotfix/1.0.1-security-fix
-```
-
-### Scenario 5: Multiple Features in Progress
-
-```bash
-# Developer 1: Feature A
-git checkout -b feature/feature-a main
-# Work on feature A
-
-# Developer 2: Feature B
-git checkout -b feature/feature-b main
-# Work on feature B
-
-# Feature A finishes first
-git checkout main
-git merge feature/feature-a
-git push origin main
-
-# Feature B rebases onto updated main
-git checkout feature/feature-b
-git rebase origin/main
-# Continue work
-
-# Feature B finishes
-git checkout main
-git merge feature/feature-b
-git push origin main
-```
-
-## Best Practices
-
-### Do
-
-1. **Commit often** with clear messages
-2. **Pull before push** to avoid conflicts
-3. **Rebase feature branches** to keep history clean
-4. **Delete merged branches** to reduce clutter
-5. **Tag releases** with annotated tags
-6. **Write descriptive commit messages** (50 char summary, then details)
-7. **Test before merging** to main
-8. **Use pull requests** for team development
-9. **Keep main stable** - always passing tests
-10. **Document breaking changes** in commits and changelog
-
-### Don't
-
-1. **Never force push** to `main`
-2. **Never rewrite history** on `main`
-3. **Don't commit directly** to `main` (team development)
-4. **Don't merge broken code** - tests must pass
-5. **Don't create long-lived branches** - integrate frequently
-6. **Don't use lightweight tags** for releases
-7. **Don't forget to push tags** after creating them
-8. **Don't merge without updating** from origin first
-9. **Don't commit secrets** or sensitive data
-10. **Don't skip version bumps** before tagging
-
-### Commit Message Format
-
-**Format**:
-```
-:  (50 chars or less)
-
-
-
-
-```
-
-**Types**:
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation
-- `style:` Formatting, whitespace
-- `refactor:` Code refactoring
-- `test:` Adding tests
-- `chore:` Maintenance tasks
-
-**Examples**:
-```
-feat: Add Micropub create endpoint
-
-Implements the create action for Micropub specification.
-Supports h-entry posts with content, name, and published properties.
-
-Refs: #15
-
-fix: Correct RSS pubDate timezone handling
-
-Previously used local timezone, now uses UTC as per RSS spec.
-
-Fixes: #23
-
-docs: Update installation instructions
-
-chore: Bump version to 1.0.0
-```
-
-## Troubleshooting
-
-### Problem: Merge Conflict
-
-```bash
-# During merge
-git merge feature/my-feature
-# CONFLICT (content): Merge conflict in file.py
-
-# Resolve conflicts
-# Edit file.py, resolve conflicts
-git add file.py
-git commit -m "Merge feature/my-feature"
-```
-
-### Problem: Accidentally Committed to Main
-
-```bash
-# If not pushed yet
-git reset HEAD~1  # Undo last commit, keep changes
-git stash         # Save changes
-git checkout -b feature/my-feature  # Create feature branch
-git stash pop     # Apply changes
-git commit -am "Feature implementation"
-```
-
-### Problem: Need to Update Feature Branch
-
-```bash
-# Option 1: Rebase (clean history)
-git checkout feature/my-feature
-git rebase origin/main
-
-# Option 2: Merge (preserves history)
-git checkout feature/my-feature
-git merge origin/main
-```
-
-### Problem: Wrong Tag Name
-
-```bash
-# Delete local tag
-git tag -d v1.0.0
-
-# Delete remote tag
-git push origin :refs/tags/v1.0.0
-
-# Create correct tag
-git tag -a v1.0.1 -m "Release 1.0.1"
-git push origin v1.0.1
-```
+Branch `docs/`, no version bump, no changelog entry, no tag.
+Merge with `--no-ff` like any other branch.
 
 ## References
 
-### Internal Documentation
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md) - Version numbering scheme
-- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md) - Versioning decision rationale
-- [ADR-009: Git Branching Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-009-git-branching-strategy.md) - This strategy's decision record
-- [Development Setup](/home/phil/Projects/starpunk/docs/standards/development-setup.md) - Development environment
-
-### External Resources
-- [Git Branching Model](https://nvie.com/posts/a-successful-git-branching-model/) - Git Flow (inspiration, not followed exactly)
-- [GitHub Flow](https://guides.github.com/introduction/flow/) - Simpler flow (closer to our approach)
-- [Semantic Versioning](https://semver.org/) - Version numbering
-- [Git Documentation](https://git-scm.com/doc) - Official Git documentation
-
----
-
-**Document**: Git Branching Strategy
-**Version**: 1.0
-**Last Updated**: 2025-11-18
-**Status**: Active
+- [versioning-strategy.md](versioning-strategy.md): choosing the version number
+- [version-implementation-guide.md](version-implementation-guide.md): where the version lives, changelog and design note format
+- [testing-checklist.md](testing-checklist.md): tests and CI
+- [ADR-009: Git branching strategy](../decisions/ADR-009-git-branching-strategy.md)
diff --git a/docs/standards/python-coding-standards.md b/docs/standards/python-coding-standards.md
index 82f5835..c94a9e2 100644
--- a/docs/standards/python-coding-standards.md
+++ b/docs/standards/python-coding-standards.md
@@ -1,1008 +1,151 @@
 # Python Coding Standards
 
-## Purpose
-
-This document establishes coding standards for all Python code in StarPunk. These standards ensure consistency, readability, and maintainability while adhering to the project philosophy: "Every line of code must justify its existence."
-
-## Philosophy
-
-Code standards should:
-- **Enhance readability** without adding ceremony
-- **Catch errors early** through consistent patterns
-- **Enable automation** via tools (black, flake8, mypy)
-- **Stay minimal** - no rules without clear benefit
-
-## Base Standard
-
-StarPunk follows **PEP 8** with specific clarifications and exceptions documented below.
-
-**Reference**: [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/)
-
----
-
-## Code Formatting
-
-### Automated Formatting with Black
-
-**Decision**: All Python code MUST be formatted with [Black](https://black.readthedocs.io/).
-
-**Configuration**: Use Black's defaults (88 character line length).
-
-**Rationale**:
-- Eliminates formatting debates
-- Consistent across entire codebase
-- Automated via pre-commit hook or CI
-- Industry standard
-
-**Usage**:
-```bash
-# Format all code
-.venv/bin/black starpunk/ tests/
-
-# Check formatting without changes
-.venv/bin/black --check starpunk/ tests/
-
-# Format specific file
-.venv/bin/black starpunk/notes.py
-```
-
-**Configuration File** (optional `pyproject.toml`):
-```toml
-[tool.black]
-line-length = 88
-target-version = ['py311']
-include = '\.pyi?$'
-extend-exclude = '''
-/(
-    \.venv
-  | data
-)/
-'''
-```
-
----
-
-## Code Style
-
-### Line Length
-
-**Standard**: 88 characters (Black default)
-
-**Exception**: Long strings, URLs, or comments can exceed if breaking them reduces readability.
-
-**Good**:
-```python
-# Fits in 88 characters, readable
-def create_note(content: str, published: bool = False) -> Note:
-    """Create a new note with the given content."""
-    ...
-```
-
-**Acceptable Exception**:
-```python
-# URL shouldn't be broken
-INDIELOGIN_ENDPOINT = "https://indielogin.com/auth?me={me}&client_id={client_id}&redirect_uri={redirect_uri}&state={state}"
-```
-
----
-
-### Indentation
-
-**Standard**: 4 spaces per indentation level (PEP 8).
-
-**Never use tabs** - Black enforces this.
-
-**Good**:
-```python
-def example():
-    if condition:
-        do_something()
-        if nested:
-            do_nested()
-```
-
----
-
-### Blank Lines
-
-**Rules**:
-- 2 blank lines between top-level functions and classes
-- 1 blank line between methods in a class
-- Use blank lines sparingly within functions for logical grouping
-
-**Good**:
-```python
-import os
-
-
-def first_function():
-    """First function."""
-    pass
-
-
-def second_function():
-    """Second function."""
-    pass
-
-
-class MyClass:
-    """Example class."""
-
-    def method_one(self):
-        """First method."""
-        pass
-
-    def method_two(self):
-        """Second method."""
-        pass
-```
-
----
-
-### Imports
-
-**Order** (enforced by Black and flake8):
-1. Standard library imports
-2. Third-party imports
-3. Local application imports
-
-**Within each group**: Alphabetically sorted
-
-**Style**: One import per line (except `from` imports)
-
-**Good**:
-```python
-# Standard library
-import os
-import sqlite3
-from datetime import datetime
-from pathlib import Path
-
-# Third-party
-import httpx
-import markdown
-from flask import Flask, render_template, request
-from feedgen.feed import FeedGenerator
-
-# Local
-from starpunk.config import load_config
-from starpunk.database import get_db
-from starpunk.models import Note
-```
-
-**Bad**:
-```python
-import os, sys  # Multiple imports on one line
-from starpunk.config import *  # Star imports
-from flask import Flask
-import httpx  # Wrong order (third-party before local)
-from starpunk.models import Note
-```
-
-**Absolute vs Relative Imports**:
-- Use absolute imports: `from starpunk.database import get_db`
-- Avoid relative imports: `from .database import get_db`
-
----
-
-### Quotes
-
-**Standard**: Use double quotes `"` for strings (Black default).
-
-**Exception**: Use single quotes to avoid escaping doubles inside string.
-
-**Good**:
-```python
-name = "StarPunk"
-description = "A minimal CMS"
-html = 'Link'  # Single quotes to avoid escaping
-```
-
-**Bad**:
-```python
-name = 'StarPunk'  # Black will change to double quotes
-```
-
----
-
-## Naming Conventions
-
-### Files and Modules
-
-**Pattern**: `lowercase_with_underscores.py`
-
-**Good**:
-```
-starpunk/database.py
-starpunk/notes.py
-starpunk/utils.py
-tests/test_auth.py
-```
-
-**Bad**:
-```
-starpunk/Database.py    # CamelCase
-starpunk/db.py          # Abbreviation
-starpunk/note-utils.py  # Hyphens
-```
-
----
-
-### Classes
-
-**Pattern**: `PascalCase` (CapWords)
-
-**Good**:
-```python
-class Note:
-    pass
-
-class SessionManager:
-    pass
-
-class MicropubEndpoint:
-    pass
-```
-
-**Bad**:
-```python
-class note:           # lowercase
-class session_manager: # snake_case
-class Micropub_Endpoint: # Mixed
-```
-
----
-
-### Functions and Methods
-
-**Pattern**: `lowercase_with_underscores`
-
-**Good**:
-```python
-def create_note(content):
-    pass
-
-def get_note_by_slug(slug):
-    pass
-
-def generate_rss_feed():
-    pass
-```
-
-**Bad**:
-```python
-def createNote():      # camelCase
-def GetNoteBySlug():   # PascalCase
-def generate_RSS_feed(): # Mixed case
-```
-
----
-
-### Variables
-
-**Pattern**: `lowercase_with_underscores`
-
-**Good**:
-```python
-note_count = 10
-file_path = Path("data/notes")
-session_token = generate_token()
-```
-
-**Bad**:
-```python
-noteCount = 10      # camelCase
-FilePath = Path()   # PascalCase
-session_Token = ""  # Mixed
-```
-
----
-
-### Constants
-
-**Pattern**: `UPPERCASE_WITH_UNDERSCORES`
-
-**Location**: Define at module level (top of file after imports)
-
-**Good**:
-```python
-MAX_NOTE_LENGTH = 10000
-DEFAULT_SESSION_LIFETIME = 30
-INDIELOGIN_URL = "https://indielogin.com"
-```
-
-**Bad**:
-```python
-max_note_length = 10000    # lowercase
-MaxNoteLength = 10000      # PascalCase
-```
-
----
-
-### Private Members
-
-**Pattern**: Single leading underscore `_name` for internal use
-
-**Good**:
-```python
-class Note:
-    def __init__(self, content):
-        self._content_hash = None  # Internal attribute
-
-    def _calculate_hash(self):  # Internal method
-        """Calculate content hash (internal use)."""
-        pass
-
-    def save(self):
-        """Public method."""
-        self._calculate_hash()  # Can call private method
-```
-
-**Never use double underscore** `__name` (name mangling) unless you specifically need it (rare).
-
----
-
-## Type Hints
-
-### Standard
-
-**Use type hints** for all function signatures in application code.
-
-**Good**:
-```python
-from pathlib import Path
-from typing import Optional, List
-
-def create_note(content: str, published: bool = False) -> Note:
-    """Create a new note."""
-    pass
-
-def get_notes(limit: int = 10, offset: int = 0) -> List[Note]:
-    """Get list of notes."""
-    pass
-
-def find_note(slug: str) -> Optional[Note]:
-    """Find note by slug, returns None if not found."""
-    pass
-```
-
-**Type Hint Guidelines**:
-- Use built-in types when possible: `str`, `int`, `bool`, `list`, `dict`
-- Use `typing` module for complex types: `Optional`, `List`, `Dict`, `Tuple`
-- Python 3.11+ can use `list[Note]` instead of `List[Note]`
-- Use `Optional[T]` for nullable types
-- Use `->` for return type annotation
-
-**Optional for Tests**: Type hints in tests are optional but encouraged.
-
----
-
-## Documentation
-
-### Docstrings
-
-**Standard**: Use docstrings for all modules, classes, and functions.
-
-**Format**: Google-style docstrings
-
-**Module Docstring**:
-```python
-"""
-Notes management module for StarPunk
-
-This module handles creating, reading, updating, and deleting notes.
-Notes are stored as markdown files with metadata in SQLite.
-"""
-```
-
-**Function Docstring**:
-```python
-def create_note(content: str, slug: Optional[str] = None, published: bool = False) -> Note:
-    """
-    Create a new note with the given content
-
-    Args:
-        content: Markdown content of the note
-        slug: Optional URL slug (generated if not provided)
-        published: Whether note is published (default: False)
-
-    Returns:
-        Created Note instance
-
-    Raises:
-        ValueError: If content is empty
-        FileExistsError: If slug already exists
-
-    Example:
-        >>> note = create_note("Hello world", slug="first-note")
-        >>> note.slug
-        'first-note'
-    """
-    pass
-```
-
-**Class Docstring**:
-```python
-class Note:
-    """
-    Represents a note with content and metadata
-
-    Attributes:
-        slug: URL-safe identifier
-        content: Markdown content
-        file_path: Path to markdown file
-        created_at: Creation timestamp
-        updated_at: Last modification timestamp
-        published: Publication status
-    """
-
-    def __init__(self, slug: str, content: str):
-        """
-        Initialize a new Note
-
-        Args:
-            slug: URL-safe identifier
-            content: Markdown content
-        """
-        self.slug = slug
-        self.content = content
-```
-
-**Property Docstring**:
-```python
-@property
-def html(self) -> str:
-    """Rendered HTML content from markdown."""
-    return markdown.markdown(self.content)
-```
-
-**Short Functions**: One-line docstring is acceptable.
-
-```python
-def get_all_notes() -> List[Note]:
-    """Get all notes from database."""
-    pass
-```
-
----
-
-### Comments
-
-**Use sparingly** - code should be self-documenting via good naming.
-
-**When to Comment**:
-- Explain **why**, not **what**
-- Document non-obvious business logic
-- Clarify complex algorithms
-- Note important gotchas or limitations
-
-**Good Comment**:
-```python
-# IndieLogin requires state token to prevent CSRF attacks
-state = generate_state_token()
-
-# File operations must be atomic to prevent corruption
-temp_path = file_path.with_suffix('.tmp')
-temp_path.write_text(content)
-temp_path.replace(file_path)  # Atomic rename
-```
-
-**Bad Comment** (obvious from code):
-```python
-# Increment counter
-counter += 1
-
-# Create a note
-note = Note(content)
-```
-
-**TODO Comments**: Acceptable for V1, should include context.
-
-```python
-# TODO: Add pagination when note count > 100
-# TODO(username): Consider caching RSS feed (V2 feature)
-```
-
----
-
-## Error Handling
-
-### Exceptions
-
-**Prefer specific exceptions** over generic `Exception`.
-
-**Good**:
-```python
-def get_note(slug: str) -> Note:
-    """Get note by slug."""
-    if not slug:
-        raise ValueError("Slug cannot be empty")
-
-    note = db.query(slug)
-    if not note:
-        raise FileNotFoundError(f"Note not found: {slug}")
-
-    return note
-```
-
-**Bad**:
-```python
-def get_note(slug: str) -> Note:
-    if not slug:
-        raise Exception("Bad slug")  # Too generic
-
-    # Silently return None instead of raising exception
-    note = db.query(slug)
-    return note  # Could be None
-```
-
-### Error Messages
-
-**Be specific and actionable**:
-
-**Good**:
-```python
-raise ValueError(
-    f"Invalid slug '{slug}': must contain only lowercase letters, "
-    f"numbers, and hyphens"
-)
-
-raise FileNotFoundError(
-    f"Note file not found: {file_path}. "
-    f"Database may be out of sync with filesystem."
-)
-```
-
-**Bad**:
-```python
-raise ValueError("Invalid input")
-raise FileNotFoundError("File missing")
-```
-
-### Exception Handling
-
-**Catch specific exceptions**, not bare `except:`.
-
-**Good**:
-```python
-try:
-    note = create_note(content)
-except ValueError as e:
-    logger.error(f"Invalid note content: {e}")
-    return {"error": str(e)}, 400
-except FileExistsError as e:
-    logger.error(f"Duplicate slug: {e}")
-    return {"error": "Note already exists"}, 409
-```
-
-**Bad**:
-```python
-try:
-    note = create_note(content)
-except:  # Too broad, catches everything including KeyboardInterrupt
-    return {"error": "Something went wrong"}, 500
-```
-
----
-
-## Flask-Specific Patterns
-
-### Route Decorators
-
-**Pattern**: One route per function, clear HTTP methods.
-
-**Good**:
-```python
-@app.route('/api/notes', methods=['GET'])
-def list_notes():
-    """List all published notes."""
-    notes = get_published_notes()
-    return jsonify([note.to_dict() for note in notes])
-
-@app.route('/api/notes', methods=['POST'])
-def create_note_endpoint():
-    """Create a new note."""
-    data = request.get_json()
-    note = create_note(data['content'])
-    return jsonify(note.to_dict()), 201
-```
-
-**Bad**:
-```python
-@app.route('/api/notes', methods=['GET', 'POST'])  # Multiple methods in one function
-def notes():
-    if request.method == 'GET':
-        ...
-    elif request.method == 'POST':
-        ...
-```
-
-### Request Handling
-
-**Validate input explicitly**:
-
-**Good**:
-```python
-@app.route('/api/notes', methods=['POST'])
-def create_note_endpoint():
-    """Create a new note."""
-    data = request.get_json()
-
-    # Validate required fields
-    if not data or 'content' not in data:
-        return {"error": "Missing required field: content"}, 400
-
-    content = data['content'].strip()
-    if not content:
-        return {"error": "Content cannot be empty"}, 400
-
-    # Create note
-    try:
-        note = create_note(content)
-        return jsonify(note.to_dict()), 201
-    except ValueError as e:
-        return {"error": str(e)}, 400
-```
-
----
-
-## Testing Standards
-
-### Test Naming
-
-**Pattern**: `test_{function_name}_{scenario}`
-
-**Good**:
-```python
-def test_create_note_success():
-    """Test creating a note with valid content."""
-    pass
-
-def test_create_note_empty_content():
-    """Test creating a note with empty content raises ValueError."""
-    pass
-
-def test_get_note_by_slug_not_found():
-    """Test getting non-existent note raises FileNotFoundError."""
-    pass
-```
-
-### Test Structure
-
-**Use Arrange-Act-Assert pattern**:
-
-```python
-def test_create_note_success():
-    """Test creating a note with valid content."""
-    # Arrange
-    content = "This is a test note"
-    slug = "test-note"
-
-    # Act
-    note = create_note(content, slug=slug)
-
-    # Assert
-    assert note.slug == slug
-    assert note.content == content
-    assert note.published is False
-```
-
-### Fixtures
-
-**Use pytest fixtures** for common setup:
-
-```python
-@pytest.fixture
-def sample_note():
-    """Create a sample note for testing."""
-    return create_note("Sample content", slug="sample")
-
-def test_note_to_dict(sample_note):
-    """Test converting note to dictionary."""
-    data = sample_note.to_dict()
-    assert data['slug'] == 'sample'
-    assert 'content' in data
-```
-
----
-
-## File Organization
-
-### Module Structure
-
-**Standard order within a Python file**:
-
-1. Module docstring
-2. Imports (standard → third-party → local)
-3. Constants
-4. Exception classes (if any)
-5. Classes
-6. Functions
-7. Main execution block (if applicable)
-
-**Example**:
-```python
-"""
-Notes management module
-
-This module handles note CRUD operations.
-"""
-
-# Standard library
-import os
-from datetime import datetime
-from pathlib import Path
-
-# Third-party
-import markdown
-from flask import current_app
-
-# Local
-from starpunk.database import get_db
-from starpunk.utils import generate_slug
-
-# Constants
-MAX_NOTE_LENGTH = 10000
-DEFAULT_PUBLISHED_STATUS = False
-
-
-# Exception classes
-class NoteError(Exception):
-    """Base exception for note operations."""
-    pass
-
-
-class DuplicateSlugError(NoteError):
-    """Raised when note slug already exists."""
-    pass
-
-
-# Classes
-class Note:
-    """Represents a note."""
-    pass
-
-
-# Functions
-def create_note(content: str) -> Note:
-    """Create a new note."""
-    pass
-
-
-def get_note(slug: str) -> Note:
-    """Get note by slug."""
-    pass
-```
-
----
-
-## Anti-Patterns to Avoid
-
-### Don't Repeat Yourself (DRY)
-
-**Bad**:
-```python
-def get_note_as_html(slug):
-    note = db.query(slug)
-    html = markdown.markdown(note.content)
-    return html
-
-def get_note_for_rss(slug):
-    note = db.query(slug)
-    html = markdown.markdown(note.content)
-    return html
-```
-
-**Good**:
-```python
-def get_note(slug: str) -> Note:
-    """Get note by slug."""
-    return db.query(slug)
-
-def render_markdown(content: str) -> str:
-    """Render markdown to HTML."""
-    return markdown.markdown(content)
-
-# Use in different contexts
-def get_note_as_html(slug: str) -> str:
-    note = get_note(slug)
-    return render_markdown(note.content)
-```
-
-### Avoid Magic Numbers
-
-**Bad**:
-```python
-if len(content) > 10000:
-    raise ValueError("Content too long")
-
-time.sleep(86400)  # What is 86400?
-```
-
-**Good**:
-```python
-MAX_NOTE_LENGTH = 10000
-SECONDS_PER_DAY = 86400
-
-if len(content) > MAX_NOTE_LENGTH:
-    raise ValueError(f"Content exceeds {MAX_NOTE_LENGTH} characters")
-
-time.sleep(SECONDS_PER_DAY)
-```
-
-### Avoid Mutable Default Arguments
-
-**Bad**:
-```python
-def create_note(content: str, tags: list = []):  # Mutable default
-    tags.append('note')  # Modifies shared default list
-    return Note(content, tags)
-```
-
-**Good**:
-```python
-def create_note(content: str, tags: Optional[List[str]] = None) -> Note:
-    if tags is None:
-        tags = []
-    tags.append('note')
-    return Note(content, tags)
-```
-
-### Avoid God Objects
-
-**Bad**:
-```python
-class StarPunk:
-    """Does everything."""
-    def create_note(self): pass
-    def render_html(self): pass
-    def generate_rss(self): pass
-    def authenticate(self): pass
-    def send_email(self): pass
-    # 50 more methods...
-```
-
-**Good**:
-```python
-# Separate concerns into focused modules
-class Note:
-    """Represents a note."""
-    pass
-
-class NoteManager:
-    """Manages note CRUD operations."""
-    pass
-
-class FeedGenerator:
-    """Generates RSS feeds."""
-    pass
-```
-
----
-
-## Code Quality Tools
-
-### Black (Formatter)
-
-**Required**: All code MUST be formatted with Black before commit.
-
-```bash
-# Format code
-.venv/bin/black starpunk/ tests/
-
-# Check formatting
-.venv/bin/black --check starpunk/ tests/
-```
-
-### Flake8 (Linter)
-
-**Required**: All code MUST pass flake8 checks.
-
-```bash
-# Lint code
-.venv/bin/flake8 starpunk/ tests/
-
-# Configuration in setup.cfg or pyproject.toml
-```
-
-**Configuration** (`setup.cfg`):
-```ini
-[flake8]
-max-line-length = 88
-extend-ignore = E203, W503
-exclude =
-    .venv,
-    __pycache__,
-    data,
-    .git
-```
-
-### Mypy (Type Checker)
-
-**Recommended**: Run mypy for type checking (optional for V1).
-
-```bash
-# Type check
-.venv/bin/mypy starpunk/
-```
-
-**Configuration** (`pyproject.toml`):
-```toml
-[tool.mypy]
-python_version = "3.11"
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = false  # Set to true for strict mode
-```
-
-### Pytest (Testing)
-
-**Required**: All code MUST have tests with >80% coverage.
-
-```bash
-# Run tests
-.venv/bin/pytest
-
-# With coverage
-.venv/bin/pytest --cov=starpunk --cov-report=html tests/
-```
-
----
-
-## Pre-Commit Checklist
-
-Before committing code, verify:
-
-```bash
-# 1. Format code
-.venv/bin/black starpunk/ tests/
-
-# 2. Lint code
-.venv/bin/flake8 starpunk/ tests/
-
-# 3. Run tests
-.venv/bin/pytest
-
-# 4. Check coverage
-.venv/bin/pytest --cov=starpunk tests/
-
-# 5. Type check (optional)
-.venv/bin/mypy starpunk/
-```
-
-**All checks must pass** before code is committed.
-
----
-
-## Summary
-
-**Key Principles**:
-1. Use Black for formatting (88 char lines)
-2. Follow PEP 8 naming conventions
-3. Add type hints to all function signatures
-4. Write docstrings for all public APIs
-5. Handle errors with specific exceptions
-6. Keep functions focused and small
-7. Test everything (>80% coverage)
-8. Make code self-documenting
-
-**Tools**:
-- Black (required) - formatting
-- Flake8 (required) - linting
-- Pytest (required) - testing
-- Mypy (recommended) - type checking
-
-**Remember**: "Every line of code must justify its existence."
-
----
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
+
+How Python code in StarPunk is written. The project rule comes first:
+"Every line of code must justify its existence. When in doubt, leave it
+out." Patterns specific to small helper functions are in
+[utility-function-patterns.md](utility-function-patterns.md).
+
+## Base style
+
+- [PEP 8](https://peps.python.org/pep-0008/) naming and layout, Python 3.11.
+- **Match the file you are editing.** 4-space indents everywhere; quote
+  style varies between modules (newer code uses double quotes); keep lines
+  to roughly 100 characters.
+- Keep diffs about the change. Don't reformat or re-order code you aren't
+  otherwise touching.
+
+### Formatters and linters
+
+`black`, `flake8` and `mypy` are in `requirements-dev.txt`, but they are
+**not enforced**: there is no configuration file, no pre-commit hook, and CI
+runs only pytest. The existing code is not Black-formatted (running
+`black` over `starpunk/` would rewrite most files). So:
+
+- Don't run `black` on whole files or directories.
+- Use `uv run flake8 --select=F ` to catch unused imports, undefined
+  names and similar real errors in files you changed.
+- Type hints are checked by review, not by mypy.
+
+## Naming
+
+| Kind | Style | Examples |
+|---|---|---|
+| Modules | `snake_case.py`, named for what they do | `webmention_ssrf.py`, `websub_worker.py` |
+| Functions, variables | `snake_case`, verbs for functions | `create_note`, `validate_url_for_fetch` |
+| Classes | `PascalCase` | `WebSubWorker`, `ConnectionPool` |
+| Constants | `UPPER_SNAKE_CASE`, module level | `MAX_SLUG_LENGTH`, `RESERVED_SLUGS` |
+| Private | leading underscore | `_consume_login_state`, `_Watchdog` |
+| Exceptions | `...Error`, one base per module | `NoteError` → `NoteNotFoundError` |
+
+## Type hints and docstrings
+
+- New and changed public functions get type hints on parameters and return
+  values. Use built-in generics (`list[str]`, `dict[str, int]`) and
+  `X | None` in new code; `Optional[...]` is also present in older modules.
+- Every module starts with a docstring saying what it is for. Mention the
+  ADR or spec it implements and, for later changes, the release
+  (`v2.10.1: every queue item is handled on its own, ...`).
+- Public functions get a docstring: one summary line, then `Args:`,
+  `Returns:` and `Raises:` sections where they add information.
+- Comments explain **why** (a spec requirement, an incident, a security
+  reason), not what the next line does.
+
+## Project patterns
+
+### Configuration
+
+Read settings from `current_app.config` (or `app.config` during startup),
+never `os.getenv` outside `starpunk/config.py`. A new setting is:
+
+1. read in `load_config()` with its default and type conversion
+   (`int(...)`, `== "true"`);
+2. validated in `validate_config()` if a wrong value would break startup;
+3. documented in `.env.example` with its default.
+
+### Database
+
+- Get connections with `get_db()` from `starpunk.database` (connection
+  pool). Use parameterised queries (`?` placeholders) only, never string
+  formatting.
+- Schema changes are new numbered files in `migrations/`; never edit an
+  applied migration. See
+  [git-branching-strategy.md](git-branching-strategy.md#migrations).
+
+### Outbound HTTP
+
+New code that requests a URL which came from outside (webmention sources
+and targets, WebSub callbacks, Micropub photo URLs) uses
+`starpunk/webmention_ssrf.py` (`safe_get`, `safe_post`): it refuses private
+addresses, pins the resolved address, caps the response size and enforces a
+hard deadline. Send its `user_agent()` string. Plain `httpx` is for fixed,
+configured endpoints (OIDC provider, crossposting APIs, `ADMIN_ME`).
+
+Older code has its own checks instead: IndieAuth client metadata
+(`indieauth.py`, `validate_url_for_fetch` then `httpx.get`) and link-card
+fetching for crossposts (`syndication._fetch_public`). Moving them onto
+`safe_get` is welcome when touching that code.
+
+### Errors
+
+- Raise specific exceptions from the module's own hierarchy
+  (`MicropubValidationError`, `SyndicationError`, `MigrationError`).
+- Catch the narrowest exception you can handle. Broad `except Exception`
+  belongs only at boundaries that must keep running (worker loops, one
+  queue item at a time) and must log the error.
+- Protocol endpoints return the error format their spec requires (e.g.
+  Micropub `{"error": ..., "error_description": ...}` with the right status).
+  See [ADR-055](../decisions/ADR-055-error-handling-philosophy.md).
+
+### Routes
+
+- Routes live in blueprints in `starpunk/routes/`, one module per area
+  (`public`, `admin`, `auth`, `indieauth`, `micropub`, `webmention`,
+  `websub`, `search`, `dev_auth`).
+- Prefer one view per HTTP method; a single view for `GET` and `POST` is
+  fine where a spec defines one endpoint for both (`/micropub`).
+- Admin views use `@require_auth` from `starpunk.auth`. State-changing
+  admin actions are `POST` only.
+- Keep views thin: parsing and response in the route, logic in a module
+  (`notes.py`, `micropub.py`, `websub.py`).
+
+### Background work
+
+Long-running work runs in worker threads started by `create_app()`
+(webmention, WebSub, syndication). Workers:
+
+- skip starting when `app.config["TESTING"]` is true;
+- must cope with every gunicorn process running its own copy: claim work
+  in the database so an item is processed once;
+- handle each queue item on its own, so one bad item can't stop the loop;
+- run inside `app.app_context()`.
+
+### Logging
+
+Use `current_app.logger` (structured logging with request correlation IDs,
+[ADR-054](../decisions/ADR-054-structured-logging-architecture.md)). Never
+log secrets, tokens or full request bodies.
+
+## Tests
+
+See [testing-checklist.md](testing-checklist.md). In short: pytest
+functions or `Test...` classes with descriptive names
+(`test_unsubscribe_ignores_lease_seconds`), fixtures from
+`tests/conftest.py`, no real network access.
+
+## Anti-patterns
+
+- Abstractions with one caller, configuration nobody sets, code for
+  features not yet planned
+- Mutable default arguments
+- Magic numbers: name them as module constants
+- Silent failures: an error is raised, returned or logged, never swallowed
+- Reformatting unrelated code in a feature change
 
 ## References
 
-- [PEP 8 - Style Guide](https://peps.python.org/pep-0008/)
-- [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)
-- [PEP 484 - Type Hints](https://peps.python.org/pep-0484/)
-- [Black Documentation](https://black.readthedocs.io/)
-- [Flake8 Documentation](https://flake8.pycqa.org/)
-- [Mypy Documentation](https://mypy.readthedocs.io/)
-- [Pytest Documentation](https://docs.pytest.org/)
-- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
+- [PEP 8](https://peps.python.org/pep-0008/), [PEP 257](https://peps.python.org/pep-0257/), [PEP 484](https://peps.python.org/pep-0484/)
+- [utility-function-patterns.md](utility-function-patterns.md)
+- [ADR-055: Error handling philosophy](../decisions/ADR-055-error-handling-philosophy.md)
diff --git a/docs/standards/testing-checklist.md b/docs/standards/testing-checklist.md
index cfe9100..3ad514d 100644
--- a/docs/standards/testing-checklist.md
+++ b/docs/standards/testing-checklist.md
@@ -1,127 +1,116 @@
 # Testing Checklist
 
-This document provides a comprehensive checklist for testing StarPunk functionality before release.
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-## Manual Testing Checklist
+What to test, how to run the tests, and what CI does with them. Setup and
+the environment variables the tests need are in
+[development-setup.md](development-setup.md#running-the-tests).
 
-### Core Functionality
-- [ ] Create notes via web interface
-- [ ] Create notes via Micropub JSON
-- [ ] Create notes via Micropub form-encoded
-- [ ] Notes display with proper microformats
-- [ ] Markdown renders correctly
-- [ ] Slugs generate uniquely
-- [ ] Timestamps record accurately
+## How tests run
 
-### Authentication & Security
-- [ ] IndieAuth login flow works
-- [ ] Micropub client authentication
-- [ ] Token expiration works
-- [ ] Rate limiting functions
+**Locally**
 
-### Syndication & Standards
-- [ ] RSS feed validates (W3C validator)
-- [ ] API returns correct status codes
+```bash
+SESSION_SECRET=test uv run pytest                                            # everything
+SESSION_SECRET=test uv run pytest --ignore=tests/test_migration_race_condition.py  # fast loop
+```
 
-### Automated Testing
-- [ ] All unit tests pass
-- [ ] All integration tests pass
-- [ ] Test coverage >80%
+`tests/test_migration_race_condition.py` takes about 5 minutes; skip it
+while iterating, never before a release.
 
-## Validation Tools
+**In CI** (`.gitea/workflows/build-container.yml`), on every pushed
+`vX.Y.Z` tag (or a manual run):
 
-### IndieWeb Standards
-- **IndieWebify.me**: https://indiewebify.me/
-  - Verify microformats (h-entry, h-card, h-feed)
-  - Check IndieAuth implementation
+1. `docker buildx build --target test -f Containerfile .` builds the
+   Containerfile's `test` stage: the runtime dependencies plus pytest and
+   pytest-mock, with `SESSION_SECRET=ci-test-secret`,
+   `SITE_URL=http://localhost:5000` and `ADMIN_ME=https://test.example.com`,
+   then `python -m pytest -q -p no:cacheprovider tests`.
+2. Only if that succeeds is the runtime image built and pushed as
+   `:vX.Y.Z` and `:latest`.
 
-- **IndieAuth Validator**: https://indieauth.com/validate
-  - Test IndieAuth flow
-  - Validate token handling
+So a failing test blocks the release image; it does not block the merge or
+the tag. Run the full suite before merging (see
+[git-branching-strategy.md](git-branching-strategy.md#release-process)).
+To reproduce CI locally: `docker build --target test -f Containerfile .`
+(pytest-cov is not installed in that stage, so don't depend on it in
+tests).
 
-- **Micropub Test Suite**: https://micropub.rocks/
-  - Comprehensive Micropub endpoint testing
-  - Verify spec compliance
+## Every change
 
-### Web Standards
-- **W3C Feed Validator**: https://validator.w3.org/feed/
-  - Validate RSS 2.0 feed structure
-  - Check date formatting
-  - Verify CDATA wrapping
+- [ ] Full suite passes locally
+- [ ] New behaviour has tests; a bug fix has a test that failed before the fix
+- [ ] Tests use the `app` / `client` fixtures from `tests/conftest.py`
+      (temporary data directory, `TESTING=True`); nothing touches `./data`
+- [ ] No test makes real network requests (see below)
+- [ ] Schema changes: a numbered migration in `migrations/`, plus a test
+      that it applies to an existing database (`tests/test_migrations.py`)
 
-- **W3C HTML Validator**: https://validator.w3.org/
-  - Validate HTML5 markup
-  - Check semantic structure
-  - Verify accessibility
+## Conventions
 
-- **JSON Validator**: https://jsonlint.com/
-  - Validate API responses
-  - Check Micropub payloads
+- **Where**: one file per module or feature (`tests/test_websub.py`). Work
+  driven by a spec review or an incident gets its own file named for the
+  release, with a docstring saying what it covers, e.g.
+  `test_micropub_v290.py`, `test_microformats_v280.py`,
+  `test_websub_hardening.py` ("one test per finding of the v2.10.0 review").
+- **Outbound HTTP**: everything StarPunk fetches from or sends to other
+  servers goes through `starpunk/webmention_ssrf.py`. Tests replace its
+  transport and DNS instead of mocking callers:
 
-## Testing Resources
+  ```python
+  monkeypatch.setattr("starpunk.webmention_ssrf.socket.getaddrinfo", lambda *a, **k: PUBLIC)
+  monkeypatch.setattr("starpunk.webmention_ssrf.TRANSPORT", httpx.MockTransport(handler))
+  ```
 
-### Specifications
-- IndieWeb Notes: https://indieweb.org/note
-- Micropub Spec: https://micropub.spec.indieweb.org
-- IndieAuth Spec: https://www.w3.org/TR/indieauth/
-- Microformats2: http://microformats.org/wiki/h-entry
-- RSS 2.0 Spec: https://www.rssboard.org/rss-specification
+  (see the `web` fixture in `tests/test_websub.py`). Test the private
+  address rejection by making `getaddrinfo` return e.g. `10.0.0.2`.
+- **Background workers** don't run under `TESTING=True`. Drive them
+  directly, e.g. `WebSubWorker(app)` inside `app.app_context()`
+  (`run_worker` in `tests/test_websub.py`).
+- **Crossposting** targets are configured per test with app config
+  overrides and mocked HTTP; never with real credentials.
+- **Concurrency** fixes need a test that reproduces the race with real
+  processes or threads (`tests/test_migration_concurrency.py`).
 
-### Testing & Validation
-- Micropub Test Suite: https://micropub.rocks/
-- IndieAuth Testing: https://indieauth.com/
-- Microformats Parser: https://pin13.net/mf2/
+## New or changed protocol work
 
-### Example Implementations
-- IndieWeb Examples: https://indieweb.org/examples
-- Micropub Clients: https://indieweb.org/Micropub/Clients
+StarPunk implements Micropub, IndieAuth, Webmention, WebSub and
+microformats2. For changes to any of them:
 
-## Pre-Release Validation Workflow
+- [ ] Read the W3C Recommendation (or the living spec) and cite section
+      numbers in the ADR and in test names or docstrings
+- [ ] Test each MUST that the change touches, including the error responses
+      (status codes, `error` values, headers) and not only the happy path
+- [ ] Test discovery: `Link` headers and `` elements still advertise
+      the endpoint on every page and feed that should have them
+- [ ] Test what a strict client sends: form-encoded and JSON (Micropub),
+      case and percent-encoding variants (WebSub topics), relative URLs
+      (Webmention sources)
+- [ ] Test that requests to user-supplied URLs are refused for private
+      addresses and time out
+- [ ] Rendered markup: parse the page with `mf2py` and assert on the parsed
+      properties (`tests/test_microformats*.py`), not on raw HTML strings
+- [ ] Manual check against the live site after deploy with the external
+      validators below
 
-1. **Run Automated Tests**
-   ```bash
-   uv run pytest
-   ```
+## Validation tools (manual, after deploy)
 
-2. **Validate HTML**
-   - Test homepage output
-   - Test note permalink output
-   - Run through W3C HTML Validator
+| Protocol | Tool |
+|---|---|
+| Micropub | [micropub.rocks](https://micropub.rocks/), a real client (Quill, Indigenous) |
+| IndieAuth | Sign in to a Micropub client; [indieauth.rocks](https://indieauth.rocks/) |
+| Webmention | [webmention.rocks](https://webmention.rocks/) |
+| WebSub | [websub.rocks](https://websub.rocks/) (publisher and hub tests) |
+| Microformats2 | [pin13.net/mf2](https://pin13.net/mf2/), [IndieWebify.me](https://indiewebify.me/) |
+| Feeds | [W3C Feed Validator](https://validator.w3.org/feed/) (RSS, Atom), [JSON Feed validator](https://validator.jsonfeed.org/) |
+| HTML | [W3C HTML validator](https://validator.w3.org/) |
 
-3. **Validate RSS Feed**
-   - Access /feed.xml
-   - Run through W3C Feed Validator
-   - Verify in actual RSS reader
+## Specifications
 
-4. **Validate Microformats**
-   - Test homepage with IndieWebify.me
-   - Test note permalinks
-   - Use microformats parser
-
-5. **Validate Micropub**
-   - Run micropub.rocks test suite
-   - Test with real Micropub client (Quill)
-
-6. **Manual Browser Testing**
-   - Chrome/Chromium
-   - Firefox
-   - Safari (if available)
-   - Mobile browsers
-
-7. **Security Verification**
-   - CSRF protection working
-   - XSS prevention verified
-   - SQL injection tests pass
-   - Path traversal prevention works
-
-## Success Criteria
-
-All checklist items must pass before V1 release. If any validation tool reports errors, they must be fixed before proceeding.
-
-## Related Documentation
-
-- [Testing Strategy](/home/phil/Projects/starpunk/docs/architecture/overview.md#testing-strategy)
-- [Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
-- [Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md)
-
-**Last Updated**: 2025-11-24
+- Micropub: https://www.w3.org/TR/micropub/
+- IndieAuth: https://indieauth.spec.indieweb.org/
+- Webmention: https://www.w3.org/TR/webmention/
+- WebSub: https://www.w3.org/TR/websub/
+- Microformats2 h-entry: https://microformats.org/wiki/h-entry
+- RSS 2.0: https://www.rssboard.org/rss-specification, Atom: RFC 4287, JSON Feed 1.1: https://www.jsonfeed.org/version/1.1/
diff --git a/docs/standards/utility-function-patterns.md b/docs/standards/utility-function-patterns.md
index 8f52151..72a119a 100644
--- a/docs/standards/utility-function-patterns.md
+++ b/docs/standards/utility-function-patterns.md
@@ -1,8 +1,13 @@
 # Utility Function Patterns
 
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1; reviewed, content from 2025-11-18)
+
 ## Purpose
 
-This document establishes coding patterns and conventions specifically for utility functions in StarPunk. These patterns ensure utilities are consistent, testable, and maintainable.
+This document establishes coding patterns and conventions specifically for utility functions in StarPunk (`starpunk/utils.py`, `starpunk/slug_utils.py`, `starpunk/mf2_utils.py` and helpers in other modules). These patterns ensure utilities are consistent, testable, and maintainable. General rules, including project-wide patterns for configuration, database access and outbound HTTP, are in [python-coding-standards.md](python-coding-standards.md); where the two differ, that document wins.
+
+The examples are illustrative. Several mirror real functions in `starpunk/utils.py` (`calculate_content_hash`, `write_note_file`, `validate_slug`, `generate_slug`, `validate_note_path`); others (`require_valid_slug`, `iter_note_files`) only show the pattern.
 
 ## Philosophy
 
@@ -481,7 +486,7 @@ def generate_slug(content: str) -> str:
     # Additional validation
     if not validate_slug(normalized):
         # Fallback to safe default
-        normalized = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+        normalized = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
 
     return normalized
 ```
@@ -500,7 +505,7 @@ def generate_slug(content: str, created_at: Optional[datetime] = None) -> str:
 
     # Only generate timestamp if needed
     if not slug:
-        created_at = created_at or datetime.utcnow()
+        created_at = created_at or datetime.now(timezone.utc)
         slug = created_at.strftime("%Y%m%d-%H%M%S")
 
     return slug
@@ -705,7 +710,7 @@ def generate_slug(content: str) -> str:
     slug = normalize_slug_text(content)
     if not slug:
         # Explicit fallback with timestamp
-        slug = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+        slug = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
 
     return slug
 ```
@@ -726,7 +731,7 @@ def generate_slug(content: str) -> str:
 
 ## References
 
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
+- [Python Coding Standards](python-coding-standards.md)
 - [PEP 8 - Style Guide](https://peps.python.org/pep-0008/)
 - [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)
 - [PEP 484 - Type Hints](https://peps.python.org/pep-0484/)
diff --git a/docs/standards/version-implementation-guide.md b/docs/standards/version-implementation-guide.md
index b83382d..d266d41 100644
--- a/docs/standards/version-implementation-guide.md
+++ b/docs/standards/version-implementation-guide.md
@@ -1,603 +1,95 @@
 # Version Implementation Guide
 
-## Quick Reference
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-This guide shows exactly where and how version information is stored in StarPunk.
+Where the version number lives and what to write for each release. Which
+number to pick: [versioning-strategy.md](versioning-strategy.md). Git steps:
+[git-branching-strategy.md](git-branching-strategy.md#release-process).
 
-**See Also**: [versioning-strategy.md](versioning-strategy.md) for complete strategy documentation.
+## Where the version lives
 
-## Version Storage Locations
+There is one source: `starpunk/__init__.py`, at the end of the file.
 
-### 1. Primary Source: `starpunk/__init__.py`
-
-**Status**: ✅ Already implemented
-
-**Location**: `/home/phil/Projects/starpunk/starpunk/__init__.py`
-
-**Content**:
 ```python
 # Package version (Semantic Versioning 2.0.0)
 # See docs/standards/versioning-strategy.md for details
-__version__ = "0.1.0"
-__version_info__ = (0, 1, 0)
+__version__ = "2.10.1"
+__version_info__ = (2, 10, 1)
 ```
 
-**Usage**:
-```python
-from starpunk import __version__, __version_info__
+Update both lines. Nothing else holds the number: there is no
+`pyproject.toml`, and the README doesn't state a version. At runtime:
 
-print(f"StarPunk version {__version__}")
-print(f"Version info: {__version_info__}")  # (0, 1, 0)
+- `starpunk/config.py` sets `app.config["VERSION"]` from the `VERSION`
+  environment variable, defaulting to `__version__`. Leave `VERSION` unset
+  in deployments so the code's version is shown.
+- The version appears in the page footer, `/health`, `/admin/health`
+  and the `User-Agent` of outgoing requests (`StarPunk/`).
+
+The git tag (`vX.Y.Z`) and the image tag CI publishes come from the tag you
+push, so they must match `__version__`. Check before tagging:
+
+```bash
+uv run python -c "import starpunk; print(starpunk.__version__)"
 ```
 
-**Format**:
-- `__version__`: String in PEP 440 format (e.g., `"1.0.0"`, `"1.0.0a1"`, `"1.0.0rc1"`)
-- `__version_info__`: Tuple of integers (major, minor, patch) for programmatic comparison
+## CHANGELOG.md
 
----
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. Add the
+new entry under `## [Unreleased]`, newest first:
 
-### 2. README.md
-
-**Status**: ✅ Already implemented
-
-**Location**: `/home/phil/Projects/starpunk/README.md`
-
-**Content**: Shows current version at the top of the file:
 ```markdown
-# StarPunk
+## [2.10.1] - 2026-11-03
 
-A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.
-
-**Current Version**: 0.1.0 (development)
-
-## Versioning
-
-StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
-- Version format: `MAJOR.MINOR.PATCH`
-- Current: `0.1.0` (pre-release development)
-- First stable release will be `1.0.0`
-```
-
-**Update when**: Version changes (manually)
-
----
-
-### 3. CHANGELOG.md
-
-**Status**: ✅ Created
-
-**Location**: `/home/phil/Projects/starpunk/CHANGELOG.md`
-
-**Format**: Based on [Keep a Changelog](https://keepachangelog.com/)
-
-**Structure**:
-```markdown
-# Changelog
-
-## [Unreleased]
-
-### Added
-- Features being developed
-
-## [1.0.0] - 2024-11-18
-
-### Added
-- New features
-
-### Changed
-- Changes to existing features
-
-### Fixed
-- Bug fixes
+One optional sentence of context, e.g. which review or incident this
+release comes from, with links (ADR, spec).
 
 ### Security
-- Security patches
-```
-
-**Update when**: Every change (add to `[Unreleased]`), then move to versioned section on release
-
----
-
-### 4. Git Tags
-
-**Status**: ⏳ To be created when releasing
-
-**Format**: `vMAJOR.MINOR.PATCH[-PRERELEASE]`
-
-**Examples**:
-```bash
-v0.1.0          # Development version
-v0.2.0          # Next development version
-v1.0.0-alpha.1  # Alpha pre-release
-v1.0.0-beta.1   # Beta pre-release
-v1.0.0-rc.1     # Release candidate
-v1.0.0          # Stable release
-```
-
-**How to Create**:
-```bash
-# Annotated tag (recommended)
-git tag -a v0.1.0 -m "Development version 0.1.0: Phase 1.1 complete
-
-- Core utilities implemented
-- Slug generation
-- File operations
-- Content hashing
-
-See CHANGELOG.md for full details."
-
-# Push tag
-git push origin v0.1.0
-```
-
-**Current Tags**: None yet (will create when Phase 1.1 is complete)
-
----
-
-### 5. pyproject.toml (Optional, Future)
-
-**Status**: ⚠️ Not currently used
-
-**Location**: `/home/phil/Projects/starpunk/pyproject.toml` (if created)
-
-**Content** (if we create this file):
-```toml
-[project]
-name = "starpunk"
-version = "0.1.0"
-description = "Minimal IndieWeb CMS"
-authors = [
-    {name = "Your Name", email = "your@email.com"}
-]
-dependencies = [
-    "flask>=3.0.0",
-    "python-markdown>=3.5.0",
-    "feedgen>=1.0.0",
-    "httpx>=0.25.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/YOUR_USERNAME/starpunk"
-Repository = "https://github.com/YOUR_USERNAME/starpunk"
-Changelog = "https://github.com/YOUR_USERNAME/starpunk/blob/main/CHANGELOG.md"
-```
-
-**Decision**: Not needed for V1 (keeping it simple)
-
----
-
-## How to Update Version
-
-### Step-by-Step Process
-
-When you're ready to release a new version:
-
-#### 1. Decide on Version Number
-
-Use the decision tree from `versioning-strategy.md`:
-
-- **Breaking changes?** → Increment MAJOR (e.g., 1.0.0 → 2.0.0)
-- **New features?** → Increment MINOR (e.g., 1.0.0 → 1.1.0)
-- **Bug fixes only?** → Increment PATCH (e.g., 1.0.0 → 1.0.1)
-
-**During 0.x development**:
-- **Phase complete?** → Increment MINOR (e.g., 0.1.0 → 0.2.0)
-- **Bug fix?** → Increment PATCH (e.g., 0.1.0 → 0.1.1)
-
-#### 2. Update `starpunk/__init__.py`
-
-```python
-# Change version strings
-__version__ = "0.2.0"  # New version
-__version_info__ = (0, 2, 0)  # New version tuple
-```
-
-#### 3. Update `CHANGELOG.md`
-
-Move `[Unreleased]` items to new version section:
-
-```markdown
-## [Unreleased]
-
-### Added
-
-### Changed
+- ...
 
 ### Fixed
-
-## [0.2.0] - 2024-11-19
-
-### Added
-- Data models implementation
-- Database schema
-- Note class with validation
-
-### Changed
-- Improved error handling in utilities
-
-[Unreleased]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/YOUR_USERNAME/starpunk/releases/tag/v0.1.0
+- ...
 ```
 
-#### 4. Update `README.md`
+- Sections, in this order, only those that apply: **Added**, **Changed**,
+  **Deprecated**, **Removed**, **Fixed**, **Security**.
+- Write for the site owner: what they will notice and what they must do
+  (new settings, behaviour changes), not which functions changed.
+- Name new settings in backticks, new migrations by number
+  ("(migration 017)"), and link the ADR for a new feature.
+- Behaviour changes a user could trip over go first under **Changed**, in
+  bold if they need action.
+
+## Design note
+
+`docs/design/vX.Y.Z/YYYY-MM-DD-.md`, written alongside the change
+(rules in [docs/DOCUMENTATION.md](../DOCUMENTATION.md)). Short and factual,
+for example `docs/design/v2.8.1/2026-11-03-migration-lock.md`:
 
-Change current version:
 ```markdown
-**Current Version**: 0.2.0 (development)
+# vX.Y.Z: 
+
+## Incident / Context     what was wrong or what was asked for
+## Causes / Decision      why, with references to the spec or ADR
+## Fix / Changes          what the code now does, file by file if useful
+## Verification           tests added, manual checks, before/after numbers
 ```
 
-#### 5. Commit Changes
+Releases whose design is fully recorded in an ADR (a new ADR, or an
+"Amendments" section, as v2.10.0 and v2.10.1 did in ADR-071) may skip the
+design note; the changelog then links the ADR.
 
-```bash
-git add starpunk/__init__.py CHANGELOG.md README.md
-git commit -m "Bump version to 0.2.0"
-```
+## Code comments
 
-#### 6. Create Git Tag
+New or changed behaviour is often marked with the release that introduced
+it, e.g. `# Media types are case-insensitive (v2.10.1)`. This helps when
+reading the code next to the changelog; it is optional.
 
-```bash
-git tag -a v0.2.0 -m "Development version 0.2.0: Phase 1.2 complete
+## Checklist
 
-- Data models implementation
-- Database schema defined
-- Note class with full validation
-- Session and token models
-
-See CHANGELOG.md for full details."
-```
-
-#### 7. Push to Repository
-
-```bash
-git push origin main
-git push origin v0.2.0
-```
-
-#### 8. Create GitHub Release (Optional)
-
-If using GitHub:
-1. Go to repository → Releases
-2. Click "Draft a new release"
-3. Choose tag: `v0.2.0`
-4. Release title: `Version 0.2.0`
-5. Description: Copy from CHANGELOG.md
-6. Publish release
-
----
-
-## How to Check Version
-
-### From Python Code
-
-```python
-# Method 1: Import from package
-from starpunk import __version__
-print(f"Version: {__version__}")
-
-# Method 2: Use version_info for comparisons
-from starpunk import __version_info__
-if __version_info__ >= (1, 0, 0):
-    print("Stable release")
-else:
-    print("Development version")
-```
-
-### From Command Line
-
-```bash
-# Method 1: Python one-liner
-python -c "from starpunk import __version__; print(__version__)"
-
-# Method 2: Check Git tags
-git tag -l
-
-# Method 3: Check current HEAD tag
-git describe --tags --abbrev=0
-
-# Method 4: Show all version info
-git describe --tags
-```
-
-### From Web Interface (Future)
-
-When implemented, will show in:
-- Footer of all pages
-- `/api/info` endpoint
-- Admin dashboard
-
----
-
-## Version Comparison Examples
-
-### Using `__version_info__`
-
-```python
-from starpunk import __version_info__
-
-# Check minimum version
-def require_version(major, minor, patch):
-    return __version_info__ >= (major, minor, patch)
-
-# Examples
-if require_version(1, 0, 0):
-    print("Running stable version")
-
-if require_version(0, 2, 0):
-    print("Has data models")
-```
-
-### Parsing `__version__` String
-
-```python
-from starpunk import __version__
-from packaging.version import Version
-
-current = Version(__version__)
-required = Version("1.0.0")
-
-if current >= required:
-    print("Version requirement met")
-```
-
----
-
-## Release Checklist
-
-Use this checklist when releasing a new version:
-
-### Pre-Release
-
-- [ ] All tests pass: `pytest`
-- [ ] Code formatted: `black starpunk/ tests/`
-- [ ] Code linted: `flake8 starpunk/ tests/`
-- [ ] Documentation updated
-- [ ] All features working
-- [ ] Manual testing completed
-
-### Version Bump
-
-- [ ] Decide version number (MAJOR.MINOR.PATCH)
-- [ ] Update `starpunk/__init__.py` → `__version__`
-- [ ] Update `starpunk/__init__.py` → `__version_info__`
-- [ ] Update `CHANGELOG.md` with changes and date
-- [ ] Update `README.md` with current version
-- [ ] Review changes: `git diff`
-
-### Commit and Tag
-
-- [ ] Stage files: `git add starpunk/__init__.py CHANGELOG.md README.md`
-- [ ] Commit: `git commit -m "Bump version to X.Y.Z"`
-- [ ] Create annotated tag: `git tag -a vX.Y.Z -m "Release X.Y.Z: [description]"`
-- [ ] Push commits: `git push origin main`
-- [ ] Push tag: `git push origin vX.Y.Z`
-
-### Post-Release
-
-- [ ] Verify tag exists: `git tag -l`
-- [ ] Create GitHub release (if applicable)
-- [ ] Test installation from tag
-- [ ] Announce release (if applicable)
-- [ ] Create `[Unreleased]` section in CHANGELOG.md for next development
-
----
-
-## Common Scenarios
-
-### Scenario 1: Completing a Development Phase
-
-**Situation**: Phase 1.2 is complete (data models implemented)
-
-**Action**:
-1. Version: 0.1.0 → 0.2.0 (increment MINOR during 0.x)
-2. Update `__init__.py`: `__version__ = "0.2.0"`, `__version_info__ = (0, 2, 0)`
-3. Update CHANGELOG: Add `[0.2.0]` section with date
-4. Commit: `"Bump version to 0.2.0"`
-5. Tag: `v0.2.0`
-6. Push
-
-### Scenario 2: Fixing a Bug
-
-**Situation**: Found bug in slug generation, fixed it
-
-**Action**:
-1. Version: 0.2.0 → 0.2.1 (increment PATCH)
-2. Update `__init__.py`: `__version__ = "0.2.1"`, `__version_info__ = (0, 2, 1)`
-3. Update CHANGELOG: Add `[0.2.1]` section with bug fix
-4. Commit: `"Bump version to 0.2.1"`
-5. Tag: `v0.2.1`
-6. Push
-
-### Scenario 3: First Stable Release
-
-**Situation**: All V1 features complete, ready for production
-
-**Action**:
-1. Version: 0.9.0 → 1.0.0 (first stable release!)
-2. Update `__init__.py`: `__version__ = "1.0.0"`, `__version_info__ = (1, 0, 0)`
-3. Update CHANGELOG: Comprehensive `[1.0.0]` section
-4. Update README: Change "0.x.0 (development)" to "1.0.0 (stable)"
-5. Commit: `"Bump version to 1.0.0 - First stable release"`
-6. Tag: `v1.0.0` with detailed release notes
-7. Push
-8. Create GitHub release with announcement
-
-### Scenario 4: Adding New Feature (Post-1.0)
-
-**Situation**: Added tags feature in version 1.0.0, want to release it
-
-**Action**:
-1. Version: 1.0.0 → 1.1.0 (increment MINOR for new feature)
-2. Update `__init__.py`: `__version__ = "1.1.0"`, `__version_info__ = (1, 1, 0)`
-3. Update CHANGELOG: Add `[1.1.0]` section with "Added: Tags support"
-4. Commit and tag
-5. Push
-
-### Scenario 5: Breaking Change (Post-1.0)
-
-**Situation**: Changed Micropub API response format (breaking change)
-
-**Action**:
-1. Version: 1.5.0 → 2.0.0 (increment MAJOR for breaking change)
-2. Update `__init__.py`: `__version__ = "2.0.0"`, `__version_info__ = (2, 0, 0)`
-3. Update CHANGELOG: Clear "Breaking Changes" section
-4. Create upgrade guide: `docs/upgrade/1.x-to-2.0.md`
-5. Commit and tag
-6. Push
-7. Prominently announce breaking changes
-
----
-
-## Troubleshooting
-
-### Version Mismatch
-
-**Problem**: `__version__` and `__version_info__` don't match
-
-**Solution**: They must always match:
-```python
-# Correct
-__version__ = "1.2.3"
-__version_info__ = (1, 2, 3)
-
-# Wrong
-__version__ = "1.2.3"
-__version_info__ = (1, 2, 0)  # Mismatch!
-```
-
-### Forgot to Update CHANGELOG
-
-**Problem**: Released version without updating CHANGELOG
-
-**Solution**:
-1. Update CHANGELOG now
-2. Commit: `"Update CHANGELOG for version X.Y.Z"`
-3. Don't change version number or tag
-4. Consider creating patch release with corrected changelog
-
-### Wrong Version Number
-
-**Problem**: Tagged v1.1.0 but should have been v2.0.0
-
-**Solution**:
-```bash
-# Delete local tag
-git tag -d v1.1.0
-
-# Delete remote tag
-git push origin :refs/tags/v1.1.0
-
-# Create correct tag
-git tag -a v2.0.0 -m "Release 2.0.0"
-git push origin v2.0.0
-```
-
-**Warning**: Only do this immediately after release, before anyone uses the tag!
-
-### Git Tag vs Python Version Mismatch
-
-**Problem**: Git tag says `v1.0.0` but `__version__` says `"0.9.0"`
-
-**Solution**: These must always match:
-1. Check Git tag: `git describe --tags`
-2. Check Python version: `python -c "from starpunk import __version__; print(__version__)"`
-3. They should match (ignoring `v` prefix)
-4. If mismatch, fix `__init__.py` and create new tag
-
----
-
-## Pre-Release Versions
-
-### Alpha Releases
-
-**When**: Early development, unstable, missing features
-
-**Format**:
-- Git tag: `v1.0.0-alpha.1`
-- Python `__version__`: `"1.0.0a1"` (PEP 440 format)
-- `__version_info__`: `(1, 0, 0, "alpha", 1)` (extended tuple)
-
-**Example**:
-```python
-__version__ = "1.0.0a1"
-__version_info__ = (1, 0, 0)  # Simplified, or extended: (1, 0, 0, "alpha", 1)
-```
-
-### Beta Releases
-
-**When**: Feature complete, testing phase
-
-**Format**:
-- Git tag: `v1.0.0-beta.1`
-- Python `__version__`: `"1.0.0b1"`
-- `__version_info__`: `(1, 0, 0)`
-
-### Release Candidates
-
-**When**: Final testing before stable release
-
-**Format**:
-- Git tag: `v1.0.0-rc.1`
-- Python `__version__`: `"1.0.0rc1"`
-- `__version_info__`: `(1, 0, 0)`
-
-**Note**: For V1, we may skip pre-releases entirely and go straight to 1.0.0 if 0.x testing is sufficient.
-
----
-
-## Integration with Other Systems
-
-### Flask Application
-
-```python
-# In Flask app
-from starpunk import __version__
-
-@app.route('/api/info')
-def api_info():
-    return {
-        "name": "StarPunk",
-        "version": __version__,
-        "micropub_endpoint": "/api/micropub"
-    }
-```
-
-### CLI Tool (Future)
-
-```python
-import click
-from starpunk import __version__
-
-@click.group()
-@click.version_option(version=__version__, prog_name="StarPunk")
-def cli():
-    """StarPunk CMS"""
-    pass
-```
-
-### User-Agent String
-
-```python
-from starpunk import __version__
-
-USER_AGENT = f"StarPunk/{__version__} (https://github.com/YOUR_USERNAME/starpunk)"
-
-# Use in HTTP requests
-headers = {"User-Agent": USER_AGENT}
-```
-
----
-
-## References
-
-- [Versioning Strategy (complete spec)](versioning-strategy.md)
-- [ADR-008: Versioning Strategy](../decisions/ADR-008-versioning-strategy.md)
-- [Semantic Versioning 2.0.0](https://semver.org/)
-- [PEP 440 - Version Identification](https://peps.python.org/pep-0440/)
-- [Keep a Changelog](https://keepachangelog.com/)
-
----
-
-**Document Version**: 1.0
-**Last Updated**: 2024-11-18
-**Status**: Active
+- [ ] `__version__` and `__version_info__` updated in `starpunk/__init__.py`
+- [ ] `CHANGELOG.md` entry with today's date
+- [ ] Design note in `docs/design/vX.Y.Z/` (or ADR amendment)
+- [ ] `.env.example` updated for new settings
+- [ ] Commit subject ends with `(vX.Y.Z)`; tag is `vX.Y.Z`, annotated, message `vX.Y.Z: `
diff --git a/docs/standards/versioning-strategy.md b/docs/standards/versioning-strategy.md
index 29b1c28..d945987 100644
--- a/docs/standards/versioning-strategy.md
+++ b/docs/standards/versioning-strategy.md
@@ -1,1319 +1,75 @@
-# StarPunk Versioning Strategy
+# Versioning Strategy
 
-## Overview
+**Status**: Active
+**Last Updated**: 2026-11-03 (v2.10.1)
 
-StarPunk uses **Semantic Versioning 2.0.0** (SemVer) with Python ecosystem compliance (PEP 440) for version numbering. This strategy provides clear, predictable version numbers that communicate the nature of changes to users and developers.
+StarPunk uses [Semantic Versioning 2.0.0](https://semver.org/):
+`MAJOR.MINOR.PATCH`, currently **2.10.1**. Every release is a git tag
+`vX.Y.Z` and a `CHANGELOG.md` entry. Where the number is stored and how to
+write the changelog entry is in
+[version-implementation-guide.md](version-implementation-guide.md); the
+release steps are in [git-branching-strategy.md](git-branching-strategy.md#release-process).
+Background: [ADR-008](../decisions/ADR-008-versioning-strategy.md).
 
-**Current Version**: 0.1.0 (pre-release/development)
+## What the number means
 
-**Version Format**: `MAJOR.MINOR.PATCH` (e.g., `1.0.0`)
+StarPunk is a single-user site, so "compatibility" means: can the owner
+upgrade by changing the image tag, without editing configuration, losing
+data, or breaking Micropub clients, feed readers and other sites that talk
+to it?
 
-## Rationale
+**MAJOR**: the owner has to act, or something that worked stops working.
 
-Semantic Versioning was chosen because:
+- A required setting is added, renamed or removed, or login changes
+  (v2.0.0: IndieLogin replaced by OIDC admin login, new `OIDC_*` settings)
+- A public URL, feed or protocol endpoint goes away or changes behaviour
+  incompatibly
+- Data has to be converted by hand
 
-1. **Industry Standard**: Widely used in Python ecosystem (Flask, Django, etc.)
-2. **Clear Communication**: Version number immediately conveys type of changes
-3. **Dependency Management**: Works seamlessly with pip, uv, and Python packaging
-4. **Simple and Predictable**: Easy for indie developers to understand and apply
-5. **IndieWeb Aligned**: Transparent versioning supports independent, sustainable software
+**MINOR**: new capability; upgrading needs no action.
 
-## Version Number Format
+- New features, post types, protocol support or crossposting targets
+  (v2.6.0 Threads, v2.9.0 bookmarks, v2.10.0 WebSub)
+- New optional settings with safe defaults
+- Changes to defaults that a spec review shows are needed for compliance
+  (v2.9.0: Micropub posts are only crossposted to targets the client asks
+  for). Call these out under **Changed** in the changelog
 
-### Structure
+**PATCH**: fixes; nothing new to learn.
 
-```
-MAJOR.MINOR.PATCH[-PRERELEASE][+BUILDMETADATA]
+- Bug and security fixes (v2.8.1 migration lock, v2.10.1 WebSub hardening)
+- Spec-compliance fixes that don't add features
+- CI and build changes (v2.7.1)
 
-Examples:
-  0.1.0          - Development version
-  1.0.0          - First stable release
-  1.1.0          - Minor feature addition
-  1.1.1          - Bug fix
-  2.0.0          - Breaking change
-  1.0.0-alpha.1  - Alpha pre-release
-  1.0.0-beta.2   - Beta pre-release
-  1.0.0-rc.1     - Release candidate
-```
+A migration on its own doesn't decide the level: migrations run
+automatically, so a PATCH may include one (v2.10.1 added migration 017).
+What it changes decides the level. Any release with a migration needs a
+database backup before deploying.
 
-### Component Definitions
+## Decision guide
 
-**MAJOR** - Increment when making incompatible changes:
-- Breaking API changes (e.g., removing endpoints, changing response formats)
-- Database schema changes requiring migration
-- Configuration file format changes requiring user intervention
-- Major architectural rewrites
-- Removal of deprecated features
+1. Does upgrading require the owner to change configuration or data, or
+   break an existing client or URL? **MAJOR**
+2. Otherwise, does it add something new (feature, endpoint, setting, post
+   type)? **MINOR**
+3. Otherwise **PATCH**.
 
-**MINOR** - Increment when adding functionality in a backward-compatible manner:
-- New features (e.g., adding tags, categories)
-- New API endpoints
-- Non-breaking enhancements to existing features
-- Addition of optional configuration parameters
-- Performance improvements (significant)
+A MINOR resets PATCH to 0; a MAJOR resets both.
 
-**PATCH** - Increment for backward-compatible bug fixes:
-- Bug fixes
-- Security patches
-- Documentation corrections
-- Minor performance improvements
-- Dependency updates (without feature changes)
+## Pre-releases
 
-**PRE-RELEASE** (optional) - Alpha, beta, and release candidate versions:
-- `alpha.N` - Early development, unstable, missing features
-- `beta.N` - Feature complete, testing and stabilization
-- `rc.N` - Release candidate, final testing before stable release
+Release candidate tags `vX.Y.Z-rc.N` may be used to try a risky release
+in production first (v1.x had several; the last was `v2.0.0-rc.1`). CI only
+builds tags matching `vX.Y.Z`, so a release candidate image has to be built
+by hand. `__version__` may carry the suffix (`"1.1.1-rc.2"`);
+`__version_info__` holds the numbers only (`(1, 1, 1)`).
 
-**BUILD METADATA** (optional, rarely used) - Build information:
-- Not used for version precedence
-- Example: `1.0.0+20241118.abc123`
+## Documentation-only changes
 
-## Version Lifecycle
-
-### Development Phase (Current: 0.x.y)
-
-**Status**: Pre-1.0, anything may change at any time
-
-- Version format: `0.MINOR.PATCH`
-- MINOR increments for new features (Phase 1.1, 1.2, etc.)
-- PATCH increments for bug fixes
-- Public API should not be considered stable
-- Breaking changes allowed without major version increment
-
-**Examples**:
-```
-0.1.0  - Phase 1.1: Core utilities
-0.2.0  - Phase 1.2: Data models
-0.3.0  - Phase 1.3: Web routes
-0.3.1  - Bug fix in web routes
-0.4.0  - Phase 2.1: Micropub endpoint
-1.0.0  - First stable release (V1 complete)
-```
-
-### Pre-Release Versions
-
-**Alpha** - Early development, experimental features:
-```
-1.0.0-alpha.1  - First alpha
-1.0.0-alpha.2  - Second alpha
-```
-
-**Beta** - Feature complete, testing phase:
-```
-1.0.0-beta.1   - First beta
-1.0.0-beta.2   - Second beta (bug fixes)
-```
-
-**Release Candidate** - Final testing before stable:
-```
-1.0.0-rc.1     - First release candidate
-1.0.0-rc.2     - Second RC (critical fixes only)
-```
-
-**Usage**: Pre-releases are optional. For StarPunk V1, we may skip directly to 1.0.0 if development version (0.x.y) is sufficiently tested.
-
-### Stable Releases
-
-**First Stable Release**: `1.0.0`
-- Indicates production-ready software
-- All V1 features implemented and tested
-- Public API is stable and documented
-- Breaking changes require MAJOR version increment
-
-**Maintenance Releases**: `1.0.x`
-- Bug fixes only
-- Security patches
-- Documentation updates
-- No new features
-- No breaking changes
-
-**Feature Releases**: `1.x.0`
-- New backward-compatible features
-- Enhancements to existing features
-- Non-breaking API additions
-- Optional new configuration parameters
-
-**Major Releases**: `x.0.0`
-- Breaking changes
-- Major new features requiring incompatible changes
-- Database schema changes
-- Configuration format changes
-
-## Version Increment Decision Tree
-
-```
-┌─────────────────────────────────────────┐
-│ Does the change break existing usage?   │
-│ (API, config, database schema)          │
-└─────────┬───────────────────────────────┘
-          │
-    ┌─────┴─────┐
-    │    YES    │
-    └─────┬─────┘
-          │
-          ▼
-    ┌───────────────┐
-    │ Increment     │
-    │ MAJOR         │
-    └───────────────┘
-
-    ┌─────┴─────┐
-    │     NO    │
-    └─────┬─────┘
-          │
-          ▼
-┌─────────────────────────────────────────┐
-│ Does the change add new functionality?   │
-└─────────┬───────────────────────────────┘
-          │
-    ┌─────┴─────┐
-    │    YES    │
-    └─────┬─────┘
-          │
-          ▼
-    ┌───────────────┐
-    │ Increment     │
-    │ MINOR         │
-    └───────────────┘
-
-    ┌─────┴─────┐
-    │     NO    │
-    └─────┬─────┘
-          │
-          ▼
-┌─────────────────────────────────────────┐
-│ Is this a bug fix, security patch,      │
-│ or documentation update?                │
-└─────────┬───────────────────────────────┘
-          │
-    ┌─────┴─────┐
-    │    YES    │
-    └─────┬─────┘
-          │
-          ▼
-    ┌───────────────┐
-    │ Increment     │
-    │ PATCH         │
-    └───────────────┘
-```
-
-## Practical Examples
-
-### Scenario 1: Adding Tags Feature (Backward Compatible)
-
-**Change**: Add optional tags to notes, new API endpoint `/api/tags`
-
-**Impact**:
-- Database: Add `tags` table (migration script provided)
-- API: Add new `/api/tags` endpoint (doesn't break existing endpoints)
-- Config: Add optional `ENABLE_TAGS` setting (defaults to false)
-
-**Version**: `1.0.0` → `1.1.0` (MINOR increment)
-
-**Rationale**: New feature, backward compatible, existing functionality unchanged
-
----
-
-### Scenario 2: Fixing RSS Feed Date Format Bug
-
-**Change**: Fix RFC-822 date formatting in RSS feed
-
-**Impact**:
-- Bug fix only
-- No API changes
-- No configuration changes
-- No breaking changes
-
-**Version**: `1.1.0` → `1.1.1` (PATCH increment)
-
-**Rationale**: Bug fix, backward compatible
-
----
-
-### Scenario 3: Changing Micropub Response Format
-
-**Change**: Change Micropub endpoint response from `201 Created` with `Location` header to JSON body with `url` field
-
-**Impact**:
-- Breaks existing Micropub clients
-- API contract changed
-- Incompatible with previous version
-
-**Version**: `1.1.1` → `2.0.0` (MAJOR increment)
-
-**Rationale**: Breaking API change requires major version
-
----
-
-### Scenario 4: Performance Optimization
-
-**Change**: Optimize database queries for note listing
-
-**Impact**:
-- No API changes
-- No configuration changes
-- Faster response times
-- No breaking changes
-
-**Version**: `1.1.1` → `1.1.2` (PATCH increment)
-
-**Rationale**: Internal improvement, no user-facing changes
-
-## Version Scope
-
-### Application Version
-
-**What**: The overall StarPunk software version
-
-**Where Stored**:
-- `starpunk/__init__.py` - `__version__` variable
-- `pyproject.toml` - `version` field
-- Git tag - `vMAJOR.MINOR.PATCH`
-
-**What It Covers**:
-- All StarPunk code
-- API endpoints
-- Web interface
-- File storage format
-- Configuration format
-
-**Example**:
-```python
-# starpunk/__init__.py
-__version__ = "1.0.0"
-```
-
----
-
-### API Version (Future Consideration)
-
-**When Needed**: If we need to support multiple API versions simultaneously (V2+)
-
-**Format**: URL-based versioning (e.g., `/api/v1/notes`, `/api/v2/notes`)
-
-**Relationship to Application Version**:
-- API v1 introduced in StarPunk 1.0.0
-- API v2 might be introduced in StarPunk 2.0.0
-- Both can coexist (e.g., StarPunk 2.5.0 supports both API v1 and v2)
-
-**V1 Decision**: Not needed. Simple versioning via application version is sufficient.
-
----
-
-### Database Schema Version
-
-**What**: Version of database schema structure
-
-**When Needed**: If database migrations are required (V2+)
-
-**Format**: Integer sequence (1, 2, 3, ...)
-
-**Storage**: `schema_version` table or SQLite `PRAGMA user_version`
-
-**Relationship to Application Version**:
-- Schema version increments independently
-- Application version specifies compatible schema versions
-- Migration scripts bridge schema versions
-
-**V1 Decision**: Not needed. Database schema is simple and stable. If migrations are needed in V2+, we'll add this.
-
-**Example (if implemented)**:
-```sql
--- Store schema version
-PRAGMA user_version = 1;
-
--- Migration script 001-to-002.sql increments to 2
-PRAGMA user_version = 2;
-```
-
----
-
-### Configuration Version
-
-**What**: Version of configuration file format
-
-**When Needed**: If `.env` or config format changes incompatibly
-
-**V1 Decision**: Not needed. Configuration is simple and backward compatible.
-
-**V2+ Consideration**: If config format changes:
-- Add `CONFIG_VERSION=1` to `.env`
-- Migration tool or clear upgrade documentation
-- Version mismatch warning in application
-
----
-
-### Documentation Version
-
-**Strategy**: Documentation is versioned with the code
-
-**Implementation**:
-- Docs stored in Git alongside code
-- Git tags include documentation
-- README shows current version
-- Changelog documents changes
-
-**Multiple Versions**: Not maintained. Latest documentation is for latest version.
-
-**Historical Docs**: Available via Git tags (e.g., `git checkout v1.0.0` shows docs for that version)
-
-## Git Workflow
-
-### Tag Naming Convention
-
-**Format**: `vMAJOR.MINOR.PATCH[-PRERELEASE]`
-
-**Examples**:
-```
-v0.1.0          Development version
-v0.2.0          Development version with new features
-v1.0.0-alpha.1  First alpha of 1.0
-v1.0.0-beta.1   First beta of 1.0
-v1.0.0-rc.1     Release candidate
-v1.0.0          Stable release
-v1.0.1          Bug fix release
-v1.1.0          Feature release
-v2.0.0          Major release
-```
-
-**Prefix**: Use `v` prefix for Git tags (common convention, distinguishes from other tags)
-
-### Tag Type
-
-**Use Annotated Tags** (not lightweight tags)
-
-**Why**:
-- Contains tagger name, email, date
-- Can include release notes
-- Treated as full objects in Git
-- Can be signed with GPG
-
-**Command**:
-```bash
-git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
-```
-
-### Branch Strategy
-
-**Main Branch**: `main`
-- Always contains stable code
-- Tagged for releases
-- Protected (no direct commits)
-
-**Development Branch**: `develop` (optional, V2+)
-- Integration branch for features
-- Not needed for single developer in V1
-
-**Release Branches**: `release/vX.Y.Z` (optional, for testing)
-- Created when preparing release
-- Final testing and bug fixes
-- Merged to main when ready
-- Tagged on main branch
-
-**Feature Branches**: `feature/feature-name`
-- For new features
-- Merged to main when complete
-- Deleted after merge
-
-**Hotfix Branches**: `hotfix/issue-description`
-- For critical bug fixes
-- Merged to main
-- Tagged immediately
-
-**V1 Simple Workflow** (current):
-```
-main branch only
-  |
-  |-- feature work ---> commit ---> tag v0.1.0
-  |
-  |-- more features --> commit ---> tag v0.2.0
-  |
-  |-- ready for 1.0 -> commit ---> tag v1.0.0
-  |
-  |-- bug fix --------> commit ---> tag v1.0.1
-```
-
-### Release Process
-
-**Step-by-step**:
-
-1. **Ensure all changes are committed and tested**
-   ```bash
-   git status
-   pytest
-   ```
-
-2. **Update version in code**
-   ```bash
-   # Edit starpunk/__init__.py
-   __version__ = "1.0.0"
-
-   # Edit pyproject.toml (if exists)
-   version = "1.0.0"
-   ```
-
-3. **Update CHANGELOG.md**
-   ```bash
-   # Add release notes (see Changelog Format below)
-   ```
-
-4. **Commit version bump**
-   ```bash
-   git add starpunk/__init__.py pyproject.toml CHANGELOG.md
-   git commit -m "Bump version to 1.0.0"
-   ```
-
-5. **Create annotated tag**
-   ```bash
-   git tag -a v1.0.0 -m "Release 1.0.0: First stable release
-
-   - IndieAuth authentication
-   - Micropub support
-   - RSS feed generation
-   - File-based note storage
-   - Basic web interface
-
-   See CHANGELOG.md for full details."
-   ```
-
-6. **Push to repository**
-   ```bash
-   git push origin main
-   git push origin v1.0.0
-   ```
-
-7. **Create GitHub release** (if applicable)
-   - Go to GitHub Releases
-   - Create release from tag v1.0.0
-   - Add release notes
-   - Attach any binaries (not needed for Python)
-
-## Changelog Format
-
-### File Location
-
-**Path**: `/home/phil/Projects/starpunk/CHANGELOG.md`
-
-**Purpose**: Human-readable record of all notable changes
-
-### Format
-
-Based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
-
-**Structure**:
-```markdown
-# Changelog
-
-All notable changes to StarPunk will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- Work in progress features
-
-### Changed
-- Work in progress changes
-
-### Fixed
-- Work in progress fixes
-
-## [1.1.0] - 2024-12-01
-
-### Added
-- Tags support for organizing notes
-- New `/api/tags` endpoint
-- Tag filtering on homepage
-
-### Changed
-- Improved RSS feed performance
-- Updated markdown rendering library
-
-### Fixed
-- RSS feed date format now RFC-822 compliant
-- Session timeout handling
-
-### Security
-- Updated dependencies to patch vulnerabilities
-
-## [1.0.1] - 2024-11-20
-
-### Fixed
-- Corrected RSS feed date formatting
-- Fixed slug generation for non-ASCII content
-
-### Security
-- Patched XSS vulnerability in note rendering
-
-## [1.0.0] - 2024-11-18
-
-### Added
-- IndieAuth authentication via IndieLogin
-- Micropub endpoint for publishing
-- RSS feed generation
-- File-based note storage (Markdown)
-- SQLite metadata database
-- Web admin interface
-- Public note viewing
-- Slug generation and uniqueness
-- Session management
-- Basic security headers
-
-[Unreleased]: https://github.com/username/starpunk/compare/v1.1.0...HEAD
-[1.1.0]: https://github.com/username/starpunk/compare/v1.0.1...v1.1.0
-[1.0.1]: https://github.com/username/starpunk/compare/v1.0.0...v1.0.1
-[1.0.0]: https://github.com/username/starpunk/releases/tag/v1.0.0
-```
-
-### Entry Categories
-
-**Added** - New features
-**Changed** - Changes to existing functionality
-**Deprecated** - Features that will be removed in future versions
-**Removed** - Features that have been removed
-**Fixed** - Bug fixes
-**Security** - Security vulnerability fixes
-
-### Writing Changelog Entries
-
-**Good Entries** (clear, specific, user-focused):
-```markdown
-### Added
-- Tags support for organizing notes with `/api/tags` endpoint
-- Dark mode toggle in user preferences
-
-### Fixed
-- RSS feed now uses RFC-822 date format as required by spec
-- Micropub endpoint returns correct HTTP 201 status code
-```
-
-**Bad Entries** (vague, technical, unclear):
-```markdown
-### Added
-- New feature
-
-### Fixed
-- Bug fixes
-- Various improvements
-```
-
-## Communication Strategy
-
-### Version Display
-
-**In Web Interface**:
-```html
-<!-- Footer of all pages -->
-<footer>
-  StarPunk v1.0.0
-  <a href="https://github.com/username/starpunk/releases/tag/v1.0.0">Release Notes</a>
-</footer>
-```
-
-**In CLI**:
-```bash
-$ python -m starpunk --version
-StarPunk 1.0.0
-```
-
-**In API**:
-```http
-GET /api/info HTTP/1.1
-
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
-  "name": "StarPunk",
-  "version": "1.0.0",
-  "micropub_endpoint": "/api/micropub",
-  "indieauth_endpoint": "https://indielogin.com/auth"
-}
-```
-
-**In HTTP Headers** (optional):
-```http
-HTTP/1.1 200 OK
-X-StarPunk-Version: 1.0.0
-```
-
-**In User-Agent** (when making HTTP requests):
-```
-User-Agent: StarPunk/1.0.0 (https://github.com/username/starpunk)
-```
-
-### Release Announcements
-
-**Channels**:
-1. GitHub Releases (primary)
-2. README.md (update version badge)
-3. Personal website/blog (optional)
-4. IndieWeb community (optional)
-
-**Template**:
-```markdown
-# StarPunk 1.0.0 Released
-
-I'm excited to announce the first stable release of StarPunk, a minimal IndieWeb CMS!
-
-## What's New
-
-- Full IndieAuth authentication
-- Micropub endpoint for publishing from any client
-- RSS feed for syndication
-- File-based storage (your notes, your files)
-- Lightweight and self-hostable
-
-## Upgrade Instructions
-
-This is the first stable release. If you're upgrading from a development version (0.x):
-
-1. Backup your `data/` directory
-2. Pull the latest code: `git pull origin main`
-3. Check for any configuration changes in `.env.example`
-4. Restart the application
-
-## Download
-
-- [Source code](https://github.com/username/starpunk/archive/refs/tags/v1.0.0.zip)
-- [Installation instructions](https://github.com/username/starpunk#quick-start)
-
-## Changelog
-
-See [CHANGELOG.md](https://github.com/username/starpunk/blob/v1.0.0/CHANGELOG.md) for full details.
-```
-
-### Deprecation Warnings
-
-**When to Warn**:
-- One MINOR version before removal (e.g., deprecated in 1.1.0, removed in 2.0.0)
-- At least 6 months notice (for longer release cycles)
-
-**How to Warn**:
-
-**In Documentation**:
-```markdown
-## Configuration
-
-### `OLD_SETTING` (Deprecated)
-
-**Status**: Deprecated in v1.1.0, will be removed in v2.0.0
-
-**Replacement**: Use `NEW_SETTING` instead
-
-**Migration**:
-```env
-# Old (deprecated)
-OLD_SETTING=value
-
-# New
-NEW_SETTING=value
-```
-```
-
-**In Application Logs**:
-```python
-import warnings
-
-if config.get('OLD_SETTING'):
-    warnings.warn(
-        "OLD_SETTING is deprecated and will be removed in StarPunk 2.0.0. "
-        "Use NEW_SETTING instead.",
-        DeprecationWarning,
-        stacklevel=2
-    )
-```
-
-**In Changelog**:
-```markdown
-### Deprecated
-- `OLD_SETTING` configuration option (use `NEW_SETTING` instead)
-- Will be removed in v2.0.0
-```
-
-### Upgrade Guides
-
-**Location**: `docs/upgrade/`
-
-**Files**:
-- `docs/upgrade/0.x-to-1.0.md` - Development to stable
-- `docs/upgrade/1.x-to-2.0.md` - Major version upgrade
-
-**Template**:
-```markdown
-# Upgrading from 0.x to 1.0
-
-## Overview
-
-StarPunk 1.0 is the first stable release. This guide helps you upgrade from development versions (0.x).
-
-## Breaking Changes
-
-### Configuration Format
-
-**Change**: Configuration moved from JSON to .env file
-
-**Action Required**:
-1. Create `.env` file from `.env.example`
-2. Migrate settings from old `config.json`
-3. Delete `config.json`
-
-### Database Schema
-
-**Change**: Added `content_hash` column to `notes` table
-
-**Action Required**:
-Run migration script:
-```bash
-python scripts/migrate_0x_to_10.py
-```
-
-## New Features
-
-- IndieAuth authentication
-- Micropub endpoint
-- RSS feed
-
-See [CHANGELOG.md](../../CHANGELOG.md) for full details.
-
-## Step-by-Step Upgrade
-
-1. **Backup your data**:
-   ```bash
-   cp -r data/ data-backup-$(date +%Y%m%d)/
-   ```
-
-2. **Pull latest code**:
-   ```bash
-   git pull origin main
-   git checkout v1.0.0
-   ```
-
-3. **Update dependencies**:
-   ```bash
-   uv pip install -r requirements.txt
-   ```
-
-4. **Migrate configuration**:
-   ```bash
-   cp .env.example .env
-   # Edit .env with your settings
-   ```
-
-5. **Run database migration**:
-   ```bash
-   python scripts/migrate_0x_to_10.py
-   ```
-
-6. **Test**:
-   ```bash
-   pytest
-   flask --app app.py run
-   # Visit http://localhost:5000 and verify
-   ```
-
-7. **Restart production**:
-   ```bash
-   sudo systemctl restart starpunk
-   ```
-
-## Rollback
-
-If you encounter issues:
-
-1. Stop application
-2. Restore backup: `cp -r data-backup-*/ data/`
-3. Checkout previous version: `git checkout v0.9.0`
-4. Restart application
-
-## Support
-
-- [GitHub Issues](https://github.com/username/starpunk/issues)
-- [Documentation](../../README.md)
-```
-
-## Version Management in Code
-
-### Primary Version Storage
-
-**File**: `starpunk/__init__.py`
-
-```python
-"""
-StarPunk - Minimal IndieWeb CMS
-
-Version: 1.0.0
-"""
-
-__version__ = "1.0.0"
-__version_info__ = (1, 0, 0)
-
-# Make version easily importable
-from starpunk import __version__
-```
-
-**Usage**:
-```python
-from starpunk import __version__
-
-print(f"StarPunk version {__version__}")
-```
-
-### Package Metadata
-
-**File**: `pyproject.toml` (if using)
-
-```toml
-[project]
-name = "starpunk"
-version = "1.0.0"
-description = "Minimal IndieWeb CMS"
-authors = [
-    {name = "Your Name", email = "your.email@example.com"}
-]
-dependencies = [
-    "flask>=3.0.0",
-    # ... other dependencies
-]
-
-[project.urls]
-Homepage = "https://github.com/username/starpunk"
-Repository = "https://github.com/username/starpunk"
-Changelog = "https://github.com/username/starpunk/blob/main/CHANGELOG.md"
-```
-
-### Keeping Versions in Sync
-
-**Problem**: Version defined in multiple places (`__init__.py`, `pyproject.toml`, Git tags)
-
-**Solution**: Single source of truth in `starpunk/__init__.py`
-
-**Implementation**:
-
-Option 1 - Manual sync (simple, V1):
-```bash
-# Update version in __init__.py
-# Update version in pyproject.toml manually
-# Commit and tag
-```
-
-Option 2 - Automated sync (V2+):
-```bash
-# Use bumpversion/bump2version tool
-pip install bump2version
-
-# Configure in .bumpversion.cfg
-[bumpversion]
-current_version = 1.0.0
-commit = True
-tag = True
-
-[bumpversion:file:starpunk/__init__.py]
-[bumpversion:file:pyproject.toml]
-
-# Then bump version with:
-bump2version patch  # 1.0.0 -> 1.0.1
-bump2version minor  # 1.0.1 -> 1.1.0
-bump2version major  # 1.1.0 -> 2.0.0
-```
-
-**V1 Decision**: Manual sync (simple, no extra dependencies)
-
-### Version Check Utility
-
-**File**: `starpunk/utils.py` (or dedicated `starpunk/version.py`)
-
-```python
-from starpunk import __version__, __version_info__
-
-def get_version() -> str:
-    """Get StarPunk version string"""
-    return __version__
-
-def get_version_info() -> tuple:
-    """Get StarPunk version as tuple (major, minor, patch)"""
-    return __version_info__
-
-def check_version_compatibility(min_version: str) -> bool:
-    """
-    Check if current version meets minimum requirement
-
-    Args:
-        min_version: Minimum version required (e.g., "1.0.0")
-
-    Returns:
-        True if current version >= min_version
-    """
-    min_parts = tuple(int(x) for x in min_version.split('.'))
-    return __version_info__ >= min_parts
-```
-
-### CLI Version Display
-
-**Implementation**:
-
-```python
-# In app.py or starpunk/cli.py
-import click
-from starpunk import __version__
-
-@click.group()
-@click.version_option(version=__version__, prog_name="StarPunk")
-def cli():
-    """StarPunk - Minimal IndieWeb CMS"""
-    pass
-
-if __name__ == '__main__':
-    cli()
-```
-
-**Usage**:
-```bash
-$ python app.py --version
-StarPunk, version 1.0.0
-```
-
-## Development Workflow
-
-### Starting New Development
-
-**After Release**:
-1. Create new section in CHANGELOG.md:
-   ```markdown
-   ## [Unreleased]
-
-   ### Added
-
-   ### Changed
-
-   ### Fixed
-   ```
-
-2. Continue developing on main branch
-
-3. Track changes in `[Unreleased]` section
-
-### Preparing for Release
-
-**Checklist**:
-- [ ] All features complete and tested
-- [ ] All tests pass
-- [ ] Documentation updated
-- [ ] CHANGELOG.md updated with release date
-- [ ] Version bumped in `starpunk/__init__.py`
-- [ ] Version bumped in `pyproject.toml` (if exists)
-- [ ] Migration scripts created (if needed)
-- [ ] Upgrade guide written (if major/minor)
-
-### Release Testing
-
-**Pre-release**:
-1. Create release branch: `git checkout -b release/v1.1.0`
-2. Run full test suite: `pytest`
-3. Test upgrade from previous version
-4. Manual testing of all features
-5. Fix any bugs found
-6. Merge to main: `git checkout main && git merge release/v1.1.0`
-7. Tag and release
-
-## Python Ecosystem Compliance
-
-### PEP 440 Compatibility
-
-**Reference**: [PEP 440 - Version Identification](https://peps.python.org/pep-0440/)
-
-**Format**: Our SemVer format is PEP 440 compliant:
-```
-MAJOR.MINOR.PATCH[{a|b|rc}N]
-
-Examples:
-  1.0.0        - Final release
-  1.0.0a1      - Alpha (note: no dot before 'a')
-  1.0.0b2      - Beta
-  1.0.0rc1     - Release candidate
-```
-
-**Difference from SemVer**:
-- SemVer: `1.0.0-alpha.1` (hyphen and dot)
-- PEP 440: `1.0.0a1` (no separators)
-
-**Decision**: Use PEP 440 format for Python package compatibility
-
-**Git Tags**: Still use `v1.0.0-alpha.1` (hyphen allowed in Git tags, not in Python version)
-
-**Mapping**:
-```
-Git Tag          Python Version (__version__)
-v1.0.0-alpha.1   "1.0.0a1"
-v1.0.0-beta.2    "1.0.0b2"
-v1.0.0-rc.1      "1.0.0rc1"
-v1.0.0           "1.0.0"
-```
-
-### Version Specifiers
-
-**For dependencies** (`requirements.txt`, `pyproject.toml`):
-
-```
-# Exact version
-starpunk==1.0.0
-
-# Minimum version
-starpunk>=1.0.0
-
-# Compatible version (same major version)
-starpunk~=1.0.0  # Allows 1.0.x, not 1.1.0
-
-# Version range
-starpunk>=1.0.0,<2.0.0
-```
-
-## Current State and Transition
-
-### Current Terminology
-
-**Documentation References**:
-- "V1" - Overall first release goal
-- "Phase 1.1", "Phase 1.2" - Implementation milestones
-- "v1.1", "v2.0" - Future iteration references
-
-### Clarifications
-
-**Phases vs Versions**:
-- **Phases**: Development milestones (internal planning)
-  - Phase 1.1: Core utilities (development version 0.1.0)
-  - Phase 1.2: Data models (development version 0.2.0)
-  - Phase 1.3: Web routes (development version 0.3.0)
-  - etc.
-
-- **Versions**: Public release numbers (external communication)
-  - 0.1.0, 0.2.0 - Development versions
-  - 1.0.0 - First stable release (when all V1 phases complete)
-  - 1.1.0, 1.2.0 - Feature releases
-  - 2.0.0 - Next major version
-
-**Mapping**:
-```
-Implementation Phase  →  Version Number  →  Git Tag
-Phase 1.1 complete    →  0.1.0          →  v0.1.0
-Phase 1.2 complete    →  0.2.0          →  v0.2.0
-Phase 1.3 complete    →  0.3.0          →  v0.3.0
-Phase 2.1 complete    →  0.4.0          →  v0.4.0
-All V1 phases done    →  1.0.0          →  v1.0.0
-V1.1 features added   →  1.1.0          →  v1.1.0
-V2.0 features added   →  2.0.0          →  v2.0.0
-```
-
-### First Release Name
-
-**Question**: What should the first production release be called?
-
-**Answer**: `1.0.0`
-
-**Rationale**:
-- Signals production-ready software
-- Follows semantic versioning convention
-- "V1" in documentation refers to the feature set, not the version number
-- Version 1.0.0 implements the "V1 feature set"
-
-### Updating Documentation
-
-**Action Items**:
-1. Update references from "V1", "V2" to "version 1.0", "version 2.0"
-2. Clarify that "V1" is a feature scope, not a version number
-3. Use version numbers (1.0.0, 1.1.0) in user-facing communication
-4. Use phases (Phase 1.1, Phase 1.2) in development documentation
-
-**Example Updates**:
-
-Before:
-```markdown
-# V1 Features
-- IndieAuth authentication
-- Micropub support
-```
-
-After:
-```markdown
-# Version 1.0 Features (V1 Scope)
-- IndieAuth authentication
-- Micropub support
-```
-
-## FAQ
-
-### Q: When should I create version 1.0.0?
-
-**A**: When all features planned for the first production release are complete, tested, and documented. For StarPunk, this means:
-- All core features working (auth, publishing, RSS)
-- Full test coverage
-- Complete documentation
-- Production deployment tested
-- Ready for public use
-
-### Q: Can I skip 0.x versions and go straight to 1.0.0?
-
-**A**: Yes, but not recommended for StarPunk. Since we're actively developing, 0.x versions signal "not yet production ready" and give us freedom to make breaking changes.
-
-### Q: Should I version my API separately?
-
-**A**: Not needed for V1. Simple version numbers are sufficient. If you need to support multiple API versions simultaneously (e.g., breaking changes but maintain backward compatibility), consider API versioning in URLs (`/api/v1/`, `/api/v2/`).
-
-### Q: How do I handle hotfixes?
-
-**A**:
-1. Create hotfix branch from tag: `git checkout -b hotfix/critical-bug v1.0.0`
-2. Fix bug
-3. Increment PATCH version: 1.0.0 → 1.0.1
-4. Tag: `v1.0.1`
-5. Merge to main
-6. If developing next version, merge hotfix to develop branch too
-
-### Q: What if I need to change the database schema?
-
-**A**:
-- **Backward compatible** (adding optional column): MINOR version (1.0.0 → 1.1.0)
-- **Breaking change** (removing column, changing format): MAJOR version (1.0.0 → 2.0.0)
-- Provide migration script
-- Document in upgrade guide
-
-### Q: How do I handle dependency updates?
-
-**A**:
-- **Security patches**: PATCH version (1.0.0 → 1.0.1)
-- **Minor updates** (no feature changes): PATCH version
-- **Major updates** (with feature changes): MINOR or MAJOR depending on impact
-
-### Q: Should I version documentation separately?
-
-**A**: No. Documentation lives with code in Git. Version the whole repository together.
-
-### Q: What about version numbers for forks?
-
-**A**: If someone forks StarPunk:
-- They should use their own version numbers
-- Or add suffix: `1.0.0-fork` or `1.0.0+myname.1`
-- Keep major.minor.patch in sync with upstream if merging changes
-
-### Q: How do I communicate breaking changes?
-
-**A**:
-1. Increment MAJOR version
-2. Document in CHANGELOG under "Breaking Changes" section
-3. Provide upgrade guide
-4. Deprecate features one version early if possible
-5. Announce prominently in release notes
-
-### Q: Can I use dates in version numbers?
-
-**A**: Not recommended. Calendar versioning (CalVer) like `2024.11.18` is valid but doesn't communicate change impact. Semantic versioning is clearer for StarPunk's use case.
-
-## Tools and Automation
-
-### Manual Version Management (V1)
-
-**Current Approach**: Simple, manual versioning
-
-**Process**:
-1. Edit `starpunk/__init__.py`: `__version__ = "1.0.0"`
-2. Edit `pyproject.toml`: `version = "1.0.0"`
-3. Update `CHANGELOG.md`
-4. Commit: `git commit -m "Bump version to 1.0.0"`
-5. Tag: `git tag -a v1.0.0 -m "Release 1.0.0"`
-6. Push: `git push origin main v1.0.0`
-
-**Pros**: Simple, no dependencies, full control
-**Cons**: Manual, error-prone, easy to forget steps
-
-### Automated Version Management (V2+)
-
-**Tools to Consider**:
-
-**1. bump2version** / **bumpversion**
-```bash
-pip install bump2version
-
-# Configure in .bumpversion.cfg
-bump2version patch  # Increments, commits, tags automatically
-```
-
-**2. python-semantic-release**
-```bash
-pip install python-semantic-release
-
-# Analyzes commit messages, determines version bump
-semantic-release version
-```
-
-**3. setuptools_scm**
-```bash
-# Derives version from Git tags automatically
-pip install setuptools_scm
-```
-
-**V1 Decision**: Manual versioning (simplest, aligns with indie philosophy)
-
-**V2+ Consideration**: Add `bump2version` if versioning becomes tedious
-
-### Version Check on Install
-
-**Feature**: Warn user if running outdated version
-
-**Implementation** (optional, V2+):
-```python
-import requests
-from starpunk import __version__
-
-def check_for_updates():
-    """Check if a newer version is available"""
-    try:
-        response = requests.get(
-            "https://api.github.com/repos/username/starpunk/releases/latest",
-            timeout=2
-        )
-        latest = response.json()["tag_name"].lstrip('v')
-
-        if latest != __version__:
-            print(f"Update available: {latest} (you have {__version__})")
-            print("Visit: https://github.com/username/starpunk/releases")
-    except:
-        pass  # Silently fail, don't block application
-```
-
-**V1 Decision**: Not needed (manual update check)
+No version change. They are merged on a `docs/` branch without a tag.
 
 ## References
 
-### Standards
-
-- [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) - Official SemVer spec
-- [PEP 440](https://peps.python.org/pep-0440/) - Python version identification
-- [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Changelog format
-- [Calendar Versioning](https://calver.org/) - Alternative versioning (not used)
-
-### Tools
-
-- [bump2version](https://github.com/c4urself/bump2version) - Version bump automation
-- [python-semantic-release](https://python-semantic-release.readthedocs.io/) - Semantic release automation
-- [setuptools_scm](https://github.com/pypa/setuptools_scm) - SCM-based versioning
-
-### Examples
-
-- [Flask versioning](https://github.com/pallets/flask) - SemVer with PEP 440
-- [Django versioning](https://docs.djangoproject.com/en/stable/internals/release-process/) - Modified SemVer
-- [Requests versioning](https://github.com/psf/requests) - SemVer
-
-### Internal Documentation
-
-- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md)
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Development Setup](/home/phil/Projects/starpunk/docs/standards/development-setup.md)
-
----
-
-**Document Version**: 1.0
-**Last Updated**: 2024-11-18
-**Author**: StarPunk Architecture Team
-**Status**: Active
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+- [ADR-008: Versioning strategy](../decisions/ADR-008-versioning-strategy.md)
diff --git a/starpunk/rate_limiter.py b/starpunk/rate_limiter.py
index adf7f2d..5a69f74 100644
--- a/starpunk/rate_limiter.py
+++ b/starpunk/rate_limiter.py
@@ -2,11 +2,12 @@
 Rate limiting for webmention endpoint
 
 Implements sliding window log algorithm with thread-safe in-memory storage.
-Per ADR-064, this uses in-memory counters consistent with the existing
-_discovery_cache pattern in webmention_worker.py.
+Per ADR-063 (Decision 10), this uses in-memory counters. They are per
+gunicorn process, so the effective limit is the setting times the number of
+workers (see docs/design/v1.6.0/rate-limiting.md).
 
 References:
-    - ADR-064: Webmention Rate Limiting
+    - ADR-063: Webmention Implementation (Decision 10: rate limiting)
     - Design: /docs/design/v1.6.0/rate-limiting.md
 """
 
diff --git a/starpunk/routes/webmention.py b/starpunk/routes/webmention.py
index 7b35a2e..5342953 100644
--- a/starpunk/routes/webmention.py
+++ b/starpunk/routes/webmention.py
@@ -39,7 +39,7 @@ def rate_limit_webmention():
     """
     Check rate limits before processing webmention requests.
 
-    Per ADR-064, checks:
+    Per ADR-063 (Decision 10), checks:
     1. IP rate limit (60/min by default)
     2. Source domain rate limit (10/min by default)
 
diff --git a/tests/test_routes_public.py b/tests/test_routes_public.py
index 908d216..6733edc 100644
--- a/tests/test_routes_public.py
+++ b/tests/test_routes_public.py
@@ -281,4 +281,4 @@ class TestVersionDisplay:
 # OAuth metadata endpoint tests removed in Phase 1 of IndieAuth server removal
 # The /.well-known/oauth-authorization-server endpoint was removed as part of
 # removing the built-in IndieAuth authorization server functionality.
-# See: docs/architecture/indieauth-removal-phases.md
+# See: docs/decisions/ADR-050-remove-custom-indieauth-server.md (since superseded by ADR-064)
diff --git a/tests/test_templates.py b/tests/test_templates.py
index bb96183..e41c742 100644
--- a/tests/test_templates.py
+++ b/tests/test_templates.py
@@ -399,4 +399,4 @@ class TestTemplateVariables:
 # The h-app markup was only needed when StarPunk acted as an IndieAuth client
 # for Micropub authorization. With the authorization server removed, these
 # discovery microformats are no longer needed.
-# See: docs/architecture/indieauth-removal-phases.md
+# See: docs/decisions/ADR-050-remove-custom-indieauth-server.md (since superseded by ADR-064)