[docs] Update documentation for features from 2026-04-26

docs/src/content/docs/reference/audit.md

@@ -80,6 +80,9 @@ The Metrics section includes an `ambient_context` object when available. Ambient
 - MCP tool invocation changes (new/removed tools, call count and error count diffs)
 - Run metrics comparison (token usage, duration, turns)
 - Token usage breakdown: input tokens, output tokens, cache read/write tokens, effective tokens, total API requests, and cache efficiency per run
+- Tokens per turn: effective tokens divided by turn count for each run, with the change between runs
+- Tool call breakdown: per-tool call counts (new, removed, and changed tools) with max input/output sizes
+- Bash command breakdown: aggregated call counts and max input/output sizes for each distinct bash command invoked
 
 **Diff output behavior with multiple comparisons:**
 - `--json` outputs a single object for one comparison, or an array for multiple

docs/src/content/docs/reference/cache-memory.md

@@ -113,6 +113,7 @@ You can also trigger cleanup manually from the GitHub Actions UI by running the
 - **Files not persisting**: Check cache key consistency and logs for restore/save messages.
 - **File access issues**: Create subdirectories first, verify permissions, use absolute paths.
 - **Cache size issues**: Track growth, clear periodically, or use time-based keys for auto-expiration.
+- **Cache path misconfiguration**: When the agent calls `missing_data` with `reason: "cache_memory_miss"`, the conclusion handler automatically opens a failure issue flagging a likely cache path problem. Check that the agent prompt references the correct path (`/tmp/gh-aw/cache-memory/` by default, or `/tmp/gh-aw/cache-memory-{id}/` for named caches) and that the cache key is consistent across runs.
 
 ## Integrity-Aware Caching
 

docs/src/content/docs/reference/frontmatter.md

@@ -832,6 +832,71 @@ cache:
     node-modules-
 ```
 
+## Observability (`observability:`)
+
+The `observability.otlp` field exports distributed traces from workflow runs to any [OpenTelemetry](https://opentelemetry.io/) Protocol (OTLP) compatible backend such as Honeycomb, Grafana Tempo, or Sentry.
+
+```yaml wrap
+observability:
+  otlp:
+    endpoint: ${{ secrets.OTLP_ENDPOINT }}
+    headers:
+      Authorization: ${{ secrets.OTLP_TOKEN }}
+      X-Tenant: my-org
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `observability.otlp.endpoint` | string | OTLP/HTTP collector endpoint URL (e.g. `https://traces.example.com:4318`). Supports GitHub Actions expressions. When a static URL is provided, its hostname is automatically added to the network firewall allowlist. |
+| `observability.otlp.headers` | map or string | HTTP headers sent with every OTLP export request. |
+
+### `observability.otlp.headers`
+
+The `headers` field accepts two forms:
+
+**Map form (preferred)** — define each header as a key/value pair:
+
+```yaml wrap
+observability:
+  otlp:
+    endpoint: ${{ secrets.OTLP_ENDPOINT }}
+    headers:
+      Authorization: ${{ secrets.OTLP_TOKEN }}
+      X-Tenant: acme
+```
+
+**String form (deprecated)** — comma-separated `key=value` pairs. Use the map form instead:
+
+```yaml wrap
+observability:
+  otlp:
+    endpoint: ${{ secrets.OTLP_ENDPOINT }}
+    headers: "Authorization=${{ secrets.OTLP_TOKEN }},X-Tenant=acme"
+```
+
+> [!NOTE]
+> Using the string form emits a deprecation warning. Migrate to the map form to suppress it.
+
+### Agent span attributes
+
+The agent span (`gh-aw.agent.agent`) uses [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) and is emitted as a `SPAN_KIND_CLIENT` span. The following attributes are set on the agent span:
+
+| Attribute | Description |
+|-----------|-------------|
+| `gen_ai.request.model` | Model name used for inference |
+| `gen_ai.operation.name` | Always `"chat"` |
+| `gen_ai.provider.name` | Engine identifier (e.g. `copilot`, `claude`) |
+| `gen_ai.workflow.name` | Workflow name |
+| `gen_ai.usage.input_tokens` | Total input tokens consumed |
+| `gen_ai.usage.output_tokens` | Total output tokens produced |
+| `gen_ai.usage.cache_read.input_tokens` | Cache-read tokens reused |
+| `gen_ai.usage.cache_creation.input_tokens` | Cache-creation tokens written |
+
+> [!NOTE]
+> Prior to v0.70, the agent span used private `gh-aw.*` attribute names (`gh-aw.model`, `gh-aw.tokens.input`, etc.) and `SPAN_KIND_INTERNAL`. These attributes were removed and replaced with the `gen_ai.*` convention above. Update any dashboards or alert rules that reference the old attribute names.
+
 ## Related Documentation
 
 See also: [Trigger Events](/gh-aw/reference/triggers/), [AI Engines](/gh-aw/reference/engines/), [CLI Commands](/gh-aw/setup/cli/), [Workflow Structure](/gh-aw/reference/workflow-structure/), [Network Permissions](/gh-aw/reference/network/), [Command Triggers](/gh-aw/reference/command-triggers/), [MCPs](/gh-aw/guides/mcps/), [Tools](/gh-aw/reference/tools/), [Imports](/gh-aw/reference/imports/)

docs/src/content/docs/setup/cli.md

@@ -453,7 +453,7 @@ gh aw audit 12345 12346 --json              # JSON for CI integration
 gh aw audit 12345 12346 --repo owner/repo   # Specify repository
 ```
 
-The diff output shows: new or removed network domains, status changes (allowed ↔ denied), volume changes (>100% threshold), MCP tool invocation changes, and run metric comparisons (token usage, duration, turns).
+The diff output shows: new or removed network domains, status changes (allowed ↔ denied), volume changes (>100% threshold), MCP tool invocation changes, run metric comparisons (token usage, duration, turns), tokens-per-turn changes, and per-tool and per-bash-command call breakdowns.
 
 **Options:** `--format` (pretty, markdown; default: pretty), `--json`, `--repo/-r`