docs: modernize remaining legacy CLI-option references in guides

Convert the narrative guides to current config-key vocabulary, completing
the pass started for the thread/throttle references:

  - config.md: scan-mode prose now points at the [scan.subvol] and
    [scan.extent.*] sections; --workaround-btrfs-send ->
    scan.subvol.workaround-btrfs-send (subvol and extent cases);
    --verbose -> log.level.
  - how-it-works.md: --loadavg-target -> thread.loadavg-target.
  - btrfs-kernel.md: --workaround-btrfs-send ->
    scan.subvol.workaround-btrfs-send.
  - running.md / wrong.md: the "load management" / "load throttling"
    feature pointers now link to the config.md "Threads and load
    management" guide section instead of options.md.

Links target config-file.md reference sections (and the config.md guide
section), matching the established guide-vs-reference split.  Anchors use
GitHub heading slugs, consistent with the existing intra-doc links;
cmark-gfm (the local doc build) emits no heading ids, so GitHub is the
canonical anchor target.

The deliberate CLI references stay on options.md: the --show-config debug
option, the index.md table-of-contents entry, and running.md's pointer to
options available without a configuration file.

Assisted-by: Claude-Code:claude-opus-4-8

diff --git a/docs/btrfs-kernel.md b/docs/btrfs-kernel.md
index e7a5c228ac175305b79344774dcc2cc24e9d6824..b988283b669745afe8f20c42b9f85e490a77c5b7 100644 (file)
--- a/docs/btrfs-kernel.md
+++ b/docs/btrfs-kernel.md
@@ -139,8 +139,9 @@ Workarounds for known kernel bugs
   false positives now) and clear all previously saved toxic extent bits.
 
 * **dedupe breaks `btrfs send` in old kernels**.  The bees option
-  `--workaround-btrfs-send` prevents any modification of read-only subvols
-  in order to avoid breaking `btrfs send` on kernels before 5.2.
+  [`scan.subvol.workaround-btrfs-send`](config-file.md#scansubvol-section)
+  prevents any modification of read-only subvols in order to avoid breaking
+  `btrfs send` on kernels before 5.2.
 
   This workaround is no longer necessary to avoid kernel crashes and
   send performance failure on kernel 5.4.4 and later.  bees will pause

diff --git a/docs/config.md b/docs/config.md
index 80e25db8be6452c40b42f1bd3865c69aad36ef82..29b90afebd4da6cd1f4f2030515a812052de4d81 100644 (file)
--- a/docs/config.md
+++ b/docs/config.md
@@ -97,14 +97,17 @@ every time a new client machine's data is added to the server.
 Scanning modes
 --------------
 
-The `--scan-mode` option affects how bees iterates over the filesystem,
-schedules extents for scanning, and tracks progress.
+The scan mode affects how bees iterates over the filesystem, schedules
+extents for scanning, and tracks progress.  It is selected by the
+[`[scan.subvol]`](config-file.md#scansubvol-section) and
+[`[scan.extent.*]`](config-file.md#scanextent-sections) configuration
+sections.
 
 There are now two kinds of scan mode:  the legacy **subvol** scan modes,
 and the new **extent** scan mode.
 
-Scan mode can be changed by restarting bees with a different scan mode
-option.
+Scan mode can be changed by restarting bees with a different scan
+configuration.
 
 Extent scan mode:
 
@@ -148,10 +151,11 @@ If a filesystem has only one subvolume with data in it, then all of
 the subvol scan modes are equivalent.  In this case, there is only one
 subvolume to scan, so every possible ordering of subvols is the same.
 
-The `--workaround-btrfs-send` option pauses scanning subvols that are
-read-only.  If the subvol is made read-write (e.g. with `btrfs prop set
-$subvol ro false`), or if the `--workaround-btrfs-send` option is removed,
-then the scan of that subvol is unpaused and dedupe proceeds normally.
+The [`scan.subvol.workaround-btrfs-send`](config-file.md#scansubvol-section)
+option pauses scanning subvols that are read-only.  If the subvol is made
+read-write (e.g. with `btrfs prop set $subvol ro false`), or if
+`scan.subvol.workaround-btrfs-send` is disabled, then the scan of that subvol
+is unpaused and dedupe proceeds normally.
 Space will only be recovered when the last read-only subvol is deleted.
 
 Subvol scan modes cannot efficiently or accurately calculate an ETA for
@@ -253,8 +257,8 @@ first run after upgrading from an older bees version, checkpoint data from
 the old `beescrawl.dat` format is automatically migrated to
 `beespoint.ini`.
 
-The `--workaround-btrfs-send` option behaves differently in extent
-scan modes:  In extent scan mode, dedupe proceeds on all subvols that are
+The [`scan.subvol.workaround-btrfs-send`](config-file.md#scansubvol-section)
+option behaves differently in extent scan modes:  In extent scan mode, dedupe proceeds on all subvols that are
 read-write, but all subvols that are read-only are excluded from dedupe.
 Space will only be recovered when the last read-only subvol is deleted.
 
@@ -336,4 +340,4 @@ bees supports a number of options for reducing system load:
 Log verbosity
 -------------
 
-bees can be made less chatty with the [`--verbose` option](options.md).
+bees can be made less chatty with the [`log.level` option](config-file.md#log-section).

diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index f3d01e22778bd9c24ff7b1809c4b293fa2951fef..30e9313d795e453574e05ef6d0a66f0499b91cb1 100644 (file)
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -95,7 +95,7 @@ the current btrfs transaction ID over time so that it polls less often
 on quiescent filesystems and more often on busy filesystems.
 
 Scanning and deduplication work is performed by worker threads.  If the
-[`--loadavg-target` option](options.md) is used, bees adjusts the number
+[`thread.loadavg-target` option](config-file.md#thread-section) is used, bees adjusts the number
 of worker threads up or down as required to have a user-specified load
 impact on the system.  The maximum and minimum number of threads is
 configurable.  If the system load is too high then bees will stop until

diff --git a/docs/running.md b/docs/running.md
index 2d466feb89ab3e80afccfbfb7e09c70242fae75e..d4bb6ded4e9c77523e24b9193d0e92a664707ccc 100644 (file)
--- a/docs/running.md
+++ b/docs/running.md
@@ -86,7 +86,7 @@ in the shell script that launches `bees`:
         schedtool -D -n20 $$
         ionice -c3 -p $$
 
-You can also use the [load management options](options.md) to further
+You can also use the [load management settings](config.md#threads-and-load-management) to further
 control the impact of bees on the rest of the system.
 
 Let the bees fly:

diff --git a/docs/wrong.md b/docs/wrong.md
index f5079dc842ca88021769b8bb5c7db31e42346c91..f986b1e6af3ee311c3966e541994f3bdd5df211e 100644 (file)
--- a/docs/wrong.md
+++ b/docs/wrong.md
@@ -7,7 +7,7 @@ Hangs and excessive slowness
 ### Use load-throttling options
 
   If bees is just more aggressive than you would like, consider using
-  [load throttling options](options.md).  These are usually more effective
+  [load throttling settings](config.md#threads-and-load-management).  These are usually more effective
   than `ionice`, `schedtool`, and the `blkio` cgroup (though you can
   certainly use those too) because they limit work that bees queues up
   for later execution inside btrfs.