fix: correct 4 documentation inaccuracies found by docs-validation suite

docs/assets/samples/agent-card-full.json

@@ -3,6 +3,7 @@
   "description": "AI-powered code review assistant that analyzes pull requests for bugs, security issues, and style improvements",
   "url": "https://codereview.example.com",
   "version": "2.1.0",
+  "protocolVersion": "0.2.1",
   "documentationUrl": "https://docs.codereview.example.com",
   "provider": {
     "organization": "DevTools Inc",

docs/assets/samples/agent-card.json

@@ -3,6 +3,7 @@
   "description": "A helpful AI assistant built with CapiscIO",
   "url": "https://my-agent.example.com",
   "version": "1.0.0",
+  "protocolVersion": "0.2.1",
   "provider": {
     "organization": "My Company",
     "url": "https://mycompany.com"

docs/getting-started/complete-workflow.md

@@ -47,6 +47,7 @@ Every A2A agent needs an `agent-card.json` that describes its capabilities:
   "description": "A helpful assistant that can answer questions",
   "url": "https://my-agent.example.com",
   "version": "1.0.0",
+  "protocolVersion": "{{ protocol_version }}",
   "provider": {
     "organization": "My Company",
     "url": "https://example.com"

docs/getting-started/secure/1-intro.md

@@ -99,13 +99,15 @@ The token contains:
 
 ```json
 {
-  "iss": "did:capiscio:agent:my-agent",
   "iat": 1701432000,
   "exp": 1701432060,
   "bh": "sha256-hash-of-body"
 }
 ```
 
+!!! note "Production vs Dev Mode"
+    In production with registered badges, the token also includes `"iss"` (the agent's DID). In dev mode, only `iat`, `exp`, and `bh` are present.
+
 ---
 
 ## What You'll Learn

docs/getting-started/secure/2-sdk.md

@@ -154,7 +154,7 @@ async def handle_message(request: Request):
     # 3. Verify the signature
     try:
         claims = guard.verify_inbound(badge_token, body=body)
-        print(f"✅ Verified request from: {claims.get('iss')}")
+        print(f"✅ Verified request from: {claims.get('iss', 'dev-mode agent')}")
     except Exception as e:
         raise HTTPException(status_code=401, detail=f"Signature verification failed: {e}")
 

docs/getting-started/secure/3-guard.md

@@ -52,13 +52,15 @@ your-project/
 
     Decoded claims:
     {
-      "iss": "local-dev-agent",
       "iat": 1701432000,
       "exp": 1701432060,
       "bh": "sha256:a1b2c3d4e5f6..."
     }
     ```
 
+    !!! note
+        In dev mode, claims contain `iat`, `exp`, and `bh`. The `iss` claim (agent DID) is added when using registered badges in production.
+
 ### Use the Signature in HTTP
 
 === "Code"
@@ -112,7 +114,7 @@ your-project/
 
     try:
         claims = guard.verify_inbound(jws=badge, body=body)
-        print(f"✓ Valid request from: {claims['iss']}")
+        print(f"✓ Valid request")
         print(f"  Issued at: {claims['iat']}")
         print(f"  Expires: {claims['exp']}")
     except VerificationError as e:
@@ -122,7 +124,7 @@ your-project/
 === "Valid Request"
 
     ```
-    ✓ Valid request from: partner-agent
+    ✓ Valid request
       Issued at: 1701432000
       Expires: 1701432060
     ```
@@ -216,6 +218,9 @@ When you call `verify_inbound()`, SimpleGuard checks:
 | **Not Expired** | `exp` > now | `Token expired` |
 | **Not Future** | `iat` <= now | `Token not yet valid` |
 
+!!! warning "Dev Mode Trust"
+    In `dev_mode=True`, the trust store is permissive — all valid Ed25519 signatures are accepted. The **Trust** check above only rejects untrusted keys when you have a configured trust store (i.e., keys in `capiscio_keys/trusted/`) or when using the `CapiscioMiddleware`. See [Step 4: Test Enforcement](4-test.md) for an example that demonstrates trust rejection via the middleware.
+
 ---
 
 ## Managing the Trust Store

docs/getting-started/validate/2-install.md

@@ -25,7 +25,7 @@ The CapiscIO CLI is available for Node.js and Python. Choose your preferred plat
 
     Expected output:
     ```
-    capiscio/{{ capiscio_version }} (darwin-arm64)
+    capiscio version {{ capiscio_version }} (commit: <hash>)
     ```
 
 === "pip (Python)"
@@ -42,7 +42,7 @@ The CapiscIO CLI is available for Node.js and Python. Choose your preferred plat
 
     Expected output:
     ```
-    capiscio/{{ capiscio_version }} (darwin-arm64)
+    capiscio version {{ capiscio_version }} (commit: <hash>)
     ```
 
 === "Go (Direct)"

docs/getting-started/validate/3-validate.md

@@ -21,6 +21,7 @@ First, grab our sample agent card:
   "description": "A helpful AI assistant",
   "url": "https://my-agent.example.com",
   "version": "1.0.0",
+  "protocolVersion": "{{ protocol_version }}",
   "capabilities": {
     "streaming": true,
     "pushNotifications": false