atech 1.0.0a1__tar.gz

atech-1.0.0a1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Build / dist
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+.claude/
+*.swp
+
+# Secrets — never commit publishing tokens / credentials.
+# Prefer storing the PyPI token in $HOME (~/.pypirc) or a CI secret store,
+# outside the repo entirely. These are a belt-and-suspenders backstop.
+.env
+.env.*
+.pypirc
+*.token
+secrets.yaml
+secrets.yml
+
+# OS
+.DS_Store
+Thumbs.db

atech-1.0.0a1/CLAUDE.md

@@ -0,0 +1,194 @@
+# CLAUDE.md — writing firmware for an Atech board
+
+You are helping a user build firmware for an **Atech motherboard** — a
+small ESP32-S3 board with numbered ports that accept snap-in electrical
+modules. They have the hardware; you write the code.
+
+The `atech` Python SDK is the bridge. It picks pins, assembles drivers,
+generates a `main.cpp` and `platformio.ini`, compiles with PlatformIO, and
+flashes the board. **Your job is to write the behavior** — the user
+code block that's spliced into `loop()` (and `setup()` if needed) to make
+the modules do what the user asked.
+
+## The 60-second mental model
+
+A project is one YAML file:
+
+```yaml
+name: my_project
+board: 8port                          # 8port | 14port
+modules:
+  - {id: button,   instance: btn, port: 3}
+  - {id: neopixel, instance: led, port: 4}
+code:
+  setup: |
+    // optional — runs once
+  loop: |
+    // your behavior — runs forever
+    if (btn.wasPressed()) {
+      led.setAll(255, 0, 0);
+      led.show();
+    }
+```
+
+`atech build .` turns that into a working PlatformIO project with all the
+plumbing wired up. `atech upload .` flashes it.
+
+## Your workflow when the user asks for something
+
+1. **List the catalog first.** Always start here. Don't guess what modules exist:
+   ```bash
+   atech list-modules
+   atech list-modules --category sensor
+   atech list-boards
+   ```
+   If the user wants a temperature reading and no temperature module is in
+   the catalog, say so. **Do not invent modules.**
+
+2. **Read each chosen module's manifest** to know the public API:
+   ```bash
+   python -c "from atech import get_module; m = get_module('button'); print(m.usage)"
+   ```
+   Or read `src/atech/catalog/data/modules/<id>/module.yaml` directly. The
+   `usage:` field is a short C++ snippet showing every method you can
+   call from user code.
+
+3. **Pick ports.** On the 8-port board, valid ports are 1, 2, 3, 4, 5, 7
+   (6 and 8 are reserved for the reset button and USB-C). Adjacent pairs
+   for double-width modules: `[1,2]` and `[3,4]`. Check `get_board(...)`
+   for specifics.
+
+4. **Write the YAML** with `code.loop` (and `code.setup` if you need
+   one-time initialization beyond what each module's `templates.setup`
+   already does).
+
+5. **Validate before building:**
+   ```bash
+   atech validate .
+   ```
+   If it complains, fix the placement. Reserved ports, overlapping
+   modules, and non-adjacent double-width pairs all surface here.
+
+6. **Build:**
+   ```bash
+   atech build .
+   ```
+   On success it prints the path to `firmware.bin` and leaves a full
+   PlatformIO project under `./build/`.
+
+7. **Flash:**
+   ```bash
+   atech upload .
+   ```
+
+## Writing the `code:` block — the part you actually own
+
+Every module placed on the board becomes a C++ global variable at the
+name you gave as `instance`. The `usage:` field in each module manifest
+is your source of truth for what methods exist on that variable.
+
+```yaml
+modules:
+  - {id: button, instance: btn, port: 3}
+code:
+  loop: |
+    // `btn` is a `ButtonModule` global. See atech list-modules.
+    if (btn.wasPressed()) { /* edge */ }
+    if (btn.isPressed())  { /* level */ }
+```
+
+Things to remember:
+
+- **You're writing into a real Arduino `loop()`** — non-blocking only.
+  Use `millis()` for timing, never `delay()` longer than a few ms.
+- **`Serial` is wired to USB-CDC** so events you `Serial.println(...)`
+  show up in `atech monitor`. The wire format the runtime SDK
+  understands is one JSON object per line (see the auto-generated module
+  loop snippets for the exact shape).
+- **Don't hand-edit `main.cpp`.** Re-run `atech build`. The generator
+  splices your `code:` block in the right place and keeps the project
+  reproducible.
+- **Don't hardcode GPIO numbers.** They come from the port assignment.
+  If you need a pin number for something exotic, ask the user to use the
+  Python API and pull it from `BoardSpec.port(port_id).pins`.
+
+## Bringing your own module (rare but supported)
+
+If the user has a sensor or actuator no bundled module covers, drop a
+folder next to `project.yaml`:
+
+```
+my_project/
+├── project.yaml          # add `modules_path: ./my_modules` at the top
+└── my_modules/
+    └── <id>/
+        ├── module.yaml   # manifest (templates, usage, lib_deps)
+        ├── <id>.h        # driver header
+        └── <id>.cpp      # driver source
+```
+
+See [`examples/custom_module/`](examples/custom_module/) for a working
+example. The manifest schema is identical to the bundled modules —
+copy/paste one and edit.
+
+When you write the module's `usage:` block, **think about what the
+*next* agent will need to know to use this module**. Give the typical
+method calls with the `{{ instance }}` placeholder.
+
+## Things to NEVER do
+
+- ❌ Invent modules that aren't in `atech list-modules`.
+- ❌ Skip `atech validate` and go straight to `atech build`. Physics catches you.
+- ❌ Hand-edit `build/src/main.cpp`. It'll be overwritten on the next build.
+- ❌ Use `delay(1000)` in the loop. Use `millis()` deltas.
+- ❌ Hardcode pin numbers in the `code:` block. Use the instance API.
+- ❌ Reach into the runtime SDK (`atech.runtime.transport`) for raw
+  serial bytes. Use `Board.connect()` / `board.events()` / `board.send()`.
+- ❌ Depend on atech.dev or any Atech cloud feature. The SDK is fully
+  offline.
+
+## Quick reference
+
+```bash
+atech list-boards
+atech list-modules [--category X]
+atech new <name> --board <id>          # scaffolds project.yaml
+atech validate [project-dir]
+atech build    [project-dir]
+atech upload   [project-dir] [--port X]
+atech monitor                          # stream events after flashing
+atech ports                            # see candidate USB devices
+atech send <key> <value>               # send one action to the board
+```
+
+```python
+from atech import Project, list_modules, get_module, Board
+
+# Inspect what's available
+list_modules(category="input")
+get_module("button").usage              # the C++ snippet
+
+# Assemble
+p = (
+    Project(board="8port", name="thing")
+        .add("button", port=3, instance="btn")
+        .add("neopixel", port=4, instance="led")
+        .set_loop("""
+            if (btn.wasPressed()) { led.setAll(0, 0, 255); led.show(); }
+        """)
+)
+print(p.describe())     # human/agent-readable summary of instances + their APIs
+p.build()
+p.upload()
+
+# After flashing — talk to the board
+with Board.connect() as board:
+    for ev in board.events():
+        print(ev.key, ev.value)
+```
+
+## When in doubt
+
+`atech list-modules` is the source of truth for what's buildable today.
+If the user wants something that isn't in there, your job is to *say so
+clearly* and offer to build a custom module — not to fabricate one.

atech-1.0.0a1/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,180 @@
+# Atech Python SDK — Implementation Plan
+
+Sequenced plan to ship `atech` v1.0 — the comprehensive open SDK described in [PRD.md](PRD.md).
+
+## Layout
+
+```
+python-sdk/
+├── pyproject.toml
+├── README.md
+├── PRD.md
+├── IMPLEMENTATION_PLAN.md
+├── LICENSE                              # MIT
+├── CLAUDE.md                            # how Claude Code uses the SDK
+├── examples/
+│   └── thermometer/                     # one end-to-end demo project
+│       ├── project.yaml
+│       └── README.md
+├── src/atech/
+│   ├── __init__.py                      # top-level re-exports
+│   ├── _version.py
+│   ├── errors.py                        # SDK-wide exception types
+│   ├── catalog/                         # bundled data + loader
+│   │   ├── __init__.py
+│   │   ├── loader.py                    # load_boards / load_modules from package data
+│   │   ├── models.py                    # BoardSpec, ModuleSpec, PortSpec, …
+│   │   └── data/
+│   │       ├── boards/
+│   │       │   ├── 8port.yaml
+│   │       │   └── 14port.yaml
+│   │       └── modules/
+│   │           ├── button/
+│   │           │   ├── module.yaml
+│   │           │   ├── button.h
+│   │           │   └── button.cpp
+│   │           ├── neopixel/
+│   │           │   ├── module.yaml
+│   │           │   └── …
+│   │           └── aht20/
+│   │               ├── module.yaml
+│   │               └── …
+│   ├── placement.py                     # validator + structured issues
+│   ├── project.py                       # Project class (assembly + YAML)
+│   ├── codegen.py                       # template stitching → PlatformIO project
+│   ├── build.py                         # `pio run` wrapper
+│   ├── upload.py                        # `pio run -t upload` wrapper
+│   ├── runtime/                         # v0.1 serial SDK, preserved
+│   │   ├── __init__.py
+│   │   ├── board.py
+│   │   ├── transport.py
+│   │   └── models.py
+│   └── cli.py
+└── tests/
+    ├── test_catalog.py
+    ├── test_placement.py
+    ├── test_project.py
+    ├── test_codegen.py
+    ├── test_runtime_models.py
+    ├── test_runtime_transport.py
+    └── test_runtime_board.py
+```
+
+## Phases
+
+### Phase 0 — Repackage (no behavior change)
+- Move `src/atech/{board,transport,models}.py` → `src/atech/runtime/`.
+- Top-level `atech/__init__.py` re-exports the runtime symbols at the old paths for one minor version (`atech.Board`, `atech.Event`, etc.) so the v0.1 API stays callable while internals reorganize.
+- Move corresponding tests under `tests/` to `test_runtime_*.py`.
+
+### Phase 1 — Catalog
+- `catalog/models.py`: Pydantic models for `BoardSpec`, `PortSpec`, `AdjacentPair`, `ModuleSpec`, `ModuleTemplates`, `EventDecl`, `ActionDecl`. Mirrors the existing `motherboard/board.yaml` and the new per-module YAML.
+- `catalog/loader.py`: `load_boards()` and `load_modules()` read from package data via `importlib.resources`. Cache results.
+- `catalog/data/boards/8port.yaml`: copied from `backend/motherboard/board.yaml`, trimmed to just the 8-port entry. Reformatted so the SDK loader matches the schema.
+- `catalog/data/modules/<id>/module.yaml`: new schema (see §"Module manifest schema" below). Seed with three modules whose drivers already exist in the backend:
+    - `button` — single GPIO input, size=1
+    - `neopixel` — single GPIO output, size=1
+    - `aht20` — I²C sensor, size=1
+- Each module bundles its `.h` / `.cpp` files copied directly from `backend/src/lib/athera_modules/esp32/modules/`.
+
+### Phase 2 — Placement validator
+- `placement.py`: pure function `validate(board: BoardSpec, placements: list[Placement]) -> list[PlacementIssue]`.
+- Issue types: `ReservedPort`, `UnknownPort`, `Overlap`, `NotAdjacent` (double-width module), `MissingSecondaryPort`, `IncompatibleInterface`.
+- Ported from the backend's `placement_optimizer.py` but pared back to validation only — the open SDK does *not* auto-correct or solve, it reports.
+
+### Phase 3 — Project
+- `project.py`: dataclass-style `Project` with `add` / `remove` / `validate` / `generate` / `build` / `upload` / `to_yaml` / `from_yaml`.
+- Project state on disk is a single `project.yaml`:
+    ```yaml
+    name: weather
+    board: 8port
+    modules:
+      - id: aht20
+        instance: aht20_1
+        port: 1
+      - id: neopixel
+        instance: status_led
+        port: 3
+    ```
+- `Project.add` accepts either an int (single port) or a tuple (double-width); raises if the placement fails validation.
+
+### Phase 4 — Codegen
+- `codegen.py`: takes a validated `Project`, returns the in-memory representation of the PlatformIO tree, and can write it to disk.
+- Per-module Jinja2 templates from the manifest produce three fragments: `globals`, `setup`, `loop`. The codegen splices them into a single `main.cpp` skeleton. No LLM, no regex post-processing — keep it dumb on purpose.
+- `platformio.ini` emitted from `BoardSpec.platformio_env` + accumulated `lib_deps` from every selected module.
+- Drivers (`.h` / `.cpp`) are copied per-instance into `lib/atech_<module>/` so PlatformIO's library finder picks them up.
+- Pin assignments come from `BoardSpec.ports[port_id].pins` and are exposed to templates as `{{ pin_a }}`, `{{ pin_b }}`, `{{ instance_name }}`.
+
+### Phase 5 — Build / upload
+- `build.py`: `run_build(project_dir) -> BuildResult` shells out to `pio run` (using the bundled PlatformIO from the venv). Captures stdout/stderr; surfaces the path to `firmware.bin` on success.
+- `upload.py`: `run_upload(project_dir, port=None) -> UploadResult` shells out to `pio run -t upload --upload-port <port>`. If `port` is None, calls `runtime.discover_ports()` and picks the first match.
+- Both stream PlatformIO output to the user's terminal in CLI mode; return logs as strings in library mode.
+
+### Phase 6 — CLI
+Subcommands:
+- `atech ports` *(preserved)*
+- `atech monitor` *(preserved)*
+- `atech send` *(preserved)*
+- `atech list-boards`
+- `atech list-modules [--category X]`
+- `atech new <name> --board <id>`
+- `atech validate <project-dir>`
+- `atech build <project-dir>`
+- `atech upload <project-dir> [--port X]`
+
+### Phase 7 — Tests
+- All catalog / placement / project / codegen tests use the bundled data + `tmp_path` + string comparisons. No PlatformIO or hardware required.
+- Build/upload tests are gated on `ATECH_INTEGRATION=1` and a connected board.
+- Runtime tests stay against `MockTransport`.
+
+### Phase 8 — Docs
+- README: install, quick-start, the Claude Code story, links to PRD.
+- CLAUDE.md: a short, deliberate cheatsheet for Claude Code in a user's repo — "to build a hardware project, do this".
+- `examples/thermometer/`: a 30-second demo that gets a user from clone → flashed firmware.
+
+## Module manifest schema (Phase 1 deliverable)
+
+```yaml
+id: aht20
+name: "Temperature & Humidity Sensor (AHT20)"
+category: sensor          # sensor | input | display | actuator | led | connectivity | audio
+size: 1                   # 1 or 2 ports
+interface: i2c            # i2c | gpio | analog | uart
+i2c_address: 0x38         # only when interface=i2c
+driver:
+  header: aht20.h
+  source: aht20.cpp
+  class_name: AHT20
+templates:
+  globals: |
+    AHT20 {{ instance }};
+  setup: |
+    {{ instance }}.begin({{ pin_a }}, {{ pin_b }});
+  loop: |
+    if (millis() - {{ instance }}_last >= 1000) {
+      {{ instance }}_last = millis();
+      float t = {{ instance }}.readTemperature();
+      Serial.printf("{\"type\":\"event\",\"payload\":{\"event_type\":\"sensor\",\"key\":\"temperature\",\"value\":%.2f,\"source\":\"aht20\"}}\n", t);
+    }
+  globals_extra: |
+    unsigned long {{ instance }}_last = 0;
+events:
+  - key: temperature
+    type: sensor
+    value_type: float
+    unit: "°C"
+    description: "Ambient temperature in Celsius"
+actions: []
+lib_deps: []              # PlatformIO dep strings; empty when bundled driver is self-contained
+```
+
+## Out for v1
+- Module-authoring framework (custom modules outside the bundled catalog).
+- AI module selection.
+- Async runtime API.
+- WiFi / BLE transports.
+- MCP server (P2 in the PRD; can ship in 1.1).
+
+## Hard dependencies
+- **PlatformIO** is a runtime dep declared in `pyproject.toml` so `pip install atech` brings it in. Users still need USB-UART drivers on Windows for boards that don't use native ESP32-S3 USB.
+- **Backend firmware modules** (`backend/src/lib/athera_modules/`) are the source of the bundled drivers. M1 copies a subset; M4 should track the backend catalog 1:1.

atech-1.0.0a1/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: atech
+Version: 1.0.0a1
+Summary: Open-source Python SDK for Atech motherboards: catalog, codegen, build, flash, and runtime control.
+Project-URL: Homepage, https://atech.dev
+Project-URL: Repository, https://github.com/atechdotdev/python-sdk
+Project-URL: Documentation, https://github.com/atechdotdev/python-sdk#readme
+Author: Atech
+License: MIT
+Keywords: atech,claude-code,esp32,firmware,hardware,iot,platformio,serial
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: platformio>=6.1
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# atech
+
+**The open-source way to write firmware for [Atech](https://atech.dev)
+boards — designed for humans + coding agents working together.**
+
+You have an Atech motherboard and you want it to do something. With this
+SDK installed, you can ask Claude Code (or any coding agent that can run
+Python) — *"make my board light up red when the button is pressed"* — and
+the agent has everything it needs: a catalog of available modules, the
+public API of each driver, deterministic codegen, a real compiler, and
+an upload command. No cloud account, no AI prompts in the SDK, no
+proprietary glue.
+
+## Install
+
+```bash
+pip install atech
+# or
+uv add atech
+```
+
+PlatformIO is pulled in as a dep, so a single install builds and flashes.
+
+## What it gives a coding agent
+
+A coding agent working in a user's repo gets four things:
+
+1. **A discoverable catalog** of bundled modules with rich metadata.
+   ```bash
+   atech list-modules
+   atech list-modules --category sensor
+   python -c "from atech import get_module; print(get_module('button').usage)"
+   ```
+   Each module's `usage:` field is a short C++ snippet showing the public
+   API — no need for the agent to grep through driver headers.
+
+2. **A small declarative project format** (`project.yaml`) that the agent
+   writes or edits directly:
+   ```yaml
+   name: my_thing
+   board: 8port
+   modules:
+     - {id: button,   instance: btn, port: 3}
+     - {id: neopixel, instance: led, port: 4}
+   code:
+     loop: |
+       if (btn.wasPressed()) { led.setAll(255, 0, 0); led.show(); }
+   ```
+
+3. **Mechanical, deterministic codegen.** `atech build` turns the YAML
+   into a vanilla PlatformIO project, compiles it, and produces a
+   `firmware.bin`. No LLM in this path — the agent owns the behavior,
+   the SDK owns the plumbing.
+
+4. **An upload + monitor flow** that doesn't require the user to know
+   PlatformIO internals: `atech upload` / `atech monitor`.
+
+## 60-second example
+
+```bash
+atech new thermo --board 8port
+cd thermo
+# Tell Claude (or write yourself):
+#   "edit project.yaml to add a button on port 3 and a neopixel on port 4,
+#    and in code.loop, cycle the neopixel through six colours on each press"
+atech validate .
+atech build .
+atech upload .
+```
+
+Or, fully programmatic:
+
+```python
+from atech import Project
+
+(
+    Project(board="8port", name="thermo")
+        .add("button",   port=3, instance="btn")
+        .add("neopixel", port=4, instance="led")
+        .set_loop("""
+            if (btn.wasPressed()) {
+                static uint8_t hue = 0;
+                hue += 60;
+                led.setAll(hue, 0, 255 - hue);
+                led.show();
+            }
+        """)
+        .build()
+        .upload()
+)
+```
+
+## Bringing your own module
+
+If the bundled catalog doesn't cover what the user has, drop a folder
+next to `project.yaml`:
+
+```
+my_project/
+├── project.yaml          # add `modules_path: ./my_modules`
+└── my_modules/
+    └── lidar_v2/
+        ├── module.yaml   # id, templates, usage, lib_deps
+        ├── lidar_v2.h
+        └── lidar_v2.cpp
+```
+
+Same shape as the SDK's
+[`src/atech/catalog/data/modules/`](src/atech/catalog/data/modules/) tree.
+The SDK merges your modules with the bundled catalog at build time; you
+never have to fork. See [`examples/custom_module/`](examples/custom_module/)
+for a working example.
+
+## Examples
+
+- [`examples/blink_button/`](examples/blink_button/) — minimal user
+  behavior hook: a button cycles an LED grid through colours.
+- [`examples/speaker_music/`](examples/speaker_music/) — write your own
+  music: note-by-note melodies, RTTTL ringtone strings, and chords on the
+  `speaker` module.
+- [`examples/custom_module/`](examples/custom_module/) — a user-authored
+  module (`heartbeat`) placed in a sibling folder, then used by the project.
+
+All build end-to-end with `atech build .`.
+
+## The full Python API
+
+```python
+import atech
+
+# Discovery — what the agent should call first
+atech.list_boards()
+atech.list_modules(category="sensor")
+atech.get_board("8port")
+atech.get_module("button").usage     # C++ snippet showing the public API
+
+# Project assembly
+p = atech.Project(board="8port", name="weather")
+p.add("button", port=3, instance="btn")
+p.add("dc_motor", ports=(1, 2))            # double-width = adjacent pair
+p.set_setup("Serial.println(\"booting\");")
+p.set_loop("if (btn.wasPressed()) { Serial.println(\"hi\"); }")
+p.use_modules_from("./my_modules")          # custom catalog directory
+p.validate()                                # -> list[PlacementIssue]
+p.describe()                                # human/agent summary + per-module usage
+p.generate(out_dir="./build")               # -> Path to PlatformIO tree
+p.build()                                   # -> BuildResult
+p.upload(port="/dev/ttyACM0")               # -> UploadResult
+p.to_yaml(); atech.Project.from_yaml(text); atech.Project.load(path)
+
+# Runtime — after flashing
+with atech.Board.connect() as board:
+    for ev in board.events():
+        print(ev.key, ev.value)
+    board.send("led", {"r": 255, "g": 0, "b": 0})
+```
+
+## CLI
+
+```text
+atech list-boards
+atech list-modules [--category X]
+atech new <name> --board <id>          # scaffolds project.yaml + README
+atech validate [project-dir]
+atech build    [project-dir]
+atech upload   [project-dir] [--port X]
+
+atech ports                            # candidate USB devices
+atech monitor  [--port X] [--type T,T] [--key K,K] [--json]
+atech send <key> <value> [--port X]
+```
+
+## How a coding agent should drive it
+
+[`CLAUDE.md`](CLAUDE.md) — drop a copy into your project root and your
+coding agent will follow it. It covers: how to discover modules, how to
+write the `code:` block, what *not* to do (invent modules, skip
+validation, hand-edit generated files, use `delay()` in the loop).
+
+## Architecture (short version)
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ atech.Project          ← agent assembles a hardware spec           │
+├────────────────────────────────────────────────────────────────────┤
+│ atech.placement        ← validates adjacency / reserved / overlap  │
+│ atech.catalog          ← bundled + user-authored modules           │
+│ atech.codegen          ← deterministic template stitching          │
+│ atech.build / upload   ← `pio run` wrappers                        │
+├────────────────────────────────────────────────────────────────────┤
+│ atech.runtime.Board    ← serial client for the flashed board       │
+└────────────────────────────────────────────────────────────────────┘
+            │                                       │
+       PlatformIO                              pyserial
+            │                                       │
+        ESP32 flash                          ESP32 USB-CDC
+```
+
+The closed Atech hosted product imports this SDK and layers AI module
+selection, OTA, sharing, and signing on top. The open SDK is everything
+needed to build firmware locally; nothing in this package phones home.
+
+## Status
+
+`v1.0.0a1` — alpha. Two boards (`8port`, `14port`) and nine bundled
+modules: `button`, `rotary_encoder`, `pir` (motion), `aht20`
+(temp/humidity), `neopixel`, `st7735_tft` (colour display), `speaker`
+(I2S audio), `dc_motor`, and `stepper_motor`. More ship through the
+catalog as they're ported in — run `atech list-modules` for the live list.
+The runtime serial API is stable and preserves the v0.1.x surface under
+`atech.runtime`.
+
+See [`PRD.md`](PRD.md) and [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md)
+for the longer story.
+
+## License
+
+MIT.