docs: LLM-ready documentation suite — LLM_CONTEXT.md, module deep-dives, JSON schemas, CLI reference

Complete documentation system for LLM consumption: primary LLM_CONTEXT.md (27KB system overview), 4 module deep-dives (composer, reaper-builder, reaper-scripting, calibrator), 2 JSON Schema draft-07 contracts, CLI reference, and README correction (FL Studio -> REAPER identity).
2026-05-04 10:30:24 -03:00
parent b08dcccca2
commit 7bcd8052a9
13 changed files with 2402 additions and 29 deletions
--- a/docs/schemas/reascript-protocol.json
+++ b/docs/schemas/reascript-protocol.json
@@ -0,0 +1,158 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fl-control/schemas/reascript-protocol.json",
+  "title": "ReaScript Protocol",
+  "description": "Command/result protocol for ReaScript two-way JSON communication",
+  "definitions": {
+    "ReaScriptCommand": {
+      "title": "ReaScriptCommand",
+      "description": "Command sent to the ReaScript via fl_control_command.json",
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "integer",
+          "description": "Protocol version",
+          "default": 1
+        },
+        "action": {
+          "description": "Single action name or pipeline list. Known values: add_plugins, configure_fx_params, verify_fx, calibrate, render",
+          "default": "calibrate",
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          ]
+        },
+        "rpp_path": {
+          "type": "string",
+          "description": "Path to .rpp file to open",
+          "default": ""
+        },
+        "render_path": {
+          "type": "string",
+          "description": "Path for rendered WAV output",
+          "default": ""
+        },
+        "timeout": {
+          "type": "integer",
+          "description": "Polling timeout in seconds",
+          "default": 120
+        },
+        "track_calibration": {
+          "type": "array",
+          "description": "Per-track volume/pan/send calibration",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "track_index": { "type": "integer" },
+              "volume": { "type": "number" },
+              "pan": { "type": "number" },
+              "sends": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "dest_track_index": { "type": "integer" },
+                    "level": { "type": "number" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "plugins_to_add": {
+          "type": "array",
+          "description": "Each dict: {\"track_name\": str, \"fx_name\": str, \"params\": {\"0\": float, ...}}",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "track_name": { "type": "string" },
+              "fx_name": { "type": "string" },
+              "params": {
+                "type": "object",
+                "additionalProperties": { "type": "number" }
+              }
+            },
+            "required": ["track_name", "fx_name"]
+          }
+        }
+      }
+    },
+    "ReaScriptResult": {
+      "title": "ReaScriptResult",
+      "description": "Result written by the ReaScript to fl_control_result.json",
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "integer",
+          "description": "Protocol version",
+          "default": 1
+        },
+        "status": {
+          "type": "string",
+          "description": "ok | error | timeout",
+          "default": "ok",
+          "enum": ["ok", "error", "timeout"]
+        },
+        "message": {
+          "type": "string",
+          "description": "Error or status message",
+          "default": ""
+        },
+        "lufs": {
+          "type": ["number", "null"],
+          "description": "Integrated LUFS",
+          "default": null
+        },
+        "integrated_lufs": {
+          "type": ["number", "null"],
+          "description": "Integrated LUFS reading",
+          "default": null
+        },
+        "short_term_lufs": {
+          "type": ["number", "null"],
+          "description": "Short-term LUFS",
+          "default": null
+        },
+        "fx_errors": {
+          "type": "array",
+          "description": "FX verification errors. Each dict: {\"track_index\": int, \"fx_index\": int, \"name\": str, \"expected\": str}",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "track_index": { "type": "integer" },
+              "fx_index": { "type": "integer" },
+              "name": { "type": "string" },
+              "expected": { "type": "string" }
+            }
+          }
+        },
+        "tracks_verified": {
+          "type": "integer",
+          "description": "Number of tracks verified",
+          "default": 0
+        },
+        "added_plugins": {
+          "type": "array",
+          "description": "Each dict: {\"fx_name\": str, \"instance_id\": int, \"track_name\": str, \"status\": str}",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "fx_name": { "type": "string" },
+              "instance_id": { "type": "integer" },
+              "track_name": { "type": "string" },
+              "status": { "type": "string" }
+            },
+            "required": ["fx_name", "track_name", "status"]
+          }
+        }
+      }
+    }
+  }
+}