docs(priorities): refresh planner queue for 3732

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

.github/loop/PRIORITIES.md

@@ -21,13 +21,11 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Keep plan-delegate runs open until delegation completes** ([#3674](https://github.com/micro/go-micro/issues/3674)) — PR #3677 closed the universe A2A reachability blocker, and the latest live conformance failure is now the plan/delegate harness completing with an unfinished delegation step and no notification side effect. This is the highest-value Now-phase lifecycle gap because a developer's first multi-agent workflow must not report success while delegated work is still in progress.
-2. **Make the examples index a walkable first-agent map** ([#3671](https://github.com/micro/go-micro/issues/3671)) — recent README/docs work surfaced the first-agent on-ramp, and blog #33 sharpened the dogfooded loop story; the next adoption gap is example wayfinding. A newcomer should be able to move from first service to first agent to first workflow from the examples surface without stitching together README, website docs, and directories by hand.
-3. **Expose `fallback_echo` during A2A streaming fallback conformance** ([#3560](https://github.com/micro/go-micro/issues/3560)) — this remains the next scoped Now-phase interop/conformance gap: it protects the A2A streaming promise developers see in the README and site by ensuring the non-native streaming fallback path receives the tool surface, while staying behind the immediate multi-agent correctness and on-ramp blockers.
-4. **Parse multi-event A2A SSE fallback responses in the harness** ([#3662](https://github.com/micro/go-micro/issues/3662)) — once the fallback tool path succeeds, the harness must accept legitimate multi-event `message/stream` responses instead of concatenating valid SSE events into invalid JSON. This is a small CI-verifiable harness fix that keeps cross-provider streaming conformance focused on real gateway failures rather than parser brittleness.
-5. **Propagate agent run cancellation and deadlines through model and tool calls** ([#3544](https://github.com/micro/go-micro/issues/3544)) — the highest-value remaining Now-phase resilience gap after the live-provider side-effect fixes is predictable failure semantics across agent runs, model calls, tool calls, plan/delegate, and flow handoffs. Tool retries and live-provider deadline tuning are in place; the lifecycle still needs cancellation/deadline propagation so work fails safely instead of becoming opaque loops.
-6. **Emit OpenTelemetry spans for agent run timelines** ([#3525](https://github.com/micro/go-micro/issues/3525)) — recent work made runs inspectable, correlated trace metadata through scheduled dispatch, verified restart resume, added opt-in tool retries, hardened provider conformance, and fixed provider-emitted text tool calls. The next Next-phase step is to turn that RunInfo foundation into standard OTel spans for agent runs, model calls, tool calls, checkpoint/resume, cancellation/deadlines, and failures.
-7. **Add an AP2 mandate layer over A2A and x402** ([#3552](https://github.com/micro/go-micro/issues/3552)) — this is a forward interop investment, not a Now-phase 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 away from adoption, resilience, or observability. Keep it additive and opt-in while the AP2/FIDO work settles.
+1. **Expose `fallback_echo` during A2A streaming fallback conformance** ([#3560](https://github.com/micro/go-micro/issues/3560)) — PR #3731 closed the plan/delegate completion regression, so this is now the top remaining Now-phase interop/conformance gap. It protects the A2A streaming promise developers see in the README and site by ensuring the non-native streaming fallback path receives the tool surface, while staying scoped and CI-verifiable.
+2. **Parse multi-event A2A SSE fallback responses in the harness** ([#3662](https://github.com/micro/go-micro/issues/3662)) — once the fallback tool path succeeds, the harness must accept legitimate multi-event `message/stream` responses instead of concatenating valid SSE events into invalid JSON. This is a small CI-verifiable harness fix that keeps cross-provider streaming conformance focused on real gateway failures rather than parser brittleness.
+3. **Propagate agent run cancellation and deadlines through model and tool calls** ([#3544](https://github.com/micro/go-micro/issues/3544)) — the highest-value remaining resilience gap is predictable failure semantics across agent runs, model calls, tool calls, plan/delegate, and flow handoffs. Tool retries, live-provider deadline tuning, and delegated-plan completion are in place; the lifecycle still needs cancellation/deadline propagation so work fails safely instead of becoming opaque loops.
+4. **Emit OpenTelemetry spans for agent run timelines** ([#3525](https://github.com/micro/go-micro/issues/3525)) — recent work made runs inspectable, correlated trace metadata through scheduled dispatch, verified restart resume, added opt-in tool retries, hardened provider conformance, and fixed provider-emitted text tool calls. The next Next-phase step is to turn that RunInfo foundation into standard OTel spans for agent runs, model calls, tool calls, checkpoint/resume, cancellation/deadlines, and failures.
+5. **Add an AP2 mandate layer over A2A and x402** ([#3552](https://github.com/micro/go-micro/issues/3552)) — this is a forward interop investment, not a Now-phase 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 away from adoption, resilience, or observability. Keep it additive and opt-in while the AP2/FIDO work settles.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

.github/loop/prompts/triage.md

@@ -1,14 +1,14 @@
 <!--
-The TRIAGE prompt — go-micro's harness-failure feedback path. Editable policy;
-the workflow prepends the agent @mention and substitutes __ISSUE__ (this
-tracking issue) and __RUNURL__ (the failed run) before posting. Keep both literal.
+The TRIAGE prompt — go-micro's CI-failure feedback path. Editable policy; the
+workflow prepends the agent @mention and substitutes __ISSUE__ (this tracking
+issue) and __RUNURL__ (the failed run) before posting. Keep both literal.
 -->
-Triage the failed provider-conformance harness run at __RUNURL__.
+Triage the failed CI run at __RUNURL__. It may be the linter (Lint), the unit/integration tests (Run Tests), or the provider-conformance harness (Harness (E2E)).
 
 Read the logs and root-cause each distinct failure. DEDUPE against open issues — if a failure matches an existing issue, comment "recurred" there instead of filing a duplicate.
 
-For each genuine, self-contained defect, file a scoped issue (`gh issue create --label codex --label enhancement --title "<scoped fix>" --body "<root cause, where, acceptance criteria>"`) so the increment loop builds it and the next harness run verifies it.
+For each genuine, self-contained defect, file a scoped issue (`gh issue create --label codex --label enhancement --title "<scoped fix>" --body "<root cause, where, acceptance criteria>"`) so the increment loop builds it and the next CI/harness run verifies it. A lint or test failure on master is a real regression — file it so it is fixed promptly; do NOT ignore it.
 
-IGNORE transient flakes — live-model latency, provider outages, rate limits, timeouts with no code cause. Anything needing a breaking or architectural change: file it as `needs-human` and describe it, rather than auto-queuing it as a routine fix.
+IGNORE only genuine transient flakes — live-model latency, provider outages, rate limits, network timeouts with no code cause (mostly relevant to the harness). Anything needing a breaking or architectural change: file it as `needs-human` and describe it, rather than auto-queuing it as a routine fix.
 
 Close this issue (`gh issue close __ISSUE__`) when triage is done. Open any PR yourself from the shell with `gh`; do not use the make_pr tool.

.github/workflows/loop-triage.yml

@@ -1,14 +1,14 @@
 name: "Loop: Triage"
 
-# Generated by `micro loop init`. The feedback path of the evaluator: when the
-# CI workflow ("Harness (E2E)") fails on a non-PR run, dispatch the agent
+# Generated by `micro loop init`. The feedback path of the evaluator: when a CI
+# workflow (Harness (E2E), Lint, Run Tests) fails on a non-PR run, dispatch the agent
 # (@codex) with the instruction in .github/loop/prompts/triage.md
 # to root-cause the failure and file scoped fix issues back into the queue — so
 # failures become fixes with no human in the middle. Gated on CODEX_TRIGGER_TOKEN.
 
 on:
   workflow_run:
-    workflows: ["Harness (E2E)"]
+    workflows: ["Harness (E2E)", "Lint", "Run Tests"]
     types: [completed]
 
 permissions:
@@ -33,6 +33,7 @@ jobs:
           REPO: ${{ github.repository }}
           RUN_ID: ${{ github.event.workflow_run.id }}
           RUN_URL: ${{ github.event.workflow_run.html_url }}
+          WORKFLOW_NAME: ${{ github.event.workflow_run.name }}
         run: |
           if [ "$HAS_TOKEN" != "true" ]; then
             echo "CODEX_TRIGGER_TOKEN is not set — skipping."
@@ -44,8 +45,8 @@ jobs:
             exit 1
           fi
           ISSUE_URL=$(gh issue create --repo "$REPO" \
-            --title "Loop: triage failed run $RUN_ID" \
-            --body "The 'Harness (E2E)' workflow failed: $RUN_URL")
+            --title "Loop: triage failed run $RUN_ID ($WORKFLOW_NAME)" \
+            --body "The '$WORKFLOW_NAME' workflow failed on a non-PR run: $RUN_URL")
           ISSUE_NUM="${ISSUE_URL##*/}"
           echo "Opened issue #$ISSUE_NUM — dispatching triage."
           {

README.md

@@ -87,12 +87,14 @@ make harness
 After install and the first `micro new`/`micro run` smoke check, take the
 walkable agent path in this order:
 
-1. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
+1. [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
    service-backed agent and talk to it with `micro chat`.
-2. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
+3. [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.
-3. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
+4. [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.
 

agent/agent.go

@@ -293,57 +293,77 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 		}
 	}
 
-	resp, err := ai.GenerateWithRetry(ctx, a.model, &ai.Request{
-		Prompt:       message,
-		SystemPrompt: a.buildPrompt(),
-		Tools:        toolList,
-		Messages:     messages,
-	}, ai.GeneratePolicy{
-		Timeout:     a.opts.ModelTimeout,
-		MaxAttempts: a.opts.ModelMaxAttempts,
-		Backoff:     a.opts.ModelRetryBackoff,
-	})
-	if err != nil {
-		run.Status = agentRunFailureStatus(err)
-		if a.currentRun != nil {
-			run.Steps = a.currentRun.Steps
-		}
-		if len(run.Steps) == 0 {
-			run.Steps = []flow.StepRecord{{Name: agentAskStep}}
-		}
-		run.Steps[0].Status = run.Status
-		run.Steps[0].Error = err.Error()
-		_ = a.saveRun(ctx, run)
-		return nil, err
-	}
-	if a.pause != nil && a.opts.Checkpoint != nil {
-		run.Status = "paused"
-		run.State.Stage = agentApprovalStep
-		run.State.Data = []byte(message)
-		if a.pause.Tool == toolHumanInput {
-			run.State.Stage = agentInputStep
-			_ = run.State.Set(inputPause{OriginalMessage: message, Prompt: a.pause.Message})
-		}
-		run.Steps[0].Status = "paused"
-		run.Steps[0].Error = a.pause.Message
-		run.Steps[0].Result = a.pause.Tool
-		if err := a.saveRun(ctx, run); err != nil {
+	const maxPlanCompletionTurns = 3
+	var resp *ai.Response
+	for planCompletionTurn := 0; ; planCompletionTurn++ {
+		resp, err = ai.GenerateWithRetry(ctx, a.model, &ai.Request{
+			Prompt:       message,
+			SystemPrompt: a.buildPrompt(),
+			Tools:        toolList,
+			Messages:     messages,
+		}, ai.GeneratePolicy{
+			Timeout:     a.opts.ModelTimeout,
+			MaxAttempts: a.opts.ModelMaxAttempts,
+			Backoff:     a.opts.ModelRetryBackoff,
+		})
+		if err != nil {
+			run.Status = agentRunFailureStatus(err)
+			if a.currentRun != nil {
+				run.Steps = a.currentRun.Steps
+			}
+			if len(run.Steps) == 0 {
+				run.Steps = []flow.StepRecord{{Name: agentAskStep}}
+			}
+			run.Steps[0].Status = run.Status
+			run.Steps[0].Error = err.Error()
+			_ = a.saveRun(ctx, run)
 			return nil, err
 		}
-		return nil, fmt.Errorf("agent run %s paused for approval: %s", run.ID, a.pause.Message)
-	}
-
-	if len(resp.ToolCalls) == 0 {
-		if calls, answer, ok := a.executeTextToolCalls(ctx, resp.Reply, toolList); ok {
-			resp.ToolCalls = calls
-			if resp.Answer == "" {
-				resp.Answer = answer
+		if a.pause != nil && a.opts.Checkpoint != nil {
+			run.Status = "paused"
+			run.State.Stage = agentApprovalStep
+			run.State.Data = []byte(message)
+			if a.pause.Tool == toolHumanInput {
+				run.State.Stage = agentInputStep
+				_ = run.State.Set(inputPause{OriginalMessage: message, Prompt: a.pause.Message})
 			}
-			trimmedReply := strings.TrimSpace(resp.Reply)
-			if strings.HasPrefix(trimmedReply, "{") || strings.HasPrefix(trimmedReply, "[") || strings.HasPrefix(trimmedReply, "```") {
-				resp.Reply = ""
+			run.Steps[0].Status = "paused"
+			run.Steps[0].Error = a.pause.Message
+			run.Steps[0].Result = a.pause.Tool
+			if err := a.saveRun(ctx, run); err != nil {
+				return nil, err
+			}
+			return nil, fmt.Errorf("agent run %s paused for approval: %s", run.ID, a.pause.Message)
+		}
+
+		if len(resp.ToolCalls) == 0 {
+			if calls, answer, ok := a.executeTextToolCalls(ctx, resp.Reply, toolList); ok {
+				resp.ToolCalls = calls
+				if resp.Answer == "" {
+					resp.Answer = answer
+				}
+				trimmedReply := strings.TrimSpace(resp.Reply)
+				if strings.HasPrefix(trimmedReply, "{") || strings.HasPrefix(trimmedReply, "[") || strings.HasPrefix(trimmedReply, "```") {
+					resp.Reply = ""
+				}
 			}
 		}
+
+		if a.opts.Checkpoint != nil {
+			if unfinished := a.unfinishedPlanSteps(); len(unfinished) > 0 && planCompletionTurn < maxPlanCompletionTurns {
+				if resp.Reply != "" {
+					a.mem.Add("assistant", resp.Reply)
+				}
+				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, ", ")
+				a.mem.Add("user", message)
+				messages = a.mem.Messages()
+				continue
+			}
+		}
+		break
 	}
 
 	if resp.Reply != "" {
@@ -368,6 +388,24 @@ func (a *agentImpl) askLocked(ctx context.Context, runID, message, parentRunID s
 		RunID:     a.runID,
 		ParentID:  parentRunID,
 	}
+	if a.opts.Checkpoint != nil {
+		if unfinished := a.unfinishedPlanSteps(); len(unfinished) > 0 {
+			err = fmt.Errorf("agent run %s has unfinished plan steps: %s", run.ID, strings.Join(unfinished, ", "))
+			run.Status = "failed"
+			run.State.Stage = agentAskStep
+			run.State.Data = []byte(message)
+			if a.currentRun != nil {
+				run.Steps = a.currentRun.Steps
+			}
+			if len(run.Steps) == 0 {
+				run.Steps = []flow.StepRecord{{Name: agentAskStep}}
+			}
+			run.Steps[0].Status = "failed"
+			run.Steps[0].Error = err.Error()
+			_ = a.saveRun(ctx, run)
+			return nil, err
+		}
+	}
 	run.Status = "done"
 	run.State.Stage = ""
 	if b, marshalErr := json.Marshal(res); marshalErr == nil {

agent/builtin.go

@@ -402,6 +402,38 @@ func (a *agentImpl) completeNextPlanStep() {
 	}
 }
 
+func (a *agentImpl) unfinishedPlanSteps() []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
+		}
+		status, _ := step["status"].(string)
+		if status != "" && status != "pending" && status != "in_progress" {
+			continue
+		}
+		task, _ := step["task"].(string)
+		if task == "" {
+			task = "<unnamed>"
+		}
+		unfinished = append(unfinished, task)
+	}
+	return unfinished
+}
+
 // handleHumanInput records that the model needs operator input before it can continue.
 func (a *agentImpl) handleHumanInput(call ai.ToolCall) ai.ToolResult {
 	prompt, _ := call.Input["prompt"].(string)

agent/checkpoint_test.go

@@ -7,7 +7,10 @@ import (
 	"testing"
 
 	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/client"
+	codecBytes "go-micro.dev/v6/codec/bytes"
 	"go-micro.dev/v6/flow"
+	"go-micro.dev/v6/registry"
 	"go-micro.dev/v6/store"
 )
 
@@ -141,6 +144,81 @@ func TestCheckpointSkipsDuplicateToolWithinAsk(t *testing.T) {
 	}
 }
 
+func TestCheckpointContinuesRunWithUnfinishedPlanStep(t *testing.T) {
+	ctx := context.Background()
+	cp := flow.StoreCheckpoint(store.NewMemoryStore(), "unfinished-plan-agent")
+
+	reg := registry.NewMemoryRegistry()
+	if err := reg.Register(&registry.Service{
+		Name:     "comms",
+		Metadata: map[string]string{"type": "agent"},
+		Nodes:    []*registry.Node{{Id: "comms-1", Address: "127.0.0.1:0"}},
+	}); err != nil {
+		t.Fatalf("register comms agent: %v", err)
+	}
+
+	delegateCalls := 0
+	fc := &fakeClient{Client: client.DefaultClient}
+	fc.callFn = func(ctx context.Context, req client.Request, rsp interface{}) error {
+		delegateCalls++
+		if req.Service() != "comms" || req.Endpoint() != "Agent.Chat" {
+			t.Fatalf("delegate RPC = %s %s, want comms Agent.Chat", req.Service(), req.Endpoint())
+		}
+		frame := rsp.(*codecBytes.Frame)
+		frame.Data = []byte(`{"reply":"owner notified","agent":"comms"}`)
+		return nil
+	}
+
+	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 launch tasks", "status": "done"},
+					map[string]any{"task": "delegate readiness notification to comms", "status": "in_progress"},
+				},
+			}})
+			return &ai.Response{Reply: "tasks are ready"}, nil
+		case 2:
+			if !strings.Contains(req.Prompt, "delegate readiness notification to comms") {
+				t.Fatalf("continuation prompt = %q, want unfinished step", req.Prompt)
+			}
+			res := opts.ToolHandler(ctx, ai.ToolCall{ID: "delegate-1", Name: toolDelegate, Input: map[string]any{"task": "Notify owner@acme.com that the launch plan is ready", "to": "comms"}})
+			if !strings.Contains(res.Content, "owner notified") {
+				t.Fatalf("delegate result = %q, want owner notified", res.Content)
+			}
+			return &ai.Response{Reply: "all done"}, nil
+		default:
+			t.Fatalf("unexpected model call %d", modelCalls)
+			return nil, nil
+		}
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("unfinished-plan-agent"), WithCheckpoint(cp), WithRegistry(reg), WithClient(fc))
+	resp, err := a.Ask(ctx, "create tasks and notify owner")
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if resp.Reply != "all done" {
+		t.Fatalf("reply = %q, want final continuation reply", resp.Reply)
+	}
+	if modelCalls != 2 {
+		t.Fatalf("model calls = %d, want initial plus continuation", modelCalls)
+	}
+	if delegateCalls != 1 {
+		t.Fatalf("delegate calls = %d, want exactly one", delegateCalls)
+	}
+	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")

cmd/micro/loop/loop.go

@@ -40,10 +40,11 @@ var templatesFS embed.FS
 // given repo tunes.
 type config struct {
 	// Shared.
-	DefaultBranch string // base branch for the loop's PRs (e.g. main)
-	AgentMention  string // how the workflows summon the agent (e.g. @codex)
-	TokenSecret   string // repo secret holding the user PAT that drives dispatch
-	CIWorkflow    string // name: of the CI workflow triage watches for failures
+	DefaultBranch   string // base branch for the loop's PRs (e.g. main)
+	AgentMention    string // how the workflows summon the agent (e.g. @codex)
+	TokenSecret     string // repo secret holding the user PAT that drives dispatch
+	CIWorkflow      string // human-readable CI workflow name(s) triage watches
+	CIWorkflowsYAML string // the same as a YAML array literal, e.g. ["Lint", "Run Tests"]
 
 	// Per-dispatch-role (set while rendering each one).
 	Role         string
@@ -122,7 +123,7 @@ Examples:
 					&cli.StringFlag{Name: "branch", Usage: "Base branch for the loop's PRs (auto-detected if empty)"},
 					&cli.StringFlag{Name: "agent", Usage: "How the workflows summon the agent (an @mention)", Value: "@codex"},
 					&cli.StringFlag{Name: "token-secret", Usage: "Repo secret holding the user PAT that drives dispatch", Value: "LOOP_TOKEN"},
-					&cli.StringFlag{Name: "ci-workflow", Usage: "name: of the CI workflow triage watches for failures", Value: "CI"},
+					&cli.StringFlag{Name: "ci-workflow", Usage: "CI workflow name(s) triage watches for failures (comma-separated)", Value: "CI"},
 					&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 * * *"},
@@ -149,13 +150,15 @@ func runInit(c *cli.Context) error {
 		return err
 	}
 
+	ciNames := splitCSV(c.String("ci-workflow"))
 	cfg := config{
-		DefaultBranch: c.String("branch"),
-		AgentMention:  strings.TrimSpace(c.String("agent")),
-		TokenSecret:   strings.TrimSpace(c.String("token-secret")),
-		CIWorkflow:    c.String("ci-workflow"),
-		TagPrefix:     c.String("tag-prefix"),
-		ReleaseCron:   c.String("release-cron"),
+		DefaultBranch:   c.String("branch"),
+		AgentMention:    strings.TrimSpace(c.String("agent")),
+		TokenSecret:     strings.TrimSpace(c.String("token-secret")),
+		CIWorkflow:      strings.Join(ciNames, ", "),
+		CIWorkflowsYAML: yamlStringArray(ciNames),
+		TagPrefix:       c.String("tag-prefix"),
+		ReleaseCron:     c.String("release-cron"),
 	}
 	if cfg.DefaultBranch == "" {
 		cfg.DefaultBranch = detectDefaultBranch(dir)
@@ -205,6 +208,30 @@ func parseRoles(spec string) ([]string, error) {
 	return out, nil
 }
 
+// splitCSV splits a comma-separated flag into trimmed, non-empty values.
+func splitCSV(s string) []string {
+	var out []string
+	for _, v := range strings.Split(s, ",") {
+		if v = strings.TrimSpace(v); v != "" {
+			out = append(out, v)
+		}
+	}
+	if len(out) == 0 {
+		out = []string{"CI"}
+	}
+	return out
+}
+
+// yamlStringArray renders names as a YAML/JSON flow array, e.g. ["Lint", "Run Tests"].
+// Names are known workflow display names (no embedded quotes), so a simple quote is safe.
+func yamlStringArray(names []string) string {
+	quoted := make([]string, len(names))
+	for i, n := range names {
+		quoted[i] = fmt.Sprintf("%q", n)
+	}
+	return "[" + strings.Join(quoted, ", ") + "]"
+}
+
 func isRole(r string) bool {
 	for _, x := range allRoles {
 		if x == r {

cmd/micro/loop/loop_test.go

@@ -8,12 +8,13 @@ import (
 )
 
 var testCfg = config{
-	DefaultBranch: "main",
-	AgentMention:  "@codex",
-	TokenSecret:   "LOOP_TOKEN",
-	CIWorkflow:    "CI",
-	TagPrefix:     "v",
-	ReleaseCron:   "0 23 * * *",
+	DefaultBranch:   "main",
+	AgentMention:    "@codex",
+	TokenSecret:     "LOOP_TOKEN",
+	CIWorkflow:      "CI",
+	CIWorkflowsYAML: `["CI"]`,
+	TagPrefix:       "v",
+	ReleaseCron:     "0 23 * * *",
 }
 
 var testCrons = map[string]string{"planner": "0 * * * *", "builder": "30 * * * *", "coherence": "0 7 * * *"}
@@ -201,6 +202,25 @@ func TestReinitForceKeepsPromptsRefreshesWorkflows(t *testing.T) {
 	}
 }
 
+func TestCIWorkflowListRendersAsYAMLArray(t *testing.T) {
+	if got := yamlStringArray([]string{"Harness (E2E)", "Lint", "Run Tests"}); got != `["Harness (E2E)", "Lint", "Run Tests"]` {
+		t.Errorf("yamlStringArray = %q", got)
+	}
+	if got := splitCSV("Harness (E2E), Lint ,Run Tests"); strings.Join(got, "|") != "Harness (E2E)|Lint|Run Tests" {
+		t.Errorf("splitCSV = %v", got)
+	}
+	if got := splitCSV("  "); strings.Join(got, "|") != "CI" {
+		t.Errorf("splitCSV empty should default to CI, got %v", got)
+	}
+	// The triage workflow must embed the array so workflow_run watches all of them.
+	cfg := testCfg
+	cfg.CIWorkflowsYAML = `["Harness (E2E)", "Lint", "Run Tests"]`
+	s := mustRender(t, "templates/loop-triage.yml.tmpl", cfg)
+	if !strings.Contains(s, `workflows: ["Harness (E2E)", "Lint", "Run Tests"]`) {
+		t.Errorf("triage workflow does not watch the CI workflow list:\n%s", s)
+	}
+}
+
 func TestParseRoles(t *testing.T) {
 	if got, err := parseRoles("all"); err != nil || len(got) != len(allRoles) {
 		t.Errorf("all => %v, %v", got, err)

cmd/micro/loop/templates/loop-triage.yml.tmpl

@@ -1,14 +1,14 @@
 name: "Loop: Triage"
 
-# Generated by `micro loop init`. The feedback path of the evaluator: when the
-# CI workflow ("<< .CIWorkflow >>") fails on a non-PR run, dispatch the agent
+# Generated by `micro loop init`. The feedback path of the evaluator: when a CI
+# workflow (<< .CIWorkflow >>) fails on a non-PR run, dispatch the agent
 # (<< .AgentMention >>) with the instruction in .github/loop/prompts/triage.md
 # to root-cause the failure and file scoped fix issues back into the queue — so
 # failures become fixes with no human in the middle. Gated on << .TokenSecret >>.
 
 on:
   workflow_run:
-    workflows: ["<< .CIWorkflow >>"]
+    workflows: << .CIWorkflowsYAML >>
     types: [completed]
 
 permissions:
@@ -33,6 +33,7 @@ jobs:
           REPO: ${{ github.repository }}
           RUN_ID: ${{ github.event.workflow_run.id }}
           RUN_URL: ${{ github.event.workflow_run.html_url }}
+          WORKFLOW_NAME: ${{ github.event.workflow_run.name }}
         run: |
           if [ "$HAS_TOKEN" != "true" ]; then
             echo "<< .TokenSecret >> is not set — skipping."
@@ -44,8 +45,8 @@ jobs:
             exit 1
           fi
           ISSUE_URL=$(gh issue create --repo "$REPO" \
-            --title "Loop: triage failed run $RUN_ID" \
-            --body "The '<< .CIWorkflow >>' workflow failed: $RUN_URL")
+            --title "Loop: triage failed run $RUN_ID ($WORKFLOW_NAME)" \
+            --body "The '$WORKFLOW_NAME' workflow failed on a non-PR run: $RUN_URL")
           ISSUE_NUM="${ISSUE_URL##*/}"
           echo "Opened issue #$ISSUE_NUM — dispatching triage."
           {

examples/README.md

@@ -1,14 +1,34 @@
 # Go Micro Examples
 
-This directory contains runnable examples demonstrating various go-micro features and patterns.
+This directory contains runnable examples that take you through the Go Micro
+lifecycle: start with a service, expose it as agent-usable capability, then
+coordinate work with workflows.
 
 ## Quick Start
 
-Each example can be run with `go run .` from its directory.
+Each example can be run with `go run .` from its directory unless its README says
+otherwise. If you are new to the repo, follow the first-agent path below instead
+of reading the directories alphabetically.
 
-## Examples
+## Recommended first-agent path
 
-### [hello-world](./hello-world/)
+| 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/). |
+| 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
+[`mcp/hello`](./mcp/hello/) → [`mcp/crud`](./mcp/crud/) →
+[`mcp/workflow`](./mcp/workflow/). For debugging and production hardening, keep
+[`agent-wrap-tool`](./agent-wrap-tool/), [`agent-durable`](./agent-durable/), and
+[`deployment`](./deployment/) nearby.
+
+## Lifecycle map
+
+### 1. Services — learn the runtime foundation
+
+#### [hello-world](./hello-world/)
 Basic RPC service demonstrating core concepts:
 - Service creation and registration
 - Handler implementation
@@ -21,7 +41,7 @@ cd hello-world
 go run .
 ```
 
-### [web-service](./web-service/)
+#### [web-service](./web-service/)
 HTTP web service with service discovery:
 - HTTP handlers
 - Service registration
@@ -34,7 +54,7 @@ cd web-service
 go run .
 ```
 
-### [multi-service](./multi-service/)
+#### [multi-service](./multi-service/)
 Multiple services in a single binary — the modular monolith pattern:
 - Isolated server, client, store, and cache per service
 - Shared registry and broker for inter-service communication
@@ -47,44 +67,76 @@ cd multi-service
 go run .
 ```
 
-### [deployment](./deployment/)
+#### [deployment](./deployment/)
 Docker Compose deployment with MCP gateway, Consul registry, and Jaeger tracing:
 - Production-like architecture in one `docker-compose up`
 - Standalone MCP gateway connected to service registry
 - Distributed tracing with OpenTelemetry + Jaeger
 
-### MCP Examples
+### 2. Agents — turn services into tool-using teammates
+
+#### [agent-demo](./agent-demo/)
+Recommended first agent: a multi-service project management app with Projects,
+Tasks, and Team services, seed data, and agent playground integration.
+
+#### [agent-plan-delegate](./agent-plan-delegate/)
+The two built-in agent capabilities in a small multi-agent system:
+- **plan** — an agent records an ordered plan in its store-backed memory before doing multi-step work
+- **delegate** — an agent hands a subtask to another agent (over RPC if it's registered, else to an ephemeral sub-agent)
+
+#### [agent-wrap-tool](./agent-wrap-tool/)
+Middleware around an agent's tool execution with `AgentWrapTool`, the tool-side analogue of client/server wrappers:
+- **observe** — time every tool call and record per-tool metrics, correlated by call ID
+- **retry** — re-run a call whose result is an error, recovering from a transient failure before the model sees it
+
+#### [agent-durable](./agent-durable/)
+Durable agent runs that can be checkpointed and resumed, useful once your first
+agent needs predictable recovery behavior.
+
+#### [agent-human-input](./agent-human-input/)
+Human-in-the-loop agent interaction for decisions that need an explicit person
+before the run can continue.
+
+#### [agent-ollama](./agent-ollama/)
+Local-model agent wiring for developers experimenting with Ollama-backed model
+calls.
+
+### 3. Workflows — coordinate longer-running work
+
+#### [support](./support/)
+A maintained 0-to-hero reference path in one runnable file:
+- **scaffold** typed `customers`, `tickets`, and `notify` services
+- **run/chat** with a support agent that uses those services as tools
+- **inspect** the event-driven `intake` flow and approval gate
+- **CI** keeps the deterministic mock-model journey runnable with `go test ./examples/support`
+
+#### [flow-durable](./flow-durable/)
+A workflow as ordered, checkpointed steps that survives a crash and resumes where it stopped:
+- **steps** — a flow is a task with stages (`reserve → charge → confirm`), not just one LLM turn
+- **Checkpoint** — each step is persisted; on `Resume`, completed steps are not re-run (no duplicate side effects)
+
+#### [flow-loop](./flow-loop/)
+A looping flow example for repeated workflow steps.
+
+### 4. MCP and agent integration examples
 
 See the [mcp/](./mcp/) directory for AI agent integration examples:
 - **[hello](./mcp/hello/)** - Minimal MCP service (start here)
 - **[crud](./mcp/crud/)** - CRUD contact book with full agent documentation
 - **[workflow](./mcp/workflow/)** - Cross-service orchestration via AI agents
 - **[documented](./mcp/documented/)** - All MCP features with auth scopes
+- **[platform](./mcp/platform/)** - Platform-oriented MCP service example
 
-### [agent-demo](./agent-demo/)
-Multi-service project management app (Projects, Tasks, Team) with seed data and agent playground integration.
+## Other examples
 
-### [agent-plan-delegate](./agent-plan-delegate/)
-The two built-in agent capabilities in a small multi-agent system:
-- **plan** — an agent records an ordered plan in its store-backed memory before doing multi-step work
-- **delegate** — an agent hands a subtask to another agent (over RPC if it's registered, else to an ephemeral sub-agent)
+### [auth](./auth/)
+Authentication and authorization example.
 
-### [agent-wrap-tool](./agent-wrap-tool/)
-Middleware around an agent's tool execution with `AgentWrapTool`, the tool-side analogue of client/server wrappers:
-- **observe** — time every tool call and record per-tool metrics, correlated by call ID
-- **retry** — re-run a call whose result is an error, recovering from a transient failure before the model sees it
+### [graceful-stop](./graceful-stop/)
+Graceful shutdown behavior for long-running services.
 
-### [flow-durable](./flow-durable/)
-A workflow as ordered, checkpointed steps that survives a crash and resumes where it stopped:
-- **steps** — a flow is a task with stages (`reserve → charge → confirm`), not just one LLM turn
-- **Checkpoint** — each step is persisted; on `Resume`, completed steps are not re-run (no duplicate side effects)
-
-### [support](./support/)
-A maintained 0-to-hero reference path in one runnable file:
-- **scaffold** typed `customers`, `tickets`, and `notify` services
-- **run/chat** with a support agent that uses those services as tools
-- **inspect** the event-driven `intake` flow and approval gate
-- **CI** keeps the deterministic mock-model journey runnable with `go test ./examples/support`
+### [grpc-interop](./grpc-interop/)
+gRPC interoperability example.
 
 ## Coming Soon
 
@@ -106,6 +158,5 @@ To add a new example:
 1. Create a new directory
 2. Add a descriptive README.md
 3. Include working code with comments
-4. Add to this index
+4. Add to this index under the lifecycle stage it supports
 5. Ensure it runs with `go run .`
-

internal/docs/CONTINUOUS_IMPROVEMENT.md

@@ -22,7 +22,7 @@ Actions instead of subagents. Each role is a workflow:
 | **Planner** | `loop-planner.yml` — *Loop: Planner* | Tracks live state, prioritizes the roadmap + an internal scan, and maintains the ranked queue in [`.github/loop/PRIORITIES.md`](../../.github/loop/PRIORITIES.md). Decides *what*. |
 | **Generator** | `loop-builder.yml` — *Loop: Builder (Generator)* | Builds the top open queue item as a single-concern PR (via Codex) and self-merges on green CI. Does the work. |
 | **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)* | On harness failure, root-causes, dedupes, and files scoped fix issues back into the planner's queue. The hill-climbing feedback path. |
+| **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. |
 | **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. |
 
@@ -194,14 +194,16 @@ to redirect. Codex is serial, so these passes queue behind any in-flight increme
 ## Failure triage (the feedback loop)
 
 The loop also closes on its own failures. `.github/workflows/loop-triage.yml`
-fires when the live provider-conformance harness finishes with `conclusion:
-failure` (scheduled/manual runs only), and dispatches Codex to **triage** the
-failing run: read the logs, root-cause each distinct failure, **dedupe** against
-open issues (comment "recurred" rather than filing a duplicate), and file a scoped
-`codex`/`enhancement` issue for each genuine, self-contained defect — which the
-increment loop then builds and the next harness run verifies. Transient flakes
-(live-model latency, provider outages) are ignored; anything needing a breaking or
-architectural change is escalated as `needs-human` instead of auto-built. This is
+fires when a gate workflow — **Lint**, **Run Tests**, or the provider-conformance
+**Harness (E2E)** — finishes with `conclusion: failure` on a non-PR run (so a red
+lint or test on `master`, not just a harness failure, becomes a fix issue). It
+dispatches Codex to **triage** the failing run: read the logs, root-cause each
+distinct failure, **dedupe** against open issues (comment "recurred" rather than
+filing a duplicate), and file a scoped `codex`/`enhancement` issue for each genuine,
+self-contained defect — which the increment loop then builds and the next run
+verifies. Genuine transient flakes (live-model latency, provider outages) are
+ignored; anything needing a breaking or architectural change is escalated as
+`needs-human` instead of auto-built. This is
 the hill-climbing layer: CI/harness failures become fixes with no human in the
 middle, short of a decision that's genuinely the human's.
 

internal/harness/plan-delegate/main.go

@@ -135,9 +135,11 @@ type SendResponse struct {
 	Sent bool `json:"sent"`
 }
 type NotifyService struct {
-	mu     sync.Mutex
-	sent   int
-	bySend map[string]bool
+	mu         sync.Mutex
+	sent       int
+	attempts   int
+	duplicates int
+	bySend     map[string]bool
 }
 
 // Send delivers a notification message to a recipient. Duplicate delivery
@@ -150,11 +152,13 @@ func (s *NotifyService) Send(ctx context.Context, req *SendRequest, rsp *SendRes
 		s.bySend = map[string]bool{}
 	}
 	key := strings.ToLower(strings.TrimSpace(req.To)) + "\x00" + strings.ToLower(strings.TrimSpace(req.Message))
+	s.attempts++
 	if !s.bySend[key] {
 		s.bySend[key] = true
 		s.sent++
 		fmt.Printf("    \033[35m[notify]\033[0m 📨 to=%s message=%q\n", req.To, req.Message)
 	} else {
+		s.duplicates++
 		fmt.Printf("    \033[35m[notify]\033[0m reused to=%s message=%q\n", req.To, req.Message)
 	}
 	s.mu.Unlock()
@@ -168,13 +172,28 @@ func (s *NotifyService) count() int {
 	return s.sent
 }
 
+func (s *NotifyService) duplicateAttempts() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.duplicates
+}
+
 // ---------------------------------------------------------------------------
 // mock LLM provider — the ONLY fake. It "reasons" by simple heuristics
 // over the tools it's offered and the system prompt it's given, calling
 // the real tool handler exactly the way a real provider would.
 // ---------------------------------------------------------------------------
 
-type mockModel struct{ opts ai.Options }
+type mockModel struct {
+	opts ai.Options
+
+	// unknownDelegateOnce makes the mock emit one provider-style, unavailable
+	// delegate tool name before using the registered delegate tool. This mirrors
+	// live providers that occasionally hallucinate a provider-specific tool while
+	// still keeping the regression deterministic and keyless.
+	unknownDelegateOnce    bool
+	emittedUnknownDelegate bool
+}
 
 func newMock(opts ...ai.Option) ai.Model {
 	m := &mockModel{}
@@ -182,6 +201,12 @@ func newMock(opts ...ai.Option) ai.Model {
 	return m
 }
 
+func newMockUnknownDelegate(opts ...ai.Option) ai.Model {
+	m := &mockModel{unknownDelegateOnce: true}
+	_ = m.Init(opts...)
+	return m
+}
+
 func (m *mockModel) Init(opts ...ai.Option) error {
 	for _, o := range opts {
 		o(&m.opts)
@@ -247,10 +272,18 @@ func (m *mockModel) Generate(ctx context.Context, req *ai.Request, _ ...ai.Gener
 			}
 		}
 		if del := findTool(req.Tools, "delegate"); del != "" {
-			m.call("conductor", del, map[string]any{
-				"task": "Notify owner@acme.com that the launch plan is ready",
-				"to":   "comms",
-			})
+			if m.unknownDelegateOnce && !m.emittedUnknownDelegate {
+				m.emittedUnknownDelegate = true
+				m.call("conductor", "atlascloud_delegate", map[string]any{
+					"task": "Notify owner@acme.com that the launch plan is ready",
+					"to":   "comms",
+				})
+			} else {
+				m.call("conductor", del, map[string]any{
+					"task": "Notify owner@acme.com that the launch plan is ready",
+					"to":   "comms",
+				})
+			}
 		}
 		return &ai.Response{Answer: "Created Design, Build and Ship, and had comms notify the owner."}, nil
 
@@ -278,9 +311,12 @@ func providerKey(provider string) string {
 
 func runPlanDelegate(provider string) error {
 	apiKey := ""
-	if provider == "mock" {
+	switch provider {
+	case "mock":
 		ai.Register("mock", newMock)
-	} else {
+	case "mock-unknown-delegate":
+		ai.Register("mock-unknown-delegate", newMockUnknownDelegate)
+	default:
 		apiKey = providerKey(provider)
 		if apiKey == "" {
 			fmt.Printf("no API key for provider %q — set MICRO_AI_API_KEY or the provider's key env\n", provider)
@@ -370,8 +406,15 @@ func runPlanDelegate(provider string) error {
 	}
 
 	fmt.Print("\n\033[1m> flow:\033[0m services + agents + workflow + plan/delegate, no API key.\n\n")
-	if err := f.Execute(context.Background(), "launch readiness"); err != nil {
-		return fmt.Errorf("flow execute: %w", err)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	executeDone := make(chan error, 1)
+	go func() {
+		executeDone <- f.Execute(ctx, "launch readiness")
+	}()
+
+	if err := waitForPlanDelegateExecution(executeDone, notifySvc); err != nil {
+		return err
 	}
 
 	if rs := f.Results(); len(rs) > 0 {
@@ -392,8 +435,26 @@ func runPlanDelegate(provider string) error {
 	return nil
 }
 
+func waitForPlanDelegateExecution(done <-chan error, notifySvc *NotifyService) error {
+	ticker := time.NewTicker(50 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		select {
+		case err := <-done:
+			if err != nil {
+				return fmt.Errorf("flow execute: %w", err)
+			}
+			return nil
+		case <-ticker.C:
+			if dup := notifySvc.duplicateAttempts(); dup > 0 {
+				return fmt.Errorf("duplicate notify attempts: got %d duplicate replay(s), want 0", dup)
+			}
+		}
+	}
+}
+
 func main() {
-	provider := flag.String("provider", "mock", "LLM provider: mock (default), anthropic, openai, gemini, groq, mistral, together, atlascloud")
+	provider := flag.String("provider", "mock", "LLM provider: mock (default), mock-unknown-delegate, anthropic, openai, gemini, groq, mistral, together, atlascloud")
 	flag.Parse()
 
 	if err := runPlanDelegate(*provider); err != nil {

internal/harness/plan-delegate/main_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"strings"
 	"testing"
 	"time"
 
@@ -220,6 +221,15 @@ func TestZeroToHeroContract(t *testing.T) {
 	}
 }
 
+func TestPlanDelegateRetriesAfterUnknownDelegateTool(t *testing.T) {
+	if testing.Short() {
+		t.Skip("0→hero harness boots an end-to-end system; skipped with -short")
+	}
+	if err := runPlanDelegate("mock-unknown-delegate"); err != nil {
+		t.Fatalf("0→hero harness with unknown delegate retry: %v", err)
+	}
+}
+
 func TestTaskServiceAddIsIdempotentForLaunchTitles(t *testing.T) {
 	svc := new(TaskService)
 	for _, title := range []string{"Design", "design task", "Build", "Build launch task", "Ship", "ship readiness"} {
@@ -236,6 +246,32 @@ func TestTaskServiceAddIsIdempotentForLaunchTitles(t *testing.T) {
 	}
 }
 
+func TestPlanDelegateExecutionReportsDuplicateNotifyBeforeTimeout(t *testing.T) {
+	notifySvc := new(NotifyService)
+	for i := 0; i < 2; i++ {
+		var rsp SendResponse
+		if err := notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp); err != nil {
+			t.Fatalf("Send attempt %d: %v", i+1, err)
+		}
+	}
+
+	done := make(chan error)
+	errCh := make(chan error, 1)
+	go func() { errCh <- waitForPlanDelegateExecution(done, notifySvc) }()
+
+	select {
+	case err := <-errCh:
+		if err == nil {
+			t.Fatal("waitForPlanDelegateExecution returned nil, want duplicate notify error")
+		}
+		if got := err.Error(); !strings.Contains(got, "duplicate notify attempts") {
+			t.Fatalf("error = %q, want duplicate notify attempts", got)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("waitForPlanDelegateExecution did not report duplicate notify before timeout")
+	}
+}
+
 func TestNotifyServiceSendIsIdempotentForDuplicateDelivery(t *testing.T) {
 	svc := new(NotifyService)
 	for i := 0; i < 3; i++ {

internal/harness/universe/main.go

@@ -117,6 +117,16 @@ type Notify struct {
 // Send delivers a notification.
 // @example {"to": "buyer@acme.com", "message": "Your order is confirmed"}
 func (s *Notify) Send(_ context.Context, req *SendRequest, rsp *SendResponse) error {
+	if !isBuyerNotification(req) {
+		to, message := "", ""
+		if req != nil {
+			to, message = req.To, req.Message
+		}
+		fmt.Printf("    \033[35m[notify]\033[0m 📨 ignored non-buyer notification to=%s %q\n", to, message)
+		rsp.Sent = false
+		return nil
+	}
+
 	keys := notificationDedupeKeys(req)
 	s.mu.Lock()
 	if s.seen == nil {
@@ -141,8 +151,41 @@ func (s *Notify) Send(_ context.Context, req *SendRequest, rsp *SendResponse) er
 	return nil
 }
 
+func isBuyerNotification(req *SendRequest) bool {
+	if req == nil {
+		return false
+	}
+	return canonicalBuyerRecipient(req.To) != ""
+}
+
+func canonicalBuyerRecipient(to string) string {
+	recipient := strings.ToLower(strings.TrimSpace(to))
+	switch recipient {
+	case "buyer", "buyer@acme.com":
+		return "buyer@acme.com"
+	}
+	for _, field := range strings.FieldsFunc(recipient, func(r rune) bool {
+		switch r {
+		case ' ', '\t', '\n', '\r', ',', ';', ':', '/', '\\', '(', ')', '[', ']', '{', '}':
+			return true
+		default:
+			return false
+		}
+	}) {
+		switch field {
+		case "buyer", "buyer@acme.com":
+			return "buyer@acme.com"
+		}
+	}
+	return ""
+}
+
 func notificationDedupeKeys(req *SendRequest) []string {
-	keys := []string{req.To + "\x00" + req.Message}
+	recipient := canonicalBuyerRecipient(req.To)
+	if recipient == "" {
+		recipient = strings.TrimSpace(req.To)
+	}
+	keys := []string{recipient + "\x00" + req.Message}
 	message := strings.ToLower(req.Message)
 	if strings.Contains(message, "confirm") {
 		// Live models occasionally emit equivalent confirmation copy more than
@@ -151,7 +194,7 @@ func notificationDedupeKeys(req *SendRequest) []string {
 		// harness has one checkout order, so treat confirmation messages to the
 		// same buyer as the same side effect while preserving exact-message
 		// idempotency for all other notifications.
-		keys = append(keys, req.To+"\x00confirmation")
+		keys = append(keys, recipient+"\x00confirmation")
 	}
 	return keys
 }

internal/harness/universe/main_test.go

@@ -90,3 +90,99 @@ func TestNotifySuppressesEquivalentConfirmationMessages(t *testing.T) {
 		t.Fatalf("equivalent confirmation notifications sent = %d, want 1", got)
 	}
 }
+
+func TestNotifyAcceptsBuyerAlias(t *testing.T) {
+	ntf := new(Notify)
+	ctx := context.Background()
+
+	var rsp SendResponse
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "buyer",
+		Message: "Your order order-1 has been confirmed.",
+	}, &rsp); err != nil {
+		t.Fatalf("send buyer alias notification: %v", err)
+	}
+	if !rsp.Sent {
+		t.Fatal("buyer alias notification did not report sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 1 {
+		t.Fatalf("buyer alias notifications sent = %d, want 1", got)
+	}
+
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "buyer@acme.com",
+		Message: "order-1 confirmed",
+	}, &rsp); err != nil {
+		t.Fatalf("send canonical buyer notification: %v", err)
+	}
+	if !rsp.Sent {
+		t.Fatal("canonical buyer notification did not report sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 1 {
+		t.Fatalf("alias/canonical confirmation notifications sent = %d, want 1", got)
+	}
+}
+
+func TestNotifyIgnoresNonBuyerRecipients(t *testing.T) {
+	ntf := new(Notify)
+	ctx := context.Background()
+
+	var rsp SendResponse
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "order-1",
+		Message: "order-1 confirmed",
+	}, &rsp); err != nil {
+		t.Fatalf("send non-buyer notification: %v", err)
+	}
+	if rsp.Sent {
+		t.Fatal("non-buyer notification reported sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 0 {
+		t.Fatalf("non-buyer notifications sent = %d, want 0", got)
+	}
+
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "buyer@acme.com",
+		Message: "Your order order-1 has been confirmed.",
+	}, &rsp); err != nil {
+		t.Fatalf("send buyer notification: %v", err)
+	}
+	if !rsp.Sent {
+		t.Fatal("buyer notification did not report sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 1 {
+		t.Fatalf("buyer notifications sent = %d, want 1", got)
+	}
+}
+
+func TestNotifyAcceptsOrderScopedBuyerRecipient(t *testing.T) {
+	ntf := new(Notify)
+	ctx := context.Background()
+
+	var rsp SendResponse
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "order-1 buyer",
+		Message: "order-1 confirmed",
+	}, &rsp); err != nil {
+		t.Fatalf("send order-scoped buyer notification: %v", err)
+	}
+	if !rsp.Sent {
+		t.Fatal("order-scoped buyer notification did not report sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 1 {
+		t.Fatalf("order-scoped buyer notifications sent = %d, want 1", got)
+	}
+
+	if err := ntf.Send(ctx, &SendRequest{
+		To:      "non-buyer",
+		Message: "order-1 confirmed",
+	}, &rsp); err != nil {
+		t.Fatalf("send hyphenated non-buyer notification: %v", err)
+	}
+	if rsp.Sent {
+		t.Fatal("hyphenated non-buyer notification reported sent")
+	}
+	if got := atomic.LoadInt64(&ntf.sent); got != 1 {
+		t.Fatalf("notifications sent after hyphenated non-buyer = %d, want 1", got)
+	}
+}

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

@@ -45,6 +45,7 @@ func TestGuidesNavigationLeadsWithDoing(t *testing.T) {
 	nav := readFile(t, filepath.Join(root, "internal", "website", "_data", "navigation.yml"))
 
 	orderedGuides := []string{
+		"/docs/guides/no-secret-first-agent.html",
 		"/docs/guides/your-first-agent.html",
 		"/docs/guides/zero-to-hero.html",
 		"/docs/guides/plan-delegate.html",
@@ -73,6 +74,37 @@ func TestGuidesNavigationLeadsWithDoing(t *testing.T) {
 	}
 }
 
+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{
+		"go run ./examples/support",
+		"go test ./examples/support -run TestRunSupportMockSmoke -count=1",
+		"make harness",
+		"micro agent preflight",
+		"micro run",
+		"micro chat assistant",
+		"micro inspect agent assistant",
+		"go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1",
+		"No-secret first-agent transcript",
+	} {
+		if !strings.Contains(guide, want) {
+			t.Fatalf("no-secret first-agent transcript 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")
+	}
+
+	firstAgent := readFile(t, filepath.Join(root, "internal", "website", "docs", "guides", "your-first-agent.md"))
+	if !strings.Contains(firstAgent, "no-secret-first-agent.html") {
+		t.Fatal("Your First Agent guide does not point to the no-secret transcript")
+	}
+}
+
 func readFile(t *testing.T, name string) string {
 	t.Helper()
 	data, err := os.ReadFile(name)

internal/website/_data/navigation.yml

@@ -5,6 +5,8 @@ core:
     url: /docs/getting-started.html
   - title: AI Integration
     url: /docs/ai-integration.html
+  - title: No-secret First Agent
+    url: /docs/guides/no-secret-first-agent.html
   - title: Your First Agent
     url: /docs/guides/your-first-agent.html
   - title: 0→hero Reference

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

@@ -0,0 +1,94 @@
+---
+layout: default
+---
+
+# No-secret first-agent transcript
+
+This is the fastest first-agent success path when you do not have a provider key
+handy. It starts from the maintained `examples/support` app and uses the
+repository harness that CI already runs: real Go Micro services, registry,
+broker, client, store, agent loop, flow handoff, and guardrail code with only the
+LLM provider mocked.
+
+Use it before the live-provider [Your First Agent](your-first-agent.html)
+walkthrough when you want to see the services → agents → workflows lifecycle run
+end to end with no secrets.
+
+## What this proves
+
+- **Services** expose typed `customers`, `tickets`, and `notify` endpoints.
+- **The `support` agent** discovers those endpoints as tools and uses them to
+  triage a ticket.
+- **The `intake` flow** turns a `ticket.created` event into an agent run.
+- **The approval gate** intercepts the customer email action before the tool
+  executes.
+
+## Transcript
+
+From a fresh clone of the repository:
+
+```sh
+git clone https://github.com/micro/go-micro.git
+cd go-micro
+go run ./examples/support
+```
+
+The default provider is `mock`, so the command does not need `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, or any other secret. A healthy run prints the event, service
+calls, guardrail decision, and final support-agent reply in one terminal:
+
+```text
+> event: events.ticket.created {"id":"ticket-1","customer":"alice@acme.com",...}
+
+    [customers] looked up Alice (pro plan)
+    [tickets]   ticket-1 → priority=high status=in_progress
+    ▣ approval gate notify_NotifyService_Send(alice@acme.com) — approved
+    [notify]    📨 to=alice@acme.com: "Hi Alice — thanks for reaching out..."
+
+support agent: Hi Alice — thanks for reaching out...
+
+✓ ticket triaged and the customer was replied to — triggered by an event
+```
+
+That single run is the no-secret version of the first-agent loop: a service
+capability exists, an agent calls it as a tool, and workflow infrastructure can
+trigger and inspect the work.
+
+## CI-backed check
+
+Run the same deterministic path as a focused test:
+
+```sh
+go test ./examples/support -run TestRunSupportMockSmoke -count=1
+```
+
+For the broader no-secret contract that also checks scaffold, chat/inspect CLI
+boundaries, flow history, deploy dry-run, and mock provider conformance, run:
+
+```sh
+make harness
+```
+
+## Equivalent scaffold → run → chat → inspect path
+
+When you are ready to build the smaller live-agent version yourself, follow
+[Your First Agent](your-first-agent.html). The command shape is the same, but a
+live `micro chat` turn needs a provider key because the model is no longer
+mocked:
+
+```sh
+micro agent preflight
+micro run
+micro chat assistant
+micro inspect agent assistant
+```
+
+CI keeps those CLI boundaries present with:
+
+```sh
+go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1
+```
+
+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/your-first-agent.md

@@ -13,13 +13,13 @@ run on events or schedules.
 
 ## Runnable reference first
 
-If you want to run the lifecycle before copying code, start with the maintained support-desk example from the repository root:
+If you want to run the lifecycle before copying code, start with the [no-secret first-agent transcript](no-secret-first-agent.html) or run the maintained support-desk example from the repository root:
 
 ```sh
 go run ./examples/support
 ```
 
-It uses a deterministic mock model by default, so it needs no provider key, and it exercises the same shape this guide teaches: services become tools, an agent uses them, and a flow can trigger the work. Use this guide when you are ready to build the smaller 0→1 version yourself.
+It uses a deterministic mock model by default, so it needs no provider key, and it exercises the same shape this guide teaches: services become tools, an agent uses them, and a flow can trigger the work. Use the transcript for expected output, then use this guide when you are ready to build the smaller 0→1 version yourself.
 
 ## What you'll build
 
@@ -219,7 +219,7 @@ agent for judgment, tool use, and handoffs when the path is not known up front.
 
 - Read the [0→hero reference path](zero-to-hero.html) for the CI-verified
   lifecycle contract.
-- Run [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) for the no-secret 0→hero support-desk lifecycle.
+- Run the [no-secret first-agent transcript](no-secret-first-agent.html) or [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) for the no-secret support-desk lifecycle.
 - Run [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate)
   to see planning and delegation across agents.
 - Read [Debugging your agent](debugging-agents.html) when a chat turn does not call the tool you expected, loops, refuses a call, loses memory, or fails after a flow handoff.

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: [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: [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
+- [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
 - [CLI & Gateway Guide](guides/cli-gateway.html) - Development vs Production modes
@@ -47,6 +48,7 @@ Otherwise continue to read the docs for more information about the framework.
 ## AI & Agents
 
 - [0→hero Reference](guides/zero-to-hero.html) - Walk scaffold → run → chat → inspect → deploy dry-run with CI-backed commands
+- [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
 - [Building AI-Native Services](guides/ai-native-services.html) - End-to-end tutorial for MCP-enabled services
 - [MCP Security Guide](guides/mcp-security.html) - Auth, scopes, rate limiting, and audit logging

wrapper/x402/x402_settle_test.go

@@ -73,7 +73,7 @@ func TestSettlementFailureChallenges(t *testing.T) {
 	}
 }
 
-// TestPaymentSignatureHeaderAccepted checks the v2 request header is honoured.
+// TestPaymentSignatureHeaderAccepted checks the v2 request header is honored.
 func TestPaymentSignatureHeaderAccepted(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_ = json.NewEncoder(w).Encode(map[string]any{"isValid": true, "success": true, "transaction": "0x1"})
@@ -86,7 +86,7 @@ func TestPaymentSignatureHeaderAccepted(t *testing.T) {
 	rec := httptest.NewRecorder()
 
 	if !cfg.Require(rec, r, "10000", "chat") {
-		t.Fatalf("Require should honour PAYMENT-SIGNATURE; body=%s", rec.Body.String())
+		t.Fatalf("Require should honor PAYMENT-SIGNATURE; body=%s", rec.Body.String())
 	}
 }