docs(readme): lead with the demo, declutter the front door - #4895
Conversation
The README buried its best asset — the micro run --prompt transcript, including mid-conversation service generation — under an 11-step on-ramp and four paragraphs of internal CI make-targets, and put monetization sections above the first code sample. Restructure for a first-time visitor while keeping every CI-guarded wayfinding contract intact: - New "See it" hero right after the Overview: the condensed --prompt transcript with the mid-chat shipping-service generation moment. - Quick Start decluttered: install → no-key start → on-ramp → prompt generation, with the harness make-targets consolidated into one line in Docs (install-smoke, inner-loop, zero-to-hero-transcript, harness). - First agent on-ramp compressed from 11 steps to 4, preserving every canonical wayfinding marker and their required order. - Community and Commercial Support moved below the value demonstration; sponsor logos stay near the top. - Autonomous improvement loop tightened and moved out of Quick Start, now leading with "Go Micro maintains itself". - internal/demo/: VHS tapes for a reproducible quick-start GIF (first-run.tape, no key; make demo-gif) and the keyed hero demo (prompt-demo.tape, manual), with recording/embedding instructions. Verified: the zero-to-hero-ci docs harness and cmd/micro wayfinding tests pass unchanged.
There was a problem hiding this comment.
Pull request overview
Reworks the repository “front door” by moving the most compelling micro run --prompt demo transcript to the top of the README, simplifying the Quick Start/on-ramp flow, and adding reproducible terminal demo assets (VHS tapes) plus a Makefile target to record a quick-start GIF.
Changes:
- Restructures
README.mdto lead with a condensed “See it” demo transcript and declutters the Quick Start + first-agent on-ramp while keeping CI wayfinding contracts referenced. - Adds
internal/demo/VHS tapes + documentation for recording/embedding demo GIFs. - Adds
make demo-gifto record the no-key quick-start demo.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Reorders sections to surface the demo early and streamlines the getting-started path while preserving wayfinding references. |
| Makefile | Adds demo-gif target for recording the README quick-start GIF. |
| internal/demo/README.md | Documents demo tapes, recording steps, and embedding guidance. |
| internal/demo/prompt-demo.tape | Adds a manually-recorded “hero” prompt demo tape (keyed, timing-dependent). |
| internal/demo/first-run.tape | Adds a reproducible no-key quick-start tape for recording a GIF. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # Record the README quick-start demo GIF with VHS (no provider key needed). | ||
| # See internal/demo/README.md for the keyed hero demo (prompt-demo.tape). | ||
| demo-gif: | ||
| @command -v vhs >/dev/null || { echo "vhs not found — install with: go install github.com/charmbracelet/vhs@latest (needs ttyd + ffmpeg)"; exit 1; } | ||
| vhs internal/demo/first-run.tape | ||
|
|
| Type "micro run -d &" | ||
| Enter | ||
| Sleep 8s | ||
|
|
||
| Type `curl -s -X POST localhost:8080/api/helloworld/Helloworld.Call -H 'Content-Type: application/json' -d '{"name":"World"}'` | ||
| Enter | ||
| Sleep 4s | ||
|
|
||
| Hide | ||
| Type "kill %1" | ||
| Enter |
|
|
||
| ```bash | ||
| go install github.com/charmbracelet/vhs@latest | ||
| make demo-gif # records first-run.gif (no key needed) |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 87c6378f5b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Tool calls stream: project_Project_Create, task_Task_Create x3 | ||
| Sleep 30s | ||
|
|
||
| Type "I need to track shipping. Create a shipment for order 123 to London." |
There was a problem hiding this comment.
In this micro run --prompt session, the interactive REPL is runConsole, which exposes only discovered service endpoints and explicitly instructs the model to say when a capability is missing; micro_generate_service is wired only into micro chat. Consequently, this shipping request cannot produce the generation sequence the tape is meant to record. Start a micro chat session for this portion or add the generation tool to the micro run console.
Useful? React with 👍 / 👎.
| Set TypingSpeed 40ms | ||
| Set Padding 12 | ||
|
|
||
| Type "micro new helloworld" |
There was a problem hiding this comment.
When make demo-gif is run as documented from the repository root, this command creates helloworld/ directly in the worktree and the tape never removes it. The next recording then prints helloworld already exists and proceeds using stale generated code, so the supposedly reproducible target both pollutes the checkout and records a failed scaffold step. Run the shell commands in a temporary directory and copy only the GIF back to internal/demo.
Useful? React with 👍 / 👎.
Why
Clean-slate read of the README as a first-time visitor: the best asset — the
micro run --prompttranscript, including an agent generating a new service mid-conversation — was buried at ~line 200, under an 11-step on-ramp and four paragraphs of internal CImaketargets, with monetization sections above the first code sample. The substance is strong; the front door was hiding it.Changes
README restructure (every CI-guarded wayfinding contract preserved):
--prompttranscript with the mid-chat shipping-service generation moment — the wow in the first screen.make-target paragraphs are consolidated into one line at the bottom of Docs (install-smoke,inner-loop,zero-to-hero-transcript,harnessall still referenced).micro agent demo/quickcheck/preflight/doctor,micro examples,micro zero-to-hero,micro chat,micro inspect agent <name>, all guide links,examples/first-agent,examples/support,examples/INDEX.md,make docs-wayfinding) and their required order (no-secret → first-agent → debugging → 0→hero).Demo tapes (
internal/demo/):first-run.tape— reproducible no-key quick-start GIF (VHS);make demo-gifrecords it. Uses the new loopback-no-auth behavior, so the curl needs no token.prompt-demo.tape— the keyed hero demo (manual recording; live-provider timing).internal/demo/README.md— recording + embedding instructions (embed at the top of the README once recorded).Verification
go test ./internal/harness/zero-to-hero-ci/ -count=1— the full docs/wayfinding harness passes unchanged (ordered Quick Start markers, on-ramp link order, link-target resolution, examples lifecycle maps).go test ./cmd/micro -count=1— CLI wayfinding contracts pass.Follow-ups (not in this PR)
first-run.gif(make demo-gif, needs vhs/ttyd/ffmpeg) and the keyedprompt-demo.gif, then embed at the top of the README + website homepage.ai/*first, so the table stays truthful).🤖 Generated with Claude Code
Generated by Claude Code