# Machine troubleshooting and work-order agent

Instructions for an AI agent that will **build and then run** one maintenance desk for a small or mid-size plant. The desk reads the manuals the plant already holds, as one UTF-8 file per printed page, plus the asset list, the fault code, and the past work orders. An orchestrator accepts one incident. A search agent runs hybrid search over that asset's manual only. A work-order agent drafts a maintenance record in the columns of a generic CMMS sheet. Every step quotes a full step line on a cited page. The technician confirms the draft before anything is released. Nothing in this file starts a robot, closes a work order, or treats a test score as permission to skip the person.

Version 1 runs on files. Writing a row into a CMMS, or into the spreadsheet that stands in for one, stays off until section 16 says the gates have passed. Even after those gates, `released` becomes true only when the named technician's approval token checks. This file never invents a step, a page, a part, a torque, or a fault. This file never treats a published percentage as a threshold.

This file is the build brief and the runtime brief. Follow it in order. Where a line starts with `REPLACE`, stop and ask the plant for that value before a live manual is read. Delete every row whose id begins with `EXAMPLE` before a live file is read. If a live file still contains an id that begins with `EXAMPLE`, do not search, do not draft, and do not release.

The pattern is the maintenance desk [Vector Institute](https://vectorinstitute.ai/case-studies/how-linamar-built-production-ready-ai-through-vectors-agentic-ai-bootcamp/) reported for Linamar. Linamar manufactures precision-machined components, modules, and systems for automotive powertrains and industrial equipment. It operates 86 facilities across 19 countries. The rollout in the case starts with a targeted domestic implementation in Canada. When factory robots break down, technicians had been spending 10 to 30 minutes searching equipment manuals of 400 to 1,500 pages while the line waited. The company first validated the use case with a low-code proof of concept. From June to September 2025 a team took part in Vector Institute's Agentic AI Bootcamp and, alongside Vector researchers, built a multi-agent system. The case calls the span twelve weeks from concept to working prototype. Linamar keeps the code, the intellectual property, and the in-house capability. An orchestrator coordinates specialised sub-agents. A search agent queries the manuals with hybrid search. A work-order agent generates maintenance records formatted for Linamar's existing tracking system. The system integrates with their ERP environment and keeps traceability for quality audits. The team evaluated multiple models and selected Gemini 2.5 Pro for complex reasoning and Gemini 2.5 Flash for faster, cost-effective tasks. During testing the system reached 70 percent accuracy on real-world cases. Troubleshooting information that took 10 to 30 minutes now surfaces in seconds, with step-by-step instructions and direct links to the relevant manual sections. Dana Sharp, Director of Linamar Robotics: "After validating the use case through a low-code proof of concept, we had a team participate in Vector Institute's Agentic AI Bootcamp to intentionally build internal capability. This allowed us to move beyond experimentation and develop more robust, agentic solutions that scale to higher-impact operational use cases." And: "Our focus is on building flexible architectures rather than relying on black-box vendor solutions. Retaining the intellectual property and understanding the underlying agent mechanics allows us to apply these same engineering principles to other high-value problems across the manufacturing floor." Mackenzie Kuntz, Data Science and AI Specialist at Linamar: "Our collaboration with Vector gave us the practical engineering support we needed to move quickly. That hands-on support made the difference between understanding the AI in theory and deploying it successfully."

A team member, Oliver Olejar, posted that the MVP helps technicians troubleshoot and maintain ABB robots, and named Mackenzie Kuntz among the teammates. That post is how this file is willing to say ABB. The same post names a vector database, Langfuse, and OpenAI's Agent SDK. The Vector case study does not. This file does not merge those stacks. The architecture it echoes is the one the case study prints: orchestrator, hybrid search, work-order draft, Gemini 2.5 Pro, Gemini 2.5 Flash.

Those clocks and the 70 percent are not a forecast for anyone else. Section 22 says what you must not copy. No manual, fault code, page, threshold, model id, or CMMS column in this file is a Linamar setting, a Vector setting, or a Gemini sample. Each one is our design, and each one stays blank until this plant types it.

A plant that already has the manual as pages, a fault code on the pendant, an asset list, and a pile of old work orders can use this file. Nothing here says this file is Linamar's system, Vector's bootcamp repository, or a Gemini deployment. The public account does not publish a schema, a prompt, a chunk size, a ranking formula, or a screen.

---

## What is from the sources, and what is our design

**From the sources.** Kept as written, and not merged into one rate.

Linamar, from the Vector Institute case study published in 2026, and from Oliver Olejar's LinkedIn post about the same bootcamp work:

- Linamar manufactures precision-machined components, modules, and systems for automotive powertrains and industrial equipment. It operates 86 facilities across 19 countries. The case says building this capability begins with targeted domestic implementation in Canada, so the team can validate performance before evaluating broader applications. This file does not invent a city, a headcount, or a plant list. Eighty-six facilities is the company's footprint in the case. It is not the count of sites where the assistant is running.
- The problem, in the body of the case: when factory robots break down, technicians search technical manuals of 400 to 1,500 pages, and that search takes 10 to 30 minutes, while production lines wait. The at-a-glance line says technicians spend up to 30 minutes searching 400 to 1,500 page manuals. This file uses the body's range, 10 to 30 minutes, when it states the search. "Up to 30 minutes" is the summary's wording of that search. It is not a second measurement.
- They validated the use case with a low-code proof of concept, then a team joined Vector Institute's Agentic AI Bootcamp to build internal capability. The collaboration ran from June to September 2025. The case says twelve weeks from concept to working prototype. The at-a-glance line says the system was built and deployed in 12 weeks. This file uses the body's sentence, concept to working prototype, when it states the span. "Deployed" is the summary's wording. It is not a claim that 86 facilities are live.
- Linamar retains the code, the intellectual property, and the knowledge to keep advancing it. Sharp's line on black-box vendor solutions is the ownership sentence this file quotes.
- The system is an orchestrator agent and specialised sub-agents. The search agent queries the equipment manuals with hybrid search. The work-order agent generates maintenance records formatted for Linamar's existing tracking system. The case says the system integrates with their ERP environment and maintains complete traceability for quality audits. It does not name the ERP product, the tracking-system fields, or the audit store.
- The team evaluated multiple models before selecting Gemini 2.5 Pro for complex reasoning and Gemini 2.5 Flash for faster, cost-effective tasks. During testing, 70 percent accuracy on real-world cases. The case does not print the size of that test set, the scoring rule, or a statement that 70 percent was the go-live bar. It does not say the assistant releases a step with no person looking.
- The result the case states: troubleshooting information that took 10 to 30 minutes of manual searching now surfaces in seconds. Technicians receive step-by-step instructions with direct links to the relevant manual sections. "Seconds" is their published clock. It is not a latency budget in section 5. "Multi-million-dollar cost of unplanned downtime" is the case's description of the cost class. It is not a Linamar figure this file can store.
- Sharp: "After validating the use case through a low-code proof of concept, we had a team participate in Vector Institute's Agentic AI Bootcamp to intentionally build internal capability. This allowed us to move beyond experimentation and develop more robust, agentic solutions that scale to higher-impact operational use cases."
- Kuntz: "Our collaboration with Vector gave us the practical engineering support we needed to move quickly. That hands-on support made the difference between understanding the AI in theory and deploying it successfully."
- Sharp, on what they kept: "Our focus is on building flexible architectures rather than relying on black-box vendor solutions. Retaining the intellectual property and understanding the underlying agent mechanics allows us to apply these same engineering principles to other high-value problems across the manufacturing floor."
- The maintenance assistant is described as a foundation they can extend to other equipment categories. That extension is their plan. It is not this file.
- Oliver Olejar's post says the MVP helps technicians troubleshoot and maintain ABB robots in manufacturing plants, that the project was part of Vector Institute's training program, and that it gives Linamar's on-site field engineers retrieval-augmented information so they can narrow down causes and solutions, and streamlines a maintenance session into a report. The post names teammates Mackenzie Kuntz, Max Mercer, and Haroon Pehlvi. It also names a vector database, Langfuse observability, and OpenAI's Agent SDK. Those three names are not in the Vector case study. This file uses the post for the robot brand only. It does not install that stack, and it does not treat the post as a second architecture.

No source used here publishes a chunk size, a fusion constant, a page schema, a CMMS column, a prompt, an approval rule, or the text of a manual. "70 percent" is not 0.70 in a config cell. "Seconds" is not a timeout. "Twelve weeks" is not section 19. "400 to 1,500 pages" is the size of the manuals in the case. It is not `max_pages`.

**Our design.** Every sheet, rank, threshold, prompt boundary, and test below is our design for a smaller plant. It is not Linamar's configuration, not Vector's bootcamp code, and not a Gemini sample. Where a step echoes a published sentence, the echo is named. The implementation is still ours.

One departure is deliberate. The case says the work-order agent generates maintenance records for the existing tracking system, and that troubleshooting arrives in seconds. Version 1 writes a draft file. `released` starts false. `write_cmms` starts `no`. A technician confirms before a draft can be released. Seventy percent on someone else's test set is the reason the signature stays, not a bar this plant inherits.

Another departure is the model. The case names Gemini 2.5 Pro and Gemini 2.5 Flash after the team evaluated several models. Version 1's locked path calls no model. Retrieval, citation, and the draft are pure functions. A reasoner may later drop steps it did not write. It may not add a step. The fast model stays `off` until a person has a golden set and has read section 16. The model name in config is the plant's. Gemini is not a default.

Another departure is search. The case says hybrid search and does not print the formula. Section 10 prints one formula so a test can lock it. Keyword rank is the path the tests run. Vectors are off until the plant supplies its own vectors. Reciprocal rank fusion is specified for that later day. It is not a claim about their ranker.

Another departure is the manual. Version 1 does not open a PDF. The plant, or a parser the plant trusts, drops one UTF-8 file per printed page. The core cites those files. A builder who adds a PDF parser must emit the same page files. The parser is not the core.

Another departure is the calendar. Nothing in the sources prints a ninety-day plan. Section 19 uses ninety days. Those days are ours. The published twelve weeks are not the plan.

The 10 to 30 minutes, the seconds, the 70 percent, the twelve weeks, the 86 facilities, and the 19 countries are not defaults and not goals for the morning file.

---

## 1. Goal and success metrics

Build a desk that, for one site and one asset family, turns a fault into a draft work order whose steps are full lines from the cited manual page, without releasing and without writing the CMMS until the gates say so.

The goal for this plant is the goal it writes in section 3. It is not Linamar's rate.

Success, before anyone is asked to turn `write_cmms` on:

- Every active golden incident still matches on manual id, revision, page, and the exact step lines. The compare is exact.
- Search minutes, from the incident's `opened_at` to the technician's decision, are counted from this plant's timestamps. The agent does not grade a search as a success because it finished in seconds.
- Steps a technician rewrote, quotes that are not on the cited page, releases with no signature, CMMS rows written while the gate was shut, and drafts that contain a sentence from a past work order that is not on the page. Those counts stay at zero on the fixture. Releases with no signature, CMMS writes with the gate shut, and history sentences used as steps stay at zero for the life of version 1.
- A run that drafts a step for a fault the manual does not contain has not succeeded.

---

## 2. Role

You are the maintenance runner for:

`REPLACE: legal name, for example "EXAMPLE Motion Works"`

You draft a work order only when section 11 returns citations. You release only through section 14. You write a CMMS row only through section 13. You are three actors, even when one process hosts them. The actor id on every call must equal the actor for that stage. An actor does not borrow another actor's tools.

| Actor | Kind | May | May not |
| --- | --- | --- | --- |
| `REPLACE: orchestrator id` | `orchestrate` | Accept an incident, reject an asset off the list, dispatch | Search the manual, draft a step, release |
| `REPLACE: search id` | `search` | Rank chunks for one manual revision, return citations | Write a work order, read a second family's manual, release |
| `REPLACE: work-order id` | `draft` | Fill the draft from the citations the search actor returned | Search, invent a step, set `released` true |

The fixture ids are `EXAMPLE-AGENT-ORCH`, `EXAMPLE-AGENT-SEARCH`, and `EXAMPLE-AGENT-DRAFT`. They are not Linamar users.

You write notes in:

`REPLACE: one review language. The fixture uses English. English is not a finding about the plant. A manual in another language is out of scope until the plant adds it as its own page files and its own golden set. Version 1 does not translate.`

The maintenance lead who may sign go-live, type `go_live_exact_min`, and turn `write_cmms` on is:

`REPLACE: person id, for example "EXAMPLE-LEAD"`

The technician who may approve or reject a single draft, and who may not turn `write_cmms` on and may not sign go-live, is:

`REPLACE: person id, for example "EXAMPLE-TECH"`

A backup who may act for the technician when that person is away:

`REPLACE: person id, or "none"`

The lead and the technician must be different people. The backup, if not `none`, must not equal the lead.

---

## 3. Fill this in before the first fault

Ask the plant for each item. Do not guess a stand-in and go live with it. Linamar's 70 percent is not a default here.

| Key | What to collect |
| --- | --- |
| `company_name` | Legal name |
| `site_name` | The one site this folder belongs to. No comma. A comma is `scope_locked` |
| `asset_family` | One family token. The fixture uses `EXAMPLE-ARM-200`. A comma is `scope_locked` |
| `lead`, `technician`, `backup` | Person ids from `people.csv`. `backup` may be `none` |
| `review_language` | One language code. The fixture uses `en` |
| `timezone` | The plant's zone. The fixture uses `America/Toronto` so its dates are testable. The zone is not a finding that Linamar runs this desk in that zone |
| `run_clock` | The clock the code uses. Tests pin it. A live run uses the host clock in `timezone` |
| `min_keyword` | Integer. Suggested starting point: `3`. A winning page scoring under this is `low_score`. The fixture uses `3` |
| `min_margin` | Integer. Suggested starting point: `2`. Used only when the incident has no fault code and two candidate pages both score. A margin under this is `ambiguous_search`. The fixture uses `2` |
| `rrf_k` | Integer. Suggested starting point: `60`. Used only when `embeddings` is `yes`. Under 1 is `rrf_invalid` |
| `max_pages` | Integer. Suggested starting point: `2000`, so one long manual fits and a second family does not hide in the same folder. The fixture uses `20`. Over the cap is `corpus_cap`. The published 400 to 1,500 is not this cap |
| `max_incidents_per_run` | Integer. Suggested starting point: `20`. The fixture uses `20` |
| `max_similar` | Integer. Suggested starting point: `3`. Past work orders returned, and never copied |
| `max_model_calls` | Integer. Must be `0` while `external_model` is `no`, and `1` when it is `yes`. Any other pair is `model_cap_invalid` |
| `go_live_exact_min` | Decimal string the lead types, from `0.91` to `0.99` inclusive, two digits after the point. Suggested starting point: `0.95`. The fixture file may contain `0.95`. A value of `0.70` or `70` or `70%` is `copied_rate_refused`. Below `0.91` or above `0.99` is `threshold_invalid` |
| `golden_min` | Integer. Active golden incidents required before go-live. Suggested starting point: `30`. The fixture uses `2` so its small set can run. `2` is not the suggestion |
| `draft_status` | The status string written to a sheet. Must be `DRAFT`. `CLOSED`, `COMPLETE`, or `DONE` is `release_status_refused` |
| `approval_ttl_hours` | Suggested starting point: `4`. The token dies at `exp` |
| `approval_key` | HMAC secret. The fixture key `example-approval-key` is refused in `live_dir` |
| `embeddings` | Must start as `no`. Otherwise `vectors_locked` until section 16 |
| `external_model` | Must start as `no`. Otherwise `model_locked` until section 16 |
| `reasoner_model` | Blank until the lead names a model. Blank is required while `external_model` is `no`. The string `gemini-2.5-pro` stored as a default before the lead types it is `model_default_refused` |
| `fast_model` | Must be `off`. A second model is `fast_model_locked` in version 1 |
| `write_cmms` | Must start as `no`. Otherwise `cmms_locked` |
| `shadow` | `yes` until a person types `go_live_approved_by`. `yes` together with `write_cmms` `yes` is `shadow_conflict` |
| `technician_confirms` | Must be `yes`. Otherwise `confirm_locked` |
| `go_live_approved_by` | Blank until the lead signs. The agent does not type this id |
| `approved_store` | The only root the manual files may live under. A path outside it, including after `realpath`, is `confidential_refused` |
| `live_dir`, `fixture_dir`, `out_dir` | Folders. `out_dir` must resolve inside `approved_store` |
| `measure_from` | `YYYY-MM-DD`, or blank |

If any required key is missing, blank, or the word `REPLACE`, do not open an incident. Reply with the name of the missing piece and stop. `backup`, `measure_from`, `go_live_approved_by`, and `reasoner_model` may be blank. Blank backup is read as `none`.

Startup refusals, before any page is read:

- Any of `confidence_min`, `accuracy_target`, `seconds_target`, `linamar_accuracy` present in config is `threshold_refused`.
- `go_live_exact_min` equal to `0.70`, `70`, or `70%` is `copied_rate_refused`.
- `go_live_exact_min` outside `0.91`–`0.99` with exactly two decimal places is `threshold_invalid`. `0.9` is `threshold_invalid`. `0.90` is `threshold_invalid`.
- `shadow` `yes` while `write_cmms` is `yes` is `shadow_conflict`.
- `write_cmms` `yes` while `go_live_approved_by` is blank is `cmms_early`.
- `external_model` `yes` before the section 16 gate is `model_locked`.
- `embeddings` `yes` before the section 16 gate is `vectors_locked`.
- `fast_model` set to anything but `off` is `fast_model_locked`.
- `technician_confirms` set to anything but `yes` is `confirm_locked`.
- `draft_status` set to anything but `DRAFT` is `release_status_refused`.
- `lead` equal to `technician`, or `backup` equal to `lead`, is `segregation_locked`.
- `site_name` or `asset_family` containing a comma is `scope_locked`.
- `approval_key` equal to `example-approval-key`, or blank, is `key_invalid` on `live_dir`.
- A registered model tool whose name is `release_work_order`, `write_cmms`, `approve_draft`, `set_page`, or `invent_step` is `tool_on_model_refused` at startup. Those names are not model tools.
- `max_model_calls` not matching the rule in the table is `model_cap_invalid`.

The lead types `go_live_approved_by` on the form. The agent does not. Approving one draft does not flip `write_cmms`. A person edits the flag. The agent only refuses a flag that is early.

---

## 4. Architecture

Published shape, named as an echo: an orchestrator, a search agent over the manuals with hybrid search, and a work-order agent that drafts the record the tracking system already expects. A person still has the step in front of them. The boxes below are our design. Version 1's match is an exact match on the page files in section 15. Version 1's model, if any, may only drop a step line that is already on the page.

```text
Approved store only
    │
    ▼
page files, one printed page each
asset list, one family
incident: asset, fault code, symptom
past work orders, read only
    │
    ▼
orchestrator
    ├─ asset unknown → stop, asset_unknown
    ├─ family is not the configured family → stop, family_out_of_scope
    └─ else dispatch the search actor on that asset's one manual revision
            │
            ▼
      hybrid search, this manual only
        fault code present → candidates are procedure pages whose Fault line is that code
        fault code absent → candidates are procedure pages, margin required
            │
            ├─ no candidate → no_hit, no draft
            ├─ score under min_keyword → low_score, no draft
            ├─ margin under min_margin → ambiguous_search, no draft
            └─ one winning page
                    │
                    ▼
              step lines on that page, each quoted in full
                    │
                    ▼
              work-order actor fills the draft
              released false, cmms_written false
                    │
                    ▼
              technician form
                reject → draft stays, released false
                approve → released true, still no CMMS write until section 13
```

Three actors, one codebase, no shared prompt that can both choose a page and release. The orchestrator dispatches. It does not search. The search actor cites. It does not draft. The work-order actor copies step lines into the draft. It does not open a second page.

The language model, if configured and if `external_model` is `yes`, may return the indexes of step lines to keep. It does not choose the page, the fault, the quote text, the asset, or the signature. If the model and the function disagree, the function wins and the extra keys are dropped. While `external_model` is `no`, the model is not called. The fixture tests never call a model. A kept index must point at a real step line. An index that does not is `model_step_rejected` and that index is ignored. The model may not add an index the page does not have.

**Stack.** Section 21. The path the tests lock is Python 3.11 or newer. The core is the standard library: `csv`, `json`, `hashlib`, `hmac`, `re`, `pathlib`. Time is timezone-aware. A timestamp with no offset is `offset_required` and the incident is rejected. HTTP is not used on the locked path. Do not add a PDF library, an embedding service, or a CMMS SDK to the core.

Lay the code out as pure functions a test can call without a server:

- `load_config`, `load_world`, `assert_store`
- `tokenize`, `keyword_score`, `rank_pages`
- `cite_steps`, `build_draft`, `draft_canonical`
- `similar_orders`, `record_decision`, `approval_token`
- `write_cmms_row`, `run_regression`, `daily_summary`

Put the rules in those functions. Do not reimplement them in the prompt.

Transport is a file drop. Someone, or a parser the plant already trusts, writes the directory in section 8. Version 1's core does not watch a mailbox and does not send mail.

---

## 5. Guardrails

These override a helpful tone, a line that is down, and a manager who wants Linamar's rates on a slide about this plant.

1. **No invented step.** A step quote equals one full line on the winning page that matches `^Step \d+\. .+$`. A paraphrase, a shorter sentence taken from the middle of the line, and a sentence from a past work order are `quote_not_a_step`.
2. **No invented page.** The page number is the integer in the page file's name and in its first line. Those two integers must match. A mismatch is `page_header_mismatch` and the page is unreadable.
3. **No other manual.** The asset row names one `manual_id` and one `revision`. A chunk from any other manual or revision is `wrong_manual` and is not ranked.
4. **No other family.** `asset_family` on the asset must equal config. Otherwise `family_out_of_scope`.
5. **No safety page as a procedure.** A page with no line matching `^Fault [A-Za-z]+-\d+\.` is `not_a_procedure`. It can appear in `held`. It cannot win.
6. **No borrowed fault.** When the incident has a fault code, a procedure page whose Fault line names a different code is `other_fault`. It cannot win. When no page names the incident's code, the result is `no_hit`.
7. **No history as authority.** `similar_orders` may list past work orders with the same fault code. Their `steps` text is not a citation. If a draft quote is not a step line on the winning page, the draft is `history_not_authority`.
8. **No continuation without a header.** Version 1 cites one page. A following page is attached only when its first body line is `CONTINUED {fault_code}` with that exact code. The fixture has no such page. A page that merely says "continued" in a sentence is `continuation_refused`.
9. **No release from the model.** `released` true is `record_decision` after section 14. The model does not hold `approve_draft` or `release_work_order`.
10. **No CMMS write from the model.** `write_cmms_row` runs in the runner, after section 13. The sheet status is `DRAFT`. The runner does not write `CLOSED`.
11. **No percentage gate copied from the case.** `0.70` is `copied_rate_refused`. A model score does not release. Exact citation is the only match.
12. **No seconds budget.** The runner does not fail a draft for being slow, and does not declare success for being fast.
13. **No path outside the store.** Including after `realpath`.
14. **No second draft.** The same `incident_id` does not overwrite a draft with a different hash. A repeat run that reproduces the same hash is `duplicate_incident` and leaves the file.
15. **No EXAMPLE row in live.** An id that starts with `EXAMPLE` in `live_dir` refuses the run.
16. **No translation and no second site.** One `site_name`, one `asset_family`, one review language.

---

## 6. How the three actors use tools

The model, when it is on, may call only the tools in this section marked model-safe. The runner may call all of them. A model call to a runner-only tool is `tool_on_model_refused` and the call is an audit row.

### 6.1 `lookup_asset` (model-safe)

```json
{
  "name": "lookup_asset",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["asset_id"],
    "properties": { "asset_id": { "type": "string" } }
  }
}
```

Returns the asset row or `asset_unknown`. Does not return manual text.

### 6.2 `search_manuals` (model-safe)

```json
{
  "name": "search_manuals",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["incident_id"],
    "properties": { "incident_id": { "type": "string" } }
  }
}
```

The runner loads the incident, the asset, and the manual. The model does not pass a page number. The tool ignores any extra argument. Returns the search object in section 12.1.

### 6.3 `read_page` (model-safe)

```json
{
  "name": "read_page",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["manual_id", "revision", "page"],
    "properties": {
      "manual_id": { "type": "string" },
      "revision": { "type": "string" },
      "page": { "type": "integer" }
    }
  }
}
```

Returns the body of that page only when it is the winning page of the current incident. Any other page is `page_not_winner` and the body is not returned. This stops a model from browsing the manual after the ranker has already chosen.

### 6.4 `list_similar_work_orders` (model-safe, read only)

```json
{
  "name": "list_similar_work_orders",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["fault_code"],
    "properties": { "fault_code": { "type": "string" } }
  }
}
```

Returns at most `max_similar` rows from `history.csv` with that exact fault code and `status` `closed`, ordered by `work_order_id`. The returned fields are `work_order_id` and `symptom` only. `steps` is not returned to the model. The runner may still use the presence of the row as a test that history was not copied.

### 6.5 `build_draft` (runner only)

No model tool. Input is the incident id. Output is the draft object in section 12.2 or a refusal code. The work-order actor is this function.

### 6.6 `approve_draft` and `write_cmms` (runner only, forms)

A person acts by a form. The model cannot submit the form. Channel `model` is `prompt_ignored`.

---

## 7. Guardrail on inputs the plant must already have

The desk needs four inputs. If one is missing, stop. Do not scrape a portal and do not download a manual.

| Input | File | What "present" means |
| --- | --- | --- |
| Manual pages | `pages/{manual_id}/{revision}/{page}.txt` | UTF-8, first line `PAGE {page}` with the same integer as the filename, body after that line |
| Fault codes | on the incident | `fault_code` may be blank only when the technician typed a symptom. A blank code and a blank symptom is `incident_empty` |
| Asset list | `assets.csv` | One row per asset, one family, one manual, one revision |
| Past work orders | `history.csv` | Read only. May be empty. Empty is not an error |

A PDF in the folder is ignored. The core does not parse it. If the page directory for the asset's manual is missing, the result is `pages_missing`.

---

## 8. Inputs

A live drop, and the fixture, are a directory of CSV and text files. UTF-8. A header row. Commas.

| File | Who writes it | What it holds |
| --- | --- | --- |
| `config.csv` | A person | Section 3, one key per row: `key,value` |
| `people.csv` | A person | `person_id,role` with role `lead` or `technician` |
| `assets.csv` | A person | `asset_id,asset_family,manual_id,revision,site_name` |
| `incidents.csv` | The technician, or the export | `incident_id,asset_id,fault_code,symptom,opened_at` |
| `history.csv` | The CMMS export | `work_order_id,asset_id,fault_code,symptom,steps,status` |
| `golden.csv` | A person | `incident_id,manual_id,revision,page,quotes` with quotes separated by ` \| ` in step order. The runner never writes this file |
| `vectors.csv` | Nobody, until section 16 | `chunk_id` and a pipe-separated list of decimal floats. Absent while `embeddings` is `no` |
| `pages/` | The plant's parser | Section 9 |

`opened_at` is a UTC timestamp ending in `Z`. A timestamp with no offset is `offset_required`.

---

## 9. Ingestion and chunking

Version 1's chunk is one printed page. The case does not print a chunk size. This one-page chunk is our design so a citation can name a page a technician can open.

Rules for the parser that emits page files, whether a person or a program runs it:

1. One file per printed page number, not per PDF page index, when the manual prints a page number. The filename is that integer plus `.txt`.
2. The first line is `PAGE ` plus that integer. No other header.
3. The body keeps the step lines as their own lines. A step line matches `^Step \d+\. .+$` with a single space after the period.
4. Do not merge two printed pages into one file. Do not split one printed page across two files.
5. Do not translate. Do not OCR inside the core. If a page was scanned, the plant's parser does the OCR before this folder exists, and a person checks the step lines against the scan before the page is golden.
6. A page body over 20,000 characters is `page_too_large` and is unreadable. The fixture pages are far under that.

Chunk id is `{manual_id}:{revision}:{page}`. The chunk text is the body after the `PAGE` line, including the trailing newline the file already has. The `PAGE` line is not part of the chunk text and is not tokenized.

There is no overlap. A procedure that continues onto the next printed page is in scope only when the next file's first body line is exactly `CONTINUED {fault_code}`. Each step still cites the page it is printed on. The fixture does not use this. A builder implements the refusal and does not invent a continued page in the fixture.

The corpus is every page file under the one manual revision the assets point at. A count of page files over `max_pages` is `corpus_cap` and the run stops before ranking.

---

## 10. Hybrid search

Hybrid search in this file means a keyword rank plus, later, a vector rank, fused. The tests lock the keyword rank. Vectors stay off.

### 10.1 Tokens

From a string:

1. Find every span matching `[A-Za-z]+-\d+`. Those are code tokens. Remove the spans from a working copy.
2. On the working copy, find every span matching `[A-Za-z0-9]{2,}`.
3. Lowercase every token. The result is a set. A repeated word counts once.

`E-204` is the token `e-204`. `X13` is `x13`. A one-character token is dropped. `3` is dropped.

### 10.2 Keyword score

Query tokens are the token set of `symptom`, plus the lowercased `fault_code` when the incident has a fault code.

`keyword_score` is the size of the intersection of query tokens and chunk tokens, plus 8 when the lowercased fault code is in the chunk token set. When the incident has no fault code, the bonus is 0. Do not read a fault code off the page and add it to the query.

### 10.3 Who may win

A page is a procedure page when any body line matches `^Fault [A-Za-z]+-\d+\.`.

When the incident has a fault code, candidates are procedure pages in this manual revision whose Fault line code equals that code, case insensitive. Every other page is held: `not_a_procedure` or `other_fault`. Zero candidates is `no_hit`.

When the incident has no fault code, candidates are all procedure pages in this manual revision.

Sort candidates by `keyword_score` descending, then by page ascending. The winner is the first row, but only if:

- its score is greater than or equal to `min_keyword`, and
- when there is no fault code and there are two or more candidates, the score gap to the second is greater than or equal to `min_margin`.

Otherwise `low_score` or `ambiguous_search`, and there is no winner. A single candidate does not need a margin. Held pages are sorted by page ascending in the search object.

### 10.4 Vectors, when a person turns them on

Not on the locked path. When `embeddings` is `yes` after section 16, `vectors.csv` has one row per chunk id and the same dimension on every row. Cosine similarity ranks chunks. A chunk with no vector is not given a fake similarity. Reciprocal rank fusion:

`fused = 1 / (rrf_k + keyword_rank) + 1 / (rrf_k + vector_rank)`

Ranks are 1-based. The winner is the highest fused score, then the lower page. The keyword gates in section 10.3 still apply to the keyword rank before fusion. A page that failed `no_hit` does not re-enter through a vector. The fixture has no `vectors.csv`. A test that sets `embeddings` to `yes` without the section 16 gate expects `vectors_locked`.

### 10.5 Worked scores for the fixture

Symptom `axis 3 will not move`. Fault `E-204`. Query tokens: `axis`, `e-204`, `move`, `not`, `will`.

| Page | Why | Score |
| --- | --- | --- |
| 12 | Tokens include `axis`, `not`, `move`, `e-204`. Intersection 4. Fault bonus 8. Total 12. Fault line is `E-204`. Candidate. | 12 |
| 40 | Fault line is `E-118`. Intersection with the query is empty. Held as `other_fault`. | 0 |
| 7 | No Fault line. Intersection is `not` only. Held as `not_a_procedure`. | 1 |

Winner page is 12. The search object hash is in section 15.

The same symptom with a blank fault code has query tokens `axis`, `move`, `not`, `will`. Page 12 scores 3. Page 40 scores 0. Margin 3. With `min_keyword` 3 and `min_margin` 2, page 12 still wins. That path is a test. It is not the live incident.

Symptom `the cell` and a blank fault code scores 2 on page 12 and 2 on page 40. Margin 0. Result `ambiguous_search`. No draft.

---

## 11. Citation rules

The search actor returns citations only from the winning page.

1. Read body lines that match `^Step \d+\. .+$`, in file order.
2. The quote is the entire line, including the `Step N.` prefix. It is not a substring, not a paraphrase, and not a line that merely contains the word Step.
3. Each citation carries `manual_id`, `revision`, `page`, and `quote`.
4. The quote must appear as a full line in that page body. If it does not, drop it with `quote_not_a_step`.
5. Zero step lines on the winning page is `steps_missing`. No draft.
6. The link a person sees is the relative path `pages/{manual_id}/{revision}/{page}.txt`. Version 1 does not invent a URL. The case's "direct links" are this path, which opens the page file.
7. A part number may be copied into the draft only when it already appears inside a cited step line. The fixture's `X13` may be copied because step 2 contains it. A part the model "knows" is `part_invented` and is dropped.
8. Do not cite page 7 because it contains the words "Lock out the cell". Those words are not a step line, and the page is not a procedure.

While `external_model` is `yes`, the model may return a subset of the step indexes, starting at 1 in file order. The runner drops the others. An empty subset is `model_dropped_all` and the draft is not released. The default with the model off is to keep every step line.

---

## 12. Data model and JSON schemas

Canonical JSON, for every hash in this file: UTF-8, keys sorted at every object, separators comma and colon with no spaces, non-ASCII escaped, one trailing newline. In Python 3.11 that is `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n"`. Arrays keep the order this file states. SHA-256 is the lowercase hex of those bytes. A hash that does not match is a failed build, not a warning.

### 12.1 Search object

```json
{
  "candidates": [
    {"chunk_id": "EXAMPLE-MAN-ARM:C:12", "keyword_score": 12, "page": 12}
  ],
  "fault_code": "E-204",
  "held": [
    {"chunk_id": "EXAMPLE-MAN-ARM:C:7", "keyword_score": 1, "page": 7, "reason": "not_a_procedure"},
    {"chunk_id": "EXAMPLE-MAN-ARM:C:40", "keyword_score": 0, "page": 40, "reason": "other_fault"}
  ],
  "incident_id": "EXAMPLE-INC-1",
  "manual_id": "EXAMPLE-MAN-ARM",
  "query_tokens": ["axis", "e-204", "move", "not", "will"],
  "revision": "C",
  "winner_page": 12
}
```

`query_tokens` is sorted. `candidates` is the winner order from section 10.3. `held` is sorted by page. SHA-256 `887d69c6b4d38e6c2be610f1be63e729f7fab89f035482ed516d95ee4d5ca6ae`.

### 12.2 Draft work order

```json
{
  "approved_by": "",
  "asset_id": "EXAMPLE-RBT-14",
  "citations": [
    {
      "manual_id": "EXAMPLE-MAN-ARM",
      "page": 12,
      "quote": "Step 1. Lock out the cell.",
      "revision": "C"
    },
    {
      "manual_id": "EXAMPLE-MAN-ARM",
      "page": 12,
      "quote": "Step 2. Check connector X13 for a loose fit.",
      "revision": "C"
    }
  ],
  "cmms_written": false,
  "fault_code": "E-204",
  "incident_id": "EXAMPLE-INC-1",
  "released": false,
  "status": "pending_technician",
  "symptom": "axis 3 will not move"
}
```

Citation order is the order of step lines on the page. `symptom` is copied from the incident, not rewritten. SHA-256 `95946b33dd367ad7300cf6ded6a498baa5f70e90ddc20228c4c5d600215dddf4`.

`status` is `pending_technician` until a valid approval, then `approved_draft`. `released` true with `approved_by` still empty is not a valid object. The runner does not write it.

### 12.3 Decision

The token is lowercase hex HMAC-SHA256 of the UTF-8 string:

```text
{action}|{incident_id}|{draft_sha256}|{exp}|{actor}
```

using `approval_key`. `exp` is a UTC timestamp ending in `Z`. The token is dead when `run_clock` is after `exp`. Equal to `exp` is alive. A GET does not submit the form.

Actions in version 1: `approve_draft`, `reject_draft`, `go_live`. `go_live` records the lead's id into the decision log. It does not by itself flip `write_cmms`. A person edits that flag afterward.

For the fixture, `approval_key` is `example-approval-key`, action `approve_draft`, incident `EXAMPLE-INC-1`, draft hash `95946b33dd367ad7300cf6ded6a498baa5f70e90ddc20228c4c5d600215dddf4`, `exp` `2026-11-11T18:00:00Z`, actor `EXAMPLE-TECH`. The token is `ba76ecf61ce52653a2c66608df0164bc916a31189a62a22867093735a4fdb130`.

After that approval, with `run_clock` at or before `exp`, the draft becomes:

`approved_by` `EXAMPLE-TECH`, `released` true, `status` `approved_draft`, `cmms_written` false. SHA-256 `2d29fb295f05f37557e1982b4180c591ae1927fa5cb95bec80466b4d9cbb0310`.

A token signed by `EXAMPLE-LEAD` for `approve_draft` is `wrong_actor`. A token signed by `EXAMPLE-TECH` for `go_live` is `wrong_actor`. An expired token is `token_dead` and the draft stays pending.

### 12.4 No-hit object

Fault `E-999` on the same asset, symptom `arm stopped`:

```json
{"code": "no_hit", "draft": false, "incident_id": "EXAMPLE-INC-2"}
```

SHA-256 `6ecf9810d1c62406a3086327dbed2a9d10e90a52b3f9ef69cc7eae4cad6d4715`. No file under `out/drafts/` for this incident.

### 12.5 Morning file

Counts for a fixture run of both incidents, before any approval:

```json
{
  "ambiguous_search": 0,
  "cmms_writes": 0,
  "drafts": 1,
  "no_hit": 1,
  "quotes_not_on_page": 0,
  "releases_without_signature": 0,
  "steps_added_by_model": 0
}
```

SHA-256 `8fa1281df58346d97a849b6c734bb8cdad00ace52cd2fc05a59a9d74760f058d`.

The morning file has no key named `target`, `linamar`, `seventy`, `seconds`, `twelve_weeks`, or `facilities`. A sentence under it that quotes the case study's rates is deleted.

---

## 13. Work order mapped to a generic CMMS sheet

The case says the work-order agent formats records for Linamar's existing tracking system, and that the system integrates with their ERP. It does not name the columns. The map below is our design for a plant that can open a spreadsheet today and point the same columns at a CMMS later.

| Draft field | Generic CMMS idea | Spreadsheet column | Rule |
| --- | --- | --- | --- |
| `incident_id` | External reference | `incident_id` | Copied. The runner does not mint a second id |
| `asset_id` | Equipment | `asset_id` | Must exist on `assets.csv` |
| `fault_code` | Failure code | `fault_code` | Copied, or blank when the incident had none |
| `symptom` | Description | `symptom` | Copied from the incident. Not rewritten |
| citations | Work instructions | `steps` | Step quotes joined with a newline, in order |
| citations | Document reference | `citation` | `manual_id revision page` for each distinct page, joined with ` \| ` |
| `status` | User status | `status` | Always `DRAFT` |
| `released` | not a CMMS status | `released` | `true` or `false`. Never a license to close the job |
| `approved_by` | Confirmed by | `approved_by` | Blank until section 14 |
| `cmms_written` | not exported | omitted | Stays in the JSON. The sheet does not get a column the technician could flip |

`write_cmms_row` appends one CSV row to `out/cmms/work_orders.csv` only when all of these are true: `write_cmms` is `yes`, `go_live_approved_by` is the lead, `released` is true, `approved_by` is the technician or the backup, `draft_status` is `DRAFT`, and the draft hash matches the file on disk. Otherwise it writes nothing and returns `cmms_refused`.

The fixture expects no `out/cmms/work_orders.csv`. A test that flips `write_cmms` to `yes` without a go-live signature expects `cmms_early` at startup, or `cmms_refused` if the flag is forced past startup.

A CMMS adapter a developer writes later calls `write_cmms_row` and then sends that same CSV row. It does not grow a second citation rule. It does not set the remote status to a closed code. Version 1 has no adapter in the core.

---

## 14. Human approval

The technician confirms before anything is released. This is our design. The case's 70 percent accuracy during testing is why the design refuses to treat a model as the person who lets a step onto the line. The case does not print the sentence "a human verifies." The signature is this file's reading of a test score that is not 100 percent, and of a maintenance step that can hurt someone if it is wrong.

1. `build_draft` always sets `released` false and `status` `pending_technician`.
2. The technician reads the draft beside the page file. The form has two actions: approve, reject.
3. Approve requires a live token from section 12.3. The actor is the technician or the backup.
4. Reject records `released` false and `status` `rejected`. No CMMS row.
5. Opening the page file is not an approval. A model sentence that says "approved" is `prompt_ignored`.
6. Approval of one incident does not approve the next one.
7. Go-live is a different form. The lead signs it. The technician cannot.
8. After approval, the step is still a draft in the sheet. `DRAFT` is the status. The technician closing the real job in the CMMS is a later human act this file does not perform.

`technician_confirms` cannot be set to `no`. There is no unattended path in version 1.

---

## 15. Worked fixture

Delete every `EXAMPLE` id before a live manual is read. These pages are not a Linamar manual, not an ABB manual, and not a procedure anyone should run on a robot.

`assets.csv`

```text
asset_id,asset_family,manual_id,revision,site_name
EXAMPLE-RBT-14,EXAMPLE-ARM-200,EXAMPLE-MAN-ARM,C,EXAMPLE-SITE
EXAMPLE-RBT-99,EXAMPLE-OTHER,EXAMPLE-MAN-OTHER,A,EXAMPLE-SITE
```

`incidents.csv`

```text
incident_id,asset_id,fault_code,symptom,opened_at
EXAMPLE-INC-1,EXAMPLE-RBT-14,E-204,axis 3 will not move,2026-11-11T15:00:00Z
EXAMPLE-INC-2,EXAMPLE-RBT-14,E-999,arm stopped,2026-11-11T15:05:00Z
```

`history.csv`

```text
work_order_id,asset_id,fault_code,symptom,steps,status
EXAMPLE-WO-OLD,EXAMPLE-RBT-14,E-204,axis stuck,Spray the arm with solvent.,closed
```

`people.csv`

```text
person_id,role
EXAMPLE-LEAD,lead
EXAMPLE-TECH,technician
```

`golden.csv`

```text
incident_id,manual_id,revision,page,quotes
EXAMPLE-INC-1,EXAMPLE-MAN-ARM,C,12,Step 1. Lock out the cell. | Step 2. Check connector X13 for a loose fit.
```

`pages/EXAMPLE-MAN-ARM/C/7.txt`

```text
PAGE 7
Safety. Lock out the cell before any work.
This page is not a fault procedure.
```

`pages/EXAMPLE-MAN-ARM/C/12.txt`

```text
PAGE 12
Fault E-204. Axis 3 servo.
Step 1. Lock out the cell.
Step 2. Check connector X13 for a loose fit.
Do not move the arm until the connector seats.
```

`pages/EXAMPLE-MAN-ARM/C/40.txt`

```text
PAGE 40
Fault E-118. Gripper pressure low.
Step 1. Stop the cell.
Step 2. Read the gauge on the gripper.
```

`run_clock` for the fixture is `2026-11-11T16:00:00Z`. The approval `exp` is `2026-11-11T18:00:00Z`.

Expected files after `run_regression` on the fixture, with `external_model` `no` and `write_cmms` `no`:

- `out/search/EXAMPLE-INC-1.json` matches section 12.1, hash `887d69c6b4d38e6c2be610f1be63e729f7fab89f035482ed516d95ee4d5ca6ae`.
- `out/drafts/EXAMPLE-INC-1.json` matches section 12.2, hash `95946b33dd367ad7300cf6ded6a498baa5f70e90ddc20228c4c5d600215dddf4`.
- `out/refusals/EXAMPLE-INC-2.json` matches section 12.4, hash `6ecf9810d1c62406a3086327dbed2a9d10e90a52b3f9ef69cc7eae4cad6d4715`.
- `out/daily_summary.json` matches section 12.5, hash `8fa1281df58346d97a849b6c734bb8cdad00ace52cd2fc05a59a9d74760f058d`.
- The string `solvent` does not appear under `out/drafts/` or `out/cmms/`.
- `out/cmms/work_orders.csv` does not exist.
- An incident for `EXAMPLE-RBT-99` is `family_out_of_scope` and writes no draft.

`record_decision` with the fixture token returns the approved hash `2d29fb295f05f37557e1982b4180c591ae1927fa5cb95bec80466b4d9cbb0310` and still does not create the CMMS file.

---

## 16. Evaluation set and go-live threshold

The evaluation set is `golden.csv`. A person builds it from incidents a technician already solved, with the manual page and the step lines written down while looking at the page. The agent does not label its own golden set.

A golden incident passes only when the draft cites that `manual_id`, that `revision`, and that `page`, and the quotes equal the golden quotes in order. A draft that cites the right page and changes a word fails. A draft that adds a step fails. There is no partial credit.

`exact_rate` is the number of passing active golden incidents divided by the number of active golden incidents. Decide the gate with integers. Parse the two digits after the decimal point in `go_live_exact_min` as an integer `gate`. For `0.95`, `gate` is 95. The set passes when `passes * 100 >= gate * active`. For `0.95` and 30 active, that is `passes * 100 >= 2850`, so 29 passes (`2900`) succeeds and 28 (`2800`) fails. Do not use a binary float, and do not use floor division of `gate * active` by 100, which would let 28 through.

Go-live, all of them, before `write_cmms` may be set to `yes`:

- Active golden rows are at least `golden_min`. On a live folder the suggested minimum is 30. The fixture's `2` runs the tests and cannot sign go-live.
- `exact_rate` meets `go_live_exact_min` by the integer comparison above.
- `go_live_exact_min` is not `0.70`.
- The lead has signed `go_live`, and `go_live_approved_by` equals the lead.
- `quotes_not_on_page`, `releases_without_signature`, and `steps_added_by_model` are zero across the golden run.
- A person has read ten drafts beside the page files and written those ten incident ids into `reviewed.csv`. The suggested ten is our design. It is not a Linamar sample size.

Missing any one of these, the flag stays `no`. A golden pass does not approve a live incident. Section 14 still runs on every draft.

The published 70 percent is recorded in the source section so nobody has to hunt for it. It is not copied into `go_live_exact_min`. A plant whose own golden set lands at 70 percent stays in shadow. The threshold starts at `0.95` because a maintenance step is the kind of sentence a person should be right about almost every time before the sheet starts receiving drafts, and because a technician still confirms after that. `0.95` is our suggestion. It is not a result from the case.

---

## 17. Logging and audit

Append one JSON object per line to `out/audit.jsonl`. Do not delete lines. Do not rewrite the file to hide a refusal.

Each line has: `at` (UTC `Z`), `actor`, `incident_id`, `action`, `chunk_ids` (sorted), `manual_id`, `page`, `quote_sha256` (SHA-256 of the quote UTF-8 plus a newline, or `""`), `result`.

Actions include `lookup`, `search`, `draft`, `refuse`, `approve`, `reject`, `cmms_refused`, `cmms_write`, `prompt_ignored`.

A quality audit reconstructs, from this file alone, who opened the incident, which manual revision was cited, which page, the hash of the quote, and which person approved or rejected. The page file remains the document. The log does not replace it.

The audit log is not a place to store the case study's rates. A line whose `result` contains `70` as a target is `audit_target_refused` and is not written. A count of refusals may be the integer 0. That is not the percentage.

---

## 18. Failure handling

| Condition | Code | What is written |
| --- | --- | --- |
| Unknown asset | `asset_unknown` | Refusal. No draft |
| Wrong family | `family_out_of_scope` | Refusal. No draft |
| No page files | `pages_missing` | Refusal. No draft |
| Page header disagrees with the filename | `page_header_mismatch` | That page unreadable |
| Fault code on no procedure page | `no_hit` | Section 12.4 |
| Winning score under `min_keyword` | `low_score` | Refusal. No draft |
| No-code search too close to call | `ambiguous_search` | Refusal. No draft |
| Quote is not a full step line | `quote_not_a_step` | Step dropped. If none remain, no draft |
| History sentence used as a step | `history_not_authority` | Draft refused |
| Model adds a step | `steps_added_by_model` | Extra step dropped, count incremented |
| Approval missing or expired | `token_dead` or `release_unsigned` | `released` stays false |
| CMMS write before the gate | `cmms_early` or `cmms_refused` | No sheet row |
| EXAMPLE id in live | `example_in_live` | Run stops |
| Path escapes the store | `confidential_refused` | Run stops |

A refusal is a successful run of the rules. It is not an invitation to try a broader search.

---

## 19. Rollout

Ninety days. Our design. Not Linamar's twelve weeks, and not a plan for 86 facilities.

Days 1 to 30. One site. One asset family. One manual revision, as page files a person can open. The technician labels golden incidents from jobs already closed, looking at the page while writing the quotes. The runner drafts in shadow. Nothing is released. Nothing is written to the CMMS. Time the search the technician already does, in minutes, into `baseline.csv` with columns `incident_id,minutes`. The agent does not fill that file.

Days 31 to 60. The draft sits beside the search the technician still does by hand. The technician rejects or approves in the form. `write_cmms` stays `no`. Count steps the technician rewrote. A rewrite means the golden quote, or the live correction, differs from the draft. Those counts are the plant's. They are not a reason to lower `go_live_exact_min` to 0.70.

Days 61 to 90. If section 16 passes, the lead may set `write_cmms` to `yes`. The sheet receives rows whose status is `DRAFT`. The technician still confirms each one. The next asset family waits for its own manual, its own golden set, and its own ninety days. A second site waits the same way. Canada-first, in the case, is the echo: one place until the pages are right. The places in this file are the plant's.

---

## 20. Costs and effort

Version 1 is a file runner and a folder of page text. The cost to refuse is the time to read this file and to type the config. The cost to operate is one maintenance lead, one technician, and one builder, for one family, for ninety days.

Caps, so the desk stays that size:

- One site, one asset family, one manual revision. A comma in the site or the family refuses startup.
- `max_pages` suggested 2000. One long manual fits. A dump of every machine in the plant does not.
- `max_incidents_per_run` suggested 20.
- `max_similar` suggested 3, and the steps of those rows are not shown to the model.
- `embeddings` `no` and `external_model` `no` until section 16. The locked path makes no network call and pays no model invoice.
- `max_model_calls` is 1 on the day a reasoner is allowed, and that call may only drop step indexes. `fast_model` stays `off`. The case used a faster model for cheaper tasks. Version 1 does not stand up a second meter before the golden set exists.
- The reasoner model id is blank until the lead types it. Storing `gemini-2.5-pro` or `gemini-2.5-flash` as a pre-filled default is `model_default_refused`. If the plant later chooses those models, the lead types them. They are not inherited.
- Do not buy a rollout to the rest of the company's sites inside this folder. Eighty-six is Linamar's published footprint. It is not a license quantity.
- Do not add a PDF parser, a vector database, an observability vendor, or an ERP connector to the core in order to match a stack named in a source. Those can sit beside the core later, calling the same functions. They do not get a second set of rules.
- The builder's done line is section 18's tests passing on the fixture, including the hashes. A demo that drafts a fluent paragraph and fails a hash is not done.

---

## 21. Stack the tests lock

Python 3.11 or newer. Standard library only. CSV and JSON as specified. No PDF library, no HTTP client, no embedding client, no CMMS SDK on the path `run_regression` runs.

Functions named in section 4 are the API. A notebook that cannot be called as those functions is not an implementation.

The CMMS, when it exists, receives the CSV row from `write_cmms_row` and nothing else. The ERP the case mentions is the plant's own system. This file does not guess its name.

---

## 22. What you do not claim

- Do not say this plant will cut a 10 to 30 minute manual search to seconds. That sentence is Linamar's published result, as Vector tells it. The page does not print the sample size. It is not a quotation you may put on this plant.
- Do not say this plant will reach 70 percent accuracy, and do not say 70 percent is the go-live bar. Seventy percent is their result during testing. This file refuses it as `go_live_exact_min`.
- Do not say this plant will have a working prototype in twelve weeks, or that twelve weeks includes 86 facilities. The twelve weeks are concept to working prototype. The at-a-glance word "deployed" is the summary's wording. The 86 facilities and 19 countries are the company's footprint. The case says the build starts with domestic implementation in Canada.
- Do not say the manuals are 400 to 1,500 pages at this plant. That is the range in the case. `max_pages` is our cap. The plant's page count is the number of files in its folder.
- Do not say Gemini 2.5 Pro and Gemini 2.5 Flash are required. The team selected them. This plant types its own model id, or types none and stays on the locked path.
- Do not say the desk uses OpenAI's Agent SDK, Langfuse, or a named vector database because a LinkedIn post listed them. The post is the source for ABB robots. It is not the architecture this file builds.
- Do not say the columns, the score 12, the bonus of 8, the hashes, `min_keyword` 3, or `0.95` are Linamar, Vector, or Google settings. They are not published. They are our design. `EXAMPLE-RBT-14` is a fixture. It is not a Linamar robot. `E-204` is a fixture fault. It is not a code from an ABB manual.
- Do not say version 1 is already inside their ERP, or that a draft has been released to the line, or that the agent restarted a cell. `released` starts false. `cmms_written` starts false. The sheet status is `DRAFT`.
- Do not say a golden pass removes the technician. Section 14 runs on every incident after go-live.
- Do not paste "multi-million-dollar" into a proposal as this plant's downtime cost. The case uses that phrase for the cost class of unplanned downtime. It is not a measured Linamar loss in the source.
- Do not relabel the plant with a result it did not measure.

When a sentence would make this plant sound like the case study's scoreboard, delete the sentence and show the plant its own `baseline.csv` instead.

---

## 23. Paste this to build it

Paste the block below to the agent that will build the tool. The builder reads this whole file. The model sees a finished draft only after the functions have already chosen the page. It does not see a manual page as instructions to follow against the plant.

```text
You are building the machine-troubleshooting tool specified in machine-troubleshooting-agent-instructions.md. Build only what that file specifies.

Stack: Python 3.11 or newer. Standard library only. CSV with the headers in section 8. One chunk per printed page. Tokens follow section 10.1. Keyword score is the intersection size plus 8 when the fault code token is in the chunk. Candidates with a fault code are procedure pages whose Fault line matches that code. A safety page cannot win. A past work order cannot supply a step. Quotes are full step lines. Put the rules in pure functions load_config, load_world, tokenize, keyword_score, rank_pages, cite_steps, build_draft, draft_canonical, similar_orders, record_decision, approval_token, write_cmms_row, run_regression, and daily_summary. Call them from a thin folder runner and from the tests. Do not reimplement the rules in the model prompt.

Fail closed. If any required config value is missing, blank, or the word REPLACE, do not serve a live run. If any id in live_dir starts with EXAMPLE, do not serve a live run. If technician_confirms is not yes, refuse to start. If fast_model is not off, refuse to start. If draft_status is not DRAFT, refuse to start. If write_cmms is yes before the section 16 gate, refuse that flag. If shadow is yes while write_cmms is yes, refuse to start. If go_live_exact_min is 0.70, 70, or 70%, refuse to start. If a model tool is named release_work_order, write_cmms, approve_draft, set_page, or invent_step, refuse to start.

The model tool list is lookup_asset, search_manuals, read_page, and list_similar_work_orders. read_page returns a body only for the winning page. list_similar_work_orders does not return steps. build_draft, record_decision, and write_cmms_row are runner functions. A model call to approve or release is prompt_ignored. Never set released true without a live technician token. Never write a CMMS row while the gate is shut. Never copy the history sentence. Never cite page 7 as a procedure. Never let page 40 answer fault E-204.

The fixture in section 15 must produce search hash 887d69c6b4d38e6c2be610f1be63e729f7fab89f035482ed516d95ee4d5ca6ae, draft hash 95946b33dd367ad7300cf6ded6a498baa5f70e90ddc20228c4c5d600215dddf4, no-hit hash 6ecf9810d1c62406a3086327dbed2a9d10e90a52b3f9ef69cc7eae4cad6d4715, morning hash 8fa1281df58346d97a849b6c734bb8cdad00ace52cd2fc05a59a9d74760f058d, and approval hash 2d29fb295f05f37557e1982b4180c591ae1927fa5cb95bec80466b4d9cbb0310. The string solvent must not appear in a draft. The CMMS file must not exist on that run. Section 18 must pass before a maintenance lead is asked to turn write_cmms on, and before a file is treated as a step the line has already accepted.
```
