# CW Academy Core-Flow Release Notes + Operator Runbook

## Release notes (website core flow)
- Status: core learner flow released for website dashboard + section pathway + exam center + session launch routing.
- Scope: deterministic status/recommendation rendering, section progression summaries, quick navigation, certificate handoff, mentor sharing preview, and route telemetry.
- Guardrails: keep endpoint contracts additive-only and preserve deterministic fallback copy for unauthorized/error states.

## Incident triage quick map
1. Dashboard renders but sections stay in `Loading...`.
   - Check startup fallback guard and status response payload.
2. Quick-nav chips click but section does not open.
   - Check route-event telemetry entries and hash target bindings.
3. Exam center actions show lockout/retry mismatch.
   - Check `retry_policy` payload and section state lane.
4. Certificate actions missing for eligible learners.
   - Check certificate history diagnostics + section handoff URLs.

<a id="deterministic-remediation-commands"></a>
## Deterministic remediation commands
Run in repository root:

```bash
bash cw-academy-dashboard-startup-audit.sh
bash cw-academy-path-audit.sh
bash cw-academy-session-player-routing-audit.sh
bash cw-academy-website-route-smoke.sh
bash cw-academy-ci-gate.sh
```

## Post-release watch window command
- Run a deterministic watch sweep (full):

```bash
bash cw-academy-watch-window.sh
```

- Run a lighter watch sweep (quick):

```bash
bash cw-academy-watch-window.sh --quick
```

- Output:
  - summary: `admin/reports/cw-academy-watch-window/latest.txt`
  - per-check logs: `admin/reports/cw-academy-watch-window/watch-window-<timestamp>-<check>.log`

If CI gate fails, collect:
- failing script output,
- failing drift marker(s),
- latest runner report JSON in `admin/reports/cw-academy-test-runner/`.

## Website checklist command runner failure modes
Applies to `/admin/cw-academy-website-checklist-run.php` (admin-only checklist command endpoint).

- `forbidden_admin_required` (`403`): caller is not an admin session.
- `method_not_allowed` (`405`): request method is not `POST`.
- `invalid_command_key` (`400`): payload is malformed, oversized, or command key format is invalid.
- `unsupported_command_key` (`400`): command key is outside the fixed allowlist.
- `script_missing` (`500`): allowlisted command script is not present on disk.

Failure-code remediation commands (deterministic):
- `forbidden_admin_required` -> `Log in with an admin session, then rerun POST /admin/cw-academy-website-checklist-run.php`
- `method_not_allowed` -> `Use POST with JSON body {"command":"startup"} to /admin/cw-academy-website-checklist-run.php`
- `invalid_command_key` -> `Send JSON body with command in allowlist: startup,path,fallback,route_smoke,ci_gate`
- `unsupported_command_key` -> `Use one of: startup,path,fallback,route_smoke,ci_gate`
- `script_missing` -> `Restore checklist scripts and rerun: bash cw-academy-ci-gate.sh`

Command allowlist:
- `startup`
- `path`
- `fallback`
- `route_smoke`
- `ci_gate`

<a id="operator-rollbackretry-sequence"></a>
## Operator rollback/retry sequence
1. Re-run deterministic audits above to confirm reproducibility.
2. If only quick-nav drift fails, patch `js/cw-academy-home-navigation.js` and `js/cw-academy-page.js` telemetry keys only.
3. If startup fallback drift fails, patch `js/cw-academy-page.js` fallback contract and keep unauthorized/error copy aligned.
4. Re-run `bash cw-academy-ci-gate.sh` before publish.

## Startup/interaction failure triage (dashboard)
Use this branch when learners report:
- header/footer missing or delayed render,
- whole dashboard appears non-clickable,
- status stays in loading state.

Deterministic sequence:
1. Run:
   - `bash cw-academy-dashboard-startup-audit.sh`
   - `bash cw-academy-website-route-smoke.sh`
   - `bash cw-academy-ci-gate.sh`
2. If status fetch is flaky, verify status-flow retry is active (transient retries enabled).
3. If optional sections fail after first load, verify optional-loader did not double-inject already-loaded scripts.
4. Confirm shell fallback diagnostics are present in startup contract (`shell_*` keys) and no unresolved loading placeholders remain.

## Evidence checklist before release tag
- `cw-academy-ci-gate.sh` PASS.
- route-event smoke matrix PASS.
- startup audit PASS.
- pathway/session-player audits PASS.
- status file (`CW_ACADEMY_PROJECT_STATUS.md`) updated with completed tickets and next queue.