Promote dev2 to main for the first public release (v0.1.0).

.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dir:*)",
+      "Bash(findstr:*)",
+      "Bash(make:*)",
+      "Bash(uv sync:*)",
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ]
+  }
+}

CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0 - 2026-02-26
+
+### Added
+
+- v0.1 documentation structure with capability-oriented API reference pages:
+  - Client API
+  - Service API
+  - Server API
+  - Files API
+  - Addressing API
+  - Validation API
+  - Advanced API
+- New usage guides:
+  - `guides/types.md` for native Python value contracts
+  - `guides/addressing.md` for canonical normalized addressing and XD/YD details
+- API reference coverage guard in `docs/gen_reference.py` to ensure all exported symbols in `pyclickplc.__all__` are documented exactly once.
+
+### Changed
+
+- README restructured for v0.1 launch:
+  - clearer async (`ClickClient`) vs sync (`ModbusService`) entry points
+  - native Python type contract table
+  - explicit error model (`ValueError` validation vs `OSError` transport)
+  - `XD0u` / `YD0u` moved out of quickstart to addressing guidance
+  - stability policy documented as "stable core, evolving edges"
+- MkDocs navigation updated to capability-oriented API pages and new core guides.
+
+### Notes
+
+- Stable core APIs are documented in primary navigation.
+- Lower-level Modbus mapping and bank metadata APIs are documented under Advanced API and may evolve more quickly.

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`pyclickplc` is a shared utility library for AutomationDirect CLICK PLCs. It provides PLC bank definitions, address parsing, nickname CSV and DataView CDV file I/O, BlockTag parsing, Modbus protocol mapping, and async Modbus TCP client/server. Consumed by ClickNick (GUI editor), pyrung (simulation), and standalone tooling.
+
+## Commands
+
+- **Install**: `uv sync --all-extras --dev`
+- **Run all (install + lint + test)**: `make` or `make default`
+- **Test**: `make test` (runs `uv run pytest`)
+- **Single test**: `uv run pytest tests/test_addresses.py::TestParseAddress::test_xd_basic -v`
+- **Lint**: `make lint` (runs `uv run devtools/lint.py` — codespell, ruff check --fix, ruff format, ty check)
+- **Build**: `make build` (runs `uv build`)
+
+## Architecture
+
+### Two-Layer Design
+
+PLC knowledge and Modbus protocol are separated into two layers linked by bank name:
+
+1. **`banks.py`** (foundation, zero deps) — `BankConfig`, `BANKS` dict, `DataType` enum, sparse `valid_ranges` for X/Y hardware slots, address validation
+2. **`modbus.py`** (depends on banks) — `ModbusMapping`, `MODBUS_MAPPINGS` dict, forward/reverse address mapping, register pack/unpack
+
+### Address System
+
+All address parsing flows through `parse_address()` in `addresses.py`, which returns `(memory_type, mdb_address)` — MDB-style indices for all banks. XD/YD use contiguous MDB indices 0-16; display addresses 0-8 map via `xd_yd_display_to_mdb()`. The `format_address_display()` function handles the reverse. These two functions are the canonical formatting/parsing entry points used by client, server, nicknames, and dataview modules.
+
+### Dependency Graph
+
+```
+banks.py                          ← no deps (foundation)
+    ↑
+    ├── validation.py
+    ├── addresses.py
+    │       ↑
+    │       ├── blocks.py
+    │       ├── dataview.py
+    │       ├── modbus.py
+    │       │       ↑
+    │       │       ├── client.py ──→ nicknames.py
+    │       │       └── server.py
+    │       └── nicknames.py ──→ blocks.py, validation.py
+```
+
+### Key Modules
+
+- **`client.py`** — `ClickClient` (async Modbus TCP client using pymodbus) with `AddressAccessor`, `AddressInterface`, `TagInterface`
+- **`server.py`** — `ClickServer` (async Modbus TCP server) with `DataProvider` protocol and `MemoryDataProvider`
+- **`nicknames.py`** — Read/write CLICK nickname CSV files
+- **`dataview.py`** — Read/write DataView CDV files (UTF-16 LE CSV format)
+- **`blocks.py`** — BlockTag parsing and computation
+
+### Modbus Mapping
+
+`plc_to_modbus(bank, index)` uses `base + index` for 0-based banks (XD/YD) and `base + width * (index - 1)` for 1-based banks. X/Y are sparse coil banks with slot-based offset formulas. `modbus_to_plc()` reverses the mapping.
+
+## Conventions
+
+- `DataType` enum is the single source of truth for PLC types; Modbus properties derive from it
+- All dataclasses use `frozen=True`
+- Tests in `tests/` mirror source modules (e.g., `test_addresses.py` tests `addresses.py`)
+- pytest discovers tests from both `src/` and `tests/` directories (`python_files = ["*.py"]`)
+- `asyncio_mode = "auto"` — async tests need no decorator
+- Package uses src-layout: source is in `src/pyclickplc/`
+- Python 3.11+ required; CI tests 3.11-3.14
+- Ruff line-length is 100

Makefile

@@ -4,7 +4,7 @@
 
 .DEFAULT_GOAL := default
 
-.PHONY: default install lint test upgrade build clean docs docs-check
+.PHONY: default install lint test upgrade build clean docs-serve docs-build docs-check
 
 default: install lint test
 
@@ -23,6 +23,14 @@ upgrade:
 build:
 	uv build
 
+docs-serve:
+	uv run --group docs mkdocs serve
+
+docs-build:
+	uv run --group docs mkdocs build --strict
+
+docs-check: docs-build
+
 # Improved Windows detection
 ifeq ($(OS),Windows_NT)
     WINDOWS := 1

README.md

@@ -1,12 +1,133 @@
-# Pyrung
+# pyclickplc
 
-Utilities to work with AutomationDirect CLICK Plcs
+Utilities for AutomationDirect CLICK PLCs: Modbus TCP client/server, address helpers, nickname CSV I/O, and DataView CDV I/O.
 
-## Status
+Documentation: https://ssweber.github.io/pyclickplc/
+LLM docs index: https://ssweber.github.io/pyclickplc/llms.txt
+LLM full context: https://ssweber.github.io/pyclickplc/llms-full.txt
 
-PLANNING ONLY * INITIAL COMMIT
+## Installation
 
-## Goals
+```bash
+uv add pyclickplc
+# or
+pip install pyclickplc
+```
 
-- Provide shared utility library for reading/writing Nickname csv files, 
-Dataview .cdv file, communicating via Modbus, and parsing the BlockTag comment specification
+Requires Python 3.11+. Modbus client/server functionality depends on [pymodbus](https://github.com/pymodbus-dev/pymodbus).
+
+## Choose Your Interface
+
+- `ClickClient`: async API for direct `asyncio` applications.
+- `ModbusService`: sync + polling API for UI/event-driven applications that do not want to manage an async loop.
+
+## Native Python Type Contract
+
+All read/write APIs operate on native Python values.
+
+| Bank family | Python type | Examples |
+| --- | --- | --- |
+| `X`, `Y`, `C`, `T`, `CT`, `SC` | `bool` | `True`, `False` |
+| `DS`, `DD`, `DH`, `TD`, `CTD`, `SD`, `XD`, `YD` | `int` | `42`, `0x1234` |
+| `DF` | `float` | `3.14` |
+| `TXT` | `str` | `"A"` |
+
+`read()` methods return `ModbusResponse`, keyed by canonical normalized addresses (`"DS1"`, `"X001"`):
+
+- lookups are normalized (`resp["ds1"]` resolves `"DS1"`)
+- single index reads like `await plc.ds[1]` return a bare native Python value
+
+## Quickstart (`ClickClient`, async)
+
+```python
+import asyncio
+from pyclickplc import ClickClient, read_csv
+
+tags = read_csv("nicknames.csv")
+
+async def main():
+    async with ClickClient("192.168.1.10", 502, tags=tags) as plc:
+        # Bank accessors
+        await plc.ds.write(1, 100)
+        ds1 = await plc.ds[1]
+        df_values = await plc.df.read(1, 3)
+        await plc.y.write(1, True)
+
+        # String address interface
+        await plc.addr.write("df1", 3.14)
+        df1 = await plc.addr.read("DF1")
+
+        # Tag interface (case-insensitive)
+        await plc.tag.write("mytag", 42.0)
+        tag_value = await plc.tag.read("MyTag")
+
+        print(ds1, df_values, df1, tag_value)
+
+asyncio.run(main())
+```
+
+## `ModbusService` (sync + polling)
+
+```python
+from pyclickplc import ModbusService, ReconnectConfig
+
+def on_values(values):
+    print(values)  # ModbusResponse keyed by canonical normalized addresses
+
+svc = ModbusService(
+    poll_interval_s=0.5,
+    reconnect=ReconnectConfig(delay_s=0.5, max_delay_s=5.0),
+    on_values=on_values,
+)
+svc.connect("192.168.1.10", 502, device_id=1, timeout=1)
+
+svc.set_poll_addresses(["DS1", "DF1", "Y1"])
+print(svc.read(["DS1", "DF1"]))
+print(svc.write({"DS1": 100, "Y1": True, "X1": True}))  # X1 is not writable
+
+svc.disconnect()
+```
+
+## Error Model
+
+- Validation and address parsing failures raise `ValueError`.
+- Transport/protocol failures raise `OSError` for reads.
+- `ModbusService.write()` returns per-address outcomes (`ok` + `error`) instead of raising per-item validation failures.
+
+## Addressing Nuances
+
+- Address strings are canonical normalized (`x1` -> `X001`, `ds1` -> `DS1`).
+- `X`/`Y` are sparse address families; not every numeric value is valid.
+- `XD`/`YD` accessors are display-indexed (`0..8`) by default.
+- `XD0u`/`YD0u` are explicit upper-byte aliases for advanced use cases.
+
+See the addressing guide for details:
+- https://ssweber.github.io/pyclickplc/guides/addressing/
+
+## Other Features
+
+- Modbus simulator: `ClickServer`, `MemoryDataProvider`, `run_server_tui`
+- CLICK nickname CSV I/O: `read_csv`, `write_csv`, `AddressRecordMap`
+- CLICK DataView CDV I/O: `read_cdv`, `write_cdv`, `verify_cdv`, `check_cdv_file`
+
+Server docs:
+- Guide: https://ssweber.github.io/pyclickplc/guides/server/
+- API: https://ssweber.github.io/pyclickplc/reference/api/server/
+
+## v0.1 API Stability
+
+`pyclickplc` v0.1 follows a “stable core, evolving edges” policy.
+
+- Stable core: client/service/server/file I/O/address/validation APIs surfaced in the docs site primary navigation.
+- Advanced/evolving: low-level Modbus mapping helpers and bank metadata (`ModbusMapping`, `plc_to_modbus`, `BANKS`, etc.).
+
+## Development
+
+```bash
+uv sync --all-extras --dev    # Install dependencies
+make test                     # Run tests (uv run pytest)
+make lint                     # Lint (codespell, ruff, ty)
+make docs-build               # Build docs (mkdocs + mkdocstrings)
+make docs-serve               # Serve docs locally
+make                          # All of the above
+```