docs: refresh planner priorities for 4085

.github/loop/PRIORITIES.md

@@ -21,7 +21,7 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Add a one-command 0→hero demo entrypoint** ([#4097](https://github.com/micro/go-micro/issues/4097)) — the first-agent, install, debugging, and architecture wayfinding have landed, but the adoption path still asks newcomers to translate docs into several commands before they see the whole services → agents → workflows lifecycle. Add a discoverable `micro` entrypoint that either runs the maintained provider-free 0→hero flow or prints exact commands for it, link it from the first-agent docs, and guard the CLI/docs boundary with focused tests.
+1. **Promote agent doctor in the first-agent debug loop** ([#4086](https://github.com/micro/go-micro/issues/4086)) — install troubleshooting and preflight now cover the before-run adoption seams; next close the after-run recovery seam for newcomers whose first agent starts but chat, gateway, registration, provider settings, or run history misbehave. Link `micro agent doctor` from the first-agent and debugging path, distinguish it from install troubleshooting and `micro agent preflight`, and add a focused CLI/docs harness assertion so the scaffold → run → chat → inspect recovery checkpoint stays discoverable.
 
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

cmd/micro/cli/agent/agent.go

@@ -33,10 +33,9 @@ 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  # before micro run: prerequisites
+  micro agent preflight
   micro run
   micro chat
-  micro agent doctor     # after micro run: chat/gateway/inspect recovery
   micro inspect agent <name>`
 
 func init() {
@@ -81,7 +80,7 @@ for live-provider chat and inspect/debugging.`,
 			},
 			{
 				Name:  "doctor",
-				Usage: "Diagnose chat, gateway, registration, provider, and inspect recovery after micro run",
+				Usage: "Diagnose chat 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

@@ -40,10 +40,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  # before micro run: prerequisites
+       micro agent preflight
        micro run
        micro chat
-       micro agent doctor     # after micro run: chat/gateway/inspect recovery
+       micro agent doctor
 
   4. Debugging your agent
      https://go-micro.dev/docs/guides/debugging-agents.html

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  # before micro run: prerequisites",
+		"micro agent preflight",
 		"micro run",
 		"micro chat",
-		"micro agent doctor     # after micro run: chat/gateway/inspect recovery",
+		"micro agent doctor",
 		"micro inspect agent",
 	} {
 		if !strings.Contains(out.String(), want) {
@@ -79,13 +79,6 @@ 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 {
@@ -95,9 +88,8 @@ 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  # before micro run: prerequisites",
+		"micro agent preflight",
 		"micro chat",
-		"micro agent doctor     # after micro run: chat/gateway/inspect recovery",
 		"micro inspect agent <name>",
 		"your-first-agent.html",
 		"debugging-agents.html",

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

@@ -76,41 +76,6 @@ 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 {

internal/website/docs/architecture.md

@@ -2,124 +2,75 @@
 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;" />
 
-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.
+An overview of the Go Micro architecture.
 
-## Lifecycle map
+## Overview
 
-```text
-Services  →  Agents  →  Workflows
-handlers     model loop  durable orchestration
-registry     memory      triggers and ordered steps
-RPC tools    guardrails   agent dispatch
-```
+Go Micro abstracts away the details of distributed systems. Here are the main features.
 
-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.
+- **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.
 
-## Service substrate
+- **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.
 
-Go Micro's service framework supplies the distributed-systems base every agent
-needs:
+- **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.
 
-- **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.
+- **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.
 
-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.
+- **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.
 
-## Agent harness
+- **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.
 
-Agents compose the service substrate with the AI-specific packages:
+- **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.
 
-- **`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.
+- **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.
 
-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.
+- **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.
 
-## Workflows
+## Design
 
-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.
+We will share more on architecture soon
 
 ## Related
 
-- [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
+- [ADR Index](architecture/index.md)
 - [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/guides/debugging-agents.md

@@ -17,21 +17,9 @@ 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.
-
-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.
+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.
 
 ## 1. Reproduce one small turn
 

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

@@ -53,11 +53,7 @@ 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. 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
-```
+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.
 
 ## 1. Create a workspace