Add first-agent docs wayfinding guard

Makefile

@@ -80,7 +80,7 @@ cli-wayfinding:
 # maintained local docs and examples. This is a focused no-network guard for the
 # developer-adoption on-ramp.
 docs-wayfinding:
-	go test ./internal/harness/zero-to-hero-ci -run 'TestFirstAgentWayfindingDocs|TestFirstAgentWayfindingLinkTargetsResolve' -count=1
+	go test ./internal/harness/zero-to-hero-ci -run 'TestFirstAgentWayfinding' -count=1
 	go test ./cmd/micro -run 'TestFirstAgentDocsMatchCLIOutput|TestFirstAgentWalkthroughCLIBoundaries' -count=1
 
 # Verify the documented install script and first-run CLI command boundaries without

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

@@ -422,6 +422,106 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
 	}
 }
 
+func TestFirstAgentWayfindingCanonicalTrailStaysInSync(t *testing.T) {
+	root := filepath.Clean(filepath.Join("..", "..", ".."))
+	onRampTrail := []string{
+		"micro agent demo",
+		"micro examples",
+		"micro zero-to-hero",
+		"examples/INDEX.md",
+		"examples/first-agent",
+		"examples/support",
+		"no-secret-first-agent",
+		"your-first-agent",
+		"debugging-agents",
+		"micro inspect agent <name>",
+		"zero-to-hero",
+	}
+	checks := []struct {
+		name    string
+		file    string
+		heading string
+		markers []string
+	}{
+		{
+			name:    "README first-agent on-ramp",
+			file:    filepath.Join(root, "README.md"),
+			heading: "### First agent on-ramp",
+			markers: onRampTrail,
+		},
+		{
+			name:    "website docs index first-agent path",
+			file:    filepath.Join(root, "internal", "website", "docs", "index.md"),
+			heading: "## Learn More",
+			markers: onRampTrail,
+		},
+		{
+			name:    "website getting-started first-agent on-ramp",
+			file:    filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
+			heading: "### First-agent on-ramp",
+			markers: onRampTrail,
+		},
+		{
+			name:    "website quickstart next steps",
+			file:    filepath.Join(root, "internal", "website", "docs", "quickstart.md"),
+			heading: "## Next Steps",
+			markers: onRampTrail,
+		},
+		{
+			name:    "examples map recommended adoption path",
+			file:    filepath.Join(root, "examples", "INDEX.md"),
+			heading: "",
+			markers: []string{
+				"micro examples",
+				"micro zero-to-hero",
+				"examples/INDEX.md",
+				"examples/first-agent",
+				"examples/support",
+				"zero-to-hero",
+			},
+		},
+		{
+			name:    "no-secret first-agent guide next steps",
+			file:    filepath.Join(root, "internal", "website", "docs", "guides", "no-secret-first-agent.md"),
+			heading: "",
+			markers: []string{
+				"micro agent demo",
+				"examples/first-agent",
+				"examples/support",
+				"your-first-agent",
+				"debugging-agents",
+				"micro inspect agent <name>",
+			},
+		},
+		{
+			name:    "0→hero guide related examples",
+			file:    filepath.Join(root, "internal", "website", "docs", "guides", "zero-to-hero.md"),
+			heading: "",
+			markers: []string{
+				"micro zero-to-hero",
+				"examples/first-agent",
+				"examples/support",
+				"micro inspect agent <name>",
+				"zero-to-hero",
+			},
+		},
+	}
+
+	for _, check := range checks {
+		t.Run(check.name, func(t *testing.T) {
+			section := readFile(t, check.file)
+			if check.heading != "" {
+				section = firstMarkdownSection(t, section, check.heading)
+			}
+			for _, marker := range check.markers {
+				if !containsWayfindingMarker(section, marker) {
+					t.Fatalf("%s missing canonical first-agent wayfinding marker %q; keep README, website, examples, no-secret, and 0→hero surfaces aligned", check.name, marker)
+				}
+			}
+		})
+	}
+}
+
 func TestFirstAgentWayfindingLinkTargetsResolve(t *testing.T) {
 	root := filepath.Clean(filepath.Join("..", "..", ".."))
 	checks := []struct {
@@ -543,7 +643,7 @@ func TestFirstAgentGuideChainDocumentsRequiredNextSteps(t *testing.T) {
 			name: "zero-to-hero guide exposes the provider-free contract commands",
 			file: filepath.Join(root, "internal", "website", "docs", "guides", "zero-to-hero.md"),
 			markers: []string{
-				"go test ./internal/harness/zero-to-hero-ci -run TestFirstAgentWayfindingDocs -count=1",
+				"go test ./internal/harness/zero-to-hero-ci -run TestFirstAgentWayfinding -count=1",
 				"micro zero-to-hero",
 				"go run ./examples/first-agent",
 				"go run ./examples/support",
@@ -1004,6 +1104,43 @@ func markdownLinks(section string) []string {
 	return links
 }
 
+func containsWayfindingMarker(section, marker string) bool {
+	if strings.Contains(section, marker) {
+		return true
+	}
+	switch marker {
+	case "examples/INDEX.md":
+		return strings.Contains(section, "examples/INDEX.md") ||
+			strings.Contains(section, "Recommended adoption path") ||
+			strings.Contains(section, "examples wayfinding index") ||
+			strings.Contains(section, "Examples wayfinding index") ||
+			strings.Contains(section, "./INDEX.md")
+	case "examples/first-agent":
+		return strings.Contains(section, "examples/first-agent") ||
+			strings.Contains(section, "./first-agent")
+	case "examples/support":
+		return strings.Contains(section, "examples/support") ||
+			strings.Contains(section, "./support")
+	case "no-secret-first-agent":
+		return strings.Contains(section, "no-secret-first-agent") ||
+			strings.Contains(section, "No-secret First Agent")
+	case "your-first-agent":
+		return strings.Contains(section, "your-first-agent") ||
+			strings.Contains(section, "Your First Agent")
+	case "debugging-agents":
+		return strings.Contains(section, "debugging-agents") ||
+			strings.Contains(section, "Debugging your agent")
+	case "zero-to-hero":
+		return strings.Contains(section, "zero-to-hero") ||
+			strings.Contains(section, "0→hero")
+	default:
+		if strings.HasPrefix(marker, "micro inspect agent ") {
+			return strings.Contains(section, "micro inspect agent ")
+		}
+		return false
+	}
+}
+
 func assertWayfindingTargetExists(t *testing.T, root, sourceFile, link string) {
 	t.Helper()
 	if !strings.Contains(link, "/") && !strings.Contains(link, ".") {

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

@@ -18,7 +18,7 @@ cloud credentials?"
 | Boundary | Contract | CI check |
 | --- | --- | --- |
 | Scaffold | `micro new` generates a runnable service with and without MCP support. | `go test ./cmd/micro/cli/new -run TestZeroToOne -count=1` |
-| First-agent wayfinding | README and the website getting-started docs keep the no-secret → first-agent → debugging → 0→hero links present and in order. | `go test ./internal/harness/zero-to-hero-ci -run TestFirstAgentWayfindingDocs -count=1` |
+| First-agent wayfinding | README, website index/quickstart, examples, and no-secret/0→hero docs keep the no-secret → first-agent → debugging → 0→hero links present and in order. | `go test ./internal/harness/zero-to-hero-ci -run TestFirstAgentWayfinding -count=1` |
 | First agent | `micro new`, `micro agent preflight`, `micro run`, `micro chat`, and `micro inspect agent <name>` stay available for the documented first-agent walkthrough. | `go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1` |
 | Run | `micro run` remains the local development entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` |
 | Chat | `micro chat` remains the interactive agent entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` |

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 in the same order as the README: `micro agent demo` for the installed no-secret CLI affordance, `micro examples` for the provider-free examples map, `micro zero-to-hero` for the maintained lifecycle harness, [examples wayfinding index](https://github.com/micro/go-micro/blob/master/examples/INDEX.md) for the runnable examples map, [the 0→hero support reference](https://github.com/micro/go-micro/tree/master/examples/support) for the full no-secret lifecycle example, [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 use `micro inspect agent <name>` for 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 in the same order as the README: `micro agent demo` for the installed no-secret CLI affordance, `micro examples` for the provider-free examples map, `micro zero-to-hero` for the maintained lifecycle harness, [examples wayfinding index](https://github.com/micro/go-micro/blob/master/examples/INDEX.md) for the runnable examples map, [the smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) for the fastest provider-free run, [the 0→hero support reference](https://github.com/micro/go-micro/tree/master/examples/support) for the full no-secret lifecycle example, [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 use `micro inspect agent <name>` for 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.
 
@@ -27,6 +27,7 @@ Otherwise continue to read the docs for more information about the framework.
 - `micro agent demo` - Show the provider-free first-agent demo command and next docs steps
 - `micro examples` - Show provider-free first-agent examples in copy/paste order
 - [Examples wayfinding index](https://github.com/micro/go-micro/blob/master/examples/INDEX.md) - Choose the first-agent, support, and interop examples from one map
+- [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) - Run one service-backed agent with a deterministic mock model
 - [0→hero support reference](https://github.com/micro/go-micro/tree/master/examples/support) - Run the maintained no-secret services → agents → workflows example
 - [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