pyshal 0.1.0__tar.gz

pyshal-0.1.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Fixed
+- **Authoring-contract drift** (#15) — aligned the `shal-build-*` skills with
+  `docs/SDK.md` and the framework so a driver copied verbatim from the
+  `shal-build-driver` skeleton passes `conformance.check_driver` (now regression-
+  tested): the skeleton uses the blessed `shal.TemperatureSensor` and includes the
+  required `llm_ready` + `@op` (no longer framed as "optional"). Also fixed the
+  `src/shal/schema/` path in `shal-build-yaml`, completed its bundled-id list
+  (added `shal,scpi-raw`/`shal,sim-scpi`/`shal,sim-msg`, pointing at
+  `shal.catalog()` as authoritative), added `txn=` to the documented `HopError`
+  signature, and documented the actuator `safe_state()` hook in the SDK.
+
+### Added
+- **Human-in-the-loop actuation gate** (#14) — actuator and destructive/config
+  ops (`@shal.op(side_effect="actuator"|"config")`) now stop for an injectable
+  `Approver` *after* the limit check and *before* any bus I/O. The gate lives in the capability-wrapper, so neither the
+  tool surface (`call_tool`) nor the raw path (`get_device().method()`) can bypass
+  it. SHAL ships the mechanism + a safe default (`ConsoleApprover`: prompt when
+  interactive, deny when headless) plus `AutoApprove`/`DenyAll`/`CallableApprover`;
+  install one with `shal.set_approver(...)` or the `shal.approver(...)` context
+  manager. Refusal raises `shal.ApprovalDenied` (nothing sent) and `call_tool`
+  returns `{"ok": False, "rejected": "approval"}`. Every decision (approved/denied)
+  is written to `shal.audit`. Order is always limits → approval → I/O.
+- **Declared operating limits** (#10) — `@shal.op(params=...)` takes JSON-Schema
+  fragments per parameter; the merged schema is advertised verbatim in
+  `tool_schemas()`/`catalog()` AND enforced by the framework before any bus I/O
+  (`shal.LimitError`; rejected writes are audited `outcome=rejected`). Two
+  narrow-only layers stack on top: `driver.op_limits()` for address-dependent
+  ratings and YAML `config.limits` for installation policy — widening fails the
+  load naming both numbers.
+- **Conformance kit** (#10) — `shal.conformance.check_driver()` self-certifies a
+  driver: static checks (llm_ready, @op metadata, schema well-formedness) plus
+  live probes on a sim topology (limits actually reject pre-I/O, writes actually
+  hit the audit channel, capabilities actually isinstance).
+- **Generic sim buses** (#10) — `shal,sim-scpi` (`@scpi_sim_model`) and
+  `shal,sim-msg` (`@msg_sim_model`) mirror sim-i2c's model registry for the
+  MessageTransport families; ships a DP832 model for hermetic SCPI coverage.
+- **Driver SDK guide** (#10) — `docs/SDK.md`: the complete authoring contract
+  (driver anatomy, capabilities, transport dialects, limits, sims, conformance);
+  with the skills, writing a driver requires reading zero SHAL internals. New
+  `shal-generate-driver` skill: the documentation→driver generation recipe.
+- **Core I²C drivers** (#2/#3) — `microchip,mcp9808` (`TemperatureSensor`),
+  `ti,ads1115` (new `ADC` capability), `microchip,mcp23017` (new `GPIOExpander`
+  capability). All dependency-free, sim-backed (`shal,sim-i2c` models), hermetic tests.
+- **SCPI instrument stack** (#2, Wave 1) — `shal,scpi-raw` bus (SCPI over a raw TCP
+  socket, the lab :5025 convention; stdlib sockets only, no VISA; plaintext with a
+  required `insecure: true`), plus the first instrument drivers `rigol,dp832`
+  (`PowerSupply`) and `keysight,34461a` (`DigitalMultimeter`) and their capability
+  Protocols. End-to-end tested against a fake SCPI socket server (no hardware).
+- **Driver `ti,ina219`** (#2, Wave 1) — I²C bus-voltage / current / power monitor,
+  the first `PowerMonitor` capability. Dependency-free, sim-backed (`shal,sim-i2c`
+  gains an `ina219` model), fully hermetic tests.
+- **Node-level agent metadata** (#1) — optional `description:` (instance context
+  blended into each tool's description, so an agent distinguishes like devices) and
+  `expose: false` (omit a node from `tool_schemas()`/`tool_catalog()`/`call_tool()`
+  while keeping it usable from Python) on any topology node. Additive; existing
+  topologies are unaffected.
+- **`shal.catalog()` authoring surface** (#1) — an introspection view of every
+  registered driver/bus so an LLM (or a human) can construct a valid topology:
+  `catalog()` returns compact summaries, `catalog(compatible)` the full detail.
+  Most fields are derived (compatible, required parent kind, capability Protocol,
+  ops); a class declares only the irreducible bits via an optional `authoring_meta()`
+  classmethod (`address_schema` / `config_schema` / `child_address_schema` as
+  JSON-Schema fragments). Op annotations map side-effects to MCP-style hint names
+  (`readOnlyHint`/`idempotentHint`/`destructiveHint`), also added to `tool_catalog()`.
+- **Topology includes** — a node may `use:` an external `template:` file to graft
+  a reusable subtree (a board, a rack) without copy-paste, with `with:` parameter
+  substitution (`${param}`), use-site key overrides, include chains, a cycle
+  guard, and path confinement to the project tree. Still `yaml.safe_load` only —
+  the splice happens in the loader, never via a YAML tag.
+- **Registry collision policy** — two different classes claiming one `compatible`
+  no longer silently overwrite (last-write-wins). The clash fails the load,
+  naming each providing distribution; disambiguate with a node `from:` key,
+  `register(..., override=True)`, or by uninstalling one. Re-registering the same
+  class stays an idempotent no-op.
+- **LLM tool surface** — `@shal.op(description, unit, side_effect)` metadata on
+  capability ops; `Driver.llm_ready = True` enforces it at bind time.
+  `hal.tool_schemas()` emits Anthropic tool-use definitions for every device op,
+  `hal.tool_catalog()` reports per-op `side_effect`/idempotency for gating, and
+  `hal.call_tool(name, args)` dispatches — a delivery-unknown write is reported,
+  never silently retried. Buses are excluded (they provide transport, not
+  capabilities).
+
+## [0.1.0] - 2026-06-10
+
+Phase 1: the synchronous core.
+
+### Added
+- Topology loader: versioned YAML (`shal_version: 1`) with JSON Schema
+  validation, global id uniqueness, address-grammar validation at load,
+  `$ref` back-links, `${ENV_VAR}` resolution for addresses and `config:` values.
+- Typed transport kinds: `ByteTransport`, `CommandTransport` (argv only),
+  `MessageTransport`, `Stream` (Phase 2 placeholder); `kinds()` introspection.
+- Driver model: registry keyed by `compatible`, entry-point group
+  `shal.drivers`, `@shal.idempotent`, framework-owned retry
+  (reconnect once / retry once for idempotent ops; delivery-unknown writes are
+  never re-fired).
+- Bundled buses: `shal,sim-i2c`, `shal,local`, `shal,ssh-host`,
+  `shal,i2c-cli`, `shal,spi-cli`, `shal,tcp` (TLS default), `shal,http`,
+  `nxp,pca9548` mux with per-mux selection cache.
+- Bundled driver: `ti,tmp102` (`TemperatureSensor` capability).
+- Lookup API: `shal.load()` context manager, `get_device()` by id/path with
+  positional shorthand, deterministic leaf→root teardown.
+- Error taxonomy: `LoadError`, `HopError` (`delivered: no|unknown`),
+  `HopTimeout`, `Busy`, `Gap`.
+- Observability: structured records with stable `event` keys and
+  `path/hop/addr/txn/duration_ms` fields on every hop; WARNING on handled
+  retries; DEBUG breadcrumbs before raising; `shal.audit` channel for
+  actuator-style write ops (silent by default); `shal.logging` with
+  `ConsoleFormatter`, `JSONFormatter`, and the `capture()` JSON-lines flight
+  recorder.
+- Packaging: PEP 621 metadata, `py.typed`, MIT license, CI workflow.

pyshal-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to SHAL
+
+Thanks for your interest. SHAL is a standard-in-the-making, so the bar for the
+core is deliberately high; extending it via drivers and buses is meant to be easy.
+
+## Where complexity goes
+
+> Complexity flows toward the rarest audience; simplicity flows toward users.
+
+Three audiences, in order of how rare they are: **bus authors** (core/experts) →
+**driver authors** (the community) → **end users** (write YAML, call
+capabilities). A change that pushes complexity toward end users is rejected.
+The locked design lives in [docs/DESIGN V2.md](docs/DESIGN%20V2.md) and
+[docs/DECISIONS - V2.1.md](docs/DECISIONS%20-%20V2.1.md) — read them before
+proposing core changes; the invariants there are not up for re-litigation in a PR.
+
+## Project layout
+
+```
+src/shal/        the package (importable as `shal`)
+tests/           pytest suite
+docs/            design + decision records
+examples/demos/  runnable showcases (Deebot cloud, microservice mesh) — not shipped
+examples/driver-creator/  the doc→driver generation benchmark — not shipped
+```
+
+## Dev setup
+
+```sh
+pip install -e ".[dev]"
+python -m pytest          # tests
+ruff check src tests      # lint
+python -m build           # sdist + wheel
+```
+
+Requires Python ≥ 3.10. CI runs the suite on Linux and Windows across 3.10–3.13.
+
+## Adding a driver or bus
+
+Don't edit the core to add hardware support — publish a package that exposes your
+driver via the `shal.drivers` entry point (the bundled drivers are wired the same
+way in `pyproject.toml`). The `.claude/skills/` folder has step-by-step guides:
+`shal-build-driver`, `shal-build-bus`, `shal-build-yaml`.
+
+## Pull requests
+
+- Keep changes minimal and consistent with the documented invariants; the code
+  comments state them explicitly.
+- Every change ships with tests; the suite must stay green and `ruff` clean.
+- A failure that needs a *design decision* rather than a bug fix → open an issue
+  first, don't guess.
+- Update `CHANGELOG.md` under `## [Unreleased]`.
+
+## The non-negotiables (security & safety)
+
+`yaml.safe_load` only · `CommandTransport` carries argv vectors, never shell
+strings · a delivery-unknown write is never auto-retried · secrets via `${ENV}`,
+never in topology files, never logged · the library never configures logging.

pyshal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHAL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyshal-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+# Source distribution contents. Wheel data files are handled by package-data in
+# pyproject.toml; this governs the sdist tarball.
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+recursive-include src/shal *.json py.typed
+recursive-include docs *.md
+
+# Keep examples out of the tarball.
+prune examples
+prune tests
+global-exclude __pycache__ *.py[cod]

pyshal-0.1.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: pyshal
+Version: 0.1.0
+Summary: System/Software Hardware Abstraction Layer — device-tree-inspired, dynamic, user-space, network-capable
+Author: SHAL contributors
+License: MIT
+Project-URL: Documentation, https://github.com/determlab/shal#readme
+Project-URL: Changelog, https://github.com/determlab/shal/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/determlab/shal
+Keywords: hardware,hal,device-tree,i2c,spi,ssh,embedded,lab-automation,robotics,instrumentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# SHAL
+
+### Give an AI agent real hardware — gated, so it asks before it moves.
+
+Describe your whole lab — sensors, instruments, robots, services — in **one YAML
+file**, and hand it to an LLM as **typed, permission-gated tools**: writes stop
+for approval before they reach the device; reads don't. No transport code, no glue.
+
+> In a blind test, an agent wrote working, safety-checked drivers for **4 of 4**
+> devices from documentation alone — then drove a **real robot, gated**.
+
+<!-- BADGES -->
+[![GitHub stars](https://img.shields.io/github/stars/determlab/shal?style=social)](https://github.com/determlab/shal)
+[![PyPI](https://img.shields.io/badge/PyPI-coming_soon-blue)](#install)
+[![Python](https://img.shields.io/badge/python-3.10+-blue)](#install)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#roadmap)
+
+<picture>
+  <source srcset="docs/assets/SHAL_banner.webp" type="image/webp">
+  <img alt="SHAL turns your lab and services into one YAML topology — controlled from Python or exposed to an AI agent as typed, gated tools" src="docs/assets/SHAL_banner.png" width="100%">
+</picture>
+
+
+### [→ Try it in 60 seconds — no hardware required](#quick-start)
+
+</div>
+
+**Built for:**
+
+✓ AI agent builders &nbsp;·&nbsp; ✓ Validation & test engineers &nbsp;·&nbsp;
+✓ Hardware-in-the-loop automation &nbsp;·&nbsp; ✓ Labs with mixed hardware + software
+
+---
+
+## From glue scripts to agent tools — in three steps
+
+**Step 1 · Today, without SHAL** — a separate library, address, and retry per device:
+
+```python
+sensor  = TMP102(i2c_bus, 0x48)
+supply  = SCPIPowerSupply("10.0.0.50:5025")
+results = RESTClient("https://mes.lab.internal")
+# ...and you wire each one's retries, logging, and tool-wrapper by hand
+```
+
+**Step 2 · With SHAL** — describe the rack once, then call devices by name:
+
+```python
+hal = shal.load("lab.yaml")
+
+hal.get_device("ambient_temp").read_celsius()       # I²C sensor
+hal.get_device("dut_power").set_voltage(3.3)        # SCPI supply
+hal.get_device("results_db").record(status="pass")  # HTTP service
+```
+
+> **Validation & test engineers can stop here.** One model for the whole rack —
+> no agent needed, no transport code, no glue.
+
+**Step 3 · Hand the same rack to an agent** — the tool catalog is generated for you:
+
+```python
+tools = hal.tool_schemas()                           # one typed tool per device op
+hal.call_tool("dut_power__set_voltage", {"volts": 3.3})
+```
+
+> Writes are gated, reads aren't. The agent never sees SCPI, I²C, or an address.
+
+---
+
+## Why existing agent frameworks fall short
+
+Most agent tooling assumes **software-only** tools: APIs, databases, functions.
+The moment a tool is a *physical* device — a sensor on I²C, an instrument over a
+raw socket, a robot behind a network hop — you're on your own.
+
+SHAL exposes physical devices, remote labs, instruments, **and** software
+services as the *same* kind of tool — with the safety rails physical actions
+need: gated writes, honest failure, a full audit trail.
+
+---
+
+## One model for hardware *and* software
+
+The core idea is small:
+
+> **A bus is just a node that provides a transport to its children.**
+
+A sensor on I²C and an HTTP service are the same kind of node. Your code — and
+your agent — calls **capabilities** (`read_celsius()`, `set_voltage()`), never
+transports. `[core]` ships with SHAL; `[pkg]` is a driver you install or write.
+
+```yaml
+# lab.yaml — hardware and software in ONE graph
+shal_version: 1
+root:
+  bench:                         # one SSH hop to the bench controller       [core]
+    driver: shal,ssh-host
+    address: ${BENCH_SSH}        # secrets resolve from the environment, never logged
+    children:
+      i2c0:                      # I²C rendered as argv over the SSH hop      [core]
+        driver: shal,i2c-cli
+        address: /dev/i2c-1
+        children:
+          ambient: { id: ambient_temp, driver: ti,tmp102, address: 0x48 }   # [core]
+
+  instruments:                   # raw-socket SCPI bus                        [pkg]
+    driver: acme,scpi
+    address: 10.0.0.50:5025
+    children:
+      supply: { id: dut_power, driver: keysight,e36312, address: ch1 }       # [pkg]
+
+  services:                      # HTTPS to internal services                [core]
+    driver: shal,http
+    address: https://mes.lab.internal
+    children:
+      results: { id: results_db, driver: acme,mes-results, address: api/v2 } # [pkg]
+```
+
+Every node is reached the same way — `hal.get_device("dut_power").set_voltage(3.3)`
+— sensor or database, local or across the network. Same retries, same logs. Swap
+any node for its sim and **nothing in your code changes**.
+
+---
+
+## Features
+
+- **Agent-native** — every device op becomes a gated LLM tool.
+- **Asks before it moves** — actuator & destructive/config ops stop for a
+  host-supplied approver (CLI prompt, an agent, or auto in sim/CI); the gate is
+  pre-I/O and unbypassable.
+- **Hardware + software, one graph** — a sensor and an HTTP service are the same node.
+- **Capabilities, not wires** — call `read_celsius()`, never I²C.
+- **Retry you can trust** — reads auto-retry; risky writes never silently repeat.
+- **Sim-first** — test the whole rack with zero hardware.
+- **Recursive** — muxes, jumpboxes, nested buses: one primitive, no special cases.
+- **Drivers as plugins** — add a device in one small class.
+- **Secure by default** — no shell strings, TLS on, secrets via `${ENV}`.
+- **Observable** — structured logs, one `txn` id per call.
+
+---
+
+## Install
+
+> SHAL is in **alpha** (Phase 1). A PyPI release is coming; for now install from
+> source:
+
+```bash
+pip install git+https://github.com/determlab/shal
+
+# or, for development
+git clone https://github.com/determlab/shal && cd shal
+pip install -e ".[dev]"                                  # pytest, ruff
+```
+
+Requires **Python ≥ 3.10**. Dependencies: `pyyaml`, `jsonschema`.
+
+---
+
+## Quick Start
+
+Runs with **zero hardware** — the simulated bus ships with SHAL. New to hardware?
+This is the whole setup, and it's just Python and a YAML file.
+
+```yaml
+# sim.yaml
+shal_version: 1
+root:
+  bus:
+    driver: shal,sim-i2c
+    address: sim0
+    children:
+      temp0:
+        id: ambient_temp
+        driver: ti,tmp102
+        address: 0x48
+```
+
+```python
+import shal
+
+with shal.load("sim.yaml") as hal:
+    print(hal.get_device("ambient_temp").read_celsius())   # 25.0
+```
+
+```bash
+$ python quickstart.py
+25.0
+```
+
+When the real board arrives, change `shal,sim-i2c` → `shal,i2c-cli`. **Your
+Python doesn't change.**
+
+---
+
+## Write a driver in 30 seconds
+
+Need a device SHAL doesn't have yet? A driver is one small class. This is the
+*entire* bundled temperature-sensor driver:
+
+```python
+from shal import Driver, TemperatureSensor, registry, idempotent, op, ByteTransport, Read, Write
+
+@registry.register
+class Tmp102(Driver, TemperatureSensor):
+    compatible = "ti,tmp102"          # matched against the YAML `driver:` field
+    kind = ByteTransport
+    llm_ready = True
+
+    @idempotent                        # a read: safe to auto-retry across drops
+    @op("Read the ambient temperature now.", unit="celsius", side_effect="none")
+    def read_celsius(self) -> float:
+        raw = self.bus.txn(self.addr, [Write(b"\x00"), Read(2)])
+        return ((raw[0] << 4) | (raw[1] >> 4)) * 0.0625
+```
+
+That's it — register the `compatible`, implement the capability. The `@op`
+metadata is what makes it show up as a gated agent tool. SHAL discovers your
+driver via the `shal.drivers` entry point.
+
+---
+
+## How It Works
+
+A topology is a tree, and **every edge is a bus** — itself a node that carries
+traffic to its children. You call a capability; SHAL translates it down the stack
+to the wire and hands the result back up. No layer leaks into the one above.
+
+```mermaid
+sequenceDiagram
+    participant U as Your code
+    participant T as tmp102 driver
+    participant I as i2c-cli bus
+    participant S as ssh-host bus
+    U->>T: read_celsius()
+    T->>I: read register 0x00
+    I->>S: i2ctransfer 0x48 … (argv)
+    Note over S: runs on lab_server
+    S-->>I: raw bytes
+    I-->>T: raw bytes
+    T-->>U: 22.5 °C
+```
+
+Because every hop is the same primitive, an SSH jumpbox, an I²C mux, and an
+in-process sim all compose — no special cases.
+
+---
+
+## Core Concepts
+
+| Concept | What it means |
+|---|---|
+| **Node** | Anything in the tree: a device, a bus, a board. |
+| **Bus** | A node that provides a transport to its children (I²C, SSH, HTTP…). |
+| **Driver** | Bound to a node by its `compatible` string. Implements a capability. |
+| **Capability** | The typed API your code calls (`read_celsius()`), independent of transport. |
+| **id vs path** | `id` is a stable name for lookup; `path` is where it sits. Move a device, keep its `id`. |
+
+```python
+hal.get_device("ambient_temp").read_celsius()   # by semantic id — no wires leak in
+```
+
+---
+
+## Real-World Use Cases
+
+- **AI agents with real-world access** — expose a lab or robot to an LLM as
+  gated tools; every actuator call stops for a human (or policy) to approve
+  before it fires, and a delivery-unknown write is never silently retried.
+- **Validation & test racks** — one model for eval boards, instruments, and the
+  results database; test against sims in CI before hardware.
+- **Manufacturing lines** — same capability calls across stations; one audit
+  trail (`shal.audit`) for every actuator command.
+- **Remote & distributed setups** — drive hardware behind an SSH jumpbox with
+  nothing on the far side but standard CLI tools.
+- **Robotics bringup** — start against a sim, swap in transports as boards land,
+  without rewriting control code.
+
+---
+
+## FAQ
+
+**Why not just wrap Python libraries as agent tools myself?**
+You can — until there are ten devices on four transports, some behind an SSH hop,
+some not. Then you're hand-maintaining a tool wrapper, address, retry policy, and
+audit log *per device*. SHAL generates all of it from one topology.
+
+**Is it production-ready?**
+It's **alpha** (Phase 1). The synchronous core — topology, drivers, buses, retry
+policy, and the agent tool surface — is real and tested. Async/streaming, the
+actuator watchdog, and route failover are Phase 2 ([roadmap](#roadmap)).
+
+**Do I need real hardware to try it?**
+No. The bundled simulated bus runs the [Quick Start](#quick-start) with zero
+hardware — swap in a real transport later, and your code doesn't change.
+
+---
+
+## Roadmap
+
+**Shipped — Phase 1 (synchronous core, v0.1.0):**
+
+- ✅ Declarative YAML topology: JSON-Schema validation, `id`/`path`/`$ref`,
+  `${ENV}` secrets, reusable `template:` includes
+- ✅ Bundled buses: `sim-i2c`, `local`, `ssh-host`, `i2c-cli`, `spi-cli`,
+  `tcp` (TLS), `http`, `nxp,pca9548` mux
+- ✅ Capability model, driver plugin registry, trustworthy retry policy
+- ✅ Agent tool surface: `tool_schemas()` / `tool_catalog()` / `call_tool()`
+- ✅ Human-in-the-loop actuation gate: actuator ops stop for an injectable
+  `Approver` (pre-I/O, unbypassable, every decision audited)
+- ✅ Structured observability + `capture()` flight recorder
+
+**Designed, in progress — Phase 2:**
+
+- 🚧 Async / streaming (`subscribe`, held channels) — [spec](docs/DESIGN%20-%20PHASE%202%20ASYNC.md)
+- 🚧 Actuator watchdog & safe-state (timeouts, auto safe-state on disconnect)
+- 🚧 Route failover for multi-path devices
+
+---
+
+## Documentation
+
+- [Architecture & locked decisions](docs/DESIGN%20V2.md)
+- [Phase 1 implementation decisions](docs/DECISIONS%20-%20V2.1.md)
+- [Phase 2 async + watchdog spec](docs/DESIGN%20-%20PHASE%202%20ASYNC.md)
+- Build guides: write a [driver](.claude/skills/shal-build-driver/SKILL.md),
+  a [bus](.claude/skills/shal-build-bus/SKILL.md), or a
+  [topology](.claude/skills/shal-build-yaml/SKILL.md)
+
+---
+
+## Contributing
+
+Contributions welcome — **new drivers and buses especially**. A driver is one
+small class (see [above](#write-a-driver-in-30-seconds)); SHAL discovers it via
+the `shal.drivers` entry point.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest          # test suite
+ruff check src tests      # lint
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## License
+
+[MIT](LICENSE).