Add comprehensive documentation and examples for STFilePath functionality

- Introduced new markdown files covering various aspects of STFilePath, including:
  - Core paths and sandbox usage
  - DownloadableFile async fetch/save pipeline
  - File and folder I/O operations
  - Function cookbook for practical coding examples
  - Hashing utilities using CryptoKit
  - iOS/macOS integrations for file handling
  - JSON Lines support for line-oriented file access
  - Metadata, permissions, extended attributes, and symlink handling
  - MMAP and Darwin-specific file operations
  - Search and backup functionalities
  - Watchers for file/folder/path event monitoring

- Added a test support file for handling watcher events in unit tests.

Author: linhay

.agent/skills/stfilepath/README_SKILL.md

@@ -1,38 +1,50 @@
 ---
 name: stfilepath
-description: "Developer-facing skill for working with the STFilePath Swift library. Use when you need to read, modify, build, test, or produce examples for STFilePath (repository contains Swift package, macOS/iOS support, file-watching, hashing, and DownloadableFile utilities)."
+description: "Developer-facing skill for working with the STFilePath Swift library. Use when you need to read, modify, build, test, or generate examples for any STFilePath feature (paths/files/folders, sandbox & containers, watchers, hashing, metadata/permissions/xattrs, mmap/Darwin, search/backup, JSON lines, compression, DownloadableFile, caches/UserDefaults, iOS/macOS integrations)."
 ---
 
 
 # STFilePath Skill
 
-Concise developer-facing guidance and quick references for working with the STFilePath Swift package. Use this skill when you need to read, modify, explain, test, or produce examples that use STFilePath features (file operations, hashing, folder watching, DownloadableFile patterns).
+Developer-facing guidance for working with the STFilePath Swift package. Use this skill when you need to read, modify, explain, test, or produce examples across the full surface area of the library.
 
 Trigger signals (when to use this skill)
 - User asks about STFilePath internals or how to implement/patch features in Sources/STFilePath
-- User asks for example code, README snippets, or sample apps using STFilePath APIs
+- User asks for example code, README snippets, scripts, or sample apps using STFilePath APIs
 - User requests CI/build/test guidance, or to add unit tests to Tests/STFilePathTests
+- User asks about any of: sandbox/container URLs, iOS document picker, macOS Finder integration, mmap, permissions/xattrs, JSON lines, caching, compression
 
 Quick start
 - Build locally: `swift build`
 - Run tests: `swift test`
 - CI workflow: see `.github/workflows/swift.yml` for an example using macOS and swift build/test
-- Example snippet for README: use `scripts/example_usage.swift` as canonical sample code
-
-What this skill provides
-- Quick start snippets for the most common tasks (create/read/write/move/delete, hashing, folder watcher)
-- Pointer files mapping core sources and where to add or change code (references/FILES.md)
-- Example code for basic and advanced patterns (references/EXAMPLES.md and scripts/example_usage.swift)
-- Short API quick reference to locate types and commonly-used methods (references/API_REFERENCE.md)
-- Troubleshooting guide for common runtime issues (references/TROUBLESHOOTING.md)
-- CI, packaging, and release notes (references/CI_AND_PACKAGING.md)
-- Test suggestions and where to add them (references/TESTS.md)
+- Example snippets: see `references/EXAMPLES.md` (API-accurate snippets) and `scripts/` (longer, script-like examples)
+
+Capability map (open the referenced file for details)
+- “函数教程/直接写代码”：`references/FUNCTION_COOKBOOK.md`
+- Core types & path model: `references/API_REFERENCE.md`
+- File/folder operations & streaming: `references/FILE_IO.md`
+- Sandbox & containers (document/library/cache/app group/iCloud): `references/CORE_PATHS_AND_SANDBOX.md`
+- Watchers (file/folder/path, backends): `references/WATCHERS.md`
+- Hashing (CryptoKit): `references/HASHING.md`
+- Metadata/permissions/xattrs/symlinks/security-scoped: `references/METADATA_PERMISSIONS_XATTR_LINKS.md`
+- MMAP & Darwin low-level APIs: `references/MMAP_AND_DARWIN.md`
+- Search & backup: `references/SEARCH_AND_BACKUP.md`
+- JSON Lines: `references/JSON_LINES.md`
+- Compression: `references/COMPRESSION.md`
+- DownloadableFile (DFAnyFile/DFFileMap/DFCurrentValueFile): `references/DOWNLOADABLEFILE.md`
+- Caching & UserDefaults helpers: `references/CACHING_AND_USERDEFAULTS.md`
+- Platform integrations (iOS/macOS): `references/INTEGRATIONS_IOS_MACOS.md`
+- Repo map (where to change code/tests): `references/FILES.md`
+- Tests guidance (existing tests + adding new): `references/TESTS.md`
+- Troubleshooting: `references/TROUBLESHOOTING.md`
+- Skill packaging notes: `references/CI_AND_PACKAGING.md`
 
 Progressive disclosure (what to open when)
-- Look at references/FILES.md first to locate the implementation file you need to change.
-- Open references/API_REFERENCE.md when you need method signatures and short usage snippets.
-- Open references/EXAMPLES.md for copy-pasteable examples (basic + advanced).
-- Open references/TROUBLESHOOTING.md when encountering runtime issues (watcher permissions, file locks, path errors).
+- If you’re changing behavior: open `references/FILES.md` first to locate the implementation + existing tests.
+- If you’re writing usage/docs: open `references/EXAMPLES.md` first; then jump to the matching deep-dive reference file.
+- If you’re debugging runtime issues: open `references/TROUBLESHOOTING.md`.
+- If you need a quick symbol search: use `rg` with keywords listed at the top of each reference file.
 
 Minimal expectations and conventions
 - This repo is a Swift Package (Package.swift present) and targets macOS/iOS.
@@ -44,7 +56,7 @@ Safety and change guidance
 - For platform-specific behavior (macOS vs iOS), include platform guards and run tests on macOS CI.
 
 Packaging the skill
-- To package this skill as a distributable .skill, bundle the skills/stfilepath directory. Tell me if you want me to produce that .skill archive.
+- To package this skill as a distributable `.skill`, zip the `.agent/skills/stfilepath` directory (see `references/CI_AND_PACKAGING.md`).
 
 Contacts and maintenance
 - When renaming or moving files, update references/FILES.md.

.agent/skills/stfilepath/SKILL.md

@@ -1,47 +1,86 @@
-STFilePath - API Quick Reference (short)
-
-STFile (file-level operations)
-- create(with: Data) -> create file with contents
-- read() -> Data
-- append(data: Data)
-- delete()
-- move(to: STFile)
-- hash(with: HashAlgorithm) -> String
-- watcher() -> STFileWatcher
-
-STFolder (folder-level operations)
-- folder(name: String) -> STFolder (path builder)
-- file(name: String) -> STFile (path builder)
-- create() -> create folder
-- delete()
-- watcher(options:) -> STFolderWatcher
-
-STPath / STPathProtocol
-- path string properties, checks for isExists, isFolderExists, isFileExists
-- watcher() -> STPathWatcher (generic)
-- openingProcesses() -> [STProcessInfo] (macOS only)
-
-STProcessInfo
-- pid: Int32
-- name: String
-- command: String
-
-Watcher Classes (STFileWatcher, STFolderWatcher, STPathWatcher)
-- streamMonitoring() / stream() -> AsyncThrowingStream of events
-- stopMonitoring() / stop() -> terminates the stream
-
-DownloadableFile / DFAnyFile
-- .codable(Type.self) to transform to Codable handling
-- fetch() async -> Type
-- save(_:) async to persist transformed content
-
-Where to find implementations
-- Sources/STFilePath/STFile.swift
-- Sources/STFilePath/STFolder+Folder.swift
-- Sources/STFilePath/STFolderWatcher.swift
-- Sources/STFilePath/STFileWatcher.swift
-- Sources/STFilePath/STPathWatcher.swift
-- Sources/STFilePath/STPathProtocol.swift
-- Sources/STFilePath/DownloadableFile/*
-
-Note: This reference is intentionally concise. For method signatures and exact parameter types, open the source files listed above.
+STFilePath - API Quick Reference (accurate, terse)
+
+If you need deeper coverage by area, open the matching reference file:
+- File/folder IO: `references/FILE_IO.md`
+- Sandbox/containers: `references/CORE_PATHS_AND_SANDBOX.md`
+- Watchers: `references/WATCHERS.md`
+- Hashing: `references/HASHING.md`
+- Metadata/permissions/xattrs/symlinks: `references/METADATA_PERMISSIONS_XATTR_LINKS.md`
+- MMAP & Darwin: `references/MMAP_AND_DARWIN.md`
+- DownloadableFile: `references/DOWNLOADABLEFILE.md`
+- Search/backup: `references/SEARCH_AND_BACKUP.md`
+- JSON Lines: `references/JSON_LINES.md`
+- Integrations: `references/INTEGRATIONS_IOS_MACOS.md`
+
+Use cases
+1) 我想“直接写代码”而不是翻源码：先看 `references/FUNCTION_COOKBOOK.md`
+2) 我想快速复制粘贴：看 `references/EXAMPLES.md`
+3) 我想改库实现/补测试：先看 `references/FILES.md`（定位实现与测试文件）
+
+Search hints
+- Core protocol: `rg -n "protocol STPathProtocol" Sources/STFilePath`
+- Core types: `rg -n "struct STPath|struct STFile|struct STFolder" Sources/STFilePath`
+- Watchers: `rg -n "Watcher|ST(Folder|File|Path)Watcher|WatcherBackend" Sources/STFilePath`
+- DownloadableFile: `rg -n "protocol DownloadableFile|DFAnyFile|DFFileMap|DFCurrentValueFile" Sources/STFilePath`
+
+Core types
+- `STPathProtocol`: shared URL-based API for paths (exists/type/relativePath, attributes, permission, etc.). Implementation: `Sources/STFilePath/STPathProtocol.swift`
+- `STPath`: type-erased path (file/folder/notExist), can expose `referenceType` as `STFilePathReferenceType`. Implementation: `Sources/STFilePath/STPath.swift`
+- `STFile`: file path + file ops. Implementation: `Sources/STFilePath/STFile.swift`
+- `STFolder`: folder path + folder ops. Implementation: `Sources/STFilePath/STFolder+Folder.swift`
+
+Path classification & reference
+- `STFilePathItemType`: `.file/.folder/.notExist`. Implementation: `Sources/STFilePath/STFilePathItemType.swift`
+- `STFilePathReferenceType`: `.file(STFile)` / `.folder(STFolder)`. Implementation: `Sources/STFilePath/STFilePathReferenceType.swift`
+
+Watchers (AsyncThrowingStream-based)
+- `STFileWatcher(file: STFile).stream() -> AsyncThrowingStream<STPathChanged, Error>` and `.stop()`. Implementation: `Sources/STFilePath/STFileWatcher.swift`
+- `STFolderWatcher(folder: STFolder, options:).streamMonitoring() -> AsyncThrowingStream<STFolderWatcher.Changed, Error>` and `.stopMonitoring()`. Implementation: `Sources/STFilePath/STFolderWatcher.swift`
+- `STPathWatcher(path: STPath).stream() -> AsyncThrowingStream<STPathChanged, Error>` and `.stop()`. Implementation: `Sources/STFilePath/STPathWatcher.swift`
+- Backends:
+  - macOS folder/path: FSEvents (`Sources/STFilePath/macos/FSEventsWatcher.swift`)
+  - file + non-macOS: DispatchSource (`Sources/STFilePath/DispatchSourceWatcher.swift`)
+  - common event model: `Sources/STFilePath/WatcherBackend.swift` (`STPathChanged`, `STPathChangeKind`)
+
+Hashing (CryptoKit)
+- `STHasherKind`: `.sha256/.sha384/.sha512/.md5` (md5 uses `Insecure.MD5`). Implementation: `Sources/STFilePath/STFile+CryptoKit.swift`
+- `STFile.hash(with kind: STHasherKind) -> String` (hex digest). Implementation: `Sources/STFilePath/STFile+CryptoKit.swift`
+
+Metadata / permissions / xattrs / symlinks
+- Attributes wrapper: `STPathAttributes` via `STPathProtocol.attributes`. Implementation: `Sources/STFilePath/STPathAttributes.swift`
+- Convenience permissions:
+  - `STPathProtocol.permission -> STPathPermission` (exists/readable/writable/executable/deletable). Implementation: `Sources/STFilePath/STPathProtocol.swift`, `Sources/STFilePath/STPathPermission.swift`
+  - POSIX permissions helpers: `STPathProtocol.permissions()` / `set(permissions:)` and `STPathPermission.Posix`. Implementation: `Sources/STFilePath/STPath+Metadata.swift`, `Sources/STFilePath/STPathPermission.swift`
+- Extended attributes (Darwin only): `STPathProtocol.extendedAttributes` with `set/value/remove/list`. Implementation: `Sources/STFilePath/STPath+Metadata.swift`
+- Symlink helpers: `isSymbolicLink`, `createSymbolicLink(to:)`, `destinationOfSymbolicLink()`. Implementation: `Sources/STFilePath/STPath+Link.swift`
+- Security-scoped resource helpers (Apple platforms): `startAccessingSecurityScopedResource()` / `stopAccessingSecurityScopedResource()`. Implementation: `Sources/STFilePath/STPathProtocol.swift`
+
+Search & enumeration
+- `STFolder.files(...) / folders(...) / subFilePaths(...) / allSubFilePaths(...)`. Implementation: `Sources/STFilePath/STFolder+Search.swift`
+- `STFolder.SearchPredicate` and custom filters. Implementation: `Sources/STFilePath/STFolder+Search.swift`
+- Recursive file scanning with filters: `STFolder.files(matching:in:)`. Implementation: `Sources/STFilePath/STFolder+Search.swift`
+
+Backup
+- `STFolder.backup(options:) -> STFolderBackup`, `connect()`, `monitoring() async`, `stopMonitoring()`. Implementation: `Sources/STFilePath/STFolderBackup.swift`
+
+JSON Lines
+- `STFile.lineFile -> STLineFile`, `STLineFile.lines()` / `lines(as:)`, `STLineFile.NewLineWriter.append(...)`. Implementation: `Sources/STFilePath/STJSONLines.swift`
+
+DownloadableFile
+- `DownloadableFile` protocol: `fetch()` / `save(_:) async`. Implementation: `Sources/STFilePath/DownloadableFile/DownloadableFile.swift`
+- `DFAnyFile<Model>` type erasure and `DFAnyFile(file: STFile)` when `Model == Data`. Implementation: `Sources/STFilePath/DownloadableFile/DFAnyFile.swift`
+- `DFFileMap<File, To>` mapping via `map(fetch:save:)` and helpers like `.codable(...)`, `.compression(...)`. Implementation: `Sources/STFilePath/DownloadableFile/DFFileMap.swift`, `Sources/STFilePath/DownloadableFile/DownloadableFile.swift`
+- `DFCurrentValueFile`: debounced-ish “last write wins” wrapper that saves on `value` set. Implementation: `Sources/STFilePath/DownloadableFile/DFAnyFile.swift`
+- Convenience: `STFile.toDFAnyFile() -> DFAnyFile<Data>`. Implementation: `Sources/STFilePath/DownloadableFile/DFAnyFile.swift`
+
+Compression (if `Compression` module available)
+- `STComparator.compress/decompress(_:algorithm:)`. Implementation: `Sources/STFilePath/Compression/STComparator.swift`
+- `DownloadableFile.compression(_:)` for `Model == Data`. Implementation: `Sources/STFilePath/DownloadableFile/DownloadableFile.swift`
+
+MMAP & Darwin file APIs (Darwin only)
+- `STFile.withMmap(...) { STFileMMAP in ... }`, `STFile.setSize(_:)`. Implementation: `Sources/STFilePath/STFile+MMAP.swift`
+- `STFile.system -> STFileSystem` (`open/stat/truncate/sync/...`). Implementation: `Sources/STFilePath/STFile+Darwin.swift`
+
+Integrations
+- iOS: `STDocumentPicker` (UIDocumentPicker) and `STPathQuickLookController` (QuickLook). Implementation: `Sources/STFilePath/ios/*`
+- macOS: Finder helpers (`showInFinder`, `selectInFinder`) and associated apps (`associatedApplications`, `open(with:)`). Implementation: `Sources/STFilePath/macos/*`

.agent/skills/stfilepath/SKILL_zh-CN.md

@@ -0,0 +1,95 @@
+Caching (STKVCache) and UserDefaults helpers (STUserDefaults)
+
+Search hints
+- Cache: `rg -n "final class STKVCache" Sources/STFilePath/Surroundings/STKVCache.swift`
+- UserDefaults wrapper: `rg -n "propertyWrapper\\s+public struct STUserDefaults" Sources/STFilePath/Surroundings/STUserDefaults.swift`
+
+Use cases
+1) 解析结果缓存（避免重复 JSON decode）
+```swift
+import Foundation
+import STFilePath
+
+let cache = STKVCache<String, Any>()
+// 业务建议：定义明确的 Value 类型（这里仅展示用法）
+```
+
+2) Codable cache 落盘（重启恢复）
+```swift
+import Foundation
+import STFilePath
+
+let file = STFile("/tmp/cache.json")
+try file.createIfNotExists(with: Data("[]".utf8))
+
+let cache = STKVCache<String, Int>()
+cache["a"] = 1
+try cache.saveToDisk(with: file)
+
+let restored = try STKVCache<String, Int>.decode(from: file)
+_ = restored["a"]
+```
+
+3) 用户偏好（UserDefaults property wrapper）
+```swift
+import STFilePath
+
+struct Settings {
+    @STUserDefaults("enabled", default: false) var enabled: Bool
+    @STUserDefaults("recentIDs", default: []) var recentIDs: [Int]
+}
+```
+
+STKVCache
+- In-memory cache built on `NSCache` with optional expiration.
+- Codable support when `Key` and `Value` are Codable:
+  - Can encode/decode the cache contents.
+  - Can persist to disk using `saveToDisk(with:)` / `decode(from:)` with an `STFile`.
+
+Example (basic)
+
+```swift
+import STFilePath
+
+let cache = STKVCache<String, Int>()
+cache.insert(1, forKey: "a", lifeTime: 60)
+let v = cache.value(of: "a")
+```
+
+Example (persist to disk)
+
+```swift
+import Foundation
+import STFilePath
+
+let file = STFile("/tmp/cache.json")
+try file.createIfNotExists(with: Data("[]".utf8))
+
+let cache = STKVCache<String, Int>()
+cache["a"] = 1
+try cache.saveToDisk(with: file)
+
+let restored = try STKVCache<String, Int>.decode(from: file)
+```
+
+STUserDefaults
+- `@STUserDefaults(key, default: ...)` property wrapper with typed values.
+- Supported out of the box:
+  - `String`, `Int`, `Bool`, `Float`, `Double`, `URL`, `UUID`, `Data`
+  - `Optional<Wrapped>` where `Wrapped: STUserDefaultsValue`
+  - `Array<Element>` where `Element: Codable` (stored as binary plist)
+
+Example
+
+```swift
+import STFilePath
+
+struct Settings {
+    @STUserDefaults("enabled", default: false) var enabled: Bool
+    @STUserDefaults("recentIDs", default: []) var recentIDs: [Int]
+}
+```
+
+Where to change behavior
+- Cache: `Sources/STFilePath/Surroundings/STKVCache.swift`
+- UserDefaults wrapper: `Sources/STFilePath/Surroundings/STUserDefaults.swift`

.agent/skills/stfilepath/references/API_REFERENCE.md

@@ -1,15 +1,32 @@
 CI, build, and packaging notes
 
+Use cases
+1) 本地验证（构建 + 测试）
+```bash
+swift build
+swift test
+```
+
+2) 只跑 watcher 相关测试（定位 flake/hang）
+```bash
+swift test --filter STFilePathTests.STFolderWatcherTests --filter STFilePathTests.STWatcherTests
+```
+
+3) 打包 skill（生成 `stfilepath.skill`）
+```bash
+zip -r stfilepath.skill .agent/skills/stfilepath
+```
+
 Build & Test
 - Local: `swift build` and `swift test`
 - CI: .github/workflows/swift.yml currently runs `swift build` and `swift test --enable-code-coverage` on macos-latest with Swift 6.0 in the matrix
 
 Packaging the skill
-- To distribute this skill as a .skill archive, create a zip of the skills/stfilepath directory and rename to `stfilepath.skill`.
+- To distribute this skill as a `.skill` archive, create a zip of the `.agent/skills/stfilepath` directory and rename to `stfilepath.skill`.
 - Ensure SKILL.md frontmatter is present and valid (name + description). The packaging can be automated with a small script:
 
 ```bash
-zip -r stfilepath.skill skills/stfilepath
+zip -r stfilepath.skill .agent/skills/stfilepath
 ```
 
 Publishing