feat(summer): help, examples and hints for every tool command

- build runs go build under a spinner on a terminal and ends with
  'Built bin/<name> in <time>'; make:* print 'Created <path>' per file
- make:*, plugin:add, new, parity:*, docs:build, docs:sync and every
  delegate get long help and examples; delegates note that global options
  pass through to the application binary
- make:* failures (no summer.yaml, invalid plugin ID or name, existing
  artifact, unknown plugin) explain themselves and suggest a command
- docs:build and docs:sync return bonfire.Reported after the problem list
- TestCommandsDocumented covers the tool commands too
- docs: Upgrading to 0.4, delegates and global options, make: results and
  hints, the checklist for a finished command

cmd/summer/docs.go

@@ -2,7 +2,7 @@ package main
 
 import (
 	"context"
-	"errors"
+	"fmt"
 	"os"
 	"os/signal"
 	"sync"
@@ -24,6 +24,17 @@ func docsBuildCommand() bonfire.Command {
 	return bonfire.Command{
 		Name:        "docs:build",
 		Description: "Build the documentation site",
+		Long: `Checks every page under docs/ and every module README, then writes the static
+site to site/ (or --out): HTML pages, a raw .md copy of each page, llms.txt,
+llms-full.txt and the search index. It fails, writing nothing, when a page
+names an identifier that does not exist, links to a missing page or anchor,
+shows a command neither summer nor an application binary has, or has a src=
+code block that differs from its source. --check only reports. Run it from
+the framework root.`,
+		Examples: []bonfire.Example{
+			{Command: "docs:build --check", Description: "Check the docs and write nothing"},
+			{Command: "docs:build --base-url /docs/ --out /tmp/site", Description: "Build the site for /docs/ into /tmp/site"},
+		},
 		Flags: []bonfire.Flag{
 			{Name: "root", Description: "Repository root; src= paths and modules/ resolve against it", Default: "."},
 			{Name: "src", Description: "Docs source directory (default <root>/docs)"},
@@ -63,6 +74,14 @@ func docsSyncCommand() bonfire.Command {
 	return bonfire.Command{
 		Name:        "docs:sync",
 		Description: "Rewrite src= code blocks from their sources",
+		Long: `Rewrites every code block that has a src= reference with the current text of
+its source (a file, or a function, test or example in it), so the docs show
+what the code does. Run it after changing code a page shows; docs:build
+--check fails until you do.`,
+		Examples: []bonfire.Example{
+			{Command: "docs:sync", Description: "Refresh every src= block of the docs in this repository"},
+			{Command: "docs:sync --root ../summercms.go", Description: "Refresh the docs of another checkout"},
+		},
 		Flags: []bonfire.Flag{
 			{Name: "root", Description: "Repository root; src= paths resolve against it", Default: "."},
 			{Name: "src", Description: "Docs source directory (default <root>/docs)"},
@@ -174,11 +193,11 @@ func docsCommands() *docsite.Commands {
 }
 
 // reportDocsProblems prints one line per problem and a summary, and returns
-// a short error so the binary exits 1.
+// a Reported error, so the binary exits 1 without repeating the list.
 func reportDocsProblems(out bonfire.Output, cmd string, problems []docsite.Problem) error {
 	for _, p := range problems {
 		out.Printf("%s\n", p)
 	}
 	out.Printf("%s: %d problems, nothing written\n", cmd, len(problems))
-	return errors.New(cmd + " failed")
+	return bonfire.Reported(fmt.Errorf("%s failed", cmd))
 }