Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Codex
|
b21f8a47aa |
@@ -21,7 +21,8 @@ changes, architectural rewrites. Those go to the human.
|
||||
|
||||
## Work queue (ranked)
|
||||
|
||||
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.
|
||||
1. **Keep website quickstart on the first-agent on-ramp** ([#4071](https://github.com/micro/go-micro/issues/4071)) — the README, Getting Started guide, docs index, examples map, CLI docs, and zero-to-hero guide now tell the provider-free first-agent story in order; the website Quick Start page still trails that canonical path by omitting some wayfinding anchors (`micro agent demo`, the no-secret transcript, debugging/inspect). Update the page and extend the focused docs harness so quickstart drift fails fast. This keeps developer adoption weighted alongside hardening instead of letting the queue become purely internal.
|
||||
2. **Add install troubleshooting to the first-agent on-ramp** ([#4077](https://github.com/micro/go-micro/issues/4077)) — after the quickstart page is aligned, close the next 0→1 adoption seam: install verification and recovery before a newcomer reaches `micro new` or `micro agent demo`. Link a focused install troubleshooting path from the canonical on-ramp pages, cover binary installer versus `go install`, PATH/version checks, and the no-secret smoke path, then add a docs harness assertion so the install-recovery link cannot drift out of the first-agent journey.
|
||||
|
||||
_Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
|
||||
architecture-review pass._
|
||||
|
||||
@@ -50,8 +50,6 @@ 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:
|
||||
@@ -89,17 +87,16 @@ make harness
|
||||
After install and the first `micro new`/`micro run` smoke check, take the
|
||||
walkable agent path in this order:
|
||||
|
||||
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. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
|
||||
4. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
|
||||
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
|
||||
maintained support agent with a mock model and see services → agents → workflows succeed without a key.
|
||||
5. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
|
||||
4. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
|
||||
service-backed agent and talk to it with `micro chat`.
|
||||
6. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
|
||||
5. [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.
|
||||
7. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
|
||||
6. [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.
|
||||
|
||||
|
||||
@@ -89,7 +89,6 @@ 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",
|
||||
"internal/website/docs/guides/no-secret-first-agent.md",
|
||||
"internal/website/docs/guides/your-first-agent.md",
|
||||
@@ -132,7 +131,6 @@ 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",
|
||||
"guides/no-secret-first-agent.html",
|
||||
"guides/your-first-agent.html",
|
||||
@@ -332,7 +330,6 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
file: filepath.Join(root, "README.md"),
|
||||
section: "## Quick Start",
|
||||
want: []string{
|
||||
"install troubleshooting guide",
|
||||
"### Fastest start — no API key",
|
||||
"micro new helloworld",
|
||||
"micro run",
|
||||
@@ -357,9 +354,8 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
{
|
||||
name: "website getting started",
|
||||
file: filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
|
||||
section: "Install troubleshooting",
|
||||
section: "## Quick Start: Scaffold, Run, Call",
|
||||
want: []string{
|
||||
"Install troubleshooting",
|
||||
"## Quick Start: Scaffold, Run, Call",
|
||||
"micro new helloworld",
|
||||
"micro run",
|
||||
@@ -369,21 +365,6 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
"## 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",
|
||||
"guides/no-secret-first-agent.html",
|
||||
"guides/debugging-agents.html",
|
||||
"guides/zero-to-hero.html",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, check := range checks {
|
||||
|
||||
@@ -3,8 +3,6 @@ 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
|
||||
@@ -82,7 +80,6 @@ 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
|
||||
|
||||
@@ -29,8 +29,6 @@ curl -fsSL https://go-micro.dev/install.sh | sh
|
||||
go install go-micro.dev/v6/cmd/micro@latest
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
@@ -55,13 +53,12 @@ That install → scaffold → run → call loop is the 0→1 contract. It requir
|
||||
|
||||
After this quick start, follow the agent path in order:
|
||||
|
||||
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. [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.
|
||||
4. [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.
|
||||
5. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
|
||||
6. [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.
|
||||
7. [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. `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`.
|
||||
|
||||
## Write a Service
|
||||
|
||||
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -16,8 +16,6 @@ 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
|
||||
@@ -41,13 +39,10 @@ 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. **[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. **[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.
|
||||
4. **[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.
|
||||
5. **[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.
|
||||
6. **[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.
|
||||
7. **[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. **[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.
|
||||
|
||||
After that first-agent path, branch out to:
|
||||
|
||||
@@ -118,3 +113,4 @@ 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user