docs: refresh planner priorities for 4053

Co-authored-by: Codex <codex@openai.com>

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: true
 contact_links:
+  - name: 🔒 Report a vulnerability
+    url: https://github.com/micro/go-micro/security/advisories/new
+    about: Privately disclose security vulnerabilities to the maintainers.
   - name: 💖 Sponsor Go Micro
     url: https://github.com/sponsors/asim
     about: Fund ongoing development and see your name or logo on the project.

.github/loop/PRIORITIES.md

@@ -21,8 +21,7 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Trace agent `RunInfo` into OpenTelemetry spans** ([#3867](https://github.com/micro/go-micro/issues/3867)) — #3857/#3865 closed the streaming queue item, there are no open `codex` PRs in flight, and the remaining Next-phase gap with the strongest mission fit is operability of the services → agents → workflows lifecycle. The README, website, roadmap, and recent blog all promise that agents are services you can run, chat with, inspect, and trust under the same runtime; projecting run steps, tool calls, delegation, streaming, cancellation, and errors into OTel spans makes that lived path debuggable without a public-API rewrite. Keep this additive/no-op when tracing is disabled, with tests proving representative `RunInfo` events become trace data.
-2. **Add an AP2 mandate layer over A2A and x402** ([#3552](https://github.com/micro/go-micro/issues/3552)) — this remains a forward interop investment, not a Now/Next blocker: Go Micro already has A2A agents and x402 paid tools, so a small signed-mandate foundation can keep agent payments aligned with the open-protocol story without pulling the queue ahead of adoption, resilience, streaming, or durable agent operation. Keep it additive and opt-in while the AP2/FIDO work settles.
+1. **Lead Getting Started with the no-secret first-run path** ([#4054](https://github.com/micro/go-micro/issues/4054)) — #4039 added `micro agent demo`, #4044 documented it in the README/website on-ramp, #4049 moved the installed CLI docs to lead with it, and #4052 surfaced it from scaffold next steps. The remaining adoption seam is the website Getting Started page: it still introduces provider-key setup and prompt generation before the no-secret scaffold → run → call path, so a new developer can infer an LLM key is mandatory before they have proved the runtime works. Reorder Getting Started to lead with install → `micro new` → `micro run` → curl, then `micro agent demo` and the no-secret first-agent sequence, and add a focused docs/harness assertion so the README, CLI docs, and website cannot drift apart again.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

.github/loop/prompts/security.md

@@ -0,0 +1,30 @@
+<!--
+The SECURITY prompt — go-micro's security audit. Editable policy; the workflow
+prepends the agent @mention and substitutes __ISSUE__ before posting. Keep
+__ISSUE__ literal.
+
+Deliberately conservative: it does NOT auto-merge fixes, and it does NOT publish
+exploit details in public issues (responsible disclosure).
+-->
+Act as the security reviewer for go-micro. Audit for real, exploitable vulnerabilities — skip theoretical or lint-style noise.
+
+GO-MICRO ATTACK SURFACE — weight these:
+- **MCP gateway** (`gateway/mcp`) and **A2A gateway** (`gateway/a2a`) — untrusted input from agents/tools: auth/scope enforcement, injection into downstream RPC, SSRF via tool/agent URLs, rate-limit/circuit-breaker bypass, info leak in errors.
+- **x402 payments** (`wrapper/x402`) — payment verification and settlement: signature/mandate validation, replay, budget-reservation races, facilitator auth (CDP bearer) handling, amount/network confusion.
+- **Auth** (`auth/jwt`, `wrapper/auth`) — token validation, algorithm confusion, scope/priority rule bypass, missing checks on endpoints.
+- **AI providers** (`ai/*`) — base-URL and endpoint handling: SSRF via config-controlled `BaseURL`, API keys leaking into logs/errors, TLS verification.
+- **Agent tool loop** (`agent/`) — prompt injection reaching real tool calls, guardrail (`MaxSteps`/`LoopLimit`/`ApproveTool`) bypass, delegate/plan side effects.
+- **Trust boundaries** — `server` RPC handlers, `broker` consumers, `store`/`registry` inputs, `transport` TLS defaults (v6 verifies by default — confirm nothing regressed).
+- **The loop itself** — `.github/workflows/loop-*.yml`: the `CODEX_TRIGGER_TOKEN` PAT must never be echoed/leaked; workflow inputs must not enable script injection.
+- **Dependencies** — run `govulncheck ./...` (install if needed) and inspect `go.mod` for known CVEs.
+
+DEDUPE against open issues first.
+
+HOW TO REPORT:
+- **Known/public dependency CVEs**: file a `security` issue referencing the CVE + module; you MAY open a PR bumping to the patched version. Do NOT enable auto-merge.
+- **Novel, exploitable vulnerabilities in this code** (not yet public): do NOT post an exploit or PoC in a public issue. File a CONCISE `security` + `needs-human` issue naming the class, location (file/function), and impact only — and note it should go through GitHub private vulnerability reporting. Do NOT open a public fix PR that reveals it.
+- **Low-risk hardening**: a normal `security` issue is fine.
+
+NEVER auto-merge a security change. Never weaken a control to make a test pass. Architectural/breaking fixes → `needs-human` with the tradeoff.
+
+Post a summary as a comment on this issue (#__ISSUE__) — findings by severity, what you filed, what needs a human — then close it (`gh issue close __ISSUE__`). If you open a dependency-bump PR: `git switch -c loop/security-__ISSUE__`, `git push -u origin loop/security-__ISSUE__`, `gh pr create --base master --label codex --label security --title "<title>" --body "<summary, Closes #__ISSUE__>"` — then STOP, do NOT run `gh pr merge --auto`. Do not use the make_pr tool.

.github/workflows/loop-security.yml

@@ -0,0 +1,60 @@
+name: "Loop: Security"
+
+# Generated by `micro loop init`. A dispatch role of the autonomous loop: on a
+# cadence it opens a fresh tracking issue and posts the instruction in
+# .github/loop/prompts/security.md to the agent (@codex).
+#
+# The workflow is the MECHANISM; that prompt file is the editable POLICY —
+# change what this role does by editing the prompt, not this YAML. A FRESH
+# issue per run is deliberate: agents derive the PR branch name from the
+# triggering issue, so reusing one tracker collapses every run onto one branch.
+#
+# Gated on CODEX_TRIGGER_TOKEN: the agent ignores @mentions from the
+# github-actions bot, so dispatch posts as a real user (a PAT). No token → no-op.
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  issues: write
+
+concurrency:
+  group: loop-security
+  cancel-in-progress: false
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4 # needed to read the prompt file
+      - name: Dispatch security
+        env:
+          GH_TOKEN: ${{ secrets.CODEX_TRIGGER_TOKEN || github.token }}
+          HAS_TOKEN: ${{ secrets.CODEX_TRIGGER_TOKEN != '' }}
+          REPO: ${{ github.repository }}
+          RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          if [ "$HAS_TOKEN" != "true" ]; then
+            echo "CODEX_TRIGGER_TOKEN is not set — skipping (the agent ignores bot @mentions)."
+            exit 0
+          fi
+          PROMPT=".github/loop/prompts/security.md"
+          if [ ! -f "$PROMPT" ]; then
+            echo "missing $PROMPT — run 'micro loop init'." >&2
+            exit 1
+          fi
+          ISSUE_URL=$(gh issue create --repo "$REPO" \
+            --title "Loop: security review #$RUN_NUMBER" \
+            --body "Autonomous security pass. Direction: .github/loop/NORTH_STAR.md; queue: .github/loop/PRIORITIES.md.")
+          ISSUE_NUM="${ISSUE_URL##*/}"
+          echo "Opened issue #$ISSUE_NUM — dispatching security."
+          # The prompt file is the policy; strip its editorial <!-- --> header and
+          # substitute the tracking issue number (__ISSUE__) at runtime.
+          {
+            echo "@codex"
+            echo
+            sed -e '/<!--/,/-->/d' -e "s/__ISSUE__/$ISSUE_NUM/g" "$PROMPT"
+          } > "$RUNNER_TEMP/loop-body.md"
+          gh issue comment "$ISSUE_NUM" --repo "$REPO" --body-file "$RUNNER_TEMP/loop-body.md"

CHANGELOG.md

@@ -16,12 +16,46 @@ next version when it ships.
 
 ## [Unreleased]
 
+## [6.3.15] - July 2026
+
+### Added
+- **Anthropic streaming** — the Anthropic provider now supports Messages SSE streaming and is registered as a streaming-capable provider, with capability docs and parser coverage. (`ai/anthropic/`, `internal/website/docs/guides/`)
+- **AP2 mandate foundation for A2A** — the A2A gateway now has the shared payment-mandate foundation needed for AP2-style agent payment flows. (`gateway/a2a/`)
+- **Smallest first-agent example** — a no-secret, mock-model first-agent example gives the on-ramp a minimal runnable starting point. (`examples/first-agent/`)
+
+### Changed
+- **First-agent CLI next steps** — CLI output now points new users toward the maintained first-agent path after scaffold/run milestones. (`cmd/micro/`)
+
+### Fixed
+- **Plan/delegate completion** — plan-delegate runs now preserve completed steps, guard ordering, require notify-before-completion, and stabilize checkpoint continuation paths. (`agent/`, `internal/harness/`)
+- **Provider text tool calls** — AtlasCloud and weaker-model fallback paths now recover tagged, `Create`-suffixed, mixed text/tool-call, and follow-up tool calls more reliably. (`agent/`, `ai/atlascloud/`)
+- **First-agent broker isolation** — the first-agent harness now isolates broker state more reliably across runs. (`internal/harness/`)
+
+### Documentation
+- **First-agent example path** — docs and website wayfinding now surface the smallest example, no-secret transcript, and 0→hero path together. (`README.md`, `internal/website/docs/`)
+- **Agent operations guidance** — agent debugging docs now include operational failure guidance, inspect hints, and durable resume pointers. (`internal/website/docs/guides/`)
+
+---
+
+## [6.3.14] - July 2026
+
 ### Added
 - **MiniMax provider** — run agents against MiniMax's `MiniMax-M3` model via its OpenAI-compatible endpoint, with tool calling and streaming; auto-detected from the base URL. (`ai/minimax/`)
+- **`micro loop` security role** — a new opt-in loop role (`--roles …,security`) that periodically audits a repo for vulnerabilities and files `security` issues. It is deliberately conservative: it never auto-merges fixes and never publishes exploit detail in public issues (responsible disclosure), and risky fixes are marked `needs-human`. go-micro now runs it against its own attack surface (MCP/A2A gateways, x402, auth, provider URLs, agent tool loop, deps). (`cmd/micro/loop/`)
+- **Agent run tracing** — agent model streaming and run-event kinds now emit richer trace detail for debugging agent execution. (`agent/`)
+
+### Changed
+- **Agent memory** — streamed agent replies are persisted in conversation memory so later turns can reference streamed responses. (`agent/`)
 
 ### Fixed
 - **Plan/delegate completion** — agents now continue unfinished plan steps more reliably, fail checkpointed runs that leave delegated plans unfinished, recover from unknown plan-delegate tool calls, avoid duplicate side effects, and complete timeout paths deterministically. (`agent/`)
 - **AtlasCloud tool calls** — streaming and request fallback handling now recovers tool-call results from provider responses that omit the expected structured fields. (`ai/atlascloud/`)
+- **Agent preflight diagnostics** — provider setup failures now surface more actionable errors before an agent run starts. (`agent/`)
+- **A2A fallback streams** — fallback stream validation is stricter for malformed or incomplete A2A streaming responses. (`gateway/a2a/`)
+- **File-store test isolation** — file-store expiry and table tests are less timing-sensitive and isolate their state more reliably. (`store/file/`)
+
+### Documentation
+- **First-agent debugging path** — docs now include no-secret transcript checkpoints, durable resume examples, and clearer CLI/website wayfinding for first-agent debugging. (`README.md`, `internal/website/docs/`, `examples/agent-durable/`)
 
 ---
 

README.md

@@ -87,14 +87,16 @@ make harness
 After install and the first `micro new`/`micro run` smoke check, take the
 walkable agent path in this order:
 
-1. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
+1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
+2. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
+3. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
    maintained support agent with a mock model and see services → agents → workflows succeed without a key.
-2. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
+4. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
    service-backed agent and talk to it with `micro chat`.
-3. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
+5. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
    `micro agent inspect`, run history, memory, and provider checks when the first
    conversation does something unexpected.
-4. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
+6. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
    services → agents → workflows loop with scaffold, run, chat, inspect, flow
    history, and deploy dry-run commands that match the maintained harness.
 
@@ -439,9 +441,12 @@ resp, _ := m.Generate(ctx, &ai.Request{Prompt: "hello"})
 
 ## Examples
 
+New to agents? Follow the [first-agent on-ramp](#first-agent-on-ramp), then use the [examples index](examples/README.md) for the full services → agents → workflows map.
+
 - [hello-world](examples/hello-world/) — Basic RPC service
 - [multi-service](examples/multi-service/) — Multiple services in one binary
 - [mcp](examples/mcp/) — MCP integration with AI agents
+- [first-agent](examples/first-agent/) — Smallest provider-free service-backed agent
 - [agent-plan-delegate](examples/agent-plan-delegate/) — Agent planning and multi-agent delegation
 - [agent-durable](examples/agent-durable/) — Checkpoint and resume an agent run without replaying completed tool side effects
 - [grpc-interop](examples/grpc-interop/) — Call go-micro from any gRPC client

SECURITY.md

@@ -17,11 +17,11 @@ We actively support the following versions of go-micro:
 
 ### How to Report
 
-Send security vulnerability reports to: **security@go-micro.dev**
-
-Or use GitHub's private security advisory feature:
+Use GitHub's private security advisory feature:
 https://github.com/micro/go-micro/security/advisories/new
 
+This keeps vulnerability reports private, ties follow-up to the affected repository, and avoids relying on project email routing.
+
 ### What to Include
 
 Please include as much of the following information as possible:
@@ -175,5 +175,4 @@ We currently do not offer a bug bounty program, but we greatly appreciate respon
 For security questions that are not vulnerabilities, please:
 - Open a discussion: https://github.com/micro/go-micro/discussions
 - Join Discord: https://discord.gg/G8Gk5j3uXr
-- Email: support@go-micro.dev
 

agent/agent.go

@@ -297,7 +297,11 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 		}
 	}
 
-	const maxPlanCompletionTurns = 3
+	// Some providers satisfy a saved plan one outstanding item per turn,
+	// especially when the final item delegates to another agent. Allow enough
+	// continuations for the services → agents → workflows harness to complete
+	// every planned side effect without weakening the final unfinished-plan guard.
+	const maxPlanCompletionTurns = 6
 	var resp *ai.Response
 	for planCompletionTurn := 0; ; planCompletionTurn++ {
 		resp, err = ai.GenerateWithRetry(ctx, a.model, &ai.Request{
@@ -312,6 +316,7 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 		})
 		if err != nil {
 			run.Status = agentRunFailureStatus(err)
+			err = agentOperationalError(err)
 			if a.currentRun != nil {
 				run.Steps = a.currentRun.Steps
 			}
@@ -351,6 +356,15 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 					resp.Reply = ""
 				}
 			}
+		} else if calls, answer, ok := a.executeAdditionalTextToolCalls(ctx, resp.Reply, toolList, resp.ToolCalls); ok {
+			resp.ToolCalls = append(resp.ToolCalls, calls...)
+			if answer != "" {
+				if resp.Answer == "" {
+					resp.Answer = answer
+				} else {
+					resp.Answer += "\n" + answer
+				}
+			}
 		}
 
 		if a.opts.Checkpoint != nil {
@@ -361,7 +375,7 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 				if resp.Answer != "" {
 					a.mem.Add("assistant", resp.Answer)
 				}
-				message = "Continue the run. These plan steps are still unfinished and must be completed before a final answer: " + strings.Join(unfinished, ", ")
+				message = fmt.Sprintf("Continue the same run by calling the required tool(s) for the unfinished plan steps below. Do not repeat completed work, do not provide a final answer yet, and complete at least one unfinished step this turn if a matching tool is available. Unfinished plan steps: %s", strings.Join(unfinished, ", "))
 				a.mem.Add("user", message)
 				messages = a.mem.Messages()
 				continue
@@ -459,7 +473,7 @@ func (a *agentImpl) Run() error {
 		a.setup()
 	}
 
-	a.server = server.NewServer(
+	serverOpts := []server.Option{
 		server.Name(a.opts.Name),
 		server.Address(a.opts.Address),
 		server.Registry(a.opts.Registry),
@@ -467,7 +481,11 @@ func (a *agentImpl) Run() error {
 			"type":     "agent",
 			"services": strings.Join(a.opts.Services, ","),
 		}),
-	)
+	}
+	if a.opts.Broker != nil {
+		serverOpts = append(serverOpts, server.Broker(a.opts.Broker))
+	}
+	a.server = server.NewServer(serverOpts...)
 
 	_ = pb.RegisterAgentHandler(a.server, a)
 

agent/builtin.go

@@ -290,6 +290,11 @@ func (a *agentImpl) planWrap(next ai.ToolHandler) ai.ToolHandler {
 		if call.Name == toolPlan {
 			return a.handlePlan(call)
 		}
+		if call.Name == toolDelegate {
+			if blocked := a.unfinishedPlanStepsBeforeDelegation(); len(blocked) > 0 {
+				return refused(call.ID, ai.RefusedApproval, "complete these plan steps before delegating: "+strings.Join(blocked, ", "))
+			}
+		}
 		res := next(ctx, call)
 		if res.Refused == "" && toolErrorMessage(res) == "" {
 			a.completeNextPlanStep()
@@ -364,12 +369,74 @@ func (a *agentImpl) approveWrap(next ai.ToolHandler) ai.ToolHandler {
 // handlePlan persists the supplied plan to the agent's memory and
 // echoes it back so the model can see the stored state.
 func (a *agentImpl) handlePlan(call ai.ToolCall) ai.ToolResult {
-	data, err := json.Marshal(call.Input)
+	input := preserveCompletedPlanSteps(a.loadPlan(), call.Input)
+	data, err := json.Marshal(input)
 	if err != nil {
 		return errResult(call.ID, "invalid plan: "+err.Error())
 	}
 	_ = a.stateStore().Write(&store.Record{Key: planKey, Value: data})
-	return ai.ToolResult{ID: call.ID, Value: call.Input, Content: string(data)}
+	return ai.ToolResult{ID: call.ID, Value: input, Content: string(data)}
+}
+
+func preserveCompletedPlanSteps(stored string, input map[string]any) map[string]any {
+	if stored == "" {
+		return input
+	}
+	var previous map[string]any
+	if err := json.Unmarshal([]byte(stored), &previous); err != nil {
+		return input
+	}
+	completed := completedPlanTasks(previous)
+	if len(completed) == 0 {
+		return input
+	}
+	steps, ok := input["steps"].([]any)
+	if !ok {
+		return input
+	}
+	for _, raw := range steps {
+		step, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		task, _ := step["task"].(string)
+		if completed[normalizePlanTask(task)] && isUnfinishedPlanStatus(step["status"]) {
+			step["status"] = "done"
+		}
+	}
+	return input
+}
+
+func completedPlanTasks(plan map[string]any) map[string]bool {
+	steps, ok := plan["steps"].([]any)
+	if !ok {
+		return nil
+	}
+	completed := map[string]bool{}
+	for _, raw := range steps {
+		step, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		status, _ := step["status"].(string)
+		if status != "done" {
+			continue
+		}
+		task, _ := step["task"].(string)
+		if task = normalizePlanTask(task); task != "" {
+			completed[task] = true
+		}
+	}
+	return completed
+}
+
+func normalizePlanTask(task string) string {
+	return strings.Join(strings.Fields(strings.ToLower(task)), " ")
+}
+
+func isUnfinishedPlanStatus(status any) bool {
+	s, _ := status.(string)
+	return s == "" || s == "pending" || s == "in_progress"
 }
 
 func (a *agentImpl) completeNextPlanStep() {
@@ -402,6 +469,53 @@ func (a *agentImpl) completeNextPlanStep() {
 	}
 }
 
+func (a *agentImpl) unfinishedPlanStepsBeforeDelegation() []string {
+	plan := a.loadPlan()
+	if plan == "" {
+		return nil
+	}
+	var data map[string]any
+	if err := json.Unmarshal([]byte(plan), &data); err != nil {
+		return nil
+	}
+	steps, ok := data["steps"].([]any)
+	if !ok {
+		return nil
+	}
+	var unfinished []string
+	for _, raw := range steps {
+		step, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		task := planStepTask(step)
+		if isDelegationPlanTask(task) {
+			break
+		}
+		if !isUnfinishedPlanStatus(step["status"]) {
+			continue
+		}
+		if task == "" {
+			task = "<unnamed>"
+		}
+		unfinished = append(unfinished, task)
+	}
+	return unfinished
+}
+
+func planStepTask(step map[string]any) string {
+	if task, _ := step["task"].(string); task != "" {
+		return task
+	}
+	desc, _ := step["description"].(string)
+	return desc
+}
+
+func isDelegationPlanTask(task string) bool {
+	task = normalizePlanTask(task)
+	return strings.Contains(task, "delegate") || strings.Contains(task, "notify") || strings.Contains(task, "notification")
+}
+
 func (a *agentImpl) unfinishedPlanSteps() []string {
 	plan := a.loadPlan()
 	if plan == "" {
@@ -425,7 +539,7 @@ func (a *agentImpl) unfinishedPlanSteps() []string {
 		if status != "" && status != "pending" && status != "in_progress" {
 			continue
 		}
-		task, _ := step["task"].(string)
+		task := planStepTask(step)
 		if task == "" {
 			task = "<unnamed>"
 		}

agent/builtin_test.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"context"
 	"encoding/json"
 	"testing"
 
@@ -52,6 +53,32 @@ func TestHandlePlanPersists(t *testing.T) {
 	}
 }
 
+func TestHandlePlanPreservesCompletedSteps(t *testing.T) {
+	mem := store.NewMemoryStore()
+	a := New(Name("planner"), WithStore(mem)).(*agentImpl)
+
+	a.handlePlan(ai.ToolCall{Name: "plan", Input: map[string]any{
+		"steps": []any{
+			map[string]any{"task": "create Design task", "status": "done"},
+			map[string]any{"task": "Delegate readiness notification to comms agent", "status": "done"},
+		},
+	}})
+
+	res := a.handlePlan(ai.ToolCall{Name: "plan", Input: map[string]any{
+		"steps": []any{
+			map[string]any{"task": "create Design task", "status": "done"},
+			map[string]any{"task": "  delegate   readiness notification TO comms agent  ", "status": "in_progress"},
+			map[string]any{"task": "write summary", "status": "pending"},
+		},
+	}})
+	if res.Content == "" {
+		t.Fatal("handlePlan returned empty content")
+	}
+	if unfinished := a.unfinishedPlanSteps(); len(unfinished) != 1 || unfinished[0] != "write summary" {
+		t.Fatalf("unfinished plan steps = %v, want only write summary", unfinished)
+	}
+}
+
 func TestPlanShowsInPrompt(t *testing.T) {
 	mem := store.NewMemoryStore()
 	a := New(Name("planner"), Prompt("base prompt"), WithStore(mem)).(*agentImpl)
@@ -165,3 +192,45 @@ func TestIsAgent(t *testing.T) {
 		t.Error("isAgent(nonexistent) = true, want false")
 	}
 }
+
+func TestPlanWrapBlocksDelegationUntilPriorPlanStepsFinish(t *testing.T) {
+	mem := store.NewMemoryStore()
+	a := New(Name("planner"), WithStore(mem)).(*agentImpl)
+	a.handlePlan(ai.ToolCall{Name: toolPlan, Input: map[string]any{
+		"steps": []any{
+			map[string]any{"task": "Create Design task", "status": "pending"},
+			map[string]any{"task": "Create Build task", "status": "pending"},
+			map[string]any{"task": "Create Ship task", "status": "pending"},
+			map[string]any{"task": "Delegate readiness notification to comms agent", "status": "pending"},
+		},
+	}})
+
+	called := false
+	handle := a.planWrap(func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		called = true
+		return ai.ToolResult{ID: call.ID, Content: "ok"}
+	})
+
+	res := handle(context.Background(), ai.ToolCall{ID: "delegate-1", Name: toolDelegate, Input: map[string]any{"to": "comms"}})
+	if called {
+		t.Fatal("delegate handler was called before prior task plan steps completed")
+	}
+	if res.Refused == "" {
+		t.Fatalf("delegate result was not refused: %+v", res)
+	}
+	if got := res.Content; !containsStr(got, "Create Design task") || !containsStr(got, "Create Ship task") {
+		t.Fatalf("delegate refusal content = %q, want prior unfinished task steps", got)
+	}
+
+	for _, id := range []string{"add-design", "add-build", "add-ship"} {
+		_ = handle(context.Background(), ai.ToolCall{ID: id, Name: "task.Add", Input: map[string]any{"title": id}})
+	}
+	called = false
+	res = handle(context.Background(), ai.ToolCall{ID: "delegate-2", Name: toolDelegate, Input: map[string]any{"to": "comms"}})
+	if !called {
+		t.Fatal("delegate handler was not called after prior task plan steps completed")
+	}
+	if res.Refused != "" {
+		t.Fatalf("delegate result refused after prior task steps completed: %+v", res)
+	}
+}

agent/checkpoint.go

@@ -191,6 +191,43 @@ func agentRunFailureStatus(err error) string {
 	}
 }
 
+type operationalError struct {
+	err  error
+	hint string
+}
+
+func (e *operationalError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.err.Error() + "; " + e.hint
+}
+
+func (e *operationalError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+func agentOperationalError(err error) error {
+	if err == nil {
+		return nil
+	}
+	switch ai.ClassifyError(err) {
+	case ai.ErrorKindCanceled:
+		return &operationalError{err: err, hint: "agent run canceled; inspect run history with `micro inspect agent <name> --status canceled` or see docs/guides/debugging-agents.md"}
+	case ai.ErrorKindTimeout:
+		return &operationalError{err: err, hint: "agent provider call timed out; inspect run history with `micro inspect agent <name> --status timeout`, then adjust AgentModelCallTimeout/AgentModelRetry or see docs/guides/debugging-agents.md"}
+	case ai.ErrorKindRateLimited:
+		return &operationalError{err: err, hint: "agent provider was rate limited; inspect run history with `micro inspect agent <name> --status rate_limited`, check provider keys with `micro agent preflight`, or see docs/guides/debugging-agents.md"}
+	case ai.ErrorKindUnavailable:
+		return &operationalError{err: err, hint: "agent provider appears temporarily unavailable; retry with bounded AgentModelRetry and verify provider setup with `micro agent preflight` or docs/guides/debugging-agents.md"}
+	default:
+		return err
+	}
+}
+
 func (a *agentImpl) checkpointToolWrap(next ai.ToolHandler) ai.ToolHandler {
 	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
 		if a.opts.Checkpoint == nil || a.currentRun == nil {

agent/checkpoint_test.go

@@ -219,6 +219,72 @@ func TestCheckpointContinuesRunWithUnfinishedPlanStep(t *testing.T) {
 	}
 }
 
+func TestCheckpointContinuesRunThroughSeveralSingleStepTurns(t *testing.T) {
+	ctx := context.Background()
+	cp := flow.StoreCheckpoint(store.NewMemoryStore(), "single-step-plan-agent")
+
+	completed := []string{}
+	modelCalls := 0
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		modelCalls++
+		if opts.ToolHandler == nil {
+			t.Fatal("missing tool handler")
+		}
+		switch modelCalls {
+		case 1:
+			opts.ToolHandler(ctx, ai.ToolCall{ID: "plan-1", Name: toolPlan, Input: map[string]any{
+				"steps": []any{
+					map[string]any{"task": "create Design task", "status": "pending"},
+					map[string]any{"task": "create Build task", "status": "pending"},
+					map[string]any{"task": "create Ship task", "status": "pending"},
+					map[string]any{"task": "delegate readiness notification", "status": "pending"},
+				},
+			}})
+			return &ai.Response{Reply: "planned"}, nil
+		case 2, 3, 4, 5:
+			want := []string{"create Design task", "create Build task", "create Ship task", "delegate readiness notification"}[modelCalls-2]
+			if !strings.Contains(req.Prompt, want) {
+				t.Fatalf("continuation prompt %d = %q, want %q", modelCalls, req.Prompt, want)
+			}
+			res := opts.ToolHandler(ctx, ai.ToolCall{ID: want, Name: "external.step", Input: map[string]any{"step": want}})
+			if res.Content != "completed "+want {
+				t.Fatalf("tool result = %q, want completed %s", res.Content, want)
+			}
+			if modelCalls == 5 {
+				return &ai.Response{Reply: "all plan steps complete"}, nil
+			}
+			return &ai.Response{Reply: "one more step complete"}, nil
+		default:
+			t.Fatalf("unexpected model call %d", modelCalls)
+			return nil, nil
+		}
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("single-step-plan-agent"), WithCheckpoint(cp),
+		WithTool("external.step", "complete one planned step", nil, func(ctx context.Context, input map[string]any) (string, error) {
+			step, _ := input["step"].(string)
+			completed = append(completed, step)
+			return "completed " + step, nil
+		}))
+	resp, err := a.Ask(ctx, "work through the launch plan")
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if resp.Reply != "all plan steps complete" {
+		t.Fatalf("reply = %q, want final continuation reply", resp.Reply)
+	}
+	if modelCalls != 5 {
+		t.Fatalf("model calls = %d, want initial plus four continuations", modelCalls)
+	}
+	if len(completed) != 4 {
+		t.Fatalf("completed steps = %v, want four tool-backed continuations", completed)
+	}
+	if unfinished := a.unfinishedPlanSteps(); len(unfinished) != 0 {
+		t.Fatalf("unfinished plan steps = %v, want none", unfinished)
+	}
+}
+
 func TestResumeFailedCheckpointAfterFreshAgentRestart(t *testing.T) {
 	ctx := context.Background()
 	cp := flow.StoreCheckpoint(store.NewMemoryStore(), "restart-resume-agent")

agent/conformance_test.go

@@ -67,30 +67,45 @@ func runAgentConformanceScenario(t *testing.T, provider conformanceProvider) {
 		}
 	} else {
 		fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
-			if req.Prompt == "" {
-				return nil, errors.New("missing prompt")
+			if err := validateConformanceRequest(req, opts); err != nil {
+				return nil, err
 			}
-			if len(req.Messages) == 0 || req.Messages[len(req.Messages)-1].Role != "user" {
-				return nil, fmt.Errorf("missing user history: %+v", req.Messages)
-			}
-			if len(req.Tools) == 0 {
-				return nil, errors.New("missing tools")
-			}
-			if opts.ToolHandler == nil {
-				return nil, errors.New("missing tool handler")
-			}
-			res := opts.ToolHandler(ctx, ai.ToolCall{
+
+			plan := opts.ToolHandler(ctx, ai.ToolCall{
+				ID:   "fake-plan-1",
+				Name: "plan",
+				Input: map[string]any{"steps": []map[string]any{
+					{"description": "call conformance_echo", "status": "pending"},
+					{"description": "attempt guarded delegate", "status": "pending"},
+				}},
+			})
+			echo := opts.ToolHandler(ctx, ai.ToolCall{
 				ID:    "fake-call-1",
 				Name:  "conformance_echo",
 				Input: map[string]any{"value": "agent-conformance"},
 			})
-			if res.Content == "" {
+			delegate := opts.ToolHandler(ctx, ai.ToolCall{
+				ID:    "fake-delegate-1",
+				Name:  "delegate",
+				Input: map[string]any{"task": "summarize the conformance marker", "to": "blocked-reviewer"},
+			})
+			if plan.Content == "" {
+				return nil, errors.New("empty plan result")
+			}
+			if echo.Content == "" {
 				return nil, errors.New("empty tool result")
 			}
+			if delegate.Refused != ai.RefusedApproval {
+				return nil, fmt.Errorf("delegate refusal = %q, want %q", delegate.Refused, ai.RefusedApproval)
+			}
 			return &ai.Response{
-				Reply:     "used conformance_echo",
-				Answer:    res.Content,
-				ToolCalls: []ai.ToolCall{{ID: "fake-call-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: res.Content}},
+				Reply:  "planned, called conformance_echo, and handled guarded delegate refusal",
+				Answer: echo.Content + " " + delegate.Content,
+				ToolCalls: []ai.ToolCall{
+					{ID: "fake-plan-1", Name: "plan", Input: map[string]any{}},
+					{ID: "fake-call-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: echo.Content},
+					{ID: "fake-delegate-1", Name: "delegate", Input: map[string]any{"task": "summarize the conformance marker", "to": "blocked-reviewer"}, Error: delegate.Content},
+				},
 			}, nil
 		}
 		defer func() { fakeGen = nil }()
@@ -98,15 +113,23 @@ func runAgentConformanceScenario(t *testing.T, provider conformanceProvider) {
 
 	var sawTool bool
 	var sawRunInfo bool
+	var sawBlockedDelegate bool
 	agentOpts := []Option{
 		Name("conformance-" + provider.name),
 		Provider(provider.name),
 		APIKey(os.Getenv(provider.key)),
-		Prompt("You are a conformance test agent. Use the conformance_echo tool exactly once with input {\"value\":\"agent-conformance\"}, then answer with the tool result."),
+		Prompt(conformanceSystemPrompt(provider.name)),
 		WithRegistry(registry.NewMemoryRegistry()),
 		WithStore(store.NewMemoryStore()),
 		WithMemory(NewInMemory(8)),
 		ModelCallTimeout(45 * time.Second),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			if tool == "delegate" {
+				sawBlockedDelegate = true
+				return false, "cross-provider conformance blocks delegate side effects"
+			}
+			return true, ""
+		}),
 		WithTool("conformance_echo", "Echo a conformance value and return a deterministic marker.", map[string]any{
 			"value": map[string]any{"type": "string", "description": "value to echo"},
 		}, func(ctx context.Context, input map[string]any) (string, error) {
@@ -132,7 +155,7 @@ func runAgentConformanceScenario(t *testing.T, provider conformanceProvider) {
 	}
 
 	a := New(agentOpts...)
-	resp, err := a.Ask(context.Background(), "Run the provider conformance check.")
+	resp, err := askWithConformanceRetry(context.Background(), a, "Run the provider conformance check.", &sawTool, &sawBlockedDelegate)
 	if err != nil {
 		t.Fatalf("Ask: %v", err)
 	}
@@ -148,11 +171,103 @@ func runAgentConformanceScenario(t *testing.T, provider conformanceProvider) {
 	if !sawRunInfo {
 		t.Fatal("tool did not receive RunInfo")
 	}
+	if !sawBlockedDelegate {
+		t.Fatal("provider did not exercise the guarded delegate path")
+	}
 	if !strings.Contains(resp.Reply, "agent-conformance-ok") && !strings.Contains(resp.Reply, "agent-conformance") {
 		t.Fatalf("reply %q does not include conformance marker", resp.Reply)
 	}
 }
 
+func askWithConformanceRetry(ctx context.Context, a Agent, initialPrompt string, sawTool, sawBlockedDelegate *bool) (*Response, error) {
+	const maxAttempts = 3
+	prompt := initialPrompt
+	var resp *Response
+	for attempt := 1; attempt <= maxAttempts; attempt++ {
+		var err error
+		resp, err = a.Ask(ctx, prompt)
+		if err != nil {
+			return nil, err
+		}
+		sawRequiredTool := sawTool == nil || *sawTool
+		sawRequiredDelegate := sawBlockedDelegate == nil || *sawBlockedDelegate
+		hasMarker := responseHasConformanceMarker(resp)
+		if sawRequiredTool && sawRequiredDelegate && hasMarker {
+			return resp, nil
+		}
+		if attempt == maxAttempts {
+			break
+		}
+		prompt = nextConformanceRetryPrompt(sawRequiredTool, sawRequiredDelegate, hasMarker)
+	}
+	return resp, nil
+}
+
+func askWithConformanceToolRetry(ctx context.Context, a Agent, initialPrompt string, sawTool *bool) (*Response, error) {
+	return askWithConformanceRetry(ctx, a, initialPrompt, sawTool, nil)
+}
+
+func conformanceSystemPrompt(provider string) string {
+	prompt := "You are a conformance test agent. Create a short plan, use conformance_echo exactly once with input {\"value\":\"agent-conformance\"}, then attempt to delegate a summary to blocked-reviewer with input {\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}. If the delegate is refused, explain the refusal and answer with the echo result."
+	if provider == "atlascloud" {
+		prompt += " AtlasCloud/minimax conformance note: the delegate attempt is mandatory after conformance_echo. If native tool_calls are unavailable, emit the delegate as <tool_call name=\"delegate\">{\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}</tool_call> rather than answering in prose."
+	}
+	return prompt
+}
+
+func TestAgentProviderConformanceAtlasCloudPromptRequiresTaggedDelegateFallback(t *testing.T) {
+	prompt := conformanceSystemPrompt("atlascloud")
+	for _, want := range []string{
+		"delegate attempt is mandatory",
+		"<tool_call name=\"delegate\">",
+		`{"task":"summarize the conformance marker","to":"blocked-reviewer"}`,
+	} {
+		if !strings.Contains(prompt, want) {
+			t.Fatalf("atlascloud conformance prompt %q missing %q", prompt, want)
+		}
+	}
+
+	if strings.Contains(conformanceSystemPrompt("openai"), "AtlasCloud/minimax") {
+		t.Fatal("non-AtlasCloud prompt should not include provider-specific fallback guidance")
+	}
+}
+
+func nextConformanceRetryPrompt(sawTool, sawBlockedDelegate, hasMarker bool) string {
+	switch {
+	case !sawTool:
+		return "The previous response did not call the required conformance_echo tool. Retry the same conformance check now: you must call conformance_echo exactly once with input {\"value\":\"agent-conformance\"} before any final answer, then include the tool result marker in the final answer."
+	case !sawBlockedDelegate:
+		return "The previous response called conformance_echo but did not attempt the required guarded delegation. Continue the same conformance check now: call delegate exactly once with input {\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}; do not answer in prose until that delegate call has been attempted. If native tool_calls are unavailable, emit exactly <tool_call name=\"delegate\">{\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}</tool_call>. The delegate is expected to be refused by policy; include that refusal and the agent-conformance marker in the final answer."
+	case !hasMarker:
+		return "The previous response completed the required tool calls but omitted the conformance marker. Continue the same conformance check now: do not call more tools; answer with the prior echo result marker agent-conformance-ok and mention the guarded delegate refusal."
+	default:
+		return "Retry the provider conformance check and include the agent-conformance marker in the final answer."
+	}
+}
+
+func responseHasConformanceMarker(resp *Response) bool {
+	if resp == nil {
+		return false
+	}
+	return strings.Contains(resp.Reply, "agent-conformance-ok") || strings.Contains(resp.Reply, "agent-conformance")
+}
+
+func validateConformanceRequest(req *ai.Request, opts ai.Options) error {
+	if req.Prompt == "" {
+		return errors.New("missing prompt")
+	}
+	if len(req.Messages) == 0 || req.Messages[len(req.Messages)-1].Role != "user" {
+		return fmt.Errorf("missing user history: %+v", req.Messages)
+	}
+	if len(req.Tools) == 0 {
+		return errors.New("missing tools")
+	}
+	if opts.ToolHandler == nil {
+		return errors.New("missing tool handler")
+	}
+	return nil
+}
+
 func TestAgentProviderConformanceFakeError(t *testing.T) {
 	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
 		return nil, errors.New("conformance provider failure")
@@ -172,6 +287,177 @@ func TestAgentProviderConformanceFakeError(t *testing.T) {
 	}
 }
 
+func TestAgentProviderConformanceRetriesMissingTool(t *testing.T) {
+	var attempts int
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		attempts++
+		if err := validateConformanceRequest(req, opts); err != nil {
+			return nil, err
+		}
+		if attempts == 1 {
+			return &ai.Response{Reply: "I can confirm agent-conformance in prose only."}, nil
+		}
+		echo := opts.ToolHandler(ctx, ai.ToolCall{
+			ID:    "fake-call-1",
+			Name:  "conformance_echo",
+			Input: map[string]any{"value": "agent-conformance"},
+		})
+		return &ai.Response{
+			Reply:  "called conformance_echo",
+			Answer: echo.Content,
+			ToolCalls: []ai.ToolCall{
+				{ID: "fake-call-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: echo.Content},
+			},
+		}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	var sawTool bool
+	a := New(
+		Name("conformance-retry"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WithMemory(NewInMemory(4)),
+		WithTool("conformance_echo", "Echo a conformance value.", map[string]any{
+			"value": map[string]any{"type": "string"},
+		}, func(ctx context.Context, input map[string]any) (string, error) {
+			sawTool = true
+			return `{"marker":"agent-conformance-ok"}`, nil
+		}),
+	)
+
+	resp, err := askWithConformanceToolRetry(context.Background(), a, "Run the provider conformance check.", &sawTool)
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if attempts != 2 {
+		t.Fatalf("attempts = %d, want retry after missing tool", attempts)
+	}
+	if !sawTool {
+		t.Fatal("retry did not execute conformance_echo")
+	}
+	if !strings.Contains(resp.Reply, "agent-conformance-ok") {
+		t.Fatalf("Reply = %q, want tool result marker", resp.Reply)
+	}
+}
+
+func TestAgentProviderConformanceRetriesMissingMarker(t *testing.T) {
+	var attempts int
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		attempts++
+		if err := validateConformanceRequest(req, opts); err != nil {
+			return nil, err
+		}
+		if attempts == 1 {
+			return &ai.Response{Reply: "called conformance_echo and handled guarded delegate refusal without the required marker"}, nil
+		}
+		return &ai.Response{Reply: "agent-conformance-ok after guarded delegate refusal"}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	sawTool := true
+	sawBlockedDelegate := true
+	a := New(
+		Name("conformance-retry-marker"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WithMemory(NewInMemory(4)),
+		WithTool("conformance_echo", "Echo a conformance value.", map[string]any{
+			"value": map[string]any{"type": "string"},
+		}, func(ctx context.Context, input map[string]any) (string, error) {
+			return `{"marker":"agent-conformance-ok"}`, nil
+		}),
+	)
+
+	resp, err := askWithConformanceRetry(context.Background(), a, "Run the provider conformance check.", &sawTool, &sawBlockedDelegate)
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if attempts != 2 {
+		t.Fatalf("attempts = %d, want retry after missing marker", attempts)
+	}
+	if !strings.Contains(resp.Reply, "agent-conformance-ok") {
+		t.Fatalf("Reply = %q, want conformance marker", resp.Reply)
+	}
+}
+
+func TestAgentProviderConformanceRetriesMissingDelegate(t *testing.T) {
+	var attempts int
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		attempts++
+		if err := validateConformanceRequest(req, opts); err != nil {
+			return nil, err
+		}
+		echo := opts.ToolHandler(ctx, ai.ToolCall{
+			ID:    "fake-call-1",
+			Name:  "conformance_echo",
+			Input: map[string]any{"value": "agent-conformance"},
+		})
+		if attempts == 1 {
+			return &ai.Response{
+				Reply:  "called conformance_echo but skipped delegate",
+				Answer: echo.Content,
+				ToolCalls: []ai.ToolCall{
+					{ID: "fake-call-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: echo.Content},
+				},
+			}, nil
+		}
+		delegate := opts.ToolHandler(ctx, ai.ToolCall{
+			ID:    "fake-delegate-1",
+			Name:  "delegate",
+			Input: map[string]any{"task": "summarize the conformance marker", "to": "blocked-reviewer"},
+		})
+		return &ai.Response{
+			Reply:  "called conformance_echo and handled guarded delegate refusal",
+			Answer: echo.Content + " " + delegate.Content,
+			ToolCalls: []ai.ToolCall{
+				{ID: "fake-call-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: echo.Content},
+				{ID: "fake-delegate-1", Name: "delegate", Input: map[string]any{"task": "summarize the conformance marker", "to": "blocked-reviewer"}, Error: delegate.Content},
+			},
+		}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	var sawTool bool
+	var sawBlockedDelegate bool
+	a := New(
+		Name("conformance-retry-delegate"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WithMemory(NewInMemory(4)),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			if tool == "delegate" {
+				sawBlockedDelegate = true
+				return false, "cross-provider conformance blocks delegate side effects"
+			}
+			return true, ""
+		}),
+		WithTool("conformance_echo", "Echo a conformance value.", map[string]any{
+			"value": map[string]any{"type": "string"},
+		}, func(ctx context.Context, input map[string]any) (string, error) {
+			sawTool = true
+			return `{"marker":"agent-conformance-ok"}`, nil
+		}),
+	)
+
+	resp, err := askWithConformanceRetry(context.Background(), a, "Run the provider conformance check.", &sawTool, &sawBlockedDelegate)
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if attempts != 2 {
+		t.Fatalf("attempts = %d, want retry after missing delegate", attempts)
+	}
+	if !sawBlockedDelegate {
+		t.Fatal("retry did not attempt guarded delegate")
+	}
+	if !strings.Contains(resp.Reply, "agent-conformance-ok") && !strings.Contains(resp.Reply, "agent-conformance") {
+		t.Fatalf("Reply = %q, want conformance marker", resp.Reply)
+	}
+}
+
 func TestAgentExecutesProviderTextToolCallFallback(t *testing.T) {
 	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
 		if opts.ToolHandler == nil {
@@ -218,3 +504,67 @@ func TestAgentExecutesProviderTextToolCallFallback(t *testing.T) {
 		t.Fatalf("Reply = %q, want tool result instead of raw JSON", resp.Reply)
 	}
 }
+
+func TestAgentExecutesTextToolCallFallbackAfterStructuredToolCall(t *testing.T) {
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		if opts.ToolHandler == nil {
+			return nil, errors.New("missing tool handler")
+		}
+		echo := opts.ToolHandler(ctx, ai.ToolCall{
+			ID:    "structured-echo-1",
+			Name:  "conformance_echo",
+			Input: map[string]any{"value": "agent-conformance"},
+		})
+		return &ai.Response{
+			Reply:  echo.Content + "\n<tool_call name=\"delegate\">{\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}</tool_call>",
+			Answer: echo.Content,
+			ToolCalls: []ai.ToolCall{
+				{ID: "structured-echo-1", Name: "conformance_echo", Input: map[string]any{"value": "agent-conformance"}, Result: echo.Content},
+			},
+		}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	var sawTool bool
+	var sawBlockedDelegate bool
+	a := New(
+		Name("conformance-mixed-text-tool"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WithMemory(NewInMemory(4)),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			if tool == "delegate" {
+				sawBlockedDelegate = true
+				return false, "cross-provider conformance blocks delegate side effects"
+			}
+			return true, ""
+		}),
+		WithTool("conformance_echo", "Echo a conformance value.", map[string]any{
+			"value": map[string]any{"type": "string"},
+		}, func(ctx context.Context, input map[string]any) (string, error) {
+			sawTool = true
+			return `{"marker":"agent-conformance-ok"}`, nil
+		}),
+	)
+
+	resp, err := a.Ask(context.Background(), "Run the mixed structured/text tool fallback.")
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if !sawTool {
+		t.Fatal("structured conformance_echo did not execute")
+	}
+	if !sawBlockedDelegate {
+		t.Fatal("tagged text delegate fallback did not execute")
+	}
+	if len(resp.ToolCalls) != 2 {
+		t.Fatalf("ToolCalls = %+v, want structured echo and text delegate", resp.ToolCalls)
+	}
+	if resp.ToolCalls[1].Name != "delegate" || resp.ToolCalls[1].Error != ai.RefusedApproval {
+		t.Fatalf("delegate ToolCall = %+v, want refused delegate", resp.ToolCalls[1])
+	}
+	if !strings.Contains(resp.Reply, "agent-conformance-ok") {
+		t.Fatalf("Reply = %q, want conformance marker", resp.Reply)
+	}
+}

agent/options.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/broker"
 	"go-micro.dev/v6/client"
 	"go-micro.dev/v6/flow"
 	"go-micro.dev/v6/registry"
@@ -44,6 +45,7 @@ type Options struct {
 	Address      string
 	Registry     registry.Registry
 	Client       client.Client
+	Broker       broker.Broker
 	Store        store.Store
 	HistoryLimit int
 
@@ -192,6 +194,13 @@ func WithClient(c client.Client) Option {
 	return func(o *Options) { o.Client = c }
 }
 
+// WithBroker sets the broker used by the agent service endpoint. Use an
+// in-memory broker in local harnesses/tests to avoid sharing the package-wide
+// default broker listener across concurrently running examples.
+func WithBroker(b broker.Broker) Option {
+	return func(o *Options) { o.Broker = b }
+}
+
 // WithStore sets the store for agent memory.
 func WithStore(s store.Store) Option {
 	return func(o *Options) { o.Store = s }

agent/otel.go

@@ -3,7 +3,9 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"sort"
 	"strings"
 	"time"
@@ -18,9 +20,10 @@ import (
 const agentInstrumentationName = "go-micro.dev/v6/agent"
 
 const (
-	spanNameRun       = "agent.run"
-	spanNameModelCall = "agent.model.call"
-	spanNameToolCall  = "agent.tool.call"
+	spanNameRun         = "agent.run"
+	spanNameModelCall   = "agent.model.call"
+	spanNameModelStream = "agent.model.stream"
+	spanNameToolCall    = "agent.tool.call"
 
 	AttrRunID            = "agent.run.id"
 	AttrParentRunID      = "agent.run.parent_id"
@@ -100,6 +103,8 @@ type RunSummary struct {
 	DurationMS    int64     `json:"duration_ms,omitempty"`
 	Events        int       `json:"events"`
 	Status        string    `json:"status,omitempty"`
+	Checkpoint    string    `json:"checkpoint,omitempty"`
+	Stage         string    `json:"stage,omitempty"`
 	LastKind      string    `json:"last_kind,omitempty"`
 	LastError     string    `json:"last_error,omitempty"`
 	LastErrorKind string    `json:"last_error_kind,omitempty"`
@@ -210,16 +215,133 @@ func (m *tracedModel) Generate(ctx context.Context, req *ai.Request, opts ...ai.
 	} else {
 		span.SetStatus(codes.Ok, "")
 	}
-	span.End()
 	e := RunEvent{Time: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent, Kind: "model", Provider: provider, Model: model, Attempt: info.Attempt, MaxAttempts: info.MaxAttempts, LatencyMS: dur, Tokens: usage}
 	if err != nil {
 		e.Error = err.Error()
 		e.ErrorKind = string(ai.ClassifyError(err))
 	}
 	m.a.recordSpanEvent(span, e)
+	span.End()
 	return resp, err
 }
 
+func (m *tracedModel) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	info, _ := ai.RunInfoFrom(ctx)
+	provider := m.String()
+	model := m.Options().Model
+	start := time.Now()
+
+	if m.a.opts.TraceProvider == nil {
+		stream, err := m.Model.Stream(ctx, req, opts...)
+		if err != nil {
+			m.a.recordRunEvent(RunEvent{Time: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent, Kind: "stream", Provider: provider, Model: model, Attempt: info.Attempt, MaxAttempts: info.MaxAttempts, LatencyMS: time.Since(start).Milliseconds(), Error: err.Error(), ErrorKind: string(ai.ClassifyError(err))})
+			return nil, err
+		}
+		return &tracedStream{Stream: stream, a: m.a, info: info, provider: provider, model: model, start: start}, nil
+	}
+
+	attrs := appendRunInfoAttributes([]attribute.KeyValue{
+		attribute.String(AttrRunID, info.RunID),
+		attribute.String(AttrParentRunID, info.ParentID),
+		attribute.String(AttrAgentName, info.Agent),
+		attribute.String(AttrProvider, provider),
+		attribute.String(AttrModel, model),
+	}, info)
+	ctx, span := m.a.tracer().Start(ctx, spanNameModelStream, trace.WithAttributes(attrs...))
+	stream, err := m.Model.Stream(ctx, req, opts...)
+	if err != nil {
+		dur := time.Since(start).Milliseconds()
+		span.SetAttributes(attribute.Int64(AttrLatencyMS, dur), attribute.String(AttrErrorKind, string(ai.ClassifyError(err))))
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		e := RunEvent{Time: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent, Kind: "stream", Provider: provider, Model: model, Attempt: info.Attempt, MaxAttempts: info.MaxAttempts, LatencyMS: dur, Error: err.Error(), ErrorKind: string(ai.ClassifyError(err))}
+		m.a.recordSpanEvent(span, e)
+		span.End()
+		return nil, err
+	}
+	return &tracedStream{Stream: stream, a: m.a, info: info, provider: provider, model: model, start: start, span: span}, nil
+}
+
+type tracedStream struct {
+	ai.Stream
+	a        *agentImpl
+	info     ai.RunInfo
+	provider string
+	model    string
+	start    time.Time
+	span     trace.Span
+	usage    ai.Usage
+	closed   bool
+}
+
+func (s *tracedStream) Recv() (*ai.Response, error) {
+	resp, err := s.Stream.Recv()
+	if resp != nil {
+		s.usage = mergeUsage(s.usage, resp.Usage)
+	}
+	if err != nil {
+		if errors.Is(err, io.EOF) {
+			s.finish(nil)
+		} else {
+			s.finish(err)
+		}
+	}
+	return resp, err
+}
+
+func (s *tracedStream) Close() error {
+	err := s.Stream.Close()
+	s.finish(err)
+	return err
+}
+
+func (s *tracedStream) finish(err error) {
+	if s.closed {
+		return
+	}
+	s.closed = true
+	dur := time.Since(s.start).Milliseconds()
+	e := RunEvent{Time: time.Now(), RunID: s.info.RunID, ParentID: s.info.ParentID, Agent: s.info.Agent, Kind: "stream", Provider: s.provider, Model: s.model, Attempt: s.info.Attempt, MaxAttempts: s.info.MaxAttempts, LatencyMS: dur, Tokens: s.usage}
+	if err != nil {
+		e.Error = err.Error()
+		e.ErrorKind = string(ai.ClassifyError(err))
+	}
+	if s.span == nil {
+		s.a.recordRunEvent(e)
+		return
+	}
+	attrs := appendUsage([]attribute.KeyValue{attribute.Int64(AttrLatencyMS, dur)}, s.usage)
+	if s.info.Attempt > 0 {
+		attrs = append(attrs, attribute.Int(AttrAttempt, s.info.Attempt))
+	}
+	if s.info.MaxAttempts > 0 {
+		attrs = append(attrs, attribute.Int(AttrMaxAttempts, s.info.MaxAttempts))
+	}
+	if err != nil {
+		attrs = append(attrs, attribute.String(AttrErrorKind, e.ErrorKind))
+		s.span.RecordError(err)
+		s.span.SetStatus(codes.Error, err.Error())
+	} else {
+		s.span.SetStatus(codes.Ok, "")
+	}
+	s.span.SetAttributes(attrs...)
+	s.a.recordSpanEvent(s.span, e)
+	s.span.End()
+}
+
+func mergeUsage(current, next ai.Usage) ai.Usage {
+	if next.InputTokens > current.InputTokens {
+		current.InputTokens = next.InputTokens
+	}
+	if next.OutputTokens > current.OutputTokens {
+		current.OutputTokens = next.OutputTokens
+	}
+	if next.TotalTokens > current.TotalTokens {
+		current.TotalTokens = next.TotalTokens
+	}
+	return current
+}
+
 func appendUsage(attrs []attribute.KeyValue, u ai.Usage) []attribute.KeyValue {
 	if u.InputTokens > 0 {
 		attrs = append(attrs, attribute.Int(AttrInputTokens, u.InputTokens))
@@ -271,8 +393,8 @@ func (a *agentImpl) traceTool(next ai.ToolHandler) ai.ToolHandler {
 		} else {
 			span.SetStatus(codes.Ok, "")
 		}
-		span.End()
 		a.recordSpanEvent(span, RunEvent{Time: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent, Kind: "tool", Name: call.Name, LatencyMS: dur, Refused: res.Refused, Error: resErr, ErrorKind: classifyToolError(resErr)})
+		span.End()
 		return res
 	}
 }
@@ -460,6 +582,10 @@ func ListRunSummariesWithOptions(s store.Store, agentName string, opts RunListOp
 			if e.SpanID != "" {
 				summary.SpanID = e.SpanID
 			}
+			if e.Kind == "checkpoint" {
+				summary.Checkpoint = e.Status
+				summary.Stage = e.Name
+			}
 			if e.Error != "" {
 				summary.LastError = e.Error
 			}

agent/otel_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"strings"
 	"testing"
 	"time"
@@ -94,8 +95,16 @@ func TestAgentOpenTelemetrySpans(t *testing.T) {
 		if attrs[AttrRunID] != runID || attrs[AttrAgentName] != "runner" {
 			t.Fatalf("%s missing run correlation attributes: %#v", s.Name(), attrs)
 		}
-		if s.Name() == spanNameModelCall && (attrs[AttrAttempt] != "1" || attrs[AttrMaxAttempts] != "1") {
-			t.Fatalf("model span missing attempt attributes: %#v", attrs)
+		if s.Name() == spanNameModelCall {
+			if attrs[AttrAttempt] != "1" || attrs[AttrMaxAttempts] != "1" {
+				t.Fatalf("model span missing attempt attributes: %#v", attrs)
+			}
+			if !spanEventHasRunInfo(s.Events(), "agent.model", runID, "runner") {
+				t.Fatalf("model span missing model event: %#v", s.Events())
+			}
+		}
+		if s.Name() == spanNameToolCall && !spanEventHasRunInfo(s.Events(), "agent.tool", runID, "runner") {
+			t.Fatalf("tool span missing tool event: %#v", s.Events())
 		}
 	}
 	keys, err := store.Scope(st, "agent", "runner").List(store.ListPrefix("runs/"))
@@ -499,7 +508,8 @@ func TestListRunSummaries(t *testing.T) {
 		{Time: time.Unix(0, 1), RunID: "run-a", Agent: "runner", TraceID: "trace-a", SpanID: "span-a", Kind: "run", Name: "first"},
 		{Time: time.Unix(0, 2), RunID: "run-a", Agent: "runner", Kind: "tool", Name: "probe"},
 		{Time: time.Unix(0, 3), RunID: "run-b", Agent: "runner", ParentID: "parent", Kind: "run", Name: "second"},
-		{Time: time.Unix(0, 4), RunID: "run-b", Agent: "runner", ParentID: "parent", Kind: "error", Error: "context deadline exceeded", ErrorKind: string(ai.ErrorKindTimeout)},
+		{Time: time.Unix(0, 4), RunID: "run-b", Agent: "runner", ParentID: "parent", Kind: "checkpoint", Name: "ask", Status: "failed"},
+		{Time: time.Unix(0, 5), RunID: "run-b", Agent: "runner", ParentID: "parent", Kind: "error", Error: "context deadline exceeded", ErrorKind: string(ai.ErrorKindTimeout)},
 	}
 	for _, e := range events {
 		b, err := json.Marshal(e)
@@ -522,7 +532,7 @@ func TestListRunSummaries(t *testing.T) {
 	if got[0].RunID != "run-a" || got[0].TraceID != "trace-a" || got[0].SpanID != "span-a" || got[0].Events != 2 || got[0].Status != "running" || got[0].DurationMS != 0 || got[0].LastKind != "tool" || !got[0].UpdatedAt.Equal(time.Unix(0, 2)) {
 		t.Fatalf("unexpected run-a summary: %#v", got[0])
 	}
-	if got[1].RunID != "run-b" || got[1].ParentID != "parent" || got[1].Events != 2 || got[1].Status != "timeout" || got[1].DurationMS != 0 || got[1].LastKind != "error" || got[1].LastError != "context deadline exceeded" || got[1].LastErrorKind != string(ai.ErrorKindTimeout) {
+	if got[1].RunID != "run-b" || got[1].ParentID != "parent" || got[1].Events != 3 || got[1].Status != "timeout" || got[1].DurationMS != 0 || got[1].LastKind != "error" || got[1].Checkpoint != "failed" || got[1].Stage != "ask" || got[1].LastError != "context deadline exceeded" || got[1].LastErrorKind != string(ai.ErrorKindTimeout) {
 		t.Fatalf("unexpected run-b summary: %#v", got[1])
 	}
 }
@@ -578,3 +588,95 @@ func TestListRunSummariesWithOptionsFiltersAndLimits(t *testing.T) {
 		t.Fatalf("filtered summaries = %#v", got)
 	}
 }
+
+type otelStreamModel struct{ opts ai.Options }
+
+func (m *otelStreamModel) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&m.opts)
+	}
+	return nil
+}
+func (m *otelStreamModel) Options() ai.Options { return m.opts }
+func (m *otelStreamModel) String() string      { return "otelstream" }
+func (m *otelStreamModel) Generate(context.Context, *ai.Request, ...ai.GenerateOption) (*ai.Response, error) {
+	return &ai.Response{Reply: "unused"}, nil
+}
+func (m *otelStreamModel) Stream(context.Context, *ai.Request, ...ai.GenerateOption) (ai.Stream, error) {
+	return &otelTestStream{chunks: []*ai.Response{{Reply: "one", Usage: ai.Usage{InputTokens: 1, OutputTokens: 2, TotalTokens: 3}}, {Reply: "two", Usage: ai.Usage{InputTokens: 1, OutputTokens: 4, TotalTokens: 5}}}}, nil
+}
+
+type otelTestStream struct {
+	chunks []*ai.Response
+	idx    int
+}
+
+func (s *otelTestStream) Recv() (*ai.Response, error) {
+	if s.idx >= len(s.chunks) {
+		return nil, io.EOF
+	}
+	resp := s.chunks[s.idx]
+	s.idx++
+	return resp, nil
+}
+
+func (s *otelTestStream) Close() error { return nil }
+
+func TestAgentOpenTelemetrySpansModelStream(t *testing.T) {
+	exp := tracetest.NewInMemoryExporter()
+	tp := trace.NewTracerProvider(trace.WithSyncer(exp))
+	st := store.NewMemoryStore()
+	a := New(Name("stream-runner"), Provider("oteltest"), Model("stream-model"), WithStore(st), TraceProvider(tp))
+	m := a.(*agentImpl).tracedModel(&otelStreamModel{opts: ai.Options{Model: "stream-model"}})
+	ctx := ai.WithRunInfo(context.Background(), ai.RunInfo{RunID: "stream-run-1", ParentID: "parent-run", Agent: "stream-runner", Attempt: 2, MaxAttempts: 3, Flow: "deploy", Step: "plan"})
+
+	stream, err := m.Stream(ctx, &ai.Request{Prompt: "stream"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for {
+		_, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := stream.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	spans := exp.GetSpans().Snapshots()
+	var sawStream bool
+	for _, s := range spans {
+		if s.Name() != spanNameModelStream {
+			continue
+		}
+		attrs := spanAttributes(s.Attributes())
+		if attrs[AttrRunID] != "stream-run-1" || attrs[AttrParentRunID] != "parent-run" || attrs[AttrAgentName] != "stream-runner" {
+			t.Fatalf("stream span missing run lineage: %#v", attrs)
+		}
+		if attrs[AttrFlowName] != "deploy" || attrs[AttrFlowStep] != "plan" {
+			t.Fatalf("stream span missing workflow attributes: %#v", attrs)
+		}
+		if attrs[AttrAttempt] != "2" || attrs[AttrMaxAttempts] != "3" || attrs[AttrTotalTokens] != "5" {
+			t.Fatalf("stream span missing attempt/usage attributes: %#v", attrs)
+		}
+		if !spanEventHasRunInfo(s.Events(), "agent.stream", "stream-run-1", "stream-runner") {
+			t.Fatalf("stream span missing stream event: %#v", s.Events())
+		}
+		sawStream = true
+	}
+	if !sawStream {
+		t.Fatalf("stream span not emitted; got %d spans", len(spans))
+	}
+
+	events, err := LoadRunEvents(st, "stream-runner", "stream-run-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(events) != 1 || events[0].Kind != "stream" || events[0].TraceID == "" || events[0].SpanID == "" || events[0].Tokens.TotalTokens != 5 {
+		t.Fatalf("unexpected stream run event: %#v", events)
+	}
+}

agent/resilience_test.go

@@ -77,6 +77,30 @@ func TestAskRetriesTransientErrorsThenSurfacesStructuredError(t *testing.T) {
 	if attempts != 2 {
 		t.Fatalf("model attempts = %d, want 2", attempts)
 	}
+	if !strings.Contains(err.Error(), "micro inspect agent <name> --status timeout") ||
+		!strings.Contains(err.Error(), "docs/guides/debugging-agents.md") {
+		t.Fatalf("Ask error = %q, want actionable timeout/debugging guidance", err.Error())
+	}
+}
+
+func TestAskRateLimitFailureSuggestsPreflightAndInspect(t *testing.T) {
+	fakeGen = func(ctx context.Context, opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		return nil, testStatusError{code: 429}
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("rate-limit-guidance"), ModelRetry(1, time.Millisecond))
+	_, err := a.Ask(context.Background(), "hello")
+	if err == nil {
+		t.Fatal("Ask succeeded, want rate-limit failure")
+	}
+	if !strings.Contains(err.Error(), "micro inspect agent <name> --status rate_limited") ||
+		!strings.Contains(err.Error(), "micro agent preflight") {
+		t.Fatalf("Ask error = %q, want inspect and preflight guidance", err.Error())
+	}
+	if ai.ClassifyError(err) != ai.ErrorKindRateLimited {
+		t.Fatalf("ClassifyError(wrapped error) = %q, want rate_limited", ai.ClassifyError(err))
+	}
 }
 
 func TestCanceledAskContextSkipsToolExecution(t *testing.T) {

agent/text_tool_calls.go

@@ -11,6 +11,8 @@ import (
 )
 
 var fencedJSONBlock = regexp.MustCompile("(?s)```(?:json)?\\s*(.*?)\\s*```")
+var taggedToolCallBlock = regexp.MustCompile(`(?s)<[^<>]*(?:tool_call|tool_calls|function=)[^<>]*>(.*?)</[^<>]*>`)
+var singleTaggedToolCall = regexp.MustCompile(`(?s)<(tool_call\b[^<>]*|[^<>]*function=[^<>]*)>(.*?)</[^<>]*>`)
 
 type textToolCall struct {
 	ID        string         `json:"id"`
@@ -45,18 +47,57 @@ func (a *agentImpl) executeTextToolCalls(ctx context.Context, reply string, tool
 	return calls, strings.Join(results, "\n"), true
 }
 
-func parseTextToolCalls(text string, tools []ai.Tool) []ai.ToolCall {
-	allowed := map[string]bool{}
-	for _, tool := range tools {
-		allowed[tool.Name] = true
-		if tool.OriginalName != "" {
-			allowed[tool.OriginalName] = true
-		}
+// executeAdditionalTextToolCalls runs text-encoded tool calls that accompany a
+// structured tool_calls response. Some OpenAI-compatible providers can mix the
+// two forms in a single assistant turn: for example, emitting a native
+// conformance_echo call while rendering a follow-up guarded delegate call as
+// <tool_call name="delegate">...</tool_call> text. Keep this fallback additive
+// and de-duplicate calls already represented in the structured tool_calls list.
+func (a *agentImpl) executeAdditionalTextToolCalls(ctx context.Context, reply string, tools []ai.Tool, existing []ai.ToolCall) ([]ai.ToolCall, string, bool) {
+	calls := parseTextToolCalls(reply, tools)
+	if len(calls) == 0 {
+		return nil, "", false
 	}
+
+	seen := map[string]bool{}
+	for _, call := range existing {
+		seen[textToolCallKey(call)] = true
+	}
+
+	handler := a.toolHandler()
+	out := make([]ai.ToolCall, 0, len(calls))
+	results := make([]string, 0, len(calls))
+	for i := range calls {
+		if seen[textToolCallKey(calls[i])] {
+			continue
+		}
+		result := handler(ctx, calls[i])
+		calls[i].Result = result.Content
+		if result.Refused != "" {
+			calls[i].Error = result.Refused
+		}
+		if result.Content != "" {
+			results = append(results, result.Content)
+		}
+		out = append(out, calls[i])
+	}
+	return out, strings.Join(results, "\n"), len(out) > 0
+}
+
+func textToolCallKey(call ai.ToolCall) string {
+	b, _ := json.Marshal(call.Input)
+	return call.Name + "\x00" + string(b)
+}
+
+func parseTextToolCalls(text string, tools []ai.Tool) []ai.ToolCall {
+	allowed := textToolNames(tools)
 	if len(allowed) == 0 {
 		return nil
 	}
 
+	if calls := decodeTaggedTextToolCalls(text, allowed); len(calls) > 0 {
+		return calls
+	}
 	for _, candidate := range jsonCandidates(text) {
 		if calls := decodeTextToolCalls(candidate, allowed); len(calls) > 0 {
 			return calls
@@ -65,6 +106,33 @@ func parseTextToolCalls(text string, tools []ai.Tool) []ai.ToolCall {
 	return nil
 }
 
+func textToolNames(tools []ai.Tool) map[string]string {
+	allowed := map[string]string{}
+	for _, tool := range tools {
+		addTextToolName(allowed, tool.Name, tool.Name)
+		if tool.OriginalName != "" {
+			addTextToolName(allowed, tool.OriginalName, tool.Name)
+		}
+	}
+	return allowed
+}
+
+func addTextToolName(allowed map[string]string, name, canonical string) {
+	if name == "" || canonical == "" {
+		return
+	}
+	allowed[name] = canonical
+	// Some OpenAI-compatible models describe an idempotent Add endpoint as a
+	// creation action and emit the otherwise-correct service tool with a Create
+	// suffix in text-only tool-call markup. Keep the fallback bounded by the
+	// offered service tool prefix so ordinary unknown tools remain ignored.
+	for _, suffix := range []string{"_Add", ".Add"} {
+		if strings.HasSuffix(name, suffix) {
+			allowed[strings.TrimSuffix(name, suffix)+strings.Replace(suffix, "Add", "Create", 1)] = canonical
+		}
+	}
+}
+
 func jsonCandidates(text string) []string {
 	trimmed := strings.TrimSpace(text)
 	var out []string
@@ -76,13 +144,18 @@ func jsonCandidates(text string) []string {
 			out = append(out, strings.TrimSpace(match[1]))
 		}
 	}
+	for _, match := range taggedToolCallBlock.FindAllStringSubmatch(text, -1) {
+		if len(match) > 1 {
+			out = append(out, strings.TrimSpace(match[1]))
+		}
+	}
 	if start, end := strings.IndexAny(text, "[{"), strings.LastIndexAny(text, "]}"); start >= 0 && end > start {
 		out = append(out, strings.TrimSpace(text[start:end+1]))
 	}
 	return out
 }
 
-func decodeTextToolCalls(candidate string, allowed map[string]bool) []ai.ToolCall {
+func decodeTextToolCalls(candidate string, allowed map[string]string) []ai.ToolCall {
 	var root any
 	if err := json.Unmarshal([]byte(candidate), &root); err != nil {
 		return nil
@@ -90,7 +163,7 @@ func decodeTextToolCalls(candidate string, allowed map[string]bool) []ai.ToolCal
 	return collectTextToolCalls(root, allowed)
 }
 
-func collectTextToolCalls(v any, allowed map[string]bool) []ai.ToolCall {
+func collectTextToolCalls(v any, allowed map[string]string) []ai.ToolCall {
 	switch x := v.(type) {
 	case []any:
 		var out []ai.ToolCall
@@ -111,19 +184,65 @@ func collectTextToolCalls(v any, allowed map[string]bool) []ai.ToolCall {
 		if input == nil {
 			input = call.Arguments
 		}
-		if name == "" || !allowed[name] || input == nil {
+		if name == "" || allowed[name] == "" || input == nil {
 			return nil
 		}
 		id := call.ID
 		if id == "" {
 			id = fmt.Sprintf("text-call-%s", strings.ReplaceAll(name, ".", "_"))
 		}
-		return []ai.ToolCall{{ID: id, Name: name, Input: input}}
+		return []ai.ToolCall{{ID: id, Name: allowed[name], Input: input}}
 	default:
 		return nil
 	}
 }
 
+func decodeTaggedTextToolCalls(text string, allowed map[string]string) []ai.ToolCall {
+	var out []ai.ToolCall
+	for _, match := range singleTaggedToolCall.FindAllStringSubmatch(text, -1) {
+		if len(match) < 3 {
+			continue
+		}
+		tag, body := match[1], strings.TrimSpace(match[2])
+		if calls := decodeTextToolCalls(body, allowed); len(calls) > 0 {
+			out = append(out, calls...)
+			continue
+		}
+		if calls := decodeTaggedTextToolCalls(body, allowed); len(calls) > 0 {
+			out = append(out, calls...)
+			continue
+		}
+		name := taggedToolName(tag)
+		if name == "" || allowed[name] == "" {
+			continue
+		}
+		var input map[string]any
+		if err := json.Unmarshal([]byte(body), &input); err != nil || input == nil {
+			continue
+		}
+		out = append(out, ai.ToolCall{
+			ID:    fmt.Sprintf("text-call-%s", strings.ReplaceAll(name, ".", "_")),
+			Name:  allowed[name],
+			Input: input,
+		})
+	}
+	return out
+}
+
+func taggedToolName(tag string) string {
+	for _, marker := range []string{"function=", "name=", "tool="} {
+		if idx := strings.Index(tag, marker); idx >= 0 {
+			name := strings.TrimSpace(tag[idx+len(marker):])
+			name = strings.Trim(name, `"'`)
+			if end := strings.IndexAny(name, " \t\r\n>"); end >= 0 {
+				name = name[:end]
+			}
+			return strings.Trim(name, `"'`)
+		}
+	}
+	return ""
+}
+
 func firstNestedToolCalls(m map[string]any) (any, bool) {
 	for _, key := range []string{"tool_calls", "toolCalls", "calls"} {
 		if v, ok := m[key]; ok {

agent/text_tool_calls_test.go

@@ -0,0 +1,58 @@
+package agent
+
+import (
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestParseTextToolCallsMiniMaxTaggedMarkup(t *testing.T) {
+	tools := []ai.Tool{{Name: "task_TaskService_Add"}}
+	reply := `<tool_calls>
+<tool_call>{"name":"task_TaskService_Add","arguments":{"title":"Design"}}</tool_call>
+<tool_call>{"name":"task_TaskService_Add","arguments":{"title":"Build"}}</tool_call>
+<tool_call>{"name":"task_TaskService_Add","arguments":{"title":"Ship"}}</tool_call>
+</tool_calls>`
+
+	calls := parseTextToolCalls(reply, tools)
+	if len(calls) != 3 {
+		t.Fatalf("parseTextToolCalls returned %d calls, want 3: %+v", len(calls), calls)
+	}
+	for i, want := range []string{"Design", "Build", "Ship"} {
+		if calls[i].Name != "task_TaskService_Add" {
+			t.Fatalf("call %d name = %q, want task_TaskService_Add", i, calls[i].Name)
+		}
+		if got := calls[i].Input["title"]; got != want {
+			t.Fatalf("call %d title = %v, want %q", i, got, want)
+		}
+	}
+}
+
+func TestParseTextToolCallsFunctionTaggedMarkup(t *testing.T) {
+	tools := []ai.Tool{{Name: "task_TaskService_Add"}}
+	reply := `<function=task_TaskService_Add>{"title":"Design"}</function>`
+
+	calls := parseTextToolCalls(reply, tools)
+	if len(calls) != 1 {
+		t.Fatalf("parseTextToolCalls returned %d calls, want 1: %+v", len(calls), calls)
+	}
+	if got := calls[0].Input["title"]; got != "Design" {
+		t.Fatalf("title = %v, want Design", got)
+	}
+}
+
+func TestParseTextToolCallsCreateAliasForAddTool(t *testing.T) {
+	tools := []ai.Tool{{Name: "task_TaskService_Add", OriginalName: "task.TaskService.Add"}}
+	reply := `<tool_call>{"name":"task_TaskService_Create","arguments":{"title":"Design"}}</tool_call>`
+
+	calls := parseTextToolCalls(reply, tools)
+	if len(calls) != 1 {
+		t.Fatalf("parseTextToolCalls returned %d calls, want 1: %+v", len(calls), calls)
+	}
+	if calls[0].Name != "task_TaskService_Add" {
+		t.Fatalf("call name = %q, want canonical task_TaskService_Add", calls[0].Name)
+	}
+	if got := calls[0].Input["title"]; got != "Design" {
+		t.Fatalf("title = %v, want Design", got)
+	}
+}

ai/anthropic/anthropic.go

@@ -2,6 +2,7 @@
 package anthropic
 
 import (
+	"bufio"
 	"bytes"
 	"context"
 	"encoding/json"
@@ -17,6 +18,7 @@ func init() {
 	ai.Register("anthropic", func(opts ...ai.Option) ai.Model {
 		return NewProvider(opts...)
 	})
+	ai.RegisterStream("anthropic")
 }
 
 // Provider implements the ai.Model interface for Anthropic Claude
@@ -156,9 +158,113 @@ func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.Gen
 	return resp, nil
 }
 
-// Stream generates a streaming response (not yet implemented)
+// Stream generates a streaming response from Anthropic's Messages SSE API.
 func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
-	return nil, fmt.Errorf("%w: anthropic provider", ai.ErrStreamingUnsupported)
+	apiReq := map[string]any{
+		"model":      p.opts.Model,
+		"max_tokens": anthropicMaxTokens(p.opts),
+		"system":     req.SystemPrompt,
+		"messages":   threadAnthropicMessages(req),
+		"stream":     true,
+	}
+	reqBody, err := json.Marshal(apiReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal stream request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/messages"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create stream request: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Accept", "text/event-stream")
+	httpReq.Header.Set("x-api-key", p.opts.APIKey)
+	httpReq.Header.Set("anthropic-version", "2023-06-01")
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("stream API request failed: %w", err)
+	}
+	if httpResp.StatusCode != http.StatusOK {
+		defer httpResp.Body.Close()
+		respBody, _ := io.ReadAll(httpResp.Body)
+		return nil, fmt.Errorf("stream API error (%s): %s", httpResp.Status, string(respBody))
+	}
+	return &streamReader{body: httpResp.Body, scanner: bufio.NewScanner(httpResp.Body)}, nil
+}
+
+type streamReader struct {
+	body    io.ReadCloser
+	scanner *bufio.Scanner
+	closed  bool
+}
+
+func (s *streamReader) Recv() (*ai.Response, error) {
+	for s.scanner.Scan() {
+		line := strings.TrimSpace(s.scanner.Text())
+		if line == "" || strings.HasPrefix(line, ":") || strings.HasPrefix(line, "event:") {
+			continue
+		}
+		if !strings.HasPrefix(line, "data:") {
+			continue
+		}
+		data := strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+		var chunk struct {
+			Type  string `json:"type"`
+			Delta struct {
+				Type string `json:"type"`
+				Text string `json:"text"`
+			} `json:"delta"`
+			Message struct {
+				Usage struct {
+					InputTokens  int `json:"input_tokens"`
+					OutputTokens int `json:"output_tokens"`
+				} `json:"usage"`
+			} `json:"message"`
+			Usage *struct {
+				InputTokens  int `json:"input_tokens"`
+				OutputTokens int `json:"output_tokens"`
+			} `json:"usage"`
+		}
+		if err := json.Unmarshal([]byte(data), &chunk); err != nil {
+			return nil, fmt.Errorf("failed to parse stream chunk: %w", err)
+		}
+		switch chunk.Type {
+		case "content_block_delta":
+			if chunk.Delta.Type == "text_delta" && chunk.Delta.Text != "" {
+				return &ai.Response{Reply: chunk.Delta.Text}, nil
+			}
+		case "message_start":
+			if chunk.Message.Usage.InputTokens > 0 || chunk.Message.Usage.OutputTokens > 0 {
+				return &ai.Response{Usage: usage(chunk.Message.Usage.InputTokens, chunk.Message.Usage.OutputTokens)}, nil
+			}
+		case "message_delta":
+			if chunk.Usage != nil {
+				return &ai.Response{Usage: usage(chunk.Usage.InputTokens, chunk.Usage.OutputTokens)}, nil
+			}
+		case "message_stop":
+			return nil, io.EOF
+		case "error":
+			return nil, fmt.Errorf("anthropic stream error: %s", data)
+		}
+	}
+	if err := s.scanner.Err(); err != nil {
+		return nil, err
+	}
+	return nil, io.EOF
+}
+
+func (s *streamReader) Close() error {
+	if s.closed {
+		return nil
+	}
+	s.closed = true
+	return s.body.Close()
+}
+
+func usage(input, output int) ai.Usage {
+	return ai.Usage{InputTokens: input, OutputTokens: output, TotalTokens: input + output}
 }
 
 // callAPI makes an HTTP request to the Anthropic API

ai/anthropic/anthropic_test.go

@@ -3,6 +3,10 @@ package anthropic
 import (
 	"context"
 	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"go-micro.dev/v6/ai"
@@ -81,15 +85,67 @@ func TestProvider_Generate_NoAPIKey(t *testing.T) {
 	}
 }
 
-func TestProvider_Stream_NotImplemented(t *testing.T) {
-	p := NewProvider()
+func TestProvider_Stream(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/messages" {
+			t.Fatalf("path = %q, want /v1/messages", r.URL.Path)
+		}
+		if got := r.Header.Get("Accept"); got != "text/event-stream" {
+			t.Fatalf("Accept = %q, want text/event-stream", got)
+		}
+		if got := r.Header.Get("x-api-key"); got != "test-key" {
+			t.Fatalf("x-api-key = %q, want test-key", got)
+		}
+		body, _ := io.ReadAll(r.Body)
+		if !strings.Contains(string(body), `"stream":true`) {
+			t.Fatalf("request body %s does not enable streaming", string(body))
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("event: message_start\n"))
+		_, _ = w.Write([]byte(`data: {"type":"message_start","message":{"usage":{"input_tokens":2}}}` + "\n\n"))
+		_, _ = w.Write([]byte("event: content_block_delta\n"))
+		_, _ = w.Write([]byte(`data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"hel"}}` + "\n\n"))
+		_, _ = w.Write([]byte("event: content_block_delta\n"))
+		_, _ = w.Write([]byte(`data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"lo"}}` + "\n\n"))
+		_, _ = w.Write([]byte("event: message_delta\n"))
+		_, _ = w.Write([]byte(`data: {"type":"message_delta","usage":{"output_tokens":3}}` + "\n\n"))
+		_, _ = w.Write([]byte("event: message_stop\n"))
+		_, _ = w.Write([]byte(`data: {"type":"message_stop"}` + "\n\n"))
+	}))
+	defer ts.Close()
+
+	p := NewProvider(ai.WithAPIKey("test-key"), ai.WithBaseURL(ts.URL))
 
 	req := &ai.Request{
 		Prompt: "Hello",
 	}
 
-	_, err := p.Stream(context.Background(), req)
-	if !errors.Is(err, ai.ErrStreamingUnsupported) {
-		t.Fatalf("Stream error = %v, want ErrStreamingUnsupported", err)
+	stream, err := p.Stream(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Stream failed: %v", err)
+	}
+	defer stream.Close()
+
+	var reply strings.Builder
+	var usage ai.Usage
+	for {
+		chunk, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatalf("Recv failed: %v", err)
+		}
+		reply.WriteString(chunk.Reply)
+		if chunk.Usage.TotalTokens > 0 {
+			usage = chunk.Usage
+		}
+	}
+	if got := reply.String(); got != "hello" {
+		t.Fatalf("reply = %q, want hello", got)
+	}
+	if usage.TotalTokens != 3 {
+		t.Fatalf("usage = %+v, want total 3", usage)
 	}
 }

ai/atlascloud/atlascloud.go

@@ -140,6 +140,7 @@ func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.Gen
 	}
 
 	if p.opts.ToolHandler != nil {
+		allToolCalls := append([]ai.ToolCall(nil), resp.ToolCalls...)
 		var toolResults []string
 		followUpMessages := append(messages, map[string]any{
 			"role":       "assistant",
@@ -163,11 +164,32 @@ func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.Gen
 			"model":    p.opts.Model,
 			"messages": followUpMessages,
 		}
+		if len(tools) > 0 {
+			// Keep the tool schema available during the follow-up turn. Minimax
+			// models behind Atlas Cloud sometimes call one required tool, inspect
+			// that result, and then issue a second tool call (for example a guarded
+			// delegate conformance check) instead of completing immediately.
+			followUpReq["tools"] = tools
+		}
 
 		followUpResp, _, err := p.callAPI(ctx, "tool-follow-up", followUpReq)
 		if err != nil {
 			return nil, err
 		}
+		if len(followUpResp.ToolCalls) > 0 {
+			for i := range followUpResp.ToolCalls {
+				result := p.opts.ToolHandler(ctx, followUpResp.ToolCalls[i])
+				if result.Refused != "" {
+					followUpResp.ToolCalls[i].Error = result.Refused
+				}
+				if result.Content != "" {
+					followUpResp.ToolCalls[i].Result = result.Content
+					toolResults = append(toolResults, result.Content)
+				}
+			}
+			allToolCalls = append(allToolCalls, followUpResp.ToolCalls...)
+			resp.ToolCalls = allToolCalls
+		}
 		if followUpResp.Reply != "" {
 			resp.Answer = followUpResp.Reply
 		} else if len(toolResults) > 0 {

ai/atlascloud/atlascloud_test.go

@@ -289,6 +289,71 @@ func TestProvider_GenerateMinimaxToolRequests(t *testing.T) {
 	}
 }
 
+func TestProvider_GenerateExecutesFollowUpToolCall(t *testing.T) {
+	var bodies []map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Fatalf("decode request: %v", err)
+		}
+		bodies = append(bodies, body)
+		w.Header().Set("Content-Type", "application/json")
+		switch len(bodies) {
+		case 1:
+			_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"","tool_calls":[{"id":"call-1","function":{"name":"conformance_echo","arguments":"{\"value\":\"agent-conformance\"}"}}]}}]}`))
+		case 2:
+			_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"","tool_calls":[{"id":"call-2","function":{"name":"delegate","arguments":"{\"task\":\"summarize the conformance marker\",\"to\":\"blocked-reviewer\"}"}}]}}]}`))
+		default:
+			t.Fatalf("unexpected API call %d", len(bodies))
+		}
+	}))
+	defer ts.Close()
+
+	var sawEcho, sawDelegate bool
+	p := NewProvider(
+		ai.WithAPIKey("test-key"),
+		ai.WithBaseURL(ts.URL),
+		ai.WithToolHandler(func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+			switch call.Name {
+			case "conformance_echo":
+				sawEcho = true
+				return ai.ToolResult{ID: call.ID, Content: `{"marker":"agent-conformance-ok"}`}
+			case "delegate":
+				sawDelegate = true
+				return ai.ToolResult{ID: call.ID, Refused: ai.RefusedApproval, Content: "blocked by policy"}
+			default:
+				t.Fatalf("unexpected tool call %+v", call)
+				return ai.ToolResult{}
+			}
+		}),
+	)
+	resp, err := p.Generate(context.Background(), &ai.Request{
+		Prompt: "run conformance",
+		Tools: []ai.Tool{
+			{Name: "conformance_echo", Description: "echo conformance marker", Properties: map[string]any{"value": map[string]any{"type": "string"}}},
+			{Name: "delegate", Description: "delegate work", Properties: map[string]any{"task": map[string]any{"type": "string"}, "to": map[string]any{"type": "string"}}},
+		},
+	})
+	if err != nil {
+		t.Fatalf("Generate returned error: %v", err)
+	}
+	if !sawEcho || !sawDelegate {
+		t.Fatalf("sawEcho=%v sawDelegate=%v, want both tools executed", sawEcho, sawDelegate)
+	}
+	if len(resp.ToolCalls) != 2 {
+		t.Fatalf("ToolCalls = %+v, want echo and delegate", resp.ToolCalls)
+	}
+	if resp.ToolCalls[1].Name != "delegate" || resp.ToolCalls[1].Error != ai.RefusedApproval {
+		t.Fatalf("follow-up delegate = %+v, want refused delegate", resp.ToolCalls[1])
+	}
+	if !strings.Contains(resp.Answer, "blocked by policy") {
+		t.Fatalf("Answer = %q, want follow-up tool result", resp.Answer)
+	}
+	if _, ok := bodies[1]["tools"].([]any); !ok {
+		t.Fatalf("follow-up request did not include tools: %#v", bodies[1])
+	}
+}
+
 func TestProvider_GenerateToolCallHTTPErrorIncludesRequestContext(t *testing.T) {
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, `{"code":400,"msg":"bad request"}`, http.StatusBadRequest)

ai/capabilities_test.go

@@ -35,7 +35,7 @@ func TestRegisteredProviders(t *testing.T) {
 	}
 
 	got = ai.RegisteredProviders("stream")
-	want = []string{"atlascloud", "groq", "minimax", "mistral", "openai", "together"}
+	want = []string{"anthropic", "atlascloud", "groq", "minimax", "mistral", "openai", "together"}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("RegisteredProviders(stream) = %#v, want %#v", got, want)
 	}
@@ -44,7 +44,7 @@ func TestRegisteredProviders(t *testing.T) {
 func TestCapabilityRows(t *testing.T) {
 	got := ai.CapabilityRows()
 	want := []ai.CapabilityRow{
-		{Provider: "anthropic", Capabilities: ai.Capabilities{Model: true}},
+		{Provider: "anthropic", Capabilities: ai.Capabilities{Model: true, Stream: true}},
 		{Provider: "atlascloud", Capabilities: ai.Capabilities{Model: true, Image: true, Video: true, Stream: true}},
 		{Provider: "gemini", Capabilities: ai.Capabilities{Model: true}},
 		{Provider: "groq", Capabilities: ai.Capabilities{Model: true, Stream: true}},
@@ -90,7 +90,7 @@ func TestRegisterStream(t *testing.T) {
 	}
 
 	got := ai.RegisteredProviders("stream")
-	want := []string{"atlascloud", "groq", "minimax", "mistral", "openai", "test-stream", "together"}
+	want := []string{"anthropic", "atlascloud", "groq", "minimax", "mistral", "openai", "test-stream", "together"}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("RegisteredProviders(stream) = %#v, want %#v", got, want)
 	}

ai/stream_conformance_test.go

@@ -215,6 +215,7 @@ func TestConfiguredProviderStreamsSkipWithoutCredentials(t *testing.T) {
 		{provider: "mistral", keyEnv: "MISTRAL_API_KEY", modelEnv: "MISTRAL_MODEL"},
 		{provider: "together", keyEnv: "TOGETHER_API_KEY", modelEnv: "TOGETHER_MODEL"},
 		{provider: "atlascloud", keyEnv: "ATLASCLOUD_API_KEY", modelEnv: "ATLASCLOUD_MODEL"},
+		{provider: "anthropic", keyEnv: "ANTHROPIC_API_KEY", modelEnv: "ANTHROPIC_MODEL"},
 	} {
 		tc := tc
 		t.Run(tc.provider, func(t *testing.T) {
@@ -256,7 +257,7 @@ func TestConfiguredProviderStreamsSkipWithoutCredentials(t *testing.T) {
 }
 
 func TestUnsupportedProvidersReturnStreamingUnsupportedAndStayUnregistered(t *testing.T) {
-	for _, provider := range []string{"anthropic", "gemini"} {
+	for _, provider := range []string{"gemini"} {
 		provider := provider
 		t.Run(provider, func(t *testing.T) {
 			if caps := ai.ProviderCapabilities(provider); caps.Stream {

cmd/micro/README.md

@@ -646,6 +646,7 @@ micro loop verify    # check a repo is wired correctly
 | Builder | `loop-builder.yml` | Builds the top open item as a single-concern PR, auto-merged on green CI |
 | Triage | `loop-triage.yml` | Turns CI failures into scoped fix issues, back into the queue |
 | Coherence | `loop-coherence.yml` | Keeps README/docs/CHANGELOG aligned with the North Star *(opt-in)* |
+| Security | `loop-security.yml` | Audits for vulnerabilities and files them; never auto-merges fixes, never publishes exploit detail *(opt-in)* |
 | Release | `loop-release.yml` | Cuts the next patch tag when the branch has new commits *(opt-in)* |
 
 The workflows are the **mechanism**; each dispatch role's instruction is an editable file in `.github/loop/prompts/` — the **policy**. Edit those prompts (and `.github/loop/NORTH_STAR.md`) to steer the loop without touching the CLI. That split is what lets go-micro itself use `micro loop` while keeping its own richer prompts.

cmd/micro/cli/agent/agent.go

@@ -14,6 +14,30 @@ import (
 	"go-micro.dev/v6/store"
 )
 
+const noSecretDemoHelp = `No-secret first-agent demo
+
+Use this when you want the fastest provider-free agent success path before
+configuring API keys. It runs the maintained support/first-agent transcript with
+the deterministic mock model used by CI:
+
+  go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1
+
+What this proves:
+  - service tools can be called by an agent
+  - chat behavior is exercised without contacting a live provider
+  - run history can be inspected after the prompt
+
+After it passes:
+  - Build your own service-backed agent: https://go-micro.dev/docs/guides/your-first-agent.html
+  - Diagnose provider-backed chat:     https://go-micro.dev/docs/guides/debugging-agents.html
+  - Walk the full 0→hero lifecycle:    https://go-micro.dev/docs/guides/zero-to-hero.html
+
+Use live-provider chat when you are ready for real model behavior:
+  micro agent preflight
+  micro run
+  micro chat
+  micro inspect agent <name>`
+
 func init() {
 	cmd.Register(&cli.Command{
 		Name:      "runs",
@@ -34,16 +58,36 @@ func init() {
 
 	cmd.Register(&cli.Command{
 		Name:  "agent",
-		Usage: "Manage AI agents",
+		Usage: "Manage AI agents (try: micro agent demo)",
 		Subcommands: []*cli.Command{
 			{
-				Name:    "preflight",
-				Aliases: []string{"doctor"},
-				Usage:   "Check local prerequisites before the first provider-backed agent",
+				Name:  "demo",
+				Usage: "Show the no-secret first-agent demo command",
+				Description: `Print the provider-free first-agent path for new developers:
+the deterministic mock-model transcript, when to use it, and where to go next
+for live-provider chat and inspect/debugging.`,
+				Action: func(c *cli.Context) error {
+					fmt.Fprintln(c.App.Writer, noSecretDemoHelp)
+					return nil
+				},
+			},
+			{
+				Name:  "preflight",
+				Usage: "Check local prerequisites before the first provider-backed agent",
 				Action: func(c *cli.Context) error {
 					return runAgentPreflight(os.Stdout, defaultPreflightDeps())
 				},
 			},
+			{
+				Name:  "doctor",
+				Usage: "Diagnose chat and inspect recovery after micro run",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "gateway", Value: "http://localhost:8080", Usage: "Gateway URL started by micro run"},
+				},
+				Action: func(c *cli.Context) error {
+					return runAgentDoctor(os.Stdout, defaultDoctorDeps(), c.String("gateway"))
+				},
+			},
 			{
 				Name:  "list",
 				Usage: "List registered agents",

cmd/micro/cli/agent/doctor.go

@@ -0,0 +1,179 @@
+package agent
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	goagent "go-micro.dev/v6/agent"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+type doctorDeps struct {
+	getenv       func(string) string
+	httpGet      func(string) (*http.Response, error)
+	listServices func() ([]*registry.Service, error)
+	getService   func(string) ([]*registry.Service, error)
+	listRuns     func(string) ([]goagent.RunSummary, error)
+}
+
+func defaultDoctorDeps() doctorDeps {
+	client := &http.Client{Timeout: 2 * time.Second}
+	return doctorDeps{
+		getenv:       defaultPreflightDeps().getenv,
+		httpGet:      client.Get,
+		listServices: registry.ListServices,
+		getService:   registry.GetService,
+		listRuns: func(name string) ([]goagent.RunSummary, error) {
+			return goagent.ListRunSummariesWithOptions(store.DefaultStore, name, goagent.RunListOptions{Limit: 1})
+		},
+	}
+}
+
+func runAgentDoctor(w io.Writer, deps doctorDeps, gateway string) error {
+	if gateway == "" {
+		gateway = "http://localhost:8080"
+	}
+	gateway = strings.TrimRight(gateway, "/")
+	checks := agentDoctorChecks(deps, gateway)
+	failures := 0
+	fmt.Fprintln(w, "First-agent recovery doctor")
+	for _, check := range checks {
+		mark := "✓"
+		if !check.OK {
+			mark = "✗"
+			failures++
+		}
+		fmt.Fprintf(w, "  %s %s — %s\n", mark, check.Name, check.Detail)
+		if !check.OK && check.Fix != "" {
+			fmt.Fprintf(w, "    Fix: %s\n", check.Fix)
+		}
+		if !check.OK && check.Next != "" {
+			fmt.Fprintf(w, "    Next: %s\n", check.Next)
+		}
+	}
+	if failures > 0 {
+		return fmt.Errorf("first-agent doctor found %d recovery boundary issue(s)", failures)
+	}
+	fmt.Fprintln(w, "\nReady: gateway, agent registration, chat settings, and inspect history are reachable.")
+	return nil
+}
+
+func agentDoctorChecks(deps doctorDeps, gateway string) []preflightCheck {
+	if deps.getenv == nil {
+		deps.getenv = defaultPreflightDeps().getenv
+	}
+	if deps.httpGet == nil {
+		deps.httpGet = http.Get
+	}
+	if deps.listServices == nil {
+		deps.listServices = registry.ListServices
+	}
+	if deps.getService == nil {
+		deps.getService = registry.GetService
+	}
+	if deps.listRuns == nil {
+		deps.listRuns = func(name string) ([]goagent.RunSummary, error) {
+			return goagent.ListRunSummariesWithOptions(store.DefaultStore, name, goagent.RunListOptions{Limit: 1})
+		}
+	}
+
+	checks := []preflightCheck{checkGateway(deps, gateway), checkChatSettings(deps, gateway)}
+	agents, regCheck := checkAgentRegistration(deps)
+	checks = append(checks, regCheck)
+	checks = append(checks, checkRunHistory(deps, agents))
+	checks = append(checks, checkProviderConfig(deps))
+	return checks
+}
+
+func checkGateway(deps doctorDeps, gateway string) preflightCheck {
+	resp, err := deps.httpGet(gateway + "/agent")
+	if err != nil {
+		return preflightCheck{Name: "gateway /agent", Detail: err.Error(), Fix: "Start the local gateway with `micro run`, or pass the matching URL with `micro agent doctor --gateway http://localhost:<port>`.", Next: "Then open " + gateway + "/agent or retry `micro chat`."}
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return preflightCheck{Name: "gateway /agent", Detail: fmt.Sprintf("%s returned %s", gateway+"/agent", resp.Status), Fix: "Confirm `micro run` is serving the web gateway and that auth/proxy settings are not blocking /agent.", Next: "See docs/guides/debugging-agents.html#chat-and-gateway-failures."}
+	}
+	return preflightCheck{Name: "gateway /agent", OK: true, Detail: gateway + "/agent is reachable"}
+}
+
+func checkChatSettings(deps doctorDeps, gateway string) preflightCheck {
+	resp, err := deps.httpGet(gateway + "/api/agent/settings")
+	if err != nil {
+		return preflightCheck{Name: "chat settings endpoint", Detail: err.Error(), Fix: "Keep `micro run` running and retry; the playground uses /api/agent/settings before chat prompts.", Next: "See docs/guides/debugging-agents.html#chat-and-gateway-failures."}
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return preflightCheck{Name: "chat settings endpoint", Detail: fmt.Sprintf("returned %s", resp.Status), Fix: "Check gateway auth/proxy configuration or use the Agent settings page to confirm chat settings load.", Next: "See docs/guides/debugging-agents.html#provider-failures."}
+	}
+	var settings map[string]string
+	_ = json.NewDecoder(resp.Body).Decode(&settings)
+	if settings["provider"] != "" || settings["model"] != "" || settings["api_key"] != "" {
+		return preflightCheck{Name: "chat settings endpoint", OK: true, Detail: "reachable with saved provider settings"}
+	}
+	return preflightCheck{Name: "chat settings endpoint", OK: true, Detail: "reachable; no saved provider settings"}
+}
+
+func checkAgentRegistration(deps doctorDeps) ([]string, preflightCheck) {
+	services, err := deps.listServices()
+	if err != nil {
+		return nil, preflightCheck{Name: "agent registration", Detail: err.Error(), Fix: "Keep the scaffolded agent process running under `micro run` and retry `micro agent list`.", Next: "See docs/guides/your-first-agent.html#run-your-agent."}
+	}
+	var agents []string
+	for _, svc := range services {
+		records, err := deps.getService(svc.Name)
+		if err != nil || len(records) == 0 {
+			continue
+		}
+		if serviceIsAgent(records[0]) {
+			agents = append(agents, svc.Name)
+		}
+	}
+	if len(agents) == 0 {
+		return nil, preflightCheck{Name: "agent registration", Detail: "no registered agent services found", Fix: "Start an agent project with `micro run` and confirm `micro agent list` shows it.", Next: "Use docs/guides/no-secret-first-agent.html for a deterministic no-provider agent."}
+	}
+	return agents, preflightCheck{Name: "agent registration", OK: true, Detail: "found " + strings.Join(agents, ", ")}
+}
+
+func serviceIsAgent(svc *registry.Service) bool {
+	if svc.Metadata != nil && svc.Metadata["type"] == "agent" {
+		return true
+	}
+	for _, node := range svc.Nodes {
+		if node.Metadata != nil && node.Metadata["type"] == "agent" {
+			return true
+		}
+	}
+	return false
+}
+
+func checkRunHistory(deps doctorDeps, agents []string) preflightCheck {
+	if len(agents) == 0 {
+		return preflightCheck{Name: "inspect run history", Detail: "skipped because no agent is registered", Fix: "Fix agent registration first, then chat once and run `micro inspect agent <name>`.", Next: "See docs/guides/debugging-agents.html#inspect-run-history."}
+	}
+	for _, name := range agents {
+		runs, err := deps.listRuns(name)
+		if err != nil {
+			return preflightCheck{Name: "inspect run history", Detail: err.Error(), Fix: "Ensure the local store is writable and retry `micro inspect agent " + name + "`.", Next: "See docs/guides/debugging-agents.html#inspect-run-history."}
+		}
+		if len(runs) > 0 {
+			return preflightCheck{Name: "inspect run history", OK: true, Detail: "recent runs available for " + name}
+		}
+	}
+	return preflightCheck{Name: "inspect run history", Detail: "no recorded agent runs yet", Fix: "Send one prompt with `micro chat` or the /agent playground, then run `micro inspect agent " + agents[0] + "`.", Next: "See docs/guides/your-first-agent.html#inspect-what-happened."}
+}
+
+func checkProviderConfig(deps doctorDeps) preflightCheck {
+	check := checkProviderKey(preflightDeps{getenv: deps.getenv})
+	check.Name = "provider configuration"
+	if !check.OK {
+		check.Detail = "no provider key found for live LLM chat"
+		check.Fix = "For provider-backed chat, export MICRO_AI_API_KEY or a provider-specific key; for no-secret recovery, use the mock-model walkthrough."
+	}
+	return check
+}

cmd/micro/cli/agent/doctor_test.go

@@ -0,0 +1,75 @@
+package agent
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	goagent "go-micro.dev/v6/agent"
+	"go-micro.dev/v6/registry"
+)
+
+func doctorHTTP(status int, body string) func(string) (*http.Response, error) {
+	return func(string) (*http.Response, error) {
+		return &http.Response{StatusCode: status, Status: "200 OK", Body: io.NopCloser(strings.NewReader(body))}, nil
+	}
+}
+
+func TestRunAgentDoctorPassesWhenRecoveryBoundariesReachable(t *testing.T) {
+	deps := doctorDeps{
+		getenv: func(key string) string {
+			if key == "MICRO_AI_API_KEY" {
+				return "set"
+			}
+			return ""
+		},
+		httpGet: doctorHTTP(200, `{"provider":"anthropic","model":"claude"}`),
+		listServices: func() ([]*registry.Service, error) {
+			return []*registry.Service{{Name: "assistant"}}, nil
+		},
+		getService: func(name string) ([]*registry.Service, error) {
+			return []*registry.Service{{Name: name, Metadata: map[string]string{"type": "agent"}}}, nil
+		},
+		listRuns: func(name string) ([]goagent.RunSummary, error) {
+			return []goagent.RunSummary{{RunID: "run-1", Status: "done"}}, nil
+		},
+	}
+	var out bytes.Buffer
+	if err := runAgentDoctor(&out, deps, "http://example.test"); err != nil {
+		t.Fatalf("runAgentDoctor() error = %v\n%s", err, out.String())
+	}
+	got := out.String()
+	for _, want := range []string{"First-agent recovery doctor", "✓ gateway /agent", "✓ chat settings endpoint", "✓ agent registration", "✓ inspect run history", "✓ provider configuration", "Ready:"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("output missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestRunAgentDoctorReportsActionableRecoveryFailures(t *testing.T) {
+	deps := doctorDeps{
+		getenv:  func(string) string { return "" },
+		httpGet: func(string) (*http.Response, error) { return nil, errors.New("connection refused") },
+		listServices: func() ([]*registry.Service, error) {
+			return []*registry.Service{{Name: "greeter"}}, nil
+		},
+		getService: func(name string) ([]*registry.Service, error) {
+			return []*registry.Service{{Name: name}}, nil
+		},
+		listRuns: func(name string) ([]goagent.RunSummary, error) { return nil, nil },
+	}
+	var out bytes.Buffer
+	err := runAgentDoctor(&out, deps, "http://localhost:8080")
+	if err == nil {
+		t.Fatal("runAgentDoctor() error = nil")
+	}
+	got := out.String()
+	for _, want := range []string{"✗ gateway /agent", "micro run", "✗ chat settings endpoint", "✗ agent registration", "micro agent list", "✗ inspect run history", "micro inspect agent <name>", "✗ provider configuration", "docs/guides/no-secret-first-agent.html"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("output missing %q:\n%s", want, got)
+		}
+	}
+}

cmd/micro/cli/cli.go

@@ -26,25 +26,33 @@ import (
 
 const docsWayfinding = `First-agent and 0→hero docs:
 
-  1. No-secret first-agent transcript
+  1. Start with the no-secret CLI demo
+       micro agent demo
+     This prints the maintained support-agent transcript command so you can
+     prove service tools, mock-model chat, and inspectable run history without
+     configuring a provider key.
+
+  2. No-secret first-agent transcript
      https://go-micro.dev/docs/guides/no-secret-first-agent.html
      Run the maintained support agent without a provider key:
        go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1
 
-  2. Your First Agent
+  3. Your First Agent
      https://go-micro.dev/docs/guides/your-first-agent.html
      Build a service-backed agent, then use:
        micro agent preflight
        micro run
        micro chat
+       micro agent doctor
 
-  3. Debugging your agent
+  4. Debugging your agent
      https://go-micro.dev/docs/guides/debugging-agents.html
      Inspect agent runs and memory with:
+       micro agent doctor
        micro inspect agent
        micro runs <agent>
 
-  4. 0→hero Reference
+  5. 0→hero Reference
      https://go-micro.dev/docs/guides/zero-to-hero.html
      Walk the scaffold → run → chat → inspect → deploy dry-run lifecycle.`
 

cmd/micro/cli/new/contract_test.go

@@ -1,6 +1,7 @@
 package new
 
 import (
+	"bytes"
 	"errors"
 	"flag"
 	"os"
@@ -57,6 +58,44 @@ func TestZeroToOneNoMCPContract(t *testing.T) {
 	generated.call(t, "Bob", "Hello Bob")
 }
 
+func TestPrintNextStepsSurfacesFirstAgentPath(t *testing.T) {
+	var out bytes.Buffer
+	printNextSteps(&out, "helloworld", false)
+
+	for _, want := range []string{
+		"cd helloworld",
+		"micro agent preflight",
+		"go run .",
+		"micro chat",
+		"micro inspect agent",
+		"micro agent demo",
+		"micro docs",
+		"your-first-agent.html",
+		"zero-to-hero.html",
+		"http://localhost:3001/mcp/tools",
+	} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("next steps missing %q:\n%s", want, out.String())
+		}
+	}
+}
+
+func TestPrintNextStepsNoMCPSkipsMCPHints(t *testing.T) {
+	var out bytes.Buffer
+	printNextSteps(&out, "worker", true)
+
+	for _, want := range []string{"micro agent preflight", "micro chat", "micro inspect agent", "micro agent demo", "micro docs"} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("--no-mcp next steps missing %q:\n%s", want, out.String())
+		}
+	}
+	for _, notWant := range []string{"http://localhost:3001/mcp/tools", "micro mcp serve"} {
+		if strings.Contains(out.String(), notWant) {
+			t.Fatalf("--no-mcp next steps should not include %q:\n%s", notWant, out.String())
+		}
+	}
+}
+
 type generatedService struct {
 	dir      string
 	repoRoot string

cmd/micro/cli/new/new.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"fmt"
 	"go/build"
+	"io"
 	"os"
 	"os/exec"
 	"os/signal"
@@ -280,18 +281,31 @@ func Run(ctx *cli.Context) error {
 
 	fmt.Println()
 	fmt.Printf("  \033[32m✓\033[0m Service \033[36m%s\033[0m created\n\n", dir)
-	fmt.Println("  Next steps:")
-	fmt.Printf("    cd %s\n", dir)
-	fmt.Println("    go run .")
-	if !noMCP {
-		fmt.Println()
-		fmt.Printf("    MCP tools   \033[36mhttp://localhost:3001/mcp/tools\033[0m\n")
-		fmt.Println("    Claude Code \033[2mmicro mcp serve\033[0m")
-	}
-	fmt.Println()
+	printNextSteps(os.Stdout, dir, noMCP)
 	return nil
 }
 
+func printNextSteps(w io.Writer, dir string, noMCP bool) {
+	fmt.Fprintln(w, "  Next steps:")
+	fmt.Fprintf(w, "    cd %s\n", dir)
+	fmt.Fprintln(w, "    micro agent preflight")
+	fmt.Fprintln(w, "    go run .")
+	fmt.Fprintln(w, "    micro chat")
+	fmt.Fprintln(w, "    micro inspect agent")
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, "  First-agent path:")
+	fmt.Fprintln(w, "    micro agent demo")
+	fmt.Fprintln(w, "    micro docs")
+	fmt.Fprintln(w, "    https://go-micro.dev/docs/guides/your-first-agent.html")
+	fmt.Fprintln(w, "    https://go-micro.dev/docs/guides/zero-to-hero.html")
+	if !noMCP {
+		fmt.Fprintln(w)
+		fmt.Fprintf(w, "    MCP tools   \033[36mhttp://localhost:3001/mcp/tools\033[0m\n")
+		fmt.Fprintln(w, "    Claude Code \033[2mmicro mcp serve\033[0m")
+	}
+	fmt.Fprintln(w)
+}
+
 func selectTemplates(name string, noMCP bool) (mainTmpl, handlerTmpl, protoTmpl string) {
 	switch name {
 	case "crud":

cmd/micro/first_agent_walkthrough_test.go

@@ -30,6 +30,12 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 	if !subcommands["agent"]["preflight"] {
 		t.Fatal("first-agent walkthrough missing preflight boundary: agent preflight")
 	}
+	if !subcommands["agent"]["demo"] {
+		t.Fatal("first-agent walkthrough missing no-secret boundary: agent demo")
+	}
+	if !subcommands["agent"]["doctor"] {
+		t.Fatal("first-agent walkthrough missing recovery boundary: agent doctor")
+	}
 	if !subcommands["inspect"]["agent"] {
 		t.Fatal("first-agent walkthrough missing inspect boundary: inspect agent")
 	}
@@ -49,7 +55,11 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 	if err := docs.Action(cli.NewContext(app, nil, nil)); err != nil {
 		t.Fatalf("micro docs failed: %v", err)
 	}
+	if demoIdx, guideIdx := strings.Index(out.String(), "micro agent demo"), strings.Index(out.String(), "no-secret-first-agent.html"); demoIdx < 0 || guideIdx < 0 || demoIdx > guideIdx {
+		t.Fatalf("micro docs should lead with micro agent demo before guide links:\n%s", out.String())
+	}
 	for _, want := range []string{
+		"micro agent demo",
 		"no-secret-first-agent.html",
 		"your-first-agent.html",
 		"debugging-agents.html",
@@ -57,12 +67,38 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 		"micro agent preflight",
 		"micro run",
 		"micro chat",
+		"micro agent doctor",
 		"micro inspect agent",
 	} {
 		if !strings.Contains(out.String(), want) {
 			t.Fatalf("micro docs output missing %q:\n%s", want, out.String())
 		}
 	}
+
+	agent := commandByName(t, "agent")
+	if !strings.Contains(agent.Usage, "micro agent demo") {
+		t.Fatalf("micro agent help should advertise the no-secret demo; usage was %q", agent.Usage)
+	}
+	demo := subcommandByName(t, agent, "demo")
+	out.Reset()
+	if err := demo.Action(cli.NewContext(app, nil, nil)); err != nil {
+		t.Fatalf("micro agent demo failed: %v", err)
+	}
+	for _, want := range []string{
+		"No-secret first-agent demo",
+		"go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1",
+		"provider-free",
+		"micro agent preflight",
+		"micro chat",
+		"micro inspect agent <name>",
+		"your-first-agent.html",
+		"debugging-agents.html",
+		"zero-to-hero.html",
+	} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("micro agent demo output missing %q:\n%s", want, out.String())
+		}
+	}
 }
 
 func commandByName(t *testing.T, name string) *cli.Command {
@@ -75,3 +111,14 @@ func commandByName(t *testing.T, name string) *cli.Command {
 	t.Fatalf("missing command %q", name)
 	return nil
 }
+
+func subcommandByName(t *testing.T, command *cli.Command, name string) *cli.Command {
+	t.Helper()
+	for _, subcommand := range command.Subcommands {
+		if subcommand.Name == name {
+			return subcommand
+		}
+	}
+	t.Fatalf("missing subcommand %q under %q", name, command.Name)
+	return nil
+}

cmd/micro/inspect/inspect.go

@@ -85,6 +85,12 @@ func writeAgentInspection(w io.Writer, name string, runs []goagent.RunSummary, a
 	fmt.Fprintf(w, "  Agent %q runs\n", name)
 	for _, run := range runs {
 		fmt.Fprintf(w, "  %s  status=%s  events=%d  last=%s", run.RunID, run.Status, run.Events, run.LastKind)
+		if run.Checkpoint != "" {
+			fmt.Fprintf(w, "  checkpoint=%s", run.Checkpoint)
+		}
+		if run.Stage != "" {
+			fmt.Fprintf(w, "  stage=%s", run.Stage)
+		}
 		if run.LastError != "" {
 			fmt.Fprintf(w, "  error=%q", run.LastError)
 		}
@@ -92,10 +98,25 @@ func writeAgentInspection(w io.Writer, name string, runs []goagent.RunSummary, a
 			fmt.Fprintf(w, "  trace=%s", shortID(run.TraceID))
 		}
 		fmt.Fprintln(w)
+		if isResumableAgentRun(run) {
+			fmt.Fprintf(w, "    resume: call micro.AgentResume(ctx, agent, %q) after recreating the agent with the same checkpoint store\n", run.RunID)
+		}
+		if run.Stage == "input-required" {
+			fmt.Fprintf(w, "    input:  call micro.AgentResumeInput(ctx, agent, %q, input) to continue the paused run\n", run.RunID)
+		}
 	}
 	return nil
 }
 
+func isResumableAgentRun(run goagent.RunSummary) bool {
+	switch run.Status {
+	case "running", "error", "failed", "refused":
+		return run.Checkpoint != "done" || run.Stage != ""
+	default:
+		return false
+	}
+}
+
 func inspectFlow(c *cli.Context) error {
 	name := c.Args().First()
 	if name == "" {

cmd/micro/inspect/inspect_test.go

@@ -11,13 +11,27 @@ import (
 )
 
 func TestWriteAgentInspectionIncludesActionableBreadcrumbs(t *testing.T) {
-	runs := []goagent.RunSummary{{RunID: "run-1", Status: "error", Events: 4, LastKind: "tool", LastError: "boom", TraceID: "1234567890abcdef"}}
+	runs := []goagent.RunSummary{{RunID: "run-1", Status: "error", Events: 4, LastKind: "tool", LastError: "boom", TraceID: "1234567890abcdef", Checkpoint: "failed", Stage: "ask"}}
 	var out bytes.Buffer
 	if err := writeAgentInspection(&out, "support", runs, false); err != nil {
 		t.Fatal(err)
 	}
 	got := out.String()
-	for _, want := range []string{"Agent \"support\" runs", "run-1", "status=error", "events=4", "last=tool", `error="boom"`, "trace=1234567890ab"} {
+	for _, want := range []string{"Agent \"support\" runs", "run-1", "status=error", "events=4", "last=tool", "checkpoint=failed", "stage=ask", `error="boom"`, "trace=1234567890ab", `micro.AgentResume(ctx, agent, "run-1")`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("output missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestWriteAgentInspectionIncludesInputResumeBreadcrumb(t *testing.T) {
+	runs := []goagent.RunSummary{{RunID: "run-input", Status: "running", Events: 3, LastKind: "checkpoint", Checkpoint: "paused", Stage: "input-required"}}
+	var out bytes.Buffer
+	if err := writeAgentInspection(&out, "support", runs, false); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	for _, want := range []string{"checkpoint=paused", "stage=input-required", `micro.AgentResumeInput(ctx, agent, "run-input", input)`} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("output missing %q:\n%s", want, got)
 		}

cmd/micro/loop/loop.go

@@ -71,10 +71,11 @@ var dispatchRoles = map[string]dispatchRole{
 	"planner":   {"Loop: Planner", "Loop: planning review", "loop-planner", "planner-cron", "0 * * * *"},
 	"builder":   {"Loop: Builder", "Loop: build increment", "loop-builder", "builder-cron", "30 * * * *"},
 	"coherence": {"Loop: Coherence", "Loop: coherence review", "loop-coherence", "coherence-cron", "0 7 * * *"},
+	"security":  {"Loop: Security", "Loop: security review", "loop-security", "security-cron", "0 6 * * 1"},
 }
 
 // allRoles is the full set, in a stable order, for --roles=all and help text.
-var allRoles = []string{"planner", "builder", "triage", "coherence", "release"}
+var allRoles = []string{"planner", "builder", "triage", "coherence", "security", "release"}
 
 const (
 	promptDir = ".github/loop/prompts"
@@ -95,6 +96,7 @@ Roles (choose with --roles, default: planner,builder,triage):
   builder    builds the top open item as a single-concern PR (auto-merged on green CI)
   triage     turns CI failures into scoped fix issues back into the queue
   coherence  keeps README/docs/CHANGELOG aligned with the North Star
+  security   audits for vulnerabilities and files them (fixes stay human-reviewed)
   release    cuts the next patch tag when the branch has new commits
 
 Each dispatch role's instruction is an editable file in .github/loop/prompts/ —
@@ -127,6 +129,7 @@ Examples:
 					&cli.StringFlag{Name: "planner-cron", Usage: "Cron schedule for the planner", Value: "0 * * * *"},
 					&cli.StringFlag{Name: "builder-cron", Usage: "Cron schedule for the builder", Value: "30 * * * *"},
 					&cli.StringFlag{Name: "coherence-cron", Usage: "Cron schedule for the coherence role", Value: "0 7 * * *"},
+					&cli.StringFlag{Name: "security-cron", Usage: "Cron schedule for the security role", Value: "0 6 * * 1"},
 					&cli.StringFlag{Name: "release-cron", Usage: "Cron schedule for the release role", Value: "0 23 * * *"},
 					&cli.StringFlag{Name: "tag-prefix", Usage: "Tag prefix the release role matches and bumps", Value: "v"},
 					&cli.BoolFlag{Name: "force", Usage: "Overwrite existing loop files"},
@@ -171,6 +174,7 @@ func runInit(c *cli.Context) error {
 		"planner":   c.String("planner-cron"),
 		"builder":   c.String("builder-cron"),
 		"coherence": c.String("coherence-cron"),
+		"security":  c.String("security-cron"),
 	}
 
 	if err := scaffold(dir, cfg, roles, crons, c.Bool("force")); err != nil {

cmd/micro/loop/loop_test.go

@@ -29,6 +29,7 @@ func renderCases() map[string]config {
 		"templates/prompts/planner.md.tmpl":   testCfg,
 		"templates/prompts/builder.md.tmpl":   testCfg,
 		"templates/prompts/coherence.md.tmpl": testCfg,
+		"templates/prompts/security.md.tmpl":  testCfg,
 	}
 	for role, d := range dispatchRoles {
 		rc := testCfg
@@ -59,7 +60,7 @@ func TestRenderIsPlaceholderFreeAndKeepsGHAExpressions(t *testing.T) {
 
 func TestBaseBranchSubstitutedIntoPrompts(t *testing.T) {
 	// The base branch appears in the PR-opening instructions of these prompts.
-	for _, p := range []string{"planner", "builder", "coherence"} {
+	for _, p := range []string{"planner", "builder", "coherence", "security"} {
 		s := mustRender(t, "templates/prompts/"+p+".md.tmpl", testCfg)
 		if !strings.Contains(s, "--base main") {
 			t.Errorf("%s prompt missing substituted base branch", p)
@@ -117,7 +118,7 @@ func TestDispatchWorkflowsStripPromptComments(t *testing.T) {
 
 func TestPromptsLeaveRuntimeTokensLiteral(t *testing.T) {
 	// __ISSUE__ must survive render (the workflow substitutes it at runtime).
-	for _, p := range []string{"planner", "builder", "coherence", "triage"} {
+	for _, p := range []string{"planner", "builder", "coherence", "triage", "security"} {
 		s := mustRender(t, "templates/prompts/"+p+".md.tmpl", testCfg)
 		if !strings.Contains(s, "__ISSUE__") {
 			t.Errorf("%s prompt lost its __ISSUE__ runtime token", p)
@@ -133,19 +134,19 @@ func TestScaffoldAllRolesWritesEverything(t *testing.T) {
 	dir := t.TempDir()
 	mustWrite(t, filepath.Join(dir, wfDir, "ci.yml"), "name: CI\n")
 
-	roles := []string{"planner", "builder", "triage", "coherence", "release"}
+	roles := []string{"planner", "builder", "triage", "coherence", "security", "release"}
 	if err := scaffold(dir, testCfg, roles, testCrons, false); err != nil {
 		t.Fatalf("scaffold: %v", err)
 	}
 
-	wantWorkflows := []string{"loop-planner.yml", "loop-builder.yml", "loop-triage.yml", "loop-coherence.yml", "loop-release.yml"}
+	wantWorkflows := []string{"loop-planner.yml", "loop-builder.yml", "loop-triage.yml", "loop-coherence.yml", "loop-security.yml", "loop-release.yml"}
 	for _, w := range wantWorkflows {
 		if !fileExists(filepath.Join(dir, wfDir, w)) {
 			t.Errorf("expected %s", w)
 		}
 	}
 	// Dispatch + triage roles have prompts; release does not.
-	for _, p := range []string{"planner.md", "builder.md", "triage.md", "coherence.md"} {
+	for _, p := range []string{"planner.md", "builder.md", "triage.md", "coherence.md", "security.md"} {
 		if !fileExists(filepath.Join(dir, promptDir, p)) {
 			t.Errorf("expected prompt %s", p)
 		}

cmd/micro/loop/templates/prompts/security.md.tmpl

@@ -0,0 +1,22 @@
+<!--
+The SECURITY prompt — the editable policy for the security role. The workflow
+prepends the agent @mention and substitutes __ISSUE__ before posting. Keep
+__ISSUE__ literal.
+
+Security is deliberately more conservative than the other roles: it does NOT
+auto-merge fixes, and it does NOT publish exploit details in public issues.
+-->
+Act as the security reviewer for this repository. Audit for real, exploitable vulnerabilities — do not pad the report with theoretical or low-value lint-style noise.
+
+WHAT TO LOOK FOR: injection (SQL/command/template), authentication and authorization bypass, credential/secret/token exposure (in code, logs, or error messages), SSRF and unsafe outbound requests (especially user- or config-controlled URLs), path traversal, unsafe deserialization, missing or incorrect input validation on trust boundaries (HTTP handlers, RPC endpoints, message consumers), insecure defaults (TLS, auth, permissions), unsafe use of `crypto`/randomness, and known-vulnerable dependencies (run `govulncheck ./...` if available, or inspect `go.mod`).
+
+DEDUPE against open issues before filing anything.
+
+HOW TO REPORT — this matters:
+- **Known/public dependency CVEs** (already disclosed): file an issue labeled `security` referencing the CVE and the affected module, and you MAY open a PR that bumps the dependency to the patched version. Do **NOT** enable auto-merge — leave it for human review.
+- **Novel, exploitable vulnerabilities in this codebase** (not yet public): do **NOT** post a working exploit, proof-of-concept, or step-by-step reproduction in a public issue — that is irresponsible disclosure. File a CONCISE issue labeled `security` and `needs-human` that names the vulnerability *class*, the *location* (file/function), and the *impact*, with only enough detail for a maintainer to find it — and note it should be handled via the repository's private vulnerability reporting if the repo is public. Do NOT open a public fix PR that reveals the vulnerability; leave the fix to a human.
+- **Low-risk hardening** (defense-in-depth, missing validation with no proven exploit): a normal `security` issue is fine.
+
+NEVER auto-merge a security change. Never weaken a control to make a test pass. Anything requiring an architectural or breaking change: label it `needs-human` and describe the tradeoff.
+
+Post a summary as a comment on this issue (#__ISSUE__) — how many findings by severity, what you filed, and what needs a human — then close it (`gh issue close __ISSUE__`). If you open a dependency-bump PR, do it yourself from the shell: `git switch -c loop/security-__ISSUE__`, `git push -u origin loop/security-__ISSUE__`, `gh pr create --base << .DefaultBranch >> --title "<title>" --body "<summary, Closes #__ISSUE__>"` — then STOP; do NOT run `gh pr merge --auto`. Do not use a make_pr tool.

examples/README.md

@@ -15,7 +15,7 @@ of reading the directories alphabetically.
 | Step | Start here | What you learn | Next step |
 |------|------------|----------------|-----------|
 | 1. First service | [`hello-world`](./hello-world/) | Create and register a basic RPC service, add a handler, call it with a client, and expose health checks. | Move to [`agent-demo`](./agent-demo/) to see services used by an agent. |
-| 2. First agent | [`agent-demo`](./agent-demo/) | Run a small project-management app with Projects, Tasks, and Team services plus an agent playground. | Compare with the maintained 0-to-hero path in [`support`](./support/). |
+| 2. First agent | [`first-agent`](./first-agent/) | Run the smallest service-backed agent with a deterministic mock model and no provider key. | Compare with [`agent-demo`](./agent-demo/) or the maintained 0-to-hero path in [`support`](./support/). |
 | 3. First workflow | [`support`](./support/) | Follow typed services into an agent chat loop, an event-driven `intake` flow, and an approval gate in one runnable reference. | Deepen the workflow model with [`flow-durable`](./flow-durable/). |
 
 For the shortest AI-tooling bridge, the MCP path is
@@ -75,8 +75,11 @@ Docker Compose deployment with MCP gateway, Consul registry, and Jaeger tracing:
 
 ### 2. Agents — turn services into tool-using teammates
 
+#### [first-agent](./first-agent/)
+Smallest first agent: one notes service plus one scoped agent, backed by a deterministic mock model so `go run ./examples/first-agent` works without provider secrets.
+
 #### [agent-demo](./agent-demo/)
-Recommended first agent: a multi-service project management app with Projects,
+A multi-service project management app with Projects,
 Tasks, and Team services, seed data, and agent playground integration.
 
 #### [agent-plan-delegate](./agent-plan-delegate/)

examples/first-agent/README.md

@@ -0,0 +1,38 @@
+# First Agent
+
+This is the smallest runnable service-backed agent in the repository. It sits
+between `micro new helloworld` and the full [`examples/support`](../support/)
+0→hero reference.
+
+It runs with a deterministic mock model, so you do not need `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, or any other provider secret.
+
+```bash
+go run ./examples/first-agent
+```
+
+Expected transcript:
+
+```text
+First agent (provider: mock, no API key)
+> Summarize my next steps
+  [notes] listed starter notes
+assistant: Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent.
+✓ service-backed agent completed without provider secrets
+```
+
+## What it demonstrates
+
+- `notes` is a normal Go Micro service with one RPC method.
+- `assistant` is an agent scoped to that service via `agent.Services("notes")`.
+- The mock model requests the service tool through the normal agent tool handler.
+- The final answer proves the service → agent path without a live model key.
+
+CI keeps this path runnable with:
+
+```bash
+go test ./examples/first-agent
+```
+
+After this, continue to [`examples/support`](../support/) for the full services →
+agents → workflows lifecycle with a flow trigger and an approval gate.

examples/first-agent/main.go

@@ -0,0 +1,156 @@
+// First Agent — the smallest runnable service-backed agent.
+//
+// Run:
+//
+//	go run ./examples/first-agent
+//
+// It uses a deterministic mock model, so it needs no provider API key. The
+// point is to show the first agent shape: a service exposes a tool, an agent
+// discovers that service, the model asks to call the tool, and the agent returns
+// a final answer.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"go-micro.dev/v6/agent"
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/selector"
+	"go-micro.dev/v6/service"
+	"go-micro.dev/v6/store"
+)
+
+type ListNotesRequest struct{}
+
+type ListNotesResponse struct {
+	Notes []string `json:"notes" description:"Notes the assistant can summarize"`
+}
+
+type NotesService struct{}
+
+// List returns the starter notes the first agent can read.
+// @example {}
+func (s *NotesService) List(ctx context.Context, req *ListNotesRequest, rsp *ListNotesResponse) error {
+	rsp.Notes = []string{"Install the micro CLI", "Run a service", "Chat with an agent"}
+	fmt.Println("  [notes] listed starter notes")
+	return nil
+}
+
+type mockModel struct{ opts ai.Options }
+
+func newMock(opts ...ai.Option) ai.Model {
+	m := &mockModel{}
+	_ = m.Init(opts...)
+	return m
+}
+
+func (m *mockModel) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&m.opts)
+	}
+	return nil
+}
+func (m *mockModel) Options() ai.Options { return m.opts }
+func (m *mockModel) String() string      { return "first-agent-mock" }
+func (m *mockModel) Stream(context.Context, *ai.Request, ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("stream not supported by first-agent mock")
+}
+
+func (m *mockModel) Generate(ctx context.Context, req *ai.Request, _ ...ai.GenerateOption) (*ai.Response, error) {
+	for _, tool := range req.Tools {
+		if strings.Contains(tool.Name, "List") && m.opts.ToolHandler != nil {
+			m.opts.ToolHandler(ctx, ai.ToolCall{ID: "list-notes", Name: tool.Name, Input: map[string]any{}})
+			break
+		}
+	}
+	return &ai.Response{Answer: "Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent."}, nil
+}
+
+func waitFor(reg registry.Registry, names ...string) error {
+	deadline := time.Now().Add(5 * time.Second)
+	for _, name := range names {
+		for {
+			if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 {
+				break
+			}
+			if time.Now().After(deadline) {
+				return fmt.Errorf("timed out waiting for %s", name)
+			}
+			time.Sleep(20 * time.Millisecond)
+		}
+	}
+	return nil
+}
+
+func runFirstAgent() error {
+	ai.Register("first-agent-mock", newMock)
+
+	reg := registry.NewMemoryRegistry()
+	br := broker.NewMemoryBroker()
+	if err := br.Init(); err != nil {
+		return fmt.Errorf("init broker: %w", err)
+	}
+	if err := br.Connect(); err != nil {
+		return fmt.Errorf("connect broker: %w", err)
+	}
+	defer br.Disconnect()
+	cl := client.NewClient(client.Registry(reg), client.Selector(selector.NewSelector(selector.Registry(reg))), client.Broker(br))
+
+	notes := service.New(service.Name("notes"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl), service.Broker(br), service.HandleSignal(false))
+	if err := notes.Handle(new(NotesService)); err != nil {
+		return fmt.Errorf("handle notes: %w", err)
+	}
+	svcErr := make(chan error, 1)
+	go func() { svcErr <- notes.Run() }()
+	defer notes.Server().Stop()
+
+	assistant := agent.New(
+		agent.Name("assistant"),
+		agent.Address("127.0.0.1:0"),
+		agent.Services("notes"),
+		agent.Prompt("You are a friendly first agent. Use the notes service before answering."),
+		agent.Provider("first-agent-mock"),
+		agent.WithRegistry(reg),
+		agent.WithClient(cl),
+		agent.WithBroker(br),
+		agent.WithStore(store.NewMemoryStore()),
+	)
+	agentErr := make(chan error, 1)
+	go func() { agentErr <- assistant.Run() }()
+	defer assistant.Stop()
+
+	if err := waitFor(reg, "notes", "assistant"); err != nil {
+		select {
+		case runErr := <-svcErr:
+			return fmt.Errorf("run notes: %w", runErr)
+		case runErr := <-agentErr:
+			return fmt.Errorf("run assistant: %w", runErr)
+		default:
+		}
+		return err
+	}
+
+	fmt.Println("First agent (provider: mock, no API key)")
+	fmt.Println("> Summarize my next steps")
+	resp, err := assistant.Ask(context.Background(), "Summarize my next steps")
+	if err != nil {
+		return fmt.Errorf("ask assistant: %w", err)
+	}
+	fmt.Println("assistant:", resp.Reply)
+	fmt.Println("✓ service-backed agent completed without provider secrets")
+	return nil
+}
+
+func main() {
+	if err := runFirstAgent(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}

examples/first-agent/main_test.go

@@ -0,0 +1,9 @@
+package main
+
+import "testing"
+
+func TestRunFirstAgent(t *testing.T) {
+	if err := runFirstAgent(); err != nil {
+		t.Fatalf("first-agent example failed: %v", err)
+	}
+}

gateway/a2a/a2a.go

@@ -201,12 +201,13 @@ type Part struct {
 
 // Message is a turn in an A2A conversation.
 type Message struct {
-	Role      string `json:"role"` // "user" | "agent"
-	Parts     []Part `json:"parts"`
-	MessageID string `json:"messageId,omitempty"`
-	TaskID    string `json:"taskId,omitempty"`
-	ContextID string `json:"contextId,omitempty"`
-	Kind      string `json:"kind"` // "message"
+	Role        string             `json:"role"` // "user" | "agent"
+	Parts       []Part             `json:"parts"`
+	MessageID   string             `json:"messageId,omitempty"`
+	TaskID      string             `json:"taskId,omitempty"`
+	ContextID   string             `json:"contextId,omitempty"`
+	Kind        string             `json:"kind"` // "message"
+	AP2Mandates []AP2SignedMandate `json:"ap2Mandates,omitempty"`
 }
 
 // TaskStatus is a task's lifecycle state.
@@ -223,12 +224,14 @@ type Artifact struct {
 
 // Task is the unit of work returned by message/send and tasks/get.
 type Task struct {
-	ID        string     `json:"id"`
-	ContextID string     `json:"contextId"`
-	Status    TaskStatus `json:"status"`
-	Artifacts []Artifact `json:"artifacts,omitempty"`
-	History   []Message  `json:"history,omitempty"`
-	Kind      string     `json:"kind"` // "task"
+	ID               string             `json:"id"`
+	ContextID        string             `json:"contextId"`
+	Status           TaskStatus         `json:"status"`
+	Artifacts        []Artifact         `json:"artifacts,omitempty"`
+	History          []Message          `json:"history,omitempty"`
+	Kind             string             `json:"kind"` // "task"
+	AP2Mandates      []AP2SignedMandate `json:"ap2Mandates,omitempty"`
+	AP2Verifications []AP2Verification  `json:"ap2Verifications,omitempty"`
 }
 
 // PushNotificationConfig tells the gateway where to POST task updates for a
@@ -848,12 +851,13 @@ func taskFromReplyWithIDsAndHistory(input Message, reply, state, taskID, context
 		input.Kind = "message"
 	}
 	task := &Task{
-		ID:        taskID,
-		ContextID: contextID,
-		Kind:      "task",
-		History:   append(append([]Message{}, history...), input),
-		Status:    TaskStatus{State: state, Timestamp: time.Now().UTC().Format(time.RFC3339)},
-		Artifacts: []Artifact{textArtifact(reply)},
+		ID:          taskID,
+		ContextID:   contextID,
+		Kind:        "task",
+		History:     append(append([]Message{}, history...), input),
+		Status:      TaskStatus{State: state, Timestamp: time.Now().UTC().Format(time.RFC3339)},
+		Artifacts:   []Artifact{textArtifact(reply)},
+		AP2Mandates: append([]AP2SignedMandate{}, input.AP2Mandates...),
 	}
 	task.History = append(task.History, Message{
 		Role:      "agent",

gateway/a2a/ap2.go

@@ -0,0 +1,150 @@
+package a2a
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// AP2MandateKind identifies the AP2 mandate stage represented by a credential.
+type AP2MandateKind string
+
+const (
+	AP2CheckoutMandate AP2MandateKind = "checkout"
+	AP2PaymentMandate  AP2MandateKind = "payment"
+)
+
+// AP2RailRef names the settlement rail authorized by an AP2 payment mandate.
+type AP2RailRef struct {
+	Type      string `json:"type"`
+	Reference string `json:"reference"`
+}
+
+// AP2Mandate is a small verifiable AP2 credential. It is deliberately rail-neutral:
+// x402 is represented as one possible rail reference under a payment mandate.
+type AP2Mandate struct {
+	ID          string         `json:"id"`
+	Kind        AP2MandateKind `json:"kind"`
+	Subject     string         `json:"subject,omitempty"`
+	Merchant    string         `json:"merchant,omitempty"`
+	Amount      string         `json:"amount,omitempty"`
+	Currency    string         `json:"currency,omitempty"`
+	Description string         `json:"description,omitempty"`
+	TaskID      string         `json:"taskId,omitempty"`
+	ContextID   string         `json:"contextId,omitempty"`
+	Rail        *AP2RailRef    `json:"rail,omitempty"`
+	IssuedAt    time.Time      `json:"issuedAt"`
+}
+
+// AP2SignedMandate is an AP2 mandate plus an Ed25519 signature over its canonical JSON.
+type AP2SignedMandate struct {
+	Mandate   AP2Mandate `json:"mandate"`
+	KeyID     string     `json:"keyId,omitempty"`
+	Signature string     `json:"signature"`
+}
+
+// AP2Verification records mandate verification on an A2A task without mixing in
+// payment-settlement state.
+type AP2Verification struct {
+	MandateID string `json:"mandateId"`
+	Kind      string `json:"kind"`
+	Verified  bool   `json:"verified"`
+	Error     string `json:"error,omitempty"`
+}
+
+// NewAP2Keypair returns an Ed25519 keypair suitable for tests or local demos.
+func NewAP2Keypair() (ed25519.PublicKey, ed25519.PrivateKey, error) {
+	return ed25519.GenerateKey(rand.Reader)
+}
+
+// SignAP2Mandate signs a mandate as a verifiable AP2 credential.
+func SignAP2Mandate(m AP2Mandate, keyID string, private ed25519.PrivateKey) (AP2SignedMandate, error) {
+	if m.ID == "" {
+		return AP2SignedMandate{}, errors.New("ap2: mandate id is required")
+	}
+	if m.Kind == "" {
+		return AP2SignedMandate{}, errors.New("ap2: mandate kind is required")
+	}
+	if m.IssuedAt.IsZero() {
+		m.IssuedAt = time.Now().UTC()
+	}
+	payload, err := ap2Payload(m)
+	if err != nil {
+		return AP2SignedMandate{}, err
+	}
+	return AP2SignedMandate{Mandate: m, KeyID: keyID, Signature: base64.RawURLEncoding.EncodeToString(ed25519.Sign(private, payload))}, nil
+}
+
+// VerifyAP2Mandate verifies a signed mandate credential.
+func VerifyAP2Mandate(s AP2SignedMandate, public ed25519.PublicKey) error {
+	sig, err := base64.RawURLEncoding.DecodeString(s.Signature)
+	if err != nil {
+		return fmt.Errorf("ap2: invalid signature encoding: %w", err)
+	}
+	payload, err := ap2Payload(s.Mandate)
+	if err != nil {
+		return err
+	}
+	if !ed25519.Verify(public, payload, sig) {
+		return errors.New("ap2: mandate signature verification failed")
+	}
+	return nil
+}
+
+// AP2BindMandateToMessage returns a copy of m bound to the A2A message's task/context.
+func AP2BindMandateToMessage(m AP2Mandate, msg Message) AP2Mandate {
+	m.TaskID = msg.TaskID
+	m.ContextID = msg.ContextID
+	return m
+}
+
+// AP2AttachMandate returns a copy of msg carrying the signed AP2 mandate.
+func AP2AttachMandate(msg Message, mandate AP2SignedMandate) Message {
+	msg.AP2Mandates = append(append([]AP2SignedMandate{}, msg.AP2Mandates...), mandate)
+	return msg
+}
+
+// VerifyAP2ForTask verifies signature, task binding, and optional settlement rail reference.
+func VerifyAP2ForTask(s AP2SignedMandate, public ed25519.PublicKey, task Task, rail *AP2RailRef) AP2Verification {
+	out := AP2Verification{MandateID: s.Mandate.ID, Kind: string(s.Mandate.Kind), Verified: true}
+	if err := VerifyAP2Mandate(s, public); err != nil {
+		out.Verified = false
+		out.Error = err.Error()
+		return out
+	}
+	if s.Mandate.TaskID != "" && s.Mandate.TaskID != task.ID {
+		out.Verified = false
+		out.Error = "ap2: mandate task binding mismatch"
+		return out
+	}
+	if s.Mandate.ContextID != "" && s.Mandate.ContextID != task.ContextID {
+		out.Verified = false
+		out.Error = "ap2: mandate context binding mismatch"
+		return out
+	}
+	if s.Mandate.Kind == AP2PaymentMandate && rail != nil {
+		if s.Mandate.Rail == nil || *s.Mandate.Rail != *rail {
+			out.Verified = false
+			out.Error = "ap2: settlement rail reference mismatch"
+			return out
+		}
+	}
+	return out
+}
+
+// X402AP2Rail builds the x402 settlement rail reference carried under a payment mandate.
+func X402AP2Rail(reference string) AP2RailRef { return AP2RailRef{Type: "x402", Reference: reference} }
+
+func ap2Payload(m AP2Mandate) ([]byte, error) {
+	b, err := json.Marshal(m)
+	if err != nil {
+		return nil, fmt.Errorf("ap2: marshal mandate: %w", err)
+	}
+	sum := sha256.Sum256(b)
+	return sum[:], nil
+}

gateway/a2a/ap2_test.go

@@ -0,0 +1,78 @@
+package a2a
+
+import (
+	"crypto/ed25519"
+	"strings"
+	"testing"
+	"time"
+)
+
+func testAP2Key(t *testing.T) (ed25519.PublicKey, ed25519.PrivateKey) {
+	t.Helper()
+	pub, priv, err := NewAP2Keypair()
+	if err != nil {
+		t.Fatal(err)
+	}
+	return pub, priv
+}
+
+func TestAP2CheckoutMandateSignAttachAndVerify(t *testing.T) {
+	pub, priv := testAP2Key(t)
+	msg := Message{Role: "user", Kind: "message", TaskID: "task-1", ContextID: "ctx-1", Parts: []Part{{Kind: "text", Text: "buy"}}}
+	mandate := AP2BindMandateToMessage(AP2Mandate{ID: "checkout-1", Kind: AP2CheckoutMandate, Subject: "alice", Merchant: "store", Amount: "10.00", Currency: "USD", Description: "demo", IssuedAt: time.Unix(1, 0).UTC()}, msg)
+	signed, err := SignAP2Mandate(mandate, "test-key", priv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	msg = AP2AttachMandate(msg, signed)
+	task := taskFromReplyWithIDs(msg, "ok", stateCompleted, msg.TaskID, msg.ContextID)
+
+	if len(task.AP2Mandates) != 1 {
+		t.Fatalf("expected mandate carried on task, got %d", len(task.AP2Mandates))
+	}
+	got := VerifyAP2ForTask(task.AP2Mandates[0], pub, *task, nil)
+	if !got.Verified || got.Error != "" {
+		t.Fatalf("expected verified mandate, got %+v", got)
+	}
+}
+
+func TestAP2PaymentMandateX402RailReference(t *testing.T) {
+	pub, priv := testAP2Key(t)
+	rail := X402AP2Rail("payreq_123")
+	task := Task{ID: "task-2", ContextID: "ctx-2"}
+	signed, err := SignAP2Mandate(AP2Mandate{ID: "payment-1", Kind: AP2PaymentMandate, TaskID: task.ID, ContextID: task.ContextID, Rail: &rail, IssuedAt: time.Unix(1, 0).UTC()}, "test-key", priv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := VerifyAP2ForTask(signed, pub, task, &rail)
+	if !got.Verified {
+		t.Fatalf("expected x402 rail to verify, got %+v", got)
+	}
+}
+
+func TestAP2TamperCasesFailDistinctly(t *testing.T) {
+	pub, priv := testAP2Key(t)
+	rail := X402AP2Rail("payreq_123")
+	task := Task{ID: "task-3", ContextID: "ctx-3"}
+	signed, err := SignAP2Mandate(AP2Mandate{ID: "payment-2", Kind: AP2PaymentMandate, TaskID: task.ID, ContextID: task.ContextID, Rail: &rail, IssuedAt: time.Unix(1, 0).UTC()}, "test-key", priv)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tampered := signed
+	tampered.Mandate.Amount = "999.00"
+	if got := VerifyAP2ForTask(tampered, pub, task, &rail); got.Verified || !strings.Contains(got.Error, "signature") {
+		t.Fatalf("expected signature failure, got %+v", got)
+	}
+
+	wrongTask := task
+	wrongTask.ID = "other-task"
+	if got := VerifyAP2ForTask(signed, pub, wrongTask, &rail); got.Verified || !strings.Contains(got.Error, "task binding") {
+		t.Fatalf("expected task binding failure, got %+v", got)
+	}
+
+	otherRail := X402AP2Rail("payreq_other")
+	if got := VerifyAP2ForTask(signed, pub, task, &otherRail); got.Verified || !strings.Contains(got.Error, "rail reference") {
+		t.Fatalf("expected rail reference failure, got %+v", got)
+	}
+}

gateway/a2a/client.go

@@ -107,12 +107,13 @@ func (c *Client) SendMessage(ctx context.Context, message Message) (*Task, error
 			return nil, err
 		}
 		return &Task{
-			ID:        m.TaskID,
-			ContextID: m.ContextID,
-			Kind:      "task",
-			Status:    TaskStatus{State: stateCompleted, Timestamp: time.Now().UTC().Format(time.RFC3339)},
-			Artifacts: []Artifact{textArtifact(textOf(m.Parts))},
-			History:   []Message{m},
+			ID:          m.TaskID,
+			ContextID:   m.ContextID,
+			Kind:        "task",
+			Status:      TaskStatus{State: stateCompleted, Timestamp: time.Now().UTC().Format(time.RFC3339)},
+			Artifacts:   []Artifact{textArtifact(textOf(m.Parts))},
+			History:     []Message{m},
+			AP2Mandates: append([]AP2SignedMandate{}, m.AP2Mandates...),
 		}, nil
 	}
 

internal/docs/CONTINUOUS_IMPROVEMENT.md

@@ -24,6 +24,7 @@ Actions instead of subagents. Each role is a workflow:
 | **Evaluator** | `harness.yml` — *Harness (E2E)*, plus the CI gate (`tests.yaml`, `lint.yaml`) | Grades every change: the mock harness + unit/lint on each push/PR, and real-model conformance hourly. A *separate* grader — never the generator judging itself. |
 | **Evaluator → feedback** | `loop-triage.yml` — *Loop: Triage (Evaluator feedback)* | When a gate workflow (Lint, Run Tests, or the harness) fails on a non-PR run, root-causes, dedupes, and files scoped fix issues back into the planner's queue. The hill-climbing feedback path. |
 | **Coherence** | `loop-coherence.yml` — *Loop: Coherence* | Keeps README/website/docs/blog aligned with the North Star, keeps `CHANGELOG.md` living (reconciling `[Unreleased]` against merged PRs and rolling it into version headings as tags cut), and drafts the changelog blog post. |
+| **Security** | `loop-security.yml` — *Loop: Security* | Weekly vulnerability audit of the attack surface (MCP/A2A gateways, x402, auth, provider URLs, agent tool loop, deps via `govulncheck`). Files `security` issues; **never auto-merges** fixes and **never publishes exploit detail** in public issues (responsible disclosure); risky fixes are `needs-human`. |
 | **Release** | `loop-release.yml` — *Loop: Release (daily patch)* | Cuts a daily patch tag when master has new commits, so the *installable* framework tracks the loop's improvements (triggers `release.yml`/goreleaser). Minor/major bumps stay with the human. |
 
 Generation is separated from evaluation on purpose: an agent grading its own work

internal/harness/plan-delegate/main.go

@@ -131,6 +131,8 @@ const delegatedNotifyTask = "Use the notify Send tool exactly once to tell owner
 
 const commsPrompt = "You handle outbound notifications. When asked to notify someone, you must call the notify Send tool exactly once before replying. Never claim a notification was sent unless the notify tool returned success."
 
+const delegatedNotifySettleTimeout = 10 * time.Second
+
 type SendRequest struct {
 	To      string `json:"to" description:"Recipient address"`
 	Message string `json:"message" description:"Message body"`
@@ -401,8 +403,14 @@ func runPlanDelegate(provider string) error {
 	}
 
 	f := flow.New("zero-to-hero",
-		flow.Agent("conductor"),
-		flow.Prompt("Create three launch tasks (Design, Build, Ship), then make sure owner@acme.com is notified: {{.Data}}"),
+		flow.Steps(
+			flow.Step{Name: "conductor", Run: planDelegateConductorStep(conductor)},
+			flow.Step{Name: "require-notify", Run: requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
+				_, err := conductor.Ask(ctx, "The Design, Build, and Ship tasks already exist, but the owner notification is still missing. Delegate exactly one notification to the \"comms\" agent now with this exact subtask: "+delegatedNotifyTask+" Do not create more tasks and do not answer until comms has handled the notification.")
+				return err
+			})},
+		),
+		flow.WithCheckpoint(flow.StoreCheckpoint(mem, "flow-zero-to-hero")),
 		flow.Timeout(harnessutil.LiveTimeout(provider)),
 	)
 	if err := f.Register(reg, broker.DefaultBroker, cl); err != nil {
@@ -417,15 +425,8 @@ func runPlanDelegate(provider string) error {
 		executeDone <- f.Execute(ctx, "launch readiness")
 	}()
 
-	if err := waitForPlanDelegateExecution(executeDone, taskSvc, notifySvc, func(ctx context.Context) error {
-		_, err := conductor.Ask(ctx, "The Design, Build, and Ship tasks already exist, but the owner notification is still missing. Delegate exactly one notification to the \"comms\" agent now with this exact subtask: "+delegatedNotifyTask+" Do not create more tasks and do not answer until comms has handled the notification.")
+	if err := waitForPlanDelegateExecution(executeDone, taskSvc, notifySvc); err != nil {
 		return err
-	}); err != nil {
-		return err
-	}
-
-	if rs := f.Results(); len(rs) > 0 {
-		fmt.Println("\n\033[1m< conductor reply:\033[0m", rs[len(rs)-1].Reply)
 	}
 
 	// Prove plan was persisted to the real store.
@@ -442,7 +443,48 @@ func runPlanDelegate(provider string) error {
 	return nil
 }
 
-func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) error {
+func planDelegateConductorStep(conductor agent.Agent) flow.StepFunc {
+	return func(ctx context.Context, in flow.State) (flow.State, error) {
+		prompt := "Create three launch tasks (Design, Build, Ship), then make sure owner@acme.com is notified: " + in.String()
+		rsp, err := conductor.Ask(ctx, prompt)
+		if err != nil {
+			return in, err
+		}
+		if rsp != nil && rsp.Reply != "" {
+			fmt.Println("\n\033[1m< conductor reply:\033[0m", rsp.Reply)
+		}
+		return in, nil
+	}
+}
+
+func requireDelegatedNotifyStep(taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) flow.StepFunc {
+	return func(ctx context.Context, in flow.State) (flow.State, error) {
+		tasks := taskSvc.count()
+		notify := notifySvc.count()
+		if notify == 1 {
+			return in, nil
+		}
+		if recoverMissingNotify == nil || tasks != 3 || notify != 0 {
+			return in, fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
+		}
+		settled, err := waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout)
+		if err != nil {
+			return in, err
+		}
+		if !settled {
+			fmt.Print("\n\033[33mwarning:\033[0m conductor step completed before delegated notify; retrying the missing comms handoff once before the flow can complete.\n")
+			if err := recoverMissingNotify(ctx); err != nil {
+				return in, fmt.Errorf("delegation completed without required notify side effect and recovery failed: notify=%d, want 1: %w", notify, err)
+			}
+		}
+		if notify = notifySvc.count(); notify != 1 {
+			return in, fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notify)
+		}
+		return in, nil
+	}
+}
+
+func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notifySvc *NotifyService) error {
 	ticker := time.NewTicker(50 * time.Millisecond)
 	defer ticker.Stop()
 	for {
@@ -461,19 +503,7 @@ func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notif
 				return fmt.Errorf("flow execute after side effects tasks=%d notify=%d: %w", tasks, notify, err)
 			}
 			if notify != 1 {
-				if recoverMissingNotify == nil || tasks != 3 || notify != 0 {
-					return fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
-				}
-				fmt.Print("\n\033[33mwarning:\033[0m flow completed before delegated notify; retrying the missing comms handoff once.\n")
-				ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-				retryErr := recoverMissingNotify(ctx)
-				cancel()
-				if retryErr != nil {
-					return fmt.Errorf("delegation completed without required notify side effect and recovery failed: notify=%d, want 1: %w", notify, retryErr)
-				}
-				if notify = notifySvc.count(); notify != 1 {
-					return fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notify)
-				}
+				return fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
 			}
 			return nil
 		case <-ticker.C:
@@ -484,6 +514,22 @@ func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notif
 	}
 }
 
+func waitForNotifySideEffect(notifySvc *NotifyService, timeout time.Duration) (bool, error) {
+	deadline := time.Now().Add(timeout)
+	for {
+		if notifySvc.count() == 1 {
+			return true, nil
+		}
+		if dup := notifySvc.duplicateAttempts(); dup > 0 {
+			return false, fmt.Errorf("duplicate notify attempts: got %d duplicate replay(s), want 0", dup)
+		}
+		if !time.Now().Before(deadline) {
+			return false, nil
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+}
+
 func classifiedPlanDelegateTimeout(tasks, notify int, err error) error {
 	return fmt.Errorf("provider latency/outage during plan-delegate before required side effects completed (tasks=%d/3 notify=%d/1); retry live provider or inspect provider logs if this recurs: %w", tasks, notify, err)
 }

internal/harness/plan-delegate/main_test.go

@@ -258,7 +258,7 @@ func TestPlanDelegateExecutionReportsDuplicateNotifyBeforeTimeout(t *testing.T)
 
 	done := make(chan error)
 	errCh := make(chan error, 1)
-	go func() { errCh <- waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil) }()
+	go func() { errCh <- waitForPlanDelegateExecution(done, new(TaskService), notifySvc) }()
 
 	select {
 	case err := <-errCh:
@@ -278,7 +278,7 @@ func TestPlanDelegateExecutionRejectsClaimedCompletionWithoutNotify(t *testing.T
 	done := make(chan error, 1)
 	done <- nil
 
-	err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil)
+	err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc)
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want missing notify side-effect error")
 	}
@@ -296,15 +296,13 @@ func TestPlanDelegateExecutionRecoversMissingNotifyOnce(t *testing.T) {
 		}
 	}
 	notifySvc := new(NotifyService)
-	done := make(chan error, 1)
-	done <- nil
 
 	recovered := false
-	err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, func(ctx context.Context) error {
+	_, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
 		recovered = true
 		var rsp SendResponse
 		return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp)
-	})
+	})(context.Background(), flow.State{})
 	if err != nil {
 		t.Fatalf("waitForPlanDelegateExecution returned %v, want recovery success", err)
 	}
@@ -316,6 +314,45 @@ func TestPlanDelegateExecutionRecoversMissingNotifyOnce(t *testing.T) {
 	}
 }
 
+func TestPlanDelegateExecutionWaitsForInFlightNotifyAfterFlowCompletion(t *testing.T) {
+	taskSvc := new(TaskService)
+	for _, title := range []string{"Design", "Build", "Ship"} {
+		var rsp AddResponse
+		if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil {
+			t.Fatalf("Add(%q): %v", title, err)
+		}
+	}
+	notifySvc := new(NotifyService)
+
+	go func() {
+		time.Sleep(100 * time.Millisecond)
+		var rsp SendResponse
+		_ = notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp)
+	}()
+
+	recovered := false
+	_, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
+		recovered = true
+		var rsp SendResponse
+		return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp)
+	})(context.Background(), flow.State{})
+	if err != nil {
+		t.Fatalf("waitForPlanDelegateExecution returned %v, want in-flight notify success", err)
+	}
+	if recovered {
+		t.Fatal("missing notify recovery ran while delegated notify was still in flight")
+	}
+	if got := taskSvc.count(); got != 3 {
+		t.Fatalf("task count = %d, want 3 after in-flight notify settles", got)
+	}
+	if got := notifySvc.count(); got != 1 {
+		t.Fatalf("notify count = %d, want 1 after in-flight notify settles", got)
+	}
+	if got := notifySvc.duplicateAttempts(); got != 0 {
+		t.Fatalf("duplicate notify attempts = %d, want 0", got)
+	}
+}
+
 func TestPlanDelegateExecutionAcceptsClientTimeoutAfterSideEffects(t *testing.T) {
 	taskSvc := new(TaskService)
 	for _, title := range []string{"Design", "Build", "Ship"} {
@@ -333,7 +370,7 @@ func TestPlanDelegateExecutionAcceptsClientTimeoutAfterSideEffects(t *testing.T)
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, nil); err != nil {
+	if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc); err != nil {
 		t.Fatalf("waitForPlanDelegateExecution returned %v, want completed side effects to satisfy client timeout", err)
 	}
 }
@@ -342,7 +379,7 @@ func TestPlanDelegateExecutionClassifiesClientTimeoutBeforeSideEffects(t *testin
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	err := waitForPlanDelegateExecution(done, new(TaskService), new(NotifyService), nil)
+	err := waitForPlanDelegateExecution(done, new(TaskService), new(NotifyService))
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before side effects to fail")
 	}
@@ -369,7 +406,7 @@ func TestPlanDelegateExecutionClassifiesPartialClientTimeout(t *testing.T) {
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	err := waitForPlanDelegateExecution(done, taskSvc, new(NotifyService), nil)
+	err := waitForPlanDelegateExecution(done, taskSvc, new(NotifyService))
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before notify to fail")
 	}

internal/harness/zero-to-hero-ci/docs_test.go

@@ -17,6 +17,7 @@ func TestZeroToHeroReferenceDocs(t *testing.T) {
 		"go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1",
 		"go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1",
 		"go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1",
+		"go test ./examples/first-agent -run TestRunFirstAgent -count=1",
 		"go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1",
 		"./internal/harness/zero-to-hero-ci/run.sh",
 		"go run ./internal/harness/agent-flow",
@@ -74,11 +75,96 @@ func TestGuidesNavigationLeadsWithDoing(t *testing.T) {
 	}
 }
 
+func TestFirstAgentWayfindingDocs(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	checks := []struct {
+		name    string
+		file    string
+		heading string
+		links   []string
+	}{
+		{
+			name:    "README first-agent on-ramp",
+			file:    filepath.Join(root, "README.md"),
+			heading: "### First agent on-ramp",
+			links: []string{
+				"micro agent demo",
+				"internal/website/docs/guides/no-secret-first-agent.md",
+				"internal/website/docs/guides/your-first-agent.md",
+				"internal/website/docs/guides/debugging-agents.md",
+				"internal/website/docs/guides/zero-to-hero.md",
+			},
+		},
+		{
+			name:    "README examples list",
+			file:    filepath.Join(root, "README.md"),
+			heading: "## Examples",
+			links: []string{
+				"examples/README.md",
+				"examples/first-agent/",
+			},
+		},
+		{
+			name:    "repository examples index",
+			file:    filepath.Join(root, "examples", "README.md"),
+			heading: "## Recommended first-agent path",
+			links: []string{
+				"./first-agent/",
+				"./support/",
+			},
+		},
+		{
+			name:    "website examples index",
+			file:    filepath.Join(root, "internal", "website", "docs", "examples", "index.md"),
+			heading: "## Start here",
+			links: []string{
+				"https://github.com/micro/go-micro/tree/master/examples/first-agent",
+				"../guides/no-secret-first-agent.html",
+				"../guides/your-first-agent.html",
+				"../guides/debugging-agents.html",
+				"../guides/zero-to-hero.html",
+			},
+		},
+		{
+			name:    "website getting-started on-ramp",
+			file:    filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
+			heading: "### First-agent on-ramp",
+			links: []string{
+				"micro agent demo",
+				"guides/no-secret-first-agent.html",
+				"guides/your-first-agent.html",
+				"guides/debugging-agents.html",
+				"guides/zero-to-hero.html",
+			},
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			doc := firstMarkdownSection(t, readFile(t, check.file), check.heading)
+			last := -1
+			for _, link := range check.links {
+				idx := strings.Index(doc, link)
+				if idx == -1 {
+					t.Fatalf("%s missing first-agent wayfinding link %q; keep the no-secret → first-agent → debugging → 0→hero path discoverable", check.name, link)
+				}
+				if idx < last {
+					t.Fatalf("%s link %q appeared out of order; expected no-secret → first-agent → debugging → 0→hero", check.name, link)
+				}
+				last = idx
+			}
+		})
+	}
+}
+
 func TestNoSecretFirstAgentTranscript(t *testing.T) {
 	root := filepath.Clean(filepath.Join("..", "..", ".."))
 	guide := readFile(t, filepath.Join(root, "internal", "website", "docs", "guides", "no-secret-first-agent.md"))
 
 	for _, want := range []string{
+		"micro agent demo",
+		"go run ./examples/first-agent",
+		"go test ./examples/first-agent -run TestRunFirstAgent -count=1",
 		"go run ./examples/support",
 		"go test ./examples/support -run TestRunSupportMockSmoke -count=1",
 		"make harness",
@@ -94,6 +180,20 @@ func TestNoSecretFirstAgentTranscript(t *testing.T) {
 		}
 	}
 
+	debugCheckpoint := firstMarkdownSection(t, guide, "## Debug transcript checkpoint")
+	for _, want := range []string{
+		`micro chat assistant --prompt "Triage ticket-1 for Alice"`,
+		"micro inspect agent assistant --limit 1",
+		"micro agent history assistant",
+		"status, event count, last event",
+		"Debugging your agent",
+		"debugging-agents.html",
+	} {
+		if !strings.Contains(debugCheckpoint, want) {
+			t.Fatalf("no-secret debug transcript checkpoint missing %q", want)
+		}
+	}
+
 	readme := readFile(t, filepath.Join(root, "README.md"))
 	if !strings.Contains(readme, "internal/website/docs/guides/no-secret-first-agent.md") {
 		t.Fatal("README does not point to the no-secret first-agent transcript")
@@ -105,6 +205,36 @@ func TestNoSecretFirstAgentTranscript(t *testing.T) {
 	}
 }
 
+func TestFirstAgentWayfindingTargetsExist(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	for _, target := range []string{
+		"examples/README.md",
+		"examples/first-agent/README.md",
+		"internal/website/docs/examples/index.md",
+		"internal/website/docs/guides/no-secret-first-agent.md",
+		"internal/website/docs/guides/your-first-agent.md",
+		"internal/website/docs/guides/debugging-agents.md",
+		"internal/website/docs/guides/zero-to-hero.md",
+	} {
+		if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(target))); err != nil {
+			t.Fatalf("first-agent wayfinding target %s disappeared: %v", target, err)
+		}
+	}
+}
+
+func firstMarkdownSection(t *testing.T, doc, heading string) string {
+	t.Helper()
+	start := strings.Index(doc, heading)
+	if start == -1 {
+		t.Fatalf("missing %q section", heading)
+	}
+	section := doc[start+len(heading):]
+	if next := strings.Index(section, "\n##"); next != -1 {
+		section = section[:next]
+	}
+	return section
+}
+
 func readFile(t *testing.T, name string) string {
 	t.Helper()
 	data, err := os.ReadFile(name)

internal/harness/zero-to-hero-ci/run.sh

@@ -8,10 +8,12 @@ cd "$ROOT"
 # without secrets or long-running daemons.
 go test ./cmd/micro -run 'TestFirstAgentWalkthroughCLIBoundaries|TestZeroToHeroCLIBoundaries' -count=1
 go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1
+go test ./internal/harness/zero-to-hero-ci -run 'TestNoSecretFirstAgentTranscript|TestZeroToHeroReferenceDocs' -count=1
 
 # Deterministic no-secret reference scenarios. These use the real Go Micro
 # runtime and mock only the LLM provider. The support example is the maintained
 # runnable 0→hero app; keep it in this CI path so its documented run/chat/inspect
 # journey cannot drift from the framework.
+go test ./examples/first-agent -run TestRunFirstAgent -count=1
 go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1
 go test ./internal/harness/universe ./internal/harness/plan-delegate -run 'Test.*Harness|TestPlanDelegateEndToEnd|TestPlanDelegateFlowHandoff' -count=1

internal/website/docs/ai-integration.md

@@ -5,27 +5,29 @@ title: AI Integration
 
 # AI Integration
 
-Go Micro is an AI-native microservices framework. Every service you build is automatically accessible to AI agents, and every service can call AI models. This page explains how the pieces fit together.
+Go Micro is an agent harness and service framework for Go. Every service you build can become an AI-callable tool, every agent runs as a service with model/memory/guardrails around it, and flows orchestrate the deterministic parts. This page explains how the services → agents → workflows lifecycle fits together.
 
 <img src="/images/generated/mcp-agent.jpg" alt="AI integration architecture" style="width: 100%; border-radius: 8px; margin: 1rem 0 1.5rem;" />
 
 ## The Stack
 
 ```
-Your Services           →  write Go handlers, register with the framework
+Services               →  write Go handlers, register with the framework
     ↓
-Registry                →  automatic service discovery (mDNS, Consul, etcd)
+Registry                →  automatic discovery for services, agents, and flows
     ↓
-Gateways                →  micro api (HTTP→RPC) / micro mcp (MCP tools)
+Gateways                →  micro api (HTTP→RPC), micro mcp (tools), micro a2a (agents)
     ↓
 ai.Tools                →  discovers services + executes RPCs programmatically
     ↓
 ai.Model                →  calls LLMs (Anthropic, OpenAI, Gemini, Atlas Cloud, ...)
     ↓
-agent / flow / micro chat  →  agent-managed, event-driven, or interactive orchestration
+Agents                 →  service-backed model loop with memory, guardrails, plan/delegate
+    ↓
+Flows                  →  durable deterministic steps that can dispatch to agents
 ```
 
-Every layer is optional. You can use go-micro without AI. You can use the `ai` package without MCP. But when you stack them, you get services that AI agents can discover and orchestrate automatically.
+Every layer is optional. You can use Go Micro as a service framework without AI. You can use the `ai` package without MCP. But when you stack them, you get one runtime where services become tools, agents are reachable services, and workflows coordinate the predictable parts.
 
 ## Layer by Layer
 

internal/website/docs/examples/index.md

@@ -10,9 +10,12 @@ agents → workflows lifecycle.
 
 ## Start here
 
+For the provider-free first-agent route, run [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent), then follow [No-secret First Agent](../guides/no-secret-first-agent.html), [Your First Agent](../guides/your-first-agent.html), [Debugging your agent](../guides/debugging-agents.html), and the [0→hero Reference](../guides/zero-to-hero.html).
+
 | Goal | Runnable example | Why it is useful |
 | --- | --- | --- |
 | 0→1 service | [`examples/hello-world`](https://github.com/micro/go-micro/tree/master/examples/hello-world) | Smallest RPC service with a client call and health checks. |
+| Provider-free first agent | [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent) | Smallest service-backed agent with a deterministic mock model; no provider key required. |
 | First service-backed agent | [`examples/agent-demo`](https://github.com/micro/go-micro/tree/master/examples/agent-demo) | Multi-service project/task/team app with agent playground integration. |
 | 0→hero lifecycle | [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) | No-secret support-desk story: typed services, an agent, an event-driven flow, and a guardrail. |
 | Planning and delegation | [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate) | Two agents collaborate through `plan` and `delegate` over normal Go Micro RPC. |
@@ -25,10 +28,16 @@ agents → workflows lifecycle.
 - [Getting Started](../getting-started.html) → run
   [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support)
   to see the full lifecycle before generating your own service.
+- [No-secret First Agent](../guides/no-secret-first-agent.html) → run
+  [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent)
+  first for the smallest provider-free agent transcript.
 - [Your First Agent](../guides/your-first-agent.html) → run
   [`examples/agent-demo`](https://github.com/micro/go-micro/tree/master/examples/agent-demo)
   or [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support)
   when you want a complete service-backed agent to inspect.
+- [Debugging your agent](../guides/debugging-agents.html) → keep
+  [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent)
+  nearby as the smallest mock-model reproduction before inspecting richer runs.
 - [0→hero Reference](../guides/zero-to-hero.html) → run
   [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support)
   for the human-readable scenario, then `make harness` for the full CI contract.

internal/website/docs/getting-started.md

@@ -86,9 +86,16 @@ Created project Launch and added task 'Write docs' to it.
 
 The console discovers services from the registry and orchestrates across them via the agent. Use `micro run -d` for detached mode without the console, or `micro chat` as a standalone command.
 
-If the agent surprises you while iterating, use the [Debugging your agent](guides/debugging-agents.html) guide to inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs.
+### First-agent on-ramp
 
-When you are ready to prove the whole path end to end, follow the [0→hero reference path](guides/zero-to-hero.html). It is the canonical handoff from this quick start: scaffold a service, run it locally, chat with an agent, inspect durable agent/flow history, and finish with `micro deploy --dry-run` using the same commands exercised by `make harness`.
+After this quick start, follow the agent path in order:
+
+1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
+2. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) — run one service-backed agent with a mock model and no provider key.
+3. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — run a useful support agent with a mock model before setting up a provider key.
+4. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
+5. [Debugging your agent](guides/debugging-agents.html) — inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent surprises you.
+6. [0→hero reference path](guides/zero-to-hero.html) — prove the full scaffold → run → chat → inspect → deploy dry-run lifecycle with commands exercised by `make harness`.
 
 ## Quick Start: Write a Service
 

internal/website/docs/guides/a2a-protocol.md

@@ -186,6 +186,16 @@ This is the JSON-RPC binding for task execution:
 
 Both directions work: the gateway exposes your agents, and `a2a.Client` (via `flow.A2A` or `delegate` to a URL) calls external ones. The task binding is what makes a Go Micro agent both reachable from, and able to reach, the A2A ecosystem today.
 
+## AP2 mandate layer (opt-in)
+
+AP2 sits above A2A as a verifiable-intent and audit layer. Go Micro keeps the
+A2A envelope separate from payment settlement: an A2A message can carry signed
+AP2 checkout or payment mandates, and the resulting task can retain the stable
+mandate reference plus verification result. Payment settlement state remains in
+the payment rail. For x402, use an AP2 payment mandate with an `x402` rail
+reference to name the payment requirement; the existing x402 facilitator still
+performs verification and settlement.
+
 ## See also
 
 - [MCP & AI Agents](../mcp.html) — exposing services as tools

internal/website/docs/guides/ai-provider-guide.md

@@ -38,7 +38,7 @@ The built-in providers currently register these capability interfaces:
 
 | Provider | Chat/text (`ai.Model`) | Image (`ai.ImageModel`) | Video (`ai.VideoModel`) | Streaming (`ai.Stream`) |
 | --- | --- | --- | --- | --- |
-| `anthropic` | Yes | No | No | No |
+| `anthropic` | Yes | No | No | Yes |
 | `atlascloud` | Yes | Yes | Yes | Yes |
 | `gemini` | Yes | No | No | No |
 | `groq` | Yes | No | No | Yes |

internal/website/docs/guides/no-secret-first-agent.md

@@ -25,11 +25,23 @@ end to end with no secrets.
 
 ## Transcript
 
-From a fresh clone of the repository:
+If you installed the CLI first, ask it for the no-secret path:
+
+```sh
+micro agent demo
+```
+
+From a fresh clone of the repository, first run the smallest service-backed agent:
 
 ```sh
 git clone https://github.com/micro/go-micro.git
 cd go-micro
+go run ./examples/first-agent
+```
+
+Then run the maintained support-agent transcript that exercises the full lifecycle:
+
+```sh
 go run ./examples/support
 ```
 
@@ -56,9 +68,10 @@ trigger and inspect the work.
 
 ## CI-backed check
 
-Run the same deterministic path as a focused test:
+Run the same deterministic paths as focused tests:
 
 ```sh
+go test ./examples/first-agent -run TestRunFirstAgent -count=1
 go test ./examples/support -run TestRunSupportMockSmoke -count=1
 ```
 
@@ -89,6 +102,26 @@ CI keeps those CLI boundaries present with:
 go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1
 ```
 
+## Debug transcript checkpoint
+
+A successful first chat turn should always leave an inspectable trail. After the
+chat command finishes, continue the same terminal transcript with the inspection
+and history commands before changing prompts or provider settings:
+
+```sh
+micro chat assistant --prompt "Triage ticket-1 for Alice"
+micro inspect agent assistant --limit 1
+micro agent history assistant
+```
+
+The inspection output is the checkpoint that the runnable loop did not stop at
+chat: it should show a recent agent run with a status, event count, last event,
+and trace breadcrumb when tracing is configured. `micro agent history assistant`
+then confirms the conversation memory that future turns will reuse. If either
+command is empty after a successful chat turn, keep the failing transcript and
+use [Debugging your agent](debugging-agents.html) to check provider failures, run
+history, memory, and tool-call inspection before changing application code.
+
 If `micro agent preflight` reports a missing provider key, you can still use this no-secret path because it runs against the mock model; the command now prints this guide as the next step for that failure. If chat behaves unexpectedly, continue to
 [Debugging your agent](debugging-agents.html) for provider checks, run history,
 memory, and tool-call inspection.

internal/website/docs/guides/provider-conformance.md

@@ -57,7 +57,7 @@ previous section.
 
 | Provider | Chat/text agent harness | Image | Video | Streaming | Structured errors |
 | --- | --- | --- | --- | --- | --- |
-| `anthropic` | ✅ Verified when configured | — Unsupported | — Unsupported | ⚠️ Unverified | ⚠️ Unverified |
+| `anthropic` | ✅ Verified when configured | — Unsupported | — Unsupported | ✅ Verified when configured | ⚠️ Unverified |
 | `openai` | ✅ Verified when configured | ✅ Registered | — Unsupported | ⚠️ Unverified | ⚠️ Unverified |
 | `gemini` | ✅ Verified when configured | — Unsupported | — Unsupported | ⚠️ Unverified | ⚠️ Unverified |
 | `groq` | ✅ Verified when configured | — Unsupported | — Unsupported | ⚠️ Unverified | ⚠️ Unverified |

internal/website/docs/guides/x402-payments.md

@@ -128,3 +128,11 @@ Leave those variables unset in normal CI; the live test skips unless the facilit
 - [Building Effective Agents — Agents and Workflows](agents-and-workflows.html)
 - [MCP & AI Agents](../mcp.html)
 - [x402 — Coinbase Developer Docs](https://docs.cdp.coinbase.com/x402/welcome) · [x402 on Solana](https://solana.com/x402/what-is-x402)
+
+## AP2 payment mandates
+
+AP2 can authorize an x402 payment without making A2A carry settlement state. A
+payment mandate records the buyer intent and names an `x402` rail reference; the
+existing x402 facilitator remains responsible for payment verification and
+settlement. This keeps AP2 as the signed mandate/audit layer while x402 stays the
+pluggable payment rail.

internal/website/docs/guides/zero-to-hero.md

@@ -18,17 +18,25 @@ cloud credentials?"
 | Boundary | Contract | CI check |
 | --- | --- | --- |
 | Scaffold | `micro new` generates a runnable service with and without MCP support. | `go test ./cmd/micro/cli/new -run TestZeroToOne -count=1` |
+| First-agent wayfinding | README and the website getting-started docs keep the no-secret → first-agent → debugging → 0→hero links present and in order. | `go test ./internal/harness/zero-to-hero-ci -run TestFirstAgentWayfindingDocs -count=1` |
 | First agent | `micro new`, `micro agent preflight`, `micro run`, `micro chat`, and `micro inspect agent` stay available for the documented first-agent walkthrough. | `go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1` |
 | Run | `micro run` remains the local development entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` |
 | Chat | `micro chat` remains the interactive agent entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` |
 | Inspect | `micro inspect agent`, `micro inspect flow`, and `micro flow runs` remain discoverable for run history. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` |
 | Deploy | `micro deploy --dry-run` resolves deploy targets without touching remote infrastructure. | `go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1` |
+| Smallest first agent | `examples/first-agent` runs one service-backed agent with a deterministic mock model and no provider key. | `go test ./examples/first-agent -run TestRunFirstAgent -count=1` |
 | Runtime reference app | `examples/support` runs typed services, an agent using those services as tools, an event-driven flow handoff, and an approval gate with only the model mocked. | `go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1` |
 | Runtime harnesses | Real services, agents, durable flows, store-backed history, delegation, and A2A run with only the model mocked. | `./internal/harness/zero-to-hero-ci/run.sh` and `make provider-conformance-mock` |
 
 ## Run the runnable example
 
-From the repository root, start with the support-desk example when you want to see the full lifecycle in one terminal:
+From the repository root, start with the smallest service-backed agent when you want the fastest no-secret success path:
+
+```sh
+go run ./examples/first-agent
+```
+
+Then run the support-desk example when you want to see the full lifecycle in one terminal:
 
 ```sh
 go run ./examples/support
@@ -67,6 +75,9 @@ go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1
 go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1
 go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1
 
+# Smallest no-secret service-backed first agent.
+go test ./examples/first-agent -run TestRunFirstAgent -count=1
+
 # Maintained 0→hero support-desk reference app.
 go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1
 
@@ -82,6 +93,9 @@ make provider-conformance-mock
 
 ## Reference scenarios
 
+- [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent)
+  is the smallest no-secret service-backed agent: one notes service, one scoped
+  assistant agent, and a deterministic mock model.
 - [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support)
   is the runnable support-desk story: customers, tickets, notify, a support
   agent, an intake flow, and an approval gate in one no-secret example.

internal/website/docs/index.md

@@ -16,7 +16,7 @@ It's built on a pluggable architecture of Go interfaces: service discovery, clie
 
 ## Learn More
 
-Start with [Getting Started](getting-started.html) for install and the first local service. Then follow the first-agent on-ramp: [No-secret first-agent transcript](guides/no-secret-first-agent.html) to run a mock-model support agent, [Your First Agent](guides/your-first-agent.html) to build and chat with a service-backed agent, [Debugging your agent](guides/debugging-agents.html) to inspect runs and memory, and the [0→hero reference path](guides/zero-to-hero.html) to walk the full scaffold → run → chat → inspect → deploy dry-run lifecycle covered by CI.
+Start with [Getting Started](getting-started.html) for install and the first local service. Then follow the first-agent on-ramp: `micro agent demo` for the installed no-secret CLI affordance, [No-secret first-agent transcript](guides/no-secret-first-agent.html) to run a mock-model support agent, [Your First Agent](guides/your-first-agent.html) to build and chat with a service-backed agent, [Debugging your agent](guides/debugging-agents.html) to inspect runs and memory, and the [0→hero reference path](guides/zero-to-hero.html) to walk the full scaffold → run → chat → inspect → deploy dry-run lifecycle covered by CI.
 
 Otherwise continue to read the docs for more information about the framework.
 
@@ -24,6 +24,7 @@ Otherwise continue to read the docs for more information about the framework.
 
 - [Getting Started](getting-started.html)
 - [0→hero Reference](guides/zero-to-hero.html) - Walk scaffold → run → chat → inspect → deploy dry-run with CI-backed commands
+- `micro agent demo` - Show the provider-free first-agent demo command and next docs steps
 - [No-secret first-agent transcript](guides/no-secret-first-agent.html) - Run the first useful agent path without a provider key
 - [Your First Agent](guides/your-first-agent.html) - Build a service-backed agent end to end
 - [MCP & AI Agents](mcp.html) - Turn services into AI-callable tools with the Model Context Protocol

internal/website/docs/quickstart.md

@@ -39,9 +39,10 @@ curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
 
 You now have the service half of the services → agents → workflows lifecycle running locally. Keep the on-ramp going in this order:
 
-1. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
-2. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
-3. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
+1. **[Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)** - run a mock-model, no-secret agent before adding provider keys.
+2. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
+3. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
+4. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
 
 After that first-agent path, branch out to:
 
@@ -56,7 +57,11 @@ After that first-agent path, branch out to:
 ```go
 package main
 
-import "go-micro.dev/v6"
+import (
+    "context"
+
+    "go-micro.dev/v6"
+)
 
 type Greeter struct{}
 
@@ -74,7 +79,11 @@ func main() {
 
 ### Pub/Sub Event Handler
 ```go
-import "go-micro.dev/v6"
+import (
+    "context"
+
+    "go-micro.dev/v6"
+)
 
 func main() {
     service := micro.NewService("subscriber")
@@ -82,7 +91,7 @@ func main() {
     // Subscribe to events
     micro.RegisterSubscriber("user.created", service.Server(), 
         func(ctx context.Context, event *UserCreatedEvent) error {
-            log.Infof("User created: %s", event.Email)
+            // Handle the event here.
             return nil
         },
     )