[docs] Document max payload size for workflow webhook submissions + 413 response shape

[B2JK-Industry]

Friction

Building sbo3l-keeperhub-adapter, the IP-1 envelope our adapter POSTs to a workflow webhook (crates/sbo3l-keeperhub-adapter/src/lib.rs#L235-L289) carries:

• agent_id (~32 bytes)
• intent (~16 bytes)
• The full IP-1 envelope: request_hash, policy_hash, audit_event_id, receipt_signature (Ed25519 hex, 128 bytes), policy_version (~16 bytes)
• The original APRP body (~1-4 KB depending on destination shape)

Total typical envelope: 2-6 KB. We've never hit a size error in testing. But:

• We don't know what KH's max body size IS
• We don't know if it varies per workflow tier (free / paid / enterprise)
• We don't know the response shape for "too large" — is it 413 Payload Too Large per HTTP spec, or a custom 422 with a domain error?

This blocks adapter authors who want to carry richer evidence in the envelope. For example, issue #50 proposes optional sbo3l_passport_uri plus the full encoded passport capsule (~16-50 KB depending on destination chain proofs). Today we strip the capsule from the envelope and pass only the URI — but the URI alone is a backward step from "self-contained verifiable evidence" to "trust-the-server-still-has-the-bytes."

Reproduction

# What we tried during integration:
# Submit envelope with large optional `audit_evidence` payload (~10KB):
PAYLOAD_10K=$(python3 -c "print('{\"a\":\"' + 'x'*10000 + '\"}')")
curl -i \
  -H "Authorization: Bearer wfb_<token>" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD_10K" \
  "https://app.keeperhub.com/api/workflows/<id>/webhook"
# → 200 OK. So <10K is fine.

# Same with 100KB:
PAYLOAD_100K=$(python3 -c "print('{\"a\":\"' + 'x'*100000 + '\"}')")
curl -i ... -d "$PAYLOAD_100K"
# → ?  We didn't risk breaking the live workflow with arbitrary-size testing.

# What we actually need to know: where's the cliff, and what's the
# error response shape at the cliff.

Proposed fix

Document the limit in two places:

1. Workflow webhook docs

Body size limit:        1 MB (per webhook submit)
Excess response:        413 Payload Too Large
                        Content-Type: application/json
                        Body: {"error": "kh.envelope.too_large",
                               "limit_bytes": 1048576,
                               "received_bytes": <actual>}
Per-tier override:      Enterprise tier — 10 MB on request to support@keeperhub.com

2. Webhook config UI

Show the per-workflow effective limit alongside the workflow's webhook URL + token. Adapter authors copying the URL also get the contract they're agreeing to.

3. Optional but valuable — a Content-Length preflight

If KH's gateway rejects oversize bodies before reading them (which is what nginx / cloud LBs do), document that explicitly so adapter authors know to:

• Compute envelope size before POSTing
• Surface a typed EnvelopeTooLarge { limit, actual } error to their callers immediately
• Avoid wasted upload bandwidth on a guaranteed-fail submit

Reference PR draft (consumer side)

B2JK-Industry/SBO3L-ethglobal-openagents-2026 PR — branch agent/dev2/kh-bf-additional-pr-draft-5: shows our adapter (a) computing envelope size pre-POST, (b) returning ExecutionError::EnvelopeTooLarge { limit_bytes, actual_bytes } when over the documented limit, (c) embedding the full passport capsule in sbo3l_passport_capsule_b64 when under the limit and sbo3l_passport_uri (with the capsule served separately) when over. This unlocks the "fully self-contained evidence" path requested in issue #50.

Why this matters for KH

Adapter authors today either guess conservative (truncate evidence, lose verifiability) or guess generous (risk runtime failures with no clear contract). A documented limit lets the adapter ecosystem make principled tradeoffs and lets KH's platform team plan capacity.

This is also a prerequisite for the rich-evidence path in issue #50 (sbo3l_* upstream fields). Without a documented size budget, adapter authors won't know whether to embed passport capsules inline or by URI.

Context

• Filed as part of SBO3L's KeeperHub Builder Feedback submission for ETHGlobal Open Agents 2026
• Related: [feature] First-class upstream policy/audit fields on action submission envelope #50 (sbo3l_* upstream fields — payload size determines whether evidence can be inline)
• Related: [docs] Publish JSON schema for action submission/result envelope #48 (envelope schema — size limit becomes one of the schema's documented constraints)