docs(quick-260619-jp4): add app screenshots to README

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 14:24:33 -04:00
parent 23dc3cdd3f
commit cf9e345b87
3 changed files with 102 additions and 1 deletions
@@ -0,0 +1,50 @@
+---
+quick_id: 260619-jp4
+slug: add-app-screenshots-to-readme
+status: complete
+date: 2026-06-19
+---
+
+# Quick Task 260619-jp4: Add app screenshots to README
+
+## Goal
+
+Add real screenshots of the running FamilySync PWA to the README, organized into
+a **Features** section that expands on the top-line project description (per user
+follow-up: "the screenshots should go in some sort of features section that
+expands on the description").
+
+## Approach
+
+1. Drive the live dev app (Vite :5173 + API :3000, dev-auth-bypass) with
+   `playwright-cli` (Chromium) and capture six views: Calendar, Lists index,
+   List detail, Login, Setup wizard, Admin.
+2. The live instance has only one seeded event and one list — too sparse to
+   showcase. Per the user's decision (AskUserQuestion: "Mock locally"), populate
+   the views by intercepting API responses in the browser with `playwright-cli
+   route` (no writes to the real Fastmail account):
+   - `/api/me` → friendly member "Jordan" (blue), admin, setup not needed
+   - `/api/events` → a full June 2026 month of color-coded personal + family events
+   - `/api/lists` + `/api/lists/*/items` → four lists, a stocked grocery list
+   - `/api/admin/members` + `/api/admin/calendars` → two-person household
+   - `/api/setup/status` → `setupComplete:false` so the wizard renders
+3. Save final PNGs to `docs/screenshots/`.
+4. Rewrite the README "What It Does" bullets into a "## Features" section with
+   one screenshot per capability and expanded prose.
+
+## Tasks
+
+- [x] Capture six screenshots into `docs/screenshots/` via playwright-cli (mocked data)
+- [x] Replace README "What It Does" with a "Features" section embedding the screenshots
+- [x] Pass local CI gates (prettier, markdownlint)
+
+## Files
+
+- `docs/screenshots/*.png` (new — 6 images)
+- `README.md` (Features section)
+
+## Verify
+
+- `pnpm exec prettier --check README.md` → clean
+- `pnpm md:lint` → 0 errors (MD033 inline-HTML active → pure-markdown images only)
+- Images resolve at `docs/screenshots/<name>.png` relative paths
@@ -0,0 +1,50 @@
+---
+quick_id: 260619-jp4
+slug: add-app-screenshots-to-readme
+status: complete
+date: 2026-06-19
+---
+
+# Quick Task 260619-jp4 — Summary
+
+## What was done
+
+Added six real screenshots of the running PWA to `docs/screenshots/` and rebuilt
+the README intro into a **Features** section that expands the project description,
+pairing each capability with its screenshot:
+
+| View | File | Feature |
+| --- | --- | --- |
+| Calendar (month) | `calendar.png` | One color-coded family calendar |
+| Lists index | `lists.png` | Shared collaborative lists |
+| List detail | `list-detail.png` | Live-syncing list items |
+| Login | `login.png` | Single sign-on (local + Authelia OIDC) |
+| Setup wizard | `setup.png` | Guided zero-setup onboarding |
+| Admin | `admin.png` | Household administration |
+
+## How
+
+Captured with `playwright-cli` (Chromium — the box has no Google Chrome) against
+the live dev stack. Demo data was injected per-browser via `playwright-cli route`
+response interception — **nothing was written to the real Fastmail account**
+(user chose "Mock locally"). Screens that fight the dev-bypass authed/locked
+state were unlocked by mocking `/api/me`, `/api/setup/status`, and the auth/admin
+endpoints. Login and Setup were reframed at a 1280×720 viewport to remove dead
+vertical space; the content views at 1280×900.
+
+## Notes / honest caveats
+
+- The list-detail header literally reads "List", not the list name — that is the
+  app's own placeholder (`apps/pwa/src/routes/ListDetail.tsx:380`, "List name not
+  available without an extra fetch"), not a screenshot artifact. Left as-is rather
+  than faking the real UI.
+- The color-legend in the sidebar shows the current member + "Family" by design
+  (`App.tsx` derives legend members from `/api/me` only); the two-person household
+  is shown on the Admin members screen.
+
+## Verification
+
+- `pnpm exec prettier --check README.md` → "All matched files use Prettier code style!"
+- `pnpm md:lint` → Summary: 0 error(s) (12 files)
+- Images committed under `docs/screenshots/` (not gitignored); README references
+  resolve via relative paths.