docs: lead v6 installs with latest

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

README.md

@@ -46,7 +46,7 @@ Install the CLI:
 curl -fsSL https://go-micro.dev/install.sh | sh
 
 # Or with Go
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
 ### Fastest start — no API key
@@ -425,6 +425,7 @@ See [all examples](examples/README.md).
 
 - [Getting Started](internal/website/docs/getting-started.md)
 - [AI Integration](internal/website/docs/ai-integration.md)
+- [Your First Agent](internal/website/docs/guides/your-first-agent.md)
 - [0→hero Reference](internal/website/docs/guides/zero-to-hero.md)
 - [Agents and Workflows](internal/website/docs/guides/agents-and-workflows.md)
 - [Agent Design](internal/docs/AGENT_DESIGN.md)

internal/docs/PRIORITIES.md

@@ -21,16 +21,15 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Write a “Your First Agent” walkthrough that takes a developer from services to an agent end to end** ([#3561](https://github.com/micro/go-micro/issues/3561)) — the current adoption gap is the on-ramp, not another internal primitive. This should be the highest-value Now/DX task: a walkable, CI-verifiable first-agent path that proves “building an agent is as easy as building a service” and gives new users an immediate win.
-2. **Lead install docs with `@latest` now that the phantom-module retraction is published** ([#3565](https://github.com/micro/go-micro/issues/3565)) — install friction blocks every later experience. Make the first command current, boring, and consistent across README/website/docs so revived usage does not stall before scaffold/run.
-3. **Surface runnable examples from getting-started and the guides** ([#3562](https://github.com/micro/go-micro/issues/3562)) — the blog canon now has a concrete support-agent story, but developers need obvious links from docs into runnable code. Tie examples to the 0→1 and 0→hero paths so “read → run → modify one thing” is discoverable.
-4. **Reorder the guides nav to lead with doing before concepts** ([#3563](https://github.com/micro/go-micro/issues/3563)) — the framework is deep, but the first impression should be action: quickstart, first agent, examples, debugging, then architecture. This is small, CI-checkable wayfinding work with outsized adoption value.
-5. **Add a “Debugging your agent” guide focused on the dev workflow** ([#3564](https://github.com/micro/go-micro/issues/3564)) — the inner loop is scaffold → run → chat → inspect → deploy. Document how to see tool calls, run history, provider failures, guardrail refusals, and flow handoffs before adding more depth that users cannot diagnose.
-6. **Prevent duplicate tool side effects in the plan/delegate harness** ([#3559](https://github.com/micro/go-micro/issues/3559)) — correctness still matters where it protects real user trust. Plan/delegate is central to the services → agents lifecycle, and duplicate side effects undermine the “agent as dependable service” story.
-7. **Expose `fallback_echo` during A2A streaming fallback conformance** ([#3560](https://github.com/micro/go-micro/issues/3560)) — keep interop conformance trustworthy without letting it dominate the adoption queue. This is scoped, testable, and protects the A2A promise developers see in the README and site.
-8. **Propagate agent run cancellation and deadlines through model and tool calls** ([#3544](https://github.com/micro/go-micro/issues/3544)) — after the on-ramp items, the highest-value remaining Now-phase resilience gap is predictable failure semantics across agent runs, model calls, tool calls, plan/delegate, and flow handoffs. Tool retries and live-provider deadline tuning are in place; the lifecycle still needs cancellation/deadline propagation so work fails safely instead of becoming opaque loops.
-9. **Emit OpenTelemetry spans for agent run timelines** ([#3525](https://github.com/micro/go-micro/issues/3525)) — recent work made runs inspectable, correlated trace metadata through scheduled dispatch, verified restart resume, added opt-in tool retries, hardened provider conformance, and fixed provider-emitted text tool calls. The next Next-phase step is to turn that RunInfo foundation into standard OTel spans for agent runs, model calls, tool calls, checkpoint/resume, cancellation/deadlines, and failures.
-10. **Add an AP2 mandate layer over A2A and x402** ([#3552](https://github.com/micro/go-micro/issues/3552)) — this is a forward interop investment, not a Now-phase blocker: Go Micro already has A2A agents and x402 paid tools, so a small signed-mandate foundation can keep agent payments aligned with the open-protocol story without pulling the queue away from adoption, resilience, or observability. Keep it additive and opt-in while the AP2/FIDO work settles.
+1. **Lead install docs with `@latest` now that the phantom-module retraction is published** ([#3565](https://github.com/micro/go-micro/issues/3565)) — install friction blocks every later experience. Make the first command current, boring, and consistent across README/website/docs so revived usage does not stall before scaffold/run.
+2. **Surface runnable examples from getting-started and the guides** ([#3562](https://github.com/micro/go-micro/issues/3562)) — the blog canon now has a concrete support-agent story, but developers need obvious links from docs into runnable code. Tie examples to the 0→1 and 0→hero paths so “read → run → modify one thing” is discoverable.
+3. **Reorder the guides nav to lead with doing before concepts** ([#3563](https://github.com/micro/go-micro/issues/3563)) — the framework is deep, but the first impression should be action: quickstart, first agent, examples, debugging, then architecture. This is small, CI-checkable wayfinding work with outsized adoption value.
+4. **Add a “Debugging your agent” guide focused on the dev workflow** ([#3564](https://github.com/micro/go-micro/issues/3564)) — the inner loop is scaffold → run → chat → inspect → deploy. Document how to see tool calls, run history, provider failures, guardrail refusals, and flow handoffs before adding more depth that users cannot diagnose.
+5. **Prevent duplicate tool side effects in the plan/delegate harness** ([#3559](https://github.com/micro/go-micro/issues/3559)) — correctness still matters where it protects real user trust. Plan/delegate is central to the services → agents lifecycle, and duplicate side effects undermine the “agent as dependable service” story.
+6. **Expose `fallback_echo` during A2A streaming fallback conformance** ([#3560](https://github.com/micro/go-micro/issues/3560)) — keep interop conformance trustworthy without letting it dominate the adoption queue. This is scoped, testable, and protects the A2A promise developers see in the README and site.
+7. **Propagate agent run cancellation and deadlines through model and tool calls** ([#3544](https://github.com/micro/go-micro/issues/3544)) — after the on-ramp items, the highest-value remaining Now-phase resilience gap is predictable failure semantics across agent runs, model calls, tool calls, plan/delegate, and flow handoffs. Tool retries and live-provider deadline tuning are in place; the lifecycle still needs cancellation/deadline propagation so work fails safely instead of becoming opaque loops.
+8. **Emit OpenTelemetry spans for agent run timelines** ([#3525](https://github.com/micro/go-micro/issues/3525)) — recent work made runs inspectable, correlated trace metadata through scheduled dispatch, verified restart resume, added opt-in tool retries, hardened provider conformance, and fixed provider-emitted text tool calls. The next Next-phase step is to turn that RunInfo foundation into standard OTel spans for agent runs, model calls, tool calls, checkpoint/resume, cancellation/deadlines, and failures.
+9. **Add an AP2 mandate layer over A2A and x402** ([#3552](https://github.com/micro/go-micro/issues/3552)) — this is a forward interop investment, not a Now-phase blocker: Go Micro already has A2A agents and x402 paid tools, so a small signed-mandate foundation can keep agent payments aligned with the open-protocol story without pulling the queue away from adoption, resilience, or observability. Keep it additive and opt-in while the AP2/FIDO work settles.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

internal/website/docs/getting-started.md

@@ -26,11 +26,9 @@ Go Micro has three core abstractions:
 curl -fsSL https://go-micro.dev/install.sh | sh
 
 # Or with Go
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
-> Use `@v6` (not `@latest`). It selects the newest `v6.x.x` release. Plain `@latest` can currently resolve to a stale pre-rename tag through the public module proxy and fail with a "version constraints conflict"; `@v6` avoids that. To pin an exact version use e.g. `@v6.2.0` (see [releases](https://github.com/micro/go-micro/releases)).
-
 ## Quick Start: Generate from a Prompt
 
 Describe what you need. The AI designs services, writes handlers, compiles, and starts them:
@@ -136,6 +134,8 @@ micro new gateway --template api
 
 ## Building Agents
 
+For a complete service-backed walkthrough, start with [Your First Agent](guides/your-first-agent.html).
+
 An Agent is an intelligent layer that manages one or more services:
 
 ```go

internal/website/docs/guides/ai-native-services.md

@@ -17,7 +17,7 @@ A **task management service** with full CRUD operations that:
 ## Prerequisites
 
 ```bash
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
 ## Step 1: Create the Service

internal/website/docs/guides/grpc-compatibility.md

@@ -84,7 +84,7 @@ message Response {
 
 ```bash
 # Install protoc-gen-micro
-go install go-micro.dev/v6/cmd/protoc-gen-micro@v6
+go install go-micro.dev/v6/cmd/protoc-gen-micro@latest
 
 # Generate Go code
 protoc --proto_path=. \
@@ -93,8 +93,6 @@ protoc --proto_path=. \
     proto/helloworld.proto
 ```
 
-> **Note:** Use a specific version instead of `@latest` to avoid module path conflicts. See [releases](https://github.com/micro/go-micro/releases) for the latest version.
-
 ### Server Implementation
 
 ```go

internal/website/docs/guides/migration/from-grpc.md

@@ -90,7 +90,7 @@ Update your proto generation:
 
 ```bash
 # Install protoc-gen-micro
-go install go-micro.dev/v6/cmd/protoc-gen-micro@v6
+go install go-micro.dev/v6/cmd/protoc-gen-micro@latest
 
 # Generate both gRPC and Go Micro code
 protoc --proto_path=. \
@@ -100,7 +100,6 @@ protoc --proto_path=. \
   proto/hello.proto
 ```
 
-> **Note:** Use a specific version instead of `@latest` to avoid module path conflicts. See [releases](https://github.com/micro/go-micro/releases) for the latest version.
 
 This generates:
 - `hello.pb.go` - Protocol Buffers types

internal/website/docs/guides/migration/v5-to-v6.md

@@ -32,7 +32,7 @@ go mod tidy
 Update the CLI too:
 
 ```bash
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
 ## 2. TLS is verified by default

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

@@ -0,0 +1,207 @@
+---
+layout: default
+---
+
+# Your First Agent
+
+This walkthrough builds the smallest useful Go Micro agent path: one service
+with typed endpoints, one agent scoped to that service, and one CLI conversation
+that proves the agent can use the service as a tool. It is the 0→1 version of
+the services → agents → workflows lifecycle: build capability first, add
+intelligence on top, then keep a clear path toward flows when the work needs to
+run on events or schedules.
+
+## What you'll build
+
+A tiny task assistant:
+
+1. A `task` service exposes `Create` and `List` endpoints.
+2. An `assistant` agent is scoped to the `task` service.
+3. `micro run` starts both in the local harness.
+4. `micro chat` asks the agent to create and list tasks.
+
+The same service endpoints are normal RPC methods, dashboard/API actions, MCP
+tools, and agent tools. You do not write a second integration layer for the
+agent.
+
+## Prerequisites
+
+- Go 1.24 or newer.
+- The `micro` CLI installed.
+- An LLM provider key for live agent calls. For example:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Plain service calls work without a model key; the key is only needed when the
+agent reasons over tools.
+
+## 1. Create a workspace
+
+```sh
+mkdir first-agent
+cd first-agent
+go mod init example.com/first-agent
+go get go-micro.dev/v6@v6
+```
+
+Add `main.go`:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"sync"
+
+	micro "go-micro.dev/v6"
+)
+
+type CreateRequest struct {
+	Title string `json:"title"`
+}
+
+type CreateResponse struct {
+	ID    string `json:"id"`
+	Title string `json:"title"`
+}
+
+type ListRequest struct{}
+
+type ListResponse struct {
+	Tasks []CreateResponse `json:"tasks"`
+}
+
+type TaskService struct {
+	mu    sync.Mutex
+	next  int
+	tasks []CreateResponse
+}
+
+// Create adds a task to the list.
+// @example {"title":"Write first agent guide"}
+func (t *TaskService) Create(ctx context.Context, req *CreateRequest, rsp *CreateResponse) error {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	t.next++
+	*rsp = CreateResponse{ID: fmt.Sprintf("task-%d", t.next), Title: req.Title}
+	t.tasks = append(t.tasks, *rsp)
+	return nil
+}
+
+// List returns all known tasks.
+// @example {}
+func (t *TaskService) List(ctx context.Context, req *ListRequest, rsp *ListResponse) error {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	rsp.Tasks = append([]CreateResponse(nil), t.tasks...)
+	return nil
+}
+
+func main() {
+	service := micro.NewService("task")
+	service.Handle(new(TaskService))
+
+	agent := micro.NewAgent("assistant",
+		micro.AgentServices("task"),
+		micro.AgentPrompt("You help manage tasks. Use the task service before answering."),
+		micro.AgentProvider("anthropic"),
+		micro.AgentAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
+	)
+
+	go agent.Run()
+	service.Run()
+}
+```
+
+> Why the comments matter: endpoint comments and `@example` tags become tool
+> descriptions, so the agent has enough context to choose `task.Create` and
+> `task.List` correctly.
+
+## 2. Run the service and agent
+
+From the same directory:
+
+```sh
+micro run
+```
+
+The local harness starts the service, gateway, dashboard, MCP tool surface, and
+agent playground. You can also verify the service directly before involving the
+agent:
+
+```sh
+micro call task TaskService.Create '{"title":"Ship the walkthrough"}'
+micro call task TaskService.List '{}'
+```
+
+## 3. Chat with the agent
+
+In another terminal, ask the agent to use the service:
+
+```sh
+micro chat assistant
+```
+
+Try:
+
+```text
+Create a task called "Review the first-agent walkthrough", then show me all tasks.
+```
+
+A healthy run shows the agent calling the task service and then summarizing the
+result. If the model refuses to call tools, tighten the prompt so it explicitly
+uses the `task` service before answering.
+
+## 4. Know what just happened
+
+- The service registered typed RPC endpoints.
+- Go Micro derived tool descriptions from the endpoint names, comments, request
+  fields, and examples.
+- The agent registered as another service with an `Agent.Chat` endpoint.
+- `micro chat` sent your message to the agent.
+- The agent selected the scoped `task` tools, called them over the same runtime,
+  and stored conversation history in memory.
+
+That is the core lifecycle: services provide capability, agents use the
+capability, and the same runtime can later put the interaction behind a flow.
+
+## 5. Make it a workflow when the path is event-driven
+
+Once the prompt should run because something happened rather than because a
+human typed a message, move the handoff into a flow:
+
+```go
+flow := micro.NewFlow("task-triage",
+	micro.FlowTrigger("tasks.created"),
+	micro.FlowPrompt("Review this new task and decide the next action: {{.Data}}"),
+	micro.FlowProvider("anthropic"),
+	micro.FlowAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
+)
+```
+
+Use flows for deterministic triggers and long-running orchestration; keep the
+agent for judgment, tool use, and handoffs when the path is not known up front.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| The agent says it cannot access tasks. | Confirm the agent was created with `micro.AgentServices("task")` and that `micro agent list` shows `assistant`. |
+| Tool calls use the wrong fields. | Add or improve doc comments and `@example` tags on the service methods. |
+| Plain service calls work but chat fails. | Check that your provider key is exported in the shell that runs `micro run`. |
+| You need a no-secret reference path. | Run `make harness` from the Go Micro repository; it exercises the services → agents → workflows lifecycle with a mock provider. |
+
+## Next steps
+
+- Read the [0→hero reference path](zero-to-hero.html) for the CI-verified
+  lifecycle contract.
+- Run [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate)
+  to see planning and delegation across agents.
+- Read [Agents and Workflows](agents-and-workflows.html) when you are ready to
+  compose agents behind durable flows.

internal/website/docs/index.md

@@ -23,6 +23,7 @@ about the framework.
 ## Contents
 
 - [Getting Started](getting-started.html)
+- [Your First Agent](guides/your-first-agent.html) - Build a service-backed agent end to end
 - [MCP & AI Agents](mcp.html) - Turn services into AI-callable tools with the Model Context Protocol
 - [CLI & Gateway Guide](guides/cli-gateway.html) - Development vs Production modes
 - [Quick Start](quickstart.html)
@@ -44,6 +45,7 @@ about the framework.
 
 ## AI & Agents
 
+- [Your First Agent](guides/your-first-agent.html) - Build a service-backed agent end to end
 - [Building AI-Native Services](guides/ai-native-services.html) - End-to-end tutorial for MCP-enabled services
 - [MCP Security Guide](guides/mcp-security.html) - Auth, scopes, rate limiting, and audit logging
 - [Tool Description Best Practices](guides/tool-descriptions.html) - Writing docs that make agents effective

internal/website/docs/quickstart.md

@@ -13,11 +13,9 @@ curl -fsSL https://go-micro.dev/install.sh | sh
 Or, if you have Go and prefer to build from source:
 
 ```bash
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
-> **Note:** Use `@v6` (not `@latest`) — it resolves to the newest `v6.x.x` release. Plain `@latest` can currently resolve to a stale pre-rename tag through the public module proxy and fail with a "version constraints conflict"; `@v6` avoids that. To pin an exact version use e.g. `@v6.2.0` (see [releases](https://github.com/micro/go-micro/releases)).
-
 ## Create Your First Service
 
 ```bash

internal/website/docs/server.md

@@ -28,11 +28,9 @@ For local development, use [`micro run`](guides/micro-run.html) instead.
 Install the CLI which includes the server command:
 
 ```bash
-go install go-micro.dev/v6/cmd/micro@v6
+go install go-micro.dev/v6/cmd/micro@latest
 ```
 
-> **Note:** Use a specific version instead of `@latest` to avoid module path conflicts. See [releases](https://github.com/micro/go-micro/releases) for the latest version.
-
 ## Run
 
 Start the server: