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")