docs(examples): add explain_decision example [skip-runtime-e2e]

[saurabhjain1592]

Closes the example-parity gap: client.explain_decision() shipped in April but no runnable example existed. Mirror the Rust SDK pattern (axonflow-sdk-rust#29 / commit 2360282) so a caller can copy a complete demo without reading the SDK source.

Scope

• New examples/explain_decision.py (sibling of quickstart.py).
• Reads AXONFLOW_DECISION_ID from env, calls await client.explain_decision(...), prints every ADR-043 field: matched policies, matched rules, decision, reason, risk level, override availability, historical hit count.
• Defaults AXONFLOW_CLIENT_ID to community (the cross-SDK Basic-auth default).

Three-rule definition of done

Rule 0 — Runtime proof. Live run against the local community stack at localhost:8080 (agent v7.7.0 / orchestrator v7.7.0):

Step 1 — trigger a real decision via curl (yields decision_id=7a4876eb-3fd5-4467-a412-b0b42833e165, policy sys_sqli_drop_table, risk critical).

Step 2 — explain via the new Python example (using .venv/bin/python since the SDK requires Python 3.10+ for PEP 604 union syntax in axonflow/masfeat.py):

AXONFLOW_AGENT_URL=http://localhost:8080 \
AXONFLOW_CLIENT_ID=community \
AXONFLOW_CLIENT_SECRET="" \
AXONFLOW_DECISION_ID=7a4876eb-3fd5-4467-a412-b0b42833e165 \
.venv/bin/python examples/explain_decision.py

Output:

Initializing AxonFlow client at http://localhost:8080...
Explaining decision 7a4876eb-3fd5-4467-a412-b0b42833e165...

=== Decision Explanation ===
  decision_id: 7a4876eb-3fd5-4467-a412-b0b42833e165
  timestamp:   2026-05-07T12:16:36.779420+00:00
  decision:    deny
  reason:      Detects DROP TABLE statement
  risk_level:  critical

  policy_matches (1):
    [0] sys_sqli_drop_table (DROP TABLE Statement) — action=- risk=critical allow_override=False

  override_available:           False
  historical_hit_count_session: 0

Rule 1 — Self-review. Hunk-by-hunk:

• Field accesses match axonflow/decisions.py exactly: decision_id, timestamp, decision, reason, risk_level, tool_signature, policy_matches[{policy_id, policy_name, action, risk_level, allow_override}], matched_rules, override_available, override_existing_id, historical_hit_count_session, policy_source_link. ✓
• async with AxonFlow(...) as client: pattern matches quickstart.py style. ✓
• Risk_level + tool_signature + override_existing_id + policy_source_link are guarded with ifs before printing — they're optional in the schema. ✓
• matched_rules is list | None in the schema; the if exp.matched_rules: guard handles both null and empty correctly. ✓

Rule 2 — No deferred bugs. None found in path. The example runs cleanly against the v7.7.0 platform.

⛔ Do not merge — V1.1 release window

Per the feedback_v1_1_no_merge_during_release_window.md guideline. V1.1 is the next coordinated release train; nothing lands on main across V1.1-related PRs until the user explicitly authorizes the V1.1 release.

Skip-runtime-e2e justification

This SDK PR is runtime-tested by the repo's existing integration.yml workflow, which brings up the AxonFlow community stack via docker compose and runs every example end-to-end against it. Adding a parallel runtime-e2e/<feature>/ subdir would duplicate that flow without adding signal.

Manual runtime proof for this PR (live stack, command + wire dump) is captured in the PR body above. The community-stack integration.yml run on this branch is the automated equivalent.

Pattern matches the existing Rust SDK convention where examples double as runtime tests (axonflow-sdk-rust commit 2360282).

[saurabhjain1592]

⛔ Do not merge — V1.1 release window. Per feedback_v1_1_no_merge_during_release_window.md.