# Wave 0 — Orientation

**Do this before wave 1.** Nothing else in the plan should be started until `T0.1` is merged.

The item IDs and file references throughout this plan come from a UX review conducted on
branch `users/directory-super-user`, not from a fresh read of the repo you are in. The line
numbers were accurate at the time of the review. Confirm them before relying on them.

---

### T0.1 — Build the file map

- **Items:** none (prerequisite)
- **Depends on:** nothing
- **Blocks:** every other task
- **Surface:** documentation only
- **Files:** creates `docs/reference/file-map.md`

**Do:**

Inventory the frontend and record it. The review described `html/` as 6 pages, 4
stylesheets, roughly 11,900 lines. Confirm that and write down what is actually there.

For each of the 6 pages record: file path, what it is called in this plan (launcher, SOP
wizard, creator, admin, field view, directory/users, login), which stylesheets it loads,
which scripts it loads, and whether it renders inside an iframe or hosts one.

For each stylesheet record: path, and which pages consume it.

Then verify these specific references from the review and record the current line number
next to each, or mark it `NOT FOUND`:

| Reference | Claim |
|---|---|
| `wp-creation-app.js:1144` | `alert()` reading "Subject and WP Type are required" |
| `wp-creation-app.js:1962-1972` | logged-override path for predecessor constraints |
| `work-package-suite-app.js:326` | the only `beforeunload` listener, analytics dwell tracking |
| `work-package-suite-styles.css:322-328` | `outline: none` plus a pale 3px focus glow |
| `work-package-suite-styles.css:336` | comment about `.field-hint` rendering unstyled |
| `console.css:85-87` | the contrast fix that was not propagated |
| `admin.js:484-517` | language and time localization |
| `server/seed_demo.py` | seeding script that does not authenticate |

Also record counts, so later waves can prove they went down:

- occurrences of `alert(`, `confirm(`, `prompt(` — review found 79 app-wide, 43 in the creator
- `<div` and `<span` elements carrying `onclick` — review found 12 and 2
- declarations of `#0f62fe` — review found 4
- `.help-tip` elements — review found 15
- `aria-live` regions — review found 0
- `pushState` calls — review found 0

**Do not:** change any application code in this task. It is a read and a document.

**Done when:**

- [ ] `docs/reference/file-map.md` exists and lists all pages, stylesheets and scripts
- [ ] every reference in the table above is confirmed with a current line number or marked `NOT FOUND`
- [ ] the seven counts are recorded with the command used to produce each
- [ ] any file path used in a later wave file that does not exist is listed under a `Discrepancies` heading

---

### T0.2 — Confirm the app runs and the baseline is captured

- **Items:** none (prerequisite)
- **Depends on:** T0.1
- **Blocks:** every task with a visual done-when
- **Surface:** local environment
- **Files:** creates `docs/reference/baseline/`

**Do:**

Run the app locally (`uvicorn server.app:app` against a throwaway SQLite database) and drive
the first-run flow: sign in, create a project, SOP wizard, creator, directory, field view.

Capture baseline screenshots at **390px** and **1440px** for each of the 6 pages into
`docs/reference/baseline/`. Name them `<page>-<width>.png`. These are the before images
every later PR compares against.

While doing this, confirm each of `F1` through `F6` still reproduces and note it. If one does
not reproduce, say so in the PR rather than deleting the task from wave 1.

**Do not:** fix anything you see. Wave 1 does that.

**Done when:**

- [ ] the app runs locally from a clean database
- [ ] 12 baseline screenshots exist (6 pages x 2 widths)
- [ ] each of `F1`–`F6` is marked reproduces / does not reproduce, with a screenshot reference
- [ ] the exact run command and any setup steps are recorded in `docs/reference/file-map.md`