Merge pull request 'chore(release): v0.15.0 — files folder-ops + docpipe (#8)' (#9) from chore/release-v0.15.0#8 into main

feat(docs): Ghostscript PDF optimize for OO

.github/workflows/test.yml

@@ -10,6 +10,51 @@ permissions:
   contents: read
 
 jobs:
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Compute scan range (diff of new commits only)
+        id: range
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+            RANGE="${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}"
+          else
+            BEFORE="${{ github.event.before }}"
+            if [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+              RANGE="$(git rev-list --max-parents=0 HEAD | tail -1)..$GITHUB_SHA"
+            else
+              RANGE="$BEFORE..$GITHUB_SHA"
+            fi
+          fi
+          echo "RANGE=$RANGE" >> "$GITHUB_ENV"
+          echo "Scanning range: $RANGE"
+
+      # Install the gitleaks binary instead of a docker action: the
+      # docker://zricethezav/gitleaks action hardcodes /github/workspace,
+      # which does not exist on the Gitea (act) runner. $GITHUB_WORKSPACE is
+      # the checkout dir on BOTH runners (GitHub and Gitea act). Mirrors the
+      # fix applied to 2dph (issue #142).
+      - name: Gitleaks (diff-only, fail on leak)
+        env:
+          GITLEAKS_RANGE: ${{ env.RANGE }}
+        run: |
+          set -euo pipefail
+          curl -fsSLo /tmp/gitleaks.tar.gz \
+            https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          chmod +x /tmp/gitleaks
+          /tmp/gitleaks detect \
+            --source "$GITHUB_WORKSPACE" \
+            --log-opts="$GITLEAKS_RANGE" \
+            --redact \
+            --verbose
+
   test:
     name: Test (Go ${{ matrix.go }})
     runs-on: ubuntu-latest

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.0"
+  ".": "0.15.0"
 }

AGENTS.md

@@ -28,6 +28,7 @@ Canonical Go client for OnlyOffice Workspace (Projects + Calendar + CRM) and the
 - Prefer `ResponseObject` / `postFormObject` / `putFormObject` / `deleteObject` over hand-rolled `json.Unmarshal(responseField(...))` blocks — they exist for DRY, use them.
 - Domain split is by file, **not** by subpackage. Don't introduce `internal/` or `pkg/*` subpackages inside the library — it flattens the `*Client` call surface for a reason.
 - CLI commands follow **subject → verb** structure (`oo <subject> <verb>`), never `oo <verb>-<subject>`. Add new commands to the existing subject file if one fits; create a new `cmd/oo/<subject>.go` for a genuinely new domain.
+- **Documents for agents:** prefer Markdown in git; OnlyOffice UI is weak for `.md`/`.txt`. Use `oo docs put-md` (md→docx) and `oo docs put-txt` (txt→docx, preserves line breaks). `oo projects files dedupe PROJECT_ID` reports/removes duplicate stem|ext copies (`--apply`, `--cross`).
 - Every table output goes through `printTable(headers, rows)`; every single-object through `printObject(v)`. Do not `fmt.Println` rows ad-hoc or the `--output json` flag breaks for that command.
 - No secrets in the repo; use `.env` (gitignored). Commit `.env.example` only.
 - Follow SemVer on tags; this repo is tagged at GitHub under `git@github.com:eSlider/go-onlyoffice.git`.

CHANGELOG.md

@@ -16,6 +16,101 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 * Document that invoice→deal must be set at create (`update --opportunity` often HTTP 400)
 
+## [0.15.0](https://github.com/eSlider/go-onlyoffice/compare/v0.14.0...v0.15.0) (2026-08-29)
+
+### Features
+
+* **files:** `ListFolder`, `CreateFolder`, `MoveFiles`, `UploadToFolder` — Documents folder helpers for OO Documents ingestion ([6ea2fba](https://github.com/eSlider/go-onlyoffice/commit/6ea2fba))
+* **files:** dedupe by stem|ext (`files_stem.go`) + `oo projects files dedupe` ([ac06d86](https://github.com/eSlider/go-onlyoffice/commit/ac06d86))
+* **docs:** `internal/docpipe` — md↔docx convert, OCR→PDF, hOCR→Markdown via go-hocr, as-md/put-md for agents ([6ea2fba](https://github.com/eSlider/go-onlyoffice/commit/6ea2fba), [a264cbd](https://github.com/eSlider/go-onlyoffice/commit/a264cbd))
+* **docs:** optimize PDF via Ghostscript pdfwrite ([6b3f40e](https://github.com/eSlider/go-onlyoffice/commit/6b3f40e))
+* **security:** gitleaks secret-scan in CI + pre-push/pre-commit hooks ([9ead554](https://github.com/eSlider/go-onlyoffice/commit/9ead554))
+
+### Fixes
+
+* **files:** `DeleteFiles` via per-file DELETE API; `DeleteDavItems` with `Immediately` true ([622dcdb](https://github.com/eSlider/go-onlyoffice/commit/622dcdb), [d9a7adc](https://github.com/eSlider/go-onlyoffice/commit/d9a7adc))
+* **docs:** put-txt preserves line breaks in DOCX; fixed-width extracts in code block; put-md upsert by stem ([309ae44](https://github.com/eSlider/go-onlyoffice/commit/309ae44), [f1739dc](https://github.com/eSlider/go-onlyoffice/commit/f1739dc), [50bd475](https://github.com/eSlider/go-onlyoffice/commit/50bd475))
+* **ci:** point gitleaks at `/github/workspace` in docker action ([2c0df0d](https://github.com/eSlider/go-onlyoffice/commit/2c0df0d))
+
+## [0.14.0](https://github.com/eSlider/go-onlyoffice/compare/v0.13.0...v0.14.0) (2026-08-27)
+
+
+### Features
+
+* **crm:** contact email & person-opportunity indexes, history entity whitelist ([9c450a0](https://github.com/eSlider/go-onlyoffice/commit/9c450a0352c25f12ac16d91062744ab026ffe660))
+* **docs:** hOCR → Markdown via go-hocr ([e531de2](https://github.com/eSlider/go-onlyoffice/commit/e531de280f2c521a7411f75212803649b177db58))
+* **docs:** md↔docx convert, OCR→PDF, as-md/put-md for agents ([6ea2fba](https://github.com/eSlider/go-onlyoffice/commit/6ea2fbadf768d7d85f6c7a49a9bc1050e642bc56))
+* **docs:** md↔docx, OCR→PDF, as-md/put-md ([db9ef12](https://github.com/eSlider/go-onlyoffice/commit/db9ef12ff4096f8aadb557ca128b6edcb503028c))
+* **docs:** oo docs hocr — tesseract hOCR → go-hocr Markdown/YAML ([a264cbd](https://github.com/eSlider/go-onlyoffice/commit/a264cbd61c12be9098c8d16e7c1c1253eb460816))
+* **mail:** oo mails send — SendMail + guard empty-by-id send ([dda2bd3](https://github.com/eSlider/go-onlyoffice/commit/dda2bd3ca5cea6ebb89e1ac02b785b9838727bda))
+* **mail:** oo mails send — SendMail client + guard empty-by-id ([ab7dfbd](https://github.com/eSlider/go-onlyoffice/commit/ab7dfbd8594de5724286e2b460e789f4acb114bc))
+* **security:** secret-scan via gitleaks in CI + pre-push/pre-commit hooks ([#142](https://github.com/eSlider/go-onlyoffice/issues/142)) ([9ead554](https://github.com/eSlider/go-onlyoffice/commit/9ead554f5cc229687d3a27934a023fb1dddaef15))
+
+
+### Bug Fixes
+
+* **ci:** point gitleaks at /github/workspace in docker action ([2c0df0d](https://github.com/eSlider/go-onlyoffice/commit/2c0df0d55fb03555b60481695554d75dceffce48))
+* **docs:** put-md upsert — no duplicate folder files ([2b267d3](https://github.com/eSlider/go-onlyoffice/commit/2b267d36a8086b14a94706468f7e92e9179e62d4))
+* **docs:** put-md upsert by stem to avoid duplicate folder files ([50bd475](https://github.com/eSlider/go-onlyoffice/commit/50bd47570b6430cebde43641a7b1d2f8d54d32f2))
+* **files:** DeleteFiles actually removes files on produktor OO ([a8cb4e9](https://github.com/eSlider/go-onlyoffice/commit/a8cb4e97805226e8af694ec6a64ee3ac6a5e9fdd))
+* **files:** DeleteFiles via per-file DELETE API ([622dcdb](https://github.com/eSlider/go-onlyoffice/commit/622dcdb7bffd49acbea5ef07f5d5d009f44b1358))
+
+
+### Documentation
+
+* **readme:** document oo docs hocr ([70e605b](https://github.com/eSlider/go-onlyoffice/commit/70e605b4ca8ee005e4351b2fc2d2eec081604998))
+* **readme:** document oo docs md↔docx / OCR agent workflow ([239c5ea](https://github.com/eSlider/go-onlyoffice/commit/239c5ea67201e62de6ba067f0e7963c7c9bda188))
+
+## [0.13.0](https://github.com/eSlider/go-onlyoffice/compare/v0.12.0...v0.13.0) (2026-08-27)
+
+
+### Features
+
+* **crm:** contact email & person-opportunity indexes, history entity whitelist ([9c450a0](https://github.com/eSlider/go-onlyoffice/commit/9c450a0352c25f12ac16d91062744ab026ffe660))
+* **docs:** hOCR → Markdown via go-hocr ([e531de2](https://github.com/eSlider/go-onlyoffice/commit/e531de280f2c521a7411f75212803649b177db58))
+* **docs:** md↔docx convert, OCR→PDF, as-md/put-md for agents ([6ea2fba](https://github.com/eSlider/go-onlyoffice/commit/6ea2fbadf768d7d85f6c7a49a9bc1050e642bc56))
+* **docs:** md↔docx, OCR→PDF, as-md/put-md ([db9ef12](https://github.com/eSlider/go-onlyoffice/commit/db9ef12ff4096f8aadb557ca128b6edcb503028c))
+* **docs:** oo docs hocr — tesseract hOCR → go-hocr Markdown/YAML ([a264cbd](https://github.com/eSlider/go-onlyoffice/commit/a264cbd61c12be9098c8d16e7c1c1253eb460816))
+* **mail:** oo mails send — SendMail + guard empty-by-id send ([dda2bd3](https://github.com/eSlider/go-onlyoffice/commit/dda2bd3ca5cea6ebb89e1ac02b785b9838727bda))
+* **mail:** oo mails send — SendMail client + guard empty-by-id ([ab7dfbd](https://github.com/eSlider/go-onlyoffice/commit/ab7dfbd8594de5724286e2b460e789f4acb114bc))
+* **security:** secret-scan via gitleaks in CI + pre-push/pre-commit hooks ([#142](https://github.com/eSlider/go-onlyoffice/issues/142)) ([9ead554](https://github.com/eSlider/go-onlyoffice/commit/9ead554f5cc229687d3a27934a023fb1dddaef15))
+
+
+### Bug Fixes
+
+* **ci:** point gitleaks at /github/workspace in docker action ([2c0df0d](https://github.com/eSlider/go-onlyoffice/commit/2c0df0d55fb03555b60481695554d75dceffce48))
+* **files:** rewrite viewUrl host to API base on download ([ecf34ba](https://github.com/eSlider/go-onlyoffice/commit/ecf34ba51aae77f1626a60795f7329f25d9344e5))
+
+
+### Documentation
+
+* **readme:** document oo docs hocr ([70e605b](https://github.com/eSlider/go-onlyoffice/commit/70e605b4ca8ee005e4351b2fc2d2eec081604998))
+* **readme:** document oo docs md↔docx / OCR agent workflow ([239c5ea](https://github.com/eSlider/go-onlyoffice/commit/239c5ea67201e62de6ba067f0e7963c7c9bda188))
+
+## [0.12.0](https://github.com/eSlider/go-onlyoffice/compare/v0.11.0...v0.12.0) (2026-08-27)
+
+
+### Features
+
+* **crm:** contact email & person-opportunity indexes, history entity whitelist ([9c450a0](https://github.com/eSlider/go-onlyoffice/commit/9c450a0352c25f12ac16d91062744ab026ffe660))
+* **docs:** md↔docx convert, OCR→PDF, as-md/put-md for agents ([6ea2fba](https://github.com/eSlider/go-onlyoffice/commit/6ea2fbadf768d7d85f6c7a49a9bc1050e642bc56))
+* **docs:** md↔docx, OCR→PDF, as-md/put-md ([db9ef12](https://github.com/eSlider/go-onlyoffice/commit/db9ef12ff4096f8aadb557ca128b6edcb503028c))
+* **files:** add WebDAV-oriented Files operations ([ebbd5d5](https://github.com/eSlider/go-onlyoffice/commit/ebbd5d5373abfeca5f160312f201cbd683f55e42))
+* **mail:** oo mails send — SendMail + guard empty-by-id send ([dda2bd3](https://github.com/eSlider/go-onlyoffice/commit/dda2bd3ca5cea6ebb89e1ac02b785b9838727bda))
+* **mail:** oo mails send — SendMail client + guard empty-by-id ([ab7dfbd](https://github.com/eSlider/go-onlyoffice/commit/ab7dfbd8594de5724286e2b460e789f4acb114bc))
+* **security:** secret-scan via gitleaks in CI + pre-push/pre-commit hooks ([#142](https://github.com/eSlider/go-onlyoffice/issues/142)) ([9ead554](https://github.com/eSlider/go-onlyoffice/commit/9ead554f5cc229687d3a27934a023fb1dddaef15))
+
+
+### Bug Fixes
+
+* **ci:** point gitleaks at /github/workspace in docker action ([2c0df0d](https://github.com/eSlider/go-onlyoffice/commit/2c0df0d55fb03555b60481695554d75dceffce48))
+* **files:** rewrite viewUrl host to API base on download ([ecf34ba](https://github.com/eSlider/go-onlyoffice/commit/ecf34ba51aae77f1626a60795f7329f25d9344e5))
+
+
+### Documentation
+
+* **readme:** document oo docs md↔docx / OCR agent workflow ([239c5ea](https://github.com/eSlider/go-onlyoffice/commit/239c5ea67201e62de6ba067f0e7963c7c9bda188))
+
 ## [0.11.0](https://github.com/eSlider/go-onlyoffice/compare/v0.10.0...v0.11.0) (2026-08-18)
 
 

README.md

@@ -607,10 +607,25 @@ go test -tags=integration ./cmd/office/fetch/... ./cmd/office/preview/...
 ```bash
 # Project Documents (files module)
 oo projects files list 33
-oo projects files upload 33 ./notes.md
+oo projects files upload 33 ./notes.docx
-oo projects files download 12345 --to ./copy.md
+oo projects files download 12345 --to ./copy.docx
-oo projects files rename 12345 notes-v2.md
+oo projects files rename 12345 notes-v2.docx
 oo projects files delete 12345
+oo projects files dedupe 7              # dry-run duplicate report
+oo projects files dedupe 7 --apply      # remove older stem|ext copies per folder
+oo projects files dedupe 7 --cross --apply  # cross-folder; keep non-_trash
+
+# Agent document pipeline (md in git ↔ docx in OO; OCR scans)
+oo docs tools
+oo docs convert ./note.md                 # → note.docx
+oo docs convert ./note.docx               # → note.md
+oo docs ocr ./scan.jpg --md ./scan.md     # searchable PDF + markdown
+oo docs hocr ./scan.jpg --lang spa --md ./scan.hocr.md --yaml ./scan.yml
+oo docs put-md 7 ./OO-HONDA-7-INDEX.md --folder 490
+oo docs as-md 2815 --to ./parte.md        # download OO file as MD (OCR if needed)
+oo docs as-md 307 --hocr --lang spa       # OO download via go-hocr structure
+oo projects files put-md 7 ./note.md      # alias
+oo projects files as-md 2815              # alias
 oo tasks files list 208
 oo tasks files upload 208 ./notes.pdf
 oo tasks files detach 208 12345

cmd/oo/docs.go

@@ -0,0 +1,542 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	onlyoffice "github.com/eslider/go-onlyoffice"
+	"github.com/eslider/go-onlyoffice/internal/docpipe"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(docsCmd())
+}
+
+func docsCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "docs",
+		Short: "Local document pipeline: md↔docx, OCR→PDF, extract Markdown",
+		Long: `Agent-friendly conversions (requires pandoc / ocrmypdf / pdftotext on PATH).
+
+OnlyOffice Documents UI is poor for .md/.txt — keep sources in git, store .docx in OO.
+Upload Markdown as DOCX:  oo docs put-md PROJECT_ID file.md
+Upload plain text:        oo docs put-txt PROJECT_ID file.txt  (preserves line breaks)
+Read an OO file as MD:    oo docs as-md FILE_ID
+OCR a scan locally:       oo docs ocr scan.pdf --md out.md
+Structured OCR (hOCR→MD): oo docs hocr scan.jpg --md out.md --yaml out.yml`,
+	}
+	cmd.AddCommand(docsConvertCmd())
+	cmd.AddCommand(docsOptimizeCmd())
+	cmd.AddCommand(docsOCRCmd())
+	cmd.AddCommand(docsHOCRCmd())
+	cmd.AddCommand(docsAsMDCmd())
+	cmd.AddCommand(docsPutMDCmd())
+	cmd.AddCommand(docsPutTxtCmd())
+	cmd.AddCommand(docsToolsCmd())
+	return cmd
+}
+
+func docsToolsCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tools",
+		Short: "Show which converter binaries are on PATH",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			t := docpipe.LookPath()
+			printObject(map[string]any{
+				"pandoc":      strOrNil(t.Pandoc),
+				"ocrmypdf":    strOrNil(t.OCRMyPDF),
+				"pdftotext":   strOrNil(t.PDFToText),
+				"tesseract":   strOrNil(t.Tesseract),
+				"ghostscript": strOrNil(t.Ghostscript),
+			})
+			return nil
+		},
+	}
+}
+
+func strOrNil(s string) any {
+	if s == "" {
+		return nil
+	}
+	return s
+}
+
+func docsConvertCmd() *cobra.Command {
+	var to string
+	cmd := &cobra.Command{
+		Use:   "convert PATH",
+		Short: "Convert a local file with pandoc (md↔docx by default)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			in := args[0]
+			t := docpipe.LookPath()
+			out := to
+			if out == "" {
+				switch docpipe.Ext(in) {
+				case ".md", ".markdown":
+					out = docpipe.SiblingDOCX(in)
+				case ".docx":
+					out = strings.TrimSuffix(in, docpipe.Ext(in)) + ".md"
+				default:
+					return fmt.Errorf("--to required for input type %s", docpipe.Ext(in))
+				}
+			}
+			if err := docpipe.EnsureDir(out); err != nil {
+				return err
+			}
+			if err := t.ConvertFile(in, out); err != nil {
+				return err
+			}
+			printObject(map[string]any{"in": in, "out": out})
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&to, "to", "", "output path (default: sibling .docx or .md)")
+	return cmd
+}
+
+func docsOptimizeCmd() *cobra.Command {
+	var out string
+	cmd := &cobra.Command{
+		Use:   "optimize PDF_PATH",
+		Short: "Rewrite PDF via Ghostscript (PostScript pdfwrite) for OO-friendly size/text",
+		Long: `Use for InDesign/iText PDFs with a good text layer — avoids ocrmypdf invisible
+text overlays that break OnlyOffice DocEditor. Skips OCR; rewrites via gs pdfwrite.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			in := args[0]
+			t := docpipe.LookPath()
+			if out == "" {
+				base := strings.TrimSuffix(filepath.Base(in), filepath.Ext(in))
+				out = filepath.Join(filepath.Dir(in), base+".optimized.pdf")
+			}
+			if err := docpipe.EnsureDir(out); err != nil {
+				return err
+			}
+			chars, _ := t.PDFTextLayerChars(in)
+			if err := t.OptimizePDF(in, out); err != nil {
+				return err
+			}
+			outChars, _ := t.PDFTextLayerChars(out)
+			printObject(map[string]any{
+				"in":              in,
+				"pdf":             out,
+				"text_chars_in":   chars,
+				"text_chars_out":  outChars,
+				"note":            "native text layer preserved; no OCR overlay",
+			})
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&out, "out", "", "output PDF (default: <name>.optimized.pdf)")
+	return cmd
+}
+
+func docsOCRCmd() *cobra.Command {
+	var out, mdOut, lang string
+	var force bool
+	var writeMD bool
+	cmd := &cobra.Command{
+		Use:   "ocr PATH",
+		Short: "OCR image/PDF → searchable PDF (and optional Markdown)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			in := args[0]
+			t := docpipe.LookPath()
+			if out == "" {
+				base := strings.TrimSuffix(filepath.Base(in), filepath.Ext(in))
+				out = filepath.Join(filepath.Dir(in), base+".ocr.pdf")
+			}
+			if err := docpipe.EnsureDir(out); err != nil {
+				return err
+			}
+			if err := t.OCRToPDF(in, out, force, lang); err != nil {
+				return err
+			}
+			res := map[string]any{"in": in, "pdf": out}
+			if writeMD || mdOut != "" {
+				if mdOut == "" {
+					mdOut = strings.TrimSuffix(out, filepath.Ext(out)) + ".md"
+				}
+				text, err := t.ExtractPDFText(out)
+				if err != nil {
+					return err
+				}
+				body := "# " + filepath.Base(in) + "\n\n" + strings.TrimSpace(text) + "\n"
+				if err := os.WriteFile(mdOut, []byte(body), 0o644); err != nil {
+					return err
+				}
+				res["md"] = mdOut
+			}
+			printObject(res)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&out, "out", "", "output searchable PDF (default: <name>.ocr.pdf)")
+	cmd.Flags().StringVar(&mdOut, "md", "", "write Markdown extraction to this path")
+	cmd.Flags().BoolVar(&writeMD, "markdown", false, "also write sibling .md next to OCR PDF")
+	cmd.Flags().StringVar(&lang, "lang", "eng", "OCR language(s) for tesseract/ocrmypdf")
+	cmd.Flags().BoolVar(&force, "force", false, "force OCR even if a text layer exists (default: skip when pdftotext finds enough text)")
+	return cmd
+}
+
+func docsHOCRCmd() *cobra.Command {
+	var mdOut, yamlOut, hocrOut, lang string
+	var dpi int
+	var minConf float32
+	cmd := &cobra.Command{
+		Use:   "hocr PATH",
+		Short: "Tesseract hOCR → structured Markdown/YAML (via go-hocr)",
+		Long: `Runs tesseract with hOCR output, parses with go-hocr, writes Markdown
+(and optional YAML). Better reading order / confidence than plain pdftotext.
+
+For Spanish scans: --lang spa or spa+eng (needs tesseract-ocr-spa / TESSDATA_PREFIX).
+Phone photos: --dpi 200..300.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			in := args[0]
+			t := docpipe.LookPath()
+			dir, err := os.MkdirTemp("", "oo-docs-hocr-*")
+			if err != nil {
+				return err
+			}
+			defer os.RemoveAll(dir)
+
+			res, err := t.ToHOCRMarkdown(in, dir, lang, dpi, minConf)
+			if err != nil {
+				return err
+			}
+			if mdOut == "" {
+				base := strings.TrimSuffix(filepath.Base(in), filepath.Ext(in))
+				mdOut = filepath.Join(filepath.Dir(in), base+".hocr.md")
+			}
+			if err := docpipe.EnsureDir(mdOut); err != nil {
+				return err
+			}
+			if err := os.WriteFile(mdOut, []byte(res.Markdown), 0o644); err != nil {
+				return err
+			}
+			obj := map[string]any{
+				"in":      in,
+				"md":      mdOut,
+				"did_ocr": res.DidOCR,
+			}
+			if hocrOut != "" {
+				if err := docpipe.EnsureDir(hocrOut); err != nil {
+					return err
+				}
+				b, err := os.ReadFile(res.HOCRPath)
+				if err != nil {
+					return err
+				}
+				if err := os.WriteFile(hocrOut, b, 0o644); err != nil {
+					return err
+				}
+				obj["hocr"] = hocrOut
+			} else {
+				obj["hocr_tmp"] = res.HOCRPath
+			}
+			if yamlOut != "" {
+				if err := docpipe.EnsureDir(yamlOut); err != nil {
+					return err
+				}
+				if err := os.WriteFile(yamlOut, []byte(res.YAML), 0o644); err != nil {
+					return err
+				}
+				obj["yaml"] = yamlOut
+			}
+			printObject(obj)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&mdOut, "md", "", "Markdown output (default: <name>.hocr.md)")
+	cmd.Flags().StringVar(&yamlOut, "yaml", "", "also write structured YAML from go-hocr")
+	cmd.Flags().StringVar(&hocrOut, "hocr", "", "also keep raw .hocr file at this path")
+	cmd.Flags().StringVar(&lang, "lang", "eng", "tesseract language(s), e.g. spa+eng")
+	cmd.Flags().IntVar(&dpi, "dpi", 220, "hint DPI for phone photos / scans (0 = tesseract default)")
+	cmd.Flags().Float32Var(&minConf, "min-conf", 0, "drop words with OCR confidence below this (0 = keep all)")
+	return cmd
+}
+
+func docsAsMDCmd() *cobra.Command {
+	var to, lang string
+	var minChars int
+	var uploadOCR bool
+	var useHOCR bool
+	var dpi int
+	var minConf float32
+	cmd := &cobra.Command{
+		Use:   "as-md FILE_ID",
+		Short: "Download an OO Documents file and emit Markdown (OCR PDF/image if needed)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			ctx := cmd.Context()
+			meta, err := c.GetFile(ctx, args[0])
+			if err != nil {
+				return err
+			}
+			title := onlyoffice.FileEntryTitle(meta)
+			dir, err := os.MkdirTemp("", "oo-docs-as-md-*")
+			if err != nil {
+				return err
+			}
+			defer os.RemoveAll(dir)
+
+			local := filepath.Join(dir, onlyoffice.SafeLocalFileName(title))
+			f, err := os.Create(local)
+			if err != nil {
+				return err
+			}
+			if _, err := c.DownloadFile(ctx, args[0], f); err != nil {
+				_ = f.Close()
+				return err
+			}
+			_ = f.Close()
+
+			tools := docpipe.LookPath()
+			var res docpipe.Result
+			if useHOCR {
+				hr, err := tools.ToHOCRMarkdown(local, dir, lang, dpi, minConf)
+				if err != nil {
+					return err
+				}
+				res = docpipe.Result{Markdown: hr.Markdown, DidOCR: hr.DidOCR, Source: hr.Source}
+			} else {
+				res, err = tools.ToMarkdown(local, dir, lang, minChars)
+				if err != nil {
+					return err
+				}
+			}
+			outPath := to
+			if outPath == "" {
+				base := strings.TrimSuffix(onlyoffice.SafeLocalFileName(title), filepath.Ext(onlyoffice.SafeLocalFileName(title)))
+				if base == "" || base == "download" {
+					base = "file-" + args[0]
+				}
+				outPath = base + ".md"
+			}
+			if err := docpipe.EnsureDir(outPath); err != nil {
+				return err
+			}
+			if err := os.WriteFile(outPath, []byte(res.Markdown), 0o644); err != nil {
+				return err
+			}
+
+			obj := map[string]any{
+				"file_id": args[0],
+				"title":   title,
+				"md":      outPath,
+				"did_ocr": res.DidOCR,
+			}
+			if res.OCRPDFPath != "" && uploadOCR {
+				folderID := onlyoffice.FileFolderID(meta)
+				upName := strings.TrimSuffix(onlyoffice.SafeLocalFileName(title), filepath.Ext(onlyoffice.SafeLocalFileName(title))) + ".ocr.pdf"
+				tmpUp := filepath.Join(dir, upName)
+				data, err := os.ReadFile(res.OCRPDFPath)
+				if err != nil {
+					return err
+				}
+				if err := os.WriteFile(tmpUp, data, 0o644); err != nil {
+					return err
+				}
+				if folderID == "" {
+					obj["ocr_pdf_local"] = res.OCRPDFPath
+					obj["note"] = "file has no folderId; OCR PDF left local — pass after moving into a folder"
+				} else {
+					ent, err := c.UploadToFolder(ctx, folderID, tmpUp)
+					if err != nil {
+						return err
+					}
+					obj["ocr_pdf_file_id"] = fileIDStr(ent)
+					obj["ocr_pdf_title"] = onlyoffice.FileEntryTitle(ent)
+				}
+			} else if res.OCRPDFPath != "" {
+				// Keep OCR PDF outside temp by copying beside md if requested via env-less default:
+				kept := strings.TrimSuffix(outPath, filepath.Ext(outPath)) + ".ocr.pdf"
+				if b, err := os.ReadFile(res.OCRPDFPath); err == nil {
+					_ = os.WriteFile(kept, b, 0o644)
+					obj["ocr_pdf_local"] = kept
+				} else {
+					obj["ocr_pdf_local"] = res.OCRPDFPath
+				}
+			}
+			printObject(obj)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&to, "to", "", "write Markdown to this path (default: ./<title>.md)")
+	cmd.Flags().StringVar(&lang, "lang", "eng", "OCR language")
+	cmd.Flags().IntVar(&minChars, "min-chars", docpipe.DefaultMinTextChars, "OCR PDF if text layer shorter than this")
+	cmd.Flags().BoolVar(&uploadOCR, "upload-ocr", false, "upload searchable OCR PDF back into the same OO folder")
+	cmd.Flags().BoolVar(&useHOCR, "hocr", false, "use tesseract hOCR + go-hocr instead of ocrmypdf/pdftotext")
+	cmd.Flags().IntVar(&dpi, "dpi", 220, "DPI hint when --hocr (phone photos)")
+	cmd.Flags().Float32Var(&minConf, "min-conf", 0, "drop low-confidence words when --hocr")
+	return cmd
+}
+
+func docsPutMDCmd() *cobra.Command {
+	var folderID string
+	var keepLocalDOCX string
+	var replace bool
+	cmd := &cobra.Command{
+		Use:   "put-md PROJECT_ID MARKDOWN_PATH",
+		Short: "Convert Markdown→DOCX and upload DOCX into a project (OO-friendly)",
+		Long:  `Agents edit .md locally; this uploads .docx so OnlyOffice can open/version it.`,
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			pid, mdPath := args[0], args[1]
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			tools := docpipe.LookPath()
+			dir, err := os.MkdirTemp("", "oo-docs-put-md-*")
+			if err != nil {
+				return err
+			}
+			defer os.RemoveAll(dir)
+			docxName := strings.TrimSuffix(filepath.Base(mdPath), filepath.Ext(mdPath)) + ".docx"
+			docxPath := filepath.Join(dir, docxName)
+			if err := tools.MDToDOCX(mdPath, docxPath); err != nil {
+				return err
+			}
+			if keepLocalDOCX != "" {
+				if err := docpipe.EnsureDir(keepLocalDOCX); err != nil {
+					return err
+				}
+				b, err := os.ReadFile(docxPath)
+				if err != nil {
+					return err
+				}
+				if err := os.WriteFile(keepLocalDOCX, b, 0o644); err != nil {
+					return err
+				}
+			}
+			ctx := cmd.Context()
+			var ent *onlyoffice.FileEntry
+			var deleted []int
+			if folderID != "" {
+				if replace {
+					ent, deleted, err = c.UploadToFolderReplacing(ctx, folderID, docxPath)
+				} else {
+					ent, err = c.UploadToFolder(ctx, folderID, docxPath)
+				}
+				if err != nil {
+					return err
+				}
+				obj := map[string]any{
+					"project_id": pid,
+					"folder_id":  folderID,
+					"md":         mdPath,
+					"uploaded":   fileEntryToMap(ent),
+				}
+				if len(deleted) > 0 {
+					obj["replaced_file_ids"] = deleted
+				}
+				printObject(obj)
+				return nil
+			}
+			ent, err = c.UploadProjectFile(ctx, pid, docxPath)
+			if err != nil {
+				return err
+			}
+			printObject(map[string]any{
+				"project_id": pid,
+				"md":         mdPath,
+				"uploaded":   fileEntryToMap(ent),
+			})
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&folderID, "folder", "", "Documents folder id (default: project root)")
+	cmd.Flags().StringVar(&keepLocalDOCX, "keep-docx", "", "also write the generated DOCX to this local path")
+	cmd.Flags().BoolVar(&replace, "replace", true, "delete same-stem files in folder before upload (put-md upsert)")
+	return cmd
+}
+
+func docsPutTxtCmd() *cobra.Command {
+	var folderID string
+	var keepLocalDOCX string
+	var replace bool
+	cmd := &cobra.Command{
+		Use:   "put-txt PROJECT_ID TEXT_PATH",
+		Short: "Convert plain text→DOCX (preserve line breaks) and upload into a project",
+		Long:  `OnlyOffice cannot render .txt well. This keeps each source line on its own DOCX line.`,
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			pid, txtPath := args[0], args[1]
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			tools := docpipe.LookPath()
+			dir, err := os.MkdirTemp("", "oo-docs-put-txt-*")
+			if err != nil {
+				return err
+			}
+			defer os.RemoveAll(dir)
+			docxName := strings.TrimSuffix(filepath.Base(txtPath), filepath.Ext(txtPath)) + ".docx"
+			docxPath := filepath.Join(dir, docxName)
+			if err := tools.TXTToDOCX(txtPath, docxPath); err != nil {
+				return err
+			}
+			if keepLocalDOCX != "" {
+				if err := docpipe.EnsureDir(keepLocalDOCX); err != nil {
+					return err
+				}
+				b, err := os.ReadFile(docxPath)
+				if err != nil {
+					return err
+				}
+				if err := os.WriteFile(keepLocalDOCX, b, 0o644); err != nil {
+					return err
+				}
+			}
+			ctx := cmd.Context()
+			var ent *onlyoffice.FileEntry
+			var deleted []int
+			if folderID != "" {
+				if replace {
+					ent, deleted, err = c.UploadToFolderReplacing(ctx, folderID, docxPath)
+				} else {
+					ent, err = c.UploadToFolder(ctx, folderID, docxPath)
+				}
+				if err != nil {
+					return err
+				}
+				obj := map[string]any{
+					"project_id": pid,
+					"txt":        txtPath,
+					"folder_id":  folderID,
+					"uploaded":   fileEntryToMap(ent),
+				}
+				if len(deleted) > 0 {
+					obj["replaced_file_ids"] = deleted
+				}
+				printObject(obj)
+				return nil
+			}
+			ent, err = c.UploadProjectFile(ctx, pid, docxPath)
+			if err != nil {
+				return err
+			}
+			printObject(map[string]any{
+				"project_id": pid,
+				"txt":        txtPath,
+				"uploaded":   fileEntryToMap(ent),
+			})
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&folderID, "folder", "", "Documents folder id (default: project root)")
+	cmd.Flags().StringVar(&keepLocalDOCX, "keep-docx", "", "also write the generated DOCX to this local path")
+	cmd.Flags().BoolVar(&replace, "replace", true, "delete same-stem files in folder before upload (put-txt upsert)")
+	return cmd
+}

cmd/oo/main.go

@@ -3,7 +3,7 @@
 // Command tree is subject-based (mirrors the library split and the `tea` CLI):
 //
 //	oo calendar      list | events | add | delete
-//	oo projects      list | get | milestones | create | update | delete | files (list|upload|download|rename|delete)
+//	oo projects      list | get | milestones | create | update | delete | files (list|upload|download|rename|delete|as-md|put-md)
 //	oo tasks         list | get | create | update | delete | subtask add | files (list|upload|detach)
 //	oo users         list | self            (alias: oo whoami)
 //	oo contacts      list | get | delete | info-add | merge | dedupe-info
@@ -15,6 +15,7 @@
 //	oo crm           cleanup
 //	oo mails         accounts | folders | list | get | download-attachment | draft | attach | draft-invoice | delete
 //	oo invoices      list | get | create | update | pdf | pdf-cleanup | status | delete | items …
+//	oo docs          tools | convert | ocr | as-md | put-md
 //
 // CRM association rules: docs/crm-associations.md
 //

cmd/oo/projects_files.go

@@ -24,9 +24,35 @@ func projectFilesCmd() *cobra.Command {
 	cmd.AddCommand(prjFilesDownloadCmd())
 	cmd.AddCommand(prjFilesRenameCmd())
 	cmd.AddCommand(prjFilesDeleteCmd())
+	cmd.AddCommand(prjFilesDedupeCmd())
+	// Convenience aliases into oo docs (md↔docx / OCR pipeline).
+	cmd.AddCommand(aliasDocsAsMD())
+	cmd.AddCommand(aliasDocsPutMD())
+	cmd.AddCommand(aliasDocsPutTxt())
 	return cmd
 }
 
+func aliasDocsAsMD() *cobra.Command {
+	c := docsAsMDCmd()
+	c.Use = "as-md FILE_ID"
+	c.Short = "Alias of `oo docs as-md` — download OO file as Markdown (OCR if needed)"
+	return c
+}
+
+func aliasDocsPutMD() *cobra.Command {
+	c := docsPutMDCmd()
+	c.Use = "put-md PROJECT_ID MARKDOWN_PATH"
+	c.Short = "Alias of `oo docs put-md` — Markdown→DOCX upload into project"
+	return c
+}
+
+func aliasDocsPutTxt() *cobra.Command {
+	c := docsPutTxtCmd()
+	c.Use = "put-txt PROJECT_ID TEXT_PATH"
+	c.Short = "Alias of `oo docs put-txt` — plain text→DOCX upload into project"
+	return c
+}
+
 func prjFilesListCmd() *cobra.Command {
 	var showFolders bool
 	cmd := &cobra.Command{
@@ -184,6 +210,62 @@ func prjFilesDeleteCmd() *cobra.Command {
 	}
 }
 
+func prjFilesDedupeCmd() *cobra.Command {
+	var apply, cross bool
+	cmd := &cobra.Command{
+		Use:   "dedupe PROJECT_ID",
+		Short: "Find (and optionally remove) duplicate files in project Documents folders",
+		Long: `Duplicates share the same logical name: stem|ext (OO title+fileExst).
+
+Default: dry-run report. Pass --apply to delete older copies (keeps newest; --cross prefers non-trash folders).`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			groups, deleted, err := c.DedupeProject(cmd.Context(), args[0], onlyoffice.DedupOptions{
+				CrossFolder: cross,
+			}, apply)
+			if err != nil {
+				return err
+			}
+			rows := make([]map[string]any, 0, len(groups))
+			for _, g := range groups {
+				row := map[string]any{
+					"key":          g.Key,
+					"folder_id":    g.FolderID,
+					"folder_title": g.FolderTitle,
+					"keep_id":      fileIDStr(g.Keep),
+					"keep_title":   onlyoffice.FileEntryTitle(g.Keep),
+					"remove_count": len(g.Remove),
+				}
+				removeIDs := make([]string, 0, len(g.Remove))
+				for _, f := range g.Remove {
+					removeIDs = append(removeIDs, fileIDStr(f))
+				}
+				row["remove_ids"] = removeIDs
+				rows = append(rows, row)
+			}
+			out := map[string]any{
+				"project_id": args[0],
+				"dry_run":    !apply,
+				"cross":      cross,
+				"groups":     len(groups),
+				"duplicates": rows,
+			}
+			if apply {
+				out["deleted_ids"] = deleted
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&apply, "apply", false, "delete duplicate files (default: report only)")
+	cmd.Flags().BoolVar(&cross, "cross", false, "also dedupe same stem|ext across folders (prefers non-_trash)")
+	return cmd
+}
+
 func fileEntryRows(files []*onlyoffice.FileEntry) []map[string]any {
 	rows := make([]map[string]any, 0, len(files))
 	for _, f := range files {

files.go

@@ -263,22 +263,86 @@ func (c *Client) RenameFile(ctx context.Context, fileID, newTitle string) (*File
 	return decodeResponseFileEntry(raw)
 }
 
-type deleteFilesBody struct {
-	FileIDs   []int `json:"fileIds"`
-	FolderIDs []int `json:"folderIds"`
-}
-
 // DeleteFiles permanently deletes files by numeric id (Documents module).
+// Uses per-file DELETE (DeleteDavItems); fileops/delete returns 200 on some
+// portals (e.g. produktor.io) without removing the file.
 func (c *Client) DeleteFiles(ctx context.Context, fileIDs []int) error {
 	if len(fileIDs) == 0 {
 		return fmt.Errorf("no file ids to delete")
 	}
-	body := deleteFilesBody{FileIDs: fileIDs, FolderIDs: nil}
+	strIDs := make([]string, len(fileIDs))
-	_, err := c.putJSON(ctx, "/api/2.0/files/fileops/delete.json", body)
+	for i, id := range fileIDs {
-	if err != nil {
+		strIDs[i] = strconv.Itoa(id)
-		_, err = c.putJSON(ctx, "/api/2.0/files/fileops/delete", body)
 	}
-	return err
+	return c.DeleteDavItems(ctx, nil, strIDs)
+}
+
+// ListFolder returns the Documents module listing for a folder id
+// (GET /api/2.0/files/{folderId}).
+func (c *Client) ListFolder(ctx context.Context, folderID string) (map[string]any, error) {
+	if folderID == "" {
+		return nil, fmt.Errorf("folder id is required")
+	}
+	out, err := c.ResponseObject(ctx, "/api/2.0/files/"+url.PathEscape(folderID)+".json")
+	if err != nil {
+		out, err = c.ResponseObject(ctx, "/api/2.0/files/"+url.PathEscape(folderID))
+	}
+	return out, err
+}
+
+// CreateFolder creates a subfolder under parentFolderID.
+func (c *Client) CreateFolder(ctx context.Context, parentFolderID, title string) (map[string]any, error) {
+	if parentFolderID == "" || title == "" {
+		return nil, fmt.Errorf("parent folder id and title are required")
+	}
+	body := map[string]any{"title": title}
+	out, err := c.postJSONObject(ctx, "/api/2.0/files/folder/"+url.PathEscape(parentFolderID)+".json", body)
+	if err != nil {
+		out, err = c.postJSONObject(ctx, "/api/2.0/files/folder/"+url.PathEscape(parentFolderID), body)
+	}
+	return out, err
+}
+
+// MoveFiles moves file ids into destFolderID (Documents fileops/move).
+func (c *Client) MoveFiles(ctx context.Context, destFolderID int, fileIDs []int) (map[string]any, error) {
+	if destFolderID == 0 || len(fileIDs) == 0 {
+		return nil, fmt.Errorf("dest folder and file ids are required")
+	}
+	body := map[string]any{
+		"folderIds":    []int{},
+		"fileIds":      fileIDs,
+		"destFolderId": destFolderID,
+	}
+	out, err := c.putJSONObject(ctx, "/api/2.0/files/fileops/move.json", body)
+	if err != nil {
+		out, err = c.putJSONObject(ctx, "/api/2.0/files/fileops/move", body)
+	}
+	return out, err
+}
+
+// UploadToFolder uploads a local file into an arbitrary Documents folder id.
+func (c *Client) UploadToFolder(ctx context.Context, folderID, localPath string) (*FileEntry, error) {
+	if folderID == "" || localPath == "" {
+		return nil, fmt.Errorf("folder id and local path are required")
+	}
+	uploadPath := fmt.Sprintf("/api/2.0/files/%s/upload.json", url.PathEscape(folderID))
+	raw, err := c.uploadMultipart(ctx, uploadPath, "file", localPath)
+	if err != nil {
+		uploadPath = fmt.Sprintf("/api/2.0/files/%s/upload", url.PathEscape(folderID))
+		raw, err = c.uploadMultipart(ctx, uploadPath, "file", localPath)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return decodeResponseFileEntry(raw)
+}
+
+// FileFolderID returns the parent folder id string for a file entry, if known.
+func FileFolderID(f *FileEntry) string {
+	if f == nil || f.FolderID == nil {
+		return ""
+	}
+	return f.FolderID.String()
 }
 
 // DownloadFile streams file bytes from the file's viewUrl using the same auth

files_dedupe.go

@@ -0,0 +1,337 @@
+package onlyoffice
+
+import (
+	"context"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// FileEntryExt returns a normalized extension (lowercase, with leading dot).
+func FileEntryExt(f *FileEntry) string {
+	if f == nil {
+		return ""
+	}
+	exst := ""
+	if f.FileExst != nil {
+		exst = strings.TrimSpace(*f.FileExst)
+	}
+	if exst != "" {
+		if !strings.HasPrefix(exst, ".") {
+			exst = "." + exst
+		}
+		return strings.ToLower(exst)
+	}
+	if f.Title != nil {
+		if ext := filepath.Ext(*f.Title); ext != "" {
+			return strings.ToLower(ext)
+		}
+	}
+	return ""
+}
+
+// FileDedupKey is stem|ext — two files with the same key are duplicates.
+func FileDedupKey(f *FileEntry) string {
+	st := FileEntryStem(f)
+	ext := FileEntryExt(f)
+	if st == "" {
+		return ""
+	}
+	if ext == "" {
+		return st
+	}
+	return st + "|" + strings.TrimPrefix(ext, ".")
+}
+
+// FindFilesByDedupKey returns folder files matching stem and extension.
+func FindFilesByDedupKey(files []*FileEntry, stem, ext string) []*FileEntry {
+	key := dedupKeyFromParts(stem, ext)
+	if key == "" {
+		return nil
+	}
+	var out []*FileEntry
+	for _, f := range files {
+		if FileDedupKey(f) == key {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+func dedupKeyFromParts(stem, ext string) string {
+	stem = strings.TrimSpace(stem)
+	if stem == "" {
+		return ""
+	}
+	ext = strings.ToLower(strings.TrimSpace(ext))
+	if ext != "" && !strings.HasPrefix(ext, ".") {
+		ext = "." + ext
+	}
+	if ext == "" {
+		return stem
+	}
+	return stem + "|" + strings.TrimPrefix(ext, ".")
+}
+
+// UploadExtFromLocal returns the lowercase extension from a local path.
+func UploadExtFromLocal(localPath string) string {
+	ext := filepath.Ext(localPath)
+	if ext == "" {
+		return ""
+	}
+	return strings.ToLower(ext)
+}
+
+// IsTrashFolderTitle reports staging/trash folders (e.g. _trash-md).
+func IsTrashFolderTitle(title string) bool {
+	t := strings.ToLower(strings.TrimSpace(title))
+	return strings.HasPrefix(t, "_") || strings.Contains(t, "trash")
+}
+
+// ProjectFolderFile ties a file to its project Documents subfolder.
+type ProjectFolderFile struct {
+	FolderID    string
+	FolderTitle string
+	File        *FileEntry
+}
+
+// DedupGroup is one duplicate set: keep the newest (or non-trash) file.
+type DedupGroup struct {
+	Key         string
+	FolderID    string
+	FolderTitle string
+	Keep        *FileEntry
+	Remove      []*FileEntry
+}
+
+// DedupOptions controls project-wide duplicate scans.
+type DedupOptions struct {
+	CrossFolder bool
+}
+
+// FindProjectDuplicates scans project folders for duplicate files.
+func FindProjectDuplicates(folders []*FolderEntry, filesByFolder map[string][]*FileEntry, opts DedupOptions) []DedupGroup {
+	var indexed []ProjectFolderFile
+	for _, folder := range folders {
+		if folder == nil || folder.ID == nil {
+			continue
+		}
+		fid := folder.ID.String()
+		title := ""
+		if folder.Title != nil {
+			title = *folder.Title
+		}
+		for _, f := range filesByFolder[fid] {
+			if f == nil {
+				continue
+			}
+			indexed = append(indexed, ProjectFolderFile{
+				FolderID: fid, FolderTitle: title, File: f,
+			})
+		}
+	}
+	if opts.CrossFolder {
+		return findCrossFolderDuplicates(indexed)
+	}
+	return findWithinFolderDuplicates(indexed)
+}
+
+func findWithinFolderDuplicates(indexed []ProjectFolderFile) []DedupGroup {
+	byFolder := map[string][]ProjectFolderFile{}
+	for _, it := range indexed {
+		byFolder[it.FolderID] = append(byFolder[it.FolderID], it)
+	}
+	var out []DedupGroup
+	for fid, items := range byFolder {
+		title := ""
+		if len(items) > 0 {
+			title = items[0].FolderTitle
+		}
+		byKey := map[string][]*FileEntry{}
+		for _, it := range items {
+			k := FileDedupKey(it.File)
+			byKey[k] = append(byKey[k], it.File)
+		}
+		for k, group := range byKey {
+			if len(group) < 2 {
+				continue
+			}
+			keep, remove := pickDuplicateKeeper(group, false)
+			if keep == nil || len(remove) == 0 {
+				continue
+			}
+			out = append(out, DedupGroup{
+				Key: k, FolderID: fid, FolderTitle: title, Keep: keep, Remove: remove,
+			})
+		}
+	}
+	sortDedupGroups(out)
+	return out
+}
+
+func findCrossFolderDuplicates(indexed []ProjectFolderFile) []DedupGroup {
+	byKey := map[string][]ProjectFolderFile{}
+	for _, it := range indexed {
+		k := FileDedupKey(it.File)
+		byKey[k] = append(byKey[k], it)
+	}
+	var out []DedupGroup
+	for k, items := range byKey {
+		if len(items) < 2 {
+			continue
+		}
+		files := make([]*FileEntry, len(items))
+		folders := make([]string, len(items))
+		folderTitles := make([]string, len(items))
+		for i, it := range items {
+			files[i] = it.File
+			folders[i] = it.FolderID
+			folderTitles[i] = it.FolderTitle
+		}
+		keep, remove := pickDuplicateKeeperWithFolders(files, folders, folderTitles)
+		if keep == nil || len(remove) == 0 {
+			continue
+		}
+		fid, ftitle := "", ""
+		for _, it := range items {
+			if it.File == keep {
+				fid, ftitle = it.FolderID, it.FolderTitle
+				break
+			}
+		}
+		out = append(out, DedupGroup{
+			Key: k, FolderID: fid, FolderTitle: ftitle, Keep: keep, Remove: remove,
+		})
+	}
+	sortDedupGroups(out)
+	return out
+}
+
+func pickDuplicateKeeper(files []*FileEntry, _ bool) (*FileEntry, []*FileEntry) {
+	return pickDuplicateKeeperWithFolders(files, nil, nil)
+}
+
+func pickDuplicateKeeperWithFolders(files []*FileEntry, folderIDs, folderTitles []string) (*FileEntry, []*FileEntry) {
+	if len(files) == 0 {
+		return nil, nil
+	}
+	type ranked struct {
+		file  *FileEntry
+		trash bool
+	}
+	rankedFiles := make([]ranked, len(files))
+	for i, f := range files {
+		trash := false
+		if folderTitles != nil && i < len(folderTitles) {
+			trash = IsTrashFolderTitle(folderTitles[i])
+		}
+		rankedFiles[i] = ranked{file: f, trash: trash}
+	}
+	sort.SliceStable(rankedFiles, func(i, j int) bool {
+		ri, rj := rankedFiles[i], rankedFiles[j]
+		if ri.trash != rj.trash {
+			return !ri.trash // non-trash first
+		}
+		ti, tj := rankedFiles[i].file.Updated, rankedFiles[j].file.Updated
+		if ti == nil {
+			return false
+		}
+		if tj == nil {
+			return true
+		}
+		return ti.After(*tj) // newest first
+	})
+	keep := rankedFiles[0].file
+	var remove []*FileEntry
+	for _, r := range rankedFiles[1:] {
+		remove = append(remove, r.file)
+	}
+	return keep, remove
+}
+
+func sortDedupGroups(groups []DedupGroup) {
+	sort.Slice(groups, func(i, j int) bool {
+		if groups[i].FolderTitle != groups[j].FolderTitle {
+			return groups[i].FolderTitle < groups[j].FolderTitle
+		}
+		return groups[i].Key < groups[j].Key
+	})
+}
+
+// ApplyDedupGroups deletes Remove files from each group.
+func (c *Client) ApplyDedupGroups(ctx context.Context, groups []DedupGroup) ([]int, error) {
+	seen := map[int]struct{}{}
+	var ids []int
+	for _, g := range groups {
+		for _, f := range g.Remove {
+			n := int(FileEntryNumericID(f))
+			if n == 0 {
+				continue
+			}
+			if _, ok := seen[n]; ok {
+				continue
+			}
+			seen[n] = struct{}{}
+			ids = append(ids, n)
+		}
+	}
+	if len(ids) == 0 {
+		return nil, nil
+	}
+	if err := c.DeleteFiles(ctx, ids); err != nil {
+		return ids, err
+	}
+	return ids, nil
+}
+
+// DeleteFilesByDedupKey removes all files in folderID matching stem+ext.
+func (c *Client) DeleteFilesByDedupKey(ctx context.Context, folderID, stem, ext string) ([]int, error) {
+	files, err := c.FolderFiles(ctx, folderID)
+	if err != nil {
+		return nil, err
+	}
+	matches := FindFilesByDedupKey(files, stem, ext)
+	if len(matches) == 0 {
+		return nil, nil
+	}
+	ids := make([]int, 0, len(matches))
+	for _, f := range matches {
+		n := int(FileEntryNumericID(f))
+		if n != 0 {
+			ids = append(ids, n)
+		}
+	}
+	if len(ids) == 0 {
+		return nil, nil
+	}
+	if err := c.DeleteFiles(ctx, ids); err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+// DedupeProject scans project folders and optionally deletes duplicates.
+func (c *Client) DedupeProject(ctx context.Context, projectID string, opts DedupOptions, apply bool) ([]DedupGroup, []int, error) {
+	pf, err := c.GetProjectFiles(ctx, projectID)
+	if err != nil {
+		return nil, nil, err
+	}
+	filesByFolder := make(map[string][]*FileEntry, len(pf.Folders))
+	for _, folder := range pf.Folders {
+		if folder == nil || folder.ID == nil {
+			continue
+		}
+		fid := folder.ID.String()
+		files, err := c.FolderFiles(ctx, fid)
+		if err != nil {
+			return nil, nil, err
+		}
+		filesByFolder[fid] = files
+	}
+	groups := FindProjectDuplicates(pf.Folders, filesByFolder, opts)
+	if !apply || len(groups) == 0 {
+		return groups, nil, nil
+	}
+	deleted, err := c.ApplyDedupGroups(ctx, groups)
+	return groups, deleted, err
+}

files_dedupe_test.go

@@ -0,0 +1,81 @@
+package onlyoffice
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+func TestFileDedupKey(t *testing.T) {
+	title := "OO-HONDA-7-INDEX.docx"
+	exst := ".docx"
+	f := &FileEntry{Title: &title, FileExst: &exst}
+	if got := FileDedupKey(f); got != "OO-HONDA-7-INDEX|docx" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestFindFilesByDedupKey(t *testing.T) {
+	a := &FileEntry{Title: strPtr("foo.docx"), FileExst: strPtr(".docx")}
+	b := &FileEntry{Title: strPtr("foo.md"), FileExst: strPtr(".md")}
+	files := []*FileEntry{a, b}
+	got := FindFilesByDedupKey(files, "foo", ".docx")
+	if len(got) != 1 || got[0] != a {
+		t.Fatalf("got %+v", got)
+	}
+}
+
+func TestFindWithinFolderDuplicates(t *testing.T) {
+	t1 := time.Date(2026, 8, 27, 16, 0, 0, 0, time.UTC)
+	t2 := t1.Add(time.Hour)
+	old := &FileEntry{ID: jsonNum("1"), Title: strPtr("idx.docx"), FileExst: strPtr(".docx"), Updated: &t1}
+	new := &FileEntry{ID: jsonNum("2"), Title: strPtr("idx.docx"), FileExst: strPtr(".docx"), Updated: &t2}
+	indexed := []ProjectFolderFile{
+		{FolderID: "490", FolderTitle: "00-Index", File: old},
+		{FolderID: "490", FolderTitle: "00-Index", File: new},
+	}
+	groups := findWithinFolderDuplicates(indexed)
+	if len(groups) != 1 {
+		t.Fatalf("groups=%d", len(groups))
+	}
+	if FileEntryNumericID(groups[0].Keep) != 2 {
+		t.Fatalf("keep id=%d", FileEntryNumericID(groups[0].Keep))
+	}
+	if len(groups[0].Remove) != 1 || FileEntryNumericID(groups[0].Remove[0]) != 1 {
+		t.Fatalf("remove=%v", groups[0].Remove)
+	}
+}
+
+func TestCrossFolderPrefersNonTrash(t *testing.T) {
+	t1 := time.Date(2026, 8, 27, 18, 0, 0, 0, time.UTC)
+	t2 := t1.Add(-time.Hour)
+	trash := &FileEntry{ID: jsonNum("10"), Title: strPtr("INDEX.md"), FileExst: strPtr(".md"), Updated: &t1}
+	good := &FileEntry{ID: jsonNum("20"), Title: strPtr("INDEX.md"), FileExst: strPtr(".md"), Updated: &t2}
+	indexed := []ProjectFolderFile{
+		{FolderID: "493", FolderTitle: "_trash-md", File: trash},
+		{FolderID: "492", FolderTitle: "OCR", File: good},
+	}
+	groups := findCrossFolderDuplicates(indexed)
+	if len(groups) != 1 {
+		t.Fatalf("groups=%d", len(groups))
+	}
+	if FileEntryNumericID(groups[0].Keep) != 20 {
+		t.Fatalf("keep id=%d", FileEntryNumericID(groups[0].Keep))
+	}
+}
+
+func TestIsTrashFolderTitle(t *testing.T) {
+	if !IsTrashFolderTitle("_trash-md") {
+		t.Fatal("expected trash")
+	}
+	if IsTrashFolderTitle("00-Index") {
+		t.Fatal("expected not trash")
+	}
+}
+
+func strPtr(s string) *string { return &s }
+
+func jsonNum(s string) *json.Number {
+	n := json.Number(s)
+	return &n
+}

files_stem.go

@@ -0,0 +1,129 @@
+package onlyoffice
+
+import (
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+)
+
+// FileEntryStem returns the logical basename without duplicated extensions.
+// OO often stores title="foo.docx" and fileExst=".docx" (UI shows foo.docx.docx).
+func FileEntryStem(f *FileEntry) string {
+	if f == nil || f.Title == nil {
+		return ""
+	}
+	exst := ""
+	if f.FileExst != nil {
+		exst = *f.FileExst
+	}
+	return NormalizeUploadStem(*f.Title, exst)
+}
+
+// NormalizeUploadStem derives a stable stem for matching uploads.
+func NormalizeUploadStem(title, exst string) string {
+	t := strings.TrimSpace(title)
+	t = strings.TrimSuffix(t, ".")
+	if exst != "" && strings.HasSuffix(t, exst) {
+		t = strings.TrimSuffix(t, exst)
+	}
+	if ext := filepath.Ext(t); ext != "" {
+		t = strings.TrimSuffix(t, ext)
+	}
+	return strings.TrimSpace(t)
+}
+
+// UploadStemFromLocal returns the stem used to match/replace folder files.
+func UploadStemFromLocal(localPath string) string {
+	base := filepath.Base(localPath)
+	ext := filepath.Ext(base)
+	if ext != "" {
+		base = strings.TrimSuffix(base, ext)
+	}
+	return base
+}
+
+// FolderFiles returns file entries in a Documents folder.
+func (c *Client) FolderFiles(ctx context.Context, folderID string) ([]*FileEntry, error) {
+	raw, err := c.ListFolder(ctx, folderID)
+	if err != nil {
+		return nil, err
+	}
+	return ParseFolderFileEntries(raw), nil
+}
+
+// ParseFolderFileEntries extracts []*FileEntry from ListFolder JSON.
+func ParseFolderFileEntries(raw map[string]any) []*FileEntry {
+	items, _ := raw["files"].([]any)
+	out := make([]*FileEntry, 0, len(items))
+	for _, it := range items {
+		m, ok := it.(map[string]any)
+		if !ok {
+			continue
+		}
+		b, err := json.Marshal(m)
+		if err != nil {
+			continue
+		}
+		var f FileEntry
+		if err := json.Unmarshal(b, &f); err != nil {
+			continue
+		}
+		out = append(out, &f)
+	}
+	return out
+}
+
+// FindFilesByStem returns folder files whose logical stem matches.
+func FindFilesByStem(files []*FileEntry, stem string) []*FileEntry {
+	stem = strings.TrimSpace(stem)
+	if stem == "" {
+		return nil
+	}
+	var out []*FileEntry
+	for _, f := range files {
+		if FileEntryStem(f) == stem {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// DeleteFilesByStem removes all files in folderID matching stem (any extension).
+// Prefer DeleteFilesByDedupKey when the upload extension is known.
+func (c *Client) DeleteFilesByStem(ctx context.Context, folderID, stem string) ([]int, error) {
+	files, err := c.FolderFiles(ctx, folderID)
+	if err != nil {
+		return nil, err
+	}
+	matches := FindFilesByStem(files, stem)
+	if len(matches) == 0 {
+		return nil, nil
+	}
+	ids := make([]int, 0, len(matches))
+	for _, f := range matches {
+		n := int(FileEntryNumericID(f))
+		if n != 0 {
+			ids = append(ids, n)
+		}
+	}
+	if len(ids) == 0 {
+		return nil, nil
+	}
+	if err := c.DeleteFiles(ctx, ids); err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+// UploadToFolderReplacing deletes same stem+ext files then uploads localPath.
+func (c *Client) UploadToFolderReplacing(ctx context.Context, folderID, localPath string) (*FileEntry, []int, error) {
+	stem := UploadStemFromLocal(localPath)
+	ext := UploadExtFromLocal(localPath)
+	deleted, err := c.DeleteFilesByDedupKey(ctx, folderID, stem, ext)
+	if err != nil {
+		return nil, deleted, err
+	}
+	ent, err := c.UploadToFolder(ctx, folderID, localPath)
+	return ent, deleted, err
+}

files_stem_test.go

@@ -0,0 +1,35 @@
+package onlyoffice
+
+import "testing"
+
+func TestNormalizeUploadStem(t *testing.T) {
+	tests := []struct {
+		title, exst, want string
+	}{
+		{"OO-HONDA-7-INDEX.docx", ".docx", "OO-HONDA-7-INDEX"},
+		{"README.txt", ".txt", "README"},
+		{"car-docs-print.docx", ".docx", "car-docs-print"},
+		{"plain.", "", "plain"},
+		{"foo", ".docx", "foo"},
+	}
+	for _, tc := range tests {
+		if got := NormalizeUploadStem(tc.title, tc.exst); got != tc.want {
+			t.Fatalf("NormalizeUploadStem(%q,%q)=%q want %q", tc.title, tc.exst, got, tc.want)
+		}
+	}
+}
+
+func TestFileEntryStem(t *testing.T) {
+	title := "00-INDEX.docx"
+	exst := ".docx"
+	f := &FileEntry{Title: &title, FileExst: &exst}
+	if got := FileEntryStem(f); got != "00-INDEX" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestUploadStemFromLocal(t *testing.T) {
+	if got := UploadStemFromLocal("/tmp/OO-HONDA-7-INDEX.docx"); got != "OO-HONDA-7-INDEX" {
+		t.Fatalf("got %q", got)
+	}
+}

files_webdav.go

@@ -169,7 +169,7 @@ func (c *Client) CopyDavItems(ctx context.Context, folderIDs, fileIDs []string,
 
 // DeleteDavItems deletes the given folders and/or files.
 func (c *Client) DeleteDavItems(ctx context.Context, folderIDs, fileIDs []string) error {
-	body := map[string]any{"DeleteAfter": true, "Immediately": false}
+	body := map[string]any{"DeleteAfter": true, "Immediately": true}
 	for _, id := range folderIDs {
 		if _, err := c.deleteJSON(ctx, "/api/2.0/files/folder/"+url.PathEscape(id), body); err != nil {
 			return err

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/charmbracelet/lipgloss v0.12.1
 	github.com/charmbracelet/x/ansi v0.1.4
 	github.com/emersion/go-vcard v0.0.0-20260618161152-d854b7e0e2d3
+	github.com/eslider/go-hocr v0.2.2-0.20260827163626-8ff01582b002
 	github.com/eslider/go-xls/v2 v2.1.0
 	github.com/google/go-querystring v1.2.0
 	github.com/joho/godotenv v1.5.1

go.sum

@@ -37,6 +37,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/emersion/go-vcard v0.0.0-20260618161152-d854b7e0e2d3 h1:B9YK+Tck5mTccyDhtxBzWyqGYcFxLyB6+noMNW4/VgI=
 github.com/emersion/go-vcard v0.0.0-20260618161152-d854b7e0e2d3/go.mod h1:HMJKR5wlh/ziNp+sHEDV2ltblO4JD2+IdDOWtGcQBTM=
+github.com/eslider/go-hocr v0.2.2-0.20260827163626-8ff01582b002 h1:LOFxQG4mxvlH7+lffbO2SIn2ThlClJlrHHfs1OqMNXs=
+github.com/eslider/go-hocr v0.2.2-0.20260827163626-8ff01582b002/go.mod h1:fIgfH/E1j3rU8du4X4+7mxTD0GPtPQibTzytgitdJWU=
 github.com/eslider/go-xls/v2 v2.1.0 h1:HszWKqYQbXxACmAXXWdMsfNl1NDBfGVBnJUPtyUHQ7A=
 github.com/eslider/go-xls/v2 v2.1.0/go.mod h1:xgxO6JrfuBr9jGUB+0z5l/yDmFFZ5diGk0ATGihxlMU=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=

internal/docpipe/docpipe.go

@@ -0,0 +1,419 @@
+// Package docpipe converts documents for OnlyOffice agent workflows:
+// Markdown ↔ DOCX (pandoc) and image/PDF OCR → searchable PDF + Markdown text.
+//
+// External tools (optional at runtime; helpers skip/error clearly when missing):
+//   - pandoc     — md↔docx
+//   - ocrmypdf   — OCR into a searchable PDF
+//   - pdftotext  — extract text layer
+//   - tesseract  — OCR single images when ocrmypdf is unsuitable
+//   - ghostscript (gs) — PDF rewrite/optimize via PostScript (pdfwrite)
+package docpipe
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// DefaultMinTextChars: below this, a PDF is treated as needing OCR.
+const DefaultMinTextChars = 200
+
+// Tools reports which converters are available on PATH.
+type Tools struct {
+	Pandoc      string
+	OCRMyPDF    string
+	PDFToText   string
+	Tesseract   string
+	Ghostscript string
+}
+
+// LookPath resolves converter binaries (empty string if missing).
+func LookPath() Tools {
+	find := func(names ...string) string {
+		for _, n := range names {
+			if p, err := exec.LookPath(n); err == nil {
+				return p
+			}
+		}
+		return ""
+	}
+	return Tools{
+		Pandoc:      find("pandoc"),
+		OCRMyPDF:    find("ocrmypdf"),
+		PDFToText:   find("pdftotext"),
+		Tesseract:   find("tesseract"),
+		Ghostscript: find("gs", "ghostscript"),
+	}
+}
+
+func (t Tools) requirePandoc() error {
+	if t.Pandoc == "" {
+		return fmt.Errorf("pandoc not found on PATH (needed for md↔docx)")
+	}
+	return nil
+}
+
+// Ext returns lower-case extension including dot (".pdf").
+func Ext(path string) string {
+	return strings.ToLower(filepath.Ext(path))
+}
+
+// ConvertFile converts between md and docx (and other pandoc formats) via pandoc.
+// outExt may be ".md", ".docx", or a full output path.
+func (t Tools) ConvertFile(inPath, outPath string) error {
+	if err := t.requirePandoc(); err != nil {
+		return err
+	}
+	if strings.TrimSpace(outPath) == "" {
+		return fmt.Errorf("output path required")
+	}
+	cmd := exec.Command(t.Pandoc, inPath, "-o", outPath)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("pandoc %s → %s: %w (%s)", inPath, outPath, err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+// TXTToDOCX converts plain text to DOCX preserving line breaks (via markdown hard breaks).
+func (t Tools) TXTToDOCX(txtPath, docxPath string) error {
+	if Ext(txtPath) != ".txt" {
+		return fmt.Errorf("expected .txt input, got %q", txtPath)
+	}
+	if docxPath == "" {
+		docxPath = strings.TrimSuffix(txtPath, Ext(txtPath)) + ".docx"
+	}
+	b, err := os.ReadFile(txtPath)
+	if err != nil {
+		return err
+	}
+	dir := filepath.Dir(docxPath)
+	if dir == "" || dir == "." {
+		dir = os.TempDir()
+	}
+	tmpMD := filepath.Join(dir, trimExt(filepath.Base(txtPath))+".txt2docx.md")
+	md := TxtToMarkdown(string(b))
+	if err := os.WriteFile(tmpMD, []byte(md), 0o644); err != nil {
+		return err
+	}
+	defer os.Remove(tmpMD)
+	return t.MDToDOCX(tmpMD, docxPath)
+}
+
+// TxtToMarkdown converts plain text to Markdown for DOCX output.
+// Prose text: each line is a hard break. Fixed-width extracts (INE, pdftotext -layout):
+// wrapped in a fenced code block (monospace, columns preserved).
+func TxtToMarkdown(content string) string {
+	content = normalizeTxtNewlines(content)
+	if isFixedWidthTxt(content) {
+		return "```\n" + content + "\n```\n"
+	}
+	var b strings.Builder
+	for _, line := range strings.Split(content, "\n") {
+		if strings.TrimSpace(line) == "" {
+			b.WriteByte('\n')
+			continue
+		}
+		b.WriteString(line)
+		b.WriteString("  \n")
+	}
+	return b.String()
+}
+
+func normalizeTxtNewlines(content string) string {
+	content = strings.ReplaceAll(content, "\r\n", "\n")
+	return strings.ReplaceAll(content, "\r", "\n")
+}
+
+// isFixedWidthTxt detects pdftotext -layout style extracts (many indented/spaced columns).
+func isFixedWidthTxt(content string) bool {
+	lines := strings.Split(content, "\n")
+	if len(lines) < 8 {
+		return false
+	}
+	indented, long := 0, 0
+	for _, line := range lines {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		if len(line) >= 72 {
+			long++
+		}
+		if len(line) > 0 && (line[0] == ' ' || line[0] == '\t') {
+			indented++
+		}
+	}
+	n := len(lines)
+	return indented*100/n >= 20 || (long >= 5 && indented*100/n >= 10)
+}
+
+// MDToDOCX writes a DOCX next to or at outPath from a Markdown file.
+func (t Tools) MDToDOCX(mdPath, docxPath string) error {
+	if Ext(mdPath) != ".md" && Ext(mdPath) != ".markdown" {
+		return fmt.Errorf("expected markdown input, got %q", mdPath)
+	}
+	if docxPath == "" {
+		docxPath = strings.TrimSuffix(mdPath, Ext(mdPath)) + ".docx"
+	}
+	return t.ConvertFile(mdPath, docxPath)
+}
+
+// DOCXToMD writes Markdown from a DOCX file.
+func (t Tools) DOCXToMD(docxPath, mdPath string) error {
+	if Ext(docxPath) != ".docx" {
+		return fmt.Errorf("expected .docx input, got %q", docxPath)
+	}
+	if mdPath == "" {
+		mdPath = strings.TrimSuffix(docxPath, Ext(docxPath)) + ".md"
+	}
+	return t.ConvertFile(docxPath, mdPath)
+}
+
+// OptimizePDF rewrites a PDF through Ghostscript (PostScript pdfwrite).
+// Preserves native text layers; strips broken OCR overlays; shrinks for OO preview.
+// Use instead of ocrmypdf when pdftotext already extracts enough text.
+func (t Tools) OptimizePDF(inPath, outPath string) error {
+	if t.Ghostscript == "" {
+		return fmt.Errorf("ghostscript (gs) not found on PATH")
+	}
+	if outPath == "" {
+		return fmt.Errorf("output PDF path required")
+	}
+	args := []string{
+		"-sDEVICE=pdfwrite",
+		"-dCompatibilityLevel=1.5",
+		"-dNOPAUSE", "-dQUIET", "-dBATCH",
+		"-dPDFSETTINGS=/ebook",
+		"-dEmbedAllFonts=true",
+		"-dSubsetFonts=true",
+		"-dCompressFonts=true",
+		"-dCompressPages=true",
+		"-dDetectDuplicateImages=true",
+		"-dAutoRotatePages=/None",
+		"-sOutputFile=" + outPath,
+		inPath,
+	}
+	cmd := exec.Command(t.Ghostscript, args...)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("ghostscript pdfwrite: %w (%s)", err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+// PDFTextLayerChars returns approximate extracted character count (0 if unavailable).
+func (t Tools) PDFTextLayerChars(pdfPath string) (int, error) {
+	if t.PDFToText == "" {
+		return 0, fmt.Errorf("pdftotext not found on PATH")
+	}
+	cmd := exec.Command(t.PDFToText, "-layout", pdfPath, "-")
+	out, err := cmd.Output()
+	if err != nil {
+		return 0, err
+	}
+	return len(bytes.TrimSpace(out)), nil
+}
+
+// NeedsOCR reports whether path likely needs OCR before text extraction.
+func (t Tools) NeedsOCR(path string, minChars int) (bool, error) {
+	if minChars <= 0 {
+		minChars = DefaultMinTextChars
+	}
+	switch Ext(path) {
+	case ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp", ".gif", ".bmp":
+		return true, nil
+	case ".pdf":
+		n, err := t.PDFTextLayerChars(path)
+		if err != nil {
+			// If we cannot measure, prefer OCR.
+			return true, nil
+		}
+		return n < minChars, nil
+	default:
+		return false, nil
+	}
+}
+
+// OCRToPDF runs ocrmypdf into outPDF (searchable). Forces OCR when force is true.
+func (t Tools) OCRToPDF(inPath, outPDF string, force bool, lang string) error {
+	if t.OCRMyPDF == "" {
+		return fmt.Errorf("ocrmypdf not found on PATH")
+	}
+	if outPDF == "" {
+		return fmt.Errorf("output PDF path required")
+	}
+	if lang == "" {
+		lang = "eng"
+	}
+	args := []string{"-l", lang, "--skip-big", "100"}
+	if force {
+		args = append(args, "--force-ocr")
+	} else {
+		args = append(args, "--skip-text")
+	}
+	args = append(args, inPath, outPDF)
+	cmd := exec.Command(t.OCRMyPDF, args...)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		// Retry with force if skip-text refused.
+		if !force && strings.Contains(stderr.String(), "PriorOcrFoundError") == false {
+			args2 := []string{"-l", lang, "--force-ocr", inPath, outPDF}
+			cmd2 := exec.Command(t.OCRMyPDF, args2...)
+			var stderr2 bytes.Buffer
+			cmd2.Stderr = &stderr2
+			if err2 := cmd2.Run(); err2 == nil {
+				return nil
+			}
+		}
+		return fmt.Errorf("ocrmypdf: %w (%s)", err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+// ImageToText OCRs a raster image with tesseract (stdout text).
+func (t Tools) ImageToText(imgPath, lang string) (string, error) {
+	if t.Tesseract == "" {
+		return "", fmt.Errorf("tesseract not found on PATH")
+	}
+	if lang == "" {
+		lang = "eng"
+	}
+	cmd := exec.Command(t.Tesseract, imgPath, "stdout", "-l", lang)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		return "", fmt.Errorf("tesseract: %w (%s)", err, strings.TrimSpace(stderr.String()))
+	}
+	return string(out), nil
+}
+
+// ExtractPDFText returns layout text from a PDF via pdftotext.
+func (t Tools) ExtractPDFText(pdfPath string) (string, error) {
+	if t.PDFToText == "" {
+		return "", fmt.Errorf("pdftotext not found on PATH")
+	}
+	cmd := exec.Command(t.PDFToText, "-layout", pdfPath, "-")
+	out, err := cmd.Output()
+	if err != nil {
+		return "", err
+	}
+	return string(out), nil
+}
+
+// Result of ToMarkdown.
+type Result struct {
+	Markdown   string
+	OCRPDFPath string // set when a searchable PDF was produced
+	DidOCR     bool
+	Source     string
+}
+
+// ToMarkdown turns a local file into Markdown text.
+// PDFs/images with weak/no text layer are OCR'd to a searchable PDF first (when tools exist).
+func (t Tools) ToMarkdown(path string, workDir string, lang string, minChars int) (Result, error) {
+	res := Result{Source: path}
+	ext := Ext(path)
+	switch ext {
+	case ".md", ".markdown", ".txt":
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return res, err
+		}
+		res.Markdown = string(b)
+		return res, nil
+	case ".docx", ".odt", ".rtf", ".html", ".htm":
+		if err := t.requirePandoc(); err != nil {
+			return res, err
+		}
+		tmp := filepath.Join(workDir, "out.md")
+		if err := t.ConvertFile(path, tmp); err != nil {
+			return res, err
+		}
+		b, err := os.ReadFile(tmp)
+		if err != nil {
+			return res, err
+		}
+		res.Markdown = string(b)
+		return res, nil
+	case ".pdf":
+		need, _ := t.NeedsOCR(path, minChars)
+		pdf := path
+		if need {
+			if workDir == "" {
+				workDir = os.TempDir()
+			}
+			outPDF := filepath.Join(workDir, trimExt(filepath.Base(path))+".ocr.pdf")
+			if err := t.OCRToPDF(path, outPDF, true, lang); err != nil {
+				return res, err
+			}
+			res.DidOCR = true
+			res.OCRPDFPath = outPDF
+			pdf = outPDF
+		}
+		text, err := t.ExtractPDFText(pdf)
+		if err != nil {
+			return res, err
+		}
+		res.Markdown = wrapMD(filepath.Base(path), text)
+		return res, nil
+	case ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp", ".gif", ".bmp":
+		if workDir == "" {
+			workDir = os.TempDir()
+		}
+		outPDF := filepath.Join(workDir, trimExt(filepath.Base(path))+".ocr.pdf")
+		if t.OCRMyPDF != "" {
+			if err := t.OCRToPDF(path, outPDF, true, lang); err == nil {
+				res.DidOCR = true
+				res.OCRPDFPath = outPDF
+				text, err := t.ExtractPDFText(outPDF)
+				if err != nil {
+					return res, err
+				}
+				res.Markdown = wrapMD(filepath.Base(path), text)
+				return res, nil
+			}
+		}
+		text, err := t.ImageToText(path, lang)
+		if err != nil {
+			return res, err
+		}
+		res.DidOCR = true
+		res.Markdown = wrapMD(filepath.Base(path), text)
+		return res, nil
+	default:
+		return res, fmt.Errorf("unsupported type %q for markdown extraction", ext)
+	}
+}
+
+func wrapMD(title, body string) string {
+	body = strings.TrimSpace(body)
+	if body == "" {
+		return "# " + title + "\n\n_(empty text layer)_\n"
+	}
+	return "# " + title + "\n\n" + body + "\n"
+}
+
+func trimExt(name string) string {
+	return strings.TrimSuffix(name, filepath.Ext(name))
+}
+
+// SiblingDOCX returns path with .docx extension replacing the original ext.
+func SiblingDOCX(mdPath string) string {
+	return strings.TrimSuffix(mdPath, Ext(mdPath)) + ".docx"
+}
+
+// EnsureDir creates parent directories for path.
+func EnsureDir(path string) error {
+	dir := filepath.Dir(path)
+	if dir == "" || dir == "." {
+		return nil
+	}
+	return os.MkdirAll(dir, 0o755)
+}

internal/docpipe/docpipe_test.go

@@ -0,0 +1,167 @@
+package docpipe
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestExt(t *testing.T) {
+	if Ext("Foo.PDF") != ".pdf" {
+		t.Fatalf("Ext: %q", Ext("Foo.PDF"))
+	}
+}
+
+func TestSiblingDOCX(t *testing.T) {
+	if got := SiblingDOCX("notes.md"); got != "notes.docx" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestWrapMD(t *testing.T) {
+	s := wrapMD("a.pdf", " hello ")
+	if !strings.HasPrefix(s, "# a.pdf\n") || !strings.Contains(s, "hello") {
+		t.Fatalf("wrap: %q", s)
+	}
+}
+
+func TestNeedsOCR_Image(t *testing.T) {
+	tools := LookPath()
+	need, err := tools.NeedsOCR("x.jpg", 0)
+	if err != nil || !need {
+		t.Fatalf("jpg should need OCR: need=%v err=%v", need, err)
+	}
+}
+
+func TestTxtToMarkdown_FixedWidthUsesCodeBlock(t *testing.T) {
+	var lines []string
+	for i := 0; i < 12; i++ {
+		lines = append(lines, "          column layout line "+strings.Repeat("x", 40))
+	}
+	in := strings.Join(lines, "\n")
+	md := TxtToMarkdown(in)
+	if !strings.HasPrefix(md, "```\n") || !strings.Contains(md, "```") {
+		t.Fatalf("expected code block: %q", md[:min(80, len(md))])
+	}
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func TestTxtToMarkdownPreservesLines(t *testing.T) {
+	in := "line1\nline2\n\nline4"
+	md := TxtToMarkdown(in)
+	if !strings.Contains(md, "line1  \n") || !strings.Contains(md, "line2  \n") {
+		t.Fatalf("hard breaks missing: %q", md)
+	}
+	if !strings.Contains(md, "line4  \n") {
+		t.Fatalf("last line: %q", md)
+	}
+}
+
+func TestTXTToDOCXPreservesLines(t *testing.T) {
+	tools := LookPath()
+	if tools.Pandoc == "" {
+		t.Skip("pandoc not installed")
+	}
+	dir := t.TempDir()
+	txt := filepath.Join(dir, "sample.txt")
+	docx := filepath.Join(dir, "sample.docx")
+	body := "MyBox Auto — resumen\nNº contrato: 123\n\nEstado: Vigente\n"
+	if err := os.WriteFile(txt, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := tools.TXTToDOCX(txt, docx); err != nil {
+		t.Fatal(err)
+	}
+	mdOut := filepath.Join(dir, "out.md")
+	if err := tools.DOCXToMD(docx, mdOut); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(mdOut)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(got)
+	for _, want := range []string{"MyBox Auto", "Nº contrato", "Estado: Vigente"} {
+		if !strings.Contains(s, want) {
+			t.Fatalf("missing %q in %q", want, s)
+		}
+	}
+	if strings.Contains(s, "MyBox Auto — resumen Nº") {
+		t.Fatalf("lines collapsed: %q", s)
+	}
+}
+
+func TestMDDocxRoundTrip(t *testing.T) {
+	tools := LookPath()
+	if tools.Pandoc == "" {
+		t.Skip("pandoc not installed")
+	}
+	dir := t.TempDir()
+	md := filepath.Join(dir, "n.md")
+	docx := filepath.Join(dir, "n.docx")
+	md2 := filepath.Join(dir, "n2.md")
+	if err := os.WriteFile(md, []byte("# Title\n\nHello **world**.\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := tools.MDToDOCX(md, docx); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(docx); err != nil {
+		t.Fatal(err)
+	}
+	if err := tools.DOCXToMD(docx, md2); err != nil {
+		t.Fatal(err)
+	}
+	b, err := os.ReadFile(md2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(b), "Hello") {
+		t.Fatalf("round-trip missing Hello: %s", b)
+	}
+}
+
+func TestOptimizePDF(t *testing.T) {
+	tools := LookPath()
+	if tools.Ghostscript == "" || tools.PDFToText == "" {
+		t.Skip("ghostscript/pdftotext not installed")
+	}
+	in := "/tmp/ccgg-original.pdf"
+	if _, err := os.Stat(in); err != nil {
+		t.Skip("local fixture not present")
+	}
+	dir := t.TempDir()
+	out := filepath.Join(dir, "out.pdf")
+	charsIn, err := tools.PDFTextLayerChars(in)
+	if err != nil || charsIn < 1000 {
+		t.Skip("fixture has no text layer")
+	}
+	if err := tools.OptimizePDF(in, out); err != nil {
+		t.Fatal(err)
+	}
+	charsOut, err := tools.PDFTextLayerChars(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if charsOut < charsIn/2 {
+		t.Fatalf("text layer lost: in=%d out=%d", charsIn, charsOut)
+	}
+}
+
+func TestToMarkdown_PlainMD(t *testing.T) {
+	tools := LookPath()
+	dir := t.TempDir()
+	p := filepath.Join(dir, "a.md")
+	_ = os.WriteFile(p, []byte("hi"), 0o644)
+	res, err := tools.ToMarkdown(p, dir, "eng", 0)
+	if err != nil || res.Markdown != "hi" {
+		t.Fatalf("got %+v err=%v", res, err)
+	}
+}

internal/docpipe/hocr.go

@@ -0,0 +1,153 @@
+package docpipe
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	hocr "github.com/eslider/go-hocr"
+)
+
+// HOCRResult is structured OCR output for agents.
+type HOCRResult struct {
+	HOCRPath string
+	Markdown string
+	YAML     string
+	DidOCR   bool
+	Source   string
+}
+
+// ImageToHOCR runs tesseract hOCR into outBase+".hocr" (tesseract adds the extension).
+// outBase must not include ".hocr". dpi 0 uses tesseract default; phone photos often need 200–300.
+func (t Tools) ImageToHOCR(imgPath, outBase, lang string, dpi int) (string, error) {
+	if t.Tesseract == "" {
+		return "", fmt.Errorf("tesseract not found on PATH")
+	}
+	if lang == "" {
+		lang = "eng"
+	}
+	if outBase == "" {
+		return "", fmt.Errorf("hOCR output base path required")
+	}
+	args := []string{imgPath, outBase, "-l", lang}
+	if dpi > 0 {
+		args = append(args, "--dpi", fmt.Sprintf("%d", dpi))
+	}
+	args = append(args, resolveHOCRConfig())
+	cmd := exec.Command(t.Tesseract, args...)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return "", fmt.Errorf("tesseract hocr: %w (%s)", err, strings.TrimSpace(stderr.String()))
+	}
+	out := outBase + ".hocr"
+	if _, err := os.Stat(out); err != nil {
+		// Some builds write .html
+		alt := outBase + ".html"
+		if _, err2 := os.Stat(alt); err2 == nil {
+			return alt, nil
+		}
+		return "", fmt.Errorf("tesseract hocr: missing output %s (%s)", out, strings.TrimSpace(stderr.String()))
+	}
+	return out, nil
+}
+
+// resolveHOCRConfig returns a tesseract config path that works when TESSDATA_PREFIX
+// points at a custom traineddata dir without relative "hocr" configs.
+func resolveHOCRConfig() string {
+	var candidates []string
+	if p := strings.TrimSpace(os.Getenv("TESSDATA_PREFIX")); p != "" {
+		candidates = append(candidates,
+			filepath.Join(p, "configs", "hocr"),
+			filepath.Join(p, "tessdata", "configs", "hocr"),
+		)
+	}
+	candidates = append(candidates,
+		"/usr/share/tesseract-ocr/5/tessdata/configs/hocr",
+		"/usr/share/tesseract-ocr/4.00/tessdata/configs/hocr",
+		"/usr/share/tessdata/configs/hocr",
+	)
+	for _, c := range candidates {
+		if _, err := os.Stat(c); err == nil {
+			return c
+		}
+	}
+	return "hocr"
+}
+
+// HOCRToMarkdown parses an hOCR file via go-hocr and returns Markdown (+ optional YAML).
+// Words with confidence in (0, minConf) are dropped; minConf 0 keeps all.
+func HOCRToMarkdown(hocrPath string, minConf float32) (md string, yml string, err error) {
+	doc, err := hocr.ReadFile(hocrPath)
+	if err != nil {
+		return "", "", fmt.Errorf("go-hocr: %w", err)
+	}
+	md = doc.ToMarkdown(minConf)
+	yml, err = doc.ToYaml()
+	if err != nil {
+		return md, "", err
+	}
+	return md, yml, nil
+}
+
+// ToHOCRMarkdown OCRs an image (or rasterizes first PDF page) to hOCR → Markdown/YAML.
+func (t Tools) ToHOCRMarkdown(path, workDir, lang string, dpi int, minConf float32) (HOCRResult, error) {
+	res := HOCRResult{Source: path}
+	if workDir == "" {
+		workDir = os.TempDir()
+	}
+	ext := Ext(path)
+	img := path
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp", ".gif", ".bmp":
+		// ok
+	case ".pdf":
+		raster, err := t.pdfFirstPagePNG(path, workDir)
+		if err != nil {
+			return res, err
+		}
+		img = raster
+		if dpi == 0 {
+			dpi = 300
+		}
+	default:
+		return res, fmt.Errorf("hOCR path expects image or PDF, got %q", ext)
+	}
+	base := filepath.Join(workDir, trimExt(filepath.Base(path))+".hocr-out")
+	hocrPath, err := t.ImageToHOCR(img, base, lang, dpi)
+	if err != nil {
+		return res, err
+	}
+	res.DidOCR = true
+	res.HOCRPath = hocrPath
+	md, yml, err := HOCRToMarkdown(hocrPath, minConf)
+	if err != nil {
+		return res, err
+	}
+	res.Markdown = wrapMD(filepath.Base(path), strings.TrimSpace(md))
+	res.YAML = yml
+	return res, nil
+}
+
+// pdfFirstPagePNG uses pdftoppm when available.
+func (t Tools) pdfFirstPagePNG(pdfPath, workDir string) (string, error) {
+	pdftoppm, err := exec.LookPath("pdftoppm")
+	if err != nil {
+		return "", fmt.Errorf("pdftoppm not found (needed to rasterize PDF for hOCR)")
+	}
+	outBase := filepath.Join(workDir, trimExt(filepath.Base(pdfPath))+".page")
+	cmd := exec.Command(pdftoppm, "-png", "-f", "1", "-singlefile", "-r", "200", pdfPath, outBase)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return "", fmt.Errorf("pdftoppm: %w (%s)", err, strings.TrimSpace(stderr.String()))
+	}
+	png := outBase + ".png"
+	if _, err := os.Stat(png); err != nil {
+		return "", fmt.Errorf("pdftoppm: missing %s", png)
+	}
+	return png, nil
+}

internal/docpipe/hocr_test.go

@@ -0,0 +1,49 @@
+package docpipe
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestHOCRToMarkdown_Fixture(t *testing.T) {
+	// Minimal hOCR 1.2 snippet
+	hocrXML := `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+  <title>tesseract</title>
+  <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+  <meta name="ocr-system" content="tesseract 5"/>
+  <meta name="ocr-capabilities" content="ocr_page ocr_carea ocr_par ocr_line ocrx_word"/>
+ </head>
+ <body>
+  <div class="ocr_page" id="page_1" title="image &quot;x.png&quot;; bbox 0 0 100 50; ppageno 0">
+   <div class="ocr_carea" id="block_1_1" title="bbox 0 0 100 50">
+    <p class="ocr_par" id="par_1_1" lang="eng" title="bbox 0 0 100 50">
+     <span class="ocr_line" id="line_1_1" title="bbox 0 0 100 20; baseline 0 0; x_size 20">
+      <span class="ocrx_word" id="word_1_1" title="bbox 0 0 40 20; x_wconf 96">Hello</span>
+      <span class="ocrx_word" id="word_1_2" title="bbox 45 0 100 20; x_wconf 92">world</span>
+     </span>
+    </p>
+   </div>
+  </div>
+ </body>
+</html>`
+	dir := t.TempDir()
+	p := filepath.Join(dir, "sample.hocr")
+	if err := os.WriteFile(p, []byte(hocrXML), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	md, yml, err := HOCRToMarkdown(p, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(md, "Hello") || !strings.Contains(md, "world") {
+		t.Fatalf("md=%q", md)
+	}
+	if !strings.Contains(yml, "Hello") {
+		t.Fatalf("yaml missing word: %s", yml)
+	}
+}

scripts/githooks/install.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# install.sh — symlinks the shared githooks (pre-push, pre-commit) into .git/hooks
+# for this repository. Safe to run repeatedly.
+#
+# Usage:
+#   ./scripts/githooks/install.sh
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+SRC="$ROOT/scripts/githooks"
+HOOKS="$ROOT/.git/hooks"
+
+mkdir -p "$HOOKS"
+chmod +x "$SRC"/secret-scan.sh "$SRC"/pre-push "$SRC"/pre-commit
+
+for h in pre-push pre-commit; do
+  if [[ -e "$HOOKS/$h" ]] && [[ ! -L "$HOOKS/$h" ]]; then
+    echo "error: $HOOKS/$h already exists and is not a symlink; remove it first" >&2
+    exit 1
+  fi
+  ln -sfn "$SRC/$h" "$HOOKS/$h"
+  echo "installed $h -> $SRC/$h"
+done
+echo "githooks installed for $(basename "$ROOT")"

scripts/githooks/pre-commit

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+#
+# pre-commit git hook — blocks a commit if staged changes contain a secret.
+# Scans only the staged (index) diff with gitleaks (via secret-scan.sh).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+ROOT="$(git rev-parse --show-toplevel)"
+if [[ "$SCRIPT_DIR" == "$ROOT/scripts/githooks" ]]; then
+  SCAN="$SCRIPT_DIR/secret-scan.sh"
+else
+  SCAN="$ROOT/scripts/githooks/secret-scan.sh"
+fi
+
+if ! "$SCAN" --staged; then
+  echo "pre-commit: LEAK FOUND in staged changes; commit BLOCKED. Remove the secret first." >&2
+  exit 1
+fi
+exit 0

scripts/githooks/pre-push

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# pre-push git hook — blocks a push if any NEW commit leaks a secret.
+#
+# Reads the refs being pushed from stdin (format:
+#   <local ref> <local sha> <remote ref> <remote sha>
+# per ref). Scans only the new commits with gitleaks (via secret-scan.sh) and
+# aborts (exit 1) if anything is found.
+#
+# Install: ln -s ../../scripts/githooks/pre-push .git/hooks/pre-push
+#          (or run scripts/githooks/install.sh)
+
+set -euo pipefail
+
+# Resolve symlinks so the hook works whether copied into .git/hooks or
+# symlinked from scripts/githooks (and in worktrees sharing the main repo hooks).
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+ROOT="$(git rev-parse --show-toplevel)"
+if [[ "$SCRIPT_DIR" == "$ROOT/scripts/githooks" ]]; then
+  SCAN="$SCRIPT_DIR/secret-scan.sh"
+else
+  SCAN="$ROOT/scripts/githooks/secret-scan.sh"
+fi
+
+zero=0000000000000000000000000000000000000000
+failed=0
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [[ -n "$local_sha" ]] || continue
+
+  # Deletion push — nothing to scan.
+  if [[ "$local_sha" == "$zero" ]]; then
+    continue
+  fi
+
+  # New branch (no remote ref yet): scan only the commits this branch ADDS over
+  # its merge-base with the integration branch (PR target), NOT all history.
+  # This keeps pre-existing historical leaks (see #140) from blocking new work.
+  if [[ "$remote_sha" == "$zero" ]]; then
+    base=""
+    for base_ref in origin/release/v1 origin/release/v2 origin/master origin/main; do
+      if git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
+        base="$(git merge-base "$base_ref" "$local_sha" 2>/dev/null)"
+        break
+      fi
+    done
+    if [[ -z "$base" ]] && git rev-parse --verify origin/HEAD >/dev/null 2>&1; then
+      base="$(git merge-base origin/HEAD "$local_sha" 2>/dev/null)"
+    fi
+    [[ -z "$base" ]] && base="$(git rev-list --max-parents=0 "$local_sha" 2>/dev/null | tail -1)"
+    range="${base}..${local_sha}"
+  else
+    range="${remote_sha}..${local_sha}"
+  fi
+
+  echo "secret-scan: scanning new commits ${range} (ref ${local_ref})"
+  if ! "$SCAN" --range "$range"; then
+    echo "secret-scan: LEAK FOUND in ${local_ref}; push BLOCKED. Remove the secret before pushing." >&2
+    failed=1
+  fi
+done
+
+if [[ "$failed" -ne 0 ]]; then
+  exit 1
+fi
+exit 0

scripts/githooks/secret-scan.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+#
+# secret-scan.sh — shared secret scanner used by git hooks (pre-push, pre-commit)
+# and by SE agents before any push.
+#
+# Scans ONLY the diff of new commits (or staged changes) with gitleaks, never the
+# full history. Fails (exit non-zero) on any finding, so a leaking push is blocked.
+#
+# Uses the gitleaks Docker image (gitleaks/gitleaks) if docker is available,
+# otherwise a locally installed `gitleaks` binary. No secret VALUES are ever
+# printed: findings are emitted redacted.
+#
+# Usage:
+#   secret-scan.sh <range>            scan a git log range, e.g. origin/release/v1..HEAD
+#   secret-scan.sh --staged           scan staged (index) changes
+#   secret-scan.sh --all              scan full history (warning: not for normal use)
+#
+# Exit codes: 0 = clean, 1 = leaks found (caller should abort), 2 = scan failed.
+
+set -euo pipefail
+
+GITLEAKS_IMAGE="zricethezav/gitleaks:latest"
+
+run_gitleaks() {
+  # $@ = gitleaks args; runs in current dir (a git repo).
+  if command -v gitleaks >/dev/null 2>&1; then
+    gitleaks "$@"
+  elif command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+    docker run --rm -v "$PWD:/repo" -w /repo "$GITLEAKS_IMAGE" "$@"
+  else
+    echo "error: secret-scan: neither 'gitleaks' binary nor docker image available" >&2
+    exit 2
+  fi
+}
+
+mode="${1:---range}"
+shift || true
+
+case "$mode" in
+  --range)
+    range="${1:?usage: secret-scan.sh <range>}"
+    run_gitleaks detect --source "$PWD" --no-banner --redact --log-opts="$range" >&2
+    ;;
+  --staged)
+    # Scan only staged (index) content: pipe `git diff --cached` through gitleaks --pipe.
+    git diff --cached --binary | run_gitleaks detect --pipe --no-banner --redact >&2
+    ;;
+  --all)
+    run_gitleaks detect --source "$PWD" --no-banner --redact >&2
+    ;;
+  *)
+    echo "error: secret-scan: unknown mode '$mode'" >&2
+    exit 2
+    ;;
+esac