Crown Debrief

You wear the Crown through a work block. At the end, the app reads the CSV and tells you what happened, when you peaked, when you crashed, how long your best stretch lasted, and one thing to try tomorrow. Half of this already exists: your logger writes the data. This finishes it.

Project 4 · golden build

A chat panel that answers questions about the project, what alpha is, how to run the logger, what a number means, by looking them up in the project’s own documentation rather than improvising. It reads your current state and gives a dense answer when you’re sharp, a scaffolded one when you’re not.

Where you’re starting from

The crown-focus-logger repository already existed when this spec was written. It records focus, calm, and five bands to CSV every two seconds, with a mock mode and a real Crown mode. It is the collection half of Project 2 and it stays exactly as it is; nothing in this spec rewrites it.

If the handoff is “run this server on a particular machine,” it dies the day that machine stops being maintained. So the version GFT gets has to be a set of files on a web host: open the link and it works, with nobody running anything. That means every calculation the lab version performs has to happen in the visitor’s browser.

Two reasons, and the second is the important one. First, a public site cannot ship an API key, anyone with the page can read it straight out of the source. Second, a tool that stops working when an external service is down is fragile in a lab.

So the debrief is computed, then written: a plain analysis engine works out the facts, and a set of sentence templates turns those facts into readable English. No model involved. If you later add a key, an optional button rewrites that same paragraph more naturally, but it’s polish on top of something already complete.

A side effect worth having

Because every sentence traces back to a number, the debrief is auditable. A GFT engineer can check any claim against the CSV. That’s a stronger position than “the model said so”, the constraint made the product better, not worse.

• Data Load a session Drag a CSV in, or pick one from the data folder. Reads the format your logger already writes.

• Data Quality filter Drop rows where the electrodes weren’t making contact, and report what percentage of the session survived. A loose sensor produces confident-looking nonsense; this is the guard.

• Stats Personal baseline Learn your normal range and judge everything against it. Neurosity’s own docs say focus above 0.3 is already significant, which is exactly why a fixed threshold like “0.7 is focused” would mislead every beginner who used it.

• Stats Peak windows Your three longest sustained stretches above baseline, with clock times.

• Stats Slumps Dips below baseline lasting more than a few minutes, with clock times.

• Stats Time in state How much of the session was focused, calm, drifting, or unreadable.

• Chart Session timeline Focus and calm across the session, with your baseline band shaded behind it. Hand-drawn on a canvas, no chart library, so it works offline.

• Chart Band summary Average alpha, beta, theta and gamma, plus how they moved across the session.

• Output Written debrief A plain-English paragraph assembled from the numbers above. No model, no key, no network.

• Output One suggestion A single rule-chosen tip, kept behavioural and modest, protect the window you’re actually sharp in, that sort of thing.

• Output Copy summary One button puts a compact, labelled version of the whole session on your clipboard, ready to paste into Claude or anything else. The app owns the numbers; any model you like can own the words.

• Output Export Download the whole debrief as a Markdown file.

EEG tells you when something changed and is permanently silent on why. A one-line note against a peak or a slump, “back-to-back meetings”, “after lunch”, “the deploy broke”, is the only thing that can supply it. A few weeks of those and the debrief stops describing and starts noticing: slumps cluster after meetings, peaks are all before eleven.

It’s also the same primitive any future model would train on, a timestamp plus what was true at that moment. Arrived at from the useful end rather than the theoretical one.

• Today The file format Notes live in their own file keyed by timestamp, never mixed into the CSV, so the raw record stays raw. The debrief displays them if they exist.

• Next Retrospective capture On the debrief screen: “you dipped at 15:10, what was going on?” You get the label with zero interruption.

• Later Live prompting Only after a dip has clearly persisted, never during a good stretch, always dismissible.

Why live prompting comes last

Interrupting someone to ask whether they’re distracted is itself distracting, a notification fired during a dip can cause the dip it’s asking about. Retrospective capture gets the same label for free. And these notes are more sensitive than the brain data in places, so: local only, never on the public site, never sent to a model without an explicit yes.

• Unbuilt Local rewrite experiment Would rewrite the same computed facts more naturally. Local only, and never wired into the public build.

• Next Multi-day view Compare sessions; find which hours of the day are reliably yours.

• Next Eyes-closed self-test 30 seconds open, 30 closed, check alpha rose. Turns “is this real data?” into a button, and since Neurosity computes calm from alpha, it validates calm too.

For a one-off, “here’s my CSV, what do you make of it?”, pasting into a general assistant is better than anything built in a week, and the spec doesn’t pretend otherwise. Four things are different here:

• It computes rather than estimates. The same peak window, the same way, every run, checkable against the CSV.

• It says things you didn’t know to ask. The debrief is unprompted; a chat only answers the question you thought of.

• It has the live stream. “What am I doing right now and what would help?” cannot be pasted into a chat window. This is the strongest reason to build it.

• It works without prompting skill. A lab visitor gets a link and a working thing.

The framing

The app owns the numbers, the model owns the words. Build the layer that makes any model good at this rather than competing with one, which is exactly what the copy summary button in Project 2 is for.

Live brain state is available on the machine running the headset, so answers could adapt in real time. This variant was explored locally against a key held in .env and was never wired into the public build.

Public · the lab’s copy

No headset means no live state, so there is nothing to adapt to, which retires the problem rather than solving it. The guide retrieves the right passage and explains it. No key, and nothing that can go down.

This is why the two-depth writing idea is gone: it only existed to fake adaptation without a model, and on the site where there’s no model there’s also no state to adapt to. Every explanation gets written once, properly.

• Core Local search A small keyword-ranking search over the project’s own notes. About sixty lines, no dependencies, no network.

• Core Sources on every answer Which note, which section. Nothing unattributed, this is what stops it inventing things.

• Core Answers that reach your data “What’s my focus doing?” answered from the loaded session, not from generic text.

• UI State badge A small label showing what state it thinks you’re in and what it’s doing about it. Without it the adaptation is invisible and faintly creepy; with it you can see it, debug it, and disagree with it, which matters, because the metric is noisy.

• UI Adaptive on/off toggle Ask the same question twice with it on and off. This is the demo that sells the idea to the lab.

• UI Starter questions Six suggested questions, so a first-time visitor isn’t staring at an empty box.

• Unbuilt Model-written answers Retrieved passages plus the computed summary handed to a model, which answers in its own words. A local experiment only, and not part of the shipped guide.

• Next Notes in the loop Once session notes exist, “why do I keep crashing at three?” becomes answerable.

Two rules this feature must never break

Adaptation changes the shape of an answer, how long, how scaffolded, how much at once. Never the substance. If you read as scattered it may slow down; it must never soften, hedge, or withhold something true because it decided you couldn’t handle it.

And it stays behavioural. “Your longest good stretch was 10:20-11:05, protect that window” is just your own data read back to you. “Your theta suggests you need more magnesium” is pseudo-neuroscience and would embarrass the project in front of a lab. When something is unknown, it says so.

Node server on the machine running the headset. Live Crown data, recording, tuning, diagnostics, and the guide. The guide is keyword search over the project notes and cites the note each answer came from; there is no model in the loop here or anywhere else. This is the only tier that touches hardware.

Today

Tier 2 · the handoff

The same modules, no server, no model, no keys. Published on GitHub Pages from the repo. A visitor drops in a CSV and gets the full debrief; the guide answers from a search index built at publish time. Nothing to keep running.

Day 2

Tier 3 · only if asked

It was on the list and it’s off it. A key pasted into a web page is readable by anyone with the device, by any browser extension, by any script on the page, and it sits in plain view in the network panel. There is no way to guarantee otherwise.

The worse problem isn’t technical. Asking lab staff to paste a credential into a website trains them to paste credentials into websites, which is the exact habit phishing depends on. Not shipping it, however carefully it’s built.

The one real answer to “a model they can just talk to” is a small model running inside the visitor’s own browser, no key exists at all and nothing leaves their machine. It costs a large first-visit download and a recent browser, and the model is noticeably weaker. Worth a prototype another week; not this one.

Neurosity already documents their own API, so none of that gets rebuilt here. What their docs don’t do is interpret: they’ll tell you focus is a probability derived from gamma between 30 and 44 Hz, and that above 0.3 is significant, but not what to make of your 0.35 on a Tuesday afternoon. That interpretation layer is the only thing worth writing, and it links out for everything canonical rather than copying it.

Privacy, since this becomes public

A CSV dropped into the static site is read in the visitor’s own browser and never uploaded, worth stating on the page itself, because people are right to be careful with brain data. Session notes never go near it at all. And if multi-person collection ever happens, contributing is an explicit opt-in, not a side effect of using the tool.