Plant assistant: one agent management and operators can ask

New docs/plant-assistant.md (decision, Alexander, 26 Oct 2026): an
assistant for the whole plant, asked in Thai or English at kiosks, desks
and phones, answering from the knowledge base (SOPs as ERPNext Quality
Procedures, vendor manuals on the Assets, recipes and limits, this
repository, lessons learned) and from ERPNext and the machine-data store,
with sources on every answer. Roles and questions, what it does
(explain, trace, summarise, alert context, plan vs actual, drafts) and
never does (machines, submitting, safety improvisation, seeing more than
the asker, rating operators, needing the internet). Built on Typhoon 2.5
(open weights, Apache-2.0, CPU trial first), Typhoon ASR for optional
voice, pgvector retrieval, MCP tools in cnx-factory through the one
integration layer and the PostgreSQL replica; vinyl-ai GPU server only if
needed (~250k to 300k THB, RTX 5090 Thai retail Oct 2026). Test set per
role, phasing, cost, risks, open decisions.

Mirrors: digital-factory systems and machines tables, rough cost note;
catalogue advisor becomes a role of the assistant; worker-safety
training; roadmap item 18; README bullet and layout.

README.md

@@ -195,6 +195,12 @@ The detail lives in dedicated documents:
   repo, VLAN zoning, Telegraf/MQTT acquisition source by source, QC
   instrument integration, the factory application, alerting, backup,
   security, the data clauses for every RFQ, build order and rough cost
+- [Plant assistant](docs/plant-assistant.md): an agent management and
+  operators ask in Thai or English, at a press kiosk, a desk or a phone;
+  it answers from the procedures, vendor manuals and this repository and
+  from ERPNext and the machine data, with sources on every answer, sees
+  only what the asker may see, drafts but never submits, never touches a
+  machine, and runs on site on an open-weights model
 - [Inline optical QC](docs/equipment/inline-optical-qc.md): devices for
   the 100% record inspection station (line-scan cameras with dark-field
   and transmitted light, label camera, laser warp sensors, centring
@@ -433,6 +439,7 @@ docs/
 │                          Payap rezoning route)
 ├── make-a-record.html     Artist platform investor demo (end-user flow)
 ├── payap-partnership.md   Joint student programmes with Payap University
+├── plant-assistant.md     Ask the plant: assistant on knowledge base and data
 ├── plant-operation.html   Animated plant overview (simulated SCADA)
 ├── process-flow.md        Audio file to delivered record, with all checks
 ├── production-hall-layout-sketch.FCStd  Rough BIM sketch, Mueang Chi hall (earlier fleet)

docs/catalogue-intelligence.md

@@ -338,12 +338,12 @@ How it is kept honest:
   scored against the plain reorder rule; if it does not beat it, it
   becomes a report instead of an agent.
 
-**Which model runs it.** By the open-source rule, an open-weights
-language model served on a fleet machine (llama.cpp or vLLM on NixOS) is
-the default; the forecasting is ordinary statistics, so the language
-model only reads, searches and writes. No such GPU machine is in the
-fleet plan yet (estimate: one workstation-class GPU, a few thousand USD).
-A hosted model is a fallback to decide on only if the open one proves
+**Which model runs it.** The advisor is one role of the
+[plant assistant](plant-assistant.md): the same open-weights model on the
+plant's own machines, the same tool rules, with the catalogue tools and
+the catalogue roles' permissions added. The forecasting is ordinary
+statistics, so the language model only reads, searches and writes. A
+hosted model is a fallback to decide on only if the open one proves
 inadequate, and then only aggregates leave the fleet.
 
 ## How it fits the plant
@@ -386,7 +386,7 @@ inadequate, and then only aggregates leave the fleet.
 | Dashboard and sales map in the factory application | 1.5 to 3 person-months |
 | Forecast job: Stage 1 rule, then the Stage 2 model | 0.5, then 1 to 2 person-months |
 | Advisor: tools, prompts, logging, scoring | 1 to 1.5 person-months |
-| GPU machine for the open-weights model | a few thousand USD of hardware |
+| Language model and its machine | shared with the [plant assistant](plant-assistant.md#rough-cost-estimates) |
 | Map tiles, geocoder, hosting | on the existing fleet |
 
 ## Risks

docs/digital-factory.md

@@ -198,6 +198,7 @@ TODO list or small extensions to existing modules):
 | Plant core | Machine-data store (PostgreSQL for cycle and record rows, VictoriaMetrics + vmalert + Grafana for time series), Mosquitto, Telegraf persister, Alertmanager, factory application, file datasets on ZFS | `vinyl-core` | Build |
 | ERPNext | The system of record: accounting with Thai VAT and withholding tax, customers, prices, sales and purchase orders, artist gates, items, BOMs, work orders and job cards, stock and batches, quality inspections, metal parts and their genealogy, deliveries, assets and maintenance, payroll | `vinyl-erp` | from the first capex invoice; production records at commissioning |
 | Factory application | The tools and interfaces we build on ERPNext: station kiosks working the job cards, customer portal, machine-data service (cycles and per-record results in, totals and verdicts to ERPNext), instrument adapters, reports; the ERPNext integration layer. No business records of its own | `vinyl-core` | Build (v1), Launch (v2) |
+| Plant assistant | Management and operators ask in Thai or English; answers from the procedures, manuals and this repository and from ERPNext and the machine data, with sources; read-only, drafts records but never submits, never touches a machine ([plant assistant](plant-assistant.md)) | `vinyl-core` (CPU at first), `vinyl-ai` if a GPU is needed | Build (documents), Launch (kiosks) |
 | Edge collectors | Telegraf per machine zone, disk-backed store-and-forward, NTP to the OT segment, vision result receiver | `vinyl-edge-press`, `vinyl-edge-util`, `vinyl-edge-galv` | Build, Expand |
 | Environmental monitoring | Zone temperature, humidity, PM, differential pressure; alarms; correlation with production | RS485 loops into the edge collectors | Build |
 | Machine telemetry | Presses, extruders, hydraulics, boiler, chiller, compressor, heat pump, HVAC, PV, BESS, energy and water meters | edge collectors | Build |
@@ -304,13 +305,15 @@ Hardware classes are planning positions; models are chosen at purchase.
 | `vinyl-st-pack1` | Runout code camera read, jacket barcode scan, BOM check, barcode verifier | mini PC, camera, scanner, verifier | packaging |
 | `vinyl-st-ship` | Consignment assembly, carrier label and tracking capture | mini PC, label printer | shipping |
 | `vinyl-nvr` | Frigate CCTV recording on the cctv VLAN (optional; a vendor NVR appliance is the alternative) | small server with GPU or Coral accelerator | IT room |
+| `vinyl-ai` | The [plant assistant](plant-assistant.md)'s language model and speech recognition (optional; only if the CPU trial on `vinyl-core` is too slow) | server with one 32 GB GPU | IT room |
 
 Office audio intake and gate approvals happen from ordinary staff laptops
 on the `lan` VLAN through the same proxy; no dedicated machine. Stations
 run a kiosk browser (`cage` plus Firefox or Chromium) pointed at the
 application; badge readers and scanners are USB HID keyboard devices, so
 there is no driver work. Sixteen plant machines at launch, about twenty-one
-at maturity; every one is a directory and a line in the inventory.
+at maturity, plus `vinyl-ai` if the assistant needs it; every one is a
+directory and a line in the inventory.
 
 ## Networks
 
@@ -984,6 +987,10 @@ options, which come back with the quotes. Fleet pieces already paid for
 | Clan modules, router extensions, collectors, dashboards and rules to commissioning | 1 to 2 person-months |
 | Vision, metrology and audio pipeline integration (Launch and Expand) | 3 to 5 person-months, plus integrator fees in the vision quote |
 
+The plant assistant's GPU server, if it is bought, is costed in
+[plant assistant](plant-assistant.md#rough-cost-estimates), not in this
+total.
+
 Headcount note: [scale](scale.md) lists no IT or automation role in the
 15 to 25 people. Running this needs one automation and IT engineer from
 Build onward, part-time at launch; add it to the headcount.

docs/plant-assistant.md

@@ -0,0 +1,244 @@
+# Plant Assistant: Ask the Plant
+
+Decided (Alexander, 26 October 2026): **the plant gets an agent that
+management and operators can ask**, which reads the plant's knowledge
+base and its data and gives insight into the process. This document plans
+it on the systems of the [digital factory](digital-factory.md): ERPNext as
+the system of record, the machine-data store, the factory application and
+the NixOS fleet. It is a planning position; every figure without a source
+is an estimate.
+
+## In one paragraph
+
+One assistant for the whole plant, asked in Thai or English at a press
+kiosk, at a desk or on a phone. It answers from two places: **the
+knowledge base** (procedures, vendor manuals, safety rules, this planning
+repository) and **the records and data** (ERPNext documents, press cycles,
+inspection results, time series, alarms). Every answer names its sources;
+every number comes from a query it shows. It sees only what the person
+asking may see, it can draft but never submit a record, and it never
+touches a machine. It runs on site on an open-weights model, so it works
+when the internet does not.
+
+## Who asks what
+
+| Who | Typical questions | What it uses | Where |
+|---|---|---|---|
+| Press operator | "What is the band for the mould temperature at 180 g on the Classic?" "Non-fill rejects since 14:00, what changed?" "Show me the stamper change steps for the HRP 12." "Is compound lot L-0412 released?" | Quality Procedures (the SOPs), the recipe and inspection templates, the press's cycle rows and zone environment, the lot's Quality Inspection | press kiosk, Thai first, the station and job card already known |
+| Shift lead | "Handover: what happened on the last shift?" "Which stampers are near retirement?" "Downtime by reason this week." | job cards, downtime entries, stamper serial numbers and play counts, open holds, alarms | kiosk, office |
+| QC engineer | "Trace the record with this sleeve code." "Compare today's run of this title with the last repress." "Audio score against play count for stamper S-1187." | the record key's chain (cycle, stamper, mother, lot, environment) per [traceability](traceability.md), inspection results, audio scores | office |
+| Maintenance | "Alarm history of boiler B-1 this month." "Hours since the last oil change on the Duplex hydraulics?" "Page of the manual for the chiller's low-pressure fault." "Is the seal kit in stock?" | alarm history, run hours, ERPNext Asset Maintenance and stock, the vendor manuals attached to the Asset | workshop kiosk, phone |
+| Cutting and galvanics | "Current density in cell 2 over the last father." "Which mothers of POY013 have sets left?" | rectifier and bath series, metal-part serial numbers | room kiosks |
+| Management | "Yield and effectiveness per press this week, and why the Classic dropped." "Energy per record against the plan." "Orders at risk of missing their date." "Which gates are waiting on customers?" | ERPNext reports, the machine-data store, the design figures in this repository | office, phone |
+| Customer service | "Where is order SO-0231, and when will it ship?" | the same records the customer portal shows | office |
+| New staff and trainees | "Why must labels be dried before pressing?" | procedures and the training material, never live customer data | training mode |
+
+## What it knows
+
+### The knowledge base: what should happen, and why
+
+| Source | Where it lives | Notes |
+|---|---|---|
+| Procedures and work instructions (SOPs), safety procedures, emergency steps | ERPNext **Quality Procedure** documents: structured, nested steps, versioned; a **Non Conformance** links to the procedure it breaks and a **Quality Action** carries the fix ([ERPNext docs](https://docs.frappe.io/erpnext/user/manual/en/non-conformance)) | the SOPs are written into ERPNext during commissioning, not kept as loose files |
+| Vendor manuals, datasheets, site requirements | attached to the ERPNext **Asset** (each press, boiler, chiller, lathe, cell) and Item | the vendor PDFs already filed under `docs/equipment/` are the first ones |
+| Recipes and limits | Item, BOM and Quality Inspection Templates (parameters and limits from [quality automation](quality-automation.md)) | |
+| Why the plant is built as it is | this planning repository, indexed from git | utility sizing, the metal archive, the QC layers, the decisions and their dates |
+| Lessons learned | Non Conformance and Quality Review records with their actions | |
+| Thai and English terms | a glossary document (stamper, mother, non-fill, flash, run-out) | keeps the Thai answers consistent |
+
+Only **approved, current** versions are indexed. Superseded versions stay
+available for "what did the procedure say on 3 March?", marked as
+superseded.
+
+**Tacit knowledge is the part worth catching.** P-Vine's pressing staff
+describe a room that changes every day with the weather despite air
+conditioning, so the settings (boiler temperature, a few seconds more or
+less of press time) are adjusted daily by feel
+([ele-king, VGAP interview](https://www.ele-king.net/vga/vga_column/011864/);
+[BRUTUS](https://brutus.jp/en/post-430468/)). Here every adjustment is a
+logged event next to the zone environment, so the assistant can answer
+"last time the press hall was this humid, what did the operator change,
+and did the rejects fall?" from the data, and a question nobody could
+answer goes to the shift lead as an ERPNext ToDo; the expert's answer,
+once approved, becomes a procedure note. The knowledge base grows from
+the floor's own questions.
+
+### The records and data: what did happen
+
+- **ERPNext**: work orders, job cards, batches, quality inspections,
+  metal-part serial numbers and their genealogy, downtime entries, stock,
+  sales orders, gates, deliveries, assets and maintenance
+  ([who owns what](digital-factory.md#who-owns-what)).
+- **Machine-data store**: press cycles, per-record optical results, audio
+  scores, packaging scans and the hash-chained event log in PostgreSQL;
+  1 Hz machine tags, zone environment, energy and water in VictoriaMetrics
+  ([design decision 2](digital-factory.md#design-decisions)).
+- **Alarms**: vmalert and Alertmanager history.
+- **Catalogue data**, for those who may see it
+  ([own catalogue](catalogue-intelligence.md)).
+
+## What it does with it
+
+1. **Answers with sources**: the procedure step and its version, the
+   ERPNext document names, the query and time window behind a number.
+2. **Explains a number**: yield down this week is broken down by press,
+   title, stamper, compound lot, shift and zone environment. What moves
+   together is reported as a correlation, never as the cause.
+3. **Traces**: from a sleeve code or a complaint back through cycle,
+   stamper, mother, lot and environment, in one answer.
+4. **Summarises**: a handover note at each shift start (open holds,
+   stampers near the end of their life, lots on hold, excursions,
+   downtime), a daily plant note and a weekly management note.
+5. **Adds context to alerts**: when vmalert fires, the alert still goes
+   out through Alertmanager unchanged; the assistant follows it with what
+   changed in the half hour before (lot start, stamper change, humidity,
+   a neighbouring alarm).
+6. **Compares against the plan**: actual cycle times, steam and energy per
+   record, reject rates and repress lead times against the figures in
+   this repository ([scale](scale.md),
+   [production timeline](production-timeline.md)), so the plan learns
+   from the plant.
+7. **Drafts records**: a Non Conformance, a maintenance request, a
+   ToDo, a revision of a Quality Procedure. A person reviews and submits.
+
+## What it never does
+
+- **Touches a machine.** No writes to a PLC, an instrument, a recipe or a
+  setpoint; the data platform is read-only toward machines
+  ([design decision 4](digital-factory.md#design-decisions)).
+- **Submits a record.** Drafts only; the person asking submits.
+- **Improvises on safety.** For lockout, steam and boilers, hydraulics,
+  galvanics chemistry, the crane and electrical work it quotes the
+  approved procedure word for word with its version and names the
+  responsible person. With no approved procedure it says so and stops. It
+  is not an alarm and not an emergency channel
+  ([worker safety](worker-safety.md)).
+- **Sees more than the asker.** Every tool call runs with the asker's
+  ERPNext role: an operator sees the job, not the customer's price;
+  customer service sees orders, not payroll. The client audio vault and
+  customers' artwork are never indexed. Questions that must be refused
+  are part of the test set below.
+- **Answers from memory.** A figure without a query or a document behind
+  it is not given; missing data is said to be missing.
+- **Rates people.** Operators' questions are logged to improve the
+  answers and the procedures, not to assess the operator; that goes into
+  the staff policy, and the logs are kept for a limited time (staff are
+  data subjects under the PDPA).
+- **Needs the internet.** Model, index and tools all run on site
+  ([design decision 8](digital-factory.md#design-decisions)).
+
+## How it is built
+
+- **Model.** Open weights, Thai and English, served on site. The first
+  candidate is **Typhoon 2.5** from SCB 10X, a Thai fine-tune of
+  Qwen3-30B-A3B for Thai and English with a 256K context, Apache-2.0
+  ([model card](https://huggingface.co/typhoon-ai/typhoon2.5-qwen3-30b-a3b),
+  checked October 2026), with a 4B sibling for quick kiosk answers. It
+  is a mixture-of-experts model with about 3B parameters active per
+  token, so it may run usefully on a CPU server before any GPU is bought
+  (to be measured). The choice is made on our own test set, not on
+  published benchmarks.
+- **Serving.** llama.cpp or vLLM as a NixOS service on the clan, like
+  every other plant service.
+- **Speech, optional.** **Typhoon ASR Real-time**: open-source streaming
+  Thai speech recognition that runs on CPUs, Apache-2.0
+  ([model](https://huggingface.co/typhoon-ai/typhoon-asr-realtime),
+  [code](https://github.com/scb-10x/typhoon-asr)). Its authors name
+  background noise and Thai-English code-switching as weaknesses, both of
+  which the press hall has, so push-to-talk with a headset and a test on
+  the floor come before any promise.
+- **Retrieval.** Document chunks with embeddings in PostgreSQL with
+  pgvector on `vinyl-core`, rebuilt from the sources (Quality Procedures
+  and attachments in ERPNext, the repository). Derived and rebuildable;
+  no business records.
+- **Tools.** Exposed to the model over the Model Context Protocol, each
+  a thin wrapper in `cnx-factory`:
+  - ERPNext through the existing integration client, read as the asker,
+    create drafts only;
+  - SQL on the machine-data store through the **PostgreSQL streaming
+    replica on `vinyl-backup`**, read-only with row and time limits, so a
+    heavy question never slows the floor;
+  - PromQL on VictoriaMetrics' read API;
+  - document search, the event log and alarm history.
+
+  An open-source MCP app for ERPNext exists (Frappe Assistant Core,
+  AGPL-3.0); it runs inside Frappe as a second way into ERPNext, which the
+  rule of one integration layer
+  ([how every tool interacts](digital-factory.md#how-every-tool-interacts-with-it))
+  does not allow, so its ideas are reused and the tools stay in
+  `cnx-factory`.
+- **Front ends.** An "Ask" panel in the factory application: on the
+  station kiosks with the station, job card and the operator's language
+  filled in, on office desktops, and on phones over the mesh. Same badge
+  and sign-on identity as everything else.
+- **Machine.** `vinyl-ai` in the IT room: one server with a 32 GB GPU.
+  An RTX 5090 32 GB sells in Thailand for about 203,000 to 209,000 THB
+  ([Advice](https://www.advice.co.th/product/graphic-card-vga-/nvidia-5000-series/vga-asus-geforce-rtx-5090-rog-astral-gaming-32gb-gddr7);
+  JIB via [BigGo](https://biggo.co.th/s/rtx%205090%2032gb); October 2026), so the server is roughly 250,000
+  to 300,000 THB (~7,500 to 9,000 USD, estimate). The cheaper start is
+  CPU-only on the dev trio and then on `vinyl-core`, with the GPU bought
+  only if answers are too slow for the kiosks.
+
+## Keeping it right
+
+- **A test set per role**, in Thai and English: questions with known
+  answers from the procedures and from recorded history, plus questions
+  it must refuse (another customer's order, payroll, a safety step with
+  no approved procedure). It runs on every change of model, index or
+  tool, and nothing is deployed that fails it, the same rule as an
+  ERPNext upgrade.
+- **Feedback** on every answer; wrong answers are reviewed weekly by the
+  QC lead, and the fix goes into the source (the procedure, the glossary,
+  the data), not into a prompt.
+- **Measures**: share of answers with a source, share of questions it
+  could not answer, time to answer, use per role, incidents where it was
+  wrong.
+- **Owners**: the automation and IT engineer the digital factory plan
+  adds to the headcount runs it; the QC lead owns the content.
+
+## Phasing
+
+| Roadmap phase | Step |
+|---|---|
+| 0 to 1, now | Prototype on the dev trio over this planning repository: the team asks the plan ("how much steam does the launch plant need, and why?") in Thai and English, CPU-only; the test-set habit starts here |
+| 3, build | SOPs written as Quality Procedures during commissioning (vendor training sessions recorded and transcribed into procedures), manuals attached to the Assets; assistant v1 on documents and ERPNext records; `vinyl-ai` installed if the CPU trial says so |
+| 4, launch | "Ask" on the kiosks with station context; machine-data and alarm tools; shift handover notes; alert context |
+| 5, expand | Voice at the presses if the floor test passes; the catalogue advisor as one of its roles; galvanics and audio QC data; offered with the open plant stack to other plants ([digital factory](digital-factory.md#open-source-throughout-and-working-with-other-plants)) |
+
+## Rough cost (estimates)
+
+| Item | Estimate |
+|---|---|
+| `vinyl-ai` server with one 32 GB GPU | 250,000 to 300,000 THB (~7,500 to 9,000 USD); none while CPU-only |
+| Tools, retrieval and the "Ask" panel in `cnx-factory` | 2 to 3 person-months |
+| Test set and evaluation harness | 0.5 person-month, then part of the IT role |
+| Speech at the kiosks | 0.5 person-month plus headsets |
+| Writing the SOPs into ERPNext | part of commissioning and training, not IT time |
+
+Not in the [digital factory](digital-factory.md#rough-cost) hardware total
+or in the [total investment](finance/total-investment.md).
+
+## Risks
+
+- **A confident wrong answer.** Sources on every answer, no source no
+  answer, and the safety quoting rule carry most of it; the test set
+  catches the rest before a release.
+- **Stale procedures.** Only approved versions are indexed, and every
+  answer shows the version and date.
+- **Training replaced by asking.** It supports training; training and
+  sign-off stay with the supervisors and the safety programme.
+- **Noise and gloves.** Voice is optional and tested on the floor first;
+  the touch panel always works.
+- **Leaks across customers.** Permissions per asker, refusals in the test
+  set, and no customer audio or artwork in the index.
+
+## Open decisions
+
+1. **Model**: Typhoon 2.5 or another open model, chosen on the test set.
+2. **Hardware**: CPU first and a GPU only if needed (recommended), or
+   `vinyl-ai` from the build.
+3. **Voice** at the presses, after a floor test.
+4. **Web search** for management questions through a fleet-hosted search,
+   or none: the assistant stays on plant data and the repository.
+5. **Log retention** for questions and answers.
+6. **Name** on the kiosks.

docs/roadmap.md

@@ -129,7 +129,9 @@ These three run in parallel and gate everything downstream:
     order in [digital-factory.md](digital-factory.md); the network, servers
     and edge collectors go in before the machinery arrives)
 18. Hire and train the launch team; safety program stands up with the
-    equipment, not after it
+    equipment, not after it. Procedures are written as ERPNext Quality
+    Procedures during commissioning, the knowledge base the
+    [plant assistant](plant-assistant.md) answers from
 
 ## Phase 4: Launch (the whole chain in-house)
 

docs/worker-safety.md

@@ -7,7 +7,10 @@ commitments:
   maintenance staff, starting with the vendor-led commissioning training and
   extending into an ongoing in-house program. The pressing line combines
   hydraulics (~180 bar), saturated steam (10 bar / 180 °C), and hot PVC, and
-  every one of these demands trained, deliberate handling.
+  every one of these demands trained, deliberate handling. The
+  [plant assistant](plant-assistant.md) quotes the approved safety
+  procedures word for word and never improvises one; it supports this
+  training and does not replace it.
 - **Clean rooms for galvanics**: silvering and stamper electroforming will
   run in dedicated clean rooms with controlled access, proper ventilation and
   exhaust, and decontamination procedures for people and equipment leaving