Reverify docs and skill against current merged truth

docs/architecture/system-overview.md

@@ -3,57 +3,57 @@
 <!-- verification:
   source_repo: ant-sdk
   source_ref: main
-  source_commit: 1cbfb3e92cb4309f29e92b5609837812027f0a67
-  verified_date: 2026-04-29
+  source_commit: d7652ec3da82dfbe2107778e5223dc413d95815b
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 97587c248ce6410edc1c6ee28846216ef82145eb
-  verified_date: 2026-04-29
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-node
   source_ref: main
   source_commit: 23aee15cae33a17257ba833b2b98ed8a7a12e684
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-protocol
   source_ref: main
-  source_commit: 87071931a982e8a90494353007a3f4e6ebb3de3c
-  verified_date: 2026-04-29
+  source_commit: 65651f3a3243af8299a3e8d63385cba846ef88a4
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-core
   source_ref: main
-  source_commit: ae3c607fec0882b80e37837143382e9c9687c316
-  verified_date: 2026-04-29
+  source_commit: a3fd6eaedb8a7d6a8e4bbeeeebe07426bb9f6bc6
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-transport
   source_ref: main
   source_commit: 9808c2782a5605a7cf728a4e2c756c4bf24eef40
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-pqc
   source_ref: main
   source_commit: 2ab931e2533f1df6aa446636fbcf6e95b5bf5a21
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: self_encryption
   source_ref: master
   source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 

docs/cli/command-reference.md

@@ -3,12 +3,12 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 97587c248ce6410edc1c6ee28846216ef82145eb
-  verified_date: 2026-04-29
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 
-Reference for the `ant` CLI command tree and its current flags. The command tree below mirrors the current `ant --help` output, and the option tables are verified against the current command help while the sections stay grouped by command family for easier scanning.
+Reference for the `ant` CLI command tree and its flags. The command tree below follows the direct-network CLI surface, and the option tables stay grouped by command family for easier scanning. Hidden or advanced flags are called out where they matter for troubleshooting.
 
 ## Command tree
 
@@ -30,7 +30,8 @@ ant
 │   └── balance
 ├── file
 │   ├── upload
-│   └── download
+│   ├── download
+│   └── cost
 ├── chunk
 │   ├── put
 │   └── get
@@ -52,10 +53,10 @@ The root command accepts the global flags used across data and node operations.
 | `--devnet-manifest <PATH>` | path | No | Path to a local devnet manifest JSON file |
 | `--allow-loopback` | boolean | No | Allow loopback connections for local devnet or local testing |
 | `--ipv4-only` | boolean | No | Disable dual-stack and force IPv4-only mode |
-| `--quote-timeout-secs <N>` | integer | No | Timeout for lightweight network operations such as DHT lookups |
-| `--store-timeout-secs <N>` | integer | No | Timeout for chunk store and retrieve operations |
-| `--quote-concurrency <N>` | integer | No | Maximum number of chunks quoted or downloaded concurrently |
-| `--store-concurrency <N>` | integer | No | Maximum number of chunks stored concurrently during uploads. `--chunk-concurrency` is accepted as an alias. |
+| `--quote-timeout-secs <N>` | integer | No | Hidden. Controls lightweight network-operation timeouts such as DHT lookups. |
+| `--store-timeout-secs <N>` | integer | No | Hidden. Controls chunk store and retrieve timeouts. |
+| `--quote-concurrency <N>` | integer | No | Hidden. Caps the quote channel only. It does not affect store or download concurrency. |
+| `--store-concurrency <N>` | integer | No | Hidden. Controls upload chunk concurrency. `--chunk-concurrency` is accepted as an alias. |
 | `-v, --verbose...` | count | No | Increase log verbosity: `-v`, `-vv`, or `-vvv` |
 | `--evm-network <NET>` | string | No | EVM network for payments: `arbitrum-one`, `arbitrum-sepolia`, or `local` |
 | `-h, --help` | boolean | No | Print help |
@@ -87,8 +88,9 @@ Uploads a file with self-encryption and EVM payment.
 | `--public` | boolean | No | Store the DataMap on-network so anyone with the address can download the file |
 | `--merkle` | boolean | No | Force Merkle batch payment |
 | `--no-merkle` | boolean | No | Force single per-chunk payments |
-| `--store-timeout <N>` | integer | No | Override the chunk store timeout for this upload |
-| `--store-concurrency <N>` | integer | No | Override upload chunk concurrency for this upload |
+| `--store-timeout <N>` | integer | No | Hidden. Overrides the chunk store timeout for this upload. |
+| `--store-concurrency <N>` | integer | No | Hidden. Overrides upload chunk concurrency for this upload. |
+| `--overwrite` | boolean | No | Replace any existing `<filename>.datamap` instead of writing a suffixed `<filename>-2.datamap`. |
 
 **Example:**
 
@@ -106,7 +108,7 @@ Downloads a public file by address or a private file using a local DataMap file.
 |------|------|----------|-------------|
 | `ADDRESS` | string | Conditionally | Public DataMap address. Required unless `--datamap` is provided. |
 | `--datamap <PATH>` | path | No | Local `.datamap` file for private download |
-| `-o, --output <PATH>` | path | Yes | Output file path |
+| `-o, --output <PATH>` | path | Conditionally | Required for address-based downloads. Optional for `--datamap` downloads that can infer the original filename. |
 
 **Example:**
 
@@ -116,6 +118,30 @@ ant file download 711c7e20006ff3e0ac6c1f3063286a0c1a3e4c409642e8c526173fa60bb707
 
 The output path is your local filename. In this example, the command downloads a public JPEG of Lucky the dog and saves it as `lucky.jpg`.
 
+Private datamap example:
+
+```bash
+ant file download --datamap photo.jpg.datamap
+```
+
+### `ant file cost <PATH>`
+
+Estimates the upload cost for a file without uploading it.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `PATH` | path | Yes | File to estimate |
+| `--merkle` | boolean | No | Force Merkle batch payment mode for the estimate |
+| `--no-merkle` | boolean | No | Force single payment mode for the estimate |
+
+**Example:**
+
+```bash
+ant file cost photo.jpg --merkle
+```
+
 ## Chunk commands
 
 ### `ant chunk put [FILE]`

docs/cli/use-the-cli.md

@@ -3,8 +3,8 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 0b104d1e8e5a8dab08a24eeb8c81b25702548c96
-  verified_date: 2026-04-21
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 
@@ -59,6 +59,9 @@ If you build `ant` from source instead, provide your own bootstrap config or pas
 
 ```bash
 ant --help
+
+# or, if you built from source and have not installed it on PATH:
+./target/release/ant --help
 ```
 
 For the `ant` CLI, root flags such as `--bootstrap`, `--devnet-manifest`, `--allow-loopback`, and `--evm-network` come before the subcommand.

docs/core-concepts/data-types.md

@@ -3,22 +3,22 @@
 <!-- verification:
   source_repo: ant-sdk
   source_ref: main
-  source_commit: 1cbfb3e92cb4309f29e92b5609837812027f0a67
-  verified_date: 2026-04-29
+  source_commit: d7652ec3da82dfbe2107778e5223dc413d95815b
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 97587c248ce6410edc1c6ee28846216ef82145eb
-  verified_date: 2026-04-29
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: self_encryption
   source_ref: master
   source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 

docs/core-concepts/keys-addresses-and-datamaps.md

@@ -3,22 +3,22 @@
 <!-- verification:
   source_repo: ant-sdk
   source_ref: main
-  source_commit: bf541ccd4ae1fd3e174fb7b5bb21deef38d999ce
-  verified_date: 2026-04-21
+  source_commit: d7652ec3da82dfbe2107778e5223dc413d95815b
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 0b104d1e8e5a8dab08a24eeb8c81b25702548c96
-  verified_date: 2026-04-21
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: self_encryption
   source_ref: master
   source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0
-  verified_date: 2026-04-21
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 

docs/core-concepts/overview.md

@@ -3,29 +3,29 @@
 <!-- verification:
   source_repo: ant-sdk
   source_ref: main
-  source_commit: bf541ccd4ae1fd3e174fb7b5bb21deef38d999ce
-  verified_date: 2026-04-21
+  source_commit: d7652ec3da82dfbe2107778e5223dc413d95815b
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 0b104d1e8e5a8dab08a24eeb8c81b25702548c96
-  verified_date: 2026-04-21
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: self_encryption
   source_ref: master
   source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0
-  verified_date: 2026-04-21
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-pqc
   source_ref: main
-  source_commit: 1619cb2231db942cd65ab954ca0e0304dd6bc220
-  verified_date: 2026-04-21
+  source_commit: 2ab931e2533f1df6aa446636fbcf6e95b5bf5a21
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 

docs/core-concepts/payment-model.md

@@ -3,36 +3,36 @@
 <!-- verification:
   source_repo: ant-sdk
   source_ref: main
-  source_commit: 1cbfb3e92cb4309f29e92b5609837812027f0a67
-  verified_date: 2026-04-29
+  source_commit: d7652ec3da82dfbe2107778e5223dc413d95815b
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 97587c248ce6410edc1c6ee28846216ef82145eb
-  verified_date: 2026-04-29
+  source_commit: 8b2c9c606a1223f105fed9aa2b56310b6a6763da
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-node
   source_ref: main
   source_commit: 23aee15cae33a17257ba833b2b98ed8a7a12e684
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: evmlib
   source_ref: main
   source_commit: 225acbb1af613193bcc8264b6ede4d7e4a7ac607
-  verified_date: 2026-04-29
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-protocol
   source_ref: main
-  source_commit: 87071931a982e8a90494353007a3f4e6ebb3de3c
-  verified_date: 2026-04-29
+  source_commit: 65651f3a3243af8299a3e8d63385cba846ef88a4
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 
@@ -76,7 +76,7 @@ The `antd` surface exposes cost estimation explicitly:
 - `POST /v1/data/cost`
 - `POST /v1/files/cost`
 
-Those endpoints return the estimated upload cost as a string amount in atto tokens.
+Those endpoints return a structured estimate with cost, file size, chunk count, estimated gas, and the payment mode that would be used.
 
 ### Payment modes
 
@@ -88,15 +88,15 @@ The supported payment modes are:
 | `merkle` | Force Merkle batch payment |
 | `single` | Force per-chunk payment |
 
-In `ant-core`, the current Merkle threshold is `64` chunks.
+In `ant-core`, the Merkle threshold is `64` chunks.
 
 Nodes verify the payment proof that arrives with each write. That includes signature checks, on-chain payment verification, and record-level validation before content is accepted into the chunk store.
 
-Node-side storage pricing currently follows `BASELINE + K × (n / D)^2`, where `n` is the number of close records the node is already storing and `D` is a fixed divisor. That gives lightly loaded nodes a non-zero spam-barrier price and pushes larger uploads toward less-loaded close groups as the network fills.
+Node-side storage pricing follows `BASELINE + K × (n / D)^2`, where `n` is the number of close records the node is already storing and `D` is a fixed divisor. That gives lightly loaded nodes a non-zero spam-barrier price and pushes larger uploads toward less-loaded close groups as the network fills.
 
 ### What happens on retrieval
 
-Downloads do not require a separate payment step. Payments are tied to storing data, chunks, files, directories, or node-management operations that require wallet context.
+Downloads do not require a separate payment step. Payments are tied to storage writes such as storing data, chunks, files, or directories.
 
 ## Practical example
 

docs/core-concepts/post-quantum-cryptography.md

@@ -3,22 +3,22 @@
 <!-- verification:
   source_repo: saorsa-pqc
   source_ref: main
-  source_commit: 1619cb2231db942cd65ab954ca0e0304dd6bc220
-  verified_date: 2026-04-21
+  source_commit: 2ab931e2533f1df6aa446636fbcf6e95b5bf5a21
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-transport
   source_ref: main
-  source_commit: c34424efba78546ca08a4bf69382a7fc04aa2789
-  verified_date: 2026-04-21
+  source_commit: 9808c2782a5605a7cf728a4e2c756c4bf24eef40
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-keygen
   source_ref: main
   source_commit: 3a2953f384a3b16391968de451b703843b98ed86
-  verified_date: 2026-04-21
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->
 

docs/core-concepts/self-encryption.md

@@ -4,7 +4,7 @@
   source_repo: self_encryption
   source_ref: master
   source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0
-  verified_date: 2026-04-02
+  verified_date: 2026-04-30
   verification_mode: current-merged-truth
 -->