Keep Feature Docs Up To Date

Use this checklist whenever a UI feature is added, renamed, or improved. The goal is simple: if the app changes, the FAQ should show the real workflow, use current product language, and include screenshots for the main pages and modals a prospect or staff member needs to understand.

What We Updated In This Documentation Sweep

This sweep moved the FAQ closer to the current product:

• Reworked the feature overview so live features are no longer described as coming soon.
• Added Progress Tracking docs and screenshots for the progress workspace and member progress entry flow.
• Updated Calendar & Booking to cover personal training, classes, blocked time, non-training sessions, and Google Calendar sync.
• Added Payment Issues coverage inside Invoice Management and a dedicated Payment Issues how-to.
• Added household sharing and payer behavior documentation with household admin and sharing modal screenshots.
• Added a Google Calendar Sync how-to for trainers and instructors, including the connected-state panel.
• Added a dedicated Public Class Calendar how-to so the public schedule feature is searchable and sidebar-accessible.
• Corrected User Management docs to match the current owner, admin, trainer, and member roles.
• Updated billing/payment wording from Stripe-only language to Stripe or Clover where member card processing is discussed.
• Added screenshots for custom invoice creation, invoice action modals, member portal pages, member payment method modals, membership payment/discount/billing-date modals, trainer workspace pages, trainer pay rates, payroll rate editing, payroll custom lines, class scheduling, invoice activity notes, linked sessions, fixed-weekly buckets, progress tracking, household sharing, payment issues, cancellation preview, create/edit user, document assignment, signed-document upload, and document upload/edit modals.
• Updated landing page payment copy so it matches current Stripe and Clover support.

Coverage Log

This is the practical record of what changed during the sweep and where future updates should start.

Workstream	What Changed	Primary Files
Prospect navigation	Reworked the left sidebar so new prospects start with the product walkthroughs before deeper support pages. Internal maintenance docs stay searchable without crowding the first impression.	faq/sidebars.ts
Product walkthroughs	Added or expanded how-to pages with screenshots for memberships, member portal, PT booking, classes, invoices, payment issues, payroll, documents, household sharing, Google Calendar sync, trainer workspace, and public calendar.	faq/docs/how-to/*
Feature explanations	Updated the main feature pages so they describe the current app instead of older or planned behavior.	faq/docs/features/*
Billing rules	Updated fixed-weekly, pause/resume, cancellation, smart refund, and invoice audit trail explanations to match the hardened product rules.	faq/docs/credit-system/*, faq/docs/finance/*
Demo state	Added a repeatable seed script so the docs can show realistic people, prices, memberships, invoices, household relationships, and payment issues.	scripts/seed-feature-docs-demo.mjs
Screenshot automation	Added repeatable Playwright captures for the main pages, modals, panels, and audit examples used by the FAQ and landing pages.	playwright/demos/faq-screenshot-sweep.demo.ts
Shared images	Saved generated screenshots in the FAQ image folder and copied shared marketing/docs images to the landing site.	faq/static/img/screenshots, landing/public/screenshots
Marketing alignment	Updated landing/payment wording where the public site needed to match current Stripe and Clover support.	landing/src/*

The latest source files for this sweep are:

• scripts/seed-feature-docs-demo.mjs
• playwright/demos/faq-screenshot-sweep.demo.ts
• faq/docs/how-to/keep-feature-docs-up-to-date.md
• faq/docs/how-to/connect-google-calendar-sync.md
• faq/docs/how-to/manage-household-membership-sharing.md
• faq/docs/how-to/review-payment-issues.md
• faq/docs/features/*
• faq/docs/finance/*
• faq/docs/credit-system/*

What This Sweep Now Covers

The FAQ is now organized around the main product areas a new prospect or staff member needs to understand:

Area	What Was Documented
Getting started	Cleaner starting path, member creation, user roles, payment setup, documents, memberships, booking, invoices, payroll
Memberships	Add memberships, payment method changes, discounts, billing-date edits, household sharing, pause, resume, cancellation
Fixed-weekly credits	Monthly billing with weekly buckets, first-cycle proration, pause/resume, cancellation boundary handling, smart refunds, invoice audit trails
Calendar and booking	Personal training booking, class setup, class scheduling, public class calendar, booking hours, blocked/non-training time, Google Calendar sync
Classes	Weekly templates, apply-template behavior, attendance, member booking, waitlist, public calendar publishing
Finance	Invoice history, invoice detail, activity notes, linked sessions, custom invoices, payment issues, refunds, line items, one-off billing date and payment edits
Payroll	Trainer rates, payroll review, custom billing lines, payroll run workflow
Trainer workspace	Trainer dashboard, trainer calendar, client/member list, own documents, Google Calendar sync
Member portal	Member dashboard, current memberships, public membership purchase, saved payments, booking history, account documents
Users and households	Create/edit users, household admin, dependent members, household membership sharing and payer behavior
Documents	Document upload, edit, assignment, signed document upload, required/hidden document behavior
Progress	Progress workspace and member progress entry flow
Landing copy	Payment-provider language updated so marketing copy matches current Stripe and Clover support

Current Update System

Use this system when the UI changes:

1. Seed or update realistic demo data. For shared household/payment issue examples, run:

set -a
source playwright/demo.config.dev
source playwright/demo.config.local
set +a
AWS_REGION=us-east-1 node scripts/seed-feature-docs-demo.mjs

2. Capture screenshots from the dev demo gym. The FAQ sweep writes screenshots into landing/public/screenshots and copies them to faq/static/img/screenshots.

cd playwright
DEMO_BASE_URL=https://do7l4n1ptt3iz.cloudfront.net DEMO_GYM_ID=demo npx playwright test -c demo.playwright.config.ts --grep "faq screenshot sweep"

3. Update the docs that match the UI surface. Feature docs explain what exists, how-to docs show the workflow, and credit/billing explanation docs capture product rules.

4. Build and search for stale language before shipping. The FAQ should not mention removed labels, old payment-provider assumptions, or outdated product rules.

5. Decide whether the page belongs in the sidebar. The sidebar should stay prospect-first. Add pages that help a new buyer understand the platform quickly. Keep internal maintenance pages searchable and direct-linkable when they are useful for the team but noisy for prospects.

Update Path By Change Type

Not every UI change needs the same amount of documentation work. Use the smallest path that keeps the docs truthful.

Change Type	Required Update
Label, button, or copy change	Search faq/docs and landing/src for the old label, update screenshots if the old label is visible, then build the FAQ.
Visual/layout change only	Refresh the affected screenshots if the page looks meaningfully different. No rule doc update is needed unless the workflow changed.
New modal, drawer, tab, or page	Add the screenshot capture, reference the screenshot from the matching how-to, and decide whether the page should be in the sidebar.
New staff/member workflow	Add or update a how-to with exact steps, screenshots, and role-specific language. If the workflow needs special data, update the seed script.
Billing, credits, pause, resume, cancellation, refund, payroll, or permissions change	Update the how-to, the feature page, and the explanation page. Confirm the backend rule before documenting the behavior.
Marketing-visible feature improvement	Update docs first, then landing/social copy. The public claim should link to a page that shows the real workflow.

Ongoing Gaps To Watch

These are the areas that should be checked when the app or demo account changes:

• Member-only portal screenshots should continue to use real member auth. Owner/admin views are useful for staff workflows, but they are not a substitute for the member experience.
• Trainer client-detail screenshots should be refreshed when the demo trainer account has a visible trainer/client relationship.
• Any new main modal should be added to the screenshot sweep before the docs reference it.
• Any change to fixed-weekly rules should be checked against first-cycle proration, bucket end-date assignment, pause/resume previews, cancellation boundaries, refunds, and invoice activity notes.

Update The Right Artifacts

Use this table when a UI change lands:

UI Change	Update These Files
New page, tab, or workflow	Add/update a how-to in faq/docs/how-to, add screenshots, and decide whether faq/sidebars.ts should expose it.
New modal, drawer, or panel	Add a repeatable capture in playwright/demos/faq-screenshot-sweep.demo.ts, then reference it from the matching how-to or feature page.
Billing, credit, refund, pause, resume, cancellation, or payroll rule	Update the how-to plus the relevant explanation page in faq/docs/credit-system or faq/docs/finance.
New demo state needed for screenshots	Add realistic members, memberships, invoices, payment methods, sessions, or integration state to scripts/seed-feature-docs-demo.mjs.
Label rename or copy change	Search for the old phrase in faq/docs and landing/src, update screenshots if the label is visible.
Marketing-visible feature	Update the feature/how-to docs first, then update any landing or social copy that links deeper into those docs.

Do not treat screenshots as decoration. If a modal is important enough to explain, it should be regenerated by the sweep.

Source Files For The System

These are the files that keep the documentation repeatable:

File	Purpose
scripts/seed-feature-docs-demo.mjs	Creates realistic demo members, memberships, household sharing, and payment issue examples.
playwright/demos/faq-screenshot-sweep.demo.ts	Captures current screenshots from the dev demo gym.
faq/static/img/screenshots	FAQ screenshot assets.
landing/public/screenshots	Landing-page screenshot assets.
faq/sidebars.ts	Controls what appears in the left sidebar. Keep prospect-first pages here; keep maintenance/internal docs searchable but off the main path.
faq/docs/how-to/keep-feature-docs-up-to-date.md	This maintenance checklist.

Documentation Types

Use the right kind of page for the job.

Type	Use It For	Example
Feature overview	What the feature does and why it exists	Calendar & Booking, Membership Management
How-to guide	Exact staff workflow with screenshots	Book a PT session, Run Trainer Payroll
Explanation	Product rules and edge cases	Weekly credits, smart refunds, pause/resume
Marketing guide	Search-friendly problem/solution article	Reward consistency with weekly memberships

Most meaningful UI changes need at least one how-to update. If the change affects rules, billing, credits, payroll, or permissions, update the explanation page too.

UI Change Checklist

When a feature changes, work through this list:

1. Identify the real UI entry point. Example: Finance -> Payment Issues, Manage Gym -> Settings, Calendar -> Personal Training.

2. Find the product rule behind the UI. Do not document only labels. For billing, credits, pauses, cancellations, payment methods, household sharing, and payroll, confirm what the backend actually does.

3. Update or create the feature overview. Keep this high-level and prospect-friendly.

4. Update or create the how-to guide. Include the exact steps staff or members follow in the app.

5. Update explanation docs for any rule changes. Fixed-weekly billing, credit bucket assignment, pause/resume, cancellation, refunds, payroll, and household sharing all need rule-level explanations.

6. Capture screenshots for every main page and main modal. Skip small confirmation dialogs unless the confirmation explains an important irreversible or billing-sensitive action.

7. Update landing page copy if the feature appears in marketing pages. Do not leave older provider names, unsupported workflows, or stale claims in landing/src.

8. Run stale-copy searches and builds. The docs should build and obvious old language should be gone.

9. Keep the screenshot sweep current. If a new main modal, drawer, or workflow panel is added, add a repeatable capture to playwright/demos/faq-screenshot-sweep.demo.ts instead of taking one-off manual screenshots.

10. Keep demo data realistic. If the workflow needs a special member, membership, invoice, payment issue, household, or staff integration state, add it to scripts/seed-feature-docs-demo.mjs so screenshots can be regenerated later.

Definition Of Done For A UI Feature Change

A UI feature or improvement is documented when all of these are true:

• The feature overview says what the feature is for and uses the current app labels.
• At least one how-to guide shows the exact path a staff member, trainer, or member follows.
• Screenshots exist for the main page state and every main modal, drawer, or workflow panel.
• Billing, credit, payroll, permission, household, or integration rules are explained on a rule-level page, not only inside a how-to.
• The screenshot sweep can regenerate the images without manual clicking.
• The demo seed script creates any special state the screenshots need.
• The left sidebar still gives a new prospect a clear starting path instead of exposing every internal maintenance page.
• FAQ and landing builds pass when those areas were touched.

For small visual-only UI changes, this can be a screenshot refresh and stale-copy search. For rule changes, it usually requires updates in feature docs, how-to docs, explanation docs, seed data, and screenshot automation.

Screenshot Rules

Screenshots should show what the platform feels like to use, not just prove a page exists.

• Capture main workspaces, table/detail views, and important modals.
• For modal screenshots, crop to the modal or a readable panel unless the surrounding calendar/table context matters.
• When context matters, keep a second screenshot with the modal over the calendar or page background.
• Keep modal images small enough that readers do not need to scroll past a giant screenshot.
• Hide debug-only UI before capturing.
• Use real-looking names, realistic prices, and plausible dates.
• Use the correct role for role-specific screenshots. Owner/admin screenshots are acceptable for owner/admin workflows, but member-only pages should be captured with member auth and trainer-only pages should be captured with trainer or owner-as-trainer access.
• Save screenshots in both:
  • faq/static/img/screenshots
  • landing/public/screenshots when landing pages also use them

Use descriptive names:

feature-area-specific-view.png
payment-issues-dashboard.png
google-calendar-sync-connected.png
household-sharing-modal.png
fixedweekly-boundary-adjustment-preview.png

Do not reference a screenshot from a page until the image exists in faq/static/img/screenshots.

Fixed-Weekly Rule Checklist

Any change to fixed-weekly memberships should be checked against these docs:

• Weekly Credits with Monthly Billing
• Weekly Credits
• Predictable Billing Dates
• Pause & Resume
• Cancellation Policies
• Smart Refund Handling
• Invoice Audit Trails
• Check Pause and Resume Billing

For fixed-weekly updates, explicitly confirm:

• Weekly buckets are assigned to an invoice by the bucket end date during normal billing.
• The first cycle is prorated based on credits actually granted.
• Pause previews explain which invoices, buckets, and sessions are affected before staff confirms.
• Resume behavior explains whether a bridge invoice or adjusted next billing date is created.
• Cancellation behavior explains which future invoices are removed, which sessions are honored or cancelled, and how refunds are calculated.
• Invoice activity notes preserve the audit trail.

Main Modal Screenshot Checklist

When a feature area changes, check these main modals:

Area	Main Modals
Memberships	Create membership type, add membership, pause membership, resume confirmation, cancellation preview, update payment method, update discount, update fixed billing date, membership sharing
Calendar / PT	Create slot, book member, non-training session, reassign session, booking hours editor, non-training session type editor
Classes	Add class type, add weekly template session, apply template, class detail/attendance, add members, waitlist
Finance	Create custom invoice, refund invoice, edit invoice line items, edit billing date, invoice cleanup when relevant
Payroll	Edit trainer pay rates, create payroll, payroll detail adjustments
Documents	Upload document, assign document, edit document, fillable form review, signature/details review
Progress	Progress workspace, member progress entry
Integrations	Payment provider settings, Google Calendar sync connected/not connected
Trainer Workspace	Trainer dashboard, trainer calendar, trainer member/client list, trainer account integrations

Verification Commands

Run these before considering documentation current:

cd faq
npm run build

cd landing
npm run build

git diff --check

Run targeted stale-copy searches for the specific feature. Examples:

rg -n "Coming Soon|Stripe integration|Apple Calendar|Block Time|Bulk Import|Staff role" faq/docs landing/src -S

rg -n "fixedweekly|fixed-weekly|fixed weekly|pause|resume|cancel|refund" faq/docs/credit-system faq/docs/how-to -S

The search terms should change with the feature. If a UI label was renamed, search for the old label.

Also check that documented screenshots exist:

rg -o "/img/screenshots/[^)\" ]+" faq/docs --glob '!**/keep-feature-docs-up-to-date.md' | sed 's#.*:##; s#^/img/screenshots/##' | sort -u

Compare that output against faq/static/img/screenshots. Any missing image should be captured, renamed, or removed from the doc before the page ships.

Release Checklist

Before shipping a UI change, confirm:

• The feature page explains the workflow in plain language.
• The how-to page has current screenshots.
• Any product rules are documented in explanation pages.
• The landing page copy does not contradict the app.
• The FAQ build passes.
• The landing build passes when landing content or shared screenshots changed.
• The screenshot source script is updated so future screenshots can be regenerated.

If one of those is missing, the docs are not done yet.