agentic-hil 0.2.0__tar.gz

agentic_hil-0.2.0/AGENTS.md

@@ -0,0 +1,15 @@
+# Agentic HIL Agent Instructions
+
+Agentic HIL is the hardware gate. The project-local `.hardci/config.yaml` is the policy. HardCI adapters are the reference hardware.
+
+For installation and first-time setup, follow [AI_AGENT_QUICKSTART.md](AI_AGENT_QUICKSTART.md) — everything installs user-local without admin rights.
+
+Use Agentic HIL MCP tools for hardware actions. Do not bypass them with raw OpenOCD commands, arbitrary debugger shells, direct serial-device access, direct CAN-adapter access, or direct test-adapter access when an Agentic HIL tool is available.
+
+If a HardCI tool returns `permission_denied`, stop. Do not loosen policy unless the user explicitly asks.
+
+Install or update the local agent setup skill with:
+
+```bash
+agentic-hil skill-install --agent opencode
+```

agentic_hil-0.2.0/AI_AGENT_QUICKSTART.md

@@ -0,0 +1,122 @@
+# AI Agent Quickstart
+
+Use Agentic HIL as the local MCP server for embedded firmware development and embedded hardware actions. HardCI adapters are the reference hardware.
+
+This file is for agents. Humans should start with `README.md` and use `TROUBLESHOOTING.md` for operator-facing diagnostics.
+
+If you were given only the Agentic HIL repository URL and asked to set it up: run the fast path below, install the Agentic HIL skill into your own skill directory, configure the firmware project, then return to the firmware project. Do not clone, checkout, or vendor the Agentic HIL source tree into the firmware project for normal setup.
+
+## Ground Rules
+
+- Never use `sudo` or any administrator privileges for the Agentic HIL installation. Every step below works user-local.
+- Never use `pip install --break-system-packages`, and do not install into the system Python (PEP 668 environments will refuse, and they are right).
+- If the board, debugger, COM port, or artifact path cannot be inferred, ask one concise question instead of guessing.
+
+## Reference Setup
+
+Prefer the supported first path unless the firmware project or user clearly says otherwise:
+
+- STM32 Nucleo-F446RE (a complete demo lives in `examples/nucleo-f446re_demo/`).
+- ST-Link with OpenOCD (`interface/stlink.cfg`, `target/stm32f4x.cfg`).
+- Python 3.10 or newer.
+- Firmware artifacts under `build/`.
+
+## Start Agentic HIL
+
+Fast path, in order — stop at the first step that works:
+
+1. If `agentic-hil --version` works, do not reinstall.
+2. If `uv` is available, run Agentic HIL without installing anything (no admin rights, no `PATH` changes):
+
+```bash
+uvx agentic-hil --version
+```
+
+3. If the PyPI package lookup fails, use the repository as the package source (this is a package source only — it does not create a checkout):
+
+```bash
+uvx --from git+https://github.com/agentic-hil/agentic-hil agentic-hil --version
+```
+
+4. If `uv` is missing but `pipx` is available, the equivalents are `pipx run agentic-hil --version` and `pipx run --spec git+https://github.com/agentic-hil/agentic-hil agentic-hil --version`.
+5. If neither `uv` nor `pipx` is available, install `uv` user-locally (no admin rights; installs to `~/.local/bin`):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+then rerun step 2. A missing runner is a remediable setup prerequisite, not a reason to refuse the Agentic HIL setup.
+
+For the MCP server entry it is usually better to install the `agentic-hil` command persistently (still user-local, still no admin rights):
+
+```bash
+uv tool install agentic-hil        # or from the repository: uv tool install git+https://github.com/agentic-hil/agentic-hil
+```
+
+`pipx install agentic-hil` is the equivalent. Both place `agentic-hil` into `~/.local/bin`; if that is not on `PATH`, fix it with `uv tool update-shell` or `pipx ensurepath` — never with admin rights.
+
+## Install Agent Skill
+
+Agent-driven Agentic HIL installation includes installing the bundled `hardci-config-setup` skill into the active agent's user-level skill directory after the CLI is available:
+
+```bash
+agentic-hil skill-install --agent <agent>          # or: uvx agentic-hil skill-install --agent <agent>
+```
+
+Supported agent names and aliases: `opencode`/`open-code`, `claude-code`/`claude`, `codex`/`codex-cli`/`openai-codex`. For other skill-capable agents use `--agent <name> --target <path>` with that agent's documented user-level skill directory. The CLI package is authoritative: if the installed skill's front-matter version differs from `agentic-hil --version`, rerun `skill-install`.
+
+## Configure Each Project
+
+In every firmware project that should use Agentic HIL:
+
+```bash
+agentic-hil init            # writes the starter .hardci/config.yaml
+# edit .hardci/config.yaml: target, debugger configs, allowed artifact roots,
+# named com_ports / can_buses / adapters — keep the safety policy restrictive
+agentic-hil doctor          # validates config and checks the debugger
+agentic-hil mcp-config --output .mcp.json
+```
+
+Keep `.hardci/` with the project: it defines that project's hardware policy, reports, logs, and allowed artifact locations. Do not reinstall Agentic HIL inside every project.
+
+Expected healthy `agentic-hil doctor` result: `ok: true`, `summary: "HardCI configuration loaded and debugger checked."`, and a nested debugger result with `ok: true`.
+
+## Configure MCP
+
+`.mcp.json` is only the MCP launch entry. The default written by `agentic-hil mcp-config` assumes `agentic-hil` is on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "agentic-hil": {
+      "command": "agentic-hil",
+      "args": ["mcp-stdio", "--config", ".hardci/config.yaml"]
+    }
+  }
+}
+```
+
+If `agentic-hil` is not on `PATH`, use the runner form instead: `"command": "uvx", "args": ["agentic-hil", "mcp-stdio", "--config", ".hardci/config.yaml"]`.
+
+`mcp-stdio` is project-scoped and JSON-RPC only. COM tool calls pass `port_id`, CAN tool calls pass `bus_id`, and test-adapter tool calls pass `adapter_id` as tool arguments. For a continuous plain-text serial channel use a separate `agentic-hil com-stdio --config .hardci/config.yaml --port <port_id>` process — never mix plain text into `mcp-stdio`.
+
+## Use The Tools
+
+Use `tools/list` to discover available MCP tools, then follow this loop:
+
+1. Build firmware.
+2. Check debugger availability with `hardci_debugger_info` if setup is unclear.
+3. Probe with `hardci_probe_target`.
+4. Flash with `hardci_flash_firmware` using `image_path` (usually `build/firmware.elf`), or first call `hardci_artifact_upload` and flash the returned `artifact_id`. Pass `reset_after_flash: true` only when a post-flash reset is explicitly needed.
+5. For serial feedback: `hardci_com_session_start`, stimulate with `hardci_com_write`, read with `hardci_com_read`, stop with `hardci_com_session_stop`.
+6. For CAN: `hardci_can_session_start`, `hardci_can_send`, `hardci_can_read`, `hardci_can_session_stop`.
+7. For simulated sensors, loads, and fault states: `hardci_adapter_session_start`, `hardci_adapter_set_value`, `hardci_adapter_inject_fault`, `hardci_adapter_measure`, `hardci_adapter_clear_fault`, `hardci_adapter_session_stop`.
+8. Read the tool result and `hardci_get_last_report`; diagnose failures with `hardci_classify_last_error`.
+
+Healthy probe and flash signals: `target_detected: true`, `success_confirmed: true`, `verify: true`, an intentional `reset_after_flash` value, plus `report_path` and `log_path` for auditability.
+
+Do not use raw OpenOCD commands, arbitrary COM-port shell tools, direct CAN adapter tools, or direct test-adapter access when an Agentic HIL MCP tool is available. Treat `permission_denied` as authoritative and stop.
+
+## pytest Suites
+
+For CI regression suites the installed package registers a pytest plugin: the `agentic_hil` fixture drives the same tools via `agentic_hil.call(name, arguments)`. Tests skip when no `.hardci/config.yaml` exists and fail loudly when the config is invalid. See `examples/pytest/` and `examples/nucleo-f446re_demo/tests/`.

agentic_hil-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hannes Pauli
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agentic_hil-0.2.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include AGENTS.md
+include AI_AGENT_QUICKSTART.md
+include TROUBLESHOOTING.md
+include SECURITY.md
+include llms.txt
+include LICENSE
+recursive-include src/hardci/schemas *.json
+recursive-include src/hardci/templates *.json
+recursive-include src/hardci/skills *.md
+recursive-include tests *.py
+recursive-include examples *.py *.md
+# The firmware demo is repository content, not package content.
+prune examples/nucleo-f446re_demo

agentic_hil-0.2.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: agentic-hil
+Version: 0.2.0
+Summary: Agentic hardware-in-the-loop tools for AI-assisted embedded firmware loops
+Author-email: Hannes Pauli <mail@hannes-pauli.de>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/agentic-hil/agentic-hil
+Project-URL: Repository, https://github.com/agentic-hil/agentic-hil.git
+Project-URL: Issues, https://github.com/agentic-hil/agentic-hil/issues
+Keywords: mcp,model-context-protocol,embedded,hardware-in-the-loop,openocd,firmware,serial,stlink,debugger,agentic-hil,agentic,hardci,stm32
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.22
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pyserial>=3.5
+Provides-Extra: can
+Requires-Dist: python-can>=4.4; extra == "can"
+Provides-Extra: pyocd
+Requires-Dist: pyocd>=0.36; extra == "pyocd"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Agentic HIL
+
+**Your AI agent can develop firmware on its own — because Agentic HIL closes the loop with real hardware.**
+
+```
++--> build --> flash --> stimulate --> observe --+
+|                                                |
++<-------------- diagnose & fix -----------------+
+
+  your agent, unattended -- you review the pull request
+```
+
+Agentic HIL is a Python package that exposes bounded MCP tools for probing, flashing, resetting, artifact validation, serial and CAN stimulus/feedback, test adapters, reports, and logs — without giving an agent arbitrary host or debugger access. A project-local policy file (`.hardci/config.yaml`) defines exactly which devices, actions, paths, and limits are allowed. That policy gate is what makes unattended hardware access workable in the first place.
+
+HardCI adapters are the reference hardware for Agentic HIL: physical pytest fixtures for sensor simulation, loads, and fault injection.
+
+## Why
+
+A green build is not enough in embedded development: firmware has to behave correctly on the real board. Classic tools automate single steps — flash here, read a log there — but the moment real hardware has to respond, a human is back in the loop. Handing an agent a raw debugger shell or direct serial access instead is neither safe nor reproducible. Agentic HIL closes the gap with a small, auditable gate:
+
+```
+AI agent / CI  ──MCP (stdio)──▶  Agentic HIL  ──policy check──▶  OpenOCD / pyOCD / STM32CubeProgrammer
+                                    │                        serial ports (pyserial)
+                                    │                        CAN (PEAK / SocketCAN / bridge)
+                                    ▼
+                       structured results, reports, logs
+```
+
+Every hardware action is validated against the project policy, executed with timeouts, logged to `.hardci/logs/`, and answered with a structured JSON result (`ok`, `error_type`, `summary`, `likely_causes`, `report_path`, `log_path`) that an agent can act on.
+
+## Install
+
+The easiest path: tell your AI agent
+
+> Install Agentic HIL and set it up for this project.
+
+Agents follow [AI_AGENT_QUICKSTART.md](AI_AGENT_QUICKSTART.md) — everything installs user-local, **no admin rights required, ever**.
+
+By hand, without installing anything (no `PATH` changes; needs [uv](https://docs.astral.sh/uv/) or pipx):
+
+```bash
+uvx agentic-hil --version
+uvx --from git+https://github.com/agentic-hil/agentic-hil agentic-hil --version
+```
+
+Persistent user-local install (recommended for the MCP server entry):
+
+```bash
+uv tool install agentic-hil      # or: pipx install agentic-hil
+agentic-hil init
+agentic-hil doctor
+agentic-hil mcp-config --output .mcp.json
+```
+
+For direct PEAK/SocketCAN access install the CAN extra: `uv tool install 'agentic-hil[can]'`. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) when something does not start.
+
+## MCP Entry
+
+Project-local `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentic-hil": {
+      "command": "agentic-hil",
+      "args": ["mcp-stdio", "--config", ".hardci/config.yaml"]
+    }
+  }
+}
+```
+
+## Configuration
+
+`agentic-hil init` writes a starter `.hardci/config.yaml`. The file is the policy — it names the target, the debugger backend, allowed artifact roots, named serial ports and CAN buses, and per-action permissions:
+
+```yaml
+target:
+  name: "sensor-board"
+  controller: "stm32f4"
+
+debugger:
+  type: "openocd"            # or "pyocd" (most Cortex-M targets), or "stlink" (STM32CubeProgrammer CLI)
+  interface_cfg: "interface/stlink.cfg"
+  target_cfg: "target/stm32f4x.cfg"
+  timeout_s: 60
+
+artifacts:
+  allowed_roots: ["build"]   # firmware may only be flashed from here
+  allowed_extensions: [".elf", ".hex", ".bin"]
+
+com_ports:
+  dut_uart:
+    device: "/dev/ttyACM0"
+    baudrate: 115200
+
+can_buses:
+  dut_can:
+    adapter: "socketcan"     # or "peak", or "process" for a custom bridge
+    channel: "can0"
+    bitrate: 500000
+
+adapters:
+  ntc_sim:                   # sensor/actuator/fault-simulation bridge
+    executable: "examples/adapters/sim_ntc_adapter.py"
+    channels: ["temperature", "resistance"]
+    faults: ["open", "short_to_gnd", "short_to_vcc"]
+
+permissions:
+  allow_flash: true
+  allow_com_write: true
+  allow_can_write: true
+  allow_adapter_write: true
+  allow_raw_debugger_commands: false
+  allow_mass_erase: false
+```
+
+Export the full JSON schema with `agentic-hil schema --output agentic-hil-config.schema.json`.
+
+## MCP Tools
+
+| Group | Tools | Notes |
+|-------|-------|-------|
+| Debugger | `hardci_debugger_info`, `hardci_probe_target`, `hardci_reset_target` | OpenOCD, pyOCD, or STM32CubeProgrammer CLI |
+| Firmware | `hardci_flash_firmware`, `hardci_artifact_upload` | artifacts are validated (path, extension, format, SHA-256) before flashing; post-flash reset requires `reset_after_flash: true` |
+| Serial | `hardci_com_ports_list`, `hardci_com_session_start`, `hardci_com_session_stop`, `hardci_com_write`, `hardci_com_read` | named ports only, buffered background reader |
+| CAN | `hardci_can_buses_list`, `hardci_can_session_start`, `hardci_can_session_stop`, `hardci_can_send`, `hardci_can_read` | PEAK, SocketCAN, or a process bridge |
+| Test adapters | `hardci_adapters_list`, `hardci_adapter_session_start`, `hardci_adapter_session_stop`, `hardci_adapter_set_value`, `hardci_adapter_inject_fault`, `hardci_adapter_clear_fault`, `hardci_adapter_measure` | sensor/actuator/fault simulation via the [adapter bridge protocol](examples/adapters/README.md) |
+| Diagnostics | `hardci_get_last_report`, `hardci_classify_last_error` | structured error classification with likely causes |
+| Debug sessions | `hardci_debug_*` (start/stop/status, breakpoints, continue/halt, symbol info, memory dump) | typed GDB/MI sessions via the OpenOCD backend's gdbserver; unexpected breakpoints and target exceptions are returned as structured stop reasons; symbol allowlist and dump-size limits come from the `debug:` policy section |
+
+A typical loop: build firmware → `hardci_flash_firmware` with `reset_after_flash: true` when a fresh boot is required → `hardci_com_session_start` → stimulate via `hardci_com_write`/`hardci_can_send`/`hardci_adapter_set_value` → assert on `hardci_com_read`/`hardci_can_read`/`hardci_adapter_measure` → on failure, `hardci_classify_last_error`.
+
+## Test Adapters
+
+Real-world firmware bugs show up under electrical conditions that standard lab tools cannot reproduce on demand: an open or shorted sensor, a drifting NTC, a missing load, a bouncing contact. The `adapters:` section connects HardCI to test adapters that simulate exactly these states — physical adapter hardware or pure-software simulators, both speaking the same [JSON bridge protocol](examples/adapters/README.md).
+
+Example diagnosis loop with the bundled NTC simulator (`examples/adapters/sim_ntc_adapter.py`): flash the firmware, set the simulated sensor to 25 °C and assert nominal behavior, inject an `open` fault and assert the firmware reports the sensor failure, clear the fault and assert recovery — every step automated, reproducible, and policy-gated.
+
+## Safety Model
+
+- The agent never gets a shell, a raw debugger, or a device path — only the named, configured resources.
+- Firmware artifacts must live under `artifacts.allowed_roots`, match an allowed extension, pass format plausibility checks, and are hashed before flashing. Path traversal is rejected.
+- Permission switches gate high-risk action classes; `permission_denied` results are authoritative and agents are instructed to stop (see [AGENTS.md](AGENTS.md)).
+- Deliberate interlock: flashing is refused while `allow_raw_debugger_commands` or `allow_mass_erase` is enabled — validated flashing and unrestricted debugger access are mutually exclusive policies.
+- Serial/CAN writes are size-capped (`max_write_bytes`, `max_frame_data_bytes`); reads are buffer-capped. Debugger calls run with timeouts and TCP servers disabled (OpenOCD `gdb_port`/`tcl_port`/`telnet_port disabled`); only a typed debug session opens a `gdb_port`, bound to `localhost` on an ephemeral port for exactly that session, and it is torn down with the session.
+- Test adapter channels and fault names are explicit allowlists — HardCI rejects anything not named in the config before it reaches the adapter bridge.
+- All actions log to `.hardci/logs/` and write a structured report to `.hardci/reports/`.
+
+## pytest Plugin
+
+Installing `agentic-hil` registers a pytest plugin, so CI regression suites can drive the same policy-gated tools without an MCP client:
+
+```python
+def test_open_sensor_diagnosis(agentic_hil):
+    started = agentic_hil.call("hardci_adapter_session_start", {"adapter_id": "ntc_sim"})
+    assert started["ok"] is True
+    injected = agentic_hil.call("hardci_adapter_inject_fault", {"adapter_id": "ntc_sim", "fault": "open"})
+    assert injected["ok"] is True
+    # ...assert the firmware's reaction via hardci_com_read...
+```
+
+The `agentic_hil` fixture loads `.hardci/config.yaml` relative to the pytest rootdir (override with `--hardci-config` or the `hardci_config` ini option). Tests are skipped when no configuration file exists, but an existing invalid configuration fails loudly — a config typo must not silently disable the hardware suite in CI. Adapter, COM, and CAN sessions opened during a test are stopped afterwards so stimulus state cannot leak between tests. See [examples/pytest/](examples/pytest/) for a full diagnosis-loop example, and [examples/nucleo-f446re_demo/](examples/nucleo-f446re_demo/) for the complete loop on real hardware: a bare-metal STM32 firmware that is built, flashed, reset, and asserted on via its UART boot banner.
+
+## Common Commands
+
+```text
+agentic-hil init
+agentic-hil doctor
+agentic-hil com-ports
+agentic-hil mcp-config --output .mcp.json
+agentic-hil mcp-stdio --config .hardci/config.yaml
+agentic-hil com-stdio --config .hardci/config.yaml --port dut_uart
+agentic-hil schema --output agentic-hil-config.schema.json
+agentic-hil skill-install --agent opencode
+```
+
+## Platform Support
+
+Linux, macOS, and Windows (CI-tested on Python 3.10–3.13). Debugger backends: OpenOCD, pyOCD (`agentic-hil[pyocd]` — covers most ARM Cortex-M targets via CMSIS packs and CMSIS-DAP/ST-Link/J-Link probes, set `debugger.target_type`), and STM32CubeProgrammer CLI (auto-discovered on Windows). Direct CAN requires `agentic-hil[can]` (python-can); any other adapter can be attached through the `process` bridge protocol.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+ruff check src tests
+pytest
+python -m build
+twine check dist/*
+```
+
+The package is configured for PyPI publishing through GitHub trusted publishing in `.github/workflows/workflow.yml`.
+
+## Security
+
+Policy bypasses are treated as vulnerabilities — see [SECURITY.md](SECURITY.md).
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).