HYBIM-948 refresh README and changelog for first Splunk AO release

[pradystar]

Summary

Refresh the README and changelog for the first Splunk AO Python SDK release, covering standalone and O11y configuration and the SDK’s OTLP based telemetry behavior.

Why

The existing documentation described legacy Galileo behavior and did not accurately explain current routing, lifecycle, batching, authentication, diagnostics, and OpenTelemetry integration requirements.

What changed

• Documented standalone and O11y installation, authentication, and routing.
• Added Agent Stream name/ID guidance and routing precedence.
• Documented service naming and reserved routing Resource attributes.
• Clarified @log, handler, manual logger, flush(), terminate(), and provider shutdown behavior.
• Added standard OpenTelemetry instrumentation and custom exporter examples.
• Documented export diagnostics and session behavior for both deployments.
• Corrected dataset and experiment examples.
• Reset the changelog for the first Splunk AO release.

Documentation corrections

• Updated the main, A2A, and ADK setup guidance to use SPLUNK_AO_O11Y_TOKEN and SPLUNK_AO_O11Y_API_TOKEN.
• Simplified general routing documentation to use Project and Agent Stream names; ID routing remains documented only where Agent Control requires it.
• Reset the A2A and ADK changelogs for their first Splunk AO releases.
• Clarified that the generated low-level API client does not read SDK environment variables or perform deployment-aware configuration.

Tests

Validated 23 Python examples, 9 shell examples, 76 focused tests.

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: request_changes — The new "Export diagnostics" docs describe a public attribute (processor.export_health) and rejection/recovery/logger behavior that do not exist in the source.

[pradystar]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: request_changes — The new "Export diagnostics" docs describe a public attribute (processor.export_health) and rejection/recovery/logger behavior that do not exist in the source.

@fercor-cisco This branch now includes all missing changes from other PRs. Please check. Thank you :).

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: approve — Documentation-only PR; all documented APIs, env vars, and behaviors verified accurate against the source.

Follow-ups

Suggested follow-up work that could be tracked as Jira tickets:

• README.md:295-311: The OpenAI streaming example (pre-existing, outside this PR's edits) does not call flush() or terminate(). In a finite script the completed span may never be exported before the process exits, unlike the other examples in this refresh which now consistently show explicit flush()/terminate(). Consider aligning it with the new guidance in a later pass.
• src/splunk_ao/decorator.py:1404-1415: The docstring for splunk_ao_context.init() still documents a 'log_stream' parameter that no longer exists (the parameter is 'agent_stream'). This source docstring is out of scope for a docs PR but is now inconsistent with the README's Agent Stream terminology and could be updated for consistency.

[fercor-cisco]

Filed follow-up stories under epic HYBIM-697 for the review items deferred from this PR:

• HYBIM-953 — Align the OpenAI streaming README example (README.md:295-311) with the new flush()/terminate() guidance so all examples are consistent.
• HYBIM-954 — Fix the stale log_stream parameter in the splunk_ao_context.init() docstring (src/splunk_ao/decorator.py:1404-1415); it should reference agent_stream.