fix(docs): clear zensical sync output

cmd/docs/cmd_sync.go

@@ -140,9 +140,7 @@ func runPHPSync(reg *repos.Registry, basePath string, outputDir string, dryRun b
 		repoOutDir := filepath.Join(outputDir, outName)
 
 		// Clear existing directory (recursively)
-		_ = io.Local.DeleteAll(repoOutDir)
-
-		if err := io.Local.EnsureDir(repoOutDir); err != nil {
+		if err := resetOutputDir(repoOutDir); err != nil {
 			cli.Print("  %s %s: %s\n", errorStyle.Render("✗"), info.Name, err)
 			continue
 		}
@@ -275,6 +273,7 @@ func runZensicalSync(reg *repos.Registry, basePath string, outputDir string, dry
 
 	cli.Blank()
 	var synced int
+repoLoop:
 	for _, info := range docsInfo {
 		section, folder := zensicalOutputName(info.Name)
 
@@ -283,6 +282,11 @@ func runZensicalSync(reg *repos.Registry, basePath string, outputDir string, dry
 			destDir = filepath.Join(destDir, folder)
 		}
 
+		if err := resetOutputDir(destDir); err != nil {
+			cli.Print("  %s %s: %s\n", errorStyle.Render("✗"), info.Name, err)
+			continue
+		}
+
 		weight := 10
 		docsDir := filepath.Join(info.Path, "docs")
 		for _, f := range info.DocsFiles {
@@ -304,6 +308,10 @@ func runZensicalSync(reg *repos.Registry, basePath string, outputDir string, dry
 		if len(info.KBFiles) > 0 {
 			suffix := strings.TrimPrefix(info.Name, "go-")
 			kbDestDir := filepath.Join(outputDir, "kb", suffix)
+			if err := resetOutputDir(kbDestDir); err != nil {
+				cli.Print("  %s KB: %s\n", errorStyle.Render("✗"), err)
+				continue repoLoop
+			}
 			kbDir := filepath.Join(info.Path, "KB")
 			kbWeight := 10
 			for _, f := range info.KBFiles {
@@ -331,6 +339,14 @@ func copyZensicalReadme(src, destDir string) error {
 	return copyWithFrontMatter(src, dst, 1)
 }
 
+// resetOutputDir clears and recreates a target directory before copying files into it.
+func resetOutputDir(dir string) error {
+	if err := io.Local.DeleteAll(dir); err != nil {
+		return err
+	}
+	return io.Local.EnsureDir(dir)
+}
+
 // goHelpOutputName maps repo name to output folder name for go-help.
 func goHelpOutputName(repoName string) string {
 	if repoName == "core" {
@@ -393,9 +409,7 @@ func runGoHelpSync(reg *repos.Registry, basePath string, outputDir string, dryRu
 		repoOutDir := filepath.Join(outputDir, outName)
 
 		// Clear existing directory
-		_ = io.Local.DeleteAll(repoOutDir)
-
-		if err := io.Local.EnsureDir(repoOutDir); err != nil {
+		if err := resetOutputDir(repoOutDir); err != nil {
 			cli.Print("  %s %s: %s\n", errorStyle.Render("✗"), info.Name, err)
 			continue
 		}

cmd/docs/cmd_sync_test.go

@@ -37,3 +37,28 @@ func TestCopyZensicalReadme_Good(t *testing.T) {
 		t.Fatalf("expected README body to be preserved, got: %q", content)
 	}
 }
+
+func TestResetOutputDir_ClearsExistingFiles(t *testing.T) {
+	dir := t.TempDir()
+
+	stale := filepath.Join(dir, "stale.md")
+	if err := os.WriteFile(stale, []byte("old content"), 0o644); err != nil {
+		t.Fatalf("write stale file: %v", err)
+	}
+
+	if err := resetOutputDir(dir); err != nil {
+		t.Fatalf("reset output dir: %v", err)
+	}
+
+	if _, err := os.Stat(stale); !os.IsNotExist(err) {
+		t.Fatalf("expected stale file to be removed, got err=%v", err)
+	}
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("stat output dir: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatalf("expected output dir to exist as a directory")
+	}
+}