From 189f528d47e1fea3b42884f1a5cebd8746239d05 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 13:19:45 +1000 Subject: [PATCH] Add the plain-language workflow map A single-page explainer for people who will not read the build spec: how a question becomes an answer, the four lanes and why they are separate, the four tools the assistant may reach for, where the knowledge comes from, and what is live against what is only built. Status snapshot as observed on the host, 21 August 2026. Kept at the repository root beside the other narrative documents rather than in docs/, which is gitignored and holds controlled plant documents. Listed in the layout sections of README.md and the build spec so it is findable. Note: it predates Phase 9 and so does not mention operator document upload, withdrawal or pool curation. Its step table stops at 8. Co-Authored-By: Claude Opus 5 --- BUILD-AI-CONTAINERS.md | 2 + README.md | 2 + workflow-map.html | 381 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 385 insertions(+) create mode 100644 workflow-map.html diff --git a/BUILD-AI-CONTAINERS.md b/BUILD-AI-CONTAINERS.md index d13357d..d03c45a 100644 --- a/BUILD-AI-CONTAINERS.md +++ b/BUILD-AI-CONTAINERS.md @@ -239,6 +239,8 @@ Project lives in Forgejo (`git.yokogawa.tech`). Compose files stay in `~` per ho . ├── BUILD-AI-CONTAINERS.md # this file ├── CLAUDE.md # symlink or copy of the host onboarding brief +├── workflow-map.html # the plain-language explainer, for people who are +│ # not going to read this file ├── README.md # rebuild-from-zero ├── compose/ │ ├── ai-compose.yml # deployed to ~/ai-compose.yml diff --git a/README.md b/README.md index 6e7b8a7..50df30c 100644 --- a/README.md +++ b/README.md @@ -343,6 +343,8 @@ pytest api/tests # contracts, classifier rules, SQL allow-list. No netw ``` CLAUDE.md short rules — what Claude Code keeps front of mind +workflow-map.html the non-technical explainer — how a question becomes + an answer, and what is built. Open it in a browser BUILD-AI-CONTAINERS.md the build spec YAU_Linux_Host_Onboarding.md the host brief (reference; wins on conflict) compose/ deployed to ~/ai-compose.yml and ~/langfuse-compose.yml diff --git a/workflow-map.html b/workflow-map.html new file mode 100644 index 0000000..689d8a5 --- /dev/null +++ b/workflow-map.html @@ -0,0 +1,381 @@ + + + + + +WRPS Plant Assistant — Workflow Map + + + +
+ +

The plant assistant — how a question becomes an answer

+

Waterloo Road Pump Station. An operator types a question in plain English; the +assistant answers it from plant records and controlled documents, and shows its evidence. This page +follows one question through the assistant, names the piece of software doing each job, and marks +what already exists.

+

Status as observed on the live host, 21 August 2026.

+ +
+ Running now + Built and tested, not yet switched on + Waiting on someone else + Not started +
+ +

1 · The question’s journey

+

Seven stages. The important thing to notice: the assistant decides what kind of +question it is before it looks anything up, and that decision fixes both which sources it may +use and what it is allowed to say.

+ +
+ +
+
Ask
+
+

The question box Built, not switched on

+

A web page with a question box and an answer pane, opened in an ordinary browser on the + control-room PC. Nothing to install.

+
Application: ai-web — the operator’s screen
+
+
+
↓
+ +
+
Sort
+
+

What kind of question is this? AI step + Built, not switched on

+

A small, fast AI model reads the question and labels it as one of four kinds — or says it is + unsure. It does no answering; it only labels. This is the most safety-relevant step in the + whole assistant, because the label decides everything downstream.

+

Two rules are built in: if it is not confident, it asks the operator to rephrase rather than + guessing; and if two labels are close, it takes the more cautious one — a question that is + partly advice is treated as advice.

+
Application: ai-api · the classifier, using a small AI model
+
+
+
↓
+ +
+
Translate
+
+

What is “Pump 02”, exactly? Built, not switched on

+

Operators say “Pump 02” or “the wet well”. The plant records call + those PU-302 and WW-101. This step converts everyday names into the plant’s official + ones by looking them up in a list — no AI, no guessing. When it gets a name wrong, the fix is + to add the nickname to the list.

+
Application: ai-api · the name resolver, reading the equipment + and tag list in pg-ai
+
+
+
↓into one of four lanes — or back to the operator
+ +
+
+

Historical — what happened?

+

“How many high level alarms last week?”

+

Counts and measurements taken from the plant’s recorded history. If there are no + records, the answer says so — it never estimates a figure.

+
Looks in: Cube → the plant historian
+
+
+

Reference — what does this mean?

+

“What does the level fault alarm mean?”

+

Explains a signal, alarm or piece of equipment from the manuals and alarm records, quoting + the document it came from.

+
Looks in: document search + the equipment and tag list
+
+
+

Procedural — how do I do it?

+

“How do I lift the interlock on Pump 02?”

+

Finds the approved procedure and identifies it — document number, revision, date — and + quotes its prerequisites word for word. It never writes the steps itself.

+
Looks in: document search, procedures only
+
+
+

Advisory — what should we do?

+

“What discharge rate avoids a spill?”

+

Shows what has been run before, what happened when, and the documented limits — then hands + the decision back to a competent person. It never gives a number as the answer.

+
Looks in: Cube and document search together
+
+
+

Unclear — I need more

+

“Is the pump alright?”

+

When the sorting step is not confident, the assistant stops and asks a clarifying question. + No sources are searched and no answer is drafted.

+
Looks in: nothing — it asks instead
+
+
+
↓evidence gathered
+ +
+
Word it
+
+

Turn the evidence into a readable answer AI step + Built, not switched on

+

The larger AI model is used here and only here: to put the gathered evidence into plain + English. It cannot go looking for anything else — it only sees what its lane collected. It + supplies wording, not facts.

+
Application: ai-api · the answer writer, using the larger AI model
+
+
+
↓
+ +
+
Check
+
+

Is this answer allowed to leave? Built, not switched on

+

Every draft is checked against a fixed rulebook before the operator sees it: no invented + steps for safety-critical work, no recommended setpoint, nothing beyond the evidence actually + found, and every claim carrying its citation. A draft that fails is rewritten once and then + refused — it is never shown.

+

These are ordinary software checks written in code, not instructions given to the AI. That + distinction is the point: an AI can be talked out of an instruction, and cannot be talked out + of a check.

+
Application: ai-api · the answer contracts and guardrails
+
+
+
↓
+ +
+
Show
+
+

The answer, and its working Built, not switched on

+

Beside the answer the operator sees how it was reached: which kind of question it was judged + to be, what data was counted and over what period, how many records were found, and which + documents were cited with their revision and date. Procedural and advisory answers carry a + visible banner stating plainly what the assistant did not do.

+
Application: ai-web · the “show working” panel
+
+
+
↓
+ +
+
Record
+
+

Everything is written down Running now

+

Each question, the kind it was judged to be, the sources used, the rulebook result and how + long it took are all recorded, so any answer can be reviewed afterwards and any mistake traced + to the step that caused it.

+
Application: Langfuse — the assistant’s logbook
+
+
+ +
+ +
Why four lanes instead of one clever assistant: the four kinds of +question need different sources, and — more importantly — different limits on what may be said. One +general-purpose pipeline answering all four is the main way a project like this hurts somebody: it +is how a bypass procedure gets reassembled from fragments nobody approved, or a setpoint gets +suggested and typed into a control system. The assistant cannot wander between lanes, because the +lane is fixed before any searching starts.
+ +

2 · The four tools it can reach for

+

The assistant has no free access to anything. These four, and nothing else.

+ +
+
+

Cube — the data translator Waiting on the historian

+

Turns “high level alarms last week” into an exact query over the plant’s + recorded history. The definitions that make an answer right — what counts as an alarm, what + “last week” means, what counts as a fill — are written down in files an engineer can + read and check, instead of being invented per question. It also keeps ready-made summaries so + common questions never hammer the live historian.

+

The assistant never writes database code itself. It fills in a request form; Cube does the + rest.

+
Reads: the imh plant historian, read-only. Definitions live in + cube/model/ — alarms, process values, operations, equipment.
+
+ +
+

Document search No documents loaded yet

+

Searches the controlled documents by meaning rather than keyword, so “lift the + interlock” finds the right procedure even when the document says “interlock + override”. Two rules are permanently on: withdrawn revisions are never returned, and every + result carries its document number, revision, date, page and section — a passage that cannot be + cited cannot be used.

+
Reads: document sections stored in pg-ai
+
+ +
+

The name list Built, loaded

+

Every piece of equipment and every measurement point, with the everyday names operators + actually use. Deliberately a plain list rather than something the AI works out, so it behaves the + same way every time and can be corrected by editing one row.

+
Reads: the equipment and tag tables in pg-ai
+
+ +
+

The logbook Running now

+

Not a source of answers — the record of them. Every question and every step it took is stored + so the assistant’s behaviour can be audited and improved from evidence rather than + impressions.

+
Application: Langfuse
+
+
+ +

3 · Where the knowledge comes from

+

Two supply lines feed those tools. Neither is finished.

+ +
+
+

Documents in Not started

+

Procedures, manuals, alarm rationalisation and design documents are read, split into sections, + and converted into a searchable form. Three habits matter: a numbered step sequence is never cut + in half; the document’s type comes from the folder it was filed in, not from a guess; and + a person confirms the document number, revision and date before anything is stored. A wrong + revision on a procedure is a safety problem, not a tidiness one.

+
Application: ai-ingest, run by hand when documents change → stored + in pg-ai. Written and tested; no documents loaded onto the host yet.
+
+ +
+

Plant history in Waiting on someone else

+

The station’s control system records levels, pump runs and alarms into the plant + historian. The assistant reads that history through Cube — read-only, never writing to it, and + never touching the control system itself.

+
Source: the imh historian. That server is still being built, so a + read-only login and the agreed table names are still outstanding.
+
+
+ +
Worth knowing: until the real historian is available, the data lanes run on +stand-in figures. Every answer produced that way carries a warning label all the way to the +operator’s screen, so it cannot be mistaken for a real plant number.
+ +

4 · What exists, and the order the rest gets built

+

Each step ends in a check that must pass before the next begins — so that when an +answer comes out wrong, there is one place to look, not four.

+ +
+ + + + + + + + + + + + +
StepWhat it deliversStatusWhat it needs
1The store — where documents, equipment names and ready-made summaries liveRunning nowDone. Live, checks passed.
2The logbook — recording of every question, put in early on purpose so every later experiment is traceableRunning nowDone. Live.
3The documents — the real procedures and manuals, read in and searchableNext upThe documents themselves, and someone to confirm each one’s revision and date. Needs nothing from the historian — which is why it goes next.
4Access to plant history — a read-only login to the historianBlockedThe historian server, a read-only login and agreed table names. The only true blocker — start that conversation now, alongside step 3.
5Cube — the data translator, with every definition written downBuilt, not switched onStep 4 — though it can be proven on stand-in data first. An engineer must independently confirm its first numbers before anyone trusts them.
6The assistant itself — the sorting step, the four lanes, the answer writer and the rulebookBuilt, not switched onSteps 3 and 5, so that a wrong answer can only be the assistant’s own fault.
7The operator’s screen — the question box, the answer, the workingBuilt, not switched onStep 6, plus one network name record so control-room PCs can reach it — ask for that early, it depends on someone else and will not surface as a problem until the day it is tried.
8The exam — 62 engineer-checked questions run end to end and scoredWritten, not runEverything above. Pass mark: 85% correct overall, 95% on the two dangerous kinds, and zero breaches of the rulebook.
+
+ +

5 · The short version

+
    +
  • Live today: the store and the logbook — the foundations, not yet anything an operator +would see.
    • +
  • Written and tested, waiting to be switched on: the sorting step, all four lanes, the +answer writer, the rulebook, Cube and the operator’s screen. The software exists; it has not +been put into service.
    • +
  • Not started: loading the real documents. This is the nearest useful milestone — it needs +nothing from the historian, and it is what makes “find me the procedure” work, a +demonstration that stands on its own.
    • +
  • Needs other people, so ask today: the read-only historian login, and the network name +record for the control room. Both take days of someone else’s time and neither can be hurried +at the end.
    • +
  • Before any operator sees this: what the assistant will and will not say must be reviewed +with an OT/safety representative.
    • +
+ +

Sign-in, network routing and hosting are handled by platform services already running +on the demo host. They are deliberately left off this map — they protect the assistant, but they are +not part of how it answers a question.

+ +
+ +