@litfamily/lithermes 1.0.28 → 1.0.30

package/assets/lithermes-plugin/skills/lit-schematic/references/pid-drafting.md

@@ -0,0 +1,103 @@
+# Drafting a P&ID sheet
+
+A P&ID is an operating document: an operator, a reviewer in a HAZOP and a commissioning engineer each read it for a different question, and each must find the answer without asking the author. Everything here serves that reading.
+
+## Contents
+1. Before drawing
+2. The sheet
+3. Placing equipment
+4. Lines: routing, crossings, branches
+5. Line numbers and flow arrows
+6. Valves and isolation
+7. Instruments and control loops
+8. Relief and venting
+9. Legend, header, notes and title block
+10. Faults that reviewers catch
+
+## 1. Before drawing
+
+Write four lists in the build script before any coordinate:
+
+- **Equipment**: tag, name, design pressure and temperature, size or duty. These go to the header band (`sheet.equipmentInfo(sym, ["10 MPa / -20…80 °C", "1.0 L, SS316"])`).
+- **Lines**: from, to, nominal size, fluid code, sequence, piping class → the line number `1/4"-CH4-101-HP1`. State the format once in the notes.
+- **Instruments**: tag, what it measures, where it reads (field, panel, DCS), what it acts on.
+- **Safety devices**: each PSV and rupture disk, its set pressure, the equipment it protects, and where it discharges.
+
+Invent nothing silently. When the brief gives no set point, choose a plausible one, keep it in the build as a named constant, and list it in the reply as an assumption.
+
+## 2. The sheet
+
+`createSheet({ size: "A3", … })` draws an ISO A3 landscape sheet (420 × 297 mm): a frame 20 mm from the left edge (binding) and 10 mm elsewhere, zone numbers along the top and bottom and zone letters along the sides so a reviewer can say "the PSV at C6", the equipment header band across the top, the legend column on the right, the notes block bottom left and the title block bottom right. A1 and A2 work the same way for dense units; A4 suits a small skid.
+
+Text at 1:1 on A3: tags 2.5 mm, equipment tags 3.0 mm bold, line numbers and notes 2.2 mm, title 4 mm. Nothing under 2.0 mm, because sheets are photocopied and reduced; the QA floor for P&ID sheets is 5.6 pt.
+
+Line weights carry the hierarchy on the ISO 128 series, and every pipe class has its own: main process 0.7 mm, minor process 0.5 mm, utility 0.35 mm, instrument supply or process connection 0.18 mm; equipment outlines 0.5 mm, symbols 0.35 mm, signals 0.25 mm with the mark of their medium, tangent lines and details 0.18 mm. Pick the class by what the line carries, not by how it looks: a 2-inch cooling-water header is a utility line however big it is.
+
+## 3. Placing equipment
+
+- **Flow runs left to right.** Feed and utilities enter on the left, products and vents leave on the right or top. The main process route reads as one horizontal story.
+- **Gravity is real.** Pumps sit below and near their suction vessel; drains go down; vents and relief discharge go up. A tank's outlet nozzle is at its bottom.
+- **Equal elevations for related items.** Put duty and standby pumps one above the other with the same spacing; line up instruments of one loop.
+- **Room for lines.** Keep 15–25 mm between symbols that exchange several lines, and leave free horizontal lanes for headers and a lane below the equipment for signal runs to the DCS.
+- **Instruments sit next to what they measure,** offset 10–15 mm from the line or nozzle, with a short connection. Controllers and DCS bubbles go between the measurement and the final element, toward the top or the bottom lane, so signal lines do not cross the process.
+- **Symbols never overlap.** The canvas warns, and the router cannot pass between symbols closer than twice the clearance (2.2 mm each side on a sheet).
+
+## 4. Lines: routing, crossings, branches
+
+The router follows the drafting rules a checker applies to a hand-drawn sheet:
+
+1. **Leave a port on its normal.** A line leaves a nozzle straight out (up from a top nozzle, sideways from a side nozzle) before it turns, so the reader sees where it starts.
+2. **Never through a symbol.** A route enters a symbol only at its own port. When there is no way around, the build throws: move a symbol or give `via` waypoints. Never draw the line by hand through it; `LINE.THROUGH_SYMBOL` fails.
+3. **Few bends.** Each bend costs as much as about 9 mm of straight line, so routes prefer one or two clean corners to a staircase.
+4. **Cross at right angles, on straights.** A later process line hops over an earlier one (a small semicircle); signal lines cross process lines without a hop. A line never turns on top of another line (`LINE.BEND_ON_LINE`): a corner on another line reads as a junction.
+5. **Never run along another line** (`LINE.OVERLAP`): two lines on one track cannot be told apart.
+6. **Branches leave a straight run.** `line.tap()` refuses a point within 3 mm of a bend and draws a junction dot. A branch leaves perpendicular to the main line.
+7. **Every line ends on something:** a port, another line (a junction), or a terminal (vent, drain, off-page, utility). `LINE.DANGLING` fails anything else.
+
+Draw the main process lines first, then minor lines, then utilities, then instrument connections and signals last, so the thin lines route around the heavy ones (the same order an illustrator uses for ducts before cables).
+
+## 5. Line numbers and flow arrows
+
+A line number labels each line between two pieces of equipment, placed parallel to its longest clear straight, beside it, never on it. The format sits in the notes: size – fluid code – sequence – piping class (`2"-PG-101-A1A`). Fluid codes are short and listed in the legend notes when they are not obvious (`CH4`, `CO2`, `CWS`/`CWR`, `N2`, `IA`, `PW`).
+
+Flow arrows: one on each line's longest clear straight by default, kept clear of junctions and symbols; add arrows (`arrows: [0.2, 0.8]`) where the direction is not obvious, such as at a recycle or after a three-way valve. Never arrow a signal line.
+
+## 6. Valves and isolation
+
+- **Every instrument, pump, control valve and relief device can be isolated.** Put a block valve on each side of a control valve, with a bypass globe or needle valve when the process must run while the control valve is out.
+- **Check valves** sit on pump discharges and on any line that must never flow back (gas supply into a reactor).
+- **Drains and vents** at low and high points of a liquid loop, each with a valve.
+- **Double block and bleed** on high-pressure gas: two block valves with a bleed valve between, where the gas supply meets the reactor.
+- **Valve on a straight run**: `inline` snaps a valve to the nearest straight run that can hold it, and throws when none can.
+
+## 7. Instruments and control loops
+
+A loop on the sheet: element or transmitter at the process (`PT-101` connected by a thin solid line to a nozzle or a tap), signal to the controller (`PIC-101` in the DCS, dashed for electric), signal to the final element (`PV-101` diaphragm valve, or a pump's `signal` port, or a chiller's setpoint input). Draw the whole loop on the sheet, or end it at an off-page connector naming the sheet that continues it.
+
+Alarms and trips: put `PAH`, `PAHH`, `TAH` on the controller bubble's loop number; a trip (`PSHH-101` → interlock `I-1` → `XV-101` closes) is drawn as its own loop through an interlock diamond. Safety instrumented functions are labelled as such in the notes.
+
+## 8. Relief and venting
+
+Every vessel that can be over-pressured (by a gas supply, a booster, heat input, fire, or a blocked outlet) has a relief device set at or below its design pressure. Draw the PSV on the vessel or its inlet line with its set pressure beside it (`setPressure: "SET 12 MPa"`), and draw where it discharges: a vent header, a flare off-page connector or a safe vent with `ATM`. A rupture disk upstream of a PSV protects the valve from a corrosive or hydrate-forming gas; draw a pressure gauge between them to show the disk is intact. A relief path that ends in the air is the first defect a HAZOP finds.
+
+## 9. Legend, header, notes and title block
+
+- **Legend**: built from what the sheet draws: every line kind, every symbol kind (composed kinds such as a globe valve with a diaphragm actuator, or a DCS function in the control room, get their own row and sample), and the instrument identification letters used with their meaning. Its column is fixed; when it would overflow, the identification letters move into the right half of the notes block, and if it still overflows the sheet warns: move to a larger sheet.
+- **Legend sheet**: a drawing set opens with a "P&ID symbols and abbreviations" sheet. `createLegendSheet({ number, rev, date })` builds it from the library (every symbol, line class, the ISA shape-and-location matrix, the letters, fail positions, the line-number form, the equipment prefixes); give it the set's first drawing number.
+- **Equipment header**: tag, name and two or three spec lines above each major item.
+- **Notes**: numbered; the line number format, the meaning of duty/standby, set-point references, hold points. Keep them to facts the drawing cannot show.
+- **Title block** (ISO 7200 fields): title, drawing number, revision, sheet, project, owner, drawn/checked/approved, date, scale (`NTS` for P&IDs). `TITLEBLOCK.FIELDS` fails an empty title, number, revision, date or scale.
+
+## 10. Faults that reviewers catch
+
+| You see | Fix |
+| --- | --- |
+| A line passes behind a vessel or through a valve body | Re-route with `via`, or move the symbol; the router refuses the pass-through. |
+| A branch leaves at a corner | Tap a straight run at least 3 mm from the bend. |
+| A controller with no final element | Draw the output signal to the valve, pump or heater it moves, or remove the `C`. |
+| An instrument floating next to a vessel | Connect it to a nozzle (`vessel.port("right", 0.4)`) or a tap. |
+| PSV discharge stops in the air | Run it to a vent, header or off-page connector. |
+| Two lines labelled with the same number | Number every line between two items once. |
+| Tags like `TCI` or `PCIC` | Readout letters come before output letters, no repeats: `TIC`, `PIC`. |
+| A dense corner where labels overlap | Spread the equipment; never shrink text under 2.0 mm. |
+| The legend shows symbols not on the sheet | The kit builds the legend from the drawing; a hand-written legend drifts. |

package/assets/lithermes-plugin/skills/lit-schematic/references/pid-symbols.md

@@ -0,0 +1,163 @@
+# P&ID symbols and identification
+
+The kit draws a vocabulary close to ISO 10628-2 (graphical symbols for process diagrams) for equipment and fittings, and ANSI/ISA-5.1 for instruments, their identification letters and signal lines. Conventions vary between owners and countries, so **the legend on the sheet governs**: the sheet's legend is built from the symbols and line kinds actually drawn, and the QA gate fails a sheet whose legend misses one. When a project has its own symbol standard, follow it and keep the legend true.
+
+## Contents
+1. Identification letters (ISA-5.1)
+2. Instrument bubbles: what the function is and where it lives
+3. Pipe classes and signal lines
+4. Equipment symbols and tags
+5. Valves, actuators and fail positions
+6. Piping items, flow elements and terminals
+7. Common tags for a high-pressure gas-hydrate loop
+8. Standards basis, symbol by symbol
+
+## 1. Identification letters (ISA-5.1)
+
+A tag is **letters + loop number**: `PIC-101` is loop 101, pressure (P), indicating (I), controller (C). The first letter is the measured or initiating variable; an optional modifier follows it; then the functions, readout or passive ones before output ones; `H`, `L`, `M` modify the alarm or switch letter before them.
+
+| Letter | First (measured variable) | Modifier after the first letter | Succeeding: readout / passive | Succeeding: output | Function modifier |
+| --- | --- | --- | --- | --- | --- |
+| A | Analysis (composition, pH, O₂) | | Alarm | | |
+| B | Burner, combustion | | User's choice | | |
+| C | User's choice (often conductivity) | | | Control | |
+| D | User's choice (often density) | Differential | | | |
+| E | Voltage | | Primary element (sensor) | | |
+| F | Flow | Ratio | | | |
+| G | User's choice (gauging) | | Glass, gauge, viewing | | |
+| H | Hand | | | | High |
+| I | Current | | Indicate | | |
+| J | Power | Scan | | | |
+| K | Time, schedule | Time rate of change | | Control station | |
+| L | Level | | Light | | Low |
+| M | User's choice (moisture) | Momentary | | | Middle |
+| O | User's choice | | Orifice, restriction | | |
+| P | Pressure, vacuum | | Point (test connection) | | |
+| Q | Quantity | Integrate, totalise | | | |
+| R | Radiation | | Record | | |
+| S | Speed, frequency | Safety | | Switch | |
+| T | Temperature | | | Transmit | |
+| U | Multivariable | | | Multifunction | |
+| V | Vibration | | | Valve, damper | |
+| W | Weight, force | | Well, probe | | |
+| X | Unclassified | x-axis | Unclassified | | |
+| Y | Event, state | y-axis | | Relay, compute, convert | |
+| Z | Position, dimension | z-axis | | Driver, actuator | |
+
+Readable examples: `PT` pressure transmitter · `PI` local pressure gauge reading · `PIC` pressure indicating controller · `PCV` self-actuated pressure regulator · `PV` pressure control valve (final element of a PIC loop) · `PSV` pressure safety valve · `PSE` rupture disk · `PAH`/`PAHH` high and high-high pressure alarm · `PSHH` high-high pressure switch (trip) · `PDT` differential pressure transmitter · `TE` temperature element (thermocouple, RTD) · `TW` thermowell · `TT`, `TIC`, `TV` · `FT`, `FE` (orifice), `FIC`, `FV`, `FQI` totaliser · `LT`, `LG` level gauge, `LIC`, `LSL` · `AT` analyser transmitter (GC, MS, O₂) · `SC` speed controller · `HS` hand switch · `XV` on-off valve · `ZSO`/`ZSC` position switch open/closed.
+
+`parseInstrumentTag` enforces: the first letter exists; a variable modifier only directly after it; function letters from the table, readout `I`/`R` before outputs, no repeats; `H`/`L`/`M` only after `A`, `S` or another `H`/`L`/`M`. `TAG.GRAMMAR` fails a symbol tag that breaks these, `TAG.DUPLICATE` fails two items with one tag.
+
+**Loop numbering.** One loop number per measured point and everything that acts on it: `PT-101 → PIC-101 → PV-101`, and its alarms `PAH-101`. Number loops by unit (100s for the reactor section, 200s for the chiller) so a reader finds them.
+
+## 2. Instrument bubbles: what the function is and where it lives
+
+ISA-5.1 Table 5.1.1 separates two things a bubble says. Its **shape** names the kind of device or function; the **lines across it** name where it lives.
+
+| Shape | Function | Kit `fn` |
+| --- | --- | --- |
+| Circle | Discrete instrument: a transmitter, gauge, switch or single-loop controller | `"discrete"` (default) |
+| Circle in a square | Shared display and control: a function of the DCS or operator screen | `"shared"` |
+| Hexagon | Computer function: an optimiser, a calculation outside the DCS | `"computer"` |
+| Diamond in a square | PLC logic, or a safety instrumented system function | `"plc"` |
+
+| Lines across the shape | Location | Kit `location` |
+| --- | --- | --- |
+| none | In the field, at the equipment | `"field"` (default) |
+| one solid | Main control room, operator accessible (on the console or panel front) | `"main"` |
+| one dashed | Main control room, not normally accessible (behind the panel, in a cabinet) | `"main-rear"` |
+| two solid | Auxiliary or local panel near the unit, operator accessible | `"aux"` |
+| two dashed | Auxiliary or local panel, not normally accessible | `"aux-rear"` |
+
+So a DCS controller on the operator console is `instrument({ tag: "PIC-101", fn: "shared", location: "main" })`: a circle in a square with one solid line. A local pressure gauge is a plain circle. The kind is `instrument.<fn>-<location>` and the legend names both halves. The round-1 names still work: `location: "dcs"` means shared/main, `"plc"` plc/main, `"panel"` discrete/main, `"panel-rear"` discrete/main-rear, `"local-panel"` discrete/aux.
+
+The letters sit in the upper half and the loop number in the lower half, clear of the location lines. Keep bubbles 10 mm across on an A3 sheet (`r = 5`); a 4-letter tag drops to 2.1 mm text automatically. An interlock or logic block is a diamond with its number (`interlock()`).
+
+## 3. Pipe classes and signal lines
+
+Pipe classes differ by **weight**, on the ISO 128 series, so they never look alike on the sheet or in the legend: main process 0.7 mm, minor process 0.5 mm, utility 0.35 mm, instrument supply or process connection 0.18 mm. Instrument signals are 0.25 mm and carry the mark of ISA-5.1 Table 5.3.2 for their medium.
+
+| Line | Drawing | Kit |
+| --- | --- | --- |
+| Main process line | heavy solid, 0.7 mm | `pipe({ kind: "process-major" })` |
+| Minor process line, small bore | solid, 0.5 mm | `"process-minor"` |
+| Utility (cooling water, nitrogen, instrument air, steam) | solid, 0.35 mm | `"utility"` |
+| Instrument supply or process connection, impulse line (Table 5.3.1) | thin solid, 0.18 mm | `connect()` |
+| Electric or electronic signal (4–20 mA, discrete) | dashed | `signal({ type: "electric" })` |
+| Pneumatic signal | double slashes every 6 mm | `"pneumatic"` |
+| Hydraulic signal | L marks | `"hydraulic"` |
+| Filled-system capillary tube | crosses | `"capillary"` |
+| Guided electromagnetic or sonic signal (fibre, guided wave) | sine wave | `"guided"` |
+| Unguided electromagnetic signal (radio, wireless transmitter) | broken sine wave | `"unguided"` |
+| Data link within a control system (DCS bus, fieldbus segment) | small open circles | `"data"` (`"software"` still works) |
+| Mechanical link (a lever, a shaft between two functions) | small filled dots | `"mechanical"` |
+
+A signal runs from the transmitter to the controller to the final element. Every loop on the sheet ends at something that acts (a control valve, a pump's speed or stroke input, a heater, a trip), or it is an indication-only loop and has no controller letter. An actuated valve has an `actuator` port at the top of its actuator: run the controller's signal to `valve.port("actuator")`, never to the valve body.
+
+## 4. Equipment symbols and tags
+
+Equipment tags are a class prefix and a number, with an optional train letter: `R-101` reactor, `V-101` vessel, `TK-101` tank, `D-101` drum, `C-101` column, `E-101` exchanger, `P-101A/B` duty and standby pumps, `K-101` compressor, `BR-101` gas booster, `CH-101` chiller, `F-101` filter, `GC-101` gas cylinder, `M-101` mixer or agitator. The kit draws:
+
+- **Vessels** (`vessel`): shell with 2:1 ellipsoidal heads (or flat or conical), tangent lines, optional jacket (`jacket-in` at the bottom, `jacket-out` at the top, so coolant flows upward), agitator with motor (turbine, anchor or propeller), internal coil, packing (a box with its diagonals, ISO 10628-2 item 2.4), trays, demister, legs or skirt, liquid level mark. Trays run across the whole shell as on a tray column (item 2.2); `trayStyle: "staggered"` draws segmental baffles that stop short of the far wall (item 2.5).
+- **Machines** (`pump`, `compressor`): a centrifugal pump is a circle with a tangential discharge on a base; a rotary positive-displacement pump shows two rotors; a metering pump adds the diagonal adjustment arrow. A centrifugal compressor is a circle with converging sides; a reciprocating compressor or gas booster is a circle with a cylinder and rod.
+- **Heat transfer**: a general exchanger or condenser (circle crossed by a zigzag, item 3.1); shell-and-tube with fixed tube sheets (`shellTube()`, item 3.3: shell, a tube sheet at each end, straight tubes), floating head (`type: "floating"`, item 3.4) or U-tubes (`type: "utube"`, item 3.5); plate exchanger (`plateExchanger()`, item 3.6: the pack with both diagonals and a centre line); air-cooled exchanger (`airCooler()`: bundle with its tube run, fan and motor below).
+- **Packaged units**: anything with its own skid (chiller, circulator, analyser, DAQ, booster package) is a box with its caption and declared ports (`unit({ glyph: "coil" | "wave" })`).
+
+## 5. Valves, actuators and fail positions
+
+Valves are inline symbols on a straight run; the line is gapped under them. Bodies (ISA-5.1 Table 5.4.1, ISO 10628-2 groups 21 and 22): gate (plain bowtie), globe (bowtie with a filled dot), ball (bowtie with an open circle), plug (bowtie with a small square), butterfly (two end bars, the disc on the diagonal, a hub dot), needle (bowtie with a solid point above, for fine metering), diaphragm (bowtie under a bonnet arc), check (bowtie with the solid half pointing along the allowed flow), three-way (a third body on the branch, port `c`). An angle valve (`angleValve({ inlet, outlet })`) sits where the line turns: one body toward each port.
+
+Actuators (Table 5.4.2) stand perpendicular to the line and name themselves in the kind, `valve.<body>.<actuator>`: `diaphragm` (spring-opposed pneumatic, the usual control valve), `piston` (cylinder), `motor` (electric, `M`), `solenoid` (on-off, `S`), `hand` (handwheel; `manual` is the same). Fail positions (Table 5.4.4) go beside the actuator as letters: `FO` fail open, `FC` fail closed, `FL` fail locked in its last position, `FI` fail indeterminate; anything else throws. Self-acting devices (Table 5.4.3): a pressure-reducing regulator (`regulator`) senses downstream through its impulse line, a back-pressure regulator (`backPressure: true`) senses upstream; a pressure safety or relief valve (`safetyValve`) has its inlet from below, outlet to the side and spring on top; a rupture disk (`ruptureDisk`) is two bars with the domed disk between them.
+
+## 6. Piping items, flow elements and terminals
+
+Piping items: concentric reducer (`reducer`) or eccentric reducer (`reducer({ eccentric: true, flat: "bottom" | "top" })`, flat side down on pump suctions), flange pair (`flange`), spectacle blind (`blind`, figure-8: the half in the line is solid when the line is blinded, `state: "open"` turns it to a ring), inline filter or strainer (`filter`), sight glass. Flow elements (ISA-5.1 Table 5.2.3) through `flowElement({ type })`: `orifice` (plate between flanges), `venturi` (converging-diverging throat), and notation boxes for meters without a drawn form of their own, labelled with the Table 5.2.2 notation: `magnetic` MAG, `coriolis` COR, `vortex` VOR, `turbine` TUR, `ultrasonic` US, `thermal` TMF. A variable-area meter (`rotameter`) and a mass flow controller (`mfc`, with a `signal` port) complete the set.
+
+Terminals end a line on purpose: vent to atmosphere (`vent`, labelled `ATM` or the vent header), drain, sample point, off-page connector with the destination and drawing number, utility connection (`N2`, `IA`, `CWS`, `CWR`). A line that ends anywhere else is dangling (`LINE.DANGLING`).
+
+**Line numbers** read `size-fluid-sequence-class[-insulation]`: `2"-P-1001-A1A`, `1/4"-CH4-101-HP1`, `DN50-CW-205-B1-IH`. On a P&ID the QA gate fails a line number that breaks this form (`LINE.NUMBER`); `parseLineNumber` reads one apart.
+
+## 7. Common tags for a high-pressure gas-hydrate loop
+
+A hydrate formation rig is a compact high-pressure gas loop; its P&ID usually carries these items, which the kit covers as listed:
+
+| Item | Tag | Kit |
+| --- | --- | --- |
+| Gas cylinders (CH₄, CO₂, mixtures) with cylinder regulator | `GC-101`, `PCV-101` | `gasCylinder`, `regulator` |
+| Gas booster raising cylinder gas to test pressure | `BR-101` | `compressor({ type: "reciprocating" })` or `unit` |
+| Buffer or supply vessel | `V-101` | `vessel` |
+| Jacketed stirred high-pressure reactor (sapphire windows optional) | `R-101` | `reactor` |
+| Chiller or circulator on the jacket | `CH-101` | `unit({ glyph: "coil" })` |
+| Reactor pressure and temperature | `PT-101`, `PI-101`, `TE-101`/`TT-101`, `TW-101` | `instrument` |
+| Pressure control (supply regulator or BPR on vent) | `PIC-101`, `PV-101` | `valve({ actuator: "diaphragm" })` |
+| Temperature control on the chiller | `TIC-201` → chiller setpoint | `signal` to the chiller unit |
+| Relief: PSV set below the reactor's design pressure, rupture disk in series or parallel | `PSV-101`, `PSE-101` | `safetyValve`, `ruptureDisk` |
+| Gas flow into the reactor | `FT-101`, `FQI-101` (consumed gas) | `instrument`, `mfc` |
+| Sampling to GC | `SP-101`, `AT-101` | `samplePoint`, `instrument` |
+| Vent to a safe location | `ATM` or `TO VENT HEADER` | `vent`, `offPage` |
+
+
+## 8. Standards basis, symbol by symbol
+
+Where each drawn form comes from, so a reviewer can check it against the project's own licensed copies. ISO 10628-2:2012 numbers its symbols by subject group (Table 1) and item (Table 2: group.item with an ISO 14617 registration number); ANSI/ISA-5.1-2009 groups instrument symbols in tables 4.1 and 5.1.1 to 5.4.4. Where the kit follows common US practice (PIP PIC001) rather than a numbered entry, the row says so.
+
+| Kit kind | Basis |
+| --- | --- |
+| `vessel.*`, `vessel.horizontal`, `vessel.tank`, `gas.cylinder` | ISO 10628-2 group 1 (vessels and tanks): items 1.5 dished ends, 1.3 cone roof tank, 1.13 drum, 1.14 gas cylinder, 1.27 jacketed vessel |
+| `vessel.column` | ISO 10628-2 group 2: 2.2 tray column (full-width trays, default), 2.4 fixed bed (packing), 2.5 staggered baffles |
+| `exchanger.general`, `.shelltube`, `.floating`, `.utube`, `.plate` | ISO 10628-2 group 3: 3.1, 3.3, 3.4, 3.5, 3.6 |
+| `exchanger.aircooler` | ISO 10628-2 group 3 (air cooler); drawn as bundle, fan and motor after common practice |
+| `pump.*` | ISO 10628-2 group 15 (liquid pumps); centrifugal form with tangential discharge after PIP practice |
+| `compressor.*` | ISO 10628-2 group 16 (compressors) |
+| `valve.<body>` | ISA-5.1 Table 5.4.1; ISO 10628-2 group 21 (valves), group 22 (check valves) |
+| `valve.<body>.<actuator>`, fail letters | ISA-5.1 Table 5.4.2 (actuators), Table 5.4.4 (failure and de-energised positions) |
+| `valve.regulator`, `.backpressure`, `.safety`, `relief.rupture` | ISA-5.1 Table 5.4.3 (self-actuated final control elements); ISO 10628-2 group 23 (safety function) |
+| `line.reducer*`, `line.flange`, `line.blind*`, `line.filter`, `line.sightglass` | ISO 10628-2 groups 24 (fittings) and 25 (piping); spectacle blind form after PIP practice |
+| `flow.orifice`, `flow.venturi`, `flow.<meter>` | ISA-5.1 Table 5.2.3 (primary elements) and Table 5.2.2 (measurement notations MAG, COR, VOR, TUR, US, TMF) |
+| `instrument.<fn>-<location>` | ISA-5.1 Table 5.1.1 (device and function symbols by location) |
+| `logic.interlock` | ISA-5.1 binary logic (Table 5.7) as a diamond with its number |
+| Pipe classes and widths | ISO 128 line-width series; ISO 10628-1 (main lines heavier than others) |
+| Signal lines | ISA-5.1 Table 5.3.1 (instrument to process) and Table 5.3.2 (instrument to instrument) |
+| Identification letters, tags | ISA-5.1 Table 4.1 |
+
+The standalone legend sheet (`createLegendSheet`, `scripts/lib/legend-sheet.mjs`) prints every row of this vocabulary from the library itself, so the sheet a drawing set opens with never drifts from what the kit draws.

package/assets/lithermes-plugin/skills/lit-schematic/references/verification.md

@@ -0,0 +1,100 @@
+# Verification
+
+Look at the drawing the way its harshest reader will, before anyone else does. Rendering is cheap; a reviewer finding a line through a vessel costs a revision.
+
+## Contents
+1. The loop
+2. The QA gate: every code and its fix
+3. Render and look
+4. The close-up sweep
+5. Review checklist
+6. Exports
+
+## 1. The loop
+
+1. Build → `node "$SKILL_ROOT/scripts/qa.mjs" drawing.svg`.
+2. Fix every FAIL **in the build script**, rebuild, re-run QA until `QA PASS`.
+3. Render (`render.mjs --png --dpi 600`) and open the PNG. Read it in the order of section 3. QA reads the SVG, never the PNG, so the renderer checks the PNG itself: it compares the ink in 36 regions against a small reference render of the same page, and a region that holds ink there but came out blank means the browser stopped painting (it happens above roughly 60 to 80 million pixels, an A2 sheet at 600 dpi). The renderer then steps the dpi down until the page arrives whole and prints `reduced from 600`; if it cannot, it stops with `RENDER_INCOMPLETE`. A reduced dpi on a large sheet is fine for reading; the PDF stays vector, and `--crop` gives any region at full resolution.
+4. For anything denser than a dozen symbols or parts, render the close-up sweep (`--sheet sweep.png --grid 3x2`, or `4x3` for an A1 sheet) and read every cell.
+5. Fix what the eye found, rebuild, re-run QA, re-render. Stop when QA passes and the last render shows nothing to fix.
+
+QA is necessary, never sufficient: it reads geometry and markers, not appearance. It cannot see a leader dot on a face hidden behind another part, a nozzle standing on a cut-away shell, a misleading symbol choice, or a crowded corner that is technically clear. The look is the gate that catches those.
+
+## 2. The QA gate: every code and its fix
+
+`qa.mjs` parses the SVG itself (no browser), applies every transform and reads the markers the kit writes (`data-sym`, `data-box`, `data-ports`, `data-line`, `data-part`, `data-hull`, `data-leader`, `data-panel`, `data-legend-item`, `data-within`). Unmarked geometry still counts for strokes and text, so a hand-edited SVG cannot slip past by dropping markers. `--json` gives the same result as JSON; `--codes` lists the codes.
+
+| Code | Meaning | Fix in the build |
+| --- | --- | --- |
+| `XML.WELLFORMED` | The SVG does not parse. | Rebuild; never hand-edit the output. |
+| `XML.EXTERNAL` | It loads an outside file or URL. | Inline it or drop it. |
+| `SVG.ACTIVE` | Script or event handlers. | Remove them; a schematic is static. |
+| `SVG.SIZE` | No physical width/height or viewBox. | Use `createSheet` / `createFigure`, which write mm sizes. |
+| `TEXT.MIN_SIZE` | Text under the floor at print size (5.6 pt on sheets, 6 pt on figures). | Spread the layout or shorten the text; never shrink it. |
+| `TEXT.OVERLAP` | Two labels overlap. | Move a symbol; the placer then finds room. |
+| `TEXT.ON_SYMBOL` | A label sits on a symbol it does not belong to. | Move the label's owner or the symbol. |
+| `TEXT.ON_ART` | A label sits on the isometric art. | Use `callout`, which places labels beside the art. |
+| `TEXT.ON_LINE` | A line runs through a label. | Re-route (`via`) or move the label's owner. |
+| `TEXT.CLIPPED` | A label runs past the drawing edge. | Widen the panel or shorten the label. |
+| `TEXT.OUT_OF_CELL` | Text overflows its title-block cell, legend or notes block. | Shorten it, or move to a larger sheet. |
+| `LINE.THROUGH_SYMBOL` | A line passes through a symbol. | Let the router route it, add `via`, or move the symbol. |
+| `LINE.DANGLING` | A line end touches no port, line or terminal. | End it on a port, a `tap`, or a vent/drain/off-page terminal. |
+| `LINE.BEND_ON_LINE` | A line turns on another line. | Move the waypoint; corners on lines read as junctions. |
+| `LINE.OVERLAP` | Two lines share a track. | Give one a different lane. |
+| `LINE.CROSSING` (warn) | Process lines cross without a hop. | Hand-drawn lines: route through the canvas so later lines hop. |
+| `LINE.ARROW_IN_SYMBOL` | A flow arrow is drawn inside a valve, instrument or other body, where it reads as part of the symbol. | Let the canvas place arrows, or give `arrows` fractions that fall on open pipe; the canvas already slides an asked-for arrow off a body and warns when it cannot. |
+| `LEADER.LOOSE` | A leader does not run from its label to a dot on its named part. | Use `callout({ part })` and anchor on that part. |
+| `LEADER.CROSSING` | Two leaders cross. | Reorder anchors or move one callout to the other side. |
+| `LEADER.SPACING` | A leader runs within 1.2 mm (print size) of another leader or of another leader's dot, so two read as one. | Move one dot to a clearer spot on its part (another face, further along the body), or send that label to the other side. The placer already reorders labels and opens rows to separate them; what it cannot clear it lists in `fig.warnings()`. |
+| `STROKE.MIN` | A stroke under 0.25 pt. | Thicken it; hairlines vanish in print. |
+| `SYMBOL.NO_BOX` | A symbol group without its box. | Draw symbols with the kit factories. |
+| `TAG.GRAMMAR` | A tag breaks ISA-5.1 or the equipment pattern. | See `pid-symbols.md` section 1. |
+| `LINE.NUMBER` | A P&ID line number is not size-fluid-sequence-class[-insulation]. | Write it as `2"-P-1001-A1A`; see `pid-symbols.md` section 6. |
+| `TAG.DUPLICATE` | Two items share a tag. | Number loops and trains uniquely. |
+| `LEGEND.COVERAGE` | A sheet draws a kind the legend lacks; a figure draws a stream role its key lacks. | Let the sheet build its legend; add the role to `fig.key`. |
+| `TITLEBLOCK.FIELDS` | Title, number, revision, date or scale empty. | Fill them in `createSheet`. |
+| `PALETTE.CVD` | Two stream colours are too close for some reader. | Use the `STREAM` roles; never invent colours for categories. |
+| `PANEL.LABELS` | Panel labels missing, out of order, unequal or misplaced. | Use `fig.panel("a", …)` in reading order. |
+| `FONT.FAMILIES` (warn) | More than two families. | Arial for Latin, Pretendard for Hangul. |
+
+## 3. Render and look
+
+Open the PNG at a size where the whole drawing fits, then read it in this order:
+
+1. **Lines.** Every line runs from a port to a port, a junction or a terminal; nothing passes through a body; crossings are hops at right angles on straights; no line hugs another.
+2. **Labels.** Nothing on a line, a symbol or the art; every label next to its owner; tags readable.
+3. **Topology.** Trace each stream from source to destination; trace each control loop from element to final element; trace each relief path to its discharge.
+4. **Isometric order.** Nothing behind shows through anything in front; the ground is under everything; tubes, baffles and pipes interleave correctly.
+5. **Cutaways.** Nozzles and brackets stand on closed shell; internals stay inside the wall; the cut faces read as wall thickness.
+6. **Leaders.** Each dot is on the face of the part its label names and on a face the viewer can see.
+7. **Detail.** At this size the drawing reads as one machine or one process; no region is bare where the real thing has parts.
+
+## 4. The close-up sweep
+
+`render.mjs drawing.svg --sheet sweep.png --grid 3x2` renders every region of the drawing enlarged in one image, each cell captioned with its viewBox box. Read every cell for: line ends a hair short of a port, hops that clip a junction, arrowheads on dots, text touching strokes, bolt circles that stop in mid-face, seams that miss the outline, tone steps on a curved body. To inspect one region at print resolution: `render.mjs drawing.svg --crop x,y,w,h --png close.png --dpi 1200`.
+
+## 5. Review checklist
+
+**Content**
+- [ ] Every number on the drawing comes from the brief, or is listed in the reply as an assumption.
+- [ ] Every vessel that can be over-pressured has a relief device with a discharge destination.
+- [ ] Every controller has a measurement and a final element; every instrument has a process connection.
+- [ ] Isolation valves on both sides of control valves and instruments where the process requires them.
+
+**Drawing**
+- [ ] `QA PASS` on the final SVG.
+- [ ] Flow reads left to right; gravity is respected.
+- [ ] The legend and title block are complete (sheets); the key covers every stream role (figures).
+- [ ] Line weights follow the hierarchy; text sizes meet the floor at print size.
+
+**Isometric**
+- [ ] It reads as the real equipment; 40+ parts; each part in its real material colour (grey only on request), at most one accent; halo under the base.
+- [ ] Painter's order correct everywhere; interleaving parts split.
+- [ ] Leaders end on visible faces of their parts; none cross.
+
+**Exports**
+- [ ] PNG at 600 dpi or more, pHYs written; PDF page equals the drawing size; both opened.
+
+## 6. Exports
+
+`qa.mjs drawing.svg --png drawing.png --pdf drawing.pdf [--dpi 600]` adds `PNG.CLOSED` (truncated file or bad checksum), `PNG.DPI` (declared resolution under the requirement, or pixel width that does not match the drawing width at that resolution), `PDF.CLOSED` (no header or end marker) and `PDF.SIZE` (page size differs from the drawing by more than 1 mm). A sheet larger than about 16 000 px at the requested resolution is rendered at the highest resolution Chrome can capture and the render line says so; render crops for a larger print.

package/assets/lithermes-plugin/skills/lit-schematic/scripts/doctor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Reports what lit-schematic can do on this machine. Drawing and QA need only Node; PNG and
+// PDF export need Chrome or Chromium; Korean labels render in Pretendard when it is found; a
+// cutaway's motion loop needs ffmpeg (MP4, GIF) and img2webp (WebP), and is the only part that does.
+// It never installs anything and always exits 0 unless --strict is given and export is blocked.
+//
+//   node doctor.mjs [--out <dir>] [--json] [--strict]
+
+import { accessSync, constants, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { findPretendard } from "./lib/fonts.mjs";
+import { findTool } from "./motion.mjs";
+import { findChrome } from "./render.mjs";
+
+export function diagnose({ out = process.cwd(), env = process.env } = {}) {
+  const major = Number(process.versions.node.split(".")[0]);
+  const chrome = findChrome(env);
+  const font = findPretendard();
+  let writable = false;
+  try {
+    accessSync(existsSync(out) ? out : resolve(out, ".."), constants.W_OK);
+    writable = true;
+  } catch {
+    writable = false;
+  }
+  const checks = [
+    { id: "node", ok: major >= 20, detail: `Node ${process.versions.node}`, needed: "drawing, QA" },
+    { id: "renderer", ok: Boolean(chrome), detail: chrome ?? "no Chrome or Chromium found (set CHROME_PATH)", needed: "PNG, PDF, close-up sheets" },
+    { id: "font.korean", ok: Boolean(font), detail: font ? `${font.file} (${font.source})` : "Pretendard not found; Hangul falls back to the system font", needed: "Korean labels" },
+    { id: "output", ok: writable, detail: resolve(out), needed: "writing files" },
+    { id: "motion.ffmpeg", ok: Boolean(findTool("ffmpeg", env)), detail: findTool("ffmpeg", env) ?? "ffmpeg not found", needed: "motion loop (MP4, GIF)" },
+    { id: "motion.webp", ok: Boolean(findTool("img2webp", env)), detail: findTool("img2webp", env) ?? "img2webp not found", needed: "motion loop (WebP)" },
+  ];
+  const status = !checks[0].ok || !writable ? "BLOCKED" : chrome ? "PASS" : "DEGRADED";
+  return {
+    status,
+    checks,
+    setup: [
+      ...(chrome ? [] : ["Install Google Chrome (or Chromium), or point CHROME_PATH at an existing binary. lit-schematic never installs it for you."]),
+      ...(findTool("ffmpeg", env) && findTool("img2webp", env) ? [] : ["Only for motion loops: install ffmpeg and the WebP tools (img2webp) with your package manager. lit-schematic never installs them."]),
+    ],
+  };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const args = process.argv.slice(2);
+  const i = args.indexOf("--out");
+  const result = diagnose({ out: i >= 0 ? args[i + 1] : process.cwd() });
+  if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else {
+    for (const c of result.checks) console.log(`${c.ok ? "ok  " : "MISS"} ${c.id.padEnd(12)} ${c.detail}  [${c.needed}]`);
+    for (const line of result.setup) console.log(`setup: ${line}`);
+    console.log(`DOCTOR ${result.status}`);
+  }
+  process.exitCode = args.includes("--strict") && result.status !== "PASS" ? 1 : 0;
+}

package/assets/lithermes-plugin/skills/lit-schematic/scripts/lib/figure.mjs

@@ -0,0 +1,81 @@
+// Journal figure pages: an exact column width in millimetres, panels with (a), (b) labels at
+// their top left, a key of stream colours, and the same mm user space as every other kit
+// drawing so the QA gate reads sizes at print scale.
+
+import { createCanvas } from "./sheet.mjs";
+import { el, esc, n, pathOf, ptToMm, svgDocument } from "./svg.mjs";
+import { JOURNAL, STREAM, fontFor } from "./theme.mjs";
+
+export const WIDTHS = JOURNAL.width;
+
+export function createFigure({ width = "double", height, title, desc = "", lang = "en", mode = "journal", labelStyle = "paren", textPt = JOURNAL.textPt } = {}) {
+  const w = typeof width === "number" ? width : WIDTHS[width];
+  if (!w) throw new Error(`createFigure: width must be a number of mm or one of ${Object.keys(WIDTHS).join(", ")}`);
+  if (!height) throw new Error("createFigure: height in mm is required");
+  if (height > JOURNAL.maxHeight) throw new Error(`createFigure: ${height} mm is taller than a journal page allows (${JOURNAL.maxHeight} mm)`);
+  const panels = [];
+  const layers = [];
+  const text = ptToMm(textPt);
+  const panelText = ptToMm(JOURNAL.panelPt);
+
+  function panel(label, [x, y, pw, ph]) {
+    const box = [x, y, x + pw, y + ph];
+    const inner = label === null ? box : [x, y + panelText + 1.6, x + pw, y + ph];
+    const entry = { label, box, inner, body: [] };
+    panels.push(entry);
+    return {
+      box,
+      inner,
+      label,
+      canvas: (options = {}) => {
+        const c = createCanvas({ box: options.box ?? inner, style: "journal", ...options });
+        entry.body.push(() => c.render());
+        entry.canvas = c;
+        return c;
+      },
+      iso: (view, { box: target = inner, labelColumn = null, calloutSize = text } = {}) => {
+        const fitted = view.fit(target, { labelColumn, size: calloutSize });
+        entry.view = view;
+        entry.body.push(() => view.render() + view.renderCallouts({ box: target, size: calloutSize }));
+        return fitted;
+      },
+      text: (tx, ty, content, { size = text, anchor = "start", bold = false, color = "#000000", kind = "note" } = {}) => {
+        entry.body.push(() => el("text", { x: tx, y: ty, "font-family": fontFor(content), "font-size": size, "text-anchor": anchor, "font-weight": bold ? "bold" : undefined, fill: color, "data-label": kind }, esc(content)));
+      },
+      raw: (svg) => entry.body.push(() => svg),
+    };
+  }
+
+  // A key of stream roles: a short line swatch and its name, one row each.
+  function key(roles, [x, y], { columns = 1, colWidth = 34, rowHeight = text + 1.6 } = {}) {
+    const rows = roles.map((role, i) => {
+      const spec = STREAM[role];
+      if (!spec) throw new Error(`key: unknown stream role ${role}`);
+      const cx = x + (i % columns) * colWidth;
+      const cy = y + Math.floor(i / columns) * rowHeight;
+      return el("g", { "data-legend-item": `role:${role}` },
+        el("path", { d: pathOf([[cx, cy - text * 0.3], [cx + 7, cy - text * 0.3]]), stroke: spec.color, "stroke-width": ptToMm(JOURNAL.linePt * 1.4), "stroke-dasharray": spec.dash ?? undefined, fill: "none", "data-legend-line": role }),
+        el("text", { x: cx + 9, y: cy, "font-family": fontFor(spec.label), "font-size": text, fill: "#000000", "data-label": "legend" }, esc(spec.label)));
+    });
+    layers.push(el("g", { "data-key": "streams" }, rows));
+  }
+
+  function render() {
+    const body = [el("rect", { x: 0, y: 0, width: w, height, fill: "#ffffff" })];
+    panels.forEach((p) => {
+      if (p.label === null) {
+        body.push(el("g", { "data-figure-body": "1" }, p.body.map((f) => f())));
+        return;
+      }
+      const [x0, y0] = p.box;
+      const shown = labelStyle === "paren" ? `(${p.label})` : labelStyle === "bold" ? p.label : p.label.toUpperCase();
+      body.push(el("g", { "data-panel": p.label, "data-panel-box": p.box.map(n).join(" ") },
+        el("text", { x: x0 + 0.2, y: y0 + panelText * 0.8, "font-family": fontFor(shown), "font-size": panelText, "font-weight": "bold", fill: "#000000", "data-label": "panel-label" }, esc(shown)),
+        p.body.map((f) => f())));
+    });
+    body.push(...layers);
+    return svgDocument({ width: w, height, title, desc, mode, lang, body: body.join(""), extra: { "data-min-text-pt": JOURNAL.minTextPt } });
+  }
+
+  return { width: w, height, text, panel, key, render, warnings: () => panels.flatMap((p) => [...(p.canvas?.warnings ?? []), ...(p.view?.warnings ?? [])]) };
+}

package/assets/lithermes-plugin/skills/lit-schematic/scripts/lib/fonts.mjs

@@ -0,0 +1,27 @@
+// Locates fonts for rendering. Pretendard ships with the diagram skill (unmodified official
+// file under the OFL); lit-schematic reads it from there instead of carrying a second copy.
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+
+export function findPretendard() {
+  const inPlugin = [
+    join(SKILL_ROOT, "..", "lit-diagram-drawer", "assets", "fonts", "PretendardVariable.woff2"),
+    join(SKILL_ROOT, "..", "lit-pptx", "pretendard-font", "public", "static", "Pretendard-Regular.otf"),
+  ];
+  for (const file of inPlugin) if (existsSync(file)) return { file, source: "plugin" };
+  const dirs = [join(homedir(), "Library", "Fonts"), "/Library/Fonts", join(homedir(), ".local", "share", "fonts"), "/usr/share/fonts", "C:\\Windows\\Fonts"];
+  for (const dir of dirs) {
+    try {
+      const hit = readdirSync(dir).find((name) => /^Pretendard.*\.(?:otf|ttf|woff2)$/iu.test(name));
+      if (hit) return { file: join(dir, hit), source: "system" };
+    } catch {
+      // directory absent on this platform
+    }
+  }
+  return null;
+}