@aryacode/dsh-engineering 0.8.4 → 0.9.1

package/vendor/l5x/lib/engine/style.js

@@ -0,0 +1,119 @@
+/**
+ * Infer the house style of one L5X project.
+ *
+ * Every number here is counted from the export, and the shape is deliberately
+ * the bundle-wide profile schema (`packages/resources/src/profile.ts`) rather
+ * than an L5X-specific one, so the resources row can validate and store it.
+ * Nothing is inferred from fewer than a handful of samples, and the confidence
+ * field says how much of the project the inference actually saw.
+ *
+ * @module dsh-engineering-l5x/engine/style
+ */
+/** Classify one identifier's case convention. */
+function caseOf(identifier) {
+    if (/^[A-Z][A-Za-z0-9]*$/u.test(identifier))
+        return 'PascalCase';
+    if (/^[a-z][A-Za-z0-9]*$/u.test(identifier))
+        return 'camelCase';
+    if (/^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)+$/u.test(identifier))
+        return 'snake_case';
+    return 'other';
+}
+/** The most common value in a counter, with its count. */
+function top(counts) {
+    let best;
+    for (const [value, count] of counts) {
+        if (best === undefined || count > best.count)
+            best = { value, count };
+    }
+    return best;
+}
+/**
+ * Read the style of one project.
+ *
+ * @param project - Snapshot the session opened.
+ * @returns The profile.
+ */
+export function styleProfileOf(project) {
+    const document = project.document;
+    const rungs = document.routines
+        .filter(routine => routine.body.type === 'RLL')
+        .flatMap(routine => (routine.body.type === 'RLL' ? routine.body.rungs.map(rung => ({ routine: routine.name, rung })) : []));
+    const identifiers = new Map();
+    const prefixes = new Map();
+    const cases = new Map();
+    let sealIn = 0;
+    let latchInstructions = 0;
+    let commented = 0;
+    const evidence = [];
+    const aoiNames = new Set(document.aois.map(aoi => aoi.name.toUpperCase()));
+    let firstSealInRung;
+    for (const { routine, rung } of rungs) {
+        if (rung.comment !== undefined)
+            commented += 1;
+        const text = rung.text;
+        for (const match of text.matchAll(/[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*/gu)) {
+            const whole = match[0];
+            if (aoiNames.has(whole.toUpperCase()))
+                continue;
+            const base = whole.split('.')[0] ?? whole;
+            if (base.length < 5)
+                continue;
+            identifiers.set(base, (identifiers.get(base) ?? 0) + 1);
+            const parts = base.split('_');
+            if (parts.length > 1) {
+                const prefix = parts[0];
+                if (/^[A-Z][A-Za-z]{1,6}$/u.test(prefix) && base.length > prefix.length + 3) {
+                    prefixes.set(prefix, (prefixes.get(prefix) ?? 0) + 1);
+                }
+            }
+            const kind = caseOf(base);
+            if (kind !== 'other')
+                cases.set(kind, (cases.get(kind) ?? 0) + 1);
+        }
+        for (const coil of text.matchAll(/OTE\(([^),]+)\)/gu)) {
+            const target = (coil[1] ?? '').trim();
+            const contact = `XIC(${target})`;
+            const coilIndex = coil.index ?? 0;
+            const contactIndex = text.indexOf(contact);
+            if (contactIndex >= 0 && contactIndex < coilIndex) {
+                sealIn += 1;
+                if (firstSealInRung === undefined)
+                    firstSealInRung = rung.number;
+            }
+        }
+        latchInstructions += (text.match(/OT[LU]\(/gu) ?? []).length;
+    }
+    const total = rungs.length;
+    const dominant = top(prefixes);
+    const dominantCase = top(cases);
+    const prefixShare = dominant === undefined ? 0 : dominant.count / Math.max(1, [...prefixes.values()].reduce((sum, count) => sum + count, 0));
+    const routineCases = new Map();
+    for (const routine of document.routines) {
+        const kind = caseOf(routine.name);
+        if (kind !== 'other')
+            routineCases.set(kind, (routineCases.get(kind) ?? 0) + 1);
+    }
+    const routineCase = top(routineCases);
+    if (dominant !== undefined)
+        evidence.push({ count: dominant.count, note: `tag prefix "${dominant.value}" appears ${dominant.count} time(s)` });
+    if (firstSealInRung !== undefined)
+        evidence.push({ line: firstSealInRung, count: sealIn, note: `seal-in rungs detected from rung ${firstSealInRung}` });
+    evidence.push({ count: total, note: `${total} ladder rung(s) read, ${commented} with a comment` });
+    const confidence = total >= 50 && prefixShare >= 0.5 ? 'high' : total >= 10 ? 'medium' : 'low';
+    return {
+        schema: 1,
+        source: { kind: 'l5x', path: project.path, sha256: project.sha256 },
+        naming: {
+            tags: { prefixes: [...prefixes].sort((left, right) => right[1] - left[1]).slice(0, 6).map(([value, count]) => ({ value, count })), case: dominantCase?.value ?? 'PascalCase' },
+            routines: { case: routineCase?.value ?? 'PascalCase', examples: document.routines.slice(0, 5).map(routine => routine.name) },
+        },
+        idioms: {
+            sealIn: { count: sealIn, form: sealIn > 0 ? 'XIC(seal) in parallel with the start contact, in series with the stop contact' : 'not observed' },
+            latch: { count: latchInstructions },
+        },
+        comments: { total, commented, ratio: total === 0 ? 0 : Number((commented / total).toFixed(2)) },
+        evidence,
+        confidence,
+    };
+}

package/vendor/l5x/lib/session.d.ts

@@ -12,6 +12,7 @@
  * @module dsh-engineering-l5x/session
  */
 import { type L5xDocument } from './model/index.ts';
+import { type L5xStyleProfile } from './engine/style.ts';
 import type { ExecContext } from './core/tool.ts';
 import { L5xError } from './core/errors.ts';
 import type { FsService, FsTarget } from './core/tool.ts';
@@ -93,6 +94,14 @@ export declare class ProjectSession {
      * @returns The open project.
      */
     require(projectId: string | undefined, exec?: ExecContext): Promise<ProjectSnapshot>;
+    /**
+     * Read the house style of one open project.
+     *
+     * @param projectId - Explicit handle, or undefined for the chat's only project.
+     * @param exec - Calling context.
+     * @returns The profile in the shared resources schema.
+     */
+    styleProfile(projectId: string | undefined, exec?: ExecContext): Promise<L5xStyleProfile>;
     /**
      * Resolve one path through the filesystem provider without reading it.
      *

package/vendor/l5x/lib/session.js

@@ -13,6 +13,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { L5xParseError, loadL5x } from "./model/index.js";
+import { styleProfileOf } from "./engine/style.js";
 import { L5xError } from "./core/errors.js";
 import { decodeExport } from "./fs.js";
 /** A failure raised by an analysis engine. */
@@ -130,6 +131,16 @@ export class ProjectSession {
         }
         return project;
     }
+    /**
+     * Read the house style of one open project.
+     *
+     * @param projectId - Explicit handle, or undefined for the chat's only project.
+     * @param exec - Calling context.
+     * @returns The profile in the shared resources schema.
+     */
+    async styleProfile(projectId, exec) {
+        return styleProfileOf(await this.require(projectId, exec));
+    }
     /**
      * Resolve one path through the filesystem provider without reading it.
      *

package/vendor/resources/LICENSE-CONTENT.md

@@ -0,0 +1,17 @@
+# Content licence
+
+The pages under `corpus/` are written for this bundle. They summarise engineering practice and
+implementation rules; they do **not** reproduce the text of any standard or vendor manual.
+
+Each page names its basis in front matter (`basis:`). Those names are attribution, not endorsement:
+
+- **IEC 61131-3** — the programmable-controller languages the pages describe (ST, LD, FBD, SFC).
+- **ISA-101** — human-machine interface design, especially the high-performance HMI model.
+- **ISA-18.2** — alarm management lifecycle and presentation.
+- **Rockwell / Yaskawa / FactoryTalk** — vendor documentation and field practice for those products.
+
+Rule IDs (`CRAFT-NAME-01`, `VIEW-HPM-02`, …) identify this bundle's own rules. They are not the
+standards' clause numbers, and a finding that cites one is this bundle's opinion about your code, not a
+certification.
+
+Standards documents are copyrighted. If you need the normative text, obtain it from the issuing body.

package/vendor/resources/SKILL.md

@@ -0,0 +1,27 @@
+# Engineering standards
+
+Use this skill whenever you write, change or review control code or HMI screens — before you author, not
+after.
+
+## Read first
+
+- `engineering_reference` with no arguments lists the corpus. Search it for the language and the domain
+  you are about to touch (`iec state machine`, `rockwell naming`, `view alarm`, `craft fault`), then read
+  the page. Each page carries rule IDs; cite the ID when you report a finding.
+- When a project or export is open, call `engineering_profile` **before** writing. It reports the naming,
+  idioms and visual conventions the plant already uses, with evidence and a confidence level. Follow the
+  profile where it is confident; where it is low, say so and ask.
+
+## Order of work
+
+1. Read the profile (existing project) or the standard pages (new work).
+2. Author the change with the project's own names and visual language.
+3. `engineering_review` on the draft. Fix findings you agree with; explain the ones you do not.
+4. Then run the product's own validation (`draft_validate`, `ftview_validate`, `mw_compile`).
+
+## Honesty rules
+
+- A profile is evidence, not authority: quote the counts and the source path when you rely on it.
+- A rule ID is this bundle's opinion. Never present it as a standards clause or a certification.
+- Do not reproduce standards text; link the page instead.
+- If the corpus or a profile is unavailable, say which one and continue with the product's own checks.

package/vendor/resources/SOURCE.json

@@ -0,0 +1,6 @@
+{
+  "corpus": 1,
+  "built": "2026-10-27T16:39:24.478Z",
+  "digest": "49ea7864020a72c7affc8f13bbc353a21226e63c1d973111e05898a525dd91de",
+  "pages": 34
+}

package/vendor/resources/corpus/craft/craft-comments-and-intent.md

@@ -0,0 +1,29 @@
+---
+id: craft-comments-and-intent
+title: Comments that explain why
+domain: craft
+level: intro
+basis: [field practice]
+tags: [comments, intent]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-COMMENT-01, CRAFT-COMMENT-02, CRAFT-COMMENT-03]
+---
+## Principle
+
+A comment that repeats the code is noise; a comment that explains the decision is maintenance.
+
+## Rules
+
+- **CRAFT-COMMENT-01** Comment the intent and the constraint (`// 250 ms: debounce for a bouncing
+  proximity switch`), not the instruction.
+- **CRAFT-COMMENT-02** Every non-obvious rung gets a rung comment; every routine gets one line of purpose.
+- **CRAFT-COMMENT-03** Record the change reason and date where the project does that, and never leave
+  commented-out logic as the only record.
+
+## Apply
+
+Write the comment as if the reader has the drawing but not the meeting.
+
+## Anti-patterns
+
+`// set bit`; a wall of comments at the top that no one updates; TODOs without an owner.

package/vendor/resources/corpus/craft/craft-debounce-and-filtering.md

@@ -0,0 +1,29 @@
+---
+id: craft-debounce-and-filtering
+title: Debounce, hysteresis and filtering
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [filter, debounce, hysteresis]
+applies_to: [l5x, mwi]
+rules: [CRAFT-FILTER-01, CRAFT-FILTER-02]
+---
+## Principle
+
+Real sensors are noisy and real processes overshoot. Filter in the PLC with a stated time, not in the
+operator's head.
+
+## Rules
+
+- **CRAFT-FILTER-01** Debounce discrete inputs with a timer sized from the sensor's bounce, and document
+  the time next to the timer.
+- **CRAFT-FILTER-02** Use hysteresis for thresholds that would otherwise chatter, and keep the band in one
+  place per signal.
+
+## Apply
+
+When a value "flickers" on the HMI, find the filter time before adding another one downstream.
+
+## Anti-patterns
+
+Filters stacked three deep with no owner; a debounce so long it hides a real trip.

package/vendor/resources/corpus/craft/craft-fault-handling.md

@@ -0,0 +1,32 @@
+---
+id: craft-fault-handling
+title: Faults: detect, latch, annunciate, reset
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [faults, reset, diagnostics]
+applies_to: [l5x, mwi, optix]
+rules: [CRAFT-FAULT-01, CRAFT-FAULT-02, CRAFT-FAULT-03]
+---
+## Principle
+
+A fault is a fact about the machine, not a message. The logic must detect it, remember it, tell someone,
+and define recovery.
+
+## Rules
+
+- **CRAFT-FAULT-01** Detect at the source and set one bit for one cause; do not infer a fault from a
+  downstream symptom.
+- **CRAFT-FAULT-02** Latch with a reset that only succeeds when the cause is gone; a reset that always
+  clears is a way to run a broken machine.
+- **CRAFT-FAULT-03** Record first-out and the time, and surface it where the operator acts.
+
+## Apply
+
+For each fault, write the four sentences: what detects it, what it stops, how it is shown, how it is
+cleared.
+
+## Anti-patterns
+
+Faults that clear themselves on the next scan; one reset for unrelated faults; a fault with no operator
+message.

package/vendor/resources/corpus/craft/craft-naming.md

@@ -0,0 +1,30 @@
+---
+id: craft-naming
+title: Naming that survives the project
+domain: craft
+level: intro
+basis: [field practice]
+tags: [naming, readability]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-NAME-01, CRAFT-NAME-02, CRAFT-NAME-03]
+---
+## Principle
+
+Names are the interface between the code and everyone who will read it after you.
+
+## Rules
+
+- **CRAFT-NAME-01** One case convention per project (PascalCase for tags is common; follow the project).
+  Consistency matters more than the choice.
+- **CRAFT-NAME-02** Booleans read as assertions (`MotorRunning`, `DoorClosed`), not as questions or
+  negatives (`NotStopped`).
+- **CRAFT-NAME-03** Put units and ranges in the description, not hidden in the name (`Temp_C`, `Speed_mps`).
+
+## Apply
+
+When a name does not fit the project's scheme, prefer the project's scheme; when adding a new concept, add
+it to the scheme and document the prefix.
+
+## Anti-patterns
+
+`tmp`, `data`, `flag`; names that encode the wiring (`DI_3`); renaming a published tag without a migration.

package/vendor/resources/corpus/craft/craft-review-checklist.md

@@ -0,0 +1,29 @@
+---
+id: craft-review-checklist
+title: Pre-handover review checklist
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [review, handover, checklist]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-REVIEW-01, CRAFT-REVIEW-02]
+---
+## Principle
+
+Handover is a review, not a save. Walk the same list every time, and record what was not checked.
+
+## Rules
+
+- **CRAFT-REVIEW-01** Before handover: every fault has a message and a reset, every screen has a way back,
+  every changed tag is documented, and the backup is taken and named.
+- **CRAFT-REVIEW-02** Distinguish "checked" from "not checked" in the handover note; an unchecked item is
+  not a pass.
+
+## Apply
+
+Run the product's own checks first, then `engineering_review`, then the human walkthrough with the
+operator.
+
+## Anti-patterns
+
+A handover that lists only what changed; signing off a screen nobody navigated.

package/vendor/resources/corpus/craft/craft-units-and-ranges.md

@@ -0,0 +1,32 @@
+---
+id: craft-units-and-ranges
+title: Units, ranges and engineering values
+domain: craft
+level: intro
+basis: [field practice]
+tags: [units, range, scaling]
+applies_to: [l5x, mwi, optix]
+rules: [CRAFT-UNIT-01, CRAFT-UNIT-02, CRAFT-UNIT-03]
+---
+## Principle
+
+Every number the operator sees should have a unit, a range and a resolution. A number without those is a
+guess.
+
+## Rules
+
+- **CRAFT-UNIT-01** Carry raw counts and engineering units as separate values with one documented
+  conversion.
+- **CRAFT-UNIT-02** State the valid range and what happens outside it (clamp, fault, ignore) at the
+  conversion point.
+- **CRAFT-UNIT-03** Display the unit next to the value and keep the decimal places consistent with the
+  resolution.
+
+## Apply
+
+When a value moves to a new screen, move its unit and range with it.
+
+## Anti-patterns
+
+Two conversions for one signal; a percentage displayed as a fraction; more decimal places than the sensor
+has.

package/vendor/resources/corpus/iec/iec-ld-fbd-equivalence.md

@@ -0,0 +1,31 @@
+---
+id: iec-ld-fbd-equivalence
+title: Ladder, FBD and ST: same logic, different reading
+domain: iec
+level: intro
+basis: [IEC 61131-3]
+tags: [ladder, fbd, st, translation]
+applies_to: [l5x, mwi]
+rules: [IEC-LANG-01, IEC-LANG-02]
+---
+## Principle
+
+The languages are notations, not designs. Choose the one that makes the intent obvious and keep one
+implementation of each behaviour.
+
+## Rules
+
+- **IEC-LANG-01** Ladder for permissives, interlocks and outputs an electrician will trace; ST for
+  arithmetic, loops and state machines; FBD for signal flow. Do not translate a whole routine because you
+  prefer another language.
+- **IEC-LANG-02** One behaviour, one implementation. A seal-in duplicated in LD and ST will diverge; if a
+  block is reused, make it an FB/AOI and call it.
+
+## Apply
+
+When reviewing inherited code, read it in its own language before proposing a rewrite. A "modernisation"
+that changes scan-order semantics is a behaviour change.
+
+## Anti-patterns
+
+ST one-liners that hide three outputs; ladder with arithmetic chains no one can trace.

package/vendor/resources/corpus/iec/iec-sequences-and-sfc.md

@@ -0,0 +1,32 @@
+---
+id: iec-sequences-and-sfc
+title: Sequences, steps and timeouts
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [sequence, sfc, step]
+applies_to: [mwi, l5x]
+rules: [IEC-SEQ-01, IEC-SEQ-02, IEC-SEQ-03]
+---
+## Principle
+
+A sequence is a state machine whose states are process steps. The difference is that each step has a
+completion condition and a timeout.
+
+## Rules
+
+- **IEC-SEQ-01** Give every step a timeout and a defined action on expiry. A sequence that can wait forever
+  is a fault waiting for an operator.
+- **IEC-SEQ-02** Separate the step advance from the step action: advance on `done OR timeout`, act on the
+  current step.
+- **IEC-SEQ-03** Make hold, abort and reset explicit transitions to named states, not flags that freeze
+  the sequence wherever it was.
+
+## Apply
+
+Draw the sequence (states and transitions) before coding it, and keep the drawing with the project. SFC is
+appropriate when the drawing is the specification; a `CASE` machine is simpler when steps share actions.
+
+## Anti-patterns
+
+Advancing on a timer alone; a reset that clears outputs without leaving the step.

package/vendor/resources/corpus/iec/iec-st-structure.md

@@ -0,0 +1,33 @@
+---
+id: iec-st-structure
+title: Structured Text that reads like a specification
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [st, structure, declarations]
+applies_to: [mwi, optix, l5x]
+rules: [IEC-ST-01, IEC-ST-02, IEC-ST-03]
+---
+## Principle
+
+A POU should be readable top to bottom without scrolling sideways: declarations grouped, one intent per
+block, no hidden state. The reader is a maintenance technician at 2 a.m., not the author.
+
+## Rules
+
+- **IEC-ST-01** Group declarations by role (`VAR_INPUT`, `VAR_OUTPUT`, `VAR`), then by purpose, with a
+  comment above each group. Do not interleave.
+- **IEC-ST-02** One POU, one responsibility. A POU that sequences, scales, filters and writes HMI data has
+  four reasons to change; split it.
+- **IEC-ST-03** No side effects in conditions. A call inside an `IF` that changes state makes the scan
+  order part of the logic; call it explicitly, one statement per line.
+
+## Apply
+
+Order the body: input conditioning, permissives, sequence or control, outputs, diagnostics. A reader can
+then stop at the block they need.
+
+## Anti-patterns
+
+Deeply nested `IF` (three levels or more) hiding permissives; magic numbers instead of named constants;
+declarations added wherever there was space.

package/vendor/resources/corpus/iec/iec-state-machines.md

@@ -0,0 +1,33 @@
+---
+id: iec-state-machines
+title: State machines that fail predictably
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [state-machine, case, sequence]
+applies_to: [mwi, l5x]
+rules: [IEC-SM-01, IEC-SM-02, IEC-SM-03]
+---
+## Principle
+
+A state machine is a contract: exactly one state is active, every transition has a cause, and an
+unexpected state is handled rather than ignored.
+
+## Rules
+
+- **IEC-SM-01** Use one integer or enumeration `step` for the active state and a `CASE` (ST) or
+  integer-compare chain (LD) to act on it. Do not scatter `IF step =` tests through the program.
+- **IEC-SM-02** Every `CASE` has an `ELSE` (or a default branch) that forces a known safe state and raises
+  a diagnostic. An out-of-range step must never leave outputs energised.
+- **IEC-SM-03** Entry actions run once on the transition; continuous actions live in the state body. Mixing
+  them makes a re-entry repeat motion.
+
+## Apply
+
+Name states after the machine condition (`Idle`, `Homing`, `Ready`, `Cutting`, `Faulted`), not after
+numbers in the HMI. Keep a parallel `stepTime` for timeouts.
+
+## Anti-patterns
+
+Two variables claiming to be the state; timers inside the transition condition; a `GOTO` around the
+`CASE`.

package/vendor/resources/corpus/iec/iec-task-model.md

@@ -0,0 +1,31 @@
+---
+id: iec-task-model
+title: Tasks, scan time and determinism
+domain: iec
+level: specialist
+basis: [IEC 61131-3]
+tags: [task, scan, watchdog]
+applies_to: [mwi, l5x]
+rules: [IEC-TASK-01, IEC-TASK-02, IEC-TASK-03]
+---
+## Principle
+
+The task schedule is part of the program. A control loop that moved to a slower task is a behaviour
+change even when the code is untouched.
+
+## Rules
+
+- **IEC-TASK-01** Put motion and fast interlocks in a fixed-rate task; put HMI handshakes and diagnostics in
+  a slower one. Document the rate next to the POU.
+- **IEC-TASK-02** No unbounded work in a cyclic task: no file I/O, no waiting loops, no long string
+  handling. Bound every loop.
+- **IEC-TASK-03** Size the watchdog from the measured worst case, not the average. A watchdog that fires
+  only under load is doing its job.
+
+## Apply
+
+Record for each task: period, priority, watchdog, worst measured scan, and what happens when it overruns.
+
+## Anti-patterns
+
+Copying a fast task into a slow one and accepting the jitter; hiding a blocking call behind a one-shot.

package/vendor/resources/corpus/iec/iec-types-and-scaling.md

@@ -0,0 +1,32 @@
+---
+id: iec-types-and-scaling
+title: Types, ranges and scaling without surprises
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [types, scaling, real]
+applies_to: [mwi, l5x, optix]
+rules: [IEC-TYPE-01, IEC-TYPE-02, IEC-TYPE-03]
+---
+## Principle
+
+Most field faults blamed on "the PLC" are a divide by zero, an overflow, or a REAL compared with `=`.
+
+## Rules
+
+- **IEC-TYPE-01** Declare the narrowest type that holds the range, and say the range in the comment
+  (`INT 0..1000 mm`). Never rely on the default type.
+- **IEC-TYPE-02** Guard every division and scale: check the divisor, clamp the result, and handle the
+  out-of-range case explicitly.
+- **IEC-TYPE-03** Compare REALs with a tolerance, never with equality. For counters and positions, use
+  integers where the resolution allows.
+
+## Apply
+
+Keep one scale/offset pair per signal, in one place. If two blocks scale the same input, they will
+disagree.
+
+## Anti-patterns
+
+`INT` for a millisecond timer that can exceed 32 s; scaling in the HMI and again in the PLC; a REAL used
+as a state number.

package/vendor/resources/corpus/optix/optix-alarms-and-trends.md

@@ -0,0 +1,30 @@
+---
+id: optix-alarms-and-trends
+title: Alarms and trends in Optix
+domain: optix
+level: practitioner
+basis: [FactoryTalk Optix, ISA-18.2]
+tags: [alarms, trends]
+applies_to: [optix]
+rules: [OPTIX-ALM-01, OPTIX-ALM-02]
+---
+## Principle
+
+Alarms and trends are process evidence. Their configuration is part of the design, not a runtime
+afterthought.
+
+## Rules
+
+- **OPTIX-ALM-01** Configure alarm limits and priorities in the model (type or instance), so every
+  instance inherits a reviewed definition.
+- **OPTIX-ALM-02** Choose trend sampling from the process dynamics, and keep the same time base across
+  pens that will be compared.
+
+## Apply
+
+Review the alarm list as a document: condition, limit, priority, message, action. Trends should answer a
+specific question the operator or engineer has.
+
+## Anti-patterns
+
+Alarms enabled per instance with different limits; trend pens on unrelated time bases.

package/vendor/resources/corpus/optix/optix-bindings-and-expressions.md

@@ -0,0 +1,30 @@
+---
+id: optix-bindings-and-expressions
+title: Bindings and expressions
+domain: optix
+level: practitioner
+basis: [FactoryTalk Optix]
+tags: [bindings, expressions, converters]
+applies_to: [optix]
+rules: [OPTIX-BIND-01, OPTIX-BIND-02, OPTIX-BIND-03]
+---
+## Principle
+
+A binding moves a value; an expression computes one. Mixing them hides where a number comes from.
+
+## Rules
+
+- **OPTIX-BIND-01** Bind raw values point to point; put formatting and unit conversion in a formatter or a
+  converter with a name, not inline in the binding.
+- **OPTIX-BIND-02** Validate expressions with the expression tool before attaching them, and handle the
+  null/empty case explicitly.
+- **OPTIX-BIND-03** Keep one source of truth per value: do not bind and also write the same property from
+  NetLogic.
+
+## Apply
+
+When a value looks wrong, trace binding → converter → source before editing any of them.
+
+## Anti-patterns
+
+Long inline expressions in a property; two writers for one property; conversions that silently round.