Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

files.go

@@ -9,11 +9,15 @@ import (
 	"strings"
 )
 
-// Sentinel errors for Visit / Working Folder resolution.
 var (
-	ErrNotExist  = errors.New("not found")
+	// ErrNotExist means the folder or file is missing.
+	// Callers should use IsNotExist rather than comparing text.
+	ErrNotExist = errors.New("not found")
+	// ErrForbidden means the caller may not read or write the path.
+	// Callers should use IsForbidden rather than comparing text.
 	ErrForbidden = errors.New("forbidden")
-	ErrNotDir    = errors.New("not a directory")
+	// ErrNotDir means the path exists and is not a directory.
+	ErrNotDir = errors.New("not a directory")
 )
 
 // Entry is a first-level name in a Working Folder.
@@ -50,6 +54,8 @@ type Local struct {
 }
 
 // OpenFolder opens an existing directory under the local root.
+// It returns an error wrapping ErrNotExist, ErrForbidden, or ErrNotDir,
+// or a plain error when rel is not a valid User Files Root–relative path.
 func (l Local) OpenFolder(rel string) (Folder, error) {
 	dir, err := l.resolve(rel)
 	if err != nil {
@@ -71,7 +77,9 @@ func (l Local) OpenFolder(rel string) (Folder, error) {
 	return localFolder{dir: dir}, nil
 }
 
-// EnsureFolder creates the directory if missing, then opens it.
+// EnsureFolder creates the directory and its parents if missing, then opens it.
+// It returns an error wrapping ErrForbidden when the process cannot create
+// the directory, or a plain error when rel is not valid.
 func (l Local) EnsureFolder(rel string) (Folder, error) {
 	dir, err := l.resolve(rel)
 	if err != nil {
@@ -94,8 +102,10 @@ func (l Local) resolve(rel string) (string, error) {
 	return filepath.Join(l.RootDir, filepath.FromSlash(clean)), nil
 }
 
-// CleanRel normalizes a User Files Root–relative path; empty means invalid.
-// Absolute URLs and numeric file IDs are rejected.
+// CleanRel normalizes a User Files Root–relative path.
+// The result is empty when rel is empty, contains "..", is a URL, or is a
+// bare numeric Nextcloud file ID. An empty result is not a usable path.
+// Backslashes are treated as slashes. A leading or trailing slash is removed.
 func CleanRel(rel string) string {
 	rel = strings.TrimSpace(rel)
 	rel = strings.ReplaceAll(rel, "\\", "/")