Set up Cloud Agent development environment (macaddy toolkit)

.cursor/environment.json

@@ -0,0 +1,16 @@
+{
+  "name": "macaddy",
+  "install": "npm ci",
+  "terminals": [
+    {
+      "name": "dev-server",
+      "command": "npm run dev"
+    }
+  ],
+  "ports": [
+    {
+      "name": "web",
+      "port": 3000
+    }
+  ]
+}

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+npm-debug.log*
+.DS_Store
+*.log
+.env

README.md

@@ -1 +1,66 @@
-# macaddy
+# macaddy
+
+A small MAC address toolkit. `macaddy` validates, normalizes, inspects, and
+generates 48-bit MAC addresses through a tiny HTTP API and a single-page web UI.
+It ships with an offline subset of the IEEE OUI registry so vendor lookups work
+without network access.
+
+## Features
+
+- Validate MAC addresses in colon, hyphen, Cisco-dot, or bare notation.
+- Normalize a MAC into any of those notations (upper/lowercase).
+- Inspect bit-level facts: OUI/NIC split, unicast vs multicast,
+  universal vs locally-administered, and broadcast detection.
+- Look up the vendor from a MAC's OUI (offline table).
+- Generate random, locally-administered unicast MAC addresses.
+
+## Requirements
+
+- Node.js >= 20 (developed against Node 22)
+
+## Getting started
+
+```bash
+npm install       # install dependencies
+npm test          # run the unit and API tests
+npm start         # start the server on http://localhost:3000
+npm run dev       # start with auto-reload (node --watch)
+```
+
+Set `PORT` to change the listening port (defaults to `3000`).
+
+## HTTP API
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/health` | Liveness check. |
+| GET | `/api/lookup?mac=<mac>` | Validate + analyze a MAC address. |
+| GET | `/api/generate?format=<fmt>&upper=<bool>` | Generate a random MAC. |
+
+`format` may be `colon` (default), `hyphen`, `dot`, or `bare`.
+
+### Examples
+
+```bash
+curl 'http://localhost:3000/api/health'
+curl 'http://localhost:3000/api/lookup?mac=00:1b:63:84:45:e6'
+curl 'http://localhost:3000/api/generate?format=hyphen'
+```
+
+## Project layout
+
+```
+src/
+  mac.js       # pure MAC utilities (validate/normalize/analyze/generate)
+  oui.js       # offline OUI -> vendor table
+  server.js    # Express app + JSON API + static frontend
+public/        # single-page web UI
+test/          # node:test unit + API tests
+```
+
+## Cloud Agent environment
+
+This repository is configured for Cursor Cloud Agents via
+[`.cursor/environment.json`](.cursor/environment.json): dependencies are
+installed with `npm ci` and the dev server runs in a `terminals` entry on
+port 3000.