docs: formalize ASP v2.0 spec and node onboarding standards

MASTER_SETUP_GUIDE.md

@@ -0,0 +1,65 @@
+# APEX Master Setup Guide (L1/L2/L3 Onboarding)
+
+## 1) Prerequisites
+- Git with submodule support
+- Node.js + npm (Core/RAM)
+- Bun (Core/CLI)
+- Python 3.10+ (CLI tests/tooling)
+- PlatformIO (firmware builds where applicable)
+
+## 2) Clone and Initialize
+```bash
+git clone <repo-url> APEX
+cd APEX
+git submodule update --init --recursive
+```
+
+## 3) Bring Up Core Layers
+
+### Core/RAM
+```bash
+cd Core/RAM
+npm install
+npm run dev
+```
+
+### Core/CLI
+```bash
+cd Core/CLI
+bun run dev
+```
+
+## 4) Node-Level Onboarding
+
+### L1 MicroMax
+1. Connect node over USB serial.
+2. Configure firmware for supported board (Uno/Pico/ESP32 wired mode).
+3. Validate ASP line framing with:
+   - `{"query":"WHO_ARE_YOU"}`
+   - `{"action":"WRITE","target":"D13","value":1}`
+
+### L2 MiniMax
+1. Provision WiFi credentials and MQTT broker endpoint.
+2. Ensure bridge mirrors ASP payloads without mutating command/event semantics.
+3. Validate heartbeat + reconnection under temporary network loss.
+
+### L3 MegaMax
+1. Provision SIM/modem and APN settings.
+2. Validate LTE data path first, then SMS fallback path.
+3. Confirm periodic telemetry (including GPS if enabled) with ASP-compliant JSON.
+
+## 5) ASP v2.0 Conformance Checks
+- Use `./SPEC_ASP_V2.md` as canonical reference.
+- Ensure nodes accept legacy minimal payloads and v2 envelope payloads.
+- Ensure parsers validate expected keys/types and reject malformed frames safely.
+
+## 6) Fail-Safe Expectations
+- Heartbeat loss should trigger deterministic safe behavior on actuator-capable nodes.
+- Recovery should send explicit `event`, `ack`, or `error` frames where possible.
+
+## 7) Documentation Map
+- Protocol spec: `./SPEC_ASP_V2.md`
+- Research log: `./RESEARCH.md`
+- L1 docs: `./docs/MicroMax/DOCS.md`
+- L2 docs: `./docs/MiniMax/DOCS.md`
+- L3 docs: `./docs/MegaMax/DOCS.md`

README.md

@@ -68,6 +68,9 @@ cargo run
 ## Documentation
 
 - Architecture overview: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+- ASP v2.0 specification: [`SPEC_ASP_V2.md`](./SPEC_ASP_V2.md)
+- Master setup guide: [`MASTER_SETUP_GUIDE.md`](./MASTER_SETUP_GUIDE.md)
+- Node docs: [`docs/MicroMax/DOCS.md`](./docs/MicroMax/DOCS.md), [`docs/MiniMax/DOCS.md`](./docs/MiniMax/DOCS.md), [`docs/MegaMax/DOCS.md`](./docs/MegaMax/DOCS.md)
 - Agent capability notes: [`AGENT.md`](./AGENT.md)
 - Workflow and planning system: [`conductor/index.md`](./conductor/index.md)
 - Conductor module guide: [`conductor/README.md`](./conductor/README.md)
@@ -78,4 +81,3 @@ cargo run
 - **[Contributing](./CONTRIBUTING.md)**
 - **[Code of Conduct](./CODE_OF_CONDUCT.md)**
 - **[Security Policy](./SECURITY.md)**
-

RESEARCH.md

@@ -0,0 +1,45 @@
+# RESEARCH: ASP v2.0 + Node Documentation Audit
+
+## Scope
+- Module: root `APEX` repository (Protocol Architect task)
+- Goal: produce canonical protocol and setup documentation for L1/L2/L3 nodes
+
+## Repository Audit Findings
+1. The primary in-repo ASP references are in:
+   - `./ARCHITECTURE.md`
+   - `./AI_PROMPTS.md`
+   - `./MicroMax/README.md`
+2. Current documented baseline for ASP:
+   - JSON messages
+   - newline-terminated framing on serial links
+   - 115200 baud (8-N-1) for MicroMax serial transport
+   - canonical example fields in active use:
+     - Command path: `action`, `target`, `value`
+     - Event path: `event`, `source`, `type`
+     - Heartbeat/query path: `query` (example `WHO_ARE_YOU`)
+3. L1/L2/L3 submodules currently expose high-level module READMEs and capabilities, but no root-level unified formal spec file yet.
+
+## Industry Pattern Research (Applied Principles)
+Because external docs were not reachable from this sandbox at runtime, this phase applies stable, widely adopted IoT protocol patterns used across systems such as device shadows and MQTT-first home automation stacks:
+- Keep a backward-compatible minimal payload path.
+- Add optional metadata envelope fields for extensibility (`v`, `id`, timestamps, node identity).
+- Separate message intent (`command`, `query`, `event`, `telemetry`, `ack`, `error`) to simplify routing.
+- Standardize correlation (`id`/`ref`) for request/ack tracing.
+- Define transport-agnostic payload semantics so Serial, MQTT, WebSocket, and cellular links can mirror the same JSON contract.
+
+## Design Decisions for Documentation Output
+1. Define **ASP v2.0** as an additive superset: existing simple messages remain valid.
+2. Provide one canonical spec file (`SPEC_ASP_V2.md`) with:
+   - wire framing
+   - required vs optional keys
+   - validation and security rules
+   - examples for command/event/heartbeat/ack/error/telemetry
+3. Provide per-level docs (`DOCS.md`) for:
+   - MicroMax (L1 wired)
+   - MiniMax (L2 wireless MQTT bridge)
+   - MegaMax (L3 cellular bridge)
+4. Provide one onboarding runbook (`MASTER_SETUP_GUIDE.md`) covering:
+   - hardware bring-up
+   - transport mapping
+   - protocol conformance checks
+   - fail-safe expectations

SPEC_ASP_V2.md

@@ -0,0 +1,123 @@
+# Apex Serial Protocol (ASP) v2.0 Specification
+
+## 1) Purpose
+ASP v2.0 defines a transport-agnostic JSON message contract for APEX nodes.
+
+- L1 (MicroMax): USB Serial
+- L2 (MiniMax): WiFi/MQTT bridge
+- L3 (MegaMax): Cellular data + SMS fallback bridge
+
+ASP v2.0 is **backward-compatible** with existing minimal JSON messages already documented in APEX.
+
+## 2) Transport and Framing
+
+### 2.1 Serial (L1 baseline)
+- Encoding: UTF-8 JSON
+- Framing: one JSON object per line (`\n` terminated)
+- Default line speed: `115200 8-N-1`
+
+### 2.2 Networked transports (L2/L3)
+- Payload schema stays identical to serial JSON.
+- Framing is delegated to transport (MQTT/WebSocket/TCP message boundaries).
+
+## 3) Message Model
+
+### 3.1 Minimal backward-compatible forms (valid)
+```json
+{"action":"WRITE","target":"D13","value":1}
+{"event":"TRIGGER","source":"D2","type":"Interrupt"}
+{"query":"WHO_ARE_YOU"}
+```
+
+### 3.2 Preferred v2 envelope (recommended)
+```json
+{
+  "v": "2.0",
+  "id": "a7c6f5f0-1b6f-4a3f-bbe8-7f8c20f1b4ef",
+  "ts": "2026-04-16T00:00:00Z",
+  "node": {"level":"L1","id":"micromax-uno-01"},
+  "kind": "command"
+}
+```
+
+## 4) Field Definitions
+
+### 4.1 Core optional envelope fields
+- `v` (string): protocol version, recommended `"2.0"`.
+- `id` (string): message correlation id.
+- `ts` (string): ISO-8601 UTC timestamp.
+- `node` (object): node identity metadata.
+  - `node.level`: `L1` | `L2` | `L3`
+  - `node.id`: unique node identifier
+- `kind` (string): `command` | `query` | `event` | `telemetry` | `ack` | `error`
+
+### 4.2 Existing operational fields (must remain supported)
+- Command fields: `action`, `target`, `value`
+- Query fields: `query`
+- Event fields: `event`, `source`, `type`
+
+### 4.3 Ack/Error fields (v2 standardization)
+- Ack:
+  - `kind: "ack"`
+  - `ok: true|false`
+  - `ref`: request `id` being acknowledged
+- Error:
+  - `kind: "error"`
+  - `code`: stable machine code (e.g., `ERR_UNKNOWN_ACTION`)
+  - `message`: human-readable description
+  - `ref`: originating request id when available
+
+## 5) Canonical Message Examples
+
+### 5.1 Command (write output)
+```json
+{"v":"2.0","id":"cmd-001","kind":"command","action":"WRITE","target":"D13","value":1}
+```
+
+### 5.2 Query (heartbeat/identity)
+```json
+{"v":"2.0","id":"hb-001","kind":"query","query":"WHO_ARE_YOU"}
+```
+
+### 5.3 Event (edge trigger)
+```json
+{"v":"2.0","id":"evt-001","kind":"event","event":"TRIGGER","source":"D2","type":"Interrupt"}
+```
+
+### 5.4 Telemetry
+```json
+{"v":"2.0","id":"tel-001","kind":"telemetry","source":"A0","metric":"light","value":512,"unit":"raw"}
+```
+
+### 5.5 Ack
+```json
+{"v":"2.0","id":"ack-001","kind":"ack","ok":true,"ref":"cmd-001"}
+```
+
+### 5.6 Error
+```json
+{"v":"2.0","id":"err-001","kind":"error","code":"ERR_INVALID_TARGET","message":"Unknown target pin","ref":"cmd-001"}
+```
+
+## 6) Validation Rules
+- Payload MUST be valid JSON object.
+- Unknown top-level keys MAY be ignored unless strict mode is enabled.
+- Receivers MUST validate type/shape for recognized keys.
+- `action`, `query`, `event` values SHOULD be treated case-sensitive.
+- `id` values SHOULD be unique per sender session.
+- Numeric `value` fields SHOULD be range-checked by target type.
+
+## 7) Fail-Safe and Heartbeat Semantics
+- Host heartbeat uses `query: "WHO_ARE_YOU"` or a node-defined heartbeat query.
+- Nodes SHOULD define heartbeat timeout behavior.
+- On timeout/disconnect, nodes controlling actuators SHOULD revert to safe state and emit an `event` or `error` frame when possible.
+
+## 8) Security Notes
+- Validate all incoming JSON keys and value types.
+- Never execute unsanitized command strings from protocol payloads.
+- For untrusted networks, use authenticated/encrypted transport wrappers for ASP payloads.
+
+## 9) Versioning and Compatibility
+- ASP v2.0 is additive over legacy minimal frames.
+- Breaking changes require a new major version field (`v`).
+- Extensions SHOULD prefer new optional keys over mutating existing meanings.

docs/MegaMax/DOCS.md

@@ -0,0 +1,37 @@
+# MegaMax (L3) DOCS
+
+## Role
+MegaMax is the long-range tier for cellular-connected and mobility-oriented deployments.
+
+## Hardware Scope
+- ESP32 + SIM800L / SIM7000G
+- RP2040 + SIM7000G
+- LilyGO T-SIM series
+
+## Transport Profile
+- Primary transport: LTE/Cat-M/NB-IoT data sockets
+- Fallback transport: SMS control channel
+- Payload contract: ASP v2.0 JSON for data channels; SMS may carry compact command/query subsets
+
+## ASP v2.0 Mapping
+- Reuse L1/L2 core semantics (`command`, `query`, `event`, `telemetry`, `ack`, `error`).
+- For failover, keep command intent consistent across data and SMS paths.
+- Recommended metadata:
+  - `node.level = "L3"`
+  - correlation keys (`id`, `ref`) for retransmit-safe operation
+
+## Typical L3 Payloads
+```json
+{"v":"2.0","id":"gps-01","kind":"telemetry","metric":"gps","value":{"lat":12.34,"lon":56.78}}
+{"v":"2.0","id":"cmd-01","kind":"command","action":"WRITE","target":"RELAY1","value":0}
+{"v":"2.0","id":"ack-01","kind":"ack","ok":true,"ref":"cmd-01"}
+```
+
+## Reliability Expectations
+- State machine should handle transitions between data, SMS fallback, and sleep.
+- Buffered messages should retain `id` for dedupe and audit.
+
+## Verification Checklist
+- [ ] Data/SMS mode transitions preserve command semantics
+- [ ] GPS telemetry serializes to valid ASP telemetry frames
+- [ ] Heartbeat + fail-safe behavior is deterministic under high latency

docs/MicroMax/DOCS.md

@@ -0,0 +1,37 @@
+# MicroMax (L1) DOCS
+
+## Role
+MicroMax is the wired, low-latency endpoint layer for direct actuator/sensor control.
+
+## Hardware Scope
+- Arduino Uno / Nano (ATmega328P)
+- Raspberry Pi Pico (RP2040)
+- ESP32 (wired mode)
+
+## Transport Profile
+- Primary transport: USB Serial
+- ASP framing: newline-terminated JSON at 115200 baud (default)
+
+## ASP v2.0 Mapping
+- Mandatory legacy compatibility fields:
+  - `action`, `target`, `value`
+  - `event`, `source`, `type`
+  - `query` (heartbeat/identity)
+- Recommended v2 envelope:
+  - `v`, `id`, `ts`, `node`, `kind`
+
+## Baseline Message Examples
+```json
+{"action":"WRITE","target":"D13","value":1}
+{"event":"TRIGGER","source":"D2","type":"Interrupt"}
+{"query":"WHO_ARE_YOU"}
+```
+
+## Reliability Expectations
+- Heartbeat timeout handling should move outputs to safe state.
+- Ack/error responses should include correlation where available (`id`/`ref`).
+
+## Verification Checklist
+- [ ] Serial command parser accepts legacy and envelope-based ASP frames
+- [ ] Heartbeat timeout transitions to fail-safe
+- [ ] Event and telemetry frames serialize as valid JSON lines

docs/MiniMax/DOCS.md

@@ -0,0 +1,36 @@
+# MiniMax (L2) DOCS
+
+## Role
+MiniMax is the local wireless node tier for ambient telemetry and sentry workflows.
+
+## Hardware Scope
+- Raspberry Pi Pico W
+- ESP32 / ESP32-CAM
+- Challenger RP2040 WiFi
+
+## Transport Profile
+- Primary transport: WiFi + MQTT (or equivalent wireless socket)
+- Protocol contract: ASP v2.0 JSON mirrored over wireless transport
+
+## ASP v2.0 Mapping
+- Command/query/event semantics match L1 payload contract.
+- Wireless bridge should preserve payload body; transport metadata remains outside ASP payload.
+- Recommended fields:
+  - `v`, `id`, `node`, `kind`
+  - telemetry-friendly keys: `metric`, `value`, `unit`
+
+## Typical L2 Payloads
+```json
+{"v":"2.0","id":"tel-123","kind":"telemetry","source":"pir-1","metric":"motion","value":1}
+{"v":"2.0","id":"qry-123","kind":"query","query":"WHO_ARE_YOU"}
+{"v":"2.0","id":"evt-123","kind":"event","event":"SENTRY_ALERT","source":"cam-1","type":"visual"}
+```
+
+## Reliability Expectations
+- Reconnection logic should preserve session identity and re-publish heartbeat.
+- Node should emit `ack`/`error` frames for mirrored command paths.
+
+## Verification Checklist
+- [ ] MQTT heartbeat survives reconnect cycles
+- [ ] ASP payload parity with L1 is maintained
+- [ ] Sentry events publish as valid ASP event JSON