Add project command API

docs/circuit-list-editor-api.md

@@ -6,15 +6,49 @@ The circuit-first editor uses tree, circuit, row and project-device endpoints.
 All paths below are mounted below `/api`. There is no Consumer application API.
 
 Project responses from `GET /projects` and `GET /projects/:projectId` include
-`currentRevision`. It currently exposes the persisted revision foundation only;
-no public undo or redo command exists yet.
+`currentRevision`. Versioned project commands use this value for optimistic
+concurrency checks.
 
-### Project History State
+### Project Commands and History
 
 - `GET /projects/:projectId/history`
   - returns `currentRevision`, `undoDepth`, `redoDepth` and the current top
     change-set id for both persistent stacks
-  - is read-only; the editor does not consume it yet
+- `POST /projects/:projectId/commands`
+  - executes a supported versioned command as a new user revision
+  - body: `{ "expectedRevision": 0, "command": { ... } }`
+- `POST /projects/:projectId/history/undo`
+- `POST /projects/:projectId/history/redo`
+  - body: `{ "expectedRevision": 1 }`
+  - executes the eligible inverse or forward command as a new auditable
+    revision
+
+The public dispatcher currently supports `circuit.update` and
+`circuit-device-row.update`, both with schema version `1`. Other command types
+are rejected. The editor does not consume these endpoints yet.
+
+Example:
+
+```json
+{
+  "expectedRevision": 0,
+  "description": "Rename circuit",
+  "command": {
+    "schemaVersion": 1,
+    "type": "circuit.update",
+    "payload": {
+      "circuitId": "cir_1",
+      "changes": [
+        { "field": "displayName", "value": "Sockets East" }
+      ]
+    }
+  }
+}
+```
+
+A stale `expectedRevision` returns HTTP `409` with
+`PROJECT_REVISION_CONFLICT`. Undo or redo without an eligible stack entry
+returns HTTP `409` with `PROJECT_HISTORY_OPERATION_UNAVAILABLE`.
 
 ## Circuit-First Endpoints