@openclaw/feishu 2026.9.8 → 2026.10.1-beta.2

package/node_modules/@openclaw/fs-safe/docs/native-helper.md

@@ -29,25 +29,15 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `off` | Do not load a native package. Use supported fallbacks and reject native-only operations deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
-Plain TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use a bundled,
-import-free WASM build of the same Rust TAR parser when native support is absent
-or disabled. Zstd/bzip2 codecs are bundled alongside the parser; gzip uses Node's
-built-in decoder. These archive fallbacks require no runtime interpreter or
-download. `off` disables the optional native filesystem helper, not the bundled
-WASM. `auto` prefers native and does not retry a native operation failure through
-WASM; `require` still rejects an unavailable native binding. ZIP fallback still
-requires optional `jszip`. `inspectTarArchive()` remains limited to plain TAR
-and gzip.
-
-Windows security operations can use the package's readable PowerShell/C# scripts
-in `auto` and `off`, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
-
-On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
-same Rust addon for system canonicalization in `auto` and `require`. No JIT is
-needed. With `off` or a missing addon in `auto`, Bun's own resolver retains its
-path and permission limitations. Canonicalization in `require` fails with
-`helper-unavailable` if the addon or its canonicalizer is missing, including
-when admitting a temp workspace. Containment and identity checks stay intact.
+See [Archive extraction](archive.md) for native, bundled WASM, and ZIP backends.
+Native archive-operation failures are terminal; `auto` does not retry them through a
+fallback. `require` rejects missing bindings or required capabilities.
+
+Windows owner/DACL inspection, private-directory creation, and secure reads can
+use [PowerShell fallbacks](install.md#windows-security-fallback) in `auto` and
+`off`; `require` stays strict, and native operation failures remain terminal.
+Bun macOS/Linux canonicalization uses the addon under its
+[runtime requirements](install.md#bun-runtime).
 
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
@@ -64,22 +54,12 @@ with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
 open until process exit. The native close operation handles explicit cleanup,
 not forced worker termination.
 
-[`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
-remain available in every mode. Their default compatible cleanup uses guarded
-JavaScript quarantine when owned native tree removal is unavailable.
-`cleanupSafety: "require-bounded"` instead rejects before child creation unless
-no-replace quarantine plus descriptor-relative owned-tree removal are available.
-On Linux, admission probes the exact `openat2` child-directory flags, including
-`RESOLVE_NO_XDEV`, at runtime. An unavailable or denied probe selects compatible
-JavaScript cleanup even in global `require` mode; `require-bounded` rejects before
-child creation.
-Already-created strict workspaces retain their binding
-and descriptors across later mode changes.
-
-[`stageFileInDirectory()`](staged-file.md) always requires native support on
-Linux/macOS and rejects before creation when off, unavailable, or missing the
-required capability. Windows is unsupported for this lifecycle. This does not
-change the mode policy of existing fallback-capable APIs.
+Temp workspaces have an independent `cleanupSafety` policy: `"compatible"`
+can use guarded JavaScript cleanup even in native `require` mode;
+`"require-bounded"` rejects before child creation without the required cleanup
+capabilities. See the [temp workspace contract](temp.md#private-temp-workspaces).
+[Retained-directory staging](staged-file.md) requires native support on Linux/macOS
+and is unsupported on Windows.
 
 ## Native boundary
 
@@ -87,15 +67,9 @@ The internal Darwin descriptor ACL inspector requires its matching native
 capability in both `auto` and `require`; `off`, a missing package, or an older
 binding without `inspectDarwinAcl` rejects with `helper-unavailable`. Inspection
 failure or malformed facts reject with `permission-unverified`; there is no
-mode-bit or pathname fallback for this capability. Clone admission uses a fused
-descriptor-bound metadata and ACL observation, then compares immutable receipts
-with fresh no-follow pathname identity fences; pathnames never authorize ACL
-state. The payload ACL-clear readback is part of that fused observation. Once
-a clone payload exists, normalization and verification failures become terminal
-`EIO` errors (with the underlying status and detail retained), not capability
-signals that permit an ordinary-copy retry. Checked cleanup cannot undo that
-terminal classification.
-This addition does not change other APIs' native-mode or permission contracts.
+mode-bit or pathname fallback for this capability. See
+[Darwin clone normalization](native.md#the-beneath-model) for descriptor-bound
+admission and terminal errors after a clone payload exists.
 
 The native layer exposes policy-free filesystem mechanisms: beneath-root
 open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
@@ -103,9 +77,9 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
-- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+Platform mechanisms and containment limits are documented in the
+[security model](security-model.md#containment-guarantees-by-platform) and
+[native architecture](native.md#the-beneath-model).
 
 Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
 
@@ -120,58 +94,23 @@ through the retained parents without another receipt, duplicate, reopen, or
 macOS `F_GETPATH`; the documented final source-name substitution window remains
 there. Deeper names retain guarded parent traversal.
 
-Native primitives back create-only and replacing pinned writes, no-clobber
-`Root.move()`, async sidecar creation, guarded publication, archive acceleration,
-and direct Windows ACL operations. Windows secure-file reads require
-descriptor-bound owner/DACL facts. In native `auto` or `off` mode, a missing
-binding or capability can use a packaged PowerShell script that inspects the
-borrowed handle. Raw owner/DACL inspection and private-directory creation also support
-this fallback, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
-Each capability emits a path-free warning once per process and adds PowerShell
-startup and compilation overhead per call. Native `require` rejects missing
-capabilities, and native operation failures remain terminal. No-clobber moves fail with
-`helper-unavailable` when descriptor-relative parent admission or the atomic
-no-replace rename is unavailable; they never use a check followed by a replacing
-rename. Equivalent JavaScript paths remain available for documented
-fallback-capable features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
-for the exact difference.
-
-The guarded JavaScript mutation path is detection-based, not containment-atomic.
-If a same-privilege peer can replace a writable parent after its identity guard
-but before Node resolves a pathname mutation, the mutation can land outside the
-intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
-`kernel-atomic` resolver; inspect containment and use OS isolation when that
-concurrent attacker is part of the threat model.
-
-`openBeneath()` returns `{ fd, containment }`. `containment` is
-`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
-Windows. Public JavaScript root open/read/writable results also expose the
-field and report `"best-effort"`; the label reports mechanism, not policy.
+No-clobber `Root.move()` fails with `helper-unavailable` if descriptor-relative
+parent admission or atomic no-replace rename is unavailable; it never substitutes
+a check followed by a replacing rename. See the
+[fallback contract](native.md#javascript-fallback-guarantees-and-delta).
 
-## Migration from the Python helper
+Guarded JavaScript mutations can have out-of-root effects before a post-check
+detects a hostile parent swap. Native `require` does not require a kernel-atomic
+resolver: inspect the operation's `containment` and use OS isolation for hostile
+concurrent actors. The [security model](security-model.md#native-root-mutation-capabilities)
+is authoritative for operation and platform guarantees.
 
-Version 0.5 removes the Python worker and interpreter-path selection. The mode
-contract is unchanged, so migrate startup configuration directly:
+## Migration from the Python helper
 
-| Python helper configuration | Native replacement |
-|---|---|
-| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
-| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
-| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
-| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
-| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
-| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
-
-In 0.5, `configureFsSafePython` and the legacy Python environment names
-remain only as an upgrade bridge. On the first config read they emit one
-`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
-native mode, and then apply that mode. A legacy interpreter path without an
-explicit mode maps to `auto` and the path itself is ignored. Native config has
-the normal precedence over legacy environment config.
-
-There is no silent alias and no Python execution fallback. The bridge exists
-only to make shipped 0.4 configuration visible and predictable while the
-consumer performs its 0.5 upgrade.
+The deprecated configuration bridge maps Python settings to native modes and
+warns once; it never executes Python. Follow the
+[0.5 migration checklist](migrating-to-0.5.md#2-replace-python-helper-configuration)
+for aliases, warning behavior, and precedence.
 
 ## Related pages
 

package/node_modules/@openclaw/fs-safe/docs/native.md

@@ -17,7 +17,7 @@ guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
 run postinstall code, or fetch binaries at runtime. Seven exact-version optional
 packages are filtered by OS, CPU, and Linux libc, so an installation receives
 only its matching prebuilt binding.
-Native-only formats fail explicitly
+Native-only operations fail explicitly
 instead of substituting a weaker implementation.
 
 ## The beneath model
@@ -235,11 +235,8 @@ not bypass the byte limit.
 
 ## Mode semantics
 
-| Mode | Native loading | Fallback |
-|---|---|---|
-| `auto` | Try once, cache the result | Use guarded JavaScript when safe; reject native-only operations |
-| `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
-| `off` | Never attempt a binding load | Use guarded JavaScript when safe; reject native-only operations |
+See [Native helper policy](native-helper.md#modes) for the `auto`, `require`, and
+`off` contracts and cached loader behavior.
 
 `sha256FileSync()` is a synchronous Node implementation in all three modes and
 does not load the binding. Use asynchronous `sha256File()` for native hashing
@@ -251,19 +248,10 @@ Features without a safe fallback, including no-clobber
 when native support is absent or off. Staging is currently Linux/macOS only and
 rejects Windows with `unsupported-platform`.
 
-Windows raw owner/DACL inspection, private-directory creation, and secure-file
-descriptor inspection can use a package-shipped, readable `.ps1` driver and
-adjacent `.cs` source in `auto` or `off` mode when their binding or capability is
-unavailable. System Windows PowerShell runs the fixed driver with `-File`;
-paths remain data, with no runtime-generated helper script or encoded launcher.
-The [Windows security fallback prerequisites](install.md#windows-security-fallback)
-apply, and unsupported or disallowed command execution fails closed. This route
-preserves raw ACL facts, private DACLs at creation, and descriptor-bound secure
-reads, and emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per capability
-per process. Each call adds PowerShell startup and compilation overhead.
-`require` rejects missing capabilities without a command, and an available native operation's
-failure never triggers this fallback. See [Permissions](permissions.md) and
-[Secure file reads](secure-file.md) for error and platform contracts.
+Windows owner/DACL inspection, private-directory creation, and secure-file
+inspection support [PowerShell fallbacks](install.md#windows-security-fallback)
+in `auto` and `off`. `require` rejects missing capabilities, and native operation
+failures are terminal.
 
 The staged-file owner also serves POSIX native pinned writes, including streaming.
 Unpublished files remain at `0600`; requested modes are applied through the
@@ -304,7 +292,12 @@ denied-path decisions remain in TypeScript.
 Public policy does not change with the selected mechanism: traversal and link
 rejection, archive filters/limits/modes, exclusive target creation, source and
 target identity fencing, publication cleanup receipts, and secret/lock policy
-remain TypeScript-owned. What changes is the syscall strength or availability:
+remain TypeScript-owned. Windows buffered replacement writes with an omitted
+`mutationSymlinks` policy retain the existing
+[final-link and parent-junction differences](writing.md#windows-link-modes)
+between native and legacy JavaScript paths; use explicit `"reject"` for uniform
+link rejection. Apart from that legacy compatibility exception, what changes
+is the syscall strength or availability:
 
 The table compares underlying mechanisms. On Node, public `Root.open()`,
 `Root.read()`, and `Root.openWritable()` use guarded Node file opens and report
@@ -328,6 +321,15 @@ infer native loading from timing.
 
 ## Loader security
 
+Native initialization runs in the async context captured when fs-safe's loader
+module is evaluated. Import fs-safe during application startup, outside request
+or lease scopes, so the addon's process-lifetime housekeeping cannot retain the
+first operation's `AsyncLocalStorage` stores. Importing still does not load the
+addon: only the first native operation pays the registration cost. Subsequent
+operations and their callbacks retain their own caller context. Dynamically
+importing fs-safe for the first time inside a request scope captures that import
+scope instead; this boundary does not clear an already active import context.
+
 Importing fs-safe never executes a child process. Linux libc selection uses
 the Node process report, then the ELF `PT_INTERP` field of `process.execPath`,
 then conventional musl library filenames. An installed compatibility loader

package/node_modules/@openclaw/fs-safe/docs/path.md

@@ -36,7 +36,7 @@ isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
 isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
 ```
 
-The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding. A target on a different UNC share or device namespace than `rootDir` is never inside it: hosts and shares compare with ASCII-only case folding, and namespace spellings whose share or device cannot be identified count as outside unless spelled exactly under `rootDir` (see the [security model](security-model.md)).
 It is a lexical comparison, not a filesystem-admission boundary: it does not
 reject Windows alternate data streams or index-allocation aliases. Use a
 filesystem operation such as `root()` when a caller-controlled path will be

package/node_modules/@openclaw/fs-safe/docs/permissions.md

@@ -85,8 +85,7 @@ Structured ACLs containing only canonical SIDs are classified directly from
 the current-user SID without requiring a separate account-name lookup.
 The advanced options retain `currentUserSid` as an explicit classification
 override and `principalTranslationFailed: true` as an immediate unverified
-result. The optional `principalSids` translation cache is still accepted but
-is no longer needed because the query returns SIDs directly.
+result. The query returns SIDs directly; no translation cache is needed.
 Injected executors must return the same structured success JSON as the built-in
 query: valid `ownerSid` and `currentUserSid` strings, an explicit boolean
 `remote`, and complete DACL facts (`complete`, `daclPresent`, and `aces`).

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -24,8 +24,7 @@ The handle resolver verifies exact descriptor and pathname identities, with one
 bounded retry for unknown Windows observations. It borrows the handle without
 reading, reopening, closing it, or changing its cursor.
 
-The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
-deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
+The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`.
 
 ## `path` and `advanced`
 

package/node_modules/@openclaw/fs-safe/docs/reading.md

@@ -99,14 +99,13 @@ try {
 type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
-  nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // override defaults.symlinks
 };
 ```
 
 `maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
 
-`nonBlockingRead` remains as a compatibility hint. Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
+Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
 
 ## `readAbsolute()` and `reader()`
 

package/node_modules/@openclaw/fs-safe/docs/root.md

@@ -25,7 +25,6 @@ type RootDefaults = {
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
   mode?: number;                   // requested file mode; per-call override available
-  nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
   mutationSymlinks?: "reject" | "follow-parents-within-root"; // opt-in mutation policy
@@ -66,39 +65,11 @@ fs.reader(options?)            // (path) => Promise<Buffer>; useful for loader A
 fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kind, size }>
 ```
 
-`walk()` is the incremental, root-bounded recursive scan. It supports entry and
-depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root" | "include"`. Include mode returns links as
-`{ relativePath, kind: "symlink", size }` without resolving or entering their
-targets, including dangling and outside-root links. `size` describes the link,
-not its target. With an entry budget, sorted walks prepare small metadata
-batches within the remaining budget; unbounded sorted walks reuse the full
-directory snapshot.
-The default `order: "sorted"` enumerates and sorts each directory's names;
-`order: "filesystem"` streams names in filesystem order for bounded work in
-wide directories. Budget exhaustion yields a `"truncated"` marker by
-default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
-Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
-`"skip-subtree"`, directly or through a Promise. `"skip"` omits the current
-entry but still descends into a directory; `"skip-subtree"` omits a directory
-and all of its descendants.
-Filters run serially outside metadata batches, with the options object as their
-`this` receiver. After an awaited filter resolves, the walk checks cancellation
-and revalidates the current listing directory and Root identities before using
-the decision. Captured entry metadata retains its snapshot semantics.
-
-Cancellation and iterator disposal wait for a pending filter to settle; they do
-not race the callback or close its directory while it is running. Callback
-throws and promise rejections reject the walk through normal cleanup.
-Directory reads remain fail-fast by default. With
-`onDirectoryError: "skip-and-report"`, the iterator instead yields
-`{ relativePath, kind: "directory-error", size: 0, error }` and continues with
-the remaining tree. That policy also covers identity-check failures after an
-awaited filter, while callback failures always reject.
-In include mode, a directory that becomes a symlink before descent is a
-`path-mismatch` directory error; it is never silently omitted or followed.
-See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
-with the standalone best-effort walkers.
+`walk()` is the root-bounded recursive iterator, with budgets, cancellation,
+and symlink/filter policies. Default `order: "sorted"` enumerates and sorts all
+names in each directory even with an entry budget; use `order: "filesystem"`
+for bounded memory in wide directories. See [Root-bounded walking](walk.md#root-bounded-async-iteration)
+for truncation, callback, and directory-error contracts.
 
 `open()` returns a Node `FileHandle` for streaming. Prefer `await using` for cleanup:
 
@@ -143,136 +114,22 @@ fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 ```
 
-`mkdir`, `ensureRoot`, `create`, and `createJson` accept `private: true`.
-Missing directories are created with private permissions, and an existing
-requested directory must already be private. Existing ancestors are not
-chmodded or assigned new ACLs. Private files use owner-only POSIX permissions
-or a protected Windows DACL granting access to the current user, System, and
-Administrators. On macOS, private directories and files must also have no ACL;
-creation rejects relevant inheritable parent ACLs, while noninheriting parent
-ACLs remain allowed. A native helper with `inspectDarwinAcl` is required. Native
-`off`, a missing helper, or an older helper without that capability rejects with
-`helper-unavailable` before creating parents or stages. See [creation](creation.md)
-for platform support, synchronous leaf creation, and failure handling.
+Mutation options control parent creation, modes, durability, and publication.
+`write`, `create`, `append`, `writeJson`, `createJson`, and `copyIn` inherit
+`durable` from Root defaults (normally `true`); `false` skips synchronization
+without changing publication or identity checks. See [write options](writing.md#write-options)
+for precedence and platform behavior, and [append](writing.md#write-verbs)
+for newline handling and creation modes.
 
-```ts
-await fs.mkdir("private-data", { private: true });
-await fs.create("private-data/credential", "synthetic credential", { private: true });
-```
-
-`write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
-
-For `append` and `openWritable`, `mode` only affects new-file creation: POSIX
-permissions remain subject to the process umask. These methods do not chmod
-existing files. Replacement and create-only writes apply their final mode
-through the retained descriptor; see [Writing](writing.md#write-options).
-
-Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
-complete content is staged before exclusive publication even in native-off mode;
-the fallback requires hardlinks. Omitted or `false` keeps the existing buffered
-publication behavior. Streamed creates always stage complete content. The flag
-does not change `durable` or promise stronger containment or crash durability.
-See [atomic creation and settlement](writing.md#atomic-buffered-creation).
-
-`create` also accepts `AsyncIterable<Uint8Array>` with `RootCreateStreamOptions`:
-the same path, authority, mode, and durability options, plus `maxBytes` and
-`signal`, without `encoding` or `renameIdentity`. It consumes one chunk at a
-time and publishes the completed file exclusively. The byte cap inherits an
-explicit `Root.defaults.maxBytes`; without either cap, consumption is unlimited.
-See [streamed creation](writing.md#streamed-creation) for cancellation,
-cleanup, and filesystem requirements.
-
-`append` accepts `prependNewlineIfNeeded: true` to separate text from existing
-content when neither side supplies a newline. String data uses its `encoding`
-for the newline check, including UTF-16LE; Buffer data uses a single LF byte.
-Empty strings and Buffers add no separator; an empty append still creates a
-missing file.
-
-These five methods and `copyIn` also accept `durable?: boolean`: the per-call value overrides
-`Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
-`undefined` per-call value preserves the root default. `durable: false` keeps
-the existing publication behavior, modes, and identity checks but skips file
-and parent-directory fsync calls. Use it only for reconstructible data: a crash
-may lose the write or leave the previous file. See [Writing](writing.md#write-options)
-for platform details.
-
-`create` and `createJson` additionally accept `durable: "file"` to require file
-synchronization, including propagating `EPERM`. Parent-directory synchronization
-retains its existing best-effort behavior. This option applies to buffered and
-streamed creation and does not select a publication strategy.
-
-`copyIn` accepts a `RootCopySource`: a trusted absolute source path or a file
-within another Root. The guarded form supplies `root` with only its `open` and
-`stat` read capabilities, plus `relativePath`:
+`mkdir`, `ensureRoot`, `create`, and `createJson` accept `private: true`; see
+[Creation](creation.md) for permission checks and native requirements.
+Buffered `create` and `createJson` support [atomic publication](writing.md#atomic-buffered-creation)
+and `durable: "file"`; `create` also supports [streamed input](writing.md#streamed-creation).
 
-```ts
-const source = await root("/srv/templates");
-const destination = await root("/srv/workspace");
-await destination.copyIn("config/settings.json", {
-  root: source,
-  relativePath: "config/settings.json",
-}, {
-  overwrite: false,
-  clone: "auto",
-  mode: 0o600,
-  signal: AbortSignal.timeout(30_000),
-});
-```
-
-The source Root applies its read policies, including confinement and symlink
-handling. `sourceHardlinks` overrides its hardlink policy only when supplied;
-otherwise the source Root default is retained. The admitted source
-descriptor stays open through copying and source-identity verification; copying
-does not consume its current file position. Both forms enforce `maxBytes` while
-reading, including when a file grows after admission, and use bounded buffers.
-Copies have independent file data; changing either file cannot change the other.
-Set `preserveSourceMode: true` to select the mode from the admitted source
-descriptor. An explicit numeric `mode`, including `Root.defaults.mode`, takes
-precedence. By default, copying retains the existing destination-mode rules.
-The operation verifies source identity, not a coherent snapshot of concurrent
-in-place edits. Keep the source unchanged when snapshot consistency is required.
-
-`overwrite` defaults to `true`, preserving the existing replacement behavior.
-With `overwrite: false`, an existing destination produces `already-exists` and
-is never altered. Copying prepares a private sibling file before publishing its
-completed contents. Native mode uses no-replace rename. The guarded JavaScript
-fallback links the completed stage and removes its temporary name in the same
-JavaScript turn; the filesystem must support hardlinks. Other processes can
-briefly observe both names. The source is never hardlinked to the destination.
-
-`clone` chooses the file-data transfer strategy through `CopyCloneMode`, shared
-with [`copyTree`](copy.md#api). File copies default to `"never"`; tree copies
-default to `"auto"`:
-
-| Value | Behavior |
-| --- | --- |
-| `never` | Copy regular file bytes using reads and writes, without explicit cloning or copy offload. |
-| `auto` | Try native file cloning, then copy offload or ordinary byte copying when cloning is unavailable. |
-| `always` | Require native cloning; fail when the binding or filesystem cannot provide it. |
-
-Native file cloning supports APFS and supported Linux filesystems. Windows
-currently uses byte copying for `never` and `auto`; `always` fails. Clone choice
-does not change modes, durability, root confinement, or source and publication
-identity checks. The shared strategy does not replace Root's guarded regular-file
-contract with `copyTree`'s caller-owned immutable-tree and metadata contract.
-
-An already aborted `signal` prevents I/O. Cancellation during copying waits for
-admitted reads and native work to settle, then cleans only the owned unpublished
-stage. The final authority check runs before publication. Once publication has
-occurred, later cancellation or verification failure preserves the destination.
-The synchronous optional `onDestinationPublished` callback receives a frozen
-`RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
-publication, before later checks can fail. Callback errors also preserve the
-published file. Promise, thenable, and synchronous or asynchronous generator
-results reject with `TypeError`; returned generators are never advanced. Other
-synchronous return values are ignored. This receipt records an outcome; it does
-not authorize removing a file that another actor may have edited. Application recovery and cooperative
-locking remain caller-owned.
-
-Existing `copyIn` callers must account for completed destinations retained after
-a post-publication source-verification failure, even without the new options.
-Recovery must inspect current destination state rather than assume a rejected
-copy left no file.
+`copyIn` accepts a trusted absolute path or another Root as its source, with
+byte limits, cloning, cancellation, and publication receipts. See the complete
+[copy contract](writing.md#write-verbs); a rejected copy
+can still leave a completed destination after publication.
 
 Root operations that choose a new destination reject a leading Windows
 drive-relative spelling such as `C:name` on every platform. This applies to
@@ -294,17 +151,11 @@ does not otherwise reject them.
 
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Before truncation or handle return, descriptor and pathname identities are compared with lossless bigint metadata; persistently unknown Windows identities fail closed. The returned `stat` remains an ordinary numeric Node `Stats` object. Use it for streaming output. Prefer `await using` for cleanup.
 
-`remove` leaves non-empty directories unchanged unless `recursive: true` is
-provided. Recursive removal defaults to streaming entries in filesystem order;
-`order: "sorted"` processes each directory's children lexicographically. The
-`maxEntries` (100,000 by default) and `maxDepth` (64 by default) budgets accept
-explicit `Infinity` when the caller needs unlimited traversal. It never
-follows discovered symlinks; an explicit `mutationSymlinks` policy rejects them,
-while the omitted policy unlinks them. `force: true` ignores missing targets,
-and `signal` stops further work after admitted I/O and resource cleanup settle.
-Removal is not transactional: a budget, cancellation, policy, or identity
-failure can leave a partially removed tree. See [removal](writing.md)
-for the full counting and failure contract.
+`remove` leaves non-empty directories unchanged unless `recursive: true`.
+Recursive removal defaults to filesystem order, `maxEntries: 100_000`, and
+`maxDepth: 64`. It is incremental: budget, cancellation, policy, or identity
+failures can leave a partially removed tree. See [removal](writing.md#write-verbs)
+for ordering, symlink, and failure semantics.
 
 ### Live mutation authority
 
@@ -540,17 +391,8 @@ const b = await load("/srv/workspace/state.bin"); // absolute, but inside the ro
 
 ### "Touch only if missing" seeding
 
-```ts
-try {
-  await fs.create("config/seed.json", initialJson);
-} catch (err) {
-  if (err instanceof FsSafeError && err.code === "already-exists") {
-    // existing config wins
-  } else {
-    throw err;
-  }
-}
-```
+Use `create()` and handle `already-exists` so existing configuration wins;
+see the [seeding example](writing.md#write-verbs).
 
 ### Replace + verify
 

package/node_modules/@openclaw/fs-safe/docs/secret-file.md

@@ -314,5 +314,5 @@ await withTimeout(
 
 - [JSON files](json.md) — `writeJson` accepts `mode: 0o600` for non-secret JSON state.
 - [Atomic writes](atomic.md) — the lower-level `replaceFileAtomic` used by these helpers.
-- [Private file-store mode](private-file-store.md) — root-bounded JSON+text stores using secret-file write policy.
+- [Private file-store mode](file-store.md#private-mode) — root-bounded JSON+text stores using secret-file write policy.
 - [Migrating to 0.5](migrating-to-0.5.md) — strict/try reads and create-only adoption checklist.