feat(11.1-01): verify src= code blocks and add summer docs:sync

- src= fences name a file, a Go declaration or Example body, or a docs:start region
- confinement: relative clean paths inside the root, no dotfiles or .env,
  no nested go.mod modules, Examples need // Output:, test regions must run
- a drifted or missing snippet is a problem, so docs:build writes nothing
- docs:sync rewrites drifted fence bodies in place
- fences render in figure.code with a source caption; .md fences keep only the language
- bonfire ExampleCall is the first verified example, shown in setup/installation

cmd/summer/docs.go

@@ -45,6 +45,32 @@ func docsBuildCommand() bonfire.Command {
 	}
 }
 
+func docsSyncCommand() bonfire.Command {
+	return bonfire.Command{
+		Name:        "docs:sync",
+		Description: "Rewrite src= code blocks from their sources",
+		Flags: []bonfire.Flag{
+			{Name: "root", Description: "Repository root; src= paths resolve against it", Default: "."},
+			{Name: "src", Description: "Docs source directory (default <root>/docs)"},
+		},
+		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
+			result, problems, err := docsite.Sync(docsOptions(in))
+			if err != nil {
+				return err
+			}
+			if len(problems) > 0 {
+				return reportDocsProblems(out, "docs:sync", problems)
+			}
+			if result.Snippets == 0 {
+				out.Printf("docs:sync: all snippets up to date\n")
+				return nil
+			}
+			out.Printf("docs:sync: updated %d snippets in %d files\n", result.Snippets, result.Files)
+			return nil
+		},
+	}
+}
+
 func docsOptions(in bonfire.Input) docsite.Options {
 	var opts docsite.Options
 	opts.Root, _ = in.Flag("root")

cmd/summer/main.go

@@ -47,6 +47,7 @@ func toolCommands() []bonfire.Command {
 		delegateScheduleRunCommand(),
 		delegateCommand("queue:clear", "Clear pending queued jobs in the app binary"),
 		docsBuildCommand(),
+		docsSyncCommand(),
 	}
 }
 

cmd/summer/main_test.go

@@ -19,7 +19,7 @@ func TestToolCommandNames(t *testing.T) {
 	for _, c := range toolCommands() {
 		names = append(names, c.Name)
 	}
-	for _, want := range []string{"build", "make:plugin", "make:model", "make:migration", "make:command", "make:job", "make:admin-controller", "plugin:add", "dev", "migrate", "migrate:rollback", "migrate:status", "serve", "queue:work", "queue:clear", "schedule:run", "parity:broadcasts", "docs:build"} {
+	for _, want := range []string{"build", "make:plugin", "make:model", "make:migration", "make:command", "make:job", "make:admin-controller", "plugin:add", "dev", "migrate", "migrate:rollback", "migrate:status", "serve", "queue:work", "queue:clear", "schedule:run", "parity:broadcasts", "docs:build", "docs:sync"} {
 		if !slices.Contains(names, want) {
 			t.Fatalf("missing %s in %v", want, names)
 		}
@@ -35,6 +35,7 @@ func TestToolCommandNames(t *testing.T) {
 		"schedule:run":          {"--once"},
 		"parity:broadcasts":     {"--flow", "--step", "--ids", "127.0.0.1:8424"},
 		"docs:build":            {"--out", "--src", "--root", "--base-url", "--check"},
+		"docs:sync":             {"--src", "--root"},
 	}
 	for cmd, wants := range helpWants {
 		var buf bytes.Buffer