docs(readme): refresh features, fix accuracy nits, strengthen story (#464)

* docs(readme): refresh features, fix accuracy nits, strengthen story

- Sync Features list with shipped app: My Festival (Want to try / Tasted),
  tasting notes; surface accessibility and offline caching as differentiators
- Add intro framing the app for real festival conditions
- Fix accuracy nits: pin Flutter 3.44.0 (drop "or later"), use self-bootstrapping
  ./bin/mise install, make drink list consistent across the doc
- Point Contributing at the development guide, AGENTS.md, and the check gate
- Add a Screenshots section with a placeholder for device shots

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017GurzXkAkKjYF1GUdSEze8

* docs: consolidate deployment detail into ci-cd.md

The README duplicated the deployment mechanism already documented in
docs/processes/ci-cd.md, and the two had drifted. Trim the README's
Deployment section to a trigger→target summary plus links, keeping the
authoritative detail in ci-cd.md.

Also fix the stale preview/staging URLs in ci-cd.md: PR previews and
staging are served from the `staging-cambeerfestival` Pages project
(`<branch>.staging-cambeerfestival.pages.dev`, staging.cambeerfestival.app),
not `cambeerfestival.pages.dev`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017GurzXkAkKjYF1GUdSEze8

* docs: address review — clarify mise prereq and fix deploy action name

- README: state Flutter is installed by ./bin/mise and a global mise is
  optional; drop the now-redundant separate mise prerequisite bullet
- ci-cd.md: the staging/preview deploy uses cloudflare/wrangler-action@v4
  (wrangler pages deploy), not cloudflare/pages-action@v1

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017GurzXkAkKjYF1GUdSEze8

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: richardthe3rd

README.md

@@ -9,7 +9,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Play Store](https://img.shields.io/badge/Google_Play-414141?logo=google-play&logoColor=white)](https://play.google.com/store/apps/details?id=ralcock.cbf)
 
-A Flutter app for browsing beers, ciders, meads, and more at the Cambridge Beer Festival.
+A Flutter app for browsing, searching, and rating the beers, ciders, perries, meads, and wines on offer at the Cambridge Beer Festival — on Android, iOS, and the web.
+
+Built for real festival conditions: the drinks list is cached so it keeps working when the venue network drops, and every screen is built with screen-reader semantics and keyboard/touch accessibility in mind.
 
 **Production**: [cambeerfestival.app](https://cambeerfestival.app)
 **Staging**: [staging.cambeerfestival.app](https://staging.cambeerfestival.app)
@@ -18,23 +20,37 @@ A Flutter app for browsing beers, ciders, meads, and more at the Cambridge Beer
 
 ## Features
 
-- 🍺 Browse all drinks from the festival (beers, ciders, perry, mead, wine)
+- 🍺 Browse all drinks from the festival (beer, cider, perry, mead, wine, and more)
 - 🔍 Search by name, brewery, or style
 - 🏷️ Filter by drink category and style
 - ↕️ Sort by name, ABV, brewery, or style
 - 👁️ Hide unavailable drinks (sold out or not yet available)
-- ❤️ Save favorites for easy access
-- ⭐ Rate drinks (1-5 stars)
+- 📋 Build your **My Festival** list — mark drinks "Want to try", then "Tasted"
+- ⭐ Rate drinks (1–5 stars) and jot personal tasting notes
 - 🏭 View brewery details and all their drinks
+- ♿ Accessibility-first: screen-reader semantics on every interactive element
+- 📶 Cached data keeps browsing usable when the festival network is patchy
 - 📱 Works on Android, iOS, and Web
 
+## Screenshots
+
+<!--
+  TODO: add screenshots. Drop images under docs/assets/ (e.g. drinks-list.png,
+  drink-detail.png, my-festival.png) and reference them here, for example:
+
+  | Drinks list | Drink detail | My Festival |
+  |---|---|---|
+  | ![Drinks list](docs/assets/drinks-list.png) | ![Drink detail](docs/assets/drink-detail.png) | ![My Festival](docs/assets/my-festival.png) |
+-->
+
+_Screenshots coming soon — try the live app at [cambeerfestival.app](https://cambeerfestival.app)._
+
 ## Getting Started
 
 ### Prerequisites
 
-- [Flutter SDK](https://docs.flutter.dev/get-started/install) (3.44.0 or later)
+- **Flutter SDK 3.44.0** — pinned and installed for you by `./bin/mise` (the repo ships this wrapper, so a global [mise](https://mise.jdx.dev/) install is optional)
 - Android Studio, Xcode, or VS Code with Flutter extensions
-- (Optional) [mise](https://mise.jdx.dev/) for automatic tool version management
 
 ### Installation
 
@@ -43,8 +59,9 @@ A Flutter app for browsing beers, ciders, meads, and more at the Cambridge Beer
 git clone https://github.com/richardthe3rd/cambridge-beer-festival-app.git
 cd cambridge-beer-festival-app
 
-# Install tools (Flutter 3.44.0, Node, etc.)
-mise install
+# Install tools (Flutter 3.44.0, Node, etc.) — ./bin/mise self-bootstraps,
+# so you don't need mise installed globally
+./bin/mise install
 
 # Install Dart dependencies and verify setup
 ./bin/mise run check
@@ -157,35 +174,26 @@ Technical documentation is available in the [docs](docs/) directory - see [docs/
 
 ## Deployment
 
-The app is deployed to multiple environments:
-
-- **Production** (Cloudflare Pages): [cambeerfestival.app](https://cambeerfestival.app)
-  - Deployed on version tags (e.g., `v2025.12.0`)
-  - Uses Cloudflare Pages project `cambeerfestival`, branch `release`
-  - Workflow: `.github/workflows/release-web.yml`
-- **Staging** (Cloudflare Pages): [staging.cambeerfestival.app](https://staging.cambeerfestival.app)
-  - Stable staging environment
-  - Deployed automatically on push to `main`
-  - Uses Cloudflare Pages project `staging-cambeerfestival`, branch `main`
-  - Workflow: `.github/workflows/ci.yml` (deploy-web-preview job)
-- **PR Previews** (Cloudflare Pages): Unique URL per pull request
-  - Each PR gets its own preview environment (e.g., `<branch>.staging-cambeerfestival.pages.dev`)
-  - Preview URL posted as comment on the PR
-  - Workflow: `.github/workflows/ci.yml` (deploy-web-preview job)
+| Trigger | Lands on |
+|---|---|
+| Push to `main` | Staging — [staging.cambeerfestival.app](https://staging.cambeerfestival.app) |
+| Open a pull request | A unique per-PR preview (`<branch>.staging-cambeerfestival.pages.dev`), posted as a comment on the PR |
+| Push a version tag (e.g. `v2025.12.0`) | Production — [cambeerfestival.app](https://cambeerfestival.app) |
 
-### Deployment Strategy
+The app is hosted on Cloudflare Pages, with the API served by a Cloudflare Worker. For the full detail — every workflow, the Pages projects, and the release train:
 
-1. **Development changes**: Push to `main` → Staging (Cloudflare Pages)
-2. **PR reviews**: Open PR → Unique Cloudflare Pages preview created
-3. **Production releases**: Create tag (e.g., `v2025.12.0`) → Production deployment to cambeerfestival.app
+- [CI/CD](docs/processes/ci-cd.md) — each workflow and deploy job
+- [Cloudflare Pages Setup](docs/tooling/cloudflare-pages.md) — deployment configuration
+- [Release Guide](docs/processes/release.md) — version bumping, branching, and tagging
 
-For the full release process (version bumping, branching, tagging), see the [Release Guide](docs/processes/release.md).
+## Contributing
 
-For deployment setup and configuration, see [Cloudflare Pages Setup Guide](docs/tooling/cloudflare-pages.md).
+Contributions are welcome! Before opening a pull request, please read:
 
-## Contributing
+- [Development Guide](docs/processes/development.md) — setup, workflows, and conventions
+- [AGENTS.md](AGENTS.md) — architecture, code style, testing, and accessibility standards (written for AI agents, but the rules apply to everyone)
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Run `./bin/mise run check` (generate → analyze → test) before every commit, and follow [Conventional Commits](https://www.conventionalcommits.org/) for commit and PR titles.
 
 ## License
 

docs/processes/ci-cd.md

@@ -116,18 +116,20 @@ Deploys to **Cloudflare Pages** (staging and PR previews).
 
 **Runs when**: `needs.changes.outputs.app == 'true'`
 
+Uses the Cloudflare Pages project `staging-cambeerfestival`.
+
 **Environments:**
-- **Staging**: `main.cambeerfestival.pages.dev` (push to `main`)
+- **Staging**: `https://staging.cambeerfestival.app` (custom domain; push to `main`)
 - **PR Previews**: Unique URL per PR (pull requests)
 
 **Steps:**
 1. Download `web-build` artifact
-2. Deploy to Cloudflare Pages using `cloudflare/pages-action@v1`
+2. Deploy to Cloudflare Pages using `cloudflare/wrangler-action@v4` (`wrangler pages deploy build/web --project-name=staging-cambeerfestival --branch=<head-ref>`)
 3. Comment PR with preview URL (if PR)
 
 **Preview URL Format:**
-- PR: `https://<pr-branch>.cambeerfestival.pages.dev`
-- Staging: `https://main.cambeerfestival.pages.dev`
+- PR: `https://<pr-branch>.staging-cambeerfestival.pages.dev`
+- Staging: `https://staging.cambeerfestival.app` (also reachable at `https://main.staging-cambeerfestival.pages.dev`)
 
 ---