feat(search): index embedded PDF attachment text (#42)

- FileClient composes FileStore/Searcher backends; Read()/Write()/Search()
  select REST/DAV/PG/ES with transient read fallback. Client.Files() returns
  it and *FileClient implements FileStore, so existing callers keep working.
- Entry gains backend-native Updated + folder FilesCount/FoldersCount so
  dav ls output round-trips.
- cmd/oo dav/projects files and cmd/office/fetch download/preview/delete go
  through FileStore; oo search goes through the facade.
- Mark transport methods that FileStore now abstracts as deprecated.

.env.example

@@ -41,3 +41,22 @@ ONLYOFFICE_PROJECT_ID=33
 # ONLYOFFICE_ES_URL=http://127.0.0.1:9200
 # ONLYOFFICE_ES_INDEX=files_file
 # ONLYOFFICE_TENANT=
+
+# Read-only SQL file store over the Community Server database (see
+# docs/community-server-db.md). The live portal runs MySQL; ONLYOFFICE_DSN is
+# `user:pass@tcp(host:port)/onlyoffice?parseTime=true`, or a `postgres://` URL.
+# ONLYOFFICE_DSN=
+# ONLYOFFICE_PG_DRIVER=          # postgres | mysql (auto-detected from DSN)
+# ONLYOFFICE_PG_TENANT=1         # falls back to ONLYOFFICE_TENANT
+# Alternatively build a PostgreSQL DSN from parts:
+# ONLYOFFICE_PG_HOST=
+# ONLYOFFICE_PG_PORT=5432
+# ONLYOFFICE_PG_USER=
+# ONLYOFFICE_PG_PASSWORD=
+# ONLYOFFICE_PG_DBNAME=onlyoffice
+# ONLYOFFICE_PG_SSLMODE=disable
+
+# oo index / oo search --backend own — own full-text index for PDF/scans,
+# filled by `oo index` from internal/docpipe (pdftotext + OCR). Defaults to
+# oo_docs_text. Uses the same ONLYOFFICE_ES_URL.
+# ONLYOFFICE_ES_TEXT_INDEX=oo_docs_text

README.md

@@ -697,6 +697,27 @@ oo search "Rechnung" --json                   # shorthand for -o json
 Requires `ONLYOFFICE_ES_URL` (plus optional `ONLYOFFICE_ES_INDEX`,
 `ONLYOFFICE_TENANT`).
 
+#### PDF/scans: own index (`oo index` + `--backend own`)
+
+The OnlyOffice index covers Office formats only, so PDFs (`S1019`-style invoice
+numbers) are not searchable by content. `oo index` extracts PDF text with
+`internal/docpipe` (pdftotext, OCR for scans) — including the text of embedded
+PDF attachments (`pdfdetach`: `<doc>.md`, `.xml`, covers the original/scan and
+ZUGFeRD e-invoice XML) — into a separate index (`ONLYOFFICE_ES_TEXT_INDEX`,
+default `oo_docs_text`); the OnlyOffice server and its index are **not**
+modified. Then search it with `--backend own`.
+
+```bash
+oo index folder 634 --recursive --exts pdf    # populate (idempotent upsert)
+oo index files 3576 3578                      # specific files
+oo index folder 634 --dry-run                 # plan only
+oo search "S1021" --content --backend own     # finds the PDF
+oo search "Rechnung" --backend own --folder 634 --json
+```
+
+See [`docs/elasticsearch.md`](docs/elasticsearch.md) for the decision and
+trade-offs.
+
 ### Bulk tools (`cmd/`)
 
 Small single-purpose binaries for bulk Documents work. All of them pace
@@ -733,7 +754,8 @@ kontolink IN.xlsx oo-index.tsv OUT.xlsx [FILE_ID] [AMOUNTS_TSV]
 | `docs` | `tools`, `convert`, `optimize`, `ocr`, `hocr`, `as-md`, `put-md`, `put-txt`, `put-xlsx` |
 | `catalog` | `match`, `merge`, `apply`, `scan-contacts`, `scan-projects`, `scan-thunderbird` |
 | `dav` | `ls`, `move`, `copy`, `mkdir`, `rename-file`, `rename-folder`, `download`, `fileops` |
-| `search` | `QUERY` (`--content`, `--folder ID`, `--limit N`, `--json`) |
+| `search` | `QUERY` (`--content`, `--folder ID`, `--limit N`, `--backend oo\|own`, `--json`) |
+| `index` | `folder FOLDER_ID`, `files FILE_ID...` (`--recursive`, `--exts pdf`, `--limit N`, `--dry-run`) |
 
 The CLI reads only `.env` from the current working directory (godotenv is a
 CLI-only concern — the library itself never loads dotfiles).

cmd/office/fetch/list.go

@@ -17,6 +17,18 @@ const MailListPageSize = 25
 // Loader fetches list items for a menu subject using the OnlyOffice client.
 type Loader struct {
 	Client *onlyoffice.Client
+
+	// Files is the backend-agnostic file store used for file download, preview
+	// and delete. When nil it falls back to Client.FileStore(ProviderREST).
+	Files onlyoffice.FileStore
+}
+
+// fileStore returns the configured file store, defaulting to REST.
+func (l *Loader) fileStore() onlyoffice.FileStore {
+	if l.Files != nil {
+		return l.Files
+	}
+	return l.Client.FileStore(onlyoffice.ProviderREST)
 }
 
 // List returns items for the given list spec (nav leaf).
@@ -171,11 +183,7 @@ func (l *Loader) executeDelete(ctx context.Context, item model.Item) (string, er
 		}
 		return fmt.Sprintf("Deleted message %s", item.Title), nil
 	case model.KindFile:
-		id, err := strconv.Atoi(item.ID)
+		if err := l.fileStore().Delete(ctx, []string{item.ID}); err != nil {
-		if err != nil {
-			return "", err
-		}
-		if err := l.Client.DeleteFiles(ctx, []int{id}); err != nil {
 			return "", err
 		}
 		return fmt.Sprintf("Deleted file %s", item.Title), nil
@@ -199,7 +207,7 @@ func (l *Loader) executeDownload(ctx context.Context, item model.Item, destPath
 		return "", err
 	}
 	defer f.Close()
-	if _, err := l.Client.DownloadFile(ctx, item.ID, f); err != nil {
+	if _, err := l.fileStore().Download(ctx, item.ID, f); err != nil {
 		return "", err
 	}
 	return fmt.Sprintf("Downloaded to %s", destPath), nil

cmd/office/fetch/preview.go

@@ -5,7 +5,6 @@ import (
 	"context"
 	"fmt"
 
-	onlyoffice "github.com/eslider/go-onlyoffice"
 	"github.com/eslider/go-onlyoffice/cmd/office/model"
 	"github.com/eslider/go-onlyoffice/cmd/office/preview"
 )
@@ -30,13 +29,11 @@ func (l *Loader) filePreviewMarkdown(ctx context.Context, item model.Item) (stri
 		return "", fmt.Errorf("file id missing")
 	}
 	name := item.Title
-	if meta, err := l.Client.GetFile(ctx, item.ID); err == nil && meta != nil {
+	if e, err := l.fileStore().Stat(ctx, item.ID); err == nil && e.Title != "" {
-		if t := onlyoffice.FileEntryTitle(meta); t != "" {
+		name = e.Title
-			name = t
-		}
 	}
 	var buf bytes.Buffer
-	if _, err := l.Client.DownloadFile(ctx, item.ID, &buf); err != nil {
+	if _, err := l.fileStore().Download(ctx, item.ID, &buf); err != nil {
 		return "", err
 	}
 	return preview.FileBytesToMarkdown(name, buf.Bytes())

cmd/oo/dav.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"time"
 
 	onlyoffice "github.com/eslider/go-onlyoffice"
 	"github.com/spf13/cobra"
@@ -12,8 +13,8 @@ func init() {
 	rootCmd.AddCommand(davCmd())
 }
 
-// davCmd exposes the Documents module through the same Dav calls that back
+// davCmd exposes the Documents module through the backend-agnostic FileStore
-// oo-webdav (ListDavFolder / MoveDavItems / CopyDavItems / DownloadDavFile).
+// (DAV backend). The underlying Dav calls are the oo-webdav proven path:
 // MoveDavItems sends resolveType=Skip + holdResult=true, which the legacy
 // fileops/move call without those params silently ignores (200 without move).
 func davCmd() *cobra.Command {
@@ -61,59 +62,46 @@ func davLsCmd() *cobra.Command {
 				printTable([]string{"id", "title", "filesCount", "foldersCount"}, rows)
 				return nil
 			}
-			l, err := c.ListDavFolder(ctx, args[0])
+			entries, err := c.FileStore(onlyoffice.ProviderDAV).List(ctx, args[0])
 			if err != nil {
 				return err
 			}
-			if outputFormat == "json" {
+			folders := make([]onlyoffice.Entry, 0, len(entries))
-				folders := make([]map[string]any, 0, len(l.Folders))
+			files := make([]onlyoffice.Entry, 0, len(entries))
-				for _, f := range l.Folders {
+			for _, e := range entries {
-					folders = append(folders, map[string]any{
+				if e.Kind == onlyoffice.Folder {
-						"id":           f.ID,
+					folders = append(folders, e)
-						"title":        f.Title,
+				} else {
-						"filesCount":   f.FilesCount,
+					files = append(files, e)
-						"foldersCount": f.FoldersCount,
-					})
 				}
-				files := make([]map[string]any, 0, len(l.Files))
-				for _, f := range l.Files {
-					files = append(files, map[string]any{
-						"id":      f.ID,
-						"title":   f.Title,
-						"size":    f.Size,
-						"updated": f.Updated,
-					})
-				}
-				printObject(map[string]any{"folders": folders, "files": files})
-				return nil
 			}
-			if len(l.Folders) > 0 {
+			frows := make([]map[string]any, 0, len(folders))
-				frows := make([]map[string]any, 0, len(l.Folders))
+			for _, f := range folders {
-				for _, f := range l.Folders {
+				frows = append(frows, map[string]any{
-					frows = append(frows, map[string]any{
+					"id":           f.ID,
-						"id":           f.ID,
+					"title":        f.Title,
-						"title":        f.Title,
+					"filesCount":   f.FilesCount,
-						"filesCount":   f.FilesCount,
+					"foldersCount": f.FoldersCount,
-						"foldersCount": f.FoldersCount,
+				})
-					})
-				}
-				if outputFormat == "table" {
-					fmt.Println("folders:")
-				}
-				printTable([]string{"id", "title", "filesCount", "foldersCount"}, frows)
 			}
-			rows := make([]map[string]any, 0, len(l.Files))
+			rows := make([]map[string]any, 0, len(files))
-			for _, f := range l.Files {
+			for _, f := range files {
 				rows = append(rows, map[string]any{
 					"id":      f.ID,
 					"title":   f.Title,
 					"size":    f.Size,
-					"updated": f.Updated,
+					"updated": entryUpdated(f),
 				})
 			}
-			if outputFormat == "table" {
+			if outputFormat == "json" {
-				fmt.Println("files:")
+				printObject(map[string]any{"folders": frows, "files": rows})
+				return nil
 			}
+			if len(frows) > 0 {
+				fmt.Println("folders:")
+				printTable([]string{"id", "title", "filesCount", "foldersCount"}, frows)
+			}
+			fmt.Println("files:")
 			printTable([]string{"id", "title", "size", "updated"}, rows)
 			return nil
 		},
@@ -121,6 +109,18 @@ func davLsCmd() *cobra.Command {
 	return cmd
 }
 
+// entryUpdated prefers the backend-native timestamp string so table/JSON output
+// round-trips what the API returned.
+func entryUpdated(e onlyoffice.Entry) string {
+	if e.Updated != "" {
+		return e.Updated
+	}
+	if e.Modified.IsZero() {
+		return ""
+	}
+	return e.Modified.Format(time.RFC3339)
+}
+
 func davMoveCmd() *cobra.Command {
 	var folderIDs []string
 	cmd := &cobra.Command{
@@ -132,7 +132,8 @@ func davMoveCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if err := c.MoveDavItems(cmd.Context(), folderIDs, args[1:], args[0]); err != nil {
+			ids := append(append([]string{}, folderIDs...), args[1:]...)
+			if err := c.FileStore(onlyoffice.ProviderDAV).Move(cmd.Context(), ids, args[0]); err != nil {
 				return err
 			}
 			printObject(map[string]any{"moved_files": args[1:], "moved_folders": folderIDs, "dest": args[0]})
@@ -154,7 +155,8 @@ func davCopyCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if err := c.CopyDavItems(cmd.Context(), folderIDs, args[1:], args[0]); err != nil {
+			ids := append(append([]string{}, folderIDs...), args[1:]...)
+			if err := c.FileStore(onlyoffice.ProviderDAV).Copy(cmd.Context(), ids, args[0]); err != nil {
 				return err
 			}
 			printObject(map[string]any{"copied_files": args[1:], "copied_folders": folderIDs, "dest": args[0]})
@@ -175,7 +177,7 @@ func davMkdirCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			f, err := c.CreateDavFolder(cmd.Context(), args[0], args[1])
+			f, err := c.FileStore(onlyoffice.ProviderDAV).CreateFolder(cmd.Context(), args[0], args[1])
 			if err != nil {
 				return err
 			}
@@ -200,7 +202,8 @@ func davRemoveCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if err := c.DeleteDavItems(cmd.Context(), folderIDs, args); err != nil {
+			ids := append(append([]string{}, args...), folderIDs...)
+			if err := c.FileStore(onlyoffice.ProviderDAV).Delete(cmd.Context(), ids); err != nil {
 				return err
 			}
 			printObject(map[string]any{"deleted_files": args, "deleted_folders": folderIDs})
@@ -221,7 +224,7 @@ func davRenameFileCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if err := c.RenameDavFile(cmd.Context(), args[0], args[1]); err != nil {
+			if err := c.FileStore(onlyoffice.ProviderDAV).Rename(cmd.Context(), args[0], args[1]); err != nil {
 				return err
 			}
 			printObject(map[string]any{"id": args[0], "title": args[1]})
@@ -240,7 +243,7 @@ func davRenameFolderCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if err := c.RenameDavFolder(cmd.Context(), args[0], args[1]); err != nil {
+			if err := c.FileStore(onlyoffice.ProviderDAV).Rename(cmd.Context(), args[0], args[1]); err != nil {
 				return err
 			}
 			printObject(map[string]any{"id": args[0], "title": args[1]})
@@ -261,20 +264,21 @@ func davDownloadCmd() *cobra.Command {
 				return err
 			}
 			ctx := cmd.Context()
-			f, err := c.GetFile(ctx, args[0])
+			store := c.FileStore(onlyoffice.ProviderDAV)
+			e, err := store.Stat(ctx, args[0])
 			if err != nil {
 				return err
 			}
 			path := to
 			if path == "" {
-				path = onlyoffice.SafeLocalFileName(onlyoffice.FileEntryTitle(f))
+				path = onlyoffice.SafeLocalFileName(e.Title)
 			}
 			out, err := os.Create(path)
 			if err != nil {
 				return err
 			}
 			defer out.Close()
-			n, err := c.DownloadDavFile(ctx, args[0], out)
+			n, err := store.Download(ctx, args[0], out)
 			if err != nil {
 				_ = os.Remove(path)
 				return err

cmd/oo/index.go

@@ -0,0 +1,158 @@
+package main
+
+import (
+	"strings"
+
+	onlyoffice "github.com/eslider/go-onlyoffice"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(indexCmd())
+}
+
+// indexFlags are shared by the `oo index folder` and `oo index files` verbs.
+type indexFlags struct {
+	recursive bool
+	exts      string
+	limit     int
+	workers   int
+	lang      string
+	minChars  int
+	workDir   string
+	backend   string
+	dryRun    bool
+	asJSON    bool
+}
+
+// indexCmd populates the own full-text index (oo_docs_text) that makes PDF and
+// scanned content searchable. The OnlyOffice index is left untouched.
+func indexCmd() *cobra.Command {
+	f := &indexFlags{}
+	cmd := &cobra.Command{
+		Use:   "index",
+		Short: "Populate the own full-text index for PDF/scan content",
+		Long: "Index document text that the OnlyOffice Elasticsearch index does not\n" +
+			"cover (PDFs and scans) into a separate index (ONLYOFFICE_ES_TEXT_INDEX,\n" +
+			"default oo_docs_text). Text is extracted with docpipe (pdftotext, OCR)\n" +
+			"and the OnlyOffice server is never modified.\n\n" +
+			"Requires ONLYOFFICE_URL/USER/PASS (to download files) and ONLYOFFICE_ES_URL\n" +
+			"(to write the index). See docs/elasticsearch.md.",
+	}
+	cmd.PersistentFlags().BoolVar(&f.recursive, "recursive", false, "folder: descend into subfolders")
+	cmd.PersistentFlags().StringVar(&f.exts, "exts", "pdf", "comma-separated extensions to index")
+	cmd.PersistentFlags().IntVar(&f.limit, "limit", 0, "maximum number of files to index (0 = all)")
+	cmd.PersistentFlags().IntVar(&f.workers, "workers", 3, "parallel downloads/extractions")
+	cmd.PersistentFlags().StringVar(&f.lang, "lang", "deu+eng", "OCR language(s)")
+	cmd.PersistentFlags().IntVar(&f.minChars, "min-chars", 0, "text-layer threshold below which OCR runs")
+	cmd.PersistentFlags().StringVar(&f.workDir, "work-dir", "", "temp dir for downloads (default: system temp)")
+	cmd.PersistentFlags().StringVar(&f.backend, "backend", "rest", "file backend: rest|dav")
+	cmd.PersistentFlags().BoolVar(&f.dryRun, "dry-run", false, "list what would be indexed, without changes")
+	cmd.PersistentFlags().BoolVar(&f.asJSON, "json", false, "shorthand for --output json")
+
+	cmd.AddCommand(indexFolderCmd(f), indexFilesCmd(f))
+	return cmd
+}
+
+func indexFolderCmd(f *indexFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "folder FOLDER_ID",
+		Short: "Index every matching file in a Documents folder",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runIndex(cmd, f, args[0], nil)
+		},
+	}
+}
+
+func indexFilesCmd(f *indexFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "files FILE_ID...",
+		Short: "Index specific Documents files",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runIndex(cmd, f, "", args)
+		},
+	}
+}
+
+func runIndex(cmd *cobra.Command, f *indexFlags, folderID string, ids []string) error {
+	if f.asJSON {
+		outputFormat = "json"
+	}
+	c, err := newOO(cmd)
+	if err != nil {
+		return err
+	}
+	idx, err := onlyoffice.NewESTextIndex(onlyoffice.ESTextConfigFromEnv())
+	if err != nil {
+		return err
+	}
+	ti := onlyoffice.NewTextIndexer(c.FileStore(f.backend), idx)
+	ti.WorkDir = f.workDir
+	opts := onlyoffice.IndexOptions{
+		Recursive:  f.recursive,
+		Extensions: splitList(f.exts),
+		Limit:      f.limit,
+		Lang:       f.lang,
+		MinChars:   f.minChars,
+		Workers:    f.workers,
+	}
+	ctx := cmd.Context()
+
+	if f.dryRun {
+		var entries []onlyoffice.Entry
+		if folderID != "" {
+			entries, err = ti.PlanFolder(ctx, folderID, opts)
+		} else {
+			entries, err = ti.PlanFiles(ctx, ids, opts)
+		}
+		if err != nil {
+			return err
+		}
+		rows := make([]map[string]any, 0, len(entries))
+		for _, e := range entries {
+			rows = append(rows, map[string]any{
+				"id":     e.ID,
+				"title":  e.Title,
+				"folder": e.ParentID,
+			})
+		}
+		printTable([]string{"id", "title", "folder"}, rows)
+		return nil
+	}
+
+	if err := ti.Ensure(ctx); err != nil {
+		return err
+	}
+	var res onlyoffice.IndexResult
+	if folderID != "" {
+		res, err = ti.IndexFolder(ctx, folderID, opts)
+	} else {
+		res, err = ti.IndexFiles(ctx, ids, opts)
+	}
+	if err != nil {
+		return err
+	}
+	printObject(map[string]any{
+		"index":   idx.Index(),
+		"scanned": res.Scanned,
+		"indexed": res.Indexed,
+		"skipped": res.Skipped,
+		"failed":  res.Failed,
+		"errors":  res.Errors,
+	})
+	return nil
+}
+
+// splitList parses a comma-separated flag value, dropping blanks.
+func splitList(s string) []string {
+	parts := strings.Split(s, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}

cmd/oo/index_test.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestIndexCommandRegistered(t *testing.T) {
+	cmd, _, err := rootCmd.Find([]string{"index"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cmd.Name() != "index" {
+		t.Fatalf("index resolved to %q", cmd.Name())
+	}
+	for _, name := range []string{"exts", "limit", "workers", "lang", "min-chars", "work-dir", "backend", "dry-run", "recursive", "json"} {
+		if cmd.PersistentFlags().Lookup(name) == nil {
+			t.Errorf("index: missing --%s flag", name)
+		}
+	}
+	if cmd.PersistentFlags().Lookup("exts").DefValue != "pdf" {
+		t.Errorf("--exts default = %q, want pdf", cmd.PersistentFlags().Lookup("exts").DefValue)
+	}
+	for _, verb := range []string{"index folder", "index files"} {
+		sub, _, err := rootCmd.Find(strings.Fields(verb))
+		if err != nil {
+			t.Fatalf("%s: %v", verb, err)
+		}
+		if sub.Name() != strings.Fields(verb)[1] {
+			t.Errorf("%s resolved to %q", verb, sub.Name())
+		}
+	}
+}
+
+func TestIndexSearchBackendFlag(t *testing.T) {
+	cmd, _, err := rootCmd.Find([]string{"search"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cmd.Flags().Lookup("backend") == nil {
+		t.Fatal("search: missing --backend flag")
+	}
+	if cmd.Flags().Lookup("backend").DefValue != "oo" {
+		t.Errorf("--backend default = %q, want oo", cmd.Flags().Lookup("backend").DefValue)
+	}
+}
+
+func TestSplitList(t *testing.T) {
+	got := splitList(" pdf , .PDF, docx ,, ")
+	want := []string{"pdf", ".PDF", "docx"}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("splitList = %v, want %v", got, want)
+	}
+}

cmd/oo/main.go

@@ -18,7 +18,8 @@
 //	oo docs          tools | convert | optimize | ocr | hocr | as-md | put-md | put-txt | put-xlsx
 //	oo catalog       match | merge | apply | scan-contacts | scan-projects | scan-thunderbird
 //	oo dav           ls | move | copy | mkdir | rename-file | rename-folder | download | fileops
-//	oo search        QUERY [--content] [--folder ID] [--limit N] [--json]
+//	oo search        QUERY [--content] [--folder ID] [--limit N] [--backend oo|own] [--json]
+//	oo index         folder FOLDER_ID | files FILE_ID... [--recursive] [--exts pdf] [--dry-run]
 //
 // CRM association rules: docs/crm-associations.md
 //

cmd/oo/projects_files.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"path/filepath"
 	"strconv"
 	"time"
 
@@ -159,20 +160,22 @@ func prjFilesDownloadCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			f, err := c.GetFile(cmd.Context(), args[0])
+			ctx := cmd.Context()
+			store := c.Files()
+			e, err := store.Stat(ctx, args[0])
 			if err != nil {
 				return err
 			}
 			path := to
 			if path == "" {
-				path = onlyoffice.SafeLocalFileName(onlyoffice.FileEntryTitle(f))
+				path = onlyoffice.SafeLocalFileName(e.Title)
 			}
 			out, err := os.Create(path)
 			if err != nil {
 				return err
 			}
 			defer out.Close()
-			n, err := c.DownloadFile(cmd.Context(), args[0], out)
+			n, err := store.Download(ctx, args[0], out)
 			if err != nil {
 				_ = os.Remove(path)
 				return err
@@ -199,11 +202,16 @@ func prjFilesRenameCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			entry, err := c.RenameFile(cmd.Context(), args[0], args[1])
+			store := c.Files()
+			if err := store.Rename(cmd.Context(), args[0], args[1]); err != nil {
+				return err
+			}
+			entry, err := store.Stat(cmd.Context(), args[0])
 			if err != nil {
 				return err
 			}
-			printObject(fileEntryToMap(entry))
+			entry.Title = args[1]
+			printObject(entryToMap(entry))
 			return nil
 		},
 	}
@@ -228,7 +236,7 @@ func prjFilesDeleteCmd() *cobra.Command {
 				}
 				ids = append(ids, id)
 			}
-			if err := c.DeleteFiles(cmd.Context(), ids); err != nil {
+			if err := c.Files().Delete(cmd.Context(), args); err != nil {
 				return err
 			}
 			printObject(map[string]any{"deleted": ids})
@@ -317,6 +325,29 @@ func fileEntryToMap(f *onlyoffice.FileEntry) map[string]any {
 	return m
 }
 
+// entryToMap renders a canonical Entry with the same keys as fileEntryToMap.
+func entryToMap(e onlyoffice.Entry) map[string]any {
+	m := map[string]any{
+		"id":            e.ID,
+		"title":         e.Title,
+		"fileExst":      filepath.Ext(e.Title),
+		"contentLength": contentLengthString(e.Size),
+	}
+	if e.Updated != "" {
+		m["updated"] = e.Updated
+	} else if !e.Modified.IsZero() {
+		m["updated"] = e.Modified.Format(time.RFC3339)
+	}
+	return m
+}
+
+func contentLengthString(n int64) string {
+	if n <= 0 {
+		return ""
+	}
+	return strconv.FormatInt(n, 10)
+}
+
 func fileIDStr(f *onlyoffice.FileEntry) string {
 	if f == nil || f.ID == nil {
 		return ""

cmd/oo/search.go

@@ -1,7 +1,11 @@
 package main
 
 import (
+	"fmt"
+	"strings"
+
 	onlyoffice "github.com/eslider/go-onlyoffice"
+	"github.com/eslider/go-onlyoffice/cmd/internal/bootstrap"
 	"github.com/spf13/cobra"
 )
 
@@ -9,14 +13,15 @@ func init() {
 	rootCmd.AddCommand(searchCmd())
 }
 
-// searchCmd queries the OnlyOffice Elasticsearch index directly. The REST
+// searchCmd queries the OnlyOffice document index through the file facade. The
-// /api/2.0/files/@search endpoint only searches file names in the database;
+// REST /api/2.0/files/@search endpoint only searches file names in the database;
-// content search needs ES (see docs/elasticsearch.md).
+// content search needs Elasticsearch (see docs/elasticsearch.md).
 func searchCmd() *cobra.Command {
 	var (
 		content bool
 		folder  string
 		limit   int
+		backend string
 		asJSON  bool
 	)
 	cmd := &cobra.Command{
@@ -26,6 +31,9 @@ func searchCmd() *cobra.Command {
 			"By default only file names are matched. With --content the query also\n" +
 			"matches extracted document text (document.attachment.content); this covers\n" +
 			"Office formats (docx/xlsx/pptx) and is slower.\n\n" +
+			"--backend own queries the separate index populated by `oo index`\n" +
+			"(ONLYOFFICE_ES_TEXT_INDEX, default oo_docs_text) instead, which also holds\n" +
+			"PDFs and scans (see docs/elasticsearch.md).\n\n" +
 			"Requires ONLYOFFICE_ES_URL (and optionally ONLYOFFICE_ES_INDEX,\n" +
 			"ONLYOFFICE_TENANT). See docs/elasticsearch.md for the tunnel setup.",
 		Args: cobra.ExactArgs(1),
@@ -33,11 +41,24 @@ func searchCmd() *cobra.Command {
 			if asJSON {
 				outputFormat = "json"
 			}
-			es, err := onlyoffice.NewESSearcher(onlyoffice.ESConfigFromEnv())
+			bootstrap.LoadEnv()
+			c := onlyoffice.NewClient(onlyoffice.GetEnvironmentCredentials())
+			var (
+				searcher onlyoffice.Searcher
+				err      error
+			)
+			switch strings.ToLower(strings.TrimSpace(backend)) {
+			case "", "oo", "elasticsearch":
+				searcher, err = c.Files().Search()
+			case "own", "es-text":
+				searcher, err = onlyoffice.NewESTextIndex(onlyoffice.ESTextConfigFromEnv())
+			default:
+				return fmt.Errorf("unknown search backend %q (want oo|own)", backend)
+			}
 			if err != nil {
 				return err
 			}
-			hits, err := es.Search(cmd.Context(), onlyoffice.SearchQuery{
+			hits, err := searcher.Search(cmd.Context(), onlyoffice.SearchQuery{
 				Text:      args[0],
 				InContent: content,
 				FolderID:  folder,
@@ -67,6 +88,7 @@ func searchCmd() *cobra.Command {
 	cmd.Flags().BoolVar(&content, "content", false, "also match extracted document content")
 	cmd.Flags().StringVar(&folder, "folder", "", "limit to a Documents folder id")
 	cmd.Flags().IntVar(&limit, "limit", 20, "maximum number of results")
+	cmd.Flags().StringVar(&backend, "backend", "oo", "index to query: oo (OnlyOffice) | own (oo index)")
 	cmd.Flags().BoolVar(&asJSON, "json", false, "shorthand for --output json")
 	return cmd
 }

docs/community-server-db.md

@@ -0,0 +1,130 @@
+---
+type: reference
+status: current
+related:
+  - README.md
+  - file_pg.go
+  - docs/elasticsearch.md
+---
+
+# Community Server DB — прямой SQL-доступ (read-only)
+
+## Что это
+
+Бэкенд `pgStore` (`file_pg.go`) читает файлы и папки **напрямую из БД
+Community Server**, без HTTP-слоя. Реализует `FileStore` (`List`/`Stat`/
+`Download`) и `Searcher` по имени. Запись запрещена: все write-методы
+возвращают `ErrReadOnly`.
+
+## Что за БД (research, live)
+
+Проверено на VM `onlyoffice-v2` (SSH `127.0.0.1:32`):
+
+- Community Server работает на **MySQL 8.0**, не на PostgreSQL.
+  - Хост: `127.0.0.1:3306` внутри VM, база `onlyoffice`.
+  - Конфиг: `/etc/onlyoffice/communityserver/appsettings.production.json`,
+    `providerName: MySql.Data.MySqlClient`.
+  - Таблицы: `files_file`, `files_folder`, `files_folder_tree`,
+    `files_security`, тенанты — `tenants_tenants` (не `tenants`).
+- PostgreSQL 16 в той же VM — **наш** контур (`edw_docs`, роли `edw`/`edw_ro`,
+  office-assistant), к OnlyOffice отношения не имеет. `files_file` в PG нет.
+- Портал хранит файлы в **S3/MinIO** (DiscStorage только для мелочи).
+  Бакет `office`, объект — по ключу (см. ниже).
+
+Вывод: бэкенд назван по issue «PostgreSQL», но живой источник — MySQL.
+`database/sql` + драйвер по DSN: `mysql` для MySQL, `pgx` для PostgreSQL.
+`Name()` возвращает фактический движок (`mysql` или `postgres`).
+
+## Схема
+
+`files_file` — одна строка **на версию** (PK `tenant_id, id, version`):
+
+| поле | смысл |
+|------|-------|
+| `id` | id файла (тот же, что в REST/ES) |
+| `version` | номер версии этой строки |
+| `version_group` | номер версии |
+| `current_version` | `1` = текущая версия, `0` = старая |
+| `folder_id` | id родительской папки |
+| `title` | имя файла с расширением |
+| `content_length` | размер в байтах |
+| `create_on`, `modified_on` | даты (UTC, без зоны) |
+| `tenant_id` | тенант (портал) |
+
+`files_folder`: `id`, `parent_id`, `title`, `create_on`, `modified_on`,
+`tenant_id`. `files_folder_tree`: `folder_id`, `parent_id`, `level` — готовое
+дерево, пока не используется.
+
+Текущую строку файла берём по `current_version = 1`.
+
+## Доступ (SSH-туннель)
+
+MySQL слушает только `127.0.0.1:3306` внутри VM. Снаружи — SSH-туннель
+(SSH в VM открыт как `127.0.0.1:32`):
+
+```bash
+ssh -f -N -o ControlMaster=no -o ControlPath=none \
+    -p 32 -i ~/.ssh/id_ed25519 \
+    -L 13306:127.0.0.1:3306 root@127.0.0.1
+
+# MySQL DSN затем:
+# root:<pw>@tcp(127.0.0.1:13306)/onlyoffice?parseTime=true
+```
+
+`-o ControlMaster=no -o ControlPath=none` обязательны: иначе forward уходит в
+persistent master из `~/.ssh/config`.
+
+## Переменные
+
+| env | default | смысл |
+|-----|---------|-------|
+| `ONLYOFFICE_DSN` | — | DSN драйвера (MySQL `...@tcp(...)/...` или `postgres://...`) |
+| `ONLYOFFICE_PG_DRIVER` | авто | `postgres` или `mysql`; иначе по форме DSN |
+| `ONLYOFFICE_PG_TENANT` | `ONLYOFFICE_TENANT` | фильтр `tenant_id` (пусто = все) |
+| `ONLYOFFICE_PG_HOST/PORT/USER/PASSWORD/DBNAME/SSLMODE` | — | собрать PG DSN, если `ONLYOFFICE_DSN` пуст |
+
+Имена — в [`.env.example`](../.env.example). Секретов нет.
+
+## Download (MinIO)
+
+`Download` не ходит в REST. Ключ объекта собирается из строки `files_file`:
+
+```
+00/00/<tenant>/files/folder_<shard>/file_<id>/v<version>/content.<ext>
+shard = (id/1000 + 1) * 1000
+```
+
+`shard` — не `folder_id`, а следующая тысяча над `id` (файл 3727 →
+`folder_4000`). Проверено live по бакету `office`.
+
+Стриминг переиспользует `downloadMinioObject` из `storage_fallback.go`
+(та же подпись SigV4 и `MINIO_*`), без дублирования.
+
+## Тесты
+
+```bash
+go test ./...                              # unit: rebind, csObjectKey, маппинг
+go test -race ./...
+
+# integration (нужен DSN; skip без него)
+ONLYOFFICE_DSN='root:<pw>@tcp(127.0.0.1:13306)/onlyoffice?parseTime=true' \
+ONLYOFFICE_PG_TENANT=1 \
+ONLYOFFICE_PG_TEST_FILE_ID=22484 \
+ONLYOFFICE_PG_TEST_FOLDER_ID=649 \
+MINIO_ACCESS_KEY=... MINIO_SECRET_KEY=... \
+  go test -tags=integration -run TestIntegrationPGStore -v ./...
+```
+
+Integration сверяет `Stat`/`List`/`Download` с REST (`c.Files()`) и проверяет,
+что write-методы дают `ErrReadOnly`.
+
+## Грабли
+
+- MySQL хранит `datetime` без зоны; `parseTime=true` (ставится автоматически)
+  читает их как UTC. REST отдаёт `+02:00` — сравнивать моменты, не строки.
+- `GetFile` (REST) не отдаёт `contentLength` — размер сверять с `Stat` SQL.
+- Один файл = много строк `files_file` (по версиям). Без `current_version = 1`
+  получите дубликаты.
+- `folder_id` не входит в ключ MinIO; ключ считает `shard` от `id`.
+- Searcher SQL ищет только по имени (`LIKE`). Контент — Elasticsearch
+  ([elasticsearch.md](elasticsearch.md)).

docs/elasticsearch.md

@@ -121,5 +121,135 @@ ONLYOFFICE_ES_URL=http://127.0.0.1:9200 ONLYOFFICE_TENANT=1 \
 - `locale`/версия ES: 7.16.3, `_search` совместим с REST 7.x.
 - ES без auth и слушает только localhost — туннель обязателен.
 - Фильтр `tenantId` сузит выдачу; без него видны документы всех тенантов.
-- Поиск по содержимому PDF, залитых через API, не работает (нет
+- Поиск по содержимому PDF в индексе OnlyOffice не работает (для PDF нет
-  `attachment.content`) — только Office-форматы.
+  `attachment.content`) — только Office-форматы. Решение для PDF — свой индекс
+  `oo_docs_text` (F6 #42), см. ниже.
+
+# PDF и сканы — свой индекс (F6 #42)
+
+## Проблема
+
+`oo search --content "S1019"` не находил номер внутри PDF-счёта: в индексе
+OnlyOffice PDF лежит только по имени.
+
+## Почему PDF исключён (исходники CommunityServer)
+
+Разобрано в `ONLYOFFICE/CommunityServer`:
+
+- `web/core/ASC.Web.Core/Files/FileUtility.cs` — `CanIndex(fileName)` читает
+  серверную настройку `files.index.formats` (в `web/studio/ASC.Web.Studio/web.appsettings.config`
+  значение по умолчанию `".pptx|.xlsx|.docx"`).
+- `web/studio/ASC.Web.Studio/Products/Files/Core/Search/FilesWrapper.cs` —
+  `GetDocumentStream*` возвращает `null`, если `!FileUtility.CanIndex(Title)`,
+  файл зашифрован или больше `MaxFileSize`.
+- `module/ASC.ElasticSearch/Core/WrapperWithDoc.cs` + mapping в `Wrapper.cs` —
+  маппинг `document.attachment.content` и ingest-pipeline `attachments`
+  формат-агностичны: они распарсят любой поток.
+
+Вывод: PDF исключён **только настройкой** `files.index.formats`; жёсткого
+ограничения на формат в коде нет.
+
+## Варианты и решение
+
+| # | Вариант | Оценка |
+|---|---------|--------|
+| a | Включить `.pdf` в `files.index.formats` + reindex | Правка сервера OO; настройка может потеряться при обновлении; полный reindex 39k док-в; Tika **не OCR** — сканы без текстового слоя дадут пустой контент. Отклонён без решения PO. |
+| b | Server-side ingest/attachment для PDF | По факту то же, что (a): сервер кормит поток только для `CanIndex`. |
+| c | **Свой индекс** `oo_docs_text`, наполняемый `internal/docpipe` | **Выбран.** Сервер OO не трогаем; детерминированно; работает OCR для сканов; независимо от обновлений OO; любые форматы; фильтры папка/тип. |
+| d | Локальный поиск без индекса | Отклонён как основной: качаем и извлекаем на каждый запрос, нет выдачи/ранжирования/highlight. |
+
+Итог: **вариант c**. Индекс OnlyOffice (`files_file`) не изменяется; наш
+индекс живёт рядом.
+
+## Устройство
+
+- `file_es_text.go` — `ESTextIndex` (`Name() = "es-text"`):
+  `Ensure` (создаёт индекс с явным маппингом), `Put` (bulk, `refresh`),
+  `Delete` (по `id`), `Search` (`multi_match` по `title^2` + `content`,
+  фильтры `folder`/`ext`, highlight).
+- `file_text_index.go` — `TextIndexer`: листает папки (`FileStore.List`),
+  качает файлы (`FileStore.Download`), извлекает текст через
+  `internal/docpipe` (`pdftotext`, для сканов — `ocrmypdf`/`tesseract`),
+  пишет в `TextIndex`. Пул воркеров (по умолчанию 3).
+- CLI: `oo index folder|files` наполняет индекс; `oo search --backend own`
+  ищет по нему.
+
+### Встроенные вложения PDF
+
+Оцифрованные PDF несут вложения (`<doc>.md` — текст/таблицы скана,
+`<doc>.yaml`/`.json` — метаданные, `.xml` — EN 16931 CII eRechnung,
+`factur-x.xml` у ZUGFeRD; см. `office-assistant/docs/reference/document-metadata.md`).
+`TextIndexer` обходит их: `pdfdetach -list` перечисляет, `-save` сохраняет,
+каждое вложение проходит штатный `docpipe.ToMarkdown` (PDF/картинки → OCR,
+`.md`/`.txt` — как есть). Форматы, которые docpipe не конвертирует
+(`.xml`/`.html` — снимаются теги; `.json`/`.csv` — как текст), извлекаются
+текстом; нечитаемые — пропускаются.
+
+Текст склеивается: тело, затем по секции на вложение с маркером
+`[attachment: <имя>]` (функция `docpipe.JoinWithAttachments`). Индекс — тот же
+`file_id`, upsert идемпотентен. Нет вложений или pdfdetach/формат нечитаем —
+индексируется тело (без падения).
+
+Поля `oo_docs_text`:
+
+| поле | тип | смысл |
+|------|-----|-------|
+| `id` | keyword | id файла Documents |
+| `title` | text (+`.keyword`) | имя файла |
+| `folder` | keyword | id папки |
+| `ext` | keyword | расширение |
+| `content` | text | извлечённый текст (pdftotext/OCR) |
+
+## CLI
+
+```bash
+set -a; . .env; set +a          # ONLYOFFICE_URL/USER/PASS + ONLYOFFICE_ES_URL
+oo index folder 634             # PDF в папке 634
+oo index folder 634 --recursive --exts pdf,png --limit 100
+oo index files 3576 3578        # точечно
+oo index folder 634 --dry-run   # показать план, ничего не менять
+
+oo search "S1021" --content --backend own
+oo search "S1021" --backend own --folder 634 --json
+```
+
+`--backend` у `oo search`: `oo` (по умолчанию, индекс OnlyOffice) или `own`
+(наш `ONLYOFFICE_ES_TEXT_INDEX`).
+
+## Переменные (дополнение)
+
+| env | default | смысл |
+|-----|---------|-------|
+| `ONLYOFFICE_ES_TEXT_INDEX` | `oo_docs_text` | индекс своего конвейера |
+
+`ONLYOFFICE_ES_URL` — общий для обоих индексов.
+
+## Тесты
+
+```bash
+go test -run 'ESText|TextIndexer|Index' ./ ./cmd/oo/        # unit, без сети
+ONLYOFFICE_ES_URL=http://127.0.0.1:9200 \
+  go test -tags=integration -run TestIntegrationESTextIndex -v .
+```
+
+Интеграционный тест создаёт временный индекс, наполняет, ищет по контенту,
+проверяет фильтры и удаление, затем удаляет индекс;
+`TestIntegrationESTextIndexPDFAttachment` индексирует
+`testdata/pdf-with-attachment.pdf` реальным конвейером (pdfdetach + pdftotext)
+и ищет токен, лежащий только во вложении. Unit-тесты используют
+fake-store/fake-extractor и не требуют pdftotext/OCR (парсер списка, склейка
+`JoinWithAttachments`, снятие тегов `xmlToText` — чистые).
+
+## Грабли
+
+- Наполнение — ручное (`oo index`); после изменения/добавления PDF повтори.
+  Повтор идемпотентен (upsert по id файла).
+- В индексе ищется только то, что проиндексировано; `oo index` качает каждый
+  файл и (для сканов) гоняет OCR — это медленно, отсюда `--limit`/`--exts`.
+- `folder` фильтруется как id папки, а не как путь.
+- Дубликаты (напр. `S1055.pdf` и `2026-08-20-S1055-…`) дадут несколько строк —
+  это ожидаемо, дедуп — на стороне потребителя.
+- Вложения: нужен `pdfdetach` (poppler); если его нет — индексируется только
+  тело. Вложенный PDF/картинка с плохим текстовым слоем проходит OCR, это
+  медленно. `.json`-метаданные (CuraSoft) индексируются как текст и могут
+  добавить шумовых токенов.

file_core.go

@@ -52,8 +52,17 @@ type Entry struct {
 	MIME     string
 	Created  time.Time
 	Modified time.Time
+	// Updated is the backend-native timestamp string, when the backend exposes
+	// one. It lets list output round-trip the API value; Modified is the
+	// parsed form for logic.
+	Updated  string
 	Version  int
 	Provider string
+
+	// Folder-only counters. Zero for files and for backends that do not
+	// report them.
+	FilesCount   int
+	FoldersCount int
 }
 
 // FileStore is the operation surface every file backend implements.
@@ -97,8 +106,8 @@ type Searcher interface {
 }
 
 // FileStore returns the adapter for a backend name: ProviderREST (default) or
-// ProviderDAV. Unknown or empty names select the REST backend. The full facade
+// ProviderDAV. Unknown or empty names select the REST backend. The composed
-// (backend composition) is deliberately left to a later change.
+// facade (backend selection/fallback) lives on FileClient in file_facade.go.
 func (c *Client) FileStore(backend string) FileStore {
 	switch strings.ToLower(strings.TrimSpace(backend)) {
 	case ProviderDAV, "webdav":
@@ -108,8 +117,9 @@ func (c *Client) FileStore(backend string) FileStore {
 	}
 }
 
-// Files returns the default (REST) file store.
+// Files returns the composed file facade. The returned *FileClient implements
-func (c *Client) Files() FileStore { return c.FileStore(ProviderREST) }
+// FileStore, so callers that used Files() as the plain REST store keep working.
+func (c *Client) Files() *FileClient { return c.newFileClient() }
 
 // retryStoreOp runs one store operation under the shared deterministic
 // transient-error policy (429/502/503/504).
@@ -140,6 +150,7 @@ func FileEntryToEntry(f *FileEntry, provider string) Entry {
 	e.MIME = mimeForTitle(e.Title, exst)
 	if f.Updated != nil {
 		e.Modified = *f.Updated
+		e.Updated = f.Updated.Format(time.RFC3339)
 	}
 	return e
 }
@@ -153,6 +164,7 @@ func DavFileToEntry(f DavFile, provider string) Entry {
 		Size:     f.Size,
 		MIME:     mimeForTitle(f.Title, ""),
 		Modified: f.ModTime(),
+		Updated:  f.Updated,
 		Provider: provider,
 	}
 }
@@ -160,12 +172,15 @@ func DavFileToEntry(f DavFile, provider string) Entry {
 // DavFolderToEntry converts a WebDAV folder row to the canonical model.
 func DavFolderToEntry(f DavFolder, provider string) Entry {
 	return Entry{
-		ID:       f.ID,
+		ID:           f.ID,
-		ParentID: f.ParentID,
+		ParentID:     f.ParentID,
-		Title:    f.Title,
+		Title:        f.Title,
-		Kind:     Folder,
+		Kind:         Folder,
-		Modified: f.ModTime(),
+		Modified:     f.ModTime(),
-		Provider: provider,
+		Updated:      f.Updated,
+		Provider:     provider,
+		FilesCount:   f.FilesCount,
+		FoldersCount: f.FoldersCount,
 	}
 }
 

file_es.go

@@ -188,6 +188,7 @@ type esBool struct {
 type esClause struct {
 	MultiMatch *esMultiMatch  `json:"multi_match,omitempty"`
 	Term       map[string]any `json:"term,omitempty"`
+	Terms      map[string]any `json:"terms,omitempty"`
 	Wildcard   map[string]any `json:"wildcard,omitempty"`
 }
 
@@ -268,9 +269,10 @@ func parseESSearchResponse(raw []byte) ([]SearchHit, error) {
 var esHighlightTag = regexp.MustCompile(`</?em[^>]*>`)
 
 // esHighlightText flattens a highlight map into one plain-text snippet,
-// preferring the content fragment over the title.
+// preferring the content fragment over the title. It covers both the
+// OnlyOffice content field and the own-index "content" field.
 func esHighlightText(hl map[string][]string) string {
-	for _, key := range []string{"document.attachment.content", "title"} {
+	for _, key := range []string{"document.attachment.content", "content", "title"} {
 		frags := hl[key]
 		if len(frags) == 0 {
 			continue

file_es_text.go

@@ -0,0 +1,336 @@
+package onlyoffice
+
+// Own full-text index (epic #34, F6 #42).
+//
+// The OnlyOffice Elasticsearch index (files_file) only holds extracted content
+// for Office formats. FileUtility.CanIndex gates extraction by the server
+// setting files.index.formats, whose default is ".pptx|.xlsx|.docx", so PDFs
+// are indexed by name only. Instead of patching the server (risky: lost on
+// upgrade, forces a full reindex) this file implements a second, independent
+// index (default oo_docs_text) that our own pipeline fills from
+// internal/docpipe (pdftotext + OCR). The OnlyOffice index is never touched.
+//
+// See docs/elasticsearch.md for the decision and the trade-offs.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+const defaultESTextIndex = "oo_docs_text"
+
+// ESTextConfig configures the own full-text index.
+type ESTextConfig struct {
+	URL    string // scheme://host:port of the ES HTTP endpoint
+	Index  string // index name, default oo_docs_text
+	Tenant string // reserved for future multi-tenant data; unused for now
+}
+
+// ESTextConfigFromEnv reads ONLYOFFICE_ES_URL and ONLYOFFICE_ES_TEXT_INDEX
+// (default oo_docs_text). The library never loads dotfiles — the CLI does that.
+func ESTextConfigFromEnv() ESTextConfig {
+	return ESTextConfig{
+		URL:    strings.TrimRight(strings.TrimSpace(os.Getenv("ONLYOFFICE_ES_URL")), "/"),
+		Index:  firstNonEmpty(os.Getenv("ONLYOFFICE_ES_TEXT_INDEX"), defaultESTextIndex),
+		Tenant: strings.TrimSpace(os.Getenv("ONLYOFFICE_TENANT")),
+	}
+}
+
+// TextDoc is one document in the own full-text index. It is keyed by the
+// OnlyOffice file id so hits map straight back to Documents entries.
+type TextDoc struct {
+	ID       string `json:"id"`
+	Title    string `json:"title"`
+	FolderID string `json:"folder,omitempty"`
+	Ext      string `json:"ext,omitempty"`
+	Content  string `json:"content"`
+}
+
+// TextIndex is the storage/search surface for locally extracted document text.
+// It complements Searcher: ESSearcher reads OnlyOffice's index, ESTextIndex
+// reads ours.
+type TextIndex interface {
+	Put(ctx context.Context, docs []TextDoc) error
+	Delete(ctx context.Context, ids []string) error
+	Search(ctx context.Context, q SearchQuery) ([]SearchHit, error)
+	Name() string
+}
+
+// ESTextIndex is a TextIndex (and Searcher) over a dedicated Elasticsearch
+// index filled by TextIndexer.
+type ESTextIndex struct {
+	cfg  ESTextConfig
+	http *http.Client
+}
+
+var (
+	_ TextIndex = (*ESTextIndex)(nil)
+	_ Searcher  = (*ESTextIndex)(nil)
+)
+
+// NewESTextIndex returns a searcher/writer for the own full-text index. The URL
+// is required; an empty index falls back to oo_docs_text.
+func NewESTextIndex(cfg ESTextConfig) (*ESTextIndex, error) {
+	if strings.TrimSpace(cfg.URL) == "" {
+		return nil, fmt.Errorf("onlyoffice: elasticsearch URL is empty (set ONLYOFFICE_ES_URL)")
+	}
+	cfg.URL = strings.TrimRight(cfg.URL, "/")
+	if cfg.Index == "" {
+		cfg.Index = defaultESTextIndex
+	}
+	return &ESTextIndex{cfg: cfg, http: &http.Client{Timeout: 120 * time.Second}}, nil
+}
+
+// Name implements Searcher and TextIndex.
+func (x *ESTextIndex) Name() string { return "es-text" }
+
+// Index returns the configured index name.
+func (x *ESTextIndex) Index() string { return x.cfg.Index }
+
+// esTextMapping pins explicit types: content must stay a plain text field (no
+// keyword subfield) and folder/ext stay exact keywords for filters.
+const esTextMapping = `{
+  "mappings": {
+    "properties": {
+      "id":      {"type": "keyword"},
+      "title":   {"type": "text", "fields": {"keyword": {"type": "keyword", "ignore_above": 512}}},
+      "folder":  {"type": "keyword"},
+      "ext":     {"type": "keyword"},
+      "content": {"type": "text"}
+    }
+  }
+}`
+
+// Ensure creates the index with the explicit mapping. A missing index is
+// created; an already existing one is left untouched.
+func (x *ESTextIndex) Ensure(ctx context.Context) error {
+	status, raw, err := x.do(ctx, http.MethodPut, "/"+x.cfg.Index, []byte(esTextMapping), "application/json")
+	if err != nil {
+		return err
+	}
+	if status == http.StatusOK {
+		return nil
+	}
+	if status == http.StatusBadRequest && bytes.Contains(raw, []byte("resource_already_exists_exception")) {
+		return nil
+	}
+	return fmt.Errorf("onlyoffice: create text index %s: %d %s", x.cfg.Index, status, truncate(string(raw), 300))
+}
+
+// Put upserts documents via the bulk API and refreshes so they are immediately
+// searchable.
+func (x *ESTextIndex) Put(ctx context.Context, docs []TextDoc) error {
+	if len(docs) == 0 {
+		return nil
+	}
+	status, raw, err := x.do(ctx, http.MethodPost, "/"+x.cfg.Index+"/_bulk?refresh=true", esTextBulkBody(docs), "application/x-ndjson")
+	if err != nil {
+		return err
+	}
+	if status >= 400 {
+		return fmt.Errorf("onlyoffice: bulk index %s: %d %s", x.cfg.Index, status, truncate(string(raw), 400))
+	}
+	var res esBulkResponse
+	if err := json.Unmarshal(raw, &res); err != nil {
+		return fmt.Errorf("onlyoffice: decode bulk response: %w", err)
+	}
+	if !res.Errors {
+		return nil
+	}
+	return fmt.Errorf("onlyoffice: bulk index %s: %s", x.cfg.Index, res.firstError())
+}
+
+// Delete removes documents by OnlyOffice file id. A missing index means there
+// is nothing to delete.
+func (x *ESTextIndex) Delete(ctx context.Context, ids []string) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	body, err := json.Marshal(map[string]any{"query": map[string]any{"terms": map[string]any{"id": ids}}})
+	if err != nil {
+		return err
+	}
+	status, raw, err := x.do(ctx, http.MethodPost, "/"+x.cfg.Index+"/_delete_by_query?refresh=true", body, "application/json")
+	if err != nil {
+		return err
+	}
+	if status == http.StatusNotFound {
+		return nil
+	}
+	if status >= 400 {
+		return fmt.Errorf("onlyoffice: delete from %s: %d %s", x.cfg.Index, status, truncate(string(raw), 400))
+	}
+	return nil
+}
+
+// Search runs a multi_match over title (boosted) and content, with optional
+// folder and extension filters. A missing index yields no hits, not an error.
+func (x *ESTextIndex) Search(ctx context.Context, q SearchQuery) ([]SearchHit, error) {
+	q.Text = strings.TrimSpace(q.Text)
+	if q.Text == "" {
+		return nil, fmt.Errorf("onlyoffice: empty search query")
+	}
+	body, err := json.Marshal(esTextSearchRequest(q))
+	if err != nil {
+		return nil, fmt.Errorf("onlyoffice: build elasticsearch query: %w", err)
+	}
+	status, raw, err := x.do(ctx, http.MethodPost, "/"+x.cfg.Index+"/_search", body, "application/json")
+	if err != nil {
+		return nil, err
+	}
+	if status == http.StatusNotFound {
+		return nil, nil
+	}
+	if status >= 400 {
+		return nil, fmt.Errorf("onlyoffice: search %s: %d %s", x.cfg.Index, status, truncate(string(raw), 400))
+	}
+	return parseESTextResponse(raw)
+}
+
+// do sends one request and returns the status and body (bounded). The caller
+// decides which statuses are errors.
+func (x *ESTextIndex) do(ctx context.Context, method, path string, body []byte, contentType string) (int, []byte, error) {
+	var r io.Reader
+	if body != nil {
+		r = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, x.cfg.URL+path, r)
+	if err != nil {
+		return 0, nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	resp, err := x.http.Do(req)
+	if err != nil {
+		return 0, nil, fmt.Errorf("onlyoffice: elasticsearch %s: %w", method, err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, maxESResponseSize))
+	if err != nil {
+		return resp.StatusCode, nil, err
+	}
+	return resp.StatusCode, raw, nil
+}
+
+// esTextBulkBody renders the NDJSON bulk payload. Pure, so it is unit-tested.
+func esTextBulkBody(docs []TextDoc) []byte {
+	var b bytes.Buffer
+	enc := json.NewEncoder(&b)
+	enc.SetEscapeHTML(false)
+	for _, d := range docs {
+		_ = enc.Encode(map[string]any{"index": map[string]any{"_id": d.ID}})
+		_ = enc.Encode(d)
+	}
+	return b.Bytes()
+}
+
+// esTextSearchRequest builds the own-index query. Pure, so it is unit-tested.
+func esTextSearchRequest(q SearchQuery) esRequest {
+	limit := q.Limit
+	if limit <= 0 {
+		limit = defaultESLimit
+	}
+	if limit > maxESLimit {
+		limit = maxESLimit
+	}
+	fields := []string{"title^2", "content"}
+	must := []esClause{{MultiMatch: &esMultiMatch{Query: q.Text, Fields: fields}}}
+
+	var filter []esClause
+	if f := strings.TrimSpace(q.FolderID); f != "" {
+		filter = append(filter, esClause{Term: map[string]any{"folder": f}})
+	}
+	if exts := normalizeExtensions(q.Extensions); len(exts) > 0 {
+		filter = append(filter, esClause{Terms: map[string]any{"ext": exts}})
+	}
+
+	return esRequest{
+		Size:      limit,
+		Source:    []string{"id", "title", "folder", "ext"},
+		Query:     esQuery{Bool: esBool{Must: must, Filter: filter}},
+		Highlight: esHighlight{PreTags: []string{"<em>"}, PostTags: []string{"</em>"}, Fields: map[string]struct{}{"title": {}, "content": {}}},
+	}
+}
+
+// esBulkResponse is the subset of an ES bulk response we consume.
+type esBulkResponse struct {
+	Errors bool `json:"errors"`
+	Items  []map[string]struct {
+		ID     string `json:"_id"`
+		Status int    `json:"status"`
+		Error  *struct {
+			Type   string `json:"type"`
+			Reason string `json:"reason"`
+		} `json:"error"`
+	} `json:"items"`
+}
+
+// firstError returns a compact description of the first failed bulk item.
+func (r esBulkResponse) firstError() string {
+	for _, item := range r.Items {
+		for op, res := range item {
+			if res.Error != nil {
+				return fmt.Sprintf("%s %s: %s %s", op, res.ID, res.Error.Type, res.Error.Reason)
+			}
+		}
+	}
+	return "unknown bulk error"
+}
+
+// esTextResponse is the subset of an own-index search response we consume.
+type esTextResponse struct {
+	Hits struct {
+		Total struct {
+			Value int `json:"value"`
+		} `json:"total"`
+		Hits []struct {
+			ID     string              `json:"_id"`
+			Score  float64             `json:"_score"`
+			Source TextDoc             `json:"_source"`
+			HL     map[string][]string `json:"highlight"`
+		} `json:"hits"`
+	} `json:"hits"`
+}
+
+// parseESTextResponse converts an own-index search response into SearchHit
+// values. Pure, so it is unit-tested.
+func parseESTextResponse(raw []byte) ([]SearchHit, error) {
+	var r esTextResponse
+	if err := json.Unmarshal(raw, &r); err != nil {
+		return nil, fmt.Errorf("onlyoffice: decode elasticsearch response: %w", err)
+	}
+	hits := make([]SearchHit, 0, len(r.Hits.Hits))
+	for _, h := range r.Hits.Hits {
+		id := h.Source.ID
+		if id == "" {
+			id = h.ID
+		}
+		parent := h.Source.FolderID
+		var path []string
+		if parent != "" {
+			path = []string{parent}
+		}
+		hits = append(hits, SearchHit{
+			Entry: Entry{
+				ID:       id,
+				ParentID: parent,
+				Title:    h.Source.Title,
+				Kind:     File,
+				Provider: "es-text",
+			},
+			Score:     h.Score,
+			Highlight: esHighlightText(h.HL),
+			Path:      path,
+		})
+	}
+	return hits, nil
+}

file_es_text_integration_test.go

@@ -0,0 +1,158 @@
+//go:build integration
+
+package onlyoffice
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/eslider/go-onlyoffice/internal/docpipe"
+)
+
+// TestIntegrationESTextIndex verifies the own full-text index end to end
+// against a live Elasticsearch: create the index with its mapping, index a
+// document, find it by content (and reject it via a folder filter and after
+// deletion), then drop the throwaway index.
+//
+// Requires ONLYOFFICE_ES_URL (a reachable ES endpoint — in the current setup a
+// tunnel to the ES inside the OnlyOffice VM, see docs/elasticsearch.md). It
+// does not need OnlyOffice credentials because no file is downloaded: the
+// TextIndexer write path is covered by unit tests with a fake extractor.
+func TestIntegrationESTextIndex(t *testing.T) {
+	esURL := strings.TrimSpace(os.Getenv("ONLYOFFICE_ES_URL"))
+	if esURL == "" {
+		t.Skip("ONLYOFFICE_ES_URL not set — skipping Elasticsearch integration test")
+	}
+	stamp := time.Now().UTC().Format("20060102150405")
+	idx, err := NewESTextIndex(ESTextConfig{URL: esURL, Index: "oo_docs_text_it_" + stamp})
+	if err != nil {
+		t.Fatalf("NewESTextIndex: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	t.Cleanup(func() {
+		cleanupCtx, done := context.WithTimeout(context.Background(), 30*time.Second)
+		defer done()
+		_, _, _ = idx.do(cleanupCtx, http.MethodDelete, "/"+idx.Index(), nil, "")
+	})
+
+	if err := idx.Ensure(ctx); err != nil {
+		t.Fatalf("Ensure: %v", err)
+	}
+	// Ensure is idempotent.
+	if err := idx.Ensure(ctx); err != nil {
+		t.Fatalf("Ensure (second): %v", err)
+	}
+
+	token := "gotes" + stamp
+	doc := TextDoc{
+		ID:       "3578",
+		Title:    "2026-07-28-S1021-Edelweiss-rechnung.pdf",
+		FolderID: "634",
+		Ext:      "pdf",
+		Content:  "Begleitzettel SGB XI — Rechnung " + token,
+	}
+	if err := idx.Put(ctx, []TextDoc{doc}); err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	hits, err := idx.Search(ctx, SearchQuery{Text: token})
+	if err != nil {
+		t.Fatalf("Search: %v", err)
+	}
+	if len(hits) != 1 || hits[0].ID != "3578" {
+		t.Fatalf("content search hits = %+v, want doc 3578", hits)
+	}
+	if !strings.Contains(hits[0].Highlight, token) {
+		t.Errorf("highlight = %q, want token", hits[0].Highlight)
+	}
+
+	if hits, err := idx.Search(ctx, SearchQuery{Text: token, FolderID: "999"}); err != nil {
+		t.Fatalf("Search with folder filter: %v", err)
+	} else if len(hits) != 0 {
+		t.Errorf("folder filter returned %d hits, want 0", len(hits))
+	}
+	if hits, err := idx.Search(ctx, SearchQuery{Text: token, Extensions: []string{"docx"}}); err != nil {
+		t.Fatalf("Search with ext filter: %v", err)
+	} else if len(hits) != 0 {
+		t.Errorf("ext filter returned %d hits, want 0", len(hits))
+	}
+
+	if err := idx.Delete(ctx, []string{"3578"}); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+	if hits, err := idx.Search(ctx, SearchQuery{Text: token}); err != nil {
+		t.Fatalf("Search after delete: %v", err)
+	} else if len(hits) != 0 {
+		t.Errorf("after delete search returned %d hits, want 0", len(hits))
+	}
+}
+
+// TestIntegrationESTextIndexPDFAttachment indexes testdata/pdf-with-attachment.pdf
+// through the real pipeline (TextIndexer + docpipe: pdfdetach + pdftotext) and
+// verifies that text living only in the embedded attachment is searchable.
+//
+// Requires ONLYOFFICE_ES_URL plus poppler (pdfdetach/pdftotext). No OnlyOffice
+// credentials are needed: a fixture FileStore serves the PDF bytes.
+func TestIntegrationESTextIndexPDFAttachment(t *testing.T) {
+	esURL := strings.TrimSpace(os.Getenv("ONLYOFFICE_ES_URL"))
+	if esURL == "" {
+		t.Skip("ONLYOFFICE_ES_URL not set — skipping Elasticsearch integration test")
+	}
+	if docpipe.LookPath().PDFDetach == "" {
+		t.Skip("pdfdetach not on PATH — skipping PDF attachment integration test")
+	}
+	pdf, err := os.ReadFile("testdata/pdf-with-attachment.pdf")
+	if err != nil {
+		t.Fatalf("read fixture: %v", err)
+	}
+
+	stamp := time.Now().UTC().Format("20060102150405")
+	idx, err := NewESTextIndex(ESTextConfig{URL: esURL, Index: "oo_docs_text_it_att_" + stamp})
+	if err != nil {
+		t.Fatalf("NewESTextIndex: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	t.Cleanup(func() {
+		cleanupCtx, done := context.WithTimeout(context.Background(), 30*time.Second)
+		defer done()
+		_, _, _ = idx.do(cleanupCtx, http.MethodDelete, "/"+idx.Index(), nil, "")
+	})
+	if err := idx.Ensure(ctx); err != nil {
+		t.Fatalf("Ensure: %v", err)
+	}
+
+	store := &textFakeStore{files: map[string][]byte{"9001": pdf}}
+	ix := NewTextIndexer(store, idx)
+	res, err := ix.IndexEntries(ctx, []Entry{{ID: "9001", Title: "scan.pdf", ParentID: "777", Kind: File}}, IndexOptions{MinChars: 1})
+	if err != nil {
+		t.Fatalf("IndexEntries: %v", err)
+	}
+	if res.Indexed != 1 || res.Failed != 0 {
+		t.Fatalf("result = %+v, want one indexed doc", res)
+	}
+
+	// Token appears only inside the embedded goo-note.txt attachment.
+	hits, err := idx.Search(ctx, SearchQuery{Text: "gooattachmenttoken"})
+	if err != nil {
+		t.Fatalf("Search attachment token: %v", err)
+	}
+	if len(hits) != 1 || hits[0].ID != "9001" {
+		t.Fatalf("attachment-token hits = %+v, want doc 9001", hits)
+	}
+	if !strings.Contains(hits[0].Highlight, "gooattachmenttoken") {
+		t.Errorf("highlight = %q, want attachment token", hits[0].Highlight)
+	}
+	// Body text is indexed as before.
+	if hits, err := idx.Search(ctx, SearchQuery{Text: "goobodytoken"}); err != nil {
+		t.Fatalf("Search body token: %v", err)
+	} else if len(hits) != 1 {
+		t.Errorf("body-token hits = %d, want 1", len(hits))
+	}
+}

file_es_text_test.go

@@ -0,0 +1,275 @@
+package onlyoffice
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestESTextSearchRequestShape(t *testing.T) {
+	got := esTextSearchRequest(SearchQuery{
+		Text:       "S1021",
+		FolderID:   "634",
+		Extensions: []string{".PDF", "pdf"},
+		Limit:      5,
+	})
+	if got.Size != 5 {
+		t.Errorf("size = %d, want 5", got.Size)
+	}
+	mm := got.Query.Bool.Must[0].MultiMatch
+	if mm == nil || !reflect.DeepEqual(mm.Fields, []string{"title^2", "content"}) {
+		t.Fatalf("multi_match = %+v, want title^2 + content", mm)
+	}
+	if _, ok := got.Highlight.Fields["content"]; !ok {
+		t.Error("content highlight missing")
+	}
+	if _, ok := got.Highlight.Fields["title"]; !ok {
+		t.Error("title highlight missing")
+	}
+	var folder, exts int
+	for _, f := range got.Query.Bool.Filter {
+		switch {
+		case f.Term != nil && f.Term["folder"] != nil:
+			folder++
+			if f.Term["folder"] != "634" {
+				t.Errorf("folder term = %+v", f.Term)
+			}
+		case f.Terms != nil:
+			exts++
+			if !reflect.DeepEqual(f.Terms["ext"], []string{"pdf"}) {
+				t.Errorf("ext terms = %+v, want deduped pdf", f.Terms)
+			}
+		}
+	}
+	if folder != 1 || exts != 1 {
+		t.Errorf("filters folder=%d exts=%d, want 1 each", folder, exts)
+	}
+}
+
+func TestESTextBulkBody(t *testing.T) {
+	body := esTextBulkBody([]TextDoc{
+		{ID: "3578", Title: "S1021.pdf", FolderID: "634", Ext: "pdf", Content: "Begleitzettel <S1021> & mehr"},
+		{ID: "3579", Title: "S1023.pdf", Ext: "pdf", Content: "x"},
+	})
+	lines := strings.Split(strings.TrimRight(string(body), "\n"), "\n")
+	if len(lines) != 4 {
+		t.Fatalf("bulk body has %d lines, want 4:\n%s", len(lines), body)
+	}
+	if !strings.Contains(lines[0], `"index"`) || !strings.Contains(lines[0], `"_id":"3578"`) {
+		t.Errorf("action line = %q", lines[0])
+	}
+	if !strings.Contains(lines[1], `"content":"Begleitzettel <S1021> & mehr"`) {
+		t.Errorf("source line should keep HTML unescaped, got %q", lines[1])
+	}
+	if !strings.Contains(lines[2], `"_id":"3579"`) {
+		t.Errorf("second action line = %q", lines[2])
+	}
+}
+
+func TestParseESTextResponse(t *testing.T) {
+	raw := []byte(`{
+	  "hits": {
+	    "total": {"value": 1, "relation": "eq"},
+	    "hits": [
+	      {
+	        "_id": "3578",
+	        "_score": 3.21,
+	        "_source": {"id": "3578", "title": "2026-07-28-S1021-Edelweiss-rechnung.pdf", "folder": "634", "ext": "pdf"},
+	        "highlight": {"content": ["Begleitzettel … <em>S1021</em> …"]}
+	      }
+	    ]
+	  }
+	}`)
+	hits, err := parseESTextResponse(raw)
+	if err != nil {
+		t.Fatalf("parseESTextResponse: %v", err)
+	}
+	if len(hits) != 1 {
+		t.Fatalf("hits = %d, want 1", len(hits))
+	}
+	h := hits[0]
+	if h.ID != "3578" || h.Title != "2026-07-28-S1021-Edelweiss-rechnung.pdf" || h.Kind != File {
+		t.Errorf("entry = %+v", h.Entry)
+	}
+	if h.ParentID != "634" || !reflect.DeepEqual(h.Path, []string{"634"}) {
+		t.Errorf("path = %v parent = %q", h.Path, h.ParentID)
+	}
+	if h.Provider != "es-text" {
+		t.Errorf("provider = %q", h.Provider)
+	}
+	if h.Highlight != "Begleitzettel … S1021 …" {
+		t.Errorf("highlight = %q, want tags stripped", h.Highlight)
+	}
+}
+
+func TestNewESTextIndexDefaults(t *testing.T) {
+	if _, err := NewESTextIndex(ESTextConfig{}); err == nil {
+		t.Error("empty URL: want error")
+	}
+	x, err := NewESTextIndex(ESTextConfig{URL: "http://es:9200/"})
+	if err != nil {
+		t.Fatalf("NewESTextIndex: %v", err)
+	}
+	if x.Index() != defaultESTextIndex {
+		t.Errorf("index = %q, want %q", x.Index(), defaultESTextIndex)
+	}
+	if x.cfg.URL != "http://es:9200" {
+		t.Errorf("url = %q, want trimmed", x.cfg.URL)
+	}
+	if x.Name() != "es-text" {
+		t.Errorf("Name() = %q", x.Name())
+	}
+}
+
+func TestESTextConfigFromEnvIndexDefault(t *testing.T) {
+	t.Setenv("ONLYOFFICE_ES_URL", "http://es:9200/")
+	t.Setenv("ONLYOFFICE_ES_TEXT_INDEX", "")
+	cfg := ESTextConfigFromEnv()
+	if cfg.Index != defaultESTextIndex {
+		t.Errorf("index = %q, want %q", cfg.Index, defaultESTextIndex)
+	}
+}
+
+func TestTextIndexerIndexEntries(t *testing.T) {
+	store := &textFakeStore{
+		files: map[string][]byte{"1": []byte("PDFBYTES")},
+	}
+	idx := &textFakeIndex{}
+	ix := NewTextIndexer(store, idx)
+	ix.Extractor = textFakeExtractor{prefix: "TEXT "}
+
+	res, err := ix.IndexEntries(context.Background(), []Entry{
+		{ID: "1", Title: "Rechnung.PDF", ParentID: "649", Kind: File},
+		{ID: "2", Title: "Tabelle.xlsx", ParentID: "649", Kind: File},
+		{ID: "3", Title: "Unterordner", Kind: Folder},
+	}, IndexOptions{})
+	if err != nil {
+		t.Fatalf("IndexEntries: %v", err)
+	}
+	if res.Scanned != 3 || res.Indexed != 1 || res.Skipped != 2 || res.Failed != 0 {
+		t.Errorf("result = %+v, want scanned=3 indexed=1 skipped=2 failed=0", res)
+	}
+	if len(idx.docs) != 1 {
+		t.Fatalf("indexed docs = %d, want 1", len(idx.docs))
+	}
+	got := idx.docs[0]
+	want := TextDoc{ID: "1", Title: "Rechnung.PDF", FolderID: "649", Ext: "pdf", Content: "TEXT PDFBYTES"}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("doc = %+v, want %+v", got, want)
+	}
+}
+
+func TestTextIndexerRecordsExtractionFailure(t *testing.T) {
+	store := &textFakeStore{files: map[string][]byte{"1": []byte("x")}}
+	idx := &textFakeIndex{}
+	ix := NewTextIndexer(store, idx)
+	ix.Extractor = textFailingExtractor{}
+
+	res, err := ix.IndexEntries(context.Background(), []Entry{{ID: "1", Title: "a.pdf", Kind: File}}, IndexOptions{})
+	if err != nil {
+		t.Fatalf("IndexEntries: %v", err)
+	}
+	if res.Indexed != 0 || res.Failed != 1 || len(res.Errors) != 1 {
+		t.Errorf("result = %+v, want one failure recorded", res)
+	}
+}
+
+func TestTextIndexerPlanFolder(t *testing.T) {
+	store := &textFakeStore{dirs: map[string][]Entry{
+		"root": {
+			{ID: "10", Title: "a.pdf", Kind: File},
+			{ID: "11", Title: "sub", Kind: Folder},
+		},
+		"11": {
+			{ID: "12", Title: "b.PDF", Kind: File},
+			{ID: "13", Title: "c.xlsx", Kind: File},
+		},
+	}}
+	ix := NewTextIndexer(store, &textFakeIndex{})
+
+	flat, err := ix.PlanFolder(context.Background(), "root", IndexOptions{})
+	if err != nil {
+		t.Fatalf("PlanFolder: %v", err)
+	}
+	if len(flat) != 1 || flat[0].ID != "10" {
+		t.Errorf("flat plan = %+v, want only a.pdf", flat)
+	}
+	deep, err := ix.PlanFolder(context.Background(), "root", IndexOptions{Recursive: true, Limit: 10})
+	if err != nil {
+		t.Fatalf("PlanFolder recursive: %v", err)
+	}
+	if len(deep) != 2 {
+		t.Errorf("recursive plan = %d entries, want 2", len(deep))
+	}
+}
+
+// --- fakes -----------------------------------------------------------------
+
+type textFakeStore struct {
+	dirs  map[string][]Entry
+	files map[string][]byte
+	stat  map[string]Entry
+}
+
+func (f *textFakeStore) Name() string { return "fake" }
+
+func (f *textFakeStore) List(_ context.Context, parentID string) ([]Entry, error) {
+	return f.dirs[parentID], nil
+}
+
+func (f *textFakeStore) Stat(_ context.Context, id string) (Entry, error) {
+	if e, ok := f.stat[id]; ok {
+		return e, nil
+	}
+	return Entry{}, fmt.Errorf("not found: %s", id)
+}
+
+func (f *textFakeStore) Download(_ context.Context, id string, w io.Writer) (int64, error) {
+	b, ok := f.files[id]
+	if !ok {
+		return 0, fmt.Errorf("no bytes for %s", id)
+	}
+	n, err := w.Write(b)
+	return int64(n), err
+}
+
+func (f *textFakeStore) CreateFolder(context.Context, string, string) (Entry, error) {
+	return Entry{}, nil
+}
+func (f *textFakeStore) Upload(context.Context, string, string, io.Reader) (Entry, error) {
+	return Entry{}, nil
+}
+func (f *textFakeStore) Move(context.Context, []string, string) error { return nil }
+func (f *textFakeStore) Copy(context.Context, []string, string) error { return nil }
+func (f *textFakeStore) Rename(context.Context, string, string) error { return nil }
+func (f *textFakeStore) Delete(context.Context, []string) error       { return nil }
+
+type textFakeIndex struct{ docs []TextDoc }
+
+func (f *textFakeIndex) Put(_ context.Context, docs []TextDoc) error {
+	f.docs = append(f.docs, docs...)
+	return nil
+}
+func (f *textFakeIndex) Delete(context.Context, []string) error                   { return nil }
+func (f *textFakeIndex) Search(context.Context, SearchQuery) ([]SearchHit, error) { return nil, nil }
+func (f *textFakeIndex) Name() string                                             { return "fake" }
+
+type textFakeExtractor struct{ prefix string }
+
+func (f textFakeExtractor) Extract(path, _, _ string, _ int) (string, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	return f.prefix + string(b), nil
+}
+
+type textFailingExtractor struct{}
+
+func (textFailingExtractor) Extract(string, string, string, int) (string, error) {
+	return "", fmt.Errorf("boom")
+}

file_facade.go

@@ -0,0 +1,249 @@
+package onlyoffice
+
+// Single file client (epic #34, F4 #38). FileClient composes the registered
+// FileStore and Searcher backends and picks one per operation: REST/DAV for
+// writes, PostgreSQL (when registered) for fast reads, Elasticsearch for name
+// and content search. Client.Files returns the facade; it also implements
+// FileStore, so existing callers keep compiling.
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+)
+
+// ProviderES is the composed Elasticsearch searcher. The SQL store owns
+// ProviderPG/ProviderMySQL (file_pg.go); the facade references ProviderPG in
+// readOrder.
+const ProviderES = "elasticsearch"
+
+var (
+	errNoReadBackend  = errors.New("onlyoffice: no file backend registered for reads")
+	errNoWriteBackend = errors.New("onlyoffice: no file backend registered for writes")
+	errNoSearcher     = errors.New("onlyoffice: no search backend registered (set ONLYOFFICE_ES_URL)")
+)
+
+// FileClient is the single entry point for file operations. It holds the
+// registered backends and the order in which each operation tries them.
+type FileClient struct {
+	stores    map[string]FileStore
+	searchers map[string]Searcher
+
+	readOrder   []string
+	writeOrder  []string
+	searchOrder []string
+}
+
+// newFileClient builds the facade over the built-in REST and DAV stores. The
+// Elasticsearch searcher is registered when ONLYOFFICE_ES_URL is set; the
+// missing-credential case is left to Search so read-only commands still work.
+func (c *Client) newFileClient() *FileClient {
+	f := &FileClient{
+		stores: map[string]FileStore{
+			ProviderREST: &restStore{c: c},
+			ProviderDAV:  &davStore{c: c},
+		},
+		searchers:   map[string]Searcher{},
+		readOrder:   []string{ProviderPG, ProviderREST, ProviderDAV},
+		writeOrder:  []string{ProviderREST, ProviderDAV},
+		searchOrder: []string{ProviderES},
+	}
+	if cfg := ESConfigFromEnv(); cfg.URL != "" {
+		if es, err := NewESSearcher(cfg); err == nil {
+			f.searchers[ProviderES] = es
+		}
+	}
+	return f
+}
+
+// RegisterStore adds or replaces a named backend (for example the PostgreSQL
+// read store). The name is matched case-insensitively.
+func (f *FileClient) RegisterStore(name string, s FileStore) {
+	if f == nil || s == nil {
+		return
+	}
+	name = normalizeProvider(name)
+	if name == "" {
+		return
+	}
+	if f.stores == nil {
+		f.stores = map[string]FileStore{}
+	}
+	f.stores[name] = s
+}
+
+// RegisterSearcher adds or replaces a named search backend.
+func (f *FileClient) RegisterSearcher(name string, s Searcher) {
+	if f == nil || s == nil {
+		return
+	}
+	name = normalizeProvider(name)
+	if name == "" {
+		return
+	}
+	if f.searchers == nil {
+		f.searchers = map[string]Searcher{}
+	}
+	f.searchers[name] = s
+}
+
+// Read returns the preferred backend for reads: PostgreSQL when registered,
+// then REST, then WebDAV.
+func (f *FileClient) Read() FileStore { return f.firstStore(f.readOrder) }
+
+// Write returns the preferred backend for writes: REST, then WebDAV.
+func (f *FileClient) Write() FileStore { return f.firstStore(f.writeOrder) }
+
+// Search returns the preferred name/content searcher (Elasticsearch), or an
+// error when no search backend is configured.
+func (f *FileClient) Search() (Searcher, error) {
+	if f == nil {
+		return nil, errNoSearcher
+	}
+	for _, name := range f.searchOrder {
+		if s := f.searchers[normalizeProvider(name)]; s != nil {
+			return s, nil
+		}
+	}
+	return nil, errNoSearcher
+}
+
+// firstStore returns the first registered store in the order.
+func (f *FileClient) firstStore(order []string) FileStore {
+	if f == nil {
+		return nil
+	}
+	for _, name := range order {
+		if s := f.stores[normalizeProvider(name)]; s != nil {
+			return s
+		}
+	}
+	return nil
+}
+
+// orderedStores returns the registered stores in the order.
+func (f *FileClient) orderedStores(order []string) []FileStore {
+	if f == nil {
+		return nil
+	}
+	out := make([]FileStore, 0, len(order))
+	for _, name := range order {
+		if s := f.stores[normalizeProvider(name)]; s != nil {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+func normalizeProvider(name string) string {
+	return strings.ToLower(strings.TrimSpace(name))
+}
+
+// Name implements FileStore and reports the preferred read backend.
+func (f *FileClient) Name() string {
+	if s := f.Read(); s != nil {
+		return s.Name()
+	}
+	return ""
+}
+
+// List reads from the preferred backend, falling back to the next read backend
+// only on a transient error (429/502/503/504).
+func (f *FileClient) List(ctx context.Context, parentID string) ([]Entry, error) {
+	return fallbackRead(ctx, f.orderedStores(f.readOrder), func(s FileStore) ([]Entry, error) {
+		return s.List(ctx, parentID)
+	})
+}
+
+// Stat reads from the preferred backend, with the same transient fallback.
+func (f *FileClient) Stat(ctx context.Context, id string) (Entry, error) {
+	return fallbackRead(ctx, f.orderedStores(f.readOrder), func(s FileStore) (Entry, error) {
+		return s.Stat(ctx, id)
+	})
+}
+
+// Download streams file bytes. It does not fall back: a failed attempt may have
+// already written partial bytes into w, so a second backend would append.
+func (f *FileClient) Download(ctx context.Context, id string, w io.Writer) (int64, error) {
+	s := f.Read()
+	if s == nil {
+		return 0, errNoReadBackend
+	}
+	return s.Download(ctx, id, w)
+}
+
+// CreateFolder writes to the preferred write backend.
+func (f *FileClient) CreateFolder(ctx context.Context, parentID, title string) (Entry, error) {
+	s := f.Write()
+	if s == nil {
+		return Entry{}, errNoWriteBackend
+	}
+	return s.CreateFolder(ctx, parentID, title)
+}
+
+// Upload writes to the preferred write backend.
+func (f *FileClient) Upload(ctx context.Context, parentID, title string, r io.Reader) (Entry, error) {
+	s := f.Write()
+	if s == nil {
+		return Entry{}, errNoWriteBackend
+	}
+	return s.Upload(ctx, parentID, title, r)
+}
+
+// Move writes to the preferred write backend.
+func (f *FileClient) Move(ctx context.Context, ids []string, parentID string) error {
+	s := f.Write()
+	if s == nil {
+		return errNoWriteBackend
+	}
+	return s.Move(ctx, ids, parentID)
+}
+
+// Copy writes to the preferred write backend.
+func (f *FileClient) Copy(ctx context.Context, ids []string, parentID string) error {
+	s := f.Write()
+	if s == nil {
+		return errNoWriteBackend
+	}
+	return s.Copy(ctx, ids, parentID)
+}
+
+// Rename writes to the preferred write backend.
+func (f *FileClient) Rename(ctx context.Context, id, title string) error {
+	s := f.Write()
+	if s == nil {
+		return errNoWriteBackend
+	}
+	return s.Rename(ctx, id, title)
+}
+
+// Delete writes to the preferred write backend.
+func (f *FileClient) Delete(ctx context.Context, ids []string) error {
+	s := f.Write()
+	if s == nil {
+		return errNoWriteBackend
+	}
+	return s.Delete(ctx, ids)
+}
+
+// fallbackRead runs op against each store in order, moving on only when the
+// error is transient. Non-transient errors (not found, forbidden) are final.
+func fallbackRead[T any](ctx context.Context, stores []FileStore, op func(FileStore) (T, error)) (T, error) {
+	var zero T
+	if len(stores) == 0 {
+		return zero, errNoReadBackend
+	}
+	var err error
+	for i, s := range stores {
+		var v T
+		v, err = op(s)
+		if err == nil {
+			return v, nil
+		}
+		if i == len(stores)-1 || !Transient(err) {
+			return zero, err
+		}
+	}
+	return zero, err
+}

file_facade_test.go

@@ -0,0 +1,230 @@
+package onlyoffice
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+)
+
+// fakeStore is a FileStore test double; it records which backend served a call
+// and returns a canned result or error.
+type fakeStore struct {
+	name    string
+	entries []Entry
+	err     error
+	calls   *[]string
+}
+
+func (f *fakeStore) record(op string) {
+	if f.calls != nil {
+		*f.calls = append(*f.calls, op+":"+f.name)
+	}
+}
+
+func (f *fakeStore) Name() string { return f.name }
+
+func (f *fakeStore) List(_ context.Context, _ string) ([]Entry, error) {
+	f.record("list")
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.entries, nil
+}
+
+func (f *fakeStore) Stat(_ context.Context, id string) (Entry, error) {
+	f.record("stat")
+	if f.err != nil {
+		return Entry{}, f.err
+	}
+	return Entry{ID: id, Title: "t-" + f.name, Provider: f.name}, nil
+}
+
+func (f *fakeStore) CreateFolder(_ context.Context, _, title string) (Entry, error) {
+	f.record("mkdir")
+	if f.err != nil {
+		return Entry{}, f.err
+	}
+	return Entry{ID: "new", Title: title, Provider: f.name}, nil
+}
+
+func (f *fakeStore) Upload(_ context.Context, _, title string, _ io.Reader) (Entry, error) {
+	f.record("upload")
+	return Entry{ID: "up", Title: title, Provider: f.name}, f.err
+}
+
+func (f *fakeStore) Download(_ context.Context, _ string, _ io.Writer) (int64, error) {
+	f.record("download")
+	return 0, f.err
+}
+
+func (f *fakeStore) Move(_ context.Context, _ []string, _ string) error {
+	f.record("move")
+	return f.err
+}
+
+func (f *fakeStore) Copy(_ context.Context, _ []string, _ string) error {
+	f.record("copy")
+	return f.err
+}
+
+func (f *fakeStore) Rename(_ context.Context, _, _ string) error {
+	f.record("rename")
+	return f.err
+}
+
+func (f *fakeStore) Delete(_ context.Context, _ []string) error {
+	f.record("delete")
+	return f.err
+}
+
+type fakeSearcher struct{ name string }
+
+func (s *fakeSearcher) Name() string { return s.name }
+
+func (s *fakeSearcher) Search(_ context.Context, _ SearchQuery) ([]SearchHit, error) {
+	return []SearchHit{{Entry: Entry{Title: s.name}}}, nil
+}
+
+func newFacadeTestClient(stores map[string]FileStore, read, write []string) *FileClient {
+	return &FileClient{
+		stores:     stores,
+		searchers:  map[string]Searcher{},
+		readOrder:  read,
+		writeOrder: write,
+	}
+}
+
+// TestFileClientIsFileStore guarantees the facade can stand in for the
+// interface anywhere a plain FileStore is expected.
+func TestFileClientIsFileStore(t *testing.T) {
+	var _ FileStore = (*FileClient)(nil)
+}
+
+func TestClientFilesPrefersRESTForReadsAndWrites(t *testing.T) {
+	c := NewClient(Credentials{})
+	f := c.Files()
+	if got := f.Read().Name(); got != ProviderREST {
+		t.Errorf("Read().Name() = %q, want %q", got, ProviderREST)
+	}
+	if got := f.Write().Name(); got != ProviderREST {
+		t.Errorf("Write().Name() = %q, want %q", got, ProviderREST)
+	}
+	if got := f.Name(); got != ProviderREST {
+		t.Errorf("Name() = %q, want %q", got, ProviderREST)
+	}
+}
+
+func TestFileClientPostgresTakesReadPriority(t *testing.T) {
+	pg := &fakeStore{name: ProviderPG}
+	f := newFacadeTestClient(
+		map[string]FileStore{ProviderREST: &fakeStore{name: ProviderREST}, ProviderPG: pg},
+		[]string{ProviderPG, ProviderREST},
+		[]string{ProviderREST},
+	)
+	if got := f.Read().Name(); got != ProviderPG {
+		t.Errorf("Read().Name() = %q, want %q", got, ProviderPG)
+	}
+	if got := f.Write().Name(); got != ProviderREST {
+		t.Errorf("Write().Name() = %q, want %q (PG is read-only)", got, ProviderREST)
+	}
+}
+
+func TestFileClientRegisterStoreNormalizesName(t *testing.T) {
+	pg := &fakeStore{name: "pg"}
+	f := newFacadeTestClient(map[string]FileStore{}, []string{ProviderPG}, nil)
+	f.RegisterStore("  POSTGRES  ", pg)
+	if got := f.Read(); got != pg {
+		t.Fatalf("Read() = %v, want registered postgres store", got)
+	}
+	f.RegisterStore("", pg)
+	f.RegisterStore("pg", nil)
+}
+
+func TestFileClientReadFallsBackOnlyOnTransient(t *testing.T) {
+	var calls []string
+	primary := &fakeStore{name: "primary", err: fmt.Errorf("onlyoffice: list: 503 unavailable"), calls: &calls}
+	secondary := &fakeStore{name: "secondary", entries: []Entry{{ID: "1"}}, calls: &calls}
+	f := newFacadeTestClient(
+		map[string]FileStore{"primary": primary, "secondary": secondary},
+		[]string{"primary", "secondary"},
+		nil,
+	)
+	got, err := f.List(context.Background(), "root")
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(got) != 1 || got[0].ID != "1" {
+		t.Fatalf("List() = %+v, want secondary entry", got)
+	}
+	want := []string{"list:primary", "list:secondary"}
+	if fmt.Sprint(calls) != fmt.Sprint(want) {
+		t.Fatalf("call order = %v, want %v", calls, want)
+	}
+}
+
+func TestFileClientReadStopsOnPermanentError(t *testing.T) {
+	var calls []string
+	primary := &fakeStore{name: "primary", err: errors.New("onlyoffice: not found"), calls: &calls}
+	secondary := &fakeStore{name: "secondary", entries: []Entry{{ID: "1"}}, calls: &calls}
+	f := newFacadeTestClient(
+		map[string]FileStore{"primary": primary, "secondary": secondary},
+		[]string{"primary", "secondary"},
+		nil,
+	)
+	if _, err := f.List(context.Background(), "root"); err == nil {
+		t.Fatal("expected permanent error to be returned")
+	}
+	if len(calls) != 1 || calls[0] != "list:primary" {
+		t.Fatalf("secondary backend must not run on a permanent error: %v", calls)
+	}
+}
+
+func TestFileClientWriteUsesWriteBackend(t *testing.T) {
+	var calls []string
+	rest := &fakeStore{name: ProviderREST, calls: &calls}
+	dav := &fakeStore{name: ProviderDAV, calls: &calls}
+	f := newFacadeTestClient(
+		map[string]FileStore{ProviderREST: rest, ProviderDAV: dav},
+		[]string{ProviderREST},
+		[]string{ProviderREST, ProviderDAV},
+	)
+	if _, err := f.CreateFolder(context.Background(), "p", "t"); err != nil {
+		t.Fatalf("CreateFolder: %v", err)
+	}
+	if _, err := f.Upload(context.Background(), "p", "t", nil); err != nil {
+		t.Fatalf("Upload: %v", err)
+	}
+	if len(calls) != 2 || calls[0] != "mkdir:rest" || calls[1] != "upload:rest" {
+		t.Fatalf("write calls = %v, want REST", calls)
+	}
+}
+
+func TestFileClientWriteWithoutBackend(t *testing.T) {
+	f := newFacadeTestClient(map[string]FileStore{}, nil, nil)
+	if err := f.Delete(context.Background(), []string{"1"}); !errors.Is(err, errNoWriteBackend) {
+		t.Fatalf("Delete err = %v, want errNoWriteBackend", err)
+	}
+	if _, err := f.List(context.Background(), "root"); !errors.Is(err, errNoReadBackend) {
+		t.Fatalf("List err = %v, want errNoReadBackend", err)
+	}
+}
+
+func TestFileClientSearchSelection(t *testing.T) {
+	f := &FileClient{searchers: map[string]Searcher{}, searchOrder: []string{ProviderES}}
+	_, err := f.Search()
+	if err == nil || !strings.Contains(err.Error(), "ONLYOFFICE_ES_URL") {
+		t.Fatalf("Search without backend = %v, want ONLYOFFICE_ES_URL hint", err)
+	}
+	es := &fakeSearcher{name: "fake-es"}
+	f.RegisterSearcher(ProviderES, es)
+	got, err := f.Search()
+	if err != nil {
+		t.Fatalf("Search: %v", err)
+	}
+	if got.Name() != "fake-es" {
+		t.Fatalf("searcher = %q, want fake-es", got.Name())
+	}
+}

file_pg.go

@@ -0,0 +1,516 @@
+package onlyoffice
+
+// Read-only SQL backend of the unified file client (epic #34, F2 #36).
+//
+// The goal is to read files and folders straight from the Community Server
+// database, without the REST layer. Research on the live portal (VM
+// `onlyoffice-v2`) showed the server runs on **MySQL 8.0** (`files_file`,
+// `files_folder`, `files_folder_tree`, tenant `tenants_tenants`), not
+// PostgreSQL — see docs/community-server-db.md. The store below therefore
+// speaks `database/sql` and selects its driver from the DSN, so it works
+// against the live MySQL today and against PostgreSQL if the portal is ever
+// migrated. Every query is a SELECT; the write methods of FileStore return
+// ErrReadOnly.
+//
+// Downloads follow the portal's S3/MinIO object layout through the shared
+// MinIO helper in storage_fallback.go — no HTTP file endpoint is used.
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-sql-driver/mysql"
+	_ "github.com/jackc/pgx/v5/stdlib"
+)
+
+// Provider names for the SQL backend. ProviderPG is the value Name reports for
+// a PostgreSQL connection and ProviderMySQL for MySQL.
+const (
+	ProviderPG    = "postgres"
+	ProviderMySQL = "mysql"
+)
+
+// ErrReadOnly is returned by every FileStore write method of the SQL backend.
+var ErrReadOnly = errors.New("onlyoffice: sql file store is read-only")
+
+const (
+	pgConnectTimeout = 10 * time.Second
+	pgSearchLimit    = 50
+	pgSearchMaxLimit = 500
+)
+
+// PGConfig configures the read-only SQL store. DSN is a driver DSN:
+// `user:pass@tcp(host:port)/onlyoffice?parseTime=true` for MySQL or a
+// `postgres://` / libpq keyword string for PostgreSQL. Driver, when set,
+// forces the engine ("postgres" or "mysql"); otherwise it is detected from the
+// DSN. Tenant filters rows (empty means all tenants).
+type PGConfig struct {
+	DSN    string
+	Driver string
+	Tenant string
+}
+
+// PGConfigFromEnv reads ONLYOFFICE_DSN (or the ONLYOFFICE_PG_* parts),
+// ONLYOFFICE_PG_DRIVER and the tenant from ONLYOFFICE_PG_TENANT /
+// ONLYOFFICE_TENANT. The library never loads dotfiles — the CLI does that.
+func PGConfigFromEnv() PGConfig {
+	dsn := strings.TrimSpace(os.Getenv("ONLYOFFICE_DSN"))
+	if dsn == "" {
+		dsn = pgDSNFromParts()
+	}
+	return PGConfig{
+		DSN:    dsn,
+		Driver: strings.TrimSpace(os.Getenv("ONLYOFFICE_PG_DRIVER")),
+		Tenant: firstNonEmpty(os.Getenv("ONLYOFFICE_PG_TENANT"), os.Getenv("ONLYOFFICE_TENANT")),
+	}
+}
+
+// pgDSNFromParts builds a libpq keyword DSN from ONLYOFFICE_PG_* variables.
+// It returns "" unless a host is set, which keeps the MySQL path (ONLYOFFICE_DSN)
+// the default.
+func pgDSNFromParts() string {
+	host := strings.TrimSpace(os.Getenv("ONLYOFFICE_PG_HOST"))
+	if host == "" {
+		return ""
+	}
+	port := firstNonEmpty(os.Getenv("ONLYOFFICE_PG_PORT"), "5432")
+	dbname := firstNonEmpty(os.Getenv("ONLYOFFICE_PG_DBNAME"), "onlyoffice")
+	sslmode := firstNonEmpty(os.Getenv("ONLYOFFICE_PG_SSLMODE"), "disable")
+	return fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=%s",
+		host, port, os.Getenv("ONLYOFFICE_PG_USER"), os.Getenv("ONLYOFFICE_PG_PASSWORD"), dbname, sslmode)
+}
+
+// pgStore is a read-only FileStore/Searcher over the Community Server database.
+type pgStore struct {
+	db        *sql.DB
+	driver    string
+	tenantID  int64
+	hasTenant bool
+	http      *http.Client
+}
+
+var (
+	_ FileStore = (*pgStore)(nil)
+	_ Searcher  = (*pgStore)(nil)
+)
+
+// NewPGStore opens the database and verifies connectivity. It never writes.
+func NewPGStore(cfg PGConfig) (*pgStore, error) {
+	dsn := strings.TrimSpace(cfg.DSN)
+	if dsn == "" {
+		return nil, fmt.Errorf("onlyoffice: sql file store: empty DSN (set ONLYOFFICE_DSN)")
+	}
+	driver := pgDriver(dsn, cfg.Driver)
+	dsn, err := normalizeSQLDSN(driver, dsn)
+	if err != nil {
+		return nil, err
+	}
+	db, err := sql.Open(sqlDriverName(driver), dsn)
+	if err != nil {
+		return nil, fmt.Errorf("onlyoffice: sql file store: open %s: %w", driver, err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), pgConnectTimeout)
+	defer cancel()
+	if err := db.PingContext(ctx); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("onlyoffice: sql file store: ping %s: %w", driver, err)
+	}
+	s := &pgStore{db: db, driver: driver, http: &http.Client{}}
+	if t := strings.TrimSpace(cfg.Tenant); t != "" {
+		n, err := strconv.ParseInt(t, 10, 64)
+		if err != nil {
+			db.Close()
+			return nil, fmt.Errorf("onlyoffice: sql file store: non-numeric tenant %q", t)
+		}
+		s.tenantID, s.hasTenant = n, true
+	}
+	return s, nil
+}
+
+// Close releases the database handle.
+func (s *pgStore) Close() error { return s.db.Close() }
+
+// Name implements FileStore and Searcher.
+func (s *pgStore) Name() string { return s.driver }
+
+// pgDriver resolves the engine: the explicit value wins, otherwise the DSN
+// shape decides. A leading postgres:// scheme or a libpq keyword DSN (which
+// always carries '=') selects PostgreSQL; anything else is MySQL.
+func pgDriver(dsn, explicit string) string {
+	switch strings.ToLower(strings.TrimSpace(explicit)) {
+	case ProviderPG, "pg", "postgresql", "pgx":
+		return ProviderPG
+	case ProviderMySQL, "mariadb":
+		return ProviderMySQL
+	}
+	l := strings.ToLower(strings.TrimSpace(dsn))
+	switch {
+	case strings.HasPrefix(l, "postgres://"), strings.HasPrefix(l, "postgresql://"):
+		return ProviderPG
+	case strings.HasPrefix(l, "mysql://"), strings.Contains(l, "@tcp("), strings.Contains(l, "@unix("):
+		return ProviderMySQL
+	case strings.Contains(l, "="):
+		return ProviderPG
+	default:
+		return ProviderMySQL
+	}
+}
+
+// sqlDriverName maps the engine to its registered database/sql driver.
+func sqlDriverName(driver string) string {
+	if driver == ProviderPG {
+		return "pgx"
+	}
+	return "mysql"
+}
+
+// normalizeSQLDSN converts a mysql:// URL to the go-sql-driver form and forces
+// parseTime so datetime columns scan into time.Time. PostgreSQL DSNs pass
+// through untouched.
+func normalizeSQLDSN(driver, dsn string) (string, error) {
+	if driver != ProviderMySQL {
+		return dsn, nil
+	}
+	if strings.HasPrefix(strings.ToLower(dsn), "mysql://") {
+		converted, err := mysqlDSNFromURL(dsn)
+		if err != nil {
+			return "", err
+		}
+		dsn = converted
+	}
+	cfg, err := mysql.ParseDSN(dsn)
+	if err != nil {
+		return "", fmt.Errorf("onlyoffice: sql file store: parse mysql DSN: %w", err)
+	}
+	cfg.ParseTime = true
+	return cfg.FormatDSN(), nil
+}
+
+// mysqlDSNFromURL turns mysql://user:pass@host:port/db into the driver DSN.
+func mysqlDSNFromURL(raw string) (string, error) {
+	u, err := url.Parse(raw)
+	if err != nil || u.Host == "" {
+		return "", fmt.Errorf("onlyoffice: sql file store: bad mysql URL %q", raw)
+	}
+	user := ""
+	if u.User != nil {
+		user = u.User.Username()
+		if p, ok := u.User.Password(); ok {
+			user += ":" + p
+		}
+	}
+	q := u.Query()
+	q.Set("parseTime", "true")
+	return fmt.Sprintf("%s@tcp(%s)/%s?%s", user, u.Host, strings.TrimPrefix(u.Path, "/"), q.Encode()), nil
+}
+
+// rebind rewrites '?' placeholders to PostgreSQL's $1..$n. MySQL keeps them.
+func rebind(query, driver string) string {
+	if driver != ProviderPG {
+		return query
+	}
+	var b strings.Builder
+	b.Grow(len(query) + 8)
+	n := 0
+	for _, r := range query {
+		if r == '?' {
+			n++
+			b.WriteByte('$')
+			b.WriteString(strconv.Itoa(n))
+			continue
+		}
+		b.WriteRune(r)
+	}
+	return b.String()
+}
+
+// List returns the folders and files directly below parentID, folders first.
+func (s *pgStore) List(ctx context.Context, parentID string) ([]Entry, error) {
+	pid, err := parseEntryID(parentID)
+	if err != nil {
+		return nil, err
+	}
+	folders, err := s.queryFolders(ctx, "parent_id = ?", pid)
+	if err != nil {
+		return nil, err
+	}
+	files, err := s.queryFiles(ctx, "folder_id = ? AND current_version = 1", pid)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]Entry, 0, len(folders)+len(files))
+	for _, f := range folders {
+		out = append(out, folderRowToEntry(f, s.Name()))
+	}
+	for _, f := range files {
+		out = append(out, fileRowToEntry(f, s.Name()))
+	}
+	return out, nil
+}
+
+// Stat resolves a folder or file id to an Entry. Folders win when both id
+// spaces overlap (they never do on a real portal, but the lookup is cheap).
+func (s *pgStore) Stat(ctx context.Context, id string) (Entry, error) {
+	n, err := parseEntryID(id)
+	if err != nil {
+		return Entry{}, err
+	}
+	folders, err := s.queryFolders(ctx, "id = ?", n)
+	if err != nil {
+		return Entry{}, err
+	}
+	if len(folders) > 0 {
+		return folderRowToEntry(folders[0], s.Name()), nil
+	}
+	files, err := s.queryFiles(ctx, "id = ? AND current_version = 1", n)
+	if err != nil {
+		return Entry{}, err
+	}
+	if len(files) == 0 {
+		return Entry{}, fmt.Errorf("onlyoffice: sql file store: id %s not found", id)
+	}
+	return fileRowToEntry(files[0], s.Name()), nil
+}
+
+// Download streams the file's current version from the portal's S3/MinIO store.
+// The object key is reconstructed from the file id and version; the parent
+// folder id is not part of the key.
+func (s *pgStore) Download(ctx context.Context, id string, w io.Writer) (int64, error) {
+	n, err := parseEntryID(id)
+	if err != nil {
+		return 0, err
+	}
+	files, err := s.queryFiles(ctx, "id = ? AND current_version = 1", n)
+	if err != nil {
+		return 0, err
+	}
+	if len(files) == 0 {
+		return 0, fmt.Errorf("onlyoffice: sql file store: file %s not found", id)
+	}
+	f := files[0]
+	key := csObjectKey(s.tenantID, f.id, f.version, filepath.Ext(f.title))
+	return downloadMinioObject(ctx, s.http, key, w)
+}
+
+// CreateFolder is unavailable: the SQL backend is read-only.
+func (s *pgStore) CreateFolder(context.Context, string, string) (Entry, error) {
+	return Entry{}, ErrReadOnly
+}
+
+// Upload is unavailable: the SQL backend is read-only.
+func (s *pgStore) Upload(context.Context, string, string, io.Reader) (Entry, error) {
+	return Entry{}, ErrReadOnly
+}
+
+// Move is unavailable: the SQL backend is read-only.
+func (s *pgStore) Move(context.Context, []string, string) error { return ErrReadOnly }
+
+// Copy is unavailable: the SQL backend is read-only.
+func (s *pgStore) Copy(context.Context, []string, string) error { return ErrReadOnly }
+
+// Rename is unavailable: the SQL backend is read-only.
+func (s *pgStore) Rename(context.Context, string, string) error { return ErrReadOnly }
+
+// Delete is unavailable: the SQL backend is read-only.
+func (s *pgStore) Delete(context.Context, []string) error { return ErrReadOnly }
+
+// Search matches file titles by substring. Content search lives in the
+// Elasticsearch backend; q.InContent is ignored here.
+func (s *pgStore) Search(ctx context.Context, q SearchQuery) ([]SearchHit, error) {
+	text := strings.TrimSpace(q.Text)
+	if text == "" {
+		return nil, fmt.Errorf("onlyoffice: empty search query")
+	}
+	limit := q.Limit
+	if limit <= 0 {
+		limit = pgSearchLimit
+	}
+	if limit > pgSearchMaxLimit {
+		limit = pgSearchMaxLimit
+	}
+
+	where := "title LIKE ? AND current_version = 1"
+	args := []any{"%" + text + "%"}
+	if s.hasTenant {
+		where += " AND tenant_id = ?"
+		args = append(args, s.tenantID)
+	}
+	if fid := strings.TrimSpace(q.FolderID); fid != "" {
+		n, err := parseEntryID(fid)
+		if err != nil {
+			return nil, err
+		}
+		where += " AND folder_id = ?"
+		args = append(args, n)
+	}
+	for _, ext := range normalizeExtensions(q.Extensions) {
+		where += " AND LOWER(title) LIKE ?"
+		args = append(args, "%."+ext)
+	}
+	query := rebind(`SELECT id, folder_id, title, content_length, version, create_on, modified_on
+        FROM files_file WHERE `+where+` ORDER BY modified_on DESC, id DESC LIMIT ?`, s.driver)
+	args = append(args, limit)
+
+	rows, err := s.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("onlyoffice: sql search: %w", err)
+	}
+	defer rows.Close()
+	var hits []SearchHit
+	for rows.Next() {
+		f, err := scanFileRow(rows)
+		if err != nil {
+			return nil, err
+		}
+		hits = append(hits, SearchHit{Entry: fileRowToEntry(f, s.Name())})
+	}
+	return hits, rows.Err()
+}
+
+// queryFolders runs a folder SELECT with the tenant filter applied.
+func (s *pgStore) queryFolders(ctx context.Context, where string, arg any) ([]pgFolderRow, error) {
+	args := []any{arg}
+	if s.hasTenant {
+		where += " AND tenant_id = ?"
+		args = append(args, s.tenantID)
+	}
+	query := rebind(`SELECT id, parent_id, title, create_on, modified_on
+        FROM files_folder WHERE `+where+` ORDER BY title, id`, s.driver)
+	rows, err := s.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("onlyoffice: sql list folders: %w", err)
+	}
+	defer rows.Close()
+	var out []pgFolderRow
+	for rows.Next() {
+		var r pgFolderRow
+		if err := rows.Scan(&r.id, &r.parentID, &r.title, &r.created, &r.modified); err != nil {
+			return nil, fmt.Errorf("onlyoffice: sql folder row: %w", err)
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
+// queryFiles runs a file SELECT for the current version with the tenant filter.
+func (s *pgStore) queryFiles(ctx context.Context, where string, arg any) ([]pgFileRow, error) {
+	args := []any{arg}
+	if s.hasTenant {
+		where += " AND tenant_id = ?"
+		args = append(args, s.tenantID)
+	}
+	query := rebind(`SELECT id, folder_id, title, content_length, version, create_on, modified_on
+        FROM files_file WHERE `+where+` ORDER BY title, id`, s.driver)
+	rows, err := s.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("onlyoffice: sql list files: %w", err)
+	}
+	defer rows.Close()
+	var out []pgFileRow
+	for rows.Next() {
+		f, err := scanFileRow(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, f)
+	}
+	return out, rows.Err()
+}
+
+// pgFileRow is one current files_file row.
+type pgFileRow struct {
+	id       int64
+	folderID int64
+	title    string
+	size     int64
+	version  int
+	created  time.Time
+	modified time.Time
+}
+
+// pgFolderRow is one files_folder row.
+type pgFolderRow struct {
+	id       int64
+	parentID int64
+	title    string
+	created  time.Time
+	modified time.Time
+}
+
+// scanFileRow reads the canonical file column order.
+func scanFileRow(rows *sql.Rows) (pgFileRow, error) {
+	var f pgFileRow
+	if err := rows.Scan(&f.id, &f.folderID, &f.title, &f.size, &f.version, &f.created, &f.modified); err != nil {
+		return f, fmt.Errorf("onlyoffice: sql file row: %w", err)
+	}
+	return f, nil
+}
+
+// fileRowToEntry maps a files_file row to the canonical model.
+func fileRowToEntry(f pgFileRow, provider string) Entry {
+	return Entry{
+		ID:       strconv.FormatInt(f.id, 10),
+		ParentID: strconv.FormatInt(f.folderID, 10),
+		Title:    f.title,
+		Kind:     File,
+		Size:     f.size,
+		MIME:     mimeForTitle(f.title, ""),
+		Created:  f.created.UTC(),
+		Modified: f.modified.UTC(),
+		Version:  f.version,
+		Provider: provider,
+	}
+}
+
+// folderRowToEntry maps a files_folder row to the canonical model.
+func folderRowToEntry(f pgFolderRow, provider string) Entry {
+	return Entry{
+		ID:       strconv.FormatInt(f.id, 10),
+		ParentID: strconv.FormatInt(f.parentID, 10),
+		Title:    f.title,
+		Kind:     Folder,
+		Created:  f.created.UTC(),
+		Modified: f.modified.UTC(),
+		Provider: provider,
+	}
+}
+
+// csObjectKey reconstructs the object key the portal's S3 consumer uses:
+//
+//	00/00/<tenant>/files/folder_<shard>/file_<id>/v<version>/content.<ext>
+//
+// The shard is the next thousand above the file id (file 3727 -> folder_4000),
+// NOT the parent folder id — verified live against the MinIO bucket.
+func csObjectKey(tenant int64, fileID int64, version int, ext string) string {
+	shard := (fileID/1000 + 1) * 1000
+	ext = strings.TrimPrefix(strings.ToLower(strings.TrimSpace(ext)), ".")
+	if ext == "" {
+		ext = "bin"
+	}
+	if version < 1 {
+		version = 1
+	}
+	if tenant <= 0 {
+		tenant = 1
+	}
+	return fmt.Sprintf("00/00/%02d/files/folder_%d/file_%d/v%d/content.%s", tenant, shard, fileID, version, ext)
+}
+
+// parseEntryID parses a numeric OnlyOffice id or returns a store error.
+func parseEntryID(id string) (int64, error) {
+	n, err := strconv.ParseInt(strings.TrimSpace(id), 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("onlyoffice: sql file store: non-numeric id %q", id)
+	}
+	return n, nil
+}

file_pg_integration_test.go

@@ -0,0 +1,139 @@
+//go:build integration
+
+package onlyoffice
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestIntegrationPGStore exercises the read-only SQL backend against the live
+// Community Server database and cross-checks list/stat/download with the REST
+// FileStore. It needs ONLYOFFICE_DSN plus the usual ONLYOFFICE_URL/USER/PASS;
+// ONLYOFFICE_PG_TEST_FILE_ID / ONLYOFFICE_PG_TEST_FOLDER_ID pick a real file
+// (a file reachable over REST too). Download streams from MinIO, so it also
+// needs MINIO_ACCESS_KEY/MINIO_SECRET_KEY.
+//
+// The live Community Server runs on MySQL; PostgreSQL is supported by the same
+// code path when the DSN says so.
+func TestIntegrationPGStore(t *testing.T) {
+	cfg := PGConfigFromEnv()
+	if strings.TrimSpace(cfg.DSN) == "" {
+		t.Skip("ONLYOFFICE_DSN not set — skipping SQL store integration test")
+	}
+	store, err := NewPGStore(cfg)
+	if err != nil {
+		t.Fatalf("NewPGStore: %v", err)
+	}
+	t.Cleanup(func() { _ = store.Close() })
+	t.Logf("sql store backend: %s", store.Name())
+	ctx := context.Background()
+
+	if err := testPGStoreReadOnly(ctx, store); err != nil {
+		t.Fatal(err)
+	}
+
+	fileID := strings.TrimSpace(os.Getenv("ONLYOFFICE_PG_TEST_FILE_ID"))
+	folderID := strings.TrimSpace(os.Getenv("ONLYOFFICE_PG_TEST_FOLDER_ID"))
+	if fileID == "" || folderID == "" {
+		t.Skip("ONLYOFFICE_PG_TEST_FILE_ID / ONLYOFFICE_PG_TEST_FOLDER_ID not set — skipping live comparison")
+	}
+
+	c := liveClient(t)
+	rest := c.Files()
+
+	dbFile, err := store.Stat(ctx, fileID)
+	if err != nil {
+		t.Fatalf("sql Stat(%s): %v", fileID, err)
+	}
+	restFile, err := rest.Stat(ctx, fileID)
+	if err != nil {
+		t.Fatalf("rest Stat(%s): %v", fileID, err)
+	}
+	if dbFile.Kind != File {
+		t.Errorf("sql kind = %v, want file", dbFile.Kind)
+	}
+	if dbFile.ID != restFile.ID || dbFile.Title != restFile.Title || dbFile.ParentID != restFile.ParentID {
+		t.Errorf("stat mismatch sql=%+v rest=%+v", dbFile, restFile)
+	}
+	// GetFile omits contentLength, so size is only comparable when REST has it.
+	if restFile.Size > 0 && dbFile.Size != restFile.Size {
+		t.Errorf("size sql=%d rest=%d", dbFile.Size, restFile.Size)
+	}
+	if d := dbFile.Modified.Sub(restFile.Modified); d > 2*time.Minute || d < -2*time.Minute {
+		t.Errorf("modified sql=%v rest=%v", dbFile.Modified, restFile.Modified)
+	}
+
+	list, err := store.List(ctx, folderID)
+	if err != nil {
+		t.Fatalf("sql List(%s): %v", folderID, err)
+	}
+	if entryByID(list, fileID) == nil {
+		t.Errorf("file %s not in sql List(%s)", fileID, folderID)
+	}
+
+	// Every file the REST layer can see in the folder must be in the SQL list
+	// (the SQL store sees more, so only assert this direction).
+	restList, err := rest.List(ctx, folderID)
+	if err != nil {
+		t.Fatalf("rest List(%s): %v", folderID, err)
+	}
+	dbIDs := make(map[string]bool, len(list))
+	for _, e := range list {
+		dbIDs[e.ID] = true
+	}
+	for _, e := range restList {
+		if e.Kind == File && !dbIDs[e.ID] {
+			t.Errorf("rest file %s (%q) missing from sql list", e.ID, e.Title)
+		}
+	}
+
+	var buf bytes.Buffer
+	n, err := store.Download(ctx, fileID, &buf)
+	if err != nil {
+		t.Fatalf("sql Download(%s): %v", fileID, err)
+	}
+	if n == 0 || n != dbFile.Size {
+		t.Errorf("sql Download = %d bytes, stat says %d", n, dbFile.Size)
+	}
+	if os.Getenv("MINIO_ACCESS_KEY") != "" && os.Getenv("MINIO_SECRET_KEY") != "" {
+		var restBuf bytes.Buffer
+		rn, err := rest.Download(ctx, fileID, &restBuf)
+		if err != nil {
+			t.Fatalf("rest Download(%s): %v", fileID, err)
+		}
+		if rn != n || !bytes.Equal(restBuf.Bytes(), buf.Bytes()) {
+			t.Errorf("download mismatch sql=%d rest=%d bytes", n, rn)
+		}
+	} else {
+		t.Log("MINIO_ACCESS_KEY/MINIO_SECRET_KEY not set — REST download cross-check skipped")
+	}
+}
+
+// testPGStoreReadOnly asserts that every write method returns ErrReadOnly.
+func testPGStoreReadOnly(ctx context.Context, s *pgStore) error {
+	if _, err := s.CreateFolder(ctx, "1", "x"); !errors.Is(err, ErrReadOnly) {
+		return errors.New("CreateFolder did not return ErrReadOnly")
+	}
+	if _, err := s.Upload(ctx, "1", "x", strings.NewReader("x")); !errors.Is(err, ErrReadOnly) {
+		return errors.New("Upload did not return ErrReadOnly")
+	}
+	if err := s.Move(ctx, []string{"1"}, "2"); !errors.Is(err, ErrReadOnly) {
+		return errors.New("Move did not return ErrReadOnly")
+	}
+	if err := s.Copy(ctx, []string{"1"}, "2"); !errors.Is(err, ErrReadOnly) {
+		return errors.New("Copy did not return ErrReadOnly")
+	}
+	if err := s.Rename(ctx, "1", "x"); !errors.Is(err, ErrReadOnly) {
+		return errors.New("Rename did not return ErrReadOnly")
+	}
+	if err := s.Delete(ctx, []string{"1"}); !errors.Is(err, ErrReadOnly) {
+		return errors.New("Delete did not return ErrReadOnly")
+	}
+	return nil
+}

file_pg_test.go

@@ -0,0 +1,165 @@
+package onlyoffice
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestRebind(t *testing.T) {
+	mysqlQuery := "SELECT id FROM files_file WHERE folder_id = ? AND title = ? LIMIT ?"
+	if got := rebind(mysqlQuery, ProviderMySQL); got != mysqlQuery {
+		t.Errorf("mysql query changed: %q", got)
+	}
+	want := "SELECT id FROM files_file WHERE folder_id = $1 AND title = $2 LIMIT $3"
+	if got := rebind(mysqlQuery, ProviderPG); got != want {
+		t.Errorf("rebind = %q, want %q", got, want)
+	}
+}
+
+func TestCSPObjectKey(t *testing.T) {
+	cases := []struct {
+		tenant  int64
+		fileID  int64
+		version int
+		ext     string
+		want    string
+	}{
+		{1, 2, 1, ".docx", "00/00/01/files/folder_1000/file_2/v1/content.docx"},
+		{1, 999, 1, ".pdf", "00/00/01/files/folder_1000/file_999/v1/content.pdf"},
+		{1, 1000, 1, ".xlsx", "00/00/01/files/folder_2000/file_1000/v1/content.xlsx"},
+		{1, 3727, 1, ".pdf", "00/00/01/files/folder_4000/file_3727/v1/content.pdf"},
+		{1, 22484, 1, ".PDF", "00/00/01/files/folder_23000/file_22484/v1/content.pdf"},
+		{1, 4, 6, "xlsx", "00/00/01/files/folder_1000/file_4/v6/content.xlsx"},
+		{0, 7, 0, "", "00/00/01/files/folder_1000/file_7/v1/content.bin"},
+		{2, 11, 3, ".doc", "00/00/02/files/folder_1000/file_11/v3/content.doc"},
+	}
+	for _, tc := range cases {
+		if got := csObjectKey(tc.tenant, tc.fileID, tc.version, tc.ext); got != tc.want {
+			t.Errorf("csObjectKey(%d,%d,%d,%q) = %q, want %q", tc.tenant, tc.fileID, tc.version, tc.ext, got, tc.want)
+		}
+	}
+}
+
+func TestPGDriverDetection(t *testing.T) {
+	cases := []struct {
+		dsn, explicit, want string
+	}{
+		{"postgres://u:p@h:5432/onlyoffice", "", ProviderPG},
+		{"postgresql://u:p@h/db", "", ProviderPG},
+		{"host=h user=u password=p dbname=onlyoffice sslmode=disable", "", ProviderPG},
+		{"root:secret@tcp(127.0.0.1:3306)/onlyoffice?parseTime=true", "", ProviderMySQL},
+		{"mysql://root:secret@127.0.0.1:3306/onlyoffice", "", ProviderMySQL},
+		{"root:secret@tcp(h:3306)/db", "postgres", ProviderPG},
+		{"postgres://u:p@h/db", "mysql", ProviderMySQL},
+	}
+	for _, tc := range cases {
+		if got := pgDriver(tc.dsn, tc.explicit); got != tc.want {
+			t.Errorf("pgDriver(%q, %q) = %q, want %q", tc.dsn, tc.explicit, got, tc.want)
+		}
+	}
+}
+
+func TestNormalizeSQLDSNMySQL(t *testing.T) {
+	got, err := normalizeSQLDSN(ProviderMySQL, "mysql://root:secret@127.0.0.1:3306/onlyoffice")
+	if err != nil {
+		t.Fatalf("normalizeSQLDSN: %v", err)
+	}
+	want := "root:secret@tcp(127.0.0.1:3306)/onlyoffice?parseTime=true"
+	if got != want {
+		t.Errorf("normalize = %q, want %q", got, want)
+	}
+
+	// A driver DSN keeps parseTime and gains it when missing.
+	got, err = normalizeSQLDSN(ProviderMySQL, "root:secret@tcp(127.0.0.1:3306)/onlyoffice")
+	if err != nil {
+		t.Fatalf("normalizeSQLDSN: %v", err)
+	}
+	if got != want {
+		t.Errorf("normalize = %q, want %q", got, want)
+	}
+}
+
+func TestFileRowToEntry(t *testing.T) {
+	created := time.Date(2026, 9, 12, 18, 0, 37, 0, time.UTC)
+	modified := time.Date(2026, 9, 13, 13, 50, 36, 0, time.UTC)
+	e := fileRowToEntry(pgFileRow{
+		id: 22484, folderID: 649, title: "Rechnung.pdf",
+		size: 123433, version: 2, created: created, modified: modified,
+	}, ProviderMySQL)
+	if e.ID != "22484" || e.ParentID != "649" {
+		t.Errorf("ids = %q/%q", e.ID, e.ParentID)
+	}
+	if e.Title != "Rechnung.pdf" || e.Kind != File {
+		t.Errorf("title/kind = %q/%v", e.Title, e.Kind)
+	}
+	if e.Size != 123433 || e.Version != 2 {
+		t.Errorf("size/version = %d/%d", e.Size, e.Version)
+	}
+	if e.MIME != "application/pdf" {
+		t.Errorf("mime = %q", e.MIME)
+	}
+	if !e.Created.Equal(created) || !e.Modified.Equal(modified) {
+		t.Errorf("times = %v/%v", e.Created, e.Modified)
+	}
+	if e.Provider != ProviderMySQL {
+		t.Errorf("provider = %q", e.Provider)
+	}
+}
+
+func TestFolderRowToEntry(t *testing.T) {
+	modified := time.Date(2026, 8, 1, 10, 30, 0, 0, time.UTC)
+	e := folderRowToEntry(pgFolderRow{id: 649, parentID: 647, title: "2025", modified: modified}, ProviderMySQL)
+	if e.ID != "649" || e.ParentID != "647" || e.Title != "2025" {
+		t.Errorf("folder = %+v", e)
+	}
+	if e.Kind != Folder {
+		t.Errorf("kind = %v, want folder", e.Kind)
+	}
+	if e.Size != 0 || e.MIME != "" {
+		t.Errorf("folder size/mime = %d/%q", e.Size, e.MIME)
+	}
+	if !e.Modified.Equal(modified) {
+		t.Errorf("modified = %v", e.Modified)
+	}
+}
+
+func TestPGStoreWriteMethodsReadOnly(t *testing.T) {
+	s := &pgStore{driver: ProviderPG}
+	ctx := context.Background()
+	if _, err := s.CreateFolder(ctx, "1", "x"); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("CreateFolder err = %v", err)
+	}
+	if _, err := s.Upload(ctx, "1", "x", nil); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("Upload err = %v", err)
+	}
+	if err := s.Move(ctx, nil, "1"); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("Move err = %v", err)
+	}
+	if err := s.Copy(ctx, nil, "1"); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("Copy err = %v", err)
+	}
+	if err := s.Rename(ctx, "1", "x"); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("Rename err = %v", err)
+	}
+	if err := s.Delete(ctx, nil); !errors.Is(err, ErrReadOnly) {
+		t.Errorf("Delete err = %v", err)
+	}
+}
+
+func TestPGStoreName(t *testing.T) {
+	if got := (&pgStore{driver: ProviderPG}).Name(); got != ProviderPG {
+		t.Errorf("Name = %q, want %q", got, ProviderPG)
+	}
+	if got := (&pgStore{driver: ProviderMySQL}).Name(); got != ProviderMySQL {
+		t.Errorf("Name = %q, want %q", got, ProviderMySQL)
+	}
+}
+
+func TestPGStoreStatRejectsNonNumeric(t *testing.T) {
+	s := &pgStore{driver: ProviderPG}
+	if _, err := s.Stat(context.Background(), "not-a-number"); err == nil {
+		t.Error("Stat accepted a non-numeric id")
+	}
+}

file_text_index.go

@@ -0,0 +1,337 @@
+package onlyoffice
+
+// Text extraction pipeline for the own full-text index (epic #34, F6 #42).
+//
+// TextIndexer downloads stored documents, extracts text through docpipe
+// (pdftotext; OCR for scans) and writes the result to a TextIndex. For PDFs it
+// also indexes the text of embedded attachments (pdfdetach), so a scan filed
+// as an attachment is searchable too. It is the write side of ESTextIndex and
+// never touches the OnlyOffice server's own ES index.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+
+	"github.com/eslider/go-onlyoffice/internal/docpipe"
+)
+
+// defaultTextIndexExts are the formats extracted by default. The OnlyOffice
+// index already covers docx/xlsx/pptx; F6 adds PDF.
+var defaultTextIndexExts = []string{"pdf"}
+
+const (
+	defaultTextIndexWorkers = 3
+	defaultTextIndexLang    = "deu+eng"
+	maxTextIndexErrors      = 20
+)
+
+// TextExtractor turns a local file into indexable plain text. The default uses
+// docpipe (pdftotext + OCR); tests inject a fake to stay offline.
+type TextExtractor interface {
+	Extract(path, workDir, lang string, minChars int) (string, error)
+}
+
+// docpipeExtractor is the production TextExtractor.
+type docpipeExtractor struct{ tools docpipe.Tools }
+
+// Extract renders the file as Markdown, OCRing PDFs/images with a weak text
+// layer first and appending the text of embedded PDF attachments
+// (docpipe.ToMarkdownWithAttachments).
+func (d docpipeExtractor) Extract(path, workDir, lang string, minChars int) (string, error) {
+	text, err := d.tools.ToMarkdownWithAttachments(path, workDir, lang, minChars)
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(text), nil
+}
+
+// IndexOptions controls a TextIndexer run.
+type IndexOptions struct {
+	Recursive  bool     // IndexFolder: descend into subfolders
+	Extensions []string // empty = defaultTextIndexExts (pdf)
+	Limit      int      // max files to index, 0 = all
+	Lang       string   // OCR language(s), default deu+eng
+	MinChars   int      // OCR threshold, default docpipe.DefaultMinTextChars
+	Workers    int      // parallel downloads/extractions, default 3
+}
+
+// IndexResult summarises a run.
+type IndexResult struct {
+	Scanned int
+	Indexed int
+	Skipped int
+	Failed  int
+	Errors  []string
+}
+
+// TextIndexer wires a FileStore, a TextIndex and an extractor together.
+type TextIndexer struct {
+	Store     FileStore
+	Index     TextIndex
+	Extractor TextExtractor // nil = local docpipe tools
+	WorkDir   string        // temp dir for downloads/extraction
+}
+
+// NewTextIndexer returns a TextIndexer over the given store and index.
+func NewTextIndexer(store FileStore, index TextIndex) *TextIndexer {
+	return &TextIndexer{Store: store, Index: index}
+}
+
+// textIndexEnsurer is implemented by indexes that can be created up front.
+type textIndexEnsurer interface {
+	Ensure(ctx context.Context) error
+}
+
+// Ensure creates the backing index when the TextIndex supports it.
+func (ix *TextIndexer) Ensure(ctx context.Context) error {
+	if e, ok := ix.Index.(textIndexEnsurer); ok {
+		return e.Ensure(ctx)
+	}
+	return nil
+}
+
+// IndexFiles stats the given file ids and indexes them.
+func (ix *TextIndexer) IndexFiles(ctx context.Context, ids []string, opts IndexOptions) (IndexResult, error) {
+	entries := make([]Entry, 0, len(ids))
+	for _, id := range ids {
+		e, err := ix.Store.Stat(ctx, id)
+		if err != nil {
+			return IndexResult{}, fmt.Errorf("onlyoffice: stat %s: %w", id, err)
+		}
+		entries = append(entries, e)
+	}
+	return ix.IndexEntries(ctx, entries, opts)
+}
+
+// IndexFolder lists a folder and indexes every matching file.
+func (ix *TextIndexer) IndexFolder(ctx context.Context, folderID string, opts IndexOptions) (IndexResult, error) {
+	entries, err := ix.collect(ctx, folderID, opts.Recursive)
+	if err != nil {
+		return IndexResult{}, err
+	}
+	return ix.IndexEntries(ctx, entries, opts)
+}
+
+// PlanFolder lists the files IndexFolder would process, without downloading or
+// extracting anything.
+func (ix *TextIndexer) PlanFolder(ctx context.Context, folderID string, opts IndexOptions) ([]Entry, error) {
+	entries, err := ix.collect(ctx, folderID, opts.Recursive)
+	if err != nil {
+		return nil, err
+	}
+	return selectEntries(entries, opts), nil
+}
+
+// PlanFiles stats the ids and returns those that would be indexed.
+func (ix *TextIndexer) PlanFiles(ctx context.Context, ids []string, opts IndexOptions) ([]Entry, error) {
+	entries := make([]Entry, 0, len(ids))
+	for _, id := range ids {
+		e, err := ix.Store.Stat(ctx, id)
+		if err != nil {
+			return nil, fmt.Errorf("onlyoffice: stat %s: %w", id, err)
+		}
+		entries = append(entries, e)
+	}
+	return selectEntries(entries, opts), nil
+}
+
+// IndexEntries extracts and indexes the given files (folders are ignored).
+func (ix *TextIndexer) IndexEntries(ctx context.Context, entries []Entry, opts IndexOptions) (IndexResult, error) {
+	opts = opts.withDefaults()
+	var res IndexResult
+	work := selectEntries(entries, opts)
+	res.Scanned = len(entries)
+	res.Skipped = len(entries) - len(work)
+	if len(work) == 0 {
+		return res, nil
+	}
+
+	workers := opts.Workers
+	if workers > len(work) {
+		workers = len(work)
+	}
+	if workers < 1 {
+		workers = 1
+	}
+
+	type outcome struct {
+		doc TextDoc
+		err error
+	}
+	jobs := make(chan Entry)
+	results := make(chan outcome, workers)
+	var wg sync.WaitGroup
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for e := range jobs {
+				if err := ctx.Err(); err != nil {
+					results <- outcome{err: err}
+					continue
+				}
+				doc, err := ix.indexOne(ctx, e, opts)
+				results <- outcome{doc: doc, err: err}
+			}
+		}()
+	}
+	go func() {
+		defer close(jobs)
+		for _, e := range work {
+			select {
+			case jobs <- e:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+	go func() {
+		wg.Wait()
+		close(results)
+	}()
+
+	var docs []TextDoc
+	for r := range results {
+		if r.err != nil {
+			res.Failed++
+			if len(res.Errors) < maxTextIndexErrors {
+				res.Errors = append(res.Errors, r.err.Error())
+			}
+			continue
+		}
+		docs = append(docs, r.doc)
+	}
+	if err := ctx.Err(); err != nil {
+		return res, err
+	}
+	if len(docs) > 0 {
+		if err := ix.Index.Put(ctx, docs); err != nil {
+			return res, fmt.Errorf("onlyoffice: index %d docs: %w", len(docs), err)
+		}
+		res.Indexed = len(docs)
+	}
+	return res, nil
+}
+
+// indexOne downloads and extracts a single file.
+func (ix *TextIndexer) indexOne(ctx context.Context, e Entry, opts IndexOptions) (TextDoc, error) {
+	ext := fileExt(e.Title)
+	dir := ix.WorkDir
+	if dir == "" {
+		dir = os.TempDir()
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return TextDoc{}, err
+	}
+	tmp, err := os.CreateTemp(dir, "ooidx-*."+ext)
+	if err != nil {
+		return TextDoc{}, err
+	}
+	tmpPath := tmp.Name()
+	defer os.Remove(tmpPath)
+
+	if _, err := ix.Store.Download(ctx, e.ID, tmp); err != nil {
+		tmp.Close()
+		return TextDoc{}, fmt.Errorf("download %s (%s): %w", e.ID, e.Title, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return TextDoc{}, err
+	}
+	text, err := ix.extractor().Extract(tmpPath, dir, opts.Lang, opts.MinChars)
+	if err != nil {
+		return TextDoc{}, fmt.Errorf("extract %s: %w", e.Title, err)
+	}
+	return TextDoc{ID: e.ID, Title: e.Title, FolderID: e.ParentID, Ext: ext, Content: text}, nil
+}
+
+// collect lists files under folderID, breadth-first when recursive.
+func (ix *TextIndexer) collect(ctx context.Context, folderID string, recursive bool) ([]Entry, error) {
+	var files []Entry
+	queue := []string{folderID}
+	for len(queue) > 0 {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		id := queue[0]
+		queue = queue[1:]
+		entries, err := ix.Store.List(ctx, id)
+		if err != nil {
+			return nil, fmt.Errorf("onlyoffice: list folder %s: %w", id, err)
+		}
+		for _, e := range entries {
+			if e.Kind == Folder {
+				if recursive {
+					queue = append(queue, e.ID)
+				}
+				continue
+			}
+			if e.ParentID == "" {
+				e.ParentID = id
+			}
+			files = append(files, e)
+		}
+	}
+	return files, nil
+}
+
+// selectEntries filters files by extension and applies the limit.
+func selectEntries(entries []Entry, opts IndexOptions) []Entry {
+	allowed := extensionSet(opts.Extensions)
+	work := make([]Entry, 0, len(entries))
+	for _, e := range entries {
+		if e.Kind != File {
+			continue
+		}
+		if opts.Limit > 0 && len(work) >= opts.Limit {
+			break
+		}
+		if !allowed[fileExt(e.Title)] {
+			continue
+		}
+		work = append(work, e)
+	}
+	return work
+}
+
+// extensionSet normalises the extension allow-list (default: pdf).
+func extensionSet(exts []string) map[string]bool {
+	if len(exts) == 0 {
+		exts = defaultTextIndexExts
+	}
+	set := make(map[string]bool, len(exts))
+	for _, e := range normalizeExtensions(exts) {
+		set[e] = true
+	}
+	return set
+}
+
+// fileExt returns the lower-case extension without the dot.
+func fileExt(title string) string {
+	return strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(title)), "."))
+}
+
+// withDefaults fills zero-valued options.
+func (o IndexOptions) withDefaults() IndexOptions {
+	if o.Workers <= 0 {
+		o.Workers = defaultTextIndexWorkers
+	}
+	if o.MinChars <= 0 {
+		o.MinChars = docpipe.DefaultMinTextChars
+	}
+	if strings.TrimSpace(o.Lang) == "" {
+		o.Lang = defaultTextIndexLang
+	}
+	return o
+}
+
+// extractor returns the configured extractor or the local docpipe default.
+func (ix *TextIndexer) extractor() TextExtractor {
+	if ix.Extractor != nil {
+		return ix.Extractor
+	}
+	return docpipeExtractor{tools: docpipe.LookPath()}
+}

files.go

@@ -247,6 +247,8 @@ func (c *Client) UploadProjectFileReplacing(ctx context.Context, projectID, loca
 }
 
 // GetFile returns file metadata including viewUrl for download.
+//
+// Deprecated: use FileStore.Stat via Client.Files()/Client.FileStore.
 func (c *Client) GetFile(ctx context.Context, fileID string) (*FileEntry, error) {
 	if fileID == "" {
 		return nil, fmt.Errorf("file id is required")
@@ -260,6 +262,8 @@ func (c *Client) GetFile(ctx context.Context, fileID string) (*FileEntry, error)
 }
 
 // RenameFile sets a new title (including extension) for the file.
+//
+// Deprecated: use FileStore.Rename via Client.Files()/Client.FileStore.
 func (c *Client) RenameFile(ctx context.Context, fileID, newTitle string) (*FileEntry, error) {
 	if fileID == "" || newTitle == "" {
 		return nil, fmt.Errorf("file id and new title are required")
@@ -275,6 +279,8 @@ func (c *Client) RenameFile(ctx context.Context, fileID, newTitle string) (*File
 // 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.
+//
+// Deprecated: use FileStore.Delete via Client.Files()/Client.FileStore.
 func (c *Client) DeleteFiles(ctx context.Context, fileIDs []int) error {
 	if len(fileIDs) == 0 {
 		return fmt.Errorf("no file ids to delete")
@@ -288,6 +294,8 @@ func (c *Client) DeleteFiles(ctx context.Context, fileIDs []int) error {
 
 // ListFolder returns the Documents module listing for a folder id
 // (GET /api/2.0/files/{folderId}).
+//
+// Deprecated: use FileStore.List via Client.Files()/Client.FileStore.
 func (c *Client) ListFolder(ctx context.Context, folderID string) (map[string]any, error) {
 	if folderID == "" {
 		return nil, fmt.Errorf("folder id is required")
@@ -313,6 +321,8 @@ func (c *Client) CreateFolder(ctx context.Context, parentFolderID, title string)
 }
 
 // MoveFiles moves file ids into destFolderID (Documents fileops/move).
+//
+// Deprecated: use FileStore.Move via Client.Files()/Client.FileStore.
 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")
@@ -343,6 +353,8 @@ func (c *Client) MoveFiles(ctx context.Context, destFolderID int, fileIDs []int)
 }
 
 // UploadToFolder uploads a local file into an arbitrary Documents folder id.
+//
+// Deprecated: use FileStore.Upload via Client.Files()/Client.FileStore.
 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")
@@ -400,6 +412,8 @@ func FileFolderID(f *FileEntry) string {
 // as API calls. Writes into dst. When the portal serves the file from its stale
 // AWS S3 consumer, the bytes are fetched from the local MinIO store instead
 // (see storage_fallback.go).
+//
+// Deprecated: use FileStore.Download via Client.Files()/Client.FileStore.
 func (c *Client) DownloadFile(ctx context.Context, fileID string, dst io.Writer) (int64, error) {
 	f, err := c.GetFile(ctx, fileID)
 	if err != nil {

files_webdav.go

@@ -52,6 +52,8 @@ type DavListing struct {
 
 // ListDavFolder returns the contents of a folder by id, which may be a
 // symbolic root such as "@my". For "@root" use ListDavSections.
+//
+// Deprecated: use FileStore.List via Client.Files()/Client.FileStore.
 func (c *Client) ListDavFolder(ctx context.Context, id string) (*DavListing, error) {
 	raw, err := c.getJSON(ctx, "/api/2.0/files/"+url.PathEscape(id))
 	if err != nil {
@@ -111,6 +113,8 @@ func (c *Client) ListDavSections(ctx context.Context) ([]DavFolder, error) {
 }
 
 // CreateDavFolder creates a folder titled title inside parentID.
+//
+// Deprecated: use FileStore.CreateFolder via Client.Files()/Client.FileStore.
 func (c *Client) CreateDavFolder(ctx context.Context, parentID, title string) (*DavFolder, error) {
 	raw, err := c.postJSON(ctx, "/api/2.0/files/folder/"+url.PathEscape(parentID),
 		map[string]string{"title": title})
@@ -130,6 +134,8 @@ func (c *Client) CreateDavFolder(ctx context.Context, parentID, title string) (*
 }
 
 // RenameDavFolder renames a folder.
+//
+// Deprecated: use FileStore.Rename via Client.Files()/Client.FileStore.
 func (c *Client) RenameDavFolder(ctx context.Context, id, title string) error {
 	_, err := c.putJSON(ctx, "/api/2.0/files/folder/"+url.PathEscape(id),
 		map[string]string{"title": title})
@@ -137,6 +143,8 @@ func (c *Client) RenameDavFolder(ctx context.Context, id, title string) error {
 }
 
 // RenameDavFile renames a file (title includes the extension).
+//
+// Deprecated: use FileStore.Rename via Client.Files()/Client.FileStore.
 func (c *Client) RenameDavFile(ctx context.Context, id, title string) error {
 	_, err := c.putJSON(ctx, "/api/2.0/files/file/"+url.PathEscape(id),
 		map[string]string{"title": title})
@@ -147,6 +155,8 @@ func (c *Client) RenameDavFile(ctx context.Context, id, title string) error {
 // The fileops API answers 200 with per-operation error strings even when
 // nothing moves (e.g. missing permission), so the response is parsed and the
 // first operation error is returned instead of a silent nil.
+//
+// Deprecated: use FileStore.Move via Client.Files()/Client.FileStore.
 func (c *Client) MoveDavItems(ctx context.Context, folderIDs, fileIDs []string, destFolderID string) error {
 	raw, err := c.putJSON(ctx, "/api/2.0/files/fileops/move", map[string]any{
 		"folderIds":    nums(folderIDs),
@@ -163,6 +173,8 @@ func (c *Client) MoveDavItems(ctx context.Context, folderIDs, fileIDs []string,
 
 // CopyDavItems copies the given folders and/or files into destFolderID.
 // Per-operation errors are surfaced like in MoveDavItems.
+//
+// Deprecated: use FileStore.Copy via Client.Files()/Client.FileStore.
 func (c *Client) CopyDavItems(ctx context.Context, folderIDs, fileIDs []string, destFolderID string) error {
 	raw, err := c.putJSON(ctx, "/api/2.0/files/fileops/copy", map[string]any{
 		"folderIds":           nums(folderIDs),
@@ -226,6 +238,8 @@ func fileopsError(raw json.RawMessage) error {
 }
 
 // DeleteDavItems deletes the given folders and/or files.
+//
+// Deprecated: use FileStore.Delete via Client.Files()/Client.FileStore.
 func (c *Client) DeleteDavItems(ctx context.Context, folderIDs, fileIDs []string) error {
 	body := map[string]any{"DeleteAfter": true, "Immediately": true}
 	for _, id := range folderIDs {
@@ -242,6 +256,8 @@ func (c *Client) DeleteDavItems(ctx context.Context, folderIDs, fileIDs []string
 }
 
 // UploadDavFile uploads src (fileName) into folderID, streaming from src.
+//
+// Deprecated: use FileStore.Upload via Client.Files()/Client.FileStore.
 func (c *Client) UploadDavFile(ctx context.Context, folderID, fileName string, src io.Reader) (*DavFile, error) {
 	raw, err := c.uploadReader(ctx, "/api/2.0/files/"+url.PathEscape(folderID)+"/upload", "file", fileName, src)
 	if err != nil {
@@ -261,6 +277,8 @@ func (c *Client) UploadDavFile(ctx context.Context, folderID, fileName string, s
 
 // DownloadDavFile streams the file identified by id to w, returning bytes
 // copied. It shares the MinIO stale-S3 fallback with DownloadFile.
+//
+// Deprecated: use FileStore.Download via Client.Files()/Client.FileStore.
 func (c *Client) DownloadDavFile(ctx context.Context, id string, w io.Writer) (int64, error) {
 	return c.DownloadFile(ctx, id, w)
 }

go.mod

@@ -13,7 +13,9 @@ require (
 	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/go-sql-driver/mysql v1.10.1
 	github.com/google/go-querystring v1.2.0
+	github.com/jackc/pgx/v5 v5.11.0
 	github.com/joho/godotenv v1.5.1
 	github.com/mattn/go-runewidth v0.0.15
 	github.com/muesli/termenv v0.16.0
@@ -24,6 +26,7 @@ require (
 )
 
 require (
+	filippo.io/edwards25519 v1.2.0 // indirect
 	github.com/JohannesKaufmann/dom v0.3.1 // indirect
 	github.com/alecthomas/chroma/v2 v2.14.0 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
@@ -36,6 +39,10 @@ require (
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -48,6 +55,7 @@ require (
 	github.com/richardlehane/mscfb v1.0.7 // indirect
 	github.com/richardlehane/msoleps v1.0.6 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/rogpeppe/go-internal v1.16.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/tiendc/go-deepcopy v1.7.2 // indirect
 	github.com/xuri/efp v0.0.1 // indirect

go.sum

@@ -1,3 +1,5 @@
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 github.com/JohannesKaufmann/dom v0.3.1 h1:J16l9JAHWgkFPR3VIPbQ1gvS0cWab6laK1q7PFL3qh0=
 github.com/JohannesKaufmann/dom v0.3.1/go.mod h1:BZPkf8ZeYrBgABjwJn9iiKt8aiCtkxpHkevms+Yp2DE=
 github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.2 h1:XFJZFWESIWlUEHHjzBuv8RvrtCWnSGlimEX17ysSDb8=
@@ -35,6 +37,8 @@ github.com/charmbracelet/x/exp/golden v0.0.0-20240715153702-9ba8adf781c4/go.mod
 github.com/containerd/console v1.0.4-0.20230313162750-1ae8d489ac81 h1:q2hJAaP1k2wIvVRd/hEHD7lacgqrCPS+k8g1MndzfWY=
 github.com/containerd/console v1.0.4-0.20230313162750-1ae8d489ac81/go.mod h1:YynlIjWYF8myEu6sdkwKIvGQq+cOckRm6So2avqoYAk=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
@@ -47,6 +51,8 @@ github.com/eslider/go-hocr v0.2.2-0.20260827163626-8ff01582b002 h1:LOFxQG4mxvlH7
 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/go-sql-driver/mysql v1.10.1 h1:arlSnNLq6a5yxGxV7qg9lF4j0C+KwD6NbQyKr9QL6ME=
+github.com/go-sql-driver/mysql v1.10.1/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-querystring v1.2.0 h1:yhqkPbu2/OH+V9BfpCVPZkNmUXhb2gBxJArfhIxNtP0=
@@ -63,8 +69,20 @@ github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUq
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
+github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
@@ -98,6 +116,8 @@ github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJ
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8rc=
 github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
@@ -107,6 +127,9 @@ github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/tiendc/go-deepcopy v1.7.2 h1:Ut2yYR7W9tWjTQitganoIue4UGxZwCcJy3orjrrIj44=
@@ -142,8 +165,10 @@ golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
 golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
 golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 modernc.org/cc/v4 v4.29.1 h1:MKgdCV3WykTSPqpVrnxdEDS0HEd2FHpKZDzxzU5LyeI=

internal/docpipe/docpipe.go

@@ -5,6 +5,7 @@
 //   - pandoc     — md↔docx
 //   - ocrmypdf   — OCR into a searchable PDF
 //   - pdftotext  — extract text layer
+//   - pdfdetach  — list/save embedded PDF attachments
 //   - tesseract  — OCR single images when ocrmypdf is unsuitable
 //   - ghostscript (gs) — PDF rewrite/optimize via PostScript (pdfwrite)
 package docpipe
@@ -26,6 +27,7 @@ type Tools struct {
 	Pandoc      string
 	OCRMyPDF    string
 	PDFToText   string
+	PDFDetach   string
 	Tesseract   string
 	Ghostscript string
 }
@@ -44,6 +46,7 @@ func LookPath() Tools {
 		Pandoc:      find("pandoc"),
 		OCRMyPDF:    find("ocrmypdf"),
 		PDFToText:   find("pdftotext"),
+		PDFDetach:   find("pdfdetach"),
 		Tesseract:   find("tesseract"),
 		Ghostscript: find("gs", "ghostscript"),
 	}

internal/docpipe/pdfattach.go

@@ -0,0 +1,231 @@
+package docpipe
+
+// Embedded PDF attachments (F6 #42). Digitised invoices often carry the
+// original scan as a PDF attachment; the searchable body may hold only a
+// summary. pdfdetach (poppler) lists/saves them; each saved attachment is run
+// through the normal docpipe extraction (pdftotext/OCR).
+
+import (
+	"bytes"
+	"encoding/xml"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// PDFAttachment is one embedded file in a PDF.
+type PDFAttachment struct {
+	Index int    // 1-based number as `pdfdetach -list` reports it
+	Name  string // embedded file name
+}
+
+// AttachmentText is the extracted text of one embedded attachment.
+type AttachmentText struct {
+	Name string
+	Text string
+}
+
+// parseAttachmentList parses `pdfdetach -list` output. The first line is a
+// count ("N embedded files"); every following line is "<index>: <name>".
+// Pure, so it is unit-tested.
+func parseAttachmentList(out string) []PDFAttachment {
+	var atts []PDFAttachment
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		colon := strings.Index(line, ":")
+		if colon <= 0 {
+			continue
+		}
+		n, err := strconv.Atoi(strings.TrimSpace(line[:colon]))
+		if err != nil {
+			continue
+		}
+		name := strings.TrimSpace(line[colon+1:])
+		if name == "" {
+			continue
+		}
+		atts = append(atts, PDFAttachment{Index: n, Name: name})
+	}
+	return atts
+}
+
+// safeAttachmentName strips directories and leading dots so a hostile
+// attachment name cannot escape the extraction directory.
+func safeAttachmentName(name string) string {
+	name = strings.ReplaceAll(strings.TrimSpace(name), "\\", "/")
+	name = filepath.Base(name)
+	name = strings.TrimLeft(name, ".")
+	if name == "" || name == "." || name == "/" {
+		return ""
+	}
+	return name
+}
+
+// JoinWithAttachments appends attachment text to the document body, each
+// section preceded by an "[attachment: <name>]" marker so a search hit shows
+// its source. Empty attachments are skipped. Pure, so it is unit-tested.
+func JoinWithAttachments(body string, atts []AttachmentText) string {
+	var b strings.Builder
+	b.WriteString(strings.TrimRight(body, "\n"))
+	for _, a := range atts {
+		text := strings.TrimSpace(a.Text)
+		if text == "" {
+			continue
+		}
+		b.WriteString("\n\n[attachment: ")
+		b.WriteString(a.Name)
+		b.WriteString("]\n\n")
+		b.WriteString(text)
+	}
+	return b.String()
+}
+
+// ListAttachments returns the embedded files of a PDF. A PDF without
+// attachments yields an empty slice and no error.
+func (t Tools) ListAttachments(pdfPath string) ([]PDFAttachment, error) {
+	if t.PDFDetach == "" {
+		return nil, fmt.Errorf("pdfdetach not found on PATH")
+	}
+	cmd := exec.Command(t.PDFDetach, "-list", pdfPath)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("pdfdetach -list %s: %w (%s)", filepath.Base(pdfPath), err, strings.TrimSpace(stderr.String()))
+	}
+	return parseAttachmentList(string(out)), nil
+}
+
+// SaveAttachment writes the n-th embedded file (1-based) to outPath.
+func (t Tools) SaveAttachment(pdfPath string, index int, outPath string) error {
+	if t.PDFDetach == "" {
+		return fmt.Errorf("pdfdetach not found on PATH")
+	}
+	if strings.TrimSpace(outPath) == "" {
+		return fmt.Errorf("output path required")
+	}
+	if err := EnsureDir(outPath); err != nil {
+		return err
+	}
+	cmd := exec.Command(t.PDFDetach, "-save", strconv.Itoa(index), "-o", outPath, pdfPath)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("pdfdetach -save %d: %w (%s)", index, err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+// ToMarkdownWithAttachments extracts the file as ToMarkdown does, then — for
+// PDFs — appends the text of every embedded attachment under an
+// "[attachment: <name>]" marker. Attachment failures are non-fatal: the body
+// is returned unchanged.
+func (t Tools) ToMarkdownWithAttachments(path, workDir, lang string, minChars int) (string, error) {
+	res, err := t.ToMarkdown(path, workDir, lang, minChars)
+	if err != nil {
+		return "", err
+	}
+	if Ext(path) != ".pdf" {
+		return res.Markdown, nil
+	}
+	atts, err := t.attachmentTexts(path, workDir, lang, minChars)
+	if err != nil {
+		return res.Markdown, nil
+	}
+	return JoinWithAttachments(res.Markdown, atts), nil
+}
+
+// attachmentTexts saves and extracts every embedded attachment, skipping the
+// ones that cannot be read. It returns an error only when the attachment list
+// itself cannot be obtained.
+func (t Tools) attachmentTexts(pdfPath, workDir, lang string, minChars int) ([]AttachmentText, error) {
+	list, err := t.ListAttachments(pdfPath)
+	if err != nil || len(list) == 0 {
+		return nil, err
+	}
+	if workDir == "" {
+		workDir = os.TempDir()
+	}
+	dir := filepath.Join(workDir, "att-"+trimExt(filepath.Base(pdfPath)))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return nil, err
+	}
+	defer os.RemoveAll(dir)
+
+	out := make([]AttachmentText, 0, len(list))
+	for _, a := range list {
+		name := safeAttachmentName(a.Name)
+		if name == "" {
+			continue
+		}
+		saved := filepath.Join(dir, fmt.Sprintf("%d-%s", a.Index, name))
+		if err := t.SaveAttachment(pdfPath, a.Index, saved); err != nil {
+			continue
+		}
+		text, err := t.attachmentMarkdown(saved, dir, lang, minChars)
+		if err != nil {
+			continue
+		}
+		out = append(out, AttachmentText{Name: a.Name, Text: text})
+	}
+	return out, nil
+}
+
+// attachmentMarkdown extracts a saved attachment with the regular pipeline.
+// Structured attachments that docpipe does not convert (e-invoice XML,
+// CuraSoft JSON, CSV/HTML) fall back to their text content, so the embedded
+// original is still searchable. Other unreadable formats return an error and
+// the caller skips them.
+func (t Tools) attachmentMarkdown(path, workDir, lang string, minChars int) (string, error) {
+	if res, err := t.ToMarkdown(path, workDir, lang, minChars); err == nil {
+		return res.Markdown, nil
+	}
+	switch Ext(path) {
+	case ".xml", ".html", ".htm":
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return "", err
+		}
+		return xmlToText(raw), nil
+	case ".json", ".csv":
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return "", err
+		}
+		return string(raw), nil
+	default:
+		return "", fmt.Errorf("unsupported attachment type %q", Ext(path))
+	}
+}
+
+// xmlToText returns the character data of an XML/HTML document: element text
+// values with decoded entities, one per line. Used for invoice XML (EN 16931
+// CII / ZUGFeRD) and HTML attachments. Pure, so it is unit-tested.
+func xmlToText(raw []byte) string {
+	dec := xml.NewDecoder(bytes.NewReader(raw))
+	dec.Strict = false
+	var b strings.Builder
+	for {
+		tok, err := dec.Token()
+		if err != nil {
+			break
+		}
+		cd, ok := tok.(xml.CharData)
+		if !ok {
+			continue
+		}
+		s := strings.TrimSpace(string(cd))
+		if s == "" {
+			continue
+		}
+		b.WriteString(s)
+		b.WriteByte('\n')
+	}
+	return b.String()
+}

internal/docpipe/pdfattach_test.go

@@ -0,0 +1,163 @@
+package docpipe
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParseAttachmentList(t *testing.T) {
+	out := "2 embedded files\n1: original.pdf\n2: scan_001.png\n"
+	got := parseAttachmentList(out)
+	want := []PDFAttachment{{Index: 1, Name: "original.pdf"}, {Index: 2, Name: "scan_001.png"}}
+	if len(got) != len(want) {
+		t.Fatalf("got %+v, want %+v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("att[%d] = %+v, want %+v", i, got[i], want[i])
+		}
+	}
+}
+
+func TestParseAttachmentListEmptyAndMalformed(t *testing.T) {
+	for _, in := range []string{"", "0 embedded files\n", "garbage\n\n  \n"} {
+		if got := parseAttachmentList(in); len(got) != 0 {
+			t.Errorf("parseAttachmentList(%q) = %+v, want empty", in, got)
+		}
+	}
+}
+
+func TestSafeAttachmentName(t *testing.T) {
+	cases := map[string]string{
+		"note.txt":            "note.txt",
+		"../../evil.pdf":      "evil.pdf",
+		`..\..\evil.pdf`:      "evil.pdf",
+		"/abs/scan_001.pdf":   "scan_001.pdf",
+		".hidden":             "hidden",
+		"  spaced name.txt  ": "spaced name.txt",
+		"..":                  "",
+		"":                    "",
+	}
+	for in, want := range cases {
+		if got := safeAttachmentName(in); got != want {
+			t.Errorf("safeAttachmentName(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestJoinWithAttachments(t *testing.T) {
+	body := "# scan.pdf\n\nbody token\n"
+	atts := []AttachmentText{
+		{Name: "original.pdf", Text: "  original token  "},
+		{Name: "empty.txt", Text: "   "},
+	}
+	got := JoinWithAttachments(body, atts)
+	if !strings.Contains(got, "body token") {
+		t.Errorf("body text lost: %q", got)
+	}
+	if !strings.Contains(got, "[attachment: original.pdf]") {
+		t.Errorf("marker missing: %q", got)
+	}
+	if !strings.Contains(got, "original token") {
+		t.Errorf("attachment text missing: %q", got)
+	}
+	if strings.Contains(got, "empty.txt") {
+		t.Errorf("empty attachment must be skipped: %q", got)
+	}
+}
+
+func TestJoinWithAttachmentsNoAttachments(t *testing.T) {
+	got := JoinWithAttachments("# a.pdf\n\ntext\n\n", nil)
+	if got != "# a.pdf\n\ntext" {
+		t.Errorf("got %q, want trimmed body only", got)
+	}
+}
+
+func TestListAttachmentsWithoutTool(t *testing.T) {
+	if _, err := (Tools{}).ListAttachments("x.pdf"); err == nil || !strings.Contains(err.Error(), "pdfdetach") {
+		t.Fatalf("want pdfdetach error, got %v", err)
+	}
+}
+
+// TestToMarkdownWithAttachmentsFixture exercises the real pdfdetach + pdftotext
+// pipeline on testdata/pdf-with-attachment.pdf (body token + embedded
+// goo-note.txt). Skips when poppler is not installed.
+func TestToMarkdownWithAttachmentsFixture(t *testing.T) {
+	tools := LookPath()
+	if tools.PDFDetach == "" || tools.PDFToText == "" {
+		t.Skip("pdfdetach/pdftotext not on PATH — skipping attachment extraction test")
+	}
+	fixture := filepath.Join("..", "..", "testdata", "pdf-with-attachment.pdf")
+	got, err := tools.ToMarkdownWithAttachments(fixture, t.TempDir(), "eng", 1)
+	if err != nil {
+		t.Fatalf("ToMarkdownWithAttachments: %v", err)
+	}
+	for _, want := range []string{"goobodytoken", "[attachment: goo-note.txt]", "gooattachmenttoken"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("result missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestXMLToText(t *testing.T) {
+	raw := []byte(`<?xml version="1.0" encoding="UTF-8"?>
+<rsm:CrossIndustryInvoice><rsm:ExchangedDocument>
+<ram:ID>S1063</ram:ID></rsm:ExchangedDocument>
+<ram:Name>Edelweiss &amp; Co</ram:Name><ram:GrandTotalAmount>42.00</ram:GrandTotalAmount>
+</rsm:CrossIndustryInvoice>`)
+	got := xmlToText(raw)
+	for _, want := range []string{"S1063", "Edelweiss & Co", "42.00"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("xmlToText missing %q:\n%s", want, got)
+		}
+	}
+	if strings.ContainsAny(got, "<>") {
+		t.Errorf("xmlToText left markup: %q", got)
+	}
+}
+
+// TestAttachmentMarkdownFallback verifies structured attachments that docpipe
+// cannot convert are still reduced to searchable text, and unknown binary
+// formats error (so the caller skips them).
+func TestAttachmentMarkdownFallback(t *testing.T) {
+	dir := t.TempDir()
+	xmlPath := filepath.Join(dir, "factur-x.xml")
+	if err := os.WriteFile(xmlPath, []byte(`<Invoice><Number>S1063</Number></Invoice>`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := (Tools{}).attachmentMarkdown(xmlPath, dir, "", 0)
+	if err != nil {
+		t.Fatalf("attachmentMarkdown(xml): %v", err)
+	}
+	if !strings.Contains(got, "S1063") {
+		t.Errorf("xml attachment text = %q, want S1063", got)
+	}
+
+	binPath := filepath.Join(dir, "data.bin")
+	if err := os.WriteFile(binPath, []byte{0, 1, 2, 3}, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := (Tools{}).attachmentMarkdown(binPath, dir, "", 0); err == nil {
+		t.Error("unsupported attachment: want error, got nil")
+	}
+}
+
+// TestToMarkdownWithAttachmentsPlainPDF ensures a PDF without attachments
+// returns just the body (pdfdetach prints "0 embedded files").
+func TestToMarkdownWithAttachmentsPlainPDF(t *testing.T) {
+	tools := LookPath()
+	if tools.PDFDetach == "" || tools.PDFToText == "" {
+		t.Skip("pdfdetach/pdftotext not on PATH")
+	}
+	// The fixture itself is a PDF with one attachment; strip it by extracting
+	// the body only through ToMarkdown and compare JoinWithAttachments(nil).
+	res, err := tools.ToMarkdown(filepath.Join("..", "..", "testdata", "pdf-with-attachment.pdf"), t.TempDir(), "eng", 1)
+	if err != nil {
+		t.Fatalf("ToMarkdown: %v", err)
+	}
+	if strings.Contains(res.Markdown, "gooattachmenttoken") {
+		t.Fatalf("body must not contain attachment text: %q", res.Markdown)
+	}
+}

storage_fallback.go

@@ -157,6 +157,13 @@ func (c *Client) downloadFileEntry(ctx context.Context, f *FileEntry, dst io.Wri
 
 // downloadFromMinio streams objectKey from the configured MinIO bucket.
 func (c *Client) downloadFromMinio(ctx context.Context, objectKey string, dst io.Writer) (int64, error) {
+	return downloadMinioObject(ctx, c.client, objectKey, dst)
+}
+
+// downloadMinioObject streams objectKey from the configured MinIO bucket using
+// hc. It is the shared implementation behind (*Client).downloadFromMinio and
+// the read-only SQL store (file_pg.go), which has no *Client.
+func downloadMinioObject(ctx context.Context, hc *http.Client, objectKey string, dst io.Writer) (int64, error) {
 	if objectKey == "" {
 		return 0, fmt.Errorf("onlyoffice: minio fallback: empty object key")
 	}
@@ -177,7 +184,7 @@ func (c *Client) downloadFromMinio(ctx context.Context, objectKey string, dst io
 	if err := signMinioRequest(ctx, cfg, req); err != nil {
 		return 0, err
 	}
-	resp, err := c.client.Do(req)
+	resp, err := hc.Do(req)
 	if err != nil {
 		return 0, fmt.Errorf("onlyoffice: minio fallback: %w", err)
 	}

testdata/pdf-with-attachment.pdf

@@ -0,0 +1,114 @@
+%PDF-1.7
+%Çì�¢
+%%Invocation: gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite ? ? ?
+5 0 obj
+<</Length 6 0 R/Filter /FlateDecode>>
+stream
+xœ-ŠA
+ƒ0÷ÿoÙnìO7q]èZ*ÿ�IˆmJ½½M
+³f7
+\¨6‘žfRÿŠ*ñºõª…8:g}‡f†Dºø”ÞiØsúØ	ÝôÝ;炱(Ùn.ly]ìUFz
+½~Aë øendstream
+endobj
+6 0 obj
+110
+endobj
+4 0 obj
+<</Type/Page/MediaBox [0 0 612 792]
+/Rotate 0/Parent 3 0 R
+/Resources<</ProcSet[/PDF /Text]
+/Font 8 0 R
+>>
+/Contents 5 0 R
+>>
+endobj
+3 0 obj
+<< /Type /Pages /Kids [
+4 0 R
+] /Count 1
+>>
+endobj
+1 0 obj
+<</Type /Catalog /Pages 3 0 R
+/Metadata 9 0 R
+>>
+endobj
+8 0 obj
+<</R7
+7 0 R>>
+endobj
+7 0 obj
+<</BaseFont/Helvetica/Type/Font
+/Subtype/Type1>>
+endobj
+9 0 obj
+<</Type/Metadata
+/Subtype/XML/Length 1173>>stream
+<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
+<?adobe-xap-filters esc="CRLF"?>
+<x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='XMP toolkit 2.9.1-13, framework 1.6'>
+<rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'>
+<rdf:Description rdf:about="" xmlns:pdf='http://ns.adobe.com/pdf/1.3/' pdf:Producer='GPL Ghostscript 10.02.1'/>
+<rdf:Description rdf:about="" xmlns:xmp='http://ns.adobe.com/xap/1.0/'><xmp:ModifyDate>2026-09-16T17:29:12Z</xmp:ModifyDate>
+<xmp:CreateDate>2026-09-16T17:29:12Z</xmp:CreateDate>
+<xmp:CreatorTool>UnknownApplication</xmp:CreatorTool></rdf:Description>
+<rdf:Description rdf:about="" xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/' xapMM:DocumentID='uuid:ae8d7575-ea10-11fc-0000-3a98742e0b71'/>
+<rdf:Description rdf:about="" xmlns:dc='http://purl.org/dc/elements/1.1/' dc:format='application/pdf'><dc:title><rdf:Alt><rdf:li xml:lang='x-default'>Untitled</rdf:li></rdf:Alt></dc:title></rdf:Description>
+</rdf:RDF>
+</x:xmpmeta>
+                                                                        
+                                                                        
+<?xpacket end='w'?>
+endstream
+endobj
+2 0 obj
+<</Producer(GPL Ghostscript 10.02.1)
+/CreationDate(D:20260916172912Z00'00')
+/ModDate(D:20260916172912Z00'00')>>endobj
+xref
+0 10
+0000000000 65535 f 
+0000000476 00000 n 
+0000001882 00000 n 
+0000000417 00000 n 
+0000000276 00000 n 
+0000000077 00000 n 
+0000000257 00000 n 
+0000000569 00000 n 
+0000000540 00000 n 
+0000000633 00000 n 
+trailer
+<< /Size 10 /Root 1 0 R /Info 2 0 R
+/ID [<5A562476FBF11852133AA873452909F9><5A562476FBF11852133AA873452909F9>]
+>>
+startxref
+2008
+%%EOF
+1 0 obj
+<</Type /Catalog /Pages 3 0 R /Metadata 9 0 R /Names <</EmbeddedFiles 12 0 R >> >> 
+endobj
+10 0 obj
+<</Length 44 /Params <</Size 44 >> >> stream
+gooattachmenttoken embedded attachment text
+
+endstream
+
+endobj
+11 0 obj
+<</Type /Filespec /UF <feff0067006f006f002d006e006f00740065002e007400780074> /EF <</F 10 0 R >> >> 
+endobj
+12 0 obj
+<</Names [<feff0067006f006f002d006e006f00740065002e007400780074> 11 0 R ] >> 
+endobj
+xref
+0 2
+0000000002 65535 f
+0000002361 00000 n
+10 3
+0000002463 00000 n
+0000002586 00000 n
+0000002705 00000 n
+trailer
+<</Size 13 /ID [(ZV$vûñR:¨sE\)	ù) (P…õrˆ‚ Åð¡Ï) ] /Root 1 0 R /Prev 2008 /Info 2 0 R >> 
+startxref
+2802