v0.2.2 fixes: split only text sources, report a mode change once, don't block on open

doc/access.md

@@ -24,8 +24,9 @@ provided by the caller. A present nil value clears its destination.
 Conversions support signed/unsigned numbers, floats, booleans, strings, slices,
 arrays, string-keyed maps, structs and pointers. Durations, time.Time, net.IP,
 net.IPNet and url.URL are atomic configuration values, including pointer forms.
-They accept their native types or documented text representations. Comma-separated
-strings can populate typed numeric slices as well as string slices.
+They accept their native types or documented text representations. Environment and
+command-line text splits at commas into typed numeric slices as well as string
+slices; any other string is one element.
 
 No truncating integer conversions or integer-to-float precision loss is allowed.
 Float narrowing may round within range. NaN/Inf and unsupported object graphs are

doc/cli.md

@@ -1,14 +1,18 @@
 # Command-line arguments
 
 `LoadCLI` accepts `--server.port=9000`, `--server.port 9000`, and bare boolean flags
-such as `--debug`. Arguments after `--` are positional and are not parsed. Other
-positional arguments are ignored. There is no short-flag parser; use Go's flag package
-when that interface is needed. Paths must obey registration's dot-separated key syntax.
+such as `--debug`. A bare flag is the boolean true, so on a path that is not
+boolean (`--dir --debug`) it fails with "--dir needs a value". Arguments after `--`
+are positional and are not parsed. There is no short-flag parser; use Go's flag
+package when that interface is needed. Paths must obey registration's dot-separated
+key syntax.
 
-Values remain strings and are validated against registered types before publication.
-Each successful call replaces the complete CLI source, including an empty argument
-list. Omitted flags lose their previous overrides. Unknown paths are recorded in
-`UnknownCLIKeys` in sorted order and are not registered. The returned list is a copy.
+Values remain strings and are validated against registered types before publication;
+a slice or array path splits them at commas. Each successful call replaces the
+complete CLI source, including an empty argument list. Omitted flags lose their
+previous overrides. Unknown paths are recorded in `UnknownCLIKeys` in sorted order,
+followed by the arguments before `--` that are no `--` flag (a positional word, a
+`-q`), and are not registered. The returned list is a copy.
 
 `GenerateFlags` creates a flag.FlagSet from defaults. `BindFlags` atomically replaces
 the CLI source with explicitly visited flags, rejects unregistered flags, and uses

doc/env.md

@@ -8,8 +8,10 @@ Options are copied. Custom transforms run outside Config locks and may inspect C
 Environment values are stored as strings and validated against registered types
 before any part of the replacement is published. Numbers use decimal text; durations
 use Go duration syntax; timestamps use RFC3339Nano-compatible text. Slices and arrays
-use comma-separated elements without an escaping convention. Empty text gives an
-empty slice. Values larger than MaxValueSize are rejected.
+use comma-separated elements without an escaping convention. An empty variable is
+unset, so a template may leave one blank. Two paths whose names map to one set
+variable (`a.b_c` and `a_b.c` both to `APP_A_B_C`) fail the load. Values larger than
+MaxValueSize are rejected.
 
 `RegisterWithEnv` and a struct field's `env` tag load an explicitly named variable
 during registration. Later `LoadEnv` calls use the configured transform/whitelist,

doc/file.md

@@ -9,11 +9,13 @@ removes that source override, exposing the next source or registered default.
 
 Loads parse and validate before publication. Syntax errors, incompatible values,
 overflow and read failures leave prior values, comments and the loaded path intact.
-Readers must be regular files. Security options check ownership of the opened file
-on Unix and enforce size limits both before and during reading. Ownership checks
-fail explicitly on unsupported platforms. PreventPathTraversal rejects relative
-paths escaping through `..`; it is not a symlink sandbox. Absolute paths remain
-allowed. A zero MaxFileSize means no configured byte limit.
+Readers must be regular files, checked on the opened descriptor. The open does not
+block, so a FIFO swapped in after the path's check fails at once, and a file whose
+reads would block fails its read. Security options check ownership of the opened
+file on Unix and enforce size limits both before and during reading. Ownership
+checks fail explicitly on unsupported platforms. PreventPathTraversal checks the
+path text only: it rejects relative paths escaping through `..`, not symlinks or
+absolute paths. A zero MaxFileSize means no configured byte limit.
 
 `Save(path)` writes effective values; `SaveSource(path, source)` writes one source.
 Default selects registered defaults. Both use a temporary file in the destination

doc/reconfiguration.md

@@ -21,9 +21,11 @@ timeouts for the same observation emit only one notification until recovery.
 
 Events are changed registered paths, or `file_deleted`, `permissions_changed`,
 `reload_timeout`, `reload_error:<detail>`, and `precedence:<path>`. A path event means
-the effective value changed; a file value masked by CLI need not notify. Group/world
-permission changes are blocked when VerifyPermissions is enabled; correcting the
-permissions allows loading again. Default options enable that check.
+the effective value changed; a file value masked by CLI need not notify. With
+VerifyPermissions (on by default), a change of the group/world permission bits is
+reported once as `permissions_changed` and that version is not applied; the next
+change applies under the new mode. While a watcher runs, a further Watch or
+WatchWithOptions call subscribes to it and its options are ignored.
 
 Notifications are buffered (10 entries) and best effort; a slow subscriber may miss
 events and should read the latest full state. MaxWatchers bounds retained channels.