Adaptive sync doc (#256)

* fix: add missing sdk/next/build/ directory

The sdk/next/ directory was created as a copy of sdk/v0.53/ but the
build/ subdirectory was not included, causing broken internal links
in the learn/ pages. Copy build/ from v0.53, rewrite internal links
to /sdk/next/, add noindex: true to all pages, and update .gitignore
to allow sdk/next/build/.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update docs.json

* Create adaptive-sync.mdx

* Update cometbft/next/docs/experimental/adaptive-sync.mdx

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

* fix

* improve

* move AdaptiveSync to BlockSync page

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Dmitry S <11892559+swift1337@users.noreply.github.com>

Author: 4 people

cometbft/next/docs/core/block-sync.mdx

@@ -45,5 +45,78 @@ other than v0 have been deprecated in favor of the simplest and most well-unders
 version = "v0"
 ```
 
-If we're lagging sufficiently, we should go back to block syncing, but
-this is an [open issue](https://github.com/tendermint/tendermint/issues/129).
+## AdaptiveSync
+
+<Warning>
+  This is an experimental feature.
+  It has been tested under a range of network conditions and perturbations, but you should validate it
+  for your specific workload before enabling it on a production mainnet chain.
+</Warning>
+
+AdaptiveSync allows a node to run blocksync and consensus at the same time.
+
+In the default flow, a node starts in blocksync, catches up, then switches to consensus.
+Under sustained load (for example, busy RPC nodes), a node can remain behind and struggle to catch up.
+With short block times, this can hurt network liveness.
+
+With `adaptive_sync` enabled, consensus still works normally, but it can also ingest already available 
+blocks from blocksync. This acts as a fallback path when a node is behind, allowing it to recover 
+more quickly during traffic spikes and continue progressing with the network.
+
+AdaptiveSync does not change consensus safety or finality rules. It changes catch-up behavior, not block validity rules.
+
+### Scope and compatibility
+
+- AdaptiveSync is intended for nodes that can temporarily lag, especially RPC-heavy or high-throughput deployments.
+- It is experimental; enable it gradually and validate in your own network conditions before broad rollout.
+- If you run mixed node roles (validators, sentries, RPC nodes), test each role separately.
+
+### How it works
+
+1. The node continues running consensus as usual.
+2. If the node is behind, blocks obtained by blocksync can be handed to consensus ingestion.
+3. If a candidate block is already included by consensus, it is skipped.
+4. If not already included, it is ingested and applied through normal validation paths.
+5. The node converges faster during transient load spikes while preserving normal consensus behavior.
+
+### When to use it
+
+Enable `adaptive_sync` if your nodes can temporarily fall behind and need better recovery behavior:
+
+- **High-throughput or bursty traffic** where load spikes can delay vote processing.
+- **Short block times** where slow catch-up can impact liveness sooner.
+- **RPC-heavy nodes** that may lag during periods of high request volume.
+
+If your network is stable and nodes consistently keep up, the default mode may already be sufficient.
+
+**Notes**:
+
+- Running this fallback path may slightly increase CPU and I/O during catch-up windows
+- Constant blocksync message processing may increase network traffic.
+- Gains are most visible during temporary overload.
+
+### Configuration
+
+AdaptiveSync is disabled by default.
+To enable it, set `adaptive_sync = true` in the `[blocksync]` section of `config.toml`:
+
+```toml
+[blocksync]
+version = "v0"
+adaptive_sync = true
+```
+
+### Metrics
+
+```text
+# counter: blocksync block was already included by consensus --> skip
+cometbft_blocksync_already_included_blocks
+
+# counter: blocksync block was ingested by consensus --> ingest
+cometbft_blocksync_ingested_blocks
+
+# histogram: duration of ingesting a non-skipped block
+cometbft_blocksync_ingested_block_duration_bucket
+cometbft_blocksync_ingested_block_duration_count
+cometbft_blocksync_ingested_block_duration_sum
+```