# AGS Math — Flutter app

K-P6 Singapore Math curriculum, IRT-based adaptive learning, SIMBA telco
partnership. Backend lives at mathapi.allgifted.com (separate Laravel repo).

## Git workflow — read this before any commit

This repo is worked across multiple machines (work laptop, home Windows PC,
and the production server via SSH). Divergent-branch incidents have happened
seven times. The rules below prevent recurrence.

**Rule 1: Start every session by checking remote state.**

Before any work, run:

    git fetch origin
    git status

Possible states and what to do:
- "up to date" → safe to work
- "behind" → `git pull` before any local changes
- "ahead" → investigate why; probably forgot to push from another machine
- "diverged" → STOP and report to user before doing anything

**Rule 2: Never commit on the production server.**

Production SSH sessions are for `git pull`, .env edits, cache clears,
service restarts, and log reading. Don't `git add` or `git commit` on prod.
Production consumes commits; it does not author them.

**Rule 3: Long work goes on a feature branch, not master.**

For any work spanning more than one commit (Phase 0 hardening, Phase 1.5
cleanup, etc.), branch first:

    git checkout -b phase-X-description

Push to that branch, merge to master via PR or after explicit approval.
This bounds the blast radius of any cross-machine divergence.

**Rule 4: Push before walking away from a machine.**

If work is unfinished, commit as WIP and push anyway:

    git commit -am "wip: short description"
    git push origin <branch>

Better a messy WIP commit on remote than work that goes missing because
another machine got there first.

**Rule 5: Don't force-push to master.** Ever. Without explicit user
confirmation per push.

## Project conventions

### Brand — canonical, do not drift

- **Product name**: **AGS Math** (Latin script, all languages and locales).
  - Full form: **"AGS Math — The Singapore Method"**.
  - Use the short form "AGS Math" everywhere display-side.
  - Do NOT use "All Gifted Math", "AllGifted Math", "Ag Math", "AG Math",
    or any localized translation of the product name. The product is
    "AGS Math" in every locale, including ZH/ID/MS/etc.
  - **Future Claude sessions must not revert "AGS Math" to "All Gifted Math"** —
    that earlier convention is superseded.
- **Company name**: **"All Gifted"** (two words, always) — the parent
  organization that publishes the AGS Math product. Use only when
  referring to the company itself, never as the product name.
- **Slugs / identifiers**: the Dart package slug `ag_math` and the binary
  filenames (`ag_math.exe`, `ag_math.app`) are intentionally retained —
  they are not user-visible. Only display strings are governed by the
  canonical brand rule above.

### Other conventions

- **Accreditation**: "ACS WASC" and "MSA-CESS" — full names, never just "WASC" or "MSA"
- **AGS founding date**: 2014 (NOT 2018 — the latter has been wrong in old copy)
- **Brand colors**: Crimson #960000, Gold #BF9237, Lime #88C808, Steel Blue #4A6488, Dusty Rose #D0ACAC
  - Primary brand pair: Crimson #960000 + Gold #BF9237

## Architecture notes

- Frontend: Flutter (this repo), targets web + iOS + Android
- Backend API base URL: configured via --dart-define=API_BASE_URL at build time
  - Local dev: http://localhost:8000 (or 10.0.2.2:8000 on Android emulator)
  - Production: https://mathapi.allgifted.com
- Stripe publishable key: configured via --dart-define=STRIPE_PUBLISHABLE_KEY
- Mail / payments / auth flow through the Laravel backend, not Firebase

## Current work-in-progress context

- Phase 1.5 frontend cleanup landed on `1.5-cleanup` branch (commits
  172a8ae through cd0f685); awaiting reconciliation with `origin/master`
  before merge.
- FE2-FE5 work is gated on backend Stage A (BE1-BE5) landing in production
- X-Client-Version format is now `semver+build` (e.g. `1.4.0+2`), driven by
  package_info_plus. Backend version-gating logic must parse only up to `+`.

## When in doubt

Ask the user before destructive operations: force-push, branch deletion,
git reset --hard, history rewrites, mass file deletions.