# Workbook v1 — Spec & the case for its own home

*Scoping doc, not a build. Written the day we decided to stop layering "What's Best
For Us" on top of another domain. The Workbook — public accounts + real personal
data about real children — is the tipping point that earns this project its own
domain, repo, and database. This captures (a) the Workbook v1 design so it's ready
to build the moment the new home exists, and (b) exactly what moving there involves.*

Related: [07-playbook.md](07-playbook.md) · [08-workbook.md](08-workbook.md) (the concept) ·
`_mysql-wbfu-playbook.sql` (the tables, already created).

---

## Where things stand today

Built and working, currently living under `whatsbestfor.us/`:

- **Foundation** — DB-driven, admin CMS, private feedback inbox.
- **Playbook** — Skills + Tactics (many-to-many), admin CMS, a filterable 2-wide
  grid (age band + orbit ring), standalone lesson pages, and a comment/question/
  challenge widget on each lesson feeding the shared inbox.
- **Data** — `nodes` / `premises` / `comments`, `skills` /
  `tactics` / `skill_tactics`, and the **Workbook tables already created
  but unused**: `users`, `members`, `progress`.

Everything leans on shared, domain-specific infrastructure: `_config.php`,
`_global.php`, `_core.php` (the site-wide `Core` class), the `admin/` app, and
`post.php`. **That entanglement is the thing to unwind before the Workbook.**

---

## Workbook v1 — what it is

A per-person tracker: a registered user tracks **each family member's** progress
through the Playbook. The seam is one table — `progress` = one row per
**(member × skill)**. The Playbook is the person-agnostic catalogue; the Workbook
is where a real person meets it.

### Decisions locked (this session)

- **Tracking surface:** *lesson page **and** a Workbook hub.* Logged-in users mark
  progress right on the lesson page (the "Track your progress" CTA becomes real);
  `workbook.php` is the hub to manage people and see each person's board.
- **Progress depth for v1:** **status only** — `not_started` / `building` /
  `mastered`. The `bucket` (strength / build / mature), `is_focus`, and `notes`
  columns already exist but are **reserved for v2**.
- **Accounts:** intended as quick email + password (hashed, session login), but the
  final auth decision is deferred to the migration (see Open Questions) — because
  auth is the piece most coupled to "which domain/host is this."

### Core flows (v1)

1. **Sign up / log in / log out** — `users`, a public session (separate from
   the admin session).
2. **Manage family members** — add / edit / remove (`members`: name,
   birth_date → drives which lessons are age-relevant).
3. **Track from a lesson** — logged in, on `lesson.php`: *"Track for [member]"* →
   set status. Creates or updates the `progress` row.
4. **Workbook hub** — list members with quick counts (learning / mastered); open a
   member → their **board**: the lessons they have progress on, grouped by status,
   each with a status control and a remove. A link back to the Playbook to add more.

### Screens

| Screen | Route | Shows |
|---|---|---|
| Workbook (logged out) | `workbook.php` | Intro + register / login |
| Workbook (logged in)  | `workbook.php` | Member list + add member |
| Member board          | `workbook.php?member=ID` | That member's tracked lessons, grouped by status |
| Lesson enhancement    | `lesson.php?skill=uid` | Progress control per member when logged in; the "sign in to track" boilerplate when not |

### Data model (already created — recap)

- **`users`** — `uid`, `email` (unique), `password_hash`, `display_name`,
  `status` (pending/active/disabled), `reset_token` / `reset_expires`, timestamps.
- **`members`** — `user_id`, `name`, `birth_date`, `notes`, `sort`.
- **`progress`** — `member_id`, `skill_id`, `status` *(v1 uses this)*,
  `bucket` / `is_focus` / `notes` / `started_at` / `mastered_at` *(reserved for v2)*.
  `UNIQUE(member_id, skill_id)` keeps it one row per pairing.

### Endpoints (proposed — match the existing AJAX style)

A public API surface, mirroring how `post.php` / `admin/api.php` already work:

- `wb-register`, `wb-login`, `wb-logout`
- `wb-add-member`, `wb-update-member`, `wb-delete-member`
- `wb-set-progress` (member_id, skill_id, status) — upsert
- `wb-remove-progress` (member_id, skill_id)

Session: `$_SESSION['user']` = { id, expires }. **Every** progress/member query
is scoped by the logged-in `user_id` — never trust a `member_id` or `skill_id` from
the client without an ownership check.

### Security / correctness notes (for whoever builds it)

- `password_hash()` / `password_verify()` (the same pattern `admins` uses).
- Prepared statements throughout; ownership-scope every read and write.
- Regenerate the session id on login; honeypot field on the register form.
- Basic login rate-limiting.
- The admin already has a password-reset pattern to borrow when reset is added.

---

## Moving to its own home — what it takes

The Workbook is the right moment to separate, because it's the first thing that
stores accounts and data about real kids. Do the move **before** building it.

### What carries over cleanly

- The `whats-best-for-us/` pages (foundation, playbook, lesson, workbook, partials,
  assets, seeders, and the numbered concept docs).
- The `*` **table schemas** — they're self-contained and `uid`-anchored, so
  they migrate to a fresh DB with no rewrites.
- The admin CMS pages (`page-whatsbest.php`, `page-playbook.php`).
- The Docker setup is reusable as-is (PHP 8.1 + Apache + mysqli).

### What's entangled with this domain (to decouple)

- **`_core.php`** — the WBFU methods are mixed into the site-wide `Core` class.
  Extract them into a dedicated class/module (e.g. `Wbfu`).
- **`admin/`** — the WBFU admin lives inside this site's larger admin app (shared
  login, nav includes, `api.php` switch). The new home needs its own admin shell,
  or a clean carve-out of just the WBFU pages + methods + api cases.
- **`post.php`** — the `wbfu-comment` handler is one case in a shared switch;
  lift it out.
- **`_config.php` / `_global.php`** — shared DB creds, `BLOG_SECRET_KEY`, session
  bootstrap. New home gets its own config.
- **Database** — currently the shared `red_mc_web` DB. New home gets its own DB;
  the `*` tables move over intact.

### Suggested target setup

- Its **own domain** (naming still open — see [02-overview.md](02-overview.md):
  "What's Best For Us" / "Human Operating Manual" / "Competent Adult Roadmap").
- Its **own repo**, **own DB**, PHP 8.1+ (matches today), same table schemas.
- Reuse the concept docs and **this spec** as the build brief.

---

## Open questions to settle at migration

- **Domain & name** — still open.
- **Auth** — roll-your-own vs a library/managed service; email verification yes/no;
  password reset (borrow the admin's existing pattern).
- **Admin model** — multi-author CMS vs single-author; its own admin shell.
- **Feedback inbox** — keep Foundation + Lesson feedback unified, or split.
- **v2 scope** — the 3-bucket model (strength / build / mature), current-focus,
  private notes, member dashboards, and "next lesson" gating by mastery (the
  rollout gate from [07-playbook.md](07-playbook.md)).

---

## Recommended next step

1. Stand up the new home: domain + repo + database.
2. Port the `whats-best-for-us/` pages and the `*` schema.
3. Extract the `Core` / `admin` / `post.php` entanglements into a self-contained module.
4. **Then** build Workbook v1 per this spec — auth, members, status-only progress,
   tracked from the lesson page and the hub.

*Nothing here was built into `redmcwebstudios.com`. This is the plan to build once
the project has its own ground to stand on.*