docs: architecture overview and API spec

.prettierignore

@@ -0,0 +1,5 @@
+dist/
+node_modules/
+coverage/
+.turbo/
+package-lock.json

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2
+}

README.md

@@ -18,6 +18,11 @@ MoltClaw is the **cloud brain** of the Clawland ecosystem — a TypeScript-based
 - **Plugin System** — Extensible architecture for custom integrations
 - **Multi-Provider Support** — OpenAI, Anthropic, Google Gemini, local models, and more
 
+## Documentation
+
+- **[Architecture Overview](docs/architecture.md)** — High-level L3 Cloud Gateway design and Mermaid diagrams.
+- **[API Design](docs/api.md)** — Endpoint specifications and request/response schemas.
+
 ## Architecture
 
 ```
@@ -41,11 +46,11 @@ MoltClaw is the **cloud brain** of the Clawland ecosystem — a TypeScript-based
 
 - **Language:** TypeScript / Node.js
 - **Runtime:** >1GB RAM, Cloud / Mac Mini / any server
-- **Framework:** TBD (contributions welcome!)
+- **Framework:** [Hono](https://hono.dev/) with Node-server
 
 ## Status
 
-🚧 **Pre-Alpha** — Architecture design phase. Looking for contributors!
+🚧 **Pre-Alpha** — Basic HTTP gateway implemented. Looking for contributors!
 
 ## Contributing
 

docs/api.md

@@ -0,0 +1,63 @@
+# MoltClaw API Design (v1)
+
+This is the spec for how MoltClaw talks to the world. We're keeping it REST-ish for now using Hono.
+
+## Base URL
+The default dev server runs at `http://localhost:3000`.
+
+## Endpoints
+
+### 1. Health Check
+`GET /healthz`
+
+Simple probe to check if the gateway is alive.
+- **Response**: `200 OK`
+- **Body**:
+  ```json
+  {
+    "status": "ok",
+    "uptime": 123,
+    "version": "0.1.0"
+  }
+  ```
+
+### 2. Fleet Registration
+`POST /api/v1/fleet/register`
+
+Used by PicoClaw agents when they first boot up.
+- **Request Body**:
+  ```json
+  {
+    "agentId": "uuid-string",
+    "hardware": "esp32/pi/etc",
+    "capabilities": ["sensing", "actuation"]
+  }
+  ```
+- **Response**: `201 Created`
+
+### 3. Fleet Heartbeat
+`POST /api/v1/fleet/heartbeat`
+
+Agents hit this every X seconds to stay "Active" in the fleet manager.
+- **Request Body**:
+  ```json
+  {
+    "agentId": "uuid-string",
+    "load": 0.45,
+    "status": "idle"
+  }
+  ```
+- **Response**: `200 OK`
+
+## Configuration (Environment Variables)
+
+Stick these in your `.env` file (don't commit it!):
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PORT` | Port the gateway binds to | `3000` |
+| `LOG_LEVEL` | Verbosity of the Hono logger | `info` |
+
+---
+
+*TODO: Document the authentication flow (API keys or JWT?) once we implement the auth middleware.*

docs/architecture.md

@@ -0,0 +1,37 @@
+# MoltClaw Architecture
+
+MoltClaw acts as the **L3 Cloud Gateway** for the Clawland network. Its main job is to sit between the high-level cloud orchestration and the tiny edge agents (PicoClaw) running on actual hardware.
+
+## Big Picture
+
+We're building this to be the "brain" that knows where every edge agent is and what it's doing. It handles the heavy lifting so the PicoClaw agents can stay lean.
+
+```mermaid
+graph TD
+    A["Cloud Orchestrator (User/Control Plane)"] -->|Commands| B["MoltClaw (L3 Gateway)"]
+    B -->|Instruction Set| C["PicoClaw Agent A (Edge)"]
+    B -->|Instruction Set| D["PicoClaw Agent B (Edge)"]
+    C -->|Heartbeat/State| B
+    D -->|Heartbeat/State| B
+
+    subgraph "MoltClaw Internals"
+        B1["Fleet Manager"]
+        B2["Routing Engine"]
+        B3["State Store"]
+    end
+```
+
+## Core Components
+
+1.  **Fleet Manager**: Keeps track of who's online. It handles the registration handshake and monitors those incoming heartbeats.
+2.  **Routing Engine**: Decides which agent gets which task. If Agent A is busy or offline, the router finds someone else.
+3.  **State Store**: (Coming Soon) A persistent way to remember agent configurations and history.
+
+## Integration with PicoClaw
+
+PicoClaw agents are expected to:
+- Register themselves on startup.
+- Send a "pulse" (heartbeat) every few seconds.
+- Listen for specific task payloads defined in the MoltClaw instruction set.
+
+*Note: We're still early in the design, so expect some of the internal routing logic to change as we scale. TODO: add more detail on the state store once we pick a DB.*

eslint.config.js

@@ -0,0 +1,17 @@
+import js from "@eslint/js";
+import ts from "typescript-eslint";
+
+export default ts.config(
+  js.configs.recommended,
+  ...ts.configs.recommended,
+  {
+    rules: {
+      "no-unused-vars": "warn",
+      "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+      "@typescript-eslint/no-explicit-any": "warn",
+    },
+  },
+  {
+    ignores: ["dist/", "node_modules/", "coverage/"],
+  }
+);