Demonstration dashboard for the Wood River crude and vacuum distillation unit.
Values are illustrative, taken from the 22 November 2022 snapshot. They are internally consistent, so the arithmetic holds if a reviewer checks it, and they are never to be presented as measured plant performance. See
PROVENANCE.md.
Read SETUP.md. It is the one document for a fresh clone: what to install
(Node 20.9 or newer is the only hard requirement), how to start it, what you are
looking at, and what to read before changing anything.
npm ci :: not npm install - the lockfile is committed
npm run dev :: http://localhost:3000
Double-click start_frontend.bat. It installs anything missing, starts the
server and opens http://localhost:3000/. The console window is the server —
close it, or press Ctrl+C, to stop.
To let colleagues on the same network open it, use share_on_network.bat.
It builds for production and prints a LAN link to hand out.
Full notes — publishing more widely, ports, and what the Python environment is
actually for — are in docs/RUNNING_AND_SHARING.md.
From a terminal:
npm ci :: first time, and after anyone changes package.json
npm run dev :: http://localhost:3000
npm run build && npm run start
reference/ the source artifact and the three workbooks behind it -
the KPI calculation sheet, the single-timestamp DCS extract
and CDU_VDU_Dashboard_Data_Reference.xlsx
docs/ in force - architecture, plant context, specs, decisions
docs/context/ background reading, explicitly not spec
docs/archive/ superseded specifications, kept for the record, NOT in force
config/ site config and its Zod schema
scripts/ two gates, four generators, and the setup helpers
src/ the app
reference/cvd_demo_v0.5.jsx is the specification. Where it and a document
disagree, the artifact wins. docs/DECISIONS.md is the single register of rules
in force; PORTING_GUIDE.md has the order of work.
| Branch | What it is |
|---|---|
main |
The line of work. Push here. |
nirmal |
Last known good. A pointer to a main that was checked and worked. Never worked on. |
port/* |
The step-by-step port history, kept for the record. All merged into main. |
Tags mark verified states — port-step-6 is all eight screens rendering. A tag
cannot drift the way a branch can, which is what makes it the thing to restore
from.
Advance nirmal only when main is good — it builds, the screens render.
One line, from anywhere, without switching branches:
git push origin main:nirmal
Do this deliberately, not on every push. If it is refused as non-fast-forward,
main has been rewritten — stop and find out why before forcing anything.
If something unwanted lands on main, prefer the repair that keeps history
and needs no force-push:
git fetch origin
git revert --no-commit <bad-sha>..main
git commit -m "Revert unintended changes on main"
git push origin main
Only if main is genuinely mangled, reset it to the safety pointer:
git reset --hard origin/nirmal
git push --force-with-lease origin main
--force-with-lease, never a bare --force — it refuses if someone else pushed
while you were not looking.
There are no branch-protection rules on this repo, by choice. So the above is
a convention, held by people rather than by GitHub: nobody force-pushes, and
nobody touches nirmal. If that is ever violated, Settings → Rules can lock
main later without changing how anyone works. Two backstops if it all goes
wrong anyway: the tags, and GitHub’s repository Activity tab, which records
every force-push with the before-and-after SHAs.
Open this folder in Claude Code and type:
/port-step 7
That is all. The command loads docs/13_ARTIFACT_MAP.md for what is live, the
spec for that step, and the compile-before-presenting rule. It stops for your
agreement before editing anything.
If you want the fuller opening — build health, what the last session left
broken, the decision register bottom-up — run /start-session first, then
/port-step 7.
Steps are listed in docs/00_BLUEPRINT.md §8. Step 7 is the last one, and the
only one left. One step per session. Close with /close-session, which runs
the gates and writes the log entry.
To compare a screen against the specification, open /preview — the artifact
mounted whole. It is no longer linked from the nav (D57), so type the URL.
If the slash commands are not offered, .claude/ was not picked up — restart
Claude Code once. As a fallback, paste this instead:
Read CLAUDE.md, then docs/DECISIONS.md from the bottom up, then the last
entry of docs/SESSION_LOG.md. docs/archive/ is historical and not in force.
The specification is reference/cvd_demo_v0.5.jsx. Where it and a document
disagree, the artifact wins.
Today's goal: port step 7 from docs/00_BLUEPRINT.md section 8 -
accessibility, closing invariant checks 4 and 5, and the last of the D35
inline-style conversion. It is the last step.
Three things to know going in.
There is NO dark theme pass. D56 removed dark mode and the theme toggle
from the product. .wr.dark is still generated byte-identical to the
artifact and nothing renders it - leave it alone, do not strip it, and do
not re-add a toggle.
D35's carve-out reverts to its unqualified form after step 7, so
src/shared/ui/ and src/shared/diagrams/ convert their remaining inline
styles to Tailwind in this step and the design-token rule becomes absolute.
The declaration-parity harness from sessions 016 and 018 is the tool that
makes that conversion checkable - it found two real defects the eye did
not. Rebuild it rather than converting by eye. It is not committed (D49).
Invariant check 4 is twelve dead Screen* declarations and six unused
imports in the artifact; check 5 is eight #fff literals. Close them in the
port, NOT by editing reference/cvd_demo_v0.5.jsx - it is the specification.
The pinch tab has never been walked at any width, nor the equipment popup
inside the real shell. See the Owner actions in the last session log entry.
Show me the plan before editing. One goal this session, not two.
Both gates are stdlib-only Python — no virtual environment required.
scripts\run_checks.bat :: all three at once
Or individually:
python scripts/check_invariants.py
python scripts/flowsheet_collision_check.py reference/cvd_demo_v0.5.jsx \
MAIN_A desalt h24 h28 hen ctower vtower strip lab
python scripts/flowsheet_collision_check.py --stress reference/cvd_demo_v0.5.jsx \
MAIN_A desalt h24 h28 hen ctower vtower strip lab
Both collision runs must pass, nominal and stressed — a bare nominal pass is not evidence of margin.
The invariant check exits non-zero today, by design. Checks 4 and 5 of
its six fail on pre-existing defects in the artifact — twelve dead Screen*
declarations and eight #fff literals. They close in port step 7. The
known-open list is in docs/SESSION_LOG.md — read it before assuming you broke
something. A gate that has never failed has never been tested.
Only needed to read the two spreadsheets in reference/.
scripts\setup_python.bat :: .venv on Python 3.12, installs openpyxl