[ryanbr]

Follow-up to #862, found reviewing it. Docs only — two things that would each stop someone using the harness on their first attempt.

1. The analyze command names a file nothing writes

- swift run whoop-optical-experiment /path/to/noop-whoop5-optical-experiment.jsonl \
+ swift run whoop-optical-experiment /path/to/puffin-deepbuffers.jsonl \

opticalExperimentURL() returns Self.logURL(), which is puffin-deepbuffers.jsonl — the existing capture log, because markers are appended to it rather than written to a file of their own. Copying the documented command fails, and the natural next move is to go hunting for a file that was never created.

Also made the export step say which file it is, since "save the .jsonl file" gives no clue that it is the same log the frames are already going into.

2. The procedure names buttons; the data uses raw values

The capture steps say Off wrist · sensor covered. The JSONL says off_wrist_dark. Those are not the same words, so grepping your own export for what you tapped can quietly return nothing — on a harness whose entire output is that file.

Added the eight-row mapping, and stated that experiment_end is a boundary rather than a phase: it closes the preceding one so later offload records are not attributed past the run, and it never appears as a phase in the report. That behaviour is correct in the analyzer but was not written down anywhere a capturer would look.

Verification

Every mapped value checked against PuffinOpticalExperimentPhase — all eight present, none invented:

enum values : experiment_end, gentle_pressure, off_wrist_dark, off_wrist_room_light,
              on_wrist_again, on_wrist_still, paced_breathing_normal, paced_breathing_slow
doc ⊆ enum  : True

Both gates green. No code touched.

Worth saying why this is worth a PR rather than a shrug: #862 is a harness with no value until someone takes a labelled capture, and both of these defects land squarely on the person trying to take one.

[ryanbr]

Reviewed my own PR and had to reverse half of it.

I claimed the analyze command named a file nothing writes. It does. SettingsView exports via FileExport.timestampedName("noop-whoop5-optical-experiment"), so the file a user actually saves is noop-whoop5-optical-experiment-<timestamp>.jsonl. The original doc was describing the exported file. I checked only the on-device writer — logURL() → puffin-deepbuffers.jsonl — and concluded the doc was wrong.

Pointing the command at puffin-deepbuffers.jsonl made it worse: that name exists only inside the app container, so a reader following step 9 would have saved one file and been told to analyse a different one. I turned a non-bug into a real one.

Both names are now documented together with the reason they differ — markers are appended to the existing capture log, and the export renames on the way out. The analyzer reads contents, so either file works.

The label-mapping table stands, and I re-verified it properly this time: raw values against PuffinOpticalExperimentPhase, button names against the String(localized:) cases. Both columns come from code rather than from the prose I was correcting — which is exactly the check I skipped on the filename.