diff --git a/README.md b/README.md
index 089b0bf..efbb010 100644
--- a/README.md
+++ b/README.md
@@ -43,3 +43,6 @@ contain only local synthetic data.
 Named-user command rules use `bot-command-user-rule.json`; fixtures contain
 only synthetic Twitch IDs and literal response templates.
 
+Typed command arguments use `bot-command-argument-definition.json` and remain
+literal validated data.
+
diff --git a/contracts/v1/bot-command-argument-definition.json b/contracts/v1/bot-command-argument-definition.json
new file mode 100644
index 0000000..e8df7ba
--- /dev/null
+++ b/contracts/v1/bot-command-argument-definition.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/bot-command-argument-definition.json",
+  "title": "Trixie typed bot command argument",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "kind", "required"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" },
+    "kind": { "enum": ["text", "number", "choice", "username", "duration"] },
+    "required": { "type": "boolean" },
+    "default": { "type": ["string", "null"], "maxLength": 200 },
+    "minimum": { "type": ["integer", "null"] },
+    "maximum": { "type": ["integer", "null"] },
+    "choices": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }
+  }
+}
diff --git a/fixtures/v1/bot-command-argument-definition.json b/fixtures/v1/bot-command-argument-definition.json
new file mode 100644
index 0000000..3e3ef01
--- /dev/null
+++ b/fixtures/v1/bot-command-argument-definition.json
@@ -0,0 +1,9 @@
+{
+  "name": "count",
+  "kind": "number",
+  "required": true,
+  "default": null,
+  "minimum": 1,
+  "maximum": 5,
+  "choices": []
+}