prashna 0.2.0__tar.gz

prashna-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+__pycache__/
+*.pyc
+.venv/
+.DS_Store
+
+# SQLite DB and journals — contains user accounts, session data.
+# (-wal / -shm are the WAL-mode sidecar files created at runtime.)
+prashna.db
+prashna.db-journal
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# User-uploaded files
+uploads/*
+!uploads/.gitkeep
+
+# Local env / IDE / tooling
+.env
+.env.*
+!.env.example
+.idea/
+.vscode/
+.claude/
+.mcp.json
+
+# Frontend dev-lint tooling (no runtime/build artifacts — dev only)
+node_modules/
+
+# Lint / test caches & coverage
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Vite build output (produced by `npm run build`)
+prashna/static/
+
+# Local release archives (published artifacts are attached in GitHub Releases)
+dist/

prashna-0.2.0/LICENSE

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

prashna-0.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: prashna
+Version: 0.2.0
+Summary: Live Q&A and quizzes for any session with an audience
+Project-URL: Homepage, https://kvsankar.github.io/prashna/
+Project-URL: Source, https://github.com/kvsankar/prashna
+Project-URL: Documentation, https://github.com/kvsankar/prashna/tree/main/docs
+Project-URL: Issues, https://github.com/kvsankar/prashna/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audience,classroom,live,q&a,quiz,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: itsdangerous>=2.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+# Prashna
+
+![How prashna brings an admin, moderators, participants and a projector into one live session for Q&A and quizzes, and what it produces afterwards](https://raw.githubusercontent.com/kvsankar/prashna/main/docs/images/prashna-infographic.png)
+
+*How prashna runs a session with an audience: an admin sets it up, a moderator runs the room, participants join on their phones and the projector shows the room the same state. Questions are asked and upvoted, versioned quizzes are run question by question, and the session ends with ranked questions, quiz results, run reports, attendee profiles and feedback. The [infographic source](https://github.com/kvsankar/prashna/blob/main/docs/images/prashna-infographic.html) is kept with the image.*
+
+A live Q&A and quiz tool for any session with an audience: training,
+lectures, workshops, town halls, meetups. *Prashna* (प्रश्न) is
+Sanskrit for *question*.
+
+Two core features:
+
+- **Anonymous Q&A.** Participants post questions and upvote each other's.
+  The moderator responds in text or out loud. A removed question is hidden
+  from participants and kept for the record.
+- **Moderator-run quizzes.** Single- or multiple-choice questions, optional
+  images, anonymous answers, results revealed one question at a time, a lobby
+  screen on the projector, and optional live counts while people answer.
+  Quizzes are versioned: editing a quiz never changes the report of a past
+  run.
+
+A **projector view** for the screen at the front of the room shows the join
+code, a QR code for the participant link, the top questions, and the current
+quiz question in step with the moderator.
+
+## Install
+
+One command, on macOS, Linux, or Windows:
+
+```bash
+curl -LsSf https://kvsankar.github.io/prashna/install.sh | sh                  # macOS / Linux
+powershell -ExecutionPolicy ByPass -c "irm https://kvsankar.github.io/prashna/install.ps1 | iex"   # Windows
+```
+
+Then start it:
+
+```bash
+prashna
+```
+
+If you already have [uv](https://docs.astral.sh/uv/), `uvx prashna` installs
+and starts it in one step. Update with `uv tool upgrade prashna`.
+`prashna --help` lists the options: port, data folder, and backups.
+
+## First run
+
+`prashna` serves on <http://127.0.0.1:8000> and opens your browser on a
+one-time page where you choose the admin's username and password. The page
+works once. After that, sign in to create sessions and write quizzes.
+Prashna keeps its data in your app-data folder.
+
+## Roles
+
+| Role | Page | Who gets in |
+| --- | --- | --- |
+| Admin | `/` | The person who signed in with the admin password (or an allowed GitHub account). Creates sessions and quizzes. |
+| Moderator | `/m/<code>` | The admin who owns the session, or anyone the admin gives the moderator link to, such as a co-host. Runs the room. |
+| Participant | `/s/<code>` | Anyone with the session code or QR code. No account; an optional profile. |
+| Projector | `/p/<code>` | Anyone. Read-only, for the room's screen. |
+| Quiz library | `/quizzes` | The admin. Writes quizzes and reads run reports. |
+
+The admin who owns a session can do everything a moderator can, on the same
+page, plus the session's settings. The moderator link is how the admin hands
+the room to someone without an admin account.
+
+## Documentation
+
+- [Behaviour specification](https://github.com/kvsankar/prashna/blob/main/docs/specs.md): every use case and its tests.
+- [UX rules](https://github.com/kvsankar/prashna/blob/main/docs/UX.md): the frontend design system.
+- [Architecture](https://github.com/kvsankar/prashna/blob/main/docs/architecture.md): components, data model, design decisions, and risks.
+- [Development guide](https://github.com/kvsankar/prashna/blob/main/docs/development.md): setup, environment variables, tests, checks, and releases.
+- [Engineering backlog](https://github.com/kvsankar/prashna/blob/main/docs/todo.md).
+- [Performance measurement](https://github.com/kvsankar/prashna/blob/main/performance/README.md).
+
+To run Prashna in Docker instead, see the
+[container guide](https://github.com/kvsankar/prashna/blob/main/distribution/README.md).
+The production deployment behind nginx is described in the
+[deployment runbook](https://github.com/kvsankar/prashna/blob/main/deploy/README.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/kvsankar/prashna/blob/main/LICENSE).
+
+## Status
+
+Prashna runs in production at `prashna.sankara.net` for a single operator. It
+is released as a container image.
+Product ideas that need a decision are listed in the
+[deferred appendix](https://github.com/kvsankar/prashna/blob/main/docs/specs.md#deferred-decision-needed)
+of the specification.

prashna-0.2.0/README.md

@@ -0,0 +1,90 @@
+# Prashna
+
+![How prashna brings an admin, moderators, participants and a projector into one live session for Q&A and quizzes, and what it produces afterwards](https://raw.githubusercontent.com/kvsankar/prashna/main/docs/images/prashna-infographic.png)
+
+*How prashna runs a session with an audience: an admin sets it up, a moderator runs the room, participants join on their phones and the projector shows the room the same state. Questions are asked and upvoted, versioned quizzes are run question by question, and the session ends with ranked questions, quiz results, run reports, attendee profiles and feedback. The [infographic source](https://github.com/kvsankar/prashna/blob/main/docs/images/prashna-infographic.html) is kept with the image.*
+
+A live Q&A and quiz tool for any session with an audience: training,
+lectures, workshops, town halls, meetups. *Prashna* (प्रश्न) is
+Sanskrit for *question*.
+
+Two core features:
+
+- **Anonymous Q&A.** Participants post questions and upvote each other's.
+  The moderator responds in text or out loud. A removed question is hidden
+  from participants and kept for the record.
+- **Moderator-run quizzes.** Single- or multiple-choice questions, optional
+  images, anonymous answers, results revealed one question at a time, a lobby
+  screen on the projector, and optional live counts while people answer.
+  Quizzes are versioned: editing a quiz never changes the report of a past
+  run.
+
+A **projector view** for the screen at the front of the room shows the join
+code, a QR code for the participant link, the top questions, and the current
+quiz question in step with the moderator.
+
+## Install
+
+One command, on macOS, Linux, or Windows:
+
+```bash
+curl -LsSf https://kvsankar.github.io/prashna/install.sh | sh                  # macOS / Linux
+powershell -ExecutionPolicy ByPass -c "irm https://kvsankar.github.io/prashna/install.ps1 | iex"   # Windows
+```
+
+Then start it:
+
+```bash
+prashna
+```
+
+If you already have [uv](https://docs.astral.sh/uv/), `uvx prashna` installs
+and starts it in one step. Update with `uv tool upgrade prashna`.
+`prashna --help` lists the options: port, data folder, and backups.
+
+## First run
+
+`prashna` serves on <http://127.0.0.1:8000> and opens your browser on a
+one-time page where you choose the admin's username and password. The page
+works once. After that, sign in to create sessions and write quizzes.
+Prashna keeps its data in your app-data folder.
+
+## Roles
+
+| Role | Page | Who gets in |
+| --- | --- | --- |
+| Admin | `/` | The person who signed in with the admin password (or an allowed GitHub account). Creates sessions and quizzes. |
+| Moderator | `/m/<code>` | The admin who owns the session, or anyone the admin gives the moderator link to, such as a co-host. Runs the room. |
+| Participant | `/s/<code>` | Anyone with the session code or QR code. No account; an optional profile. |
+| Projector | `/p/<code>` | Anyone. Read-only, for the room's screen. |
+| Quiz library | `/quizzes` | The admin. Writes quizzes and reads run reports. |
+
+The admin who owns a session can do everything a moderator can, on the same
+page, plus the session's settings. The moderator link is how the admin hands
+the room to someone without an admin account.
+
+## Documentation
+
+- [Behaviour specification](https://github.com/kvsankar/prashna/blob/main/docs/specs.md): every use case and its tests.
+- [UX rules](https://github.com/kvsankar/prashna/blob/main/docs/UX.md): the frontend design system.
+- [Architecture](https://github.com/kvsankar/prashna/blob/main/docs/architecture.md): components, data model, design decisions, and risks.
+- [Development guide](https://github.com/kvsankar/prashna/blob/main/docs/development.md): setup, environment variables, tests, checks, and releases.
+- [Engineering backlog](https://github.com/kvsankar/prashna/blob/main/docs/todo.md).
+- [Performance measurement](https://github.com/kvsankar/prashna/blob/main/performance/README.md).
+
+To run Prashna in Docker instead, see the
+[container guide](https://github.com/kvsankar/prashna/blob/main/distribution/README.md).
+The production deployment behind nginx is described in the
+[deployment runbook](https://github.com/kvsankar/prashna/blob/main/deploy/README.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/kvsankar/prashna/blob/main/LICENSE).
+
+## Status
+
+Prashna runs in production at `prashna.sankara.net` for a single operator. It
+is released as a container image.
+Product ideas that need a decision are listed in the
+[deferred appendix](https://github.com/kvsankar/prashna/blob/main/docs/specs.md#deferred-decision-needed)
+of the specification.

prashna-0.2.0/deploy/README.md

@@ -0,0 +1,176 @@
+# Deploy
+
+This directory holds everything the **Hetzner** box needs to run Prashna at
+`https://prashna.sankara.net`.
+
+Laptop and other self-hosted container installs use the root `compose.yaml`
+instead; see [`distribution/README.md`](../distribution/README.md).
+
+## One-time setup
+
+1. **DNS** — create a proxied Cloudflare `A` record whose origin value is:
+
+   ```
+   prashna.sankara.net → <server-ip>
+   ```
+
+   With the orange cloud enabled, public DNS correctly returns Cloudflare
+   anycast addresses rather than the server's IP. Verify the record and proxy
+   state in Cloudflare before continuing.
+
+2. **GitHub Actions** — the `Build & publish Docker image` workflow pushes to
+   `ghcr.io/kvsankar/prashna`. No extra secrets needed; it uses the built-in
+   `GITHUB_TOKEN` with `packages:write` permission. Trigger it once by pushing
+   to `main` or running it manually so the image exists.
+
+3. **On the server**, install nginx and Certbot if they are not already
+   present. `setup.sh` installs Docker when necessary, but it expects the nginx
+   and Certbot commands to exist before configuring TLS.
+
+4. **If the GHCR package is private**, sign in to `ghcr.io` on the server
+   first, as described in
+   [Registry access](../distribution/README.md#registry-access).
+
+5. **Run the bootstrap**:
+
+   ```bash
+   git clone git@github.com:kvsankar/prashna.git ~/repos/prashna
+   cd ~/repos/prashna
+   CERTBOT_EMAIL=you@example.com ./deploy/setup.sh
+   ```
+
+   This installs Docker when it is missing, lays down `/opt/prashna/` with a
+   generated `PRASHNA_SECRET_KEY` in `.env`, pulls the image, installs the
+   nginx site, prepares nginx for Cloudflare proxying
+   (`prepare-cloudflare-proxy.sh`), requests a TLS certificate with Certbot,
+   enables HTTP/2 (`enable-http2.sh`), and starts the container.
+
+6. **Create the first admin.** Find the one-time setup link in the log and
+   open it on `https://prashna.sankara.net`:
+
+   ```bash
+   cd /opt/prashna && docker compose logs prashna | grep setup=
+   ```
+
+   With GitHub sign-in configured, an allowlisted GitHub account can create
+   the admin instead.
+
+## Updating
+
+Either:
+
+```bash
+cd /opt/prashna && docker compose pull && docker compose up -d --wait
+```
+
+Or wire up the optional `deploy.yml` workflow (not included by default) that
+SSHes in and runs that on every push to `main`.
+
+## Cloudflare visitor IP and HTTP/2
+
+`setup.sh` runs two idempotent nginx helpers. Each one backs up the site file,
+validates the result with `nginx -t`, and restores the backup if validation
+fails.
+
+- `prepare-cloudflare-proxy.sh` downloads Cloudflare's published IP ranges and
+  writes them to `/etc/nginx/snippets/prashna-cloudflare-realip.conf` as
+  `set_real_ip_from` lines with `real_ip_header CF-Connecting-IP`. It includes
+  that file in the site. nginx then sees the visitor's address rather than a
+  Cloudflare edge address, and passes it on in `X-Forwarded-For`, which the
+  application reads with `PRASHNA_TRUSTED_PROXY_HOPS=1`. Re-run the script to
+  refresh the ranges.
+- `enable-http2.sh` adds `http2` to the Certbot-managed TLS listeners without
+  touching the certificates.
+
+Both read `PRASHNA_DOMAIN` and `PRASHNA_NGINX_SITE_PATH` to target another
+site.
+
+## Cloudflare HTML-shell caching
+
+The application marks only its static HTML page shells as edge-cacheable. API
+responses, bad-session redirects, and personalized data remain `no-store`.
+Cloudflare still needs a Cache Rule to make non-static HTML eligible. Preview
+the idempotent ruleset update, then apply it with a token that can edit zone
+rulesets:
+
+```bash
+export CLOUDFLARE_API_TOKEN=...       # Zone Rulesets:Edit and Zone:Read
+export CLOUDFLARE_ZONE_ID=...         # optional; discovered by zone name
+deploy/configure-cloudflare-cache.sh --dry-run
+deploy/configure-cloudflare-cache.sh --apply
+```
+
+The helper preserves unrelated cache rules and replaces only the stable
+`prashna_html_shells` rule. It covers `/`, `/quizzes`, and the `/s/`, `/m/`,
+and `/p/` page prefixes, and respects the application's browser and edge TTLs.
+Verify a repeated page response with `CF-Cache-Status`; purge the affected URLs
+after a deploy if the five-minute edge TTL is too long for an urgent shell fix.
+
+## Smoke test
+
+Run the production-like Docker Compose smoke from a development checkout with:
+
+```bash
+PRASHNA_COMPOSE_SMOKE=1 uv run pytest tests/ops/test_compose_smoke.py -q
+```
+
+The smoke builds the local image, starts Compose with temporary data and upload
+directories, waits for `/api/admin/status`, creates the first admin user,
+uploads an image, restarts the service, and verifies the SQLite file, upload,
+health endpoint, cookie signing, and safe diagnostics survive the restart.
+
+After an image is published, CI runs the same state/restart checks against its
+exact digest through the root distribution Compose model and also verifies the
+in-image backup command.
+
+The test removes its Compose project at the end. If it is interrupted, clean up
+with `docker compose --project-name <printed-project> down --volumes
+--remove-orphans`.
+
+## Files
+
+- `docker-compose.yml`: the service definition, copied to `/opt/prashna/`.
+  It requires `PRASHNA_SECRET_KEY` in `.env`.
+- `env.example`: reference for `/opt/prashna/.env`. `setup.sh` writes that
+  file with a generated key when it is missing.
+- `nginx-prashna.conf`: the nginx server block, symlinked into
+  `sites-enabled/`.
+- `setup.sh`: the idempotent bootstrap script.
+- `prepare-cloudflare-proxy.sh`: Cloudflare visitor-IP configuration for nginx.
+- `enable-http2.sh`: HTTP/2 on the TLS listeners.
+- `configure-cloudflare-cache.sh`: dry-run and apply reconciler for the
+  Cloudflare Cache Rule for HTML shells.
+
+## Persistent data
+
+- SQLite DB → `/opt/prashna/data/prashna.db`
+- User uploads → `/opt/prashna/uploads/`
+
+Back these two up. Everything else is rebuilt from the image.
+
+The container writes as UID/GID `1001:1001`, so those two host directories must
+be writable by that identity. If startup logs show SQLite or upload permission
+errors, fix ownership with:
+
+```bash
+sudo chown -R 1001:1001 /opt/prashna/data /opt/prashna/uploads
+```
+
+For local smoke tests only, the compose file accepts `PRASHNA_PORT`,
+`PRASHNA_DATA_DIR`, and `PRASHNA_UPLOADS_HOST_DIR` overrides. Here
+`PRASHNA_DATA_DIR` is the host folder mounted at `/data`; it is a Compose
+variable, unrelated to the `prashna` command's `PRASHNA_DATA_DIR`. Production
+keeps the `/opt/prashna` defaults.
+
+## Logs and retention
+
+The app writes operator diagnostics to the container log stream. Inspect them
+with:
+
+```bash
+cd /opt/prashna && docker compose logs -f prashna
+```
+
+Keep at least 7 days of application logs on the host or in your external log
+shipper. Configure that retention in Docker, journald, or the server's logging
+stack; Prashna emits safe diagnostic context but does not own log rotation.

prashna-0.2.0/distribution/README.md

@@ -0,0 +1,118 @@
+# Prashna local distribution
+
+This bundle runs the published Prashna container on a laptop or a small
+self-hosted machine. It is separate from the Hetzner production configuration.
+
+## Start
+
+1. Install Docker Desktop or Docker Engine with the Compose plugin.
+2. Start Prashna and wait for its health check:
+
+   ```bash
+   docker compose up -d --wait
+   ```
+
+3. On a fresh install, find the one-time setup link in the log:
+
+   ```bash
+   docker compose logs prashna | grep setup=
+   ```
+
+4. Open <http://127.0.0.1:8000/> plus the `/#setup=...` path from the log,
+   and choose the admin's username and password. The link works once.
+
+No `.env` is needed. The cookie-signing key is generated into the data volume
+on first start. To change the port or bind address, pin a version, or set
+optional values, copy `compose.env.example` to `.env`; the file describes each
+setting.
+
+The database and uploads live in the Compose named volumes `prashna-data`
+(mounted at `/data`) and `prashna-uploads` (mounted at `/app/uploads`). They
+survive container replacement.
+
+## Start without Compose
+
+The image also runs on its own:
+
+```bash
+docker run -d --name prashna -p 127.0.0.1:8000:8000 \
+  -v prashna-data:/data -v prashna-uploads:/app/uploads \
+  ghcr.io/kvsankar/prashna
+docker logs prashna 2>&1 | grep setup=
+```
+
+## Upgrade
+
+The release bundle pins `PRASHNA_IMAGE_TAG` to its version. Upgrade only after
+reading the release notes, then change the tag in `.env` and run
+`docker compose pull` and `docker compose up -d --wait`.
+
+## Registry access
+
+Anonymous pulls work only while the `prashna` container package is set to
+**Public** in GitHub Packages. That setting belongs to the GitHub account, not
+to the repository workflow. While the package is private, authorized users
+first sign in with a GitHub token that has `read:packages`:
+
+```bash
+echo "$GHCR_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_LOGIN --password-stdin
+```
+
+Do not put the token in `.env`; that file is passed to Compose and is for
+application configuration only.
+
+## Share temporarily with ngrok
+
+Set `PRASHNA_TRUSTED_PROXY_HOPS=1` in `.env`, restart with
+`docker compose up -d`, and run:
+
+```bash
+ngrok http 8000
+```
+
+The ngrok URL is public. Stop ngrok when the session is over.
+
+## Backup
+
+The database and uploads live in Docker named volumes. This command creates a
+consistent archive inside the container, including SQLite WAL state and all
+uploads:
+
+```bash
+mkdir -p backups
+name="prashna-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
+docker compose exec -T prashna python -m prashna.backup create "/data/$name"
+docker compose cp "prashna:/data/$name" "backups/$name"
+docker compose exec -T prashna rm "/data/$name"
+```
+
+Keep backup archives outside the Docker volumes.
+
+## Restore
+
+Restore replaces the database and uploads. The command creates an additional
+pre-restore archive beside the staged archive before changing anything.
+
+```bash
+archive=prashna-YYYYMMDDTHHMMSSZ.tar.gz
+docker compose cp "backups/$archive" "prashna:/data/$archive"
+docker compose stop prashna
+docker compose run --rm --no-deps prashna \
+  python -m prashna.backup restore "/data/$archive" --confirm
+docker compose start prashna
+docker compose exec -T prashna rm "/data/$archive"
+```
+
+After restoring, open <http://127.0.0.1:8000/api/admin/status> and confirm the
+expected session data. Copy the reported `prashna-pre-restore-*.tar.gz` out of
+the container before deleting it.
+
+## Useful commands
+
+```bash
+docker compose ps
+docker compose logs -f prashna
+docker compose restart prashna
+docker compose down                 # keeps named volumes
+docker compose down --volumes       # DELETES database and uploads
+```

prashna-0.2.0/performance/README.md

@@ -0,0 +1,119 @@
+# Performance measurement
+
+Measure Prashna at three separate layers:
+
+1. `Server-Timing: app;dur=...` isolates FastAPI application time.
+2. Browser navigation and resource timing captures cold/repeat loads,
+   transfers, protocols, paint milestones, and the application-defined
+   `prashna-usable` milestone.
+3. Structured application logs identify slow or state-changing requests
+   without storing credentials, participant identity, session URLs, or Q&A
+   content.
+
+`measure.py` records the browser layer plus the server timing, five slowest
+resources, transfer sizes, protocol, navigation type, and Cloudflare colo.
+Reports are JSON so runs can be compared in CI or retained as release evidence.
+
+Build the frontend and install Chromium before measuring a local server:
+
+```bash
+npm run build
+uv run playwright install chromium
+uv run python performance/measure.py \
+  --base-url http://127.0.0.1:8000 \
+  --session-code ABC123 \
+  --runs 5 \
+  --output /tmp/prashna-perf.json
+```
+
+For production, save a baseline and compare the same routes after a change:
+
+```bash
+uv run python performance/measure.py \
+  --base-url https://prashna.sankara.net \
+  --session-code ABC123 \
+  --budget performance/budgets.json \
+  --output /tmp/prashna-before.json
+
+uv run python performance/measure.py \
+  --base-url https://prashna.sankara.net \
+  --session-code ABC123 \
+  --baseline /tmp/prashna-before.json \
+  --max-regression-percent 20 \
+  --budget performance/budgets.json \
+  --output /tmp/prashna-after.json
+```
+
+Use repeated samples from the same machine and network. Do not compare one
+cold browser run with one warm run or infer browser speed from server timing
+alone. Production budgets are intentionally broad enough for normal network
+variation; baseline comparison provides the more sensitive release signal.
+Every measured page must emit the usable milestone; a fast error or incomplete
+boot therefore cannot pass merely because network activity stopped.
+With the default five samples, release gates use browser/transfer medians and
+application-time p95. Browser p95 remains in every report for diagnosis, but
+needs at least 20 samples before it is a useful percentile rather than nearly
+the single slowest request.
+
+Optional authenticated measurements read secrets from environment variables
+without writing them to reports:
+
+```bash
+uv run python performance/measure.py \
+  --base-url https://prashna.sankara.net \
+  --session-code ABC123 \
+  --moderator-key-env PRASHNA_PERF_MOD_KEY \
+  --route moderator=/m/ABC123
+```
+
+For an admin page, pass both `--admin-username-env` and
+`--admin-password-env`. Never put credentials or moderator keys directly in a
+command, report, or committed file.
+
+## Interpret high variance
+
+Do not infer browser performance from application timing or one public request.
+When `Server-Timing` stays low but navigation varies, separate these fault
+domains:
+
+- client access network and ISP;
+- client-to-Cloudflare ingress routing;
+- Cloudflare edge and cache behavior;
+- Cloudflare-to-Hetzner origin routing; and
+- nginx, FastAPI, SQLite, and host capacity.
+
+Capture several successful and failed samples from the same machine and
+network. Record UTC time, client ISP/ASN, `CF-RAY`, `CF-Cache-Status`, negotiated
+protocol, cURL phase timings, and MTR/traceroute output. Compare against an
+unrelated control host during the same interval.
+
+For Cloudflare routing, compare `https://prashna.sankara.net/cdn-cgi/trace`
+with Cloudflare control endpoints from the same connection. Different `colo`
+values are possible because anycast selection is destination-prefix-specific;
+the value is not simply the geographically nearest data center. A different
+colo explains the path selection, but does not by itself prove the cause of
+latency variance. Correlate it with timestamped timings, Ray IDs, packet loss,
+and path traces.
+
+There is no zone setting that pins client ingress to a particular Cloudflare
+colo. Argo Smart Routing affects the edge-to-origin path, not client-to-edge
+selection. Keep the hostname proxied unless collected evidence shows the proxy
+itself is the regression. The nginx visitor-IP and HTTP/2 setup and the
+HTML-shell cache rule are described in
+[`deploy/README.md`](../deploy/README.md#cloudflare-visitor-ip-and-http2).
+
+## Release verification
+
+For a performance-sensitive release:
+
+1. Run lint and the full automated suite.
+2. Save a pre-release JSON report when practical.
+3. Deploy and verify the intended immutable image revision.
+4. Check container health, `/api/admin/status`, and a direct static page.
+5. Repeat the browser measurement from the same location and network.
+6. Confirm HTTP/2 or HTTP/3, immutable compressed assets, page-shell cache
+   behavior, API `no-store`, and `Server-Timing`.
+
+Five-run gates use browser and transfer medians plus application p95. Retain
+browser p95 for diagnosis, but use at least 20 samples before treating it as a
+meaningful tail percentile.