Merge remote-tracking branch 'origin/dev' into codex/issue-161-skill-self-evolution

# Conflicts:
#	docs/project-changelog.md

docs/10-tracing-observability.md

@@ -187,7 +187,10 @@ worker.Stop()
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/v1/traces` | List traces with pagination and filters |
+| GET | `/v1/traces/follow` | Poll trace changes for one session or agent |
 | GET | `/v1/traces/{id}` | Get trace details with all spans |
+| GET | `/v1/traces/{id}/export` | Export a gzipped trace tree with spans and sub-traces |
+| GET | `/v1/runs/{runID}/timeline` | Get persisted run archive timeline items |
 
 ### Query Filters
 
@@ -210,6 +213,35 @@ worker.Stop()
 | `limit` | int | Page size (default 50) |
 | `offset` | int | Pagination offset |
 
+### Operator CLI
+
+The main `goclaw` binary can also act as a thin operator client for trace
+inspection:
+
+```bash
+goclaw traces list --status error --limit 20
+goclaw traces get <trace-id> -o json
+goclaw traces export <trace-id> --file trace.json.gz
+goclaw traces follow --session <session-key> --since 2026-06-12T01:00:00Z
+goclaw traces timeline <trace-id>
+```
+
+By default, commands use the same local gateway config and
+`GOCLAW_GATEWAY_TOKEN` behavior as existing admin commands. For remote
+operations, use explicit overrides:
+
+```bash
+goclaw --server https://goclaw.example.com --token "$GOCLAW_GATEWAY_TOKEN" traces get <trace-id> -o json
+```
+
+`--server` also applies to existing WebSocket/RPC-backed admin commands such as
+`sessions`, `cron`, and `pairing`. The URL can also come from `GOCLAW_SERVER`
+or `GOCLAW_GATEWAY_URL`; `--server` wins when both are set.
+
+The standalone `nextlevelbuilder/goclaw-cli` can remain a compatibility tool,
+but first-party trace operator workflows are now available from the main
+server/runtime binary.
+
 ---
 
 ## 8. Delegation History

docs/18-http-api.md

@@ -1423,6 +1423,26 @@ Follow response:
 }
 ```
 
+Main binary operator commands wrap the same endpoints:
+
+```bash
+goclaw traces list --query "provider fail" --status error
+goclaw traces get <trace-id> -o json
+goclaw traces export <trace-id> --file trace.json.gz
+goclaw traces follow --session <session-key>
+goclaw traces timeline <trace-id>
+```
+
+Remote gateways use the shared client overrides:
+
+```bash
+goclaw --server https://goclaw.example.com --token "$GOCLAW_GATEWAY_TOKEN" traces list -o json
+```
+
+The same `--server` / `--token` resolver is shared with WebSocket/RPC-backed
+admin commands. `GOCLAW_SERVER` or `GOCLAW_GATEWAY_URL` can provide the base URL
+when the flag is omitted.
+
 ### Run Timeline
 
 `GET /v1/runs/{runID}/timeline` returns display-safe archive entries for one

docs/project-changelog.md

@@ -6,6 +6,24 @@ Significant changes, features, and fixes in reverse chronological order.
 
 ## 2026-06-12
 
+### Operator trace CLI (issue #158)
+
+**Changes**
+
+- Added first-class `goclaw traces` operator commands to the main binary:
+  `list`, `get`, `export`, `follow`, and `timeline`.
+- Added remote client overrides with `--server` and `--token`; trace commands
+  support trace-scoped output selection via `--output` / `-o`.
+- Shared the URL/token resolver with WebSocket/RPC-backed admin commands so
+  `sessions`, `cron`, and `pairing` can use the same remote gateway overrides.
+- Kept trace commands as thin wrappers over existing HTTP endpoints so the
+  server/runtime and operator CLI share one binary without new API contracts.
+
+**Tests**
+
+- Added command/client regressions for gateway URL and token overrides, trace
+  query serialization, follow scope validation, and timeline run ID handling.
+
 ### Skill self-evolution metrics and upgrades (issue #161, issue #142 foundation)
 
 **Features**