docs: refresh planner priorities for 4103

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

.github/loop/PRIORITIES.md

@@ -21,7 +21,8 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Lead Getting Started with the no-secret first-run path** ([#4054](https://github.com/micro/go-micro/issues/4054)) — #4039 added `micro agent demo`, #4044 documented it in the README/website on-ramp, #4049 moved the installed CLI docs to lead with it, and #4052 surfaced it from scaffold next steps. The remaining adoption seam is the website Getting Started page: it still introduces provider-key setup and prompt generation before the no-secret scaffold → run → call path, so a new developer can infer an LLM key is mandatory before they have proved the runtime works. Reorder Getting Started to lead with install → `micro new` → `micro run` → curl, then `micro agent demo` and the no-secret first-agent sequence, and add a focused docs/harness assertion so the README, CLI docs, and website cannot drift apart again.
+1. **Make plan-delegate notification side effects idempotent** ([#4100](https://github.com/micro/go-micro/issues/4100)) — the latest live provider-conformance run exposed a duplicate delegated notify call in the plan-delegate harness. Fixing this protects the green-CI evaluator and the services → agents → workflows contract: model retries or repeated tool attempts must not create duplicate real side effects. Keep the patch narrow around the harness/service boundary and add a deterministic replay test before relying on the next live atlascloud run.
+2. **Unify first-agent run inspection command across CLI and docs** ([#4104](https://github.com/micro/go-micro/issues/4104)) — the install, first-agent, debugging, and 0→hero on-ramp is now rich enough that command-name drift becomes the next adoption seam. Make the documented inspect step copy/pasteable from the CLI and website, either by adding the intended alias or aligning docs on the existing command, and guard the CLI/docs boundary with focused tests.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

README.md

@@ -50,6 +50,8 @@ curl -fsSL https://go-micro.dev/install.sh | sh
 go install go-micro.dev/v6/cmd/micro@latest
 ```
 
+If install or `PATH` checks fail, use the [install troubleshooting guide](internal/website/docs/guides/install-troubleshooting.md) before scaffolding your first service.
+
 ### Fastest start — no API key
 
 Scaffold a service, run it, call it:
@@ -87,16 +89,18 @@ make harness
 After install and the first `micro new`/`micro run` smoke check, take the
 walkable agent path in this order:
 
-1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
-2. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
-3. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
+1. [Install troubleshooting](internal/website/docs/guides/install-troubleshooting.md) — verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path before agent work.
+2. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
+3. `micro zero-to-hero` — print the maintained one-command no-secret lifecycle harness and runnable examples.
+4. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
+5. [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.
-4. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
+6. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
    service-backed agent and talk to it with `micro chat`.
-5. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
+7. [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.
-6. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
+8. [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.
 

cmd/micro/README.md

@@ -52,6 +52,25 @@ This starts:
 
 Open http://localhost:8080 to see your services and call them from the browser.
 
+Call the generated service from another terminal:
+
+```
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
+```
+
+## First agent on-ramp
+
+Once the scaffold → run → call path works, ask the installed CLI for the
+provider-free agent path:
+
+```
+micro agent demo
+```
+
+That points at the smallest mock-model first-agent example and the no-secret
+transcript before you add provider-backed chat.
+
 ### Output
 
 ```

cmd/micro/cli/agent/agent.go

@@ -33,9 +33,10 @@ After it passes:
   - Walk the full 0→hero lifecycle:    https://go-micro.dev/docs/guides/zero-to-hero.html
 
 Use live-provider chat when you are ready for real model behavior:
-  micro agent preflight
+  micro agent preflight  # before micro run: prerequisites
   micro run
   micro chat
+  micro agent doctor     # after micro run: chat/gateway/inspect recovery
   micro inspect agent <name>`
 
 func init() {
@@ -80,7 +81,7 @@ for live-provider chat and inspect/debugging.`,
 			},
 			{
 				Name:  "doctor",
-				Usage: "Diagnose chat and inspect recovery after micro run",
+				Usage: "Diagnose chat, gateway, registration, provider, and inspect recovery after micro run",
 				Flags: []cli.Flag{
 					&cli.StringFlag{Name: "gateway", Value: "http://localhost:8080", Usage: "Gateway URL started by micro run"},
 				},

cmd/micro/cli/cli.go

@@ -24,6 +24,28 @@ import (
 	_ "go-micro.dev/v6/cmd/micro/cli/remote"
 )
 
+const zeroToHeroHelp = `0→hero no-secret lifecycle demo
+
+Run this from a go-micro repository checkout when you want one command that
+proves the maintained services → agents → workflows path without provider keys:
+
+  ./internal/harness/zero-to-hero-ci/run.sh
+
+That script runs the same deterministic path CI uses:
+  - CLI discovery for scaffold, run, chat, inspect, flow runs, and deploy dry-run
+  - the smallest first-agent example
+  - the support-desk reference app with services, an agent, a flow, and an approval gate
+  - plan/delegate and universe harnesses with only the model mocked
+
+If you only want the runnable examples first:
+  go run ./examples/first-agent
+  go run ./examples/support
+
+Full local contract:
+  make harness
+
+Guide: https://go-micro.dev/docs/guides/zero-to-hero.html`
+
 const docsWayfinding = `First-agent and 0→hero docs:
 
   1. Start with the no-secret CLI demo
@@ -40,10 +62,10 @@ const docsWayfinding = `First-agent and 0→hero docs:
   3. Your First Agent
      https://go-micro.dev/docs/guides/your-first-agent.html
      Build a service-backed agent, then use:
-       micro agent preflight
+       micro agent preflight  # before micro run: prerequisites
        micro run
        micro chat
-       micro agent doctor
+       micro agent doctor     # after micro run: chat/gateway/inspect recovery
 
   4. Debugging your agent
      https://go-micro.dev/docs/guides/debugging-agents.html
@@ -128,6 +150,17 @@ func init() {
 				return nil
 			},
 		},
+		{
+			Name:  "zero-to-hero",
+			Usage: "Show the no-secret 0→hero lifecycle demo command",
+			Description: `Print the maintained provider-free services → agents → workflows
+lifecycle command and the smaller runnable examples it covers.`,
+			Aliases: []string{"hero"},
+			Action: func(ctx *cli.Context) error {
+				fmt.Fprintln(ctx.App.Writer, zeroToHeroHelp)
+				return nil
+			},
+		},
 		{
 			Name:  "docs",
 			Usage: "Show the first-agent and 0→hero documentation path",

cmd/micro/first_agent_walkthrough_test.go

@@ -64,10 +64,10 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 		"your-first-agent.html",
 		"debugging-agents.html",
 		"zero-to-hero.html",
-		"micro agent preflight",
+		"micro agent preflight  # before micro run: prerequisites",
 		"micro run",
 		"micro chat",
-		"micro agent doctor",
+		"micro agent doctor     # after micro run: chat/gateway/inspect recovery",
 		"micro inspect agent",
 	} {
 		if !strings.Contains(out.String(), want) {
@@ -79,6 +79,13 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 	if !strings.Contains(agent.Usage, "micro agent demo") {
 		t.Fatalf("micro agent help should advertise the no-secret demo; usage was %q", agent.Usage)
 	}
+	doctor := subcommandByName(t, agent, "doctor")
+	for _, want := range []string{"chat", "gateway", "registration", "provider", "inspect", "after micro run"} {
+		if !strings.Contains(doctor.Usage, want) {
+			t.Fatalf("micro agent doctor usage should advertise after-run recovery for %q; usage was %q", want, doctor.Usage)
+		}
+	}
+
 	demo := subcommandByName(t, agent, "demo")
 	out.Reset()
 	if err := demo.Action(cli.NewContext(app, nil, nil)); err != nil {
@@ -88,8 +95,9 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
 		"No-secret first-agent demo",
 		"go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1",
 		"provider-free",
-		"micro agent preflight",
+		"micro agent preflight  # before micro run: prerequisites",
 		"micro chat",
+		"micro agent doctor     # after micro run: chat/gateway/inspect recovery",
 		"micro inspect agent <name>",
 		"your-first-agent.html",
 		"debugging-agents.html",

cmd/micro/zero_to_hero_cli_test.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"bytes"
+	"strings"
 	"testing"
 
 	microcmd "go-micro.dev/v6/cmd"
@@ -19,7 +21,7 @@ func TestZeroToHeroCLIBoundaries(t *testing.T) {
 		}
 	}
 
-	for _, want := range []string{"run", "chat", "flow", "inspect", "deploy"} {
+	for _, want := range []string{"run", "chat", "flow", "inspect", "deploy", "zero-to-hero"} {
 		if !commands[want] {
 			t.Fatalf("missing %q command", want)
 		}
@@ -48,3 +50,29 @@ func TestZeroToHeroCLIBoundaries(t *testing.T) {
 		t.Fatal("missing deploy boundary: deploy --dry-run")
 	}
 }
+
+func TestZeroToHeroCommandPrintsMaintainedNoSecretPath(t *testing.T) {
+	app := microcmd.DefaultCmd.App()
+	var out bytes.Buffer
+	oldWriter := app.Writer
+	app.Writer = &out
+	t.Cleanup(func() { app.Writer = oldWriter })
+
+	if err := app.Run([]string{"micro", "zero-to-hero"}); err != nil {
+		t.Fatalf("micro zero-to-hero failed: %v", err)
+	}
+
+	got := out.String()
+	for _, want := range []string{
+		"0→hero no-secret lifecycle demo",
+		"./internal/harness/zero-to-hero-ci/run.sh",
+		"go run ./examples/first-agent",
+		"go run ./examples/support",
+		"make harness",
+		"services → agents → workflows",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("micro zero-to-hero output missing %q:\n%s", want, got)
+		}
+	}
+}

config/default.go

@@ -14,8 +14,10 @@ import (
 
 type config struct {
 	// the current values
-	vals reader.Values
-	exit chan bool
+	vals    reader.Values
+	exit    chan bool
+	closeMu sync.Mutex
+	closed  bool
 	// the current snapshot
 	snap *loader.Snapshot
 	opts Options
@@ -48,6 +50,9 @@ func (c *config) Init(opts ...Option) error {
 		Reader: json.NewReader(),
 	}
 	c.exit = make(chan bool)
+	c.closeMu.Lock()
+	c.closed = false
+	c.closeMu.Unlock()
 	for _, o := range opts {
 		o(&c.opts)
 	}
@@ -184,12 +189,15 @@ func (c *config) Sync() error {
 }
 
 func (c *config) Close() error {
-	select {
-	case <-c.exit:
+	c.closeMu.Lock()
+	defer c.closeMu.Unlock()
+
+	if c.closed {
 		return nil
-	default:
-		close(c.exit)
 	}
+
+	close(c.exit)
+	c.closed = true
 	return nil
 }
 

config/default_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -45,6 +46,30 @@ func createFileForTest(t *testing.T) *os.File {
 	return fh
 }
 
+func TestConfigCloseConcurrentIdempotent(t *testing.T) {
+	conf, err := NewConfig(WithWatcherDisabled())
+	if err != nil {
+		t.Fatalf("Expected no error but got %v", err)
+	}
+
+	const goroutines = 64
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func() {
+			defer wg.Done()
+			if err := conf.Close(); err != nil {
+				t.Errorf("Expected close to be idempotent but got %v", err)
+			}
+		}()
+	}
+	wg.Wait()
+
+	if err := conf.Close(); err != nil {
+		t.Fatalf("Expected repeated close to be idempotent but got %v", err)
+	}
+}
+
 func TestConfigLoadWithGoodFile(t *testing.T) {
 	fh := createFileForTest(t)
 	path := fh.Name()

config/loader/memory/memory.go

@@ -18,8 +18,10 @@ import (
 
 type memory struct {
 	// the current values
-	vals reader.Values
-	exit chan bool
+	vals    reader.Values
+	exit    chan bool
+	closeMu sync.Mutex
+	closed  bool
 	// the current snapshot
 	snap *loader.Snapshot
 
@@ -270,12 +272,15 @@ func (m *memory) Sync() error {
 }
 
 func (m *memory) Close() error {
-	select {
-	case <-m.exit:
+	m.closeMu.Lock()
+	defer m.closeMu.Unlock()
+
+	if m.closed {
 		return nil
-	default:
-		close(m.exit)
 	}
+
+	close(m.exit)
+	m.closed = true
 	return nil
 }
 

examples/README.md

@@ -12,9 +12,11 @@ of reading the directories alphabetically.
 
 ## Recommended first-agent path
 
+This path is the canonical services → agents → workflows route through the examples map. Debugging and observability wayfinding stays nearby once the first run works.
+
 | 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. |
+| 1. First service | [`hello-world`](./hello-world/) | Build the 0→1 service path: 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 | [`first-agent`](./first-agent/) | Run the smallest service-backed agent with a deterministic mock model and no provider key. | Compare with [`agent-demo`](./agent-demo/) or the maintained 0-to-hero path in [`support`](./support/). |
 | 3. First workflow | [`support`](./support/) | Follow typed services into an agent chat loop, an event-driven `intake` flow, and an approval gate in one runnable reference. | Deepen the workflow model with [`flow-durable`](./flow-durable/). |
 

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

@@ -3,6 +3,7 @@ package zerotoheroci
 import (
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"testing"
 )
@@ -20,6 +21,7 @@ func TestZeroToHeroReferenceDocs(t *testing.T) {
 		"go test ./examples/first-agent -run TestRunFirstAgent -count=1",
 		"go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1",
 		"./internal/harness/zero-to-hero-ci/run.sh",
+		"micro zero-to-hero",
 		"go run ./internal/harness/agent-flow",
 		"make provider-conformance-mock",
 		"internal/harness/plan-delegate",
@@ -75,6 +77,41 @@ func TestGuidesNavigationLeadsWithDoing(t *testing.T) {
 	}
 }
 
+func TestArchitectureDocsAlignWithAgentHarnessLifecycle(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	doc := readFile(t, filepath.Join(root, "internal", "website", "docs", "architecture.md"))
+
+	for _, want := range []string{
+		"services → agents → workflows lifecycle",
+		"## Service substrate",
+		"## Agent harness",
+		"## Workflows",
+		"## Interop gateways",
+		"`model` / `ai.Model`",
+		"`store` / memory",
+		"`ai.Tools`",
+		"`agent`",
+		"`flow`",
+		"`micro mcp`",
+		"`micro a2a`",
+		"[AI Integration](ai-integration.html)",
+		"[Your First Agent](guides/your-first-agent.html)",
+		"[0→hero Reference](guides/zero-to-hero.html)",
+	} {
+		if !strings.Contains(doc, want) {
+			t.Fatalf("architecture doc missing lifecycle marker %q", want)
+		}
+	}
+
+	assertOrderedMarkers(t, "architecture lifecycle", doc, []string{
+		"## Service substrate",
+		"## Agent harness",
+		"## Workflows",
+		"## Interop gateways",
+		"## Developer path",
+	})
+}
+
 func TestFirstAgentWayfindingDocs(t *testing.T) {
 	root := filepath.Clean(filepath.Join("..", "..", ".."))
 	checks := []struct {
@@ -88,7 +125,9 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
 			file:    filepath.Join(root, "README.md"),
 			heading: "### First agent on-ramp",
 			links: []string{
+				"internal/website/docs/guides/install-troubleshooting.md",
 				"micro agent demo",
+				"micro zero-to-hero",
 				"internal/website/docs/guides/no-secret-first-agent.md",
 				"internal/website/docs/guides/your-first-agent.md",
 				"internal/website/docs/guides/debugging-agents.md",
@@ -130,7 +169,9 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
 			file:    filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
 			heading: "### First-agent on-ramp",
 			links: []string{
+				"guides/install-troubleshooting.html",
 				"micro agent demo",
+				"micro zero-to-hero",
 				"guides/no-secret-first-agent.html",
 				"guides/your-first-agent.html",
 				"guides/debugging-agents.html",
@@ -148,6 +189,7 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
 				if idx == -1 {
 					t.Fatalf("%s missing first-agent wayfinding link %q; keep the no-secret → first-agent → debugging → 0→hero path discoverable", check.name, link)
 				}
+				assertWayfindingTargetExists(t, root, check.file, link)
 				if idx < last {
 					t.Fatalf("%s link %q appeared out of order; expected no-secret → first-agent → debugging → 0→hero", check.name, link)
 				}
@@ -157,6 +199,257 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
 	}
 }
 
+func TestFirstAgentWayfindingLinkTargetsResolve(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	checks := []struct {
+		name    string
+		file    string
+		heading string
+	}{
+		{
+			name:    "README first-agent on-ramp",
+			file:    filepath.Join(root, "README.md"),
+			heading: "### First agent on-ramp",
+		},
+		{
+			name:    "README examples list",
+			file:    filepath.Join(root, "README.md"),
+			heading: "## Examples",
+		},
+		{
+			name:    "repository examples index",
+			file:    filepath.Join(root, "examples", "README.md"),
+			heading: "## Recommended first-agent path",
+		},
+		{
+			name:    "website examples index",
+			file:    filepath.Join(root, "internal", "website", "docs", "examples", "index.md"),
+			heading: "## Start here",
+		},
+		{
+			name:    "website getting-started on-ramp",
+			file:    filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
+			heading: "### First-agent on-ramp",
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			section := firstMarkdownSection(t, readFile(t, check.file), check.heading)
+			links := markdownLinks(section)
+			if len(links) == 0 {
+				t.Fatalf("%s has no Markdown links in %q", check.name, check.heading)
+			}
+			for _, link := range links {
+				assertWayfindingTargetExists(t, root, check.file, link)
+			}
+		})
+	}
+}
+
+func TestFirstAgentLifecycleCommandOrderIsDocumented(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	checks := []struct {
+		name    string
+		file    string
+		heading string
+		markers []string
+	}{
+		{
+			name:    "0→hero guide lifecycle",
+			file:    filepath.Join(root, "internal", "website", "docs", "guides", "zero-to-hero.md"),
+			heading: "## What the contract covers",
+			markers: []string{"micro new", "micro run", "micro chat", "micro inspect agent", "micro deploy --dry-run"},
+		},
+		{
+			name:    "CLI docs lifecycle",
+			file:    filepath.Join(root, "cmd", "micro", "cli", "cli.go"),
+			heading: "const docsWayfinding",
+			markers: []string{"micro agent demo", "micro run", "micro chat", "micro inspect agent", "deploy dry-run"},
+		},
+		{
+			name:    "scaffold next steps",
+			file:    filepath.Join(root, "cmd", "micro", "cli", "new", "new.go"),
+			heading: "func printNextSteps",
+			markers: []string{"go run .", "micro chat", "micro inspect agent", "micro agent demo", "micro docs"},
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			doc := readFile(t, check.file)
+			if check.heading != "" {
+				start := strings.Index(doc, check.heading)
+				if start == -1 {
+					t.Fatalf("%s missing %q boundary", check.name, check.heading)
+				}
+				doc = doc[start:]
+			}
+			assertOrderedMarkers(t, check.name, doc, check.markers)
+		})
+	}
+}
+
+func TestExamplesIndexesPreserveLifecycleMap(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	checks := []struct {
+		name    string
+		file    string
+		heading string
+		want    []string
+		ordered []string
+	}{
+		{
+			name:    "repository examples lifecycle map",
+			file:    filepath.Join(root, "examples", "README.md"),
+			heading: "## Recommended first-agent path",
+			want: []string{
+				"hello-world",
+				"0→1",
+				"first-agent",
+				"support",
+				"services",
+				"agents",
+				"workflows",
+				"Debugging and observability",
+			},
+			ordered: []string{"1. First service", "2. First agent", "3. First workflow"},
+		},
+		{
+			name:    "website examples lifecycle map",
+			file:    filepath.Join(root, "internal", "website", "docs", "examples", "index.md"),
+			heading: "## Start here",
+			want: []string{
+				"examples/hello-world",
+				"0→1",
+				"examples/first-agent",
+				"examples/support",
+				"services",
+				"agents",
+				"workflows",
+				"debugging-agents.html",
+			},
+			ordered: []string{"0→1 service", "Provider-free first agent", "0→hero lifecycle"},
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			section := firstMarkdownSection(t, readFile(t, check.file), check.heading)
+			for _, want := range check.want {
+				if !strings.Contains(section, want) {
+					t.Fatalf("%s missing lifecycle map marker %q", check.name, want)
+				}
+			}
+
+			last := -1
+			for _, marker := range check.ordered {
+				idx := strings.Index(section, marker)
+				if idx == -1 {
+					t.Fatalf("%s missing ordered example marker %q", check.name, marker)
+				}
+				if idx < last {
+					t.Fatalf("%s marker %q appeared out of order; keep examples flowing hello-world/0→1 → first-agent → support/0→hero", check.name, marker)
+				}
+				last = idx
+			}
+		})
+	}
+}
+
+func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	checks := []struct {
+		name    string
+		file    string
+		section string
+		want    []string
+	}{
+		{
+			name:    "README quick start",
+			file:    filepath.Join(root, "README.md"),
+			section: "## Quick Start",
+			want: []string{
+				"install troubleshooting guide",
+				"### Fastest start — no API key",
+				"micro new helloworld",
+				"micro run",
+				"curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call",
+				"### First agent on-ramp",
+				"micro agent demo",
+				"### Generate from a prompt — with an LLM key",
+			},
+		},
+		{
+			name:    "CLI README",
+			file:    filepath.Join(root, "cmd", "micro", "README.md"),
+			section: "## Create a service",
+			want: []string{
+				"## Create a service",
+				"micro new helloworld",
+				"## Run the service",
+				"micro run",
+				"micro agent demo",
+			},
+		},
+		{
+			name:    "website getting started",
+			file:    filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
+			section: "Install troubleshooting",
+			want: []string{
+				"Install troubleshooting",
+				"## Quick Start: Scaffold, Run, Call",
+				"micro new helloworld",
+				"micro run",
+				"curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call",
+				"### First-agent on-ramp",
+				"micro agent demo",
+				"## Generate from a Prompt — with an LLM key",
+			},
+		},
+		{
+			name:    "website quickstart",
+			file:    filepath.Join(root, "internal", "website", "docs", "quickstart.md"),
+			section: "## Create Your First Service",
+			want: []string{
+				"micro new helloworld",
+				"micro run",
+				"curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call",
+				"## Next Steps",
+				"micro agent demo",
+				"micro zero-to-hero",
+				"guides/no-secret-first-agent.html",
+				"guides/debugging-agents.html",
+				"guides/zero-to-hero.html",
+			},
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			doc := readFile(t, check.file)
+			if check.section != "" {
+				start := strings.Index(doc, check.section)
+				if start == -1 {
+					t.Fatalf("%s missing %q section", check.name, check.section)
+				}
+				doc = doc[start:]
+			}
+			last := -1
+			for _, want := range check.want {
+				idx := strings.Index(doc, want)
+				if idx == -1 {
+					t.Fatalf("%s missing no-secret first-run marker %q", check.name, want)
+				}
+				if idx < last {
+					t.Fatalf("%s marker %q appeared out of order; keep install/scaffold/run/call before provider-backed generation", check.name, want)
+				}
+				last = idx
+			}
+		})
+	}
+}
+
 func TestNoSecretFirstAgentTranscript(t *testing.T) {
 	root := filepath.Clean(filepath.Join("..", "..", ".."))
 	guide := readFile(t, filepath.Join(root, "internal", "website", "docs", "guides", "no-secret-first-agent.md"))
@@ -243,3 +536,67 @@ func readFile(t *testing.T, name string) string {
 	}
 	return string(data)
 }
+
+var markdownLinkRE = regexp.MustCompile(`\[[^\]]+\]\(([^)#?]+)(?:[#?][^)]*)?\)`)
+
+func markdownLinks(section string) []string {
+	matches := markdownLinkRE.FindAllStringSubmatch(section, -1)
+	links := make([]string, 0, len(matches))
+	for _, match := range matches {
+		if len(match) > 1 {
+			links = append(links, match[1])
+		}
+	}
+	return links
+}
+
+func assertWayfindingTargetExists(t *testing.T, root, sourceFile, link string) {
+	t.Helper()
+	if !strings.Contains(link, "/") && !strings.Contains(link, ".") {
+		return
+	}
+	if strings.HasPrefix(link, "http://") || strings.HasPrefix(link, "https://") {
+		switch {
+		case strings.HasPrefix(link, "https://go-micro.dev/docs/"):
+			link = strings.TrimPrefix(link, "https://go-micro.dev/docs/")
+			link = filepath.ToSlash(filepath.Join("internal", "website", "docs", strings.TrimSuffix(link, ".html")+".md"))
+		case strings.HasPrefix(link, "https://github.com/micro/go-micro/tree/master/"):
+			link = strings.TrimPrefix(link, "https://github.com/micro/go-micro/tree/master/")
+		default:
+			return
+		}
+	} else if strings.HasSuffix(link, ".html") {
+		sourceDir := filepath.Dir(sourceFile)
+		websiteDocs := filepath.Join(root, "internal", "website", "docs")
+		resolved := filepath.Clean(filepath.Join(sourceDir, filepath.FromSlash(link)))
+		if rel, err := filepath.Rel(websiteDocs, resolved); err == nil && !strings.HasPrefix(rel, "..") {
+			link = filepath.ToSlash(filepath.Join("internal", "website", "docs", strings.TrimSuffix(rel, ".html")+".md"))
+		}
+	} else if strings.HasPrefix(link, ".") {
+		target := filepath.Clean(filepath.Join(filepath.Dir(sourceFile), filepath.FromSlash(link)))
+		if _, err := os.Stat(target); err != nil {
+			t.Fatalf("first-agent wayfinding link %q in %s resolves to missing target %s: %v", link, sourceFile, target, err)
+		}
+		return
+	}
+
+	target := filepath.Join(root, filepath.FromSlash(link))
+	if _, err := os.Stat(target); err != nil {
+		t.Fatalf("first-agent wayfinding link %q in %s resolves to missing target %s: %v", link, sourceFile, target, err)
+	}
+}
+
+func assertOrderedMarkers(t *testing.T, name, doc string, markers []string) {
+	t.Helper()
+	last := -1
+	for _, marker := range markers {
+		idx := strings.Index(doc, marker)
+		if idx == -1 {
+			t.Fatalf("%s missing lifecycle command marker %q", name, marker)
+		}
+		if idx < last {
+			t.Fatalf("%s marker %q appeared out of order; keep scaffold → run → chat → inspect → deploy discoverable", name, marker)
+		}
+		last = idx
+	}
+}

internal/website/_data/navigation.yml

@@ -3,6 +3,8 @@ core:
     url: /docs/
   - title: Getting Started
     url: /docs/getting-started.html
+  - title: Install Troubleshooting
+    url: /docs/guides/install-troubleshooting.html
   - title: AI Integration
     url: /docs/ai-integration.html
   - title: No-secret First Agent
@@ -80,6 +82,7 @@ project:
   - title: Server (optional)
     url: /docs/server.html
 search_order:
+  - /docs/guides/install-troubleshooting.html
   - /docs/guides/your-first-agent.html
   - /docs/guides/zero-to-hero.html
   - /docs/guides/debugging-agents.html

internal/website/docs/architecture.md

@@ -2,75 +2,124 @@
 layout: default
 ---
 
-## Architecture
+# Architecture
 
 <img src="/images/generated/architecture.jpg" alt="Go Micro architecture" style="width: 100%; border-radius: 8px; margin: 1rem 0 1.5rem;" />
 
-An overview of the Go Micro architecture.
+Go Micro is one runtime for the services → agents → workflows lifecycle. The same
+registry, client/server RPC, store, broker, and gateway primitives that run a
+service also give an agent discoverable tools, durable state, interop, and a
+place to hand off deterministic work.
 
-## Overview
+## Lifecycle map
 
-Go Micro abstracts away the details of distributed systems. Here are the main features.
+```text
+Services  →  Agents  →  Workflows
+handlers     model loop  durable orchestration
+registry     memory      triggers and ordered steps
+RPC tools    guardrails   agent dispatch
+```
 
-- **Authentication** - Auth is built in as a first class citizen. Authentication and authorization enable secure
-  zero trust networking by providing every service an identity and certificates. This additionally includes rule
-  based access control.
+The layers are progressive: start with a service, expose its endpoints as tools,
+wrap those tools with an agent, then move the known paths into flows so the model
+only handles the uncertain parts.
 
-- **Dynamic Config** - Load and hot reload dynamic config from anywhere. The config interface provides a way to load application
-  level config from any source such as env vars, file, etcd. You can merge the sources and even define fallbacks.
+## Service substrate
 
-- **Data Storage** - A simple data store interface to read, write and delete records. It includes support for many storage backends
-in the plugins repo. State and persistence becomes a core requirement beyond prototyping and Micro looks to build that into the framework.
+Go Micro's service framework supplies the distributed-systems base every agent
+needs:
 
-- **Service Discovery** - Automatic service registration and name resolution. Service discovery is at the core of micro service
-  development. When service A needs to speak to service B it needs the location of that service. The default discovery mechanism is
-  multicast DNS (mdns), a zeroconf system.
+- **Registry** — services, agents, and flows register under names so clients,
+  gateways, and other agents can discover them without hard-coded addresses. The
+  default is mDNS for local development, with pluggable backends for production.
+- **RPC client/server** — endpoints are normal Go handlers reached through the
+  client, load balanced through discovery, encoded through codecs, and optionally
+  streamed.
+- **Broker** — asynchronous events connect services and trigger flows without
+  coupling producers to consumers.
+- **Config and auth** — dynamic configuration plus identity and authorization keep
+  local and production runtimes using the same shape.
+- **Pluggable interfaces** — registry, broker, store, transport, codecs, auth, and
+  config are Go interfaces, so the runtime can stay stable while deployments swap
+  infrastructure.
 
-- **Load Balancing** - Client side load balancing built on service discovery. Once we have the addresses of any number of instances
-  of a service we now need a way to decide which node to route to. We use random hashed load balancing to provide even distribution
-  across the services and retry a different node if there's a problem.
+That substrate is intentionally not separate from the agent stack. A service
+endpoint is the smallest useful unit of work, and the registry is the source of
+truth for which tools and agents exist.
 
-- **Message Encoding** - Dynamic message encoding based on content-type. The client and server will use codecs along with content-type
-  to seamlessly encode and decode Go types for you. Any variety of messages could be encoded and sent from different clients. The client
-  and server handle this by default. This includes protobuf and json by default.
+## Agent harness
 
-- **RPC Client/Server** - RPC based request/response with support for bidirectional streaming. We provide an abstraction for synchronous
-  communication. A request made to a service will be automatically resolved, load balanced, dialled and streamed.
+Agents compose the service substrate with the AI-specific packages:
 
-- **Async Messaging** - PubSub is built in as a first class citizen for asynchronous communication and event driven architectures.
-  Event notifications are a core pattern in micro service development. The default messaging system is a HTTP event message broker.
+- **`model` / `ai.Model`** — a pluggable model interface normalizes provider calls
+  while letting applications pick Anthropic, OpenAI, Gemini, Atlas Cloud, Groq,
+  Mistral, Together AI, or a mock model for no-secret tests.
+- **`store` / memory** — agent history, plans, run state, and compacted memory live
+  in durable storage rather than in an in-process chat loop.
+- **`ai.Tools`** — discovers registered service endpoints and executes them through
+  the Go Micro client, so tools are generated from running services instead of a
+  parallel tool registry.
+- **`agent`** — runs the tool-calling loop with guardrails, planning, delegation,
+  service-backed memory, and an `Agent.Chat` RPC endpoint. An agent is therefore a
+  service other clients and agents can call.
 
-- **Pluggable Interfaces** - Go Micro makes use of Go interfaces for each distributed system abstraction. Because of this these interfaces
-  are pluggable and allows Go Micro to be runtime agnostic. You can plugin any underlying technology.
+The result is a harness, not just a prompt loop: model calls are bounded by tool
+scope, state is recoverable, and the same CLI and gateways that reach services can
+reach agents.
 
-## Design
+## Workflows
 
-We will share more on architecture soon
+Use `flow` when the path is known or must be repeatable. Flows subscribe to broker
+events, run ordered deterministic steps, and can dispatch to an agent at the point
+where judgment or language understanding is needed. This keeps long-running work
+observable and restartable while preserving agents for open-ended decisions.
+
+A common shape is:
+
+1. A service emits an event such as `ticket.created`.
+2. A flow validates and enriches the event with deterministic handlers.
+3. The flow dispatches to an agent for classification, drafting, or escalation.
+4. The agent calls registered service tools and returns to the flow for final
+   durable steps.
+
+## Interop gateways
+
+Gateways project the same runtime to external callers:
+
+- **`micro api`** exposes service RPC over HTTP.
+- **`micro mcp`** exposes registered service endpoints as Model Context Protocol
+  tools for external agents.
+- **`micro a2a`** exposes registered Go Micro agents through the Agent2Agent
+  protocol and lets Go Micro flows or agents dispatch to agents hosted elsewhere.
+
+MCP is the services-as-tools boundary; A2A is the agents-as-agents boundary. Both
+come from registry metadata, so adding a service or agent updates the external
+surface without duplicate wiring.
+
+## Developer path
+
+If you are new, follow the architecture in the same order the runtime composes it:
+
+1. [Install troubleshooting](guides/install-troubleshooting.html) — make sure the
+   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. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)
+   — run one service-backed agent with a mock model.
+4. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — see the
+   maintained support-agent path work without a provider key.
+5. [Your First Agent](guides/your-first-agent.html) — build and chat with a
+   service-backed agent.
+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
 
-- [ADR Index](architecture/index.md)
+- [AI Integration](ai-integration.html) — layer-by-layer services → agents → workflows wiring
+- [Getting Started](getting-started.html) — first service and first-agent on-ramp
+- [Examples](examples/) — runnable examples mapped to the lifecycle
+- [ADR Index](architecture/index.md) — architecture decision records
 - [Configuration](config.html)
 - [Plugins](plugins.html)
-
-## Example Usage
-
-Here's a minimal Go Micro service demonstrating the architecture:
-
-```go
-package main
-
-import (
-    "go-micro.dev/v6"
-    "log"
-)
-
-func main() {
-    service := micro.NewService("example",
-    )
-    service.Init()
-    if err := service.Run(); err != nil {
-        log.Fatal(err)
-    }
-}
-```

internal/website/docs/getting-started.md

@@ -17,15 +17,7 @@ Go Micro has three core abstractions:
 ## Prerequisites
 
 - **Go 1.24+** for development. The `curl` install below gives you the `micro` binary without Go, but `micro run` compiles your services, so you'll want Go installed to build them.
-- An **LLM provider key** (Anthropic, OpenAI, Gemini, …) *only* for the AI features — `micro run --prompt`, `micro chat`, and agents. Plain services need no key. Set it before running, e.g. `export ANTHROPIC_API_KEY=sk-ant-...`.
-
-Before your first provider-backed agent run, check the local path with:
-
-```bash
-micro agent preflight
-```
-
-The preflight is read-only: it verifies Go 1.24+, the `micro` binary, provider-key setup, and whether the default `micro run` gateway port is free, without calling an LLM provider. When a check fails it prints the exact fix plus the next guide to open, so the scaffold → run → chat path stays walkable.
+- **No LLM provider key is required** for the first run below. Add an Anthropic, OpenAI, Gemini, or other provider key only when you reach the provider-backed generation and chat steps.
 
 ## Install
 
@@ -37,67 +29,42 @@ curl -fsSL https://go-micro.dev/install.sh | sh
 go install go-micro.dev/v6/cmd/micro@latest
 ```
 
-## Quick Start: Generate from a Prompt
+If install or shell setup fails, start with [Install troubleshooting](guides/install-troubleshooting.html) to verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path.
 
-Prefer to start from a runnable reference? Clone the repository and run the maintained support-desk lifecycle example first:
+## Quick Start: Scaffold, Run, Call
+
+Start with the path that proves the runtime works before any provider setup: install the CLI, scaffold one service, run it locally, then call it through the gateway.
 
 ```bash
-git clone https://github.com/micro/go-micro.git
-cd go-micro
-go run ./examples/support
+micro new helloworld
+cd helloworld
+micro run
 ```
 
-That example is the no-secret 0→hero path: services expose ticket/customer/notification tools, an agent handles the work, and an event-driven flow triggers the agent. See [Learn by Example](examples/) when you want more runnable starting points.
-
-Describe what you need. The AI designs services, writes handlers, compiles, and starts them:
+In another terminal, call the generated service:
 
 ```bash
-micro run --prompt "task management system"
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
 ```
 
-You'll see the design, confirm, and services + agent start:
+That install → scaffold → run → call loop is the 0→1 contract. It requires Go and the `micro` binary, but no LLM key. Once this succeeds, you know the local runtime, hot reload, gateway, and service registration are working.
 
-```text
-Services:
-  ● task — Core task management
-  ● project — Project organization
-
-Generate? [Y/n]
-
-Micro
-  Services:
-    ● task
-    ● project
-  Agents:
-    ◆ agent
-```
-
-The interactive console lets you talk to your services immediately:
-
-```text
-> Create a project called Launch, then add a task called 'Write docs'
-
-→ project_Project_Create({"name":"Launch"})
-← {"record":{"id":"p1..."},"success":true}
-→ task_Task_Create({"title":"Write docs","project_id":"p1..."})
-
-Created project Launch and added task 'Write docs' to it.
-```
-
-The console discovers services from the registry and orchestrates across them via the agent. Use `micro run -d` for detached mode without the console, or `micro chat` as a standalone command.
 
 ### First-agent on-ramp
 
 After this quick start, follow the agent path in order:
 
-1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
-2. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) — run one service-backed agent with a mock model and no provider key.
-3. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — run a useful support agent with a mock model before setting up a provider key.
-4. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
-5. [Debugging your agent](guides/debugging-agents.html) — inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent surprises you.
-6. [0→hero reference path](guides/zero-to-hero.html) — prove the full scaffold → run → chat → inspect → deploy dry-run lifecycle with commands exercised by `make harness`.
+1. [Install troubleshooting](guides/install-troubleshooting.html) — verify the CLI install before agent work.
+2. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
+3. `micro zero-to-hero` — print the maintained one-command no-secret lifecycle harness and runnable examples.
+4. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) — run one service-backed agent with a mock model and no provider key.
+5. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — run a useful support agent with a mock model before setting up a provider key.
+6. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
+7. [Debugging your agent](guides/debugging-agents.html) — inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent surprises you.
+8. [0→hero reference path](guides/zero-to-hero.html) — prove the full scaffold → run → chat → inspect → deploy dry-run lifecycle with commands exercised by `make harness`.
 
-## Quick Start: Write a Service
+## Write a Service
 
 Create and run a service manually:
 
@@ -161,6 +128,43 @@ micro new events --template pubsub
 micro new gateway --template api
 ```
 
+
+## Generate from a Prompt — with an LLM key
+
+After the no-secret path works, set a provider key if you want Go Micro to design services and an agent from a prompt:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GEMINI_API_KEY, ...
+micro run --prompt "task management system" --provider anthropic
+```
+
+You'll see the design, confirm it, and then services plus an agent start:
+
+```text
+Services:
+  ● task — Core task management
+  ● project — Project organization
+
+Generate? [Y/n]
+
+Micro
+  Services:
+    ● task
+    ● project
+  Agents:
+    ◆ agent
+```
+
+Use the interactive console, `micro run -d` plus `micro chat`, or the agent playground to talk to the generated services.
+
+Before your first provider-backed agent run, check the local path with:
+
+```bash
+micro agent preflight
+```
+
+The preflight is read-only: it verifies Go 1.24+, the `micro` binary, provider-key setup, and whether the default `micro run` gateway port is free, without calling an LLM provider. When a check fails it prints the exact fix plus the next guide to open, so the scaffold → run → chat path stays walkable.
+
 ## Building Agents
 
 For a complete service-backed walkthrough, start with [Your First Agent](guides/your-first-agent.html). If you want to run before you write, use [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) for the full services → agents → workflows lifecycle or [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate) for the smallest multi-agent planning/delegation path.

internal/website/docs/guides/debugging-agents.md

@@ -17,9 +17,21 @@ micro inspect ...  # read the recorded run or workflow history
 
 Debug the lifecycle in the same order Go Micro runs it: first prove the service is
 registered and callable, then inspect the agent run that chose tools, then inspect
-any workflow that handed off to the agent. If the first local run fails before a
-chat turn, run `micro agent preflight`; failed checks include `Fix:` and `Next:`
-lines for Go, CLI installation, provider-key setup, and the local gateway port.
+any workflow that handed off to the agent.
+
+Use the recovery command that matches where you are in the first-agent journey:
+
+| Checkpoint | When to use it | Command |
+| --- | --- | --- |
+| Install troubleshooting | `micro` is not installed, not on `PATH`, or the shell cannot run it. | [Install troubleshooting](install-troubleshooting.html) |
+| Preflight before `micro run` | You have not started the local runtime yet and want to verify Go, CLI, provider-key, and gateway-port prerequisites. | `micro agent preflight` |
+| Doctor after `micro run` | `micro run` is active, but chat, the `/agent` gateway, agent registration, provider settings, or inspect/run history is not behaving. | `micro agent doctor` |
+
+`micro agent preflight` is read-only and runs before the first local run; failed
+checks include `Fix:` and `Next:` lines for Go, CLI installation, provider-key
+setup, and the local gateway port. Once `micro run` is already up, switch to
+`micro agent doctor` so the recovery output follows the live gateway, chat
+settings, registered agents, provider configuration, and inspectable run history.
 
 ## 1. Reproduce one small turn
 

internal/website/docs/guides/install-troubleshooting.md

@@ -0,0 +1,96 @@
+---
+layout: default
+title: Install troubleshooting
+---
+
+# Install troubleshooting
+
+Use this page before `micro new` or `micro agent demo` when the CLI install is
+unclear. The goal is to prove three boundaries in order: the `micro` binary is on
+`PATH`, it is the version you expected, and the no-secret first-run path works
+without provider keys.
+
+## 1. Choose one install path
+
+### Binary installer (no Go required to install)
+
+```sh
+curl -fsSL https://go-micro.dev/install.sh | sh
+```
+
+Use this when you want the released `micro` binary without building it yourself.
+The generated services still need a Go toolchain when you run `micro run`, but the
+installer itself does not require Go.
+
+### Go install (build from source)
+
+```sh
+go install go-micro.dev/v6/cmd/micro@latest
+```
+
+Use this when Go is already installed and you want the binary in your Go bin
+directory. If the command succeeds but `micro` is not found, your Go bin directory
+is probably not on `PATH`.
+
+## 2. Verify `PATH` and version
+
+Check which binary your shell will run:
+
+```sh
+command -v micro
+micro --version
+```
+
+If `command -v micro` prints nothing, add the install directory to `PATH`, then
+open a new terminal and retry. Common locations are:
+
+```sh
+export PATH="$HOME/.micro/bin:$PATH"      # binary installer
+export PATH="$(go env GOPATH)/bin:$PATH"  # go install
+```
+
+If `micro --version` shows an older binary than expected, remove the stale copy or
+put the intended install directory earlier in `PATH`.
+
+## 3. Run the no-secret smoke path
+
+Once `micro` resolves, prove the local service runtime before adding LLM provider
+keys:
+
+```sh
+micro new helloworld
+cd helloworld
+micro run
+```
+
+In another terminal:
+
+```sh
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
+```
+
+This checks the scaffold, local build, gateway, and service registration without
+calling a model provider.
+
+## 4. Recover common failures
+
+| Symptom | Check | Fix |
+|---------|-------|-----|
+| `micro: command not found` | `command -v micro` | Add the installer bin directory or `$(go env GOPATH)/bin` to `PATH`, then open a new terminal. |
+| `micro run` cannot find Go | `go version` | Install Go 1.24 or newer from <https://go.dev/doc/install>. |
+| The gateway port is busy | `lsof -i :8080` | Stop the process using the port, or run with a different address. |
+| Provider-key errors block an agent run | `micro agent preflight` | Stay on the no-secret path first: run `micro agent demo`, then the no-secret first-agent guide. |
+
+## 5. Continue the first-agent on-ramp
+
+After install verification succeeds, continue in order:
+
+1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps.
+2. [No-secret first-agent transcript](no-secret-first-agent.html) — prove an agent can use services without a provider key.
+3. [Your First Agent](your-first-agent.html) — build and chat with your own service-backed agent.
+4. [Debugging your agent](debugging-agents.html) — inspect registration, tool calls, run history, and provider failures.
+5. [0→hero Reference](zero-to-hero.html) — walk the full services → agents → workflows lifecycle.
+
+For repository contributors, `make install-smoke` runs the same installer seam
+against a local build without network access.

internal/website/docs/guides/your-first-agent.md

@@ -53,7 +53,11 @@ Run the read-only first-agent preflight before starting the walkthrough. The sam
 micro agent preflight
 ```
 
-It checks Go 1.24+, the `micro` binary, provider-key setup, and the default local gateway port without contacting a provider. Failed checks include a `Fix:` line and a `Next:` line that points back to this guide, the no-secret walkthrough, or the debugging guide.
+It checks Go 1.24+, the `micro` binary, provider-key setup, and the default local gateway port without contacting a provider. Failed checks include a `Fix:` line and a `Next:` line that points back to this guide, the no-secret walkthrough, or the debugging guide. Use it before `micro run`; if `micro run` is already active but `micro chat`, the `/agent` gateway, registration, provider settings, or inspect history is failing, run the after-run recovery check instead:
+
+```sh
+micro agent doctor
+```
 
 ## 1. Create a workspace
 

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

@@ -28,6 +28,16 @@ cloud credentials?"
 | Runtime reference app | `examples/support` runs typed services, an agent using those services as tools, an event-driven flow handoff, and an approval gate with only the model mocked. | `go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1` |
 | Runtime harnesses | Real services, agents, durable flows, store-backed history, delegation, and A2A run with only the model mocked. | `./internal/harness/zero-to-hero-ci/run.sh` and `make provider-conformance-mock` |
 
+## Find the one-command entrypoint
+
+After installing the CLI, ask `micro` for the maintained no-secret lifecycle command:
+
+```sh
+micro zero-to-hero
+```
+
+The command prints the exact harness command below plus the smaller runnable examples, so a new developer can discover the 0→hero path from CLI help instead of translating this guide by hand.
+
 ## Run the runnable example
 
 From the repository root, start with the smallest service-backed agent when you want the fastest no-secret success path:

internal/website/docs/quickstart.md

@@ -16,6 +16,8 @@ Or, if you have Go and prefer to build from source:
 go install go-micro.dev/v6/cmd/micro@latest
 ```
 
+If the installer finishes but your shell cannot find `micro`, open [Install troubleshooting](guides/install-troubleshooting.html) before creating your first service.
+
 ## Create Your First Service
 
 ```bash
@@ -39,10 +41,14 @@ curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
 
 You now have the service half of the services → agents → workflows lifecycle running locally. Keep the on-ramp going in this order:
 
-1. **[Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)** - run a mock-model, no-secret agent before adding provider keys.
-2. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
-3. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
-4. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
+1. **[Install troubleshooting](guides/install-troubleshooting.html)** - verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path.
+2. `micro agent demo` - print the provider-free first-agent demo command and the next docs steps from the installed CLI.
+3. `micro zero-to-hero` - print the maintained one-command no-secret lifecycle harness and runnable examples.
+4. **[Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)** - run a mock-model, no-secret agent before adding provider keys.
+5. **[No-secret first-agent transcript](guides/no-secret-first-agent.html)** - run a useful support agent with a mock model before setting up a provider key.
+6. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
+7. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
+8. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
 
 After that first-agent path, branch out to:
 
@@ -113,4 +119,3 @@ publisher.Publish(ctx, &UserCreatedEvent{
 - **[Discord Community](https://discord.gg/G8Gk5j3uXr)** - Chat with other users
 - **[GitHub Issues](https://github.com/micro/go-micro/issues)** - Report bugs or request features
 - **[Documentation](https://go-micro.dev/docs/)** - Complete docs
-