Verify first-agent chat wayfinding

.github/loop/PRIORITIES.md

@@ -21,7 +21,8 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Harden agent provider failure resilience** ([#4650](https://github.com/micro/go-micro/issues/4650)) — With scheduled cross-provider conformance closed by #4678 and the first-agent fixture race closed by #4684, the next Now-roadmap reliability seam is making timeouts, cancellation, rate limits, retry/backoff, and inspectable failure metadata predictable through the agent loop. Keep this scoped to existing behavior and tests; surface any breaking API or default changes as human review notes instead of queue work.
+1. **Verify first-agent docs wayfinding against CLI commands** ([#4634](https://github.com/micro/go-micro/issues/4634)) — PR #4632 merged the 0→hero inspect transcript check and #4627 is closed, so the top developer-adoption risk moves from proving transcript output to preventing the on-ramp map from drifting. README, the website docs index, the 0→hero guide, and the v6.3.15 blog all tell one story: install → scaffold/run → provider-free first agent → chat/inspect → workflows. Make that wayfinding CI-verifiable against real CLI commands and maintained examples so a new developer can still walk from 0→1 to 0→hero without provider keys.
+2. **Harden atlascloud plan-delegate plan persistence** ([#4630](https://github.com/micro/go-micro/issues/4630)) — Keep this Next/Now hardening item close behind adoption work: recent AtlasCloud repair fixes reduced provider brittleness, but plan/delegate durability still has a provider-specific persistence seam. Scope it to the existing plan/delegate harness and CI-verifiable behavior so services → agents → workflows remains reliable without broad public-API or architecture changes.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

CHANGELOG.md

@@ -17,30 +17,8 @@ below is kept current between tags and rolled into the next version when it ship
 
 ## [Unreleased]
 
-### Added
-- **First-agent chat/inspect fixture** — the maintained first-agent CLI fixture now covers chat and inspect boundaries together. (`internal/harness/`, `cmd/micro/`)
-- **Zero-to-hero inspect transcript check** — the 0→hero harness now verifies the inspect transcript path stays visible in the lifecycle walkthrough. (`internal/harness/zero-to-hero-ci/`, `internal/website/docs/`)
-
-### Changed
-- **Plan-delegate plan persistence** — plan/delegate runs now persist plan state more defensively across harness scenarios. (`agent/`, `internal/harness/`)
-
-### Fixed
-- **Zero-to-hero fixture output race** — 0→hero fixture output is less race-prone during harness runs. (`internal/harness/zero-to-hero-ci/`)
-
----
-
-## [6.6.0] - July 2026
-
 ### Added
 - **First-agent guide chain contract** — the harness now verifies the install → demo → examples → 0→hero guide chain stays connected for new agent builders. (`internal/harness/`, `internal/website/docs/`)
-- **First-agent docs wayfinding guard** — the local harness now includes a focused no-network check for first-agent and 0→hero docs links. (`Makefile`, `internal/harness/`)
-- **First-agent quickcheck breadcrumbs** — first-agent docs now surface quickcheck wayfinding for install, scaffold, chat, inspect, and recovery paths. (`internal/website/docs/`, `README.md`)
-- **First-agent chat wayfinding verification** — the harness now verifies first-agent chat wayfinding remains discoverable from the public docs route. (`internal/harness/`, `internal/website/docs/`)
-
-### Changed
-- **Universe A2A reachability probe** — the universe harness now exercises A2A reachability more defensively. (`internal/harness/`)
-- **AtlasCloud workspace repair fallback** — AtlasCloud fallback handling now recovers workspace-repair tool calls more reliably. (`ai/atlascloud/`, `agent/`)
-- **AtlasCloud empty-argument tool repair** — AtlasCloud text tool-call repair now handles empty-argument calls more consistently. (`ai/atlascloud/`, `agent/`)
 
 ### Fixed
 - **A2A fallback artifact text** — A2A fallback responses now avoid leaking provider artifact text into agent-visible output. (`gateway/a2a/`, `agent/`)
@@ -48,20 +26,6 @@ below is kept current between tags and rolled into the next version when it ship
 - **Plan-delegate harness cleanup** — plan/delegate harness cleanup is more reliable after conformance runs. (`internal/harness/`)
 - **AtlasCloud spoken notify replays** — AtlasCloud fallback handling now collapses spoken notification replays more consistently. (`ai/atlascloud/`, `agent/`)
 - **Agent-flow onboarding side effects** — onboarding side-effect checks are more stable across the agent-flow harness. (`agent/`, `internal/harness/`)
-- **Plan-delegate plan-only side effects** — plan/delegate recovery now preserves plan-only side effects more reliably. (`agent/`, `internal/harness/`)
-- **Checkpointed tool result recording** — checkpoint resume paths now guard tool-result recording against duplicate or stale writes. (`agent/`)
-- **Agent timeout notification completion** — universe runs now finalize observed notifications more reliably after agent timeouts. (`agent/`, `internal/harness/`)
-- **Completed plan-delegate side effects** — completed plan/delegate side effects are accepted more consistently in recovery paths. (`agent/`, `internal/harness/`)
-- **Agent-flow onboarding notifications** — agent-flow onboarding notification recovery is more reliable across replay scenarios. (`agent/`, `internal/harness/`)
-
-### Documentation
-- **Agent-agnostic mention model** — loop docs now describe the mention-driven agent model without binding it to one coding agent. (`internal/docs/`, `.github/loop/`)
-- **First-agent quickcheck docs** — public docs now surface the first-agent quickcheck path for faster troubleshooting. (`internal/website/docs/`)
-- **Agent resume breadcrumbs** — docs now add clearer resume breadcrumbs for checkpointed agent runs. (`internal/website/docs/`)
-
-### Security
-- **Govulncheck vulnerability gate** — CI now includes a govulncheck gate and wires vulnerability failures into loop triage. (`.github/workflows/`, `cmd/micro/loop/`)
-- **Dependency vulnerability patches** — toolchain and dependency updates patch reachable CVEs across the project. (`go.mod`, `go.sum`)
 
 ---
 

examples/first-agent/README.md

@@ -34,22 +34,5 @@ CI keeps this path runnable with:
 go test ./examples/first-agent
 ```
 
-## Next chat, inspect, and debug breadcrumbs
-
-This example exits after one in-process `assistant.Ask` call so it stays tiny and
-provider-free. When you move from this transcript to a long-running agent, keep
-these commands nearby:
-
-```bash
-micro run
-micro chat assistant --prompt "Summarize my next steps"
-micro inspect agent assistant
-micro agent doctor assistant
-```
-
-Use the [no-secret first-agent guide](../../internal/website/docs/guides/no-secret-first-agent.md)
-to compare this transcript with the CLI demo, then keep the
-[debugging guide](../../internal/website/docs/guides/debugging-agents.md) open for
-preflight, doctor, inspect, and history checks. After that, continue to
-[`examples/support`](../support/) for the full services → agents → workflows
-lifecycle with a flow trigger and an approval gate.
+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_test.go

@@ -20,32 +20,6 @@ func TestRunFirstAgent(t *testing.T) {
 	}
 }
 
-func TestReadmeDocumentsNextBreadcrumbs(t *testing.T) {
-	b, err := os.ReadFile("README.md")
-	if err != nil {
-		t.Fatalf("read README.md: %v", err)
-	}
-	readme := string(b)
-	start := strings.Index(readme, "## Next chat, inspect, and debug breadcrumbs")
-	if start < 0 {
-		t.Fatal("README.md missing next chat, inspect, and debug breadcrumbs section")
-	}
-	section := readme[start:]
-	for _, want := range []string{
-		"micro run",
-		"micro chat assistant --prompt \"Summarize my next steps\"",
-		"micro inspect agent assistant",
-		"micro agent doctor assistant",
-		"no-secret-first-agent.md",
-		"debugging-agents.md",
-		"examples/support",
-	} {
-		if !strings.Contains(section, want) {
-			t.Fatalf("README.md next breadcrumbs missing %q", want)
-		}
-	}
-}
-
 func readExpectedTranscript(t *testing.T) string {
 	t.Helper()
 	b, err := os.ReadFile("README.md")

internal/docs/AGENT_CONFORMANCE.md

@@ -43,20 +43,7 @@ live model credits.
 
 Use `make provider-conformance` when you want the live-provider sweep: providers
 without keys are skipped, and configured providers must satisfy the same harness
-contract. For the exact scheduled command, run:
-
-```sh
-go run ./internal/harness/provider-conformance \
-  -providers anthropic,openai,gemini,groq,minimax,mistral,together,atlascloud \
-  -harnesses agent,universe,agent-flow,plan-delegate,a2a-stream-fallback \
-  -summary-json provider-conformance-summary.json \
-  -summary-markdown provider-conformance-summary.md \
-  -capabilities-markdown provider-capabilities.md
-```
-
-The generated summary records one row for every selected provider/harness pair;
-missing live-provider keys become skipped rows for each harness, while configured
-providers produce pass/fail rows per harness.
+contract.
 
 ## Scheduled CI
 

internal/harness/plan-delegate/main.go

@@ -474,11 +474,10 @@ func runPlanDelegate(provider string) error {
 		agent.Name("conductor"),
 		agent.Address("127.0.0.1:0"),
 		agent.Services("task"),
-		agent.Prompt("You coordinate launch work. Before any task or delegate tool call, you must persist the launch-readiness plan with the built-in plan tool. Then create exactly one Design task, one Build task, and one Ship task, then delegate exactly one readiness notification to the \"comms\" agent. Do not create duplicate tasks and do not send notifications yourself."),
+		agent.Prompt("You coordinate launch work. Plan first, create exactly one Design task, one Build task, and one Ship task, then delegate exactly one readiness notification to the \"comms\" agent. Do not create duplicate tasks and do not send notifications yourself."),
 		agent.Provider(provider), agent.APIKey(apiKey),
 		agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(mem),
 		agent.WithCheckpoint(conductorCheckpoint),
-		agent.WrapTool(requirePersistedPlanBeforeConductorActions(mem)),
 	}
 	conductorOpts = append(conductorOpts, liveAgentOpts...)
 	conductor := agent.New(conductorOpts...)
@@ -532,8 +531,11 @@ func runPlanDelegate(provider string) error {
 		return err
 	}
 
-	if err := requireConductorPlan(context.Background(), mem, conductor); err != nil {
-		return err
+	// Prove plan was persisted to the real store.
+	if recs, _ := store.Scope(mem, "agent", "conductor").Read("plan"); len(recs) > 0 {
+		fmt.Printf("\n\033[1mstored plan (agent/conductor/plan):\033[0m %s\n", string(recs[0].Value))
+	} else {
+		return fmt.Errorf("plan was not persisted")
 	}
 	if taskSvc.count() == 0 || notifySvc.count() != 1 {
 		return fmt.Errorf("unexpected side effects: tasks=%d notify=%d", taskSvc.count(), notifySvc.count())
@@ -543,46 +545,6 @@ func runPlanDelegate(provider string) error {
 	return nil
 }
 
-func requirePersistedPlanBeforeConductorActions(mem store.Store) ai.ToolWrapper {
-	return func(next ai.ToolHandler) ai.ToolHandler {
-		return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
-			if call.Name == "plan" {
-				return next(ctx, call)
-			}
-			if recs, err := store.Scope(mem, "agent", "conductor").Read("plan"); err == nil && len(recs) > 0 {
-				return next(ctx, call)
-			}
-			msg := "persist the launch-readiness plan first by calling the built-in plan tool before task or delegate side effects"
-			return ai.ToolResult{
-				ID:      call.ID,
-				Value:   map[string]string{"error": msg},
-				Content: `{"error":"` + msg + `"}`,
-				Refused: ai.RefusedApproval,
-			}
-		}
-	}
-}
-
-func requireConductorPlan(ctx context.Context, mem store.Store, conductor agent.Agent) error {
-	recs, _ := store.Scope(mem, "agent", "conductor").Read("plan")
-	if len(recs) == 0 && conductor != nil {
-		fmt.Print("\n\033[33mwarning:\033[0m conductor completed side effects without a persisted plan; retrying plan persistence once before final assertions.\n")
-		_, err := conductor.Ask(ctx, "Persist the launch-readiness plan now using the built-in plan tool before answering. Record exactly these completed steps: Design launch task, Build launch task, Ship launch task, and delegate owner readiness notification to comms. Do not call task or notify tools.")
-		if err != nil {
-			return fmt.Errorf("plan was not persisted at agent/conductor/plan and recovery prompt failed after completed side effects: %w", err)
-		}
-		recs, _ = store.Scope(mem, "agent", "conductor").Read("plan")
-	}
-	if len(recs) == 0 {
-		return fmt.Errorf("plan was not persisted at agent/conductor/plan; conductor completed task/notify side effects without calling the built-in plan tool")
-	}
-	if len(recs) != 1 {
-		return fmt.Errorf("unexpected persisted conductor plans at agent/conductor/plan: got %d records, want 1", len(recs))
-	}
-	fmt.Printf("\n\033[1mstored plan (agent/conductor/plan):\033[0m %s\n", string(recs[0].Value))
-	return nil
-}
-
 func planDelegateConductorStep(conductor agent.Agent, taskSvc *TaskService, notifySvc *NotifyService) 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()

internal/harness/plan-delegate/main_test.go

@@ -3,7 +3,6 @@ package main
 import (
 	"context"
 	"errors"
-	"reflect"
 	"strings"
 	"testing"
 	"time"
@@ -402,88 +401,6 @@ func (a failingAgent) Run() error                                           { re
 func (a failingAgent) Stop() error                                          { return nil }
 func (a failingAgent) String() string                                       { return "failing" }
 
-func TestRequireConductorPlanRecoversAfterCompletedSideEffects(t *testing.T) {
-	mem := store.NewMemoryStore()
-	ag := &scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){
-		func(ctx context.Context, prompt string) (*agent.Response, error) {
-			if !strings.Contains(prompt, "built-in plan tool") || !strings.Contains(prompt, "Do not call task or notify tools") {
-				return nil, errors.New("missing scoped plan recovery prompt")
-			}
-			if err := store.Scope(mem, "agent", "conductor").Write(&store.Record{Key: "plan", Value: []byte(`{"steps":[{"task":"Design launch task","status":"done"}]}`)}); err != nil {
-				return nil, err
-			}
-			return &agent.Response{Reply: "Plan persisted."}, nil
-		},
-	}}
-
-	if err := requireConductorPlan(context.Background(), mem, ag); err != nil {
-		t.Fatalf("requireConductorPlan returned %v, want recovered plan", err)
-	}
-	if ag.calls != 1 {
-		t.Fatalf("conductor calls = %d, want one plan recovery prompt", ag.calls)
-	}
-}
-
-func TestRequireConductorPlanFailureNamesScopedRecord(t *testing.T) {
-	err := requireConductorPlan(context.Background(), store.NewMemoryStore(), &scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){
-		func(context.Context, string) (*agent.Response, error) {
-			return &agent.Response{Reply: "Done without plan."}, nil
-		},
-	}})
-	if err == nil {
-		t.Fatal("requireConductorPlan returned nil, want missing plan diagnostic")
-	}
-	for _, want := range []string{"agent/conductor/plan", "without calling the built-in plan tool"} {
-		if got := err.Error(); !strings.Contains(got, want) {
-			t.Fatalf("error = %q, want %q", got, want)
-		}
-	}
-}
-
-func TestRequirePersistedPlanBeforeConductorActionsBlocksSideEffects(t *testing.T) {
-	mem := store.NewMemoryStore()
-	called := false
-	wrapped := requirePersistedPlanBeforeConductorActions(mem)(func(context.Context, ai.ToolCall) ai.ToolResult {
-		called = true
-		return ai.ToolResult{ID: "call-1", Content: `{"ok":true}`}
-	})
-
-	res := wrapped(context.Background(), ai.ToolCall{ID: "call-1", Name: "task.Add"})
-	if called {
-		t.Fatal("side-effecting tool ran before persisted plan")
-	}
-	if res.Refused != ai.RefusedApproval {
-		t.Fatalf("Refused = %q, want %q", res.Refused, ai.RefusedApproval)
-	}
-	if !strings.Contains(res.Content, "built-in plan tool") {
-		t.Fatalf("Content = %q, want plan-first steering message", res.Content)
-	}
-}
-
-func TestRequirePersistedPlanBeforeConductorActionsAllowsPlanAndPlannedActions(t *testing.T) {
-	mem := store.NewMemoryStore()
-	var calls []string
-	wrapped := requirePersistedPlanBeforeConductorActions(mem)(func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
-		calls = append(calls, call.Name)
-		if call.Name == "plan" {
-			if err := store.Scope(mem, "agent", "conductor").Write(&store.Record{Key: "plan", Value: []byte(`{"steps":[{"task":"Design","status":"pending"}]}`)}); err != nil {
-				t.Fatalf("write plan: %v", err)
-			}
-		}
-		return ai.ToolResult{ID: call.ID, Content: `{"ok":true}`}
-	})
-
-	if res := wrapped(context.Background(), ai.ToolCall{ID: "call-1", Name: "plan"}); res.Refused != "" {
-		t.Fatalf("plan Refused = %q, want allowed", res.Refused)
-	}
-	if res := wrapped(context.Background(), ai.ToolCall{ID: "call-2", Name: "task.Add"}); res.Refused != "" {
-		t.Fatalf("planned action Refused = %q, want allowed", res.Refused)
-	}
-	if want := []string{"plan", "task.Add"}; !reflect.DeepEqual(calls, want) {
-		t.Fatalf("calls = %v, want %v", calls, want)
-	}
-}
-
 func TestPlanDelegateConductorRetriesAfterPlanOnlySuccess(t *testing.T) {
 	taskSvc := new(TaskService)
 	notifySvc := new(NotifyService)

internal/harness/provider-conformance/main.go

@@ -92,11 +92,11 @@ func main() {
 			if *requireConfiguredFlag {
 				fmt.Printf("FAIL %s: missing API key (%s)\n", provider, msg)
 				failed++
-				results = append(results, missingKeyResults(provider, harnesses, statusFailed, "missing API key: "+msg)...)
+				results = append(results, conformanceResult{Provider: provider, Status: statusFailed, Error: "missing API key: " + msg})
 			} else {
 				fmt.Printf("- %s: skipped (%s)\n", provider, msg)
 				skipped++
-				results = append(results, missingKeyResults(provider, harnesses, statusSkipped, msg)...)
+				results = append(results, conformanceResult{Provider: provider, Status: statusSkipped, Error: msg})
 			}
 			continue
 		}
@@ -166,20 +166,6 @@ type conformanceSummary struct {
 	Failed       int                 `json:"failed"`
 }
 
-func missingKeyResults(provider string, harnesses []string, status, detail string) []conformanceResult {
-	results := make([]conformanceResult, 0, len(harnesses))
-	for _, harness := range harnesses {
-		results = append(results, conformanceResult{
-			Provider: provider,
-			Harness:  harness,
-			Phase:    harnessPhase(harness),
-			Status:   status,
-			Error:    detail,
-		})
-	}
-	return results
-}
-
 func writeSummaryJSON(path string, summary conformanceSummary) error {
 	b, err := json.MarshalIndent(summary, "", "  ")
 	if err != nil {

internal/harness/provider-conformance/main_test.go

@@ -77,23 +77,6 @@ func TestCapabilityMatrixHasRegisteredProviders(t *testing.T) {
 	}
 }
 
-func TestMissingKeyResultsReportsEachHarness(t *testing.T) {
-	results := missingKeyResults("openai", []string{"agent", "plan-delegate"}, statusSkipped, "set OPENAI_API_KEY")
-	if len(results) != 2 {
-		t.Fatalf("missingKeyResults returned %d results, want 2", len(results))
-	}
-
-	wants := []conformanceResult{
-		{Provider: "openai", Harness: "agent", Phase: harnessPhase("agent"), Status: statusSkipped, Error: "set OPENAI_API_KEY"},
-		{Provider: "openai", Harness: "plan-delegate", Phase: harnessPhase("plan-delegate"), Status: statusSkipped, Error: "set OPENAI_API_KEY"},
-	}
-	for i, want := range wants {
-		if results[i] != want {
-			t.Fatalf("result[%d] = %#v, want %#v", i, results[i], want)
-		}
-	}
-}
-
 func TestWriteCapabilityMarkdown(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "capabilities.md")
 	rows := []ai.CapabilityRow{

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

@@ -7,7 +7,6 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
-	"sync"
 	"testing"
 	"time"
 
@@ -1005,190 +1004,6 @@ func TestNoSecretFirstAgentDebuggingSmoke(t *testing.T) {
 	}
 }
 
-func TestFirstAgentCLIChatInspectFixture(t *testing.T) {
-	root := filepath.Clean(filepath.Join("..", "..", ".."))
-	absRoot, err := filepath.Abs(root)
-	if err != nil {
-		t.Fatalf("resolve repository root: %v", err)
-	}
-
-	workspace := t.TempDir()
-	home := filepath.Join(workspace, "home")
-	if err := os.MkdirAll(home, 0o755); err != nil {
-		t.Fatalf("create fixture home: %v", err)
-	}
-	writeFile(t, filepath.Join(workspace, "go.mod"), "module example.com/first-agent-cli-fixture\n\ngo 1.24\n\nrequire go-micro.dev/v6 v6.0.0\n\nreplace go-micro.dev/v6 => "+filepath.ToSlash(absRoot)+"\n")
-	writeFile(t, filepath.Join(workspace, "main.go"), firstAgentCLIFixtureSource())
-	runInWorkspace(t, workspace, "go", "mod", "tidy")
-
-	micro := buildMicroBinary(t, absRoot)
-	fixtureBin := filepath.Join(workspace, "first-agent-cli-fixture")
-	runInWorkspace(t, workspace, "go", "build", "-o", fixtureBin, ".")
-	fixture := exec.Command(fixtureBin)
-	fixture.Dir = workspace
-	fixture.Env = append(os.Environ(),
-		"HOME="+home,
-		"MICRO_AI_API_KEY=",
-		"OPENAI_API_KEY=",
-		"ANTHROPIC_API_KEY=",
-		"GEMINI_API_KEY=",
-	)
-	var fixtureOut lockedBuffer
-	fixture.Stdout = &fixtureOut
-	fixture.Stderr = &fixtureOut
-	if err := fixture.Start(); err != nil {
-		t.Fatalf("start first-agent CLI fixture: %v\n%s", err, fixtureOut.String())
-	}
-	defer func() {
-		if fixture.Process != nil {
-			_ = fixture.Process.Signal(os.Interrupt)
-			_ = fixture.Process.Kill()
-		}
-	}()
-
-	waitForCLIOutput(t, &fixtureOut, "first-agent fixture ready", 15*time.Second)
-	waitForRegisteredAgent(t, micro, home, "assistant", &fixtureOut, 15*time.Second)
-
-	chat := runMicroCLIWithHome(t, micro, home, "chat", "--prompt", "Summarize my first-agent next steps", "assistant")
-	for _, want := range []string{"assistant:", "install the CLI", "run a service", "chat with an agent"} {
-		if !strings.Contains(chat, want) {
-			t.Fatalf("micro chat assistant output missing %q:\n%s\nfixture output:\n%s", want, chat, fixtureOut.String())
-		}
-	}
-
-	stopFixture(t, fixture)
-
-	inspect := runMicroCLIWithHome(t, micro, home, "inspect", "agent", "assistant", "--limit", "1")
-	for _, want := range []string{`Agent "assistant" runs`, "status=done", "last=done"} {
-		if !strings.Contains(inspect, want) {
-			t.Fatalf("micro inspect agent assistant output missing %q:\n%s\nfixture output:\n%s", want, inspect, fixtureOut.String())
-		}
-	}
-}
-
-func stopFixture(t *testing.T, cmd *exec.Cmd) {
-	t.Helper()
-	if cmd.Process == nil {
-		return
-	}
-	done := make(chan error, 1)
-	_ = cmd.Process.Signal(os.Interrupt)
-	go func() { done <- cmd.Wait() }()
-	select {
-	case <-done:
-	case <-time.After(2 * time.Second):
-		_ = cmd.Process.Kill()
-		<-done
-	}
-}
-
-func waitForCLIOutput(t *testing.T, out *lockedBuffer, want string, timeout time.Duration) {
-	t.Helper()
-	deadline := time.Now().Add(timeout)
-	for time.Now().Before(deadline) {
-		if strings.Contains(out.String(), want) {
-			return
-		}
-		time.Sleep(100 * time.Millisecond)
-	}
-	t.Fatalf("timed out waiting for fixture output %q; got:\n%s", want, out.String())
-}
-
-func waitForRegisteredAgent(t *testing.T, micro, home, agent string, fixtureOut *lockedBuffer, timeout time.Duration) {
-	t.Helper()
-	deadline := time.Now().Add(timeout)
-	var lastOut []byte
-	var lastErr error
-	for time.Now().Before(deadline) {
-		cmd := exec.Command(micro, "agent", "list")
-		cmd.Env = microCLIEnv(home)
-		lastOut, lastErr = cmd.CombinedOutput()
-		if lastErr == nil && strings.Contains(string(lastOut), agent) {
-			return
-		}
-		time.Sleep(100 * time.Millisecond)
-	}
-	t.Fatalf("timed out waiting for registered agent %q; last micro agent list error: %v\nlast output:\n%s\nfixture output:\n%s", agent, lastErr, lastOut, fixtureOut.String())
-}
-
-type lockedBuffer struct {
-	mu sync.Mutex
-	b  strings.Builder
-}
-
-func (b *lockedBuffer) Write(p []byte) (int, error) {
-	b.mu.Lock()
-	defer b.mu.Unlock()
-	return b.b.Write(p)
-}
-
-func (b *lockedBuffer) String() string {
-	b.mu.Lock()
-	defer b.mu.Unlock()
-	return b.b.String()
-}
-
-func firstAgentCLIFixtureSource() string {
-	return `package main
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"os/signal"
-	"path/filepath"
-	"strings"
-	"syscall"
-
-	"go-micro.dev/v6/agent"
-	"go-micro.dev/v6/ai"
-	"go-micro.dev/v6/service"
-	"go-micro.dev/v6/store"
-)
-
-type NotesService struct{}
-type ListNotesRequest struct{}
-type ListNotesResponse struct { Notes []string ` + "`json:\"notes\" description:\"Notes the assistant can summarize\"`" + ` }
-
-func (s *NotesService) List(ctx context.Context, req *ListNotesRequest, rsp *ListNotesResponse) error {
-	rsp.Notes = []string{"Install the CLI", "Run a service", "Chat with an agent"}
-	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-cli-fixture" }
-func (m *mockModel) Stream(context.Context, *ai.Request, ...ai.GenerateOption) (ai.Stream, error) { return nil, fmt.Errorf("stream unsupported") }
-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: "assistant: your first agent should install the CLI, run a service, then chat with an agent."}, nil
-}
-
-func main() {
-	ai.Register("first-agent-cli-fixture", newMock)
-	home, _ := os.UserHomeDir()
-	st := store.NewFileStore(store.DirOption(filepath.Join(home, "micro", "store")))
-	defer st.Close()
-
-	svc := service.New(service.Name("notes"), service.Address("127.0.0.1:0"))
-	if err := svc.Handle(&NotesService{}); err != nil { panic(err) }
-	go func() { if err := svc.Run(); err != nil { fmt.Println(err); os.Exit(1) } }()
-	defer svc.Server().Stop()
-
-	a := agent.New(agent.Name("assistant"), agent.Address("127.0.0.1:0"), agent.Services("notes"), agent.Provider("first-agent-cli-fixture"), agent.WithStore(st))
-	go func() { if err := a.Run(); err != nil { fmt.Println(err); os.Exit(1) } }()
-	defer a.Stop()
-
-	fmt.Println("first-agent fixture ready")
-	stop := make(chan os.Signal, 1)
-	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
-	<-stop
-}
-`
-}
-
 func seedNoSecretAgentDebuggingState(t *testing.T, st store.Store) {
 	t.Helper()
 	scoped := store.Scope(st, "agent", "assistant")
@@ -1229,22 +1044,18 @@ func buildMicroBinary(t *testing.T, root string) string {
 func runMicroCLIWithHome(t *testing.T, micro, home string, args ...string) string {
 	t.Helper()
 	cmd := exec.Command(micro, args...)
-	cmd.Env = microCLIEnv(home)
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		t.Fatalf("micro %s failed: %v\n%s", strings.Join(args, " "), err, out)
-	}
-	return string(out)
-}
-
-func microCLIEnv(home string) []string {
-	return append(os.Environ(),
+	cmd.Env = append(os.Environ(),
 		"HOME="+home,
 		"MICRO_AI_API_KEY=",
 		"OPENAI_API_KEY=",
 		"ANTHROPIC_API_KEY=",
 		"GEMINI_API_KEY=",
 	)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("micro %s failed: %v\n%s", strings.Join(args, " "), err, out)
+	}
+	return string(out)
 }
 
 func TestFirstAgentWayfindingTargetsExist(t *testing.T) {

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

@@ -25,7 +25,7 @@ run_step "run/chat/inspect: first-agent CLI boundaries" \
 run_step "deploy dry-run: configured target plan" \
   go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1
 run_step "chat/inspect: no-secret first-agent transcript and docs" \
-  go test ./internal/harness/zero-to-hero-ci -run 'TestNoSecretFirstAgentTranscript|TestFirstAgentCLIChatInspectFixture|TestNoSecretFirstAgentDebuggingSmoke|TestZeroToHeroReferenceDocs|TestZeroToHeroDeployDryRunCommandSmoke|TestYourFirstAgentTutorialSmoke' -count=1
+  go test ./internal/harness/zero-to-hero-ci -run 'TestNoSecretFirstAgentTranscript|TestNoSecretFirstAgentDebuggingSmoke|TestZeroToHeroReferenceDocs|TestZeroToHeroDeployDryRunCommandSmoke|TestYourFirstAgentTutorialSmoke' -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

internal/website/docs/architecture.md

@@ -104,25 +104,16 @@ If you are new, follow the architecture in the same order the runtime composes i
    CLI, `PATH`, version, and no-secret smoke path are healthy.
 2. [`micro agent demo`](getting-started.html#first-agent-on-ramp) — print the
    provider-free first-agent command and next docs steps from the installed CLI.
-3. `micro agent quickcheck` (or `micro agent debug`) — print the short recovery
-   map when scaffold → run → chat → inspect stalls.
-4. `micro examples` — list the maintained provider-free runnable examples in
-   copy/paste order.
-5. `micro zero-to-hero` — print the maintained one-command no-secret lifecycle
-   harness and runnable examples.
-6. [Examples wayfinding index](https://github.com/micro/go-micro/blob/master/examples/INDEX.md)
-   — choose the smallest no-secret first-agent, support reference, and interop
-   examples from one map.
-7. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)
+3. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)
    — run one service-backed agent with a mock model.
-8. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — see the
+4. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — see the
    maintained support-agent path work without a provider key.
-9. [Your First Agent](guides/your-first-agent.html) — build and chat with a
+5. [Your First Agent](guides/your-first-agent.html) — build and chat with a
    service-backed agent.
-10. [Debugging your agent](guides/debugging-agents.html) — inspect service
-    registration, tools, memory, providers, and run history.
-11. [0→hero Reference](guides/zero-to-hero.html) — walk scaffold → run → chat →
-    inspect → flow → deploy dry-run as the maintained lifecycle contract.
+6. [Debugging your agent](guides/debugging-agents.html) — inspect service
+   registration, tools, memory, providers, and run history.
+7. [0→hero Reference](guides/zero-to-hero.html) — walk scaffold → run → chat →
+   inspect → flow → deploy dry-run as the maintained lifecycle contract.
 
 ## Related