add-guide-command

name	add-guide-command
description	Add a `guide` command to an agent-first CLI that embeds the full operator/agent manual (model, loop, concepts, commands, examples, gotchas) in the binary. Use when asked to "add a guide command", "embed the agent skill", "make the CLI self-documenting", or to teach agents how to drive a tool without external docs.

Add a guide command (cli-guide-spec convention)

Give a CLI a guide subcommand that bakes the complete mental model into the binary — so an agent (or human) with only the binary learns the tool end-to-end in one call, no external docs, no network fetch. Full norms in PROTOCOL.md; full how-to in RECIPE.md. This skill is the checklist.

Decide the shape first

• JSON agent-skill flavor (RECOMMENDED for agent-first tools): structured JSON — one_liner, model, loop, concepts, commands, examples, gotchas. An agent parses it; --human renders markdown.
• Markdown flavor (simpler, human-readable): a single markdown string is the whole guide. Body: {"guide": "<markdown>", "version": "..."}.
• Does the tool run an HTTP server? If yes, also add GET /guide + GET /llms.txt (step 3). If it's a pure CLI, skip step 3.

The four edits

1. Write the guide content as an embedded function (RECIPE.md step 1): guideData() returns the structured object (or guideText() returns the markdown string). It MUST be in-source / //go:embed-ed — never a runtime URL fetch. Include version and see_also: ["<tool> help-json"].

2. Wire the CLI command (RECIPE.md step 2): add guide to the command dispatch. JSON by default; --human prints markdown. Advertise guide in help and help-json so an agent discovers it.

3. HTTP endpoints (only if the tool runs a server, RECIPE.md step 3):

   • GET /guide → the same JSON body, Content-Type: application/json, no auth.
   • GET /llms.txt → a short text breadcrumb (Content-Type: text/plain) that points at /guide and names the CLI command. This is the agent's front door.
   • If you ship two binaries (full + cloud) and only the full one has a server, put the HTTP handlers in a //go:build local file; keep guideData()/cmdGuide() in a no-tag file so both binaries get the CLI command.

4. Document + bump: add a short "Guide" section to the README (name the command, the HTTP endpoints if any); add guide to the command catalog / docs-sync tests if they exist; bump the version.

Verify before you're done

# CLI: JSON by default
myapp guide | jq '.guide.one_liner'        # -> the elevator pitch
# CLI: human markdown
myapp guide --human | head                 # -> "# myapp guide — ..."
# HTTP (if the tool runs a server)
curl -s http://localhost:PORT/guide | jq '.guide.loop'
curl -s http://localhost:PORT/llms.txt     # -> the short breadcrumb
# discovery: help advertises guide
myapp help | grep guide                    # -> guide  Print the embedded agent skill

Gotchas

• Embed, don't fetch. The guide MUST be in the binary. A runtime URL fetch defeats the purpose (offline machines, air-gapped workers). Use //go:embed or an in-source constant.
• guide is not help. Don't duplicate the command catalog in the guide; point at help-json from see_also. The guide is the model and the loop; help is the flag list. A tool SHOULD have both.
• Keep docs-sync tests aligned. If you have a CommandCatalog ↔ help-json ↔ README table invariant, add guide to all three in the same commit or the tests fail.
• Split build-tagged HTTP handlers if only one binary distribution runs a server.