docs: sync command-reference + managing-dragonfly to Dragonfly v1.39.0

[vyavdoshenko]

Summary

Syncs the command-reference and managing-dragonfly docs from Dragonfly v1.38.0 to v1.39.0 using the in-repo docsync tooling (flags_sync + docs_sync), then takes the story one step further: every machine-generated change was replayed against a live v1.39.0 Docker container and the C++ source, and corrected wherever the tool was wrong. A brand-new page documents the Dragonfly-specific FT.HYBRID command, and the sync harness itself was patched so quoted example values are no longer mangled — the root cause of the example corruption repaired here.

Every changed file is traceable to a bullet below.

Reviewer focus — start here:

1. The new FT.HYBRID page (docs/command-reference/search/ft.hybrid.md, 245 lines) — a Dragonfly-specific command, so there is no upstream reference to diff against. Please scrutinize the syntax, the COMBINE RRF/LINEAR semantics, the KNN/RANGE mutual exclusion, and the RANGE cannot-combine-with-FILTER constraint.
2. The corrections below, where the synced output was factually wrong and was overridden by hand.

New documentation

• search/ft.hybrid.md (new, 245 lines) — full reference for Dragonfly's hybrid full-text (SEARCH) + vector (VSIM / KNN / RANGE) search: COMBINE RRF (default) and COMBINE LINEAR rank fusion, YIELD_SCORE_AS (settable independently for the text, vector, and combined scores), LOAD, LIMIT, PARAMS, the four-field map reply, and three worked examples (default RRF, per-pipeline score yielding, weighted linear) whose output was captured from a live v1.39.0 container.
• compatibility.md — adds an FT.HYBRID row to the Search family, marked Fully supported.
• Cross-references to FT.HYBRID added from ft.search.md, ft.aggregate.md.

Verified & corrected sync output

• search/ft.aggregate.md — documents ADDSCORES (adds __score, defaults to the BM25STD scorer) and SCORER (BM25STD / TFIDF / TFIDF.DOCNORM); corrects WITHSCORES to note it is accepted for FT.SEARCH compatibility but silently ignored by FT.AGGREGATE (use ADDSCORES to expose __score).
• search/ft.search.md — documents WITHSCORES (default scorer BM25STD) and SCORER scorer_name (BM25STD / TFIDF / TFIDF.DOCNORM), the score's position in the reply, and the query operators ~term (optional), w'glob*' (glob on TEXT/TAG), and "phrase"~N (slop); plus two scored-search examples.
• search/ft.create.md — clarifies that JSON field identifiers may be a JSONPath expression ($.title) or a bare field name (title), with a new bare-name example.
• server-management/bgsave.md — corrects the syntax to BGSAVE [SCHEDULE] [RDB|DF] ..., documents SCHEDULE as a no-op (concurrent saves still rejected, not queued); corrects the Return to a plain OK (not the Redis-style Background saving started / Background saving scheduled strings); fixes an "Equvalent" typo.
• server-management/client-list.md — documents the CLIENT LIST [TYPE <type>] [ID <client-id> ...] filters and notes that TYPE and ID are mutually exclusive (one filter per call).
• scripting.md — documents the Lua sandbox restrictions and corrects the rawset / setmetatable / getmetatable description: the protected versions guard the global environment (_G); they do not prevent a script from reassigning/shadowing those names. Also notes load() is text-mode-only and dragonfly.randstr() validates its size argument.
• tiering.md — notes data tiering now covers list nodes and mutable hash commands, experimentally, and replaces the retired tiered_storage_write_depth flag with tiered_max_pending_stash_bytes.
• cluster-mode.md — updates the debug tip from --logtostdout to --logtostderr (the former was removed in v1.39.0).
• monitoring.md — adds a Replication Metrics section noting the /metrics endpoint also exposes replication role, connected replicas, and lag.

Fixed examples

• hashes/hsetex.md — rewrites the example blocks the sync harness had corrupted into self-contained, verified v1.39.0 sequences: unquoted argument values, correct TTLs (FIELDTTL now 30 / 60), and the new-fields-added return semantics for NX and KEEPTTL.
• generic/restore.md — replaces the corrupted RESTORE example with a real SET → DUMP → DEL → RESTORE → GET round-trip in a plain fence, plus a note that the payload is tied to the server's RDB version; keeps the verified "listpack/intset payloads are deeply validated on restore" prose.

Flag reference updates

flags.md re-synced via flags_sync to v1.39.0:

• Added: --container_iteration_yield_interval_usec, --tiered_max_pending_stash_bytes, --listpack_max_bytes, --listpack_max_field_len, --s3_use_helio_client, --serialization_tagged_chunks, --cluster_coordinator_connect_timeout_ms, --cluster_coordinator_response_timeout_ms, --logbuflevel, --logbufsecs, --enable_memcache_io_loop_v2, --enable_resp_io_loop_v2, --journal_omit_redundant_writes, --use_oah_set.
• Removed (retired): --tiered_storage_write_depth, --logtostdout, --experimental_io_loop_v2.
• Corrected defaults: --max_log_size 1800 → 200, --rdb_sbf_chunked false → true.

Tooling

• tools/docsync/docs_sync.py — fixes the example tokenizer with a new tokenize_invocation() helper that uses shlex.split so quoted values are unquoted the way redis-cli would (e.g. "alice" → alice instead of being stored with literal quotes), with a fallback to a plain whitespace split on invalid shell syntax (unbalanced quotes). Wired into both verify_invocations() and verify_and_substitute_examples(). This is the root-cause fix for the kind of example corruption repaired in hsetex.md and restore.md.

Verification

• yarn build passes.
• Command examples (FT.HYBRID, HSETEX, RESTORE, scoring) were run against a live Dragonfly v1.39.0 Docker container and the captured output is what appears in the docs.
• Behavioral corrections (WITHSCORES silently ignored by FT.AGGREGATE, BGSAVE returns plain OK, the Lua sandbox guards _G, CLIENT LIST TYPE/ID mutually exclusive, hash tiering experimental, the FT.HYBRID reply shape) were checked against the v1.39.0 C++ source.

Notes for reviewers

• The bgsave.md Return correction (Background saving started → plain OK) is a pre-existing fix — it is not produced by the v1.38 → v1.39 sync.
• The FT.HYBRID Fully supported entry in compatibility.md is a curated judgement, not a tool-generated value.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	Jun 10, 2026 3:57pm

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (1)

1. ft.hybrid.md links to redis.io 📘 Rule violation ⚙ Maintainability

Description

The new FT.HYBRID command reference page links to redis.io for query syntax and related topics.
This violates the requirement to avoid redis.io links in command/protocol reference documentation
and use Valkey-approved sources instead.

Code

docs/command-reference/search/ft.hybrid.md[R49-52]

+<summary><code>SEARCH query</code></summary>
+
+is the full-text query, using the same [query syntax](https://redis.io/docs/latest/develop/interact/search-and-query/query/) as `FT.SEARCH`. If the query is more than a single word, put it in quotes.
+</details>

Evidence

PR Compliance ID 5 prohibits redis.io links in command/protocol reference documentation. The added
FT.HYBRID page includes two new redis.io URLs: one for query syntax and one in the related
topics section.

AGENTS.md: Command/Protocol Reference Links Must Use Valkey Documentation (No redis.io Links)
docs/command-reference/search/ft.hybrid.md[49-52]
docs/command-reference/search/ft.hybrid.md[243-245]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `FT.HYBRID` command reference page includes external links to `redis.io`, which is disallowed for command/protocol reference documentation in this repo.

## Issue Context
This affects:
- The `SEARCH query` section linking to `https://redis.io/.../search-and-query/query/`
- The `Related topics` section linking to `https://redis.io/.../operate/oss_and_stack/.../search/`

Update these references to Valkey-approved documentation URLs (e.g., `valkey.io`) or to appropriate in-repo documentation pages.

## Fix Focus Areas
- docs/command-reference/search/ft.hybrid.md[49-52]
- docs/command-reference/search/ft.hybrid.md[243-245]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Bash examples not verified 🐞 Bug ☼ Reliability

Description

tools/docsync/docs_sync.py only replays/verifies dragonfly> invocations found inside ```shell
fenced blocks, but this PR adds/updates dragonfly> examples in ``bash fences (e.g., FT.HYBRID`,
FT.SEARCH), so docsync will skip them and their outputs can silently become stale.

Code

docs/command-reference/search/ft.hybrid.md[R137-148]

+``` bash
+dragonfly> FT.CREATE idx ON HASH PREFIX 1 doc: SCHEMA title TEXT vec VECTOR FLAT 6 TYPE FLOAT32 DIM 2 DISTANCE_METRIC L2
+OK
+```
+
+<details open>
+<summary><b>Basic hybrid search (default RRF)</b></summary>
+
+Combine the text query `running` with a nearest-neighbor vector search and fuse the rankings with the default Reciprocal Rank Fusion. `$q` is a binary FLOAT32 little-endian vector passed via `PARAMS` (here the 2-dimensional vector `[1.0, 0.0]`).
+
+``` bash
+dragonfly> FT.HYBRID idx SEARCH "running" VSIM @vec $q KNN 3 PARAMS 2 q "\x00\x00\x80?\x00\x00\x00\x00"

Evidence

The verifier’s regex only matches blocks fenced as shell, while the new/updated docs place
dragonfly> invocations inside bash fences; therefore those examples are skipped by
verify_and_substitute_examples/extract_redis_invocations and won’t be replayed/refreshed by
docsync.

tools/docsync/docs_sync.py[595-611]
docs/command-reference/search/ft.hybrid.md[137-148]
docs/command-reference/search/ft.search.md[225-257]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docsync harness only detects fenced blocks that start with ````shell`, so any `dragonfly>` examples inside ````bash` (or other) fences are never executed in Docker and their outputs are never refreshed.

### Issue Context
This PR adds/updates `dragonfly>` examples under ` ``` bash ` fences (not ` ```shell `), which means future runs of `docs_sync.py` will not verify them.

### Fix Focus Areas
- tools/docsync/docs_sync.py[595-611]
- docs/command-reference/search/ft.hybrid.md[137-148]
- docs/command-reference/search/ft.search.md[225-257]

### What to change
- Update `SHELL_BLOCK_RE` to match both `shell` and `bash` fences (and consider `sh` if used elsewhere), e.g. `^```(?:shell|bash)[ \t]*\n...`.
- Update the docstring in `extract_redis_invocations` (and any related comments) to reflect the expanded fence support.
- (Alternative) If you prefer keeping the verifier strict, change the affected docs’ code fences from `bash` to `shell` wherever they contain `dragonfly>` lines intended for verification.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---