commands: declarative argument schemas with dispatch validation

1 files changed, 18 insertions, 5 deletions

diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index 16fd2c5..00f5200 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -220,20 +220,33 @@ The discovery commands themselves:
 ### 6.2 `describe`
 
 Returns the full command catalogue. `describe {"cmd":"voucher.post"}` returns
-one entry. Each entry:
+one entry. Each entry carries a declarative argument schema:
 
 ```json
 {
   "name":"voucher.post","summary":"Post an immutable voucher",
   "permission":{"role":"bookkeeper","require_org":true},
   "mutating":true,"dry_run":true,
-  "args":{"date":{"type":"date","required":true},
-          "rows":{"type":"array","min":2,"of":{...}}},
-  "result":{...},
-  "examples":[{"args":{...},"result":{...}}]
+  "args":[
+    {"name":"date","type":"date","required":true,
+     "description":"Voucher date (YYYY-MM-DD)"},
+    {"name":"description","type":"string","required":false},
+    {"name":"rows","type":"json","required":false,
+     "description":"Array of {account,debit_ore,credit_ore,description?}"}
+  ]
 }
 ```
 
+`args` is an array in validation order. `type` is one of `string`, `int`,
+`bool`, `enum`, `date` or `json`; `required` tells whether the argument must
+be present (and, for `string`/`enum`, non-empty); `default` gives the
+documented default; `values` lists the allowed values of an `enum`; and
+`description` is a one-line summary. `json` covers structured values (rows,
+entries, ids, selections). The daemon validates every present argument
+against this schema before the handler runs and answers `INVALID_ARGS` for a
+missing required argument or a wrong type; unknown arguments are ignored for
+forward compatibility. Commands without arguments emit an empty array.
+
 This is the primary integration surface for agents: call `describe`, then act.
 
 ### 6.3 `agent.instructions`