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

[Copilot]

Description

This PR addresses the Protocol Architect scope in the orchestration plan by defining a single ASP v2.0 contract and publishing missing cross-tier documentation for L1/L2/L3 onboarding and protocol parity.
It adds the required research artifact and establishes canonical docs at the repository root for consistent implementation across MicroMax, MiniMax, and MegaMax.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Dependency update

Affected Modules

• Core/CLI
• Core/RAM
• MicroMax/OS
• MicroMax/OS Client
• IOT
• conductor
• Documentation

Changes Made

• Protocol standardization

  • Added SPEC_ASP_V2.md as the canonical ASP v2.0 spec (transport/framing, envelope, message kinds, validation, compatibility, fail-safe semantics).
  • Codified v2 as additive/backward-compatible with existing minimal frames (action/target/value, event/source/type, query).

• Research artifact

  • Added root RESEARCH.md documenting in-repo ASP audit findings and design decisions for v2 extensibility.

• Node-level operational docs

  • Added:
    • docs/MicroMax/DOCS.md
    • docs/MiniMax/DOCS.md
    • docs/MegaMax/DOCS.md
  • Each doc maps tier-specific transport behavior to the shared ASP payload contract and includes verification checklists.

• Onboarding and discoverability

  • Added MASTER_SETUP_GUIDE.md for end-to-end L1/L2/L3 onboarding and conformance checks.
  • Updated root README.md documentation links to surface the new canonical docs.

• Example ASP v2 frame

  {"v":"2.0","id":"cmd-001","kind":"command","action":"WRITE","target":"D13","value":1}

How Has This Been Tested?

• Ran existing test suite
• Added new tests
• Manual testing (describe below)

Test Details

# Documentation change; validated by review/consistency pass:
# - cross-checked field names and examples with:
#   ARCHITECTURE.md, AI_PROMPTS.md, MicroMax/README.md
# - verified all new documentation links resolve from README.md

Validation Checklist

• Code follows the project's style guidelines
• I have commented complex code sections
• Documentation has been updated (if needed)
• Tests pass locally and don't break existing functionality
• Commit messages follow the project convention (e.g., area: action)
• No secrets or credentials were committed
• Changes are focused and don't include unrelated modifications

Screenshots (if applicable)

N/A (no UI changes)

Related Issues or PRs

• Source requirements captured in AI_PROMPTS.md (“Copilot Cloud: The Protocol Architect” section).

Additional Notes

• Paths were normalized to portable repository-relative links (no environment-specific absolute paths).
• Changes are documentation-only; no runtime code paths were modified.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• docs.aws.amazon.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
• fonts.googleapis.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/APEX/APEX/Core/RAM/node_modules/.bin/next build (dns block)
• www.home-assistant.io
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

YOU ARE AGENT COPILOT CLOUD # AI Agent Orchestration: Unified Prompts This document contains the standardized prompts for each AI agent participating in the APEX Tiered Node Expansion. --- ## 🛑 GLOBAL PROTOCOL (For All Agents) 1. RESEARCH FIRST: You MUST perform a research phase and document findings in a RESEARCH.md file within your module before touching any source code. 2. HARDWARE SCOPE: Your implementation MUST aim for universal support across AVR (Uno), RP2040 (Pico), and ESP32 series microcontrollers. 3. PROTOCOL PARITY: All communication MUST adhere to or extend the Apex Serial Protocol (ASP) v2.0 (JSON-based). 4. ISOLATION: Work only within your assigned repository/directory. 5. SUBMISSION: Once complete and verified, open a separate Pull Request for your module. --- ## 1. Google Jules: The Reliability Engineer (MicroMax L1) Target: APEX-MicroMax Objective: Refactor the baseline firmware into a high-reliability, multi-board Hardware Abstraction Layer (HAL). Prompt: > You are the Reliability Engineer for APEX. Your task is to refactor the MicroMax/OS firmware. > 1. Research Phase: Investigate Hardware Abstraction Layer (HAL) patterns for Arduino/C++ that allow a single codebase to support ATmega328P, RP2040, and ESP32 without excessive #ifdef macros. Document this in RESEARCH.md. > 2. Core Implementation: > - Implement a deterministic Fail-Safe State Machine that triggers if the host heartbeat expires. > - Ensure all Relays/Servos revert to safe positions on disconnect. > - Standardize the Communication.cpp logic to be 100% compliant with ASP v2.0. > 3. Verification: Add unit tests for the command parser and state transitions. > 4. Output: Open a PR to riteshrajas/APEX-MicroMax. --- ## 2. Copilot CLI: The Wireless Specialist (MiniMax L2) Target: APEX-MiniMax Objective: Implement the wireless "Ambient Intelligence" stack for local WiFi nodes. Prompt: > You are the Wireless Specialist for APEX. Your task is to build the MiniMax/OS for Level 2 nodes. > 1. Research Phase: Research robust WiFi reconnection strategies and MQTT state management for ESP32 and Pico W. Investigate low-bandwidth image capture logic for the ESP32-CAM (Visual Sentry). Document in RESEARCH.md. > 2. Core Implementation: > - Build a WiFi/MQTT bridge that mirrors the ASP v2.0 protocol over wireless sockets. > - Implement ambient telemetry publishing (Motion, Air Quality, Light). > - Add a 'Sentry Mode' that triggers visual alerts via MQTT. > 3. Verification: Verify the MQTT heartbeat and reconnection logic under simulated network loss. > 4. Output: Open a PR to riteshrajas/APEX-MiniMax. --- ## 3. Codex CLI: The Global Orchestrator (MegaMax L3) Target: APEX-MegaMax Objective: Implement the cellular "Long-Range" stack for outdoor/mobile nodes. Prompt: > You are the Global Orchestrator for APEX. Your task is to build the MegaMax/OS for Level 3 nodes. > 1. Research Phase: Research TinyGSM integration for SIM7000G and SIM800L modems. Focus on LTE data socket management, SMS command fallback logic, and GPS geolocation accuracy. Document in RESEARCH.md. > 2. Core Implementation: > - Implement a cellular data bridge to the APEX Core. > - Build an SMS-based fail-over control system for high-latency environments. > - Implement periodic GPS telemetry and power-saving sleep cycles. > 3. Verification: Test the state machine transitions between LTE Data, SMS, and Sleep modes. > 4. Output: Open a PR to riteshrajas/APEX-MegaMax. --- ## 4. Gemini CLI: The Bridge Architect (Apex Horizon Hub) Target: Core/Horizon Objective: Build the Universal PWA Hub that orchestrates all node levels. Prompt: > You are the Bridge Architect for APEX. Your task is to build the Apex Horizon universal dashboard. > 1. Research Phase: Investigate PWA patterns for handling simultaneous Web Serial (L1), MQTT.js (L2), and Cloud WebSockets (L3) connections. Research semantic parsing of hardware telemetry for injection into the RAM Brain. Document in RESEARCH.md. > 2. Core Implementation: > - Build the Transport Adapter Layer: Modular classes for Serial, WiFi, and Cloud communication. > - Implement the Universal HUD: Real-time telemetry visualization for all node levels. > - Implement the Semantic Command HUD: A UI that sends natural language commands to the Brain for hardware inference. > 3. Verification: Perform an end-to-end handshake test: Hardware Event -> Horizon Adapter -> Brain Ingestion. > 4. Output: Open a PR to Core/Horizon. --- ## 5. Copilot Cloud: The Protocol Architect (Docs & Standards) Target: APEX (Root) Objective: Formalize the ecosystem standards and generate master documentation. Prompt: > You are the Protocol Architect for APEX. Your task is to formalize the ecosystem standards. > 1. Research Phase: Audit existing node implementations and the origi...

Created from Copilot CLI via the copilot delegate command.