[vernonstinebaker]

Documents two conventions discovered while validating #48 end-to-end against a live nullclaw v0.3.0 worker (details in #53):

1. A2A worker URL is the base URL — the dispatcher appends /a2a itself; a full-path URL (http://host:3000/a2a) produces POST /a2a/a2a and a bare HTTP 404 with no hint. Captured via netcat.
2. transition_to is applied as the FSM trigger name — a trigger that doesn't exist on the task's current stage is rejected and the task re-enters retry.

Docs-only; no code changes.

[DonPrus]

The A2A base-URL warning is useful and matches worker_protocol.buildRequestUrl, its trailing-slash tests, and the existing A2A worker in config.example.json. I checked the request builder and response parser as well: message/send, kind and messageId match the implementation. No other active A2A configuration example contains the erroneous /a2a suffix, and the docs merge cleanly with current main.

Two non-blocking precision improvements would be great:

• Qualify the failure-transition paragraph: on_success.transition_to is passed as the FSM trigger, but current Tracker.driveFailed never consumes on_failure.transition_to; it calls failRun after retry handling. #52 was closed without merging. The same wording also appears in #55, so please keep the two documents consistent and label failure transitions as an existing implementation gap.
• The response parser currently reads result.parts[0].text or result.artifacts[0].parts[0].text, not every text part. Using those exact paths would avoid implying that multi-part replies are combined.

Approving the documentation improvement with these clarifications; no code regression or merge conflict found.

[vernonstinebaker]

Both non-blocking improvements addressed in 0f17be0:

1. Failure-transition paragraph qualified. Split into two statements:

• on_success.transition_to is what is actually passed as the FSM trigger name.
• on_failure.transition_to is now labelled an existing implementation gap — parsed, never consumed; Tracker.driveFailed calls failRun directly after retry handling, so no failure transition fires (fix(tracker): apply the workflow's on_failure transition when a dispatch fails #52, closed without merge). Ends with "treat failure transitions as the intended contract, not current behavior".

Kept consistent with #55, which has since merged with matching AGENTS.md wording (intended contract / parsed but not yet applied, plus a Known-gaps entry).

2. Response-parser paths made exact. parts[].text / artifacts[].parts[].text → result.parts[0].text falling back to result.artifacts[0].parts[0].text, with an explicit note that only the first part is read and multi-part replies are not combined. Verified against src/dispatch.zig (parseA2aResponse: the parts branch returns on items[0], then the legacy artifacts branch returns on artifacts[0].parts[0]).

Validation — merge result c7375127 (base = current main 80956d51, includes #58): zig build test --summary all 370/370, zig fmt --check src/ OK, run in a Linux container. Merge vs main touches only docs/multi-bot-integration.md (+28/-0). All 4 CI checks pass.

Approval retained.