Align Commons requests with v1.1.0 schemas

Author: GsCommand

EXAMPLES.md

@@ -1,21 +1,33 @@
 # CommandLayer SDK Examples
 
-Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story receipt-first: `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object is protocol metadata rather than a commercial SDK surface.
+Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story aligned with the active request and receipt contracts: requests are flat top-level protocol objects, `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object only appears inside receipts as protocol metadata.
 
 All examples in this file target:
 - Protocol-Commons v1.1.0,
+- flat request payloads shaped exactly like `schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json`,
 - canonical signed receipts returned as `response.receipt`, and
 - optional execution context returned as `response.runtime_metadata`.
 
-## 1. Canonical response envelope
+## 1. Canonical summarize request
+
+```json
+{
+  "verb": "summarize",
+  "version": "1.1.0",
+  "input": "CommandLayer defines semantic agent verbs.",
+  "mode": "brief"
+}
+```
+
+## 2. Canonical response envelope
 
 ```json
 {
   "receipt": {
     "status": "success",
     "x402": {
       "verb": "summarize",
-      "version": "1.1.0",
+      "version": "1.1.0"
     },
     "result": {
       "summary": "..."
@@ -39,15 +51,14 @@ All examples in this file target:
 }
 ```
 
-## 2. TypeScript examples
+## 3. TypeScript examples
 
 ### Create client
 
 ```ts
 import { createClient } from "@commandlayer/sdk";
 
 const client = createClient({
-  actor: "examples-ts",
   runtime: "https://runtime.commandlayer.org"
 });
 ```
@@ -56,8 +67,8 @@ const client = createClient({
 
 ```ts
 const response = await client.summarize({
-  content: "CommandLayer defines semantic agent verbs.",
-  style: "bullet_points"
+  input: "CommandLayer defines semantic agent verbs.",
+  mode: "brief"
 });
 
 console.log(response.receipt.result?.summary);
@@ -67,73 +78,70 @@ console.log(response.receipt.result?.summary);
 
 ```ts
 const response = await client.analyze({
-  content: "Invoice total: $1200",
-  goal: "detect finance intent"
+  input: "Invoice total: $1200",
+  mode: "deep"
 });
 ```
 
 ### Classify
 
 ```ts
 const response = await client.classify({
-  content: "Contact support@example.com"
+  input: "Contact support@example.com",
+  mode: "single"
 });
 ```
 
 ### Clean
 
 ```ts
 const response = await client.clean({
-  content: "   test@example.com  ",
-  operations: ["trim", "redact_emails"]
+  input: "   test@example.com  ",
+  mode: "sanitize"
 });
 ```
 
 ### Convert
 
 ```ts
 const response = await client.convert({
-  content: '{"a":1}',
-  from: "json",
-  to: "csv"
+  input: '{"a":1}',
+  mode: "structured"
 });
 ```
 
 ### Describe
 
 ```ts
 const response = await client.describe({
-  subject: "receipt verification",
-  audience: "general",
-  detail: "medium"
+  input: "receipt verification",
+  mode: "detailed"
 });
 ```
 
 ### Explain
 
 ```ts
 const response = await client.explain({
-  subject: "receipt verification",
-  audience: "novice",
-  style: "step-by-step"
+  input: "receipt verification",
+  mode: "stepwise"
 });
 ```
 
 ### Format
 
 ```ts
 const response = await client.format({
-  content: "a: 1\nb: 2",
-  to: "table"
+  input: "a: 1\nb: 2",
+  mode: "markdown"
 });
 ```
 
 ### Parse
 
 ```ts
 const response = await client.parse({
-  content: '{ "a": 1 }',
-  contentType: "json",
+  input: '{ "a": 1 }',
   mode: "strict"
 });
 ```
@@ -142,154 +150,7 @@ const response = await client.parse({
 
 ```ts
 const response = await client.fetch({
-  source: "https://example.com",
-  include_metadata: true
-});
-```
-
-## 3. Python examples
-
-```python
-from commandlayer import create_client
-
-client = create_client(actor="examples-py")
-
-summary = client.summarize(content="CommandLayer defines semantic agent verbs.", style="bullet_points")
-analysis = client.analyze(content="Invoice total: $1200", goal="detect finance intent")
-classification = client.classify(content="Contact support@example.com")
-cleaned = client.clean(content="   test@example.com  ", operations=["trim", "redact_emails"])
-converted = client.convert(content='{"a":1}', from_format="json", to_format="csv")
-description = client.describe(subject="receipt verification")
-explanation = client.explain(subject="receipt verification", style="step-by-step")
-formatted = client.format(content="a: 1\nb: 2", to="table")
-parsed = client.parse(content='{ "a": 1 }', content_type="json", mode="strict")
-fetched = client.fetch(source="https://example.com", include_metadata=True)
-```
-
-## 4. Verification examples
-
-### TypeScript, explicit key
-
-```ts
-import { verifyReceipt } from "@commandlayer/sdk";
-
-const result = await verifyReceipt(response.receipt, {
-  publicKey: "ed25519:BASE64_PUBLIC_KEY"
-});
-```
-
-### Python, explicit key
-
-```python
-from commandlayer import verify_receipt
-
-result = verify_receipt(response["receipt"], public_key="ed25519:BASE64_PUBLIC_KEY")
-```
-
-### ENS-backed verification
-
-```ts
-const result = await verifyReceipt(response.receipt, {
-  ens: {
-    name: "summarizeagent.eth",
-    rpcUrl: process.env.MAINNET_RPC_URL!
-  }
-});
-```
-
-```python
-result = verify_receipt(
-    response["receipt"],
-    ens={"name": "summarizeagent.eth", "rpcUrl": "https://mainnet.infura.io/v3/YOUR_KEY"},
-)
-```
-
-## 5. CLI examples
-
-### Summarize
-
-```bash
-commandlayer summarize \
-  --content "CommandLayer defines semantic verbs." \
-  --style bullet_points \
-  --json
-```
-
-### Analyze
-
-```bash
-commandlayer analyze \
-  --content "Invoice total: $500" \
-  --goal "detect finance intent" \
-  --json
-```
-
-### Verify a saved receipt
-
-```bash
-commandlayer verify \
-  --file receipt.json \
-  --public-key "ed25519:BASE64_PUBLIC_KEY"
-```
-
-## 6. Runtime override
-
-### TypeScript
-
-```ts
-const client = createClient({
-  actor: "override-example",
-  runtime: "https://staging-runtime.commandlayer.org"
+  input: "https://example.com",
+  mode: "html"
 });
 ```
-
-### Python
-
-```python
-client = create_client(
-    actor="override-example",
-    runtime="https://staging-runtime.commandlayer.org",
-)
-```
-
-## 7. Persist the canonical receipt
-
-```ts
-import { writeFile } from "node:fs/promises";
-
-await writeFile("receipt.json", JSON.stringify(response.receipt, null, 2));
-```
-
-```python
-import json
-from pathlib import Path
-
-Path("receipt.json").write_text(json.dumps(response["receipt"], indent=2), encoding="utf-8")
-```
-
-## 8. Error handling
-
-### TypeScript
-
-```ts
-import { CommandLayerError } from "@commandlayer/sdk";
-
-try {
-  await client.summarize({ content: "" });
-} catch (error) {
-  if (error instanceof CommandLayerError) {
-    console.error(error.statusCode, error.message, error.details);
-  }
-}
-```
-
-### Python
-
-```python
-from commandlayer import CommandLayerError
-
-try:
-    client.summarize(content="")
-except CommandLayerError as error:
-    print(error.status_code, error, error.details)
-```

QUICKSTART.md

@@ -31,11 +31,11 @@ npm install -g @commandlayer/sdk
 ```ts
 import { createClient } from "@commandlayer/sdk";
 
-const client = createClient({ actor: "quickstart-ts" });
+const client = createClient();
 
 const response = await client.summarize({
-  content: "CommandLayer makes agent execution verifiable.",
-  style: "bullet_points"
+  input: "CommandLayer makes agent execution verifiable.",
+  mode: "brief"
 });
 
 console.log(response.receipt.result?.summary);
@@ -55,7 +55,22 @@ response = client.summarize(
 print(response["receipt"]["result"]["summary"])
 ```
 
-## 3. Inspect the response
+## 3. Inspect the request contract
+
+Protocol-Commons v1.1.0 Commons requests are flat top-level objects:
+
+```json
+{
+  "verb": "summarize",
+  "version": "1.1.0",
+  "input": "CommandLayer makes agent execution verifiable.",
+  "mode": "brief"
+}
+```
+
+Do not send nested `input` objects, `limits`, actor wrappers, or `x402` request metadata for Commons verbs.
+
+## 4. Inspect the response
 
 Both SDKs return the same shape:
 
@@ -83,9 +98,9 @@ Both SDKs return the same shape:
 }
 ```
 
-Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata and is not a commercial feature signal.
+Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata in receipts and is not a request wrapper or commercial feature signal.
 
-## 4. Verify the receipt
+## 5. Verify the receipt
 
 ### TypeScript
 
@@ -118,12 +133,12 @@ Use the same signer-discovery model in both SDKs:
 - signer ENS TXT: `cl.sig.pub`
 - signer ENS TXT: `cl.sig.kid`
 
-## 5. Try the CLI
+## 6. Try the CLI
 
 ```bash
 commandlayer summarize \
-  --content "CommandLayer makes agent execution verifiable." \
-  --style bullet_points \
+  --input "CommandLayer makes agent execution verifiable." \
+  --mode brief \
   --json
 ```
 
@@ -135,7 +150,7 @@ commandlayer verify \
   --public-key "ed25519:BASE64_PUBLIC_KEY"
 ```
 
-## 6. What is stable today?
+## 7. What is stable today?
 
 Stable in this repo:
 - Protocol-Commons v1.1.0 verb surface,