devagent-ai 0.8.7__tar.gz → 0.8.12__tar.gz

{devagent_ai-0.8.7/devagent_ai.egg-info → devagent_ai-0.8.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devagent-ai
-Version: 0.8.7
+Version: 0.8.12
 Summary: Evidence-driven local autonomous software engineering agent
 Author: Tom Ha
 Maintainer: Tom Ha
@@ -26,9 +26,12 @@ Requires-Dist: openai>=1.40.0
 Requires-Dist: anthropic>=0.34.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Provides-Extra: live
+Requires-Dist: asyncua<3,>=2.0; extra == "live"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: asyncua<3,>=2.0; extra == "dev"
 Dynamic: license-file
 
 # DevAgent
@@ -39,21 +42,76 @@ Dynamic: license-file
 [![Production CI](https://github.com/tomha85/devagent/actions/workflows/ci.yml/badge.svg)](https://github.com/tomha85/devagent/actions/workflows/ci.yml)
 [![Sponsor DevAgent](https://img.shields.io/badge/Sponsor-DevAgent-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)
 
-**A local, evidence-driven software engineering agent that turns a requirement into a tested, independently reviewed patch, prints a developer-grade engineering report, and only publishes a branch when the result is `VERIFIED`.**
+**A local, evidence-driven engineering agent for software engineering, offline PLC engineering/FAT review, and read-only onsite commissioning that turns source evidence and trusted runtime observations into bounded engineering decisions without treating model confidence as proof.**
 
-> **From requirement to evidence-backed verified branch.**
+> **From requirement to evidence-backed engineering decisions.**
 
 > ❤️ **DevAgent is free during public beta.** If DevAgent saves you engineering time, consider [sponsoring continued development](https://github.com/sponsors/tomha85).
 
-DevAgent runs against a developer's local repository. It discovers the application, gathers source evidence, compiles explicit acceptance criteria, plans a bounded change, creates backups, implements the minimum necessary patch, runs repository-supported verification, independently reviews the final diff, and decides `VERIFIED`, `PARTIALLY_VERIFIED`, or `BLOCKED` from evidence rather than model confidence.
+DevAgent runs against a developer's local repository or supported exported PLC engineering artifacts. For software work, it discovers the application, gathers source evidence, compiles explicit acceptance criteria, plans a bounded change, creates backups, implements the minimum necessary patch, runs repository-supported verification, independently reviews the final diff, and decides `VERIFIED`, `PARTIALLY_VERIFIED`, or `BLOCKED` from evidence rather than model confidence.
 
-For a normal verified run the deterministic harness prints the complete engineering report first, then commits reviewed paths and fast-forward pushes the developer's current non-protected branch. If the developer starts on `main`, `master`, or `trunk`, DevAgent creates a new safe branch instead. Runtime DevAgent never creates a pull request, merges, rebases, force-pushes, or deploys.
+For PLC engineering, **DevAgent PLC** provides a vendor-dispatched offline/pre-site review workflow for **Siemens TIA Portal**, **Rockwell Studio 5000 / Logix Designer**, and **Schneider Electric EcoStruxure Control Expert / Unity Pro**. It normalizes supported exports into a canonical PLC model, analyzes logic and dependencies, verifies requirements where evidence permits, detects engineering risks, generates FAT procedures, evaluates regression impact, produces recommendations and evidence, and reports release readiness without pretending that static analysis replaces simulator, HIL, or real-PLC execution.
+
+For onsite commissioning, **DevAgent Live** is a separate first-class **read-only product branch**. It owns its own onsite commissioning workflow, connects to OPC UA endpoints, reconciles engineering tags to runtime nodes, rejects bad/stale/replayed/ambiguous evidence, and supports deterministic blocker diagnosis, recursive tracing, stateful/historical context, numeric/analog comparisons, handshakes, AOI/FB context, fault codes, sequencers, motion/PID context, and bounded AI explanation. Live may consume stable canonical PLC engineering context through a read-only adapter contract, but it is not a sub-branch of DevAgent PLC and does not inherit FAT or release-readiness authority.
+
+For a normal verified software run the deterministic harness prints the complete engineering report first, then commits reviewed paths and fast-forward pushes the developer's current non-protected branch. If the developer starts on `main`, `master`, or `trunk`, DevAgent creates a new safe branch instead. Runtime DevAgent never creates a pull request, merges, rebases, force-pushes, or deploys.
+
+## General Architecture
+
+DevAgent has **three sibling product branches** under one evidence-driven core. Each branch owns a distinct engineering responsibility, input model, safety boundary, and qualification path.
+
+```mermaid
+%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 50, "rankSpacing": 55}}}%%
+flowchart TB
+    CORE["DevAgent Core<br/>Evidence-Driven Engineering Platform"]
+
+    CORE --> SW["Software Engineering<br/>Product Branch #1"]
+    CORE --> PLC["DevAgent PLC<br/>Product Branch #2"]
+    CORE --> LIVE["DevAgent Live<br/>Product Branch #3"]
+
+    SW --> SW_IN["Local / GitHub Repository"]
+    SW_IN --> SW_FLOW["Understand · Plan · Modify · Test · Review"]
+    SW_FLOW --> SW_OUT["Engineering Report · Safe Branch"]
+
+    PLC --> PLC_IN["PLC Engineering Export"]
+    PLC_IN --> PLC_VENDOR["Siemens · Rockwell · Schneider"]
+    PLC_VENDOR --> PLC_MODEL["Canonical PLC Engineering Model"]
+    PLC_MODEL --> PLC_OUT["Analyze · Verify · FAT · Release Readiness"]
+
+    LIVE --> LIVE_IN["Engineering Context + OPC UA Endpoint(s)"]
+    LIVE_IN --> LIVE_TRUST["Reconcile · Trust · Freshness · History"]
+    LIVE_TRUST --> LIVE_DIAG["Deterministic Commissioning Diagnosis"]
+    LIVE_DIAG --> LIVE_OUT["Evidence · Explanation · Next Check"]
+```
+
+| Product branch | Primary input | Authority |
+| --- | --- | --- |
+| **Software Engineering** | Local / GitHub repository | Understand, modify, verify, review, report, publish a safe branch |
+| **DevAgent PLC** | Exported PLC engineering artifacts | Offline engineering review, requirements, FAT, evidence, release readiness |
+| **DevAgent Live** | Read-only engineering context + OPC UA runtime | Onsite commissioning diagnosis, runtime evidence, history, Q&A — **no PLC control** |
+
+### Read-only PLC → Live integration contract
+
+DevAgent Live is **not a child of DevAgent PLC**. PLC engineering context crosses into Live through a bounded data contract; PLC theorem/FAT ownership remains in DevAgent PLC, while OPC UA sessions, runtime trust/history, diagnosis, and commissioning Q&A remain owned by DevAgent Live.
+
+```mermaid
+%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 50, "rankSpacing": 45}}}%%
+flowchart LR
+    MODEL["Canonical PLC Engineering Model"] -. "READ-ONLY ENGINEERING CONTEXT" .-> ADAPTER["DevAgent Live Adapter"]
+    OPC["OPC UA Runtime Evidence"] --> ADAPTER
+    ADAPTER --> JOIN["Engineering ↔ Runtime Join"]
+    JOIN --> DIAG["Commissioning Diagnosis"]
+```
+
+**Solid lines** represent normal execution/data flow. The **dotted line** represents the read-only engineering-context contract; it does not transfer FAT, release-readiness, or PLC control authority to Live.
+
+For the expanded branch boundaries, ownership model, internal flows, and evidence rules, see [General Architecture](docs/general-architecture.md).
 
 ## Why DevAgent?
 
 Many coding agents optimize first for code generation. DevAgent is built around a different question:
 
-**Can this change be supported by repository evidence and verified on the current revision?**
+**Can this change or engineering claim be supported by evidence on the exact analyzed revision/export?**
 
 Core principles:
 
@@ -68,6 +126,7 @@ Core principles:
 - **Developer-grade reporting** — implementation logic, symbols, tests, acceptance evidence, verification, failures, gaps, and source-control status are recorded before publication.
 - **Bring your own model** — OpenAI, Anthropic/Claude, xAI/Grok, Google Gemini, and OpenAI-compatible endpoints use one engineering workflow.
 - **Deterministic branch publication** — only a `VERIFIED` isolated run can be committed and normally fast-forward pushed; `--no-publish` keeps the result local.
+- **Read-only commissioning boundary** — DevAgent Live can diagnose trusted runtime state but cannot turn an AI answer into PLC control authority.
 
 ## Install
 
@@ -77,6 +136,12 @@ From PyPI:
 python -m pip install devagent-ai
 ```
 
+For DevAgent Live with OPC UA runtime support:
+
+```bash
+python -m pip install "devagent-ai[live]"
+```
+
 For an isolated CLI installation:
 
 ```bash
@@ -256,13 +321,13 @@ Binary data, invalid UTF-8, secret-like paths, and files above the input-size bo
 
 ## PLC engineer quick start
 
-DevAgent also provides an **offline PLC engineering review, requirement-verification, regression-analysis, risk-review, and FAT-planning workflow** through `devagent plc`.
+DevAgent also provides an **offline PLC engineering review, requirement-verification, regression-analysis, risk-review, and FAT-planning workflow** through `devagent plc` for Siemens, Rockwell, and Schneider engineering exports.
 
-The PLC workflow is intended for controls/PLC engineers who want to review exported engineering artifacts before FAT, site travel, commissioning, or release. DevAgent does **not** connect to, upload to, download to, force, start, stop, or control a PLC, TIA Portal, Studio 5000, PLCSIM, Logix Echo, HIL bench, or production machine. Runtime FAT and commissioning execution remain owned by the PLC engineer.
+The PLC workflow is intended for controls/PLC engineers who want to review exported engineering artifacts before FAT, site travel, commissioning, or release. DevAgent PLC does **not** connect to, upload to, download to, force, start, stop, or control a PLC, TIA Portal, Studio 5000, Control Expert, PLCSIM, Logix Echo, HIL bench, or production machine. Runtime FAT and commissioning execution remain owned by the PLC engineer; onsite read-only assistance belongs to the separate `devagent live` product branch.
 
 ### 1. Export the PLC project
 
-**Rockwell Studio 5000:** export the full controller project as `.L5X`.
+**Rockwell Studio 5000 / Logix Designer:** export the full controller project as `.L5X`.
 
 ```text
 Line1_Controller.L5X
@@ -270,6 +335,12 @@ Line1_Controller.L5X
 
 **Siemens TIA Portal:** provide a TIA Openness/XML/generated-source file or export directory. Supported engineering inputs include `.scl`, `.db`, `.udt`, `.xml`, `.stl`, and `.awl`. Proprietary `.ap*` / `.zap*` project archives must be exported from TIA Portal first.
 
+**Schneider Electric EcoStruxure Control Expert / Unity Pro:** export `.XEF` when possible. DevAgent also accepts supported granular Control Expert XML exchange files such as `.XSY`, `.XST`, `.XLD`, `.XBD`, `.XSF`, `.XIL`, `.XDD`, `.XDB`, `.XHW`, and `.XCM`. `.STU` and `.STA` work/archive formats are not direct static-analysis inputs; export the project to `.XEF`. A `.ZEF` may contain broader project exchange data, but use an extracted/supported engineering export for DevAgent analysis rather than assuming the archive itself is directly analyzable.
+
+```text
+Machine_Controller.XEF
+```
+
 #### Siemens `.zapXX` archived projects
 
 Files such as `.zap17`, `.zap18`, `.zap19`, and `.zap20` are **TIA Portal archived projects**, not direct DevAgent static-analysis inputs. Do not point `devagent plc` directly at a `.zapXX` archive and assume the internal archive contents are equivalent to a supported engineering export.
@@ -370,6 +441,15 @@ devagent plc ./exports/TIA_Line1/ \
   --output-dir ./plc-review/line1-current
 ```
 
+Schneider:
+
+```bash
+devagent plc ./exports/Machine_Controller.XEF \
+  --requirements ./requirements/line1.md \
+  --ai \
+  --output-dir ./plc-review/line1-current
+```
+
 `--ai` enables the evidence-constrained AI engineering-review layer. It is optional; the deterministic PLC analysis and FAT-planning path still runs without it.
 
 ### 4. Compare a PLC revision
@@ -384,7 +464,7 @@ devagent plc ./exports/new/TIA_Line1/ \
   --output-dir ./plc-review/line1-revision
 ```
 
-The same pattern works for Rockwell using current and previous `.L5X` files.
+The same pattern works for Rockwell using current and previous `.L5X` files and for Schneider using current and previous supported Control Expert exports such as `.XEF`.
 
 ### 5. Review the evidence package
 
@@ -418,8 +498,442 @@ ENGINEERING APPROVAL
         ↓
 SITE COMMISSIONING / RELEASE PROCESS
 ```
+For signed runtime-result, policy, trust-store, and approval workflows, and a complete explanation of Rockwell/Siemens/Schneider evidence boundaries, see **[PLC Engineer Guide](docs/plc-engineer-guide.md)**.
+
+## DevAgent Live onsite commissioning quick start
+
+Use **DevAgent Live** when an onsite controls engineer needs to understand the running controller/system, inspect trusted current state, diagnose why an output is blocked, trace modeled PLC logic upstream, inspect recent trusted transitions, or identify the next evidence-backed check. Live is a separate read-only product branch: the LLM may understand the engineer's wording, but **deterministic PLC logic plus trusted OPC UA evidence decide the engineering result**.
+
+```text
+DevAgent PLC  = Product Branch #2 — offline engineering / FAT authority
+DevAgent Live = Product Branch #3 — onsite read-only commissioning
+```
+
+For the strongest diagnosis, provide both the supported PLC engineering export/context and a read-only OPC UA endpoint:
+
+```text
+Supported PLC engineering export
+              +
+      OPC UA runtime endpoint
+              ↓
+         DevAgent Live
+              ↓
+  reconcile engineering ↔ runtime
+              ↓
+ deterministic diagnosis + evidence
+```
 
-For signed runtime-result, policy, trust-store, and approval workflows, and a complete explanation of Rockwell/Siemens evidence boundaries, see **[PLC Engineer Guide](docs/plc-engineer-guide.md)**.
+### 1. Install Live support
+
+From PyPI:
+
+```bash
+python -m pip install "devagent-ai[live]"
+```
+
+From a source checkout:
+
+```bash
+git clone https://github.com/tomha85/devagent.git
+cd devagent
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+If AI language routing is enabled, configure a provider and keep its API key in an environment variable. Example with OpenAI:
+
+```bash
+export OPENAI_API_KEY=...
+devagent setup --provider openai --model YOUR_OPENAI_MODEL
+```
+
+Do not paste API keys into prompts, command history, issue comments, or logs.
+
+### 2. Run the included Rockwell + OPC UA demo
+
+The repository includes a small commissioning handoff package:
+
+```text
+examples/live/
+├── warehouse_commissioning_demo.L5X   # authoritative Rockwell engineering export
+├── IO_List.csv                        # supplemental context
+├── Tag_Descriptions.csv               # supplemental context
+├── requirements.md                    # supplemental context
+└── FAT_tests.csv                      # supplemental context
+```
+
+Terminal 1 — start the built-in read-only OPC UA simulator in a healthy state:
+
+```bash
+cd ~/devagent
+source .venv/bin/activate
+
+devagent live sim \
+  --endpoint opc.tcp://127.0.0.1:4841/devagent/simulator/ \
+  --scenario healthy
+```
+
+Useful simulator scenarios include:
+
+```text
+healthy             steady healthy operation
+idle                intentional inactivity; not a proven machine fault
+drive_fault         DriveFault=True, DriveReady=False, FaultCode=101
+downstream_blocker  downstream permissive blocks RunCmd
+safety_trip         safety chain fault
+multi_blocker       multiple missing permissives
+logic_conflict      modeled logic expects RunCmd=True but runtime is False
+stuck_on_conflict   modeled logic expects RunCmd=False but runtime is True
+normal              dynamic test mode with changing DownstreamReady/RunCmd
+```
+
+The simulator is for development and qualification of the software path. It does **not** certify a real PLC/vendor endpoint for commercial field readiness.
+
+### 3. Start the interactive Live assistant
+
+Terminal 2:
+
+```bash
+cd ~/devagent
+source .venv/bin/activate
+
+devagent live assist \
+  --project-folder examples/live \
+  --primary-project warehouse_commissioning_demo.L5X \
+  --endpoint opc.tcp://127.0.0.1:4841/devagent/simulator/ \
+  --history-seconds 60 \
+  --ai \
+  --provider openai \
+  --model YOUR_OPENAI_MODEL
+```
+
+For customer/site work, prefer an explicit `--primary-project` so the authoritative PLC source is unambiguous. If AI is not needed, omit `--ai`, `--provider`, and `--model`; deterministic exact-tag/current-state diagnosis remains available.
+
+A successful session prints the selected engineering project, vendor/controller, endpoint, `Mode: READ ONLY`, mapping counts, recursive-trace limits, and history status. If the OPC UA server prints a negotiated session timeout such as:
+
+```text
+Requested session timeout to be 3600000ms, got 600000ms instead
+```
+
+that is informational when the session continues successfully; the server accepted a lower timeout.
+
+### 4. Ask normal commissioning questions
+
+With `--ai`, engineers can use natural wording rather than memorizing fixed command phrases:
+
+```text
+is system ok?
+are there any errors?
+anything I should worry about?
+what is RunCmd?
+why is RunCmd false?
+is motor fault?
+what is DriveReady?
+what error do we have now?
+why did RunCmd stop 20 seconds ago?
+what should I check next?
+```
+
+After a whole-system health answer, immediate bounded follow-ups can be conversational:
+
+```text
+how do I fix this?
+why?
+what should I check first?
+is it still bad?
+```
+
+Example healthy result:
+
+```text
+> is system ok
+DEVAGENT LIVE SYSTEM HEALTH
+Status: NO_CURRENT_PROVEN_FAULT
+...
+DriveFault = False
+FaultCode = 0
+MachineState = RUNNING
+```
+
+Example drive-fault result when Terminal 1 uses `--scenario drive_fault`:
+
+```text
+> are there any errors
+DEVAGENT LIVE SYSTEM HEALTH
+Status: ATTENTION_REQUIRED
+...
+DriveFault = True
+DriveReady = False
+FaultCode = 101
+RunCmd = False
+```
+
+A question such as `is motor fault?` may resolve to the exact engineering signal `DriveFault`. DevAgent can prove the **current PLC signal value** when trusted evidence exists, but it will not claim a physical motor/device root cause unless that deeper cause is actually supported by imported engineering or device/runtime evidence.
+
+#### Conversational whole-system follow-ups
+
+After a validated whole-system `SYSTEM_HEALTH` result, DevAgent may use one bounded conversational context to understand immediate follow-ups such as `how to fix`, `why`, `what should I check first?`, or `is it still bad?`. The previous answer is **context only, not current engineering truth**.
+
+Before answering an accepted whole-system follow-up, Live re-runs the deterministic **CURRENT** system-health diagnosis from trusted OPC UA evidence. The LLM may explain that newly proven result, but it cannot replace it. If the runtime health truth changes while AI wording is being prepared and the configured final-revalidation threshold is exceeded, the AI wording is discarded and the newest deterministic result wins.
+
+Unrelated or confidently different-topic turns clear the whole-system conversational context. Ambiguous/low-confidence routing remains fail-closed. PLC control/write/force/reset/bypass/upload/download/mode/start/stop/jog/override requests never enter whole-system recovery; they are refused under the READ ONLY boundary and terminate stale conversational context rather than reusing it later.
+
+### 5. Current state is refreshed when you ask again
+
+Current-state answers are query-driven and evidence-bounded. Each new current-state question reads fresh trusted OPC UA evidence for the required signals. DevAgent does not keep an old fault as current truth just because it appeared earlier in the conversation.
+
+Example:
+
+```text
+10:00  DriveFault=True, DriveReady=False, FaultCode=101
+       engineer asks: "is system ok?"
+       → ATTENTION_REQUIRED
+
+10:03  fault is cleared in the PLC/device
+       DriveFault=False, DriveReady=True, FaultCode=0
+       engineer asks again: "is system ok now?"
+       → current status is evaluated from the new OPC UA values
+```
+
+Conversation context can help interpret immediate bounded follow-ups, but every accepted whole-system follow-up re-runs current deterministic health before explanation; prior conversational text never overrides trusted current PLC evidence.
+
+Historical questions are separate. Enable a positive retention window such as `--history-seconds 60` or `--history-seconds 900` so Live can retain a bounded rolling timeline of trusted transitions. `--history-seconds 0` disables historical capture.
+
+The `normal` simulator scenario is useful for proving that repeated questions see changing runtime values because `DownstreamReady` and `RunCmd` transition over time.
+
+### 6. Inspect workspace, mapping, connection, and history
+
+Inside `devagent live assist`:
+
+```text
+:workspace     show the project-folder inventory and authoritative PLC input
+:status        show OPC UA connection/security state
+:mappings      show accepted and unresolved engineering ↔ OPC UA mappings
+:refresh       re-browse OPC UA and rebuild reconciliation
+:overview      show engineering, mapping, trace, stateful, and history coverage
+:help          show interactive help
+:disconnect    close the read-only session
+```
+
+Unresolved, stale, BAD, replayed, uncertain, missing, type-incompatible, or ambiguous runtime evidence is not silently trusted as definitive current-state proof.
+
+### 7. Browse limits and diagnosis-trace limits are different
+
+These options control OPC UA browse/reconciliation:
+
+```text
+--max-depth
+--max-nodes
+```
+
+These separate options control recursive deterministic PLC root-cause tracing:
+
+```text
+--trace-max-depth
+--trace-max-nodes
+```
+
+Therefore a command using `--max-depth 5 --max-nodes 500` may still print a banner such as `Recursive root-cause trace: ENABLED (depth=6, nodes=64)` if the trace options were left at their defaults. That is expected.
+
+### OPC UA connection and security setup
+
+For a real PLC, gateway, Ignition OPC UA server, Kepware/KEPServerEX instance, or other OPC UA server, **start with endpoint discovery instead of guessing the security profile**:
+
+```bash
+devagent live probe opc.tcp://192.168.10.20:4840/
+```
+
+`probe` reports the server-advertised endpoint, SecurityPolicy, MessageSecurityMode, user-token types, certificate requirements, DevAgent compatibility, and a preferred supported profile. DevAgent does not modify the server during discovery or connection.
+
+Use the same OPC UA endpoint/security information already configured for the customer's SCADA or OPC UA client. The server administrator remains responsible for endpoint enablement, accounts, certificates, trust lists, firewall/network access, and permissions.
+
+| Existing OPC UA server profile | DevAgent setup |
+| --- | --- |
+| `NoSecurity` + Anonymous | `--endpoint` only |
+| `NoSecurity` + UserName | `--username`, `--password-env`, and explicit `--allow-insecure-username-password` |
+| Secure + Anonymous | application certificate/key + `--trust-store` or `--server-certificate` |
+| Secure + UserName | application certificate/key + server trust + `--username` / `--password-env` |
+| Secure + X.509 user | application certificate/key + server trust + user certificate/key |
+
+For most customer/factory PKI deployments, prefer a reusable **trust store / CA trust** rather than pinning a separate server certificate for every PLC:
+
+```text
+pki/
+├── devagent-app.der
+├── devagent-app-key.pem
+└── trusted/
+    ├── factory-opcua-root-ca.crt
+    └── factory-opcua-intermediate-ca.cer
+```
+
+Then a typical production connection is:
+
+```bash
+export PLC_OPCUA_PASSWORD='...'
+
+devagent live assist \
+  --project-folder /path/to/customer-line1 \
+  --primary-project plc/Line1.L5X \
+  --endpoint opc.tcp://plc01.factory.local:4840/ \
+  --security-policy Basic256Sha256 \
+  --security-mode SignAndEncrypt \
+  --client-certificate ./pki/devagent-app.der \
+  --client-private-key ./pki/devagent-app-key.pem \
+  --trust-store ./pki/trusted \
+  --username devagent_reader \
+  --password-env PLC_OPCUA_PASSWORD
+```
+
+If PLC01, PLC02, PLC03, and other servers have certificates issued by the same trusted CA chain, the same `--trust-store` can validate them; a separate `--server-certificate` is not required for each PLC. For a self-signed server or when exact per-server pinning is desired, use:
+
+```bash
+--server-certificate ./pki/plc01-server.der
+```
+
+`--server-certificate` and `--trust-store` may also be supplied together for exact pinning plus CA/trust validation. An optional CRL directory can be added with a trust store:
+
+```bash
+--trust-store ./pki/trusted \
+--crl-store ./pki/crl
+```
+
+DevAgent accepts the common certificate formats customers encounter in OPC UA, Windows/enterprise PKI, Ignition, and PLC engineering tools:
+
+| Certificate input | Supported formats |
+| --- | --- |
+| Client application certificate | `.der`, `.pem`, `.cer`, `.crt`, `.pfx`, `.p12` |
+| Pinned server certificate | `.der`, `.pem`, `.cer`, `.crt`, `.pfx`, `.p12` |
+| Trust-store certificates / CA roots | `.der`, `.pem`, `.cer`, `.crt`, `.pfx`, `.p12` |
+| X.509 user certificate | `.der`, `.pem`, `.cer`, `.crt`, `.pfx`, `.p12` |
+| CRL | `.der`, `.pem`, `.crl` |
+
+`.cer` and `.crt` are detected from their content, so either DER-encoded or PEM-encoded certificate files are accepted. A `.pfx/.p12` bundle may contain both the certificate and its private key, so a separate key file is not required for that identity.
+
+Example password-protected application `.pfx`:
+
+```bash
+export DEVAGENT_PFX_PASSWORD='...'
+export PLC_OPCUA_PASSWORD='...'
+
+devagent live assist \
+  --project-folder /path/to/customer-line1 \
+  --primary-project plc/Line1.L5X \
+  --endpoint opc.tcp://plc01.factory.local:4840/ \
+  --security-policy Basic256Sha256 \
+  --security-mode SignAndEncrypt \
+  --client-certificate ./pki/devagent-client.pfx \
+  --private-key-password-env DEVAGENT_PFX_PASSWORD \
+  --trust-store ./pki/trusted \
+  --username devagent_reader \
+  --password-env PLC_OPCUA_PASSWORD
+```
+
+There is intentionally no `--client-private-key` above because the private key is inside the PKCS#12 bundle.
+
+OPC UA **application identity** and **X.509 user identity** are different concepts. `--client-certificate` identifies the DevAgent OPC UA application/SecureChannel; `--user-certificate` is an optional certificate-based user login for the Session. For a server that uses X.509 user authentication:
+
+```bash
+devagent live assist \
+  --project-folder /path/to/customer-line1 \
+  --primary-project plc/Line1.L5X \
+  --endpoint opc.tcp://plc01.factory.local:4840/ \
+  --security-policy Basic256Sha256 \
+  --security-mode SignAndEncrypt \
+  --client-certificate ./pki/devagent-app.der \
+  --client-private-key ./pki/devagent-app-key.pem \
+  --trust-store ./pki/trusted \
+  --user-certificate ./pki/operator-user.der \
+  --user-private-key ./pki/operator-user-key.pem
+```
+
+If the X.509 user identity is a `.pfx/.p12` containing its private key, use `--user-certificate` plus `--user-private-key-password-env` and omit `--user-private-key`.
+
+Passwords and PKCS#12/key passwords are referenced through environment variables; do not put literal secrets on the command line or in commissioning JSON.
+
+Modern executable secure-channel policies include `Basic256Sha256`, `Aes128_Sha256_RsaOaep` / `Aes128Sha256RsaOaep`, and `Aes256_Sha256_RsaPss` / `Aes256Sha256RsaPss`, with `Sign` or `SignAndEncrypt`. `Basic128Rsa15` and `Basic256` remain deprecated compatibility profiles. Recognized ECC policies and IssuedToken/JWT profiles are reported as runtime-unavailable rather than silently downgraded.
+
+For the complete profile matrix, trust-store/CRL rules, PKCS#12 password options, exact-pin behavior, aliases, multi-PLC commissioning JSON, and unsupported-runtime boundaries, see **[DevAgent Live OPC UA Connection Profiles V1](docs/live/opcua-connection-profiles-v1.md)**.
+
+### 8. Connect to a real customer/site project
+
+A typical handoff workspace can contain one authoritative PLC engineering export plus supplemental engineering files:
+
+```text
+customer-line1/
+├── plc/
+│   └── Line1.L5X
+├── io/
+│   └── IO_List.csv
+├── tags/
+│   └── Tag_Descriptions.xlsx
+├── requirements/
+│   └── FDS.md
+├── fat/
+│   └── FAT_tests.csv
+└── drawings/
+    └── conveyor_layout.pdf
+```
+
+Example real-site command:
+
+```bash
+devagent live assist \
+  --project-folder /path/to/customer-line1 \
+  --primary-project plc/Line1.L5X \
+  --endpoint opc.tcp://192.168.10.20:4840/ \
+  --history-seconds 900 \
+  --history-poll-seconds 1 \
+  --history-max-tags 128 \
+  --ai \
+  --provider openai \
+  --model YOUR_OPENAI_MODEL
+```
+
+Supported authoritative engineering surfaces remain vendor-specific: Rockwell Studio 5000 `.L5X`, supported Siemens TIA exported source/XML bundles, and supported Schneider Control Expert/Unity Pro XML exchange exports with `.XEF` preferred. Supplemental files help provide auditable engineering context but do not silently override canonical PLC logic.
+
+For project-folder behavior and authority boundaries, see **[DevAgent Live Project Folder Intake V1](docs/live/project-folder-intake-v1.md)**.
+
+### 9. Read-only safety boundary
+
+DevAgent Live is deliberately read only:
+
+```text
+READ ONLY
+no write
+no force
+no reset
+no bypass
+no upload / download
+no mode change
+no start / stop control
+```
+
+The LLM is used only for bounded language interpretation/explanation. It cannot turn model confidence into PLC truth, invent a valid target, or authorize a PLC control action. Deterministic control/write guards execute before semantic routing.
+
+The Live diagnosis stack can use supported canonical engineering evidence for Boolean logic, recursive dependencies, timers/counters/state machines, numeric/analog comparisons, one-shot/latch context, handshakes, AOI/FB context, fault-code observations, sequencers, motion/PID context, and UDT/array structure context. Unsupported, partial, source-protected, ambiguous, stateful-history-dependent, or untrusted regions remain limited/indeterminate instead of being guessed.
+
+Useful Live commands include:
+
+```bash
+devagent live --help
+devagent live doctor --help
+devagent live probe --help
+devagent live browse --help
+devagent live read --help
+devagent live snapshot --help
+devagent live watch --help
+devagent live plan --help
+devagent live commission --help
+devagent live assist --help
+devagent live qualify --help
+devagent live vendor-qualify --help
+devagent live soak --help
+devagent live readiness --help
+devagent live commercial-readiness --help
+```
+
+Commercial V1 field qualification remains evidence-driven. Real runtime/vendor endpoints and the required soak/doctor artifacts must pass; simulator or missing runtime evidence cannot be converted into a production PASS. See **[DevAgent Live Commercial V1 Qualification Runbook](docs/live/commercial-v1-runbook.md)**.
 
 ## Practical examples
 
@@ -537,6 +1051,7 @@ devagent doctor
 devagent models
 devagent status
 devagent plc --help
+devagent live --help
 devagent benchmark --help
 ```
 
@@ -574,7 +1089,7 @@ A truthful conservative result is preferable to a false `VERIFIED`.
 
 ## Safety boundary
 
-DevAgent uses defense-in-depth controls around repository modification, command execution, and publishing:
+DevAgent uses defense-in-depth controls around repository modification, command execution, publishing, and industrial runtime evidence:
 
 - external isolated worktrees for clean repositories by default;
 - dirty tracked and real untracked developer files are protected;
@@ -588,7 +1103,9 @@ DevAgent uses defense-in-depth controls around repository modification, command
 - only reviewed changed paths are staged;
 - remote branch state is captured and rechecked to block publication races;
 - protected targets are refused and force push is never used;
-- no runtime PR, merge, rebase, force-push, or deployment automation.
+- no runtime PR, merge, rebase, force-push, or deployment automation;
+- DevAgent Live exposes no PLC write/force/reset/bypass/upload/download/mode-change/start-stop control surface;
+- DevAgent Live uses trusted-current/freshness/reconciliation gates before runtime values can support definitive commissioning conclusions.
 
 On Linux, DevAgent can execute engineering commands inside a bubblewrap-based operating-system sandbox. Production qualification exercises required sandbox mode with network access denied. Required mode fails closed when isolation cannot be established rather than silently falling back. Review the report and pushed branch before integrating customer or production code: sandboxing reduces execution risk, but it does not make arbitrary generated changes universally safe.
 
@@ -656,6 +1173,20 @@ Production CI also runs Python 3.10/3.11/3.12, a clean wheel build/install, real
 
 See [docs/production-readiness.md](docs/production-readiness.md) for the project's earlier readiness assessment and its explicit limitations.
 
+### DevAgent Live commercial qualification
+
+DevAgent Live has a separate field-readiness contract because onsite OPC UA behavior cannot be proven by software/static fixtures alone. Commercial V1 requires five evidence gates:
+
+```text
+CV1-001  Real OPC UA LQ-001..LQ-014 = 14 PASS / 0 FAIL / 0 BLOCKED
+CV1-002  Real Rockwell + Siemens + Schneider endpoint qualification
+CV1-003  Deterministic stateful / sequence diagnosis contract
+CV1-004  Trusted historical commissioning timeline contract
+CV1-005  Production doctor PASS + real read-only soak >= 8 hours
+```
+
+Missing real runtime evidence remains `BLOCKED`; an inconsistent or below-contract artifact is `FAIL`. A simulator is useful for development/runtime validation but does not certify a real vendor endpoint. See [docs/live/commercial-v1-runbook.md](docs/live/commercial-v1-runbook.md).
+
 ## Provider architecture
 
 Currently supported:
@@ -712,11 +1243,13 @@ DevAgent 0.8.6 is **beta software with a verified core release baseline**. The e
 
 The current core includes evidence-backed `VERIFIED` / `PARTIALLY_VERIFIED` / `BLOCKED` outcomes, backup-first editing, isolated worktrees, bounded structural file operations, repository-native verification, independent review, safe branch publication, provider/model choice, Java and .NET engineering discovery/execution, SQLite migration forward/rollback verification, large-monorepo deep-manifest discovery, bounded parallel agents, repository-local skills, foreground automations, Linux OS sandboxing, bounded browser/local-UI verification, and real-provider structured-contract benchmarking.
 
-Current `main` also includes vendor-dispatched PLC engineering review for **Rockwell Studio 5000 full-project `.L5X`** and **Siemens TIA Portal exported engineering artifacts**, with separate production qualification workflows and fail-closed evidence boundaries. The Siemens qualification is cumulative through V9 and covers the bounded supported SCL/LAD/FBD, call/interface, state/interlock/recovery, canonical identity/type, support-accounting, malformed-input, revision, and large-project fixture surfaces. Unsupported, protected, ambiguous, or runtime-dependent behavior is withheld from static proof and routed to explicit limitations and engineer-executed FAT rather than silently reported as verified.
+Current `main` also includes vendor-dispatched **DevAgent PLC** engineering review for **Rockwell Studio 5000 full-project `.L5X`**, **Siemens TIA Portal exported engineering artifacts**, and **Schneider Electric EcoStruxure Control Expert / Unity Pro XML engineering exports with `.XEF` preferred**. All three feed the canonical PLC engineering/review/FAT/report pipeline while preserving vendor-specific proof boundaries. Siemens qualification is cumulative through its V9 support-accounting stack. Schneider includes V9 support closeout plus additive V10 real-ST local-action modeling and the PLC Report Contract V1, while unsupported or stateful/runtime-dependent regions remain explicitly `PARTIAL`, `OPAQUE`, `PROTECTED`, or FAT-gated. Rockwell remains the mature Studio 5000 path. These are bounded static engineering capabilities; they do not claim simulator, HIL, field wiring, process physics, or real-controller execution unless corresponding runtime evidence is supplied.
+
+Current `main` also includes the independent **DevAgent Live** onsite product branch. Live consumes canonical PLC engineering context through a read-only adapter contract without modifying DevAgent PLC authority, reconciles engineering tags to OPC UA runtime nodes, applies trust/freshness/replay gates, and supports direct/recursive blocker diagnosis, stateful and historical context, numeric/analog comparisons, one-shot/latch awareness, handshake diagnosis, AOI/FB context, fault-code observations, generic sequencer context, motion/PID context, UDT/array structure context, and bounded conversational whole-system follow-ups that re-read current deterministic health before explanation and final-revalidate slow AI wording. Unsupported or insufficiently evidenced behavior remains bounded/indeterminate. Live's Commercial V1 field-readiness gate still requires real OPC UA 14/14, real three-vendor endpoint evidence, production doctor evidence, and a qualifying read-only soak; merged feature coverage is not itself a claim of completed field certification.
 
-These results are **bounded engineering claims**, not universal-correctness or market-superiority claims. They are tied to explicit qualification cases, pinned revisions, deterministic fixtures/external oracles where applicable, and the environments actually exercised by CI.
+These results are **bounded engineering claims**, not universal-correctness or market-superiority claims. They are tied to explicit qualification cases, pinned revisions, deterministic fixtures/external oracles where applicable, and the environments actually exercised by CI or documented local qualification.
 
-Remaining work is primarily **breadth and external validation**, not missing core architecture: a larger public corpus of pinned upstream repositories and tasks; broader browser/UI coverage across dynamic applications and multiple browser environments; a wider Java/Gradle, .NET test-framework, and PostgreSQL/MySQL migration matrix beyond the current qualified fixtures; larger and more diverse monorepo stress cases beyond the current >12,000-file deep-manifest case; more real-world multi-agent workload studies; continuous paid real-provider benchmarking across a broader set of model/provider combinations; and additional real license-safe Siemens/Rockwell customer export qualification beyond deterministic repository fixtures. GitHub branch protection/rulesets are external repository settings and must be configured separately; DevAgent does not claim to configure them itself.
+Remaining work is primarily **breadth and external validation**, not missing core architecture: a larger public corpus of pinned upstream repositories and tasks; broader browser/UI coverage across dynamic applications and multiple browser environments; a wider Java/Gradle, .NET test-framework, and PostgreSQL/MySQL migration matrix beyond the current qualified fixtures; larger and more diverse monorepo stress cases beyond the current >12,000-file deep-manifest case; more real-world multi-agent workload studies; continuous paid real-provider benchmarking across a broader set of model/provider combinations; additional real license-safe Siemens/Rockwell/Schneider PLC export qualification beyond deterministic repository fixtures and official/demo interoperability samples; and real DevAgent Live commissioning qualification across representative vendor-supported OPC UA endpoints and longer site-like soak runs. GitHub branch protection/rulesets are external repository settings and must be configured separately; DevAgent does not claim to configure them itself.
 
 The project intentionally prioritizes trustworthy outcomes, reproducible evidence, and safe engineering behavior over feature count or unsupported "best agent" claims.
 
@@ -729,7 +1262,8 @@ If DevAgent saves you engineering time or helps you deliver safer, better-verifi
 Your sponsorship helps fund:
 
 - new engineering and PLC capabilities;
-- Siemens and Rockwell verification;
+- Siemens, Rockwell, and Schneider verification;
+- DevAgent Live onsite commissioning qualification;
 - additional AI provider support;
 - regression and production qualification;
 - documentation and examples;
@@ -739,7 +1273,7 @@ Your sponsorship helps fund:
 
 ## Contributing
 
-Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Changes to safety, verification, reporting, acceptance semantics, providers, or bounded publication behavior should include regression evidence and must not give model-generated actions unrestricted Git publishing authority.
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Changes to safety, verification, reporting, acceptance semantics, providers, bounded publication behavior, PLC engineering proof boundaries, or DevAgent Live trust/read-only behavior should include regression evidence and must not give model-generated actions unrestricted Git or PLC control authority.
 
 ## Security